# 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

```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

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

### Environment Variables

```bash
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](./tls.md).

## 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
```

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

### Connection Timeout

```
Error: Connection to gateway.internal:5100 timed out
```

1. Increase `ConnectTimeout` value
2. Check network connectivity between services
3. Verify no network segmentation blocking traffic

### Performance Issues

1. Enable `NoDelay: true` for latency-sensitive workloads
2. Tune buffer sizes based on payload sizes
3. Monitor connection pool exhaustion

## See Also

- [TLS Transport](./tls.md) - Encrypted variant
- [Transport Overview](./README.md)
- [Router Architecture](../ARCHITECTURE.md)