@dxos/teleport 0.1.14

package/src/muxing/framer.ts

@@ -0,0 +1,132 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import assert from 'node:assert';
+import { Duplex } from 'node:stream';
+import * as varint from 'varint';
+
+import { RpcPort } from './rpc-port';
+
+/**
+ * Framer that turns a stream of binary messages into a framed RpcPort.
+ *
+ * Buffers are written prefixed by their length encoded as a varint.
+ */
+export class Framer {
+  // private readonly _tagBuffer = Buffer.alloc(4)
+  private _messageCb?: (msg: Uint8Array) => void;
+  private _subscribeCb?: () => void;
+  private _buffer?: Buffer; // The rest of the bytes from the previous write call.
+
+  private readonly _stream = new Duplex({
+    objectMode: false,
+    read: () => {},
+    write: (chunk, encoding, callback) => {
+      assert(!this._subscribeCb, 'Internal Framer bug. Concurrent writes detected.');
+
+      if (this._buffer && this._buffer.length > 0) {
+        this._buffer = Buffer.concat([this._buffer, chunk]);
+      } else {
+        this._buffer = chunk;
+      }
+
+      if (this._messageCb) {
+        this._popFrames();
+        callback();
+      } else {
+        this._subscribeCb = () => {
+          // Schedule the processing of the chunk after the peer subscribes to the messages.
+          this._popFrames();
+          this._subscribeCb = undefined;
+          callback();
+        };
+      }
+    }
+  });
+
+  public readonly port: RpcPort = {
+    send: (message) => {
+      this._stream.push(encodeLength(message.length));
+      this._stream.push(message);
+    },
+    subscribe: (callback) => {
+      assert(!this._messageCb, 'Rpc port already has a message listener.');
+      this._messageCb = callback;
+      this._subscribeCb?.();
+      return () => {
+        this._messageCb = undefined;
+      };
+    }
+  };
+
+  get stream(): Duplex {
+    return this._stream;
+  }
+
+  /**
+   * Attempts to pop frames from the buffer and call the message callback.
+   */
+  private _popFrames() {
+    let offset = 0;
+    while (offset < this._buffer!.length) {
+      const frame = readFrame(this._buffer!, offset);
+
+      if (!frame) {
+        break; // Couldn't read frame but there are still bytes left in the buffer.
+      }
+      offset += frame.bytesConsumed;
+      // TODO(dmaretskyi): Possible bug if the peer unsubscribes while we're reading frames.
+      this._messageCb!(frame.payload);
+    }
+
+    if (offset < this._buffer!.length) {
+      // Save the rest of the bytes for the next write call.
+      this._buffer = this._buffer!.subarray(offset);
+    } else {
+      this._buffer = undefined;
+    }
+  }
+
+  destroy() {
+    // TODO(dmaretskyi): Call stream.end() instead?
+    this._stream.destroy();
+  }
+}
+
+/**
+ * Attempts to read a frame from the input buffer.
+ */
+export const readFrame = (buffer: Buffer, offset: number): { payload: Buffer; bytesConsumed: number } | undefined => {
+  try {
+    const frameLength = varint.decode(buffer, offset);
+    const tagLength = varint.decode.bytes;
+
+    if (buffer.length < offset + tagLength + frameLength) {
+      // Not enough bytes to read the frame.
+      return undefined;
+    }
+
+    const payload = buffer.subarray(offset + tagLength, offset + tagLength + frameLength);
+
+    return {
+      payload,
+      bytesConsumed: tagLength + frameLength
+    };
+  } catch (err) {
+    if (err instanceof RangeError) {
+      // Not enough bytes to read the tag.
+      return undefined;
+    } else {
+      throw err;
+    }
+  }
+};
+
+const encodeLength = (length: number) => {
+  const res = varint.encode(length, Buffer.allocUnsafe(4)).subarray(0, varint.encode.bytes);
+  if (varint.encode.bytes > 4) {
+    throw new Error('Frame too large');
+  }
+  return res;
+};

package/src/muxing/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2021 DXOS.org
+//
+
+export * from './framer';
+export * from './muxer';
+export * from './rpc-port';

package/src/muxing/muxer.test.ts

