starpc 0.3.2 → 0.3.5

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/srpc/client.d.ts

@@ -3,8 +3,10 @@ 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);
-    setOpenConnFn(openConnFn: OpenStreamFunc): void;
+    private _openConnFn?;
+    constructor(openConnFn?: OpenStreamFunc);
+    setOpenConnFn(openConnFn?: OpenStreamFunc): Promise<OpenStreamFunc>;
+    private initOpenConnFn;
     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,15 +19,45 @@ function writeClientStream(call, data) {
 }
 // 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 is a promise which contains the OpenStreamFunc.
     openConnFn;
+    // _openConnFn resolves openConnFn.
+    _openConnFn;
     constructor(openConnFn) {
-        this.openConnFn = openConnFn;
+        this.openConnFn = this.setOpenConnFn(openConnFn);
     }
     // setOpenConnFn updates the openConnFn for the Client.
     setOpenConnFn(openConnFn) {
-        this.openConnFn = openConnFn;
+        if (this._openConnFn) {
+            if (openConnFn) {
+                this._openConnFn(openConnFn);
+                this._openConnFn = undefined;
+            }
+        }
+        else {
+            if (openConnFn) {
+                this.openConnFn = Promise.resolve(openConnFn);
+            }
+            else {
+                this.initOpenConnFn();
+            }
+        }
+        return this.openConnFn;
+    }
+    // initOpenConnFn creates the empty Promise for openConnFn.
+    initOpenConnFn() {
+        const openPromise = new Promise((resolve, reject) => {
+            this._openConnFn = (conn, err) => {
+                if (err) {
+                    reject(err);
+                }
+                else if (conn) {
+                    resolve(conn);
+                }
+            };
+        });
+        this.openConnFn = openPromise;
+        return this.openConnFn;
     }
     // request starts a non-streaming request.
     async request(service, method, data) {
@@ -105,7 +135,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 conn = await this.openConnFn();
+        const openConnFn = await this.openConnFn;
+        const conn = await openConnFn();
         const call = new ClientRPC(rpcService, rpcMethod);
         pipe(conn, parseLengthPrefixTransform(), decodePacketSource, call, encodePacketSource, prependLengthPrefixTransform(), conn);
         await call.writeCallStart(data || undefined);

package/dist/srpc/index.d.ts

@@ -4,6 +4,5 @@ export { Server } from './server.js';
 export { Conn, ConnParams } from './conn.js';
 export { Handler, InvokeFn, createHandler, createInvokeFn } from './handler.js';
 export { Mux, createMux } from './mux.js';
-export { WebSocketConn } from './websocket.js';
 export { BroadcastChannelIterable, newBroadcastChannelIterable, BroadcastChannelConn, } from './broadcast-channel.js';
 export { MessagePortIterable, newMessagePortIterable, MessagePortConn, } from './message-port.js';

package/dist/srpc/index.js

@@ -3,6 +3,5 @@ export { Server } from './server.js';
 export { Conn } from './conn.js';
 export { createHandler, createInvokeFn } from './handler.js';
 export { createMux } from './mux.js';
-export { WebSocketConn } from './websocket.js';
 export { BroadcastChannelIterable, newBroadcastChannelIterable, BroadcastChannelConn, } from './broadcast-channel.js';
 export { MessagePortIterable, newMessagePortIterable, MessagePortConn, } from './message-port.js';

package/integration/integration.bash

@@ -1,6 +1,9 @@
 #!/bin/bash
 set -eo pipefail
 
+unset GOOS
+unset GOARCH
+
 echo "Compiling ts..."
 # ../node_modules/.bin/tsc --out integration.js --project tsconfig.json
 ../node_modules/.bin/esbuild integration.ts --bundle --platform=node --outfile=integration.js

package/integration/integration.ts

@@ -1,4 +1,4 @@
-import { WebSocketConn } from '../srpc'
+import { WebSocketConn } from '../srpc/websocket'
 import { runClientTest } from '../echo'
 import WebSocket from 'isomorphic-ws'
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starpc",
-  "version": "0.3.2",
+  "version": "0.3.5",
   "description": "Streaming protobuf RPC service protocol over any two-way channel.",
   "license": "MIT",
   "author": {

package/srpc/client.ts

@@ -29,17 +29,45 @@ function writeClientStream(call: ClientRPC, data: Observable<Uint8Array>) {
 
 // Client implements the ts-proto Rpc interface with the drpcproto protocol.
 export class Client implements TsProtoRpc {
-  // openConnFn is the open connection function.
-  // called when starting RPC.
-  private openConnFn: OpenStreamFunc
+  // openConnFn is a promise which contains the OpenStreamFunc.
+  private openConnFn: Promise<OpenStreamFunc>
+  // _openConnFn resolves openConnFn.
+  private _openConnFn?: (conn?: OpenStreamFunc, err?: Error) => void
 
-  constructor(openConnFn: OpenStreamFunc) {
-    this.openConnFn = openConnFn
+  constructor(openConnFn?: OpenStreamFunc) {
+    this.openConnFn = this.setOpenConnFn(openConnFn)
   }
 
   // setOpenConnFn updates the openConnFn for the Client.
-  public setOpenConnFn(openConnFn: OpenStreamFunc) {
-    this.openConnFn = openConnFn
+  public setOpenConnFn(openConnFn?: OpenStreamFunc): Promise<OpenStreamFunc> {
+    if (this._openConnFn) {
+      if (openConnFn) {
+        this._openConnFn(openConnFn)
+        this._openConnFn = undefined
+      }
+    } else {
+      if (openConnFn) {
+        this.openConnFn = Promise.resolve(openConnFn)
+      } else {
+        this.initOpenConnFn()
+      }
+    }
+    return this.openConnFn
+  }
+
+  // initOpenConnFn creates the empty Promise for openConnFn.
+  private initOpenConnFn(): Promise<OpenStreamFunc> {
+    const openPromise = new Promise<OpenStreamFunc>((resolve, reject) => {
+      this._openConnFn = (conn?: OpenStreamFunc, err?: Error) => {
+        if (err) {
+          reject(err)
+        } else if (conn) {
+          resolve(conn)
+        }
+      }
+    })
+    this.openConnFn = openPromise
+    return this.openConnFn
   }
 
   // request starts a non-streaming request.
@@ -140,7 +168,8 @@ export class Client implements TsProtoRpc {
     rpcMethod: string,
     data: Uint8Array | null
   ): Promise<ClientRPC> {
-    const conn = await this.openConnFn()
+    const openConnFn = await this.openConnFn
+    const conn = await openConnFn()
     const call = new ClientRPC(rpcService, rpcMethod)
     pipe(
       conn,

package/srpc/index.ts

@@ -4,7 +4,6 @@ export { Server } from './server.js'
 export { Conn, ConnParams } from './conn.js'
 export { Handler, InvokeFn, createHandler, createInvokeFn } from './handler.js'
 export { Mux, createMux } from './mux.js'
-export { WebSocketConn } from './websocket.js'
 export {
   BroadcastChannelIterable,
   newBroadcastChannelIterable,

package/srpc/server-http.go

@@ -57,7 +57,7 @@ func (s *HTTPServer) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 			return
 		}
 		go func() {
-			err := s.srpc.HandleConn(ctx, strm)
+			err := s.srpc.HandleStream(ctx, strm)
 			_ = err
 			// TODO: handle / log error?
 			// err != nil && err != io.EOF && err != context.Canceled

package/srpc/server-pipe.go

@@ -7,12 +7,12 @@ import (
 
 // NewServerPipe constructs a open stream func which creates an in-memory Pipe
 // Stream with the given Server. Starts read pumps for both. Starts the
-// HandleConn function on the server in a separate goroutine.
+// HandleStream function on the server in a separate goroutine.
 func NewServerPipe(server *Server) OpenStreamFunc {
 	return func(ctx context.Context, msgHandler func(pkt *Packet) error) (Writer, error) {
 		srvPipe, clientPipe := net.Pipe()
 		go func() {
-			_ = server.HandleConn(ctx, srvPipe)
+			_ = server.HandleStream(ctx, srvPipe)
 		}()
 		clientPrw := NewPacketReadWriter(clientPipe, msgHandler)
 		go func() {

package/srpc/server.go

@@ -3,6 +3,8 @@ package srpc
 import (
 	"context"
 	"io"
+
+	"github.com/libp2p/go-libp2p-core/network"
 )
 
 // Server handles incoming RPC streams with a mux.
@@ -18,8 +20,8 @@ func NewServer(mux Mux) *Server {
 	}
 }
 
-// HandleConn handles an incoming ReadWriteCloser.
-func (s *Server) HandleConn(ctx context.Context, rwc io.ReadWriteCloser) error {
+// HandleStream handles an incoming ReadWriteCloser stream.
+func (s *Server) HandleStream(ctx context.Context, rwc io.ReadWriteCloser) error {
 	subCtx, subCtxCancel := context.WithCancel(ctx)
 	defer subCtxCancel()
 	serverRPC := NewServerRPC(subCtx, s.mux)
@@ -27,3 +29,28 @@ func (s *Server) HandleConn(ctx context.Context, rwc io.ReadWriteCloser) error {
 	serverRPC.SetWriter(prw)
 	return prw.ReadPump()
 }
+
+// AcceptMuxedConn runs a loop which calls Accept on a muxer to handle streams.
+//
+// Starts HandleStream in a separate goroutine to handle the stream.
+// Returns context.Canceled or io.EOF when the loop is complete / closed.
+func (s *Server) AcceptMuxedConn(ctx context.Context, mplex network.MuxedConn) error {
+	for {
+		select {
+		case <-ctx.Done():
+			return context.Canceled
+		default:
+			if mplex.IsClosed() {
+				return io.EOF
+			}
+		}
+
+		muxedStream, err := mplex.AcceptStream()
+		if err != nil {
+			return err
+		}
+		go func() {
+			_ = s.HandleStream(ctx, muxedStream)
+		}()
+	}
+}