@sametnurel/game-server 0.0.0-stage → 1.0.0

package/dist/sessions.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionManager = void 0;
+/**
+ * Keeps a client's identity across reconnects. A session is keyed by a stable
+ * identifier (device or account id). When its connection drops, the session is
+ * kept for `reconnectWindowMs`; attaching the same identifier again resumes it.
+ */
+class SessionManager {
+    sessions = new Map();
+    timers = new Map();
+    windowMs;
+    onExpire;
+    constructor(options = {}) {
+        this.windowMs = options.reconnectWindowMs ?? 30_000;
+        this.onExpire = options.onExpire;
+    }
+    /** Binds a connection to an identifier. `resumed` is true if it came back in time. */
+    attach(identifier, connection) {
+        const existing = this.sessions.get(identifier);
+        if (existing) {
+            const resumed = existing.disconnectedAt !== undefined;
+            this.clearTimer(identifier);
+            existing.connection = connection;
+            existing.disconnectedAt = undefined;
+            return { session: existing, resumed };
+        }
+        const session = { identifier, connection, state: undefined, disconnectedAt: undefined };
+        this.sessions.set(identifier, session);
+        return { session, resumed: false };
+    }
+    /** Marks the session of this connection as disconnected and starts the reconnect window. */
+    detach(connection, now = Date.now()) {
+        const identifier = connection.identifier;
+        if (!identifier)
+            return undefined;
+        const session = this.sessions.get(identifier);
+        if (!session || session.connection !== connection)
+            return undefined;
+        session.connection = undefined;
+        session.disconnectedAt = now;
+        this.clearTimer(identifier);
+        const timer = setTimeout(() => {
+            this.timers.delete(identifier);
+            if (this.sessions.get(identifier) !== session || session.disconnectedAt === undefined)
+                return;
+            this.sessions.delete(identifier);
+            this.onExpire?.(session);
+        }, this.windowMs);
+        timer.unref?.();
+        this.timers.set(identifier, timer);
+        return session;
+    }
+    get(identifier) {
+        return this.sessions.get(identifier);
+    }
+    /** Ends a session for good (e.g. after the game is over). */
+    end(identifier) {
+        this.clearTimer(identifier);
+        this.sessions.delete(identifier);
+    }
+    clear() {
+        for (const timer of this.timers.values())
+            clearTimeout(timer);
+        this.timers.clear();
+        this.sessions.clear();
+    }
+    get size() {
+        return this.sessions.size;
+    }
+    clearTimer(identifier) {
+        const timer = this.timers.get(identifier);
+        if (timer)
+            clearTimeout(timer);
+        this.timers.delete(identifier);
+    }
+}
+exports.SessionManager = SessionManager;

package/dist/transport/memory.d.ts

@@ -0,0 +1,41 @@
+import type { ClientSocket, Transport, TransportContext, TransportHandlers } from './types';
+interface Received {
+    event: string;
+    data: unknown;
+}
+type Listener = (data: unknown) => void;
+/**
+ * In-process client: for bots and tests. Speaks the same events as a network
+ * client. Server-to-client messages are delivered asynchronously (microtask).
+ */
+export declare class MemoryClient {
+    readonly id: string;
+    private readonly handlers;
+    private readonly socket;
+    readonly received: Received[];
+    private readonly listeners;
+    private connected;
+    constructor(id: string, handlers: TransportHandlers, socket: ClientSocket);
+    /** Client -> server. */
+    send(event: string, data?: unknown): void;
+    on(event: string, listener: Listener): () => void;
+    /** Resolves with the next payload of `event`, or rejects after `timeoutMs`. */
+    waitFor<T = unknown>(event: string, timeoutMs?: number): Promise<T>;
+    disconnect(reason?: string): void;
+    get isConnected(): boolean;
+    /** @internal Server -> client delivery. */
+    deliver(event: string, data: unknown): void;
+    /** @internal Server closed the connection. */
+    closedByServer(): void;
+}
+export declare class MemoryTransport implements Transport {
+    readonly name = "memory";
+    readonly needsHttp = false;
+    private handlers;
+    private counter;
+    private readonly clients;
+    attach(context: TransportContext): void;
+    connect(): MemoryClient;
+    close(): Promise<void>;
+}
+export {};

