smplkit 1.0.5

data/lib/smplkit/logging/adapters/semantic_logger_adapter.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# This file is loaded conditionally by the LoggingClient — only when the
+# customer's app has +require "semantic_logger"+. The +require+ at the top is
+# safe because the file itself is only loaded after a successful
+# +require "semantic_logger"+ elsewhere.
+require "semantic_logger"
+require "concurrent"
+
+module Smplkit
+  module Logging
+    module Adapters
+      # Adapter for the +semantic_logger+ gem.
+      #
+      # SemanticLogger has its own internal logger registry and its own level
+      # system that natively includes TRACE — a 1-to-1 map across all seven
+      # smplkit canonical levels.
+      class SemanticLoggerAdapter < Base
+        def initialize
+          super
+          @loggers = Concurrent::Hash.new
+          @on_new = nil
+          @uninstalled = false
+        end
+
+        def name
+          "semantic-logger"
+        end
+
+        def track(name, logger)
+          @loggers[name] = logger
+        end
+
+        def discover
+          rows = []
+          # Default named loggers SemanticLogger creates: itself + the global
+          # one. Customers add more via +SemanticLogger[ClassOrName]+.
+          all_loggers.each do |name, logger|
+            level = logger.respond_to?(:level) ? logger.level : nil
+            smpl_level = Levels.semantic_level_to_smpl(level)
+            rows << [name, smpl_level, smpl_level]
+          end
+
+          rows.uniq { |row| row[0] }
+        end
+
+        def apply_level(logger_name, level)
+          logger = @loggers[logger_name]
+          return unless logger
+          return unless logger.respond_to?(:level=)
+
+          logger.level = Levels.smpl_level_to_semantic(level)
+        end
+
+        def install_hook(&on_new_logger)
+          @on_new = on_new_logger
+          @uninstalled = false
+          # SemanticLogger's API for new-logger interception varies across
+          # versions. The Ruby SDK initial release relies on +discover+ being
+          # called periodically — full prepend-based interception will be
+          # filled in once tested against the targeted +semantic_logger+
+          # version pinned in dev deps. (See ISSUES.md.)
+        end
+
+        def uninstall_hook
+          @uninstalled = true
+        end
+
+        private
+
+        def all_loggers
+          loggers = @loggers.dup
+          if defined?(::SemanticLogger::Logger) && ::SemanticLogger::Logger.respond_to?(:processors)
+            # No-op probe to keep this method tolerant of the live API.
+          end
+
+          if defined?(::SemanticLogger) &&
+             ::SemanticLogger.respond_to?(:default_level) &&
+             ::SemanticLogger.respond_to?(:[])
+            loggers["root"] ||= ::SemanticLogger["root"]
+          end
+
+          loggers
+        end
+      end
+    end
+  end
+end

