starpc 0.25.0 → 0.25.2

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,32 @@ 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 opts = { idleTimeoutMs: 250, keepAliveMs: 100 };
+    const clientChannelStream = new ChannelStream('client', clientPort, opts);
+    const serverChannelStream = new ChannelStream('server', serverPort, opts);
+    // 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,9 @@
 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;
+    closed?: true;
     error?: Error;
     data?: T;
 }
@@ -11,7 +11,12 @@ 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;
+    keepAliveMs?: number;
+    idleTimeoutMs?: number;
+}
+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>;
@@ -24,10 +29,14 @@ export declare class ChannelStream<T> implements Duplex<AsyncGenerator<T>, Sourc
     private remoteAck;
     readonly waitRemoteAck: Promise<void>;
     private _remoteAck?;
+    private keepAlive?;
+    private idleWatchdog?;
     get isAcked(): boolean;
     get isOpen(): boolean;
-    constructor(localId: string, channel: ChannelPort, remoteOpen: boolean);
+    constructor(localId: string, channel: ChannelPort, opts?: ChannelStreamOpts);
     private postMessage;
+    private idleElapsed;
+    private keepAliveElapsed;
     close(error?: Error): void;
     private onLocalOpened;
     private onRemoteAcked;
@@ -35,4 +44,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

@@ -1,4 +1,6 @@
 import { pushable } from 'it-pushable';
+import { Watchdog } from './watchdog.js';
+import { ERR_STREAM_IDLE } from './errors.js';
 // ChannelStream implements a Stream over a BroadcastChannel duplex or MessagePort.
 //
 // NOTE: there is no way to tell if a BroadcastChannel or MessagePort is closed.
@@ -7,21 +9,22 @@ 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) {
+        // initial state
         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;
+        // wire up the promises for remote ack and remote open
+        if (this.remoteOpen) {
             this.waitRemoteOpen = Promise.resolve();
             this.waitRemoteAck = Promise.resolve();
         }
@@ -49,9 +52,13 @@ export class ChannelStream {
             });
             this.waitRemoteAck.catch(() => { });
         }
+        // create the sink
+        this.sink = this._createSink();
+        // create the pushable source
         const source = pushable({ objectMode: true });
         this.source = source;
         this._source = source;
+        // wire up the message handlers
         const onMessage = this.onMessage.bind(this);
         if (channel instanceof MessagePort) {
             // MessagePort
@@ -62,6 +69,14 @@ export class ChannelStream {
             // BroadcastChannel
             channel.rx.onmessage = onMessage;
         }
+        // handle the keep alive or idle timeout opts
+        if (opts?.idleTimeoutMs != null) {
+            this.idleWatchdog = new Watchdog(opts.idleTimeoutMs, () => this.idleElapsed());
+        }
+        if (opts?.keepAliveMs != null) {
+            this.keepAlive = new Watchdog(opts.keepAliveMs, () => this.keepAliveElapsed());
+        }
+        // broadcast ack to start the stream
         this.postMessage({ ack: true });
     }
     // postMessage writes a message to the stream.
