console_kit 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 348d99d0b8d74a78d96ffa4e74f7ee2baf25aab659700b5d44929d2e3cd87104
-  data.tar.gz: 9c5e7514f498818e2ffe8b0a9376511cbf364e81336a266df7fe02d143a26cf4
+  metadata.gz: 88e21758bbea2b210aedef584fabb6da0bd68084adfc5a00a831b756bd923b1c
+  data.tar.gz: 0fc14b5091c42181416f065a9513875daa59847b4f919f293d5ed548e494c83b
 SHA512:
-  metadata.gz: 5e56f04db89485e9b0a3a23b667062a8998287a8ab9ad67dc793f3202730ba6f54dcf02f45ab65ff739e3aef23ec7c65574ba32c4aafe7cebc1a6dcff63c907f
-  data.tar.gz: 86d6d4457bb2ad62e8ac2ecdd22c3afc0fa72313f4625cf4b304bbd1f0436a67033e0a2c4190d995895b12aba4aef77c68465ffa1fe1dcf6815d93909f355394
+  metadata.gz: 8f04ee40c2c17bfea636739a4de3d8578fc26da679dbc638bb606931f09ab951852c5b2f212132eaf85f61b411bd09a3a88fc48dca7caa48dc40106587c8fb4a
+  data.tar.gz: 16be45ab2a923ffe6c7a4e772175cb614787faf3de5bbc6d20b53f6dcf2b25c77a3b61e0da80c814cd430fabe3a85f7b2c54844b1121810f062ccf03f5844088

data/lib/console_kit/configuration.rb

@@ -1,39 +1,33 @@
 # frozen_string_literal: true
 
+require_relative 'configuration_validator'
+
 module ConsoleKit
-  # Stores ConsoleKit configurations such as tenant map and context behavior
   class Configuration
-    # Value object for storing configuration settings
-    Settings = Struct.new(:pretty_output, :tenants, :context_class, :sql_base_class, :show_dashboard)
+    attr_accessor :pretty_output, :tenants, :sql_base_class, :show_dashboard
+    attr_writer :context_class
 
     def initialize
-      @settings = Settings.new(true, nil, nil, 'ApplicationRecord', false)
-    end
-
-    %i[pretty_output tenants context_class sql_base_class show_dashboard].each do |attr|
-      define_method(attr) { @settings.send(attr) }
-      define_method("#{attr}=") { |val| @settings.send("#{attr}=", val) }
+      @pretty_output = true
+      @context_class = nil
+      @tenants = nil
+      @sql_base_class = 'ApplicationRecord'
+      @show_dashboard = false
     end
 
     def context_class
-      val = @settings.context_class
-      case val
-      when String, Symbol then resolve_context_class(val)
-      else val
+      case @context_class
+      when String, Symbol then resolve_context_class(@context_class)
+      else @context_class
       end
     end
 
-    def validate
-      validate!
-      true
-    rescue Error
-      false
-    end
-
     def validate!
       raise Error, 'ConsoleKit: `tenants` is not configured.' if tenants.blank?
       raise Error, 'ConsoleKit: `tenants` must be a Hash.' unless tenants.is_a?(Hash)
-      raise Error, 'ConsoleKit: `context_class` is not configured.' if @settings.context_class.blank?
+      raise Error, 'ConsoleKit: `context_class` is not configured.' if @context_class.blank?
+
+      ConfigurationValidator.new(self).validate!
     end
 
     private

