pingops 0.0.1

data/lib/pingops/core/constants.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Pingops
+  module Core
+    # Constants used throughout the SDK
+    module Constants
+      # Tracer identification
+      TRACER_NAME = 'pingops-sdk'
+      TRACER_VERSION = '0.0.1'
+
+      # Root span name for startTrace
+      ROOT_SPAN_NAME = 'pingops-trace'
+
+      # Default sizes and timeouts
+      DEFAULT_MAX_REQUEST_BODY_SIZE = 4096
+      DEFAULT_MAX_RESPONSE_BODY_SIZE = 4096
+      DEFAULT_BATCH_SIZE = 50
+      DEFAULT_BATCH_TIMEOUT = 5000
+      DEFAULT_EXPORT_TIMEOUT = 5000
+
+      # Export modes
+      EXPORT_MODE_BATCHED = 'batched'
+      EXPORT_MODE_IMMEDIATE = 'immediate'
+
+      # Context key names
+      CONTEXT_KEY_TRACE_ID = 'pingops-trace-id'
+      CONTEXT_KEY_USER_ID = 'pingops-user-id'
+      CONTEXT_KEY_SESSION_ID = 'pingops-session-id'
+      CONTEXT_KEY_TAGS = 'pingops-tags'
+      CONTEXT_KEY_METADATA = 'pingops-metadata'
+      CONTEXT_KEY_CAPTURE_REQUEST_BODY = 'pingops-capture-request-body'
+      CONTEXT_KEY_CAPTURE_RESPONSE_BODY = 'pingops-capture-response-body'
+
+      # Span attribute names
+      ATTR_PINGOPS_TRACE_ID = 'pingops.trace_id'
+      ATTR_PINGOPS_USER_ID = 'pingops.user_id'
+      ATTR_PINGOPS_SESSION_ID = 'pingops.session_id'
+      ATTR_PINGOPS_TAGS = 'pingops.tags'
+      ATTR_PINGOPS_METADATA_PREFIX = 'pingops.metadata.'
+
+      ATTR_HTTP_REQUEST_BODY = 'http.request.body'
+      ATTR_HTTP_RESPONSE_BODY = 'http.response.body'
+      ATTR_HTTP_RESPONSE_CONTENT_ENCODING = 'http.response.content_encoding'
+      ATTR_HTTP_REQUEST_HEADER_PREFIX = 'http.request.header.'
+      ATTR_HTTP_RESPONSE_HEADER_PREFIX = 'http.response.header.'
+
+      # HTTP attributes for eligibility checking
+      ATTR_HTTP_METHOD = 'http.method'
+      ATTR_HTTP_REQUEST_METHOD = 'http.request.method'
+      ATTR_HTTP_URL = 'http.url'
+      ATTR_URL_FULL = 'url.full'
+      ATTR_SERVER_ADDRESS = 'server.address'
+      ATTR_SERVER_PORT = 'server.port'
+      ATTR_HTTP_STATUS_CODE = 'http.response.status_code'
+
+      # Compressed body encodings
+      COMPRESSED_ENCODINGS = %w[gzip br deflate x-gzip x-deflate].freeze
+
+      # Default sensitive header patterns (case-insensitive, substring match)
+      DEFAULT_SENSITIVE_HEADER_PATTERNS = %w[
+        authorization
+        www-authenticate
+        proxy-authenticate
+        proxy-authorization
+        x-auth-token
+        x-api-key
+        x-api-token
+        x-access-token
+        x-auth-user
+        x-auth-password
+        x-csrf-token
+        x-xsrf-token
+        api-key
+        apikey
+        api_key
+        access-key
+        accesskey
+        access_key
+        secret-key
+        secretkey
+        secret_key
+        private-key
+        privatekey
+        private_key
+        cookie
+        set-cookie
+        session-id
+        sessionid
+        session_id
+        session-token
+        sessiontoken
+        session_token
+        oauth-token
+        oauth_token
+        oauth2-token
+        oauth2_token
+        bearer
+        x-amz-security-token
+        x-amz-signature
+        x-aws-access-key
+        x-aws-secret-key
+        x-aws-session-token
+        x-password
+        x-secret
+        x-token
+        x-jwt
+        x-jwt-token
+        x-refresh-token
+        x-client-secret
+        x-client-id
+        x-user-token
+        x-service-key
+      ].freeze
+
+      # Redaction strategies
+      REDACTION_STRATEGY_REPLACE = 'replace'
+      REDACTION_STRATEGY_PARTIAL = 'partial'
+      REDACTION_STRATEGY_PARTIAL_END = 'partial_end'
+      REDACTION_STRATEGY_REMOVE = 'remove'
+
+      # Default redaction settings
+      DEFAULT_REDACTION_STRING = '[REDACTED]'
+      DEFAULT_VISIBLE_CHARS = 4
+    end
+  end
+end

