FractalDataWorks.Services.Execution.Abstractions 0.4.0-preview.6

FractalDataWorks.Services.Execution.Abstractions

Overview

Foundational contracts and base types for process execution within the FractalDataWorks framework. This project defines abstractions that enable different types of processes (ETL, data migration, batch processing) to be executed, monitored, and managed through a unified process execution system.

Purpose

This abstractions library provides:

• Process Contracts - Core interfaces for process definition and execution
• State Management - Process state tracking using TypeCollections
• Result Models - Standardized result and metrics reporting
• Message System - Process execution messages and notifications
• Base Types - TypeOption base classes for process types and states

Key Components

Core Interfaces

IProcess

From IProcess.cs:13-55:

public interface IProcess
{
    /// <summary>
    /// Unique identifier for this process instance.
    /// </summary>
    string ProcessId { get; }

    /// <summary>
    /// Name of the process type (e.g., "ETL", "HealthCheck").
    /// </summary>
    string ProcessTypeName { get; }

    /// <summary>
    /// Current state of the process.
    /// </summary>
    IProcessState State { get; }

    /// <summary>
    /// Configuration for this process instance.
    /// </summary>
    object Configuration { get; }

    /// <summary>
    /// Execute an operation on this process.
    /// </summary>
    Task<IProcessResult> Execute(string operationName, CancellationToken cancellationToken = default);

    /// <summary>
    /// Check if this process supports the specified operation.
    /// </summary>
    bool SupportsOperation(string operationName);

    /// <summary>
    /// Get all operations supported by this process.
    /// </summary>
    string[] GetSupportedOperations();
}

IProcessResult

From IProcessResult.cs:10-71:

public interface IProcessResult
{
    string ProcessId { get; }
    string OperationName { get; }
    bool IsSuccess { get; }
    IProcessState FinalState { get; }
    object? Data { get; }
    string? ErrorMessage { get; }
    Exception? Exception { get; }
    IProcessMetrics Metrics { get; }
    IReadOnlyDictionary<string, object> Metadata { get; }
    DateTime StartedAt { get; }
    DateTime? CompletedAt { get; }
    TimeSpan? Duration { get; }
}

IProcessMetrics

From IProcessMetrics.cs:9-40:

public interface IProcessMetrics
{
    TimeSpan CpuTime { get; }
    long PeakMemoryBytes { get; }
    long ItemsProcessed { get; }
    int RetryAttempts { get; }
    IReadOnlyDictionary<string, long> Counters { get; }
    IReadOnlyDictionary<string, TimeSpan> Timings { get; }
}

Model Classes

ProcessResult

From ProcessResult.cs:13-130:

[ExcludeFromCodeCoverage]
public class ProcessResult : IProcessResult
{
    public string ProcessId { get; init; } = string.Empty;
    public string OperationName { get; init; } = string.Empty;
    public bool IsSuccess { get; init; }
    public required IProcessState FinalState { get; init; }
    public object? Data { get; init; }
    public string? ErrorMessage { get; init; }
    public Exception? Exception { get; init; }
    public IProcessMetrics Metrics { get; init; } = ProcessMetrics.Empty;
    public IReadOnlyDictionary<string, object> Metadata { get; init; } = new Dictionary<string, object>(StringComparer.Ordinal);
    public DateTime StartedAt { get; init; } = DateTime.UtcNow;
    public DateTime? CompletedAt { get; init; }
    public TimeSpan? Duration => CompletedAt?.Subtract(StartedAt);

    public static ProcessResult Success(
        string processId,
        string operationName,
        IProcessState finalState,
        object? data = null,
        IProcessMetrics? metrics = null)
    {
        return new ProcessResult
        {
            ProcessId = processId,
            OperationName = operationName,
            IsSuccess = true,
            FinalState = finalState,
            Data = data,
            Metrics = metrics ?? ProcessMetrics.Empty,
            CompletedAt = DateTime.UtcNow
        };
    }

    public static ProcessResult Failure(
        string processId,
        string operationName,
        IProcessState finalState,
        string errorMessage,
        Exception? exception = null)
    {
        return new ProcessResult
        {
            ProcessId = processId,
            OperationName = operationName,
            IsSuccess = false,
            FinalState = finalState,
            ErrorMessage = errorMessage,
            Exception = exception,
            CompletedAt = DateTime.UtcNow
        };
    }
}

