fingerly 0.1.0

data/lib/fingerly/client.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "time"
+
+module Fingerly
+  # Reads events for one organization and environment.
+  #
+  # Build one and reuse it: it is safe to share between threads and fibers,
+  # and connections come from one pool per process. Secret keys and webhook
+  # secrets belong in server-side code only; a browser must never see either.
+  #
+  #   fingerly = Fingerly::Client.new(secret_key: ENV.fetch("FINGERLY_SECRET_KEY"))
+  #   event = fingerly.events.get(request_id)
+  class Client
+    include Redacted
+
+    DEFAULT_TIMEOUT = 10
+    DEFAULT_API_VERSION = "v1"
+    USER_AGENT = "fingerly-ruby/#{VERSION}".freeze
+
+    # An error body is small; anything larger is not one worth reading.
+    MAX_ERROR_BODY = 1 << 20
+
+    # @return [Events] event reads under this client's secret key
+    attr_reader :events
+
+    # @param secret_key [String] a server-only key,
+    #   +fly_sk_{environment}_…+, whose prefix names the environment read
+    # @param endpoint [String, nil] overrides the Fingerly API origin, for a
+    #   local or self-hosted API
+    # @param api_version [String] the API route version
+    # @param timeout [Numeric] the deadline for each request in seconds,
+    #   covering the response body
+    # @param configure_http [Proc, nil] receives the +Net::HTTP+ before it
+    #   connects, for a proxy or a custom TLS setup. Timeouts set there are
+    #   replaced: the deadline belongs to this client.
+    # @raise [ConfigurationError] if a key, endpoint, version or timeout is
+    #   invalid. Nothing is sent until then.
+    def initialize(secret_key:, endpoint: nil, api_version: DEFAULT_API_VERSION,
+                   timeout: DEFAULT_TIMEOUT, configure_http: nil)
+      # The key is validated even when an endpoint is given, so a public, proxy
+      # or management key can never reach an API that would accept it.
+      Config.parse_key(secret_key, Config::SECRET)
+      origin = Config.normalize_endpoint(endpoint || Config::DEFAULT_ENDPOINT)
+
+      @secret_key = secret_key
+      @origin = origin
+      @base_path = "/api/#{Config.normalize_api_version(api_version)}"
+      @transport = Transport.new(
+        origin: origin,
+        timeout: Config.positive_seconds(timeout, "timeout"),
+        configure_http: configure_http
+      )
+      @events = Events.new(self)
+      freeze
+    end
+
+    # Closes the idle connections to this client's destination, which every
+    # client and proxy in the process shares.
+    #
+    # Reusing the client afterwards simply opens another one, so this is for a
+    # script that is finished rather than something a server needs to call.
+    def close
+      @transport.close
+    end
+
+    # Performs one authenticated GET and returns the decoded body.
+    #
+    # Never retries a delivered request, and the deadline covers reading the
+    # body.
+    #
+    # @api private
+    def get(path)
+      result = @transport.call(
+        Net::HTTP::Get, @base_path + path,
+        "x-api-key" => @secret_key,
+        "accept" => "application/json",
+        "user-agent" => USER_AGENT
+      )
+      raise api_error(result) unless (200..299).cover?(result.status)
+
+      decode(result.body)
+    end
+
+    private
+
+    def redacted_fields
+      [["endpoint", @origin + @base_path], ["secret_key", Redacted::MARK]]
+    end
+
+    # @raise [Error] if the body is not JSON, which means it did not come from
+    #   the Fingerly API
+    def decode(body)
+      parsed = JSON.parse(body)
+      return parsed if parsed.is_a?(Hash)
+
+      raise Error, "Fingerly API returned a body that is not an object"
+    rescue JSON::ParserError
+      raise Error, "Fingerly API returned a body that is not JSON"
+    end
+
+    # Maps a failed response to a redacted APIError.
+    #
+    # Only the status and the structured fields the API documents are
+    # surfaced. The raw body is deliberately dropped rather than echoed.
+    def api_error(result)
+      envelope = error_envelope(result.body)
+      error = envelope["error"]
+      error = {} unless error.is_a?(Hash)
+
+      APIError.new(
+        status: result.status,
+        code: redact(error["code"]),
+        # Redacting the rendered JSON covers nested values without walking the
+        # tree.
+        details: error.key?("details") ? redact_tree(error["details"]) : nil,
+        request_id: redact(envelope["request_id"] || header(result, "x-request-id")),
+        retry_after: retry_after(header(result, "retry-after"))
+      )
+    end
+
+    def header(result, name)
+      value = Array(result.headers[name]).first
+      value.is_a?(String) && !value.empty? ? value : nil
+    end
+
+    # Retry-After is either whole seconds or an HTTP date.
+    #
+    # @return [Integer, nil] seconds from now, never negative
+    def retry_after(value)
+      return nil if value.nil?
+      return Integer(value, 10) if value.match?(/\A\d{1,10}\z/)
+
+      [(Time.httpdate(value) - Time.now).ceil, 0].max
+    rescue ArgumentError
+      nil
+    end
+
+    def error_envelope(body)
+      return {} if body.empty? || body.bytesize > MAX_ERROR_BODY
+
+      parsed = JSON.parse(body)
+      parsed.is_a?(Hash) ? parsed : {}
+    rescue JSON::ParserError
+      # A non-JSON body still reports its HTTP status.
+      {}
+    end
+
+    def redact(value)
+      value.is_a?(String) ? value.gsub(@secret_key, "[redacted]") : value
+    end
+
+    def redact_tree(value)
+      return nil if value.nil?
+
+      # Any JSON value is legal at the top level, so a details field that is a
+      # bare string or number survives the round trip too. quirks_mode is not
+      # passed: the json gem dropped the keyword in 3.0, and it has not been
+      # needed since 2.0.
+      JSON.parse(JSON.generate(value).gsub(@secret_key, "[redacted]"))
+    rescue JSON::ParserError, JSON::GeneratorError
+      nil
+    end
+  end
+
+  # Reads events stored for the organization and environment of the client's
+  # secret key. Reached as +fingerly.events+.
+  class Events
+    include Redacted
+
+    # @api private
+    def initialize(client)
+      @client = client
+      freeze
+    end
+
+    # Fetches one event by request id.
+    #
+    # @param request_id [String] the +request_id+ returned by identification
+    # @return [Event]
+    # @raise [APIError] on any non-2xx response. +404 event_pending+
+    #   ({APIError#pending?}) means the event was accepted and is still being
+    #   recorded: retry after {APIError#retry_after} seconds.
+    #   +404 event_not_found+ means a request id that was never issued, or one
+    #   past retention.
+    # @raise [TimeoutError] if the request exceeds the client timeout
+    def get(request_id)
+      raise ConfigurationError, "request_id is required" if request_id.to_s.empty?
+
+      Event.new(@client.get("/events/#{Events.escape(request_id)}"))
+    end
+
+    # Lists events within the retention window, newest first.
+    #
+    # An unset filter is not sent, so the server applies its own default.
+    #
+    # @param from [Time, nil] start of the window; defaults to 24 hours ago,
+    #   and may be at most 30 days wide and start at most 30 days ago
+    # @param to [Time, nil] end of the window; defaults to now
+    # @param page [Integer, nil] one-based page number
+    # @param limit [Integer, nil] rows per page; the server caps it at 200
+    # @param visitor [String, nil] restricts the listing to one exact visitor
+    # @param level [String, nil] restricts it to +low+, +medium+ or +high+
+    # @return [EventPage]
+    # @raise [APIError] on any non-2xx response
+    def list(from: nil, to: nil, page: nil, limit: nil, visitor: nil, level: nil)
+      query = {
+        "from" => from && Events.instant(from),
+        "to" => to && Events.instant(to),
+        "page" => page && Config.positive_int(page, "page"),
+        "limit" => limit && Config.positive_int(limit, "limit"),
+        "visitor" => visitor,
+        "level" => level
+      }.compact
+
+      suffix = query.empty? ? "" : "?#{URI.encode_www_form(query)}"
+      EventPage.new(@client.get("/events#{suffix}"))
+    end
+
+    # Percent-encodes a request id into exactly one path segment.
+    #
+    # Only RFC 3986 unreserved characters survive, so a slash cannot escape the
+    # segment and a space cannot become a +.
+    #
+    # @api private
+    def self.escape(value)
+      # Byte by byte, so an id that is not valid UTF-8 is escaped like any
+      # other rather than raising from the regular expression.
+      value.to_s.b.gsub(/[^A-Za-z0-9\-._~]/n) { |byte| format("%%%02X", byte.ord) }
+    end
+
+    # The API accepts RFC 3339 only, and reads it as an absolute instant.
+    #
+    # @api private
+    def self.instant(value)
+      raise ConfigurationError, "from and to must be Time values" unless value.is_a?(Time)
+
+      # getutc, because Time#utc converts the caller's own object in place and
+      # raises on a frozen one.
+      value.getutc.iso8601(3)
+    end
+
+    private
+
+    def redacted_fields
+      []
+    end
+  end
+end

