apologiesserver.interface

Definition of the public interface for the server.

Both requests (message sent from a client to the server) and events (published from the server to one or more clients) can be serialized and deserialized to and from JSON. However, we apply much tighter validation rules on the context associated with requests, since the input is untrusted. We assume that the unit tests and the Python type validations imposed by MyPy give us everything we need for events that are only built internally.

The file docs/design.rst includes a detailed discussion of each request and event.

Module Contents

class apologiesserver.interface.Visibility

Bases: enum.Enum

Visibility for advertised games.

PUBLIC = Public

PRIVATE = Private

class apologiesserver.interface.CancelledReason

Bases: enum.Enum

Reasons a game can be cancelled.

CANCELLED = Game was cancelled by advertiser

NOT_VIABLE = Game is no longer viable.

INACTIVE = The game was idle too long and was marked inactive

SHUTDOWN = Game was cancelled due to system shutdown

class apologiesserver.interface.PlayerType

Bases: enum.Enum

Types of players.

HUMAN = Human

PROGRAMMATIC = Programmatic

class apologiesserver.interface.PlayerState

Bases: enum.Enum

A player’s game state.

WAITING = Waiting

JOINED = Joined

PLAYING = Playing

FINISHED = Finished

QUIT = Quit

DISCONNECTED = Disconnected

class apologiesserver.interface.ConnectionState

Bases: enum.Enum

A player’s connection state.

CONNECTED = Connected

DISCONNECTED = Disconnected

class apologiesserver.interface.ActivityState

Bases: enum.Enum

A player’s activity state.

ACTIVE = Active

IDLE = Idle

INACTIVE = Inactive

class apologiesserver.interface.GameState

Bases: enum.Enum

A game’s state.

ADVERTISED = Advertised

PLAYING = Playing

COMPLETED = Completed

CANCELLED = Cancelled

class apologiesserver.interface.FailureReason

Bases: enum.Enum

Failure reasons advertised to clients.

INVALID_REQUEST = Invalid request

DUPLICATE_USER = Handle is already in use

INVALID_AUTH = Missing or invalid authorization header

WEBSOCKET_LIMIT = Connection limit reached; try again later

USER_LIMIT = System user limit reached; try again later

GAME_LIMIT = System game limit reached; try again later

INVALID_PLAYER = Unknown or invalid player

INVALID_GAME = Unknown or invalid game

NOT_PLAYING = Player is not playing a game

NOT_ADVERTISER = Player did not advertise this game

ALREADY_PLAYING = Player is already playing a game

NO_MOVE_PENDING = No move is pending for this player

ILLEGAL_MOVE = The chosen move is not legal

ADVERTISER_MAY_NOT_QUIT = Advertiser may not quit a game (cancel instead)

INTERNAL_ERROR = Internal error

class apologiesserver.interface.MessageType

Bases: enum.Enum

Enumeration of all message types, including received events and published requests.

REGISTER_PLAYER = Register Player

REREGISTER_PLAYER = Reregister Player

UNREGISTER_PLAYER = Unregister Player

LIST_PLAYERS = List Players

ADVERTISE_GAME = Advertise Game

LIST_AVAILABLE_GAMES = List Available

JOIN_GAME = Join Game

QUIT_GAME = Quit Game

START_GAME = Start Game

CANCEL_GAME = Cancel Game

EXECUTE_MOVE = Execute Move

OPTIMAL_MOVE = Optimal Move

RETRIEVE_GAME_STATE = Retrieve Game State

SEND_MESSAGE = Send Message

SERVER_SHUTDOWN = Server Shutdown

REQUEST_FAILED = Request Failed

REGISTERED_PLAYERS = Registered Players

AVAILABLE_GAMES = Available Games

PLAYER_REGISTERED = Player Registered

PLAYER_UNREGISTERED = Player Unregistered

WEBSOCKET_IDLE = Connection Idle

WEBSOCKET_INACTIVE = Connection Inactive

PLAYER_IDLE = Player Idle

PLAYER_INACTIVE = Player Inactive

