debugbundle 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 126aea22f92db0369dc85cf08b493d4a91691a316c7c9acfe01ef758e7406fda
-  data.tar.gz: e6dba95f670a89995a35c6024e73317ebc18347764bb786fefd807181b23d06b
+  metadata.gz: c33eb05bc99ae435c838069ade718b123f897eae489769a3aca8969289cdd5b2
+  data.tar.gz: 13628e1335f3597e46c1457a20b8f242972e5da2f54971cf69c9f5fef08ecf3e
 SHA512:
-  metadata.gz: e59add670d8eec20f3dd739101315b6b352ef991652c797a42cd92e9d3d92b3587c50d9382ef62f36b5f47a15101e14dfd03e6cf556c1cd2fe83d9b5100f4275
-  data.tar.gz: 7771fad92d01afb8b0d6398701e9cb0e1a5199b6f492474cd24b1d5698fddbb24c93a9cc26c29be02523e6d19b08475615d6b52d36adea54185134a4f167eb37
+  metadata.gz: 7c0e7b78a867a41fb326300ca20f816760cc43d4534109824c1ced09072a025eb54efaaceb3c16cc0f8d8ef686ecf065e99ee3a2c8b4f99ac50922d267184c25
+  data.tar.gz: 5d16ab5d4bddf01eb39fb65269c624d941ab5f9820b89e253c8c9131c528fff935f48d5d56f14b06a1e8d015a173f7412c937ba37476583eb1c32cd367643b21

data/README.md

@@ -314,7 +314,7 @@ This repository also ships a clean-install app-driven smoke harness that validat
 
 ```sh
 make smoke
-make smoke-published VERSION=1.1.2
+make smoke-published VERSION=1.3.0
 ```
 
 `make smoke` builds the gem, installs it into a fresh RubyGems home, drives a Rack request plus a browser relay batch through the public SDK surface, validates event envelope shape, and confirms the mock ingestion endpoint receives the expected service, environment, SDK metadata, and correlation fields.

data/lib/debugbundle/acknowledgement.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module DebugBundle
+  module Acknowledgement
+    RETRYABLE_REASONS = %w[
+      rate_limited
+      monthly_quota_exceeded
+      analytics_quota_exceeded
+    ].freeze
+    FIELDS = %w[accepted rejected errors].freeze
+
+    module_function
+
+    def decide(body, batch_length)
+      return { kind: :legacy } unless body.is_a?(Hash) && FIELDS.any? { |field| body.key?(field) }
+      return protocol_failure unless FIELDS.all? { |field| body.key?(field) }
+
+      accepted = body['accepted']
+      rejected = body['rejected']
+      errors = body['errors']
+      return protocol_failure unless count?(accepted) && count?(rejected) && errors.is_a?(Array)
+      return protocol_failure unless accepted + rejected == batch_length && errors.length == rejected
+
+      seen = {}
+      retryable_indices = []
+      terminal_errors = []
+      errors.each do |error|
+        return protocol_failure unless error.is_a?(Hash)
+
+        index = error['index']
+        reason = error['reason']
+        return protocol_failure unless index.is_a?(Integer) && index.between?(0, batch_length - 1)
+        return protocol_failure unless reason.is_a?(String) && !reason.empty? && !seen[index]
+
+        seen[index] = true
+        if RETRYABLE_REASONS.include?(reason)
+          retryable_indices << index
+        else
+          terminal_errors << [index, reason]
+        end
+      end
+
+      {
+        kind: :acknowledged,
+        accepted: accepted,
+        retryable_indices: retryable_indices,
+        terminal_errors: terminal_errors
+      }
+    end
+
+    def count?(value)
+      value.is_a?(Integer) && value >= 0
+    end
+
+    def protocol_failure
+      { kind: :protocol_failure }
+    end
+  end
+end

