locd 0.1.3

data/lib/locd/agent/system.rb

@@ -0,0 +1,270 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Refinements
+# =======================================================================
+
+using NRSER
+using NRSER::Types
+
+
+# Definitions
+# =======================================================================
+
+# Mixin for common stuff that system agents do different.
+# 
+# System agents are specific types of {Locd::Agent} built in to Loc'd to
+# handle things like proxying HTTP request site ({Locd::Agent::Proxy}),
+# rotating logs so they don't get unwieldily ({Locd::Agent::RotaeLogs}),
+# and probably more in the future, like serving a site index, API, etc.
+# 
+# System agents are singular - there's only one of each for a Loc'd
+# label namespace, which is set via the configuration, and Loc'd uses
+# that label namespace, together with the each system agent's `.label_name`,
+# to form the agent's unique label, which is how it finds the system agents.
+# 
+# This was really just to make it simpler by side-stepping how to handle
+# many proxies and log rotators and such because besides the dev/release
+# situation described above I can't really think of any reason you would want
+# to create and manage multiple of each system agent.
+# 
+# As a consequence, {Locd::Agent} subclasses that mix {Locd::Agent::System}
+# in must define a `.label_name` class method.
+# 
+module Locd::Agent::System
+  
+  @@classes = Hamster::Set.new
+  
+  def self.classes
+    @@classes
+  end
+  
+  
+  def self.label? label
+    label.is_a?( String ) \
+    && label.start_with?( Locd.config[:namespace, :label] )
+  end
+  
+  
+  # Is a plist for one of this config's system agents?
+  # 
+  # @param plist (see Locd::Agent.plist?)
+  # 
+  # @return [Boolean]
+  #   `true` if the plist is for a system agent for this Loc'd config.
+  # 
+  def self.plist? plist
+    !!(
+      plist.dig( Locd::Agent::CONFIG_KEY, 'is_system' ) \
+      && label?( plist['Label'] )
+    )
+  end # .plist?
+  
+  
+  # Find the concrete {Locd::Agent} subclass (that has mixed in
+  # {Locd::Agent::System}) for a property list.
+  # 
+  # @param plist (see Locd::Agent.plist?)
+  # 
+  # @return [Class<Locd::Agent>]
+  #   If the plist is for one of {.classes}, returns that class.
+  # 
+  # @return [nil]
+  #   If the plist is:
+  #   
+  #   1.  Not a system plist (see {.plist?})
+  #       
+  #   2.  If none of {.classes} claim it (via their `.plist?` method).
+  #       
+  #       Though, really, this one shouldn't happen except in weird version
+  #       switching situations maybe or something.
+  # 
+  def self.class_for plist
+    return nil unless plist?( plist )
+    
+    classes.to_a.find_bounded( max: 1 ) { |cls| cls.plist? plist }.first
+  end # .class_for
+  
+  
+  def self.included base
+    base.extend ClassMethods
+    @@classes = @@classes.add base
+  end
+  
+  
+  # Mixed in to classes themselves that include {Locd::Agent::System}.
+  # 
+  module ClassMethods
+    
+    def label
+      "#{ Locd.config[:namespace, :label] }.#{ label_name }"
+    end
+    
+    
+    # The property lists for system agents are identified by their unique
+    # label (unique to the label namespace).
+    # 
+    # @param  (see Locd::Agent.plist?)
+    # @return (see Locd::Agent.plist?)
+    # 
+    def plist? plist
+      plist['Label'] == self.label
+    end
+    
+    
+    # Overridden as convenience, defaults the label to `.label`.
+    # 
+    # @param  (see Locd::Agent.plist_abs_path)
+    # @return (see Locd::Agent.plist_abs_path)
+    # 
+    def plist_abs_path label = self.label
+      super label
+    end # .plist_abs_path
+    
+    
+    # By default system agent logs are placed in the Loc'd log directory,
+    # which is `<locd_home>/log` and named `<label>.log`.
+    # 
+    # It does not depend on the `workdir` parameter at all - `workdir` is
+    # only included to conform to the {Locd::Agent.default_log_path} signature.
+    # 
+    # @example
+    #   # Considering
+    #   Locd.config.log_dir
+    #   # => #<Pathname:/Users/nrser/.locd/log>
+    #   
+    #   # then
+    #   default_log_path _, 'com.nrser.locd.proxy'
+    #   # => #<Pathname:/Users/nrser/.locd/log/com.nrser.locd.proxy.log>
+    # 
+    # @see Locd::Config#log_dir
+    # @see Locd.config
+    # @see Locd::Agent.default_log_path
+    # 
+    # @param [Pathname] workdir
+    #   Not used.
+    # 
+    # @param [String] label
+    #   The agent's label.
+    # 
+    # @return [Pathname]
+    #   Absolute path to the log file.
+    # 
+    def default_log_path workdir, label
+      Locd.config.log_dir / "#{ label }.log"
+    end
+    
+    
+    # @!group Querying
+    # --------------------------------------------------------------------------
+    
+    # Get the agent.
+    # 
+    # @return [Locd::Agent]
+    #   If the agent exists.
+    # 
+    # @return [nil]
+    #   If the agent does not exist.
+    # 
+    def get
+      super label
+    end
+    
+    # @!endgroup
+    
+    
+    # @!group Creating the Agent
+    # --------------------------------------------------------------------------
+    
+    # Wrapper that keyword arguments to `.add` and `.create_plist_data` are
+    # passed through before forwarding up to the super method.
+    # 
+    # Provides default values and checks that necessary values like `label`
+    # and `is_system` are either not provided in the call or match the
+    # expected values.
+    # 
+    # @param [String] bin:
+    #   The executable that will be used by system agents to call Loc'd.
+    # 
+    # @param workdir: (see Locd::Agent.add)
+    # 
+    # @param **kwds
+    #   Merged into the returned {Hash}.
+    # 
+    # @raise [ArgumentError]
+    #   If `kwds` contains bad values.
+    # 
+    def default_write_kwds  bin: Locd.config[:bin],
+                            workdir: Locd.config.home_dir,
+                            **kwds
+      
+      if kwds.key?( :is_system ) && kwds[:is_system] != true
+        raise ArgumentError.new binding.erb <<~END
+          The `:is_system` keyword **must** be `true` for system agents.
+          
+          It's how we recognize them!
+          
+          Found
+          
+              <%= kwds[:is_system] %>
+          
+        END
+      end
+      
+      if kwds.key?( :label ) && kwds[:label] != self.label
+        raise ArgumentError.new binding.erb <<~END
+          Can not customize system agent labels!
+          
+          It **must** be `<%= self.label %>`, because that's how Loc'd finds it.
+          
+          You can change the part before the `.proxy` via the
+          
+              locd.namespace.label
+          
+          configuration value. Create or edit the file at
+          
+              <%= Locd.config.user_config_path %>
+          
+          to define overrides (nested YAML hashes, deep merged).
+          
+        END
+      end
+      
+      {
+        bin: bin,
+        workdir: workdir,
+        **kwds,
+        is_system: true,
+        label: self.label,
+      }
+    end
+    
+    
+    # Wrapper that passes keywords though {#default_write_kwds} before
+    # calling the super method.
+    # 
+    # @param  (see Locd::Agent.create_plist_data)
+    # @return (see Locd::Agent.create_plist_data)
+    # @raise  (see Locd::Agent.create_plist_data)
+    # 
+    def create_plist_data **kwds
+      super **default_write_kwds( **kwds )
+    end
+    
+    
+    # Wrapper that passes keywords though {#default_write_kwds} before
+    # calling the super method.
+    # 
+    # @param  (see Locd::Agent.add)
+    # @return (see Locd::Agent.add)
+    # @raise  (see Locd::Agent.add)
+    # 
+    def add **kwds
+      super **default_write_kwds( **kwds )
+    end # .add
+    
+    # @!endgroup Creating the Agent
+    
+  end # module ClassMethods
+  
+end # module Locd::Agent::System

