@dxos/teleport 0.1.14

package/src/teleport.test.ts

@@ -0,0 +1,81 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import { expect } from 'chai';
+
+import { latch } from '@dxos/async';
+import { log } from '@dxos/log';
+import { afterTest, describe, test } from '@dxos/test';
+
+import { TestExtension } from './test-extension';
+import { TestBuilder } from './testing';
+
+describe('Teleport', () => {
+  test('sends rpc via TestExtension', async () => {
+    const builder = new TestBuilder();
+    afterTest(() => builder.destroy());
+    const { peer1, peer2 } = await builder.createPipedPeers();
+
+    const extension1 = new TestExtension();
+    peer1.teleport!.addExtension('example.testing.rpc', extension1);
+    const extension2 = new TestExtension();
+    peer2.teleport!.addExtension('example.testing.rpc', extension2);
+
+    await extension1.test();
+    log('test1 done');
+    await extension2.test();
+    log('test2 done');
+
+    expect(extension1.extensionContext?.initiator).to.equal(true);
+    expect(extension2.extensionContext?.initiator).to.equal(false);
+  });
+
+  test('disconnect', async () => {
+    const builder = new TestBuilder();
+    afterTest(() => builder.destroy());
+    const { peer1, peer2 } = await builder.createPipedPeers();
+
+    const extension1 = new TestExtension();
+    peer1.teleport!.addExtension('example.testing.rpc', extension1);
+    const extension2 = new TestExtension();
+    peer2.teleport!.addExtension('example.testing.rpc', extension2);
+    await extension1.test();
+    log('test1 done');
+    await extension2.test();
+    log('test2 done');
+
+    await peer2.destroy();
+
+    await extension2.closed.wait({ timeout: 100 });
+    await extension1.closed.wait({ timeout: 100 });
+  });
+
+  test('destroy is idempotent', async () => {
+    const builder = new TestBuilder();
+    afterTest(() => builder.destroy());
+    const { peer1, peer2 } = await builder.createPipedPeers();
+
+    const extension1 = new TestExtension();
+    peer1.teleport!.addExtension('example.testing.rpc', extension1);
+    const extension2 = new TestExtension();
+    peer2.teleport!.addExtension('example.testing.rpc', extension2);
+    await extension1.test();
+    log('test1 done');
+    await extension2.test();
+    log('test2 done');
+
+    {
+      // latch to ensure all 4 destroy calls are made.
+      const [done, inc, errorHandler] = latch({ count: 4 });
+      peer1.destroy().then(inc, errorHandler);
+      peer1.destroy().then(inc, errorHandler);
+      peer2.destroy().then(inc, errorHandler);
+      peer2.destroy().then(inc, errorHandler);
+      await done();
+    }
+
+    await extension2.closed.wait({ timeout: 100 });
+    await extension1.closed.wait({ timeout: 100 });
+  });
+});

package/src/teleport.ts

