starpc 0.0.1 → 0.1.2

package/dist/srpc/client-rpc.js

@@ -0,0 +1,176 @@
+import { Packet } from './rpcproto';
+import { pushable } from 'it-pushable';
+// ClientRPC is an ongoing RPC from the client side.
+export class ClientRPC {
+    // sink is the data sink for incoming messages.
+    sink;
+    // source is the packet source for outgoing Packets.
+    source;
+    // _source is used to write to the source.
+    _source;
+    // service is the rpc service
+    service;
+    // method is the rpc method
+    method;
+    // dataCb is called with any incoming data.
+    dataCb;
+    // started is resolved when the request starts.
+    started;
+    // onStarted is called by the message handler when the request starts.
+    onStarted;
+    // complete is resolved when the request completes.
+    // rejected with an error if the call encountered any error.
+    complete;
+    // onComplete is called by the message handler when the call completes.
+    onComplete;
+    // closed indicates close has been called
+    closed;
+    constructor(service, method, dataCb) {
+        this.closed = false;
+        this.sink = this._createSink();
+        const sourcev = this._createSource();
+        this.source = sourcev;
+        this._source = sourcev;
+        this.service = service;
+        this.method = method;
+        if (dataCb) {
+            this.dataCb = dataCb;
+        }
+        this.started = new Promise((resolveStarted, rejectStarted) => {
+            this.onStarted = (err) => {
+                if (err) {
+                    rejectStarted(err);
+                }
+                else {
+                    resolveStarted();
+                }
+            };
+        });
+        this.complete = new Promise((resolveComplete, rejectComplete) => {
+            this.onComplete = (err) => {
+                this.closed = true;
+                if (err) {
+                    rejectComplete(err);
+                }
+                else {
+                    resolveComplete();
+                }
+            };
+        });
+    }
+    // waitStarted returns the started promise.
+    waitStarted() {
+        return this.started;
+    }
+    // waitComplete returns the complete promise.
+    waitComplete() {
+        return this.complete;
+    }
+    // writeCallStart writes the call start packet.
+    async writeCallStart(data) {
+        const callStart = {
+            rpcService: this.service,
+            rpcMethod: this.method,
+            data: data || new Uint8Array(0),
+        };
+        await this.writePacket({
+            body: {
+                $case: 'callStart',
+                callStart,
+            },
+        });
+    }
+    // writeCallData writes the call data packet.
+    async writeCallData(data, complete, error) {
+        const callData = {
+            data,
+            complete: complete || false,
+            error: error || "",
+        };
+        await this.writePacket({
+            body: {
+                $case: 'callData',
+                callData,
+            },
+        });
+    }
+    // writePacket writes a packet to the stream.
+    async writePacket(packet) {
+        this._source.push(packet);
+    }
+    // handleMessage handles an incoming encoded Packet.
+    //
+    // note: may throw an error if the message was unexpected or invalid.
+    async handleMessage(message) {
+        return this.handlePacket(Packet.decode(message));
+    }
+    // handlePacket handles an incoming packet.
+    async handlePacket(packet) {
+        switch (packet?.body?.$case) {
+            case 'callStart':
+                return this.handleCallStart(packet.body.callStart);
+            case 'callStartResp':
+                return this.handleCallStartResp(packet.body.callStartResp);
+            case 'callData':
+                return this.handleCallData(packet.body.callData);
+        }
+    }
+    // handleCallStart handles a CallStart packet.
+    async handleCallStart(packet) {
+        // we do not implement server -> client RPCs.
+        throw new Error(`unexpected server to client rpc: ${packet.rpcService}/${packet.rpcMethod}`);
+    }
+    // handleCallStartResp handles a CallStartResp packet.
+    async handleCallStartResp(packet) {
+        if (packet.error && packet.error.length) {
+            const err = new Error(packet.error);
+            this.onStarted(err);
+            this.onComplete(err);
+        }
+    }
+    // handleCallData handles a CallData packet.
+    async handleCallData(packet) {
+        const data = packet.data;
+        if (this.dataCb && data?.length) {
+            await this.dataCb(data);
+        }
+        if (packet.error && packet.error.length) {
+            this.onComplete(new Error(packet.error));
+        }
+        else if (packet.complete) {
+            this.onComplete();
+        }
+    }
+    // close closes the active call if not already completed.
+    async close(err) {
+        if (!this.closed) {
+            await this.writeCallData(new Uint8Array(0), true, err ? err.message : "");
+        }
+        if (!err) {
+            err = new Error('call closed');
+        }
+        this.onComplete(err);
+    }
+    // _createSink initializes the sink field.
+    _createSink() {
+        return async (source) => {
+            try {
+                for await (const msg of source) {
+                    await this.handlePacket(msg);
+                }
+            }
+            catch (err) {
+                this.close(err);
+            }
+        };
+    }
+    // _createSource initializes the source field.
+    _createSource() {
+        return pushable({
+            objectMode: true,
+            onEnd: (err) => {
+                this.onComplete(err);
+            },
+        });
+    }
+}

