smplkit 3.0.94 → 3.0.96

data/lib/smplkit/{management/audit.rb → audit/forwarders.rb}

@@ -1,40 +1,37 @@
 # frozen_string_literal: true
 
+# SIEM forwarder CRUD for the Smpl Audit client.
+#
+# Forwarders are part of the single unified audit surface — there is no
+# runtime/management split for audit (see +Smplkit::Audit::AuditClient+). This
+# file holds the forwarder CRUD sub-client that the unified +AuditClient+
+# exposes as +.forwarders+:
+#
+# * +ForwardersClient+ — +forwarders.new/get/list/save/delete+
+#
+# The forwarder model classes (+Forwarder+, +ForwarderEnvironment+, …) live in
+# +lib/smplkit/audit/models.rb+.
 module Smplkit
-  module Management
-    # Audit management surface — accessed via +mgmt.audit.forwarders+.
+  module Audit
+    # Surface for +client.audit.forwarders.*+ — manage the customer's
+    # configured SIEM forwarders.
     #
-    # Counterpart to the runtime {Smplkit::Audit::AuditClient}. The
-    # runtime client owns event recording and read-side queries; this
-    # surface owns SIEM forwarder CRUD. ADR-047 §2.7.
-    class AuditNamespace
-      # @return [ForwardersNamespace] CRUD surface for +mgmt.audit.forwarders+.
-      attr_reader :forwarders
-
-      def initialize(api_client)
-        @forwarders = ForwardersNamespace.new(
-          SmplkitGeneratedClient::Audit::ForwardersApi.new(api_client)
-        )
-      end
-    end
-
-    # +mgmt.audit.forwarders.*+ — manage the customer's configured SIEM
-    # forwarders.
-    #
-    # The active-record entry point is {#new_forwarder}: instantiate a
-    # draft, mutate fields, then call {Smplkit::Audit::Forwarder#save}.
-    # The namespace exposes {#list}, {#get}, and {#delete} directly; the
-    # +_create_forwarder+ / +_update_forwarder+ helpers are private and
-    # invoked by {Smplkit::Audit::Forwarder#save}.
-    class ForwardersNamespace
+    # The active-record entry point is {#new}: instantiate a draft, mutate
+    # fields, then call {Smplkit::Audit::Forwarder#save}. The client exposes
+    # {#list}, {#get}, and {#delete} directly; the +_create_forwarder+ /
+    # +_update_forwarder+ helpers are invoked by {Smplkit::Audit::Forwarder#save}.
+    class ForwardersClient
       def initialize(api)
         @api = api
       end
 
-      # Construct an unsaved {Smplkit::Audit::Forwarder} bound to this
-      # namespace. Call +#save+ on the returned instance to persist.
+      # Construct an unsaved {Smplkit::Audit::Forwarder} bound to this client.
+      # Call +#save+ on the returned instance to persist.
       #
-      # @param name [String] Display name.
+      # @param id [String] Caller-supplied unique identifier (the forwarder's
+      #   key). Unique within the account; immutable. The audit service returns
+      #   409 if another live forwarder already uses this id.
+      # @param name [String] Display name. Defaults to +id+ when not supplied.
       # @param forwarder_type [String] One of {Smplkit::Audit::ForwarderType::VALUES}.
       # @param configuration [Smplkit::Audit::HttpConfiguration] Destination
       #   request configuration. Headers carry credentials and are encrypted at
@@ -56,11 +53,9 @@ module Smplkit
       # @param filter [Hash, nil] Optional JSON Logic filter; events that don't
       #   match are recorded as +filtered_out+ deliveries.
       # @param transform [Object, nil] Optional template applied to each event
