smplkit 3.0.95 → 3.0.97

data/lib/smplkit/logging/helpers.rb

@@ -2,6 +2,9 @@
 
 module Smplkit
   module Logging
+    # Resource-to-model conversion helpers for the logging wrapper.
+    #
+    # @api private
     module Helpers
       module_function
 
@@ -18,6 +21,7 @@ module Smplkit
           log_group_id: attrs["log_group_id"],
           managed: attrs.fetch("managed", true),
           description: attrs["description"],
+          environments: attrs["environments"],
           created_at: attrs["created_at"],
           updated_at: attrs["updated_at"]
         )
@@ -32,7 +36,7 @@ module Smplkit
           name: attrs["name"],
           level: attrs["level"] && LogLevel.coerce(attrs["level"]),
           description: attrs["description"],
-          parent_id: attrs["parent_id"],
+          group: attrs["parent_id"],
           environments: attrs["environments"] || {},
           created_at: attrs["created_at"],
           updated_at: attrs["updated_at"]

data/lib/smplkit/logging/levels.rb

@@ -6,7 +6,7 @@ require_relative "../log_level"
 module Smplkit
   module Logging
     # Bidirectional mapping between Ruby stdlib +Logger+ levels and smplkit
-    # canonical levels (per ADR-046 §2.3).
+    # canonical levels.
     #
     # Stdlib +Logger+ has DEBUG/INFO/WARN/ERROR/FATAL/UNKNOWN — no TRACE. The
     # +stdlib-logger+ adapter maps smplkit TRACE to stdlib DEBUG when
@@ -14,6 +14,8 @@ module Smplkit
     # discovering — there is no way to distinguish smplkit-TRACE-mapped-to-
     # DEBUG from genuine DEBUG, which is consistent with how the Python
     # +stdlib-logging+ adapter handles the same gap.
+    #
+    # @api private
     module Levels
       STDLIB_TO_SMPL = {
         ::Logger::DEBUG => LogLevel::DEBUG,

data/lib/smplkit/logging/models.rb

@@ -2,6 +2,60 @@
 
 module Smplkit
   module Logging
+    # Per-environment configuration on a logger or log group.
+    #
+    # Lives at +logger.environments[env_name]+ (a +Hash{String => LoggerEnvironment}+).
+    # Frozen — mutate the override via +logger.set_level(level, environment: "...")+
+    # or remove it via +logger.clear_level(environment: "...")+.
+    #
+    # Attributes:
+    #   - level: Per-environment level override (+nil+ means no override).
+    LoggerEnvironment = Struct.new(:level, keyword_init: true) do
+      def initialize(level: nil)
+        super
+        freeze
+      end
+    end
+
+    # Coerce a dict input into +Hash{String => LoggerEnvironment}+.
+    #
+    # Accepts both pre-built +LoggerEnvironment+ instances and the wire-shaped
+    # +{env_id => {"level" => "ERROR"}}+ dicts.
+    #
+    # @api private
+    def self.convert_environments(value)
+      return {} if value.nil? || value.empty?
+
+      value.each_with_object({}) do |(env_id, env_data), out|
+        out[env_id] = build_logger_environment(env_data)
+      end
+    end
+
+    # @api private
+    def self.build_logger_environment(env_data)
+      return env_data if env_data.is_a?(LoggerEnvironment)
+      return LoggerEnvironment.new unless env_data.is_a?(Hash)
+
+      level_str = env_data["level"] || env_data[:level]
+      return LoggerEnvironment.new if level_str.nil?
+
+      begin
+        LoggerEnvironment.new(level: LogLevel.coerce(level_str))
+      rescue ArgumentError
+        LoggerEnvironment.new
+      end
+    end
+
+    # Convert a typed environments dict to the wire-shaped dict for sending.
+    # Entries with +level=nil+ are skipped (no override to send).
+    #
+    # @api private
+    def self.environments_to_wire(environments)
+      environments.each_with_object({}) do |(env_id, env), out|
+        out[env_id] = { "level" => env.level.to_s } unless env.level.nil?
+      end
+    end
+
     # A logger resource managed by the smplkit Logging service.
     #
     # Attributes:
@@ -12,13 +66,15 @@ module Smplkit
     #   - service, environment: provenance
     #   - log_group_id: parent log group, if any
     #   - managed: whether the SDK should apply server-driven level changes
+    #   - environments: per-environment level overrides, keyed by environment
     class SmplLogger
       attr_accessor :id, :name, :resolved_level, :level, :service, :environment,
                     :log_group_id, :managed, :created_at, :updated_at, :description
 
       def initialize(client = nil, name:, resolved_level:, id: nil, level: nil,
                      service: nil, environment: nil, log_group_id: nil,
-                     managed: true, description: nil, created_at: nil, updated_at: nil)
+                     managed: true, description: nil, environments: nil,
+                     created_at: nil, updated_at: nil)
         @client = client
         @id = id
         @name = name