PLAYER_MESSAGE_RECEIVED = Player Message Received

GAME_ADVERTISED = Game Advertise

GAME_INVITATION = Game Invitation

GAME_JOINED = Game Joined

GAME_STARTED = Game Started

GAME_CANCELLED = Game Cancelled

GAME_COMPLETED = Game Completed

GAME_IDLE = Game Idle

GAME_INACTIVE = Game Inactive

GAME_PLAYER_QUIT = Game Player Quit

GAME_PLAYER_CHANGE = Game Player Change

GAME_STATE_CHANGE = Game State Change

GAME_PLAYER_TURN = Game Player Turn

exception apologiesserver.interface.ProcessingError

Bases: RuntimeError

Exception thrown when there is a general processing error.

reason :FailureReason

comment :Optional[str]

handle :Optional[str]

__repr__() → str

Return repr(self).

__str__() → str

Return str(self).

class apologiesserver.interface.GamePlayer

The public definition of a player within a game.

handle :str

player_color :Optional[apologies.PlayerColor]

player_type :PlayerType

player_state :PlayerState

class apologiesserver.interface.RegisteredPlayer

The public definition of a player registered with the system.

handle :str

registration_date :pendulum.datetime.DateTime

last_active_date :pendulum.datetime.DateTime

connection_state :ConnectionState

activity_state :ActivityState

player_state :PlayerState

game_id :Optional[str]

class apologiesserver.interface.AdvertisedGame

A game that has been advertised in the system.

game_id :str

name :str

mode :apologies.GameMode

advertiser_handle :str

players :int

available :int

visibility :Visibility

invited_handles :List[str]

class apologiesserver.interface.GameStatePawn

State of a pawn in a game.

color :apologies.PlayerColor

id :str

start :bool

home :bool

safe :Optional[int]

square :Optional[int]

static for_pawn(pawn: apologies.Pawn) → GameStatePawn

Create a GameStatePawn based on apologies.game.Pawn.

static for_position(pawn: apologies.Pawn, position: apologies.Position) → GameStatePawn

Create a GameStatePawn based on apologies.game.Pawn and apologies.gamePosition.

class apologiesserver.interface.GameStatePlayer

Player in a game, when describing the state of the board.

color :apologies.PlayerColor

turns :int

hand :List[apologies.CardType]

pawns :List[GameStatePawn]

static for_player(player: apologies.Player) → GameStatePlayer

Create a GameStatePlayer based on apologies.game.Player.

class apologiesserver.interface.GameStateHistory

History for a game.

action :str

color :Optional[apologies.PlayerColor]

card :Optional[apologies.CardType]

timestamp :pendulum.datetime.DateTime

static for_history(history: apologies.History) → GameStateHistory

class apologiesserver.interface.GameAction

An action applied to a pawn in a game.

start :GameStatePawn

end :GameStatePawn

static for_action(action: apologies.Action) → GameAction

Create a GamePlayerAction based on apologies.rules.Action.

class apologiesserver.interface.GameMove

A move that may be executed as a result of a player’s turn.

move_id :str

card :apologies.CardType

actions :List[GameAction]

side_effects :List[GameAction]

static for_move(move: apologies.Move) → GameMove

Create a GameMove based on apologies.rules.Move.

class apologiesserver.interface.RegisterPlayerContext

Bases: Context

Context for a REGISTER_PLAYER request.

handle :str

class apologiesserver.interface.ReregisterPlayerContext

Bases: Context

Context for a REREGISTER_PLAYER request.

handle :str

class apologiesserver.interface.AdvertiseGameContext

Bases: Context

Context for an ADVERTISE_GAME request.

name :str

mode :apologies.GameMode

players :int

visibility :Visibility

invited_handles :List[str]

class apologiesserver.interface.JoinGameContext

Bases: Context

Context for a JOIN_GAME request.

game_id :str

class apologiesserver.interface.ExecuteMoveContext

Bases: Context

Context for an EXECUTE_MOVE request.

move_id :str

