logbrew-sdk 0.1.2 → 0.1.4

data/lib/logbrew/telemetry_context.rb

@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+require "etc"
+require "rbconfig"
+
+module LogBrew
+  # Immutable schema-v1 resource, trace, session, subject, and tag context.
+  class TelemetryContext
+    SCHEMA_VERSION = 1
+    ROOT_FIELDS = %w[schemaVersion resource trace session subject tags].freeze
+    TRACE_FIELDS = %w[traceId spanId parentSpanId sampled].freeze
+    SESSION_FIELDS = %w[id previousId].freeze
+    SUBJECT_FIELDS = %w[id kind].freeze
+
+    def self.create
+      TelemetryContextBuilder.new
+    end
+
+    def self.from_hash(value = nil, **keywords)
+      if value.nil?
+        value = keywords
+      elsif !keywords.empty?
+        raise TelemetryContextValue.invalid("telemetry context must be one object")
+      end
+      object = TelemetryContextValue.object(value, "telemetry context")
+      TelemetryContextValue.reject_unknown_fields(object, ROOT_FIELDS, "telemetry context")
+      unless object["schemaVersion"] == SCHEMA_VERSION
+        raise TelemetryContextValue.invalid("telemetry context schemaVersion must be 1")
+      end
+
+      normalized = { "schemaVersion" => SCHEMA_VERSION }
+      if object.key?("resource")
+        normalized["resource"] = TelemetryResource.from_hash(object.fetch("resource")).to_h
+      end
+      normalized["trace"] = normalize_trace(object.fetch("trace")) if object.key?("trace")
+      normalized["session"] = normalize_session(object.fetch("session")) if object.key?("session")
+      normalized["subject"] = normalize_subject(object.fetch("subject")) if object.key?("subject")
+      normalized["tags"] = normalize_tags(object.fetch("tags")) if object.key?("tags")
+      if normalized.length == 1
+        raise TelemetryContextValue.invalid(
+          "telemetry context must include resource, trace, session, subject, or tags"
+        )
+      end
+
+      new(normalized)
+    end
+
+    # Resource fields and tags merge by field. Trace, session, and subject are replaced.
+    def self.merge(base, override)
+      require_context_or_nil(base, "base telemetry context")
+      require_context_or_nil(override, "override telemetry context")
+      return nil if base.nil? && override.nil?
+      return from_hash(override.to_h) if base.nil?
+      return from_hash(base.to_h) if override.nil?
+
+      base_value = base.to_h
+      override_value = override.to_h
+      merged = { "schemaVersion" => SCHEMA_VERSION }
+
+      base_resource = resource_from_value(base_value["resource"])
+      override_resource = resource_from_value(override_value["resource"])
+      resource = TelemetryResource.merge(base_resource, override_resource)
+      merged["resource"] = resource.to_h unless resource.nil?
+
+      %w[trace session subject].each do |section|
+        value = override_value[section] || base_value[section]
+        merged[section] = value unless value.nil?
+      end
+
+      base_tags = base_value["tags"] || {}
+      override_tags = override_value["tags"] || {}
+      unless base_tags.empty? && override_tags.empty?
+        tags = base_tags.merge(override_tags)
+        TelemetryContextValue.require_tag_count(tags.length)
+        merged["tags"] = tags.keys.sort.each_with_object({}) { |key, sorted| sorted[key] = tags.fetch(key) }
+      end
+
+      from_hash(merged)
+    end
+
+    # Add exact active trace correlation over any existing context.
+    def self.with_trace(context, trace)
+      require_context_or_nil(context, "telemetry context")
+      unless defined?(LogBrew::TraceContext) && trace.is_a?(LogBrew::TraceContext)
+        raise TelemetryContextValue.invalid("trace must be a LogBrew::TraceContext")
+      end
+
+      trace_context = create.with_trace(trace).build
+      merge(context, trace_context)
+    end
+
+    # Conservative Ruby runtime, OS-family/release, and architecture identity.
+    def self.runtime_defaults
+      runtime_name = defined?(RUBY_ENGINE) ? RUBY_ENGINE : "ruby"
+      resource = TelemetryResource.create.with_runtime(name: runtime_name, version: RUBY_VERSION)
+      uname = safe_uname
+      operating_system = normalize_os_name(
+        safe_runtime_value(uname && uname[:sysname]) ||
+          safe_runtime_value(RbConfig::CONFIG["host_os"])
+      )
+      operating_system_version = safe_runtime_value(uname && uname[:release])
+      architecture = safe_runtime_value(uname && uname[:machine]) ||
+                     safe_runtime_value(RbConfig::CONFIG["host_cpu"])
+      unless operating_system.nil?
+        resource.with_operating_system(name: operating_system, version: operating_system_version)
+      end
+      resource.with_device(architecture: architecture) unless architecture.nil?
+      create.with_resource(resource.build).build
+    end
+
+    def to_h
+      TelemetryContextValue.deep_copy(@value)
+    end
+
+    class << self
+      private
+
+      def normalize_trace(value)
+        object = TelemetryContextValue.object(value, "telemetry context trace")
+        TelemetryContextValue.reject_unknown_fields(object, TRACE_FIELDS, "telemetry context trace")
+        unless object.key?("traceId")
+          raise TelemetryContextValue.invalid("traceId must be 32 non-zero hex characters")
+        end
+
+        normalized = {
+          "traceId" => TelemetryContextValue.trace_id(object.fetch("traceId"))
+        }
+        if object.key?("spanId")
+          normalized["spanId"] = TelemetryContextValue.span_id(object.fetch("spanId"), "spanId")
+        end
+        if object.key?("parentSpanId")
+          normalized["parentSpanId"] = TelemetryContextValue.span_id(
+            object.fetch("parentSpanId"),
+            "parentSpanId"
+          )
+        end
+        if object.key?("sampled")
+          sampled = object.fetch("sampled")
+          unless sampled == true || sampled == false
+            raise TelemetryContextValue.invalid("sampled must be a boolean")
+          end
+          normalized["sampled"] = sampled
+        end
+        normalized
+      end
+
+      def normalize_session(value)
+        object = TelemetryContextValue.object(value, "telemetry context session")
+        TelemetryContextValue.reject_unknown_fields(object, SESSION_FIELDS, "telemetry context session")
+        unless object.key?("id")
+          raise TelemetryContextValue.invalid("session id must be a string")
+        end
+        id = TelemetryContextValue.required_id(object.fetch("id"), "session id")
+        normalized = { "id" => id }
+        if object.key?("previousId")
+          previous_id = TelemetryContextValue.required_id(
+            object.fetch("previousId"),
+            "session previousId"
+          )
+          if previous_id == id
+            raise TelemetryContextValue.invalid("session previousId must differ from id")
+          end
+          normalized["previousId"] = previous_id
+        end
+        normalized
+      end
+
+      def normalize_subject(value)
+        object = TelemetryContextValue.object(value, "telemetry context subject")
+        TelemetryContextValue.reject_unknown_fields(object, SUBJECT_FIELDS, "telemetry context subject")
+        unless object.key?("id")
+          raise TelemetryContextValue.invalid("subject id must be a string")
+        end
+        kind = object["kind"]
+        unless %w[anonymous user].include?(kind)
+          raise TelemetryContextValue.invalid("subject kind must be anonymous or user")
+        end
+        {
+          "id" => TelemetryContextValue.required_id(object.fetch("id"), "subject id"),
+          "kind" => kind
+        }
+      end
+
+      def normalize_tags(value)
+        object = TelemetryContextValue.object(value, "telemetry context tags")
+        TelemetryContextValue.require_tag_count(object.length)
+        object.keys.sort.each_with_object({}) do |key, normalized|
+          normalized_key = TelemetryContextValue.tag_key(key)
+          normalized[normalized_key] = TelemetryContextValue.required_string(
+            object.fetch(key),
+            "tag value for #{normalized_key}"
+          )
+        end
+      end
+
+      def resource_from_value(value)
+        value.nil? ? nil : TelemetryResource.from_hash(value)
+      end
+
+      def require_context_or_nil(value, label)
+        return if value.nil? || value.is_a?(TelemetryContext)
+
+        raise TelemetryContextValue.invalid("#{label} must be a LogBrew::TelemetryContext")
+      end
+
+      def safe_uname
+        Etc.uname
+      rescue StandardError
+        nil
+      end
+
+      def safe_runtime_value(value)
+        return nil if value.nil?
+
+        TelemetryContextValue.required_string(value.to_s, "runtime context value")
+      rescue StandardError
+        nil
+      end
+
+      def normalize_os_name(value)
+        return nil if value.nil?
+
+        normalized = value.downcase
+        return "darwin" if normalized.include?("darwin") || normalized.include?("mac os")
+        return "linux" if normalized.include?("linux")
+        return "windows" if normalized.match?(/windows|mswin|mingw|cygwin/)
+
+        normalized
+      end
+    end
+
+    private
+
+    def initialize(value)
+      @value = TelemetryContextValue.deep_freeze(TelemetryContextValue.deep_copy(value))
+      freeze
+    end
+  end
+
+  # Builder for one immutable, privacy-bounded shared telemetry context.
+  class TelemetryContextBuilder
+    def initialize
+      @value = { "schemaVersion" => TelemetryContext::SCHEMA_VERSION }
+    end
+
+    def with_resource(resource)
+      unless resource.is_a?(TelemetryResource)
+        raise TelemetryContextValue.invalid("resource must be a LogBrew::TelemetryResource")
+      end
+      @value["resource"] = resource.to_h
+      self
+    end
+
+    def with_trace(trace)
+      unless defined?(LogBrew::TraceContext) && trace.is_a?(LogBrew::TraceContext)
+        raise TelemetryContextValue.invalid("trace must be a LogBrew::TraceContext")
+      end
+      with_trace_ids(
+        trace_id: trace.trace_id,
+        span_id: trace.span_id,
+        parent_span_id: trace.parent_span_id,
+        sampled: trace.sampled
+      )
+    end
+
+    def with_trace_ids(trace_id:, span_id: nil, parent_span_id: nil, sampled: nil)
+      trace = { "traceId" => trace_id }
+      trace["spanId"] = span_id unless span_id.nil?
+      trace["parentSpanId"] = parent_span_id unless parent_span_id.nil?
+      trace["sampled"] = sampled unless sampled.nil?
+      @value["trace"] = trace
+      self
+    end
+
+    def with_session(id:, previous_id: nil)
+      session = { "id" => id }
+      session["previousId"] = previous_id unless previous_id.nil?
+      @value["session"] = session
+      self
+    end
+
+    def with_subject(id:, kind:)
+      @value["subject"] = { "id" => id, "kind" => kind }
+      self
+    end
+
+    def with_tag(key, value)
+      normalized_key = TelemetryContextValue.tag_key(key.to_s)
+      normalized_value = TelemetryContextValue.required_string(value, "tag value for #{normalized_key}")
+      tags = (@value["tags"] ||= {})
+      tags[normalized_key] = normalized_value
+      TelemetryContextValue.require_tag_count(tags.length)
+      self
+    end
+
+    def with_tags(tags)
+      object = TelemetryContextValue.object(tags, "telemetry context tags")
+      object.each { |key, value| with_tag(key, value) }
+      self
+    end
+
+    def build
+      TelemetryContext.from_hash(@value)
+    end
+  end
+end

