runner

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 16, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

README

Runner

Package runner provides runner types, session storage, and telephony/WebRTC session argument types for the development runner (POST /start, /sessions/{id}, Daily, LiveKit, etc.).

Purpose

  • Session: Per-call/session data (Body from /start, EnableDefaultIceServers).
  • SessionStore: Put/Get/Delete sessions by ID; in-memory (single instance) or Redis (horizontal scaling).
  • Runner args: RunnerArgs, DailyRunnerArgs, WebSocketRunnerArgs, SmallWebRTCRunnerArgs, LiveKitRunnerArgs carry transport-specific parameters (room URL, token, SDP, etc.).
  • Telephony: TelephonyCallData, ParseTelephonyMessage detect provider (Twilio, Telnyx, Plivo, Exotel) and build the right frame serializer.
  • Dial-in: DialinSettings, DailyDialinRequest for Daily PSTN dial-in webhook.

Session lifecycle

stateDiagram-v2
    [*] --> Created : POST /start
    Created --> Active : transport connected
    Active --> Active : /sessions/id/api/offer etc.
    Active --> Ended : disconnect or timeout
    Ended --> [*] : Delete(session_id)
  • Server creates a session (e.g. on POST /start), stores it in SessionStore, returns session ID. Client uses the ID for WebRTC offer or WebSocket telephony. When the call ends, the server deletes the session.

Exported symbols

Symbol Type Description
Session struct Body, EnableDefaultIceServers
SessionStore interface Put(id, sess), Get(id), Delete(id)
MemorySessionStore struct In-memory store; NewMemorySessionStore, Put, Get, Delete
RedisSessionStore struct Redis-backed store with TTL; RedisSessionStoreOptions, NewRedisSessionStore
NewSessionStoreFromConfig(cfg) func Returns memory or Redis store from config (session_store, redis_url, session_ttl_secs)
RunnerArgs struct HandleSigint, HandleSigterm, PipelineIdleTimeoutSecs, Body
DailyRunnerArgs struct RunnerArgs + RoomURL, Token
WebSocketRunnerArgs struct RunnerArgs + Body (telephony)
SmallWebRTCRunnerArgs struct RunnerArgs + SDP, Type, PCID, RestartPC, RequestData
LiveKitRunnerArgs struct RunnerArgs + RoomName, URL, Token
DialinSettings struct CallID, CallDomain, To, From, SIPHeaders (Daily dial-in)
DailyDialinRequest struct DialinSettings, DailyAPIKey, DailyAPIURL
TelephonyCallData struct Provider, stream/call IDs, body (Twilio, Telnyx, Plivo, Exotel)
ParseTelephonyMessage(first, second []byte) func Detects provider and returns TelephonyCallData
Serializer helpers funcs Build Twilio/Telnyx/Plivo/Exotel serializer from TelephonyCallData

Concurrency

  • MemorySessionStore: Protected by sync.RWMutex for Put/Get/Delete.
  • RedisSessionStore: Uses Redis client (safe for concurrent use); Put sets TTL.

Files

File Description
types.go RunnerArgs, DailyRunnerArgs, WebSocketRunnerArgs, SmallWebRTCRunnerArgs, LiveKitRunnerArgs, DialinSettings, DailyDialinRequest
session.go Session, SessionStore, MemorySessionStore
session_factory.go NewSessionStoreFromConfig
redis_session.go RedisSessionStore, RedisSessionStoreOptions, NewRedisSessionStore
telephony.go TelephonyCallData, ParseTelephonyMessage, serializer construction

Subpackages

Path Description
daily/ Daily.co transport integration (room, token, dial-in)
livekit/ LiveKit transport integration

See also

Documentation

Overview

Package runner provides Redis-backed session store for horizontal scaling.

Package runner provides runner types and session management.

Package runner provides runner telephony WebSocket parsing and serializer construction.

Package runner provides runner types and session argument types for development runner.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BuildTelephonySerializer

