toiljs 0.0.34 → 0.0.36

package/server/runtime/ssr/Ssr.ts

@@ -0,0 +1,43 @@
+/**
+ * The auto-populated SSR render router. Every compiler-generated route render
+ * self-registers here at module init; the `render` wasm export calls
+ * `Ssr.dispatch(req)` to find the one whose path matches. The host has already
+ * decided this is a template route, but the guest re-derives WHICH route from
+ * the request path (the template name is not in the request envelope), exactly
+ * as a `@rest` controller matches its own prefix.
+ *
+ * First matching render wins; `null` means no route matched (a guest/host
+ * coherence problem) and the export emits a fail-safe empty result.
+ */
+
+import { Request } from '../request';
+import { SlotValues } from './slots';
+
+/** A route render: returns filled hole values on a path hit, null on a miss. */
+export type RenderFn = (req: Request) => SlotValues | null;
+
+export class SsrRegistry {
+    private fns: Array<RenderFn> = new Array<RenderFn>();
+
+    /** Compiler-injected: registers a route's render. Not for direct use. */
+    register(fn: RenderFn): void {
+        this.fns.push(fn);
+    }
+
+    /** Try every registered render in registration order; first match wins. */
+    dispatch(req: Request): SlotValues | null {
+        for (let i = 0; i < this.fns.length; i++) {
+            const hit = this.fns[i](req);
+            if (hit != null) return hit;
+        }
+        return null;
+    }
+
+    /** Number of registered renders (diagnostics / tests). */
+    get size(): i32 {
+        return this.fns.length;
+    }
+}
+
+/** The process-wide SSR render router singleton. */
+export const Ssr: SsrRegistry = new SsrRegistry();

package/server/runtime/ssr/encode.ts

@@ -0,0 +1,110 @@
+/**
+ * Serialiser for the SSR **values envelope** (guest -> host), byte-for-byte
+ * compatible with `toil-backend/src/host/template/assemble.rs::decode_values`.
+ *
+ * Layout (LE, no padding):
+ *
+ *   u16  status
+ *   [32] template_hash
+ *   u16  n_headers
+ *   for each header: u16 name_len, u16 val_len, [u8] name, [u8] val
+ *   u16  n_slots
+ *   for each value: u16 slot_id, u8 kind, u32 value_len, [u8] value
+ *
+ * The host keys values by `slot_id` and inserts each at the manifest-fixed
+ * offset, so the guest can never choose where bytes land.
+ */
+
+import {
+    utf8Length,
+    writeBytes,
+    writeU16,
+    writeU32,
+    writeU8,
+    writeUtf8,
+} from '../memory';
+import { HASH_LEN, SlotValues } from './slots';
+
+/** Serialise `v` into linear memory at `dst_ofs`; returns bytes written. On any
+ * representability violation (counts/lengths over their field widths, or a
+ * wrong-sized hash) a minimal 500 envelope is written instead so the host never
+ * sees an encoder fault. */
+export function encodeValues(v: SlotValues, dst_ofs: usize): u32 {
+    if (v.templateHash.length != HASH_LEN) return encodeFallback(dst_ofs);
+    if (v.headers.length > 0xffff || v.slots.length > 0xffff) return encodeFallback(dst_ofs);
+    for (let i = 0; i < v.headers.length; i++) {
+        const h = v.headers[i];
+        if (utf8Length(h.name) > 0xffff || utf8Length(h.value) > 0xffff) {
+            return encodeFallback(dst_ofs);
+        }
+    }
+    for (let i = 0; i < v.slots.length; i++) {
+        if (<u64>v.slots[i].bytes.length > <u64>0xffffffff) return encodeFallback(dst_ofs);
+    }
+
+    let cur: usize = dst_ofs;
+
+    writeU16(cur, v.status);
+    cur += 2;
+
+    for (let i = 0; i < HASH_LEN; i++) {
+        writeU8(cur + <usize>i, v.templateHash[i]);
+    }
+    cur += <usize>HASH_LEN;
+
+    writeU16(cur, <u16>v.headers.length);
+    cur += 2;
+    for (let i = 0; i < v.headers.length; i++) {
+        const h = v.headers[i];
+        writeU16(cur, <u16>utf8Length(h.name));
+        cur += 2;
+        writeU16(cur, <u16>utf8Length(h.value));
+        cur += 2;
+        cur += writeUtf8(cur, h.name);
+        cur += writeUtf8(cur, h.value);
+    }
+
+    writeU16(cur, <u16>v.slots.length);
+    cur += 2;
+    for (let i = 0; i < v.slots.length; i++) {
+        const s = v.slots[i];
+        writeU16(cur, <u16>s.slotId);
+        cur += 2;
+        writeU8(cur, s.kind);
+        cur += 1;
+        writeU32(cur, <u32>s.bytes.length);
+        cur += 4;
+        cur += writeBytes(cur, s.bytes);
+    }
+
+    return <u32>(cur - dst_ofs);
+}
+
+/** Upper bound on the encoded size of `v`, used to size the response slot the
+ * `render` export allocates before encoding. */
+export function valuesEncodedBound(v: SlotValues): usize {
+    // status + hash + n_headers + n_slots field overheads.
+    let bound: usize = 2 + <usize>HASH_LEN + 2 + 2;
+    for (let i = 0; i < v.headers.length; i++) {
+        const h = v.headers[i];
+        bound += 4 + <usize>utf8Length(h.name) + <usize>utf8Length(h.value);
+    }
+    for (let i = 0; i < v.slots.length; i++) {
+        bound += 7 + <usize>v.slots[i].bytes.length;
+    }
+    return bound;
+}
+
+function encodeFallback(dst_ofs: usize): u32 {
+    // status=500, zeroed 32-byte hash (host rejects as a coherence mismatch),
+    // 0 headers, 0 slots.
+    writeU16(dst_ofs, 500);
+    let cur = dst_ofs + 2;
+    for (let i = 0; i < HASH_LEN; i++) {
+        writeU8(cur + <usize>i, 0);
+    }
+    cur += <usize>HASH_LEN;
+    writeU16(cur, 0);
+    writeU16(cur + 2, 0);
+    return <u32>(2 + HASH_LEN + 2 + 2);
+}

