apidepth 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48290c633c238b8bbfcaff2a1f98cb4ffa26a3d0c02853ef0f345841425b463e
-  data.tar.gz: b3564982b79da91fe2ad976c913aa8bf94efbd35928f78a52d934e43b02eb4d0
+  metadata.gz: 69006b5a613f60527b41de94536502c71526d9e9dd274625c7f235d03624d194
+  data.tar.gz: 76941c29e08ec0c4a40e310a017f57f9c32f1c90cc37820ce794834c90ad8d15
 SHA512:
-  metadata.gz: 7a932948137e2d17f75d346686e60f0287c06f2702ec03a7adf3458c521604d9691e7803921726d391f1e161c59f77bce15063a5eeda93800093d7bb7d75e3ac
-  data.tar.gz: d262bd3e9b0668a1f5c667160efba8a41b99b850fcf177d3ccf3a5398b7179a005d9b141fb1ef62e1e3a86d55533fce7cf7eaf96c71f01a059ba96d98888ff9e
+  metadata.gz: d5e0babbb150df6d38aa32c83df843da7d7991c8fd17be37010d1454eaef8a936b878c4efdc8eb3373d714c70e75a124a99ada7d3fa43e248c4eb464920f833c
+  data.tar.gz: fd034d845f43a8f34af26f6cf99067ec51c690168744d379d19727de2c383ea88a8e9ffd89dbdc8ffc79b6fbd2e73fa29f684b1415c7708c1c88bc78ee01f52b

data/README.md

@@ -56,6 +56,46 @@ Get your API key at [apidepth.io](https://apidepth.io).
 
 ---
 
+## CLI
+
+The gem ships two subcommands for setup and connectivity verification.
+
+### `bundle exec apidepth setup`
+
+Interactive wizard that detects your framework (Rails, Sinatra, or generic), generates the correct initializer snippet, and optionally writes it to disk.
+
+```bash
+bundle exec apidepth setup
+```
+
+For CI/CD pipelines, skip all prompts:
+
+```bash
+bundle exec apidepth setup --api-key $APIDEPTH_API_KEY --no-prompt
+```
+
+| Flag | Description |
+|---|---|
+| `--api-key <key>` | Inject your API key into the generated snippet. |
+| `--no-prompt` | Non-interactive mode — print snippet to stdout and exit. |
+| `--framework <name>` | Override auto-detection (`rails`, `sinatra`, `generic`). |
+| `--ignored-hosts <patterns>` | Comma-separated host patterns to add to `ignored_hosts` (glob wildcards supported). |
+| `--collector-url <url>` | Override the collector URL in the generated snippet. |
+
+### `bundle exec apidepth test`
+
+Sends a synthetic test event to the collector and confirms the pipeline is working end-to-end. Reads `APIDEPTH_API_KEY` (and optionally `APIDEPTH_COLLECTOR_URL`) from the environment. Prints the round-trip time on success, or a per-failure-mode error message with next steps on failure.
+
+```bash
+bundle exec apidepth test
+# ✓ received in 142ms
+# Visit your dashboard: https://apidepth.io/dashboard
+```
+
+Exits with code 1 on any error (bad key, unreachable, SSL failure, timeout).
+
+---
+
 ## Configuration
 
 All options with their defaults:

data/lib/apidepth/configuration.rb

@@ -18,9 +18,10 @@ module Apidepth
                   :registry_refresh_interval,
                   :registry_cache_path,
                   :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" }
+                  :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" }
+                  :capture_model_names # Boolean — read model field from AI vendor JSON responses
 
     attr_reader :ignored_hosts, :collector_url
 
@@ -35,6 +36,7 @@ module Apidepth
       @environment               = nil   # Railtie sets this to Rails.env at boot
       @sample_rate               = 1.0   # capture everything by default
       @extra_vendors             = {}    # customer-defined host mappings
+      @capture_model_names       = true  # read model field from AI vendor JSON responses
       _rebuild_ignored_hosts
     end
 

data/lib/apidepth/model_name_extractor.rb

@@ -0,0 +1,68 @@
+# lib/apidepth/model_name_extractor.rb
+require "set"
+#
+# Extracts the model name from AI vendor JSON response bodies.
+#
+# WHY response body rather than headers?
+# AI vendors (OpenAI, Anthropic, Gemini, Mistral, Cohere) return the active
+# model in the response body ({"model":"claude-3-opus-20240229",...}), not in
+# headers. This is the only reliable source.
+#
+# WHY only for known AI vendor hosts?
+# Body reads add a tiny overhead. Scoping to a hard-coded allowlist keeps the
+# hot path for non-AI vendors completely unaffected.
+#
+# Body safety: Net::HTTP::HTTPResponse#body memoizes after the first read.
+# Calling it here and returning the response to the application is safe — the
+# application receives the same cached body bytes.
+#
+# Streaming safety: streamed responses have Content-Type: text/event-stream, not
+# application/json. The content-type guard exits early before any body read.
+#
+# Extraction strategy (RUBY-018): scan for the JSON "model": "<value>" field
+# with a linear regex rather than JSON.parse-ing a truncated body. Embeddings
+# and batch responses place `model` AFTER a large `data` array, so the old
+# parse-after-8KB-truncate approach produced invalid JSON and silently dropped
+# the model. The regex finds the first structural model field wherever it sits.
+
+module Apidepth
+  module ModelNameExtractor
+    AI_VENDOR_HOSTS = %w[
+      api.openai.com
+      api.anthropic.com
+      generativelanguage.googleapis.com
+      api.mistral.ai
+      api.cohere.com
+    ].to_set.freeze
+
+    # Upper bound on how far into the body we scan for the model field. 256 KB
+    # comfortably covers realistic embeddings/batch responses (a few-input OpenAI
+    # embeddings body is ~23 KB) while bounding work on pathologically large bodies.
+    MODEL_SCAN_MAX_BYTES = 262_144
+
+    # Matches a structural JSON "model": "<value>" pair. Escaped quotes inside
+    # string values appear as \" so this never matches a "model" mentioned inside
+    # another JSON string. First match wins (the top-level model field).
+    MODEL_RE = /"model"\s*:\s*"([^"]+)"/.freeze
+
+    def self.extract(host, response)
+      return nil unless Apidepth.configuration.capture_model_names
+      # Case-insensitive host match (RUBY-019): DNS hostnames are case-insensitive,
+      # so a vendor declared with mixed case (e.g. via extra_vendors) still matches.
+      return nil unless AI_VENDOR_HOSTS.include?(host.to_s.downcase)
+      return nil unless response["content-type"]&.include?("application/json")
+
+      body = response.body
+      return nil if body.nil? || body.empty?
+
+      scan = body.byteslice(0, MODEL_SCAN_MAX_BYTES).to_s.dup.force_encoding("UTF-8")
+      match = MODEL_RE.match(scan)
+      match && !match[1].empty? ? match[1] : nil
+    rescue StandardError
+      # Covers malformed/invalid-encoding bodies and non-buffered streaming
+      # bodies (e.g. Net::ReadAdapter, which has no #empty?). Returning nil keeps
+      # the surrounding telemetry event intact rather than dropping it (RUBY-017).
+      nil
+    end
+  end
+end

