logbrew-sdk 0.1.0 → 0.1.2

data/lib/logbrew/trace.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module LogBrew
+  TraceContext = Struct.new(:trace_id, :span_id, :parent_span_id, :trace_flags, :sampled, keyword_init: true)
+
+  class TraceScope
+    def initialize(scope_id)
+      @scope_id = scope_id
+      @closed = false
+    end
+
+    def close
+      return if @closed
+
+      LogBrew::Trace.close_scope(@scope_id)
+      @closed = true
+    end
+  end
+
+  # Request-local trace context for app-owned logs, errors, actions, and metrics.
+  module Trace
+    STACK_KEY = :logbrew_trace_stack
+    private_constant :STACK_KEY
+
+    module_function
+
+    def current
+      entry = stack.last
+      entry && entry[:context]
+    end
+
+    def activate(context)
+      unless context.is_a?(TraceContext)
+        raise SdkError.new("validation_error", "trace context must be a LogBrew::TraceContext")
+      end
+
+      scope_id = Object.new.object_id
+      stack << { id: scope_id, context: context }
+      TraceScope.new(scope_id)
+    end
+
+    def with_context(context)
+      scope = activate(context)
+      yield context
+    ensure
+      scope.close if scope
+    end
+
+    def close_scope(scope_id)
+      entries = stack
+      index = entries.rindex { |entry| entry[:id] == scope_id }
+      entries.delete_at(index) unless index.nil?
+    end
+
+    def continue_or_create(traceparent)
+      text = traceparent.to_s.strip
+      return create_root if text.empty?
+
+      from_traceparent(text)
+    rescue SdkError
+      create_root
+    end
+
+    def from_traceparent(traceparent)
+      context = Traceparent.parse(traceparent)
+      create(
+        trace_id: context.trace_id,
+        span_id: generate_span_id,
+        parent_span_id: context.parent_span_id,
+        trace_flags: context.trace_flags
+      )
+    end
+
+    def create_root
+      create(trace_id: generate_trace_id, span_id: generate_span_id, trace_flags: "01")
+    end
+
+    def create(trace_id:, span_id:, trace_flags: "01", parent_span_id: nil)
+      normalized_traceparent = Traceparent.create(trace_id: trace_id, span_id: span_id, trace_flags: trace_flags)
+      _version, normalized_trace_id, normalized_span_id, normalized_flags = normalized_traceparent.split("-")
+      normalized_parent_span_id = nil
+      unless parent_span_id.nil?
+        parent_traceparent = Traceparent.create(
+          trace_id: normalized_trace_id,
+          span_id: parent_span_id,
+          trace_flags: normalized_flags
+        )
+        normalized_parent_span_id = parent_traceparent.split("-")[2]
+      end
+
+      TraceContext.new(
+        trace_id: normalized_trace_id,
+        span_id: normalized_span_id,
+        parent_span_id: normalized_parent_span_id,
+        trace_flags: normalized_flags,
+        sampled: (normalized_flags.to_i(16) & 1) == 1
+      )
+    end
+
+    def create_headers(context = current)
+      return {} unless context
+
+      Traceparent.create_headers(
+        trace_id: context.trace_id,
+        span_id: context.span_id,
+        trace_flags: context.trace_flags
+      )
+    end
+
+    def metadata(context = current)
+      return {} unless context
+
+      {
+        "traceId" => context.trace_id,
+        "spanId" => context.span_id,
+        "traceFlags" => context.trace_flags,
+        "traceSampled" => context.sampled
+      }.tap do |payload|
+        payload["parentSpanId"] = context.parent_span_id unless context.parent_span_id.nil?
+      end
+    end
+
+    def add_metadata(target, context = current)
+      return target unless context
+
+      metadata(context).each do |key, value|
+        target[key] = value unless target.key?(key) || target.key?(key.to_sym)
+      end
+      target
+    end
+
+    def merge_attributes(attributes, context = current)
+      return attributes unless context && attributes.is_a?(Hash)
+
+      metadata_value = attributes.key?("metadata") ? attributes["metadata"] : attributes[:metadata]
+      return attributes unless metadata_value.nil? || metadata_value.is_a?(Hash)
+
+      copied = attributes.dup
+      merged_metadata = metadata_value.nil? ? {} : metadata_value.dup
+      add_metadata(merged_metadata, context)
+      if copied.key?(:metadata) && !copied.key?("metadata")
+        copied[:metadata] = merged_metadata
+      else
+        copied["metadata"] = merged_metadata
+      end
+      copied
+    end
+
+    def from_rack_env(env)
+      existing = env_value(env, "logbrew.trace")
+      return existing if existing.is_a?(TraceContext)
+
+      traceparent = env_value(env, "HTTP_TRACEPARENT") || env_value(env, "traceparent") || env_value(env, "logbrew.traceparent")
+      return continue_or_create(traceparent) unless traceparent.nil? || traceparent.empty?
+
+      trace_id = env_value(env, "logbrew.trace_id")
+      span_id = env_value(env, "logbrew.span_id")
+      if trace_id && span_id
+        begin
+          return create(
+            trace_id: trace_id,
+            span_id: span_id,
+            parent_span_id: env_value(env, "logbrew.parent_span_id"),
+            trace_flags: env_value(env, "logbrew.trace_flags") || "01"
+          )
+        rescue SdkError
+          nil
+        end
+      end
+
+      create_root
+    end
+
+    def generate_trace_id
+      loop do
+        value = SecureRandom.hex(16)
+        return value unless value.delete("0").empty?
+      end
+    end
+
+    def generate_span_id
+      loop do
+        value = SecureRandom.hex(8)
+        return value unless value.delete("0").empty?
+      end
+    end
+
+    def stack
+      Thread.current[STACK_KEY] ||= []
+    end
+    private_class_method :stack
+
+    def env_value(env, key)
+      return nil unless env.respond_to?(:[])
+
+      value = env[key]
+      return value if value.is_a?(TraceContext)
+      return nil if value.nil?
+
+      text = value.to_s
+      text.empty? ? nil : text
+    end
+    private_class_method :env_value
+  end
+
+  module TraceClientMethods
+    def issue(id, timestamp, attributes)
+      super(id, timestamp, Trace.merge_attributes(attributes))
+    end
+
+    def log(id, timestamp, attributes)
+      super(id, timestamp, Trace.merge_attributes(attributes))
+    end
+
+    def metric(id, timestamp, attributes)
+      super(id, timestamp, Trace.merge_attributes(attributes))
+    end
+
+    def action(id, timestamp, attributes)
+      super(id, timestamp, Trace.merge_attributes(attributes))
+    end
+  end
+
+  module TraceLoggerMethods
+    private
+
+    def logbrew_metadata(severity, message, progname)
+      Trace.add_metadata(super)
+    end
+  end
+
+  module TraceRackMiddlewareMethods
+    def call(env)
+      trace_context = Trace.from_rack_env(env)
+      env["logbrew.trace"] = trace_context if env.respond_to?(:[]=)
+      Trace.with_context(trace_context) { super(env) }
+    end
+
+    private
+
+    def capture_request_span(env, status_code, elapsed_ms, status)
+      context = rack_trace_context(env)
+      attributes = {
+        name: request_name(env),
+        traceId: context ? context.trace_id : trace_id(env),
+        spanId: context ? context.span_id : span_id(env),
+        status: status,
+        durationMs: elapsed_ms,
+        metadata: request_metadata(env, status_code)
+      }
+      attributes[:parentSpanId] = context.parent_span_id if context && context.parent_span_id
+
+      @client.span(next_event_id("span"), logbrew_timestamp, attributes)
+    end
+
+    def trace_id(env)
+      context = rack_trace_context(env)
+      return context.trace_id if context
+
+      super
+    end
+
+    def span_id(env)
+      context = rack_trace_context(env)
+      return context.span_id if context
+
+      super
+    end
+
+    def request_metadata(env, status_code)
+      Trace.add_metadata(super, rack_trace_context(env))
+    end
+
+    def exception_metadata(env, error)
+      Trace.add_metadata(super, rack_trace_context(env))
+    end
+
+    def rack_trace_context(env)
+      trace = env["logbrew.trace"] if env.respond_to?(:[])
+      trace.is_a?(TraceContext) ? trace : Trace.current
+    end
+  end
+
+  module TraceRailsErrorSubscriberMethods
+    private
+
+    def rails_metadata(error, handled, severity, context, source)
+      Trace.add_metadata(super)
+    end
+  end
+
+  Client.prepend(TraceClientMethods)
+  Logger.prepend(TraceLoggerMethods)
+  RackMiddleware.prepend(TraceRackMiddlewareMethods)
+  RailsErrorSubscriber.prepend(TraceRailsErrorSubscriberMethods)
+end

