paseo-plugin-zcode-provider 0.0.0-stage → 0.1.0

package/server/vendor/zcode/packages/rpc/src/channelServer.ts

@@ -0,0 +1,283 @@
+import { VSBuffer } from "./buffer.js";
+import { type IDisposable, CancellationTokenSource, toDisposable } from "./foundation.js";
+import { BufferReader, BufferWriter, deserialize, serialize } from "./serialization.js";
+import type { IMessagePassingProtocol } from "./protocol.js";
+import {
+  type IChannelServer,
+  type IRawResponse,
+  type IServerChannel,
+  RequestType,
+  ResponseType,
+} from "./channels.shared.js";
+
+export class ChannelServer<TContext = string> implements IChannelServer<TContext>, IDisposable {
+  private channels = new Map<string, IServerChannel<TContext>>();
+  private activeRequests = new Map<number, IDisposable>();
+  private pendingRequests = new Map<
+    string,
+    { request: any; timer: ReturnType<typeof setTimeout> }[]
+  >();
+  private protocolListener: IDisposable | null;
+
+  constructor(
+    private protocol: IMessagePassingProtocol,
+    private ctx: TContext,
+    private timeoutDelay = 1000,
+    private deferInit = false,
+  ) {
+    this.protocolListener = this.protocol.onMessage((msg) => this.onRawMessage(msg));
+    if (!this.deferInit) {
+      this.sendResponse({ type: ResponseType.Initialize });
+    }
+  }
+
+  ready(): void {
+    this.sendResponse({ type: ResponseType.Initialize });
+  }
+
+  registerChannel(channelName: string, channel: IServerChannel<TContext>): void {
+    this.channels.set(channelName, channel);
+    setTimeout(() => this.flushPendingRequests(channelName), 0);
+  }
+
+  private sendResponse(response: IRawResponse): void {
+    switch (response.type) {
+      case ResponseType.Initialize:
+        this.send([response.type]);
+        return;
+      case ResponseType.PromiseSuccess:
+      case ResponseType.PromiseError:
+      case ResponseType.EventFire:
+      case ResponseType.PromiseErrorObj:
+        this.send([response.type, response.id], response.data);
+        return;
+    }
+  }
+
+  private send(header: any, body: any = undefined): void {
+    const writer = new BufferWriter();
+    serialize(writer, header);
+    serialize(writer, body);
+    try {
+      this.protocol.send(writer.buffer);
+    } catch {
+      /* noop */
+    }
+  }
+
+  private onRawMessage(message: VSBuffer): void {
+    const reader = new BufferReader(message);
+    const header = deserialize(reader);
+    const body = deserialize(reader);
+    const type = header[0] as RequestType;
+
+    switch (type) {
+      case RequestType.Promise:
+        this.onPromise({
+          type,
+          id: header[1],
+          channelName: header[2],
+          name: header[3],
+          arg: body,
+        });
+        return;
+      case RequestType.EventListen:
+        this.onEventListen({
+          type,
+          id: header[1],
+          channelName: header[2],
+          name: header[3],
+          arg: body,
+        });
+        return;
+      case RequestType.PromiseCancel:
+      case RequestType.EventDispose:
+        this.disposeActiveRequest(header[1]);
+        return;
+    }
+  }
+
+  private onPromise(request: {
+    type: RequestType.Promise;
+    id: number;
+    channelName: string;
+    name: string;
+    arg: any;
+  }): void {
+    const channel = this.channels.get(request.channelName);
+    if (!channel) {
+      this.collectPendingRequest(request);
+      return;
+    }
+
+    const cts = new CancellationTokenSource();
+    let promise: Promise<any>;
+
+    try {
+      promise = channel.call(this.ctx, request.name, request.arg, cts.token);
+    } catch (error) {
+      promise = Promise.reject(error);
+    }
+
+    const disposable = toDisposable(() => cts.cancel());
+    this.activeRequests.set(request.id, disposable);
+
+    promise
+      .then(
+        (data) => {
+          this.sendResponse({
+            id: request.id,
+            data,
+            type: ResponseType.PromiseSuccess,
+          });
+        },
+        (error) => {
+          if (error instanceof Error) {
+            const rpcErrorPayload: {
+              message: string;
+              name: string;
+              stack: string[] | undefined;
+              code?: unknown;
+              kind?: unknown;
+              status?: unknown;
+              retryAfterMs?: unknown;
+              data?: unknown;
+              detail?: unknown;
+              details?: unknown;
+              taskId?: unknown;
+              traceId?: unknown;
+            } = {
+              message: error.message,
+              name: error.name,
+              stack: error.stack ? error.stack.split("\n") : undefined,
+            };
+            const errorRecord = error as Error & Record<string, unknown>;
+            const passthroughKeys = [
+              "code",
+              "kind",
+              "status",
+              "retryAfterMs",
+              "data",
+              "detail",
+              "details",
+              "taskId",
+              "traceId",
+            ] as const;
+            for (const key of passthroughKeys) {
+              const value = errorRecord[key];
+              if (value !== undefined) {
+                rpcErrorPayload[key] = value;
+              }
+            }
+            this.sendResponse({
+              id: request.id,
+              data: rpcErrorPayload,
+              type: ResponseType.PromiseError,
+            });
+            return;
+          }
+
+          this.sendResponse({
+            id: request.id,
+            data: error,
+            type: ResponseType.PromiseErrorObj,
+          });
+        },
+      )
+      .finally(() => {
+        disposable.dispose();
+        this.activeRequests.delete(request.id);
+      });
+  }
+
+  private onEventListen(request: {
+    type: RequestType.EventListen;
+    id: number;
+    channelName: string;
+    name: string;
+    arg: any;
+  }): void {
+    const channel = this.channels.get(request.channelName);
+    if (!channel) {
+      this.collectPendingRequest(request);
+      return;
+    }
+
+    const disposable = channel.listen(
+      this.ctx,
+      request.name,
+      request.arg,
+    )((data) => {
+      this.sendResponse({
+        id: request.id,
+        data,
+        type: ResponseType.EventFire,
+      });
+    });
+    this.activeRequests.set(request.id, disposable);
+  }
+
+  private disposeActiveRequest(id: number): void {
+    const disposable = this.activeRequests.get(id);
+    if (!disposable) {
+      return;
+    }
+    disposable.dispose();
+    this.activeRequests.delete(id);
+  }
+
+  private collectPendingRequest(request: any): void {
+    const pendingRequests = this.pendingRequests.get(request.channelName) ?? [];
+    if (pendingRequests.length === 0) {
+      this.pendingRequests.set(request.channelName, pendingRequests);
+    }
+
+    const timer = setTimeout(() => {
+      console.error(`Unknown channel: ${request.channelName}`);
+      if (request.type !== RequestType.Promise) {
+        return;
+      }
+
+      this.sendResponse({
+        id: request.id,
+        data: {
+          name: "Unknown channel",
+          message: `Channel name '${request.channelName}' timed out after ${this.timeoutDelay}ms`,
+          stack: undefined,
+        },
+        type: ResponseType.PromiseError,
+      });
+    }, this.timeoutDelay);
+
+    pendingRequests.push({ request, timer });
+  }
+
+  private flushPendingRequests(channelName: string): void {
+    const requests = this.pendingRequests.get(channelName);
+    if (!requests) {
+      return;
+    }
+
+    for (const { request, timer } of requests) {
+      clearTimeout(timer);
+      switch (request.type) {
+        case RequestType.Promise:
+          this.onPromise(request);
+          break;
+        case RequestType.EventListen:
+          this.onEventListen(request);
+          break;
+      }
+    }
+    this.pendingRequests.delete(channelName);
+  }
+
+  dispose(): void {
+    this.protocolListener?.dispose();
+    this.protocolListener = null;
+    for (const disposable of this.activeRequests.values()) {
+      disposable.dispose();
+    }
+    this.activeRequests.clear();
+  }
+}

