starpc 0.1.7 → 0.2.0

package/dist/srpc/mux.js

@@ -0,0 +1,36 @@
+// createMux builds a new Mux.
+export function createMux() {
+    return new StaticMux();
+}
+// StaticMux contains a in-memory mapping between service ID and handlers.
+// implements Mux
+export class StaticMux {
+    // services contains a mapping from service id to handlers.
+    services = {};
+    register(handler) {
+        const serviceID = handler?.getServiceID();
+        if (!serviceID) {
+            throw new Error('service id cannot be empty');
+        }
+        const serviceMethods = this.services[serviceID] || {};
+        const methodIDs = handler.getMethodIDs();
+        for (const methodID of methodIDs) {
+            serviceMethods[methodID] = handler;
+        }
+        this.services[serviceID] = serviceMethods;
+    }
+    async lookupMethod(serviceID, methodID) {
+        if (!serviceID) {
+            return null;
+        }
+        const serviceMethods = this.services[serviceID];
+        if (!serviceMethods) {
+            return null;
+        }
+        const handler = serviceMethods[methodID];
+        if (!handler) {
+            return null;
+        }
+        return await handler.lookupMethod(serviceID, methodID);
+    }
+}

package/dist/srpc/packet.d.ts

@@ -1,7 +1,7 @@
-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>;
+import type { Transform } from 'it-stream-types';
+import { Packet } from './rpcproto.js';
+export declare const decodePacketSource: (source: import("it-stream-types").Source<Uint8Array | Uint8Array[]>) => AsyncIterable<Packet>;
+export declare const encodePacketSource: (source: import("it-stream-types").Source<Packet | Packet[]>) => AsyncIterable<Uint8Array>;
 export declare function prependLengthPrefixTransform(): Transform<Uint8Array>;
 export declare function parseLengthPrefixTransform(): Transform<Uint8Array>;
 export declare function encodeUint32Le(value: number): Uint8Array;

package/dist/srpc/packet.js