@@ -0,0 +1,185 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import { expect } from 'chai';
+import { pipeline, Transform } from 'node:stream';
+import waitForExpect from 'wait-for-expect';
+
+import { latch, asyncTimeout } from '@dxos/async';
+import { schema } from '@dxos/protocols';
+import { TestService } from '@dxos/protocols/proto/example/testing/rpc';
+import { createProtoRpcPeer } from '@dxos/rpc';
+import { afterTest, describe, test } from '@dxos/test';
+
+import { Muxer } from './muxer';
+import { RpcPort } from './rpc-port';
+
+const setupPeers = () => {
+  const peer1 = new Muxer();
+  const peer2 = new Muxer();
+
+  peer1.stream.pipe(peer2.stream).pipe(peer1.stream);
+
+  const unpipe = () => {
+    peer1.stream.unpipe(peer2.stream);
+    peer2.stream.unpipe(peer1.stream);
+  };
+  afterTest(unpipe);
+
+  return {
+    peer1,
+    peer2,
+    unpipe
+  };
+};
+
+const createRpc = (port: RpcPort, handler: TestService['testCall']) =>
+  createProtoRpcPeer({
+    requested: {
+      TestService: schema.getService('example.testing.rpc.TestService')
+    },
+    exposed: {
+      TestService: schema.getService('example.testing.rpc.TestService')
+    },
+    handlers: {
+      TestService: {
+        testCall: handler,
+        voidCall: async () => {}
+      }
+    },
+    port
+  });
+
+describe('Muxer', () => {
+  test('rpc calls on 1 port', async () => {
+    const { peer1, peer2 } = setupPeers();
+
+    const [wait, inc] = latch({ count: 2, timeout: 500 });
+
+    for (const peer of [peer1, peer2]) {
+      const client = createRpc(
+        peer.createPort('example.extension/rpc', {
+          contentType: 'application/x-protobuf; messageType="dxos.rpc.Message"'
+        }),
+        async ({ data }) => ({ data })
+      );
+
+      setTimeout(async () => {
+        await client.open();
+        expect(await client.rpc.TestService.testCall({ data: 'test' })).to.deep.eq({ data: 'test' });
+        inc();
+      });
+    }
+
+    await wait();
+  });
+
+  test('destroy releases other stream', async () => {
+    const { peer1, peer2 } = setupPeers();
+
+    const promise = asyncTimeout(peer1.close.waitForCount(1), 100);
+
+    peer2.destroy();
+
+    await promise;
+  });
+
+  test('two concurrent rpc ports', async () => {
+    const { peer1, peer2 } = setupPeers();
+
+    const [wait, inc] = latch({ count: 4, timeout: 500 });
+
+    for (const peer of [peer1, peer2]) {
+      {
+        const client = createRpc(
+          peer.createPort('example.extension/rpc1', {
+            contentType: 'application/x-protobuf; messageType="dxos.rpc.Message"'
+          }),
+          async ({ data }) => ({ data: data + '-rpc1' })
+        );
+
+        setTimeout(async () => {
+          await client.open();
+          expect(await client.rpc.TestService.testCall({ data: 'test' })).to.deep.eq({ data: 'test-rpc1' });
+          inc();
+        });
+      }
+      {
+        const client = createRpc(
+          peer.createPort('example.extension/rpc2', {
+            contentType: 'application/x-protobuf; messageType="dxos.rpc.Message"'
+          }),
+          async ({ data }) => ({ data: data + '-rpc2' })
+        );
+
+        setTimeout(async () => {
+          await client.open();
+          expect(await client.rpc.TestService.testCall({ data: 'test' })).to.deep.eq({ data: 'test-rpc2' });
+          inc();
+        });
+      }
+    }
+
+    await wait();
+  });
+
+  test('node.js streams', async () => {
+    const { peer1, peer2 } = setupPeers();
+
+    const stream2 = peer2.createStream('example.extension/stream1', {
+      contentType: 'application/octet-stream'
+    });
+
+    // Buffer data before remote peer opens.
+    stream2.write('hello');
+
+    const stream1 = peer1.createStream('example.extension/stream1', {
+      contentType: 'application/octet-stream'
+    });
+
+    pipeline(
+      stream1,
+      new Transform({
+        transform: (chunk, encoding, callback) => {
+          callback(null, Buffer.from(Buffer.from(chunk).toString().toUpperCase())); // Make all characters uppercase.
+        }
+      }),
+      stream1,
+      () => {}
+    );
+
+    let received = '';
+    stream2.on('data', (chunk) => {
+      received += Buffer.from(chunk).toString();
+    });
+
+    stream2.write(' world!');
+
+    await waitForExpect(() => {
+      expect(received).to.eq('HELLO WORLD!');
+    });
+  });
+
+  test('destroying muxers destroys open streams', async () => {
+    const { peer1, peer2 } = setupPeers();
+
+    const stream1 = peer1.createStream('example.extension/stream1', {
+      contentType: 'application/octet-stream'
+    });
+
+    const stream2 = peer2.createStream('example.extension/stream1', {
+      contentType: 'application/octet-stream'
+    });
+
+    const [wait, inc] = latch({ count: 2, timeout: 500 });
+
+    stream1.once('close', inc);
+    stream2.once('close', inc);
+
+    peer1.destroy();
+    // Peer2 should also be destroyed.
+
+    await wait();
+  });
+});

