StellaOps.Router.Transport.Udp
Router UDP transport, client side: sends the frames of a microservice to a gateway as UDP datagrams.
| Package | StellaOps.Router.Transport.Udp |
| 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.Udp | 5 |
StellaOps.Router.Transport.Udp namespace
| Type | Kind | Description |
|---|---|---|
UdpFrameProtocol | class | Handles serialization and deserialization of frames for UDP transport. |
UdpTransportClient | class | UDP transport client implementation for microservices. |
UdpTransportClientServiceCollectionExtensions | class | Extension methods for registering UDP transport services. |
UdpTransportOptions | class | Options for UDP transport configuration. |
UdpTransportPlugin | class | Plugin for the client side of the UDP transport, which a microservice connects with. |
UdpFrameProtocol class
public static class UdpFrameProtocol
Handles serialization and deserialization of frames for UDP transport. Frame format: [1-byte frame type][1-byte correlation length N][N bytes UTF-8 correlation id][remaining data] (TransportFrameHeader). The correlation id travels unchanged, so the gateway’s ULID correlations survive the round trip.
GetHeaderSize() method
public static int GetHeaderSize()
Gets the smallest valid datagram size: a header without a correlation id.
ParseFrame(ReadOnlySpan<byte>) method
public static Frame ParseFrame(ReadOnlySpan<byte> data)
Parses a frame from a datagram.
Parameters
data: The datagram data.
Returns
The parsed frame.
Exceptions
InvalidOperationException: Thrown when the datagram header is malformed.
SerializeFrame(Frame) method
public static byte[] SerializeFrame(Frame frame)
Serializes a frame to a datagram.
Parameters
frame: The frame to serialize.
Returns
The serialized datagram bytes.
Exceptions
ArgumentException: The correlation id is longer thanTransportFrameHeader.MaxCorrelationIdBytesUTF-8 bytes.
UdpTransportClient class
public sealed class UdpTransportClient : ITransportClient, IMicroserviceTransport, IAsyncDisposable
UDP transport client implementation for microservices. UDP transport does not support streaming.
UdpTransportClient(IOptions<UdpTransportOptions>, ILogger<UdpTransportClient>) constructor
public UdpTransportClient(IOptions<UdpTransportOptions> options, ILogger<UdpTransportClient> logger)
Initializes a new instance of the UdpTransportClientclass.
OnCancelReceived event
public event Func<Guid, string?, Task>? OnCancelReceived
Event raised when a CANCEL frame is received.
OnRequestReceived event
public event Func<Frame, CancellationToken, Task<Frame>>? OnRequestReceived
Event raised when a REQUEST frame is received.
CancelAllInflight(string) method
public void CancelAllInflight(string reason)
Cancels all in-flight handlers.
ConnectAsync(InstanceDescriptor, IReadOnlyList<EndpointDescriptor>, CancellationToken) method
public Task ConnectAsync(InstanceDescriptor instance, IReadOnlyList<EndpointDescriptor> endpoints, CancellationToken cancellationToken)
Connects to the gateway.
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 gateway and registers the instance, its endpoints, schemas and OpenAPI metadata in the HELLO datagram. The whole HELLO must fit one datagram (UdpTransportOptions.MaxDatagramSize); a larger one fails with PayloadTooLargeExceptionbefore anything is sent.
Parameters
instance: The instance descriptor.endpoints: The endpoints to register.schemas: Schema definitions referenced by the endpoints.openApiInfo: OpenAPI metadata for the service.cancellationToken: Cancellation token.
DisconnectAsync() method
public Task DisconnectAsync()
Disconnects from the gateway.
DisposeAsync() method
public ValueTask DisposeAsync()
See IAsyncDisposable.DisposeAsync().
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.
SendHeartbeatAsync(HeartbeatPayload, CancellationToken) method
public Task SendHeartbeatAsync(HeartbeatPayload heartbeat, CancellationToken cancellationToken)
Sends a heartbeat.
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.
UdpTransportClientServiceCollectionExtensions class
public static class UdpTransportClientServiceCollectionExtensions
Extension methods for registering UDP transport services.
AddUdpTransportClient(IServiceCollection, Action<UdpTransportOptions>) extension method
public static IServiceCollection AddUdpTransportClient(this IServiceCollection services, Action<UdpTransportOptions>? configure = null)
Adds UDP transport client services to the service collection.
Parameters
services: The service collection.configure: Optional configuration action.
Returns
The service collection.
UdpTransportOptions class
public sealed class UdpTransportOptions
Options for UDP transport configuration.
UdpTransportOptions() constructor
public UdpTransportOptions()
Creates an instance of UdpTransportOptions.
AllowBroadcast property
public bool AllowBroadcast { get; set; }
Gets or sets whether to allow broadcast.
BindAddress property
public IPAddress BindAddress { get; set; }
Gets or sets the bind address for the server.
DefaultTimeout property
public TimeSpan DefaultTimeout { get; set; }
Gets or sets the default timeout for requests.
Host property
public string? Host { get; set; }
Gets or sets the host to connect to (client only).
MaxDatagramSize property
public int MaxDatagramSize { get; set; }
Gets or sets the maximum datagram size in bytes. Conservative default well under typical MTU of 1500 bytes.
Port property
public int Port { get; set; }
Gets or sets the port to listen on/connect to. Default: TransportDefaultPorts.Udp(5102), the gateway options’ default.
ReceiveBufferSize property
public int ReceiveBufferSize { get; set; }
Gets or sets the receive buffer size.
SendBufferSize property
public int SendBufferSize { get; set; }
Gets or sets the send buffer size.
UdpTransportPlugin class
public sealed class UdpTransportPlugin : IRouterTransportPlugin
Plugin for the client side of the UDP transport, which a microservice connects with. The server side is UdpTransportServerPlugin in StellaOps.Router.Transport.Udp.Server; both carry the transport name udp.
UdpTransportPlugin() constructor
public UdpTransportPlugin()
Creates an instance of UdpTransportPlugin.
AllowInsecureTransportsEnvVar constant
public const string AllowInsecureTransportsEnvVar = "STELLAOPS_ROUTER_ALLOW_INSECURE_TRANSPORTS"
Environment variable that enables loading the UDP transport plugin. UDP is unencrypted, unauthenticated, and unordered at the network layer; the runtime guard refuses to register the plugin unless the operator explicitly opts in.
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.
IsInsecureTransportsAllowed() method
public static bool IsInsecureTransportsAllowed()
Returns true when UdpTransportPlugin.AllowInsecureTransportsEnvVaris set to a truthy value (case-insensitive: true, 1, yes).
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.
RegisterShared(RouterTransportRegistrationContext, Type) method
public static void RegisterShared(RouterTransportRegistrationContext context, Type loggerCategory)
The registration the client and the server plugin of the UDP transport share: the insecure-transport guard (UdpTransportPlugin.AllowInsecureTransportsEnvVar) and the UdpTransportOptionsbinding of the context’s configuration section (Router:Transport:Udp when the context names none). Both plugins call it from UdpTransportPlugin.Register(RouterTransportRegistrationContext); a plugin for either side of the transport calls it the same way.
Parameters
context: The registration context of the plugin.loggerCategory: The logger category of the warning written when the guard is open.
Exceptions
InvalidOperationException: The insecure-transport guard is closed.
