@hadoku/service-kernel 0.0.0-stage → 0.1.0

package/dist/log/log.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A service's log line: one JSON object on stdout with a timestamp, the
+ * service that wrote it, then the entry's own fields. pm2 keeps stdout, and
+ * every reader of these logs greps for `svc`.
+ */
+export type JsonLog = (entry: Record<string, unknown>) => void;
+export declare function jsonLogger(svc: string): JsonLog;

package/dist/log/log.js

@@ -0,0 +1,8 @@
+/**
+ * A service's log line: one JSON object on stdout with a timestamp, the
+ * service that wrote it, then the entry's own fields. pm2 keeps stdout, and
+ * every reader of these logs greps for `svc`.
+ */
+export function jsonLogger(svc) {
+    return (entry) => console.log(JSON.stringify({ t: new Date().toISOString(), svc, ...entry }));
+}

package/dist/relays/client-events.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A browser relay for page telemetry from a screen with no match: a flat `{ page, kind, data }`
+ * event, posted here and logged as a `client` line keyed by page and user. Nothing is stored and
+ * nothing is answered but 204. The schema, the mount path, the per-second cap and the caller's id
+ * are all parameters — this module knows no game's event shape.
+ */
+import type { Request } from 'express';
+import { Router } from 'express';
+/**
+ * What a `client-malformed` line says about telemetry the schema turned away: the event's `kind` and
+ * `data.what`, when they are strings, and each failing field by its path. Never a value. "Invalid input"
+ * alone could not say which report or which field.
+ */
+export declare function malformedFacts(raw: unknown, issues: readonly {
+    path: readonly PropertyKey[];
+    message: string;
+}[]): Record<string, unknown>;
+export interface PageEventSchema<T> {
+    safeParse(body: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            issues: readonly {
+                path: readonly PropertyKey[];
+                message: string;
+            }[];
+        };
+    };
+}
+export interface ClientEventsOptions<T extends {
+    page: unknown;
+    kind: unknown;
+    data: Record<string, unknown>;
+}> {
+    /** The event's schema. */
+    schema: PageEventSchema<T>;
+    /** The mount path under `api`, e.g. `/api/<path>`. */
+    path: string;
+    /** Per-user events-per-second cap; the rest of the second is dropped silently (204). */
+    maxPerSecond: number;
+    userIdOf: (req: Request) => string;
+    log?: (entry: Record<string, unknown>) => void;
+    now?: () => number;
+}
+export declare function attachClientEvents<T extends {
+    page: unknown;
+    kind: unknown;
+    data: Record<string, unknown>;
+}>(api: Router, opts: ClientEventsOptions<T>): void;

package/dist/relays/client-events.js

@@ -0,0 +1,53 @@
+import { Router } from 'express';
+import { bodyErrors } from "../limits/limits.js";
+/** How much of a client-chosen name (a kind, a `what`, a field's key) a `client-malformed` line keeps. */
+const NAME_MAX = 32;
+function shortName(value) {
+    return typeof value === 'string' ? value.slice(0, NAME_MAX) : undefined;
+}
+/**
+ * What a `client-malformed` line says about telemetry the schema turned away: the event's `kind` and
+ * `data.what`, when they are strings, and each failing field by its path. Never a value. "Invalid input"
+ * alone could not say which report or which field.
+ */
+export function malformedFacts(raw, issues) {
+    const event = typeof raw === 'object' && raw !== null ? raw : {};
+    const data = typeof event.data === 'object' && event.data !== null ? event.data : {};
+    return {
+        kind: shortName(event.kind),
+        what: shortName(data.what),
+        errors: issues.slice(0, 3).map((i) => `${i.path.map((k) => String(k).slice(0, NAME_MAX)).join('.') || '(event)'}: ${i.message}`),
+    };
+}
+export function attachClientEvents(api, opts) {
+    const log = opts.log ?? (() => { });
+    const now = opts.now ?? Date.now;
+    /** Per user, the second being counted and how many arrived in it. */
+    const sent = new Map();
+    const events = Router();
+    events.post('/', (req, res) => {
+        const parsed = opts.schema.safeParse(req.body);
+        const userId = opts.userIdOf(req);
+        if (!parsed.success) {
+            log({ evt: 'client-malformed', userId, ...malformedFacts(req.body, parsed.error.issues) });
+            return res.status(400).json({ error: 'not a page event' });
+        }
+        const second = Math.floor(now() / 1000);
+        const window = sent.get(userId);
+        if (window === undefined || window.second !== second) {
+            for (const [id, w] of sent)
+                if (w.second !== second)
+                    sent.delete(id);
+            sent.set(userId, { second, count: 1 });
+        }
+        else {
+            window.count += 1;
+            if (window.count > opts.maxPerSecond)
+                return res.status(204).end();
+        }
+        log({ evt: 'client', page: parsed.data.page, userId, kind: parsed.data.kind, ...parsed.data.data });
+        return res.status(204).end();
+    });
+    api.use(`/${opts.path}`, events);
+    api.use(`/${opts.path}`, bodyErrors((name) => log({ evt: 'client-error', name })));
+}

