brainzlab 0.1.10 → 0.1.12

data/lib/brainzlab/testing.rb

@@ -0,0 +1,327 @@
+# frozen_string_literal: true
+
+require_relative 'testing/event_store'
+require_relative 'testing/helpers'
+require_relative 'testing/matchers'
+
+module BrainzLab
+  # Testing utilities for BrainzLab SDK
+  #
+  # Provides helpers for stubbing SDK calls, capturing events,
+  # and custom matchers for RSpec/Minitest.
+  #
+  # @example Usage in RSpec
+  #   # spec/rails_helper.rb or spec/spec_helper.rb
+  #   require 'brainzlab/testing'
+  #
+  #   RSpec.configure do |config|
+  #     config.include BrainzLab::Testing::Helpers
+  #   end
+  #
+  # @example Usage in Minitest
+  #   # test/test_helper.rb
+  #   require 'brainzlab/testing'
+  #
+  #   class ActiveSupport::TestCase
+  #     include BrainzLab::Testing::Helpers
+  #   end
+  #
+  module Testing
+    class << self
+      # Global event store for capturing events during tests
+      def event_store
+        @event_store ||= EventStore.new
+      end
+
+      # Reset the event store (called between tests)
+      def reset!
+        @event_store = EventStore.new
+      end
+
+      # Check if testing mode is active
+      def enabled?
+        @enabled == true
+      end
+
+      # Enable testing mode (stubs all SDK calls)
+      def enable!
+        return if @enabled
+
+        @enabled = true
+        install_stubs!
+      end
+
+      # Disable testing mode
+      def disable!
+        return unless @enabled
+
+        @enabled = false
+        remove_stubs!
+      end
+
+      private
+
+      def install_stubs!
+        # Stub Flux (events/metrics)
+        stub_flux!
+
+        # Stub Recall (logging)
+        stub_recall!
+
+        # Stub Reflex (error tracking)
+        stub_reflex!
+
+        # Stub Pulse (APM/tracing)
+        stub_pulse!
+
+        # Stub Signal (alerts/notifications)
+        stub_signal!
+
+        # Stub other modules
+        stub_beacon!
+        stub_nerve!
+        stub_dendrite!
+        stub_sentinel!
+        stub_synapse!
+        stub_cortex!
+        stub_vault!
+        stub_vision!
+      end
+
+      def remove_stubs!
+        # Reset all modules to restore original behavior
+        BrainzLab.reset_configuration!
+      end
+
+      def stub_flux!
+        # Store original methods
+        @original_flux_track = BrainzLab::Flux.method(:track)
+
+        # Replace with capturing versions
+        BrainzLab::Flux.define_singleton_method(:track) do |name, properties = {}|
+          BrainzLab::Testing.event_store.record_event(name, properties)
+        end
+
+        BrainzLab::Flux.define_singleton_method(:track_for_user) do |user, name, properties = {}|
+          user_id = user.respond_to?(:id) ? user.id.to_s : user.to_s
+          BrainzLab::Testing.event_store.record_event(name, properties.merge(user_id: user_id))
+        end
+
+        # Stub metrics
+        %i[gauge increment decrement distribution histogram timing set].each do |method|
+          BrainzLab::Flux.define_singleton_method(method) do |name, value = nil, **opts|
+            BrainzLab::Testing.event_store.record_metric(method, name, value, opts)
+          end
+        end
+
+        BrainzLab::Flux.define_singleton_method(:measure) do |name, **opts, &block|
+          start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          result = block.call
+          duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000
+          BrainzLab::Testing.event_store.record_metric(:distribution, name, duration_ms, opts.merge(unit: 'ms'))
+          result
+        end
+
+        BrainzLab::Flux.define_singleton_method(:flush!) { true }
+      end
+
+      def stub_recall!
+        %i[debug info warn error fatal].each do |level|
+          BrainzLab::Recall.define_singleton_method(level) do |message, **data|
+            BrainzLab::Testing.event_store.record_log(level, message, data)
+          end
+        end
+
+        BrainzLab::Recall.define_singleton_method(:log) do |level, message, **data|
+          BrainzLab::Testing.event_store.record_log(level, message, data)
+        end
+
+        BrainzLab::Recall.define_singleton_method(:time) do |label, **data, &block|
+          start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          result = block.call
+          duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(1)
+          BrainzLab::Testing.event_store.record_log(:info, "#{label} (#{duration_ms}ms)", data.merge(duration_ms: duration_ms))
+          result
+        end
+
+        BrainzLab::Recall.define_singleton_method(:flush) { true }
+      end
+
+      def stub_reflex!
+        BrainzLab::Reflex.define_singleton_method(:capture) do |exception, **context|
+          BrainzLab::Testing.event_store.record_error(exception, context)
+        end
+
+        BrainzLab::Reflex.define_singleton_method(:capture_message) do |message, level: :error, **context|
+          BrainzLab::Testing.event_store.record_error_message(message, level, context)
+        end
+      end
+
+      def stub_pulse!
+        # Stub tracing methods
+        BrainzLab::Pulse.define_singleton_method(:start_trace) do |name, **opts|
+          BrainzLab::Testing.event_store.record_trace(name, opts.merge(action: :start))
+          { trace_id: 'test-trace-id-12345', name: name }
+        end
+
+        BrainzLab::Pulse.define_singleton_method(:finish_trace) do |**opts|
+          BrainzLab::Testing.event_store.record_trace('finish', opts.merge(action: :finish))
+          true
+        end
+
+        BrainzLab::Pulse.define_singleton_method(:span) do |name, **opts, &block|
+          BrainzLab::Testing.event_store.record_trace(name, opts.merge(type: :span))
+          block&.call
+        end
+
+        BrainzLab::Pulse.define_singleton_method(:record_trace) do |name, **opts|
+          BrainzLab::Testing.event_store.record_trace(name, opts)
+          true
+        end
+
+        BrainzLab::Pulse.define_singleton_method(:record_span) do |**opts|
+          BrainzLab::Testing.event_store.record_trace(opts[:name], opts)
+          true
+        end
+
+        BrainzLab::Pulse.define_singleton_method(:record_metric) do |name, **opts|
+          BrainzLab::Testing.event_store.record_metric(opts[:kind] || :gauge, name, opts[:value], tags: opts[:tags] || {})
+          true
+        end
+
+        # Stub metric convenience methods
+        %i[gauge counter histogram].each do |method|
+          BrainzLab::Pulse.define_singleton_method(method) do |name, value, tags: {}|
+            BrainzLab::Testing.event_store.record_metric(method, name, value, tags: tags)
+            true
+          end
+        end
+
+        # Stub distributed tracing methods
+        BrainzLab::Pulse.define_singleton_method(:inject) do |headers, **opts|
+          headers['traceparent'] = '00-test-trace-id-12345-test-span-id-67890-01'
+          headers
+        end
+
+        BrainzLab::Pulse.define_singleton_method(:extract) do |headers|
+          BrainzLab::Pulse::Propagation::Context.new(
+            trace_id: 'test-trace-id-12345',
+            span_id: 'test-span-id-67890'
+          ) if headers['traceparent']
+        end
+
+        BrainzLab::Pulse.define_singleton_method(:extract!) do |headers|
+          BrainzLab::Pulse.extract(headers)
+        end
+
+        BrainzLab::Pulse.define_singleton_method(:propagation_context) do
+          BrainzLab::Pulse::Propagation::Context.new(
+            trace_id: 'test-trace-id-12345',
+            span_id: 'test-span-id-67890'
+          )
+        end
+
+        BrainzLab::Pulse.define_singleton_method(:child_context) do
+          BrainzLab::Pulse::Propagation::Context.new(
+            trace_id: 'test-trace-id-12345',
+            span_id: SecureRandom.hex(8)
+          )
+        end
+      end
+
+      def stub_signal!
+        BrainzLab::Signal.define_singleton_method(:alert) do |name, message, severity: :warning, channels: nil, data: {}|
+          BrainzLab::Testing.event_store.record_alert(name, message, severity, channels, data)
+        end
+
+        BrainzLab::Signal.define_singleton_method(:notify) do |channel, message, title: nil, data: {}|
+          BrainzLab::Testing.event_store.record_notification(channel, message, title, data)
+        end
+
+        BrainzLab::Signal.define_singleton_method(:trigger) do |rule_name, context = {}|
+          BrainzLab::Testing.event_store.record_trigger(rule_name, context)
+        end
+
+        BrainzLab::Signal.define_singleton_method(:test!) { true }
+      end
+
+      def stub_beacon!
+        return unless defined?(BrainzLab::Beacon)
+
+        BrainzLab::Beacon.define_singleton_method(:create_http_monitor) { |*| { id: 'test-monitor-1', status: 'created' } }
+        BrainzLab::Beacon.define_singleton_method(:create_ssl_monitor) { |*| { id: 'test-monitor-2', status: 'created' } }
+        BrainzLab::Beacon.define_singleton_method(:create_tcp_monitor) { |*| { id: 'test-monitor-3', status: 'created' } }
+        BrainzLab::Beacon.define_singleton_method(:create_dns_monitor) { |*| { id: 'test-monitor-4', status: 'created' } }
+        BrainzLab::Beacon.define_singleton_method(:list) { [] }
+        BrainzLab::Beacon.define_singleton_method(:get) { |_id| nil }
+        BrainzLab::Beacon.define_singleton_method(:update) { |*| true }
+        BrainzLab::Beacon.define_singleton_method(:delete) { |_id| true }
+        BrainzLab::Beacon.define_singleton_method(:pause) { |_id| true }
+        BrainzLab::Beacon.define_singleton_method(:resume) { |_id| true }
+        BrainzLab::Beacon.define_singleton_method(:history) { |*| [] }
+        BrainzLab::Beacon.define_singleton_method(:status) { { status: 'up', monitors: 0 } }
+        BrainzLab::Beacon.define_singleton_method(:all_up?) { true }
+        BrainzLab::Beacon.define_singleton_method(:incidents) { [] }
+      end
+
+      def stub_nerve!
+        return unless defined?(BrainzLab::Nerve)
+
+        BrainzLab::Nerve.define_singleton_method(:flag) { |*| false }
+        BrainzLab::Nerve.define_singleton_method(:enabled?) { |*| false }
+        BrainzLab::Nerve.define_singleton_method(:disabled?) { |*| true }
+        BrainzLab::Nerve.define_singleton_method(:variation) { |*| nil }
+        BrainzLab::Nerve.define_singleton_method(:all_flags) { {} }
+      end
+
+      def stub_dendrite!
+        return unless defined?(BrainzLab::Dendrite)
+
+        BrainzLab::Dendrite.define_singleton_method(:get) { |*| nil }
+        BrainzLab::Dendrite.define_singleton_method(:set) { |*| true }
+        BrainzLab::Dendrite.define_singleton_method(:delete) { |*| true }
+        BrainzLab::Dendrite.define_singleton_method(:all) { {} }
+      end
+
+      def stub_sentinel!
+        return unless defined?(BrainzLab::Sentinel)
+
+        BrainzLab::Sentinel.define_singleton_method(:check) { |*| { allowed: true } }
+        BrainzLab::Sentinel.define_singleton_method(:allowed?) { |*| true }
+        BrainzLab::Sentinel.define_singleton_method(:denied?) { |*| false }
+      end
+
+      def stub_synapse!
+        return unless defined?(BrainzLab::Synapse)
+
+        BrainzLab::Synapse.define_singleton_method(:publish) { |*| true }
+        BrainzLab::Synapse.define_singleton_method(:subscribe) { |*| true }
+      end
+
+      def stub_cortex!
+        return unless defined?(BrainzLab::Cortex)
+
+        BrainzLab::Cortex.define_singleton_method(:read) { |*| nil }
+        BrainzLab::Cortex.define_singleton_method(:write) { |*| true }
+        BrainzLab::Cortex.define_singleton_method(:delete) { |*| true }
+        BrainzLab::Cortex.define_singleton_method(:fetch) { |key, **opts, &block| block&.call }
+      end
+
+      def stub_vault!
+        return unless defined?(BrainzLab::Vault)
+
+        BrainzLab::Vault.define_singleton_method(:get) { |*| nil }
+        BrainzLab::Vault.define_singleton_method(:set) { |*| true }
+        BrainzLab::Vault.define_singleton_method(:delete) { |*| true }
+      end
+
+      def stub_vision!
+        return unless defined?(BrainzLab::Vision)
+
+        BrainzLab::Vision.define_singleton_method(:track_pageview) { |*| true }
+        BrainzLab::Vision.define_singleton_method(:track_event) { |*| true }
+        BrainzLab::Vision.define_singleton_method(:identify) { |*| true }
+      end
+    end
+  end
+end

