starpc 0.3.4 → 0.4.0

package/Makefile

@@ -99,9 +99,10 @@ gents: $(PROTOWRAP) node_modules
 		-I $$(pwd)/vendor \
 		--plugin=./node_modules/.bin/protoc-gen-ts_proto \
 		--ts_proto_out=$$(pwd)/vendor \
+		--ts_proto_opt=esModuleInterop=true \
+		--ts_proto_opt=fileSuffix=.pb \
 		--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 \

package/README.md

@@ -1,6 +1,6 @@
 # Stream RPC
 
-**starpc** implements [Proto3 services] in both TypeScript and Go.
+**starpc** implements [Proto3 services] (server & client) in both TypeScript and Go.
 
 [Proto3 services]: https://developers.google.com/protocol-buffers/docs/proto3#services
 
@@ -13,8 +13,6 @@ Can use any Stream multiplexer: defaults to [libp2p-mplex] over a WebSocket.
 
 [libp2p-mplex]: https://github.com/libp2p/js-libp2p-mplex
 
-Note: the server has not yet been implemented in TypeScript.
-
 # Usage
 
 Starting with the [protobuf-project] repository on the "starpc" branch.
@@ -30,6 +28,8 @@ The demo/boilerplate project implements the Echo example below.
 
 [protobuf-project]: https://github.com/aperturerobotics/protobuf-project/tree/starpc
 
+This repository uses protowrap, see the [Makefile](./Makefile).
+
 ## Protobuf
 
 The following examples use the [echo](./echo/echo.proto) protobuf sample.
@@ -56,9 +56,9 @@ message EchoMsg {
 }
 ```
 
-## Go: Server & Client
+## Go
 
-A basic example can be found in the [e2e test]:
+This example demonstrates both the server and client:
 
 ```go
 // construct the server
