restless-sdk 0.1.0

data/lib/restless/conformance.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require_relative "mask"
+require_relative "redact"
+require_relative "fingerprint"
+require_relative "stack_frames"
+require_relative "har"
+require_relative "request_id"
+require_relative "injection"
+
+module Restless
+  # The shared operation table behind the conformance driver.
+  #
+  # Both `exe/restless-conformance` (the stdio driver the cross-language
+  # harness drives) and `test/test_vectors.rb` (the in-process replay) go
+  # through this one file, so it is impossible for the vectors to describe
+  # behaviour the driver does not exhibit.
+  #
+  # See node-sdk/spec/driver/PROTOCOL.md. Internal: never part of the public
+  # API, never shipped behaviour a customer depends on.
+  module Conformance
+    # An input this implementation's language cannot represent or parse. The
+    # harness records it as a SKIP, not a failure. See CONTRACT.md FP-046 and
+    # PRIM-035.
+    class UnsupportedDialect < StandardError; end
+
+    class UnknownOp < StandardError; end
+
+    module_function
+
+    def dispatch(op, input)
+      input ||= {}
+      case op
+      # --- masking (section 3) ---
+      when "mask"
+        Mask.mask(str_or_nil(input["apiKey"]))
+
+      # --- redaction (section 4) ---
+      when "redactValue"
+        Redact.redact_value(str(input["value"]))
+      when "redactHeaders"
+        Redact.redact_headers(hash(input["headers"]), strs(input["extra"]))
+      when "redactUrl"
+        Redact.redact_url(str(input["url"]), strs(input["extra"]))
+      when "redactBody"
+        body = str_or_nil(input["body"])
+        # An empty string is a VALUE here, distinct from an absent body, so
+        # this is deliberately not collapsed to nil.
+        body.nil? ? nil : Redact.redact_body(body, str_or_nil(input["contentType"]), strs(input["extra"]))
+      when "truncateBody"
+        body = str_or_nil(input["body"])
+        body.nil? ? nil : Redact.truncate_body(body, int(input["maxBytes"]))
+
+      # --- fingerprinting (section 5) ---
+      when "fingerprint"
+        fingerprint(input)
+      when "normalizeRoute"
+        Fingerprint.normalize_route(str_or_nil(input["route"]))
+      when "normalizeMessage"
+        Fingerprint.normalize_message(str(input["message"]))
+      when "projectRelative"
+        # FP-042 is shared across every SDK even though frame PARSING is not
+        # (FP-044/FP-046), so path normalization gets its own dialect-free op.
+        Fingerprint.project_relative(str(input["file"]))
+
+      # --- request ids (section 6) ---
+      when "formatRequestId"
+        RequestId.format_request_id(str(input["rawId"]), str_or_nil(input["prefix"]))
+      when "stripRequestIdPrefix"
+        RequestId.strip_request_id_prefix(str(input["requestId"]))
+      when "requestIdHeaders"
+        RequestId.response_headers(
+          str(input["ourId"]),
+          hash(input["incomingHeaders"]),
+          str_or_nil(input["prefix"]),
+          input.key?("hasApiKey") ? input["hasApiKey"] == true : true
+        )
+
+      # --- injection (section 10) ---
+      when "recoverySlug"
+        Injection.recovery_slug(str_or_nil(input["method"]), str_or_nil(input["path"]))
+
+      # --- HAR (section 7) ---
+      when "harEntry"
+        Har.to_har_entry(hash(input["captured"]))
+
+      else
+        raise UnknownOp, "unknown op: #{op}"
+      end
+    end
+
+    def fingerprint(input)
+      stack = stack_text(input["stackTrace"])
+      if !stack.empty? && v8_dialect?(stack)
+        raise UnsupportedDialect,
+              "unsupported stack dialect: v8 (this SDK parses Ruby backtraces; FP-044/FP-046)"
+      end
+
+      # Parse the stack the way the Rack adapter does. This used to pass
+      # nil, which made the driver structurally incapable of reaching the
+      # stack strategy: the whole path was dead through the harness while
+      # the SDK's own tests, which call StackFrames directly, still passed.
+      # Nothing caught it, because every v8-shaped stack vector is skipped
+      # under FP-046 so the harness never exercises this branch. A driver
+      # that short-circuits the SDK is testing itself.
+      result = Fingerprint.compute(
+        status: int(input["status"]),
+        method: str_or_nil(input["method"]),
+        route: str_or_nil(input["route"]),
+        response_headers: input["responseHeaders"].is_a?(Hash) ? input["responseHeaders"] : nil,
+        response_body: input["responseBody"],
+        stack_frame: stack.empty? ? nil : StackFrames.top_user_frame(stack.split("\n"))
+      )
+      # FP-003: `reason` is human-facing prose, explicitly not contract
+      # surface, so drivers must not emit it.
+      { "strategy" => result.strategy, "key" => result.key }
+    end
+
+    def stack_text(raw)
+      case raw
+      when String then raw
+      when Array  then raw.map(&:to_s).join("\n")
+      else ""
+      end
+    end
+
+    # A v8 frame is `    at fn (/file.js:12:34)`. Ruby backtraces are
+    # `/file.rb:12:in 'fn'`, so anything shaped like the former is out of
+    # dialect and the driver says so rather than guessing.
+    def v8_dialect?(stack)
+      stack.split("\n").any? { |line| line.strip.start_with?("at ") }
+    end
+
+    # --- input coercion -----------------------------------------------------
+    # The protocol represents absence as JSON null.
+
+    def str(value)
+      value.is_a?(String) ? value : ""
+    end
+
+    def str_or_nil(value)
+      value.is_a?(String) ? value : nil
+    end
+
+    def strs(value)
+      return [] unless value.is_a?(Array)
+
+      value.select { |v| v.is_a?(String) }
+    end
+
+    def hash(value)
+      value.is_a?(Hash) ? value : {}
+    end
+
+    def int(value)
+      case value
+      when Integer then value
+      when Float then value.to_i
+      when String then value.to_i
+      else 0
+      end
+    end
+  end
+end

