@cloudpss/ubrpc 0.4.10

package/src/socket.ts

@@ -0,0 +1,304 @@
+import type WebSocket from 'isomorphic-ws';
+import { from, Observable, Subscriber, Subscription } from 'rxjs';
+import type {
+    ConnectionID,
+    RpcCallPayload,
+    RpcMetadata,
+    RpcNotifyPayload,
+    RpcPayload,
+    RpcSubscribePayload,
+} from './types/payload.js';
+import type {
+    Methods,
+    Notifications,
+    ObservableLike,
+    RpcObject,
+    RpcParameters,
+    RpcReturns,
+    Subjects,
+} from './types/utils.js';
+import { send } from './utils/messaging.js';
+import { decodePayload, deserializeError, serializeError } from './utils/serialize.js';
+import { ready } from './utils/websocket.js';
+
+/** RPC 连接 */
+export abstract class RpcSocket<TRemote extends {}, TLocal extends {}> {
+    constructor(readonly id: ConnectionID, local?: RpcObject<TLocal>) {
+        this.__local = local;
+        this.ready = new Promise((...args) => (this.__readyCallbacks = args));
+    }
+    protected _localMetadata?: RpcMetadata;
+    protected _remoteMetadata?: RpcMetadata;
+    /** 本地认证信息 */
+    get localMetadata(): RpcMetadata | undefined {
+        return this._localMetadata;
+    }
+    /** 远程认证信息 */
+    get remoteMetadata(): RpcMetadata | undefined {
+        return this._remoteMetadata;
+    }
+    /** 连接是否已认证 */
+    get authenticated(): boolean {
+        return this._remoteMetadata != null;
+    }
+    private readonly __local?: RpcObject<TLocal>;
+    /** 用于响应调用的本地对象 */
+    protected get local(): RpcObject<TLocal> | undefined {
+        return this.__local;
+    }
+    private __socket?: WebSocket;
+    /** 作为底层传输的 WebSocket */
+    get socket(): WebSocket {
+        if (!this.__socket) throw new Error(`Socket not initialized`);
+        return this.__socket;
+    }
+    protected set socket(value: WebSocket) {
+        if (this.__socket === value) return;
+        this.__socket = value;
+        void this.initSocket(this.__socket, value).then(...this.__readyCallbacks);
+    }
+    private __readyCallbacks!: Parameters<ConstructorParameters<typeof Promise<void>>[0]>;
+    protected ready: Promise<void>;
+    private readonly __handlers = Object.freeze({
+        open: (ev: WebSocket.Event) => this.onOpen(ev),
+        close: (ev: WebSocket.CloseEvent) => this.onClose(ev),
+        error: (ev: WebSocket.ErrorEvent) => this.onError(ev),
+        message: (ev: WebSocket.MessageEvent) => this.onMessage(ev),
+    } as const);
+    /** 初始化 WebSocket */
+    protected async initSocket(oldValue: WebSocket | undefined, newValue: WebSocket): Promise<void> {
+        try {
+            if (oldValue) {
+                oldValue.removeEventListener('open', this.__handlers.open);
+                oldValue.removeEventListener('close', this.__handlers.close);
+                oldValue.removeEventListener('error', this.__handlers.error);
+                oldValue.removeEventListener('message', this.__handlers.message);
+            }
+            await ready(newValue);
+            const info = await this.authSocket();
+            if (this.__socket === newValue) {
+                newValue.addEventListener('open', this.__handlers.open);
+                newValue.addEventListener('close', this.__handlers.close);
+                newValue.addEventListener('error', this.__handlers.error);
+                newValue.addEventListener('message', this.__handlers.message);
+                this._remoteMetadata = info ?? {};
+            }
+        } catch (ex) {
+            this._remoteMetadata = undefined;
+            throw ex;
+        }
+    }
+    /** 认证 WebSocket */
+    protected abstract authSocket(): Promise<RpcMetadata>;
+    /** 响应 WebSocket error */
+    protected onError(_ev: WebSocket.ErrorEvent): void {
+        this._remoteMetadata = undefined;
+    }
+    /** 响应 WebSocket open */
+    protected onOpen(_ev: WebSocket.Event): void {
+        //
+    }
+    /** 响应 WebSocket close */
+    protected onClose(ev: WebSocket.CloseEvent): void {
+        this._remoteMetadata = undefined;
+        if (ev.code === 1000) {
+            this.destroy();
+        } else {
+            this.ready = new Promise((...args) => (this.__readyCallbacks = args));
+        }
+    }
+    /** 响应 WebSocket message */
+    protected onMessage(ev: WebSocket.MessageEvent): void {
+        const payload = decodePayload(ev.data);
+        let error;
+        if (payload) {
+            const handled = this.onPayload(payload);
+            if (!handled) error = [payload.seq, `Unrecognized message, not handled.`] as const;
+        } else {
+            error = [this.nextSeq(), `Invalid message, unknown format.`] as const;
+        }
+        if (error) {
+            void this.sendPayload('error', {
+                seq: error[0],
+                error: serializeError(new SyntaxError(error[1])),
+            });
+        }
+    }
+
+    /** 响应 Rpc 消息 */
+    protected onPayload(payload: RpcPayload): boolean {
+        switch (payload.type) {
+            case 'call':
+            case 'notify':
+                void this.localCall(payload);
+                return true;
+            case 'return': {
+                const pending = this.pendingCalls.get(payload.seq);
+                // 即使不存在等待的请求，也认为响应是有效的
+                if (!pending) return true;
+                this.pendingCalls.delete(payload.seq);
+                if (payload.error) {
+                    pending[1](deserializeError(payload.error));
+                } else {
+                    pending[0](payload.result);
+                }
+                return true;
+            }
+            case 'subscribe':
+                void this.localSubscribe(payload);
+                return true;
+            case 'unsubscribe': {
+                const subscription = this.localSubscription.get(payload.seq);
+                // 即使不存在对应订阅，也认为响应是有效的
+                if (!subscription) return true;
+                subscription.unsubscribe();
+                this.localSubscription.delete(payload.seq);
+                return true;
+            }
+            case 'publish': {
+                const subscriber = this.pendingSubscriptions.get(payload.seq);
+                // 即使不存在对应订阅，也认为响应是有效的
+                if (!subscriber) {
+                    void this.sendPayload('unsubscribe', { seq: payload.seq });
+                    return true;
+                }
+                if (payload.error) {
+                    subscriber.error(deserializeError(payload.error));
+                } else if (payload.complete) {
+                    subscriber.complete();
+                } else {
+                    subscriber.next(payload.next);
+                }
+                return true;
+            }
+            case 'error':
+                return true;
+            default:
+                return false;
+        }
+    }
+    /** 调用本地方法 */
+    protected async localCall(payload: RpcCallPayload | RpcNotifyPayload): Promise<void> {
+        const noReturn = payload.type === 'notify';
+        const method = this.local ? this.local[payload.method as Methods<TLocal>] : undefined;
+        const seq = payload.seq;
+        if (typeof method != 'function') {
+            if (noReturn) return;
+            return this.sendPayload('return', {
+                seq,
+                error: serializeError(new TypeError(`${payload.method} is not a function`)),
+            });
+        }
+        try {
+            const result: unknown = await Reflect.apply(method, this.local, payload.args);
+            if (noReturn) return;
+            return this.sendPayload('return', { seq, result });
+        } catch (ex) {
+            if (noReturn) return;
+            return this.sendPayload('return', { seq, error: serializeError(ex) });
+        }
+    }
+    private readonly localSubscription = new Map<number, Subscription>();
+    /** 调用本地方法 */
+    protected async localSubscribe(payload: RpcSubscribePayload): Promise<void> {
+        const method = this.local ? this.local[payload.method as Subjects<TLocal>] : undefined;
+        const seq = payload.seq;
+        if (typeof method != 'function') {
+            return this.sendPayload('publish', {
+                seq,
+                error: serializeError(new TypeError(`${payload.method} is not a function`)),
+            });
+        }
+        try {
+            const result = from((await Reflect.apply(method, this.local, payload.args)) as ObservableLike<unknown>);
+            const subscription = result.subscribe({
+                next: (value) => {
+                    void this.sendPayload('publish', { seq, next: value });
+                },
+                error: (err) => {
+                    this.localSubscription.delete(payload.seq);
+                    void this.sendPayload('publish', { seq, error: serializeError(err) });
+                },
+                complete: () => {
+                    this.localSubscription.delete(payload.seq);
+                    void this.sendPayload('publish', { seq, complete: true });
+                },
+            });
+            this.localSubscription.set(seq, subscription);
+        } catch (ex) {
+            return this.sendPayload('publish', { seq, error: serializeError(ex) });
+        }
+    }
+    /** 发送数据 */
+    protected async sendPayload<T extends RpcPayload['type']>(
+        type: T,
+        info: Omit<RpcPayload & { type: T }, 'type'>,
+    ): Promise<void> {
+        await this.ready;
+        send(this.socket, type, info);
+    }
+    /** 序列号 */
+    protected seq = 0;
+    /** 获取下一个序列号 */
+    protected nextSeq(): number {
+        const seq = this.seq;
+        this.seq += 2;
+        return seq;
+    }
+    private readonly pendingCalls = new Map<
+        number,
+        [resolve: (result: unknown) => void, reject: (error: Error) => void]
+    >();
+    /** 调用远程方法 */
+    call<TMethod extends Methods<TRemote>>(
+        method: TMethod,
+        ...args: RpcParameters<TRemote[TMethod]>
+    ): Promise<RpcReturns<TRemote[TMethod]>> {
+        return new Promise((resolve, reject) => {
+            const seq = this.nextSeq();
+            void this.sendPayload('call', { seq, method, args });
+            this.pendingCalls.set(seq, [resolve as (result: unknown) => void, reject]);
+        });
+    }
+    /** 调用远程方法，放弃返回值 */
+    notify<TNotification extends Notifications<TRemote>>(
+        method: TNotification,
+        ...args: RpcParameters<TRemote[TNotification]>
+    ): void {
+        const seq = this.nextSeq();
+        void this.sendPayload('notify', { seq, method, args });
+    }
+
+    private readonly pendingSubscriptions = new Map<number, Subscriber<unknown>>();
+    /** 调用远程订阅 */
+    subscribe<TSubject extends Subjects<TRemote>>(
+        method: TSubject,
+        ...args: RpcParameters<TRemote[TSubject]>
+    ): Observable<RpcReturns<TRemote[TSubject]>> {
+        return new Observable((subscriber) => {
+            const seq = this.nextSeq();
+            void this.sendPayload('subscribe', { seq, method, args });
+            this.pendingSubscriptions.set(seq, subscriber);
+            return () => {
+                this.pendingSubscriptions.delete(seq);
+                void this.sendPayload('unsubscribe', { seq });
+            };
+        });
+    }
+    /** 结束 */
+    destroy(): void {
+        if (
+            this.__socket &&
+            (this.__socket.readyState === this.__socket.CONNECTING || this.__socket.readyState === this.__socket.OPEN)
+        ) {
+            this.__socket.close(1000);
+            this.__socket = undefined;
+        }
+        this.localSubscription.forEach((s) => s.unsubscribe());
+        this.localSubscription.clear();
+        this.pendingCalls.forEach(([, reject]) => reject(new Error(`RPC Socket closed.`)));
+        this.pendingCalls.clear();
+        this.pendingSubscriptions.forEach((s) => s.error(new Error(`RPC Socket closed.`)));
+        this.pendingSubscriptions.clear();
+    }
+}

