convert_sdk 1.0.0

data/lib/convert_sdk/http_client.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "openssl"
+
+module ConvertSdk
+  # The single hardened HTTP port every SDK request flows through.
+  #
+  # +HttpClient+ is the *only* file in the gem that touches +Net::HTTP+ (a cheap
+  # architectural regression test asserts this). Every request it sends carries
+  # the ConvertAgent wire invariant and bounded timeouts, and every failure it
+  # encounters is converted into a failed {Response} rather than raised — the
+  # port NEVER raises to callers, so the config fetch (Story 2.5) and event
+  # delivery (Story 4.1) consumers degrade gracefully on a failed response.
+  #
+  # == The ConvertAgent wire invariant
+  #
+  # The metrics endpoint's bot filter silently DROPS server-side events whose
+  # +User-Agent+ is not +ConvertAgent/1.0+. The header is therefore applied
+  # LAST, after every header merge, so it cannot be overridden by an
+  # integrator-supplied +User-Agent+. Without it, tracking events would vanish
+  # silently in production. (JS/PHP precedent: set unconditionally after merge.)
+  #
+  # == Bounded timeouts
+  #
+  # Both +open_timeout+ and +read_timeout+ are set explicitly on EVERY request
+  # (a deliberate improvement over the JS SDK, which sets none). The SDK can
+  # never hang a host thread waiting on a slow or dead endpoint.
+  #
+  # == TLS / Bearer / proxies
+  #
+  # HTTPS endpoints use TLS with verification ON (+verify_mode+ is never
+  # +VERIFY_NONE+). An +Authorization: Bearer ...+ header is stripped (and a
+  # warning logged) on any non-HTTPS endpoint so the SDK key secret never
+  # crosses the wire in plaintext. Proxies are honoured through the standard
+  # +Net::HTTP+ environment conventions (+http_proxy+/+https_proxy+/+no_proxy+).
+  #
+  # == JSON boundary
+  #
+  # Callers pass and receive Ruby hashes; JSON encode/decode happens only here.
+  # A request +body+ hash is rendered with +JSON.generate+; a response body is
+  # parsed with +JSON.parse+ (string keys). A parse failure is logged and yields
+  # +body: nil+ on an otherwise intact response.
+  #
+  # All logging goes through the injected {LogManager} (never +puts+), so the
+  # {Redactor} masks secrets and strips URL query strings from every line.
+  class HttpClient
+    # The mandatory wire User-Agent. Applied LAST so it is unoverridable.
+    USER_AGENT = "ConvertAgent/1.0"
+
+    # The status used for a failed Response when no HTTP response was received
+    # (network error / timeout). Callers MUST use {Response#success?}, never
+    # compare the status integer, for error detection.
+    FAILURE_STATUS = 0
+
+    # An immutable result of a single HTTP request.
+    #
+    # +status+ is the HTTP status integer (or {FAILURE_STATUS} on a transport
+    # failure); +body+ is the parsed JSON object (or nil); +headers+ is the
+    # response header hash; +#success?+ is a strict 2xx predicate.
+    #
+    # Declared as an explicit +class < Struct.new(...)+ subclass (NOT the
+    # +Struct.new do...end+ block form): this is the only shape Steep can
+    # statically resolve +#success?+ and the keyword constructor against, the
+    # same reason the frozen value objects (BucketedVariation/BucketedFeature)
+    # use it.
+    class Response < Struct.new(:status, :body, :headers, keyword_init: true)
+      # @return [void] builds the struct then freezes it (immutable value object).
+      def initialize(**)
+        super
+        freeze
+      end
+
+      # @return [Boolean] true iff +status+ is in the 2xx range.
+      def success?
+        status.between?(200, 299)
+      end
+    end
+
+    # @param log_manager [LogManager] the injected logging surface. All output
+    #   flows through it so the {Redactor} applies.
+    # @param open_timeout [Numeric] connection-establishment timeout (seconds).
+    # @param read_timeout [Numeric] response-read timeout (seconds).
+    def initialize(log_manager:, open_timeout:, read_timeout:)
+      @log_manager = log_manager
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+    end
+
+    # Send one HTTP request and return a frozen {Response}. Never raises: any
+    # transport failure is logged and returned as a failed response.
+    #
+    # @param method [Symbol] +:get+ / +:post+ / etc.
+    # @param url [String] the absolute request URL.
+    # @param headers [Hash{String=>String}] caller headers (merged before the
+    #   wire invariant is applied last).
+    # @param body [Hash, nil] a request body; JSON-encoded if present.
+    # @return [Response] frozen; +success?+ is the only valid error check.
+    def request(method:, url:, headers: {}, body: nil)
+      uri = URI.parse(url)
+      https = uri.scheme == "https"
+      wire_headers = build_headers(headers, https)
+      @log_manager.debug("HttpClient#request: #{method.to_s.upcase} #{url}")
+
+      perform(method, uri, https, wire_headers, body)
+    rescue StandardError => e
+      @log_manager.error("HttpClient#request: request failed (#{e.class}: #{e.message})")
+      failed_response
+    end
+
+    private
+
+    # Open a per-call connection (no reuse — the seam admits net-http-persistent
+    # post-MVP), set explicit timeouts, send the request, and map the result to
+    # a frozen {Response}.
+    def perform(method, uri, https, wire_headers, body)
+      host = uri.host or raise(ArgumentError, "URL has no host: #{uri}")
+      Net::HTTP.start(
+        host, uri.port,
+        use_ssl: https,
+        open_timeout: @open_timeout,
+        read_timeout: @read_timeout
+      ) do |http|
+        http.open_timeout = @open_timeout
+        http.read_timeout = @read_timeout
+        net_response = http.request(build_request(method, uri, wire_headers, body))
+        build_response(net_response)
+      end
+    end
+
+    # Build the wire headers: caller headers first, then the ConvertAgent UA
+    # applied LAST (unoverridable), then the Bearer guard for non-HTTPS.
+    def build_headers(headers, https)
+      merged = {} #: Hash[String, String]
+      headers.each { |key, value| merged[key.to_s] = value }
+      merged["User-Agent"] = USER_AGENT
+      guard_bearer(merged, https)
+      merged
+    end
+
+    # Strip an Authorization header on a non-HTTPS endpoint (and warn): the SDK
+    # key secret must never cross the wire in plaintext.
+    def guard_bearer(headers, https)
+      return if https
+      return unless headers.key?("Authorization")
+
+      headers.delete("Authorization")
+      @log_manager.warn("HttpClient#request: stripped Authorization on non-HTTPS endpoint")
+    end
+
+    # Construct the Net::HTTP request object for +method+, attaching the JSON
+    # body (if any) and all wire headers.
+    def build_request(method, uri, wire_headers, body)
+      request_class = Net::HTTP.const_get(method.to_s.capitalize)
+      net_request = request_class.new(uri)
+      wire_headers.each { |key, value| net_request[key] = value }
+      if body
+        net_request["Content-Type"] ||= "application/json"
+        net_request.body = JSON.generate(body)
+      end
+      net_request
+    end
+
+    # Map a Net::HTTPResponse to a frozen {Response}, parsing the JSON body.
+    def build_response(net_response)
+      Response.new(
+        status: net_response.code.to_i,
+        body: parse_body(net_response.body),
+        headers: flatten_headers(net_response)
+      )
+    end
+
+    # Parse a response body as JSON (string keys). A blank body or a parse
+    # failure yields nil; a failure is logged.
+    def parse_body(raw)
+      return nil if raw.nil? || raw.empty?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError => e
+      @log_manager.warn("HttpClient#request: response body is not JSON (#{e.class})")
+      nil
+    end
+
+    # Flatten Net::HTTP's multi-value header representation into a simple Hash.
+    def flatten_headers(net_response)
+      headers = {} #: Hash[String, String]
+      net_response.each_header { |key, value| headers[key] = value }
+      headers
+    end
+
+    # A failed Response with no HTTP status. Frozen, like every Response.
+    def failed_response
+      Response.new(status: FAILURE_STATUS, body: nil, headers: {}) #: Response
+    end
+  end
+end