ProcessMetrics

From ProcessMetrics.cs:11-61:

[ExcludeFromCodeCoverage]
public class ProcessMetrics : IProcessMetrics
{
    public TimeSpan CpuTime { get; init; } = TimeSpan.Zero;
    public long PeakMemoryBytes { get; init; }
    public long ItemsProcessed { get; init; }
    public int RetryAttempts { get; init; }
    public IReadOnlyDictionary<string, long> Counters { get; init; } = new Dictionary<string, long>(StringComparer.Ordinal);
    public IReadOnlyDictionary<string, TimeSpan> Timings { get; init; } = new Dictionary<string, TimeSpan>(StringComparer.Ordinal);

    public static ProcessMetrics Empty => new();
    public static ProcessMetrics WithItemCount(long itemsProcessed) => new() { ItemsProcessed = itemsProcessed };
    public static ProcessMetrics WithCounters(IDictionary<string, long> counters) => new() { Counters = new Dictionary<string, long>(counters, StringComparer.Ordinal) };
}

TypeCollection Base Classes

ProcessTypeBase

From ProcessTypeBase.cs:14-66:

public abstract class ProcessTypeBase : TypeOptionBase<int, IProcessType>, ITypeOption<int, ProcessTypeBase>, IProcessType
{
    protected ProcessTypeBase(int id, string name) : base(id, name)
    {
    }

    public abstract IProcess CreateProcess(string processId, object configuration, IServiceProvider serviceProvider);

    public abstract Task<IProcessResult> Execute(
        string operationName,
        string processId,
        IServiceProvider serviceProvider,
        CancellationToken cancellationToken = default);

    public abstract string[] GetSupportedOperations();

    public abstract Type GetConfigurationType();

    public abstract bool IsValidConfiguration(object configuration);
}

ProcessStateBase

From ProcessStateBase.cs:10-49:

public abstract class ProcessStateBase : TypeOptionBase<int, IProcessState>, ITypeOption<int, ProcessStateBase>, IProcessState
{
    protected ProcessStateBase(int id, string name, bool isTerminal, bool isError, bool isActive, bool isInitial = false)
        : base(id, name)
    {
        IsTerminal = isTerminal;
        IsError = isError;
        IsActive = isActive;
        IsInitial = isInitial;
    }

    public bool IsTerminal { get; }
    public bool IsError { get; }
    public bool IsInitial { get; }
    public bool IsActive { get; }
}

ProcessTypes and ProcessStates Collections

From ProcessTypes.cs:11-15:

[ExcludeFromCodeCoverage]
[TypeCollection(typeof(ProcessTypeBase), typeof(IProcessType), typeof(ProcessTypes))]
public abstract partial class ProcessTypes
{
}

From ProcessStates.cs:10-14:

[ExcludeFromCodeCoverage]
[TypeCollection(typeof(ProcessStateBase), typeof(IProcessState), typeof(ProcessStates))]
public partial class ProcessStates : TypeCollectionBase<ProcessStateBase, IProcessState>
{

}

Standard Process States

Created

From States/Created.cs:8-17:

[TypeOption(typeof(ProcessStates), "Created")]
public sealed class Created : ProcessStateBase
{
    public Created() : base(1, "Created", isTerminal: false, isError: false, isActive: false, isInitial: true)
    {
    }
}

Pending

From States/Pending.cs:8-24:

[TypeOption(typeof(ProcessStates), "Pending")]
public sealed class Pending : ProcessStateBase
{
    public Pending()
        : base(
            id: 6,
            name: "Pending",
            isTerminal: false,
            isError: false,
            isActive: false,
            isInitial: false)
    {
    }
}

Running

From States/Running.cs:8-17:

[TypeOption(typeof(ProcessStates), "Running")]
public sealed class Running : ProcessStateBase
{
    public Running() : base(2, "Running", isTerminal: false, isError: false, isActive: true, isInitial: false)
    {
    }
}

Completed

From States/Completed.cs:8-17:

[TypeOption(typeof(ProcessStates), "Completed")]
public sealed class Completed : ProcessStateBase
{
    public Completed() : base(3, "Completed", isTerminal: true, isError: false, isActive: false, isInitial: false)
    {
    }
}

Failed

From States/Failed.cs:8-17:

