toiljs 0.0.33 → 0.0.34

package/server/runtime/response.ts

@@ -106,4 +106,60 @@ export class Response {
 
         return this;
     }
+
+    /**
+     * Mark this response cacheable at the toil edge and/or the browser.
+     *
+     * `edgeTtlMinutes` caches the response on the edge node (per-core,
+     * keyed by host + method + path + request body) for up to that many
+     * minutes -- the ONLY way a POST response is cached. `browserTtlSeconds`
+     * emits a `Cache-Control: max-age` for the client.
+     *
+     * Host-side safety, enforced no matter what you ask for: the edge TTL
+     * is clamped to 24h, only 2xx responses are edge-cached, a response
+     * carrying a `Set-Cookie` is never edge-cached, and an AUTHENTICATED
+     * request (one with a `Cookie` or `Authorization` header) is not
+     * edge-cached unless you pass `allowAuth = true`. Only mark a response
+     * cacheable when its body is a pure function of (host, path, body) --
+     * never per-user data keyed by a cookie/header that is not in the path
+     * or body, or one user's response could be served to another.
+     *
+     * Builder-style: returns `this`.
+     */
+    public cache(
+        edgeTtlMinutes: u16,
+        browserTtlSeconds: u32 = 0,
+        privateScope: bool = false,
+        allowAuth: bool = false,
+    ): Response {
+        let v = '';
+        if (edgeTtlMinutes > 0) {
+            v = 'edge=' + edgeTtlMinutes.toString();
+        }
+        if (browserTtlSeconds > 0) {
+            if (v.length > 0) v += '; ';
+            v += 'browser=' + browserTtlSeconds.toString();
+        }
+        if (privateScope) {
+            if (v.length > 0) v += '; ';
+            v += 'scope=private';
+        }
+        if (allowAuth) {
+            if (v.length > 0) v += '; ';
+            v += 'auth=1';
+        }
+        if (v.length > 0) {
+            this.setHeader('toil-cache-control', v);
+        }
+
+        return this;
+    }
+
+    /**
+     * Shorthand for {@link cache}: edge-cache this response for `minutes`
+     * minutes (no browser caching).
+     */
+    public cacheFor(minutes: u16): Response {
+        return this.cache(minutes);
+    }
 }

package/src/cli/create.ts

