api

Documentation

Overview

Package api defines the general API for both coordinator and worker applications.

Each API call (request and response) is a JSON-encoded "packet" of the following structure:

id - (optional) a globally unique packet id;
 t - (required) one of the predefined unique packet types;
 p - (optional) packet payload with arbitrary data.

The basic idea behind this API is that the packets differentiate by their predefined types with which it is possible to unwrap the payload into distinct request/response data structures. And the id field is used for tracking packets through a chain of different network points (apps, devices), for example, passing a packet from a browser forward to a worker and back through a coordinator.

Example:

{"t":4,"p":{"ice":[{"urls":"stun:stun.l.google.com:19302"}],"games":["Sushi The Cat"],"wid":"cfv68irdrc3ifu3jn6bg"}}

Index

• Constants
• Variables
• func Unwrap[T any](data []byte) *T
• func UnwrapChecked[T any](bytes []byte, err error) (*T, error)
• type ChangePlayerRequest
• type ChangePlayerResponse
• type ChangePlayerUserRequest
• type CheckLatencyUserRequest
• type CheckLatencyUserResponse
• type CloseRoomRequest
• type ConnectionRequest
• type GameInfo
• type GameQuitRequest
• type GameStartUserRequest
• type GetWorkerListResponse
• type IceServer
• type Id
• type In
  • func (i In[I]) GetId() I
  • func (i In[I]) GetPayload() []byte
  • func (i In[I]) GetType() PT
• type InitSessionUserResponse
• type LoadGameRequest
• type LoadGameResponse
• type Out
  • func (o *Out) GetPayload() any
  • func (o *Out) SetGetId(s fmt.Stringer)
  • func (o *Out) SetId(s string)
  • func (o *Out) SetPayload(a any)
  • func (o *Out) SetType(u uint8)
• type PT
  • func (p PT) String() string
• type RecordGameRequest
• type RecordGameResponse
• type RegisterRoomRequest
• type Room
• type SaveGameRequest
• type SaveGameResponse
• type Server
• type StartGameRequest
• type StartGameResponse
• type Stateful
• type StatefulRoom
• type TerminateSessionRequest
• type ToggleMultitapRequest
• type WebrtcAnswerRequest
• type WebrtcAnswerUserRequest
• type WebrtcIceCandidateRequest
• type WebrtcInitRequest
• type WebrtcInitResponse
• type WebrtcUserIceCandidate

Constants

const (
	EMPTY = ""
	OK    = "ok"
)

Various codes

const (
	DataQueryParam   = "data"
	RoomIdQueryParam = "room_id"
	ZoneQueryParam   = "zone"
	WorkerIdParam    = "wid"
)

Variables

var (
	ErrForbidden = fmt.Errorf("forbidden")
	ErrMalformed = fmt.Errorf("malformed")
)

var (
	EmptyPacket = Out{Payload: ""}
	ErrPacket   = Out{Payload: "err"}
	OkPacket    = Out{Payload: "ok"}
)

Functions

func Unwrap

func Unwrap[T any](data []byte) *T

func UnwrapChecked

func UnwrapChecked[T any](bytes []byte, err error) (*T, error)

Types

type ChangePlayerRequest

type ChangePlayerRequest[T Id] struct {
	StatefulRoom[T]
	Index int `json:"index"`
}

type ChangePlayerResponse

type ChangePlayerResponse int

type ChangePlayerUserRequest

type ChangePlayerUserRequest int

type CheckLatencyUserRequest

type CheckLatencyUserRequest map[string]int64

type CheckLatencyUserResponse

type CheckLatencyUserResponse []string

type CloseRoomRequest

type CloseRoomRequest string

type ConnectionRequest

type ConnectionRequest[T Id] struct {
	Addr    string `json:"addr,omitempty"`
	Id      T      `json:"id,omitempty"`
	IsHTTPS bool   `json:"is_https,omitempty"`
	PingURL string `json:"ping_url,omitempty"`
	Port    string `json:"port,omitempty"`
	Tag     string `json:"tag,omitempty"`
	Zone    string `json:"zone,omitempty"`
}

type GameInfo

type GameInfo struct {
	Name string `json:"name"`
	Base string `json:"base"`
	Path string `json:"path"`
	Type string `json:"type"`
}

type GameQuitRequest

type GameQuitRequest[T Id] struct {
	StatefulRoom[T]
}

type GameStartUserRequest

type GameStartUserRequest struct {
	GameName    string `json:"game_name"`
	RoomId      string `json:"room_id"`
	Record      bool   `json:"record,omitempty"`
	RecordUser  string `json:"record_user,omitempty"`
	PlayerIndex int    `json:"player_index"`
}

type GetWorkerListResponse

type GetWorkerListResponse struct {
	Servers []Server `json:"servers"`
}

type IceServer

type IceServer struct {
	Urls       string `json:"urls,omitempty"`
	Username   string `json:"username,omitempty"`
	Credential string `json:"credential,omitempty"`
}