data/lib/brainzlab/utilities/circuit_breaker.rb

@@ -54,7 +54,7 @@ module BrainzLab
         case @state
         when :open
           track_rejected
-          raise CircuitOpenError, "Circuit '#{@name}' is open" unless fallback
+          raise CircuitOpenError.new(@name, failure_count: @failure_count, last_failure_at: @last_failure_at) unless fallback
 
           fallback.respond_to?(:call) ? fallback.call : fallback
 
@@ -65,7 +65,15 @@ module BrainzLab
 
       # Force the circuit to a specific state
       def force_state!(new_state)
-        raise ArgumentError, "Invalid state: #{new_state}" unless STATES.include?(new_state)
+        unless STATES.include?(new_state)
+          raise BrainzLab::ValidationError.new(
+            "Invalid circuit breaker state: #{new_state}",
+            hint: "Valid states are: #{STATES.join(', ')}",
+            code: 'invalid_circuit_state',
+            field: 'state',
+            context: { provided: new_state, valid_values: STATES }
+          )
+        end
 
         @mutex.synchronize do
           @state = new_state
@@ -255,7 +263,28 @@ module BrainzLab
       end
 
       # Error raised when circuit is open
-      class CircuitOpenError < StandardError; end
+      # Inherits from BrainzLab::ServiceUnavailableError for structured error handling
+      class CircuitOpenError < BrainzLab::ServiceUnavailableError
+        attr_reader :circuit_name, :failure_count, :last_failure_at
+
+        def initialize(circuit_name, failure_count: nil, last_failure_at: nil)
+          @circuit_name = circuit_name
+          @failure_count = failure_count
+          @last_failure_at = last_failure_at
+
+          super(
+            "Circuit '#{circuit_name}' is open",
+            hint: 'The circuit breaker has tripped due to repeated failures. The service will be retried automatically after the recovery timeout.',
+            code: 'circuit_open',
+            service_name: circuit_name,
+            context: {
+              circuit_name: circuit_name,
+              failure_count: failure_count,
+              last_failure_at: last_failure_at&.iso8601
+            }.compact
+          )
+        end
+      end
     end
   end
 end