class apologiesserver.interface.SendMessageContext

Bases: Context

Context for an SEND_MESSAGE request.

message :str

recipient_handles :List[str]

class apologiesserver.interface.RequestFailedContext

Bases: Context

Context for a REQUEST_FAILED event.

reason :FailureReason

comment :Optional[str]

handle :Optional[str]

class apologiesserver.interface.RegisteredPlayersContext

Bases: Context

Context for a REGISTERED_PLAYERS event.

players :List[RegisteredPlayer]

class apologiesserver.interface.AvailableGamesContext

Bases: Context

Context for an AVAILABLE_GAMES event.

games :List[AdvertisedGame]

class apologiesserver.interface.PlayerRegisteredContext

Bases: Context

Context for a PLAYER_REGISTERED event.

handle :str

class apologiesserver.interface.PlayerUnregisteredContext

Bases: Context

Context for a PLAYER_UNREGISTERED event.

handle :str

class apologiesserver.interface.PlayerIdleContext

Bases: Context

Context for a PLAYER_IDLE event.

handle :str

class apologiesserver.interface.PlayerInactiveContext

Bases: Context

Context for a PLAYER_INACTIVE event.

handle :str

class apologiesserver.interface.PlayerMessageReceivedContext

Bases: Context

Context for a PLAYER_MESSAGE_RECEIVED event.

sender_handle :str

recipient_handles :List[str]

message :str

class apologiesserver.interface.GameAdvertisedContext

Bases: Context

Context for a GAME_ADVERTISED event.

game :AdvertisedGame

class apologiesserver.interface.GameInvitationContext

Bases: Context

Context for a GAME_INVITATION event.

game :AdvertisedGame

class apologiesserver.interface.GameJoinedContext

Bases: Context

Context for a GAME_JOINED event.

player_handle :str

game_id :str

name :str

mode :apologies.GameMode

advertiser_handle :str

class apologiesserver.interface.GameStartedContext

Bases: Context

Context for a GAME_STARTED event.

game_id :str

class apologiesserver.interface.GameCancelledContext

Bases: Context

Context for a GAME_CANCELLED event.

game_id :str

reason :CancelledReason

comment :Optional[str]

class apologiesserver.interface.GameCompletedContext

Bases: Context

Context for a GAME_COMPLETED event.

game_id :str

winner :str

comment :str

class apologiesserver.interface.GameIdleContext

Bases: Context

Context for a GAME_IDLE event.

game_id :str

class apologiesserver.interface.GameInactiveContext

Bases: Context

Context for a GAME_INACTIVE event.

game_id :str

class apologiesserver.interface.GamePlayerQuitContext

Bases: Context

Context for a GAME_PLAYER_LEFT event.

handle :str

game_id :str

class apologiesserver.interface.GamePlayerChangeContext

Bases: Context

Context for a GAME_PLAYER_CHANGE event.

game_id :str

comment :Optional[str]

players :List[GamePlayer]

class apologiesserver.interface.GameStateChangeContext

Bases: Context

Context for a GAME_STATE_CHANGE event.

game_id :str

recent_history :List[GameStateHistory]

player :GameStatePlayer

opponents :List[GameStatePlayer]

static for_context(game_id: str, view: apologies.PlayerView, history: List[apologies.History]) → GameStateChangeContext

Create a GameStateChangeContext based on apologies.game.PlayerView.

class apologiesserver.interface.GamePlayerTurnContext

Bases: Context

Context for a GAME_PLAYER_TURN event.

handle :str

game_id :str

drawn_card :Optional[apologies.CardType]

moves :Dict[str, GameMove]

static for_moves(handle: str, game_id: str, moves: List[apologies.Move]) → GamePlayerTurnContext

Create a GamePlayerTurnContext based on a sequence of apologies.rules.Move.

class apologiesserver.interface.Message

A message that is part of the public interface, either a client request or a published event.

message :MessageType

player_id :Optional[str]

context :Any

to_json() → str

Convert the request to JSON.

static for_json(data: str) → Message

Create a request based on JSON data.