opn_api 0.1.0

data/lib/opn_api/errors.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module OpnApi
+  # Base error class for all opn_api exceptions.
+  class Error < StandardError; end
+
+  # Raised when a network connection cannot be established
+  # (e.g. ECONNREFUSED, EHOSTUNREACH, ETIMEDOUT).
+  class ConnectionError < Error; end
+
+  # Raised when an HTTP request times out (open_timeout or read_timeout).
+  class TimeoutError < Error; end
+
+  # Raised when the OPNsense API returns a non-2xx HTTP response.
+  class ApiError < Error
+    # @return [Integer] HTTP status code
+    attr_reader :code
+
+    # @return [String] HTTP response body
+    attr_reader :body
+
+    # @return [String] Request URI that caused the error
+    attr_reader :uri
+
+    # @param message [String]
+    # @param code [Integer] HTTP status code
+    # @param body [String] Response body
+    # @param uri [String] Request URI
+    def initialize(message, code:, body:, uri:)
+      @code = code
+      @body = body
+      @uri  = uri
+      super(message)
+    end
+  end
+
+  # Raised when a configuration file is missing or malformed.
+  class ConfigError < Error; end
+
+  # Raised when IdResolver cannot translate a name to an ID or vice versa.
+  class ResolveError < Error; end
+
+  # Raised when a configtest returns ALERT (e.g. HAProxy configtest).
+  class ConfigTestError < Error; end
+end