data/lib/console_kit/configuration_validator.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+require_relative 'output'
+require_relative 'connections/diagnostic_helpers'
+
+module ConsoleKit
+  class TenantEntry
+    EXTRA_CONSTANTS_KEYS = [:environment].freeze
+
+    attr_reader :key, :errors, :warnings
+
+    def initialize(key, entry)
+      @key = key
+      @entry = entry
+      @errors = []
+      @warnings = []
+    end
+
+    def constants
+      constants = @entry[:constants] if @entry.is_a?(Hash)
+      constants if constants.is_a?(Hash)
+    end
+
+    def validate
+      check_identifier
+      return @errors << "ConsoleKit: tenant #{@key.inspect} configuration must be a Hash, got #{@entry.class}." \
+        unless @entry.is_a?(Hash)
+
+      validate_constants
+    end
+
+    private
+
+    def validate_constants
+      declared = @entry[:constants]
+      tenant = @key.inspect
+      return @errors << "ConsoleKit: tenant #{tenant} is missing a `:constants` Hash." if declared.nil?
+      unless declared.is_a?(Hash)
+        return @errors << "ConsoleKit: tenant #{tenant} `:constants` must be a Hash, got #{declared.class}."
+      end
+
+      check_required_keys
+      check_constants_values
+      warn_unknown_keys
+    end
+
+    def check_identifier
+      return if (@key.is_a?(Symbol) || @key.is_a?(String)) && @key.to_s.strip.present?
+
+      @errors << "ConsoleKit: tenant identifier #{@key.inspect} must be a non-blank Symbol or String."
+    end
+
+    def check_required_keys
+      required = TenantPlan::REQUIRED_KEYS
+      missing = required - constants.keys
+      return if missing.empty?
+
+      @errors << "ConsoleKit: tenant #{@key.inspect} constants missing required keys: #{missing.join(', ')} " \
+                 "(expected: #{required.join(', ')})."
+    end
+
+    def check_constants_values
+      values = constants
+      Connections::BaseConnectionHandler.registry.each do |handler_class|
+        field = handler_class.constants_key
+        next unless values.key?(field)
+
+        check_backend_value(field, values[field], handler_class)
+      end
+    end
+
+    def check_backend_value(field, value, handler_class)
+      reason = handler_class.target_error(value)
+      return unless reason
+
+      scrubbed = Connections::DiagnosticHelpers.scrub(value.inspect)
+      @errors << "ConsoleKit: tenant #{@key.inspect} #{field} #{scrubbed} is invalid: #{reason}"
+    end
+
+    def warn_unknown_keys
+      recognised = TenantConfigurator.context_mapping.values + EXTRA_CONSTANTS_KEYS
+      extra = constants.keys - recognised
+      return if extra.empty?
+
+      @warnings << "tenant #{@key.inspect} constants has unrecognised keys: #{extra.map(&:inspect).join(', ')} " \
+                   "(recognised: #{recognised.map(&:inspect).join(', ')}). Check for typos."
+    end
+  end
+
+  class BackendCoverage
+    WARNING = 'tenant %<tenant>p does not name %<omitted>s, which other tenants do. Switching to it RESETS those ' \
+              'backends to their defaults rather than leaving them on the tenant before it.'
+
+    def initialize(entries)
+      @entries = entries.select(&:constants)
+    end
+
+    def warnings
+      @entries.filter_map do |entry|
+        omitted = named - entry.constants.keys
+        next if omitted.empty?
+
+        format(WARNING, tenant: entry.key, omitted: omitted.map(&:inspect).join(', '))
+      end
+    end
+
+    private
+
+    def named
+      @named ||= @entries.flat_map { |entry| entry.constants.keys }
+                         .intersection(Connections::BaseConnectionHandler.registry.map(&:constants_key))
+    end
+  end
+
+  class ConfigurationValidator
+    def initialize(configuration)
+      @configuration = configuration
+      @errors = []
+      @warnings = []
+    end
+
+    def validate!
+      entries.each do |entry|
+        entry.validate
+        errors.concat(entry.errors)
+        warnings.concat(entry.warnings)
+      end
+      check_across_tenants
+      raise ConfigurationError, errors.join("\n") if errors.any?
+    end
+
+    private
+
+    attr_reader :configuration, :errors, :warnings
+
+    def entries = @entries ||= configuration.tenants.map { |key, entry| TenantEntry.new(key, entry) }
+
+    def check_across_tenants
+      check_duplicate_identifiers
+      warnings.concat(BackendCoverage.new(entries).warnings)
+      check_context_writers
+      warnings.each { |message| Output.print_warning("ConsoleKit: #{message}") }
+    end
+
+    def check_duplicate_identifiers
+      configuration.tenants.keys.group_by { |key| key.to_s.downcase }.each_value do |keys|
+        next if keys.size < 2
+
+        errors << "ConsoleKit: tenant identifiers #{keys.map(&:inspect).join(', ')} are duplicates once " \
+                  'normalized (differ only by type or case). Tenant lookup uses an exact match, so only one ' \
+                  'of these is ever reachable.'
+      end
+    end
+
+    def check_context_writers
+      klass = resolve_context_class
+      missing = klass && configured_attributes.reject { |attr| writer?(klass, :"#{attr}=") }
+      return if missing.blank?
+
+      warnings << "context_class #{klass} has no writer for: #{missing.join(', ')}. ConsoleKit will silently " \
+                  'never configure that backend during a tenant switch.'
+    end
+
+    def configured_attributes
+      named = entries.filter_map { |entry| entry.constants&.keys }.flatten.uniq
+      TenantConfigurator.context_mapping.select { |_attr, field| named.include?(field) }.keys
+    end
+
+    def writer?(klass, writer) = klass.respond_to?(writer) || klass.method_defined?(writer)
+
+    def resolve_context_class
+      configuration.context_class
+    rescue Error => e
+      errors << e.message
+      nil
+    end
+  end
+end