package/src/types/payload.ts

@@ -0,0 +1,115 @@
+/** RPC 连接 ID */
+export type ConnectionID = string & { tag: 'ConnectionID' };
+/** 认证信息 */
+export type RpcMetadata = Record<string, unknown>;
+
+/** RPC 错误 */
+export interface RpcErrorLike {
+    /** 名称 */
+    name: string;
+    /** 消息 */
+    message: string;
+    /** 调用 */
+    stack?: string;
+    /** 引发错误的其他错误 */
+    errors?: RpcErrorLike[];
+}
+
+/** RPC 调用的通用属性 */
+interface RpcPayloadBase {
+    /** 调用类型 */
+    type: string;
+    /** 序列号 */
+    seq: number;
+}
+
+/** RPC 认证调用 */
+export interface RpcAuthPayload extends RpcPayloadBase {
+    /** @inheritdoc */
+    type: 'auth';
+    /** 连接 ID */
+    id: ConnectionID;
+    /** 协议版本 */
+    version: number;
+    /** 认证信息 */
+    metadata: RpcMetadata;
+    /** 异常 */
+    error?: RpcErrorLike;
+}
+
+/** RPC 方法调用 */
+export interface RpcCallPayload extends RpcPayloadBase {
+    /** @inheritdoc */
+    type: 'call';
+    /** 调用的方法 */
+    method: string;
+    /** 参数 */
+    args: unknown[];
+}
+
+/** RPC 方法返回 */
+export interface RpcReturnPayload extends RpcPayloadBase {
+    /** @inheritdoc */
+    type: 'return';
+    /** 返回值 */
+    result?: unknown;
+    /** 异常 */
+    error?: RpcErrorLike;
+}
+
+/** RPC 通知 */
+export interface RpcNotifyPayload extends RpcPayloadBase {
+    /** @inheritdoc */
+    type: 'notify';
+    /** 调用的方法 */
+    method: string;
+    /** 参数 */
+    args: unknown[];
+}
+
+/** RPC 订阅 */
+export interface RpcSubscribePayload extends RpcPayloadBase {
+    /** @inheritdoc */
+    type: 'subscribe';
+    /** 调用的方法 */
+    method: string;
+    /** 参数 */
+    args: unknown[];
+}
+
+/** RPC 发布 */
+export interface RpcPublishPayload extends RpcPayloadBase {
+    /** @inheritdoc */
+    type: 'publish';
+    /** 发布的值 */
+    next?: unknown;
+    /** 异常结束 */
+    error?: RpcErrorLike;
+    /** 正常结束 */
+    complete?: true;
+}
+
+/** RPC 取消订阅 */
+export interface RpcUnsubscribePayload extends RpcPayloadBase {
+    /** @inheritdoc */
+    type: 'unsubscribe';
+}
+
+/** RPC 错误 */
+export interface RpcErrorPayload extends RpcPayloadBase {
+    /** @inheritdoc */
+    type: 'error';
+    /** 异常 */
+    error: RpcErrorLike;
+}
+
+/** RPC 调用 */
+export type RpcPayload =
+    | RpcCallPayload
+    | RpcReturnPayload
+    | RpcNotifyPayload
+    | RpcPublishPayload
+    | RpcSubscribePayload
+    | RpcUnsubscribePayload
+    | RpcAuthPayload
+    | RpcErrorPayload;

