apidepth 0.2.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f499652eea585017c268ea82a997a9e11af46e36c912b6f672fa91fd7d354eb4
-  data.tar.gz: aa70866eaf7876101236b986472ad14b24ea68bcaa9a38a68ed901d88e1f06b5
+  metadata.gz: 48290c633c238b8bbfcaff2a1f98cb4ffa26a3d0c02853ef0f345841425b463e
+  data.tar.gz: b3564982b79da91fe2ad976c913aa8bf94efbd35928f78a52d934e43b02eb4d0
 SHA512:
-  metadata.gz: 22a04205584e05a111b2422209733b4c06b0008dada3840caa340915d2d9ffb7195dec530c4791b692990812f357b4148a714da904ada5fba15e5b20f854460e
-  data.tar.gz: 607dca2a4455e60fcf21bd3502382107a3840b02ca23102a0dac4fc4c903c62101bf46b099210591182aa6350f229ffc0209f650a71076060c1e482b83340cee
+  metadata.gz: 7a932948137e2d17f75d346686e60f0287c06f2702ec03a7adf3458c521604d9691e7803921726d391f1e161c59f77bce15063a5eeda93800093d7bb7d75e3ac
+  data.tar.gz: d262bd3e9b0668a1f5c667160efba8a41b99b850fcf177d3ccf3a5398b7179a005d9b141fb1ef62e1e3a86d55533fce7cf7eaf96c71f01a059ba96d98888ff9e

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.
@@ -36,7 +40,7 @@ bundle install
 
 ---
 
-## Quick start
+## Getting started
 
 Create `config/initializers/apidepth.rb`:
 
@@ -96,7 +100,8 @@ Apidepth.configure do |config|
   # Path for the local vendor registry cache. Must be an absolute path.
   # The registry is fetched from Apidepth's servers and cached here so
   # cold starts don't block on a network fetch.
-  # Default: "/tmp/apidepth_registry.json"
+  # Rails default: Rails.root.join("tmp/apidepth_registry.json") (set by the Railtie)
+  # Non-Rails default: "/tmp/apidepth_registry.json"
   config.registry_cache_path = "/tmp/apidepth_registry.json"
 
   # Custom vendors your app calls that aren't in the global registry.
@@ -129,6 +134,9 @@ Every event contains:
 | `cold_start` | `true` if this request paid for SSL handshake; excluded from p95 calculations |
 | `env` | Environment tag from `config.environment` or `Rails.env` |
 | `ts` | Unix timestamp in milliseconds |
+| `rl_remaining` | Remaining quota, e.g. `4999` — present when vendor rate limit headers are found |
+| `rl_limit` | Total quota, e.g. `5000` — present when vendor rate limit headers are found |
+| `rl_reset_at` | Quota reset time in epoch milliseconds — present when vendor rate limit headers are found |
 
 ### What is never captured
 

data/bin/apidepth

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+# bin/apidepth — CLI entry point for the Apidepth Ruby SDK.
+#
+# Subcommands:
+#   setup   Configure the SDK for your project (writes initializer)
+#   test    Send a synthetic test event and confirm the pipeline works
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+subcommand = ARGV.shift
+
+case subcommand
+when "setup"
+  require "apidepth/cli/setup"
+  Apidepth::CLI::Setup.run(ARGV)
+when "test"
+  require "apidepth/cli/test_cmd"
+  Apidepth::CLI::TestCmd.run(ARGV)
+when nil, "--help", "-h"
+  puts "Usage: bundle exec apidepth <subcommand> [options]"
+  puts ""
+  puts "Subcommands:"
+  puts "  setup   Configure the SDK and write your initializer"
+  puts "  test    Send a test event to confirm the pipeline works"
+  puts ""
+  puts "Run `bundle exec apidepth <subcommand> --help` for subcommand options."
+else
+  warn "Unknown subcommand: #{subcommand.inspect}"
+  warn "Run `bundle exec apidepth --help` for usage."
+  exit 1
+end

data/lib/apidepth/cli/framework_detector.rb

