logbrew-sdk 0.1.0 → 0.1.1

data/lib/logbrew/operation_tracing.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module LogBrew
+  # Explicit dependency spans for app-owned database, cache, and queue work.
+  module OperationTracing
+    UNSAFE_METADATA_PATTERNS = [
+      /authorization/i,
+      /body/i,
+      /broker/i,
+      /cache.?key/i,
+      /command/i,
+      /connection/i,
+      /cookie/i,
+      /dsn/i,
+      /header/i,
+      /host/i,
+      /\bjid\z/i,
+      /job.?id/i,
+      /key/i,
+      /message/i,
+      /param/i,
+      /pass#{'word'}/i,
+      /payload/i,
+      /query/i,
+      /sec#{'ret'}/i,
+      /sql/i,
+      /statement/i,
+      /to#{'ken'}/i,
+      /url/i,
+      /username/i,
+      /value/i
+    ].freeze
+    private_constant :UNSAFE_METADATA_PATTERNS
+
+    module_function
+
+    def database_operation(client, name, **options, &block)
+      capture_operation(client, "database", name, options, &block)
+    end
+
+    def cache_operation(client, name, **options, &block)
+      capture_operation(client, "cache", name, options, &block)
+    end
+
+    def queue_operation(client, name, **options, &block)
+      capture_operation(client, "queue", name, options, &block)
+    end
+
+    def capture_operation(client, kind, name, options)
+      raise SdkError.new("validation_error", "#{kind} operation block is required") unless block_given?
+
+      Validation.require_non_empty("#{kind} operation name", name)
+      started_at = monotonic_time
+      context = child_context
+      error = nil
+      result = nil
+
+      Trace.with_context(context) do
+        begin
+          result = yield context
+        rescue StandardError => captured
+          error = captured
+        end
+      end
+
+      capture_span(client, kind, name, context, started_at, options, error)
+      raise error if error
+
+      result
+    end
+
+    def capture_span(client, kind, name, context, started_at, options, error)
+      client.span(
+        event_id(kind, context, options),
+        timestamp(options),
+        {
+          name: "#{kind}.operation:#{name}",
+          traceId: context.trace_id,
+          spanId: context.span_id,
+          parentSpanId: context.parent_span_id,
+          status: error ? "error" : "ok",
+          durationMs: duration_ms(started_at, options),
+          metadata: span_metadata(kind, options, error)
+        }
+      )
+    rescue StandardError => capture_error
+      on_error = read_option(options, :on_error)
+      begin
+        on_error.call(capture_error) if on_error.respond_to?(:call)
+      rescue StandardError
+        nil
+      end
+    end
+
+    def child_context
+      parent = Trace.current
+      return Trace.create_root unless parent
+
+      Trace.create(
+        trace_id: parent.trace_id,
+        span_id: generate_span_id,
+        parent_span_id: parent.span_id,
+        trace_flags: parent.trace_flags
+      )
+    end
+
+    def span_metadata(kind, options, error)
+      sanitized_metadata(read_option(options, :metadata)).tap do |metadata|
+        metadata["source"] = "#{kind}.operation"
+        add_option(metadata, "#{kind}.system", read_option(options, :system))
+        add_option(metadata, "#{kind}.operation", read_option(options, :operation))
+        add_option(metadata, "#{kind}.target", read_option(options, :target))
+        metadata["exceptionType"] = error.class.name if error
+      end
+    end
+
+    def sanitized_metadata(metadata)
+      return {} if metadata.nil?
+      raise SdkError.new("validation_error", "operation metadata must be an object") unless metadata.is_a?(Hash)
+
+      metadata.each_with_object({}) do |(key, value), copied|
+        normalized_key = key.to_s
+        next if normalized_key.strip.empty?
+        next if unsafe_metadata_key?(normalized_key)
+        next unless primitive_metadata_value?(value)
+
+        copied[normalized_key] = value
+      end
+    end
+
+    def unsafe_metadata_key?(key)
+      UNSAFE_METADATA_PATTERNS.any? { |pattern| key.match?(pattern) }
+    end
+
+    def primitive_metadata_value?(value)
+      return true if value.nil? || value == true || value == false
+      return true if value.is_a?(String) || value.is_a?(Integer)
+
+      value.is_a?(Float) && value.finite?
+    end
+
+    def add_option(metadata, key, value)
+      metadata[key] = value if primitive_metadata_value?(value) && !(value.is_a?(String) && value.strip.empty?)
+    end
+
+    def read_option(options, key)
+      options[key] || options[key.to_s]
+    end
+
+    def event_id(kind, context, options)
+      read_option(options, :event_id) || "ruby_#{kind}_span_#{context.span_id}"
+    end
+
+    def timestamp(options)
+      value = read_option(options, :timestamp)
+      return value unless value.nil?
+
+      Time.now.utc.iso8601
+    end
+
+    def duration_ms(started_at, options)
+      configured = read_option(options, :duration_ms)
+      return configured unless configured.nil?
+
+      ((monotonic_time - started_at) * 1000.0).round(3)
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def generate_span_id
+      loop do
+        value = SecureRandom.hex(8)
+        return value unless value.delete("0").empty?
+      end
+    end
+  end
+end

