@diffenderfer-games/hub-contract 0.0.0-stage → 2.0.0-next.1

package/src/realtime/ops/races.ts

@@ -0,0 +1,99 @@
+/**
+ * Race ops (docs/plans/race.md §4). A race is a hub room with a referee: the
+ * countdown starts when every seat is filled, the seed is revealed with it,
+ * and the first valid finish wins. Reports come from browsers, so the hub
+ * measures time itself and enforces what it can (`minMs`, one result each).
+ */
+import { z } from 'zod';
+import { Slug } from '../../common';
+import { OpaqueId } from '../../api/mp/parties';
+import { RaceParams, RaceProgress, RaceResult, RaceStats } from '../../api/mp/races';
+import { RoomInfo, RoomTarget } from '../../api/mp/rooms';
+import { op, type OpDef } from '../define';
+import { EmptyAck, NoInput } from './empty';
+
+/** A racer's report (status, finish, lose): stats (`null` means none) and optional 0..1 progress. */
+const RaceReport = z.object({
+  stats: RaceStats.nullish(),
+  progress: RaceProgress.nullish(),
+});
+
+/** The refusal a malformed report gets (old wording). */
+const BAD_STATS = { code: 'bad_stats', error: 'Race stats must be numbers, true/false or #rrggbb colours.' } as const;
+
+/** A race room ack. */
+const RoomAck = z.object({ room: RoomInfo });
+
+/** The race ops, by op name. */
+export const raceOps = {
+  'race.create': op({
+    d: z.object({
+      game: Slug,
+      /** The creator's choices; undeclared keys and values fall back to the defaults. */
+      params: RaceParams.optional(),
+      /** Shown in Open races and can alert followers (default true). */
+      public: z.boolean().optional(),
+      /** Seats, within the game's `race.players` (default its min). */
+      maxPlayers: z.number().optional(),
+      /** The caller's party: when they lead it, its join info becomes `{ room: code }`. */
+      partyId: OpaqueId.optional(),
+    }),
+    ack: RoomAck,
+    errors: ['not_race', 'too_many_rooms'],
+    doc: 'Open a race room with the caller seated; the countdown starts once every seat is filled.',
+  }),
+  'race.join': op({
+    d: RoomTarget,
+    ack: RoomAck,
+    errors: ['room_not_found', 'banned', 'in_progress', 'room_full', 'not_multiplayer', 'not_supported'],
+    doc: 'Join (or watch) a race room, like `room.join` but only for races.',
+  }),
+  'race.list': op({
+    d: z.object({ game: Slug }),
+    ack: z.object({ rooms: z.array(RoomInfo) }),
+    errors: [],
+    doc: 'Public races waiting for racers (at most 50), minus rooms with blocked players.',
+  }),
+  'race.start': op({
+    d: NoInput,
+    ack: EmptyAck,
+    errors: ['not_in_race', 'not_host', 'in_progress', 'not_ready'],
+    doc: 'Creator: start the countdown early once the minimum racers are in.',
+  }),
+  'race.status': op({
+    d: RaceReport,
+    ack: EmptyAck,
+    errors: ['not_in_race', 'not_started', 'race_over', 'rate_limited', 'bad_stats'],
+    invalid: BAD_STATS,
+    doc: 'Live status for the race HUD. Numbers, booleans and #rrggbb only: never text.',
+  }),
+  'race.finish': op({
+    d: RaceReport,
+    ack: z.object({ result: RaceResult }),
+    errors: ['not_in_race', 'not_started', 'race_over', 'too_fast', 'bad_stats'],
+    invalid: BAD_STATS,
+    doc: 'Report a finish with final stats; the first valid finish wins the race.',
+  }),
+  'race.lose': op({
+    d: RaceReport,
+    ack: EmptyAck,
+    errors: ['not_in_race', 'not_started', 'race_over', 'bad_stats'],
+    invalid: BAD_STATS,
+    doc: 'Game over for this racer (out of lives, stuck…); the last racer left wins.',
+  }),
+  'race.forfeit': op({
+    d: NoInput,
+    ack: EmptyAck,
+    errors: ['not_in_race', 'race_over'],
+    doc: 'Give up (leaving the room mid-race counts the same).',
+  }),
+  'race.rematch': op({
+    d: z.object({
+      /** Creator only: params for the next round. */
+      params: RaceParams.optional(),
+    }),
+    ack: EmptyAck,
+    errors: ['not_in_race', 'in_progress'],
+    doc: 'Ask for another round; it starts when every seated racer has asked.',
+  }),
+} satisfies Record<string, OpDef>;

