@sonamu-kit/tasks 0.0.1

package/src/database/migrations/20251212000000_1_tables.ts

@@ -0,0 +1,54 @@
+import type { Knex } from "knex";
+import { DEFAULT_SCHEMA } from "../base";
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.withSchema(DEFAULT_SCHEMA).createTable("workflow_runs", (table) => {
+    table.text("namespace_id").notNullable();
+    table.text("id").notNullable();
+    table.text("workflow_name").notNullable();
+    table.text("version");
+    table.text("status").notNullable();
+    table.text("idempotency_key");
+    table.jsonb("config").notNullable();
+    table.jsonb("context");
+    table.jsonb("input");
+    table.jsonb("output");
+    table.jsonb("error");
+    table.integer("attempts").notNullable();
+    table.text("parent_step_attempt_namespace_id");
+    table.text("parent_step_attempt_id");
+    table.text("worker_id");
+    table.timestamp("available_at", { useTz: true, precision: 3 });
+    table.timestamp("deadline_at", { useTz: true, precision: 3 });
+    table.timestamp("started_at", { useTz: true, precision: 3 });
+    table.timestamp("finished_at", { useTz: true, precision: 3 });
+    table.timestamp("created_at", { useTz: true, precision: 3 }).notNullable();
+    table.timestamp("updated_at", { useTz: true, precision: 3 }).notNullable();
+    table.primary(["namespace_id", "id"]);
+  });
+
+  await knex.schema.withSchema(DEFAULT_SCHEMA).createTable("step_attempts", (table) => {
+    table.text("namespace_id").notNullable();
+    table.text("id").notNullable();
+    table.text("workflow_run_id").notNullable();
+    table.text("step_name").notNullable();
+    table.text("kind").notNullable();
+    table.text("status").notNullable();
+    table.jsonb("config").notNullable();
+    table.jsonb("context");
+    table.jsonb("output");
+    table.jsonb("error");
+    table.text("child_workflow_run_namespace_id");
+    table.text("child_workflow_run_id");
+    table.timestamp("started_at", { useTz: true, precision: 3 });
+    table.timestamp("finished_at", { useTz: true, precision: 3 });
+    table.timestamp("created_at", { useTz: true, precision: 3 }).notNullable();
+    table.timestamp("updated_at", { useTz: true, precision: 3 }).notNullable();
+    table.primary(["namespace_id", "id"]);
+  });
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.withSchema(DEFAULT_SCHEMA).dropTable("workflow_runs");
+  await knex.schema.withSchema(DEFAULT_SCHEMA).dropTable("step_attempts");
+}

package/src/database/migrations/20251212000000_2_fk.ts

@@ -0,0 +1,46 @@
+import type { Knex } from "knex";
+import { DEFAULT_SCHEMA } from "../base";
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.withSchema(DEFAULT_SCHEMA).alterTable("step_attempts", (table) => {
+    table
+      .foreign(["namespace_id", "workflow_run_id"], "step_attempts_workflow_run_fk")
+      .references(["namespace_id", "id"])
+      .inTable(`${DEFAULT_SCHEMA}.workflow_runs`)
+      .onDelete("cascade");
+    table
+      .foreign(
+        ["child_workflow_run_namespace_id", "child_workflow_run_id"],
+        "step_attempts_child_workflow_run_fk",
+      )
+      .references(["namespace_id", "id"])
+      .inTable(`${DEFAULT_SCHEMA}.workflow_runs`)
+      .onDelete("set null");
+  });
+  await knex.schema.withSchema(DEFAULT_SCHEMA).alterTable("workflow_runs", (table) => {
+    table
+      .foreign(
+        ["parent_step_attempt_namespace_id", "parent_step_attempt_id"],
+        "workflow_runs_parent_step_attempt_fk",
+      )
+      .references(["namespace_id", "id"])
+      .inTable(`${DEFAULT_SCHEMA}.step_attempts`)
+      .onDelete("set null");
+  });
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.withSchema(DEFAULT_SCHEMA).alterTable("step_attempts", (table) => {
+    table.dropForeign(["namespace_id", "workflow_run_id"], "step_attempts_workflow_run_fk");
+    table.dropForeign(
+      ["child_workflow_run_namespace_id", "child_workflow_run_id"],
+      "step_attempts_child_workflow_run_fk",
+    );
+  });
+  await knex.schema.withSchema(DEFAULT_SCHEMA).alterTable("workflow_runs", (table) => {
+    table.dropForeign(
+      ["parent_step_attempt_namespace_id", "parent_step_attempt_id"],
+      "workflow_runs_parent_step_attempt_fk",
+    );
+  });
+}

package/src/database/migrations/20251212000000_3_indexes.ts