package/dist/relays/index.d.ts

@@ -0,0 +1,2 @@
+export { attachClientEvents, malformedFacts, type ClientEventsOptions, type PageEventSchema } from './client-events.js';
+export { attachUsage, MAX_BATCHES_PER_MINUTE, USAGE_TOP, USAGE_WINDOW_MS, type UsageCounter, type UsageEntry, type UsageOptions, type UsageSchema, } from './usage.js';

package/dist/relays/index.js

@@ -0,0 +1,2 @@
+export { attachClientEvents, malformedFacts } from "./client-events.js";
+export { attachUsage, MAX_BATCHES_PER_MINUTE, USAGE_TOP, USAGE_WINDOW_MS, } from "./usage.js";

package/dist/relays/usage.d.ts

@@ -0,0 +1,53 @@
+/**
+ * A browser relay for usage batches: which screens were shown and which controls pressed, counted
+ * here and posted to telemetry as one `usage` event per window — how often, by how many people,
+ * by tier. Nothing per click is kept, and nothing is answered but 204. The schema, the mount path
+ * and the caller's tier/id are all parameters — this module knows no game's usage shape.
+ *
+ * A caller sending more than `maxBatchesPerMinute` is a client bug or a script; the rest of that
+ * minute is dropped and counted as `dropped`, so the event says so.
+ */
+import type { Request } from 'express';
+import { Router } from 'express';
+import { type Report } from '../telemetry/telemetry.js';
+export declare const USAGE_WINDOW_MS: number;
+export declare const MAX_BATCHES_PER_MINUTE = 10;
+/** How many (kind, screen, target) rows one event lists, busiest first. */
+export declare const USAGE_TOP = 60;
+export interface UsageEntry {
+    kind: string;
+    screen: string;
+    target?: string;
+}
+export interface UsageSchema<T extends {
+    entries: readonly UsageEntry[];
+}> {
+    safeParse(body: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+    };
+}
+export interface UsageOptions<T extends {
+    entries: readonly UsageEntry[];
+}> {
+    schema: UsageSchema<T>;
+    /** The mount path under `api`, e.g. `/api/<path>`. */
+    path: string;
+    tierOf: (req: Request) => string;
+    userIdOf: (req: Request) => string;
+    report?: Report;
+    now?: () => number;
+    windowMs?: number;
+    maxBatchesPerMinute?: number;
+    top?: number;
+}
+export interface UsageCounter {
+    /** Post the window counted so far, if anything arrived, and start a new one. */
+    flush(): void;
+    stop(): void;
+}
+export declare function attachUsage<T extends {
+    entries: readonly UsageEntry[];
+}>(api: Router, opts: UsageOptions<T>): UsageCounter;

package/dist/relays/usage.js

@@ -0,0 +1,75 @@
+import { Router } from 'express';
+import { bodyErrors } from "../limits/limits.js";
+import { report as defaultReport } from "../telemetry/telemetry.js";
+export const USAGE_WINDOW_MS = 5 * 60_000;
+export const MAX_BATCHES_PER_MINUTE = 10;
+/** How many (kind, screen, target) rows one event lists, busiest first. */
+export const USAGE_TOP = 60;
+export function attachUsage(api, opts) {
+    const report = opts.report ?? defaultReport;
+    const now = opts.now ?? Date.now;
+    const maxBatchesPerMinute = opts.maxBatchesPerMinute ?? MAX_BATCHES_PER_MINUTE;
+    const top = opts.top ?? USAGE_TOP;
+    let counts = new Map();
+    let users = new Map();
+    let batches = 0;
+    let dropped = 0;
+    let windowStart = now();
+    const perMinute = new Map();
+    const router = Router();
+    router.post('/', (req, res) => {
+        const parsed = opts.schema.safeParse(req.body);
+        if (!parsed.success)
+            return res.status(400).json({ error: 'not a usage batch' });
+        const userId = opts.userIdOf(req);
+        const minute = Math.floor(now() / 60_000);
+        const seen = perMinute.get(userId);
+        if (seen === undefined || seen.minute !== minute) {
+            for (const [id, w] of perMinute)
+                if (w.minute !== minute)
+                    perMinute.delete(id);
+            perMinute.set(userId, { minute, n: 1 });
+        }
+        else if (++seen.n > maxBatchesPerMinute) {
+            dropped += 1;
+            return res.status(204).end();
+        }
+        batches += 1;
+        users.set(userId, opts.tierOf(req));
+        for (const e of parsed.data.entries) {
+            const key = `${e.kind} ${e.screen}${e.target === undefined ? '' : ` ${e.target}`}`;
+            counts.set(key, (counts.get(key) ?? 0) + 1);
+        }
+        return res.status(204).end();
+    });
+    api.use(`/${opts.path}`, router);
+    api.use(`/${opts.path}`, bodyErrors());
+    const flush = () => {
+        const start = windowStart;
+        windowStart = now();
+        if (batches === 0 && dropped === 0)
+            return;
+        const tiers = {};
+        for (const tier of users.values())
+            tiers[tier] = (tiers[tier] ?? 0) + 1;
+        const rows = [...counts].sort((a, b) => b[1] - a[1]);
+        report('usage', {
+            from: new Date(start).toISOString(),
+            minutes: Math.round((windowStart - start) / 60_000),
+            users: users.size,
+            tiers,
+            batches,
+            dropped,
+            views: rows.filter(([k]) => k.startsWith('view ')).reduce((n, [, c]) => n + c, 0),
+            clicks: rows.filter(([k]) => k.startsWith('click ')).reduce((n, [, c]) => n + c, 0),
+            top: Object.fromEntries(rows.slice(0, top)),
+        });
+        counts = new Map();
+        users = new Map();
+        batches = 0;
+        dropped = 0;
+    };
+    const timer = setInterval(flush, opts.windowMs ?? USAGE_WINDOW_MS);
+    timer.unref();
+    return { flush, stop: () => clearInterval(timer) };
+}

