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

package/README.md

@@ -12,6 +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/vite` | The Vite plugin, `tokamak()` |
 | `tok` | The CLI |
 
@@ -28,7 +29,10 @@ export default defineConfig({
 });
 ```
 
-It does nothing unless `tok` runs the build or development command.
+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.
 
 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

@@ -0,0 +1,10 @@
+/** 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.
+ */
+export declare function openDevSocket(workerName: string | undefined, token: string | undefined): Promise<DevSocket>;

package/dist/dev-socket.mjs

@@ -0,0 +1,106 @@
+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";
+/** Calls `TokamakEvents` in the Worker its `TOKAMAK` service binding names, through the dev registry. */
+const CALLER = `export default {
+  async fetch(request, env) {
+    const { name, event } = await request.json();
+    try {
+      const { reply } = await env.TOKAMAK.dispatch(name, event);
+      return Response.json({ reply: reply ?? null });
+    } catch (error) {
+      return new Response(error?.stack ?? String(error), { status: 500 });
+    }
+  },
+};`;
+/**
+ * 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.
+ */
+export async function openDevSocket(workerName, token) {
+    const worker = new DevWorker(workerName);
+    const server = http.createServer((_request, response) => response.writeHead(426).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));
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", resolve);
+    });
+    return {
+        port: server.address().port,
+        async close() {
+            for (const websocket of sockets.clients)
+                websocket.terminate();
+            server.close();
+            await worker.dispose();
+        },
+    };
+}
+function serve(websocket, worker) {
+    // 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 !== "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) })));
+    });
+}
+function parseMessage(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The development Worker's `TokamakEvents`, called through a Miniflare session started on first use. */
+class DevWorker {
+    name;
+    #miniflare;
+    constructor(name) {
+        this.name = name;
+    }
+    async dispatch(name, event) {
+        this.#miniflare ??= this.#start().catch((error) => {
+            this.#miniflare = undefined;
+            throw error;
+        });
+        const miniflare = await this.#miniflare;
+        const response = await miniflare.dispatchFetch("http://tokamak/", {
+            method: "POST",
+            body: JSON.stringify({ name, event }),
+        });
+        if (!response.ok)
+            throw new Error(await response.text());
+        return (await response.json()).reply;
+    }
+    async dispose() {
+        await (await this.#miniflare?.catch(() => undefined))?.dispose();
+    }
+    /** A Miniflare session from the Miniflare that Cloudflare's plugin uses. */
+    async #start() {
+        if (!this.name)
+            throw new Error("the Wrangler configuration names no Worker to deliver events to");
+        const require = createRequire(import.meta.resolve("@cloudflare/vite-plugin"));
+        const module = (await import(pathToFileURL(require.resolve("miniflare")).href));
+        const miniflare = new module.Miniflare(module.convertV4MiniflareOptions({
+            modules: true,
+            script: CALLER,
+            compatibilityDate: "2025-01-01",
+            serviceBindings: { TOKAMAK: { name: this.name, entrypoint: "TokamakEvents" } },
+            unsafeDevRegistryPath: module.getDefaultDevRegistryPath(),
+        }));
+        await miniflare.ready;
+        return miniflare;
+    }
+}

package/dist/events.d.mts

@@ -0,0 +1,8 @@
+/** Runs once per runtime start, including when the system starts the app in the background. */
+export declare const onStart: (listener: import("@tokamakdev/plugin/events").Listener<{
+    readonly foreground: boolean;
+}, void>) => void;
+/** Runs each time the app moves into the foreground, but not when it starts there. */
+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;

package/dist/events.mjs

@@ -0,0 +1,7 @@
+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");
+/** Runs each time the app moves into the foreground, but not when it starts there. */
+export const onResume = defineEvent("resume");
+/** Runs each time the app moves out of the foreground. */
+export const onSuspend = defineEvent("suspend");

package/dist/vite.d.mts