@@ -0,0 +1,82 @@
+# lib/apidepth/cli/framework_detector.rb
+#
+# Detects the web framework in the current directory by inspecting well-known
+# files. Returns a framework identifier and the recommended initializer path.
+# Used by `apidepth setup` to produce copy-paste-ready output.
+
+module Apidepth
+  module CLI
+    module FrameworkDetector
+      FRAMEWORKS = %i[rails sinatra].freeze
+
+      DetectedFramework = Struct.new(:name, :initializer_path, :initializer_snippet, keyword_init: true)
+
+      def self.detect(dir: Dir.pwd, api_key: nil, ignored_hosts: [], collector_url: nil)
+        framework = _detect_framework(dir)
+        _build_result(framework, api_key: api_key, ignored_hosts: ignored_hosts, collector_url: collector_url)
+      end
+
+      def self._detect_framework(dir)
+        return :rails   if File.exist?(File.join(dir, "config/application.rb"))
+        return :sinatra if File.exist?(File.join(dir, "config.ru"))
+
+        :generic
+      end
+
+      def self._build_result(framework, api_key:, ignored_hosts:, collector_url:)
+        key_val     = api_key       || "YOUR_API_KEY"
+        url_val     = collector_url || "https://collector.apidepth.io"
+        hosts_val   = ignored_hosts.empty? ? "[]" : ignored_hosts.map { |h| %("#{h}") }.join(", ").then { |s| "[#{s}]" }
+
+        case framework
+        when :rails
+          snippet = <<~RUBY
+            # config/initializers/apidepth.rb
+            Apidepth.configure do |config|
+              config.api_key       = #{key_val.inspect}
+              config.collector_url = #{url_val.inspect}
+              config.ignored_hosts = #{hosts_val}
+            end
+          RUBY
+          DetectedFramework.new(
+            name: :rails,
+            initializer_path: "config/initializers/apidepth.rb",
+            initializer_snippet: snippet
+          )
+        when :sinatra
+          snippet = <<~RUBY
+            # Top of your main app file (e.g. app.rb), before any routes
+            require "apidepth"
+            Apidepth.configure do |config|
+              config.api_key       = #{key_val.inspect}
+              config.collector_url = #{url_val.inspect}
+              config.ignored_hosts = #{hosts_val}
+            end
+            Apidepth.instrument!
+          RUBY
+          DetectedFramework.new(
+            name: :sinatra,
+            initializer_path: nil,
+            initializer_snippet: snippet
+          )
+        else
+          snippet = <<~RUBY
+            # Add to your application startup file
+            require "apidepth"
+            Apidepth.configure do |config|
+              config.api_key       = #{key_val.inspect}
+              config.collector_url = #{url_val.inspect}
+              config.ignored_hosts = #{hosts_val}
+            end
+            Apidepth.instrument!
+          RUBY
+          DetectedFramework.new(
+            name: :generic,
+            initializer_path: nil,
+            initializer_snippet: snippet
+          )
+        end
+      end
+    end
+  end
+end

data/lib/apidepth/cli/setup.rb

