StellaOps.Router.Transport.InMemory
Router in-memory transport: connects microservices and a gateway inside one process, for development and tests.
| Package | StellaOps.Router.Transport.InMemory |
| Component | Router |
| Licence | Apache-2.0 |
| Package kind | Library |
| Target framework | net10.0 |
To add the package to a project, see Installing Stella Ops packages.
Namespaces
| Namespace | Types |
|---|---|
StellaOps.Router.Transport.InMemory | 7 |
StellaOps.Router.Transport.InMemory namespace
| Type | Kind | Description |
|---|---|---|
InMemoryChannel | class | Represents a bidirectional in-memory channel for frame passing between gateway and microservice. |
InMemoryConnectionRegistry | class | Thread-safe registry for in-memory connections. |
InMemoryTransportClient | class | In-memory transport client implementation for testing and development. |
InMemoryTransportOptions | class | Configuration options for the InMemory transport. |
InMemoryTransportPlugin | class | Plugin implementation for InMemory transport (for testing and development). |
InMemoryTransportServer | class | In-memory transport server implementation for testing and development. |
InMemoryTransportServiceCollectionExtensions | class | Extension 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: The connection ID.bufferSize: The channel buffer size. Zero for unbounded.
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
connectionId: The connection ID.bufferSize: The channel buffer size.
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
connectionId: The connection ID.
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
serviceName: The service name.version: The version.method: The HTTP method.path: The path.
GetRequiredChannel(string) method
public InMemoryChannel GetRequiredChannel(string connectionId)
Gets a channel by connection ID, throwing if not found.
Parameters
connectionId: The connection ID.
Returns
The channel.
RemoveChannel(string) method
public bool RemoveChannel(string connectionId)
Removes and disposes a channel by connection ID.
Parameters
connectionId: The connection ID.
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
reason: The reason for cancellation.
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
instance: The instance descriptor.endpoints: The endpoints to register.cancellationToken: Cancellation token.
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
instance: The instance descriptor.endpoints: The endpoints to register.schemas: Schema definitions referenced by the endpoints, ornull.openApiInfo: OpenAPI metadata for the service, ornull.cancellationToken: Cancellation token.
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
connection: The connection to use.correlationId: The correlation ID of the request to cancel.reason: Optional reason for cancellation.
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
cancellationToken: Cancellation token.
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
connection: The connection to use.requestFrame: The request frame.timeout: The timeout for the request.cancellationToken: Cancellation token.
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
connection: The connection to use.requestHeader: The request header frame.requestBody: The request body stream.readResponse: Callback that receives the response head (the status code and headers of the microservice’s response; itsResponseFrame.Payloadis empty) and the response body stream.limits: Payload limits to enforce.cancellationToken: Cancellation token.
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
context: The registration context containing services, configuration, and transport mode.
Exceptions
InvalidOperationException: The context asks for a side this plugin does not provide.
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
cancellationToken: Cancellation token.
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
cancellationToken: Cancellation token.
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
services: The service collection.configure: Optional configuration action.
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
services: The service collection.configure: Optional configuration action.
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
services: The service collection.configure: Optional configuration action.
Returns
The service collection for chaining.