data/lib/debugbundle/before_send.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module DebugBundle
+  module BeforeSend
+    REQUIRED_PAYLOAD_FIELDS = {
+      'backend_exception' => %w[name message stack handled request response runtime],
+      'request_event' => %w[method path query headers response_status duration_ms],
+      'log_event' => %w[level message attributes],
+      'frontend_breadcrumb' => %w[breadcrumb_type data],
+      'frontend_exception' => %w[name message stack],
+      'deploy_metadata' => %w[commit_sha version branch environment deployed_at],
+      'error_suppressed' => %w[fingerprint suppressed_count window_seconds first_seen last_seen],
+      'probe_event' => %w[label data activation_id probe_label_pattern]
+    }.freeze
+    ALLOWED_PAYLOAD_FIELDS = {
+      'backend_exception' => %w[name message stack handled request response runtime probe_data],
+      'request_event' => %w[
+        method path query headers body response_status duration_ms route_template
+        response_headers response_body device
+      ],
+      'log_event' => %w[level message attributes device],
+      'frontend_breadcrumb' => %w[breadcrumb_type route data device],
+      'frontend_exception' => %w[
+        name message stack route browser breadcrumbs device browser_event
+        rejection_reason dom_context probe_data
+      ],
+      'deploy_metadata' => %w[commit_sha version branch environment deployed_at],
+      'error_suppressed' => %w[fingerprint suppressed_count window_seconds first_seen last_seen device],
+      'probe_event' => %w[label data activation_id probe_label_pattern device]
+    }.freeze
+    ROOT_FIELDS = %w[
+      schema_version event_id event_type project_token project_id sdk_name sdk_version
+      service occurred_at correlation context payload
+    ].freeze
+    UUID_PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/i
+
+    module_function
+
+    def apply(event, hook)
+      return event unless hook
+
+      result = hook.call(Marshal.load(Marshal.dump(event)))
+      return nil if result.nil?
+
+      valid?(result) ? result : event
+    rescue StandardError
+      event
+    end
+
+    def valid?(event)
+      return false unless event.is_a?(Hash)
+      return false unless (event.keys - ROOT_FIELDS).empty?
+      return false unless %w[schema_version event_id event_type occurred_at sdk_name sdk_version].all? do |field|
+        event[field].is_a?(String) && !event[field].empty?
+      end
+      return false unless UUID_PATTERN.match?(event['event_id'])
+
+      Time.iso8601(event['occurred_at'])
+      service = event['service']
+      payload = event['payload']
+      fields = REQUIRED_PAYLOAD_FIELDS[event['event_type']]
+      allowed_fields = ALLOWED_PAYLOAD_FIELDS[event['event_type']]
+      service.is_a?(Hash) &&
+        service['name'].is_a?(String) && !service['name'].empty? &&
+        service['environment'].is_a?(String) && !service['environment'].empty? &&
+        payload.is_a?(Hash) &&
+        fields &&
+        allowed_fields &&
+        (payload.keys - allowed_fields).empty? &&
+        fields.all? { |field| payload.key?(field) } &&
+        valid_payload_shape?(event['event_type'], payload)
+    rescue ArgumentError
+      false
+    end
+
+    def valid_payload_shape?(event_type, payload)
+      case event_type
+      when 'backend_exception'
+        valid_backend_exception?(payload)
+      when 'request_event'
+        valid_request_event?(payload)
+      when 'log_event'
+        non_empty_strings?(payload, 'level', 'message') && payload['attributes'].is_a?(Hash)
+      when 'frontend_breadcrumb'
+        non_empty_strings?(payload, 'breadcrumb_type') && payload['data'].is_a?(Hash)
+      when 'frontend_exception'
+        valid_frontend_exception?(payload)
+      when 'deploy_metadata'
+        valid_deploy_metadata?(payload)
+      when 'error_suppressed'
+        valid_error_suppressed?(payload)
+      when 'probe_event'
+        valid_probe_event?(payload)
+      else
+        false
+      end
+    end
+
+    def valid_backend_exception?(payload)
+      non_empty_strings?(payload, 'name', 'message', 'stack') &&
+        [true, false].include?(payload['handled']) &&
+        %w[request response runtime].all? { |field| payload[field].is_a?(Hash) } &&
+        optional_hash?(payload, 'probe_data')
+    end
+
+    def valid_request_event?(payload)
+      non_empty_strings?(payload, 'method', 'path') &&
+        payload['query'].is_a?(Hash) &&
+        payload['headers'].is_a?(Hash) &&
+        non_negative_number?(payload['response_status']) &&
+        non_negative_number?(payload['duration_ms']) &&
+        optional_hash?(payload, 'response_headers')
+    end
+
+    def valid_frontend_exception?(payload)
+      non_empty_strings?(payload, 'name', 'message', 'stack') &&
+        (!payload.key?('breadcrumbs') || payload['breadcrumbs'].is_a?(Array)) &&
+        optional_hash?(payload, 'probe_data')
+    end
+
+    def valid_deploy_metadata?(payload)
+      non_empty_strings?(payload, 'commit_sha', 'version', 'branch', 'environment') &&
+        timestamp?(payload['deployed_at'])
+    end
+
+    def valid_error_suppressed?(payload)
+      non_empty_strings?(payload, 'fingerprint') &&
+        non_negative_integer?(payload['suppressed_count']) &&
+        positive_integer?(payload['window_seconds']) &&
+        timestamp?(payload['first_seen']) &&
+        timestamp?(payload['last_seen'])
+    end
+
+    def valid_probe_event?(payload)
+      non_empty_strings?(payload, 'label', 'probe_label_pattern') &&
+        payload['data'].is_a?(Hash) &&
+        nullable_uuid?(payload['activation_id'])
+    end
+
+    def non_empty_strings?(payload, *fields)
+      fields.all? { |field| payload[field].is_a?(String) && !payload[field].strip.empty? }
+    end
+
+    def optional_hash?(payload, field)
+      !payload.key?(field) || payload[field].is_a?(Hash)
+    end
+
+    def non_negative_number?(value)
+      value.is_a?(Numeric) && value.finite? && value >= 0
+    end
+
+    def non_negative_integer?(value)
+      value.is_a?(Integer) && value >= 0
+    end
+
+    def positive_integer?(value)
+      value.is_a?(Integer) && value.positive?
+    end
+
+    def timestamp?(value)
+      value.is_a?(String) && Time.iso8601(value)
+    rescue ArgumentError
+      false
+    end
+
+    def nullable_uuid?(value)
+      value.nil? || (value.is_a?(String) && UUID_PATTERN.match?(value))
+    end
+  end
+end

