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

package/src/realtime/events/multiplayer.ts

@@ -0,0 +1,8 @@
+/** Socket events for invites, parties, hub rooms and races. */
+import type { EventDef } from '../define';
+import { partyEvents } from './parties';
+import { raceEvents } from './races';
+import { roomEvents } from './rooms';
+
+/** The multiplayer events, by event name. */
+export const multiplayerEvents = { ...partyEvents, ...roomEvents, ...raceEvents } satisfies Record<string, EventDef>;

package/src/realtime/events/parties.ts

@@ -0,0 +1,31 @@
+/** Invite and party events (multiplayer-impl.md §5.6). */
+import { z } from 'zod';
+import { PlayerLite } from '../../entities';
+import { ChatLineEvent } from '../../api/mp/chat';
+import { Invite, InviteStatus, OpaqueId, Party } from '../../api/mp/parties';
+import { event, type EventDef } from '../define';
+
+/** The invite and party events, by event name. */
+export const partyEvents = {
+  invite: event({
+    d: Invite,
+    doc: 'A friend invited you to a game.',
+  }),
+  'invite.update': event({
+    d: z.object({
+      id: OpaqueId,
+      status: InviteStatus,
+      /** Who accepted or declined (absent for cancelled and expired). */
+      by: PlayerLite.optional(),
+    }),
+    doc: 'An invite ended; sent to the inviter and the invitee (so its toast closes).',
+  }),
+  party: event({
+    d: Party.nullable(),
+    doc: "Your party's current state, or null when you left it or it dissolved.",
+  }),
+  'party.chat': event({
+    d: ChatLineEvent,
+    doc: 'A party chat line.',
+  }),
+} satisfies Record<string, EventDef>;

package/src/realtime/events/races.ts

@@ -0,0 +1,27 @@
+/** Race events (docs/plans/race.md §4). */
+import { z } from 'zod';
+import { UserId } from '../../common';
+import { RaceProgress, RaceResult, RaceStart, RaceStats } from '../../api/mp/races';
+import { event, type EventDef } from '../define';
+
+/** The race events, by event name. */
+export const raceEvents = {
+  'race.start': event({
+    d: RaceStart,
+    doc: 'The countdown began: the seed is revealed now.',
+  }),
+  'race.status': event({
+    d: z.object({
+      userId: UserId,
+      stats: RaceStats,
+      progress: RaceProgress.optional(),
+      /** ms since the go (server clock). */
+      at: z.number().int().nonnegative(),
+    }),
+    doc: "Another racer's live status, for the race HUD.",
+  }),
+  'race.result': event({
+    d: z.object({ result: RaceResult }),
+    doc: 'The race was decided.',
+  }),
+} satisfies Record<string, EventDef>;

package/src/realtime/events/rooms.ts

@@ -0,0 +1,48 @@
+/** Hub relay room events (multiplayer-impl.md §6). Race rooms send these too. */
+import { z } from 'zod';
+import { Json, UserId } from '../../common';
+import { ChatLineEvent } from '../../api/mp/chat';
+import { OpaqueId } from '../../api/mp/parties';
+import { RoomClosedReason, RoomInfo, RoomMessage, RoomState, SeatGoneReason } from '../../api/mp/rooms';
+import { event, type EventDef } from '../define';
+
+/** The room events, by event name. */
+export const roomEvents = {
+  room: event({
+    d: z.object({
+      room: RoomInfo,
+      /** What the host passed to `room.end`; present once, on that update. */
+      results: Json.optional(),
+    }),
+    doc: 'The room changed: roster, ready flags, phase, host, race state.',
+  }),
+  'room.msg': event({
+    d: RoomMessage,
+    doc: 'A relayed game message.',
+  }),
+  'room.state': event({
+    d: z.object({
+      /** Shallow-merged into the state unless `replace`; a `null` value deletes its key. */
+      patch: RoomState,
+      replace: z.boolean(),
+      seq: z.number().int().positive(),
+    }),
+    doc: 'The shared state changed.',
+  }),
+  'room.chat': event({
+    d: ChatLineEvent,
+    doc: 'A room chat line.',
+  }),
+  'room.kicked': event({
+    d: z.object({ roomId: OpaqueId }),
+    doc: 'The host removed you from the room.',
+  }),
+  'room.closed': event({
+    d: z.object({ reason: RoomClosedReason }),
+    doc: 'The room is gone for this tab (emptied, ended, host left, moved, another tab took the seat, removed).',
+  }),
+  'room.abandoned': event({
+    d: z.object({ userId: UserId, reason: SeatGoneReason }),
+    doc: 'A player left mid-game (or their reconnect grace ran out); the game decides what that means.',
+  }),
+} satisfies Record<string, EventDef>;