package/src/muxing/muxer.ts

@@ -0,0 +1,301 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import assert from 'node:assert';
+import { Duplex } from 'node:stream';
+
+import { Event } from '@dxos/async';
+import { failUndefined } from '@dxos/debug';
+import { log } from '@dxos/log';
+import { schema } from '@dxos/protocols';
+import { Command } from '@dxos/protocols/proto/dxos/mesh/muxer';
+
+import { Framer } from './framer';
+import { RpcPort } from './rpc-port';
+
+const codec = schema.getCodecForType('dxos.mesh.muxer.Command');
+
+export type CleanupCb = void | (() => void);
+
+export type CreateChannelOpts = {
+  /**
+   * MIME type of the wire content.
+   *
+   * Examples:
+   *  - application/octet-stream
+   *  - application/x-protobuf; messageType="dxos.rpc.Message"
+   */
+  contentType?: string;
+};
+
+/**
+ * Channel based multiplexer.
+ *
+ * Can be used to open a number of channels represented by streams or RPC ports.
+ * Performs framing for RPC ports.
+ * Will buffer data until the remote peer opens the channel.
+ *
+ * The API will not advertise channels that as they are opened by the remote peer.
+ * A higher level API (could be build on top of this muxer) for channel discovery is required.
+ */
+export class Muxer {
+  private readonly _framer = new Framer();
+  public readonly stream = this._framer.stream;
+
+  private readonly _channelsByLocalId = new Map<number, Channel>();
+  private readonly _channelsByTag = new Map<string, Channel>();
+
+  private _nextId = 0;
+  private _destroyed = false;
+  private _destroying = false;
+
+  public close = new Event<Error | undefined>();
+
+  constructor() {
+    this._framer.port.subscribe((msg) => {
+      this._handleCommand(codec.decode(msg));
+    });
+  }
+
+  /**
+   * Creates a duplex Node.js-style stream.
+   * The remote peer is expected to call `createStream` with the same tag.
+   * The stream is immediately readable and writable.
+   * NOTE: The data will be buffered until the stream is opened remotely with the same tag (may cause a memory leak).
+   */
+  createStream(tag: string, opts: CreateChannelOpts = {}): Duplex {
+    const channel = this._getOrCreateStream({
+      tag,
+      contentType: opts.contentType
+    });
+    assert(!channel.push, `Channel already open: ${tag}`);
+
+    const stream = new Duplex({
+      write: (data, encoding, callback) => {
+        this._sendData(channel, data);
+        // TODO(dmaretskyi): Should we error if sending data has errored?
+        callback();
+      },
+      read: () => {} // No-op. We will push data when we receive it.
+    });
+
+    channel.push = (data) => {
+      stream.push(data);
+    };
+    channel.destroy = (err) => {
+      // TODO(dmaretskyi): Call stream.end() instead?
+      stream.destroy(err);
+    };
+
+    // NOTE: Make sure channel.push is set before sending the command.
+    this._sendCommand({
+      openChannel: {
+        id: channel.id,
+        tag: channel.tag,
+        contentType: channel.contentType
+      }
+    });
+
+    return stream;
+  }
+
+  /**
+   * Creates an RPC port.
+   * The remote peer is expected to call `createPort` with the same tag.
+   * The port is immediately usable.
+   * NOTE: The data will be buffered until the stream is opened remotely with the same tag (may cause a memory leak).
+   */
+  createPort(tag: string, opts: CreateChannelOpts = {}): RpcPort {
+    const channel = this._getOrCreateStream({
+      tag,
+      contentType: opts.contentType
+    });
+    assert(!channel.push, `Channel already open: ${tag}`);
+
+    // We need to buffer incoming data until the port is subscribed to.
+    let inboundBuffer: Uint8Array[] = [];
+    let callback: ((data: Uint8Array) => void) | undefined;
+
+    channel.push = (data) => {
+      if (callback) {
+        callback(data);
+      } else {
+        inboundBuffer.push(data);
+      }
+    };
+
+    const port: RpcPort = {
+      send: (data: Uint8Array) => {
+        this._sendData(channel, data); // TODO(dmaretskyi): Error propagation?
+
+        // TODO(dmaretskyi): Debugging.
+        // appendFileSync('log.json', JSON.stringify(schema.getCodecForType('dxos.rpc.RpcMessage').decode(data), null, 2) + '\n')
+      },
+      subscribe: (cb: (data: Uint8Array) => void) => {
+        assert(!callback, 'Only one subscriber is allowed');
+        callback = cb;
+        for (const data of inboundBuffer) {
+          cb(data);
+        }
+        inboundBuffer = [];
+      }
+    };
+
+    // NOTE: Make sure channel.push is set before sending the command.
+    this._sendCommand({
+      openChannel: {
+        id: channel.id,
+        tag: channel.tag,
+        contentType: channel.contentType
+      }
+    });
+
+    return port;
+  }
+
+  /**
+   * Force-close with optional error.
+   */
+  destroy(err?: Error) {
+    if (this._destroying) {
+      return;
+    }
+    this._destroying = true;
+
+    this._sendCommand({
+      destroy: {
+        error: err?.message
+      }
+    });
+    this._dispose();
+  }
+
+  private _dispose(err?: Error) {
+    if (this._destroyed) {
+      return;
+    }
+
+    this._destroyed = true;
+    this._framer.destroy();
+
+    for (const channel of this._channelsByTag.values()) {
+      channel.destroy?.(err);
+    }
+
+    this.close.emit(err);
+
+    // Make it easy for GC.
+    this._channelsByLocalId.clear();
+    this._channelsByTag.clear();
+  }
+
+  private _handleCommand(cmd: Command) {
+    log('Received command', { cmd });
+
+    if (this._destroyed || this._destroying) {
+      log.warn('Received command after destroy');
+      return;
+    }
+
+    if (cmd.openChannel) {
+      const channel = this._getOrCreateStream({
+        tag: cmd.openChannel.tag,
+        contentType: cmd.openChannel.contentType
+      });
+      channel.remoteId = cmd.openChannel.id;
+
+      // Flush any buffered data.
+      for (const data of channel.buffer) {
+        this._sendCommand({
+          data: {
+            channelId: channel.remoteId,
+            data
+          }
+        });
+      }
+      channel.buffer = [];
+    } else if (cmd.data) {
+      const stream = this._channelsByLocalId.get(cmd.data.channelId) ?? failUndefined();
+      if (!stream.push) {
+        log.warn('Received data for channel before it was opened', { tag: stream.tag });
+        return;
+      }
+      stream.push(cmd.data.data);
+    } else if (cmd.destroy) {
+      this._dispose();
+    }
+  }
+
+  private _sendCommand(cmd: Command) {
+    Promise.resolve(this._framer.port.send(codec.encode(cmd))).catch((err) => {
+      this.destroy(err);
+    });
+  }
+
+  private _getOrCreateStream(params: CreateChannelInternalParams): Channel {
+    let channel = this._channelsByTag.get(params.tag);
+    if (!channel) {
+      channel = {
+        id: this._nextId++,
+        remoteId: null,
+        tag: params.tag,
+        contentType: params.contentType,
+        buffer: [],
+        push: null,
+        destroy: null
+      };
+      this._channelsByTag.set(channel.tag, channel);
+      this._channelsByLocalId.set(channel.id, channel);
+    }
+    return channel;
+  }
+
+  private _sendData(channel: Channel, data: Uint8Array) {
+    if (channel.remoteId === null) {
+      // Remote side has not opened the channel yet.
+      channel.buffer.push(data);
+    } else {
+      this._sendCommand({
+        data: {
+          channelId: channel.remoteId,
+          data
+        }
+      });
+    }
+  }
+}
+
+type Channel = {
+  /**
+   * Our local channel ID.
+   * Incoming Data commands will have this ID.
+   */
+  id: number;
+  tag: string;
+
+  /**
+   * Remote id is set when we receive an OpenChannel command.
+   * The originating Data commands should carry this id.
+   */
+  remoteId: null | number;
+
+  contentType?: string;
+
+  /**
+   * Send buffer.
+   */
+  buffer: Uint8Array[];
+
+  /**
+   * Set when we initialize a NodeJS stream or an RPC port consuming the channel.
+   */
+  push: null | ((data: Uint8Array) => void);
+
+  destroy: null | ((err?: Error) => void);
+};
+
+type CreateChannelInternalParams = {
+  tag: string;
+  contentType?: string;
+};

package/src/muxing/rpc-port.test.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import * as rpc from '@dxos/rpc';
+import { test } from '@dxos/test';
+
+import { RpcPort } from './rpc-port';
+
+// This test will break at compile time if the interface changes.
+test('RpcPort type is assignable to type from @dxos/rpc package', () => {
+  {
+    const _port: RpcPort = {} as rpc.RpcPort;
+  }
+  {
+    const _port: rpc.RpcPort = {} as RpcPort;
+  }
+});

package/src/muxing/rpc-port.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import { MaybePromise } from '@dxos/util';
+
+/**
+ * Interface for a transport-agnostic port to send/receive binary messages.
+ *
+ * NOTE: Copied from @dxos/rpc to avoid dependency. Structural typing should still work.
+ */
+export interface RpcPort {
+  send: (msg: Uint8Array) => MaybePromise<void>;
+  subscribe: (cb: (msg: Uint8Array) => void) => (() => void) | void;
+}