smplkit 3.0.15 → 3.0.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d846979c77a96bd5b8f3fbd3bf36ddbe0a6556b7925a33302142b173c7c3e96
-  data.tar.gz: dd7e3c2b10238f038f2d9e5de715bb5b12e7a05eae85af9acf53d5ac7735b370
+  metadata.gz: 215caf14863d35bebf83849e104befe12423a9ef468a547cb44714e6a9ea1932
+  data.tar.gz: 928ab9e89ea2dca1548eb82a06aa8d9b525f874026437bb6b862b4cdc254a4c9
 SHA512:
-  metadata.gz: 52eaa355e2937332ed2637f9cec86b2959b477ad577caeb36bda66c6ca966ca8d1782c9c8a0f6c5a5e3ce11e20f3ad08a54239f0069109b691797a09fe970810
-  data.tar.gz: 3931a2e34214aa78575f1dc7652631335608246fec988e5a5fca12488b330d59297d585c7e2b3cf3b60e9afe0ba38853107e66e6342ec58c1ad3d6906a0704f1
+  metadata.gz: 1f77af115d5412a34711fb54af8de0c402e47f33e53512fb808794a103a046d514494d947a6ed9d7d42998d9aca3f196db433914de52f96b785e3b35e5c63972
+  data.tar.gz: d028dd314e06e87fc6185f80695ba0c4bdf21b5d77d548c62e32bc2c4138590f7566c327cc83946191c26e233be9b0d923d1ba0d3d6fb59f835f91ca9f6f3bfa

data/lib/smplkit/logging/client.rb

@@ -9,6 +9,11 @@ module Smplkit
     # Obtained via +Smplkit::Client#logging+. Manages the discovery and level
     # application for a customer's logging frameworks via pluggable adapters.
     # CRUD has moved to +mgmt.loggers.*+ / +mgmt.log_groups.*+.
+    #
+    # Level resolution is client-side: the server stores raw configuration
+    # and the SDK walks the chain (env override → base → group chain →
+    # dot-notation ancestry) to compute each managed logger's effective
+    # level. See {Smplkit::Logging::Resolution}.
     class LoggingClient
       def initialize(parent, manage:, metrics:, logging_base_url:, app_base_url:)
         @parent = parent
@@ -21,6 +26,23 @@ module Smplkit
         @global_listeners = []
         @key_listeners = Hash.new { |h, k| h[k] = [] }
         @lock = Mutex.new
+        # original_name → normalized_id for every adapter-discovered logger.
+        # We keep originals so adapter.apply_level receives whatever the
+        # framework's registry indexes by.
+        @name_map = {}
+        # normalized_id → resolution-cache entry. Populated by
+        # +_fetch_and_apply+ and mutated by the +logger_changed+ /
+        # +logger_deleted+ WS handlers.
+        @loggers_cache = {}
+        # group id → resolution-cache entry. Without this, any managed
+        # logger with +level=null+ that inherits from a group silently
+        # keeps whatever level its adapter had at startup.
+        @groups_cache = {}
+        # normalized_id → resolved level (string). Used to decide whether
+        # to fire change listeners on a re-resolution — a group-driven
+        # change isn't visible in the raw +loggers_cache+ but moves the
+        # resolved value.
+        @resolved_levels = {}
       end
 
       # Install the logging integration.
@@ -39,8 +61,15 @@ module Smplkit
           adapter.install_hook { |name, _explicit, effective| observe_logger(adapter, name, effective) }
         end
 
+        flush_initial_registration
+        fetch_and_apply(trigger: "install")
+
         @ws_manager = @parent._ensure_ws
         @ws_manager.on("logger_changed") { |data| handle_logger_changed(data) }
+        @ws_manager.on("logger_deleted") { |data| handle_logger_deleted(data) }
+        @ws_manager.on("group_changed") { |data| handle_group_changed(data) }
+        @ws_manager.on("group_deleted") { |data| handle_group_deleted(data) }
+        @ws_manager.on("loggers_changed") { |data| handle_loggers_changed(data) }
         @installed = true
         self
       end