package/src/types/utils.ts

@@ -0,0 +1,83 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { InteropObservable, Observable } from 'rxjs';
+
+/** 可转换为 Observable 的类型 */
+export type ObservableLike<T> = Observable<T> | InteropObservable<T> | AsyncIterable<T>;
+
+/** Returns a boolean for whether the two given types are equal. */
+type IsEqual<A, B> = (<G>() => G extends A ? 1 : 2) extends <G>() => G extends B ? 1 : 2 ? true : false;
+
+/** 作为通知输出的方法 */
+type IsNotificationReturn<R> = IsEqual<R, void> extends true
+    ? true
+    : IsEqual<R, undefined> extends true
+    ? true
+    : R extends PromiseLike<void> | void
+    ? true
+    : false;
+
+/** 作为 Observable 输出的方法 */
+type ObservableReturn = ObservableLike<any> | PromiseLike<ObservableLike<any>>;
+
+/** 提取类型中的方法 */
+export type Methods<T> = {
+    [P in keyof T]: T[P] extends (...args: any[]) => infer R ? (R extends ObservableReturn ? never : P) : never;
+}[keyof T] &
+    string;
+/** 提取类型中的通知 */
+export type Notifications<T> = {
+    [P in keyof T]: T[P] extends (...args: any[]) => infer R
+        ? IsNotificationReturn<R> extends true
+            ? P
+            : never
+        : never;
+}[keyof T] &
+    string;
+/** 提取类型中的订阅主题 */
+export type Subjects<T> = {
+    [P in keyof T]: T[P] extends (...args: any[]) => ObservableReturn ? P : never;
+}[keyof T] &
+    string;
+
+/** RPC 调用的参数 */
+export type RpcParameters<T> = T extends (...args: infer R) => any ? R : never;
+/** RPC 调用的返回 */
+export type RpcReturns<T> = T extends (...args: any[]) => infer R
+    ? Awaited<R> extends ObservableLike<infer U>
+        ? U
+        : Awaited<R>
+    : never;
+
+/** RPC 调用函数的实现 */
+type RpcField<T> = T extends (...args: infer P) => infer R
+    ? Awaited<R> extends ObservableReturn
+        ? (...args: P) => ObservableLike<RpcReturns<T>> | PromiseLike<ObservableLike<RpcReturns<T>>>
+        : (...args: P) => RpcReturns<T> | PromiseLike<RpcReturns<T>>
+    : never;
+
+/** RPC 调用对象的实现 */
+export type RpcObject<T> = {
+    [K in Methods<T> | Subjects<T>]: RpcField<T[K]>;
+};
+
+// interface A {
+//     field: number;
+//     methodA(x: number): number | undefined;
+//     methodB: (x: string, y: number) => Promise<number>;
+//     readonly methodC: () => Iterable<number>;
+//     readonly methodD: () => void | Promise<null | undefined>;
+//     readonly notificationA: () => undefined;
+//     readonly notificationB: () => Promise<void>;
+//     notificationC(): void;
+//     readonly notificationD: () => void | PromiseLike<undefined>;
+//     readonly notificationE: () => void | Promise<void>;
+//     subjectA(x: number): Observable<number>;
+//     subjectB: (x: string) => Promise<Observable<number>>;
+//     subjectC: () => PromiseLike<InteropObservable<number>>;
+//     subjectD: () => AsyncGenerator<number>;
+//     subjectE: () => PromiseLike<AsyncGenerator<number>>;
+// }
+
+// type X = Methods<A>;
+// type Y = Subjects<A>;
+// type Z = Notifications<A>;

