Go SDK Transport, Proxy, and DNS

Transport settings control how a Go process reaches the rstream engine. They do not change what a tunnel publishes. A published HTTP tunnel, a private TCP tunnel, and a datagram tunnel can all use the same agent transport policy.

Automatic Transport Selection

The default transport is auto. It prefers QUIC, starts TLS after a brief head start when necessary, and keeps the first successful choice for the client lifetime.

client, err := rstream.NewClient(rstream.ClientOptions{
  Engine: "project-endpoint.cluster.example.rstream.test:443",
  Token:  os.Getenv("RSTREAM_AUTHENTICATION_TOKEN"),
})
if err != nil {
  log.Fatal(err)
}

Selection happens while the client opens its control channel. It is not repeated for every tunnel stream or datagram session. Authentication and protocol errors after a transport has connected do not trigger fallback. Construct a new client to select again.

Use Transport directly when TLS is mandatory:

Bind options can pin the local source address or constrain the address family.

client := &rstream.Client{
  EngineURL: "project-endpoint.cluster.example.rstream.test:443",
  Token:     os.Getenv("RSTREAM_AUTHENTICATION_TOKEN"),
  Transport: &rstream.Transport{
    LocalAddr: rstream.StringPtr("10.10.0.25"),
    ForceIPv4: rstream.BoolPtr(true),
  },
}

MPTCPEnabled can be enabled for TCP paths when the host and network support Multipath TCP.

QUIC Transport

QUICTransport uses one QUIC connection for SDK-to-engine streams and datagrams. Select it directly in code when QUIC is mandatory and fallback is not desired.

client := &rstream.Client{
  EngineURL: "project-endpoint.cluster.example.rstream.test:443",
  Token:     os.Getenv("RSTREAM_AUTHENTICATION_TOKEN"),
  Transport: &rstream.QUICTransport{},
}

The config bridge accepts auto, tls, or quic through RSTREAM_TUNNEL_TRANSPORT, or through YAML with transport.mode.

contexts:
  - name: lab
    engine: project-endpoint.cluster.example.rstream.test:443
    transport:
      mode: auto

QUICTransport is stateful. Keep one instance for the lifetime of the client and create a fresh instance after a connection failure.

Proxy Support Matrix

The Go SDK supports proxying the agent-to-engine session for both TCP/TLS and QUIC transports.

Configure only one proxy type at a time. The SDK rejects configurations that set both proxy.http and proxy.socks5.

HTTPS and MASQUE proxy TLS uses the system trust store by default. If the proxy is issued by a private corporate CA, add that CA to the proxy TLS block. This verifies the proxy hop without changing the end-to-end TLS session between the SDK and the rstream engine.

contexts:
  - name: corp-masque
    engine: project-endpoint.cluster.example.rstream.test:443
    transport:
      mode: quic
      proxy:
        http: https://masque-proxy.corp
        tls:
          caFile: /etc/rstream/proxy-ca.pem
          serverName: masque-proxy.corp
          insecureSkipVerify: false

The proxy TLS block follows the standard TLS client shape. caFile adds a PEM trust bundle for the proxy certificate, serverName overrides the proxy SNI and certificate verification name, and insecureSkipVerify disables proxy certificate verification for controlled diagnostics.

proxy.fromEnvironment: true reads the process proxy environment when neither proxy.http nor proxy.socks5 is set. The lookup honors HTTPS_PROXY, HTTP_PROXY, ALL_PROXY, and NO_PROXY in upper- and lower-case forms. HTTP and HTTPS proxy URLs become HTTP proxy transport settings, while socks5:// and socks5h:// become SOCKS5 proxy settings.

contexts:
  - name: corp-env
    engine: project-endpoint.cluster.example.rstream.test:443
    transport:
      proxy:
        fromEnvironment: true

The Go SDK does not read desktop proxy preferences directly from macOS System Settings, Windows Internet Options, or similar GUI stores. Agents and services should receive deterministic process environment variables or explicit YAML transport settings.

HTTP CONNECT Proxy for TCP/TLS