package/dist/transport/memory.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryTransport = exports.MemoryClient = void 0;
+/**
+ * In-process client: for bots and tests. Speaks the same events as a network
+ * client. Server-to-client messages are delivered asynchronously (microtask).
+ */
+class MemoryClient {
+    id;
+    handlers;
+    socket;
+    received = [];
+    listeners = new Map();
+    connected = true;
+    constructor(id, handlers, socket) {
+        this.id = id;
+        this.handlers = handlers;
+        this.socket = socket;
+    }
+    /** Client -> server. */
+    send(event, data) {
+        if (!this.connected)
+            throw new Error(`MemoryClient ${this.id} is disconnected`);
+        this.handlers.onMessage(this.socket, event, data);
+    }
+    on(event, listener) {
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        set.add(listener);
+        return () => set.delete(listener);
+    }
+    /** Resolves with the next payload of `event`, or rejects after `timeoutMs`. */
+    waitFor(event, timeoutMs = 1000) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                off();
+                reject(new Error(`MemoryClient ${this.id}: timed out waiting for '${event}'`));
+            }, timeoutMs);
+            const off = this.on(event, (data) => {
+                clearTimeout(timer);
+                off();
+                resolve(data);
+            });
+        });
+    }
+    disconnect(reason = 'client disconnect') {
+        if (!this.connected)
+            return;
+        this.connected = false;
+        this.handlers.onDisconnect(this.socket, reason);
+    }
+    get isConnected() {
+        return this.connected;
+    }
+    /** @internal Server -> client delivery. */
+    deliver(event, data) {
+        if (!this.connected)
+            return;
+        queueMicrotask(() => {
+            if (!this.connected)
+                return;
+            this.received.push({ event, data });
+            for (const listener of [...(this.listeners.get(event) ?? [])])
+                listener(data);
+        });
+    }
+    /** @internal Server closed the connection. */
+    closedByServer() {
+        this.disconnect('server disconnect');
+    }
+}
+exports.MemoryClient = MemoryClient;
+class MemoryTransport {
+    name = 'memory';
+    needsHttp = false;
+    handlers = null;
+    counter = 0;
+    clients = new Set();
+    attach(context) {
+        this.handlers = context.handlers;
+    }
+    connect() {
+        const handlers = this.handlers;
+        if (!handlers)
+            throw new Error('MemoryTransport is not attached to a server yet');
+        const id = `mem-${++this.counter}`;
+        let client;
+        const socket = {
+            id,
+            transport: this.name,
+            send: (event, data) => client?.deliver(event, data),
+            close: () => client?.closedByServer(),
+        };
+        client = new MemoryClient(id, handlers, socket);
+        this.clients.add(client);
+        handlers.onConnect(socket);
+        return client;
+    }
+    async close() {
+        for (const client of this.clients)
+            client.closedByServer();
+        this.clients.clear();
+    }
+}
+exports.MemoryTransport = MemoryTransport;

package/dist/transport/socket-io.d.ts

@@ -0,0 +1,17 @@
+import { Server, type ServerOptions } from 'socket.io';
+import type { Transport, TransportContext } from './types';
+/**
+ * Socket.IO transport. Events map 1:1 to Socket.IO events.
+ * Import from '@sametnurel/game-server/socket-io' (needs the `socket.io` package).
+ */
+export declare class SocketIOTransport implements Transport {
+    private readonly options;
+    readonly name = "socket.io";
+    readonly needsHttp = true;
+    private io;
+    constructor(options?: Partial<ServerOptions>);
+    attach({ httpServer, handlers, cors }: TransportContext): void;
+    /** The underlying Socket.IO server, for advanced use. */
+    get server(): Server | null;
+    close(): Promise<void>;
+}

