locd 0.1.3

data/lib/locd/agent/job.rb

@@ -0,0 +1,142 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Refinements
+# =======================================================================
+
+using NRSER
+using NRSER::Types
+
+
+# Definitions
+# =======================================================================
+
+# A user-defined agent that runs periodically to perform a task.
+# 
+class Locd::Agent::Job < Locd::Agent
+  
+  # Modules
+  # ============================================================================
+  
+  module Types
+    def self.start_calendar_interval
+      t.and(
+        t.shape(
+          minute:   t.maybe( t.non_neg_int ),
+          hour:     t.maybe( t.non_neg_int ),
+          day:      t.maybe( t.and( t.int, 0..31 ) ),
+          weekday:  t.maybe( t.and( t.int, 0..7 ) ),
+          month:    t.maybe( t.and( t.int, 0..11 ) ),
+        ),
+        # All values can't be `nil`
+        t.not( t.hash_( values: nil ) ),
+      )
+    end
+    
+    def self.start_calendar_intervals
+      t.array start_calendar_interval
+    end
+  end
+  
+  
+  
+  # Class Methods
+  # ======================================================================
+  
+  # @todo Document plist? method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def self.plist? plist
+    super( plist ) && ( plist.key?( 'StartInterval' ) ||
+                        plist.key?( 'StartCalendarInterval' ) )
+  end # .plist?
+  
+  
+  # @!group Creating Servers
+  # --------------------------------------------------------------------------
+
+  # Create the `launchd` property list data for a new {Locd::Agent::Site}, which
+  # has an additional `port:` keyword versus {Locd::Agent.create_plist_data}.
+  # 
+  # @param cmd_template   (see Locd::Agent.create_plist_data)
+  # @param label          (see Locd::Agent.create_plist_data)
+  # @param workdir        (see Locd::Agent.create_plist_data)
+  # @param log_path       (see Locd::Agent.create_plist_data)
+  # @param keep_alive     (see Locd::Agent.create_plist_data)
+  # @param run_at_load    (see Locd::Agent.create_plist_data)
+  # 
+  # @param [Fixnum | Hash] start_interval:
+  #   How often to start the job:
+  #   
+  #   1.  {Fixnum} - Run about every X number of seconds (positive integer).
+  #   2.  {Hash}
+  # 
+  # @return (see Locd::Agent.create_plist_data)
+  # 
+  # @example Run a job about every minute
+  #   Locd::Agent::Job.create_plist_date \
+  #     cmd_template:     'myexe do-some-job',
+  #     label:            'myexe.do-some-job',
+  #     workdir:          '~',
+  #     start_interval:   60
+  # 
+  # @example Run a job every hour, on the hour
+  #   Locd::Agent::Job.create_plist_date \
+  #     cmd_template:     'myexe do-some-job',
+  #     label:            'myexe.do-some-job',
+  #     workdir:          '~',
+  #     start_interval:   {
+  #                         minute: 0,
+  #                       }
+  # 
+  def self.create_plist_data  cmd_template:,
+                              label:,
+                              workdir:,
+                              start_interval:,
+                              log_path: nil,
+                              keep_alive: false,
+                              run_at_load: false,
+                              **extras
+    
+    plist_data = super  cmd_template: cmd_template,
+                        label: label,
+                        workdir: workdir,
+                        log_path: log_path,
+                        keep_alive: keep_alive,
+                        run_at_load: run_at_load,
+                        **extras
+    
+    start_interval_data = t.match start_interval,
+      t.pos_int,
+        {"StartInterval" => start_interval},
+      
+      Types.start_calendar_interval,
+        ->( interval ) {
+          interval.map { |key, value| [key.to_s.capitalize, value] }.to_h
+        },
+      
+      Types.start_calendar_intervals,
+        ->( intervals ) {
+          intervals.map { |interval|
+            interval.map { |key, value| [key.to_s.capitalize, value] }.to_h
+          }
+        }
+    
+    plist_data.merge start_interval_data
+  end
+  
+  
+  # Attributes
+  # ======================================================================
+  
+  
+  # Instance Methods
+  # ======================================================================
+  
+  
+end # class Locd::Agent::Job