@@ -29,12 +85,58 @@ module Smplkit
         @log_group_id = log_group_id
         @managed = managed
         @description = description
+        @environments = Logging.convert_environments(environments)
         @created_at = created_at
         @updated_at = updated_at
       end
 
+      # Whether the SDK applies server-driven level changes to this logger.
+      #
+      # @return [Boolean] +true+ when smplkit controls this logger's level.
       def managed? = !!@managed
 
+      # Read-only view of per-environment level overrides. Mutate via
+      # +set_level+ / +clear_level+ (with +environment: "..."+).
+      def environments
+        @environments.dup
+      end
+
+      # Set the log level.
+      #
+      # With +environment: nil+ (the default), sets the base log level used when
+      # no environment-specific override applies. With +environment: "..."+,
+      # sets the per-environment override. Changes are local until +save+.
+      def set_level(level, environment: nil)
+        if environment.nil?
+          @level = level
+        else
+          @environments[environment] = LoggerEnvironment.new(level: level)
+        end
+      end
+
+      # Remove a log level.
+      #
+      # With +environment: nil+ (the default), removes the base log level (the
+      # logger then inherits from its group / ancestor / system default). With
+      # +environment: "..."+, removes the per-environment override only. Changes
+      # are local until +save+.
+      def clear_level(environment: nil)
+        if environment.nil?
+          @level = nil
+        else
+          @environments.delete(environment)
+        end
+      end
+
+      # Remove all per-environment level overrides.
+      def clear_all_environment_levels
+        @environments = {}
+      end
+
+      # Persist this logger to the server (create or update).
+      #
+      # @return [self] this logger, refreshed from the server response.
+      # @raise [RuntimeError] If the logger was constructed without a client.
       def save
         raise "SmplLogger was constructed without a client; cannot save" if @client.nil?
 
@@ -44,6 +146,11 @@ module Smplkit
       end
       alias save! save
 
+      # Delete this logger from the server.
+      #
+      # @return [void]
+      # @raise [RuntimeError] If the logger was constructed without a client.
+      # @raise [Smplkit::NotFoundError] If the logger no longer exists.
       def delete
         raise "SmplLogger was constructed without a client; cannot delete" if @client.nil?
 
@@ -51,6 +158,7 @@ module Smplkit
       end
       alias delete! delete
 
+      # @api private
       def _apply(other)
         @id = other.id
         @name = other.name
@@ -61,6 +169,7 @@ module Smplkit
         @log_group_id = other.log_group_id
         @managed = other.managed
         @description = other.description
+        @environments = other.environments
         @created_at = other.created_at
         @updated_at = other.updated_at
       end
@@ -69,11 +178,11 @@ module Smplkit
     # A log group resource — a hierarchical bag of loggers with a shared
     # configured level.
     class SmplLogGroup
