smplkit 3.0.46 → 3.0.47

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05451aff4b25b69dbb8559407e759b5d621eb3d3718673aa0a2ae2eea6872828
-  data.tar.gz: 70efc7544a753f44714b9b8c9bb20eb13748b7e8cb1788dda869ff5f160afc0e
+  metadata.gz: 45143f97a9697f58ffc237a49e1c56c530d969a08f758acb969ed0d6ecd4c8fa
+  data.tar.gz: 2d678b90f48d3db9db2b8179af51e47357f96dc7d03d14eb4931e5f74543a7ca
 SHA512:
-  metadata.gz: 2a8a7c7a9b89f69ab9fe46285590c3b4a6483916e8283f2e2849d645b2186e48fa425004970ea61cacaa81e72f5ef7ae95136f14d47fc87ca5da3aec50911981
-  data.tar.gz: 367b840a5c525940bcffbaaace1e271735fe6040e0479f0f4eaccca49db2f404d0d747f9db054d0fd45f15e5e8c2ca3da98835a31e899b2412a2febec3cc6dff
+  metadata.gz: 8be90684fe43d7ac3f61111c64ed98ad686e38028fdccdc28048418c7eda0e26378447417b28d5f6b3e5c4ab1af6c323b98a969244511361a41b4f8834b86a20
+  data.tar.gz: 4b8e13b2b1a7646910c19cce3542695bdd1fcfd76e5598c27b25b77c166b89f31239af2c2234ce1b57b2f3b6f78a3a4cf7ccf91a5c0845614d8b5a9fb29f7d30

data/lib/smplkit/config/client.rb

@@ -25,21 +25,24 @@ module Smplkit
 
     # A live, dot-accessible view over a resolved configuration.
     #
-    # Backed by the most-recent resolved Hash for a config key. +#get+ /
-    # +#[]+ return the resolved value at the time of access; +#refresh+
-    # rebuilds the snapshot from the underlying client.
+    # Identity-stable per config key (the same instance is returned by
+    # repeat +client.config.get+ / +get_or_create+ calls). Every read goes
+    # through the underlying client's resolved-config cache, so WebSocket
+    # updates are picked up automatically — there is no +subscribe+ step.
     class LiveConfigProxy
       def initialize(client, key)
         @client = client
         @key = key
-        @snapshot = client._resolve_now(key)
       end
 
+      def config_id = @key
+
       def get(item_key, default = nil)
-        return @snapshot if item_key.nil?
+        snapshot = current_values
+        return snapshot if item_key.nil?
 
         keys = item_key.to_s.split(".")
-        keys.reduce(@snapshot) do |scope, k|
+        keys.reduce(snapshot) do |scope, k|
           break default if scope.nil?
 
           scope.is_a?(Hash) ? scope[k] : default
@@ -51,13 +54,82 @@ module Smplkit
       end
 
       def to_h
-        @snapshot.dup
+        current_values.dup
       end
 
       def refresh
-        @snapshot = @client._resolve_now(@key)
+        # The cache is fully invalidated for this key — the next read
+        # re-resolves from the parent client.
+        @client._invalidate(@key)
         self
       end
+
+      # ------------------------------------------------------------------
+      # Typed getters (ADR-037 §2.13)
+      #
+      # Each registers the item (key, type, default, description) on first
+      # call within the process, then returns the resolved value. When the
+      # resolved value can't be coerced to the getter's type — including
+      # the "not yet set on the server" case — the in-code default is
+      # returned and a debug message is logged.
+      # ------------------------------------------------------------------
+
+      def get_bool(item_key, default, description: nil)
+        register_item(item_key, "BOOLEAN", default, description)
+        value = current_values[item_key.to_s]
+        return default unless value.is_a?(TrueClass) || value.is_a?(FalseClass)
+
+        value
+      end
+
+      def get_int(item_key, default, description: nil)
+        register_item(item_key, "NUMBER", default, description)
+        value = current_values[item_key.to_s]
+        return default if value.is_a?(TrueClass) || value.is_a?(FalseClass)
+        return value if value.is_a?(Integer)
+        return value.to_i if value.is_a?(Float) && value == value.floor
+
+        default
+      end
+
+      def get_float(item_key, default, description: nil)
+        register_item(item_key, "NUMBER", default, description)
+        value = current_values[item_key.to_s]
+        return default if value.is_a?(TrueClass) || value.is_a?(FalseClass)
+        return value.to_f if value.is_a?(Numeric)
+
+        default
+      end
+
+      def get_string(item_key, default, description: nil)
+        register_item(item_key, "STRING", default, description)
+        value = current_values[item_key.to_s]
+        value.is_a?(String) ? value : default
+      end
+
+      def get_json(item_key, default, description: nil)
+        register_item(item_key, "JSON", default, description)
+        snap = current_values
+        snap.key?(item_key.to_s) ? snap[item_key.to_s] : default
+      end
+
+      def on_change(item_key = nil, &)
+        if item_key.nil?
+          @client.on_change(@key, &)
+        else
+          @client.on_change_item(@key, item_key.to_s, &)
+        end
+      end
+
+      private
+
+      def current_values
+        @client._resolve_now(@key)
+      end
+
+      def register_item(item_key, item_type, default, description)
+        @client._observe_item_declaration(@key, item_key.to_s, item_type, default, description)
+      end
     end
 
     # Synchronous config runtime namespace.
