toiljs 0.0.33 → 0.0.36

package/examples/basic/server/core/AppHandler.ts

@@ -0,0 +1,290 @@
+import { Method, Request, Response, Rest, ToilHandler } from 'toiljs/server/runtime';
+
+/**
+ * The app's request handler: every request enters here. `@rest` controllers (see
+ * `routes/`) are tried first via `Rest.dispatch`; whatever they do not claim falls
+ * through to the hand-rolled demo endpoints below, then yields to the client.
+ */
+export class AppHandler extends ToilHandler {
+    public handle(req: Request): Response {
+        // Rest.dispatch returns the first matching route's Response, or null if nothing
+        // matched - then we fall through to our own logic. REST composes; it never takes
+        // over handle().
+        const hit = Rest.dispatch(req);
+        if (hit != null) {
+            return hit;
+        }
+
+        if (req.method != Method.GET && req.method != Method.HEAD) {
+            return Response.empty(405).setHeader('allow', 'GET, HEAD');
+        }
+
+        if (req.path == '/json') {
+            return Response.json('{"hello":"toiljs"}\n');
+        }
+
+        if (req.path == '/echo') {
+            return Response.text('you GET ' + req.path + '\n');
+        }
+
+        // Web Crypto demo. `crypto` is a global (no import), synchronous: the
+        // same SubtleCrypto-style API the browser has, running in the server
+        // wasm via metered host functions.
+        if (req.path == '/api/hash') {
+            const digest = crypto.sha256Text(req.path);
+            return Response.json('{"sha256":"' + crypto.toHex(digest) + '"}\n');
+        }
+
+        if (req.path == '/api/uuid') {
+            return Response.text(crypto.randomUUID() + '\n');
+        }
+
+        // Cookies. `Cookie`, `Cookies`, `SecureCookies`, and `SameSite` are ambient
+        // globals (no import), exactly like `crypto`. The demo lives in its own
+        // method; the client page is `client/routes/cookies.tsx`.
+        const cookie = this.cookieDemo(req);
+        if (cookie != null) return cookie;
+
+        // Unhandled (not a plain notFound): tells the host this server has no
+        // answer for the path, so it may serve it itself. Under `toiljs dev`
+        // that falls through to Vite (client routes, assets).
+        return Response.unhandled();
+    }
+
+    /**
+     * The `/api/cookies/*` demo. Each endpoint returns JSON so the client page can
+     * render the actual cookie output. Returns `null` for a non-cookie path.
+     */
+    private cookieDemo(req: Request): Response | null {
+        // GALLERY: the serialized `Set-Cookie` output of every capability, no
+        // round-trip needed. This is the "everything you can do" reference.
+        if (req.path == '/api/cookies/gallery') {
+            const labels = new Array<string>();
+            const cookies = new Array<string>();
+
+            labels.push('basic');
+            cookies.push(Cookie.create('id', 'abc123').serialize());
+            labels.push('percent-encoded (default)');
+            cookies.push(Cookie.create('msg', 'hello world & more!').serialize());
+            labels.push('base64url-encoded');
+            cookies.push(Cookie.create('data', 'hello').withEncoding(CookieEncoding.Base64Url).serialize());
+            labels.push('raw (no encoding)');
+            cookies.push(Cookie.create('tok', 'AAAA.BBBB').withEncoding(CookieEncoding.Raw).serialize());
+            labels.push('Max-Age');
+            cookies.push(Cookie.create('a', 'b').maxAge(3600).serialize());
+            labels.push('Expires (from epoch seconds)');
+            cookies.push(Cookie.create('a', 'b').expires(1700000000).serialize());
+            labels.push('Domain + Path');
+            cookies.push(Cookie.create('a', 'b').domain('example.com').path('/app').serialize());
+            labels.push('Secure + HttpOnly');
+            cookies.push(Cookie.create('a', 'b').secure().httpOnly().serialize());
+            labels.push('SameSite=Strict');
+            cookies.push(Cookie.create('a', 'b').sameSite(SameSite.Strict).serialize());
+            labels.push('SameSite=None (implies Secure)');
+            cookies.push(Cookie.create('a', 'b').sameSite(SameSite.None).serialize());
+            labels.push('Partitioned / CHIPS (implies Secure)');
+            cookies.push(Cookie.create('a', 'b').partitioned().serialize());
+            labels.push('Priority');
+            cookies.push(Cookie.create('a', 'b').priority('High').serialize());
+            labels.push('__Host- prefix (Secure + Path=/ + no Domain)');
+            cookies.push(Cookie.create('sid', 'x').asHostPrefixed().serialize());
+            labels.push('__Secure- prefix');
+            cookies.push(Cookie.create('sid', 'x').asSecurePrefixed().serialize());
+            labels.push('Max-Age clamped to the 400-day cap');
+            cookies.push(Cookie.create('a', 'b').maxAge(99999999).serialize());
+            labels.push('everything at once');
+            cookies.push(
+                Cookie.create('full', 'v')
+                    .domain('example.com')
+                    .path('/')
+                    .maxAge(86400)
+                    .secure()
+                    .httpOnly()
+                    .sameSite(SameSite.Lax)
+                    .partitioned()
+                    .priority('Medium')
+                    .extension('CustomFlag')
+                    .serialize(),
+            );
+
+            let json = '{';
+            for (let i = 0; i < labels.length; i++) {
+                if (i > 0) json += ',';
+                json += '"' + this.esc(labels[i]) + '":"' + this.esc(cookies[i]) + '"';
+            }
+            json += '}';
+            return Response.json(json);
+        }
+
+        // SET: store three real cookies on the browser. A plain visit counter
+        // (readable by JS), an HMAC-signed session, and an AES-256-GCM-encrypted
+        // secret (both HttpOnly, so invisible to JS but readable by the server).
+        if (req.path == '/api/cookies/set') {
+            const prev = req.cookie('visits');
+            let next: string;
+            if (prev == null) next = '1';
+            else next = (this.toI32(prev) + 1).toString();
+
+            const visits = Cookie.create('visits', next).path('/').sameSite(SameSite.Lax).maxAge(86400);
+            const session = SecureCookies.signed(this.demoKey()).seal(
+                Cookie.create('session', 'user-42').httpOnly().sameSite(SameSite.Strict).asHostPrefixed(),
+            );
+            const secret = SecureCookies.encrypted(this.demoKey()).seal(
+                Cookie.create('secret', 'top-secret-value').httpOnly().path('/'),
+            );
+
+            const json =
+                '{"visits":' +
+                next +
+                ',"emitted":["' +
+                this.esc(visits.serialize()) +
+                '","' +
+                this.esc(session.serialize()) +
+                '","' +
+                this.esc(secret.serialize()) +
+                '"]}';
+            return Response.json(json).setCookie(visits).setCookie(session).setCookie(secret);
+        }
+
+        // INSPECT: what the server sees. Parses the `Cookie` header, then verifies
+        // the signed session (HMAC) and decrypts the secret (AES-GCM) server-side.
+        if (req.path == '/api/cookies/inspect') {
+            const raw = req.header('cookie');
+            const jar = req.cookies();
+            const names = jar.names();
+
+            let parsed = '{';
+            for (let i = 0; i < names.length; i++) {
+                if (i > 0) parsed += ',';
+                const val = jar.get(names[i]);
+                parsed += '"' + this.esc(names[i]) + '":"' + this.esc(val == null ? '' : val) + '"';
+            }
+            parsed += '}';
+
+            const session = SecureCookies.signed(this.demoKey()).open(jar, '__Host-session');
+            const secret = SecureCookies.encrypted(this.demoKey()).open(jar, 'secret');
+
+            const json =
+                '{"raw":"' +
+                this.esc(raw == null ? '' : raw) +
+                '","count":' +
+                names.length.toString() +
+                ',"cookies":' +
+                parsed +
+                ',"session":' +
+                (session == null ? 'null' : '"' + this.esc(session) + '"') +
+                ',"secret":' +
+                (secret == null ? 'null' : '"' + this.esc(secret) + '"') +
+                '}';
+            return Response.json(json);
+        }
+
+        // CLEAR: expire the demo cookies (Max-Age=0 + epoch Expires).
+        if (req.path == '/api/cookies/clear') {
+            const json =
+                '{"cleared":["' +
+                this.esc(this.clearString('visits')) +
+                '","' +
+                this.esc(this.clearString('__Host-session')) +
+                '","' +
+                this.esc(this.clearString('secret')) +
+                '"]}';
+            return Response.json(json)
+                .clearCookie('visits')
+                .clearCookie('__Host-session')
+                .clearCookie('secret');
+        }
+
+        // SEAL: sign and encrypt a value (from `?v=`), then recover both and show
+        // that a tampered signature fails to verify. Pure backend crypto, no headers.
+        if (req.path.indexOf('/api/cookies/seal') == 0) {
+            const value = this.queryValue(req.path, 'v', 'hello toiljs');
+            const signer = SecureCookies.signed(this.demoKey());
+            const box = SecureCookies.encrypted(this.demoKey());
+
+            const signed = signer.sign('demo', value);
+            const encrypted = box.encrypt('demo', value);
+            const unsigned = signer.unsign('demo', signed);
+            const decrypted = box.decrypt('demo', encrypted);
+            const tampered = signer.unsign('demo', this.flip(signed));
+
+            const json =
+                '{"value":"' +
+                this.esc(value) +
+                '","signed":"' +
+                this.esc(signed) +
+                '","unsigned":' +
+                (unsigned == null ? 'null' : '"' + this.esc(unsigned) + '"') +
+                ',"encrypted":"' +
+                this.esc(encrypted) +
+                '","decrypted":' +
+                (decrypted == null ? 'null' : '"' + this.esc(decrypted) + '"') +
+                ',"tamperVerifies":' +
+                (tampered == null ? 'false' : 'true') +
+                '}';
+            return Response.json(json);
+        }
+
+        return null;
+    }
+
+    // Demo signing/encryption key: 32 bytes, valid for AES-256-GCM and HMAC. A real
+    // app loads a long random secret from config; never hard-code one.
+    private demoKey(): Uint8Array {
+        return Uint8Array.wrap(String.UTF8.encode('0123456789abcdef0123456789abcdef'));
+    }
+
+    /** The `Set-Cookie` string `clearCookie(name)` emits, for display. */
+    private clearString(name: string): string {
+        return new Cookie(name, '').path('/').maxAge(0).expires(0).serialize();
+    }
+
+    /** Flip the first character (tamper a sealed value while keeping it base64url). */
+    private flip(s: string): string {
+        if (s.length == 0) return 'A';
+        const c = s.charCodeAt(0);
+        return String.fromCharCode(c == 65 ? 66 : 65) + s.substring(1);
+    }
+
+    /** Read `?key=` (or `&key=`) from `path`, percent-decoded, or `fallback`. */
+    private queryValue(path: string, key: string, fallback: string): string {
+        const q = path.indexOf('?');
+        if (q < 0) return fallback;
+        const pairs = path.substring(q + 1).split('&');
+        const prefix = key + '=';
+        for (let i = 0; i < pairs.length; i++) {
+            if (pairs[i].indexOf(prefix) == 0) {
+                return Cookies.decodeValue(pairs[i].substring(prefix.length));
+            }
+        }
+        return fallback;
+    }
+
+    /** Parse a non-negative base-10 integer prefix of `s`. */
+    private toI32(s: string): i32 {
+        let r = 0;
+        for (let i = 0; i < s.length; i++) {
+            const c = s.charCodeAt(i);
+            if (c < 48 || c > 57) break;
+            r = r * 10 + (c - 48);
+        }
+        return r;
+    }
+
+    /** JSON string escaping for the demo's hand-built JSON (incl. all controls). */
+    private esc(s: string): string {
+        const hex = '0123456789abcdef';
+        let out = '';
+        for (let i = 0; i < s.length; i++) {
+            const c = s.charCodeAt(i);
+            if (c == 34) out += '\\"';
+            else if (c == 92) out += '\\\\';
+            else if (c == 10) out += '\\n';
+            else if (c == 13) out += '\\r';
+            else if (c == 9) out += '\\t';
+            else if (c < 0x20) out += '\\u00' + hex.charAt((c >> 4) & 0xf) + hex.charAt(c & 0xf);
+            else out += String.fromCharCode(c);
+        }
+        return out;
+    }
+}

