@sametnurel/game-server 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## 1.0.0
+
+First stable release, renamed from `@sametnurel/socket-io-game-server` (0.0.x) because the server is no longer tied to Socket.IO. A rewrite with breaking changes.
+
+### Added
+- Pluggable transports: `SocketIOTransport`, `WebSocketTransport` (plain JSON frames, for engines without Socket.IO such as Godot) and an in-process `MemoryTransport`. Several can run on one HTTP server and share rooms.
+- `GameServer` instance that wires everything; several servers per process are possible.
+- Payload validation per command (`parse`), `PayloadError`, and `error` events with codes (`unknown_event`, `invalid_payload`, `internal_error`, `bad_frame`).
+- Per-client in-order message handling, also for async commands.
+- `SessionManager` (reconnect window), `MatchQueue` (matchmaking per mode, stale-entry pickup for bots), `TurnTimer`, `RoomRegistry`.
+- `Game<TStatus>` with custom phases, `update(tick, now)` on a server tick, `dispose()`.
+- `createVirtualClient()` for bots and tests.
+- Options for port, host, CORS, an existing HTTP server, logger and tick interval.
+- Test suite (Vitest).
+
+### Changed
+- No singletons: use `server.games`, `server.connections`, `server.rooms`.
+- Commands get `(context, payload)` instead of `(socket, connection, message)`.
+- Event names are plain strings; system events live in `SystemEvents`.
+- `socket.io` and `ws` are optional peer dependencies; Express is no longer required.
+
+### Fixed
+- `IdGenerator` looped forever once 9000 ids were used; ids are now released and exhaustion throws.
+- The logger, `GameOverParams` and other public types were not exported.
+- A throwing command could crash the process.
+- Removed use of Socket.IO's private `_readyState`.
+- README: wrong package name, placeholder badges, license mismatch.

package/README.md

