starpc 0.25.0 → 0.25.1

package/dist/e2e/e2e.js

@@ -1,5 +1,5 @@
 import { pipe } from 'it-pipe';
-import { createHandler, createMux, Server, Client, StreamConn } from '../srpc';
+import { createHandler, createMux, Server, Client, StreamConn, ChannelStream, combineUint8ArrayListTransform } from '../srpc';
 import { EchoerDefinition, EchoerServer, runClientTest } from '../echo';
 import { runAbortControllerTest, runRpcStreamTest } from '../echo/client-test';
 async function runRPC() {
@@ -7,13 +7,31 @@ async function runRPC() {
     const server = new Server(mux.lookupMethodFunc);
     const echoer = new EchoerServer(server);
     mux.register(createHandler(EchoerDefinition, echoer));
+    // StreamConn is unnecessary since ChannelStream has packet framing.
+    // Use it here to include yamux in this e2e test.
     const clientConn = new StreamConn();
     const serverConn = new StreamConn(server, { direction: 'inbound' });
-    pipe(clientConn, serverConn, clientConn);
+    // pipe clientConn -> messageStream -> serverConn -> messageStream -> clientConn
+    const { port1: clientPort, port2: serverPort } = new MessageChannel();
+    const clientChannelStream = new ChannelStream('client', clientPort);
+    const serverChannelStream = new ChannelStream('server', serverPort);
+    // Pipe the client traffic via the client end of the MessageChannel.
+    pipe(clientChannelStream, clientConn, combineUint8ArrayListTransform(), clientChannelStream)
+        .catch((err) => clientConn.close(err))
+        .then(() => clientConn.close());
+    // Pipe the server traffic via the server end of the MessageChannel.
+    pipe(serverChannelStream, serverConn, combineUint8ArrayListTransform(), serverChannelStream)
+        .catch((err) => serverConn.close(err))
+        .then(() => serverConn.close());
+    // Build the client
     const client = new Client(clientConn.buildOpenStreamFunc());
+    // Run the tests
     await runClientTest(client);
     await runAbortControllerTest(client);
     await runRpcStreamTest(client);
+    // Close cleanly
+    clientConn.close();
+    serverConn.close();
 }
 runRPC()
     .then(() => {

package/dist/srpc/channel.d.ts

@@ -1,9 +1,10 @@
 import type { Sink, Source, Duplex } from 'it-stream-types';
 export interface ChannelStreamMessage<T> {
     from: string;
-    ack?: boolean;
-    opened?: boolean;
-    closed?: boolean;
+    ack?: true;
+    opened?: true;
+    alive?: true;
+    closed?: true;
     error?: Error;
     data?: T;
 }
@@ -11,7 +12,10 @@ export type ChannelPort = MessagePort | {
     tx: BroadcastChannel;
     rx: BroadcastChannel;
 };
-export declare class ChannelStream<T> implements Duplex<AsyncGenerator<T>, Source<T>, Promise<void>> {
+export interface ChannelStreamOpts {
+    remoteOpen?: boolean;
+}
+export declare class ChannelStream<T = Uint8Array> implements Duplex<AsyncGenerator<T>, Source<T>, Promise<void>> {
     readonly channel: ChannelPort;
     sink: Sink<Source<T>, Promise<void>>;
     source: AsyncGenerator<T>;
@@ -26,7 +30,7 @@ export declare class ChannelStream<T> implements Duplex<AsyncGenerator<T>, Sourc
     private _remoteAck?;
     get isAcked(): boolean;
     get isOpen(): boolean;
-    constructor(localId: string, channel: ChannelPort, remoteOpen: boolean);
+    constructor(localId: string, channel: ChannelPort, opts?: ChannelStreamOpts);
     private postMessage;
     close(error?: Error): void;
     private onLocalOpened;
@@ -35,4 +39,4 @@ export declare class ChannelStream<T> implements Duplex<AsyncGenerator<T>, Sourc
     private _createSink;
     private onMessage;
 }
-export declare function newBroadcastChannelStream<T>(id: string, readName: string, writeName: string, remoteOpen: boolean): ChannelStream<T>;
+export declare function newBroadcastChannelStream<T>(id: string, readName: string, writeName: string, opts?: ChannelStreamOpts): ChannelStream<T>;

package/dist/srpc/channel.js

@@ -7,21 +7,21 @@ import { pushable } from 'it-pushable';
 export class ChannelStream {
     // isAcked checks if the stream is acknowledged by the remote.
     get isAcked() {
-        return this.remoteAck || false;
+        return this.remoteAck ?? false;
     }
     // isOpen checks if the stream is opened by the remote.
     get isOpen() {
-        return this.remoteOpen || false;
+        return this.remoteOpen ?? false;
     }
-    // remoteOpen indicates if we know the remote has already opened the stream.
-    constructor(localId, channel, remoteOpen) {
+    // remoteOpen indicates that we know the remote has already opened the stream.
+    constructor(localId, channel, opts) {
         this.localId = localId;
         this.channel = channel;
         this.sink = this._createSink();
         this.localOpen = false;
-        this.remoteAck = remoteOpen;
-        this.remoteOpen = remoteOpen;
-        if (remoteOpen) {
+        this.remoteOpen = opts?.remoteOpen ?? false;
+        this.remoteAck = this.remoteOpen;
+        if (this.remoteOpen) {
             this.waitRemoteOpen = Promise.resolve();
             this.waitRemoteAck = Promise.resolve();
         }
@@ -159,6 +159,6 @@ export class ChannelStream {
     }
 }
 // newBroadcastChannelStream constructs a ChannelStream with a channel name.
-export function newBroadcastChannelStream(id, readName, writeName, remoteOpen) {
-    return new ChannelStream(id, { tx: new BroadcastChannel(writeName), rx: new BroadcastChannel(readName) }, remoteOpen);
+export function newBroadcastChannelStream(id, readName, writeName, opts) {
+    return new ChannelStream(id, { tx: new BroadcastChannel(writeName), rx: new BroadcastChannel(readName) }, opts);
 }

package/e2e/e2e.ts

@@ -1,5 +1,5 @@
 import { pipe } from 'it-pipe'
-import { createHandler, createMux, Server, Client, StreamConn } from '../srpc'
+import { createHandler, createMux, Server, Client, StreamConn, ChannelStream, combineUint8ArrayListTransform } from '../srpc'
 import { EchoerDefinition, EchoerServer, runClientTest } from '../echo'
 import { runAbortControllerTest, runRpcStreamTest } from '../echo/client-test'
 
@@ -9,16 +9,37 @@ async function runRPC() {
   const echoer = new EchoerServer(server)
   mux.register(createHandler(EchoerDefinition, echoer))
 
+  // StreamConn is unnecessary since ChannelStream has packet framing.
+  // Use it here to include yamux in this e2e test.
   const clientConn = new StreamConn()
   const serverConn = new StreamConn(server, { direction: 'inbound' })
 
-  pipe(clientConn, serverConn, clientConn)
+  // pipe clientConn -> messageStream -> serverConn -> messageStream -> clientConn
+  const {port1: clientPort, port2: serverPort} = new MessageChannel()
+  const clientChannelStream = new ChannelStream('client', clientPort)
+  const serverChannelStream = new ChannelStream('server', serverPort)
 
+  // Pipe the client traffic via the client end of the MessageChannel.
+  pipe(clientChannelStream, clientConn, combineUint8ArrayListTransform(), clientChannelStream)
+    .catch((err: Error) => clientConn.close(err))
+    .then(() => clientConn.close())
+
+  // Pipe the server traffic via the server end of the MessageChannel.
+  pipe(serverChannelStream, serverConn, combineUint8ArrayListTransform(), serverChannelStream)
+    .catch((err: Error) => serverConn.close(err))
+    .then(() => serverConn.close())
+
+  // Build the client
   const client = new Client(clientConn.buildOpenStreamFunc())
 
+  // Run the tests
   await runClientTest(client)
   await runAbortControllerTest(client)
   await runRpcStreamTest(client)
+
+  // Close cleanly
+  clientConn.close()
+  serverConn.close()
 }
 
 runRPC()

package/package.json

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

package/srpc/channel.ts

@@ -5,27 +5,39 @@ import { pushable, Pushable } from 'it-pushable'
 export interface ChannelStreamMessage<T> {
   // from indicates who sent the message.
   from: string
-  // ack indicates a remote joined the stream.
-  ack?: boolean
+  // ack indicates a remote acked establishing the stream.
+  ack?: true
   // opened indicates the remote has opened the stream.
-  opened?: boolean
+  opened?: true
+  // alive indicates this is a keep-alive packet.
+  // not set unless keep-alives are enabled.
+  alive?: true
   // closed indicates the stream is closed.
-  closed?: boolean
+  closed?: true
   // error indicates the stream has an error.
   error?: Error
   // data is any message data.
   data?: T
 }
 
-// Channel represents a channel we can open a stream over.
-export type ChannelPort = MessagePort | { tx: BroadcastChannel; rx: BroadcastChannel }
+// ChannelPort represents a channel we can open a stream over.
+export type ChannelPort =
+  | MessagePort
+  | { tx: BroadcastChannel; rx: BroadcastChannel }
+
+// ChannelStreamOpts are options for ChannelStream.
+export interface ChannelStreamOpts {
+  // remoteOpen indicates that the remote already knows the channel is open.
+  // this skips sending and waiting for the open+ack messages.
+  remoteOpen?: boolean
+}
 
 // ChannelStream implements a Stream over a BroadcastChannel duplex or MessagePort.
 //
 // NOTE: there is no way to tell if a BroadcastChannel or MessagePort is closed.
 // This implementation sends a "closed" message when close() is called.
 // However: if the remote is removed w/o closing cleanly, the stream will be left open!
-export class ChannelStream<T>
+export class ChannelStream<T = Uint8Array>
   implements Duplex<AsyncGenerator<T>, Source<T>, Promise<void>>
 {
   // channel is the read/write channel.
@@ -58,24 +70,24 @@ export class ChannelStream<T>
 
   // isAcked checks if the stream is acknowledged by the remote.
   public get isAcked() {
-    return this.remoteAck || false
+    return this.remoteAck ?? false
   }
 
   // isOpen checks if the stream is opened by the remote.
   public get isOpen() {
-    return this.remoteOpen || false
+    return this.remoteOpen ?? false
   }
 
-  // remoteOpen indicates if we know the remote has already opened the stream.
-  constructor(localId: string, channel: ChannelPort, remoteOpen: boolean) {
+  // remoteOpen indicates that we know the remote has already opened the stream.
+  constructor(localId: string, channel: ChannelPort, opts?: ChannelStreamOpts) {
     this.localId = localId
     this.channel = channel
     this.sink = this._createSink()
 
     this.localOpen = false
-    this.remoteAck = remoteOpen
-    this.remoteOpen = remoteOpen
-    if (remoteOpen) {
+    this.remoteOpen = opts?.remoteOpen ?? false
+    this.remoteAck = this.remoteOpen
+    if (this.remoteOpen) {
       this.waitRemoteOpen = Promise.resolve()
       this.waitRemoteAck = Promise.resolve()
     } else {
@@ -220,11 +232,11 @@ export function newBroadcastChannelStream<T>(
   id: string,
   readName: string,
   writeName: string,
-  remoteOpen: boolean,
+  opts?: ChannelStreamOpts,
 ): ChannelStream<T> {
   return new ChannelStream<T>(
     id,
     { tx: new BroadcastChannel(writeName), rx: new BroadcastChannel(readName) },
-    remoteOpen,
+    opts,
   )
 }