starpc 0.1.7 → 0.2.0

package/Makefile

@@ -102,6 +102,7 @@ gents: $(PROTOWRAP) node_modules
 		--ts_proto_opt=forceLong=long \
 		--ts_proto_opt=oneof=unions \
 		--ts_proto_opt=esModuleInterop=true \
+		--ts_proto_opt=outputServices=default,outputServices=generic-definitions \
 		--proto_path $$(pwd)/vendor \
 		--print_structure \
 		--only_specified_files \

package/README.md

@@ -56,7 +56,7 @@ message EchoMsg {
 }
 ```
 
-## Go
+## Go: Server & Client
 
 A basic example can be found in the [e2e test]:
 
@@ -103,6 +103,29 @@ for WebSockets.
 
 This repository uses protowrap, see the [Makefile](./Makefile).
 
+`WebSocketConn` uses [js-libp2p-mplex] to multiplex streams over the WebSocket.
+
+[js-libp2p-mplex]: https://github.com/libp2p/js-libp2p-mplex
+
+### Server
+
+```typescript
+import { WebSocketConn, Server, createMux } from '../srpc'
+import { EchoerClientImpl } from '../echo/echo'
+
+const mux = createMux()
+mux.register(TODO)
+const server = new Server(mux)
+
+// TODO: accept a WebSocket-like object.
+const ws = TODO
+const channel = new WebSocketConn(ws, server)
+// incoming streams will be handled by server.
+```
+
+
+### Client
+
 ```typescript
 import { WebSocketConn } from '../srpc'
 import { EchoerClientImpl } from '../echo/echo'
