starpc 0.24.0 → 0.25.0

package/dist/srpc/channel.d.ts

@@ -0,0 +1,38 @@
+import type { Sink, Source, Duplex } from 'it-stream-types';
+export interface ChannelStreamMessage<T> {
+    from: string;
+    ack?: boolean;
+    opened?: boolean;
+    closed?: boolean;
+    error?: Error;
+    data?: T;
+}
+export type ChannelPort = MessagePort | {
+    tx: BroadcastChannel;
+    rx: BroadcastChannel;
+};
+export declare class ChannelStream<T> implements Duplex<AsyncGenerator<T>, Source<T>, Promise<void>> {
+    readonly channel: ChannelPort;
+    sink: Sink<Source<T>, Promise<void>>;
+    source: AsyncGenerator<T>;
+    private readonly _source;
+    private readonly localId;
+    private localOpen;
+    private remoteOpen;
+    readonly waitRemoteOpen: Promise<void>;
+    private _remoteOpen?;
+    private remoteAck;
+    readonly waitRemoteAck: Promise<void>;
+    private _remoteAck?;
+    get isAcked(): boolean;
+    get isOpen(): boolean;
+    constructor(localId: string, channel: ChannelPort, remoteOpen: boolean);
+    private postMessage;
+    close(error?: Error): void;
+    private onLocalOpened;
+    private onRemoteAcked;
+    private onRemoteOpened;
+    private _createSink;
+    private onMessage;
+}
+export declare function newBroadcastChannelStream<T>(id: string, readName: string, writeName: string, remoteOpen: boolean): ChannelStream<T>;

package/dist/srpc/channel.js

@@ -0,0 +1,164 @@
+import { pushable } from 'it-pushable';
+// 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 {
+    // isAcked checks if the stream is acknowledged by the remote.
+    get isAcked() {
+        return this.remoteAck || false;
+    }
+    // isOpen checks if the stream is opened by the remote.
+    get isOpen() {
+        return this.remoteOpen || false;
+    }
+    // remoteOpen indicates if we know the remote has already opened the stream.
+    constructor(localId, channel, remoteOpen) {
+        this.localId = localId;
+        this.channel = channel;
+        this.sink = this._createSink();
+        this.localOpen = false;
+        this.remoteAck = remoteOpen;
+        this.remoteOpen = remoteOpen;
+        if (remoteOpen) {
+            this.waitRemoteOpen = Promise.resolve();
+            this.waitRemoteAck = Promise.resolve();
+        }
+        else {
+            this.waitRemoteOpen = new Promise((resolve, reject) => {
+                this._remoteOpen = (err) => {
+                    if (err) {
+                        reject(err);
+                    }
+                    else {
+                        resolve();
+                    }
+                };
+            });
+            this.waitRemoteOpen.catch(() => { });
+            this.waitRemoteAck = new Promise((resolve, reject) => {
+                this._remoteAck = (err) => {
+                    if (err) {
+                        reject(err);
+                    }
+                    else {
+                        resolve();
+                    }
+                };
+            });
+            this.waitRemoteAck.catch(() => { });
+        }
+        const source = pushable({ objectMode: true });
+        this.source = source;
+        this._source = source;
+        const onMessage = this.onMessage.bind(this);
+        if (channel instanceof MessagePort) {
+            // MessagePort
+            channel.onmessage = onMessage;
+            channel.start();
+        }
+        else {
+            // BroadcastChannel
+            channel.rx.onmessage = onMessage;
+        }
+        this.postMessage({ ack: true });
+    }
+    // postMessage writes a message to the stream.
+    postMessage(msg) {
+        msg.from = this.localId;
+        if (this.channel instanceof MessagePort) {
+            this.channel.postMessage(msg);
+        }
+        else {
+            this.channel.tx.postMessage(msg);
+        }
+    }
+    // close closes the broadcast channels.
+    close(error) {
+        // write a message to indicate the stream is now closed.
+        this.postMessage({ closed: true, error });
+        // close channels
+        if (this.channel instanceof MessagePort) {
+            this.channel.close();
+        }
+        else {
+            this.channel.tx.close();
+            this.channel.rx.close();
+        }
+        if (!this.remoteOpen && this._remoteOpen) {
+            this._remoteOpen(error || new Error('closed'));
+        }
+        if (!this.remoteAck && this._remoteAck) {
+            this._remoteAck(error || new Error('closed'));
+        }
+    }
+    // onLocalOpened indicates the local side has opened the read stream.
+    onLocalOpened() {
+        if (!this.localOpen) {
+            this.localOpen = true;
+            this.postMessage({ opened: true });
+        }
+    }
+    // onRemoteAcked indicates the remote side has acked the stream.
+    onRemoteAcked() {
+        if (!this.remoteAck) {
+            this.remoteAck = true;
+            if (this._remoteAck) {
+                this._remoteAck();
+            }
+        }
+    }
+    // onRemoteOpened indicates the remote side has opened the read stream.
+    onRemoteOpened() {
+        if (!this.remoteOpen) {
+            this.remoteOpen = true;
+            if (this._remoteOpen) {
+                this._remoteOpen();
+            }
+        }
+    }
+    _createSink() {
+        return async (source) => {
+            // make sure the remote is open before we send any data.
+            await this.waitRemoteAck;
+            this.onLocalOpened();
+            await this.waitRemoteOpen;
+            try {
+                for await (const msg of source) {
+                    this.postMessage({ data: msg });
+                }
+                this.postMessage({ closed: true });
+            }
+            catch (error) {
+                this.postMessage({ closed: true, error: error });
+            }
+        };
+    }
+    onMessage(ev) {
+        const msg = ev.data;
+        if (!msg || msg.from === this.localId || !msg.from) {
+            return;
+        }
+        if (msg.ack || msg.opened) {
+            this.onRemoteAcked();
+        }
+        if (msg.opened) {
+            this.onRemoteOpened();
+        }
+        const { data, closed, error: err } = msg;
+        if (data) {
+            this._source.push(data);
+        }
+        if (err) {
+            this._source.end(err);
+        }
+        else if (closed) {
+            this._source.end();
+        }
+    }
+}
+// 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);
+}

