TCP Transport

The TCP transport provides high-performance binary communication for internal microservices within the same datacenter or trusted network.

Overview

Property	Value
Plugin Assembly	`StellaOps.Router.Transport.Tcp.dll`
Transport Name	`tcp`
Default Port	5100
Security	Network isolation (no encryption)
Use Case	Internal services, low-latency communication

Configuration

router.yaml

Router:
  Transport:
    Type: tcp
    Tcp:
      Host: "0.0.0.0"
      Port: 5100
      MaxConnections: 1000
      ReceiveBufferSize: 65536
      SendBufferSize: 65536
      KeepAlive: true
      NoDelay: true

microservice.yaml

routers:
  - host: gateway.internal
    port: 5100
    transportType: Tcp
    priority: 1

Environment Variables

ROUTER__TRANSPORT__TYPE=tcp
ROUTER__TRANSPORT__TCP__HOST=0.0.0.0
ROUTER__TRANSPORT__TCP__PORT=5100
ROUTER__TRANSPORT__TCP__MAXCONNECTIONS=1000

Options Reference

Option	Type	Default	Description
`Host`	string	`0.0.0.0`	Bind address for server
`Port`	int	`5100`	TCP port number
`MaxConnections`	int	`1000`	Maximum concurrent connections
`ReceiveBufferSize`	int	`65536`	Socket receive buffer size in bytes
`SendBufferSize`	int	`65536`	Socket send buffer size in bytes
`KeepAlive`	bool	`true`	Enable TCP keep-alive probes
`NoDelay`	bool	`true`	Disable Nagle’s algorithm (lower latency)
`ConnectTimeout`	TimeSpan	`00:00:30`	Connection timeout
`ReadTimeout`	TimeSpan	`00:02:00`	Socket read timeout
`WriteTimeout`	TimeSpan	`00:02:00`	Socket write timeout

Performance Characteristics

Metric	Typical Value
Latency (p50)	< 1ms
Latency (p99)	< 5ms
Throughput	100,000+ rps
Memory per connection	~2KB

Benchmarks on 10Gbps network with small payloads (<1KB)

Security Considerations

TCP transport does not provide encryption. Use only in:

Private networks with proper network segmentation
Same-datacenter deployments with firewalled traffic
Container orchestration networks (Kubernetes pod network)

For encrypted communication, use TLS transport.

Framing Protocol

The TCP transport uses the standard Router binary framing protocol:

┌────────────────────────────────────────────────────────────────┐
│                        Frame Header (24 bytes)                  │
├────────────┬────────────┬────────────┬────────────┬────────────┤
│ Magic (4)  │ Version(2) │ Type (2)   │ Flags (4)  │ Length (8) │
├────────────┴────────────┴────────────┴────────────┴────────────┤
│ Correlation ID (4)                                              │
├─────────────────────────────────────────────────────────────────┤
│                        Frame Payload (variable)                 │
└─────────────────────────────────────────────────────────────────┘

Troubleshooting

Connection Refused

Error: Connection refused to gateway.internal:5100

Verify Gateway is running and listening on port 5100
Check firewall rules allow traffic on port 5100
Verify DNS resolution of hostname

Connection Timeout

Error: Connection to gateway.internal:5100 timed out

Increase ConnectTimeout value
Check network connectivity between services
Verify no network segmentation blocking traffic

Performance Issues

Enable NoDelay: true for latency-sensitive workloads
Tune buffer sizes based on payload sizes
Monitor connection pool exhaustion