data/lib/brainzlab/vault/client.rb

@@ -189,7 +189,27 @@ module BrainzLab
       end
 
       def log_error(operation, error)
-        BrainzLab.debug_log("[Vault::Client] #{operation} failed: #{error.message}")
+        structured_error = ErrorHandler.wrap(error, service: 'Vault', operation: operation)
+        BrainzLab.debug_log("[Vault::Client] #{operation} failed: #{structured_error.message}")
+
+        # Call on_error callback if configured
+        if @config.on_error
+          @config.on_error.call(structured_error, { service: 'Vault', operation: operation })
+        end
+      end
+
+      def handle_response_error(response, operation)
+        return if response.is_a?(Net::HTTPSuccess) || response.is_a?(Net::HTTPCreated) || response.is_a?(Net::HTTPNoContent)
+
+        structured_error = ErrorHandler.from_response(response, service: 'Vault', operation: operation)
+        BrainzLab.debug_log("[Vault::Client] #{operation} failed: #{structured_error.message}")
+
+        # Call on_error callback if configured
+        if @config.on_error
+          @config.on_error.call(structured_error, { service: 'Vault', operation: operation })
+        end
+
+        structured_error
       end
     end
   end

data/lib/brainzlab/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BrainzLab
-  VERSION = '0.1.10'
+  VERSION = '0.1.12'
 end

