httpapi

package
v0.4.0 Latest Latest
Warning

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

Go to latest
Published: Nov 18, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package httpapi exposes the reusable, player-facing lobby API. It has no database, network, or environment dependency and deliberately excludes Centrifugo's trusted internal proxy endpoints.

Index

Constants

View Source
const MaxErrorDetails = 100

MaxErrorDetails is the most entries a problem's errors list holds. A longer list keeps its first MaxErrorDetails-1 problems and ends with one entry, with no location, that counts the rest: "and N more problems".

View Source
const MaxErrorValueLength = 256

MaxErrorValueLength is the most bytes of a string value an error detail echoes. A longer string is cut at a rune boundary to end with "..." within that length.

Variables

This section is empty.

Functions

func BoundErrorDetails

func BoundErrorDetails(_ huma.Context, _ string, v any) (any, error)

BoundErrorDetails is a Huma transformer that keeps problem responses small, applying LimitErrorDetails to their errors list. Without it, Huma's "unexpected property" error echoes the whole enclosing object as its value, so an object with n unknown keys answers with n copies of itself, which is quadratic in the request size.

It accepts any struct pointer with an Errors []*huma.ErrorDetail field, so it also handles the copies that Huma's schema link transformer makes. Running it twice changes nothing.

func LimitErrorDetails

func LimitErrorDetails(details []*huma.ErrorDetail) []*huma.ErrorDetail

LimitErrorDetails bounds a list of problems for a response:

  • It drops object and array values. Huma's object errors, such as an unexpected or missing property, echo the whole enclosing object, and the location already points into the request.
  • It cuts string values to MaxErrorValueLength bytes.
  • A list longer than MaxErrorDetails keeps its first MaxErrorDetails-1 problems, listing unexpected properties after every other problem, and ends with an entry that counts the rest.

It returns details itself when nothing needs to change, and never edits the details it is given.

func Register

func Register(api huma.API, app domain.Application, authenticator domain.Authenticator, issuer domain.ConnectionTokenIssuer, playerTokens domain.PlayerTokenIssuer, retention domain.RetentionRunner)

Register installs the public lobby API. app, authenticator, issuer, playerTokens and retention are invoked only while serving requests, so offline OpenAPI export may use fakes. After each lobby request, retention runs a pass if one is due; a nil retention deletes nothing.

func RegisterGameAPI

func RegisterGameAPI(api huma.API, games domain.GameAPI, secrets GameSecrets)

RegisterGameAPI installs the game API, which a game that the lobby calls over HTTP uses to read the lobby, under /lobby/v1/game-api/games/{game_key}. Every request is signed with the game's shared secret, as the hooks are (gamehooks.Sign); one that doesn't verify with the secret of the game key in its path is refused with 401, so a game reaches only its own lobbies. The game API is not part of the player API: hosts register it on an API of its own, whose OpenAPI document is api/game-api.openapi.json.

func RegisterGameBinding

func RegisterGameBinding[Result any](api huma.API, operation huma.Operation, binding *application.GameBinding[Result], authenticator domain.Authenticator)

RegisterGameBinding installs an explicit game-owned endpoint using shared lobby authentication and problem responses. Register does not call it, so these operations stay outside the lobby-only OpenAPI/SDK surface.

Types

type AddSeatBody

type AddSeatBody struct {
	RequestID    string       `` /* 230-byte string literal not displayed */
	TeamID       string       `json:"team_id" format:"uuid" doc:"The team the seat joins."`
	SeatSettings SeatSettings `json:"seat_settings" required:"true"`
}

type AddSeatInput

type AddSeatInput struct {
	ScopeInput
	Body AddSeatBody `json:"-"`
}

type ChangeSettingsBody

type ChangeSettingsBody struct {
	Teams        []TeamDefinition `` /* 324-byte string literal not displayed */
	GameSettings GameSettings     `json:"game_settings,omitempty"`
}

type ChangeSettingsInput

type ChangeSettingsInput struct {
	ScopeInput
	Body ChangeSettingsBody `json:"-"`
}

type ConnectionToken

type ConnectionToken struct {
	Token        string    `json:"token"`
	ExpiresAt    time.Time `json:"expires_at"`
	WebsocketURL string    `json:"websocket_url" format:"uri"`
}

type ConnectionTokenInput

type ConnectionTokenInput struct {
	Body struct{} `json:"-"`
}

type ConnectionTokenOutput

type ConnectionTokenOutput struct {
	Body ConnectionToken `json:"-"`
}

type CreateLobbyBody

