@hadoku/service-kernel 0.0.0-stage → 0.1.4

package/dist/server/server.js

@@ -0,0 +1,244 @@
+/**
+ * `createGameServer`: the one boot sequence every game's server runs, so a game is its config
+ * and a list of plugins.
+ *
+ * ## What the kernel owns
+ *
+ * The express app and its `/api` router, the HTTP server and the socket.io server; edge
+ * provenance and the tier floor (the app's `EdgeAuth` and `Gate`, `../auth` and `../http`);
+ * `/health` and the local-only busy probe; the telemetry sink and the capacity sampler; the
+ * account-erase route and its registry; the origin stamp; `listen`; and SIGTERM/SIGINT with
+ * the restart notice, the connection grace and the shutdown deadline.
+ *
+ * ## The order a request meets
+ *
+ *   provenance → capacity → access log → /health, /health/busy, the erase route, the sealed routes
+ *   → the tier floor → first-seen → /api (JSON body, then the plugins' routes)
+ *   → the bundle's static files → the plugins' own app routes, in registration order
+ *
+ * Everything above the floor is public on purpose; a plugin registers nothing above it except on
+ * `sealed`, which answers only a request carrying the edge's seal and passes every other one on to
+ * the floor. The edge seals each request it proxies whatever the caller's tier, so a route there is
+ * reachable through hadoku.me by anyone the edge itself lets through (a link-preview crawler, say),
+ * and never by a direct hit on the tunnel.
+ *
+ * ## Boot phases
+ *
+ * `config → bundle → stores → routes → sockets → listen → warm`, each plugin's `setup` in
+ * array order within its phase. The kernel checks the bundle at the start of `bundle` and
+ * installs telemetry at its end, builds first-seen at the end of `config` (so a state-dir move in `config`
+ * happens before it reads its file), and starts listening between `sockets` and `listen`:
+ * `listen` and `warm` run once the server answers, `warm` last. The boot clock stamps each phase as it ends, unless the
+ * config turns that off to keep a game's own names (`stampPhases: false`, `ctx.bootPhase`).
+ *
+ * ## Going down
+ *
+ * The first SIGTERM or SIGINT logs `shutdown-begin`, emits `shutdown` on the bus, runs every
+ * plugin's `shutdown` in REVERSE setup order (the last thing built goes first), then tells
+ * every socket the game's restart event, closes socket.io and the HTTP server, and lets
+ * in-flight requests finish within `requestGraceMs`. It exits on the close or at
+ * `deadlineMs`, whichever comes first, logging `shutdown-done` with the fields the plugins'
+ * shutdowns returned.
+ */
+import { createServer } from 'node:http';
+import express from 'express';
+import { Server as SocketIOServer } from 'socket.io';
+import { callerIdOf, tierOf, userIdOf } from "../auth/index.js";
+import { capacitySampler } from "../capacity/index.js";
+import { createAccountErase, ERASE_PATH } from "../erase/index.js";
+import { healthResponse, readCommit, serviceIdOf } from "../health/index.js";
+import { checkBundle, isEmbedEntry, stampOrigin } from "../http/index.js";
+import { bootClock, busyHandler, closeConnections, sendThenFlush } from "../lifecycle/index.js";
+import { firstSeen, installTelemetry } from "../telemetry/index.js";
+import { createBus } from "./bus.js";
+export const PHASES = ['config', 'bundle', 'stores', 'routes', 'sockets', 'listen', 'warm'];
+const DEFAULT_SHUTDOWN = { deadlineMs: 1_300, requestGraceMs: 300, restartFlushMs: 500 };
+export async function createGameServer({ id, config, state, plugins }) {
+    const { log } = config;
+    const stamp = bootClock(log);
+    const stampPhases = config.stampPhases ?? true;
+    const timing = { ...DEFAULT_SHUTDOWN, ...config.shutdown };
+    const exit = config.exit ?? ((code) => process.exit(code));
+    const bus = createBus();
+    // The kernel's own two events, emitted through the same bus the game's plugins share.
+    const kernelBus = bus;
+    const app = express();
+    app.set('trust proxy', true);
+    app.disable('x-powered-by');
+    const httpServer = createServer(app);
+    // The default path: the edge strips the base prefix before the socket's request reaches us.
+    const io = new SocketIOServer(httpServer, { serveClient: false });
+    const gauges = { sockets: () => io.engine.clientsCount };
+    const countReaders = [];
+    const capacity = capacitySampler({
+        gauges,
+        counts: () => Object.assign({}, ...countReaders.map((read) => read())),
+        ...(config.uncounted === undefined ? {} : { uncountedPath: config.uncounted.path, uncountedField: config.uncounted.field }),
+    });
+    const quiet = config.uncounted?.path ?? (() => false);
+    let verdict;
+    const service = serviceIdOf(config.basePrefix, id);
+    const commit = readCommit(config.repoRoot);
+    const busyReaders = [];
+    const accountErase = createAccountErase({ log, edgeSealed: config.edgeAuth.edgeSealed, deriveParticipantId: config.erase.deriveParticipantId });
+    let seen;
+    app.use(config.edgeAuth.edgeProvenance);
+    app.use(capacity.requests);
+    app.use((req, res, next) => {
+        if (quiet(req.path)) {
+            next();
+            return;
+        }
+        const start = process.hrtime.bigint();
+        res.on('finish', () => {
+            const ms = Number(process.hrtime.bigint() - start) / 1e6;
+            // The identity the handlers saw, post-sanitize: a spoofed request logs as public.
+            console.log(JSON.stringify({ t: new Date().toISOString(), svc: id, method: req.method, path: req.path, status: res.statusCode, ms: Math.round(ms), user: userIdOf(req), tier: tierOf(req) }));
+        });
+        next();
+    });
+    // Public: the monitoring probe has no key. A server up but serving a bundle nobody can load says so.
+    app.get('/health', (_req, res) => {
+        const { code, body } = healthResponse({ service, commit, bundle: verdict ?? { ok: false, reason: 'missing' } });
+        res.status(code).json(body);
+    });
+    // Local only, and a bare 404 to anyone else: the deploy asks it before stopping us.
+    app.get('/health/busy', busyHandler(() => {
+        const runs = busyReaders.flatMap((read) => read());
+        return { busy: runs.length > 0, count: runs.length, runs };
+    }));
+    // The edge's seal only, never a tier, and above first-seen so an erase does not record the person again.
+    app.post(ERASE_PATH, (req, res) => void accountErase.handle(req, res));
+    const sealed = express.Router();
+    app.use((req, res, next) => (config.edgeAuth.edgeSealed(req) ? sealed(req, res, next) : next()));
+    // ── The tier floor: everything below is gated ──
+    app.use(config.gate.requireMinTier);
+    app.use((req, res, next) => (seen === undefined ? next() : seen(req, res, next)));
+    const api = express.Router();
+    api.use(express.json({ limit: '1mb' }));
+    app.use('/api', api);
+    // Hashed names are immutable; index.html is never cached; the embed entries keep their names, so they revalidate.
+    const statics = express.static(config.bundle.webDir, {
+        index: false,
+        maxAge: '1y',
+        immutable: true,
+        setHeaders: (res, filePath) => {
+            if (filePath.endsWith('index.html'))
+                res.setHeader('Cache-Control', 'no-store');
+            else if (isEmbedEntry(filePath, config.bundle.embedEntries))
+                res.setHeader('Cache-Control', 'no-cache');
+        },
+    });
+    app.use((req, res, next) => (verdict?.ok === true ? statics(req, res, next) : next()));
+    const ctx = {
+        id,
+        app,
+        api,
+        sealed,
+        httpServer,
+        io,
+        bus,
+        state,
+        get bundle() {
+            if (verdict === undefined)
+                throw new Error('the bundle is checked in the bundle phase; read it from then on');
+            return verdict;
+        },
+        bootPhase: stamp,
+        gauge: (name, read) => void (gauges[name] = read),
+        counts: (read) => void countReaders.push(read),
+        busy: (read) => void busyReaders.push(read),
+    };
+    const stoppers = [];
+    const listeners = [];
+    const runPhase = async (phase) => {
+        for (const plugin of plugins) {
+            if (plugin.phase !== phase)
+                continue;
+            const hooks = (await plugin.setup(ctx)) ?? {};
+            if (hooks.shutdown !== undefined)
+                stoppers.push({ name: plugin.name, stop: hooks.shutdown });
+            for (const step of hooks.erase ?? [])
+                accountErase.register(step);
+            if (hooks.onListen !== undefined)
+                listeners.push(hooks.onListen);
+        }
+        if (stampPhases)
+            stamp(phase);
+    };
+    await runPhase('config');
+    seen = firstSeen({ file: config.firstSeen.file, userIdOf: callerIdOf, tierOf, log: config.firstSeen.log });
+    const callersSeen = seen;
+    accountErase.register({ what: 'callersSeen', erase: (p) => callersSeen.forget(p.userId) });
+    verdict = await checkBundle(config.bundle.indexHtml, config.basePrefix);
+    await runPhase('bundle');
+    if (config.telemetry !== undefined)
+        installTelemetry(config.telemetry());
+    await runPhase('stores');
+    await runPhase('routes');
+    await runPhase('sockets');
+    let shuttingDown;
+    const shutdown = (signal) => {
+        // A second signal is the process manager being impatient, not a second shutdown.
+        if (shuttingDown !== undefined)
+            return shuttingDown;
+        shuttingDown = new Promise((done) => {
+            const startedAt = Date.now();
+            log({ evt: 'shutdown-begin', signal });
+            kernelBus.emit('shutdown', { signal, deadlineMs: timing.deadlineMs });
+            const fields = {};
+            for (const { name, stop } of [...stoppers].reverse()) {
+                try {
+                    Object.assign(fields, stop() ?? {});
+                }
+                catch (err) {
+                    // One plugin that will not let go must not stop the rest of the shutdown.
+                    log({ evt: 'shutdown-plugin-failed', plugin: name, error: err.message });
+                }
+            }
+            let finished = false;
+            const finish = (why) => {
+                if (finished)
+                    return;
+                finished = true;
+                log({ evt: 'shutdown-done', signal, why, ms: Date.now() - startedAt, ...fields });
+                done(why);
+                exit(0);
+            };
+            // Referenced on purpose: it holds the process up for the closes below, and ends it if one never returns.
+            const deadline = setTimeout(() => finish('deadline'), timing.deadlineMs);
+            // `io.close` drops whatever a connection has not written, so the notice is let out first.
+            void sendThenFlush([...io.sockets.sockets.values()].map((socket) => socket.conn), () => io.emit(config.restartEvent), timing.restartFlushMs).then(() => {
+                // Disconnects every socket and closes the HTTP server it was given.
+                io.close(() => {
+                    clearTimeout(deadline);
+                    finish('closed');
+                });
+                closeConnections(httpServer, timing.requestGraceMs);
+            });
+        });
+        return shuttingDown;
+    };
+    if (config.signals ?? true) {
+        process.on('SIGTERM', () => void shutdown('SIGTERM'));
+        process.on('SIGINT', () => void shutdown('SIGINT'));
+    }
+    // After every socket.io attach: engine.io moves itself to the front of the request listeners.
+    stampOrigin(httpServer, config.origin ?? id);
+    await new Promise((listening, failed) => {
+        httpServer.once('error', failed);
+        httpServer.listen(config.port, config.host, () => {
+            httpServer.off('error', failed);
+            listening();
+        });
+    });
+    capacity.start();
+    const { port } = httpServer.address();
+    console.log(`[${id}] listening on ${config.host}:${port}`);
+    kernelBus.emit('listening', { host: config.host, port });
+    for (const onListen of listeners)
+        onListen();
+    await runPhase('listen');
+    await runPhase('warm');
+    return { app, httpServer, io, bus, state, shutdown };
+}

