restless-sdk 0.1.0

data/lib/restless/injection.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "text"
+require_relative "request_id"
+
+module Restless
+  # CONTRACT.md section 10. What the SDK adds to the customer's own responses.
+  module Injection
+    module_function
+
+    # INJECT-005. Legible URL slug for the recovery dig-in path, derived from
+    # method + route pattern: `GET /car/{id}` becomes `get-car-id`.
+    #
+    # The server resolves it back to an OpenAPI operation by matching the same
+    # scheme, so this MUST stay in sync with the app's `recoverySlug`
+    # (INJECT-007).
+    def recovery_slug(method = nil, path = nil)
+      m = Text.full_lower(method.to_s)
+      # JavaScript's `trim` strips the PRIM-002 set; Ruby's `strip` strips a
+      # different one in both directions.
+      p = Text.ws_trim(path.to_s)
+      return "unknown" if m.empty? || p.empty?
+
+      flat = p.gsub(%r{[/{}:]+}, "-")
+              .gsub(/[^a-zA-Z0-9\-]/, "")
+              .gsub(/-+/, "-")
+      # `\A` / `\z`, not `^` / `$`: Ruby's are line anchors (PRIM-005).
+      flat = flat.sub(/\A-/, "").sub(/-\z/, "")
+      flat.empty? ? m : "#{m}-#{flat}"
+    end
+
+    # INJECT-001..004, INJECT-006. Returns the headers to set plus the `debug`
+    # object to merge into a JSON body, or nil when nothing should be injected.
+    def build(status:, request_id:, base_url:, prefix: nil, recovery: nil,
+              method: nil, path: nil, docs_url: nil)
+      return nil if status < 400 # INJECT-001
+
+      display = RequestId.format_request_id(request_id, prefix)
+      # INJECT-006: the server-supplied docsUrl when one has been learned,
+      # else the configured base URL. One batch of staleness after a
+      # docs-domain change is accepted.
+      log_host = docs_url.nil? || docs_url.empty? ? base_url : docs_url
+      log_url = "#{log_host}/logs/#{request_id}"
+      debug_cmd = "npx api debug #{display}"
+
+      # Per-request "dig-in" URL the calling agent (often an AI) can fetch for
+      # concrete next steps. Deliberately LEGIBLE: it ends in `<slug>.md` so it
+      # reads as documentation rather than a tracking blob. The first segment
+      # is the same public request id already in `debug.log`, so the dashboard
+      # can correlate the follow-up without any new tracking token.
+      slug = recovery_slug(method, path)
+      dig_in = "For the accepted parameters and next steps, " \
+               "fetch #{log_host}/p/#{request_id}/#{slug}.md"
+      # INJECT-004: a cached recovery message precedes the dig-in line,
+      # separated by a blank line.
+      recovery_text =
+        if recovery.nil? || recovery.empty?
+          dig_in
+        else
+          "#{recovery}\n\n#{dig_in}"
+        end
+
+      {
+        headers: {
+          "x-log-url" => log_url, # INJECT-002
+          "x-debug" => debug_cmd
+        },
+        debug: {
+          "log" => log_url,
+          "cli" => debug_cmd,
+          "recovery" => recovery_text
+        }
+      }
+    end
+
+    # INJECT-003. Merge `debug` into the response body ONLY when the body is a
+    # JSON OBJECT (not an array, not a scalar) and the content type says JSON.
+    #
+    # Returns the original body untouched on any parse failure: SAFETY-001
+    # outranks everything here.
+    def apply_body(body, content_type, debug)
+      return body if body.nil? || body.empty? || debug.nil?
+      return body unless Text.full_lower(content_type.to_s).include?("application/json")
+
+      begin
+        parsed = JSON.parse(body, max_nesting: false)
+      rescue StandardError
+        return body
+      end
+      return body unless parsed.is_a?(Hash)
+
+      JSON.generate(parsed.merge("debug" => debug))
+    rescue StandardError
+      body
+    end
+  end
+end