package/examples/basic/server/core/store.ts

@@ -0,0 +1,31 @@
+// The demo's shared state, used by the routes and services.
+//
+// IMPORTANT - the server runs with a FRESH WebAssembly instance per request, so linear memory
+// (and any module-level state, like the `store` below) is reset on every request. It does NOT
+// persist across requests. We seed a few players at module init so the read routes always have
+// data; writes take effect only for the current request's response. For real persistence, call
+// out to a database or KV store from your handler.
+
+import { Player } from '../models/Player';
+
+/** Players by id, re-seeded on EVERY request (see the note above). */
+export const store = new Map<u64, Player>();
+
+let nextId: u64 = 1;
+
+/** The next fresh player id (module-local so callers cannot desync it). */
+export function allocId(): u64 {
+    return nextId++;
+}
+
+function seed(name: string, score: i64): void {
+    const p = new Player();
+    p.id = u256.fromU64(allocId());
+    p.name = name;
+    p.score = score;
+    store.set(p.id.toU64(), p);
+}
+
+seed('Ada', 120);
+seed('Linus', 95);
+seed('Grace', 140);

package/examples/basic/server/deco-main.ts

@@ -0,0 +1,18 @@
+import { Server } from 'toiljs/server/runtime';
+import { revertOnError } from 'toiljs/server/runtime/abort/abort';
+import { Request, Response, Rest, ToilHandler } from 'toiljs/server/runtime';
+import './DecoCache';
+
+class DecoHandler extends ToilHandler {
+    public handle(req: Request): Response {
+        const hit = Rest.dispatch(req);
+        if (hit != null) return hit;
+        return Response.notFound();
+    }
+}
+
+Server.handler = () => { return new DecoHandler(); };
+export * from 'toiljs/server/runtime/exports';
+export function abort(message: string, fileName: string, line: u32, column: u32): void {
+    revertOnError(message, fileName, line, column);
+}

