toiljs 0.0.33 → 0.0.36

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

@@ -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',
@@ -203,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
@@ -261,12 +263,118 @@ function scaffold(
     return files;
 }
 
-/** A minimal but working server for the `minimal` template (the `app` template copies examples/basic/server). */
+/**
+ * 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:
+ * 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/toil-server-env.d.ts': TOIL_SERVER_ENV_DTS,
+        '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 +393,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 +710,28 @@ 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',
+            'toil-server-env.d.ts',
+            '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 +773,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() + ')')}`);
 }