package/dist/srpc/client.d.ts

@@ -0,0 +1,12 @@
+import { Observable } from 'rxjs';
+import type { TsProtoRpc } from './ts-proto-rpc';
+import type { OpenStreamFunc } from './stream';
+export declare class Client implements TsProtoRpc {
+    private openConnFn;
+    constructor(openConnFn: OpenStreamFunc);
+    request(service: string, method: string, data: Uint8Array): Promise<Uint8Array>;
+    clientStreamingRequest(service: string, method: string, data: Observable<Uint8Array>): Promise<Uint8Array>;
+    serverStreamingRequest(service: string, method: string, data: Uint8Array): Observable<Uint8Array>;
+    bidirectionalStreamingRequest(service: string, method: string, data: Observable<Uint8Array>): Observable<Uint8Array>;
+    private startRpc;
+}

package/dist/srpc/client.js

@@ -0,0 +1,129 @@
+import { from as observableFrom } from 'rxjs';
+import { ClientRPC } from './client-rpc';
+import { pipe } from 'it-pipe';
+import { pushable } from 'it-pushable';
+import { decodePacketSource, encodePacketSource, parseLengthPrefixTransform, prependLengthPrefixTransform, } from './packet';
+// unaryDataCb builds a new unary request data callback.
+function unaryDataCb(resolve) {
+    return async (data) => {
+        // resolve the promise
+        resolve(data);
+        // this is the last data we expect.
+        return false;
+    };
+}
+// streamingDataCb builds a new streaming request data callback.
+/*
+function streamingDataCb(resolve: (data: Uint8Array) => void): DataCb {
+  return async (
+    data: Uint8Array
+  ): Promise<boolean | void> => {
+    // TODO
+  }
+}
+*/
+// writeClientStream registers the subscriber to write the client data stream.
+function writeClientStream(call, data) {
+    data.subscribe({
+        next(value) {
+            call.writeCallData(value);
+        },
+        error(err) {
+            call.close(err);
+        },
+        complete() {
+            call.writeCallData(new Uint8Array(0), true);
+        },
+    });
+}
+// waitCallComplete handles the call complete promise.
+function waitCallComplete(call, resolve, reject) {
+    call.waitComplete().catch(reject).finally(() => {
+        // ensure we resolve it if no data was ever returned.
+        resolve(new Uint8Array());
+    });
+}
+// Client implements the ts-proto Rpc interface with the drpcproto protocol.
+export class Client {
+    // openConnFn is the open connection function.
+    // called when starting RPC.
+    openConnFn;
+    constructor(openConnFn) {
+        this.openConnFn = openConnFn;
+    }
+    // request starts a non-streaming request.
+    async request(service, method, data) {
+        return new Promise((resolve, reject) => {
+            const dataCb = unaryDataCb(resolve);
+            this.startRpc(service, method, data, dataCb)
+                .then((call) => {
+                waitCallComplete(call, resolve, reject);
+            })
+                .catch(reject);
+        });
+    }
+    // clientStreamingRequest starts a client side streaming request.
+    clientStreamingRequest(service, method, data) {
+        return new Promise((resolve, reject) => {
+            const dataCb = unaryDataCb(resolve);
+            this.startRpc(service, method, null, dataCb)
+                .then((call) => {
+                writeClientStream(call, data);
+                waitCallComplete(call, resolve, reject);
+            })
+                .catch(reject);
+        });
+    }
+    // serverStreamingRequest starts a server-side streaming request.
+    serverStreamingRequest(service, method, data) {
+        const pushServerData = pushable();
+        const serverData = observableFrom(pushServerData);
+        const dataCb = async (data) => {
+            // push the message to the observable
+            pushServerData.push(data);
+            // expect more messages
+            return true;
+        };
+        this.startRpc(service, method, data, dataCb)
+            .then((call) => {
+            call.waitComplete().catch((err) => {
+                pushServerData.throw(err);
+            }).finally(() => {
+                pushServerData.end();
+            });
+        })
+            .catch(pushServerData.throw.bind(pushServerData));
+        return serverData;
+    }
+    // bidirectionalStreamingRequest starts a two-way streaming request.
+    bidirectionalStreamingRequest(service, method, data) {
+        const pushServerData = pushable();
+        const serverData = observableFrom(pushServerData);
+        const dataCb = async (data) => {
+            // push the message to the observable
+            pushServerData.push(data);
+            // expect more messages
+            return true;
+        };
+        this.startRpc(service, method, null, dataCb)
+            .then((call) => {
+            writeClientStream(call, data);
+            call.waitComplete().catch((err) => {
+                pushServerData.throw(err);
+            }).finally(() => {
+                pushServerData.end();
+            });
+        })
+            .catch(pushServerData.throw.bind(pushServerData));
+        return serverData;
+    }
+    // startRpc is a common utility function to begin a rpc call.
+    // throws any error starting the rpc call
+    async startRpc(rpcService, rpcMethod, data, dataCb) {
+        const conn = await this.openConnFn();
+        const call = new ClientRPC(rpcService, rpcMethod, dataCb);
+        pipe(conn, parseLengthPrefixTransform(), decodePacketSource, call, encodePacketSource, prependLengthPrefixTransform(), conn);
+        await call.writeCallStart(data || undefined);
+        return call;
+    }
+}