func BuildTelephonySerializer(data TelephonyCallData, getKey GetAPIKeyFunc) serialize.Serializer

BuildTelephonySerializer returns a Serializer for the given provider and call data. getKey is used to resolve account SID, auth token, API key, etc.

func ReadFirstTwoTextMessages

func ReadFirstTwoTextMessages(readFunc func() ([]byte, error)) (first, second []byte, err error)

ReadFirstTwoTextMessages reads up to two text messages from the WebSocket-style reader. It is used to parse the telephony handshake. The readFunc should read one message and return (payload, nil) or (nil, err).

Types

type DailyDialinRequest

type DailyDialinRequest struct {
	DialinSettings DialinSettings `json:"dialin_settings"`
	DailyAPIKey    string         `json:"daily_api_key"`
	DailyAPIURL    string         `json:"daily_api_url"`
}

DailyDialinRequest is the request body for Daily PSTN dial-in webhook handler.

type DailyRunnerArgs

type DailyRunnerArgs struct {
	RunnerArgs
	RoomURL string
	Token   string
}

DailyRunnerArgs holds Daily transport session arguments.

type DialinSettings

type DialinSettings struct {
	CallID     string            `json:"callId"`
	CallDomain string            `json:"callDomain"`
	To         string            `json:"To,omitempty"`
	From       string            `json:"From,omitempty"`
	SIPHeaders map[string]string `json:"sipHeaders,omitempty"`
}

DialinSettings holds dial-in settings from the Daily webhook (PSTN/SIP). Matches runner cloud and Daily.co webhook payload structure (camelCase from webhook).

type GetAPIKeyFunc

type GetAPIKeyFunc func(service, envVar string) string

GetAPIKeyFunc returns an API key for a service (e.g. from config or env).

type LiveKitRunnerArgs

type LiveKitRunnerArgs struct {
	RunnerArgs
	RoomName string
	URL      string
	Token    string
}

LiveKitRunnerArgs holds LiveKit transport session arguments.

type MemorySessionStore

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

MemorySessionStore is an in-memory, concurrency-safe store for sessions by ID.

func NewMemorySessionStore

func NewMemorySessionStore() *MemorySessionStore

NewMemorySessionStore returns a new in-memory session store.

func (*MemorySessionStore) Delete

func (s *MemorySessionStore) Delete(id string) error

Delete removes the session for id. Idempotent.

func (*MemorySessionStore) Get

func (s *MemorySessionStore) Get(id string) (*Session, error)

Get returns the session for id, or nil if not found.

func (*MemorySessionStore) Put

func (s *MemorySessionStore) Put(id string, sess *Session) error

Put stores a session by id. Overwrites if id exists.

type RedisSessionStore

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

RedisSessionStore stores sessions in Redis with a configurable TTL and key prefix.

func NewRedisSessionStore

func NewRedisSessionStore(client *redis.Client, opts RedisSessionStoreOptions) *RedisSessionStore

NewRedisSessionStore creates a session store backed by the given Redis client.

func (*RedisSessionStore) Delete

func (s *RedisSessionStore) Delete(id string) error

Delete removes the session for id. Idempotent.

func (*RedisSessionStore) Get

func (s *RedisSessionStore) Get(id string) (*Session, error)

Get returns the session for id, or (nil, nil) if not found.

func (*RedisSessionStore) Ping

func (s *RedisSessionStore) Ping(ctx context.Context) error

Ping checks Redis connectivity. Used for readiness probes when session_store is redis.

func (*RedisSessionStore) Put

func (s *RedisSessionStore) Put(id string, sess *Session) error

Put stores a session by id with TTL. Overwrites if id exists.

type RedisSessionStoreOptions

type RedisSessionStoreOptions struct {
	// Prefix is prepended to session IDs for Redis keys (default: "voxray:session:").
	Prefix string
	// TTL is how long sessions live in Redis (default: 1 hour).
	TTL time.Duration
}

