durable-locks

DurableLock - Cloudflare Durable Objects Lock Library

Credits

This project is based on the dlock code by losfair, which provides a similar distributed locking mechanism.

Overview

DurableLock is a lightweight TypeScript library designed to manage locking mechanisms using Cloudflare Durable Objects. This library allows multiple processes or users to safely acquire and release locks, ensuring consistent and synchronized access to shared resources.

Features

• Distributed Locking: Safely acquire and release locks across distributed systems using Cloudflare Durable Objects.
• Lease-Based Locking: Support for time-to-live (TTL) based locking to avoid stale locks.
• Alarm System: Automatically clean up expired locks after a set period.
• Simple API: Easy-to-use functions to acquire and release locks using fetch-based requests.

Installation

To use the DurableLock class in your Cloudflare Workers project, simply copy the provided code into your project, or install the package if available on npm.

npm install durable-locks

Prerequisites

• Cloudflare Workers environment
• Durable Objects enabled on your Cloudflare account

Usage

1. Define the Durable Object

In your wrangler.toml file, you need to define the DurableLock as a durable object:

[[durable_objects]]
name = "DURABLE_LOCK"
class_name = "DurableLock"

2. Create a Durable Object Class

import { DurableLock, useDurableLock } from "durable-locks";

3. Use the Lock

You can use the useDurableLock function to interact with the DurableLock object and perform locking operations.

const { acquire, release } = useDurableLock(DURABLE_LOCK, "lock-id");

// Acquiring a lock with a TTL of 5 seconds
const result = await acquire(5000);
if (result.success) {
  console.log(`Lock acquired with lease ${result.lease}`);
} else {
  console.error(`Failed to acquire lock: ${result.reason}`);
}

// Releasing the lock
const releaseResult = await release(result.lease);
if (releaseResult === true) {
  console.log("Lock released successfully");
} else {
  console.error("Failed to release the lock");
}

API

acquire(ttl: number, lease?: number): Promise<Result>

Attempts to acquire a lock for the specified ttl (time-to-live). If a lease is provided, it tries to renew the existing lock; otherwise, it acquires a new lock.

• ttl (number): The duration in milliseconds for which the lock should be held.
• lease (number, optional): The current lease of the lock, if renewing.

Returns:

• Success: Lock was successfully acquired.
• Failed: Lock acquisition failed due to one of the reasons:
  • BORROWED: Lock is already acquired by another process.
  • NO_LONGER_VALID: The lease provided is no longer valid.

release(lease: number): Promise<Failed | true>

Releases the lock associated with the provided lease.

• lease (number): The lease of the lock to be released.

Returns:

• true: Lock successfully released.
• Failed: Lock release failed due to one of the reasons:
  • NO_LONGER_VALID: The lease is no longer valid or the lock has already expired.

isLocked(): Promise<boolean>

Checks if the lock is currently locked.

Returns:

• true: Lock is locked.
• false: Lock is not locked.

Alarm System

The DurableLock class implements an alarm system to automatically clean up expired locks after a hard deadline of 1 day.

async alarm() {
  await this.ctx.storage.deleteAll();
}

License

This project is licensed under the MIT License. See the LICENSE file for details.