redis-read-write-locks 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '02872b14abf3f2ab995c0d0ccf405cbfbab1fe88c7ccb7c59453a11da4bb3e33'
+  data.tar.gz: 3f647988f91d9b003dcbd242920af95d6942b94be79b2845b54e2a0d4af893e2
+SHA512:
+  metadata.gz: 771040f529b8d93a4acd3d1770c11413573fe37be918a1d91ea0e0dd0376ae1d184a4616fca159b914dec0a89da71c5d4657f7ced036b4be66634b996ad8a4a2
+  data.tar.gz: 4b15e4c18f97a0b76959df16bc821d1816efe437a82061c0dfd610806cd098e2de0b4253d00ca35215956bbd00ba428c0ff5a7a7d6d56621f4dcd47d9e39fd84

data/README.md

@@ -0,0 +1,75 @@
+# redis-read-write-locks
+
+Distributed read-write locks for Ruby backed by Redis.
+
+- Multiple readers can hold the lock simultaneously
+- Writers get exclusive access (blocks all readers and other writers)
+- Locks expire automatically via TTL — no deadlock on crash
+- Atomic operations via Lua scripts
+
+## Installation
+
+```ruby
+gem "redis-read-write-locks"
+```
+
+## Usage
+
+```ruby
+require "redis"
+require "redis_read_write_locks"
+
+client = RedisReadWriteLocks::Client.new(Redis.new(url: "redis://localhost:6379/0"))
+
+# Block form — acquires, yields, releases
+client.read_lock("my_resource") { read_data }
+client.write_lock("my_resource") { write_data }
+
+# Manual acquire/release
+lock = client.read_lock("my_resource")
+lock.acquire          # => true / false (non-blocking)
+lock.release
+
+# Block on contention — retries for up to N seconds
+lock.acquire(timeout: 5)          # raises LockTimeoutError if timeout exceeded
+lock.synchronize(timeout: 5) { }  # acquire + yield + release
+
+# Per-lock TTL override
+client.write_lock("my_resource", ttl: 60) { long_operation }
+```
+
+### Client options
+
+```ruby
+client = RedisReadWriteLocks::Client.new(redis, default_ttl: 60)
+```
+
+### Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `ttl`  | `30`    | Lock TTL in seconds. Lock auto-expires if holder crashes. |
+
+### Errors
+
+| Error | When |
+|-------|------|
+| `LockNotAcquiredError` | `synchronize` (no timeout) called when lock is contended |
+| `LockTimeoutError` | `acquire(timeout:)` or `synchronize(timeout:)` exceeded timeout |
+
+## Redis key structure
+
+```
+rw_lock:writer:<name>   # String, holds owner token, TTL = lock TTL
+rw_lock:readers:<name>  # Sorted set, member = token, score = expiry timestamp
+```
+
+## Requirements
+
+- Ruby >= 2.7
+- Redis >= 5.0
+- `redis` gem >= 4.0
+
+## License
+
+MIT

data/lib/redis_read_write_locks/base_lock.rb

@@ -0,0 +1,67 @@
+require "securerandom"
+
+module RedisReadWriteLocks
+  class BaseLock
+    DEFAULT_TTL = 30
+    RETRY_INTERVAL = 0.01
+
+    attr_reader :name, :token
+
+    def initialize(redis:, name:, ttl: DEFAULT_TTL)
+      @redis = redis
+      @name = name
+      @ttl = ttl
+      @token = SecureRandom.uuid
+      @acquired = false
+    end
+
+    def acquired?
+      @acquired
+    end
+
+    # Non-blocking: returns true/false.
+    # With timeout: retries for timeout seconds, returns true or raises LockTimeoutError.
+    def acquire(timeout: nil)
+      return try_acquire if timeout.nil?
+
+      deadline = Time.now.to_f + timeout
+      loop do
+        return true if try_acquire
+        raise LockTimeoutError, "Timeout acquiring #{lock_type} lock '#{@name}'" if Time.now.to_f >= deadline
+        sleep RETRY_INTERVAL
+      end
+    end
+
+    # Acquires lock, yields, releases. Raises LockNotAcquiredError if non-blocking acquire fails.
+    def synchronize(timeout: nil, &block)
+      if timeout
+        acquire(timeout: timeout)
+      else
+        acquire || raise(LockNotAcquiredError, "Could not acquire #{lock_type} lock '#{@name}'")
+      end
+      begin
+        block.call
+      ensure
+        release
+      end
+    end
+
+    private
+
+    def writer_key
+      "rw_lock:writer:#{@name}"
+    end
+
+    def readers_key
+      "rw_lock:readers:#{@name}"
+    end
+
+    def lock_type
+      self.class.name.split("::").last.sub("Lock", "").downcase
+    end
+
+    def eval_script(script, keys:, argv:)
+      @redis.eval(script, keys: keys, argv: argv)
+    end
+  end
+end

