@econ-v1/rpc 6.6.0 → 6.10.0

package/src/message-port-client.js

@@ -0,0 +1,628 @@
+// @ts-check
+import {
+  DomainError,
+  TransportError,
+} from "@econ-v1/domain";
+
+import { isJsonValue } from "./errors.js";
+import {
+  deserializeRpcEvent,
+  deserializeRpcResponse,
+  serializeRpcRequest,
+} from "./protocol.js";
+
+/** @typedef {import("@econ-v1/domain").DomainEvent} DomainEvent */
+/** @typedef {import("@econ-v1/domain").JsonValue} JsonValue */
+/** @typedef {import("@econ-v1/domain").KernelEventType} KernelEventType */
+/** @typedef {import("@econ-v1/domain").QueryName} QueryName */
+/** @typedef {import("./client.js").KernelRpcClient} KernelRpcClient */
+/** @typedef {import("./client.js").PreparedStage} PreparedStage */
+/** @typedef {import("./client.js").StageRpcSession} StageRpcSession */
+/** @typedef {import("./client.js").Unsubscribe} Unsubscribe */
+/** @typedef {import("./protocol.js").RpcRequest} RpcRequest */
+/** @typedef {RpcRequest extends infer TRequest ? TRequest extends RpcRequest ? Omit<TRequest, "id"> : never : never} RpcRequestWithoutId */
+/** @typedef {import("./transport.js").RpcTransport} RpcTransport */
+/** @typedef {{ readonly reject: (error: unknown) => void, readonly resolve: (value: JsonValue) => void, readonly sessionId: string | undefined, readonly timeoutId: ReturnType<typeof globalThis.setTimeout> }} PendingRequest */
+/** @typedef {{ readonly eventType: KernelEventType, readonly listeners: Set<(event: DomainEvent) => void>, readonly sessionId: string | undefined, readonly subscriptionId: string }} EventGroup */
+/** @typedef {{ readonly listeners: Set<(diff: import("@econ-v1/domain").QueryDiff<JsonValue>) => void>, readonly name: QueryName, readonly params: JsonValue, readonly sessionId: string | undefined, readonly subscriptionId: string }} LiveQueryGroup */
+/** @typedef {{ readonly now?: () => string, readonly requestTimeoutMs?: number }} MessagePortKernelRpcClientOptions */
+
+/**
+ * A subscribe request the kernel refused. The group is dropped either way,
+ * but reporting the refusal keeps a silent subscription outage observable.
+ *
+ * @param {"event" | "live-query"} kind
+ * @param {string} resource
+ * @param {string | undefined} sessionId
+ * @param {unknown} error
+ */
+function warnSubscriptionRejected(kind, resource, sessionId, error) {
+  const reason = error instanceof Error ? error.message : String(error);
+  const owner = sessionId === undefined ? "shell" : `stage session ${sessionId}`;
+  console.warn(
+    `[kernel-rpc] ${kind} subscription to "${resource}" was rejected for the ${owner} ` +
+      `and has been dropped — nothing will be delivered: ${reason}`,
+  );
+}
+
+/**
+ * A single kernel RPC request exceeded its local response deadline. This is deliberately
+ * distinct from connection loss: the transport remains usable and callers may retry.
+ */
+export class KernelRpcTimeoutError extends Error {
+  /** @readonly @type {string} */
+  commandName;
+  /** @readonly @type {string} */
+  correlationId;
+  /** @readonly @type {number} */
+  timeoutMs;
+
+  /**
+   * @param {string} commandName
+   * @param {string} correlationId
+   * @param {number} timeoutMs
+   */
+  constructor(commandName, correlationId, timeoutMs) {
+    super(`Kernel RPC "${commandName}" (${correlationId}) timed out after ${timeoutMs}ms; the request may be retried`);
+    this.name = "KernelRpcTimeoutError";
+    this.commandName = commandName;
+    this.correlationId = correlationId;
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+// Kernel RPC is local, but stage work can cross browser/worker scheduling boundaries.
+// Thirty seconds bounds dropped fire-and-forget messages without penalizing slow devices.
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+
+/** @implements {KernelRpcClient} */
+export class MessagePortKernelRpcClient {
+  /** @type {Map<string, EventGroup>} */
+  #eventGroupsByKey = new Map();
+  /** @type {Map<string, EventGroup>} */
+  #eventGroupsBySubscription = new Map();
+  /** @type {Map<string, LiveQueryGroup>} */
+  #liveGroupsByKey = new Map();
+  /** @type {Map<string, LiveQueryGroup>} */
+  #liveGroupsBySubscription = new Map();
+  /** @type {() => string} */
+  #now;
+  /** @type {Map<string, PendingRequest>} */
+  #pending = new Map();
+  /** @type {number} */
+  #requestTimeoutMs;
+  /** @type {RpcTransport} */
+  #transport;
+  /** @type {() => void} */
+  #unsubscribeClose;
+  /** @type {() => void} */
+  #unsubscribeMessages;
+  #closed = false;
+  #nextRequestId = 1;
+  #nextSubscriptionId = 1;
+
+  /**
+   * @param {RpcTransport} transport
+   * @param {MessagePortKernelRpcClientOptions} [options]
+   */
+  constructor(transport, options = {}) {
+    this.#transport = transport;
+    this.#now = options.now ?? (() => new Date().toISOString());
+    this.#requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    this.#unsubscribeMessages = transport.subscribe((message) => this.#handleMessage(message));
+    this.#unsubscribeClose = transport.subscribeClose(() => this.#handleClose());
+  }
+
+  close() {
+    if (this.#closed) return;
+    this.#transport.close();
+    this.#handleClose();
+  }
+
+  /**
+   * @template T
+   * @param {string} name
+   * @param {unknown} payload
+   * @returns {Promise<T>}
+   */
+  async command(name, payload) {
+    return /** @type {T} */ (await this.#request({ name, payload: jsonValue(payload, "command payload"), type: "command" }));
+  }
+
+  /**
+   * @template T
+   * @param {QueryName} name
+   * @param {unknown} params
+   * @param {(diff: import("@econ-v1/domain").QueryDiff<T>) => void} listener
+   * @returns {Unsubscribe}
+   */
+  liveQuery(name, params, listener) {
+    return this.#subscribeLiveQuery(undefined, name, jsonValue(params, "live-query params"), listener);
+  }
+
+  /**
+   * @param {string} appName
+   * @param {string} manifestSha256
+   * @returns {Promise<StageRpcSession>}
+   */
+  async openStageSession(appName, manifestSha256) {
+    const value = await this.#request({ appName, manifestSha256, type: "stage.open-session" });
+    if (!isRecord(value) || typeof value.sessionId !== "string") {
+      throw new DomainError({ code: "invalid_request", message: "Invalid stage session response" });
+    }
+    return new BoundStageRpcSession(this, value.sessionId);
+  }
+
+  /**
+   * @param {string} appName
+   * @returns {Promise<PreparedStage>}
+   */
+  async prepareStage(appName) {
+    const value = await this.#request({ appName, type: "stage.prepare" });
+    if (
+      !isRecord(value) ||
+      typeof value.appName !== "string" ||
+      typeof value.entryUrl !== "string" ||
+      typeof value.manifestSha256 !== "string" ||
+      typeof value.version !== "string"
+    ) {
+      throw new DomainError({ code: "invalid_request", message: "Invalid prepared stage response" });
+    }
+    return {
+      appName: value.appName,
+      entryUrl: value.entryUrl,
+      manifestSha256: value.manifestSha256,
+      version: value.version,
+    };
+  }
+
+  /**
+   * @template {KernelEventType} T
+   * @param {T} type
+   * @param {import("@econ-v1/domain").KernelEventPayload<T>} payload
+   * @returns {Promise<void>}
+   */
+  publish(type, payload) {
+    const event = /** @type {DomainEvent} */ (jsonValue({ occurredAt: this.#now(), payload, type }, "domain event"));
+    return this.#request({ event, type: "event.publish" }).then(() => undefined);
+  }
+
+  /**
+   * @template T
+   * @param {QueryName} name
+   * @param {unknown} params
+   * @returns {Promise<T>}
+   */
+  async query(name, params) {
+    return /** @type {T} */ (await this.#request({ name, params: jsonValue(params, "query params"), type: "query" }));
+  }
+
+  /**
+   * @template {KernelEventType} T
+   * @param {T} type
+   * @param {(event: import("@econ-v1/domain").KernelEventByType<T>) => void} listener
+   * @returns {Unsubscribe}
+   */
+  subscribe(type, listener) {
+    return this.#subscribeEvent(undefined, type, listener);
+  }
+
+  /** @param {string} sessionId */
+  closeStageSession(sessionId) {
+    const error = new TransportError({ code: "connection_lost", message: "Stage RPC session closed" });
+    for (const [requestId, pending] of [...this.#pending]) {
+      if (pending.sessionId === sessionId) {
+        this.#takePending(requestId)?.reject(error);
+      }
+    }
+    this.#removeSessionSubscriptions(sessionId);
+    void this.#request({ sessionId, type: "stage.close-session" }).catch(() => undefined);
+  }
+
+  /**
+   * @template T
+   * @param {string} sessionId
+   * @param {string} capability
+   * @param {unknown} payload
+   * @returns {Promise<T>}
+   */
+  invokeStageCapability(sessionId, capability, payload) {
+    return /** @type {Promise<T>} */ (this.#request({
+      capability,
+      payload: jsonValue(payload, "capability payload"),
+      sessionId,
+      type: "stage.capability.invoke",
+    }));
+  }
+
+  /**
+   * @template T
+   * @param {string} sessionId
+   * @param {QueryName} name
+   * @param {unknown} params
+   * @param {(diff: import("@econ-v1/domain").QueryDiff<T>) => void} listener
+   * @returns {Unsubscribe}
+   */
+  liveQueryStage(sessionId, name, params, listener) {
+    return this.#subscribeLiveQuery(sessionId, name, jsonValue(params, "live-query params"), listener);
+  }
+
+  /**
+   * @template {KernelEventType} T
+   * @param {string} sessionId
+   * @param {T} type
+   * @param {import("@econ-v1/domain").KernelEventPayload<T>} payload
+   * @returns {Promise<void>}
+   */
+  publishStage(sessionId, type, payload) {
+    const event = /** @type {DomainEvent} */ (jsonValue({ occurredAt: this.#now(), payload, type }, "domain event"));
+    return this.#request({ event, sessionId, type: "stage.event.publish" }).then(() => undefined);
+  }
+
+  /**
+   * @template T
+   * @param {string} sessionId
+   * @param {QueryName} name
+   * @param {unknown} params
+   * @returns {Promise<T>}
+   */
+  queryStage(sessionId, name, params) {
+    return /** @type {Promise<T>} */ (this.#request({
+      name,
+      params: jsonValue(params, "query params"),
+      sessionId,
+      type: "stage.query",
+    }));
+  }
+
+  /**
+   * @template {KernelEventType} T
+   * @param {string} sessionId
+   * @param {T} type
+   * @param {(event: import("@econ-v1/domain").KernelEventByType<T>) => void} listener
+   * @returns {Unsubscribe}
+   */
+  subscribeStage(sessionId, type, listener) {
+    return this.#subscribeEvent(sessionId, type, listener);
+  }
+
+  #handleClose() {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#unsubscribeMessages();
+    this.#unsubscribeClose();
+    const error = new TransportError({ code: "connection_lost", message: "Kernel RPC port closed" });
+    for (const requestId of [...this.#pending.keys()]) this.#takePending(requestId)?.reject(error);
+    this.#eventGroupsByKey.clear();
+    this.#eventGroupsBySubscription.clear();
+    this.#liveGroupsByKey.clear();
+    this.#liveGroupsBySubscription.clear();
+  }
+
+  /** @param {string} message */
+  #handleMessage(message) {
+    /** @type {unknown} */
+    let envelope;
+    try {
+      envelope = JSON.parse(message);
+    } catch {
+      return;
+    }
+
+    if (isRecord(envelope) && "id" in envelope) {
+      const responseId = typeof envelope.id === "string" ? envelope.id : undefined;
+      try {
+        const response = deserializeRpcResponse(message);
+        const pending = this.#takePending(response.id);
+        if (pending === undefined) return;
+        if (response.ok) pending.resolve(response.value);
+        else pending.reject(response.error);
+        return;
+      } catch {
+        if (responseId !== undefined) {
+          const pending = this.#takePending(responseId);
+          if (pending !== undefined) {
+            pending.reject(new DomainError({ code: "invalid_request", message: "Malformed kernel RPC response" }));
+          }
+        }
+        return;
+      }
+    }
+
+    try {
+      const event = deserializeRpcEvent(message);
+      if (event.type === "kernel.event") {
+        const group = this.#eventGroupsBySubscription.get(event.subscriptionId);
+        if (group === undefined || group.eventType !== event.event.type) return;
+        // The protocol decoder accepts the current device-cleanup core event even when a
+        // consumer resolves an older published domain declaration. Runtime listeners still
+        // receive the same domain-event shape; keep this boundary explicit until declarations
+        // are regenerated from the current source package.
+        for (const listener of [...group.listeners]) {
+          this.#notify(() => listener(/** @type {DomainEvent} */ (event.event)));
+        }
+        return;
+      }
+      const group = this.#liveGroupsBySubscription.get(event.subscriptionId);
+      if (group === undefined) return;
+      for (const listener of [...group.listeners]) this.#notify(() => listener(event.diff));
+    } catch {
+      // Malformed or stale port messages are isolated from valid pending requests.
+    }
+  }
+
+  /** @param {() => void} listener */
+  #notify(listener) {
+    try {
+      listener();
+    } catch {
+      // One UI listener must not suppress later listeners on the same RPC subscription.
+    }
+  }
+
+  /**
+   * @param {string} requestId
+   * @returns {PendingRequest | undefined}
+   */
+  #takePending(requestId) {
+    const pending = this.#pending.get(requestId);
+    if (pending === undefined) return undefined;
+    this.#pending.delete(requestId);
+    globalThis.clearTimeout(pending.timeoutId);
+    return pending;
+  }
+
+  /** @param {string} sessionId */
+  #removeSessionSubscriptions(sessionId) {
+    for (const [key, group] of [...this.#eventGroupsByKey]) {
+      if (group.sessionId === sessionId) {
+        this.#eventGroupsByKey.delete(key);
+        this.#eventGroupsBySubscription.delete(group.subscriptionId);
+      }
+    }
+    for (const [key, group] of [...this.#liveGroupsByKey]) {
+      if (group.sessionId === sessionId) {
+        this.#liveGroupsByKey.delete(key);
+        this.#liveGroupsBySubscription.delete(group.subscriptionId);
+      }
+    }
+  }
+
+  /**
+   * @param {RpcRequestWithoutId} request
+   * @returns {Promise<JsonValue>}
+   */
+  #request(request) {
+    if (this.#closed || this.#transport.state !== "open") {
+      return Promise.reject(new TransportError({ code: "connection_lost", message: "Kernel RPC port is closed" }));
+    }
+    const id = `request-${this.#nextRequestId}`;
+    this.#nextRequestId += 1;
+    return new Promise((resolve, reject) => {
+      const sessionId = "sessionId" in request ? request.sessionId : undefined;
+      const commandName = "name" in request
+        ? request.name
+        : "capability" in request ? request.capability : request.type;
+      const timeoutId = globalThis.setTimeout(() => {
+        this.#takePending(id)?.reject(new KernelRpcTimeoutError(commandName, id, this.#requestTimeoutMs));
+      }, this.#requestTimeoutMs);
+      this.#pending.set(id, { reject, resolve, sessionId, timeoutId });
+      try {
+        this.#transport.send(serializeRpcRequest(/** @type {RpcRequest} */ ({ ...request, id })));
+      } catch (error) {
+        const sendError = error instanceof TransportError
+          ? error
+          : new TransportError({ code: "connection_lost", message: "Kernel RPC send failed" });
+        this.#takePending(id)?.reject(sendError);
+      }
+    });
+  }
+
+  /**
+   * @template {KernelEventType} T
+   * @param {string | undefined} sessionId
+   * @param {T} eventType
+   * @param {(event: import("@econ-v1/domain").KernelEventByType<T>) => void} listener
+   * @returns {Unsubscribe}
+   */
+  #subscribeEvent(sessionId, eventType, listener) {
+    const key = `${sessionId ?? "host"}:event:${eventType}`;
+    let group = this.#eventGroupsByKey.get(key);
+    if (group === undefined) {
+      const subscriptionId = this.#newSubscriptionId();
+      group = { eventType, listeners: new Set(), sessionId, subscriptionId };
+      this.#eventGroupsByKey.set(key, group);
+      this.#eventGroupsBySubscription.set(subscriptionId, group);
+      const request = sessionId === undefined
+        ? /** @type {const} */ ({ eventType, subscriptionId, type: "event.subscribe" })
+        : /** @type {const} */ ({ eventType, sessionId, subscriptionId, type: "stage.event.subscribe" });
+      void this.#request(request).catch((error) => {
+        this.#dropEventGroup(key, /** @type {EventGroup} */ (group));
+        warnSubscriptionRejected("event", eventType, sessionId, error);
+      });
+    }
+    const storedListener = /** @type {(event: DomainEvent) => void} */ (listener);
+    group.listeners.add(storedListener);
+    let active = true;
+    return () => {
+      if (!active) return;
+      active = false;
+      group?.listeners.delete(storedListener);
+      if (group !== undefined && group.listeners.size === 0) {
+        this.#dropEventGroup(key, group);
+        const request = sessionId === undefined
+          ? /** @type {const} */ ({ subscriptionId: group.subscriptionId, type: "event.unsubscribe" })
+          : /** @type {const} */ ({ sessionId, subscriptionId: group.subscriptionId, type: "stage.event.unsubscribe" });
+        void this.#request(request).catch(() => undefined);
+      }
+    };
+  }
+
+  /**
+   * @template T
+   * @param {string | undefined} sessionId
+   * @param {QueryName} name
+   * @param {JsonValue} params
+   * @param {(diff: import("@econ-v1/domain").QueryDiff<T>) => void} listener
+   * @returns {Unsubscribe}
+   */
+  #subscribeLiveQuery(sessionId, name, params, listener) {
+    const key = `${sessionId ?? "host"}:live:${name}:${JSON.stringify(params)}`;
+    let group = this.#liveGroupsByKey.get(key);
+    if (group === undefined) {
+      const subscriptionId = this.#newSubscriptionId();
+      group = { listeners: new Set(), name, params, sessionId, subscriptionId };
+      this.#liveGroupsByKey.set(key, group);
+      this.#liveGroupsBySubscription.set(subscriptionId, group);
+      const request = sessionId === undefined
+        ? /** @type {const} */ ({ name, params, subscriptionId, type: "live-query.subscribe" })
+        : /** @type {const} */ ({ name, params, sessionId, subscriptionId, type: "stage.live-query.subscribe" });
+      void this.#request(request).catch((error) => {
+        this.#dropLiveGroup(key, /** @type {LiveQueryGroup} */ (group));
+        warnSubscriptionRejected("live-query", name, sessionId, error);
+      });
+    }
+    const storedListener = /** @type {(diff: import("@econ-v1/domain").QueryDiff<JsonValue>) => void} */ (listener);
+    group.listeners.add(storedListener);
+    let active = true;
+    return () => {
+      if (!active) return;
+      active = false;
+      group?.listeners.delete(storedListener);
+      if (group !== undefined && group.listeners.size === 0) {
+        this.#dropLiveGroup(key, group);
+        const request = sessionId === undefined
+          ? /** @type {const} */ ({ subscriptionId: group.subscriptionId, type: "live-query.unsubscribe" })
+          : /** @type {const} */ ({ sessionId, subscriptionId: group.subscriptionId, type: "stage.live-query.unsubscribe" });
+        void this.#request(request).catch(() => undefined);
+      }
+    };
+  }
+
+  /**
+   * @param {string} key
+   * @param {EventGroup} group
+   */
+  #dropEventGroup(key, group) {
+    if (this.#eventGroupsByKey.get(key) === group) this.#eventGroupsByKey.delete(key);
+    this.#eventGroupsBySubscription.delete(group.subscriptionId);
+  }
+
+  /**
+   * @param {string} key
+   * @param {LiveQueryGroup} group
+   */
+  #dropLiveGroup(key, group) {
+    if (this.#liveGroupsByKey.get(key) === group) this.#liveGroupsByKey.delete(key);
+    this.#liveGroupsBySubscription.delete(group.subscriptionId);
+  }
+
+  /** @returns {string} */
+  #newSubscriptionId() {
+    const id = `subscription-${this.#nextSubscriptionId}`;
+    this.#nextSubscriptionId += 1;
+    return id;
+  }
+}
+
+/** @implements {StageRpcSession} */
+class BoundStageRpcSession {
+  /** @type {MessagePortKernelRpcClient} */
+  #client;
+  /** @type {string} */
+  #sessionId;
+  #closed = false;
+
+  /**
+   * @param {MessagePortKernelRpcClient} client
+   * @param {string} sessionId
+   */
+  constructor(client, sessionId) {
+    this.#client = client;
+    this.#sessionId = sessionId;
+  }
+
+  close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#client.closeStageSession(this.#sessionId);
+  }
+
+  /**
+   * @template T
+   * @param {string} capability
+   * @param {unknown} payload
+   * @returns {Promise<T>}
+   */
+  invokeCapability(capability, payload) {
+    this.#assertOpen();
+    return this.#client.invokeStageCapability(this.#sessionId, capability, payload);
+  }
+
+  /**
+   * @template T
+   * @param {QueryName} name
+   * @param {unknown} params
+   * @param {(diff: import("@econ-v1/domain").QueryDiff<T>) => void} listener
+   * @returns {Unsubscribe}
+   */
+  liveQuery(name, params, listener) {
+    this.#assertOpen();
+    return this.#client.liveQueryStage(this.#sessionId, name, params, listener);
+  }
+
+  /**
+   * @template {KernelEventType} T
+   * @param {T} type
+   * @param {import("@econ-v1/domain").KernelEventPayload<T>} payload
+   * @returns {Promise<void>}
+   */
+  publish(type, payload) {
+    this.#assertOpen();
+    return this.#client.publishStage(this.#sessionId, type, payload);
+  }
+
+  /**
+   * @template T
+   * @param {QueryName} name
+   * @param {unknown} params
+   * @returns {Promise<T>}
+   */
+  query(name, params) {
+    this.#assertOpen();
+    return this.#client.queryStage(this.#sessionId, name, params);
+  }
+
+  /**
+   * @template {KernelEventType} T
+   * @param {T} type
+   * @param {(event: import("@econ-v1/domain").KernelEventByType<T>) => void} listener
+   * @returns {Unsubscribe}
+   */
+  subscribe(type, listener) {
+    this.#assertOpen();
+    return this.#client.subscribeStage(this.#sessionId, type, listener);
+  }
+
+  #assertOpen() {
+    if (this.#closed) throw new TransportError({ code: "connection_lost", message: "Stage RPC session is closed" });
+  }
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} label
+ * @returns {JsonValue}
+ */
+function jsonValue(value, label) {
+  if (isJsonValue(value)) return value;
+  throw new DomainError({ code: "validation_failed", message: `${label} must be JSON-serializable` });
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Readonly<Record<string, unknown>>}
+ */
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/node-app-memory-contract.js

@@ -0,0 +1,10 @@
+// @ts-check
+
+export const NODE_APP_MEMORY_LIST_QUERY = "node-app-memory.list.v1";
+export const NODE_APP_MEMORY_DETAIL_QUERY = "node-app-memory.detail.v1";
+export const NODE_APP_MEMORY_OVERVIEW_QUERY = "node-app-memory.overview.v1";
+export const NODE_APP_MEMORY_CAPTURE_COMMAND = "node-app-memory.capture.v1";
+export const NODE_APP_MEMORY_STATUS_COMMAND = "node-app-memory.status.v1";
+export const NODE_APP_MEMORY_DOWNLOAD_COMMAND = "node-app-memory.download.v1";
+
+/** @typedef {{ readonly id: string }} NodeAppMemoryDetailQueryParams */