@@ -0,0 +1,82 @@
+import type { Knex } from "knex";
+import { DEFAULT_SCHEMA } from "../base";
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.withSchema(DEFAULT_SCHEMA).table("workflow_runs", (table) => {
+    table.index(
+      ["namespace_id", "status", "available_at", "created_at"],
+      "workflow_runs_status_available_at_created_at_idx",
+    );
+    table.index(
+      ["namespace_id", "workflow_name", "idempotency_key", "created_at"],
+      "workflow_runs_workflow_name_idempotency_key_created_at_idx",
+    );
+    table.index(
+      ["parent_step_attempt_namespace_id", "parent_step_attempt_id"],
+      "workflow_runs_parent_step_idx",
+    );
+    table.index(["namespace_id", "created_at"], "workflow_runs_created_at_desc_idx");
+    table.index(
+      ["namespace_id", "status", "created_at"],
+      "workflow_runs_status_created_at_desc_idx",
+    );
+    table.index(
+      ["namespace_id", "workflow_name", "status", "created_at"],
+      "workflow_runs_workflow_name_status_created_at_desc_idx",
+    );
+  });
+  await knex.schema.withSchema(DEFAULT_SCHEMA).table("step_attempts", (table) => {
+    table.index(
+      ["namespace_id", "workflow_run_id", "created_at"],
+      "step_attempts_workflow_run_created_at_idx",
+    );
+    table.index(
+      ["namespace_id", "workflow_run_id", "step_name", "created_at"],
+      "step_attempts_workflow_run_step_name_created_at_idx",
+    );
+    table.index(
+      ["child_workflow_run_namespace_id", "child_workflow_run_id"],
+      "step_attempts_child_workflow_run_idx",
+    );
+  });
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.withSchema(DEFAULT_SCHEMA).table("workflow_runs", (table) => {
+    table.dropIndex(
+      ["namespace_id", "status", "available_at", "created_at"],
+      "workflow_runs_status_available_at_created_at_idx",
+    );
+    table.dropIndex(
+      ["namespace_id", "workflow_name", "idempotency_key", "created_at"],
+      "workflow_runs_workflow_name_idempotency_key_created_at_idx",
+    );
+    table.dropIndex(
+      ["parent_step_attempt_namespace_id", "parent_step_attempt_id"],
+      "workflow_runs_parent_step_idx",
+    );
+    table.dropIndex(["namespace_id", "created_at"], "workflow_runs_created_at_desc_idx");
+    table.dropIndex(
+      ["namespace_id", "status", "created_at"],
+      "workflow_runs_status_created_at_desc_idx",
+    );
+    table.dropIndex(
+      ["namespace_id", "workflow_name", "status", "created_at"],
+      "workflow_runs_workflow_name_status_created_at_desc_idx",
+    );
+  });
+  await knex.schema.withSchema(DEFAULT_SCHEMA).table("step_attempts", (table) => {
+    table.dropIndex(
+      ["namespace_id", "workflow_run_id", "created_at"],
+      "step_attempts_workflow_run_created_at_idx",
+    );
+    table.dropIndex(
+      ["namespace_id", "workflow_run_id", "step_name", "created_at"],
+      "step_attempts_workflow_run_step_name_created_at_idx",
+    );
+    table.dropIndex(
+      ["child_workflow_run_namespace_id", "child_workflow_run_id"],
+      "step_attempts_child_workflow_run_idx",
+    );
+  });
+}

package/src/database/pubsub.test.ts