data/lib/opn_api/id_resolver.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module OpnApi
+  # Resolves ModelRelationField UUIDs/IDs <-> names for OPNsense resources.
+  #
+  # Maintains a per-run class-level cache keyed by
+  # "device:endpoint:id_field:name_field" to avoid redundant API calls.
+  #
+  # Supports:
+  # - Standard UUID fields (ModelRelationField) — id_field: 'uuid', name_field: 'name'
+  # - Certificate fields (CertificateField) — id_field: 'refid', name_field: 'descr'
+  # - Cron job fields — id_field: 'uuid', name_field: 'description'
+  # - Dot-path fields for nested configs — e.g. 'general.stats.allowedUsers'
+  #
+  # @example
+  #   relation_fields = {
+  #     'linkedServers' => { endpoint: 'haproxy/settings/search_servers', multiple: true },
+  #     'sslCA' => { endpoint: 'trust/ca/search', id_field: 'refid', name_field: 'descr' },
+  #   }
+  #   translated = OpnApi::IdResolver.translate_to_names(client, 'myfw', relation_fields, config)
+  module IdResolver
+    UUID_RE = %r{\A[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}\z}
+
+    @cache = {}
+
+    # Queries the given endpoint once and builds id<->name maps.
+    # Subsequent calls for the same cache key are no-ops.
+    #
+    # @param client [OpnApi::Client]
+    # @param device [String]
+    # @param endpoint [String]
+    # @param id_field [String] Field containing the ID (default: 'uuid')
+    # @param name_field [String] Field containing the display name (default: 'name')
+    # @param method [Symbol] HTTP method to use (default: :post)
+    def self.populate(client, device, endpoint, id_field: 'uuid', name_field: 'name', method: :post)
+      key = cache_key(device, endpoint, id_field, name_field)
+      return if @cache.key?(key)
+
+      id_to_name = {}
+      name_to_id = {}
+      begin
+        response = method == :get ? client.get(endpoint) : client.post(endpoint, {})
+        rows = response['rows'] || []
+        rows.each do |row|
+          id   = row[id_field].to_s
+          name = row[name_field].to_s
+          next if id.empty? || name.empty?
+
+          id_to_name[id] = name
+          name_to_id[name] = id
+        end
+      rescue OpnApi::Error => e
+        OpnApi.logger.warning(
+          "IdResolver: failed to populate '#{endpoint}' " \
+          "for '#{device}': #{e.message}",
+        )
+      end
+
+      @cache[key] = { id_to_name: id_to_name, name_to_id: name_to_id }
+    end
+
+    # Returns a deep copy of +config+ with each relation-field value translated
+    # from IDs to names. Falls back to the original value if not found.
+    # Supports dot-path field names for nested config hashes.
+    #
+    # @param client [OpnApi::Client]
+    # @param device [String]
+    # @param relation_fields [Hash] field_name => { endpoint:, multiple:, ... }
+    # @param config [Hash]
+    # @return [Hash]
+    def self.translate_to_names(client, device, relation_fields, config)
+      result = deep_dup(config)
+      relation_fields.each do |field, opts|
+        id_field    = opts[:id_field]   || 'uuid'
+        name_field  = opts[:name_field] || 'name'
+        http_method = opts[:method]     || :post
+
+        parent, last_key = dig_path(result, field)
+        next unless parent
+
+        value = parent[last_key]
+        next if value.nil? || value.to_s.empty?
+
+        populate(client, device, opts[:endpoint],
+                 id_field: id_field, name_field: name_field, method: http_method)
+        entry = @cache[cache_key(device, opts[:endpoint], id_field, name_field)] || {}
+        map = entry[:id_to_name] || {}
+
+        parent[last_key] = if opts[:multiple]
+                             value.to_s.split(',').map do |item|
+                               item = item.strip
+                               map[item] || item
+                             end.join(',')
+                           else
+                             map[value.to_s] || value.to_s
+                           end
+      end
+      result
+    end
+
+    # Returns a deep copy of +config+ with each relation-field value translated
+    # from names to IDs. Raises ResolveError if a name cannot be resolved.
+    # Values that are already valid IDs pass through unchanged.
+    # Supports dot-path field names for nested config hashes.
+    #
+    # @param client [OpnApi::Client]
+    # @param device [String]
+    # @param relation_fields [Hash] field_name => { endpoint:, multiple:, ... }
+    # @param config [Hash]
+    # @return [Hash]
+    def self.translate_to_uuids(client, device, relation_fields, config)
+      result = deep_dup(config)
+      relation_fields.each do |field, opts|
+        id_field    = opts[:id_field]   || 'uuid'
+        name_field  = opts[:name_field] || 'name'
+        http_method = opts[:method]     || :post
+
+        parent, last_key = dig_path(result, field)
+        next unless parent
+
+        value = parent[last_key]
+        next if value.nil? || value.to_s.empty?
+
+        key = cache_key(device, opts[:endpoint], id_field, name_field)
+        populate(client, device, opts[:endpoint],
+                 id_field: id_field, name_field: name_field, method: http_method)
+        entry = @cache[key] || {}
+        id_to_name = entry[:id_to_name] || {}
+
+        parent[last_key] = if opts[:multiple]
+                             value.to_s.split(',').map do |item|
+                               item = item.strip
+                               # Already a known ID — pass through
+                               next item if id_to_name.key?(item)
+                               # Looks like a UUID — pass through
+                               next item if UUID_RE.match?(item)
+
+                               resolve_with_retry(
+                                 client, device, opts[:endpoint],
+                                 id_field, name_field, http_method, item
+                               )
+                             end.join(',')
+                           else
+                             str = value.to_s
+                             if id_to_name.key?(str) || UUID_RE.match?(str)
+                               str
+                             else
+                               resolve_with_retry(
+                                 client, device, opts[:endpoint],
+                                 id_field, name_field, http_method, str
+                               )
+                             end
+                           end
+      end
+      result
+    end
+
+    # Clears all cached mappings. Call between runs or in tests.
+    def self.reset!
+      @cache.clear
+    end
+
+    # Navigates a dotted field path in a hash and returns [parent, last_key].
+    # For 'stats.allowedUsers' on { 'stats' => { 'allowedUsers' => 'x' } }
+    # returns [{ 'allowedUsers' => 'x' }, 'allowedUsers'].
+    # For simple fields like 'defaultBackend', returns [hash, 'defaultBackend'].
+    # Returns [nil, nil] if any intermediate key is missing.
+    def self.dig_path(hash, dotted_field)
+      parts = dotted_field.split('.')
+      parent = hash
+      parts[0..-2].each do |part|
+        parent = parent[part]
+        return [nil, nil] unless parent.is_a?(Hash)
+      end
+      [parent, parts.last]
+    end
+
+    # Deep-duplicates a Hash/Array structure.
+    def self.deep_dup(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) { |(k, v), h| h[k] = deep_dup(v) }
+      when Array
+        obj.map { |v| deep_dup(v) }
+      else
+        obj
+      end
+    end
+
+    # Builds a cache key from device, endpoint, id_field, and name_field.
+    def self.cache_key(device, endpoint, id_field, name_field)
+      "#{device}:#{endpoint}:#{id_field}:#{name_field}"
+    end
+    private_class_method :cache_key
+
+    # Attempts to resolve a name to an ID, retrying once with a cache refresh.
+    # Raises ResolveError if the name cannot be found after retry.
+    def self.resolve_with_retry(client, device, endpoint, id_field, name_field, http_method, name)
+      key = cache_key(device, endpoint, id_field, name_field)
+      entry = @cache[key] || {}
+      name_to_id = entry[:name_to_id] || {}
+
+      resolved = name_to_id[name]
+      unless resolved
+        # Cache miss — refresh and try once more
+        @cache.delete(key)
+        populate(client, device, endpoint,
+                 id_field: id_field, name_field: name_field, method: http_method)
+        entry = @cache[key] || {}
+        name_to_id = entry[:name_to_id] || {}
+        resolved = name_to_id[name]
+      end
+      unless resolved
+        raise OpnApi::ResolveError,
+              "IdResolver: cannot resolve '#{name}' to an ID " \
+              "via '#{endpoint}' on '#{device}'"
+      end
+      resolved
+    end
+    private_class_method :resolve_with_retry
+  end
+end

