effect-distributed-lock 0.0.3 → 0.0.4

package/src/RedisBacking.ts

@@ -1,19 +1,50 @@
-import { Duration, Effect, Layer, Option } from "effect";
+import { Duration, Effect, Layer } from "effect";
 import { Redis } from "ioredis";
-import { DistributedMutexBacking } from "./DistributedMutex.js";
-import { MutexBackingError } from "./Errors.js";
+import {
+  DistributedSemaphoreBacking,
+  SemaphoreBackingError,
+} from "./Backing.js";
 
 /**
- * Lua script for atomic lock acquisition.
- * SET key value NX PX ttl - set only if not exists, with TTL
+ * Lua script for atomic semaphore acquisition.
+ *
+ * Uses a sorted set where:
+ * - Each member is `holderId_permitIndex` (e.g., "abc123_0", "abc123_1")
+ * - Score is the acquisition timestamp
+ * - Expired entries are removed before checking capacity
+ *
+ * Arguments:
+ * - KEYS[1]: the semaphore key
+ * - ARGV[1]: limit (max permits)
+ * - ARGV[2]: permits to acquire
+ * - ARGV[3]: holderId
+ * - ARGV[4]: ttlMs (lock timeout in ms)
+ * - ARGV[5]: now (current timestamp in ms)
+ *
+ * Returns 1 if acquired, 0 if not enough permits available.
  */
 const ACQUIRE_SCRIPT = `
 local key = KEYS[1]
-local holderId = ARGV[1]
-local ttlMs = tonumber(ARGV[2])
+local limit = tonumber(ARGV[1])
+local permits = tonumber(ARGV[2])
+local holderId = ARGV[3]
+local ttlMs = tonumber(ARGV[4])
+local now = tonumber(ARGV[5])
+local expiredTimestamp = now - ttlMs
 
-local result = redis.call('SET', key, holderId, 'NX', 'PX', ttlMs)
-if result then
+-- Remove expired entries
+redis.call('zremrangebyscore', key, '-inf', expiredTimestamp)
+
+-- Check if there's room for the requested permits
+if (redis.call('zcard', key) + permits) <= limit then
+  -- Add all permits with current timestamp
+  local args = {}
+  for i = 0, permits - 1 do
+    table.insert(args, now)
+    table.insert(args, holderId .. '_' .. i)
+  end
+  redis.call('zadd', key, unpack(args))
+  redis.call('pexpire', key, ttlMs)
   return 1
 else
   return 0
@@ -21,34 +52,68 @@ end
 `;
 
 /**
- * Lua script for atomic lock release.
- * Only deletes if we are the current holder.
+ * Lua script for atomic release.
+ *
+ * Removes all permits held by this holder.
+ *
+ * Arguments:
+ * - KEYS[1]: the semaphore key
+ * - ARGV[1]: permits to release
+ * - ARGV[2]: holderId
+ *
+ * Returns the number of permits released.
  */
 const RELEASE_SCRIPT = `
 local key = KEYS[1]
-local holderId = ARGV[1]
+local permits = tonumber(ARGV[1])
+local holderId = ARGV[2]
+local args = {}
 
-local currentHolder = redis.call('GET', key)
-if currentHolder == holderId then
-  redis.call('DEL', key)
-  return 1
-else
-  return 0
+for i = 0, permits - 1 do
+  table.insert(args, holderId .. '_' .. i)
 end
+
+return redis.call('zrem', key, unpack(args))
 `;
 
 /**
  * Lua script for atomic TTL refresh.
- * Only refreshes if we are the current holder.
+ *
+ * Updates the timestamp (score) for all permits held by this holder.
+ * Returns 0 if the holder doesn't have any permits (lock was lost).
+ *
+ * Arguments:
+ * - KEYS[1]: the semaphore key
+ * - ARGV[1]: limit (for consistency, though not strictly needed for refresh)
+ * - ARGV[2]: permits
+ * - ARGV[3]: holderId
+ * - ARGV[4]: ttlMs
+ * - ARGV[5]: now
+ *
+ * Returns 1 if refreshed, 0 if permits were lost.
  */
 const REFRESH_SCRIPT = `
 local key = KEYS[1]
-local holderId = ARGV[1]
-local ttlMs = tonumber(ARGV[2])
+local limit = tonumber(ARGV[1])
+local permits = tonumber(ARGV[2])
+local holderId = ARGV[3]
+local ttlMs = tonumber(ARGV[4])
+local now = tonumber(ARGV[5])
+local expiredTimestamp = now - ttlMs
 
-local currentHolder = redis.call('GET', key)
-if currentHolder == holderId then
-  redis.call('PEXPIRE', key, ttlMs)
+-- Remove expired entries
+redis.call('zremrangebyscore', key, '-inf', expiredTimestamp)
+
+-- Check if we still hold the first permit (indicator that we still own it)
+if redis.call('zscore', key, holderId .. '_0') then
+  -- Update all permits with new timestamp
+  local args = {}
+  for i = 0, permits - 1 do
+    table.insert(args, now)
+    table.insert(args, holderId .. '_' .. i)
+  end
+  redis.call('zadd', key, unpack(args))
+  redis.call('pexpire', key, ttlMs)
   return 1
 else
   return 0
@@ -56,99 +121,140 @@ end
 `;
 
 /**
- * Create a Redis-backed distributed mutex backing layer.
+ * Lua script to get the current count of active permits.
+ *
+ * Arguments:
+ * - KEYS[1]: the semaphore key
+ * - ARGV[1]: ttlMs
+ * - ARGV[2]: now
+ *
+ * Returns the number of active (non-expired) permits.
+ */
+const GET_COUNT_SCRIPT = `
+local key = KEYS[1]
+local ttlMs = tonumber(ARGV[1])
+local now = tonumber(ARGV[2])
+local expiredTimestamp = now - ttlMs
+
+-- Remove expired entries
+redis.call('zremrangebyscore', key, '-inf', expiredTimestamp)
+
+return redis.call('zcard', key)
+`;
+
+/**
+ * Create a Redis-backed distributed semaphore backing layer.
  *
- * @param redis - An ioredis client instance
- * @param keyPrefix - Optional prefix for all keys (default: "dmutex:")
+ * **Important:** This implementation is for single-instance Redis only.
+ * It does not implement the Redlock algorithm and should not be used with
+ * Redis Cluster or Redis Sentinel for distributed locking guarantees.
+ * 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:")
  */
 export const layer = (
   redis: Redis,
-  keyPrefix = "dmutex:"
-): Layer.Layer<DistributedMutexBacking> => {
+  keyPrefix = "dsem:"
+): Layer.Layer<DistributedSemaphoreBacking> => {
   const prefixKey = (key: string) => `${keyPrefix}${key}`;
 
   const tryAcquire = (
     key: string,
     holderId: string,
-    ttl: Duration.Duration
-  ): Effect.Effect<boolean, MutexBackingError> =>
+    ttl: Duration.Duration,
+    limit: number,
+    permits: number
+  ): Effect.Effect<boolean, SemaphoreBackingError> =>
     Effect.tryPromise({
       try: async () => {
+        const now = Date.now();
         const result = await redis.eval(
           ACQUIRE_SCRIPT,
           1,
           prefixKey(key),
+          limit.toString(),
+          permits.toString(),
           holderId,
-          Duration.toMillis(ttl).toString()
+          Duration.toMillis(ttl).toString(),
+          now.toString()
         );
         return result === 1;
       },
       catch: (cause) =>
-        new MutexBackingError({ operation: "tryAcquire", cause }),
+        new SemaphoreBackingError({ operation: "tryAcquire", cause }),
     });
 
   const release = (
     key: string,
-    holderId: string
-  ): Effect.Effect<boolean, MutexBackingError> =>
+    holderId: string,
+    permits: number
+  ): Effect.Effect<number, SemaphoreBackingError> =>
     Effect.tryPromise({
       try: async () => {
         const result = await redis.eval(
           RELEASE_SCRIPT,
           1,
           prefixKey(key),
+          permits.toString(),
           holderId
         );
-        return result === 1;
+        return result as number;
       },
-      catch: (cause) => new MutexBackingError({ operation: "release", cause }),
+      catch: (cause) =>
+        new SemaphoreBackingError({ operation: "release", cause }),
     });
 
   const refresh = (
     key: string,
     holderId: string,
-    ttl: Duration.Duration
-  ): Effect.Effect<boolean, MutexBackingError> =>
+    ttl: Duration.Duration,
+    limit: number,
+    permits: number
+  ): Effect.Effect<boolean, SemaphoreBackingError> =>
     Effect.tryPromise({
       try: async () => {
+        const now = Date.now();
         const result = await redis.eval(
           REFRESH_SCRIPT,
           1,
           prefixKey(key),
+          limit.toString(),
+          permits.toString(),
           holderId,
-          Duration.toMillis(ttl).toString()
+          Duration.toMillis(ttl).toString(),
+          now.toString()
         );
         return result === 1;
       },
-      catch: (cause) => new MutexBackingError({ operation: "refresh", cause }),
-    });
-
-  const isLocked = (key: string): Effect.Effect<boolean, MutexBackingError> =>
-    Effect.tryPromise({
-      try: async () => {
-        const exists = await redis.exists(prefixKey(key));
-        return exists === 1;
-      },
-      catch: (cause) => new MutexBackingError({ operation: "isLocked", cause }),
+      catch: (cause) =>
+        new SemaphoreBackingError({ operation: "refresh", cause }),
     });
 