package/dist/state/index.d.ts

@@ -0,0 +1 @@
+export { moveLegacyDir, moveLegacyState, type StateMove } from './state-dir.js';

package/dist/state/index.js

@@ -0,0 +1 @@
+export { moveLegacyDir, moveLegacyState } from "./state-dir.js";

package/dist/state/state-dir.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The boot move from an in-clone layout to a state directory the app sets up
+ * outside its deploy clone.
+ *
+ * Until a deploy builds its new clone aside and swaps it in, everything a
+ * server writes lives in the clone (e.g. `apps/server/data`, `apps/server/logs`).
+ * A swapped clone has none of it, so the state has to live outside before that
+ * deploy is turned on. The first boot that has a state dir moves each entry of
+ * the old directory into the new one; an entry already there is never
+ * overwritten, and is left where it was and reported. Runs before anything opens
+ * a store.
+ */
+export interface StateMove {
+    from: string;
+    to: string;
+    /** Entries moved into `to`. */
+    moved: string[];
+    /** Entries left in `from` because `to` already holds one of that name. */
+    kept: string[];
+}
+/**
+ * Move every entry of `from` into `to` that `to` lacks, then remove `from` if
+ * that emptied it. Null when there was nothing to move: `from` missing, or the
+ * same directory as `to`.
+ */
+export declare function moveLegacyDir(from: string, to: string): StateMove | null;
+/**
+ * The boot move for a server: its in-clone `data/` and `logs/` into the state
+ * dir, when one is set. Logs one `state-moved` line per directory that held
+ * anything, so the cutover is visible in pm2's log.
+ */
+export declare function moveLegacyState(config: {
+    stateDir: string;
+    dataDir: string;
+    logDir: string;
+}, legacy: {
+    dataDir: string;
+    logDir: string;
+}, log: (entry: Record<string, unknown>) => void): StateMove[];