data/lib/smplkit/logging/adapters/stdlib_logger_adapter.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "logger"
+require "concurrent"
+
+module Smplkit
+  module Logging
+    module Adapters
+      # Adapter for Ruby stdlib +Logger+ (which +ActiveSupport::Logger+
+      # subclasses, so Rails is covered automatically).
+      #
+      # Ruby has no global logger registry like Python's
+      # +logging.Logger.manager.loggerDict+. Instead this adapter:
+      #
+      #   1. Always reports +"root"+ at the framework default level.
+      #   2. Reports +"rails"+ if +Rails.logger+ is defined.
+      #   3. Reports any logger explicitly registered via +track+.
+      #   4. Uses +Module#prepend+ on +::Logger+ to catch new logger
+      #      creation. The hook fires on every +Logger.new+ call.
+      class StdlibLoggerAdapter < Base
+        @hook_module = nil
+        @global_lock = Mutex.new
+
+        class << self
+          attr_reader :hook_module
+        end
+
+        def initialize
+          super
+          @loggers = Concurrent::Hash.new
+          track_root!
+          @on_new = nil
+          @uninstalled = false
+        end
+
+        def name
+          "stdlib-logger"
+        end
+
+        # Register an additional logger with the adapter so its level can be
+        # discovered and applied.
+        def track(logger_name, logger)
+          @loggers[logger_name] = logger
+        end
+
+        def discover
+          rows = []
+          @loggers.each_pair do |logger_name, logger|
+            level = logger.level
+            smpl_level = Levels.stdlib_level_to_smpl(level)
+            rows << [logger_name, smpl_level, smpl_level]
+          end
+
+          if defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
+            track("rails", ::Rails.logger) unless @loggers.key?("rails")
+            level = ::Rails.logger.level
+            smpl_level = Levels.stdlib_level_to_smpl(level)
+            rows << ["rails", smpl_level, smpl_level]
+          end
+
+          rows.uniq { |row| row[0] }
+        end
+
+        def apply_level(logger_name, level)
+          logger = @loggers[logger_name]
+          return unless logger
+
+          native = Levels.smpl_level_to_stdlib(level)
+          logger.level = native
+        end
+
+        def install_hook(&on_new_logger)
+          @on_new = on_new_logger
+          @uninstalled = false
+
+          self.class.global_lock.synchronize do
+            unless self.class.hook_installed?
+              hook = self.class.build_hook
+              ::Logger.prepend(hook)
+              self.class.instance_variable_set(:@hook_module, hook)
+            end
+            self.class.adapters << self
+          end
+        end
+
+        def uninstall_hook
+          @uninstalled = true
+          self.class.global_lock.synchronize do
+            self.class.adapters.delete(self)
+          end
+        end
+
+        # Called by the prepended hook when a new Logger is created.
+        def on_new_logger_created(logger, name)
+          return if @uninstalled
+
+          track(name, logger)
+          smpl_level = Levels.stdlib_level_to_smpl(logger.level)
+          @on_new&.call(name, smpl_level, smpl_level)
+        end
+
+        class << self
+          def adapters
+            @adapters ||= Concurrent::Array.new
+          end
+
+          def global_lock
+            @global_lock ||= Mutex.new
+          end
+
+          def hook_installed?
+            !@hook_module.nil?
+          end
+
+          def build_hook
+            Module.new do
+              def initialize(*args, **kwargs)
+                super
+                StdlibLoggerAdapter.adapters.each do |adapter|
+                  adapter.on_new_logger_created(self, "logger.#{object_id}")
+                rescue StandardError
+                  # Swallow to keep Logger.new robust under the hook.
+                end
+              end
+            end
+          end
+
+          def reset_hook!
+            @hook_module = nil
+          end
+        end
+
+        private
+
+        def track_root!
+          @loggers["root"] ||= ::Logger.new($stdout)
+        end
+      end
+    end
+  end
+
+  StdlibLoggerAdapter = Logging::Adapters::StdlibLoggerAdapter
+end

