@tokamakdev/tok 0.1.1-beta.83 → 0.1.1-beta.84

package/README.md

@@ -12,7 +12,7 @@ npx tok targets
 | Entry | Contents |
 | --- | --- |
 | `@tokamakdev/tok` | The `Config` type of the Vite plugin's options |
-| `@tokamakdev/tok/events` | The app's events: `onStart`, `onResume` and `onSuspend` |
+| `@tokamakdev/tok/events` | The app's events, `onStart`, `onResume` and `onSuspend`, and `getLifecycleStage()` |
 | `@tokamakdev/tok/vite` | The Vite plugin, `tokamak()` |
 | `tok` | The CLI |
 
@@ -31,8 +31,9 @@ export default defineConfig({
 
 It does nothing unless `tok` runs the build or development command. Then it
 makes the entry Worker import `src/tokamak.ts` and export the entrypoint the
-runtime delivers events through, and in development it delivers the device's
-events to the development Worker through Cloudflare's dev registry.
+runtime delivers events through. In development it delivers the device's
+events to the development Worker through Cloudflare's dev registry, and passes
+the development Worker's plugin calls to the device.
 
 The package installs the `tok` binary for the current machine through an
 optional dependency (`@tokamakdev/tok-darwin-arm64`, `-darwin-x64`,

package/dist/dev-socket.d.mts

@@ -1,10 +1,23 @@
+/** The header that carries the device's session token, which `tok dev`'s relay forwards. */
+export declare const SESSION_HEADER = "x-tokamak-session";
+/** A plugin's result, as the page's native transport receives it. */
+export interface PluginResult {
+    value?: unknown;
+    error?: {
+        name: string;
+        message: string;
+    };
+    done: boolean;
+}
 /** The loopback server the device's dev WebSocket reaches through `tok dev`'s relay. */
 export interface DevSocket {
     readonly port: number;
     close(): Promise<void>;
 }
 /**
- * Listens on a loopback port for dev WebSockets that carry `token`, and delivers each event they
- * carry to `TokamakEvents` in the development Worker `workerName`, replying with its reply.
+ * Listens on a loopback port, with `token`, for the device's dev WebSocket and the development
+ * Worker's plugin calls. Delivers each event the device sends to `TokamakEvents` in the
+ * development Worker `workerName`, and passes each plugin call the Worker posts to `/call` or
+ * `/subscribe` to the device.
  */
 export declare function openDevSocket(workerName: string | undefined, token: string | undefined): Promise<DevSocket>;

package/dist/dev-socket.mjs

@@ -2,8 +2,10 @@ import http from "node:http";
 import { createRequire } from "node:module";
 import { pathToFileURL } from "node:url";
 import { WebSocketServer } from "ws";
-/** The header `tok dev`'s relay forwards with the device's session token. */
-const SESSION_HEADER = "x-tokamak-session";
+/** The header that carries the device's session token, which `tok dev`'s relay forwards. */
+export const SESSION_HEADER = "x-tokamak-session";
+/** How long a plugin call waits for the device to connect. */
+const CONNECT_TIMEOUT = 10_000;
 /** Calls `TokamakEvents` in the Worker its `TOKAMAK` service binding names, through the dev registry. */
 const CALLER = `export default {
   async fetch(request, env) {
@@ -17,19 +19,32 @@ const CALLER = `export default {
   },
 };`;
 /**
- * Listens on a loopback port for dev WebSockets that carry `token`, and delivers each event they
- * carry to `TokamakEvents` in the development Worker `workerName`, replying with its reply.
+ * Listens on a loopback port, with `token`, for the device's dev WebSocket and the development
+ * Worker's plugin calls. Delivers each event the device sends to `TokamakEvents` in the
+ * development Worker `workerName`, and passes each plugin call the Worker posts to `/call` or
+ * `/subscribe` to the device.
  */
 export async function openDevSocket(workerName, token) {
     const worker = new DevWorker(workerName);
-    const server = http.createServer((_request, response) => response.writeHead(426).end());
+    const device = new Device();
+    const server = http.createServer((request, response) => {
+        if (!token || request.headers[SESSION_HEADER] !== token) {
+            response.writeHead(401).end();
+            return;
+        }
+        if (request.method === "POST" && (request.url === "/call" || request.url === "/subscribe")) {
+            void forward(device, request, response);
+            return;
+        }
+        response.writeHead(request.method === "GET" ? 426 : 404).end();
+    });
     const sockets = new WebSocketServer({ noServer: true });
     server.on("upgrade", (request, socket, head) => {
         if (!token || request.headers[SESSION_HEADER] !== token) {
             socket.end("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
             return;
         }
-        sockets.handleUpgrade(request, socket, head, (websocket) => serve(websocket, worker));
+        sockets.handleUpgrade(request, socket, head, (websocket) => serve(websocket, worker, device));
     });
     await new Promise((resolve, reject) => {
         server.once("error", reject);
@@ -40,21 +55,65 @@ export async function openDevSocket(workerName, token) {
         async close() {
             for (const websocket of sockets.clients)
                 websocket.terminate();
+            server.closeAllConnections();
             server.close();
             await worker.dispose();
         },
     };
 }
-function serve(websocket, worker) {
+function serve(websocket, worker, device) {
+    device.connect(websocket);
     // The device opens another dev WebSocket after this one fails.
     websocket.on("error", () => websocket.terminate());
     websocket.on("message", (data) => {
         const message = parseMessage(String(data));
+        if (message?.type === "result") {
+            device.receive(message.id, message.result);
+            return;
+        }
         if (message?.type !== "event")
             return;
         worker.dispatch(message.name, message.event).then((reply) => websocket.send(JSON.stringify({ type: "reply", id: message.id, reply })), (error) => websocket.send(JSON.stringify({ type: "error", id: message.id, message: String(error) })));
     });
 }
+/**
+ * Passes the plugin call `request` carries to the device. A call's response is its result; a
+ * subscription's streams each result as a line of JSON until one is done, and closing it ends the
+ * subscription.
+ */
+async function forward(device, request, response) {
+    let call;
+    try {
+        call = JSON.parse(await readBody(request));
+    }
+    catch {
+        response.writeHead(400).end();
+        return;
+    }
+    response.writeHead(200, { "content-type": "application/json" });
+    if (request.url === "/call") {
+        response.end(JSON.stringify(await new Promise((resolve) => device.send("call", call, resolve))));
+        return;
+    }
+    response.flushHeaders();
+    const cancel = device.send("subscribe", call, (result) => {
+        response.write(`${JSON.stringify(result)}\n`);
+        if (result.done)
+            response.end();
+    });
+    response.once("close", () => {
+        if (!response.writableEnded)
+            cancel();
+    });
+}
+function readBody(request) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        request.on("data", (chunk) => chunks.push(chunk));
+        request.once("end", () => resolve(Buffer.concat(chunks).toString()));
+        request.once("error", reject);
+    });
+}
 function parseMessage(text) {
     try {
         return JSON.parse(text);
@@ -63,6 +122,82 @@ function parseMessage(text) {
         return undefined;
     }
 }
+/** A failed result, which ends a subscription. */
+function failure(name, message) {
+    return { error: { name, message }, done: true };
+}
+/** The device, through its latest dev WebSocket, and the plugin calls waiting for its results. */
+class Device {
+    #socket;
+    #connected = [];
+    #nextId = 1;
+    #pending = new Map();
+    connect(socket) {
+        this.#socket = socket;
+        for (const connected of this.#connected.splice(0))
+            connected();
+        socket.once("close", () => {
+            if (this.#socket === socket)
+                this.#socket = undefined;
+            for (const [id, pending] of this.#pending) {
+                if (pending.socket !== socket)
+                    continue;
+                this.#pending.delete(id);
+                pending.receive(failure("NetworkError", "The device disconnected"));
+            }
+        });
+    }
+    receive(id, result) {
+        const pending = this.#pending.get(id);
+        if (!pending)
+            return;
+        if (result.done || pending.type === "call")
+            this.#pending.delete(id);
+        pending.receive(result);
+    }
+    /**
+     * Sends a call or subscription once the device is connected, waiting up to 10 seconds for it,
+     * and passes each of its results to `receive`. Returns the function that unsubscribes.
+     */
+    send(type, request, receive) {
+        const id = this.#nextId++;
+        let cancelled = false;
+        void this.#connection().then((socket) => {
+            if (cancelled)
+                return;
+            if (!socket) {
+                receive(failure("NetworkError", "The device is not connected"));
+                return;
+            }
+            this.#pending.set(id, { type, socket, receive });
+            socket.send(JSON.stringify({ type, id, ...request }));
+        });
+        return () => {
+            cancelled = true;
+            const pending = this.#pending.get(id);
+            if (!pending)
+                return;
+            this.#pending.delete(id);
+            pending.socket.send(JSON.stringify({ type: "unsubscribe", id }));
+        };
+    }
+    /** The open dev WebSocket, once the device connects, or undefined after 10 seconds without. */
+    #connection() {
+        if (this.#socket)
+            return Promise.resolve(this.#socket);
+        return new Promise((resolve) => {
+            const connected = () => {
+                clearTimeout(timer);
+                resolve(this.#socket);
+            };
+            const timer = setTimeout(() => {
+                this.#connected.splice(this.#connected.indexOf(connected), 1);
+                resolve(undefined);
+            }, CONNECT_TIMEOUT);
+            this.#connected.push(connected);
+        });
+    }
+}
 /** The development Worker's `TokamakEvents`, called through a Miniflare session started on first use. */
 class DevWorker {
     name;

package/dist/events.d.mts

@@ -6,3 +6,11 @@ export declare const onStart: (listener: import("@tokamakdev/plugin/events").Lis
 export declare const onResume: (listener: import("@tokamakdev/plugin/events").Listener<Readonly<Record<string, never>>, void>) => void;
 /** Runs each time the app moves out of the foreground. */
 export declare const onSuspend: (listener: import("@tokamakdev/plugin/events").Listener<Readonly<Record<string, never>>, void>) => void;
+/** Whether the app is on screen. */
+export type LifecycleStage = "foreground" | "background";
+/**
+ * The app's stage now, which can differ from the last event delivered: an `onSuspend` listener
+ * that runs late reads `"foreground"` once the user has returned. Rejects with
+ * `NotSupportedError` outside a tokamak Worker.
+ */
+export declare function getLifecycleStage(): Promise<LifecycleStage>;

package/dist/events.mjs

@@ -1,3 +1,4 @@
+import { Plugin } from "@tokamakdev/plugin";
 import { defineEvent } from "@tokamakdev/plugin/events";
 /** Runs once per runtime start, including when the system starts the app in the background. */
 export const onStart = defineEvent("start");
@@ -5,3 +6,21 @@ export const onStart = defineEvent("start");
 export const onResume = defineEvent("resume");
 /** Runs each time the app moves out of the foreground. */
 export const onSuspend = defineEvent("suspend");
+/** The functions the runtime answers itself, as the reserved plugin `tokamak`. */
+class Tokamak extends Plugin {
+    constructor() {
+        super("tokamak");
+    }
+    lifecycleStage() {
+        return this.call("lifecycleStage");
+    }
+}
+const tokamak = new Tokamak();
+/**
+ * The app's stage now, which can differ from the last event delivered: an `onSuspend` listener
+ * that runs late reads `"foreground"` once the user has returned. Rejects with
+ * `NotSupportedError` outside a tokamak Worker.
+ */
+export function getLifecycleStage() {
+    return tokamak.lifecycleStage();
+}

package/dist/native.d.mts

@@ -0,0 +1,6 @@
+/**
+ * Defines `__tokamakNativeCall` and `__tokamakNativeListen`, which post to the plugin's loopback
+ * `port` with the session `token`. `waitUntil` keeps each listener's invocation running, as
+ * `waitUntil` from `cloudflare:workers` does.
+ */
+export declare function defineNativeCalls(port: number, token: string, waitUntil: (promise: Promise<unknown>) => void): void;

package/dist/native.mjs

@@ -0,0 +1,73 @@
+// Defines the development Worker's native calls, which reach the device through the tokamak Vite
+// plugin. The plugin's entry Worker transform imports this module in development only.
+/**
+ * Defines `__tokamakNativeCall` and `__tokamakNativeListen`, which post to the plugin's loopback
+ * `port` with the session `token`. `waitUntil` keeps each listener's invocation running, as
+ * `waitUntil` from `cloudflare:workers` does.
+ */
+export function defineNativeCalls(port, token, waitUntil) {
+    const post = async (path, plugin, method, arguments_, signal) => {
+        const response = await fetch(`http://127.0.0.1:${String(port)}${path}`, {
+            method: "POST",
+            headers: { "x-tokamak-session": token },
+            body: JSON.stringify({ plugin, method, arguments: arguments_ }),
+            signal,
+        });
+        if (!response.ok)
+            throw new Error(`the tokamak Vite plugin answered HTTP ${String(response.status)}`);
+        return response;
+    };
+    globalThis.__tokamakNativeCall = async (plugin, method, arguments_ = null) => {
+        let result;
+        try {
+            result = (await (await post("/call", plugin, method, arguments_)).json());
+        }
+        catch (error) {
+            throw networkError(error);
+        }
+        if (result.error)
+            throw new DOMException(result.error.message, result.error.name);
+        return result.value;
+    };
+    globalThis.__tokamakNativeListen = (plugin, method, arguments_, next, error) => {
+        const listening = new AbortController();
+        const deliver = (result) => {
+            try {
+                if (result.error)
+                    error(new DOMException(result.error.message, result.error.name));
+                else
+                    next(result.value);
+            }
+            catch (thrown) {
+                reportError(thrown);
+            }
+        };
+        const listen = async () => {
+            const response = await post("/subscribe", plugin, method, arguments_ ?? null, listening.signal);
+            for await (const result of lines(response))
+                deliver(result);
+        };
+        waitUntil(listen().catch((failure) => {
+            if (!listening.signal.aborted)
+                deliver({ error: networkError(failure), done: true });
+        }));
+        return () => {
+            listening.abort();
+        };
+    };
+}
+/** Each line of `response`'s body, parsed as a result. */
+async function* lines(response) {
+    const decoder = new TextDecoder();
+    let text = "";
+    for await (const chunk of response.body ?? []) {
+        text += decoder.decode(chunk, { stream: true });
+        const complete = text.split("\n");
+        text = complete.pop() ?? "";
+        for (const line of complete)
+            yield JSON.parse(line);
+    }
+}
+function networkError(error) {
+    return new DOMException(`The device could not be reached: ${String(error)}`, "NetworkError");
+}

