TCP Transport

Reliable, connection-oriented transport protocol implementation.

TCP is the preferred transport when reliability, ordering, and flow control are required. MapsMessaging uses TCP for stateful, long-lived client connections and high-integrity data exchange.

---

Features

• Connection-oriented transport
• Reliable, ordered delivery
• Flow control and congestion handling
• Configurable socket buffers
• Fragmentation detection and mitigation
• Proxy Protocol support (optional)

---

When to Use TCP

TCP is recommended when:

• Message delivery must be reliable
• Ordering matters
• Clients maintain long-lived sessions
• Backpressure handling is required
• Security is enforced at the transport or protocol layer

If ultra-low latency or fire-and-forget semantics are required, consider UDP instead.

---

Basic Configuration

transport:
  tcp:
    type: tcp
    port: 1883
    backlog: 100

---

TCP-specific Configuration

transport:
  tcp:
    type: tcp
    port: 1883

    receiveBufferSize: 128000
    sendBufferSize: 128000
    timeout: 60000
    backlog: 100

    soLingerDelaySec: 10

    readDelayOnFragmentation: 100
    fragmentationLimit: 5
    enableReadDelayOnFragmentation: true

Fields

Field	Description
receiveBufferSize	Socket receive buffer size in bytes
sendBufferSize	Socket send buffer size in bytes
timeout	Connection timeout in milliseconds
backlog	Maximum queued incoming connections
soLingerDelaySec	SO_LINGER delay in seconds (0 disables linger)
readDelayOnFragmentation	Delay applied when packet fragmentation is detected (ms)
fragmentationLimit	Maximum fragmentation events before backoff logic is applied
enableReadDelayOnFragmentation	Enable read delay on fragmentation detection

---

Fragmentation Handling

TCP fragmentation can occur when clients send partial frames or deliberately fragment data. MapsMessaging detects excessive fragmentation and applies adaptive backoff.

Behaviour

• Fragmentation is tracked per connection
• Read delays are introduced once the fragmentation limit is exceeded
• Protects the server against slow-loris style attacks
• Backoff logic is configurable

enableReadDelayOnFragmentation: true
fragmentationLimit: 5
readDelayOnFragmentation: 100

---

Common Endpoint Fields

TCP endpoints inherit common settings from EndPointConfigDTO.

transport:
  tcp:
    type: tcp
    port: 1883

    discoverable: false
    selectorThreadCount: 2
    serverReadBufferSize: 10240
    serverWriteBufferSize: 10240

    proxyProtocolMode: DISABLED
    allowedProxyHosts: ""
    connectionTimeout: 5000

Fields

Field	Description
discoverable	Whether the endpoint is discoverable
selectorThreadCount	Number of selector threads
serverReadBufferSize	Server read buffer size in bytes
serverWriteBufferSize	Server write buffer size in bytes
proxyProtocolMode	Proxy Protocol support mode (DISABLED, ENABLED, REQUIRED)
allowedProxyHosts	Allowed proxy source addresses (hosts, IPs, CIDR)
connectionTimeout	Time to wait for a client to establish the connection (ms)

---

Security Notes

• TCP provides reliable delivery but not encryption
• Use TLS (ssl endpoint) if encryption is required
• Fragmentation controls mitigate resource exhaustion attacks
• Proxy Protocol should only be enabled when required and restricted by source

---

Operational Notes

• Larger buffer sizes improve throughput at the cost of memory
• Smaller buffers reduce memory footprint but may limit throughput
• Backlog tuning is important for bursty connection patterns
• Fragmentation detection protects server resources under attack

---

When NOT to Use TCP

Avoid TCP when:

• Messages are small and infrequent
• Latency is more important than reliability
• Multicast or broadcast semantics are required

Choose the transport that matches the workload.