Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 59 additions & 0 deletions benchmarks/Relayer.Benchmarks/OutboxScopeResolutionBenchmarks.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
using BenchmarkDotNet.Attributes;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Options;
using Relayer.Outbox.EntityFrameworkCore;
using Relayer.Outbox.PostgreSql;

namespace Relayer.Benchmarks;

/// <summary>Default capability discovery in the delivery scope, without a DbContext or database I/O.</summary>
[MemoryDiagnoser]
public class OutboxScopeResolutionBenchmarks
{
private ServiceProvider _legacy = null!;
private ServiceProvider _cached = null!;

[GlobalSetup]
public void Setup()
{
var legacy = Services();
// Reproduce the previous factory, including snapshot validation and SQL generation per scope.
legacy.AddScoped<EntityFrameworkCoreOutbox>(static provider =>
{
var configuration = new OutboxConfiguration(
provider.GetRequiredService<IOptionsSnapshot<EntityFrameworkCoreOutboxOptions>>().Value,
workers: provider.GetServices<PostgreSqlSchedulingRegistration>());
return new(configuration.SupportsScheduling, configuration.SupportsOrderedScheduling);
});
_legacy = legacy.BuildServiceProvider();
_cached = Services().BuildServiceProvider();
_ = Resolve(_legacy);
_ = Resolve(_cached);
}

private static IServiceCollection Services()
{
var services = new ServiceCollection().AddRelayerEntityFrameworkCoreOutbox();
services.AddSingleton(new PostgreSqlSchedulingRegistration(null, "relayer_"));
return services;
}

[Benchmark(Baseline = true)]
public bool PreviousFactory() => Resolve(_legacy);

[Benchmark]
public bool CachedCapabilities() => Resolve(_cached);

private static bool Resolve(ServiceProvider provider)
{
using var scope = provider.CreateScope();
return scope.ServiceProvider.GetRequiredService<IOutboxEnlistment>().SupportsScheduling;
}

[GlobalCleanup]
public void Cleanup()
{
_legacy.Dispose();
_cached.Dispose();
}
}
2 changes: 2 additions & 0 deletions docs/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,8 @@ Each transport declares the capabilities of each endpoint (decision D24). A feat

Transport stubs declare only conservative known values; native adapters must resolve configuration-dependent limits and features at startup. In particular, a Service Bus endpoint name does not establish session support, and a RabbitMQ queue name does not establish delayed-message plugin support. SQS declarations distinguish standard and FIFO queues: [FIFO queues do not support per-message delivery timers](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-message-timers.html).