@@ -1,3 +1,161 @@
-# Temporary Holding Version
+# @sametnurel/game-server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A small, transport-agnostic server for turn-based multiplayer games. It gives you
+commands, rooms, reconnectable sessions, matchmaking and turn timers, and lets
+clients connect over **Socket.IO**, **plain WebSocket** (any engine, e.g. Godot),
+or **in-process** (bots and tests) at the same time.
+
+Game rules stay in your code. The server routes messages and manages people.
+
+## Install
+
+```bash
+npm install @sametnurel/game-server
+# plus the transports you use:
+npm install ws          # plain WebSocket
+npm install socket.io   # Socket.IO
+```
+
+Requires Node 18+. Works from both CommonJS and ESM.
+
+## Quick start
+
+```ts
+import { GameServer, PayloadError } from '@sametnurel/game-server';
+import { WebSocketTransport } from '@sametnurel/game-server/ws';
+import { SocketIOTransport } from '@sametnurel/game-server/socket-io';
+
+const server = new GameServer({
+  transports: [new WebSocketTransport({ path: '/ws' }), new SocketIOTransport()],
+  port: 5200,
+  cors: { origin: ['https://my-game.example'] },
+});
+
+server.command<{ text: string }>('chat', {
+  parse(raw) {
+    const text = (raw as { text?: unknown } | null)?.text;
+    if (typeof text !== 'string' || text.length > 200) throw new PayloadError('text must be a short string');
+    return { text };
+  },
+  handle({ server, connection }, { text }) {
+    server.broadcast('lobby', 'chat', { from: connection.id, text });
+  },
+});
+
+server.onConnect((connection) => server.rooms.join('lobby', connection));
+
+await server.start();
+```
+
+Nothing is global: create as many servers as you like (handy in tests).
+
+## Transports
+
+| Transport | Import | Wire format |
+| --- | --- | --- |
+| `WebSocketTransport` | `.../ws` | One JSON frame per message: `{ "event": string, "data"?: any }`, both directions |
+| `SocketIOTransport` | `.../socket-io` | Socket.IO events: `emit(event, data)` |
+| `MemoryTransport` | built in | `server.createVirtualClient()`: for bots and tests |
+
+All transports share one HTTP server, rooms and commands; a room can mix clients
+from different transports. Plain WebSocket clients get a ping every 30 s and are
+dropped if they stop answering.
+
+### Bring your own HTTP server
+
+Pass an existing server (e.g. Express) to serve a REST API on the same port:
+
+```ts
+const app = express();
+app.get('/health', (_req, res) => res.send('ok'));
+const http = app.listen(5200);
+const server = new GameServer({ httpServer: http, transports: [new WebSocketTransport()] });
+await server.start();
+```
+
+## Commands
+
+`server.command(event, commandOrFunction)` registers one handler per event.
+
+- `parse(raw)` validates the payload and returns it typed. Throw to reject; the
+  client gets `error` `{ code: 'invalid_payload', event, message }` (message only
+  for `PayloadError`). Any validator works: `parse: (raw) => schema.parse(raw)`.
+- `handle(context, payload)` runs the logic. `context` has `server`, `connection`, `event`.
+- A throwing or rejecting handler never crashes the process: it is logged and the
+  client gets `{ code: 'internal_error', event }`.
+- Unregistered events get `{ code: 'unknown_event', event }`.
+- Messages from one client are handled **in order**, also when handlers are async.
+
+Prefer classes? Extend `BaseCommand<TPayload>`.
+
+## Connections and rooms
+
+`Connection` wraps the current socket and has `data` (your state), `identifier`
+(a stable device or account id) and `rooms`. Use `connections.identify(conn, id)`
+and `connections.rebind(existing, fresh)` to move a returning client onto its
+new socket while keeping rooms and data.
+
+`server.rooms.join/leave/leaveAll/members`, `server.broadcast(room, event, data, except?)`.
+Disconnected clients leave all rooms automatically, then `onDisconnect` hooks run.
+
+## Games
+
+```ts
+class Match extends Game<'SETUP' | 'PLAY'> {
+  start() { this.status = 'PLAY'; }
+  override update(tick: number, now: number) { /* called every tickIntervalMs */ }
+  override dispose() { /* clear timers */ }
+}
+const match = server.games.create((id) => new Match(id));
+server.broadcast(match.roomId, 'started');
+server.games.remove(match.id); // disposes and frees the id
+```
+
+Game ids come from `IdGenerator` (default 1000-9999). Ids are freed on remove and
+the generator throws when the range is full instead of hanging.
+
+## Sessions and reconnect
+
+```ts
+const sessions = new SessionManager<{ gameId: number }>({
+  reconnectWindowMs: 30_000,
+  onExpire: (session) => forfeit(session.state?.gameId),
+});
+
+server.command<{ deviceId: string }>('hello', ({ connection }, { deviceId }) => {
+  const { session, resumed } = sessions.attach(deviceId, connection);
+  connection.identifier = deviceId;
+  if (resumed) connection.send('resume', session.state);
+});
+server.onDisconnect((connection) => sessions.detach(connection));
+```
+
+## Matchmaking, bots and turn timers
+
+```ts
+const queue = new MatchQueue<Player>((p) => p.id); // groups of 2
+const pair = queue.enqueue('ranked', player);        // Player[] when a match forms
+const lonely = queue.takeWaitingLongerThan('ranked', 15_000); // pair these with bots
+
+const bot = server.createVirtualClient(); // a bot speaks the same protocol
+bot.on('yourTurn', (state) => bot.send('move', decide(state)));
+
+const timer = new TurnTimer();
+timer.start(30_000, () => endTurn());
+connection.send('turn', { deadline: timer.deadline });
+```
+
+## Logging
+
+`ConsoleLogger` (level from `LOG_LEVEL`, default `info`) is used by default.
+Pass `logger: silentLogger` or your own `{ error, warn, info, debug }`.
+
+## Migrating from 0.0.x
+
+This package was published as `@sametnurel/socket-io-game-server` up to 0.0.8. 1.0 is a rewrite; see [CHANGELOG.md](CHANGELOG.md). In short: no singletons
+(`GameManager.getInstance()` → `server.games`), commands receive a context
+instead of a socket, transports are pluggable, and port/CORS are options.
+
+## License
+
+ISC © Samet Nurel