data/lib/fingerly/config.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require "uri"
+
+module Fingerly
+  # Validation of caller-supplied configuration.
+  #
+  # Everything here runs before any network access, so a misconfigured client
+  # fails while it is being built rather than mid-request or against the wrong
+  # host.
+  #
+  # @api private
+  module Config
+    # Key kinds Fingerly issues: browser public, server secret, and proxy.
+    PUBLIC = "pk"
+    SECRET = "sk"
+    PROXY = "px"
+
+    # Anchored with \A and \z rather than ^ and $, which in Ruby match at every
+    # line boundary. A key with a newline in it would otherwise pass.
+    KEY = /\Afly_(pk|sk|px)_(production|staging|development)_[A-Za-z0-9_-]+\z/
+    API_VERSION = /\Av[1-9][0-9]*\z/
+
+    LABELS = { PUBLIC => "public", SECRET => "secret", PROXY => "proxy" }.freeze
+
+    # The one Fingerly API origin.
+    DEFAULT_ENDPOINT = "https://api.fingerly.io"
+
+    # The environment a Fingerly key is scoped to.
+    Scope = Struct.new(:environment)
+
+    module_function
+
+    # Parses a Fingerly key and asserts it is of the expected kind.
+    #
+    # @param key [String, nil] the raw key, such as +fly_sk_production_…+
+    # @param expected [String] the kind the caller requires
+    # @return [Scope] the environment the key is scoped to
+    # @raise [ConfigurationError] if the key is malformed or of another kind,
+    #   so a public, proxy or management key can never reach an API that would
+    #   accept it
+    def parse_key(key, expected)
+      scope = scope_for(key, expected)
+      return scope if scope
+
+      raise ConfigurationError,
+            "A valid Fingerly #{LABELS.fetch(expected)} key is required"
+    end
+
+    # The same, without raising.
+    #
+    # @return [Scope, nil] nil when the key is not of the expected kind
+    def scope_for(key, expected)
+      # As bytes, because the proxy passes the browser's own header here and a
+      # string that is not valid in its encoding raises from a regular
+      # expression instead of failing to match.
+      match = key.is_a?(String) ? KEY.match(key.b) : nil
+      return nil unless match && match[1] == expected
+
+      Scope.new(match[2])
+    end
+
+    # Validates a caller-supplied API origin.
+    #
+    # Credentials, queries and fragments are refused: they would be attached to
+    # every authenticated request, and embedded credentials would leak on a
+    # redirect.
+    #
+    # @return [String] the origin without trailing slashes
+    # @raise [ConfigurationError] if the URL is malformed or carries any of those
+    def normalize_endpoint(value)
+      uri = begin
+        URI.parse(value.to_s)
+      rescue URI::InvalidURIError
+        nil
+      end
+      usable = uri.is_a?(URI::HTTP) && !uri.host.to_s.empty? &&
+               uri.userinfo.nil? && uri.query.nil? && uri.fragment.nil?
+      unless usable
+        raise ConfigurationError,
+              "endpoint must be an HTTP(S) URL without credentials, query, or fragment"
+      end
+
+      value.to_s.sub(%r{/+\z}, "")
+    end
+
+    # Validates an API route version before it is spliced into a URL.
+    #
+    # @raise [ConfigurationError] if the version is not of that shape
+    def normalize_api_version(version)
+      return version if version.is_a?(String) && API_VERSION.match?(version)
+
+      raise ConfigurationError, %(api_version must be a version such as "v1" or "v2")
+    end
+
+    # Validates a duration option, in seconds.
+    #
+    # @raise [ConfigurationError] if it is not a positive number
+    def positive_seconds(value, name)
+      return value if value.is_a?(Numeric) && value.positive?
+
+      raise ConfigurationError, "#{name} must be a positive number of seconds"
+    end
+
+    # Validates a byte count option.
+    #
+    # @raise [ConfigurationError] if it is not a positive integer
+    def positive_int(value, name)
+      return value if value.is_a?(Integer) && value.positive?
+
+      raise ConfigurationError, "#{name} must be a positive integer"
+    end
+
+    # Validates the path the dashboard issued for a proxy and drops trailing
+    # slashes. It is matched exactly: the proxy answers that path and nothing
+    # under it.
+    def normalize_path(value)
+      path = value.to_s.strip.sub(%r{/+\z}, "")
+      segments = path.split("/", -1).drop(1)
+      usable = path.match?(%r{\A(/[A-Za-z0-9._~-]+)+\z}) &&
+               !segments.intersect?(%w[. ..])
+      raise ConfigurationError, "path must be an absolute URL path such as /k7x2qm4a" unless usable
+
+      path
+    end
+
+    # Whether a value is exactly one IPv4 or IPv6 address and nothing else: no
+    # list, port, prefix length, zone, padding or whitespace.
+    def ip_literal?(value)
+      return false unless value.is_a?(String) && value.bytesize <= 45
+      return false unless value.b.match?(/\A[0-9A-Fa-f:.]+\z/)
+
+      IPAddr.new(value)
+      true
+    rescue IPAddr::Error
+      false
+    end
+
+    # Whether a value is printable ASCII, so it cannot inject a header of its
+    # own.
+    def header_safe?(value)
+      value.is_a?(String) && value.b.match?(/\A[\x20-\x7e]*\z/)
+    end
+  end
+end

