application

package
v0.6.0 Latest Latest
Warning

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

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

Documentation

Overview

Package application coordinates lobby commands, game binding, and pushing committed changes. Every command applies due lease and grace expiry first, so requests (heartbeats included) and subscription proxy calls drive expiry; no background work runs. It depends on domain contracts; persistence and transports are supplied by callers.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func TransactNormalized

func TransactNormalized(ctx context.Context, store domain.Store, clock domain.Clock, policy domain.Policy, scope domain.Scope, command domain.Mutation) (domain.Aggregate, error)

TransactNormalized commits deadline cleanup even if the requested command is rejected. Commands run on a detached copy so their partial writes cannot leak.

Types

type GameBinding

type GameBinding[Result any] struct {
	// contains filtered or unexported fields
}

GameBinding authorizes each request before invoking game-specific persistence. Result is owned by the game; the lobby imposes no game ID or team representation.

func NewGameBinding

func NewGameBinding[Result any](gameKey string, lobbies domain.SnapshotReader, bind func(context.Context, domain.Snapshot) (Result, error)) (*GameBinding[Result], error)

NewGameBinding accepts a callback that atomically creates or returns the same game for a lobby. It receives a started snapshot with validated, ordered teams and a frozen roster, only after current host authorization succeeds.

func (*GameBinding[Result]) Bind

func (binding *GameBinding[Result]) Bind(ctx context.Context, principal domain.Principal, scope domain.Scope) (Result, error)

type PublishingStore

type PublishingStore struct {
	domain.Store
	// contains filtered or unexported fields
}

PublishingStore pushes every committed change to subscribers before Create or Transact returns, so the request that made a change also delivers it. A push never undoes its commit: the publisher retries briefly and logs what fails.

func NewPublishingStore

func NewPublishingStore(store domain.Store, publisher domain.ChangePublisher) (*PublishingStore, error)

func (*PublishingStore) Create

func (store *PublishingStore) Create(ctx context.Context, principal domain.Principal, request domain.CreateRequest, aggregate domain.Aggregate) (domain.Snapshot, error)

Create announces version 1 of a new room. An idempotent replay announces the original version again, which clients ignore.

func (*PublishingStore) Transact

func (store *PublishingStore) Transact(ctx context.Context, scope domain.Scope, mutation domain.Mutation) (domain.Aggregate, error)

type Retention

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

Retention deletes lobby data past its retention period at the end of requests, since nothing runs between them. A process runs at most one pass at a time, and at most one per PassInterval while passes find no backlog. When a pass fills a batch, the next request runs another, so a backlog drains at the pace of requests without one request doing all of it.

func NewRetention

func NewRetention(store domain.RetentionStore, clock domain.Clock, policy domain.Policy, logger *slog.Logger) (*Retention, error)

func (*Retention) RunIfDue

func (retention *Retention) RunIfDue(ctx context.Context)

RunIfDue runs a pass when one is due and none is running in this process. It outlives a canceled request, within its own timeout, and logs failures instead of returning them, because the request itself has succeeded.

type Service

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

func NewService

func NewService(store domain.Store, clock domain.Clock, identifiers domain.IdentifierSource, policy domain.Policy) (*Service, error)

func (*Service) AddSeat

func (service *Service) AddSeat(ctx context.Context, principal domain.Principal, scope domain.Scope, request domain.AddSeatRequest) (domain.Snapshot, error)

AddSeat adds a seat that no person plays, such as a game's bot, to a team of a waiting lobby. Only the host can add one. The game checks the seat's settings, for the player making the request, and names the seat before the transaction, so it never runs while the room is locked; the host check runs afterwards, inside it. The seat takes its team, which holds no other member, and counts toward the lobby's capacity. It is always ready, holds no lease, and joins the start roster with its own player ID, which the game plays from the seat's settings. A request ID makes a retry safe: the same ID with the same team and settings returns the current snapshot without a second seat, and with others fails with idempotency_conflict.

func (*Service) AuthorizeGameWatch

func (service *Service) AuthorizeGameWatch(ctx context.Context, scope domain.Scope, playerID string) error

AuthorizeGameWatch is AuthorizeWatch for a game that names the player itself, through the game API, rather than through the player's session: it succeeds for an active member or a watcher the host hasn't kicked. A kicked watcher gets watcher_kicked; anyone else, and a lobby that is gone, not_found.

func (*Service) AuthorizeWatch

func (service *Service) AuthorizeWatch(ctx context.Context, principal domain.Principal, scope domain.Scope) error

AuthorizeWatch lets a game open its watcher reads to an active member or a watcher the host hasn't kicked. It reads without locking the room. A kicked watcher gets watcher_kicked; anyone else, and a lobby that is gone, not_found. A game knows its caller from a player token, which names the player but not their session, so only the player ID is checked.

func (*Service) ChangeSettings

func (service *Service) ChangeSettings(ctx context.Context, principal domain.Principal, scope domain.Scope, request domain.ChangeSettingsRequest) (domain.Snapshot, error)

ChangeSettings replaces a waiting lobby's game settings and teams. Only the host can change them. The teams and settings follow the rules of a create request, and the game checks the settings against the new teams before the transaction, so it never runs while the room is locked.

The teams are rebuilt by position: the lobby's first team stays the first, with its ID, and takes the first new name, and so on. New teams are added at the end, and teams beyond the new count are removed: a person on a removed team stays in the lobby without a team, and a seat on a removed team is removed like RemoveSeat removes it. Every person's ready is cleared and the lobby's capacity becomes the new number of teams. A change that leaves more members than teams, such as more people than the new map has teams, fails with lobby_full and changes nothing. Settings and teams equal to the lobby's change nothing.