package/dist/state/state-dir.js

@@ -0,0 +1,63 @@
+/**
+ * The boot move from an in-clone layout to a state directory the app sets up
+ * outside its deploy clone.
+ *
+ * Until a deploy builds its new clone aside and swaps it in, everything a
+ * server writes lives in the clone (e.g. `apps/server/data`, `apps/server/logs`).
+ * A swapped clone has none of it, so the state has to live outside before that
+ * deploy is turned on. The first boot that has a state dir moves each entry of
+ * the old directory into the new one; an entry already there is never
+ * overwritten, and is left where it was and reported. Runs before anything opens
+ * a store.
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync, renameSync, rmdirSync, rmSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+/** Rename, or copy then delete when `to` is on another filesystem. */
+function moveEntry(from, to) {
+    try {
+        renameSync(from, to);
+    }
+    catch (err) {
+        if (err.code !== 'EXDEV')
+            throw err;
+        cpSync(from, to, { recursive: true, preserveTimestamps: true, verbatimSymlinks: true });
+        rmSync(from, { recursive: true, force: true });
+    }
+}
+/**
+ * Move every entry of `from` into `to` that `to` lacks, then remove `from` if
+ * that emptied it. Null when there was nothing to move: `from` missing, or the
+ * same directory as `to`.
+ */
+export function moveLegacyDir(from, to) {
+    const src = resolve(from);
+    const dst = resolve(to);
+    if (src === dst || !existsSync(src))
+        return null;
+    mkdirSync(dst, { recursive: true });
+    const move = { from: src, to: dst, moved: [], kept: [] };
+    for (const name of readdirSync(src).sort()) {
+        if (existsSync(join(dst, name))) {
+            move.kept.push(name);
+            continue;
+        }
+        moveEntry(join(src, name), join(dst, name));
+        move.moved.push(name);
+    }
+    if (move.kept.length === 0)
+        rmdirSync(src);
+    return move;
+}
+/**
+ * The boot move for a server: its in-clone `data/` and `logs/` into the state
+ * dir, when one is set. Logs one `state-moved` line per directory that held
+ * anything, so the cutover is visible in pm2's log.
+ */
+export function moveLegacyState(config, legacy, log) {
+    if (!config.stateDir)
+        return [];
+    const moves = [moveLegacyDir(legacy.dataDir, config.dataDir), moveLegacyDir(legacy.logDir, config.logDir)].filter((m) => m !== null);
+    for (const m of moves)
+        log({ event: m.kept.length ? 'state-moved-partly' : 'state-moved', ...m });
+    return moves;
+}