package/src/utils/messaging.ts

@@ -0,0 +1,17 @@
+import type WebSocket from 'isomorphic-ws';
+import { encode } from '@cloudpss/ubjson';
+import type { RpcPayload } from '../types/payload.js';
+
+/** 发送消息 */
+export function send<T extends RpcPayload['type']>(
+    socket: WebSocket,
+    type: T,
+    info: Omit<RpcPayload & { type: T }, 'type'>,
+): void {
+    socket.send(
+        encode({
+            ...info,
+            type,
+        }),
+    );
+}

package/src/utils/serialize.ts

@@ -0,0 +1,67 @@
+import { decode } from '@cloudpss/ubjson';
+import type WebSocket from 'isomorphic-ws';
+import type { RpcErrorLike, RpcPayload } from '../types/payload.js';
+
+/** 反序列化 */
+export function decodePayload(data: WebSocket.Data): RpcPayload | undefined {
+    if (!data || typeof data == 'string') return undefined;
+    if (Array.isArray(data)) data = Buffer.concat(data);
+    try {
+        const payload = decode(data) as RpcPayload;
+        if (!payload || typeof payload != 'object') return undefined;
+        if (typeof payload.type !== 'string') return undefined;
+        if (typeof payload.seq !== 'number') return undefined;
+        return payload;
+    } catch (ex) {
+        return undefined;
+    }
+}
+
+const serializing = Symbol('serializing error');
+/** 序列化错误信息 */
+export function serializeError(error: unknown): RpcErrorLike {
+    if (error == null)
+        return {
+            name: 'Error',
+            message: '',
+        };
+    if (typeof error != 'object')
+        return {
+            name: 'Error',
+            message: String(error),
+        };
+    try {
+        const reenter = !!(error as { [serializing]?: true })[serializing];
+        (error as { [serializing]?: true })[serializing] = true;
+        const { message, stack, name, errors, ...rest } = error as AggregateError;
+        return {
+            ...rest,
+            name: String(name ?? 'Error'),
+            message: String(message ?? ''),
+            stack: stack,
+            errors: reenter ? undefined : Array.isArray(errors) ? errors.map(serializeError) : errors,
+        };
+    } finally {
+        delete (error as { [serializing]?: true })[serializing];
+    }
+}
+/** 反序列化错误信息 */
+export function deserializeError(error: RpcErrorLike): Error {
+    if (error == null || typeof error != 'object') return new Error(error ?? '');
+    const { message, stack, name, errors, ...rest } = error;
+    let ex;
+    if (Array.isArray(errors)) {
+        ex = new AggregateError(errors.map(deserializeError), message);
+    } else {
+        ex = new Error(message);
+    }
+    if (name !== ex?.name)
+        Object.defineProperty(ex, 'name', { value: String(name), configurable: true, writable: true });
+    Object.defineProperty(ex, 'stack', {
+        value: stack ? String(stack) : undefined,
+        configurable: true,
+        writable: true,
+    });
+    Object.assign(ex, rest);
+    return ex;
+}

