TCIS.Pluggable.Abstractions 1.0.0-rc.19

TCIS.Pluggable.Abstractions

The contract package of the TCIS Pluggable architecture. It defines pipeline steps, business rules, site modules, and connection-level tenant isolation.

Zero infrastructure dependencies. No ASP.NET Core, no EF Core, no database provider. A plugin only needs a reference to this package plus the Platform Core it extends.

Table of contents

1. Pipeline contracts

IPipelineContext — the bag that travels through a run

IPipelineContext<TResponse> adds TResponse? Result { get; set; } for pipelines that return data.

IsSuccess is a derived property (_errors.IsEmpty), not a flag — so a context can never end up "holding errors but reporting success". Errors are stored in a ConcurrentQueue, which keeps it safe when a step fans out internally.

IPipelineStep<TContext> — one business step

[PlatformStep("Gate.ValidateContainer", executionOrder: 10)]
public sealed class CoreValidateContainerStep(IContainerRepository repo)
    : IPipelineStep<IGateInContext>
{
    public async Task ProcessAsync(IGateInContext context, CancellationToken ct = default)
    {
        var container = await repo.FindAsync(context.ContainerNo, ct);   // exception -> 503
        if (container is null)
        {
            context.Fail($"Container {context.ContainerNo} does not exist.");   // business -> 4xx
            return;
        }

        context.SetFeature(container);      // hand it to later steps
    }
}

Step attributes

Reusing a StepKey overrides: the step with the higher priority wins, so a [PluginStep] replaces the [PlatformStep] carrying the same key. A new StepKey inserts: pick an executionOrder between two existing ones.

Before overriding, weigh it up: if you find yourself copying most of the Core step's logic, the real problem is the granularity of the Core step. Ask the Platform team to split it instead of copying — copying is precisely the mechanism that produces drift between a port and Core.

Passing data between steps

context.SetFeature(container);                       // producer step
var container = context.GetRequiredFeature<Container>();   // consumer step
var maybe     = context.GetFeature<Container>();           // null when absent

Prefer this over State when the value is typed — GetRequiredFeature<T> fails loudly with the type name instead of returning a silent null.

2. Business rules

Use IBusinessRule<TContext> when a step needs to be split into independently switchable checks.

public sealed class ContainerWeightRule(ISiteSettings settings) : IBusinessRule<IGateInContext>
{
    public string RuleKey => "Rule.Gate.ContainerWeight";

    public Task<bool> IsSatisfiedAsync(IGateInContext context, CancellationToken ct)
        => Task.FromResult(context.WeightKg <= settings.MaxContainerWeightKg);
}

A site can switch a Platform rule off without touching Platform code:

public sealed class CatLaiRulePolicy : IBusinessRulePolicy   // the "Policy" suffix auto-registers it
{
    private static readonly HashSet<string> Disabled = ["Rule.Gate.ContainerWeight"];

    public bool IsRuleEnabled(string ruleKey) => !Disabled.Contains(ruleKey);
}

DefaultBusinessRulePolicy enables everything; it is the fallback when a site supplies no policy.

3. Site modules

ISiteModule — the entry point of a module

public sealed class CatLaiModule : ISiteModule
{
    public string SiteCode => "CATLAI";        // MUST NOT be "DEFAULT" for a plugin

    public void RegisterServices(IServiceCollection services, IConfiguration configuration)
    {
        services.AddScoped<ICustomsGateway, CatLaiCustomsGateway>();
    }
}

Platform modules declare SiteCode = "DEFAULT" and load for every site. Plugin modules declare their own site code and load only for that site.

[MultiTenantService] — per-site service implementations

Classes whose names end with a configured suffix (Service, Provider, Repository, Factory, Manager, Mapper, Policy) are registered per site automatically. Use the attribute when the name does not follow a suffix, or to name the service type explicitly:

[MultiTenantService(typeof(IFeeCalculator))]
public sealed class CatLaiFeeCalculator : IFeeCalculator { … }

IPluggableDiscoveryHook — joining discovery from your own library

Implement it when a library of yours needs to inspect or contribute during the discovery sweep, rather than requiring every host to wire it manually.