package/dist/srpc/conn.d.ts

@@ -0,0 +1,14 @@
+import type { Stream } from '@libp2p/interfaces/connection';
+import type { Duplex } from 'it-stream-types';
+import type { Stream as SRPCStream } from './stream';
+import { Client } from './client';
+export declare class Conn implements Duplex<Uint8Array> {
+    private muxer;
+    constructor();
+    get sink(): import("it-stream-types").Sink<Uint8Array, Promise<void>>;
+    get source(): AsyncIterable<Uint8Array>;
+    get streams(): Stream[];
+    buildClient(): Client;
+    openStream(): Promise<SRPCStream>;
+    private handleIncomingStream;
+}

package/dist/srpc/conn.js

@@ -0,0 +1,38 @@
+import { Components } from '@libp2p/interfaces/components';
+import { MplexStreamMuxer } from '@libp2p/mplex';
+import { Client } from './client';
+// Conn implements a generic connection with a two-way stream.
+export class Conn {
+    // muxer is the mplex stream muxer.
+    muxer;
+    constructor() {
+        // see https://github.com/libp2p/js-libp2p-mplex/pull/179
+        this.muxer = new MplexStreamMuxer(new Components(), {
+            onIncomingStream: this.handleIncomingStream.bind(this),
+        });
+    }
+    // sink returns the message sink.
+    get sink() {
+        return this.muxer.sink;
+    }
+    // source returns the outgoing message source.
+    get source() {
+        return this.muxer.source;
+    }
+    // streams returns the set of all ongoing streams.
+    get streams() {
+        return this.muxer.streams;
+    }
+    // buildClient builds a new client from the connection.
+    buildClient() {
+        return new Client(this.openStream.bind(this));
+    }
+    // openStream implements the client open stream function.
+    async openStream() {
+        return this.muxer.newStream();
+    }
+    // handleIncomingStream handles an incoming stream.
+    handleIncomingStream(strm) {
+        strm.abort(new Error('server -> client streams not implemented'));
+    }
+}