package/src/realtime/ops/rooms.ts

@@ -0,0 +1,122 @@
+/**
+ * Hub relay room ops (multiplayer-impl.md §6). Rooms hold up to 8 seats;
+ * the hub relays messages and state but never referees, so results are
+ * untrusted. Race rooms refuse `room.start`, `room.state` and `room.end`
+ * (`race_room`): the race ops drive them.
+ */
+import { z } from 'zod';
+import { Json, Slug, UserId } from '../../common';
+import { CHAT_ERRORS, ChatLine, ChatSend } from '../../api/mp/chat';
+import { GameMode, OpaqueId } from '../../api/mp/parties';
+import { RoomInfo, RoomMessage, RoomModel, RoomState, RoomTarget } from '../../api/mp/rooms';
+import { op, type OpDef } from '../define';
+import { EmptyAck, NoInput } from './empty';
+
+/** A per-room sequence number ack (`room.send`, `room.state`). */
+const SeqAck = z.object({ seq: z.number().int().positive() });
+
+/** The room ops, by op name. */
+export const roomOps = {
+  'room.create': op({
+    d: z.object({
+      game: Slug,
+      /** One of the game's modes (`race` is refused: use `race.create`). */
+      mode: GameMode.nullish(),
+      /** Listed in `room.list` (default false). */
+      public: z.boolean().optional(),
+      /** Seats; clamped to the game's max (and 8). Defaults to the max. */
+      maxPlayers: z.number().optional(),
+      model: RoomModel.optional(),
+      /** The caller's party: when they lead it, its join info becomes `{ room: code }`. */
+      partyId: OpaqueId.optional(),
+    }),
+    ack: z.object({ room: RoomInfo, state: RoomState }),
+    errors: ['not_multiplayer', 'not_supported', 'bad_mode', 'too_many_rooms'],
+    doc: 'Open a room for a hub-rooms game with the caller seated as host (leaving any other seat).',
+  }),
+  'room.join': op({
+    d: RoomTarget,
+    ack: z.object({
+      room: RoomInfo,
+      state: RoomState,
+      /** Recent messages this member may see, oldest first. */
+      history: z.array(RoomMessage),
+    }),
+    errors: ['room_not_found', 'banned', 'in_progress', 'room_full', 'not_multiplayer', 'not_supported'],
+    doc: 'Take a seat (lobby only), reclaim your own seat (any phase, any tab), or watch.',
+  }),
+  'room.leave': op({
+    d: NoInput,
+    ack: EmptyAck,
+    errors: [],
+    doc: 'Give up your seat, or stop watching.',
+  }),
+  'room.ready': op({
+    d: z.object({ ready: z.boolean() }),
+    ack: EmptyAck,
+    errors: ['not_in_room', 'in_progress'],
+    doc: 'Mark yourself ready in the lobby.',
+  }),
+  'room.seat': op({
+    d: z.object({ data: Json.optional() }),
+    ack: EmptyAck,
+    errors: ['not_in_room', 'too_large'],
+    doc: 'Set your seat data (team, colour…), at most 2 KB of JSON.',
+  }),
+  'room.start': op({
+    d: NoInput,
+    ack: EmptyAck,
+    errors: ['not_in_room', 'not_host', 'race_room', 'in_progress', 'not_ready'],
+    doc: "Host: start once the game's minimum players are seated and everyone else is ready.",
+  }),
+  'room.send': op({
+    d: z.object({
+      /** The game message, at most 8 KB of JSON. */
+      data: Json.optional(),
+      /** Address one seat; otherwise the room model decides who hears it. */
+      to: UserId.nullish(),
+    }),
+    ack: SeqAck,
+    errors: ['not_in_room', 'ended', 'too_large', 'rate_limited', 'bad_target'],
+    doc: 'Relay a game message (at most 30 a second).',
+  }),
+  'room.state': op({
+    d: z.object({
+      /** Shallow-merged into the state; a `null` value deletes its key. */
+      patch: RoomState,
+      /** Replace the whole state with `patch`. */
+      replace: z.boolean().optional(),
+    }),
+    ack: SeqAck,
+    errors: ['not_in_room', 'race_room', 'not_host', 'bad_patch', 'too_large'],
+    invalid: { code: 'bad_patch', error: 'patch must be an object.' },
+    doc: 'Update the shared state (host only in the host model), at most 32 KB.',
+  }),
+  'room.chat': op({
+    d: ChatSend,
+    ack: ChatLine,
+    errors: ['not_in_room', 'room_not_found', ...CHAT_ERRORS],
+    doc: 'Moderated room chat: free text only when every seated player is a mutual friend.',
+  }),
+  'room.kick': op({
+    d: z.object({ userId: UserId }),
+    ack: EmptyAck,
+    errors: ['not_in_room', 'not_host', 'bad_target'],
+    doc: "Host: remove a player; they can't rejoin this room.",
+  }),
+  'room.end': op({
+    d: z.object({
+      /** Relayed to everyone in the final `room` event, untrusted; at most 8 KB of JSON. */
+      results: Json.optional(),
+    }),
+    ack: EmptyAck,
+    errors: ['not_in_room', 'not_host', 'race_room', 'too_large'],
+    doc: 'Host: end the match. Players become recent players; the room closes after a delay.',
+  }),
+  'room.list': op({
+    d: z.object({ game: Slug, mode: GameMode.optional() }),
+    ack: z.object({ rooms: z.array(RoomInfo) }),
+    errors: [],
+    doc: 'Public lobbies with a free seat (at most 50), minus rooms with blocked players.',
+  }),
+} satisfies Record<string, OpDef>;