package/dist/transport/socket-io.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SocketIOTransport = void 0;
+const socket_io_1 = require("socket.io");
+/**
+ * Socket.IO transport. Events map 1:1 to Socket.IO events.
+ * Import from '@sametnurel/game-server/socket-io' (needs the `socket.io` package).
+ */
+class SocketIOTransport {
+    options;
+    name = 'socket.io';
+    needsHttp = true;
+    io = null;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    attach({ httpServer, handlers, cors }) {
+        if (!httpServer)
+            throw new Error('SocketIOTransport needs an HTTP server');
+        this.io = new socket_io_1.Server(httpServer, { cors, ...this.options });
+        this.io.on('connection', (raw) => {
+            const socket = {
+                id: raw.id,
+                transport: this.name,
+                send: (event, data) => {
+                    raw.emit(event, data);
+                },
+                close: () => {
+                    raw.disconnect(true);
+                },
+            };
+            handlers.onConnect(socket);
+            raw.onAny((event, data) => handlers.onMessage(socket, event, data));
+            raw.on('disconnect', (reason) => handlers.onDisconnect(socket, reason));
+        });
+    }
+    /** The underlying Socket.IO server, for advanced use. */
+    get server() {
+        return this.io;
+    }
+    async close() {
+        const io = this.io;
+        this.io = null;
+        if (!io)
+            return;
+        io.disconnectSockets(true);
+        // Do not let Socket.IO close the shared HTTP server; GameServer owns it.
+        io.engine.close();
+        io.removeAllListeners();
+    }
+}
+exports.SocketIOTransport = SocketIOTransport;

package/dist/transport/types.d.ts

@@ -0,0 +1,31 @@
+import type { Server as HttpServer } from 'node:http';
+/** One client connection, independent of the wire protocol. */
+export interface ClientSocket {
+    readonly id: string;
+    /** Name of the transport that created it, e.g. 'socket.io', 'ws', 'memory'. */
+    readonly transport: string;
+    send(event: string, data?: unknown): void;
+    close(): void;
+}
+/** Callbacks a transport reports to. Implemented by GameServer. */
+export interface TransportHandlers {
+    onConnect(socket: ClientSocket): void;
+    onMessage(socket: ClientSocket, event: string, data: unknown): void;
+    onDisconnect(socket: ClientSocket, reason: string): void;
+}
+export interface CorsOptions {
+    origin: string | string[] | boolean;
+}
+export interface TransportContext {
+    /** Null for transports that do not use HTTP (memory). */
+    httpServer: HttpServer | null;
+    handlers: TransportHandlers;
+    cors?: CorsOptions;
+}
+export interface Transport {
+    readonly name: string;
+    /** True when the transport needs an HTTP server. */
+    readonly needsHttp: boolean;
+    attach(context: TransportContext): void;
+    close(): Promise<void>;
+}

package/dist/transport/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/transport/ws.d.ts

@@ -0,0 +1,28 @@
+import type { Transport, TransportContext } from './types';
+export interface WebSocketTransportOptions {
+    /** URL path clients connect to. Default '/ws'. */
+    path?: string;
+    /** Max incoming frame size in bytes. Default 64 KiB. */
+    maxPayload?: number;
+    /** Ping interval to drop dead connections, in ms. 0 disables. Default 30000. */
+    heartbeatMs?: number;
+}
+/**
+ * Plain WebSocket transport (the `ws` package). Every frame is JSON:
+ *   { "event": string, "data"?: any }
+ * in both directions. Works with any WebSocket client (browser, Godot, mobile).
+ * Import from '@sametnurel/game-server/ws'.
+ */
+export declare class WebSocketTransport implements Transport {
+    readonly name = "ws";
+    readonly needsHttp = true;
+    private wss;
+    private heartbeat;
+    private detachUpgrade;
+    private readonly path;
+    private readonly maxPayload;
+    private readonly heartbeatMs;
+    constructor(options?: WebSocketTransportOptions);
+    attach({ httpServer, handlers, cors }: TransportContext): void;
+    close(): Promise<void>;
+}

