StellaOps.Router.Transport.Udp

Router UDP transport, client side: sends the frames of a microservice to a gateway as UDP datagrams.

PackageStellaOps.Router.Transport.Udp
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.Udp5

StellaOps.Router.Transport.Udp namespace

TypeKindDescription
UdpFrameProtocolclassHandles serialization and deserialization of frames for UDP transport.
UdpTransportClientclassUDP transport client implementation for microservices.
UdpTransportClientServiceCollectionExtensionsclassExtension methods for registering UDP transport services.
UdpTransportOptionsclassOptions for UDP transport configuration.
UdpTransportPluginclassPlugin 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

Returns

The parsed frame.

Exceptions

SerializeFrame(Frame) method

public static byte[] SerializeFrame(Frame frame)

Serializes a frame to a datagram.

Parameters

Returns

The serialized datagram bytes.

Exceptions

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

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

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

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

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

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

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

Exceptions

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

Exceptions