apidepth 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1863cc44a0aa90d68dbae4bba31293e4d8154a3a92c1fa0030c3a0002cf5237
-  data.tar.gz: 881062b88799903817b01067cfad0227499402073cd8e58702de8eb5cbf00f3e
+  metadata.gz: ee27b15f831798b976f293eda67c90c9cccab735e75cb82a225d3ea511331622
+  data.tar.gz: 2ed0a290e8acab029c51eb12a116d295f8dfaa1390eef934cb61e5f9344b63ce
 SHA512:
-  metadata.gz: a3f798621d4d00f8c158ec0ed50b1c00fb8e215da5efaec04fe04a996c29eec97dcf746c355eb16336b98ac46655133f7a16f0c4325cbec7b20e3bff72b37fa3
-  data.tar.gz: 88da8b454854604520dd0d025eb08ece7da634adb8951f59bc9c6b1421d6440b6ce7a0d9d82413f740025d9df361a80f530c18c8359a7484ca5ce4bf3d24d43e
+  metadata.gz: b32de3265dc5a4add529dd10741d21aa935ba18fccf669614fb74b9b06ed5d8125200d0ec26be7cf0c9349b8f6cc9a56d173ed4b2ba89acd551b5684bd411aa8
+  data.tar.gz: bf7106cbfdf0a003824b625680a047978f1f8a27c862ce8df52551f316405e47dbd4444e3e64361f35cedf6317f74575a9998ed766afdbdd6459d56a5a719404

data/README.md

@@ -1,5 +1,9 @@
 # apidepth
 
+[![Gem Version](https://img.shields.io/gem/v/apidepth)](https://rubygems.org/gems/apidepth)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.7-ruby)](https://rubygems.org/gems/apidepth)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
 Most API monitoring tools measure latency from their servers to the vendor. That's not what your users feel. Apidepth instruments `Net::HTTP` directly — every outbound call your app makes to Stripe, OpenAI, or Twilio is timed at the socket level, from your server. Then it benchmarks your numbers against anonymized fleet data, so when Stripe is slow you can tell if it's you or everyone.
 
 No payload capture. No credentials touch our infrastructure. No changes to your application code beyond a one-time initializer.

data/lib/apidepth/collector.rb

@@ -92,16 +92,21 @@ module Apidepth
       end
     end
 
+    # Canonical test cases live in apidepth-collector/tests/fixtures/private_host_cases.json.
+    # All SDK implementations load that fixture and must pass every case. Any change here
+    # must be accompanied by a fixture update and a matching change in every other SDK.
     PRIVATE_HOST_PATTERN = /
       \Alocalhost\z          |
       \A127\.                |
       \A0\.0\.0\.0\z         |
+      \A0\z                  |
+
       \A169\.254\.           |
       \A10\.                 |
       \A172\.(1[6-9]|2\d|3[01])\. |
       \A192\.168\.           |
       \A\[?::1\]?\z          |
-      \A\[?fc                |
+      \A\[?f[cd]             |
       \A\[?fe80:
     /xi.freeze
 
@@ -184,6 +189,8 @@ module Apidepth
     end
 
     def drain_queue
+      return [].freeze if @queue.empty?
+
       events = []
       events << @queue.pop(true) while events.size < MAX_BATCH_SIZE
       events
@@ -235,13 +242,7 @@ module Apidepth
 
       key = Apidepth.configuration.api_key
       if key.nil? || key.empty?
-        unless @warned_no_key
-          @warned_no_key = true
-          Apidepth.logger&.warn(
-            "[Apidepth] No API key configured — events are being dropped. " \
-            "Visit www.apidepth.io to create an account and get your key."
-          )
-        end
+        warn_no_api_key!
         return
       end
 
@@ -287,7 +288,7 @@ module Apidepth
 
       if host.match?(/\A\d+\z/)
         int = host.to_i
-        if int.positive? && int <= 0xFFFFFFFF
+        if int.between?(0, 0xFFFFFFFF)
           host = [int >> 24, (int >> 16) & 0xFF, (int >> 8) & 0xFF,
                   int & 0xFF].join(".")
         end
@@ -300,6 +301,18 @@ module Apidepth
             "addresses (got #{url.host.inspect})."
     end
 
+    def warn_no_api_key!
+      @stats_mutex.synchronize do
+        unless @warned_no_key
+          @warned_no_key = true
+          Apidepth.logger&.warn(
+            "[Apidepth] No API key configured — events are being dropped. " \
+            "Visit www.apidepth.io to create an account and get your key."
+          )
+        end
+      end
+    end
+
     def validate_api_key!(key)
       return if key.nil? || key.empty?
       return unless key.match?(/[\r\n]/)

data/lib/apidepth/net_http_instrumentation.rb

@@ -88,7 +88,8 @@ module Apidepth
           }.merge(rl || {})
         )
       )
-    rescue StandardError
+    rescue StandardError => e
+      Apidepth.logger&.debug("[Apidepth] Instrumentation error: #{e.class}: #{e.message}")
       nil
     end
 
@@ -110,7 +111,8 @@ module Apidepth
           ts: Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
         )
       )