package/src/realtime/events/social.ts

@@ -0,0 +1,81 @@
+/**
+ * Socket events for presence, counts, friends, typing, config, DMs, notices
+ * and suspension (multiplayer-impl.md §4.6). Every event goes to all of the
+ * recipient's tabs.
+ */
+import { z } from 'zod';
+import { Millis, UserId } from '../../common';
+import { PlayerLite } from '../../entities';
+import { Message, MessageId } from '../../api/messages';
+import { SocialConfig } from '../../api/social/config';
+import { FriendChange } from '../../api/social/people';
+import { Counts, Presence } from '../../api/social/presence';
+import { event, type EventDef } from '../define';
+
+/** What kind of thing a notice is about. `renamed`: an admin changed your username. */
+export const NoticeKind = z.enum(['dm', 'friend_request', 'friend_online', 'lobby_open', 'invite', 'suggestion', 'renamed']);
+
+/** A notice kind. */
+export type NoticeKind = z.infer<typeof NoticeKind>;
+
+/** A toast (`ev:notice`), sent instead of a push when the player has a visible tab. */
+export const Notice = z.object({
+  kind: NoticeKind,
+  title: z.string(),
+  body: z.string().optional(),
+  /** A button: its label and the page it opens. */
+  action: z.object({ label: z.string(), url: z.string() }).optional(),
+});
+
+/** A toast. */
+export type Notice = z.infer<typeof Notice>;
+
+/** The social events, by event name. */
+export const socialEvents = {
+  presence: event({
+    d: z.object({
+      userId: UserId,
+      /** `null`: offline, or no longer visible to you. */
+      p: Presence.nullable(),
+    }),
+    doc: "A friend's presence changed.",
+  }),
+  counts: event({ d: Counts, doc: 'The online counts changed (broadcast to every tab, at most every 15 s).' }),
+  friends: event({
+    d: z.object({ change: FriendChange, user: PlayerLite }),
+    doc: 'Your friends list changed (refetch `GET /social/friends`).',
+  }),
+  typing: event({ d: z.object({ from: UserId }), doc: 'A friend is typing to you.' }),
+  config: event({ d: SocialConfig, doc: 'The site-wide social configuration changed (broadcast).' }),
+  dm: event({
+    d: z.object({
+      message: Message,
+      /** The other side of the conversation, from your point of view. */
+      conversationWith: UserId,
+    }),
+    doc: 'A DM was delivered: to the recipient, and to the sender\'s other tabs.',
+  }),
+  'dm.read': event({
+    d: z.object({
+      /** Who read. */
+      by: UserId,
+      /** Their messages up to and including this id are read. */
+      upTo: MessageId,
+    }),
+    doc: 'Messages were read (to the sender, and to the reader\'s own tabs to sync badges).',
+  }),
+  'dm.hidden': event({
+    d: z.object({ ids: z.array(MessageId) }),
+    doc: 'A moderator hid these messages: drop them from both sides of the conversation.',
+  }),
+  notice: event({ d: Notice, doc: 'A toast to show.' }),
+  suspended: event({
+    d: z.object({
+      /** When the suspension ends (epoch ms). */
+      until: Millis,
+      /** The moderator's reason, when given. */
+      reason: z.string().optional(),
+    }),
+    doc: 'The account is suspended; the socket then closes with 4003.',
+  }),
+} satisfies Record<string, EventDef>;

package/src/realtime/index.ts