@@ -0,0 +1,136 @@
+# lib/apidepth/cli/setup.rb
+#
+# Implements `bundle exec apidepth setup`.
+#
+# Interactive mode (default):
+#   Opens the Apidepth dashboard in a browser so the developer can copy their
+#   API key, then prompts for ignored host patterns and writes the initializer.
+#
+# Non-interactive mode (CI/CD and AI-assisted setup):
+#   bundle exec apidepth setup --api-key $APIDEPTH_API_KEY --no-prompt
+#   All prompts are bypassed; output goes to stdout only.
+
+require "optparse"
+require "apidepth/cli/framework_detector"
+
+module Apidepth
+  module CLI
+    module Setup
+      DASHBOARD_KEYS_URL = "https://apidepth.io/dashboard/api-keys".freeze
+
+      def self.run(argv = ARGV)
+        options = parse_options(argv)
+        api_key = options[:api_key]
+        collector_url = options[:collector_url]
+        ignored_hosts = options[:ignored_hosts] || []
+        no_prompt = options[:no_prompt]
+        framework_override = options[:framework]
+
+        # Interactive: open dashboard and prompt for key
+        unless api_key || no_prompt
+          $stdout.puts "\nApidepth SDK Setup"
+          $stdout.puts "─" * 40
+          $stdout.puts "\nOpening your API keys page..."
+          _open_browser(DASHBOARD_KEYS_URL)
+          $stdout.print "\nPaste your API key: "
+          api_key = $stdin.gets&.strip
+          if api_key.nil? || api_key.empty?
+            warn "No API key provided. Aborting."
+            exit 1
+          end
+        end
+
+        # Interactive: prompt for ignored hosts
+        unless no_prompt
+          $stdout.puts "\nDefault ignored hosts (always skipped):"
+          %w[localhost 127.0.0.1 0.0.0.0 ::1].each { |h| $stdout.puts "  • #{h}" }
+          $stdout.puts "  • #{collector_url || 'collector.apidepth.io'}"
+          $stdout.puts "\nAny internal API patterns to ignore? (comma-separated, wildcards ok)"
+          $stdout.puts "  Examples: *.internal, *.local, *.svc.cluster.local, *.railway.internal"
+          $stdout.print "> "
+          input = $stdin.gets&.strip || ""
+          ignored_hosts += input.split(",").map(&:strip).reject(&:empty?) unless input.empty?
+        end
+
+        result = FrameworkDetector.detect(
+          dir: Dir.pwd,
+          api_key: api_key,
+          ignored_hosts: ignored_hosts,
+          collector_url: collector_url
+        )
+        # Override detected framework if flag provided
+        if framework_override
+          result = FrameworkDetector.detect(
+            dir: Dir.pwd,
+            api_key: api_key,
+            ignored_hosts: ignored_hosts,
+            collector_url: collector_url
+          )
+        end
+
+        _print_result(result, no_prompt: no_prompt)
+      end
+
+      def self.parse_options(argv)
+        options = {}
+        parser = OptionParser.new do |opts|
+          opts.banner = "Usage: bundle exec apidepth setup [options]"
+          opts.on("--api-key KEY", "API key (skips browser OAuth)") { |v| options[:api_key] = v }
+          opts.on("--collector-url URL", "Override collector URL") { |v| options[:collector_url] = v }
+          opts.on("--ignored-hosts HOSTS", "Comma-separated ignored host patterns") do |v|
+            options[:ignored_hosts] = v.split(",").map(&:strip)
+          end
+          opts.on("--no-prompt", "Non-interactive mode; output to stdout only") { options[:no_prompt] = true }
+          opts.on("--framework NAME", "Override framework detection (rails|sinatra|generic)") do |v|
+            options[:framework] = v
+          end
+          opts.on_tail("-h", "--help", "Show this message") do
+            puts opts
+            exit
+          end
+        end
+        begin
+          parser.parse!(argv.dup)
+        rescue OptionParser::InvalidOption => e
+          warn e.message
+          exit 1
+        end
+        options
+      end
+
+      def self._open_browser(url)
+        if RUBY_PLATFORM.include?("darwin")
+          system("open", url)
+        elsif RUBY_PLATFORM.include?("linux")
+          system("xdg-open", url)
+        else
+          $stdout.puts "Visit: #{url}"
+        end
+      end
+
+      def self._print_result(result, no_prompt:)
+        framework_label = result.name.to_s.capitalize
+        $stdout.puts "\nDetected: #{framework_label}" unless no_prompt
+
+        if result.initializer_path && !no_prompt
+          $stdout.puts "\nAdd the following to #{result.initializer_path}:"
+          $stdout.puts
+          $stdout.puts result.initializer_snippet
+          $stdout.print "Write to #{result.initializer_path}? [y/N] "
+          answer = $stdin.gets&.strip&.downcase
+          if answer == "y"
+            full_path = File.join(Dir.pwd, result.initializer_path)
+            FileUtils.mkdir_p(File.dirname(full_path))
+            File.write(full_path, result.initializer_snippet)
+            $stdout.puts "Written to #{result.initializer_path}"
+          else
+            $stdout.puts "(Not written — copy the snippet above into your codebase)"
+          end
+        else
+          $stdout.puts result.initializer_snippet
+        end
+        $stdout.puts "\nRun `bundle exec apidepth test` to confirm events are reaching the collector." unless no_prompt
+      end
+    end
+  end
+end

