@synnaxlabs/client 0.42.3 → 0.43.0

package/src/framer/streamer.spec.ts

@@ -7,257 +7,462 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { DataType, TimeStamp } from "@synnaxlabs/x/telem";
-import { describe, expect, it, test } from "vitest";
+import { EOF, Unreachable } from "@synnaxlabs/freighter";
+import { DataType, Series, TimeSpan, TimeStamp } from "@synnaxlabs/x/telem";
+import { describe, expect, it, test, vi } from "vitest";
 
+import { type channel } from "@/channel";
+import { Frame } from "@/framer/frame";
+import {
+  HardenedStreamer,
+  parseStreamerConfig,
+  type Streamer,
+} from "@/framer/streamer";
 import { newClient } from "@/setupspecs";
-import { newVirtualChannel } from "@/testutil/indexedPair";
+import { newVirtualChannel } from "@/testutil/channels";
 
 const client = newClient();
 
 describe("Streamer", () => {
-  test("happy path", async () => {
-    const ch = await newVirtualChannel(client);
-    const streamer = await client.openStreamer(ch.key);
-    const writer = await client.openWriter({
-      start: TimeStamp.now(),
-      channels: ch.key,
+  describe("standard", () => {
+    test("happy path", async () => {
+      const ch = await newVirtualChannel(client);
+      const streamer = await client.openStreamer(ch.key);
+      const writer = await client.openWriter({
+        start: TimeStamp.now(),
+        channels: ch.key,
+      });
+      try {
+        await writer.write(ch.key, new Float64Array([1, 2, 3]));
+      } finally {
+        await writer.close();
+      }
+      const d = await streamer.read();
+      expect(Array.from(d.get(ch.key))).toEqual([1, 2, 3]);
     });
-    try {
-      await writer.write(ch.key, new Float64Array([1, 2, 3]));
-    } finally {
-      await writer.close();
-    }
-    const d = await streamer.read();
-    expect(Array.from(d.get(ch.key))).toEqual([1, 2, 3]);
-  });
-  test("open with config", async () => {
-    const ch = await newVirtualChannel(client);
-    await expect(client.openStreamer({ channels: ch.key })).resolves.not.toThrow();
-  });
-  it("should not throw an error when the streamer is opened with zero channels", async () => {
-    await expect(client.openStreamer([])).resolves.not.toThrow();
-  });
-  it("should throw an error when the streamer is opened with a channel that does not exist", async () => {
-    await expect(client.openStreamer([5678])).rejects.toThrow("not found");
-  });
-  test("downsample factor of 1", async () => {
-    const ch = await newVirtualChannel(client);
-    const streamer = await client.openStreamer({
-      channels: ch.key,
-      downSampleFactor: 1,
+    test("open with config", async () => {
+      const ch = await newVirtualChannel(client);
+      await expect(client.openStreamer({ channels: ch.key })).resolves.not.toThrow();
     });
-    const writer = await client.openWriter({
-      start: TimeStamp.now(),
-      channels: ch.key,
+    it("should not throw an error when the streamer is opened with zero channels", async () => {
+      await expect(client.openStreamer([])).resolves.not.toThrow();
     });
-    try {
-      await writer.write(ch.key, new Float64Array([1, 2, 3, 4, 5]));
-    } finally {
-      await writer.close();
-    }
-    const d = await streamer.read();
-    expect(Array.from(d.get(ch.key))).toEqual([1, 2, 3, 4, 5]);
-  });
-  test("downsample factor of 2", async () => {
-    const ch = await newVirtualChannel(client);
-    const streamer = await client.openStreamer({
-      channels: ch.key,
-      downSampleFactor: 2,
+    it("should throw an error when the streamer is opened with a channel that does not exist", async () => {
+      await expect(client.openStreamer([5678])).rejects.toThrow("not found");
     });
-    const writer = await client.openWriter({
-      start: TimeStamp.now(),
-      channels: ch.key,
-    });
-    try {
-      await writer.write(ch.key, new Float64Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]));
-    } finally {
-      await writer.close();
-    }
-    const d = await streamer.read();
-    expect(Array.from(d.get(ch.key))).toEqual([1, 3, 5, 7, 9]);
-  });
-  test("downsample factor of 10", async () => {
-    const ch = await newVirtualChannel(client);
-    const streamer = await client.openStreamer({
-      channels: ch.key,
-      downSampleFactor: 10,
-    });
-    const writer = await client.openWriter({
-      start: TimeStamp.now(),
-      channels: ch.key,
+    describe("downsampling", () => {
+      test("downsample factor of 1", async () => {
+        const ch = await newVirtualChannel(client);
+        const streamer = await client.openStreamer({
+          channels: ch.key,
+          downsampleFactor: 1,
+        });
+        const writer = await client.openWriter({
+          start: TimeStamp.now(),
+          channels: ch.key,
+        });
+        try {
+          await writer.write(ch.key, new Float64Array([1, 2, 3, 4, 5]));
+        } finally {
+          await writer.close();
+        }
+        const d = await streamer.read();
+        expect(Array.from(d.get(ch.key))).toEqual([1, 2, 3, 4, 5]);
+      });
+      test("downsample factor of 2", async () => {
+        const ch = await newVirtualChannel(client);
+        const streamer = await client.openStreamer({
+          channels: ch.key,
+          downsampleFactor: 2,
+        });
+        const writer = await client.openWriter({
+          start: TimeStamp.now(),
+          channels: ch.key,
+        });
+        try {
+          await writer.write(ch.key, new Float64Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]));
+        } finally {
+          await writer.close();
+        }
+        const d = await streamer.read();
+        expect(Array.from(d.get(ch.key))).toEqual([1, 3, 5, 7, 9]);
+      });
+      test("downsample factor of 10", async () => {
+        const ch = await newVirtualChannel(client);
+        const streamer = await client.openStreamer({
+          channels: ch.key,
+          downsampleFactor: 10,
+        });
+        const writer = await client.openWriter({
+          start: TimeStamp.now(),
+          channels: ch.key,
+        });
+        try {
+          await writer.write(ch.key, new Float64Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]));
+        } finally {
+          await writer.close();
+        }
+        const d = await streamer.read();
+        expect(Array.from(d.get(ch.key))).toEqual([1]);
+      });
     });
-    try {
-      await writer.write(ch.key, new Float64Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]));
-    } finally {
-      await writer.close();
-    }
-    const d = await streamer.read();
-    expect(Array.from(d.get(ch.key))).toEqual([1]);
-  });
-});
 
-describe("Streamer - Calculated Channels", () => {
-  test("basic calculated channel streaming", async () => {
-    // Create a timestamp index channel
-    const timeChannel = await client.channels.create({
-      name: "calc_test_time",
-      isIndex: true,
-      dataType: DataType.TIMESTAMP,
-    });
+    describe("calculations", () => {
+      test("basic calculated channel streaming", async () => {
+        // Create a timestamp index channel
+        const timeChannel = await client.channels.create({
+          name: "calc_test_time",
+          isIndex: true,
+          dataType: DataType.TIMESTAMP,
+        });
 
-    // Create source channels with the timestamp index
-    const [channelA, channelB] = await client.channels.create([
-      {
-        name: "test_a",
-        dataType: DataType.FLOAT64,
-        index: timeChannel.key,
-      },
-      {
-        name: "test_b",
-        dataType: DataType.FLOAT64,
-        index: timeChannel.key,
-      },
-    ]);
-
-    // Create calculated channel that adds the two source channels
-    const calcChannel = await client.channels.create({
-      name: "test_calc",
-      dataType: DataType.FLOAT64,
-      index: timeChannel.key,
-      virtual: true,
-      expression: "return test_a + test_b",
-      requires: [channelA.key, channelB.key],
-    });
+        // Create source channels with the timestamp index
+        const [channelA, channelB] = await client.channels.create([
+          {
+            name: "test_a",
+            dataType: DataType.FLOAT64,
+            index: timeChannel.key,
+          },
+          {
+            name: "test_b",
+            dataType: DataType.FLOAT64,
+            index: timeChannel.key,
+          },
+        ]);
 
-    // Set up streamer to listen for calculated results
-    const streamer = await client.openStreamer(calcChannel.key);
+        // Create calculated channel that adds the two source channels
+        const calcChannel = await client.channels.create({
+          name: "test_calc",
+          dataType: DataType.FLOAT64,
+          index: timeChannel.key,
+          virtual: true,
+          expression: "return test_a + test_b",
+          requires: [channelA.key, channelB.key],
+        });
 
-    // Write test data
-    const startTime = TimeStamp.now();
-    const writer = await client.openWriter({
-      start: startTime,
-      channels: [timeChannel.key, channelA.key, channelB.key],
-    });
+        // Set up streamer to listen for calculated results
+        const streamer = await client.openStreamer(calcChannel.key);
+
+        // Write test data
+        const startTime = TimeStamp.now();
+        const writer = await client.openWriter({
+          start: startTime,
+          channels: [timeChannel.key, channelA.key, channelB.key],
+        });
 
-    try {
-      // Write test values - each source gets 2.5 so sum should be 5.0
-      await writer.write({
-        [timeChannel.key]: [startTime],
-        [channelA.key]: new Float64Array([2.5]),
-        [channelB.key]: new Float64Array([2.5]),
+        try {
+          // Write test values - each source gets 2.5 so sum should be 5.0
+          await writer.write({
+            [timeChannel.key]: [startTime],
+            [channelA.key]: new Float64Array([2.5]),
+            [channelB.key]: new Float64Array([2.5]),
+          });
+
+          // Read from streamer
+          const frame = await streamer.read();
+
+          // Verify calculated results
+          const calcData = Array.from(frame.get(calcChannel.key));
+          expect(calcData).toEqual([5.0]);
+        } finally {
+          await writer.close();
+          streamer.close();
+        }
       });
+      test("calculated channel with constant", async () => {
+        // Create an index channel for timestamps
+        const timeChannel = await client.channels.create({
+          name: "calc_const_time",
+          isIndex: true,
+          dataType: DataType.TIMESTAMP,
+        });
 
-      // Read from streamer
-      const frame = await streamer.read();
+        // Create base channel with index
+        const baseChannel = await client.channels.create({
+          name: "base_channel",
+          dataType: DataType.FLOAT64,
+          index: timeChannel.key,
+        });
 
-      // Verify calculated results
-      const calcData = Array.from(frame.get(calcChannel.key));
-      expect(calcData).toEqual([5.0]);
-    } finally {
-      await writer.close();
-      streamer.close();
-    }
-  });
-  test("calculated channel with constant", async () => {
-    // Create an index channel for timestamps
-    const timeChannel = await client.channels.create({
-      name: "calc_const_time",
-      isIndex: true,
-      dataType: DataType.TIMESTAMP,
-    });
+        // Create calculated channel that adds 5
+        const calcChannel = await client.channels.create({
+          name: "calc_const_channel",
+          dataType: DataType.FLOAT64,
+          index: timeChannel.key,
+          virtual: true,
+          expression: `return ${baseChannel.name} + 5`,
+          requires: [baseChannel.key],
+        });
 
-    // Create base channel with index
-    const baseChannel = await client.channels.create({
-      name: "base_channel",
-      dataType: DataType.FLOAT64,
-      index: timeChannel.key,
-    });
+        const streamer = await client.openStreamer(calcChannel.key);
 
-    // Create calculated channel that adds 5
-    const calcChannel = await client.channels.create({
-      name: "calc_const_channel",
-      dataType: DataType.FLOAT64,
-      index: timeChannel.key,
-      virtual: true,
-      expression: `return ${baseChannel.name} + 5`,
-      requires: [baseChannel.key],
-    });
+        const startTime = TimeStamp.now();
+        const writer = await client.openWriter({
+          start: startTime,
+          channels: [timeChannel.key, baseChannel.key],
+        });
 
-    const streamer = await client.openStreamer(calcChannel.key);
+        try {
+          const timestamps = [
+            startTime,
+            new TimeStamp(startTime.valueOf() + BigInt(1000000000)),
+            new TimeStamp(startTime.valueOf() + BigInt(2000000000)),
+          ];
 
-    const startTime = TimeStamp.now();
-    const writer = await client.openWriter({
-      start: startTime,
-      channels: [timeChannel.key, baseChannel.key],
-    });
+          await writer.write({
+            [timeChannel.key]: timestamps,
+            [baseChannel.key]: new Float64Array([1, 2, 3]),
+          });
 
-    try {
-      const timestamps = [
-        startTime,
-        new TimeStamp(startTime.valueOf() + BigInt(1000000000)),
-        new TimeStamp(startTime.valueOf() + BigInt(2000000000)),
-      ];
+          const frame = await streamer.read();
+          const calcData = Array.from(frame.get(calcChannel.key));
+          expect(calcData).toEqual([6, 7, 8]); // Original values + 5
+        } finally {
+          await writer.close();
+          streamer.close();
+        }
+      });
+
+      test("calculated channel with multiple operations", async () => {
+        // Create timestamp channel
+        const timeChannel = await client.channels.create({
+          name: "calc_multi_time",
+          isIndex: true,
+          dataType: DataType.TIMESTAMP,
+        });
+
+        // Create source channels
+        const [channelA, channelB] = await client.channels.create([
+          { name: "multi_test_a", dataType: DataType.FLOAT64, index: timeChannel.key },
+          { name: "multi_test_b", dataType: DataType.FLOAT64, index: timeChannel.key },
+        ]);
+
+        // Create calculated channel with multiple operations
+        const calcChannel = await client.channels.create({
+          name: "multi_calc",
+          dataType: DataType.FLOAT64,
+          index: timeChannel.key,
+          virtual: true,
+          expression: "return (multi_test_a * 2) + (multi_test_b / 2)",
+          requires: [channelA.key, channelB.key],
+        });
+
+        const streamer = await client.openStreamer(calcChannel.key);
 
-      await writer.write({
-        [timeChannel.key]: timestamps,
-        [baseChannel.key]: new Float64Array([1, 2, 3]),
+        const startTime = TimeStamp.now();
+        const writer = await client.openWriter({
+          start: startTime,
+          channels: [timeChannel.key, channelA.key, channelB.key],
+        });
+
+        try {
+          await writer.write({
+            [timeChannel.key]: [startTime],
+            [channelA.key]: new Float64Array([2.0]), // Will be multiplied by 2 = 4.0
+            [channelB.key]: new Float64Array([4.0]), // Will be divided by 2 = 2.0
+          });
+
+          const frame = await streamer.read();
+          const calcData = Array.from(frame.get(calcChannel.key));
+          expect(calcData).toEqual([6.0]); // (2.0 * 2) + (4.0 / 2) = 4.0 + 2.0 = 6.0
+        } finally {
+          await writer.close();
+          streamer.close();
+        }
       });
+    });
+  });
+
+  describe("hardened", () => {
+    class MockStreamer implements Streamer {
+      keys: channel.Key[] = [];
+      updateMock = vi.fn();
+      readMock = vi.fn();
+      closeMock = vi.fn();
+      responses: [Frame, Error | null][] = [];
+      updateErrors: (Error | null)[] = [];
+
+      update(channels: channel.Params): Promise<void> {
+        if (this.updateErrors.length > 0) {
+          const err = this.updateErrors.shift()!;
+          if (err) throw err;
+        }
+        this.updateMock(channels);
+        return Promise.resolve();
+      }
+
+      close(): void {
+        this.closeMock();
+      }
 
-      const frame = await streamer.read();
-      const calcData = Array.from(frame.get(calcChannel.key));
-      expect(calcData).toEqual([6, 7, 8]); // Original values + 5
-    } finally {
-      await writer.close();
-      streamer.close();
+      async read(): Promise<Frame> {
+        this.readMock();
+        if (this.responses.length === 0) throw new EOF();
+        const [frame, err] = this.responses.shift()!;
+        if (err) throw err;
+        return frame;
+      }
+
+      async next(): Promise<IteratorResult<Frame, any>> {
+        const fr = await this.read();
+        return { done: false, value: fr };
+      }
+
+      [Symbol.asyncIterator](): AsyncIterator<Frame, any, undefined> {
+        return this;
+      }
     }
-  });
 
-  test("calculated channel with multiple operations", async () => {
-    // Create timestamp channel
-    const timeChannel = await client.channels.create({
-      name: "calc_multi_time",
-      isIndex: true,
-      dataType: DataType.TIMESTAMP,
+    it("should correctly call the underlying streamer methods", async () => {
+      const streamer = new MockStreamer();
+      const openMock = vi.fn();
+      const config = { channels: [1, 2, 3] };
+      const fr = new Frame({ 1: new Series([1]) });
+      const hardened = await HardenedStreamer.open(
+        async (cfg) => {
+          openMock(cfg);
+          const cfg_ = parseStreamerConfig(cfg);
+          streamer.responses = [[fr, null]];
+          streamer.keys = cfg_.channels as channel.Key[];
+          return streamer;
+        },
+        { channels: [1, 2, 3] },
+      );
+      expect(hardened.keys).toEqual([1, 2, 3]);
+      expect(openMock).toHaveBeenCalledWith(config);
+      await hardened.update([1, 2, 3]);
+      expect(streamer.updateMock).toHaveBeenCalledWith([1, 2, 3]);
+      const fr2 = await hardened.read();
+      expect(streamer.readMock).toHaveBeenCalled();
+      expect(fr2).toEqual(fr);
+      hardened.close();
+      expect(streamer.closeMock).toHaveBeenCalled();
+    });
+
+    it("should correctly iterate over the streamer", async () => {
+      const streamer = new MockStreamer();
+      const fr = new Frame({ 1: new Series([1]) });
+      const fr2 = new Frame({ 1: new Series([2]) });
+      streamer.responses = [
+        [fr, null],
+        [fr2, null],
+      ];
+      const hardened = await HardenedStreamer.open(async () => streamer, {
+        channels: [1],
+      });
+      const first = await hardened.next();
+      expect(first.value).toEqual(fr);
+      const second = await hardened.next();
+      expect(second.value).toEqual(fr2);
+      const third = await hardened.next();
+      expect(third.done).toBe(true);
+      expect(streamer.readMock).toHaveBeenCalledTimes(3);
     });
 
-    // Create source channels
-    const [channelA, channelB] = await client.channels.create([
-      { name: "multi_test_a", dataType: DataType.FLOAT64, index: timeChannel.key },
-      { name: "multi_test_b", dataType: DataType.FLOAT64, index: timeChannel.key },
-    ]);
-
-    // Create calculated channel with multiple operations
-    const calcChannel = await client.channels.create({
-      name: "multi_calc",
-      dataType: DataType.FLOAT64,
-      index: timeChannel.key,
-      virtual: true,
-      expression: "return (multi_test_a * 2) + (multi_test_b / 2)",
-      requires: [channelA.key, channelB.key],
+    it("should try to re-open the streamer when read fails", async () => {
+      const streamer1 = new MockStreamer();
+      const streamer2 = new MockStreamer();
+      const fr1 = new Frame({ 1: new Series([1]) });
+      const fr2 = new Frame({ 1: new Series([2]) });
+      streamer1.responses = [
+        [fr1, null],
+        [fr2, new Unreachable({ message: "cat" })],
+      ];
+      streamer2.responses = [[fr2, null]];
+      let count = 0;
+      const openerMock = vi.fn();
+      const hardened = await HardenedStreamer.open(
+        async () => {
+          count++;
+          openerMock();
+          if (count === 1) return streamer1;
+          return streamer2;
+        },
+        {
+          channels: [1],
+        },
+      );
+      const fr = await hardened.read();
+      expect(streamer1.readMock).toHaveBeenCalledTimes(1);
+      expect(fr).toEqual(fr1);
+      const fr3 = await hardened.read();
+      expect(fr3).toEqual(fr2);
+      expect(streamer2.readMock).toHaveBeenCalledTimes(1);
+      expect(openerMock).toHaveBeenCalledTimes(2);
     });
 
-    const streamer = await client.openStreamer(calcChannel.key);
+    it("should repeatedly try re-opening the streamer when read fails", async () => {
+      const streamer1 = new MockStreamer();
+      const streamer5 = new MockStreamer();
+      const fr1 = new Frame({ 1: new Series([1]) });
+      const fr5 = new Frame({ 1: new Series([4]) });
+      streamer1.responses = [
+        [fr1, null],
+        [fr5, new Unreachable({ message: "cat" })],
+      ];
+      streamer5.responses = [[fr5, null]];
+      const openerMock = vi.fn();
+      let count = 0;
+      const hardened = await HardenedStreamer.open(
+        async () => {
+          count++;
+          openerMock();
+          if (count === 1) return streamer1;
+          if (count < 5) throw new Unreachable({ message: "very unreachable" });
+          return streamer5;
+        },
+        { channels: [1] },
+        { baseInterval: TimeSpan.milliseconds(1) },
+      );
+      const fr = await hardened.read();
+      expect(fr).toEqual(fr1);
+      const fr2 = await hardened.read();
+      expect(fr2).toEqual(fr5);
+      expect(openerMock).toHaveBeenCalledTimes(5);
+    });
 
-    const startTime = TimeStamp.now();
-    const writer = await client.openWriter({
-      start: startTime,
-      channels: [timeChannel.key, channelA.key, channelB.key],
+    it("should rethrow the error when the breaker exceeds the max retries", async () => {
+      const streamer = new MockStreamer();
+      const fr = new Frame({ 1: new Series([1]) });
+      streamer.responses = [[fr, null]];
+      const openerMock = vi.fn();
+      await expect(
+        HardenedStreamer.open(
+          async () => {
+            openerMock();
+            throw new Unreachable({ message: "very unreachable" });
+          },
+          { channels: [1] },
+          { maxRetries: 3, baseInterval: TimeSpan.milliseconds(1) },
+        ),
+      ).rejects.toThrow("very unreachable");
     });
 
-    try {
-      await writer.write({
-        [timeChannel.key]: [startTime],
-        [channelA.key]: new Float64Array([2.0]), // Will be multiplied by 2 = 4.0
-        [channelB.key]: new Float64Array([4.0]), // Will be divided by 2 = 2.0
-      });
+    it("should retry update when the underlying streamer fails", async () => {
+      const streamer1 = new MockStreamer();
+      streamer1.updateErrors = [null, new Unreachable({ message: "cat" })];
+      const streamer2 = new MockStreamer();
+      const fr1 = new Frame({ 1: new Series([1]) });
+      const fr2 = new Frame({ 1: new Series([2]) });
+      streamer1.responses = [[fr1, null]];
+      streamer2.responses = [[fr2, null]];
+      let count = 0;
+      const openerMock = vi.fn();
+      const hardened = await HardenedStreamer.open(
+        async () => {
+          count++;
+          openerMock();
+          if (count === 1) return streamer1;
+          return streamer2;
+        },
+        { channels: [1] },
+      );
 
-      const frame = await streamer.read();
-      const calcData = Array.from(frame.get(calcChannel.key));
-      expect(calcData).toEqual([6.0]); // (2.0 * 2) + (4.0 / 2) = 4.0 + 2.0 = 6.0
-    } finally {
-      await writer.close();
-      streamer.close();
-    }
+      await hardened.update([1, 2]);
+      expect(streamer1.updateMock).toHaveBeenCalledWith([1, 2]);
+
+      await hardened.update([2, 3]);
+      expect(openerMock).toHaveBeenCalledTimes(2);
+    });
   });
 });