@@ -71,6 +100,12 @@ module Smplkit
         @manage.loggers.delete(name)
       end
 
+      # Re-fetch all loggers and groups and re-apply resolved levels. Fires
+      # change listeners for any logger whose resolved level moved.
+      def refresh
+        fetch_and_apply(trigger: "refresh")
+      end
+
       def on_change(name = nil, &block)
         raise ArgumentError, "on_change requires a block" unless block
 
@@ -102,15 +137,17 @@ module Smplkit
 
         return unless @adapters.empty?
 
-        # :nocov: defensive log — unreachable in practice because stdlib
-        # +Logger+ is always present, so +StdlibLoggerAdapter+ is always
+        # Defensive log — unreachable in practice because stdlib +Logger+
+        # is always present, so +StdlibLoggerAdapter+ is always
         # constructible.
+        # :nocov:
         Smplkit.debug("registration", "no logging adapters loaded; runtime features disabled")
         # :nocov:
       end
 
       def observe_logger(_adapter, raw_name, level)
         normalized = Normalize.normalize_logger_name(raw_name)
+        @name_map[raw_name] = normalized
         @manage.loggers.register(LoggerSource.new(
                                    name: normalized,
                                    resolved_level: level,
@@ -120,16 +157,135 @@ module Smplkit
                                  ))
       end
 
+      def flush_initial_registration
+        @manage.loggers.flush
+      rescue StandardError => e
+        Smplkit.debug("registration", "initial logger flush failed: #{e.class}: #{e.message}")
+      end
+
+      # Full re-fetch of loggers + groups, then apply resolved levels.
+      # Fires change listeners for any logger whose resolved level moved.
+      def fetch_and_apply(trigger:)
+        Smplkit.debug("resolution", "full resolution pass starting (trigger: #{trigger})")
+        loggers = @manage.loggers.list_logger_entries
+        groups = @manage.log_groups.list_group_entries
+        @loggers_cache = loggers
+        @groups_cache = groups
+        apply_levels(source: "websocket")
+      rescue StandardError => e
+        Smplkit.debug("resolution", "fetch_and_apply failed (trigger: #{trigger}): #{e.class}: #{e.message}")
+      end
+
+      # Resolve the effective level for every locally-known managed logger
+      # and push it to every adapter. Returns the list of normalized ids
+      # whose resolved level changed.
+      #
+      # +source+ is the +LoggerChangeEvent#source+ for any change-listener
+      # event we fire. The default reflects callers that arrived through a
+      # server event (WebSocket).
+      def apply_levels(source: "websocket")
+        changed = []
+        @name_map.each do |raw_name, normalized_id|
+          entry = @loggers_cache[normalized_id]
+          next if entry.nil?
+          next unless entry["managed"]
+
+          resolved_string = Resolution.resolve_level(
+            normalized_id, @parent._environment, @loggers_cache, @groups_cache
+          )
+          coerced = LogLevel.coerce(resolved_string)
+          push_to_adapters(raw_name, coerced)
+          previous = @resolved_levels[normalized_id]
+          if previous != resolved_string
+            @resolved_levels[normalized_id] = resolved_string
+            changed << [normalized_id, coerced]
+          end
+        end
+        fire_resolved_change_events(changed, source: source)
+        changed
+      end
+
+      def push_to_adapters(raw_name, coerced_level)
+        @adapters.each do |a|
+          a.apply_level(raw_name, coerced_level)
+        rescue StandardError => e
+          Smplkit.debug("logging", "adapter apply_level raised: #{e.class}: #{e.message}")
+        end
+      end
+
+      def fire_resolved_change_events(changed, source:)
+        changed.each do |(normalized_id, coerced_level)|
+          event = LoggerChangeEvent.new(name: normalized_id, level: coerced_level, source: source)
+          (@global_listeners + @key_listeners[normalized_id]).each do |cb|
+            cb.call(event)
+          rescue StandardError => e
+            Smplkit.debug("logging", "listener raised: #{e.class}: #{e.message}")
+          end
+        end
+      end
+
       def handle_logger_changed(data)