type CreateLobbyBody struct {
	RequestID        string           `json:"request_id" format:"uuid"`
	GameKey          string           `json:"game_key" pattern:"^[a-z][a-z0-9-]{0,31}$"`
	Name             string           `json:"name" minLength:"1" maxLength:"80"`
	Teams            []TeamDefinition `` /* 169-byte string literal not displayed */
	ClientInstanceID string           `json:"client_instance_id" format:"uuid"`
	GameSettings     GameSettings     `json:"game_settings,omitempty"`
}

type CreateLobbyInput

type CreateLobbyInput struct {
	Body CreateLobbyBody `json:"-"`
}

type CreateLobbyOutput

type CreateLobbyOutput struct {
	Body Snapshot `json:"-"`
}

type CreateSessionBody

type CreateSessionBody struct {
	DisplayName string `json:"display_name" minLength:"1" maxLength:"40"`
}

type CreateSessionInput

type CreateSessionInput struct {
	Body CreateSessionBody `json:"-"`
}

type CreateSessionOutput

type CreateSessionOutput struct {
	Body GuestSession `json:"-"`
}

type EmptyOutput

type EmptyOutput struct{}

type GameProblem

type GameProblem struct {
	Title  string           `json:"title"`
	Status int              `json:"status"`
	Detail string           `json:"detail"`
	Code   domain.ErrorCode `json:"code" enum:"unauthenticated,not_found,permission_denied,watcher_kicked,invalid_input,unavailable,internal_error"`
	// contains filtered or unexported fields
}

GameProblem is a game API refusal.

func (*GameProblem) ContentType

func (problem *GameProblem) ContentType(string) string

func (*GameProblem) Error

func (problem *GameProblem) Error() string

func (*GameProblem) GetStatus

func (problem *GameProblem) GetStatus() int

func (*GameProblem) Unwrap

func (problem *GameProblem) Unwrap() error

type GameSecrets

type GameSecrets func(gameKey string) ([]byte, bool)

GameSecrets returns the shared secret of a game that the lobby calls over HTTP, by its key, or false for a game without one.

type GameSettings

type GameSettings json.RawMessage

GameSettings is a game's own JSON object. It keeps the raw bytes, so numbers and nested values reach the domain without a lossy decode.

func (GameSettings) MarshalJSON

func (settings GameSettings) MarshalJSON() ([]byte, error)

func (GameSettings) Schema

func (*GameSettings) UnmarshalJSON

func (settings *GameSettings) UnmarshalJSON(data []byte) error

type GuestSession

type GuestSession struct {
	PlayerID    string    `json:"player_id" format:"uuid"`
	AccessToken string    `json:"access_token"`
	ExpiresAt   time.Time `json:"expires_at"`
}

type HeartbeatBody

type HeartbeatBody struct {
	ClientInstanceID     string `json:"client_instance_id" format:"uuid"`
	MembershipGeneration int64  `json:"membership_generation" minimum:"1"`
}

type HeartbeatInput

type HeartbeatInput struct {
	ScopeInput
	Body HeartbeatBody `json:"-"`
}

type HeartbeatOutput

type HeartbeatOutput struct {
	Body HeartbeatResult `json:"-"`
}

type HeartbeatResult

type HeartbeatResult struct {
	Version              int64      `json:"version"`
	MembershipGeneration int64      `json:"membership_generation"`
	LeaseExpiresAt       time.Time  `json:"lease_expires_at"`
	DisconnectedUntil    *time.Time `json:"disconnected_until"`
}

type IssuePlayerTokenBody

type IssuePlayerTokenBody struct {
	GameKey string `` /* 135-byte string literal not displayed */
}

type IssuePlayerTokenInput

type IssuePlayerTokenInput struct {
	Body IssuePlayerTokenBody `json:"-"`
}

type IssuePlayerTokenOutput

type IssuePlayerTokenOutput struct {
	Body PlayerToken `json:"-"`
}

type JoinLobbyBody

type JoinLobbyBody struct {
	GameKey          string `json:"game_key" pattern:"^[a-z][a-z0-9-]{0,31}$"`
	JoinCode         string `json:"join_code" minLength:"8" maxLength:"8"`
	ClientInstanceID string `json:"client_instance_id" format:"uuid"`
}

type JoinLobbyInput

type JoinLobbyInput struct {
	Body JoinLobbyBody `json:"-"`
}

type JoinLobbyOutput

type JoinLobbyOutput struct {
	Body Snapshot `json:"-"`
}

type KickWatcherInput

type KickWatcherInput struct {
	ScopeInput
	PlayerID string `path:"player_id" format:"uuid" doc:"The watcher's player ID."`
}

type LeaveInput

type LeaveInput struct{ ScopeInput }

type Lobby