Send routes declare known scheduling needs with `SendRouteOptions.RequiredDeliveryDelay` and select transaction guarantees with `TransactionRequirement` (`None`, `Native`, `Outbox`). Composition validates native limits or the actual registered outbox executor and due-row workers once. Native transaction availability never implies database durability or automatic native transaction ownership. Runtime checks reject unavailable schedules and missing active outbox transactions before serialization. See the [send guide](https://relayer.tomlonghurst.dev/docs/guides/sending) for configuration and executor contracts.

The native mechanisms and core fallbacks are:

| Feature | Native when available | Fallback |
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
using Microsoft.Extensions.Options;
using Relayer.Outbox.PostgreSql;

namespace Relayer.Outbox.EntityFrameworkCore;

// Share immutable defaults across delivery scopes without building SQL or retaining scoped services.
internal sealed class DefaultOutboxCapabilities(IOptionsMonitor<EntityFrameworkCoreOutboxOptions> options,
IEnumerable<PostgreSqlSchedulingRegistration> workers)
{
private Snapshot? _current;

internal Snapshot Get()
{
var value = options.CurrentValue;
var current = Volatile.Read(ref _current);
if (current is not null && ReferenceEquals(current.Options, value)) return current;

current = new(value,
PostgreSqlSchedulingRegistration.Supports(workers, value.Schema, value.TablePrefix),
PostgreSqlSchedulingRegistration.Supports(workers, value.Schema, value.TablePrefix, value.Lanes));
// Concurrent reloads may duplicate this cold work; each scope still receives one coherent version.
Volatile.Write(ref _current, current);
return current;
}

internal sealed record Snapshot(EntityFrameworkCoreOutboxOptions Options, bool Scheduling, bool OrderedScheduling);
}
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,26 @@
namespace Relayer.Outbox.EntityFrameworkCore;

// Scoped, like DbContext and ISender. Never shared by concurrent units of work.
internal sealed class EntityFrameworkCoreOutbox : IOutboxEnlistment, IDisposable
internal sealed class EntityFrameworkCoreOutbox(bool supportsScheduling = false, bool supportsOrderedScheduling = false) : IOutboxEnlistment, IDisposable
{
private readonly List<OutboxContext> _contexts = [];
private readonly PostgreSqlOutboxBatch _batch = new();
private Selection? _selection;

public bool IsActive => Target() is not null;
private OutboxConfiguration? _activeConfiguration;
public bool SupportsScheduling => _activeConfiguration?.SupportsScheduling ?? supportsScheduling;
public bool SupportsOrderedScheduling => _activeConfiguration?.SupportsOrderedScheduling ?? supportsOrderedScheduling;

public bool IsActive
{
get
{
// Sender already resolves the active target. Cache its immutable dispatch settings without another context scan.
var target = Target();
_activeConfiguration = target?.Configuration;
return target is not null;
}
}

public ValueTask EnlistAsync(OutboxRecord record, CancellationToken cancellationToken)
{
Expand Down Expand Up @@ -189,6 +202,9 @@ internal void EnsureTransactionAvailable()
internal void Add(OutboxRecord record)
{
if (Failed) throw new InvalidOperationException("Roll back the failed outbox transaction before sending again.");
if (record.Message.DeliverAt is not null && !(record.Message.OrderingKey is not null
? Configuration.SupportsOrderedScheduling : Configuration.SupportsScheduling))
throw new InvalidOperationException("Scheduled EF Core outbox sends require a matching due-row dispatch worker for the selected DbContext schema, table prefix and ordered lane count. Register PostgreSQL maintenance or ordered dispatch for that store.");
BufferedOutboxMessage.Validate(record);
if (Count == Rows.Count) Rows.Add(new());
Rows[Count].Copy(record, Configuration.Lanes);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,12 @@ public static IServiceCollection AddRelayerEntityFrameworkCoreOutbox(this IServi
if (services.Any(static descriptor => descriptor.ServiceType == typeof(IOutboxEnlistment)) &&
!services.Any(static descriptor => descriptor.ServiceType == typeof(EntityFrameworkCoreOutbox)))
throw new InvalidOperationException("A different IOutboxEnlistment is already registered. Configure one scoped outbox integration.");
services.TryAddScoped<EntityFrameworkCoreOutbox>();
services.TryAddSingleton<DefaultOutboxCapabilities>();
services.TryAddScoped<EntityFrameworkCoreOutbox>(static provider =>
{
var capabilities = provider.GetRequiredService<DefaultOutboxCapabilities>().Get();
return new(capabilities.Scheduling, capabilities.OrderedScheduling);
});
services.TryAddScoped<IOutboxEnlistment>(static provider => provider.GetRequiredService<EntityFrameworkCoreOutbox>());
services.TryAddSingleton<IValidateOptions<EntityFrameworkCoreOutboxOptions>, OutboxOptionsValidator>();
services.AddOptions<EntityFrameworkCoreOutboxOptions>().ValidateOnStart();
Expand Down Expand Up @@ -58,7 +63,7 @@ public static TBuilder AddRelayerOutbox<TBuilder>(this TBuilder builder,
var outbox = services.GetRequiredService<EntityFrameworkCoreOutbox>();
var dispatcher = options.DispatchStoreName is { } name
? services.GetRequiredKeyedService<PostgreSqlDirectDispatcher>(name) : null;
var configuration = new OutboxConfiguration(options, dispatcher);
var configuration = new OutboxConfiguration(options, dispatcher, services.GetServices<PostgreSqlSchedulingRegistration>());
builder.AddInterceptors(new OutboxSaveChangesInterceptor(outbox, configuration),
new OutboxTransactionInterceptor(outbox, configuration));
return builder;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,11 @@ internal sealed class OutboxConfiguration
internal int Lanes { get; }
internal string InsertSql { get; }
internal PostgreSqlDirectDispatcher? Dispatcher { get; }
internal bool SupportsScheduling { get; }
internal bool SupportsOrderedScheduling { get; }
internal string InboxInsertSql { get; }

internal OutboxConfiguration(EntityFrameworkCoreOutboxOptions options, PostgreSqlDirectDispatcher? dispatcher = null)
internal OutboxConfiguration(EntityFrameworkCoreOutboxOptions options, PostgreSqlDirectDispatcher? dispatcher = null, IEnumerable<PostgreSqlSchedulingRegistration>? workers = null)
{
// Reuse the schema's validation, including generated identifier lengths, at registration time.
_ = PostgreSqlOutboxSchema.CreateScript(new() { Schema = options.Schema, TablePrefix = options.TablePrefix });
Expand All @@ -21,6 +23,11 @@ internal OutboxConfiguration(EntityFrameworkCoreOutboxOptions options, PostgreSq
if (options.DispatchStoreName is not null) ArgumentException.ThrowIfNullOrWhiteSpace(options.DispatchStoreName);
dispatcher?.ValidateStore(options.Schema, options.TablePrefix);
Dispatcher = dispatcher;
if (workers is not null)
{
SupportsScheduling = PostgreSqlSchedulingRegistration.Supports(workers, options.Schema, options.TablePrefix);
SupportsOrderedScheduling = PostgreSqlSchedulingRegistration.Supports(workers, options.Schema, options.TablePrefix, options.Lanes);
}
var inbox = PostgreSqlOutboxSchema.QuoteIdentifier(options.Schema ?? "public") + "." +
PostgreSqlOutboxSchema.QuoteIdentifier(options.TablePrefix + "inbox");
InboxInsertSql = $"INSERT INTO {inbox} (consumer, message_id, processed_at) VALUES (@consumer, @id, clock_timestamp()) ON CONFLICT (consumer, message_id) DO NOTHING";
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,12 @@ public static IServiceCollection AddRelayerPostgreSqlMaintenance(this IServiceCo
provider.GetRequiredService<IOptionsMonitor<PostgreSqlMaintenanceOptions>>().Get(name), provider.GetServices<ITransport>(),
provider.GetRequiredService<ILogger<PostgreSqlMaintenanceWorker>>(), provider.GetRequiredService<ILogger<PostgreSqlDirectDispatcher>>()));
services.AddSingleton<IHostedService>(provider => provider.GetRequiredKeyedService<PostgreSqlMaintenanceWorker>(name));
services.AddSingleton<PostgreSqlSchedulingRegistration>(provider =>
{
var settings = provider.GetRequiredService<IOptionsMonitor<PostgreSqlMaintenanceOptions>>().Get(name);
_ = settings.Validate();
return new(settings.Schema, settings.TablePrefix);
});
return services;
}

Expand Down
13 changes: 12 additions & 1 deletion src/Relayer.Outbox.PostgreSql/PostgreSqlOutbox.cs
Original file line number Diff line number Diff line change
Expand Up @@ -18,17 +18,28 @@ public sealed class PostgreSqlOutbox : IOutboxEnlistment, IDisposable, IAsyncDis
private bool _disposed;

/// <summary>Creates an enlistment using this scope's validated options.</summary>
public PostgreSqlOutbox(IOptionsSnapshot<PostgreSqlOutboxOptions> options)
public PostgreSqlOutbox(IOptionsSnapshot<PostgreSqlOutboxOptions> options) : this(options, []) { }

internal PostgreSqlOutbox(IOptionsSnapshot<PostgreSqlOutboxOptions> options,
IEnumerable<PostgreSqlSchedulingRegistration> workers)
{
ArgumentNullException.ThrowIfNull(options);
var value = options.Value;
ValidateOptions(value);
_lanes = value.Lanes;
SupportsScheduling = PostgreSqlSchedulingRegistration.Supports(workers, value.Schema, value.TablePrefix);
SupportsOrderedScheduling = PostgreSqlSchedulingRegistration.Supports(workers, value.Schema, value.TablePrefix, value.Lanes);
_insertSql = PostgreSqlOutboxBatch.CreateInsertSql(
PostgreSqlOutboxSchema.QuoteIdentifier(value.Schema ?? "public") + "." +
PostgreSqlOutboxSchema.QuoteIdentifier(value.TablePrefix + "outbox"));
}

/// <inheritdoc />
public bool SupportsScheduling { get; }

/// <inheritdoc />
public bool SupportsOrderedScheduling { get; }

/// <inheritdoc />
public bool IsActive => _transaction is { IsActive: true };

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,8 @@ public static IServiceCollection AddRelayerPostgreSqlOutbox(this IServiceCollect
!services.Any(static descriptor => descriptor.ServiceType == typeof(PostgreSqlOutbox)))
throw new InvalidOperationException("A different IOutboxEnlistment is already registered. Configure one scoped outbox integration.");
if (options is not null) PostgreSqlOutbox.ValidateOptions(options);
services.TryAddScoped<PostgreSqlOutbox>();
services.TryAddScoped<PostgreSqlOutbox>(provider => new(provider.GetRequiredService<IOptionsSnapshot<PostgreSqlOutboxOptions>>(),
provider.GetServices<PostgreSqlSchedulingRegistration>()));
services.TryAddScoped<IOutboxEnlistment>(static provider => provider.GetRequiredService<PostgreSqlOutbox>());
services.TryAddSingleton<IValidateOptions<PostgreSqlOutboxOptions>, Validator>();
services.AddOptions<PostgreSqlOutboxOptions>().ValidateOnStart();
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,12 @@ public static IServiceCollection AddRelayerPostgreSqlOrderedDispatch(this IServi
new(dataSource, provider.GetRequiredService<IOptionsMonitor<PostgreSqlOrderedDispatchOptions>>().Get(name),
provider.GetServices<ITransport>(), provider.GetRequiredService<ILogger<PostgreSqlOrderedDispatcher>>()));
services.AddSingleton<IHostedService>(provider => provider.GetRequiredKeyedService<PostgreSqlOrderedDispatcher>(name));
services.AddSingleton<PostgreSqlSchedulingRegistration>(provider =>
{
var settings = provider.GetRequiredService<IOptionsMonitor<PostgreSqlOrderedDispatchOptions>>().Get(name);
_ = settings.Validate();
return new(settings.Schema, settings.TablePrefix, settings.Lanes);
});
return services;
}

Expand Down
14 changes: 14 additions & 0 deletions src/Relayer.Outbox.PostgreSql/PostgreSqlSchedulingRegistration.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
namespace Relayer.Outbox.PostgreSql;

// Created only by registrations that install an actual hosted due-row dispatcher.
internal sealed record PostgreSqlSchedulingRegistration(string? Schema, string TablePrefix, int? OrderedLanes = null)
{
internal static bool Supports(IEnumerable<PostgreSqlSchedulingRegistration> workers, string? schema,
string prefix, int? orderedLanes = null)
{
foreach (var worker in workers)
if ((worker.Schema ?? "public") == (schema ?? "public") && worker.TablePrefix == prefix &&
worker.OrderedLanes == orderedLanes) return true;
return false;
}
}
7 changes: 6 additions & 1 deletion src/Relayer/Configuration/EndpointCapabilityValidator.cs
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,12 @@ internal sealed class EndpointCapabilityValidator
private readonly List<string> _failures;
private readonly EndpointCapabilityCache _cache;
private readonly bool _hasRuntimeTransports;
private readonly OutboxCapabilities? _outbox;

internal EndpointCapabilityValidator(IEnumerable<ITransport> transports, List<string> failures, EndpointCapabilityCache cache)
internal EndpointCapabilityValidator(IEnumerable<ITransport> transports, List<string> failures, EndpointCapabilityCache cache, OutboxCapabilities? outbox = null)
{
_failures = failures;
_outbox = outbox;
_cache = cache;
foreach (var transport in transports)
{
Expand Down Expand Up @@ -45,6 +47,9 @@ internal void Validate(TransportDefinition definition)
foreach (var route in definition.Routes)
{
var capabilities = GetCapabilities(transport, route.Destination);
if (capabilities is not null && route is ISendRouteDefinition send && _outbox is not null)
SendCapabilityValidator.Validate(send.SendOptions, capabilities, route.HasOrderingKey, _outbox,
$"Route for '{route.MessageType}' to '{route.Destination}' on transport '{definition.Name}'", _failures);
if (route.HasOrderingKey && capabilities is { OrderedByKey: false })
{
_failures.Add($"Route for '{route.MessageType}' to '{route.Destination}' on transport '{definition.Name}': " +
Expand Down
20 changes: 20 additions & 0 deletions src/Relayer/Configuration/OutboxCapabilities.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
using Microsoft.Extensions.DependencyInjection;

namespace Relayer;

// Resolve scoped executors once during composition, never retain a scoped service in the pipeline.
internal sealed class OutboxCapabilities(IServiceScopeFactory scopes)
{
private readonly Lazy<Snapshot> _snapshot = new(() => Resolve(scopes));
internal Snapshot Get() => _snapshot.Value;

private static Snapshot Resolve(IServiceScopeFactory scopes)
{
using var scope = scopes.CreateScope();
var executor = scope.ServiceProvider.GetService<IOutboxEnlistment>();
return new(executor is not null, executor?.SupportsScheduling == true,
executor?.SupportsOrderedScheduling == true);
}

internal sealed record Snapshot(bool Transactions, bool Scheduling, bool OrderedScheduling);
}
2 changes: 1 addition & 1 deletion src/Relayer/Configuration/RelayerConfigurationValidator.cs
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ public void Validate()
}
try
{
var capabilities = new EndpointCapabilityValidator(services.GetServices<ITransport>(), failures, services.GetRequiredService<EndpointCapabilityCache>());
var capabilities = new EndpointCapabilityValidator(services.GetServices<ITransport>(), failures, services.GetRequiredService<EndpointCapabilityCache>(), services.GetRequiredService<OutboxCapabilities>());
foreach (var transport in configuration.Transports) capabilities.Validate(transport);
}
catch (OptionsValidationException error)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ public static IServiceCollection AddRelayer(this IServiceCollection services, Ac
});
services.TryAddEnumerable(ServiceDescriptor.Singleton<IHostedService, MessageSerializerStartupValidator>());
services.TryAddSingleton<EndpointCapabilityCache>();
services.TryAddSingleton<OutboxCapabilities>();
services.TryAddSingleton<SendPipeline>();
services.TryAddSingleton<SenderPool>();
services.TryAddScoped<ISender>(static provider => provider.GetRequiredService<SenderPool>()
Expand Down
Loading
Loading