-        name = Normalize.normalize_logger_name(data["name"] || data["id"] || "")
-        return if name.empty?
+        key = data["id"] || data["name"] || ""
+        normalized = Normalize.normalize_logger_name(key)
+        return if normalized.empty?
 
-        level = data["resolved_level"] || data["level"]
-        coerced = level && LogLevel.coerce(level)
-        @adapters.each { |a| a.apply_level(name, coerced) } if coerced
+        begin
+          entry_id, entry = @manage.loggers.get_logger_entry(normalized)
+          @loggers_cache[entry_id || normalized] = entry
+        rescue StandardError => e
+          Smplkit.debug("websocket", "logger_changed fetch failed for #{normalized.inspect}: #{e.class}: #{e.message}")
+          return
+        end
+
+        apply_levels(source: "websocket")
+      end
+
+      def handle_logger_deleted(data)
+        key = data["id"] || data["name"] || ""
+        normalized = Normalize.normalize_logger_name(key)
+        return if normalized.empty?
+
+        existed = @loggers_cache.delete(normalized)
+        @resolved_levels.delete(normalized)
+        return unless existed
+
+        apply_levels(source: "websocket")
+        fire_deletion_event(normalized)
+      end
+
+      def handle_group_changed(data)
+        key = data["id"] || data["key"] || ""
+        return if key.to_s.empty?
+
+        begin
+          entry_id, entry = @manage.log_groups.get_group_entry(key)
+          @groups_cache[entry_id || key] = entry
+        rescue StandardError => e
+          Smplkit.debug("websocket", "group_changed fetch failed for #{key.inspect}: #{e.class}: #{e.message}")
+          return
+        end
+
+        apply_levels(source: "websocket")
+      end
 
-        event = LoggerChangeEvent.new(name: name, level: coerced, source: "websocket")
-        (@global_listeners + @key_listeners[name]).each do |cb|
+      def handle_group_deleted(data)
+        key = data["id"] || data["key"] || ""
+        return if key.to_s.empty?
+
+        existed = @groups_cache.delete(key)
+        return unless existed
+
+        apply_levels(source: "websocket")
+        fire_deletion_event(key)
+      end
+
+      def handle_loggers_changed(_data)
+        fetch_and_apply(trigger: "loggers_changed WS event")
+      end
+
+      def fire_deletion_event(key)
+        event = LoggerChangeEvent.new(name: key, level: nil, source: "websocket", deleted: true)
+        (@global_listeners + @key_listeners[key]).each do |cb|
           cb.call(event)
         rescue StandardError => e
           Smplkit.debug("logging", "listener raised: #{e.class}: #{e.message}")
@@ -137,9 +293,15 @@ module Smplkit
       end
     end
 
-    LoggerChangeEvent = Struct.new(:name, :level, :source, keyword_init: true) do
+    LoggerChangeEvent = Struct.new(:name, :level, :source, :deleted, keyword_init: true) do
+      def initialize(name:, level:, source:, deleted: false)
+        super
+      end
+
       def ==(other)
-        other.is_a?(LoggerChangeEvent) && name == other.name && level == other.level && source == other.source
+        other.is_a?(LoggerChangeEvent) &&
+          name == other.name && level == other.level &&
+          source == other.source && deleted == other.deleted
       end
     end
   end

