toiljs 0.0.66 → 0.0.68

package/build/devserver/stream/manager.js

@@ -0,0 +1,103 @@
+import fs from 'node:fs';
+import { DevStreamBox } from './index.js';
+export const STREAM_REJECTED = 0x0208;
+export const STREAM_HOOK_TRAPPED = 0x0200;
+export class StreamDevHost {
+    streamWasmPath;
+    bytes = null;
+    loadedMtimeMs = -1;
+    conns = new Map();
+    nextStreamId = 1n;
+    constructor(streamWasmPath) {
+        this.streamWasmPath = streamWasmPath;
+    }
+    get activeConnections() {
+        return this.conns.size;
+    }
+    has(connId) {
+        return this.conns.has(connId);
+    }
+    acceptUpgrade(connId, authority, path) {
+        if (this.conns.has(connId))
+            throw new Error(`stream connection '${connId}' is already open`);
+        this.refresh();
+        if (!this.bytes)
+            return { kind: 'rejected', code: STREAM_REJECTED };
+        let box;
+        try {
+            box = DevStreamBox.load(this.bytes);
+        }
+        catch {
+            return { kind: 'rejected', code: STREAM_REJECTED };
+        }
+        const streamId = this.allocStreamId();
+        let outcome;
+        try {
+            outcome = box.onConnect(streamId, authority, path);
+        }
+        catch {
+            return { kind: 'rejected', code: STREAM_HOOK_TRAPPED };
+        }
+        if (outcome.kind === 'reject')
+            return { kind: 'rejected', code: outcome.code };
+        this.conns.set(connId, { box, streamId });
+        return { kind: 'accepted', streamId };
+    }
+    dispatch(connId, inbound) {
+        const conn = this.conns.get(connId);
+        if (!conn)
+            return { kind: 'noConnection' };
+        try {
+            const out = conn.box.onMessage(conn.streamId, inbound);
+            if (out.kind === 'reply')
+                return { kind: 'reply', frames: out.frames };
+            return { kind: 'close', code: out.code };
+        }
+        catch {
+            this.conns.delete(connId);
+            return { kind: 'close', code: STREAM_HOOK_TRAPPED };
+        }
+    }
+    close(connId) {
+        const conn = this.conns.get(connId);
+        if (!conn)
+            return;
+        try {
+            conn.box.onClose(conn.streamId);
+        }
+        catch {
+        }
+        this.conns.delete(connId);
+    }
+    disconnect(connId) {
+        const conn = this.conns.get(connId);
+        if (!conn)
+            return;
+        try {
+            conn.box.onDisconnect(conn.streamId);
+        }
+        catch {
+        }
+        this.conns.delete(connId);
+    }
+    refresh() {
+        let mtimeMs;
+        try {
+            mtimeMs = fs.statSync(this.streamWasmPath).mtimeMs;
+        }
+        catch {
+            this.bytes = null;
+            this.loadedMtimeMs = -1;
+            return;
+        }
+        if (mtimeMs === this.loadedMtimeMs && this.bytes)
+            return;
+        this.bytes = fs.readFileSync(this.streamWasmPath);
+        this.loadedMtimeMs = mtimeMs;
+    }
+    allocStreamId() {
+        const id = this.nextStreamId;
+        this.nextStreamId = id + 1n;
+        return id;
+    }
+}

package/build/devserver/stream/router.d.ts

@@ -0,0 +1,25 @@
+import { type StreamDef } from './catalog.js';
+export interface StreamWs {
+    send(data: Buffer, isBinary: boolean): void;
+    close(code: number): void;
+    on(event: 'message', cb: (message: Buffer, isBinary: boolean) => void): void;
+    on(event: 'close', cb: () => void): void;
+}
+export interface StreamUpgradeContext {
+    readonly kind: 'stream';
+    readonly route: string;
+    readonly url: string;
+    readonly authority: string;
+}
+export declare class StreamRouter {
+    private readonly streamWasmPath;
+    private catalog;
+    private catalogMtimeMs;
+    private readonly host;
+    private connSeq;
+    constructor(streamWasmPath: string);
+    get activeConnections(): number;
+    matchRoute(path: string): StreamDef | null;
+    onUpgrade(ws: StreamWs, ctx: StreamUpgradeContext): void;
+    private refreshCatalog;
+}