data/lib/debugbundle/client.rb

@@ -4,6 +4,7 @@ require 'digest'
 require 'time'
 require 'uri'
 
+require 'debugbundle/client_event_support'
 require 'debugbundle/runtime'
 
 module DebugBundle
@@ -96,6 +97,7 @@ module DebugBundle
       @last_event_at = nil
       @retry_at = nil
       @consecutive_failures = 0
+      @acknowledgement_state = nil
       @at_exit_registered = false
       @thread_exception_registered = false
       @logger_bindings = {}
@@ -110,6 +112,10 @@ module DebugBundle
     end
 
     def capture_exception(error, context: nil, handled: true)
+      capture_exception_internal(error, context: context, handled: handled, run_before_send: true)
+    end
+
+    def capture_exception_internal(error, context:, handled:, run_before_send:)
       return unless capture_enabled?
 
       poll_remote_config_if_due!
@@ -133,11 +139,22 @@ module DebugBundle
       extra_context = merged_context.except('request', 'response', 'correlation')
       extra_context['causes'] = causes unless causes.empty?
 
-      suppression_key = [payload['name'], payload['message'], payload['stack']].join(':')
+      event = base_event('backend_exception', payload, extra_context)
+      event = apply_before_send(event) if run_before_send
+      return if event.nil?
+
+      event_payload = event.fetch('payload')
+      suppression_key = [
+        event['event_type'],
+        event_payload['name'],
+        event_payload['message'],
+        event_payload['stack']
+      ].join(':')
       return unless @suppression.should_capture(suppression_key, now: monotonic_now)
 
-      enqueue_event(base_event('backend_exception', payload, extra_context))
+      enqueue_event(event)
     end
+    private :capture_exception_internal
 
     def capture_error(error, context: nil, handled: true) = capture_exception(error, context: context, handled: handled)
 
