TCIS.Pluggable.Engine 1.0.0-rc.19

TCIS.Pluggable.Engine

The core engine of the TCIS Pluggable architecture: unified discovery (modules, steps, rules, services), the pipeline engine, and the pipeline analyzer.

Contracts live in TCIS.Pluggable.Abstractions. Your plugins reference the contracts; the host references this package.

Table of contents

1. Registration

dotnet add package TCIS.Pluggable.Engine

builder.Services
    // Standard business, shared by every site
    .AddPluggablePipeline(builder.Configuration,
        typeof(GatePlatformModule).Assembly,
        typeof(VesselPlatformModule).Assembly)

    // Site-specific business — EXPLICIT assembly references, no directory scanning
    .AddSitePlugins(builder.Configuration,
        typeof(CatLaiModule).Assembly);

Auto-registration suffixes are configurable:

{
  "TLogSettings": {
    "AopSettings": {
      "DiRegistrationSuffixes": [ "Service", "Provider", "Mapper", "Factory", "Manager", "Repository", "Policy" ]
    }
  }
}

2. Plugins are referenced statically

Every deployment has its own host project, and the hosts differ in exactly one thing — the assemblies passed to AddSitePlugins:

// A large port with its own deployment
.AddSitePlugins(configuration, typeof(CatLaiModule).Assembly);

// Several small ports sharing one deployment
.AddSitePlugins(configuration,
    typeof(SiteAModule).Assembly,
    typeof(SiteBModule).Assembly);

Why there is no DLL directory scanning

The plugin set of any deployment is already known at build time, so an AssemblyLoadContext buys nothing — while a static reference buys something far more valuable: the compiler becomes a drift detector.

With dynamic loading, Core can change an interface signature and the old plugin still compiles (it is built separately); the failure then surfaces at runtime, in production, at that one port. With static references the build goes red immediately and names exactly which plugin broke. That is the cheapest possible guard against Core/plugin drift — see md/28.

3. Discovery

Discovery runs once, during ConfigureServices:

Discovery never skips an error quietly. One malformed step and the application will not start. That is deliberate: a step that failed to register would never run, and a pipeline missing a safety check is more dangerous than an application that refuses to boot.

PipelineDiscoveryException lists all problems at once, not just the first.

4. Execution semantics

Controller / handler
   └─ IPipelineEngine.ExecuteAsync(context, ct)
        1. Guard the context
        2. siteCode <- WorkContext.Tenant.SiteCode      (THE ONLY SOURCE OF TRUTH)
        3. context.SiteCode = siteCode                  (direct assignment, never ??=)
        4. blueprint <- cache[(siteCode, contextType)]
        5. for each step:
              - resolve through keyed DI
              - start an Activity, start a stopwatch
              - await step.ProcessAsync(context, ct)
              - record metrics
              - if (!context.IsSuccess) stop, unless ContinueOnError

Writing, overriding, inserting

// Platform: standard business
[PlatformStep("Gate.ValidateContainer", executionOrder: 10)]
public sealed class CoreValidateContainerStep : IPipelineStep<IGateInContext> { … }

// Plugin: override — SAME StepKey, wins on priority
[PluginStep("Gate.ValidateContainer", executionOrder: 10)]
public sealed class CatLaiValidateContainerStep : IPipelineStep<IGateInContext> { … }

// Plugin: insert — NEW StepKey, slotted between 20 and 30
[PluginStep("Gate.CustomsCheck", executionOrder: 25)]
public sealed class CatLaiCustomsCheckStep : IPipelineStep<IGateInContext> { … }

Blueprints are cached per (siteCode, contextType), so step selection is resolved once, not per request.

Generic steps with several type parameters are not supported. Discovery rejects them at startup rather than failing later at resolution time.

5. Error behaviour

Three cases, and none of them skips a step. Every step either runs or stops the pipeline — so the failure class "pipeline reports success although a business step never ran" no longer exists structurally.

6. Resilience is not applied at step level

There is no timeout, retry or circuit breaker around a step. This is a deliberate decision, not an omission — see md/28.

Resilience belongs where a call crosses an infrastructure boundary, not around in-process business logic:

Why a step-level timeout does not do what people expect

Polly uses cooperative cancellation: it cancels a token and throws to the caller, but the step keeps running — .NET cannot forcibly abort a task. The result can be: the client already received an error, the pipeline already aborted, and the step still writes to the database seconds later. The only timeouts that genuinely stop work are CommandTimeout and the ones at the connection layer.

Configure the backstop like this:

builder.Services.AddRequestTimeouts(o =>
    o.DefaultPolicy = new RequestTimeoutPolicy { Timeout = TimeSpan.FromSeconds(60) });

app.UseTCISCore();       // TExceptionMiddleware must WRAP the outside to classify correctly
app.UseRequestTimeouts();

TExceptionMiddleware distinguishes a server timeout from a client disconnect through IHttpRequestTimeoutFeature.RequestTimeoutToken — both surface as OperationCanceledException, so the exception type alone cannot tell them apart.

Situation	HTTP	Log level
Request exceeded the server time limit	504 GATEWAY_TIMEOUT	Error → alerts fire
Client closed the connection	499 CLIENT_CLOSED	Information → no alert

Misclassifying is not only the wrong status code, it is the wrong log level — an overload incident would slip past every alerting system.

7. Metrics

A circuit breaker used to detect a repeatedly failing step. It was removed because it guarded the wrong threat, but the signal is still needed. Alerting is now the only breaker.

builder.Services.AddOpenTelemetry()
    .WithTracing(t => t.AddSource("TCIS.Platform.Pipelines"))
    .WithMetrics(m  => m.AddMeter(PipelineMetrics.MeterName));   // "TCIS.Platform.Pipelines"

All three carry the tcis.site_code, tcis.step_key and tcis.context labels.

Business failures are counted separately. Rejecting an overweight container is the system doing its job correctly; mixing the two into one metric makes every alerting threshold meaningless.

The tcis.site_code label is mandatory rather than decorative: many small ports share one process, so a system-wide error total hides the very situation that most needs an alert — one port failing completely while nine others stay green.

Suggested alerting rules:

# One step of one port failing repeatedly — replaces what the circuit breaker used to do
sum by (tcis_site_code, tcis_step_key) (rate(tcis_pipeline_step_errors_total[5m])) > 0.2

# One step unusually slow — an early sign of a stalling database
histogram_quantile(0.95,
  sum by (le, tcis_site_code, tcis_step_key) (rate(tcis_pipeline_step_duration_bucket[5m]))) > 5000

8. Diagnosing "my step doesn't run"

The analyzer is a read-only borrower of the engine's step-selection rules. It never influences them.

9. Pitfalls