func (*Service) Create

func (service *Service) Create(ctx context.Context, principal domain.Principal, request domain.CreateRequest) (domain.Snapshot, error)

func (*Service) GameSnapshot

func (service *Service) GameSnapshot(ctx context.Context, scope domain.Scope) (domain.Snapshot, error)

GameSnapshot returns a lobby as its game reads it through the game API: the view of every member, with no player behind it (domain.BuildGameSnapshot), and the game's start rules. It reads without locking the room, so a game can read the lobby while one of its hooks runs, and applies due lease and grace expiry to what it returns without storing it. A lobby that is gone, or one of another game, is not_found.

func (*Service) Heartbeat

func (service *Service) Heartbeat(ctx context.Context, principal domain.Principal, scope domain.Scope, request domain.HeartbeatRequest) (domain.HeartbeatResult, error)

func (*Service) Join

func (service *Service) Join(ctx context.Context, principal domain.Principal, request domain.JoinRequest) (domain.Snapshot, error)

func (*Service) KickWatcher

func (service *Service) KickWatcher(ctx context.Context, principal domain.Principal, scope domain.Scope, playerID string) error

KickWatcher lets the host remove a watcher, in any phase. The watcher is unsubscribed from the watch channel at once, as a departing member is from the room channel, and the join code no longer lets them watch. Kicking a kicked watcher again changes nothing; a player who isn't a watcher of the lobby is not_found.

func (*Service) Leave

func (service *Service) Leave(ctx context.Context, principal domain.Principal, scope domain.Scope) error

func (*Service) ReleaseLease

func (service *Service) ReleaseLease(ctx context.Context, principal domain.Principal, scope domain.Scope, request domain.ReleaseLeaseRequest) error

func (*Service) RemoveSeat

func (service *Service) RemoveSeat(ctx context.Context, principal domain.Principal, scope domain.Scope, seatID string) (domain.Snapshot, error)

RemoveSeat removes a seat that the host added, while the lobby waits. Only the host can remove one. Removing a seat that is already gone changes nothing; an ID that names no seat of the lobby is invalid input.

func (*Service) Reopen

func (service *Service) Reopen(ctx context.Context, principal domain.Principal, scope domain.Scope) (domain.Snapshot, error)

Reopen brings a started lobby whose game ended back to waiting, in its next round, so its members can play another game. Any active person may reopen it. Members, teams, seats, the game settings and member settings stay; every person's ready is cleared, seats stay ready, and the start roster is emptied for the next start. A lobby that already waits is returned unchanged, so two members reopening at once both succeed. A closed lobby, or one whose game declares no GameOver check, fails with phase_conflict, and one whose game hasn't ended with game_running.

The game is asked before the transaction, like the ready gate, so it never reads its data while the room is locked. The transaction then checks that the lobby is still started in the round it asked about; if it moved, it asks again. A game that ended stays ended, so the answer can't go stale within a round.

func (*Service) SelectTeam

func (service *Service) SelectTeam(ctx context.Context, principal domain.Principal, scope domain.Scope, request domain.SelectTeamRequest) (domain.Snapshot, error)

func (*Service) SetMemberSettings

func (service *Service) SetMemberSettings(ctx context.Context, principal domain.Principal, scope domain.Scope, request domain.MemberSettingsRequest) (domain.Snapshot, error)

SetMemberSettings sets the caller's own member settings, a JSON object that only the game reads, such as what plays for them, while the lobby waits. The game checks the settings before the transaction, so it never runs while the room is locked. New settings clear the caller's ready, so a start always sees the settings that the person confirmed by getting ready again. Settings equal to the stored ones change nothing: the version stays and the caller stays ready.

func (*Service) SetReady

func (service *Service) SetReady(ctx context.Context, principal domain.Principal, scope domain.Scope, request domain.ReadyRequest) (domain.Snapshot, error)

func (*Service) Snapshot

func (service *Service) Snapshot(ctx context.Context, principal domain.Principal, scope domain.Scope) (domain.Snapshot, error)

func (*Service) Start

func (service *Service) Start(ctx context.Context, principal domain.Principal, scope domain.Scope) (domain.Snapshot, error)

func (*Service) Unwatch

func (service *Service) Unwatch(ctx context.Context, principal domain.Principal, scope domain.Scope) error

Unwatch removes the caller's watcher row and unsubscribes them from the watch channel. A kicked watcher's row stays, so leaving never clears a kick.

func (*Service) Watch

func (service *Service) Watch(ctx context.Context, principal domain.Principal, request domain.WatchRequest) (domain.WatchAccess, error)

Watch lets anyone with a guest session and the lobby's join code watch the lobby, in any phase: waiting, started or closed. It adds the caller's watcher row, or finds the one they have, and returns the watch channel. A watcher takes no seat and counts toward nothing, so watching never changes capacity, the start roster, leases, grace or retention, and doesn't mark the lobby connected. An active member keeps their member access and gets no watcher row. A code of another game finds no lobby, a watcher the host kicked is refused with watcher_kicked, and a new watcher beyond domain.MaxWatchersPerLobby with watchers_full.

func (*Service) Watchers

func (service *Service) Watchers(ctx context.Context, principal domain.Principal, scope domain.Scope) ([]domain.Watcher, error)

Watchers lists the lobby's watchers, kicked ones left out, in the order they started watching, for its active members.

Jump to

Keyboard shortcuts

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