data/lib/smplkit/logging/resolution.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Smplkit
+  module Logging
+    # Client-side level resolution per ADR-034 §3.1.
+    #
+    # The server stores raw configuration and returns it as-is; the SDK is
+    # responsible for walking the inheritance chain. Mirrors the Python
+    # SDK's +smplkit.logging._resolution+ verbatim — both implementations
+    # MUST resolve identically for any given (loggers, groups, env) input.
+    module Resolution
+      FALLBACK_LEVEL = "INFO"
+
+      module_function
+
+      # Resolve the effective level for +logger_id+ in +environment+.
+      #
+      # Resolution chain (first non-nil wins):
+      #
+      #   1. Logger's own +environments[env].level+
+      #   2. Logger's own +level+
+      #   3. Group chain (recursive: group env level → group level → parent group …)
+      #   4. Dot-notation ancestry (+com.acme.payments+ → +com.acme+ → +com+,
+      #      applying steps 1–3 at each)
+      #   5. System fallback: +"INFO"+
+      #
+      # +loggers+ and +groups+ are id-keyed Hashes whose values are Hashes
+      # with the same shape as the Python SDK: +"level"+, +"group"+ (parent
+      # group id for loggers; parent_id for groups), +"environments"+
+      # (Hash keyed by env name with +{"level" => "..."}+ values).
+      def resolve_level(logger_id, environment, loggers, groups)
+        result = resolve_for_entry(logger_id, environment, loggers, groups)
+        if result
+          if Smplkit::Debug.enabled
+            source = find_resolution_source(logger_id, environment, loggers, groups)
+            Smplkit.debug("resolution", "#{logger_id} -> #{result} (source: #{source})")
+          end
+          return result
+        end
+
+        parts = logger_id.split(".")
+        (parts.length - 1).downto(1) do |i|
+          ancestor_id = parts[0, i].join(".")
+          result = resolve_for_entry(ancestor_id, environment, loggers, groups)
+          if result
+            Smplkit.debug("resolution", "#{logger_id} -> #{result} (source: ancestor \"#{ancestor_id}\")")
+            return result
+          end
+        end
+
+        Smplkit.debug("resolution", "#{logger_id} -> #{FALLBACK_LEVEL} (source: system default)")
+        FALLBACK_LEVEL
+      end
+
+      # Try to resolve a level for a single entry (logger or ancestor).
+      # Returns +nil+ if no level is found at any step of 1–3.
+      def resolve_for_entry(logger_id, environment, loggers, groups)
+        entry = loggers[logger_id]
+        return nil if entry.nil?
+
+        env_level = env_level_of(entry, environment)
+        return env_level if env_level
+
+        base = entry["level"]
+        return base if base
+
+        resolve_group_chain(entry["group"], environment, groups)
+      end
+
+      # Walk the group chain looking for a level. Cycle-safe via +visited+.
+      def resolve_group_chain(group_id, environment, groups)
+        visited = Set.new
+        current_id = group_id
+        while !current_id.nil? && !visited.include?(current_id)
+          visited.add(current_id)
+          group = groups[current_id]
+          break if group.nil?
+
+          env_level = env_level_of(group, environment)
+          return env_level if env_level
+
+          base = group["level"]
+          return base if base
+
+          current_id = group["group"]
+        end
+        nil
+      end
+
+      # Human-readable label for which resolution step won. Only consulted
+      # when debug logging is enabled; mirrors Python's +_find_resolution_source+.
+      def find_resolution_source(logger_id, environment, loggers, groups)
+        entry = loggers[logger_id]
+        return "not found" if entry.nil?
+
+        return %(env override "#{environment}") if env_level_of(entry, environment)
+        return "base level" if entry["level"]
+
+        group_id = entry["group"]
+        return %(group "#{group_id}") if resolve_group_chain(group_id, environment, groups)
+
+        "unknown"
+      end
+
+      def env_level_of(entry, environment)
+        envs = entry["environments"]
+        return nil unless envs.is_a?(Hash)
+
+        env_data = envs[environment]
+        return nil unless env_data.is_a?(Hash)
+
+        env_data["level"]
+      end
+    end
+  end
+end

data/lib/smplkit/management/client.rb

