hexasync.access.client

The client for the HexaSync graph authorization engine. Four things live here, and only the last one needs a guide:

The outbox, in one paragraph

Your service owns some entities — profiles, tenants, devices. The engine needs to know they exist and what they are called, and it must learn this exactly when your write commits and never otherwise. So you write a row into graph_outbox inside your own transaction, and a background driver walks that table in commit order and delivers each entry to the engine. If your transaction rolls back, the entry was never there. If delivery fails, the entry is still there.

Two lanes ship with the package:

• graph.init — this resource now exists, with these initial relations. Delivered to POST /api/v3/graph/resources/init.
• graph.metadata — this entity's label changed. Delivered to PUT /api/v3/graph/entities/{type}/{id}/metadata.

Wiring it up — four steps, and none of them is optional

1. Put the tables in your model

The package owns the shape; you own the migration. One line in your DbContext:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    base.OnModelCreating(modelBuilder);
    modelBuilder.ApplyGraphOutboxModel();   // graph_outbox, graph_outbox_cursor, graph_outbox_dead
}

Then scaffold your own migration as you would for any other change:

dotnet ef migrations add GraphOutbox --project <your-ef-project>

Why not a DDL script the package hands you? It used to be exactly that, and it rotted in a way worth understanding before you reach for the same shortcut elsewhere. CREATE TABLE IF NOT EXISTS does nothing to a database that already has the table, so every column added after the first release had to arrive as an appended ALTER TABLE … ADD COLUMN IF NOT EXISTS. That list only grows, and it is applied by whatever you remember to run. The failure that actually happened is worse than untidy: a consumer ran the script as raw SQL from inside a migration, so the tables existed in its database and nothing at all was in its model snapshot — and the next migrations add could not see them.

An IEntityTypeConfiguration describes the shape as it is, not as a history of edits. Your migrations add computes the diff, and your snapshot carries the tables, so the migration after this one is computed against the truth.

⚠️ ApplyConfigurationsFromAssembly on your own assembly will not find these — they live in this one. That is why the call is explicit.

2. Register the driver

services.AddGraphOutbox(o =>
{
    o.DeliveryUrl = config["GRAPH_ENGINE_URL"];          // required, checked at boot
    o.NotificationUrl = config["ALERT_WEBHOOK_URL"];     // optional today
    o.Notify = (notice, ct) => alerts.SendAsync(notice, ct);   // required, see below
});

Two things must already be in your DI container, because both are deployment-wide decisions and neither is the package's to make:

• NpgsqlDataSource — the outbox tables live in your database. That is the entire point of an outbox.
• IDistributedLockProvider — the leader lock. Its backend is yours to choose; this workspace uses Redis via Medallion.

AddGraphOutbox registers the driver, both standard processors, the named HttpClient, and the boot-time URL check. It resolves nothing at registration time.

3. Attach your service identity to the delivery client

The package sets the address. You supply the credential — every consumer reaches the engine as itself, and a library that picked a token source would be choosing your infrastructure:

services.AddHttpClient(GraphOutboxHttp.ClientName)
        .AddHttpMessageHandler<InnerServiceTokenHandler>();

Skip this and every entry parks on a 401.

4. Enqueue inside your own transaction

await using var tx = await connection.BeginTransactionAsync(ct);

// … your mutation, FIRST …
await UpdateTheProfileRow(connection, tx, profile, ct);

// … then the enqueue, on the SAME connection and transaction …
await GraphOutboxWriter.EnqueueAsync(
    connection, tx,
    Guid.CreateVersion7(),
    GraphOutboxLanes.Init,
    JsonSerializer.Serialize(new
    {
        resourceType = "profile",
        resourceId = profile.Id.ToString("D"),
        relations = new[] { new { relation = "parent", subjectType = "user", subjectId = ownerId.ToString("D") } },
        requestedBy = ownerId.ToString("D"),
    }),
    ct);

await tx.CommitAsync(CancellationToken.None);