data/lib/apidepth/cli/test_cmd.rb

@@ -0,0 +1,136 @@
+# lib/apidepth/cli/test_cmd.rb
+#
+# Implements `bundle exec apidepth test`.
+#
+# Fires a synthetic event to the collector with `"test": true` in the payload.
+# The collector writes this to `test_events`, not the main events table.
+# Hard 5-second timeout. Per-failure-mode error messages with concrete next steps.
+
+require "net/http"
+require "uri"
+require "json"
+require "apidepth/version"
+
+module Apidepth
+  module CLI
+    module TestCmd
+      DEFAULT_COLLECTOR_URL = "https://collector.apidepth.io".freeze
+      TIMEOUT_SECONDS = 5
+
+      def self.run(argv = ARGV)
+        api_key, collector_url = _load_config(argv)
+
+        unless api_key
+          warn "No API key configured."
+          warn "Run `bundle exec apidepth setup` or set APIDEPTH_API_KEY."
+          exit 1
+        end
+
+        base_url = (collector_url || DEFAULT_COLLECTOR_URL).chomp("/")
+        $stdout.print "Sending test event to collector... "
+
+        begin
+          elapsed = _send_test_event(api_key, base_url)
+          $stdout.puts "✓ received in #{elapsed}ms"
+          $stdout.puts "Visit your dashboard: https://apidepth.io/dashboard"
+        rescue TestError => e
+          $stdout.puts "✗"
+          warn "\n#{e.message}"
+          warn e.hint if e.hint
+          exit 1
+        end
+      end
+
+      class TestError < StandardError
+        attr_reader :hint
+
+        def initialize(msg, hint: nil)
+          super(msg)
+          @hint = hint
+        end
+      end
+
+      def self._load_config(_argv)
+        # Try the SDK configuration first, fall back to environment variable
+        begin
+          require "apidepth"
+          cfg = Apidepth.configuration
+          api_key = cfg.api_key || ENV.fetch("APIDEPTH_API_KEY", nil)
+          collector_url = cfg.collector_url || ENV.fetch("APIDEPTH_COLLECTOR_URL", nil)
+        rescue StandardError
+          api_key = ENV.fetch("APIDEPTH_API_KEY", nil)
+          collector_url = ENV.fetch("APIDEPTH_COLLECTOR_URL", nil)
+        end
+        [api_key, collector_url]
+      end
+
+      def self._send_test_event(api_key, base_url)
+        uri = URI.parse("#{base_url}/v1/events")
+        payload = {
+          batch: [
+            {
+              vendor: "apidepth-test",
+              endpoint: "/test",
+              method: "GET",
+              status: 200,
+              outcome: "success",
+              duration_ms: 1,
+              cold_start: false,
+              env: "test",
+              ts: (Time.now.to_f * 1000).to_i,
+              test: true
+            }
+          ],
+          sdk: { name: "apidepth-ruby", version: Apidepth::VERSION }
+        }.to_json
+
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.read_timeout = TIMEOUT_SECONDS
+        http.open_timeout = TIMEOUT_SECONDS
+
+        request = Net::HTTP::Post.new(uri.path.empty? ? "/" : uri.path)
+        request["Content-Type"]  = "application/json"
+        request["Authorization"] = "Bearer #{api_key}"
+        request.body = payload
+
+        # Bypass our own instrumentation
+        Thread.current[:apidepth_skip] = true
+        response = http.request(request)
+        Thread.current[:apidepth_skip] = false
+
+        case response.code.to_i
+        when 200, 201, 204
+          ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
+        when 401, 403
+          raise TestError.new(
+            "API key not recognised (HTTP #{response.code}).",
+            hint: "Check the key in your initializer matches your dashboard at https://apidepth.io/dashboard/api-keys"
+          )
+        else
+          raise TestError.new(
+            "Collector returned HTTP #{response.code}.",
+            hint: "Check https://status.apidepth.io for service status."
+          )
+        end
+      rescue Net::OpenTimeout, Net::ReadTimeout
+        raise TestError.new(
+          "No response after #{TIMEOUT_SECONDS} seconds.",
+          hint: "Check for a firewall blocking outbound port 443."
+        )
+      rescue OpenSSL::SSL::SSLError => e
+        raise TestError.new(
+          "SSL certificate verification failed: #{e.message}",
+          hint: "Check your Ruby SSL configuration."
+        )
+      rescue Errno::ECONNREFUSED, SocketError => e
+        raise TestError.new(
+          "Could not reach #{uri.host}: #{e.message}",
+          hint: "Check outbound HTTPS (port 443) is allowed from this environment."
+        )
+      end
+    end
+  end
+end