@@ -147,7 +164,6 @@ module DebugBundle
       poll_remote_config_if_due!
 
       normalized_level = normalize_level(level || :warning)
-      return unless level_enabled?(normalized_level)
 
       merged_context = merge_context(context)
       payload = {
@@ -155,7 +171,10 @@ module DebugBundle
         'message' => message.to_s,
         'attributes' => merged_context
       }
-      enqueue_event(base_event('log_event', payload, merged_context))
+      event = apply_before_send(base_event('log_event', payload, merged_context))
+      return if event.nil? || !level_enabled?(normalized_level)
+
+      enqueue_event(event)
     end
 
     def capture_request(request, response, context: nil)
@@ -167,7 +186,6 @@ module DebugBundle
       sanitized_request = request_payload(request)
       sanitized_response = response_payload(response)
       response_status = (sanitized_response['status_code'] || 0).to_i
-      return unless capture_request_event?(response_status, sanitized_request)
 
       payload = {
         'method' => sanitized_request['method'],
@@ -181,7 +199,12 @@ module DebugBundle
         'response_headers' => sanitized_response['headers'],
         'response_body' => sanitized_response['body']
       }
-      enqueue_event(base_event('request_event', payload, merged_context.merge('request' => sanitized_request)))
+      event = apply_before_send(
+        base_event('request_event', payload, merged_context.merge('request' => sanitized_request))
+      )
+      return if event.nil? || !capture_request_event?(response_status, sanitized_request)
+
+      enqueue_event(event)
     end
 
     def capture_message(message, level: nil, context: nil)
@@ -203,18 +226,22 @@ module DebugBundle
       if heavy
         return if matching_directives.empty?
 
-        raw_value = block ? block.call : data
-        emit_probe_events(label.to_s, @redactor.redact_value(raw_value), matching_directives)
+        resolved, raw_value = resolve_probe_value(data, block)
+        return unless resolved
+
+        emit_probe_events(label.to_s, normalize_probe_data(raw_value), matching_directives)
         return
       end
 
       return if !@probe_buffers.key?(label) && @probe_buffers.size >= config.max_probe_labels
 
-      raw_value = block ? block.call : data
+      resolved, raw_value = resolve_probe_value(data, block)
+      return unless resolved
+
       entry = {
         'label' => label.to_s,
-        'data' => @redactor.redact_value(raw_value),
-        'occurred_at' => now.iso8601
+        'data' => normalize_probe_data(raw_value),
+        'timestamp' => now.iso8601
       }
 
       bucket = (@probe_buffers[label.to_s] ||= [])
@@ -240,7 +267,13 @@ module DebugBundle
         error = $ERROR_INFO
         next unless error.is_a?(Exception)
 
-        client.capture_exception(error, handled: false)
+        client.__send__(
+          :capture_exception_internal,
+          error,
+          context: nil,
+          handled: false,
+          run_before_send: false
+        )
         client.flush
       end
       true
@@ -329,11 +362,7 @@ module DebugBundle
 
         case result.status_code
         when 200..299
-          remove_buffered_events(batch)
-          @retry_at = nil
-          @consecutive_failures = 0
-          @last_event_at = now
-          true
+          handle_successful_result(result, batch)
         when 429
           @consecutive_failures += 1
           retry_after_seconds = (result.retry_after_seconds || 1).clamp(1, RETRY_AFTER_CAP_SECONDS)
@@ -358,6 +387,7 @@ module DebugBundle
     def status
       return :disconnected unless config.enabled?
       return :degraded unless config.configured?
+      return @acknowledgement_state if @acknowledgement_state
       return :disconnected if @consecutive_failures >= 3
       return :degraded if rate_limited?
 
@@ -368,6 +398,48 @@ module DebugBundle
 
     private
 