package/dist/command.d.ts

@@ -0,0 +1,25 @@
+import type { Connection } from './connection';
+import type { GameServer } from './server';
+export interface CommandContext<TData = unknown> {
+    server: GameServer<any, TData>;
+    connection: Connection<TData>;
+    event: string;
+}
+/**
+ * Handles one client event. `parse` validates the raw payload and returns it
+ * typed; throw to reject it. Plug in any
+ * validator, e.g. `parse: (raw) => schema.parse(raw)` with zod.
+ */
+export interface Command<TPayload = unknown, TData = unknown> {
+    parse?(raw: unknown): TPayload;
+    handle(context: CommandContext<TData>, payload: TPayload): void | Promise<void>;
+}
+/** Class form of Command, for apps that prefer one class per command. */
+export declare abstract class BaseCommand<TPayload = unknown, TData = unknown> implements Command<TPayload, TData> {
+    parse?(raw: unknown): TPayload;
+    abstract handle(context: CommandContext<TData>, payload: TPayload): void | Promise<void>;
+}
+/** Thrown by `parse` to reject a payload with a client-visible message. */
+export declare class PayloadError extends Error {
+    constructor(message: string);
+}

package/dist/command.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PayloadError = exports.BaseCommand = void 0;
+/** Class form of Command, for apps that prefer one class per command. */
+class BaseCommand {
+}
+exports.BaseCommand = BaseCommand;
+/** Thrown by `parse` to reject a payload with a client-visible message. */
+class PayloadError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PayloadError';
+    }
+}
+exports.PayloadError = PayloadError;

package/dist/connection-manager.d.ts

@@ -0,0 +1,24 @@
+import { Connection } from './connection';
+import type { ClientSocket } from './transport/types';
+/** Tracks live connections by socket id and by app identifier. */
+export declare class ConnectionManager<TData = unknown> {
+    private readonly bySocket;
+    private readonly byIdentifier;
+    add(socket: ClientSocket): Connection<TData>;
+    get(socketId: string): Connection<TData> | undefined;
+    getByIdentifier(identifier: string): Connection<TData> | undefined;
+    /**
+     * Associates a connection with an identifier. If another live connection
+     * already had it (same device opened twice), that one is returned so the app
+     * can decide; it is not closed here.
+     */
+    identify(conn: Connection<TData>, identifier: string): Connection<TData> | undefined;
+    /**
+     * Moves an existing Connection (rooms, data) onto a new socket and drops the
+     * temporary Connection created for that socket. Returns the surviving one.
+     */
+    rebind(existing: Connection<TData>, fresh: Connection<TData>): Connection<TData>;
+    remove(conn: Connection<TData>): void;
+    all(): IterableIterator<Connection<TData>>;
+    get size(): number;
+}

package/dist/connection-manager.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectionManager = void 0;
+const connection_1 = require("./connection");
+/** Tracks live connections by socket id and by app identifier. */
+class ConnectionManager {
+    bySocket = new Map();
+    byIdentifier = new Map();
+    add(socket) {
+        const conn = new connection_1.Connection(socket);
+        this.bySocket.set(socket.id, conn);
+        return conn;
+    }
+    get(socketId) {
+        return this.bySocket.get(socketId);
+    }
+    getByIdentifier(identifier) {
+        return this.byIdentifier.get(identifier);
+    }
+    /**
+     * Associates a connection with an identifier. If another live connection
+     * already had it (same device opened twice), that one is returned so the app
+     * can decide; it is not closed here.
+     */
+    identify(conn, identifier) {
+        const previous = this.byIdentifier.get(identifier);
+        if (conn.identifier && conn.identifier !== identifier)
+            this.byIdentifier.delete(conn.identifier);
+        conn.identifier = identifier;
+        this.byIdentifier.set(identifier, conn);
+        return previous && previous !== conn ? previous : undefined;
+    }
+    /**
+     * Moves an existing Connection (rooms, data) onto a new socket and drops the
+     * temporary Connection created for that socket. Returns the surviving one.
+     */
+    rebind(existing, fresh) {
+        if (existing === fresh)
+            return existing;
+        this.bySocket.delete(existing.id);
+        this.bySocket.delete(fresh.id);
+        existing.setSocket(fresh.socket);
+        this.bySocket.set(existing.id, existing);
+        return existing;
+    }
+    remove(conn) {
+        if (this.bySocket.get(conn.id) === conn)
+            this.bySocket.delete(conn.id);
+        if (conn.identifier && this.byIdentifier.get(conn.identifier) === conn) {
+            this.byIdentifier.delete(conn.identifier);
+        }
+    }
+    all() {
+        return this.bySocket.values();
+    }
+    get size() {
+        return this.bySocket.size;
+    }
+}
+exports.ConnectionManager = ConnectionManager;

