@qping/plugin-bus 0.1.0 → 0.2.0

package/src/protocol.ts

@@ -6,25 +6,90 @@
  *
  * Field names are camelCase on the wire (System.Text.Json camelCase policy on the C# side).
  * Null fields are omitted on the wire (WhenWritingNull).
+ *
+ * Runtime constants mirror MyTools.Protocol (MessageKindWire, Routes, EndpointIds,
+ * ProtocolVersion.CurrentWire). Do not re-hardcode those strings in SDK source.
  */
 
-export type MessageKind = "request" | "response" | "event";
+export const MessageKind = {
+  Request: "request",
+  Response: "response",
+  Event: "event",
+} as const;
+export type MessageKind = (typeof MessageKind)[keyof typeof MessageKind];
+
+export const ErrorCode = {
+  ProtocolMismatch: "ProtocolMismatch",
+  HandshakeFailed: "HandshakeFailed",
+  CapabilityNotDeclared: "CapabilityNotDeclared",
+  CapabilityDenied: "CapabilityDenied",
+  InvalidPayload: "InvalidPayload",
+  MessageTooLarge: "MessageTooLarge",
+  RouteNotFound: "RouteNotFound",
+  RequestTimeout: "RequestTimeout",
+  TooManyRequests: "TooManyRequests",
+  TransportDisconnected: "TransportDisconnected",
+  PluginUnavailable: "PluginUnavailable",
+  InternalError: "InternalError",
+  Cancelled: "Cancelled",
+  RateLimited: "RateLimited",
+} as const;
+export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+
+export const ProtocolVersion = "3.0";
+
+export const EndpointIds = {
+  NodeMain: "node-main",
+  Host: "host",
+} as const;
+
+export const Routes = {
+  Bus: {
+    Handshake: "bus.handshake",
+    Ping: "bus.ping",
+    Cancel: "bus.cancel",
+    Subscribe: "bus.subscribe",
+    Unsubscribe: "bus.unsubscribe",
+  },
+  Prefix: {
+    PluginCall: "plugin.call.",
+    HostCall: "host.call.",
+    PluginEvent: "plugin.event.",
+    HostEvent: "host.event.",
+    Diagnostics: "diagnostics.",
+  },
+  PluginCall: {
+    Initialize: "plugin.call.initialize",
+    Search: "plugin.call.search",
+    InvokeAction: "plugin.call.invokeAction",
+  },
+  HostEvent: {
+    Initialize: "host.event.initialize",
+    Search: "host.event.search",
+    Key: "host.event.key",
+    LanguageChanged: "host.event.languageChanged",
+    ThemeChanged: "host.event.themeChanged",
+    InputActionCaptured: "host.event.inputActionCaptured",
+  },
+} as const;
 
-export type ErrorCode =
-  | "ProtocolMismatch"
-  | "HandshakeFailed"
-  | "CapabilityNotDeclared"
-  | "CapabilityDenied"
-  | "InvalidPayload"
-  | "MessageTooLarge"
-  | "RouteNotFound"
-  | "RequestTimeout"
-  | "TooManyRequests"
-  | "TransportDisconnected"
-  | "PluginUnavailable"
-  | "InternalError"
-  | "Cancelled"
-  | "RateLimited";
+export function pluginCallRoute(method: string): string {
+  return method.startsWith(Routes.Prefix.PluginCall)
+    ? method
+    : `${Routes.Prefix.PluginCall}${method}`;
+}
+
+export function hostCallRoute(method: string): string {
+  return method.startsWith(Routes.Prefix.HostCall)
+    ? method
+    : `${Routes.Prefix.HostCall}${method}`;
+}
+
+export function pluginEventRoute(subjectId: string): string {
+  return subjectId.startsWith(Routes.Prefix.PluginEvent)
+    ? subjectId
+    : `${Routes.Prefix.PluginEvent}${subjectId}`;
+}
 
 export interface BusError {
   code: ErrorCode;
@@ -38,7 +103,7 @@ export interface BusError {
  * required; the optional ones are omitted on the wire when null.
  */
 export interface Envelope {
-  version: string; // e.g. "3.0"
+  version: string; // e.g. ProtocolVersion
   id: string;
   correlationId?: string | null;
   traceId: string;

package/src/router.ts

@@ -4,8 +4,17 @@
  * and correlate their responses. Mirrors the C# MessageBus routing rules on the Node side.
  */
 
+import { AsyncLocalStorage } from "node:async_hooks";
 import { randomBytes } from "node:crypto";
-import type { Envelope, BusError } from "./protocol.ts";
+import {
+  type Envelope,
+  type BusError,
+  EndpointIds,
+  ErrorCode,
+  MessageKind,
+  ProtocolVersion,
+  Routes,
+} from "./protocol.ts";
 
 type Handler = (payload: unknown) => Promise<unknown> | unknown;
 type Sender = (env: Envelope) => void;
@@ -16,13 +25,46 @@ interface PendingHostCall {
   route: string;
 }
 
+type RequestScope = { deadlineMs: number | null };
+
+const requestScope = new AsyncLocalStorage<RequestScope>();
+
+export const DefaultHostCallTimeoutMs = 30_000;
+
+/** Remaining ms of the inbound plugin.call timeout, if currently inside a request. */
+export function remainingTimeoutMs(): number | undefined {
+  const scope = requestScope.getStore();
+  if (!scope || scope.deadlineMs == null) {
+    return undefined;
+  }
+
+  return scope.deadlineMs - Date.now();
+}
+
+export function resolveHostCallTimeoutMs(explicit?: number): number {
+  const remaining = remainingTimeoutMs();
+  if (explicit != null) {
+    return remaining == null ? explicit : Math.min(explicit, remaining);
+  }
+
+  return remaining ?? DefaultHostCallTimeoutMs;
+}
+
+function deadlineFromTimeoutMs(timeoutMs: number | null | undefined): number | null {
+  if (typeof timeoutMs !== "number" || timeoutMs <= 0) {
+    return null;
+  }
+
+  return Date.now() + timeoutMs;
+}
+
 export class HandlerRouter {
   private handlers = new Map<string, Handler>();
   private pendingHostCalls = new Map<string, PendingHostCall>();
   private pluginId = "p";
   private entryId = "e";
   private sessionId = "s";
-  private endpointId = "node-main";
+  private endpointId: string = EndpointIds.NodeMain;
 
   /** Injected transport send fn; tests can override `router.send` directly. */
   send: Sender;
@@ -45,48 +87,54 @@ export class HandlerRouter {
 
   /** Dispatches an inbound request/response. Returns once handled. */
   async dispatch(env: Envelope): Promise<void> {
-    if (env.kind === "response") {
+    if (env.kind === MessageKind.Response) {
       this.handleHostResponse(env);
       return;
     }
-    if (env.kind !== "request") return;
+    if (env.kind !== MessageKind.Request) return;
 
     // bus.ping is always auto-replied; it does not occupy a handler slot.
-    if (env.route === "bus.ping") {
+    if (env.route === Routes.Bus.Ping) {
       this.send(this.responseFor(env, { ok: true }));
       return;
     }
 
     const handler = this.handlers.get(env.route);
     if (!handler) {
-      this.send(this.errorResponseFor(env, "RouteNotFound", `route '${env.route}' has no handler`));
+      this.send(this.errorResponseFor(env, ErrorCode.RouteNotFound, `route '${env.route}' has no handler`));
       return;
     }
 
+    const deadlineMs = deadlineFromTimeoutMs(env.timeoutMs);
     try {
-      const result = await handler(env.payload);
+      const result = await requestScope.run({ deadlineMs }, () => handler(env.payload));
       this.send(this.responseFor(env, result ?? {}));
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
-      this.send(this.errorResponseFor(env, "InternalError", message));
+      this.send(this.errorResponseFor(env, ErrorCode.InternalError, message));
     }
   }
 
   /** Calls a host.call.* capability and resolves with the response payload. */
-  callHost(route: string, payload: unknown, timeoutMs = 30000): Promise<unknown> {
+  callHost(route: string, payload: unknown, timeoutMs?: number): Promise<unknown> {
+    const effectiveTimeoutMs = resolveHostCallTimeoutMs(timeoutMs);
+    if (effectiveTimeoutMs <= 0) {
+      return Promise.reject(new Error(`host call ${route} timed out (no time remaining)`));
+    }
+
     return new Promise((resolve, reject) => {
       const id = randomBytesHex();
       const req: Envelope = {
-        version: "3.0",
+        version: ProtocolVersion,
         id,
         traceId: id,
         sessionId: this.sessionId,
         pluginId: this.pluginId,
         entryId: this.entryId,
         endpointId: this.endpointId,
-        kind: "request",
+        kind: MessageKind.Request,
         route,
-        timeoutMs,
+        timeoutMs: effectiveTimeoutMs,
         payload,
       };
       const pending: PendingHostCall = { resolve, reject, route };
@@ -94,10 +142,9 @@ export class HandlerRouter {
       const timer = setTimeout(() => {
         if (this.pendingHostCalls.has(id)) {
           this.pendingHostCalls.delete(id);
-          reject(new Error(`host call ${route} timed out after ${timeoutMs}ms`));
+          reject(new Error(`host call ${route} timed out after ${effectiveTimeoutMs}ms`));
         }
-      }, timeoutMs);
-      // Clear the timer when settled.
+      }, effectiveTimeoutMs);
       const origResolve = pending.resolve;
       const origReject = pending.reject;
       pending.resolve = (v) => { clearTimeout(timer); origResolve(v); };
@@ -120,7 +167,7 @@ export class HandlerRouter {
 
   private responseFor(req: Envelope, payload: unknown): Envelope {
     return {
-      version: "3.0",
+      version: ProtocolVersion,
       id: randomBytesHex(),
       correlationId: req.id,
       traceId: req.traceId,
@@ -128,13 +175,13 @@ export class HandlerRouter {
       pluginId: req.pluginId,
       entryId: req.entryId,
       endpointId: this.endpointId,
-      kind: "response",
+      kind: MessageKind.Response,
       route: req.route,
       payload,
     };
   }
 
-  private errorResponseFor(req: Envelope, code: string, message: string): Envelope {
+  private errorResponseFor(req: Envelope, code: BusError["code"], message: string): Envelope {
     return {
       ...this.responseFor(req, null),
       payload: undefined,

package/src/transport.ts

@@ -17,8 +17,9 @@ export class NodeTransport {
   private disconnectHandlers = new Set<DisconnectHandler>();
   private closed = false;
 
-  onMessage(handler: MessageHandler): void {
+  onMessage(handler: MessageHandler): () => void {
     this.messageHandlers.add(handler);
+    return () => { this.messageHandlers.delete(handler); };
   }
 
   onDisconnect(handler: DisconnectHandler): void {

package/src/webClient.ts

@@ -0,0 +1,285 @@
+/**
+ * v3 Web SDK: speaks protocol envelopes over chrome.webview.postMessage.
+ * Host stamps identity; the page does not supply plugin/entry/session ids.
+ *
+ * Connections start with bus.handshake. Subsequent plugin.call.* envelopes use the
+ * negotiated version. call("refresh") is sent as plugin.call.refresh.
+ */
+
+import { mytoolsI18n } from "./i18n.ts";
+import {
+  type Envelope,
+  type BusError,
+  MessageKind,
+  ProtocolVersion,
+  Routes,
+  pluginCallRoute,
+} from "./protocol.ts";
+import type { MyToolsThemePayload } from "./webTypes.ts";
+
+export { mytoolsI18n } from "./i18n.ts";
+export { HostEvents } from "./webTypes.ts";
+export type {
+  MyToolsHostInitializePayload,
+  MyToolsHostKeyPayload,
+  MyToolsHostSearchPayload,
+  MyToolsInputActionCapturedPayload,
+  MyToolsLanguageChangedPayload,
+  MyToolsThemeChangedPayload,
+  MyToolsThemePayload,
+} from "./webTypes.ts";
+
+type Pending = {
+  resolve: (value: unknown) => void;
+  reject: (err: Error) => void;
+};
+
+export interface WebBusClient {
+  /** Sends plugin.call.<method>. Bare names are prefixed; full routes are left as-is. */
+  call<T = unknown>(method: string, payload?: unknown, timeoutMs?: number): Promise<T>;
+  on<T = unknown>(route: string, handler: (payload: T) => void): () => void;
+  i18n: typeof mytoolsI18n;
+  theme: typeof mytoolsTheme;
+  close(): void;
+}
+
+const HandshakeTimeoutMs = 8_000;
+
+const mytoolsTheme = {
+  current: "dark",
+  apply(payload: MyToolsThemePayload): void {
+    if (typeof payload.theme === "string") {
+      this.current = payload.theme;
+    }
+    const root = typeof document !== "undefined" ? document.documentElement : null;
+    if (!root) {
+      return;
+    }
+    if (typeof payload.theme === "string") {
+      root.setAttribute("data-theme", payload.theme);
+      root.style.colorScheme = payload.theme;
+    }
+    if (payload.themeTokens) {
+      for (const [key, value] of Object.entries(payload.themeTokens)) {
+        if (typeof value === "string") {
+          root.style.setProperty(key, value);
+        }
+      }
+    }
+  },
+};
+
+function hasWebView(): boolean {
+  return !!(typeof window !== "undefined" && (window as any).chrome?.webview);
+}
+
+function post(env: Envelope): void {
+  if (!hasWebView()) throw new Error("chrome.webview is not available");
+  (window as any).chrome.webview.postMessage(env);
+}
+
+function randomId(): string {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+function parseMessage(data: unknown): Envelope | null {
+  if (typeof data === "string") {
+    try {
+      data = JSON.parse(data);
+    } catch {
+      return null;
+    }
+  }
+  if (!data || typeof data !== "object") return null;
+  const env = data as Envelope;
+  if (typeof env.kind !== "string" || typeof env.route !== "string") return null;
+  return env;
+}
+
+function applyHostSideEffects(env: Envelope): void {
+  const payload = env.payload;
+  if (!payload || typeof payload !== "object") return;
+  if (env.route === Routes.HostEvent.Initialize) {
+    mytoolsI18n.configure(payload);
+    mytoolsI18n.apply();
+    mytoolsTheme.apply(payload as MyToolsThemePayload);
+  } else if (env.route === Routes.HostEvent.LanguageChanged) {
+    mytoolsI18n.configure(payload);
+    mytoolsI18n.apply();
+  } else if (env.route === Routes.HostEvent.ThemeChanged) {
+    mytoolsTheme.apply(payload as MyToolsThemePayload);
+  }
+}
+
+function negotiatedVersionFrom(payload: unknown): string {
+  if (payload && typeof payload === "object" && "negotiatedVersion" in payload) {
+    const value = (payload as { negotiatedVersion?: unknown }).negotiatedVersion;
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return ProtocolVersion;
+}
+
+/**
+ * Creates a Web bus client. Registers the message listener immediately so host
+ * events that arrive before `on()` are buffered and replayed.
+ *
+ * Handshake is required before call(). Page scripts are bundled as IIFE, so this
+ * function is synchronous; handshake runs in the background and gates call().
+ */
+export function createWebBusClient(options?: {
+  timeoutMs?: number;
+}): WebBusClient {
+  const pending = new Map<string, Pending>();
+  const eventHandlers = new Set<(env: Envelope) => void>();
+  const lastByRoute = new Map<string, Envelope>();
+  const defaultTimeout = options?.timeoutMs ?? 30_000;
+  let wireVersion = ProtocolVersion;
+  let handshakeError: Error | null = null;
+
+  const onMessage = (event: MessageEvent) => {
+    const env = parseMessage(event.data);
+    if (!env) return;
+    if (env.kind === MessageKind.Response && env.correlationId) {
+      const p = pending.get(env.correlationId);
+      if (!p) return;
+      pending.delete(env.correlationId);
+      if (env.error) {
+        p.reject(new Error(`${(env.error as BusError).code}: ${(env.error as BusError).message}`));
+      } else {
+        p.resolve(env.payload);
+      }
+      return;
+    }
+    if (env.kind === MessageKind.Event) {
+      lastByRoute.set(env.route, env);
+      applyHostSideEffects(env);
+      for (const h of eventHandlers) h(env);
+    }
+  };
+
+  let handshakeDone: Promise<void> = Promise.resolve();
+  if (hasWebView()) {
+    (window as any).chrome.webview.addEventListener("message", onMessage);
+    handshakeDone = handshake(HandshakeTimeoutMs)
+      .then((version) => {
+        wireVersion = version;
+      })
+      .catch((err: unknown) => {
+        handshakeError = err instanceof Error ? err : new Error(String(err));
+        throw handshakeError;
+      });
+  }
+
+  function ensureHandshaken(): Promise<void> {
+    if (handshakeError) return Promise.reject(handshakeError);
+    return handshakeDone.then(() => {
+      if (handshakeError) throw handshakeError;
+    });
+  }
+
+  function call<T = unknown>(method: string, payload?: unknown, timeoutMs = defaultTimeout): Promise<T> {
+    const route = pluginCallRoute(method);
+    return ensureHandshaken().then(
+      () =>
+        new Promise<T>((resolve, reject) => {
+          const id = randomId();
+          const timer = window.setTimeout(() => {
+            pending.delete(id);
+            reject(new Error(`request timed out: ${route}`));
+          }, timeoutMs);
+          pending.set(id, {
+            resolve: (v) => {
+              window.clearTimeout(timer);
+              resolve(v as T);
+            },
+            reject: (e) => {
+              window.clearTimeout(timer);
+              reject(e);
+            },
+          });
+          post({
+            version: wireVersion,
+            id,
+            traceId: id,
+            sessionId: "",
+            pluginId: "",
+            entryId: "",
+            endpointId: "",
+            kind: MessageKind.Request,
+            route,
+            timeoutMs,
+            payload: payload ?? {},
+          });
+        }),
+    );
+  }
+
+  function subscribe(handler: (env: Envelope) => void): () => void {
+    eventHandlers.add(handler);
+    for (const env of lastByRoute.values()) handler(env);
+    return () => {
+      eventHandlers.delete(handler);
+    };
+  }
+
+  return {
+    call,
+    on: (route, handler) =>
+      subscribe((env) => {
+        if (env.route === route) handler((env.payload ?? {}) as never);
+      }),
+    i18n: mytoolsI18n,
+    theme: mytoolsTheme,
+    close: () => {
+      if (hasWebView()) {
+        (window as any).chrome.webview.removeEventListener("message", onMessage);
+      }
+      pending.clear();
+      eventHandlers.clear();
+      lastByRoute.clear();
+    },
+  };
+}
+
+function handshake(timeoutMs: number): Promise<string> {
+  const id = randomId();
+  return new Promise((resolve, reject) => {
+    const timer = window.setTimeout(() => {
+      cleanup();
+      reject(new Error("bus.handshake timed out"));
+    }, timeoutMs);
+
+    const onMessage = (event: MessageEvent) => {
+      const env = parseMessage(event.data);
+      if (!env || env.kind !== MessageKind.Response || env.correlationId !== id) return;
+      cleanup();
+      if (env.error) {
+        reject(new Error(`${env.error.code}: ${env.error.message}`));
+      } else {
+        resolve(negotiatedVersionFrom(env.payload));
+      }
+    };
+
+    const cleanup = () => {
+      window.clearTimeout(timer);
+      (window as any).chrome.webview.removeEventListener("message", onMessage);
+    };
+
+    (window as any).chrome.webview.addEventListener("message", onMessage);
+    post({
+      version: ProtocolVersion,
+      id,
+      traceId: id,
+      sessionId: "",
+      pluginId: "",
+      entryId: "",
+      endpointId: "web",
+      kind: MessageKind.Request,
+      route: Routes.Bus.Handshake,
+      timeoutMs,
+      payload: { version: ProtocolVersion, supportedVersions: [ProtocolVersion] },
+    });
+  });
+}

package/src/webTypes.ts

@@ -0,0 +1,52 @@
+import { Routes } from "./protocol.ts";
+
+export interface MyToolsHostInitializePayload {
+  protocolVersion: string;
+  pluginId: string;
+  version?: string;
+  itemId: string;
+  query: string;
+  keyword: string;
+  initialState: unknown;
+  locale: string;
+  fallbackLocale: string;
+  translationRevision: string;
+  messages: Record<string, string>;
+  theme?: string;
+  themeTokens?: Record<string, string>;
+}
+
+export interface MyToolsLanguageChangedPayload {
+  locale: string;
+  fallbackLocale: string;
+  translationRevision: string;
+  messages: Record<string, string>;
+}
+
+export interface MyToolsThemeChangedPayload {
+  theme: string;
+  themeTokens: Record<string, string>;
+}
+
+export interface MyToolsHostSearchPayload {
+  query: string;
+}
+
+export interface MyToolsHostKeyPayload {
+  key: string;
+}
+
+export interface MyToolsInputActionCapturedPayload {
+  requestId: string;
+  cancelled?: boolean;
+  kind?: "hotkey" | "mouse";
+  hotKey?: string | null;
+  mouseButton?: string | null;
+}
+
+export interface MyToolsThemePayload {
+  theme?: string;
+  themeTokens?: Record<string, string>;
+}
+
+export const HostEvents = Routes.HostEvent;

package/dist/bootstrap.d.mts

@@ -1 +0,0 @@
-export * from "../src/bootstrap.ts";

package/dist/protocol.d.mts

@@ -1 +0,0 @@
-export * from "../src/protocol.ts";

package/dist/server.d.mts

@@ -1 +0,0 @@
-export * from "../src/server.ts";