+    def handle_successful_result(result, batch)
+      decision = Acknowledgement.decide(result.body, batch.length)
+      return handle_protocol_failure if decision[:kind] == :protocol_failure
+
+      if decision[:kind] == :legacy
+        remove_buffered_events(batch)
+        record_success
+        return true
+      end
+
+      retryable_indices = decision.fetch(:retryable_indices)
+      retryable_events = retryable_indices.map { |index| batch.fetch(index) }
+      remove_buffered_events(batch - retryable_events)
+      @last_event_at = now if decision.fetch(:accepted).positive?
+
+      if retryable_events.any?
+        @consecutive_failures += 1
+        @retry_at = now + 1
+        @acknowledgement_state = :degraded
+        false
+      else
+        @retry_at = nil
+        @consecutive_failures = 0
+        @acknowledgement_state = decision.fetch(:accepted).positive? ? nil : :disconnected
+        decision.fetch(:accepted).positive?
+      end
+    end
+
+    def handle_protocol_failure
+      @consecutive_failures += 1
+      @retry_at = now + 1
+      @acknowledgement_state = :degraded
+      false
+    end
+
+    def record_success
+      @retry_at = nil
+      @consecutive_failures = 0
+      @acknowledgement_state = nil
+      @last_event_at = now
+    end
+
     def build_default_transport
       return nil unless config.enabled?
 
@@ -391,204 +463,6 @@ module DebugBundle
       )
     end
 