package/dist/connection.d.ts

@@ -0,0 +1,22 @@
+import type { ClientSocket } from './transport/types';
+/**
+ * A client as the game sees it. Wraps the current socket; on reconnect the same
+ * Connection can be re-bound to a new socket so rooms and data survive.
+ */
+export declare class Connection<TData = unknown> {
+    /** Free slot for app data, e.g. the player this client controls. */
+    data: TData | undefined;
+    /** Stable client identifier (device id, account id) once the app sets it. */
+    identifier: string | undefined;
+    readonly rooms: Set<string>;
+    private current;
+    constructor(socket: ClientSocket);
+    /** Id of the current socket. Changes when the connection is re-bound. */
+    get id(): string;
+    get transport(): string;
+    get socket(): ClientSocket;
+    send(event: string, data?: unknown): void;
+    close(): void;
+    /** @internal Used by ConnectionManager.rebind. */
+    setSocket(socket: ClientSocket): void;
+}

package/dist/connection.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Connection = void 0;
+/**
+ * A client as the game sees it. Wraps the current socket; on reconnect the same
+ * Connection can be re-bound to a new socket so rooms and data survive.
+ */
+class Connection {
+    /** Free slot for app data, e.g. the player this client controls. */
+    data;
+    /** Stable client identifier (device id, account id) once the app sets it. */
+    identifier;
+    rooms = new Set();
+    current;
+    constructor(socket) {
+        this.current = socket;
+    }
+    /** Id of the current socket. Changes when the connection is re-bound. */
+    get id() {
+        return this.current.id;
+    }
+    get transport() {
+        return this.current.transport;
+    }
+    get socket() {
+        return this.current;
+    }
+    send(event, data) {
+        this.current.send(event, data);
+    }
+    close() {
+        this.current.close();
+    }
+    /** @internal Used by ConnectionManager.rebind. */
+    setSocket(socket) {
+        this.current = socket;
+    }
+}
+exports.Connection = Connection;

package/dist/events.d.ts

@@ -0,0 +1,19 @@
+/** Events the server itself sends. Game events are plain strings chosen by the app. */
+export declare const SystemEvents: {
+    /** Sent when a message is rejected or a handler fails. Payload: ErrorPayload. */
+    readonly Error: 'error';
+};
+export type SystemEvent = (typeof SystemEvents)[keyof typeof SystemEvents];
+export declare const ErrorCodes: {
+    readonly UnknownEvent: 'unknown_event';
+    readonly InvalidPayload: 'invalid_payload';
+    readonly InternalError: 'internal_error';
+    readonly BadFrame: 'bad_frame';
+};
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+export interface ErrorPayload {
+    code: ErrorCode;
+    /** The client event that caused the error, when known. */
+    event?: string;
+    message?: string;
+}

package/dist/events.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorCodes = exports.SystemEvents = void 0;
+/** Events the server itself sends. Game events are plain strings chosen by the app. */
+exports.SystemEvents = {
+    /** Sent when a message is rejected or a handler fails. Payload: ErrorPayload. */
+    Error: 'error',
+};
+exports.ErrorCodes = {
+    UnknownEvent: 'unknown_event',
+    InvalidPayload: 'invalid_payload',
+    InternalError: 'internal_error',
+    BadFrame: 'bad_frame',
+};