package/dist/telemetry/index.d.ts

@@ -0,0 +1 @@
+export { callerContext, firstSeen, installTelemetry, monitoringSink, report, reportingAlerts, reportSealRefused, siteOf, userAgentOf, type FirstSeen, type FirstSeenOptions, type JsonLog, type Level, type Report, type SinkOptions, type TelemetryContext, type TelemetryValue, } from './telemetry.js';

package/dist/telemetry/index.js

@@ -0,0 +1 @@
+export { callerContext, firstSeen, installTelemetry, monitoringSink, report, reportingAlerts, reportSealRefused, siteOf, userAgentOf, } from "./telemetry.js";

package/dist/telemetry/telemetry.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Security telemetry: who got in, who was turned away, and who is spending the costly acts — the
+ * platform half. Knows no game: the service id, the deployment site and the refusal surface are
+ * all parameters, so an app that posts under `service: 'cardtable'` and one that posts under a
+ * second game's id read apart in the same monitoring store. See the app's own adapter (this
+ * wave's `apps/server/src/telemetry.ts`) for the one place those values get bound.
+ *
+ * Everything here is fire-and-forget. A post that fails is logged on stdout (pm2 keeps it), never
+ * retried, and never delays the request that caused it. One event per (name, caller, incident
+ * key) per window goes out; the rest are counted and ride on the next one as `suppressed`, so a
+ * scanner hammering the seal costs monitoring one row a minute, not one per request.
+ */
+import type { NextFunction, Request, Response } from 'express';
+/**
+ * A log line: one object a reader can grep by its own fields. This module never imports a
+ * concrete logger (another lane owns that), so it takes whatever shape fits.
+ */
+export type JsonLog = (entry: Record<string, unknown>) => void;
+export type TelemetryValue = string | number | boolean | null | TelemetryValue[] | {
+    [key: string]: TelemetryValue;
+};
+export type TelemetryContext = Record<string, TelemetryValue>;
+/**
+ * How much an event needs a person. monitoring-api stores `debug | info | warn | error` and
+ * answers 400 to anything else, so `critical` goes out as `error` with `severity: 'critical'`
+ * in its context; a reader takes `severity` over the level column.
+ */
+export type Level = 'info' | 'warn' | 'error' | 'critical';
+/** `level` overrides the name rule (`levelOf`). */
+export type Report = (event: string, context: TelemetryContext, level?: Level) => void;
+/** The process's reporter. The app's boot installs the monitoring sink once. */
+export declare function installTelemetry(sink: Report): void;
+/** Report one event. A no-op until a sink is installed. */
+export declare function report(event: string, context: TelemetryContext, level?: Level): void;
+/**
+ * Which deployment a base path is: `/<service>` is prod, `/<service>-<site>` that site (a PPE
+ * wrapper's prefix, e.g. `/<service>-ppe`). Any other prefix names itself.
+ */
+export declare function siteOf(basePrefix: string, service: string): string;
+/**
+ * The hosting alerts (`play/placement/alerts.ts`) as service events, so the daily report lists
+ * each one beside the seal refusals. Wraps the log the alerts are given: every entry still goes
+ * to it, and each `alert` entry — one per message the alerts post to Discord — is also reported
+ * as `alert` with its key and text, at `alertLevel`. Every key is reported, so an alert kind
+ * added later needs nothing here.
+ */
+export declare function reportingAlerts(log: JsonLog, sink?: Report): JsonLog;
+export interface SinkOptions {
+    /** `https://hadoku.me` — the telemetry route is `/health/api/telemetry` under it. */
+    baseUrl: string;
+    serviceKey: string;
+    /** The env var named in the disabled-reason log line, when `serviceKey` is empty (e.g. `CARDTABLE_SERVICE_KEY`). */
+    serviceKeyEnvVar: string;
+    log: JsonLog;
+    /** Stamped on every event's `context.service`, and in the posting User-Agent. */
+    service: string;
+    /** This deployment (`siteOf`), on every event. */
+    site: string;
+    /** One post per (event, caller, incident key) per this many ms. */
+    windowMs?: number;
+    now?: () => number;
+    fetch?: typeof fetch;
+}
+/**
+ * A reporter that posts to monitoring-api. Without a service key it posts
+ * nothing and says so once, the way the stats reporter does.
+ */
+export declare function monitoringSink(opts: SinkOptions): Report;
+type Headers = Request['headers'];
+/** The caller's user agent, cut short: enough to tell a browser from a script. */
+export declare function userAgentOf(headers: Headers): string | null;
+/**
+ * Who a request or handshake says it is, from the edge's headers AFTER
+ * `sanitizeHeaders` — so a spoofed caller reports as public with a null userId,
+ * exactly what the handlers saw.
+ */
+export declare function callerContext(headers: Headers): TelemetryContext;
+/**
+ * A seal below the edge refused a caller. With the edge in front this should
+ * never fire: one means a direct hit on the tunnel host, or an edge rule wider
+ * than this server's floor — both worth a look. `Surface` is an open string:
+ * this module knows no game's surface names, so the app's own adapter narrows
+ * it to a closed set.
+ */
+export declare function reportSealRefused<Surface extends string>(surface: Surface, headers: Headers, path: string | null): void;
+export interface FirstSeenOptions {
+    /** The JSON list of every user id this server has admitted, kept across restarts. */
+    file: string;
+    userIdOf: (req: Request) => string | null;
+    tierOf: (req: Request) => string;
+    log: JsonLog;
+}
+export interface FirstSeen {
+    (req: Request, res: Response, next: NextFunction): void;
+    /** Drop one account from the list (account erase); 1 when it was there, else 0. */
+    forget(userId: string): number;
+}
+/**
+ * Middleware, mounted below the tier floor: the first request this server ever
+ * admits from a user id reports `caller-first-seen` with its tier and user
+ * agent — the "who is getting in" signal, once per account, not per visit.
+ * Callers the edge named nobody (a null userId) are not accounts and are skipped.
+ */
+export declare function firstSeen(opts: FirstSeenOptions): FirstSeen;
+export {};