philiprehberger-lock_kit 0.2.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00027e34019a2945cc1d0cdb7814856d850735edbb603d2bc56bf3bbd1c6dee3
-  data.tar.gz: 57ce5708b9dc2000720334da4a7b55281331e374942d7b24887d33ef36e622df
+  metadata.gz: ea17573729655a3a771771a4491e4ad67313ccdd8c1910964efc84e28cc55cd1
+  data.tar.gz: 3d045b798cd8f8b4df88af8127d4fb1ecd30c0ba252a1058fc90095fc4b98b75
 SHA512:
-  metadata.gz: 658255f5a49295524d9a8bd72d4e5530f2cd194dac02d1f2c70b679106f0e4919b674c2fe2eba257d7c8af65c185516368a3d4c5b2643394427ce3e81b75a393
-  data.tar.gz: 71781478e3a427aeeb256b80582a96cb7c58c799b98aa60ccf10a66fd9ac59a632fe4c5fb7374a5c0f814870f9b212f7c99afdc5509696cd15c15de72343655c
+  metadata.gz: '08161efb6474fd3cc5b04d6896200df0e6c3e638e7eb89e898e2de4e0efee4ab2ac7decf99eea5f472a78c2914bbb1d5e4665e4d80a4fd7d72efdb3d4c942505'
+  data.tar.gz: 1776595c803f9c9285afc8bb6b7fc9f26cf32db45f1067a5f6084d585f741b5c27d6bce6ab2d1824c2db4941991e44bd1c0ac53e71f845e4011ac079b4f5f4af

data/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-04-15
+
+### Added
+- `with_retry_lock(path, retries: 3, delay: 0.1, backoff: 2, timeout: nil, auto_cleanup: true, ttl: nil)` module method for lock acquisition with exponential backoff retries
+
+## [0.3.0] - 2026-04-10
+
+### Added
+- `ttl:` option for `with_file_lock`, `with_pid_lock`, `FileLock#acquire`, and `PidLock#acquire` — locks auto-expire after the specified duration
+- `FileLock#expired?` and `PidLock#expired?` instance methods for checking TTL expiration
+- `LockKit.expired?(path)` module-level method for checking lock expiration
+- Stale lock cleanup now considers expired TTL locks as stale
+
+### Fixed
+- Align feature request issue template with guide structure
+
 ## [0.2.3] - 2026-04-09
 
 ### Fixed

data/README.md

