websitescreenshotworld 0.1.3

data/lib/websitescreenshotworld/events.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module WebsiteScreenshotWorld
+  # A webhook delivery, as returned by {Webhook.verify}. Each type has its own subclass, so a +case+ on the
+  # class (or pattern matching on +type+ and +data+) picks the handler.
+  #
+  # @!attribute [r] id
+  #   @return [String] the delivery id
+  # @!attribute [r] type
+  #   @return [String] one of {EventType}, or a type added later
+  # @!attribute [r] created_at
+  #   @return [Time, nil]
+  # @!attribute [r] product
+  #   @return [String] one of {Product}
+  # @!attribute [r] data
+  #   @return [Object] the typed payload; see each subclass
+  Event = Data.define(:id, :type, :created_at, :product, :data) do
+    include Model::Raw
+  end
+
+  # +capture.succeeded+. {#data} is a {Capture} for Instant Snap and a {ScheduledCapture} for Auto Schedule.
+  class CaptureSucceededEvent < Event; end
+
+  # +capture.failed+. {#data} is a {Capture} for Instant Snap and a {ScheduledCapture} for Auto Schedule.
+  class CaptureFailedEvent < Event; end
+
+  # +delivery.completed+ (Auto Schedule). {#data} is a {ScheduledCapture} with its +destinations+.
+  class DeliveryCompletedEvent < Event; end
+
+  # +capture.changed+ (Auto Schedule). {#data} is a {ScheduledCapture} with its +change_percent+.
+  class CaptureChangedEvent < Event; end
+
+  # +schedule.paused+ (Auto Schedule). {#data} is a {SchedulePause}.
+  class SchedulePausedEvent < Event; end
+
+  # +sitemap_run.completed+ (Auto Schedule). {#data} is a {SitemapRun}.
+  class SitemapRunCompletedEvent < Event; end
+
+  # +ping+, a test delivery. {#data} is a {Ping}.
+  class PingEvent < Event; end
+
+  # A type this version of the library does not know yet. {#type} names it and {#data} is the raw Hash.
+  class UnknownEvent < Event; end
+
+  # The subclasses exist only now, so the table that picks one is added here.
+  class Event
+    TYPES = {
+      EventType::DELIVERY_COMPLETED => [DeliveryCompletedEvent, ScheduledCapture],
+      EventType::CAPTURE_CHANGED => [CaptureChangedEvent, ScheduledCapture],
+      EventType::SCHEDULE_PAUSED => [SchedulePausedEvent, SchedulePause],
+      EventType::SITEMAP_RUN_COMPLETED => [SitemapRunCompletedEvent, SitemapRun],
+      EventType::PING => [PingEvent, Ping]
+    }.freeze
+    private_constant :TYPES
+
+    # @api private
+    def self.from_api(hash)
+      klass, data_class = classes_for(hash["type"], hash["product"])
+      data = hash["data"]
+      data = data_class.from_api(data) if data_class && data.is_a?(Hash)
+      Model.build(klass, hash, created_at: Model.time(hash["created_at"]), data: data)
+    end
+
+    def self.classes_for(type, product)
+      capture_class = product == Product::INSTANT_SNAP ? Capture : ScheduledCapture
+      case type
+      when EventType::CAPTURE_SUCCEEDED then [CaptureSucceededEvent, capture_class]
+      when EventType::CAPTURE_FAILED then [CaptureFailedEvent, capture_class]
+      else TYPES.fetch(type, [UnknownEvent, nil])
+      end
+    end
+    private_class_method :classes_for
+  end
+end