data/lib/logbrew/product_timeline.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module LogBrew
+  # Builders for app-owned product and network timeline action events.
+  class ProductTimeline
+    private_class_method :new
+
+    def self.product_action(
+      name:,
+      status: "success",
+      route_template: nil,
+      session_id: nil,
+      trace_id: nil,
+      screen: nil,
+      funnel: nil,
+      step: nil,
+      metadata: nil
+    )
+      action_metadata = timeline_metadata("product_timeline", metadata)
+      put_if_present(action_metadata, "routeTemplate", sanitize_optional_route_template("product route_template", route_template))
+      put_if_present(action_metadata, "sessionId", optional_label("session_id", session_id))
+      put_if_present(action_metadata, "traceId", optional_label("trace_id", trace_id))
+      put_if_present(action_metadata, "screen", optional_label("screen", screen))
+      put_if_present(action_metadata, "funnel", optional_label("funnel", funnel))
+      put_if_present(action_metadata, "step", optional_label("step", step))
+
+      {
+        "name" => required_label("product action name", name),
+        "status" => normalize_status(status),
+        "metadata" => action_metadata
+      }
+    end
+
+    def self.network_milestone(
+      route_template:,
+      method: "GET",
+      status_code: nil,
+      duration_ms: nil,
+      status: nil,
+      name: nil,
+      session_id: nil,
+      trace_id: nil,
+      metadata: nil
+    )
+      route = sanitize_route_template("network milestone route_template", route_template)
+      normalized_method = normalize_method(method)
+      validate_status_code(status_code)
+      validate_duration_ms(duration_ms)
+      normalized_status = normalize_status(status || (status_code && status_code >= 400 ? "failure" : "success"))
+
+      action_metadata = timeline_metadata("network_timeline", metadata)
+      action_metadata["routeTemplate"] = route
+      action_metadata["method"] = normalized_method
+      put_if_present(action_metadata, "statusCode", status_code)
+      put_if_present(action_metadata, "durationMs", duration_ms)
+      put_if_present(action_metadata, "sessionId", optional_label("session_id", session_id))
+      put_if_present(action_metadata, "traceId", optional_label("trace_id", trace_id))
+
+      {
+        "name" => name.nil? ? "network.#{normalized_method.downcase} #{route}" : required_label("network milestone name", name),
+        "status" => normalized_status,
+        "metadata" => action_metadata
+      }
+    end
+
+    def self.timeline_metadata(source, metadata)
+      copied = { "source" => source }
+      validated = Validation.require_metadata(metadata)
+      return copied if validated.nil?
+
+      validated.each do |key, value|
+        copied[key] = value unless key == "source"
+      end
+      copied
+    end
+
+    def self.required_label(label, value)
+      Validation.require_non_empty(label, value)
+      value.to_s.strip
+    end
+
+    def self.optional_label(label, value)
+      return nil if value.nil?
+
+      required_label(label, value)
+    end
+
+    def self.normalize_status(status)
+      Validation.require_allowed_value("action status", status, LogBrew::ACTION_STATUSES)
+      status
+    end
+
+    def self.sanitize_optional_route_template(label, route_template)
+      return nil if route_template.nil?
+
+      sanitize_route_template(label, route_template)
+    end
+
+    def self.sanitize_route_template(label, route_template)
+      Validation.require_non_empty(label, route_template)
+      trimmed = route_template.to_s.strip
+      if trimmed.match?(/\Ahttps?:\/\//i)
+        uri = URI.parse(trimmed)
+        return uri.path.nil? || uri.path.empty? ? "/" : uri.path
+      end
+
+      cutoff = first_present_index(trimmed.index("?"), trimmed.index("#"))
+      cutoff.nil? ? trimmed : (trimmed[0...cutoff].rstrip.empty? ? "/" : trimmed[0...cutoff].rstrip)
+    rescue URI::InvalidURIError => error
+      raise SdkError.new("validation_error", "route_template must be a valid route or URL: #{error.message}")
+    end
+
+    def self.normalize_method(method)
+      normalized = method.to_s.strip.upcase
+      unless normalized.match?(/\A[A-Z0-9_-]+\z/)
+        raise SdkError.new("validation_error", "network milestone method must be a valid HTTP method")
+      end
+
+      normalized
+    end
+
+    def self.validate_status_code(status_code)
+      return if status_code.nil?
+
+      unless status_code.is_a?(Integer) && status_code >= 100 && status_code <= 599
+        raise SdkError.new("validation_error", "network milestone status_code must be between 100 and 599")
+      end
+    end
+
+    def self.validate_duration_ms(duration_ms)
+      return if duration_ms.nil?
+      unless duration_ms.is_a?(Numeric) && duration_ms.finite?
+        raise SdkError.new("validation_error", "network milestone duration_ms must be a finite number")
+      end
+      raise SdkError.new("validation_error", "network milestone duration_ms must be non-negative") if duration_ms.negative?
+    end
+
+    def self.put_if_present(metadata, key, value)
+      metadata[key] = value unless value.nil?
+    end
+
+    def self.first_present_index(first, second)
+      return second if first.nil?
+      return first if second.nil?
+
+      [first, second].min
+    end
+
+    private_class_method :timeline_metadata, :required_label, :optional_label, :normalize_status,
+                         :sanitize_optional_route_template, :sanitize_route_template, :normalize_method,
+                         :validate_status_code, :validate_duration_ms, :put_if_present, :first_present_index
+  end
+end

data/lib/logbrew/support_ticket.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module LogBrew
+  # Local-only support-ticket payload drafts for explicit user or agent handoff.
+  module SupportTicketDraft
+    SOURCES = %w[cli sdk website docs mobile].freeze
+    CATEGORIES = %w[
+      sdk_install_failure
+      ingest_failure
+      auth_failure
+      project_setup
+      dashboard_issue
+      docs_confusion
+      cli_issue
+      mobile_issue
+      billing_question
+      other
+    ].freeze
+    SENSITIVE_KEY_MARKERS = %w[
+      apikey
+      auth
+      authorization
+      authtoken
+      bearer
+      clientsecret
+      connectionstring
+      cookie
+      credential
+      dsn
+      email
+      errormessage
+      exceptionmessage
+      password
+      passwd
+      privatekey
+      refreshtoken
+      secret
+      session
+      setcookie
+      stacktrace
+      token
+      traceback
+    ].freeze
+    REDACTED = "[redacted]"
+    MAX_DEPTH = 5
+    MAX_ARRAY_LENGTH = 20
+    MAX_STRING_LENGTH = 500
+
+    module_function
+
+    def create(source:, category:, title:, description:, **options)
+      Validation.require_allowed_value("support ticket source", source, SOURCES)
+      Validation.require_allowed_value("support ticket category", category, CATEGORIES)
+
+      draft = {
+        "source" => source,
+        "category" => category,
+        "title" => required_string("support ticket title", title),
+        "description" => required_string("support ticket description", description)
+      }
+      add_optional_string(draft, "project_id", options[:project_id])
+      add_optional_string(draft, "environment", options[:environment])
+      add_optional_string(draft, "runtime", options[:runtime])
+      add_optional_string(draft, "framework", options[:framework])
+      add_optional_string(draft, "sdk_package", options[:sdk_package])
+      add_optional_string(draft, "sdk_version", options[:sdk_version])
+      add_optional_string(draft, "release", options[:release])
+      add_trace_id(draft, options[:trace_id])
+      add_optional_string(draft, "event_id", options[:event_id])
+      add_diagnostics(draft, options[:diagnostics]) if options.key?(:diagnostics)
+      draft
+    end
+
+    def required_string(label, value)
+      Validation.require_non_empty(label, value)
+      value.strip
+    end
+    private_class_method :required_string
+
+    def add_optional_string(draft, key, value)
+      return if value.nil?
+
+      draft[key] = required_string("support ticket #{key}", value)
+    end
+    private_class_method :add_optional_string
+
+    def add_trace_id(draft, value)
+      return if value.nil?
+
+      normalized = value.to_s.strip.downcase
+      unless normalized.match?(/\A[0-9a-f]{32}\z/) && !normalized.delete("0").empty?
+        raise SdkError.new("validation_error", "support ticket trace_id must be 32 non-zero hex characters")
+      end
+      draft["trace_id"] = normalized
+    end
+    private_class_method :add_trace_id
+
+    def add_diagnostics(draft, diagnostics)
+      unless diagnostics.is_a?(Hash)
+        raise SdkError.new("validation_error", "support ticket diagnostics must be an object")
+      end
+
+      sanitized = sanitize_diagnostic_hash(diagnostics, 0)
+      draft["diagnostics"] = sanitized unless sanitized.empty?
+    end
+    private_class_method :add_diagnostics
+
+    def sanitize_diagnostic_hash(value, depth)
+      value.each_with_object({}) do |(key, child), safe|
+        break safe if safe.length >= MAX_ARRAY_LENGTH
+
+        normalized_key = key.to_s
+        next if normalized_key.strip.empty?
+
+        sanitized = if sensitive_key?(normalized_key)
+                      REDACTED
+                    else
+                      sanitize_diagnostic_value(child, depth + 1)
+                    end
+        safe[normalized_key] = sanitized unless sanitized.nil?
+      end
+    end
+    private_class_method :sanitize_diagnostic_hash
+
+    def sanitize_diagnostic_value(value, depth)
+      return { "type" => value.class.name } if value.is_a?(Exception)
+      return nil if depth > MAX_DEPTH
+
+      case value
+      when nil, true, false, String, Integer
+        sanitize_primitive(value)
+      when Float
+        value.finite? ? value : nil
+      when Hash
+        sanitize_diagnostic_hash(value, depth)
+      when Array
+        value.first(MAX_ARRAY_LENGTH).map { |item| sanitize_diagnostic_value(item, depth + 1) }.compact
+      else
+        nil
+      end
+    end
+    private_class_method :sanitize_diagnostic_value
+
+    def sanitize_primitive(value)
+      return value unless value.is_a?(String)
+
+      text = value.strip
+      return "" if text.empty?
+      return REDACTED if sensitive_string?(text)
+
+      redacted = redact_url(redact_local_path(text))
+      redacted.length > MAX_STRING_LENGTH ? "#{redacted[0, MAX_STRING_LENGTH]}..." : redacted
+    end
+    private_class_method :sanitize_primitive
+
+    def sensitive_key?(key)
+      normalized = key.downcase.gsub(/[^a-z0-9]/, "")
+      SENSITIVE_KEY_MARKERS.any? { |marker| normalized.include?(marker) }
+    end
+    private_class_method :sensitive_key?
+
+    def sensitive_string?(value)
+      value.match?(/(?:authorization|api[_-]?key|token|secret|password|passwd|cookie)\s*[:=]/i) ||
+        value.match?(/\bBearer\s+[A-Za-z0-9._~+\/=-]+/i) ||
+        value.match?(/\blbw_(?:ingest|client|api)_[A-Za-z0-9._-]+/i) ||
+        value.match?(/\b(?:github_pat|ghp|gho|npm|pypi|sk_live|sk_test|xox[baprs]|AKIA)[A-Za-z0-9._-]+/)
+    end
+    private_class_method :sensitive_string?
+
+    def redact_local_path(value)
+      return "[redacted-path]" if value.match?(/\A(?:\/Users\/|\/home\/|\/var\/folders\/|[A-Za-z]:\\)/)
+
+      value
+    end
+    private_class_method :redact_local_path
+
+    def redact_url(value)
+      uri = URI.parse(value)
+      return "[redacted-url]#{uri.path.empty? ? '/' : uri.path}" if uri.is_a?(URI::HTTP) && uri.host
+
+      value.split(/[?#]/, 2)[0]
+    rescue URI::InvalidURIError
+      value.split(/[?#]/, 2)[0]
+    end
+    private_class_method :redact_url
+  end
+end