data/lib/smplkit/logging/client.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Smplkit
+  module Logging
+    # Synchronous logging runtime namespace.
+    #
+    # 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.*+.
+    class LoggingClient
+      def initialize(parent, manage:, metrics:, logging_base_url:, app_base_url:)
+        @parent = parent
+        @manage = manage
+        @metrics = metrics
+        @logging_base_url = logging_base_url
+        @app_base_url = app_base_url
+        @adapters = []
+        @installed = false
+        @global_listeners = []
+        @key_listeners = Hash.new { |h, k| h[k] = [] }
+        @lock = Mutex.new
+      end
+
+      # Install the logging integration.
+      #
+      # Auto-loads the +stdlib-logger+ adapter (always) and the
+      # +semantic-logger+ adapter (when the gem is available). Customer
+      # explicit registration via +register_adapter+ wins over auto-load.
+      def install
+        return self if @installed
+
+        auto_load_adapters if @adapters.empty?
+
+        @adapters.each do |adapter|
+          discovered = adapter.discover
+          discovered.each { |(name, _explicit, effective)| observe_logger(adapter, name, effective) }
+          adapter.install_hook { |name, _explicit, effective| observe_logger(adapter, name, effective) }
+        end
+
+        @ws_manager = @parent._ensure_ws
+        @ws_manager.on("logger_changed") { |data| handle_logger_changed(data) }
+        @installed = true
+        self
+      end
+      alias start install
+
+      def register_adapter(adapter)
+        unless adapter.is_a?(Adapters::Base)
+          raise ArgumentError, "adapter must implement Smplkit::Logging::Adapters::Base"
+        end
+
+        @adapters << adapter
+        self
+      end
+
+      def adapters
+        @adapters.dup
+      end
+
+      def get(name)
+        @manage.loggers.get(name)
+      end
+
+      def list
+        @manage.loggers.list
+      end
+
+      def delete(name)
+        @manage.loggers.delete(name)
+      end
+
+      def on_change(name = nil, &block)
+        raise ArgumentError, "on_change requires a block" unless block
+
+        if name.nil?
+          @global_listeners << block
+        else
+          @key_listeners[Normalize.normalize_logger_name(name)] << block
+        end
+        block
+      end
+
+      def _close
+        @adapters.each(&:uninstall_hook) if @installed
+        @installed = false
+      end
+
+      private
+
+      def auto_load_adapters
+        @adapters << Adapters::StdlibLoggerAdapter.new
+
+        begin
+          require "semantic_logger"
+          require_relative "adapters/semantic_logger_adapter"
+          @adapters << Adapters::SemanticLoggerAdapter.new
+        rescue LoadError
+          Smplkit.debug("registration", "semantic_logger gem not installed; semantic-logger adapter skipped")
+        end
+
+        return unless @adapters.empty?
+
+        Smplkit.debug("registration", "no logging adapters loaded; runtime features disabled")
+      end
+
+      def observe_logger(_adapter, raw_name, level)
+        normalized = Normalize.normalize_logger_name(raw_name)
+        @manage.loggers.register(LoggerSource.new(
+                                   name: normalized,
+                                   resolved_level: level,
+                                   level: nil,
+                                   service: @parent._service,
+                                   environment: @parent._environment
+                                 ))
+      end
+
+      def handle_logger_changed(data)
+        name = Normalize.normalize_logger_name(data["name"] || data["id"] || "")
+        return if name.empty?
+
+        level = data["resolved_level"] || data["level"]
+        coerced = level && LogLevel.coerce(level)
+        @adapters.each { |a| a.apply_level(name, coerced) } if coerced
+
+        event = LoggerChangeEvent.new(name: name, level: coerced, source: "websocket")
+        (@global_listeners + @key_listeners[name]).each do |cb|
+          cb.call(event)
+        rescue StandardError => e
+          Smplkit.debug("logging", "listener raised: #{e.class}: #{e.message}")
+        end
+      end
+    end
+
+    LoggerChangeEvent = Struct.new(:name, :level, :source, keyword_init: true) do
+      def ==(other)
+        other.is_a?(LoggerChangeEvent) && name == other.name && level == other.level && source == other.source
+      end
+    end
+  end
+end

