swarm-mail 0.1.0

package/src/streams/effect/lock.ts

@@ -0,0 +1,399 @@
+/**
+ * DurableLock - Distributed Mutual Exclusion via CAS
+ *
+ * Uses seq=0 CAS (Compare-And-Swap) pattern for distributed locking.
+ * Provides acquire/release/withLock methods with TTL expiry and contention handling.
+ *
+ * Based on Kyle Matthews' pattern from Agent Mail.
+ *
+ * @example
+ * ```typescript
+ * // Using Effect API
+ * const program = Effect.gen(function* (_) {
+ *   const lock = yield* _(acquireLock("my-resource", { ttlSeconds: 30 }))
+ *   try {
+ *     // Critical section
+ *   } finally {
+ *     yield* _(lock.release())
+ *   }
+ * }).pipe(Effect.provide(DurableLockLive))
+ *
+ * // Or use withLock helper
+ * const program = Effect.gen(function* (_) {
+ *   const lock = yield* _(DurableLock)
+ *   yield* _(lock.withLock("my-resource", Effect.succeed(42)))
+ * }).pipe(Effect.provide(DurableLockLive))
+ * ```
+ */
+
+import { Context, Effect, Layer, Schedule } from "effect";
+import { getDatabase } from "../index";
+import { randomUUID } from "node:crypto";
+
+// ============================================================================
+// Types & Errors
+// ============================================================================
+
+/**
+ * Configuration for lock acquisition
+ */
+export interface LockConfig {
+  /**
+   * Time-to-live in seconds before lock auto-expires
+   * @default 30
+   */
+  ttlSeconds?: number;
+
+  /**
+   * Maximum retry attempts when lock is contended
+   * @default 10
+   */
+  maxRetries?: number;
+
+  /**
+   * Base delay in milliseconds for exponential backoff
+   * @default 50
+   */
+  baseDelayMs?: number;
+
+  /**
+   * Project path for database instance
+   */
+  projectPath?: string;
+
+  /**
+   * Custom holder ID (defaults to generated UUID)
+   */
+  holderId?: string;
+}
+
+/**
+ * Handle representing an acquired lock
+ */
+export interface LockHandle {
+  /** Resource being locked */
+  readonly resource: string;
+  /** Holder ID who owns the lock */
+  readonly holder: string;
+  /** Sequence number when acquired */
+  readonly seq: number;
+  /** Timestamp when lock was acquired */
+  readonly acquiredAt: number;
+  /** Timestamp when lock expires */
+  readonly expiresAt: number;
+  /** Release the lock */
+  readonly release: () => Effect.Effect<void, LockError>;
+}
+
+/**
+ * Lock errors
+ */
+export type LockError =
+  | { readonly _tag: "LockTimeout"; readonly resource: string }
+  | { readonly _tag: "LockContention"; readonly resource: string }
+  | {
+      readonly _tag: "LockNotHeld";
+      readonly resource: string;
+      readonly holder: string;
+    }
+  | { readonly _tag: "DatabaseError"; readonly error: Error };
+
+// ============================================================================
+// Service Definition
+// ============================================================================
+
+/**
+ * DurableLock service for distributed mutual exclusion
+ */
+export class DurableLock extends Context.Tag("DurableLock")<
+  DurableLock,
+  {
+    /**
+     * Acquire a lock on a resource
+     *
+     * Uses CAS (seq=0) pattern:
+     * - INSERT if no lock exists
+     * - UPDATE if expired or we already hold it
+     *
+     * Retries with exponential backoff on contention.
+     */
+    readonly acquire: (
+      resource: string,
+      config?: LockConfig,
+    ) => Effect.Effect<LockHandle, LockError>;
+
+    /**
+     * Release a lock
+     *
+     * Only succeeds if the holder matches.
+     */
+    readonly release: (
+      resource: string,
+      holder: string,
+      projectPath?: string,
+    ) => Effect.Effect<void, LockError>;
+
+    /**
+     * Execute an effect with automatic lock acquisition and release
+     *
+     * Guarantees lock release even on error (Effect.ensuring).
+     */
+    readonly withLock: <A, E, R>(
+      resource: string,
+      effect: Effect.Effect<A, E, R>,
+      config?: LockConfig,
+    ) => Effect.Effect<A, E | LockError, R | DurableLock>;
+  }
+>() {}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+/**
+ * Try to acquire lock once via CAS pattern
+ *
+ * Returns sequence number on success, null on contention
+ */
+async function tryAcquire(
+  resource: string,
+  holder: string,
+  expiresAt: number,
+  projectPath?: string,
+): Promise<{ seq: number; acquiredAt: number } | null> {
+  const db = await getDatabase(projectPath);
+  const now = Date.now();
+
+  try {
+    // Try INSERT first (no existing lock)
+    const insertResult = await db.query<{ seq: number }>(
+      `INSERT INTO locks (resource, holder, seq, acquired_at, expires_at)
+       VALUES ($1, $2, 0, $3, $4)
+       RETURNING seq`,
+      [resource, holder, now, expiresAt],
+    );
+
+    if (insertResult.rows.length > 0) {
+      return { seq: insertResult.rows[0]!.seq, acquiredAt: now };
+    }
+  } catch {
+    // INSERT failed - lock exists, try UPDATE
+    const updateResult = await db.query<{ seq: number }>(
+      `UPDATE locks
+       SET holder = $2, seq = seq + 1, acquired_at = $3, expires_at = $4
+       WHERE resource = $1
+         AND (expires_at < $3 OR holder = $2)
+       RETURNING seq`,
+      [resource, holder, now, expiresAt],
+    );
+
+    if (updateResult.rows.length > 0) {
+      return { seq: updateResult.rows[0]!.seq, acquiredAt: now };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Release a lock by holder
+ */
+async function tryRelease(
+  resource: string,
+  holder: string,
+  projectPath?: string,
+): Promise<boolean> {
+  const db = await getDatabase(projectPath);
+
+  const result = await db.query<{ holder: string }>(
+    `DELETE FROM locks
+     WHERE resource = $1 AND holder = $2
+     RETURNING holder`,
+    [resource, holder],
+  );
+
+  return result.rows.length > 0;
+}
+
+/**
+ * Acquire implementation
+ */
+function acquireImpl(
+  resource: string,
+  config?: LockConfig,
+): Effect.Effect<LockHandle, LockError> {
+  return Effect.gen(function* (_) {
+    const {
+      ttlSeconds = 30,
+      maxRetries = 10,
+      baseDelayMs = 50,
+      projectPath,
+      holderId,
+    } = config || {};
+
+    const holder = holderId || randomUUID();
+    const expiresAt = Date.now() + ttlSeconds * 1000;
+
+    // Retry schedule: exponential backoff with max retries
+    const retrySchedule = Schedule.exponential(baseDelayMs).pipe(
+      Schedule.compose(Schedule.recurs(maxRetries)),
+    );
+
+    // Attempt acquisition with retries
+    const result = yield* _(
+      Effect.tryPromise({
+        try: () => tryAcquire(resource, holder, expiresAt, projectPath),
+        catch: (error) => ({
+          _tag: "DatabaseError" as const,
+          error: error as Error,
+        }),
+      }).pipe(
+        Effect.flatMap((result) =>
+          result
+            ? Effect.succeed(result)
+            : Effect.fail({
+                _tag: "LockContention" as const,
+                resource,
+              }),
+        ),
+        Effect.retry(retrySchedule),
+        Effect.catchTag("LockContention", () =>
+          Effect.fail({
+            _tag: "LockTimeout" as const,
+            resource,
+          }),
+        ),
+      ),
+    );
+
+    const { seq, acquiredAt } = result;
+
+    // Create lock handle with release method
+    const lockHandle: LockHandle = {
+      resource,
+      holder,
+      seq,
+      acquiredAt,
+      expiresAt,
+      release: () => releaseImpl(resource, holder, projectPath),
+    };
+
+    return lockHandle;
+  });
+}
+
+/**
+ * Release implementation
+ */
+function releaseImpl(
+  resource: string,
+  holder: string,
+  projectPath?: string,
+): Effect.Effect<void, LockError> {
+  return Effect.gen(function* (_) {
+    const released = yield* _(
+      Effect.tryPromise({
+        try: () => tryRelease(resource, holder, projectPath),
+        catch: (error) => ({
+          _tag: "DatabaseError" as const,
+          error: error as Error,
+        }),
+      }),
+    );
+
+    if (!released) {
+      yield* _(
+        Effect.fail({
+          _tag: "LockNotHeld" as const,
+          resource,
+          holder,
+        }),
+      );
+    }
+  });
+}
+
+/**
+ * WithLock implementation
+ */
+function withLockImpl<A, E, R>(
+  resource: string,
+  effect: Effect.Effect<A, E, R>,
+  config?: LockConfig,
+): Effect.Effect<A, E | LockError, R | DurableLock> {
+  return Effect.gen(function* (_) {
+    const lock = yield* _(DurableLock);
+    const lockHandle = yield* _(lock.acquire(resource, config));
+
+    // Execute effect with guaranteed release
+    const result = yield* _(
+      effect.pipe(
+        Effect.ensuring(
+          lockHandle.release().pipe(
+            Effect.catchAll(() => Effect.void), // Swallow release errors in cleanup
+          ),
+        ),
+      ),
+    );
+
+    return result;
+  });
+}
+
+// ============================================================================
+// Layer
+// ============================================================================
+
+/**
+ * Live implementation of DurableLock service
+ */
+export const DurableLockLive = Layer.succeed(DurableLock, {
+  acquire: acquireImpl,
+  release: releaseImpl,
+  withLock: withLockImpl,
+});
+
+// ============================================================================
+// Convenience Functions
+// ============================================================================
+
+/**
+ * Acquire a lock (convenience Effect wrapper)
+ */
+export function acquireLock(
+  resource: string,
+  config?: LockConfig,
+): Effect.Effect<LockHandle, LockError, DurableLock> {
+  return Effect.gen(function* (_) {
+    const service = yield* _(DurableLock);
+    return yield* _(service.acquire(resource, config));
+  });
+}
+
+/**
+ * Release a lock (convenience Effect wrapper)
+ */
+export function releaseLock(
+  resource: string,
+  holder: string,
+  projectPath?: string,
+): Effect.Effect<void, LockError, DurableLock> {
+  return Effect.gen(function* (_) {
+    const service = yield* _(DurableLock);
+    return yield* _(service.release(resource, holder, projectPath));
+  });
+}
+
+/**
+ * Execute with lock (convenience Effect wrapper)
+ */
+export function withLock<A, E, R>(
+  resource: string,
+  effect: Effect.Effect<A, E, R>,
+  config?: LockConfig,
+): Effect.Effect<A, E | LockError, R | DurableLock> {
+  return Effect.gen(function* (_) {
+    const service = yield* _(DurableLock);
+    return yield* _(service.withLock(resource, effect, config));
+  });
+}

package/src/streams/effect/mailbox.test.ts

@@ -0,0 +1,260 @@
+/**
+ * Tests for DurableMailbox service
+ */
+import { describe, it, expect, beforeEach, afterAll } from "vitest";
+import { Effect, Layer } from "effect";
+import { DurableMailbox, DurableMailboxLive, type Envelope } from "./mailbox";
+import { DurableCursor, DurableCursorLive } from "./cursor";
+import { resetDatabase, closeDatabase } from "../index";
+
+describe("DurableMailbox", () => {
+  const projectPath = "/tmp/mailbox-test";
+  const projectKey = "/test/project";
+
+  beforeEach(async () => {
+    await resetDatabase(projectPath);
+  });
+
+  afterAll(async () => {
+    await closeDatabase(projectPath);
+  });
+
+  describe("send/receive cycle", () => {
+    it("should send and receive a message", async () => {
+      const program = Effect.gen(function* () {
+        const mailboxService = yield* DurableMailbox;
+
+        // Create mailboxes for two agents
+        const senderMailbox = yield* mailboxService.create({
+          agent: "sender",
+          projectKey,
+          projectPath,
+        });
+
+        const receiverMailbox = yield* mailboxService.create({
+          agent: "receiver",
+          projectKey,
+          projectPath,
+        });
+
+        // Send message
+        yield* senderMailbox.send("receiver", {
+          payload: { task: "process-data", value: 42 },
+        });
+
+        // Receive message using Effect.promise for async iteration
+        const messages = yield* Effect.promise(async () => {
+          const results: Envelope<{ task: string; value: number }>[] = [];
+          for await (const envelope of receiverMailbox.receive<{
+            task: string;
+            value: number;
+          }>()) {
+            results.push(envelope);
+            await Effect.runPromise(envelope.commit());
+            break;
+          }
+          return results;
+        });
+
+        return messages;
+      });
+
+      const layer = Layer.provideMerge(
+        DurableMailboxLive,
+        Layer.succeed(DurableCursor, DurableCursorLive),
+      );
+      const messages = await Effect.runPromise(
+        program.pipe(Effect.provide(layer)),
+      );
+
+      expect(messages).toHaveLength(1);
+      expect(messages[0]?.payload).toEqual({
+        task: "process-data",
+        value: 42,
+      });
+      expect(messages[0]?.sender).toBe("sender");
+    });
+
+    it("should support replyTo pattern", async () => {
+      const program = Effect.gen(function* () {
+        const mailboxService = yield* DurableMailbox;
+
+        const senderMailbox = yield* mailboxService.create({
+          agent: "sender",
+          projectKey,
+          projectPath,
+        });
+
+        const receiverMailbox = yield* mailboxService.create({
+          agent: "receiver",
+          projectKey,
+          projectPath,
+        });
+
+        // Send message with replyTo
+        yield* senderMailbox.send("receiver", {
+          payload: { request: "ping" },
+          replyTo: "deferred:test-123",
+        });
+
+        // Receive and check replyTo
+        yield* Effect.promise(async () => {
+          for await (const envelope of receiverMailbox.receive()) {
+            expect(envelope.replyTo).toBe("deferred:test-123");
+            await Effect.runPromise(envelope.commit());
+            break;
+          }
+        });
+      });
+
+      const layer = Layer.provideMerge(
+        DurableMailboxLive,
+        Layer.succeed(DurableCursor, DurableCursorLive),
+      );
+      await Effect.runPromise(program.pipe(Effect.provide(layer)));
+    });
+
+    it("should filter messages by recipient", async () => {
+      const program = Effect.gen(function* () {
+        const mailboxService = yield* DurableMailbox;
+
+        const senderMailbox = yield* mailboxService.create({
+          agent: "sender",
+          projectKey,
+          projectPath,
+        });
+
+        const agent1Mailbox = yield* mailboxService.create({
+          agent: "agent1",
+          projectKey,
+          projectPath,
+        });
+
+        const agent2Mailbox = yield* mailboxService.create({
+          agent: "agent2",
+          projectKey,
+          projectPath,
+        });
+
+        // Send to agent1 only
+        yield* senderMailbox.send("agent1", {
+          payload: { for: "agent1" },
+        });
+
+        // Send to agent2 only
+        yield* senderMailbox.send("agent2", {
+          payload: { for: "agent2" },
+        });
+
+        // Agent1 should only see their message
+        const agent1Messages = yield* Effect.promise(async () => {
+          const results: Envelope<{ for: string }>[] = [];
+          for await (const envelope of agent1Mailbox.receive<{
+            for: string;
+          }>()) {
+            results.push(envelope);
+            await Effect.runPromise(envelope.commit());
+            break;
+          }
+          return results;
+        });
+
+        // Agent2 should only see their message
+        const agent2Messages = yield* Effect.promise(async () => {
+          const results: Envelope<{ for: string }>[] = [];
+          for await (const envelope of agent2Mailbox.receive<{
+            for: string;
+          }>()) {
+            results.push(envelope);
+            await Effect.runPromise(envelope.commit());
+            break;
+          }
+          return results;
+        });
+
+        return { agent1Messages, agent2Messages };
+      });
+
+      const layer = Layer.provideMerge(
+        DurableMailboxLive,
+        Layer.succeed(DurableCursor, DurableCursorLive),
+      );
+      const { agent1Messages, agent2Messages } = await Effect.runPromise(
+        program.pipe(Effect.provide(layer)),
+      );
+
+      expect(agent1Messages).toHaveLength(1);
+      expect(agent1Messages[0]?.payload.for).toBe("agent1");
+
+      expect(agent2Messages).toHaveLength(1);
+      expect(agent2Messages[0]?.payload.for).toBe("agent2");
+    });
+  });
+
+  describe("peek", () => {
+    it("should return next message without consuming", async () => {
+      const program = Effect.gen(function* () {
+        const mailboxService = yield* DurableMailbox;
+
+        const senderMailbox = yield* mailboxService.create({
+          agent: "sender",
+          projectKey,
+          projectPath,
+        });
+
+        const receiverMailbox = yield* mailboxService.create({
+          agent: "receiver",
+          projectKey,
+          projectPath,
+        });
+
+        // Send message
+        yield* senderMailbox.send("receiver", {
+          payload: { value: 123 },
+        });
+
+        // Peek (doesn't consume)
+        const peeked = yield* receiverMailbox.peek<{ value: number }>();
+        expect(peeked?.payload.value).toBe(123);
+
+        // Receive (should still be there)
+        yield* Effect.promise(async () => {
+          for await (const envelope of receiverMailbox.receive<{
+            value: number;
+          }>()) {
+            expect(envelope.payload.value).toBe(123);
+            await Effect.runPromise(envelope.commit());
+            break;
+          }
+        });
+      });
+
+      const layer = Layer.provideMerge(
+        DurableMailboxLive,
+        Layer.succeed(DurableCursor, DurableCursorLive),
+      );
+      await Effect.runPromise(program.pipe(Effect.provide(layer)));
+    });
+
+    it("should return null when no messages", async () => {
+      const program = Effect.gen(function* () {
+        const mailboxService = yield* DurableMailbox;
+
+        const mailbox = yield* mailboxService.create({
+          agent: "receiver",
+          projectKey,
+          projectPath,
+        });
+
+        const peeked = yield* mailbox.peek();
+        expect(peeked).toBeNull();
+      });
+
+      const layer = Layer.provideMerge(
+        DurableMailboxLive,
+        Layer.succeed(DurableCursor, DurableCursorLive),
+      );
+      await Effect.runPromise(program.pipe(Effect.provide(layer)));
+    });
+  });
+});