@@ -816,8 +816,38 @@ module Smplkit
         Smplkit::Logging::Helpers.logger_resource_to_model(self, ResourceShim.from_model(response.data))
       end
 
+      # Runtime entry — walks every page and returns an id-keyed Hash of
+      # resolution-cache entries (+level+, +group+, +managed+,
+      # +environments+). Mirrors the Python SDK's
+      # +LoggingClient._fetch_and_apply+ loggers branch.
+      def list_logger_entries
+        rows = PaginatedFetch.collect { |opts| @api.list_loggers(opts) }
+        rows.to_h { |r| logger_entry_from_resource(ResourceShim.from_model(r)) }
+      end
+
+      # Fetch one logger as a resolution-cache entry. Used by the
+      # +logger_changed+ WS handler.
+      def get_logger_entry(id)
+        normalized = Smplkit::Logging::Normalize.normalize_logger_name(id)
+        response = ErrorMapping.call { @api.get_logger(normalized) }
+        logger_entry_from_resource(ResourceShim.from_model(response.data))
+      end
+
       private
 
+      def logger_entry_from_resource(resource)
+        attrs = resource["attributes"] || {}
+        [
+          resource["id"],
+          {
+            "level" => attrs["level"],
+            "group" => attrs["group"],
+            "managed" => attrs.key?("managed") ? attrs["managed"] : true,
+            "environments" => attrs["environments"] || {}
+          }
+        ]
+      end
+
       def logger_body(logger)
         # Logger server schema: name, level, group, managed.
         # +resolved_level+ is read-only, +service+/+environment+ are
@@ -880,8 +910,35 @@ module Smplkit
         Smplkit::Logging::Helpers.log_group_resource_to_model(self, ResourceShim.from_model(response.data))
       end
 
+      # Runtime entry — walks every page and returns an id-keyed Hash of
+      # resolution-cache entries (+level+, +group+, +environments+). The
+      # +group+ key carries the *parent group id* so the resolution
+      # algorithm can walk the chain with the same key shape it uses for
+      # loggers.
+      def list_group_entries
+        rows = PaginatedFetch.collect { |opts| @api.list_log_groups(opts) }
+        rows.to_h { |r| group_entry_from_resource(ResourceShim.from_model(r)) }
+      end
+
+      def get_group_entry(key)
+        response = ErrorMapping.call { @api.get_log_group(key) }
+        group_entry_from_resource(ResourceShim.from_model(response.data))
+      end
+
       private
 
+      def group_entry_from_resource(resource)
+        attrs = resource["attributes"] || {}
+        [
+          resource["id"],
+          {
+            "level" => attrs["level"],
+            "group" => attrs["parent_id"],
+            "environments" => attrs["environments"] || {}
+          }
+        ]
+      end
+
       def log_group_body(group)
         # LogGroup server schema: name, level, parent_id (no description).
         SmplkitGeneratedClient::Logging::LogGroupResponse.new(

data/lib/smplkit.rb

@@ -55,6 +55,7 @@ require_relative "smplkit/logging/normalize"
 require_relative "smplkit/logging/sources"
 require_relative "smplkit/logging/models"
 require_relative "smplkit/logging/helpers"
+require_relative "smplkit/logging/resolution"
 require_relative "smplkit/logging/adapters/base"
 require_relative "smplkit/logging/adapters/stdlib_logger_adapter"
 require_relative "smplkit/logging/client"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smplkit
 version: !ruby/object:Gem::Version
-  version: 3.0.15
+  version: 3.0.16
 platform: ruby
 authors:
 - Smpl Solutions LLC
@@ -701,6 +701,7 @@ files:
 - lib/smplkit/logging/levels.rb
 - lib/smplkit/logging/models.rb
 - lib/smplkit/logging/normalize.rb
+- lib/smplkit/logging/resolution.rb
 - lib/smplkit/logging/sources.rb
 - lib/smplkit/management/audit.rb
 - lib/smplkit/management/buffer.rb