4. Connection-level tenant isolation

This is the layer that makes a single process safely serve several tenants.

ITenantConnectionInitializer

void Initialize(DbConnection connection, string? tenantId);
Task InitializeAsync(DbConnection connection, string? tenantId, CancellationToken ct = default);
void Cleanup(DbConnection connection);
Task CleanupAsync(DbConnection connection);

Initialize runs immediately after the connection opens; Cleanup runs before it returns to the pool.

TenantConnectionInitializerBase — write only the SQL

A template-method base: derived classes describe the command, the orchestration is written once.

public sealed class MyRlsInitializer : TenantConnectionInitializerBase
{
    protected override void ConfigureInitializeCommand(DbCommand command, string? tenantId) { … }
    protected override void ConfigureCleanupCommand(DbCommand command) { … }
}

Every initializer used to hand-write all four methods, with the sync and async bodies about 84% identical. That duplication produced two serious defects — a fix applied to the async branch but not the sync one, and Tier 1 failing closed while Tier 2 failed open because the branches were written separately.

Throwing from ConfigureInitializeCommand means the framework executes no command at all — fail-closed by construction.

TenantAwareDbConnection — the decorator trio

public sealed class TenantAwareDbConnection(
    DbConnection innerConnection, string? tenantId, ITenantConnectionInitializer initializer) : DbConnection

Transparent to both EF Core and Dapper.

Four safety details worth knowing:

1. Initialize fails → Close() at once. A connection that never got its isolation applied must not reach the pool; it would carry poisoned state into another tenant's request.

2. _isInitialized is reset in a finally — including when State == Broken (dropped network, database restart) causes the cleanup branch to be skipped. Leaving the flag set would make the next Open() skip Initialize, giving a session with no tenant isolation at all.

3. A connection decorator must decorate all four types, because the invariant only holds if every path that opens a transaction, creates a command or closes the connection goes through the wrapper:

   Type	Why it is needed
   TenantAwareDbConnection	The entry point — applies and clears tenant isolation
   TenantAwareDbTransaction	EF Core validates connection.DbConnection != transaction.Connection inside the RelationalTransaction constructor
   TenantAwareDbCommand	Providers downcast (SqlCommand.DbTransaction → SqlTransaction), so the wrapper must be unwrapped before reaching the inner command
   TenantAwareDbDataReader	CommandBehavior.CloseConnection makes the reader close the connection. Letting it close the inner connection skips Cleanup and leaves the initialised flag set — the next Open() then runs with no tenant isolation

4. DisposeAsync needs a double-release guard. DbTransaction.DisposeAsync() and DbCommand.DisposeAsync() fall back to calling Dispose(), so an async branch that releases the inner object and lets base run releases it twice. It does not crash on SQL Server or SQLite because their Dispose is idempotent — exactly the kind of defect a green test suite does not catch.

Why the command and the transaction are wrapped too

EF Core validates identity inside the RelationalTransaction constructor — connection.DbConnection != transaction.Connection throws "The specified transaction is not associated with the current connection." Returning the inner connection's transaction directly fails that check, because EF holds the decorator while the transaction reports the inner connection.

That broke every transaction in the Pluggable stack — not only explicit BeginTransactionAsync, but also the transaction EF opens by itself when SaveChanges has to send more than one batch. Saving many rows at once was enough to hit it.

Wrapping the transaction then forces wrapping the command: providers downcast (SqlCommand.DbTransaction casts to SqlTransaction), so the wrapper has to be unwrapped before it is handed to the inner command. TenantAwareDbCommand exists for exactly that one job and delegates everything else untouched.

Verified against real SQL Server and PostgreSQL containers.

TenantConnectionIdentifier — which identifier each tier needs

public static string? Resolve(IsolationTier tier, string? tenantId, string? tenantIdentifier);

The rule lives in one place because there are six connection-building sites (3 providers × EF Core and Dapper). All six once passed Id straight through, which made Tier 2 impossible to run.

NoOpConnectionInitializer does nothing and serves Tier 3, where a dedicated connection string already provides isolation.

5. ⚠️ Invariants you must not break

Full reasoning: md/29 Part 6.

6. Pitfalls