@tokamakdev/plugin 0.1.0-beta.82 → 0.1.0-beta.84

package/README.md

@@ -0,0 +1,120 @@
+# @tokamakdev/plugin
+
+The shared base of tokamak plugins: the native transport, Worker events, and
+test fakes.
+
+| Entry | Contents |
+| --- | --- |
+| `@tokamakdev/plugin` | `Plugin`, the base class of a plugin's API, which the page and the Worker call alike |
+| `@tokamakdev/plugin/events` | `defineEvent`, which defines a plugin's Worker events |
+| `@tokamakdev/plugin/testing` | A fake native transport, and `dispatch`, which runs event listeners as the runtime does |
+
+A plugin lists `@tokamakdev/plugin` as a peer dependency, so an app has one
+copy of it, shared with `@tokamakdev/tok`, which depends on it.
+
+## Calls
+
+A plugin's API extends `Plugin`, whose `call` and `listen` reach its native
+code from the page through the shell's bridge, and from the Worker through the
+runtime. `hasNativeTransport` is false outside a tokamak app, such as on the
+web and Cloudflare, where the plugin uses its web implementation or rejects
+with `NotSupportedError`:
+
+```ts
+import { Plugin } from "@tokamakdev/plugin";
+
+class Alarms extends Plugin {
+  constructor() {
+    super("alarms");
+  }
+
+  set(at: number): Promise<void> {
+    return this.call("set", { at });
+  }
+
+  onRing(next: (id: string) => void, error: (error: DOMException) => void): () => void {
+    return this.listen("onRing", next, error);
+  }
+}
+
+export const alarms = new Alarms();
+```
+
+The native side runs each call and subscription on the main thread, for the
+page and the Worker alike. A `subscribe` that throws, as for a method the
+plugin does not have, ends the subscription; a failure it replies with does
+not.
+
+## Showing UI
+
+Calls come at any time, including while the app is off screen. Native code
+that would show UI then fails with `NeedsUIError` instead, through the host,
+so only calls that would show UI fail:
+
+- **Android:** `requestPermissions` throws `NeedsUIError` when a permission
+  would prompt while the app is in the background, and answers at once,
+  without UI, when none would. The host remembers the permissions the user has
+  refused for good, as Android reports them the same way as permissions never
+  asked for; `wouldPrompt` tells them apart. Other UI goes in the
+  activity `requireForegroundActivity()` returns, which throws `NeedsUIError`
+  in the background; `authenticateOwner` uses it. `isInForeground` reports the
+  app's stage.
+- **Apple:** `requireUI()` throws `NeedsUIError` on iOS while no scene is in
+  the foreground. Call it where the plugin would show UI, and only when the
+  UI would appear, such as before `requestWhenInUseAuthorization` while the
+  authorization is not determined. A hidden macOS app still shows system
+  prompts, so it never throws there.
+
+## Worker events
+
+A plugin's native code delivers events to the app's Worker, whose listeners
+register in `src/tokamak.ts` and run even when no page is loaded, such as when
+the system starts the app in the background.
+
+The plugin defines each event in its own `/events` entry, which apps import:
+
+```ts
+// events/index.ts, exported as "./events" in package.json
+import { defineEvent } from "@tokamakdev/plugin/events";
+
+/** Receives each alarm as it rings. A returned number snoozes it for that many minutes. */
+export const onRing = defineEvent<{ id: string }, number>("alarms.ring");
+```
+
+`defineEvent<T, Reply>(name)` returns the function that registers listeners,
+typed with the event's data `T` and the `Reply` its listeners may return. The
+name is the plugin's ID, a `.`, and the event's name. The event's reply is the
+first value, in registration order, that a listener returns other than
+`undefined`.
+
+The native side emits the event through the host the plugin is created with,
+which prefixes the plugin's ID, so listeners of `alarms.ring` receive
+`host.emit("ring", …)`. Events are JSON:
+
+```swift
+host.emit("ring", event: ["id": alarm.id], timeout: 10) { result in
+  // `result` is the reply, parsed from JSON, or nil when no listener replies.
+}
+```
+
+```kotlin
+// Blocks, so call it off the main thread.
+val reply = host.emit("ring", JSONObject().put("id", alarm.id).toString(), 10_000)
+// `reply` is the reply's JSON, "null" when no listener replies.
+```
+
+`timeout` includes starting the runtime when the app is not running. `emit`
+fails when the Worker cannot run, or when a listener has not returned by the
+timeout; it is not retried. The runtime starts no Worker for an event without
+listeners, so emit each event the plugin defines whether or not the app
+listens. Plugin IDs contain no `.`.
+
+Test listeners with `dispatch` from `@tokamakdev/plugin/testing`, which runs
+them as the runtime does and returns what they threw:
+
+```ts
+import { dispatch } from "@tokamakdev/plugin/testing";
+
+onRing(() => 5);
+const { reply, reported } = await dispatch("alarms.ring", { id: "a1" }, env);
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamakdev/plugin",
-  "version": "0.1.0-beta.82",
+  "version": "0.1.0-beta.84",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mantty/tokamak.git",
@@ -9,7 +9,7 @@
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
-    "./worker": "./src/worker.ts",
+    "./events": "./src/events.ts",
     "./testing": "./src/testing.ts"
   },
   "files": [

package/src/entrypoint.js

@@ -0,0 +1,12 @@
+// The tokamak Vite plugin exports this class from the entry Worker in tokamak builds and
+// development, where the runtime and `tok dev` call `dispatch` to deliver events.
+import { WorkerEntrypoint } from "cloudflare:workers";
+
+import { dispatch } from "./registry.ts";
+
+export class TokamakEvents extends WorkerEntrypoint {
+  /** Runs the listeners of the event `name` and returns `{ reply, listened }`. */
+  dispatch(name, event) {
+    return dispatch(name, event, this.env, this.ctx);
+  }
+}

package/src/events.ts

@@ -0,0 +1,35 @@
+import { register, type RegisteredListener } from "./registry.js";
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace -- `wrangler types` declares the Worker's bindings here.
+  namespace Cloudflare {
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type -- the app's `wrangler types` declares the members.
+    interface Env {}
+  }
+}
+
+/** The invocation a listener runs in. */
+export interface EventContext {
+  /** Keeps the event running until `promise` settles or the event's deadline passes. */
+  waitUntil(promise: Promise<unknown>): void;
+}
+
+/** Receives an event of type `T` with the Worker's `env`, and may return a `Reply`. */
+export type Listener<T, Reply = void> = (
+  event: T,
+  env: Cloudflare.Env,
+  ctx: EventContext,
+) => Reply | undefined | Promise<Reply | undefined>;
+
+/**
+ * Defines the event `name` and returns the function that registers its listeners. The event's
+ * reply is the first value, in registration order, that a listener returns other than
+ * `undefined`.
+ */
+export function defineEvent<T, Reply = void>(
+  name: string,
+): (listener: Listener<T, Reply>) => void {
+  return (listener) => {
+    register(name, listener as RegisteredListener);
+  };
+}

package/src/index.ts

@@ -30,8 +30,24 @@ interface PendingSubscription {
 
 type Pending = PendingCall | PendingSubscription;
 
+/** Calls `method` of `plugin` from the Worker, resolving with its value. */
+type WorkerCall = (plugin: string, method: string, arguments_: unknown) => Promise<unknown>;
+
+/** Subscribes to `method` of `plugin` from the Worker, returning the function that unsubscribes. */
+type WorkerListen = (
+  plugin: string,
+  method: string,
+  arguments_: unknown,
+  next: (value: unknown) => void,
+  error: (error: DOMException) => void,
+) => () => void;
+
 declare global {
+  /** The page's native transport, which the shells define. */
   var __tokamakNative: NativeTransport | undefined;
+  /** The Worker's native calls, which the runtime and `tok dev` define. */
+  var __tokamakNativeCall: WorkerCall | undefined;
+  var __tokamakNativeListen: WorkerListen | undefined;
 }
 
 let nextRequestId = 1;
@@ -39,17 +55,24 @@ const session = `${String(Date.now())}-${String(Math.random())}`;
 let connected: NativeTransport | undefined;
 const pending = new Map<number, Pending>();
 
-export abstract class FrontendPlugin {
+/** The base class of a plugin's API, which the page and the Worker call alike. */
+export abstract class Plugin {
   protected constructor(private readonly pluginId: string) {}
 
   protected get hasNativeTransport(): boolean {
-    return nativeTransport() !== undefined;
+    return pageTransport() !== undefined || globalThis.__tokamakNativeCall !== undefined;
   }
 
   protected call<T>(method: string, arguments_: unknown = null): Promise<T> {
-    return new Promise<T>((resolve, reject) => {
-      send("call", this.pluginId, method, arguments_, { kind: "call", resolve, reject });
-    });
+    const page = pageTransport();
+    if (page) {
+      return new Promise<T>((resolve, reject) => {
+        send(page, this.pluginId, method, arguments_, { kind: "call", resolve, reject });
+      });
+    }
+    const call = globalThis.__tokamakNativeCall;
+    if (call) return call(this.pluginId, method, arguments_) as Promise<T>;
+    return Promise.reject(unavailable());
   }
 
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters -- T types the native values, as in call.
@@ -59,47 +82,58 @@ export abstract class FrontendPlugin {
     error: (error: DOMException) => void,
     arguments_: unknown = null,
   ): () => void {
-    const { transport, id } = send("subscribe", this.pluginId, method, arguments_, {
-      kind: "subscription",
-      next,
-      error,
-    });
-    return () => {
-      if (!pending.delete(id)) return;
-      transport.postMessage(JSON.stringify({ type: "cancel", session, id }));
-    };
+    const page = pageTransport();
+    if (page) {
+      const id = send(page, this.pluginId, method, arguments_, {
+        kind: "subscription",
+        next,
+        error,
+      });
+      return () => {
+        if (!pending.delete(id)) return;
+        page.postMessage(JSON.stringify({ type: "cancel", session, id }));
+      };
+    }
+    const listen = globalThis.__tokamakNativeListen;
+    if (listen) return listen(this.pluginId, method, arguments_, next as (value: unknown) => void, error);
+    throw unavailable();
   }
 }
 
-function nativeTransport(): NativeTransport | undefined {
+function unavailable(): DOMException {
+  return new DOMException("Native plugin transport is unavailable", "NotSupportedError");
+}
+
+/** The page's native transport, connected on first use. */
+function pageTransport(): NativeTransport | undefined {
   const transport = globalThis.__tokamakNative;
   if (!transport || typeof transport.postMessage !== "function") return undefined;
-  if (connected !== transport) {
-    connected = transport;
-    transport.onmessage = ({ data }) => {
-      receive(JSON.parse(data) as NativeResponse);
-    };
-    transport.postMessage(JSON.stringify({ type: "reset", session }));
-  }
+  if (connected !== transport) connect(transport);
   return transport;
 }
 
-function requireNativeTransport(): NativeTransport {
-  const transport = nativeTransport();
-  if (transport) return transport;
-  throw new DOMException("Native plugin transport is unavailable", "NotSupportedError");
+function connect(transport: NativeTransport): void {
+  if (!connected) {
+    const page: { addEventListener?: (type: string, listener: () => void) => void } = globalThis;
+    page.addEventListener?.("pagehide", cancelSubscriptions);
+  }
+  connected = transport;
+  transport.onmessage = ({ data }) => {
+    receive(JSON.parse(data) as NativeResponse);
+  };
+  transport.postMessage(JSON.stringify({ type: "reset", session }));
 }
 
 /** Posts a call or subscription, keeping `request` pending unless posting throws. */
 function send(
-  type: "call" | "subscribe",
+  transport: NativeTransport,
   plugin: string,
   method: string,
   arguments_: unknown,
   request: Pending,
-): { transport: NativeTransport; id: number } {
-  const transport = requireNativeTransport();
+): number {
   const id = nextRequestId++;
+  const type = request.kind === "call" ? "call" : "subscribe";
   pending.set(id, request);
   try {
     transport.postMessage(
@@ -109,7 +143,7 @@ function send(
     pending.delete(id);
     throw error;
   }
-  return { transport, id };
+  return id;
 }
 
 function receive(response: NativeResponse): void {
@@ -129,15 +163,11 @@ function receive(response: NativeResponse): void {
   else request.next(response.value);
 }
 
-const eventTarget: {
-  addEventListener?: (type: string, listener: () => void) => void;
-} = globalThis;
-
-eventTarget.addEventListener?.("pagehide", () => {
+function cancelSubscriptions(): void {
   if (!connected) return;
   for (const [id, request] of pending) {
     if (request.kind !== "subscription") continue;
     pending.delete(id);
     connected.postMessage(JSON.stringify({ type: "cancel", session, id }));
   }
-});
+}

package/src/registry.ts

@@ -0,0 +1,40 @@
+/** A registered listener. */
+export type RegisteredListener = (event: unknown, env: unknown, ctx: unknown) => unknown;
+
+/** What a dispatch returns. */
+export interface Dispatched {
+  /** The first value, in registration order, that a listener returned other than `undefined`. */
+  reply: unknown;
+  /** The names of the events that have listeners. */
+  listened: string[];
+}
+
+/** Every listener, by event name, in registration order. */
+const listeners = new Map<string, RegisteredListener[]>();
+
+export function register(name: string, listener: RegisteredListener): void {
+  const registered = listeners.get(name);
+  if (registered) registered.push(listener);
+  else listeners.set(name, [listener]);
+}
+
+/**
+ * Runs the listeners of the event `name` and waits for them to settle. A listener that throws is
+ * reported with `reportError`, and the others still run.
+ */
+export async function dispatch(
+  name: string,
+  event: unknown,
+  env: unknown,
+  ctx: unknown,
+): Promise<Dispatched> {
+  const results = await Promise.allSettled(
+    (listeners.get(name) ?? []).map(async (listener) => await listener(event, env, ctx)),
+  );
+  let reply: unknown;
+  for (const result of results) {
+    if (result.status === "rejected") reportError(result.reason);
+    else if (reply === undefined) reply = result.value;
+  }
+  return { reply, listened: [...listeners.keys()] };
+}

package/src/testing.ts

@@ -1,3 +1,5 @@
+import { dispatch as dispatchEvent, type Dispatched } from "./registry.js";
+
 /** A native transport that records the page's messages and replies as the native bridges do. */
 export class FakeNativeTransport {
   /** Every message the page posted, parsed. */
@@ -37,3 +39,23 @@ export function connectNative(): FakeNativeTransport {
 export function disconnectNative(): void {
   Reflect.deleteProperty(globalThis, "__tokamakNative");
 }
+
+/**
+ * Runs the listeners of the event `name` as the runtime does, returning the reply, the events
+ * that have listeners, and what listeners threw, which the runtime reports with `reportError`.
+ */
+export async function dispatch(
+  name: string,
+  event: unknown,
+  env: unknown = {},
+  ctx: unknown = { waitUntil: () => undefined },
+): Promise<Dispatched & { reported: unknown[] }> {
+  const reported: unknown[] = [];
+  const previous = Reflect.get(globalThis, "reportError") as unknown;
+  globalThis.reportError = (error: unknown) => reported.push(error);
+  try {
+    return { ...(await dispatchEvent(name, event, env, ctx)), reported };
+  } finally {
+    Reflect.set(globalThis, "reportError", previous);
+  }
+}

package/src/worker.ts

@@ -1,17 +0,0 @@
-declare const process:
-  | { readonly env: { readonly NODE_ENV?: string; readonly TOKAMAK_RUNTIME?: string } }
-  | undefined;
-
-/**
- * Whether the Worker serves the tokamak runtime's calls to endpoints under `/tokamak/`: in a
- * tokamak app, where the runtime sets `TOKAMAK_RUNTIME`, and in development. Those endpoints
- * refuse requests otherwise.
- */
-export function acceptsRuntimeCalls(): boolean {
-  // One expression: Rollup 4.63.0 drops callers' checks when this is an early return followed
-  // by a return of `typeof process !== "undefined" && false`.
-  return (
-    typeof process !== "undefined" &&
-    (process.env.NODE_ENV === "development" || process.env.TOKAMAK_RUNTIME === "true")
-  );
-}