toiljs 0.0.67 → 0.0.69

package/src/devserver/stream/ws.ts

@@ -0,0 +1,76 @@
+/**
+ * Transport adapter that bridges ONE dev WebSocket connection to the {@link StreamDevHost} session
+ * driver. It is the per-socket glue the dev WS endpoint instantiates: socket-open -> `acceptUpgrade`
+ * (close on a `@connect`/gate reject), inbound frame -> `dispatch` (send reply frames back, or close
+ * on a reject/trap close code), socket-close -> `@close` + drop. It owns NO transport itself - the
+ * caller passes a {@link StreamWsTransport} of `send`/`close` callbacks - so it is unit-testable
+ * without a live socket and reusable across whatever WS/WebTransport the endpoint ends up speaking.
+ *
+ * The endpoint that wires hyper-express `app.ws` to this (the URL convention + coexistence with the
+ * Vite-HMR catch-all proxy + a `streamWasmFile` config) is the remaining live-server step; this is the
+ * transport-agnostic core it drives.
+ */
+
+import type { StreamDevHost } from './manager.js';
+
+/** The socket-side primitives this adapter needs: send one binary frame, and close with a code. */
+export interface StreamWsTransport {
+    /** Send one outbound binary frame to the client. */
+    send(frame: Buffer): void;
+    /** Close the connection with a `0x02xx` stream close code. */
+    close(code: number): void;
+}
+
+export class StreamWsSession {
+    private open = false;
+
+    constructor(
+        private readonly host: StreamDevHost,
+        private readonly connId: string,
+        private readonly authority: string,
+        private readonly path: string,
+        private readonly transport: StreamWsTransport,
+    ) {}
+
+    /** Whether the connection is accepted + live. */
+    get isOpen(): boolean {
+        return this.open;
+    }
+
+    /**
+     * Socket open: accept the upgrade (node gate is the endpoint's job; this drives the box). On a
+     * `@connect`/artifact reject the connection is closed with the code and no box is held. Returns
+     * whether the connection was accepted.
+     */
+    onOpen(): boolean {
+        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;
+    }
+
+    /** An inbound binary frame: dispatch it; send the reply frames, or close on a reject/trap code. */
+    onMessage(inbound: Buffer): void {
+        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') {
+            // A guest reject or a TRAP close: close the socket; the socket-close event runs onClose,
+            // which fires @close + drops the box (a no-op if a trap already discarded it).
+            this.open = false;
+            this.transport.close(r.code);
+        }
+        // 'noConnection' cannot occur for a live, accepted session.
+    }
+
+    /** Socket close (client-initiated or after our own close): fire `@close` + drop the box. */
+    onClose(): void {
+        if (!this.open && !this.host.has(this.connId)) return;
+        this.open = false;
+        this.host.close(this.connId);
+    }
+}

package/test/built-ssr.test.ts

@@ -0,0 +1,98 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+import { loadBuiltSsrTemplates } from '../src/devserver/production';
+import { assembleSsr, type SsrRoute } from '../src/devserver/ssr';
+
+function slotsManifest(tmplLen: number, hash: Buffer): Buffer {
+    const buf = Buffer.alloc(46 + 8);
+    let o = 0;
+    buf.write('TSLT', o, 'ascii');
+    o += 4;
+    buf.writeUInt16LE(1, o);
+    o += 2;
+    buf.writeUInt16LE(0, o);
+    o += 2;
+    buf.writeUInt32LE(tmplLen, o);
+    o += 4;
+    hash.copy(buf, o);
+    o += 32;
+    buf.writeUInt16LE(1, o);
+    o += 2;
+    buf.writeUInt32LE(1, o); // insert after the first byte
+    o += 4;
+    buf.writeUInt16LE(0, o);
+    o += 2;
+    buf.writeUInt8(0, o); // text
+    o += 1;
+    buf.writeUInt8(0, o);
+    return buf;
+}
+
+function valuesEnvelope(hash: Buffer, value: string): Buffer {
+    const valueBytes = Buffer.from(value);
+    const buf = Buffer.alloc(2 + 32 + 2 + 2 + 2 + 1 + 4 + valueBytes.length);
+    let o = 0;
+    buf.writeUInt16LE(200, o);
+    o += 2;
+    hash.copy(buf, o);
+    o += 32;
+    buf.writeUInt16LE(0, o); // headers
+    o += 2;
+    buf.writeUInt16LE(1, o); // slots
+    o += 2;
+    buf.writeUInt16LE(0, o);
+    o += 2;
+    buf.writeUInt8(0, o);
+    o += 1;
+    buf.writeUInt32LE(valueBytes.length, o);
+    o += 4;
+    valueBytes.copy(buf, o);
+    return buf;
+}
+
+describe('built SSR templates', () => {
+    it('loads the built shell, including production CSS links, from _ssr artifacts', () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), 'toil-built-ssr-'));
+        try {
+            const dir = path.join(root, '_ssr');
+            fs.mkdirSync(dir, { recursive: true });
+            const tmpl = Buffer.from(
+                '<!doctype html><html><head><link rel="stylesheet" href="/css/style.css"></head><body>A</body></html>',
+            );
+            const hash = Buffer.alloc(32, 7);
+            fs.writeFileSync(
+                path.join(dir, 'templates.json'),
+                JSON.stringify([{ route: '/x', name: 'x', hash: hash.toString('hex') }]),
+            );
+            fs.writeFileSync(path.join(dir, 'x.tmpl'), tmpl);
+            fs.writeFileSync(path.join(dir, 'x.slots'), slotsManifest(tmpl.length, hash));
+
+            const templates = loadBuiltSsrTemplates(root);
+            expect(templates).toHaveLength(1);
+            expect(Buffer.from(templates[0]!.tmpl).toString('utf8')).toContain('/css/style.css');
+            expect(Buffer.from(templates[0]!.hash!).equals(hash)).toBe(true);
+            expect(templates[0]!.entries).toEqual([{ id: 0, offset: 1 }]);
+        } finally {
+            fs.rmSync(root, { recursive: true, force: true });
+        }
+    });
+
+    it('checks the deployed template hash before splicing production SSR values', () => {
+        const hash = Buffer.alloc(32, 1);
+        const route: SsrRoute = {
+            test: () => true,
+            tmpl: Buffer.from('ab'),
+            entries: [{ id: 0, offset: 1 }],
+            hash,
+        };
+
+        expect(Buffer.from(assembleSsr(route, valuesEnvelope(hash, 'X'))!.html).toString()).toBe(
+            'aXb',
+        );
+        expect(assembleSsr(route, valuesEnvelope(Buffer.alloc(32, 2), 'X'))).toBeNull();
+    });
+});

