@qping/plugin-bus 0.1.0

package/src/framing.ts

@@ -0,0 +1,130 @@
+/**
+ * Length-prefixed framing for the v3 named-pipe transport, mirroring the C# FrameCodec/FrameDecoder.
+ * Wire format: [4-byte little-endian unsigned length][UTF-8 JSON payload].
+ *
+ * The incremental decoder handles fragmented, sticky and truncated streams, and rejects an oversize
+ * length prefix as fatal *before* allocating the payload buffer (so a malicious/buggy peer cannot
+ * force a huge allocation). After a fatal error the decoder stays dead.
+ */
+
+export const MAX_FRAME_BYTES = 4 * 1024 * 1024;
+export const PREFIX_BYTES = 4;
+
+/** Encodes a raw payload buffer into a length-prefixed frame. */
+export function encodeFrame(payload: Buffer): Buffer {
+  const length = payload.length;
+  const frame = Buffer.alloc(PREFIX_BYTES + length);
+  frame[0] = length & 0xff;
+  frame[1] = (length >> 8) & 0xff;
+  frame[2] = (length >> 16) & 0xff;
+  frame[3] = (length >> 24) & 0xff;
+  payload.copy(frame, PREFIX_BYTES);
+  return frame;
+}
+
+/** Encodes a UTF-8 JSON string into a length-prefixed frame. */
+export function encodeFrameString(json: string): Buffer {
+  return encodeFrame(Buffer.from(json, "utf8"));
+}
+
+export interface FrameFeedResult {
+  hasFrame: boolean;
+  payload: Buffer;
+  isFatal: boolean;
+}
+
+/**
+ * Incremental length-prefixed frame decoder. Feed byte chunks (fragmented/sticky/partial) and get
+ * back one complete payload at a time. Leftover bytes from a chunk that contained more than one
+ * frame are buffered internally and surfaced by subsequent feeds (including an empty buffer).
+ */
+export class FrameDecoder {
+  private prefixBuf = Buffer.alloc(PREFIX_BYTES);
+  private prefixFilled = 0;
+  private payload: Buffer | null = null;
+  private payloadFilled = 0;
+  private payloadLength = 0;
+  private fatal = false;
+  private pending: Buffer = Buffer.alloc(0);
+
+  feed(chunk: Buffer): FrameFeedResult {
+    const empty = { hasFrame: false, payload: Buffer.alloc(0), isFatal: false };
+    if (this.fatal) {
+      return { hasFrame: false, payload: Buffer.alloc(0), isFatal: true };
+    }
+
+    // Merge pending leftover with the new chunk into the working buffer.
+    let current: Buffer;
+    if (this.pending.length > 0) {
+      current = Buffer.concat([this.pending, chunk]);
+      this.pending = Buffer.alloc(0);
+    } else {
+      current = chunk;
+    }
+
+    let offset = 0;
+    while (offset < current.length) {
+      // Phase 1: accumulate the 4-byte length prefix.
+      if (this.payload === null) {
+        const need = PREFIX_BYTES - this.prefixFilled;
+        const take = Math.min(need, current.length - offset);
+        current.copy(this.prefixBuf, this.prefixFilled, offset, offset + take);
+        this.prefixFilled += take;
+        offset += take;
+
+        if (this.prefixFilled < PREFIX_BYTES) {
+          return empty; // still waiting for the full prefix
+        }
+
+        this.payloadLength =
+          this.prefixBuf[0] |
+          (this.prefixBuf[1] << 8) |
+          (this.prefixBuf[2] << 16) |
+          (this.prefixBuf[3] << 24);
+
+        if (this.payloadLength < 0 || this.payloadLength > MAX_FRAME_BYTES) {
+          this.fatal = true;
+          return { hasFrame: false, payload: Buffer.alloc(0), isFatal: true };
+        }
+        if (this.payloadLength === 0) {
+          this.reset();
+          // Buffer any leftover and return the empty frame.
+          this.bufferLeftover(current, offset);
+          return { hasFrame: true, payload: Buffer.alloc(0), isFatal: false };
+        }
+
+        this.payload = Buffer.alloc(this.payloadLength);
+        this.payloadFilled = 0;
+      }
+
+      // Phase 2: accumulate the payload.
+      const payloadNeed = this.payloadLength - this.payloadFilled;
+      const payloadTake = Math.min(payloadNeed, current.length - offset);
+      current.copy(this.payload!, this.payloadFilled, offset, offset + payloadTake);
+      this.payloadFilled += payloadTake;
+      offset += payloadTake;
+
+      if (this.payloadFilled >= this.payloadLength) {
+        const out = this.payload!;
+        this.reset();
+        this.bufferLeftover(current, offset);
+        return { hasFrame: true, payload: out, isFatal: false };
+      }
+    }
+
+    return empty;
+  }
+
+  private bufferLeftover(src: Buffer, offset: number): void {
+    if (offset < src.length) {
+      this.pending = src.subarray(offset);
+    }
+  }
+
+  private reset(): void {
+    this.prefixFilled = 0;
+    this.payload = null;
+    this.payloadFilled = 0;
+    this.payloadLength = 0;
+  }
+}