data/lib/locd/agent/proxy.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+require 'plist'
+require 'fileutils'
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+
+# Refinements
+# =======================================================================
+
+using NRSER
+using NRSER::Types
+
+
+# Definitions
+# =======================================================================
+
+
+# An server {Locd::Agent} (HTTP only at the moment) that the proxy can
+# route requests to.
+# 
+class Locd::Agent::Proxy < Locd::Agent
+  
+  # Mixins
+  # ============================================================================
+  
+  include Locd::Agent::System
+  
+  
+  # Constants
+  # ==========================================================================
+  
+  # Attribute / method names that {#to_h} uses.
+  # 
+  # @return [Hamster::SortedSet<Symbol>]
+  # 
+  TO_H_NAMES = Locd::Agent::TO_H_NAMES.union [:port, :url]
+  
+  
+  # Class Methods
+  # ==========================================================================
+  
+  # @return [String]
+  #   The non-namespace part of the proxy's label.
+  # 
+  def self.label_name
+    "proxy"
+  end
+  
+  
+  # @todo Document cmd_template method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def self.default_cmd_template
+    "{bin} proxy run"
+  end # .cmd_template
+  
+  
+  def self.default_write_kwds cmd_template: self.default_cmd_template,
+                              **kwds
+    super(
+      keep_alive: true,
+      run_at_load: true,
+      port: Locd.config[:proxy, :port],
+      cmd_template: cmd_template,
+      **kwds,
+      label: self.label
+    )
+  end
+  
+  
+  # Instance Methods
+  # ============================================================================
+  
+  # @!group Instance Methods: Attribute Readers
+  # ----------------------------------------------------------------------------
+  # 
+  # Methods to read proxied and computed attributes.
+  # 
+  
+  # @return [Fixnum]
+  #   Port service runs on.
+  def port
+    config['port']
+  end
+  
+  
+  # @return [String]
+  #   The URL the agent can be reached at through the proxy.
+  def url
+    "http://#{ label }:#{ Locd.get_port }"
+  end
+  
+  # @!endgroup Instance Methods: Attribute Readers
+  
+end # class Locd::Agent::Proxy

data/lib/locd/agent/rotate_logs.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+require 'plist'
+require 'fileutils'
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+
+# Refinements
+# =======================================================================
+
+using NRSER
+using NRSER::Types
+
+
+# Definitions
+# =======================================================================
+
+
+# An server {Locd::Agent} (HTTP only at the moment) that the proxy can
+# route requests to.
+# 
+class Locd::Agent::RotateLogs < Locd::Agent::Job
+  
+  # Mixins
+  # ============================================================================
+  
+  include Locd::Agent::System
+  
+  
+  # Class Methods
+  # ==========================================================================
+  
+  # @return [String]
+  #   The non-namespace part of the log rotator agent's label.
+  # 
+  def self.label_name
+    "rotate_logs"
+  end
+  
+  
+  # Not much to explain here.
+  # 
+  # @return [String]
+  # 
+  def self.default_cmd_template
+    "{bin} rotate-logs run"
+  end # .cmd_template
+  
+  
+  def self.default_start_interval
+    NRSER.deep_symbolize_keys Locd.config[:rotate_logs, :start_interval]
+  end
+  
+  
+  # Patch in {.default_cmd_template} as, well, the default for `cmd_template`.
+  # 
+  # @param cmd_template: (see Locd::Agent.render_cmd)
+  # 
+  # @param **kwds (see Locd::Agent::System::ClassMethods#default_write_kwds)
+  # 
+  # @return (see Locd::Agent::System::ClassMethods#default_write_kwds)
+  # 
+  def self.default_write_kwds cmd_template: self.default_cmd_template,
+                              start_interval: self.default_start_interval,
+                              **kwds
+    super \
+      cmd_template: cmd_template,
+      start_interval: start_interval,
+      **kwds
+  end
+  
+end # class Locd::Agent::RotateLogs