@@ -1,31 +1,10 @@
-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()];
-        }
-    }
-}
+import { Packet } from './rpcproto.js';
+import { buildDecodeMessageTransform, buildEncodeMessageTransform, } from './message.js';
+// decodePacketSource decodes packets from a binary data stream.
+export const decodePacketSource = buildDecodeMessageTransform(Packet);
+// encodePacketSource encodes packets from a packet object stream.
+export const encodePacketSource = buildEncodeMessageTransform(Packet);
 // uint32LEDecode removes the length prefix.
 const uint32LEDecode = (data) => {
     if (data.length < 4) {
@@ -87,3 +66,35 @@ export function prependPacketLen(msgData) {
     merged.set(msgData, msgLenData.length);
     return merged;
 }
+/*
+// buildCallDataPacket builds a CallData packet.
+function buildCallDataPacket(data: Uint8Array): Packet {
+  const callData: CallData = {
+    data: p,
+    complete: false,
+    error: '',
+  }
+  const pkt: Packet = {
+    body: {
+      $case: 'callData',
+      callData: callData,
+    }
+  }
+  return pkt
+}
+
+// wrapCallDataTransform is a transformer that wraps call data into a Packet.
+export async function* wrapCallDataTransform(
+  source: Source<Uint8Array | Uint8Array>
+): AsyncIterable<Packet> {
+  for await (const pkt of source) {
+    if (Array.isArray(pkt)) {
+      for (const p of pkt) {
+        yield* [buildCallDataPacket(p)]
+      }
+    } else {
+      yield* [buildCallDataPacket(pkt)]
+    }
+  }
+}
+*/

package/dist/srpc/rpcproto.d.ts

@@ -6,9 +6,6 @@ export interface Packet {
     body?: {
         $case: 'callStart';
         callStart: CallStart;
-    } | {
-        $case: 'callStartResp';
-        callStartResp: CallStartResp;
     } | {
         $case: 'callData';
         callData: CallData;
@@ -31,19 +28,15 @@ export interface CallStart {
      * 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;
+    /** DataIsZero indicates Data is set with an empty message. */
+    dataIsZero: boolean;
 }
 /** CallData contains a message in a streaming RPC sequence. */
 export interface CallData {
     /** Data contains the packet in the sequence. */
     data: Uint8Array;
+    /** DataIsZero indicates Data is set with an empty message. */
+    dataIsZero: boolean;
     /** Complete indicates the RPC call is completed. */
     complete: boolean;
     /**
@@ -63,18 +56,14 @@ export declare const Packet: {
                 rpcService?: string | undefined;
                 rpcMethod?: string | undefined;
                 data?: Uint8Array | undefined;
+                dataIsZero?: boolean | undefined;
             } | undefined;
         } & {
             $case: "callStart";
-        }) | ({
-            callStartResp?: {
-                error?: string | undefined;
-            } | undefined;
-        } & {
-            $case: "callStartResp";
         }) | ({
             callData?: {
                 data?: Uint8Array | undefined;
+                dataIsZero?: boolean | undefined;
                 complete?: boolean | undefined;
                 error?: string | undefined;
             } | undefined;
@@ -87,6 +76,7 @@ export declare const Packet: {
                 rpcService?: string | undefined;
                 rpcMethod?: string | undefined;
                 data?: Uint8Array | undefined;
+                dataIsZero?: boolean | undefined;
             } | undefined;
         } & {
             $case: "callStart";
@@ -95,28 +85,18 @@ export declare const Packet: {
                 rpcService?: string | undefined;
                 rpcMethod?: string | undefined;
                 data?: Uint8Array | undefined;
+                dataIsZero?: boolean | undefined;
             } & {
                 rpcService?: string | undefined;
                 rpcMethod?: string | undefined;
                 data?: Uint8Array | undefined;
+                dataIsZero?: boolean | 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>) | ({
+        } & Record<Exclude<keyof I["body"], "callStart" | "$case">, never>) | ({
             callData?: {
                 data?: Uint8Array | undefined;
+                dataIsZero?: boolean | undefined;
                 complete?: boolean | undefined;
                 error?: string | undefined;
             } | undefined;
@@ -125,15 +105,17 @@ export declare const Packet: {
         } & {
             callData?: ({
                 data?: Uint8Array | undefined;
+                dataIsZero?: boolean | undefined;
                 complete?: boolean | undefined;
                 error?: string | undefined;
             } & {
                 data?: Uint8Array | undefined;
+                dataIsZero?: boolean | 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"], "callData" | "$case">, never>) | undefined;
     } & Record<Exclude<keyof I, "body">, never>>(object: I): Packet;
 };
 export declare const CallStart: {
@@ -145,23 +127,14 @@ export declare const CallStart: {
         rpcService?: string | undefined;
         rpcMethod?: string | undefined;
         data?: Uint8Array | undefined;
+        dataIsZero?: boolean | undefined;
     } & {
         rpcService?: string | undefined;
         rpcMethod?: string | undefined;
         data?: Uint8Array | undefined;
+        dataIsZero?: boolean | 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;
@@ -169,10 +142,12 @@ export declare const CallData: {
     toJSON(message: CallData): unknown;
     fromPartial<I extends {
         data?: Uint8Array | undefined;
+        dataIsZero?: boolean | undefined;
         complete?: boolean | undefined;
         error?: string | undefined;
     } & {
         data?: Uint8Array | undefined;
+        dataIsZero?: boolean | undefined;
         complete?: boolean | undefined;
         error?: string | undefined;
     } & Record<Exclude<keyof I, keyof CallData>, never>>(object: I): CallData;

package/dist/srpc/rpcproto.js

@@ -10,11 +10,8 @@ export const Packet = {
         if (message.body?.$case === 'callStart') {
             CallStart.encode(message.body.callStart, writer.uint32(10).fork()).ldelim();
         }
-        if (message.body?.$case === 'callStartResp') {
-            CallStartResp.encode(message.body.callStartResp, writer.uint32(18).fork()).ldelim();
-        }
         if (message.body?.$case === 'callData') {
-            CallData.encode(message.body.callData, writer.uint32(26).fork()).ldelim();
+            CallData.encode(message.body.callData, writer.uint32(18).fork()).ldelim();
         }
         return writer;
     },
@@ -32,12 +29,6 @@ export const Packet = {
                     };
                     break;
                 case 2:
-                    message.body = {
-                        $case: 'callStartResp',
-                        callStartResp: CallStartResp.decode(reader, reader.uint32()),
-                    };
-                    break;
-                case 3:
                     message.body = {
                         $case: 'callData',
                         callData: CallData.decode(reader, reader.uint32()),
@@ -57,14 +48,9 @@ export const Packet = {
                     $case: 'callStart',
                     callStart: CallStart.fromJSON(object.callStart),
                 }
-                : isSet(object.callStartResp)
-                    ? {
-                        $case: 'callStartResp',
-                        callStartResp: CallStartResp.fromJSON(object.callStartResp),
-                    }
-                    : isSet(object.callData)
-                        ? { $case: 'callData', callData: CallData.fromJSON(object.callData) }
-                        : undefined,
+                : isSet(object.callData)
+                    ? { $case: 'callData', callData: CallData.fromJSON(object.callData) }
+                    : undefined,
         };
     },
     toJSON(message) {
@@ -73,10 +59,6 @@ export const Packet = {
             (obj.callStart = message.body?.callStart
                 ? CallStart.toJSON(message.body?.callStart)
                 : undefined);
-        message.body?.$case === 'callStartResp' &&
-            (obj.callStartResp = message.body?.callStartResp
-                ? CallStartResp.toJSON(message.body?.callStartResp)
-                : undefined);
         message.body?.$case === 'callData' &&
             (obj.callData = message.body?.callData
                 ? CallData.toJSON(message.body?.callData)
@@ -93,14 +75,6 @@ export const Packet = {
                 callStart: CallStart.fromPartial(object.body.callStart),
             };
         }
-        if (object.body?.$case === 'callStartResp' &&
-            object.body?.callStartResp !== undefined &&
-            object.body?.callStartResp !== null) {
-            message.body = {
-                $case: 'callStartResp',
-                callStartResp: CallStartResp.fromPartial(object.body.callStartResp),
-            };
-        }
         if (object.body?.$case === 'callData' &&
             object.body?.callData !== undefined &&
             object.body?.callData !== null) {
@@ -113,7 +87,12 @@ export const Packet = {
     },
 };
 function createBaseCallStart() {
-    return { rpcService: '', rpcMethod: '', data: new Uint8Array() };
+    return {
+        rpcService: '',
+        rpcMethod: '',
+        data: new Uint8Array(),
+        dataIsZero: false,
+    };
 }
 export const CallStart = {
     encode(message, writer = _m0.Writer.create()) {
@@ -126,6 +105,9 @@ export const CallStart = {
         if (message.data.length !== 0) {
             writer.uint32(26).bytes(message.data);
         }
+        if (message.dataIsZero === true) {
+            writer.uint32(32).bool(message.dataIsZero);
+        }
         return writer;
     },
     decode(input, length) {
@@ -144,6 +126,9 @@ export const CallStart = {
                 case 3:
                     message.data = reader.bytes();
                     break;
+                case 4:
+                    message.dataIsZero = reader.bool();
+                    break;
                 default:
                     reader.skipType(tag & 7);
                     break;
@@ -158,6 +143,7 @@ export const CallStart = {
             data: isSet(object.data)
                 ? bytesFromBase64(object.data)
                 : new Uint8Array(),
+            dataIsZero: isSet(object.dataIsZero) ? Boolean(object.dataIsZero) : false,
         };
     },
     toJSON(message) {
@@ -166,6 +152,7 @@ export const CallStart = {
         message.rpcMethod !== undefined && (obj.rpcMethod = message.rpcMethod);
         message.data !== undefined &&
             (obj.data = base64FromBytes(message.data !== undefined ? message.data : new Uint8Array()));
+        message.dataIsZero !== undefined && (obj.dataIsZero = message.dataIsZero);
         return obj;
     },
     fromPartial(object) {
@@ -173,65 +160,31 @@ export const CallStart = {
         message.rpcService = object.rpcService ?? '';
         message.rpcMethod = object.rpcMethod ?? '';
         message.data = object.data ?? new Uint8Array();
-        return message;
-    },
-};
-function createBaseCallStartResp() {
-    return { error: '' };
-}
-export const CallStartResp = {
-    encode(message, writer = _m0.Writer.create()) {
-        if (message.error !== '') {
-            writer.uint32(10).string(message.error);
-        }
-        return writer;
-    },
-    decode(input, length) {
-        const reader = input instanceof _m0.Reader ? input : new _m0.Reader(input);
-        let end = length === undefined ? reader.len : reader.pos + length;
-        const message = createBaseCallStartResp();
-        while (reader.pos < end) {
-            const tag = reader.uint32();
-            switch (tag >>> 3) {
-                case 1:
-                    message.error = reader.string();
-                    break;
-                default:
-                    reader.skipType(tag & 7);
-                    break;
-            }
-        }
-        return message;
-    },
-    fromJSON(object) {
-        return {
-            error: isSet(object.error) ? String(object.error) : '',
-        };
-    },
-    toJSON(message) {
-        const obj = {};
-        message.error !== undefined && (obj.error = message.error);
-        return obj;
-    },
-    fromPartial(object) {
-        const message = createBaseCallStartResp();
-        message.error = object.error ?? '';
+        message.dataIsZero = object.dataIsZero ?? false;
         return message;
     },
 };
 function createBaseCallData() {
-    return { data: new Uint8Array(), complete: false, error: '' };
+    return {
+        data: new Uint8Array(),
+        dataIsZero: false,
+        complete: false,
+        error: '',
+    };
 }
 export const CallData = {
     encode(message, writer = _m0.Writer.create()) {
         if (message.data.length !== 0) {
             writer.uint32(10).bytes(message.data);
         }
+        if (message.dataIsZero === true) {
+            writer.uint32(16).bool(message.dataIsZero);
+        }
         if (message.complete === true) {
-            writer.uint32(16).bool(message.complete);
+            writer.uint32(24).bool(message.complete);
         }
         if (message.error !== '') {
-            writer.uint32(26).string(message.error);
+            writer.uint32(34).string(message.error);
         }
         return writer;
     },
@@ -246,9 +199,12 @@ export const CallData = {
                     message.data = reader.bytes();
                     break;
                 case 2:
-                    message.complete = reader.bool();
+                    message.dataIsZero = reader.bool();
                     break;
                 case 3:
+                    message.complete = reader.bool();
+                    break;
+                case 4:
                     message.error = reader.string();
                     break;
                 default:
@@ -263,6 +219,7 @@ export const CallData = {
             data: isSet(object.data)
                 ? bytesFromBase64(object.data)
                 : new Uint8Array(),
+            dataIsZero: isSet(object.dataIsZero) ? Boolean(object.dataIsZero) : false,
             complete: isSet(object.complete) ? Boolean(object.complete) : false,
             error: isSet(object.error) ? String(object.error) : '',
         };
@@ -271,6 +228,7 @@ export const CallData = {
         const obj = {};
         message.data !== undefined &&
             (obj.data = base64FromBytes(message.data !== undefined ? message.data : new Uint8Array()));
+        message.dataIsZero !== undefined && (obj.dataIsZero = message.dataIsZero);
         message.complete !== undefined && (obj.complete = message.complete);
         message.error !== undefined && (obj.error = message.error);
         return obj;
@@ -278,6 +236,7 @@ export const CallData = {
     fromPartial(object) {
         const message = createBaseCallData();
         message.data = object.data ?? new Uint8Array();
+        message.dataIsZero = object.dataIsZero ?? false;
         message.complete = object.complete ?? false;
         message.error = object.error ?? '';
         return message;

package/dist/srpc/server-rpc.d.ts

@@ -0,0 +1,11 @@
+import type { CallData, CallStart } from './rpcproto.js';
+import { CommonRPC } from './common-rpc.js';
+import { Mux } from './mux.js';
+export declare class ServerRPC extends CommonRPC {
+    private mux;
+    constructor(mux: Mux);
+    handleCallStart(packet: Partial<CallStart>): Promise<void>;
+    handleCallData(packet: Partial<CallData>): Promise<void>;
+    private invokeRPC;
+    private _createDataSink;
+}

package/dist/srpc/server-rpc.js

@@ -0,0 +1,55 @@
+import { CommonRPC } from './common-rpc.js';
+// ServerRPC is an ongoing RPC from the server side.
+export class ServerRPC extends CommonRPC {
+    // mux is used to handle incoming rpcs.
+    mux;
+    constructor(mux) {
+        super();
+        this.mux = mux;
+    }
+    // handleCallStart handles a CallStart cket.
+    async handleCallStart(packet) {
+        if (this.service || this.method) {
+            throw new Error('call start must be sent only once');
+        }
+        this.service = packet.rpcService;
+        this.method = packet.rpcMethod;
+        if (!this.service || !this.method) {
+            throw new Error('rpcService and rpcMethod cannot be empty');
+        }
+        const methodDef = await this.mux.lookupMethod(this.service, this.method);
+        if (!methodDef) {
+            throw new Error(`not found: ${this.service}/${this.method}`);
+        }
+        this.pushRpcData(packet.data, packet.dataIsZero);
+        this.invokeRPC(methodDef);
+    }
+    // handleCallData handles a CallData packet.
+    async handleCallData(packet) {
+        if (!this.service || !this.method) {
+            throw new Error('call start must be sent before call data');
+        }
+        return super.handleCallData(packet);
+    }
+    // invokeRPC starts invoking the RPC handler.
+    invokeRPC(invokeFn) {
+        const dataSink = this._createDataSink();
+        invokeFn(this.rpcDataSource, dataSink).catch((err) => {
+            this.close(err);
+        });
+    }
+    // _createDataSink creates a sink for outgoing data packets.
+    _createDataSink() {
+        return async (source) => {
+            try {
+                for await (const msg of source) {
+                    await this.writeCallData(msg);
+                }
+                await this.writeCallData(undefined, true);
+            }
+            catch (err) {
+                this.close(err);
+            }
+        };
+    }
+}

package/dist/srpc/server.d.ts

@@ -0,0 +1,14 @@
+import { Stream } from '@libp2p/interface-connection';
+import { Duplex } from 'it-stream-types';
+import { Mux } from './mux.js';
+import { ServerRPC } from './server-rpc.js';
+import { Packet } from './rpcproto.js';
+import { StreamHandler } from './conn.js';
+export declare class Server implements StreamHandler {
+    private mux;
+    constructor(mux: Mux);
+    startRpc(): ServerRPC;
+    handleStream(stream: Stream): Promise<void>;
+    handleDuplex(stream: Duplex<Uint8Array>): Promise<void>;
+    handlePacketStream(stream: Duplex<Packet>): Promise<void>;
+}

package/dist/srpc/server.js

@@ -0,0 +1,31 @@
+import { pipe } from 'it-pipe';
+import { ServerRPC } from './server-rpc.js';
+import { parseLengthPrefixTransform, prependLengthPrefixTransform, decodePacketSource, encodePacketSource, } from './packet.js';
+// Server implements the SRPC server in TypeScript with a Mux.
+export class Server {
+    // mux is the mux used to handle requests.
+    mux;
+    constructor(mux) {
+        this.mux = mux;
+    }
+    // startRpc starts a new server-side RPC.
+    // the returned RPC handles incoming Packets.
+    startRpc() {
+        return new ServerRPC(this.mux);
+    }
+    // handleStream handles an incoming Uint8Array message duplex.
+    // closes the stream when the rpc completes.
+    handleStream(stream) {
+        return this.handleDuplex(stream);
+    }
+    // handleDuplex handles an incoming message duplex.
+    async handleDuplex(stream) {
+        const rpc = this.startRpc();
+        await pipe(stream, parseLengthPrefixTransform(), decodePacketSource, rpc, encodePacketSource, prependLengthPrefixTransform(), stream);
+    }
+    // handlePacketStream handles an incoming Packet duplex.
+    async handlePacketStream(stream) {
+        const rpc = this.startRpc();
+        await pipe(stream, rpc, stream);
+    }
+}

package/dist/srpc/websocket.d.ts

@@ -1,7 +1,8 @@
-import { Conn } from './conn.js';
 import type WebSocket from 'isomorphic-ws';
+import { Conn } from './conn.js';
+import { Server } from './server.js';
 export declare class WebSocketConn extends Conn {
     private socket;
-    constructor(socket: WebSocket);
+    constructor(socket: WebSocket, server?: Server);
     getSocket(): WebSocket;
 }

package/dist/srpc/websocket.js

@@ -1,13 +1,13 @@
-import { Conn } from './conn.js';
 import { duplex } from 'it-ws';
 import { pipe } from 'it-pipe';
 import { Mplex } from '@libp2p/mplex';
-// WebSocketConn implements a connection with a WebSocket.
+import { Conn } from './conn.js';
+// WebSocketConn implements a connection with a WebSocket and optional Server.
 export class WebSocketConn extends Conn {
     // socket is the web socket
     socket;
-    constructor(socket) {
-        super({
+    constructor(socket, server) {
+        super(server, {
             muxerFactory: new Mplex(),
         });
         this.socket = socket;

package/e2e/README.md

@@ -0,0 +1,10 @@
+# E2E
+
+E2E contains tests using the client and server written in the same language.
+
+For example:
+
+ - Go Client calling Go server: "go test" or "yarn test:go"
+ - TypeScript client calling TypeScript server: "yarn test:js"
+
+For cross-language tests, i.e. Ts <-> Go, see [integration](../integration).