data/lib/logbrew/telemetry_context_value.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module LogBrew
+  # Shared validation and detachment rules for schema-v1 telemetry context.
+  module TelemetryContextValue
+    MAX_CONTEXT_STRING = 256
+    MAX_CONTEXT_ID = 200
+    MAX_TAGS = 32
+    MAX_TAG_KEY = 64
+    TAG_KEY = /\A[A-Za-z][A-Za-z0-9_.-]*\z/.freeze
+    CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f]/.freeze
+    LOWER_HEX = /\A[0-9a-f]+\z/.freeze
+
+    module_function
+
+    def object(value, label)
+      raise invalid("#{label} must be an object") unless value.is_a?(Hash)
+
+      value.each_with_object({}) do |(key, item), normalized|
+        unless key.is_a?(String) || key.is_a?(Symbol)
+          raise invalid("#{label} keys must be strings")
+        end
+
+        normalized_key = key.to_s
+        if normalized.key?(normalized_key)
+          raise invalid("#{label} contains duplicate field #{normalized_key}")
+        end
+        normalized[normalized_key] = item
+      end
+    end
+
+    def reject_unknown_fields(value, allowed, label)
+      unknown = value.keys - allowed
+      return if unknown.empty?
+
+      raise invalid("#{label} has unknown field #{unknown.sort.first}")
+    end
+
+    def required_string(value, label, maximum = MAX_CONTEXT_STRING)
+      raise invalid("#{label} must be a string") unless value.is_a?(String)
+
+      normalized = utf8_string(value, label).strip
+      raise invalid("#{label} must not be empty") if normalized.empty? || !normalized.match?(/\S/)
+      if normalized.length > maximum
+        raise invalid("#{label} must contain at most #{maximum} characters")
+      end
+      if normalized.match?(CONTROL_CHARACTERS)
+        raise invalid("#{label} must not contain control characters")
+      end
+
+      normalized
+    end
+
+    def optional_string(value, label, maximum = MAX_CONTEXT_STRING)
+      return nil if value.nil?
+
+      required_string(value, label, maximum)
+    end
+
+    def required_id(value, label)
+      required_string(value, label, MAX_CONTEXT_ID)
+    end
+
+    def optional_id(value, label)
+      return nil if value.nil?
+
+      required_id(value, label)
+    end
+
+    def trace_id(value, label = "traceId")
+      normalized_hex_id(value, 32, "0" * 32, label)
+    end
+
+    def span_id(value, label)
+      normalized_hex_id(value, 16, "0" * 16, label)
+    end
+
+    def optional_span_id(value, label)
+      return nil if value.nil?
+
+      span_id(value, label)
+    end
+
+    def tag_key(value)
+      raise invalid("tag key must be a string") unless value.is_a?(String)
+
+      normalized = utf8_string(value, "tag key")
+      unless normalized.length <= MAX_TAG_KEY && normalized.match?(TAG_KEY)
+        raise invalid("tag key #{normalized} must start with a letter and contain only letters, numbers, _, ., or -")
+      end
+
+      normalized
+    end
+
+    def require_tag_count(count)
+      unless count.between?(1, MAX_TAGS)
+        raise invalid("telemetry context must contain 1 to at most #{MAX_TAGS} tags")
+      end
+    end
+
+    def deep_copy(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(key, item), copy| copy[key.dup] = deep_copy(item) }
+      when Array
+        value.map { |item| deep_copy(item) }
+      when String
+        value.dup
+      else
+        value
+      end
+    end
+
+    def deep_freeze(value)
+      case value
+      when Hash
+        value.each do |key, item|
+          key.freeze
+          deep_freeze(item)
+        end
+      when Array
+        value.each { |item| deep_freeze(item) }
+      end
+      value.freeze
+    end
+
+    def invalid(message)
+      SdkError.new("validation_error", message)
+    end
+
+    def normalized_hex_id(value, width, all_zero, label)
+      raise invalid("#{label} must be #{width} non-zero hex characters") unless value.is_a?(String)
+
+      normalized = utf8_string(value, label).downcase
+      unless normalized.length == width && normalized.match?(LOWER_HEX) && normalized != all_zero
+        raise invalid("#{label} must be #{width} non-zero hex characters")
+      end
+      normalized
+    end
+    private_class_method :normalized_hex_id
+
+    def utf8_string(value, label)
+      normalized = value.encode(Encoding::UTF_8)
+      raise EncodingError unless normalized.valid_encoding?
+
+      normalized.dup
+    rescue EncodingError
+      raise invalid("#{label} must be valid UTF-8")
+    end
+    private_class_method :utf8_string
+  end
+end