package/dist/srpc/index.d.ts

@@ -8,6 +8,7 @@ export { Handler, InvokeFn, MethodMap, StaticHandler, createHandler, } from './h
 export { MethodProto, createInvokeFn } from './invoker.js';
 export { Packet, CallStart, CallData } from './rpcproto.pb.js';
 export { Mux, StaticMux, LookupMethod, createMux } from './mux.js';
+export { ChannelStreamMessage, ChannelPort, ChannelStream, newBroadcastChannelStream, } from './channel.js';
 export { BroadcastChannelDuplex, BroadcastChannelConn, newBroadcastChannelDuplex, } from './broadcast-channel.js';
 export { MessagePortDuplex, MessagePortConn, newMessagePortDuplex, } from './message-port.js';
 export { MessageDefinition, DecodeMessageTransform, buildDecodeMessageTransform, EncodeMessageTransform, buildEncodeMessageTransform, memoProto, memoProtoDecode, } from './message.js';

package/dist/srpc/index.js

@@ -7,6 +7,7 @@ export { StaticHandler, createHandler, } from './handler.js';
 export { createInvokeFn } from './invoker.js';
 export { Packet, CallStart, CallData } from './rpcproto.pb.js';
 export { StaticMux, createMux } from './mux.js';
+export { ChannelStream, newBroadcastChannelStream, } from './channel.js';
 export { BroadcastChannelDuplex, BroadcastChannelConn, newBroadcastChannelDuplex, } from './broadcast-channel.js';
 export { MessagePortDuplex, MessagePortConn, newMessagePortDuplex, } from './message-port.js';
 export { buildDecodeMessageTransform, buildEncodeMessageTransform, memoProto, memoProtoDecode, } from './message.js';

package/go.mod