data/lib/console_kit/connections/base_connection_handler.rb

@@ -1,50 +1,161 @@
 # frozen_string_literal: true
 
-require 'active_support/core_ext/class/subclasses'
-require 'active_support/core_ext/string/inflections'
-require 'active_support/core_ext/string/filters'
 require_relative 'diagnostic_helpers'
+require_relative '../errors'
+require_relative '../output'
+require_relative '../instrumentation'
+require_relative '../diagnostics'
 
 module ConsoleKit
   module Connections
-    # Parent class for connection handlers
+    module HandlerRegistry
+      COLLISION_WARNING = 'ConsoleKit: %<previous>s and %<current>s both claim the backend key %<key>p. Only ' \
+                          '%<current>s will be switched, verified and rolled back.'
+      DUPLICATE_ATTRIBUTE = 'ConsoleKit: %<current>s claims the context attribute %<attribute>p, which %<previous>s ' \
+                            'already claims for the %<key>p backend. One attribute is one slot on the context ' \
+                            'object, so each backend would write the other values there and the context would ' \
+                            'disagree with the live connection. Give %<current>s a context attribute of its own.'
+
+      class << self
+        def all = entries.values.freeze
+
+        def add(handler_class)
+          key = handler_class.backend_key
+          reject_duplicate_attribute(handler_class, key)
+          drop_other_keys(handler_class, key)
+          report_collision(entries[key], handler_class)
+          entries[key] = handler_class
+        end
+
+        def remove(handler_class)
+          key = handler_class.backend_key
+          entries.delete(key) if entries[key].equal?(handler_class)
+        end
+
+        private
+
+        def entries = @entries ||= {}
+
+        def drop_other_keys(handler_class, key)
+          entries.delete_if { |existing, klass| existing != key && klass.equal?(handler_class) }
+        end
+
+        def reject_duplicate_attribute(handler_class, key)
+          attribute = handler_class.context_attribute
+          previous_key, previous_class =
+            entries.find { |other, klass| other != key && klass.context_attribute == attribute }
+          return if !previous_class || same_declaration?(previous_class, handler_class)
+
+          raise ConfigurationError, format(DUPLICATE_ATTRIBUTE, current: handler_class, previous: previous_class,
+                                                                attribute: attribute, key: previous_key)
+        end
+
+        def same_declaration?(previous, current)
+          previous_name = previous.name
+          previous.equal?(current) || (previous_name && previous_name == current.name)
+        end
+
+        def report_collision(previous, current)
+          previous_name = previous&.name
+          current_name = current.name
+          return unless previous_name && current_name && previous_name != current_name
+
+          Instrumentation.increment('console_kit.handler_collision')
+          Output.print_warning(format(COLLISION_WARNING, previous: previous, current: current,
+                                                         key: current.backend_key))
+        end
+      end
+    end
+
     class BaseConnectionHandler
       include DiagnosticHelpers
 
       class << self
-        def registry = descendants
+        def backend_key = declaration[:backend_key] || superclass.try(:backend_key)
+        def display_name = declaration[:display_name] || superclass.try(:display_name)
+        def context_attribute = declaration[:context_attribute] || superclass.try(:context_attribute)
+        def constants_key = declaration[:constants_key] || superclass.try(:constants_key)
+        def detail_label = declaration[:detail_label] || superclass.try(:detail_label)
+
+        def backend(key, display_name:, context_attribute:, constants_key:, detail_label:)
+          @declaration = { backend_key: key, display_name: display_name, context_attribute: context_attribute,
+                           constants_key: constants_key, detail_label: detail_label }
+          HandlerRegistry.add(self)
+        end
+
+        def declaration = @declaration ||= {}
+
+        def registry = HandlerRegistry.all
+        def unregister(handler_class) = HandlerRegistry.remove(handler_class)
+
+        def target_error(_value) = nil
+
+        def identifier_error(value)
+          return if value.nil? || ((value.is_a?(String) || value.is_a?(Symbol)) && value.to_s.strip.present?)
+
+          'expected a non-blank String or Symbol'
+        end
       end
 
       attr_reader :context
 
       def initialize(context) = @context = context