data/lib/logbrew/telemetry_resource.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module LogBrew
+  # Immutable service, deployment, runtime, framework, OS, device, and app identity.
+  class TelemetryResource
+    SECTION_FIELDS = {
+      "service" => %w[name version].freeze,
+      "deployment" => %w[environment release].freeze,
+      "runtime" => %w[name version].freeze,
+      "framework" => %w[name version].freeze,
+      "operatingSystem" => %w[name version build].freeze,
+      "device" => %w[family model architecture].freeze,
+      "application" => %w[name version build].freeze
+    }.freeze
+    NAME_REQUIRED_SECTIONS = %w[service runtime framework operatingSystem].freeze
+
+    def self.create
+      TelemetryResourceBuilder.new
+    end
+
+    def self.from_hash(value = nil, **keywords)
+      if value.nil?
+        value = keywords
+      elsif !keywords.empty?
+        raise TelemetryContextValue.invalid("telemetry resource must be one object")
+      end
+      object = TelemetryContextValue.object(value, "telemetry resource")
+      TelemetryContextValue.reject_unknown_fields(object, SECTION_FIELDS.keys, "telemetry resource")
+      raise TelemetryContextValue.invalid("telemetry resource must not be empty") if object.empty?
+
+      normalized = {}
+      SECTION_FIELDS.each do |section_name, fields|
+        next unless object.key?(section_name)
+
+        section = TelemetryContextValue.object(
+          object.fetch(section_name),
+          "telemetry resource #{section_name}"
+        )
+        TelemetryContextValue.reject_unknown_fields(
+          section,
+          fields,
+          "telemetry resource #{section_name}"
+        )
+        normalized_section = {}
+        fields.each do |field|
+          next unless section.key?(field)
+
+          normalized_section[field] = TelemetryContextValue.required_string(
+            section.fetch(field),
+            "telemetry resource #{section_name} #{field}"
+          )
+        end
+        if NAME_REQUIRED_SECTIONS.include?(section_name) && !normalized_section.key?("name")
+          raise TelemetryContextValue.invalid("telemetry resource #{section_name} name is required")
+        end
+        if normalized_section.empty?
+          raise TelemetryContextValue.invalid("telemetry resource #{section_name} must not be empty")
+        end
+        normalized[section_name] = normalized_section
+      end
+
+      new(normalized)
+    end
+
+    def self.merge(base, override)
+      require_resource_or_nil(base, "base telemetry resource")
+      require_resource_or_nil(override, "override telemetry resource")
+      return nil if base.nil? && override.nil?
+      return from_hash(override.to_h) if base.nil?
+      return from_hash(base.to_h) if override.nil?
+
+      base_value = base.to_h
+      override_value = override.to_h
+      merged = {}
+      SECTION_FIELDS.each_key do |section|
+        base_section = base_value[section]
+        override_section = override_value[section]
+        next if base_section.nil? && override_section.nil?
+
+        merged[section] = (base_section || {}).merge(override_section || {})
+      end
+      from_hash(merged)
+    end
+
+    def to_h
+      TelemetryContextValue.deep_copy(@value)
+    end
+
+    private
+
+    def initialize(value)
+      @value = TelemetryContextValue.deep_freeze(TelemetryContextValue.deep_copy(value))
+      freeze
+    end
+
+    def self.require_resource_or_nil(value, label)
+      return if value.nil? || value.is_a?(TelemetryResource)
+
+      raise TelemetryContextValue.invalid("#{label} must be a LogBrew::TelemetryResource")
+    end
+    private_class_method :require_resource_or_nil
+  end
+
+  # Builder for one immutable telemetry resource.
+  class TelemetryResourceBuilder
+    def initialize
+      @value = {}
+    end
+
+    def with_service(name:, version: nil)
+      @value["service"] = named_version(name, version)
+      self
+    end
+
+    def with_deployment(environment: nil, release: nil)
+      @value["deployment"] = optional_fields(environment: environment, release: release)
+      self
+    end
+
+    def with_runtime(name:, version: nil)
+      @value["runtime"] = named_version(name, version)
+      self
+    end
+
+    def with_framework(name:, version: nil)
+      @value["framework"] = named_version(name, version)
+      self
+    end
+
+    def with_operating_system(name:, version: nil, build: nil)
+      @value["operatingSystem"] = optional_fields(name: name, version: version, build: build)
+      self
+    end
+
+    def with_device(family: nil, model: nil, architecture: nil)
+      @value["device"] = optional_fields(family: family, model: model, architecture: architecture)
+      self
+    end
+
+    def with_application(name: nil, version: nil, build: nil)
+      @value["application"] = optional_fields(name: name, version: version, build: build)
+      self
+    end
+
+    def build
+      TelemetryResource.from_hash(@value)
+    end
+
+    private
+
+    def named_version(name, version)
+      optional_fields(name: name, version: version)
+    end
+
+    def optional_fields(**values)
+      values.each_with_object({}) do |(key, value), section|
+        section[key.to_s] = value unless value.nil?
+      end
+    end
+  end
+end

data/lib/logbrew/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module LogBrew
+  VERSION = "0.1.4"
+end

data/lib/logbrew-sdk.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "logbrew"
+require "logbrew/rails" if defined?(::Rails::Railtie)