data/lib/apidepth/net_http_instrumentation.rb

@@ -72,21 +72,23 @@ module Apidepth
 
       now_ms = Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
       rl = Apidepth::RateLimitHeaders.extract(response, now_ms)
+      model_name = Apidepth::ModelNameExtractor.extract(address, response)
+
+      event_attrs = {
+        vendor: vendor,
+        endpoint: normalized_path,
+        method: req.method,
+        status: status,
+        outcome: outcome,
+        duration_ms: duration_ms,
+        cold_start: cold_start,
+        env: resolve_env,
+        ts: now_ms
+      }.merge(rl || {})
+      event_attrs[:model_name] = model_name if model_name
 
       Apidepth::Collector.instance.record(
-        Apidepth::Event.build(
-          {
-            vendor: vendor,
-            endpoint: normalized_path,
-            method: req.method,
-            status: status,
-            outcome: outcome,
-            duration_ms: duration_ms,
-            cold_start: cold_start,
-            env: resolve_env,
-            ts: now_ms
-          }.merge(rl || {})
-        )
+        Apidepth::Event.build(event_attrs)
       )
     rescue StandardError => e
       Apidepth.logger&.debug("[Apidepth] Instrumentation error: #{e.class}: #{e.message}")

data/lib/apidepth/vendor_registry.rb

@@ -58,12 +58,22 @@ module Apidepth
       }
     }.freeze
 
