akanjs 3.0.0-beta.20 → 3.0.0-beta.21

package/vendor/@akanjs/native/packages/core/src/plugin.ts

@@ -0,0 +1,358 @@
+
+
+import { aclCheck, type CallScope, listenItem } from "./acl.ts";
+import { AkanNativeError } from "./errors.ts";
+import {
+  type BridgeRequest,
+  type BridgeResponse,
+  type CancelReason,
+  LISTEN,
+  MEMBER_NAME,
+  RESERVED_MEMBERS,
+  UNLISTEN,
+} from "./protocol.ts";
+import { cancelCall, dispatchEvent, eventKey, runtime } from "./runtime.ts";
+
+export type Implementation = "native" | "web" | "none";
+
+type Unsubscribe = () => void;
+type Emit<T> = (data: T) => void;
+
+/** Second argument of a web implementation method: what the app's capabilities allow this call (PL-11). */
+export interface WebCallContext {
+  scope?: CallScope;
+  /** The caller's AbortSignal: stop the work when it fires (the call has already been rejected). */
+  signal?: AbortSignal;
+}
+
+/**
+ * The last argument of every plugin method (bridge v1.1 `cancel`). There is no timeout option:
+ * `AbortSignal.timeout(ms)` rejects with TIMEOUT, any other abort with CANCELLED, and
+ * `AbortSignal.any([...])` combines them.
+ */
+export interface CallOptions {
+  signal?: AbortSignal;
+}
+
+export interface ListenOptions {
+  /** Unsubscribes when it fires. */
+  signal?: AbortSignal;
+  /** Unsubscribes after the first event. */
+  once?: boolean;
+}
+
+export interface WebPlugin<Api, Events> {
+  methods: { [K in keyof Api]?: Api[K] };
+  /** Event sources. Started for the first listener, stopped after the last one leaves. */
+  events?: { [E in keyof Events]?: (emit: Emit<Events[E]>) => Unsubscribe };
+}
+
+export interface PluginOptions<Api, Events> {
+  methods: readonly (keyof Api & string)[];
+  events?: readonly (keyof Events & string)[];
+  web?: WebPlugin<Api, Events>;
+}
+
+export interface PluginHandle<Api, Events> {
+  readonly id: string;
+  readonly methods: readonly (keyof Api & string)[];
+  readonly events: readonly (keyof Events & string)[];
+  /** Where a call to this method would go on the current host. */
+  implementation(method: keyof Api & string): Implementation;
+  isSupported(method: keyof Api & string): boolean;
+  /** Whether the app's capabilities let this window call the method (PL-11). Independent of isSupported. */
+  isAllowed(method: keyof Api & string): boolean;
+  eventImplementation(event: keyof Events & string): Implementation;
+  /** Subscribes to an event. Safe to call and undo repeatedly (React StrictMode). */
+  listen<E extends keyof Events & string>(
+    event: E,
+    listener: (data: Events[E]) => void,
+    options?: ListenOptions,
+  ): Unsubscribe;
+}
+
+/** A method with the CallOptions argument after its own (a method without arguments takes `undefined` first). */
+type WithOptions<F> = F extends (...args: infer P) => infer R
+  ? (...args: P extends [] ? [args: undefined, options: CallOptions] : [...P, options: CallOptions]) => R
+  : never;
+
+/**
+ * Each method keeps its own signature (generics and overloads intact) and gains an overload that
+ * takes CallOptions last. With options, the argument types come from the last overload.
+ */
+export type PluginMethods<Api> = { [K in keyof Api]: Api[K] & WithOptions<Api[K]> };
+
+export type Plugin<Api, Events = {}> = PluginMethods<Api> & PluginHandle<Api, Events>;
+
+const RESERVED = new Set([...RESERVED_MEMBERS, "$$typeof"]);
+
+/** Identity helper that gives web implementations their types. */
+export function defineWebPlugin<Api, Events = {}>(impl: WebPlugin<Api, Events>): WebPlugin<Api, Events> {
+  return impl;
+}
+
+export function definePlugin<Api extends object, Events extends object = {}>(
+  id: string,
+  options: PluginOptions<Api, Events>,
+): Plugin<Api, Events> {
+  const web = options.web;
+  const events = options.events ?? [];
+
+  const nativeDecl = () => {
+    const decl = runtime().boot.plugins[id];
+    return decl && decl !== "web" ? decl : null;
+  };
+  const webAllowed = () => {
+    const boot = runtime().boot;
+    const decl = boot.plugins[id];
+    return boot.platform === "web" || decl === "web" || (typeof decl === "object" && decl.web === true);
+  };
+
+  const implementation = (method: string): Implementation => {
+    if (runtime().boot.platform !== "web" && nativeDecl()?.methods.includes(method)) return "native";
+    if (webAllowed() && typeof (web?.methods as Record<string, unknown> | undefined)?.[method] === "function")
+      return "web";
+    return "none";
+  };
+
+  const eventImplementation = (event: string): Implementation => {
+    if (runtime().boot.platform !== "web" && nativeDecl()?.events.includes(event)) return "native";
+    if (webAllowed() && typeof (web?.events as Record<string, unknown> | undefined)?.[event] === "function")
+      return "web";
+    return "none";
+  };
+
+  const callNative = async (method: string, args: unknown, signal?: AbortSignal): Promise<unknown> => {
+    const rt = runtime();
+    const request: BridgeRequest = { v: 1, id: ++rt.nextId, plugin: id, method };
+    if (args !== undefined) request.args = args;
+    if (!rt.transport) throw new AkanNativeError("UNSUPPORTED", `${id}.${method}() has no host on ${rt.boot.platform}`);
+
+    const site = rt.boot.dev ? new Error(`${id}.${method}() was called here`) : undefined;
+    if (rt.boot.dev) {
+      const problem = cloneProblem(args, "args");
+      if (problem)
+        throw new AkanNativeError("INVALID_ARGS", `${id}.${method}(): ${problem}`, { name: "DataCloneError" });
+    }
+    let response: BridgeResponse;
+    try {
+      const sent = rt.transport.send(request);
+      response = signal ? await untilAborted(sent, signal, (reason) => cancelCall(rt, request.id, reason)) : await sent;
+    } catch (error) {
+      throw AkanNativeError.from(error);
+    }
+    if (response.ok) return response.result;
+    throw AkanNativeError.fromBody(response.error, site);
+  };
+
+  const access = (item: string) => {
+    const boot = runtime().boot;
+    return aclCheck(boot.acl, id, item, boot.windowId ?? 1);
+  };
+  const notAllowed = (what: string) =>
+    new AkanNativeError("NOT_ALLOWED", `${id}.${what} is not allowed by the app's capabilities`);
+
+  const call = (method: string, args: unknown, options?: CallOptions): Promise<unknown> => {
+    const signal = options?.signal;
+    if (signal?.aborted) return Promise.reject(abortError(signal.reason));
+    switch (implementation(method)) {
+      case "native":
+        return callNative(method, args, signal);
+      case "web": {
+        const granted = access(method);
+        if (!granted.allowed) return Promise.reject(notAllowed(`${method}()`));
+
+        const fn = (web!.methods as Record<string, (a: unknown, ctx: WebCallContext) => unknown>)[method]!;
+        const ctx: WebCallContext = {};
+        if (granted.scope) ctx.scope = granted.scope;
+        if (signal) ctx.signal = signal;
+        try {
+          const result = Promise.resolve(fn(args, ctx)).catch((error: unknown) => {
+            throw AkanNativeError.from(error);
+          });
+          return signal ? untilAborted(result, signal) : result;
+        } catch (error) {
+          return Promise.reject(AkanNativeError.from(error));
+        }
+      }
+      case "none":
+        return Promise.reject(
+          new AkanNativeError("UNSUPPORTED", `${id}.${method}() is not supported on ${runtime().boot.platform}`),
+        );
+    }
+  };
+
+  const sources = new Map<string, { stop: Unsubscribe | null; stopScheduled: boolean }>();
+  const nativeChain = new Map<string, Promise<unknown>>();
+
+  const nativeSubscribe = (event: string, method: typeof LISTEN | typeof UNLISTEN) => {
+    
+    const previous = nativeChain.get(event) ?? Promise.resolve();
+    const next = previous
+      .then(() => callNative(method, { event }))
+      .catch((error) => console.warn(`[akan-native] ${id}.${method}(${event}) failed`, error));
+    nativeChain.set(event, next);
+  };
+
+  const startSource = (event: string): Unsubscribe | null => {
+    switch (eventImplementation(event)) {
+      case "native":
+        nativeSubscribe(event, LISTEN);
+        return () => nativeSubscribe(event, UNLISTEN);
+      case "web": {
+        if (!access(listenItem(event)).allowed) {
+          console.warn(`[akan-native] ${notAllowed(`${event} events`).message}`);
+          return null;
+        }
+        const start = (web!.events as Record<string, (emit: Emit<unknown>) => Unsubscribe>)[event]!;
+        try {
+          return start((data) => dispatchEvent(runtime(), id, event, data));
+        } catch (error) {
+          console.error(`[akan-native] starting web event ${id}.${event} failed`, error);
+          return null;
+        }
+      }
+      case "none":
+        return null;
+    }
+  };
+
+  const listen = (event: string, listener: (data: never) => void, options?: ListenOptions): Unsubscribe => {
+    const signal = options?.signal;
+    if (signal?.aborted) return () => {};
+    const rt = runtime();
+    const key = eventKey(id, event);
+    let set = rt.listeners.get(key);
+    if (!set) {
+      set = new Set();
+      rt.listeners.set(key, set);
+    }
+    const entry = (data: unknown) => {
+      if (options?.once) unsubscribe();
+      (listener as (d: unknown) => void)(data);
+    };
+    set.add(entry);
+
+    const source = sources.get(event);
+    if (source) {
+      source.stopScheduled = false; 
+    } else {
+      sources.set(event, { stop: startSource(event), stopScheduled: false });
+    }
+
+    let active = true;
+    const unsubscribe = () => {
+      if (!active) return;
+      active = false;
+      signal?.removeEventListener("abort", unsubscribe);
+      set.delete(entry);
+      if (set.size > 0) return;
+      const current = sources.get(event);
+      if (!current) return;
+      current.stopScheduled = true;
+      queueMicrotask(() => {
+        if (!current.stopScheduled || sources.get(event) !== current) return;
+        sources.delete(event);
+        current.stop?.();
+      });
+    };
+    signal?.addEventListener("abort", unsubscribe, { once: true });
+    return unsubscribe;
+  };
+
+  const handle: PluginHandle<Api, Events> = {
+    id,
+    methods: options.methods,
+    events,
+    implementation,
+    isSupported: (method) => implementation(method) !== "none",
+    isAllowed: (method) => access(method).allowed,
+    eventImplementation,
+    listen: listen as PluginHandle<Api, Events>["listen"],
+  };
+
+  const plugin: Record<string, unknown> = { ...handle };
+  for (const method of options.methods) {
+    if (RESERVED.has(method) || !MEMBER_NAME.test(method))
+      throw new Error(`[akan-native] plugin ${id}: method name "${method}" is reserved or not a name`);
+    plugin[method] = (args?: unknown, options?: CallOptions) => call(method, args, options);
+  }
+  return Object.freeze(plugin) as Plugin<Api, Events>;
+}
+
+/** What a signal's reason means for the host: a TimeoutError (AbortSignal.timeout) or any other abort. */
+function reasonOf(reason: unknown): CancelReason {
+  return (reason as { name?: unknown } | undefined)?.name === "TimeoutError" ? "timeout" : "abort";
+}
+
+/** The rejection for an aborted call: TIMEOUT for AbortSignal.timeout, else CANCELLED; the reason is the cause. */
+function abortError(reason: unknown): AkanNativeError {
+  if (reason instanceof AkanNativeError) return reason;
+  const timeout = reasonOf(reason) === "timeout";
+  const message = (reason as { message?: unknown } | undefined)?.message;
+  return new AkanNativeError(
+    timeout ? "TIMEOUT" : "CANCELLED",
+    typeof message === "string" && message ? message : timeout ? "the call timed out" : "the call was aborted",
+    { cause: reason },
+  );
+}
+
+/** Settles with `work`, or rejects as soon as the signal fires (after `onAbort`, e.g. telling the host). */
+function untilAborted<T>(work: Promise<T>, signal: AbortSignal, onAbort?: (reason: CancelReason) => void): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const abort = () => {
+      onAbort?.(reasonOf(signal.reason));
+      reject(abortError(signal.reason));
+    };
+    signal.addEventListener("abort", abort, { once: true });
+    work.then(
+      (value) => {
+        signal.removeEventListener("abort", abort);
+        resolve(value);
+      },
+      (error: unknown) => {
+        signal.removeEventListener("abort", abort);
+        reject(error);
+      },
+    );
+  });
+}
+
+/**
+ * Dev builds: why `value` would not survive the JSON trip to a native host, or null. JSON would
+ * silently turn these into something else (a Date into a string, a Map into {}, NaN into null) or
+ * throw (BigInt, a cycle). Plain objects, arrays, strings, finite numbers, booleans and null pass.
+ */
+export function cloneProblem(value: unknown, path: string, ancestors: object[] = []): string | null {
+  switch (typeof value) {
+    case "string":
+    case "boolean":
+    case "undefined":
+      return null;
+    case "number":
+      return Number.isFinite(value) ? null : `${path} is ${value} (JSON has no such number)`;
+    case "bigint":
+      return `${path} is a BigInt (JSON has no such number)`;
+    case "function":
+    case "symbol":
+      return `${path} is a ${typeof value}`;
+  }
+  if (value === null) return null;
+  const object = value as object;
+  if (ancestors.includes(object)) return `${path} refers back to itself (a cycle)`;
+  const proto = Object.getPrototypeOf(object);
+  if (!Array.isArray(object) && proto !== Object.prototype && proto !== null) {
+    const name = (object as { constructor?: { name?: string } }).constructor?.name || "class instance";
+    return `${path} is a ${name}: only plain objects, arrays, strings, numbers, booleans and null cross the bridge`;
+  }
+  ancestors.push(object);
+  try {
+    for (const [key, item] of Object.entries(object)) {
+      const problem = cloneProblem(item, Array.isArray(object) ? `${path}[${key}]` : `${path}.${key}`, ancestors);
+      if (problem) return problem;
+    }
+  } finally {
+    ancestors.pop();
+  }
+  return null;
+}