Use proxy.http when a network requires outbound TCP through an HTTP proxy.

contexts:
  - name: corp
    engine: project-endpoint.cluster.example.rstream.test:443
    transport:
      proxy:
        http: http://proxy.corp:3128
        username: agent
        password: "<proxy-password>"
        headers:
          X-Company: acme

In Go code, the equivalent configuration is explicit on rstream.Transport.

transport := &rstream.Transport{
  ProxyHTTP:     rstream.StringPtr("http://proxy.corp:3128"),
  ProxyUsername: rstream.StringPtr("agent"),
  ProxyPassword: rstream.StringPtr(os.Getenv("PROXY_PASSWORD")),
  ProxyHTTPHeaders: map[string]string{
    "X-Company": "acme",
  },
}

The HTTP proxy sees the CONNECT target authority. The rstream TLS session is negotiated through that TCP tunnel and remains end to end between the SDK and the engine.

MASQUE Proxy for QUIC Transport

QUIC transport cannot use classic HTTP CONNECT because QUIC runs over UDP. When QUICTransport is combined with proxy.http, the SDK uses HTTPS MASQUE CONNECT-UDP.

contexts:
  - name: masque
    engine: project-endpoint.cluster.example.rstream.test:443
    transport:
      mode: quic
      proxy:
        http: https://masque-proxy.corp

The default MASQUE URI template expands to the standard well-known CONNECT-UDP route.

https://masque-proxy.corp:443/.well-known/masque/udp/{target_host}/{target_port}/

Use a custom template when the proxy publishes a different route.

transport:
  mode: quic
  proxy:
    http: https://masque-proxy.corp/connect-udp/{target_host}/{target_port}

proxy.username, proxy.password, and proxy.headers apply to HTTP CONNECT proxy paths. For QUIC over MASQUE, authenticate the proxy endpoint at the MASQUE layer or with the deployment policy provided by that proxy.

SOCKS5 Proxy

Use proxy.socks5 when a SOCKS5 proxy is the approved egress path.

contexts:
  - name: socks
    engine: project-endpoint.cluster.example.rstream.test:443
    transport:
      proxy:
        socks5: socks5://proxy.corp:1080
        username: agent
        password: "<proxy-password>"

The same proxy.socks5 setting works with transport.mode: quic. TCP/TLS uses SOCKS5 CONNECT. QUIC uses SOCKS5 UDP ASSOCIATE.

contexts:
  - name: socks-quic
    engine: project-endpoint.cluster.example.rstream.test:443
    transport:
      mode: quic
      proxy:
        socks5: socks5://proxy.corp:1080

HTTP proxy headers do not apply to SOCKS5.

DNS Behavior

With no custom DNS settings, proxied target resolution stays with the proxy whenever the proxy protocol supports it. HTTP CONNECT, MASQUE CONNECT-UDP, and SOCKS5 can receive the engine hostname and resolve it from the proxy side.

When transport.dns is configured, the SDK intentionally resolves the engine name before opening the proxied connection and sends the selected IP address to the proxy. This is the correct mode when the client must use a dedicated resolver, DNS over TLS, DNSSEC validation, or a resolver reachable through a specific local route.

transport:
  dns:
    override: 1.1.1.1:853
    tls: true
    serverName: cloudflare-dns.com
    dnssec: true

The same DNS policy is used for direct engine hostname resolution and for ECH discovery through DNS SVCB and HTTPS records. Without explicit DNS settings, the SDK uses the platform resolver configuration. On macOS, scoped per-domain resolvers from the system DNS state are respected.

Bind and address-family settings apply to the local side of the selected path. With a proxy, that means the TCP or UDP socket opened toward the proxy is bound or constrained; with custom DNS, the SDK resolves the engine hostname first and sends the selected IP address through the proxy protocol.

Environment Variables

The config bridge reads the same core environment variables as the CLI.

Token authentication and mTLS agent authentication are mutually exclusive for the control-channel connection. When both mTLS variables are set, the SDK authenticates that connection with the client certificate and does not use a stored context token.