potluck 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8be6daeb322e6bd8b0a99cc25d8fb5a2a805b6354c620439c7a22ecdd289e189
-  data.tar.gz: 852bafb9263287a210c98c26b99e4a3e9358fd490c8b71910ecce2be16b980d7
+  metadata.gz: f1c7870515c28013595dbe15f34ba4c2cf3e76fabbbd55c1859066462df9227f
+  data.tar.gz: a87627ecfe3232593fd0f7223089a15893ad3e7227aed8a47d48ec32326b0572
 SHA512:
-  metadata.gz: 84d60ae064035c6657aa601a622e1f65e38fc915162cbb6287a40b2309d6736c17881f552abbf7daef2c159961a010aed4a61d5cc8111c7d7c4865925c058a81
-  data.tar.gz: 2659df968b31e9851addaa50369c92c1e143ea118e3837ae493c728ea6050f1f9efb34a350f238cb788d847a3a77632f5777b9f607e3cf00b391effec9c34c3f
+  metadata.gz: 6b4cc348d159c69e95de691c0e6f0c159ef94818174f3f45319e76e21b971669e600a1d3fb4040edecc0a05b130c6ab0fcdcd2eb08dfdf3fe5e32936d13d7685
+  data.tar.gz: 9e69dd441a0bf951edbccf7d7c590a9697327033e3e88a61801ceaefb3d05ba13734ecba4580f446e1497964a947d99b725a25832d9c0e8efe841a8fdc3414c0

data/VERSION

@@ -1 +1 @@
-0.0.3
+0.0.4

data/lib/potluck/{dish.rb → service.rb}

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
+require('fileutils')
+
 module Potluck
-  class Dish
+  ##
+  # A Ruby interface for controlling, configuring, and interacting with external processes. Serves as a
+  # parent class for service-specific child classes.
+  #
+  class Service
     SERVICE_PREFIX = 'potluck.npickens.'
 
     PLIST_XML = '<?xml version="1.0" encoding="UTF-8"?>'
@@ -10,6 +16,15 @@ module Potluck
 
     LAUNCHCTL_ERROR_REGEX = /^-|\t[^0]\t/.freeze
 
+    ##
+    # Creates a new instance.
+    #
+    # * +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).
+    # * +is_local+ - DEPRECATED. True if the service runs locally (use +manage+ instead).
+    #
     def initialize(logger: nil, manage: launchctl?, is_local: (is_local_omitted = true; nil))
       @logger = logger
       @manage = !!manage
@@ -23,7 +38,7 @@ module Potluck
         ensure_launchctl!
       end
 
-      # DEPRECATED. Use `manage` instead.
+      # DEPRECATED. Use +manage+ instead.
       @is_local = is_local.nil? ? (IS_MACOS && ensure_launchctl! rescue false) : is_local
 
       unless is_local_omitted
@@ -32,38 +47,71 @@ module Potluck
       end
     end
 
+    ##
+    # Returns true if the service is managed.
+    #
     def manage?
       @manage
     end
 
+    ##
+    # Returns true if launchctl is available.
+    #
     def launchctl?
       defined?(@@launchctl) ? @@launchctl : (@@launchctl = `which launchctl 2>&1` && $? == 0)
     end
 
+    ##
+    # Checks if launchctl is available and raises an error if not.
+    #
     def ensure_launchctl!
       launchctl? || raise("Cannot manage #{self.class.to_s.split('::').last}: launchctl not found")
     end
 
+    ##
+    # Command to get the status of the service.
+    #
     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.
+    #
     def status_error_regex
       @status_error_regex || LAUNCHCTL_ERROR_REGEX
     end
 
+    ##
+    # Command to start the service.
+    #
     def start_command
       @start_command || "launchctl bootstrap gui/#{Process.uid} #{self.class.plist_path}"
     end
 
+    ##
+    # Command to stop the service.
+    #
     def stop_command
       @stop_command || "launchctl bootout gui/#{Process.uid}/#{self.class.launchctl_name}"
     end
 
+    ##
+    # Writes the service's launchctl plist file to disk.
+    #
     def ensure_plist
+      FileUtils.mkdir_p(File.dirname(self.class.plist_path))
       File.write(self.class.plist_path, self.class.plist)
     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.
+    #
     def status
       return :inactive unless manage?
 
@@ -78,6 +126,9 @@ module Potluck
       end
     end
 
+    ##
+    # Starts the service if it's managed and is not active.
+    #
     def start
       return unless manage?
 
@@ -96,6 +147,9 @@ module Potluck
       log("#{self.class.pretty_name} started")
     end
 
+    ##
+    # Stops the service if it's managed and is active or in an error state.
+    #
     def stop
       return unless manage? && status != :inactive
 
@@ -107,6 +161,9 @@ module Potluck
       log("#{self.class.pretty_name} stopped")
     end
 
+    ##
+    # Restarts the service if it's managed by calling stop and then start.
+    #
     def restart
       return unless manage?
 
@@ -114,6 +171,13 @@ module Potluck
       start
     end
 
+    ##
+    # Runs a command with the default shell. Raises an error if the command exits with a non-zero status.
+    #
+    # * +command+ - Command to run.
+    # * +redirect_stderr+ - True if stderr should be redirected to stdout; otherwise stderr output will not
+    #   be logged (default: true).
+    #
     def run(command, redirect_stderr: true)
       output = `#{command}#{' 2>&1' if redirect_stderr}`
       status = $?
@@ -126,6 +190,12 @@ module Potluck
       end
     end
 
+    ##
+    # Logs 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).
+    #
     def log(message, error = false)
       if @logger
         error ? @logger.error(message) : @logger.info(message)
@@ -136,6 +206,13 @@ module Potluck
 
     private
 
+    ##
+    # Calls 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.
+    #
     def wait(timeout = 30, &block)
       while block.call && timeout > 0
         reduce = [[(30 - timeout.to_i) / 5.0, 0.1].max, 1].min
@@ -145,22 +222,37 @@ 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
         #{PLIST_XML}
@@ -179,4 +271,17 @@ module Potluck
       EOS
     end
   end
+
+  ##
+  # DEPRECATED. Old name of Potluck::Service class.
+  #
+  Dish = Service.clone
+
+  # :nodoc: all
+  class Dish
+    def self.inherited(subclass)
+      warn("Potluck::Dish has been renamed to Potluck::Service. Please update #{subclass} to inherit from "\
+        'Potluck::Service instead of Potluck::Dish.')
+    end
+  end
 end

data/lib/potluck/version.rb

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

data/lib/potluck.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative('potluck/dish')
+require_relative('potluck/service')
 
 module Potluck
   DIR = File.expand_path(File.join(ENV['HOME'], '.potluck')).freeze

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: potluck
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Nate Pickens
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-12-16 00:00:00.000000000 Z
+date: 2021-12-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -54,7 +54,7 @@ files:
 - README.md
 - VERSION
 - lib/potluck.rb
-- lib/potluck/dish.rb
+- lib/potluck/service.rb
 - lib/potluck/version.rb
 homepage: https://github.com/npickens/potluck
 licenses:
@@ -78,7 +78,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
+rubygems_version: 3.2.32
 signing_key:
 specification_version: 4
 summary: An extensible Ruby framework for managing external processes.