@anterior/brrr 0.1.1

package/src/app.ts

@@ -0,0 +1,201 @@
+import {
+  type Connection,
+  Defer,
+  type DeferredCall,
+  type Request,
+  type Response,
+} from "./connection.ts";
+import type { Codec } from "./codec.ts";
+import { NotFoundError, TaskNotFoundError } from "./errors.ts";
+import { BrrrTaskSymbol } from "./symbol.ts";
+
+export type Task<A extends unknown[] = any[], R = any> = ((
+  ...args: [ActiveWorker, ...A]
+) => R) & {
+  readonly [BrrrTaskSymbol]?: (...args: A) => R;
+};
+
+export type StripLeadingActiveWorker<A extends unknown[]> = A extends [
+  ActiveWorker,
+  ...infer Rest,
+]
+  ? Rest
+  : A;
+
+export type NoAppTask<A extends unknown[], R> = (
+  ...args: StripLeadingActiveWorker<A>
+) => Promise<R>;
+
+export type Handlers = Readonly<Record<string, Task>>;
+
+export type TaskIdentifier<A extends unknown[], R> =
+  | ((...args: A) => R | Promise<R>)
+  | string;
+
+export function taskIdentifierToName(
+  identifier: TaskIdentifier<any[], any>,
+  handlers: Handlers,
+): string {
+  if (typeof identifier === "string") {
+    return identifier;
+  }
+  for (const [name, handler] of Object.entries(handlers)) {
+    if (handler[BrrrTaskSymbol] === identifier || handler === identifier) {
+      return name;
+    }
+  }
+  throw new TaskNotFoundError(identifier.name);
+}
+
+export function taskFn<A extends unknown[], R>(
+  fn: (...args: A) => R,
+): Task<A, R> {
+  const task: Task<A, R> = (_: ActiveWorker, ...args: A): R => fn(...args);
+  return Object.defineProperty(task, BrrrTaskSymbol, {
+    value: fn satisfies Task<A, R>[typeof BrrrTaskSymbol],
+    writable: false,
+    configurable: false,
+  });
+}
+
+export class AppConsumer {
+  public readonly codec: Codec;
+  public readonly connection: Connection;
+  public readonly handlers: Handlers;
+
+  public constructor(
+    codec: Codec,
+    connection: Connection,
+    handlers: Handlers = {},
+  ) {
+    this.codec = codec;
+    this.connection = connection;
+    this.handlers = handlers;
+  }
+
+  public schedule<A extends unknown[], R>(
+    taskIdentifier: TaskIdentifier<A, R>,
+    topic: string,
+  ): NoAppTask<A, void> {
+    const taskName = taskIdentifierToName(taskIdentifier, this.handlers);
+    return async (...args: StripLeadingActiveWorker<A>) => {
+      const call = await this.codec.encodeCall(taskName, args);
+      await this.connection.scheduleRaw(topic, call);
+    };
+  }
+
+  public read<A extends unknown[], R>(
+    taskIdentifier: TaskIdentifier<A, R>,
+  ): NoAppTask<A, R> {
+    return async (...args: StripLeadingActiveWorker<A>) => {
+      const taskName = taskIdentifierToName(taskIdentifier, this.handlers);
+      const call = await this.codec.encodeCall(taskName, args);
+      const payload = await this.connection.memory.getValue(call.callHash);
+      if (!payload) {
+        throw new NotFoundError({
+          type: "value",
+          callHash: call.callHash,
+        });
+      }
+      return this.codec.decodeReturn(taskName, payload) as R;
+    };
+  }
+}
+
+export class AppWorker extends AppConsumer {
+  public readonly handle = async (
+    request: Request,
+    connection: Connection,
+  ): Promise<Response | Defer> => {
+    const handler = this.handlers[request.call.taskName];
+    if (!handler) {
+      throw new TaskNotFoundError(request.call.taskName);
+    }
+    try {
+      const activeWorker = new ActiveWorker(
+        connection,
+        this.codec,
+        this.handlers,
+      );
+      const payload = await this.codec.invokeTask(request.call, (...args) => {
+        return handler(activeWorker, ...args);
+      });
+      return { payload };
+    } catch (err) {
+      if (err instanceof Defer) {
+        return err;
+      }
+      throw err;
+    }
+  };
+}
+
+export class ActiveWorker {
+  private readonly connection: Connection;
+  private readonly codec: Codec;
+  private readonly handlers: Handlers;
+
+  public constructor(connection: Connection, codec: Codec, handlers: Handlers) {
+    this.connection = connection;
+    this.codec = codec;
+    this.handlers = handlers;
+  }
+
+  public call<A extends unknown[], R>(
+    taskIdentifier: TaskIdentifier<A, R>,
+    topic?: string | undefined,
+  ): NoAppTask<A, R> {
+    const taskName = taskIdentifierToName(taskIdentifier, this.handlers);
+    return async (...args: StripLeadingActiveWorker<A>): Promise<R> => {
+      const call = await this.codec.encodeCall(taskName, args);
+      const payload = await this.connection.memory.getValue(call.callHash);
+      if (!payload) {
+        throw new Defer({ topic, call });
+      }
+      return this.codec.decodeReturn(taskName, payload) as R;
+    };
+  }
+
+  public async gather<T1>(t1: T1): Promise<[Awaited<T1>]>;
+  public async gather<T1, T2>(
+    t1: T1,
+    t2: T2,
+  ): Promise<[Awaited<T1>, Awaited<T2>]>;
+  public async gather<T1, T2, T3>(
+    t1: T1,
+    t2: T2,
+    t3: T3,
+  ): Promise<[Awaited<T1>, Awaited<T2>, Awaited<T3>]>;
+  public async gather<T1, T2, T3, T4>(
+    t1: T1,
+    t2: T2,
+    t3: T3,
+    t4: T4,
+  ): Promise<[Awaited<T1>, Awaited<T2>, Awaited<T3>, Awaited<T4>]>;
+  public async gather<T1, T2, T3, T4, T5>(
+    t1: T1,
+    t2: T2,
+    t3: T3,
+    t4: T4,
+    t5: T5,
+  ): Promise<[Awaited<T1>, Awaited<T2>, Awaited<T3>, Awaited<T4>, Awaited<T5>]>;
+  public async gather<T>(...promises: Promise<T>[]): Promise<Awaited<T>[]>;
+  public async gather<T>(...promises: Promise<T>[]): Promise<Awaited<T>[]> {
+    const deferredCalls: DeferredCall[] = [];
+    const values: Awaited<T>[] = [];
+    for (const promise of promises) {
+      try {
+        values.push(await promise);
+      } catch (err) {
+        if (!(err instanceof Defer)) {
+          throw err;
+        }
+        deferredCalls.push(...err.calls);
+      }
+    }
+    if (deferredCalls.length) {
+      throw new Defer(...deferredCalls);
+    }
+    return values;
+  }
+}

