@anterior/brrr 0.1.1

package/src/store.test.ts

@@ -0,0 +1,398 @@
+import {
+  afterEach,
+  before,
+  beforeEach,
+  mock,
+  type MockTimersOptions,
+  suite,
+  test,
+} from "node:test";
+import {
+  deepStrictEqual,
+  doesNotReject,
+  ok,
+  strictEqual,
+} from "node:assert/strict";
+import {
+  type Cache,
+  type MemKey,
+  Memory,
+  PendingReturns,
+  type Store,
+} from "./store.ts";
+import { InMemoryStore } from "./backends/in-memory.ts";
+import type { Call } from "./call.ts";
+import { PendingReturn, TaggedTuple } from "./tagged-tuple.ts";
+
+await suite(import.meta.filename, async () => {
+  await suite(PendingReturns.name, async () => {
+    await test("Encoded payload can be encoded & decoded", async () => {
+      const original = new PendingReturns(0, [
+        new PendingReturn("a", "b", "c"),
+      ]);
+      const encoded = original.encode();
+      const decoded = PendingReturns.decode(encoded);
+      deepStrictEqual(original, decoded);
+      deepStrictEqual(encoded, decoded.encode());
+    });
+
+    await test("Encoded payload with undefined timestamp can be encoded & decoded", async () => {
+      const original = new PendingReturns(undefined, [
+        new PendingReturn("a", "b", "c"),
+      ]);
+      const encoded = original.encode();
+      const decoded = PendingReturns.decode(encoded);
+      deepStrictEqual(original, decoded);
+      deepStrictEqual(encoded, decoded.encode());
+    });
+  });
+
+  await suite(Memory.name, async () => {
+    let store: Store;
+    let memory: Memory;
+
+    const fixture = {
+      call: {
+        taskName: "test-task",
+        payload: new Uint8Array([1, 2, 3]),
+        callHash: "test-call-hash",
+      } satisfies Call,
+      pendingReturns: {
+        key: {
+          type: "pending_returns",
+          callHash: "test-pending-return-hash",
+        } satisfies MemKey,
+      },
+      newReturn: new PendingReturn("some-root", "some-parent", "some-topic"),
+    } as const;
+
+    beforeEach(async () => {
+      store = new InMemoryStore();
+      memory = new Memory(store);
+      await memory.setCall(fixture.call);
+      await memory.setValue(fixture.call.callHash, fixture.call.payload);
+    });
+
+    await test("getCall", async () => {
+      const retrieved = await memory.getCall(fixture.call.callHash);
+      deepStrictEqual(retrieved, fixture.call);
+    });
+
+    await test("setCall", async () => {
+      const newCall: Call = {
+        taskName: "new-task",
+        payload: new Uint8Array([4, 5, 6]),
+        callHash: "new-call-hash",
+      };
+      await memory.setCall(newCall);
+      const retrieved = await memory.getCall(newCall.callHash);
+      deepStrictEqual(retrieved, newCall);
+    });
+
+    await test("hasValue", async () => {
+      ok(await memory.hasValue(fixture.call.callHash));
+      ok(!(await memory.hasValue("non-existing-call-hash")));
+    });
+
+    await test("getValue", async () => {
+      const retrieved = await memory.getValue(fixture.call.callHash);
+      deepStrictEqual(retrieved, fixture.call.payload);
+      strictEqual(await memory.getValue("non-existing-call-hash"), undefined);
+    });
+
+    await test("setValue", async () => {
+      const newPayload = new Uint8Array([7, 8, 9]);
+      await memory.setValue(fixture.call.callHash, newPayload);
+      const retrieved = await memory.getValue(fixture.call.callHash);
+      deepStrictEqual(retrieved, newPayload);
+    });
+
+    await suite("addPendingReturn", async () => {
+      const mockTimersOptions = {
+        apis: ["Date"],
+        now: 5000,
+      } as const satisfies MockTimersOptions;
+
+      before(() => {
+        mock.timers.enable(mockTimersOptions);
+      });
+
+      await test("simple cases to document & test shouldSchedule", async () => {
+        const hash = "some-hash";
+        const base = new PendingReturn("root", "parent", "topic");
+
+        const cases = [
+          // base case
+          [hash, base, true],
+          // same one, shouldn't schedule again
+          [hash, base, false],
+          // different root, should schedule - it's a retry
+          [hash, new PendingReturn("diff-root", "parent", "topic"), true],
+          // new callHash, new PR, should schedule
+          ["diff-hash", base, true],
+          // continuation, shouldn't schedule again
+          [hash, new PendingReturn("root", "parent", "diff-topic"), false],
+          [hash, new PendingReturn("root", "diff-parent", "topic"), false],
+          [hash, new PendingReturn("root", "diff-parent", "diff-topic"), false],
+        ] as const;
+
+        for (const [hash, pr, shouldSchedule] of cases) {
+          strictEqual(await memory.addPendingReturns(hash, pr), shouldSchedule);
+        }
+
+        // ensure all returns are stored
+        const encoded = await store.get({
+          type: "pending_returns",
+          callHash: hash,
+        });
+        deepStrictEqual(
+          PendingReturns.decode(encoded!).encodedReturns,
+          new Set(cases.map((it) => TaggedTuple.encodeToString(it[1]))),
+        );
+      });
+
+      await test("First-time call triggers schedule and stores return", async () => {
+        const shouldSchedule = await memory.addPendingReturns(
+          fixture.call.callHash,
+          fixture.newReturn,
+        );
+        ok(shouldSchedule);
+        const raw = await store.get({
+          type: "pending_returns",
+          callHash: fixture.call.callHash,
+        });
+        ok(raw);
+        const decoded = PendingReturns.decode(raw);
+        ok(
+          decoded.encodedReturns.has(
+            TaggedTuple.encodeToString(fixture.newReturn),
+          ),
+        );
+        strictEqual(decoded.scheduledAt, mockTimersOptions.now / 1000);
+      });
+
+      await test("Repeated call with same return does not call schedule again", async () => {
+        await memory.addPendingReturns(
+          fixture.call.callHash,
+          fixture.newReturn,
+        );
+        const shouldSchedule = await memory.addPendingReturns(
+          fixture.call.callHash,
+          fixture.newReturn,
+        );
+        ok(!shouldSchedule);
+        const raw = await store.get({
+          type: "pending_returns",
+          callHash: fixture.call.callHash,
+        });
+        ok(raw);
+        const decoded = PendingReturns.decode(raw);
+        deepStrictEqual(
+          decoded.encodedReturns,
+          new Set([TaggedTuple.encodeToString(fixture.newReturn)]),
+        );
+      });
+
+      await test("Handles different returns properly", async () => {
+        await memory.addPendingReturns(
+          fixture.call.callHash,
+          fixture.newReturn,
+        );
+        const completelyDifferentReturn = new PendingReturn(
+          "completely",
+          "different",
+          "return",
+        );
+        const shouldSchedule = await memory.addPendingReturns(
+          fixture.call.callHash,
+          completelyDifferentReturn,
+        );
+        ok(!shouldSchedule);
+        const raw = await store.get({
+          type: "pending_returns",
+          callHash: fixture.call.callHash,
+        });
+        ok(raw);
+        const decoded = PendingReturns.decode(raw);
+        deepStrictEqual(
+          decoded.encodedReturns,
+          new Set(
+            [fixture.newReturn, completelyDifferentReturn].map((it) =>
+              TaggedTuple.encodeToString(it),
+            ),
+          ),
+        );
+      });
+
+      await test("Repeated call with different rootId should schedule again", async () => {
+        const returnWithDifferentRoot = new PendingReturn(
+          "other-root",
+          fixture.newReturn.callHash,
+          fixture.newReturn.topic,
+        );
+        const shouldSchedule = await memory.addPendingReturns(
+          fixture.call.callHash,
+          returnWithDifferentRoot,
+        );
+        ok(shouldSchedule);
+        const raw = await store.get({
+          type: "pending_returns",
+          callHash: fixture.call.callHash,
+        });
+        ok(raw);
+        const decoded = PendingReturns.decode(raw);
+        ok(
+          decoded.encodedReturns.has(
+            TaggedTuple.encodeToString(returnWithDifferentRoot),
+          ),
+        );
+        strictEqual(decoded.scheduledAt, mockTimersOptions.now / 1000);
+      });
+    });
+
+    await suite("withPendingReturnRemove", async () => {
+      const mockFn =
+        mock.fn<(returns: Iterable<PendingReturn>) => Promise<void>>();
+
+      afterEach(() => {
+        mockFn.mock.resetCalls();
+      });
+
+      await test("don't call f if no pending return is found", async () => {
+        await memory.withPendingReturnsRemove(fixture.call.callHash, mockFn);
+        strictEqual(mockFn.mock.callCount(), 0);
+      });
+
+      await test("invokes f with pending returns and deletes the key", async () => {
+        const pendingReturns = new PendingReturns(undefined, [
+          new PendingReturn("a", "b", "c"),
+          new PendingReturn("d", "e", "f"),
+        ]);
+        await store.set(fixture.pendingReturns.key, pendingReturns.encode());
+        await memory.withPendingReturnsRemove(
+          fixture.pendingReturns.key.callHash,
+          (returns) => {
+            deepStrictEqual(
+              [...returns].map((it) => TaggedTuple.encodeToString(it)),
+              [...pendingReturns.encodedReturns],
+            );
+            return mockFn(returns);
+          },
+        );
+        strictEqual(mockFn.mock.callCount(), 1);
+        strictEqual(await store.get(fixture.pendingReturns.key), undefined);
+      });
+    });
+  });
+});
+
+export async function storeContractTest(
+  acquireResource: () => Promise<{ store: Store } & AsyncDisposable>,
+) {
+  await suite("store-contract", async () => {
+    const fixture = {
+      key: {
+        type: "call",
+        callHash: "test-call-hash",
+      } satisfies MemKey,
+      value: new Uint8Array([1, 2, 3, 4, 5]),
+      otherKey: {
+        type: "call",
+        callHash: "other-test-call-hash",
+      },
+    } as const;
+
+    await test("Basic get", async () => {
+      await using resource = await acquireResource();
+      const store = resource.store;
+      await store.set(fixture.key, fixture.value);
+      const retrieved = await store.get(fixture.key);
+      deepStrictEqual(retrieved, fixture.value);
+      strictEqual(await store.get(fixture.otherKey), undefined);
+    });
+
+    await test("Basic has", async () => {
+      await using resource = await acquireResource();
+      await resource.store.set(fixture.key, fixture.value);
+      ok(await resource.store.has(fixture.key));
+      ok(!(await resource.store.has(fixture.otherKey)));
+    });
+
+    await test("Basic set", async () => {
+      await using resource = await acquireResource();
+      await resource.store.set(fixture.key, fixture.value);
+      const newKey: MemKey = {
+        type: "call",
+        callHash: "new-call-hash",
+      };
+      const newValue = new Uint8Array([6, 7, 8, 9, 10]);
+      await resource.store.set(newKey, newValue);
+      const retrieved = await resource.store.get(newKey);
+      deepStrictEqual(retrieved, newValue);
+    });
+
+    await test("Basic delete", async () => {
+      await using resource = await acquireResource();
+      await resource.store.set(fixture.key, fixture.value);
+      await resource.store.delete(fixture.key);
+      strictEqual(await resource.store.get(fixture.key), undefined);
+    });
+
+    await test("Basic setNewValue", async () => {
+      await using resource = await acquireResource();
+      await resource.store.set(fixture.key, fixture.value);
+      const newValue = new Uint8Array([6, 7, 8, 9, 10]);
+      ok(!(await resource.store.setNewValue(fixture.key, newValue)));
+      await doesNotReject(
+        resource.store.setNewValue(fixture.otherKey, newValue),
+      );
+      const retrieved = await resource.store.get(fixture.otherKey);
+      deepStrictEqual(retrieved, newValue);
+    });
+
+    await test("Basic compareAndSet", async () => {
+      await using resource = await acquireResource();
+      await resource.store.set(fixture.key, fixture.value);
+      const newValue = new Uint8Array([6, 7, 8, 9, 10]);
+      await resource.store.compareAndSet(fixture.key, newValue, fixture.value);
+      const retrieved = await resource.store.get(fixture.key);
+      deepStrictEqual(retrieved, newValue);
+      ok(
+        !(await resource.store.compareAndSet(
+          fixture.otherKey,
+          newValue,
+          fixture.value,
+        )),
+      );
+    });
+
+    await test("Basic compareAndDelete", async () => {
+      await using resource = await acquireResource();
+      await resource.store.set(fixture.key, fixture.value);
+      await resource.store.compareAndDelete(fixture.key, fixture.value);
+      strictEqual(await resource.store.get(fixture.key), undefined);
+      ok(
+        !(await resource.store.compareAndDelete(
+          fixture.otherKey,
+          fixture.value,
+        )),
+      );
+    });
+  });
+}
+
+export async function cacheContractTest(
+  acquireResource: () => Promise<{ cache: Cache } & AsyncDisposable>,
+) {
+  await suite("cache-contract", async () => {
+    const key = "test-incr-key";
+
+    await test("Basic incr", async () => {
+      await using resource = await acquireResource();
+      const initialValue = await resource.cache.incr(key);
+      strictEqual(initialValue, 1);
+      const nextValue = await resource.cache.incr(key);
+      strictEqual(nextValue, 2);
+    });
+  });
+}