@@ -0,0 +1,277 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import assert from 'node:assert';
+import { Duplex } from 'node:stream';
+
+import { asyncTimeout, scheduleTaskInterval, runInContextAsync, synchronized, scheduleTask } from '@dxos/async';
+import { Context } from '@dxos/context';
+import { failUndefined } from '@dxos/debug';
+import { PublicKey } from '@dxos/keys';
+import { log } from '@dxos/log';
+import { schema } from '@dxos/protocols';
+import { ControlService } from '@dxos/protocols/proto/dxos/mesh/teleport/control';
+import { createProtoRpcPeer, ProtoRpcPeer, RpcClosedError } from '@dxos/rpc';
+import { Callback } from '@dxos/util';
+
+import { CreateChannelOpts, Muxer, RpcPort } from './muxing';
+
+export type TeleportParams = {
+  initiator: boolean;
+  localPeerId: PublicKey;
+  remotePeerId: PublicKey;
+};
+
+export class Teleport {
+  public readonly initiator: boolean;
+  public readonly localPeerId: PublicKey;
+  public readonly remotePeerId: PublicKey;
+
+  private readonly _ctx = new Context({
+    onError: (err) => {
+      void this.destroy(err).catch(() => {
+        log.error('Error during destroy', err);
+      });
+    }
+  });
+
+  private readonly _muxer = new Muxer();
+
+  private readonly _control = new ControlExtension({
+    heartbeatInterval: 3000,
+    heartbeatTimeout: 3000
+  });
+
+  private readonly _extensions = new Map<string, TeleportExtension>();
+  private readonly _remoteExtensions = new Set<string>();
+
+  private _open = false;
+
+  constructor({ initiator, localPeerId, remotePeerId }: TeleportParams) {
+    assert(typeof initiator === 'boolean');
+    assert(PublicKey.isPublicKey(localPeerId));
+    assert(PublicKey.isPublicKey(remotePeerId));
+    assert(typeof initiator === 'boolean');
+    this.initiator = initiator;
+    this.localPeerId = localPeerId;
+    this.remotePeerId = remotePeerId;
+
+    this._control.onExtensionRegistered.set(async (name) => {
+      log('remote extension', { name });
+      assert(!this._remoteExtensions.has(name), 'Remote extension already exists');
+      this._remoteExtensions.add(name);
+
+      if (this._extensions.has(name)) {
+        try {
+          await this._openExtension(name);
+        } catch (err: any) {
+          await this.destroy(err);
+        }
+      }
+    });
+
+    {
+      // Destroy Teleport when the stream is closed.
+      this._muxer.stream.on('close', async () => {
+        await this.destroy();
+      });
+
+      this._muxer.stream.on('error', async (err) => {
+        await this.destroy(err);
+      });
+    }
+  }
+
+  get stream(): Duplex {
+    return this._muxer.stream;
+  }
+
+  /**
+   * Blocks until the handshake is complete.
+   */
+  async open() {
+    this._setExtension('dxos.mesh.teleport.control', this._control);
+    await this._openExtension('dxos.mesh.teleport.control');
+    this._open = true;
+  }
+
+  async close(err?: Error) {
+    // TODO(dmaretskyi): Try soft close.
+
+    await this.destroy(err);
+  }
+
+  @synchronized
+  async destroy(err?: Error) {
+    if (this._ctx.disposed) {
+      return;
+    }
+
+    await this._ctx.dispose();
+
+    for (const extension of this._extensions.values()) {
+      try {
+        await extension.onClose(err);
+      } catch (err: any) {
+        log.catch(err);
+      }
+    }
+
+    this._muxer.destroy(err);
+  }
+
+  addExtension(name: string, extension: TeleportExtension) {
+    if (!this._open) {
+      throw new Error('Not open');
+    }
+
+    log('addExtension', { name });
+    this._setExtension(name, extension);
+
+    // Perform the registration in a separate tick as this might block while the remote side is opening the extension.
+    scheduleTask(this._ctx, async () => {
+      try {
+        await this._control.registerExtension(name);
+      } catch (err) {
+        if (err instanceof RpcClosedError) {
+          return;
+        }
+        throw err;
+      }
+    });
+
+    if (this._remoteExtensions.has(name)) {
+      // Open the extension in a separate tick.
+      scheduleTask(this._ctx, async () => {
+        await this._openExtension(name);
+      });
+    }
+  }
+
+  private _setExtension(extensionName: string, extension: TeleportExtension) {
+    assert(!extensionName.includes('/'), 'Invalid extension name');
+    assert(!this._extensions.has(extensionName), 'Extension already exists');
+    this._extensions.set(extensionName, extension);
+  }
+
+  private async _openExtension(extensionName: string) {
+    log('open extension', { extensionName });
+    const extension = this._extensions.get(extensionName) ?? failUndefined();
+
+    const context: ExtensionContext = {
+      initiator: this.initiator,
+      localPeerId: this.localPeerId,
+      remotePeerId: this.remotePeerId,
+      createPort: (channelName: string, opts?: CreateChannelOpts) => {
+        assert(!channelName.includes('/'), 'Invalid channel name');
+        return this._muxer.createPort(`${extensionName}/${channelName}`, opts);
+      },
+      createStream: (channelName: string, opts?: CreateChannelOpts) => {
+        assert(!channelName.includes('/'), 'Invalid channel name');
+        return this._muxer.createStream(`${extensionName}/${channelName}`, opts);
+      },
+      close: (err) => {
+        void runInContextAsync(this._ctx, async () => {
+          await this.close(err);
+        });
+      }
+    };
+
+    await extension.onOpen(context);
+    log('extension opened', { extensionName });
+  }
+}
+
+export type ExtensionContext = {
+  /**
+   * One of the peers will be designated an initiator.
+   */
+  initiator: boolean;
+  localPeerId: PublicKey;
+  remotePeerId: PublicKey;
+  createStream(tag: string, opts?: CreateChannelOpts): Duplex;
+  createPort(tag: string, opts?: CreateChannelOpts): RpcPort;
+  close(err?: Error): void;
+};
+
+export interface TeleportExtension {
+  onOpen(context: ExtensionContext): Promise<void>;
+  onClose(err?: Error): Promise<void>;
+}
+
+type ControlExtensionOpts = {
+  heartbeatInterval: number;
+  heartbeatTimeout: number;
+};
+
+class ControlExtension implements TeleportExtension {
+  private readonly _ctx = new Context({
+    onError: (err) => {
+      this._extensionContext.close(err);
+    }
+  });
+
+  private _extensionContext!: ExtensionContext;
+  private _rpc!: ProtoRpcPeer<{ Control: ControlService }>;
+
+  public readonly onExtensionRegistered = new Callback<(extensionName: string) => void>();
+  public readonly onTimeout = new Callback<() => void>();
+
+  constructor(private readonly opts: ControlExtensionOpts) {}
+
+  async onOpen(extensionContext: ExtensionContext): Promise<void> {
+    this._extensionContext = extensionContext;
+
+    // NOTE: Make sure that RPC timeout is greater than the heartbeat timeout.
+    // TODO(dmaretskyi): Allow overwriting the timeout on individual RPC calls?
+    this._rpc = createProtoRpcPeer<ControlRpcBundle, ControlRpcBundle>({
+      requested: {
+        Control: schema.getService('dxos.mesh.teleport.control.ControlService')
+      },
+      exposed: {
+        Control: schema.getService('dxos.mesh.teleport.control.ControlService')
+      },
+      handlers: {
+        Control: {
+          registerExtension: async (request) => {
+            this.onExtensionRegistered.call(request.name);
+          },
+          heartbeat: async (request) => {
+            // Ok.
+          }
+        }
+      },
+      port: extensionContext.createPort('rpc', {
+        contentType: 'application/x-protobuf; messageType="dxos.rpc.Message"'
+      })
+    });
+
+    await this._rpc.open();
+
+    scheduleTaskInterval(
+      this._ctx,
+      async () => {
+        try {
+          await asyncTimeout(this._rpc.rpc.Control.heartbeat(), this.opts.heartbeatTimeout);
+        } catch (err: any) {
+          this.onTimeout.call();
+        }
+      },
+      this.opts.heartbeatInterval
+    );
+  }
+
+  async onClose(err?: Error): Promise<void> {
+    await this._ctx.dispose();
+    await this._rpc.close();
+  }
+
+  async registerExtension(name: string) {
+    await this._rpc.rpc.Control.registerExtension({ name });
+  }
+}
+
+type ControlRpcBundle = {
+  Control: ControlService;
+};