data/lib/convert_sdk/log_manager.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module ConvertSdk
+  # Multi-sink, level-gated logger with secret redaction wired in by
+  # construction.
+  #
+  # +LogManager+ is consumed by every manager from the HTTP client (Story 1.5)
+  # onward. It fans messages out to any number of stdlib-+Logger+-compatible
+  # *sinks* and guarantees, structurally, that no message reaches a sink
+  # without first passing through the {Redactor}: every public level method
+  # funnels through the single private +#emit+ path, and that path applies the
+  # +loggable+ conversion boundary and redaction before touching a sink. There
+  # is no public method that bypasses +#emit+.
+  #
+  # == Levels
+  #
+  # Verbosity is gated by the JS-parity {LogLevel} values (TRACE=0 … SILENT=5).
+  # A call at level +L+ emits only when +L >= configured_level+; +SILENT+
+  # suppresses everything. The stdlib +Logger+ has no +trace+, so both
+  # {#trace} and {#debug} dispatch to the sink's +#debug+ — the numeric level
+  # value (0 vs 1), not the sink method, decides whether they emit.
+  #
+  # Level conventions (callers choose the level by intent):
+  #
+  # * +trace+ / +debug+ — decisioning internals (bucketing, rule evaluation).
+  # * +info+  — lifecycle events (SDK ready, config refreshed).
+  # * +warn+  — recoverable conditions (stale config, retry).
+  # * +error+ — internal failures (parse error, exhausted retries).
+  #
+  # == Message format
+  #
+  # Callers pass messages already formatted as <tt>{ClassName}#{method}:
+  # {message}</tt>. +LogManager+ does not prepend the class name itself — the
+  # format is a usage convention, documented here and enforced at call sites.
+  #
+  # == Thread safety
+  #
+  # The sink list is guarded by +@sinks_mutex+. Compound operations on the list
+  # happen inside the lock; the (potentially slow, potentially raising) sink
+  # I/O happens outside the lock by iterating a +dup+ snapshot. A sink that
+  # raises is contained (rescue +StandardError+) so a broken sink never crashes
+  # the host or starves the other sinks.
+  class LogManager
+    # @param level [Integer] a {LogLevel} threshold; messages below it are
+    #   suppressed. Defaults to ERROR (quiet by default).
+    # @param sink [Object, nil] an optional initial sink (anything responding
+    #   to debug/info/warn/error). Invalid sinks are rejected, not raised.
+    # @param secrets [Array<String>] secret values to redact from every
+    #   message. More can be added later via {#register_secret}.
+    def initialize(level: LogLevel::ERROR, sink: nil, secrets: [])
+      @level = level
+      @redactor = Redactor.new(secrets)
+      @sinks = []
+      # Thread safety: guarded by @sinks_mutex.
+      @sinks_mutex = Thread::Mutex.new
+      add_sink(sink) unless sink.nil?
+    end
+
+    # The methods every valid sink must respond to (stdlib +Logger+ contract).
+    REQUIRED_SINK_METHODS = %i[debug info warn error].freeze
+
+    # Register a sink. Accepted iff it duck-types to the stdlib +Logger+
+    # contract (responds to debug/info/warn/error). An invalid sink is rejected
+    # with a logged error rather than raising — registration must never crash
+    # the host.
+    #
+    # @param sink [Object] the candidate sink.
+    # @return [self] for chaining. A rejected sink is logged, not registered.
+    def add_sink(sink)
+      if REQUIRED_SINK_METHODS.all? { |m| sink.respond_to?(m) }
+        @sinks_mutex.synchronize { @sinks << sink }
+      else
+        emit(LogLevel::ERROR, "LogManager#add_sink: rejected sink #{sink.class} " \
+                              "(must respond to #{REQUIRED_SINK_METHODS.join("/")})")
+      end
+      self
+    end
+
+    # Register an additional secret to redact (e.g. once the SDK key is known
+    # at +ConvertSdk.create+ time). nil/blank is a no-op.
+    #
+    # @param secret [String, nil]
+    # @return [void]
+    def register_secret(secret)
+      @redactor.register_secret(secret)
+    end
+
+    # @!method trace(message)
+    #   Log at TRACE — decisioning internals. Dispatches to sink +#debug+.
+    # @!method debug(message)
+    #   Log at DEBUG — decisioning internals. Dispatches to sink +#debug+.
+    # @!method info(message)
+    #   Log at INFO — lifecycle events.
+    # @!method warn(message)
+    #   Log at WARN — recoverable conditions.
+    # @!method error(message)
+    #   Log at ERROR — internal failures.
+
+    # @param message [String] the already-formatted message.
+    # @return [void] log at TRACE (finest-grained); dispatches to the sink's +#debug+.
+    def trace(message)
+      emit(LogLevel::TRACE, message)
+    end
+
+    def debug(message)
+      emit(LogLevel::DEBUG, message)
+    end
+
+    def info(message)
+      emit(LogLevel::INFO, message)
+    end
+
+    def warn(message)
+      emit(LogLevel::WARN, message)
+    end
+
+    def error(message)
+      emit(LogLevel::ERROR, message)
+    end
+
+    private
+
+    # The single emission funnel. Every public log path lands here. Gates on
+    # level, converts the argument across the +loggable+ boundary, redacts the
+    # result, then fans out to a snapshot of the sinks. No sink is touched with
+    # an unredacted string, and no sink failure escapes.
+    def emit(level, message)
+      return if level < @level
+
+      text = @redactor.redact(loggable(message))
+      sink_method = sink_method_for(level)
+      each_sink do |sink|
+        sink.public_send(sink_method, text)
+      rescue StandardError
+        # A broken sink must never crash the host or starve other sinks.
+      end
+    end
+
+    # The +loggable+ conversion boundary (PHP qs-12 lesson): structured objects
+    # become a controlled string BEFORE redaction, since redaction operates on
+    # strings. Strings pass through unchanged; everything else is rendered with
+    # a compact +#inspect+ so a later raw-object dump cannot bypass redaction.
+    def loggable(message)
+      return message if message.is_a?(String)
+
+      message.inspect
+    end
+
+    # Map a {LogLevel} value to the sink method that carries it. TRACE and
+    # DEBUG both go to +#debug+ (stdlib has no trace); the rest map 1:1.
+    def sink_method_for(level)
+      case level
+      when LogLevel::TRACE, LogLevel::DEBUG then :debug
+      when LogLevel::INFO then :info
+      when LogLevel::WARN then :warn
+      else :error
+      end
+    end
+
+    # Iterate a snapshot of the sink list. The +dup+ is taken inside the lock
+    # so registration is atomic against iteration; the yielded I/O runs outside
+    # the lock so a slow/blocking sink cannot hold the mutex.
+    def each_sink(&)
+      snapshot = @sinks_mutex.synchronize { @sinks.dup }
+      snapshot.each(&)
+    end
+  end
+end