type Lobby struct {
	ID           string       `json:"id"`
	GameKey      string       `json:"game_key"`
	Name         string       `json:"name"`
	JoinCode     string       `json:"join_code"`
	Capacity     int          `json:"capacity" doc:"The number of members the lobby holds, which is its number of teams, since each team holds one member."`
	Phase        domain.Phase `json:"phase"`
	Round        int64        `` /* 226-byte string literal not displayed */
	Version      int64        `json:"version"`
	HostPlayerID *string      `json:"host_player_id"`
	CreatedAt    time.Time    `json:"created_at"`
	GameSettings GameSettings `json:"game_settings"`
}

type LobbyInvalidation

type LobbyInvalidation struct {
	SchemaVersion int    `json:"schema_version" enum:"1"`
	EventID       string `json:"event_id"`
	GameKey       string `json:"game_key"`
	LobbyID       string `json:"lobby_id"`
	Version       int64  `json:"version" minimum:"1"`
	Type          string `json:"type" enum:"lobby.changed"`
}

type Member

type Member struct {
	ID                string               `json:"id"`
	PlayerID          string               `json:"player_id"`
	DisplayName       string               `json:"display_name"`
	Generation        int64                `json:"generation"`
	Active            bool                 `json:"active"`
	TeamID            *string              `json:"team_id"`
	Ready             bool                 `json:"ready"`
	JoinedAt          time.Time            `json:"joined_at"`
	JoinSequence      int64                `json:"join_sequence"`
	DisconnectedUntil *time.Time           `json:"disconnected_until"`
	Kind              domain.MemberKind    `` /* 283-byte string literal not displayed */
	SeatSettings      MemberSeatSettings   `json:"seat_settings"`
	MemberSettings    MemberMemberSettings `json:"member_settings"`
}

type MemberMemberSettings

type MemberMemberSettings json.RawMessage

MemberMemberSettings is a member's member settings: the object a person set, or null.

func (MemberMemberSettings) MarshalJSON

func (settings MemberMemberSettings) MarshalJSON() ([]byte, error)

func (MemberMemberSettings) Schema

func (*MemberMemberSettings) UnmarshalJSON

func (settings *MemberMemberSettings) UnmarshalJSON(data []byte) error

type MemberSeatSettings

type MemberSeatSettings json.RawMessage

MemberSeatSettings is a member's seat settings: the object for a seat, and null for a person.

func (MemberSeatSettings) MarshalJSON

func (settings MemberSeatSettings) MarshalJSON() ([]byte, error)

func (MemberSeatSettings) Schema

func (*MemberSeatSettings) UnmarshalJSON

func (settings *MemberSeatSettings) UnmarshalJSON(data []byte) error

type MemberSettings

type MemberSettings json.RawMessage

MemberSettings is a game's own JSON object for one person in a lobby. Like GameSettings, it keeps the raw bytes.

func (MemberSettings) MarshalJSON

func (settings MemberSettings) MarshalJSON() ([]byte, error)

func (MemberSettings) Schema

func (*MemberSettings) UnmarshalJSON

func (settings *MemberSettings) UnmarshalJSON(data []byte) error

type MemberSettingsBody

type MemberSettingsBody struct {
	MemberSettings MemberSettings `json:"member_settings" required:"true"`
}

type MemberSettingsInput

type MemberSettingsInput struct {
	ScopeInput
	Body MemberSettingsBody `json:"-"`
}

type NullableUUID

type NullableUUID struct{ Value *string }

NullableUUID distinguishes JSON null (clear) from a valid UUID. Omission is rejected by the containing field's `required` schema tag before unmarshalling.

func (NullableUUID) Schema

func (*NullableUUID) UnmarshalJSON

func (value *NullableUUID) UnmarshalJSON(data []byte) error

type PlayerToken

type PlayerToken struct {
	Token     string    `` /* 267-byte string literal not displayed */
	ExpiresAt time.Time `` /* 134-byte string literal not displayed */
}

type Problem

type Problem struct {
	Title  string `json:"title"`
	Status int    `json:"status"`
	Detail string `json:"detail"`
	// TeamIDs lists the teams the error is about.
	TeamIDs []string         `` /* 129-byte string literal not displayed */
	Code    domain.ErrorCode `` /* 334-byte string literal not displayed */
	// Type is the game's problem type of game_requirement.
	Type string `` /* 214-byte string literal not displayed */
	// contains filtered or unexported fields
}

func (*Problem) ContentType

func (problem *Problem) ContentType(string) string

func (*Problem) Error

func (problem *Problem) Error() string

func (*Problem) GetStatus

func (problem *Problem) GetStatus() int

func (*Problem) Unwrap

func (problem *Problem) Unwrap() error

type PublicKeysInput

type PublicKeysInput struct{}

type PublicKeysOutput

type PublicKeysOutput struct {
	CacheControl string `header:"Cache-Control"`
	Body         playertoken.JWKS
}