🔴 Enqueue AFTER the row update, never before. The row lock is what orders two concurrent mutations of the same entity: the second cannot reach its enqueue until the first commits, so ids come out in commit order. Insert first and they invert — the transaction that has not taken a lock yet gets the lower id, and the later change is delivered as if it were earlier.

🔴 The id is yours to supply — normally Guid.CreateVersion7(). There is no column default, because uuidv7() is a PostgreSQL 18 built-in and this package does not control your server version.

The shape of the running system

your handler ──┬── UPDATE profiles          ┐
               └── INSERT graph_outbox      ┘ one transaction

                        ▼

  GraphOutboxService  (one per pod; exactly one holds the leader lock)
        │
        ├─ lane graph.init ──── ScanOnceAsync(LIMIT 100) ──→ GraphOutboxInitProcessor ──→ engine
        └─ lane graph.metadata ─ ScanOnceAsync(LIMIT 100) ──→ GraphOutboxMetadataProcessor ─→ engine

One driver, every lane. The lanes are the registered processors, not a SELECT DISTINCT(lane). Each gets one bounded pass per cycle, which is what keeps a wedged lane from starving the others: a pass returns after at most BatchSize entries whatever happens inside it.

One leader. Every pod starts the driver; one acquires the lock and works, the rest stand by and take over on eviction. Standby is the normal state, not an error. If the leader loses its lease mid-pass it stops immediately — a holder that kept working after eviction would produce the exact double-driver state the lock exists to prevent.

The lock buys waste, not correctness. The cursor claim is an UPDATE, so two pods cannot both notify, and the walk tolerates double delivery against an idempotent destination. Do not remove either of those on the strength of the lock.

Adding your own lane

Implement the interface and register it. Nothing else changes:

public sealed class DeviceProjectionProcessor : IGraphOutboxLaneProcessor
{
    public string Lane => "myservice.devices";

    public async Task<DeliveryOutcome> DeliverAsync(GraphOutboxEntry entry, CancellationToken ct)
    {
        var response = await _client.PostAsync("…", Body(entry.Payload), ct);
        return response.IsSuccessStatusCode
            ? DeliveryOutcome.Delivered
            : DeliveryOutcome.FromStatus((int)response.StatusCode);
    }
}

services.AddScoped<IGraphOutboxLaneProcessor, DeviceProjectionProcessor>();

One entry, not a batch — and that is deliberate. A batch signature would move two rules into every processor you ever write: stop at the first failure, never skip, and who advances the cursor. Both live in the scanner today, once, and the walk's whole guarantee — delivery in (xid, id) commit order — depends on them. A processor that advanced past its own failure would deliver a later change as if it were earlier.

Return, don't throw, for an expected refusal. A throw is caught and treated as a retry, which is the right default for a broken transport — it keeps deliverable data out of the dead-letter table.

What happens when delivery fails

There is no attempt limit, and that is the design: what matters is whether the response can ever change, not how many times you have asked.

A parked entry is logged at Warning every pass, and raises a notice through your Notify delegate. That delegate is required for a reason — an earlier version halted the lane on a permanent failure, which was impossible to ignore; parking is easy to ignore, and a notice nobody configured is the same silence in a different place.

Triage and replay through GraphOutboxDeadLetterStore — the list route deliberately carries no payloads, and a requeue inserts a new entry with a fresh id so both attempts stay traceable.

Lag

A lane cannot advance past the oldest in-flight transaction anywhere in your database. A lane sitting at zero delivered with a non-zero lag is not idle — it is blocked by an unrelated long-running query. The driver logs the lag on every pass, including empty ones, precisely because the symptom otherwise reads as "the graph is stale" with the cause nowhere near it.

Options

Two failure modes worth recognising

"Everything is healthy and the graph is stale." The driver catches every exception a pass throws, logs it, and sleeps. So a misconfiguration produced a lane that looked alive and delivered nothing — which is why the URLs are checked at boot and the host refuses to start without them.

"Registered and idle" looks exactly like "not registered at all." A consumer enqueued onto both lanes for a month while nothing drained them, because wiring the outbox took six registrations per lane and nobody did it. That is what AddGraphOutbox exists to prevent — and why the driver logs a Warning, every pass, when no processors are registered.