toiljs 0.0.68 → 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/derive.md

@@ -0,0 +1,159 @@
+# Derive (materialized views)
+
+`@derive` precomputes a read-optimized **view** from your data so reads stay
+fast and never scan. A request handler (`@get` runs as a *query*, `@post`/`@put`/
+`@delete` as an *action*) is not allowed to scan, reading "the latest N events"
+or "every member of a set" could fan out across unbounded rows, so those scans
+are barred on the request path. A `@derive` does the scan **off** the request
+path: it folds your event log / counters into a `View`, and your route serves
+that view with a single keyed read.
+
+```ts
+@database
+class GuestbookDb {
+  @collection static entries: Events<GuestKey, GuestEntry>;
+  @collection static totals: Counter<GuestKey>;
+  @collection static book: View<GuestKey, GuestbookView>;
+
+  // Recompute the view from the sources. Runs after a signature is written
+  // (and when a box first loads). A derive MAY scan + publish; a route may not.
+  @derive
+  recompute(): void {
+    const key = new GuestKey('main');
+    const view = new GuestbookView();
+    view.total = GuestbookDb.totals.get(key);      // counter read
+    view.entries = GuestbookDb.entries.latest(key, 10); // scan, allowed here
+    GuestbookDb.book.publish(key, view);           // publish the materialized view
+  }
+}
+```
+
+## Why a derive
+
+ToilDB gates every data op by the *function kind* it runs under:
+
+- **query** (`@get`/`@head`) and **action** (`@post`/`@put`/`@patch`/`@delete`)
+  may do keyed reads and (actions only) writes, but **not scans**
+  (`events.latest`, `membership.list`).
+- **derive** may do everything a read can, **plus** scans, plus
+  `view.publish`/`append`/`counter.add`.
+
+So if a page needs "the 10 newest entries" or "the leaderboard", you cannot read
+that directly in the `@get`. Instead a `@derive` builds it once into a `View`,
+and the `@get` reads the view by key, which is not a scan.
+
+## Declaring a derive
+
+A derive is a method on your `@database` class, alongside the collections it
+reads and the `View` it writes:
+
+```ts
+@database
+class MyDb {
+  @collection static events: Events<Key, Fact>;   // a source
+  @collection static home: View<Key, HomePage>;    // the materialized view
+
+  @derive
+  rebuild(): void {
+    // read sources, build the value, publish it
+  }
+}
+```
+
+Rules:
+
+- A `@derive` method takes **no arguments and returns `void`**.
+- A `@database` may declare **multiple** `@derive` methods; each is run
+  independently.
+- The view value (`HomePage` above) and the key are ordinary `@data` types, so
+  they round-trip through the codec like any other stored value.
+
+## `View<K, V>`
+
+A `View` is a published, read-optimized projection. Its API:
+
+```ts
+view.get(key)       // V | null   - the published view, or null if none yet
+view.require(key)   // V          - like get, but traps if nothing is published
+view.publish(key, value) // void  - overwrite the view (derive/job only)
+```
+
+`publish` is only allowed from a `@derive` (or a `@job`); the host assigns the
+version so a later publish always supersedes an earlier one. `get`/`require` are
+plain keyed reads, allowed from any handler, including a `@get` route.
+
+## When derives run
+
+You never call a derive yourself. The runtime runs it for you:
+
+- **After a write to a source.** When a request writes one of a database's
+  source collections (an `events.append`/`append_once`, a `counter.add`, or a
+  record `create`/`patch`), that database's derives run right after the response
+  is produced, so the view reflects the new data on the next read. Many writes to
+  one database in a single request coalesce into one recompute.
+- **On box load.** When a server box starts or hot-reloads (or the underlying
+  source data changed out of band), the views are rebuilt from their sources
+  before the first read is served. This is also where a value type's `@migrate`
+  runs against old stored events, as the derive re-reads and republishes them.
+
+A derive's own writes (its `view.publish`) never re-trigger it.
+
+The same code runs under `toiljs dev` (the in-process emulator) and on the
+production edge, no flags or wiring to change.
+
+## Reading a view from a route
+
+The route just reads the view by key, which is a non-scan read and so is legal in
+a `@get`:
+
+```ts
+@rest('guestbook')
+class Guestbook {
+  @get('/')
+  list(): GuestbookView {
+    const key = new GuestKey('main');
+    const view = GuestbookDb.book.get(key);
+    return view == null ? new GuestbookView() : view; // empty until first publish
+  }
+
+  @post('/')
+  sign(input: NewMessage): GuestbookView {
+    const key = new GuestKey('main');
+    GuestbookDb.entries.append(key, new GuestEntry(input.author, input.message, 0));
+    GuestbookDb.totals.add(key, 1);
+    // The @derive republishes `book` right after this action returns, so the
+    // entries list is served by GET. The action just acks with the new total
+    // (a counter read is allowed here; a scan is not).
+    const view = new GuestbookView();
+    view.total = GuestbookDb.totals.get(key);
+    return view;
+  }
+}
+```
+
+## How it fits together (the guestbook)
+
+The `examples/basic` guestbook is the end-to-end demo:
+
+1. `POST /guestbook` (an action) appends the signature to an `Events` stream and
+   bumps a `Counter`. It returns the running total, but it does **not** read the
+   entry list (that would be a scan).
+2. The runtime then runs `@derive recompute()` under the derive kind: it scans
+   `entries.latest(...)`, reads the `totals` counter, and `publish`es a fresh
+   `GuestbookView`.
+3. `GET /guestbook` (a query) reads `book.get(...)`, a single keyed read, and
+   returns the precomputed total + newest entries.
+
+Sign twice and the total climbs across requests, because the data lives in
+ToilDB (and its view), not in module memory.
+
+## Notes
+
+- A derive **recomputes** the view from whatever its method reads (here, the
+  latest 10 events). It is a fresh recompute on each trigger, so it suits views
+  built from a bounded read (latest N, a counter total, a small set). Folding an
+  unbounded full event log incrementally is a separate, more advanced pattern.
+- Because publishes are last-writer-wins and a derive recomputes from the source
+  of truth, a view always converges to a correct snapshot of its sources.
+- See also: [`data.md`](data.md) for `@data` value types, and the ToilDB host
+  ABI for the exact `derive_run` / `toildb.derives` contract.

