redb.Tsak.Core 3.3.1

redb.Tsak.Core

The server-side engine of redb.Tsak. Contains the REST API controllers, all runtime services (hot-reload, context management, coordinator, watchdog, metrics), the module system (assembly loading, isolated ALCs), security middleware (API key auth with HMAC-SHA256), and storage abstractions.

This project is referenced by the Worker host (redb.Tsak.Worker) and the Pro variant (redb.Tsak.Core.Pro). It is not meant to be consumed directly by application code — use redb.Tsak.Client for programmatic access.

Project structure

redb.Tsak.Core/
├── Contracts/          ← Interfaces (ITsakModule, ITsakContextManager, ITsakCoordinator, …)
├── Controllers/        ← ASP.NET Core controllers (13 controllers, 32 endpoints)
├── Extensions/         ← DI registration helpers
├── Models/             ← Internal models (not exposed as API DTOs)
├── Modules/            ← Assembly loading: ALC, hot-swap, manifest, packages
├── Monitoring/         ← Watchdog, metrics, health, lifecycle audit, log ring-buffer
├── Security/           ← API key service, stores, audit filter
└── Services/           ← Business logic: context manager, coordinator, hot-reload, storage

Core concepts

Module

A module is a deployable unit — a directory of DLLs or a .tpkg archive — that contains one or more redb.Route route builders. The core module contract is ITsakModule:

Two concrete implementations exist:

• StaticMethodModule — wraps a static void main(IRouteContext) entry point
• RouteBuilderModule — wraps a RouteBuilder subclass

Context

A context is a named IRouteContext instance that groups one or more modules into a shared lifecycle, property bag, and redb instance. Contexts are either:

• Named — declared in appsettings.json under Tsak:Contexts:{name}:Modules, may host multiple modules.
• Anonymous — created automatically for any module not assigned to a named context; one module = one context.

5-layer configuration merge

Every context's property bag is built by ConfigMergeHelper.DeepMerge across five layers (outer layers win):

Services

HotReloadService

Background service that periodically scans Tsak:Modules:AssemblyPaths for:

• Directories containing *.dll → loads via per-module ModuleAssemblyLoadContext
• *.tpkg ZIP archives → unpacks into ModulePackage with its own isolated ALC

Tracks file timestamps and performs graceful hot-swap:

1. New DLL/package detected → load new module into new ALC
2. Stop old module (drain in-flight exchanges)
3. Register new module, start context
4. Optionally unload old ALC (requires Collectible = true)

Key configuration (Tsak:HotReload):

TsakContextManager

Manages the lifecycle of all IRouteContext instances:

• Creates named and anonymous contexts from config + merged property bag
• Starts/stops/restarts contexts and individual routes
• Serializes lifecycle operations via SemaphoreSlim to prevent races
• Maintains isolated mini-DI containers per named IRedbService instance (created by RedbInstanceFactory)
• Persists autostart state in ITsakStateStore
• Publishes events to LifecycleAuditService

TsakCoordinator

Bridges the module registry and the context manager. Subscribes to ITsakModuleRegistry events (ModuleAdded, ModuleRemoved, ModuleUpdated, ModulesBatchAdded) and orchestrates context creation/teardown:

• Groups modules by target context (named vs anonymous)
• Per-context locks prevent races when multiple modules arrive concurrently
• On module removal, decides whether to destroy the whole context or just remove one module from a named context

TsakModuleRegistry

In-memory registry of all currently known ITsakModule instances. Raises typed events consumed by TsakCoordinator. Backed by ITsakModuleStore for persistence across restarts (optional).

RedbInstanceFactory

Creates isolated IRedbService instances (Postgres or MSSql, open or Pro) from a config dictionary. Each instance lives in its own ServiceProvider mini-container that the context manager disposes when the context is removed.

SystemContextBuilder

Builds the global system context that hosts Tsak's own REST API and monitoring endpoints. Configured by ISystemContextPlugin contributors (Pro variant adds cluster leadership, metrics retention, etc.).

Monitoring subsystem

RouteWatchdogService

Background service (IHostedService) that periodically scans all routes for:

• Suspected exchanges — in-flight longer than Tsak:Watchdog:SuspectedThresholdSeconds
• Hung exchanges — in-flight longer than Tsak:Watchdog:HungThresholdSeconds

Maintains a queryable WatchdogState with ActiveAlerts. Can auto-restart hung routes when configured. Enable/disable at runtime via RouteWatchdogService.Enable() / .Disable(), or via the REST API / CLI.

MetricsCollectionService

Background service that samples CPU, memory, thread pool, and GC metrics on a configurable interval and stores them in a ring buffer. The ring buffer is queryable via /api/system/metrics and /api/system/metrics/history.

HealthCheckService

Aggregates IHealthContributor registrations (from Core, Pro, and module-contributed) into a single /api/system/health response.

LifecycleAuditService

Maintains an append-only audit log of context/route lifecycle events, queryable via /api/diagnostics/lifecycle. Persisted to ITsakStateStore in Redb-backed mode.

LogRingBuffer / RingBufferSink

Serilog sink that captures recent log entries into a fixed-capacity ring buffer. Accessible via /api/logs. Enabled when Tsak:Logging:RingBuffer:Enabled = true.

Security

ApiKeyService

• Keys are stored as HMAC-SHA256 hashes (never raw).
• Validation uses CryptographicOperations.FixedTimeEquals to prevent timing attacks.
• Validated results are cached for CacheTtl (default 5 min) to reduce store round-trips.

IApiKeyStore implementations

AdminAuditFilter

MVC action filter that records every mutating API call to LifecycleAuditService for compliance and debugging.

Controllers

Module assembly loading

ModuleAssemblyLoadContext

Per-module isolated AssemblyLoadContext. Resolution order:

1. Module's own directory (private DLLs)
2. Shared loader (SharedAssemblyLoader — common assemblies provided by the host)
3. Default ALC (host assemblies)

Collectible = true enables Unload() for GC reclamation after a hot-swap, at the cost of incompatibility with Reflection.Emit-based serializers.

ModulePackage

Manages .tpkg ZIP archives. On load, extracts the archive to a temp directory, resolves entry-point DLLs, loads them into a dedicated isolated ALC. On unload (atomic package removal), tears down all modules from the package simultaneously.

ModuleManifest

Deserialized from manifest.json inside each module directory or .tpkg:

{
  "Name": "Orders",
  "Version": "2026.05.06.1430",
  "EntryPoints": ["Orders.dll"],
  "Dependencies": ["redb.Route.Kafka"]
}

EntryPoints lists DLLs containing route builders. Other DLLs in the package are companion dependencies loaded into the same ALC.

SharedAssemblyLoader

Coordinates assembly resolution across multiple module ALCs to avoid loading the same host-provided DLL multiple times. Modules that resolve via the shared loader get the host's singleton instance (same type identity, no interface mismatch).

LoadedAssemblyTracker

Prevents duplicate DLL loads when multiple modules in the same ALC reference the same assembly file.

Storage abstractions

Two storage areas are abstracted behind interfaces:

ITsakModuleStore — persists module registrations across restarts.
ITsakStateStore — persists context autostart flags and lifecycle audit events.

Configure via Tsak:Storage:Mode:

• InMemory — default; stateless restarts, no database required.
• Redb — persistent; requires a configured IRedbService (Postgres or MSSql).

Extension points

Key dependencies

Related projects