package/src/backends/dynamo.test-integration.ts

@@ -0,0 +1,20 @@
+import { suite } from "node:test";
+import { Dynamo } from "./dynamo.ts";
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { storeContractTest } from "../store.test.ts";
+import { randomUUID } from "node:crypto";
+
+await suite(import.meta.filename, async () => {
+  const client = new DynamoDBClient();
+
+  await storeContractTest(async () => {
+    const dynamo = new Dynamo(client, randomUUID());
+    await dynamo.createTable();
+    return {
+      store: dynamo,
+      async [Symbol.asyncDispose]() {
+        await dynamo.deleteTable();
+      },
+    };
+  });
+});

package/src/backends/dynamo.ts

@@ -0,0 +1,184 @@
+import {
+  ConditionalCheckFailedException,
+  CreateTableCommand,
+  DeleteTableCommand,
+  type DynamoDBClient,
+  ResourceInUseException,
+} from "@aws-sdk/client-dynamodb";
+import {
+  DeleteCommand,
+  DynamoDBDocumentClient,
+  GetCommand,
+  PutCommand,
+  UpdateCommand,
+} from "@aws-sdk/lib-dynamodb";
+import type { MemKey, Store } from "../store.ts";
+import type { NativeAttributeValue } from "@aws-sdk/util-dynamodb";
+
+export class Dynamo implements Store {
+  private readonly client: DynamoDBDocumentClient;
+  private readonly tableName: string;
+
+  public constructor(dynamoDbClient: DynamoDBClient, tableName: string) {
+    this.client = DynamoDBDocumentClient.from(dynamoDbClient);
+    this.tableName = tableName;
+  }
+
+  public async has(key: MemKey): Promise<boolean> {
+    const { Item } = await this.client.send(
+      new GetCommand({
+        TableName: this.tableName,
+        Key: this.key(key),
+        ProjectionExpression: "pk",
+      }),
+    );
+    return !!Item;
+  }
+
+  public async get(key: MemKey): Promise<Uint8Array | undefined> {
+    const { Item } = await this.client.send(
+      new GetCommand({
+        TableName: this.tableName,
+        Key: this.key(key),
+      }),
+    );
+    return Item?.value;
+  }
+
+  public async set(key: MemKey, value: Uint8Array): Promise<void> {
+    await this.client.send(
+      new PutCommand({
+        TableName: this.tableName,
+        Item: {
+          ...this.key(key),
+          value,
+        },
+      }),
+    );
+  }
+
+  public async delete(key: MemKey): Promise<void> {
+    await this.client.send(
+      new DeleteCommand({
+        TableName: this.tableName,
+        Key: this.key(key),
+        ReturnValues: "ALL_OLD",
+      }),
+    );
+  }
+
+  public async setNewValue(key: MemKey, value: Uint8Array): Promise<boolean> {
+    try {
+      await this.client.send(
+        new UpdateCommand({
+          TableName: this.tableName,
+          Key: this.key(key),
+          UpdateExpression: "SET #value = :value",
+          ConditionExpression: "attribute_not_exists(#value)",
+          ExpressionAttributeNames: { "#value": "value" },
+          ExpressionAttributeValues: { ":value": value },
+        }),
+      );
+      return true;
+    } catch (err: unknown) {
+      if (err instanceof ConditionalCheckFailedException) {
+        return false;
+      }
+      throw err;
+    }
+  }
+
+  public async compareAndSet(
+    key: MemKey,
+    value: Uint8Array,
+    expected: Uint8Array,
+  ): Promise<boolean> {
+    try {
+      await this.client.send(
+        new UpdateCommand({
+          TableName: this.tableName,
+          Key: this.key(key),
+          UpdateExpression: "SET #value = :value",
+          ConditionExpression: "#value = :expected",
+          ExpressionAttributeNames: { "#value": "value" },
+          ExpressionAttributeValues: {
+            ":value": value,
+            ":expected": expected,
+          },
+        }),
+      );
+      return true;
+    } catch (err: unknown) {
+      if (err instanceof ConditionalCheckFailedException) {
+        return false;
+      }
+      throw err;
+    }
+  }
+
+  public async compareAndDelete(
+    key: MemKey,
+    expected: Uint8Array,
+  ): Promise<boolean> {
+    try {
+      await this.client.send(
+        new DeleteCommand({
+          TableName: this.tableName,
+          Key: this.key(key),
+          ConditionExpression:
+            "attribute_exists(#value) AND #value = :expected",
+          ExpressionAttributeNames: { "#value": "value" },
+          ExpressionAttributeValues: { ":expected": expected },
+        }),
+      );
+      return true;
+    } catch (err: unknown) {
+      if (err instanceof ConditionalCheckFailedException) {
+        return false;
+      }
+      throw err;
+    }
+  }
+
+  public async createTable(): Promise<void> {
+    try {
+      await this.client.send(
+        new CreateTableCommand({
+          TableName: this.tableName,
+          KeySchema: [
+            { AttributeName: "pk", KeyType: "HASH" },
+            { AttributeName: "sk", KeyType: "RANGE" },
+          ],
+          AttributeDefinitions: [
+            { AttributeName: "pk", AttributeType: "S" },
+            { AttributeName: "sk", AttributeType: "S" },
+          ],
+          ProvisionedThroughput: {
+            ReadCapacityUnits: 5,
+            WriteCapacityUnits: 5,
+          },
+        }),
+      );
+    } catch (err: unknown) {
+      if (err instanceof ResourceInUseException) {
+        return;
+      }
+      throw err;
+    }
+  }
+
+  public async deleteTable(): Promise<void> {
+    await this.client.send(
+      new DeleteTableCommand({
+        TableName: this.tableName,
+      }),
+    );
+  }
+
+  private key(key: MemKey): Record<string, NativeAttributeValue> {
+    return {
+      pk: key.callHash,
+      sk: key.type,
+    };
+  }
+}

