toiljs 0.0.68 → 0.0.70

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;

package/src/client/stream/client.ts

@@ -1,9 +1,12 @@
 /**
  * Client runtime for the typed `@stream` channel (doc 08 section 8.2). `Server.Stream.<Class>.connect(path?)`
- * opens a browser `WebSocket` to the class's `route` (same origin) and returns a channel:
- * `onMessage` / `send` / `onClose` / `close`. RAW byte mode (the default `@message` bridge); the typed
- * `@data` codec (`messageMode = 'data'`) is a follow-up. The generated `shared/server.ts` (toilscript
- * hot pass) attaches `makeStreamClient(routes)` to `globalThis.__toilStream`, and `Server.Stream`
+ * opens a browser `WebTransport` session to the class's `route` on the production edge (an `https://`
+ * stream-tier origin), or a `WebSocket` against the dev server (a `ws(s)://` origin), and returns a channel:
+ * `onMessage` / `send` / `onClose` / `close`. A raw `@stream` channel sends `Uint8Array`; a typed
+ * `@stream({ message: T })` channel sends the `@data` class and encodes it on send (the per-class
+ * encoder the generated module passes). The inbound reply is always raw bytes. The generated
+ * `shared/server.ts` (toilscript hot pass) attaches `makeStreamClient(routes, undefined, encoders)` to
+ * `globalThis.__toilStream`, and `Server.Stream`
  * (`rpc.ts`) surfaces it - the same wiring the REST client uses via `globalThis.__toilRest`.
  */
 