package/dist/vite.d.mts

@@ -3,8 +3,10 @@ import type { Config } from "./index.mjs";
 /**
  * Reports the app's tokamak configuration, and the development server's
  * address, HTTPS certificate, Worker name and dev socket port, to `tok`, and
- * makes the entry Worker import `module` and export `TokamakEvents`. Without
- * `TOKAMAK_VITE_OUTPUT`, which `tok` sets, it adds no hooks.
+ * makes the entry Worker import `module` and export `TokamakEvents`. In
+ * development, the entry Worker also defines native calls that reach the
+ * device through the dev socket. Without `TOKAMAK_VITE_OUTPUT`, which `tok`
+ * sets, it adds no hooks.
  */
 export declare function tokamak({ module, ...config }?: Config & {
     /**

package/dist/vite.mjs

@@ -9,11 +9,15 @@ const DEFAULT_MODULES = ["src/tokamak.ts", "src/tokamak.js"];
 /** Wrangler configuration files Cloudflare's plugin tries in order. */
 const WRANGLER_FILES = ["wrangler.jsonc", "wrangler.json", "wrangler.toml"];
 const MIDDLEWARE_MODE_ERROR = "Vite is running in middleware mode, so tokamak cannot find the development server's address; tok dev needs Vite's own dev server";
+/** The module that defines the development Worker's native calls. */
+const NATIVE_CALLS = normalizePath(fileURLToPath(new URL("./native.mjs", import.meta.url)));
 /**
  * Reports the app's tokamak configuration, and the development server's
  * address, HTTPS certificate, Worker name and dev socket port, to `tok`, and
- * makes the entry Worker import `module` and export `TokamakEvents`. Without
- * `TOKAMAK_VITE_OUTPUT`, which `tok` sets, it adds no hooks.
+ * makes the entry Worker import `module` and export `TokamakEvents`. In
+ * development, the entry Worker also defines native calls that reach the
+ * device through the dev socket. Without `TOKAMAK_VITE_OUTPUT`, which `tok`
+ * sets, it adds no hooks.
  */
 export function tokamak({ module, ...config } = {}) {
     const output = process.env.TOKAMAK_VITE_OUTPUT;
@@ -30,6 +34,9 @@ export function tokamak({ module, ...config } = {}) {
     const entryIds = new Map();
     /** The entry environments whose input exports `TokamakEvents`. */
     const exporting = new Set();
+    /** The development server's dev socket, once open. */
+    let devSocket;
+    const token = process.env.TOKAMAK_SESSION_TOKEN;
     return [
         {
             name: "tokamak",
@@ -42,20 +49,25 @@ export function tokamak({ module, ...config } = {}) {
                 file = findModule(root, module);
                 writeJson(output, "config.json", { root, config });
             },
-            async configureServer(server) {
-                const httpServer = server.httpServer;
-                // A middleware-mode server beside a reported one, such as the server
-                // Astro syncs content with, leaves the report in place.
-                if (!httpServer) {
-                    if (!fs.existsSync(path.join(output, "server.json"))) {
-                        writeJson(output, "server.json", { error: MIDDLEWARE_MODE_ERROR });
+            // Runs before plugins that load the entry Worker, whose native calls
+            // need the dev socket's port.
+            configureServer: {
+                order: "pre",
+                async handler(server) {
+                    const httpServer = server.httpServer;
+                    // A middleware-mode server beside a reported one, such as the server
+                    // Astro syncs content with, leaves the report in place.
+                    if (!httpServer) {
+                        if (!fs.existsSync(path.join(output, "server.json"))) {
+                            writeJson(output, "server.json", { error: MIDDLEWARE_MODE_ERROR });
+                        }
+                        return;
                     }
-                    return;
-                }
-                const worker = await readWorker(server.config.root);
-                httpServer.once("listening", () => {
-                    openDevSocket(worker?.name, process.env.TOKAMAK_SESSION_TOKEN).then((socket) => {
-                        httpServer.once("close", () => void socket.close());
+                    const worker = await readWorker(server.config.root);
+                    const socket = await openDevSocket(worker?.name, token);
+                    devSocket = socket;
+                    httpServer.once("close", () => void socket.close());
+                    httpServer.once("listening", () => {
                         const urls = server.resolvedUrls;
                         writeJson(output, "server.json", {
                             url: urls?.local[0] ?? urls?.network[0],
@@ -63,8 +75,8 @@ export function tokamak({ module, ...config } = {}) {
                             certificates: endEntityCertificates(server.config.server.https),
                             socketPort: socket.port,
                         });
-                    }, (error) => server.config.logger.error(`tokamak could not open its dev socket: ${String(error)}`));
-                });
+                    });
+                },
             },
             async buildApp(builder) {
                 const environments = Object.values(builder.environments);
@@ -88,7 +100,11 @@ export function tokamak({ module, ...config } = {}) {
                 // In Cloudflare's Worker entry, which dev and build both start from,
                 // this follows the imports of its polyfills and of the app's entry.
                 const imports = file ? `import ${JSON.stringify(file)};\n` : "";
-                return { code: `${code}\n${imports}export { TokamakEvents } from ${JSON.stringify(entrypoint)};\n`, map: null };
+                const native = environment.mode === "dev" && devSocket && token ? nativeCalls(devSocket.port, token) : "";
+                return {
+                    code: `${code}\n${imports}export { TokamakEvents } from ${JSON.stringify(entrypoint)};\n${native}`,
+                    map: null,
+                };
             },
             // A module that registers listeners adds them again each time it
             // evaluates, so when an update re-evaluates one, the registry and every
@@ -114,6 +130,17 @@ export function tokamak({ module, ...config } = {}) {
         },
     ];
 }
+/**
+ * Code that defines the development Worker's native calls on the dev socket's
+ * `port`, with the session `token`, which only the entry Worker's environment
+ * sees.
+ */
+function nativeCalls(port, token) {
+    return `import { waitUntil as __tokamakWaitUntil } from "cloudflare:workers";
+import { defineNativeCalls as __tokamakDefineNativeCalls } from ${JSON.stringify(NATIVE_CALLS)};
+__tokamakDefineNativeCalls(${String(port)}, ${JSON.stringify(token)}, __tokamakWaitUntil);
+`;
+}
 /** `module` and every module that imports it, directly or through others. */
 function withImporters(module) {
     const found = new Set();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamakdev/tok",
-  "version": "0.1.1-beta.83",
+  "version": "0.1.1-beta.84",
   "description": "The tokamak CLI, Vite plugin and app API: build native apps from a Cloudflare Workers codebase",
   "repository": {
     "type": "git",
@@ -39,7 +39,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@tokamakdev/plugin": "0.1.0-beta.83",
+    "@tokamakdev/plugin": "0.1.0-beta.84",
     "ws": "^8.22.0"
   },
   "peerDependencies": {
@@ -64,17 +64,17 @@
     "wrangler": "4.147.0"
   },
   "optionalDependencies": {
-    "@tokamakdev/platform-android-arm64": "0.1.1-beta.83",
-    "@tokamakdev/platform-ios-arm64": "0.1.1-beta.83",
-    "@tokamakdev/platform-ios-simulator-arm64": "0.1.1-beta.83",
-    "@tokamakdev/platform-ios-simulator-x64": "0.1.1-beta.83",
-    "@tokamakdev/platform-macos-arm64": "0.1.1-beta.83",
-    "@tokamakdev/platform-macos-x64": "0.1.1-beta.83",
-    "@tokamakdev/platform-windows-x64": "0.1.1-beta.83",
-    "@tokamakdev/tok-darwin-arm64": "0.1.1-beta.83",
-    "@tokamakdev/tok-darwin-x64": "0.1.1-beta.83",
-    "@tokamakdev/tok-linux-x64": "0.1.1-beta.83",
-    "@tokamakdev/tok-win32-x64": "0.1.1-beta.83"
+    "@tokamakdev/platform-android-arm64": "0.1.1-beta.84",
+    "@tokamakdev/platform-ios-arm64": "0.1.1-beta.84",
+    "@tokamakdev/platform-ios-simulator-arm64": "0.1.1-beta.84",
+    "@tokamakdev/platform-ios-simulator-x64": "0.1.1-beta.84",
+    "@tokamakdev/platform-macos-arm64": "0.1.1-beta.84",
+    "@tokamakdev/platform-macos-x64": "0.1.1-beta.84",
+    "@tokamakdev/platform-windows-x64": "0.1.1-beta.84",
+    "@tokamakdev/tok-darwin-arm64": "0.1.1-beta.84",
+    "@tokamakdev/tok-darwin-x64": "0.1.1-beta.84",
+    "@tokamakdev/tok-linux-x64": "0.1.1-beta.84",
+    "@tokamakdev/tok-win32-x64": "0.1.1-beta.84"
   },
   "publishConfig": {
     "access": "public"