data/lib/brainzlab/vision/client.rb

@@ -98,18 +98,65 @@ module BrainzLab
         when Net::HTTPSuccess
           JSON.parse(response.body, symbolize_names: true)
         when Net::HTTPUnauthorized
-          { error: 'Unauthorized: Invalid API key' }
+          structured_error = AuthenticationError.new(
+            'Invalid API key',
+            hint: 'Verify your Vision API key is correct and has not expired.',
+            code: 'vision_unauthorized'
+          )
+          log_error(path, structured_error)
+          { error: structured_error.message, brainzlab_error: structured_error }
         when Net::HTTPForbidden
-          { error: 'Forbidden: Vision is not enabled for this project' }
+          structured_error = AuthenticationError.new(
+            'Vision is not enabled for this project',
+            hint: 'Enable Vision in your project settings or check your permissions.',
+            code: 'vision_forbidden'
+          )
+          log_error(path, structured_error)
+          { error: structured_error.message, brainzlab_error: structured_error }
         when Net::HTTPNotFound
-          { error: "Not found: #{path}" }
+          structured_error = NotFoundError.new(
+            "Vision endpoint not found: #{path}",
+            hint: 'Verify the Vision service is properly configured.',
+            code: 'vision_not_found',
+            resource_type: 'endpoint',
+            resource_id: path
+          )
+          log_error(path, structured_error)
+          { error: structured_error.message, brainzlab_error: structured_error }
+        when Net::HTTPTooManyRequests
+          structured_error = RateLimitError.new(
+            'Vision rate limit exceeded',
+            retry_after: response['Retry-After']&.to_i,
+            code: 'vision_rate_limit'
+          )
+          log_error(path, structured_error)
+          { error: structured_error.message, brainzlab_error: structured_error }
         else
