potluck 0.0.1 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50b13dbd4649490c2673d9dde14aef89251279b2ea39c6cb816d110320078efa
-  data.tar.gz: f380c5e9c07a27b55bfa20a5a4deddbb3e1978ecb9d63db8acc5888e9457f533
+  metadata.gz: 67a2b224bd6ed00dcfe15688c0ebaa8764649cc7a201174c20c6238bab45bc27
+  data.tar.gz: e1fececdb06d683f1879ac8baab15a26ba8bb6db2a15a3ea8e0dd247876435e9
 SHA512:
-  metadata.gz: 878a3446024f4ef4ac5464acb7866ed5517d27dd4a113ed2e2f24c119d9a0416bc82eb5cf00462a0dd4e3a602a566bf15a9f1b900c8e28fba5734399ed5a3d48
-  data.tar.gz: 0fe2162e70524a4bd85eba990d32b5d5397c4366bb8532d3f8a11a06824e7bce169f03b4dbe27e04600f0763a62a6f4a596a597f24ce4197a1bdb07e8ee8de07
+  metadata.gz: 43b41b2bade1a6b87ee0d266a38f0d59b7417e5a652804521952356d7aec8fb9f98c3e2727e903e5b79b91587ff621c557b7be90325e86db303ab66cf5c193d1
+  data.tar.gz: 6ffedd39746332d83f7c09b3cf3a7a4e40c60503eb88f3083e904347712a60a508199fcb44b8d8949250992e61de160e476654f5acb2f4a1b7ca867e26a13ba8

data/README.md

@@ -1,6 +1,19 @@
 # Potluck
 