-    rescue StandardError
+    rescue StandardError => e
+      Apidepth.logger&.debug("[Apidepth] Instrumentation error: #{e.class}: #{e.message}")
       nil
     end
   end

data/lib/apidepth/rate_limit_headers.rb

@@ -72,6 +72,7 @@ module Apidepth
       headers.each do |name|
         val = response[name]
         next unless val
+        next unless val.strip.match?(/\A\d+\z/)
 
         n = val.strip.to_i
         return n if n >= 0

data/lib/apidepth/registry_loader.rb

@@ -12,14 +12,32 @@ module Apidepth
     # registry (remote → disk cache → bundled baseline already loaded by
     # VendorRegistry.initialize_registry) and starts the background
     # refresh thread.
+    #
+    # Startup strategy: apply the on-disk cache synchronously so the in-process
+    # registry is populated immediately (no blocking network call on the boot
+    # thread). The initial remote fetch is dispatched to a background thread so
+    # that slow or unreachable endpoints (CI, air-gapped environments) do not
+    # block Rails boot for up to 8 seconds (open_timeout + read_timeout).
+    # The background refresh loop (start_refresh_thread) is unchanged.
     def self.load_and_start
-      registry = fetch_remote || load_from_disk
-      VendorRegistry.replace(registry) if registry
+      # Apply disk cache immediately — zero network latency, registry is ready
+      # before the application begins serving requests.
+      disk_registry = load_from_disk
+      VendorRegistry.replace(disk_registry) if disk_registry
+
+      # Fetch the freshest registry from the network in the background so the
+      # boot thread is never blocked by the remote request.
+      Thread.new do
+        registry = fetch_remote
+        VendorRegistry.replace(registry) if registry
+      end.tap do |t|
+        t.abort_on_exception = false
+        t.name = "apidepth-registry-init"
+      end
+
       start_refresh_thread
     end
 
-    private
-
     def self.start_refresh_thread
       Thread.new do
         loop do
@@ -57,6 +75,11 @@ module Apidepth
 
       registry = JSON.parse(res.body)
 
+      # Apply registry-managed customer vendors and emit developer warnings.
+      # Must run before replace() so the vendor list is complete when it lands.
+      apply_customer_vendors(registry)
+      emit_warnings(registry)
+
       # Warm the disk cache so the next cold-start skips the network fetch.
       begin
         validate_cache_path!(Apidepth.configuration.registry_cache_path)
@@ -79,6 +102,103 @@ module Apidepth
       Thread.current[:apidepth_skip] = false
     end
 