package/src/protocol.ts

@@ -0,0 +1,78 @@
+/**
+ * Hand-written TypeScript protocol types for the plugin message bus v3. These MUST stay
+ * byte-for-byte aligned with the C# types in MyTools.Protocol (see the canonical fixtures in
+ * MyTools.Protocol.Test/Fixtures/*.json). The drift-prevention self-check
+ * (fixtures-selfcheck.mjs) encodes/decodes those fixtures through these types.
+ *
+ * Field names are camelCase on the wire (System.Text.Json camelCase policy on the C# side).
+ * Null fields are omitted on the wire (WhenWritingNull).
+ */
+
+export type MessageKind = "request" | "response" | "event";
+
+export type ErrorCode =
+  | "ProtocolMismatch"
+  | "HandshakeFailed"
+  | "CapabilityNotDeclared"
+  | "CapabilityDenied"
+  | "InvalidPayload"
+  | "MessageTooLarge"
+  | "RouteNotFound"
+  | "RequestTimeout"
+  | "TooManyRequests"
+  | "TransportDisconnected"
+  | "PluginUnavailable"
+  | "InternalError"
+  | "Cancelled"
+  | "RateLimited";
+
+export interface BusError {
+  code: ErrorCode;
+  message: string;
+  retryable: boolean;
+  details?: unknown;
+}
+
+/**
+ * The frozen Phase-1 envelope. All fields except correlationId/timeoutMs/error/payload are
+ * required; the optional ones are omitted on the wire when null.
+ */
+export interface Envelope {
+  version: string; // e.g. "3.0"
+  id: string;
+  correlationId?: string | null;
+  traceId: string;
+  sessionId: string;
+  pluginId: string;
+  entryId: string;
+  endpointId: string;
+  kind: MessageKind;
+  route: string;
+  timeoutMs?: number | null;
+  payload?: unknown;
+  error?: BusError | null;
+}
+
+/** Omit null/undefined-valued keys to match the C# WhenWritingNull behavior. */
+export function canonicalStringify(value: unknown): string {
+  return JSON.stringify(stripNulls(value));
+}
+
+function stripNulls(value: unknown): unknown {
+  if (value === null || value === undefined) return undefined;
+  if (Array.isArray(value)) return value.map(stripNulls);
+  if (typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      const stripped = stripNulls(v);
+      if (stripped !== undefined) out[k] = stripped;
+    }
+    return out;
+  }
+  return value;
+}
+
+/** Parse + re-canonicalize, returning the canonical JSON string (stable key order via JSON.stringify). */
+export function canonicalize(json: string): string {
+  return canonicalStringify(JSON.parse(json));
+}

package/src/router.ts