package/vendor/@akanjs/native/packages/core/src/protocol.ts

@@ -0,0 +1,194 @@
+
+
+import { ERROR_CODES as CONTRACT_ERROR_CODES, INIT_PREFIX, INIT_SUFFIX } from "./contract.ts";
+import { isDocumentId, isName } from "./kernel.ts";
+
+export const PROTOCOL_VERSION = 1;
+
+/**
+ * What the hosts of this akan-native version speak beyond v1 (boot.json `bridge.features`, part of the UP-3
+ * fingerprint, so a web bundle never runs on a shell that lacks one):
+ * - doc: every request names its document (one page load); the host ends the previous document
+ *   when a new one calls or the main frame commits a navigation, and refuses calls of ended ones
+ * - seq: the host numbers a document's responses and events (from 1) where it sends them; the page
+ *   delivers them in that order
+ * - once: a document's request id runs at most once
+ * - cancel: `$bridge.cancel { id, reason }` ends a running call of the same document at once
+ *   (CANCELLED, or TIMEOUT for reason "timeout") and tells its plugin; `$bridge.release { url }`
+ *   drops a FileRef. Errors may carry `data` and `retryable`.
+ */
+export const BRIDGE_FEATURES = ["doc", "seq", "once", "cancel"] as const;
+
+/** Reserved method names for event subscription. */
+export const LISTEN = "$listen";
+export const UNLISTEN = "$unlisten";
+
+/**
+ * Reserved plugin id for the bridge's follow-up operations (v1.1 `cancel`). They act on something a
+ * call of the same page handed out, so holding it is the permission (no ACL entry):
+ * - cancel { id, reason }: the call `id` of this document ends now (reason "abort" → CANCELLED,
+ *   "timeout" → TIMEOUT); answers `{ cancelled }`, false when the call already finished
+ * - release { url }: the FileRef at `url` is no longer served; answers `{ released }`
+ */
+export const BRIDGE_PLUGIN = "$bridge";
+export const CANCEL = "cancel";
+export const RELEASE = "release";
+export type CancelReason = "abort" | "timeout";
+
+/**
+ * A plugin's method and event names (manifest, definePlugin): a letter, then letters, digits and "_".
+ * Names starting with "$" belong to the bridge ($listen, $unlisten, $bridge, $host, $console).
+ */
+export const MEMBER_NAME = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+
+/** Method names the plugin object uses itself, or that JavaScript and React look for on any object. */
+export const RESERVED_MEMBERS: readonly string[] = [
+  "id",
+  "methods",
+  "events",
+  "implementation",
+  "isSupported",
+  "isAllowed",
+  "eventImplementation",
+  "listen",
+  "then",
+  "toJSON",
+  "constructor",
+  "prototype",
+  "__proto__",
+];
+export const CANCEL_REASONS: readonly CancelReason[] = ["abort", "timeout"];
+
+/** The app's capabilities do not grant a call: NOT_ALLOWED (PL-11). PERMISSION_DENIED is the OS or the user saying no. */
+export type ErrorCode = (typeof CONTRACT_ERROR_CODES)[number];
+
+export const ERROR_CODES: readonly ErrorCode[] = CONTRACT_ERROR_CODES;
+
+/** JS → host */
+export interface BridgeRequest {
+  v: 1;
+  id: number;
+  plugin: string;
+  method: string;
+  args?: unknown;
+  /** The calling document (v1.1 `doc`). The page runtime always sends it. */
+  doc?: string;
+}
+
+export interface BridgeErrorBody {
+  code: ErrorCode;
+  message: string;
+  /** Details a caller can act on, e.g. `{ reason: "packageManaged" }` (v1.1 `cancel`). */
+  data?: unknown;
+  /** The same call may work later (a plugin still starting, the network, a busy database). */
+  retryable?: boolean;
+}
+
+/** Where a host message goes and its place in the document's order (v1.1 `doc`, `seq`). */
+export interface Delivery {
+  doc?: string;
+  seq?: number;
+}
+
+/** host → JS, answers one request */
+export type BridgeResponse =
+  | ({ v: 1; id: number; ok: true; result?: unknown } & Delivery)
+  | ({ v: 1; id: number; ok: false; error: BridgeErrorBody } & Delivery);
+
+/** host → JS, push */
+export interface BridgeEvent extends Delivery {
+  v: 1;
+  plugin: string;
+  event: string;
+  data?: unknown;
+}
+
+/** Arguments of the reserved $listen / $unlisten methods. */
+export interface ListenArgs {
+  event: string;
+}
+
+/** Large results (photos, files) are returned as a URL served by the host (PL-7). */
+export interface FileRef {
+  url: string;
+  mime: string;
+  size: number;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** A document id: the page runtime makes 32 hex digits; hosts accept 8 to 64 of [A-Za-z0-9_-] (contract.json). */
+export const DOC_ID = /^[A-Za-z0-9_-]{8,64}$/;
+
+/** Validates an incoming request (SEC-3). Returns an error message or null. */
+export function validateRequest(value: unknown): string | null {
+  if (!isObject(value)) return "request must be an object";
+  if (value.v !== PROTOCOL_VERSION) return `unsupported protocol version: ${String(value.v)}`;
+  if (typeof value.id !== "number" || !Number.isSafeInteger(value.id)) return "id must be an integer";
+  if (typeof value.plugin !== "string" || !isName(value.plugin)) return "invalid plugin name";
+  if (typeof value.method !== "string" || !isName(value.method)) return "invalid method name";
+  if (value.doc !== undefined && (typeof value.doc !== "string" || !isDocumentId(value.doc)))
+    return "invalid document id";
+  if (
+    (value.method === LISTEN || value.method === UNLISTEN) &&
+    !(isObject(value.args) && typeof value.args.event === "string")
+  ) {
+    return `${value.method} requires args.event`;
+  }
+  if (value.plugin === BRIDGE_PLUGIN) {
+    const args = isObject(value.args) ? value.args : {};
+    if (value.method === CANCEL) {
+      if (typeof args.id !== "number" || !Number.isSafeInteger(args.id)) return "$bridge.cancel requires args.id";
+      if (args.reason !== undefined && !CANCEL_REASONS.includes(args.reason as CancelReason))
+        return "$bridge.cancel: reason must be abort or timeout";
+    } else if (value.method === RELEASE) {
+      if (typeof args.url !== "string") return "$bridge.release requires args.url";
+    } else return `unknown bridge operation $bridge.${value.method}`;
+  }
+  return null;
+}
+
+export function isResponse(value: unknown): value is BridgeResponse {
+  return (
+    isObject(value) && value.v === PROTOCOL_VERSION && typeof value.id === "number" && typeof value.ok === "boolean"
+  );
+}
+
+export function isEvent(value: unknown): value is BridgeEvent {
+  return (
+    isObject(value) &&
+    value.v === PROTOCOL_VERSION &&
+    typeof value.plugin === "string" &&
+    typeof value.event === "string"
+  );
+}
+
+export function okResponse(id: number, result?: unknown): BridgeResponse {
+  return result === undefined ? { v: 1, id, ok: true } : { v: 1, id, ok: true, result };
+}
+
+export function errorResponse(
+  id: number,
+  code: ErrorCode,
+  message: string,
+  extra?: { data?: unknown; retryable?: boolean },
+): BridgeResponse {
+  const error: BridgeErrorBody = { code, message };
+  if (extra?.data !== undefined) error.data = extra.data;
+  if (extra?.retryable) error.retryable = true;
+  return { v: 1, id, ok: false, error };
+}
+
+export { INIT_PREFIX, INIT_SUFFIX };
+
+export function renderInitScript(bootJson: string, envJson: string): string {
+  return `${INIT_PREFIX}${bootJson},${envJson}${INIT_SUFFIX}`;
+}
+
+/** Reserved plugin id for forwarding page console output to the host log in dev builds (WV-3). */
+export const CONSOLE_PLUGIN = "$console";
+
+/** Reserved plugin id for shell built-ins the page runtime calls itself, e.g. `print` (plugins.md D8). */
+export const HOST_PLUGIN = "$host";