data/lib/smplkit/logging/helpers.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Smplkit
+  module Logging
+    module Helpers
+      module_function
+
+      def logger_resource_to_model(client, resource)
+        attrs = resource["attributes"] || {}
+        SmplLogger.new(
+          client,
+          id: resource["id"] || attrs["id"],
+          name: attrs["name"],
+          resolved_level: attrs["resolved_level"] && LogLevel.coerce(attrs["resolved_level"]),
+          level: attrs["level"] && LogLevel.coerce(attrs["level"]),
+          service: attrs["service"],
+          environment: attrs["environment"],
+          log_group_id: attrs["log_group_id"],
+          managed: attrs.fetch("managed", true),
+          description: attrs["description"],
+          created_at: attrs["created_at"],
+          updated_at: attrs["updated_at"]
+        )
+      end
+
+      def log_group_resource_to_model(client, resource)
+        attrs = resource["attributes"] || {}
+        SmplLogGroup.new(
+          client,
+          id: resource["id"] || attrs["id"],
+          key: attrs["key"] || resource["id"],
+          name: attrs["name"],
+          level: attrs["level"] && LogLevel.coerce(attrs["level"]),
+          description: attrs["description"],
+          parent_id: attrs["parent_id"],
+          environments: attrs["environments"] || {},
+          created_at: attrs["created_at"],
+          updated_at: attrs["updated_at"]
+        )
+      end
+
+      def build_logger_body(logger)
+        attributes = {
+          "name" => logger.name,
+          "resolved_level" => logger.resolved_level&.to_s,
+          "level" => logger.level&.to_s,
+          "service" => logger.service,
+          "environment" => logger.environment,
+          "log_group_id" => logger.log_group_id,
+          "managed" => logger.managed,
+          "description" => logger.description
+        }.compact
+        { "data" => { "type" => "logger", "id" => logger.id, "attributes" => attributes } }
+      end
+
+      def build_log_group_body(group)
+        attributes = {
+          "key" => group.key,
+          "name" => group.name,
+          "level" => group.level&.to_s,
+          "description" => group.description,
+          "parent_id" => group.parent_id,
+          "environments" => group.environments
+        }.compact
+        { "data" => { "type" => "log_group", "id" => group.key, "attributes" => attributes } }
+      end
+    end
+  end
+end

data/lib/smplkit/logging/levels.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "logger"
+require_relative "../log_level"
+
+module Smplkit
+  module Logging
+    # Bidirectional mapping between Ruby stdlib +Logger+ levels and smplkit
+    # canonical levels (per ADR-046 §2.3).
+    #
+    # Stdlib +Logger+ has DEBUG/INFO/WARN/ERROR/FATAL/UNKNOWN — no TRACE. The
+    # +stdlib-logger+ adapter maps smplkit TRACE to stdlib DEBUG when
+    # applying levels, and maps stdlib DEBUG to smplkit DEBUG when
+    # 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.
+    module Levels
+      STDLIB_TO_SMPL = {
+        ::Logger::DEBUG => LogLevel::DEBUG,
+        ::Logger::INFO => LogLevel::INFO,
+        ::Logger::WARN => LogLevel::WARN,
+        ::Logger::ERROR => LogLevel::ERROR,
+        ::Logger::FATAL => LogLevel::FATAL,
+        ::Logger::UNKNOWN => LogLevel::SILENT
+      }.freeze
+
+      SMPL_TO_STDLIB = {
+        LogLevel::TRACE => ::Logger::DEBUG,
+        LogLevel::DEBUG => ::Logger::DEBUG,
+        LogLevel::INFO => ::Logger::INFO,
+        LogLevel::WARN => ::Logger::WARN,
+        LogLevel::ERROR => ::Logger::ERROR,
+        LogLevel::FATAL => ::Logger::FATAL,
+        LogLevel::SILENT => ::Logger::UNKNOWN
+      }.freeze
+
+      module_function
+
+      def stdlib_level_to_smpl(level)
+        return LogLevel::DEBUG if level.nil?
+
+        STDLIB_TO_SMPL[level] || nearest_smpl_for(level)
+      end
+
+      def smpl_level_to_stdlib(level)
+        coerced = LogLevel.coerce(level)
+        SMPL_TO_STDLIB.fetch(coerced)
+      end
+
+      # SemanticLogger's level system natively includes TRACE — a 1-to-1 map.
+      SEMANTIC_TO_SMPL = {
+        trace: LogLevel::TRACE,
+        debug: LogLevel::DEBUG,
+        info: LogLevel::INFO,
+        warn: LogLevel::WARN,
+        error: LogLevel::ERROR,
+        fatal: LogLevel::FATAL
+      }.freeze
+
+      SMPL_TO_SEMANTIC = SEMANTIC_TO_SMPL.invert.freeze
+
+      def semantic_level_to_smpl(level)
+        return LogLevel::INFO if level.nil?
+
+        SEMANTIC_TO_SMPL[level.to_sym] || LogLevel::INFO
+      end
+
+      def smpl_level_to_semantic(level)
+        coerced = LogLevel.coerce(level)
+        # SemanticLogger has no SILENT — closest equivalent is :fatal.
+        SMPL_TO_SEMANTIC[coerced] || :fatal
+      end
+
+      def nearest_smpl_for(stdlib_level)
+        sorted = STDLIB_TO_SMPL.keys.sort
+        best = sorted.first
+        sorted.each do |bp|
+          break if bp > stdlib_level
+
+          best = bp
+        end
+        STDLIB_TO_SMPL[best]
+      end
+    end
+  end
+end