type Id

type Id interface {
	String() string
}

type In

type In[I Id] struct {
	Id      I               `json:"id,omitempty"`
	T       PT              `json:"t"`
	Payload json.RawMessage `json:"p,omitempty"` // should be json.RawMessage for 2-pass unmarshal
}

func (In[I]) GetId

func (i In[I]) GetId() I

func (In[I]) GetPayload

func (i In[I]) GetPayload() []byte

func (In[I]) GetType

func (i In[I]) GetType() PT

type InitSessionUserResponse

type InitSessionUserResponse struct {
	Ice   []IceServer `json:"ice"`
	Games []string    `json:"games"`
	Wid   string      `json:"wid"`
}

type LoadGameRequest

type LoadGameRequest[T Id] struct {
	StatefulRoom[T]
}

type LoadGameResponse

type LoadGameResponse string

type Out

type Out struct {
	Id      string `json:"id,omitempty"` // string because omitempty won't work as intended with arrays
	T       uint8  `json:"t"`
	Payload any    `json:"p,omitempty"`
}

func (*Out) GetPayload

func (o *Out) GetPayload() any

func (*Out) SetGetId

func (o *Out) SetGetId(s fmt.Stringer)

func (*Out) SetId

func (o *Out) SetId(s string)

func (*Out) SetPayload

func (o *Out) SetPayload(a any)

func (*Out) SetType

func (o *Out) SetType(u uint8)

type PT

type PT uint8

const (
	CheckLatency     PT = 3
	InitSession      PT = 4
	WebrtcInit       PT = 100
	WebrtcOffer      PT = 101
	WebrtcAnswer     PT = 102
	WebrtcIce        PT = 103
	StartGame        PT = 104
	ChangePlayer     PT = 108
	QuitGame         PT = 105
	SaveGame         PT = 106
	LoadGame         PT = 107
	ToggleMultitap   PT = 109
	RecordGame       PT = 110
	GetWorkerList    PT = 111
	RegisterRoom     PT = 201
	CloseRoom        PT = 202
	IceCandidate        = WebrtcIce
	TerminateSession PT = 204
)

Packet codes:

x, 1xx - user codes
2xx - worker codes

func (PT) String

func (p PT) String() string

type RecordGameRequest

type RecordGameRequest[T Id] struct {
	StatefulRoom[T]
	Active bool   `json:"active"`
	User   string `json:"user"`
}

type RecordGameResponse

type RecordGameResponse string

type RegisterRoomRequest

type RegisterRoomRequest string

type Room

type Room struct {
	Rid string `json:"room_id"` // room id
}

type SaveGameRequest

type SaveGameRequest[T Id] struct {
	StatefulRoom[T]
}

type SaveGameResponse

type SaveGameResponse string

type Server

type Server struct {
	Addr     string `json:"addr,omitempty"`
	Id       Id     `json:"id,omitempty"`
	IsBusy   bool   `json:"is_busy,omitempty"`
	InGroup  bool   `json:"in_group,omitempty"`
	Machine  string `json:"machine,omitempty"`
	PingURL  string `json:"ping_url"`
	Port     string `json:"port,omitempty"`
	Replicas uint32 `json:"replicas,omitempty"`
	Tag      string `json:"tag,omitempty"`
	Zone     string `json:"zone,omitempty"`
}

Server contains a list of server groups. Server is a separate machine that may contain multiple sub-processes.

type StartGameRequest

type StartGameRequest[T Id] struct {
	StatefulRoom[T]
	Record      bool
	RecordUser  string
	Game        GameInfo `json:"game"`
	PlayerIndex int      `json:"player_index"`
}

type StartGameResponse

type StartGameResponse struct {
	Room
	Record bool
}

type Stateful

type Stateful[T Id] struct {
	Id T `json:"id"`
}

type StatefulRoom

type StatefulRoom[T Id] struct {
	Stateful[T]
	Room
}

type TerminateSessionRequest

type TerminateSessionRequest[T Id] struct {
	Stateful[T]
}

type ToggleMultitapRequest

type ToggleMultitapRequest[T Id] struct {
	StatefulRoom[T]
}

type WebrtcAnswerRequest

type WebrtcAnswerRequest[T Id] struct {
	Stateful[T]
	Sdp string `json:"sdp"`
}

type WebrtcAnswerUserRequest

type WebrtcAnswerUserRequest string

type WebrtcIceCandidateRequest

type WebrtcIceCandidateRequest[T Id] struct {
	Stateful[T]
	Candidate string `json:"candidate"` // Base64-encoded ICE candidate
}

type WebrtcInitRequest

type WebrtcInitRequest[T Id] struct {
	Stateful[T]
}

type WebrtcInitResponse

type WebrtcInitResponse string

type WebrtcUserIceCandidate

type WebrtcUserIceCandidate string