pidfd 0.6.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 61a5d615dfec6deefe6cb78906b3be7887fb747696ac911c91dafabf5e123db5
+  data.tar.gz: 7a7a6d725b86d614ea72d61f14f19d9ad3b14a934eb5df16a7a434441d1b7224
+SHA512:
+  metadata.gz: e7be3b9c2c7127e959ec114d9ae0d460be6ba618dc3b39c681f8e9915a03ff218f349a423571ad0e0ded86ce542469495406c32457c443ec91f498cc5efe1357
+  data.tar.gz: 2150b342587007ed488338afb0f5b1a818768d98faba2b3eb2a407d9ebf6753beb430d588c530ba6aa52bbe2bf84ddaa31afb2a80c5d7c4ceb8af1c48aab7e2d

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Pidfd Changelog
+
+## 0.6.0 (2025-09-05)
+- [Breaking] **BREAKING CHANGE**: Moved main API from `Pidfd::Pidfd` to `Pidfd` class
+  - Old: `pidfd = Pidfd::Pidfd.new(pid)` → New: `pidfd = Pidfd.new(pid)`
+  - Old: `Pidfd::Pidfd.supported?` → New: `Pidfd.supported?`
+  - Old: `Pidfd::Pidfd.pidfd_open_syscall = 434` → New: `Pidfd.pidfd_open_syscall = 434`
+  - Error classes remain namespaced as `Pidfd::Errors::*`
+  - This simplifies the API and removes redundant nested class structure
+
+## 0.5.0 (2025-09-05)
+- [Feature] Initial release extracted from Karafka framework.
+- [Feature] Core pidfd functionality for Linux 5.3+.
+- [Feature] `Pidfd::Pidfd` class with process management capabilities.
+- [Feature] `#alive?` method for race-free process status checking.
+- [Feature] `#signal` method for safe signal delivery.
+- [Feature] `#cleanup` method for zombie process reaping.
+- [Feature] Platform support detection via `Pidfd::Pidfd.supported?`.
+- [Feature] Configurable syscall numbers for different architectures.
+- [Feature] Thread-safe operations with mutex protection.
+- [Feature] Non-blocking process monitoring using IO.select.
+- [Feature] Comprehensive error handling with custom exceptions.
+- [Feature] Full test suite with RSpec.
+- [Feature] GitHub Actions CI/CD pipeline.
+- [Feature] Documentation and usage examples.
+- [Enhancement] Uses FFI for direct syscall bindings.
+- [Enhancement] Supports pidfd_open and pidfd_send_signal syscalls.
+- [Enhancement] Implements waitid for process cleanup.
+- [Enhancement] Compatible with Ruby 3.2+.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Maciej Mensfeld
+
+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,231 @@
+# Pidfd
+
+[![Gem Version](https://badge.fury.io/rb/pidfd.svg)](https://rubygems.org/gems/pidfd)
+[![Build Status](https://github.com/mensfeld/pidfd/actions/workflows/ci.yml/badge.svg)](https://github.com/mensfeld/pidfd/actions/workflows/ci.yml)
+
+A Ruby wrapper for Linux pidfd (Process File Descriptor) system calls, providing safer process management with guaranteed process identity.
+
+## What is pidfd?
+
+Process file descriptors (pidfd) were introduced in Linux 5.3 (2019) to solve fundamental problems with traditional PID-based process management:
+
+### The Problem with PIDs
+
+Traditional Unix PIDs have a critical flaw: **PID reuse**. When a process dies, its PID can be immediately reassigned to a new, unrelated process. This creates race conditions where:
+
+- You might send signals to the wrong process
+- Process state checks become unreliable
+- Security vulnerabilities can arise from PID confusion
+
+### The pidfd Solution
+
+Pidfds provide a **stable reference** to a process that remains valid even if the PID is reused. Key benefits:
+
+- **Race-free signal delivery** - Signals always go to the intended process
+- **Reliable process monitoring** - Know definitively when a process exits
+- **Thread-safe operations** - No TOCTTOU races
+- **Pollable file descriptors** - Integrate with event loops efficiently
+
+## When to Use This Gem
+
+Use pidfd when you need:
+
+- **Reliable process management** in production environments
+- **Non-child process monitoring** without being the parent
+- **High-security applications** where PID confusion is unacceptable
+- **Systems with high process churn** where PID reuse is common
+- **Libraries operating in uncontrolled environments**
+
+Don't use pidfd for:
+- macOS or Windows (Linux-only feature)
+- Kernels older than Linux 5.3
+- Simple parent-child relationships (traditional wait works fine)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'pidfd'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install pidfd
+```
+
+## Requirements
+
+- Linux kernel 5.3 or newer
+- Ruby 3.2 or newer
+- FFI gem
+
+## Usage
+
+### Basic Process Management
+
+```ruby
+require 'pidfd'
+
+# Create a pidfd for a process
+process = fork { sleep 10 }
+pidfd = Pidfd.new(process)
+
+# Check if process is alive
+pidfd.alive? # => true
+
+# Send a signal safely
+pidfd.signal('TERM') # => true (signal sent)
+
+# Clean up zombie process after it exits
+pidfd.cleanup
+```
+
+### Monitoring Non-Child Processes
+
+```ruby
+# Monitor any process by PID (requires appropriate permissions)
+nginx_pid = File.read('/var/run/nginx.pid').to_i
+pidfd = Pidfd.new(nginx_pid)
+
+# Check status without race conditions
+if pidfd.alive?
+  puts "Nginx is running"
+else
+  puts "Nginx has stopped"
+  pidfd.cleanup
+end
+```
+
+### Safe Signal Delivery
+
+```ruby
+# Traditional approach (UNSAFE - race condition)
+Process.kill('TERM', pid) # Might hit wrong process if PID was reused!
+
+# Pidfd approach (SAFE)
+pidfd = Pidfd.new(pid)
+pidfd.signal('TERM') # Guaranteed to hit the right process or fail safely
+```
+
+### Integration with Event Loops
+
+```ruby
+# Pidfd provides a pollable file descriptor
+pidfd = Pidfd.new(child_pid)
+
+# Use with IO.select for non-blocking monitoring
+loop do
+  if pidfd.alive?
+    # Process still running
+    sleep 0.1
+  else
+    # Process exited
+    pidfd.cleanup
+    break
+  end
+end
+```
+
+## Platform Support
+
+### Checking Support
+
+```ruby
+if Pidfd.supported?
+  puts "pidfd is supported on this system"
+else
+  puts "pidfd is not available (wrong OS or kernel version)"
+end
+```
+
+### Fallback Strategy
+
+```ruby
+def safe_process_check(pid)
+  if Pidfd.supported?
+    pidfd = Pidfd.new(pid)
+    result = pidfd.alive?
+    pidfd.cleanup unless result
+    result
+  else
+    # Fallback to traditional (less safe) approach
+    Process.kill(0, pid)
+    true
+  rescue Errno::ESRCH
+    false
+  end
+end
+```
+
+## Configuration
+
+### Custom Syscall Numbers
+
+Different architectures may use different syscall numbers. You can configure them:
+
+```ruby
+# Default values for x86_64
+Pidfd.pidfd_open_syscall = 434
+Pidfd.pidfd_signal_syscall = 424
+
+# For other architectures, consult your system headers
+```
+
+## Error Handling
+
+```ruby
+begin
+  pidfd = Pidfd.new(pid)
+rescue Pidfd::Errors::PidfdOpenFailedError => e
+  # Process doesn't exist or permission denied
+  puts "Could not open pidfd: #{e.message}"
+end
+
+begin
+  pidfd.signal('TERM')
+rescue Pidfd::Errors::PidfdSignalFailedError => e
+  # Signal delivery failed
+  puts "Could not send signal: #{e.message}"
+end
+```
+
+## Performance Considerations
+
+- **Efficient**: Pidfd operations are kernel-level, very fast
+- **Low overhead**: Minimal memory usage per pidfd
+- **Scalable**: Handles thousands of processes efficiently
+- **Non-blocking**: Supports async operation patterns
+
+## Security
+
+Pidfd provides significant security improvements:
+
+- Prevents signal delivery to wrong processes
+- Eliminates PID confusion attacks
+- Provides capability-based process references
+- Works with Linux security modules (SELinux, AppArmor)
+
+## Further Reading
+
+- [Linux pidfd documentation](https://man7.org/linux/man-pages/man2/pidfd_open.2.html)
+- [LWN: Process-descriptor file descriptors](https://lwn.net/Articles/801319/)
+- [Bringing Linux pidfd to Ruby](https://mensfeld.github.io/bringing_linux_pidfd_to_ruby/)
+
+## Author
+
+Based on the pidfd implementation in [Karafka](https://github.com/karafka/karafka) by Maciej Mensfeld.
+
+## Acknowledgments
+
+Special thanks to:
+- The Linux kernel team for implementing pidfd
+- KJ Tsanaktsidis for Ruby core contributions discussions
+- The Karafka community for battle-testing this implementation

data/lib/pidfd/errors.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class Pidfd
+  # Namespace for all the pidfd errors
+  module Errors
+    # Base error class for all pidfd errors
+    BaseError = Class.new(StandardError)
+
+    # Error raised when pidfd_open syscall fails
+    PidfdOpenFailedError = Class.new(BaseError)
+
+    # Error raised when pidfd_signal syscall fails
+    PidfdSignalFailedError = Class.new(BaseError)
+  end
+end

data/lib/pidfd/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class Pidfd
+  # Current version of the pidfd gem
+  VERSION = '0.6.0'
+end

data/lib/pidfd.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+# Main class that wraps Linux pidfd functionality for Ruby
+class Pidfd
+  extend FFI::Library
+
+  begin
+    ffi_lib FFI::Library::LIBC
+
+    # direct usage of this is only available since glibc 2.36, hence we use bindings and call
+    # it directly via syscalls
+    attach_function :fdpid_open, :syscall, %i[long int uint], :int
+    attach_function :fdpid_signal, :syscall, %i[long int int pointer uint], :int
+    attach_function :waitid, %i[int int pointer uint], :int
+
+    API_SUPPORTED = true
+  # LoadError is a parent to FFI::NotFoundError
+  rescue LoadError
+    API_SUPPORTED = false
+  ensure
+    private_constant :API_SUPPORTED
+  end
+
+  # https://github.com/torvalds/linux/blob/7e90b5c295/include/uapi/linux/wait.h#L20
+  P_PIDFD = 3
+
+  # Wait for child processes that have exited
+  WEXITED = 4
+
+  # Default syscall numbers for x86_64 Linux
+  # These can be overridden if needed for different architectures
+  # Pidfd open call number
+  DEFAULT_PIDFD_OPEN_SYSCALL = 434
+
+  # Pidfd signal call number
+  DEFAULT_PIDFD_SIGNAL_SYSCALL = 424
+
+  private_constant :P_PIDFD, :WEXITED
+
+  class << self
+    # @return [Integer] syscall number for pidfd_open
+    attr_accessor :pidfd_open_syscall
+
+    # @return [Integer] syscall number for pidfd_signal
+    attr_accessor :pidfd_signal_syscall
+
+    # @return [Boolean] true if syscall is supported via FFI
+    def supported?
+      # If we were not even able to load the FFI C lib, it won't be supported
+      return false unless API_SUPPORTED
+      # Won't work on macOS because it does not support pidfd
+      return false if RUBY_DESCRIPTION.include?('darwin')
+      # Won't work on Windows for the same reason as on macOS
+      return false if RUBY_DESCRIPTION.match?(/mswin|ming|cygwin/)
+
+      # There are some OSes like BSD that will have C lib for FFI bindings but will not support
+      # the needed syscalls. In such cases, we can just try and fail, which will indicate it
+      # won't work. The same applies to using new glibc on an old kernel.
+      new(::Process.pid)
+
+      true
+    rescue Errors::PidfdOpenFailedError
+      false
+    end
+  end
+
+  # Set default syscall numbers
+  self.pidfd_open_syscall = DEFAULT_PIDFD_OPEN_SYSCALL
+  self.pidfd_signal_syscall = DEFAULT_PIDFD_SIGNAL_SYSCALL
+
+  # @param pid [Integer] pid of the node we want to work with
+  def initialize(pid)
+    @mutex = Mutex.new
+
+    @pid = pid
+    @pidfd = open_pidfd(pid)
+    @pidfd_io = IO.new(@pidfd)
+  end
+
+  # @return [Boolean] true if given process is alive, false if no longer
+  def alive?
+    @pidfd_select ||= [@pidfd_io]
+
+    if @mutex.owned?
+      return false if @cleaned
+
+      IO.select(@pidfd_select, nil, nil, 0).nil?
+    else
+      @mutex.synchronize do
+        return false if @cleaned
+
+        IO.select(@pidfd_select, nil, nil, 0).nil?
+      end
+    end
+  end
+
+  # Cleans the zombie process
+  # @note This should run **only** on processes that exited, otherwise will wait
+  def cleanup
+    @mutex.synchronize do
+      return if @cleaned
+
+      waitid(P_PIDFD, @pidfd, nil, WEXITED)
+
+      @pidfd_io.close
+      @pidfd_select = nil
+      @pidfd_io = nil
+      @pidfd = nil
+      @cleaned = true
+    end
+  end
+
+  # Sends given signal to the process using its pidfd
+  # @param sig_name [String] signal name
+  # @return [Boolean] true if signal was sent, otherwise false or error raised. `false`
+  #   returned when we attempt to send a signal to a dead process
+  # @note It will not send signals to dead processes
+  def signal(sig_name)
+    @mutex.synchronize do
+      return false if @cleaned
+      # Never signal processes that are dead
+      return false unless alive?
+
+      result = fdpid_signal(
+        self.class.pidfd_signal_syscall,
+        @pidfd,
+        Signal.list.fetch(sig_name),
+        nil,
+        0
+      )
+
+      return true if result.zero?
+
+      raise Errors::PidfdSignalFailedError, result
+    end
+  end
+
+  private
+
+  # Opens a pidfd for the provided pid
+  # @param pid [Integer]
+  # @return [Integer] pidfd
+  def open_pidfd(pid)
+    pidfd = fdpid_open(
+      self.class.pidfd_open_syscall,
+      pid,
+      0
+    )
+
+    return pidfd if pidfd != -1
+
+    raise Errors::PidfdOpenFailedError, pidfd
+  end
+end
+
+require_relative 'pidfd/version'
+require_relative 'pidfd/errors'

data/pidfd.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'lib/pidfd/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'pidfd'
+  spec.version = Pidfd::VERSION
+  spec.authors = ['Maciej Mensfeld']
+  spec.email = ['maciej@mensfeld.pl']
+
+  spec.summary = 'Ruby wrapper for Linux pidfd system calls'
+  spec.homepage = 'https://github.com/mensfeld/pidfd'
+  spec.license = 'MIT'
+  spec.description = <<~DESC
+    Provides race-free process management using Linux pidfd (process file descriptors) for safer
+    signal delivery and process monitoring
+  DESC
+
+  spec.required_ruby_version = '>= 3.2.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+  spec.metadata['source_code_uri'] = 'https://github.com/mensfeld/pidfd'
+  spec.metadata['changelog_uri'] = 'https://github.com/mensfeld/pidfd/blob/main/CHANGELOG.md'
+  spec.metadata['documentation_uri'] = 'https://github.com/mensfeld/pidfd#readme'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.glob('{lib}/**/*') + %w[LICENSE CHANGELOG.md README.md pidfd.gemspec]
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'ffi', '>= 1.15'
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: pidfd
+version: !ruby/object:Gem::Version
+  version: 0.6.0
+platform: ruby
+authors:
+- Maciej Mensfeld
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.15'
+description: |
+  Provides race-free process management using Linux pidfd (process file descriptors) for safer
+  signal delivery and process monitoring
+email:
+- maciej@mensfeld.pl
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/pidfd.rb
+- lib/pidfd/errors.rb
+- lib/pidfd/version.rb
+- pidfd.gemspec
+homepage: https://github.com/mensfeld/pidfd
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/mensfeld/pidfd
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/mensfeld/pidfd
+  changelog_uri: https://github.com/mensfeld/pidfd/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/mensfeld/pidfd#readme
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.0
+specification_version: 4
+summary: Ruby wrapper for Linux pidfd system calls
+test_files: []