package/server/runtime/ssr/escape.ts

@@ -0,0 +1,83 @@
+/**
+ * HTML escaping for edge-SSR hole values, byte-for-byte identical to
+ * react-dom/server's `escapeTextForBrowser` (the regex `/["'&<>]/`). React
+ * runs the SAME escaper for text children and attribute values, so a single
+ * function serves both kinds. Matching React exactly is load-bearing: the
+ * browser's `hydrateRoot` compares the server markup to its own first render,
+ * and any escaping difference triggers a hydration mismatch.
+ *
+ * Note the entities: `'` becomes `&#x27;` (React's choice, NOT `&#39;` or
+ * `&apos;`), and `"` becomes `&quot;`. Do not "simplify" these.
+ */
+
+@inline function needsEscape(c: i32): bool {
+    // 0x22 " | 0x26 & | 0x27 ' | 0x3C < | 0x3E >
+    return c == 0x22 || c == 0x26 || c == 0x27 || c == 0x3c || c == 0x3e;
+}
+
+/** React-exact HTML text/attribute escape. */
+export function escapeHtml(s: string): string {
+    let hit = false;
+    for (let i = 0; i < s.length; i++) {
+        if (needsEscape(s.charCodeAt(i))) {
+            hit = true;
+            break;
+        }
+    }
+    if (!hit) return s;
+
+    let out = '';
+    let last = 0;
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        let rep: string = '';
+        if (c == 0x22) rep = '&quot;';
+        else if (c == 0x26) rep = '&amp;';
+        else if (c == 0x27) rep = '&#x27;';
+        else if (c == 0x3c) rep = '&lt;';
+        else if (c == 0x3e) rep = '&gt;';
+        else continue;
+        out += s.substring(last, i);
+        out += rep;
+        last = i + 1;
+    }
+    out += s.substring(last, s.length);
+    return out;
+}
+
+/**
+ * Escape a JSON string for safe embedding inside a `<script>` element (the
+ * `__toil_state` hydration blob). Neutralises `<`, `>`, `&` and the JS line
+ * terminators U+2028/U+2029 to their `\uXXXX` forms so the JSON can never
+ * close the script element or break the parse. Mirrors the standard
+ * "serialize-javascript"/Next.js approach; the bytes stay valid JSON.
+ */
+export function escapeJsonForScript(json: string): string {
+    let hit = false;
+    for (let i = 0; i < json.length; i++) {
+        const c = json.charCodeAt(i);
+        if (c == 0x3c || c == 0x3e || c == 0x26 || c == 0x2028 || c == 0x2029) {
+            hit = true;
+            break;
+        }
+    }
+    if (!hit) return json;
+
+    let out = '';
+    let last = 0;
+    for (let i = 0; i < json.length; i++) {
+        const c = json.charCodeAt(i);
+        let rep: string = '';
+        if (c == 0x3c) rep = '\\u003c';
+        else if (c == 0x3e) rep = '\\u003e';
+        else if (c == 0x26) rep = '\\u0026';
+        else if (c == 0x2028) rep = '\\u2028';
+        else if (c == 0x2029) rep = '\\u2029';
+        else continue;
+        out += json.substring(last, i);
+        out += rep;
+        last = i + 1;
+    }
+    out += json.substring(last, json.length);
+    return out;
+}