package/dist/server/bus.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The event bus a game's plugins share (`ctx.bus`): a typed emitter, synchronous, so a
+ * listener runs inside `emit` and a plugin set up later hears what an earlier one emits from
+ * then on. The kernel emits `listening` and `shutdown`; each game declares its own events in
+ * the type parameter and emits them itself.
+ */
+/** The events the kernel itself emits. A type, not an interface, so it is an `EventMap`. */
+export type KernelEvents = {
+    /** The HTTP server is listening, before any `onListen` hook or `warm` plugin runs. */
+    listening: {
+        host: string;
+        port: number;
+    };
+    /** A signal began the shutdown, before any plugin's own `shutdown` runs. */
+    shutdown: {
+        signal: string;
+        deadlineMs: number;
+    };
+};
+export type EventMap = Record<string, unknown>;
+export interface Bus<E extends EventMap> {
+    /** Listen for `event`; the returned function stops listening. */
+    on<K extends keyof E & string>(event: K, listener: (payload: E[K]) => void): () => void;
+    /** Call every listener of `event`, in the order they were added. */
+    emit<K extends keyof E & string>(event: K, payload: E[K]): void;
+}
+export declare function createBus<E extends EventMap>(): Bus<E>;

package/dist/server/bus.js

@@ -0,0 +1,21 @@
+/**
+ * The event bus a game's plugins share (`ctx.bus`): a typed emitter, synchronous, so a
+ * listener runs inside `emit` and a plugin set up later hears what an earlier one emits from
+ * then on. The kernel emits `listening` and `shutdown`; each game declares its own events in
+ * the type parameter and emits them itself.
+ */
+export function createBus() {
+    const listeners = new Map();
+    return {
+        on(event, listener) {
+            const set = listeners.get(event) ?? new Set();
+            listeners.set(event, set);
+            set.add(listener);
+            return () => void set.delete(listener);
+        },
+        emit(event, payload) {
+            for (const listener of [...(listeners.get(event) ?? [])])
+                listener(payload);
+        },
+    };
+}

package/dist/server/index.d.ts

@@ -0,0 +1,2 @@
+export { createBus, type Bus, type EventMap, type KernelEvents } from './bus.js';
+export { createGameServer, PHASES, type GameContext, type GamePlugin, type GameServer, type GameServerConfig, type GameServerOptions, type Phase, type PluginHooks, } from './server.js';

package/dist/server/index.js

@@ -0,0 +1,2 @@
+export { createBus } from "./bus.js";
+export { createGameServer, PHASES, } from "./server.js";

package/dist/server/server.d.ts

