@zhin.js/adapter-sandbox 5.0.5 → 5.0.6

package/pages/sandbox.tsx

@@ -0,0 +1,95 @@
+import { definePage } from '@zhin.js/console-contract';
+import { useEffect, useRef, useState, type FormEvent } from 'react';
+
+export const meta = definePage({
+  title: 'Sandbox',
+  icon: 'Box',
+  order: 10,
+});
+
+/**
+ * Convention page (ADR 0046). Plugin Runtime Host also serves a vanilla WS shell
+ * for this localName so local smoke does not depend on a CDN React graph.
+ */
+export default function SandboxPage() {
+  const [connected, setConnected] = useState(false);
+  const [input, setInput] = useState('');
+  const [lines, setLines] = useState<readonly { readonly kind: 'in' | 'out'; readonly text: string }[]>([]);
+  const wsRef = useRef<WebSocket | null>(null);
+
+  useEffect(() => {
+    const url = new URL('/sandbox', window.location.href);
+    url.protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+    const ws = new WebSocket(url);
+    wsRef.current = ws;
+    ws.addEventListener('open', () => setConnected(true));
+    ws.addEventListener('close', () => setConnected(false));
+    ws.addEventListener('message', (event) => {
+      let text = String(event.data);
+      try {
+        const data = JSON.parse(text) as {
+          content?: Array<{ data?: { text?: string } }> | string;
+        };
+        text = Array.isArray(data.content)
+          ? data.content.map((segment) => segment?.data?.text ?? '').filter(Boolean).join('\n')
+          : typeof data.content === 'string'
+            ? data.content
+            : text;
+      } catch {
+        /* keep raw */
+      }
+      setLines((previous) => [...previous, { kind: 'in', text }]);
+    });
+    return () => {
+      ws.close();
+      wsRef.current = null;
+    };
+  }, []);
+
+  const onSubmit = (event: FormEvent) => {
+    event.preventDefault();
+    const text = input.trim();
+    const ws = wsRef.current;
+    if (!text || !ws || ws.readyState !== WebSocket.OPEN) return;
+    ws.send(JSON.stringify({ text, timestamp: Date.now() }));
+    setLines((previous) => [...previous, { kind: 'out', text }]);
+    setInput('');
+  };
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', height: 'calc(100vh - 3rem)', maxWidth: 720, margin: '0 auto' }}>
+      <p style={{ padding: '0.75rem 1rem', margin: 0, color: '#71717a' }}>
+        {connected ? 'WebSocket /sandbox connected' : 'connecting…'}
+      </p>
+      <div style={{ flex: 1, overflow: 'auto', padding: '1rem', display: 'flex', flexDirection: 'column', gap: 8 }}>
+        {lines.map((line, index) => (
+          <div
+            key={`${line.kind}-${index}-${line.text.slice(0, 12)}`}
+            style={{
+              alignSelf: line.kind === 'out' ? 'flex-end' : 'flex-start',
+              background: line.kind === 'out' ? '#ccfbf1' : '#fff',
+              border: '1px solid #e4e4e7',
+              borderRadius: 10,
+              padding: '0.6rem 0.8rem',
+              maxWidth: '85%',
+              whiteSpace: 'pre-wrap',
+            }}
+          >
+            {line.text}
+          </div>
+        ))}
+      </div>
+      <form onSubmit={onSubmit} style={{ display: 'flex', gap: 8, padding: 12, borderTop: '1px solid #e4e4e7' }}>
+        <input
+          value={input}
+          onChange={(event) => setInput(event.target.value)}
+          placeholder="发送到 /sandbox …"
+          style={{ flex: 1, padding: '0.55rem 0.75rem', borderRadius: 8, border: '1px solid #d4d4d8' }}
+        />
+        <button type="submit" style={{ padding: '0.55rem 0.9rem', border: 0, borderRadius: 8, background: '#0f766e', color: '#fff' }}>
+          发送
+        </button>
+      </form>
+    </div>
+  );
+}

package/plugin.ts

@@ -0,0 +1,8 @@
+import { definePlugin } from '@zhin.js/plugin-runtime';
+
+export default definePlugin({
+  name: 'sandbox',
+  metadata: {
+    displayName: 'Sandbox Adapter',
+  },
+});