@@ -175,12 +175,10 @@ function scaffold(
         'toilconfig.json':
             JSON.stringify(
                 {
-                    // `toiljs build` compiles every server/*.ts so dropped-in @data/@rest files are
-                    // picked up; these entries are the fallback when running `toilscript` directly.
-                    entries:
-                        template === 'minimal'
-                            ? ['server/main.ts']
-                            : ['server/main.ts', 'server/api.ts'],
+                    // `toiljs build` compiles every decorated server file (recursively) so
+                    // dropped-in @data/@rest files are picked up; main.ts imports the surface
+                    // modules so a direct `toilscript` run builds the same server.
+                    entries: ['server/main.ts'],
                     targets: {
                         release: {
                             outFile: 'build/server/release.wasm',
@@ -261,12 +259,18 @@ function scaffold(
     return files;
 }
 
-/** A minimal but working server for the `minimal` template (the `app` template copies examples/basic/server). */
+/**
+ * A minimal but working server for the `minimal` template (the `app` template copies
+ * examples/basic/server). Same folder conventions as the full starter, just fewer files:
+ * the entry in main.ts, the handler under core/, and a README mapping where new
+ * routes/services/models go.
+ */
 function minimalServer(): Record<string, string> {
     return {
-        'server/HelloHandler.ts':
+        'server/core/AppHandler.ts':
             "import { ToilHandler, Request, Response, Method } from 'toiljs/server/runtime';\n\n" +
-            'export class HelloHandler extends ToilHandler {\n' +
+            '/** Every request enters here. Add `@rest` controllers under routes/ as you grow. */\n' +
+            'export class AppHandler extends ToilHandler {\n' +
             '    public handle(req: Request): Response {\n' +
             '        if (req.method != Method.GET && req.method != Method.HEAD) {\n' +
             "            return Response.empty(405).setHeader('allow', 'GET, HEAD');\n" +
@@ -285,15 +289,31 @@ function minimalServer(): Record<string, string> {
             '}\n',
         'server/main.ts':
             "import { Server } from 'toiljs/server/runtime';\n" +
-            "import { revertOnError } from 'toiljs/server/runtime/abort/abort';\n" +
-            "import { HelloHandler } from './HelloHandler';\n\n" +
+            "import { revertOnError } from 'toiljs/server/runtime/abort/abort';\n\n" +
+            "import { AppHandler } from './core/AppHandler';\n\n" +
+            '// As you add surface modules (@rest routes, @service/@remote RPC), import them here\n' +
+            '// so a direct `toilscript` run builds the same server `toiljs build` does, e.g.:\n' +
+            "//   import './routes/Players';\n\n" +
             '// Wire your handler here.\n' +
-            'Server.handler = () => new HelloHandler();\n\n' +
+            'Server.handler = () => new AppHandler();\n\n' +
             '// Required: re-export the WASM entry points and the abort hook.\n' +
             "export * from 'toiljs/server/runtime/exports';\n" +
             'export function abort(message: string, fileName: string, line: u32, column: u32): void {\n' +
             '    revertOnError(message, fileName, line, column);\n' +
             '}\n',
+        'server/README.md':
+            '# server/\n\n' +
+            'Your ToilScript backend, compiled to a single WebAssembly module. One folder per concern:\n\n' +
+            '| Folder | What lives here |\n' +
+            '| --- | --- |\n' +
+            '| `main.ts` | The entry point: wires the handler and imports the surface modules. |\n' +
+            '| `core/` | The request handler and shared app logic (state, helpers). |\n' +
+            '| `models/` | `@data` classes, the typed wire model shared by HTTP and RPC. One type per file. |\n' +
+            '| `routes/` | `@rest` controllers (HTTP). One controller per file, named after its class. |\n' +
+            '| `services/` | `@service` classes and free `@remote` functions (typed RPC). |\n' +
+            '| `scheduled/` | Reserved for scheduled tasks (not shipped yet). |\n\n' +
+            'New decorated files are picked up automatically by `toiljs build`/`dev`; also add an import\n' +
+            'in `main.ts` so a direct `toilscript` run builds the same server.\n',
     };
 }
 
@@ -586,7 +606,27 @@ export async function runCreate(opts: CreateOptions): Promise<void> {
     if (template === 'app') {
         // Copy the example client + server (the single starter source), set the <title>, then style.
         await fs.cp(appClientDir(), path.join(targetDir, 'client'), { recursive: true });
-        await fs.cp(appServerDir(), path.join(targetDir, 'server'), { recursive: true });
+        // Only the canonical starter layout ships; anything else sitting in the example's
+        // server/ (local experiments, scratch entries) stays out of scaffolded apps.
+        const serverAllow = new Set([
+            'main.ts',
+            'README.md',
+            'tsconfig.json',
+            'core',
+            'models',
+            'routes',
+            'services',
+            'scheduled',
+        ]);
+        const serverSrc = appServerDir();
+        await fs.cp(serverSrc, path.join(targetDir, 'server'), {
+            recursive: true,
+            filter: (src) => {
+                const rel = path.relative(serverSrc, src);
+                if (rel === '') return true;
+                return serverAllow.has(rel.split(path.sep)[0]);
+            },
+        });
         const indexHtml = path.join(targetDir, 'client', 'public', 'index.html');
         const html = await fs.readFile(indexHtml, 'utf8');
         await fs.writeFile(
@@ -628,5 +668,5 @@ export async function runCreate(opts: CreateOptions): Promise<void> {
     steps.push(`${accent('npm run build')} ${dim('build for production')}`);
     note(steps.map((l) => dim('  ') + l).join('\n'), 'Next steps');
 
-    outro(`Created ${accent(path.basename(name))}, happy building! ${dim('· v' + version())}`);
+    outro(`Created ${accent(path.basename(name))}, happy building! ${dim('(v' + version() + ')')}`);
 }

package/src/devserver/index.ts

@@ -25,6 +25,7 @@ import path from 'node:path';
 import { Server, type Request, type Response } from '@dacely/hyper-express';
 import pc from 'picocolors';
 
+import { applyCacheRule, lookupCache } from './cache.js';
 import { METHOD_CODES, type EnvelopeRequest } from './envelope.js';
 import { WasmServerModule } from './module.js';
 import { proxyToVite, wireWebsocketProxy, type ViteTarget } from './proxy.js';
@@ -210,10 +211,29 @@ export async function startDevServer(options: DevServerOptions): Promise<Running
 
         if (dispatchable && module.available) {
             const envelopeReq = await toEnvelopeRequest(request);
+            // Honor the tenant cache directive locally, same rules as the
+            // edge: serve an identical request from the per-process cache,
+            // else dispatch and apply/strip the directive on the response.
+            const cacheHost = request.headers.host ?? 'dev';
+            const hasAuth =
+                request.headers.cookie !== undefined || request.headers.authorization !== undefined;
+            const cached = lookupCache(cacheHost, request.method, request.url, envelopeReq.body);
+            if (cached !== null) {
+                sendWasmResponse(response, root, cached);
+                return;
+            }
             try {
                 const result = module.dispatch(envelopeReq);
                 if (!result.unhandled) {
-                    sendWasmResponse(response, root, result);
+                    const finalized = applyCacheRule(
+                        cacheHost,
+                        request.method,
+                        request.url,
+                        envelopeReq.body,
+                        hasAuth,
+                        result,
+                    );
+                    sendWasmResponse(response, root, finalized);
                     return;
                 }
             } catch (e) {

package/test/devserver.test.ts

@@ -155,10 +155,10 @@ describe.skipIf(!fs.existsSync(EXAMPLE_WASM))('dispatch into the example server
         });
 
     it('serves a plain route', () => {
-        const r = get(load(), '/');
+        const r = get(load(), '/json');
         expect(r.status).toBe(200);
         expect(r.unhandled).toBe(false);
-        expect(Buffer.from(r.body).toString()).toBe('hello from toiljs\n');
+        expect(Buffer.from(r.body).toString()).toBe('{"hello":"toiljs"}\n');
     });
 
     it('serves a @rest route with its content-type', () => {
@@ -186,8 +186,10 @@ describe.skipIf(!fs.existsSync(EXAMPLE_WASM))('dispatch into the example server
             body: new TextEncoder().encode('{"name":"ada"}'),
         });
         expect(r.unhandled).toBe(false);
-        expect(r.status).toBeGreaterThanOrEqual(200);
-        expect(r.status).toBeLessThan(500);
+        expect(r.status).toBe(200);
+        // u256 id and i64 score cross JSON as decimal strings, exact at any size (3 seeded
+        // players, so the new player's id is 4).
+        expect(Buffer.from(r.body).toString()).toBe('{"id":"4","name":"ada","score":"0"}');
     });
 
     it('keeps requests isolated across instances (fresh state per dispatch)', () => {

package/test/fixtures/bignum-wire/spec.ts

@@ -0,0 +1,27 @@
+// Fixture for the generated-client JSON wire-format test (test/rpc-bignum-wire.test.ts).
+// Compiled by the installed toilscript with --rpcModule, then the generated TS client is
+// imported and exercised. Covers every JSON bignum width plus a nested @data so the
+// recursive toJSONValue path is hit.
+
+@data
+class Wallet {
+    u: u64 = 0;
+    i: i64 = 0;
+    a: u128 = u128.Zero;
+    b: i128 = i128.Zero;
+    c: u256 = u256.Zero;
+    d: i256 = i256.Zero;
+    label: string = '';
+}
+
+@data
+class Account {
+    main: Wallet = new Wallet();
+    ids: u256[] = [];
+}
+
+// A free @remote so buildServerModule emits a surface (it returns null otherwise).
+@remote
+function touch(n: i32): i32 {
+    return n;
+}

package/test/rpc-bignum-wire.test.ts

@@ -0,0 +1,164 @@
+/**
+ * Regression test for the bignum JSON wire format. 64-bit-and-up integers
+ * (u64/i64/u128/i128/u256/i256) must cross JSON as DECIMAL STRINGS, not number tokens
+ * or limb arrays: JSON numbers ride through a browser client's JSON.parse as IEEE
+ * doubles, which silently corrupt any integer past 2^53.
+ *
+ * Compiles test/fixtures/bignum-wire/spec.ts with the installed toilscript (so it
+ * exercises the published compiler + generated client, not a hand-written stub), then
+ * imports the generated TS client and asserts the wire shape both directions, including
+ * values far above 2^53 and the legacy limb-array shape older servers emitted.
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { beforeAll, describe, expect, it } from 'vitest';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const spec = path.join(here, 'fixtures', 'bignum-wire', 'spec.ts');
+// The generated module imports DataWriter/DataReader from this specifier.
+const codec = path.join(here, '..', 'src', 'io', 'codec.ts');
+
+/** Resolves the installed toilscript CLI entry (no PATH / .bin assumptions). */
+function toilscriptBin(): string {
+    const pkgPath = require.resolve('toilscript/package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')) as { bin?: Record<string, string> };
+    const binRel = pkg.bin?.toilscript;
+    if (!binRel) throw new Error('toilscript declares no bin');
+    return path.join(path.dirname(pkgPath), binRel);
+}
+
+interface Wallet {
+    u: bigint;
+    i: bigint;
+    a: bigint;
+    b: bigint;
+    c: bigint;
+    d: bigint;
+    label: string;
+    toJSONValue(): Record<string, unknown>;
+}
+interface WalletStatic {
+    new (): Wallet;
+    fromJSONValue(v: unknown): Wallet;
+}
+interface AccountStatic {
+    new (): { main: Wallet; ids: bigint[]; toJSONValue(): Record<string, unknown> };
+    fromJSONValue(v: unknown): { main: Wallet; ids: bigint[] };
+}
+
+let Wallet: WalletStatic;
+let Account: AccountStatic;
+let tmp: string;
+
+beforeAll(async () => {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'bignum-wire-'));
+    fs.writeFileSync(path.join(tmp, 'package.json'), '{ "type": "module" }\n');
+    // vitest transforms the imported .ts through Vite/oxc, which walks up for a tsconfig.
+    fs.writeFileSync(
+        path.join(tmp, 'tsconfig.json'),
+        JSON.stringify({ compilerOptions: { target: 'esnext', module: 'esnext' } }),
+    );
+    const mod = path.join(tmp, 'server.ts');
+    const wasm = path.join(tmp, 'spec.wasm');
+    const res = spawnSync(
+        process.execPath,
+        [
+            toilscriptBin(),
+            spec,
+            '-o',
+            wasm,
+            '--runtime',
+            'stub',
+            '--initialMemory',
+            '32',
+            '--rpcModule',
+            mod,
+            '--rpcRuntime',
+            codec,
+        ],
+        { encoding: 'utf8' },
+    );
+    if (res.status !== 0) throw new Error('toilscript compile failed:\n' + res.stderr);
+    const gen = (await import(pathToFileURL(mod).href)) as {
+        Wallet: WalletStatic;
+        Account: AccountStatic;
+    };
+    Wallet = gen.Wallet;
+    Account = gen.Account;
+});
+
+// A few representative bignum types; `huge` is well past Number.MAX_SAFE_INTEGER.
+const huge = '123456789012345678901234567890';
+const u128Max = '340282366920938463463374607431768211455';
+const i64Min = '-9223372036854775808';
+
+describe('generated client bignum JSON wire format', () => {
+    it('serializes every 64-bit-and-up integer as a decimal string', () => {
+        const w = new Wallet();
+        w.u = BigInt(huge.slice(0, 19)); // fits u64
+        w.i = BigInt(i64Min);
+        w.a = BigInt(u128Max);
+        w.b = -123n;
+        w.c = BigInt(huge);
+        w.d = -1n;
+        w.label = 'x';
+        const json = w.toJSONValue();
+        // Each bignum field is a string, never a number or an array.
+        for (const k of ['u', 'i', 'a', 'b', 'c', 'd'] as const) {
+            expect(typeof json[k], `field ${k}`).toBe('string');
+        }
+        expect(json.a).toBe(u128Max);
+        expect(json.c).toBe(huge);
+        expect(json.i).toBe(i64Min);
+        expect(json.label).toBe('x');
+    });
+
+    it('revives a decimal string past 2^53 into an exact bigint', () => {
+        const w = Wallet.fromJSONValue({
+            u: '0',
+            i: i64Min,
+            a: u128Max,
+            b: '-123',
+            c: huge,
+            d: '-1',
+            label: 'y',
+        });
+        expect(w.c).toBe(BigInt(huge));
+        expect(w.a).toBe(BigInt(u128Max));
+        expect(w.i).toBe(BigInt(i64Min));
+        expect(w.d).toBe(-1n);
+    });
+
+    it('round-trips a value through send then revive without loss', () => {
+        const w = new Wallet();
+        w.c = BigInt(huge);
+        w.d = BigInt('-' + huge);
+        const back = Wallet.fromJSONValue(JSON.parse(JSON.stringify(w.toJSONValue())));
+        expect(back.c).toBe(BigInt(huge));
+        expect(back.d).toBe(BigInt('-' + huge));
+    });
+
+    it('still revives the legacy little-endian limb-array shape (back-compat)', () => {
+        // u256 [5,0,4,0] little-endian = 5 + 4*2^128.
+        const w = Wallet.fromJSONValue({ c: [5, 0, 4, 0], a: [9, 1] });
+        expect(w.c).toBe(2n ** 130n + 5n);
+        expect(w.a).toBe(2n ** 64n + 9n);
+    });
+
+    it('recurses into nested @data and arrays of bignums', () => {
+        const a = new Account();
+        a.main.c = BigInt(huge);
+        a.ids = [1n, BigInt(huge)];
+        const json = a.toJSONValue();
+        const main = json.main as Record<string, unknown>;
+        expect(main.c).toBe(huge);
+        expect(json.ids).toEqual(['1', huge]);
+        const back = Account.fromJSONValue(JSON.parse(JSON.stringify(json)));
+        expect(back.main.c).toBe(BigInt(huge));
+        expect(back.ids).toEqual([1n, BigInt(huge)]);
+    });
+});

package/examples/basic/server/api.ts

@@ -1,137 +0,0 @@
-// A small REST demo: a players list + a leaderboard.
-//
-// 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; the write routes (create / addScore) take effect only for the current request's response.
-// For real persistence, call out to a database or KV store from your handler.
-//
-// `@data` types are the wire model (shared by HTTP and RPC). `@rest` controllers expose HTTP
-// routes; `@service`/`@remote` expose typed RPC. Building the server (toilscript --rpcModule)
-// regenerates the typed client into shared/server.ts:
-//   @rest    -> Server.REST.<controller>.<route>(args)  (a working fetch client)
-//   @service -> Server.<service>.<method>()             (RPC, transport TODO)
-
-import { Response, RouteContext } from 'toiljs/server/runtime';
-
-/** A leaderboard player. */
-@data
-class Player {
-    id: u64 = 0;
-    name: string = '';
-    score: i64 = 0;
-}
-
-/** Request body for `POST /players` - the fields a client supplies to create a player. */
-@data
-class NewPlayer {
-    name: string = '';
-}
-
-/** Request body for `POST /players/:id/score` - points to add to a player's score. */
-@data
-class ScoreDelta {
-    points: i64 = 0;
-}
-
-/** A leaderboard page. A `@data` wrapper so the `Player[]` round-trips through the codec. */
-@data
-class Standings {
-    players: Player[] = [];
-}
-
-// Re-seeded on EVERY request - module memory does not persist across requests (see the note at
-// the top of the file). Swap this for a database/KV to keep data between requests.
-const store = new Map<u64, Player>();
-let nextId: u64 = 1;
-
-function seed(name: string, score: i64): void {
-    const p = new Player();
-    p.id = nextId++;
-    p.name = name;
-    p.score = score;
-    store.set(p.id, p);
-}
-seed('Ada', 120);
-seed('Linus', 95);
-seed('Grace', 140);
-
-/**
- * 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 = nextId++;
-        p.name = input.name;
-        p.score = 0;
-        store.set(p.id, 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;
-    }
-}
-
-/**
- * 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;
-    }
-}
-
-/** Typed RPC service (transport still a TODO): reached as `Server.stats.playerCount()` on the client. */
-@service
-class Stats {
-    /** Number of seeded players (the RPC transport is a TODO, so this throws on the client for now). */
-    @remote
-    public playerCount(): i32 {
-        return store.size;
-    }
-}
-
-/** A free `@remote` function: `Server.ping(n)` on the client. */
-@remote
-function ping(n: i32): i32 {
-    return n + 1;
-}