type ReadyBody

type ReadyBody struct {
	Ready bool `json:"ready" required:"true"`
}

type ReadyInput

type ReadyInput struct {
	ScopeInput
	Body ReadyBody `json:"-"`
}

type ReleaseLeaseInput

type ReleaseLeaseInput struct {
	ScopeInput
	ClientInstanceID     string `path:"client_instance_id" format:"uuid"`
	MembershipGeneration int64  `query:"generation" minimum:"1" required:"true"`
}

type RemoveSeatInput

type RemoveSeatInput struct {
	ScopeInput
	SeatID string `path:"seat_id" format:"uuid" doc:"The seat's member ID."`
}

type ReopenInput

type ReopenInput struct {
	ScopeInput
}

ReopenInput takes no body.

type ScopeInput

type ScopeInput struct {
	GameKey string `path:"game_key" pattern:"^[a-z][a-z0-9-]{0,31}$"`
	LobbyID string `path:"lobby_id" format:"uuid"`
}

type SeatSettings

type SeatSettings json.RawMessage

SeatSettings is a game's own JSON object for a seat that no person plays. Like GameSettings, it keeps the raw bytes.

func (SeatSettings) MarshalJSON

func (settings SeatSettings) MarshalJSON() ([]byte, error)

func (SeatSettings) Schema

func (*SeatSettings) UnmarshalJSON

func (settings *SeatSettings) UnmarshalJSON(data []byte) error

type SelectTeamBody

type SelectTeamBody struct {
	TeamID NullableUUID `json:"team_id" required:"true"`
}

type SelectTeamInput

type SelectTeamInput struct {
	ScopeInput
	Body SelectTeamBody `json:"-"`
}

type Snapshot

type Snapshot struct {
	Lobby                Lobby              `json:"lobby"`
	Teams                []Team             `json:"teams"`
	Members              []Member           `json:"members"`
	StartRoster          []StartRosterEntry `json:"start_roster"`
	MembershipGeneration int64              `json:"membership_generation"`
	Channel              string             `json:"channel"`
	StartRules           StartRules         `json:"start_rules"`
	WatcherCount         int                `` /* 203-byte string literal not displayed */
}

type SnapshotOutput

type SnapshotOutput struct {
	Body Snapshot `json:"-"`
}

type StartInput

type StartInput struct {
	ScopeInput
	Body struct{} `json:"-"`
}

type StartRosterEntry

type StartRosterEntry struct {
	PlayerID  string `json:"player_id"`
	TeamID    string `json:"team_id"`
	MemberID  string `json:"member_id"`
	TeamOrder int    `json:"team_order"`
}

type StartRules

type StartRules struct {
	EveryTeamNeedsMember bool `json:"every_team_needs_member" doc:"Starting fails with empty_teams while a team has no member."`
}

StartRules are the start conditions the lobby's game declares on top of the default ones, so a client can show why the lobby can't start yet.

type Team

type Team struct {
	ID    string `json:"id"`
	Name  string `json:"name"`
	Order int    `json:"order"`
}

Team is one of a lobby's teams. It holds at most one member.

type TeamDefinition

type TeamDefinition struct {
	Name string `json:"name" minLength:"1" maxLength:"40"`
}

TeamDefinition names a team of a new lobby. A team holds one member.

type WatchAccess

type WatchAccess struct {
	GameKey string `json:"game_key"`
	LobbyID string `json:"lobby_id" format:"uuid"`
	Channel string `` /* 223-byte string literal not displayed */
	Member  bool   `` /* 154-byte string literal not displayed */
}

WatchAccess tells a person who asked to watch where the lobby's game arrives for watchers.

type WatchLobbyBody

type WatchLobbyBody struct {
	GameKey  string `json:"game_key" pattern:"^[a-z][a-z0-9-]{0,31}$"`
	JoinCode string `json:"join_code" minLength:"8" maxLength:"8"`
}

type WatchLobbyInput

type WatchLobbyInput struct {
	Body WatchLobbyBody `json:"-"`
}

type WatchLobbyOutput

type WatchLobbyOutput struct {
	Body WatchAccess `json:"-"`
}

type Watcher

type Watcher struct {
	PlayerID    string    `json:"player_id" format:"uuid" doc:"The watcher's player ID, for kicking them."`
	DisplayName string    `json:"display_name"`
	JoinedAt    time.Time `json:"joined_at" doc:"When they started watching."`
}

type WatcherList

type WatcherList struct {
	Watchers []Watcher `json:"watchers" nullable:"false" doc:"The watchers the host hasn't kicked, in the order they started watching."`
}

type WatchersOutput

type WatchersOutput struct {
	Body WatcherList `json:"-"`
}

Jump to

Keyboard shortcuts

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