@@ -0,0 +1,157 @@
+/**
+ * `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 { type Server } from 'node:http';
+import { type Express, type Router } from 'express';
+import { Server as SocketIOServer } from 'socket.io';
+import { type EdgeAuth } from '../auth/index.js';
+import { type EraseStep } from '../erase/index.js';
+import { type BasePathVerdict, type Gate } from '../http/index.js';
+import { type BusyRun } from '../lifecycle/index.js';
+import type { JsonLog } from '../log/index.js';
+import { type Report } from '../telemetry/index.js';
+import { type Bus, type EventMap, type KernelEvents } from './bus.js';
+export declare const PHASES: readonly ["config", "bundle", "stores", "routes", "sockets", "listen", "warm"];
+export type Phase = (typeof PHASES)[number];
+export interface GameServerConfig {
+    host: string;
+    port: number;
+    /** The service's own lines: the boot clock, `shutdown-*`, and the erase route's. */
+    log: JsonLog;
+    /** The app's edge-auth binding: provenance on every request, the seal on the erase route. */
+    edgeAuth: EdgeAuth;
+    /** The app's gate: its `requireMinTier` is the HTTP floor. */
+    gate: Gate;
+    /** The prefix the edge serves this app under (`/<game>`); names `/health`'s service. */
+    basePrefix: string;
+    /** The built bundle: its index page, the directory served beside it, and the entry files that keep their names. */
+    bundle: {
+        indexHtml: string;
+        webDir: string;
+        embedEntries: readonly string[];
+    };
+    /** This instance's checkout, for `/health`'s commit. */
+    repoRoot: string;
+    /** The socket event that tells every client the server is restarting. */
+    restartEvent: string;
+    /** Built and installed after the `bundle` phase, before any plugin's route. Absent: events go nowhere. */
+    telemetry?: () => Report;
+    /** The accounts this server has admitted, kept across restarts (`caller-first-seen`). */
+    firstSeen: {
+        file: string;
+        log: JsonLog;
+    };
+    /** The app's own derived id for an erased account (`personOf`). */
+    erase: {
+        deriveParticipantId: (userId: string) => string;
+    };
+    /** A request path counted on its own, never timed nor logged a line each, and its capacity field. */
+    uncounted?: {
+        path: (path: string) => boolean;
+        field: string;
+    };
+    /** `X-Hadoku-Origin`; defaults to the game's id. */
+    origin?: string;
+    /** Stamp each kernel phase on the boot clock (default true). */
+    stampPhases?: boolean;
+    shutdown?: {
+        deadlineMs?: number;
+        requestGraceMs?: number;
+        restartFlushMs?: number;
+    };
+    /** Install SIGTERM/SIGINT handlers (default true). */
+    signals?: boolean;
+    /** Ends the process once shut down; `process.exit` unless a test passes its own. */
+    exit?: (code: number) => void;
+}
+export interface GameContext<E extends EventMap, S> {
+    readonly id: string;
+    readonly app: Express;
+    /** Mounted at `/api`, below the floor, after the JSON body parser. */
+    readonly api: Router;
+    /** Above the floor, behind the edge's seal and no tier: what the edge itself serves publicly. */
+    readonly sealed: Router;
+    readonly httpServer: Server;
+    readonly io: SocketIOServer;
+    readonly bus: Bus<KernelEvents & E>;
+    /** The bundle check's verdict, from the `bundle` phase on. */
+    readonly bundle: BasePathVerdict;
+    /** The game's own state, shared between its plugins. */
+    readonly state: S;
+    /** Stamp a named step on the boot clock. */
+    bootPhase(name: string): void;
+    /** Add a gauge to the capacity sample, read each sample. */
+    gauge(name: string, read: () => number): void;
+    /** Add counts to each capacity post, read once as it goes out. */
+    counts(read: () => Record<string, unknown>): void;
+    /** Add runs to the busy probe's answer. */
+    busy(read: () => BusyRun[]): void;
+}
+export interface PluginHooks {
+    /** Runs at shutdown, in reverse setup order; what it returns is added to `shutdown-done`. */
+    shutdown?: () => Record<string, unknown> | void;
+    /** Registered on the erase route in setup order. */
+    erase?: EraseStep[];
+    /** Runs once the server listens, in setup order, before the `listen` phase. */
+    onListen?: () => void;
+}
+export interface GamePlugin<E extends EventMap, S> {
+    name: string;
+    phase: Phase;
+    setup(ctx: GameContext<E, S>): PluginHooks | void | Promise<PluginHooks | void>;
+}
+export interface GameServer<E extends EventMap, S> {
+    readonly app: Express;
+    readonly httpServer: Server;
+    readonly io: SocketIOServer;
+    readonly bus: Bus<KernelEvents & E>;
+    readonly state: S;
+    /** Shut down as a signal would; resolves with why it finished (`closed` or `deadline`). */
+    shutdown(signal: string): Promise<string>;
+}
+export interface GameServerOptions<E extends EventMap, S> {
+    id: string;
+    config: GameServerConfig;
+    state: S;
+    plugins: readonly GamePlugin<E, S>[];
+}
+export declare function createGameServer<E extends EventMap, S>({ id, config, state, plugins }: GameServerOptions<E, S>): Promise<GameServer<E, S>>;