@@ -73,6 +88,23 @@ export class ChannelStream {
         else {
             this.channel.tx.postMessage(msg);
         }
+        if (!msg.closed) {
+            this.keepAlive?.feed();
+        }
+    }
+    // idleElapsed is called if the idle timeout was elapsed.
+    idleElapsed() {
+        if (this.idleWatchdog) {
+            delete this.idleWatchdog;
+            this.close(new Error(ERR_STREAM_IDLE));
+        }
+    }
+    // keepAliveElapsed is called if the keep alive timeout was elapsed.
+    keepAliveElapsed() {
+        if (this.keepAlive) {
+            // send a keep-alive message
+            this.postMessage({});
+        }
     }
     // close closes the broadcast channels.
     close(error) {
@@ -92,6 +124,15 @@ export class ChannelStream {
         if (!this.remoteAck && this._remoteAck) {
             this._remoteAck(error || new Error('closed'));
         }
+        if (this.idleWatchdog) {
+            this.idleWatchdog.clear();
+            delete this.idleWatchdog;
+        }
+        if (this.keepAlive) {
+            this.keepAlive.clear();
+            delete this.keepAlive;
+        }
+        this._source.end(error);
     }
     // onLocalOpened indicates the local side has opened the read stream.
     onLocalOpened() {
@@ -140,6 +181,7 @@ export class ChannelStream {
         if (!msg || msg.from === this.localId || !msg.from) {
             return;
         }
+        this.idleWatchdog?.feed();
         if (msg.ack || msg.opened) {
             this.onRemoteAcked();
         }
@@ -159,6 +201,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/dist/srpc/errors.d.ts

@@ -1,3 +1,5 @@
 export declare const ERR_RPC_ABORT = "ERR_RPC_ABORT";
 export declare function isAbortError(err: unknown): boolean;
+export declare const ERR_STREAM_IDLE = "ERR_STREAM_IDLE";
+export declare function isStreamIdleError(err: unknown): boolean;
 export declare function castToError(err: any, defaultMsg?: string): Error;

package/dist/srpc/errors.js

@@ -8,6 +8,16 @@ export function isAbortError(err) {
     const message = err.message;
     return message === ERR_RPC_ABORT;
 }
+// ERR_STREAM_IDLE is returned if the stream idle timeout was exceeded.
+export const ERR_STREAM_IDLE = 'ERR_STREAM_IDLE';
+// isStreamIdleError checks if the error object is ERR_STREAM_IDLE.
+export function isStreamIdleError(err) {
+    if (typeof err !== 'object') {
+        return false;
+    }
+    const message = err.message;
+    return message === ERR_STREAM_IDLE;
+}
 // castToError casts an object to an Error.
 // if err is a string, uses it as the message.
 // if err is undefined, returns new Error(defaultMsg)

package/dist/srpc/index.d.ts

@@ -1,4 +1,4 @@
-export { ERR_RPC_ABORT, isAbortError, castToError } from './errors.js';
+export { ERR_RPC_ABORT, isAbortError, ERR_STREAM_IDLE, isStreamIdleError, castToError, } from './errors.js';
 export { Client } from './client.js';
 export { Server } from './server.js';
 export { StreamConn, StreamConnParams, StreamHandler } from './conn.js';
@@ -8,7 +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 { ChannelStreamMessage, ChannelPort, ChannelStream, ChannelStreamOpts, 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';
@@ -17,3 +17,4 @@ export { combineUint8ArrayListTransform } from './array-list.js';
 export { ValueCtr } from './value-ctr.js';
 export { OpenStreamCtr } from './open-stream-ctr.js';
 export { writeToPushable, buildPushableSink } from './pushable.js';
+export { Watchdog } from './watchdog.js';

package/dist/srpc/index.js

@@ -1,4 +1,4 @@
-export { ERR_RPC_ABORT, isAbortError, castToError } from './errors.js';
+export { ERR_RPC_ABORT, isAbortError, ERR_STREAM_IDLE, isStreamIdleError, castToError, } from './errors.js';
 export { Client } from './client.js';
 export { Server } from './server.js';
 export { StreamConn } from './conn.js';
@@ -16,3 +16,4 @@ export { combineUint8ArrayListTransform } from './array-list.js';
 export { ValueCtr } from './value-ctr.js';
 export { OpenStreamCtr } from './open-stream-ctr.js';
 export { writeToPushable, buildPushableSink } from './pushable.js';
+export { Watchdog } from './watchdog.js';

package/dist/srpc/watchdog.d.ts

@@ -0,0 +1,35 @@
+export declare class Watchdog {
+    private timeoutDuration;
+    private expiredCallback;
+    private timerId;
+    private lastFeedTimestamp;
+    /**
+     * Constructs a Watchdog instance.
+     * The Watchdog will not start ticking until feed() is called.
+     * @param timeoutDuration The duration in milliseconds after which the watchdog should expire if not fed.
+     * @param expiredCallback The callback function to be called when the watchdog expires.
+     */
+    constructor(timeoutDuration: number, expiredCallback: () => void);
+    /**
+     * Feeds the watchdog, preventing it from expiring.
+     * This resets the timeout and reschedules the next tick.
+     */
+    feed(): void;
+    /**
+     * Clears the current timeout, effectively stopping the watchdog.
+     * This prevents the expired callback from being called until the watchdog is fed again.
+     */
+    clear(): void;
+    /**
+     * Schedules the next tick of the watchdog.
+     * This method calculates the delay for the next tick based on the last feed time
+     * and schedules a call to tickWatchdog after that delay.
+     */
+    private scheduleTickWatchdog;
+    /**
+     * Handler for the watchdog tick.
+     * Checks if the time since the last feed is greater than the timeout duration.
+     * If so, it calls the expired callback. Otherwise, it reschedules the tick.
+     */
+    private tickWatchdog;
+}

package/dist/srpc/watchdog.js

@@ -0,0 +1,64 @@
+// Watchdog must be fed every timeoutDuration or it will call the expired callback.
+export class Watchdog {
+    /**
+     * Constructs a Watchdog instance.
+     * The Watchdog will not start ticking until feed() is called.
+     * @param timeoutDuration The duration in milliseconds after which the watchdog should expire if not fed.
+     * @param expiredCallback The callback function to be called when the watchdog expires.
+     */
+    constructor(timeoutDuration, expiredCallback) {
+        this.timerId = null;
+        this.lastFeedTimestamp = null;
+        this.timeoutDuration = timeoutDuration;
+        this.expiredCallback = expiredCallback;
+    }
+    /**
+     * Feeds the watchdog, preventing it from expiring.
+     * This resets the timeout and reschedules the next tick.
+     */
+    feed() {
+        this.lastFeedTimestamp = Date.now();
+        this.scheduleTickWatchdog(this.timeoutDuration);
+    }
+    /**
+     * Clears the current timeout, effectively stopping the watchdog.
+     * This prevents the expired callback from being called until the watchdog is fed again.
+     */
+    clear() {
+        if (this.timerId != null) {
+            clearTimeout(this.timerId);
+            this.timerId = null;
+        }
+        this.lastFeedTimestamp = null;
+    }
+    /**
+     * Schedules the next tick of the watchdog.
+     * This method calculates the delay for the next tick based on the last feed time
+     * and schedules a call to tickWatchdog after that delay.
+     */
+    scheduleTickWatchdog(delay) {
+        if (this.timerId != null) {
+            clearTimeout(this.timerId);
+        }
+        this.timerId = setTimeout(() => this.tickWatchdog(), delay);
+    }
+    /**
+     * Handler for the watchdog tick.
+     * Checks if the time since the last feed is greater than the timeout duration.
+     * If so, it calls the expired callback. Otherwise, it reschedules the tick.
+     */
+    tickWatchdog() {
+        this.timerId = null;
+        if (this.lastFeedTimestamp == null) {
+            this.expiredCallback();
+            return;
+        }
+        const elapsedSinceLastFeed = Date.now() - this.lastFeedTimestamp;
+        if (elapsedSinceLastFeed >= this.timeoutDuration) {
+            this.expiredCallback();
+        }
+        else {
+            this.scheduleTickWatchdog(this.timeoutDuration - elapsedSinceLastFeed);
+        }
+    }
+}

package/e2e/e2e.ts

@@ -1,5 +1,14 @@
 import { pipe } from 'it-pipe'
-import { createHandler, createMux, Server, Client, StreamConn } from '../srpc'
+import {
+  createHandler,
+  createMux,
+  Server,
+  Client,
+  StreamConn,
+  ChannelStream,
+  combineUint8ArrayListTransform,
+  ChannelStreamOpts,
+} from '../srpc'
 import { EchoerDefinition, EchoerServer, runClientTest } from '../echo'
 import { runAbortControllerTest, runRpcStreamTest } from '../echo/client-test'
 
@@ -9,16 +18,48 @@ 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 opts: ChannelStreamOpts = { idleTimeoutMs: 250, keepAliveMs: 100 }
+  const clientChannelStream = new ChannelStream('client', clientPort, opts)
+  const serverChannelStream = new ChannelStream('server', serverPort, opts)
 
+  // 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.2",
   "description": "Streaming protobuf RPC service protocol over any two-way channel.",
   "license": "MIT",
   "author": {

package/srpc/channel.ts

@@ -1,31 +1,48 @@
 import type { Sink, Source, Duplex } from 'it-stream-types'
 import { pushable, Pushable } from 'it-pushable'
+import { Watchdog } from './watchdog.js'
+import { ERR_STREAM_IDLE } from './errors.js'
 
 // 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
+  // ack indicates a remote acked establishing the stream.
+  ack?: true
   // opened indicates the remote has opened the stream.
-  opened?: boolean
+  opened?: 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
+  // keepAliveMs is the maximum time between sending before we send a keep-alive.
+  // if idleTimeoutMs is set on the remote end, this should be less by some margin.
+  keepAliveMs?: number
+  // idleTimeoutMs is the maximum time between receiving before we close the stream.
+  // if keepAliveMs is set on the remote end, this should be more by some margin.
+  idleTimeoutMs?: number
+}
 
 // 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.
@@ -55,27 +72,32 @@ export class ChannelStream<T>
   public readonly waitRemoteAck: Promise<void>
   // _remoteAck fulfills the waitRemoteAck promise.
   private _remoteAck?: (err?: Error) => void
+  // keepAliveWatchdog is the transmission timeout watchdog.
+  private keepAlive?: Watchdog
+  // idleWatchdog is the receive timeout watchdog.
+  private idleWatchdog?: Watchdog
 
   // 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) {
+    // initial state
     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
+
+    // wire up the promises for remote ack and remote open
+    if (this.remoteOpen) {
       this.waitRemoteOpen = Promise.resolve()
       this.waitRemoteAck = Promise.resolve()
     } else {
@@ -101,10 +123,15 @@ export class ChannelStream<T>
       this.waitRemoteAck.catch(() => {})
     }
 
+    // create the sink
+    this.sink = this._createSink()
+
+    // create the pushable source
     const source: Pushable<T> = pushable({ objectMode: true })
     this.source = source
     this._source = source
 
+    // wire up the message handlers
     const onMessage = this.onMessage.bind(this)
     if (channel instanceof MessagePort) {
       // MessagePort
@@ -114,6 +141,20 @@ export class ChannelStream<T>
       // BroadcastChannel
       channel.rx.onmessage = onMessage
     }
+
+    // handle the keep alive or idle timeout opts
+    if (opts?.idleTimeoutMs != null) {
+      this.idleWatchdog = new Watchdog(opts.idleTimeoutMs, () =>
+        this.idleElapsed(),
+      )
+    }
+    if (opts?.keepAliveMs != null) {
+      this.keepAlive = new Watchdog(opts.keepAliveMs, () =>
+        this.keepAliveElapsed(),
+      )
+    }
+
+    // broadcast ack to start the stream
     this.postMessage({ ack: true })
   }
 
@@ -125,6 +166,25 @@ export class ChannelStream<T>
     } else {
       this.channel.tx.postMessage(msg)
     }
+    if (!msg.closed) {
+      this.keepAlive?.feed()
+    }
+  }
+
+  // idleElapsed is called if the idle timeout was elapsed.
+  private idleElapsed() {
+    if (this.idleWatchdog) {
+      delete this.idleWatchdog
+      this.close(new Error(ERR_STREAM_IDLE))
+    }
+  }
+
+  // keepAliveElapsed is called if the keep alive timeout was elapsed.
+  private keepAliveElapsed() {
+    if (this.keepAlive) {
+      // send a keep-alive message
+      this.postMessage({})
+    }
   }
 
   // close closes the broadcast channels.
@@ -144,6 +204,15 @@ export class ChannelStream<T>
     if (!this.remoteAck && this._remoteAck) {
       this._remoteAck(error || new Error('closed'))
     }
+    if (this.idleWatchdog) {
+      this.idleWatchdog.clear()
+      delete this.idleWatchdog
+    }
+    if (this.keepAlive) {
+      this.keepAlive.clear()
+      delete this.keepAlive
+    }
+    this._source.end(error)
   }
 
   // onLocalOpened indicates the local side has opened the read stream.