package/docs/index.md

@@ -27,4 +27,4 @@ toilscript-to-WebAssembly server target.
 
 See [routing.md](./routing.md), [client.md](./client.md), [styling.md](./styling.md),
 [server.md](./server.md), [ssr.md](./ssr.md), [rpc.md](./rpc.md), [tiers.md](./tiers.md),
-[streams.md](./streams.md), [daemon.md](./daemon.md), [cli.md](./cli.md).
+[streams.md](./streams.md), [daemon.md](./daemon.md), [derive.md](./derive.md), [cli.md](./cli.md).

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
 
@@ -117,30 +116,62 @@ build/server/release-cold.wasm     # L4 daemon     (exports: daemon_start, sched
 
 See [Tiers](./tiers.md) for how the three artifacts map to the deployment tiers.
 
-## What runs today
+## Reading and replying to messages
 
-The stream lifecycle hooks (`@connect` / `@message` / `@close` / `@disconnect`)
-run **today**, and this proves a resident box keeps state across events - that is
-exactly what the `Echo` example demonstrates by counting frames.
-
-Reading the inbound frame **bytes** and replying is the **next increment**, not
-yet available. That bridge is the `StreamPacket` / `StreamOutbound` API and the
-typed `Server.STREAM.echo.connect()` client. The intended shape, once it lands:
+`@message` receives the inbound frame as a `StreamPacket` and returns a
+`StreamOutbound`. `StreamPacket.bytes()` is the raw frame payload;
+`StreamOutbound.reply(bytes)` stages one frame back to the client (return an empty
+`StreamOutbound` to accept the frame without replying). The same resident box
+handles every frame, so state on its fields persists across messages.
 
 ```ts
-@message reply(packet: StreamPacket): StreamOutbound {
+@message
+reply(packet: StreamPacket): StreamOutbound {
   return StreamOutbound.reply(packet.bytes());   // echo the bytes back
 }
 ```
 
+## Typed messages
+
+By default a `@message` payload is **raw bytes**. Opt into a decoded `@data` value
+with `@stream({ message: T })`: the `@message` hook then receives the named `@data`
+class, decoded from the frame for you. The reply stays raw (`StreamOutbound`).
+
+```ts
+@data
+class ChatMsg { text: string = ''; }
+
+@stream({ message: ChatMsg })
+class Chat {
+  @message
+  onMessage(msg: ChatMsg): StreamOutbound {       // decoded @data, not raw bytes
+    return StreamOutbound.reply(new TextEncoder().encode(msg.text));
+  }
+}
+```
+
+## The client
+
+A `@stream` class is reachable from the browser as `Server.Stream.<ClassName>`. The
+typed client is generated into `shared/server.ts` (the same place `Server.REST`
+lands), so no manual wiring is needed. `connect()` opens a WebSocket to the class's
+route and resolves a channel:
+
 ```ts
-const stream = await Server.STREAM.echo.connect();
-stream.send(new TextEncoder().encode('hello'));
+const chat = await Server.Stream.Chat.connect();
+chat.onMessage((bytes) => { /* a reply frame, always raw bytes */ });
+chat.send(new ChatMsg('hello'));   // a typed stream: send() encodes the @data for you
+chat.onClose((code) => { /* a 0x02xx stream close code */ });
+chat.close();
 ```
 
-Until then, the hooks run on the connection lifecycle and you observe state
-through fields, as `Echo` does. See the comments in
-`examples/streams/server/streams/Echo.ts` for the authoritative note.
+- The channel key is the **class name** (`Server.Stream.Chat`); it connects to the
+  class's mount route (`/Chat`).
+- A **raw** `@stream` channel sends `Uint8Array`; a **typed** `@stream({ message: T })`
+  channel sends the `@data` class and encodes it on the wire for you.
+- The inbound reply is **always raw bytes** - the server's `StreamOutbound` is raw.
+- `connect()` resolves once the upgrade completes; a `@connect` reject (or any
+  later server close) surfaces through `onClose(code)`.
 
 ---
 

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.68",
+    "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.43",
+        "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();