+    # Apply the collector-managed customer_vendors from the registry response.
+    #
+    # The collector is the source of truth after first declaration. Registry
+    # vendors are loaded on top of locally-declared extra_vendors; registry wins
+    # on any host conflict. Conflict warnings are emitted once per vendor per
+    # process lifetime (see emit_warnings).
+    def self.apply_customer_vendors(registry)
+      remote = registry["customer_vendors"]
+      return unless remote.is_a?(Hash) && !remote.empty?
+
+      local = Apidepth.configuration.extra_vendors || {}
+
+      # Filter to string key-value pairs before passing to load_extra_vendors.
+      # The server response is trusted but load_extra_vendors calls .to_s on
+      # everything — a non-string key like 42 would silently register as "42".
+      clean = {}
+      remote.each do |name, remote_host|
+        next unless name.is_a?(String) && remote_host.is_a?(String)
+
+        clean[name] = remote_host
+        local_host = local[name]
+        # Track conflicts before overwriting — emit_warnings reads this later.
+        @mutex.synchronize do
+          if local_host && local_host != remote_host
+            @conflict_vendors ||= {}
+            @conflict_vendors[name] = { local: local_host, remote: remote_host }
+          end
+        end
+      end
+
+      VendorRegistry.load_extra_vendors(clean)
+    end
+
+    # Emit developer-facing warnings from the registry response.
+    #
+    # Stale vendor warning: vendor exists in registry but no events in 7+ days.
+    # Conflict warning:     local extra_vendors host differs from registry host.
+    #
+    # Both follow the warn-once pattern — an instance flag per vendor prevents
+    # log spam in long-running processes. Warnings fire on registry fetch, not
+    # on every event.
+    def self.emit_warnings(registry)
+      # Stale vendor warnings — sourced from the registry warnings block.
+      # Only present in responses from collector v0.3+; older cached responses skip.
+      warnings = registry["warnings"]
+      emit_stale_warnings(warnings["stale_vendors"]) if warnings.is_a?(Hash)
+
+      # Conflict warnings — collected by apply_customer_vendors, emitted here.
+      # Fires regardless of whether the registry has a warnings block, so that
+      # conflicts detected against a cached/older registry are still surfaced.
+      emit_conflict_warnings
+    end
+
+    def self.emit_stale_warnings(stale)
+      return unless stale.is_a?(Array)
+
+      to_warn = []
+      @mutex.synchronize do
+        @warned_stale ||= {}
+        stale.each do |name|
+          next unless name.is_a?(String)
+          next if @warned_stale[name]
+
+          @warned_stale[name] = true
+          to_warn << name
+        end
+      end
+
+      to_warn.each do |name|
+        Apidepth.logger&.warn(
+          "[Apidepth] No events received from '#{name}' in 7+ days — " \
+          "is it still declared in extra_vendors? If intentional, remove " \
+          "it at www.apidepth.io."
+        )
+      end
+    end
+
+    def self.emit_conflict_warnings
+      conflicts, = @mutex.synchronize do
+        c = @conflict_vendors || {}
+        @conflict_vendors = {}
+        @warned_conflict ||= {}
+        to_warn = c.reject { |name, _| @warned_conflict[name] }
+        to_warn.each_key { |name| @warned_conflict[name] = true }
+        [to_warn]
+      end
+
+      conflicts.each do |name, hosts|
+        Apidepth.logger&.warn(
+          "[Apidepth] extra_vendors conflict: '#{name}' is configured as " \
+          "'#{hosts[:local]}' locally but the registry has '#{hosts[:remote]}' " \
+          "— registry takes precedence. Update your initializer or remove " \
+          "the entry from your dashboard at www.apidepth.io."
+        )
+      end
+    end
+
     def self.load_from_disk
       path = Apidepth.configuration.registry_cache_path
 
@@ -111,10 +231,27 @@ module Apidepth
       raise ArgumentError, "registry_cache_path must not contain '..' traversal segments (got #{path.inspect})"
     end
 
