Logo
Go SDK

Go SDK

Integrate rstream tunnels, runtime agents, and engine APIs from Go.

Written by uartnet

@uartnet

The Go SDK is the reference SDK for rstream. It covers tunnel creation, published HTTP services, private bytestream and datagram dialing, HTTP/3 tunnel runtimes, WebTransport, CONNECT, CONNECT-UDP, CONNECT-IP, transport policy, engine inventory, watch streams, TURN helpers, and managed Control plane calls.

github.com/rstreamlabs/rstream-goReference Go SDK and CLI implementation for tunnel runtime integrations.

Use this page as the entrypoint. The detailed references are split by concern.

PageUse it for
Tunnel RuntimeCreating tunnels, serving HTTP with net/http, WebTransport, MASQUE protocols, and dialing private tunnels.
Transport, Proxy, and DNSControlling how the agent reaches the engine, including QUIC transport, HTTP CONNECT proxies, MASQUE CONNECT-UDP proxies, SOCKS5, custom DNS, DNS over TLS, DNSSEC, and ECH discovery.
Engine and Control PlaneListing tunnels and clients, watching events, creating TURN credentials, and calling hosted Control plane APIs.

Install

go get github.com/rstreamlabs/rstream-go

Most applications should use the config bridge so Go code and CLI workflows resolve the same selected project, engine, token, mTLS credentials, and transport settings.

client, err := config.NewClientFromEnv()
if err != nil {
  log.Fatal(err)
}

config.NewClientFromEnv() reads explicit options first, then environment variables, then the selected context from ~/.rstream/config.yaml.

When the engine and token are already known, create the client directly.

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)
}

Core Runtime Shape

The runtime path starts with an authenticated control channel, then creates or dials tunnels.

ctrl, err := client.Connect(ctx, nil)
if err != nil {
  log.Fatal(err)
}
defer ctrl.Close()
 
tunnel, err := ctrl.CreateTunnel(ctx, rstream.TunnelProperties{
  Name:        rstream.StringPtr("api"),
  Publish:     rstream.BoolPtr(true),
  Protocol:    rstream.ProtocolPtr(rstream.ProtocolHTTP),
  HTTPVersion: rstream.HTTPVersionPtr(rstream.HTTP1_1),
})
if err != nil {
  log.Fatal(err)
}
defer tunnel.Close()

Published tunnels expose a forwarding address through the edge. Private tunnels are dialed by id or name through the SDK and do not create a public endpoint.

conn, err := client.Dial(ctx, rstream.Addr{IdOrName: "private-api"})
if err != nil {
  log.Fatal(err)
}
defer conn.Close()

See Tunnel Runtime for the complete HTTP, WebTransport, MASQUE, bytestream, and datagram patterns.

Transport Policy

Transport settings are separate from tunnel properties. They describe how the Go process reaches the engine, while tunnel properties describe what the engine exposes after the agent is connected.

client := &rstream.Client{
  EngineURL: "project-endpoint.cluster.example.rstream.test:443",
  Token:     os.Getenv("RSTREAM_AUTHENTICATION_TOKEN"),
  Transport: &rstream.Transport{
    ProxyHTTP:     rstream.StringPtr("http://proxy.corp:3128"),
    ProxyUsername: rstream.StringPtr("agent"),
    ProxyPassword: rstream.StringPtr(os.Getenv("PROXY_PASSWORD")),
  },
}

The Go SDK supports TCP/TLS through HTTP CONNECT, QUIC transport through HTTPS MASQUE CONNECT-UDP, TCP/TLS through SOCKS5 CONNECT, and QUIC transport through SOCKS5 UDP ASSOCIATE. See Transport, Proxy, and DNS for the full matrix and DNS behavior.

Examples

The repository includes examples for HTTP tunnel servers built on net/http, private stream clients, datagram clients, WebTransport, plain CONNECT, CONNECT-UDP, CONNECT-IP, SCTP over datagram tunnels, TURN credential creation, and Control plane API usage.

git clone https://github.com/rstreamlabs/rstream-go.git
cd rstream-go
make examples
STUN and TURNTunnel Runtime