data/lib/logbrew/traceparent.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module LogBrew
+  TraceparentContext = Struct.new(:version, :trace_id, :parent_span_id, :trace_flags, :sampled, keyword_init: true)
+  TraceparentSpanInput = Struct.new(:name, :span_id, :status, :duration_ms, :metadata, keyword_init: true) do
+    def initialize(name:, span_id:, status: "ok", duration_ms: nil, metadata: nil)
+      super(
+        name: name,
+        span_id: span_id,
+        status: status,
+        duration_ms: duration_ms,
+        metadata: metadata
+      )
+    end
+  end
+
+  # Dependency-free W3C traceparent helpers for explicit app-owned propagation.
+  module Traceparent
+    VERSION = "00"
+    private_constant :VERSION
+
+    module_function
+
+    def parse(traceparent)
+      Validation.require_non_empty("traceparent", traceparent)
+      parts = traceparent.to_s.strip.downcase.split("-")
+      raise SdkError.new("validation_error", "traceparent must have four fields") unless parts.length == 4
+
+      version, trace_id, parent_span_id, trace_flags = parts
+      require_version(version)
+      require_trace_id(trace_id)
+      require_span_id("traceparent parent span id", parent_span_id)
+      flags = normalize_trace_flags(trace_flags)
+
+      TraceparentContext.new(
+        version: version,
+        trace_id: trace_id,
+        parent_span_id: parent_span_id,
+        trace_flags: flags,
+        sampled: (flags.to_i(16) & 1) == 1
+      )
+    end
+
+    def create(trace_id:, span_id:, trace_flags: "01")
+      normalized_trace_id = normalize_trace_id(trace_id)
+      normalized_span_id = normalize_span_id("traceparent span id", span_id)
+      flags = normalize_trace_flags(trace_flags)
+
+      "#{VERSION}-#{normalized_trace_id}-#{normalized_span_id}-#{flags}"
+    end
+
+    def create_headers(trace_id:, span_id:, trace_flags: "01")
+      { "traceparent" => create(trace_id: trace_id, span_id: span_id, trace_flags: trace_flags) }
+    end
+
+    def span_attributes_from_traceparent(traceparent, input)
+      context = traceparent.is_a?(TraceparentContext) ? traceparent : parse(traceparent)
+      attributes = {
+        "name" => required_name(input.name),
+        "traceId" => context.trace_id,
+        "spanId" => normalize_span_id("span spanId", input.span_id),
+        "parentSpanId" => context.parent_span_id,
+        "status" => normalize_status(input.status)
+      }
+
+      unless input.duration_ms.nil?
+        duration_ms = Validation.require_finite_number("span durationMs", input.duration_ms)
+        raise SdkError.new("validation_error", "span durationMs must be non-negative") if duration_ms.negative?
+
+        attributes["durationMs"] = duration_ms
+      end
+
+      metadata = Validation.require_metadata(input.metadata)
+      attributes["metadata"] = metadata unless metadata.nil?
+      attributes
+    end
+
+    def require_version(version)
+      unless version.length == 2 && lower_hex?(version) && version != "ff"
+        raise SdkError.new("validation_error", "traceparent version must be two hex characters and not ff")
+      end
+    end
+    private_class_method :require_version
+
+    def normalize_trace_id(trace_id)
+      normalized = trace_id.to_s.strip.downcase
+      require_trace_id(normalized)
+      normalized
+    end
+    private_class_method :normalize_trace_id
+
+    def require_trace_id(trace_id)
+      unless trace_id.length == 32 && lower_hex?(trace_id) && !all_zero?(trace_id)
+        raise SdkError.new("validation_error", "traceparent trace id must be 32 non-zero hex characters")
+      end
+    end
+    private_class_method :require_trace_id
+
+    def normalize_span_id(label, span_id)
+      normalized = span_id.to_s.strip.downcase
+      require_span_id(label, normalized)
+      normalized
+    end
+    private_class_method :normalize_span_id
+
+    def require_span_id(label, span_id)
+      unless span_id.length == 16 && lower_hex?(span_id) && !all_zero?(span_id)
+        raise SdkError.new("validation_error", "#{label} must be 16 non-zero hex characters")
+      end
+    end
+    private_class_method :require_span_id
+
+    def normalize_trace_flags(trace_flags)
+      normalized = trace_flags.to_s.strip.downcase
+      unless normalized.length == 2 && lower_hex?(normalized)
+        raise SdkError.new("validation_error", "traceparent flags must be two hex characters")
+      end
+
+      normalized
+    end
+    private_class_method :normalize_trace_flags
+
+    def required_name(name)
+      Validation.require_non_empty("span name", name)
+      name.to_s.strip
+    end
+    private_class_method :required_name
+
+    def normalize_status(status)
+      Validation.require_allowed_value("span status", status, LogBrew::SPAN_STATUSES)
+      status
+    end
+    private_class_method :normalize_status
+
+    def lower_hex?(value)
+      value.match?(/\A[0-9a-f]+\z/)
+    end
+    private_class_method :lower_hex?
+
+    def all_zero?(value)
+      value.delete("0").empty?
+    end
+    private_class_method :all_zero?
+  end
+end