data/lib/convert_sdk/murmur_hash3.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module ConvertSdk
+  # Vendored pure-Ruby MurmurHash3 (x86 32-bit variant).
+  #
+  # This is the cross-SDK hashing cornerstone: bucketing computes
+  # +MurmurHash3.hash(experienceId + visitorId, 9999)+ and MUST produce a
+  # byte-identical result to every other Convert SDK (JS, PHP), or a visitor
+  # would bucket into a different variation on Ruby than on web. The 75-vector
+  # parity suite (+spec/cross_sdk/hash_vectors_spec.rb+) is the proof.
+  #
+  # Implemented as pure Ruby with explicit 32-bit masking — no C extension and
+  # no gemspec dependency, so it is JRuby-compatible by construction. Ruby
+  # integers are arbitrary-precision; the +& MASK_32+ on every arithmetic step
+  # is the correctness boundary that emulates 32-bit unsigned overflow.
+  #
+  # Reference: Austin Appleby's MurmurHash3_x86_32 (public domain).
+  # https://github.com/aappleby/smhasher/blob/master/src/MurmurHash3.cpp
+  #
+  # @api private
+  module MurmurHash3
+    # 32-bit overflow mask — applied after every multiply/add/shift.
+    MASK_32 = 0xFFFFFFFF
+
+    # Canonical MurmurHash3_x86_32 k1-scramble multiply constant.
+    C1 = 0xcc9e2d51
+    # Canonical MurmurHash3_x86_32 k1-scramble second multiply constant.
+    C2 = 0x1b873593
+    # Body block mixing multiplier: rotl(h1, R2) * M + N.
+    M = 5
+    # Body block mixing addend: rotl(h1, R2) * M + N.
+    N = 0xe6546b64
+    # k1 rotate-left amount before the * C2 multiply.
+    R1 = 15
+    # h1 rotate-left amount in the body mix.
+    R2 = 13
+
+    # Finalization mix (fmix32) first multiply constant.
+    FMIX_C1 = 0x85ebca6b
+    # Finalization mix (fmix32) second multiply constant.
+    FMIX_C2 = 0xc2b2ae35
+
+    # Compute the MurmurHash3 x86 32-bit hash of +key+ with +seed+.
+    #
+    # @param key [String] the key; hashed over its UTF-8 byte sequence.
+    # @param seed [Integer] the 32-bit seed.
+    # @return [Integer] unsigned 32-bit hash value in the range 0..0xFFFFFFFF.
+    def self.hash(key, seed)
+      data = key.b # raw bytes (ASCII-8BIT view); UTF-8 multi-byte chars hash over their bytes
+      length = data.bytesize
+      h1 = seed & MASK_32
+
+      h1 = mix_body(data, length, h1)
+      h1 = mix_tail(data, length, h1)
+
+      # Finalization: fold in the length, then avalanche.
+      fmix32(h1 ^ length)
+    end
+
+    # Process all full 4-byte little-endian body blocks.
+    def self.mix_body(data, length, h1)
+      block_count = length / 4
+      block_count.times do |block|
+        i = block * 4
+        k1 = read_u32_le(data, i)
+        h1 ^= mix_k1(k1)
+        h1 = ((rotl32(h1, R2) * M) + N) & MASK_32
+      end
+      h1
+    end
+    private_class_method :mix_body
+
+    # Process the trailing 1..3 bytes (the tail) in little-endian order.
+    def self.mix_tail(data, length, h1)
+      tail_start = (length / 4) * 4
+      remaining = length & 3
+      return h1 if remaining.zero?
+
+      k1 = 0
+      k1 |= byte_at(data, tail_start + 2) << 16 if remaining >= 3
+      k1 |= byte_at(data, tail_start + 1) << 8 if remaining >= 2
+      k1 |= byte_at(data, tail_start) # remaining >= 1
+      h1 ^ mix_k1(k1)
+    end
+    private_class_method :mix_tail
+
+    # The shared k1 scramble: k1 * C1, rotl R1, * C2.
+    def self.mix_k1(k1)
+      k1 = (k1 * C1) & MASK_32
+      k1 = rotl32(k1, R1)
+      (k1 * C2) & MASK_32
+    end
+    private_class_method :mix_k1
+
+    # Read a 32-bit little-endian word at byte offset +index+.
+    def self.read_u32_le(data, index)
+      byte_at(data, index) |
+        (byte_at(data, index + 1) << 8) |
+        (byte_at(data, index + 2) << 16) |
+        (byte_at(data, index + 3) << 24)
+    end
+    private_class_method :read_u32_le
+
+    # Read one byte as a guaranteed Integer. Every call site has already bounds-
+    # checked the index, so a nil here would be a genuine bug — surface it.
+    def self.byte_at(data, index)
+      Integer(data.getbyte(index))
+    end
+    private_class_method :byte_at
+
+    # 32-bit left rotate.
+    def self.rotl32(value, shift)
+      value &= MASK_32
+      ((value << shift) | (value >> (32 - shift))) & MASK_32
+    end
+    private_class_method :rotl32
+
+    # fmix32 avalanche finalizer.
+    def self.fmix32(hash)
+      hash &= MASK_32
+      hash ^= hash >> 16
+      hash = (hash * FMIX_C1) & MASK_32
+      hash ^= hash >> 13
+      hash = (hash * FMIX_C2) & MASK_32
+      hash ^ (hash >> 16)
+    end
+    private_class_method :fmix32
+  end
+end