@@ -127,10 +150,6 @@ result = await demoServiceClient.EchoClientStream(clientRequestStream)
 console.log('success: output', result.body)
 ```
 
-`WebSocketConn` uses [js-libp2p-mplex] to multiplex streams over the WebSocket.
-
-[js-libp2p-mplex]: https://github.com/libp2p/js-libp2p-mplex
-
 # Attribution
 
 `protoc-gen-go-starpc` is a heavily modified version of `protoc-gen-go-drpc`.

package/dist/echo/client-test.d.ts

@@ -0,0 +1,2 @@
+import { Client } from '../srpc/index.js';
+export declare function runClientTest(client: Client): Promise<void>;

package/dist/echo/client-test.js

@@ -0,0 +1,35 @@
+import { EchoerClientImpl } from './echo.js';
+import { Observable } from 'rxjs';
+export async function runClientTest(client) {
+    const demoServiceClient = new EchoerClientImpl(client);
+    console.log('Calling Echo: unary call...');
+    let result = await demoServiceClient.Echo({
+        body: 'Hello world!',
+    });
+    console.log('success: output', result.body);
+    // observable for client requests
+    const clientRequestStream = new Observable((subscriber) => {
+        subscriber.next({ body: 'Hello world from streaming request.' });
+        subscriber.complete();
+    });
+    console.log('Calling EchoClientStream: client -> server...');
+    result = await demoServiceClient.EchoClientStream(clientRequestStream);
+    console.log('success: output', result.body);
+    console.log('Calling EchoServerStream: server -> client...');
+    const serverStream = demoServiceClient.EchoServerStream({
+        body: 'Hello world from server to client streaming request.',
+    });
+    await new Promise((resolve, reject) => {
+        serverStream.subscribe({
+            next(result) {
+                console.log('server: output', result.body);
+            },
+            complete() {
+                resolve();
+            },
+            error(err) {
+                reject(err);
+            },
+        });
+    });
+}

package/dist/echo/echo.d.ts

@@ -36,6 +36,130 @@ export declare class EchoerClientImpl implements Echoer {
     EchoClientStream(request: Observable<EchoMsg>): Promise<EchoMsg>;
     EchoBidiStream(request: Observable<EchoMsg>): Observable<EchoMsg>;
 }
+/** Echoer service returns the given message. */
+export declare type EchoerDefinition = typeof EchoerDefinition;
+export declare const EchoerDefinition: {
+    readonly name: "Echoer";
+    readonly fullName: "echo.Echoer";
+    readonly methods: {
+        /** Echo returns the given message. */
+        readonly echo: {
+            readonly name: "Echo";
+            readonly requestType: {
+                encode(message: EchoMsg, writer?: _m0.Writer): _m0.Writer;
+                decode(input: _m0.Reader | Uint8Array, length?: number): EchoMsg;
+                fromJSON(object: any): EchoMsg;
+                toJSON(message: EchoMsg): unknown;
+                fromPartial<I extends {
+                    body?: string | undefined;
+                } & {
+                    body?: string | undefined;
+                } & Record<Exclude<keyof I, "body">, never>>(object: I): EchoMsg;
+            };
+            readonly requestStream: false;
+            readonly responseType: {
+                encode(message: EchoMsg, writer?: _m0.Writer): _m0.Writer;
+                decode(input: _m0.Reader | Uint8Array, length?: number): EchoMsg;
+                fromJSON(object: any): EchoMsg;
+                toJSON(message: EchoMsg): unknown;
+                fromPartial<I extends {
+                    body?: string | undefined;
+                } & {
+                    body?: string | undefined;
+                } & Record<Exclude<keyof I, "body">, never>>(object: I): EchoMsg;
+            };
+            readonly responseStream: false;
+            readonly options: {};
+        };
+        /** EchoServerStream is an example of a server -> client one-way stream. */
+        readonly echoServerStream: {
+            readonly name: "EchoServerStream";
+            readonly requestType: {
+                encode(message: EchoMsg, writer?: _m0.Writer): _m0.Writer;
+                decode(input: _m0.Reader | Uint8Array, length?: number): EchoMsg;
+                fromJSON(object: any): EchoMsg;
+                toJSON(message: EchoMsg): unknown;
+                fromPartial<I extends {
+                    body?: string | undefined;
+                } & {
+                    body?: string | undefined;
+                } & Record<Exclude<keyof I, "body">, never>>(object: I): EchoMsg;
+            };
+            readonly requestStream: false;
+            readonly responseType: {
+                encode(message: EchoMsg, writer?: _m0.Writer): _m0.Writer;
+                decode(input: _m0.Reader | Uint8Array, length?: number): EchoMsg;
+                fromJSON(object: any): EchoMsg;
+                toJSON(message: EchoMsg): unknown;
+                fromPartial<I extends {
+                    body?: string | undefined;
+                } & {
+                    body?: string | undefined;
+                } & Record<Exclude<keyof I, "body">, never>>(object: I): EchoMsg;
+            };
+            readonly responseStream: true;
+            readonly options: {};
+        };
+        /** EchoClientStream is an example of client->server one-way stream. */
+        readonly echoClientStream: {
+            readonly name: "EchoClientStream";
+            readonly requestType: {
+                encode(message: EchoMsg, writer?: _m0.Writer): _m0.Writer;
+                decode(input: _m0.Reader | Uint8Array, length?: number): EchoMsg;
+                fromJSON(object: any): EchoMsg;
+                toJSON(message: EchoMsg): unknown;
+                fromPartial<I extends {
+                    body?: string | undefined;
+                } & {
+                    body?: string | undefined;
+                } & Record<Exclude<keyof I, "body">, never>>(object: I): EchoMsg;
+            };
+            readonly requestStream: true;
+            readonly responseType: {
+                encode(message: EchoMsg, writer?: _m0.Writer): _m0.Writer;
+                decode(input: _m0.Reader | Uint8Array, length?: number): EchoMsg;
+                fromJSON(object: any): EchoMsg;
+                toJSON(message: EchoMsg): unknown;
+                fromPartial<I extends {
+                    body?: string | undefined;
+                } & {
+                    body?: string | undefined;
+                } & Record<Exclude<keyof I, "body">, never>>(object: I): EchoMsg;
+            };
+            readonly responseStream: false;
+            readonly options: {};
+        };
+        /** EchoBidiStream is an example of a two-way stream. */
+        readonly echoBidiStream: {
+            readonly name: "EchoBidiStream";
+            readonly requestType: {
+                encode(message: EchoMsg, writer?: _m0.Writer): _m0.Writer;
+                decode(input: _m0.Reader | Uint8Array, length?: number): EchoMsg;
+                fromJSON(object: any): EchoMsg;
+                toJSON(message: EchoMsg): unknown;
+                fromPartial<I extends {
+                    body?: string | undefined;
+                } & {
+                    body?: string | undefined;
+                } & Record<Exclude<keyof I, "body">, never>>(object: I): EchoMsg;
+            };
+            readonly requestStream: true;
+            readonly responseType: {
+                encode(message: EchoMsg, writer?: _m0.Writer): _m0.Writer;
+                decode(input: _m0.Reader | Uint8Array, length?: number): EchoMsg;
+                fromJSON(object: any): EchoMsg;
+                toJSON(message: EchoMsg): unknown;
+                fromPartial<I extends {
+                    body?: string | undefined;
+                } & {
+                    body?: string | undefined;
+                } & Record<Exclude<keyof I, "body">, never>>(object: I): EchoMsg;
+            };
+            readonly responseStream: true;
+            readonly options: {};
+        };
+    };
+};
 interface Rpc {
     request(service: string, method: string, data: Uint8Array): Promise<Uint8Array>;
     clientStreamingRequest(service: string, method: string, data: Observable<Uint8Array>): Promise<Uint8Array>;

package/dist/echo/echo.js

@@ -76,6 +76,48 @@ export class EchoerClientImpl {
         return result.pipe(map((data) => EchoMsg.decode(new _m0.Reader(data))));
     }
 }
+export const EchoerDefinition = {
+    name: 'Echoer',
+    fullName: 'echo.Echoer',
+    methods: {
+        /** Echo returns the given message. */
+        echo: {
+            name: 'Echo',
+            requestType: EchoMsg,
+            requestStream: false,
+            responseType: EchoMsg,
+            responseStream: false,
+            options: {},
+        },
+        /** EchoServerStream is an example of a server -> client one-way stream. */
+        echoServerStream: {
+            name: 'EchoServerStream',
+            requestType: EchoMsg,
+            requestStream: false,
+            responseType: EchoMsg,
+            responseStream: true,
+            options: {},
+        },
+        /** EchoClientStream is an example of client->server one-way stream. */
+        echoClientStream: {
+            name: 'EchoClientStream',
+            requestType: EchoMsg,
+            requestStream: true,
+            responseType: EchoMsg,
+            responseStream: false,
+            options: {},
+        },
+        /** EchoBidiStream is an example of a two-way stream. */
+        echoBidiStream: {
+            name: 'EchoBidiStream',
+            requestType: EchoMsg,
+            requestStream: true,
+            responseType: EchoMsg,
+            responseStream: true,
+            options: {},
+        },
+    },
+};
 if (_m0.util.Long !== Long) {
     _m0.util.Long = Long;
     _m0.configure();

package/dist/echo/index.d.ts

@@ -0,0 +1,3 @@
+export * from './echo.js';
+export * from './server.js';
+export { runClientTest } from './client-test.js';

package/dist/echo/index.js

@@ -0,0 +1,3 @@
+export * from './echo.js';
+export * from './server.js';
+export { runClientTest } from './client-test.js';

package/dist/echo/server.d.ts

@@ -0,0 +1,8 @@
+import { Observable } from 'rxjs';
+import { Echoer, EchoMsg } from './echo';
+export declare class EchoerServer implements Echoer {
+    Echo(request: EchoMsg): Promise<EchoMsg>;
+    EchoServerStream(request: EchoMsg): Observable<EchoMsg>;
+    EchoClientStream(request: Observable<EchoMsg>): Promise<EchoMsg>;
+    EchoBidiStream(request: Observable<EchoMsg>): Observable<EchoMsg>;
+}

package/dist/echo/server.js

@@ -0,0 +1,50 @@
+import { from as observableFrom } from 'rxjs';
+import { pushable } from 'it-pushable';
+// EchoServer implements the Echoer server.
+export class EchoerServer {
+    async Echo(request) {
+        return request;
+    }
+    EchoServerStream(request) {
+        // send 5 responses, with a 200ms delay for each
+        return observableFrom((async function* response() {
+            for (let i = 0; i < 5; i++) {
+                yield request;
+                await new Promise((resolve) => setTimeout(resolve, 200));
+            }
+        })());
+    }
+    EchoClientStream(request) {
+        return new Promise((resolve, reject) => {
+            request.subscribe({
+                next(msg) {
+                    resolve(msg);
+                },
+                error(err) {
+                    reject(err);
+                },
+                complete() {
+                    reject(new Error('none received'));
+                },
+            });
+        });
+    }
+    EchoBidiStream(request) {
+        // build result observable
+        const pushResponse = pushable({ objectMode: true });
+        const response = observableFrom(pushResponse);
+        pushResponse.push({ body: 'hello from server' });
+        request.subscribe({
+            next(msg) {
+                pushResponse.push(msg);
+            },
+            error(err) {
+                pushResponse.throw(err);
+            },
+            complete() {
+                pushResponse.end();
+            },
+        });
+        return response;
+    }
+}

package/dist/echo/sever.js

@@ -0,0 +1 @@
+"use strict";

package/dist/srpc/broadcast-channel.d.ts

@@ -1,5 +1,6 @@
 import type { Duplex, Sink } from 'it-stream-types';
-import { Conn } from './conn';
+import { Conn, ConnParams } from './conn';
+import { Server } from './server';
 export declare class BroadcastChannelIterable<T> implements Duplex<T> {
     readonly channel: BroadcastChannel;
     sink: Sink<T>;
@@ -11,6 +12,6 @@ export declare class BroadcastChannelIterable<T> implements Duplex<T> {
 export declare function newBroadcastChannelIterable<T>(name: string): BroadcastChannelIterable<T>;
 export declare class BroadcastChannelConn extends Conn {
     private channel;
-    constructor(channel: BroadcastChannel);
+    constructor(channel: BroadcastChannel, server?: Server, connParams?: ConnParams);
     getBroadcastChannel(): BroadcastChannel;
 }

package/dist/srpc/broadcast-channel.js

@@ -48,8 +48,8 @@ export function newBroadcastChannelIterable(name) {
 export class BroadcastChannelConn extends Conn {
     // channel is the broadcast channel iterable
     channel;
-    constructor(channel) {
-        super();
+    constructor(channel, server, connParams) {
+        super(server, connParams);
         this.channel = new BroadcastChannelIterable(channel);
         pipe(this, this.channel, this);
     }

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

@@ -1,31 +1,7 @@
-import type { CallData, CallStart, CallStartResp } from './rpcproto';
-import { Packet } from './rpcproto';
-import type { Sink } from 'it-stream-types';
-export declare type DataCb = (data: Uint8Array) => Promise<boolean | void>;
-export declare class ClientRPC {
-    sink: Sink<Packet>;
-    source: AsyncIterable<Packet>;
-    private readonly _source;
-    private service;
-    private method;
-    private dataCb?;
-    private started;
-    private onStarted?;
-    private complete;
-    private onComplete?;
-    private closed;
-    constructor(service: string, method: string, dataCb: DataCb | null);
-    waitStarted(): Promise<void>;
-    waitComplete(): Promise<void>;
+import type { CallStart } from './rpcproto.js';
+import { CommonRPC } from './common-rpc.js';
+export declare class ClientRPC extends CommonRPC {
+    constructor(service: string, method: string);
     writeCallStart(data?: Uint8Array): Promise<void>;
-    writeCallData(data: Uint8Array, complete?: boolean, error?: string): Promise<void>;
-    private writePacket;
-    handleMessage(message: Uint8Array): Promise<void>;
-    handlePacket(packet: Partial<Packet>): Promise<void>;
     handleCallStart(packet: Partial<CallStart>): Promise<void>;
-    handleCallStartResp(packet: Partial<CallStartResp>): Promise<void>;
-    handleCallData(packet: Partial<CallData>): Promise<void>;
-    close(err?: Error): Promise<void>;
-    private _createSink;
-    private _createSource;
 }

package/dist/srpc/client-rpc.js

@@ -1,77 +1,22 @@
-import { Packet } from './rpcproto';
-import { pushable } from 'it-pushable';
+import { CommonRPC } from './common-rpc.js';
 // 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;
+export class ClientRPC extends CommonRPC {
+    constructor(service, method) {
+        super();
         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.
+    // if data === undefined and data.length === 0 sends empty data packet.
     async writeCallStart(data) {
+        if (!this.service || !this.method) {
+            throw new Error('service and method must be set');
+        }
         const callStart = {
             rpcService: this.service,
             rpcMethod: this.method,
             data: data || new Uint8Array(0),
+            dataIsZero: !!data && data.length === 0,
         };
         await this.writePacket({
             body: {
@@ -80,97 +25,9 @@ export class ClientRPC {
             },
         });
     }
-    // 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

@@ -1,6 +1,6 @@
 import { Observable } from 'rxjs';
-import type { TsProtoRpc } from './ts-proto-rpc';
-import type { OpenStreamFunc } from './stream';
+import type { TsProtoRpc } from './ts-proto-rpc.js';
+import type { OpenStreamFunc } from './stream.js';
 export declare class Client implements TsProtoRpc {
     private openConnFn;
     constructor(openConnFn: OpenStreamFunc);