philiprehberger-lock_kit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4323796d385deb9f9a2280dbd05aad5a442738b62fd126f2a9309ded2009d4e7
+  data.tar.gz: a552375e35331d9bcbeb02d7ffd09a1c27c9edd26114eb76a299cae9ff54f0b9
+SHA512:
+  metadata.gz: cd045a2839a2885aa218b11146c2af5c43ee04de2c13934ba1c4dbb02e587bd9f6d1491a7f0cce7d31c8e01f6646cd54e0a45780623e5af0cc8631b1d5b2002c
+  data.tar.gz: 5f309ce7a1b7d03c4c86686e23766264e51118b3f8abc13c3c8e7cebd5ac9ef0bac66f07ebc544f06f753b0bf4cd6e33173278341cd71c79a56a1c9c948d473a

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this gem will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-26
+
+### Added
+- Initial release
+- `FileLock` class with exclusive file locking via `flock(2)`
+- `PidLock` class with PID file locking and stale process detection
+- `with_file_lock` convenience method with optional timeout
+- `with_pid_lock` convenience method with automatic cleanup
+- `locked?` and `stale?` module-level query methods

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 philiprehberger
+
+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.

data/README.md

@@ -0,0 +1,119 @@
+# philiprehberger-lock_kit
+
+[![Tests](https://github.com/philiprehberger/rb-lock-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-lock-kit/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/philiprehberger-lock_kit.svg)](https://rubygems.org/gems/philiprehberger-lock_kit)
+[![License](https://img.shields.io/github/license/philiprehberger/rb-lock-kit)](LICENSE)
+[![Sponsor](https://img.shields.io/badge/sponsor-GitHub%20Sponsors-ec6cb9)](https://github.com/sponsors/philiprehberger)
+
+File-based and PID locking for process coordination
+
+## Requirements
+
+- Ruby >= 3.1
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "philiprehberger-lock_kit"
+```
+
+Or install directly:
+
+```bash
+gem install philiprehberger-lock_kit
+```
+
+## Usage
+
+```ruby
+require "philiprehberger/lock_kit"
+
+Philiprehberger::LockKit.with_file_lock("/tmp/my.lock") do
+  # exclusive work here
+end
+```
+
+### File Locking with Timeout
+
+```ruby
+Philiprehberger::LockKit.with_file_lock("/tmp/my.lock", timeout: 5) do
+  # waits up to 5 seconds for the lock
+end
+```
+
+### PID File Locking
+
+```ruby
+Philiprehberger::LockKit.with_pid_lock("my_worker") do
+  # only one process with this name can run at a time
+end
+```
+
+### Manual File Lock
+
+```ruby
+lock = Philiprehberger::LockKit::FileLock.new("/tmp/my.lock")
+lock.acquire(timeout: 10)
+# ... do work ...
+lock.release
+```
+
+### Manual PID Lock
+
+```ruby
+lock = Philiprehberger::LockKit::PidLock.new("my_worker", dir: "/var/run")
+lock.acquire
+# ... do work ...
+lock.release
+```
+
+### Checking Lock Status
+
+```ruby
+Philiprehberger::LockKit.locked?("/tmp/my.lock")    # => true/false
+Philiprehberger::LockKit.stale?("/tmp/my_worker.pid") # => true/false
+```
+
+## API
+
+### `LockKit`
+
+| Method | Description |
+|--------|-------------|
+| `.with_file_lock(path, timeout: nil) { }` | Execute block with exclusive file lock |
+| `.with_pid_lock(name, dir: Dir.tmpdir) { }` | Execute block with PID file lock |
+| `.locked?(path)` | Check if a file is currently locked |
+| `.stale?(pid_file)` | Check if a PID file references a dead process |
+
+### `LockKit::FileLock`
+
+| Method | Description |
+|--------|-------------|
+| `.new(path)` | Create a file lock instance |
+| `#acquire(timeout: nil)` | Acquire exclusive lock, optional timeout in seconds |
+| `#release` | Release the lock and close the file handle |
+| `#locked?` | Check if the file is currently locked |
+
+### `LockKit::PidLock`
+
+| Method | Description |
+|--------|-------------|
+| `.new(name, dir: Dir.tmpdir)` | Create a PID lock instance |
+| `#acquire` | Acquire PID lock, raises if held by a living process |
+| `#release` | Release lock and remove PID file |
+| `#locked?` | Check if lock is held by a living process |
+| `#stale?` | Check if PID file references a dead process |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+[MIT](LICENSE)

data/lib/philiprehberger/lock_kit/file_lock.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module LockKit
+    # Exclusive file lock using flock(2)
+    #
+    # Provides process-level mutual exclusion via the filesystem. The lock is
+    # advisory and relies on all participants using the same lock file path.
+    class FileLock
+      # @param path [String] path to the lock file
+      def initialize(path)
+        @path = path
+        @file = nil
+      end
+
+      # Acquire an exclusive lock on the file
+      #
+      # @param timeout [Numeric, nil] seconds to wait before raising; nil means non-blocking single attempt
+      # @return [true] when the lock is acquired
+      # @raise [LockKit::Error] if the lock cannot be acquired
+      def acquire(timeout: nil)
+        @file = File.open(@path, File::CREAT | File::RDWR)
+
+        if timeout.nil?
+          unless @file.flock(File::LOCK_EX | File::LOCK_NB)
+            close_file
+            raise Error, "Could not acquire lock on #{@path}"
+          end
+        else
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+
+          until @file.flock(File::LOCK_EX | File::LOCK_NB)
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            if remaining <= 0
+              close_file
+              raise Error, "Timeout acquiring lock on #{@path} after #{timeout}s"
+            end
+
+            sleep [0.05, remaining].min
+          end
+        end
+
+        true
+      end
+
+      # Release the lock and close the file handle
+      #
+      # @return [void]
+      def release
+        return unless @file
+
+        @file.flock(File::LOCK_UN)
+        close_file
+      end
+
+      # Check whether the file is currently locked by another process
+      #
+      # Opens the file, attempts a non-blocking exclusive lock, and immediately
+      # releases it. Returns true if the lock attempt fails (file is locked).
+      #
+      # @return [Boolean]
+      def locked?
+        return false unless File.exist?(@path)
+
+        f = File.open(@path, File::CREAT | File::RDWR)
+        got_lock = f.flock(File::LOCK_EX | File::LOCK_NB)
+        if got_lock
+          f.flock(File::LOCK_UN)
+          f.close
+          false
+        else
+          f.close
+          true
+        end
+      end
+
+      private
+
+      def close_file
+        @file&.close
+        @file = nil
+      end
+    end
+  end
+end

data/lib/philiprehberger/lock_kit/pid_lock.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'tmpdir'
+
+module Philiprehberger
+  module LockKit
+    # PID-file based lock with stale process detection
+    #
+    # Writes the current process ID to a file. Other processes can check the
+    # file to determine if the lock holder is still alive, enabling automatic
+    # recovery from crashed processes.
+    class PidLock
+      # @param name [String] lock name (used as the PID file basename)
+      # @param dir [String] directory for the PID file (defaults to system tmpdir)
+      def initialize(name, dir: Dir.tmpdir)
+        @name = name
+        @dir = dir
+        @pid_path = File.join(dir, "#{name}.pid")
+        @acquired = false
+      end
+
+      # Acquire the PID lock
+      #
+      # Creates a PID file containing the current process ID. If a PID file
+      # already exists, checks whether the owning process is still alive. Stale
+      # PID files from dead processes are automatically cleaned up.
+      #
+      # @return [true] when the lock is acquired
+      # @raise [LockKit::Error] if the lock is held by a living process
+      def acquire
+        if File.exist?(@pid_path)
+          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
+
+        File.write(@pid_path, Process.pid.to_s)
+        @acquired = true
+        true
+      end
+
+      # Release the lock by removing the PID file
+      #
+      # Only removes the file if it was written by this process.
+      #
+      # @return [void]
+      def release
+        return unless @acquired
+
+        File.delete(@pid_path) if File.exist?(@pid_path) && read_pid == Process.pid
+
+        @acquired = false
+      end
+
+      # Check whether the lock is currently held by a living process
+      #
+      # @return [Boolean]
+      def locked?
+        return false unless File.exist?(@pid_path)
+
+        pid = read_pid
+        return false unless pid
+
+        process_alive?(pid)
+      end
+
+      # Check whether the PID file references a dead process
+      #
+      # @return [Boolean]
+      def stale?
+        return false unless File.exist?(@pid_path)
+
+        pid = read_pid
+        return true unless pid
+
+        !process_alive?(pid)
+      end
+
+      private
+
+      # @return [Integer, nil]
+      def read_pid
+        content = File.read(@pid_path).strip
+        return nil if content.empty?
+
+        Integer(content)
+      rescue ArgumentError, Errno::ENOENT
+        nil
+      end
+
+      # @param pid [Integer]
+      # @return [Boolean]
+      def process_alive?(pid)
+        Process.kill(0, pid)
+        true
+      rescue Errno::ESRCH
+        false
+      rescue Errno::EPERM
+        # Process exists but we don't have permission to signal it
+        true
+      end
+    end
+  end
+end

data/lib/philiprehberger/lock_kit/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module LockKit
+    VERSION = '0.1.0'
+  end
+end

data/lib/philiprehberger/lock_kit.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative 'lock_kit/version'
+require_relative 'lock_kit/file_lock'
+require_relative 'lock_kit/pid_lock'
+
+module Philiprehberger
+  module LockKit
+    class Error < StandardError; end
+
+    # Execute a block while holding an exclusive file lock
+    #
+    # @param path [String] path to the lock file
+    # @param timeout [Numeric, nil] seconds to wait before raising
+    # @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, &block)
+      lock = FileLock.new(path)
+      lock.acquire(timeout: timeout)
+      begin
+        block.call
+      ensure
+        lock.release
+      end
+    end
+
+    # Execute a block while holding a PID file lock
+    #
+    # @param name [String] lock name
+    # @param dir [String] directory for the PID file
+    # @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, &block)
+      lock = PidLock.new(name, dir: dir)
+      lock.acquire
+      begin
+        block.call
+      ensure
+        lock.release
+      end
+    end
+
+    # Check if a file is currently locked by another process
+    #
+    # @param path [String] path to the lock file
+    # @return [Boolean]
+    def self.locked?(path)
+      FileLock.new(path).locked?
+    end
+
+    # Check if a PID file references a dead process
+    #
+    # @param pid_file [String] path to the PID file
+    # @return [Boolean]
+    def self.stale?(pid_file)
+      return false unless File.exist?(pid_file)
+
+      content = File.read(pid_file).strip
+      return true if content.empty?
+
+      pid = Integer(content)
+      Process.kill(0, pid)
+      false
+    rescue ArgumentError
+      true
+    rescue Errno::ESRCH
+      true
+    rescue Errno::EPERM
+      false
+    end
+  end
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: philiprehberger-lock_kit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Philip Rehberger
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-27 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.
+email:
+- me@philiprehberger.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/philiprehberger/lock_kit.rb
+- lib/philiprehberger/lock_kit/file_lock.rb
+- lib/philiprehberger/lock_kit/pid_lock.rb
+- lib/philiprehberger/lock_kit/version.rb
+homepage: https://github.com/philiprehberger/rb-lock-kit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/philiprehberger/rb-lock-kit
+  source_code_uri: https://github.com/philiprehberger/rb-lock-kit
+  changelog_uri: https://github.com/philiprehberger/rb-lock-kit/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/philiprehberger/rb-lock-kit/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: File-based and PID locking for process coordination
+test_files: []