-  const getHolder = (
-    key: string
-  ): Effect.Effect<Option.Option<string>, MutexBackingError> =>
+  const getCount = (
+    key: string,
+    ttl: Duration.Duration
+  ): Effect.Effect<number, SemaphoreBackingError> =>
     Effect.tryPromise({
       try: async () => {
-        const holder = await redis.get(prefixKey(key));
-        return holder ? Option.some(holder) : Option.none();
+        const now = Date.now();
+        const result = await redis.eval(
+          GET_COUNT_SCRIPT,
+          1,
+          prefixKey(key),
+          Duration.toMillis(ttl).toString(),
+          now.toString()
+        );
+        return result as number;
       },
       catch: (cause) =>
-        new MutexBackingError({ operation: "getHolder", cause }),
+        new SemaphoreBackingError({ operation: "getCount", cause }),
     });
 
-  return Layer.succeed(DistributedMutexBacking, {
+  return Layer.succeed(DistributedSemaphoreBacking, {
     tryAcquire,
     release,
     refresh,
-    isLocked,
-    getHolder,
+    getCount,
   });
 };

package/src/index.ts

@@ -1,30 +1,38 @@
 /**
- * Effect Distributed Lock
+ * Effect Distributed Semaphore
  *
- * A distributed mutex library for Effect with pluggable backends.
+ * A distributed semaphore library for Effect with pluggable backends.
+ * Implements a multi-semaphore that can be used to implement:
+ * - Mutex (limit=1, permits=1)
+ * - Semaphore (limit=N, permits=1)
+ * - Multi-semaphore (limit=N, permits=M)
  *
  * @example
  * ```ts
- * import { DistributedMutex, RedisBacking } from "effect-distributed-lock";
+ * import { DistributedSemaphore, RedisBacking } from "effect-distributed-lock";
  * import { Effect } from "effect";
  * import Redis from "ioredis";
  *
  * const redis = new Redis(process.env.REDIS_URL);
  *
  * const program = Effect.gen(function* () {
- *   // Create a mutex for a specific resource
- *   const mutex = yield* DistributedMutex.make("my-resource-lock", {
+ *   // Create a semaphore that allows 5 concurrent operations
+ *   const sem = yield* DistributedSemaphore.make("my-resource", {
+ *     limit: 5,
  *     ttl: "30 seconds",
- *     acquireTimeout: "10 seconds",
  *   });
  *
- *   // Use the lock
- *   yield* mutex.withLock(
+ *   // Acquire 2 permits, run effect, release when done
+ *   yield* sem.withPermits(2)(
  *     Effect.gen(function* () {
- *       // Critical section - only one process can be here at a time
- *       yield* doSomethingExclusive();
+ *       // Only 2 of the 5 slots are used
+ *       yield* doSomethingLimited();
  *     })
  *   );
+ *
+ *   // For mutex behavior, use limit=1 and withPermits(1)
+ *   const mutex = yield* DistributedSemaphore.make("my-lock", { limit: 1 });
+ *   yield* mutex.withPermits(1)(criticalSection);
  * });
  *
  * program.pipe(
@@ -36,10 +44,18 @@
  * @module
  */
 
+// Backing interface
+export * as Backing from "./Backing.js";
+export {
+  DistributedSemaphoreBacking,
+  SemaphoreBackingError,
+} from "./Backing.js";
+
 // Core module (namespace with types and functions)
-export * as DistributedMutex from "./DistributedMutex.js";
+export * as DistributedSemaphore from "./DistributedSemaphore.js";
+
 // Errors
-export { MutexBackingError, LockLostError } from "./Errors.js";
+export { LockLostError } from "./Errors.js";
 
 // Redis backing
 export * as RedisBacking from "./RedisBacking.js";