potluck 0.0.6 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6881b14c35b5ae6be793e8390d8ab87d1b8220ea78a2803dac55f5ea8c2bc4cf
-  data.tar.gz: e0c7b0e3a472f03dded30e35e38fbad4f8f484a1d3cb44cd4ced99248cdd298c
+  metadata.gz: 9827c82165e843be1296376b9fc09df5802b8a5935094dfe9a0ee25543ed8780
+  data.tar.gz: fc963b6df8213041917fb4f8f44bd257180883d058ac3e365adb4d5a8357c201
 SHA512:
-  metadata.gz: 0ce2edbef44e0f8e27ffb0bb63e717d5f9781f29a27661b72de6bd77b0421f73757a230f5d3193f8e04bbaba8abd9e282d8021af9c4aded66e5e10efd78bb2c7
-  data.tar.gz: 5246bb757a883318ed514c8a5a5a94d5631732170c9622d1b20f92541a419fb36b9b559a3a6967ca700d2ba765ec58a323fed3b39fb464f222a9ca9dfc84e77b
+  metadata.gz: 4dabce647594c290c42a1db1b5c0100ae618ee1e91998272978bae09bd8f89ee6d9838dab506f5dd0dc83532f00ec2c045086f06b02197da2fda4152ca9d3536
+  data.tar.gz: efd26d28db394a6186cd719fa5aca62137eb742b328d50fb9a0cd636f265438a4b047141330657453ebe9d0aa074ed7297541d7dae80eca76aeeb53a63a53c9b

data/VERSION

@@ -1 +1 @@
-0.0.6
+0.0.8

data/lib/potluck/config.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Potluck
+  # Public: Configuration settings for Potluck services.
+  class Config
+    DEFAULT_DIR = File.expand_path(File.join(Dir.home, '.potluck')).freeze
+    OLD_HOMEBREW_PREFIX = '/usr/local'
+
+    attr_writer(:dir, :homebrew_prefix)
+
+    # Public: Create a new instance.
+    #
+    # Yields the instance being created.
+    #
+    # Examples
+    #
+    #   Config.new do |config|
+    #     config.dir = '/etc/potluck'
+    #     config.homebrew_prefix = '/custom/brew'
+    #   end
+    def initialize
+      yield(self) if block_given?
+    end
+
+    # Public: Get the directory path setting.
+    #
+    # Returns the String value.
+    def dir
+      @dir || DEFAULT_DIR
+    end
+
+    # Public: Get the Homebrew prefix path setting.
+    #
+    # Returns the String value.
+    def homebrew_prefix
+      @homebrew_prefix || ENV['HOMEBREW_PREFIX'] || OLD_HOMEBREW_PREFIX
+    end
+  end
+end

data/lib/potluck/service.rb

@@ -1,32 +1,108 @@
 # frozen_string_literal: true
 
+require('English')
 require('fileutils')
 
 module Potluck
-  ##
-  # General error class used for errors encountered with a service.
-  #
+  # Public: General error class used for errors encountered with a service.
   class ServiceError < StandardError; end
 
-  ##
-  # A Ruby interface for configuring, controlling, and interacting with external processes. Serves as a
-  # parent class for service-specific child classes.
-  #
+  # Public: A Ruby interface for configuring, controlling, and interacting with external processes. Serves
+  # as a parent class for service-specific child classes.
   class Service
     SERVICE_PREFIX = 'potluck.npickens.'
-    LAUNCHCTL_ERROR_REGEX = /^-|\t[^0]\t/.freeze
+    LAUNCHCTL_ERROR_REGEX = /^-|\t[^0]\t/
 
-    ##
-    # Creates a new instance.
+    # Public: Get the human-friendly name of the service.
     #