package/examples/basic/server/main.ts

@@ -1,13 +1,24 @@
 import { Server } from 'toiljs/server/runtime';
 import { revertOnError } from 'toiljs/server/runtime/abort/abort';
-import { HelloHandler } from './HelloHandler';
+
+import { AppHandler } from './core/AppHandler';
+
+// Surface modules: @rest routes and @service/@remote RPC. `toiljs build` discovers every
+// decorated file under server/ on its own; importing them here keeps a direct `toilscript`
+// run (which only sees the toilconfig entries) building the exact same server.
+import './routes/Players';
+import './routes/Leaderboard';
+import './routes/Session';
+import './routes/PqDemo';
+import './services/Stats';
+import './services/remotes';
 
 // DO NOT TOUCH THIS.
 Server.handler = () => {
     // ONLY CHANGE THE HANDLER CLASS NAME.
     // DO NOT ADD CUSTOM LOGIC HERE.
 
-    return new HelloHandler();
+    return new AppHandler();
 };
 
 // VERY IMPORTANT

package/examples/basic/server/models/NewPlayer.ts

@@ -0,0 +1,5 @@
+/** Request body for `POST /players` - the fields a client supplies to create a player. */
+@data
+export class NewPlayer {
+    name: string = '';
+}

package/examples/basic/server/models/Player.ts