package/dist/transport/ws.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSocketTransport = void 0;
+const node_crypto_1 = require("node:crypto");
+const ws_1 = require("ws");
+const events_1 = require("../events");
+/**
+ * Plain WebSocket transport (the `ws` package). Every frame is JSON:
+ *   { "event": string, "data"?: any }
+ * in both directions. Works with any WebSocket client (browser, Godot, mobile).
+ * Import from '@sametnurel/game-server/ws'.
+ */
+class WebSocketTransport {
+    name = 'ws';
+    needsHttp = true;
+    wss = null;
+    heartbeat = null;
+    detachUpgrade = null;
+    path;
+    maxPayload;
+    heartbeatMs;
+    constructor(options = {}) {
+        this.path = options.path ?? '/ws';
+        this.maxPayload = options.maxPayload ?? 64 * 1024;
+        this.heartbeatMs = options.heartbeatMs ?? 30_000;
+    }
+    attach({ httpServer, handlers, cors }) {
+        if (!httpServer)
+            throw new Error('WebSocketTransport needs an HTTP server');
+        const wss = new ws_1.WebSocketServer({ noServer: true, maxPayload: this.maxPayload });
+        this.wss = wss;
+        const alive = new WeakMap();
+        // Only take upgrades for our path; leave the rest (e.g. Socket.IO) alone.
+        const onUpgrade = (req, stream, head) => {
+            const pathname = new URL(req.url ?? '/', 'http://localhost').pathname;
+            if (pathname !== this.path)
+                return;
+            if (!originAllowed(cors, req.headers.origin)) {
+                stream.end('HTTP/1.1 403 Forbidden\r\n\r\n');
+                return;
+            }
+            wss.handleUpgrade(req, stream, head, (ws) => wss.emit('connection', ws, req));
+        };
+        httpServer.on('upgrade', onUpgrade);
+        this.detachUpgrade = () => httpServer.off('upgrade', onUpgrade);
+        wss.on('connection', (ws) => {
+            const socket = {
+                id: (0, node_crypto_1.randomUUID)(),
+                transport: this.name,
+                send: (event, data) => {
+                    if (ws.readyState === ws_1.WebSocket.OPEN)
+                        ws.send(JSON.stringify({ event, data }));
+                },
+                close: () => ws.close(1000, 'server close'),
+            };
+            alive.set(ws, true);
+            ws.on('pong', () => alive.set(ws, true));
+            handlers.onConnect(socket);
+            ws.on('message', (raw, isBinary) => {
+                const frame = isBinary ? undefined : parseFrame(raw.toString());
+                if (!frame) {
+                    socket.send(events_1.SystemEvents.Error, { code: events_1.ErrorCodes.BadFrame, message: 'Expected JSON {"event","data"}' });
+                    return;
+                }
+                handlers.onMessage(socket, frame.event, frame.data);
+            });
+            ws.on('close', (code) => handlers.onDisconnect(socket, `close ${code}`));
+            ws.on('error', () => ws.terminate());
+        });
+        if (this.heartbeatMs > 0) {
+            this.heartbeat = setInterval(() => {
+                for (const ws of wss.clients) {
+                    if (alive.get(ws) === false) {
+                        ws.terminate();
+                        continue;
+                    }
+                    alive.set(ws, false);
+                    ws.ping();
+                }
+            }, this.heartbeatMs);
+            this.heartbeat.unref();
+        }
+    }
+    async close() {
+        if (this.heartbeat)
+            clearInterval(this.heartbeat);
+        this.heartbeat = null;
+        this.detachUpgrade?.();
+        this.detachUpgrade = null;
+        const wss = this.wss;
+        this.wss = null;
+        if (!wss)
+            return;
+        for (const ws of wss.clients)
+            ws.terminate();
+        await new Promise((resolve) => wss.close(() => resolve()));
+    }
+}
+exports.WebSocketTransport = WebSocketTransport;
+function parseFrame(text) {
+    try {
+        const value = JSON.parse(text);
+        if (typeof value !== 'object' || value === null)
+            return undefined;
+        const { event, data } = value;
+        return typeof event === 'string' && event.length > 0 ? { event, data } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function originAllowed(cors, origin) {
+    if (!cors || cors.origin === true || cors.origin === '*')
+        return true;
+    if (cors.origin === false)
+        return origin === undefined;
+    if (origin === undefined)
+        return true; // non-browser clients (Godot, native) send no Origin
+    return Array.isArray(cors.origin) ? cors.origin.includes(origin) : cors.origin === origin;
+}

package/dist/turn-timer.d.ts

@@ -0,0 +1,15 @@
+/**
+ * One countdown, e.g. a player's turn. Send `deadline` to clients so they can
+ * show the remaining time without trusting their own clock for the rule.
+ */
+export declare class TurnTimer {
+    private timer;
+    private deadlineAt;
+    /** Starts (or restarts) the countdown. */
+    start(durationMs: number, onExpire: () => void, now?: number): void;
+    stop(): void;
+    get running(): boolean;
+    /** Epoch ms when the countdown ends, or null when stopped. */
+    get deadline(): number | null;
+    remainingMs(now?: number): number;
+}

package/dist/turn-timer.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TurnTimer = void 0;
+/**
+ * One countdown, e.g. a player's turn. Send `deadline` to clients so they can
+ * show the remaining time without trusting their own clock for the rule.
+ */
+class TurnTimer {
+    timer = null;
+    deadlineAt = null;
+    /** Starts (or restarts) the countdown. */
+    start(durationMs, onExpire, now = Date.now()) {
+        this.stop();
+        this.deadlineAt = now + durationMs;
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            this.deadlineAt = null;
+            onExpire();
+        }, durationMs);
+        this.timer.unref?.();
+    }
+    stop() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+        this.deadlineAt = null;
+    }
+    get running() {
+        return this.timer !== null;
+    }
+    /** Epoch ms when the countdown ends, or null when stopped. */
+    get deadline() {
+        return this.deadlineAt;
+    }
+    remainingMs(now = Date.now()) {
+        return this.deadlineAt === null ? 0 : Math.max(0, this.deadlineAt - now);
+    }
+}
+exports.TurnTimer = TurnTimer;