package/server/vendor/zcode/packages/rpc/src/channels.shared.ts

@@ -0,0 +1,66 @@
+import type { CancellationToken, Event } from "./foundation.js";
+
+export interface IChannel {
+  call<T>(command: string, arg?: any, cancellationToken?: CancellationToken): Promise<T>;
+  listen<T>(event: string, arg?: any): Event<T>;
+}
+
+export interface IServerChannel<TContext = string> {
+  call<T>(
+    ctx: TContext,
+    command: string,
+    arg?: any,
+    cancellationToken?: CancellationToken,
+  ): Promise<T>;
+  listen<T>(ctx: TContext, event: string, arg?: any): Event<T>;
+}
+
+export const enum RequestType {
+  Promise = 100,
+  PromiseCancel = 101,
+  EventListen = 102,
+  EventDispose = 103,
+}
+
+export const enum ResponseType {
+  Initialize = 200,
+  PromiseSuccess = 201,
+  PromiseError = 202,
+  PromiseErrorObj = 203,
+  EventFire = 204,
+}
+
+export type IRawResponse =
+  | { type: ResponseType.Initialize }
+  | { type: ResponseType.PromiseSuccess; id: number; data: any }
+  | {
+      type: ResponseType.PromiseError;
+      id: number;
+      data: {
+        message: string;
+        name: string;
+        stack: string[] | undefined;
+        code?: unknown;
+        kind?: unknown;
+        status?: unknown;
+        retryAfterMs?: unknown;
+        data?: unknown;
+        detail?: unknown;
+        details?: unknown;
+        taskId?: unknown;
+        traceId?: unknown;
+      };
+    }
+  | { type: ResponseType.PromiseErrorObj; id: number; data: any }
+  | { type: ResponseType.EventFire; id: number; data: any };
+
+export type IHandler = (response: IRawResponse) => void;
+
+export interface IChannelServer<TContext = string> {
+  registerChannel(channelName: string, channel: IServerChannel<TContext>): void;
+  ready?(): void;
+}
+
+export interface IChannelClient {
+  getChannel<T extends IChannel>(channelName: string): T;
+}