@@ -9,7 +9,7 @@ require (
 )
 
 require (
-	github.com/aperturerobotics/util v1.13.3 // latest
+	github.com/aperturerobotics/util v1.13.5 // latest
 	github.com/libp2p/go-libp2p v0.32.2 // latest
 	github.com/libp2p/go-yamux/v4 v4.0.2-0.20240206065824-7222fbc3459d // master
 	github.com/sirupsen/logrus v1.9.3 // latest

package/go.sum

@@ -2,6 +2,8 @@ github.com/aperturerobotics/util v1.13.2 h1:MTe8MO+Tfo9d3Z4Zi6Akm//rIymy5gyoAOIE
 github.com/aperturerobotics/util v1.13.2/go.mod h1:d84OAQAGXCpl7JOBstnal91Lm6nKgk+vBgtHPgxBYrQ=
 github.com/aperturerobotics/util v1.13.3 h1:N4JXKYql0R/A2hMuV79SZ2vaftf8tiN8DUJ8sGc7Rso=
 github.com/aperturerobotics/util v1.13.3/go.mod h1:JdziNd9tR6lWqc9bSMIe1At8Gagrg986rmtZuPCv6+w=
+github.com/aperturerobotics/util v1.13.5 h1:g8Q9VKBUYR5Nu5Ee/ZygVbe0JkGXeNq1fBkT0ipLBMY=
+github.com/aperturerobotics/util v1.13.5/go.mod h1:8AfpGb9RJqUItLBb5ec3sprpl9swYyHlgOw0HzkE+S8=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=

package/package.json

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

package/srpc/channel.ts

@@ -0,0 +1,230 @@
+import type { Sink, Source, Duplex } from 'it-stream-types'
+import { pushable, Pushable } from 'it-pushable'
+
+// ChannelStreamMessage is a message sent over the stream.
+export interface ChannelStreamMessage<T> {
+  // from indicates who sent the message.
+  from: string
+  // ack indicates a remote joined the stream.
+  ack?: boolean
+  // opened indicates the remote has opened the stream.
+  opened?: boolean
+  // closed indicates the stream is closed.
+  closed?: boolean
+  // 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 }
+
+// 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>
+  implements Duplex<AsyncGenerator<T>, Source<T>, Promise<void>>
+{
+  // channel is the read/write channel.
+  public readonly channel: ChannelPort
+  // sink is the sink for incoming messages.
+  public sink: Sink<Source<T>, Promise<void>>
+  // source is the source for outgoing messages.
+  public source: AsyncGenerator<T>
+  // _source emits incoming data to the source.
+  private readonly _source: {
+    push: (val: T) => void
+    end: (err?: Error) => void
+  }
+  // localId is the local identifier
+  private readonly localId: string
+  // localOpen indicates the local side has opened the stream.
+  private localOpen: boolean
+  // remoteOpen indicates the remote side has opened the stream.
+  private remoteOpen: boolean
+  // waitRemoteOpen indicates the remote side has opened the stream.
+  public readonly waitRemoteOpen: Promise<void>
+  // _remoteOpen fulfills the waitRemoteOpen promise.
+  private _remoteOpen?: (err?: Error) => void
+  // remoteAck indicates the remote side has acked the stream.
+  private remoteAck: boolean
+  // waitRemoteAck indicates the remote side has opened the stream.
+  public readonly waitRemoteAck: Promise<void>
+  // _remoteAck fulfills the waitRemoteAck promise.
+  private _remoteAck?: (err?: Error) => void
+
+  // isAcked checks if the stream is acknowledged by the remote.
+  public get isAcked() {
+    return this.remoteAck || false
+  }
+
+  // isOpen checks if the stream is opened by the remote.
+  public get isOpen() {
+    return this.remoteOpen || false
+  }
+
+  // remoteOpen indicates if we know the remote has already opened the stream.
+  constructor(localId: string, channel: ChannelPort, remoteOpen: boolean) {
+    this.localId = localId
+    this.channel = channel
+    this.sink = this._createSink()
+
+    this.localOpen = false
+    this.remoteAck = remoteOpen
+    this.remoteOpen = remoteOpen
+    if (remoteOpen) {
+      this.waitRemoteOpen = Promise.resolve()
+      this.waitRemoteAck = Promise.resolve()
+    } else {
+      this.waitRemoteOpen = new Promise<void>((resolve, reject) => {
+        this._remoteOpen = (err?: Error) => {
+          if (err) {
+            reject(err)
+          } else {
+            resolve()
+          }
+        }
+      })
+      this.waitRemoteOpen.catch(() => {})
+      this.waitRemoteAck = new Promise<void>((resolve, reject) => {
+        this._remoteAck = (err?: Error) => {
+          if (err) {
+            reject(err)
+          } else {
+            resolve()
+          }
+        }
+      })
+      this.waitRemoteAck.catch(() => {})
+    }
+
+    const source: Pushable<T> = pushable({ objectMode: true })
+    this.source = source
+    this._source = source
+
+    const onMessage = this.onMessage.bind(this)
+    if (channel instanceof MessagePort) {
+      // MessagePort
+      channel.onmessage = onMessage
+      channel.start()
+    } else {
+      // BroadcastChannel
+      channel.rx.onmessage = onMessage
+    }
+    this.postMessage({ ack: true })
+  }
+
+  // postMessage writes a message to the stream.
+  private postMessage(msg: Partial<ChannelStreamMessage<T>>) {
+    msg.from = this.localId
+    if (this.channel instanceof MessagePort) {
+      this.channel.postMessage(msg)
+    } else {
+      this.channel.tx.postMessage(msg)
+    }
+  }
+
+  // close closes the broadcast channels.
+  public close(error?: Error) {
+    // write a message to indicate the stream is now closed.
+    this.postMessage({ closed: true, error })
+    // close channels
+    if (this.channel instanceof MessagePort) {
+      this.channel.close()
+    } else {
+      this.channel.tx.close()
+      this.channel.rx.close()
+    }
+    if (!this.remoteOpen && this._remoteOpen) {
+      this._remoteOpen(error || new Error('closed'))
+    }
+    if (!this.remoteAck && this._remoteAck) {
+      this._remoteAck(error || new Error('closed'))
+    }
+  }
+
+  // onLocalOpened indicates the local side has opened the read stream.
+  private onLocalOpened() {
+    if (!this.localOpen) {
+      this.localOpen = true
+      this.postMessage({ opened: true })
+    }
+  }
+
+  // onRemoteAcked indicates the remote side has acked the stream.
+  private onRemoteAcked() {
+    if (!this.remoteAck) {
+      this.remoteAck = true
+      if (this._remoteAck) {
+        this._remoteAck()
+      }
+    }
+  }
+
+  // onRemoteOpened indicates the remote side has opened the read stream.
+  private onRemoteOpened() {
+    if (!this.remoteOpen) {
+      this.remoteOpen = true
+      if (this._remoteOpen) {
+        this._remoteOpen()
+      }
+    }
+  }
+
+  private _createSink(): Sink<Source<T>, Promise<void>> {
+    return async (source: Source<T>) => {
+      // make sure the remote is open before we send any data.
+      await this.waitRemoteAck
+      this.onLocalOpened()
+      await this.waitRemoteOpen
+
+      try {
+        for await (const msg of source) {
+          this.postMessage({ data: msg })
+        }
+        this.postMessage({ closed: true })
+      } catch (error) {
+        this.postMessage({ closed: true, error: error as Error })
+      }
+    }
+  }
+
+  private onMessage(ev: MessageEvent<ChannelStreamMessage<T>>) {
+    const msg = ev.data
+    if (!msg || msg.from === this.localId || !msg.from) {
+      return
+    }
+    if (msg.ack || msg.opened) {
+      this.onRemoteAcked()
+    }
+    if (msg.opened) {
+      this.onRemoteOpened()
+    }
+    const { data, closed, error: err } = msg
+    if (data) {
+      this._source.push(data)
+    }
+    if (err) {
+      this._source.end(err)
+    } else if (closed) {
+      this._source.end()
+    }
+  }
+}
+
+// newBroadcastChannelStream constructs a ChannelStream with a channel name.
+export function newBroadcastChannelStream<T>(
+  id: string,
+  readName: string,
+  writeName: string,
+  remoteOpen: boolean,
+): ChannelStream<T> {
+  return new ChannelStream<T>(
+    id,
+    { tx: new BroadcastChannel(writeName), rx: new BroadcastChannel(readName) },
+    remoteOpen,
+  )
+}

package/srpc/index.ts

@@ -19,6 +19,12 @@ export {
 export { MethodProto, createInvokeFn } from './invoker.js'
 export { Packet, CallStart, CallData } from './rpcproto.pb.js'
 export { Mux, StaticMux, LookupMethod, createMux } from './mux.js'
+export {
+  ChannelStreamMessage,
+  ChannelPort,
+  ChannelStream,
+  newBroadcastChannelStream,
+} from './channel.js'
 export {
   BroadcastChannelDuplex,
   BroadcastChannelConn,