package/src/test-extension.ts

@@ -0,0 +1,65 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import assert from 'node:assert';
+
+import { asyncTimeout, Trigger } from '@dxos/async';
+import { log } from '@dxos/log';
+import { schema } from '@dxos/protocols';
+import { TestService } from '@dxos/protocols/proto/example/testing/rpc';
+import { createProtoRpcPeer, ProtoRpcPeer } from '@dxos/rpc';
+
+import { ExtensionContext, TeleportExtension } from './teleport';
+
+export class TestExtension implements TeleportExtension {
+  public readonly closed = new Trigger();
+  public extensionContext: ExtensionContext | undefined;
+  private _rpc!: ProtoRpcPeer<{ TestService: TestService }>;
+  private _opened = new Trigger();
+
+  async onOpen(context: ExtensionContext) {
+    log('onOpen', { localPeerId: context.localPeerId, remotePeerId: context.remotePeerId });
+    this.extensionContext = context;
+    this._rpc = createProtoRpcPeer<{ TestService: TestService }, { TestService: TestService }>({
+      port: context.createPort('rpc', {
+        contentType: 'application/x-protobuf; messageType="dxos.rpc.Message"'
+      }),
+      requested: {
+        TestService: schema.getService('example.testing.rpc.TestService')
+      },
+      exposed: {
+        TestService: schema.getService('example.testing.rpc.TestService')
+      },
+      handlers: {
+        TestService: {
+          voidCall: async (request) => {
+            // Ok.
+          },
+          testCall: async (request) => {
+            return {
+              data: request.data
+            };
+          }
+        }
+      },
+      timeout: 1000
+    });
+
+    await this._rpc.open();
+
+    this._opened.wake();
+  }
+
+  async onClose(err?: Error) {
+    log('onClose', { err });
+    this.closed.wake();
+    await this._rpc.close();
+  }
+
+  async test() {
+    await this._opened.wait({ timeout: 500 });
+    const res = await asyncTimeout(this._rpc.rpc.TestService.testCall({ data: 'test' }), 500);
+    assert(res.data === 'test');
+  }
+}