data/lib/restless/env.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Restless
+  # Environment probing: CONFIG-003, CONFIG-004, BATCH-003, BATCH-008.
+  #
+  # All of it is per-language by design (CONTRACT.md section 14); what is
+  # normative is only the effect.
+  module Env
+    # WIRE-005.
+    DEFAULT_BASE_URL = "https://ingress.restless.ai"
+
+    module_function
+
+    # BATCH-003's "language equivalent environment indicator". Ruby has three
+    # spellings in the wild and no single winner, so all three are consulted,
+    # most specific first.
+    def app_env
+      %w[RESTLESS_ENV RACK_ENV RAILS_ENV].each do |name|
+        value = ENV[name]
+        return value if value && !value.empty?
+      end
+      ""
+    end
+
+    def production?
+      app_env == "production"
+    end
+
+    # BATCH-008. Under a test runner, captures are dropped rather than
+    # uploaded, unless RESTLESS_SETUP_MODE=1. Test suites must not hammer
+    # production ingest.
+    #
+    # The constants are checked rather than merely `defined?(Minitest)` at the
+    # top level, because a library can pull minitest in without the process
+    # actually being a test run.
+    def test_run?
+      return true if app_env == "test"
+      return true if defined?(::RSpec::Core)
+      return true if defined?(::Minitest::Test)
+      return true if defined?(::Test::Unit::TestCase)
+
+      false
+    end
+
+    def setup_mode?
+      ENV["RESTLESS_SETUP_MODE"] == "1"
+    end
+
+    # CONFIG-004. `DEBUG` containing `restless` as a whitespace- or
+    # comma-delimited token, or the literal `*`.
+    def debug?
+      flag = ENV["DEBUG"].to_s
+      return true if flag == "*" || flag == "restless"
+
+      flag.split(/[\s,]+/).include?("restless")
+    end
+
+    def debug_log(message)
+      warn("[restless] #{message}") if debug?
+    end
+
+    # CONFIG-001. Explicit key, then RESTLESS_KEY, then README_API_KEY.
+    def resolve_api_key(explicit = nil)
+      [explicit, ENV["RESTLESS_KEY"], ENV["README_API_KEY"]]
+        .find { |v| v && !v.empty? } || ""
+    end
+
+    # CONFIG-003.
+    def resolve_base_url(explicit = nil)
+      return explicit if explicit && !explicit.empty?
+
+      from_env = ENV["RESTLESS_BASE_URL"]
+      return from_env if from_env && !from_env.empty?
+
+      DEFAULT_BASE_URL
+    end
+
+    def localhost?(base_url)
+      base_url.include?("//localhost") || base_url.include?("//127.0.0.1")
+    end
+  end
+end

