Skip to main content

Aqueduct Reference

Overview​

Aqueduct is the Mississippi subsystem for Orleans-backed SignalR backplane integration. This page documents the runtime composition contract and the options required by an Orleans host.

Applies to​

  • Mississippi.Aqueduct.Abstractions
  • Mississippi.Aqueduct.Gateway
  • Mississippi.Aqueduct.Runtime

The runtime API in this page is included by Mississippi.Sdk.Runtime. Gateway hub registration is a separate host-specific surface and is not a second runtime attachment path.

Contract​

Compose Aqueduct from an Orleans silo's single runtime terminal callback:

using Mississippi.Aqueduct.Runtime;
using Mississippi.Hosting.Runtime;


builder.UseOrleans(siloBuilder =>
{
    siloBuilder.UseMississippi(runtime =>
    {
        runtime.AddAqueduct(aqueduct =>
            aqueduct.StreamProviderName = "StreamProvider");
        runtime.ApplyToSilo(siloBuilder);
    });
});

AddAqueduct(...) returns the same IRuntimeBuilder for chaining. Its optional Action<AqueductBuilder> runs when the runtime applies queued native configuration. ApplyToSilo(...) is the recommended explicit hook; omitting it allows UseMississippi(...) to apply queued native configuration automatically at the end of the terminal callback.

The overloads are:

APIContract
IRuntimeBuilder AddAqueduct(Action<AqueductBuilder>? configure = null)Queue one nested Aqueduct configuration for the runtime
IRuntimeBuilder AddAqueduct(IConfiguration configuration)Read option property-name keys from the supplied configuration
IRuntimeBuilder AddAqueduct(string streamProviderName, string serverStreamNamespace = ...)Queue explicit provider and server-namespace settings

Only one AddAqueduct(...) call is valid for a given runtime builder. Combine settings in one call.

Verified Ownership Boundary​

  • Distributed SignalR backplane integration
  • Orleans-driven push delivery of events and notifications into SignalR-connected clients
  • Gateway-side hub lifetime management and notifier registration
  • Runtime-side backplane registration
  • Aqueduct-specific options and abstractions for distributed message routing

Options​

AqueductBuilder exposes these runtime settings inside the AddAqueduct(...) callback:

PropertyMeaningDefault
StreamProviderNameOrleans stream provider used for SignalR deliverymississippi-streaming
ServerStreamNamespaceNamespace for server-targeted messagesmississippi-server

Names must be nonempty and must not consist only of whitespace. The values are preserved as supplied. AllClientsStreamNamespace remains a gateway option for broadcasts and is not set or validated by the runtime builder.

Defaults​

The defaults are provided by AqueductStreamDefaults and AqueductOptions:

  • Runtime StreamProviderName: mississippi-streaming
  • Runtime ServerStreamNamespace: mississippi-server
  • Gateway AllClientsStreamNamespace: mississippi-all-clients

Memory Streams​

aqueduct.UseMemoryStreams() enables Orleans memory streams using the builder's final StreamProviderName and adds the PubSubStore grain storage convention. aqueduct.UseMemoryStreams("ProviderName") selects the supplied provider name and enables the same registrations. These methods are intended for development and tests.

For a host-owned provider, set StreamProviderName to the existing provider name. Aqueduct does not provision an external provider through this API.

Configuration​

The IConfiguration overload reads these exact keys from the supplied configuration object:

KeyTarget property
StreamProviderNameAqueductBuilder.StreamProviderName
ServerStreamNamespaceAqueductBuilder.ServerStreamNamespace

Missing keys keep the runtime defaults. AllClientsStreamNamespace is configured on the gateway hosts that use it; the runtime configuration overload does not read it.

Behavior​

The nested configuration is applied to the runtime's staged silo, then the two runtime settings are copied into a snapshot used to configure IOptions<AqueductOptions>. Capturing an AqueductBuilder beyond its callback is unsupported: the scope closes after success or failure, and later property changes throw BuilderValidationException with MSB206.

Runtime service descriptors are staged with the surrounding RuntimeBuilder. Use runtime.Services or runtime.ConfigureSilo(...) for advanced runtime work; Aqueduct does not expose a nested service collection.

  • Inlet composes with Aqueduct for higher-level projection delivery.
  • Domain Modeling owns domain behavior, not transport infrastructure.
  • Runtime Composition documents the terminal runtime lifecycle and native Orleans integration.

Failure behavior​

BuilderValidationException.Diagnostics contains a stable Code plus Message and Remediation guidance. The current Aqueduct diagnostic codes are:

CodeFailureRemediation
MSB201StreamProviderName is empty or whitespaceSet a nonempty provider name
MSB202ServerStreamNamespace is empty or whitespaceSet a nonempty server namespace
MSB206A captured nested builder scope is closedConfigure a fresh AddAqueduct(...) callback
MSB207Aqueduct was added more than once to one runtimeCombine settings in one AddAqueduct(...) call

Null runtime or configuration arguments produce ArgumentNullException. The optional AddAqueduct(...) configuration callback may be omitted. Required callbacks on the runtime terminal and native configuration APIs also report ArgumentNullException; see Runtime Composition.

Compatibility​

The runtime composition layer removes the silo-level UseAqueduct(...) entry point and the AqueductSiloOptions host-capturing type. Migrate those settings to runtime.AddAqueduct(...) inside UseMississippi(...). The new UseMemoryStreams("ProviderName") overload uses the Orleans PubSubStore convention and does not accept a separate storage-name argument.

Summary​

Use runtime.AddAqueduct(...) once inside UseMississippi(...), choose a provider strategy, and rely on the stable diagnostics when validation rejects the composition.

Next Steps​