-Potluck is an extensible Ruby framework for managing external processes.
+Potluck is an extensible Ruby framework for configuring, controlling, and interacting with external
+processes. It leverages `launchctl` for starting and stopping processes when the command is available (e.g.
+when developing locally on macOS) while gracefully taking either a more passive or manual role with external
+processes in other environments (e.g. production).
+
+The core Potluck gem provides a simple interface which is used by service-specific extensions to the gem.
+Currently there are two official extensions:
+
+* [Potluck::Nginx](potluck-nginx/README.md) - Generates Nginx configuration files and (optionally) controls
+  the Nginx process with `launchctl` or manual commands. Allows for multiple Ruby apps as well as other
+  external processes to all seamlessly use Nginx simultaneously.
+* [Potluck::Postgres](potluck-postgres/README.md) - Provides control of the Postgres process and basic
+  common functionality for connecting to and setting up a database. Uses the
+  [Sequel](https://github.com/jeremyevans/sequel) and [pg](https://github.com/ged/ruby-pg) gems.
 
 ## Installation
 
@@ -18,7 +31,9 @@ gem install potluck
 
 ## Usage
 
-[Coming soon.]
+The core Potluck gem is not meant to be used directly. Rather its `Service` class defines a common interface
+for external processes which can be inherited by service-specific child classes. See
+[Potluck::Nginx](potluck-nginx/README.md) and [Potluck::Postgres](potluck-postgres/README.md) for examples.
 
 ## Contributing
 

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.0.5

data/lib/potluck/service.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+require('fileutils')
+
+module Potluck
+  ##
+  # 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.
+  #
+  class Service
+    SERVICE_PREFIX = 'potluck.npickens.'
+    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).
+    #
+    def initialize(logger: nil, manage: launchctl?)
+      @logger = logger
+      @manage = !!manage
+
+      if manage.kind_of?(Hash)
+        @status_command = manage[:status]
+        @status_error_regex = manage[:status_error_regex]
+        @start_command = manage[:start]
+        @stop_command = manage[:stop]
+      elsif manage
+        ensure_launchctl!
+      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(ServiceError.new("Cannot manage #{self.pretty_name}: 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?
+
+      output = `#{status_command}`
+
+      if $? != 0
+        :inactive
+      elsif status_error_regex && output[status_error_regex]
+        :error
+      else
+        :active
+      end
+    end
+
+    ##
+    # Starts the service if it's managed and is not active.
+    #
+    def start
+      return unless manage?
+
+      ensure_plist unless @start_command
+
+      case status
+      when :error then stop
+      when :active then return
+      end
+
+      run(start_command)
+      wait { status == :inactive }
+
+      raise(ServiceError.new("Could not start #{self.class.pretty_name}")) if status != :active
+
+      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
+
+      run(stop_command)
+      wait { status != :inactive }
+
+      raise(ServiceError.new("Could not stop #{self.class.pretty_name}")) if status != :inactive
+
+      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?
+
+      stop
+      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 = $?
+
+      if status != 0
+        output.split("\n").each { |line| log(line, :error) }
+        raise(ServiceError.new("Command exited with status #{status.to_i}: #{command}"))
+      else
+        output
+      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)
+      else
+        error ? $stderr.puts(message) : $stdout.puts(message)
+      end
+    end
+
+    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
+        timeout -= reduce
+
+        sleep(reduce)
+      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
+  end
+end

data/lib/potluck/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Potluck
-  VERSION = '0.0.1'
+  VERSION = '0.0.5'
 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.1
+  version: 0.0.5
 platform: ruby
 authors:
 - Nate Pickens
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-03-27 00:00:00.000000000 Z
+date: 2021-12-31 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.

data/lib/potluck/dish.rb

@@ -1,142 +0,0 @@
-# frozen_string_literal: true
-
-module Potluck
-  class Dish
-    SERVICE_PREFIX = 'potluck.npickens.'
-
-    PLIST_XML = '<?xml version="1.0" encoding="UTF-8"?>'
-    PLIST_DOCTYPE = '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/Prope'\
-      'rtyList-1.0.dtd">'
-
-    LAUNCHCTL_ERROR_REGEX = /^-|\t[^0]\t/.freeze
-
-    def initialize(logger: nil, is_local: nil)
-      @logger = logger
-      @is_local = is_local.nil? ? (IS_MACOS && ensure_launchctl! rescue false) : is_local
-    end
-
-    def ensure_launchctl!
-      @@launchctl = `which launchctl` && $? == 0 unless defined?(@@launchctl)
-      @@launchctl || raise("Cannot manage #{self.class.to_s.split('::').last}: launchctl not found")
-    end
-
-    def ensure_plist
-      File.write(self.class.plist_path, self.class.plist)
-    end
-
-    def status
-      return :inactive unless @is_local && ensure_launchctl!
-
-      output = `launchctl list 2>&1 | grep #{SERVICE_PREFIX}#{self.class.service_name}`
-
-      if $? != 0
-        :inactive
-      elsif output[LAUNCHCTL_ERROR_REGEX]
-        :error
-      else
-        :active
-      end
-    end
-
-    def start
-      return unless @is_local && ensure_launchctl!
-
-      ensure_plist
-
-      case status
-      when :error then stop
-      when :active then return
-      end
-
-      run("launchctl bootstrap gui/#{Process.uid} #{self.class.plist_path}")
-      wait { status == :inactive }
-
-      raise("Could not start #{self.class.pretty_name}") if status != :active
-
-      log("#{self.class.pretty_name} started")
-    end
-
-    def stop
-      return unless @is_local && ensure_launchctl! && status != :inactive
-
-      run("launchctl bootout gui/#{Process.uid}/#{self.class.launchctl_name}")
-      wait { status != :inactive }
-
-      raise("Could not stop #{self.class.pretty_name}") if status != :inactive
-
-      log("#{self.class.pretty_name} stopped")
-    end
-
-    def restart
-      return unless @is_local && ensure_launchctl!
-
-      stop
-      start
-    end
-
-    def run(command, redirect_stderr: true)
-      output = `#{command}#{' 2>&1' if redirect_stderr}`
-      status = $?
-
-      if status != 0
-        output.split("\n").each { |line| log(line, :error) }
-        raise("Command exited with status #{status.to_i}: #{command}")
-      else
-        output
-      end
-    end
-
-    def log(message, error = false)
-      if @logger
-        error ? @logger.error(message) : @logger.info(message)
-      else
-        error ? $stderr.puts(message) : $stdout.puts(message)
-      end
-    end
-
-    private
-
-    def wait(timeout = 30, &block)
-      while block.call && timeout > 0
-        reduce = [[(30 - timeout.to_i) / 5.0, 0.1].max, 1].min
-        timeout -= reduce
-
-        sleep(reduce)
-      end
-    end
-
-    def self.pretty_name
-      @pretty_name ||= self.to_s.split('::').last
-    end
-
-    def self.service_name
-      @service_name ||= pretty_name.downcase
-    end
-
-    def self.launchctl_name
-      "#{SERVICE_PREFIX}#{service_name}"
-    end
-
-    def self.plist_path
-      File.join(DIR, "#{launchctl_name}.plist")
-    end
-
-    def self.plist(content)
-      <<~EOS
-        #{PLIST_XML}
-        #{PLIST_DOCTYPE}
-        <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
-  end
-end