@@ -96,39 +96,58 @@ if out.GetBody() != bodyTxt {
 
 See the ts-proto README to generate the TypeScript for your protobufs.
 
-Also check out the [integration](./integration/integration.ts) test.
+For an example of Go <-> TypeScript interop, see the [integration] test. For an
+example of TypeScript <-> TypeScript interop, see the [e2e] test.
 
-Supports any AsyncIterable communication channel with an included implementation
-for WebSockets.
+[e2e]: ./e2e/e2e.ts
+[integration]: ./integration/integration.ts
 
-This repository uses protowrap, see the [Makefile](./Makefile).
-
-`WebSocketConn` uses [js-libp2p-mplex] to multiplex streams over the WebSocket.
+Supports any AsyncIterable communication channel. `DuplexConn`,
+`MessagePortConn`, and `WebSocketConn` use [js-libp2p-mplex] to multiplex
+streams, but any multiplexer can be used.
 
 [js-libp2p-mplex]: https://github.com/libp2p/js-libp2p-mplex
 
-### Server
+This example demonstrates both the server and client:
 
 ```typescript
-import { WebSocketConn, Server, createMux } from '../srpc'
-import { EchoerClientImpl } from '../echo/echo'
+import { pipe } from 'it-pipe'
+import { createHandler, createMux, Server, Client, Conn } from 'srpc'
+import { EchoerDefinition, EchoerServer, runClientTest } from 'srpc/echo'
 
 const mux = createMux()
-mux.register(TODO)
+const echoer = new EchoerServer()
+mux.register(createHandler(EchoerDefinition, echoer))
 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.
+const clientConn = new Conn()
+const serverConn = new Conn(server)
+pipe(clientConn, serverConn, clientConn)
+const client = new Client(clientConn.buildOpenStreamFunc())
+
+console.log('Calling Echo: unary call...')
+let result = await demoServiceClient.Echo({
+  body: 'Hello world!',
+})
+console.log('success: output', result.body)
+
+const clientRequestStream = new Observable<EchoMsg>(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)
 ```
 
+## WebSocket
 
-### Client
+One way to integrate Go and TypeScript is over a WebSocket:
 
 ```typescript
-import { WebSocketConn } from '../srpc'
-import { EchoerClientImpl } from '../echo/echo'
+import { WebSocketConn } from 'srpc'
+import { EchoerClientImpl } from 'srpc/echo'
 
 const ws = new WebSocket('ws://localhost:5000/demo')
 const channel = new WebSocketConn(ws)
@@ -139,15 +158,6 @@ const result = await demoServiceClient.Echo({
   body: "Hello world!"
 })
 console.log('output', result.body)
-
-const clientRequestStream = new Observable<EchoMsg>(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)
 ```
 
 # Attribution

package/dist/echo/client-test.js

@@ -1,4 +1,4 @@
-import { EchoerClientImpl } from './echo.js';
+import { EchoerClientImpl } from './echo.pb.js';
 import { Observable } from 'rxjs';
 export async function runClientTest(client) {
     const demoServiceClient = new EchoerClientImpl(client);

package/dist/echo/{echo.js → echo.pb.js}

@@ -47,7 +47,6 @@ export const EchoMsg = {
     },
 };
 export class EchoerClientImpl {
-    rpc;
     constructor(rpc) {
         this.rpc = rpc;
         this.Echo = this.Echo.bind(this);

package/dist/echo/index.d.ts

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

package/dist/echo/index.js

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

package/dist/echo/server.d.ts

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

package/dist/srpc/broadcast-channel.js

@@ -2,14 +2,6 @@ import { EventIterator } from 'event-iterator';
 import { DuplexConn } from './conn-duplex.js';
 // BroadcastChannelIterable is a AsyncIterable wrapper for BroadcastChannel.
 export class BroadcastChannelIterable {
-    // readChannel is the incoming broadcast channel
-    readChannel;
-    // writeChannel is the outgoing broadcast channel
-    writeChannel;
-    // sink is the sink for incoming messages.
-    sink;
-    // source is the source for outgoing messages.
-    source;
     constructor(readChannel, writeChannel) {
         this.readChannel = readChannel;
         this.writeChannel = writeChannel;
@@ -52,8 +44,6 @@ export function newBroadcastChannelIterable(readName, writeName) {
 //
 // expects Uint8Array objects over the BroadcastChannel.
 export class BroadcastChannelConn extends DuplexConn {
-    // broadcastChannel is the broadcast channel iterable
-    broadcastChannel;
     constructor(readChannel, writeChannel, server, connParams) {
         const broadcastChannel = new BroadcastChannelIterable(readChannel, writeChannel);
         super(broadcastChannel, server, connParams);

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

@@ -1,4 +1,4 @@
-import type { CallStart } from './rpcproto.js';
+import type { CallStart } from './rpcproto.pb.js';
 import { CommonRPC } from './common-rpc.js';
 export declare class ClientRPC extends CommonRPC {
     constructor(service: string, method: string);

package/dist/srpc/client.d.ts

@@ -2,11 +2,11 @@ import { Observable } from 'rxjs';
 import type { TsProtoRpc } from './ts-proto-rpc.js';
 import type { OpenStreamFunc } from './stream.js';
 export declare class Client implements TsProtoRpc {
-    private openConnFn;
-    private _openConnFn?;
-    constructor(openConnFn?: OpenStreamFunc);
-    setOpenConnFn(openConnFn?: OpenStreamFunc): Promise<OpenStreamFunc>;
-    private initOpenConnFn;
+    private openStreamFn;
+    private _openStreamFn?;
+    constructor(openStreamFn?: OpenStreamFunc);
+    setOpenStreamFn(openStreamFn?: OpenStreamFunc): Promise<OpenStreamFunc>;
+    private initOpenStreamFn;
     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>;

package/dist/srpc/client.js

@@ -19,35 +19,31 @@ function writeClientStream(call, data) {
 }
 // Client implements the ts-proto Rpc interface with the drpcproto protocol.
 export class Client {
-    // openConnFn is a promise which contains the OpenStreamFunc.
-    openConnFn;
-    // _openConnFn resolves openConnFn.
-    _openConnFn;
-    constructor(openConnFn) {
-        this.openConnFn = this.setOpenConnFn(openConnFn);
+    constructor(openStreamFn) {
+        this.openStreamFn = this.setOpenStreamFn(openStreamFn);
     }
-    // setOpenConnFn updates the openConnFn for the Client.
-    setOpenConnFn(openConnFn) {
-        if (this._openConnFn) {
-            if (openConnFn) {
-                this._openConnFn(openConnFn);
-                this._openConnFn = undefined;
+    // setOpenStreamFn updates the openStreamFn for the Client.
+    setOpenStreamFn(openStreamFn) {
+        if (this._openStreamFn) {
+            if (openStreamFn) {
+                this._openStreamFn(openStreamFn);
+                this._openStreamFn = undefined;
             }
         }
         else {
-            if (openConnFn) {
-                this.openConnFn = Promise.resolve(openConnFn);
+            if (openStreamFn) {
+                this.openStreamFn = Promise.resolve(openStreamFn);
             }
             else {
-                this.initOpenConnFn();
+                this.initOpenStreamFn();
             }
         }
-        return this.openConnFn;
+        return this.openStreamFn;
     }
-    // initOpenConnFn creates the empty Promise for openConnFn.
-    initOpenConnFn() {
+    // initOpenStreamFn creates the empty Promise for openStreamFn.
+    initOpenStreamFn() {
         const openPromise = new Promise((resolve, reject) => {
-            this._openConnFn = (conn, err) => {
+            this._openStreamFn = (conn, err) => {
                 if (err) {
                     reject(err);
                 }
@@ -56,8 +52,8 @@ export class Client {
                 }
             };
         });
-        this.openConnFn = openPromise;
-        return this.openConnFn;
+        this.openStreamFn = openPromise;
+        return this.openStreamFn;
     }
     // request starts a non-streaming request.
     async request(service, method, data) {
@@ -84,7 +80,7 @@ export class Client {
     }
     // serverStreamingRequest starts a server-side streaming request.
     serverStreamingRequest(service, method, data) {
-        const pushServerData = pushable();
+        const pushServerData = pushable({ objectMode: true });
         const serverData = observableFrom(pushServerData);
         this.startRpc(service, method, data)
             .then(async (call) => {
@@ -103,7 +99,7 @@ export class Client {
     }
     // bidirectionalStreamingRequest starts a two-way streaming request.
     bidirectionalStreamingRequest(service, method, data) {
-        const pushServerData = pushable();
+        const pushServerData = pushable({ objectMode: true });
         const serverData = observableFrom(pushServerData);
         this.startRpc(service, method, null)
             .then(async (call) => {
@@ -135,8 +131,8 @@ export class Client {
     // throws any error starting the rpc call
     // if data == null and data.length == 0, sends a separate data packet.
     async startRpc(rpcService, rpcMethod, data) {
-        const openConnFn = await this.openConnFn;
-        const conn = await openConnFn();
+        const openStreamFn = await this.openStreamFn;
+        const conn = await openStreamFn();
         const call = new ClientRPC(rpcService, rpcMethod);
         pipe(conn, parseLengthPrefixTransform(), decodePacketSource, call, encodePacketSource, prependLengthPrefixTransform(), conn);
         await call.writeCallStart(data || undefined);

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

@@ -1,6 +1,6 @@
 import type { Source, Sink } from 'it-stream-types';
-import type { CallData, CallStart } from './rpcproto.js';
-import { Packet } from './rpcproto.js';
+import type { CallData, CallStart } from './rpcproto.pb.js';
+import { Packet } from './rpcproto.pb.js';
 export declare class CommonRPC {
     sink: Sink<Packet>;
     source: AsyncIterable<Packet>;

package/dist/srpc/common-rpc.js

@@ -1,21 +1,7 @@
 import { pushable } from 'it-pushable';
-import { Packet } from './rpcproto.js';
+import { Packet } from './rpcproto.pb.js';
 // CommonRPC is common logic between server and client RPCs.
 export class CommonRPC {
-    // 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;
-    // rpcDataSource emits incoming client RPC messages to the caller.
-    rpcDataSource;
-    // _rpcDataSource is used to write to the rpc message source.
-    _rpcDataSource;
-    // service is the rpc service
-    service;
-    // method is the rpc method
-    method;
     constructor() {
         this.sink = this._createSink();
         const sourcev = this._createSource();

package/dist/srpc/conn-duplex.js

@@ -4,12 +4,10 @@ import { Conn } from './conn.js';
 //
 // expects Uint8Array objects
 export class DuplexConn extends Conn {
-    // channel is the iterable
-    channel;
     constructor(duplex, server, connParams) {
         super(server, connParams);
         this.channel = duplex;
-        pipe(this, this.channel, this);
+        pipe(this.channel, this, this.channel);
     }
     // getChannelDuplex returns the Duplex channel.
     getChannelDuplex() {

package/dist/srpc/conn.js

@@ -5,10 +5,6 @@ import { Client } from './client.js';
 // Implements the server by handling incoming streams.
 // If the server is unset, rejects any incoming streams.
 export class Conn {
-    // muxer is the mplex stream muxer.
-    muxer;
-    // server is the server side, if set.
-    server;
     constructor(server, connParams) {
         if (server) {
             this.server = server;

package/dist/srpc/handler.js

@@ -4,10 +4,6 @@ import { from as observableFrom } from 'rxjs';
 import { buildDecodeMessageTransform, buildEncodeMessageTransform, } from './message.js';
 // StaticHandler is a handler with a definition and implementation.
 export class StaticHandler {
-    // service is the service id
-    service;
-    // methods is the map of method to invoke fn
-    methods;
     constructor(serviceID, methods) {
         this.service = serviceID;
         this.methods = methods;
@@ -38,23 +34,27 @@ export function createInvokeFn(methodInfo, methodProto) {
             objectMode: true,
         });
         // pipe responseSink to dataSink.
-        const responsePipe = pipe(responseSink, buildEncodeMessageTransform(methodInfo.responseType), dataSink);
+        pipe(responseSink, buildEncodeMessageTransform(methodInfo.responseType), dataSink);
+        // requestSource is a Source of decoded request messages.
+        const requestSource = pipe(dataSource, requestDecode);
         // build the request argument.
         let requestArg;
         if (methodInfo.requestStream) {
-            // requestSource is a Source of decoded request messages.
-            const requestSource = pipe(dataSource, requestDecode);
             // convert the request data source into an Observable<T>
             requestArg = observableFrom(requestSource);
         }
         else {
             // receive a single message for the argument.
-            const requestRx = requestDecode(dataSource);
-            for await (const msg of requestRx) {
-                requestArg = msg;
-                break;
+            for await (const msg of requestSource) {
+                if (msg) {
+                    requestArg = msg;
+                    break;
+                }
             }
         }
+        if (!requestArg) {
+            throw new Error('request object was empty');
+        }
         // Call the implementation.
         try {
             const responseObj = methodProto(requestArg);
@@ -77,9 +77,7 @@ export function createInvokeFn(methodInfo, methodProto) {
                         },
                         complete: () => {
                             responseSink.end();
-                            responsePipe.finally(() => {
-                                resolve();
-                            });
+                            resolve();
                         },
                     });
                 });

package/dist/srpc/index.d.ts

@@ -1,4 +1,4 @@
-export type { OpenStreamFunc } from './stream.js';
+export type { PacketHandler, Stream, OpenStreamFunc } from './stream.js';
 export { Client } from './client.js';
 export { Server } from './server.js';
 export { Conn, ConnParams } from './conn.js';

package/dist/srpc/message-port.js

@@ -2,14 +2,6 @@ import { EventIterator } from 'event-iterator';
 import { DuplexConn } from './conn-duplex.js';
 // MessagePortIterable is a AsyncIterable wrapper for MessagePort.
 export class MessagePortIterable {
-    // port is the message port
-    port;
-    // sink is the sink for incoming messages.
-    sink;
-    // source is the source for outgoing messages.
-    source;
-    // _source is the EventIterator for source.
-    _source;
     constructor(port) {
         this.port = port;
         this.sink = this._createSink();
@@ -51,8 +43,6 @@ export function newMessagePortIterable(port) {
 //
 // expects Uint8Array objects over the MessagePort.
 export class MessagePortConn extends DuplexConn {
-    // messagePort is the message port iterable.
-    messagePort;
     constructor(port, server, connParams) {
         const messagePort = new MessagePortIterable(port);
         super(messagePort, server, connParams);

package/dist/srpc/mux.js

@@ -5,8 +5,10 @@ export function createMux() {
 // 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 = {};
+    constructor() {
+        // services contains a mapping from service id to handlers.
+        this.services = {};
+    }
     register(handler) {
         const serviceID = handler?.getServiceID();
         if (!serviceID) {

package/dist/srpc/packet.d.ts

@@ -1,5 +1,5 @@
 import type { Transform } from 'it-stream-types';
-import { Packet } from './rpcproto.js';
+import { Packet } from './rpcproto.pb.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>;

package/dist/srpc/packet.js

@@ -1,5 +1,5 @@
 import { encode as lengthPrefixEncode, decode as lengthPrefixDecode, } from 'it-length-prefixed';
-import { Packet } from './rpcproto.js';
+import { Packet } from './rpcproto.pb.js';
 import { buildDecodeMessageTransform, buildEncodeMessageTransform, } from './message.js';
 // decodePacketSource decodes packets from a binary data stream.
 export const decodePacketSource = buildDecodeMessageTransform(Packet);

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

@@ -1,4 +1,4 @@
-import type { CallData, CallStart } from './rpcproto.js';
+import type { CallData, CallStart } from './rpcproto.pb.js';
 import { CommonRPC } from './common-rpc.js';
 import { Mux } from './mux.js';
 export declare class ServerRPC extends CommonRPC {

package/dist/srpc/server-rpc.js

@@ -1,8 +1,6 @@
 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;

package/dist/srpc/server.d.ts

@@ -2,7 +2,7 @@ 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 { Packet } from './rpcproto.pb.js';
 import { StreamHandler } from './conn.js';
 export declare class Server implements StreamHandler {
     private mux;

package/dist/srpc/server.js

@@ -3,8 +3,6 @@ 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;
     }

package/dist/srpc/stream.d.ts

@@ -1,4 +1,4 @@
-import type { Packet } from './rpcproto';
+import type { Packet } from './rpcproto.pb.js';
 import type { Duplex } from 'it-stream-types';
 export declare type PacketHandler = (packet: Packet) => Promise<void>;
 export declare type Stream = Duplex<Uint8Array>;

package/dist/srpc/websocket.js

@@ -4,15 +4,13 @@ import { Mplex } from '@libp2p/mplex';
 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, server) {
         super(server, {
             muxerFactory: new Mplex(),
         });
         this.socket = socket;
         const socketDuplex = duplex(socket);
-        pipe(this.source, socketDuplex, this.sink);
+        pipe(socketDuplex, this, socketDuplex);
     }
     // getSocket returns the websocket.
     getSocket() {

package/e2e/e2e_test.go

@@ -3,10 +3,13 @@ package e2e
 import (
 	"context"
 	"io"
+	"net"
 	"testing"
 
 	"github.com/aperturerobotics/starpc/echo"
 	"github.com/aperturerobotics/starpc/srpc"
+	"github.com/libp2p/go-libp2p/p2p/muxer/mplex"
+	mp "github.com/libp2p/go-mplex"
 	"github.com/pkg/errors"
 )
 
@@ -20,9 +23,24 @@ func RunE2E(t *testing.T, cb func(client echo.SRPCEchoerClient) error) {
 	}
 	server := srpc.NewServer(mux)
 
+	// note: also possible to do without mplex:
+	// openStream := srpc.NewServerPipe(server)
+	// client := srpc.NewClient(openStream)
+
 	// construct the client
-	openStream := srpc.NewServerPipe(server)
-	client := srpc.NewClient(openStream)
+	clientPipe, serverPipe := net.Pipe()
+
+	ctx := context.Background()
+	go func() {
+		serverMp, _ := mp.NewMultiplex(serverPipe, false, nil)
+		_ = server.AcceptMuxedConn(ctx, mplex.NewMuxedConn(serverMp))
+	}()
+
+	clientMp, err := mp.NewMultiplex(clientPipe, true, nil)
+	if err != nil {
+		t.Fatal(err.Error())
+	}
+	client := srpc.NewClientWithMuxedConn(mplex.NewMuxedConn(clientMp))
 
 	// construct the client rpc interface
 	clientEcho := echo.NewSRPCEchoerClient(client)

package/echo/client-test.ts

@@ -1,5 +1,5 @@
 import { Client } from '../srpc/index.js'
-import { EchoerClientImpl, EchoMsg } from './echo.js'
+import { EchoerClientImpl, EchoMsg } from './echo.pb.js'
 import { Observable } from 'rxjs'
 
 export async function runClientTest(client: Client) {

package/echo/index.ts

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

package/echo/server.ts

@@ -1,5 +1,5 @@
 import { Observable, from as observableFrom } from 'rxjs'
-import { Echoer, EchoMsg } from './echo'
+import { Echoer, EchoMsg } from './echo.pb.js'
 import { pushable, Pushable } from 'it-pushable'
 
 // EchoServer implements the Echoer server.