@@ -2,8 +2,9 @@ import { type Plugin } from "vite";
 import type { Config } from "./index.mjs";
 /**
  * Reports the app's tokamak configuration, and the development server's
- * address and Worker name, to `tok`, and makes the entry Worker import
- * `module`. Without `TOKAMAK_VITE_OUTPUT`, which `tok` sets, it adds no hooks.
+ * 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.
  */
 export declare function tokamak({ module, ...config }?: Config & {
     /**

package/dist/vite.mjs

@@ -1,14 +1,19 @@
+import { X509Certificate } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { normalizePath } from "vite";
+import { fileURLToPath } from "node:url";
+import { normalizePath, } from "vite";
+import { openDevSocket } from "./dev-socket.mjs";
 /** Modules tried in order when the options name none. */
 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";
 /**
  * Reports the app's tokamak configuration, and the development server's
- * address and Worker name, to `tok`, and makes the entry Worker import
- * `module`. Without `TOKAMAK_VITE_OUTPUT`, which `tok` sets, it adds no hooks.
+ * 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.
  */
 export function tokamak({ module, ...config } = {}) {
     const output = process.env.TOKAMAK_VITE_OUTPUT;
@@ -16,38 +21,61 @@ export function tokamak({ module, ...config } = {}) {
         return [];
     }
     let file;
+    const events = import.meta.resolve("@tokamakdev/plugin/events");
+    /** The module that defines `TokamakEvents`. */
+    const entrypoint = normalizePath(fileURLToPath(new URL("./entrypoint.js", events)));
+    /** The module that holds event listeners. */
+    const registryFile = normalizePath(fileURLToPath(new URL("./registry.ts", events)));
     /** The module IDs of each entry environment's inputs. */
     const entryIds = new Map();
-    /** The entry environments whose input imports the module. */
-    const importing = new Set();
+    /** The entry environments whose input exports `TokamakEvents`. */
+    const exporting = new Set();
     return [
         {
             name: "tokamak",
+            // Keeps @tokamakdev/plugin out of pre-bundled dependencies, so they
+            // share the one module that holds event listeners.
+            configEnvironment() {
+                return { optimizeDeps: { exclude: ["@tokamakdev/plugin"] } };
+            },
             configResolved({ root }) {
                 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 });
+                    }
                     return;
                 }
-                const workerName = await readWorkerName(server.config.root);
-                httpServer.on("listening", () => {
-                    const urls = server.resolvedUrls;
-                    writeJson(output, "server.json", { url: urls?.local[0] ?? urls?.network[0], workerName });
+                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 urls = server.resolvedUrls;
+                        writeJson(output, "server.json", {
+                            url: urls?.local[0] ?? urls?.network[0],
+                            workerName: worker?.topLevelName ?? worker?.name,
+                            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);
-                if (file && !environments.some((environment) => buildsEntryWorker(environment.config))) {
-                    throw new Error(`no environment builds the entry Worker to import ${file} into`);
+                if (!environments.some((environment) => buildsEntryWorker(environment.config))) {
+                    throw new Error("no environment builds the entry Worker to export TokamakEvents from");
                 }
             },
         },
         {
             name: "tokamak:entry",
-            applyToEnvironment: ({ config }) => file !== undefined && buildsEntryWorker(config),
+            applyToEnvironment: ({ config }) => buildsEntryWorker(config),
             async transform(code, id) {
                 const environment = this.environment;
                 const ids = entryIds.get(environment.name) ??
@@ -56,19 +84,48 @@ export function tokamak({ module, ...config } = {}) {
                 if (!(await ids).includes(id)) {
                     return;
                 }
-                importing.add(environment.name);
+                exporting.add(environment.name);
                 // 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.
-                return { code: `${code}\nimport ${JSON.stringify(file)};\n`, map: null };
+                const imports = file ? `import ${JSON.stringify(file)};\n` : "";
+                return { code: `${code}\n${imports}export { TokamakEvents } from ${JSON.stringify(entrypoint)};\n`, 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
+            // module that imports it evaluate again too.
+            async hotUpdate({ modules, timestamp }) {
+                const graph = this.environment.moduleGraph;
+                const registry = graph.getModuleById(registryFile);
+                if (!registry) {
+                    return;
+                }
+                const entries = (await entryIds.get(this.environment.name)) ?? [];
+                const registering = [...withImporters(registry)].filter((module) => !entries.some((id) => id === module.id));
+                const updated = new Set(modules.flatMap((changed) => [...withImporters(changed)]));
+                if (registering.some((module) => updated.has(module))) {
+                    graph.invalidateModule(registry, new Set(), timestamp, true);
+                }
             },
             generateBundle() {
-                if (!importing.has(this.environment.name)) {
-                    this.error(`the input of the ${this.environment.name} environment did not import ${file}`);
+                if (!exporting.has(this.environment.name)) {
+                    this.error(`the input of the ${this.environment.name} environment did not export TokamakEvents`);
                 }
             },
         },
     ];
 }
+/** `module` and every module that imports it, directly or through others. */
+function withImporters(module) {
+    const found = new Set();
+    const pending = [module];
+    for (let current = pending.pop(); current; current = pending.pop()) {
+        if (!found.has(current)) {
+            found.add(current);
+            pending.push(...current.importers);
+        }
+    }
+    return found;
+}
 /** The module `name` under `root`, or else the first default under `root` that exists. */
 function findModule(root, name) {
     const candidates = (name ? [name] : DEFAULT_MODULES).map((candidate) => normalizePath(path.resolve(root, candidate)));
@@ -79,18 +136,33 @@ function findModule(root, name) {
     return file;
 }
 /**
- * The name of the Worker in the Wrangler configuration file in `root`, found
- * as Cloudflare's plugin finds it without `configPath`, without the suffix of
- * the `CLOUDFLARE_ENV` environment.
+ * The Worker in the Wrangler configuration file in `root`, read as
+ * Cloudflare's plugin reads it without `configPath`, in the `CLOUDFLARE_ENV`
+ * environment: its name, and its name without the environment's suffix.
  */
-async function readWorkerName(root) {
+async function readWorker(root) {
     const file = WRANGLER_FILES.map((name) => path.join(root, name)).find((candidate) => fs.existsSync(candidate));
     if (!file) {
         return undefined;
     }
     const { unstable_readConfig } = await import("wrangler");
-    const worker = unstable_readConfig({ config: file, env: process.env.CLOUDFLARE_ENV }, { hideWarnings: true });
-    return worker.topLevelName ?? worker.name;
+    return unstable_readConfig({ config: file, env: process.env.CLOUDFLARE_ENV }, { hideWarnings: true });
+}
+/**
+ * The PEM of the end-entity certificate of each chain in `https.cert`, which
+ * Vite reads from a file when a string names one.
+ */
+function endEntityCertificates(https) {
+    const cert = typeof https?.cert === "string" ? readFileIfExists(https.cert) : https?.cert;
+    return cert && [cert].flat().map((chain) => new X509Certificate(chain).toString()).join("");
+}
+function readFileIfExists(file) {
+    try {
+        return fs.readFileSync(path.resolve(file));
+    }
+    catch {
+        return file;
+    }
 }
 /**
  * Whether an environment builds from the entry Worker: Cloudflare's plugin

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamakdev/tok",
-  "version": "0.1.1-beta.81",
+  "version": "0.1.1-beta.83",
   "description": "The tokamak CLI, Vite plugin and app API: build native apps from a Cloudflare Workers codebase",
   "repository": {
     "type": "git",
@@ -12,6 +12,10 @@
       "types": "./dist/index.d.mts",
       "default": "./dist/index.mjs"
     },
+    "./events": {
+      "types": "./dist/events.d.mts",
+      "default": "./dist/events.mjs"
+    },
     "./vite": {
       "types": "./dist/vite.d.mts",
       "default": "./dist/vite.mjs"
@@ -34,6 +38,10 @@
   "engines": {
     "node": ">=18"
   },
+  "dependencies": {
+    "@tokamakdev/plugin": "0.1.0-beta.83",
+    "ws": "^8.22.0"
+  },
   "peerDependencies": {
     "@cloudflare/vite-plugin": "^1.54.0",
     "vite": "^7.0.0 || ^8.0.0",
@@ -50,22 +58,23 @@
   "devDependencies": {
     "@cloudflare/vite-plugin": "1.62.5",
     "@types/node": "22.19.15",
+    "@types/ws": "8.18.2",
     "typescript": "5.9.3",
     "vite": "8.3.2",
     "wrangler": "4.147.0"
   },
   "optionalDependencies": {
-    "@tokamakdev/platform-android-arm64": "0.1.1-beta.81",
-    "@tokamakdev/platform-ios-arm64": "0.1.1-beta.81",
-    "@tokamakdev/platform-ios-simulator-arm64": "0.1.1-beta.81",
-    "@tokamakdev/platform-ios-simulator-x64": "0.1.1-beta.81",
-    "@tokamakdev/platform-macos-arm64": "0.1.1-beta.81",
-    "@tokamakdev/platform-macos-x64": "0.1.1-beta.81",
-    "@tokamakdev/platform-windows-x64": "0.1.1-beta.81",
-    "@tokamakdev/tok-darwin-arm64": "0.1.1-beta.81",
-    "@tokamakdev/tok-darwin-x64": "0.1.1-beta.81",
-    "@tokamakdev/tok-linux-x64": "0.1.1-beta.81",
-    "@tokamakdev/tok-win32-x64": "0.1.1-beta.81"
+    "@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"
   },
   "publishConfig": {
     "access": "public"