potluck 0.0.2 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92a30f07b5c14817cd0f61c62cf3ea56dce665498b022321348d9d9fe99605b7
-  data.tar.gz: f7166d54bb8c382714c6503569a4d4416c9db432575de49ee763402f42520310
+  metadata.gz: 6881b14c35b5ae6be793e8390d8ab87d1b8220ea78a2803dac55f5ea8c2bc4cf
+  data.tar.gz: e0c7b0e3a472f03dded30e35e38fbad4f8f484a1d3cb44cd4ced99248cdd298c
 SHA512:
-  metadata.gz: 76407292ddfa7135cfe05728a1b860237ee6914fed9ebc5477960cf607174515d81058d2b0f23e1d7bab525a977593430d8830394083f2326f2b30d41b04bb02
-  data.tar.gz: ad0a00525b1146bf8587defa8fd96e2a1bd7066dd92961bd37d74a53283da22aaaab9bf434a848bf92d375756d2c204e96229e52c3c2d5fa4725c8eaf67b1b37
+  metadata.gz: 0ce2edbef44e0f8e27ffb0bb63e717d5f9781f29a27661b72de6bd77b0421f73757a230f5d3193f8e04bbaba8abd9e282d8021af9c4aded66e5e10efd78bb2c7
+  data.tar.gz: 5246bb757a883318ed514c8a5a5a94d5631732170c9622d1b20f92541a419fb36b9b559a3a6967ca700d2ba765ec58a323fed3b39fb464f222a9ca9dfc84e77b

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright 2021 Nate Pickens
+Copyright 2021-2022 Nate Pickens
 
 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

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.2
+0.0.6

data/lib/potluck/service.rb

@@ -0,0 +1,275 @@
+# 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: self.class.launchctl?)
+      @logger = logger
+      @manage = !!manage
+      @manage_with_launchctl = false
+
+      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
+        @manage_with_launchctl = true
+        self.class.ensure_launchctl!
+      end
+    end
+
+    ##
+    # Returns true if the service is managed.
+    #
+    def manage?
+      @manage
+    end
+
+    ##
+    # Returns true if the service is managed via launchctl.
+    #
+    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.
+    #
+    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?
+
+      case status
+      when :error then stop
+      when :active then return
+      end
+
+      self.class.write_plist if manage_with_launchctl?
+      run(start_command)
+      wait { status == :inactive }
+
+      raise(ServiceError, "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
+
+      self.class.write_plist if manage_with_launchctl?
+      run(stop_command)
+      wait { status != :inactive }
+
+      raise(ServiceError, "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.
+    # * +capture_stderr+ - True if stderr should be redirected to stdout; otherwise stderr output will not
+    #   be logged (default: true).
+    #
+    def run(command, capture_stderr: true)
+      output = `#{command}#{' 2>&1' if capture_stderr}`
+      status = $?
+
+      if status != 0
+        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.
+    #
+    # * +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
+
+    ##
+    # 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.
+    #
+    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
+
+    ##
+    # 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
+  end
+end

data/lib/potluck/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Potluck
-  VERSION = '0.0.2'
+  VERSION = '0.0.6'
 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.2
+  version: 0.0.6
 platform: ruby
 authors:
 - Nate Pickens
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-12-13 00:00:00.000000000 Z
+date: 2022-01-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -44,7 +44,10 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: 6.0.0
-description: An extensible Ruby framework for managing external processes.
+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: []
@@ -54,7 +57,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 +81,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