data/lib/websitescreenshotworld/instant_snap.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+module WebsiteScreenshotWorld
+  # The Instant Snap API: capture a page on demand. Reach it through {Client#instant_snap}.
+  #
+  # The capture and submit methods take the API's options as keyword arguments with the API's own names.
+  # Nested blocks are hashes, an option left out is not sent (an explicit +false+ is), and the keys of
+  # +headers:+ and +cookies:+ are sent exactly as given.
+  #
+  # @example
+  #   client.instant_snap.capture(url: "https://example.com", format: "webp", viewport: { width: 1440 })
+  class InstantSnap < Service
+    MISSING_KEY = "No Instant Snap API key was given: pass instant_snap_api_key: to " \
+                  "WebsiteScreenshotWorld::Client.new or set WSW_INSTANT_SNAP_API_KEY."
+
+    CAPTURES_PATH = "/instant-snap/v1/captures"
+    private_constant :CAPTURES_PATH
+
+    # Every option a capture accepts besides +url+. +response_type+ and +async+ are set by the method called.
+    # +timeout+ (the browser time of an async capture) is taken by {#submit} and {#submit_to_bucket} only; on
+    # the other capture methods +timeout:+ is the call's own timeout and the server refuses the option.
+    CAPTURE_OPTIONS = %i[
+      media_category format viewport device_category emulated_device scroll_mode auto_height max_height zoom
+      block_ads block_pop_ups press_escape page_timeout_ms scrolling_delay_ms user_agent locale time_zone headers
+      cookies
+      geolocation selectors proxy timestamp_watermark page_source s3_delivery callback_url timeout
+    ].freeze
+
+    # Statuses {#wait} keeps polling through.
+    UNFINISHED = [CaptureStatus::QUEUED, CaptureStatus::RUNNING, CaptureStatus::PENDING].freeze
+    private_constant :UNFINISHED
+
+    # @api private
+    def initialize(capture_timeout:, **settings)
+      super(**settings)
+      @capture_timeout = capture_timeout
+    end
+
+    # Captures a page and answers with its metadata and a download link valid for 60 minutes.
+    #
+    # @param url [String] the page to capture, absolute http or https
+    # @param idempotency_key [String, nil] makes the call safe to repeat; a random one is used otherwise
+    # @param timeout [Numeric, nil] seconds to wait for the answer, retries included; defaults to the
+    #   client's +capture_timeout+
+    # @param options [Hash] any of {CAPTURE_OPTIONS}
+    # @option options [String] :media_category one of {MediaCategory}
+    # @option options [String] :format one of {Format}, belonging to the media category
+    # @option options [Hash] :viewport +width+, +height+, +device_scale_factor+
+    # @option options [String] :device_category one of {DeviceCategory}
+    # @option options [String] :emulated_device a device from {#catalog}
+    # @option options [String] :scroll_mode one of {ScrollMode}
+    # @option options [Boolean] :auto_height
+    # @option options [Integer] :max_height
+    # @option options [Integer] :zoom percent, 50 to 100
+    # @option options [Boolean] :block_ads
+    # @option options [Boolean] :block_pop_ups
+    # @option options [Boolean] :press_escape press Escape after the pop-up pass and again after scrolling,
+    #   for a modal that closes on Escape
+    # @option options [Integer] :page_timeout_ms
+    # @option options [Integer] :scrolling_delay_ms the pause after each scroll step, 0 to 10000; default 500
+    # @option options [String] :user_agent
+    # @option options [String] :locale BCP 47
+    # @option options [String] :time_zone IANA time zone
+    # @option options [Hash{String => String}] :headers sent with every request the page makes
+    # @option options [Hash{String => String}] :cookies set for the URL's origin
+    # @option options [Hash] :geolocation +latitude+, +longitude+, +accuracy+
+    # @option options [Hash] :selectors +xpath+, +click+, +hover+ (each at most 512 characters) and +hide+
+    #   (up to 25 comma-separated CSS selectors, at most 2000 characters)
+    # @option options [Hash] :proxy +country+, from {#catalog}
+    # @option options [Hash] :timestamp_watermark +enabled+, +location+, +font_color+, +background_color+
+    # @option options [Hash] :page_source +format+, one of {PageSourceFormat}
+    # @option options [String] :callback_url also receives the capture's webhook
+    # @return [Capture]
+    # @raise [Error] a subclass matching the refusal
+    def capture(url:, idempotency_key: nil, timeout: nil, **options)
+      hash, response = post_capture(ResponseType::JSON, url, options, idempotency_key, timeout)
+      Capture.from_api(hash, idempotent_replayed: replayed?(response))
+    end
+
+    # Captures a page and uploads the file to your S3-compatible bucket.
+    #
+    # @param s3_delivery [Hash] +access_key_id+, +secret_access_key+, +bucket+, and +region+ or
+    #   +endpoint_url+; optionally +force_path_style+, +key_prefix+, +wait_for_sync+
+    # @param (see #capture)
+    # @option (see #capture)
+    # @return [Capture] with {Capture#s3_delivery} describing the upload
+    # @raise [Error] a subclass matching the refusal
+    def capture_to_bucket(url:, s3_delivery:, idempotency_key: nil, timeout: nil, **options)
+      options = options.merge(s3_delivery: s3_delivery)
+      hash, response = post_capture(ResponseType::CLOUD_STORAGE, url, options, idempotency_key, timeout)
+      Capture.from_api(hash, idempotent_replayed: replayed?(response))
+    end
+
+    # Captures a page and answers with the file itself, up to 64 MB.
+    #
+    # With a block, yields a {CaptureFile} whose body streams from the connection, and returns the block's
+    # value. Without one, buffers the body to a +Tempfile+ and returns the {CaptureFile}; call
+    # {CaptureFile#close} when done with it.
+    #
+    # @example
+    #   client.instant_snap.capture_file(url: "https://example.com") { |file| file.save("page.png") }
+    #
+    # @param (see #capture)
+    # @option (see #capture)
+    # @yieldparam file [CaptureFile]
+    # @return [CaptureFile, Object] the file, or the block's value
+    # @raise [Error] a subclass matching the refusal
+    def capture_file(url:, idempotency_key: nil, timeout: nil, **options)
+      send_request(:post, CAPTURES_PATH,
+                   body: capture_body(ResponseType::BY_FORMAT, url, options),
+                   headers: capture_headers(idempotency_key),
+                   accept: "*/*",
+                   timeout: timeout || @capture_timeout) do |response|
+        block_given? ? yield(CaptureFile.new(response)) : CaptureFile.buffered(response)
+      end
+    end
+
+    # Submits an async capture and answers at once, before it runs, with the capture in status +queued+.
+    # Follow it with {#wait}, {#get} or the +capture.succeeded+ / +capture.failed+ webhooks. A capture still
+    # queued 15 minutes after it was accepted ends +failed+ with +capture_expired+ and is not charged.
+    #
+    # The request uses the client's ordinary +timeout+ (30 seconds by default), not +capture_timeout+, since
+    # nothing runs while it waits.
+    #
+    # @example
+    #   queued = client.instant_snap.submit(url: "https://example.com", timeout: 240)
+    #   capture = client.instant_snap.wait(queued)
+    #
+    # @param url [String] the page to capture, absolute http or https
+    # @param timeout [Integer, nil] seconds of browser time the capture may use, 30 to 300; the server uses
+    #   120 when it is left out
+    # @param idempotency_key [String, nil] makes the call safe to repeat; a random one is used otherwise
+    # @param options [Hash] any of {CAPTURE_OPTIONS}, as for {#capture}
+    # @option (see #capture)
+    # @return [Capture] with status +queued+
+    # @raise [RateLimitError] +queue_full+ when the organization already has as many async captures waiting or
+    #   running as it may; not retried, see {Error#retry_after_seconds}
+    # @raise [Error] a subclass matching any other refusal
+    def submit(url:, timeout: nil, idempotency_key: nil, **options)
+      options = options.merge(timeout: timeout)
+      hash, response = post_capture(ResponseType::JSON, url, options, idempotency_key, @timeout, async: true)
+      Capture.from_api(hash, idempotent_replayed: replayed?(response))
+    end
+
+    # Submits an async capture whose file is uploaded to your S3-compatible bucket, and answers at once with
+    # the capture in status +queued+. Otherwise as {#submit}.
+    #
+    # @param s3_delivery [Hash] as for {#capture_to_bucket}
+    # @param (see #submit)
+    # @option (see #capture)
+    # @return [Capture] with status +queued+
+    # @raise (see #submit)
+    def submit_to_bucket(url:, s3_delivery:, timeout: nil, idempotency_key: nil, **options)
+      options = options.merge(s3_delivery: s3_delivery, timeout: timeout)
+      hash, response = post_capture(ResponseType::CLOUD_STORAGE, url, options, idempotency_key, @timeout,
+                                    async: true)
+      Capture.from_api(hash, idempotent_replayed: replayed?(response))
+    end
+
+    # Reads a capture with {#get} every +poll_interval_seconds+ until its status is no longer +queued+,
+    # +running+ or +pending+, and returns it.
+    #
+    # When +timeout_seconds+ runs out first, returns the capture as last read, still unfinished, rather than
+    # raising, so you can decide whether to wait again. A refusal from {#get} is raised as from {#get}.
+    #
+    # @param capture [Capture, String] the capture, or its id
+    # @param timeout_seconds [Numeric] how long to keep polling
+    # @param poll_interval_seconds [Numeric] the pause between reads; 0 does not pause
+    # @return [Capture]
+    # @raise [Error] a subclass matching a refusal of {#get}
+    def wait(capture, timeout_seconds: 360, poll_interval_seconds: 3)
+      id = capture.respond_to?(:id) ? capture.id : capture
+      deadline = clock + timeout_seconds
+      loop do
+        current = get(id)
+        remaining = deadline - clock
+        return current if !UNFINISHED.include?(current.status) || remaining <= 0
+
+        sleep([poll_interval_seconds, remaining].min) if poll_interval_seconds.positive?
+      end
+    end
+
+    # Reads a capture back. This also reissues its +download_url+.
+    #
+    # @param id [String]
+    # @return [Capture]
+    # @raise [NotFoundError] when there is no such capture for this account
+    def get(id)
+      hash, = request_json(:get, "/instant-snap/v1/captures/#{path_segment(id)}")
+      Capture.from_api(hash)
+    end
+
+    # Downloads a capture's file (or its page source) from its +download_url+, without holding it in
+    # memory. The API key is not sent to the download host.
+    #
+    # @param capture [Capture, PageSource, String] anything with a +download_url+, or the URL itself
+    # @param target [String, Pathname, #write] a path to create or overwrite, or an open IO
+    # @param timeout [Numeric, nil] seconds for the whole download; defaults to the client's +capture_timeout+
+    # @return [String, Pathname, #write] +target+
+    # @raise [ArgumentError] when the capture has no +download_url+
+    def download(capture, target, timeout: nil)
+      url = capture.respond_to?(:download_url) ? capture.download_url : capture
+      raise ArgumentError, "this capture has no download_url; read it again with #get to reissue one" unless url
+
+      @transport.request(:get, url, headers: { "Accept" => "*/*" }, timeout: timeout || @capture_timeout) do |answer|
+        Transport.write_body(answer, target)
+      end
+      target
+    end
+
+    # The values a capture takes for options it does not send, and the limits it is checked against.
+    # Needs no API key.
+    #
+    # @return [Defaults]
+    def defaults
+      hash, = request_json(:get, "/instant-snap/v1/defaults", authenticate: false)
+      Defaults.from_api(hash)
+    end
+
+    # The devices +emulated_device+ accepts and the countries +proxy: { country: }+ accepts.
+    #
+    # @return [Catalog]
+    def catalog
+      hash, = request_json(:get, "/instant-snap/v1/catalog")
+      Catalog.from_api(hash)
+    end
+
+    private
+
+    def post_capture(response_type, url, options, idempotency_key, timeout, async: false)
+      request_json(:post, CAPTURES_PATH,
+                   body: capture_body(response_type, url, options, async: async),
+                   headers: capture_headers(idempotency_key),
+                   timeout: timeout || @capture_timeout)
+    end
+
+    def capture_body(response_type, url, options, async: false)
+      unknown = options.keys - CAPTURE_OPTIONS
+      unless unknown.empty?
+        raise ArgumentError, "unknown keyword#{"s" if unknown.size > 1}: #{unknown.map(&:inspect).join(", ")}"
+      end
+
+      body = without_nils(url: url, **options).merge(response_type: response_type)
+      async ? body.merge(async: true) : body
+    end
+
+    # One key per call, reused by that call's retries, so a retry never captures twice.
+    def capture_headers(idempotency_key)
+      { "Idempotency-Key" => idempotency_key || SecureRandom.uuid }
+    end
+
+    def clock
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def replayed?(response)
+      response["Idempotent-Replayed"] == "true"
+    end
+  end
+end