data/lib/smplkit/logging/models.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Smplkit
+  module Logging
+    # A logger resource managed by the smplkit Logging service.
+    #
+    # Attributes:
+    #   - id, name: identity
+    #   - resolved_level: effective level computed by the platform from
+    #     environment overrides + log group inheritance
+    #   - level: explicit override (nil means inherit)
+    #   - service, environment: provenance
+    #   - log_group_id: parent log group, if any
+    #   - managed: whether the SDK should apply server-driven level changes
+    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)
+        @client = client
+        @id = id
+        @name = name
+        @resolved_level = resolved_level
+        @level = level
+        @service = service
+        @environment = environment
+        @log_group_id = log_group_id
+        @managed = managed
+        @description = description
+        @created_at = created_at
+        @updated_at = updated_at
+      end
+
+      def managed? = !!@managed
+
+      def save
+        raise "SmplLogger was constructed without a client; cannot save" if @client.nil?
+
+        updated = @client._update_logger(self)
+        _apply(updated)
+        self
+      end
+      alias save! save
+
+      def delete
+        raise "SmplLogger was constructed without a client; cannot delete" if @client.nil?
+
+        @client.delete(@id || @name)
+      end
+      alias delete! delete
+
+      def _apply(other)
+        @id = other.id
+        @name = other.name
+        @resolved_level = other.resolved_level
+        @level = other.level
+        @service = other.service
+        @environment = other.environment
+        @log_group_id = other.log_group_id
+        @managed = other.managed
+        @description = other.description
+        @created_at = other.created_at
+        @updated_at = other.updated_at
+      end
+    end
+
+    # 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,
+                    :created_at, :updated_at
+
+      def initialize(client = nil, key:, id: nil, name: nil, level: nil,
+                     description: nil, parent_id: nil, environments: nil,
+                     created_at: nil, updated_at: nil)
+        @client = client
+        @id = id
+        @key = key
+        @name = name
+        @level = level
+        @description = description
+        @parent_id = parent_id
+        @environments = environments || {}
+        @created_at = created_at
+        @updated_at = updated_at
+      end
+
+      def save
+        raise "SmplLogGroup was constructed without a client; cannot save" if @client.nil?
+
+        updated =
+          if @created_at.nil?
+            @client._create_log_group(self)
+          else
+            @client._update_log_group(self)
+          end
+        _apply(updated)
+        self
+      end
+      alias save! save
+
+      def delete
+        raise "SmplLogGroup was constructed without a client; cannot delete" if @client.nil?
+
+        @client.delete(@key)
+      end
+      alias delete! delete
+
+      def _apply(other)
+        @id = other.id
+        @key = other.key
+        @name = other.name
+        @level = other.level
+        @description = other.description
+        @parent_id = other.parent_id
+        @environments = other.environments
+        @created_at = other.created_at
+        @updated_at = other.updated_at
+      end
+    end
+  end
+end

data/lib/smplkit/logging/normalize.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Smplkit
+  module Logging
+    # Logger name normalization per ADR-034 §5.
+    #
+    # Replace +/+ with +.+, replace +:+ with +.+, lowercase everything.
+    module Normalize
+      module_function
+
+      def normalize_logger_name(name)
+        name.to_s.tr("/:", "..").downcase
+      end
+    end
+  end
+end