data/lib/redis_read_write_locks/client.rb

@@ -0,0 +1,18 @@
+module RedisReadWriteLocks
+  class Client
+    def initialize(redis, default_ttl: BaseLock::DEFAULT_TTL)
+      @redis = redis
+      @default_ttl = default_ttl
+    end
+
+    def read_lock(name, ttl: @default_ttl, &block)
+      lock = ReadLock.new(redis: @redis, name: name, ttl: ttl)
+      block ? lock.synchronize(&block) : lock
+    end
+
+    def write_lock(name, ttl: @default_ttl, &block)
+      lock = WriteLock.new(redis: @redis, name: name, ttl: ttl)
+      block ? lock.synchronize(&block) : lock
+    end
+  end
+end

data/lib/redis_read_write_locks/errors.rb

@@ -0,0 +1,5 @@
+module RedisReadWriteLocks
+  Error = Class.new(StandardError)
+  LockNotAcquiredError = Class.new(Error)
+  LockTimeoutError = Class.new(Error)
+end

data/lib/redis_read_write_locks/lock_scripts.rb

@@ -0,0 +1,71 @@
+module RedisReadWriteLocks
+  module LockScripts
+    # KEYS[1] = writer_key, KEYS[2] = readers_key
+    # ARGV[1] = token, ARGV[2] = expiry (unix ts), ARGV[3] = now (unix ts)
+    # Returns 1 = acquired, 0 = blocked
+    ACQUIRE_READ = <<~LUA.freeze
+      local writer_key = KEYS[1]
+      local readers_key = KEYS[2]
+      local token = ARGV[1]
+      local expiry = tonumber(ARGV[2])
+      local now = tonumber(ARGV[3])
+
+      redis.call('ZREMRANGEBYSCORE', readers_key, '-inf', now)
+
+      if redis.call('EXISTS', writer_key) == 1 then
+        return 0
+      end
+
+      redis.call('ZADD', readers_key, expiry, token)
+
+      local current_ttl = redis.call('TTL', readers_key)
+      if current_ttl == -1 or (current_ttl > 0 and (now + current_ttl) < expiry) then
+        redis.call('EXPIREAT', readers_key, expiry + 1)
+      end
+
+      return 1
+    LUA
+
+    # KEYS[1] = readers_key
+    # ARGV[1] = token
+    RELEASE_READ = <<~LUA.freeze
+      redis.call('ZREM', KEYS[1], ARGV[1])
+      return 1
+    LUA
+
+    # KEYS[1] = writer_key, KEYS[2] = readers_key
+    # ARGV[1] = token, ARGV[2] = ttl (seconds), ARGV[3] = now (unix ts)
+    # Returns 1 = acquired, 0 = blocked
+    ACQUIRE_WRITE = <<~LUA.freeze
+      local writer_key = KEYS[1]
+      local readers_key = KEYS[2]
+      local token = ARGV[1]
+      local ttl = tonumber(ARGV[2])
+      local now = tonumber(ARGV[3])
+
+      redis.call('ZREMRANGEBYSCORE', readers_key, '-inf', now)
+
+      if redis.call('ZCARD', readers_key) > 0 then
+        return 0
+      end
+
+      if redis.call('EXISTS', writer_key) == 1 then
+        return 0
+      end
+
+      redis.call('SET', writer_key, token, 'EX', ttl)
+      return 1
+    LUA
+
+    # KEYS[1] = writer_key
+    # ARGV[1] = token
+    # Returns 1 = released, 0 = not owner
+    RELEASE_WRITE = <<~LUA.freeze
+      if redis.call('GET', KEYS[1]) == ARGV[1] then
+        redis.call('DEL', KEYS[1])
+        return 1
+      end
+      return 0
+    LUA
+  end
+end

