smplkit 3.0.95 → 3.0.97

data/lib/smplkit/buffers.rb

@@ -0,0 +1,250 @@
+# 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.
+  #
+  # @api private
+  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.
+  #
+  # @api private
+  CONTEXT_BATCH_FLUSH_SIZE = 100
+  # @api private
+  FLAG_BATCH_FLUSH_SIZE = 50
+  # @api private
+  LOGGER_BATCH_FLUSH_SIZE = 50
+  # @api private
+  CONFIG_BATCH_FLUSH_SIZE = 50
+
+  # Thread-safe batch buffer for context registration.
+  #
+  # @api private
+  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.
+  #
+  # @api private
+  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.
+  #
+  # @api private
+  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.
+  #
+  # @api private
+  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

data/lib/smplkit/client.rb

@@ -2,8 +2,6 @@
 
 require "concurrent"
 
-require "smplkit/audit/client"
-
 module Smplkit
   # Synchronous entry point for the smplkit SDK.
   #
@@ -20,19 +18,28 @@ module Smplkit
   #     # ...
   #   end
   #
-  # All parameters are optional. When omitted, the SDK resolves them from
-  # environment variables (+SMPLKIT_*+) or the +~/.smplkit+ configuration file.
-  # See ADR-021 for the full resolution algorithm.
+  # All parameters are optional. When omitted, the SDK resolves each one in
+  # precedence order, lowest to highest: built-in defaults, then the
+  # +~/.smplkit+ configuration file, then +SMPLKIT_*+ environment variables,
+  # then the explicit constructor arguments (a value supplied at a higher
+  # level overrides the lower ones).
   #
   # +Smplkit::Client+ is thread-safe by construction. Background work runs on
   # internal SDK-owned threads; public methods block the calling thread and
   # return values directly.
   class Client
+    # Periodic flush of all sub-client registration buffers (contexts, flags,
+    # loggers).  Threshold flushes still fire immediately when buffers fill up;
+    # this timer is the liveness guarantee for the tail.
     PERIODIC_FLUSH_INTERVAL = 60.0
 
-    attr_reader :manage, :config, :flags, :logging, :audit
+    attr_reader :platform, :account, :config, :flags, :logging, :audit, :jobs
 
-    # Construct, yield to the block, and close on exit.
+    # Construct a client, yield it to the block, and close it on exit.
+    #
+    # @param kwargs [Hash] The same keyword arguments as {#initialize}.
+    # @yieldparam client [Client] The constructed client.
+    # @return [Object] The block's return value.
     def self.open(**kwargs)
       client = new(**kwargs)
       begin
@@ -42,7 +49,17 @@ module Smplkit
       end
     end
 
