Transports

A transport carries requests and responses between the gateway and the microservices. Each transport has a server half in the gateway and a client half in each service, in separate packages. The gateway can offer several transports at once; each service uses one.

TransportServer package (gateway)Client package (service)EncryptedInsecure switch needed
TCPStellaOps.Router.Transport.Tcp.ServerStellaOps.Router.Transport.TcpNoYes
TLSStellaOps.Router.Transport.Tls.ServerStellaOps.Router.Transport.TlsYes, TLS 1.2 or 1.3No
UDPStellaOps.Router.Transport.Udp.ServerStellaOps.Router.Transport.UdpNoYes
RabbitMQStellaOps.Router.Transport.RabbitMq.ServerStellaOps.Router.Transport.RabbitMqWhen the broker uses TLSNo
Messaging (Valkey)StellaOps.Router.Transport.Messaging.ServerStellaOps.Router.Transport.Messaging with StellaOps.Messaging.Transport.ValkeyWhen Valkey uses TLSNo
InMemoryStellaOps.Router.Transport.InMemory (both halves)the sameNot applicableNo

The server packages are under the Router licence; the client packages are Apache-2.0.

On every transport the client half runs each request it receives as soon as it arrives, so one connection serves several requests at the same time; only Messaging limits how many (MaxConcurrentRequests). When a caller disconnects or an endpoint timeout expires, the gateway sends a cancel frame with the request’s correlation id and the endpoint’s CancellationToken is cancelled; Messaging delivers it only with frame protection.

Choosing a transport

SituationTransport
Development on one machineTCP, or InMemory in tests
Production across a networkTLS, with client certificates where services and gateway belong to different teams
Services and gateway already share a RabbitMQ brokerRabbitMQ
Services and gateway already share a Valkey server, or must not open connections to the gateway hostMessaging over Valkey
Small, frequent requests on a trusted network, loss acceptableUDP

The running samples use TCP and InMemory. The other registrations on this page are compiled before each release (Examples.Transports) but not run, because they need certificates or servers.

Each request and each response travels in one frame, and the gateway and the service hold it in memory. The largest body each transport carries:

TransportLargest bodySetting
TCP, TLSAbout 12 MiB (a 16 MiB frame; the body travels Base64-encoded)MaxFrameSize on both sides
UDPOne datagram, 8192 bytes for the whole frameMaxDatagramSize on both sides
RabbitMQAbout 12 MiB (a 16 MiB message by default; the body travels Base64-encoded)MaxMessageSize on both sides, at most the broker’s max_message_size
MessagingNo limit of its own

A larger request is answered 413, a larger response 502 Response too large (File uploads and downloads).

The insecure-transport switch

TCP and UDP send frames unencrypted. Both halves refuse to register unless the process environment variable STELLAOPS_ROUTER_ALLOW_INSECURE_TRANSPORTS is true, yes or 1. It is an environment variable, not a configuration key, and it affects only TCP and UDP. Set it for development and for networks you trust completely; use TLS everywhere else.

Configuring the gateway side

The gateway host reads each transport from Gateway:Transports:<Name> and starts it only when Enabled is true. Pass the server assemblies to AddRouterGatewayHost (a custom host), or use the .NET tool, which has them all (Router gateway host).

Without Port, a listener uses its transport’s default: TCP 9100, TLS 9443, UDP 5102. A transport client without Port connects to the same default.

Time spans in the transport sections use .NET syntax: 00:00:10 is ten seconds. A bare number is a number of days.

TCP

{
  "Gateway": {
    "Transports": {
      "Tcp": { "Enabled": true, "BindAddress": "0.0.0.0", "Port": 9100 }
    }
  }
}

The service side is the getting-started registration: AddTcpTransportClient with Host and Port.

TLS, mTLS and certificate pinning

Gateway side:

{
  "Gateway": {
    "Transports": {
      "Tls": {
        "Enabled": true,
        "Port": 9443,
        "ServerCertificatePath": "/etc/router/tls/gateway.crt",
        "ServerCertificateKeyPath": "/etc/router/tls/gateway.key",
        "RequireClientCertificate": true,
        "EnabledProtocols": "Tls13"
      }
    }
  }
}

Service side, with a client certificate and the gateway’s certificate pinned:

// TLS with a client certificate (mTLS) and the gateway certificate pinned by SHA-256 thumbprint.
services.AddTlsTransportClient(options =>
{
    options.Host = "gateway.contoso.example";
    options.Port = 9443;
    options.ExpectedServerHostname = "gateway.contoso.example";
    options.ClientCertificatePath = "/etc/contoso/billing/client.pfx";
    options.ClientCertificatePassword = Environment.GetEnvironmentVariable("BILLING_CLIENT_CERT_PASSWORD");
    options.EnabledProtocols = SslProtocols.Tls13;
    options.CertificatePinning = new CertificatePinningOptions
    {
        ThumbprintsSha256 = ["9F2D6C4E7A1B3D5F8E0A2C4B6D8F1A3C5E7B9D0F2A4C6E8B1D3F5A7C9E0B2D4F"]
    };
});

Certificate validation, on both sides:

  1. A certificate is required when the other side requires it.
  2. The host name must match. ExpectedServerHostname is the name the service expects (and sends as SNI); without it, Host is used.
  3. A chain error rejects the certificate, unless AllowSelfSigned is true, the only error is an untrusted root or a partial chain, and the certificate matches a pin.
  4. Pins: CertificatePinning.ThumbprintsSha256 (hex SHA-256 of the certificate), AllowedSubjects (exact subject) and AllowedSans (exact DNS names). AllowSelfSigned requires at least one pin.

