effect-distributed-lock 0.0.5 → 0.0.6

package/README.md

@@ -12,6 +12,7 @@ It's like the built in `Effect.Semaphore`, but asynchronously distributed across
 - **Scope-based resource management** — permits are automatically released when the scope closes
 - **Automatic TTL refresh** — keeps permits alive while held, prevents deadlocks if holder crashes
 - **Pluggable backends** — ships with Redis (single-instance), easy to implement others
+- **Push-based waiting** — uses pub/sub for efficient notification when permits become available (optional, with polling fallback)
 - **Configurable retry policies** — control polling interval, TTL, and backing failure retry behavior
 - **Type-safe errors** — tagged errors for precise error handling
 
@@ -34,7 +35,7 @@ import Redis from "ioredis";
 import { DistributedSemaphore, RedisBacking } from "effect-distributed-lock";
 
 const redis = new Redis(process.env.REDIS_URL);
-const RedisLayer = RedisBacking.layer(redis);
+const RedisLayer = RedisBacking.layer(redis, { keyPrefix: "my-app:" });
 
 const program = Effect.gen(function* () {
   // Create a semaphore that allows 5 concurrent operations
@@ -216,7 +217,37 @@ import { RedisBacking } from "effect-distributed-lock";
 
 // Single Redis instance
 const redis = new Redis("redis://localhost:6379");
-const RedisLayer = RedisBacking.layer(redis, "my-prefix:");
+const RedisLayer = RedisBacking.layer(redis, {
+  keyPrefix: "my-prefix:",
+  pushBasedAcquireEnabled: true, // default: true
+});
+```
+
+### Configuration Options
+
+| Option                     | Type             | Default            | Description                                          |
+| -------------------------- | ---------------- | ------------------ | ---------------------------------------------------- |
+| `keyPrefix`                | `string`         | `"semaphore:"`     | Prefix for all Redis keys                            |
+| `pushBasedAcquireEnabled`  | `boolean`        | `true`             | Use pub/sub for efficient waiting (see below)        |
+| `pushStreamRetrySchedule`  | `Schedule<void>` | `Schedule.forever` | Retry schedule for pub/sub stream errors             |
+
+### Push-Based Acquisition
+
+By default, the Redis backing uses pub/sub to notify waiters when permits become available. This reduces latency and load on Redis compared to pure polling.
+
+When permits are released, a message is published to a channel. Waiters subscribe to this channel and immediately attempt to acquire when notified. The semaphore still falls back to polling as a safety net.
+
+**Trade-offs:**
+- ✅ Lower latency — waiters are notified immediately
+- ✅ Reduced Redis load — fewer polling requests
+- ⚠️ Extra connection — each waiting semaphore uses a subscriber connection
+
+To disable and use polling only:
+
+```typescript
+const RedisLayer = RedisBacking.layer(redis, {
+  pushBasedAcquireEnabled: false,
+});
 ```
 
 For multi-instance Redis deployments requiring Redlock, you'll need to implement a custom backing.
@@ -226,7 +257,7 @@ For multi-instance Redis deployments requiring Redlock, you'll need to implement
 Implement the `DistributedSemaphoreBacking` interface to use a different store:
 
 ```typescript
-import { Duration, Effect, Layer, Option } from "effect";
+import { Duration, Effect, Layer, Stream } from "effect";
 import { Backing, DistributedSemaphoreBacking } from "effect-distributed-lock";
 
 const MyCustomBacking = Layer.succeed(DistributedSemaphoreBacking, {
@@ -241,16 +272,23 @@ const MyCustomBacking = Layer.succeed(DistributedSemaphoreBacking, {
   
   getCount: (key, ttl) => 
     Effect.succeed(0), // Return number of permits currently held
+
+  // Optional: Enable push-based waiting
+  onPermitsReleased: (key) => 
+    Stream.never, // Stream that emits when permits MAY be available
 });
 ```
 
+The `onPermitsReleased` method is optional. If provided, the semaphore will use it for efficient push-based waiting instead of pure polling. The stream should emit whenever permits are released on the given key. Multiple waiters may race for permits after a notification, so `tryAcquire` is still called after each notification.
+
 ## How It Works
 
 1. **Acquire**: Atomically adds permits to a sorted set if there's room (Redis: Lua script with `ZADD`)
 2. **Keepalive**: A background fiber refreshes the TTL periodically by updating timestamps
-3. **Release**: Atomically removes permits from the sorted set (Lua script with `ZREM`)
-4. **Expiration**: Expired entries (based on TTL) are cleaned up on each operation
-5. **Crash safety**: If the holder crashes, permits expire and become available
+3. **Release**: Atomically removes permits and publishes notification to waiters (Lua script with `ZREM` + `PUBLISH`)
+4. **Waiting**: Combines polling with pub/sub notifications — waiters are notified immediately when permits are released
+5. **Expiration**: Expired entries (based on TTL) are cleaned up on each operation
+6. **Crash safety**: If the holder crashes, permits expire and become available
 
 ## License
 

package/examples/index.ts

@@ -12,7 +12,9 @@ import { DistributedSemaphore, RedisBacking } from "../src/index.ts";
 const redis = new Redis(process.env.REDIS_URL ?? "redis://localhost:6379");
 
 // Create the Redis backing layer
-const RedisLayer = RedisBacking.layer(redis, "example:");
+const RedisLayer = RedisBacking.layer(redis, {
+  keyPrefix: "example:",
+});
 
 // Example 1: Using withPermits for a critical section (mutex behavior)
 const example1 = Effect.gen(function* () {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-distributed-lock",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "A distributed semaphore library for Effect with pluggable backends",
   "license": "MIT",
   "repository": {

package/src/Backing.ts

@@ -1,4 +1,4 @@
-import { Context, Data, Duration, Effect } from "effect";
+import { Context, Data, Duration, Effect, Stream } from "effect";
 
 // =============================================================================
 // Errors
@@ -24,22 +24,12 @@ export class SemaphoreBackingError extends Data.TaggedError(
 
 /**
  * Low-level backing store interface for distributed semaphore operations.
- * Implementations handle the actual storage (Redis, etc.)
- *
- * The semaphore uses a sorted set model where:
- * - Each permit holder is stored with their acquisition timestamp as the score
- * - Expired entries are cleaned up automatically
- * - Multiple permits can be acquired atomically
  */
 export interface DistributedSemaphoreBacking {
   /**
    * Try to acquire `permits` from a semaphore with the given `limit`.
-   * Returns true if acquired, false if not enough permits available.
    *
-   * The implementation should:
-   * 1. Clean up expired entries (based on TTL)
-   * 2. Check if there's room: currentCount + permits <= limit
-   * 3. If so, add the permits with current timestamp
+   * @returns `true` if acquired, `false` if not enough permits available.
    */
   readonly tryAcquire: (
     key: string,
@@ -50,8 +40,9 @@ export interface DistributedSemaphoreBacking {
   ) => Effect.Effect<boolean, SemaphoreBackingError>;
 
   /**
-   * Release `permits` held by this holder.
-   * Returns the number of permits actually released.
+   * Release `permits` held by the given holder.
+   *
+   * @returns The number of permits actually released.
    */
   readonly release: (
     key: string,
@@ -60,8 +51,9 @@ export interface DistributedSemaphoreBacking {
   ) => Effect.Effect<number, SemaphoreBackingError>;
 
   /**
-   * Refresh the TTL on permits we hold.
-   * Returns true if refreshed, false if permits were lost.
+   * Refresh the TTL on permits held by this holder.
+   *
+   * @returns `true` if refreshed, `false` if permits were lost (e.g., expired).
    */
   readonly refresh: (
     key: string,
@@ -73,12 +65,24 @@ export interface DistributedSemaphoreBacking {
 
   /**
    * Get the number of permits currently held (in use).
-   * Available permits = limit - getCount().
    */
   readonly getCount: (
     key: string,
     ttl: Duration.Duration
   ) => Effect.Effect<number, SemaphoreBackingError>;
+
+  /**
+   * Optional: Stream of notifications when permits MAY be available.
+   *
+   * If provided, the semaphore layer uses this for efficient waiting instead
+   * of polling. The stream emits a signal whenever permits are released.
+   *
+   * Notes:
+   * - Multiple waiters may race for permits after a notification
+   * - The semaphore still calls `tryAcquire` after each notification
+   * - Implementations should handle reconnection internally (hence why the stream does not have an error type)
+   */
+  readonly onPermitsReleased?: (key: string) => Stream.Stream<void>;
 }
 
 export const DistributedSemaphoreBacking =

package/src/DistributedSemaphore.ts

@@ -3,9 +3,11 @@ import {
   Duration,
   Effect,
   Fiber,
+  Function,
   Option,
   Schedule,
   Scope,
+  Stream,
 } from "effect";
 import {
   DistributedSemaphoreBacking,
@@ -376,23 +378,75 @@ export const make = (
           identifier,
           acquiredExternally: options?.acquiredExternally,
         };
-        const maybeAcquired = yield* tryTake(permits, resolvedOptions);
-        if (Option.isNone(maybeAcquired)) {
-          return yield* new NotYetAcquiredError();
-        }
-        return maybeAcquired.value;
-      }).pipe(
-        Effect.retry({
-          while: (e) => e._tag === "NotYetAcquiredError",
-          schedule: acquireRetryPolicy,
-        }),
-        Effect.catchTag("NotYetAcquiredError", () =>
-          Effect.dieMessage(
-            "Invariant violated: `take` should never return `NotYetAcquiredError` " +
-              "since it should be caught by the retry which should retry forever until permits are acquired"
+
+        // We use a semaphore to ensure that only one acquire attempt is made at a time.
+        // With `withPermitsIfAvailable`, if both the poll-based and push-based attempts "trigger" at the same time,
+        // one will succeed and the other will simple be a no-op.
+        const acquireSemaphore = yield* Effect.makeSemaphore(1);
+
+        const pushBasedAcquireEnabled = backing.onPermitsReleased
+          ? true
+          : false;
+
+        const pollBasedAcquire = Effect.gen(function* () {
+          const maybeAcquired = yield* tryTake(permits, resolvedOptions).pipe(
+            // only apply the semaphore if push-based acquire is supported
+            pushBasedAcquireEnabled
+              ? Function.compose(
+                  acquireSemaphore.withPermitsIfAvailable(1),
+                  Effect.map(Option.flatten)
+                )
+              : Function.identity
+          );
+          if (Option.isNone(maybeAcquired)) {
+            return yield* new NotYetAcquiredError();
+          }
+          return maybeAcquired.value;
+        }).pipe(
+          Effect.retry({
+            while: (e) => e._tag === "NotYetAcquiredError",
+            schedule: acquireRetryPolicy,
+          }),
+          Effect.catchTag("NotYetAcquiredError", () =>
+            Effect.dieMessage(
+              "Invariant violated: `take` should never return `NotYetAcquiredError` " +
+                "since it should be caught by the retry which should retry forever until permits are acquired"
+            )
           )
-        )
-      );
+        );
+
+        if (!pushBasedAcquireEnabled) {
+          return yield* pollBasedAcquire;
+        }
+
+        // Push-based acquire: run both poll-based and push-based acquire in parallel, and return the first one to complete
+        const pushBasedAcquire = backing.onPermitsReleased
+          ? Effect.gen(function* () {
+              if (!backing.onPermitsReleased) {
+                // SAFETY: We know that onPermitsReleased is provided because we checked it above
+                return yield* Effect.dieMessage(
+                  "Invariant violated: `onPermitsReleased` is not provided"
+                );
+              }
+              return yield* backing.onPermitsReleased(key).pipe(
+                Stream.runFoldWhileEffect(
+                  Option.none<
+                    Fiber.Fiber<never, LockLostError | SemaphoreBackingError>
+                  >(),
+                  Option.isNone, // keep folding while we haven't acquired
+                  () =>
+                    tryTake(permits, resolvedOptions).pipe(
+                      acquireSemaphore.withPermitsIfAvailable(1),
+                      Effect.map(Option.flatten)
+                    )
+                ),
+                Effect.map(Option.getOrThrow)
+              );
+            })
+          : Effect.never;
+
+        return yield* Effect.race(pollBasedAcquire, pushBasedAcquire);
+      });
 
     // Convenience: acquire permits, run effect, release when done
     const withPermits =

package/src/RedisBacking.ts

@@ -1,4 +1,4 @@
-import { Duration, Effect, Layer } from "effect";
+import { Duration, Effect, Layer, Schedule, Stream } from "effect";
 import { Redis } from "ioredis";
 import {
   DistributedSemaphoreBacking,
@@ -54,26 +54,37 @@ end
 /**
  * Lua script for atomic release.
  *
- * Removes all permits held by this holder.
+ * Removes all permits held by this holder and optionally publishes a notification.
  *
  * Arguments:
  * - KEYS[1]: the semaphore key
+ * - KEYS[2]: the release notification channel
  * - ARGV[1]: permits to release
  * - ARGV[2]: holderId
+ * - ARGV[3]: shouldPublish (1 = publish, 0 = don't publish)
  *
  * Returns the number of permits released.
  */
 const RELEASE_SCRIPT = `
 local key = KEYS[1]
+local channel = KEYS[2]
 local permits = tonumber(ARGV[1])
 local holderId = ARGV[2]
+local shouldPublish = tonumber(ARGV[3]) == 1
 local args = {}
 
 for i = 0, permits - 1 do
   table.insert(args, holderId .. '_' .. i)
 end
 
-return redis.call('zrem', key, unpack(args))
+local released = redis.call('zrem', key, unpack(args))
+
+-- Notify waiters that permits may be available
+if released > 0 and shouldPublish then
+  redis.call('publish', channel, released)
+end
+
+return released
 `;
 
 /**
@@ -142,6 +153,33 @@ redis.call('zremrangebyscore', key, '-inf', expiredTimestamp)
 return redis.call('zcard', key)
 `;
 
+export interface RedisBackingOptions {
+  /**
+   * Prefix for all keys in Redis.
+   * @default "semaphore:"
+   */
+  readonly keyPrefix?: string;
+
+  /**
+   * Enable push-based acquisition using Redis pub/sub.
+   *
+   * When enabled, waiters subscribe to a channel and get notified immediately
+   * when permits are released, instead of polling. This reduces latency and
+   * load on Redis.
+   *
+   * Requires an additional Redis connection per waiting semaphore.
+   *
+   * @default true
+   */
+  readonly pushBasedAcquireEnabled?: boolean;
+
+  /**
+   * How often to retry the stream of notifications when permits are released.
+   * @default Schedule.forever
+   */
+  readonly pushStreamRetrySchedule?: Schedule.Schedule<void>;
+}
+
 /**
  * Create a Redis-backed distributed semaphore backing layer.
  *
@@ -151,13 +189,18 @@ return redis.call('zcard', key)
  * For multi-instance Redis, consider implementing a Redlock-based backing.
  *
  * @param redis - An ioredis client instance (single instance, not cluster)
- * @param keyPrefix - Optional prefix for all keys (default: "dsem:")
+ * @param options - Configuration options
  */
 export const layer = (
   redis: Redis,
-  keyPrefix = "semaphore:"
+  options: RedisBackingOptions = {}
 ): Layer.Layer<DistributedSemaphoreBacking> => {
+  const keyPrefix = options.keyPrefix ?? "semaphore:";
+  const pushBasedAcquireEnabled = options.pushBasedAcquireEnabled ?? true;
+  const pushStreamRetrySchedule =
+    options.pushStreamRetrySchedule ?? Schedule.forever.pipe(Schedule.asVoid);
   const prefixKey = (key: string) => `${keyPrefix}${key}`;
+  const releaseChannel = (key: string) => `${keyPrefix}${key}:released`;
 
   const tryAcquire = (
     key: string,
@@ -194,10 +237,12 @@ export const layer = (
       try: async () => {
         const result = await redis.eval(
           RELEASE_SCRIPT,
-          1,
+          2,
           prefixKey(key),
+          releaseChannel(key),
           permits.toString(),
-          holderId
+          holderId,
+          pushBasedAcquireEnabled ? "1" : "0"
         );
         return result as number;
       },
@@ -251,10 +296,55 @@ export const layer = (
         new SemaphoreBackingError({ operation: "getCount", cause }),
     });
 
+  // Stream that emits when permits are released on a given key.
+  // Uses Redis pub/sub with a dedicated subscriber connection.
+  const onPermitsReleased = (key: string): Stream.Stream<void> =>
+    Stream.asyncPush<void, SemaphoreBackingError>((emit) => {
+      const channel = releaseChannel(key);
+
+      return Effect.acquireRelease(
+        Effect.gen(function* () {
+          // Create a dedicated subscriber connection
+          const subscriber = redis.duplicate();
+
+          // Set up message handler before subscribing
+          const messageHandler = (ch: string, _message: string) => {
+            if (ch === channel) {
+              emit.single(void 0);
+            }
+          };
+          subscriber.on("message", messageHandler);
+
+          // Subscribe to the channel
+          yield* Effect.tryPromise({
+            try: () => subscriber.subscribe(channel),
+            catch: (cause) =>
+              new SemaphoreBackingError({ operation: "subscribe", cause }),
+          });
+
+          return { subscriber, messageHandler };
+        }),
+        ({ subscriber, messageHandler }) =>
+          Effect.sync(() => {
+            subscriber.off("message", messageHandler);
+            subscriber.unsubscribe(channel);
+            subscriber.disconnect();
+          })
+      );
+    }).pipe(
+      Stream.retry(pushStreamRetrySchedule),
+      Stream.catchTag("SemaphoreBackingError", () =>
+        Stream.dieMessage(
+          "Invariant violated: `onPermitsReleased` should never error because it should be retried forever"
+        )
+      )
+    );
+
   return Layer.succeed(DistributedSemaphoreBacking, {
     tryAcquire,
     release,
     refresh,
     getCount,
+    onPermitsReleased: pushBasedAcquireEnabled ? onPermitsReleased : undefined,
   });
 };