toiljs 0.0.69 → 0.0.70

package/build/devserver/db/routeKinds.js

@@ -1,6 +1,7 @@
 import { customSection } from '../wasm/sections.js';
 import { DbFunctionKind } from './types.js';
 const SECTION = 'toildb.route_kinds';
+const RPC_SECTION = 'toildb.rpc_kinds';
 const VERSION = 1;
 const MAX_SECTION_BYTES = 128 * 1024;
 const MAX_ROUTES = 2048;
@@ -58,6 +59,45 @@ export function routeKindForRequest(routes, method, path) {
     }
     return null;
 }
+export function parseRpcKinds(wasm) {
+    let section;
+    try {
+        section = customSection(wasm, RPC_SECTION);
+    }
+    catch {
+        return [];
+    }
+    if (section === null)
+        return [];
+    if (section.length > MAX_SECTION_BYTES)
+        return [];
+    const r = new Reader(section);
+    const version = r.u16();
+    if (!r.ok || version !== VERSION)
+        return [];
+    const count = r.u16();
+    if (!r.ok || count > MAX_ROUTES)
+        return [];
+    const methods = [];
+    for (let i = 0; i < count && r.ok; i++) {
+        const methodId = r.u32();
+        const kindByte = r.u8();
+        const kind = kindByte === 0 ? DbFunctionKind.Query : kindByte === 1 ? DbFunctionKind.Action : null;
+        if (!r.ok || kind === null)
+            return [];
+        methods.push({ methodId, kind });
+    }
+    if (!r.ok || r.remaining() !== 0)
+        return [];
+    return methods;
+}
+export function rpcKindForId(methods, methodId) {
+    for (const m of methods) {
+        if (m.methodId === methodId)
+            return m.kind;
+    }
+    return DbFunctionKind.Query;
+}
 function validPattern(pattern) {
     if (pattern.length === 0 || !pattern.startsWith('/'))
         return false;

package/build/devserver/index.d.ts

@@ -18,4 +18,3 @@ export { cronMatches, cronNeverFires, nextCronFireMs } from './daemon/cron.js';
 export { parseSurface } from './wasm/surface.js';
 export type { Surface, SurfaceFlags } from './wasm/surface.js';
 export { customSection } from './wasm/sections.js';
-export { DevMemoryStore, devMemoryStore } from './mstore/store.js';

package/build/devserver/index.js

@@ -9,4 +9,3 @@ export { buildDaemonImports, freshDaemonState } from './daemon/host.js';
 export { cronMatches, cronNeverFires, nextCronFireMs } from './daemon/cron.js';
 export { parseSurface } from './wasm/surface.js';
 export { customSection } from './wasm/sections.js';
-export { DevMemoryStore, devMemoryStore } from './mstore/store.js';

package/build/devserver/runtime/module.d.ts

@@ -16,6 +16,7 @@ export declare class WasmServerModule {
     private module;
     private loadedMtimeMs;
     private routeKinds;
+    private rpcKinds;
     private derives;
     private derivesDirty;
     constructor(wasmPath: string);

package/build/devserver/runtime/module.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import { DbFunctionKind, derivesForWrites, parseDerives, persistDb, setDbCatalog, } from '../db/index.js';
-import { parseRouteKinds, routeKindForRequest } from '../db/routeKinds.js';
+import { parseRouteKinds, parseRpcKinds, routeKindForRequest, rpcKindForId, } from '../db/routeKinds.js';
 import { decodeResponseEnvelope, encodeRequestEnvelope, unpackHandleResult, } from '../http/envelope.js';
 import { buildHostImports, freshDispatchState } from './host.js';
 export { WasmAbortError } from './host.js';
@@ -87,6 +87,7 @@ export class WasmServerModule {
     module = null;
     loadedMtimeMs = -1;
     routeKinds = [];
+    rpcKinds = [];
     derives = [];
     derivesDirty = false;
     constructor(wasmPath) {
@@ -103,6 +104,7 @@ export class WasmServerModule {
         catch {
             this.module = null;
             this.routeKinds = [];
+            this.rpcKinds = [];
             this.derives = [];
             this.derivesDirty = false;
             this.loadedMtimeMs = -1;
@@ -116,6 +118,7 @@ export class WasmServerModule {
         this.assertExportSurface(module);
         setDbCatalog(bytes);
         this.routeKinds = parseRouteKinds(bytes);
+        this.rpcKinds = parseRpcKinds(bytes);
         this.derives = parseDerives(bytes);
         this.module = module;
         this.loadedMtimeMs = mtimeMs;
@@ -130,7 +133,20 @@ export class WasmServerModule {
         const ref = { memory: null };
         const state = freshDispatchState();
         state.clientIp = req.clientIp ?? '';
-        state.db.functionKind = dbFunctionKindForRequest(this.routeKinds, req.method, req.path);
+        const rpcPath = req.path.split('?')[0] ?? req.path;
+        const rpcMethod = req.method.toUpperCase();
+        const rpcMutating = rpcMethod === 'POST' || rpcMethod === 'PUT' || rpcMethod === 'PATCH' || rpcMethod === 'DELETE';
+        if (rpcPath === '/__toil_rpc' && rpcMutating) {
+            const idHeader = req.headers.find(([n]) => n.toLowerCase() === 'toil-rpc')?.[1];
+            const id = idHeader !== undefined && /^\d+$/.test(idHeader) ? Number(idHeader) : NaN;
+            state.db.functionKind =
+                Number.isInteger(id) && id <= 0xffffffff
+                    ? rpcKindForId(this.rpcKinds, id)
+                    : DbFunctionKind.Query;
+        }
+        else {
+            state.db.functionKind = dbFunctionKindForRequest(this.routeKinds, req.method, req.path);
+        }
         const instance = new WebAssembly.Instance(this.module, buildHostImports(ref, state));
         const exports = instance.exports;
         ref.memory = exports.memory;

package/build/devserver/stream/index.js

@@ -35,8 +35,8 @@ export class DevStreamBox {
     }
     static load(wasm) {
         const surface = parseSurface(wasm);
-        if (surface === 'invalid' || surface.targetMode !== 'hot') {
-            throw new Error('stream box requires a hot artifact with a valid toil.surface');
+        if (surface === 'invalid' || surface.targetMode !== 'hot' || !surface.flags.stream) {
+            throw new Error('stream box requires a hot stream artifact with a valid toil.surface');
         }
         const ref = { memory: null };
         const state = freshStreamBoxState();
@@ -105,7 +105,8 @@ export class DevStreamBox {
         };
     }
     static resolveStreamInfo(e) {
-        if (typeof e.stream_info_offset !== 'function' || typeof e.stream_info_capacity !== 'function') {
+        if (typeof e.stream_info_offset !== 'function' ||
+            typeof e.stream_info_capacity !== 'function') {
             return null;
         }
         return { offset: e.stream_info_offset() >>> 0, cap: e.stream_info_capacity() >>> 0 };

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

@@ -1,3 +1,5 @@
+export declare const SURFACE_FORMAT_VERSION = 1;
+export declare const SURFACE_ABI_VERSION = 1;
 export interface SurfaceFlags {
     readonly rest: boolean;
     readonly stream: boolean;

package/build/devserver/wasm/surface.js

@@ -1,5 +1,16 @@
 import { DataReader } from 'toiljs/io';
 import { customSection } from './sections.js';
+export const SURFACE_FORMAT_VERSION = 1;
+export const SURFACE_ABI_VERSION = 1;
+const TARGET_HOT = 0;
+const TARGET_COLD = 1;
+const FLAG_REST = 1 << 0;
+const FLAG_STREAM = 1 << 1;
+const FLAG_DAEMON = 1 << 2;
+const FLAG_SCHEDULED = 1 << 3;
+const FLAG_DATABASE = 1 << 4;
+const FLAG_RENDER = 1 << 5;
+const FLAG_KNOWN_MASK = FLAG_REST | FLAG_STREAM | FLAG_DAEMON | FLAG_SCHEDULED | FLAG_DATABASE | FLAG_RENDER;
 export function parseSurface(wasm) {
     let sec;
     try {
@@ -11,16 +22,36 @@ export function parseSurface(wasm) {
     if (sec === null)
         return 'invalid';
     const r = new DataReader(sec);
-    r.readU16();
-    const targetMode = r.readU8() === 1 ? 'cold' : 'hot';
-    r.readU8();
+    const version = r.readU16();
+    if (!r.ok || version !== SURFACE_FORMAT_VERSION)
+        return 'invalid';
+    const targetModeByte = r.readU8();
+    if (!r.ok || (targetModeByte !== TARGET_HOT && targetModeByte !== TARGET_COLD)) {
+        return 'invalid';
+    }
+    const targetMode = targetModeByte === TARGET_COLD ? 'cold' : 'hot';
+    const reserved0 = r.readU8();
+    if (!r.ok || reserved0 !== 0)
+        return 'invalid';
     const f = r.readU32();
+    if (!r.ok || (f & ~FLAG_KNOWN_MASK) !== 0)
+        return 'invalid';
+    if ((f & FLAG_SCHEDULED) !== 0 && (f & FLAG_DAEMON) === 0)
+        return 'invalid';
+    if (targetMode === 'hot' && (f & (FLAG_DAEMON | FLAG_SCHEDULED)) !== 0) {
+        return 'invalid';
+    }
+    if (targetMode === 'cold' && (f & (FLAG_REST | FLAG_STREAM | FLAG_RENDER)) !== 0) {
+        return 'invalid';
+    }
     const abiVersion = r.readU16();
+    if (!r.ok || abiVersion !== SURFACE_ABI_VERSION)
+        return 'invalid';
     const buildId = r.readString();
     const fingerprint = r.readU32();
     const dataCoherenceHash = r.readU32();
     const pairCoherenceHash = r.readU32();
-    if (!r.ok)
+    if (!r.ok || r.remaining() !== 0)
         return 'invalid';
     return {
         targetMode,

package/docs/streams.md

@@ -52,7 +52,6 @@ optional - declare only the ones you need; a missing hook is a no-op.
 | `@message` | an inbound frame arrives. |
 | `@close` | the connection closes gracefully (the box is torn down after this hook). |
 | `@disconnect` | the transport is lost abruptly. |
-| `@channel` | an opt-in distributed channel delivers a message (advanced; see below). |
 
 The `Echo` example above shows why state survives: `count` is set to `0` in
 `@connect`, incremented on every `@message`, and the increments **accumulate**.
@@ -60,9 +59,9 @@ That is only possible because the same resident box handles every event for the
 connection. A `@rest` handler's fields would reset on each request, since a
 fresh handler is constructed per request.
 
-`@channel` is an opt-in **distributed** channel (advanced) - a way for boxes to
-exchange messages beyond a single connection. It is mentioned here for
-completeness; most streams use only the four connection-lifecycle hooks.
+Distributed stream channels are not part of the live v1 ABI. The edge rejects
+stream artifacts that declare a channel hook until the channel fan-out runtime
+exists.
 
 ## Placement
 

package/examples/basic/server/services/Stats.ts

@@ -1,10 +1,18 @@
 import { store } from '../core/store';
 
-/** Typed RPC service (transport still a TODO): reached as `Server.stats.playerCount()` on the client. */
-/*@service
+/** Typed RPC service: reached as `Server.stats.playerCount()` on the client (POSTs /__toil_rpc). */
+@service
 class Stats {
     @remote
     public playerCount(): i32 {
         return store.size;
     }
-}*/
+
+    // @auth on a @remote: the RPC dispatcher must reject with 401 when there is no valid session,
+    // exactly like an @auth @rest route (the guard is compiler-injected into __rpcDispatch).
+    @remote
+    @auth
+    public secretCount(): i32 {
+        return store.size;
+    }
+}

package/examples/basic/server/services/remotes.ts

@@ -1,7 +1,13 @@
 /** Free `@remote` functions: callable as `Server.<name>()` on the client. */
 
 /** `Server.ping(n)` on the client. */
-/*@remote
+@remote
 function ping(n: i32): i32 {
     return n + 1;
-}*/
+}
+
+/** `Server.echoParts(parts)` — exercises the `Uint8Array[]` arg + result wire (writeBytes/readBytes loop). */
+@remote
+function echoParts(parts: Uint8Array[]): Uint8Array[] {
+    return parts;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "toiljs",
     "type": "module",
-    "version": "0.0.69",
+    "version": "0.0.70",
     "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.44",
+        "toilscript": "^0.1.45",
         "typescript-eslint": "^8.62.0",
         "vite": "^8.1.0",
         "vite-imagetools": "^10.0.1",
@@ -145,6 +145,7 @@
         "prettier": ">=3.0.0",
         "react": ">=18.0.0",
         "react-dom": ">=18.0.0",
+        "toilscript": ">=0.1.45",
         "typescript": ">=6.0.0"
     },
     "overrides": {

package/server/runtime/exports/index.ts

@@ -16,6 +16,7 @@
 import { Server } from '../env/Server';
 import { decodeRequest, encodeResponse } from '../envelope';
 import { Response } from '../response';
+import { Rpc } from '../rpc/Rpc';
 
 // Ensure the cookie library is in every build so its `@global` types
 // (`Cookie`, `Cookies`, `SecureCookies`, ...) register as ambient globals,
@@ -57,8 +58,14 @@ export function handle(req_ofs: i32, req_len: i32): i64 {
         // can read its cookies with no argument. Cleared in resetCurrentHandler.
         Server.currentRequest = req;
         const handler = Server.currentHandler();
+        // Run the handler lifecycle hooks around BOTH the RPC and the normal path, so an app that does
+        // central bookkeeping/auth in onRequestStarted is not silently bypassed for /__toil_rpc.
         handler.onRequestStarted(req);
-        resp = handler.handle(req);
+        // Reserved RPC endpoint: a `POST /__toil_rpc` carrying a `toil-rpc` method id dispatches to the
+        // registered @service/@remote method (which applies its own @auth/@ratelimit guards); any other
+        // request returns null here and falls through to the normal handler.
+        const rpcHit = Rpc.dispatch(req);
+        resp = rpcHit != null ? rpcHit : handler.handle(req);
         handler.onRequestCompleted(req, resp);
     }
 

package/server/runtime/index.ts

@@ -29,6 +29,7 @@ export { SlotValues, SlotValue, HtmlBuilder } from './ssr/slots';
 
 // HTTP layer (`@rest` / `@route`).
 export { Rest, RestRegistry, RouteFn } from './rest/Rest';
+export { Rpc, RpcRegistry, RpcFn, RPC_PATH, RPC_HEADER } from './rpc/Rpc';
 export { RouteContext } from './rest/RouteContext';
 export { matchRoute } from './rest/match';
 export { RestHandler } from './rest/RestHandler';

package/server/runtime/rpc/Rpc.ts

@@ -0,0 +1,66 @@
+/**
+ * The auto-populated RPC dispatcher. Every `@service` method and free `@remote`
+ * function self-registers here at module init (compiler-injected), keyed by a
+ * deterministic method id (FNV-1a of `"Service.method"` / `"fnName"` — the same
+ * hash the generated client sends). The wasm `handle` export dispatches a
+ * reserved `POST /__toil_rpc` (method id in the `toil-rpc` header, `@data`-encoded
+ * args in the body) to the matching method and returns its `@data`-encoded
+ * result. Mirrors `Rest` (../rest/Rest.ts); calls are STATELESS — a fresh service
+ * instance per call, exactly like a `@rest` controller.
+ */
+
+import { Method, Request } from '../request';
+import { Response } from '../response';
+
+/** The reserved path a generated RPC client POSTs to. */
+export const RPC_PATH: string = '/__toil_rpc';
+/** The request header carrying the decimal `u32` method id. */
+export const RPC_HEADER: string = 'toil-rpc';
+
+/** A registered RPC method: takes the encoded-args body and returns a `Response` - the encoded result
+ *  (`Response.bytes`) on success, or a guard's `401`/`429` when the method carries `@auth`/`@ratelimit`.
+ *  The compiler injects these (see toilscript injectService/injectRemote). */
+export type RpcFn = (body: Uint8Array) => Response;
+
+export class RpcRegistry {
+    private ids: Array<u32> = new Array<u32>();
+    private fns: Array<RpcFn> = new Array<RpcFn>();
+
+    /** Compiler-injected: register one `@service` method / `@remote` function by id. Not for direct use. */
+    register(id: u32, fn: RpcFn): void {
+        this.ids.push(id);
+        this.fns.push(fn);
+    }
+
+    /**
+     * Dispatch a reserved `POST /__toil_rpc` call to its registered method. Returns `null` for ANY
+     * non-RPC request (wrong method, wrong path, no id header) so the caller falls through to the
+     * normal handler; returns a `400` for a well-formed RPC call whose id is unknown.
+     */
+    dispatch(req: Request): Response | null {
+        if (req.method != Method.POST) return null;
+        let path = req.path;
+        const q = path.indexOf('?');
+        if (q >= 0) path = path.substring(0, q);
+        if (path != RPC_PATH) return null;
+        const raw = req.header(RPC_HEADER);
+        if (raw == null) return null;
+        const id = U32.parseInt(raw, 10);
+        for (let i = 0, n = this.ids.length; i < n; i++) {
+            if (this.ids[i] == id) {
+                // The injected dispatcher returns the full Response (encoded result, or a 401/429 from
+                // its @auth/@ratelimit guard).
+                return this.fns[i](req.body);
+            }
+        }
+        return Response.badRequest('unknown rpc method');
+    }
+
+    /** Number of registered methods (diagnostics / tests). */
+    get size(): i32 {
+        return this.ids.length;
+    }
+}
+
+/** The process-wide RPC dispatcher singleton. */
+export const Rpc: RpcRegistry = new RpcRegistry();

package/src/client/rpc.ts

@@ -3,14 +3,12 @@
  * the toilscript server build into the project's `shared/server.ts`
  * (`declare global { const Server }`); this module is the runtime behind it.
  *
- * Two surfaces live under `Server`:
- *   - `Server.REST.<controller>.<route>(args)` is a WORKING fetch client. The
- *     generated `shared/server.ts` attaches it to `globalThis.__toilRest` when
- *     imported; the proxy below surfaces it under `Server.REST`.
- *   - `Server.<service>.<method>()` (RPC) is not wired yet, so any call throws.
- *     The pipeline (tags -> generated types -> proxy) is in place; only the
- *     network dispatch is a TODO. Build the server (`npm run build:server`) to
- *     (re)generate the typed surface.
+ * Three surfaces live under `Server`, all attached by the generated `shared/server.ts` on import:
+ *   - `Server.REST.<controller>.<route>(args)` - a fetch client (`globalThis.__toilRest`).
+ *   - `Server.Stream.<class>.connect()` - the stream client (`globalThis.__toilStream`).
+ *   - `Server.<service>.<method>(args)` and a free `Server.<remote>(args)` - the RPC client
+ *     (`globalThis.__toilRpc`): each POSTs to `/__toil_rpc` with a method id and @data-encoded args.
+ * Build the server (`npm run build:server`) to (re)generate the typed surface + attach the clients.
  */
 
 /** A recursive proxy that throws on call, used when the REST client hasn't loaded. */
@@ -18,7 +16,7 @@ function restMissingStub(path: string): unknown {
     const call = (): never => {
         throw new Error(
             `toiljs REST: ${path}() is unavailable. The generated REST client has not loaded - ` +
-                `import a type from your 'shared/server' (so the client attaches), or run 'npm run build:server'.`,
+                `run 'npm run build:server' to generate shared/server.ts; the client then attaches automatically.`,
         );
     };
     return new Proxy(call, {
@@ -37,7 +35,7 @@ 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'.`,
+                `run 'npm run build:server' to generate shared/server.ts; the client then attaches automatically.`,
         );
     };
     return new Proxy(call, {
@@ -55,8 +53,8 @@ function streamMissingStub(path: string): unknown {
 function rpcStub(path: string): unknown {
     const call = (): never => {
         throw new Error(
-            `toiljs RPC: ${path}() is not available yet. The client<->server transport ` +
-                `is not wired; this is a generated stub. Remote calls will work once transport lands.`,
+            `toiljs RPC: ${path}() is unavailable. The generated RPC client has not loaded - ` +
+                `run 'npm run build:server' to generate shared/server.ts; the client then attaches automatically.`,
         );
     };
     return new Proxy(call, {
@@ -73,6 +71,12 @@ function rpcStub(path: string): unknown {
                 const stream = (globalThis as { __toilStream?: unknown }).__toilStream;
                 return stream !== undefined ? stream : streamMissingStub('Server.Stream');
             }
+            // `Server.<service>` / `Server.<remote>` surface the generated RPC client. Its top-level
+            // keys are the @service names (-> a `{ method }` object) and free @remote functions.
+            if (path === 'Server') {
+                const rpc = (globalThis as { __toilRpc?: Record<string, unknown> }).__toilRpc;
+                if (rpc !== undefined && prop in rpc) return rpc[prop];
+            }
             return rpcStub(`${path}.${prop}`);
         },
         apply() {
@@ -86,3 +90,8 @@ function rpcStub(path: string): unknown {
  * come from the generated `shared/server.ts`. toiljs assigns this to `globalThis`.
  */
 export const Server: unknown = rpcStub('Server');
+
+// Back the generated `declare global { const Server }` (shared/server.ts) with a runtime value, so an
+// app reaches `Server.REST` / `Server.Stream.<Name>` via the global without an import (the design note
+// above). Idempotent - the proxy is a singleton; importing `toiljs/client` evaluates this once.
+(globalThis as Record<string, unknown>).Server = Server;