radist

README

radist-server (Go)

Server-side Radist SDK for creating P2P calls and SFU rooms from trusted environments.

Source: github.com/radist-tech/go-server

Requirements

Go 1.21 or later.

Installation

go get github.com/radist-tech/go-server

Authentication

Client resolves the secret token and project ID from constructor options first, then from environment variables.

Config	Option	Environment variable
Secret token	NewClient(token)	RADIST_KEY
Project ID	WithProjectID(id)	RADIST_PROJECT_ID
API base URL	WithAPIBaseURL(u)	RADIST_API_BASE_URL

If no secret token is present, NewClient returns an error immediately. If no project ID is present, request methods return an error before making a request.

Usage

import radist "github.com/radist-tech/go-server"

client, err := radist.NewClient(os.Getenv("RADIST_KEY"),
    radist.WithProjectID(os.Getenv("RADIST_PROJECT_ID")),
)
if err != nil {
    log.Fatal(err)
}

conn, err := client.CreateP2PConnection(ctx, nil)
if err != nil {
    log.Fatal(err)
}

hostToken := conn.CallTokens[0]
guestToken := conn.CallTokens[1]
fmt.Println(conn.CallID, hostToken, guestToken)

SFU rooms

room, err := client.CreateRoom(ctx, nil)
if err != nil {
    log.Fatal(err)
}

tok, err := client.MintConnectionToken(ctx, radist.MintConnectionTokenOptions{
    RoomID: room.RoomID,
})

P2P additional tokens

tok, err := client.MintConnectionToken(ctx, radist.MintConnectionTokenOptions{
    CallID: conn.CallID,
})

Persistent Spaces

Spaces are reusable meeting rooms with a stable join URL, unlike P2P calls and SFU rooms which are created fresh each time.