package/dist/game-manager.d.ts

@@ -0,0 +1,16 @@
+import type { Game } from './game';
+import { IdGenerator } from './ids';
+/** Owns the live games: creates them with unique ids, ticks and removes them. */
+export declare class GameManager<TGame extends Game<any>> {
+    private readonly ids;
+    private readonly games;
+    constructor(ids?: IdGenerator);
+    create(factory: (id: number) => TGame): TGame;
+    get(id: number): TGame | undefined;
+    all(): IterableIterator<TGame>;
+    /** Disposes the game and frees its id. */
+    remove(id: number): boolean;
+    /** Calls update() on every game that is not over. Errors are reported, not thrown. */
+    tick(tick: number, now: number, onError?: (game: TGame, error: unknown) => void): void;
+    get size(): number;
+}

package/dist/game-manager.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GameManager = void 0;
+const ids_1 = require("./ids");
+/** Owns the live games: creates them with unique ids, ticks and removes them. */
+class GameManager {
+    ids;
+    games = new Map();
+    constructor(ids = new ids_1.IdGenerator()) {
+        this.ids = ids;
+    }
+    create(factory) {
+        const id = this.ids.next();
+        try {
+            const game = factory(id);
+            this.games.set(id, game);
+            return game;
+        }
+        catch (error) {
+            this.ids.release(id);
+            throw error;
+        }
+    }
+    get(id) {
+        return this.games.get(id);
+    }
+    all() {
+        return this.games.values();
+    }
+    /** Disposes the game and frees its id. */
+    remove(id) {
+        const game = this.games.get(id);
+        if (!game)
+            return false;
+        this.games.delete(id);
+        this.ids.release(id);
+        game.dispose();
+        return true;
+    }
+    /** Calls update() on every game that is not over. Errors are reported, not thrown. */
+    tick(tick, now, onError) {
+        for (const game of this.games.values()) {
+            if (game.isOver())
+                continue;
+            try {
+                game.update(tick, now);
+            }
+            catch (error) {
+                onError?.(game, error);
+            }
+        }
+    }
+    get size() {
+        return this.games.size;
+    }
+}
+exports.GameManager = GameManager;

package/dist/game.d.ts

@@ -0,0 +1,29 @@
+export type BaseGameStatus = 'NOT_STARTED' | 'STARTED' | 'OVER';
+export interface GameOverParams {
+    /** Why the game ended, e.g. 'win', 'timeout', 'opponent_left'. */
+    reason?: string;
+    winnerId?: number;
+    [key: string]: unknown;
+}
+/**
+ * Base class for one match. Subclasses add players and rules.
+ * `TStatus` lets a game add its own phases (e.g. 'SETUP' | 'BATTLE').
+ */
+export declare abstract class Game<TStatus extends string = BaseGameStatus> {
+    readonly id: number;
+    protected status: TStatus | BaseGameStatus;
+    protected overParams: GameOverParams | undefined;
+    constructor(id: number);
+    /** Room name for broadcasting to this game's clients. */
+    get roomId(): string;
+    getStatus(): TStatus | BaseGameStatus;
+    isOver(): boolean;
+    getOverParams(): GameOverParams | undefined;
+    /** Called on every server tick while the game is not over. Override for timers. */
+    update(_tick: number, _now: number): void;
+    /** Marks the game as over. Override to notify players, then call super. */
+    end(params?: GameOverParams): void;
+    /** Called when the game is removed from its manager: clear timers here. */
+    dispose(): void;
+    abstract start(): void;
+}