package/server/vendor/zcode/packages/rpc/src/channels.ts

@@ -0,0 +1,4 @@
+export * from "./channels.shared.js";
+export { ChannelServer } from "./channelServer.js";
+export { ChannelClient } from "./channelClient.js";
+export { getDelayedChannel } from "./delayedChannel.js";

package/server/vendor/zcode/packages/rpc/src/delayedChannel.ts

@@ -0,0 +1,17 @@
+import { type CancellationToken, Event, Relay } from "./foundation.js";
+import type { IChannel } from "./channels.shared.js";
+
+export function getDelayedChannel<T extends IChannel>(promise: Promise<T>): T {
+  return {
+    call(command: string, arg?: any, cancellationToken?: CancellationToken): Promise<any> {
+      return promise.then((channel) => channel.call(command, arg, cancellationToken));
+    },
+    listen(event: string, arg?: any): Event<any> {
+      const relay = new Relay<any>();
+      promise.then((channel) => {
+        relay.input = channel.listen(event, arg);
+      });
+      return relay.event;
+    },
+  } as T;
+}

package/server/vendor/zcode/packages/rpc/src/foundation.ts

@@ -0,0 +1,260 @@
+/**
+ * Layer 0: 基础设施
+ * - IDisposable / DisposableStore: 资源生命周期管理
+ * - Event / Emitter: 事件系统
+ * - CancellationToken: 取消令牌
+ *
+ * 这些是整个 IPC 框架的地基，所有上层模块都依赖它们。
+ */
+
+// ============================================================================
+// Disposable - 资源释放模式
+// ============================================================================
+
+export interface IDisposable {
+  dispose(): void;
+}
+
+export function toDisposable(fn: () => void): IDisposable {
+  return { dispose: once(fn) };
+}
+
+function once(fn: () => void): () => void {
+  let called = false;
+  return () => {
+    if (!called) {
+      called = true;
+      fn();
+    }
+  };
+}
+
+/**
+ * DisposableStore 收集多个 IDisposable，统一释放。
+ * VS Code 里几乎每个类都有一个 DisposableStore 来管理子资源。
+ */
+export class DisposableStore implements IDisposable {
+  private items = new Set<IDisposable>();
+  private isDisposed = false;
+
+  add<T extends IDisposable>(item: T): T {
+    if (this.isDisposed) {
+      console.warn("Adding to a disposed DisposableStore");
+      item.dispose();
+      return item;
+    }
+    this.items.add(item);
+    return item;
+  }
+
+  dispose(): void {
+    if (this.isDisposed) {
+      return;
+    }
+    this.isDisposed = true;
+    for (const item of this.items) {
+      item.dispose();
+    }
+    this.items.clear();
+  }
+}
+
+// ============================================================================
+// Event System - 事件系统
+// ============================================================================
+
+/**
+ * Event<T> 就是一个函数签名：传入 listener，返回一个 IDisposable 用于取消订阅。
+ * 这是整个 IPC 框架中事件流转的核心类型。
+ */
+export type Event<T> = (listener: (e: T) => void) => IDisposable;
+
+export namespace Event {
+  /** 永远不触发的事件 */
+  export const None: Event<any> = () => ({ dispose() {} });
+
+  /** 只触发一次就自动取消订阅 */
+  export function once<T>(event: Event<T>): Event<T> {
+    return (listener) => {
+      let fired = false;
+      const disposable = event((e) => {
+        if (!fired) {
+          fired = true;
+          disposable.dispose();
+          listener(e);
+        }
+      });
+      return disposable;
+    };
+  }
+
+  /** 把事件转为 Promise，resolve 后自动取消订阅 */
+  export function toPromise<T>(event: Event<T>): Promise<T> {
+    return new Promise((resolve) => once(event)(resolve));
+  }
+
+  /** 过滤事件 */
+  export function filter<T>(event: Event<T>, fn: (e: T) => boolean): Event<T> {
+    return (listener) =>
+      event((e) => {
+        if (fn(e)) {
+          listener(e);
+        }
+      });
+  }
+
+  /** 映射事件 */
+  export function map<T, R>(event: Event<T>, fn: (e: T) => R): Event<R> {
+    return (listener) => event((e) => listener(fn(e)));
+  }
+}
+
+/**
+ * Emitter<T> 是事件的发射器。
+ *
+ * 关键设计：
+ * - onWillAddFirstListener: 第一个订阅者到来时触发（懒初始化资源）
+ * - onDidRemoveLastListener: 最后一个订阅者离开时触发（释放资源）
+ *
+ * 这个"懒订阅"机制在 IPC 框架中至关重要——
+ * ChannelClient 的 requestEvent 正是利用它来实现
+ * "有人监听才发送 EventListen 请求，无人监听就发 EventDispose"。
+ */
+export class Emitter<T> implements IDisposable {
+  private listeners = new Set<(e: T) => void>();
+  private disposed = false;
+  private options?: EmitterOptions;
+
+  constructor(options?: EmitterOptions) {
+    this.options = options;
+  }
+
+  get event(): Event<T> {
+    return (listener: (e: T) => void) => {
+      if (this.disposed) {
+        return { dispose() {} };
+      }
+
+      const isFirst = this.listeners.size === 0;
+      this.listeners.add(listener);
+
+      if (isFirst) {
+        this.options?.onWillAddFirstListener?.();
+      }
+
+      return toDisposable(() => {
+        this.listeners.delete(listener);
+        if (this.listeners.size === 0) {
+          this.options?.onDidRemoveLastListener?.();
+        }
+      });
+    };
+  }
+
+  fire(event: T): void {
+    if (this.disposed) {
+      return;
+    }
+    for (const listener of [...this.listeners]) {
+      listener(event);
+    }
+  }
+
+  dispose(): void {
+    this.disposed = true;
+    this.listeners.clear();
+  }
+}
+
+interface EmitterOptions {
+  onWillAddFirstListener?: () => void;
+  onDidRemoveLastListener?: () => void;
+}
+
+/**
+ * Relay 是一个"事件中继器"，可以动态切换输入源。
+ * 用于 getDelayedChannel 中：先创建 Relay，等 channel promise resolve 后切换 input。
+ */
+export class Relay<T> implements IDisposable {
+  private emitter = new Emitter<T>();
+  private inputDisposable: IDisposable = { dispose() {} };
+
+  readonly event = this.emitter.event;
+
+  set input(event: Event<T>) {
+    this.inputDisposable.dispose();
+    this.inputDisposable = event((e) => this.emitter.fire(e));
+  }
+
+  dispose(): void {
+    this.inputDisposable.dispose();
+    this.emitter.dispose();
+  }
+}
+
+/**
+ * EventMultiplexer 聚合多个事件源为一个事件。
+ * IPCServer 的 getMulticastEvent 用它来聚合所有客户端的同名事件。
+ */
+export class EventMultiplexer<T> implements IDisposable {
+  private readonly emitter = new Emitter<T>();
+  private readonly disposables: IDisposable[] = [];
+
+  readonly event = this.emitter.event;
+
+  add(event: Event<T>): IDisposable {
+    const d = event((e) => this.emitter.fire(e));
+    this.disposables.push(d);
+    return d;
+  }
+
+  dispose(): void {
+    for (const d of this.disposables) {
+      d.dispose();
+    }
+    this.emitter.dispose();
+  }
+}
+
+// ============================================================================
+// CancellationToken - 取消令牌
+// ============================================================================
+
+export interface CancellationToken {
+  readonly isCancellationRequested: boolean;
+  readonly onCancellationRequested: Event<void>;
+}
+
+export namespace CancellationToken {
+  export const None: CancellationToken = {
+    isCancellationRequested: false,
+    onCancellationRequested: Event.None,
+  };
+}
+
+export class CancellationTokenSource implements IDisposable {
+  private _token?: CancellationToken;
+  private emitter = new Emitter<void>();
+  private _isCancelled = false;
+
+  get token(): CancellationToken {
+    if (!this._token) {
+      this._token = {
+        isCancellationRequested: false,
+        onCancellationRequested: this.emitter.event,
+      };
+    }
+    return this._token;
+  }
+
+  cancel(): void {
+    if (!this._isCancelled) {
+      this._isCancelled = true;
+      this.emitter.fire();
+    }
+  }
+
+  dispose(): void {
+    this.emitter.dispose();
+  }
+}