@@ -0,0 +1,92 @@
+import knex, { type Knex } from "knex";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type { Result } from "../core/result";
+import { KNEX_GLOBAL_CONFIG } from "../testing/connection";
+import { type OnSubscribed, PostgresPubSub } from "./pubsub";
+
+describe("PostgresPubSub", () => {
+  let knexInstance: Knex;
+
+  beforeEach(async () => {
+    knexInstance = knex(KNEX_GLOBAL_CONFIG);
+  });
+
+  afterEach(async () => {
+    await knexInstance.destroy();
+  });
+
+  it("should create a new pubsub and connect to the database", async () => {
+    const pubsub = await PostgresPubSub.create(knexInstance);
+    expect(pubsub.destroyed).toBe(false);
+  });
+
+  it("should destroy the pubsub and close the connection", async () => {
+    const pubsub = await PostgresPubSub.create(knexInstance);
+    expect(pubsub.destroyed).toBe(false);
+    await pubsub.destroy();
+    expect(pubsub.destroyed).toBe(true);
+  });
+
+  it("should not add the same pubsub multiple times", async () => {
+    const pubsub = await PostgresPubSub.create(knexInstance);
+    const results: Result<string | null>[] = [];
+    const callback: OnSubscribed = async (result) => {
+      results.push(result);
+    };
+
+    pubsub.listenEvent("test", callback);
+    pubsub.listenEvent("test", callback);
+
+    await knexInstance.raw("NOTIFY test, 'test'");
+    await sleep(100);
+
+    expect(results.length).toBe(1);
+    expect(results[0]).toStrictEqual({ ok: true, value: "test" });
+  });
+
+  it("should route notifications to the correct pubsubs by channel", async () => {
+    const pubsub = await PostgresPubSub.create(knexInstance);
+    const results1: Result<string | null>[] = [];
+    const results2: Result<string | null>[] = [];
+
+    pubsub.listenEvent("test1", (result) => {
+      results1.push(result);
+    });
+    pubsub.listenEvent("test2", (result) => {
+      results2.push(result);
+    });
+
+    await knexInstance.raw("NOTIFY test1, '!!!'");
+    await sleep(100);
+
+    expect(results1.length).toBe(1);
+    expect(results1[0]).toStrictEqual({ ok: true, value: "!!!" });
+    expect(results2.length).toBe(0);
+
+    await knexInstance.raw("NOTIFY test2, '###'");
+    await sleep(100);
+
+    expect(results1.length).toBe(1);
+    expect(results2.length).toBe(1);
+    expect(results2[0]).toStrictEqual({ ok: true, value: "###" });
+  });
+
+  it("should payload be null if the payload is empty string", async () => {
+    const pubsub = await PostgresPubSub.create(knexInstance);
+    const results: Result<string | null>[] = [];
+    const callback: OnSubscribed = async (result) => {
+      results.push(result);
+    };
+
+    pubsub.listenEvent("test", callback);
+    await knexInstance.raw(`NOTIFY test`);
+    await sleep(100);
+
+    expect(results.length).toBe(1);
+    expect(results[0]).toStrictEqual({ ok: true, value: null });
+  });
+});
+
+function sleep(ms: number) {
+  return new Promise<void>((resolve) => setTimeout(resolve, ms));
+}

package/src/database/pubsub.ts

@@ -0,0 +1,92 @@
+import assert from "assert";
+import type { Knex } from "knex";
+import { err, ok, type Result } from "../core/result";
+
+export type OnSubscribed = (result: Result<string | null>) => void | Promise<void>;
+
+export class PostgresPubSub {
+  private _destroyed = false;
+  private _onClosed: () => Promise<void>;
+  private _listeners = new Map<string, Set<OnSubscribed>>();
+
+  // biome-ignore lint/suspicious/noExplicitAny: Knex exposes a connection as any
+  private _connection: any | null = null;
+
+  private constructor(private readonly knex: Knex) {
+    // Re-connect to the database when the connection is closed and not destroyed manually
+    this._onClosed = (async () => {
+      if (this._destroyed) {
+        return;
+      }
+
+      await this.connect();
+    }).bind(this);
+  }
+
+  get destroyed() {
+    return this._destroyed;
+  }
+
+  // acquire new raw connection and set up listeners
+  async connect() {
+    const connection = await this.knex.client.acquireRawConnection();
+    connection.on("close", this._onClosed);
+    connection.on(
+      "notification",
+      async ({ channel, payload: rawPayload }: { channel: string; payload: unknown }) => {
+        const payload =
+          typeof rawPayload === "string" && rawPayload.length !== 0 ? rawPayload : null;
+        const listeners = this._listeners.get(channel);
+        if (!listeners) {
+          return;
+        }
+
+        const result = ok(payload);
+        await Promise.allSettled(
+          Array.from(listeners.values()).map((listener) => Promise.resolve(listener(result))),
+        );
+      },
+    );
+    connection.on("error", async (error: Error) => {
+      const result = err(error);
+      await Promise.allSettled(
+        Array.from(this._listeners.values())
+          .flatMap((listeners) => Array.from(listeners))
+          .map((listener) => Promise.resolve(listener(result))),
+      );
+    });
+
+    for (const channel of this._listeners.keys()) {
+      connection.query(`LISTEN ${channel}`);
+    }
+
+    this._connection = connection;
+  }
+
+  // destroy the listener and close the connection, do not destroy the knex connection
+  async destroy() {
+    this._destroyed = true;
+    this._connection.off("close", this._onClosed);
+    await this.knex.client.destroyRawConnection(this._connection);
+  }
+
+  // create a new listener and connect to the database
+  static async create(knex: Knex) {
+    const listener = new PostgresPubSub(knex);
+    await listener.connect();
+    return listener;
+  }
+
+  // add a new listener to the channel
+  listenEvent(channel: string, callback: OnSubscribed) {
+    if (!this._listeners.has(channel)) {
+      this._connection?.query(`LISTEN ${channel}`);
+      this._listeners.set(channel, new Set<OnSubscribed>().add(callback));
+      return;
+    }
+
+    const listeners = this._listeners.get(channel);
+    assert(listeners, "Listener channel not found");
+    listeners.add(callback);
+  }
+}