@dxos/protocols 2.33.8-dev.8609bc45 → 2.33.9-dev.002e8917

package/src/public-key.ts

@@ -2,9 +2,18 @@
 // Copyright 2020 DXOS.org
 //
 
+import assert from 'node:assert';
+import { inspect, InspectOptionsStylized } from 'node:util';
 import randomBytes from 'randombytes';
-import { inspect } from 'util';
 
+export const PUBLIC_KEY_LENGTH = 32;
+export const SECRET_KEY_LENGTH = 64;
+
+/**
+ * The purpose of this class is to assure consistent use of keys throughout the project.
+ * Keys should be maintained as buffers in objects and proto definitions, and converted to hex
+ * strings as late as possible (eg, to log/display).
+ */
 export class PublicKey {
   /**
    * Creates new instance of PublicKey automatically determining the input format.
@@ -63,6 +72,35 @@ export class PublicKey {
     return PublicKey.from(left).equals(right);
   }
 
+  /**
+   * @param Hex string representation of key.
+   * @return Key buffer.
+   * @deprecated All keys should be represented as instances of PublicKey.
+   */
+  static bufferize (str: string): Buffer {
+    assert(typeof str === 'string', 'Invalid type');
+    const buffer = Buffer.from(str, 'hex');
+    assert(buffer.length === PUBLIC_KEY_LENGTH || buffer.length === SECRET_KEY_LENGTH,
+      `Invalid key length: ${buffer.length}`);
+    return buffer;
+  }
+
+  /**
+   * @param Public key like data structure (but not PublicKey which should use toString).
+   * @return Hex string representation of key.
+   * @deprecated All keys should be represented as instances of PublicKey.
+   */
+  static stringify (key: Buffer | Uint8Array): string {
+    if (key instanceof PublicKey) {
+      key = key.asBuffer();
+    } else if (key instanceof Uint8Array) {
+      key = Buffer.from(key);
+    }
+
+    assert(key instanceof Buffer, 'Invalid type');
+    return key.toString('hex');
+  }
+
   constructor (
     private readonly _value: Uint8Array
   ) {
@@ -118,8 +156,36 @@ export class PublicKey {
   /**
    * Used by NodeJS to get textual representation of this object when it's printed with a `console.log` statement.
    */
-  [inspect.custom] () {
-    return `<PublicKey ${this.truncate()}>`;
+  [inspect.custom] (depth: number, options: InspectOptionsStylized) {
+    if (!options.colors || !process.stdout.hasColors()) {
+      return `<PublicKey ${this.truncate()}>`;
+    }
+
+    const printControlCode = (code: number) => {
+      return `\x1b[${code}m`;
+    };
+
+    // Compute simple hash of the key.
+    const hash = Math.abs(this._value.reduce((acc, val) => acc ^ val | 0, 0));
+
+    const colors = [
+      'red',
+      'green',
+      'yellow',
+      'blue',
+      'magenta',
+      'cyan',
+      'redBright',
+      'greenBright',
+      'yellowBright',
+      'blueBright',
+      'magentaBright',
+      'cyanBright',
+      'whiteBright'
+    ];
+    const color = colors[hash % colors.length];
+
+    return `<PublicKey ${printControlCode(inspect.colors[color]![0])}${this.truncate()}${printControlCode(inspect.colors.reset![0])}>`;
   }
 
   /**

package/src/timeframe.test.ts

@@ -0,0 +1,125 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+import debug from 'debug';
+
+import { PublicKey } from './public-key';
+import { Timeframe } from './timeframe';
+
+const log = debug('dxos:protocols:timeframe:test');
+
+describe('spacetime', () => {
+  test('constructors', () => {
+    const feedKey = PublicKey.random();
+
+    const tf1 = new Timeframe([[feedKey, 1]]);
+    log(tf1.toString());
+    expect(tf1).toBeTruthy();
+  });
+
+  test('merge/subtract', () => {
+    const feedKey1 = PublicKey.random();
+    const feedKey2 = PublicKey.random();
+    const feedKey3 = PublicKey.random();
+
+    {
+      // Merge.
+      const tf1 = new Timeframe();
+      const tf2 = new Timeframe([[feedKey1, 2], [feedKey2, 1]]);
+      const tf3 = Timeframe.merge(tf1, tf2);
+      expect(tf3.frames()).toHaveLength(2);
+    }
+
+    {
+      // Merge (no change).
+      const tf1 = new Timeframe([[feedKey1, 1], [feedKey2, 1]]);
+      const tf2 = new Timeframe([[feedKey1, 2], [feedKey3, 1]]);
+      const tf3 = Timeframe.merge(tf1, tf2);
+      expect(tf3.frames()).toHaveLength(3);
+    }
+
+    {
+      // Merge (no change).
+      const tf1 = new Timeframe([[feedKey1, 1]]);
+      const tf2 = new Timeframe([[feedKey1, 3]]);
+      const tf3 = new Timeframe([[feedKey1, 2]]);
+      const tf4 = Timeframe.merge(tf1, tf2, tf3);
+      log(tf4.toString());
+      expect(tf4.frames()).toHaveLength(1);
+      expect(tf4.get(feedKey1)).toBe(3);
+    }
+
+    {
+      // Remove keys.
+      const tf1 = new Timeframe([[feedKey1, 1], [feedKey2, 2]]);
+      const tf2 = tf1.withoutKeys([feedKey1, feedKey3]);
+      expect(tf2.frames()).toHaveLength(1);
+    }
+  });
+
+  test('dependencies', () => {
+    const feedKey1 = PublicKey.random();
+    const feedKey2 = PublicKey.random();
+    const feedKey3 = PublicKey.random();
+
+    {
+      const tf1 = new Timeframe();
+      const tf2 = new Timeframe();
+      const tf3 = Timeframe.dependencies(tf1, tf2);
+      log(tf3.toString());
+      expect(tf3.frames()).toHaveLength(0);
+    }
+
+    {
+      const tf1 = new Timeframe();
+      const tf2 = new Timeframe([[feedKey1, 10], [feedKey2, 11]]);
+      const tf3 = Timeframe.dependencies(tf1, tf2);
+      log(tf3.toString());
+      expect(tf3.frames()).toHaveLength(0);
+    }
+
+    {
+      const tf1 = new Timeframe([[feedKey1, 10], [feedKey2, 10]]);
+      const tf2 = new Timeframe();
+      const tf3 = Timeframe.dependencies(tf1, tf2);
+      log(tf3.toString());
+      expect(tf3.frames()).toHaveLength(2);
+    }
+
+    // TODO(burdon): Test 0.
+    {
+      const tf1 = new Timeframe([[feedKey1, 0]]);
+      const tf2 = new Timeframe([[feedKey1, 0]]);
+      const tf3 = Timeframe.dependencies(tf1, tf2);
+      log(tf3.toString());
+      expect(tf3.frames()).toHaveLength(0);
+    }
+
+    {
+      const tf1 = new Timeframe([[feedKey1, 1]]);
+      const tf2 = new Timeframe([[feedKey1, 1]]);
+      const tf3 = Timeframe.dependencies(tf1, tf2);
+      log(tf1.toString());
+      log(tf2.toString());
+      log(tf3.toString());
+      expect(tf3.frames()).toHaveLength(0);
+    }
+
+    {
+      const tf1 = new Timeframe([[feedKey1, 10], [feedKey2, 10]]);
+      const tf2 = new Timeframe([[feedKey1, 10], [feedKey2, 11]]);
+      const tf3 = Timeframe.dependencies(tf1, tf2);
+      log(tf3.toString());
+      expect(tf3.frames()).toHaveLength(0);
+    }
+
+    {
+      const tf1 = new Timeframe([[feedKey1, 10], [feedKey2, 10], [feedKey3, 10]]);
+      const tf2 = new Timeframe([[feedKey1, 10], [feedKey2, 9]]);
+      const tf3 = Timeframe.dependencies(tf1, tf2);
+      log(tf3.toString());
+      expect(tf3.frames()).toHaveLength(2);
+    }
+  });
+});

package/src/timeframe.ts

@@ -0,0 +1,144 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+import { inspect } from 'node:util';
+
+import { PublicKey } from './public-key';
+
+/**
+ * A mapping of feed key to a sequence number on that feed.
+ * Describes how many messages have been processed.
+ */
+export class Timeframe {
+  // Cannot use ComplexMap because @dxos/util depends on @dxos/protocols for PublicKey.
+  private readonly _keys = new Map<string, PublicKey>();
+  private readonly _frames = new Map<string, number>();
+
+  constructor (frames: [PublicKey, number][] = []) {
+    for (const [key, seq] of frames) {
+      this.set(key, seq);
+    }
+  }
+
+  get (key: PublicKey) {
+    const keyString = key.toString();
+    return this._frames.get(keyString);
+  }
+
+  set (key: PublicKey, value: number) {
+    const keyString = key.toString();
+    this._frames.set(keyString, value);
+    this._keys.set(keyString, key);
+  }
+
+  // TODO(burdon): Change to getter.
+  frames (): [PublicKey, number][] {
+    return Array.from(this._frames.entries())
+      .map(([keyString, value]): [PublicKey, number] | undefined => {
+        const key = this._keys.get(keyString);
+        if (!key) {
+          return undefined;
+        }
+
+        return [key, value];
+      })
+      .filter((frame): frame is [PublicKey, number] => !!frame);
+  }
+
+  // TODO(burdon): Change to getter.
+  size () {
+    return this._frames.size;
+  }
+
+  // TODO(burdon): Change to getter (empty).
+  isEmpty () {
+    return this.size() === 0;
+  }
+
+  /**
+   * Returns a new timeframe with specified keys removed.
+   * @param keys
+   */
+  withoutKeys (keys: PublicKey[]): Timeframe {
+    return new Timeframe(this.frames().filter(([frameKey]) => keys.every(key =>
+      Buffer.compare(key.asBuffer(), frameKey.asBuffer()) !== 0)));
+  }
+
+  /**
+   * Returns a total amount of messages represented by this timeframe.
+   */
+  totalMessages (): number {
+    return Array.from(this._frames.values()).reduce((acc, seq) => acc + seq + 1, 0);
+  }
+
+  toJSON () {
+    return this.frames().reduce((frames: Record<string, number>, [key, seq]) => {
+      frames[key.truncate()] = seq;
+      return frames;
+    }, {});
+  }
+
+  toString () {
+    return `(${this.frames().map(([key, seq]) => `${key.truncate()} => ${seq}`).join(', ')})`;
+  }
+
+  /**
+   * Used by NodeJS to get textual representation of this object when it's printed with a `console.log` statement.
+   */
+  [inspect.custom] () {
+    return `Timeframe${this.toString()}`;
+  }
+
+  /**
+   * Merges the values, updating the highest sequence numbers.
+   * @param timeframes
+   */
+  static merge (...timeframes: Timeframe[]): Timeframe {
+    const result = new Timeframe();
+    for (const timeframe of timeframes) {
+      for (const [key, seq] of timeframe.frames()) {
+        const current = result.get(key);
+        if (current === undefined || seq > current) {
+          result.set(key, seq);
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Compares two timeframes and returns an array of frames from the first timeframe where the sequence number
+   * is greater than the associated sequence number from the second timeframe.
+   *
+   * @param tf1
+   * @param tf2
+   */
+  static dependencies (
+    tf1: Timeframe, tf2: Timeframe
+  ): Timeframe {
+    const result = new Timeframe();
+    for (const [key, seq] of tf1.frames()) {
+      const otherSeq = tf2.get(key);
+      if (otherSeq === undefined || otherSeq < seq) {
+        result.set(key, seq);
+      }
+    }
+
+    return result;
+  }
+}
+
+export const timeframeSubstitutions = {
+  'dxos.echo.timeframe.TimeframeVector': {
+    encode: (timeframe: Timeframe) => ({
+      frames: timeframe.frames().map(([feedKey, seq]) => ({ feedKey: feedKey.asUint8Array(), seq }))
+    }),
+    decode: (vector: any) => new Timeframe(
+      (vector.frames ?? [])
+        .filter((frame: any) => frame.feedKey != null && frame.seq != null)
+        .map((frame: any) => [PublicKey.from(new Uint8Array(frame.feedKey)), frame.seq])
+    )
+  }
+};