@diffenderfer-games/hub-contract 2.0.0-next.0 → 2.0.0-next.2

package/src/api/mp/rooms.ts

@@ -1,90 +1,122 @@
-/**
- * Hub relay rooms (multiplayer-impl.md §6): realtime multiplayer for static
- * games, relayed (never refereed) by the hub. A race is a room with a
- * `race` block on top. Shared by the `room.*` / `race.*` ops and events and
- * the `hello` snapshot.
- */
-import { z } from 'zod';
-import { Json, Slug, UserId } from '../../common';
-import { ChatMode } from '../../entities';
-import { GameMode, OpaqueId } from './parties';
-import { RaceState } from './races';
-
-/** A room's join code: 5 characters from `A-Z` and `2-9` (no `I`, `O`, `0`, `1`). */
-export const RoomCode = z.string().regex(/^[A-HJ-NP-Z2-9]{5}$/);
-
-/** A room's lifecycle: new players join only in the lobby. */
-export const RoomPhase = z.enum(['lobby', 'playing', 'ended']);
-
-/**
- * Who hears a send. `host` (default): guests' unaddressed sends reach the
- * host only. `relay`: every unaddressed send reaches everyone, sender
- * included.
- */
-export const RoomModel = z.enum(['host', 'relay']);
-
-/** A seat in a room, keyed by user (any tab of that user reclaims it). */
-export const RoomSeat = z.object({
-  userId: UserId,
-  /** The player's username when they sat down. */
-  name: z.string(),
-  /** Avatar token; never empty. */
-  avatar: z.string(),
-  ready: z.boolean(),
-  /** `false` while the seat is held for a dropped player's reconnect grace. */
-  connected: z.boolean(),
-  /** Small per-seat game data (team, colour…), at most 2 KB of JSON. */
-  data: Json.optional(),
-});
-
-/** The public description of a room (`room` event, room and race acks, the `hello` snapshot). */
-export const RoomInfo = z.object({
-  id: OpaqueId,
-  code: RoomCode,
-  game: Slug,
-  /** `race` for race rooms. */
-  mode: GameMode.optional(),
-  hostId: UserId,
-  /** Listed in `room.list` / `race.list`. */
-  public: z.boolean(),
-  phase: RoomPhase,
-  maxPlayers: z.number().int().positive(),
-  model: RoomModel,
-  seats: z.array(RoomSeat),
-  /** How many are watching. */
-  spectators: z.number().int().nonnegative(),
-  /** The chat mode for the seated players. */
-  chatMode: ChatMode,
-  /** Present on race rooms. */
-  race: RaceState.optional(),
-});
-
-/** A room. */
-export type RoomInfo = z.infer<typeof RoomInfo>;
-
-/** A room's shared state for late joiners: a JSON object, at most 32 KB. */
-export const RoomState = z.record(z.string(), Json);
-
-/** A relayed game message (`room.msg`, and a join's replay history). */
-export const RoomMessage = z.object({
-  from: UserId,
-  data: Json,
-  /** Per-room sequence number, shared with state patches. */
-  seq: z.number().int().positive(),
-  /** Set when the message went to one seat only. */
-  to: UserId.optional(),
-});
-
-/** How to find a room: by its code (case-insensitive) or its id. */
-export const RoomTarget = z.object({
-  code: z.string().optional(),
-  id: z.string().optional(),
-  /** Watch instead of taking a seat (if the game allows spectators). */
-  spectate: z.boolean().optional(),
-});
-
-/** Why a room went away for this tab (`room.closed`). */
-export const RoomClosedReason = z.enum(['empty', 'ended', 'host_left', 'moved', 'other_tab', 'removed']);
-
-/** Why a seat was freed (`room.abandoned`). */
-export const SeatGoneReason = z.enum(['left', 'abandoned', 'kicked']);
+/**
+ * Hub relay rooms (multiplayer-impl.md §6): realtime multiplayer for static
+ * games, relayed (never refereed) by the hub. A race is a room with a
+ * `race` block on top. Shared by the `room.*` / `race.*` ops and events and
+ * the `hello` snapshot.
+ */
+import { z } from 'zod';
+import { Json, Millis, Slug, UserId } from '../../common';
+import { ChatMode } from '../../entities';
+import { GameMode, OpaqueId } from './parties';
+import { RaceState } from './races';
+
+/** A room's join code: 5 characters from `A-Z` and `2-9` (no `I`, `O`, `0`, `1`). */
+export const RoomCode = z.string().regex(/^[A-HJ-NP-Z2-9]{5}$/);
+
+/** A room's lifecycle: new players join only in the lobby. */
+export const RoomPhase = z.enum(['lobby', 'playing', 'ended']);
+
+/**
+ * Who hears a send. `host` (default): guests' unaddressed sends reach the
+ * host only. `relay`: every unaddressed send reaches everyone, sender
+ * included.
+ */
+export const RoomModel = z.enum(['host', 'relay']);
+
+/**
+ * When the host role moves on mid-game. `grace` (default): only once the
+ * host's seat is freed (they left, or their reconnect grace ran out), so a
+ * host whose browser holds hidden state can come back and carry on. `drop`:
+ * as soon as the host drops, for games whose whole truth is in the shared
+ * state, so the match never waits.
+ */
+export const HostMigration = z.enum(['grace', 'drop']);
+
+/** A seat in a room, keyed by user (any tab of that user reclaims it). */
+export const RoomSeat = z.object({
+  userId: UserId,
+  /** The player's username when they sat down. */
+  name: z.string(),
+  /** Avatar token; never empty. */
+  avatar: z.string(),
+  ready: z.boolean(),
+  /** `false` while the seat is held for a dropped player's reconnect grace. */
+  connected: z.boolean(),
+  /** While the seat is held (`connected: false`): when the grace runs out and the seat is freed (epoch ms). */
+  graceEndsAt: Millis.optional(),
+  /** Small per-seat game data (team, colour…), at most 2 KB of JSON. */
+  data: Json.optional(),
+});
+
+/** The public description of a room (`room` event, room and race acks, the `hello` snapshot). */
+export const RoomInfo = z.object({
+  id: OpaqueId,
+  code: RoomCode,
+  game: Slug,
+  /** `race` for race rooms. */
+  mode: GameMode.optional(),
+  hostId: UserId,
+  /** Listed in `room.list` / `race.list`. */
+  public: z.boolean(),
+  phase: RoomPhase,
+  maxPlayers: z.number().int().positive(),
+  model: RoomModel,
+  seats: z.array(RoomSeat),
+  /** How many are watching. */
+  spectators: z.number().int().nonnegative(),
+  /** The chat mode for the seated players. */
+  chatMode: ChatMode,
+  /** Present on race rooms. */
+  race: RaceState.optional(),
+});
+
+/** A room. */
+export type RoomInfo = z.infer<typeof RoomInfo>;
+
+/** A room's shared state for late joiners: a JSON object, at most 32 KB. */
+export const RoomState = z.record(z.string(), Json);
+
+/** A relayed game message (`room.msg`, and a join's replay history). */
+export const RoomMessage = z.object({
+  from: UserId,
+  data: Json,
+  /** Per-room sequence number, shared with state patches. */
+  seq: z.number().int().positive(),
+  /** Set when the message went to one seat only. */
+  to: UserId.optional(),
+});
+
+/** How to find a room: by its code (case-insensitive) or its id. */
+export const RoomTarget = z.object({
+  code: z.string().optional(),
+  id: z.string().optional(),
+  /** Watch instead of taking a seat (if the game allows spectators). */
+  spectate: z.boolean().optional(),
+});
+
+/** Why a room went away for this tab (`room.closed`). */
+export const RoomClosedReason = z.enum(['empty', 'ended', 'host_left', 'moved', 'other_tab', 'removed']);
+
+/** Why a seat was freed (`room.abandoned`, `room.seat` `gone`). */
+export const SeatGoneReason = z.enum(['left', 'abandoned', 'kicked']);
+
+/**
+ * What happened to a seat (`room.seat`): `away` (the player dropped; the seat
+ * is held until `graceEndsAt`, so the game can hand it to its computer
+ * player), `back` (they reclaimed it: give control back), `gone` (freed for
+ * good: left, kicked, or the grace ran out).
+ */
+export const SeatStatus = z.enum(['away', 'back', 'gone']);
+
+/** A seat change (`room.seat`). */
+export const SeatChange = z.object({
+  userId: UserId,
+  status: SeatStatus,
+  /** `away`: when the held seat is freed (epoch ms). */
+  graceEndsAt: Millis.optional(),
+  /** `gone`: why. */
+  reason: SeatGoneReason.optional(),
+});
+
+/** A seat change. */
+export type SeatChange = z.infer<typeof SeatChange>;