Rejections are counted in the instrument router_tls_validate_rejected_total of the .NET meter StellaOps.Router.Transport.Tls; collect it with an OpenTelemetry exporter, because the gateway’s /metrics does not include it.

UDP

{
  "Gateway": {
    "Transports": {
      "Udp": { "Enabled": true, "Port": 5102, "MaxDatagramSize": 8192 }
    }
  }
}
// UDP: unencrypted, one datagram per frame; needs STELLAOPS_ROUTER_ALLOW_INSECURE_TRANSPORTS=true.
services.AddUdpTransportClient(options =>
{
    options.Host = "127.0.0.1";
    options.Port = 5102;
    options.MaxDatagramSize = 8192;
});

A frame must fit in one datagram, so UDP suits small requests and responses only.

RabbitMQ

{
  "Gateway": {
    "Transports": {
      "RabbitMq": {
        "Enabled": true,
        "HostName": "rabbitmq.contoso.example",
        "Port": 5671,
        "UseSsl": true,
        "VirtualHost": "/router",
        "NodeId": "gw-eu1"
      }
    }
  }
}
// RabbitMQ: NodeId must equal the gateway's Gateway:Transports:RabbitMq:NodeId.
services.AddRabbitMqTransportClient(options =>
{
    options.HostName = "rabbitmq.contoso.example";
    options.Port = 5671;
    options.UseSsl = true;
    options.VirtualHost = "/router";
    options.UserName = "billing";
    options.Password = Environment.GetEnvironmentVariable("BILLING_RABBITMQ_PASSWORD") ?? string.Empty;
    options.NodeId = "gw-eu1";
    options.DurableQueues = true;
});

Messaging over Valkey

{
  "Gateway": {
    "Transports": {
      "Messaging": {
        "Enabled": true,
        "valkey": { "ConnectionString": "valkey.contoso.example:6379,ssl=true" }
      }
    }
  }
}

Service side; the Valkey backend reads Router:Transport:Messaging:valkey:ConnectionString from the service’s configuration:

// Messaging over Valkey: the Valkey backend reads Router:Transport:Messaging:valkey:ConnectionString,
// and the queue names must equal the gateway's (the defaults below are the gateway's defaults).
services.AddMessagingTransport<ValkeyTransportPlugin>(configuration, "Router:Transport:Messaging");
services.AddMessagingTransportClient(options =>
{
    options.RequestQueueTemplate = "router:requests:{service}";
    options.ResponseQueueName = "router:responses";
});

InMemory

Gateway and service in one process share an InMemoryConnectionRegistry. Use it in tests (Testing with the in-memory harness).

Connection behaviour by transport

TCP and TLS clients

OptionDefaultMeaning
ConnectTimeout10 secondsHow long one connection attempt may take.
MaxReconnectAttempts10Reconnection attempts the client makes on its own after a connection drops.
MaxReconnectBackoff1 minuteThe longest wait between two of those attempts. The wait doubles from 200 milliseconds.
KeepAliveInterval30 secondsTCP keep-alive on the connection, on the service and on the gateway: after this long without traffic the system probes the other side, and closes the connection after three unanswered probes, so a host that vanished is noticed. Zero turns it off.
ClientCertificateKeyPath (TLS)noneThe private key file of a PEM client certificate.
ClientCertificate, ServerCertificate (TLS, in code)noneCertificate objects instead of file paths.

After a connection drops, the client reconnects on its own and sends its HELLO again. When all MaxReconnectAttempts fail (about 2.7 minutes with the defaults), it logs Max reconnection attempts (N) reached; reporting the transport as dead so the service connects again, and the service connects again with the SDK’s ReconnectBackoffInitial and ReconnectBackoffMax until the gateway answers. A gateway outage of any length therefore ends with the service registered again, without a restart. A TLS authentication error on an open connection is handled the same way, with a new handshake.

TLS, both sides:

UDP limits

RabbitMQ delivery

OptionDefaultMeaning
SslCertPathnoneA client certificate for the broker, with UseSsl.
InstanceIdthe SDK’s instance idThe instance part of the service’s queue name.
AutomaticRecoveryEnabledtrueThe client library reconnects to the broker after a network failure.
NetworkRecoveryInterval5 secondsThe wait between two recovery attempts.
DefaultTimeout30 secondsHow long a request or response message may wait in its queue.

Messages are not persistent and are delivered at most once: a message that waits in its queue longer than DefaultTimeout, or is lost with a broker restart, is not delivered, and the caller gets the endpoint’s 504 when its timeout expires.

Messaging delivery

Frame protection for queue transports

RabbitMQ and Messaging carry frames through a broker that other systems may read. Frames are signed and verified when the root configuration section Router:Frame:Envelope exists:

KeyMeaning
Router:Frame:Envelope:ActiveKeyIdThe key that signs new frames (default primary).
Router:Frame:Envelope:Keys:<id>A secret per key id; at least one.
Router:Frame:Envelope:ReplayWindowHow long a frame is accepted (default 5 minutes).

A section that is present but incomplete stops start-up with Router frame-envelope protection requires ...: an empty ActiveKeyId, no key, an ActiveKeyId that names no key, an empty key, or a ReplayWindow of zero or less.

The gateway host reads the section itself. In a service, Add*TransportClient does not; register the protection as well, with the same keys:

// RabbitMQ and Messaging: protect frames with the keys under Router:Frame:Envelope, the same keys
// as the gateway's. Without that section the call registers nothing.
services.AddConfiguredFrameEnvelopeProtection(configuration);

Supply the secrets from your secret store, never from a committed file. The samples do not run a queue transport, so this pairing is compiled before each release but not run.

Pitfalls