package/src/realtime/ops/social.ts

@@ -0,0 +1,58 @@
+/**
+ * Socket ops for presence, visibility, typing and the heartbeat
+ * (multiplayer-impl.md §4.3). `hello` is declared with the snapshot.
+ */
+import { z } from 'zod';
+import { Millis, UserId } from '../../common';
+import { PresenceInput } from '../../api/social/presence';
+import { op, type OpDef } from '../define';
+import { EmptyAck, NoInput } from './empty';
+
+/**
+ * `visibility` input: the tab's document visibility and idle state. Input
+ * that isn't an object counts as `{}` (visible, not idle); a field that isn't a
+ * boolean takes its default.
+ */
+export const VisibilityInput = z.object({
+  /** The document is visible (default `true`). */
+  visible: z.boolean().optional().catch(undefined),
+  /** The player has been idle (default `false`). Hidden or idle tabs count as `away`. */
+  idle: z.boolean().optional().catch(undefined),
+}).catch({});
+
+/** The social ops, by op name. */
+export const socialOps = {
+  presence: op({
+    d: PresenceInput,
+    ack: EmptyAck,
+    errors: ['rate_limited'],
+    doc: "Report this tab's activity. Rate-limited per user; a rejected `detail` is dropped silently.",
+  }),
+  visibility: op({
+    d: VisibilityInput,
+    ack: EmptyAck,
+    errors: [],
+    doc: "Report this tab's visibility and idle state (hidden or idle tabs count as `away`).",
+  }),
+  typing: op({
+    d: z.object({
+      /**
+       * The friend you're typing to. Anything that isn't a friend's id is a
+       * silent no-op; a value that isn't a user id at all parses as `0` (no one).
+       */
+      to: UserId.catch(0),
+    }),
+    ack: EmptyAck,
+    errors: [],
+    doc: 'Tell a friend you are typing (`ev:typing`), at most once per 2 s per pair.',
+  }),
+  ping: op({
+    d: NoInput,
+    ack: z.object({
+      /** The server clock (epoch ms). */
+      t: Millis,
+    }),
+    errors: [],
+    doc: 'Heartbeat and clock check; allowed before `hello`.',
+  }),
+} satisfies Record<string, OpDef>;