data/lib/restless/fingerprint.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+require_relative "text"
+
+module Restless
+  # CONTRACT.md section 5. A stable identifier for an HTTP error response,
+  # computed at capture time and shipped with the log.
+  #
+  # The ingest stores it, the dashboard groups by it, a customer attaches a
+  # recovery message to a group, and the SDK injects that message into
+  # matching responses. Nothing re-derives it, so every SDK must agree.
+  module Fingerprint
+    # FP-016. Checked in this order, matched EXACTLY (case-sensitively, no
+    # REDACT-010 normalization).
+    CODE_FIELDS = %w[code error_code errorCode type].freeze
+    NESTED_PATHS = [
+      %w[error code],
+      %w[error type],
+      %w[error error_code]
+    ].freeze
+
+    # FP-015. 1 to 64 code points, identifier-shaped. Keeps `card_declined`
+    # and `AUTH_MISMATCH`, rejects `Your card was declined.` and bare UUIDs.
+    #
+    # `\A...\z` rather than `^...$` (PRIM-005): Ruby's `$` also matches before
+    # a trailing newline, so `"boom\n"` would look like a code here and not in
+    # JavaScript.
+    CODE_RE = /\A[a-zA-Z][a-zA-Z0-9_.\-]*\z/.freeze
+
+    # FP-030. A single path segment that collapses to `:id`. Each pattern is
+    # fully anchored, so this is a whole-segment test rather than a scan.
+    #
+    # The hex ranges are written out rather than using the `i` flag: Ruby's
+    # case-insensitive matching is Unicode case folding, which is a wider
+    # relation than the ASCII-only canonicalization a non-`u` JavaScript regex
+    # performs.
+    SEG_UUID = /\A[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\z/.freeze
+    SEG_NUMERIC = /\A[0-9]+\z/.freeze
+    SEG_LONG_HEX = /\A[0-9a-fA-F]{16,}\z/.freeze
+
+    # FP-042. Project-directory markers.
+    PROJECT_DIRS = %w[src lib app api routes controllers handlers].freeze
+
+    # FP-020. The classes are enumerated (PRIM-001, PRIM-002) rather than
+    # spelled `\w` / `\s`, because those mean different things in different
+    # engines and this key has to be byte-identical in every SDK.
+    WS = Text::WS_CLASS
+    WORD = Text::WORD_CLASS
+
+    RE_URL      = Regexp.new("https?://[^#{WS}]+").freeze
+    RE_EMAIL    = Regexp.new("[^#{WS}]+@[^#{WS}]+\\.[^#{WS}]+").freeze
+    RE_QUOTED   = /['"`][^'"`]*['"`]/.freeze
+    RE_PUNCT    = Regexp.new("[^#{WORD}#{WS}\\-]").freeze
+    RE_WS_RUN   = Regexp.new("[#{WS}]+").freeze
+
+    # FP-020 step 5, and the one regex in this file that cannot be written
+    # against a UTF-8 string.
+    #
+    # Ruby's `\w` is ASCII-only (correct here) but its `\b` is NOT: Onigmo
+    # defines the boundary against the Unicode word property, so `"eA1"` with
+    # a leading accented letter has no boundary before the `A` and the whole
+    # digit-word survives, where JavaScript, Go and Python-with-re.ASCII all
+    # strip it. Applying the match to the UTF-8 BYTES restores JavaScript's
+    # semantics exactly: every non-ASCII character becomes a run of non-word
+    # bytes, which is what a non-`u` JS regex sees in UTF-16 too. The pattern
+    # can only ever match ASCII bytes, so byte slicing and character slicing
+    # coincide and the result is still well-formed UTF-8.
+    RE_DIGIT_WORD = Regexp.new("\\b[#{WORD}\\-]*[0-9][#{WORD}\\-]*\\b").freeze
+
+    Result = Struct.new(:strategy, :key, :reason)
+
+    module_function
+
+    # FP-010. Strategies are tried in this exact order; the first that yields
+    # a key wins.
+    #
+    # `stack_frame` is the already-extracted `{file:, fn:}` for the frame
+    # nearest the throw site (FP-043). Frame PARSING is per-language
+    # (FP-044) and lives in `Restless::StackFrames`, so this function stays
+    # dialect-free.
+    def compute(status:, method: nil, route: nil, response_headers: nil,
+                response_body: nil, stack_frame: nil)
+      method = "GET" if method.nil? || method.empty? # FP-011
+
+      # FP-012. 404 is intercepted BEFORE the code-based strategies: a generic
+      # `not_found` code is the same on every route, so grouping 404s by code
+      # is useless for recovery.
+      if status == 404
+        normalized = route.nil? || route.empty? ? "" : normalize_route(route)
+        # FP-014: the parameter test runs on the NORMALIZED route.
+        if normalized.include?(":") || normalized.include?("{")
+          return Result.new(
+            "resource", "404:resource",
+            "404 on a parameterized route (#{method} #{normalized}); " \
+            "the addressed resource was not found"
+          )
+        end
+        reason = if normalized.empty?
+                   "404 on a path that matched no route; the endpoint does not exist"
+                 else
+                   "404 on #{method} #{normalized}; no resource at this path"
+                 end
+        return Result.new("endpoint", "404:endpoint", reason)
+      end
+
+      # 1. Explicit header. Fully deterministic; the customer opted in.
+      header_code = read_header_code(response_headers)
+      if header_code
+        return Result.new("header", "#{status}:#{header_code}",
+                          %(x-restless-error-code header: "#{header_code}"))
+      end
+
+      # 2. Code-like field in the body. Stripe/AWS/Twilio-shaped APIs land here.
+      body_code = read_body_code(response_body)
+      if body_code
+        return Result.new("body-code", "#{status}:#{body_code}",
+                          %(code field in body: "#{body_code}"))
+      end
+
+      # 3. Stack trace (5xx with a thrown exception). File + function only:
+      # FP-041 forbids a line number, so adding a comment above a `raise`
+      # cannot split an error group.
+      if status >= 500 && stack_frame
+        return Result.new(
+          "stack", "#{status}:#{stack_frame[:file]}:#{stack_frame[:fn]}",
+          "top user frame: #{stack_frame[:fn]} in #{stack_frame[:file]}"
+        )
+      end
+
+      # 4. Normalized message + templated route.
+      normalized_route = normalize_route(route)
+      msg = normalize_message(extract_message(response_body))
+      unless msg.empty?
+        return Result.new("message", "#{status}:#{method}:#{normalized_route}:#{msg}",
+                          %(message normalized to "#{msg}"))
+      end
+
+      # 5. Status + route only. Coarse, but it groups all unhandled responses.
+      Result.new("route-only", "#{status}:#{method}:#{normalized_route}",
+                 "no usable code or message; falling back to status + route")
+    end
+
+    # FP-017. The header name is matched case-insensitively.
+    def read_header_code(headers)
+      return nil unless headers.is_a?(Hash)
+
+      lower = {}
+      headers.each { |k, v| lower[Text.full_lower(k.to_s)] = v }
+      value = lower["x-restless-error-code"]
+      looks_like_code?(value) ? value : nil
+    end
+
+    def read_body_code(body)
+      return nil unless body.is_a?(Hash)
+
+      CODE_FIELDS.each do |field|
+        value = body[field]
+        return value if looks_like_code?(value)
+      end
+
+      NESTED_PATHS.each do |path|
+        value = body
+        path.each { |segment| value = value.is_a?(Hash) ? value[segment] : nil }
+        return value if looks_like_code?(value)
+      end
+
+      nil
+    end
+
+    # FP-015.
+    def looks_like_code?(value)
+      value.is_a?(String) &&
+        !value.empty? &&
+        value.length <= 64 &&
+        CODE_RE.match?(value)
+    end
+
+    # FP-018. Body itself if it is a string; then `message`; then `error` if
+    # it is a string; then `error.message`. Anything else yields no message.
+    def extract_message(body)
+      return "" if body.nil? || body == false
+      return body if body.is_a?(String)
+      return "" unless body.is_a?(Hash)
+
+      message = body["message"]
+      return message if message.is_a?(String)
+
+      nested = body["error"]
+      return nested if nested.is_a?(String)
+      if nested.is_a?(Hash) && nested["message"].is_a?(String)
+        return nested["message"]
+      end
+
+      ""
+    end
+
+    # FP-020. The 12 steps, in exactly this order.
+    def normalize_message(msg)
+      return "" if msg.nil? || msg.empty?
+
+      s = Text.full_lower(msg)          # 1
+      s = s.gsub(RE_URL, " ")           # 2
+      s = s.gsub(RE_EMAIL, " ")         # 3
+      s = s.gsub(RE_QUOTED, " ")        # 4
+      s = strip_digit_words(s)          # 5
+      s = s.gsub(RE_PUNCT, " ")         # 6
+      s = s.gsub(RE_WS_RUN, " ")        # 7
+      s = Text.ws_trim(s)               # 8
+      s.split(/ /, -1)                  # 9  (never `split(" ")`: awk mode)
+       .reject { |w| w.length <= 1 }    # 10
+       .first(6)                        # 11
+       .join("-")                       # 12
+    end
+
+    # FP-021. Whole words containing a digit are stripped, not bare digits:
+    # `abc123` reduced to `abc` would still influence the key, so grouping
+    # would break whenever the surrounding id changed.
+    #
+    # See RE_DIGIT_WORD for why this runs against the byte string.
+    def strip_digit_words(str)
+      str.dup
+         .force_encoding(Encoding::ASCII_8BIT)
+         .gsub(RE_DIGIT_WORD, " ")
+         .force_encoding(Encoding::UTF_8)
+    end
+
+    # FP-030..FP-032.
+    def normalize_route(route)
+      return "/" if route.nil? || route.empty?
+
+      # `split("/", -1)`: Ruby drops trailing empty fields without the
+      # negative limit, so `/users/` would lose its trailing segment and stop
+      # matching JavaScript.
+      segments = route.split("/", -1)
+      # FP-031: index 0 is the text BEFORE the first "/" and is never
+      # normalized, which keeps a bare "123" route untouched.
+      (1...segments.length).each do |i|
+        segments[i] = ":id" if id_segment?(segments[i])
+      end
+      segments.join("/")
+    end
+
+    def id_segment?(segment)
+      SEG_UUID.match?(segment) ||
+        SEG_NUMERIC.match?(segment) ||
+        SEG_LONG_HEX.match?(segment)
+    end
+
+    # FP-042. Strip the machine-specific path prefix down to a project-relative
+    # path, so the same source file produces the same key on a laptop and in
+    # production.
+    #
+    # The LAST project directory wins, not the first, and the difference is the
+    # whole point:
+    #
+    #   /Users/dev/proj/src/db/users.rb     -> src/db/users.rb
+    #   /app/src/db/users.rb                -> src/db/users.rb
+    #   /opt/render/project/src/db/users.rb -> src/db/users.rb
+    #
+    # A first-match rule returns `app/src/db/users.rb` for the middle one,
+    # because the deployment root IS the first match. Docker's conventional
+    # `WORKDIR /app` and Heroku both root there, so first-match made production
+    # disagree with a laptop for the same file across the most common
+    # containerized layout there is, defeating the only thing this function
+    # exists to do.
+    #
+    # The trade is that a nested layout (`/proj/src/a/src/x.rb`) collapses to
+    # `src/x.rb` rather than `src/a/src/x.rb`. That is far rarer than an `/app`
+    # root and is still machine-independent, which is the property being
+    # protected.
+    def project_relative(file)
+      # `split("/", -1)`: Ruby drops trailing empty fields without the negative
+      # limit, so `/proj/src/` would come back as ["", "proj", "src"] and take
+      # the fallback branch where JavaScript, which keeps the empty field,
+      # matches `src` and returns "src/".
+      segments = file.split("/", -1)
+      # Stop before the final component: a project dir has to have something
+      # after it to be a directory at all. A negative start makes `downto`
+      # yield nothing, which is correct for a bare filename.
+      (segments.length - 2).downto(0) do |i|
+        return segments[i..-1].join("/") if PROJECT_DIRS.include?(segments[i])
+      end
+
+      segments.last(2).join("/")
+    end
+  end
+end

data/lib/restless/har.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative "text"
+require_relative "redact"
+
+module Restless
+  # CONTRACT.md section 7. Captured traffic rides inside a HAR 1.2 envelope.
+  module Har
+    module_function
+
+    # HAR-005. Parse the query into ordered name/value pairs.
+    #
+    # Hand-rolled rather than delegating to a URI library so it shares the
+    # exact decoding rule with `redact_url`, and so a port does not have to
+    # reproduce WHATWG URL parsing to agree with us. Duplicate names are
+    # preserved, which a hash-based parse would lose.
+    def parse_query_string(url)
+      q = url.index("?")
+      return [] if q.nil?
+
+      rest = url[(q + 1)..-1] || ""
+      hash = rest.index("#")
+      query = hash.nil? ? rest : rest[0, hash]
+      return [] if query.empty?
+
+      out = []
+      query.split("&", -1).each do |pair|
+        next if pair.empty?
+
+        eq = pair.index("=")
+        if eq.nil?
+          out << { "name" => Redact.percent_decode(pair), "value" => "" }
+        else
+          out << {
+            "name" => Redact.percent_decode(pair[0, eq]),
+            "value" => Redact.percent_decode(pair[(eq + 1)..-1] || "")
+          }
+        end
+      end
+      out
+    end
+
+    def headers_to_list(headers)
+      headers.map { |name, value| { "name" => name, "value" => value } }
+    end
+
+    # `captured` is a hash with string keys:
+    #   requestId, startedAt, duration, routePattern?,
+    #   request: {method, url, headers, body?}, response: {status, headers, body?}
+    #
+    # A nil body means "no body captured" and is distinct from an empty one:
+    # HAR-011 makes the first report -1 and the second 0.
+    def to_har_entry(captured)
+      request = captured["request"] || {}
+      response = captured["response"] || {}
+      request_headers = request["headers"] || {}
+      response_headers = response["headers"] || {}
+
+      request_body = request["body"]
+      response_body = response["body"]
+
+      req_content_type = request_headers["content-type"]
+      req_content_type = "" if req_content_type.nil? || req_content_type == ""
+      # HAR-007: mimeType falls back when the response has no content type.
+      res_content_type = response_headers["content-type"]
+      if res_content_type.nil? || res_content_type == ""
+        res_content_type = "application/octet-stream"
+      end
+
+      duration = captured["duration"] || 0
+
+      har_request = {
+        "method" => request["method"],
+        "url" => request["url"],
+        "httpVersion" => "HTTP/1.1", # HAR-003 (reserved)
+        "headers" => headers_to_list(request_headers), # HAR-004
+        "queryString" => parse_query_string(request["url"].to_s)
+      }
+      # HAR-006: postData is present ONLY when a request body was captured.
+      # The reference tests truthiness, so an empty-string body produces no
+      # postData but still reports bodySize 0.
+      unless request_body.nil? || request_body.empty?
+        har_request["postData"] = {
+          "mimeType" => req_content_type,
+          "text" => request_body
+        }
+      end
+      har_request["headersSize"] = -1 # HAR-012
+      har_request["bodySize"] =
+        request_body.nil? ? -1 : Text.utf8_length(request_body) # HAR-010/011
+
+      {
+        "startedDateTime" => captured["startedAt"], # HAR-001
+        "time" => duration, # HAR-002
+        "request" => har_request,
+        "response" => {
+          "status" => response["status"],
+          "statusText" => "", # HAR-008 (reserved)
+          "httpVersion" => "HTTP/1.1",
+          "headers" => headers_to_list(response_headers),
+          "content" => {
+            "size" => response_body.nil? ? 0 : Text.utf8_length(response_body),
+            "mimeType" => res_content_type,
+            "text" => response_body.nil? ? "" : response_body
+          },
+          "headersSize" => -1,
+          "bodySize" => response_body.nil? ? -1 : Text.utf8_length(response_body)
+        },
+        "timings" => { "send" => 0, "wait" => duration, "receive" => 0 }
+      }
+    end
+  end
+end