@@ -0,0 +1,24 @@
+/**
+ * The `/_ws` socket contract: the legacy envelope plus every op and event,
+ * by name.
+ */
+import { multiplayerEvents } from './events/multiplayer';
+import { socialEvents } from './events/social';
+import { helloOps } from './ops/hello';
+import { multiplayerOps } from './ops/multiplayer';
+import { socialOps } from './ops/social';
+
+export * from './define';
+export * from './envelope';
+
+/** Every socket op, by op name (an intersection type keeps the .d.ts small). */
+export const ops: typeof helloOps & typeof socialOps & typeof multiplayerOps = { ...helloOps, ...socialOps, ...multiplayerOps };
+
+/** Every socket event, by event name (an intersection type keeps the .d.ts small). */
+export const events: typeof socialEvents & typeof multiplayerEvents = { ...socialEvents, ...multiplayerEvents };
+
+/** A socket op name. */
+export type OpName = keyof typeof ops;
+
+/** A socket event name. */
+export type EventName = keyof typeof events;

package/src/realtime/ops/empty.ts

@@ -0,0 +1,8 @@
+/** The empty input and ack many socket ops share. */
+import { z } from 'zod';
+
+/** An op that takes no input (`d` absent or `{}`). */
+export const NoInput = z.object({});
+
+/** An ack with no payload (`{}`). */
+export const EmptyAck = z.object({});

package/src/realtime/ops/hello.ts

@@ -0,0 +1,40 @@
+/**
+ * `hello`: the first op on every socket (multiplayer-impl.md §4.5). It marks
+ * the tab live for events and presence and answers with the snapshot a
+ * client needs to draw the Friends drawer, invites and any room it still holds.
+ */
+import { z } from 'zod';
+import { UnreadSummary } from '../../api/messages';
+import { MultiplayerSnapshot } from '../../api/mp/snapshot';
+import { SocialConfig } from '../../api/social/config';
+import { FriendEntry, FriendRequests, SocialMe } from '../../api/social/people';
+import { Counts } from '../../api/social/presence';
+import { op } from '../define';
+
+/** `hello` input. Anything unrecognised is ignored rather than rejected. */
+export const HelloInput = z.object({
+  /** The game this tab is in, or `null` on the home page. Unknown slugs count as `null`. */
+  slug: z.string().nullable().optional(),
+  /** A per-tab id (`[A-Za-z0-9_-]{1,64}`); other values are ignored. */
+  tab: z.string().optional(),
+  /** The document is visible (default `true`). */
+  visible: z.boolean().optional(),
+  /** The client package version that opened the socket (`2.3.0`); v1 vendored copies send none. */
+  client: z.string().optional(),
+});
+
+/** The `hello` snapshot. Guests get no friends and empty request lists. */
+export const HelloSnapshot = z.object({
+  me: SocialMe,
+  config: SocialConfig,
+  counts: Counts,
+  friends: z.array(FriendEntry),
+  requests: FriendRequests,
+  unread: UnreadSummary,
+  ...MultiplayerSnapshot.shape,
+});
+
+/** The `hello` op (allowed before `hello`, obviously). */
+export const helloOps = {
+  hello: op({ d: HelloInput, ack: HelloSnapshot, errors: [], doc: 'Start the session on this socket; answers with the snapshot.' }),
+};

package/src/realtime/ops/multiplayer.ts

@@ -0,0 +1,8 @@
+/** Socket ops for invites, parties, hub rooms and races. */
+import type { OpDef } from '../define';
+import { partyOps } from './parties';
+import { raceOps } from './races';
+import { roomOps } from './rooms';
+
+/** The multiplayer ops, by op name. */
+export const multiplayerOps = { ...partyOps, ...roomOps, ...raceOps } satisfies Record<string, OpDef>;

package/src/realtime/ops/parties.ts

@@ -0,0 +1,13 @@
+/** The party socket op: party chat. Invites and party membership are REST (`/mp/*`). */
+import { CHAT_ERRORS, ChatLine, ChatSend } from '../../api/mp/chat';
+import { op, type OpDef } from '../define';
+
+/** The party ops, by op name. */
+export const partyOps = {
+  'party.chat': op({
+    d: ChatSend,
+    ack: ChatLine,
+    errors: ['party_gone', ...CHAT_ERRORS],
+    doc: "Chat to your party: free text only when every member is a mutual friend, quick-chat otherwise.",
+  }),
+} satisfies Record<string, OpDef>;

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>;