@@ -0,0 +1,8 @@
+/** A leaderboard player. The `u256` id shows native bignums riding the wire: it crosses
+ *  JSON as four 64-bit limbs and lands on the client as one `bigint`. */
+@data
+export class Player {
+    id: u256 = u256.Zero;
+    name: string = '';
+    score: i64 = 0;
+}

package/examples/basic/server/models/ScoreDelta.ts

@@ -0,0 +1,5 @@
+/** Request body for `POST /players/:id/score` - points to add to a player's score. */
+@data
+export class ScoreDelta {
+    points: i64 = 0;
+}

package/examples/basic/server/models/Standings.ts

@@ -0,0 +1,7 @@
+import { Player } from './Player';
+
+/** A leaderboard page. A `@data` wrapper so the `Player[]` round-trips through the codec. */
+@data
+export class Standings {
+    players: Player[] = [];
+}

package/examples/basic/server/routes/Auth.ts

@@ -0,0 +1,184 @@
+import { Method, Response, RouteContext } from 'toiljs/server/runtime';
+import { DataReader, DataWriter } from 'data';
+
+/**
+ * Post-quantum auth, illustrative. Shows how a tenant wires the no-import
+ * `AuthService` global into a challenge-response login. ML-DSA-44 keypairs are
+ * derived client-side from the password (Argon2id); the server only ever stores
+ * and verifies PUBLIC material.
+ *
+ * STORAGE IS THE APP'S, AND THIS EXAMPLE DOES NOT PROVIDE IT. A tenant's wasm
+ * memory is wiped after every request, so the account record and the login
+ * challenges CANNOT live in this module across the two round trips. A real
+ * deployment must back `Accounts` and `Challenges` with an external store, and
+ * the challenge "consume" MUST be a single atomic fetch-and-delete shared by
+ * all instances (Redis `GETDEL`, or SQL `DELETE ... RETURNING`) -- never a
+ * read-then-delete, or a sniffed signature replays across a race. The stubs
+ * below throw to make that explicit; swap them for your store + a host KV/db
+ * binding. The crypto and encoding (`AuthService`) are production-ready; the
+ * orchestration here is a template.
+ *
+ * Wire: every body/response is binary (`DataWriter`/`DataReader`), never JSON.
+ * The client half lives in `toiljs/client` (`Auth.register` / `Auth.login`).
+ */
+
+const AUD = 'toil-demo'; // this service's audience id (server config; never client-echoed)
+const MIN_MEM_KIB = 256 * 1024; // 256 MiB floor (KDF-params-as-credential)
+const MIN_ITERATIONS = 3;
+
+class AccountRecord {
+    username: string = '';
+    salt: Uint8Array = new Uint8Array(0);
+    publicKey: Uint8Array = new Uint8Array(0);
+    memKiB: u32 = 0;
+    iterations: u32 = 0;
+    parallelism: u32 = 0;
+}
+
+class ChallengeRecord {
+    cid: Uint8Array = new Uint8Array(0);
+    username: string = '';
+    nonce: Uint8Array = new Uint8Array(0);
+    iat: u64 = 0;
+    exp: u64 = 0;
+}
+
+// --- the storage the app MUST provide (external; these throw on purpose) -----
+namespace Accounts {
+    export function get(_username: string): AccountRecord | null {
+        throw new Error('wire Accounts to your store');
+    }
+    export function exists(_username: string): bool {
+        throw new Error('wire Accounts to your store');
+    }
+    export function put(_a: AccountRecord): void {
+        throw new Error('wire Accounts to your store');
+    }
+}
+namespace Challenges {
+    export function put(_c: ChallengeRecord): void {
+        throw new Error('wire Challenges to your store');
+    }
+    /** Atomic fetch-and-delete by cid (Redis GETDEL / SQL DELETE RETURNING). */
+    export function consume(_cid: Uint8Array): ChallengeRecord | null {
+        throw new Error('wire Challenges to an ATOMIC store');
+    }
+}
+
+function randomBytes(n: i32): Uint8Array {
+    const b = new Uint8Array(n);
+    crypto.getRandomValues(b);
+    return b;
+}
+
+function fail(): Response {
+    // One generic error on every failure path (anti-enumeration, anti-oracle).
+    return Response.text('auth: request failed\n', 401);
+}
+
+@rest('auth')
+class Auth {
+    /** POST /auth/register/start  body: str(username)
+     *  resp: u8(status=0) + u32(mem) u32(iters) u32(par) bytes(salt) */
+    @post('/register/start')
+    public registerStart(ctx: RouteContext): Response {
+        const username = new DataReader(ctx.request.body).readString();
+        if (Accounts.exists(username)) {
+            return new Response(200, new DataWriter().writeU8(1).toBytes().slice(0)); // taken
+        }
+        const salt = randomBytes(16);
+        const w = new DataWriter();
+        w.writeU8(0);
+        w.writeU32(<u32>MIN_MEM_KIB);
+        w.writeU32(<u32>MIN_ITERATIONS);
+        w.writeU32(1);
+        w.writeBytes(salt);
+        // NOTE: the salt must be persisted with the pending registration so
+        // registerFinish stores the same one; omitted here (no store).
+        return Response.bytes(w.toBytes());
+    }
+
+    /** POST /auth/register/finish  body: str(username) bytes(pk)  resp: u8(status) */
+    @post('/register/finish')
+    public registerFinish(ctx: RouteContext): Response {
+        const r = new DataReader(ctx.request.body);
+        const username = r.readString();
+        const pk = r.readBytes();
+        if (Accounts.exists(username) || pk.length != 1312) return fail(); // ML-DSA-44 pk
+        const a = new AccountRecord();
+        a.username = username;
+        a.publicKey = pk;
+        a.memKiB = <u32>MIN_MEM_KIB;
+        a.iterations = <u32>MIN_ITERATIONS;
+        a.parallelism = 1;
+        // a.salt = <the salt issued in registerStart>;
+        Accounts.put(a);
+        return Response.bytes(new DataWriter().writeU8(0).toBytes());
+    }
+
+    /** POST /auth/login/start  body: str(username)
+     *  resp: bytes(cid) str(aud) u32(mem) u32(iters) u32(par) bytes(salt) bytes(nonce) u64(iat) u64(exp) */
+    @post('/login/start')
+    public loginStart(ctx: RouteContext): Response {
+        const username = new DataReader(ctx.request.body).readString();
+        const acct = Accounts.get(username);
+
+        const cid = randomBytes(16);
+        const nonce = randomBytes(32);
+        const iat = <u64>(Date.now() / 1000);
+        const exp = iat + 120;
+
+        // Anti-enumeration: unknown user still gets a fully-formed challenge with
+        // a throwaway salt; the eventual verify just fails.
+        const salt = acct != null ? acct.salt : randomBytes(16);
+        const mem = acct != null ? acct.memKiB : <u32>MIN_MEM_KIB;
+        const iters = acct != null ? acct.iterations : <u32>MIN_ITERATIONS;
+        const par = acct != null ? acct.parallelism : 1;
+
+        if (acct != null) {
+            const c = new ChallengeRecord();
+            c.cid = cid;
+            c.username = username;
+            c.nonce = nonce;
+            c.iat = iat;
+            c.exp = exp;
+            Challenges.put(c);
+        }
+
+        const w = new DataWriter();
+        w.writeBytes(cid);
+        w.writeString(AUD);
+        w.writeU32(mem);
+        w.writeU32(iters);
+        w.writeU32(par);
+        w.writeBytes(salt);
+        w.writeBytes(nonce);
+        w.writeU64(iat);
+        w.writeU64(exp);
+        return Response.bytes(w.toBytes());
+    }
+
+    /** POST /auth/login/finish  body: bytes(cid) bytes(sig)  resp: u8(status) [+ bytes(session)] */
+    @post('/login/finish')
+    public loginFinish(ctx: RouteContext): Response {
+        const r = new DataReader(ctx.request.body);
+        const cid = r.readBytes();
+        const sig = r.readBytes();
+
+        // 1. CONSUME FIRST: atomic fetch-and-delete. Unknown/used/expired => fail.
+        const ch = Challenges.consume(cid);
+        if (ch == null) return fail();
+        const now = <u64>(Date.now() / 1000);
+        if (now >= ch.exp) return fail();
+
+        // 2. Rebuild the message from OUR stored values (never client-echoed),
+        //    load the account's public key, verify under the login context.
+        const acct = Accounts.get(ch.username);
+        if (acct == null) return fail();
+        const message = AuthService.buildLoginMessage(ch.username, AUD, cid, ch.nonce, ch.iat, ch.exp);
+        if (!AuthService.verifyLogin(acct.publicKey, message, sig)) return fail();
+
+        // 3. Success: mint a session (cookie / token). App-specific.
+        return Response.bytes(new DataWriter().writeU8(0).toBytes());
+    }
+}

