Go SDK

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.

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

SDK Surface

Install

go get github.com/rstreamlabs/rstream-go

The repository also provides a separate Go 1.27 FIPS build profile. It embeds a validated Go Cryptographic Module and restricts the SDK and CLI to the reviewed network paths. See FIPS 140-3 Profiles for build commands, supported operations, and exclusions.

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. Standard builds also support external mTLS signers through auth.mtls.storage.kind: exec, including HSMs with vendor APIs. The same context works in the CLI without embedding vendor dependencies in rstream.

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.

Diagnostics inside a Go application

The public github.com/rstreamlabs/rstream-go/doctor package runs the same checks as rstream doctor and returns typed results without invoking the CLI. Resolve configuration explicitly, or reuse a config.Resolved already owned by your application:

resolution, err := config.ResolveFromEnv(config.ClientEnvOptions{
  Context: "production",
})
if err != nil {
  return err
}
ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
defer cancel()
report, diagnosticErr := doctor.Run(ctx, resolution.Resolved, doctor.Options{})
for _, check := range report.Checks {
  fmt.Printf("%s: %s: %s\n", check.Name, check.Status, check.Message)
}
return diagnosticErr

Import config and doctor from github.com/rstreamlabs/rstream-go/config and github.com/rstreamlabs/rstream-go/doctor, plus the standard context, fmt and time packages for this example. The application decides how to handle diagnosticErr and present the report; doctor.Run itself writes no formatted output and does not load CLI configuration or credentials from the environment.

The report contains checks, details, aggregate counts and a timestamp. Statuses are doctor.StatusPass, StatusWarn, StatusFail and StatusSkip. It can be serialized directly with encoding/json, using the same diagnostic fields as the CLI. errors.Is(diagnosticErr, doctor.ErrChecksFailed) identifies failed checks; warnings alone do not fail the run. Cancellation and deadlines preserve context.Canceled and context.DeadlineExceeded through errors.Is, and the partial report remains available. The CLI adds its own config-loading check and config-path metadata around these shared results.

Pass doctor.Options{Deep: true} to create and close a temporary tunnel as an additional check. This is disabled by default and retains the published HTTP fallback when private tunnels are unavailable. Each probe has a bounded timeout; the context sets a budget for the whole run. Diagnostics close their own clients and probe resources and leave caller-owned transports open. Keep the supplied configuration immutable while a run uses it.

Token authentication, regional routing, Control plane headers, transport policy and mTLS (including external signers) use the existing SDK configuration. The restricted FIPS build validates its cryptographic runtime before diagnostics. For certificate-only contexts, HTTP checks use the discovered Engine API. Restricted health or inventory permissions produce warnings; when health access is denied, readiness remains unverified. Diagnostics do not issue TURN credentials. See the Go diagnostic API reference for the complete contract and lifecycle 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