@@ -75,8 +147,10 @@ module Smplkit
 
         @snapshots = {}
         @raw_chains = {}
+        @proxies = {}
         @global_listeners = []
         @key_listeners = Hash.new { |h, k| h[k] = [] }
+        @item_listeners = Hash.new { |h, k| h[k] = Hash.new { |hh, kk| hh[kk] = [] } }
         @connected = false
         @lock = Mutex.new
       end
@@ -85,6 +159,13 @@ module Smplkit
         return if @connected
 
         @environment = @parent._environment
+
+        # Per ADR-037 §2.14: flush any buffered discovery declarations
+        # BEFORE the lazy init touches the runtime so newly-declared
+        # configs are visible to the very first +get+. The flush itself
+        # swallows server/network failures.
+        @manage&.config&.flush
+
         @ws_manager = @parent._ensure_ws
         @ws_manager.on("config_changed") { |data| handle_config_changed(data) }
         @ws_manager.on("config_deleted") { |data| handle_config_deleted(data) }
@@ -95,11 +176,35 @@ module Smplkit
         start unless @connected
 
         snapshot = resolve(config_key)
+        raise Smplkit::NotFoundError, "Config #{config_key.inspect} not found" if snapshot.nil?
         return snapshot if model_class.nil?
 
         model_class.new(snapshot)
       end
 
+      # Declare a configuration from code; return a live, dict-like view.
+      #
+      # Idempotent — repeat calls with the same +id+ return the same
+      # +LiveConfigProxy+ instance. The first call queues a discovery
+      # payload (the config and any items declared via typed getters on
+      # the returned handle) for upload to +POST /api/v1/configs/bulk+ on
+      # next flush. Unlike +#get+, this method does not raise +NotFoundError+
+      # when the id is absent — discovery handles that case.
+      def get_or_create(config_id, parent: nil, name: nil, description: nil)
+        parent_id =
+          case parent
+          when nil then nil
+          when String then parent
+          when LiveConfigProxy then parent.config_id
+          else
+            raise ArgumentError,
+                  "parent must be a String id or LiveConfigProxy; got #{parent.class.name}"
+          end
+        _observe_config_declaration(config_id, parent: parent_id, name: name, description: description)
+        start unless @connected
+        cached_proxy(config_id)
+      end
+
       def get_string(item_key, default: nil, config: nil)
         typed_get(item_key, default, config) { |v| v.is_a?(String) ? v : v.to_s }
       end
@@ -123,7 +228,7 @@ module Smplkit
       def live(config_key)
         start unless @connected
 
-        LiveConfigProxy.new(self, config_key)
+        cached_proxy(config_key)
       end
 
       def on_change(config_key = nil, &block)
@@ -137,6 +242,13 @@ module Smplkit
         block
       end
 
+      def on_change_item(config_key, item_key, &block)
+        raise ArgumentError, "on_change_item requires a block" unless block
+
+        @item_listeners[config_key][item_key.to_s] << block
+        block
+      end
+
       def refresh
         @lock.synchronize do
           @snapshots.clear
@@ -146,15 +258,46 @@ module Smplkit
       end
 
       def _resolve_now(config_key)
-        resolve(config_key)
+        resolve(config_key) || {}
       end
 
       def _close
         # No durable resources; symmetry stub.
       end
 
+      # Discard cached state for +config_key+; the next resolve will refetch.
+      def _invalidate(config_key)
+        @lock.synchronize do
+          @snapshots.delete(config_key)
+          @raw_chains.delete(config_key)
+        end
+      end
+
+      # Internal: queue a config declaration with the management buffer.
+      def _observe_config_declaration(config_id, parent:, name:, description:)
+        @manage.config.register_config(
+          config_id,
+          service: @service,
+          environment: @environment,
+          parent: parent,
+          name: name,
+          description: description
+        )
+      end
+
+      # Internal: queue a config item declaration with the management buffer.
+      def _observe_item_declaration(config_id, item_key, item_type, default, description)
+        @manage.config.register_config_item(config_id, item_key, item_type, default, description)
+      end
+
       private
 
+      def cached_proxy(config_key)
+        @lock.synchronize do
+          @proxies[config_key] ||= LiveConfigProxy.new(self, config_key)
+        end
+      end
+
       def typed_get(item_key, default, config_key)
         snapshot = config_key ? resolve(config_key) : merged_snapshot
         key = item_key.to_s
@@ -190,6 +333,12 @@ module Smplkit
         end
 
         chain = fetch_chain(config_key)
+        # An empty chain means the config does not exist on the server.
+        # Callers that hit +get(key)+ must raise +NotFoundError+; callers
+        # that hold a +LiveConfigProxy+ get an empty Hash from
+        # +_resolve_now+ so typed getters fall back to defaults.
+        return nil if chain.nil? || chain.empty?
+
         snapshot = Helpers.resolve_chain(chain, @environment)
         @lock.synchronize do
           @raw_chains[config_key] = chain