-    def initialize(api_key: nil, environment: nil, service: nil, profile: nil, # rubocop:disable Metrics/AbcSize
+    # @param api_key [String, nil] API key for authenticating with the smplkit platform.
+    # @param environment [String, nil] The environment to connect to (e.g. +"production"+).
+    # @param service [String, nil] Service name (e.g. +"user-service"+).
+    # @param profile [String, nil] Named profile section to read from +~/.smplkit+.
+    # @param base_domain [String, nil] Base domain for API requests (default +"smplkit.com"+).
+    # @param scheme [String, nil] URL scheme (default +"https"+).
+    # @param debug [Boolean, nil] Enable debug logging in the SDK.
+    # @param telemetry [Boolean, nil] Enable anonymous usage telemetry (default +true+).
+    # @param extra_headers [Hash{String => String}, nil] Extra HTTP headers attached to
+    #   every request the client sends.
+    def initialize(api_key: nil, environment: nil, service: nil, profile: nil,
                    base_domain: nil, scheme: nil, debug: nil, telemetry: nil,
                    extra_headers: nil)
       cfg = ConfigResolution.resolve_config(
@@ -56,6 +73,7 @@ module Smplkit
       @service = cfg.service
       @base_domain = cfg.base_domain
       @scheme = cfg.scheme
+      @extra_headers = extra_headers
 
       masked_key = cfg.api_key.length > 10 ? "#{cfg.api_key[0, 10]}..." : cfg.api_key
       Smplkit.debug(
@@ -65,54 +83,92 @@ module Smplkit
         "debug=#{cfg.debug} telemetry=#{cfg.telemetry}"
       )
 
-      mgmt_cfg = ConfigResolution::ResolvedManagementConfig.new(
-        api_key: cfg.api_key, base_domain: cfg.base_domain, scheme: cfg.scheme, debug: cfg.debug
-      )
-      @extra_headers = extra_headers
-      @manage = ManagementClient.from_resolved(mgmt_cfg, extra_headers: extra_headers)
+      # Build the per-service HTTP transports + the context-registration buffer.
+      # Side-effect-free: each transport connects lazily on first call.
+      # client.platform owns the buffer; client.config/flags/logging/jobs borrow
+      # their transports from here.
+      @transports = Transport.build_service_transports(Transport.to_transport_config(cfg, extra_headers))
 
-      app_url = ConfigResolution.service_url(cfg.scheme, "app", cfg.base_domain)
-      flags_url = ConfigResolution.service_url(cfg.scheme, "flags", cfg.base_domain)
-      logging_url = ConfigResolution.service_url(cfg.scheme, "logging", cfg.base_domain)
+      app_url = @transports.app_url
       audit_url = ConfigResolution.service_url(cfg.scheme, "audit", cfg.base_domain)
+
+      # Alias the shared HTTP transports — single connection pool per service.
+      @http_client = @transports.config_http
+      @app_http = @transports.app_http
       @app_base_url = app_url
 
+      # Metrics reporter
       @metrics = if cfg.telemetry
-                   MetricsReporter.new(http_client: @manage._app_http,
-                                       environment: cfg.environment,
-                                       service: cfg.service)
+                   MetricsReporter.new(http_client: @app_http, environment: cfg.environment, service: cfg.service)
                  end
 
       @ws_manager = nil
-      @config = Config::ConfigClient.new(self, manage: @manage, metrics: @metrics)
-      @flags = Flags::FlagsClient.new(self, manage: @manage, metrics: @metrics,
-                                            flags_base_url: flags_url, app_base_url: app_url)
-      @logging = Logging::LoggingClient.new(self, manage: @manage, metrics: @metrics,
-                                                  logging_base_url: logging_url, app_base_url: app_url)
-      @audit = Audit::AuditClient.new(api_key: cfg.api_key, base_url: audit_url,
-                                      environment: cfg.environment, extra_headers: extra_headers)
+      # Platform's cross-cutting CRUD on one client; wired into this parent so
+      # it borrows the shared app transport, and owns the context-registration
+      # buffer. Built BEFORE flags so the contexts seam below is available.
+      @platform = Platform::PlatformClient.new(app_transport: @app_http)
+      # Account-level settings on one client; built from the app url + api key
+      # (the settings sub-client uses Faraday directly).
+      @account = Account::AccountClient.new(api_key: cfg.api_key, base_url: app_url, extra_headers: extra_headers)
+      # Config's full surface on one client; wired into this parent so it
+      # borrows the shared config transport and WebSocket.
+      @config = Config::ConfigClient.new(parent: self, transport: @transports.config_http, metrics: @metrics)
+      # Flags' full surface on one client; wired into this parent so it borrows
+      # the shared flags transport and WebSocket. ``contexts`` is the injection
+      # seam for evaluation-context registration, wired to
+      # ``client.platform.contexts``.
+      @flags = Flags::FlagsClient.new(
+        parent: self, transport: @transports.flags_http, contexts: @platform.contexts, metrics: @metrics
+      )
+      # Logging's full surface on one client; wired into this parent so it
+      # borrows the shared logging transport and WebSocket. The two management
+      # sub-clients live at client.logging.loggers / client.logging.log_groups.
+      @logging = Logging::LoggingClient.new(parent: self, transport: @transports.logging_http, metrics: @metrics)
+      # Audit's full surface on one client; this runtime instance carries the
+      # configured environment as ``X-Smplkit-Environment`` and owns its own
+      # transport (closed in ``close``).
+      @audit = Audit::AuditClient.new(
+        api_key: cfg.api_key, base_url: audit_url, environment: cfg.environment, extra_headers: extra_headers
+      )
+      # Jobs has no runtime/management split — reuse the shared jobs transport
+      # (single connection pool) so ``client.jobs`` is one-stop.
+      @jobs = Jobs::JobsClient.new(auth_client: @transports.jobs_http)
 
+      # Construction is side-effect-free: no background threads, no phone-home.
+      # The periodic registration-buffer flush and the service-context
+      # registration are deferred until the first config/flags/logging operation
+      # or set_context via ``_ensure_started`` — so an audit-only or jobs-only
+      # customer pays zero threads and zero network at construction.
       @closed = false
-      schedule_periodic_flush
-
-      @init_thread = Thread.new(@manage, @environment, @service, @app_base_url) do |mgmt, env, svc, app_url|
-        register_service_context(mgmt, env, svc, app_url)
-      end
+      @started = false
+      @start_lock = Mutex.new
+      @flush_timer = nil
+      @init_thread = nil
     end
 
-    # Eagerly initialize the SDK and block until it is fully ready.
+    # Optionally pre-warm the SDK and block until the live socket is up.
+    #
+    # Eagerly connects config and flags — flushing discovery, pre-fetching all
+    # flags and configs into the local cache, opening the live-updates WebSocket
+    # — and waits for the handshake to complete. After this returns, +flag.get+
+    # / +client.config.subscribe+ hit cache (no first-request connect tax) and
+    # any +on_change+ listeners receive every server event from this point
+    # forward.
     #
-    # Pre-fetches all flags and configs into the local cache, opens the
-    # live-updates WebSocket, and waits for the handshake to complete.
-    # After this returns, +flag.get+ / +client.config.get+ hit cache (no
-    # first-request connect tax) and any +on_change+ listeners receive every
-    # server event from this point forward.
+    # Optional: config and flags connect lazily on first live use, so this is
+    # purely a pre-warm / WebSocket-ready barrier. Logging integration is *not*
+    # connected here — call +client.logging.install+ separately if you want it
+    # (it installs adapters and hooks into your application's logger, which
+    # should be opt-in).
     #
-    # Logging integration is *not* installed here — call
-    # +client.logging.install+ separately if you want it.
+    # @param timeout [Float] Maximum seconds to wait for the live-updates
+    #   WebSocket handshake before giving up. Defaults to +10.0+.
+    # @return [void]
+    # @raise [Smplkit::TimeoutError] If the WebSocket fails to connect within
+    #   +timeout+ seconds.
     def wait_until_ready(timeout: 10.0)
-      @flags.start
-      @config.start
+      @flags._ensure_connected
+      @config._ensure_connected
       ws = _ensure_ws
       deadline = monotonic_now + timeout
       while ws.connection_status != "connected"
@@ -127,21 +183,34 @@ module Smplkit
 
     # Stash +contexts+ as the current request's evaluation context.
     #
+    # Typical use is from middleware — set the context once at request entry and
+    # every +flag.get+ (and other context-sensitive evaluations) inside that
+    # request automatically picks it up.
+    #
+    # Each unique +(type, key)+ is also registered with the platform
+    # (deduplicated via an LRU; sent in the background).
+    #
     # Two usage shapes:
     #
     #   # Fire-and-forget (typical middleware)
     #   client.set_context([Smplkit::Context.new("user", "u-123")])
     #
-    #   # Scoped block (impersonation or one-off override)
+    #   # Scoped block (e.g. impersonation or one-off override)
     #   client.set_context([Smplkit::Context.new("user", "impersonated")]) do
     #     # ...
     #   end
     #   # original context restored here
     #
-    # Each unique +(type, key)+ is also queued for bulk registration on the
-    # management API.
+    # @param contexts [Array<Smplkit::Context>] The contexts to make active for
+    #   the current thread (e.g. the request's user and account). An empty array
+    #   clears any registration step but still returns a scope.
+    # @yield When a block is given, the contexts are active only for its
+    #   duration and the previous context is restored on exit.
+    # @return [Object, Smplkit::ContextScope] The block's return value when a
+    #   block is given; otherwise a scope you can ignore for fire-and-forget use.
     def set_context(contexts, &block)
-      @manage.contexts.register(contexts) if contexts && !contexts.empty?
+      _ensure_started
+      @platform.contexts.register(contexts) if contexts && !contexts.empty?
 
       scope = Smplkit.set_request_context(contexts || [])
       if block
@@ -151,19 +220,25 @@ module Smplkit
       end
     end
 
+    # Release all resources held by this client.
+    #
+    # @return [void]
     def close
       Smplkit.debug("lifecycle", "Client.close called")
       @closed = true
       @flush_timer&.shutdown
+      @flush_timer = nil
       final_flush
       @metrics&.close
       @logging._close
       @flags._close
-      @config._close
       @audit._close
       @ws_manager&.stop
       @ws_manager = nil
-      @manage.close
+      # Close the shared per-service HTTP transports (app/config/flags/logging/
+      # jobs). client.platform/account borrow the app transport and close
+      # nothing; client.audit owns and closed its own transport above.
+      @transports.close
     end
 
     # Internal accessors used by sub-clients --------------------------------
@@ -175,15 +250,29 @@ module Smplkit
     def _metrics = @metrics
     def _extra_headers = @extra_headers
 
-    def _ensure_ws
-      @_ensure_ws ||= begin
-        ws = SharedWebSocket.new(app_base_url: @app_base_url, api_key: @api_key, metrics: @metrics)
-        ws.start
-        ws
+    # Start the deferred background machinery exactly once.
+    #
+    # Idempotent and thread-safe (lock + flag); a no-op after +close+. Triggered
+    # by the first config/flags/logging operation, +set_context+,
+    # +wait_until_ready+, or WebSocket open — never at construction.
+    def _ensure_started
+      @start_lock.synchronize do
+        return if @started || @closed
+
+        @started = true
       end
+      schedule_periodic_flush
+      @init_thread = Thread.new { register_service_context }
     end
 
-    def _flags_transport = @manage.flags
+    def _ensure_ws
+      _ensure_started
+      if @ws_manager.nil?
+        @ws_manager = SharedWebSocket.new(app_base_url: @app_base_url, api_key: @api_key, metrics: @metrics)
+        @ws_manager.start
+      end
+      @ws_manager
+    end
 
     private
 
@@ -198,38 +287,40 @@ module Smplkit
       @flush_timer.execute
     end
 
-    # Extracted as a private method so the timer body is reachable from
-    # tests without poking into Concurrent::TimerTask internals.
+    # Extracted as a private method so the timer body is reachable from tests
+    # without poking into Concurrent::TimerTask internals.
     def run_periodic_flush
       return if @closed
 
-      @manage.contexts.flush
-      @manage.flags.flush
-      @manage.loggers.flush
+      @platform.contexts.flush
+      @flags.flush
+      @logging.loggers.flush
+      @config.flush
     rescue StandardError => e
       Smplkit.debug("registration", "periodic flush failed: #{e.class}: #{e.message}")
     end
 
     def final_flush
-      [@manage.contexts, @manage.flags, @manage.loggers].each do |ns|
-        ns.flush
+      [@platform.contexts, @flags, @logging.loggers, @config].each do |target|
+        target.flush
       rescue StandardError => e
         Smplkit.debug("registration", "final flush failed: #{e.class}: #{e.message}")
       end
     end
 
-    def register_service_context(mgmt, env, svc, app_url)
-      # Bulk-register the environment + service as +Smplkit::Context+
-      # instances on the platform so they show up in the Console alongside
-      # any user-provided contexts. The buffer dedupes on +(type, key)+, so
-      # this is safe to call on every client construction.
+    def register_service_context
+      # Register the environment and/or service as context instances. Only the
+      # values that are set are registered; if neither environment nor service
+      # was provided the POST is skipped entirely (an audit/jobs-only customer
+      # has nothing to register).
       contexts = []
-      contexts << Smplkit::Context.new("environment", env) if env
-      contexts << Smplkit::Context.new("service", svc, name: svc) if svc
-      mgmt.contexts.register(contexts)
-      mgmt.contexts.flush
+      contexts << Smplkit::Context.new("environment", @environment) if @environment
+      contexts << Smplkit::Context.new("service", @service, { "name" => @service }) if @service
+      return if contexts.empty?
+
+      @platform.contexts.register(contexts, flush: true)
     rescue StandardError => e
-      Smplkit.debug("lifecycle", "register service context failed (app: #{app_url}): #{e.class}: #{e.message}")
+      Smplkit.debug("lifecycle", "register service context failed (app: #{@app_base_url}): #{e.class}: #{e.message}")
     end
   end
 end