peekapi 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7d0778bfe11ccab833051a6848f020268b249a1d3fc039c4c832d07063691b19
+  data.tar.gz: aa6959fb0c64f8e29e8f63651eefbacac4c402523f70a46aab32d44e1ed84d58
+SHA512:
+  metadata.gz: ed73170da82b86dbd618c365b27d38a95ec2f496b9afc1c21bdf3d1ee3bc3cd2a972df0647f8564895eb927746f85c0d46fabcc363e5299b4414370bfd42be2e
+  data.tar.gz: 0d67f21724318299c9441f6400bdaca42fa093352fda737eeab1f57147d155e3ef8439cdc097a320dd3d4f197aa3b91e270b231e032125ec20874ac794426a8c

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 PeekAPI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,152 @@
+# PeekAPI — Ruby SDK
+
+[![Gem](https://img.shields.io/gem/v/peekapi)](https://rubygems.org/gems/peekapi)
+[![license](https://img.shields.io/gem/l/peekapi)](./LICENSE)
+[![CI](https://github.com/peekapi-dev/sdk-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/peekapi-dev/sdk-ruby/actions/workflows/ci.yml)
+
+Zero-dependency Ruby SDK for [PeekAPI](https://peekapi.dev). Rack middleware that works with Rails, Sinatra, Hanami, and any Rack-compatible framework. Rails auto-integrates via Railtie.
+
+## Install
+
+```bash
+gem install peekapi
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "peekapi"
+```
+
+## Quick Start
+
+### Rails (auto-integration)
+
+Set environment variables and the Railtie handles everything:
+
+```bash
+export PEEKAPI_API_KEY=ak_live_xxx
+export PEEKAPI_ENDPOINT=https://...
+```
+
+The SDK auto-inserts Rack middleware and registers a shutdown hook. No code changes needed.
+
+### Rails (manual)
+
+```ruby
+# config/application.rb
+client = PeekApi::Client.new(api_key: "ak_live_xxx")
+config.middleware.use PeekApi::Middleware::Rack, client: client
+```
+
+### Sinatra
+
+```ruby
+require "sinatra"
+require "peekapi"
+
+client = PeekApi::Client.new(api_key: "ak_live_xxx")
+use PeekApi::Middleware::Rack, client: client
+
+get "/api/hello" do
+  json message: "hello"
+end
+```
+
+### Hanami
+
+```ruby
+# config/app.rb
+require "peekapi"
+
+client = PeekApi::Client.new(api_key: "ak_live_xxx")
+middleware.use PeekApi::Middleware::Rack, client: client
+```
+
+### Standalone Client
+
+```ruby
+require "peekapi"
+
+client = PeekApi::Client.new(api_key: "ak_live_xxx")
+
+client.track(
+  method: "GET",
+  path: "/api/users",
+  status_code: 200,
+  response_time_ms: 42,
+)
+
+# Graceful shutdown (flushes remaining events)
+client.shutdown
+```
+
+## Configuration
+
+| Option | Default | Description |
+|---|---|---|
+| `api_key` | required | Your PeekAPI key |
+| `endpoint` | PeekAPI cloud | Ingestion endpoint URL |
+| `flush_interval` | `10` | Seconds between automatic flushes |
+| `batch_size` | `100` | Events per HTTP POST (triggers flush) |
+| `max_buffer_size` | `10_000` | Max events held in memory |
+| `max_storage_bytes` | `5_242_880` | Max disk fallback file size (5MB) |
+| `max_event_bytes` | `65_536` | Per-event size limit (64KB) |
+| `storage_path` | auto | Custom path for JSONL persistence file |
+| `debug` | `false` | Enable debug logging to stderr |
+| `on_error` | `nil` | Callback `Proc` invoked with `Exception` on flush errors |
+
+## How It Works
+
+1. Rack middleware intercepts every request/response
+2. Captures method, path, status code, response time, request/response sizes, consumer ID
+3. Events are buffered in memory and flushed in batches on a background thread
+4. On network failure: exponential backoff with jitter, up to 5 retries
+5. After max retries: events are persisted to a JSONL file on disk
+6. On next startup: persisted events are recovered and re-sent
+7. On SIGTERM/SIGINT: remaining buffer is flushed or persisted to disk
+
+## Consumer Identification
+
+By default, consumers are identified by:
+
+1. `X-API-Key` header — stored as-is
+2. `Authorization` header — hashed with SHA-256 (stored as `hash_<hex>`)
+
+Override with the `identify_consumer` option to use any header:
+
+```ruby
+client = PeekApi::Client.new(
+  api_key: "...",
+  identify_consumer: ->(headers) { headers["x-tenant-id"] }
+)
+```
+
+The callback receives a `Hash` of lowercase header names and should return a consumer ID string or `nil`.
+
+## Features
+
+- **Zero runtime dependencies** — uses only Ruby stdlib (`net/http`, `json`, `digest`)
+- **Background flush** — dedicated thread with configurable interval and batch size
+- **Disk persistence** — undelivered events saved to JSONL, recovered on restart
+- **Exponential backoff** — with jitter, max 5 consecutive failures before disk fallback
+- **SSRF protection** — private IP blocking, HTTPS enforcement (HTTP only for localhost)
+- **Input sanitization** — path (2048), method (16), consumer_id (256) truncation
+- **Per-event size limit** — strips metadata first, drops if still too large (default 64KB)
+- **Graceful shutdown** — SIGTERM/SIGINT handlers + `at_exit` fallback
+- **Rails Railtie** — auto-configures from env vars when Rails is detected
+
+## Requirements
+
+- Ruby >= 3.1
+
+## Contributing
+
+1. Fork & clone the repo
+2. Install dependencies — `bundle install`
+3. Run tests — `bundle exec rake test`
+4. Submit a PR
+
+## License
+
+MIT

data/lib/peekapi/client.rb

@@ -0,0 +1,455 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+require 'digest/sha2'
+require 'tempfile'
+require 'fileutils'
+
+module PeekApi
+  class Client
+    # --- Constants ---
+    DEFAULT_ENDPOINT = 'https://ingest.peekapi.dev/v1/events'
+    DEFAULT_FLUSH_INTERVAL = 15 # seconds
+    DEFAULT_BATCH_SIZE = 250
+    DEFAULT_MAX_BUFFER_SIZE = 10_000
+    DEFAULT_MAX_STORAGE_BYTES = 5_242_880  # 5 MB
+    DEFAULT_MAX_EVENT_BYTES = 65_536       # 64 KB
+    MAX_PATH_LENGTH = 2_048
+    MAX_METHOD_LENGTH = 16
+    MAX_CONSUMER_ID_LENGTH = 256
+    MAX_CONSECUTIVE_FAILURES = 5
+    BASE_BACKOFF_S = 1.0
+    SEND_TIMEOUT_S = 5
+    DISK_RECOVERY_INTERVAL_S = 60
+    RETRYABLE_STATUS_CODES = [429, 500, 502, 503, 504].freeze
+
+    attr_reader :api_key, :endpoint, :identify_consumer, :collect_query_string
+
+    # @param options [Hash]
+    # @option options [String] :api_key  Required. Your API key.
+    # @option options [String] :endpoint Ingestion endpoint URL (default: PeekAPI cloud).
+    # @option options [Numeric] :flush_interval  Seconds between background flushes (default 15).
+    # @option options [Integer] :batch_size       Max events per HTTP POST (default 250).
+    # @option options [Integer] :max_buffer_size  Max buffered events (default 10_000).
+    # @option options [Integer] :max_storage_bytes Max bytes for disk persistence (default 5 MB).
+    # @option options [Integer] :max_event_bytes  Max bytes per single event (default 64 KB).
+    # @option options [String]  :storage_path     Custom path for JSONL persistence file.
+    # @option options [Boolean] :debug            Enable debug logging to $stderr.
+    # @option options [Proc]    :on_error         Callback invoked with Exception on flush failure.
+    def initialize(options = {})
+      @api_key = options[:api_key] || options['api_key']
+      raise ArgumentError, 'api_key is required' if @api_key.nil? || @api_key.empty?
+      raise ArgumentError, 'api_key contains invalid control characters' if @api_key.match?(/[\x00-\x1f\x7f]/)
+
+      raw_endpoint = options[:endpoint] || options['endpoint'] || DEFAULT_ENDPOINT
+      @endpoint = SSRF.validate_endpoint!(raw_endpoint)
+
+      @flush_interval = (options[:flush_interval] || options['flush_interval'] || DEFAULT_FLUSH_INTERVAL).to_f
+      @batch_size = (options[:batch_size] || options['batch_size'] || DEFAULT_BATCH_SIZE).to_i
+      @max_buffer_size = (options[:max_buffer_size] || options['max_buffer_size'] || DEFAULT_MAX_BUFFER_SIZE).to_i
+      @max_storage_bytes =
+        (options[:max_storage_bytes] || options['max_storage_bytes'] || DEFAULT_MAX_STORAGE_BYTES).to_i
+      @max_event_bytes = (options[:max_event_bytes] || options['max_event_bytes'] || DEFAULT_MAX_EVENT_BYTES).to_i
+      @debug = options[:debug] || options['debug'] || false
+      @identify_consumer = options[:identify_consumer] || options['identify_consumer']
+      @on_error = options[:on_error] || options['on_error']
+      # NOTE: increases DB usage — each unique path+query creates a separate endpoint row.
+      @collect_query_string = options[:collect_query_string] || options['collect_query_string'] || false
+
+      # Storage path
+      storage = options[:storage_path] || options['storage_path']
+      if storage
+        @storage_path = storage
+      else
+        h = Digest::SHA256.hexdigest(@endpoint)[0, 12]
+        @storage_path = File.join(Dir.tmpdir, "peekapi-events-#{h}.jsonl")
+      end
+
+      @recovery_path = nil
+
+      # Internal state
+      @buffer = []
+      @mutex = Mutex.new
+      @in_flight = false
+      @consecutive_failures = 0
+      @backoff_until = 0.0
+      @shutdown = false
+      @last_disk_recovery = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      # Load persisted events from disk
+      load_from_disk
+
+      # Background flush thread
+      @done = false
+      @wake = Queue.new
+      @thread = Thread.new { run_loop }
+
+      # Signal handlers (only from main thread)
+      @original_handlers = {}
+      if Thread.current == Thread.main
+        %i[TERM INT].each do |sig|
+          prev = Signal.trap(sig) { signal_handler(sig) }
+          @original_handlers[sig] = prev
+        rescue ArgumentError
+          # Signal not supported on this platform
+        end
+      end
+
+      # at_exit fallback
+      at_exit { shutdown_sync }
+    end
+
+    # Buffer an analytics event. Never raises.
+    def track(event)
+      track_inner(event)
+    rescue StandardError => e
+      warn "peekapi: track() error: #{e.message}" if @debug
+    end
+
+    # Flush buffered events synchronously (blocks until complete).
+    def flush
+      batch = drain_batch
+      return if batch.empty?
+
+      do_flush(batch)
+    end
+
+    # Graceful shutdown: stop thread, final flush, persist remainder.
+    def shutdown
+      return if @shutdown
+
+      @shutdown = true
+
+      # Remove signal handlers
+      @original_handlers.each do |sig, handler|
+        Signal.trap(sig, handler)
+      rescue ArgumentError
+        # ignore
+      end
+      @original_handlers.clear
+
+      # Stop background thread
+      @done = true
+      @wake << :stop
+      @thread.join(5)
+
+      # Final flush
+      flush
+
+      # Persist remainder
+      remaining = @mutex.synchronize do
+        buf = @buffer.dup
+        @buffer.clear
+        buf
+      end
+      persist_to_disk(remaining) unless remaining.empty?
+    end
+
+    private
+
+    # ----------------------------------------------------------------
+    # Track internals
+    # ----------------------------------------------------------------
+
+    def track_inner(event)
+      return if @shutdown
+
+      d = event.is_a?(Hash) ? event.transform_keys(&:to_s) : event.to_h.transform_keys(&:to_s)
+
+      # Sanitize
+      d['method'] = d.fetch('method', '').to_s[0, MAX_METHOD_LENGTH].upcase
+      d['path'] = d.fetch('path', '').to_s[0, MAX_PATH_LENGTH]
+      d['consumer_id'] = d['consumer_id'].to_s[0, MAX_CONSUMER_ID_LENGTH] if d['consumer_id']
+
+      # Timestamp
+      d['timestamp'] ||= Time.now.utc.iso8601(3)
+
+      # Per-event size limit
+      raw = JSON.generate(d)
+      if raw.bytesize > @max_event_bytes
+        d.delete('metadata')
+        raw = JSON.generate(d)
+        if raw.bytesize > @max_event_bytes
+          warn "peekapi: event too large, dropping (#{raw.bytesize} bytes)" if @debug
+          return
+        end
+      end
+
+      @mutex.synchronize do
+        if @buffer.size >= @max_buffer_size
+          # Buffer full — trigger flush instead of dropping
+          @wake << :flush
+          return
+        end
+        @buffer << d
+        size = @buffer.size
+        @wake << :flush if size >= @batch_size
+      end
+    end
+
+    # ----------------------------------------------------------------
+    # Flush internals
+    # ----------------------------------------------------------------
+
+    def drain_batch
+      @mutex.synchronize do
+        return [] if @buffer.empty? || @in_flight
+
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        return [] if now < @backoff_until
+
+        batch = @buffer.shift(@batch_size)
+        @in_flight = true
+        batch
+      end
+    end
+
+    def do_flush(batch)
+      send_events(batch)
+
+      # Success
+      @mutex.synchronize do
+        @consecutive_failures = 0
+        @backoff_until = 0.0
+        @in_flight = false
+      end
+      cleanup_recovery_file
+      warn "peekapi: flushed #{batch.size} events" if @debug
+    rescue NonRetryableError => e
+      @mutex.synchronize { @in_flight = false }
+      persist_to_disk(batch)
+      call_on_error(e)
+      warn "peekapi: non-retryable error, persisted to disk: #{e.message}" if @debug
+    rescue StandardError => e
+      failures = @mutex.synchronize do
+        @consecutive_failures += 1
+        f = @consecutive_failures
+
+        if f >= MAX_CONSECUTIVE_FAILURES
+          @consecutive_failures = 0
+          @in_flight = false
+          persist_to_disk(batch)
+        else
+          # Re-insert at front
+          space = @max_buffer_size - @buffer.size
+          reinsert = batch[0, space]
+          @buffer.unshift(*reinsert) unless reinsert.empty?
+          # Exponential backoff with jitter
+          delay = BASE_BACKOFF_S * (2**(f - 1)) * rand(0.5..1.0)
+          @backoff_until = Process.clock_gettime(Process::CLOCK_MONOTONIC) + delay
+          @in_flight = false
+        end
+
+        f
+      end
+
+      call_on_error(e)
+      warn "peekapi: flush failed (attempt #{failures}): #{e.message}" if @debug
+    end
+
+    def send_events(events)
+      uri = URI.parse(@endpoint)
+      body = JSON.generate(events)
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == 'https')
+      http.open_timeout = SEND_TIMEOUT_S
+      http.read_timeout = SEND_TIMEOUT_S
+
+      request = Net::HTTP::Post.new(uri.request_uri)
+      request['Content-Type'] = 'application/json'
+      request['x-api-key'] = @api_key
+      request['x-peekapi-sdk'] = "ruby/#{VERSION}"
+      request.body = body
+
+      response = http.request(request)
+      status = response.code.to_i
+
+      if status >= 200 && status < 300
+        nil
+      elsif RETRYABLE_STATUS_CODES.include?(status)
+        raise RetryableError, "HTTP #{status}: #{response.body&.[](0, 1024)}"
+      else
+        raise NonRetryableError, "HTTP #{status}: #{response.body&.[](0, 1024)}"
+      end
+    rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ETIMEDOUT,
+           Net::OpenTimeout, Net::ReadTimeout, SocketError => e
+      raise RetryableError, "Network error: #{e.message}"
+    end
+
+    # ----------------------------------------------------------------
+    # Background thread
+    # ----------------------------------------------------------------
+
+    def run_loop
+      until @done
+        # Wait for wake signal or timeout
+        begin
+          @wake.pop(timeout: @flush_interval)
+        rescue ThreadError
+          # Timeout — proceed to flush
+        end
+        break if @done
+
+        batch = drain_batch
+        do_flush(batch) unless batch.empty?
+
+        # Periodically recover persisted events from disk
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        if now - @last_disk_recovery >= DISK_RECOVERY_INTERVAL_S
+          @last_disk_recovery = now
+          load_from_disk
+        end
+      end
+    end
+
+    # ----------------------------------------------------------------
+    # Disk persistence
+    # ----------------------------------------------------------------
+
+    def persist_to_disk(events)
+      return if events.empty?
+
+      path = @storage_path
+      size = begin
+        File.size(path)
+      rescue StandardError
+        0
+      end
+
+      if size >= @max_storage_bytes
+        warn "peekapi: storage file full, dropping #{events.size} events" if @debug
+        return
+      end
+
+      line = "#{JSON.generate(events)}\n"
+      File.open(path, 'a', 0o600) { |f| f.write(line) }
+    rescue StandardError => e
+      warn "peekapi: disk persist failed: #{e.message}" if @debug
+    end
+
+    def load_from_disk
+      recovery = "#{@storage_path}.recovering"
+
+      [recovery, @storage_path].each do |path|
+        next unless File.file?(path)
+
+        begin
+          content = File.read(path, encoding: 'utf-8')
+          events = []
+          content.each_line do |line|
+            line = line.strip
+            next if line.empty?
+
+            begin
+              parsed = JSON.parse(line)
+              if parsed.is_a?(Array)
+                events.concat(parsed)
+              elsif parsed.is_a?(Hash)
+                events << parsed
+              end
+            rescue JSON::ParserError
+              next
+            end
+            break if events.size >= @max_buffer_size
+          end
+
+          unless events.empty?
+            @mutex.synchronize do
+              space = @max_buffer_size - @buffer.size
+              @buffer.concat(events[0, space]) if space.positive?
+            end
+            warn "peekapi: loaded #{events.size} events from disk" if @debug
+          end
+
+          # Rename to .recovering so we don't double-load
+          if path == @storage_path
+            rpath = "#{@storage_path}.recovering"
+            begin
+              File.rename(path, rpath)
+            rescue SystemCallError
+              begin
+                File.delete(path)
+              rescue StandardError
+                nil
+              end
+            end
+            @recovery_path = rpath
+          else
+            @recovery_path = path
+          end
+
+          break # loaded from one file, done
+        rescue StandardError => e
+          warn "peekapi: disk load failed from #{path}: #{e.message}" if @debug
+        end
+      end
+    end
+
+    def cleanup_recovery_file
+      return unless @recovery_path
+
+      begin
+        File.delete(@recovery_path)
+      rescue StandardError
+        nil
+      end
+      @recovery_path = nil
+    end
+
+    # ----------------------------------------------------------------
+    # Signal / at_exit handlers
+    # ----------------------------------------------------------------
+
+    def signal_handler(sig)
+      shutdown_sync
+      # Re-raise with original handler
+      handler = @original_handlers[sig]
+      if handler.is_a?(Proc)
+        handler.call
+      elsif handler == 'DEFAULT'
+        Signal.trap(sig, 'DEFAULT')
+        Process.kill(sig, Process.pid)
+      end
+    end
+
+    def shutdown_sync
+      return if @shutdown
+
+      @shutdown = true
+      @done = true
+      begin
+        @wake << :stop
+      rescue StandardError
+        nil
+      end
+
+      remaining = @mutex.synchronize do
+        buf = @buffer.dup
+        @buffer.clear
+        buf
+      end
+      persist_to_disk(remaining) unless remaining.empty?
+    end
+
+    # ----------------------------------------------------------------
+    # Helpers
+    # ----------------------------------------------------------------
+
+    def call_on_error(exc)
+      return unless @on_error
+
+      begin
+        @on_error.call(exc)
+      rescue StandardError
+        nil
+      end
+    end
+
+    # Error classes
+    class RetryableError < StandardError; end
+    class NonRetryableError < StandardError; end
+  end
+end

data/lib/peekapi/consumer.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'digest/sha2'
+
+module PeekApi
+  module Consumer
+    module_function
+
+    # SHA-256 hash truncated to 12 hex chars, prefixed with "hash_".
+    def hash_consumer_id(raw)
+      digest = Digest::SHA256.hexdigest(raw)[0, 12]
+      "hash_#{digest}"
+    end
+
+    # Identify consumer from request headers.
+    #
+    # Priority:
+    #   1. x-api-key (stored as-is)
+    #   2. Authorization (hashed — contains credentials)
+    #
+    # Headers keys are expected to be lowercase (Rack convention).
+    def default_identify_consumer(headers)
+      api_key = headers['x-api-key']
+      return api_key if api_key && !api_key.empty?
+
+      auth = headers['authorization']
+      return hash_consumer_id(auth) if auth && !auth.empty?
+
+      nil
+    end
+  end
+end

data/lib/peekapi/middleware/rack.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module PeekApi
+  module Middleware
+    # Rack middleware that tracks HTTP request analytics.
+    #
+    # Usage (Sinatra):
+    #
+    #   client = PeekApi::Client.new(api_key: "...", endpoint: "...")
+    #   use PeekApi::Middleware::Rack, client: client
+    #
+    # Usage (Rails):
+    #
+    #   config.middleware.use PeekApi::Middleware::Rack, client: client
+    #
+    class Rack
+      def initialize(app, client: nil)
+        @app = app
+        @client = client
+      end
+
+      def call(env)
+        return @app.call(env) if @client.nil?
+
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        status, headers, body = @app.call(env)
+
+        begin
+          elapsed_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000
+
+          # Measure response size
+          response_size = 0
+          if headers['content-length']
+            response_size = headers['content-length'].to_i
+          else
+            begin
+              body.each { |chunk| response_size += chunk.bytesize }
+            rescue StandardError
+              nil
+            end
+          end
+
+          consumer_id = identify_consumer(env)
+          path = env['PATH_INFO'] || '/'
+          if @client.collect_query_string
+            qs = env['QUERY_STRING'].to_s
+            unless qs.empty?
+              sorted = qs.split('&').sort.join('&')
+              path = "#{path}?#{sorted}"
+            end
+          end
+
+          @client.track(
+            'method' => env['REQUEST_METHOD'] || 'GET',
+            'path' => path,
+            'status_code' => status.to_i,
+            'response_time_ms' => elapsed_ms.round(2),
+            'request_size' => request_size(env),
+            'response_size' => response_size,
+            'consumer_id' => consumer_id
+          )
+        rescue StandardError
+          # Never crash the app
+        end
+
+        [status, headers, body]
+      rescue StandardError => e
+        # If the app raises, still try to track
+        begin
+          elapsed_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000
+          consumer_id = identify_consumer(env)
+          path = env['PATH_INFO'] || '/'
+          if @client.collect_query_string
+            qs = env['QUERY_STRING'].to_s
+            unless qs.empty?
+              sorted = qs.split('&').sort.join('&')
+              path = "#{path}?#{sorted}"
+            end
+          end
+
+          @client.track(
+            'method' => env['REQUEST_METHOD'] || 'GET',
+            'path' => path,
+            'status_code' => 500,
+            'response_time_ms' => elapsed_ms.round(2),
+            'request_size' => request_size(env),
+            'response_size' => 0,
+            'consumer_id' => consumer_id
+          )
+        rescue StandardError
+          # Never crash
+        end
+
+        raise e
+      end
+
+      private
+
+      def identify_consumer(env)
+        headers = extract_headers(env)
+        if @client.identify_consumer
+          @client.identify_consumer.call(headers)
+        else
+          PeekApi::Consumer.default_identify_consumer(headers)
+        end
+      end
+
+      def extract_headers(env)
+        headers = {}
+        env.each do |key, value|
+          next unless key.start_with?('HTTP_')
+
+          header_name = key[5..].downcase.tr('_', '-')
+          headers[header_name] = value
+        end
+        headers
+      end
+
+      def request_size(env)
+        env['CONTENT_LENGTH'].to_i
+      rescue StandardError
+        0
+      end
+    end
+  end
+end

data/lib/peekapi/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module PeekApi
+  class Railtie < Rails::Railtie
+    initializer 'peekapi.configure_middleware' do |app|
+      api_key = ENV.fetch('PEEKAPI_API_KEY', nil)
+      endpoint = ENV.fetch('PEEKAPI_ENDPOINT', nil)
+
+      if api_key && !api_key.empty? && endpoint && !endpoint.empty?
+        client = PeekApi::Client.new(api_key: api_key, endpoint: endpoint)
+        app.middleware.use PeekApi::Middleware::Rack, client: client
+
+        at_exit { client.shutdown }
+      end
+    end
+  end
+end

data/lib/peekapi/ssrf.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+require 'uri'
+
+module PeekApi
+  module SSRF
+    # Private/reserved IPv4 networks
+    PRIVATE_NETWORKS = [
+      IPAddr.new('10.0.0.0/8'),
+      IPAddr.new('172.16.0.0/12'),
+      IPAddr.new('192.168.0.0/16'),
+      IPAddr.new('100.64.0.0/10'),   # CGNAT
+      IPAddr.new('127.0.0.0/8'),     # Loopback
+      IPAddr.new('169.254.0.0/16'),  # Link-local
+      IPAddr.new('0.0.0.0/8') # "This" network
+    ].freeze
+
+    # Private/reserved IPv6 networks
+    PRIVATE_NETWORKS_V6 = [
+      IPAddr.new('::1/128'),         # Loopback
+      IPAddr.new('fe80::/10'),       # Link-local
+      IPAddr.new('fc00::/7'),        # ULA
+      IPAddr.new('::ffff:0:0/96') # IPv4-mapped (checked individually below)
+    ].freeze
+
+    module_function
+
+    # Check if a hostname/IP is a private or reserved address.
+    #
+    # Covers: RFC 1918, CGNAT (100.64/10), loopback, link-local,
+    # IPv6 ULA/link-local, IPv4-mapped IPv6.
+    def private_ip?(host)
+      addr = IPAddr.new(host)
+
+      if addr.ipv6?
+        # Check IPv4-mapped IPv6 (::ffff:x.x.x.x)
+        if addr.ipv4_mapped?
+          mapped = addr.native
+          return PRIVATE_NETWORKS.any? { |net| net.include?(mapped) }
+        end
+        return PRIVATE_NETWORKS_V6.any? { |net| net.include?(addr) }
+      end
+
+      PRIVATE_NETWORKS.any? { |net| net.include?(addr) }
+    rescue IPAddr::InvalidAddressError
+      false
+    end
+
+    # Validate and normalize the ingestion endpoint URL.
+    #
+    # Raises ArgumentError for:
+    #   - Non-HTTPS URLs (except localhost)
+    #   - Private/reserved IP addresses (SSRF protection)
+    #   - Embedded credentials in URL
+    #   - Malformed URLs
+    def validate_endpoint!(endpoint)
+      raise ArgumentError, 'endpoint is required' if endpoint.nil? || endpoint.empty?
+
+      uri = URI.parse(endpoint)
+      raise ArgumentError, "Invalid endpoint URL: #{endpoint}" unless uri.is_a?(URI::HTTP) && uri.host
+
+      hostname = uri.host.downcase
+
+      is_localhost = %w[localhost 127.0.0.1 ::1].include?(hostname)
+
+      unless uri.scheme == 'https' || is_localhost
+        raise ArgumentError, "HTTPS required for non-localhost endpoint: #{endpoint}"
+      end
+
+      raise ArgumentError, 'Endpoint URL must not contain credentials' if uri.user || uri.password
+
+      if !is_localhost && private_ip?(hostname)
+        raise ArgumentError, "Endpoint resolves to private/reserved IP: #{hostname}"
+      end
+
+      endpoint
+    rescue URI::InvalidURIError
+      raise ArgumentError, "Invalid endpoint URL: #{endpoint}"
+    end
+  end
+end

data/lib/peekapi/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PeekApi
+  VERSION = '0.1.0'
+end

data/lib/peekapi.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'peekapi/version'
+require_relative 'peekapi/consumer'
+require_relative 'peekapi/ssrf'
+require_relative 'peekapi/client'
+require_relative 'peekapi/middleware/rack'
+
+# Load Railtie only when Rails is present
+require_relative 'peekapi/railtie' if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: peekapi
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- PeekAPI
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+description: Rack middleware and client for tracking API usage analytics. Works with
+  Rails, Sinatra, Hanami, and any Rack-compatible framework.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/peekapi.rb
+- lib/peekapi/client.rb
+- lib/peekapi/consumer.rb
+- lib/peekapi/middleware/rack.rb
+- lib/peekapi/railtie.rb
+- lib/peekapi/ssrf.rb
+- lib/peekapi/version.rb
+homepage: https://github.com/peekapi-dev/sdk-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/peekapi-dev/sdk-ruby
+  source_code_uri: https://github.com/peekapi-dev/sdk-ruby
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key:
+specification_version: 4
+summary: Zero-dependency Ruby SDK for PeekAPI
+test_files: []