effect-distributed-lock 0.0.2 → 0.0.4

package/README.md

@@ -1,13 +1,18 @@
 # effect-distributed-lock
 
-A distributed mutex library for [Effect](https://effect.website/) with pluggable backends.
+*WARNING: This is still in active development, possibly has bugs (distributed systems are hard!), and is subject to change.*
+
+A distributed semaphore library for [Effect](https://effect.website/) with pluggable backends.
+
+It's like the built in `Effect.Semaphore`, but asynchronously distributed across multiple processes/services!
 
 ## Features
 
-- **Scope-based resource management** — locks are automatically released when the scope closes
-- **Automatic TTL refresh** — keeps locks alive while held, prevents deadlocks if holder crashes
-- **Pluggable backends** — ships with Redis, easy to implement others (etcd, DynamoDB, etc.)
-- **Configurable retry & timeout** — control polling interval, acquire timeout, and TTL
+- **Distributed semaphore** — control concurrent access across multiple processes/services
+- **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
+- **Configurable retry policies** — control polling interval, TTL, and backing failure retry behavior
 - **Type-safe errors** — tagged errors for precise error handling
 
 ## Installation
@@ -24,26 +29,25 @@ npm install ioredis
 ## Quick Start
 
 ```typescript
-import { Effect } from "effect";
+import { Effect, Schedule } from "effect";
 import Redis from "ioredis";
-import { DistributedMutex, RedisBacking } from "effect-distributed-lock";
+import { DistributedSemaphore, RedisBacking } from "effect-distributed-lock";
 
 const redis = new Redis(process.env.REDIS_URL);
 const RedisLayer = RedisBacking.layer(redis);
 
 const program = Effect.gen(function* () {
-  const mutex = yield* DistributedMutex.make("my-resource", {
-    ttl: "30 seconds",
-    acquireTimeout: "10 seconds",
+  // Create a semaphore that allows 5 concurrent operations
+  const sem = yield* DistributedSemaphore.make("my-resource", {
+    limit: 5,
+    ttl: "10 seconds",
+    refreshInterval: "3 seconds",
+    acquireRetryInterval: "500 millis",
+    backingFailureRetryPolicy: Schedule.exponential("100 millis"),
   });
 
-  // Lock is held while effect runs, released automatically after
-  yield* mutex.withLock(
-    Effect.gen(function* () {
-      // Critical section - only one process can be here at a time
-      yield* doExclusiveWork();
-    })
-  );
+  // Acquire 2 permits, run effect, release automatically after
+  yield* doWork.pipe(sem.withPermits(2));
 });
 
 program.pipe(Effect.provide(RedisLayer), Effect.runPromise);
@@ -51,60 +55,68 @@ program.pipe(Effect.provide(RedisLayer), Effect.runPromise);
 
 ## API
 
-### Creating a Mutex
+### Creating a Semaphore
 
 ```typescript
-const mutex = yield* DistributedMutex.make(key, config);
+const sem = yield* DistributedSemaphore.make(key, config);
 ```
 
-| Config Option     | Type             | Default      | Description                                      |
-| ----------------- | ---------------- | ------------ | ------------------------------------------------ |
-| `ttl`             | `DurationInput`  | `30 seconds` | Lock TTL (auto-releases if holder crashes)       |
-| `refreshInterval` | `DurationInput`  | `ttl / 3`    | How often to refresh TTL while holding           |
-| `retryInterval`   | `DurationInput`  | `100ms`      | Polling interval when waiting to acquire         |
-| `acquireTimeout`  | `DurationInput`  | `∞`          | Max time to wait for lock (fails if exceeded)    |
+| Config Option                | Type             | Default      | Description                                |
+| ---------------------------- | ---------------- | ------------ | ------------------------------------------ |
+| `limit`                      | `number`         | `1`          | Max permits (1 = mutex behavior)           |
+| `ttl`                        | `DurationInput`  | `30 seconds` | Permit TTL (auto-releases if holder crashes) |
+| `refreshInterval`            | `DurationInput`  | `ttl / 3`    | How often to refresh TTL while holding     |
+| `acquireRetryInterval`       | `DurationInput`  | `100ms`      | Polling interval when waiting to acquire   |
+| `backingFailureRetryPolicy`  | `Schedule<void>` | `100ms`      | Retry schedule for backing store failures  |
 
-### Using the Mutex
+### Using the Semaphore
 
-#### `withLock` — Acquire, run, release
+#### `withPermits` — Acquire, run, release
 
-The simplest and recommended way. Acquires the lock, runs your effect, and releases when done:
+The simplest and recommended way. Acquires permits (waiting if needed), runs your effect, and releases when done:
 
 ```typescript
-yield* mutex.withLock(myEffect);
+// Acquire 2 permits out of limit
+yield* myEffect.pipe(sem.withPermits(2));
+
+// For mutex behavior (limit=1), use withPermits(1)
+yield* criticalSection.pipe(mutex.withPermits(1));
 ```
 
-#### `withLockIfAvailable` — Non-blocking acquire
+#### `withPermitsIfAvailable` — Non-blocking acquire
 
-Tries to acquire immediately without waiting. Returns `Option.some(result)` if successful, `Option.none()` if lock is held:
+Tries to acquire immediately without waiting. Returns `Option.some(result)` if successful, `Option.none()` if not enough permits:
 
 ```typescript
-const result = yield* mutex.withLockIfAvailable(myEffect);
+const result = yield* myEffect.pipe(sem.withPermitsIfAvailable(1));
 if (Option.isSome(result)) {
-  console.log("Got the lock!", result.value);
+  console.log("Got the permit!", result.value);
 } else {
-  console.log("Lock was busy, skipping");
+  console.log("No permits available, skipping");
 }
 ```
 
-#### `acquire` / `tryAcquire` — Manual scope control
+#### `take` / `tryTake` — Manual scope control
 
-For advanced use cases where you need explicit control over the lock lifecycle:
+For advanced use cases where you need explicit control over the permit lifecycle:
 
 ```typescript
 yield* Effect.scoped(
   Effect.gen(function* () {
-    yield* mutex.acquire; // Lock held until scope closes
-    yield* doWork();
-    // Lock automatically released here
+    const keepAliveFiber = yield* sem.take(2); // 2 permits held until scope closes
+    yield* doWork;
+    // Permits automatically released + keepalive fiber interrupted here
   })
 );
 ```
 
-#### `isLocked` — Check lock status
+Both `take` and `tryTake` return the keepalive fiber that refreshes the permit TTL. Errors from the keepalive (losing permits or backing store failure) are propagated through the fiber.
+
+#### `currentCount` — Check held permits
 
 ```typescript
-const locked = yield* mutex.isLocked;
+const held = yield* sem.currentCount; // Number of permits currently held
+const available = sem.limit - held;   // Number of permits available
 ```
 
 ## Error Handling
@@ -112,48 +124,67 @@ const locked = yield* mutex.isLocked;
 All errors are tagged for precise handling with `Effect.catchTag`:
 
 ```typescript
-yield* mutex.withLock(myEffect).pipe(
-  Effect.catchTag("AcquireTimeoutError", (e) =>
-    Effect.log(`Timed out acquiring lock: ${e.key}`)
-  ),
+yield* myEffect.pipe(
+  sem.withPermits(1),
   Effect.catchTag("LockLostError", (e) =>
-    Effect.log(`Lock was lost while held: ${e.key}`)
+    Effect.log(`Permits were lost: ${e.key}`)
   ),
-  Effect.catchTag("BackingError", (e) =>
+  Effect.catchTag("SemaphoreBackingError", (e) =>
     Effect.log(`Redis error: ${e.message}`)
   )
 );
 ```
 
-| Error                 | Description                                          |
-| --------------------- | ---------------------------------------------------- |
-| `AcquireTimeoutError` | Failed to acquire lock within the timeout period     |
-| `LockLostError`       | Lock TTL expired while we thought we held it         |
-| `BackingError`        | Error from the backing store (Redis connection, etc) |
+| Error                   | Description                                          |
+| ----------------------- | ---------------------------------------------------- |
+| `LockLostError`         | Permit TTL expired while we thought we held it       |
+| `SemaphoreBackingError` | Error from the backing store (Redis connection, etc) |
+
+## Redis Backing (Single-Instance Only)
+
+The provided Redis backing is designed for **single-instance Redis only**. It does not implement the [Redlock algorithm](https://redis.io/docs/latest/develop/clients/patterns/distributed-locks/) and should not be used with Redis Cluster or Redis Sentinel when you need strong distributed locking guarantees.
+
+```typescript
+import Redis from "ioredis";
+import { RedisBacking } from "effect-distributed-lock";
+
+// Single Redis instance
+const redis = new Redis("redis://localhost:6379");
+const RedisLayer = RedisBacking.layer(redis, "my-prefix:");
+```
+
+For multi-instance Redis deployments requiring Redlock, you'll need to implement a custom backing.
 
 ## Custom Backends
 
-Implement the `DistributedMutexBacking` interface to use a different store:
+Implement the `DistributedSemaphoreBacking` interface to use a different store:
 
 ```typescript
-import { Layer } from "effect";
-import { DistributedMutex } from "effect-distributed-lock";
-
-const MyCustomBacking = Layer.succeed(DistributedMutex.DistributedMutexBacking, {
-  tryAcquire: (key, holderId, ttlMs) => /* ... */,
-  release: (key, holderId) => /* ... */,
-  refresh: (key, holderId, ttlMs) => /* ... */,
-  isLocked: (key) => /* ... */,
-  getHolder: (key) => /* ... */,
+import { Duration, Effect, Layer, Option } from "effect";
+import { Backing, DistributedSemaphoreBacking } from "effect-distributed-lock";
+
+const MyCustomBacking = Layer.succeed(DistributedSemaphoreBacking, {
+  tryAcquire: (key, holderId, ttl, limit, permits) => 
+    Effect.succeed(true), // Try to acquire permits
+  
+  release: (key, holderId, permits) => 
+    Effect.succeed(permits), // Release permits, return count released
+  
+  refresh: (key, holderId, ttl, limit, permits) => 
+    Effect.succeed(true), // Refresh TTL, return false if lost
+  
+  getCount: (key, ttl) => 
+    Effect.succeed(0), // Return number of permits currently held
 });
 ```
 
 ## How It Works
 
-1. **Acquire**: Atomically sets the lock key if not exists (Redis: `SET key value NX PX ttl`)
-2. **Keepalive**: A background fiber refreshes the TTL periodically while the lock is held
-3. **Release**: Atomically deletes the key only if we're still the holder (Lua script for atomicity)
-4. **Crash safety**: If the holder crashes, the TTL expires and another process can acquire
+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
 
 ## License
 

package/examples/index.ts

@@ -1,12 +1,12 @@
 /**
- * Example usage of the distributed mutex library.
+ * Example usage of the distributed semaphore library.
  *
  * Run with: bun run example.ts
  * Requires REDIS_URL environment variable.
  */
-import { Effect, Console, Duration } from "effect";
+import { Effect, Console, Duration, Option } from "effect";
 import Redis from "ioredis";
-import { DistributedMutex, RedisBacking } from "../src/index.ts";
+import { DistributedSemaphore, RedisBacking } from "../src/index.ts";
 
 // Create Redis client
 const redis = new Redis(process.env.REDIS_URL ?? "redis://localhost:6379");
@@ -14,16 +14,16 @@ const redis = new Redis(process.env.REDIS_URL ?? "redis://localhost:6379");
 // Create the Redis backing layer
 const RedisLayer = RedisBacking.layer(redis, "example:");
 
-// Example 1: Using withLock for a critical section
+// Example 1: Using withPermits for a critical section (mutex behavior)
 const example1 = Effect.gen(function* () {
-  yield* Console.log("=== Example 1: withLock ===");
+  yield* Console.log("=== Example 1: Mutex with withPermits(1) ===");
 
-  const mutex = yield* DistributedMutex.make("my-resource", {
+  const mutex = yield* DistributedSemaphore.make("my-resource", {
+    limit: 1, // Acts as a mutex
     ttl: Duration.seconds(10),
-    acquireTimeout: Duration.seconds(5),
   });
 
-  yield* mutex.withLock(
+  yield* mutex.withPermits(1)(
     Effect.gen(function* () {
       yield* Console.log("Lock acquired! Doing critical work...");
       yield* Effect.sleep(2000);
@@ -34,45 +34,72 @@ const example1 = Effect.gen(function* () {
   yield* Console.log("Lock released automatically");
 });
 
-// Example 2: Using tryAcquire (non-blocking)
+// Example 2: Using withPermitsIfAvailable (non-blocking)
 const example2 = Effect.gen(function* () {
-  yield* Console.log("\n=== Example 2: withLockIfAvailable ===");
+  yield* Console.log("\n=== Example 2: withPermitsIfAvailable ===");
 
-  const mutex = yield* DistributedMutex.make("another-resource", {
+  const mutex = yield* DistributedSemaphore.make("another-resource", {
+    limit: 1,
     ttl: Duration.seconds(10),
   });
 
-  const result = yield* mutex.withLockIfAvailable(
+  const result = yield* mutex.withPermitsIfAvailable(1)(
     Effect.gen(function* () {
       yield* Console.log("Got the lock without waiting!");
       return "success";
     })
   );
 
-  yield* Console.log(`Result: ${JSON.stringify(result)}`);
+  if (Option.isSome(result)) {
+    yield* Console.log(`Result: ${result.value}`);
+  } else {
+    yield* Console.log("Could not acquire lock immediately");
+  }
 });
 
-// Example 3: Manual scope management with acquire()
+// Example 3: Semaphore with multiple permits
 const example3 = Effect.gen(function* () {
-  yield* Console.log("\n=== Example 3: Manual acquire with Scope ===");
+  yield* Console.log("\n=== Example 3: Semaphore with limit=5 ===");
 
-  const mutex = yield* DistributedMutex.make("manual-resource", {
+  const sem = yield* DistributedSemaphore.make("pool-resource", {
+    limit: 5, // Allow 5 concurrent operations
+    ttl: Duration.seconds(10),
+  });
+
+  // Acquire 2 permits out of 5
+  yield* sem.withPermits(2)(
+    Effect.gen(function* () {
+      yield* Console.log("Acquired 2 permits (3 still available)");
+      const count = yield* sem.currentCount;
+      yield* Console.log(`Current active permits: ${count}`);
+      yield* Effect.sleep(1000);
+    })
+  );
+
+  yield* Console.log("Released 2 permits");
+});
+
+// Example 4: Manual scope management with take()
+const example4 = Effect.gen(function* () {
+  yield* Console.log("\n=== Example 4: Manual acquire with Scope ===");
+
+  const mutex = yield* DistributedSemaphore.make("manual-resource", {
+    limit: 1,
     ttl: Duration.seconds(10),
-    acquireTimeout: Duration.seconds(5),
   });
 
   // Using Effect.scoped to manage the lock lifecycle
   yield* Effect.scoped(
     Effect.gen(function* () {
-      yield* mutex.acquire;
-      yield* Console.log("Lock acquired via acquire()");
+      yield* mutex.take(1);
+      yield* Console.log("Permit acquired via take(1)");
       yield* Effect.sleep(1000);
       yield* Console.log("About to exit scope...");
-      // Lock is automatically released when scope closes
+      // Permits are automatically released when scope closes
     })
   );
 
-  yield* Console.log("Scope closed, lock released");
+  yield* Console.log("Scope closed, permit released");
 });
 
 // Run all examples
@@ -80,6 +107,7 @@ const main = Effect.gen(function* () {
   yield* example1;
   yield* example2;
   yield* example3;
+  yield* example4;
   yield* Console.log("\n✓ All examples completed!");
 }).pipe(
   Effect.ensuring(Effect.promise(() => redis.quit())),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "effect-distributed-lock",
-  "version": "0.0.2",
-  "description": "A distributed mutex library for Effect with pluggable backends",
+  "version": "0.0.4",
+  "description": "A distributed semaphore library for Effect with pluggable backends",
   "license": "MIT",
   "repository": {
     "type": "git",

package/redis-semaphore/.codeclimate.yml

@@ -0,0 +1,5 @@
+version: '2'
+plugins:
+  eslint:
+    enabled: true
+    channel: 'eslint-6'

package/redis-semaphore/.fossa.yml

@@ -0,0 +1,14 @@
+# Generated by FOSSA CLI (https://github.com/fossas/fossa-cli)
+# Visit https://fossa.com to learn more
+
+version: 2
+cli:
+  server: https://app.fossa.com
+  fetcher: custom
+  project: git@github.com:swarthy/redis-semaphore.git
+analyze:
+  modules:
+  - name: .
+    type: npm
+    target: .
+    path: .

package/redis-semaphore/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: 'npm'
+    directory: '/'
+    schedule:
+      interval: 'monthly'

package/redis-semaphore/.github/workflows/branches.yml

@@ -0,0 +1,39 @@
+name: CI (push)
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+
+jobs:
+  integration-test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x, 22.x]
+
+    env:
+      COVERALLS_REPO_TOKEN: '${{ secrets.COVERALLS_REPO_TOKEN }}'
+      COVERALLS_GIT_BRANCH: '${{ github.ref }}'
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'yarn'
+
+      - run: yarn install --immutable
+
+      - run: docker compose up -d redis1 redis2 redis3
+      - run: docker compose run waiter
+
+      - run: yarn build
+      - run: yarn lint
+      - run: yarn test-ci-with-coverage

package/redis-semaphore/.github/workflows/pull-requests.yml

@@ -0,0 +1,35 @@
+name: CI (PR)
+
+on:
+  pull_request:
+    branches:
+      - master
+  workflow_dispatch:
+
+jobs:
+  integration-test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x, 22.x]
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'yarn'
+
+      - run: yarn install --immutable
+
+      - run: docker compose up -d redis1 redis2 redis3
+      - run: docker compose run waiter
+
+      - run: yarn build
+      - run: yarn lint
+      - run: yarn test

package/redis-semaphore/.mocharc.yaml

@@ -0,0 +1,6 @@
+extension: ts
+recursive: true
+timeout: 5s
+require:
+  - '@swc-node/register'
+  - test/setup.ts

package/redis-semaphore/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "trailingComma": "none",
+  "arrowParens": "avoid"
+}

package/redis-semaphore/.snyk

@@ -0,0 +1,4 @@
+# Snyk (https://snyk.io) policy file, patches or ignores known vulnerabilities.
+version: v1.13.1
+ignore: {}
+patch: {}

package/redis-semaphore/.yarnrc.yml

@@ -0,0 +1,2 @@
+nodeLinker: node-modules
+defaultSemverRangePrefix: ''

package/redis-semaphore/CHANGELOG.md

@@ -0,0 +1,70 @@
+### redis-semaphore@5.6.2
+- Fixed implicit import from `src`
+- Removed `src` folder from NPM package
+
+### redis-semaphore@5.6.1
+- Removed `module` field from `package.json`
+
+### redis-semaphore@5.6.0
+- Added interface compatible client support (ex. `ioredis-mock`)
+- Removed `instanceof Redis` validation in constructor
+- `ioredis` marked as optional peerDependency, explicit `ioredis` install is required now
+
+### redis-semaphore@5.5.1
+- Fix race condition for refresh started before release and finished after release
+
+### redis-semaphore@5.5.0
+
+- Added `identifier` constructor option.
+- Added `acquiredExternally` constructor option.
+- Option `externallyAcquiredIdentifier` **DEPRECATED**.
+- Option `identifierSuffix` **DEPRECATED**.
+
+### redis-semaphore@5.4.0
+
+- Added `identifierSuffix` option, usefull for tracing app instance which locked resource
+
+### redis-semaphore@5.3.1
+
+- Fixed reacquire expired resource in refresh
+
+### redis-semaphore@5.3.0
+
+- Added `stopRefresh` method
+- Added `externallyAcquiredIdentifier` optional constructor option
+- Removed `uuid` dependency
+
+### redis-semaphore@5.2.0
+
+- Added `acquireAttemptsLimit` method
+
+### redis-semaphore@5.1.0
+
+- Added `tryAcquire`
+
+### redis-semaphore@5.0.0
+
+- **Breadking change:** Drop Node.js v10.x, v12.x support
+- Added `ioredis@5` support
+
+### redis-semaphore@4.1.0
+
+- Added `.isAcquired` property on all locks
+- Added `onLostLock` constructor option. By default throws unhandled error.
+
+### redis-semaphore@4.0.0
+
+- **Breaking change:** `Mutex`, `Semaphore`, `MultiSemaphore` not longer support `Cluster`. For multi-node case use `Redlock*` instead.
+- Added `RedlockMutex`, `RedlockSemaphore`, `RedlockMultiSemaphore`
+- Internals refactored
+
+### redis-semaphore@3.2.0
+
+- Added `MultiSemaphore`
+
+### redis-semaphore@3.0.0
+
+- **Breaking change:** `FairSemaphore` has been removed. Use `Semaphore` instead (has the same "fairness")
+  - the `acquire` method in `Semaphore` no longer returns a boolean. Instead, it throws an error if it cannot acquire, and if it doesn't throw, you can assume it worked.
+- Internal code has been cleaned up
+- Added more test, include synthetic node unsynchroned clocks

package/redis-semaphore/Dockerfile

@@ -0,0 +1,5 @@
+FROM node:alpine
+RUN npm i -g @swarthy/wait-for@2.0.2
+VOLUME /app
+WORKDIR /app
+USER node

package/redis-semaphore/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Alexander Mochalin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.