realuser 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e03f1f6f13c2a98474e2f4fc75b7ff0966730ce3706137dbd7f7bd3fc895cb8f
+  data.tar.gz: b4b2048130f57d58ee35ecfe1f4762afae8eb63d80949e5ef90a290bcefba4f2
+SHA512:
+  metadata.gz: bdee82a998f28f1a8f9ec72147ab8cbc5caeeac9b348c58e304df98cb0ad541fad430990ba602fbb04f7605fe88b94b9736c4af952eada7016fad8b7a9391e02
+  data.tar.gz: 6ed3268db94fbc18ba4a9b34013aefc48bd4eb664700878524212716299fab81601cfe65fde9b330d3642e1b1bb2dc5157c55e9e5962bcf6040aa62a62fc8325

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Julian Kahlert
+
+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,125 @@
+# RealUser
+
+[![Build Status](https://github.com/juliankahlert/realuser/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/juliankahlert/realuser)
+[![GitHub commit activity](https://img.shields.io/github/commit-activity/t/juliankahlert/realuser)](https://github.com/juliankahlert/realuser/commits/)
+[![GitHub Tag](https://img.shields.io/github/v/tag/juliankahlert/realuser)](https://github.com/juliankahlert/realuser)
+[![Gem Version](https://img.shields.io/gem/v/realuser)](https://rubygems.org/gems/realuser)
+[![Codacy Badge](https://app.codacy.com/project/badge/Grade/20103f24ebc747cda2ebe2d2029365f6)](https://app.codacy.com/gh/juliankahlert/realuser/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
+[![Codacy Badge](https://app.codacy.com/project/badge/Coverage/20103f24ebc747cda2ebe2d2029365f6)](https://app.codacy.com/gh/juliankahlert/realuser/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)
+
+## Introduction
+
+The `RealUser` gem provides a simple Ruby interface for retrieving the real user ID (RUID) of a process and its parent processes on Linux systems. It interacts with the `/proc` filesystem to fetch detailed process information and supports both deep and shallow resolution of the RUID.
+
+## Features
+
+- **Retrieve RUID**: Obtain the real user ID of a specific process.
+- **Parent Process Lookup**: Access the RUID of a process’s parent and ancestor processes.
+- **Deep and Shallow Resolution**: Choose between deep resolution (finding the root process) or shallow resolution (finding the nearest ancestor with a different RUID).
+- **Caching**: Efficiently caches results to improve performance.
+
+## Install
+
+The supported installation methods are:
+
+### Using `gitpack`
+
+To install the gem from RubyGems:
+
+```sh
+gitpack add juliankahlert/realuser
+```
+
+### Using `gem`
+
+To install the gem from RubyGems:
+
+```sh
+gem install realuser
+```
+
+### From Source
+
+You can also install the gem from the source repository:
+
+```sh
+git clone https://github.com/juliankahlert/realuser.git
+cd realuser
+gem build realuser.gemspec
+sudo gem install --local realuser-0.1.0.gem
+```
+
+## API Documentation
+
+### `RealUser#ruid(cfg = Process.pid)`
+
+- **Description**: Determines the RUID of a process based on the provided configuration. Can perform deep or shallow resolution based on the options given.
+- **Parameters**:
+  - `cfg` (Integer, Hash): 
+    - If an Integer, it performs a deep resolution for the given `pid`.
+    - If a Hash, it can contain:
+      - `:pid` (Integer): The process ID to resolve. Defaults to the current process.
+      - `:deep` (Boolean): If `true`, performs a deep resolution; if `false` or omitted, performs a shallow resolution.
+- **Returns**: Integer representing the RUID of the process, or `nil` if it cannot be determined.
+
+### `RealUser::Resolver`
+
+- **`.deep(pid)`**
+  - **Description**: Recursively resolves and returns the RUID of the root process ancestor of the specified `pid`.
+  - **Parameters**:
+    - `pid` (Integer): The process ID to start the resolution from.
+  - **Returns**: Integer representing the RUID of the root ancestor, or `nil` if the RUID cannot be determined.
+
+- **`.shallow(pid, pruid = nil)`**
+  - **Description**: Resolves and returns the RUID of the given `pid` or the nearest ancestor where the RUID differs from `pruid`. Recursively checks parent processes if needed.
+  - **Parameters**:
+    - `pid` (Integer): The process ID to start the resolution from.
+    - `pruid` (Integer, optional): The RUID of the parent process to compare against. If provided, will return the RUID of the process if it differs from `pruid`.
+  - **Returns**: Integer representing the RUID of the nearest ancestor with a different RUID, or the RUID of the specified process.
+
+### `RealUser::ProcFs`
+
+- **`.ruid(pid = Process.pid)`**
+  - **Description**: Retrieves the real user ID (RUID) of the process with the specified `pid`. Defaults to the current process ID if `pid` is not provided.
+  - **Parameters**:
+    - `pid` (Integer): The process ID to retrieve the RUID for. Defaults to `Process.pid`.
+  - **Returns**: Integer representing the RUID, or `nil` if the RUID cannot be determined.
+
+- **`.ppid(pid = Process.pid)`**
+  - **Description**: Retrieves the parent process ID (PPID) of the process with the specified `pid`. Defaults to the current process ID if `pid` is not provided.
+  - **Parameters**:
+    - `pid` (Integer): The process ID to retrieve the PPID for. Defaults to `Process.pid`.
+  - **Returns**: Integer representing the PPID, or `nil` if the PPID cannot be determined.
+
+For detailed API documentation, please refer to the [YARD documentation](https://rubydoc.info/github/juliankahlert/realuser).
+
+## Example Usage
+
+Here is an example of how to use the `RealUser` gem to find the RUID of a process and its parent processes:
+
+```ruby
+require 'realuser'
+
+# Create an instance of the RealUser module
+real_user = RealUser.new
+
+# Get the RUID of the current process
+puts "Current process RUID: #{real_user.ruid}"
+
+# Get the RUID of a specific process (PID 1234)
+puts "Process 1234 RUID: #{real_user.ruid(1234)}"
+
+# Perform a deep resolution to find the root RUID of a specific process (PID 1234)
+puts "Root RUID of process 1234: #{real_user.ruid(pid: 1234, deep: true)}"
+
+# Perform a shallow resolution to find the nearest ancestor with a different RUID
+puts "Shallow RUID of process 1234: #{real_user.ruid(pid: 1234, deep: false)}"
+```
+
+## Encouragement for Contribution
+
+Contributions from the community are welcome! If you find any issues, have suggestions for improvements, or want to add new features, please feel free to submit a pull request or open an issue on [GitHub](https://github.com/juliankahlert/realuser).
+
+## License
+
+`RealUser` is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.

data/lib/realuser.rb

@@ -0,0 +1,134 @@
+# lib/realuser.rb
+#
+# MIT License
+#
+# Copyright (c) 2024 Julian Kahlert
+#
+# 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.
+
+module RealUser
+
+  # The `ProcFs` class interacts with the `/proc` filesystem to fetch
+  # information about the real user ID (RUID) and parent process ID (PPID) of a given process.
+  class ProcFs
+
+    # Retrieves the real user ID (RUID) of the process specified by `pid`.
+    # Defaults to the current process ID if none is provided.
+    #
+    # @param pid [Integer] the process ID for which to retrieve the RUID. Defaults to `Process.pid`.
+    # @return [Integer, nil] the real user ID of the process, or `nil` if it cannot be determined.
+    def self.ruid(pid = Process.pid)
+      @ruid_cache ||= {}
+      key = pid.to_s.to_sym
+
+      result = @ruid_cache[key]
+      return result if result
+
+      result = File.stat("/proc/#{pid}").uid
+      @ruid_cache[key] = result
+      result
+    rescue
+      @ruid_cache[key] = nil
+      nil
+    end
+
+    # Retrieves the parent process ID (PPID) of the process specified by `pid`.
+    # Defaults to the current process ID if none is provided.
+    #
+    # @param pid [Integer] the process ID for which to retrieve the PPID. Defaults to `Process.pid`.
+    # @return [Integer, nil] the parent process ID of the process, or `nil` if it cannot be determined.
+    def self.ppid(pid = Process.pid)
+      @ppid_cache ||= {}
+      key = pid.to_s.to_sym
+
+      result = @ppid_cache[key]
+      return result if result
+
+      result = File.read("/proc/#{pid}/status").match(/^PPid:\s+(\d+)/)[1].to_i
+      @ppid_cache[key] = result
+      result
+    rescue
+      @ppid_cache[key] = nil
+      nil
+    end
+  end
+
+  # The `Resolver` class provides methods to resolve the real user ID (RUID) of a process
+  # and its parent processes, either through a deep search (resolving the root RUID) or a shallow search.
+  class Resolver
+
+    # Resolves the real user ID (RUID) of the root process ancestor of the given `pid`.
+    # It recursively traverses the parent processes until it finds the root process.
+    #
+    # @param pid [Integer] the process ID for which to resolve the root RUID.
+    # @return [Integer, nil] the root RUID of the process, or `nil` if it cannot be determined.
+    def self.deep(pid)
+      ppid = ProcFs.ppid(pid)
+
+      # has parent and parent is not init
+      if ppid && ppid > 1
+        deep(ppid)
+      else
+        ProcFs.ruid(pid)
+      end
+    end
+
+    # Resolves the real user ID (RUID) of the given `pid` or its nearest ancestor where
+    # the RUID differs from the process's parent RUID.
+    #
+    # @param pid [Integer] the process ID for which to resolve the shallow RUID.
+    # @param pruid [Integer, nil] the parent process's RUID. Used to compare and stop if a difference is found.
+    # @return [Integer, nil] the RUID of the process or the nearest ancestor with a different RUID.
+    def self.shallow(pid, pruid = nil)
+      ruid = ProcFs.ruid(pid)
+      return ruid if pruid && (ruid != pruid || ruid.nil?)
+
+      ppid = ProcFs.ppid(pid)
+
+      # has parent and parent is not init
+      if ppid && ppid > 1
+        shallow(ppid, ruid)
+      else
+        ruid
+      end
+    end
+  end
+
+  # Determines the real user ID (RUID) of a process, either using a deep or shallow search.
+  # If a `Hash` is provided, the configuration specifies whether to perform a deep search.
+  #
+  # @param cfg [Integer, Hash] the process ID (Integer) or configuration Hash.
+  #   - If an Integer is provided, a deep search is performed.
+  #   - If a Hash is provided, it can contain:
+  #     - `:pid` (Integer): the process ID to resolve. Defaults to the current process.
+  #     - `:deep` (Boolean): whether to perform a deep search. Defaults to shallow.
+  # @return [Integer, nil] the real user ID of the process, or `nil` if it cannot be determined.
+  def self.ruid(cfg = Process.pid)
+    case cfg
+    when Integer
+      Resolver.deep(cfg)
+    when Hash
+      pid = cfg[:pid] || Process.pid
+      deep = cfg[:deep]
+      return Resolver.deep(pid) if deep
+
+      Resolver.shallow(pid)
+    end
+  end
+end

metadata

@@ -0,0 +1,152 @@
+--- !ruby/object:Gem::Specification
+name: realuser
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Julian Kahlert
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2024-09-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: simplecov-cobertura
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: simplecov-console
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.22.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.22.0
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.37
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.37
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.4'
+description: The realuser gem provides a simple API for obtaining the real user ID
+  (RUID) of a process and its parent processes on Linux systems. It leverages the
+  `/proc` filesystem to perform deep and shallow resolution of RUIDs, making it useful
+  for process management and monitoring in Linux environments.
+email:
+- 90937526+juliankahlert@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/realuser.rb
+homepage: https://github.com/juliankahlert/realuser
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://juliankahlert.github.io/realuser/
+  documentation_uri: https://www.rubydoc.info/gems/realuser/0.1.0
+  source_code_uri: https://github.com/juliankahlert/realuser
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.33
+signing_key: 
+specification_version: 4
+summary: Retrieve the real user ID (RUID) of a process and its parent processes.
+test_files: []