data/lib/pingops/core/context_keys.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'opentelemetry-api'
+
+module Pingops
+  module Core
+    # Context keys for propagating PingOps attributes through OpenTelemetry context
+    module ContextKeys
+      # Create OpenTelemetry context keys for PingOps attributes
+      TRACE_ID_KEY = OpenTelemetry::Context.create_key(Constants::CONTEXT_KEY_TRACE_ID)
+      USER_ID_KEY = OpenTelemetry::Context.create_key(Constants::CONTEXT_KEY_USER_ID)
+      SESSION_ID_KEY = OpenTelemetry::Context.create_key(Constants::CONTEXT_KEY_SESSION_ID)
+      TAGS_KEY = OpenTelemetry::Context.create_key(Constants::CONTEXT_KEY_TAGS)
+      METADATA_KEY = OpenTelemetry::Context.create_key(Constants::CONTEXT_KEY_METADATA)
+      CAPTURE_REQUEST_BODY_KEY = OpenTelemetry::Context.create_key(Constants::CONTEXT_KEY_CAPTURE_REQUEST_BODY)
+      CAPTURE_RESPONSE_BODY_KEY = OpenTelemetry::Context.create_key(Constants::CONTEXT_KEY_CAPTURE_RESPONSE_BODY)
+
+      class << self
+        # Set trace attributes on a context
+        # @param context [OpenTelemetry::Context] The context to modify
+        # @param attributes [TraceAttributes, nil] The attributes to set
+        # @return [OpenTelemetry::Context] The modified context
+        def set_attributes(context, attributes)
+          return context if attributes.nil?
+
+          ctx = context
+          ctx = ctx.set_value(TRACE_ID_KEY, attributes.trace_id) if attributes.trace_id
+          ctx = ctx.set_value(USER_ID_KEY, attributes.user_id) if attributes.user_id
+          ctx = ctx.set_value(SESSION_ID_KEY, attributes.session_id) if attributes.session_id
+          ctx = ctx.set_value(TAGS_KEY, attributes.tags) if attributes.tags
+          ctx = ctx.set_value(METADATA_KEY, attributes.metadata) if attributes.metadata
+
+          unless attributes.capture_request_body.nil?
+            ctx = ctx.set_value(CAPTURE_REQUEST_BODY_KEY, attributes.capture_request_body)
+          end
+
+          unless attributes.capture_response_body.nil?
+            ctx = ctx.set_value(CAPTURE_RESPONSE_BODY_KEY, attributes.capture_response_body)
+          end
+
+          ctx
+        end
+
+        # Set the trace ID on a context
+        # @param context [OpenTelemetry::Context] The context to modify
+        # @param trace_id [String] The trace ID
+        # @return [OpenTelemetry::Context] The modified context
+        def set_trace_id(context, trace_id)
+          context.set_value(TRACE_ID_KEY, trace_id)
+        end
+
+        # Extract all PingOps attributes from a context
+        # @param context [OpenTelemetry::Context] The context to read from
+        # @return [Hash] Hash of attribute name to value
+        def extract_attributes(context)
+          attributes = {}
+
+          trace_id = context.value(TRACE_ID_KEY)
+          attributes[Constants::ATTR_PINGOPS_TRACE_ID] = trace_id if trace_id
+
+          user_id = context.value(USER_ID_KEY)
+          attributes[Constants::ATTR_PINGOPS_USER_ID] = user_id if user_id
+
+          session_id = context.value(SESSION_ID_KEY)
+          attributes[Constants::ATTR_PINGOPS_SESSION_ID] = session_id if session_id
+
+          tags = context.value(TAGS_KEY)
+          attributes[Constants::ATTR_PINGOPS_TAGS] = tags if tags&.any?
+
+          metadata = context.value(METADATA_KEY)
+          if metadata.is_a?(Hash)
+            metadata.each do |key, value|
+              attributes["#{Constants::ATTR_PINGOPS_METADATA_PREFIX}#{key}"] = value.to_s if value
+            end
+          end
+
+          attributes
+        end
+
+        # Get capture request body setting from context
+        # @param context [OpenTelemetry::Context] The context to read from
+        # @return [Boolean, nil] The setting or nil if not set
+        def capture_request_body?(context)
+          context.value(CAPTURE_REQUEST_BODY_KEY)
+        end
+
+        # Get capture response body setting from context
+        # @param context [OpenTelemetry::Context] The context to read from
+        # @return [Boolean, nil] The setting or nil if not set
+        def capture_response_body?(context)
+          context.value(CAPTURE_RESPONSE_BODY_KEY)
+        end
+      end
+    end
+  end
+end