package/package.json

@@ -1,6 +1,76 @@
 {
   "name": "@sametnurel/game-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Lightweight, transport-agnostic multiplayer game server: commands, rooms, sessions with reconnect, matchmaking and turn timers over Socket.IO or plain WebSocket.",
+  "keywords": [
+    "game",
+    "server",
+    "multiplayer",
+    "socket.io",
+    "websocket",
+    "matchmaking",
+    "nodejs"
+  ],
+  "homepage": "https://github.com/snurel/game-server#readme",
+  "bugs": {
+    "url": "https://github.com/snurel/game-server/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/snurel/game-server.git"
+  },
+  "license": "ISC",
+  "author": "Samet Nurel",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./socket-io": {
+      "types": "./dist/transport/socket-io.d.ts",
+      "default": "./dist/transport/socket-io.js"
+    },
+    "./ws": {
+      "types": "./dist/transport/ws.d.ts",
+      "default": "./dist/transport/ws.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "peerDependencies": {
+    "socket.io": "^4.8.0",
+    "ws": "^8.18.0"
+  },
+  "peerDependenciesMeta": {
+    "socket.io": {
+      "optional": true
+    },
+    "ws": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.19.2",
+    "@types/ws": "^8.18.2",
+    "socket.io": "^4.8.4",
+    "socket.io-client": "^4.8.4",
+    "typescript": "^7.0.2",
+    "vitest": "^5.1.0",
+    "ws": "^8.22.1"
+  }
+}