-    # * +logger+ - +Logger+ instance to use for outputting info and error messages (optional). Output will
-    #   be sent to stdout and stderr if none is supplied.
-    # * +manage+ - True if the service runs locally and should be managed by this process (default: true if
-    #   launchctl is available and false otherwise).
+    # Returns the String name.
+    def self.pretty_name
+      @pretty_name ||= to_s.split('::').last
+    end
+
+    # Public: Get the computer-friendly name of the service.
+    #
+    # Returns the String name.
+    def self.service_name
+      @service_name ||= pretty_name.downcase
+    end
+
+    # Public: Get the name for the launchctl service.
+    #
+    # Returns the String name.
+    def self.launchctl_name
+      "#{SERVICE_PREFIX}#{service_name}"
+    end
+
+    # Public: Get the path to the launchctl plist file of the service.
+    #
+    # Returns the String path.
+    def self.plist_path
+      File.join(Potluck.config.dir, "#{launchctl_name}.plist")
+    end
+
+    # Public: Get the content of the launchctl plist file.
+    #
+    # Returns the String content.
+    def self.plist(content = '')
+      <<~XML
+        <?xml version="1.0" encoding="UTF-8"?>
+        #{'<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1' \
+          '.0.dtd">'}
+        <plist version="1.0">
+        <dict>
+          <key>Label</key>
+          <string>#{launchctl_name}</string>
+          <key>RunAtLoad</key>
+          <true/>
+          <key>KeepAlive</key>
+          <false/>
+          #{content.gsub(/^/, '  ').strip}
+        </dict>
+        </plist>
+      XML
+    end
+
+    # Public: Write the service's launchctl plist file to disk.
+    #
+    # Returns nothing.
+    def self.write_plist
+      FileUtils.mkdir_p(File.dirname(plist_path))
+      File.write(plist_path, plist)
+    end
+
+    # Public: Check if launchctl is available.
     #
+    # Returns the boolean result.
+    def self.launchctl?
+      return @@launchctl if defined?(@@launchctl)
+
+      `which launchctl 2>&1`
+
+      @@launchctl = $CHILD_STATUS.success?
+    end
+
+    # Public: Raise an error if launchctl is not available.
+    #
+    # Returns true if launchctl is available.
+    # Raises ServiceError if launchctl is not available.
+    def self.ensure_launchctl!
+      launchctl? || raise(ServiceError, "Cannot manage #{pretty_name}: launchctl not found")
+    end
+
+    # Public: Create a new instance.
+    #
+    # logger: - Logger instance to use in place of sending output to stdin and stderr.
+    # manage: - Boolean specifying if the service runs locally and should be managed by this process
+    #           (defaults to whether or not launchctl is available); or a configuration Hash:
+    #
+    #           status:             - String command for fetching the status of the service.
+    #           status_error_regex: - Regexp that determines if the service is in an error state.
+    #           start:              - String command for starting the service.
+    #           stop:               - String command for stopping the service.
     def initialize(logger: nil, manage: self.class.launchctl?)
       @logger = logger
-      @manage = !!manage
+      @manage = manage
       @manage_with_launchctl = false
 
       if manage.kind_of?(Hash)
@@ -40,33 +116,30 @@ module Potluck
       end
     end
 
-    ##
-    # Returns true if the service is managed.
+    # Public: Check if the service is managed by this process.
     #
+    # Returns the boolean result.
     def manage?
       @manage
     end
 
-    ##
-    # Returns true if the service is managed via launchctl.
+    # Public: Check if the service is managed by launchctl.
     #
+    # Returns the boolean result.
     def manage_with_launchctl?
       @manage_with_launchctl
     end
 
-    ##
-    # Returns the status of the service:
-    #
-    # * +:active+ if the service is managed and running.
-    # * +:inactive+ if the service is not managed or is not running.
-    # * +:error+ if the service is managed and is in an error state.
+    # Public: Get the status of the service.
     #
+    # Returns :active if the service is managed and running, :inactive if the service is not managed or is
+    # not running, or :error if the service is managed and is in an error state.
     def status
       return :inactive unless manage?
 
       output = `#{status_command}`
 
-      if $? != 0
+      if !$CHILD_STATUS.success?
         :inactive
       elsif status_error_regex && output[status_error_regex]
         :error
@@ -75,9 +148,9 @@ module Potluck
       end
     end
 
-    ##
-    # Starts the service if it's managed and is not active.
+    # Public: Start the service if it's managed and is not active.
     #
+    # Returns nothing.
     def start
       return unless manage?
 
@@ -95,9 +168,10 @@ module Potluck
       log("#{self.class.pretty_name} started")
     end
 
-    ##
-    # Stops the service if it's managed and is active or in an error state.
+    # Public: Stop the service if it's managed and is active or in an error state.
     #
+    # Returns nothing.
+    # Raises ServiceError if the service could not be stopped.
     def stop
       return unless manage? && status != :inactive
 