data/lib/locd/agent/site.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+require 'plist'
+require 'fileutils'
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+
+# Refinements
+# =======================================================================
+
+using NRSER
+using NRSER::Types
+
+
+# Definitions
+# =======================================================================
+
+
+# An site is a {Locd::Agent} that the proxy can route HTTP requests to.
+# 
+# If you send an HTTP request to the proxy with the site's label as the
+# host, the proxy will start the site if it isn't running and route the
+# request to it's {#port}.
+# 
+# Combined with DNSMasq pointing the site's label to the proxy (and using
+# the port the proxy is running on) this allows you to open the site's
+# {#url} in the browser (or make a request to it from anything that resolves
+# DNS properly through DNSMasq... should work fine for APIs and other HTTP
+# services) and get through to the agent.
+# 
+class Locd::Agent::Site < Locd::Agent
+  
+  # Constants
+  # ==========================================================================
+  
+  # Address we expect servers to bind to so we can reach them. Provided
+  # during command rendering as `{bind}` so it can be used when running
+  # service commands.
+  # 
+  # For the moment at least this seems to need to be `127.0.0.1` 'cause I
+  # think ProxyMachine had trouble connecting to `localhost`, so services
+  # need to bind to it or be reachable at it.
+  # 
+  # @return [String]
+  # 
+  BIND = '127.0.0.1'.freeze
+  
+  
+  # Attribute / method names that {#to_h} uses.
+  # 
+  # @return [Hamster::SortedSet<Symbol>]
+  # 
+  TO_H_NAMES = Locd::Agent::TO_H_NAMES.union [:port, :url]
+  
+  
+  # Class Methods
+  # ==========================================================================
+  
+  
+  # See if a parsed plist looks like a site.
+  # 
+  # @param [Hash<String, Object>] plist
+  #   Property list parsed by {Plist.parse_xml}.
+  # 
+  # @return [Boolean]
+  #    `true` if we think this `plist` belongs to a site.
+  # 
+  def self.plist? plist
+    !! plist.dig( Locd::Agent::CONFIG_KEY, 'port' )
+  end # .plist?
+  
+  
+  
+  # @!group Querying
+  # --------------------------------------------------------------------------
+  
+  # Sorted set of all ports configured for installed {Locd::Agent::Site}.
+  # 
+  # Used to determine available ports to allocate when creating new services.
+  # 
+  # @return [Hamster::SortedSet<Fixnum>]
+  # 
+  def self.ports
+    Hamster::SortedSet.new all.values.map( &:port )
+  end
+  
+  # @!endgroup
+  
+  
+  # @!group Creating Servers
+  # --------------------------------------------------------------------------
+  
+  # Create the `launchd` property list data for a new {Locd::Agent::Site}, which
+  # has an additional `port:` keyword versus {Locd::Agent.create_plist_data}.
+  # 
+  # @param cmd_template   (see Locd::Agent.create_plist_data)
+  # @param label          (see Locd::Agent.create_plist_data)
+  # @param workdir        (see Locd::Agent.create_plist_data)
+  # @param log_path       (see Locd::Agent.create_plist_data)
+  # @param keep_alive     (see Locd::Agent.create_plist_data)
+  # @param run_at_load    (see Locd::Agent.create_plist_data)
+  # 
+  # @param [nil | Fixnum | String] port
+  #   Port to run the service on. If you don't provide one, one will be
+  #   provided for you (see {Locd::Proxy.allocate_port}).
+  # 
+  # @param [String] bind
+  #   Address that the server should bind to.
+  # 
+  # @return (see Locd::Agent.create_plist_data)
+  # 
+  def self.create_plist_data  cmd_template:,
+                              label:,
+                              workdir:,
+                              log_path: nil,
+                              keep_alive: false,
+                              run_at_load: false,
+                              port: nil,
+                              bind: Locd.config[:site, :bind]
+    # Allocate a port if one was not provided
+    port = if port.nil?
+      Locd::Proxy.allocate_port
+    else
+      # or just normalize to {Fixnum}
+      port.to_i
+    end
+    
+    super cmd_template: cmd_template,
+          label: label,
+          workdir: workdir,
+          log_path: log_path,
+          keep_alive: keep_alive,
+          run_at_load: run_at_load,
+          # Extras specific to {Locd::Agent::Site}:
+          port: port,
+          bind: bind
+  end # .create_plist_data
+  
+  
+  # Instance Methods
+  # ============================================================================
+  
+  # @!group Instance Methods: Attribute Readers
+  # ----------------------------------------------------------------------------
+  # 
+  # Methods to read proxied and computed attributes.
+  # 
+  
+  # @return [Fixnum]
+  #   Port service runs on.
+  def port
+    config['port']
+  end
+  
+  
+  # @return [String]
+  #   The URL the agent can be reached at through the proxy.
+  def url
+    "http://#{ label }:#{ Locd::Proxy.port }"
+  end
+  
+  # @!endgroup Instance Methods: Attribute Readers
+  
+end # class Locd::Launchd