@@ -238,6 +387,19 @@ module Smplkit
         rescue StandardError => e
           Smplkit.debug("config", "listener raised: #{e.class}: #{e.message}")
         end
+        # Item-scoped listeners — fire for every registered item on the
+        # changed config. We don't diff old vs new values here because
+        # the Ruby cache is invalidated wholesale per config; item-scoped
+        # listeners on this SDK fire on the "any change to this config"
+        # signal, mirroring the +LiveConfigProxy.on_change(item_key)+
+        # contract.
+        @item_listeners[config_key].each_value do |listeners|
+          listeners.each do |cb|
+            cb.call(event)
+          rescue StandardError => e
+            Smplkit.debug("config", "item listener raised: #{e.class}: #{e.message}")
+          end
+        end
       end
 
       def fire_change_listeners_all(source)

data/lib/smplkit/management/buffer.rb

@@ -6,6 +6,7 @@ module Smplkit
     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
@@ -89,6 +90,77 @@ module Smplkit
       end
     end
 
+    # Thread-safe batch buffer for config declarations. Mirrors Python's
+    # +_ConfigRegistrationBuffer+: per-config metadata is retained across
+    # flushes so post-drain deltas re-attribute correctly, and items are
+    # dedup'd per +(config_id, item_key)+ so an already-sent item is
+    # never re-sent.
+    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
+
+      # Idempotent — first writer's metadata wins.
+      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 for an already-declared config. Items
+      # already sent in a previous +drain+ are skipped.
+      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
+
+      # Returns and clears the pending batch; records 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

data/lib/smplkit/management/client.rb

@@ -453,6 +453,59 @@ module Smplkit
     class ConfigNamespace
       def initialize(api_client)
         @api = SmplkitGeneratedClient::Config::ConfigsApi.new(api_client)
+        @buffer = Management::ConfigRegistrationBuffer.new
+      end
+
+      # ---------------------------------------------------------------
+      # Discovery API (ADR-037 §2.13/§2.14)
+      # ---------------------------------------------------------------
+
+      # Queue a configuration declaration for bulk-discovery upload.
+      # Called by +ConfigClient#get_or_create+. Threshold-flushes on a
+      # background thread once the pending buffer reaches the flush size.
+      def register_config(config_id, service:, environment:, parent: nil,
+                          name: nil, description: nil)
+        @buffer.declare(config_id, service: service, environment: environment,
+                                   parent: parent, name: name, description: description)
+        trigger_background_flush_if_needed
+      end
+
+      # Queue a config item declaration. +register_config+ must have run
+      # first; items added without a prior declaration are dropped.
+      def register_config_item(config_id, item_key, item_type, default, description = nil)
+        @buffer.add_item(config_id, item_key, item_type, default, description)
+        trigger_background_flush_if_needed
+      end
+
+      def pending_count
+        @buffer.pending_count
+      end
+
+      # Send any pending config declarations to
+      # +POST /api/v1/configs/bulk+. Per ADR-024 §2.9 the bulk endpoint is
+      # plan-limit-exempt; failures here never propagate to customer code.
+      def flush
+        batch = @buffer.drain
+        return if batch.empty?
+
+        items = batch.map do |entry|
+          SmplkitGeneratedClient::Config::ConfigBulkItem.new(
+            id: entry["id"],
+            service: entry["service"],
+            environment: entry["environment"],
+            parent: entry["parent"],
+            name: entry["name"],
+            description: entry["description"],
+            items: bulk_items_to_wire(entry["items"])
+          )
+        end
+        body = SmplkitGeneratedClient::Config::ConfigBulkRequest.new(configs: items)
+        begin
+          ErrorMapping.call { @api.bulk_register_configs(body) }
+        rescue StandardError => e
+          # Fire-and-forget per ADR-024 §2.9.
+          Smplkit.debug("registration", "config bulk register failed: #{e.class}: #{e.message}")
+        end
       end
 
       def list(page_number: nil, page_size: nil)
@@ -584,6 +637,28 @@ module Smplkit
 
         { "id" => config.id, "items" => items_hash, "environments" => environments }
       end
+
+      def bulk_items_to_wire(items_hash)
+        return nil if items_hash.nil? || items_hash.empty?
+
+        items_hash.transform_values do |def_hash|
+          SmplkitGeneratedClient::Config::ConfigItemDefinition.new(
+            value: def_hash["value"],
+            type: def_hash["type"],
+            description: def_hash["description"]
+          )
+        end
+      end
+
+      def trigger_background_flush_if_needed
+        return unless @buffer.pending_count >= Management::CONFIG_BATCH_FLUSH_SIZE
+
+        Thread.new do
+          flush
+        rescue StandardError => e
+          Smplkit.debug("registration", "threshold config flush failed: #{e.class}: #{e.message}")
+        end
+      end
     end
 
     class FlagsNamespace

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smplkit
 version: !ruby/object:Gem::Version
-  version: 3.0.46
+  version: 3.0.47
 platform: ruby
 authors:
 - Smpl Solutions LLC