RustProxy/docs/STREAMS.md

TCP/UDP streams

RustProxy 0.13.0 exposes raw Layer-4 forwarding on the main Streams page, alongside Vhosts and Redirects. A stream combines one dedicated TCP or UDP listener with one upstream. Stream traffic does not enter the HTTP pipeline: no HTTP vhost routing, ACL, cache, headers, compression, Tinyauth or TLS termination is applied.

Dashboard workflow

Use Streams > New stream or Add TCP/UDP listener. The modal mirrors the Vhost workflow and contains Details, Listener & upstream, and Limits tabs. Existing streams are shown as searchable cards with live runtime counters and RX/TX rate charts.

A saved listener change is desired state only until RustProxy restarts. The page keeps the active startup listener visible and marks changed/new/removed stream configuration as pending restart.

The HTTP/HTTPS listener editor remains under Settings > Listeners. Its bind addresses use the same chip-style interaction as vhost hostnames. Those named HTTP/HTTPS listeners are separate from stream listeners.

Configuration document

{
  "streams": [
    {
      "id": "ssh",
      "name": "SSH relay",
      "enabled": true,
      "protocol": "tcp",
      "listen": "0.0.0.0:2222",
      "upstream": "10.0.0.20:22",
      "connect_timeout_seconds": 5,
      "idle_timeout_seconds": 300,
      "max_connections": 512
    },
    {
      "id": "dns-udp",
      "name": "DNS UDP",
      "enabled": true,
      "protocol": "udp",
      "listen": "0.0.0.0:5353",
      "upstream": "10.0.0.53:53",
      "connect_timeout_seconds": 5,
      "idle_timeout_seconds": 30,
      "max_connections": 2048
    }
  ]
}

TCP uses a bidirectional byte relay with a connect timeout, inactivity timeout and connection limit. UDP creates a bounded per-client session mapped to one connected upstream socket, expires it after inactivity and limits concurrent sessions.

Runtime telemetry

The administration status snapshot exposes fixed-cardinality metrics for active startup streams. The Streams page displays:

• active TCP connections or UDP client sessions;
• accepted connections/sessions and completed sessions;
• capacity rejects and relay/upstream errors;
• bytes received from clients and returned from upstreams;
• UDP packet counters;
• live RX/TX rates derived from monotonic backend byte counters.

The chart history exists only in the current browser panel session. Backend counters are process-lifetime counters and reset on process restart.

Listener safety

RustProxy validates collisions before publishing configuration. TCP stream listeners may not overlap HTTP/TLS, administration or Prometheus TCP listeners. UDP stream listeners may not overlap HTTP/3 UDP listeners. TCP and UDP may intentionally use the same numeric port because they are different transports. Direct loops into another RustProxy listener of the same transport are rejected.