@@ -0,0 +1,149 @@
+/**
+ * Handler router for the Node SDK v3. Dispatches inbound plugin.call.* requests to registered
+ * handlers, auto-replies to bus.ping, and provides callHost() to invoke host.call.* capabilities
+ * and correlate their responses. Mirrors the C# MessageBus routing rules on the Node side.
+ */
+
+import { randomBytes } from "node:crypto";
+import type { Envelope, BusError } from "./protocol.ts";
+
+type Handler = (payload: unknown) => Promise<unknown> | unknown;
+type Sender = (env: Envelope) => void;
+
+interface PendingHostCall {
+  resolve: (value: unknown) => void;
+  reject: (err: Error) => void;
+  route: string;
+}
+
+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";
+
+  /** Injected transport send fn; tests can override `router.send` directly. */
+  send: Sender;
+
+  constructor(deps: { send: Sender }) {
+    this.send = deps.send;
+  }
+
+  /** Sets the bound identity stamped on outbound messages (after handshake). */
+  setIdentity(ids: { pluginId: string; entryId: string; sessionId: string; endpointId: string }): void {
+    this.pluginId = ids.pluginId;
+    this.entryId = ids.entryId;
+    this.sessionId = ids.sessionId;
+    this.endpointId = ids.endpointId;
+  }
+
+  handle(route: string, handler: Handler): void {
+    this.handlers.set(route, handler);
+  }
+
+  /** Dispatches an inbound request/response. Returns once handled. */
+  async dispatch(env: Envelope): Promise<void> {
+    if (env.kind === "response") {
+      this.handleHostResponse(env);
+      return;
+    }
+    if (env.kind !== "request") return;
+
+    // bus.ping is always auto-replied; it does not occupy a handler slot.
+    if (env.route === "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`));
+      return;
+    }
+
+    try {
+      const result = await 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));
+    }
+  }
+
+  /** Calls a host.call.* capability and resolves with the response payload. */
+  callHost(route: string, payload: unknown, timeoutMs = 30000): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+      const id = randomBytesHex();
+      const req: Envelope = {
+        version: "3.0",
+        id,
+        traceId: id,
+        sessionId: this.sessionId,
+        pluginId: this.pluginId,
+        entryId: this.entryId,
+        endpointId: this.endpointId,
+        kind: "request",
+        route,
+        timeoutMs,
+        payload,
+      };
+      const pending: PendingHostCall = { resolve, reject, route };
+      this.pendingHostCalls.set(id, pending);
+      const timer = setTimeout(() => {
+        if (this.pendingHostCalls.has(id)) {
+          this.pendingHostCalls.delete(id);
+          reject(new Error(`host call ${route} timed out after ${timeoutMs}ms`));
+        }
+      }, timeoutMs);
+      // Clear the timer when settled.
+      const origResolve = pending.resolve;
+      const origReject = pending.reject;
+      pending.resolve = (v) => { clearTimeout(timer); origResolve(v); };
+      pending.reject = (e) => { clearTimeout(timer); origReject(e); };
+      this.send(req);
+    });
+  }
+
+  private handleHostResponse(env: Envelope): void {
+    if (!env.correlationId) return;
+    const pending = this.pendingHostCalls.get(env.correlationId);
+    if (!pending) return;
+    this.pendingHostCalls.delete(env.correlationId);
+    if (env.error) {
+      pending.reject(new Error(`${env.error.code}: ${env.error.message}`));
+    } else {
+      pending.resolve(env.payload);
+    }
+  }
+
+  private responseFor(req: Envelope, payload: unknown): Envelope {
+    return {
+      version: "3.0",
+      id: randomBytesHex(),
+      correlationId: req.id,
+      traceId: req.traceId,
+      sessionId: req.sessionId,
+      pluginId: req.pluginId,
+      entryId: req.entryId,
+      endpointId: this.endpointId,
+      kind: "response",
+      route: req.route,
+      payload,
+    };
+  }
+
+  private errorResponseFor(req: Envelope, code: string, message: string): Envelope {
+    return {
+      ...this.responseFor(req, null),
+      payload: undefined,
+      error: { code, message, retryable: false } as BusError,
+    };
+  }
+}
+
+function randomBytesHex(): string {
+  // 16 random bytes -> 32 hex chars, matching the C# GuidIdGenerator format.
+  return randomBytes(16).toString("hex");
+}

package/src/server.ts