data/lib/opn_api/logger.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module OpnApi
+  # Pluggable logger with five severity levels.
+  #
+  # Default: writes to $stderr at :info level. For puppet-opn integration,
+  # replace with a logger that delegates to Puppet.debug/notice/warning/err.
+  #
+  # @example Custom logger for Puppet integration
+  #   OpnApi.logger = PuppetLogger.new
+  class Logger
+    LEVELS = %i[debug info notice warning error].freeze
+
+    # @param output [IO] Output stream (default: $stderr)
+    # @param level [Symbol] Minimum severity to log (default: :info)
+    def initialize(output: $stderr, level: :info)
+      @output = output
+      @level  = LEVELS.index(level) || 1
+    end
+
+    LEVELS.each_with_index do |name, idx|
+      define_method(name) do |msg|
+        return if idx < @level
+
+        @output.puts("[opn_api] #{name.upcase}: #{msg}")
+      end
+    end
+  end
+end

data/lib/opn_api/normalize.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module OpnApi
+  # Normalization of OPNsense selection hashes.
+  #
+  # OPNsense returns multi-select/dropdown fields as hashes like:
+  #   { "opt1" => { "value" => "Option 1", "selected" => 1 },
+  #     "opt2" => { "value" => "Option 2", "selected" => 0 } }
+  #
+  # This module collapses them to comma-separated strings of selected
+  # keys (e.g. "opt1") and recurses into nested hashes.
+  module Normalize
+    module_function
+
+    # Recursively normalizes OPNsense selection hashes to simple values.
+    #
+    # @param obj [Object] The value to normalize
+    # @return [Object] Normalized value
+    def normalize_config(obj)
+      return obj unless obj.is_a?(Hash)
+      return normalize_selection(obj) if selection_hash?(obj)
+
+      obj.transform_values { |v| normalize_config(v) }
+    end
+
+    # Detects whether a hash is an OPNsense selection hash.
+    #
+    # A selection hash has non-empty entries where every value is a Hash
+    # containing at least 'value' and 'selected' keys.
+    #
+    # @param hash [Hash]
+    # @return [Boolean]
+    def selection_hash?(hash)
+      hash.is_a?(Hash) &&
+        !hash.empty? &&
+        hash.values.all? { |v| v.is_a?(Hash) && v.key?('value') && v.key?('selected') }
+    end
+
+    # Collapses a selection hash to a comma-separated string of selected keys.
+    #
+    # @param hash [Hash] A selection hash (as detected by selection_hash?)
+    # @return [String] Comma-separated selected keys
+    def normalize_selection(hash)
+      hash.select { |_k, v| v['selected'].to_i == 1 }.keys.join(',')
+    end
+  end
+end