@@ -197,6 +266,7 @@ export class ChannelStream<T>
     if (!msg || msg.from === this.localId || !msg.from) {
       return
     }
+    this.idleWatchdog?.feed()
     if (msg.ack || msg.opened) {
       this.onRemoteAcked()
     }
@@ -220,11 +290,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,
   )
 }

package/srpc/errors.ts

@@ -10,6 +10,18 @@ export function isAbortError(err: unknown): boolean {
   return message === ERR_RPC_ABORT
 }
 
+// ERR_STREAM_IDLE is returned if the stream idle timeout was exceeded.
+export const ERR_STREAM_IDLE = 'ERR_STREAM_IDLE'
+
+// isStreamIdleError checks if the error object is ERR_STREAM_IDLE.
+export function isStreamIdleError(err: unknown): boolean {
+  if (typeof err !== 'object') {
+    return false
+  }
+  const message = (err as Error).message
+  return message === ERR_STREAM_IDLE
+}
+
 // castToError casts an object to an Error.
 // if err is a string, uses it as the message.
 // if err is undefined, returns new Error(defaultMsg)

package/srpc/index.ts

@@ -1,4 +1,10 @@
-export { ERR_RPC_ABORT, isAbortError, castToError } from './errors.js'
+export {
+  ERR_RPC_ABORT,
+  isAbortError,
+  ERR_STREAM_IDLE,
+  isStreamIdleError,
+  castToError,
+} from './errors.js'
 export { Client } from './client.js'
 export { Server } from './server.js'
 export { StreamConn, StreamConnParams, StreamHandler } from './conn.js'