data/lib/convert_sdk/redactor.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module ConvertSdk
+  # Masks secrets and strips URL query strings out of log messages.
+  #
+  # +Redactor+ is the structural guarantee behind security NFR5: it is wired
+  # *inside* {LogManager} so that no call path can emit a message without first
+  # passing through {#redact}. Redaction is by construction, not by discipline.
+  #
+  # Two transforms are applied to every message:
+  #
+  # * *Secret masking* — each known secret (e.g. an +sdk_key+ /
+  #   +sdk_key_secret+ value) is replaced wherever it occurs with its first
+  #   four characters followed by a single-character ellipsis (+abcd…+).
+  #   Secrets shorter than four characters are replaced entirely (+…+).
+  # * *URL query stripping* — any +http(s)+ URL has its +?query=string+ removed
+  #   (+https://host/path?x=1+ becomes +https://host/path+), since query
+  #   strings frequently carry tokens.
+  #
+  # Secrets become known at different times: some at construction, some at
+  # +ConvertSdk.create+ time. {#register_secret} allows late registration so
+  # the same redactor instance can be wired before all secrets are known.
+  #
+  # Redaction operates on *strings* — structured objects must already have
+  # passed the +loggable+ conversion boundary (see {LogManager}) before
+  # reaching here.
+  class Redactor
+    # Number of leading characters kept unmasked for a secret long enough to
+    # retain a prefix. JS-parity disclosure budget.
+    MASK_PREFIX_LENGTH = 4
+    # The single-character ellipsis appended after the unmasked prefix (or used
+    # as the whole replacement for short secrets).
+    MASK_GLYPH = "…"
+    # Matches an +http(s)+ URL's query string: a +?+ and everything up to the
+    # next whitespace. The query is stripped; the path is kept.
+    URL_QUERY_PATTERN = %r{(https?://\S*?)\?\S*}
+
+    # @param secrets [Array<String, nil>] secret values to mask. nil/blank
+    #   entries are ignored.
+    def initialize(secrets = [])
+      @secrets = []
+      Array(secrets).each { |secret| register_secret(secret) }
+    end
+
+    # Register an additional secret to mask. Safe to call after construction
+    # (e.g. once the SDK key is known at +ConvertSdk.create+ time).
+    #
+    # @param secret [String, nil] the secret value. nil/blank is a no-op.
+    # @return [void]
+    def register_secret(secret)
+      return if secret.nil?
+
+      value = secret.to_s
+      return if value.strip.empty?
+
+      @secrets << value unless @secrets.include?(value)
+    end
+
+    # Apply secret masking and URL query stripping to +message+.
+    #
+    # @param message [String] the message to redact.
+    # @return [String] the redacted message (a new string; +message+ is not
+    #   mutated).
+    def redact(message)
+      result = strip_url_queries(message.to_s)
+      mask_secrets(result)
+    end
+
+    private
+
+    # Replace every occurrence of every known secret with its masked form.
+    # Longer secrets are masked first so a secret that is a prefix of another
+    # does not partially un-mask the longer one.
+    def mask_secrets(message)
+      @secrets.sort_by { |secret| -secret.length }.each do |secret|
+        message = message.gsub(secret, masked(secret))
+      end
+      message
+    end
+
+    # @return [String] +abcd…+ for secrets >= 4 chars, +…+ otherwise.
+    def masked(secret)
+      return MASK_GLYPH if secret.length < MASK_PREFIX_LENGTH
+
+      "#{secret[0, MASK_PREFIX_LENGTH]}#{MASK_GLYPH}"
+    end
+
+    # Drop the query string from any URL in the message, keeping the path.
+    def strip_url_queries(message)
+      message.gsub(URL_QUERY_PATTERN, '\1')
+    end
+  end
+end