locd 0.1.3

data/doc/files/topics/plists.md

@@ -0,0 +1,39 @@
+Property Lists (`*.plist` Files)
+==============================================================================
+
+Property lists are an Apple-specific serialization format:
+
+<https://en.wikipedia.org/wiki/Property_list>
+
+They come in several formats - XML, binary and a funky "old" / NeXTSTEP custom encoding.
+
+We care about them because {file:doc/topics/launchd.md}'s {file:doc/topics/agents.md} are defined in plist files.
+
+All the agent plists I've seen are in XML format, and that's what Loc'd writes and expects to find when reading.
+
+For more info on launchd plists check out:
+
+<https://developer.apple.com/legacy/library/documentation/Darwin/Reference/ManPages/man5/launchd.plist.5.html>
+
+
+plists in Ruby
+------------------------------------------------------------------------------
+
+Loc'd uses the [plist][] gem to read and write agent plists:
+
+1.  [Plist.parse_xml][] to parse agent plist XML files to Ruby hashes.
+    
+2.  [Plist::Emit.dump][] to encode Ruby hashes into plist XML for writing.
+
+When you see a `plist` in Loc'd it should be a Ruby hash that was read from an agent plist file and/or created or mutated to be written to an agent plist file (plists are a general data format, but the top-level object in agent plists should always be a `dict`, which is mapped to a Ruby hash).
+
+The keys of these hashes should all be strings. For details on the possible Ruby value types see
+
+<http://www.rubydoc.info/gems/plist#Generation>
+
+
+<!-- References & Further Reading: -->
+
+[plist]: https://rubygems.org/gems/plist
+
+[Plist.parse_xml]: http://www.rubydoc.info/gems/plist/Plist.parse_xml

data/doc/include/plist.md

@@ -0,0 +1,3 @@
+Ruby {Hash} representation of an agent's property list (`.plist`) file.
+
+See {file:doc/topics/plists.md} for details about possible value types.

data/exe/locd

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require 'locd'
+
+# Setup logging *before* including {Locd::CLI} so that we can get
+# trace/debug output from that setup if enabled via ENV vars
+Locd::Logging.setup dest: $stderr, sync: true
+
+# Logger for this file
+logger = SemanticLogger[__FILE__]
+
+require 'locd/cli'
+
+begin
+  Locd::CLI::Command::Main.start
+rescue Exception => e
+  if e.instance_of?(SystemExit)
+    raise
+  else
+    logger.fatal e
+  end
+end

data/lib/locd.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+# encoding: UTF-8
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+require 'pp'
+require 'pathname'
+require 'shellwords'
+
+# Deps
+# -----------------------------------------------------------------------
+require 'nrser'
+require 'semantic_logger'
+require 'cmds'
+
+# Project / Package
+# -----------------------------------------------------------------------
+require 'locd/version'
+require 'locd/errors'
+require 'locd/config'
+require 'locd/util'
+require 'locd/logging'
+require 'locd/label'
+require 'locd/pattern'
+require 'locd/launchctl'
+require 'locd/newsyslog'
+require 'locd/agent'
+require 'locd/proxy'
+
+
+# Refinements
+# =======================================================================
+
+using NRSER
+
+
+# Definitions
+# =======================================================================
+
+module Locd
+  
+  # Constants
+  # ======================================================================
+  
+  # {Regexp} to match HTTP "Host" header line.
+  # 
+  # @return [Regexp]
+  # 
+  HOST_RE = /^Host\:\ /i
+  
+  
+  ROTATE_LOGS_LABEL = 'com.nrser.locd.rotate-logs'
+  
+  
+  # Mixins
+  # ============================================================================
+  
+  # Add {.logger} and {#logger} methods
+  include SemanticLogger::Loggable
+  
+  
+  # Module Methods
+  # ======================================================================
+  
+  # @return [Locd::Config]
+  #   The configuration.
+  # 
+  def self.config
+    @config ||= Locd::Config.new
+  end
+  
+end # module Locd

data/lib/locd/agent.rb