-      def connect = raise NotImplementedError, "#{self.class} must implement #connect"
+
+      def backend_key = self.class.backend_key
+      def display_name = self.class.display_name
+
+      def target
+        attr_name = self.class.context_attribute
+        attr_name && context_attribute(attr_name).presence
+      end
+
       def available? = raise NotImplementedError, "#{self.class} must implement #available?"
-      def diagnostics = raise NotImplementedError, "#{self.class} must implement #diagnostics"
+      def snapshot = raise NotImplementedError, "#{self.class} must implement #snapshot"
+      def connect!(_target) = raise NotImplementedError, "#{self.class} must implement #connect!"
+      def restore(_snapshot) = raise NotImplementedError, "#{self.class} must implement #restore"
 
-      def safe_diagnostics(timeout: 2)
-        handler_name = self.class.name.demodulize.delete_suffix('ConnectionHandler')
-        thread, result_wrapper = spawn_diagnostic_thread(handler_name)
+      def unavailable_reason = nil
 
-        if thread.join(timeout)
-          result_wrapper[:value] || error_diagnostics(handler_name, StandardError.new('Unknown error'))
-        else
-          timeout_diagnostics(handler_name, timeout)
-        end
+      def prepare(_target) = nil
+
+      def verify!(_target) = nil
+
+      def diagnostics(level: :basic)
+        return unavailable_diagnostics unless available?
+
+        diagnostics_at(level)
+      rescue StandardError => e
+        raise e if ConsoleKit.programming_error?(e)
+
+        error_diagnostics(display_name, e)
       end
 
-      private
+      def diagnostic_identity = nil
 
-      def spawn_diagnostic_thread(handler_name)
-        wrapper = { value: nil }
-        thread = Thread.new { wrapper[:value] = run_diagnostics_safely(handler_name) { diagnostics } }
-        [thread, wrapper]
+      def safe_diagnostics(timeout: Diagnostics::DEFAULT_TIMEOUT, level: :basic)
+        Diagnostics::Runner.call(self, timeout: timeout, level: level)
       end
 
-      def run_diagnostics_safely(name)
-        yield
-      rescue StandardError => e
-        error_diagnostics(name, e)
+      def verification_error(expected, actual)
+        ConnectionVerificationError.new(
+          nil, backend: display_name, tenant: nil, expected: expected, actual: actual
+        )
+      end
+
+      private
+
+      def diagnostics_at(level) = level == :full ? full_diagnostics : basic_diagnostics
+
+      def basic_diagnostics = raise NotImplementedError, "#{self.class} must implement #basic_diagnostics"
+      def full_diagnostics = raise NotImplementedError, "#{self.class} must implement #full_diagnostics"
+
+      def validate_target!(target)
+        handler_class = self.class
+        reason = handler_class.target_error(target)
+        return unless reason
+
+        raise ConfigurationError,
+              "ConsoleKit: #{handler_class.constants_key} #{scrub(target.inspect)} is invalid: #{reason}."
       end
 
       def measure_latency
@@ -54,7 +165,10 @@ module ConsoleKit
       end
 
       def context_attribute(name) = @context.try(name)
-      def unavailable_diagnostics(name) = { name: name, status: :unavailable, latency_ms: nil, details: {} }
+
+      def unavailable_diagnostics
+        { name: display_name, status: :unavailable, latency_ms: nil, details: {} }
+      end
     end
   end
 end

data/lib/console_kit/connections/connection_manager.rb

@@ -4,23 +4,57 @@ require_relative 'sql_connection_handler'
 require_relative 'mongo_connection_handler'
 require_relative 'redis_connection_handler'
 require_relative 'elasticsearch_connection_handler'
+require_relative '../output'
+require_relative '../instrumentation'
 
 module ConsoleKit
   module Connections
-    # Manages available connection handlers
     class ConnectionManager
+      DROPPED_WARNING = 'was skipped because %<reason>s. That backend will NOT be switched, verified or rolled ' \
+                        'back; it is recorded on the tenant state so the switch cannot report itself as fully ' \
+                        'verified.'
+      HALF_IMPLEMENTED = 'it is only half-implemented (%<message>s)'
+      REPORTED_KEY = :console_kit_dropped_reported
+
       class << self
