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
- func BoundErrorDetails(_ huma.Context, _ string, v any) (any, error)
- func LimitErrorDetails(details []*huma.ErrorDetail) []*huma.ErrorDetail
- func Register(api huma.API, app domain.Application, authenticator domain.Authenticator, ...)
- func RegisterGameAPI(api huma.API, games domain.GameAPI, secrets GameSecrets)
- func RegisterGameBinding[Result any](api huma.API, operation huma.Operation, ...)
- type Account
- type AccountInput
- type AccountOutput
- type AccountSession
- type AddSeatBody
- type AddSeatInput
- type ChangeSettingsBody
- type ChangeSettingsInput
- type ConnectionToken
- type ConnectionTokenInput
- type ConnectionTokenOutput
- type CreateGoogleSessionBody
- type CreateGoogleSessionInput
- type CreateGoogleSessionOutput
- type CreateLobbyBody
- type CreateLobbyInput
- type CreateLobbyOutput
- type CreateSessionBody
- type CreateSessionInput
- type CreateSessionOutput
- type DeleteAccountInput
- type EmptyOutput
- type GameProblem
- type GameSecrets
- type GameSettings
- type GuestSession
- type HeartbeatBody
- type HeartbeatInput
- type HeartbeatOutput
- type HeartbeatResult
- type IssuePlayerTokenBody
- type IssuePlayerTokenInput
- type IssuePlayerTokenOutput
- type JoinLobbyBody
- type JoinLobbyInput
- type JoinLobbyOutput
- type KickWatcherInput
- type LeaveInput
- type Lobby
- type LobbyInvalidation
- type Member
- type MemberMemberSettings
- type MemberSeatSettings
- type MemberSettings
- type MemberSettingsBody
- type MemberSettingsInput
- type NullableUUID
- type PlayerToken
- type Problem
- type PublicKeysInput
- type PublicKeysOutput
- type ReadyBody
- type ReadyInput
- type ReleaseLeaseInput
- type RemoveSeatInput
- type ReopenInput
- type ScopeInput
- type SeatSettings
- type SelectTeamBody
- type SelectTeamInput
- type SignInSettings
- type SignInSettingsInput
- type SignInSettingsOutput
- type Snapshot
- type SnapshotOutput
- type StartInput
- type StartRosterEntry
- type StartRules
- type Team
- type TeamDefinition
- type UpdateAccountBody
- type UpdateAccountInput
- type WatchAccess
- type WatchLobbyBody
- type WatchLobbyInput
- type WatchLobbyOutput
- type Watcher
- type WatcherList
- type WatchersOutput
Constants ¶
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".
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 ¶
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, accounts domain.Accounts, retention domain.RetentionRunner)
Register installs the public lobby API. app, authenticator, issuer, playerTokens, accounts 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. A nil accounts turns sign-in off.
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 Account ¶ added in v0.6.0
type Account struct {
ID string `json:"id" format:"uuid"`
DisplayName string `json:"display_name"`
CreatedAt time.Time `json:"created_at"`
}
Account is a signed-in person's account as its owner sees it.
type AccountInput ¶ added in v0.6.0
type AccountInput struct{}
type AccountOutput ¶ added in v0.6.0
type AccountOutput struct {
Body Account `json:"-"`
}
type AccountSession ¶ added in v0.6.0
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 ConnectionTokenInput ¶
type ConnectionTokenInput struct {
Body struct{} `json:"-"`
}
type ConnectionTokenOutput ¶
type ConnectionTokenOutput struct {
Body ConnectionToken `json:"-"`
}
type CreateGoogleSessionBody ¶ added in v0.6.0
type CreateGoogleSessionInput ¶ added in v0.6.0
type CreateGoogleSessionInput struct {
Body CreateGoogleSessionBody `json:"-"`
}
type CreateGoogleSessionOutput ¶ added in v0.6.0
type CreateGoogleSessionOutput struct {
Body AccountSession `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 DeleteAccountInput ¶ added in v0.6.0
type DeleteAccountInput struct{}
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 ¶
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) UnmarshalJSON ¶
func (settings *GameSettings) UnmarshalJSON(data []byte) error
type GuestSession ¶
type HeartbeatBody ¶
type HeartbeatInput ¶
type HeartbeatInput struct {
ScopeInput
Body HeartbeatBody `json:"-"`
}
type HeartbeatOutput ¶
type HeartbeatOutput struct {
Body HeartbeatResult `json:"-"`
}
type HeartbeatResult ¶
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 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 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"`
SignedIn bool `` /* 197-byte string literal not displayed */
}
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) 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) 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) 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) UnmarshalJSON ¶
func (value *NullableUUID) UnmarshalJSON(data []byte) error
type PlayerToken ¶
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 `` /* 392-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 ¶
type PublicKeysInput ¶
type PublicKeysInput struct{}
type PublicKeysOutput ¶
type PublicKeysOutput struct {
CacheControl string `header:"Cache-Control"`
Body playertoken.JWKS
}
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 ScopeInput ¶
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) 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 SignInSettings ¶ added in v0.6.0
type SignInSettings struct {
GoogleClientID *string `` /* 126-byte string literal not displayed */
}
type SignInSettingsInput ¶ added in v0.6.0
type SignInSettingsInput struct{}
type SignInSettingsOutput ¶ added in v0.6.0
type SignInSettingsOutput struct {
Body SignInSettings `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 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 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 UpdateAccountBody ¶ added in v0.6.0
type UpdateAccountBody struct {
DisplayName string `` /* 188-byte string literal not displayed */
}
type UpdateAccountInput ¶ added in v0.6.0
type UpdateAccountInput struct {
Body UpdateAccountBody `json:"-"`
}
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 WatchLobbyInput ¶
type WatchLobbyInput struct {
Body WatchLobbyBody `json:"-"`
}
type WatchLobbyOutput ¶
type WatchLobbyOutput struct {
Body WatchAccess `json:"-"`
}
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:"-"`
}