@@ -110,9 +184,9 @@ module Potluck
       log("#{self.class.pretty_name} stopped")
     end
 
-    ##
-    # Restarts the service if it's managed by calling stop and then start.
+    # Public: Restart the service if it's managed.
     #
+    # Returns nothing.
     def restart
       return unless manage?
 
@@ -120,31 +194,32 @@ module Potluck
       start
     end
 
-    ##
-    # Runs a command with the default shell. Raises an error if the command exits with a non-zero status.
+    # Public: Run a command with the default shell.
     #
-    # * +command+ - Command to run.
-    # * +capture_stderr+ - True if stderr should be redirected to stdout; otherwise stderr output will not
-    #   be logged (default: true).
+    # command         - String command to run.
+    # capture_stderr: - Boolean specifying if stderr should be redirected to stdout (if false, stderr output
+    #                   will not be logged).
     #
+    # Returns the String output of the command.
+    # Raises ServiceError if the command exited with a non-zero status.
     def run(command, capture_stderr: true)
       output = `#{command}#{' 2>&1' if capture_stderr}`
-      status = $?
+      status = $CHILD_STATUS
 
-      if status != 0
+      if status.success?
+        output
+      else
         output.split("\n").each { |line| log(line, :error) }
         raise(ServiceError, "Command exited with status #{status.exitstatus}: #{command}")
-      else
-        output
       end
     end
 
-    ##
-    # Logs a message using the logger or stdout/stderr if no logger is configured.
+    # Public: Log a message using the logger or stdout/stderr if no logger is configured.
     #
-    # * +message+ - Message to log.
-    # * +error+ - True if the message is an error (default: false).
+    # message - String message to log.
+    # error   - Boolean specifying if the message is an error.
     #
+    # Returns nothing.
     def log(message, error = false)
       if @logger
         error ? @logger.error(message) : @logger.info(message)
@@ -153,119 +228,47 @@ module Potluck
       end
     end
 
-    ##
-    # Human-friendly name of the service.
-    #
-    def self.pretty_name
-      @pretty_name ||= self.to_s.split('::').last
-    end
-
-    ##
-    # Computer-friendly name of the service.
-    #
-    def self.service_name
-      @service_name ||= pretty_name.downcase
-    end
-
-    ##
-    # Name for the launchctl service.
-    #
-    def self.launchctl_name
-      "#{SERVICE_PREFIX}#{service_name}"
-    end
-
-    ##
-    # Path to the launchctl plist file of the service.
-    #
-    def self.plist_path
-      File.join(DIR, "#{launchctl_name}.plist")
-    end
-
-    ##
-    # Content of the launchctl plist file.
-    #
-    def self.plist(content = '')
-      <<~EOS
-        <?xml version="1.0" encoding="UTF-8"?>
-        #{'<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.'\
-          '0.dtd">'}
-        <plist version="1.0">
-        <dict>
-          <key>Label</key>
-          <string>#{launchctl_name}</string>
-          <key>RunAtLoad</key>
-          <true/>
-          <key>KeepAlive</key>
-          <false/>
-          #{content.gsub(/^/, '  ').strip}
-        </dict>
-        </plist>
-      EOS
-    end
-
-    ##
-    # Writes the service's launchctl plist file to disk.
-    #
-    def self.write_plist
-      FileUtils.mkdir_p(File.dirname(plist_path))
-      File.write(plist_path, plist)
-    end
-
-    ##
-    # Returns true if launchctl is available.
-    #
-    def self.launchctl?
-      defined?(@@launchctl) ? @@launchctl : (@@launchctl = `which launchctl 2>&1` && $? == 0)
-    end
-
-    ##
-    # Checks if launchctl is available and raises an error if not.
-    #
-    def self.ensure_launchctl!
-      launchctl? || raise(ServiceError, "Cannot manage #{pretty_name}: launchctl not found")
-    end
-
     private
 
-    ##
-    # Command to get the status of the service.
+    # Internal: Get the command for fetching the status of the service.
     #
+    # Returns the String command.
     def status_command
       @status_command || "launchctl list 2>&1 | grep #{SERVICE_PREFIX}#{self.class.service_name}"
     end
 
-    ##
-    # Regular expression to check the output of +#status_command+ against to determine if the service is in
-    # an error state.
+    # Internal: Get the regex used to determine if the service is in an error state (by matching the output
+    # of the status command against it).
     #