-        def available_handlers(context)
-          handler_classes.filter_map do |klass|
-            handler = klass.new(context)
-            handler if handler.available?
-          rescue NotImplementedError
-            nil
-          end
+        def available_handlers(context, dropped = nil)
+          handler_classes.filter_map { |klass| resolve(klass, context, dropped) }
         end
 
         private
 
+        def resolve(klass, context, dropped)
+          handler = klass.new(context)
+          return handler if handler.available?
+
+          drop(klass, dropped, handler.try(:unavailable_reason))
+        rescue NotImplementedError => e
+          drop(klass, dropped, format(HALF_IMPLEMENTED, message: e.message))
+        end
+
+        def drop(klass, dropped, reason)
+          return nil unless reason
+
+          report_dropped(klass, reason)
+          dropped << klass.backend_key if dropped
+          nil
+        end
+
+        def report_dropped(klass, reason)
+          Instrumentation.increment('console_kit.handler_dropped')
+          return unless unreported?(klass.backend_key, reason)
+
+          Output.print_warning("#{klass} #{format(DROPPED_WARNING, reason: reason)}")
+        end
+
+        def unreported?(key, reason)
+          reported = Thread.current[REPORTED_KEY] ||= {}
+          return false if reported[key] == reason
+
+          reported[key] = reason
+          true
+        end
+
         def handler_classes = BaseConnectionHandler.registry
       end
     end

data/lib/console_kit/connections/dashboard.rb

@@ -1,27 +1,19 @@
 # frozen_string_literal: true
 
 require_relative 'table_renderer'
+require_relative '../diagnostics'
 
 module ConsoleKit
   module Connections
-    # Displays connection diagnostics as a Unicode table
     module Dashboard
       class << self
-        def display
-          rows = fetch_diagnostics
+        def display(level: :basic)
+          rows = ConsoleKit::Diagnostics.run(level: level)
           return Output.print_warning('No connections available') if rows.empty?
 
           Output.print_header('Connection Dashboard')
           Output.print_raw(TableRenderer.render(rows))
         end
-
-        private
-
-        def fetch_diagnostics
-          ctx = ConsoleKit.configuration.context_class
-          handlers = ConnectionManager.available_handlers(ctx)
-          handlers.map(&:safe_diagnostics)
-        end
       end
     end
   end

data/lib/console_kit/connections/diagnostic_helpers.rb

@@ -1,21 +1,40 @@
 # frozen_string_literal: true
 
+require 'active_support/core_ext/string/filters'
+
 module ConsoleKit
   module Connections
-    # Shared helper methods for connection diagnostics
     module DiagnosticHelpers
+      CREDENTIAL_PATTERN = begin
+        url = %r{\b[a-z][a-z0-9+.-]*://\S*}i
+        secret_key = /password|passwd|pwd|secret|token|api[_-]?key|access[_-]?key|auth(?:orization)?/i
+        auth_scheme = /(?:Bearer|Basic|Token|Digest|ApiKey)\s+/i
+        assignment = /["']?\b#{secret_key}\b["']?\s*(?:=>|=|:(?!:))\s*["']?#{auth_scheme}?\S+/
+        noise = /
+          authentication|auth|is|was|for|error|required|mismatch|incorrect|invalid|failed|missing|expired|
+          limit|type|count|name|header|value|must|cannot|not|and|or|in|of|to|exceeded|denied|unsupported|
+          supported|rejected|refused|revoked|length|format|scheme|provider|store|file|path|key
+        /xi
+        phrase = /\b#{secret_key}\s+(?!#{noise}\b)["']?\S+/i
+        principal = /\b(?:for user|username|user name)\b\s+["']?\S+/i
+        principal_at = /\buser\s+["']?\S+@\S+/i
+        Regexp.union(url, assignment, phrase, principal, principal_at).freeze
+      end
+
+      REDACTED = '[redacted]'
+
       module_function
 
       def clock_time
         Process.clock_gettime(Process::CLOCK_MONOTONIC)
       end
 
-      def error_diagnostics(name, error)
-        { name: name, status: :error, latency_ms: nil, details: { error: error.message.truncate(60) } }
+      def scrub(message)
+        message.to_s.scrub.gsub(CREDENTIAL_PATTERN, REDACTED)
       end
 
-      def timeout_diagnostics(name, timeout)
-        { name: name, status: :timeout, latency_ms: nil, details: { error: "Timed out after #{timeout}s" } }
+      def error_diagnostics(name, error)
+        { name: name, status: :error, latency_ms: nil, details: { error: scrub(error.message).truncate(60) } }
       end
     end
   end