package/src/backends/in-memory.test.ts

@@ -0,0 +1,19 @@
+import { suite, test } from "node:test";
+import { InMemoryCache, InMemoryStore } from "./in-memory.ts";
+import { cacheContractTest, storeContractTest } from "../store.test.ts";
+
+await suite(import.meta.filename, async () => {
+  await test(InMemoryStore.name, async () => {
+    await storeContractTest(async () => ({
+      store: new InMemoryStore(),
+      async [Symbol.asyncDispose]() {},
+    }));
+  });
+
+  await test(InMemoryCache.name, async () => {
+    await cacheContractTest(async () => ({
+      cache: new InMemoryCache(),
+      async [Symbol.asyncDispose]() {},
+    }));
+  });
+});

package/src/backends/in-memory.ts

@@ -0,0 +1,110 @@
+import type { Cache, MemKey, Store } from "../store.ts";
+import type { Publisher, Subscriber } from "../emitter.ts";
+import { EventEmitter } from "node:events";
+import type { Call } from "../call.ts";
+import { BrrrTaskDoneEventSymbol } from "../symbol.ts";
+
+export class InMemoryStore implements Store {
+  private store = new Map<string, Uint8Array>();
+
+  public async compareAndDelete(
+    key: MemKey,
+    expected: Uint8Array,
+  ): Promise<boolean> {
+    const keyStr = this.keyToString(key);
+    const value = this.store.get(keyStr);
+    if (!value || !this.isEqualBytes(value, expected)) {
+      return false;
+    }
+    this.store.delete(keyStr);
+    return true;
+  }
+
+  public async compareAndSet(
+    key: MemKey,
+    value: Uint8Array,
+    expected: Uint8Array,
+  ): Promise<boolean> {
+    const keyStr = this.keyToString(key);
+    const current = this.store.get(keyStr);
+    if (!current || !this.isEqualBytes(current, expected)) {
+      return false;
+    }
+    this.store.set(keyStr, value);
+    return true;
+  }
+
+  public async delete(key: MemKey): Promise<void> {
+    const keyStr = this.keyToString(key);
+    this.store.delete(keyStr);
+  }
+
+  public async get(key: MemKey): Promise<Uint8Array | undefined> {
+    const keyStr = this.keyToString(key);
+    return this.store.get(keyStr);
+  }
+
+  public async has(key: MemKey): Promise<boolean> {
+    const keyStr = this.keyToString(key);
+    return this.store.has(keyStr);
+  }
+
+  public async set(key: MemKey, value: Uint8Array): Promise<void> {
+    const keyStr = this.keyToString(key);
+    this.store.set(keyStr, value);
+  }
+
+  public async setNewValue(key: MemKey, value: Uint8Array): Promise<boolean> {
+    const keyStr = this.keyToString(key);
+    if (this.store.has(keyStr)) {
+      return false;
+    }
+    this.store.set(keyStr, value);
+    return true;
+  }
+
+  private keyToString(key: MemKey): string {
+    return `${key.type}/${key.callHash}`;
+  }
+
+  private isEqualBytes(a: Uint8Array, b: Uint8Array): boolean {
+    return a.length === b.length && a.every((it, i) => it === b[i]);
+  }
+}
+
+export class InMemoryCache implements Cache {
+  private readonly cache = new Map<string, number>();
+
+  public async incr(key: string): Promise<number> {
+    const next = (this.cache.get(key) ?? 0) + 1;
+    this.cache.set(key, next);
+    return next;
+  }
+}
+
+export class InMemoryEmitter implements Publisher, Subscriber {
+  private readonly emitter = new EventEmitter();
+  private readonly eventEmitter = new EventEmitter();
+
+  public on(topic: string, listener: (callId: string) => void): void {
+    this.emitter.on(topic, listener);
+  }
+
+  public onEventSymbol(
+    event: typeof BrrrTaskDoneEventSymbol,
+    listener: (call: Call) => void,
+  ): void {
+    this.eventEmitter.on(event, listener);
+  }
+
+  public async emit(topic: string, callId: string): Promise<void> {
+    this.emitter.emit(topic, callId);
+  }
+
+  public async emitEventSymbol(
+    event: typeof BrrrTaskDoneEventSymbol,
+    call: Call,
+  ): Promise<void> {
+    this.eventEmitter.emit(event, call);
+  }
+}