+    # Reset mutable class-level warn state under @mutex.
+    # Called by tests instead of raw instance_variable_set so that state
+    # changes go through the same lock used in production code paths.
+    def self.reset_state!
+      @mutex.synchronize do
+        @conflict_vendors = {}
+        @warned_stale     = {}
+        @warned_conflict  = {}
+      end
+    end
+
     # Ruby's `private` keyword does not apply to `def self.method` — those remain
     # public class methods regardless of placement inside a private block.
     # private_class_method is the correct idiom.
     private_class_method :start_refresh_thread, :fetch_remote,
-                         :load_from_disk, :validate_cache_path!
+                         :load_from_disk, :validate_cache_path!,
+                         :apply_customer_vendors, :emit_warnings,
+                         :emit_stale_warnings, :emit_conflict_warnings
+
+    # Mutex protecting @conflict_vendors, @warned_stale, and @warned_conflict.
+    # Initialized at require time like VendorRegistry's own @mutex.
+    @mutex = Mutex.new
   end
 end

data/lib/apidepth/vendor_registry.rb

@@ -64,6 +64,10 @@ module Apidepth
       [%r{/[a-z0-9]{24,}}, "/:token"]
     ].freeze
 
+    # True when the runtime supports Regexp.timeout (introduced in Ruby 3.2).
+    # Used by apply_vendor_normalizers to enable ReDoS protection when available.
+    RUBY_GTE_3_2 = Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.2")
+
     class << self
       def identify(host, raw_path)
         hosts, patterns = @mutex.synchronize { [@hosts, @patterns] }
@@ -169,11 +173,28 @@ module Apidepth
         path.split("?").first
       end
 
+      # First-match-wins: iteration stops at the first pattern that matches the
+      # path. Vendor authors must order rules from most-specific to least-specific
+      # to ensure that narrower patterns (e.g. /v1/charges/:id) are tested before
+      # broader catch-alls (e.g. /v1/:resource/:id). A less-specific rule placed
+      # earlier will shadow any more-specific rules that follow it.
+      #
+      # ReDoS protection: on Ruby >= 3.2 we apply a per-match timeout of 1ms so
+      # that a pathological pattern from a compromised or misconfigured registry
+      # cannot stall the request thread indefinitely. On older Ruby, Regexp.timeout
+      # is not available — use a trusted, internally-reviewed registry source.
       def apply_vendor_normalizers(rules, path)
+        if RUBY_GTE_3_2
+          saved_timeout = Regexp.timeout
+          Regexp.timeout = 0.001
+        end
+
         rules.each do |pattern, replacement|
           return path.gsub(pattern, replacement) if path.match?(pattern)
         end
         path
+      ensure
+        Regexp.timeout = saved_timeout if RUBY_GTE_3_2
       end
 
       def apply_generic_normalizers(path)

data/lib/apidepth/version.rb

@@ -1,5 +1,5 @@
 # lib/apidepth/version.rb
 
 module Apidepth
-  VERSION = "0.2.2".freeze
+  VERSION = "0.3.0".freeze
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apidepth
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Apidepth
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -93,8 +94,21 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.65'
-description: |
-  Know if your API slowness is your code or the vendor's. Apidepth instruments
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: Know if your API slowness is your code or the vendor's. Apidepth instruments
   Net::HTTP to track real production latency to Stripe, OpenAI, Twilio and others
   — then benchmarks your p95 against anonymized fleet data so you can see if it's
   you, or everyone.
@@ -121,10 +135,11 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://apidepth.io
-  source_code_uri: https://github.com/apidepth/apidepth-ruby
-  changelog_uri: https://github.com/apidepth/apidepth-ruby/blob/main/CHANGELOG.md
-  bug_tracker_uri: https://github.com/apidepth/apidepth-ruby/issues
+  source_code_uri: https://github.com/apidepth-io/apidepth-ruby
+  changelog_uri: https://github.com/apidepth-io/apidepth-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/apidepth-io/apidepth-ruby/issues
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -139,7 +154,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.11
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Know if your API slowness is your code or the vendor's
 test_files: []