tickcli-js 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.3
+
+Flood limits. New sockets per client address (`connectsPerAddress`, 40 per 10 s) are checked before the server-wide accept budget, so one client can no longer spend it for everyone; IPv6 addresses count by their /64 (`addressKey`) for every per-address limit. `hardenServer(server)` in `tickcli-js/node` (used by `createGameServer` and `createRemoteServer`): request headers within 10 s, whole request 15 s, idle keep-alive 5 s, 100 headers. Remote: a deployment is looked up at most once per 15 s per id, found or not (`remote.forget(id)` drops one after an edit), fresh lookups are capped per address, and an upgrade over the address budget is refused before any lookup. `ws` 8.23.0 or later (GHSA-37g9-w4hg-h9qr, ping flood).
+
+## 0.1.2
+
+Top speed for player fields: a third number in a range (`player: { x: [0, 800, 300] }`) caps how far the field moves per second. The hub cuts a faster move to that distance (10% headroom, senders' sample times) instead of refusing it, so speed hacks and teleports look like normal running to the others and to the host; removing a field first does not reset it; a new match allows one free jump. Ranges without the third number work as before.
+
 ## 0.1.1
 
 A "Leave" button in the top bar of multiplayer games: out of the room at any time (mid-match with others, a second tap within 3 s confirms) into a new private room of your own, and the seat is freed at once. With `Game({ exit: "/" })` or `<meta name="tickcli-exit" content="/">` it reads "Exit" and goes to that URL. Fix: after leaving, a page opened from an invite link (`#room=CODE`) no longer goes back to that room.

package/README.md

@@ -112,6 +112,7 @@ Game({
 | Server | membership, host, order, match number, clock | - |
 
 - Writes merge deeply: `{hp: {a: 80}}` changes one entry, `null` removes a key, lists are replaced whole. Values that did not change are not sent (room.js and the hub both drop them), so writing a whole object every step is fine; a write that changes nothing sends nothing.
+- Top speed: a third number in a player field's range caps how fast it moves, `player: { x: [0, 800, 300] }` = at most 300 a second. The hub cuts a bigger jump to that distance (10% headroom, measured on the senders' sample times), so a speed hack or teleport shows as normal running to everyone else and to the host's rules; the writer is not refused. A new match lets each player jump once (to a start spot); a respawn mid-match shows as a quick run. Leave it out for fields that may jump.
 - Things the host moves (monsters, minions, shots) ease smoothly on every other screen when their position fields are named `x`, `y` (also `z`, `angle`, `rot`, and a quaternion `qx, qy, qz, qw`). Players ease the same way. Others are drawn in the past by a delay measured per room (mean delay of the last 40 updates + 2 send intervals + its spread, 100 to 500 ms; usually 200 to 400), at their senders' sample times; the drawing clock follows it by running 2% fast or 4% slow; a late update: the last speed for 100 ms, then hold. Measured through the real code: 0% jump frames, speed within 1%, for 4 and 16 players with 30 ms jitter.
 - Timers are end times on the shared clock: `g.shared.set({endsAt: g.now + 60})`. The clock: 4 pings 250 ms apart after connecting, then one every 5 s; the offset of the fastest of the last 8 (none older than 60 s) is used, reached over a second, never in one step.
 - `g.shared` is read-only all the way down (frozen): a write into it throws in strict code and does nothing otherwise, and `list.sort()` on a list in it throws, so copy first (`g.shared.list.slice().sort()`). The page never copies the whole state: each write makes new objects only along the paths it changes, so a frame costs the same at 3 KB or 60 KB (0.07 ms at 60 KB with 32 moving things, was 1.4 ms). `structuredClone(g.shared)` works (plain frozen objects).
@@ -261,6 +262,14 @@ Or in your own server: `createRemote({ hub, deployment })` gives `upgrade(req, s
 - A refused page stops and shows why ("This site is not allowed for deployment dep_ab12.").
 - Not a guard: a script outside a browser can send any `Origin`. The caps, the per-address limits and revoking the id are what stop a misused deployment.
 
+### Floods and DDoS
+
+The hub and adapters cap what one client can cost (table below: sockets and new sockets per address, messages, bytes, lookups, slow headers). Keep `ws` at 8.23.0 or later (a peer that floods pings while not reading exhausted memory in earlier versions, GHSA-37g9-w4hg-h9qr); `WS_OPTIONS` keeps compression off and messages at 16 KB (ws's own default is 100 MiB). What the server cannot do alone:
+
+- Volume (a full uplink, SYN floods): the host's network filter. Most VPS hosts include one; turn on the game or always-on profile if offered.
+- Before Node: a per-address limit on new TCP connections in the firewall, generous enough for a school or office behind one address, e.g. nftables `tcp dport 443 ct state new meter tcli4 { ip saddr limit rate over 30/second burst 60 packets } drop` (and the same with `ip6 saddr`).
+- In the proxy: short header timeouts (Caddy `servers { timeouts { read_header 5s } }`). Behind a proxy set `trustProxy` so limits count players, not the proxy.
+
 ## Protocol (version 1)
 
 Every message is JSON with `v: 1`.
@@ -308,8 +317,10 @@ Saving needs a host app that gives the hub a storage port (`new RoomHub({ saves
 |---|---|
 | Players per room | 16 |
 | Rooms on the server / per namespace | 500 / 50 |
-| Sockets on the server / unverified / per address | 2000 / 200 / 20 |
-| New sockets | 200 a second (over it: 1013 busy) |
+| Sockets on the server / unverified / per address | 2000 / 200 / 20 (an IPv6 address counts by its /64, `addressKey`) |
+| New sockets | 40 per address per 10 s (`connectsPerAddress`, checked first, so one client never spends the shared budget), then 200 a second for the whole server (over either: 1013 busy) |
+| HTTP (serve, remote) | request headers within 10 s, whole request 15 s, idle keep-alive 5 s, 100 headers (`hardenServer`; Node's defaults are 60 s, 300 s, 5 s, 2000) |
+| Deployment lookups (remote) | each id at most once per 15 s, found or not (`LOOKUP_MS`; `remote.forget(id)` after an edit); fresh lookups 20 per address per 10 s |
 | Joins per address | 30 a minute |
 | Message / player state / shared state | 16 KB / 2 KB / 64 KB (the client splits bigger host updates) |
 | Shape | plain JSON, depth 4, 64 keys per object, 64 items per list, text 200 characters, keys 40 characters (`SHAPE`); a write that breaks one is refused whole |

package/client/game.js

@@ -36,7 +36,7 @@
      if (g.state === "playing") g.me.set({x: hero.x, y: hero.y});
      g.sync(function (p) { return addSprite(p); }, function (s, st) { s.x = st.x; s.y = st.y; }, function (s) { s.destroy(); });
 
-   Playing together (also load room.js before this file): pass multiplayer: {max: 4, player: {x: [0, 800], y: [0, 600]}}.
+   Playing together (also load room.js before this file): pass multiplayer: {max: 4, player: {x: [0, 800], y: [0, 600]}}. A third number is a top speed per second (x: [0, 800, 300]): the server cuts faster moves to it.
    The shell then shows the lobby (room code, invite link, players, Start for the host), reconnects, and shows notices. Your code:
      update(g, dt)     every player: move yourself, g.me.set({x, y}) (sent 12 times a second at most, clamped to the declared ranges)
      host(g, dt)       runs on ONE player only (the host): rounds, timers, health, score, who won: g.shared.set({...}); g.gameOver() ends the match

package/dist/hub.d.ts

@@ -22,6 +22,7 @@ export interface Limits {
     maxConnections: number;
     maxPending: number;
     maxPerAddress: number;
+    connectsPerAddress: number;
     joinsPerMinute: number;
     messageBytes: number;
     playerStateBytes: number;
@@ -55,6 +56,9 @@ export interface Limits {
     saveDays: number;
 }
 export declare const DEFAULT_LIMITS: Limits;
+/** The key one client is counted by: an IPv4 address as is, an IPv6 address by its first 64 bits (a home, phone or server is handed a whole /64,
+ *  so per-address limits on full IPv6 addresses would not hold anyone). IPv4-mapped IPv6 counts as the IPv4 address. */
+export declare function addressKey(addr: string): string;
 /** One open socket, as the hub sees it. */
 export interface Conn {
     send(data: string): void;
@@ -88,14 +92,17 @@ export interface Who {
     name: string;
     guest: boolean;
 }
-/** The page's declaration: room size and the number range of each player field. */
+/** The page's declaration: room size and the number range of each player field, optionally with its top speed: [lo, hi] or [lo, hi, maxPerSecond]. */
 /** saveVersion: the game's save format (whole number, default 1); a page edited to read another shape raises it (README: saved games). */
+export type Range = [number, number] | [number, number, number];
 export interface Spec {
     max: number;
-    player: Record<string, [number, number]>;
+    player: Record<string, Range>;
     save: boolean;
     saveVersion: number;
 }
+/** Headroom on a declared top speed, so an honest player moving at full speed whose update was clamped once catches up again. */
+export declare const SPEED_SLACK = 1.1;
 export interface PlayerView {
     id: string;
     name: string;
@@ -161,6 +168,11 @@ interface Seat {
     profAt: number;
     /** JSON size of state, kept up to date by each write (an exact count near the limit and every 256 writes) */
     stateBytes: number;
+    /** fields with a top speed: the last value let through and its sample time (kept when the field is removed, so null then a far value is no teleport) */
+    moved?: Map<string, {
+        v: number;
+        t: number;
+    }>;
 }
 interface Room {
     key: string;
@@ -427,6 +439,7 @@ export declare class RoomHub {
     private sessions;
     pending: number;
     private perAddr;
+    private addrHits;
     private joins;
     private refused;
     private timer;
@@ -489,10 +502,16 @@ export declare class RoomHub {
     private refuse;
     private count;
     /** A new socket. Null = refused (the caller closes it with the code given). */
-    connect(conn: Conn, addr: string): Session | {
+    /** `counted`: the adapter already spent this socket's allowAddress before its upgrade, so it is not counted twice. */
+    connect(conn: Conn, address: string, o?: {
+        counted?: boolean;
+    }): Session | {
         refused: number;
         reason: string;
     };
+    /** New-socket budget of one address (addressKey), connectsPerAddress per 10 s. Adapters may call it before costly work on an upgrade (a lookup):
+     *  false = refuse now. The window map is pruned when it grows, so random addresses cannot grow it without end. */
+    allowAddress(address: string): boolean;
     /** Meter: `n` copies of a text of `len` bytes (UTF-8, as on the wire) went out (to one room's sockets when given). */
     sent(len: number, n: number, room?: Room | null): void;
     receive(s: Session, text: string): void;
@@ -515,6 +534,10 @@ export declare class RoomHub {
     private alive;
     private vis;
     private me;
+    /** Top speeds (a third number in a field's range): a declared field moves at most speed x the time since its last update (sample times, see stamp),
+     *  with SPEED_SLACK headroom. A bigger jump is cut to that distance in the same direction: the others see the player run, not teleport, and the
+     *  writer is not refused (a game that moves a player to a far spot, a respawn, shows a quick run there). No top speed declared: no change. */
+    private speedCap;
     private sharedWrite;
     /** The sender's sample time of a write (its shared clock, whole ms), trusted within 500 ms back and 50 ms ahead; else now. Pages draw others
      *  at these times, so updates sent 80 ms apart are drawn 80 ms apart whatever the fan-out tick did to them. */

package/dist/hub.js

@@ -19,11 +19,24 @@ export const CLOSE = {
     restart: 1012, roomError: 1011, busy: 1013, silent: 4009, notAllowed: 4001, full: 4002, replaced: 4003, tooFast: 4004, badMessage: 4005, removed: 4006, gameUpdated: 4007, tooSlow: 4008, idle: 4010,
 };
 export const DEFAULT_LIMITS = {
-    maxPlayers: 16, maxRooms: 500, maxRoomsPerScope: 50, maxConnections: 2000, maxPending: 200, maxPerAddress: 20, joinsPerMinute: 30,
+    maxPlayers: 16, maxRooms: 500, maxRoomsPerScope: 50, maxConnections: 2000, maxPending: 200, maxPerAddress: 20, connectsPerAddress: 40, joinsPerMinute: 30,
     messageBytes: 16 * 1024, playerStateBytes: 2048, sharedStateBytes: 64 * 1024, stateRate: 50, sharedRate: 20, actionRate: 5, timeRate: 2,
     pendingMs: 5000, seatHoldMs: 30_000, evictAfterMs: 10_000, awayHoldMs: 300_000, hostSilenceMs: 5000, silentMs: 15_000, acceptRate: 200, roomOutBytes: 250 * 1024, maxOutMbit: 100, actionTimeoutMs: 5000, slowBytes: 64 * 1024, dropBytes: 256 * 1024, rateBytes: 16 * 1024, rateUpMs: 10_000, listRate: 1, idleMs: 15 * 60_000, idleWarnMs: 60_000, listIdleMs: 5 * 60_000, tickMs: 50,
     profileBytes: 16 * 1024, profileEveryMs: 3000, worldEveryMs: 5000, saveDays: 90,
 };
+/** The key one client is counted by: an IPv4 address as is, an IPv6 address by its first 64 bits (a home, phone or server is handed a whole /64,
+ *  so per-address limits on full IPv6 addresses would not hold anyone). IPv4-mapped IPv6 counts as the IPv4 address. */
+export function addressKey(addr) {
+    const a = String(addr || "?").toLowerCase().replace(/^::ffff:(?=\d+\.)/, "").replace(/%.*$/, "");
+    if (!a.includes(":"))
+        return a;
+    const [head, tail = ""] = a.split("::");
+    const h = head ? head.split(":") : [], t = tail ? tail.split(":") : [];
+    const groups = a.includes("::") ? [...h, ...Array(Math.max(0, 8 - h.length - t.length)).fill("0"), ...t] : h;
+    return `${groups.slice(0, 4).map((g) => (g || "0").replace(/^0+(?=.)/, "")).join(":")}::/64`;
+}
+/** Headroom on a declared top speed, so an honest player moving at full speed whose update was clamped once catches up again. */
+export const SPEED_SLACK = 1.1;
 const CODE_ABC = "ABCDEFGHJKMNPQRSTUVWXYZ23456789"; // no 0/O, 1/I/L
 const CODE_RE = /^[A-HJ-NP-Z2-9]{4,6}$/;
 const NAME_RE = /^[a-z_][a-z0-9_-]{0,23}$/i; // a leading underscore is the game shell's own (_team, _seat, _shot)
@@ -87,12 +100,14 @@ export function parseSpec(raw, maxPlayers = DEFAULT_LIMITS.maxPlayers) {
         return null;
     for (const k of keys) {
         const range = p[k];
-        if (!NAME_RE.test(k) || BAD_KEYS.has(k) || !Array.isArray(range) || range.length !== 2)
+        if (!NAME_RE.test(k) || BAD_KEYS.has(k) || !Array.isArray(range) || (range.length !== 2 && range.length !== 3))
             return null;
-        const [lo, hi] = range.map(Number);
+        const [lo, hi, speed] = range.map(Number);
         if (!Number.isFinite(lo) || !Number.isFinite(hi) || lo >= hi || Math.abs(lo) > 1e9 || Math.abs(hi) > 1e9)
             return null;
-        player[k] = [lo, hi];
+        if (range.length === 3 && (!Number.isFinite(speed) || speed <= 0 || speed > 1e9))
+            return null;
+        player[k] = range.length === 3 ? [lo, hi, speed] : [lo, hi];
     }
     return { max, player, save: r.save === true, saveVersion: sv };
 }
@@ -333,6 +348,7 @@ export class RoomHub {
     sessions = new Set();
     pending = 0;
     perAddr = new Map();
+    addrHits = new Map();
     joins = new Map();
     refused = {};
     timer = null;
@@ -391,14 +407,25 @@ export class RoomHub {
     refuse(why) { this.refused[why] = (this.refused[why] || 0) + 1; }
     count(what, n = 1) { this.counts[what] = (this.counts[what] || 0) + n; }
     /** A new socket. Null = refused (the caller closes it with the code given). */
-    connect(conn, addr) {
+    /** `counted`: the adapter already spent this socket's allowAddress before its upgrade, so it is not counted twice. */
+    connect(conn, address, o = {}) {
         const L = this.limits;
+        const addr = addressKey(address);
         if (this.closing)
             return { refused: CLOSE.restart, reason: "server restarting" };
         if (this.sessions.size >= L.maxConnections) {
             this.refuse("connections");
             return { refused: CLOSE.full, reason: "server is full" };
         }
+        // one address first: a single client flooding new sockets is cut here and never spends the server-wide budgets below that everyone shares
+        if ((this.perAddr.get(addr) || 0) >= L.maxPerAddress) {
+            this.refuse("address");
+            return { refused: CLOSE.tooFast, reason: "too many connections" };
+        }
+        if (!o.counted && !this.allowAddress(addr)) {
+            this.refuse("address_rate");
+            return { refused: CLOSE.busy, reason: "too many new connections, try again" };
+        }
         // busy (not full): the page tries again with its normal backoff, so a reconnect wave after a restart spreads out instead of ending on a "full" screen
         if (this.pending >= L.maxPending) {
             this.refuse("pending");
@@ -413,16 +440,29 @@ export class RoomHub {
             this.refuse("accept_rate");
             return { refused: CLOSE.busy, reason: "server is busy, try again" };
         }
-        if ((this.perAddr.get(addr) || 0) >= L.maxPerAddress) {
-            this.refuse("address");
-            return { refused: CLOSE.tooFast, reason: "too many connections" };
-        }
         const s = new Session(this, conn, addr);
         this.sessions.add(s);
         this.pending++;
         this.perAddr.set(addr, (this.perAddr.get(addr) || 0) + 1);
         return s;
     }
+    /** New-socket budget of one address (addressKey), connectsPerAddress per 10 s. Adapters may call it before costly work on an upgrade (a lookup):
+     *  false = refuse now. The window map is pruned when it grows, so random addresses cannot grow it without end. */
+    allowAddress(address) {
+        const key = addressKey(address), now = this.now();
+        let w = this.addrHits.get(key);
+        if (!w || now - w.at >= 10_000) {
+            if (this.addrHits.size >= 50_000)
+                for (const [k, v] of this.addrHits)
+                    if (now - v.at >= 10_000)
+                        this.addrHits.delete(k);
+            if (this.addrHits.size >= 50_000)
+                return false; // 50,000 addresses inside 10 s: refuse newcomers until the window turns
+            w = { at: now, n: 0 };
+            this.addrHits.set(key, w);
+        }
+        return ++w.n <= this.limits.connectsPerAddress;
+    }
     /** Meter: `n` copies of a text of `len` bytes (UTF-8, as on the wire) went out (to one room's sockets when given). */
     sent(len, n, room) {
         this.meter.framesOut += n;
@@ -817,7 +857,8 @@ export class RoomHub {
             if (range && v !== null && (typeof v !== "number" || v < range[0] || v > range[1]))
                 return this.err(s, "out_of_range", k);
         }
-        const ch = changedOnly(seat.state, p);
+        const at = this.stamp(m.c);
+        const ch = changedOnly(seat.state, this.speedCap(room, seat, p, at));
         if (!ch)
             return; // nothing changed: nothing applied, counted or sent
         const size = this.sized(seat.stateBytes + sizeDelta(seat.state, ch), this.limits.playerStateBytes, () => applyPatch(seat.state, ch), room);
@@ -829,7 +870,33 @@ export class RoomHub {
         const pend = room.pendPlayers.get(seat.id) ?? {};
         joinPatch(pend, ch);
         room.pendPlayers.set(seat.id, pend);
-        room.pendPT.set(seat.id, this.stamp(m.c));
+        room.pendPT.set(seat.id, at);
+    }
+    /** Top speeds (a third number in a field's range): a declared field moves at most speed x the time since its last update (sample times, see stamp),
+     *  with SPEED_SLACK headroom. A bigger jump is cut to that distance in the same direction: the others see the player run, not teleport, and the
+     *  writer is not refused (a game that moves a player to a far spot, a respawn, shows a quick run there). No top speed declared: no change. */
+    speedCap(room, seat, p, at) {
+        let out = p;
+        for (const [k, v] of Object.entries(p)) {
+            const speed = room.spec.player[k]?.[2];
+            if (speed === undefined || typeof v !== "number")
+                continue;
+            const moved = (seat.moved ??= new Map());
+            const last = moved.get(k);
+            let w = v;
+            if (last) {
+                const reach = speed * SPEED_SLACK * Math.max(0, at - last.t) / 1000;
+                if (Math.abs(v - last.v) > reach) {
+                    w = last.v + Math.sign(v - last.v) * reach;
+                    if (out === p)
+                        out = { ...p };
+                    out[k] = w;
+                    this.refuse("speed");
+                }
+            }
+            moved.set(k, { v: w, t: Math.max(at, last?.t ?? at) });
+        }
+        return out;
     }
     sharedWrite(s, room, seat, m) {
         if (room.host !== seat)
@@ -942,6 +1009,8 @@ export class RoomHub {
     beginMatch(room, resume) {
         room.startWait = null;
         room.noSave = false;
+        for (const seat of room.seats.values())
+            seat.moved = undefined; // a new match: players may jump to their start spots once
         if (resume && room.saved) {
             // Continue: the saved world becomes the shared state (the shell's clock key excepted); the game's setup must not overwrite it
             this.flush(room);