package/server/runtime/ssr/slots.ts

@@ -0,0 +1,144 @@
+/**
+ * The values the guest `render` returns for one request: the hole values the
+ * edge splices into the precompiled template. The guest never emits the static
+ * template bytes (the host has those, mmap'd); it only fills the holes.
+ *
+ * Authoring is normally generated by the toiljs compiler from the route's JSX,
+ * but the typed API here is hand-writable too (it is the escape hatch). A
+ * generated render looks like:
+ *
+ * ```ts
+ * export function renderProfile(req: Request): SlotValues {
+ *   const v = new SlotValues(HASH);
+ *   v.setText(Slot.username, params(req, 'name'));
+ *   v.setRaw(Slot.bio, bioHtml);
+ *   const rows = new HtmlBuilder();
+ *   for (let i = 0; i < posts.length; i++) rows.raw('<li>').text(posts[i]).raw('</li>');
+ *   v.setRepeat(Slot.posts, rows);
+ *   return v;
+ * }
+ * ```
+ */
+
+import { Header } from '../request';
+import { escapeHtml } from './escape';
+
+/** Slot kind discriminants. Mirror `toil-backend` `SlotKind` and the on-disk
+ * `.slots` manifest; do not reorder. */
+export namespace SlotKind {
+    // @ts-ignore: decorator
+    @inline export const TEXT: u8 = 0;
+    // @ts-ignore: decorator
+    @inline export const RAW: u8 = 1;
+    // @ts-ignore: decorator
+    @inline export const ATTR: u8 = 2;
+    // @ts-ignore: decorator
+    @inline export const REPEAT: u8 = 3;
+}
+
+/** Number of bytes in the coherence hash; must match the host's `HASH_LEN`. */
+// @ts-ignore: decorator
+@inline export const HASH_LEN: i32 = 32;
+
+/** One filled hole: its stable id, kind, and the already-escaped bytes. The id
+ * is held as `i32` so a generated `Slot` enum member (AS enums are `i32`) is
+ * passed without a cast; it is narrowed to `u16` only at encode time. */
+export class SlotValue {
+    constructor(
+        public slotId: i32,
+        public kind: u8,
+        public bytes: Uint8Array,
+    ) {}
+}
+
+@inline function utf8(s: string): Uint8Array {
+    return Uint8Array.wrap(String.UTF8.encode(s));
+}
+
+/**
+ * Append-only HTML byte builder for repeat regions (and any place the
+ * generated code assembles a run of static chunks + escaped values). `raw`
+ * appends verbatim template bytes; `text`/`attr` append React-escaped values.
+ * Chaining keeps generated loops terse.
+ */
+export class HtmlBuilder {
+    private parts: Array<string> = new Array<string>();
+
+    raw(s: string): HtmlBuilder {
+        this.parts.push(s);
+        return this;
+    }
+
+    text(s: string): HtmlBuilder {
+        this.parts.push(escapeHtml(s));
+        return this;
+    }
+
+    /** Attribute escaping is identical to text escaping in React. */
+    attr(s: string): HtmlBuilder {
+        this.parts.push(escapeHtml(s));
+        return this;
+    }
+
+    toBytes(): Uint8Array {
+        return utf8(this.parts.join(''));
+    }
+}
+
+/**
+ * The render result: status, coherence hash, response headers, and the ordered
+ * filled holes. Serialised by `encodeValues` into the values envelope the host
+ * splices against the template manifest.
+ */
+export class SlotValues {
+    status: u16 = 200;
+    headers: Array<Header> = new Array<Header>();
+    slots: Array<SlotValue> = new Array<SlotValue>();
+
+    /** `hash` is the route's compiled-in coherence hash (32 bytes); the host
+     * rejects the response if it does not match the deployed template. */
+    constructor(public templateHash: StaticArray<u8>) {}
+
+    /** A text hole: React-escaped. */
+    setText(slotId: i32, value: string): SlotValues {
+        this.slots.push(new SlotValue(slotId, SlotKind.TEXT, utf8(escapeHtml(value))));
+        return this;
+    }
+
+    /** A raw-HTML hole: inserted verbatim. The author owns sanitisation, same
+     * as React `dangerouslySetInnerHTML`. */
+    setRaw(slotId: i32, html: string): SlotValues {
+        this.slots.push(new SlotValue(slotId, SlotKind.RAW, utf8(html)));
+        return this;
+    }
+
+    /** An attribute-value hole. */
+    setAttr(slotId: i32, value: string): SlotValues {
+        this.slots.push(new SlotValue(slotId, SlotKind.ATTR, utf8(escapeHtml(value))));
+        return this;
+    }
+
+    /** A repeat region: the guest pre-stamped + concatenated rows (built via
+     * [`HtmlBuilder`]); the host inserts them verbatim at the region offset. */
+    setRepeat(slotId: i32, rows: HtmlBuilder): SlotValues {
+        this.slots.push(new SlotValue(slotId, SlotKind.REPEAT, rows.toBytes()));
+        return this;
+    }
+
+    /** Add a response header (e.g. a Set-Cookie or Cache-Control). */
+    setHeader(name: string, value: string): SlotValues {
+        this.headers.push(new Header(name, value));
+        return this;
+    }
+
+    setStatus(status: u16): SlotValues {
+        this.status = status;
+        return this;
+    }
+}
+
+/** A zeroed 32-byte hash. Used for the fail-safe empty result, which the host
+ * rejects as a hash mismatch (-> 500) rather than serving a broken page. */
+export function zeroHash(): StaticArray<u8> {
+    return new StaticArray<u8>(HASH_LEN);
+}

