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

FractalDataWorks.Services.Connections.Abstractions

Abstractions for external connection services in the FractalDataWorks Framework.

Overview

This package provides interfaces and base types for connection management in the FractalDataWorks ecosystem. It defines the domain boundary for creating, configuring, and managing connections to external systems (databases, APIs, file systems).

Target Framework

• netstandard2.0

Dependencies

• FractalDataWorks.Services.Abstractions - Base service interfaces
• FractalDataWorks.Services.Abstractions - ServiceType infrastructure
• FractalDataWorks.Results - Railway-oriented result types
• FractalDataWorks.Data.Abstractions - Data layer interfaces
• FractalDataWorks.Commands.Abstractions - Command infrastructure
• FractalDataWorks.Commands.Data.Abstractions - Data command types
• FractalDataWorks.Collections - TypeCollection base classes
• FractalDataWorks.Services.SecretManagers.Abstractions - Secret manager integration
• FractalDataWorks.Services.Authentication.Abstractions - Authentication integration

Key Interfaces

IGenericConnection

From IGenericConnection.cs:15-18:

public interface IGenericConnection : IDisposable, IGenericService
{

}

The base interface for all FractalDataWorks connections. Extends IDisposable for lifecycle management and IGenericService for service framework integration.

IConnection<TConfiguration>

From IConnection.cs:19-48:

public interface IConnection<TConfiguration> : IGenericConnection
    where TConfiguration : IConnectionConfiguration
{
    TConfiguration Configuration { get; }

    Task<IGenericResult> Initialize(TConfiguration configuration);
}

Generic connection interface with typed configuration support.

IDataConnection

From IDataConnection.cs:22-42:

public interface IDataConnection : IGenericConnection
{
    Task<IGenericResult<T>> Execute<T>(DataCommand command, IStorageContainer container, CancellationToken cancellationToken = default);

    Task<IGenericResult> Execute(DataCommand command, IStorageContainer container, CancellationToken cancellationToken = default);
}

Interface for connections that execute data commands. The IStorageContainer parameter provides schema metadata from the DataGateway.

IConnectionConfiguration

From IConnectionConfiguration.cs:12-60:

public interface IConnectionConfiguration : IGenericConfiguration
{
    string ConnectionType { get; }

    IServiceLifetime Lifetime { get; }

    string? SecretManagerName { get; init; }

    string? SecretKeyName { get; init; }

    string? AuthenticationName { get; init; }
}

Configuration interface for connections. The ConnectionType property determines which factory creates the connection. Supports secret manager and authentication integration.

IConnectionFactory

From IConnectionFactory.cs:

public interface IConnectionFactory : IServiceFactory
{
    IGenericResult<IGenericConnection> Create(IGenericConfiguration configuration);

    IGenericResult<IGenericConnection> Create(IGenericConfiguration configuration, string connectionType);
}

Factory interface for creating connections. Factories inject their dependencies via constructor.

IConnectionFactory<TConnection, TConfiguration>

From IConnectionFactory.cs:

public interface IConnectionFactory<TConnection, in TConfiguration> : IConnectionFactory, IServiceFactory<TConnection, TConfiguration>
    where TConfiguration : IConnectionConfiguration
    where TConnection : IGenericConnection
{
    IGenericResult<TConnection> Create(TConfiguration configuration);

    IGenericResult<TConnection> Create(TConfiguration configuration, string connectionType);
}

Generic factory interface with typed connection and configuration.

IConnectionProvider

From IConnectionProvider.cs:

public interface IConnectionProvider : IFdwServiceProvider<IGenericConnection, IConnectionConfiguration>
{
    // Inherits from IFdwServiceProvider:
    // IGenericResult<IGenericConnection> Create(IConnectionConfiguration configuration);
    // IGenericResult<IGenericConnection> Create(string name);
    // IGenericResult<IGenericConnection> Create(Guid id);
    // IGenericResult<T> Create<T>(IConnectionConfiguration configuration) where T : IGenericConnection;
    // IGenericResult<T> Create<T>(string name) where T : IGenericConnection;
    // IGenericResult<T> Create<T>(Guid id) where T : IGenericConnection;
}

Provider interface for creating connections. Uses ConnectionTypes to lookup factories based on configuration. Extends IFdwServiceProvider with Create() methods for connection creation.

IDataConnectionProvider

From IDataConnectionProvider.cs:

public interface IDataConnectionProvider : IFdwServiceProvider<IDataConnection, IConnectionConfiguration>
{
    // Inherits Create() methods from IFdwServiceProvider
}