data/lib/restless/mask.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "digest"
+require "base64"
+
+require_relative "text"
+
+module Restless
+  # CONTRACT.md section 3. The masked end-user API key.
+  #
+  #     sha512-<base64(sha512(utf8(key)))>?<last4>
+  #
+  # This is the lookup key the ingest and the dashboard index on, so it has to
+  # be byte-identical across every SDK and the server. Server-side reference:
+  # `logs/src/clickhouse/models/request.ts`.
+  module Mask
+    # MASK-011. Setup-time placeholders the CLI (or a copy-pasted doc) leaves
+    # in curl examples. Hashing them would cluster unrelated requests under an
+    # arbitrary tail. Compared case-sensitively and exactly.
+    PLACEHOLDER_KEYS = %w[
+      API_KEY_HERE
+      YOUR_API_KEY
+      YOUR_KEY
+      REPLACE_ME
+    ].freeze
+
+    # MASK-013. Redaction may run before masking in some call paths; hashing a
+    # sentinel produces a meaningless key.
+    #
+    # `\A...\z` rather than `^...$`: PRIM-005. Ruby's `$` also matches before a
+    # trailing newline, so `"<REDACTED:5>\n"` would pass through unmasked here
+    # and be hashed in JavaScript.
+    REDACTED_RE = /\A<REDACTED:[0-9]+(?::[^>]*)?>\z/.freeze
+
+    module_function
+
+    # MASK-001. Returns nil for "no key" (MASK-010).
+    def mask(api_key)
+      return nil if api_key.nil? || api_key == ""
+      return nil if PLACEHOLDER_KEYS.include?(api_key)
+
+      # MASK-012. Idempotent for its own output.
+      return api_key if api_key.start_with?("sha512-")
+      return api_key if REDACTED_RE.match?(api_key)
+
+      # MASK-004: hash the UTF-8 encoding. MASK-002: SHA-512.
+      # MASK-003: STANDARD base64 with padding, not base64url.
+      digest = Base64.strict_encode64(Digest::SHA512.digest(Text.to_utf8(api_key)))
+
+      # MASK-006: last 4 CODE POINTS of the plaintext, never a byte or
+      # UTF-16 code-unit slice. Keys shorter than 4 contribute all of theirs.
+      last4 = api_key.chars.last(4).join
+
+      "sha512-#{digest}?#{last4}"
+    end
+  end
+end

data/lib/restless/rack.rb

