# encoding: UTF-8
# frozen_string_literal: true

# Refinements
# =======================================================================

require 'nrser/refinements/types'
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
  
  
  # Is an agent label for a system agent of *this* Loc'd instance?
  # 
  # @note
  #   We can't tell if a label is a system agent label for *any* Loc'd instance
  #   since the prefix can be configured to anything (via the
  #   `locd:namespace:label` key).
  # 
  # @return [Boolean]
  # 
  def self.instance_label? label
    label.is_a?( String ) &&
    label.start_with?( "#{ Locd.config[:namespace, :label] }." )
  end
  
  
  # Is the plist for a system agent of *any* Loc'd instance?
  # 
  # In case it's not obvious, this tests true given plists of system agents 
  # of *other* Loc'd instance configurations besides just this one, which can
  # be useful to weed things out. Maybe.
  # 
  # @param plist (see Locd::Agent.plist?)
  # 
  # @return [Boolean]
  #   `true` if the plist is for a system agent.
  # 
  def self.plist? plist
    plist.dig( Locd.config[:agent, :config_key], 'is_system' ) == true
  end # .plist?
  
  
  # Is a plist for a system agent of *this* Loc'd instance?
  # 
  # @see plist?
  # @see instance_label?
  # 
  # @param plist (see Locd::Agent.plist?)
  # 
  # @return [Boolean]
  #   `true` if the plist is for a system agent for this Loc'd instance config.
  # 
  def self.instance_plist? plist
    plist?( plist ) && instance_label?( plist[ 'Label' ] )
  end
  
  
  # 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 label = self.label
      unless label == self.label
        raise NRSER::AttributeError.new \
          "System agents have a fixed label, must be", self.label
      end
      
      super( label )
    end
    
    
    def get! label = self.label
      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.to_s,
        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