fingerly 0.1.0

data/lib/fingerly/transport.rb

@@ -0,0 +1,344 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "timeout"
+require "uri"
+require "zlib"
+
+module Fingerly
+  # One HTTP exchange, bounded end to end.
+  #
+  # Net::HTTP has +open_timeout+, +read_timeout+ and +write_timeout+, but each
+  # bounds a single operation: a server that answers and then dribbles a byte
+  # every second would satisfy all three forever. The socket's timeouts are
+  # shrunk to whatever is left of the deadline before each operation and each
+  # body chunk, and one Timeout around the whole exchange covers what those
+  # cannot reach: Net::HTTP reads the status line and every header line with
+  # the full read timeout each, so a server trickling header lines would
+  # otherwise hold the call for as long as it liked. Under a fiber scheduler
+  # Timeout hands the wait to the scheduler.
+  #
+  # Idle connections live in one pool per process, keyed by destination.
+  # Net::HTTP cannot be used by two threads or fibers at once, so each exchange
+  # checks a connection out and hands it back when it is done. A thread-local
+  # or fiber-local connection would be reused only by the same thread or
+  # fiber: under Falcon, which runs each client connection in its own fiber,
+  # that meant a new upstream socket per visitor, stranded until garbage
+  # collection. A pool shared by everything reuses a socket whoever asks next.
+  #
+  # Connections are recycled by age, because one held for the life of a
+  # process pins whatever DNS answered first, and dropped after sitting idle,
+  # because the other end will eventually close it without telling anybody.
+  # Keying by destination rather than by transport instance means an
+  # application that builds a client per request still reuses sockets.
+  #
+  # Nothing here needs an asynchronous twin. Net::HTTP has honoured the fiber
+  # scheduler since Ruby 3.0, so under Falcon or the async gem these same
+  # blocking reads yield to the scheduler instead of holding the thread.
+  #
+  # @api private
+  class Transport
+    include Redacted
+
+    # A response body is small; anything larger did not come from this API,
+    # and is refused rather than buffered.
+    MAX_BODY_BYTES = 4 * 1024 * 1024
+
+    # How long a pooled connection may live before it is reopened, so DNS is
+    # asked again at least this often.
+    RECYCLE_AFTER = 60
+
+    # How long a connection may sit idle in the pool and still be reused. Well
+    # under the idle timeouts servers and load balancers apply, so a reused
+    # socket is one the other end has not yet given up on.
+    IDLE_TIMEOUT = 15
+
+    # Idle connections kept per destination. Enough that a burst of a few
+    # hundred concurrent requests hands its sockets back rather than closing
+    # them; never more open at rest than this.
+    MAX_IDLE = 256
+
+    Result = Struct.new(:status, :headers, :body, keyword_init: true)
+
+    # @param origin [String] scheme and authority, without a trailing slash
+    # @param timeout [Numeric] the deadline for one exchange, in seconds
+    # @param configure_http [Proc, nil] receives the Net::HTTP before it starts
+    def initialize(origin:, timeout:, configure_http: nil)
+      @uri = URI.parse(origin)
+      @timeout = timeout
+      @configure_http = configure_http
+      # A caller-supplied configure_http may set anything at all, so two
+      # transports share a connection only when neither has one.
+      @pool_key = [@uri.scheme, @uri.host, @uri.port, configure_http&.object_id].freeze
+    end
+
+    # Performs one request and reads the whole response.
+    #
+    # @param method [Class] a Net::HTTPRequest subclass
+    # @param path [String] the path and query to request
+    # @param headers [Hash{String=>String}] headers to send
+    # @param body [String, nil] the request body
+    # @return [Result]
+    # @raise [TimeoutError] if the deadline passes at any point
+    # @raise [ConnectionError] if the API cannot be reached
+    def call(method, path, headers, body = nil)
+      request = method.new(path, headers)
+      request.body = body if body
+      # Net::HTTP's own retry would resend on a connection error; reuse is
+      # handled here instead, where an idempotent request can be told from one
+      # that must never be sent twice.
+      idempotent = method == Net::HTTP::Get
+
+      # One budget for the whole call, so reopening a closed connection cannot
+      # quietly buy a second timeout's worth of time.
+      Timeout.timeout(@timeout, DeadlineExceeded) do
+        perform(request, deadline: now + @timeout, idempotent: idempotent)
+      end
+    rescue DeadlineExceeded
+      # perform has already discarded the interrupted connection.
+      raise TimeoutError, "The Fingerly request timed out"
+    rescue Timeout::Error => e
+      # Net::OpenTimeout, ReadTimeout and WriteTimeout all derive from it.
+      raise TimeoutError, "The Fingerly request timed out (#{e.class})"
+    rescue SocketError, IOError, SystemCallError, OpenSSL::OpenSSLError, Zlib::Error,
+           Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError, Net::ProtocolError => e
+      # Every network failure arrives as the SDK's own error, never as a raw
+      # runtime one. The class names the cause; nothing from the body does.
+      raise ConnectionError, "Could not reach the Fingerly API (#{e.class})"
+    end
+
+    # Closes the idle connections kept for this destination.
+    def close
+      Transport.drain(@pool_key).each { |entry| discard(entry.http) }
+    end
+
+    # One entry per idle connection: the Net::HTTP, when it was opened, and
+    # when it was last handed back.
+    Idle = Struct.new(:http, :opened_at, :released_at)
+
+    @idle = {}
+    @lock = Mutex.new
+    @pid = Process.pid
+    @swept_at = nil
+
+    class << self
+      # @api private
+      # @return [Array(Idle, Array<Idle>)] the most recently used usable
+      #   connection, or nil, and the stale ones the caller must close
+      def checkout(key, now)
+        @lock.synchronize do
+          list = idle_for(key)
+          stale = prune(list, now)
+          [list.pop, stale]
+        end
+      end
+
+      # @api private
+      # @return [Array(Boolean, Array<Idle>)] whether the pool kept it, and the
+      #   stale ones the caller must close
+      def checkin(key, entry, now)
+        @lock.synchronize do
+          list = idle_for(key)
+          stale = prune(list, now)
+          kept = list.size < MAX_IDLE
+          list.push(entry) if kept
+          # After the push, so a sweep cannot drop the list just appended to.
+          [kept, stale + sweep(now)]
+        end
+      end
+
+      # @api private
+      def drain(key)
+        @lock.synchronize { idle_for(key).slice!(0..) }
+      end
+
+      # @api private
+      # @return [Integer] idle connections held for a destination
+      def idle_count(key)
+        @lock.synchronize { idle_for(key).size }
+      end
+
+      private
+
+      def idle_for(key)
+        # A forked child must never write to a socket its parent also holds.
+        # Dropping the references closes nothing the parent still uses.
+        unless @pid == Process.pid
+          @idle = {}
+          @pid = Process.pid
+        end
+        @idle[key] ||= []
+      end
+
+      # A destination nobody asks for again would otherwise keep its sockets
+      # for ever: each +configure_http+ proc is its own key, so a client built
+      # per request with an inline proc strands one socket per request.
+      #
+      # @return [Array<Idle>] the stale connections the caller must close
+      def sweep(now)
+        return [] if @swept_at && now - @swept_at < IDLE_TIMEOUT
+
+        @swept_at = now
+        stale = []
+        @idle.delete_if do |_key, list|
+          stale.concat(prune(list, now))
+          list.empty?
+        end
+        stale
+      end
+
+      # The oldest entries sit at the front; take them while they are stale.
+      def prune(list, now)
+        stale = []
+        stale << list.shift while list.first && stale?(list.first, now)
+        stale
+      end
+
+      def stale?(entry, now)
+        now - entry.released_at > IDLE_TIMEOUT || now - entry.opened_at > RECYCLE_AFTER
+      end
+    end
+
+    private
+
+    def redacted_fields
+      [["origin", "#{@uri.scheme}://#{@uri.host}:#{@uri.port}"], ["timeout", @timeout]]
+    end
+
+    def perform(request, deadline:, idempotent:)
+      entry, reused = connection
+      begin
+        result = exchange(entry.http, request, deadline)
+      rescue IOError, SystemCallError, Net::HTTPBadResponse
+        discard(entry.http)
+        # A connection the other end closed while it was idle fails on its
+        # next use. Reopening and sending again is recovery, not a retry, so
+        # it happens only for a reused connection and only for a request that
+        # may safely arrive twice. A timeout is deliberately not in this list:
+        # a slow server is not a broken connection.
+        raise unless reused && idempotent
+
+        entry = fresh
+        begin
+          result = exchange(entry.http, request, deadline)
+        rescue Exception # rubocop:disable Lint/RescueException
+          discard(entry.http)
+          raise
+        end
+      rescue Exception # rubocop:disable Lint/RescueException
+        # Anything else, the overall deadline included, leaves the connection
+        # in an unknown state, so it is never handed to another caller.
+        discard(entry.http)
+        raise
+      end
+      release(entry)
+      result
+    end
+
+    def exchange(http, request, deadline)
+      apply_timeouts(http, deadline)
+      http.start unless http.started?
+      apply_timeouts(http, deadline)
+
+      # The result is captured rather than returned from the block. Net::HTTP
+      # decides whether the connection may be kept alive after the block ends,
+      # and a non-local exit would skip that: the next request on this thread
+      # would then be written to a socket the server had already said it was
+      # closing.
+      result = nil
+      http.request(request) do |response|
+        # Refused on the declared size before a byte is buffered, and on the
+        # real size while reading, whichever comes first.
+        too_large! if response.content_length.to_i > MAX_BODY_BYTES
+        body = +""
+        response.read_body do |chunk|
+          body << chunk
+          too_large! if body.bytesize > MAX_BODY_BYTES
+
+          # Shrink the socket's own timeout to what is left of the deadline, so
+          # a stalled body cannot outlive it.
+          apply_timeouts(http, deadline)
+        end
+        declared = response.content_length
+        if declared && body.bytesize != declared
+          raise ConnectionError, "The Fingerly API response was cut short"
+        end
+
+        result = Result.new(
+          status: response.code.to_i, headers: response.to_hash, body: body
+        )
+      end
+      result
+    end
+
+    def too_large!
+      raise Error, "The Fingerly API returned more than #{MAX_BODY_BYTES} bytes"
+    end
+
+    # @raise [TimeoutError] when nothing is left of the deadline
+    def apply_timeouts(http, deadline)
+      left = deadline - now
+      raise TimeoutError, "The Fingerly request timed out" if left <= 0
+
+      http.open_timeout = left
+      http.read_timeout = left
+      http.write_timeout = left
+    end
+
+    # @return [Array(Idle, Boolean)] a connection and whether it was reused
+    def connection
+      loop do
+        entry, stale = Transport.checkout(@pool_key, now)
+        stale.each { |old| discard(old.http) }
+        return [fresh, false] if entry.nil?
+        return [entry, true] if entry.http.started?
+
+        discard(entry.http)
+      end
+    end
+
+    def release(entry)
+      return discard(entry.http) unless entry.http.started?
+
+      entry.released_at = now
+      kept, stale = Transport.checkin(@pool_key, entry, now)
+      stale.each { |old| discard(old.http) }
+      discard(entry.http) unless kept
+    end
+
+    def fresh
+      Idle.new(build, now, now)
+    end
+
+    def build
+      # hostname, not host: host keeps an IPv6 literal's brackets, which
+      # Net::HTTP would then try to resolve as a name.
+      http = Net::HTTP.new(@uri.hostname, @uri.port)
+      http.use_ssl = @uri.scheme == "https"
+      http.max_retries = 0
+      # Net::HTTP accepts a body shorter than its content-length by default,
+      # which would pass a response cut short upstream on as complete.
+      http.ignore_eof = false
+      # Net::HTTP reconnects by itself after this long idle; keep it in step
+      # with the pool's own idea of a usable connection.
+      http.keep_alive_timeout = IDLE_TIMEOUT
+      @configure_http&.call(http)
+      http
+    end
+
+    def discard(http)
+      http.finish if http.started?
+    rescue IOError
+      # Already closed by the other end; nothing left to release.
+    end
+
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # Raised by the overall deadline; never escapes {#call}.
+    class DeadlineExceeded < StandardError; end
+    private_constant :DeadlineExceeded
+  end
+end