package/src/api/mp/snapshot.ts

@@ -1,17 +1,17 @@
-/** The multiplayer part of the socket `hello` snapshot (multiplayer-impl.md §4.5). */
-import { z } from 'zod';
-import { Invite, Party } from './parties';
-import { RoomInfo } from './rooms';
-
-/**
- * The multiplayer fields of the `hello` ack, to spread into the snapshot
- * schema (`z.object({ ...other, ...MultiplayerSnapshot.shape })`).
- */
-export const MultiplayerSnapshot = z.object({
-  /** Pending invites addressed to me. */
-  invites: z.array(Invite),
-  /** The party I'm in, or `null`. */
-  party: Party.nullable(),
-  /** The room seat I still hold (not ended), or `null`; `room.join` it again to reconnect. */
-  room: RoomInfo.nullable(),
-});
+/** The multiplayer part of the socket `hello` snapshot (multiplayer-impl.md §4.5). */
+import { z } from 'zod';
+import { Invite, Party } from './parties';
+import { RoomInfo } from './rooms';
+
+/**
+ * The multiplayer fields of the `hello` ack, to spread into the snapshot
+ * schema (`z.object({ ...other, ...MultiplayerSnapshot.shape })`).
+ */
+export const MultiplayerSnapshot = z.object({
+  /** Pending invites addressed to me. */
+  invites: z.array(Invite),
+  /** The party I'm in, or `null`. */
+  party: Party.nullable(),
+  /** The room seat I still hold (not ended), or `null`; `room.join` it again to reconnect. */
+  room: RoomInfo.nullable(),
+});