-    def capture_enabled? = config.enabled? && config.configured?
-
-    def merge_context(context)
-      merged = @context.merge(stringify_hash(context || {}))
-      @redactor.redact_value(merged)
-    end
-
-    def stringify_hash(value)
-      return {} unless value.is_a?(Hash)
-
-      value.each_with_object({}) do |(key, nested_value), result|
-        result[key.to_s] = nested_value
-      end
-    end
-
-    def request_payload(request)
-      source = object_to_hash(request)
-      {
-        'method' => source['method'] || 'UNKNOWN',
-        'path' => source['path'] || '/',
-        'query' => @redactor.redact_value(source['query'] || {}),
-        'headers' => sanitized_headers(source['headers'] || {}),
-        'body' => @redactor.redact_value(source['body'] || {})
-      }
-    end
-
-    def response_payload(response)
-      source = object_to_hash(response)
-      {
-        'status_code' => source['status_code'] || source['status'] || 0,
-        'headers' => sanitized_headers(source['headers'] || {}),
-        'body' => @redactor.redact_value(source['body'] || {})
-      }
-    end
-
-    def runtime_payload = Runtime.payload
-
-    def exception_causes(error)
-      causes = []
-      current = error.cause
-
-      while current
-        causes << {
-          'name' => current.class.name,
-          'message' => current.message.to_s,
-          'stack' => Array(current.backtrace).join("\n")
-        }
-        current = current.cause
-      end
-
-      causes
-    end
-
-    def probe_snapshot
-      items = @probe_buffers.values.flatten.map do |entry|
-        entry.merge('activation_id' => nil)
-      end
-      return {} if items.empty?
-
-      { 'version' => 1, 'items' => items }
-    end
-
-    def enqueue_event(event)
-      return unless sampled_in?
-
-      @buffer_mutex.synchronize do
-        @buffer << event
-        @buffer.shift while @buffer.length > MAX_BUFFER_SIZE
-      end
-    end
-
-    def buffered_batch
-      @buffer_mutex.synchronize { @buffer.dup }
-    end
-
-    def remove_buffered_events(events)
-      event_ids = events.map { |event| event['event_id'] }
-      @buffer_mutex.synchronize do
-        @buffer.reject! { |event| event_ids.include?(event['event_id']) }
-      end
-    end
-
-    def sampled_in?
-      return false if config.sample_rate <= 0.0
-      return true if config.sample_rate >= 1.0
-
-      @random_provider.call.to_f < config.sample_rate
-    rescue StandardError
-      true
-    end
-
-    def append_suppression_aggregates
-      @suppression.drain_aggregates(now: monotonic_now).each do |aggregate|
-        enqueue_event(base_event('error_suppressed', aggregate, {}))
-      end
-    end
-
-    def base_event(event_type, payload, context)
-      event = {
-        'schema_version' => SCHEMA_VERSION,
-        'event_id' => SecureRandom.uuid,
-        'event_type' => event_type,
-        'project_token' => config.project_token,
-        'sdk_name' => SDK_NAME,
-        'sdk_version' => DebugBundle::VERSION,
-        'service' => {
-          'name' => service_name,
-          'runtime' => 'ruby',
-          'framework' => context['framework'],
-          'environment' => environment_name
-        },
-        'occurred_at' => now.iso8601,
-        'correlation' => correlation_payload(context),
-        'payload' => @redactor.redact_value(payload)
-      }
-      envelope_context = event_context(context)
-      event['context'] = envelope_context unless envelope_context.empty?
-      event
-    end
-
-    def service_name = config.service || DEFAULT_SERVICE_NAME
-
-    def environment_name = config.environment || DEFAULT_ENVIRONMENT
-
-    def correlation_payload(context)
-      request = object_to_hash(context['request'])
-      correlation = object_to_hash(context['correlation'])
-      {
-        'request_id' => correlation['request_id'] || request['request_id'] || context['request_id'],
-        'trace_id' => correlation['trace_id'] || request['trace_id'] || context['trace_id'],
-        'session_id' => correlation['session_id'] || context['session_id'],
-        'user_id_hash' => correlation['user_id_hash'] || context['user_id_hash']
-      }
-    end
-
-    def event_context(context)
-      object_to_hash(context).except(
-        'request',
-        'response',
-        'correlation',
-        'request_id',
-        'trace_id',
-        'session_id',
-        'user_id_hash'
-      )
-    end
-
-    def object_to_hash(value)
-      case value
-      when Hash
-        stringify_hash(value)
-      else
-        if value.respond_to?(:to_h)
-          stringify_hash(value.to_h)
-        elsif value.respond_to?(:to_hash)
-          stringify_hash(value.to_hash)
-        else
-          {}
-        end
-      end
-    rescue StandardError
-      {}
-    end
-
-    def sanitized_headers(headers)
-      stringify_hash(headers).each_with_object({}) do |(key, value), result|
-        normalized_key = key.to_s.downcase
-        next unless DEFAULT_HEADER_ALLOWLIST.include?(normalized_key)
-
-        result[normalized_key] = @redactor.redact_value(value)
-      end
-    end
-
-    def normalize_level(level)
-      candidate = level.to_s.strip.downcase.to_sym
-      return candidate if LOG_LEVEL_RANKS.key?(candidate)
-
-      :warning
-    end
-
-    def level_enabled?(level)
-      threshold = [normalize_level(config.log_level), policy_log_level].max_by { |entry| LOG_LEVEL_RANKS.fetch(entry) }
-      LOG_LEVEL_RANKS.fetch(level) >= LOG_LEVEL_RANKS.fetch(threshold)
-    end
-
-    def policy_log_level
-      case @capture_policy.capture_logs
-      when 'off'
-        :fatal
-      when 'error'
-        :error
-      when 'info'
-        :info
-      else
-        :warning
-      end
-    end
-
     def capture_request_event?(status_code, request)
       mode = @capture_policy.capture_request_events
 
@@ -667,15 +541,12 @@ module DebugBundle
     end
 
     def emit_probe_events(label, data, matching_directives)
-      allowed_directives = if @capture_policy.capture_probe_events == 'standalone_when_activated'
-                             matching_directives
-                           else
-                             matching_request_trigger_directives(label)
-                           end
-      return if allowed_directives.empty?
-
-      allowed_directives.each do |directive|
-        enqueue_event(
+      request_directives = matching_request_trigger_directives(label)
+      candidate_directives = (matching_directives + request_directives).uniq(&:id)
+      return if candidate_directives.empty?
+
+      candidate_directives.each do |directive|
+        event = apply_before_send(
           base_event(
             'probe_event',
             {
@@ -687,6 +558,9 @@ module DebugBundle
             {}
           )
         )
+        allowed = request_directives.include?(directive) ||
+                  @capture_policy.capture_probe_events == 'standalone_when_activated'
+        enqueue_event(event) if event && allowed
       end
     end
 
@@ -729,7 +603,7 @@ module DebugBundle
     end
 
     def capture_thread_exception(error)
-      capture_exception(error, handled: false)
+      capture_exception_internal(error, context: nil, handled: false, run_before_send: false)
       flush
     rescue StandardError
       nil