data/lib/fingerly/errors.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Fingerly
+  # Base class for every failure this SDK raises at run time.
+  #
+  # A bad option raises {ConfigurationError} instead, which is an
+  # +ArgumentError+: a key that was never valid is a programming mistake, not
+  # something a retry or a rescue around the call site can help with.
+  class Error < StandardError; end
+
+  # Raised when a credential, route, limit or callback is unusable.
+  #
+  # It derives from +ArgumentError+, so ordinary Ruby handling applies, and it
+  # is raised while the client or proxy is being built, before any network
+  # access.
+  class ConfigurationError < ArgumentError; end
+
+  # Raised for any non-2xx response from the Fingerly API.
+  #
+  # The message carries only the HTTP status. Response bodies are never
+  # echoed, and any occurrence of the secret key in the metadata is redacted.
+  #
+  #   begin
+  #     event = fingerly.events.get(request_id)
+  #   rescue Fingerly::APIError => e
+  #     return "retry" if e.pending? # not recorded yet: retry after e.retry_after
+  #     return "refuse" if e.event_not_found?
+  #     raise
+  #   end
+  class APIError < Error
+    # @return [Integer] the HTTP status code
+    attr_reader :status
+
+    # @return [String, nil] the stable machine-readable code, such as
+    #   +event_not_found+
+    attr_reader :code
+
+    # @return [Object, nil] extra context from the error body; its shape
+    #   depends on {#code}
+    attr_reader :details
+
+    # @return [String, nil] the server-side trace id to quote in support
+    #   requests
+    attr_reader :request_id
+
+    # @return [Integer, nil] seconds to wait before trying again, from the
+    #   +Retry-After+ header, or nil when the response carried none. Sent with
+    #   429, +404 event_pending+ and some 503 answers; the SDK never retries by
+    #   itself.
+    attr_reader :retry_after
+
+    # @api private
+    def initialize(status:, code: nil, details: nil, request_id: nil, retry_after: nil)
+      @status = status
+      @code = code
+      @details = details
+      @request_id = request_id
+      @retry_after = retry_after
+      described = "Fingerly API returned HTTP #{status}"
+      super(code ? "#{described} (#{code})" : described)
+    end
+
+    # Whether this is a read for an event that does not exist: a request id
+    # that was never issued, or one past retention.
+    #
+    # It is false for {#pending?}: that event exists and is still being
+    # recorded.
+    #
+    # @return [Boolean]
+    def event_not_found?
+      status == 404 && code == "event_not_found"
+    end
+
+    # Whether this is a read for an event the API accepted but has not
+    # recorded yet (+404 event_pending+).
+    #
+    # Nothing is decided yet: read again after {#retry_after} seconds, or
+    # verify asynchronously. The SDK never retries by itself.
+    #
+    # @return [Boolean]
+    def pending?
+      status == 404 && code == "event_pending"
+    end
+  end
+
+  # Raised when a request does not finish within its time limit.
+  #
+  # The deadline covers reading the response body, not only the headers.
+  class TimeoutError < Error; end
+
+  # Raised when the Fingerly API could not be reached at all.
+  #
+  # A DNS failure, a refused connection or a TLS error arrives here.
+  class ConnectionError < Error; end
+end

