StellaOps.Router.Transport.InMemory

Router in-memory transport: connects microservices and a gateway inside one process, for development and tests.

PackageStellaOps.Router.Transport.InMemory
ComponentRouter
LicenceApache-2.0
Package kindLibrary
Target frameworknet10.0

To add the package to a project, see Installing Stella Ops packages.

Namespaces

NamespaceTypes
StellaOps.Router.Transport.InMemory7

StellaOps.Router.Transport.InMemory namespace

TypeKindDescription
InMemoryChannelclassRepresents a bidirectional in-memory channel for frame passing between gateway and microservice.
InMemoryConnectionRegistryclassThread-safe registry for in-memory connections.
InMemoryTransportClientclassIn-memory transport client implementation for testing and development.
InMemoryTransportOptionsclassConfiguration options for the InMemory transport.
InMemoryTransportPluginclassPlugin implementation for InMemory transport (for testing and development).
InMemoryTransportServerclassIn-memory transport server implementation for testing and development.
InMemoryTransportServiceCollectionExtensionsclassExtension methods for registering InMemory transport services.

InMemoryChannel class

public sealed class InMemoryChannel : IDisposable

Represents a bidirectional in-memory channel for frame passing between gateway and microservice.

InMemoryChannel(string, int) constructor

public InMemoryChannel(string connectionId, int bufferSize = 0)

Initializes a new instance of the InMemoryChannelclass.

Parameters

ConnectionId property

public string ConnectionId { get; }

Gets the connection ID.

Instance property

public InstanceDescriptor? Instance { get; set; }

Gets or sets the instance descriptor for this connection. Set when HELLO is processed.

LifetimeToken property

public CancellationTokenSource LifetimeToken { get; }

Gets the cancellation token source for this connection’s lifetime.

State property

public ConnectionState? State { get; set; }

Gets or sets the connection state.

ToGateway property

public Channel<Frame> ToGateway { get; }

Gets the channel for frames from microservice to gateway. SDK writes, Gateway reads.

ToMicroservice property

public Channel<Frame> ToMicroservice { get; }

Gets the channel for frames from gateway to microservice. Gateway writes, SDK reads.

Dispose() method

public void Dispose()

Disposes the channel and cancels all pending operations.

InMemoryConnectionRegistry class

public sealed class InMemoryConnectionRegistry : IDisposable

Thread-safe registry for in-memory connections.

InMemoryConnectionRegistry() constructor

public InMemoryConnectionRegistry()

Creates an instance of InMemoryConnectionRegistry.

ConnectionIds property

public IEnumerable<string> ConnectionIds { get; }

Gets all connection IDs.

Count property

public int Count { get; }

Gets the count of active connections.

CreateChannel(string, int) method

public InMemoryChannel CreateChannel(string connectionId, int bufferSize = 0)

Creates a new channel with the given connection ID.

Parameters

Returns

The created channel.

Dispose() method

public void Dispose()

Disposes all channels.

GetAllConnections() method

public IReadOnlyList<ConnectionState> GetAllConnections()

Gets all active connection states.

GetChannel(string) method

public InMemoryChannel? GetChannel(string connectionId)

Gets a channel by connection ID.

Parameters

Returns

The channel, or null if not found.

GetConnectionsFor(string, string, string, string) method

public IReadOnlyList<ConnectionState> GetConnectionsFor(string serviceName, string version, string method, string path)

Gets connections for a specific service and endpoint.

Parameters

GetRequiredChannel(string) method

public InMemoryChannel GetRequiredChannel(string connectionId)

Gets a channel by connection ID, throwing if not found.

Parameters

Returns

The channel.

RemoveChannel(string) method

public bool RemoveChannel(string connectionId)

Removes and disposes a channel by connection ID.

Parameters

Returns

True if the channel was found and removed.

InMemoryTransportClient class

public sealed class InMemoryTransportClient : ITransportClient, IMicroserviceTransport, IDisposable

In-memory transport client implementation for testing and development. Used by the Microservice SDK to send frames to the Gateway.

InMemoryTransportClient(InMemoryConnectionRegistry, IOptions<InMemoryTransportOptions>, ILogger<InMemoryTransportClient>, InMemoryTransportServer) constructor

public InMemoryTransportClient(InMemoryConnectionRegistry registry, IOptions<InMemoryTransportOptions> options, ILogger<InMemoryTransportClient> logger, InMemoryTransportServer? transportServer = null)

Initializes a new instance of the InMemoryTransportClientclass.

OnCancelReceived event