-          { error: "HTTP #{response.code}: #{response.message}" }
+          structured_error = ErrorHandler.from_response(response, service: 'Vision', operation: path)
+          log_error(path, structured_error)
+          { error: structured_error.message, brainzlab_error: structured_error }
         end
       rescue JSON::ParserError => e
-        { error: "Invalid JSON response: #{e.message}" }
+        structured_error = ServerError.new(
+          "Invalid JSON response from Vision: #{e.message}",
+          hint: 'The Vision service returned an unexpected response format.',
+          code: 'vision_invalid_response'
+        )
+        log_error(path, structured_error)
+        { error: structured_error.message, brainzlab_error: structured_error }
       rescue StandardError => e
-        { error: "Request failed: #{e.message}" }
+        structured_error = ErrorHandler.wrap(e, service: 'Vision', operation: path)
+        log_error(path, structured_error)
+        { error: structured_error.message, brainzlab_error: structured_error }
+      end
+
+      def log_error(operation, error)
+        BrainzLab.debug_log("[Vision::Client] #{operation} failed: #{error.message}")
+
+        # Call on_error callback if configured
+        if @config.on_error
+          @config.on_error.call(error, { service: 'Vision', operation: operation })
+        end
       end
 
       def auth_key

data/lib/brainzlab.rb

@@ -1,7 +1,21 @@
 # frozen_string_literal: true
 
+# BrainzLab SDK - Official Ruby SDK for BrainzLab products
+#
+# For testing utilities, require 'brainzlab/testing' in your test helper:
+#
+#   require 'brainzlab/testing'
+#
+#   RSpec.configure do |config|
+#     config.include BrainzLab::Testing::Helpers
+#   end
+#
+# See BrainzLab::Testing for more details.
+
 require_relative 'brainzlab/version'