[TypeOption(typeof(ProcessStates), "Failed")]
public sealed class Failed : ProcessStateBase
{
    public Failed() : base(4, "Failed", isTerminal: true, isError: true, isActive: false, isInitial: false)
    {
    }
}

Cancelled

From States/Cancelled.cs:8-17:

[TypeOption(typeof(ProcessStates), "Cancelled")]
public sealed class Cancelled : ProcessStateBase
{
    public Cancelled() : base(5, "Cancelled", isTerminal: true, isError: false, isActive: false, isInitial: false)
    {
    }
}

TimedOut

From States/TimedOut.cs:9-25:

[TypeOption(typeof(ProcessStates), "TimedOut")]
public sealed class TimedOut : ProcessStateBase
{
    public TimedOut()
        : base(
            id: 7,
            name: "TimedOut",
            isTerminal: true,
            isError: true,
            isActive: false,
            isInitial: false)
    {
    }
}

Message System

ExecutionMessage

From ExecutionMessage.cs:9-24:

public abstract class ExecutionMessage : MessageTemplate<MessageSeverity>, IServiceMessage
{
    protected ExecutionMessage(int id, string name, MessageSeverity severity,
        string message, string? code = null, string? category = null, string? helpLink = null)
        : base(id, name, severity, message, code, "Execution") { }
}

ExecutionMessageCollectionBase

From ExecutionMessageCollectionBase.cs:9-13:

[MessageCollection("ExecutionMessages", ReturnType = typeof(IServiceMessage))]
public abstract class ExecutionMessageCollectionBase : MessageCollectionBase<ExecutionMessage>
{
}

Message Types

Configuration Messages:

• ProcessConfigurationInvalidMessage - Configuration validation failures
• ProcessConfigurationMissingMessage - Missing required configuration

Process Messages:

• ProcessCancellationRequestedMessage - Process cancellation notifications
• ProcessTimeoutMessage - Process timeout notifications
• ProcessStateTransitionFailedMessage - Invalid state transitions
• ProcessExecutionFailedMessage - General process execution failures

Execution Messages:

• OperationExecutionStartedMessage - Operation start notifications
• OperationExecutionCompletedMessage - Operation completion notifications
• OperationExecutionFailedMessage - Operation failure notifications
• OperationNotSupportedMessage - Unsupported operation requests

Dependencies

Project References

• FractalDataWorks.Collections - TypeCollection system
• FractalDataWorks.Collections.SourceGenerators - Code generation for TypeCollections
• FractalDataWorks.Results - Result pattern implementation
• FractalDataWorks.Services.Abstractions - Base service abstractions
• FractalDataWorks.Services.Abstractions - ServiceType patterns
• FractalDataWorks.Messages - Message system

Package References

• Microsoft.Extensions.DependencyInjection.Abstractions - DI framework
• Microsoft.Extensions.Logging.Abstractions - Logging framework

Implementation Notes

Process Lifecycle Management

Process execution follows a well-defined lifecycle with states defined in ProcessStates:

1. Created (id: 1, isInitial: true) - Process instance created with configuration
2. Pending (id: 6) - Process triggered but not yet started
3. Running (id: 2, isActive: true) - Process actively executing operations
4. Completed (id: 3, isTerminal: true) - Successfully completed
5. Failed (id: 4, isTerminal: true, isError: true) - Failed during execution
6. Cancelled (id: 5, isTerminal: true) - Cancelled before completion
7. TimedOut (id: 7, isTerminal: true, isError: true) - Exceeded timeout limit

TypeCollection Pattern

Process types and states use the TypeCollection pattern:

• ProcessTypes - Collects all ProcessTypeBase implementations via source generation
• ProcessStates - Collects all ProcessStateBase implementations via source generation
• Lookup by name using ProcessStates.ByName("Running") returns IProcessState

Process Result Factory Methods

Use the static factory methods on ProcessResult for creating results:

// Success result
ProcessResult.Success(processId, operationName, finalState, data, metrics);

// Failure result
ProcessResult.Failure(processId, operationName, finalState, errorMessage, exception);

Metrics Collection

Use ProcessMetrics factory methods:

ProcessMetrics.Empty                           // No metrics
ProcessMetrics.WithItemCount(1000)             // Items processed
ProcessMetrics.WithCounters(countersDictionary) // Custom counters

Target Framework

• netstandard2.0
• Nullable Reference Types: Enabled
• Implicit Usings: Enabled