data/lib/opn_api/resource.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module OpnApi
+  # Generic CRUD wrapper for OPNsense API resources.
+  #
+  # Supports three resource patterns:
+  #
+  # 1. Standard CRUD (search/get/add/set/del with UUID)
+  # 2. Singleton settings (GET get / POST set, no UUID, no search/add/del)
+  # 3. Resources with GET-based search (e.g. snapshots, trust_crl)
+  #
+  # @example Via ResourceRegistry (preferred)
+  #   res = OpnApi::ResourceRegistry.build(client, 'haproxy_server')
+  #   res.search
+  #
+  # @example Direct with explicit paths
+  #   res = OpnApi::Resource.new(
+  #     client: client,
+  #     base_path: 'haproxy/settings',
+  #     search_action: 'search_servers',
+  #     crud_action: '%{action}_server',
+  #   )
+  #
+  # @example Singleton settings resource
+  #   res = OpnApi::Resource.new(
+  #     client: client,
+  #     base_path: 'zabbixagent/settings',
+  #     search_action: 'get',
+  #     crud_action: '%{action}',
+  #     singleton: true,
+  #     search_method: :get,
+  #   )
+  #   config = res.show_settings  # GET zabbixagent/settings/get
+  #   res.update_settings(config)   # POST zabbixagent/settings/set
+  class Resource
+    attr_reader :singleton
+
+    # @param client [OpnApi::Client] API client instance
+    # @param base_path [String] Base path (e.g. 'haproxy/settings')
+    # @param search_action [String] Search action name (e.g. 'search_servers')
+    # @param crud_action [String] CRUD action template with %{action} placeholder
+    # @param singleton [Boolean] True for settings resources (no UUID, no search/add/del)
+    # @param search_method [Symbol] HTTP method for search (:post or :get)
+    # @param module_name [String] Legacy: OPNsense module (e.g. 'firewall')
+    # @param controller [String] Legacy: OPNsense controller (e.g. 'alias')
+    # @param resource_type [String] Legacy: Resource type (e.g. 'item')
+    def initialize(client:, base_path: nil, search_action: nil, crud_action: nil,
+                   singleton: false, search_method: :post,
+                   module_name: nil, controller: nil, resource_type: nil)
+      @client = client
+      @singleton = singleton
+      @search_method = search_method
+
+      if base_path
+        # Explicit path mode
+        @base_path = base_path
+        @search_action = search_action
+        @crud_action = crud_action
+      else
+        # Legacy module/controller/type mode
+        @base_path = "#{module_name}/#{controller}"
+        suffix = resource_type.to_s.empty? ? '' : "_#{resource_type}"
+        @search_action = "search#{suffix}"
+        @crud_action = "%{action}#{suffix}"
+      end
+    end
+
+    # Searches for resources matching the given parameters.
+    #
+    # @param params [Hash] Search parameters (passed as POST body, ignored for GET)
+    # @return [Object] Search results (Array<Hash> for standard, Hash for singletons)
+    def search(params = {})
+      path = "#{@base_path}/#{@search_action}"
+      result = if @search_method == :get
+                 @client.get(path)
+               else
+                 @client.post(path, params)
+               end
+      # Singletons return the full response hash (settings structure).
+      # All other searches extract the rows array.
+      return result if @singleton
+
+      result.is_a?(Hash) ? (result['rows'] || []) : result
+    end
+
+    # Retrieves a single resource by UUID.
+    #
+    # @param uuid [String]
+    # @return [Hash] Resource data
+    def get(uuid)
+      @client.get("#{@base_path}/#{crud_path('get')}/#{uuid}")
+    end
+
+    # Retrieves a singleton settings resource (no UUID).
+    #
+    # @return [Hash] Resource data
+    def show_settings
+      @client.get("#{@base_path}/#{crud_path('get')}")
+    end
+
+    # Creates a new resource.
+    #
+    # @param config [Hash] Resource configuration (wrapped in wrapper key)
+    # @return [Hash] API response (typically includes 'uuid' on success)
+    def add(config)
+      @client.post("#{@base_path}/#{crud_path('add')}", config)
+    end
+
+    # Updates an existing resource.
+    #
+    # @param uuid [String]
+    # @param config [Hash] Resource configuration
+    # @return [Hash] API response
+    def set(uuid, config)
+      @client.post("#{@base_path}/#{crud_path('set')}/#{uuid}", config)
+    end
+
+    # Updates a singleton settings resource (no UUID).
+    #
+    # @param config [Hash] Resource configuration
+    # @return [Hash] API response
+    def update_settings(config)
+      @client.post("#{@base_path}/#{crud_path('set')}", config)
+    end
+
+    # Deletes a resource by UUID.
+    #
+    # @param uuid [String]
+    # @return [Hash] API response
+    def del(uuid)
+      @client.post("#{@base_path}/#{crud_path('del')}/#{uuid}", {})
+    end
+
+    private
+
+    # Builds a CRUD action path from the template.
+    # e.g. crud_path('get') with template '%{action}_server' → 'get_server'
+    def crud_path(action)
+      format(@crud_action, action: action)
+    end
+  end
+end