v0.13.0 web and terminal client enhance, replay api, linux server deploy, doc and dependency update

internal/server/core/api.go

@@ -19,20 +19,40 @@ type MoveRequest struct {
 	Move string `json:"move" validate:"required,min=4,max=5"` // "cccc" for computer move, 4-5 chars for UCI moves
 }
 
+// ResignRequest ends the game in the opponent's favor. Color may be omitted
+// when the caller controls exactly one human side.
+type ResignRequest struct {
+	Color string `json:"color,omitempty" validate:"omitempty,oneof=w b white black"`
+}
+
+// DrawRequest offers, accepts, or declines a draw by agreement. Offering to a
+// computer opponent is answered at once.
+type DrawRequest struct {
+	Action string `json:"action" validate:"required,oneof=offer accept decline"`
+	Color  string `json:"color,omitempty" validate:"omitempty,oneof=w b white black"`
+}
+
 type UndoRequest struct {
 	Count int `json:"count" validate:"required,min=1,max=300"` // Max based on longest games in history (272), theoretical max 5949
 }
 
 // Response types
 
+// GameResponse is the live game. Termination names how a finished game ended;
+// DrawOffer is the color whose draw offer awaits an answer; DrawOutcome
+// reports what a draw request did ("offered", "accepted", "declined") and is
+// set only on responses to that request.
 type GameResponse struct {
-	GameID   string          `json:"gameId"`
-	FEN      string          `json:"fen"`
-	Turn     string          `json:"turn"`  // "w" or "b"
-	State    string          `json:"state"` // "ongoing", "white wins", etc
-	Moves    []string        `json:"moves"`
-	Players  PlayersResponse `json:"players"`
-	LastMove *MoveInfo       `json:"lastMove,omitempty"`
+	GameID      string          `json:"gameId"`
+	FEN         string          `json:"fen"`
+	Turn        string          `json:"turn"`  // "w" or "b"
+	State       string          `json:"state"` // "ongoing", "white wins", etc
+	Termination string          `json:"termination,omitempty"`
+	DrawOffer   string          `json:"drawOffer,omitempty"`
+	DrawOutcome string          `json:"drawOutcome,omitempty"`
+	Moves       []string        `json:"moves"`
+	Players     PlayersResponse `json:"players"`
+	LastMove    *MoveInfo       `json:"lastMove,omitempty"`
 }
 
 type MoveInfo struct {
@@ -50,19 +70,28 @@ type BoardResponse struct {
 // GameHistoryResponse is the durable replay representation of a game. Moves
 // are ordered and include the resulting FEN so clients do not need an engine
 // to replay a stored game.
+//
+// PGNResult is the PGN result token ("1-0", "0-1", "1/2-1/2", or "*") and
+// Termination names how a result was reached (see core.Termination; omitted
+// while the game is unfinished).
 type GameHistoryResponse struct {
 	GameID       string          `json:"gameId"`
 	InitialFEN   string          `json:"initialFen"`
 	Result       string          `json:"result,omitempty"`
+	PGNResult    string          `json:"pgnResult"`
+	Termination  string          `json:"termination,omitempty"`
 	StartTimeUTC time.Time       `json:"startTimeUtc"`
 	EndTimeUTC   *time.Time      `json:"endTimeUtc,omitempty"`
 	Players      PlayersResponse `json:"players"`
 	Moves        []HistoryMove   `json:"moves"`
 }
 
+// HistoryMove is one ply. SAN is derived on read and omitted only when the
+// stored move cannot be notated.
 type HistoryMove struct {
 	MoveNumber   int       `json:"moveNumber"`
 	MoveUCI      string    `json:"moveUci"`
+	SAN          string    `json:"san,omitempty"`
 	FENAfterMove string    `json:"fenAfterMove"`
 	PlayerColor  string    `json:"playerColor"`
 	MoveTimeUTC  time.Time `json:"moveTimeUtc"`
@@ -76,17 +105,22 @@ type GameSummary struct {
 	InitialFEN   string          `json:"initialFen"`
 	FinalFEN     string          `json:"finalFen"`
 	Result       string          `json:"result,omitempty"`
+	PGNResult    string          `json:"pgnResult"`
 	StartTimeUTC time.Time       `json:"startTimeUtc"`
 	EndTimeUTC   *time.Time      `json:"endTimeUtc,omitempty"`
 	MoveCount    int             `json:"moveCount"`
 	Players      PlayersResponse `json:"players"`
 }
 
+// GameListResponse pages newest first. NextCursor continues the listing and
+// stays stable while new games are added; NextOffset is kept for clients
+// that page by position and is omitted on cursor requests.
 type GameListResponse struct {
 	Games      []GameSummary `json:"games"`
 	Limit      int           `json:"limit"`
 	Offset     int           `json:"offset"`
 	NextOffset *int          `json:"nextOffset,omitempty"`
+	NextCursor string        `json:"nextCursor,omitempty"`
 }
 
 type ErrorResponse struct {

internal/server/core/state.go

@@ -59,3 +59,45 @@ func (s State) Result() (string, bool) {
 		return "", false
 	}
 }
+
+// Termination names how a game reached its result.
+type Termination string
+
+const (
+	TermNone                 Termination = ""
+	TermCheckmate            Termination = "checkmate"
+	TermStalemate            Termination = "stalemate"
+	TermInsufficientMaterial Termination = "insufficient_material"
+	TermThreefoldRepetition  Termination = "threefold_repetition"
+	TermFiftyMoveRule        Termination = "fifty_move_rule"
+	TermAgreement            Termination = "agreement"
+	TermResignation          Termination = "resignation"
+)
+
+// ValidFor reports whether a termination can produce the terminal state:
+// wins come from checkmate or resignation, stalemate from stalemate, and
+// draws from the draw rules or agreement.
+func (t Termination) ValidFor(s State) bool {
+	switch s {
+	case StateWhiteWins, StateBlackWins:
+		return t == TermCheckmate || t == TermResignation
+	case StateStalemate:
+		return t == TermStalemate
+	case StateDraw:
+		return t == TermInsufficientMaterial || t == TermThreefoldRepetition ||
+			t == TermFiftyMoveRule || t == TermAgreement
+	default:
+		return t == TermNone
+	}
+}
+
+// ParseColor accepts "w", "b", "white", or "black"; anything else is zero.
+func ParseColor(s string) Color {
+	switch s {
+	case "w", "white":
+		return ColorWhite
+	case "b", "black":
+		return ColorBlack
+	}
+	return 0
+}