DEV Community: rinat kozin

Two routes in an evening: from a debug worker to an enterprise runtime with redb.Route + Tsak

rinat kozin — Thu, 02 Jul 2026 22:31:42 +0000

Series: redb ecosystem

Integration code has a funny asymmetry to it.

Writing a couple of routes — "take an HTTP request, stash it in a database, hand something back" — is a half-hour job. But getting that same thing to run in production, come up on its own, show you metrics, let you stop and start individual pieces by hand, and redeploy without a rebuild? That's usually a completely different stack and a completely different afternoon.

This post is about how, with redb.Route + redb.Tsak, it's literally the same code. We'll:

write two tiny routes (POST to save, GET to fetch by a query param) on redb.Route;
build our own debug worker — a plain console app you can run under the debugger with breakpoints;
and then, without changing a single line of the routes, pack it into a module and drop it into Tsak — where the exact same project picks up a dashboard, hot-reload, live route management, and enterprise deployment (with Docker and without).

All the code is in the repo (redb.Route/demos/EchoWorkerDemo), and I'm pasting it here in full so you can follow along.

Part of the redb / redb.Route series — recent posts first:

Leaving MassTransit for a Camel state of mind: the Kafka connector, Scatter-Gather, and transactions

Apache Camel for .NET, dissected: the HTTP connector with no ASP.NET MVC + the Content-Based Router

redb.Route — Apache Camel for .NET: 22 transports, 30+ EIP patterns, compiled DSL

Sources: github.com/redbase-app. About the database itself: redb.ru.

This one is the gentle intro to workers and deployment. Clustering — the coordinator, leader election, failover — gets its own post.

What we're building

A tiny notes service. Two endpoints on a single HTTP port:

POST /api/notes with a body like {"tag":"work","text":"hello"} — save a note into a redb database (on SQLite);
GET /api/notes?tag=work — return notes with that tag; the lookup runs server-side via Where(...).ToListAsync(), with the parameter pulled straight from the query string.

Nothing fancy. The point of the post isn't the business logic — it's the lifecycle: how one and the same set of routes first lives in a debug console, and then in an enterprise runtime.

Project layout: two projects, one entry point

Here's the shape of it:

EchoWorkerDemo/
├─ EchoModule/            <- project 1: the module (class library -> EchoModule.tpkg)
│  ├─ InitRoute.cs        <- main(IRouteContext): two routes + the Note class
│  ├─ manifest.json       <- { Name, Version, EntryPoints: ["EchoModule.dll"] }
│  ├─ EchoModule.config.json  <- context name (ContextName) + AutoStart
│  └─ EchoModule.csproj   <- references to the connectors + the PackTpkg target
└─ EchoWorker/            <- project 2: the debug host (exe)
   ├─ Program.cs          <- redb on SQLite + a call to InitRoute.main + Start
   └─ EchoWorker.csproj

The whole thing hinges on one idea: there is exactly one entry point — InitRoute.main(IRouteContext). Both our debug worker and the real Tsak runtime call it. The route code lives in exactly one place — EchoModule. The debug EchoWorker is just the plumbing that stands up a database and calls that same main.

Why two projects and not one? You can do one — an exe still produces a DLL, and Tsak finds InitRoute.main by reflection in any assembly. But splitting the two roles makes them obvious: EchoModule is what you ship (it packs into a .tpkg), and EchoWorker is what you debug with. The module carries zero host code — which is exactly right, because in production Tsak hands it the database.

Project 1: the module with two routes

Here it is in full — EchoModule/InitRoute.cs:

using System.Text.Json;

using redb.Core;                          // IRedbService, Query, SaveAsync, SyncSchemeAsync
using redb.Core.Attributes;               // RedbScheme
using redb.Core.Models.Entities;          // RedbObject<T>

using redb.Route.Abstractions;            // IRouteContext, IExchange
using redb.Route.Core;                    // RouteContext
using redb.Route.Http;                    // HttpComponent, SharedHttpServerManager
using redb.Route.RedbCore.Extensions;     // ProcessWithRedb, GetRedbService

namespace EchoModule;

/// <summary>
/// Tsak module entry point.
/// The worker discovers it by convention — a public static class named InitRoute
/// with a public static main(IRouteContext) — and calls it once when the module
/// loads. The debug host (EchoWorker/Program.cs) calls the very same method, so the
/// route code below lives in exactly one place.
///
/// Two minimal endpoints on the shared HTTP server (port 5099), backed by redb/SQLite:
///   POST /api/notes   body {"tag":"work","text":"hello"}   -> save one note
///   GET  /api/notes?tag=work                               -> list notes with that tag
/// </summary>
public static class InitRoute
{
    private static readonly JsonSerializerOptions Json = new() { PropertyNameCaseInsensitive = true };

    public static IRouteContext main(IRouteContext context)
    {
        // redb schema for Note. Idempotent — safe to call every load. The worker
        // (or the debug host) has already brought redb + SQLite up by now.
        context.GetRedbService().SyncSchemeAsync<Note>().GetAwaiter().GetResult();

        // One shared HTTP server; both routes below bind to it.
        context.AddComponent(new HttpComponent { ServerManager = new SharedHttpServerManager() });

        ((RouteContext)context).AddRoutes(r =>
        {
            // --- POST /api/notes — save one note ---
            r.From("http:0.0.0.0:5099/api/notes?inOut=true&methods=POST")
                .RouteId("notes-post")
                .ConvertBody<string>()                       // HTTP body -> string (JSON)
                .ProcessWithRedb(async (db, ex, ct) =>
                {
                    var note = JsonSerializer.Deserialize<Note>(ex.In.Body?.ToString() ?? "{}", Json) ?? new Note();
                    var obj = new RedbObject<Note> { name = $"note:{note.Tag}", Props = note };
                    await db.SaveAsync(obj);                 // one insert into redb (SQLite)
                    Reply(ex, new { saved = true, id = obj.id });
                }).Log("Save ${body}");

            // --- GET /api/notes?tag=work — list by tag ---
            r.From("http:0.0.0.0:5099/api/notes?inOut=true&methods=GET")
                .RouteId("notes-get")
                .ProcessWithRedb(async (db, ex, ct) =>
                {
                    // ?tag=... arrives as the header redbHttp.QueryParam.tag
                    var tag = ex.In.Headers.TryGetValue("redbHttp.QueryParam.tag", out var t)
                        ? t?.ToString() ?? ""
                        : "";

                    // Server-side filter: the GET parameter goes straight into Where(...).
                    var found = await db.Query<Note>()
                        .Where(n => n.Tag == tag)
                        .ToListAsync();

                    Reply(ex, found.Select(o => new { o.Props.Tag, o.Props.Text }));
                }).Log("Load ${header.redbHttp.QueryParam.tag}");
        });

        return context;
    }

    // inOut=true -> whatever the body is at the end becomes the HTTP response.
    private static void Reply(IExchange ex, object body)
    {
        ex.In.ContentType = "application/json";
        ex.In.Body = JsonSerializer.Serialize(body);
    }
}

/// <summary>Persisted note. [RedbScheme] marks the class as a redb schema.</summary>
[RedbScheme]
public sealed class Note
{
    public string Tag { get; set; } = "";
    public string Text { get; set; } = "";
}

Let's walk through the parts that matter — nearly every line is pulling its weight here.

The `main` entry point

public static IRouteContext main(IRouteContext context)

This is the Tsak module contract. No attributes, no interface to implement — just a naming convention: a public static class InitRoute, a public static method main taking an IRouteContext. When Tsak loads your assembly, it scans it by reflection, finds this method, and calls it with a context. Whatever you hang on that context — components, routes, listeners — becomes part of the runtime.

The neat bit: this works in the debug worker too. There, we create the RouteContext and we call InitRoute.main(ctx). Same method, two hosts.

The schema

context.GetRedbService().SyncSchemeAsync<Note>().GetAwaiter().GetResult();

Note is tagged [RedbScheme], which marks it as a persistable redb class. SyncSchemeAsync<Note>() registers its schema (idempotent — call it on every load, no harm done). GetRedbService() pulls IRedbService off the context: in Tsak the database is already up before your module runs, and in the debug worker we'll stand it up ourselves before main. Either way, redb is there by the time we ask.

Notice what the module doesn't do: it never configures the database. It doesn't know or care whether that's SQLite, Postgres, or MSSQL — it just asks the context for an IRedbService. The provider is the host's problem.

One HTTP server, two routes

context.AddComponent(new HttpComponent { ServerManager = new SharedHttpServerManager() });

SharedHttpServerManager is a shared HTTP server — several routes can hang off one port. Both of ours sit on 5099.

r.From("http:0.0.0.0:5099/api/notes?inOut=true&methods=POST")
r.From("http:0.0.0.0:5099/api/notes?inOut=true&methods=GET")

Both listen on the same path /api/notes, but they split on method via ?methods=POST / ?methods=GET. The server matches an incoming request on the pair "path + method": a POST goes to the first route, a GET to the second, and a PUT /api/notes gets an honest 405 Method Not Allowed (path matched, method didn't). inOut=true means request/response: whatever ends up in the exchange body at the end of the route becomes the HTTP response.

POST: save

.ConvertBody<string>()
.ProcessWithRedb(async (db, ex, ct) =>
{
    var note = JsonSerializer.Deserialize<Note>(ex.In.Body?.ToString() ?? "{}", Json) ?? new Note();
    var obj = new RedbObject<Note> { name = $"note:{note.Tag}", Props = note };
    await db.SaveAsync(obj);
    Reply(ex, new { saved = true, id = obj.id });
}).Log("Save ${body}");

ConvertBody<string>() turns the raw HTTP body (bytes) into a string. ProcessWithRedb is a processing step into which redb.Route injects the IRedbService (db) for you: under the hood it grabs the per-exchange DI scope if there is one, otherwise the context singleton. The rest is plain C#: deserialize the JSON into a Note, wrap it in a RedbObject<Note>, save it with a single SaveAsync, hand back { saved, id }.

The trailing .Log("Save ${body}") is a log step with interpolation: ${body} substitutes the current exchange body. redb.Route's ${...} can pull body, headers (${header.X}), and more — handy for tracing right inside the DSL.

GET: fetch by param

var tag = ex.In.Headers.TryGetValue("redbHttp.QueryParam.tag", out var t)
    ? t?.ToString() ?? ""
    : "";

var found = await db.Query<Note>()
    .Where(n => n.Tag == tag)
    .ToListAsync();

Reply(ex, found.Select(o => new { o.Props.Tag, o.Props.Text }));

redb.Route lays out HTTP query params as headers prefixed with redbHttp.QueryParam., so ?tag=work shows up as the header redbHttp.QueryParam.tag. Grab it, drop it straight into a server-side query:

db.Query<Note>().Where(n => n.Tag == tag).ToListAsync()

This is not "load everything into memory, then filter" — it's a query on the database side: the lambda n => n.Tag == tag compiles to a condition on the Note.Tag field. The result is a collection of RedbObject<Note>, so we reach the fields through .Props.

And that's the whole module. Two routes, a data class, zero infrastructure. Now let's run and debug it.

Project 2: our own debug worker

To run the routes under a debugger without spinning up any Tsak at all, we'll build a tiny console app. It reproduces exactly what the Tsak worker does when it loads a module, just in the smallest possible way. Here's EchoWorker/Program.cs in full:

// ============================================================================
//  EchoWorker — a debug host for the EchoModule Tsak module.
//
//  It reproduces, in the smallest possible way, what the Tsak worker does:
//    1) stand redb up on SQLite (Free tier — the worker's default),
//    2) create the redb system tables once,
//    3) hand a RouteContext to EchoModule.InitRoute.main — the SAME entry point
//       the worker calls, so no route code is duplicated here.
//
//  Run it, then (PowerShell — JSON in single quotes; cmd.exe needs \" escaping instead):
//    POST: curl.exe -X POST http://localhost:5099/api/notes -H "Content-Type: application/json" -d '{"tag":"work","text":"hello"}'
//    GET:  curl.exe "http://localhost:5099/api/notes?tag=work"
// ============================================================================

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;

using redb.Core;                          // IRedbService
using redb.Core.Extensions;               // AddRedb
using redb.Core.Models.Configuration;     // PropsSaveStrategy
using redb.SQLite.Pro.Extensions;         // UseSqlite (tier-agnostic: AddRedb -> Free)
using redb.SQLite.Data;                   // SqliteDataSource.NativeExtensionPath

using redb.Route.Core;                    // RouteContext

namespace EchoWorker;

public static class Program
{
    public static async Task Main(string[] args)
    {
        // Free SQLite needs the native redb extension. The packaged Tsak worker ships
        // it; running from source we point at the one built under redb.SQLite/native/build.
        SqliteDataSource.NativeExtensionPath ??= ResolveNativeExtension();

        // DI: console logging + redb on SQLite (single-file DB next to the exe).
        var services = new ServiceCollection();

        services.AddLogging(b => b
            .AddSimpleConsole(o => { o.SingleLine = true; o.TimestampFormat = "HH:mm:ss "; })
            .SetMinimumLevel(LogLevel.Information));

        services.AddRedb(o => o
            .UseSqlite("Data Source=echo_demo.db")
            .Configure(c => c.PropsSaveStrategy = PropsSaveStrategy.DeleteInsert));

        var sp = services.BuildServiceProvider();

        // Create the redb system tables once (the worker does this on boot).
        // ensureCreated: true builds the base tables on a fresh SQLite file.
        await sp.GetRequiredService<IRedbService>().InitializeAsync(ensureCreated: true);

        // Build a route context over that provider and call the module entry point.
        var ctx = new RouteContext(sp, contextId: "echo-worker");
        ctx.AddService(typeof(ILoggerFactory), sp.GetRequiredService<ILoggerFactory>());
        EchoModule.InitRoute.main(ctx);       // <- the exact method the Tsak worker calls

        await ctx.Start();

        Console.WriteLine();
        Console.WriteLine("EchoWorker running: http://localhost:5099/api/notes");
        Console.WriteLine("  POST  {\"tag\":\"work\",\"text\":\"hello\"}   -> save");
        Console.WriteLine("  GET   ?tag=work                          -> list by tag");
        Console.WriteLine("Ctrl+C to exit.");
        Console.WriteLine();

        var stop = new ManualResetEventSlim();
        Console.CancelKeyPress += (_, e) => { e.Cancel = true; stop.Set(); };
        stop.Wait();

        await ctx.DisposeAsync();
    }

    // Walk up from the app dir to the repo's built Free SQLite native extension.
    // Returns null when running from a packaged worker (it resolves the extension itself).
    private static string? ResolveNativeExtension()
    {
        var suffix = OperatingSystem.IsWindows() ? ".dll"
                   : OperatingSystem.IsMacOS()   ? ".dylib"
                   : ".so";
        for (var dir = new DirectoryInfo(AppContext.BaseDirectory); dir != null; dir = dir.Parent)
        {
            var candidate = Path.Combine(dir.FullName, "redb.SQLite", "native", "build", "redb" + suffix);
            if (File.Exists(candidate))
                return candidate;
        }
        return null;
    }
}

Step by step:

1. The SQLite native extension. On its Free tier, redb-on-SQLite uses a native loadable extension (redb.dll / .so / .dylib) — part of the query machinery lives in there. The packaged Tsak worker ships that extension in the box. When you run from source, you have to point at the built binary — ResolveNativeExtension() just walks up the directory tree looking for redb.SQLite/native/build/redb.dll. One honest detail worth not hiding: without that extension, the Free SQLite provider won't start.

2. DI and the database. A regular ServiceCollection: console logging plus AddRedb(...).UseSqlite("Data Source=echo_demo.db"). UseSqlite is tier-agnostic: AddRedb gives you Free, AddRedbPro gives you Pro — you flip tiers without touching the usings. And this is the exact same tier (Free/SQLite) the Tsak worker runs by default, so your debug environment matches production.

3. System tables. InitializeAsync(ensureCreated: true) creates redb's base tables on a fresh file. In Tsak the worker does this on boot; in the debug host, we do it.

4. The context and the module call. We build a RouteContext over our provider and call EchoModule.InitRoute.main(ctx). That's the exact entry point Tsak will call. No route code is duplicated — it all lives in the module.

5. Start and wait. ctx.Start() brings up the HTTP server on 5099; then we sit until Ctrl+C.

The project files

EchoModule/EchoModule.csproj — a library plus a .tpkg packaging target:

<Project Sdk="Microsoft.NET.Sdk">

  <!-- Project 1 of 2: the Tsak MODULE.
       A class library. Its DLL is what gets packed into EchoModule.tpkg and
       hot-loaded by the Tsak worker. It contains ONLY route code — no host,
       no DB provider: the worker supplies redb + SQLite at runtime. -->
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <RootNamespace>EchoModule</RootNamespace>
    <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
  </PropertyGroup>

  <!-- The connectors the worker already ships in its shared Libs. We compile
       against them but the .tpkg carries only EchoModule.dll (see PackTpkg). -->
  <ItemGroup>
    <ProjectReference Include="..\..\..\src\redb.Route\redb.Route.csproj" />
    <ProjectReference Include="..\..\..\src\redb.Route.Core\redb.Route.Core.csproj" />
    <ProjectReference Include="..\..\..\src\redb.Route.Http\redb.Route.Http.csproj" />
    <ProjectReference Include="..\..\..\..\redb.Core\redb.Core.csproj" />
  </ItemGroup>

  <!-- After build: zip manifest.json + the module DLL into output/EchoModule.tpkg. -->
  <PropertyGroup>
    <TsakModuleName>EchoModule</TsakModuleName>
  </PropertyGroup>
  <Target Name="PackTpkg" AfterTargets="Build">
    <PropertyGroup>
      <_TpkgStaging>$(IntermediateOutputPath)tpkg</_TpkgStaging>
      <_TpkgFile>$(MSBuildThisFileDirectory)output\$(TsakModuleName).tpkg</_TpkgFile>
    </PropertyGroup>
    <RemoveDir Directories="$(_TpkgStaging)" />
    <MakeDir Directories="$(_TpkgStaging)" />
    <MakeDir Directories="$(MSBuildThisFileDirectory)output" />
    <Copy SourceFiles="$(MSBuildThisFileDirectory)manifest.json" DestinationFolder="$(_TpkgStaging)" />
    <Copy SourceFiles="$(TargetPath)" DestinationFolder="$(_TpkgStaging)" />
    <!-- {ModuleName}.config.json gives the module a named context (ContextName). -->
    <Copy SourceFiles="$(MSBuildThisFileDirectory)$(TsakModuleName).config.json"
          DestinationFolder="$(_TpkgStaging)"
          Condition="Exists('$(MSBuildThisFileDirectory)$(TsakModuleName).config.json')" />
    <ZipDirectory SourceDirectory="$(_TpkgStaging)" DestinationFile="$(_TpkgFile)" Overwrite="true" />
    <Message Importance="high" Text="Packed $(TsakModuleName) -> $(_TpkgFile)" />
  </Target>

</Project>

EchoWorker/EchoWorker.csproj — a console exe that references the module:

<Project Sdk="Microsoft.NET.Sdk">

  <!-- Project 2 of 2: the DEBUG HOST.
       A tiny console app. It stands redb up on SQLite (the same Free tier the Tsak
       worker uses by default), then calls EchoModule.InitRoute.main(ctx) — the exact
       method the worker calls. Run/F5 this to debug the route without Tsak. -->
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <RootNamespace>EchoWorker</RootNamespace>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\EchoModule\EchoModule.csproj" />
    <!-- UseSqlite is tier-agnostic: AddRedb -> Free (what Tsak uses by default). -->
    <ProjectReference Include="..\..\..\..\redb.SQLite.Pro\redb.SQLite.Pro.csproj" />
    <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="10.0.3" />
  </ItemGroup>

</Project>

There's an important detail in the dependencies. The debug host references the SQLite provider (redb.SQLite.Pro) — because it stands up the database. The module itself does not reference any DB provider: in Tsak, the worker provides the database. So the .tpkg only ships EchoModule.dll (see the PackTpkg target — it puts exactly the target DLL, the manifest, and the config into the archive, not the dependencies). The redb.Route.* and redb.Core connectors are already in the worker, which is why the package stays tiny.

Run it and poke it

dotnet run --project EchoWorker

Then, in another window, hit the endpoints. One Windows wrinkle worth calling out: escaping JSON for curl differs between cmd and PowerShell. In PowerShell the \" form does not work — you'll get '\' is an invalid start of a property name. So here's both.

cmd.exe (JSON in double quotes, inner ones escaped with \"):

curl -X POST http://localhost:5099/api/notes -H "Content-Type: application/json" -d "{\"tag\":\"work\",\"text\":\"hello\"}"
curl "http://localhost:5099/api/notes?tag=work"

PowerShell (wrap the JSON in single quotes — no escaping of the inner double quotes; and it must be curl.exe, since curl is an alias for Invoke-WebRequest):

curl.exe -X POST http://localhost:5099/api/notes -H "Content-Type: application/json" -d '{"tag":"work","text":"hello"}'
curl.exe -X POST http://localhost:5099/api/notes -H "Content-Type: application/json" -d '{"tag":"home","text":"other"}'
curl.exe "http://localhost:5099/api/notes?tag=work"

PowerShell, no curl (native):

Invoke-RestMethod -Method Post -Uri http://localhost:5099/api/notes -ContentType 'application/json' -Body '{"tag":"work","text":"hello"}'
Invoke-RestMethod "http://localhost:5099/api/notes?tag=work"

The responses:

{"saved":true,"id":1000019}
{"saved":true,"id":1000022}
[{"Tag":"work","Text":"hello"}]

A GET with ?tag=home returns the other note, and PUT /api/notes gives you a 405. It all works, and it's all under the debugger: drop a breakpoint inside ProcessWithRedb, fire a curl, and you're sitting right in the handler with a live db and ex.

That's the debug zone: a plain console app, F5, breakpoints, a live SQLite file next to the exe, raw logs to stdout. This is where you write and debug your routes. Iteration loop: "tweak → run → poke with curl."

Here's the trick: the same code, now enterprise

Now for the good part. We don't touch the routes at all. We take the same EchoModule.dll, add two tiny descriptor files, pack it into a .tpkg, and hand it to Tsak. One step — and our "console app under F5" gains a dashboard, metrics, hot-reload, and live management. New code written: zero.

What a `.tpkg` is

A .tpkg is just a ZIP with three things:

manifest.json — the module's passport;
EchoModule.dll — the assembly with InitRoute.main;
EchoModule.config.json — the module's config (first and foremost, its context name).

manifest.json:

{
  "Name": "EchoModule",
  "Version": "1.0.0",
  "EntryPoints": ["EchoModule.dll"],
  "Dependencies": []
}

EchoModule.config.json:

{
  "ContextName": "echo",
  "AutoStart": true
}

A word on ContextName, because it's an easy trap. If you don't set it, Tsak loads the module into an anonymous context with an auto-generated name (something like EchoModule_dyn_<date>_<guid>). The module runs fine, the routes work — but the dashboard's Endpoints page hides anonymous contexts by default (while still counting them in the totals, so the numbers won't match what you see in the list). The takeaway is simple: name your context via EchoModule.config.json, and it shows up neatly as echo. Small thing, big peace of mind.

Pack it

The PackTpkg target in the .csproj does everything at build time:

dotnet build EchoModule -c Debug

Out comes EchoModule/output/EchoModule.tpkg. Peek inside:

Archive:  output/EchoModule.tpkg
  Length      Name
---------  ----
       49  EchoModule.config.json
    13312  EchoModule.dll
      108  manifest.json

Three files, ~7 KB. That's your deployment artifact.

How Tsak finds modules: folders and hot-reload

This is the part the whole thing was built for. Tsak doesn't "watch" the folder with filesystem events — internally there's a background HotReloadService that polls the directories listed in the Tsak:Modules:AssemblyPaths config on a timer.

The flow:

The worker config has a list of paths, Tsak:Modules:AssemblyPaths. The module folder is usually called modules.
Every Tsak:HotReload:ScanIntervalSeconds (default 10 seconds) the service walks each path and grabs every *.tpkg (and bare *.dll too).
"New / changed / removed" is decided by file modification time:
- unchanged mtime → skip;
- new file → unzip it, load the assembly into an isolated load context (its own AssemblyLoadContext per package), find InitRoute.main by reflection, bring the context up;
- changed file → reload the package atomically (drop the old version, load the new one, preserving state such as whether the context was running);
- file gone from disk → unload every module in that package.
Shared connectors (redb.Route.*, redb.Core) resolve from the worker's shared libraries (Libs/shared), which is why they're not inside the .tpkg.

The practical upshot:

Drop or update EchoModule.tpkg in modules/ and it gets picked up within ~10 seconds, no restart.
The trigger is the file's mtime. A plain copy bumps the mtime, so "re-copied" = "reloaded."
Each .tpkg lives in its own load context — module versions are isolated from each other.

In other words, deploying a new module (or a new version) is copying one file into a folder. Tsak takes it from there.

The dashboard: watch it, and run it

Stand Tsak up (two ways below), drop EchoModule.tpkg into the modules folder, wait a few seconds, and open the web dashboard. Our echo context is right there, with its two endpoints.

And here's the second big difference from the debug console. In the console we only had text logs. In Tsak it's the same information, but:

you see the echo context and its endpoints — type (HTTP), role (Consumer), in/out counters, errors, throughput, uptime, health;
you see the _SYSTEM context — that's the worker's own management API;
you can drill into each endpoint for details (messages, bytes, average processing time, last errors).

But the real point is that you can operate it, right from the browser, without touching configs or redeploying. On the node detail page for our echo context you get:

the context as a whole — Start / Stop / Restart, plus Reset route states (clear the saved route states);
individual routes — stop/start a specific notes-post or notes-get without touching its neighbor;
schedules (if the module has Quartz jobs) — pause and resume jobs on the scheduler tab.

And here's the important bit: state sticks. If you manually stop a route, then hot-reload will not bring it back up when the package updates — Tsak respects the operator's decision. A route you stopped in production won't suddenly come back to life just because you rolled out a new .tpkg version. Management is both "hot" (takes effect immediately) and "sticky" (survives a module reload).

The management actions live behind the admin role — so this is genuinely an operator's console, not just a metrics wall.

Feel the contrast: in the custom worker you debug (F5, breakpoints, a bare console); in Tsak you operate (observe, manage, deploy). Same code, two environments, two very different jobs.

Ports: defaults, and how to set them

Since we're running this across different environments, let's put the ports on the table — it's easy to get lost in what lives where.

The module (our routes) — 5099. That's the port we wrote into From("http:0.0.0.0:5099/..."). The module's own HTTP server. Want a different one? Change it in the route.
The worker (Tsak management API) — 9090. A separate server: health, metrics, context management, the cluster API. This is what the dashboard talks to. The port comes from the worker config.
The web dashboard — pay attention here. If neither ASPNETCORE_URLS nor a Kestrel binding is set in the web config, ASP.NET Core falls back to its default — http://localhost:5000. The Docker images and the distribution's startup scripts set ASPNETCORE_URLS=http://localhost:8080 (or http://+:8080 in a container), which is why the dashboard is on 8080 under Docker and in the docs. Run the web "bare" without that variable and don't be surprised to find the UI on 5000.

To set it explicitly:

# before launching the web
$env:ASPNETCORE_URLS = "http://localhost:8080"

or in the web's appsettings.json:

"Kestrel": { "Endpoints": { "Http": { "Url": "http://localhost:8080" } } }

Cheat sheet: 9090 — worker API, 5099 — our endpoints, 8080 — dashboard (when ASPNETCORE_URLS is set; otherwise the framework default 5000).

Enterprise deploy #1: Docker (the whole stack in one container)

The simplest way to bring it all up at once is the redb-tsak-stack image: worker + dashboard in a single container. The images live on the org's packages page — there are several: redb-tsak-worker, redb-tsak-web, and the combined redb-tsak-stack (plus per-TFM variants). For a quick start, stack is all we need. Here's the docker-compose.yml in full:

# Minimal redb.Tsak stack — Worker (API) + Blazor dashboard in one container.
# Drop a module as a .tpkg into ./modules and the worker hot-loads it.
#
# Start:
#   docker compose up -d
#
# Dashboard:   http://localhost:8080   (login admin / admin)
# Tsak API:    http://localhost:9090/api/health/live
# EchoModule endpoints:  http://localhost:5099/api/notes
#   POST (PowerShell): curl.exe -X POST http://localhost:5099/api/notes -H "Content-Type: application/json" -d '{"tag":"work","text":"hello"}'
#   POST (cmd.exe):    curl -X POST http://localhost:5099/api/notes -H "Content-Type: application/json" -d "{\"tag\":\"work\",\"text\":\"hello\"}"
#   GET:  curl.exe "http://localhost:5099/api/notes?tag=work"

services:
  tsak:
    image: ghcr.io/redbase-app/redb-tsak-stack:latest
    container_name: tsak
    restart: unless-stopped
    ports:
      - "8080:8080"   # Blazor dashboard
      - "9090:9090"   # Tsak management REST API (health, cluster, contexts...)
      - "5099:5099"   # the EchoModule's own HTTP server (/api/notes)
    environment:
      # redb store on the bundled SQLite — no external dependencies
      Tsak__Storage__Type: Redb
      # HMAC secret for API-key auth (any >=16 chars; change for real use)
      Tsak__Auth__Secret: "demo-secret-change-me-please-0123456789"
    volumes:
      # your .tpkg modules — hot-loaded by the worker
      - ./modules:/app/worker/modules

What matters here:

The image ghcr.io/redbase-app/redb-tsak-stack:latest — worker and dashboard in one container (under a supervisor). Storage defaults to the bundled SQLite, no external dependencies.
The ports — the same three: 8080 (dashboard), 9090 (worker API), 5099 (our endpoints).
The volume ./modules:/app/worker/modules — this is where the .tpkg goes. Inside the stack image the module folder is /app/worker/modules, which is exactly the path hot-reload watches.
Tsak__Auth__Secret — the HMAC secret for signing API keys; for a local run any value of 16+ chars will do.

Layout on the host:

tsak/
├─ docker-compose.yml
└─ modules/
   └─ EchoModule.tpkg

Bring it up:

docker compose up -d

Dashboard at http://localhost:8080 (admin / admin). Test the endpoints (PowerShell):

curl.exe -X POST http://localhost:5099/api/notes -H "Content-Type: application/json" -d '{"tag":"work","text":"hello"}'
curl.exe "http://localhost:5099/api/notes?tag=work"

That's it. The same module we debugged in a console now runs in a container with a dashboard. To update the module: rebuild the .tpkg, re-copy it into modules/, and it gets picked up in ~10 seconds.

Enterprise deploy #2: no container (standalone archive)

Don't want Docker? Fine. The releases page has self-contained archives per platform — for example, the v3.2.0 tag ships archives for win-x64, linux-x64, and so on (each is cosign-signed, with a .bundle and an SBOM alongside for integrity checks).

Inside an extracted archive (redb-tsak-<version>-<platform>), the layout is:

redb-tsak-3.2.0-win-x64/
├─ worker/     <- the runtime: redb.Tsak.Worker.exe (+ Libs/shared with connectors, + modules/)
├─ web/        <- the dashboard: redb.Tsak.Web.exe
├─ cli/        <- the tsak command-line tool
├─ scripts/    <- start-worker / start-web / start-stack (.bat / .ps1 / .sh)
├─ README.txt
├─ LICENSE, NOTICE

Launch from scripts/:

start-stack — bring up worker and dashboard together;
start-worker — just the runtime;
start-web — just the dashboard.

On Windows, for instance:

.\scripts\start-stack.ps1

Same ports: worker on 9090, dashboard on 8080 (the scripts set ASPNETCORE_URLS; run web completely bare, outside the script, and remember the 5000 default from the ports section).

Where the module goes. In the standalone layout, modules live next to the worker — in its modules/ folder (the path comes from Tsak:Modules:AssemblyPaths). Drop our EchoModule.tpkg there:

worker/
└─ modules/
   └─ EchoModule.tpkg

Leave Libs/shared alone — that's the distribution's shared connectors, the layer your lightweight package loads on top of.

Licensing: with no key, the runtime starts in OSS mode. Pro features (clustering included) turn on via the Tsak__Redb__License__0 environment variable with your JWT, or by editing worker/appsettings.json before launch.

So — two deployment paths, container or archive, but one model: the .tpkg artifact goes into the modules folder, and hot-reload takes it from there.

Two zones: build and operate

Let's put the whole picture together.

The build/debug zone — the EchoWorker project. A console app, F5, breakpoints, a local SQLite file next to the exe, raw logs to the console. This is where you write and debug routes. Loop: "tweak → run → poke with curl."
The operations zone — Tsak (Docker or archive). The same module, but with a dashboard, metrics, hot-reload, and live management. This is where you deploy and operate. Loop: "rebuild the .tpkg → copy into modules/ → picked up."

And the key thing: not a single line of the routes changes between those zones. InitRoute.main is the same. The only difference is the plumbing — in debug you write it (a dozen lines of Program.cs), in production Tsak provides it.

What's next: clustering (a teaser)

Everything above is single-node. But Tsak clusters too: multiple workers, one shared dashboard, modules and routes distributed across nodes, leader election, automatic takeover when a node dies — and the whole cluster topology lives in the redb database itself, with no separate membership infrastructure (no ZooKeeper/etcd/Consul). There's also active-passive for routes: the same route consumer runs on exactly one node, and if that node falls over, another one picks it up.

That's a topic for the next post, though. This one was the intro: how to knock out two routes in an evening, build yourself a debug worker, and then take the exact same code into an enterprise runtime. The coordinator, the leader, and failover — we'll get into those properly next time.

Wrap-up

We walked the whole path on one tiny example:

wrote two routes on redb.Route (POST to save into redb/SQLite, GET to fetch with a server-side Where(...).ToListAsync());
built our own debug worker — a console app under F5 that calls the same InitRoute.main;
packed the module into a .tpkg (DLL + manifest.json + a config.json with a context name);
watched Tsak pick it up on its own from the modules/ folder via hot-reload;
operated it from the dashboard (start/stop/restart of contexts and routes, with sticky state);
sorted out the ports (9090 — worker API, 5099 — our endpoints, 8080/5000 — dashboard);
deployed it two ways: with Docker (the whole docker-compose.yml) and without (an archive from the releases page).

One and the same codebase — comfortable to debug, and ready for an enterprise runtime. Clustering next.

The full project: redb.Route/demos/EchoWorkerDemo in the repo. Clone it, run it, break it.

Leaving MassTransit for a Camel state of mind: the Kafka connector, Scatter-Gather, and what really happens under a transaction

rinat kozin — Tue, 30 Jun 2026 20:37:22 +0000

Series: redb ecosystem

Part of the redb.Route series — the Apache Camel we built for .NET. If you're just tuning in:

redb.Route — Apache Camel for .NET: 22 transports, 30+ EIP patterns, compiled DSL — the origin story;

Enterprise Integration Patterns in .NET — Part 1: the four in-memory channels (and the Exchange they carry);

redb.Route 3.0.1 — flat DSL navigation, CRTP refactor, and a silent null fix;

Apache Camel for .NET, dissected: the HTTP connector with no ASP.NET MVC + the Content-Based Router pattern — the previous "EIP + connector" deep-dive.

This time we open with the Kafka connector — taken apart the same way we did HTTP — and then we mount two EIP patterns on top of it: Scatter-Gather and Aggregator. And the part tutorials skip: how the whole thing behaves once you wrap a transaction around it. Also, 3.2.0 shipped.

One spoiler up front

There's no "exactly-once out of the box" in Kafka here — and you'll see exactly why from the code below. What works and what doesn't — stated plainly.

next A real production example: one HTTP request → six parallel aggregations

Why leave MassTransit at all
What landed in 3.2.0
The Kafka connector: URI anatomy and the connection factory
The Kafka producer: what .To("kafka:...") actually does
The Kafka consumer: polling, batches, rebalance
Headers and tracing across the broker
Straight talk about transacted=true
EIP #1 — Scatter-Gather: one processor, both fan-out and join
EIP #2 — Aggregator: assembly over time
Transactions: two models, and that's the whole point
The parallel cousins: Splitter and Multicast
Saga — "a slightly different one"
Outbox — there isn't one, and that's correct
Bottom line: a trade, not "better/worse"

1. Why leave MassTransit at all

MassTransit is genuinely good, and I'm not here to bury it. But it's an opinionated framework: the durable state-machine saga, the transactional outbox, the retry policies — they're baked in, and you live by the framework's rules. When your scenario matches its worldview, it's a joy; everything "just works." When it doesn't, you're fighting an abstraction, spelunking through internals and bolting hacks onto someone else's decisions.

Apache Camel is a different school. The bedrock is EIP primitives + connectors + a DSL. Nobody gifts you an outbox as a feature — you get Splitter, Aggregator, Scatter-Gather, transactional transports, and you assemble exactly what your invariants need. Less magic, more explicit composition from bricks.

redb.Route sits in the second school. Hence the title: not "batteries included," but "here are the bricks, and they snap together predictably." The rest of the article is about what that trade costs you, and what you get back.

2. What landed in 3.2.0

Full notes are in the CHANGELOG. Two items matter here:

Parallel Splitter / Multicast branches now isolate the ambient transaction per branch. Each branch gets its own DependentTransaction.DependentClone(BlockCommitUntilComplete); the parent commit blocks until every branch signals done. Before this, parallel branches shared a single Transaction.Current, and System.Transactions forbids using one transaction concurrently across threads. We'll read this fix line by line and see why Scatter-Gather never needed it.
Throttle got an RFC 6585 mode — .RejectOnOverflow() (429 + Retry-After). Off-topic today, but handy if you front all of this with an HTTP edge.

All redb.Route.* packages are version-aligned at 3.2.0.

3. The Kafka connector: URI anatomy and the connection factory

We open with Kafka, as promised — and we open with the simplest thing there is: a string endpoint URI. Here's a minimal consumer and a minimal producer:

// Consumer: read topic 'orders', group 'order-workers', from the beginning
From("kafka:orders?brokers=kafka:9092&groupId=order-workers&autoOffsetReset=earliest")
    .Log("Got: ${body}")
    .To("direct:process");

// Producer: publish to 'notifications' with acks=all
From("direct:notify")
    .To("kafka:notifications?brokers=kafka:9092&acks=All");

The URI shape is kafka:<topic>?<query>. The topic comes from the path (KafkaEndpoint):

public KafkaEndpoint(EndpointUri uri, KafkaComponent component, KafkaEndpointOptions options)
    : base(uri, component, options)
{
    TopicName = uri.Path;                       // ← topic = URI path

    // If the URI says connectionFactory=<name>, resolve it from the registry
    if (!string.IsNullOrEmpty(options.ConnectionFactory) && component.Context is not null)
        ResolvedFactory = component.Context.GetFromRegistry<KafkaConnectionFactory>(options.ConnectionFactory);

    // No brokers in the URI but the factory has them — fill it in
    if (string.IsNullOrWhiteSpace(options.Brokers) && ResolvedFactory is not null)
        options.Brokers = ResolvedFactory.Brokers;
}

Note the last touch: on a consumer, groupId is mandatory, and forgetting it fails endpoint creation rather than blowing up later:

public override IConsumer CreateConsumer(IProcessor processor)
{
    if (string.IsNullOrWhiteSpace(Options.GroupId))
        throw new InvalidOperationException(
            $"The 'groupId' parameter is required for Kafka consumer on topic '{TopicName}'.");
    return new KafkaConsumer(this, processor, Options);
}

The connection factory — so you don't repeat yourself

When you've got twenty Kafka endpoints on one cluster, spelling out brokers=...&securityProtocol=...&saslMechanism=... in every URI is suicide. That's what KafkaConnectionFactory is for: register it in the registry under a name, then reference it via connectionFactory=name.

Its full parameter surface (all from source, nothing invented):

Group	Properties	Default
Brokers	`Brokers`	`localhost:9092`
Security	`SecurityProtocol`, `SaslMechanism`, `SaslUsername`, `SaslPassword`	`Plaintext`
SSL/TLS	`SslCaLocation`, `SslCertificateLocation`, `SslKeyLocation`, `SslKeyPassword`, `SslEndpointIdentificationAlgorithm`	—
Producer	`Acks`, `Retries`	`Leader`, `3`
Consumer	`GroupId`, `AutoOffsetReset`	—, `Latest`
Consumer tuning	`GroupInstanceId`, `SessionTimeoutMs`, `HeartbeatIntervalMs`, `MaxPollIntervalMs`, `PartitionAssignmentStrategy`, `IsolationLevel`	—
Producer tuning	`LingerMs`, `BatchSize`, `CompressionType`, `MessageTimeoutMs`	—
Reconnect	`ReconnectBackoffMs`, `ReconnectBackoffMaxMs`	—
Advanced	`ClientId`, `RequestTimeoutMs`, `MetadataMaxAgeMs`, `SocketTimeoutMs`, `MaxInFlight`, `AdditionalProperties`	`redb.Route`, 30000, 300000, 60000, 5

context.AddToRegistry("prod-cluster", new KafkaConnectionFactory
{
    Brokers          = "kafka1:9092,kafka2:9092,kafka3:9092",
    SecurityProtocol = "SaslSsl",
    SaslMechanism    = "ScramSha512",
    SaslUsername     = "svc-orders",
    SaslPassword     = secret,
    CompressionType  = "Zstd",
    MaxInFlight      = 5,
});

// Now the URI only carries what's endpoint-specific:
From("kafka:orders?connectionFactory=prod-cluster&groupId=order-workers");
To("kafka:notifications?connectionFactory=prod-cluster&acks=All");

The factory builds three configs — BuildConsumerConfig(), BuildProducerConfig(), BuildAdminConfig() (the last for topic-metadata queries). Endpoint-level options are applied on top of the factory (if (!string.IsNullOrWhiteSpace(Brokers)) config.BootstrapServers = Brokers; and so on), so the factory sets the baseline and the URI overrides it surgically.

The full endpoint option set

The complete list — KafkaEndpointOptions, grouped, with defaults:

Connection / security: brokers (required, or Validate() throws), securityProtocol (Plaintext/Ssl/SaslPlaintext/SaslSsl), saslMechanism/saslUsername/saslPassword, sslCaLocation/sslCertificateLocation/sslKeyLocation/sslKeyPassword, connectionFactory.

Consumer: groupId, autoOffsetReset (Latest/Earliest/Error, default Latest), enableAutoCommit (default true, framework-level — since 3.2.1), maxPollRecords (0 = single mode, >0 = batch), pollTimeoutMs (1000), breakOnFirstError, seekTo (beginning/end), topicIsPattern, groupInstanceId, sessionTimeoutMs, heartbeatIntervalMs, maxPollIntervalMs, partitionAssignmentStrategy (Range/RoundRobin/CooperativeSticky), isolationLevel (ReadUncommitted/ReadCommitted).

Producer: acks (None/Leader/All, default Leader), retries (3), recordMetadata, key, partitionNumber, transacted, transactionIdPrefix (redb-kafka).

Producer tuning: lingerMs, batchSize, compressionType (None/Gzip/Snappy/Lz4/Zstd), messageTimeoutMs.

Advanced: additionalProperties — arbitrary librdkafka properties, applied last, overriding everything typed.

Validate() checks exactly: brokers non-empty, maxPollRecords >= 0, pollTimeoutMs >= 0, retries >= 0. Everything else has a default or is optional.

One thing to get precise — about the offset commit, and it matters. At the librdkafka level, EnableAutoCommit is hard-wired to false always — the library never commits on a background timer (which would commit un-processed offsets). From BuildConsumerConfig:

var cfg = new ConsumerConfig
{
    BootstrapServers = Brokers,
    GroupId          = GroupId,
    AutoOffsetReset  = ParseAutoOffsetReset(),
    EnableAutoCommit = false,   // librdkafka level: always manual commit
};

But there is a commit — one level up, at the framework level. As of 3.2.1 the consumer has a typed EnableAutoCommit option (default true): after a successful Process it commits the offset inline — exactly like the RabbitMQ consumer acks after processing. Set it from the URI (?enableAutoCommit=false) or fluently (.EnableAutoCommit(false)). A transactional route takes precedence: if a .Transacted() already committed the offset, the inline path is skipped. The mechanics are in §5.

The same thing, fluent

String URIs are great for short snippets and config files. In code you usually build endpoints fluently — Kafka.Topic(...):

From(Kafka.Topic("orders")
        .Brokers("kafka1:9092,kafka2:9092")
        .GroupId("order-workers")
        .AutoOffsetReset("Earliest")
        .MaxPollRecords(500)
        .PartitionAssignmentStrategy("CooperativeSticky")
        .IsolationLevel("ReadCommitted")
        .SessionTimeout(30_000)
        .MaxPollInterval(300_000));

To(Kafka.Topic("notifications")
        .Brokers("kafka1:9092")
        .Acks("All")
        .Compression("zstd")
        .Linger(20)
        .BatchSize(64 * 1024)
        .Key("${header.orderId}"));   // partition key — an expression

The fluent builder just assembles the same query string (Kafka.Topic("orders").Brokers(...)...Build() → "kafka:orders?brokers=...&..."), URL-encoding the values. The setters take an IExpression, but options resolve at different times: the producer key is evaluated as a ${...} expression per message (in DetermineKey at send time — see below), whereas connection-level options (brokers, credentials) are resolved once on connect, where there's no exchange yet, so an expression there is meaningless. The per-message story is specifically the partition key.

4. The Kafka producer: what `.To("kafka:...")` actually does

Now let's read what KafkaProducer really does when a message hits .To("kafka:..."). It's a ConnectableProducer, so it requires Start() first (EnsureStarted() at the top of Process).

Connect

protected override Task ConnectAsync(CancellationToken ct)
{
    var config = _options.BuildProducerConfig(_endpoint.ResolvedFactory);

    _producer = new ProducerBuilder<string, byte[]>(config)
        .SetValueSerializer(Serializers.ByteArray)
        .SetErrorHandler((_, e) =>
            Logger?.LogError("Kafka producer error: {Reason} (Code: {Code})", e.Reason, e.Code))
        .Build();

    if (_options.Transacted)
    {
        _producer.InitTransactions(TimeSpan.FromSeconds(30));
        Logger?.LogInformation("Kafka transactional mode enabled: topic={Topic}", _endpoint.TopicName);
    }
    return Task.CompletedTask;
}

Key is string, value is byte[]. On disconnect it does Flush(30s) before Dispose so buffered messages aren't lost.

Preparing the message

PrepareMessage turns the exchange body into a Message<string, byte[]>:

byte[] valueBytes = body switch
{
    byte[] bytes => bytes,                                  // already bytes — as-is
    string str   => Encoding.UTF8.GetBytes(str),            // string → UTF-8
    null         => Array.Empty<byte>(),                    // null → empty
    _            => Encoding.UTF8.GetBytes(body.ToString() ?? string.Empty)  // else → ToString → UTF-8
};

Then headers. ContentType rides as a content-type header, and the exchange's user headers move into Kafka headers — except the internal redbKafka.* ones, which are filtered out:

foreach (var (key, value) in exchange.In.Headers)
{
    if (KafkaHeaders.IsRedbHeader(key))   // redbKafka.* are internal — don't propagate
        continue;
    msg.Headers.Add(key, Encoding.UTF8.GetBytes(value?.ToString() ?? string.Empty));
}

The partition key

DetermineKey — three branches, in priority order:

private string? DetermineKey(IExchange exchange)
{
    // 1. Explicit partition → no key (partitioner is bypassed)
    if (_options.PartitionNumber.HasValue)
        return null;

    // 2. Key from the option — supports ${...} expressions, resolved per message
    if (!string.IsNullOrWhiteSpace(_options.Key))
    {
        var resolved = _options.ResolveOption(_options.Key, exchange);
        if (!string.IsNullOrEmpty(resolved)) return resolved;
    }

    // 3. Otherwise — keyless (round-robin across partitions)
    return null;
}

So key=${header.orderId} means "partition by orderId" — all events for one order land in one partition and keep their order.

Send: immediate vs deferred

Here's the fork that matters for transactions:

if (_options.Transacted)
{
    // Deferred send — the real publish happens when the route transaction commits
    var action = new KafkaSendAction(_producer, _endpoint.TopicName, message,
        _options.PartitionNumber, _options.RecordMetadata, exchange, Logger);
    RegisterTransactedAction(exchange, $"kafka-send-{Guid.NewGuid():N}", action);
}
else
{
    // Immediate send
    var result = _options.PartitionNumber.HasValue
        ? await _producer.ProduceAsync(new TopicPartition(_endpoint.TopicName,
              new Partition(_options.PartitionNumber.Value)), message, ct)
        : await _producer.ProduceAsync(_endpoint.TopicName, message, ct);

    if (_options.RecordMetadata)
        AddDeliveryMetadata(exchange, result);   // redbKafka.Sent.Topic/Partition/Offset/Timestamp
}

In transactional mode the producer doesn't send right away — it parks a KafkaSendAction in the deferred-action bag under a unique key kafka-send-{guid}. The real ProduceAsync happens later, at the .Transacted() boundary. More on that below.

KafkaSendAction clones the message at construction (a deep header copy via Buffer.BlockCopy) so the deferred send doesn't depend on what happens to the exchange afterwards:

public async Task Commit(CancellationToken ct = default)
{
    var result = _partition.HasValue
        ? await _producer.ProduceAsync(new TopicPartition(_topicName, new Partition(_partition.Value)), _message, ct)
        : await _producer.ProduceAsync(_topicName, _message, ct);
    if (_recordMetadata) { /* write the Sent.* headers */ }
}

public Task Rollback(CancellationToken ct = default)
{
    // The message is simply discarded — nothing was published
    return Task.CompletedTask;
}

Tracing across the broker

Before sending, the producer injects W3C trace context (traceparent/tracestate) into Kafka headers via the standard DistributedContextPropagator:

var propagator = DistributedContextPropagator.Current;
propagator.Inject(activity, headers, static (carrier, key, value) =>
{
    if (carrier is Headers h && !string.IsNullOrEmpty(value))
    {
        h.Remove(key);
        h.Add(key, Encoding.UTF8.GetBytes(value));
    }
});

The consumer on the other end lifts it back out — and your trace shows an unbroken chain across the broker. Zero configuration on your side.

5. The Kafka consumer: polling, batches, rebalance

KafkaConsumer is a DrainableConsumer (it can gracefully drain in-flight messages on stop). Step by step.

Start: subscribe/assign, seek, metadata

protected override Task OnStarting(CancellationToken ct)
{
    var config = _options.BuildConsumerConfig(_endpoint.ResolvedFactory);

    _consumer = new ConsumerBuilder<string, byte[]>(config)
        .SetValueDeserializer(Deserializers.ByteArray)
        .SetErrorHandler((_, e) => { /* fatal → LogError, else LogWarning */ })
        .SetPartitionsAssignedHandler((c, partitions) => { /* log assigned */ })
        .SetPartitionsRevokedHandler((c, partitions) =>
        {
            // Commit current offsets before partitions are revoked
            try { c.Commit(partitions); }
            catch (KafkaException) { /* nothing to commit — fine */ }
        })
        .SetPartitionsLostHandler((_, partitions) => { /* log involuntary loss */ })
        .Build();

    if (_options.PartitionNumber.HasValue)
        _consumer.Assign(new[] { new TopicPartition(_endpoint.TopicName, new Partition(_options.PartitionNumber.Value)) });
    else
        _consumer.Subscribe(_endpoint.TopicName);

    HandleSeekTo();        // seekTo=beginning/end on first start
    LogTopicMetadata();    // dump: partitions, leaders, replicas, ISR
    return Task.CompletedTask;
}

Two membership modes: Subscribe(topic) (dynamic group assignment + rebalance) or an explicit Assign(partition) when partitionNumber is set (static assignment, no group rebalance).

LogTopicMetadata spins up an AdminClient at start and logs the topic topology — partition count, each partition's leader, replicas, ISR. Handy for "why did I only get assigned 2 of 6 partitions" debugging.

The poll loop

RunAsync kicks off a long-running task with the poll loop:

private async Task PollLoop(CancellationToken pollCt, CancellationToken processingCt)
{
    while (!pollCt.IsCancellationRequested)
    {
        try
        {
            if (_options.MaxPollRecords > 0)
                await ProcessBatch(pollCt, processingCt);     // batch mode
            else
                await ProcessSingleMessage(pollCt, processingCt);  // one at a time
        }
        catch (OperationCanceledException) { break; }
        catch (Exception ex)
        {
            Logger?.LogError(ex, "Error in Kafka poll loop for topic {Topic}", _endpoint.TopicName);
            try { await Task.Delay(1000, pollCt); } catch (OperationCanceledException) { break; }
        }
    }
}

Caught an exception in the loop? Log it, wait a second, carry on (one bad message doesn't kill the consumer).

Single mode

private async Task ProcessSingleMessage(CancellationToken pollCt, CancellationToken processingCt)
{
    var result = _consumer!.Consume(pollCt);
    if (result?.Message is null) return;

    var exchange = CreateExchange(result);
    IncrementInflight();
    try
    {
        // Register the offset commit as a deferred action — for the transactional-route case.
        var commitAction = new KafkaCommitAction(_consumer, result, Logger);
        RegisterTransactedAction(exchange, $"kafka-commit-{result.Offset.Value}", commitAction);

        await Processor.Process(exchange, processingCt);
        ProcessedCount++;

        // 3.2.1: auto-commit after success — unless a transaction already committed it (Committed flag).
        if (_options.EnableAutoCommit && !commitAction.Committed)
            await commitAction.Commit(processingCt);
    }
    finally
    {
        await exchange.DisposeAsync();
        DecrementInflight();
    }
}

The key detail: the consumer registers a KafkaCommitAction before processing. So the offset isn't committed immediately — it commits when the route transaction commits, alongside any deferred sends. If processing throws, the offset isn't committed and the message comes back.

KafkaCommitAction.Commit is a plain _consumer.Commit(result):

public Task Commit(CancellationToken ct = default)
{
    _consumer.Commit(_result);   // ← plain offset commit, NOT SendOffsetsToTransaction
    return Task.CompletedTask;
}
public Task Rollback(CancellationToken ct = default) => Task.CompletedTask;  // no commit → message is re-read

Batch mode

With maxPollRecords > 0, the consumer collects up to maxPollRecords records, or until the pollTimeoutMs deadline, and hands them off as one exchange whose body is a List<IMessage>:

while (batch.Count < _options.MaxPollRecords && DateTime.UtcNow < deadline && !pollCt.IsCancellationRequested)
{
    var result = _consumer!.Consume(TimeSpan.FromMilliseconds(100));
    if (result?.Message is not null) batch.Add(result);
}
if (batch.Count == 0) return;

var exchange = CreateBatchExchange(batch);   // Body = List<IMessage>, redbKafka.BatchSize = N
// Commit only the last offset of the batch
var last = batch[^1];
RegisterTransactedAction(exchange, $"kafka-batch-commit-{last.Offset.Value}", new KafkaCommitAction(_consumer!, last, Logger));
await Processor.Process(exchange, processingCt);

Subtlety: only the last offset is committed (Kafka offsets are monotonic per partition, so committing the last covers the whole batch). Downstream you can .Split(body => body) and handle each message individually — but the commit is still one per batch.

How the exchange gets its metadata

CreateExchange sets the body (byte[]), transfers Kafka headers (UTF-8 decoded), restores ContentType, and stamps metadata:

message.Headers[KafkaHeaders.Topic]     = result.Topic;
message.Headers[KafkaHeaders.Partition] = result.Partition.Value;
message.Headers[KafkaHeaders.Offset]    = result.Offset.Value;
if (result.Message.Timestamp.Type != TimestampType.NotAvailable)
    message.Headers[KafkaHeaders.Timestamp] = result.Message.Timestamp.UtcDateTime;
if (!string.IsNullOrEmpty(result.Message.Key))
    message.Headers[KafkaHeaders.Key] = result.Message.Key;

var exchange = Exchange.Create(message, _endpoint.ScopeFactory);
exchange.Pattern = ExchangePattern.InOnly;   // a consumer is InOnly

What the consumer does while a message travels the route

Let's walk ProcessSingleMessage step by step, because it also explains the commit story:

Consume(pollCt) — pulled one record (in single mode the poll is blocking: the next record isn't pulled until the current one finishes);
CreateExchange — built the exchange;
IncrementInflight() — marked the message in-flight (this is what DrainableConsumer needs for a graceful stop: on shutdown it drains all in-flight messages);
registered a KafkaCommitAction in TRANSACT_ACTION — not committed yet;
await Processor.Process(exchange) — ran the message through the whole route (synchronously awaited);
ProcessedCount++;
if EnableAutoCommit (default true) and the offset wasn't already committed by a transaction — commits it inline right here;
finally: exchange.DisposeAsync() + DecrementInflight().

The key point: by default (EnableAutoCommit=true, since 3.2.1) the consumer commits the offset inline after a successful Process — at-least-once, just like RabbitMQ. The KafkaCommitAction registered in TRANSACT_ACTION is for the other case — when a transaction should own the commit: then .Transacted() commits it at its boundary, and the action's Committed flag stops the consumer from committing it a second time inline.

Batch mode is the same, except Process gets a single exchange whose body is a List<IMessage>, and the last offset of the batch is committed (inline or by the transaction).

How the offset commits: default vs transactional mode

As of 3.2.1 the default is simple and matches RabbitMQ: process it, commit it.

// ✅ Default (EnableAutoCommit=true): the offset commits inline after a successful Process.
//    A plain consumer needs no configuration — at-least-once out of the box.
From("kafka:orders?brokers=kafka:9092&groupId=w")
    .To("direct:process");

Transactional mode is for when the offset must commit together with other work (deferred sends to Kafka/Redis, a redb write) — atomically at the route boundary. Turn auto-commit off and wrap it in a transaction; the offset commit becomes part of the TRANSACT_ACTION batch.

// ✅ Transactional: the offset + deferred sends commit together at the .Transacted() boundary.
//    enableAutoCommit=false → no inline commit; the transaction owns the offset.
From("kafka:orders?brokers=kafka:9092&groupId=w&enableAutoCommit=false")
    .Transacted()
        .To("kafka:orders.done?brokers=kafka:9092&transacted=true")
    .EndTransaction();

// ✅ Imperative — the same via an explicit commit.
From("kafka:orders?brokers=kafka:9092&groupId=w&enableAutoCommit=false")
    .BeginTransaction()
    .To("direct:process")
    .CommitTransaction();

If you leave enableAutoCommit=true (the default) AND wrap in .Transacted(), the transaction wins: it commits the offset at the boundary, and the Committed flag on KafkaCommitAction stops the consumer from duplicating the commit inline. So inside a transactional route the option is effectively ignored.

By the way, in the redb.Route.Demo/Routes demos Kafka is used only as a producer (.WireTap(KafkaWireTap) to the demo-audit topic in MainPipelineRoutes.cs); there's no consumer there — so the production consume-process-produce pattern is in the transactions section.

6. Headers and tracing across the broker

The full header reference — KafkaHeaders. They all share the redbKafka. prefix:

Header	Set by	Meaning
`redbKafka.Topic`	consumer	topic of the consumed record
`redbKafka.Partition`	consumer	partition
`redbKafka.Offset`	consumer	offset in the partition
`redbKafka.Timestamp`	consumer	record timestamp
`redbKafka.Key`	consumer	key (if present)
`redbKafka.BatchSize`	consumer	batch size (batch mode)
`redbKafka.Sent.Topic`	producer	topic sent to (with `recordMetadata`)
`redbKafka.Sent.Partition`	producer	destination partition
`redbKafka.Sent.Offset`	producer	assigned offset
`redbKafka.Sent.Timestamp`	producer	send time

In a route you reach them as ${header.redbKafka.Offset}:

From("kafka:orders?brokers=kafka:9092&groupId=w")
    .Log("offset=${header.redbKafka.Offset} partition=${header.redbKafka.Partition} key=${header.redbKafka.Key}");

On re-publish these redbKafka.* headers are not propagated into the outgoing Kafka message (the IsRedbHeader filter in the producer) — so one hop's metadata doesn't leak into the next.

7. Straight talk about `transacted=true`

This is where marketing wants to say "exactly-once." Let's read the code with no spin.

What transacted=true does (from BuildProducerConfig):

if (Transacted)
{
    config.EnableIdempotence = true;
    config.Acks              = Acks.All;   // required for the idempotent producer
}

That's it: no transactional.id, and InitTransactions / BeginTransaction / CommitTransaction / SendOffsetsToTransaction appear nowhere. None of librdkafka's transactional API is in play.

What that means in practice:

"transacted" here = an idempotent producer (EnableIdempotence=true, dedup of retries within the session) + a deferred send (via KafkaSendAction, real ProduceAsync at the route's transaction boundary);
this is not Kafka EOS over consume-process-produce: there's no atomic Kafka transaction via SendOffsetsToTransaction;
a crash between the send and the offset commit yields a duplicate on restart (at-least-once), not exactly-once.

So the honest phrasing is "idempotent + route-level deferred commit," not exactly-once. For most needs — "don't lose the message, don't commit the offset before the work is done" — that's enough; true read-process-write EOS (BeginTransaction / SendOffsetsToTransaction / CommitTransaction) is a separate story, and it isn't here.

Apache Camel, by the way, doesn't give you EOS via transacted() either: it's auto-commit by default + a manual-commit hook (KafkaManualCommit) + an idempotent repository for dedup — the same model. So this isn't "Kafka-lite" — it's the same honest trade a mature integration framework makes.

With Kafka taken apart, we can put EIP patterns on it.

8. EIP #1 — Scatter-Gather: one processor, both fan-out and join

Classic Scatter-Gather from Hohpe/Woolf is "broadcast a request to N recipients and gather their responses into one." In redb.Route it's a single processor, ScatterGatherProcessor, whose aggregator is mandatory and whose parallelism is on by default.

The most stringly-typed shape — Kafka in, fan out to three services, fold, publish the result:

From("kafka:orders.incoming?brokers=kafka:9092&groupId=enricher&autoOffsetReset=earliest")
    .RouteId("order-enrich")
    .ScatterGather(
        // (accumulated, current) → merged. Called pair-wise.
        aggregationStrategy: (acc, cur) =>
        {
            var merged = (acc.In.Headers.TryGetValue("merged", out var m) ? m as string : "") ?? "";
            acc.In.Headers["merged"] = merged + cur.In.Body;
            return acc;
        },
        "http://pricing:8080/quote",
        "http://inventory:8080/check",
        "http://fraud:8080/score")
    .To("kafka:orders.enriched?brokers=kafka:9092&acks=All");

ℹ️ No transaction here, and that's fine: by default (3.2.1) the inbound offset commits inline after successful processing. You only need a transaction for an atomic "commit-offset + publish-result" coupling — then enableAutoCommit=false + .Transacted() (see §5).

A realistic note about Kafka. Scatter-Gather gathers responses, so its natural fan-out targets are request/reply endpoints: HTTP, gRPC, SQL SELECT. A Kafka producer is fire-and-forget — there's nothing to "gather" beyond delivery metadata. So Kafka lives at the edges here: source (From("kafka:...")) and sink (To("kafka:...")), while the fan-out targets services. That's how it shakes out in production.

Under the hood: the parallel path

private async Task ProcessParallel(IExchange exchange, IReadOnlyList<string> recipients, CancellationToken ct, CancellationToken callerCt)
{
    var clones = new IExchange?[recipients.Count];
    var maxDop = _maxDegreeOfParallelism > 0 ? _maxDegreeOfParallelism : Environment.ProcessorCount;
    using var semaphore = new SemaphoreSlim(maxDop);

    async Task<IExchange> SendToRecipient(int index)
    {
        await semaphore.WaitAsync(ct);
        try
        {
            var clone = exchange.Clone();                 // ← Clone(): Properties copied shallowly
            clones[index] = clone;
            var producer = GetOrCreateProducer(recipients[index]);  // per-URI producer cache
            await producer.Process(clone, ct);
            return clone;
        }
        finally
        {
            if (clones[index] != null)
                await clones[index]!.ReleaseScopes();      // release DI scopes early; body/headers live on for aggregation
            semaphore.Release();
        }
    }

    var tasks = Enumerable.Range(0, recipients.Count).Select(SendToRecipient).ToList();
    var results = await Task.WhenAll(tasks);   // (stopOnException; best-effort wraps each branch in try/catch)

    // Aggregation — in deterministic index order, not arrival order
    IExchange? aggregated = null;
    foreach (var result in results)
    {
        if (result == null) continue;
        aggregated = aggregated is null ? result : _aggregationStrategy(aggregated, result);
    }
    ApplyAggregation(exchange, aggregated);
}

A few things here are critical:

exchange.Clone() — each recipient works on its own clone. Clone() copies Properties shallowly (more on this in the transactions section), which matters for a consistent commit.
SemaphoreSlim(maxDop) — parallelism is capped. MaxDegreeOfParallelism=0 means Environment.ProcessorCount.
Aggregation in index order. Even if fraud answers first, the fold runs pricing → inventory → fraud. Predictability you can lean on.
ReleaseScopes() early — the clone's DI scopes are released right after the send, while body and headers stay alive for aggregation.
Producer cache — GetOrCreateProducer holds a ConcurrentDictionary<string, Lazy<ToProcessor>>; DisposeAsync stops every producer it created.

The sequential path

With ParallelProcessing(false) — different code, and a different clone:

foreach (var uri in recipients)
{
    var clone = exchange.CloneLinked();        // ← CloneLinked(), not Clone()
    var producer = GetOrCreateProducer(uri);
    await producer.Process(clone, ct);
    aggregated = aggregated is null ? clone : _aggregationStrategy(aggregated, clone);
}

The Clone() vs CloneLinked() difference isn't cosmetic — covered under transactions.

Error handling: best-effort vs stop-on-exception

StopOnException(false) (default, best-effort): a failed branch gets its clone.Exception set and is still handed to the aggregator — your strategy decides what to do with a branch carrying an Exception:

catch (Exception ex)
{
    if (_stopOnException) throw;
    clone.Exception = ex;
    aggregated = aggregated is null ? clone : _aggregationStrategy(aggregated, clone);
}

Timeout in best-effort: the sequential path aggregates the partial set and bails (break); the parallel path drops the timed-out branches (null). StopOnException(true) propagates the first failure, and a timeout is wrapped into a TimeoutException:

catch (OperationCanceledException) when (_timeout > TimeSpan.Zero && !ct.IsCancellationRequested)
{
    throw new TimeoutException($"Scatter-gather timed out after {_timeout}.");
}

Every parameter

The full contract — IScatterGatherDefinition:

Parameter	Default	What it does
`Recipients(params string[])`	—	Static list of recipient URIs.
`Recipients(Func<IExchange, IEnumerable<string>>)`	—	Dynamic — computed from the live message.
`AggregationStrategy(...)`	required	Pair-wise `(acc, cur) → merged`. Missing it fails the build.
`ParallelProcessing(bool)`	`true`	Parallel or sequential.
`MaxDegreeOfParallelism(int)`	`0` → ProcessorCount	Concurrency cap.
`StopOnException(bool)`	`false`	best-effort or fail-fast.
`Timeout(TimeSpan)`	`Zero` (none)	Whole-operation deadline.

The fully-knobbed fluent form:

.ScatterGather(sg => sg
    .Recipients("http://pricing:8080/quote", "http://inventory:8080/check", "http://fraud:8080/score")
    .AggregationStrategy((acc, cur) => { /* ... */ return acc; })
    .ParallelProcessing(true)
    .MaxDegreeOfParallelism(3)
    .Timeout(TimeSpan.FromSeconds(2))
    .StopOnException(false))

Dynamic recipients

The recipient list can be computed from the message — say, a fan-out across shards whose numbers arrived in a header:

.ScatterGather(sg => sg
    .Recipients(e =>
    {
        var shards = (e.In.Headers["shards"] as string ?? "").Split(',');
        return shards.Select(s => $"http://shard-{s.Trim()}:8080/query");
    })
    .AggregationStrategy((acc, cur) => MergeJson(acc, cur)))

That's essentially a Dynamic Recipient List inside Scatter-Gather — exactly what EIP primitives exist for.

A real production example: one HTTP request → six parallel aggregations

Enough synthetic snippets — here's a real production route (a logistics monitoring dashboard). The POST /api/tsum/routes endpoint returns a page of routes plus five different aggregate blocks for the dashboard widgets. That used to be six sequential database round-trips; here it's a single Scatter-Gather:

From("http:0.0.0.0:5090/api/tsum/routes?inOut=true&cors=true")
    .RouteId("tsum-api-routes")
    .Process(Auth.ProcessAsync)                 // authentication
    .ConvertBody<string>()
    .Process(ParseAndStashFilter)               // parse the filter → into Properties
    .ScatterGather(sg => sg
        .Recipients(
            "direct://routes-page",             // the result page (pagination)
            "direct://routes-ownership",        // aggregate: owned/hired × load status
            "direct://routes-route-status",     // aggregate: by route status
            "direct://routes-point-status",     // aggregate: by point status
            "direct://routes-territory",        // aggregate: vehicles on territory
            "direct://routes-departure")        // aggregate: departure stats
        .AggregationStrategy(MergeRouteFragments)
        .ParallelProcessing(true)
        .MaxDegreeOfParallelism(4)
        .StopOnException(true)
        .Timeout(TimeSpan.FromSeconds(30)))
    .Process(ComposeRoutesResponse);            // assemble the final JSON from the fragments

Each branch is its own direct:// route with its own redb query that drops its slice of the response into a frag:* property (plus its own timing metric):

From("direct://routes-ownership")
    .ProcessWithRedb(async (redb, ex, ct) =>
    {
        var sw = Stopwatch.StartNew();
        var query = await BuildFilteredQuery(redb, Filter(ex));   // the same filter every branch uses
        var groups = await query
            .GroupBy(r => new { r.Own, r.LoadStatus })            // server-side aggregation in redb
            .SelectAsync(g => new { g.Key.Own, g.Key.LoadStatus, Count = Agg.Count(g) });

        ex.Properties["frag:ownership"]      = BuildOwnershipFragment(groups);
        ex.Properties["metric:ownershipMs"]  = sw.ElapsedMilliseconds;
    });

The aggregator just folds each branch clone's frag:* and metric:* into the accumulator:

private static IExchange MergeRouteFragments(IExchange aggregated, IExchange current)
{
    foreach (var kv in current.Properties)
        if (kv.Key.StartsWith("frag:") || kv.Key.StartsWith("metric:"))
            aggregated.Properties[kv.Key] = kv.Value;   // branch fragment → into the shared result
    return aggregated;
}

and ComposeRoutesResponse builds the final JSON out of the six frag:* pieces.

Why this is "very fast." The six branches run in parallel (cap of 4 at a time). The endpoint's latency is the slowest single branch, not the sum of six. If each aggregation is ~80–150 ms, sequentially you'd be at ~0.6–0.9 s; through Scatter-Gather it's ~150 ms. One request from the frontend → one HTTP hop → six server-side redb aggregations at once → one JSON.

And here everything we covered about transactions lands in practice: each branch's ProcessWithRedb spins up its own per-exchange redb scope → its own connection (see §10). Six parallel queries on six connections, not sharing one transaction — which is exactly why it doesn't fall over. No .Transacted() is needed here: the branches only read, and the join is frag:* in memory. StopOnException(true) means "no half-built widget" — if any branch fails, the whole response is an error, not partial data.

9. EIP #2 — Aggregator: assembly over time

Scatter-Gather joins responses right now (fan-out → join). The Aggregator is a different pattern: it collects independent messages over time by a correlation key and emits the merge once a completion predicate trips.

The AggregatorProcessor contract is four things: correlationKey, aggregationStrategy, completionPredicate, target. The core:

public async Task Process(IExchange exchange, CancellationToken ct = default)
{
    var key = _correlationKey(exchange);
    IExchange? completed = null;

    lock (_lock)
    {
        if (_aggregated.TryGetValue(key, out var existing))
        {
            var merged = _aggregationStrategy(existing, exchange);
            _aggregated[key] = merged;
            if (_completionPredicate(merged))     // is the group complete?
            {
                completed = merged;
                _aggregated.Remove(key);
            }
        }
        else
        {
            _aggregated[key] = exchange;          // first in the group
            if (_completionPredicate(exchange)) { completed = exchange; _aggregated.Remove(key); }
        }
    }

    if (completed != null)
        await _target.Process(completed, ct);     // only completed groups flow downstream
}

A live example from the EipRoutes.cs demo — collect 3 events sharing a batchId:

From("timer://agg-source?period=2000&repeatCount=9")
    .RouteId("demo-aggregator")
    .SetHeader("batchId", e => $"batch-{DateTime.UtcNow.Second % 3}")
    .SetBody(e => $"event-{DateTime.UtcNow:ss.fff}")
    .Aggregate(
        correlationKey:      e => GetHeader(e, "batchId") ?? "default",
        aggregationStrategy: (oldEx, newEx) =>
        {
            oldEx.In.Body = $"{oldEx.In.Body} + {newEx.In.Body}";
            var count = oldEx.Properties.TryGetValue("agg.count", out var c) ? (int)c! : 1;
            oldEx.Properties["agg.count"] = count + 1;
            return oldEx;
        },
        completionPredicate:  e => e.Properties.TryGetValue("agg.count", out var c) && (int)c! >= 3)
    .Log("[AGG] done — merged 3 events: ${body}");   // runs on the completed group

.Aggregate(...) opens a scope (AggregateDefinition) — the steps after it (.Log(...)) build the target pipeline that runs on completed groups. Pre-completion messages are consumed silently.

On Kafka it's the classic "collect N by key":

From("kafka:order-lines?brokers=kafka:9092&groupId=order-assembler")
    .Aggregate(
        correlationKey:      e => e.In.Headers["redbKafka.Key"]?.ToString() ?? "x",  // key = orderId
        aggregationStrategy: (acc, cur) => AppendLine(acc, cur),
        completionPredicate: e => IsOrderComplete(e))
    .To("kafka:orders.assembled?brokers=kafka:9092&acks=All");

ℹ️ By default the inbound offset commits after processing. For an atomic "offset + publish-assembled-result" coupling, use enableAutoCommit=false + .Transacted().

The hard limitation, said out loud

The group store is a plain Dictionary<string, IExchange> behind a lock:

private readonly Dictionary<string, IExchange> _aggregated = new(StringComparer.Ordinal);
private readonly object _lock = new();

From that follows:

it's lost on a process restart — all in-flight groups vanish;
there is no timeout / eviction — only the completion predicate. A group that never reaches its condition (you wait for 3 events, 2 arrived, the source died) sits in memory forever. A potential leak if you have many keys that don't always complete.

This is not the persistent, recovery-capable aggregator from "big" Camel (completion timeout, persistent repository, recovery). For "collect N by key and emit a batch, a deploy losing in-flight state is acceptable" — great. For "buffer for a day, survive a restart" — you need persistence that isn't here. Honestly. There's a PendingGroupCount for monitoring how many groups are pending — at least you can see the pile growing.

10. Transactions: two models, and that's the whole point

Here's the fork to internalize. redb.Route has two distinct transaction models, and the connectors split into two camps. Getting this fork straight is half of using the framework well.

Camp 1: deferred actions (`ITransactedAction`) — they do NOT touch `System.Transactions`

This is every broker plus redb: Kafka, Redis, RabbitMQ, AMQP, IBM MQ, Azure Service Bus, and redb itself. One mechanic for all. The transport doesn't do the "real" work immediately — it parks an ITransactedAction in the shared bag at exchange.Properties["TRANSACT_ACTION"] (a ConcurrentDictionary) under a per-message-unique key:

private static void RegisterTransactedAction(IExchange exchange, string key, ITransactedAction action)
{
    if (!exchange.Properties.TryGetValue("TRANSACT_ACTION", out var raw) ||
        raw is not ConcurrentDictionary<string, ITransactedAction> dict)
    {
        dict = new ConcurrentDictionary<string, ITransactedAction>(StringComparer.OrdinalIgnoreCase);
        exchange.Properties["TRANSACT_ACTION"] = dict;
    }
    dict[key] = action;
}

Keys are kafka-send-{guid}, redis-write-{guid}, redb:{name}, an offset, a deliveryTag. Uniqueness is critical: parallel fan-out branches write into one shared bag (Clone() copies Properties shallowly → all clones share the dictionary), and without unique keys they'd clobber each other.

At the .Transacted() boundary, TransactedProcessor takes over:

public async Task Process(IExchange exchange, CancellationToken ct = default)
{
    if (!exchange.Properties.ContainsKey(TransactActionPropertyKey))
        exchange.Properties[TransactActionPropertyKey] = new ConcurrentDictionary<string, ITransactedAction>(...);

    using var scope = _policy.CreateScope();   // System.Transactions.TransactionScope (AsyncFlow enabled)
    try
    {
        await _inner.Process(exchange, ct);
        await CommitActions(exchange, ct);      // commit ALL deferred actions
        scope.Complete();
    }
    catch (Exception ex)
    {
        await RollbackActions(exchange, ct);    // on error — roll them all back
        throw;
    }
}

CommitActions walks the bag sequentially and commits each action — which bites us in the trade-off below:

foreach (var kvp in actions)
    await kvp.Value.Commit(ct);

These transports never touch Transaction.Current. So parallel fan-out over them is safe: unique keys → no bag collisions → no concurrent enlistment in a single System.Transactions transaction.

redb joins this camp via RedbTransactedAction — it wraps a redb-native IRedbTransaction (its own BEGIN/COMMIT on its own connection) and drops it into the same bag under key redb:{name}:

public async Task Commit(CancellationToken ct = default)
{
    if (Interlocked.Exchange(ref _completed, 1) != 0) return;  // single-use
    try { if (_tx.IsActive) await _tx.CommitAsync(); }
    finally { await _tx.DisposeAsync(); }
}

Camp 2: SQL — it enlists in `System.Transactions`

The SQL connector behaves fundamentally differently (SqlProducer):

var connection = await factory.CreateConnectionAsync(readOnly: ..., ct);

// If an ambient TransactionScope exists (route-level .Transacted()), the connection auto-enlists —
// no local transaction needed. Otherwise always wrap in a local one (like EF SaveChanges).
var hasAmbientTx = Transaction.Current != null;
DbTransaction? tx = null;
if (!hasAmbientTx)
    tx = await connection.BeginTransactionAsync(ct);
// ... execute ...
if (tx != null) await tx.CommitAsync(ct);

So:

no ambient → each execution is wrapped in a local DbTransaction on its own connection (atomic, like EF's SaveChanges, with no ?transacted=true);
an ambient Transaction.Current present (opened by .Transacted() / .BeginTransaction()) → it skips the local one and the connection auto-enlists in the ambient TransactionScope.

SQL is the one in-box connector that genuinely participates in System.Transactions. That's both a feature (one .Transacted() wrapper around several SQL writes = one atomic transaction, perfect for an outbox write) and a thing whose edges you must understand.

Why parallel Scatter-Gather doesn't blow up under a transaction

The reasonable fear: parallel branches run on different threads, Transaction.Current flows into each via ExecutionContext — won't that be concurrent use of one transaction and a promotion to MSDTC (which on PG/Linux simply throws)?

No. Here's why — from the code:

1. Scopes are created per-exchange. A named redb instance resolves through GetRedbService(name, exchange) (RedbRouteExtensions), which caches a DI scope under exchange.Properties["__redb_scope:{name}"] and pulls the service from that scope's provider:

var cacheKey = ScopeCachePrefix + cleanName;          // "__redb_scope:orders-db"
if (exchange.Properties.TryGetValue(cacheKey, out var cached) && cached is IServiceScope cachedScope)
    return cachedScope.ServiceProvider.GetRequiredService<IRedbService>();

var scope = factory.CreateScope();                    // not cached — create our own
exchange.Properties[cacheKey] = scope;
return scope.ServiceProvider.GetRequiredService<IRedbService>();

2. Clone() deliberately does NOT copy scopes. From Exchange.cs:

foreach (var kvp in _properties)
{
    // Named redb scopes are per-exchange; the child creates its own on first access.
    if (kvp.Key.StartsWith("__redb_scope:", StringComparison.Ordinal))
        continue;
    clone._properties[kvp.Key] = kvp.Value;
}

So each parallel branch spins up its own scope → its own IRedbService → its own connection.

3. redb never enlists in System.Transactions — it uses its own IRedbTransaction, parked in TRANSACT_ACTION.

Net result: there is no single System.Transactions transaction being hit concurrently by multiple connections → no MSDTC promotion, no "transaction context in use by another thread," no crash. Different connections, not one transaction — that's the design, not a bug.

Same story for SQL. In a Scatter-Gather without a .Transacted() wrapper, each branch opens its own connection (CreateConnectionAsync per Process) and its own local DbTransaction → independent atomic writes → no crash. The only way to hit the multi-connection-enlistment-to-MSDTC crash is to deliberately wrap a parallel fan-out in .Transacted() (an ambient System.Transactions scope) and fan out to several SQL connections — on PG/Npgsql that escalates to a distributed transaction and throws. A narrow edge nobody walks into, because the deferred model exists for brokers/redb.

So what is the 3.2.0 `DependentTransactionBranch` for, then?

That 3.2.0 per-branch isolation fix is wired only into Multicast and Splitter (plus the helper itself) — nowhere else. Here's its core (DependentTransactionBranch):

internal static async Task RunAsync(Func<Task> branch)
{
    var ambient = Transaction.Current;
    if (ambient is null) { await branch(); return; }   // no transaction — zero overhead

    // Fork a dependent clone: this branch's enlistment is private to its thread.
    var dependent = ambient.DependentClone(DependentCloneOption.BlockCommitUntilComplete);
    using (var scope = new TransactionScope(dependent, TransactionScopeAsyncFlowOption.Enabled))
    {
        await branch();
        scope.Complete();
    }
    dependent.Complete();   // release the parent commit (it waited on BlockCommitUntilComplete)
}

It matters only for resources that genuinely enlist in Transaction.Current — i.e. when parallel Multicast/Splitter branches do inline work on an enlisting connection. Scatter-Gather doesn't need it: per-exchange scopes + deferred ITransactedAction already give isolation without sharing a connection. Not a missing-feature asymmetry — two mechanisms for two situations.

The honest trade-off (a design choice, not a bug)

TransactedProcessor.CommitActions commits the deferred actions sequentially in a loop, and Scatter-Gather/Multicast branches are different connections, different transactions. So: if branch A commits and branch B's commit throws, you get a partial commit. No cross-branch DB atomicity here. That's the price of "no crash, no MSDTC promotion." If you need real cross-branch atomicity with enlistment, that's Multicast/Splitter under .Transacted() with the 3.2.0 fix — not Scatter-Gather.

Transaction policies

.Transacted() is backed by TransactionPolicy — four ready-made:

Policy	`ScopeOption`	Behavior
`Default`	`Required`	Join the ambient or create a new one. 30s timeout, `ReadCommitted`.
`RequiresNew`	`RequiresNew`	Always a new transaction; the ambient is suspended.
`Suppress`	`Suppress`	Run with no transaction (ambient suppressed).
`Mandatory`	(marker)	Requires an existing ambient, else `InvalidOperationException` at scope creation.

TransactionDefinition also gives Camel-parity hooks: .Retry(attempts, delay) (wraps the body in a RetryProcessor) and .DeadLetterChannel(uri) (on failure after rollback, send the exchange to the DLC). So a transactional block with retries and dead-letter is:

From("kafka:orders?brokers=kafka:9092&groupId=w")
    .Transacted()
        .Retry(3, TimeSpan.FromMilliseconds(200))
        .To("sql:INSERT INTO orders ...")
        .To("kafka:orders.done?brokers=kafka:9092&transacted=true")
    .EndTransaction();

11. The parallel cousins: Splitter and Multicast

Scatter-Gather isn't the only fan-out in the family. Next to it sit Splitter (split the body into parts, process each) and Multicast (send a copy to N processors). Both, like Scatter-Gather, have an optional aggregation, parallelism, and stopOnException. The difference is where the "branches" come from:

Scatter-Gather: branches = endpoints (producer URIs), aggregator mandatory.
Multicast: branches = processors / sub-pipelines, aggregator optional (MulticastProcessor).
Splitter: branches = body parts (SplitterProcessor), aggregator optional, with some Camel-compat nuances.

Splitter is actually the most feature-rich on aggregation: its strategy (IExchange?, IExchange) → IExchange is called even for the first part with oldExchange == null (Camel's seed/wrap contract), and there are flags parallelAggregate (aggregate inline under a lock from workers instead of a deterministic post-pass) and aggregateOnException (include failed parts in the aggregate). And it's Splitter/Multicast's parallel path that carries the DependentTransactionBranch.RunAsync:

// MulticastProcessor.ProcessParallel / SplitterProcessor.ProcessParallel
await DependentTransactionBranch.RunAsync(() => _targets[idx].Process(clone, ct));

Why they have it and Scatter-Gather doesn't — covered above: Splitter/Multicast run inline processors (which can open an enlisting connection right in the branch), whereas Scatter-Gather runs producers by URI with per-exchange scopes. Different risks, different mechanisms.

A simple Multicast from the demo:

From("direct://demo-multicast")
    .Multicast(new[] { "direct://mcast-a", "direct://mcast-b", "direct://mcast-c" }, parallelProcessing: true)
    .Log("[MCAST] ◀ All endpoints received the message");

12. Saga — "a slightly different one"

redb.Route has a saga, but it's not MassTransit's durable state machine. It's SagaProcessor — an in-process compensating saga within a single exchange:

public async Task Process(IExchange exchange, CancellationToken ct = default)
{
    var completedCount = 0;
    try
    {
        for (var i = 0; i < _steps.Length; i++)
        {
            ct.ThrowIfCancellationRequested();
            await _steps[i].Action(exchange, ct);
            completedCount++;
        }
    }
    catch (Exception ex) when (ex is not OperationCanceledException)
    {
        // Compensate completed steps in REVERSE order
        for (var i = completedCount - 1; i >= 0; i--)
        {
            if (_steps[i].Compensate is null) continue;
            try { await _steps[i].Compensate!(exchange, ct); }
            catch (Exception compEx) { _logger?.LogError(compEx, "Saga compensation for step {i} failed", i); }
        }
        throw;
    }
    if (_onCompletion is not null) await _onCompletion(exchange, ct);
}

Compensation failures are logged and don't abort the rest of the rollback. The DSL (SagaDefinition) comes in two styles, callback and fluent-scope:

From("direct:checkout")
    .Saga(s => s
        .Step(reserve, compensate: unreserve)
        .Step(charge,  compensate: refund)
        .Step(ship)                              // forward-only, no compensation
        .OnCompletion(e => Log("order placed")));

Bluntly: no state persistence, no correlation across messages/time, does not survive a process restart. It's Camel-style "routing slip with compensation," not a persisted state machine. Only the name overlaps. There are metrics, by the way: SagaCompleted / SagaCompensated / SagaFailed.

Again — not a shortcoming, a different school. Need a durable saga with persistence over Kafka? Build it from Aggregator + a SQL/Redis store + a correlation key. The bricks are there.

13. Outbox — there isn't one, and that's correct

Grep across src for Outbox — zero. No built-in outbox. That's not a gap, it's a stance: the transactional outbox is a pattern, not a framework button. Baking it into the core is over-engineering; anyone who wants one wires their own in five lines for their own invariants:

// 1. Write: business data + an outbox row under one transaction.
//    For SQL this is exactly where the System.Transactions enlistment works FOR you:
//    one .Transacted() wrapper → one ambient scope → atomic.
From("direct:place-order")
    .Transacted()
        .To("sql:INSERT INTO orders(id, payload) VALUES (@id, @payload)")
        .To("sql:INSERT INTO outbox(id, topic, payload, sent) VALUES (@id, 'orders', @payload, false)")
    .EndTransaction();

// 2. Deliver: a separate poller route reads the outbox and publishes.
From("sql:SELECT * FROM outbox WHERE sent = false ORDER BY id?outputType=SelectList&delay=1000")
    .Split(body => (IEnumerable<object?>)body)        // one message per row
        .To("kafka:orders?brokers=kafka:9092")
        .To("sql:UPDATE outbox SET sent = true WHERE id = @id");

Want the inbox pattern, dedup by messageId, a TTL on rows, a claim-check for big payloads? Add it. Nobody forces their outbox schema or retry semantics on you. That is "moving toward Camel": less baked-in magic, more explicit assembly.

14. Bottom line: a trade, not "better/worse"

	MassTransit	redb.Route (Camel school)
Saga	durable state machine, persisted, survives restarts	in-process compensation within an exchange
Outbox	a framework feature	your own route from SQL/Redis in five lines
Transactions	a framework abstraction	two explicit models: deferred `ITransactedAction` (brokers+redb) / `System.Transactions` (SQL)
Kafka "transactional"	EOS out of the box	idempotent producer + deferred commit (not EOS)
Philosophy	batteries included, do it their way	EIP + connectors + DSL, compose it yourself

This isn't "redb.Route beats MassTransit." It's a different trade: less baked-in magic, more explicit assembly from primitives. If your scenarios don't fit someone else's saga/outbox model, the Camel approach lets you assemble exactly yours. If they do fit, maybe you don't need to leave at all.

Scatter-Gather, for the record, has been rock-solid for us in production — one processor that fans out and joins, in parallel, with a deterministic merge order and transaction semantics you can actually reason about. Exactly the case where an EIP primitive solves the real problem without a single line of infrastructure code.

We run 3.2.0 in production — CHANGELOG here. War stories, things to re-verify (looking at you, transacted Kafka), which EIP to dissect next — drop them in the comments and we'll dig through the code together.

SQLite provider anatomy: moving away from EF Core — typed object storage for desktop, mobile, and Blazor WASM

rinat kozin — Mon, 29 Jun 2026 21:53:41 +0000

Series: redb — ecosystem, engineering teardown following the 3.2.0 SQLite announcement.

What this is

Full anatomy here, recommend a quick look at redbase.app first for context: https://redbase.app/

When we shipped the SQLite provider in redb 3.2.1, the pitch was two sentences: same LINQ, one line in DI. This post is the opposite of that pitch. Not "what shipped" — how it's built and where it leaked. Concretely: how redb's query engine moved into a native C extension on a database with no stored procedures; how we store DateTimeOffset in a database that has no date type; and three real bugs from this release, each with the filter JSON, the generated SQL, and the fix.

It's long and it has code. If you want the short version, the announcement is linked above. If you want what's under "one line in DI," pull up a chair.

For context, if redb is new to you (the rest assumes you've seen this):

Two tables, zero migrations: a typed object store for .NET over Postgres/MSSQL — full LINQ, no Include — the what and why.

redb inside, part 1: the 13 tables everything runs on — the storage model. Load-bearing for this post: the SQLite provider had to reproduce it one-for-one.

Why our Free was so far behind Pro — and what we shipped in 3.0.0 (with the actual SQL) — what "Free = server-side functions" means, which is exactly what we had to port to C here.

SQLite provider for RedBase is coming — the 3.2.1 teaser — the short version of what this post takes apart.

Two disclaimers before we start, so nothing trips us up later.

One — about a word. Yes, redb's model is "flexible": a class is spread across rows in a values table. No, this is not EAV in the dismissive sense people throw that acronym around. What lives in a redb database is RTTI — real type information: schemes, structures, field types, references. The DB knows that EmployeeProps.HireDate is a DateTime, that Contacts is an array of objects, that CurrentProject is a reference to another scheme. That's a runtime type system at the storage layer, not a blind bag of tuples. You'll see below why neither the materializer nor the query compiler could physically exist without it — at every step they need the type of the thing they're materializing or filtering.

Two — about fit, so nobody's disappointed later. redb is for complex business classes: object graphs, nesting, cross-scheme references, trees, dictionaries, arrays of objects. Pumping flat, high-volume streams into it — a coordinate feed, sensor telemetry, thousands of metrics a second — technically works, but it's an anti-pattern. That's what time-series and columnar stores exist for; redb pays for its flexibility and typing exactly where the data is rich and connected, not where you've got one (timestamp, value) table at a billion rows. Short version: redb shines when you have a real domain model.

Part 0. The constraint that shapes everything

SQLite has no procedural language. No PL/pgSQL, no T-SQL — nowhere to put server-side logic. And redb's "Free" tier on Postgres and MSSql is built exactly around having that: the heavy machinery (query compiler, materializer, soft-delete, permission views) lives inside the database as server-side functions. That's literally the Free/Pro line: where JSON gets materialized and who generates the SQL.

"No stored procedures" forks into exactly two paths, and we took both — one per tier:

Pro — pure C#. ProSqlBuilder generates the query SQL in code, props materialize in code, zero DB-function calls. Consequence: it runs anywhere Microsoft.Data.Sqlite runs — including Blazor WebAssembly and mobile (MAUI/iOS/Android), where you flat-out cannot load a native SQLite extension.

Free — a native C extension. Same shape as Postgres/MSSql: the engine lives in the database. On SQLite, "in the database" means a loadable extension written in C (redb.dll / .so / .dylib) on top of sqlite3ext.h. It runs wherever native code loads: desktop, server, CI — and it lets a non-.NET host (Python, the sqlite3 CLI) talk to a redb database directly if it wants to.

Both stories at full size below. Native first (it's the fun one), then dates (the important one), then the bugs, then the traps.

Part 0.5. What the provider reproduces: `_objects` and `_values`

Before diving into the native side — what it actually reads and writes. redb's model is ~13 tables (full teardown in the "13 tables" post), but two are load-bearing for the SQLite story, and the provider had to recreate both column-for-column.

_objects is the "header" of every object: identity, tree, ownership, dates, the reference to a scheme (i.e. to a type):

CREATE TABLE _objects(
    _id             INTEGER NOT NULL PRIMARY KEY,
    _id_parent      INTEGER NULL,            -- tree (parent)
    _id_scheme      INTEGER NOT NULL,        -- RTTI: which CLASS this object is
    _id_owner       INTEGER NOT NULL,
    _id_who_change  INTEGER NOT NULL,
    _date_create    REAL    NOT NULL DEFAULT (julianday('now')),  -- UTC Julian day (REAL)
    _date_modify    REAL    NOT NULL DEFAULT (julianday('now')),  -- UTC Julian day (REAL)
    _name           TEXT    NULL,
    _hash           TEXT    NULL,            -- hash of the props set (delta/cache)
    -- slots for RedbPrimitive<T> (when Props IS the primitive, no nested structure)
    _value_long     INTEGER NULL,
    _value_string   TEXT    NULL,
    _value_bool     INTEGER NULL,            -- bool = 0/1
    _value_double   REAL    NULL,
    _value_numeric  REAL    NULL,            -- NUMERIC(38,18): REAL by default
    ...
);

_values is the row-per-property store. One row per (object, structure, [array index]). The key idea is typed column slots: a value lives not in one "universal" text column, but in the column for its type:

CREATE TABLE _values(
    _id              INTEGER NOT NULL PRIMARY KEY,
    _id_structure    INTEGER NOT NULL,       -- RTTI: WHICH field this is
    _id_object       INTEGER NOT NULL,
    _String          TEXT    NULL,
    _Long            INTEGER NULL,
    _Guid            TEXT    NULL,
    _Double          REAL    NULL,
    _DateTimeOffset  REAL    NULL,           -- DateTime/DateTimeOffset/DateOnly as UTC Julian
    _Boolean         INTEGER NULL,           -- 0/1
    _ByteArray       BLOB    NULL,
    _Numeric         REAL    NULL,
    _ListItem        INTEGER NULL,
    _Object          INTEGER NULL,           -- reference to another object
    _array_parent_id INTEGER NULL,           -- arrays/dictionaries — relational
    _array_index     INTEGER NULL
);

Two consequences that everything else rests on:

Typed slots, not "everything as a string." _Boolean is 0/1, _DateTimeOffset is REAL Julian, _Long is an integer. So comparisons and sorts in SQL run on the column's native type (and use indexes) instead of a string cast. That's the "not EAV" part: _values is a typed props store, and _id_structure → _structures carries RTTI about which field this is and what type it is. The query compiler needs the field's type at every step — to pick the slot column for MAX(...) FILTER in the pivot; without RTTI it wouldn't know which column LastName comes out of.
Arrays and dictionaries are relational, via _array_parent_id/_array_index, not a JSON blob. So the materializer assembles them with GROUP BY over the index, and the compiler can filter through them (_array_index IS NULL in the pivot is exactly what separates a field's scalar row from its array elements).

From here, "the engine in the database" = functions that read/write exactly these two tables, checking the metadata in _schemes/_structures.

Part 1. The native extension: anatomy

Entry point

A SQLite loadable extension is a .so/.dll/.dylib with one exported init function. The default name is derived from the file basename: for redb.dll, that's sqlite3_redb_init. Inside, it registers all our SQL functions:

SQLITE_EXTENSION_INIT1

int sqlite3_redb_init(sqlite3 *db, char **pzErrMsg, const sqlite3_api_routines *pApi){
  SQLITE_EXTENSION_INIT2(pApi);
  int rc;

  rc = sqlite3_create_function(db, "get_object_json", 1, SQLITE_UTF8, 0,
                               getObjectJsonFunc, 0, 0);
  if(rc != SQLITE_OK) return rc;
  rc = sqlite3_create_function(db, "get_object_json", 2, SQLITE_UTF8, 0,
                               getObjectJsonFunc, 0, 0);   // overload: (_id, max_depth)
  if(rc != SQLITE_OK) return rc;

  rc = sqlite3_create_function(db, "save_object_json", 1, SQLITE_UTF8, 0,
                               saveObjectJsonFunc, 0, 0);
  if(rc != SQLITE_OK) return rc;

  rc = redbRegisterPvt(db);   // the whole pvt_* compiler
  return rc;
}

SQLITE_EXTENSION_INIT1/INIT2 are macros from sqlite3ext.h that rewrite direct sqlite3_* calls into calls through the pApi pointer table. The gotcha that's easy to miss: after INIT2, every SQLite API call inside the extension goes through that table. Forget INIT2 and the extension compiles fine — then segfaults on the first sqlite3_* call through a garbage pointer.

Loading — on every connection

The defining trait of loadable extensions: they are not persistent. SQLite forgets registered functions on a new connection. And Microsoft.Data.Sqlite pools connections. So you must load the extension on every connection, after PRAGMAs. Our wrapper around SqliteConnection does it: open → set foreign_keys=ON and busy_timeout → load the extension → hand it to the pool.

The binary is located by:

An explicit SqliteDataSource.NativeExtensionPath (if set in code).
The REDB_SQLITE_EXTENSION environment variable.
Otherwise redb.{dll,so,dylib} from the NuGet runtimes/<rid>/native/ folder; in dev, by walking up the directory tree to redb.SQLite/native/build.

Pro never sets a path: it doesn't need the native code, and in WASM/mobile there wouldn't be any.

Shipping the binary: why it cross-compiles for free

The extension is a loadable module, and that has a packaging payoff people don't expect: it links against nothing. sqlite3ext.h hands you the API as a pointer table resolved from the host at load time (that's what SQLITE_EXTENSION_INIT2 wires up) — so there's no libsqlite3 to find, no import library, no target sysroot. Cross-compiling collapses to "point CMake at a cross compiler":

# linux-arm64 from an x64 box, in a throwaway container — no sysroot needed
docker run --rm -v "$PWD:/work" debian:bookworm bash -c '
  apt-get update && apt-get install -y cmake make gcc-aarch64-linux-gnu
  cd /work/redb.SQLite/native
  cmake -S . -B build-linux-arm64 -DCMAKE_C_COMPILER=aarch64-linux-gnu-gcc
  cmake --build build-linux-arm64'
# → build-linux-arm64/redb.so: ELF 64-bit LSB shared object, ARM aarch64

A native lib that linked libsqlite3 would need the arm64 build of that library to link against; this one doesn't, because it only ever calls SQLite through the host's pointer table. One cross-gcc, one valid arm64 binary.

Delivery has its own twist. SQLite loads the extension by an explicit path (conn.LoadExtension(...)), not like a P/Invoke native lib the host resolves from the NuGet cache — so the file must physically sit in the app output. A RID-targeted dotnet publish -r <rid> flattens runtimes/<rid>/native/ for you; a framework-dependent build (no RID) doesn't, so the package ships a buildTransitive .targets that copies the OS-matching binary into the consumer's output, Exists-gated per RID. That's why "ship one more platform" = "produce one more redb.{so,dylib} and drop it in native/build-<rid>/" — the csproj and .targets already enumerate all five RIDs.

War story #5: the `.targets` that broke every consumer (3.2.0 → 3.2.1)

That delivery .targets is also where this release drew blood — and since this is an honest teardown, here it is. We shipped 3.2.1 with a banner comment in redb.SQLite.targets that had a row of - characters inside . XML comments cannot contain --, so MSBuild refused to even load the file: every consumer that pulled the package got

error MSB4024: An XML comment cannot contain '--', and '-' cannot be the last character.

and couldn't build at all. And it rode transitively — redb.SQLite.Pro depends on redb.SQLite, and buildTransitive assets flow to dependents, so the Pro package was just as broken.

Why didn't the 200/200 suite catch it? Because buildTransitive only imports when the package is consumed as a NuGet package. Our own solution references the projects by ProjectReference, which skips the build/ import entirely — so the malformed file sat in every green build, invisible, until the first real dotnet add package redb.SQLite. We found it the moment we built a packaged consumer (a sample app in the public repo), not a second earlier.

The fix is a one-line deletion (and yes — I reproduced the identical bug in a csproj comment while writing the fix; -- is a persistent little landmine). Because you can't overwrite a published version, the corrected packages went out as redb.SQLite / redb.SQLite.Pro 3.2.1, and the broken 3.2.1 pair was unlisted. So, to be exact about versions: the engine, the date handling, the bugs above — all 3.2.1; the two SQLite NuGet packages are 3.2.1. The unglamorous lesson: a package's build/ and buildTransitive assets are shipped code too — validate them from a packaged consumer in CI, because ProjectReference will happily lie to you.

What's inside: a materializer and a compiler

Two big subsystems live in the extension.

get_object_json(_id [, max_depth]) — a recursive materializer. Takes an _id, reads _values, assembles the JSON object that System.Text.Json then deserializes into a typed RedbObject<TProps>. It assembles everything: base fields from _objects, scalars, arrays and dictionaries (relationally, via _array_index / _array_parent_id), nested Class fields, object references, ListItem (including a ListItem that itself carries an Object). This is exactly where RTTI is required: to assemble a nested object, the materializer must know its scheme, its field types, that this field is an array and that one is a reference. Without type metadata, it'd just be a pile of rows in _values.

The pvt_* compiler — ~9k lines of PL/pgSQL logic ported into C as a SQL-string generator: pvt_build_query_sql, pvt_build_aggregate_sql, pvt_build_groupby_sql, pvt_build_window_sql, pvt_build_projection_sql, pvt_build_array_groupby_sql. The pipeline:

LINQ expression
   → (C#) facet filter as JSON + a field list
   → (native) pvt_build_query_sql(scheme, filterJson, ...)
   → a finished SQL SELECT string
   → (C#) execute it, materialize via get_object_json

So the native side is a filter-JSON-to-SQL translator. C# doesn't build the SQL itself (Pro does that) — it builds a filter JSON and asks the database to assemble the SQL. It sounds inside-out, but it's exactly what buys parity: the same filter JSON, on Postgres and on SQLite Free, runs through the same engine — just emitting different dialects.

A bit deeper on `get_object_json`: recursion, arrays, references

"Assembles JSON" sounds simple until you remember it's assembling a graph. The materializer walks the scheme's structure and, for each field, decides what it is from the RTTI in _structures:

scalar — reads the value from the matching _values slot column (for a date, wraps it in strftime so an ISO string goes out);
array/dictionary — gathers all rows with the same _array_parent_id, ordered by _array_index, into a JSON array/object (this is why the pivot uses _array_index IS NULL — to separate a field's "scalar" row from its elements);
nested Class — recurses into the subtree assembly;
reference (_Object) — by max_depth, either expands the target object (recursion with decremented depth) or leaves an id reference;
ListItem — a lookup-list entry; and a ListItem can itself carry an Object, so that's one more level of expansion.

The max_depth parameter (the second overload of the function) is a guard against infinite recursion on cyclic references and, at the same time, a budget for how deep to pull related objects into one JSON. None of these transitions is possible without RTTI: the materializer must know that this field is an array and that one is a reference, or it's just rows in _values with no meaning.

The other direction: `save_object_json` — the write path

Reading has a symmetric twin — save_object_json(json). It takes an object's JSON and, by the scheme, lays it back out into _objects (base) and _values (props). Two SQLite-specific subtleties:

Dates on write. In the incoming JSON, dates are ISO strings (that's how System.Text.Json serializes a DateTimeOffset). The native write wraps them in julianday('<iso>') so _DateTimeOffset gets a REAL Julian. It's the mirror of the read-side strftime — and exactly what got fixed this release under "fix save_object_json too": before the fix, a date went in as a string and didn't agree with the REAL column.
The props-save strategy. On Free it's PropsSaveStrategy.DeleteInsert: a save = delete the object's existing _values rows and insert the new set (ChangeTracking — a delta off _hash — is a Pro feature). Simple, predictable, no tracking layer — at the cost of extra rewrites; fine for an embedded load.

Loading the right type: the CLR registry and polymorphism

get_object_json hands back JSON — but deserialize it into what? For LoadAsync<EmployeeProps>(id) the answer is in the generic. But for polymorphic loads (GetChildren on a tree where the children are objects of different schemes; LoadDynamicObject) the type is unknown at compile time: you have to map the object's _id_scheme to the *Props class to materialize into.

This got rebuilt this same cycle into a two-layer CLR registry (we were fixing a polymorphic LoadAsync that returned the wrong type out of nowhere):

a global scheme name ↔ Type index — self-healing: subscribed to AppDomain.AssemblyLoad, so loading an assembly with new *Props bumps a "generation" and the index rebuilds lazily (no "register all your types at startup");
a per-domain scheme_id → Type cache — where "domain" = SHA256(sanitized connection string) or an explicit CacheDomain. Per-domain partitioning matters because one process can hold several databases (including several SQLite files), and scheme_id=1000010 in one is not the same class as in another.

This ties straight to SQLite: the materializer hands back JSON + _id_scheme, and the registry turns _id_scheme into a Type to deserialize a polymorphic child into. Get it wrong and a tree of mixed-type children all materializes into one (wrong) type.

The Postgres → SQLite phrasebook

A port isn't "retype it in C," it's a dialect translation. The most frequent swaps (all real lines from SqliteDialect/the native side):

Postgres	SQLite	where
`array_agg(x) FILTER (WHERE …)`	`json_group_array(x) FILTER (WHERE …)`	pivoting arrays
`x = ANY($1)`	`x IN (SELECT value FROM json_each($1))`	IN-lists (SQLite can't bind array params)
`EXTRACT(year FROM x)`	`CAST(strftime('%Y', x) AS INTEGER)`	date parts
`col ILIKE $1`	`col LIKE $1 ESCAPE '\'`	case-insensitive LIKE
`DELETE … WHERE _id = ANY($1)`	`DELETE … WHERE _id IN (SELECT value FROM json_each($1))`	delete-by-id-list
`DISTINCT ON (col)`	`ROW_NUMBER() OVER (PARTITION BY col)` + `WHERE rn=1`	DistinctBy (its own section below)

That ESCAPE '\' deserves a sentence, because it's a classic landmine. Postgres uses \ as the default LIKE escape character. SQLite (and MSSQL) do not. Meanwhile UserProviderBase escapes user input with a backslash (50% → 50\%), assuming PG semantics. On SQLite, without an explicit ESCAPE '\', that escaped \% starts matching a literal backslash followed by anything — a silent search corruption. So the SQLite dialect always emits LIKE with an explicit ESCAPE '\'. Small thing, easy half-day to lose.

Minimum version, and why

SQLite 3.44.0+ (Nov 2023). We deliberately lean on FILTER (WHERE …), modern window functions, RETURNING, JSON1, and recursive CTEs. The goal is to keep the SQLite SQL structurally close to the Postgres SQL, not rewrite it from scratch. The closer the dialects, the fewer places they diverge in behavior (not just syntax) — and behavioral divergences are the ones you find in prod, not in the compiler.

Identifiers: AUTOINCREMENT instead of sequences

SQLite has no sequences. redb needs globally-unique ids that both the .NET key generator and the native side (for non-.NET hosts) can hand out. The solution: a native AUTOINCREMENT table with sqlite_sequence as a shared high-water mark. Both the C extension and the C# key generator advance the same counter and reserve id blocks from it. The result: ids are unique no matter who handed them out — .NET or a Python process writing to the same file.

War story #1: `%%` in `sqlite3_mprintf`

So that "porting PL/pgSQL to C" doesn't sound sterile — here's the kind of bug the port hands you for free.

The materializer has a column-list macro VCOLS that gets interpolated into an sqlite3_mprintf format string:

char *sql = sqlite3_mprintf("SELECT" VCOLS "FROM _values WHERE _id_structure=?1 "
                            "AND _id_object=?2 AND %s LIMIT 1", cond);

When I switched the datetime columns to emit via strftime('%Y-%m-%dT%H:%M:%fZ', _DateTimeOffset), I dutifully put that strftime right into VCOLS. Everything fell over silently: objects started loading with empty properties, while base dates were fine.

I spent half an hour looking in the wrong place. The reveal: VCOLS flows into the format string of sqlite3_mprintf, and %Y %m %d %H %M %f are format specifiers to mprintf. It started eating the cond argument at the first %Y, the formatting derailed, the SQL came out malformed, sqlite3_prepare_v2 silently returned an error code, and the props function returned empty. Base dates survived because their SELECT goes through prepare_v2 directly, no mprintf.

The fix is escaping — %% (mprintf collapses %%→% before SQLite ever sees the string):

// was: ... strftime('%Y-%m-%dT%H:%M:%fZ',_DateTimeOffset) ...   // breaks mprintf
// now:
#define VCOLS " _id,_String,_Long,_Guid,_Double, " \
  "strftime('%%Y-%%m-%%dT%%H:%%M:%%fZ',_DateTimeOffset), " \
  "_Boolean,_ByteArray,_Numeric,_ListItem,_Object,_array_parent_id,_array_index "

The lasting lesson: when you generate SQL through a printf-style formatter, any % in the data is a landmine. What makes it nasty is that the failure is silent: prepare doesn't throw, it returns an error code that's easy to skip, and it surfaces as "why are my props empty."

Part 2. SQLite has no date type. How we lived with that for a release

This is the central engineering story of the release, and it didn't exist yet at announcement time.

Three storage classes, zero date types

In SQLite, datetime is a convention over three storage classes, not a type:

TEXT — an ISO-8601 string ('2024-06-15 13:45:30').
REAL — a Julian day, a floating-point number (astronomical day count).
INTEGER — Unix epoch seconds.

A .NET DateTimeOffset doesn't drop into any of these on its own. You pick a representation and hold it everywhere: on write (the parameter binder), on read (the materializer + scalar converters), in filter comparisons, in aggregates. One miss in any of those points and dates "kind of work" but lie at the boundaries.

Why not TEXT (even though that's how it started)

The first version stored dates as ISO text. It broke exactly the way string-comparing dates breaks.

datetime('now') in SQLite returns a string with a space between date and time: 2024-06-15 13:45:30. But the literal the C# layer interpolates into a comparison arrives with a T: 2024-06-15T13:45:30. TEXT comparison in SQLite is lexicographic, byte-by-byte. Here's what happens at position 10:

'2024-06-15 13:45:30'   byte[10] = 0x20 (space)
'2024-06-15T13:45:30'   byte[10] = 0x54 ('T')
0x20 < 0x54  →  the space string is ALWAYS "less than" the 'T' string

So any "stored (with a space) ⟷ literal (with a T)" comparison goes one way always, regardless of the actual time. Range filters started lying silently. In a cluster, this once marked a live node dead: the heartbeat comparison last_seen < cutoff was "always true" because the stored last_seen (with a space) sorts lexicographically below the cutoff literal (with a T). Node's alive; monitoring thinks it's a corpse.

We could normalize the separator. But that treats the symptom: TEXT comparison stays lexicographic, and any other format drift (milliseconds, a timezone suffix, leading zeros) reopens the same hole. We had to leave strings.

The fix: REAL Julian day, everything in UTC

We moved to REAL Julian day, everything in UTC — exactly how Postgres keeps timestamptz in UTC. Three reasons this is a right choice, not "yet another convention":

1. SQLite's native functions eat the Julian number directly. julianday(), strftime(), datetime(), date() take a REAL Julian as-is, no wrapping:

sqlite> SELECT strftime('%Y-%m-%dT%H:%M:%fZ', 2460477.0732638887);
2024-06-15T13:45:30.000Z
sqlite> SELECT datetime(2460477.0732638887);
2024-06-15 13:45:30
sqlite> SELECT julianday('2024-06-15T13:45:30Z');
2460477.0732638887

So to emit a date into JSON, the materializer just wraps the column in strftime and gets ISO that System.Text.Json parses natively.

2. Comparison becomes numeric. col < X on a double is correct and unambiguous. No lexicographic surprise, because you're comparing numbers, not bytes.

3. And, crucially for prod — it's sargable (index-friendly). Here's the subtlety the whole thing was for. Wrap the column in a function — julianday(col) < X — and the index on col dies: the optimizer can't use an index over an expression of the column. But comparing the raw REAL column to a constant — col < julianday('2024-06-15') — is indexable: bare column on the left, constant on the right. So in SQL generation we put julianday(...) on the literal side, never on the column:

-- NOT this (kills the index on _date_create):
WHERE julianday(o._date_create) >= julianday('2023-01-01')
-- this (sargable):
WHERE o._date_create >= julianday('2023-01-01')

The column stores a Julian number → compare it to a Julian number computed from the literal, on the constant side.

Conversion: no magic, built-in .NET

Converting DateTime/DateTimeOffset ⟷ Julian is arithmetic on the built-in ToOADate/FromOADate. An OLE Automation date (epoch 1899-12-30) differs from a Julian day by exactly the constant 2415018.5:

internal static class SqliteJulian
{
    // Julian = OADate + 2415018.5. ToOADate/FromOADate are built-in and lossless
    // within double precision — the same precision SQLite's julianday() lives in.
    private const double OADateToJulianOffset = 2415018.5;

    // DateTimeOffset → UTC Julian. .UtcDateTime APPLIES the offset → the true UTC instant.
    public static double ToJulian(DateTimeOffset dto) => dto.UtcDateTime.ToOADate() + OADateToJulianOffset;

    // DateTime → UTC Julian. The clock value is treated as UTC per redb's contract
    // (NormalizeForStorage sets Kind=Utc without converting). ToOADate ignores Kind — they agree.
    public static double ToJulian(DateTime dt) => dt.ToOADate() + OADateToJulianOffset;

    // REAL Julian → DateTimeOffset(+00:00)
    public static DateTimeOffset FromJulian(double julian)
    {
        var utc = DateTime.SpecifyKind(DateTime.FromOADate(julian - OADateToJulianOffset), DateTimeKind.Utc);
        return new DateTimeOffset(utc, TimeSpan.Zero);
    }
}

Where it plugs in: four points

For dates not to lie, the REAL-Julian representation has to hold at every point where a value crosses the C# ⟷ SQLite boundary:

Write — the central parameter binder. Every write (base dates and props alike) goes through one place — CreateCommand in SqliteRedbConnection. There, DateTimeOffset/DateTime turn into double:

switch (param)
{
    case DateTimeOffset dto:
        // REAL Julian day (UTC) — SQLite's native date format.
        sqliteParam.Value = SqliteJulian.ToJulian(dto);
        break;
    case DateTime dt2:
        sqliteParam.Value = SqliteJulian.ToJulian(dt2);
        break;
    // ...
}

Read scalars — ConvertScalar. A value from SQLite arrives as double; for a temporal target we convert back:

if (targetType == typeof(DateTimeOffset))
    return (T)(object)(value is double jdo ? SqliteJulian.FromJulian(jdo)
        : value is DateTimeOffset d ? d
        : value is DateTime dt ? new DateTimeOffset(dt, TimeSpan.Zero)
        : DateTimeOffset.Parse(value.ToString()!, ...));

Read rows — MapRow. The same double → DateTimeOffset/DateTime/DateOnly when mapping columns to properties.

Native. get_object_json emits the date via strftime(ISO, col) (see the %% story), and pvt comparisons wrap the literal in julianday('<iso>').

Three CLR types on one column

The _values._DateTimeOffset column (REAL) serves three CLR types:

DateTimeOffset — directly.
DateTime — clock value as UTC (redb's contract).
DateOnly — UTC midnight.

(TimeOnly/TimeSpan go to _String.) The scheme's RTTI disambiguates them: the field's db-type tells the materializer what to unfold the double into.

Timezones: why `+4` resolves correctly

A recurring comment-section question: "if I write a DateTimeOffset with a +04:00 zone in LINQ, does it compare correctly against what's in the DB?" Yes, for two reasons:

C# side: ToJulian(DateTimeOffset) takes dto.UtcDateTime — and .UtcDateTime applies the offset and yields the true UTC instant. So +04:00 collapses to UTC before Julian.
Native side: even if an offset leaks into the literal, the comparison wraps it in julianday('<iso-with-offset>'), and julianday() parses the offset itself:

sqlite> SELECT julianday('2026-06-25T20:00:00+04:00') = julianday('2026-06-25T16:00:00Z');
1

Stored UTC → compared by UTC instant → it agrees with any incoming offset.

War story #2: analytics and a `FormatException` from nowhere

The trickiest part of the datetime story.

A normal object load goes through get_object_json — it emits the date as an ISO string (via strftime), and C# parses it normally. But analytics — MinRedbAsync/MaxRedbAsync, AggregateRedbAsync, windows, group-bys — bypass get_object_json. They pull the date column straight into the SELECT and hand the raw Julian number to the core converter. The converter expected a string or a DateTime. The result: a FormatException out of nowhere (and funnier still: elem.GetInt64() on a fractional 2460477.07 — because the code assumed an integer Unix timestamp).

The fix was a design fork. We could patch a SQLite hack right into the core — but redb.Core has no knowledge (and shouldn't) of Julian: that's a SQLite storage detail, and the core serves three dialects. PG/MSSql return dates fine, and dragging the word "Julian" into the shared converter would leak one provider's detail into all of them.

We did it through a neutral extension point. In the core, an optional "number → temporal type" hook, empty by default:

// redb.Core: the core does NOT know the word "Julian". Only: "if a NUMBER targets a
// date and a decoder is registered, ask it."
public static class TemporalDecoder
{
    public static Func<double, Type, object?>? NumericDecoder;

    public static bool IsTemporal(Type t) =>
        t == typeof(DateTime) || t == typeof(DateTimeOffset) || t == typeof(DateOnly);

    // Convert.ChangeType that first lets a number-to-date pass through the decoder.
    public static object ChangeType(object value, Type targetType) =>
        TryDecode(value, targetType, out var d) && d != null ? d
        : System.Convert.ChangeType(value, targetType);
}

And the SQLite provider itself registers the decoder — in SqliteDataSource's static constructor, which runs for both Free and Pro:

TemporalDecoder.NumericDecoder = static (julian, targetType) =>
{
    var dto = SqliteJulian.FromJulian(julian);
    if (targetType == typeof(DateTimeOffset)) return dto;
    if (targetType == typeof(DateOnly))       return DateOnly.FromDateTime(dto.UtcDateTime);
    return dto.UtcDateTime; // DateTime
};

Then two places in the core, through which all analytics materialization flows (for both Free and Pro, because Pro has no materializer of its own — it reuses the core converters):

JsonValueConverter — the Number branch → temporal type (group-by, window, projections).
A TemporalDecoder.ChangeType wrapper at scalar points (MinRedbAsync/MaxRedbAsync, AggregateResult.Get<T>).

PG/MSSql never return a number for a date — their NumericDecoder stays null, behavior unchanged to the byte. The constant 2415018.5 and the word "Julian" stay inside redb.SQLite, and the core stays storage-agnostic.

That, to my taste, is the shape of a right fix: the problem is local (SQLite stores dates as numbers), and the cure isn't smearing SQLite specifics across the core — it's one generic extension point that only the party who needs it ever pulls.

Part 3. The pvt compiler: how a filter becomes SQL

Since the engine is a filter-JSON-to-SQL translator, let's take apart a piece of that translator. This is the most "a database inside the database" part.

The filter JSON

C# folds a LINQ Where into a facet filter — JSON the native side understands. Say Where(e => e.LastName == "NullableTest") on a prop field gives:

{ "LastName": { "$eq": "NullableTest" } }

And WhereRedb(o => o.ParentId == null) on a base field (the 0$: marker means "this is base, not a prop"):

{ "0$:ParentId": null }

Combining the two conditions is an implicit $and over the object's keys:

{ "0$:ParentId": null, "LastName": { "$eq": "NullableTest" } }

The split: push vs residual

The key function is pvtSplitFilter. It divides the filter into two parts:

push — conditions on base fields and props that can be pushed inside the CTE (into the _objects/_values subquery).
residual — what's applied outside, on top of the assembled pivot.

That split decides which "shape" the query takes. There are three:

Shape A — pure-base flat: the filter is base-only, no props. No CTE at all: SELECT _id FROM _objects o WHERE o._id_scheme=? AND <push>.
narrow — props exist, the filter reduces to the pivot: build a _pvt_cte (pivoting the needed structures via MAX(...) FILTER (WHERE _id_structure=? AND _array_index IS NULL)), join _objects.
non-narrow — there are non-pushable checks (e.g. presence), an outer WHERE is needed.

The actual assembled SQL for Where(LastName) + WhereRedb(ParentId IS NULL) (narrow shape):

WITH _pvt_cte AS (
    SELECT v._id_object,
           MAX(v._String) FILTER (WHERE v._id_structure = 1000012 AND v._array_index IS NULL) AS "LastName"
    FROM _values v
    WHERE v._id_structure IN (1000012)
      AND v._id_object IN (
            SELECT o._id FROM _objects o
            WHERE o._id_scheme = 1000010 AND o._id_parent IS NULL   -- ← pushed base condition
          )
    GROUP BY v._id_object
)
SELECT o._id FROM _pvt_cte
JOIN _objects o ON o._id = _pvt_cte._id_object
WHERE "LastName" = 'NullableTest'                                    -- ← residual prop condition

Notice: the base condition o._id_parent IS NULL went inside the _objects subquery (push), and the prop condition on LastName stayed outside (residual). That's not incidental — it's exactly what pvtSplitFilter does, and exactly where we had a bug (next).

War story #3: a multi-key filter dropped `null`

WhereRedb(o => o.ParentId == null).Where(e => e.LastName == "X") on Free returned rows that have a parent. The IS NULL condition silently vanished — but only when combined with a prop filter. Base-only WhereRedb(o => o.ParentId == null) worked.

Diagnosis. Calling the native function directly on three filters:

-- 1) base IS NULL only — WORKS:
SELECT pvt_build_query_sql(1000010, '{"0$:ParentId":null}', ...);
→ ... WHERE o._id_scheme = 1000010 AND o._id_parent IS NULL

-- 2) base equality — WORKS:
SELECT pvt_build_query_sql(1000010, '{"0$:ParentId":5}', ...);
→ ... WHERE o._id_scheme = 1000010 AND o._id_parent = 5

-- 3) base IS NULL + prop — the base condition VANISHED:
SELECT pvt_build_query_sql(1000010, '{"0$:ParentId":null,"LastName":{"$eq":"X"}}', ...);
→ ... (only LastName in the CTE, no o._id_parent IS NULL)

So {"0$:ParentId":null} on its own is fine, but as part of multiple keys it's lost. The root is in pvtSplitFilter's multi-key branch. To split each key separately, it reassembles a single-key filter object per key via pvtSingleton:

static char *pvtSingleton(sqlite3 *db, const char *k, const char *v_json){
  sqlite3_stmt *st = 0; char *r = 0;
  sqlite3_prepare_v2(db, "SELECT json_object(?1, json(?2))", -1, &st, 0);
  // ...
}

And the loop took each key's value from json_each:

// WAS:
"SELECT key, value FROM json_each(?1)"

The trap: for a JSON null, the value column in json_each is SQL NULL. So v_json arrived as an empty string, json("") is a parse error, json_object(...) returned NULL, the singleton came out NULL → pvtSplitFilter on a NULL filter returned "nothing" → the condition silently disappeared. (The same would happen with a bare text value: json_each.value returns text without quotes, and json("NullableTest") is again a parse error.) The base-only path worked because it takes the value's type from a separate type column, where null is detected correctly.

The fix — reassemble the value into a valid JSON atom by type, in SQL, before pvtSingleton:

// NOW:
"SELECT key, CASE type "
"  WHEN 'text'  THEN json_quote(value) "   // "X" with quotes
"  WHEN 'null'  THEN 'null' "              // valid JSON null
"  WHEN 'true'  THEN 'true' "
"  WHEN 'false' THEN 'false' "
"  ELSE value END "                        // integer/real/object/array — already valid JSON
"FROM json_each(?1)"

After re-encoding, {"0$:ParentId":null} stays valid JSON, the singleton assembles, and the condition reaches push and attaches to the _objects subquery. Lesson: json_each.value is a lossy source — it drops type (null → SQL NULL, text → unquoted); if you reconstruct JSON from it, do it off the type column.

DistinctBy: emulating `DISTINCT ON` with `ROW_NUMBER()`

Postgres has DISTINCT ON (col) — "one row per value of col." SQLite has none. Pro already solved it in ProSqlBuilder via ROW_NUMBER(); on Free the native distinct_on was ignored (an explicit TODO), and DistinctBy(e => e.Department) returned duplicates.

Bringing it to parity. pvt_build_query_sql accepts a 12th argument distinct_on — but the wrapper function only read up to the 11th, so C# sent the param and the native side dropped it. The fix is threefold:

Read the 12th argument and thread it through.
Pull the distinct field into the pivot. If the field isn't mentioned in the filter/sort, it's not in the collected fields → not in the CTE → nothing to partition on. So the distinct field gets mixed into field collection (pvtCollectFields) by the same mechanism as ORDER BY.
Wrap the result in a _ranked CTE with ROW_NUMBER() and keep rn=1:

WITH _pvt_cte AS ( ... pivot Department ... ),
_ranked AS (
  SELECT o._id AS _id,
         ROW_NUMBER() OVER (PARTITION BY _pvt_cte."Department" ORDER BY o._id) AS _rn
  FROM _pvt_cte
  JOIN _objects o ON o._id = _pvt_cte._id_object
)
SELECT _id FROM _ranked WHERE _rn = 1

The partition expression resolves from field metadata: base → o.<column>, prop → _pvt_cte."<FieldName>" (the pivot column). The group representative is the row with the minimum o._id (same as Pro). All of this engages only when distinct_on is present; ordinary queries take the old path — zero regression risk for 99% of queries.

Part 4. Free vs Pro: where Pro accidentally reached into Free

Architecturally Free and Pro share the base providers (redb.Core) but diverge at materialization:

Free calls get_object_json (native) to assemble objects.
Pro materializes in C# (ProLazyPropsLoader, ProSqlBuilder) and must never call a native function.

And here a principled bug surfaced. DeleteSubtreeAsync (subtree delete) collects descendant ids via the base TreeProviderBase.CollectDescendantIds. Pro overrides the loading tree methods (GetChildren, GetPolymorphicChildren, LoadDynamicObject) with C# materialization — but it did not override CollectDescendantIds, and that one used a recipe with get_object_json:

-- Tree_SelectPolymorphicChildren — the recipe that called the native function:
SELECT o._id as ObjectId, o._id_scheme as SchemeId, get_object_json(o._id, 1) as JsonData
FROM _objects o WHERE o._id_parent = $1

On PG/MSSql this passes silently: get_object_json there is a server-side function present in every tier. On SQLite Pro the function isn't there (Pro doesn't load the native code) → a hard crash, no such function: get_object_json. And on PG/MSSql Pro it was silent waste: materializing each subtree node's full JSON only to throw the JSON away and take the _id.

The fix isn't a Pro override (that would leave the base calling get_object_json for a method that doesn't need JSON); it's removing JSON from the base method itself — it only needs an id list. We added an id-only recipe to all three dialects:

// ISqlDialect + PostgreSqlDialect / MsSqlDialect / SqliteDialect:
public string Tree_SelectChildrenIds() =>
    "SELECT o._id FROM _objects o WHERE o._id_parent = $1 ORDER BY o._name, o._id";

// CollectDescendantIds — was QueryAsync<ChildObjectInfo>(Tree_SelectPolymorphicChildren), now:
var childIds = await Context.QueryScalarListAsync<long>(Sql.Tree_SelectChildrenIds(), parentId);
foreach (var childId in childIds) { ids.Add(childId); await CollectDescendantIds(childId, ids, ...); }

Now the leak is closed at the source for every tier: Free doesn't materialize extra JSON for an id list, Pro doesn't reach into the native code, PG/MSSql Pro stop materializing for nothing. Pro source now has exactly zero get_object_json calls. And, incidentally, SQLite Pro turned out to be the perfect detector for these leaks: it crashes on any native call out of Pro — the thing PG/MSSql silently tolerate.

Also: `DeleteSubtree` and cascade

The same DeleteSubtree returned the wrong delete count. On SQLite the schema has FK _id_parent ... ON DELETE CASCADE — delete a parent and the children go by cascade. But changes() (rows-affected) does not count cascade-deleted rows. So DELETE WHERE _id IN (parent, children) could return 1 (only the parent deleted directly; children by cascade). We fixed the semantics: the method returns the size of the collected subtree (objectIds.Count), not the cascade-dependent rows-affected. On PG/MSSql (no cascade on _id_parent) it's the same number — no divergence.

Bool is an INTEGER

One more small one, surfaced in group-bys. SQLite has no boolean type — it stores 0/1 as INTEGER. In a pivot/projection, a bool value reaches the shared converter as a JSON number, and the bool branch in JsonValueConverter only caught true/string → the number 1 produced false. Group-by on a bool key collapsed (everything "false"). The fix — accept Number in the bool branch:

Type t when t == typeof(bool) => elem.ValueKind == JsonValueKind.True
    || (elem.ValueKind == JsonValueKind.Number && elem.TryGetDouble(out var bn) && bn != 0)
    || (elem.ValueKind == JsonValueKind.String && bool.TryParse(elem.GetString(), out var bl) && bl),

PG/MSSql send true/false — untouched.

Part 5. How to poke at it yourself

This isn't article pseudocode. The repo ships two tools you verify all of this with by hand.

redb.Examples — ~150 runnable examples that run on any provider, SQLite included:

dotnet run --project redb.Examples -- E021 E146 E148   # date filter, aggregates, windows

Flip AddRedb/AddRedbPro + UseSqlite and the same suite runs live on SQLite Free or Pro. The same code runs on Postgres/MSSql unchanged.

redb.CLI — a global .NET tool for schema and data management, supports sqlite across every command:

redb schema -p sqlite -o redb_sqlite.sql            # dump the full schema SQL (review/CI)
redb init   -p sqlite -c "Data Source=app.db"       # create the tables in an empty DB
redb export -p sqlite -c "Data Source=app.db" -o data.redb --compress
redb import -p sqlite -c "Data Source=app.db" -i data.redb --clean

And the part that matters — trust is verified by tests. SQLite Free and Pro each pass the integration suite 200/200 — the same suite that gates Postgres and MSSql. For a brand-new provider that's worth more than adjectives: same suite, same bar.

War story #4: the CLI that "supported" sqlite — but silently didn't

While preparing this post, I wanted to show redb schema -p sqlite — and walked straight into my own tooling landmine. redb.CLI's code did support sqlite: a full SqliteProvider, the ProviderFactory.Create("sqlite") factory, the redbSqlite.sql schema resource. The csproj did not:

<!-- redb.CLI.csproj — pulled the engine from an old NuGet version: -->
<PackageReference Include="redb.SQLite" Version="1.2.*" />

1.2.* is a version where the SQLite provider didn't exist at all (it's new, at 3.2.1). So typeof(redb.SQLite.RedbService).Assembly and the embedded redbSqlite.sql resource resolved against an assembly that doesn't have them, and any -p sqlite command silently drifted from the real code. The fix — point the references at the local projects (as redb.Examples already does):

<ProjectReference Include="..\redb.SQLite\redb.SQLite.csproj" />

Same moral as the %% story: "the code supports it" ≠ "the build sees it." A version pin is part of the contract too, and a stale pin breaks a feature as quietly as a typo in SQL. It's trivially checkable — by running the command itself: redb schema -p sqlite now dumps the real schema (REAL Julian, _DateTimeOffset REAL) instead of failing on an empty resource.

Part 6. Traps you will hit

This series is honest about "what's not done and what you'll trip over," so no glossing:

The .db path follows the working directory. A relative string (Data Source=app.db) creates the file relative to the process cwd, not the project folder. I lost a couple of hours to this myself: dotnet run from different directories wrote to different files, and tests "passed/failed" against different DBs. Use an absolute path or pin the cwd.
:memory: is per-connection. For a connection pool to see one in-memory DB you need Mode=Memory;Cache=Shared plus one held-open connection. That's SQLite's lifecycle, not redb's: close the last connection and the DB evaporates.
NUMERIC → REAL by default. Fast, but lossy past double range. An exact path via TEXT is a planned setting. A known SQLite weak spot.
SQLite is single-writer. One writer per file; redb sets busy_timeout for concurrent writes, but don't expect Postgres-grade parallelism. For embedded/local, that's normal.
Free's native binaries ship for Windows x64, Linux x64 and Linux arm64. All three are packed into runtimes/<rid>/native/ and delivered to framework-dependent builds by a buildTransitive .targets — the extension is loaded by an explicit path, so the file must physically land in your output, and NuGet doesn't flatten runtimes/ for a no-RID build. macOS (osx-x64/osx-arm64 .dylib) builds from the same CMake project but needs a macOS runner — the one remaining gap, slated for the CI matrix. Pro has no native dependency — it's already everywhere today, which is exactly what WASM/mobile need.
bool in raw form is 0/1. Remember it when debugging _Boolean/_value_bool: true is stored as 1.

None of these poke through ordinary code — but in a debug session each one saves an evening.

Part 7. Pro on mobile and in the browser — and yes, free

Back to what the whole SQLite effort was for.

Writing Blazor WebAssembly, MAUI, or a standalone client? You want SQLite Pro: pure C#, loads no native code, runs in the browser sandbox and on a phone. A typed LINQ store in a single file inside your app.

And the part that draws skepticism, so plainly: Pro for this is free.

Go to redbase.app, register, and email a key request — you get a free license key back.
No bank/payment details. No card asked. Registration is the key-issuing mechanism, not a sales funnel.
The key goes in .WithLicense(...); the wiring instructions are right there after you register.

The barrier to a client-side scenario is zero.

Wrap-up

The SQLite provider made us do two non-obvious things and catch three bugs that would've cost more in prod than any review.

The non-obvious things: move the whole query engine into a C extension where the database has no stored procedures (and where a % in your data breaks mprintf), and re-answer "how do you store a date" for a database that has no date type — REAL Julian in UTC, sargable comparisons, julianday() on the literal side, and a neutral core hook instead of leaking SQLite specifics.

The bugs: a silently-dropped IS NULL in a multi-key filter (json_each.value is lossy by type), DISTINCT ON via ROW_NUMBER() instead of an ignore, and Pro accidentally reaching into the Free-only get_object_json on the subtree-delete path.

These are exactly the spots where the "one LINQ for every database" abstraction either holds or leaks. Ours holds: Free and Pro are green at 200/200 on the same suite as the other dialects, and you can poke at it with redb.Examples and redb.CLI from the repo.

Repo, docs, packages — redbase.app. The stack is at 3.2.1; the two SQLite NuGet packages (redb.SQLite / redb.SQLite.Pro) are 3.2.1 — a buildTransitive .targets hotfix, see War story #5. Questions like "does it do X on SQLite," bug reports — bring them; the provider's new and the feedback channel is open.

SQLite provider for RedBase is coming. full LINQ, typed columns — same API as PostgreSQL and MSSQL. Free tier: native extension (.so / .dll / .dylib). Pro tier: pure C# — works in Blazor WASM. SQLite 3.44.0+. Follow if you want to know when it drops.

rinat kozin — Thu, 18 Jun 2026 19:00:50 +0000

.net

rinat kozin — Thu, 18 Jun 2026 16:38:21 +0000

Apache Camel for .NET, dissected: the HTTP connector with no ASP.NET MVC + the Content-Based Router pattern

rinat kozin — Thu, 18 Jun 2026 15:48:31 +0000

Series: redb ecosystem

This continues the redb.Route series. Earlier on dev.to:

I spent a year building Apache Camel for .NET. Here's the honest state of it.

redb.Route — Apache Camel for .NET: 22 transports, 30+ EIP patterns, compiled DSL

Enterprise Integration Patterns in .NET, the deep-dive series — Part 1: the four in-memory channels

redb.Route 3.0.1 — flat DSL navigation, CRTP refactor, and a silent null fix

redb.Route 3.1.0 — LLM(AI) as just another connector

Enterprise-grade AI integration: embedding LLMs into the business processes — redb.Route.Llm 3.1.1

Full list on the author's dev.to profile.

In redb.Route — our Apache Camel-style ESB for .NET — a route always reads the same way: From(source) → [processors] → To(sink). This installment takes one simple integration pattern and one connector and dissects both all the way down.

The pattern: the Content-Based Router — the most basic of the routing patterns from Hohpe & Woolf: look inside a message and decide where it goes next. In the DSL it's .Choice().When(...).Otherwise().
The connector: redb.Route.Http — built-in HTTP/HTTPS. On one side it's a producer (an HttpClient-based caller); on the other, a consumer (an embedded Kestrel server). No controllers, no [ApiController], no ASP.NET middleware pipeline you wire up by hand.

This is a long, technical piece. You'll get the five-line "hello world", but then we go into how the connector works internally: how a single Kestrel is shared across routes, how request headers and route values flow into the Exchange and back, how CORS actually works on a shared server, what happens with streaming, and why there isn't a single app.UseCors() in the codebase.

Every snippet is verified against redb.Route/src/redb.Route.Http; every example is lifted from the real redb.Route.Demo.

Part 0. The scenario everything hangs on

Take a down-to-earth task: an HTTP gateway. A POST /api/demo comes in, and inside we:

take the body,
look at the mode header and pick a processing branch accordingly — that's the Content-Based Router;
reply synchronously over the same HTTP request (request/reply).

Here's the skeleton (full version at the end), from redb.Route.Demo/Routes/MainPipelineRoutes.cs:

From("http:0.0.0.0:5088/api/demo?inOut=true")
    .RouteId("demo-http-entry")
    .ConvertBody<string>()

    .Choice()
        .When(e => GetHeader(e, "mode") == "full")
            .SetHeader("stamp.dsl", "full-branch")
        .When(e => GetHeader(e, "mode") == "short")
            .SetHeader("stamp.dsl", "short-branch")
        .Otherwise()
            .SetHeader("mode", "default")
            .SetHeader("stamp.dsl", "default-branch")
    .EndChoice()

    .SetHeader("Content-Type", "application/json")
    .SetBody(e => BuildResponse(e));

One From brings up an HTTP server on port 5088, one .Choice() decides the message's fate, one .SetBody(...) builds the reply. Now let's see how it works.

Part 1. Content-Based Router — the simple pattern, honestly dissected

What it actually is

The Content-Based Router answers one question — "where next?" — by looking at the message itself, not at external configuration. The textbook example: orders with region=EU go to one handler, region=US to another, everything else to a default.

In redb.Route this is the ChoiceProcessor (redb.Route/src/redb.Route/Processors/ChoiceProcessor.cs), and in the DSL it's a .Choice() block:

.Choice()
    .When(<predicate>)   // branch 1
        ...processors...
    .When(<predicate>)   // branch 2
        ...processors...
    .Otherwise()         // default branch (optional)
        ...processors...
.EndChoice()

Semantics are exactly a switch: predicates are checked top to bottom, the first branch whose predicate returns true runs, the rest are skipped. If none match and there's an .Otherwise(), it runs; if there's no .Otherwise(), the message passes through untouched.

Two ways to express a predicate

1. A lambda — when the condition is easier to write as code:

.Choice()
    .When(e => GetHeader(e, "mode") == "full")  ...
    .When(e => GetHeader(e, "mode") == "short") ...
    .Otherwise() ...
.EndChoice()

2. Fluent predicates over the expression engine — when you want it declarative. From redb.Route.Demo/Routes/DataObservabilityRoutes.cs:

.Choice()
    .When(Header("amount").isGreaterThanOrEqualTo(1000).Matches, w => w
        .SetHeader("tier", "gold"))
    .When(Header("amount").isBetween(500, 999).Matches, w => w
        .SetHeader("tier", "silver"))
    .When(Header("amount").isLessThan(500).Matches, w => w
        .SetHeader("tier", "bronze"))
    .Otherwise(o => o
        .SetHeader("tier", "unknown"))

Header("amount").isBetween(500, 999) isn't a closure — it's a real IPredicate, compiled once and cached as a delegate forever after. Under the hood it's the series' compiled expression engine (Tokenizer → Parser → AST → System.Linq.Expressions → IL), but that's a whole article of its own.

Why pair it with HTTP

The Content-Based Router and an HTTP gateway are made for each other. On the way in, the HTTP consumer decomposes the request into Exchange headers (more below): method, path, query params, route params, every HTTP header. Any of them is ready material for .When(...):

.Choice()
    .When(e => GetHeader(e, "redbHttp.Method") == "DELETE")        ... // by method
    .When(e => GetHeader(e, "X-Tenant") == "acme")                 ... // by header
    .When(e => GetHeader(e, "redbHttp.QueryParam.debug") == "1")   ... // by query
.EndChoice()

The router never touches HTTP itself — it works on an already-decoded Exchange. That's the whole point of a connector: turn transport into a message so the integration patterns know nothing about transport.

Straight from production

Here's a production route from the TsUM system (delivery monitoring), verbatim. HTTP entry + Content-Based Router by method — GET and POST on one path fan out to different handlers:

From("http:0.0.0.0:5090/api/tsum/user-filters?inOut=true&cors=true&corsOrigins=*")
    .RouteId("tsum-api-user-filters")
    .Process(Auth.ProcessAsync)                 // JWT auth — just a processor
    .ConvertBody<string>()
    .Choice()
        .When(e => e.In.Headers.TryGetValue("redbHttp.Method", out var m) && m?.ToString() == "POST")
            .ProcessWithRedb((redb, exchange, ct) => HandlePost(redb, exchange))
        .Otherwise()
            .ProcessWithRedb((redb, exchange, ct) => HandleGet(redb, exchange))
    .EndChoice();

You can see everything we're about to cover in one shot: the HTTP consumer on port 5090 (inOut=true, cors=true&corsOrigins=*), the Content-Based Router over redbHttp.Method, and authentication as an ordinary processor in the chain — no [Authorize] attributes. Now let's dissect how each piece works inside.

Part 2. The HTTP connector from 10,000 feet

The same http/https scheme yields two fundamentally different roles depending on whether it sits in From(...) or To(...):

Role	Class	Built on	What it does
Consumer (`From`)	`HttpConsumer`	Kestrel	Brings up an embedded HTTP server and accepts inbound requests
Producer (`To`)	`HttpProducer`	`HttpClient`	Sends outbound HTTP requests to a remote address

The DSL entry points are the static Http and Https classes (redb.Route.Http/Fluent/HttpDsl.cs):

// Consumer — listen for inbound
.From(Http.Listen("/webhook").Port(8080).Cors("https://app.example.com").InOut())

// Producer — send outbound
.To(Http.Post("api.example.com/orders").BearerAuth().Timeout(5000))

Or the raw URI string (the builder compiles to exactly this):

.From("http:0.0.0.0:8080/webhook?cors=true&corsOrigins=https://app.example.com&inOut=true")
.To("http:api.example.com/orders?method=POST&timeout=5000")

HTTP methods: the consumer listens, the producer sends

Methods (GET/POST/PUT/…) are set differently for the two roles — and there's more than one way. First the producer (To) — which method to send:

// fluent — the method is chosen by the factory method:
.To(Http.Get("api.example.com/users"))           // GET
.To(Http.Post("api.example.com/users"))          // POST
.To(Http.Put("api.example.com/users/42"))        // PUT
.To(Http.Delete("api.example.com/users/42"))     // DELETE
.To(Http.Patch("api.example.com/users/42"))      // PATCH
.To(Http.Head("api.example.com/users/42"))       // HEAD

// the same as a URI string (singular parameter — method):
.To("http:api.example.com/users?method=POST")

// the method can be overridden per-message by a header — it wins over the option:
.SetHeader("redbHttp.Method", "PUT")
.To(Http.Post("api.example.com/users/42"))        // actually sends PUT

Now the consumer (From) — which methods to accept:

// by default ALL methods are accepted:
.From(Http.Listen("/webhook").Port(8080))

// restrict the allowed set (anything else → 405 Method Not Allowed):
.From(Http.Listen("/webhook").Port(8080).Methods("POST"))
.From(Http.Listen("/orders").Port(8080).Methods("POST,PUT"))

// the same as a URI string (plural parameter — methods):
.From("http:0.0.0.0:8080/webhook?methods=POST")

// shorthand: a method prefix right in the path (for the consumer):
.From("http:POST:0.0.0.0:8080/webhook")
.From("http:GET:/health")

The terminology difference is easy to trip over:

	Producer (`To`)	Consumer (`From`)
URI parameter	`method` (singular)	`methods` (plural, comma-separated)
Meaning	which method to send	which methods to accept (empty = all)
Default	`GET`	all methods
Per-message override	`redbHttp.Method` header	— (the filter is static)

The prefix shorthand (http:POST:/...) is a special case: it sets both values at once (method and methods), because the same string can serve as either a producer or a consumer.

And the typical move when different methods hit one path: accept several and fan them out with a Content-Based Router on redbHttp.Method (this is exactly the production example from Part 1):

.From(Http.Listen("/api/tsum/user-filters").Port(5090).Methods("GET,POST").Cors("*").InOut())
    .Choice()
        .When(e => GetHeader(e, "redbHttp.Method") == "POST")
            .ProcessWithRedb((redb, ex, ct) => HandlePost(redb, ex))   // write
        .Otherwise()
            .ProcessWithRedb((redb, ex, ct) => HandleGet(redb, ex))    // read
    .EndChoice();

We'll dissect both roles separately — but first, the big question.

Part 3. "Where's ASP.NET?" — there isn't any, on purpose

When a .NET developer hears "embedded HTTP server", they picture WebApplication, controllers, [HttpPost], filters, model binding, app.UseRouting(), app.UseCors(), a DI middleware pipeline. The redb.Route HTTP connector has none of that. There's Kestrel — bare, with no MVC layer on top.

Here's how the server comes up (SharedHttpServerManager.StartServer, abridged):

var builder = WebApplication.CreateSlimBuilder();   // slim — no MVC, no extra services

builder.WebHost.ConfigureKestrel(kestrel =>
{
    kestrel.Listen(IPAddress.Parse(entry.Host), entry.Port, listenOptions =>
    {
        listenOptions.Protocols = protocols;          // HTTP/1, /2, /3 — see below
        if (entry.Ssl) listenOptions.UseHttps(entry.SslCertPath, entry.SslCertPassword);
    });
    kestrel.Limits.MaxRequestBodySize = entry.MaxRequestBodySize > 0
        ? entry.MaxRequestBodySize : null;
});

builder.Logging.ClearProviders();
var app = builder.Build();

// ONE catch-all endpoint — we route from here ourselves
app.Map("/{**path}", (HttpContext ctx) => HandleCatchAll(entry, ctx));
app.MapGet("/",    (HttpContext ctx) => HandleCatchAll(entry, ctx));
app.MapPost("/",   (HttpContext ctx) => HandleCatchAll(entry, ctx));
// ... PUT/DELETE/PATCH/HEAD/OPTIONS on "/"
await app.StartAsync(ct);

Note the key decisions:

WebApplication.CreateSlimBuilder(), not CreateBuilder(). The slim builder doesn't drag in MVC, Razor, ASP.NET auth, or the rest of the scaffolding — only what Kestrel needs.
Exactly one catch-all route /{**path}. ASP.NET routing is used solely to intercept everything and hand it to our own dispatcher, HandleCatchAll. No controller matching.
builder.Logging.ClearProviders() — the server stays quiet on the host console; logs go through the route's logger.

Why? Because redb.Route is an integration engine, and HTTP is just transport to it — the same as Kafka or RabbitMQ. A route shouldn't know Kestrel is behind it: it gets an Exchange. ASP.NET controllers would impose their own model (attributes, model binding, ActionResult) that's redundant and alien inside a DSL route.

One Kestrel per process, not per route — and Tsak relies on it

A frequent question: "if my app already runs on ASP.NET/Kestrel (say, inside a Tsak worker), does the connector reuse the server or spawn new ones?"

First, what the connector does not do: it doesn't graft onto an external ASP.NET pipeline. The redb.Route.Http project has zero integration points with an external host (no IApplicationBuilder, no UseEndpoints, no IServer — none of it). It stands up its own Kestrel via WebApplication.CreateSlimBuilder().

But "stands up its own" ≠ "spawns instances." The key is that SharedHttpServerManager is registered in DI as a singleton (redb.Route.Http/Extensions/ServiceCollectionExtensions.cs):

public static IServiceCollection AddRedbRouteHttp(this IServiceCollection services, ...)
{
    services.AddSingleton<SharedHttpServerManager>();   // ← one server manager per process
    services.AddSingleton(sp => { var c = new HttpComponent();
        c.ServerManager = sp.GetRequiredService<SharedHttpServerManager>(); ... return c; });
    services.AddSingleton(sp => { var c = new HttpsComponent(); ... });
    ...
}

One manager per process means one Kestrel pool, shared across all route contexts. And Tsak leans on exactly this. Its worker is a plain Host.CreateDefaultBuilder (not a WebApplication) — it has no Kestrel of its own. Even Tsak's own REST admin API (the _system context, port 9090 by default) is not a separate web server — it's an ordinary redb.Route HTTP route brought up through that same singleton manager (redb.Tsak.Core/Services/SystemContextBuilder.cs):

// Tsak registers the HTTP connector itself...
services.AddRedbRouteHttp();   // redb.Tsak.Core/Extensions/ServiceCollectionExtensions.cs

// ...and brings up its admin API as a regular route on the shared manager:
var listenUri = $"http:{host}:{port}/{{**path}}?host={host}&port={port}&inOut=true";
routeContext.AddRoutes(r => r.From(listenUri).Process(/* bridge → auth → dispatch */));

So nothing is "forwarded from the host's Kestrel" — on the contrary, the host (Tsak) brings up Kestrel through the connector and reuses it. Any route targeting the same (host, port) joins the already-running server instead of starting a second one. Tsak even mounts its system-echo route on the admin port — and they don't collide: the specificity ordering from Part 4 separates the concrete /api/echo from the catch-all {**path} (called out in a comment in SystemContextBuilder).

Without Tsak — same thing, you just wire the manager yourself

Tsak isn't magic here: Kestrel is always brought up by SharedHttpServerManager; Tsak is merely a host that registers that manager and routes through it. In a standalone app (no Tsak) you wire the manager by hand. Here's a bare RouteContext from the Llm.HttpShell demo — no DI, no Tsak:

var ctx = new RouteContext(sp, contextId: "llm-http-shell");
ctx.AddComponent(new HttpComponent { ServerManager = new SharedHttpServerManager() });
// ...
ctx.AddRoutes(r => r.From("http:0.0.0.0:5088/api/llm/shell?inOut=true") ... );

Or the same through DI — AddRedbRouteHttp() registers that same singleton manager for you. Either way, the first From("http:host:port/...") that starts brings up a fresh Kestrel via CreateSlimBuilder() for that (host, port) pair, and the rest of the routes on the same (host, port) join it.

Subtlety: pooling works within a single SharedHttpServerManager instance. Create two separate managers and point both at one port and you get a socket-bind conflict, not sharing. The "one Kestrel per (host, port)" guarantee comes from a shared manager — a singleton out of the box under Tsak, and your responsibility standalone.

The practical takeaway: within a process (and one manager) there are exactly as many Kestrels as there are distinct (host, port) pairs. Mounting a route on a port another redb route already listens on (including Tsak's admin port) is fine — that's the whole "don't multiply" point. A socket-bind conflict only happens if a foreign, non-redb server already grabbed the port.

Why bus frameworks like MassTransit don't have this

It's worth contrasting with MassTransit — one of the most popular .NET messaging frameworks. It has no HTTP consumer, no embedded server, no "http as a transport." And that's not an omission; it follows from the architecture.

MassTransit is a message bus over brokers: RabbitMQ, Azure Service Bus, Amazon SQS, plus Kafka/Event Hubs as "riders." Its model is asynchronous broker-mediated delivery with guarantees, retries, and sagas; consumers are keyed to a message type (IConsumer<TMessage>), not a URI endpoint. HTTP doesn't fit that picture: synchronous request/reply contradicts the async/durable bus model. So MassTransit leaves HTTP ingress to ASP.NET — you stand up a controller or minimal API and Publish/Send to the bus from there. The "HTTP → message" boundary lives outside the framework, by hand, in your host code.

redb.Route (like Apache Camel, which it follows) is built differently: it's a mediation engine, and to it HTTP is just another transport, the same as Kafka or Rabbit. An HTTP request is normalized into the same Exchange a broker message becomes, and flows through the same EIP processors. That's why From("http:...") exists as a first-class route source, the connector owns Kestrel itself, and an "HTTP → Kafka → SQL → reply" bridge is one DSL chain without leaving the framework.

These are different tools for different jobs, not "better/worse": MassTransit shines at reliable broker delivery and sagas over queues; Camel-style engines shine at stitching together heterogeneous transports and routing by content. An embedded HTTP server is a natural part of the second approach and fundamentally alien to the first.

Part 3½. "But I love controllers" — `redb.Route.Controllers`

This is where an indignant voice usually pipes up: "Attributes, [HttpGet], model binding — I like that, I don't want to write a .Choice() per endpoint!" Fair. That's why there's a separate package: redb.Route.Controllers. It hands you back the familiar MVC-controller ergonomics, but it does not hand you back the ASP.NET hosting model. Here's the trick.

A controller that looks like ASP.NET — but isn't

Here's a working controller (from the redb.Route.Tests.Controllers tests):

[Route("modules")]
public class ModulesController : RedbController
{
    [HttpGet]
    public string[] GetAll() => ["module1", "module2"];

    [HttpGet("{id}")]
    public string GetById([FromRoute("id")] string id) => $"module-{id}";

    [HttpPost]
    public object Create([FromBody] CreateModuleRequest request) =>
        new { created = request.Name };

    [HttpPut("{id}")]
    public object Update([FromRoute("id")] string id, [FromBody] CreateModuleRequest request) =>
        new { updated = id, name = request.Name };

    [HttpDelete("{id}")]
    public void Delete([FromRoute("id")] string id) { }
}

Painfully familiar: [Route] on the class, [HttpGet]/[HttpPost]/[HttpPut]/[HttpDelete]/[HttpPatch] on methods (with an optional sub-template "{id}"), parameter binding via [FromBody], [FromRoute], [FromQuery], [FromHeader], [FromProperty]. Return an object and it goes out as JSON.

But two differences are fundamental:

The base class is RedbController, not ControllerBase. No HttpContext, no IActionResult, no [ApiController]. Instead, two properties: Context (the route context) and Exchange (the current message). The controller sees an Exchange, not HTTP.
The controller is transport-agnostic. It knows nothing about HTTP. That matters one paragraph from now.

How a controller enters a route

A controller isn't an endpoint — it's a processor inside a route. You mount it on an HTTP entry via .RedbHttpController<T>():

From("http:0.0.0.0:5088/api/{**path}?inOut=true")
    .RouteId("modules-api")
    .RedbHttpController<ModulesController>();

Or via a registry with several controllers (or an assembly scan):

var registry = new ControllerRegistry();
registry.RegisterController(typeof(ModulesController));
registry.RegisterController(typeof(ContextsController));
// or: registry.RegisterAssembly(typeof(ModulesController).Assembly);

From("http:0.0.0.0:5088/api/{**path}?inOut=true")
    .RedbHttpController(registry);

Note the {**path} — the HTTP consumer from Part 5 catches everything under /api, drops redbHttp.Method, redbHttp.Path, redbHttp.RouteParam.*, redbHttp.QueryParam.* into the Exchange, and the HttpControllerDispatcher parses those and finds the right action. No manual header translation:

// HttpControllerDispatcher.Process (abridged)
var method = exchange.In.GetHeader<string>("redbHttp.Method");
var path   = exchange.In.GetHeader<string>("redbHttp.Path");
var action = _registry.Resolve(method, normalizedPath, out var routeParams);
if (action is null) { WriteError(exchange, 404, "NotFound", ...); return; }

Routing and binding — its own, not ASP.NET's

ControllerRegistry.Resolve matches (method, path) to an action segment by segment, picking the most specific one (literals beat {param}): GET /me/sessions/current beats GET /me/sessions/{id}. Same specificity principle as the shared server in Part 4, just at the controller level.

Parameter binding (ResolveHttpParameter) is exactly what the attributes promise: [FromBody] is JSON-deserialized from the byte[], [FromRoute] comes from the template, [FromQuery] from redbHttp.QueryParam.*, [FromHeader] / [FromProperty] from the Exchange headers/properties. With no attribute, it tries a route param by name, otherwise a complex type is bound from the body.

The response is assembled like this: return an object → JSON (camelCase, with UnsafeRelaxedJsonEscaping so Cyrillic and emoji don't become А), status 200; return null/void → 204; throw → an error envelope and 500 (a route miss → 404). The dispatcher sets status.code and redbHttp.ResponseCode, and the HTTP consumer from Part 5 picks them up. The loop closes.

Why this way, not "the ASP.NET way"

Here's the whole point. The same ModulesController, without changing a line, can be invoked over something other than HTTP:

// same controller — over gRPC
From(grpcConsumer).RedbGrpcController<ModulesController>();

// same controller — over SignalR
From(signalRConsumer).RedbSignalRController<ModulesController>();

RedbController is transport-agnostic precisely because it works with an Exchange, not an HttpContext. An ASP.NET controller can't do that — it's welded to the HTTP pipeline. And since .RedbHttpController<T>() is just a processor, it composes with the rest of the DSL: put .Throttle() before it, .WireTap() after it, wrap it in OnException/TryCatch, combine it with the .Choice() from Part 1.

So: love controllers? Use controllers. Just know that under them is not ASP.NET MVC but the same Exchange and the same route pipeline. You get the ergonomics without inheriting the hosting model.

And this isn't theory — Tsak itself runs on it

The best proof the approach is battle-tested: Tsak's entire REST admin API is built exactly this way. ContextsController, RoutesController, ModulesController, AuthController, UsersController, SchedulerController, LogsController, and a dozen more (redb.Tsak.Core/Controllers) all inherit RedbController and carry the same [Route] / [HttpGet] / [HttpPost] / [FromRoute] / [FromQuery]. Here's a slice of the real ContextsController:

[Route("/api/contexts")]
public class ContextsController : RedbController
{
    [HttpGet("")]
    public object? ListContexts() => /* ... */;

    [HttpGet("/{name}")]
    public object? GetContext([FromRoute("name")] string name) => /* ... */;

    [HttpPost("/{name}/stop")]
    public async Task<object?> StopContext(
        [FromRoute("name")] string name,
        [FromQuery("timeoutSeconds")] int? timeoutSeconds = null) => /* ... */;
}

Tsak registers their assembly (ControllerRegistry.RegisterAssembly) and dispatches them via ControllerDispatcherProcessor in the _system context — on the same HTTP connector as everything else. So the controllers are as production-hardened as the HTTP consumer itself: the Tsak dashboard and CLI talk to exactly these.

A full treatment of redb.Route.Controllers (the registry, the IControllerActionFilter action filters, the gRPC/SignalR dispatchers, the error envelope) is its own article in the series. Here it's just to put the "where are my controllers" question to rest.

Part 4. One Kestrel per (host, port) — `SharedHttpServerManager`

The least obvious part of the consumer is that multiple routes can listen on one port. If you have three From(...) on 0.0.0.0:5088 with different paths (/api/demo, /api/echo, /api/llm/ask), you get one Kestrel, not three.

SharedHttpServerManager owns this. The key is the (host, port) pair:

private readonly ConcurrentDictionary<string, ServerEntry> _servers = new(...);
private static string BuildKey(string host, int port) => $"{host}:{port}";

Registering a route

When a consumer starts, it doesn't "create a server" — it registers a route on the server for its (host, port). The server is created lazily, on the first registration:

// HttpConsumer.Start (abridged)
_registration = _serverManager.RegisterRoute(
    host, port, path, _options.Methods, HandleRequest,
    ssl, _options.SslCertPath, _options.SslCertPassword,
    corsOptions, _options.MaxRequestBodySize, _options.Protocol);

await _serverManager.EnsureStarted(host, port, ct);
BaseUrl = _serverManager.GetBaseUrl(host, port);   // e.g. "http://localhost:5088"

RegisterRoute drops a RouteRegistration (path template + methods + handler + CORS) into the ServerEntry's route list. EnsureStarted brings up Kestrel if it isn't running; if it already is, it's a no-op.

Dispatch: a route table of its own

Every request lands in one HandleCatchAll, which finds the matching route itself:

private static async Task HandleCatchAll(ServerEntry entry, HttpContext ctx)
{
    var match = entry.MatchRoute(ctx.Request.Path, ctx.Request.Method);

    if (match.Registration is null)
    {
        // path matched but method didn't → 405; otherwise → 404
        ctx.Response.StatusCode = match.PathMatched
            ? StatusCodes.Status405MethodNotAllowed
            : StatusCodes.Status404NotFound;
        return;
    }

    if (match.RouteValues is not null)
        ctx.Items["__redbRouteValues"] = match.RouteValues;   // {id} etc. — into the Exchange next

    await match.Registration.Handler(ctx);
}

Two subtleties worth knowing:

1. 404 vs 405. If the path matched but the method isn't allowed, you get an honest 405 Method Not Allowed, not a 404. Small, but correct.

2. Path templates and specificity ordering. Paths are parsed via TemplateParser/TemplateMatcher from ASP.NET routing — {id} parameters and {**rest} catch-alls are supported. But the check order is not registration order; it's by descending specificity (ServerEntry.GetCompiled):

_compiled = built
    .OrderBy(x => x.spec.HasCatchAll ? 1 : 0)   // concrete paths first, catch-all last
    .ThenByDescending(x => x.spec.Literals)      // more literal segments = more specific
    .ThenBy(x => x.spec.Parameters)              // fewer parameters = more specific
    .ThenBy(x => x.order)                        // ties: stable, by registration order
    .Select(...).ToArray();

Why? So a concrete /api/echo always beats a catch-all /{**path} registered on the same port, even if the catch-all was registered first. Without this rule, a catch-all would swallow every later route. The behavior matches what you intuitively expect from ASP.NET routing.

Lifecycle: reference counting

A server lives exactly as long as it has at least one route. When a consumer stops:

// HttpConsumer.Stop
_serverManager.UnregisterRoute(_registration);
await _serverManager.StopIfEmpty(host, port, ct);

StopIfEmpty stops and unloads Kestrel only if no routes remain:

public async Task StopIfEmpty(string host, int port, ...)
{
    if (entry.Routes.Count > 0) return;   // someone's still listening — leave it
    _servers.TryRemove(key, out _);
    await StopServer(entry, ct);          // graceful stop with a 5s timeout
}

So if you stop one of three routes on port 5088, the server keeps running for the other two. Stop the last one, and Kestrel goes down. This lets you add and remove routes on the fly (e.g. from a dashboard: tsak route start demo-http-echo / stop) without bouncing the whole server.

Guard against mismatched schemes

You can't bind both HTTP and HTTPS on the same (host, port) — the manager throws on registration:

if (entry.Ssl != ssl)
    throw new InvalidOperationException(
        $"Server on {host}:{port} is already registered as {(entry.Ssl ? "HTTPS" : "HTTP")}...");

Part 5. Consumer: how an HTTP request becomes an `Exchange`

This is the heart of the inbound side — HttpConsumer.BuildExchange. Let's see exactly what reaches a route.

The request body

if (request.ContentLength > 0 || request.ContentType is not null)
{
    if (_options.StreamRequest)
        body = request.Body;                       // the stream as-is (passthrough)
    else
    {
        using var ms = new MemoryStream();
        await request.Body.CopyToAsync(ms, ...);
        body = ms.ToArray();                        // buffer into a byte[]
    }
}
var message = new Message(body);

By default the body is buffered into a byte[]. That's why you almost always see .ConvertBody<string>() right after From — to turn bytes into a string. With streamRequest=true the body stays a Stream (for large uploads), and an important detail from the code comment: that stream is owned by Kestrel, Exchange.DisposeAsync does not close it, but it stays valid until the response is written.

Headers: what the connector puts into the `Exchange`

This is probably the single most useful reference table in the article. The consumer decomposes the request into Exchange headers under the redbHttp. prefix (HttpHeaders.cs):

Exchange header	What it holds	Example
`redbHttp.Method`	HTTP method	`POST`
`redbHttp.Path`	request path	`/api/demo`
`redbHttp.Url`	full URL	`http://localhost:5088/api/demo?x=1`
`redbHttp.Port`	server port (int)	`5088`
`redbHttp.Query`	raw query string	`x=1&y=2`
`redbHttp.QueryParam.<name>`	one query parameter	`redbHttp.QueryParam.x` = `1`
`redbHttp.RouteParam.<name>`	one path-template value	`/users/{id}` → `redbHttp.RouteParam.id`
`redbHttp.RemoteAddress`	client IP	`127.0.0.1`
`<any HTTP header>`	as-is	`Content-Type`, `Authorization`, `X-Chat-Id`…

A few implementation details that matter:

Multi-value query/headers. If a parameter repeats (?tag=a&tag=b), the values are joined with a comma:

message.Headers[$"redbHttp.QueryParam.{qp.Key}"] = qp.Value.Count switch
{
    0 => string.Empty,
    1 => (object)qp.Value[0]!,
    _ => string.Join(",", qp.Value!)
};

Route values from the template. Remember ctx.Items["__redbRouteValues"] from the dispatcher? Here's where they're unpacked:

if (httpContext.Items.TryGetValue("__redbRouteValues", out var rvObj)
    && rvObj is RouteValueDictionary routeValues)
{
    foreach (var (key, value) in routeValues)
        if (value is not null)
            message.Headers[$"redbHttp.RouteParam.{key}"] = value;
}

So From("http:0.0.0.0:8080/users/{id}") gives you ${header.redbHttp.RouteParam.id} in the route.

HTTP/2 pseudo-headers are filtered out. Headers like :method, :path (HTTP/2) are skipped — if (header.Key.StartsWith(':')) continue;.

Remembering inbound header names. Subtle but important. The connector collects the names of all inbound headers into a set and stores it in the exchange properties:

exchange.Properties["redbHttp.RequestHeaderNames"] = requestHeaderNames;

Why — becomes clear on the response side: so request headers are not reflected back into the response. Without it, an inbound Host or User-Agent could accidentally ride back to the client in the reply.

Exchange pattern: InOnly vs InOut

exchange.Pattern = _options.InOut ? ExchangePattern.InOut : ExchangePattern.InOnly;

InOnly (default) — fire-and-forget. The server replies with an empty 200 OK immediately, and the route runs "in the background" relative to the response. This is a webhook receiver: "got it, thanks."
InOut (?inOut=true) — request/reply. The server waits for the route to finish and returns the result as the HTTP response. This is an API endpoint.

In practice: to return a body in the response you need inOut=true. Otherwise the body you assembled with .SetBody(...) goes nowhere (see WriteResponse — all body writing is under if (_options.InOut)).

The response: how an `Exchange` becomes HTTP again

WriteResponse assembles the HTTP response. Status code resolution order (by descending priority):

var statusCode = _options.ResponseCode;                       // 3. options default (200)
if (responseMsg.Headers.TryGetValue("redbHttp.ResponseCode", out var rc)) ...   // 1. explicit header
else if (responseMsg.Headers.TryGetValue("status.code", out var sc)) ...        // 2. transport-neutral fallback

So from a route you can return, say, 404 just by setting a header:

.SetHeader("redbHttp.ResponseCode", 404)

Response Content-Type follows a similar chain: redbHttp.ResponseContentType → Message.ContentType → options default (application/json).

Carrying headers into the response. This is where that RequestHeaderNames set earns its keep. A message header makes it into the HTTP response only if it clears several filters:

foreach (var (key, value) in responseMsg.Headers)
{
    if (value is null) continue;
    if (requestHeaderNames?.Contains(key) == true) continue;  // don't reflect request headers
    if (HttpHeaders.NonBridgedHeaders.Contains(key)) continue; // hop-by-hop and internal
    if (HttpHeaders.IsRedbHeader(key)) continue;               // redbHttp.* — internal
    if (IsInternalHeader(key)) continue;                       // redb*/Camel* — internal
    // ... set with multi-value support
}

And a special touch for Set-Cookie and other multi-value headers — StringValues is used so ASP.NET emits multiple header lines instead of one stringified array:

StringValues sv = value switch
{
    string s => s,
    string[] arr => arr,
    IEnumerable seq when value is not string =>
        seq.Cast<object?>().Select(o => o?.ToString() ?? "").ToArray(),
    _ => value.ToString()
};
if (ContainsInvalidHeaderValueCharacters(sv)) continue;  // Kestrel rejects control / non-ASCII
httpContext.Response.Headers.TryAdd(key, sv);

A gotcha from the repo's history. Response headers are copied always, even when the body is empty. Otherwise body-less responses (a 302 redirect, a 204 No Content, a Set-Cookie-only reply) would silently drop Location/Set-Cookie. It's called out in a code comment.

Part 6. CORS on a shared server — without `app.UseCors()`

CORS in ASP.NET means middleware and named policies. Here there's no ASP.NET CORS middleware at all. Instead there's one dispatch layer per server that selects the policy by the matched route. Why: a single (host, port) hosts different routes, and each can carry its own CORS policy. A classic UseCors with one policy per server can't do that.

The CORS parameters

At the endpoint level (HttpEndpointOptions):

URI parameter	Property	Meaning
`cors=true`	`Cors`	enable CORS for the route
`corsOrigins=...`	`CorsOrigins`	comma-separated origin whitelist, or `*`
`corsCredentials=true`	`CorsCredentials`	allow `Access-Control-Allow-Credentials`
— (code only)	`CorsOriginsResolver`	a `HttpRequest → string?` delegate for dynamic origin selection

In the fluent DSL:

.From(Http.Listen("/api").Port(8080).Cors("https://app.example.com").CorsCredentials())

Plus global defaults for the whole component, via DI:

services.AddRedbRouteHttp(cors =>
{
    cors.Enabled = true;
    cors.Origins = "https://example.com";
});

Endpoint parameters always override globals (HttpComponent.ApplyCorsDefaults).

No implicit `*`

A deliberate decision: if cors=true, you must supply either corsOrigins (including an explicit "*" for public endpoints) or a resolver. Otherwise it throws at startup (HttpEndpointOptions.Validate):

if (Cors && string.IsNullOrEmpty(CorsOrigins) && CorsOriginsResolver is null)
    throw new ArgumentException(
        "Cors=true requires CorsOrigins (use \"*\" for public endpoints) or CorsOriginsResolver to be set.");

Why: the old implicit * is a classic footgun. Combined with credentials, the browser silently rejects it, and the developer burns an afternoon wondering why "CORS doesn't work." Far better to fail fast at startup with a clear message.

How the dispatcher works (`CorsDispatchMiddleware`)

The layer is installed once per server, and only if at least one route declared CORS (entry.CorsEnabled). For each request:

var route = entry.MatchByPath(requestPath);   // NOTE: by path, method-agnostic
var cors = route?.Cors;
if (cors is null) { await next(); return; }    // a route without CORS — the layer is transparent

Matching by path, ignoring method is deliberate — so an OPTIONS preflight finds the route's policy even when OPTIONS isn't in the route's allowed-methods list.

Then origin resolution:

var resolved = ResolveOrigin(cors, ctx.Request, requestOrigin);

// wildcard+credentials footgun: the browser rejects it anyway → fail closed
if (resolved == "*" && cors.AllowCredentials)
    resolved = null;

if (resolved is not null)
{
    ctx.Response.Headers["Access-Control-Allow-Origin"] = resolved;
    AppendVary(ctx.Response.Headers, "Origin");   // mandatory, else caches mix up policies
    if (cors.AllowCredentials)
        ctx.Response.Headers["Access-Control-Allow-Credentials"] = "true";
    // ... preflight reflection below
}

ResolveOrigin behaves like this:

a resolver is set → its word is final (may return a specific origin, "*", or null);
static "*" → emit * verbatim;
static whitelist → reflect the request's Origin, only if it's in the list (browsers don't understand a CSV in Access-Control-Allow-Origin, so we single-select);
otherwise → null (origin not allowed, no CORS headers emitted).

Preflight (OPTIONS). On preflight, the layer reflects the method and headers the browser asked for:

if (HttpMethods.IsOptions(ctx.Request.Method))
{
    var requestedMethod = ctx.Request.Headers["Access-Control-Request-Method"].ToString();
    ctx.Response.Headers["Access-Control-Allow-Methods"] = !string.IsNullOrEmpty(requestedMethod)
        ? requestedMethod : (cors.AllowedMethods ?? route!.Methods ?? "*");

    var requestedHeaders = ctx.Request.Headers["Access-Control-Request-Headers"].ToString();
    ctx.Response.Headers["Access-Control-Allow-Headers"] = !string.IsNullOrEmpty(requestedHeaders)
        ? requestedHeaders : (cors.AllowCredentials ? "Content-Type, Authorization" : "*");

    ctx.Response.Headers["Access-Control-Max-Age"] = cors.MaxAgeSeconds.ToString();  // default 86400
}

// OPTIONS always short-circuits to 204 — even when the origin was rejected
if (HttpMethods.IsOptions(ctx.Request.Method))
{
    ctx.Response.StatusCode = StatusCodes.Status204NoContent;
    return;
}

So the whole of CORS is a careful hand-rolled implementation of the spec over Kestrel, with a correct Vary: Origin, proper preflight handling, and a guard against wildcard+credentials. No app.UseCors() anywhere.

Part 7. Streaming the response: SSE and chunked

An InOut consumer can return more than a finished body — it can return a stream, an IAsyncEnumerable<string>. This is used, for example, in the LLM connector to stream tokens. The logic lives in WriteResponse:

else if (body is IAsyncEnumerable<string> asyncStrings)
{
    var useSse = responseContentType?.Contains("text/event-stream", ...) == true;

    httpContext.Response.Headers["Cache-Control"]   = "no-cache, no-transform";
    httpContext.Response.Headers["X-Accel-Buffering"] = "no";   // don't buffer at nginx/LB

    httpContext.Features.Get<IHttpResponseBodyFeature>()?.DisableBuffering();  // turn off ASP.NET buffering

    if (useSse)
        await WriteSseStreamAsync(...);          // text/event-stream → SSE framing
    else
        await WriteChunkedTextStreamAsync(...);  // otherwise → chunked plain text
}

The framing choice is driven by the response Content-Type (the canonical end-to-end signal, Accept ↔ Content-Type), not a private header:

text/event-stream → Server-Sent Events: each yield → one data: frame; at the end, an event: done carrying late-bound summary headers (llm.tokens.in/out, llm.stop_reason, …) that the producer sets only after iteration finishes.
everything else → chunked plain text: each yield is one chunk, with a FlushAsync after each.

DisableBuffering() is critical: without it, ASP.NET would accumulate chunks and flush them in a batch, killing the whole point of streaming.

Part 8. Producer: an HTTP client with every knob

Now the outbound side — HttpProducer over HttpClient. The client is created once in ConnectAsync:

_handler = new HttpClientHandler
{
    AllowAutoRedirect = _options.FollowRedirects,        // followRedirects (default true)
    MaxAutomaticRedirections = _options.MaxRedirects      // maxRedirects (default 50)
};
_httpClient = new HttpClient(_handler)
{
    Timeout = _options.Timeout > 0
        ? TimeSpan.FromMilliseconds(_options.Timeout)     // timeout (default 30000)
        : Timeout.InfiniteTimeSpan
};
ConfigureAuthentication(_httpClient);

Building the URL — four layers

ResolveUrl assembles the target address layer by layer:

// 1. Base URL from the endpoint, with ${...} expressions resolved
var baseUrl = _options.ResolveOption(_endpoint.BuildProducerUrl(), exchange) ?? ...;

// 2. Substitute {name} parameters from .Param(...)
baseUrl = ResolveNamedParams(baseUrl, exchange);

// 3. Query string from the redbHttp.Query header, if present
if (exchange.In.Headers.TryGetValue("redbHttp.Query", out var query) && query is string qs && qs.Length > 0)
{
    var sep = baseUrl.Contains('?') ? "&" : "?";
    return $"{baseUrl}{sep}{qs}";
}

The base URL is built by HttpEndpoint.BuildProducerUrl() — simply scheme + host[:port]/path. And {name} parameters are substituted with URL escaping:

// ResolveNamedParams
var resolved = valueTemplate.Contains("${")
    ? (_options.ResolveOption(valueTemplate, exchange) ?? valueTemplate)
    : valueTemplate;
url = url.Replace($"{{{name}}}", Uri.EscapeDataString(resolved), ...);

So:

.To(Http.Get("api.example.com/users/{id}/orders").Param("id", Header("userId")))

turns at runtime into http://api.example.com/users/42/orders, where 42 comes from the userId header and is escaped.

The request method

The method comes from options (?method=POST) but can be overridden by the redbHttp.Method header:

if (exchange.In.Headers.TryGetValue("redbHttp.Method", out var hm) && hm is string methodStr)
    return new SysHttpMethod(methodStr.ToUpperInvariant());

A body is set only for POST/PUT/PATCH (HasBody). byte[] → ByteArrayContent, Stream → StreamContent, anything else → StringContent in UTF-8.

Header bridging

With bridgeHeaders=true (default), Exchange headers ride out into the HTTP request — except internal and hop-by-hop ones (NonBridgedHeaders):

foreach (var (key, value) in exchange.In.Headers)
{
    if (value is null) continue;
    if (HttpHeaders.NonBridgedHeaders.Contains(key)) continue;  // Connection, TE, redbHttp.*, Content-* etc.
    if (!request.Headers.TryAddWithoutValidation(key, strValue))
        request.Content?.Headers.TryAddWithoutValidation(key, strValue);  // else try as a content header
}

NonBridgedHeaders is the union of internal redbHttp.*, hop-by-hop (Connection, Keep-Alive, Transfer-Encoding, TE, Trailer, Upgrade, Proxy-*), and the content headers managed by HttpClient (Content-Type, Content-Length, Content-Encoding…).

Authentication

Three schemes (HttpAuthScheme):

Basic — username/password, the Authorization: Basic ... header is set once on the client.
Bearer, static — a constant token, also set once on the client.
Bearer, dynamic — a token expression (DynamicValue<string>.IsDynamic), resolved per request from the Exchange:

// ConfigurePerRequestAuth
if (_options.AuthScheme == HttpAuthScheme.Bearer && _options.AuthToken.Value.IsDynamic)
{
    var token = _options.AuthToken.Value.Resolve(exchange);
    if (!string.IsNullOrEmpty(token))
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
}

So .BearerAuth().AuthToken(Header("jwt")) injects a fresh JWT from the header on every outbound call.

Response → `Exchange`

MapResponse drops the response body into Out and sets the standard headers:

outMessage.Headers["redbHttp.StatusCode"] = (int)response.StatusCode;
outMessage.Headers["redbHttp.StatusText"] = response.ReasonPhrase ?? "";
outMessage.Headers["redbHttp.Url"]        = response.RequestMessage?.RequestUri?.ToString() ?? "";

With copyResponseHeaders=true (default) it copies the response headers plus Content-Type/Content-Length. With streamResponse=true the body becomes a Stream, not a byte[] — and then the HttpResponseMessage is deliberately not disposed right away: Exchange.DisposeAsync closes the stream.

`throwOnError`

By default throwOnError=true — on 4xx/5xx the producer throws an HttpRequestException (which your OnException/TryCatch will catch). Turn it off with .NoThrowOnError() if you'd rather handle statuses by hand via ${header.redbHttp.StatusCode}.

Part 9. Putting it all together — a real route

Back to MainPipelineRoutes.cs, here's the full HTTP entry with the Content-Based Router and request/reply (redb.Route.Demo):

From("http:0.0.0.0:5088/api/demo?inOut=true")
    .RouteId("demo-http-entry")

    .ConvertBody<string>()              // byte[] → string
    .Throttle(10)                       // no more than 10 req/sec
    .Log("[1-HTTP] ▶ body=${body}, contentType=${contentType}")

    .SetHeader("traceId", e => Guid.NewGuid().ToString("N")[..12])
    .Log("[1-HTTP]   traceId=${header.traceId}, mode=${header.mode}")

    .ValidateJsonSchema(MessageSchema)  // body must be JSON with a "message" field
    .IdempotentConsumer(e => GetHeader(e, "traceId") ?? "", IdempotentRepo)

    // ── Content-Based Router: route by the mode header ──
    .Choice()
        .When(e => GetHeader(e, "mode") == "full")
            .SetHeader("fastTrack", e => GetHeader(e, "priority") == "high" ? "true" : "false")
            .SetHeader("stamp.dsl", "full-branch")
        .When(e => GetHeader(e, "mode") == "short")
            .SetHeader("fastTrack", "false")
            .SetHeader("stamp.dsl", "short-branch")
        .Otherwise()
            .SetHeader("mode", "default")
            .SetHeader("stamp.dsl", "default-branch")
    .EndChoice()

    // ... in the demo: a cross-transport pipeline, SQL, WireTaps ...

    .SetHeader("Content-Type", "application/json")
    .SetBody(e => BuildResponse(e));     // inOut=true → this is the HTTP response

Hit it with three curls — three different branches:

# full-branch
curl -X POST http://localhost:5088/api/demo \
  -H "Content-Type: application/json" -H "mode: full" -H "priority: high" \
  -d '{"message":"hello"}'

# short-branch
curl -X POST http://localhost:5088/api/demo \
  -H "Content-Type: application/json" -H "mode: short" \
  -d '{"message":"hi"}'

# default-branch (no mode)
curl -X POST http://localhost:5088/api/demo \
  -H "Content-Type: application/json" \
  -d '{"message":"yo"}'

And right next to it, on the same port 5088, lives an echo route (EchoRoutes.cs) — a separate From, the same shared Kestrel:

From("http:0.0.0.0:5088/api/echo?inOut=true")
    .RouteId("demo-http-echo")
    .AutoStart(false)                    // dormant until you start it by hand
    .ConvertBody<string>()
    .SetHeader("Content-Type", e => /* mirror the request's Content-Type */ ...)
    .Log("[ECHO] ◀ Echoing back: ${body}");

.AutoStart(false) is a perfect illustration of the lifecycle from Part 4: the route is registered but doesn't start with the module. Start it by hand (tsak route start demo-http-echo) and it registers on the already-running Kestrel for port 5088. Stop it, and the server stays up — because /api/demo is still listening.

Gotcha cheat sheet

No body in the response? Check for inOut=true. Without it the consumer returns an empty 200 OK, no matter what you do with .SetBody(...).
CORS "doesn't work"? With cors=true you must supply corsOrigins (or a resolver) — otherwise it throws at startup. Wildcard * + credentials is rejected by browsers, and the connector honestly returns the response with no CORS headers (fail closed).
Port already in use? Within a process Kestrel is shared by (host, port) through the singleton SharedHttpServerManager — routes on one port share one server (under Tsak you can even sit on the admin API's port). A bind conflict only happens if a foreign, non-redb server already took the port.
Request headers leaking into the response? They shouldn't — the connector tracks them (RequestHeaderNames) and won't reflect them. But if you set a header with the same name yourself, it will go out.
Stream arrives as one batch? SSE needs Content-Type: text/event-stream on the response; otherwise it's chunked plain text. Buffering is disabled automatically.
{id} didn't substitute on the producer? The parameter is supplied via .Param("id", ...); without .Param, the {id} placeholder stays in the URL as-is.
405 instead of 404? That's a feature: the path matched, the method didn't. Narrow methods= or check which method you're calling with.

Wrap-up

redb.Route.Http isn't a "wrapper over a controller" — it's a transport in its own right:

The consumer brings up its own Kestrel (CreateSlimBuilder, no MVC), shares it across routes by (host, port) through the SharedHttpServerManager singleton, keeps its own route table with proper specificity ordering, ref-counts for lifecycle, and implements CORS by hand — one policy per route.
The producer is HttpClient with every knob exposed: layered URL building, {name} parameters, header bridging, Basic/Bearer (including a dynamic per-request token), response streaming, and a controllable throwOnError.
HTTP ↔ Exchange is a two-way bridge through redbHttp.* headers, with honest handling of multi-values, route parameters, status codes, and body-less responses.

And the Content-Based Router (.Choice().When().Otherwise()) shows what it's all for: a route makes decisions on the content of an already-decoded message and knows nothing about whether Kestrel, Kafka, or RabbitMQ sits beneath it.

Next in the series we take the next connector and the next EIP cluster. Want a specific one? Say so in the comments.

Every snippet is verified against the sources in redb.Route/src/redb.Route.Http (HttpConsumer, HttpProducer, HttpComponent, SharedHttpServerManager, HttpEndpointOptions, HttpHeaders, Fluent/HttpDsl) and redb.Route.Controllers. Examples come from the redb.Route.Demo/Routes demo project (MainPipelineRoutes, EchoRoutes, DataObservabilityRoutes) and from the production TsUM system (tsum.Api/Routes, tsum.Api/Auth) — the same routes run in production on port 5090. The controllers section is production-backed: Tsak's entire REST admin API (redb.Tsak.Core/Controllers — Contexts, Routes, Modules, Auth, Users, … — ~14 controllers) is built on RedbController and runs in production via ControllerDispatcherProcessor. The application-level TsUM API prefers .Process/.Choice — both approaches coexist and both are battle-tested.

redb.Route.Llm 3.1.1 — per-message audit fields for LLM compliance / replay

rinat kozin — Thu, 11 Jun 2026 22:48:57 +0000

When an auditor asks "reproduce this exact answer" six months later, you need more than (messages, model). You need the sampling parameters that were actually applied, the prompt template version, the tool set the model saw, and ideally the provider's backend fingerprint — because closed-source providers silently re-release weights.

Just shipped this in redb.Route.Llm 3.1.1: 7 nullable audit fields on every persisted message.

Set on assistant rows:

Temperature, MaxTokens, TopP — effective values (request override → factory default)
ToolSetHash — SHA-256 of canonical {name, description, InputSchema} set, sorted by name. Tool added/renamed/schema-changed → hash changes
ProviderSystemFingerprint — system_fingerprint from the response (OpenAI / xAI / Together echo it; Anthropic / Gemini-compat / Ollama leave it null)
Set on every row of the run:

PromptTemplateName, PromptTemplateVersion — when the caller used a managed template
Honest limitation: bit-exact replay is only possible with self-hosted (Ollama / vLLM / llama.cpp). Anthropic doesn't expose a fingerprint, OpenAI rotates them silently. For closed providers we record (model_id, params, tool_set_hash, prompt_template) and label it best-effort.

Zero migration. REDB stores props schemalessly — added 7 fields to the C# class, redeployed, done. No ALTER TABLE, no version bump on the storage layer.

Code & details: CHANGELOG.md → 3.1.1 — section per-message audit fields on MessageProps.

Triggered by feedback from a compliance auditor on Habr — turns out "we log conversations" doesn't cut it when the courtroom asks which exact prompt drove this.

Enterprise-grade AI integration: embedding LLMs into the business processes of large companies — redb.Route.Llm 3.1.1

rinat kozin — Wed, 10 Jun 2026 21:05:20 +0000

Series: redb ecosystem (LLM, part 2)

A few days ago I announced redb.Route.Llm — the 24th transport in redb.Route, where calling an LLM is .To("llm://claude") and an agent tool is just a route with .AsLlmTool("shell") on it. The whole pitch was: stop bolting an "AI framework" onto an integration framework that already has retry, throttle, breaker, audit, observability. Plug the LLM in as one more endpoint, get those primitives for free.

I closed that announcement with a deliberately uncomfortable section called the "honest skip-list" — features I hadn't shipped yet: streaming end-to-end, tool cache, RAG knowledge store, async batch + callback consumer, eval-run store, sliding-window memory, sandboxed tool execution. I'd rather under-promise in writing than over-promise in screenshots.

Most of that list is shipped. But that's not what this post is about. This post is about the thing I didn't quite see at announcement time: shipping the skip-list turned the whole thing into something different from a chat library. It turns out that once you put an LLM into an ESB and start adding the boring enterprise plumbing, the result isn't "a chat framework with extras". It's a runway from a 6-line demo to a multi-tenant, audited, budgeted, human-in-the-loop agent platform — with no rewrite in the middle.

That's the story I want to tell. Three angles: deep dive on the technically-tricky bits (streaming, persistence, RAG), eight enterprise patterns that collapse into one DSL line each, and a project-to-platform timeline I've watched live more than once.

Coming in cold? Earlier in this series:

redb.Route 3.1.0 — LLM as just another connector (announcement)

redb.Route — Apache Camel for .NET

Enterprise Integration Patterns in .NET, part 1

A quick word on EIP. Throughout this post I lean on Enterprise Integration Patterns — Multicast, Aggregator, Scatter-Gather, Wire-Tap, Choice, Aggregate-by-window — without unpacking each of them in detail. That's deliberate: the "EIP in .NET via redb.Route" series with per-pattern deep-dives (diagrams, code, side-by-sides) hasn't shipped yet, I'm writing those in parallel. So I'm getting a little ahead of myself here.

If you've worked with Apache Camel or WSO2 Micro Integrator, you'll spot the patterns on the fly — the names and semantics are identical. I've personally shipped and maintained integration projects on WSO2 MI for years (and on its ESB ancestor), but architecturally redb.Route sits closer to Camel — a compiled DSL over a typed Exchange, not an XML config. Side-by-side comparisons "Camel ↔ redb.Route" and "WSO2 MI ↔ redb.Route" are their own posts, also in flight. If anything EIP-flavoured in the code below trips you up, drop a question in the comments — I'll answer on the spot, and the answer goes straight into those upcoming pieces.

Why this isn't "yet another agent framework"

The agent-framework shelf is crowded. LangChain, LangChain4j, Semantic Kernel, AutoGen, LlamaIndex — each one solves the same single problem: how does my model call functions and remember a conversation. Each one leaves you to solve the other eighteen problems yourself: retry, idempotency, audit, multi-tenant, budget, observability, governance, approval, batch, scheduling, replay, dead-letter, throttling, circuit-breaking, correlation, timeouts, cost attribution, metric exporters.

redb.Route.Llm's entire reason for existing is to make those eighteen problems be already solved at the framework layer. Not "we have an integration library, plus an LLM library, glue them yourself" — same DSL, same runtime, same governance hooks. If you already have a redb.Route policy interceptor that writes every message to Kafka, it automatically writes every tool call from your agent to Kafka too — because they're the same Exchange.

This isn't theoretical elegance. It cuts through the single biggest production headache with agents: what happens the day your model decides to drop a production table? In the LangChain-plus-hooks shape, the answer is "wire up our approval callbacks and don't forget". In the LLM-as-transport shape, the answer is "intercept the Exchange before .To("exec://...") with the same .Process(...) you use for any other potentially-destructive step in any other route". Not a new pattern for AI. The same pattern as for FTP, Kafka, JMS.

Same people, same tools, same review gates. That's the actual win.

What got shipped from the skip-list

I said I would, and I'm saying I did.

Skip-list item	Status in 3.1.1
Streaming end-to-end (HTTP SSE + WS per-frame)	Shipped. `IAsyncEnumerable<string>` lives in `Out.Body`, the HTTP consumer flips into SSE, the WS consumer dispatches one frame per message.
ToolCacheStore on REDB	Shipped. `ToolCacheProps`, opt-in via `ToolCachingPolicy.Memoize`.
KnowledgeStore — RAG chunks in REDB	Shipped (partial). `KnowledgeChunkProps` with metadata + tenant + ACL; embeddings land in a follow-up release.
BatchStore + LlmCallbackProcessor	Shipped. Anthropic Message Batches and OpenAI Batch, async webhook consumer, idempotent dispatch, retry-aware.
EvalRunStore	Shipped. Eval runs are first-class objects with trace ids and prompt-version pinning.
PromptTemplateStore	Shipped. Versioned prompt registry, referenced from DSL with `#name`.
Sliding-window memory	Not shipped. Different bet placed instead: tree-branching conversations via REDB-tree (more on this below).
Sandboxed tools (per-call container)	Not shipped in container form. Shipped `redb.Route.Exec` with allowlist + working-dir + timeout + byte-cap — the practical enterprise minimum.

Bonus, not in the skip-list:

Per-exchange ?redb=<name> hint — pick a named REDB instance per Exchange, so one route serves N tenants without N route registrations or N IServiceScopes.
DSL/tool package split — redb.Route.Llm.Abstractions (contracts only) and redb.Route.Llm.Tools (six utility tools), so 22 connectors can register .AsLlmTool() without bumping a minor on every change.
Six utility tools out of the box: HttpFetch, JsonPath, XPath, RegexExtract, MathEval, TavilyWebSearch — each as both a DSL extension and a standalone tool route.
Bug fixes that only show up in real traffic: orphan tool_use (model asks for a tool, provider 5xxs mid-turn, leaves the conversation in an invalid state) and OEM codepage in Process.StandardOutput (Windows cmd /c returns cp866 bytes, breaks the UTF-8 contract every tool implicitly assumes).

Eleven REDB schemas now sit behind all of this: ConversationProps, MessageProps, ApprovalProps, CostBudgetProps, ToolCacheProps, ToolAuditProps, KnowledgeChunkProps, PromptTemplateProps, EvalRunProps, LlmBatchProps, ToolIdempotencyProps. That's not a database for your chat history. That's the operational layer of an agent platform, opt-in via one line: AddRedbLlmStorage().

Ten enterprise patterns — each one a single DSL line

Here's where it gets useful. None of these are pseudocode. They all run today.

1. Hard budget per conversation as a circuit breaker

In a side project, a "token budget" is a log line. In production, it's a safety primitive — your model must not be allowed to burn $10k because of a bad prompt. CostBudgetProps isn't an observability artifact; it's a preventive rule. Every provider call, the agent engine sums spend by conversation id and adds the worst-case for the pending request (via max_tokens). If the total would breach the cap, LlmBudgetExceededException fires before the network call, not after.

From("kafka://support-tickets")
    .To(Llm.Factory("claude")
        .Conversation(e => "ticket-" + e.In.Headers["TicketId"])
        .CostBudget(usd: 0.50)            // hard ceiling per conversation id
        .CostBudgetExceeded(BudgetPolicy.FailFast)
        .AsUri())
    .To("kafka://support-replies");

The same primitive scales to "budget per tenant", "budget per prompt template", "budget per model" — they're all just different keys in CostBudgetProps. Same shape, different GROUP BY.

2. Approval gates with a human in the loop

The most under-appreciated production pattern in agent-land. If your model can refund payments or delete records, a human stands between the tool call and the actual side effect. Not a webhook duct-taped on later — a native runtime concept.

From("direct:tool-payments-refund")
    .AsLlmTool("issue_refund")
        .Description("Refund a payment by id and reason.")
        .Input(/* JSON Schema */)
        .SideEffect(ToolSideEffect.Mutating)        // governance hook reads this
        .Cost(ToolCostClass.Expensive)
    .Then()
    .Process<ApprovalGate>()                        // suspend exchange,
                                                     // write ApprovalProps,
                                                     // notify Slack,
                                                     // wait for HTTP callback
    .To("kafka://payments.refund.commands");

ApprovalProps records the exchange id, conversation id, input arguments, the human approver, the wait deadline, and the outcome. The Slack bot, the email handler, the web form — all of those plug in as ordinary HTTP routes in the same redb.Route. When the human clicks Approve, the webhook wakes the suspended Exchange and feeds the result back to the agent engine. On timeout, the agent receives a tool_result with status:"timeout" and decides what to do next.

The point: this is not AI logic. It's the EIP Aggregator + Correlation Identifier + Wire-Tap + Reply-To pattern, which already applies to a refund engine without an LLM. They're both Exchanges in the same runtime, so the pattern is reused.

3. Idempotent tool retries via `ToolIdempotencyProps`

Webhook consumers retry. Network timeouts retry. Anthropic's batch sometimes delivers a payload twice. If your tool call "issue refund $50" runs twice, that's a bad day at standup.

ToolIdempotencyProps keeps idempotency-key → tool-result with a TTL. In the DSL:

From("direct:tool-issue-invoice")
    .AsLlmTool("issue_invoice")
        .Caching(ToolCachingPolicy.Idempotent)
    .Then()
    .Process(BuildIdempotencyKey)                    // sha256(args + customer-id + day)
    .To("...");

When the agent engine sees Caching = Idempotent, it consults ToolIdempotencyProps before the route runs. Hit → returns the saved tool_result, route never executes. Miss → route runs, result is recorded. Framework-level, not "remember to wrap your handler".

4. Multi-tenant via `?redb=<name>`

One worker, fifty customers. Each customer is their own REDB instance — their conversations, their cost budgets, their approvals, their knowledge base. In 3.1.0 this would have meant fifty IServiceScopes or fifty route registrations. In 3.1.1 it's a per-exchange hint:

From("http:0.0.0.0:5088/api/llm/ask?inOut=true")
    .Process(e =>
        e.In.Headers[LlmHeaders.Redb] = e.In.Headers["X-Tenant"]?.ToString())
    .To("llm://claude?conversationFromHeader=true");

?redb=acme or a header — the engine pulls the named REDB instance from the registry, on the current Exchange, no factory, no route swap, no restart. Conversations, audit, approvals all land in the right tenant. Each tenant gets its own billing surface and governance lane, with no awareness of the others.

This was the single feature most worth the late nights. It's the difference between "we have a multi-tenant agent platform" and "we have a multi-tenant deployment story, here's a wiki page".

5. Audit trail without a separate integration

ToolAuditProps is a REDB object: tenant id, conversation id, exchange id, tool name, input args (or hash, if PII), output (or hash), duration, status. Every tool invocation is recorded automatically — because tools are routes, and redb.Route already has post-processors.

The query "show me every Claude tool call in tenant acme over the last 7 days, side-effect=mutating, cost=expensive, ordered by time" isn't a separate analytics pipeline. It's a value_string index plus one SQL — the same indexed-business-id pattern the rest of the REDB ecosystem uses.

6. Async batch + callback consumer

Anthropic Message Batches and OpenAI Batch are up to 50% cheaper, with a price tag of up to 24 hours of latency. For offline workloads — classifying a million tickets, extracting fields from a million PDFs — that's the right knob to turn.

LlmBatchProps stores the batch id, statuses, and the link back to the originating Exchange collection. LlmCallbackProcessor is just an HTTP route that the provider calls when the batch finishes. The route reads the batch id, fetches the results, dispatches each one back to its originating Exchange via correlation id — and those Exchanges resume their journey as if the synchronous call had just finished, twenty-four hours later.

On top of this: idempotency (same ToolIdempotencyProps), retry (the standard redb.Route circuit breaker), backpressure (Kafka or queue downstream). No batch dispatcher to write. No webhook handler to write. No "what if the callback arrives twice" to test separately.

7. Versioned prompt registry: `#`-refs

The single most depressing prod bug pattern: "the model is answering differently". You go check git blame, somebody touched the system prompt three weeks ago, the tests passed because the eval set is small. The prompt is code, and it deserves a registry with versions.

// where prompts get registered:
promptRegistry.Register("triage-system", version: "v3", body: """
    You are a support triage agent. Classify into [billing, tech, sales, abuse]...
    """);

// in the route:
.To(Llm.Factory("claude").SystemPromptRef("#triage-system@v3").AsUri())

PromptTemplateProps is a REDB object: name, version, body, metadata (author, date, experiment id). When the engine resolves #name, it pins exactly that version into MessageProps for the call. Six months later you can say with certainty "this conversation ran on triage-system v3", not "probably v3, that's what we were doing then".

The juicy part: EvalRunProps records eval runs bound to a prompt version. "v4 gives +12% accuracy on the golden set" stops being a spreadsheet and becomes a query.

8. Tree-branching conversations for A/B and counterfactuals

ConversationProps is stored as a REDB tree via the native parent_id. That means a conversation isn't a flat list of messages — it's a tree. So you can:

branch from any message and run an alternative continuation with a different model or temperature;
keep a user branch and an experiment branch in parallel;
compute metrics across pairs of branches ("with-tools vs without-tools on the exact same context").

Sliding-window memory truncates the past. Tree-branching memory writes alternative pasts and compares them. For production agents, the second one is an order of magnitude more useful, because improving prompts in production is exactly that loop: take a real conversation, replay with a new prompt, score it, ship the winner.

And nothing here was bolted on for LLMs. Tree via parent_id has been a first-class REDB feature from day one — for product hierarchies, org charts, file systems. The LLM stack just wrote its own entity on the same primitive.

9. A jury of cheap models with a senior model as arbiter — Scatter-Gather + Aggregator

One of the most underrated production tricks in agent-land: don't trust a single model. Send the same task to several cheap models in parallel (Haiku, GPT-4o-mini, Mistral-Small, Gemini-Flash, Llama-3.1-70b on Groq), gather their answers, and hand the original prompt plus all five candidates to a senior model (Sonnet, Opus, GPT-4o) acting as arbiter — pick the best, synthesise a new one, or say "nobody nailed it, ask the human". The literature calls this mixture-of-agents or ensemble voting, and on hard tasks it routinely buys you +10 to +20% accuracy at a lower bill than running everything through Opus.

In a vanilla LangChain shape, this becomes a hundred-line orchestrator with try/catch, per-model timeouts, retry knobs, and a hand-rolled aggregator. In an ESB shape, it's the bog-standard EIP Scatter-Gather + Aggregator, with twenty-five years of hardening in integration buses. The LLM is just one more endpoint type the Scatter-Gather fans out to:

From("kafka://contract-clauses-to-classify")
    .RouteId("contract-jury")
    .Multicast()                                          // Scatter
        .Parallel()
        .StopOnException(false)                           // one provider down? carry on
        .Timeout(TimeSpan.FromSeconds(30))                // per branch
        .To(Llm.Factory("haiku")
            .SystemPromptRef("#contract-classify@v3")
            .Temperature(0.0).MaxTokens(200).AsUri())
        .To(Llm.Factory("gpt-4o-mini")
            .SystemPromptRef("#contract-classify@v3")
            .Temperature(0.0).MaxTokens(200).AsUri())
        .To(Llm.Factory("groq-llama-70b")
            .SystemPromptRef("#contract-classify@v3")
            .Temperature(0.0).MaxTokens(200).AsUri())
        .To(Llm.Factory("mistral-small")
            .SystemPromptRef("#contract-classify@v3")
            .Temperature(0.0).MaxTokens(200).AsUri())
    .End()                                                // Gather: results land in Exchange.Properties["multicast.results"]
    .Process<JuryAggregator>()                            // splice candidates into one arbiter prompt
    .To(Llm.Factory("sonnet")                             // Arbiter
        .SystemPromptRef("#jury-arbiter@v2")
        .Temperature(0.1).MaxTokens(500)
        .CostBudget(usd: 0.05)
        .AsUri())
    .To("kafka://contract-clauses-classified");

JuryAggregator is a tiny processor: takes the four answers and the original prompt, builds one arbiter message of the shape "here is the task; here are candidates A/B/C/D; return the final classification or say unclear". The arbiter answers with structured JSON. Headers llm.tokens.in/out are recorded per branch plus once for the arbiter — cost is transparent at the route level.

Why ESB-shape makes this so cheap to express:

Parallelism for free. Multicast EIP already knows how to fan out across N branches, await all-or-N-of-M, handle timeouts and partial failures. No Task.WhenAll with hand-written failure handling.
Idempotency for free. A retry on a failed branch hits the same ToolIdempotencyProps (or provider-side prompt-hash cache) and dedups. No double billing.
Budget for free. .CostBudget(usd: 0.05) on the arbiter is its own circuit-breaker; per-branch .CostBudget(usd: 0.01) caps the cheap models. A combined ceiling is a different CostBudgetProps key. Breach it and the whole jury fails fast — failover to a rule-based classifier (which sits as another branch on the route).
Audit for free. Each of the five LLM calls is captured in ToolAuditProps, all stitched to one exchange id. A month later you can answer "model X agrees with the arbiter 73% of the time — let's drop it and save".
Eval for free. EvalRunProps records the run with five branches plus the arbiter — replay against a golden set to find the optimal jury composition (swap GPT-4o-mini for Gemini-Flash, see if accuracy holds).

In production this pattern wins on two axes. Accuracy: on tasks like "is this contract clause a risk", where a single model wobbles, four cheap models plus a Sonnet arbiter routinely outperforms a lone Opus, at 2.5× lower cost. Robustness: when Anthropic is having a bad afternoon, the Anthropic branch fails, the other four return, the arbiter receives four candidates instead of five and ships a verdict. Graceful degradation, not a hard outage.

One subtle production gotcha: never tell the arbiter who wrote which answer. If the arbiter's prompt says "candidate from Claude Haiku, candidate from GPT-4o-mini", the arbiter develops favourites (so do humans). So JuryAggregator anonymises the candidates as A/B/C/D, shuffles their order (Latin-squared on exchange-id for reproducibility), and only after the arbiter responds do we map back to "A was the Haiku answer". Clean signal for the post-hoc analysis "which model agrees with the arbiter most often".

10. Sub-agents — an agent as another agent's tool

A direct consequence of the "tool = route" architecture: if a route can contain .To("llm://..."), then a tool can itself be an agent. The parent agent doesn't "know" there's another LLM hiding behind that tool. To it, research_topic is just another tool, like web_search or math_eval. Inside the tool, though, lives a fully-fledged second-tier agent with its own model, prompt, toolset, budget, iteration cap, retry policies, RAG sources.

In code:

// Sub-agent: a research specialist with its own toolset
From("direct:research-subagent")
    .AsLlmTool("research_topic")
        .Description("Deep research on a topic. Takes {topic, depth}. " +
                     "Returns a structured summary with sources.")
        .Input("""{"type":"object","properties":{
                    "topic":{"type":"string"},
                    "depth":{"type":"string","enum":["short","deep"]}},
                  "required":["topic"]}""")
        .SideEffect(ToolSideEffect.ReadOnly)
        .Cost(ToolCostClass.Expensive)              // parent sees the call is pricey
    .Then()
    .Knowledge("research-corpus", k: 12)            // sub-agent has its own RAG corpus
    .To(Llm.Factory("sonnet")                       // mid-tier model — research specialist
        .SystemPromptRef("#research-specialist@v3")
        .Tools("tavily_web_search", "http_fetch", "regex_extract")
        .MaxIterations(8)
        .CostBudget(usd: 0.30)                      // sub-agent has its own budget
        .Temperature(0.1).AsUri())
    .Process<ExtractResearchSummary>();

// Parent agent uses the sub-agent as just another tool
From("kafka://complex-business-questions")
    .To(Llm.Factory("opus")                         // planner — top-tier model
        .SystemPromptRef("#senior-analyst@v1")
        .Tools("research_topic",                    // ← our sub-agent
               "sql_query",                         // ← plain data tool
               "math_eval",                         // ← computation
               "draft_report")                      // ← another sub-agent (report drafter)
        .MaxIterations(15)
        .CostBudget(usd: 2.00)                      // top-level budget
        .AsUri())
    .To("kafka://business-answers");

What actually happens under the hood: when Opus decides to call research_topic, the agent engine builds the JSON input and routes it through RouteToolBridge to direct:research-subagent. That route runs as a fresh Exchange, inheriting transaction scope, principal, headers, and DI scope from the parent. Inside it, Sonnet runs its own tool-use loop (web search → fetch → extract), potentially with eight iterations and three tools. It returns a structured summary in Out.Body, which the engine repackages as a tool_result and hands back to Opus. Opus sees the result, keeps planning, calls more tools as needed.

In other words: the architecture is recursive without a single line of dedicated code. A sub-agent inside a sub-agent works the same way. At depth three, audit, budget, idempotency, prompt versioning, RAG, governance — all of it still works, because none of those are tied to "agent level"; they're tied to the Exchange, and the Exchange is the same primitive at any depth.

This unlocks three derivative patterns that are awkward to assemble in the flat "one agent, many tools" shape:

(a) Hierarchical agents — planner and workers. A top-tier model (Opus, GPT-4o) plays planner: decomposes the task and dispatches chunks to specialists. Each specialist is a sub-agent with a narrow prompt and a narrow toolset. The planner may have no direct data access at all — only through sub-agents. That gives you hard separation of authority: the planner can't accidentally call delete_records because that tool isn't in its set; only data-cleanup-subagent has it, and the planner has to hand off explicitly.

(b) Specialist sub-agents with their own memory. A sub-agent can have its own conversationId (a different branch of the REDB tree), its own Knowledge(...) sources, its own prompt registry. A legal-review-subagent lives inside the corporate legal corpus, sees only that, answers strictly in the legal register. The senior agent never gets direct access to those documents. ACL is enforced at the route level, not at the "we hope the model doesn't quote it" level.

(c) Cost-shaped escalation. A cheap agent (Haiku) takes the first swing. If it returns unclear or confidence is below threshold, it calls escalate_to_senior itself as a tool — and behind that tool sits a route to Opus with full context. Most queries land on Haiku for pennies; only the hard ones reach Opus. On high-volume workloads the economics change by an order of magnitude.

How this relates to the static jury in pattern #9: the jury is a statically-wired sub-agent pattern. The route knows up front there are N candidates and one arbiter; the DAG is hard-coded in the DSL. Sub-agents-as-tools is the dynamic version: the parent agent decides for itself whom to call and how often. Jury wins on predictable classification/forecasting pipelines. Sub-agents win on open-ended research where the number of steps and the toolset can't be known in advance.

The obvious failure mode is cycles. If sub-agent A can call B and B can call A, you've got an unbounded recursion in theory. In practice three guards keep it bounded: MaxIterations at every level (no sub-agent loops forever), CostBudgetProps (each nested call burns parent budget), and an optional depth limit in headers (LlmHeaders.SubAgentDepth increments per level; the route rejects calls past a configured limit). Real tasks rarely benefit beyond depth = 3-4.

And one more piece of architectural elegance: a sub-agent is just a route, which means it has a stock URI. Different parent agents can share one research-subagent, which has its own ?redb=acme for tenant isolation, its own rate limiter (?throttle=5/sec), its own circuit breaker. The sub-agent behaves like an internal LLM-tier microservice that you reuse across routes without duplicating prompts or proliferating clients.

Streaming: what actually changes when a token leaves the provider

In 3.1.0, providers streamed but the client never saw it — we accumulated tokens into a string and returned the whole thing. In 3.1.1, the chain closes:

the provider yields IAsyncEnumerable<string> — frames as they arrive;
the agent engine sticks that into Out.Body as IAsyncEnumerable<string>, without materialising;
the HTTP consumer sees IAsyncEnumerable<string> and switches to SSE — one data: ...\n\n per frame;
the WS consumer sends one WebSocket message per frame;
non-streaming consumers (Kafka, RabbitMQ, ActiveMQ) materialise the way they used to.

The architectural payoff: streaming stops being a separate mode and becomes a payload type. Same Exchange can fan out to SSE and Kafka simultaneously (multicast EIP) — Kafka waits for materialisation, SSE sees frames live. No "streaming endpoint" vs "regular endpoint" duplication.

Underneath, this is the well-known pipe pattern of "iterator instead of collection". The only LLM-specific bit is making sure async iteration runs inside the end-to-end Exchange tracking so traces and metrics see the whole journey, not "received an Exchange and lost the rest".

RAG: chunks as first-class REDB objects

In 3.1.1, KnowledgeChunkProps is a REDB object with:

the text;
the source (source-uri, tenant-id, doc-id, chunk-index);
metadata (language, date, tags, ACL — who's allowed to see it);
a placeholder for embeddings (vector store ships in a follow-up; the MVP is keyword search via value_string indexes plus FTS).

What this means: a RAG source is a route, not a separate vector service. From("file://docs?include=*.md").To("knowledge://acme") indexes documents. From("kafka://support-tickets").Knowledge("acme", k: 5) injects the top-5 chunks into the system prompt before .To("llm://claude"). ACL and tenant filtering happen as value_*-indexed SQL before chunks reach the prompt.

When the vector store lands, it sits next to keyword search behind the same IKnowledgeStore interface, no route changes. That's the architectural goal: tomorrow's features don't break today's routes.

Three real-world enterprise scenarios — reports, forecasts, alerts

The patterns above are atomic bricks. Now three end-to-end scenarios where those bricks combine into routes you'd actually run on Tuesday morning. No AI hype, no "cognitive automation", no pretending to "transform the industry". Just the dull stuff a human currently does by hand every day, taken over by an agent that lives in the same bus as the data.

Case 1 — A daily financial snapshot for the CFO, in their inbox by 7:00 AM

Every business morning a finance analyst pulls together yesterday's revenue, expenses by category, plan-vs-actual variances, top-5 largest transactions, account balances, FX rates. Then they write a paragraph or two — "revenue +3.2% to plan, expenses +1.7%, the variance is X". An hour and a half, gone. Worth automating? Obvious yes. Worth standing up a separate AI service for it? Hard no.

The whole route:

// Every weekday at 07:00 local
From("cron://daily-cfo-report?schedule=0 0 7 ? * MON-FRI")
    .RouteId("daily-cfo-report")
    .Process<LoadYesterdayMetrics>()                       // pulls from ERP/bank API/data warehouse
                                                            // → e.In.Body = {revenue, expenses, accounts, fx, top5}
    .Process<LoadQuarterContext>()                         // same ETL: plan, prior quarter, MTD/QTD
    .ConvertBody<FinancialDailySnapshot>()                 // strongly-typed payload
    .Multicast().Parallel()
        .To(Llm.Factory("haiku")                           // branch A: short-form for the CFO
            .SystemPromptRef("#cfo-daily-summary@v7")
            .Temperature(0.1).MaxTokens(800)
            .CostBudget(usd: 0.02).AsUri())
        .To(Llm.Factory("haiku")                           // branch B: bulletised for the board chat
            .SystemPromptRef("#cfo-daily-bullets@v7")
            .Temperature(0.1).MaxTokens(400)
            .CostBudget(usd: 0.02).AsUri())
    .End()
    .Process<RenderHtmlReport>()                           // mustache template: numbers as a table,
                                                            // model summaries as the lede
    .To("smtp://mail.acme.com?to=cfo@acme.com,board@acme.com" +
        "&subject=Daily%20FY%20snapshot%20${date:yyyy-MM-dd}")
    .To("teams://board-channel?card=adaptive")             // same HTML body → adaptive card in Teams
    .Wiretap("kafka://reports.cfo-daily.archive");         // copy to archive for audit and training

Seven steps, and those seven steps cover the whole job:

Schedule — cron lives in the URI; no separate scheduler service. redb.Route already does this.
Data pickup — LoadYesterdayMetrics is just a processor that hits your existing integrations through the same redb.Route (Kafka, REST, JDBC). Whatever retries and circuit breakers you already wired around those integrations apply.
Two-tone output — multicast to two branches of cheap Haiku with different prompt templates. Pennies, hard-budgeted.
Versioned prompt — #cfo-daily-summary@v7. Six months from now the CFO complains "the report has gotten worse" — open EvalRunProps, see v7 regressed against the golden set, roll back to v6 with no redeploy.
Delivery — two transports (SMTP + Teams), both stock redb.Route connectors. Tomorrow they want it in Slack too: .To("slack://..."), one line.
Audit — Wiretap copies the whole exchange to a Kafka archive. Twelve months later a regulator asks "what did we send on 2026-04-15?" — pulled from the archive with metadata that says "model X, prompt version Y, source data Z" (because MessageProps records both input and output).
Budget — .CostBudget(usd: 0.02) per branch. 250 trading days × 2 branches × $0.02 ≈ $10/year on token spend. The analyst's hour a day at fully-loaded cost is $50. Pays itself back in week one of month one.

What pushes this from "cute demo" to "actual enterprise asset": when the CFO asks about "that strange number in last Tuesday's report", the auditor pulls one trace id and in 30 seconds has: the snapshot at input, the prompt version that ran, the exact output the model produced, the file that hit SMTP, who opened it in Teams. Not "let me get back to you tomorrow". Right now — because it's all REDB objects pinned to one exchange id.

Case 2 — A weekly cash-flow forecast with a jury and an Opus arbiter

Cash-flow forecasting is the textbook case where one model is worse than zero models: a confident-sounding model error leads to a decision that costs more than the analyst's salary for the month. Pattern #9 (jury + arbiter) earns its keep here.

From("cron://weekly-cashflow-forecast?schedule=0 0 9 ? * MON")
    .RouteId("weekly-cashflow-forecast")
    .Process<BuildCashflowFeatures>()                      // bank balances, AR/AP, scheduled payments,
                                                            // seasonality, FX exposure
    .Knowledge("acme-finance", k: 8)                       // RAG: forecasting playbook, prior reports,
                                                            // methodology, known seasonality notes
    .Multicast().Parallel().Timeout(TimeSpan.FromMinutes(2))
        .To(Llm.Factory("sonnet")                          // four different models — cheap insurance
            .SystemPromptRef("#cashflow-forecast@v4")      // against correlated errors
            .Temperature(0.2).MaxTokens(2000).AsUri())
        .To(Llm.Factory("gpt-4o")
            .SystemPromptRef("#cashflow-forecast@v4")
            .Temperature(0.2).MaxTokens(2000).AsUri())
        .To(Llm.Factory("gemini-pro")
            .SystemPromptRef("#cashflow-forecast@v4")
            .Temperature(0.2).MaxTokens(2000).AsUri())
        .To(Llm.Factory("mistral-large")
            .SystemPromptRef("#cashflow-forecast@v4")
            .Temperature(0.2).MaxTokens(2000).AsUri())
    .End()
    .Process<JuryAggregator>()                             // anonymise A/B/C/D + shuffle
    .To(Llm.Factory("opus")                                // arbiter — strongest model in the rotation
        .SystemPromptRef("#cashflow-arbiter@v2")
        .Temperature(0.1).MaxTokens(3000)
        .CostBudget(usd: 0.50).AsUri())
    .Process<ExtractStructuredForecast>()                  // parse JSON: 30 days × {low, mid, high}
    .Choice()
        .When(e => e.In.Body<Forecast>().ConfidenceLow < 0.6)
            .Process<ApprovalGate>()                       // low confidence → wait for CFO sign-off
            .To("smtp://...?to=cfo@acme.com&priority=high")
        .Otherwise()
            .Process<RenderForecastReport>()
            .To("smtp://...?to=treasury@acme.com")
    .End()
    .Wiretap("kafka://reports.cashflow.archive");

This route runs about $2-3 per execution, once a week — call it $150/year. The analyst would spend a day producing the same artefact. The savings aren't really the point. The point is robustness: four independent forecasts from four different vendors (Anthropic, OpenAI, Google, Mistral) give you consensus as a confidence signal. Four models agree → the arbiter just codifies. Four models diverge → the arbiter writes "model A sees risk X, the rest don't, recommend human review", and the Choice branch routes the report to an approval gate without anyone wiring anything custom.

A year in, the treasury team queries EvalRunProps: "Gemini-Pro disagrees with consensus 18% of the time, and in 70% of those cases Gemini was right". Excellent — it gets upweighted in the jury, not dropped. That's not a guess; it's a SQL query.

Case 3 — A predictive plant alert: XGBoost does the math, the LLM does the sentence

In manufacturing — the real kind, with conveyor belts and SCADA tags, not the metaphorical kind — the bread-and-butter task is "from the metrics, predict that this line will throw a fault in 4-6 hours, and ping the on-shift engineer before it does". The classical play here is a feature store and a gradient-boosted model. That play is still correct, and the LLM is not there to replace it. What the LLM does well is the last-mile translation from "anomaly score + top features + line context" into a sentence a human reads at 3 AM and understands.

// Tap the SCADA bus (MQTT/Kafka), 5-minute aggregation window
From("kafka://scada.metrics?groupId=plant-anomaly-watcher")
    .RouteId("plant-anomaly-watcher")
    .Aggregate(by: e => e.In.Headers["LineId"],
               window: TimeSpan.FromMinutes(5))            // window per production line
    .Process<RunAnomalyModel>()                            // classical ML — XGBoost, nothing fancy;
                                                            // emits {score, top-features, line-context}
    .Choice()
        .When(e => e.In.Body<AnomalyReport>().Score > 0.8)
            .Knowledge("plant-runbooks", k: 3)             // RAG: this line's runbooks,
                                                            // history of similar incidents
            .To(Llm.Factory("haiku")
                .SystemPromptRef("#plant-incident-explainer@v9")
                .Temperature(0.0).MaxTokens(600)
                .Tools("metrics-history", "fetch-shift-log")  // agent fetches more if it needs to
                .MaxIterations(4)
                .CostBudget(usd: 0.10).AsUri())
            .Process<EnrichWithOnDutyEngineer>()           // who's on shift on this line, right now
            .Multicast()
                .To("teams://engineering-shift-{LineId}?card=adaptive")
                .To("sms://twilio?to={engineer.phone}")
                .To("kafka://incidents.predicted.archive")
            .End()
        .Otherwise()
            .To("kafka://scada.metrics.normal")            // archive the boring days too
    .End();

What's actually happening, and why this works:

The ML model isn't getting kicked out. Anomaly scoring is still XGBoost, which has been good at exactly this for a decade. The LLM stands after it.
The LLM explains, not predicts. The system prompt is "anomaly on Line 7, top-3 features look like X, runbook says Y, prior incidents Z. In one page: what likely happened, what the engineer should do in the next hour, and the three parameters to check first". This is synthesis — the place LLMs are objectively strong.
The agent's tools are the plant's data. metrics-history is a direct:metrics-history route that queries Influx/Prometheus. fetch-shift-log reads the shift log from REDB. The agent decides whether to invoke them, how many times. MaxIterations(4) caps it from looping.
Multi-channel delivery. Teams adaptive card with an "I've got it" button (which, by the way, fires an ApprovalGate-style webhook), SMS to the on-shift number via Twilio (already a redb.Route transport), copy to a Kafka archive.
Aggregate by LineId, window 5min is the EIP Aggregator — bucket metrics by group. Nothing redb.Route.Llm-specific; this is plain integration code that's been working in your bus for years.

The business outcome: time from "anomaly appears" to "the engineer on the line knows what to look for" drops from ~40 minutes (operator notices, calls, describes, engineer arrives, engineer starts hunting) to ~4-5 minutes. On expensive lines, an hour of unplanned downtime is tens of thousands of dollars; this route pays for itself the first time a near-miss is caught.

Notice the LLM's role is narrow in all three cases. Not "AI runs the factory". Not "AI runs the books". The LLM does one specific job in each route — summarise, synthesise, pick from candidates, explain. Around it sits all the boring enterprise plumbing: schedules, ETL, RAG, multi-channel delivery, audit, governance, budgets. That plumbing is redb.Route. The LLM is the last brick that previously demanded its own service.

Storytelling: how a chat demo becomes a platform

Here's the timeline I've now watched several times in different teams.

Day 1. Somebody shows the team that Claude can answer a support ticket. LlmHttpRoutes.cs — six lines, From("http://...").To("llm://haiku"), demo works. This is a project, not a platform.

From("http:0.0.0.0:5088/api/llm/ask?inOut=true")
    .ConvertBody<string>()
    .To(Llm.Factory("haiku").MaxIterations(1).AsUri());

Day 7. Coworkers say "it doesn't remember what I just told it". A Process(...) step adds an X-Chat-Id header, ConversationFromHeader() is flipped on. That's it — AddRedbLlmStorage() is already in Program.cs, MessageProps are already being written.

.Process(e => e.In.Headers[LlmHeaders.ConversationId] =
    e.In.Headers["X-Chat-Id"]?.ToString() ?? "default")

Day 14. "Can it run a command on the server?" A tool-shell route appears — a separate route with .AsLlmTool("shell"), backed by redb.Route.Exec, allowlist [cmd, pwsh], working dir in temp, timeout 5 sec, 8 KB stdout cap. Safety lives in the DSL, not in advice in a system prompt.

From("direct:tool-shell")
    .AsLlmTool("shell").SideEffect(ToolSideEffect.ReadOnly).Cost(ToolCostClass.Cheap)
    .Then()
    .To(ExecDsl.Run().AllowedCommands("pwsh", "cmd").TimeoutMs(5000).MaxStdoutBytes(8192));

Day 21. "Finance says the token bill is 4x plan." Add .CostBudget(usd: 0.50) per conversation. No new services, no new dashboards — CostBudgetProps is an existing REDB object, the tsak.web dashboard already knows how to render it.

Day 30. "We need every agent action to be auditable." Already done: ToolAuditProps started writing the day tools became routes. The auditor opens a SQL query — every call this quarter, filtered by tenant and side effect. No "let's set up an integration".

Day 45. "Legal wants human-in-loop on the refund tool." Add .Process<ApprovalGate>() before exec. ApprovalProps writes, the Slack bot is just another HTTP route. Done.

Day 60. "We're onboarding a second customer — separate database, separate billing." Add Process(e => e.In.Headers[LlmHeaders.Redb] = e.In.Headers["X-Tenant"]). One route, two tenants, zero changes to logic.

Day 90. "Run a million tickets through the classifier overnight." The route is already there. Change one knob: .Mode(LlmMode.Batch) — a synchronous call becomes an Anthropic Batch, LlmBatchProps records the id, LlmCallbackProcessor waits for the webhook, results land in the same Kafka the live route uses during the day. -50% on the bill.

Day 120. "Which prompt versions regressed?" EvalRunProps already stores runs. SQL across PromptTemplateRef, accuracy diff, v4 is bad, roll back to v3. No redeploy.

There's no "and then we rewrote it on a Kubernetes operator" beat in this story. There's no "and then we added an AI platform" beat. The six lines that worked as a chat demo on Day 1 are literally the same file that on Day 120 is running a multi-tenant, jury-arbitrated, batch-classifying, audit-grade platform. No migration, no rewrite, no architecture v2 — just lines accreting into the route as the requirements showed up. The chat demo doesn't grow into a platform — it was standing on a platform from day one, just opting into more of its features over time.

This is the pitch I couldn't quite articulate at announcement time. Now I can. The deliverable here isn't an agent framework. It's a runway. You walk along the runway and you're already platform-shaped.

Demo routes — see it live

The patterns above aren't concept art. The repo redbase-app/redb-route ships two demo files:

LlmDemoRoutes.cs — three shapes of the LLM call: inline step (.Llm("demo-stub")), endpoint (.To("llm://demo-stub")), tool (.AsLlmTool("echo_tool")). All on the stub provider, no API keys.
LlmHttpRoutes.cs — two HTTP endpoints (/api/llm/ask no tools, /api/llm/shell with the shell tool through redb.Route.Exec), both passing X-Chat-Id for conversation memory, both running real Claude Haiku.

dotnet run from redb.Route.Demo, port 5088 opens, and curl works:

curl -d "what time is it on this host?" -H "X-Chat-Id: test1" \
     http://localhost:5088/api/llm/shell

Repo: github.com/redbase-app/redb-route (Apache 2.0).

What's not done, and why I keep saying so

Sliding-window memory isn't done. A real vector store isn't done. There's no AI-graph editor in tsak.web — runtime conversation inspection shows up as plain REDB objects in the existing UI, no special pane. There's no built-in eval-service integration — EvalRunStore records the runs, but "click compare against prod" is manual.

That's fine. The skip-list is a technique, not an apology. An open-source project that lies in its README about scope is one you don't come back to. I'd rather say "not yet" and ship it next minor than say "shipped" and field issues for two months.

Zooming out: why the ESB shape matters

The phrase "AI-native architecture" is fashionable. What it usually means is "we built everything around the LLM" — and what usually backs that up is a new dev stack running parallel to the old one. That's not an architecture decision. That's a policy duplication problem.

If you have retry in two stacks, audit in two stacks, governance in two stacks, tenant isolation in two stacks — those two implementations drift. A year later, the AI stack adds bounded-context auditing, the integration stack doesn't. Legal asks for one report — nobody can produce it. The duplication wasn't visible on day one; it's load-bearing on day three hundred.

The ESB shape is a deliberate choice of one control point for I/O of all kinds. The LLM is a kind of I/O — asynchronous, with tools, with context, but I/O. Putting it inside the ESB isn't a philosophical pose; it's engineering economy: one governance policy covers everything.

This is not new. Garland and Ripley wrote it up in the SOA literature of the 2000s. What's new is that in 2026 the argument finally applies to LLMs, because LLMs grew up enough to expose standard interfaces: tool use, streaming, batch APIs, embeddings. Before that, "LLM in the ESB" meant "wrap a REST call and pray". Now it means "use existing EIP patterns with minor adaptations".

That economy is the entire pitch of redb.Route.Llm. Not "we have the best agent engine." Microsoft and LangChain have better agent engines. We have a perfectly average agent engine in the right place in the architecture. I'll take that trade.

Roadmap

3.1.2:

sliding-window memory as a built-in policy;
a vector-store interface behind IKnowledgeStore;
pgvector and Qdrant as the first back-ends;
an EvalCompare DSL for side-by-side prompt-version runs.

3.2:

a ConversationProps tree UI in tsak.web;
streaming-aware aggregator EIP (buffer partial frames to semantic boundaries);
distributed batch — multiple workers behind one LlmCallbackProcessor.

Later:

multi-modal (image input/output as a payload type);
voice agents as another transport (voice://...);
routing by cost / latency / accuracy SLA per message.

Links

Part 1 (3.1.0 announcement): redb.Route 3.1.0 — LLM as just another connector
redb.Route — Apache Camel for .NET
EIP series part 1 — channels and Exchange
redb.Route 3.0.1 patch notes
GitHub: github.com/redbase-app/redb-route (Apache 2.0)
Demo routes: redb.Route/demos/redb.Route.Demo/Routes/LlmDemoRoutes.cs, LlmHttpRoutes.cs
Habr companion (Russian, not a translation): link added after publication

TL;DR. Three weeks ago I shipped 3.1.0 with an honest skip-list. Three weeks later, most of it is shipped: streaming end-to-end, tool cache, RAG knowledge store, async batch + callback consumer, eval-run store, versioned prompt registry, multi-tenant ?redb=<name>, idempotent tool retries, human-in-loop approval gates, full audit. On top, two patterns that ship the architecture's real punchline: a jury of cheap models with a senior model as arbiter, dropping straight onto stock Scatter-Gather + Aggregator EIP — no custom orchestrator; and sub-agents as tools — recursive agent composition where one agent's tool is itself an agent with its own model, prompt, budget, RAG corpus, all working out of the box because RouteToolBridge → direct: → llm:// is a fixed point. Plus three honest enterprise scenarios with code: a daily CFO snapshot to inbox, a weekly cash-flow forecast with jury arbitration, and a predictive plant alert that hands XGBoost the prediction and the LLM the sentence. The point isn't the feature checklist. The point is that enterprise-grade properties land on the day you actually need them, with no rewrite, because the LLM lives inside the ESB along with every other I/O. Those six lines you typed for the Day-1 chat demo are literally the same file that's running the Day-90 multi-tenant audit-grade platform. There's no "now we rewrite" moment in this story.

redb.Route 3.1.0 — LLM(AI) as just another connector: `.To("llm://claude")` and tools-as-routes

rinat kozin — Tue, 09 Jun 2026 14:19:01 +0000

Series: redb ecosystem (announcement; deep-dive separate)

redb.Route 3.1.0 just shipped two new transports: redb.Route.Llm (the 24th) and redb.Route.Exec (the 25th). The LLM is now an addressable endpoint the same way Kafka, RabbitMQ and HTTP are: calling a model is .To("llm://claude"), an agent tool is a route with .AsLlmTool("shell") on it, a scheduled agent is From("llm://factory?schedule=5m"). Exec is a process spawner with allowlist, working-directory and timeout — both the backend that powers shell tools for agents and a first-class scheduled consumer in its own right (cron-less health probes, backups, deploy glue). No parallel "AI framework" sitting next to the integration framework — same DSL, same retry/throttle/circuit-breaker/audit, same OpenTelemetry traces, same dashboard endpoint counters.

This post is the announcement. A deep-dive on the agent loop, the governance hooks and the REDB storage internals will follow as a separate piece. Here: what landed, what it looks like in code, and what's honestly not done yet.

First time reading about redb.Route? Short context from earlier posts in the series:

redb.Route — Apache Camel for .NET: 22 transports, 30+ EIP patterns, compiled DSL — why it exists, and what "Apache Camel for .NET" actually means

RedBase / redb.Route / redb.Tsak 3.0.0 shipped — the 3.0.0 release that this LLM connector slots into

Enterprise Integration Patterns in .NET — Part 1: the four in-memory channels (and the Exchange they carry) — how the runtime is built, if you want internals

redb.Route 3.0.1 — flat DSL navigation, CRTP refactor, and a silent null fix — the previous patch right before 3.1.0

The shortest possible explanation

From("kafka://orders")
    .To(Llm.Factory("claude").Temperature(0.2).MaxTokens(1024).AsUri())
    .To("kafka://orders.translated");

One line, one full LLM call:

the inbound message body becomes the user prompt;
the agent runs (provider call → optional tool_use → next provider call → …) until EndTurn or MaxIterations;
the assistant text lands in exchange.Out.Body;
token usage, model id, stop reason, iteration count are pushed into headers;
OpenTelemetry traces and metrics light up automatically;
the endpoint shows up in the tsak.web dashboard with msg/sec, average duration, error rate and last-error info — like every other connector.

That's the whole reason "connector, not library" matters. If you already have an Apache Camel-class ESB with retry, breaker, idempotent consumer and audit, the only honest move is to turn the LLM into one more endpoint inside it. No re-implementing retries. No separate dashboard. No "AI infra" running parallel to the integration infra.

One adapter, 14 OpenAI-compatible APIs

Two production providers ship today:

OpenAiProvider — one universal transport for 14 OpenAI-compatible APIs: openai, anthropic/claude (via Anthropic's official OpenAI-compat endpoint), groq, cerebras, openrouter, gemini (OpenAI-compat surface), github-models, mistral, together, huggingface, deepseek, ollama, lmstudio, plus a generic custom for any self-hosted gateway.
StubProvider — deterministic echo for unit tests and CI runs with no keys.

A native AnthropicProvider (Messages API) is on deck for features the OpenAI-compat surface doesn't expose.

Switching provider is one DI registration:

services.AddLlmConnectionFactory("groq", f =>
{
    f.Provider = "groq";
    f.ModelId  = "llama-3.3-70b-versatile";
    f.ApiKey   = Environment.GetEnvironmentVariable("REDB_LLM_GROQ_KEY");
});

Change provider to "anthropic" and modelId to "claude-haiku-4-5" and the same .To("llm://...") is calling Claude. The DSL surface doesn't move a character.

Tools are routes

The central architectural call: a tool is an ordinary RouteBuilder route with one extra DSL aspect, .AsLlmTool("name"). Four properties fall out of that and would otherwise have to be paid for separately.

From("direct:tool-shell")
    .AsLlmTool("shell")
        .Description("Run a small shell command on the host. Input: {\"command\":\"<name>\",\"args\":[\"...\"]}.")
        .Input("""
            {
              "type":"object",
              "properties":{
                "command":{"type":"string"},
                "args":{"type":"array","items":{"type":"string"}}
              },
              "required":["command"]
            }
            """)
        .SideEffect(ToolSideEffect.ReadOnly)
        .Cost(ToolCostClass.Cheap)
    .Then()
    .To(ExecDsl.Run()
        .AllowedCommands("cmd", "pwsh")
        .WorkingDirectory(scratchDir)
        .TimeoutMs(5_000)
        .MaxStdoutBytes(8_192)
        .MaxStderrBytes(8_192));

What you get for free:

Tools-as-routes. The 30+ EIP processors are usable inside a tool — Splitter, Aggregator, CircuitBreaker, Throttle, Filter, TryCatch. A tool that talks to a fragile API gets wrapped in a breaker and a throttle without a line of runtime glue.
Tools from existing routes. Any From("http://...") or From("sql://...") you already have becomes a tool by adding .AsLlmTool("name"). Its auth, its audit trail, its metrics are already in place — because it's already a route.
Inventory-as-data. IToolDescriptorRegistry knows every tool by name with its JSON schema. Filter with ?tools=* or ?tools=lookup,shell on the URI; build "an agent that has every read-only tool" in one line.
Zero bumps on sibling connectors. The AsLlmTool() aspect lives in redb.Route.Llm.Abstractions. The other 22 connectors can be used as tools today without a NuGet bump on any of them.

A real example — a standalone "curl → Claude → shell → reply" demo

This is a complete program. Two files — Llm.HttpShell.csproj and Program.cs, top-level statements, no host abstractions on top. Drop your Anthropic key into one place and dotnet run brings up an HTTP endpoint on port 5088 where Claude Haiku can call a shell on the host and answer in the context of the previous turns.

csproj — five NuGet packages

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="redb.Route" Version="3.1.0" />
    <PackageReference Include="redb.Route.Http" Version="3.1.0" />
    <PackageReference Include="redb.Route.Llm" Version="3.1.0" />
    <PackageReference Include="redb.Route.Llm.Abstractions" Version="3.1.0" />
    <PackageReference Include="redb.Route.Exec" Version="3.1.0" />
    <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="9.0.0" />
  </ItemGroup>
</Project>

redb.Route is the ESB core, redb.Route.Http is the HTTP transport, redb.Route.Llm[.Abstractions] is the LLM connector and the .AsLlmTool() DSL aspect, redb.Route.Exec is the process spawner with allowlist and timeout. No redb.Core/redb.Postgres — the demo is self-contained and keeps conversation memory in process.

1. The key

const string ApiKey = "<your-key>";

The one you get from https://console.anthropic.com/. Switching to Groq is Provider = "groq", ModelId = "llama-3.3-70b-versatile" and a key from console.groq.com; the DSL below doesn't move.

2. DI and `RouteContext`

RouteContext ctx = null!;

var services = new ServiceCollection();
services.AddLogging(b => b
    .AddSimpleConsole(o => { o.SingleLine = true; o.TimestampFormat = "HH:mm:ss "; })
    .SetMinimumLevel(LogLevel.Information));
services.AddSingleton<IRouteContext>(_ => ctx);
services.AddSingleton<ILogger>(sp => sp.GetRequiredService<ILoggerFactory>().CreateLogger("redb.Route"));

var sp = services.BuildServiceProvider();
ctx = new RouteContext(sp, contextId: "llm-http-shell");
ctx.AddService(typeof(ILoggerFactory), sp.GetRequiredService<ILoggerFactory>());

RouteContext is the runtime container — routes, components, services. The _ => ctx closure registers IRouteContext as a DI service before the context itself is constructed (the context in turn needs the IServiceProvider). The last line hands ILoggerFactory to the context explicitly; without it .Log(...) steps in routes silently turn into no-ops (internals belong to the deep-dive piece).

3. Three components

ctx.AddComponent(new HttpComponent { ServerManager = new SharedHttpServerManager() });
ctx.AddComponent(new LlmComponent());
ctx.AddComponent(new ExecComponent());

A component in redb.Route is a transport plugin owning a URI scheme: http://, llm://, exec://. Pure registration, no business logic.

4. Connection factory for Claude Haiku

ctx.AddToRegistry("haiku", new LlmConnectionFactory
{
    Name        = "haiku",
    Provider    = "anthropic",
    ModelId     = "claude-haiku-4-5",
    ApiKey      = ApiKey,
    Temperature = 0.0,
    MaxTokens   = 512
});

"haiku" is the label the route will reference as Llm.Factory("haiku"). Same trick redb.Route uses framework-wide for named connection factories.

5. Agent engine + tool registry

var toolRegistry = new ToolDescriptorRegistry();
ctx.AddService(typeof(IToolDescriptorRegistry), toolRegistry);

var producerTemplate = new ProducerTemplate(ctx);
ctx.AddService(typeof(IProducerTemplate), producerTemplate);

var engine = new AgentEngine(
    logger:           null,
    producerTemplate: producerTemplate,
    observer:         new NoopAgentObserver(),
    budget:           new NoopBudgetEnforcer(),
    approval:         new AutoApproveGate(),
    redaction:        new NoopRedactionFilter(),
    shadow:           new NoopShadowRunner(),
    conversation:     new InMemoryConversationStore(),
    idempotency:      null,
    approvalStore:    null);
ctx.AddService(typeof(IAgentEngine), engine);

Every agent state surface — observability, budget, approval, redaction, shadow, conversation, idempotency — lives behind an interface. The demo wires Noop/InMemory implementations everywhere: the loop runs but nothing is persisted. Production swap is AddRedbLlmStorage() (covered below): replaces InMemoryConversationStore with RedbConversationStore, attaches RedbAuditObserver, etc.

6a. The HTTP route

var isWindows  = OperatingSystem.IsWindows();
var allowed    = isWindows ? new[] { "cmd", "pwsh", "powershell" } : new[] { "sh", "bash" };
var scratchDir = Path.Combine(Path.GetTempPath(), "redb-llm-shell");
Directory.CreateDirectory(scratchDir);

var systemPrompt =
    "You can run small shell commands through the 'shell' tool. " +
    $"The host is {(isWindows ? "Windows (use cmd /c)" : "Linux (use sh -c)")}. " +
    "Use the tool when the user asks about the system, files, or commands; " +
    "then summarise what you learned in one short sentence.";

ctx.AddRoutes(r =>
{
    r.From("http:0.0.0.0:5088/api/llm/shell?inOut=true")
        .RouteId("llm-http-shell")
        .ConvertBody<string>()
        .Process(e =>
        {
            e.In.Headers[LlmHeaders.SystemPrompt] = systemPrompt;
            e.In.Headers[LlmHeaders.ConversationId] =
                e.In.Headers.TryGetValue("X-Chat-Id", out var v) && v is string s && s.Length > 0
                    ? s : "default";
        })
        .Log("[LLM-SHELL] ▶ chat=${header.llm.conversation.id} prompt=${body}")
        .To(LlmDsl.Factory("haiku")
            .Tools("shell")
            .ConversationFromHeader()
            .MaxIterations(10)
            .Temperature(0.0)
            .AsUri())
        .Log("[LLM-SHELL] ◀ iters=${header.llm.tool.iterations} stop=${header.llm.stop_reason} " +
             "tokensIn=${header.llm.tokens.in} tokensOut=${header.llm.tokens.out}")
        .Log("[LLM-SHELL] ◀ reply=${body}");

The POST body is converted to a string and becomes the user prompt. Process puts the system prompt into the standard LlmHeaders.SystemPrompt header and resolves the conversation id from the client's X-Chat-Id (without it — default). .Tools("shell") is the only LLM-specific knob: "give the agent the tool registered under this name." MaxIterations(10) caps the tool loop (otherwise it's an unbounded ping between model and tool).

6b. The tool itself is a route

    r.From("direct:tool-shell")
        .AsLlmTool("shell")
            .Description(
                "Run a small shell command on the host. Input: " +
                "{\"command\":\"<name>\",\"args\":[\"...\"]}. Output: " +
                "{\"stdout\":\"...\",\"stderr\":\"...\",\"exitCode\":N}. " +
                $"Allowed commands: {string.Join(", ", allowed)}. " +
                $"Working directory is pinned to '{scratchDir}'.")
            .Input("""
                {
                  "type": "object",
                  "properties": {
                    "command": { "type": "string" },
                    "args":    { "type": "array", "items": { "type": "string" } }
                  },
                  "required": ["command"]
                }
                """)
            .SideEffect(ToolSideEffect.ReadOnly)
            .Cost(ToolCostClass.Cheap)
        .Then()
        .Log("[SHELL-TOOL] ▶ in=${body}")
        .To(ExecDsl.Run()
            .AllowedCommands(allowed)
            .WorkingDirectory(scratchDir)
            .TimeoutMs(5_000)
            .MaxStdoutBytes(8_192)
            .MaxStderrBytes(8_192))
        .Log("[SHELL-TOOL] ◀ exit=${header.redbExec.ExitCode} body=${body}");
});

Description and the JSON schema are what Claude sees as "this function is available, here's its signature." SideEffect.ReadOnly and Cost.Cheap are guidance for the governance hooks (budgets, approval gating). After .Then() it's an ordinary route: Log → ExecDsl.Run() with allowlist, working dir, 5-second timeout and a stdout/stderr cap → Log. No LLM-specific code below .Then(). It's still just a route — which means you can wrap it in a CircuitBreaker, a Throttle, a Transaction, a WireTap shadow, anything from the 30+ EIP processors redb.Route already ships.

7. Start and block

await ctx.Start();
producerTemplate.Start();

var stop = new ManualResetEventSlim();
Console.CancelKeyPress += (_, e) => { e.Cancel = true; stop.Set(); };
stop.Wait();

await ctx.DisposeAsync();

Run it

dotnet run

curl -d "how much free disk space?" http://localhost:5088/api/llm/shell
curl -d "what did you just say?" -H "X-Chat-Id: my-chat" http://localhost:5088/api/llm/shell

First request: Claude sees the system prompt ("you have a shell tool"), decides to check free space, calls the tool with something like {"command":"cmd","args":["/c","fsutil","volume","diskfree","C:"]}, gets the stdout back, summarises it for the human. Second request, with X-Chat-Id: my-chat, finds the previous turn in InMemoryConversationStore and answers in context.

The logs at that moment show the full path: [LLM-SHELL] ▶ prompt=... → [SHELL-TOOL] ▶ in={"command":"cmd",...} → [SHELL-TOOL] ◀ exit=0 body={"stdout":"...","exitCode":0} → [LLM-SHELL] ◀ iters=2 stop=end_turn tokensIn=... tokensOut=... reply=.... All of it is just the redb.Route .Log() step, not a separate LLM-tracing pipeline.

The command allowlist (cmd, pwsh, sh, bash) is the security envelope: anything outside it is rejected by redb.Route.Exec before a process starts.

`redb.Route.Exec` — process spawning as the 25th transport

In the demo above ExecDsl.Run() showed up as "the backend of the shell tool", but it's a connector in its own right, shipped in 3.1.0 alongside redb.Route.Llm. It closes a boring but ubiquitous gap: the framework already spoke 22+ transports (HTTP, Kafka, SQL, …), but reaching out to the operating system itself was missing.

Producer — .To(ExecDsl.Run(...)) — synchronous spawn. The command is resolved in this order: JSON body → headers redbExec.Command/redbExec.Args → URI options ?command=.... The Out body is JSON shaped for the LLM tool ABI:

{ "stdout": "...", "stderr": "...", "exitCode": 0, "timedOut": false }

This is exactly why the shell tool in the demo is .To(ExecDsl.Run().AllowedCommands(...)) with zero glue code in between. The model produces {"command":"cmd","args":[...]}, the producer parses it, runs it, returns structured JSON. Route-level features (CircuitBreaker, Throttle, OnException, audit) apply automatically — it's an endpoint like every other one.

Consumer — From(ExecDsl.Run(...).Schedule("5m")) — same spawner, but as a first-class source endpoint with a built-in scheduler. No cron, no separate worker:

routes.From(ExecDsl.Run("./scripts/health-check.sh")
                   .Schedule("5m")
                   .TimeoutMs(30_000))
      .Choice()
        .When(e => e.In.Headers["redbExec.ExitCode"]?.ToString() != "0")
          .To("http://alerts.internal/oncall")
        .Otherwise()
          .To("kafka://metrics.healthy");

Every 5 minutes the script runs, the route branches on exit code — one way to an HTTP webhook for the on-call, the other to a Kafka topic. ?schedule= accepts simple intervals (500ms, 30s, 5m, 1h). For cron expressions: From("quartz://<cron>").To(ExecDsl.Run(...)) — Quartz is already a scheduler, no point re-implementing it inside Exec.

The security envelope — what gives shell-as-a-tool the right to exist in the first place:

AllowedCommands — case-insensitive on the file name, so /usr/bin/git and git.exe both match git. Anything off the list is rejected with UnauthorizedAccessException before the process starts.
WorkingDirectory — pins the cwd; the spawned process can't escape it on its own.
EnvironmentOverrides + ScrubEnvironment — start from an empty environment and apply only the KEY=VALUE pairs you set.
TimeoutMs — wall-clock kill-switch that takes the whole process tree.
MaxStdoutBytes / MaxStderrBytes — caps that protect the host from a runaway process.

Why a separate package, not part of redb.Route.Llm — three reasons: (1) Exec is useful with no LLM in sight (scheduled health probes, log rotation, deploy glue, backups); (2) redb.Route.Llm shouldn't drag a dependency on process spawning into projects whose agents only call HTTP or SQL tools; (3) the same allowlist/timeout/cap mechanism will be reused by future connectors that share the same security profile.

`From("llm://...")` — the scheduled agent consumer

This is the bit that has no equivalent in Camel's langchain4j-* family (where LLM is producer-only): the LLM endpoint is a first-class source, with the scheduler baked in.

From("llm://groq?schedule=5m" +
     "&systemPromptRef=#watchdog-system" +
     "&initialBodyRef=#daily-brief" +
     "&tools=*")
    .To("rabbitmq://alerts");

Every 5 minutes: a fresh agent run with the system prompt resolved from registry key #watchdog-system and the user prompt from #daily-brief. The reply goes to RabbitMQ. ?schedule= takes simple intervals (500ms, 30s, 5m, 1h); for cron use From("quartz://...").To("llm://...") — Quartz is already a scheduler, no point duplicating it inside the LLM consumer.

Use cases that fit this shape: watchdog agents, scheduled report generation, self-improving agents with conversation memory (same history across runs).

`#`-prompts — the dynamic registry

A # prefix on a URI parameter turns the value into a registry lookup. Some other route can rewrite the prompt by name; the next agent run picks it up without a redeploy:

host.Context.AddToRegistry("style.terse", "Reply in fewer than 5 words.");

r.From("direct:chat")
    .To("llm://scripted?systemPromptRef=#style.terse")
    .To("mock:done");

// ... later, from another route ...
host.Context.AddToRegistry("style.terse", "Reply in French only.");
// the next call sees the new value

Resolution: first IPromptTemplateRegistry (versioned, what eval replay needs), then the generic context registry (a plain string). Without # the value is literal and arrives at the provider unchanged.

This is the same #name registry convention redb.Route uses framework-wide for connection factories. Same convention, not a separate prompt-ref DSL.

Agent memory — `AddRedbLlmStorage()`

By default every state surface is in-memory (conversation transcripts, tool idempotency, approvals, cost ledgers, audit). That keeps AddRedbRouteLlm() zero-dependency — fine for tests and stateless agents, lost on restart.

One line swaps the defaults for REDB-backed stores:

services.AddRedbRoute(route =>
{
    route.Services.AddRedbRouteLlm();
    route.Services.AddRedbIdempotentRepository();   // required for idempotency
    route.Services.AddRedbLlmStorage();             // ← REDB stores on every surface
});

What AddRedbLlmStorage() replaces:

Interface	Default	REDB store
`IConversationStore`	`InMemoryConversationStore`	`RedbConversationStore` — tree-backed, parent linkage via native `parent_id`, message ids on indexed `value_string`
`IToolIdempotencyStore`	`InMemoryToolIdempotencyStore`	`RedbToolIdempotencyStore` (on top of `IIdempotentRepository`)
`IApprovalStore`	`InMemoryApprovalStore`	`RedbApprovalStore`
`ICostBudgetStore`	`InMemoryCostBudgetStore`	`RedbCostBudgetStore` — running totals per tenant/window
`IAgentObserver`	`NoopAgentObserver`	`RedbAuditObserver` — one row per tool call

Two non-obvious design choices:

Per-row business identifiers live on _objects.value_string (an indexed column), not inside the props JSON. Lookups are O(log n) on one column, not a full scan with JSON decode.
Transcript integrity is the tree's native parent_id (IRedbService.CreateChildAsync), not a soft FK in props. The tree primitive enforces it.

Stores lazy-sync their scheme on first use. No migration step.

What the engine carries for free

This is the central argument for "connector, not library." Everything redb.Route already does applies to LLM calls without extra code:

Concern	DSL primitive
Retry / backoff	`RedeliveryPolicy`, `OnException`
Rate limiting	`Throttle`
Resilience	`CircuitBreaker`
Idempotency	`IdempotentConsumer`
Compensation	`Saga`
Audit / shadow	`WireTap`, `Multicast`
Tracing & metrics	`RouteActivitySource`, `RouteMetrics`
Persistence	`redb` schemes (typed object engine)

A tool that calls an expensive API gets wrapped in a CircuitBreaker and a Throttle. Want a shadow run of a new system prompt alongside the old one? Multicast + WireTap. These aren't "features of the LLM connector" — they're the engine, and the LLM is attached to it as an endpoint.

What's live-tested, and what isn't

The honest status of the provider matrix (this is in the README, repeated here):

Groq + Llama 3.3 70B — the most reliable free tier in scope. Carries the strict assertion in BasicChatTests and ToolRouteTests (the model has to produce a literal token).
Mistral small-latest — stable for short-form replies; tool-use on the free tier is flaky, so tool tests assert philosophically.
Gemini 2.0 Flash — 15 RPM on free; works on a quiet repo.
Anthropic Claude (Haiku 4.5 / Sonnet 4.6) — via the OpenAI-compat endpoint, live-tested in ClaudeChatTests and the redb.Route.Demo host.
OpenRouter / Cerebras — scaffolding works; individual free models rate-limit; tests gated on [EnvFact] and skipped without a key.

Honest skip-list, things not in this release:

Embeddings and vector stores — Phase 2 (embed://, vector:// schemes are planned).
RAG primitives, document loaders, web search — not first-class yet (a Tavily search tool is already shipped in redb.Route.Llm.Tools and plugs in as any other .AsLlmTool("web_search")).
Sliding-window memory shapes (window-by-N-messages, window-by-K-tokens) — not first-class. Persistent transcripts via AddRedbLlmStorage() are shipped; a windowed shape on top is realizable today via Process + the conversation store, just not as a one-line option.
Native AnthropicProvider — OpenAI-compat surface covers most scenarios; the native Messages API is for the features the compat surface doesn't expose.

Links

GitHub leads NuGet. Fresh bug fixes (e.g. the tool_use/tool_result
pairing recovery on conversation reload, or the Windows OEM-codepage
decoding fix in redb.Route.Exec) are already cut on main under version
3.1.1 — see CHANGELOG.md
in the public repo. NuGet packages are batched into the next release, so
if you hit a production bug — check main and the latest pre-release tag
first, then wait for the NuGet bump. This is normal practice, not a
process bug.


redb.Route on GitHub	github.com/redbase-app/redb-route
redb.Route.Llm on NuGet	nuget.org/packages/redb.Route.Llm
redb.Route.Exec on NuGet	nuget.org/packages/redb.Route.Exec
Full package README	redb.Route.Llm/README.md
USER-GUIDE (full walkthrough — DSL, governance, conversation)	redb.Route.Llm/doc/USER-GUIDE.md
STORAGE — REDB schemas for conversation / approval / audit / idempotency	redb.Route.Llm/doc/STORAGE.md
Exec connector README	redb.Route.Exec/README.md
Standalone `Llm.HttpShell` demo (curl → Claude → shell → reply)	demo/Llm.HttpShell/Program.cs
Full demo project (22+ routes)	demo/redb.Route.Demo/Routes/LlmHttpRoutes.cs
Discussions	github.com/redbase-app/redb-route/discussions

All Apache 2.0. A separate deep-dive will cover the agent tool-loop, the governance hook interfaces, and a tour of the REDB storage schemas. Questions in the comments are exactly what writes the next post — especially anything along the lines of "does the connector do X if I do Y?"

REDB inside, part 1.1 — why the same 13 tables stay fast no matter how many classes you throw at them

rinat kozin — Mon, 08 Jun 2026 21:57:41 +0000

A couple of weeks ago I published REDB inside, part 1 — the 13 tables the whole engine runs on. It walked through _objects, _values, _structures, why this isn't classical EAV, and what the _scheme_metadata_cache does. If you haven't read it, start there — the rest of this post assumes you know the layout.

This is part 1.1, not part 2. Same physical-storage conversation, different angle. Part 2 is going to be about code-first schemes (SyncSchemeAsync<T>), and the deep C# dive — LINQ translator, CRUD internals, trees — that's parts 3 through 5 of the series. This post stays in the database layer.

The reason for a 1.1 instead of jumping to 2 is simple: every time I publish part 1, the same question comes back in the comments and in DMs:

"Fine, typed columns beat string EAV. But you've still got 9.7 million rows in _values. Any real query — WHERE Salary > 80000, WHERE OrderDate >= '2026-06-01' — has to scan that table. Without one index per field per schema you're living in Seq Scan."

Fair question. Let's actually answer it, with the DDL, the prod numbers, and a side note about how to remove indexes once your app stabilizes.

Numbers in this post come from TSUM — a logistics system handling truck movements and orders through distribution centers. Real production, no benchmark setup.

TL;DR: In a classical EF schema, indexes multiply with tables. In REDB, the index set is designed once in DDL and serves any business schema you put on top — adding the 33rd class to your domain doesn't add a single line to redbPostgre.sql. The active surface for any business class is just 2 tables (_objects + _values), plus 2 more for lookups and 3 for RTTI metadata; the rest is infrastructure that doesn't grow with your class count. On TSUM prod this gives 999 orders / 991 ms on 2 cores with default Postgres settings and zero framework-level cache: one SELECT pulls all 999 existing routes (139 ms), bulk-save writes 32 changed objects through the COPY protocol (154 ms), and 967 unchanged rows never reach the database thanks to an app-level ComputeHash() short-circuit.

The "9.7 million rows" objection, defused in two sentences

Before we open any DDL, here's the structural answer to the objection above.

Classical EAV has rows like (object_id, attribute_name TEXT, value TEXT). An index on value is useless there because values are heterogeneous, casts happen at runtime, and selectivity on attribute_name is low. REDB is not that.

Two things change the picture:

Values are already split into typed columns. _Long, _String, _Numeric, _DateTimeOffset, _Boolean, _Guid, _ListItem, _Object. No casts at query time. An index on _Long is a normal bigint btree, not a polymorphic guess.
Every row in _values carries _id_structure — a bigint pointing at the schema field it belongs to. With 401 fields across the TSUM domain, WHERE _id_structure = X discards roughly 99.75% of the table before the optimizer even looks at the value column.

So a facet query never scans 9.7M rows. It scans ~_values_count / structure_count rows, then does an Index Only Scan on a typed column. We'll see this in the EXPLAIN-equivalent reasoning below.

That's the architecture. Now the question that actually matters: how exactly are the indexes laid out so that this runs in milliseconds?

The architectural payoff: indexes don't grow with your domain

In a classical EF layout, the table count grows linearly with business entities. Each table averages 3–5 indexes — primary key, FK indexes, business filters. So the total number of indexes in the database grows multiplicatively with project size.

Take TSUM. Here's what's in tsum.Domain/Entities:

TransportationRoute (the actual route)
TransportationPoint (route stops)
Driver, Vehicle, ShippingPoint, YardPlace
SliceSettings, SliceSnapshot, TransportSnapshot, TransportNorm
SpecialRcSettings, TonnageGroupSettings, GarageState
TsumAdUserRef, UserFilterPreference

Fifteen "root" entities. But that's just the start. Inside TransportationRoute alone you'll find RedbListItem references to: Drivers, Vehicles, CarMarks, ShippingPoints, BusinessTypes, YardPlaces (×2 — PlaceTo / PlaceFrom), LoadingZones, TransportStatuses, DeliveryStatuses, TripRisks. Every other entity has its own set: chassis types, readiness statuses, delay reasons, route classifications.

In a classical schema, every one of those lookups is its own table. Plus audit/history tables (TransportSnapshot, SliceSnapshot are clearly snapshot entities). Plus M2M tables for collection links. A realistic estimate for TSUM in a classical layout is 60–80 tables.

At 60–80 tables and 3–4 indexes per table, you're looking at 200–320 indexes to design, maintain, reindex, and drop when stale. Every release in an EF project ships an AddColumn + CreateIndex migration. By year two, somebody walks the schema with a flashlight removing duplicate indexes that piled up because three different developers added similar-but-not-identical indexes for slightly different queries.

In REDB the picture is different. The same 32 schemes / 401 properties in TSUM physically have 2 primary keys: pk__objects and pk__values. The full index list is hardcoded in redbPostgre.sql and runs around 50 indexes — for the entire system. Not per class. For the system.

Now here's the clarification I owe readers from part 1. I called REDB "13 tables" in that post, and a fair number of people walked away with the impression that all 13 are involved every time you query a class. They aren't. The actual breakdown is:

Data storage — 2 tables: _objects (the header) and _values (the field values). Every Query<T>(), every SaveAsync, every LINQ filter lands here.
Lookups — 2 tables: _lists and _list_items. These power RedbListItem fields (Driver, Vehicle, ShippingPoint, etc.). Lookups are shared across classes and don't grow when you add a new business entity.
RTTI / schema metadata — 3 tables: _types (primitives), _schemes (classes), _structures (class properties). The engine reads these through _scheme_metadata_cache; business queries never touch them.
Everything else — infrastructure: _users, _roles, _permissions, _links, _dependencies, _functions, _scheme_metadata_cache, soft-delete via @@__deleted. These don't grow with class count and aren't on the hot path.

So whatever class a developer writes in tsum.Domain, its data physically lives in 2 tables; reference fields hit 2 more for lookups; schema metadata sits in 3 RTTI tables. The six infrastructure tables look identical for a 5-class project and a 500-class one. That is what "indexes invariant of class count" really means — not "all 13 tables on every query," but "the active footprint for business data is two tables, and it doesn't change."

When a developer adds the 33rd class to tsum.Domain — say, WarehouseSlot — the database gets:

one row in _schemes,
N rows in _structures (one per property),
zero index migrations. None.

Because the entire query surface for the new class is served by the same indexes on _objects and _values that served the previous 32. WHERE _id_scheme = ID(WarehouseSlot) uses IX__objects__schemes. Sort by creation date — IX__objects__scheme_date_create. Find an object by some property value — IX__values__structure_object_lookup. Parent–child tree — IX__objects__scheme_parent.

This is the architectural payoff the post is built around. The index plan is fixed at engine design time, not smeared across business-app releases. The skeptic will counter: "so generic indexes on _values must be slower than per-field indexes in an EF schema." They aren't — and we'll see why below.

The same applies to MSSQL. Worth saying out loud: this post isn't Postgres-specific. redb.MSSql/sql/redbMSSQL.sql carries a mirror set of indexes with minor dialect differences (covered in a later section). The architectural trick — indexes on the physical schema, not on business tables — ports between engines without giving anything up.

A tour of `redbPostgre.sql`, grouped by what it's for

If you open the DDL and read top to bottom you'll see ~50 indexes interleaved. They're easier to understand grouped by use case rather than by table. Let's do it that way.

1. Storage uniqueness in `_values`

Three partial-unique indexes, one per shape:

-- Scalar fields: one (object, field) → one value
CREATE UNIQUE INDEX UIX__values__structure_object
ON _values (_id_structure, _id_object)
WHERE _array_index IS NULL AND _array_parent_id IS NULL;

-- The marker row for a nested class/array inside a parent
CREATE UNIQUE INDEX UIX__values__structure_object_parent
ON _values (_id_structure, _id_object, _array_parent_id)
WHERE _array_index IS NULL AND _array_parent_id IS NOT NULL;

-- Collection elements indexed by position/key
CREATE UNIQUE INDEX UIX__values__structure_object_array_index
ON _values (_id_structure, _id_object, _array_parent_id, _array_index)
WHERE _array_index IS NOT NULL;

Why three instead of one. Each shape has a different uniqueness key. Scalars are unique by (structure, object). Nested-structure markers add parent. Array elements add index. A single covering unique index can't express this (NULLs would break the semantics), but three partials map cleanly onto the physical model.

Bonus: each partial only stores its slice of rows, so the btree is smaller than one giant unique index would be. On 9.7M rows that's tens of percent saved in page cache.

2. Facet search — the hottest path

A facet query in REDB is "find objects whose field X compares to Y." In SQL terms:

SELECT v._id_object FROM _values v
WHERE v._id_structure = @structure_id
  AND v._Long > 80000;

That pattern is served by a single composite index:

CREATE INDEX IX__values__structure_object_lookup
ON _values (_id_structure, _id_object,
            _Long, _DateTimeOffset, _Boolean, _Double, _Guid, _Numeric, _ListItem, _Object);

Every typed column except _String is in the key. Index Only Scan: Postgres finds the matching rows and grabs the value directly from the index — no heap fetch.

In parallel, two covering indexes with INCLUDE:

CREATE INDEX IX__values__object_structure_lookup
ON _values (_id_object, _id_structure, _array_index)
INCLUDE (_Long, _Double, _DateTimeOffset, _Boolean, _Guid, _Numeric, _ListItem, _Object);

CREATE INDEX IX__values__object_array_null
ON _values (_id_object, _id_structure)
INCLUDE (_Long, _Double, _DateTimeOffset, _Boolean, _Guid, _Numeric, _ListItem, _Object)
WHERE _array_index IS NULL;

These cover the opposite direction: "load all values of an object in one query," for LoadAsync<T>. Same trick — Index Only Scan, zero heap reads.

Why _String is excluded. Postgres btree caps at ~2700 bytes per index row. If a JWT payload ends up in _String at 3 KB, the insert blows up. So strings get their own partial index with a length guard:

CREATE INDEX IX__values__String_not_null
ON _values (_id_structure, _id_object, _String)
WHERE _String IS NOT NULL AND length(_String) < 2000;

Long strings (CMS bodies, base64 payloads) aren't covered — and they aren't filtered with = either. For substring search there's a separate GIN:

CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE INDEX IX__values__String_pattern
ON _values USING gin (_String gin_trgm_ops)
WHERE _String IS NOT NULL;

This serves LIKE, ILIKE, $contains, $startsWith, $endsWith, regex — all through pg_trgm. The MSSQL counterpart is full-text search or a persisted computed column with a filtered index; the choice is in the dialect's DDL.

3. Collections (arrays and dictionaries)

Part 1 covered relational storage of collections — a marker row plus child rows linked by _array_parent_id and _array_index. The supporting indexes:

-- traverse collection elements by index
CREATE INDEX IX__values__array_parent_index
ON _values (_array_parent_id, _array_index);

-- look up by dictionary key (string keys)
CREATE INDEX IX__values__array_key
ON _values (_id_structure, _array_index)
WHERE _array_index IS NOT NULL;

-- partial: only rows that belong to collections
CREATE INDEX IX__values__parent_structure
ON _values (_array_parent_id, _id_structure)
WHERE _array_parent_id IS NOT NULL;

The third one feeds the pivot CTE that reads nested Class/Dictionary fields like AddressBook["home"].City.

4. Object trees (`_objects._id_parent`)

Trees are the backbone of REDB — sections, categories, org charts, all linked through _id_parent:

-- direct children: scheme + parent → id
CREATE INDEX IX__objects__scheme_parent
ON _objects (_id_scheme, _id_parent, _id);

-- covering index for subtree traversal (metadata in INCLUDE)
CREATE INDEX IX__objects__parent_id_descendant_lookup
ON _objects (_id_parent, _id_scheme)
INCLUDE (_id, _id_owner, _date_create, _date_modify)
WHERE _id_parent IS NOT NULL;

-- partial: roots (objects without a parent)
CREATE INDEX IX__objects__root_objects
ON _objects (_id_scheme, _id)
WHERE _id_parent IS NULL;

-- reverse path: child → parent → scheme
CREATE INDEX IX__objects__id_parent_scheme
ON _objects (_id, _id_parent, _id_scheme)
WHERE _id_parent IS NOT NULL;

WhereHasAncestor, WhereHasDescendant, LoadTreeAsync all run through this quartet.

5. Sorting and metadata

-- main "newest first" feed index
CREATE INDEX IX__objects__scheme_date_create
ON _objects (_id_scheme, _date_create DESC, _id);

-- sort by name within a scheme
CREATE INDEX IX__objects__scheme_name
ON _objects (_id_scheme, _name, _id);

-- global indexes for cross-scheme search
CREATE INDEX IX__objects__name ON _objects (_name);
CREATE INDEX IX__objects__hash ON _objects (_hash);

And the indexes for RedbPrimitive<T> (when an object is a primitive — counter, token, single value):

CREATE INDEX IX__objects__value_long ON _objects (_value_long) WHERE _value_long IS NOT NULL;
CREATE INDEX IX__objects__value_string ON _objects (_value_string) WHERE _value_string IS NOT NULL;
CREATE INDEX IX__objects__value_guid ON _objects (_value_guid) WHERE _value_guid IS NOT NULL;
CREATE INDEX IX__objects__value_datetime ON _objects (_value_datetime) WHERE _value_datetime IS NOT NULL;
CREATE INDEX IX__objects__value_numeric ON _objects (_value_numeric) WHERE _value_numeric IS NOT NULL;

All partial. Each one only indexes rows where its value column is set.

6. Schemes and structures (`_structures`, `_schemes`)

These are the cold tables — orders of magnitude smaller than _values, mostly read while building the metadata cache. They still need to be sub-millisecond:

-- covering index for ORDER BY field name
CREATE INDEX IX__structures__name
ON _structures (_name)
INCLUDE (_id, _id_type, _collection_type, _id_scheme);

-- covering lookup by structure ID
CREATE INDEX IX__structures__id_lookup
ON _structures (_id)
INCLUDE (_id_type, _name, _collection_type, _id_scheme);

-- partial: split collection vs non-collection
CREATE INDEX IX__structures__not_collection
ON _structures (_id, _name, _id_scheme)
WHERE _collection_type IS NULL;

CREATE INDEX IX__structures__collection
ON _structures (_id, _id_scheme, _collection_type)
WHERE _collection_type IS NOT NULL;

The DDL comments record the reason: these indexes kill Seq Scan on InitPlan and EXISTS subqueries inside build_hierarchical_properties_optimized, dropping query cost from 6.10 to 4.29 (-30%).

What got removed

redbPostgre.sql has a commented-out block worth quoting:

-- ============================================
-- REMOVED REDUNDANT INDEXES (migration_drop_redundant_indexes.sql)
-- Reason: Covered by composite index IX__values__structure_object_lookup
-- Facet search ALWAYS filters by (_id_structure, _id_object) BEFORE value
-- ============================================
-- CREATE INDEX "IX__values__String" ON _values (_String) ...;
-- CREATE INDEX "IX__values__Long" ON _values (_Long) ...;
-- CREATE INDEX "IX__values__Guid" ON _values (_Guid) ...;
-- ...

That's a cleanup history committed straight into the schema file. Early REDB shipped one index per typed column. Real workloads showed they never lit up: facet queries always start from _id_structure, never from a raw value column. The composite (_id_structure, _id_object, _Long, ...) swallowed them whole. The single-column ones got pulled.

Why this is fast on prod

Architecture is half the story. The other half is the actual numbers. Here's a typical TSUM order-processing tick from production logs:

[TSUM] orders=999 routes(+2 ~30 =967) drivers(+0 ~0) vehicles(+0 ~0)
       sync=482 query=139 save=154 total=991ms

What it means:

[TSUM] orders=999 routes(+2 ~30 =967) drivers(+0 ~0) vehicles(+0 ~0) sync=482 query=139 save=154 total=991ms

999 orders arrived in one XML batch from SAP S/4 (the stored procedure usp_TsUM_MonitoringReport_xml).
routes(+2 ~30 =967): of the 999 incoming, 2 were new routes, 30 changed, 967 weren't touched at all (content unchanged).
drivers / vehicles (+0 ~0): the driver and vehicle dictionaries had no changes in this batch.
sync = 482 ms — this is lookup-dictionary sync (DictionarySyncService.SyncFromOrdersAsync): walk all 999 orders, reconcile drivers / vehicles / shipping points / business types / delivery statuses against REDB lists, upsert any new list_items if needed. This is not schema sync.
query = 139 ms — one SELECT to REDB: WhereRedb(o => codes.Contains(o.ValueString)) — pulls all 999 existing routes by their codes in a single query.
save = 154 ms — SaveAsync for 32 objects (2 created + 30 updated). The 967 unchanged ones never get here.
Environment: 2 cores, default shared_buffers, no pg_prewarm, no framework-level cache.

Important caveat: schema sync (SyncSchemeAsync<T> — the bit that compares _structure_hash and refreshes _scheme_metadata_cache) is a separate step that runs once at process startup, before any orders flow. It's not in this log line at all. The "sync" number here is application-level dictionary reconciliation, not schema reconciliation.

Let's break down what's physically happening behind each number.

Query: 139 ms for 999 objects in one call

The most striking number in the log. This isn't 999 separate LoadAsync calls — it's one facet query:

var existing = await redb.Query<TransportationRoute>()
    .WhereRedb(o => codes.Contains(o.ValueString!))
    .ToListAsync();

It translates roughly to:

-- find all routes whose _value_string is in the list of 999 codes
SELECT o.* FROM _objects o
WHERE o._id_scheme = @routeSchemeId
  AND o._value_string = ANY(@codes);

After that, one batched query for _values of all matched objects via IX__values__object_array_null (covering INCLUDE) — Index Only Scan, no heap access. Output: 999 fully hydrated RedbObject<TransportationRoute> instances with all ~50 properties each, including ListItem references to dictionaries.

139 ms / 999 objects = 0.14 ms per object on paper, but that math is misleading — the real cost is two SQL round trips (one for _objects, one for _values) plus C# hydration.

No N+1. No Includes. ListItem references resolve through RefDataCache in memory, so Vehicle, Driver, ShippingPoint get filled without extra SQL.

Save: 154 ms for 32 changed objects

Two things matter here, and both are critical.

First — application-level change tracking. Before SaveAsync, every existing route runs through ComputeHash():

var hashBefore = obj.ComputeHash();
EnrichRouteFromOrder(obj.Props, routeProps);
if (obj.ComputeHash() != hashBefore)
{
    toSave.Add(obj);  // data really changed — queue for save
    updatedCount++;
}
else
{
    skippedCount++;   // byte-identical — don't touch the database
}

Of the 999 incoming orders, 967 are skipped right here. They never hit _objects/_values, never generate a single DML statement. This isn't a REDB-engine optimization — it's an application-code pattern, but REDB supports it cheaply via ComputeHash() over Props.

Second — bulk save in a single transaction. The remaining 32 objects go in one call:

await redb.SaveAsync(toSave);   // toSave: List<IRedbObject>, 32 items

Here's what happens inside. _objects gets normalized in a batch first — for all 32 objects, one INSERT/UPDATE pass (new rows go via COPY/UNNEST-INSERT, modified rows via batched UPDATE). Then _values: for each modified object the value rows are recreated, and again not row-by-row but in one bulk call through Postgres COPY protocol. All in a single transaction — _objects and _values commit atomically.

COPY matters. It's a streaming binary protocol that ingests N rows without a per-row round trip — the driver writes a continuous byte stream into the socket. For 32 objects × ~50 properties = ~1600 value rows, that's one COPY operation instead of 1600 INSERTs. Btree indexes get their batch and update amortized.

So 154 ms for 32 objects (~4.8 ms per object on full overwrite) isn't "the engine is very fast" — it's "the engine doesn't do unnecessary work." Bulk where it can bulk; early skip where data didn't change.

Sync: 482 ms — what it really is

482 ms is the heaviest line in the log, and it's also the most commonly misread one. It's not schema sync — schema sync already ran at Worker startup, before any orders showed up. The 482 ms is DictionarySyncService.SyncFromOrdersAsync:

Five parallel dictionary loads from REDB: Drivers, Vehicles, ShippingPoints, BusinessTypes, DeliveryStatuses — via redb.ListProvider.GetListByNameWithItemsAsync(...). Pulls _lists plus all their _list_items.
Walk over 999 orders: each DriverId, CarId, ShippingPoint, BusinessTypes is checked against existing list items. If new, an upsert is queued.
If dictionaries changed — refresh RefDataCache (a static in-memory cache so the Order → RouteProps mapping doesn't re-query the DB).

This batch had zero deltas on drivers and vehicles (+0 ~0), but 482 ms still went into proving they didn't change — that's 999 rows being checked against thousands of existing list items across multiple dictionaries.

This is application-level sync. It belongs to TSUM's logistics process, not REDB's engine. But it makes a useful point: even when "discovering nothing needs to change" costs more than the actual save (482 ms sync vs 154 ms save), the whole tick still fits in under a second for a thousand orders.

Schema sync is a separate story. Cold start of the Worker — tens to hundreds of milliseconds, one-off (32 schemes, hash comparison). Hot restart with no model changes — single-digit milliseconds. It happens before the first [TSUM] log line and isn't counted in the per-tick budget.

Coming back to the 9.7M-row objection

The original objection was "how can this be fast at that table size." The answer: the engine never scans _values whole. Any query starts from one of these four anchors:

PK (LoadAsync by ID) — O(log n) on the btree.
_id_scheme + _value_string for facets through a RedbPrimitive column, like the TSUM case above — Index Only Scan on IX__objects__value_string.
_id_structure (regular facet search) — discards ~99.75% of rows immediately. With 401 properties, the average _id_structure covers ~24K of the 9.7M total.
_id_object (LoadAsync — all values for an object) — discards even more aggressively, since an object has tens of values, not thousands.

Table size in rows only affects the index size in pages. Postgres btree fan-out is in the hundreds, so 9.7M rows is a 4–5 level deep tree. Search is logarithmic, not linear.

"You don't always need everything you've got": pruning indexes after stabilization

redbPostgre.sql carries the full spectrum of indexes for every REDB scenario: facet search, trees, collections, GIN full-text, partial indexes for NOT NULL, indexes for recursive permission CTEs. That's right for a library: you don't know up front which workload profile a given app will have.

But in your specific app, some of those indexes may never light up. That's fine. TSUM, for instance, never calls WhereHasDescendant because its domain hierarchies are flat — so IX__objects__parent_id_descendant_lookup sits in pages but no scan ever goes through it.

After the app's been in production for two to four weeks under stable load, pull the index stats and trim aggressively:

SELECT schemaname, relname, indexrelname,
       idx_scan,
       pg_size_pretty(pg_relation_size(indexrelid)) AS sz
FROM pg_stat_user_indexes
WHERE idx_scan = 0
  AND pg_relation_size(indexrelid) > 10*1024*1024  -- only indexes > 10 MB
ORDER BY pg_relation_size(indexrelid) DESC;

On TSUM, this query surfaces about 4423 MB of indexes with idx_scan = 0. That doesn't mean those indexes are bad. It means nobody's hitting those query paths in this workload profile.

Working with the result:

Don't drop everything immediately. First, walk the list: which indexes serve scenarios that "haven't fired yet" (quarterly reports, year-end reconciliations, big imports)? Leave those alone — re-creation later costs more than the disk you'd save now.
The rest are candidates for DROP INDEX CONCURRENTLY. It's safe — no table lock — and you can always restore the index with the same CREATE INDEX CONCURRENTLY, since the DDL knows what shape it should have.
After dropping, watch for two to four more weeks. If no unexpectedly slow queries show up in logs, the call was right. If something regresses, restore.

This is a standard PostgreSQL practice, not a REDB-specific trick. But it works cleaner in REDB because the index set is designed once and frozen in DDL. Pruning is one targeted decision in one place — not a hunt through three years of accumulated migrations across business tables.

The other direction works too. If you spot a single facet query that's hot enough to warrant an extra push, nothing stops you from adding a local index just for it:

-- e.g., "find routes for a specific driver in the last 7 days"
CREATE INDEX IX_my_app__route_by_driver
ON _values (_id_structure, _ListItem, _id_object)
WHERE _id_structure = <driver_field_id>;

That kind of index is application-side optimization. It lives in your app's migration, not in the REDB core. And the same pg_stat_user_indexes audit applies to it after a few weeks.

What's deliberately not in the DDL, and why

A second-level skeptic asks the next question: "Why no hash index on _String? Why no BRIN on _date_create? Why no expression index on LOWER(_String)?"

Hash indexes. Historically weaker than btree on most metrics in Postgres, and they don't support partial conditions. Almost every REDB index is partial — so hash is structurally a non-fit, not a coin-flip choice.

BRIN on _date_create. A reasonable candidate on big archival tables, but redundant for the current REDB profile. IX__objects__scheme_date_create (DESC, _id) already serves the exact scenario BRIN would compete with. BRIN would only win in a cold-storage case (>10M rows on a single scheme) — that's a separate "archival classes" phase, and the current core DDL doesn't address it yet.

Expression indexes (LOWER(_String), _DateTimeOffset::date, etc.). Deliberately omitted. This is an application choice: case-insensitive search on a specific text field, aggregation by day/month — these are options that belong in the app's migration, not the engine. GIN with pg_trgm already provides case-insensitive substring search via ILIKE, and that covers most needs.

Bloom, BRIN-multi, GIN on jsonb. All candidates for narrow scenarios. If you have one very specific query that's provably hot and provably not covered by the standard set — you add a local index for it in a separate migration. Without touching redbPostgre.sql.

The principle is general: the core DDL covers 95% of scenarios, the remaining 5% lives in the application layer. That's the opposite of the EF approach, where the DDL belongs to the application from day one and every index is part of its migration history.

MSSQL: nearly the same picture

While we're in DDL territory, worth saying clearly: this post isn't Postgres-specific. redb.MSSql/sql/redbMSSQL.sql carries a mirror set of indexes, and the architectural trick — "indexes don't grow with class count" — works identically on both engines.

Ports cleanly:

All three partial-unique indexes on _values (in MSSQL — filtered indexes with WHERE, different syntax, same semantics).
Composite indexes for facet search (IX__values__structure_object_lookup exists in both DDLs with an identical key shape).
INCLUDE covering indexes — natively supported in MSSQL since 2005, port one-to-one.
Object-tree indexes (IX__objects__scheme_parent, IX__objects__parent_id_descendant_lookup) — unchanged.
Partial / filtered indexes for RedbPrimitive<T> — unchanged.

Differs:

GIN + pg_trgm for substring search on _String. The MSSQL counterpart is full-text search or a filtered index over a computed column. redbMSSQL.sql takes a different path (LIKE over a regular btree with a length-bound partial).
NULLS NOT DISTINCT in Postgres 15+ — MSSQL spells it differently (UNIQUE + filtered WHERE NOT NULL).
ON DELETE CASCADE from _structures to _values works directly in Postgres but not in MSSQL because of multiple cascade paths — replaced with an INSTEAD OF DELETE trigger. The DELETE plan is slightly different in MSSQL but the indexes are the same.
Per-type filtered indexes are spelled out more explicitly in MSSQL (IX__values__Long_filter, IX__values__Guid_filter, ...) — in the Postgres DDL they're commented out as "covered by composite." That's a strategy difference: the MSSQL optimizer is a bit more partial to narrow filtered indexes per type.

But the main point — architectural invariance is preserved. Same 2+2+3+infrastructure layout, same facet schema, same fact that the index set doesn't grow when you add a class. To a developer writing C# models, the difference between Postgres and MSSQL is invisible.

TSUM as the proof case

Bringing the numbers from the top of the post into one place.

What REDB serves in TSUM:

32 classes in tsum.Domain (from TransportationRoute to UserFilterPreference),
401 properties across those classes,
227,896 objects at the time these metrics were captured,
9,773,174 rows in _values.

This whole schema lands not in 13 tables per entity, but in 2 data tables (_objects + _values) + 2 lookup tables (_lists + _list_items) + 3 RTTI tables (_types + _schemes + _structures). The remaining six are infrastructure — permissions, users, roles, links, dependencies, functions, soft-delete, metadata cache — invariant of business class count. The full index set is the same redbPostgre.sql you'd ship for a five-class project. In a classical EF layout, those 32 classes with their lookups and snapshots would expand to roughly 60–80 tables and 200+ indexes, with a migration history accumulating across the project's lifetime.

Production metrics for a typical order-processing tick:

999 orders in one XML batch from SAP, processed in 991 ms total:
- sync = 482 ms — reconciling lookup dictionaries (Drivers, Vehicles, ShippingPoints, BusinessTypes, DeliveryStatuses) against REDB lists,
- query = 139 ms — one SELECT loading all 999 existing routes by their codes,
- save = 154 ms — SaveAsync for 32 changed objects (2 created + 30 updated). The other 967 are short-circuited by ComputeHash() before they reach the database.
Infrastructure — 2 cores, stock PostgreSQL settings (no shared_buffers tuning, no pg_prewarm, no bumped work_mem).
No REDB-framework-level cache — every Query<T>() round-trips to the database.

This isn't a hand-picked benchmark — it's a real production tick where a developer writes ordinary C# models with a [RedbScheme] attribute and the logistics process just runs. Bulk on the read (one SELECT for 999 objects), bulk on the write (_objects and _values together in one transaction over the COPY protocol), early skip where data didn't change.

The technical takeaway: REDB hits these numbers not through magic, but because the engine doesn't do unnecessary work. The index plan is baked into the storage schema; bulk runs where bulk applies; application-level change tracking saves the most expensive thing — DML for changes that aren't there.

Wrap-up and what's coming next

Short summary. REDB ships one index set in DDL — about 50 indexes for the entire system. That set serves any business schema: 32 classes, 100 classes, 500 classes — same indexes. That's the inverse of the EF approach, where indexes multiply with tables and slowly become technical debt that needs periodic pruning.

Operational pattern — once your application stabilizes, run pg_stat_user_indexes, find the idx_scan = 0 candidates, and prune carefully (with DROP INDEX CONCURRENTLY for safe rollback). Add your own local indexes for hot application-specific queries — in a separate migration, leaving the engine DDL alone.

MSSQL is nearly the same picture. Minor differences in text indexing and per-type filtered indexes, but architectural invariance carries over.

Coming up in the series:

Part 2 — Code-first schemes: how SyncSchemeAsync<T> turns a C# class into rows in _schemes + _structures, what _structure_hash is, how automatic onboarding works when you add a new property.
Part 3 — CRUD internals: SaveAsync and LoadAsync from inside, change tracking via TreeDiff, COPY-protocol bulk insert, lazy loading.
Part 4 — LINQ to SQL: how Where(x => x.Salary > 80000) becomes CASE WHEN _id_structure = X THEN _Long END > 80000, how OrderBy and window functions work.
Part 5 — Object trees: LoadTreeAsync, GetDescendantsAsync, WhereHasAncestor, recursive CTEs.
Part 6 — Window functions: Win.RowNumber(), Win.Rank(), PartitionBy/OrderBy over REDB objects.

The deep C# dive is parts 3–5. In the storage layer, one topic remains — schema migrations — and that's where the next post picks up.

Earlier in the series (on dev.to)

An EF Core alternative for .NET apps with complex object graphs — full LINQ, no migrations, no DbContext — the wide-angle intro to RedBase: LINQ surface, production story, generated SQL.
REDB inside, part 1 — the 13 tables the whole engine runs on (with the actual SQL, and why it's not EAV) — the schema walkthrough this post builds on.
redb.Route 3.0.1 — flat DSL navigation, CRTP refactor, and a silent null fix — separate cycle on the ESB framework that sits on top of redb.

REDB inside, part 1 — the 13 tables the whole engine runs on (with the actual SQL, and why it's not EAV)

rinat kozin — Thu, 04 Jun 2026 18:49:10 +0000

A couple of weeks ago I published the redb.Core intro post — what RedBase is at the API level, why I wrote it, what production looks like, the LINQ surface, what generated SQL looks like for nested dictionary lookups. If you haven't read it, start there — it's the wide-angle shot.

This post starts a new series — "REDB inside" — that drills down into the engine. One article per layer:

Part 1 (this post) — the database schema. 13 tables, what each one does, why the design is what it is, and the SQL you'd run to dump any object flat.
Part 2 — code-first schemes. How SyncSchemeAsync<T> walks a C# class and turns it into rows in _schemes + _structures, the _structure_hash mechanism, automatic onboarding via InitializeAsync.
Part 3 — CRUD internals. SaveAsync, LoadAsync, the TreeDiff change-tracking algorithm, COPY-protocol bulk insert, lazy loading.
Part 4 — LINQ-to-SQL. How Where(x => x.Salary > 80000) becomes WHERE _id_structure = X AND _Long > 80000, the pivot CTE patterns, dialect differences (Postgres array_agg FILTER vs MSSQL MAX CASE WHEN).
Part 5 — trees. LoadTreeAsync, GetDescendantsAsync, WhereHasAncestor, closure-table vs recursive CTE.
Part 6 — window functions. Win.RowNumber(), Win.Rank(), PartitionBy/OrderBy over REDB objects.

Each one stands alone. You don't need to read them in order — but if you want to understand why anything in parts 2-6 works the way it does, you need this post. Everything else is built on the 13 tables.

The whole RedBase engine runs on 13 tables. No JSON blob hiding the schema, no NVARCHAR(MAX) catch-all column — every C# type lands in its own typed column. Let me show you how that works, and why this isn't classical EAV even though it kind of looks like it at first glance.

"Wait, isn't this just EAV?"

It's the most common reaction I get, and it deserves a real answer before we look at any DDL.

Classical EAV (Entity–Attribute–Value) looks like this:

object_id | attribute_name | value
----------|----------------|---------
42        | "FirstName"    | "Alice"
42        | "Age"          | "28"
42        | "Salary"       | "85000"

Everything in one table. Types erased. Attribute names are strings. Any non-trivial query becomes a self-join or a giant PIVOT. The filter "employees earning over $80k" turns into:

SELECT object_id
FROM   attributes
WHERE  attribute_name = 'Salary'
  AND  value::numeric > 80000;   -- runtime cast, no usable index

Add three more conditions and you're looking at three self-joins on the same table. Explain plans get embarrassing.

REDB doesn't do that. Here's what _values actually looks like:

CREATE TABLE _values (
    _id              bigint NOT NULL,
    _id_structure    bigint NOT NULL,   -- FK → _structures (which field this is)
    _id_object       bigint NOT NULL,   -- FK → _objects
    -- typed value columns, exactly one is non-NULL per row:
    _String          text NULL,
    _Long            bigint NULL,
    _Guid            uuid NULL,
    _Double          float NULL,
    _DateTimeOffset  timestamptz NULL,
    _Boolean         boolean NULL,
    _ByteArray       bytea NULL,
    _Numeric         numeric(38,18) NULL,
    _ListItem        bigint NULL,       -- FK → _list_items
    _Object          bigint NULL,       -- FK → _objects (cross-object reference)
    -- relational collection storage:
    _array_parent_id bigint NULL,       -- FK → _values (parent element)
    _array_index     text NULL          -- '0','1','2' for arrays, key for dictionaries
);

The field identity is a foreign key (_id_structure), not a string. The value lives in a typed column chosen at write time based on the field's declared C# type. Think of it as runtime type information (RTTI) persisted into the schema: the engine always knows what type each field is, because that's recorded once in _structures._id_type and reused for every value of that field.

Reading values back is one CASE expression dispatched on type, not a self-join:

CASE c.db_type
  WHEN 'String'  THEN v._String
  WHEN 'Long'    THEN v._Long::text
  WHEN 'Guid'    THEN v._Guid::text
  ...
END

The practical differences:

	Classical EAV	REDB `_values`
Field identity	string in `attribute_name`	FK → `_structures` → `_types`
Where the value lives	one `text`/`varchar(max)` column	typed column per C# type
Filter `Salary > 80000`	`WHERE attribute_name='Salary' AND value::numeric > 80000`	`WHERE _id_structure = $1 AND _Long > 80000`
Index on the value	string index + runtime cast	partial B-tree index on the typed column
Arrays/dictionaries	separate table or JSON blob	`_array_parent_id` + `_array_index` in the same row
Schema metadata	implicit in attribute names	first-class rows in `_schemes`/`_structures`/`_types`, denormalized into a metadata cache

So yes, the row shape rhymes with EAV — but the type system and the indexing story are completely different. That's why I've been pushing back on the EAV label.

The 13 tables, at a glance

_types          — type catalog (~37 system rows)
_schemes        — schemes (C# classes mapped to DB rows)
_structures     — fields of schemes (with nesting and collection metadata)
_objects        — objects (data rows, tree-shaped via self-FK)
_values         — field values (typed columns + relational collections)
_lists          — pick-list/dictionary catalog
_list_items     — pick-list entries
_users          — users (system IDs −1, 0, 1)
_roles          — roles
_users_roles    — M2M user ↔ role
_permissions    — permissions on objects (inherited along the tree)
_links          — M2M relations between objects
_functions      — stored expressions attached to schemes
_dependencies   — cross-scheme dependencies
─────────────────────────────────────────────
_scheme_metadata_cache   — denormalized cache of structures × types
_migrations              — history of props-schema migrations

The last two live in their own SQL files but matter just as much in practice. Let's walk through them layer by layer.

Layer 1 — the type catalog: `_types`

CREATE TABLE _types (
    _id      bigint NOT NULL PRIMARY KEY,
    _name    text NOT NULL UNIQUE,
    _db_type text NULL,   -- which _values column to use: 'Long', 'String', 'Guid', ...
    _type    text NULL    -- C# type name: 'long', 'string', 'Guid', ...
);

System type IDs are negative constants near long.MinValue. A small sample:

`_id`	`_name`	`_db_type`	C# type
-9223372036854775709	Boolean	Boolean	`bool`
-9223372036854775708	DateTime	DateTimeOffset	`DateTime`
-9223372036854775704	Long	Long	`long`
-9223372036854775700	String	String	`string`
-9223372036854775695	Decimal	Numeric	`decimal`
-9223372036854775675	Class	—	nested class (marker only)
-9223372036854775668	Array	—	`T[]` / `List<T>` (marker only)
-9223372036854775667	Dictionary	—	`Dictionary<K,V>` (marker only)

The scary-looking numbers are just constants picked far from anything a user-generated key could ever hit (user IDs start at 1_000_000 via a global_identity sequence). Class, Array, and Dictionary have no column of their own in _values — they're marker types; the actual leaves live in child rows.

There are ~37 built-in types total. Numeric ones (Int, Short, Byte, Float) physically store as Long/Double. Strings include semantic variants (Email, Url, Phone) that all use _String. Then DateOnly/TimeOnly/TimeSpan, geo (Latitude/Longitude), file metadata (FilePath/MimeType), Enum/EnumInt, and collection markers (Array/Dictionary/JsonDocument/XDocument).

Layer 2 — schemes and fields: `_schemes` + `_structures`

CREATE TABLE _schemes (
    _id             bigint NOT NULL,
    _id_parent      bigint NULL,          -- nesting (namespaces)
    _name           text NOT NULL UNIQUE, -- e.g. 'MyApp.Models.EmployeeProps'
    _alias          text NULL,
    _structure_hash uuid NULL,            -- field hash for fast change detection
    _type           bigint NOT NULL       -- FK → _types (Class by default)
);

CREATE TABLE _structures (
    _id              bigint NOT NULL,
    _id_parent       bigint NULL,     -- nested props class
    _id_scheme       bigint NOT NULL, -- FK → _schemes
    _id_type         bigint NOT NULL, -- FK → _types
    _id_list         bigint NULL,     -- FK → _lists (for ListItem fields)
    _name            text NOT NULL,   -- C# property name
    _alias           text NULL,
    _order           bigint NULL,
    _collection_type bigint NULL,     -- NULL=scalar, Array_ID or Dictionary_ID
    _key_type        bigint NULL,     -- key type for Dictionary<K,V>
    _readonly        boolean NULL,
    _allow_not_null  boolean NULL,
    _is_compress     boolean NULL,
    _store_null      boolean NULL,
    _default_value   bytea NULL
);

When you write:

[RedbScheme("Employee")]
public class EmployeeProps
{
    public string FirstName            { get; set; } = "";
    public int    Age                  { get; set; }
    public decimal Salary              { get; set; }
    public string[]? Skills            { get; set; }
    public Address? HomeAddress        { get; set; }   // nested class
}

…and await redb.SyncSchemeAsync<EmployeeProps>() fires for the first time, the engine:

Inserts a row into _schemes with _name = "MyApp.EmployeeProps".
Inserts one _structures row per public property.
For Skills: sets _collection_type = Array_ID.
For HomeAddress: sets _id_type = Class_ID and recursively creates child _structures rows whose _id_parent points back at the parent structure.

Then it computes a hash over all those structures and writes it to _schemes._structure_hash. Next time you call sync, comparing one UUID tells the engine whether anything actually changed — no row-by-row diff needed.

There's a DB-level trigger that validates field names: no system-reserved (_id, _name, _date_create), no C# keywords (class, int, string), no leading digits. If you accidentally try to name a property int, the INSERT throws before the bad row ever lands.

Layer 3 — objects: `_objects`

CREATE TABLE _objects (
    _id             bigint NOT NULL,
    _id_parent      bigint NULL,          -- tree parent (self-FK)
    _id_scheme      bigint NOT NULL,      -- FK → _schemes
    _id_owner       bigint NOT NULL,      -- FK → _users
    _id_who_change  bigint NOT NULL,      -- FK → _users
    _date_create    timestamptz NOT NULL,
    _date_modify    timestamptz NOT NULL,
    _date_begin     timestamptz NULL,
    _date_complete  timestamptz NULL,
    _key            bigint NULL,
    _name           text NULL,
    _note           text NULL,
    _hash           uuid NULL,
    -- value columns for RedbPrimitive<T>:
    _value_long     bigint NULL,
    _value_string   text NULL,
    _value_guid     uuid NULL,
    _value_bool     boolean NULL,
    _value_double   float NULL,
    _value_numeric  numeric(38,18) NULL,
    _value_datetime timestamptz NULL,
    _value_bytes    bytea NULL
);

Three things worth pointing out:

The tree via _id_parent is ON DELETE CASCADE. Drop a root, the whole subtree goes with it. Depth is unbounded. This is the primary organizational structure in REDB: sections, categories, folders, org charts, project trees — they're all just _objects rows pointing at a parent.

The _value_* columns are for RedbPrimitive<T>. When an object is conceptually a single primitive (e.g. RedbObject<long> for a counter, RedbObject<string> for a token), there's no need to spin up _values rows — the value rides in the object row itself. Eight columns, one per _db_type.

Soft delete is a scheme called @@__deleted (_id = -10). mark_for_deletion() walks the subtree via recursive CTE and atomically reparents everything under a trash container with _id_scheme = -10. Actual physical deletion is a separate, batched purge_trash(). This means you can offer "undelete" cheaply, and your data lake/CDC tools never see a destructive delete on the hot path.

Layer 4 — the values: `_values`

This is the table that earns its keep. Everything else exists to make this one fast and consistent.

The DDL was up top. The interesting part is how collections fit into a flat row layout without a side table.

Scalar field

Age = 28 produces exactly one row:

_id_structure=struct_Age   _id_object=42   _Long=28   _array_parent_id=NULL   _array_index=NULL

Array of primitives

Skills = ["C#", "SQL", "React"] produces a marker row plus one row per element:

-- marker: "the array property exists" (without it, the property is NULL, not [])
_id=100   _id_structure=struct_Skills   _id_object=42   _array_index=NULL   _array_parent_id=NULL

-- elements; _array_parent_id points at the marker; _array_index is the position
_id=101   _id_structure=struct_Skills   _id_object=42   _String="C#"     _array_index='0'   _array_parent_id=100
_id=102   _id_structure=struct_Skills   _id_object=42   _String="SQL"    _array_index='1'   _array_parent_id=100
_id=103   _id_structure=struct_Skills   _id_object=42   _String="React"  _array_index='2'   _array_parent_id=100

That marker row matters: it's how the engine tells null (no marker, no elements) apart from [] (marker present, zero children). The same shape works for empty dictionaries too.

Dictionary

PhoneDir = { "home": "+7 999…", "work": "+7 495…" }:

-- marker
_id=200   _id_structure=struct_PhoneDir   _id_object=42   _array_index=NULL   _array_parent_id=NULL

-- entries; _array_index holds the dictionary key (as text)
_id=201   _id_structure=struct_PhoneDir   _id_object=42   _String="+7 999..."   _array_index='home'   _array_parent_id=200
_id=202   _id_structure=struct_PhoneDir   _id_object=42   _String="+7 495..."   _array_index='work'   _array_parent_id=200

_array_index is text precisely so dictionaries with string keys work without a separate table. Numeric dictionaries store keys as their string representation.

Nested class

HomeAddress.City = "Moscow" works the same way. The _structures rows for Address.City, Address.Street, etc. carry an _id_parent pointing at the parent structure (HomeAddress). The _values rows for those leaves carry an _array_parent_id pointing at the marker row for HomeAddress on this particular object.

Three unique indexes keep all of this consistent

CREATE UNIQUE INDEX UIX__values__structure_object
    ON _values (_id_structure, _id_object)
    WHERE _array_index IS NULL AND _array_parent_id IS NULL;

CREATE UNIQUE INDEX UIX__values__structure_object_parent
    ON _values (_id_structure, _id_object, _array_parent_id)
    WHERE _array_index IS NULL AND _array_parent_id IS NOT NULL;

CREATE UNIQUE INDEX UIX__values__structure_object_array_index
    ON _values (_id_structure, _id_object, _array_parent_id, _array_index)
    WHERE _array_index IS NOT NULL;

These three together guarantee: (a) at most one scalar/marker row per (structure, object), (b) at most one nested-class marker per (structure, object, parent), and (c) at most one element per (structure, object, parent, index). Try to insert a duplicate array element and the DB rejects it before any logic bug can corrupt the shape.

Layer 5 — permissions: `_permissions`

CREATE TABLE _permissions (
    _id      bigint NOT NULL,
    _id_role bigint NULL,   -- XOR with _id_user (CHECK constraint)
    _id_user bigint NULL,
    _id_ref  bigint NOT NULL,  -- 0 = global, otherwise FK → _objects
    _select  boolean NULL,
    _insert  boolean NULL,
    _update  boolean NULL,
    _delete  boolean NULL
);

Permissions inherit along the object tree. A recursive CTE walks upwards from the target object up to 50 levels looking for the nearest ancestor that has an explicit permission row. _id_ref = 0 is the global fallback ("can this principal touch anything at all?"). Resolution priority is: user > role, specific object > global.

There's an automatic trigger that, when a child object is created without its own permission row, copies down the resolved permission from the nearest ancestor. The point isn't to materialize every permission — it's to keep the recursive CTE short. After a few months of activity the depth the resolver has to climb stays roughly constant.

`_scheme_metadata_cache` — why a cache table

Every query needs to know: "for an object with _id_scheme = X, which _structures rows exist, and what's the type of each?" That's a JOIN through _structures → _types that would otherwise fire on every single read.

So that JOIN is denormalized into a separate table that gets refreshed when the scheme changes:

CREATE TABLE _scheme_metadata_cache (
    _scheme_id           bigint NOT NULL,
    _structure_id        bigint NOT NULL,
    _parent_structure_id bigint,
    _name                text NOT NULL,
    type_name            text NOT NULL,   -- 'Long', 'String', 'Guid', ...
    db_type              text NOT NULL,   -- 'Long', 'String', 'Guid', ...
    type_semantic        text NOT NULL,   -- 'Object', '_RObject', 'Array', ...
    _collection_type     bigint,
    collection_type_name text,
    _key_type            bigint,
    key_type_name        text
    -- ... all the other _structures attributes inlined
);

A trigger on _schemes._structure_hash invalidates the cache for that scheme; on the next read, sync_metadata_cache_for_scheme(scheme_id) rebuilds it lazily. The big build_hierarchical_properties_optimized() function — the one that materializes an object's full property tree into JSON — never JOINs _structures or _types directly. It reads from this cache, and only from this cache.

Two SQL queries: dump any object flat

Here are two queries that show exactly what's in the box for a given object. The first uses raw JOINs (use this for ad-hoc debugging in DataGrip/SSMS). The second uses _scheme_metadata_cache — what the engine actually runs at scale.

Query 1 — flat pivot, no cache

-- PostgreSQL
SELECT
    s._name                                          AS scheme_name,
    st._name                                         AS field_name,
    t._name                                          AS type_name,
    CASE t._db_type
        WHEN 'String'         THEN v._String
        WHEN 'Long'           THEN v._Long::text
        WHEN 'Guid'           THEN v._Guid::text
        WHEN 'Double'         THEN v._Double::text
        WHEN 'Boolean'        THEN v._Boolean::text
        WHEN 'DateTimeOffset' THEN v._DateTimeOffset::text
        WHEN 'Numeric'        THEN v._Numeric::text
        WHEN 'ListItem'       THEN v._ListItem::text
        WHEN 'Object'         THEN v._Object::text
        WHEN 'ByteArray'      THEN encode(v._ByteArray, 'base64')
        ELSE                       NULL
    END                                              AS value_text,
    CASE
        WHEN v._array_parent_id IS NULL
         AND v._array_index     IS NULL
         AND t._name IN ('Array','Dictionary','Class')  THEN 'collection_marker'
        WHEN v._array_parent_id IS NULL
         AND v._array_index     IS NULL                 THEN 'scalar'
        WHEN v._array_parent_id IS NOT NULL             THEN 'element[' || v._array_index || ']'
        ELSE                                                 'scalar'
    END                                              AS slot,
    v._array_index,
    v._array_parent_id
FROM _values      v
JOIN _structures  st ON st._id = v._id_structure
JOIN _schemes     s  ON s._id  = st._id_scheme
JOIN _types       t  ON t._id  = st._id_type
WHERE v._id_object = :object_id
ORDER BY st._order NULLS LAST, v._array_index NULLS FIRST;

-- MS SQL Server
SELECT
    s._name                                          AS scheme_name,
    st._name                                         AS field_name,
    t._name                                          AS type_name,
    CASE t._db_type
        WHEN 'String'         THEN v._String
        WHEN 'Long'           THEN CAST(v._Long AS nvarchar(MAX))
        WHEN 'Guid'           THEN CAST(v._Guid AS nvarchar(MAX))
        WHEN 'Double'         THEN CAST(v._Double AS nvarchar(MAX))
        WHEN 'Boolean'        THEN CASE v._Boolean WHEN 1 THEN 'true' WHEN 0 THEN 'false' END
        WHEN 'DateTimeOffset' THEN CAST(v._DateTimeOffset AS nvarchar(MAX))
        WHEN 'Numeric'        THEN CAST(v._Numeric AS nvarchar(MAX))
        WHEN 'ListItem'       THEN CAST(v._ListItem AS nvarchar(MAX))
        WHEN 'Object'         THEN CAST(v._Object AS nvarchar(MAX))
        WHEN 'ByteArray'      THEN N'<binary, base64 in app code>'
        ELSE                       NULL
    END                                              AS value_text,
    CASE
        WHEN v._array_parent_id IS NULL AND v._array_index IS NULL THEN 'scalar'
        WHEN v._array_parent_id IS NOT NULL                        THEN 'element[' + ISNULL(v._array_index,'') + ']'
        ELSE                                                            'scalar'
    END                                              AS slot,
    v._array_index,
    v._array_parent_id
FROM [dbo].[_values]      v
JOIN [dbo].[_structures]  st ON st._id = v._id_structure
JOIN [dbo].[_schemes]     s  ON s._id  = st._id_scheme
JOIN [dbo].[_types]       t  ON t._id  = st._id_type
WHERE v._id_object = @object_id
ORDER BY st._order, v._array_index;

This is a diagnostic query — paste it into psql/DataGrip/SSMS, plug in any object ID, and you see exactly what's stored: which fields, which slot (scalar / collection marker / array element), which type. The marker rows for arrays show up too, which is exactly what you want when you're hunting down a null vs [] regression.

Query 2 — same result via `_scheme_metadata_cache`

-- PostgreSQL (via _scheme_metadata_cache)
SELECT
    c._scheme_id                                      AS scheme_id,
    c._name                                           AS field_name,
    c.type_name                                       AS type_name,
    c.db_type                                         AS db_type,
    c.collection_type_name                            AS collection_type,
    CASE c.db_type
        WHEN 'String'         THEN v._String
        WHEN 'Long'           THEN v._Long::text
        WHEN 'Guid'           THEN v._Guid::text
        WHEN 'Double'         THEN v._Double::text
        WHEN 'Boolean'        THEN v._Boolean::text
        WHEN 'DateTimeOffset' THEN v._DateTimeOffset::text
        WHEN 'Numeric'        THEN v._Numeric::text
        WHEN 'ListItem'       THEN v._ListItem::text
        WHEN 'Object'         THEN v._Object::text
        WHEN 'ByteArray'      THEN encode(v._ByteArray, 'base64')
        ELSE                       NULL
    END                                               AS value_text,
    v._array_index,
    v._array_parent_id,
    c._order
FROM _values                v
JOIN _scheme_metadata_cache c ON c._structure_id = v._id_structure
WHERE v._id_object = :object_id
ORDER BY c._order NULLS LAST, v._array_index NULLS FIRST;

-- MS SQL Server (via _scheme_metadata_cache)
SELECT
    c.[_scheme_id]                                    AS scheme_id,
    c.[_name]                                         AS field_name,
    c.[type_name]                                     AS type_name,
    c.[db_type]                                       AS db_type,
    c.[collection_type_name]                          AS collection_type,
    CASE c.[db_type]
        WHEN 'String'         THEN v._String
        WHEN 'Long'           THEN CAST(v._Long AS nvarchar(MAX))
        WHEN 'Guid'           THEN CAST(v._Guid AS nvarchar(MAX))
        WHEN 'Double'         THEN CAST(v._Double AS nvarchar(MAX))
        WHEN 'Boolean'        THEN CASE v._Boolean WHEN 1 THEN 'true' WHEN 0 THEN 'false' END
        WHEN 'DateTimeOffset' THEN CAST(v._DateTimeOffset AS nvarchar(MAX))
        WHEN 'Numeric'        THEN CAST(v._Numeric AS nvarchar(MAX))
        WHEN 'ListItem'       THEN CAST(v._ListItem AS nvarchar(MAX))
        WHEN 'Object'         THEN CAST(v._Object AS nvarchar(MAX))
        WHEN 'ByteArray'      THEN N'<binary>'
        ELSE                       NULL
    END                                               AS value_text,
    v._array_index,
    v._array_parent_id,
    c.[_order]
FROM [dbo].[_values]                v
JOIN [dbo].[_scheme_metadata_cache] c ON c.[_structure_id] = v.[_id_structure]
WHERE v.[_id_object] = @object_id
ORDER BY c.[_order], v.[_array_index];

Why the second one is the production query:

Two heavy JOINs (_structures, _types) gone. The cache row carries everything those joins would have produced.
The cache already has a B-tree on _structure_id and a stable _order for ordering — no extra sorts.
The cache is refreshed only when the scheme changes (_structure_hash flips), not on every read. Steady-state queries pay zero cost for it.
build_hierarchical_properties_optimized() goes one step further: it slurps all _values rows for one object into a _values[] array in a single SELECT, then walks the property tree purely in memory using unnest(). Recursion into nested classes and array elements never touches the table again. For deeply nested object graphs this is a big deal — you can materialize a 40-row, 8-level-deep object with two SELECTs total.

How this connects to the C# API

For context — what those tables look like from a SaveAsync/LoadAsync perspective. The full API tour is in the intro post; here's just the mapping back to the tables we just looked at:

[RedbScheme("Employee")]
public class EmployeeProps
{
    public string  FirstName { get; set; } = "";
    public string  LastName  { get; set; } = "";
    public int     Age       { get; set; }
    public decimal Salary    { get; set; }
    public string[]? Skills  { get; set; }
}

// InitializeAsync scans the assembly →
//   - inserts/updates rows in _schemes + _structures for each [RedbScheme]
//   - refreshes _scheme_metadata_cache on changed schemes
await redb.InitializeAsync(typeof(EmployeeProps).Assembly);

// SaveAsync →
//   - one row into _objects
//   - one row per scalar into _values (using the typed column for the C# type)
//   - for Skills: one marker row + one row per element, linked via _array_parent_id
var employee = new RedbObject<EmployeeProps>
{
    name  = "Alice Johnson",
    Props = new EmployeeProps
    {
        FirstName = "Alice",
        LastName  = "Johnson",
        Age       = 28,
        Salary    = 120_000m,
        Skills    = ["C#", "PostgreSQL", "Redis"]  // → 1 marker + 3 element rows
    }
};
long id = await redb.SaveAsync(employee);

// LoadAsync →
//   - SELECT _objects WHERE _id = id
//   - SELECT * FROM _values WHERE _id_object = id  (one shot, into a _values[])
//   - build_hierarchical_properties_optimized() materializes the C# graph
var loaded = await redb.LoadAsync<EmployeeProps>(id);

SaveAsync reads _scheme_metadata_cache to know which column to write each value to, mints IDs from the global_identity sequence, and writes _objects + _values. LoadAsync reads _objects first, then one SELECT pulls every _values row for that object into a memory array, and the recursive materializer never goes back to the database for that load.

A few design choices that aren't obvious

Negative constants for system IDs. User-generated keys come from a sequence starting at 1_000_000. System types, schemes, users live near long.MinValue. The two ranges can never collide. This means _types._id = -10 for the @@__deleted scheme isn't a special-case in any query — it's just a perfectly normal FK that happens to be negative.

_structure_hash on _schemes. Without it, every SyncSchemeAsync<T> call would have to re-read the schema structure and compare row-by-row. With it, comparing one UUID tells you whether anything changed. The cache-invalidation trigger fires only on real changes, so steady-state operation pays nothing.

Marker rows. The trickiest design choice in _values. There's no separate "collections" table — instead, a row with _array_index = NULL AND _array_parent_id = NULL and a collection-typed _id_structure is the marker, and child rows fan out from it via _array_parent_id. This is what makes null vs [] distinguishable, lets dictionaries with string keys work without a side table, and keeps nested-class hierarchies in the same physical structure as flat fields.

_Numeric NUMERIC(38, 18). Deliberate. double for money quietly loses pennies; nobody wants a 0.0000000001-off invoice total in production. The 38/18 precision/scale is more than enough for currency, percentage, weight, even small molar quantities. The cost is storage size (16 bytes vs 8), which on the kind of property volume REDB sees is noise.

Postgres vs MSSQL — the cascade-delete story. On Postgres, _values has ON DELETE CASCADE on its FK to _structures. On MSSQL the same constraint would create multiple cascade paths and SQL Server refuses to compile that. The workaround: an INSTEAD OF DELETE trigger on _structures that manually cascades into _values. Same observable behavior, different machinery. There are a handful of places in the codebase where the dialect abstraction exists specifically to paper over this kind of thing.

Series links

Intro post — An EF Core alternative for .NET apps with complex object graphs (published)
Part 1 (this post) — the 13 tables, RTTI vs EAV, _values, collection storage, _scheme_metadata_cache, two diagnostic queries
Part 2 — code-first schemes: SyncSchemeAsync<T>, _structure_hash, automatic onboarding
Part 3 — CRUD internals: SaveAsync/LoadAsync, TreeDiff change tracking, COPY-protocol bulk insert
Part 4 — LINQ → SQL: pivot CTEs, dialect splits, the OfficeLocations["HQ"].City walkthrough
Part 5 — trees: LoadTreeAsync, WhereHasAncestor, the closure-table vs recursive-CTE story
Part 6 — window functions: Win.RowNumber(), Win.Rank(), PartitionBy/OrderBy over REDB objects

Where to look

github.com/redbase-app — all repos in the ecosystem
github.com/redbase-app/redb — the redb.Core repo
Postgres schema (redbPostgre.sql) — all 13 tables + 40+ indexes + triggers + stored functions in one file
MSSQL schema (redbMSSQL.sql) — same shape, dialect-adjusted
redbase.app — docs and worked examples (EN)

Questions/critique very welcome in the comments — especially if you've built something similar and have war stories about indexing strategies on the values table, that's exactly the discussion I want to have.

redb.Route 3.0.1 — flat DSL navigation, CRTP refactor, and a silent null fix

rinat kozin — Wed, 03 Jun 2026 16:53:16 +0000

Series: redb ecosystem

Before 3.0.1, deep nested scopes required closing in exact reverse order — tedious and easy to get wrong. Three things changed.

Flat `End*()` navigation

A typed closer walks the Parent chain and exits to the right level in one call:

From("direct://demo-cascade-endchoice")
    .Choice()
        .When(e => true)
            .Split(e => new object?[] { 1, 2, 3 })
                .Process(e => { /* per-item work */ })
                .Log("item=${body}")
            .EndChoice()   // walks past Split → When → lands at route root

    .SetHeader("post-cascade", "ok")
    .Log("cascade done");

Universal .End() exits to the nearest scope without naming it:

.Choice()
    .When(e => true)
        .Split(e => new object?[] { "a", "b" })
            .Log(LogLevel.Information)
                .Message("inside")
            .End()   // closes RichLog → returns Split body
        .End()        // closes Split   → returns When body
    .EndChoice()      // closes Choice  → returns route root

Sibling branches open naturally after a closed sub-scope — .When() and .Otherwise() walk up to the enclosing ChoiceDefinition via the Parent chain, so this compiles as-is:

.Choice()
    .When(e => e.In.Body is IEnumerable<string> && e.In.Body is not string)
        .Split(...)
            .Process(...)
        .EndSplit()
        .Log("list branch done [${routeId}]")   // still on the When body, not on Split
    .When(e => e.In.Body is string s && s.Length > 0)   // ← sibling, works after EndSplit
        .Process(e => { /* ... */ })
    .Otherwise()
        .Process(e => { /* fallback */ })
.EndChoice()

Three logging styles, same pipeline step

The updated demo shows all three forms side by side — useful to see the tradeoffs:

// (A) Lambda — arbitrary C# at runtime
.Log(e => $"[lambda] item={e.In.Body} branch={e.In.Headers["branch"]}")

// (B) String template — compiled by the expression engine, zero alloc when level is off
.Log("[tmpl] item=${body} branch=${header.branch} [${routeId}]")

// (C) Rich-log scope — structured, multi-message, headers/properties as separate fields
.Log(LogLevel.Information)
    .Message("[rich-tmpl]   item=${body}")
    .Message(e => $"[rich-lambda] upper={((string)e.In.Body!).ToUpperInvariant()}")
    .Header("branch")
    .Property("item-index")
    .ShowRouteId(true)
.EndLog()

${body}, ${header.x}, ${property.y}, ${routeId}, ${exception.type}, ${exception.message} — all resolved by the compiled expression engine (Tokenizer → Parser → AST → IL). The template compiles once, runs as a cached delegate. .Message() in a rich-log scope accepts both forms simultaneously.

CRTP base — 27 duplicate class bodies removed

Every leaf method (To, Process, SetBody, Filter, Split, Transaction, ~40 more) now lives once in RouteDefinitionBase<TSelf>. Each returns TSelf — chaining stays on the concrete scope type throughout. Public API and route AST identical to 3.0.0.

Fix: `GetContext()` silently returned null inside nested scopes

IRouteDefinition.GetContext() was casting to RouteDefinition, which only matched the route root. Inside When, Loop, Traced, Catch — it returned null without throwing. Now walks Parent to the owning route. Matters if you have extension methods that read context at DSL build time.

Full demo: DeepDslShowcaseRoutes.cs · Changelog: 3.0.1 · Apache 2.0

DEV Community: rinat kozin

Two routes in an evening: from a debug worker to an enterprise runtime with redb.Route + Tsak

What we're building

Project layout: two projects, one entry point

Project 1: the module with two routes

The main entry point

The schema

One HTTP server, two routes

POST: save

GET: fetch by param

Project 2: our own debug worker

The project files

Run it and poke it

Here's the trick: the same code, now enterprise

What a .tpkg is

Pack it

How Tsak finds modules: folders and hot-reload

The dashboard: watch it, and run it

Ports: defaults, and how to set them

Enterprise deploy #1: Docker (the whole stack in one container)

Enterprise deploy #2: no container (standalone archive)

Two zones: build and operate

What's next: clustering (a teaser)

Wrap-up

Leaving MassTransit for a Camel state of mind: the Kafka connector, Scatter-Gather, and what really happens under a transaction

One spoiler up front

Table of contents

1. Why leave MassTransit at all

2. What landed in 3.2.0

3. The Kafka connector: URI anatomy and the connection factory

The connection factory — so you don't repeat yourself

The full endpoint option set

The same thing, fluent

4. The Kafka producer: what .To("kafka:...") actually does

Connect

Preparing the message

The partition key

Send: immediate vs deferred

Tracing across the broker

5. The Kafka consumer: polling, batches, rebalance

Start: subscribe/assign, seek, metadata

The poll loop

Single mode

Batch mode

How the exchange gets its metadata

What the consumer does while a message travels the route

How the offset commits: default vs transactional mode

6. Headers and tracing across the broker

7. Straight talk about transacted=true

8. EIP #1 — Scatter-Gather: one processor, both fan-out and join

Under the hood: the parallel path

The sequential path

Error handling: best-effort vs stop-on-exception

Every parameter

Dynamic recipients

A real production example: one HTTP request → six parallel aggregations

9. EIP #2 — Aggregator: assembly over time

The hard limitation, said out loud

10. Transactions: two models, and that's the whole point

Camp 1: deferred actions (ITransactedAction) — they do NOT touch System.Transactions

Camp 2: SQL — it enlists in System.Transactions

Why parallel Scatter-Gather doesn't blow up under a transaction

So what is the 3.2.0 DependentTransactionBranch for, then?

The honest trade-off (a design choice, not a bug)

Transaction policies

11. The parallel cousins: Splitter and Multicast

12. Saga — "a slightly different one"

13. Outbox — there isn't one, and that's correct

14. Bottom line: a trade, not "better/worse"

SQLite provider anatomy: moving away from EF Core — typed object storage for desktop, mobile, and Blazor WASM

What this is

Part 0. The constraint that shapes everything

Part 0.5. What the provider reproduces: _objects and _values

Part 1. The native extension: anatomy

Entry point

Loading — on every connection

Shipping the binary: why it cross-compiles for free

War story #5: the .targets that broke every consumer (3.2.0 → 3.2.1)

What's inside: a materializer and a compiler

A bit deeper on get_object_json: recursion, arrays, references

The `main` entry point

What a `.tpkg` is

4. The Kafka producer: what `.To("kafka:...")` actually does

7. Straight talk about `transacted=true`

Camp 1: deferred actions (`ITransactedAction`) — they do NOT touch `System.Transactions`

Camp 2: SQL — it enlists in `System.Transactions`

So what is the 3.2.0 `DependentTransactionBranch` for, then?

Part 0.5. What the provider reproduces: `_objects` and `_values`

War story #5: the `.targets` that broke every consumer (3.2.0 → 3.2.1)

A bit deeper on `get_object_json`: recursion, arrays, references

The other direction: `save_object_json` — the write path

War story #1: `%%` in `sqlite3_mprintf`

Timezones: why `+4` resolves correctly

War story #2: analytics and a `FormatException` from nowhere

War story #3: a multi-key filter dropped `null`

DistinctBy: emulating `DISTINCT ON` with `ROW_NUMBER()`

Also: `DeleteSubtree` and cascade

Part 3½. "But I love controllers" — `redb.Route.Controllers`

Part 4. One Kestrel per (host, port) — `SharedHttpServerManager`

Part 5. Consumer: how an HTTP request becomes an `Exchange`

Headers: what the connector puts into the `Exchange`

The response: how an `Exchange` becomes HTTP again

Part 6. CORS on a shared server — without `app.UseCors()`

No implicit `*`

How the dispatcher works (`CorsDispatchMiddleware`)

Response → `Exchange`