data/lib/websitescreenshotworld/model.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module WebsiteScreenshotWorld
+  # Helpers the result types share.
+  #
+  # @api private
+  module Model
+    # Gives a +Data+ class a {#raw} reader holding the object as the API sent it.
+    module Raw
+      # @return [Hash{String => Object}] the object as the API sent it, including fields this version of the
+      #   library does not know yet
+      attr_reader :raw
+
+      def initialize(raw: {}.freeze, **fields)
+        @raw = raw
+        super(**fields)
+      end
+    end
+
+    module_function
+
+    # Builds +klass+ from an API hash, taking each member from the key of the same name. Keys the class
+    # does not know are left in +raw+ only; +converted+ replaces members that need more than a copy.
+    def build(klass, hash, **converted)
+      fields = klass.members.to_h { |name| [name, hash[name.to_s]] }
+      klass.new(raw: hash, **fields, **converted)
+    end
+
+    # Parses a JSON body into frozen objects. The API always sends UTF-8, whatever encoding Ruby tagged the
+    # bytes with.
+    def parse_json(bytes)
+      JSON.parse(String.new(bytes, encoding: Encoding::UTF_8), freeze: true)
+    end
+
+    # Parses an ISO 8601 timestamp (any fraction length, +Z+ or an offset) into a UTC +Time+.
+    #
+    # @return [Time, nil] nil when the value is absent or not a timestamp
+    def time(value)
+      return value if value.nil? || value.is_a?(Time)
+
+      Time.iso8601(value.to_s).utc
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/websitescreenshotworld/service.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module WebsiteScreenshotWorld
+  # What {InstantSnap} and {AutoSchedule} share: the key, the base URL and JSON requests.
+  #
+  # @api private
+  class Service
+    def initialize(transport:, base_url:, api_key:, timeout:)
+      @transport = transport
+      @base_url = base_url.to_s.chomp("/")
+      @api_key = api_key.to_s.empty? ? nil : api_key
+      @timeout = timeout
+    end
+
+    # Keeps the API key out of logs and consoles.
+    def inspect
+      "#<#{self.class.name} base_url=#{@base_url.inspect}>"
+    end
+
+    private
+
+    # Sends a call to this product and yields the successful response with its body unread.
+    def send_request(method, path, body: nil, headers: {}, timeout: @timeout, authenticate: true,
+                     accept: "application/json", &)
+      headers = { "Accept" => accept }.merge(headers)
+      headers["Content-Type"] = "application/json" if body
+      headers["X-Api-Key"] = api_key! if authenticate
+      @transport.request(method, "#{@base_url}#{path}", headers: headers, body: body && JSON.generate(body),
+                                                        timeout: timeout, &)
+    end
+
+    # @return [Array(Hash, Net::HTTPResponse)] the answer without +success+, and the response for its headers
+    def request_json(method, path, **options)
+      response = send_request(method, path, **options) { |answer| answer.tap(&:read_body) }
+      [parse(response), response]
+    end
+
+    def api_key!
+      @api_key || raise(AuthenticationError, self.class::MISSING_KEY)
+    end
+
+    def parse(response)
+      hash = Model.parse_json(response.body)
+      raise JSON::ParserError, "expected an object" unless hash.is_a?(Hash)
+
+      hash.except("success").freeze
+    rescue JSON::ParserError
+      raise Error.new("The server answered HTTP #{response.code} with a body that is not a JSON object.",
+                      http_status: response.code.to_i, body: response.body)
+    end
+
+    def path_segment(value)
+      URI.encode_uri_component(value.to_s)
+    end
+
+    # Drops the options that were not set, at every level; +false+, +0+ and +""+ stay.
+    def without_nils(hash)
+      hash.each_with_object({}) do |(key, value), result|
+        next if value.nil?
+
+        result[key] = value.is_a?(Hash) ? without_nils(value) : value
+      end
+    end
+  end
+end