data/lib/apidepth/collector.rb

@@ -189,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
@@ -240,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
 
@@ -292,9 +288,13 @@ module Apidepth
 
       if host.match?(/\A\d+\z/)
         int = host.to_i
-        if int >= 0 && int <= 0xFFFFFFFF
+        if int.between?(0, 0xFFFFFFFF)
           host = [int >> 24, (int >> 16) & 0xFF, (int >> 8) & 0xFF,
                   int & 0xFF].join(".")
+        else
+          raise ArgumentError,
+                "Apidepth collector_url must not target private, loopback, or link-local " \
+                "addresses (got #{url.host.inspect})."
         end
       end
 
@@ -305,6 +305,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/configuration.rb

@@ -1,30 +1,76 @@
 # lib/apidepth/configuration.rb
 
+require "set"
+require "uri"
+
 module Apidepth
   class Configuration
+    # Always ignored regardless of user config. Covers unambiguous loopback
+    # addresses — we deliberately avoid wildcard patterns like *.internal here
+    # because silently swallowing traffic the developer wants to see is worse
+    # than showing mystery vendors. The setup subcommand prompts for custom
+    # patterns interactively.
+    HARD_IGNORED_HOSTS = %w[localhost 127.0.0.1 0.0.0.0 ::1].freeze
+
     attr_accessor :api_key,
-                  :collector_url,
                   :enabled,
                   :flush_interval,
                   :registry_refresh_interval,
                   :registry_cache_path,
-                  :ignored_hosts,
                   :on_flush_error,
                   :environment,      # e.g. "production" — set by Railtie from Rails.env
                   :sample_rate,      # Float 0.0–1.0, default 1.0 (100% of events captured)
                   :extra_vendors     # Hash of vendor_name => host, e.g. { "my-api" => "api.myservice.com" }
 
+    attr_reader :ignored_hosts, :collector_url
+
     def initialize
       @enabled                   = true
       @flush_interval            = 20
       @registry_refresh_interval = 6 * 60 * 60
       @registry_cache_path       = "/tmp/apidepth_registry.json"
       @collector_url             = nil
-      @ignored_hosts             = []
+      @_user_hosts               = []
       @on_flush_error            = nil
       @environment               = nil   # Railtie sets this to Rails.env at boot
       @sample_rate               = 1.0   # capture everything by default
       @extra_vendors             = {}    # customer-defined host mappings
+      _rebuild_ignored_hosts
+    end
+
+    def collector_url=(url)
+      @collector_url = url
+      _rebuild_ignored_hosts
+    end
+
+    def ignored_hosts=(hosts)
+      @_user_hosts = Array(hosts || [])
+      _rebuild_ignored_hosts
+    end
+
+    # Returns true if +host+ should be skipped. Supports glob wildcards
+    # (* matches any sequence, ? matches one character) so customers can
+    # ignore entire internal domains: "*.internal", "*.svc.cluster.local".
+    def ignored_host?(host)
+      @_exact_ignored.include?(host) ||
+        @_glob_ignored.any? { |pat| File.fnmatch(pat, host) }
+    end
+
+    private
+
+    def _rebuild_ignored_hosts
+      all = HARD_IGNORED_HOSTS.dup + (@_user_hosts || [])
+      if @collector_url
+        begin
+          h = URI.parse(@collector_url).host
+          all << h if h
+        rescue URI::InvalidURIError
+          nil
+        end
+      end
+      @_exact_ignored = all.reject { |p| p.include?("*") || p.include?("?") }.to_set
+      @_glob_ignored  = all.select { |p| p.include?("*") || p.include?("?") }
+      @ignored_hosts  = Set.new(all)
     end
   end
 end