data/lib/locd/cli.rb

@@ -0,0 +1,4 @@
+module Locd::CLI; end
+
+require_relative './cli/table'
+require_relative './cli/command'

data/lib/locd/cli/command.rb

@@ -0,0 +1,9 @@
+module Locd::CLI::Command; end
+
+require_relative './command/base'
+require_relative './command/agent'
+require_relative './command/site'
+require_relative './command/job'
+require_relative './command/proxy'
+require_relative './command/rotate_logs'
+require_relative './command/main'

data/lib/locd/cli/command/agent.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+
+# Refinements
+# =======================================================================
+
+using NRSER
+using NRSER::Types
+
+
+# Definitions
+# =======================================================================
+
+# CLI interface using the `thor` gem.
+# 
+# @see http://whatisthor.com/
+# 
+class Locd::CLI::Command::Agent < Locd::CLI::Command::Base
+  
+  # Helpers
+  # ==========================================================================
+  # 
+  
+  def self.agent_class
+    Locd::Agent
+  end # .agent_class
+  
+  def self.agent_type
+    agent_class.name.split( '::' ).last.downcase
+  end
+  
+  
+  protected
+  # ==========================================================================
+    
+    def agent_class
+      self.class.agent_class
+    end
+    
+    
+    def agent_type
+      self.class.agent_type
+    end
+    
+    
+    def agent_table agents
+      Locd::CLI::Table.build do |t|
+        t.col "PID", &:pid
+        t.col "LEC", desc: "Last Exit Code", &:last_exit_code
+        t.col "Label", &:label
+        t.col "File" do |agent| agent_file agent end
+        
+        t.rows agents
+      end
+    end
+    
+    
+    # Find exactly one {Locd::Agent} for a `pattern`, using the any `:pattern`
+    # shared options provided, and raising if there are no matches or more
+    # than one.
+    # 
+    # @param pattern (see Locd::Agent.find_only!)
+    # 
+    # @return [Locd::Agent]
+    #   Matched agent.
+    # 
+    # @raise If more or less than one agent is matched.
+    # 
+    def find_only! pattern
+      agent_class.find_only! pattern, **option_kwds( groups: :pattern )
+    end
+    
+    
+    def find_multi! pattern
+      # Behavior depend on the `:all` option...
+      if options[:all]
+        # `:all` is set, so we find all the agents for the pattern, raising
+        # if we don't find any
+        agent_class.find_all!(
+          pattern,
+          **option_kwds( groups: :pattern )
+        ).values
+      else
+        # `:all` is not set, so we need to find exactly one or error
+        [find_only!( pattern )]
+      end
+    end
+    
+  # end protected
+  public
+  
+  
+  # Shared Options
+  # ============================================================================
+  
+  shared_option :long,
+    groups: :respond_with_agents,
+    desc: "Display agent details",
+    aliases: '-l',
+    type: :boolean
+  
+  # `:pattern` Group
+  # ----------------------------------------------------------------------------
+  # 
+  # Options when provided a `PATTERN` argument used to find agents by label.
+  # 
+
+  shared_option :exact,
+    groups: :pattern,
+    desc: "Force PATTERN to match entire label string",
+    aliases: '-x',
+    type: :boolean
+  
+  shared_option :recursive,
+    groups: :pattern,
+    desc: "Workdir patterns match all subdirs too",
+    aliases: '-r',
+    type: :boolean
+  
+  shared_option :all,
+    groups: :multi,
+    desc: "Apply to ALL agents that PATTERN matches",
+    aliases: '-a',
+    type: :boolean
+
+
+  # `:write` Group
+  # ----------------------------------------------------------------------------
+  # 
+  # Options when writing an agent `.plist` (`create`, `update`).
+  # 
+
+  shared_option :label,
+    groups: :write,
+    desc: "Agent label, which is also the domain the proxy will serve it at",
+    aliases: ['--name', '-n'],
+    type: :string #,
+    # required: true
+
+  shared_option :workdir,
+    groups: :write,
+    desc: "Working directory for the agent's command",
+    aliases: ['--dir'],
+    type: :string
+
+  shared_option :log_path,
+    groups: :write,
+    desc: "Path to log agent's STDOUT and STDERR (combined)",
+    aliases: ['--log'],
+    type: :string
+  
+  
+  shared_option :force,
+    groups: :add,
+    desc: "Overwrite any existing agent",
+    aliases: '-f',
+    type: :boolean,
+    default: false
+  
+  
+  shared_option :load,
+    groups: :add,
+    desc: "Load the agent into `launchd`",
+    type: :boolean,
+    default: true
+  
+  
+  shared_option :unload,
+    groups: :start,
+    desc: "Unload the agent from `launchd` after stopping",
+    type: :boolean,
+    default: true
+  
+  # Commands
+  # ============================================================================
+  
+  # Querying
+  # ----------------------------------------------------------------------------
+  
+  desc              "ls [PATTERN]",
+                    "List agents"
+  map               list: :ls
+  include_options   :long,
+                    groups: :pattern
+  def ls            pattern = nil
+    results = if pattern.nil?
+      agent_class.all
+    else
+      agent_class.list pattern, **option_kwds( groups: :pattern )
+    end
+    
+    respond results.values.sort
+  end
+  
+  
+  # Write Commands
+  # ----------------------------------------------------------------------------
+  
+  desc              "add CMD_TEMPLATE...",
+                    "Add agents that runs a command in the current directory"
+  include_options   groups: [:write, :add, :respond_with_agents]
+  def add           *cmd_template
+    agent = agent_class.add \
+      cmd_template: cmd_template,
+      **option_kwds( groups: :write )
+    
+    logger.info "`#{ agent.label }` agent created."
+    
+    agent.load if options[:load]
+    
+    respond agent
+  end
+  
+  
+  desc              "update PATTERN [OPTIONS] [-- CMD_TEMPLATE...]",
+                    "Update an existing agent"
+  include_options   groups: [:pattern, :write, :respond_with_agents]
+  def update        pattern, *cmd_template
+    agent = find_only! pattern
+    
+    new_agent = agent.update \
+      cmd_template: cmd_template,
+      **option_kwds( groups: :write )
+    
+    logger.info "Agent `#{ agent.label }` updated"
+    
+    respond agent
+  end
+  
+  
+  desc              "open PATTERN",
+                    "Open an agent's URL in the browser"
+  include_options   groups: [:pattern, :multi]
+  def open          pattern
+    find_multi!( pattern ).each do |agent|
+      Cmds! "open %s", agent.url
+      logger.info "Opened agent `#{ agent.label }` at #{ agent.url }"
+    end
+  end
+  
+  
+  desc              "rm PATTERN",
+                    "Remove (uninstall, delete) a agent"
+  map               remove: :rm
+  include_options   groups: [:pattern, :multi]
+  def rm            pattern
+    agent_class.remove pattern, **option_kwds( :exact )
+  end
+  
+  
+  desc              "plist PATTERN",
+                    "Show an agent's launchd property list"
+  include_options   groups: :pattern
+  def plist         pattern
+    # TODO  Why doesn't this use {#find_only!}?
+    agent = agent_class.find_only! pattern, **option_kwds( :exact )
+    
+    if options[:json] || options[:yaml]
+      respond agent.plist
+    else
+      respond agent.path.read
+    end
+  end
+  
+    
+  desc              "start PATTERN",
+                    "Start an agent"
+  include_options   groups: :pattern
+  option            :write,
+                    desc: "Set `launchd` *Disabled* key to `false`",
+                    type: :boolean
+  def start         pattern
+    find_only!( pattern ).start
+  end
+  
+  
+  desc              "stop PATTERN",
+                    "Stop an agent"
+  include_options   groups: [:pattern, :stop]
+  option            :write,
+                    desc: "Set `launchd` *Disabled* key to `true`",
+                    type: :boolean
+  def stop          pattern
+    find_only!( pattern ).stop **option_kwds( :unload )
+  end
+  
+  
+  desc              "restart PATTERN",
+                    "Restart an agent"
+  include_options   groups: [:pattern, :stop]
+  option            :write,
+                    desc: "Set `launchd` *Disabled* key to `false`",
+                    type: :boolean
+  def restart       pattern
+    find_only!( pattern ).restart
+  end
+  
+end # class Locd::CLI::Command::Agent