data/lib/fingerly/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Fingerly
+  # The SDK version, reported to the API on every request.
+  VERSION = "0.1.0"
+end

data/lib/fingerly/webhooks.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module Fingerly
+  # Webhook signature verification.
+  #
+  # Stateless and module-level: verifying a delivery is one HMAC over bytes you
+  # already have, so it needs no client.
+  module Webhooks
+    # How far a delivery's timestamp may be from now, in seconds, before it is
+    # refused as a replay.
+    DEFAULT_TOLERANCE = 300
+
+    # A lowercase hex digest, exactly as Fingerly sends it. Anchored with \A
+    # and \z because Ruby's ^ and $ match at every line boundary.
+    SIGNATURE = /\Asha256=[a-f0-9]{64}\z/
+    # Whole unsigned seconds, and nothing else.
+    TIMESTAMP = /\A[0-9]+\z/
+
+    PREFIX = "sha256="
+
+    # Signatures read from one header. A rotation needs two; anything beyond
+    # this is not from Fingerly, and is not worth comparing one by one.
+    MAX_SIGNATURES = 32
+
+    module_function
+
+    # Reports whether a delivery came from Fingerly and is recent.
+    #
+    #   payload = request.body.read
+    #   ok = Fingerly::Webhooks.verify(
+    #     secret: ENV.fetch("FINGERLY_WEBHOOK_SECRET"),
+    #     payload: payload,
+    #     timestamp: request.get_header("HTTP_X_FINGERLY_TIMESTAMP"),
+    #     signature: request.get_header("HTTP_X_FINGERLY_SIGNATURE"),
+    #   )
+    #
+    # Verification proves authenticity and freshness. It does not deduplicate,
+    # so persist processed {WebhookEvent#id} values as well.
+    #
+    # @param secret [String] the endpoint's signing secret
+    # @param payload [String] the exact bytes received, before any JSON
+    #   parsing: re-serialising them changes the digest
+    # @param timestamp [String] the +x-fingerly-timestamp+ header
+    # @param signature [String] the +x-fingerly-signature+ header, which
+    #   carries several comma-separated signatures during a secret rotation.
+    #   Any one of the first {MAX_SIGNATURES} matching is accepted.
+    # @param tolerance [Numeric] the replay window in seconds
+    # @param now [Time, nil] the instant to measure freshness against.
+    #   Override it only in tests.
+    # @return [Boolean] true when a signature matches and the timestamp is
+    #   recent. Malformed or missing input returns false rather than raising.
+    def verify(secret:, payload:, timestamp:, signature:,
+               tolerance: DEFAULT_TOLERANCE, now: nil)
+      return false unless secret.is_a?(String) && !secret.empty?
+      return false unless payload.is_a?(String)
+      return false unless timestamp.is_a?(String) && signature.is_a?(String)
+
+      # Header values are whatever the sender wrote. As bytes, a value that is
+      # not valid in its encoding simply fails to match, where as a string it
+      # would raise from the regular expressions below.
+      timestamp = timestamp.b
+      signature = signature.b
+      # Check freshness before spending an HMAC on an obvious replay.
+      return false unless fresh?(timestamp, now, tolerance)
+
+      expected = sign(secret, timestamp, payload)
+      # The limit keeps a huge header from being split in full; whatever lies
+      # past the last candidate is ignored rather than compared.
+      candidates = signature.split(",", MAX_SIGNATURES + 1).first(MAX_SIGNATURES)
+      candidates.any? { |candidate| matches?(candidate, expected) }
+    end
+
+    # Parses a delivery's envelope.
+    #
+    # Verify the bytes before calling this: parsing an unverified body is
+    # trusting whoever sent it.
+    #
+    # @param payload [String] the raw delivery body
+    # @return [WebhookEvent]
+    # @raise [Error] if the body is not a Fingerly webhook envelope
+    def parse(payload)
+      parsed = JSON.parse(payload.to_s)
+      raise Error, "Not a Fingerly webhook envelope" unless parsed.is_a?(Hash)
+
+      WebhookEvent.new(parsed)
+    rescue JSON::ParserError
+      raise Error, "Not a Fingerly webhook envelope"
+    end
+
+    # Whether the signed time is within tolerance of now.
+    # @api private
+    def fresh?(timestamp, now, tolerance)
+      return false unless TIMESTAMP.match?(timestamp)
+      return false unless tolerance.is_a?(Numeric) && !tolerance.negative?
+
+      moment = (now || Time.now).to_i
+      (moment - Integer(timestamp, 10)).abs <= tolerance
+    end
+
+    # Computes the expected digest.
+    #
+    # Fingerly signs the timestamp, a literal dot, then the raw body bytes.
+    # Both are forced to binary first: a body that is not valid UTF-8 would
+    # otherwise raise on concatenation rather than simply fail to verify.
+    #
+    # @api private
+    def sign(secret, timestamp, payload)
+      signed = timestamp.b
+      signed += "."
+      signed += payload.b
+      OpenSSL::HMAC.hexdigest("SHA256", secret, signed)
+    end
+
+    # Compares one candidate signature in constant time.
+    # @api private
+    def matches?(candidate, expected)
+      value = candidate.strip
+      return false unless SIGNATURE.match?(value)
+
+      OpenSSL.fixed_length_secure_compare(value.delete_prefix(PREFIX), expected)
+    end
+  end
+end

data/lib/fingerly.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "fingerly/version"
+require_relative "fingerly/errors"
+require_relative "fingerly/redacted"
+require_relative "fingerly/config"
+require_relative "fingerly/models"
+require_relative "fingerly/transport"
+require_relative "fingerly/client"
+require_relative "fingerly/webhooks"
+require_relative "fingerly/proxy"
+
+# Server-side Fingerly SDK.
+#
+# It reads stored identification events with a secret key, verifies signed
+# webhooks, and serves the browser SDK's requests from a route on your own
+# domain. It has no runtime dependencies.
+#
+#   require "fingerly"
+#
+#   fingerly = Fingerly::Client.new(secret_key: ENV.fetch("FINGERLY_SECRET_KEY"))
+#   event = fingerly.events.get(request_id)
+#
+# Secret keys and webhook secrets belong in server-side code only. A browser
+# must never see either.
+module Fingerly
+end