Reference

ITraxAuditSink

Package Trax.Api.GraphQL.AuditNamespace Trax.Api.GraphQL.AuditSource ITraxAuditSink.cs

NO WARRANTY. Trax auth is plumbing, not a security product. You are solely responsible for securing systems that use it. See API Security.

The destination for audit entries, implemented by the host (a database table, a log pipeline, object storage) and registered with AddAudit<TSink>().

Signature

public interface ITraxAuditSink
{
    Task WriteAsync(IReadOnlyList<TraxAuditEntry> batch, CancellationToken ct);
}

Parameters

ParameterTypeDescription
batchIReadOnlyList<TraxAuditEntry>From 1 to TraxAuditOptions.BatchSize entries.
ctCancellationTokenFires when the host's shutdown timeout runs out, not when shutdown begins.

Returns

A task that completes when the batch is stored. A faulted task counts as a failed attempt.

Behavior

  • Called from the background writer, never from a request thread. The writer is single-threaded: one call at a time.
  • The sink is resolved from a new scope for each attempt.
  • A failed attempt is retried up to MaxRetries times, waiting RetryBackoff doubled on each attempt, capped at MaxRetryBackoff, and jittered between half and all of that value. After the last retry the batch is dropped, logged, and counted in trax.audit.dropped.
  • On graceful shutdown the writer keeps writing accepted entries until the host's shutdown timeout, and ct fires then. Whatever is unwritten at that point is counted as dropped.
  • The writer catches every sink failure. A failing sink does not fail a GraphQL request.

Example

A sink that writes each batch through an IDbContextFactory:

using Microsoft.EntityFrameworkCore;
using Trax.Api.GraphQL.Audit;
 
public sealed class PostgresAuditSink(IDbContextFactory<AppDbContext> factory) : ITraxAuditSink
{
    public async Task WriteAsync(IReadOnlyList<TraxAuditEntry> batch, CancellationToken ct)
    {
        await using var db = await factory.CreateDbContextAsync(ct);
        db.AuditEntries.AddRange(batch.Select(e => new AuditRow(e)));
        await db.SaveChangesAsync(ct);
    }
}

See also