Eigenverft.WebLib.SerilogRelayReceiver 1.0.0.8

Eigenverft.WebLib.SerilogRelayReceiver

ASP.NET Core receiver for Eigenverft.NetLib.SerilogRelay batches.

The package provides:

• HTTP ingestion and protocol validation for SerilogRelay batches;
• optional endpoint-scoped bearer-token authentication;
• built-in durable persistence through Entity Framework Core;
• provider-neutral storage integration: the host chooses SQLite, SQL Server, PostgreSQL/Npgsql, or another compatible EF Core provider;
• a custom ISerilogRelayBatchHandler path for queue, multi-backend, or non-EF scenarios.

Supported frameworks

• .NET 8 (net8.0)
• .NET 10 (net10.0)

The package references the matching major version of Microsoft.EntityFrameworkCore. It does not reference a concrete database provider.

Install

dotnet add package Eigenverft.WebLib.SerilogRelayReceiver

Add the EF Core provider package selected by the host separately.

EF Core quick start

Define a host-owned DbContext and include the receiver model:

public sealed class LoggingDbContext : DbContext
{
    public LoggingDbContext(DbContextOptions<LoggingDbContext> options)
        : base(options)
    {
    }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        base.OnModelCreating(modelBuilder);
        modelBuilder.ConfigureSerilogRelayReceiver();
    }
}

Register an IDbContextFactory<TDbContext> with the provider selected by the host. SQLite is shown only as an example:

builder.Services.AddDbContextFactory<LoggingDbContext>(
    options => options.UseSqlite(
        builder.Configuration.GetConnectionString("Logging")));

builder.Services
    .AddSerilogRelayReceiverEntityFrameworkCore<LoggingDbContext>();

Map the receiver endpoint:

app.MapSerilogRelayReceiverEntityFrameworkCore<LoggingDbContext>(
    "/api/v1/logs",
    options =>
    {
        options.BearerToken =
            builder.Configuration["SerilogRelay:BearerToken"];

        options.MaximumBatchEvents = 100;
    });

The built-in handler creates and disposes one isolated DbContext per accepted batch. Its SaveChangesAsync therefore cannot accidentally persist unrelated tracked changes from another request scope.

Changing the host's AddDbContextFactory provider configuration is enough to use another EF Core provider. Provider packages, connection strings, migrations, retention, and database lifecycle remain host-owned.

EF Core model and migrations

ConfigureSerilogRelayReceiver() adds the public SerilogRelayReceivedEvent entity to the host model.

For relational providers the default table name is:

SerilogRelayReceivedEvents

Important model semantics:

• ReceiveId is the receiver-local generated primary key;
• EventId is indexed but deliberately not unique;
• repeated delivery therefore creates another physical receive instead of being rejected or silently discarded;
• the model also indexes BatchId, ReceivedAtUtc, and (ApplicationId, ReceivedAtUtc).
• payload text fields preserve null and empty strings as distinct values; BatchTimestamp, Timestamp, Level, RenderMessage, and MessageTemplate are nullable, as are the optional machine, tracing, exception, and property fields.

The receiver does not ship provider-specific migrations. Because the entity is part of the host's DbContext model, the host's normal EF Core migration workflow owns schema creation and upgrades.

Existing databases created with the earlier non-nullable model need a host-owned migration allowing NULL in BatchTimestamp, Timestamp, Level, RenderMessage, and MessageTemplate. Updating the package or calling EnsureCreated() does not change an existing table.

For temporary/test databases, EnsureCreated() can be useful. Production databases that use migrations should use the host's normal migration workflow instead of mixing migrations with EnsureCreated().

Sender and receiver responsibilities

This package is a matching receiver implementation, not a required peer of Eigenverft.NetLib.SerilogRelay. Either side can be implemented independently against the wire format and HTTP acknowledgment contract.

The sender handles bounded local buffering, outage retries, backlog delivery during normal operation, and bounded shutdown delivery. Any HTTP 2xx allows it to release the acknowledged events locally. It does not require a receiver-side persistence receipt or negotiate storage and payload limits.