RedisSessionStoreOptions configures a RedisSessionStore.

type RunnerArgs

type RunnerArgs struct {
	// HandleSigint indicates whether to handle SIGINT (default false).
	HandleSigint bool
	// HandleSigterm indicates whether to handle SIGTERM (default false).
	HandleSigterm bool
	// PipelineIdleTimeoutSecs is the pipeline idle timeout in seconds (default 300).
	PipelineIdleTimeoutSecs int
	// Body holds additional request data (e.g. custom parameters from /start or webhook).
	Body map[string]interface{}
}

RunnerArgs holds common session arguments for the runner.

type Session

type Session struct {
	// Body is the optional request body from /start.
	Body map[string]interface{}
	// EnableDefaultIceServers is set when the client requested default ICE config in /start.
	EnableDefaultIceServers bool
}

Session holds data for a runner session (created by POST /start).

type SessionStore

type SessionStore interface {
	Put(id string, sess *Session) error
	Get(id string) (*Session, error)
	Delete(id string) error
}

SessionStore is the interface for storing and retrieving sessions by ID. Implementations may be in-memory (single instance) or backed by Redis (horizontal scaling).

func NewSessionStoreFromConfig

func NewSessionStoreFromConfig(cfg *config.Config) (SessionStore, error)

NewSessionStoreFromConfig returns a SessionStore based on cfg. When session_store is "" or "memory", returns an in-memory store (single instance / vertical scaling). When session_store is "redis", requires redis_url and returns a Redis-backed store (horizontal scaling).

type SmallWebRTCRunnerArgs

type SmallWebRTCRunnerArgs struct {
	RunnerArgs
	// SDP is the WebRTC SDP offer string.
	SDP string
	// Type is the SDP type (e.g. "offer").
	Type string
	// PCID is the peer connection ID from the client.
	PCID string
	// RestartPC indicates whether the client requested a peer connection restart.
	RestartPC bool
	// RequestData is the session/request payload from the client.
	RequestData map[string]interface{}
}

SmallWebRTCRunnerArgs holds Small WebRTC session arguments (e.g. from /sessions/{id}/api/offer).

type TelephonyCallData

type TelephonyCallData struct {
	Provider string
	// Twilio
	StreamSid string
	CallSid   string
	Body      map[string]interface{}
	// Telnyx
	StreamID      string
	CallControlID string
	OutboundEnc   string
	InboundEnc    string
	From, To      string
	// Plivo
	StreamIDPlivo string
	CallID        string
	// Exotel
	AccountSid string
}

TelephonyCallData holds provider-specific call identifiers and options. Used after ParseTelephonyMessage to build the appropriate serializer.

func ParseTelephonyMessage

func ParseTelephonyMessage(firstMessage []byte, secondMessage []byte) (data TelephonyCallData, ok bool)

ParseTelephonyMessage parses the first WebSocket message(s) and detects the telephony provider. It returns the provider name ("twilio", "telnyx", "plivo", "exotel") and call data. Message structure is used to detect: Twilio (event/start/streamSid/callSid), Telnyx (stream_id/call_control_id), Plivo (start/streamId/callId), Exotel (event/start/stream_sid/call_sid/account_sid).

type WebSocketRunnerArgs

type WebSocketRunnerArgs struct {
	RunnerArgs
	// Body is typically set from parsed telephony call data (stream_id, call_id, etc.).
	Body map[string]interface{}
}

WebSocketRunnerArgs holds WebSocket (telephony) session arguments. The WebSocket connection and body are passed when handling /ws for telephony.

Directories

Path Synopsis
Package daily provides Daily.co room and meeting token creation via the REST API (runner Daily integration).
Package daily provides Daily.co room and meeting token creation via the REST API (runner Daily integration).
Package livekit provides LiveKit room URL and agent token configuration from environment (runner Livekit integration).
Package livekit provides LiveKit room URL and agent token configuration from environment (runner Livekit integration).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL