@yuhere/js-jsonrpc2 0.0.0-stage → 2.1.2

package/webui/src/api/wsTransport.ts

@@ -0,0 +1,305 @@
+import type { RpcResponse } from './types';
+import {
+    RPCError,
+    isStreamResult,
+    type CallResult,
+    type RpcClient,
+} from './rpc';
+
+export interface WsRpcOptions {
+    /** 默认：根据当前页面 URL 推导（http->ws / https->wss，同路径） */
+    endpoint?: string;
+    connectTimeoutMs?: number;
+    callTimeoutMs?: number;
+}
+
+interface Pending {
+    resolve: (v: unknown) => void;
+    reject: (e: unknown) => void;
+    timer: ReturnType<typeof setTimeout>;
+}
+
+interface StreamSub {
+    push: (v: unknown) => void;
+    finish: () => void;
+    fail: (e: unknown) => void;
+}
+
+interface StreamFrame {
+    jsonrpc: '2.0';
+    id: number | string;
+    done: boolean;
+    index?: number;
+    value?: unknown;
+    error?: { code: number; message: string };
+}
+
+/** 首帧等待器：resolve 到原始消息对象，由 call 决定走哪条路。 */
+type FirstWaiter = (msg: RpcResponse | StreamFrame) => void;
+
+let idCounter = 0;
+
+function deriveWsEndpoint(): string {
+    const loc = window.location;
+    const proto = loc.protocol === 'https:' ? 'wss:' : 'ws:';
+    return `${proto}//${loc.host}${loc.pathname}`;
+}
+
+function isStreamFrame(v: unknown): v is StreamFrame {
+    return !!v && typeof v === 'object' && typeof (v as StreamFrame).done === 'boolean';
+}
+
+export function createWsRpc(options: WsRpcOptions = {}): RpcClient {
+    const {
+        endpoint = deriveWsEndpoint(),
+        connectTimeoutMs = 5000,
+        callTimeoutMs = 15000,
+    } = options;
+
+    const pending = new Map<number | string, Pending>();
+    const streams = new Map<number | string, StreamSub>();
+    const firstWaiters = new Map<number | string, FirstWaiter>();
+    let socket: WebSocket | null = null;
+    let openPromise: Promise<void> | null = null;
+    let closedByUser = false;
+
+    function rejectAll(reason: string) {
+        for (const [, p] of pending) {
+            clearTimeout(p.timer);
+            p.reject(new Error(reason));
+        }
+        pending.clear();
+        for (const [, sub] of streams) {
+            sub.fail(new Error(reason));
+        }
+        streams.clear();
+        for (const [, w] of firstWaiters) {
+            // 首帧没等到连接就关了：用一个假的 failure 消息唤醒，让它走普通失败分支
+            w({
+                jsonrpc: '2.0',
+                id: 0,
+                error: { code: -32603, message: reason },
+            } as RpcResponse);
+        }
+        firstWaiters.clear();
+    }
+
+    function attach(ws: WebSocket) {
+        ws.addEventListener('message', (ev) => {
+            let data: RpcResponse | RpcResponse[] | StreamFrame | StreamFrame[] | null = null;
+            try {
+                data = JSON.parse(ev.data as string);
+            } catch {
+                return;
+            }
+            const list = Array.isArray(data) ? data : [data];
+            for (const msg of list) {
+                if (msg.id == null) continue;
+
+                // 1) 首帧等待者
+                const fw = firstWaiters.get(msg.id);
+                if (fw) {
+                    firstWaiters.delete(msg.id);
+                    fw(msg as RpcResponse | StreamFrame);
+                    continue;
+                }
+
+                // 2) 流帧
+                if (isStreamFrame(msg)) {
+                    const sub = streams.get(msg.id);
+                    if (!sub) continue;
+                    if (msg.error) {
+                        streams.delete(msg.id);
+                        sub.fail(new RPCError(msg.error));
+                        continue;
+                    }
+                    if (msg.done) {
+                        streams.delete(msg.id);
+                        sub.finish();
+                        continue;
+                    }
+                    if (msg.value !== undefined) sub.push(msg.value);
+                    continue;
+                }
+
+                // 3) 普通响应
+                const p = pending.get(msg.id);
+                if (!p) continue;
+                pending.delete(msg.id);
+                clearTimeout(p.timer);
+                const plain = msg as RpcResponse;
+                if (plain.error) p.reject(new RPCError(plain.error));
+                else p.resolve(plain.result);
+            }
+        });
+
+        ws.addEventListener('close', () => {
+            if (!closedByUser) rejectAll('WebSocket 已关闭');
+            socket = null;
+            openPromise = null;
+        });
+    }
+
+    function ensureOpen(): Promise<void> {
+        if (socket && socket.readyState === WebSocket.OPEN) return Promise.resolve();
+        if (openPromise) return openPromise;
+
+        openPromise = new Promise<void>((resolve, reject) => {
+            let settled = false;
+            const ws = new WebSocket(endpoint);
+            const timer = setTimeout(() => {
+                if (settled) return;
+                settled = true;
+                try { ws.close(); } catch { /* ignore */ }
+                reject(new Error(`WebSocket 连接超时（${connectTimeoutMs}ms）`));
+            }, connectTimeoutMs);
+
+            attach(ws);
+
+            ws.addEventListener('open', () => {
+                if (settled) return;
+                settled = true;
+                clearTimeout(timer);
+                socket = ws;
+                resolve();
+            }, { once: true });
+
+            ws.addEventListener('close', () => {
+                if (settled) return;
+                settled = true;
+                clearTimeout(timer);
+                reject(new Error('WebSocket 连接被拒绝'));
+            }, { once: true });
+
+            ws.addEventListener('error', () => {
+                if (settled) return;
+                settled = true;
+                clearTimeout(timer);
+                reject(new Error('WebSocket 连接失败'));
+            }, { once: true });
+        }).finally(() => {
+            if (!socket) openPromise = null;
+        });
+
+        return openPromise;
+    }
+
+    function call<T = unknown>(method: string, ...params: unknown[]): CallResult<T> {
+        return (async () => {
+            await ensureOpen();
+            const ws = socket;
+            if (!ws || ws.readyState !== WebSocket.OPEN) {
+                throw new Error('WebSocket 未连接');
+            }
+
+            const id = ++idCounter;
+            const payload = { jsonrpc: '2.0', method, params, id };
+
+            // 等第一帧
+            const first = new Promise<RpcResponse | StreamFrame>((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    firstWaiters.delete(id);
+                    reject(new Error(`调用 ${method} 超时（${callTimeoutMs}ms）`));
+                }, callTimeoutMs);
+
+                firstWaiters.set(id, (msg) => {
+                    clearTimeout(timer);
+                    resolve(msg);
+                });
+            });
+
+            try {
+                ws.send(JSON.stringify(payload));
+            } catch (e) {
+                firstWaiters.delete(id);
+                throw e;
+            }
+
+            let firstMsg: RpcResponse | StreamFrame;
+            try {
+                firstMsg = await first;
+            } catch (e) {
+                firstWaiters.delete(id);
+                throw e;
+            }
+
+            // 流式
+            if (isStreamFrame(firstMsg)) {
+                // 桥接到 AsyncGenerator
+                const queue: T[] = [];
+                let finished = false;
+                let failure: unknown = null;
+                let waiter: (() => void) | null = null;
+                const wake = () => {
+                    const w = waiter;
+                    waiter = null;
+                    w?.();
+                };
+
+                // 先处理首帧
+                if (firstMsg.error) {
+                    throw new RPCError(firstMsg.error);
+                }
+                if (firstMsg.done) {
+                    // 空流：直接返回空 generator
+                    return (async function* (): AsyncGenerator<T, void, unknown> {})();
+                }
+                if (firstMsg.value !== undefined) queue.push(firstMsg.value as T);
+
+                const sub: StreamSub = {
+                    push: (v) => {
+                        queue.push(v as T);
+                        wake();
+                    },
+                    finish: () => {
+                        finished = true;
+                        wake();
+                    },
+                    fail: (e) => {
+                        failure = e;
+                        finished = true;
+                        wake();
+                    },
+                };
+                streams.set(id, sub);
+
+                return (async function* (): AsyncGenerator<T, void, unknown> {
+                    try {
+                        while (true) {
+                            if (failure) throw failure;
+                            if (queue.length > 0) {
+                                yield queue.shift() as T;
+                                continue;
+                            }
+                            if (finished) return;
+                            await new Promise<void>((resolve) => {
+                                waiter = resolve;
+                            });
+                        }
+                    } finally {
+                        streams.delete(id);
+                    }
+                })();
+            }
+
+            // 普通
+            if (firstMsg.error) {
+                throw new RPCError(firstMsg.error);
+            }
+            return (firstMsg as RpcResponse).result as T;
+        })();
+    }
+
+    return {
+        call,
+        close() {
+            closedByUser = true;
+            rejectAll('客户端已关闭');
+            if (socket) {
+                try { socket.close(1000, 'client closed'); } catch { /* ignore */ }
+            }
+            socket = null;
+            openPromise = null;
+        },
+    };
+}

package/webui/src/components/MethodDetail.tsx

@@ -0,0 +1,43 @@
+import type { MethodDetail as MethodDetailData } from '../hooks/useMethodDetail';
+import { SchemaView } from './SchemaView';
+
+export function MethodDetail({
+    method,
+    detail,
+}: {
+    method: string;
+    detail: MethodDetailData;
+}) {
+    if (!method) {
+        return (
+            <section className="detail">
+                <p className="hint">← 从左侧选择一个方法查看帮助与签名。</p>
+            </section>
+        );
+    }
+
+    const [returnSchema] = detail.signature;
+
+    return (
+        <section className="detail">
+            <h2>{method}</h2>
+            {detail.loading && <p className="hint">加载中…</p>}
+            {detail.error && <p className="error">加载失败：{detail.error}</p>}
+
+            <h3>Help</h3>
+            <pre className="help">{detail.help || '（无帮助信息）'}</pre>
+
+            <h3>
+                返回类型{' '}
+                <span className="hint">
+                    （服务端不会校验执行结果是否符合此类型，实际返回值可能会有所不同）
+                </span>
+            </h3>
+            {returnSchema ? (
+                <SchemaView schema={returnSchema} depth={0} defaultOpen />
+            ) : (
+                <p className="hint">（暂无）</p>
+            )}
+        </section>
+    );
+}

package/webui/src/components/MethodTree.tsx

@@ -0,0 +1,118 @@
+import { useMemo, useState } from 'react';
+
+interface TreeNode {
+    name: string;
+    fullName: string;
+    children: TreeNode[];
+    isLeaf: boolean;
+}
+
+function buildTree(methods: string[]): TreeNode[] {
+    const root: TreeNode = { name: '', fullName: '', children: [], isLeaf: false };
+    for (const m of methods) {
+        const parts = m.split('.');
+        let cur = root;
+        parts.forEach((part, i) => {
+            const isLeaf = i === parts.length - 1;
+            let child = cur.children.find((c) => c.name === part);
+            if (!child) {
+                child = {
+                    name: part,
+                    fullName: parts.slice(0, i + 1).join('.'),
+                    children: [],
+                    isLeaf,
+                };
+                cur.children.push(child);
+            }
+            cur = child;
+        });
+    }
+    const sort = (nodes: TreeNode[]) => {
+        nodes.sort((a, b) => {
+            if (a.isLeaf !== b.isLeaf) return a.isLeaf ? 1 : -1;
+            return a.name.localeCompare(b.name);
+        });
+        nodes.forEach((n) => sort(n.children));
+    };
+    sort(root.children);
+    return root.children;
+}
+
+interface MethodTreeProps {
+    methods: string[];
+    selected: string;
+    onSelect: (method: string) => void;
+}
+
+export function MethodTree({ methods, selected, onSelect }: MethodTreeProps) {
+    const tree = useMemo(() => buildTree(methods), [methods]);
+
+    if (methods.length === 0) {
+        return <p className="empty">暂无可用方法。</p>;
+    }
+
+    return (
+        <ul className="tree">
+            {tree.map((n) => (
+                <Node
+                    key={n.fullName}
+                    node={n}
+                    selected={selected}
+                    onSelect={onSelect}
+                    depth={0}
+                />
+            ))}
+        </ul>
+    );
+}
+
+interface NodeProps {
+    node: TreeNode;
+    selected: string;
+    onSelect: (method: string) => void;
+    depth: number;
+}
+
+function Node({ node, selected, onSelect, depth }: NodeProps) {
+    const [open, setOpen] = useState(false); // ← 默认折叠
+
+    if (node.isLeaf) {
+        const active = selected === node.fullName;
+        return (
+            <li
+                className={`leaf${active ? ' active' : ''}`}
+                style={{ paddingLeft: depth * 14 }}
+                onClick={() => onSelect(node.fullName)}
+                title={node.fullName}
+            >
+                {node.name}
+            </li>
+        );
+    }
+
+    return (
+        <li>
+            <div
+                className="dir-row"
+                style={{ paddingLeft: depth * 14 }}
+                onClick={() => setOpen((o) => !o)}
+            >
+                <span className="expander">{open ? '▾' : '▸'}</span>
+                <span className="dir">{node.name}</span>
+            </div>
+            {open && (
+                <ul>
+                    {node.children.map((c) => (
+                        <Node
+                            key={c.fullName}
+                            node={c}
+                            selected={selected}
+                            onSelect={onSelect}
+                            depth={depth + 1}
+                        />
+                    ))}
+                </ul>
+            )}
+        </li>
+    );
+}