@@ -0,0 +1,156 @@
+/**
+ * v3 server-side tool SDK: a fluent `createTool()` API that mirrors the v2 @qping/plugin-common/server
+ * surface (initialize/search/action/handle/publish/hostCall/start) but runs over the v3 named-pipe
+ * message bus via bootstrap.ts. This lets existing plugin backends switch to v3 transport by
+ * changing only the import — no handler-logic rewrite.
+ *
+ * Legacy method names map to v3 routes:
+ *   initialize -> plugin.call.initialize
+ *   search     -> plugin.call.search
+ *   invokeAction -> plugin.call.invokeAction
+ *   detailEvent  -> plugin.call.detailEvent
+ *   detailCall   -> plugin.call.detailCall (+ named handlers via plugin.call.<action>)
+ *   publish    -> plugin.event.<subjectId>
+ *   hostCall   -> host.call.<method>
+ */
+
+import { runPlugin, type PluginRuntime } from "./bootstrap.ts";
+
+type NodeToolContext = {
+  action: string;
+  itemId: string;
+  query: string;
+  locale: string;
+  fallbackLocale: string;
+};
+
+type NodeToolHostHandler = (params: any) => unknown | Promise<unknown>;
+type NodeToolHandler = (payload: any, context: NodeToolContext) => unknown | Promise<unknown>;
+
+export class NodeTool {
+  #handlers = new Map<string, NodeToolHandler>();
+  #searchHandler: NodeToolHostHandler | null = null;
+  #actionHandler: NodeToolHostHandler | null = null;
+  #initializeHandler: NodeToolHostHandler | null = null;
+  #runtime: PluginRuntime | null = null;
+
+  initialize(handler: NodeToolHostHandler): this {
+    this.#initializeHandler = handler;
+    return this;
+  }
+
+  search(handler: NodeToolHostHandler): this {
+    this.#searchHandler = handler;
+    return this;
+  }
+
+  action(handler: NodeToolHostHandler): this {
+    this.#actionHandler = handler;
+    return this;
+  }
+
+  handle(action: string, handler: NodeToolHandler): this {
+    if (!action || typeof action !== "string") {
+      throw new Error("tool.handle requires an action name.");
+    }
+    if (typeof handler !== "function") {
+      throw new Error("tool.handle requires a handler.");
+    }
+    this.#handlers.set(action, handler);
+    return this;
+  }
+
+  /** Publishes a plugin.event.<subjectId> event to all webviews in the session. */
+  publish(subjectId: string, payload: unknown = {}): void {
+    if (!this.#runtime) throw new Error("tool not started");
+    // Strip the legacy prefix to form a clean route; the host EventReceived surfaces the route.
+    const route = subjectId.startsWith("plugin.event.") ? subjectId : `plugin.event.${subjectId}`;
+    this.#runtime.transport.send({
+      version: "3.0",
+      id: crypto.randomUUID().replace(/-/g, "").slice(0, 32),
+      traceId: crypto.randomUUID().replace(/-/g, "").slice(0, 32),
+      sessionId: "",
+      pluginId: "",
+      entryId: "",
+      endpointId: "node-main",
+      kind: "event",
+      route,
+      payload,
+    });
+  }
+
+  /** Calls a host.call.<method> capability and awaits the response. */
+  hostCall(method: string, params: Record<string, unknown> = {}): Promise<unknown> {
+    if (!this.#runtime) return Promise.reject(new Error("tool not started"));
+    return this.#runtime.router.callHost(`host.call.${method}`, params);
+  }
+
+  /** Connects to the host pipe and begins dispatching. Must be called last. */
+  async start(): Promise<void> {
+    const routes = this.buildRoutes();
+    this.#runtime = await runPlugin(routes);
+  }
+
+  /**
+   * Builds the v3 route map from the fluent registrations. Exposed for unit testing the mapping
+   * without connecting a pipe.
+   */
+  buildRoutes(): Record<string, (payload: any) => unknown | Promise<unknown>> {
+    const routes: Record<string, (payload: any) => unknown | Promise<unknown>> = {};
+
+    if (this.#initializeHandler) {
+      routes["plugin.call.initialize"] = (p) => this.#initializeHandler!(p);
+    }
+    if (this.#searchHandler) {
+      routes["plugin.call.search"] = (p) => this.#searchHandler!(p);
+    }
+    if (this.#actionHandler) {
+      routes["plugin.call.invokeAction"] = (p) => {
+        return this.#actionHandler!({ ...p, itemId: p.itemId, query: p.query });
+      };
+    }
+    // Legacy detail calls: plugin.call.detailCall carries an `action` field selecting the handler.
+    routes["plugin.call.detailCall"] = async (p) => {
+      const action = p?.action ?? "";
+      const handler = this.#handlers.get(action);
+      if (!handler) {
+        throw new Error(`no handler registered for action '${action}'`);
+      }
+      const ctx = extractContext(p);
+      const result = await handler(p?.payload ?? {}, ctx);
+      return { result: result ?? {} };
+    };
+    routes["plugin.call.detailEvent"] = async (p) => {
+      return { state: p?.payload ?? {} };
+    };
+    for (const [action, handler] of this.#handlers) {
+      const route = `plugin.call.${action}`;
+      if (!routes[route]) {
+        routes[route] = async (p) => {
+          const ctx = extractContext(p);
+          return handler(p, ctx);
+        };
+      }
+    }
+    return routes;
+  }
+
+  async stop(): Promise<void> {
+    if (this.#runtime) await this.#runtime.close();
+  }
+}
+
+function extractContext(p: any): NodeToolContext {
+  return {
+    action: p?.action ?? "",
+    itemId: p?.itemId ?? "",
+    query: p?.query ?? "",
+    locale: p?.locale ?? "en-US",
+    fallbackLocale: p?.fallbackLocale ?? "en-US",
+  };
+}
+
+/** Creates a v3 NodeTool. Drop-in replacement for @qping/plugin-common/server's createTool(). */
+export function createTool(): NodeTool {
+  return new NodeTool();
+}

package/src/transport.ts

@@ -0,0 +1,98 @@
+/**
+ * Node-side named-pipe transport for the v3 message bus. Connects to the host's pipe server
+ * (created by NamedPipeTransport on the C# side), runs an incremental FrameDecoder read loop,
+ * and sends length-prefixed frames. Mirrors MyTools.Host.Transports.NamedPipeTransport.
+ */
+
+import { connect as netConnect, type Socket } from "node:net";
+import { encodeFrameString } from "./framing.ts";
+import { canonicalStringify, type Envelope } from "./protocol.ts";
+
+type MessageHandler = (env: Envelope) => void;
+type DisconnectHandler = () => void;
+
+export class NodeTransport {
+  private socket: Socket | null = null;
+  private messageHandlers = new Set<MessageHandler>();
+  private disconnectHandlers = new Set<DisconnectHandler>();
+  private closed = false;
+
+  onMessage(handler: MessageHandler): void {
+    this.messageHandlers.add(handler);
+  }
+
+  onDisconnect(handler: DisconnectHandler): void {
+    this.disconnectHandlers.add(handler);
+  }
+
+  get isConnected(): boolean {
+    return this.socket !== null && !this.closed;
+  }
+
+  /** Connects to a Windows named pipe (\\.\pipe\<name>). */
+  async connect(pipePath: string): Promise<void> {
+    this.socket = (netConnect as any)(pipePath) as Socket;
+
+    await new Promise<void>((resolve, reject) => {
+      this.socket!.once("connect", () => resolve());
+      this.socket!.once("error", (err: Error) => reject(err));
+    });
+
+    // Single-writer ordering is guaranteed by the socket itself; a dedicated read loop decodes
+    // frames incrementally and dispatches each complete envelope.
+    const { FrameDecoder } = await import("./framing.ts");
+    const decoder = new FrameDecoder();
+
+    this.socket.on("data", (chunk: Buffer) => {
+      let result = decoder.feed(chunk);
+      if (result.isFatal) {
+        this.handleDisconnect();
+        return;
+      }
+      while (result.hasFrame) {
+        try {
+          const env = JSON.parse(result.payload.toString("utf8")) as Envelope;
+          for (const h of this.messageHandlers) h(env);
+        } catch {
+          // Illegal JSON closes the connection per design.
+          this.handleDisconnect();
+          return;
+        }
+        result = decoder.feed(Buffer.alloc(0));
+        if (result.isFatal) {
+          this.handleDisconnect();
+          return;
+        }
+      }
+    });
+
+    this.socket.on("close", () => this.handleDisconnect());
+    this.socket.on("error", () => this.handleDisconnect());
+  }
+
+  /** Serializes an envelope to a length-prefixed frame and writes it. */
+  send(env: Envelope): void {
+    if (!this.socket || this.closed) {
+      throw new Error("transport is not connected");
+    }
+    this.socket.write(encodeFrameString(canonicalStringify(env)));
+  }
+
+  async close(): Promise<void> {
+    this.closed = true;
+    if (this.socket) {
+      this.socket.end();
+      await new Promise<void>((resolve) => {
+        if (this.socket!.destroyed) return resolve();
+        this.socket!.once("close", () => resolve());
+      });
+      this.socket = null;
+    }
+  }
+
+  private handleDisconnect(): void {
+    if (this.closed) return;
+    this.closed = true;
+    for (const h of this.disconnectHandlers) h();
+  }
+}