data/lib/fingerly/models.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Fingerly
+  # One signal group that contributed to an event's suspect score.
+  class EventTrigger
+    # @return [String, nil] the signal group, such as +vpn+ or +bot+
+    attr_reader :signal
+    # @return [Integer] the group's combined weight in this score
+    attr_reader :weight
+    # @return [String, nil] +low+, +medium+ or +high+
+    attr_reader :confidence
+
+    # @api private
+    def initialize(payload)
+      @signal = payload["signal"]
+      @weight = payload["weight"] || 0
+      @confidence = payload["confidence"]
+      freeze
+    end
+
+    def inspect
+      "#<Fingerly::EventTrigger #{signal}=#{weight}>"
+    end
+  end
+
+  # A stored identification event.
+  #
+  # {#suspect_score} is +nil+ when the request was not scored, which must not
+  # be read as zero: a visitor about whom nothing fired scores 0, while a
+  # submission that was never enriched has no score at all. {#scored?} states
+  # the distinction at the call site.
+  class Event
+    # Fields copied straight from the response, in the order the API documents
+    # them. Anything not listed stays reachable through {#raw}.
+    STRING_FIELDS = %w[
+      request_id visitor_id state environment platform sdk_platform sdk_version
+      origin url_host url_path tag ip_address country_code country_name asn
+      asn_name anonymity_network agent agent_version os device_kind visitor_kind
+      suspect_level
+    ].freeze
+
+    STRING_FIELDS.each { |name| attr_reader name.to_sym }
+
+    # @return [Time] when the request arrived
+    attr_reader :occurred_at
+    # @return [Integer, nil] the suspect score, or nil when unscored
+    attr_reader :suspect_score
+    # @return [Array<EventTrigger>] the signal groups behind the score; never
+    #   nil, and empty when nothing fired
+    attr_reader :triggers
+    # @return [Hash, nil] the archived submission, when one was kept. Its
+    #   contents are deliberately opaque, not a public contract.
+    attr_reader :document
+    # @return [Hash, nil] the deferred report attached to this request, when
+    #   one arrived. Also opaque.
+    attr_reader :deferred_signals
+    # @return [Hash] the response body exactly as it arrived, so a field the
+    #   API adds after this SDK was released needs no upgrade
+    attr_reader :raw
+
+    # @api private
+    def initialize(payload)
+      STRING_FIELDS.each { |name| instance_variable_set(:"@#{name}", payload[name]) }
+      @occurred_at = Models.parse_instant(payload["occurred_at"])
+      @suspect_score = payload["suspect_score"]
+      @has_document = payload["has_document"] ? true : false
+      @triggers = Array(payload["triggers"]).map { |item| EventTrigger.new(item) }.freeze
+      @document = payload["document"]
+      @deferred_signals = payload["deferred_signals"]
+      @raw = payload
+      freeze
+    end
+
+    # Whether the full submission was archived.
+    # @return [Boolean]
+    def has_document?
+      @has_document
+    end
+
+    # Whether the API assigned this event a suspect score.
+    #
+    # Prefer it to a nil check: it states the question being asked.
+    # @return [Boolean]
+    def scored?
+      !@suspect_score.nil?
+    end
+
+    def inspect
+      "#<Fingerly::Event request_id=#{request_id.inspect} visitor_id=#{visitor_id.inspect}>"
+    end
+  end
+
+  # One page of events, newest first.
+  class EventPage
+    include Enumerable
+
+    # @return [Array<Event>] the events on this page; never nil, possibly empty
+    attr_reader :rows
+    # @return [Integer] the one-based page number returned
+    attr_reader :page
+    # @return [Integer] rows per page the server applied
+    attr_reader :page_size
+    # @return [Hash] the response body exactly as it arrived
+    attr_reader :raw
+
+    # @api private
+    def initialize(payload)
+      @rows = Array(payload["rows"]).map { |item| Event.new(item) }.freeze
+      @page = payload["page"] || 0
+      @page_size = payload["page_size"] || 0
+      @raw = payload
+      freeze
+    end
+
+    # Yields each event, so a page is usable anywhere an Enumerable is.
+    def each(&block)
+      rows.each(&block)
+    end
+
+    def inspect
+      "#<Fingerly::EventPage page=#{page} page_size=#{page_size} rows=#{rows.size}>"
+    end
+  end
+
+  # The envelope every webhook delivery shares.
+  #
+  # {#data} is left as a plain Hash, so a new event type needs no SDK upgrade.
+  class WebhookEvent
+    # @return [String, nil] identifies this delivery. Persist it to
+    #   deduplicate: a webhook may arrive more than once.
+    attr_reader :id
+    # @return [String, nil] the event name, such as +identification.completed+
+    attr_reader :type
+    # @return [Integer, nil] the envelope version
+    attr_reader :version
+    # @return [String, nil] the organization the event belongs to
+    attr_reader :organization_id
+    # @return [String, nil] the deployment the event came from
+    attr_reader :environment
+    # @return [Time, nil] when Fingerly recorded the event
+    attr_reader :created_at
+    # @return [Hash] the event-specific payload
+    attr_reader :data
+    # @return [Hash] the delivery body exactly as it arrived
+    attr_reader :raw
+
+    # @api private
+    def initialize(payload)
+      @id = payload["id"]
+      @type = payload["type"]
+      @version = payload["version"]
+      @organization_id = payload["organization_id"]
+      @environment = payload["environment"]
+      @created_at = payload["created_at"] ? Models.parse_instant(payload["created_at"]) : nil
+      @data = payload["data"] || {}
+      @raw = payload
+      freeze
+    end
+
+    def inspect
+      "#<Fingerly::WebhookEvent id=#{id.inspect} type=#{type.inspect}>"
+    end
+  end
+
+  # Shared decoding helpers.
+  #
+  # @api private
+  module Models
+    module_function
+
+    # Reads an RFC 3339 timestamp into a Time.
+    #
+    # @raise [Error] if the API sent something that is not one
+    def parse_instant(value)
+      Time.iso8601(value.to_s)
+    rescue ArgumentError, TypeError
+      raise Error, "Fingerly API returned a timestamp that is not RFC 3339"
+    end
+  end
+end