Specialized provider for data connections. Used by DataGateway to route data commands to connections.

IConnectionType

From IConnectionType.cs:17-32:

public interface IConnectionType<TService, TConfiguration, TFactory> : IServiceType<Guid, TService, TFactory, TConfiguration>, IConnectionType
    where TService : IGenericConnection
    where TConfiguration : IConnectionConfiguration
    where TFactory : IConnectionFactory<TService, TConfiguration>
{
}

public interface IConnectionType : IServiceType
{
}

ServiceType interface for connection types. Integrates with the framework's dependency injection and configuration systems.

IConnectionMetadata

From IConnectionMetadata.cs:15-73:

public interface IConnectionMetadata
{
    string SystemName { get; }

    string? Version { get; }

    string? ServerInfo { get; }

    string? DatabaseName { get; }

    IReadOnlyDictionary<string, object> Capabilities { get; }

    DateTimeOffset CollectedAt { get; }

    IReadOnlyDictionary<string, object> CustomProperties { get; }
}

Metadata about a connected external system. Includes capabilities, version information, and custom properties.

Connection States

Connection states are implemented as a TypeCollection for type-safe state management.

IConnectionState

From States/IConnectionState.cs:1-9:

public interface IConnectionState : ITypeOption<int, ConnectionStateBase>
{
}

ConnectionStateBase

From States/ConnectionStateBase.cs:12-21:

public abstract class ConnectionStateBase : TypeOptionBase<int, ConnectionStateBase>, IConnectionState
{
    protected ConnectionStateBase(int id, string name) : base(id, name)
    {
    }
}

ConnectionStates TypeCollection

From States/ConnectionStates.cs:1-16:

[TypeCollection(typeof(ConnectionStateBase), typeof(IConnectionState), typeof(ConnectionStates))]
public abstract partial class ConnectionStates : TypeCollectionBase<ConnectionStateBase, IConnectionState>
{

}

Built-in states include:

From States/ClosedConnectionState.cs:10-11:

[TypeOption(typeof(ConnectionStates), "Closed")]
public sealed class ClosedConnectionState() : ConnectionStateBase(6, "Closed");

From States/OpenConnectionState.cs:10-11:

[TypeOption(typeof(ConnectionStates), "Open")]
public sealed class OpenConnectionState() : ConnectionStateBase(3, "Open");

From States/BrokenConnectionState.cs:10-11:

[TypeOption(typeof(ConnectionStates), "Broken")]
public sealed class BrokenConnectionState() : ConnectionStateBase(7, "Broken");

Usage:

// Lookup by name
var openState = ConnectionStates.ByName("Open");

// Lookup by ID
var closedState = ConnectionStates.ById(6);

Command Architecture

This package references two command hierarchies for the connection layer.

IConnectionCommand (from Commands.Data.Abstractions)

Connection commands are the OUTPUT of data command translation. They represent connection-specific commands ready for execution.

From /public/src/FractalDataWorks.Commands.Data.Abstractions/Commands/IConnectionCommand.cs:24-26:

public interface IConnectionCommand : IGenericCommand
{
}

Examples: SqlConnectionCommand, RestConnectionCommand, FileConnectionCommand.

IDataCommand (from Commands.Data.Abstractions)

Data commands are universal operations that work across all connection types. Translators convert them to connection-specific commands.

From /public/src/FractalDataWorks.Commands.Data.Abstractions/Commands/IDataCommand.cs:20-45:

public interface IDataCommand : IGenericCommand
{
    string ContainerName { get; }

    string ConnectionName { get; }

    IReadOnlyDictionary<string, object> Metadata { get; }
}

Architecture Pattern

The connection abstractions follow the framework's service infrastructure pattern:

1. Configuration (IConnectionConfiguration) - Defines connection parameters
2. Factory (IConnectionFactory) - Creates connection instances
3. Provider (IConnectionProvider) - Retrieves connections by name/ID
4. Connection (IGenericConnection, IDataConnection) - Executes operations

Key principles:

• Factories inject their dependencies via constructor
• IServiceProvider is never stored as a field
• All operations return IGenericResult for railway-oriented error handling
• Connection types use [ServiceTypeOption] for source-generated discovery

Related Packages

• FractalDataWorks.Services.Connections - Default implementations
• FractalDataWorks.Services.Connections.MsSql - SQL Server connection type
• FractalDataWorks.Services.Connections.Http - HTTP connection implementations
• FractalDataWorks.Services.Connections.Http.Abstractions - HTTP connection abstractions
• FractalDataWorks.Commands.Data.Abstractions - Data command types