@@ -4,7 +4,7 @@
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-lock_kit.svg)](https://rubygems.org/gems/philiprehberger-lock_kit)
 [![Last updated](https://img.shields.io/github/last-commit/philiprehberger/rb-lock-kit)](https://github.com/philiprehberger/rb-lock-kit/commits/main)
 
-File-based and PID locking for process coordination with stale lock detection, read-write locks, and lock owner identification
+File-based and PID locking for process coordination with TTL expiration, stale detection, read-write locks, and lock owner identification
 
 ## Requirements
 
@@ -64,6 +64,37 @@ Philiprehberger::LockKit.with_write_lock('/tmp/data.lock', timeout: 5) do
 end
 ```
 
+### Retry Lock
+
+```ruby
+# Retries lock acquisition with exponential backoff
+Philiprehberger::LockKit.with_retry_lock('/tmp/my.lock', retries: 5, delay: 0.2, backoff: 2) do
+  # acquired after retrying if initially contended
+end
+
+# With timeout per attempt, TTL, and custom cleanup
+Philiprehberger::LockKit.with_retry_lock('/tmp/my.lock', retries: 3, delay: 0.1, backoff: 2, timeout: 5, ttl: 30) do
+  # each attempt waits up to 5s; lock expires after 30s
+end
+```
+
+### Lock with TTL (Time-to-Live)
+
+```ruby
+# Lock expires after 30 seconds — treated as stale once elapsed
+Philiprehberger::LockKit.with_file_lock('/tmp/my.lock', ttl: 30) do
+  # work that should not hold the lock indefinitely
+end
+
+# PID locks also support TTL
+Philiprehberger::LockKit.with_pid_lock('my_worker', ttl: 60) do
+  # expires after 60 seconds
+end
+
+# Check if a lock has expired
+Philiprehberger::LockKit.expired?('/tmp/my.lock') # => true/false
+```
+
 ### Automatic Stale Lock Cleanup
 
 ```ruby
@@ -133,12 +164,14 @@ Philiprehberger::LockKit.stale?('/tmp/my_worker.pid')  # => true/false
 
 | Method | Description |
 |--------|-------------|
-| `.with_file_lock(path, timeout: nil, auto_cleanup: false, on_wait: nil) { }` | Execute block with exclusive file lock |
-| `.with_pid_lock(name, dir: Dir.tmpdir, auto_cleanup: false) { }` | Execute block with PID file lock |
+| `.with_file_lock(path, timeout: nil, auto_cleanup: false, on_wait: nil, ttl: nil) { }` | Execute block with exclusive file lock |
+| `.with_retry_lock(path, retries: 3, delay: 0.1, backoff: 2, timeout: nil, auto_cleanup: true, ttl: nil) { }` | Execute block with file lock, retrying with exponential backoff |
+| `.with_pid_lock(name, dir: Dir.tmpdir, auto_cleanup: false, ttl: nil) { }` | Execute block with PID file lock |
 | `.with_read_lock(path, timeout: nil) { }` | Execute block with shared read lock |
 | `.with_write_lock(path, timeout: nil) { }` | Execute block with exclusive write lock |
 | `.locked?(path)` | Check if a file is currently locked |
 | `.stale?(pid_file)` | Check if a PID file references a dead process |
+| `.expired?(path)` | Check if a lock has expired based on its TTL |
 | `.owner(path)` | Get lock owner metadata (pid, hostname, acquired_at) |
 | `.break!(path, force: false)` | Break a lock (stale only by default, any with force) |
 
@@ -147,9 +180,10 @@ Philiprehberger::LockKit.stale?('/tmp/my_worker.pid')  # => true/false
 | Method | Description |
 |--------|-------------|
 | `.new(path)` | Create a file lock instance |
-| `#acquire(timeout: nil, auto_cleanup: false, on_wait: nil)` | Acquire exclusive lock with optional timeout, cleanup, and wait callback |
+| `#acquire(timeout: nil, auto_cleanup: false, on_wait: nil, ttl: nil)` | Acquire exclusive lock with optional timeout, cleanup, wait callback, and TTL |
 | `#release` | Release the lock and close the file handle |
-| `#locked?` | Check if the file is currently locked |
+| `#locked?` | Check if the file is currently locked (false if expired) |
+| `#expired?` | Check if the lock has expired based on its TTL |
 | `#owner` | Get lock owner metadata |
 
 ### `LockKit::PidLock`
@@ -157,9 +191,10 @@ Philiprehberger::LockKit.stale?('/tmp/my_worker.pid')  # => true/false
 | Method | Description |
 |--------|-------------|
 | `.new(name, dir: Dir.tmpdir)` | Create a PID lock instance |
-| `#acquire(auto_cleanup: false)` | Acquire PID lock, raises if held by a living process |
+| `#acquire(auto_cleanup: false, ttl: nil)` | Acquire PID lock with optional TTL, raises if held by a living process |
 | `#release` | Release lock and remove PID file |
-| `#locked?` | Check if lock is held by a living process |
+| `#locked?` | Check if lock is held by a living process (false if expired) |
+| `#expired?` | Check if the lock has expired based on its TTL |
 | `#stale?` | Check if PID file references a dead process |
 | `#owner` | Get lock owner metadata |
 

data/lib/philiprehberger/lock_kit/file_lock.rb

@@ -22,9 +22,12 @@ module Philiprehberger
       # @param timeout [Numeric, nil] seconds to wait before raising; nil means non-blocking single attempt
       # @param auto_cleanup [Boolean] when true, check for stale locks and remove them
       # @param on_wait [Proc, nil] callback invoked every 0.5s while waiting; receives elapsed seconds
+      # @param ttl [Numeric, nil] time-to-live in seconds; lock expires after this duration
       # @return [true] when the lock is acquired
       # @raise [LockKit::Error] if the lock cannot be acquired
-      def acquire(timeout: nil, auto_cleanup: false, on_wait: nil)
+      def acquire(timeout: nil, auto_cleanup: false, on_wait: nil, ttl: nil)
+        @ttl = ttl
+
         if auto_cleanup
           cleanup_stale_lock
         end
@@ -79,10 +82,12 @@ module Philiprehberger
       #
       # Opens the file, attempts a non-blocking exclusive lock, and immediately
       # releases it. Returns true if the lock attempt fails (file is locked).
+      # Returns false if the lock has expired (TTL elapsed).
       #
       # @return [Boolean]
       def locked?
         return false unless File.exist?(@path)
+        return false if expired?
 
         f = File.open(@path, File::CREAT | File::RDWR)
         got_lock = f.flock(File::LOCK_EX | File::LOCK_NB)
@@ -96,6 +101,24 @@ module Philiprehberger
         end
       end
 
+      # Check whether the lock has expired based on its TTL
+      #
+      # @return [Boolean] true if the lock metadata contains an expires_at time that has passed
+      def expired?
+        return false unless File.exist?(@meta_path)
+
+        content = File.read(@meta_path).strip
+        return false if content.empty?
+
+        data = JSON.parse(content)
+        expires_at = data['expires_at']
+        return false unless expires_at
+
+        Time.parse(expires_at) <= Time.now
+      rescue JSON::ParserError, Errno::ENOENT
+        false
+      end
+
       # Read lock owner metadata
       #
       # @return [Hash, nil] hash with :pid, :hostname, :acquired_at keys or nil
@@ -123,6 +146,7 @@ module Philiprehberger
           'hostname' => Socket.gethostname,
           'acquired_at' => Time.now.iso8601
         }
+        metadata['expires_at'] = (Time.now + @ttl).iso8601 if @ttl
         File.write(@meta_path, JSON.generate(metadata))
       end
 
@@ -142,6 +166,15 @@ module Philiprehberger
         return if content.empty?
 
         data = JSON.parse(content)
+
+        # Check TTL expiration
+        expires_at = data['expires_at']
+        if expires_at && Time.parse(expires_at) <= Time.now
+          FileUtils.rm_f(meta_path)
+          return
+        end
+
+        # Check process liveness
         pid = data['pid']
         return unless pid
 

data/lib/philiprehberger/lock_kit/pid_lock.rb

@@ -29,18 +29,26 @@ module Philiprehberger
       # automatically cleaned up.
       #
       # @param auto_cleanup [Boolean] when true, automatically remove stale locks
+      # @param ttl [Numeric, nil] time-to-live in seconds; lock expires after this duration
       # @return [true] when the lock is acquired
       # @raise [LockKit::Error] if the lock is held by a living process
-      def acquire(auto_cleanup: false)
-        if File.exist?(@pid_path)
-          existing_pid = read_pid
+      def acquire(auto_cleanup: false, ttl: nil)
+        @ttl = ttl
 
-          if existing_pid && process_alive?(existing_pid)
-            raise Error, "Lock '#{@name}' is held by process #{existing_pid}"
+        if File.exist?(@pid_path)
+          # Check TTL expiration first
+          if lock_expired?
+            FileUtils.rm_f(@pid_path)
+          else
+            existing_pid = read_pid
+
+            if existing_pid && process_alive?(existing_pid)
+              raise Error, "Lock '#{@name}' is held by process #{existing_pid}"
+            end
+
+            # Stale PID file — remove it
+            FileUtils.rm_f(@pid_path)
           end
-
-          # Stale PID file — remove it
-          FileUtils.rm_f(@pid_path)
         end
 
         metadata = {
@@ -48,6 +56,7 @@ module Philiprehberger
           'hostname' => Socket.gethostname,
           'acquired_at' => Time.now.iso8601
         }
+        metadata['expires_at'] = (Time.now + ttl).iso8601 if ttl
         File.write(@pid_path, JSON.generate(metadata))
         @acquired = true
         true
@@ -68,9 +77,12 @@ module Philiprehberger
 
       # Check whether the lock is currently held by a living process
       #
+      # Returns false if the lock has expired (TTL elapsed).
+      #
       # @return [Boolean]
       def locked?
         return false unless File.exist?(@pid_path)
+        return false if expired?
 
         pid = read_pid
         return false unless pid
@@ -90,6 +102,13 @@ module Philiprehberger
         !process_alive?(pid)
       end
 
+      # Check whether the lock has expired based on its TTL
+      #
+      # @return [Boolean] true if the lock metadata contains an expires_at time that has passed
+      def expired?
+        lock_expired?
+      end
+
       # Read lock owner metadata from the PID file
       #
       # @return [Hash, nil] hash with :pid, :hostname, :acquired_at keys or nil
@@ -103,6 +122,23 @@ module Philiprehberger
 
       private
 
+      def lock_expired?
+        return false unless File.exist?(@pid_path)
+
+        content = File.read(@pid_path).strip
+        return false if content.empty?
+
+        data = JSON.parse(content)
+        return false unless data.is_a?(Hash)
+
+        expires_at = data['expires_at']
+        return false unless expires_at
+
+        Time.parse(expires_at) <= Time.now
+      rescue JSON::ParserError, Errno::ENOENT
+        false
+      end
+
       # @return [Integer, nil]
       def read_pid
         content = File.read(@pid_path).strip

data/lib/philiprehberger/lock_kit/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module LockKit
-    VERSION = '0.2.3'
+    VERSION = '0.4.0'
   end
 end

data/lib/philiprehberger/lock_kit.rb

@@ -17,12 +17,13 @@ module Philiprehberger
     # @param timeout [Numeric, nil] seconds to wait before raising
     # @param auto_cleanup [Boolean] automatically remove stale locks before acquiring
     # @param on_wait [Proc, nil] callback invoked every 0.5s while waiting; receives elapsed seconds
+    # @param ttl [Numeric, nil] time-to-live in seconds; lock expires after this duration
     # @yield block to execute while the lock is held
     # @return [Object] the return value of the block
     # @raise [Error] if the lock cannot be acquired
-    def self.with_file_lock(path, timeout: nil, auto_cleanup: false, on_wait: nil, &block)
+    def self.with_file_lock(path, timeout: nil, auto_cleanup: false, on_wait: nil, ttl: nil, &block)
       lock = FileLock.new(path)
-      lock.acquire(timeout: timeout, auto_cleanup: auto_cleanup, on_wait: on_wait)
+      lock.acquire(timeout: timeout, auto_cleanup: auto_cleanup, on_wait: on_wait, ttl: ttl)
       begin
         block.call
       ensure
@@ -35,12 +36,13 @@ module Philiprehberger
     # @param name [String] lock name
     # @param dir [String] directory for the PID file
     # @param auto_cleanup [Boolean] automatically remove stale locks before acquiring
+    # @param ttl [Numeric, nil] time-to-live in seconds; lock expires after this duration
     # @yield block to execute while the lock is held
     # @return [Object] the return value of the block
     # @raise [Error] if the lock is held by another process
-    def self.with_pid_lock(name, dir: Dir.tmpdir, auto_cleanup: false, &block)
+    def self.with_pid_lock(name, dir: Dir.tmpdir, auto_cleanup: false, ttl: nil, &block)
       lock = PidLock.new(name, dir: dir)
-      lock.acquire(auto_cleanup: auto_cleanup)
+      lock.acquire(auto_cleanup: auto_cleanup, ttl: ttl)
       begin
         block.call
       ensure
@@ -87,6 +89,35 @@ module Philiprehberger
       end
     end
 
+    # Execute a block with a file lock, retrying with exponential backoff on failure
+    #
+    # @param path [String] path to the lock file
+    # @param retries [Integer] maximum number of attempts
+    # @param delay [Numeric] initial delay in seconds between retries
+    # @param backoff [Numeric] multiplier applied to delay after each failed attempt
+    # @param timeout [Numeric, nil] seconds to wait per acquire attempt
+    # @param auto_cleanup [Boolean] automatically remove stale locks before acquiring
+    # @param ttl [Numeric, nil] time-to-live in seconds; lock expires after this duration
+    # @yield block to execute while the lock is held
+    # @return [Object] the return value of the block
+    # @raise [Error] if all retry attempts are exhausted
+    def self.with_retry_lock(path, retries: 3, delay: 0.1, backoff: 2, timeout: nil, auto_cleanup: true, ttl: nil, &block)
+      attempts = 0
+      current_delay = delay
+
+      loop do
+        attempts += 1
+        begin
+          return with_file_lock(path, timeout: timeout, auto_cleanup: auto_cleanup, ttl: ttl, &block)
+        rescue Error
+          raise if attempts >= retries
+
+          sleep current_delay
+          current_delay *= backoff
+        end
+      end
+    end
+
     # Check if a file is currently locked by another process
     #
     # @param path [String] path to the lock file
@@ -123,6 +154,33 @@ module Philiprehberger
       false
     end
 
+    # Check if a lock has expired based on its TTL
+    #
+    # @param path [String] path to the lock file or PID file
+    # @return [Boolean] true if the lock metadata contains an expires_at time that has passed
+    def self.expired?(path)
+      # Check file lock metadata
+      meta_path = "#{path}.meta"
+      target = if File.exist?(meta_path)
+                 meta_path
+               elsif File.exist?(path)
+                 path
+               end
+
+      return false unless target
+
+      content = File.read(target).strip
+      return false if content.empty?
+
+      data = JSON.parse(content)
+      expires_at = data['expires_at']
+      return false unless expires_at
+
+      Time.parse(expires_at) <= Time.now
+    rescue JSON::ParserError, Errno::ENOENT
+      false
+    end
+
     # Get lock owner metadata
     #
     # @param path [String] path to the lock file or PID file

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-lock_kit
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.4.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-09 00:00:00.000000000 Z
+date: 2026-04-16 00:00:00.000000000 Z
 dependencies: []
 description: File locks using flock and PID file locks with stale detection for coordinating
   between processes. Timeout support and automatic cleanup.
@@ -53,6 +53,6 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: File-based and PID locking for process coordination with stale lock detection,
-  read-write locks, and lock owner identification
+summary: File-based and PID locking for process coordination with TTL expiration,
+  stale detection, read-write locks, and lock owner identification
 test_files: []