data/lib/logbrew/worker_lifecycle.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+module LogBrew
+  # Content-free delivery details safe for application-owned diagnostics.
+  class WorkerDeliveryFailure
+    attr_reader :stage, :code, :pending_events, :pending_event_bytes, :dropped_events
+
+    def initialize(stage:, code:, pending_events:, pending_event_bytes:, dropped_events:)
+      @stage = stage.dup.freeze
+      @code = code.dup.freeze
+      @pending_events = pending_events
+      @pending_event_bytes = pending_event_bytes
+      @dropped_events = dropped_events
+      freeze
+    end
+  end
+
+  # Explicit delivery boundaries for serialized prefork worker loops.
+  class WorkerLifecycle
+    SAFE_DELIVERY_CODES = %w[
+      delivery_error
+      flush_error
+      network_failure
+      shutdown_error
+      transport_error
+      unauthenticated
+      validation_error
+    ].freeze
+
+    def self.create(client:, transport:, on_delivery_failure: nil)
+      unless client.is_a?(Client)
+        raise SdkError.new("validation_error", "client must be a LogBrew::Client")
+      end
+      unless transport.respond_to?(:send)
+        raise SdkError.new("validation_error", "transport must respond to send")
+      end
+      if !on_delivery_failure.nil? && !on_delivery_failure.respond_to?(:call)
+        raise SdkError.new("validation_error", "on_delivery_failure must be callable")
+      end
+
+      new(
+        client: client,
+        transport: transport,
+        on_delivery_failure: on_delivery_failure,
+        owner_process_id: current_process_id
+      )
+    end
+
+    def self.current_process_id
+      process_id = Process.pid
+      unless process_id.is_a?(Integer) && process_id.positive?
+        raise SdkError.new("process_ownership_error", "worker process identity is unavailable")
+      end
+
+      process_id
+    end
+    private_class_method :current_process_id
+
+    def initialize(client:, transport:, on_delivery_failure:, owner_process_id:)
+      @client = client
+      @transport = transport
+      @on_delivery_failure = on_delivery_failure
+      @owner_process_id = owner_process_id
+      @state_mutex = Mutex.new
+      @operation_active = false
+      @shutdown_response = nil
+    end
+    private_class_method :new
+
+    def run
+      assert_process_ownership
+      begin_run
+      begin
+        application_error = nil
+        result = nil
+        begin
+          result = yield
+        rescue Exception => error # rubocop:disable Lint/RescueException
+          application_error = error
+        ensure
+          finish_work_boundary(application_error)
+        end
+
+        raise application_error unless application_error.nil?
+
+        result
+      ensure
+        end_operation
+      end
+    end
+
+    def shutdown
+      assert_process_ownership
+      cached_response = begin_shutdown
+      return cached_response unless cached_response.nil?
+
+      completed = false
+      begin
+        begin
+          response = @client.shutdown(@transport)
+        rescue StandardError => delivery_error
+          report_delivery_failure("shutdown", delivery_error)
+          raise delivery_error
+        end
+
+        complete_shutdown(response)
+        completed = true
+        response
+      ensure
+        end_operation unless completed
+      end
+    end
+
+    private
+
+    def begin_run
+      @state_mutex.synchronize do
+        raise SdkError.new("shutdown_error", "worker lifecycle is already shut down") unless @shutdown_response.nil?
+
+        claim_operation
+      end
+    end
+
+    def begin_shutdown
+      @state_mutex.synchronize do
+        return @shutdown_response unless @shutdown_response.nil?
+
+        claim_operation
+        nil
+      end
+    end
+
+    def claim_operation
+      if @operation_active
+        raise SdkError.new("worker_lifecycle_error", "worker lifecycle operation is already in progress")
+      end
+
+      @operation_active = true
+    end
+
+    def complete_shutdown(response)
+      @state_mutex.synchronize do
+        @shutdown_response = response
+        @operation_active = false
+      end
+    end
+
+    def end_operation
+      if current_process_id == @owner_process_id
+        @state_mutex.synchronize { @operation_active = false }
+      else
+        # An inherited lifecycle is permanently unusable in the child.
+        @operation_active = false
+      end
+    end
+
+    def assert_process_ownership
+      return if current_process_id == @owner_process_id
+
+      raise SdkError.new(
+        "process_ownership_error",
+        "worker lifecycle must be created in the current process"
+      )
+    end
+
+    def finish_work_boundary(application_error)
+      begin
+        assert_process_ownership
+      rescue SdkError => ownership_error
+        raise application_error unless application_error.nil?
+
+        raise ownership_error
+      end
+
+      begin
+        @client.flush(@transport)
+      rescue StandardError => delivery_error
+        report_delivery_failure("work_boundary", delivery_error)
+      end
+    end
+
+    def current_process_id
+      process_id = Process.pid
+      unless process_id.is_a?(Integer) && process_id.positive?
+        raise SdkError.new("process_ownership_error", "worker process identity is unavailable")
+      end
+
+      process_id
+    end
+
+    def report_delivery_failure(stage, error)
+      return if @on_delivery_failure.nil?
+
+      code = if error.is_a?(SdkError) && SAFE_DELIVERY_CODES.include?(error.code)
+               error.code
+             else
+               "delivery_error"
+             end
+      notice = WorkerDeliveryFailure.new(
+        stage: stage,
+        code: code,
+        pending_events: @client.pending_events,
+        pending_event_bytes: @client.pending_event_bytes,
+        dropped_events: @client.dropped_events
+      )
+      @on_delivery_failure.call(notice)
+    rescue StandardError
+      nil
+    end
+  end
+end