package/schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "endpoints": {
+      "type": "array",
+      "default": [],
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "context": { "type": "string" },
+          "name": { "type": "string" },
+          "owner": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/src/endpoint.ts

@@ -0,0 +1,188 @@
+/**
+ * SandboxWsEndpoint — WebSocket lifecycle and MessageGateway bridge for /sandbox.
+ */
+import { randomUUID } from 'node:crypto';
+import type { EndpointInstance } from '@zhin.js/adapter';
+import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { HttpHost, WsConnection } from '@zhin.js/host-http';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import {
+  bindSandboxWsSocket,
+  formatSandboxOutbound,
+  parseSandboxWsPayload,
+  whenWsOpen,
+  type ResolvedSandboxBot,
+  type SandboxWsSocket,
+} from './protocol.js';
+
+const logger = getLogger('sandbox');
+
+interface SandboxConnection {
+  readonly target: string;
+  readonly owner: string;
+  readonly socket: SandboxWsSocket;
+  readonly release: () => void;
+  /** true = 占位连接（尚无真实 WS 客户端），send 命中时按 miss 处理。 */
+  readonly placeholder?: boolean;
+}
+
+export interface SandboxEndpointOptions {
+  readonly id: CapabilityId;
+  readonly gateway: MessageGateway;
+  readonly http: HttpHost;
+  readonly defaults: ResolvedSandboxBot;
+}
+
+export class SandboxWsEndpoint implements EndpointInstance {
+  readonly #options: SandboxEndpointOptions;
+  readonly #connections = new Map<string, SandboxConnection>();
+  #wsHandleRelease?: () => void;
+  #open = false;
+  #started = false;
+
+  constructor(options: SandboxEndpointOptions) {
+    this.#options = options;
+  }
+
+  /** Live endpoint name (config `name`) — Console endpoint.list/resolve uses it. */
+  get name(): string {
+    return this.#options.defaults.name;
+  }
+
+  start(): void {
+    if (this.#started) return;
+    this.#started = true;
+    const handle = this.#options.http.ws('/sandbox');
+    this.#wsHandleRelease = handle.onConnection((connection) => {
+      this.#acceptConnection(connection);
+    });
+    if (!this.#options.defaults.randomNamePerConnection) {
+      this.#ensurePlaceholder(this.#options.defaults.name, this.#options.defaults.owner);
+    }
+    logger.info(formatCompact({
+      op: 'sandbox_ws_mounted',
+      path: '/sandbox',
+      endpoint: this.#options.defaults.name,
+    }));
+  }
+
+  open(): void {
+    this.#open = true;
+  }
+
+  close(): void {
+    this.#open = false;
+  }
+
+  stop(): void {
+    this.#open = false;
+    this.#wsHandleRelease?.();
+    this.#wsHandleRelease = undefined;
+    for (const connection of this.#connections.values()) connection.release();
+    this.#connections.clear();
+    this.#started = false;
+    logger.debug(formatCompact({ op: 'sandbox_stopped' }));
+  }
+
+  send({ target, payload }: { readonly target: string; readonly payload: unknown }): unknown {
+    if (!this.#open) return undefined;
+    const connection = this.#connections.get(target);
+    if (!connection) {
+      logger.debug(formatCompact({ op: 'sandbox_send_miss', target }));
+      return undefined;
+    }
+    if (connection.placeholder) {
+      logger.debug(formatCompact({ op: 'sandbox_send_placeholder', target }));
+      return undefined;
+    }
+    connection.socket.send(formatSandboxOutbound(payload));
+    logger.debug(formatCompact({ op: 'sandbox_send', target }));
+    return payload;
+  }
+
+  #acceptConnection(connection: WsConnection): void {
+    const target = this.#options.defaults.randomNamePerConnection
+      ? `sandbox-${randomUUID().slice(0, 8)}`
+      : this.#options.defaults.name;
+    const owner = this.#options.defaults.owner;
+    const socket = connection.socket as SandboxWsSocket;
+    if (this.#connections.has(target)) {
+      this.#connections.get(target)?.release();
+      this.#connections.delete(target);
+    }
+    const release = bindSandboxWsSocket(socket, {
+      onMessage: (raw) => {
+        if (!this.#open) return;
+        const parsed = parseSandboxWsPayload(raw);
+        logger.debug(formatCompact({
+          op: 'sandbox_recv',
+          target,
+          sender: parsed.id || owner,
+          text: parsed.text.slice(0, 80),
+        }));
+        void this.#options.gateway.receive({
+          adapter: this.#options.id,
+          target,
+          content: parsed.text,
+          sender: parsed.id || owner,
+          metadata: Object.freeze({
+            type: parsed.type,
+            elements: parsed.content,
+            timestamp: parsed.timestamp,
+            ...(parsed.action ? { action: parsed.action } : {}),
+          }),
+        }).catch((err) => {
+          logger.warn(formatCompact({
+            op: 'sandbox_gateway_receive_failed',
+            target,
+            error: err instanceof Error ? err.message : String(err),
+          }));
+        });
+      },
+      onClose: () => {
+        this.#connections.delete(target);
+        logger.debug(formatCompact({ op: 'sandbox_ws_closed', target }));
+      },
+      onError: (err) => {
+        logger.warn(formatCompact({
+          op: 'sandbox_ws_error',
+          target,
+          error: err instanceof Error ? err.message : String(err),
+        }));
+      },
+    });
+    this.#connections.set(target, Object.freeze({ target, owner, socket, release }));
+    logger.debug(formatCompact({ op: 'sandbox_ws_connected', target, owner }));
+    if (!this.#options.defaults.randomNamePerConnection) {
+      const readyPayload = JSON.stringify({
+        type: 'ready',
+        id: owner,
+        endpoint: target,
+        content: [{
+          type: 'text',
+          data: {
+            text: [
+              `已连接 Sandbox「${target}」`,
+              '与 Node Host 控制台沙盒协议一致（/sandbox）',
+              '命令: help · ping · zt · status',
+            ].join('\n'),
+          },
+        }],
+        timestamp: Date.now(),
+      });
+      whenWsOpen(socket, () => socket.send(readyPayload));
+    }
+  }
+
+  #ensurePlaceholder(name: string, owner: string): void {
+    if (this.#connections.has(name)) return;
+    this.#connections.set(name, Object.freeze({
+      target: name,
+      owner,
+      socket: { send: () => undefined, close: () => undefined },
+      release: () => undefined,
+      placeholder: true,
+    }));
+  }
+}

package/src/index.ts

@@ -1,106 +1,17 @@
-import path from "node:path";
-import { usePlugin, type Plugin } from "zhin.js";
-import type { WebSocket } from "ws";
-import {
-  SandboxWsHostAdapter,
-  resolveSandboxEndpoint,
-  type SandboxWsSocket,
-} from "./sandbox-ws.js";
-import { PageManager } from "@zhin.js/host-api";
-
-type SandboxRouter = {
-  ws: (path: string) => NonNullable<SandboxAdapter["wss"]>;
-};
-
-declare module "zhin.js" {
-  interface Adapters {
-    sandbox: SandboxAdapter;
-  }
-}
-
-const plugin = usePlugin();
-const logger = plugin.logger;
-
-/** Node：`Router.ws` */
-export class SandboxAdapter extends SandboxWsHostAdapter {
-  wss?: { on: (ev: string, fn: (...args: unknown[]) => void) => void; close: () => void };
-
-  constructor(plugin: ReturnType<typeof usePlugin>) {
-    const appConfig = (plugin.inject("config")?.getPrimary() ?? {}) as Record<string, unknown>;
-    super(plugin, resolveSandboxEndpoint(appConfig));
-  }
-
-  override async start(): Promise<void> {
-    await super.start();
-    this.registerConfiguredPlaceholder();
-    logger.debug(
-      `Sandbox placeholder: ${this.defaults.name} (offline until /sandbox WS)`,
-    );
-  }
-
-  async setupWebSocket(router: SandboxRouter): Promise<void> {
-    if (this.wss) return;
-    this.wss = router.ws("/sandbox");
-
-    this.wss.on("connection", (...args: unknown[]) => {
-      const ws = args[0] as WebSocket;
-      const req = args[1] as { socket?: { remoteAddress?: string } };
-      logger.debug(
-        `New sandbox connection from ${req.socket?.remoteAddress ?? "unknown"}`,
-      );
-      const endpoint = this.acceptWebSocket(ws as SandboxWsSocket);
-      ws.on("close", () => {
-        logger.debug(`Sandbox connection closed: ${endpoint.$config.name}`);
-        this.endpoints.delete(endpoint.$id);
-      });
-      ws.on("error", (error) => {
-        logger.error(`Sandbox WebSocket error for ${endpoint.$config.name}:`, error);
-      });
-    });
-
-    logger.debug("Sandbox WebSocket server started at /sandbox (Node Router.ws)");
-  }
-}
-
-const { provide } = usePlugin();
-
-provide({
-  name: "sandbox",
-  description: "Sandbox Adapter — Node Router.ws",
-  mounted: async (p: Plugin) => {
-    const adapter = new SandboxAdapter(p);
-    await adapter.start();
-    return adapter;
-  },
-  dispose: async (adapter: SandboxAdapter) => {
-    for (const endpoint of adapter.endpoints.values()) {
-      await endpoint.$disconnect();
-    }
-    adapter.wss?.close();
-    await adapter.stop();
-  },
-} as never);
-
-plugin.useContext("router",'sandbox', async (router: SandboxRouter,adapter: SandboxAdapter) => {
-  await adapter.setupWebSocket(router);
-});
-
-plugin.useContext("web", (pageManager) => {
-  pageManager.addEntry({
-    id: "sandbox",
-    development: path.resolve(import.meta.dirname, "../client/index.tsx"),
-    production: path.resolve(import.meta.dirname, "../dist/index.js"),
-    meta: { name: "Sandbox" },
-  });
-});
-
 export {
-  SandboxWsEndpoint,
-  SandboxWsHostAdapter,
-  resolveSandboxEndpoint,
   bindSandboxWsSocket,
+  formatSandboxOutbound,
   parseSandboxWsPayload,
+  resolveSandboxEndpoint,
+  whenWsOpen,
+  type MessageElement,
+  type MessageType,
   type ResolvedSandboxBot,
-  type SandboxWsConfig,
+  type SandboxAdapterConfig,
   type SandboxWsSocket,
-} from "./sandbox-ws.js";
+} from './protocol.js';
+
+export {
+  SandboxWsEndpoint,
+  type SandboxEndpointOptions,
+} from './endpoint.js';