-      attr_accessor :id, :key, :name, :level, :description, :parent_id, :environments,
+      attr_accessor :id, :key, :name, :level, :description, :group,
                     :created_at, :updated_at
 
       def initialize(client = nil, key:, id: nil, name: nil, level: nil,
-                     description: nil, parent_id: nil, environments: nil,
+                     description: nil, group: nil, environments: nil,
                      created_at: nil, updated_at: nil)
         @client = client
         @id = id
@@ -81,12 +190,54 @@ module Smplkit
         @name = name
         @level = level
         @description = description
-        @parent_id = parent_id
-        @environments = environments || {}
+        @group = group
+        @environments = Logging.convert_environments(environments)
         @created_at = created_at
         @updated_at = updated_at
       end
 
+      # Read-only view of per-environment level overrides. Mutate via
+      # +set_level+ / +clear_level+ (with +environment: "..."+).
+      def environments
+        @environments.dup
+      end
+
+      # Set the log level.
+      #
+      # With +environment: nil+ (the default), sets the base log level used when
+      # no environment-specific override applies. With +environment: "..."+,
+      # sets the per-environment override. Changes are local until +save+.
+      def set_level(level, environment: nil)
+        if environment.nil?
+          @level = level
+        else
+          @environments[environment] = LoggerEnvironment.new(level: level)
+        end
+      end
+
+      # Remove a log level.
+      #
+      # With +environment: nil+ (the default), removes the base log level (the
+      # group then inherits from its parent group / ancestor / system default).
+      # With +environment: "..."+, removes the per-environment override only.
+      # Changes are local until +save+.
+      def clear_level(environment: nil)
+        if environment.nil?
+          @level = nil
+        else
+          @environments.delete(environment)
+        end
+      end
+
+      # Remove all per-environment level overrides.
+      def clear_all_environment_levels
+        @environments = {}
+      end
+
+      # Persist this group to the server (create or update).
+      #
+      # @return [self] this group, refreshed from the server response.
+      # @raise [RuntimeError] If the group was constructed without a client.
       def save
         raise "SmplLogGroup was constructed without a client; cannot save" if @client.nil?
 
@@ -101,6 +252,11 @@ module Smplkit
       end
       alias save! save
 
+      # Delete this group from the server.
+      #
+      # @return [void]
+      # @raise [RuntimeError] If the group was constructed without a client.
+      # @raise [Smplkit::NotFoundError] If the group no longer exists.
       def delete
         raise "SmplLogGroup was constructed without a client; cannot delete" if @client.nil?
 
@@ -108,13 +264,14 @@ module Smplkit
       end
       alias delete! delete
 
+      # @api private
       def _apply(other)
         @id = other.id
         @key = other.key
         @name = other.name
         @level = other.level
         @description = other.description
-        @parent_id = other.parent_id
+        @group = other.group
         @environments = other.environments
         @created_at = other.created_at
         @updated_at = other.updated_at

data/lib/smplkit/logging/normalize.rb

@@ -2,9 +2,11 @@
 
 module Smplkit
   module Logging
-    # Logger name normalization per ADR-034 §5.
+    # Logger name normalization.
     #
     # Replace +/+ with +.+, replace +:+ with +.+, lowercase everything.
+    #
+    # @api private
     module Normalize
       module_function
 

data/lib/smplkit/logging/resolution.rb

@@ -4,12 +4,12 @@ require "set"
 
 module Smplkit
   module Logging
-    # Client-side level resolution per ADR-034 §3.1.
+    # Client-side level resolution.
     #
     # 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.
+    # responsible for walking the inheritance chain.
+    #
+    # @api private
     module Resolution
       FALLBACK_LEVEL = "INFO"
 

data/lib/smplkit/logging/sources.rb

@@ -2,7 +2,7 @@
 
 module Smplkit
   module Logging
-    # Describes a logger to register via +Smplkit::ManagementClient#loggers#register+.
+    # Describes a logger to register via +client.logging.loggers.register+.
     #
     # Used both for buffered runtime discovery (called by +Smplkit::Client+ as
     # adapters discover loggers) and for explicit registration from setup