The receiver owns its acceptance policy. The built-in EF Core handler saves every validated event before returning successfully. A custom handler or independently implemented receiver may forward, filter, or deliberately discard an event and still acknowledge it, for example when its policy excludes oversized events. Such acknowledgment is an intentional receiver decision; the sender will not retry those events. A non-2xx response keeps them pending for the sender's retry policy.

The sender's configurable 4 MiB batch target does not impose a limit on this receiver. A single event above that target can arrive in its own batch. Host/proxy request limits and receiver acceptance policy remain host concerns.

Durable acceptance semantics

The built-in EF Core handler:

• creates a fresh host-configured DbContext for each accepted batch;
• maps every validated event to one SerilogRelayReceivedEvent;
• preserves the current batch and event metadata;
• adds receiver-side ReceivedAtUtc;
• adds the complete batch to the DbContext;
• calls SaveChangesAsync once;
• returns successfully only after that save completes.

For normal relational EF Core providers, the provider/EF Core transaction semantics protect one SaveChanges operation. The receiver test suite verifies with SQLite that a failure while persisting a later event leaves no rows from the batch.

A production provider must offer durability and atomicity appropriate for the endpoint contract. Provider-specific behavior remains the host's responsibility.

Endpoint and storage topology

An endpoint is not tied to one ApplicationId. A valid batch may contain events from multiple applications, machines, and processes.

The built-in EF Core integration directly supports:

A single endpoint can target multiple durable backends through a custom ISerilogRelayBatchHandler. The receiver does not impose a distributed transaction protocol for that case.

Application-based storage routing, application allow-lists, and storage partitioning are not part of the 1.0 API.

Request ownership and cancellation

Before a complete batch has been received and validated, request processing uses HttpContext.RequestAborted.

After validation, durable handling receives the host application's stopping token instead of the client request-abort token. Consequently:

• a client disconnect after durable handoff does not by itself cancel persistence;
• host shutdown can cancel in-flight durable work;
• host-shutdown cancellation returns 503 Service Unavailable;
• successful durable completion returns 204 No Content.

Endpoint options

SerilogRelayReceiverOptions intentionally contains only:

• BearerToken: optional exact bearer token; null/empty/whitespace disables token validation;
• MaximumBatchEvents: maximum accepted event count, default 100.

Options belong to each mapped endpoint, so different endpoints can use different authentication and limits.

Wire protocol behavior

The receiver validates:

• protocol version 1;
• canonical GUID BatchId;
• Count matching the number of events;
• MaximumBatchEvents;
• no null entries in Logs;
• canonical GUID EventId;
• non-empty ApplicationId;
• positive ProcessId.

SerilogRelay wire JSON is deserialized with receiver-owned ASP.NET Web-compatible JSON settings. Global host HttpJsonOptions therefore cannot silently change the relay protocol's naming or case behavior.

HTTP results:

• 204: durable handling completed;
• 400: malformed or protocol-invalid payload;
• 401: bearer authentication failed;
• 415: unsupported JSON media type or charset;
• 503: durable handling was cancelled because the host is stopping;
• other 5xx: unexpected receiver, handler, or storage failure.

Custom handler path

Applications that need queue-backed acceptance, multiple durable backends, or non-EF processing can supply their own handler:

builder.Services.AddSerilogRelayReceiver<MyRelayBatchHandler>();

app.MapSerilogRelayReceiver<MyRelayBatchHandler>(
    "/api/v1/logs");

A custom handler must complete its chosen acceptance policy before returning successfully. If that policy promises durable storage or queue handoff, it must fulfill that promise before acknowledgment. Intentional filtering or discarding also completes acceptance and allows the sender to release those events.

Not part of the 1.0 contract

The receiver intentionally does not define:

• request-body byte limits;
• application allow-lists or application-based storage routing;
• retention/cleanup policy;
• duplicate-query or deduplicated-view behavior;
• provider-specific migrations;
• multi-backend composition helpers;
• richer acknowledgement payloads.