package/src/backends/redis.test-integration.ts

@@ -0,0 +1,61 @@
+import { suite, test } from "node:test";
+import { ok, strictEqual } from "node:assert/strict";
+import { env } from "node:process";
+import { createClientPool } from "redis";
+import { Redis } from "./redis.ts";
+import { cacheContractTest } from "../store.test.ts";
+
+await suite(import.meta.filename, async () => {
+  async function acquireResource() {
+    ok(env.BRRR_TEST_REDIS_URL);
+    const client = createClientPool(
+      {
+        RESP: 3,
+        url: env.BRRR_TEST_REDIS_URL,
+      },
+      {
+        cleanupDelay: 0,
+      },
+    );
+    const redis = new Redis(client);
+    await redis.connect();
+    return {
+      cache: redis,
+      async [Symbol.asyncDispose]() {
+        await redis.client.flushAll();
+        redis.destroy();
+      },
+    };
+  }
+
+  await cacheContractTest(acquireResource);
+
+  await suite("as message queue", async () => {
+    const topic = "test-topic";
+    const message = "some-message";
+
+    await test("push & pop message", async () => {
+      await using resource = await acquireResource();
+      await resource.cache.push(topic, message);
+      strictEqual(await resource.cache.pop(topic), message);
+    });
+
+    await test("FIFO", async () => {
+      await using resource = await acquireResource();
+      const messages = ["first", "second", "third"];
+      for (const message of messages) {
+        await resource.cache.push(topic, message);
+      }
+      for (const message of messages) {
+        strictEqual(await resource.cache.pop(topic), message);
+      }
+    });
+
+    await test("pop before push", async () => {
+      await using resource = await acquireResource();
+      const popped = resource.cache.pop(topic);
+      await resource.cache.push(topic, message);
+      strictEqual(await popped, message);
+    });
+  });
+});