+    # Returns the Regexp.
     def status_error_regex
       @status_error_regex || LAUNCHCTL_ERROR_REGEX
     end
 
-    ##
-    # Command to start the service.
+    # Internal: Get the command for starting the service.
     #
+    # Returns the String command.
     def start_command
       @start_command || "launchctl bootstrap gui/#{Process.uid} #{self.class.plist_path}"
     end
 
-    ##
-    # Command to stop the service.
+    # Internal: Get the command for stopping the service.
     #
+    # Returns the String command.
     def stop_command
       @stop_command || "launchctl bootout gui/#{Process.uid}/#{self.class.launchctl_name}"
     end
 
-    ##
-    # Calls the supplied block repeatedly until it returns false. Checks frequently at first and gradually
-    # reduces down to one-second intervals.
+    # Internal: Call the supplied block repeatedly until it returns false. Checks frequently at first and
+    # gradually reduces down to one-second intervals.
     #
-    # * +timeout+ - Maximum number of seconds to wait before timing out (default: 30).
-    # * +block+ - Block to call until it returns false.
+    # timeout - Integer maximum number of seconds to wait before timing out.
+    # block   - Proc to call until it returns false.
     #
+    # Returns nothing.
     def wait(timeout = 30, &block)
       while block.call && timeout > 0
-        reduce = [[(30 - timeout.to_i) / 5.0, 0.1].max, 1].min
+        reduce = ((30 - timeout.to_i) / 5.0).clamp(0.1, 1)
         timeout -= reduce
 
         sleep(reduce)

data/lib/potluck/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Potluck
-  VERSION = '0.0.6'
+  VERSION = '0.0.8'
 end

data/lib/potluck.rb

@@ -1,8 +1,30 @@
 # frozen_string_literal: true
 
+require_relative('potluck/config')
 require_relative('potluck/service')
+require_relative('potluck/version')
 
+# Public: Main module providing an extensible Ruby framework for managing external processes.
 module Potluck
-  DIR = File.expand_path(File.join(ENV['HOME'], '.potluck')).freeze
-  IS_MACOS = !!RUBY_PLATFORM[/darwin/]
+  @config = Config.new
+
+  class << self
+    attr_accessor(:config)
+  end
+
+  # Public: Change settings.
+  #
+  # Yields the Config instance used by Potluck services.
+  #
+  # Examples
+  #
+  #   Potluck.configure do |config|
+  #     config.dir = '/etc/potluck'
+  #     config.homebrew_prefix = '/custom/brew'
+  #   end
+  #
+  # Returns nothing.
+  def self.configure
+    yield(config)
+  end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: potluck
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.8
 platform: ruby
 authors:
 - Nate Pickens
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-01-21 00:00:00.000000000 Z
+date: 2025-03-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -25,30 +24,51 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '2.0'
 - !ruby/object:Gem::Dependency
-  name: minitest
+  name: logger
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.6.6
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.11.2
-    - - "<"
+        version: 1.6.6
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 6.0.0
+        version: '5.24'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.24'
+- !ruby/object:Gem::Dependency
+  name: minitest-reporters
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.11.2
-    - - "<"
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 6.0.0
+        version: '1.7'
 description: Potluck provides a simple interface for managing external processes in
   a way that plays nice with others as well as smoothly handling both development
   and production environments. Current official gem extensions provide Nginx and Postgres
   management.
-email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -57,16 +77,16 @@ files:
 - README.md
 - VERSION
 - lib/potluck.rb
+- lib/potluck/config.rb
 - lib/potluck/service.rb
 - lib/potluck/version.rb
 homepage: https://github.com/npickens/potluck
 licenses:
 - MIT
 metadata:
-  allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/npickens/potluck
-  source_code_uri: https://github.com/npickens/potluck
-post_install_message:
+  bug_tracker_uri: https://github.com/npickens/potluck/issues
+  documentation_uri: https://github.com/npickens/potluck/blob/0.0.8/README.md
+  source_code_uri: https://github.com/npickens/potluck/tree/0.0.8
 rdoc_options: []
 require_paths:
 - lib
@@ -74,15 +94,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.5.8
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.0.0
 requirements: []
-rubygems_version: 3.2.32
-signing_key:
+rubygems_version: 3.6.6
 specification_version: 4
 summary: An extensible Ruby framework for managing external processes.
 test_files: []