package/dist/srpc/index.d.ts

@@ -0,0 +1,3 @@
+export { Client } from './client';
+export type { OpenStreamFunc } from './stream';
+export { WebSocketConn } from './websocket';

package/dist/srpc/index.js

@@ -0,0 +1,2 @@
+export { Client } from './client';
+export { WebSocketConn } from './websocket';

package/dist/srpc/packet.d.ts

@@ -0,0 +1,9 @@
+import type { Source, Transform } from 'it-stream-types';
+import { Packet } from './rpcproto';
+export declare function decodePacketSource(source: Source<Uint8Array | Uint8Array[]>): AsyncIterable<Packet>;
+export declare function encodePacketSource(source: Source<Packet | Packet[]>): AsyncIterable<Uint8Array>;
+export declare function prependLengthPrefixTransform(): Transform<Uint8Array>;
+export declare function parseLengthPrefixTransform(): Transform<Uint8Array>;
+export declare function encodeUint32Le(value: number): Uint8Array;
+export declare function decodeUint32Le(data: Uint8Array): number;
+export declare function prependPacketLen(msgData: Uint8Array): Uint8Array;

package/dist/srpc/packet.js

@@ -0,0 +1,89 @@
+import { Packet } from './rpcproto';
+import { encode as lengthPrefixEncode, decode as lengthPrefixDecode, } from 'it-length-prefixed';
+// decodePacketSource unmarshals and async yields encoded Packets.
+export async function* decodePacketSource(source) {
+    for await (const pkt of source) {
+        if (Array.isArray(pkt)) {
+            for (const p of pkt) {
+                yield* [Packet.decode(p)];
+            }
+        }
+        else {
+            yield* [Packet.decode(pkt)];
+        }
+    }
+}
+// encodePacketSource marshals and async yields packets.
+export async function* encodePacketSource(source) {
+    for await (const pkt of source) {
+        if (Array.isArray(pkt)) {
+            for (const p of pkt) {
+                yield* [Packet.encode(p).finish()];
+            }
+        }
+        else {
+            yield* [Packet.encode(pkt).finish()];
+        }
+    }
+}
+// uint32LEDecode removes the length prefix.
+const uint32LEDecode = (data) => {
+    if (data.length < 4) {
+        throw RangeError('Could not decode int32BE');
+    }
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    return view.getUint32(0, true);
+};
+uint32LEDecode.bytes = 4;
+// uint32LEEncode adds the length prefix.
+const uint32LEEncode = (value, target, offset) => {
+    target = target ?? new Uint8Array(4);
+    const view = new DataView(target.buffer, target.byteOffset, target.byteLength);
+    view.setUint32(offset ?? 0, value, true);
+    return target;
+};
+uint32LEEncode.bytes = 4;
+// prependLengthPrefixTransform adds a length prefix to a message source.
+// little-endian uint32
+export function prependLengthPrefixTransform() {
+    return lengthPrefixEncode({ lengthEncoder: uint32LEEncode });
+}
+// parseLengthPrefixTransform parses the length prefix from a message source.
+// little-endian uint32
+export function parseLengthPrefixTransform() {
+    return lengthPrefixDecode({ lengthDecoder: uint32LEDecode });
+}
+// encodeUint32Le encodes the number as a uint32 with little endian.
+export function encodeUint32Le(value) {
+    // output is a 4 byte array
+    const output = new Uint8Array(4);
+    for (let index = 0; index < output.length; index++) {
+        const b = value & 0xff;
+        output[index] = b;
+        value = (value - b) / 256;
+    }
+    return output;
+}
+// decodeUint32Le decodes a uint32 from a 4 byte Uint8Array.
+// returns 0 if decoding failed.
+// callers should check that len(data) == 4
+export function decodeUint32Le(data) {
+    let value = 0;
+    let nbytes = 4;
+    if (data.length < nbytes) {
+        nbytes = data.length;
+    }
+    for (let i = nbytes - 1; i >= 0; i--) {
+        value = value * 256 + data[i];
+    }
+    return value;
+}
+// prependPacketLen adds the message length prefix to a packet.
+export function prependPacketLen(msgData) {
+    const msgLen = msgData.length;
+    const msgLenData = encodeUint32Le(msgLen);
+    const merged = new Uint8Array(msgLen + msgLenData.length);
+    merged.set(msgLenData);
+    merged.set(msgData, msgLenData.length);
+    return merged;
+}