public event Func<Guid, string?, Task>? OnCancelReceived

Event raised when a CANCEL frame is received from the gateway.

OnRequestReceived event

public event Func<Frame, CancellationToken, Task<Frame>>? OnRequestReceived

Event raised when a REQUEST frame is received from the gateway.

CancelAllInflight(string) method

public void CancelAllInflight(string reason)

Cancels all in-flight handler requests. Called when connection is closed or transport is shutting down.

Parameters

ConnectAsync(InstanceDescriptor, IReadOnlyList<EndpointDescriptor>, CancellationToken) method

public Task ConnectAsync(InstanceDescriptor instance, IReadOnlyList<EndpointDescriptor> endpoints, CancellationToken cancellationToken)

Connects to the in-memory transport and sends a HELLO frame without schemas or OpenAPI metadata.

Parameters

ConnectAsync(InstanceDescriptor, IReadOnlyList<EndpointDescriptor>, IReadOnlyDictionary<string, SchemaDefinition>, ServiceOpenApiInfo, CancellationToken) method

public Task ConnectAsync(InstanceDescriptor instance, IReadOnlyList<EndpointDescriptor> endpoints, IReadOnlyDictionary<string, SchemaDefinition>? schemas, ServiceOpenApiInfo? openApiInfo, CancellationToken cancellationToken)

Connects to the in-memory transport and sends a HELLO frame. The gateway reads the endpoints, the schema definitions they reference and the OpenAPI metadata from the connection state this method registers.

Parameters

DisconnectAsync() method

public Task DisconnectAsync()

Disconnects from the transport.

Dispose() method

public void Dispose()

See IDisposable.Dispose().

SendCancelAsync(ConnectionState, Guid, string) method

public Task SendCancelAsync(ConnectionState connection, Guid correlationId, string? reason = null)

Sends a cancellation request.

Parameters

SendGoodbyeAsync(CancellationToken) method

public Task SendGoodbyeAsync(CancellationToken cancellationToken)

Sends a best-effort Goodbye control frame before shutdown. Transports that do not maintain a live microservice connection may no-op.

Parameters

SendHeartbeatAsync(HeartbeatPayload, CancellationToken) method

public Task SendHeartbeatAsync(HeartbeatPayload heartbeat, CancellationToken cancellationToken)

Sends a heartbeat frame.

SendRequestAsync(ConnectionState, Frame, TimeSpan, CancellationToken) method

public Task<Frame> SendRequestAsync(ConnectionState connection, Frame requestFrame, TimeSpan timeout, CancellationToken cancellationToken)

Sends a request and waits for a response.

Parameters

Returns

The response frame.

SendStreamingAsync(ConnectionState, Frame, Stream, Func<ResponseFrame, Stream, Task>, PayloadLimits, CancellationToken) method

public Task SendStreamingAsync(ConnectionState connection, Frame requestHeader, Stream requestBody, Func<ResponseFrame, Stream, Task> readResponse, PayloadLimits limits, CancellationToken cancellationToken)

Sends a request whose body is read from a stream and hands the microservice’s response to readResponse. TransportStreamingDispatch.SendBufferedAsync(ITransportClient, ConnectionState, Frame, Stream, Func<ResponseFrame, Stream, Task>, PayloadLimits, CancellationToken)implements it for transports whose microservice side answers a request with one response frame.

Parameters

Remarks

The request body is read into one request frame (TransportStreamingDispatch.SendBufferedAsync(ITransportClient, ConnectionState, Frame, Stream, Func<ResponseFrame, Stream, Task>, PayloadLimits, CancellationToken)): the in-memory channel carries whole frames and the SDK answers with one response frame.

InMemoryTransportOptions class

public sealed class InMemoryTransportOptions

Configuration options for the InMemory transport.

InMemoryTransportOptions() constructor

public InMemoryTransportOptions()

Creates an instance of InMemoryTransportOptions.

ChannelBufferSize property

public int ChannelBufferSize { get; set; }

Gets or sets the channel buffer size. Default: Unbounded (0 means unbounded).

DefaultTimeout property

public TimeSpan DefaultTimeout { get; set; }

Gets or sets the default timeout for requests. Default: 30 seconds.

HeartbeatInterval property

public TimeSpan HeartbeatInterval { get; set; }

Gets or sets the heartbeat interval. Default: 45 seconds.

HeartbeatTimeout property

public TimeSpan HeartbeatTimeout { get; set; }

Gets or sets the heartbeat timeout (time since last heartbeat before connection is considered unhealthy). Default: 135 seconds (3x heartbeat interval).