data/lib/pingops/core/domain_filter.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module Pingops
+  module Core
+    # Domain filtering for span eligibility
+    module DomainFilter
+      # Result of domain filter check
+      class Result
+        attr_reader :allowed, :matching_rule
+
+        def initialize(allowed:, matching_rule: nil)
+          @allowed = allowed
+          @matching_rule = matching_rule
+        end
+
+        def allowed?
+          @allowed
+        end
+
+        def denied?
+          !@allowed
+        end
+      end
+
+      class << self
+        # Check if a URL passes domain filtering
+        # @param url [String] The URL to check
+        # @param allow_list [Array<DomainRule>, nil] Domain allow list
+        # @param deny_list [Array<DomainRule>, nil] Domain deny list
+        # @return [Result] Filter result with allowed status and matching rule
+        def check(url, allow_list: nil, deny_list: nil)
+          return Result.new(allowed: true) if url.nil? || url.empty?
+
+          parsed = parse_url(url)
+          return Result.new(allowed: true) unless parsed
+
+          domain = parsed[:host]
+          path = parsed[:path] || '/'
+
+          # Step 1: Check deny list first
+          if deny_list&.any?
+            deny_list.each do |rule|
+              return Result.new(allowed: false, matching_rule: rule) if rule.matches_domain?(domain)
+            end
+          end
+
+          # Step 2: If no allow list, allow everything
+          return Result.new(allowed: true) if allow_list.nil? || allow_list.empty?
+
+          # Step 3: Check allow list
+          allow_list.each do |rule|
+            if rule.matches_domain?(domain)
+              # If rule has paths, check path match
+              if rule.paths.nil? || rule.paths.empty?
+                return Result.new(allowed: true, matching_rule: rule)
+              elsif rule.matches_path?(path)
+                return Result.new(allowed: true, matching_rule: rule)
+              end
+              # Continue to next rule if paths don't match
+            end
+          end
+
+          # No allow rule matched
+          Result.new(allowed: false)
+        end
+
+        # Extract URL from span attributes
+        # @param attributes [Hash] Span attributes
+        # @return [String, nil] The URL or nil
+        def extract_url(attributes)
+          url = attributes[Constants::ATTR_HTTP_URL] ||
+                attributes[Constants::ATTR_URL_FULL]
+
+          if url.nil? || url.empty?
+            server_address = attributes[Constants::ATTR_SERVER_ADDRESS]
+            if server_address && !server_address.empty?
+              port = attributes[Constants::ATTR_SERVER_PORT]
+              url = if port && port != 443 && port != 80
+                      "https://#{server_address}:#{port}"
+                    else
+                      "https://#{server_address}"
+                    end
+            end
+          end
+
+          url
+        end
+
+        # Find matching allow rule for a URL
+        # @param url [String] The URL to check
+        # @param allow_list [Array<DomainRule>, nil] Domain allow list
+        # @return [DomainRule, nil] The matching rule or nil
+        def find_matching_rule(url, allow_list)
+          return nil if url.nil? || url.empty? || allow_list.nil? || allow_list.empty?
+
+          parsed = parse_url(url)
+          return nil unless parsed
+
+          domain = parsed[:host]
+          path = parsed[:path] || '/'
+
+          allow_list.each do |rule|
+            next unless rule.matches_domain?(domain)
+            return rule if rule.paths.nil? || rule.paths.empty? || rule.matches_path?(path)
+          end
+
+          nil
+        end
+
+        private
+
+        def parse_url(url)
+          uri = URI.parse(url)
+          { host: uri.host&.downcase, path: uri.path }
+        rescue URI::InvalidURIError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/pingops/core/header_filter.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Pingops
+  module Core
+    # Header filtering and redaction
+    module HeaderFilter
+      class << self
+        # Filter and redact headers according to configuration
+        # @param headers [Hash] Headers to filter (name => value)
+        # @param allow_list [Array<String>, nil] Header names to include (case-insensitive)
+        # @param deny_list [Array<String>, nil] Header names to exclude (case-insensitive)
+        # @param redaction_config [HeaderRedactionConfig] Redaction configuration
+        # @return [Hash] Filtered and redacted headers
+        def filter(headers, allow_list: nil, deny_list: nil, redaction_config: nil)
+          return {} if headers.nil? || headers.empty?
+
+          redaction = redaction_config || HeaderRedactionConfig.new
+          result = {}
+
+          headers.each do |name, value|
+            normalized_name = name.to_s.downcase
+
+            # Step 1: Apply deny list (headers in deny list are removed)
+            next if deny_list&.any? { |h| h.downcase == normalized_name }
+
+            # Step 2: Apply allow list (only headers in allow list are kept)
+            next if allow_list && !allow_list.empty? && allow_list.none? { |h| h.downcase == normalized_name }
+
+            # Step 3: Apply redaction
+            redacted_value = redact_value(normalized_name, value, redaction)
+            result[name] = redacted_value unless redacted_value.nil?
+          end
+
+          result
+        end
+
+        # Filter span attributes to remove/redact headers
+        # @param attributes [Hash] Span attributes
+        # @param allow_list [Array<String>, nil] Header names to include
+        # @param deny_list [Array<String>, nil] Header names to exclude
+        # @param redaction_config [HeaderRedactionConfig] Redaction configuration
+        # @return [Hash] Filtered attributes
+        def filter_span_attributes(attributes, allow_list: nil, deny_list: nil, redaction_config: nil)
+          return {} if attributes.nil?
+
+          redaction = redaction_config || HeaderRedactionConfig.new
+          result = {}
+
+          attributes.each do |key, value|
+            key_str = key.to_s
+
+            # Check if this is a header attribute
+            if key_str.start_with?(Constants::ATTR_HTTP_REQUEST_HEADER_PREFIX)
+              header_name = key_str.sub(Constants::ATTR_HTTP_REQUEST_HEADER_PREFIX, '')
+              filtered_value = filter_header_value(header_name, value, allow_list, deny_list, redaction)
+              result[key] = filtered_value unless filtered_value.nil?
+            elsif key_str.start_with?(Constants::ATTR_HTTP_RESPONSE_HEADER_PREFIX)
+              header_name = key_str.sub(Constants::ATTR_HTTP_RESPONSE_HEADER_PREFIX, '')
+              filtered_value = filter_header_value(header_name, value, allow_list, deny_list, redaction)
+              result[key] = filtered_value unless filtered_value.nil?
+            else
+              # Not a header attribute, keep as-is
+              result[key] = value
+            end
+          end
+
+          result
+        end
+
+        private
+
+        def filter_header_value(header_name, value, allow_list, deny_list, redaction)
+          normalized_name = header_name.downcase
+
+          # Step 1: Deny list check
+          return nil if deny_list&.any? { |h| h.downcase == normalized_name }
+
+          # Step 2: Allow list check
+          return nil if allow_list && !allow_list.empty? && allow_list.none? { |h| h.downcase == normalized_name }
+
+          # Step 3: Redaction
+          redact_value(normalized_name, value, redaction)
+        end
+
+        def redact_value(header_name, value, redaction_config)
+          return value unless redaction_config.enabled
+          return value unless sensitive?(header_name, redaction_config.sensitive_patterns)
+
+          case redaction_config.strategy
+          when Constants::REDACTION_STRATEGY_REMOVE
+            nil
+          when Constants::REDACTION_STRATEGY_PARTIAL
+            partial_redact(value.to_s, redaction_config.visible_chars, redaction_config.redaction_string, :start)
+          when Constants::REDACTION_STRATEGY_PARTIAL_END
+            partial_redact(value.to_s, redaction_config.visible_chars, redaction_config.redaction_string, :end)
+          else # replace (default)
+            redaction_config.redaction_string
+          end
+        end
+
+        def sensitive?(header_name, patterns)
+          normalized = header_name.downcase
+          patterns.any? { |pattern| normalized.include?(pattern.downcase) }
+        end
+
+        def partial_redact(value, visible_chars, redaction_string, position)
+          return redaction_string if value.length <= visible_chars
+
+          case position
+          when :start
+            # Show first N chars + redaction string
+            "#{value[0, visible_chars]}#{redaction_string}"
+          when :end
+            # Redaction string + last N chars
+            "#{redaction_string}#{value[-visible_chars, visible_chars]}"
+          else
+            redaction_string
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pingops/core/id_generator.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'digest'
+
+module Pingops
+  module Core
+    # Generates trace IDs and span IDs according to the specification
+    module IdGenerator
+      class << self
+        # Generate a trace ID
+        # @param seed [String, nil] Optional seed for deterministic generation
+        # @return [String] 32 hex character trace ID (lowercase)
+        def generate_trace_id(seed = nil)
+          if seed
+            # Deterministic: first 32 hex chars of SHA-256(seed)
+            Digest::SHA256.hexdigest(seed)[0, 32]
+          else
+            # Random: 16 bytes as 32 hex chars
+            SecureRandom.hex(16)
+          end
+        end
+
+        # Generate a span ID
+        # @return [String] 16 hex character span ID (lowercase)
+        def generate_span_id
+          SecureRandom.hex(8)
+        end
+
+        # Validate trace ID format
+        # @param trace_id [String] The trace ID to validate
+        # @return [Boolean] True if valid format
+        def valid_trace_id?(trace_id)
+          return false if trace_id.nil?
+
+          trace_id.match?(/\A[0-9a-f]{32}\z/i)
+        end
+
+        # Validate span ID format
+        # @param span_id [String] The span ID to validate
+        # @return [Boolean] True if valid format
+        def valid_span_id?(span_id)
+          return false if span_id.nil?
+
+          span_id.match?(/\A[0-9a-f]{16}\z/i)
+        end
+
+        # Convert trace ID bytes to hex string
+        # @param bytes [String] 16 bytes
+        # @return [String] 32 hex character string
+        def bytes_to_trace_id(bytes)
+          bytes.unpack1('H*')
+        end
+
+        # Convert hex trace ID to bytes
+        # @param trace_id [String] 32 hex character string
+        # @return [String] 16 bytes
+        def trace_id_to_bytes(trace_id)
+          [trace_id].pack('H*')
+        end
+
+        # Convert span ID bytes to hex string
+        # @param bytes [String] 8 bytes
+        # @return [String] 16 hex character string
+        def bytes_to_span_id(bytes)
+          bytes.unpack1('H*')
+        end
+
+        # Convert hex span ID to bytes
+        # @param span_id [String] 16 hex character string
+        # @return [String] 8 bytes
+        def span_id_to_bytes(span_id)
+          [span_id].pack('H*')
+        end
+      end
+    end
+  end
+end