package/src/api/mp.ts

@@ -1,110 +1,135 @@
-/**
- * Multiplayer REST (multiplayer-impl.md §5.6): invites, launch tokens,
- * parties, joining a friend's game, and game-server tickets. Every route
- * needs an active account; invites need a claimed one. The live state is in
- * the hub's memory and changes are pushed over `/_ws` (`invite`,
- * `invite.update`, `party`).
- */
-import { z } from 'zod';
-import { Millis, Ok, Slug, UserIdParam } from '../common';
-import { ErrorBody } from '../errors';
-import { requireActive, requireClaimed } from '../middleware';
-import { GameMode, Invite, JoinInfo, Launch, LaunchTicket, OpaqueId } from './mp/parties';
-
-export * from './mp/chat';
-export * from './mp/parties';
-export * from './mp/races';
-export * from './mp/rooms';
-export * from './mp/snapshot';
-
-/** `:id` of an invite or party. */
-const IdParams = z.object({ id: OpaqueId });
-
-/** The answer to `POST /mp/invites`: the invite, plus the inviter's own `host` launch. */
-export const InviteCreated = LaunchTicket.extend({ invite: Invite });
-
-/** A game-server identity ticket. */
-export const GameTicket = z.object({
-  /** `base64url(payload).base64url(hmac)`, verified offline by the game's server with `HUB_APP_KEY`. */
-  ticket: z.string(),
-  /** Epoch ms; tickets live 60 s. */
-  expiresAt: Millis,
-});
-
-/** The mp endpoints. */
-export const mpEndpoints = {
-  ...requireClaimed.group({
-    sendGameInvite: {
-      method: 'POST', path: '/mp/invites',
-      body: z.object({
-        /** The friend to invite. */
-        to: UserIdParam,
-        game: Slug,
-        /** One of the game's modes; race-only games default to `race`. */
-        mode: GameMode.nullish(),
-      }),
-      response: InviteCreated,
-      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody, 429: ErrorBody },
-      doc: {
-        summary: 'Invite a friend to a game; creates or reuses your party and returns your host launch',
-        tags: ['mp'],
-      },
-    },
-    acceptGameInvite: {
-      method: 'POST', path: '/mp/invites/:id/accept', params: IdParams, response: LaunchTicket,
-      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody },
-      doc: { summary: "Accept an invite: join the inviter's party and get a guest launch", tags: ['mp'] },
-    },
-    declineGameInvite: {
-      method: 'POST', path: '/mp/invites/:id/decline', params: IdParams, response: Ok,
-      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
-      doc: { summary: 'Decline an invite addressed to you', tags: ['mp'] },
-    },
-    cancelGameInvite: {
-      method: 'DELETE', path: '/mp/invites/:id', params: IdParams, response: Ok,
-      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
-      doc: { summary: 'Cancel an invite you sent', tags: ['mp'] },
-    },
-  }),
-  ...requireActive.group({
-    redeemLaunchToken: {
-      method: 'GET', path: '/mp/launch/:token', params: z.object({ token: z.string() }),
-      response: z.object({ launch: Launch }),
-      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
-      doc: { summary: 'Redeem a launch token (single use, bound to the signed-in user)', tags: ['mp'] },
-    },
-    setPartyJoinInfo: {
-      method: 'POST', path: '/mp/parties/:id/join-info', params: IdParams,
-      body: z.object({ info: JoinInfo }),
-      response: Ok,
-      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
-      doc: { summary: 'Party leader: publish where the party should connect', tags: ['mp'] },
-    },
-    leaveParty: {
-      method: 'POST', path: '/mp/parties/:id/leave', params: IdParams, response: Ok,
-      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
-      doc: { summary: 'Leave a party (the leader role passes on; an empty party dissolves)', tags: ['mp'] },
-    },
-    launchIntoFriendsRoom: {
-      method: 'POST', path: '/mp/join',
-      body: z.object({
-        /** The player whose game to join or watch. */
-        userId: UserIdParam,
-        /** Watch instead of play. */
-        watch: z.boolean().optional(),
-        /** Joining a stranger's public lobby from a `lobby_open` alert (not a friend's game). */
-        fromLobbyOpen: z.boolean().optional(),
-      }),
-      response: LaunchTicket,
-      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody, 429: ErrorBody },
-      doc: { summary: "A Join or Watch launch into the room a friend's presence advertises", tags: ['mp'] },
-    },
-    getGameServerTicket: {
-      method: 'POST', path: '/mp/ticket',
-      body: z.object({ slug: Slug }),
-      response: GameTicket,
-      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 429: ErrorBody },
-      doc: { summary: "A 60 s identity ticket for a game's own server", tags: ['mp'] },
-    },
-  }),
-};
+/**
+ * Multiplayer REST (multiplayer-impl.md §5.6): invites, launch tokens,
+ * parties, joining a friend's game, and game-server tickets. Every route
+ * needs an active account; invites need a claimed one. The live state is in
+ * the hub's memory and changes are pushed over `/_ws` (`invite`,
+ * `invite.update`, `party`).
+ */
+import { z } from 'zod';
+import { Millis, Ok, Slug, UserIdParam } from '../common';
+import { ErrorBody } from '../errors';
+import { requireActive, requireClaimed } from '../middleware';
+import { InviteLink, InviteLinkCreate, InviteLinkParams, InviteLinkQuery } from './mp/invite-links';
+import { GameMode, Invite, JoinInfo, Launch, LaunchTicket, OpaqueId } from './mp/parties';
+
+export * from './mp/chat';
+export * from './mp/invite-links';
+export * from './mp/parties';
+export * from './mp/races';
+export * from './mp/rooms';
+export * from './mp/snapshot';
+
+/** `:id` of an invite or party. */
+const IdParams = z.object({ id: OpaqueId });
+
+/** The answer to `POST /mp/invites`: the invite, plus the inviter's own `host` launch. */
+export const InviteCreated = LaunchTicket.extend({ invite: Invite });
+
+/** A game-server identity ticket. */
+export const GameTicket = z.object({
+  /** `base64url(payload).base64url(hmac)`, verified offline by the game's server with `HUB_APP_KEY`. */
+  ticket: z.string(),
+  /** Epoch ms; tickets live 60 s. */
+  expiresAt: Millis,
+});
+
+/** The mp endpoints. */
+export const mpEndpoints = {
+  ...requireClaimed.group({
+    sendGameInvite: {
+      method: 'POST', path: '/mp/invites',
+      body: z.object({
+        /** The friend to invite. */
+        to: UserIdParam,
+        game: Slug,
+        /** One of the game's modes; race-only games default to `race`. */
+        mode: GameMode.nullish(),
+      }),
+      response: InviteCreated,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody, 429: ErrorBody },
+      doc: {
+        summary: 'Invite a friend to a game; creates or reuses your party and returns your host launch',
+        tags: ['mp'],
+      },
+    },
+    acceptGameInvite: {
+      method: 'POST', path: '/mp/invites/:id/accept', params: IdParams, response: LaunchTicket,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody },
+      doc: { summary: "Accept an invite: join the inviter's party and get a guest launch", tags: ['mp'] },
+    },
+    declineGameInvite: {
+      method: 'POST', path: '/mp/invites/:id/decline', params: IdParams, response: Ok,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Decline an invite addressed to you', tags: ['mp'] },
+    },
+    createInviteLink: {
+      method: 'POST', path: '/mp/links', body: InviteLinkCreate, response: InviteLink,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody, 429: ErrorBody },
+      doc: {
+        summary: "An invite link to the room I'm in (reused while it lives): anyone who opens it joins, or watches when it's full",
+        tags: ['mp'],
+      },
+    },
+    listInviteLinks: {
+      method: 'GET', path: '/mp/links', query: InviteLinkQuery, response: z.object({ links: z.array(InviteLink) }),
+      errors: { 401: ErrorBody, 403: ErrorBody },
+      doc: { summary: 'My live invite links in a game, plus the links to rooms I host', tags: ['mp'] },
+    },
+    revokeInviteLink: {
+      method: 'DELETE', path: '/mp/links/:token', params: InviteLinkParams, response: Ok,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: "Revoke an invite link (its creator, or the host of the room it opens)", tags: ['mp'] },
+    },
+    cancelGameInvite: {
+      method: 'DELETE', path: '/mp/invites/:id', params: IdParams, response: Ok,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Cancel an invite you sent', tags: ['mp'] },
+    },
+  }),
+  ...requireActive.group({
+    redeemLaunchToken: {
+      method: 'GET', path: '/mp/launch/:token', params: z.object({ token: z.string() }),
+      response: z.object({ launch: Launch }),
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Redeem a launch token (single use, bound to the signed-in user)', tags: ['mp'] },
+    },
+    openInviteLink: {
+      method: 'POST', path: '/mp/links/:token/open', params: InviteLinkParams, response: LaunchTicket,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody, 429: ErrorBody },
+      doc: { summary: 'Open an invite link: a join launch when a seat is free, else a watch launch', tags: ['mp'] },
+    },
+    setPartyJoinInfo: {
+      method: 'POST', path: '/mp/parties/:id/join-info', params: IdParams,
+      body: z.object({ info: JoinInfo }),
+      response: Ok,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Party leader: publish where the party should connect', tags: ['mp'] },
+    },
+    leaveParty: {
+      method: 'POST', path: '/mp/parties/:id/leave', params: IdParams, response: Ok,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Leave a party (the leader role passes on; an empty party dissolves)', tags: ['mp'] },
+    },
+    launchIntoFriendsRoom: {
+      method: 'POST', path: '/mp/join',
+      body: z.object({
+        /** The player whose game to join or watch. */
+        userId: UserIdParam,
+        /** Watch instead of play. */
+        watch: z.boolean().optional(),
+        /** Joining a stranger's public lobby from a `lobby_open` alert (not a friend's game). */
+        fromLobbyOpen: z.boolean().optional(),
+      }),
+      response: LaunchTicket,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody, 429: ErrorBody },
+      doc: { summary: "A Join or Watch launch into the room a friend's presence advertises", tags: ['mp'] },
+    },
+    getGameServerTicket: {
+      method: 'POST', path: '/mp/ticket',
+      body: z.object({ slug: Slug }),
+      response: GameTicket,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 429: ErrorBody },
+      doc: { summary: "A 60 s identity ticket for a game's own server", tags: ['mp'] },
+    },
+  }),
+};