package/build/devserver/stream/router.js

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import { matchStreamRoute, parseStreamCatalog, } from './catalog.js';
+import { StreamDevHost } from './manager.js';
+import { StreamWsSession } from './ws.js';
+export class StreamRouter {
+    streamWasmPath;
+    catalog = new Map();
+    catalogMtimeMs = -1;
+    host;
+    connSeq = 0;
+    constructor(streamWasmPath) {
+        this.streamWasmPath = streamWasmPath;
+        this.host = new StreamDevHost(streamWasmPath);
+        this.refreshCatalog();
+    }
+    get activeConnections() {
+        return this.host.activeConnections;
+    }
+    matchRoute(path) {
+        this.refreshCatalog();
+        return matchStreamRoute(this.catalog, path);
+    }
+    onUpgrade(ws, ctx) {
+        const connId = `s${String(++this.connSeq)}`;
+        const q = ctx.url.indexOf('?');
+        const path = q >= 0 ? ctx.url.slice(0, q) : ctx.url;
+        const session = new StreamWsSession(this.host, connId, ctx.authority, path, {
+            send: (frame) => {
+                ws.send(frame, true);
+            },
+            close: (code) => {
+                ws.close(code);
+            },
+        });
+        if (!session.onOpen())
+            return;
+        ws.on('message', (message) => {
+            session.onMessage(message);
+        });
+        ws.on('close', () => {
+            session.onClose();
+        });
+    }
+    refreshCatalog() {
+        let mtimeMs;
+        try {
+            mtimeMs = fs.statSync(this.streamWasmPath).mtimeMs;
+        }
+        catch {
+            this.catalog = new Map();
+            this.catalogMtimeMs = -1;
+            return;
+        }
+        if (mtimeMs === this.catalogMtimeMs && this.catalog.size > 0)
+            return;
+        try {
+            this.catalog = parseStreamCatalog(fs.readFileSync(this.streamWasmPath));
+        }
+        catch {
+            this.catalog = new Map();
+        }
+        this.catalogMtimeMs = mtimeMs;
+    }
+}

package/build/devserver/stream/wire.d.ts

@@ -0,0 +1,5 @@
+import { type Server } from '@dacely/hyper-express';
+import { type ViteTarget } from '../http/proxy.js';
+import { type StreamRouter } from './router.js';
+export declare function streamEmulationEnabled(nodeMode: string): boolean;
+export declare function wireStreams(app: Server, vite: ViteTarget, router: StreamRouter): void;

package/build/devserver/stream/wire.js

@@ -0,0 +1,33 @@
+import { pipeToVite } from '../http/proxy.js';
+export function streamEmulationEnabled(nodeMode) {
+    return nodeMode === 'regional' || nodeMode === 'continental' || nodeMode === 'all';
+}
+export function wireStreams(app, vite, router) {
+    app.upgrade('/*', (request, response) => {
+        const def = router.matchRoute(request.path);
+        if (def !== null) {
+            response.upgrade({
+                kind: 'stream',
+                route: def.route,
+                url: request.url,
+                authority: request.headers['host'] ?? '',
+            });
+        }
+        else {
+            response.upgrade({
+                kind: 'vite',
+                url: request.url,
+                protocol: request.headers['sec-websocket-protocol'] ?? '',
+            });
+        }
+    });
+    app.ws('/*', { message_type: 'Buffer', idle_timeout: 0, max_payload_length: 16 * 1024 * 1024 }, (ws) => {
+        const ctx = ws.context;
+        if (ctx.kind === 'stream') {
+            router.onUpgrade(ws, ws.context);
+        }
+        else {
+            pipeToVite(ws, vite, ws.context);
+        }
+    });
+}

package/build/devserver/stream/ws.d.ts