data/lib/websitescreenshotworld/tokens.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module WebsiteScreenshotWorld
+  # Values of +status+ on a {Capture}. Compare with these rather than literals; a value added later still
+  # comes through as a plain String.
+  module CaptureStatus
+    # An async capture was accepted and is waiting for a browser.
+    QUEUED = "queued"
+    # A browser is taking an async capture.
+    RUNNING = "running"
+    PENDING = "pending"
+    SUCCEEDED = "succeeded"
+    # The end state of a +by_format+ capture: the file went back in the response and is not kept.
+    DELIVERED = "delivered"
+    FAILED = "failed"
+    TIMED_OUT = "timed_out"
+    EXPIRED = "expired"
+  end
+
+  # Values of +response_type+. The capture methods set it themselves.
+  module ResponseType
+    JSON = "json"
+    BY_FORMAT = "by_format"
+    CLOUD_STORAGE = "cloud_storage"
+  end
+
+  # Values of the +media_category+ option and field.
+  module MediaCategory
+    IMAGE = "image"
+    VIDEO = "video"
+    PDF = "pdf"
+  end
+
+  # Values of the +format+ option and field. Each belongs to one {MediaCategory}.
+  module Format
+    PNG = "png"
+    JPEG = "jpeg"
+    WEBP = "webp"
+    TIFF = "tiff"
+    MP4 = "mp4"
+    WEBM = "webm"
+    MOV = "mov"
+    GIF = "gif"
+    IMAGE_PDF = "image_pdf"
+    DOCUMENT_PDF = "document_pdf"
+  end
+
+  # Values of the +device_category+ option.
+  module DeviceCategory
+    DESKTOP = "desktop"
+    MOBILE = "mobile"
+  end
+
+  # Values of the +scroll_mode+ option. +SCROLL+ captures the full page.
+  module ScrollMode
+    VIEWPORT = "viewport"
+    SCROLL = "scroll"
+  end
+
+  # Values of +timestamp_watermark: { location: }+.
+  module WatermarkLocation
+    TOP = "top"
+    BOTTOM = "bottom"
+  end
+
+  # Values of +page_source: { format: }+ and {PageSource#format}.
+  module PageSourceFormat
+    HTML = "html"
+    JSON = "json"
+    TEXT = "text"
+  end
+
+  # Values of {S3Delivery#status}.
+  module S3DeliveryStatus
+    NOT_STARTED = "not_started"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+    FAILED = "failed"
+  end
+
+  # Values of {TriggerResult#status}.
+  module TriggerStatus
+    TRIGGERED = "triggered"
+    # A capture for this web page was already queued or running: nothing new started, nothing was charged.
+    ALREADY_PENDING = "already_pending"
+  end
+
+  # Values of {TriggerResult#triggered_by}.
+  module TriggeredBy
+    API = "api"
+    UI = "ui"
+  end
+
+  # Values of {Event#product}.
+  module Product
+    INSTANT_SNAP = "instant_snap"
+    AUTO_SCHEDULE = "auto_schedule"
+  end
+
+  # Values of {Event#type}.
+  module EventType
+    CAPTURE_SUCCEEDED = "capture.succeeded"
+    CAPTURE_FAILED = "capture.failed"
+    DELIVERY_COMPLETED = "delivery.completed"
+    CAPTURE_CHANGED = "capture.changed"
+    SCHEDULE_PAUSED = "schedule.paused"
+    SITEMAP_RUN_COMPLETED = "sitemap_run.completed"
+    PING = "ping"
+  end
+end