package/src/protocol.ts

@@ -0,0 +1,200 @@
+/** Sandbox WebSocket wire protocol helpers (no legacy Adapter/Endpoint). */
+
+export type MessageType = 'private' | 'group' | 'guild' | 'direct' | 'channel';
+
+export interface MessageElement {
+  readonly type: string;
+  readonly data?: Record<string, unknown>;
+}
+
+export interface SandboxWsSocket {
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+  on?(event: 'message' | 'close' | 'error', listener: (...args: unknown[]) => void): void;
+  off?(
+    event: 'message' | 'close' | 'error',
+    listener: (...args: unknown[]) => void,
+  ): void;
+  addEventListener?(
+    type: 'message' | 'close' | 'error',
+    listener: (ev: Event | MessageEvent | CloseEvent) => void,
+  ): void;
+  removeEventListener?(
+    type: 'message' | 'close' | 'error',
+    listener: (ev: Event | MessageEvent | CloseEvent) => void,
+  ): void;
+}
+
+export type ResolvedSandboxBot = {
+  readonly context: 'sandbox';
+  readonly name: string;
+  readonly owner: string;
+  readonly randomNamePerConnection: boolean;
+};
+
+export interface SandboxAdapterConfig {
+  readonly endpoints?: ReadonlyArray<{
+    readonly context?: string;
+    readonly name?: string;
+    readonly owner?: string;
+  }>;
+}
+
+export function resolveSandboxEndpoint(
+  appConfig: SandboxAdapterConfig,
+): ResolvedSandboxBot {
+  const entry = appConfig.endpoints?.find((item) => item.context === 'sandbox');
+  const fixedName = typeof entry?.name === 'string' ? entry.name : undefined;
+  const name = fixedName || process.env.SANDBOX_BOT_NAME || 'sandbox-bot';
+  const owner = (typeof entry?.owner === 'string' && entry.owner)
+    || process.env.SANDBOX_BOT_OWNER
+    || 'sandbox-user';
+  return {
+    context: 'sandbox',
+    name,
+    owner,
+    randomNamePerConnection: !fixedName,
+  };
+}
+
+export function bindSandboxWsSocket(
+  ws: SandboxWsSocket,
+  handlers: {
+    onMessage: (raw: string) => void;
+    onClose: () => void;
+    onError?: (err: unknown) => void;
+  },
+): () => void {
+  if (typeof ws.on === 'function') {
+    const onMessage = (...args: unknown[]) => {
+      const data = args[0];
+      const raw = typeof data === 'string'
+        ? data
+        : data instanceof ArrayBuffer
+          ? new TextDecoder().decode(data)
+          : Buffer.isBuffer(data)
+            ? data.toString()
+            : String(data ?? '');
+      handlers.onMessage(raw);
+    };
+    ws.on('message', onMessage);
+    ws.on('close', handlers.onClose);
+    if (handlers.onError) ws.on('error', handlers.onError);
+    return () => {
+      ws.off?.('message', onMessage);
+      ws.off?.('close', handlers.onClose);
+      if (handlers.onError) ws.off?.('error', handlers.onError);
+    };
+  }
+  const onMessage = (ev: Event) => {
+    const data = (ev as MessageEvent).data;
+    handlers.onMessage(typeof data === 'string' ? data : '');
+  };
+  const onClose = () => handlers.onClose();
+  const onError = handlers.onError
+    ? () => handlers.onError?.(new Error('WebSocket error'))
+    : undefined;
+  ws.addEventListener!('message', onMessage);
+  ws.addEventListener!('close', onClose);
+  if (onError) ws.addEventListener!('error', onError);
+  return () => {
+    ws.removeEventListener!('message', onMessage);
+    ws.removeEventListener!('close', onClose);
+    if (onError) ws.removeEventListener!('error', onError);
+  };
+}
+
+export function parseSandboxWsPayload(raw: string): {
+  type: MessageType;
+  id: string;
+  content: MessageElement[];
+  timestamp: number;
+  text: string;
+  action?: { id: string; payload: string };
+} {
+  let payload: {
+    type?: MessageType;
+    id?: string;
+    content?: MessageElement[] | string;
+    text?: string;
+    timestamp?: number;
+  };
+  try {
+    payload = JSON.parse(raw) as typeof payload;
+  } catch {
+    payload = { text: raw };
+  }
+  const type = payload.type ?? 'private';
+  const id = payload.id ?? 'sandbox-user';
+  const content: MessageElement[] = typeof payload.content === 'string'
+    ? [{ type: 'text', data: { text: payload.content } }]
+    : Array.isArray(payload.content)
+      ? payload.content
+      : [{ type: 'text', data: { text: payload.text ?? raw } }];
+
+  const actionSegment = content.find((segment) => segment.type === 'action');
+  let action: { id: string; payload: string } | undefined;
+  if (actionSegment?.data) {
+    const actionPayload = typeof actionSegment.data.payload === 'string'
+      ? actionSegment.data.payload
+      : typeof actionSegment.data.id === 'string'
+        ? actionSegment.data.id
+        : '';
+    const actionId = typeof actionSegment.data.id === 'string'
+      ? actionSegment.data.id
+      : actionPayload;
+    if (actionId || actionPayload) {
+      action = { id: actionId || actionPayload, payload: actionPayload || actionId };
+    }
+  }
+
+  let text = content
+    .flatMap((segment) => (segment.type === 'text' && typeof segment.data?.text === 'string'
+      ? [segment.data.text]
+      : []))
+    .join('\n');
+  if (!text.trim()) {
+    text = (typeof payload.text === 'string' && payload.text.trim())
+      ? payload.text
+      : action?.payload ?? raw;
+  }
+  return { type, id, content, timestamp: payload.timestamp ?? Date.now(), text, action };
+}
+
+/**
+ * Wire-encode an already-rendered outbound payload.
+ * Canonical segment mapping (old `segment-mapper` re-export of `to/fromCanonicalSegments`
+ * from legacy `zhin.js`) is intentionally not done here — the gateway/core render path
+ * owns that before `endpoint.send`.
+ */
+export function formatSandboxOutbound(payload: unknown): string {
+  if (typeof payload === 'string') {
+    return JSON.stringify({
+      content: [{ type: 'text', data: { text: payload } }],
+      timestamp: Date.now(),
+    });
+  }
+  if (Array.isArray(payload)) {
+    return JSON.stringify({
+      content: payload,
+      timestamp: Date.now(),
+    });
+  }
+  return JSON.stringify({ content: payload, timestamp: Date.now() });
+}
+
+/** WebSocket.OPEN 常量值；Node <22 无全局 WebSocket，不能用 WebSocket.OPEN。 */
+const WS_OPEN = 1;
+
+export function whenWsOpen(ws: SandboxWsSocket, fn: () => void): void {
+  const std = ws as WebSocket;
+  if (typeof std.readyState === 'number') {
+    if (std.readyState === WS_OPEN) {
+      fn();
+      return;
+    }
+    std.addEventListener('open', fn, { once: true });
+    return;
+  }
+  fn();
+}