package/test/devserver.test.ts

@@ -4,6 +4,7 @@
  * into the example project's ToilScript-compiled server wasm.
  */
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -15,6 +16,7 @@ import {
     unpackHandleResult,
     WasmServerModule,
 } from '../src/devserver/index.js';
+import { resolveStaticFile } from '../src/devserver/http/runtime.js';
 
 const EXAMPLE_WASM = path.resolve(
     path.dirname(fileURLToPath(import.meta.url)),
@@ -121,10 +123,7 @@ describe('response envelope decoding', () => {
             /status 0/,
         );
         // Claim a huge header name with too few bytes behind it.
-        const bad = Buffer.concat([
-            Buffer.from([200, 0, 1, 0, 255, 255, 0, 0]),
-            Buffer.from('hi'),
-        ]);
+        const bad = Buffer.concat([Buffer.from([200, 0, 1, 0, 255, 255, 0, 0]), Buffer.from('hi')]);
         expect(() => decodeResponseEnvelope(bad)).toThrow(/truncated/);
     });
 });
@@ -140,6 +139,23 @@ describe('handle() result unpacking', () => {
     });
 });
 
+describe('static file resolver', () => {
+    it('resolves absolute request paths inside the static root', () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), 'toil-static-'));
+        const file = path.join(root, 'assets', 'app.css');
+        try {
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.writeFileSync(file, 'body{}');
+
+            expect(resolveStaticFile(root, '/assets/app.css')).toBe(file);
+            expect(resolveStaticFile(root, '/missing.css')).toBeNull();
+            expect(resolveStaticFile(root, '/../app.css')).toBeNull();
+        } finally {
+            fs.rmSync(root, { recursive: true, force: true });
+        }
+    });
+});
+
 describe.skipIf(!fs.existsSync(EXAMPLE_WASM))('dispatch into the example server wasm', () => {
     const load = (): WasmServerModule => {
         const m = new WasmServerModule(EXAMPLE_WASM);

package/test/example-guestbook.test.ts

@@ -64,17 +64,20 @@ describe.skipIf(!haveWasm)('guestbook demo: ToilDB events + counter persist acro
         expect(json(r).total).toBe('1');
 
         // A brand-new wasm instance - its memory is empty - still sees the prior
-        // signature, because it lives in ToilDB, not module state.
+        // signature, because it lives in ToilDB, not module state. The action
+        // acks with the running total; the entries list is served by the GET.
         r = sign(load(), 'Linus', 'second');
-        const v = json(r);
+        expect(json(r).total).toBe('2');
+
+        // The newest entries are served by GET /guestbook from the materialized
+        // view that the @derive republishes after each signature (events.latest
+        // is a scan, barred in the request handlers, so it runs in the derive).
+        const v = json(list(load()));
         expect(v.total).toBe('2');
         expect(v.entries.length).toBe(2);
         expect(v.entries[0].author).toBe('Linus'); // events.latest is newest-first
         expect(v.entries[1].author).toBe('Ada');
         expect(v.entries[1].message).toBe('first!');
-
-        // A read-only GET on yet another instance sees the same persisted state.
-        expect(json(list(load())).total).toBe('2');
     });
 
     // End-to-end proof that the `server/migrations/GuestEntry.migration.ts` demo

package/test/fixtures/stream-echo.ts

@@ -0,0 +1,26 @@
+// Dev-stream emulation fixture: a `@stream('echo')` whose raw `@message` bridge echoes the inbound
+// bytes back through the egress ring, rejects an 'X'-prefixed frame (0x0210), and `empty()`s a
+// zero-length frame. Compiled by the dev test with the LOCAL toilscript (`--targetMode hot`), then
+// driven through `DevStreamBox`. Mirrors toil-backend's `tests/fixtures/stream/echo_src.ts`.
+
+let __count: i32 = 0;
+
+// Observable so the @message hook's residency can be asserted across events.
+export function messageCount(): i32 {
+  return __count;
+}
+
+@stream('echo')
+class Echo {
+  @message reply(p: StreamPacket): StreamOutbound {
+    __count = __count + 1;
+    const n = p.length;
+    if (n == 0) return StreamOutbound.empty();
+    if (p.at(0) == 0x58) return StreamOutbound.reject(0x0210); // 'X' -> reject
+    return StreamOutbound.reply(p.bytes());
+  }
+}
+
+export function probe(): i32 {
+  return 1;
+}

package/test/fixtures/stream-gate.ts

@@ -0,0 +1,24 @@
+// Dev @connect-bridge fixture: a `@stream('gate')` whose `@connect(c: StreamInbound): StreamOutbound`
+// reads the host-written connect context (the path) and REJECTS "/blocked" with 0x0211, ACCEPTING any
+// other path; a "/greet" path stages an egress frame DURING @connect (the host must clear it so it does
+// not contaminate the first @message reply). A @message echoes. Mirrors toil-backend's connect_src.ts;
+// exercises the whole @connect bridge (stream_info block -> StreamInbound.path() -> accept/reject).
+
+@stream('gate')
+class Gate {
+  @connect onConnect(c: StreamInbound): StreamOutbound {
+    if (c.path() == "/blocked") return StreamOutbound.reject(0x0211);
+    if (c.path() == "/greet") {
+      const g = new Uint8Array(3);
+      g[0] = 0x47; g[1] = 0x48; g[2] = 0x49; // "GHI"
+      StreamOutbound.reply(g);
+      return StreamOutbound.accept();
+    }
+    return StreamOutbound.accept();
+  }
+  @message reply(p: StreamPacket): StreamOutbound {
+    return StreamOutbound.reply(p.bytes());
+  }
+}
+
+export function probe(): i32 { return 1; }

package/test/fixtures/stream-trap.ts

@@ -0,0 +1,18 @@
+// Dev trap fixture: a `@stream('trap')` whose `@message` deliberately TRAPS (the wasm `unreachable`
+// instruction). The dev has no gas-metering middleware, so this stands in for the edge's gas-kill: a
+// real trap makes the dispatch throw, which StreamDevHost turns into a STREAM_HOOK_TRAPPED close that
+// discards the poisoned box (mirrors toil-backend's poisoned-box containment, 05 7.4).
+//
+// The trap sits behind an always-true guard so the `return` stays reachable to the type checker.
+
+@stream('trap')
+class Trap {
+  @message boom(p: StreamPacket): StreamOutbound {
+    if (p.length >= 0) {
+      unreachable();
+    }
+    return StreamOutbound.empty();
+  }
+}
+
+export function probe(): i32 { return 1; }

package/test/fixtures/stream-typed.ts

@@ -0,0 +1,41 @@
+// A TYPED @stream fixture: @stream({ message: ChatMsg }) makes @message receive the DECODED @data
+// (doc 03 2.5), not raw bytes. The hook replies with the decoded text's length, so a host round-trip
+// proves the @data decode ran at runtime (not just compiled). The seed* exports hand the host a real
+// ChatMsg.encode() payload so the test never hand-crafts the @data wire format.
+
+@data
+class ChatMsg {
+  text: string = '';
+}
+
+@stream({ message: ChatMsg })
+class TypedChat {
+  @message
+  onMsg(m: ChatMsg): StreamOutbound {
+    // Reply with the DECODED text length (one byte): "hi" -> 2 proves the decode produced the string.
+    const r = new Uint8Array(1);
+    r[0] = <u8>m.text.length;
+    return StreamOutbound.reply(r);
+  }
+}
+
+// Seed buffer: the guest encodes a ChatMsg the host feeds back, so the host never hand-crafts @data
+// bytes (the encode/decode pair is the wire contract). A StaticArray<u8>'s pointer IS its data start.
+let seedBuf = new StaticArray<u8>(64);
+let seedLen: i32 = 0;
+
+export function seedHi(): void {
+  const m = new ChatMsg();
+  m.text = 'hi';
+  const b = m.encode();
+  seedLen = b.length;
+  for (let i = 0, n = b.length; i < n; i++) seedBuf[i] = b[i];
+}
+
+export function seedOffset(): i32 {
+  return changetype<i32>(seedBuf);
+}
+
+export function seedLength(): i32 {
+  return seedLen;
+}