Go SDK

The Go SDK is the reference SDK for rstream. It implements the core client, tunnel creation, dialing APIs for bytestream and datagram tunnels, and signaling helpers.

The SDK is suitable for embedding in services and agents that should connect to rstream without a separate CLI process.

Creating a client

A client requires an engine endpoint. Authentication is provided through a token, or the client can run in no-token mode when the engine does not require authentication.

client, err := rstream.NewClient(rstream.ClientOptions{
  Engine: "cluster.example.rstream.io:443",
  Token:  os.Getenv("RSTREAM_AUTHENTICATION_TOKEN"),
})

The config bridge can load engine and token from the same configuration and environment variables used by the CLI:

client, err := config.NewClientFromEnv()

Opening a control channel and creating a tunnel

Tunnel creation happens over a control channel:

ctrl, err := client.Connect(ctx, nil)
tunnel, err := ctrl.CreateTunnel(ctx, rstream.TunnelProperties{
  Publish:     rstream.BoolPtr(true),
  Protocol:    rstream.ProtocolPtr(rstream.ProtocolHTTP),
  HTTPVersion: rstream.HTTPVersionPtr(rstream.HTTP1_1),
})

Dialing a tunnel

Dialing uses an id or name:

conn, err := client.Dial(ctx, rstream.Addr{IdOrName: "my-tunnel"})

Datagram tunnels use the packet API:

pc, err := client.PacketDial(ctx, rstream.Addr{IdOrName: "my-dgram-tunnel"})

Watching events

The SDK supports watching events over SSE and WebSocket:

err := client.WatchSSE(ctx, func(ev rstream.Event) error {
  fmt.Println(ev.Type)
  return nil
})

err := client.WatchWS(ctx, func(ev rstream.Event) error {
  fmt.Println(ev.Type)
  return nil
})