@@ -0,0 +1,18 @@
+import type { StreamDevHost } from './manager.js';
+export interface StreamWsTransport {
+    send(frame: Buffer): void;
+    close(code: number): void;
+}
+export declare class StreamWsSession {
+    private readonly host;
+    private readonly connId;
+    private readonly authority;
+    private readonly path;
+    private readonly transport;
+    private open;
+    constructor(host: StreamDevHost, connId: string, authority: string, path: string, transport: StreamWsTransport);
+    get isOpen(): boolean;
+    onOpen(): boolean;
+    onMessage(inbound: Buffer): void;
+    onClose(): void;
+}

package/build/devserver/stream/ws.js

@@ -0,0 +1,46 @@
+export class StreamWsSession {
+    host;
+    connId;
+    authority;
+    path;
+    transport;
+    open = false;
+    constructor(host, connId, authority, path, transport) {
+        this.host = host;
+        this.connId = connId;
+        this.authority = authority;
+        this.path = path;
+        this.transport = transport;
+    }
+    get isOpen() {
+        return this.open;
+    }
+    onOpen() {
+        const up = this.host.acceptUpgrade(this.connId, this.authority, this.path);
+        if (up.kind === 'rejected') {
+            this.transport.close(up.code);
+            return false;
+        }
+        this.open = true;
+        return true;
+    }
+    onMessage(inbound) {
+        if (!this.open)
+            return;
+        const r = this.host.dispatch(this.connId, inbound);
+        if (r.kind === 'reply') {
+            for (const frame of r.frames)
+                this.transport.send(frame);
+        }
+        else if (r.kind === 'close') {
+            this.open = false;
+            this.transport.close(r.code);
+        }
+    }
+    onClose() {
+        if (!this.open && !this.host.has(this.connId))
+            return;
+        this.open = false;
+        this.host.close(this.connId);
+    }
+}

package/build/devserver/wasm/surface.d.ts

@@ -15,4 +15,4 @@ export interface Surface {
     readonly dataCoherenceHash: number;
     readonly pairCoherenceHash: number;
 }
-export declare function parseSurface(wasm: Buffer): Surface | 'absent' | 'invalid';
+export declare function parseSurface(wasm: Buffer): Surface | 'invalid';

package/build/devserver/wasm/surface.js

@@ -9,7 +9,7 @@ export function parseSurface(wasm) {
         return 'invalid';
     }
     if (sec === null)
-        return 'absent';
+        return 'invalid';
     const r = new DataReader(sec);
     r.readU16();
     const targetMode = r.readU8() === 1 ? 'cold' : 'hot';

package/docs/cli.md

@@ -8,7 +8,9 @@
 - `toiljs build`, production build. With a `toilconfig.json` it builds the server (toilscript,
   regenerating `shared/server.ts`) first, then the client → `build/client`. `--server` builds
   only the server. Every `server/` file declaring a surface (`@data`/`@rest`/...) is compiled.