data/lib/websitescreenshotworld/transport.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module WebsiteScreenshotWorld
+  # Sends one call over Net::HTTP, retrying what the API marks as retryable.
+  #
+  # @api private
+  class Transport
+    USER_AGENT = "websitescreenshotworld-ruby/#{VERSION} (#{RUBY_ENGINE} #{RUBY_ENGINE_VERSION})".freeze
+
+    CONNECTION_ERRORS = [
+      IOError, SocketError, SystemCallError, Timeout::Error, OpenSSL::SSL::SSLError,
+      Net::HTTPBadResponse, Net::ProtocolError
+    ].freeze
+
+    MAX_RETRY_AFTER = 60
+    FIRST_BACKOFF = 0.5
+    JITTER = 0.25
+
+    # Net::HTTP gives every POST a form Content-Type, even an empty one. Trigger-now has no body at all.
+    class EmptyPost < Net::HTTPRequest
+      METHOD = "POST"
+      REQUEST_HAS_BODY = false
+      RESPONSE_HAS_BODY = true
+    end
+
+    # Reads a response body chunk by chunk. A network failure becomes a {ConnectionError}; an exception
+    # raised by the block passes through untouched.
+    def self.each_chunk(response)
+      in_block = false
+      response.read_body do |chunk|
+        in_block = true
+        yield chunk
+        in_block = false
+      end
+    rescue *CONNECTION_ERRORS => e
+      raise if in_block
+
+      raise ConnectionError, "The connection broke before the whole body arrived (#{e.message})."
+    end
+
+    # Writes a response body to an IO, or to a file it creates at a path and deletes again if the body does
+    # not arrive whole.
+    def self.write_body(response, target)
+      return each_chunk(response) { |chunk| target.write(chunk) } if target.respond_to?(:write)
+
+      File.open(target, "wb") { |file| each_chunk(response) { |chunk| file.write(chunk) } }
+    rescue StandardError
+      File.delete(target) if !target.respond_to?(:write) && File.exist?(target)
+      raise
+    end
+
+    def initialize(max_retries:)
+      @max_retries = max_retries
+    end
+
+    # Sends the request, retrying refusals and connection failures until it succeeds, the retries run out
+    # or +timeout+ seconds have passed, then yields the successful response with its body still unread.
+    #
+    # @return the block's value
+    def request(method, url, headers:, timeout:, body: nil)
+      uri = URI(url)
+      deadline = clock + timeout
+      retries = 0
+      delivered = false
+      begin
+        connection(uri, deadline).start do |http|
+          http.request(build_request(method, uri, headers, body)) do |response|
+            raise ErrorResponse.build(response) unless response.is_a?(Net::HTTPSuccess)
+
+            delivered = true
+            # Returning from inside the block closes the connection instead of draining an unread body.
+            return yield(response)
+          end
+        end
+      rescue Error, *CONNECTION_ERRORS => e
+        raise if delivered
+
+        error = e.is_a?(Error) ? e : ConnectionError.new("The request to #{uri.host} failed: #{e.message}")
+        delay = retry_delay(error, retries, deadline) or raise error
+        sleep(delay)
+        retries += 1
+        retry
+      end
+    end
+
+    private
+
+    def connection(uri, deadline)
+      remaining = deadline - clock
+      Net::HTTP.new(uri.hostname, uri.port).tap do |http|
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = http.read_timeout = http.write_timeout = http.ssl_timeout = remaining
+        http.max_retries = 0
+      end
+    end
+
+    def build_request(method, uri, headers, body)
+      headers = headers.merge("User-Agent" => USER_AGENT)
+      case [method, body.nil?]
+      in [:get, _] then Net::HTTP::Get.new(uri, headers)
+      in [:post, true] then EmptyPost.new(uri, headers.merge("Content-Length" => "0"))
+      in [:post, false] then Net::HTTP::Post.new(uri, headers).tap { _1.body = body }
+      end
+    end
+
+    # @return [Float, nil] seconds to wait before retrying, or nil to raise the error now
+    def retry_delay(error, retries, deadline)
+      return if retries >= @max_retries
+      return unless error.is_a?(ConnectionError) || ErrorResponse.retryable?(error.error_code)
+
+      delay = error.retry_after_seconds&.clamp(0, MAX_RETRY_AFTER) || backoff(retries)
+      delay if clock + delay < deadline
+    end
+
+    def backoff(retries)
+      base = FIRST_BACKOFF * (2**retries)
+      base + (base * JITTER * rand)
+    end
+
+    def clock
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end