-      #   before delivery. Free-form by default — the audit service passes the
-      #   value verbatim to the engine named by +transform_type+. Must be paired
-      #   with a non-nil +transform_type+; when +transform_type+ is
-      #   +TransformType::JSONATA+, +transform+ must be a +String+ (the JSONata
-      #   expression).
+      #   before delivery. Must be paired with a non-nil +transform_type+; when
+      #   +transform_type+ is +TransformType::JSONATA+, +transform+ must be a
+      #   +String+ (the JSONata expression).
       # @param transform_type [String, nil] Engine that evaluates +transform+ —
       #   one of {Smplkit::Audit::TransformType::VALUES}. Must be paired with a
       #   non-nil +transform+.
@@ -68,12 +63,12 @@ module Smplkit
       #   nil or both set, or when +transform_type+ is +JSONATA+ and +transform+
       #   is not a +String+.
       # @return [Smplkit::Audit::Forwarder]
-      def new_forwarder(id, forwarder_type:, configuration:, name: nil,
-                        environments: nil, description: nil,
-                        forward_smplkit_events: false,
-                        filter: nil, transform: nil, transform_type: nil)
-        Smplkit::Audit::Forwarder.send(:validate_transform_pair!, transform, transform_type)
-        Smplkit::Audit::Forwarder.new(
+      def new(id, forwarder_type:, configuration:, name: nil,
+              environments: nil, description: nil,
+              forward_smplkit_events: false,
+              filter: nil, transform: nil, transform_type: nil)
+        Forwarder.send(:validate_transform_pair!, transform, transform_type)
+        Forwarder.new(
           self,
           id: id,
           name: name || id,
@@ -91,33 +86,31 @@ module Smplkit
       # List forwarders for the authenticated account.
       #
       # Offset paginated per ADR-014: pass +page_number+ (1-based) and
-      # +page_size+ (default 1000, max 1000). Pass +meta_total: true+ to
-      # populate +total+ and +total_pages+ in the returned +pagination+
-      # block (costs an extra COUNT query server-side).
+      # +page_size+ (default 1000, max 1000). Pass +meta_total: true+ to populate
+      # +total+ and +total_pages+ in the returned +pagination+ block (costs an
+      # extra COUNT query server-side).
       #
       # @return [ForwarderListPage]
       def list(forwarder_type: nil, page_number: nil, page_size: nil, meta_total: nil)
         opts = {}
-        opts[:filter_forwarder_type] = Smplkit::Audit::ForwarderType.coerce(forwarder_type) if forwarder_type
+        opts[:filter_forwarder_type] = ForwarderType.coerce(forwarder_type) if forwarder_type
         opts[:page_number] = page_number if page_number
         opts[:page_size] = page_size if page_size
         opts[:meta_total] = meta_total unless meta_total.nil?
 
-        resp = Smplkit::Audit.call_api { @api.list_forwarders(opts) }
-        forwarders = (resp.data || []).map do |r|
-          Smplkit::Audit::Forwarder.from_resource(r, client: self)
-        end
-        ForwarderListPage.new(forwarders, Smplkit::Audit.extract_pagination(resp.meta))
+        resp = Audit.call_api { @api.list_forwarders(opts) }
+        forwarders = (resp.data || []).map { |r| Forwarder.from_resource(r, client: self) }
+        ForwarderListPage.new(forwarders, Audit.extract_pagination(resp.meta))
       end
 
-      # Fetch a single forwarder by id. The returned instance is bound to
-      # this namespace, so +forwarder.save+ and +forwarder.delete+ work.
+      # Fetch a single forwarder by id. The returned instance is bound to this
+      # client, so +forwarder.save+ and +forwarder.delete+ work.
       #
       # @param forwarder_id [String]
       # @return [Smplkit::Audit::Forwarder]
       def get(forwarder_id)
-        resp = Smplkit::Audit.call_api { @api.get_forwarder(forwarder_id) }
-        Smplkit::Audit::Forwarder.from_resource(resp.data, client: self)
+        resp = Audit.call_api { @api.get_forwarder(forwarder_id) }
+        Forwarder.from_resource(resp.data, client: self)
       end
 
       # Soft-delete a forwarder.
@@ -125,7 +118,7 @@ module Smplkit
       # @param forwarder_id [String]
       # @return [nil]
       def delete(forwarder_id)
-        Smplkit::Audit.call_api { @api.delete_forwarder(forwarder_id) }
+        Audit.call_api { @api.delete_forwarder(forwarder_id) }
         nil
       end
 
@@ -136,22 +129,21 @@ module Smplkit
           raise ArgumentError, "Forwarder.id is required on create (caller-supplied key)"
         end
 
-        resp = Smplkit::Audit.call_api { @api.create_forwarder(build_create_body(forwarder)) }
-        Smplkit::Audit::Forwarder.from_resource(resp.data, client: self)
+        resp = Audit.call_api { @api.create_forwarder(build_create_body(forwarder)) }
+        Forwarder.from_resource(resp.data, client: self)
       end
 
-      # @api private — Full-replace PUT for an existing forwarder. Called
-      #   by {Smplkit::Audit::Forwarder#save} on instances with +created_at+.
+      # @api private — Full-replace PUT for an existing forwarder. Called by
+      #   {Smplkit::Audit::Forwarder#save} on instances with +created_at+.
       #
-      # Header values must be re-supplied as plaintext; the GET path
-      # redacts them, so a PUT body containing +"<redacted>"+ would
-      # persist that literal. Track real header values client-side and
-      # round-trip them.
+      # Header values must be re-supplied as plaintext; the GET path redacts
+      # them, so a PUT body containing +"<redacted>"+ would persist that literal.
+      # Track real header values client-side and round-trip them.
       def _update_forwarder(forwarder)
         raise ArgumentError, "cannot update a Forwarder with no id" if forwarder.id.nil?
 
-        resp = Smplkit::Audit.call_api { @api.update_forwarder(forwarder.id, build_body(forwarder)) }
-        Smplkit::Audit::Forwarder.from_resource(resp.data, client: self)
+        resp = Audit.call_api { @api.update_forwarder(forwarder.id, build_body(forwarder)) }
+        Forwarder.from_resource(resp.data, client: self)
       end
 
       private
@@ -160,16 +152,15 @@ module Smplkit
       #
       # Accepts either {Smplkit::Audit::ForwarderEnvironment} values or plain
       # hashes (+{ enabled: true, configuration: HttpConfiguration.new(...) }+)
-      # so callers can use the lightweight hash form without importing the
-      # model.
+      # so callers can use the lightweight hash form without importing the model.
       def normalize_environments(environments)
         return {} if environments.nil? || environments.empty?
 
         environments.each_with_object({}) do |(env_key, value), out|
-          out[env_key.to_s] = if value.is_a?(Smplkit::Audit::ForwarderEnvironment)
+          out[env_key.to_s] = if value.is_a?(ForwarderEnvironment)
                                 value
                               else
-                                Smplkit::Audit::ForwarderEnvironment.new(
+                                ForwarderEnvironment.new(
                                   enabled: value[:enabled] || value["enabled"] || false,
                                   configuration: value[:configuration] || value["configuration"]
                                 )
@@ -186,7 +177,7 @@ module Smplkit
         (environments || {}).each_with_object({}) do |(env_key, env), out|
           out[env_key.to_s] = SmplkitGeneratedClient::Audit::ForwarderEnvironment.new(
             enabled: env.enabled,
-            configuration: env.configuration.nil? ? nil : Smplkit::Audit::HttpConfiguration.to_wire(env.configuration)
+            configuration: env.configuration.nil? ? nil : HttpConfiguration.to_wire(env.configuration)
           )
         end
       end
@@ -197,20 +188,20 @@ module Smplkit
         SmplkitGeneratedClient::Audit::Forwarder.new(
           name: forwarder.name,
           description: forwarder.description,
-          forwarder_type: Smplkit::Audit::ForwarderType.coerce(forwarder.forwarder_type),
+          forwarder_type: ForwarderType.coerce(forwarder.forwarder_type),
           forward_smplkit_events: forwarder.forward_smplkit_events,
           environments: environments_to_wire(forwarder.environments),
           filter: forwarder.filter,
-          transform_type: Smplkit::Audit::TransformType.coerce(forwarder.transform_type),
+          transform_type: TransformType.coerce(forwarder.transform_type),
           transform: forwarder.transform,
-          configuration: Smplkit::Audit::HttpConfiguration.to_wire(forwarder.configuration)
+          configuration: HttpConfiguration.to_wire(forwarder.configuration)
         )
       end
 
       def build_create_body(forwarder)
-        # Create uses the distinct ForwarderCreateRequest envelope; the
-        # audit service requires data.id (the customer-supplied key) on
-        # create and 409s on conflict.
+        # Create uses the distinct ForwarderCreateRequest envelope; the audit
+        # service requires data.id (the customer-supplied key) on create and
+        # 409s on conflict.
         resource = SmplkitGeneratedClient::Audit::ForwarderCreateResource.new(
           id: forwarder.id.to_s,
           type: "forwarder",
@@ -230,13 +221,19 @@ module Smplkit
       end
     end
 
-    # A single page returned from {ForwardersNamespace#list}.
+    # A single page returned from {ForwardersClient#list}.
     #
     # @!attribute [rw] forwarders
     #   @return [Array<Smplkit::Audit::Forwarder>] Forwarders in this page.
     # @!attribute [rw] pagination
     #   @return [Hash] +meta.pagination+ block (+:page+, +:size+, and — only when
     #     the caller passed +meta_total: true+ — +:total+ / +:total_pages+).
-    ForwarderListPage = Struct.new(:forwarders, :pagination)
+    ForwarderListPage = Struct.new(:forwarders, :pagination) do
+      include Enumerable
+
+      def each(&) = forwarders.each(&)
+      def length = forwarders.length
+      alias_method :size, :length
+    end
   end
 end

data/lib/smplkit/audit/models.rb

@@ -422,7 +422,7 @@ module Smplkit
     # A SIEM streaming forwarder configured on the customer's account.
     #
     # Active-record style: instantiate via
-    # +mgmt.audit.forwarders.new_forwarder(...)+, mutate fields directly,
+    # +client.audit.forwarders.new(...)+, mutate fields directly,
     # and call {#save} to persist or {#delete} to remove. Header values in
     # +configuration.headers+ are returned redacted on reads — the GET path
     # on the audit API replaces every header value with +"<redacted>"+.
@@ -558,6 +558,45 @@ module Smplkit
       end
       alias delete! delete
 
+      # Set this forwarder's destination configuration in memory.
+      #
+      # With +environment+ omitted, replaces the base {#configuration}. With
+      # +environment+ given, sets the per-environment override's configuration
+      # on {#environments}, creating the override entry if it doesn't exist yet
+      # (preserving any already-set +enabled+ on it). Call {#save} to persist.
+      def set_configuration(configuration, environment: nil)
+        if environment.nil?
+          @configuration = configuration
+        else
+          _environment_override(environment).configuration = configuration
+        end
+      end
+
+      # Set this forwarder's enablement in memory.
+      #
+      # With +environment+ omitted, sets the base {#enabled} (which the server
+      # pins false regardless — enablement is per-environment). With
+      # +environment+ given, sets the per-environment override's +enabled+ on
+      # {#environments}, creating the override entry if it doesn't exist yet
+      # (preserving any already-set +configuration+ on it). Call {#save} to
+      # persist.
+      def set_enabled(enabled, environment: nil)
+        if environment.nil?
+          @enabled = enabled
+        else
+          _environment_override(environment).enabled = enabled
+        end
+      end
+
+      # Return the override for +environment+, creating an empty one if absent.
+      #
+      # The per-environment mutators reach through here so an existing
+      # override's other field is preserved when only one of +enabled+ /
+      # +configuration+ is being set.
+      def _environment_override(environment)
+        @environments[environment] ||= ForwarderEnvironment.new
+      end
+
       # @api private
       def _apply(other)
         @id = other.id

data/lib/smplkit/buffers.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require "set"
+
+# Registration buffers backing the SDK's batched-discovery sub-clients.
+#
+# Four buffer types, each owned by the sub-client that drains it:
+#
+# - +ContextRegistrationBuffer+  ->  +client.platform.contexts._buffer+
+# - +FlagRegistrationBuffer+     ->  +client.flags._buffer+
+# - +ConfigRegistrationBuffer+   ->  +client.config._buffer+
+# - +LoggerRegistrationBuffer+   ->  +client.logging.loggers._buffer+
+#
+# There is exactly one buffer + one bulk-flush implementation per resource.
+module Smplkit
+  # When the deduplication LRU exceeds this size, the oldest entry is
+  # evicted. The next observation of an evicted entry will re-flush.
+  CONTEXT_REGISTRATION_LRU_SIZE = 10_000
+
+  # Pending-queue size that triggers an immediate background flush from
+  # inside +register+.  The periodic timer on +Client+ covers the tail
+  # case for low-traffic services.
+  CONTEXT_BATCH_FLUSH_SIZE = 100
+  FLAG_BATCH_FLUSH_SIZE = 50
+  LOGGER_BATCH_FLUSH_SIZE = 50
+  CONFIG_BATCH_FLUSH_SIZE = 50
+
+  # Thread-safe batch buffer for context registration.
+  class ContextRegistrationBuffer
+    def initialize
+      @seen = {}
+      @pending = []
+      @lock = Mutex.new
+    end
+
+    # Queue any unseen contexts.
+    def observe(contexts)
+      @lock.synchronize do
+        contexts.each do |ctx|
+          cache_key = [ctx.type, ctx.key]
+          next if @seen.key?(cache_key)
+
+          @seen.shift if @seen.size >= CONTEXT_REGISTRATION_LRU_SIZE
+          @seen[cache_key] = ctx.attributes
+          @pending << { "type" => ctx.type, "key" => ctx.key, "attributes" => ctx.attributes.dup }
+        end
+      end
+    end
+
+    # Return and clear the current pending batch.
+    def drain
+      @lock.synchronize do
+        batch = @pending
+        @pending = []
+        batch
+      end
+    end
+
+    def pending_count
+      @lock.synchronize { @pending.length }
+    end
+  end
+
+  # Thread-safe batch buffer for flag declarations.
+  #
+  # Use +peek+ + +commit(ids)+ for the send path so a failed POST leaves
+  # declarations queued for the next attempt; the legacy +drain+ is
+  # unconditional and used only by tests.
+  class FlagRegistrationBuffer
+    def initialize
+      @seen = {}
+      @pending = []
+      @lock = Mutex.new
+    end
+
+    def add(declaration)
+      @lock.synchronize do
+        next if @seen.key?(declaration.id)
+
+        @seen[declaration.id] = true
+        item = { "id" => declaration.id, "type" => declaration.type, "default" => declaration.default }
+        item["service"] = declaration.service if declaration.service
+        item["environment"] = declaration.environment if declaration.environment
+        @pending << item
+      end
+    end
+
+    def peek
+      @lock.synchronize { @pending.dup }
+    end
+
+    def commit(ids)
+      return if ids.nil? || ids.empty?
+
+      committed = ids.to_set
+      @lock.synchronize { @pending.reject! { |item| committed.include?(item["id"]) } }
+    end
+
+    def drain
+      @lock.synchronize do
+        batch = @pending
+        @pending = []
+        batch
+      end
+    end
+
+    def pending_count
+      @lock.synchronize { @pending.length }
+    end
+  end
+
+  # Thread-safe batch buffer for config declarations.
+  #
+  # Configs differ from flags/loggers because each entry carries a nested
+  # +items+ dict that grows incrementally as the customer's code touches more
+  # typed getters on a declared handle. The buffer therefore stores per-config
+  # metadata permanently (so post-flush deltas can be re-attributed to the
+  # right service/environment) and dedups items per +(config_id, item_key)+ so
+  # we never re-send an item that the server has already accepted.
+  #
+  # Call sites:
+  #
+  # - +declare+ once per +client.config.bind(id, ...)+.
+  # - +add_item+ for every introspected leaf field, or anything else the
+  #   runtime client observes. Repeated calls with the same
+  #   +(config_id, item_key)+ after a successful flush are no-ops.
+  # - +drain+ returns the pending payload list, clears the pending buffer, and
+  #   records what was sent.
+  #
+  # The buffer never drops metadata — only +pending+ is cleared on flush. If
+  # the customer's code declares new items via typed getters after a flush, a
+  # fresh pending entry is created using the stored metadata so the server can
+  # route the delta to the right source row.
+  class ConfigRegistrationBuffer
+    def initialize
+      @pending = {}    # config_id -> { id:, items: {}, ...meta }
+      @meta = {}       # config_id -> { service:, environment:, parent:, name:, description: }
+      @sent_items = {} # "#{config_id}::#{item_key}" -> true
+      @lock = Mutex.new
+    end
+
+    # Register a configuration. Idempotent within a process.
+    def declare(config_id, service:, environment:, parent: nil, name: nil, description: nil)
+      @lock.synchronize do
+        next if @meta.key?(config_id)
+
+        @meta[config_id] = {
+          service: service, environment: environment,
+          parent: parent, name: name, description: description
+        }
+        @pending[config_id] = build_entry(config_id)
+      end
+    end
+
+    # Queue an item declaration if not already sent.
+    #
+    # Must be preceded by +declare+ for the same +config_id+; otherwise the
+    # call is dropped (no implicit declaration).
+    def add_item(config_id, item_key, item_type, default, description = nil)
+      @lock.synchronize do
+        next unless @meta.key?(config_id)
+        next if @sent_items.key?("#{config_id}::#{item_key}")
+
+        entry = (@pending[config_id] ||= build_entry(config_id))
+        next if entry["items"].key?(item_key)
+
+        item = { "value" => default, "type" => item_type }
+        item["description"] = description unless description.nil?
+        entry["items"][item_key] = item
+      end
+    end
+
+    # Return and clear the pending batch; record sent items.
+    def drain
+      @lock.synchronize do
+        entries = @pending.values
+        entries.each do |entry|
+          entry["items"].each_key { |item_key| @sent_items["#{entry["id"]}::#{item_key}"] = true }
+        end
+        @pending = {}
+        entries
+      end
+    end
+
+    def pending_count
+      @lock.synchronize { @pending.size }
+    end
+
+    private
+
+    def build_entry(config_id)
+      meta = @meta[config_id]
+      entry = { "id" => config_id, "items" => {} }
+      %i[service environment parent name description].each do |k|
+        v = meta[k]
+        entry[k.to_s] = v unless v.nil?
+      end
+      entry
+    end
+  end
+
+  # Thread-safe batch buffer for logger discovery.
+  class LoggerRegistrationBuffer
+    def initialize
+      @seen = {}
+      @pending = []
+      @lock = Mutex.new
+    end
+
+    def add(source)
+      @lock.synchronize do
+        next if @seen.key?(source.name)
+
+        @seen[source.name] = source.resolved_level
+        item = { "id" => source.name, "resolved_level" => source.resolved_level&.to_s }
+        item["level"] = source.level&.to_s if source.level
+        item["service"] = source.service if source.service
+        item["environment"] = source.environment if source.environment
+        @pending << item
+      end
+    end
+
+    def drain
+      @lock.synchronize do
+        batch = @pending
+        @pending = []
+        batch
+      end
+    end
+
+    def pending_count
+      @lock.synchronize { @pending.length }
+    end
+  end
+end