@@ -0,0 +1,374 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "capture"
+require_relative "injection"
+require_relative "request_id"
+require_relative "stack_frames"
+require_relative "text"
+
+module Restless
+  # Rack middleware. One interface covers Rails, Sinatra, Hanami, Grape,
+  # Roda and anything else that speaks Rack.
+  #
+  # CONTRACT.md section 14 is explicit that adapters are per-language and not
+  # standardised, so this does NOT reproduce the Node SDK's duck-typed
+  # universal middleware or its framework list. Rack is the one interface
+  # worth having in Ruby.
+  #
+  # SAFETY-001 governs everything below: no code path here may propagate an
+  # exception into the customer's app or response lifecycle. The only
+  # exception deliberately re-raised is the customer's own.
+  class Middleware
+    # SAFETY-007. Bodies over this are recorded WITHOUT a body; headers are
+    # still stamped. Capture must never buffer unboundedly.
+    MAX_CAPTURE_BYTES = 1024 * 1024
+
+    # SAFETY-007. Streaming responses are passed straight through, never
+    # buffered.
+    STREAMING_TYPES = %w[text/event-stream].freeze
+
+    # SAFETY-006. A serialized parse of multipart is meaningless.
+    SKIPPED_REQUEST_TYPES = %w[multipart/form-data].freeze
+
+    # Framework hooks that carry the matched route template, most specific
+    # first. Override wholesale with the `route:` lambda.
+    ROUTE_ENV_KEYS = %w[
+      restless.route
+      sinatra.route
+      action_dispatch.route_uri_pattern
+      grape.routing_args
+    ].freeze
+
+    # Frameworks that catch the exception themselves still leave it in the
+    # env, which is the only way to reach the `stack` fingerprint strategy
+    # for a handled 500.
+    EXCEPTION_ENV_KEYS = %w[
+      restless.exception
+      sinatra.error
+      action_dispatch.exception
+      rack.exception
+    ].freeze
+
+    # `use client.rack` hands Rack::Builder something that responds to
+    # `new(app)`; this is that something.
+    class Factory
+      def initialize(client, options)
+        @client = client
+        @options = options
+      end
+
+      def new(app)
+        Middleware.new(app, @client, @options)
+      end
+    end
+
+    def self.factory(client, **options)
+      Factory.new(client, options)
+    end
+
+    # Read-only view of the request, handed to the setup callback.
+    class RequestInfo
+      attr_reader :env
+
+      def initialize(env)
+        @env = env
+      end
+
+      # Case-insensitive, accepts either `Authorization` or `authorization`.
+      def header(name)
+        key = "HTTP_#{name.to_s.upcase.tr('-', '_')}"
+        return @env[key] if @env.key?(key)
+        return @env["CONTENT_TYPE"] if key == "HTTP_CONTENT_TYPE"
+        return @env["CONTENT_LENGTH"] if key == "HTTP_CONTENT_LENGTH"
+
+        nil
+      end
+      alias [] header
+
+      def request_method
+        @env["REQUEST_METHOD"]
+      end
+
+      def path
+        "#{@env['SCRIPT_NAME']}#{@env['PATH_INFO']}"
+      end
+
+      def query_string
+        @env["QUERY_STRING"].to_s
+      end
+
+      def url
+        Middleware.full_url(@env)
+      end
+    end
+
+    def initialize(app, client, options = {})
+      @app = app
+      @client = client
+      @engine = client.engine
+      @route_resolver = options[:route]
+      @capture_request_body =
+        options.key?(:capture_request_body) ? options[:capture_request_body] : true
+    end
+
+    def call(env)
+      started_at = Time.now
+      clock = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      request = RequestInfo.new(env)
+
+      setup = safely({}) { @engine.resolve(request) }
+      our_id = RequestId.new_request_id
+
+      block = safely(nil) { CaptureEngine.resolve_block(setup["block"]) }
+      if block
+        # SETUP-004: reject before the handler runs.
+        return finish(env, setup, our_id, started_at, clock, block_response(block),
+                      request_body: capture_request_body(env), stack_frame: nil)
+      end
+
+      request_body = capture_request_body(env)
+
+      begin
+        status, headers, body = @app.call(env)
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        # The customer's exception. Capture it with the stack so the
+        # fingerprint keys on the RAISING method (FP-043), then re-raise so
+        # their own error handling is completely unaffected.
+        frame = safely(nil) { StackFrames.from_exception(e) }
+        safely(nil) do
+          finish(env, setup, our_id, started_at, clock,
+                 [500, { "content-type" => "application/json" },
+                  [JSON.generate({ "error" => "Internal Server Error" })]],
+                 request_body: request_body, stack_frame: frame, inject: false)
+        end
+        raise
+      end
+
+      # A framework that handled the exception itself still left it here.
+      frame = nil
+      if status.to_i >= 500
+        error = EXCEPTION_ENV_KEYS.map { |k| env[k] }.find { |v| v.respond_to?(:backtrace) }
+        frame = safely(nil) { StackFrames.from_exception(error) } if error
+      end
+
+      finish(env, setup, our_id, started_at, clock, [status, headers, body],
+             request_body: request_body, stack_frame: frame)
+    end
+
+    def self.full_url(env)
+      scheme = env["rack.url_scheme"] || "http"
+      host = env["HTTP_HOST"] || "#{env['SERVER_NAME']}:#{env['SERVER_PORT']}"
+      url = +"#{scheme}://#{host}#{env['SCRIPT_NAME']}#{env['PATH_INFO']}"
+      query = env["QUERY_STRING"].to_s
+      url << "?" << query unless query.empty?
+      url
+    end
+
+    # `GET /pets/:id` (Sinatra) and `/pets/:id(.:format)` (Rails) both become
+    # `/pets/{id}`, which is what every other Restless SDK reports for the
+    # same endpoint. Without that the same API produces two different
+    # `routePattern` values depending on the language it was written in.
+    def self.normalize_route_pattern(pattern)
+      route = Text.ws_trim(pattern.to_s)
+      return nil if route.empty?
+
+      route = route.sub(/\A[A-Z]+[ \t]+/, "")     # strip the leading method
+      route = route.sub(/\(\.:format\)\z/, "")    # Rails' optional format
+      route = route.gsub(/:([A-Za-z_][A-Za-z0-9_]*)/, '{\1}')
+      route.empty? ? nil : route
+    end
+
+    private
+
+    def route_pattern(env)
+      if @route_resolver
+        resolved = safely(nil) { @route_resolver.call(env) }
+        return Middleware.normalize_route_pattern(resolved) if resolved
+      end
+
+      ROUTE_ENV_KEYS.each do |key|
+        value = env[key]
+        next unless value.is_a?(String) && !value.empty?
+
+        normalized = Middleware.normalize_route_pattern(value)
+        return normalized if normalized
+      end
+      nil
+    end
+
+    def block_response(block)
+      body = JSON.generate({ "error" => block[:message] })
+      [block[:status],
+       { "content-type" => "application/json",
+         "content-length" => body.bytesize.to_s },
+       [body]]
+    end
+
+    # Assemble the capture, inject, record, and hand the response back.
+    def finish(env, setup, our_id, started_at, clock, response,
+               request_body:, stack_frame:, inject: true)
+      status, headers, body = response
+      headers = normalize_headers(headers)
+
+      body_text, body = read_response_body(body, headers)
+      duration = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - clock) * 1000).round
+
+      captured = {
+        "requestId" => our_id,
+        "startedAt" => Text.iso8601_millis(started_at),
+        "duration" => duration,
+        "routePattern" => route_pattern(env),
+        "request" => {
+          "method" => env["REQUEST_METHOD"],
+          "url" => Middleware.full_url(env),
+          "headers" => request_headers(env),
+          "body" => request_body
+        },
+        "response" => {
+          "status" => status.to_i,
+          "headers" => headers,
+          "body" => body_text
+        },
+        "user" => setup
+      }
+      captured.delete("routePattern") if captured["routePattern"].nil?
+
+      options = @engine.uploader.options
+      # REQID-010, REQID-011.
+      headers.merge!(RequestId.response_headers(
+                       our_id, request_headers(env),
+                       options[:request_id_prefix], options[:has_api_key]
+                     ))
+
+      if inject && status.to_i >= 400
+        # INJECT-009: the fingerprint is computed against the customer's RAW
+        # response, snapshotted before any injected header or body field.
+        fingerprint = @engine.compute_fingerprint(captured, stack_frame)
+        if fingerprint
+          captured["errorFingerprint"] = CaptureEngine.wire_fingerprint(fingerprint)
+          # INJECT-010: computed once and reused for both the recovery lookup
+          # and the upload payload.
+          recovery = @engine.lookup_recovery(fingerprint.key)
+        end
+
+        injection = safely(nil) do
+          Injection.build(
+            status: status.to_i,
+            request_id: our_id,
+            base_url: options[:base_url],
+            prefix: options[:request_id_prefix],
+            recovery: recovery,
+            method: env["REQUEST_METHOD"],
+            path: captured["routePattern"],
+            docs_url: @engine.docs_url
+          )
+        end
+
+        if injection
+          headers.merge!(injection[:headers]) # INJECT-002
+          rewritten = Injection.apply_body(body_text, headers["content-type"],
+                                           injection[:debug]) # INJECT-003
+          if rewritten && !rewritten.equal?(body_text) && rewritten != body_text
+            body = [rewritten]
+            # INJECT-008: recompute Content-Length or the client truncates
+            # mid-JSON.
+            headers["content-length"] = rewritten.bytesize.to_s if headers.key?("content-length")
+          end
+        end
+      end
+
+      safely(nil) { @engine.record(captured, stack_frame: stack_frame) }
+
+      [status, headers, body]
+    rescue StandardError => e
+      Env.debug_log("middleware finish failed: #{e.class}: #{e.message}")
+      response
+    end
+
+    # Rack 2 hands out `Content-Type`, Rack 3 requires `content-type`.
+    # Downcasing is safe in both directions: header names are
+    # case-insensitive on the wire, and every lookup below assumes lowercase.
+    def normalize_headers(headers)
+      out = {}
+      (headers || {}).each do |name, value|
+        out[name.to_s.downcase] = value.is_a?(Array) ? value.join(", ") : value.to_s
+      end
+      out
+    end
+
+    def request_headers(env)
+      out = {}
+      env.each do |key, value|
+        next unless key.is_a?(String)
+
+        if key.start_with?("HTTP_") && key != "HTTP_VERSION"
+          # HAR-004: duplicate values arrive already joined by the server.
+          out[key[5..-1].downcase.tr("_", "-")] = value.to_s
+        elsif key == "CONTENT_TYPE" || key == "CONTENT_LENGTH"
+          out[key.downcase.tr("_", "-")] = value.to_s
+        end
+      end
+      out
+    end
+
+    def capture_request_body(env)
+      return nil unless @capture_request_body
+
+      content_type = env["CONTENT_TYPE"].to_s.downcase
+      # SAFETY-006.
+      return nil if SKIPPED_REQUEST_TYPES.any? { |t| content_type.include?(t) }
+
+      input = env["rack.input"]
+      return nil if input.nil?
+      # Reading a non-rewindable input would consume the customer's body.
+      # Rack 3 does not guarantee rewindability, so skip rather than break
+      # the app -- SAFETY-001 outranks capture completeness.
+      return nil unless input.respond_to?(:rewind) && input.respond_to?(:read)
+
+      raw = input.read(MAX_CAPTURE_BYTES + 1)
+      input.rewind
+      return nil if raw.nil? || raw.empty?
+      return nil if raw.bytesize > MAX_CAPTURE_BYTES
+
+      Text.to_utf8(raw)
+    rescue StandardError => e
+      Env.debug_log("request body capture failed: #{e.class}: #{e.message}")
+      nil
+    end
+
+    # Returns [captured_text_or_nil, body_to_return].
+    def read_response_body(body, headers)
+      content_type = headers["content-type"].to_s.downcase
+      # SAFETY-007: never buffer a stream.
+      return [nil, body] if STREAMING_TYPES.any? { |t| content_type.include?(t) }
+      # Rack 3 streaming bodies respond to `call`, not `each`.
+      return [nil, body] unless body.respond_to?(:each)
+
+      chunks = []
+      size = 0
+      body.each do |chunk|
+        chunks << chunk
+        size += chunk.to_s.bytesize
+      end
+      body.close if body.respond_to?(:close)
+
+      return [nil, chunks] if size > MAX_CAPTURE_BYTES
+
+      joined = chunks.join
+      [joined.empty? ? nil : Text.to_utf8(joined), chunks]
+    rescue StandardError => e
+      Env.debug_log("response body capture failed: #{e.class}: #{e.message}")
+      [nil, body]
+    end
+
+    # SAFETY-001.
+    def safely(fallback)
+      yield
+    rescue StandardError => e
+      Env.debug_log("swallowed: #{e.class}: #{e.message}")
+      fallback
+    end
+  end
+end