package/dist/game.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Game = void 0;
+/**
+ * Base class for one match. Subclasses add players and rules.
+ * `TStatus` lets a game add its own phases (e.g. 'SETUP' | 'BATTLE').
+ */
+class Game {
+    id;
+    status = 'NOT_STARTED';
+    overParams;
+    constructor(id) {
+        this.id = id;
+    }
+    /** Room name for broadcasting to this game's clients. */
+    get roomId() {
+        return `game:${this.id}`;
+    }
+    getStatus() {
+        return this.status;
+    }
+    isOver() {
+        return this.status === 'OVER';
+    }
+    getOverParams() {
+        return this.overParams;
+    }
+    /** Called on every server tick while the game is not over. Override for timers. */
+    update(_tick, _now) { }
+    /** Marks the game as over. Override to notify players, then call super. */
+    end(params = {}) {
+        this.status = 'OVER';
+        this.overParams = params;
+    }
+    /** Called when the game is removed from its manager: clear timers here. */
+    dispose() { }
+}
+exports.Game = Game;

package/dist/ids.d.ts

@@ -0,0 +1,24 @@
+export interface IdGeneratorOptions {
+    /** Smallest id (inclusive). Default 1000. */
+    min?: number;
+    /** Largest id (inclusive). Default 9999. */
+    max?: number;
+    /** Random source in [0, 1). Default Math.random. */
+    random?: () => number;
+}
+/**
+ * Hands out short, unique, human-friendly ids from a fixed range.
+ * Ids must be released when no longer used; when the range is full, next() throws
+ * instead of looping forever.
+ */
+export declare class IdGenerator {
+    private readonly used;
+    private readonly min;
+    private readonly size;
+    private readonly random;
+    constructor(options?: IdGeneratorOptions);
+    next(): number;
+    release(id: number): void;
+    isUsed(id: number): boolean;
+    get inUse(): number;
+}

package/dist/ids.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdGenerator = void 0;
+/**
+ * Hands out short, unique, human-friendly ids from a fixed range.
+ * Ids must be released when no longer used; when the range is full, next() throws
+ * instead of looping forever.
+ */
+class IdGenerator {
+    used = new Set();
+    min;
+    size;
+    random;
+    constructor(options = {}) {
+        this.min = options.min ?? 1000;
+        const max = options.max ?? 9999;
+        if (max < this.min)
+            throw new RangeError('IdGenerator: max must be >= min');
+        this.size = max - this.min + 1;
+        this.random = options.random ?? Math.random;
+    }
+    next() {
+        if (this.used.size >= this.size) {
+            throw new Error(`IdGenerator: all ${this.size} ids are in use`);
+        }
+        // Random start, then linear probe: always terminates.
+        const start = Math.floor(this.random() * this.size);
+        for (let i = 0; i < this.size; i++) {
+            const id = this.min + ((start + i) % this.size);
+            if (!this.used.has(id)) {
+                this.used.add(id);
+                return id;
+            }
+        }
+        throw new Error('IdGenerator: unreachable');
+    }
+    release(id) {
+        this.used.delete(id);
+    }
+    isUsed(id) {
+        return this.used.has(id);
+    }
+    get inUse() {
+        return this.used.size;
+    }
+}
+exports.IdGenerator = IdGenerator;

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { GameServer, type GameServerOptions } from './server';
+export { BaseCommand, PayloadError, type Command, type CommandContext } from './command';
+export { Connection } from './connection';
+export { ConnectionManager } from './connection-manager';
+export { RoomRegistry } from './rooms';
+export { Game, type BaseGameStatus, type GameOverParams } from './game';
+export { GameManager } from './game-manager';
+export { Player } from './player';
+export { MatchQueue, type QueueEntry } from './matchmaking';
+export { SessionManager, type Session, type SessionManagerOptions } from './sessions';
+export { TurnTimer } from './turn-timer';
+export { IdGenerator, type IdGeneratorOptions } from './ids';
+export { ConsoleLogger, silentLogger, type Logger, type LogLevel } from './logger';
+export { SystemEvents, ErrorCodes, type SystemEvent, type ErrorCode, type ErrorPayload } from './events';
+export { MemoryTransport, MemoryClient } from './transport/memory';
+export type { Transport, TransportContext, TransportHandlers, ClientSocket, CorsOptions } from './transport/types';