package/src/testing.ts

@@ -0,0 +1,75 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import { pipeline } from 'node:stream';
+
+import { PublicKey } from '@dxos/keys';
+import { log } from '@dxos/log';
+
+import { Teleport } from './teleport';
+
+export class TestBuilder {
+  private readonly _peers = new Array<TestPeer>();
+
+  createPeer(peerId?: PublicKey): TestPeer {
+    const peer = new TestPeer(peerId);
+    this._peers.push(peer);
+    return peer;
+  }
+
+  async destroy() {
+    await Promise.all(this._peers.map((agent) => agent.destroy()));
+  }
+
+  /**
+   * Simulates two peers connected via P2P network.
+   */
+  async createPipedPeers({ peerId1, peerId2 }: { peerId1?: PublicKey; peerId2?: PublicKey } = {}) {
+    const peer1 = this.createPeer(peerId1);
+    const peer2 = this.createPeer(peerId2);
+
+    peer1.initializeTeleport({ initiator: true, remotePeerId: peer2.peerId });
+    peer2.initializeTeleport({ initiator: false, remotePeerId: peer1.peerId });
+
+    peer1.pipeline(peer2);
+    peer2.pipeline(peer1);
+
+    await Promise.all([peer1.teleport!.open(), peer2.teleport!.open()]);
+
+    return { peer1, peer2 };
+  }
+}
+
+export class TestPeer {
+  public teleport?: Teleport;
+
+  constructor(public readonly peerId: PublicKey = PublicKey.random()) {}
+
+  initializeTeleport({ initiator, remotePeerId }: { initiator: boolean; remotePeerId: PublicKey }) {
+    if (this.teleport) {
+      return this;
+    }
+    this.teleport = new Teleport({
+      initiator,
+      localPeerId: this.peerId,
+      remotePeerId
+    });
+    return this;
+  }
+
+  pipeline(peer: TestPeer) {
+    if (!this.teleport || !peer.teleport) {
+      throw new Error('Teleport not initialized');
+    }
+    pipeline(this.teleport.stream, peer.teleport.stream, (err) => {
+      if (err && err.code !== 'ERR_STREAM_PREMATURE_CLOSE') {
+        log.catch(err);
+      }
+    });
+  }
+
+  async destroy() {
+    await this.teleport?.destroy();
+  }
+}

package/testing.d.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+/**
+ * Enable testing imports:
+ * ```tsc
+ * import { ... } from '@dxos/teleport/testing';
+ * ```
+ */
+export * from './dist/types/src/testing';

package/testing.js

@@ -0,0 +1,5 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+module.exports = require('./dist/lib/node/testing.cjs');