package/examples/basic/server/routes/Leaderboard.ts

@@ -0,0 +1,20 @@
+import { store } from '../core/store';
+import { Player } from '../models/Player';
+import { Standings } from '../models/Standings';
+
+/**
+ * The leaderboard, mounted at `/leaderboard`. On the client:
+ *   const board = await Server.REST.leaderboard.top(); // typed Standings { players: Player[] }
+ */
+@rest('leaderboard')
+class Leaderboard {
+    /** `GET /leaderboard` - the seeded players, highest score first. */
+    @get('/')
+    public top(): Standings {
+        const board = new Standings();
+        const all = store.values();
+        for (let i = 0; i < all.length; i++) board.players.push(all[i]);
+        board.players.sort((a: Player, b: Player): i32 => (a.score < b.score ? 1 : a.score > b.score ? -1 : 0));
+        return board;
+    }
+}

package/examples/basic/server/routes/Players.ts

@@ -0,0 +1,53 @@
+import { Response, RouteContext } from 'toiljs/server/runtime';
+
+import { allocId, store } from '../core/store';
+import { NewPlayer } from '../models/NewPlayer';
+import { Player } from '../models/Player';
+import { ScoreDelta } from '../models/ScoreDelta';
+
+/**
+ * Players, mounted at `/players`. On the client:
+ *   await Server.REST.players.get({ params: { id } })
+ *   await Server.REST.players.create({ body: new NewPlayer('Bob') })
+ *   await Server.REST.players.addScore({ params: { id }, body: new ScoreDelta(10n) })
+ */
+@rest('players')
+class Players {
+    /** `GET /players/:id` - returns a `Response` for full control: a real 404 for a missing id,
+     *  a custom header, and the `@data` body serialized with `toJSON()`. (The toilscript editor
+     *  plugin types the compiler-injected `toJSON()`, so this is clean; return the `@data` type
+     *  directly, like the other routes, when you do not need that control.) */
+    @get('/:id')
+    public get(ctx: RouteContext): Response {
+        const id = u64.parse(ctx.param('id'));
+        if (!store.has(id)) return Response.notFound();
+        const p = store.get(id);
+
+        return Response.json(p.toJSON().toString()).setHeader('cache-control', 'no-store');
+    }
+
+    /** `POST /players` - build a player from the request body and return it with a fresh id.
+     *  Note: it is NOT saved (memory resets next request); persist to a real store to keep it. */
+    @post('/')
+    public create(input: NewPlayer): Player {
+        const p = new Player();
+        p.id = u256.fromU64(allocId());
+        p.name = input.name;
+        p.score = 0;
+        store.set(p.id.toU64(), p);
+
+        return p;
+    }
+
+    /** `POST /players/:id/score` - add `points` (from the body) to the seeded player named by
+     *  `:id` and return it. The change applies to this response only (memory resets next request). */
+    @post('/:id/score')
+    public addScore(input: ScoreDelta, ctx: RouteContext): Player {
+        const id = u64.parse(ctx.param('id'));
+        if (!store.has(id)) return new Player();
+        const p = store.get(id);
+        p.score += input.points;
+
+        return p;
+    }
+}