Engine and Control Plane

Go SDK Engine and Control Plane

Use the Go SDK for engine inventory, watch streams, TURN credentials, and managed Control plane APIs.

Written by uartnet

@uartnet

The Go SDK includes runtime tunnel APIs and HTTP API helpers. Runtime APIs create and dial tunnels. Engine API helpers inspect the live engine. The Control plane package talks to hosted project APIs when an integration needs managed project resolution or TURN credential issuance.

List Tunnels and Clients

The Engine API client exposes typed discovery APIs.

tunnels, err := client.ListTunnels(ctx, &rstream.ListTunnelsParams{
  Filters: &rstream.ListTunnelsFilters{
    Protocol: rstream.ProtocolPtr(rstream.ProtocolHTTP),
    Labels: map[string]*string{
      "service": rstream.StringPtr("api"),
      "env":     rstream.StringPtr("prod"),
    },
  },
})
if err != nil {
  log.Fatal(err)
}
 
_ = tunnels

clients, err := client.ListClients(ctx, &rstream.ListClientsParams{
  Filters: &rstream.ListClientsFilters{
    Labels: map[string]*string{
      "role": rstream.StringPtr("edge-agent"),
    },
  },
})
if err != nil {
  log.Fatal(err)
}
 
_ = clients

Use labels consistently on tunnels and clients so inventory queries stay useful for dashboards, automation, cleanup jobs, and access reviews.

Watch Events

The watch APIs support SSE and WebSocket with the same filter model as the list APIs.

err := client.WatchWS(ctx, &rstream.WatchParams{
  Clients: &rstream.ListClientsFilters{
    Labels: map[string]*string{
      "role": rstream.StringPtr("edge-agent"),
    },
  },
  Tunnels: &rstream.ListTunnelsFilters{
    Labels: map[string]*string{
      "service": rstream.StringPtr("api"),
    },
  },
}, func(ev rstream.Event) error {
  fmt.Println(ev.Type)
  return nil
})
if err != nil {
  log.Fatal(err)
}

WatchSSE exposes the same event contract over Server-Sent Events. WebSocket is useful for bidirectional operator tools, while SSE is simple for inventory watchers and background processes.

TURN Credentials

The config-aware TURN helper creates credentials from the selected project context or the explicit environment of the process.

turn, err := config.CreateTURNCredentialsFromEnv(context.Background())
if err != nil {
  log.Fatal(err)
}
 
_ = turn

This is the simplest path when the process already runs with the same config model as the CLI. See STUN and TURN for the full TURN model and credential lifetime behavior.

Hosted Control Plane APIs

The Go SDK exposes a separate package for hosted Control plane APIs. Use github.com/rstreamlabs/rstream-go for engine runtime work and github.com/rstreamlabs/rstream-go/controlplane for hosted account, project, and managed TURN APIs.

cp := controlplane.NewClient(
  "https://rstream.io",
  os.Getenv("RSTREAM_AUTHENTICATION_TOKEN"),
)
 
whoami, err := cp.Whoami(context.Background())
if err != nil {
  log.Fatal(err)
}
 
projects, err := cp.ListProjects(context.Background(), controlplane.ListProjectsParams{})
if err != nil {
  log.Fatal(err)
}
 
project, err := cp.ResolveProjectByEndpoint(context.Background(), "project-endpoint")
if err != nil {
  log.Fatal(err)
}
 
_ = whoami
_ = projects
_ = project

Use Control plane calls for project discovery, managed project resolution, managed TURN issuance, and account-aware integrations. Use Engine API calls when the integration already knows which engine it is operating against.

Transport, Proxy, and DNS JS SDK