+    # Generic fallbacks applied after vendor-specific patterns. Canonical across
+    # all SDKs (XSDK-NORM) — see apidepth-collector/tests/fixtures/endpoint_cases.json.
+    # The :token rule requires at least one digit (?=[a-z0-9]*\d) so 24+ char
+    # readable slugs are left intact while opaque IDs/tokens — which effectively
+    # always contain a digit — are collapsed. UUID is case-insensitive.
     GENERIC_PATTERNS = [
-      [%r{/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}}, "/:uuid"],
-      [%r{/\d{4,}},        "/:id"],
-      [%r{/[a-z0-9]{24,}}, "/:token"]
+      [%r{/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}}i, "/:uuid"],
+      [%r{/\d{4,}}, "/:id"],
+      [%r{/(?=[a-z0-9]*\d)[a-z0-9]{24,}}i, "/:token"]
     ].freeze
 
+    # Upper bound on path length we run the generic normalizers against. Realistic
+    # paths are well under 4 KB; above this we skip normalization because the
+    # :token lookahead is O(n^2) worst-case on a long digit-free alnum run.
+    GENERIC_MAX_PATH = 4096
+
     # 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")
@@ -157,7 +167,13 @@ module Apidepth
                 next
               end
 
-              [Regexp.new(match), rule["replace"].to_s]
+              # ReDoS protection: bake a per-pattern timeout into the Regexp at
+              # compile time on Ruby >= 3.2 (RUBY-020). This bounds match time for
+              # a pathological pattern from a compromised/misconfigured registry
+              # without mutating the process-global Regexp.timeout on every request
+              # (which would impose the limit on unrelated regexes in other threads).
+              compiled = RUBY_GTE_3_2 ? Regexp.new(match, timeout: 0.001) : Regexp.new(match)
+              [compiled, rule["replace"].to_s]
             rescue RegexpError => e
               Apidepth.logger&.warn(
                 "[Apidepth] Skipping invalid pattern for #{Apidepth.sanitize_log(slug)} " \
@@ -179,25 +195,23 @@ module Apidepth
       # 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.
+      # ReDoS protection: each compiled pattern carries its own 1ms timeout (set
+      # in build_patterns on Ruby >= 3.2), so a pathological pattern from a
+      # compromised or misconfigured registry cannot stall the request thread
+      # indefinitely — without touching the process-global Regexp.timeout
+      # (RUBY-020). On older Ruby the timeout is absent; use a trusted,
+      # internally-reviewed registry source. A Regexp::TimeoutError that trips
+      # here propagates to identify's caller, which already rescues StandardError.
       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)
+        return path if path.length > GENERIC_MAX_PATH
+
         GENERIC_PATTERNS.reduce(path) do |p, (pattern, replacement)|
           p.gsub(pattern, replacement)
         end

data/lib/apidepth/version.rb

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

data/lib/apidepth.rb

@@ -1,14 +1,15 @@
 # lib/apidepth.rb
 #
 # Main entry point. Require order matters:
-#   1. version       — no dependencies
-#   2. configuration — no dependencies
-#   3. vendor_registry — no dependencies, boots from BUNDLED_BASELINE immediately
-#   4. rate_limit_headers — no dependencies; used by net_http_instrumentation
-#   5. net_http_instrumentation — depends on vendor_registry + collector (via lazy reference)
-#   5. collector     — depends on configuration
-#   6. registry_loader — depends on collector + vendor_registry
-#   7. railtie       — depends on all of the above; only loaded in a Rails context
+#   1. version             — no dependencies
+#   2. configuration       — no dependencies
+#   3. vendor_registry     — no dependencies, boots from BUNDLED_BASELINE immediately
+#   4. rate_limit_headers  — no dependencies; used by net_http_instrumentation
+#   5. model_name_extractor — no dependencies; used by net_http_instrumentation
+#   6. net_http_instrumentation — depends on vendor_registry + collector (via lazy reference)
+#   7. collector           — depends on configuration
+#   8. registry_loader     — depends on collector + vendor_registry
+#   9. railtie             — depends on all of the above; only loaded in a Rails context
 
 require "logger"
 require "apidepth/version"
@@ -16,6 +17,7 @@ require "apidepth/configuration"
 require "apidepth/event"
 require "apidepth/vendor_registry"
 require "apidepth/rate_limit_headers"
+require "apidepth/model_name_extractor"
 require "apidepth/net_http_instrumentation"
 require "apidepth/collector"
 require "apidepth/registry_loader"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apidepth
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Apidepth
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-30 00:00:00.000000000 Z
+date: 2026-06-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -129,6 +129,7 @@ files:
 - lib/apidepth/collector.rb
 - lib/apidepth/configuration.rb
 - lib/apidepth/event.rb
+- lib/apidepth/model_name_extractor.rb
 - lib/apidepth/net_http_instrumentation.rb
 - lib/apidepth/railtie.rb
 - lib/apidepth/rate_limit_headers.rb