@@ -0,0 +1,1186 @@
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+require 'plist'
+require 'fileutils'
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+
+# Refinements
+# =======================================================================
+
+using NRSER
+using NRSER::Types
+
+
+# Definitions
+# =======================================================================
+
+
+# Represents a backend agent that the proxy can route to.
+# 
+# Agents are managed by `launchd`, macOS's system service manager, and
+# created on-demand by generating "property list" files (`.plist`, XML format)
+# and installing them in the user's `~/Library/LaunchAgents` directory.
+# 
+# From there they can be managed directly with macOS's `launchctl` utility,
+# with the `lunchy` gem, etc.
+# 
+class Locd::Agent
+  
+  # Constants
+  # ==========================================================================
+  
+  # Extra plist key we store Loc'd config under (this is where the port is
+  # stored). We also use it's presence to detect that a plist is Loc'd.
+  # 
+  # @return [String]
+  # 
+  CONFIG_KEY = 'locd_config'
+  
+  
+  # Attribute / method names that {#to_h} uses.
+  # 
+  # @return [Hamster::SortedSet<Symbol>]
+  # 
+  TO_H_NAMES = Hamster::SortedSet[:label, :path, :plist, :status]
+  
+  
+  # Mixins
+  # ==========================================================================
+  
+  # Add {.logger} and {#logger} methods
+  include SemanticLogger::Loggable
+  
+  # Make agents sortable by label
+  include Comparable
+  
+  
+  # Class Methods
+  # ==========================================================================
+  
+  # Test if the parse of a property list is for a Loc'd agent by seeing if
+  # it has {CONFIG_KEY} as a key.
+  # 
+  # @param [Hash<String, Object>] plist
+  #   {include:file:doc/include/plist.md}
+  # 
+  # @return [Boolean]
+  #   `true` if the plist looks like it's from Loc'd.
+  # 
+  def self.plist? plist
+    plist.key? CONFIG_KEY
+  end # .plist?
+  
+  
+  # @!group Computing Paths
+  # --------------------------------------------------------------------------
+  
+  # Absolute path to `launchd` plist directory for the current user, which is
+  # an expansion of `~/Library/LaunchAgents`.
+  # 
+  # @return [Pathname]
+  # 
+  def self.user_plist_abs_dir
+    Pathname.new( '~/Library/LaunchAgents' ).expand_path
+  end
+  
+  
+  # Absolute path for the plist file given it's label, equivalent to expanding
+  # `~/Library/LaunchAgents/<label>.plist`.
+  # 
+  # @param [String] label
+  #   The agent's label.
+  # 
+  # @return [Pathname]
+  # 
+  def self.plist_abs_path label
+    user_plist_abs_dir / "#{ label }.plist"
+  end
+  
+  
+  # Default path for a {Locd::Agent} output file.
+  # 
+  # @param [Pathname] workdir
+  #   The working directory the agent will run in.
+  # 
+  # @param [String] label
+  #   The agent's label.
+  # 
+  # @return [Pathname]
+  #   If we could find a `tmp` directory walking up from `workdir`.
+  # 
+  # @return [nil]
+  #   If we could not find a `tmp` directory walking
+  # 
+  def self.default_log_path workdir, label
+    tmp_dir = workdir.find_up 'tmp', test: :directory?, result: :path
+    
+    if tmp_dir.nil?
+      logger.warn "Unable to find `tmp` dir, output will not be redirected",
+        workdir: workdir,
+        label: label,
+        stream: stream
+      return nil
+    end
+    
+    unless tmp_dir.writable?
+      logger.warn \
+        "Found `tmp` dir, but not writable. Output will not be redirected",
+        workdir: workdir,
+        label: label,
+        stream: stream
+      return nil
+    end
+    
+    tmp_dir / 'locd' / "#{ label }.log"
+  end
+  
+  
+  # Get the path to log `STDOUT` and `STDERR` to given the option value and other
+  # options we need to figure it out if that doesn't suffice.
+  # 
+  # Note that we might not figure it out at all (returning `nil`), and that
+  # needs to be ok too (though it's not expected to happen all too often).
+  # 
+  # @param [nil | String | Pathname] log_path:
+  #   The value the user provided (if any).
+  #   
+  #   1.  `nil` - {.default_log_path} is called and it's result returned.
+  #       
+  #   2.  `String | Pathname` - Value is expanded against `workdir` and the
+  #       resulting absolute path is returned (which of course may not exist).
+  #       
+  #       This means that absolute, home-relative (`~/` paths) and
+  #       `workdir`-relative paths should all produce the expected results.
+  # 
+  # @return [Pathname]
+  #   Absolute path where the agent will try to log output.
+  # 
+  # @return [nil]
+  #   If the user doesn't supply a value and {.default_log_path} returns
+  #   `nil`. The agent will not log output in this case.
+  # 
+  def self.resolve_log_path log_path:, workdir:, label:
+    if log_path.nil?
+      default_log_path workdir, label
+    else
+      log_path.to_pn.expand_path workdir
+    end
+  end
+  
+  # @!endgroup Computing Paths
+  
+  
+  # @!group Instantiating
+  # --------------------------------------------------------------------------
+  
+  # Get the agent class that a plist should be instantiated as.
+  # 
+  # @param [Hash<String, Object>] plist
+  #   {include:file:doc/include/plist.md}
+  # 
+  # @return [Class<Locd::Agent>]
+  #   If the plist is for an agent of the current Loc'd configuration, the
+  #   appropriate class to instantiate it as.
+  #   
+  #   Plists for user sites and jobs will always return their subclass.
+  #   
+  #   Plists for system agents will only return their class when they are
+  #   for the current configuration's label namespace.
+  #   
+  # @return [nil]
+  #   If the plist is not for an agent of the current Loc'd configuration
+  #   (and should be ignored by Loc'd).
+  # 
+  def self.class_for plist
+    # 1.  See if it's a Loc'd system agent plist
+    if system_class = Locd::Agent::System.class_for( plist )
+      return system_class
+    end
+    
+    # 2.  See if it's a Loc'd user agent plist
+    if user_class = [
+                      Locd::Agent::Site,
+                      Locd::Agent::Job,
+                    ].find_bounded( max: 1 ) { |cls| cls.plist? plist }.first
+      return user_class
+    end
+    
+    # 3.  Return a vanilla agent if it's a plist for one
+    #     
+    #     Really, not sure when this would happen...
+    #     
+    if Locd::Agent.plist?( plist )
+      return Locd::Agent
+    end
+    
+    # Nada
+    nil
+  end # .class_for
+  
+  
+  # Instantiate a {Locd::Agent} from the path to it's `.plist` file.
+  # 
+  # @param [Pathname | String] plist_path
+  #   Path to the `.plist` file.
+  # 
+  # @return [Locd::Agent]
+  # 
+  def self.from_path plist_path
+    plist = Plist.parse_xml plist_path.to_s
+    
+    class_for( plist ).new plist: plist, path: plist_path
+  end
+  
+  # @!endgroup
+  
+  
+  # @!group Querying
+  # --------------------------------------------------------------------------
+  
+  # All installed Loc'd agents.
+  # 
+  # @return [Hamster::Hash<String, Locd::Agent>]
+  #   Map of all Loc'd agents by label.
+  # 
+  def self.plists
+    Pathname.glob( user_plist_abs_dir / '*.plist' ).
+      map { |path|
+        begin
+          [path, Plist.parse_xml( path.to_s )]
+        rescue Exception => error
+          logger.trace "{Plist.parse_xml} failed to parse plist",
+            path: path.to_s,
+            error: error,
+            backtrace: error.backtrace
+          nil
+        end
+      }.
+      compact.
+      select { |path, plist| plist? plist }.
+      thru( &Hamster::Hash.method( :new ) )
+  end
+  
+  
+  # All {Locd::Agent} that are instances of `self`.
+  # 
+  # So, when invoked through {Locd::Agent.all} returns all agents.
+  # 
+  # When invoked from a {Locd::Agent} subclass, returns all agents that are
+  # instances of *that subclass* - {Locd::Agent::Site.all} returns all
+  # {Locd::Agent} that are {Locd::Agent::Site} instances.
+  # 
+  # @return [Hamster::Hash<String, Locd::Agent>]
+  #   Map of agent {#label} to instance.
+  # 
+  def self.all
+    # If we're being invoked through {Locd::Agent} itself actually find and
+    # load everyone
+    if self == Locd::Agent
+      plists.each_pair.map { |path, plist|
+        begin
+          agent_class = class_for plist
+          
+          if agent_class.nil?
+            nil
+          else
+            agent = agent_class.new path: path, plist: plist
+            [agent.label, agent]
+          end
+          
+        rescue Exception => error
+          logger.error "Failed to parse Loc'd Agent plist",
+            path: path,
+            error: error,
+            backtrace: error.backtrace
+          
+          nil
+        end
+      }.
+      compact.
+      thru( &Hamster::Hash.method( :new ) )
+    else
+      # We're being invoked through a {Locd::Agent} subclass, so invoke
+      # through {Locd::Agent} and filter the results to instance of `self`.
+      Locd::Agent.all.select { |label, agent| agent.is_a? self }
+    end
+  end
+  
+  
+  # Labels for all installed Loc'd agents.
+  # 
+  # @return [Hamster::Vector<String>]
+  # 
+  def self.labels
+    all.keys.sort
+  end
+  
+  
+  # Get a Loc'd agent by it's label.
+  # 
+  # @param [String] label
+  #   The agent's label.
+  # 
+  # @return [Locd::Agent]
+  #   If a Loc'd agent with `label` is installed.
+  # 
+  # @return [nil]
+  #   If no Loc'd agent with `label` is installed.
+  # 
+  def self.get label
+    path = plist_abs_path label
+    
+    if path.file?
+      from_path path
+    end
+  end
+  
+  
+  # Find a single {Locd::Agent} matching `pattern` or raise.
+  # 
+  # Parameters are passed to {Locd::Label.regexp_for_glob} and the resulting
+  # {Regexp} is matched against each agent's {#label}.
+  # 
+  # @see Locd::Label.regexp_for_glob
+  # 
+  # @param (see .find_all)
+  # 
+  # @return [Locd::Agent]
+  # 
+  def self.find_only! *find_all_args
+    find_all( *find_all_args ).values.to_a.only!
+  end
+  
+  
+  # Find all the agents that match a pattern.
+  # 
+  # @see Locd::Label.regexp_for_glob
+  # 
+  # @param [String | Pattern] pattern
+  #   Pattern to match against agent.
+  #   
+  #   When it's a {String}, passed to {Locd::Pattern.from} to get the pattern.
+  # 
+  # @param [**<Symbol, V>] options
+  #   Passed to {Locd::Pattern.from} when `pattern` is a {String}.
+  # 
+  # @return (see .all)
+  # 
+  def self.find_all pattern, **options
+    pattern = Locd::Pattern.from pattern, **options
+    all.select { |label, agent| pattern.match? agent }
+  end
+  
+  singleton_class.send :alias_method, :list, :find_all
+  
+  
+  # Just like {.find_all} but raises if result is empty.
+  # 
+  # @param (see .find_all)
+  # @return (see .find_all)
+  # 
+  # @raise [NRSER::CountError]
+  #   If no agents were found.
+  # 
+  def self.find_all! pattern, **options
+    pattern = Locd::Pattern.from pattern, **options
+    
+    find_all( pattern ).tap { |agents|
+      if agents.empty?
+        raise NRSER::CountError.new(
+          "No agents found for pattern from #{ pattern.source.inspect }",
+          subject: agents,
+          expected: '#count > 0',
+        )
+      end
+    }
+  end # .find_all!
+  
+  # @!endgroup
+  
+  
+  # @!group Creating Agents
+  # --------------------------------------------------------------------------
+  
+  # Render a command string by substituting any `{name}` parts for their
+  # values.
+  # 
+  # @example
+  #   render_cmd \
+  #     cmd_template: "serve --name={label} --port={port}",
+  #     label: 'server.test',
+  #     workdir: Pathname.new( '~' ).expand_path,
+  #     port: 1234
+  #   # => "server --name=server.test --port=1234"
+  # 
+  # @param [String | Array<String>] cmd_template:
+  #   Template for the string. Arrays are just rendered per-entry then
+  #   joined.
+  # 
+  # @param [String] label:
+  #   The agent's {#label}.
+  # 
+  # @param [Pathname] workdir:
+  #   The agent's {#workdir}.
+  # 
+  # @param [Hash<Symbol, #to_s>] **extras
+  #   Subclass-specific extra keys and values to make available. Values will
+  #   be converted to strings via `#to_s` before substitution.
+  # 
+  # @return [String]
+  #   Command string with substitutions made.
+  # 
+  def self.render_cmd cmd_template:, label:, workdir:, **extras
+    t.match cmd_template,
+      Array, ->( array ) {
+        array.map {|arg|
+          render_cmd \
+            cmd_template: arg,
+            label: label,
+            workdir: workdir,
+            **extras
+        }.shelljoin
+      },
+      
+      String, ->( string ) {
+        {
+          label: label,
+          workdir: workdir,
+          **extras,
+        }.reduce( string ) do |cmd, (key, value)|
+          cmd.gsub  "{#{ key }}", value.to_s.shellescape
+        end
+      }
+  end
+  
+  
+  # Create the `launchd` property list data for a new {Locd::Agent}.
+  # 
+  # @param [nil | String | Pathname] log_path:
+  #   Optional path to log agent standard outputs to (combined `STDOUT` and
+  #   `STDERR`).
+  #   
+  #   See {.resolve_log_path} for details on how the different types and
+  #   values are treated.
+  # 
+  # @return [Hash<String, Object>]
+  #   {include:file:doc/include/plist.md}
+  # 
+  def self.create_plist_data  cmd_template:,
+                              label:,
+                              workdir:,
+                              log_path: nil,
+                              keep_alive: false,
+                              run_at_load: false,
+                              **extras
+    # Configure daemon variables...
+    
+    # Normalize `workdir` to an expanded {Pathname}
+    workdir = workdir.to_pn.expand_path
+    
+    # Resolve the log (`STDOUT` & `STDERR`) path
+    log_path = resolve_log_path(
+      log_path: log_path,
+      workdir: workdir,
+      label: label,
+    ).to_s
+    
+    # Interpolate variables into command template
+    cmd = render_cmd(
+      cmd_template: cmd_template,
+      label: label,
+      workdir: workdir,
+      **extras
+    )
+    
+    # Form the property list hash
+    {
+      # Unique label, format: `locd.<owner>.<name>.<agent.path...>`
+      'Label' => label,
+      
+      # What to run
+      'ProgramArguments' => [
+        # TODO  Maybe this should be configurable or smarter in some way?
+        'bash',
+        # *login* shell... need this to source the user profile and set up
+        # all the ENV vars
+        '-l',
+        # Run the command in the login shell
+        '-c', cmd,
+      ],
+      
+      # Directory to run the command in
+      'WorkingDirectory' => workdir.to_s,
+      
+      # Where to send STDOUT
+      'StandardOutPath' => log_path,
+      
+      # Where to send STDERR (we send both to the same file)
+      'StandardErrorPath' => log_path,
+      
+      # Bring the process back up if it goes down (has backoff and stuff
+      # built-in)
+      'KeepAlive' => keep_alive,
+      
+      # Start the process when the plist is loaded
+      'RunAtLoad' => run_at_load,
+      
+      'ProcessType' => 'Interactive',
+      
+      # Extras we need... `launchd` complains in the system log about this
+      # but it's the easiest way to handle it at the moment
+      CONFIG_KEY => {
+        # Save this too why the hell not, might help debuging at least
+        cmd_template: cmd_template,
+        
+        # Add subclass-specific extras
+        **extras,
+      }.str_keys,
+      
+      # Stuff that *doesn't* work... so you don't try it again, because
+      # Apple's online docs seems totally out of date.
+      # 
+      # Not allowed for user agents
+      # 'UserName' => ENV['USER'],
+      # 
+      # "The Debug key is no longer respected. Please remove it."
+      # 'Debug' => true,
+      # 
+      # Yeah, it would have been nice to just use the plist to store the port,
+      # but this runs into all sorts of impenetrable security mess... gotta
+      # put it somewhere else! Weirdly enough it just totally works outside
+      # of here, so I'm not what the security is really stopping..?
+      # 
+      # 'Sockets' => {
+      #   'Listeners' => {
+      #     'SockNodeName' => BIND,
+      #     'SockServiceName' => port,
+      #     'SockType' => 'stream',
+      #     'SockFamily' => 'IPv4',
+      #   },
+      # },
+    }.reject { |key, value| value.nil? } # Drop any `nil` values
+  end
+  
+  
+  # Add an agent, writing a `.plist` to `~/Library/LaunchAgents`.
+  # 
+  # Does not start the agent.
+  # 
+  # @param [String] label:
+  #   The agent's label, which is its:
+  #   
+  #   1.  Unique identifier in launchd
+  #   2.  Domain via the proxy.
+  #   3.  Property list filename (plus the `.plist` extension).
+  # 
+  # @param [Boolean] force:
+  #   Overwrite any existing agent with the same label.
+  # 
+  # @param [String | Pathname] workdir:
+  #   Working directory for the agent.
+  # 
+  # @param [Hash<Symbol, Object>] **kwds
+  #   Additional keyword arguments to pass to {.create_plist_data}.
+  # 
+  # @return [Locd::Agent]
+  #   The new agent.
+  # 
+  def self.add  label:,
+                force: false,
+                workdir: Pathname.getwd,
+                **kwds
+    logger.debug "Creating {Agent}...",
+      label: label,
+      force: force,
+      workdir: workdir,
+      **kwds
+    
+    plist_abs_path = self.plist_abs_path label
+    
+    # Handle file already existing
+    if File.exists? plist_abs_path
+      logger.debug "Agent already exists!",
+        label: label,
+        path: plist_abs_path
+      
+      if force
+        logger.info "Forcing agent creation (overwrite)",
+          label: label,
+          path: plist_abs_path
+      else
+        raise binding.erb <<~END
+          Agent <%= label %> already exists at:
+          
+              <%= plist_abs_path %>
+          
+        END
+      end
+    end
+
+    plist_data = create_plist_data label: label, workdir: workdir, **kwds
+    logger.debug "Property list created", data: plist_data
+    
+    plist_string = Plist::Emit.dump plist_data
+    plist_abs_path.write plist_string
+    logger.debug "Property list written", path: plist_abs_path
+    
+    from_path( plist_abs_path ).tap { |agent|
+      logger.debug { ["{Agent} added", agent: agent] }
+    }
+  end # .add
+  
+  
+  # @!group Removing Agents
+  # ----------------------------------------------------------------------------
+  
+  # Find an agent using a label pattern and call {#remove} on it.
+  # 
+  # @param (see .find_only!)
+  # @return (see #remove)
+  # @raise See {.find_only!} and {#remove}
+  # 
+  def self.remove *find_only_args
+    Locd::Agent.find_only!( *find_only_args ).remove
+  end # .remove
+  
+  # @!endgroup
+  
+  
+  # Attributes
+  # ============================================================================
+  
+  # Hash of the agent's `.plist` file (keys and values from the top-level
+  # `<dict>` element).
+  # 
+  # @return [Hash<String, V>]
+  #   Check out the [plist][] gem for an idea of what types `V` may assume.
+  #   
+  #   [plist]: http://www.rubydoc.info/gems/plist
+  #     
+  attr_reader :plist
+  
+  
+  # Absolute path to the agent's `.plist` file.
+  # 
+  # @return [Pathname]
+  #     
+  attr_reader :path
+  
+  
+  # Constructor
+  # ============================================================================
+  
+  def initialize plist:, path:
+    @path = path.to_pn.expand_path
+    @plist = plist
+    @status = :UNKNOWN
+    
+    
+    # Sanity check...
+    
+    unless plist.key? CONFIG_KEY
+      raise ArgumentError.new binding.erb <<~END
+        Not a Loc'd plist (no <%= Locd::Agent::CONFIG_KEY %> key)
+        
+        path: <%= path %>
+        plist:
+        
+            <%= plist.pretty_inspect %>
+        
+      END
+    end
+    
+    unless @path.basename( '.plist' ).to_s == label
+      raise ArgumentError.new binding.erb <<~END
+        Label and filename don't match.
+        
+        Filename should be `<label>.plist`, found
+        
+            label:    <%= label %>
+            filename: <%= @path.basename %>
+            path:     <%= path %>
+      
+      END
+    end
+    
+    init_ensure_out_dirs_exist
+  end
+  
+  
+  # Instance Methods
+  # ============================================================================
+  
+  # @return [Boolean]
+  #   `true` if the {#log_path} is the default one we generate.
+  def default_log_path?
+    log_path == self.class.default_log_path( workdir, label )
+  end
+  
+  
+  # @!group Instance Methods: Attribute Readers
+  # ----------------------------------------------------------------------------
+  # 
+  # Methods to read proxied and computed attributes.
+  # 
+  
+  # @return [String]
+  # 
+  def label
+    plist['Label'].freeze
+  end
+  
+  
+  # Current process ID of the agent (if running).
+  # 
+  # @param (see #status)
+  # 
+  # @return [nil]
+  #   No process ID (not running).
+  # 
+  # @return [Fixnum]
+  #   Process ID.
+  # 
+  def pid refresh: false
+    status( refresh: refresh ) && status[:pid]
+  end
+
+
+  def running? refresh: false
+    status( refresh: refresh )[:running]
+  end
+
+
+  def stopped? refresh: false
+    !running?( refresh: refresh )
+  end
+
+  # 
+  # 
+  # @return [nil]
+  #   No last exit code information.
+  # 
+  # @return [Fixnum]
+  #   Last exit code of process.
+  # 
+  def last_exit_code refresh: false
+    status( refresh: refresh ) && status[:last_exit_code]
+  end
+  
+  
+  def config
+    plist[CONFIG_KEY]
+  end
+  
+  
+  def cmd_template
+    config['cmd_template']
+  end
+  
+  
+  # @return [Pathname]
+  #   The working directory of the agent.
+  def workdir
+    plist['WorkingDirectory'].to_pn
+  end
+  
+  
+  # Path the agent is logging `STDOUT` to.
+  # 
+  # @return [Pathname]
+  #   If the agent is logging `STDOUT` to a file path.
+  # 
+  # @return [nil]
+  #   If the agent is not logging `STDOUT`.
+  # 
+  def out_path
+    plist['StandardOutPath'].to_pn if plist['StandardOutPath']
+  end
+  
+  alias_method :log_path, :out_path
+  
+  
+  # Path the agent is logging `STDERR` to.
+  # 
+  # @return [Pathname]
+  #   If the agent is logging `STDERR` to a file path.
+  # 
+  # @return [nil]
+  #   If the agent is not logging `STDERR`.
+  # 
+  def err_path
+    plist['StandardErrorPath'].to_pn if plist['StandardErrorPath']
+  end
+  
+  # @!endgroup Instance Methods: Attribute Readers
+  
+  
+  # @!group Instance Methods: `launchctl` Interface
+  # ----------------------------------------------------------------------------
+  
+  # The agent's status from parsing `launchctl list`.
+  # 
+  # Status is read on demand and cached on the instance.
+  # 
+  # @param [Boolean] refresh:
+  #   When `true`, will re-read from `launchd` (and cache results)
+  #   before returning.
+  # 
+  # @return [Hash{pid: (Fixnum | nil), status: (Fixnum | nil)}]
+  #   When `launchd` has a status entry for the agent.
+  # 
+  # @return [nil]
+  #   When `launchd` doesn't have a status entry for the agent.
+  # 
+  def status refresh: false
+    if refresh || @status == :UNKNOWN
+      raw_status = Locd::Launchctl.status[label]
+      
+      # Happens when the agent is not loaded
+      @status = if raw_status.nil?
+        {
+          loaded: false,
+          running: false,
+          pid: nil,
+          last_exit_code: nil,
+        }
+      else
+        {
+          loaded: true,
+          running: !raw_status[:pid].nil?,
+          pid: raw_status[:pid],
+          last_exit_code: raw_status[:status],
+        }
+      end
+    end
+    
+    @status
+  end
+  
+  
+  # Load the agent by executing `launchctl load [OPTIONS] LABEL`.
+  # 
+  # This is a bit low-level; you probably want to use {#start}.
+  # 
+  # @param [Boolean] force:
+  #   Force the loading of the plist. Ignore the `launchd` *Disabled* key.
+  # 
+  # @param [Boolean] write:
+  #   Overrides the `launchd` *Disabled* key and sets it to `false`.
+  # 
+  # @return [self]
+  # 
+  def load force: false, write: false
+    logger.debug "Loading #{ label } agent...", force: force, write: write
+    
+    result = Locd::Launchctl.load! path, force: force, write: write
+    
+    message = if result.err =~ /service\ already\ loaded/
+      "already loaded"
+    else
+      "LOADED"
+    end
+    
+    status_info message, status: status
+    
+    self
+  end
+  
+  
+  # Unload the agent by executing `launchctl unload [OPTIONS] LABEL`.
+  # 
+  # This is a bit low-level; you probably want to use {#stop}.
+  # 
+  # @param [Boolean] write:
+  #   Overrides the `launchd` *Disabled* key and sets it to `true`.
+  # 
+  # @return [self]
+  # 
+  def unload write: false
+    logger.debug "Unloading #{ label } agent...", write: write
+    
+    result = Locd::Launchctl.unload! path, write: write
+    
+    status_info "UNLOADED"
+    
+    self
+  end
+  
+  
+  # {#unload} then {#load} the agent.
+  # 
+  # @param (see #load)
+  # @return (see #load)
+  # 
+  def reload force: false, write: false
+    unload
+    load force: force, write: write
+  end
+  
+  
+  # Start the agent.
+  # 
+  # If `load` is `true`, calls {#load} first, and defaults it's `force` keyword
+  # argument to `true` (the idea being that you actually want the agent to
+  # start, even if it's {#disabled?}).
+  # 
+  # @param [Boolean] load:
+  #   Call {#load} first, passing it `write` and `force`.
+  # 
+  # @param force (see #load)
+  # @param write (see #load)
+  # 
+  # @return [self]
+  # 
+  def start load: true, force: true, write: false
+    logger.trace "Starting `#{ label }` agent...",
+      load: load,
+      force: force,
+      write: write
+    
+    self.load( force: force, write: write ) if load
+    
+    Locd::Launchctl.start! label
+    status_info "STARTED"
+    
+    self
+  end
+  
+  
+  # Stop the agent.
+  # 
+  # @param [Boolean] unload:
+  #   Call {#unload} first, passing it `write`.
+  # 
+  # @param write (see #unload)
+  # 
+  # @return [self]
+  # 
+  def stop unload: true, write: false
+    logger.debug "Stopping `#{ label } agent...`",
+      unload: unload,
+      write: write
+    
+    Locd::Launchctl.stop label
+    status_info "STOPPED"
+    
+    self.unload( write: write ) if unload
+    
+    self
+  end
+  
+  
+  # Restart the agent ({#stop} then {#start}).
+  # 
+  # @param unload (see #stop)
+  # @param force  (see #start)
+  # @param write  (see #start)
+  # 
+  # @return [self]
+  # 
+  def restart unload: true, force: true, write: false
+    stop unload: unload
+    start load: unload, force: force, write: write
+  end # #restart
+  
+  
+  # Remove the agent by removing it's {#path} file. Will {#stop} and
+  # {#unloads} the agent first.
+  # 
+  # @return [self]
+  # 
+  def remove
+    stop unload: true
+    
+    FileUtils.rm path
+    status_info "REMOVED"
+    
+    self
+  end
+  
+  # @!endgroup Instance Methods: `launchctl` Interface
+  
+  
+  # Update specific values on the agent, which *may* change it's file path if
+  # a different label is provided.
+  # 
+  # **_Does not mutate this instance! Returns a new {Locd::Agent} with the
+  # updated values._**
+  # 
+  # @param (see .create_plist_data)
+  # 
+  # @return [Locd::Agent]
+  #   A new instance with the updated values.
+  # 
+  def update **values
+    logger.trace "Updating `#{ label }` agent", **values
+    
+    # Remove the `cmd_template` if it's nil of an empty array so that
+    # we use the current one
+    if  values[:cmd_template].nil? ||
+        (values[:cmd_template].is_a?( Array ) && values[:cmd_template].empty?)
+      values.delete  :cmd_template
+    end
+    
+    # Make a new plist
+    new_plist_data = self.class.create_plist_data(
+      label: label,
+      workdir: workdir,
+      
+      log_path: (
+        values.key?( :log_path ) ? values.key?( :log_path ) : (
+          default_log_path? ? nil : log_path
+        )
+      ),
+      
+      # Include the config values, which have the `cmd_template` as well as
+      # any extras. Need to symbolize the keys to make the kwds call work
+      **config.sym_keys,
+      
+      # Now merge over with the values we received
+      **values.except( :log_path )
+    )
+    
+    new_label = new_plist_data['Label']
+    new_plist_abs_path = self.class.plist_abs_path new_label
+    
+    if new_label == label
+      # We maintained the same label, overwrite the file
+      path.write Plist::Emit.dump( new_plist_data )
+      
+      # Load up the new agent from the same path, reload and return it
+      self.class.from_path( path ).reload
+      
+    else
+      # The label has changed, so we want to make sure we're not overwriting
+      # another agent
+      
+      if File.exists? new_plist_abs_path
+        # There's someone already there! Bail out
+        raise binding.erb <<-END
+          A different agent already exists at:
+          
+              <%= new_plist_abs_path %>
+          
+          Remove that agent first if you really want to replace it with an
+          updated version of this one.
+          
+        END
+      end
+      
+      # Ok, we're in the clear (save for the obvious race condition, but,
+      # hey, it's a development tool, so fuck it... it's not even clear it's
+      # possible to do an atomic file add from Ruby)
+      new_plist_abs_path.write Plist::Emit.dump( new_plist_data )
+      
+      # Remove this agent
+      remove
+      
+      # And instantiate and load a new agent from the new path
+      self.class.from_path( new_plist_abs_path ).load
+      
+    end
+  end # #update
+  
+  
+  
+  # @!group Instance Methods: Language Integration
+  # ----------------------------------------------------------------------------
+  
+  # Compare to another agent by their labels.
+  # 
+  # @param [Locd::Agent] other
+  #   The other agent.
+  # 
+  # @return [Fixnum]
+  # 
+  def <=> other
+    Locd::Label.compare label, other.label
+  end
+  
+  
+  def to_h
+    self.class::TO_H_NAMES.map { |name|
+      [name, send( name )]
+    }.to_h
+  end
+  
+  
+  def to_json *args
+    to_h.to_json *args
+  end
+  
+  
+  # TODO Doesn't work!
+  # 
+  def to_yaml *args
+    to_h.to_yaml *args
+  end
+  
+  # @!endgroup Language Integration Instance Methods
+  
+  
+  protected
+  # ========================================================================
+    
+    # Create directories for any output file if they don't already exist.
+    # 
+    # We *need* to create the directories for the output files *before*
+    # we ever try to start the agent because otherwise it seems that
+    # `launchd` *will create them*, but it will *create them as `root`*, then
+    # try to write to them *as the user*, fail, and crash the process with
+    # a `78` exit code.
+    # 
+    # How or why that makes sense to `launchd`, who knows.
+    # 
+    # But, since it's nice to be able to start the agents through `launchctl`
+    # or `lunchy`, and having a caveat that *they need to be started through
+    # Loc'd the first time* sucks, during initialization seems like a
+    # reasonable time, at least for now (I don't like doing stuff like this
+    # curing construction, but whatever for the moment, let's get it working).
+    # 
+    # @return [nil]
+    # 
+    def init_ensure_out_dirs_exist
+      [out_path, err_path].compact.each do |path|
+        dir = path.dirname
+        unless dir.exist?
+          logger.debug "Creating directory for output",
+            label: label,
+            dir: dir,
+            path: path
+          FileUtils.mkdir_p dir
+        end
+      end
+      
+      nil
+    end
+    
+    
+    def status_info message, **details
+      logger.info "Agent `#{ label }` #{ message }", **details
+    end
+    
+  # end protected
+  
+end # class Locd::Launchd
+
+
+# Post-Processing
+# =======================================================================
+
+require_relative './agent/site'
+require_relative './agent/job'
+require_relative './agent/system'
+require_relative './agent/proxy'
+require_relative './agent/rotate_logs'