data/lib/pingops/core/span_eligibility.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Pingops
+  module Core
+    # Span eligibility checking for PingOps export
+    module SpanEligibility
+      class << self
+        # Check if a span is eligible for export to PingOps
+        # A span is eligible only if:
+        # - span.kind === SpanKind.CLIENT, and
+        # - At least one of http.method, http.request.method, http.url, or server.address is present
+        #
+        # @param span [OpenTelemetry::SDK::Trace::Span] The span to check
+        # @return [Boolean] True if eligible for export
+        def eligible?(span)
+          # Check kind is CLIENT
+          return false unless client_span?(span)
+
+          # Check for HTTP attributes
+          has_http_attributes?(span)
+        end
+
+        # Check if span is a CLIENT span
+        # @param span [OpenTelemetry::SDK::Trace::Span] The span to check
+        # @return [Boolean]
+        def client_span?(span)
+          span.kind == :client
+        end
+
+        # Check if span has HTTP attributes
+        # @param span [OpenTelemetry::SDK::Trace::Span] The span to check
+        # @return [Boolean]
+        def has_http_attributes?(span)
+          attrs = span_attributes(span)
+
+          attrs.key?(Constants::ATTR_HTTP_METHOD) ||
+            attrs.key?(Constants::ATTR_HTTP_REQUEST_METHOD) ||
+            attrs.key?(Constants::ATTR_HTTP_URL) ||
+            attrs.key?(Constants::ATTR_URL_FULL) ||
+            attrs.key?(Constants::ATTR_SERVER_ADDRESS)
+        end
+
+        private
+
+        def span_attributes(span)
+          # Handle both ReadableSpan and regular span
+          if span.respond_to?(:attributes)
+            span.attributes || {}
+          else
+            {}
+          end
+        end
+      end
+    end
+  end
+end