package/src/backends/redis.ts

@@ -0,0 +1,48 @@
+import {
+  type RedisClientPoolType,
+  type RedisFunctions,
+  type RedisModules,
+  type RedisScripts,
+} from "redis";
+import type { Cache } from "../store.ts";
+
+export class Redis implements Cache {
+  public readonly client: RedisClientPoolType<
+    RedisModules,
+    RedisFunctions,
+    RedisScripts,
+    3
+  >;
+
+  public constructor(client: typeof this.client) {
+    this.client = client;
+  }
+
+  public async connect(): Promise<void> {
+    await this.client.connect();
+  }
+
+  public async push(topic: string, content: string): Promise<void> {
+    await this.client.rPush(topic, content);
+  }
+
+  public async pop(
+    topic: string,
+    timeoutMs: number = 20_000,
+  ): Promise<string | undefined> {
+    const response = await this.client.blPop(topic, timeoutMs / 1000);
+    return response?.element;
+  }
+
+  public async incr(key: string): Promise<number> {
+    return this.client.incr(key);
+  }
+
+  public destroy(): void {
+    this.client.destroy();
+  }
+
+  public async close(): Promise<void> {
+    await this.client.close();
+  }
+}

package/src/call.ts

@@ -0,0 +1,19 @@
+/**
+ * A full brrr request payload.
+ *
+ * This is a low-level brrr primitive.
+ *
+ * The memo key must be generated by the instantiator of this class, and it
+ * must be deterministic: the "same" args and kwargs must always encode to the
+ * same memo key.
+ *
+ * Using the same memo key, we store the task and its argv here so we can
+ * retrieve them in workers.
+ *
+ * <docsync>Call</docsync>
+ */
+export interface Call {
+  readonly taskName: string;
+  readonly payload: Uint8Array;
+  readonly callHash: string;
+}