package/dist/srpc/rpcproto.d.ts

@@ -0,0 +1,194 @@
+import Long from 'long';
+import * as _m0 from 'protobufjs/minimal';
+export declare const protobufPackage = "srpc";
+/** Packet is a message sent over a srpc packet connection. */
+export interface Packet {
+    body?: {
+        $case: 'callStart';
+        callStart: CallStart;
+    } | {
+        $case: 'callStartResp';
+        callStartResp: CallStartResp;
+    } | {
+        $case: 'callData';
+        callData: CallData;
+    };
+}
+/** CallStart requests starting a new RPC call. */
+export interface CallStart {
+    /**
+     * RpcService is the service to contact.
+     * Must be set.
+     */
+    rpcService: string;
+    /**
+     * RpcMethod is the RPC method to call.
+     * Must be set.
+     */
+    rpcMethod: string;
+    /**
+     * Data contains the request or the first message in the stream.
+     * Optional if streaming.
+     */
+    data: Uint8Array;
+}
+/** CallStartResp is the response to CallStart. */
+export interface CallStartResp {
+    /**
+     * Error contains any error starting the RPC call.
+     * Empty if successful.
+     */
+    error: string;
+}
+/** CallData contains a message in a streaming RPC sequence. */
+export interface CallData {
+    /** Data contains the packet in the sequence. */
+    data: Uint8Array;
+    /** Complete indicates the RPC call is completed. */
+    complete: boolean;
+    /**
+     * Error contains any error that caused the RPC to fail.
+     * If set, implies complete=true.
+     */
+    error: string;
+}
+export declare const Packet: {
+    encode(message: Packet, writer?: _m0.Writer): _m0.Writer;
+    decode(input: _m0.Reader | Uint8Array, length?: number): Packet;
+    fromJSON(object: any): Packet;
+    toJSON(message: Packet): unknown;
+    fromPartial<I extends {
+        body?: ({
+            callStart?: {
+                rpcService?: string | undefined;
+                rpcMethod?: string | undefined;
+                data?: Uint8Array | undefined;
+            } | undefined;
+        } & {
+            $case: "callStart";
+        }) | ({
+            callStartResp?: {
+                error?: string | undefined;
+            } | undefined;
+        } & {
+            $case: "callStartResp";
+        }) | ({
+            callData?: {
+                data?: Uint8Array | undefined;
+                complete?: boolean | undefined;
+                error?: string | undefined;
+            } | undefined;
+        } & {
+            $case: "callData";
+        }) | undefined;
+    } & {
+        body?: ({
+            callStart?: {
+                rpcService?: string | undefined;
+                rpcMethod?: string | undefined;
+                data?: Uint8Array | undefined;
+            } | undefined;
+        } & {
+            $case: "callStart";
+        } & {
+            callStart?: ({
+                rpcService?: string | undefined;
+                rpcMethod?: string | undefined;
+                data?: Uint8Array | undefined;
+            } & {
+                rpcService?: string | undefined;
+                rpcMethod?: string | undefined;
+                data?: Uint8Array | undefined;
+            } & Record<Exclude<keyof I["body"]["callStart"], keyof CallStart>, never>) | undefined;
+            $case: "callStart";
+        } & Record<Exclude<keyof I["body"], "$case" | "callStart">, never>) | ({
+            callStartResp?: {
+                error?: string | undefined;
+            } | undefined;
+        } & {
+            $case: "callStartResp";
+        } & {
+            callStartResp?: ({
+                error?: string | undefined;
+            } & {
+                error?: string | undefined;
+            } & Record<Exclude<keyof I["body"]["callStartResp"], "error">, never>) | undefined;
+            $case: "callStartResp";
+        } & Record<Exclude<keyof I["body"], "$case" | "callStartResp">, never>) | ({
+            callData?: {
+                data?: Uint8Array | undefined;
+                complete?: boolean | undefined;
+                error?: string | undefined;
+            } | undefined;
+        } & {
+            $case: "callData";
+        } & {
+            callData?: ({
+                data?: Uint8Array | undefined;
+                complete?: boolean | undefined;
+                error?: string | undefined;
+            } & {
+                data?: Uint8Array | undefined;
+                complete?: boolean | undefined;
+                error?: string | undefined;
+            } & Record<Exclude<keyof I["body"]["callData"], keyof CallData>, never>) | undefined;
+            $case: "callData";
+        } & Record<Exclude<keyof I["body"], "$case" | "callData">, never>) | undefined;
+    } & Record<Exclude<keyof I, "body">, never>>(object: I): Packet;
+};
+export declare const CallStart: {
+    encode(message: CallStart, writer?: _m0.Writer): _m0.Writer;
+    decode(input: _m0.Reader | Uint8Array, length?: number): CallStart;
+    fromJSON(object: any): CallStart;
+    toJSON(message: CallStart): unknown;
+    fromPartial<I extends {
+        rpcService?: string | undefined;
+        rpcMethod?: string | undefined;
+        data?: Uint8Array | undefined;
+    } & {
+        rpcService?: string | undefined;
+        rpcMethod?: string | undefined;
+        data?: Uint8Array | undefined;
+    } & Record<Exclude<keyof I, keyof CallStart>, never>>(object: I): CallStart;
+};
+export declare const CallStartResp: {
+    encode(message: CallStartResp, writer?: _m0.Writer): _m0.Writer;
+    decode(input: _m0.Reader | Uint8Array, length?: number): CallStartResp;
+    fromJSON(object: any): CallStartResp;
+    toJSON(message: CallStartResp): unknown;
+    fromPartial<I extends {
+        error?: string | undefined;
+    } & {
+        error?: string | undefined;
+    } & Record<Exclude<keyof I, "error">, never>>(object: I): CallStartResp;
+};
+export declare const CallData: {
+    encode(message: CallData, writer?: _m0.Writer): _m0.Writer;
+    decode(input: _m0.Reader | Uint8Array, length?: number): CallData;
+    fromJSON(object: any): CallData;
+    toJSON(message: CallData): unknown;
+    fromPartial<I extends {
+        data?: Uint8Array | undefined;
+        complete?: boolean | undefined;
+        error?: string | undefined;
+    } & {
+        data?: Uint8Array | undefined;
+        complete?: boolean | undefined;
+        error?: string | undefined;
+    } & Record<Exclude<keyof I, keyof CallData>, never>>(object: I): CallData;
+};
+declare type Builtin = Date | Function | Uint8Array | string | number | boolean | undefined;
+export declare type DeepPartial<T> = T extends Builtin ? T : T extends Long ? string | number | Long : T extends Array<infer U> ? Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends {
+    $case: string;
+} ? {
+    [K in keyof Omit<T, '$case'>]?: DeepPartial<T[K]>;
+} & {
+    $case: T['$case'];
+} : T extends {} ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : Partial<T>;
+declare type KeysOfUnion<T> = T extends T ? keyof T : never;
+export declare type Exact<P, I extends P> = P extends Builtin ? P : P & {
+    [K in keyof P]: Exact<P[K], I[K]>;
+} & Record<Exclude<keyof I, KeysOfUnion<P>>, never>;
+export {};