Stream Routes

Stream routes enable API7 Gateway to proxy Layer 4 (L4) traffic — TCP and UDP connections — in addition to the standard Layer 7 (HTTP/HTTPS) traffic handled by regular routes. This allows you to use API7 Gateway as a unified proxy for both HTTP APIs and non-HTTP protocols such as databases, message queues, and custom TCP services.

How Stream Routes Work

Unlike HTTP routes that match on URI paths, HTTP methods, and headers, stream routes match on network-layer attributes:

Match Field	Description	Example
remote_addr	Client IP address or CIDR range	10.0.0.0/8
server_addr	Gateway listening IP address	192.168.1.100
server_port	Gateway listening port	3306
sni	TLS Server Name Indication (for TLS streams)	db.example.com

All specified match fields are evaluated with AND logic. If no match fields are specified, the stream route matches all traffic on the configured stream proxy ports.

Request Flow

1. A TCP or UDP client connects to one of the gateway's configured stream_proxy ports.
2. The gateway evaluates all stream routes against the connection's network attributes.
3. The matching stream route determines the upstream, and the connection is proxied to the upstream service.

Stream Services

Stream routes must belong to a stream-type service (service with type: stream). A stream service cannot contain regular HTTP routes, and an HTTP service cannot contain stream routes.

Stream services share the same lifecycle as HTTP services:

• Service templates with versioning
• Publishing to gateway groups
• Upstream inheritance (stream routes inherit upstream configuration from their parent service unless overridden)

Supported Plugins

Only a subset of plugins support the stream (L4) context:

Plugin	Category	Description
ip-restriction	Security	Allow/deny traffic based on client IP
limit-conn	Traffic	Limit concurrent connections
mqtt-proxy	Protocol	MQTT protocol proxy and routing
traffic-split	Traffic	Split traffic across upstreams by weight
prometheus	Observability	Expose stream metrics
syslog	Observability	Log stream events to syslog

HTTP-only plugins (such as key-auth, proxy-rewrite, or response-rewrite) cannot be applied to stream routes.

Enabling Stream Proxy

Before using stream routes, you must configure the gateway to listen on TCP and/or UDP ports for stream traffic. This is done in the gateway's config.yaml:

apisix:
  stream_proxy:
    tcp:
      - addr: 9100          # Listen on all interfaces, port 9100
      - addr: "127.0.0.1:9101"  # Listen on specific IP
        tls: true            # Enable TLS on this port
    udp:
      - 9200                 # Listen on all interfaces, port 9200

info

Stream proxy ports are separate from the HTTP proxy ports (node_listen / ssl.listen). Clients connect to stream proxy ports for L4 traffic and to HTTP ports for L7 traffic.

Stream Routes vs. HTTP Routes

Aspect	HTTP Routes	Stream Routes
Protocol	HTTP, HTTPS, gRPC, WebSocket	TCP, UDP
Match criteria	URI, host, headers, methods, expressions	Client IP, server IP, server port, SNI
Service type	http	stream
Plugin support	Full plugin library	6 stream-compatible plugins
Routing algorithm	Radix tree on URI	Sequential match on IP/port (radix tree on SNI for TLS)

Next Steps

• TCP/UDP Proxy: Step-by-step guide to proxy TCP and UDP traffic.
• Services and Routes: Learn about HTTP services and routes.
• Plugins: Overview of the plugin system.