-- `toiljs start`, self-host the built app (hyper-express) with a `/_toil` WebSocket channel.
+- `toiljs start`, self-host the built app with production hyper-express/uWS static workers,
+  SSR/wasm dispatch, daemon support, and a `/_toil` WebSocket channel. Use `--threads <n>`
+  (or `server.threads`) to set the worker count; `1` disables the pool.
 - `toiljs configure`, toggle styling features on an existing project (see [styling.md](./styling.md)).
 - `toiljs doctor`, diagnose project setup (`--json` for CI). `--fix` auto-wires the typed-RPC
   setup (build scripts, tsconfig `shared` + alias, `.gitignore`, toilscript version, and the

package/docs/getting-started.md

@@ -95,13 +95,13 @@ store reached through a host binding.
 
 The `toiljs` CLI drives both halves:
 
-| Command | What it does |
-| --- | --- |
-| `toiljs create [name]` | Scaffold a new app (templates, styling, options). |
-| `toiljs dev` | Dev server with hot reload: watches `server/`, rebuilds the wasm via toilscript, regenerates `shared/server.ts`, and runs Vite for the client. Flags: `--root <dir>`, `--port <n>`, `--host`. |
-| `toiljs build` | Production build: server wasm first (so `shared/server.ts` is fresh), then the Vite client + static prerender. Flags: `--root <dir>`, `--server` (server only). |
-| `toiljs start` | Self-host a built app. Flags: `--root`, `--port`, `--host`. |
-| `toiljs doctor` | Diagnose setup/deps (`--json`, `--fix`). |
+| Command                | What it does                                                                                                                                                                                  |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `toiljs create [name]` | Scaffold a new app (templates, styling, options).                                                                                                                                             |
+| `toiljs dev`           | Dev server with hot reload: watches `server/`, rebuilds the wasm via toilscript, regenerates `shared/server.ts`, and runs Vite for the client. Flags: `--root <dir>`, `--port <n>`, `--host`. |
+| `toiljs build`         | Production build: server wasm first (so `shared/server.ts` is fresh), then the Vite client + static prerender. Flags: `--root <dir>`, `--server` (server only).                               |
+| `toiljs start`         | Self-host a built app with production uWS/static workers, no Vite. Flags: `--root`, `--port`, `--host`, `--threads`.                                                                          |
+| `toiljs doctor`        | Diagnose setup/deps (`--json`, `--fix`).                                                                                                                                                      |
 
 In dev, requests whose method matches a dispatchable verb go into the wasm
 first; if the guest reports "no route matched" (the `x-toil-unhandled` marker)

package/docs/tiers.md

@@ -8,11 +8,11 @@ tier purely by adding its entry file and surface decorator; nothing else changes
 
 ## The tiers
 
-| Entry (`server/`) | Surface | Artifact | Tier | Lifetime / placement |
-| --- | --- | --- | --- | --- |
-| `main.ts` | `@rest` / `@service` / `@remote` | `build/server/release.wasm` | **L1** request | A fresh handler per request, anywhere on the edge. |
-| `main.stream.ts` | `@stream` | `build/server/release-stream.wasm` | **L2/L3** stream | One resident box per connection, pinned to a worker via QUIC connection-id steering; its state survives every event. See [Streams](./streams.md). |
-| `main.daemon.ts` | `@daemon` / `@scheduled` | `build/server/release-cold.wasm` | **L4** daemon | Exactly one leader-elected box per domain (warm standby, at-most-once failover) firing `@scheduled` tasks. See [Daemon](./daemon.md). |
+| Entry (`server/`) | Surface                          | Artifact                           | Tier             | Lifetime / placement                                                                                                                              |
+| ----------------- | -------------------------------- | ---------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `main.ts`         | `@rest` / `@service` / `@remote` | `build/server/release.wasm`        | **L1** request   | A fresh handler per request, anywhere on the edge.                                                                                                |
+| `main.stream.ts`  | `@stream`                        | `build/server/release-stream.wasm` | **L2/L3** stream | One resident box per connection, pinned to a worker via QUIC connection-id steering; its state survives every event. See [Streams](./streams.md). |
+| `main.daemon.ts`  | `@daemon` / `@scheduled`         | `build/server/release-cold.wasm`   | **L4** daemon    | Exactly one leader-elected box per domain (warm standby, at-most-once failover) firing `@scheduled` tasks. See [Daemon](./daemon.md).             |
 
 The three tiers differ in how long a box lives and how many of it exist:
 
@@ -79,7 +79,7 @@ build/server/release-cold.wasm     # L4 daemon      (exports: daemon_start, sche
 
 ## Single-artifact default
 
-A project with no `@stream` and no `@daemon` surface keeps the legacy
+A project with no `@stream` and no `@daemon` surface keeps the default
 single-artifact build - just `build/server/release.wasm`. The stream and daemon
 tiers are opt-in: add `main.stream.ts` (and a `@stream` class) to get
 `release-stream.wasm`, add `main.daemon.ts` (and a `@daemon` class) to get
@@ -102,9 +102,15 @@ tiers are opt-in: add `main.stream.ts` (and a `@stream` class) to get
 class Echo {
     private count: i32 = 0;
 
-    @connect onConnect(): void { this.count = 0; }
-    @message onMessage(): void { this.count = this.count + 1; }
-    @close   onClose(): void { /* box torn down after this hook */ }
+    @connect onConnect(): void {
+        this.count = 0;
+    }
+    @message onMessage(): void {
+        this.count = this.count + 1;
+    }
+    @close onClose(): void {
+        /* box torn down after this hook */
+    }
 }
 ```
 

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

@@ -13,6 +13,12 @@ import { NewMessage } from '../models/NewMessage';
  *
  *   await Server.REST.guestbook.sign({ body: new NewMessage('Ada', 'hi!') });
  *   const book = await Server.REST.guestbook.list(); // { total, entries: [...] }
+ *
+ * Reading the newest entries is a SCAN (`events.latest`), which is barred in a
+ * request handler (a `@get` runs as a Query, a `@post` as an Action) because a
+ * scan can fan out across unbounded rows. So a `@derive` does the scan off the
+ * request path and `publish`es a materialized `GuestbookView`; the GET then
+ * serves that view with a single non-scan `view.get`.
  */
 
 // The guestbook is one global stream; a single fixed key addresses it.
@@ -28,33 +34,52 @@ class GuestKey {
 class GuestbookDb {
     @collection static entries: Events<GuestKey, GuestEntry>;
     @collection static totals: Counter<GuestKey>;
-}
+    // The materialized snapshot the GET serves: total + newest entries.
+    @collection static book: View<GuestKey, GuestbookView>;
 
-/** The current total + the 10 newest entries. */
-function snapshot(): GuestbookView {
-    const key = new GuestKey('main');
-    const view = new GuestbookView();
-    view.total = GuestbookDb.totals.get(key);
-    view.entries = GuestbookDb.entries.latest(key, 10);
-    return view;
+    /**
+     * Recompute the materialized view from the source of truth (the event log +
+     * the counter). The runtime runs this under FunctionKind=Derive after a
+     * signature is appended (and rebuilds it when a box first loads), so the
+     * scan (`events.latest`) and the `view.publish` - both barred in a request
+     * handler - are allowed here. This is also where `GuestEntry`'s `@migrate`
+     * fires: `events.latest` decodes each stored event at ITS schema version, so
+     * an old pre-`at` entry is migrated as the view is rebuilt.
+     */
+    @derive
+    recompute(): void {
+        const key = new GuestKey('main');
+        const view = new GuestbookView();
+        view.total = GuestbookDb.totals.get(key);
+        view.entries = GuestbookDb.entries.latest(key, 10);
+        GuestbookDb.book.publish(key, view);
+    }
 }
 
 @rest('guestbook')
 class Guestbook {
-    /** `GET /guestbook` - the running total + the most recent signatures. */
+    /** `GET /guestbook` - the running total + the most recent signatures, served
+     *  from the materialized view (a non-scan `view.get`). */
     @get('/')
     public list(): GuestbookView {
-        return snapshot();
+        const key = new GuestKey('main');
+        const view = GuestbookDb.book.get(key);
+        if (view == null) return new GuestbookView();
+        return view;
     }
 
-    /** `POST /guestbook` - append a signature (PERSISTED) and return the
-     *  updated book. Sign twice and the total keeps climbing across requests. */
+    /** `POST /guestbook` - append a signature (PERSISTED) and acknowledge with
+     *  the new running total. The entries list is served by the GET above from
+     *  the view the `@derive` republishes right after this action. Sign twice
+     *  and the total keeps climbing across requests. */
     @post('/')
     public sign(input: NewMessage): GuestbookView {
         const key = new GuestKey('main');
         const at = <u64>(Date.now() / 1000);
         GuestbookDb.entries.append(key, new GuestEntry(input.author, input.message, at));
         GuestbookDb.totals.add(key, 1);
-        return snapshot();
+        const view = new GuestbookView();
+        view.total = GuestbookDb.totals.get(key); // Counter get: non-scan, action-legal
+        return view;
     }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "toiljs",
     "type": "module",
-    "version": "0.0.66",
+    "version": "0.0.68",
     "author": "Dacely",
     "description": "The modern React framework: a file-based React frontend and a ToilScript-compiled WebAssembly backend.",
     "repository": {
@@ -134,7 +134,7 @@
         "nodemailer": "^9.0.1",
         "picocolors": "^1.1.1",
         "sharp": "^0.35.2",
-        "toilscript": "^0.1.41",
+        "toilscript": "^0.1.43",
         "typescript-eslint": "^8.62.0",
         "vite": "^8.1.0",
         "vite-imagetools": "^10.0.1",

package/src/cli/index.ts

@@ -19,6 +19,7 @@ interface Flags {
     root?: string;
     port?: number;
     host?: string;
+    threads?: number;
     name?: string;
     template?: Template;
     preprocessor?: Preprocessor;
@@ -51,6 +52,12 @@ function parseArgs(argv: string[]): Flags {
             case '--host':
                 flags.host = argv[++i];
                 break;
+            case '--threads':
+            case '--workers': {
+                const threads = Number(argv[++i]);
+                if (!Number.isNaN(threads)) flags.threads = threads;
+                break;
+            }
             case '--template':
             case '-t': {
                 const t = argv[++i];
@@ -138,6 +145,7 @@ function printHelp(): void {
             bold('Options'),
             cmd('--root <dir>', 'project root (default: current directory)'),
             cmd('--port <n>', 'dev server port'),
+            cmd('--threads <n>', 'start: production HTTP worker count'),
             cmd('-t, --template', 'create: app | minimal'),
             cmd('--style <name>', 'create/configure: css | sass | less | stylus'),
             cmd('--tailwind', 'create/configure: enable Tailwind (--no-tailwind to remove)'),
@@ -226,7 +234,12 @@ async function main(): Promise<void> {
         case 'start': {
             banner();
             process.stdout.write(dim('  self-hosting the built app…') + '\n\n');
-            const server = await start({ root: flags.root, port: flags.port, host: flags.host });
+            const server = await start({
+                root: flags.root,
+                port: flags.port,
+                host: flags.host,
+                threads: flags.threads,
+            });
             process.stdout.write(
                 accent('  ➜ ') +
                     bold(`http://localhost:${String(server.port)}`) +

package/src/client/index.ts

@@ -79,6 +79,8 @@ export { matchRoute } from './routing/match.js';
 export type { RouteParams } from './routing/match.js';
 export { connectChannel, useChannel, resolveChannelUrl } from './channel/channel.js';
 export type { Channel, ChannelOptions, ChannelHook, ChannelData } from './channel/channel.js';
+export { makeStreamClient } from './stream/client.js';
+export type { StreamChannel, StreamConnectable, StreamClient } from './stream/client.js';
 export { useHead, useTitle, Head, mergeHead } from './head/head.js';
 export type { HeadSpec, MetaTag, LinkTag, ResolvedHead } from './head/head.js';
 export { resolveMetadata, useMetadata, Metadata } from './head/metadata.js';

package/src/client/rpc.ts

@@ -24,7 +24,26 @@ function restMissingStub(path: string): unknown {
     return new Proxy(call, {
         get(_target, prop) {
             if (typeof prop === 'symbol' || prop === 'then') return undefined;
-            return restMissingStub(`${path}.${String(prop)}`);
+            return restMissingStub(`${path}.${prop}`);
+        },
+        apply() {
+            return call();
+        },
+    });
+}
+
+/** A recursive proxy that throws on call, used when the stream client hasn't loaded. */
+function streamMissingStub(path: string): unknown {
+    const call = (): never => {
+        throw new Error(
+            `toiljs Stream: ${path}() is unavailable. The generated stream client has not loaded - ` +
+                `import a type from your 'shared/server' (so the client attaches), or run 'npm run build:server'.`,
+        );
+    };
+    return new Proxy(call, {
+        get(_target, prop) {
+            if (typeof prop === 'symbol' || prop === 'then') return undefined;
+            return streamMissingStub(`${path}.${prop}`);
         },
         apply() {
             return call();
@@ -49,6 +68,11 @@ function rpcStub(path: string): unknown {
                 const rest = (globalThis as { __toilRest?: unknown }).__toilRest;
                 return rest !== undefined ? rest : restMissingStub('Server.REST');
             }
+            // `Server.Stream` surfaces the generated stream client attached by shared/server.ts.
+            if (path === 'Server' && prop === 'Stream') {
+                const stream = (globalThis as { __toilStream?: unknown }).__toilStream;
+                return stream !== undefined ? stream : streamMissingStub('Server.Stream');
+            }
             return rpcStub(`${path}.${prop}`);
         },
         apply() {