package/src/utils/websocket.ts

@@ -0,0 +1,22 @@
+import type WebSocket from 'isomorphic-ws';
+
+/** 等待连接建立 */
+export function ready(socket: WebSocket): Promise<void> {
+    switch (socket.readyState) {
+        case socket.CONNECTING:
+            return new Promise((resolve, reject) => {
+                socket.addEventListener('open', () => resolve(), { once: true });
+                socket.addEventListener('error', (ev) => reject(ev.error ?? new Error(`Failed to connect`)), {
+                    once: true,
+                });
+            });
+        case socket.OPEN:
+            return Promise.resolve();
+        case socket.CLOSING:
+            return Promise.reject(new Error(`Socket is closing.`));
+        case socket.CLOSED:
+            return Promise.reject(new Error(`Socket is closed.`));
+        default:
+            return Promise.reject(new Error(`Socket is in unknown state.`));
+    }
+}

package/src/version.ts

@@ -0,0 +1 @@
+export const VERSION = 1;

package/tests/client.js

@@ -0,0 +1,20 @@
+/* eslint-disable no-console */
+import { RpcClientSocket } from '@cloudpss/ubrpc';
+import { setTimeout } from 'node:timers/promises';
+import { WebSocket } from 'ws';
+
+const rpc = new RpcClientSocket('ws://localhost:8090');
+//await setTimeout(1000);
+const result = await rpc.call('hello', 'world');
+console.log(result);
+
+const s = rpc.subscribe('timer', 1000).subscribe({
+    next: console.log,
+    complete: () => console.log('complete'),
+    error: () => console.log('error'),
+});
+await setTimeout(1000);
+s.unsubscribe();
+rpc.socket.close(3600);
+
+new WebSocket('ws://localhost:8090');

package/tests/server.js

@@ -0,0 +1,44 @@
+/* eslint-disable no-console */
+import { RpcServer } from '@cloudpss/ubrpc';
+import { interval, take, tap } from 'rxjs';
+import { WebSocketServer } from 'ws';
+const a = {
+    greetings: 'Hello, ',
+    /**
+     *
+     * @param {string} name
+     * @returns  {Promise<string>}
+     */
+    async hello(name) {
+        return `${this.greetings}${name}`;
+    },
+    timer(i) {
+        return interval(i).pipe(
+            take(10),
+            tap({
+                next: console.log,
+                complete: () => console.log('complete'),
+                error: () => console.log('error'),
+                subscribe: () => console.log('subscribe'),
+                unsubscribe: () => console.log('unsubscribe'),
+                finalize: () => console.log('finalize'),
+            }),
+        );
+    },
+};
+const rpc = new RpcServer(a, (meta) => {
+    console.log(meta);
+    throw new Error('B');
+});
+const server = new WebSocketServer({
+    host: 'localhost',
+    port: 8090,
+    path: '/',
+});
+server.on('connection', async (socket) => {
+    try {
+        await rpc.connect(socket);
+    } catch (ex) {
+        console.log(ex);
+    }
+});