package/src/store.ts

@@ -0,0 +1,251 @@
+import type { Call } from "./call.ts";
+import { bencoder, decoder } from "./internal-codecs.ts";
+import { CasRetryLimitReachedError, NotFoundError } from "./errors.ts";
+import { PendingReturn, TaggedTuple } from "./tagged-tuple.ts";
+
+export interface PendingReturnsPayload {
+  readonly scheduled_at: number | undefined;
+  readonly returns: unknown[][];
+}
+
+export class PendingReturns {
+  public readonly scheduledAt: number | undefined;
+  public readonly encodedReturns: ReadonlySet<string>;
+
+  public constructor(
+    scheduledAt: number | undefined,
+    returns: Iterable<PendingReturn>,
+  ) {
+    this.scheduledAt = scheduledAt;
+    this.encodedReturns = new Set([...returns].map(TaggedTuple.encodeToString));
+  }
+
+  public static decode(encoded: Uint8Array): PendingReturns {
+    const { scheduled_at, returns } = bencoder.decode(
+      encoded,
+      "utf-8",
+    ) as PendingReturnsPayload;
+    return new this(
+      scheduled_at,
+      [...new Set(returns)].map((it) => {
+        return TaggedTuple.fromTuple(
+          PendingReturn,
+          it as [number, string, string, string],
+        );
+      }),
+    );
+  }
+
+  public encode(): Uint8Array {
+    return bencoder.encode({
+      scheduled_at: this.scheduledAt,
+      returns: [...this.encodedReturns]
+        .map((it) =>
+          TaggedTuple.asTuple(TaggedTuple.decodeFromString(PendingReturn, it)),
+        )
+        .sort(),
+    } satisfies PendingReturnsPayload);
+  }
+}
+
+export interface MemKey {
+  readonly type: "pending_returns" | "call" | "value";
+  readonly callHash: string;
+}
+
+export interface Store {
+  /**
+   * Check if the store has a value for the given key.
+   */
+  has(key: MemKey): Promise<boolean>;
+
+  /**
+   * Get the value for the given key.
+   */
+  get(key: MemKey): Promise<Uint8Array | undefined>;
+
+  /**
+   * Set the value for the given key.
+   */
+  set(key: MemKey, value: Uint8Array): Promise<void>;
+
+  /**
+   * Delete the value for the given key.
+   */
+  delete(key: MemKey): Promise<void>;
+
+  /**
+   * Set a new value for the given key.
+   * Returns true if the value was set, false if the key already exists.
+   */
+  setNewValue(key: MemKey, value: Uint8Array): Promise<boolean>;
+
+  /**
+   * Compare and set a value for the given key.
+   * Returns true if the value was set, false if the expected value did not match.
+   */
+  compareAndSet(
+    key: MemKey,
+    value: Uint8Array,
+    expected: Uint8Array,
+  ): Promise<boolean>;
+
+  /**
+   * Compare and delete a value for the given key.
+   * Returns true if the value was deleted, false if the expected value did not match.
+   */
+  compareAndDelete(key: MemKey, expected: Uint8Array): Promise<boolean>;
+}
+
+export interface Cache {
+  /**
+   * Increment the value for the given key.
+   */
+  incr(key: string): Promise<number>;
+}
+
+export class Memory {
+  private static readonly casRetryLimit = 100;
+
+  private readonly store: Store;
+
+  public constructor(store: Store) {
+    this.store = store;
+  }
+
+  public async getCall(callHash: string): Promise<Call> {
+    const memKey: MemKey = {
+      type: "call",
+      callHash,
+    };
+    const encoded = await this.store.get(memKey);
+    if (!encoded) {
+      throw new NotFoundError(memKey);
+    }
+    const { task_name, payload } = bencoder.decode(encoded) as {
+      task_name: Uint8Array;
+      payload: Uint8Array;
+    };
+    return {
+      taskName: decoder.decode(task_name),
+      payload,
+      callHash,
+    };
+  }
+
+  public async setCall(call: Call): Promise<void> {
+    const encoded = bencoder.encode({
+      task_name: call.taskName,
+      payload: call.payload,
+    });
+    await this.store.set(
+      {
+        type: "call",
+        callHash: call.callHash,
+      },
+      encoded,
+    );
+  }
+
+  public async hasValue(callHash: string): Promise<boolean> {
+    return this.store.has({
+      type: "value",
+      callHash,
+    });
+  }
+
+  public async getValue(callHash: string): Promise<Uint8Array | undefined> {
+    return this.store.get({
+      type: "value",
+      callHash,
+    });
+  }
+
+  public async setValue(callHash: string, payload: Uint8Array): Promise<void> {
+    await this.store.set(
+      {
+        type: "value",
+        callHash,
+      },
+      payload,
+    );
+  }
+
+  public async addPendingReturns(
+    callHash: string,
+    newReturn: PendingReturn,
+  ): Promise<boolean> {
+    const memKey: MemKey = {
+      type: "pending_returns",
+      callHash,
+    };
+    let shouldSchedule = false;
+    await this.withCas(async () => {
+      shouldSchedule = false;
+      const existingEncoded = await this.store.get(memKey);
+      if (!existingEncoded) {
+        const newReturns = new PendingReturns(Math.floor(Date.now() / 1000), [
+          newReturn,
+        ]);
+        shouldSchedule = true;
+        return await this.store.setNewValue(memKey, newReturns.encode());
+      }
+      const pendingReturns = PendingReturns.decode(existingEncoded);
+      shouldSchedule = [...pendingReturns.encodedReturns].some((it) =>
+        TaggedTuple.decodeFromString(PendingReturn, it).isRepeatedCall(
+          newReturn,
+        ),
+      );
+      const newReturns = new PendingReturns(
+        pendingReturns.scheduledAt,
+        pendingReturns.encodedReturns
+          .union(new Set([TaggedTuple.encodeToString(newReturn)]))
+          .values()
+          .map((it) => TaggedTuple.decodeFromString(PendingReturn, it)),
+      );
+      return this.store.compareAndSet(
+        memKey,
+        newReturns.encode(),
+        existingEncoded,
+      );
+    });
+    return shouldSchedule;
+  }
+
+  public async withPendingReturnsRemove(
+    callHash: string,
+    f: (returns: ReadonlySet<PendingReturn>) => Promise<void>,
+  ) {
+    const memKey: MemKey = {
+      type: "pending_returns",
+      callHash,
+    };
+    const handled = new Set<PendingReturn>();
+    return this.withCas(async () => {
+      const pendingEncoded = await this.store.get(memKey);
+      if (!pendingEncoded) {
+        return true;
+      }
+      const toHandle = new Set(
+        PendingReturns.decode(pendingEncoded)
+          .encodedReturns.difference(handled)
+          .values()
+          .map((it) => TaggedTuple.decodeFromString(PendingReturn, it)),
+      );
+      await f(toHandle);
+      for (const it of toHandle) {
+        handled.add(it);
+      }
+      return this.store.compareAndDelete(memKey, pendingEncoded);
+    });
+  }
+
+  private async withCas(f: () => Promise<boolean>): Promise<void> {
+    for (let i = 0; i < Memory.casRetryLimit; i++) {
+      if (await f()) {
+        return;
+      }
+    }
+    throw new CasRetryLimitReachedError(Memory.casRetryLimit);
+  }
+}

package/src/symbol.ts

@@ -0,0 +1,5 @@
+export const BrrrTaskSymbol = Symbol("brrr.task");
+
+export const BrrrShutdownSymbol = Symbol("brrr.shutdown");
+
+export const BrrrTaskDoneEventSymbol = Symbol("brrr.task_done_event");