@@ -42,10 +45,13 @@ function connectStream<TSend = Uint8Array>(
         let opened = false;
         let messageCb: ((data: Uint8Array) => void) | undefined;
         let closeCb: ((code: number) => void) | undefined;
+        const pending: Uint8Array[] = [];
 
         const channel: StreamChannel<TSend> = {
             onMessage: (cb): void => {
                 messageCb = cb;
+                for (const m of pending) cb(m);
+                pending.length = 0;
             },
             onClose: (cb): void => {
                 closeCb = cb;
@@ -54,7 +60,11 @@ function connectStream<TSend = Uint8Array>(
                 if (ws.readyState !== WebSocket.OPEN) return;
                 // A typed channel encodes the @data message; a raw channel sends the bytes as-is.
                 const bytes = encode ? encode(data as never) : (data as unknown as Uint8Array);
-                ws.send(bytes as BufferSource);
+                try {
+                    ws.send(bytes as BufferSource);
+                } catch {
+                    /* socket transitioned OPEN -> CLOSING between the readyState check and send */
+                }
             },
             close: (): void => {
                 ws.close();
@@ -66,7 +76,12 @@ function connectStream<TSend = Uint8Array>(
             resolve(channel);
         });
         ws.addEventListener('message', (event: MessageEvent) => {
-            if (event.data instanceof ArrayBuffer) messageCb?.(new Uint8Array(event.data));
+            if (!(event.data instanceof ArrayBuffer)) return;
+            const bytes = new Uint8Array(event.data);
+            // Buffer a reply that arrives before onMessage() registers (mirror the WebTransport path),
+            // so an eager server reply is not silently dropped.
+            if (messageCb) messageCb(bytes);
+            else pending.push(bytes);
         });
         ws.addEventListener('close', (event: CloseEvent) => {
             if (!opened) reject(new Error(`stream connect failed (closed ${String(event.code)})`));
@@ -78,12 +93,125 @@ function connectStream<TSend = Uint8Array>(
     });
 }
 
+/** Open a browser `WebTransport` session to `url` (an `https://` stream-tier origin) and resolve a
+ *  channel once the session is ready. The browser drives the QUIC handshake, H3 Extended-CONNECT, and
+ *  the RFC 9297 Quarter-Stream-ID datagram framing, so `send`/`onMessage` deal in raw bytes (no manual
+ *  prefix). Rejects if the session fails to open (wrong node / unreachable / cert); a server close AFTER
+ *  open surfaces via `onClose(code)`. This is the PRODUCTION transport - the L2/L3 edge is
+ *  WebTransport-only; the dev server uses the `connectStream` WebSocket above. */
+function connectStreamWT<TSend = Uint8Array>(
+    url: string,
+    encode?: (msg: never) => Uint8Array,
+): Promise<StreamChannel<TSend>> {
+    return new Promise((resolve, reject) => {
+        if (!('WebTransport' in globalThis)) {
+            reject(new Error('WebTransport is not available in this browser'));
+            return;
+        }
+        let transport: WebTransport;
+        try {
+            transport = new WebTransport(url);
+        } catch (e) {
+            reject(e instanceof Error ? e : new Error(String(e)));
+            return;
+        }
+        let messageCb: ((data: Uint8Array) => void) | undefined;
+        let closeCb: ((code: number) => void) | undefined;
+        let writer: WritableStreamDefaultWriter<Uint8Array> | undefined;
+        let opened = false;
+        const pending: Uint8Array[] = [];
+
+        const channel: StreamChannel<TSend> = {
+            onMessage: (cb): void => {
+                messageCb = cb;
+                for (const m of pending) cb(m);
+                pending.length = 0;
+            },
+            onClose: (cb): void => {
+                closeCb = cb;
+            },
+            send: (data): void => {
+                if (!writer) return;
+                const bytes = encode ? encode(data as never) : (data as unknown as Uint8Array);
+                // Fire-and-forget; a write that rejects (transport closing / backpressure) is surfaced
+                // via onClose, so swallow it here to avoid an unhandled promise rejection.
+                void writer.write(bytes).catch(() => {});
+            },
+            close: (): void => {
+                try {
+                    transport.close();
+                } catch {
+                    /* already closing */
+                }
+            },
+        };
+
+        // A close AFTER open (guest reject, idle sweep, server shutdown) reports through onClose; a
+        // failure BEFORE open rejects the connect() promise via the `ready` catch below.
+        transport.closed
+            .then((info) => {
+                if (opened) closeCb?.(info?.closeCode ?? 0);
+            })
+            .catch(() => {
+                if (opened) closeCb?.(1);
+            });
+
+        transport.ready
+            .then(() => {
+                opened = true;
+                writer = transport.datagrams.writable.getWriter();
+                const reader = transport.datagrams.readable.getReader();
+                void (async (): Promise<void> => {
+                    try {
+                        for (;;) {
+                            const { value, done } = await reader.read();
+                            if (done) break;
+                            const bytes =
+                                value instanceof Uint8Array
+                                    ? value
+                                    : new Uint8Array(value as ArrayBufferLike);
+                            if (messageCb) messageCb(bytes);
+                            else pending.push(bytes);
+                        }
+                    } catch {
+                        /* read loop ended on session close */
+                    }
+                })();
+                resolve(channel);
+            })
+            .catch((e) => reject(e instanceof Error ? e : new Error(String(e))));
+    });
+}
+
+/** Pick the transport by origin scheme: `https://` -> WebTransport (the production L2/L3 edge),
+ *  `ws(s)://` -> WebSocket (the dev server). The generated `shared/server.ts` sets the scheme per build
+ *  (edge: `https://wt.<tenant>`; dev: same-origin `wss://`). */
+function openChannel<TSend = Uint8Array>(
+    url: string,
+    encode?: (msg: never) => Uint8Array,
+): Promise<StreamChannel<TSend>> {
+    return url.startsWith('https://')
+        ? connectStreamWT<TSend>(url, encode)
+        : connectStream<TSend>(url, encode);
+}
+
 /** The same-origin WebSocket base (`ws://` / `wss://` per the page protocol). */
 function defaultOrigin(): string {
     const loc = globalThis.location;
     return `${loc.protocol === 'https:' ? 'wss:' : 'ws:'}//${loc.host}`;
 }
 
+/** Resolve the stream-tier origin when the generated client passes none. A deploy/runtime override -
+ *  `globalThis.__TOIL_STREAM_ORIGIN__` (e.g. `"https://wt.dacely.com"`, the production L2/L3 edge) -
+ *  wins; otherwise fall back to the same-origin WebSocket base (the dev server). The edge override is
+ *  `https://` so `openChannel` selects WebTransport; the dev fallback is `ws(s)://` so it selects
+ *  WebSocket. This is how a deployed app points at its `wt.<tenant>` tier without the build knowing it. */
+function resolveStreamOrigin(): string {
+    const override = (globalThis as { __TOIL_STREAM_ORIGIN__?: unknown }).__TOIL_STREAM_ORIGIN__;
+    if (typeof override === 'string' && override.length > 0) return override;
+    return defaultOrigin();
+}
+
 /**
  * Build the `Server.Stream` client from the generated route map (`{ ClassName: route }`). `origin`
  * defaults to the page origin. `encoders` carries one `@data` encoder per typed `@stream({ message: T })`
@@ -95,12 +223,14 @@ export function makeStreamClient(
     origin?: string,
     encoders?: Record<string, (msg: never) => Uint8Array>,
 ): StreamClient {
-    const base = origin ?? defaultOrigin();
     const client: StreamClient = {};
     for (const [name, route] of Object.entries(routes)) {
         const encode = encoders?.[name];
         client[name] = {
-            connect: (path = ''): Promise<StreamChannel> => connectStream(`${base}${route}${path}`, encode),
+            // Resolve the origin LAZILY, per connect() - so a deploy/app that sets
+            // `__TOIL_STREAM_ORIGIN__` after this module loads is still honoured.
+            connect: (path = ''): Promise<StreamChannel> =>
+                openChannel(`${origin ?? resolveStreamOrigin()}${route}${path}`, encode),
         };
     }
     return client;