package/server/runtime/time.ts

@@ -0,0 +1,29 @@
+/**
+ * `Time` — the guest's wall-clock, backed by the host's `Date.now()` binding
+ * (`env.Date.now`). Both the edge (`toil-backend` `date_now_import.rs`) and the
+ * dev server (`toiljs/src/devserver/host.ts`) provide it, so time behaves the
+ * same in `toiljs dev` and in production.
+ *
+ * This is the toiljs-blessed way to read the clock; prefer it over a raw
+ * `Date.now()` so the host boundary (and its single millisecond unit) is
+ * explicit and easy to find. Like browser `Date.now()` it is WALL-CLOCK, not
+ * monotonic: it can step backward across an NTP correction, so never use it to
+ * measure elapsed time, only to stamp/compare absolute instants (session
+ * `iat`/`exp`, challenge expiry, cache ages).
+ *
+ * Exposed as an ambient global (`@global`, usable with no import in a handler)
+ * and re-exported from `toiljs/server/runtime`.
+ */
+@global
+export class Time {
+    /** Milliseconds since the Unix epoch (the host `Date.now()` value). */
+    static nowMillis(): i64 {
+        return <i64>Date.now();
+    }
+
+    /** Whole seconds since the Unix epoch (`nowMillis() / 1000`), the unit used
+     *  for session and challenge timestamps. */
+    static nowSeconds(): u64 {
+        return <u64>(Date.now() / 1000);
+    }
+}

package/src/cli/create.ts

@@ -201,6 +201,10 @@ function scaffold(
                             'multi-value',
                         ],
                         runtime: 'stub',
+                        // toiljs server globals (exports become ambient, used
+                        // with no import -- e.g. `AuthService` for the
+                        // post-quantum auth primitive), exactly like `crypto`.
+                        lib: ['node_modules/toiljs/server/globals'],
                         // Reserve [0, 64 KiB) for the request envelope the
                         // edge writes at offset 0. Static data starts ABOVE
                         // it, so a large request can never overwrite guest
@@ -259,6 +263,105 @@ function scaffold(
     return files;
 }
 