space, err := client.CreateSpace(ctx, radist.CreateSpaceOptions{
    Name:       "Team Standup",
    AccessType: radist.SpaceAccessPublic,
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(space.Space.ID, space.ParticipantURL, space.HostToken)

spaces, err := client.ListSpaces(ctx, nil)
if err != nil {
    log.Fatal(err)
}
for _, s := range spaces {
    fmt.Println(s.ID, s.Slug, s.ParticipantURL)
}

SpaceCreated.HostToken and SpaceCreated.ParticipantURL are ready to hand to the host and to participants respectively; use RotateSpaceHostToken to invalidate and reissue the host token later.

tok, err := client.RotateSpaceHostToken(ctx, space.Space.ID, nil)
if err != nil {
    log.Fatal(err)
}
fmt.Println(tok.HostURL, tok.HostToken)

Error handling

API errors implement the error interface and can be inspected as *radist.APIError:

var apiErr *radist.APIError
if errors.As(err, &apiErr) {
    fmt.Println(apiErr.Status, apiErr.Message)
}

Tests

go test ./...

Documentation

Overview

Package radist provides a server-side client for the Radist API, enabling creation of P2P calls, SFU rooms, and connection tokens from trusted server environments.

Index

• type APIError
  • func (e *APIError) Error() string
• type Client
  • func NewClient(secretToken string, opts ...Option) (*Client, error)
  • func (c *Client) CreateP2PConnection(ctx context.Context, opts *CreateP2PConnectionOptions) (*P2PConnection, error)
  • func (c *Client) CreateRoom(ctx context.Context, opts *CreateRoomOptions) (*Room, error)
  • func (c *Client) CreateSpace(ctx context.Context, opts CreateSpaceOptions) (*SpaceCreated, error)
  • func (c *Client) DeleteSpace(ctx context.Context, spaceID string, opts *SpaceOptions) error
  • func (c *Client) GetSpace(ctx context.Context, spaceID string, opts *SpaceOptions) (*Space, error)
  • func (c *Client) ListSpaces(ctx context.Context, opts *SpaceOptions) ([]Space, error)
  • func (c *Client) MintConnectionToken(ctx context.Context, opts MintConnectionTokenOptions) (*ConnectionToken, error)
  • func (c *Client) RotateSpaceHostToken(ctx context.Context, spaceID string, opts *SpaceOptions) (*SpaceHostToken, error)
  • func (c *Client) UpdateSpace(ctx context.Context, spaceID string, opts UpdateSpaceOptions) (*Space, error)
• type ConnectionToken
• type CreateP2PConnectionOptions
• type CreateRoomOptions
• type CreateSpaceOptions
• type MintConnectionTokenOptions
• type Option
  • func WithAPIBaseURL(apiBaseURL string) Option
  • func WithHTTPClient(httpClient *http.Client) Option
  • func WithProjectID(projectID string) Option
• type P2PConnection
• type Room
• type Space
• type SpaceAccessType
• type SpaceCreated
• type SpaceHostToken
• type SpaceOptions
• type UpdateSpaceOptions

Types

type APIError

type APIError struct {
	// Status is the HTTP status code returned by the API.
	Status int
	// Message is the human-readable error description.
	Message string
}

APIError is returned when the Radist API responds with a non-success status or an unexpected response body.

func (*APIError) Error

func (e *APIError) Error() string

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a server-side Radist API client. Create one with NewClient.

func NewClient

func NewClient(secretToken string, opts ...Option) (*Client, error)

NewClient creates a new Radist server-side client.

secretToken may be empty, in which case the RADIST_KEY environment variable is used. If neither is set, NewClient returns an error.

The default project ID is read from RADIST_PROJECT_ID unless overridden with WithProjectID.

func (*Client) CreateP2PConnection

func (c *Client) CreateP2PConnection(ctx context.Context, opts *CreateP2PConnectionOptions) (*P2PConnection, error)

CreateP2PConnection creates a new P2P call and returns its ID and two participant tokens.

func (*Client) CreateRoom

func (c *Client) CreateRoom(ctx context.Context, opts *CreateRoomOptions) (*Room, error)

CreateRoom creates a new SFU room and returns its ID and two participant tokens.

func (*Client) CreateSpace

func (c *Client) CreateSpace(ctx context.Context, opts CreateSpaceOptions) (*SpaceCreated, error)

CreateSpace creates a new persistent Space and returns it along with join URLs and a host token.

func (*Client) DeleteSpace

func (c *Client) DeleteSpace(ctx context.Context, spaceID string, opts *SpaceOptions) error

DeleteSpace deletes a Space by ID.

func (*Client) GetSpace

func (c *Client) GetSpace(ctx context.Context, spaceID string, opts *SpaceOptions) (*Space, error)

GetSpace fetches a single Space by ID. The backend has no dedicated get-by-ID endpoint, so this lists all spaces in the project and finds the matching one; it returns a 404 APIError if no space with that ID exists.

func (*Client) ListSpaces

func (c *Client) ListSpaces(ctx context.Context, opts *SpaceOptions) ([]Space, error)

ListSpaces lists all persistent Spaces in a project.

func (*Client) MintConnectionToken

func (c *Client) MintConnectionToken(ctx context.Context, opts MintConnectionTokenOptions) (*ConnectionToken, error)

MintConnectionToken mints a connection token for a P2P call or SFU room. Exactly one of opts.CallID or opts.RoomID must be set.

func (*Client) RotateSpaceHostToken

func (c *Client) RotateSpaceHostToken(ctx context.Context, spaceID string, opts *SpaceOptions) (*SpaceHostToken, error)

RotateSpaceHostToken invalidates a Space's current host token and mints a new one, returning the refreshed join URLs and token.

func (*Client) UpdateSpace

func (c *Client) UpdateSpace(ctx context.Context, spaceID string, opts UpdateSpaceOptions) (*Space, error)

UpdateSpace updates a Space's mutable fields. Only the fields set on opts (non-empty) are sent in the update request.

type ConnectionToken

type ConnectionToken struct {
	// Token is the minted connection token.
	Token string
}

ConnectionToken is the result of Client.MintConnectionToken.

type CreateP2PConnectionOptions

type CreateP2PConnectionOptions struct {
	// ProjectID overrides the client-level project ID for this call only.
	ProjectID string
	// AccessControl sets the access policy for the call. Use "public" to allow
	// anyone with a public key to join, or "private" (the default) to restrict
	// token minting to your server.
	AccessControl string
}

CreateP2PConnectionOptions holds per-call options for Client.CreateP2PConnection. All fields are optional; a nil pointer is treated as an empty value.

type CreateRoomOptions

type CreateRoomOptions struct {
	// ProjectID overrides the client-level project ID for this call only.
	ProjectID string
}

CreateRoomOptions holds per-call options for Client.CreateRoom. All fields are optional; a nil pointer is treated as an empty value.

type CreateSpaceOptions

type CreateSpaceOptions struct {
	// ProjectID overrides the client-level project ID for this call only.
	ProjectID string
	// Name is the human-readable display name for the space.
	Name string
	// AccessType sets the access policy for the space.
	AccessType SpaceAccessType
	// Password sets the join password. Required when AccessType is
	// [SpaceAccessPassword]; omitted from the request when empty.
	Password string
}

CreateSpaceOptions holds options for Client.CreateSpace.

type MintConnectionTokenOptions

type MintConnectionTokenOptions struct {
	// ProjectID overrides the client-level project ID for this call only.
	ProjectID string
	// CallID mints a token for a P2P call created by [Client.CreateP2PConnection].
	CallID string
	// RoomID mints a token for an SFU room created by [Client.CreateRoom].
	RoomID string
}

MintConnectionTokenOptions holds options for Client.MintConnectionToken. Provide exactly one of CallID or RoomID.

type Option

type Option func(*Client)

Option configures a Client.

func WithAPIBaseURL

func WithAPIBaseURL(apiBaseURL string) Option

WithAPIBaseURL overrides the Radist API base URL. Trailing slashes are removed.

func WithHTTPClient

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient replaces the default http.DefaultClient used for requests.

func WithProjectID

func WithProjectID(projectID string) Option

WithProjectID sets the default project ID used when one is not provided to individual request methods. Overrides RADIST_PROJECT_ID.

type P2PConnection

type P2PConnection struct {
	// CallID is the unique identifier for this call.
	CallID string
	// CallTokens contains two server-minted participant tokens.
	// Give one token to each approved participant.
	CallTokens []string
	// AccessControl is the access policy for this call: "public" or "private".
	// Private calls (the default) only accept tokens minted server-side.
	AccessControl string
}

P2PConnection is the result of Client.CreateP2PConnection.

type Room

type Room struct {
	// RoomID is the unique identifier for this SFU room.
	RoomID string
	// RoomTokens contains two server-minted participant tokens.
	RoomTokens []string
}

Room is the result of Client.CreateRoom.

type Space

type Space struct {
	// ID is the unique identifier for this space.
	ID string `json:"id"`
	// ProjectID is the project this space belongs to.
	ProjectID string `json:"projectId"`
	// Slug is the URL-friendly identifier for this space.
	Slug string `json:"slug"`
	// Name is the human-readable display name for this space.
	Name string `json:"name"`
	// AccessType is the access policy for this space.
	AccessType SpaceAccessType `json:"accessType"`
	// ActiveRoomID is the ID of the room currently backing this space, if any.
	ActiveRoomID *string `json:"activeRoomId"`
	// CreatedAt is the ISO timestamp this space was created.
	CreatedAt string `json:"createdAt"`
	// UpdatedAt is the ISO timestamp this space was last updated.
	UpdatedAt string `json:"updatedAt"`
	// ParticipantURL is the URL participants use to join this space.
	// It is present in [Client.ListSpaces] results but absent elsewhere.
	ParticipantURL string `json:"participantUrl,omitempty"`
}

Space is a persistent, reusable meeting space that can be joined repeatedly without minting a new call or room each time.

type SpaceAccessType

type SpaceAccessType string

SpaceAccessType is the access policy for a persistent Space.

const (
	// SpaceAccessPublic allows anyone with the space's participant URL to join.
	SpaceAccessPublic SpaceAccessType = "public"
	// SpaceAccessPassword requires a password to join the space.
	SpaceAccessPassword SpaceAccessType = "password"
	// SpaceAccessKnock requires host approval before a participant may join.
	SpaceAccessKnock SpaceAccessType = "knock"
)

type SpaceCreated

type SpaceCreated struct {
	// Space is the newly created space.
	Space Space
	// ParticipantURL is the URL participants use to join the space.
	ParticipantURL string
	// HostURL is the URL the host uses to join the space with host privileges.
	HostURL string
	// HostToken is the minted host token for the space.
	HostToken string
}

SpaceCreated is the result of Client.CreateSpace.

type SpaceHostToken

type SpaceHostToken struct {
	// ParticipantURL is the URL participants use to join the space.
	ParticipantURL string
	// HostURL is the URL the host uses to join the space with host privileges.
	HostURL string
	// HostToken is the newly minted host token for the space.
	HostToken string
}

SpaceHostToken is the result of Client.RotateSpaceHostToken.

type SpaceOptions

type SpaceOptions struct {
	// ProjectID overrides the client-level project ID for this call only.
	ProjectID string
}

SpaceOptions holds per-call options shared by Client.ListSpaces, Client.GetSpace, Client.DeleteSpace, and Client.RotateSpaceHostToken. All fields are optional; a nil pointer is treated as an empty value.

type UpdateSpaceOptions

type UpdateSpaceOptions struct {
	// ProjectID overrides the client-level project ID for this call only.
	ProjectID string
	// Slug, if set, updates the space's URL-friendly identifier.
	Slug string
	// Name, if set, updates the space's display name.
	Name string
	// AccessType, if set, updates the space's access policy.
	AccessType SpaceAccessType
	// Password, if set, updates the space's join password.
	Password string
}

UpdateSpaceOptions holds options for Client.UpdateSpace. Only the fields that are set (non-empty) are sent in the update request; all fields are optional.