@tokamakdev/plugin 0.1.0-beta.100

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 the app is in
+  the background. Call it on the main thread where the plugin decides to 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

@@ -0,0 +1,21 @@
+{
+  "name": "@tokamakdev/plugin",
+  "version": "0.1.0-beta.100",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mantty/tokamak.git",
+    "directory": "plugins/core"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./events": "./src/events.ts",
+    "./testing": "./src/testing.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

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

@@ -0,0 +1,173 @@
+interface NativeTransport {
+  postMessage(message: string): void;
+  onmessage: ((event: { data: string }) => void) | null;
+}
+
+interface NativeError {
+  name: string;
+  message: string;
+}
+
+interface NativeResponse {
+  session: string;
+  id: number;
+  value?: unknown;
+  error?: NativeError;
+  done: boolean;
+}
+
+interface PendingCall {
+  kind: "call";
+  resolve(value: unknown): void;
+  reject(error: DOMException): void;
+}
+
+interface PendingSubscription {
+  kind: "subscription";
+  next(value: unknown): void;
+  error(error: DOMException): void;
+}
+
+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;
+const session = `${String(Date.now())}-${String(Math.random())}`;
+let connected: NativeTransport | undefined;
+const pending = new Map<number, Pending>();
+
+/** 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 pageTransport() !== undefined || globalThis.__tokamakNativeCall !== undefined;
+  }
+
+  protected call<T>(method: string, arguments_: unknown = null): Promise<T> {
+    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.
+  protected listen<T>(
+    method: string,
+    next: (value: T) => void,
+    error: (error: DOMException) => void,
+    arguments_: unknown = null,
+  ): () => void {
+    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 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) connect(transport);
+  return transport;
+}
+
+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(
+  transport: NativeTransport,
+  plugin: string,
+  method: string,
+  arguments_: unknown,
+  request: Pending,
+): number {
+  const id = nextRequestId++;
+  const type = request.kind === "call" ? "call" : "subscribe";
+  pending.set(id, request);
+  try {
+    transport.postMessage(
+      JSON.stringify({ type, session, id, plugin, method, arguments: arguments_ }),
+    );
+  } catch (error) {
+    pending.delete(id);
+    throw error;
+  }
+  return id;
+}
+
+function receive(response: NativeResponse): void {
+  if (response.session !== session) return;
+  const request = pending.get(response.id);
+  if (!request) return;
+  if (response.done) pending.delete(response.id);
+
+  if (response.error) {
+    const error = new DOMException(response.error.message, response.error.name);
+    if (request.kind === "call") request.reject(error);
+    else request.error(error);
+    return;
+  }
+
+  if (request.kind === "call") request.resolve(response.value);
+  else request.next(response.value);
+}
+
+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

@@ -0,0 +1,61 @@
+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. */
+  readonly sent: Record<string, unknown>[] = [];
+  onmessage: ((event: { data: string }) => void) | null = null;
+
+  postMessage(message: string): void {
+    this.sent.push(JSON.parse(message) as Record<string, unknown>);
+  }
+
+  /** The last message's type, plugin, method and arguments. */
+  lastRequest(): Record<string, unknown> {
+    const { type, plugin, method, arguments: arguments_ } = this.sent.at(-1) ?? {};
+    return { type, plugin, method, arguments: arguments_ };
+  }
+
+  /** Replies to the last message. */
+  respond(reply: { value?: unknown; error?: { name: string; message: string } }, done = true): void {
+    const { session, id } = this.sent.at(-1) ?? {};
+    this.deliver({ session, id, done, ...reply });
+  }
+
+  /** Delivers `response` to the page. */
+  deliver(response: Record<string, unknown>): void {
+    this.onmessage?.({ data: JSON.stringify(response) });
+  }
+}
+
+/** Installs a new fake as the page's native transport. */
+export function connectNative(): FakeNativeTransport {
+  const transport = new FakeNativeTransport();
+  globalThis.__tokamakNative = transport;
+  return transport;
+}
+
+/** Removes the page's native transport. */
+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);
+  }
+}