SimulatedLatency property

public TimeSpan SimulatedLatency { get; set; }

Gets or sets the simulated latency for frame delivery. Default: Zero (instant delivery).

InMemoryTransportPlugin class

public sealed class InMemoryTransportPlugin : IRouterTransportPlugin

Plugin implementation for InMemory transport (for testing and development). The in-process channel has no network server, so one plugin provides both sides.

InMemoryTransportPlugin() constructor

public InMemoryTransportPlugin()

Creates an instance of InMemoryTransportPlugin.

DisplayName property

public string DisplayName { get; }

Gets the human-readable display name for this transport.

Mode property

public RouterTransportMode Mode { get; }

Gets the side of the transport this plugin registers: RouterTransportMode.Client, RouterTransportMode.Server, or RouterTransportMode.Both. IRouterTransportPlugin.Register(RouterTransportRegistrationContext)refuses a context that asks for a side outside this value (RouterTransportRegistrationContext.EnsureSupportedBy(IRouterTransportPlugin)).

TransportName property

public string TransportName { get; }

Gets the transport name (e.g., “tcp”, “tls”, “udp”, “rabbitmq”, “inmemory”, “messaging”), shared by the client and the server plugin of one transport.

Register(RouterTransportRegistrationContext) method

public void Register(RouterTransportRegistrationContext context)

Registers transport services into the DI container for the side the context asks for.

Parameters

Exceptions

InMemoryTransportServer class

public sealed class InMemoryTransportServer : ITransportServer, IDisposable

In-memory transport server implementation for testing and development. Used by the Gateway to receive frames from microservices.

InMemoryTransportServer(InMemoryConnectionRegistry, IOptions<InMemoryTransportOptions>, ILogger<InMemoryTransportServer>) constructor

public InMemoryTransportServer(InMemoryConnectionRegistry registry, IOptions<InMemoryTransportOptions> options, ILogger<InMemoryTransportServer> logger)

Initializes a new instance of the InMemoryTransportServerclass.

OnConnectionClosed event

public event Func<string, Task>? OnConnectionClosed

Event raised when a connection is closed.

OnHeartbeatReceived event

public event Func<ConnectionState, HeartbeatPayload, Task>? OnHeartbeatReceived

Event raised when a HEARTBEAT frame is received.

OnHelloReceived event

public event Func<ConnectionState, HelloPayload, Task>? OnHelloReceived

Event raised when a HELLO frame is received.

OnResponseReceived event

public event Func<ConnectionState, Frame, Task>? OnResponseReceived

Event raised when a RESPONSE frame is received.

Dispose() method

public void Dispose()

See IDisposable.Dispose().

SendToMicroserviceAsync(string, Frame, CancellationToken) method

public ValueTask SendToMicroserviceAsync(string connectionId, Frame frame, CancellationToken cancellationToken)

Sends a frame to a microservice via the ToMicroservice channel.

StartAsync(CancellationToken) method

public Task StartAsync(CancellationToken cancellationToken)

Starts listening for incoming connections.

Parameters

StartListeningToConnection(string) method

public void StartListeningToConnection(string connectionId)

Starts listening to a specific connection’s ToGateway channel. Called when a new connection is registered.

StopAsync(CancellationToken) method

public Task StopAsync(CancellationToken cancellationToken)

Stops accepting new connections.

Parameters

InMemoryTransportServiceCollectionExtensions class

public static class InMemoryTransportServiceCollectionExtensions

Extension methods for registering InMemory transport services.

AddInMemoryTransport(IServiceCollection, Action<InMemoryTransportOptions>) extension method

public static IServiceCollection AddInMemoryTransport(this IServiceCollection services, Action<InMemoryTransportOptions>? configure = null)

Adds the InMemory transport for testing and development.

Parameters

Returns

The service collection for chaining.

AddInMemoryTransportClient(IServiceCollection, Action<InMemoryTransportOptions>) extension method

public static IServiceCollection AddInMemoryTransportClient(this IServiceCollection services, Action<InMemoryTransportOptions>? configure = null)

Adds the InMemory transport client only (for Microservice SDK).

Parameters

Returns

The service collection for chaining.

AddInMemoryTransportServer(IServiceCollection, Action<InMemoryTransportOptions>) extension method

public static IServiceCollection AddInMemoryTransportServer(this IServiceCollection services, Action<InMemoryTransportOptions>? configure = null)

Adds the InMemory transport server only (for Gateway).

Parameters

Returns

The service collection for chaining.