data/lib/redis_read_write_locks/read_lock.rb

@@ -0,0 +1,26 @@
+module RedisReadWriteLocks
+  class ReadLock < BaseLock
+    def release
+      return false unless @acquired
+
+      eval_script(LockScripts::RELEASE_READ, keys: [readers_key], argv: [@token])
+      @acquired = false
+      true
+    end
+
+    private
+
+    def try_acquire
+      now = Time.now.to_i
+      expiry = now + @ttl
+
+      result = eval_script(
+        LockScripts::ACQUIRE_READ,
+        keys: [writer_key, readers_key],
+        argv: [@token, expiry, now],
+      )
+
+      @acquired = result == 1
+    end
+  end
+end

data/lib/redis_read_write_locks/version.rb

@@ -0,0 +1,3 @@
+module RedisReadWriteLocks
+  VERSION = "0.1.0"
+end

data/lib/redis_read_write_locks/write_lock.rb

@@ -0,0 +1,23 @@
+module RedisReadWriteLocks
+  class WriteLock < BaseLock
+    def release
+      return false unless @acquired
+
+      eval_script(LockScripts::RELEASE_WRITE, keys: [writer_key], argv: [@token])
+      @acquired = false
+      true
+    end
+
+    private
+
+    def try_acquire
+      result = eval_script(
+        LockScripts::ACQUIRE_WRITE,
+        keys: [writer_key, readers_key],
+        argv: [@token, @ttl, Time.now.to_i],
+      )
+
+      @acquired = result == 1
+    end
+  end
+end

data/lib/redis_read_write_locks.rb

@@ -0,0 +1,7 @@
+require_relative "redis_read_write_locks/version"
+require_relative "redis_read_write_locks/errors"
+require_relative "redis_read_write_locks/lock_scripts"
+require_relative "redis_read_write_locks/base_lock"
+require_relative "redis_read_write_locks/read_lock"
+require_relative "redis_read_write_locks/write_lock"
+require_relative "redis_read_write_locks/client"

data/redis-read-write-locks.gemspec

@@ -0,0 +1,21 @@
+require_relative "lib/redis_read_write_locks/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "redis-read-write-locks"
+  spec.version = RedisReadWriteLocks::VERSION
+  spec.authors = ["Umbrellio"]
+  spec.email = ["oss@umbrellio.biz"]
+  spec.summary = "Distributed read-write locks using Redis"
+  spec.description = "Redis-backed distributed read-write locks. Multiple concurrent readers, exclusive writers."
+  spec.homepage = "https://github.com/umbrellio/redis-read-write-locks"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.files = Dir["lib/**/*.rb", "*.gemspec", "LICENSE", "README.md"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "redis", ">= 4.0"
+
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: redis-read-write-locks
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Umbrellio
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Redis-backed distributed read-write locks. Multiple concurrent readers,
+  exclusive writers.
+email:
+- oss@umbrellio.biz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/redis_read_write_locks.rb
+- lib/redis_read_write_locks/base_lock.rb
+- lib/redis_read_write_locks/client.rb
+- lib/redis_read_write_locks/errors.rb
+- lib/redis_read_write_locks/lock_scripts.rb
+- lib/redis_read_write_locks/read_lock.rb
+- lib/redis_read_write_locks/version.rb
+- lib/redis_read_write_locks/write_lock.rb
+- redis-read-write-locks.gemspec
+homepage: https://github.com/umbrellio/redis-read-write-locks
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Distributed read-write locks using Redis
+test_files: []