+require_relative 'brainzlab/errors'
 require_relative 'brainzlab/configuration'
+require_relative 'brainzlab/debug'
 require_relative 'brainzlab/context'
 require_relative 'brainzlab/recall'
 require_relative 'brainzlab/reflex'
@@ -18,6 +32,7 @@ require_relative 'brainzlab/sentinel'
 require_relative 'brainzlab/synapse'
 require_relative 'brainzlab/instrumentation'
 require_relative 'brainzlab/utilities'
+require_relative 'brainzlab/development'
 
 module BrainzLab
   class << self
@@ -45,6 +60,7 @@ module BrainzLab
       Dendrite.reset!
       Sentinel.reset!
       Synapse.reset!
+      Development.reset!
     end
 
     # Context management
@@ -94,6 +110,32 @@ module BrainzLab
       configuration.debug?
     end
 
+    # Query events stored in development mode
+    # @param service [Symbol, nil] filter by service (:recall, :reflex, :pulse, etc.)
+    # @param event_type [String, nil] filter by event type ('log', 'error', 'trace', etc.)
+    # @param since [Time, nil] filter events after this time
+    # @param limit [Integer] max number of events to return (default: 100)
+    # @return [Array<Hash>] matching events
+    # @example
+    #   BrainzLab.development_events                              # All events
+    #   BrainzLab.development_events(service: :recall)            # Only Recall logs
+    #   BrainzLab.development_events(service: :reflex, limit: 10) # Last 10 errors
+    #   BrainzLab.development_events(since: 1.hour.ago)           # Events from last hour
+    def development_events(service: nil, event_type: nil, since: nil, limit: 100)
+      Development.events(service: service, event_type: event_type, since: since, limit: limit)
+    end
+
+    # Clear all events stored in development mode
+    def clear_development_events!
+      Development.clear!
+    end
+
+    # Get stats about stored development events
+    # @return [Hash] counts by service
+    def development_stats
+      Development.stats
+    end
+
     # Health check - verifies connectivity to all enabled services
     # @return [Hash] Status of each service
     def health_check

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brainzlab
 version: !ruby/object:Gem::Version
-  version: 0.1.10
+  version: 0.1.12
 platform: ruby
 authors:
 - Brainz Lab
@@ -37,6 +37,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -102,9 +116,13 @@ files:
 - lib/brainzlab/cortex/cache.rb
 - lib/brainzlab/cortex/client.rb
 - lib/brainzlab/cortex/provisioner.rb
+- lib/brainzlab/debug.rb
 - lib/brainzlab/dendrite.rb
 - lib/brainzlab/dendrite/client.rb
 - lib/brainzlab/dendrite/provisioner.rb
+- lib/brainzlab/development.rb
+- lib/brainzlab/development/logger.rb
+- lib/brainzlab/development/store.rb
 - lib/brainzlab/devtools.rb
 - lib/brainzlab/devtools/assets/devtools.css
 - lib/brainzlab/devtools/assets/devtools.js
@@ -118,6 +136,7 @@ files:
 - lib/brainzlab/devtools/middleware/error_page.rb
 - lib/brainzlab/devtools/renderers/debug_panel_renderer.rb
 - lib/brainzlab/devtools/renderers/error_page_renderer.rb
+- lib/brainzlab/errors.rb
 - lib/brainzlab/flux.rb
 - lib/brainzlab/flux/buffer.rb
 - lib/brainzlab/flux/client.rb
@@ -183,6 +202,10 @@ files:
 - lib/brainzlab/synapse.rb
 - lib/brainzlab/synapse/client.rb
 - lib/brainzlab/synapse/provisioner.rb
+- lib/brainzlab/testing.rb
+- lib/brainzlab/testing/event_store.rb
+- lib/brainzlab/testing/helpers.rb
+- lib/brainzlab/testing/matchers.rb
 - lib/brainzlab/utilities.rb
 - lib/brainzlab/utilities/circuit_breaker.rb
 - lib/brainzlab/utilities/health_check.rb