data/lib/apidepth/net_http_instrumentation.rb

@@ -10,7 +10,7 @@ module Apidepth
       # 4. Sample rate: probabilistically skip events
       return super if Thread.current[:apidepth_skip]
       return super unless Apidepth.configuration.enabled
-      return super if Apidepth.configuration.ignored_hosts.include?(address)
+      return super if Apidepth.configuration.ignored_host?(address)
       return super unless sampled?
 
       # Snapshot connection state BEFORE calling super.
@@ -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/railtie.rb

@@ -27,6 +27,14 @@ module Apidepth
       # every outbound HTTP request.
       Apidepth.configuration.environment ||= Rails.env.to_s
 
+      # Use a per-app cache path so concurrent apps on the same host don't
+      # share a world-readable /tmp file. Falls back to /tmp only if Rails.root
+      # is somehow unavailable.
+      if defined?(Rails.root) && Rails.root
+        Apidepth.configuration.registry_cache_path ||=
+          Rails.root.join("tmp/apidepth_registry.json").to_s
+      end
+
       Net::HTTP.prepend(Apidepth::NetHTTPInstrumentation)
       Apidepth::VendorRegistry.load_extra_vendors(Apidepth.configuration.extra_vendors)
       Apidepth::RegistryLoader.load_and_start
@@ -41,16 +49,9 @@ module Apidepth
     end
 
     # -------------------------------------------------------------------------
-    # 3. Flush queue on graceful shutdown.
-    #    at_exit fires on SIGTERM → graceful Puma/Unicorn shutdown.
-    #    flush! rescues internally so a network error at shutdown is not fatal.
-    # -------------------------------------------------------------------------
-    config.after_initialize do
-      at_exit { Apidepth::Collector.instance.flush! }
-    end
-
-    # -------------------------------------------------------------------------
-    # 4. Fork safety for Puma cluster mode / Spring.
+    # 3. Shutdown flush + fork safety.
+    #
+    #    at_exit: flush the queue on graceful shutdown (SIGTERM → Puma/Unicorn).
     #
     #    after_fork: reset the Collector singleton so each worker gets a fresh
     #    instance with its own flush thread. The master's flush thread is not
@@ -65,6 +66,8 @@ module Apidepth
     #    ActiveSupport::ForkTracker is available in Rails 7.1+.
     # -------------------------------------------------------------------------
     config.after_initialize do
+      at_exit { Apidepth::Collector.instance.flush! }
+
       if defined?(ActiveSupport::ForkTracker)
         ActiveSupport::ForkTracker.after_fork { Apidepth::Collector.reset! }
       elsif defined?(Puma)

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
@@ -102,6 +103,8 @@ module Apidepth
       # Pure numeric
       if str.match?(/\A\d+(?:\.\d+)?\z/)
         n = str.to_f
+        # >= 1_000_000_000 is a Unix timestamp (seconds since epoch, e.g. "1716000000");
+        # smaller values are seconds-from-now (Retry-After style, e.g. "30").
         return n >= 1_000_000_000 ? (n * 1_000).to_i : now_ms + (n * 1_000).to_i
       end
 

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
@@ -213,6 +231,17 @@ 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.

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.3".freeze
+  VERSION = "0.4.0".freeze
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apidepth
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.4.0
 platform: ruby
 authors:
 - Apidepth
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-05-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -93,19 +94,38 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.65'
+- !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.
 email:
 - hello@apidepth.io
-executables: []
+executables:
+- apidepth
 extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
+- bin/apidepth
 - lib/apidepth.rb
+- lib/apidepth/cli/framework_detector.rb
+- lib/apidepth/cli/setup.rb
+- lib/apidepth/cli/test_cmd.rb
 - lib/apidepth/collector.rb
 - lib/apidepth/configuration.rb
 - lib/apidepth/event.rb
@@ -120,10 +140,11 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://apidepth.io
-  source_code_uri: https://github.com/cmwright33/apidepth-ruby
-  changelog_uri: https://github.com/cmwright33/apidepth-ruby/blob/main/CHANGELOG.md
-  bug_tracker_uri: https://github.com/cmwright33/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
@@ -131,14 +152,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !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: []