+/**
+ * Editor-only ambient declarations for the toiljs cookie globals (`Cookie` /
+ * `Cookies` / `SecureCookies` / `SameSite` / ...). They are `@global` in the
+ * runtime, so handlers use them without an import (like `crypto`); this gives the
+ * editor their shapes. Auto-included via the server tsconfig and ignored by the
+ * compiler. Keep in sync with `toiljs/server/runtime/http/*`.
+ */
+const TOIL_SERVER_ENV_DTS = `/**
+ * Editor-only ambient declarations for the toiljs cookie globals.
+ *
+ * \`Cookie\`, \`Cookies\`, \`SecureCookies\`, and the \`SameSite\` / \`CookieEncoding\` /
+ * \`CookiePrefix\` enums are \`@global\` in the toiljs server runtime, so a handler
+ * uses them with no import (exactly like \`crypto\`). The toilscript compiler
+ * registers them from the runtime; this file just gives the editor their shapes.
+ * It is auto-included by the server tsconfig and ignored by the compiler.
+ */
+
+declare enum SameSite {
+    Default = 0,
+    None = 1,
+    Lax = 2,
+    Strict = 3,
+}
+
+declare enum CookieEncoding {
+    Percent = 0,
+    Raw = 1,
+    Base64Url = 2,
+}
+
+declare enum CookiePrefix {
+    None = 0,
+    Secure = 1,
+    Host = 2,
+}
+
+declare class CookieValidation {
+    valid: bool;
+    errors: Array<string>;
+    fail(msg: string): void;
+}
+
+declare class Cookie {
+    name: string;
+    value: string;
+    encoding: CookieEncoding;
+    constructor(name: string, value: string);
+    static create(name: string, value: string): Cookie;
+    domain(v: string): Cookie;
+    path(v: string): Cookie;
+    maxAge(seconds: i64): Cookie;
+    expires(epochSeconds: i64): Cookie;
+    expiresRaw(date: string): Cookie;
+    secure(on?: bool): Cookie;
+    httpOnly(on?: bool): Cookie;
+    sameSite(s: SameSite): Cookie;
+    partitioned(on?: bool): Cookie;
+    priority(p: string): Cookie;
+    extension(av: string): Cookie;
+    withEncoding(e: CookieEncoding): Cookie;
+    asSecurePrefixed(): Cookie;
+    asHostPrefixed(): Cookie;
+    detectedPrefix(): CookiePrefix;
+    encodedValue(): string;
+    validate(): CookieValidation;
+    serialize(strict?: bool): string;
+    toString(): string;
+}
+
+declare class CookieMap {
+    set(name: string, value: string): void;
+    get(name: string): string | null;
+    has(name: string): bool;
+    names(): Array<string>;
+    readonly size: i32;
+}
+
+declare class Cookies {
+    static parse(cookieHeader: string): CookieMap;
+    static get(cookieHeader: string, name: string): string | null;
+    static serialize(name: string, value: string): string;
+    static parseSetCookie(setCookie: string): Cookie;
+    static encodeValue(raw: string): string;
+    static decodeValue(enc: string): string;
+}
+
+declare class SecureCookies {
+    static signed(key: Uint8Array): SecureCookies;
+    static encrypted(key: Uint8Array): SecureCookies;
+    addKey(key: Uint8Array): SecureCookies;
+    sign(name: string, value: string): string;
+    unsign(name: string, sealed: string): string | null;
+    encrypt(name: string, value: string): string;
+    decrypt(name: string, sealed: string): string | null;
+    seal(cookie: Cookie): Cookie;
+    open(jar: CookieMap, name: string): string | null;
+}
+`;
+
 /**
  * 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:
@@ -267,6 +370,7 @@ function scaffold(
  */
 function minimalServer(): Record<string, string> {
     return {
+        'server/toil-server-env.d.ts': TOIL_SERVER_ENV_DTS,
         'server/core/AppHandler.ts':
             "import { ToilHandler, Request, Response, Method } from 'toiljs/server/runtime';\n\n" +
             '/** Every request enters here. Add `@rest` controllers under routes/ as you grow. */\n' +
@@ -612,6 +716,7 @@ export async function runCreate(opts: CreateOptions): Promise<void> {
             'main.ts',
             'README.md',
             'tsconfig.json',
+            'toil-server-env.d.ts',
             'core',
             'models',
             'routes',