@@ -23,6 +29,7 @@ export {
   ChannelStreamMessage,
   ChannelPort,
   ChannelStream,
+  ChannelStreamOpts,
   newBroadcastChannelStream,
 } from './channel.js'
 export {
@@ -61,3 +68,4 @@ export { combineUint8ArrayListTransform } from './array-list.js'
 export { ValueCtr } from './value-ctr.js'
 export { OpenStreamCtr } from './open-stream-ctr.js'
 export { writeToPushable, buildPushableSink } from './pushable.js'
+export { Watchdog } from './watchdog.js'

package/srpc/watchdog.ts

@@ -0,0 +1,70 @@
+// Watchdog must be fed every timeoutDuration or it will call the expired callback.
+export class Watchdog {
+  private timeoutDuration: number
+  private expiredCallback: () => void
+  private timerId: NodeJS.Timeout | null = null
+  private lastFeedTimestamp: number | null = null
+
+  /**
+   * Constructs a Watchdog instance.
+   * The Watchdog will not start ticking until feed() is called.
+   * @param timeoutDuration The duration in milliseconds after which the watchdog should expire if not fed.
+   * @param expiredCallback The callback function to be called when the watchdog expires.
+   */
+  constructor(timeoutDuration: number, expiredCallback: () => void) {
+    this.timeoutDuration = timeoutDuration
+    this.expiredCallback = expiredCallback
+  }
+
+  /**
+   * Feeds the watchdog, preventing it from expiring.
+   * This resets the timeout and reschedules the next tick.
+   */
+  public feed(): void {
+    this.lastFeedTimestamp = Date.now()
+    this.scheduleTickWatchdog(this.timeoutDuration)
+  }
+
+  /**
+   * Clears the current timeout, effectively stopping the watchdog.
+   * This prevents the expired callback from being called until the watchdog is fed again.
+   */
+  public clear(): void {
+    if (this.timerId != null) {
+      clearTimeout(this.timerId)
+      this.timerId = null
+    }
+    this.lastFeedTimestamp = null
+  }
+
+  /**
+   * Schedules the next tick of the watchdog.
+   * This method calculates the delay for the next tick based on the last feed time
+   * and schedules a call to tickWatchdog after that delay.
+   */
+  private scheduleTickWatchdog(delay: number): void {
+    if (this.timerId != null) {
+      clearTimeout(this.timerId)
+    }
+    this.timerId = setTimeout(() => this.tickWatchdog(), delay)
+  }
+
+  /**
+   * Handler for the watchdog tick.
+   * Checks if the time since the last feed is greater than the timeout duration.
+   * If so, it calls the expired callback. Otherwise, it reschedules the tick.
+   */
+  private tickWatchdog(): void {
+    this.timerId = null
+    if (this.lastFeedTimestamp == null) {
+      this.expiredCallback()
+      return
+    }
+    const elapsedSinceLastFeed = Date.now() - this.lastFeedTimestamp
+    if (elapsedSinceLastFeed >= this.timeoutDuration) {
+      this.expiredCallback()
+    } else {
+      this.scheduleTickWatchdog(this.timeoutDuration - elapsedSinceLastFeed)
+    }
+  }
+}