pinesandbox 0.3.19 → 0.3.20

data/lib/pinesandbox/artifacts.rb

@@ -0,0 +1,776 @@
+require "faraday"
+require "json"
+require "pathname"
+require "securerandom"
+require "stringio"
+require "time"
+require "uri"
+require_relative "adapters/coordinator_adapter"
+require_relative "clock"
+require_relative "errors"
+require_relative "response_handler"
+require_relative "streamed_read"
+require_relative "version"
+require_relative "models/artifact_file"
+
+module PineSandbox
+  # @api private — what a path in a Computer's artifacts may be, checked the
+  # same way by every SDK, pine-artifact and Pine before any request (a copy
+  # of contract/artifact-paths.json, which the test suite runs).
+  module ArtifactPath
+    MAX_BYTES = 900
+    # The C0 and C1 control characters.
+    CONTROL = /[\u0000-\u001F\u007F-\u009F]/
+
+    module_function
+
+    # Returns `path` as UTF-8 when it is 1 to MAX_BYTES bytes of valid UTF-8
+    # with no control character and no empty, "." or ".." segment (so no
+    # leading, trailing or doubled "/"); raises ArgumentError otherwise.
+    # Anything else is allowed. `name` is the argument, for the message.
+    def check!(path, name: "artifact path")
+      raise ArgumentError, "#{name} must be a String" unless path.is_a?(String)
+      raise ArgumentError, "#{name} must be 1 to #{MAX_BYTES} bytes" unless path.bytesize.between?(1, MAX_BYTES)
+
+      utf8 = path.dup.force_encoding(Encoding::UTF_8)
+      raise ArgumentError, "#{name} must be valid UTF-8" unless utf8.valid_encoding?
+      raise ArgumentError, "#{name} must not contain a control character" if utf8.match?(CONTROL)
+      if utf8.split("/", -1).any? { |segment| segment.empty? || segment == "." || segment == ".." }
+        raise ArgumentError, "#{name} must not have an empty, \".\" or \"..\" segment"
+      end
+
+      utf8
+    end
+  end
+
+  # @api private — the content type an upload gets when it names none, the
+  # same in every SDK whatever the host's MIME database holds (a copy of
+  # contract/artifact-content-types.json, which the test suite checks this
+  # table against).
+  module ArtifactContentType
+    DEFAULT = "application/octet-stream"
+    # By extension, in lower case.
+    TYPES = {
+      "css" => "text/css",
+      "csv" => "text/csv",
+      "doc" => "application/msword",
+      "docx" => "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      "gif" => "image/gif",
+      "gz" => "application/gzip",
+      "htm" => "text/html",
+      "html" => "text/html",
+      "jpeg" => "image/jpeg",
+      "jpg" => "image/jpeg",
+      "js" => "text/javascript",
+      "json" => "application/json",
+      "md" => "text/markdown",
+      "mp3" => "audio/mpeg",
+      "mp4" => "video/mp4",
+      "pdf" => "application/pdf",
+      "png" => "image/png",
+      "ppt" => "application/vnd.ms-powerpoint",
+      "pptx" => "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+      "svg" => "image/svg+xml",
+      "tar" => "application/x-tar",
+      "tsv" => "text/tab-separated-values",
+      "txt" => "text/plain",
+      "wav" => "audio/wav",
+      "webm" => "video/webm",
+      "webp" => "image/webp",
+      "xls" => "application/vnd.ms-excel",
+      "xlsx" => "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+      "xml" => "application/xml",
+      "yaml" => "application/yaml",
+      "yml" => "application/yaml",
+      "zip" => "application/zip"
+    }.freeze
+
+    module_function
+
+    # The type for the extension of `path`'s last segment: what follows its
+    # last ".", unless that "." starts the segment, in lower case. DEFAULT
+    # for any other path.
+    def for_path(path)
+      segment = path.rpartition("/").last
+      dot = segment.rindex(".")
+      return DEFAULT unless dot&.positive?
+
+      TYPES.fetch(segment[(dot + 1)..].downcase, DEFAULT)
+    end
+  end
+
+  # client.artifacts(computer_id) — a Computer's artifacts: the files it keeps
+  # beyond its sessions, reachable with the project key whether the Computer
+  # is running or stopped.
+  #
+  #   artifacts = client.artifacts(computer_id)
+  #   page = artifacts.list(prefix: "research/")     # page.files, page.folders, page.next_page_token
+  #   artifacts.upload("inputs/brief.txt", Pathname("brief.txt"), note: "the brief")
+  #   artifacts.download("reports/q3.pdf", "q3.pdf") # => bytes written
+  #   artifacts.open("reports/q3.csv") { |chunk| io.write(chunk) }
+  #   artifacts.copy(other_computer_id, "templates/form.pdf", "inputs/form.pdf")
+  #   artifacts.delete("inputs/brief.txt")
+  #
+  # A path is relative to the Computer's artifacts, such as "reports/q3.pdf":
+  # 1 to 900 bytes of UTF-8 with no control character and no empty, "." or
+  # ".." segment, or the call raises ArgumentError before any request.
+  # The handle gets one short-lived storage token from Pine, then sends every
+  # request to storage itself: no file passes through Pine. It keeps the
+  # token and gets a new one before it lapses, or once when storage refuses
+  # it. A missing file is ArtifactNotFoundError; any other refusal from
+  # storage is the status tier's ApiError, with storage's message, and an
+  # answer the storage protocol doesn't allow, such as a success whose body
+  # isn't a JSON object, is PineSandbox::Error. An error's #retryable? follows
+  # the storage rule every SDK shares (contract/storage-retry.json): true for
+  # a request timeout, a 429 and any 5xx but 501. An error's #op names the
+  # route with "{object}" for the file's name; the path is only in typed
+  # fields such as ArtifactNotFoundError#path. Public links are the running
+  # Computer's: Computer#artifact_link.
+  class Artifacts
+    include PineSandbox::ResponseHandler
+
+    # A token is replaced this many seconds before it expires.
+    TOKEN_RENEW_BEFORE = 300
+
+    # The storage token and where the artifacts are. The access token never
+    # appears in #inspect.
+    Token = Struct.new(:access_token, :expires_at, :endpoint, :bucket, :prefix, :writable,
+                       :used_bytes, :limit_bytes, :copy_from, keyword_init: true) do
+      def self.from_payload(payload)
+        new(access_token: payload["access_token"], expires_at: Time.iso8601(payload["expires_at"]),
+            endpoint: payload["endpoint"].delete_suffix("/"), bucket: payload["bucket"],
+            prefix: payload["prefix"], writable: payload["writable"], used_bytes: payload["used_bytes"],
+            limit_bytes: payload["limit_bytes"], copy_from: payload["copy_from"] || {})
+      end
+
+      def inspect = "#<PineSandbox::Artifacts::Token bucket=#{bucket.inspect} prefix=#{prefix.inspect} [access_token redacted]>"
+      alias_method :to_s, :inspect
+
+      def pretty_print(printer) = printer.text(inspect)
+    end
+    private_constant :Token
+
+    # An upload's bytes, readable from any offset: a String, a local file (a
+    # Pathname), or an IO whose size is known, read from its current position.
+    class Upload
+      attr_reader :size
+
+      def initialize(source)
+        @start = 0
+        case source
+        when String
+          @io = StringIO.new(source)
+          @size = source.bytesize
+        when Pathname
+          @path = source
+          @size = File.size(source)
+        else
+          unless %i[read size seek pos].all? { |name| source.respond_to?(name) }
+            raise ArgumentError, "source must be a String of bytes, a Pathname, or an IO whose size is known"
+          end
+
+          @io = source
+          @start = source.pos
+          @size = source.size - @start
+        end
+      end
+
+      # Yields the bytes from `offset` to the end, as an IO.
+      def from(offset)
+        io = @path ? File.open(@path, "rb") : @io
+        io.seek(@start + offset)
+        yield io
+      ensure
+        io&.close if @path
+      end
+    end
+    private_constant :Upload
+
+    BlockError = StreamedRead::BlockError
+    private_constant :BlockError
+
+    attr_reader :computer_id
+
+    # @api private — Client#artifacts builds the handle. `token_source` is
+    # the project-key Portal client (#artifact_token).
+    def initialize(computer_id:, token_source:, clock: PineSandbox::SYSTEM_CLOCK)
+      @computer_id = computer_id
+      @token_source = token_source
+      @clock = clock
+      @tokens = {}
+      @connections = {}
+      @mutex = Mutex.new
+    end
+
+    # One page of the files under `prefix` ("" for all of them, "research/"
+    # for one folder). Unless `recursive`, a file in a deeper folder is
+    # summarized by its folder in the page's #folders. Pass a page's
+    # #next_page_token as `page_token` for the next one; `page_size` caps how
+    # many files and folders a page holds.
+    #
+    # @return [PineSandbox::Models::ArtifactPage]
+    def list(prefix: "", recursive: false, page_token: nil, page_size: nil)
+      unless page_size.nil? || (page_size.is_a?(Integer) && page_size.positive?)
+        raise ArgumentError, "page_size must be a positive integer"
+      end
+
+      with_token do |token|
+        params = { "prefix" => "#{token.prefix}#{prefix}" }
+        params["delimiter"] = "/" unless recursive
+        params["pageToken"] = page_token if page_token
+        params["maxResults"] = page_size if page_size
+        route = objects_route(token)
+        op = "GET /#{route}"
+        response = resending { storage_request(token, :get, route, op: op, params: params) }
+        raise_storage_error!(response, op: op) unless response.success?
+
+        body = parse_answer(response, op: op)
+        Models::ArtifactPage.new(
+          files: Array(body["items"]).map { |object| Models::ArtifactFile.from_object(object, prefix: token.prefix) },
+          folders: Array(body["prefixes"]).map { |folder| folder.delete_prefix(token.prefix) },
+          next_page_token: body["nextPageToken"]
+        )
+      end
+    end
+
+    # Saves `source` as the file at `path`, replacing any file there, and
+    # returns the saved file. `source` is the bytes (a String), a local file
+    # (a Pathname), or an IO whose size is known, such as a File, StringIO or
+    # Tempfile, read from its current position. `content_type` defaults to
+    # the one every SDK gives the path's extension, else
+    # application/octet-stream; `note` is kept with the file and listed with
+    # it.
+    #
+    # The bytes go to storage in one resumable transfer, whose start is sent
+    # again when its answer is lost. After a dropped connection or a storage
+    # answer worth retrying mid-transfer (a request timeout, a 429 or a 5xx but
+    # 501), the SDK waits (RetryPolicy's stream backoff), asks storage how much
+    # it kept, and sends the rest; it gives up after
+    # RetryPolicy::STREAM_RECONNECT_BUDGET tries in a row that moved nothing.
+    # Raises ArtifactStorageFullError, sending nothing, while the Computer's
+    # artifacts are over their limit; after one, the next upload or copy asks
+    # Pine again, so room made by deleting files is used.
+    #
+    # @return [PineSandbox::Models::ArtifactFile]
+    def upload(path, source, content_type: nil, note: nil)
+      path = ArtifactPath.check!(path)
+      upload = Upload.new(source)
+      content_type ||= ArtifactContentType.for_path(path)
+      token, session = with_token(write: true) do |current|
+        [current, start_upload(current, "#{current.prefix}#{path}", upload.size, content_type, note)]
+      end
+      Models::ArtifactFile.from_object(send_upload(session, upload, content_type), prefix: token.prefix)
+    end
+
+    # Saves the file at `path` to the local file `destination` and returns
+    # the number of bytes written. The bytes land in a temporary file beside
+    # `destination` that is renamed over it once complete, so `destination`
+    # is never left half-written. It resumes as #open does.
+    def download(path, destination)
+      path = ArtifactPath.check!(path)
+      destination = File.expand_path(destination.to_s)
+      part = File.join(File.dirname(destination), ".#{File.basename(destination)}.#{SecureRandom.hex(6)}.part")
+      written = File.open(part, File::WRONLY | File::CREAT | File::EXCL | File::BINARY) do |file|
+        receive(path) { |chunk| file.write(chunk) }
+      end
+      File.rename(part, destination)
+      written
+    ensure
+      File.delete(part) if part && File.exist?(part)
+    end
+
+    # The file at `path` as a stream, for copying onward without holding it
+    # in memory: yields binary chunks as they arrive. Without a block,
+    # returns an Enumerator of the chunks that sends the request only when
+    # iterated (`artifacts.open(path).each { |chunk| io.write(chunk) }`).
+    #
+    # After a dropped connection, a request timeout, a 429 or a 5xx but 501,
+    # the SDK waits (RetryPolicy's stream backoff) and asks again from the
+    # next byte, of
+    # the same version of the file: one replaced meanwhile raises storage's
+    # PreconditionFailedError rather than joining two versions. It gives up
+    # after RetryPolicy::STREAM_RECONNECT_BUDGET tries in a row that received
+    # nothing. A missing file raises ArtifactNotFoundError before any chunk.
+    #
+    # @yieldparam chunk [String] the next bytes, binary encoding.
+    # @return [nil, Enumerator]
+    def open(path, &block)
+      path = ArtifactPath.check!(path)
+      return enum_for(:open, path) unless block
+
+      receive(path, &block)
+      nil
+    end
+
+    # Copies the file at `from_path` in `from_computer_id` (this Computer or
+    # another of the project's) to `path` in this one, replacing any file
+    # there, and returns the copy. Storage copies the bytes itself; nothing is
+    # downloaded, and a step whose answer was lost is sent again. Raises
+    # ArtifactNotFoundError for `from_path` when that file isn't there, and
+    # ArtifactStorageFullError, copying nothing, while this Computer's
+    # artifacts are over their limit.
+    #
+    # @return [PineSandbox::Models::ArtifactFile]
+    def copy(from_computer_id, from_path, path)
+      unless from_computer_id.to_s.match?(Computer::UUID_V7)
+        raise ArgumentError, "from_computer_id must be a lowercase UUIDv7"
+      end
+      from_path = ArtifactPath.check!(from_path, name: "from_path")
+      path = ArtifactPath.check!(path)
+
+      # A copy within this Computer reads with its own token, under its own
+      # prefix; another Computer's files need a token that may read them.
+      source_id = from_computer_id == @computer_id ? nil : from_computer_id
+      # A large file takes several rewrite calls; each answer says how to go on.
+      rewrite_token = nil
+      op = nil
+      loop do
+        token, body = with_token(copy_from: source_id, write: true) do |current|
+          source_prefix = source_id ? current.copy_from.fetch(source_id) : current.prefix
+          source, source_label = object_route(current, "#{source_prefix}#{from_path}")
+          target = "/rewriteTo/b/#{escape(current.bucket)}/o/"
+          route = "#{source}#{target}#{escape("#{current.prefix}#{path}")}"
+          op = "POST /#{source_label}#{target}{object}"
+          params = rewrite_token ? { "rewriteToken" => rewrite_token } : {}
+          # Rewriting the same object to the same name again changes nothing,
+          # so a rewrite whose answer was lost is sent again.
+          response = resending { storage_request(current, :post, route, op: op, params: params, json: {}) }
+          raise_storage_error!(response, op: op, path: from_path) unless response.success?
+
+          [current, parse_answer(response, op: op)]
+        end
+        if body["done"] == true
+          unless body["resource"].is_a?(Hash)
+            raise PineSandbox::Error, PineSandbox.with_context("storage ended the copy without the copy", op: op)
+          end
+
+          return Models::ArtifactFile.from_object(body["resource"], prefix: token.prefix)
+        end
+
+        rewrite_token = body["rewriteToken"]
+        if rewrite_token.to_s.empty?
+          raise PineSandbox::Error, PineSandbox.with_context("storage stopped the copy without finishing it", op: op)
+        end
+      end
+    end
+
+    # Deletes the file at `path`. Raises ArtifactNotFoundError when it isn't
+    # there. A delete whose answer was lost is sent again; when that finds no
+    # file, the first one removed it, and the delete succeeds. Returns true.
+    def delete(path)
+      path = ArtifactPath.check!(path)
+      with_token do |token|
+        route, label = object_route(token, "#{token.prefix}#{path}")
+        op = "DELETE /#{label}"
+        resent = false
+        response = resending do |resend|
+          resent = resend
+          storage_request(token, :delete, route, op: op)
+        end
+        next if response.status == 404 && resent
+
+        raise_storage_error!(response, op: op, path: path) unless response.success?
+      end
+      true
+    end
+
+    private
+
+    # Runs the block with a current storage token: this Computer's or, with
+    # `copy_from`, one that may also read that Computer's artifacts. When
+    # storage refuses the token (401), runs it once more with a new one.
+    # `write` needs a writable token: a kept one that isn't is replaced, and
+    # a new one that isn't either means the artifacts are over their limit.
+    def with_token(copy_from: nil, write: false)
+      current = token(copy_from, write: write)
+      renewed = false
+      begin
+        if write && !current.writable
+          raise ArtifactStorageFullError.new(used_bytes: current.used_bytes, limit_bytes: current.limit_bytes)
+        end
+
+        yield current
+      rescue UnauthorizedError
+        raise if renewed
+
+        renewed = true
+        current = token(copy_from, refused: current, write: write)
+        retry
+      end
+    end
+
+    # The kept token for `copy_from`, or a new one when there is none, when it
+    # expires within TOKEN_RENEW_BEFORE, when it is the one storage `refused`,
+    # or when a `write` finds it read-only (files may have been deleted since).
+    def token(copy_from, refused: nil, write: false)
+      @mutex.synchronize do
+        kept = @tokens[copy_from]
+        usable = kept && !kept.equal?(refused) && (kept.writable || !write) &&
+                 @clock.now < kept.expires_at - TOKEN_RENEW_BEFORE
+        return kept if usable
+
+        payload = @token_source.artifact_token(@computer_id, copy_from: copy_from)
+        @tokens[copy_from] = Token.from_payload(payload)
+      end
+    end
+
+    # A connection to a storage origin. No credential rides on it: each
+    # request carries its own.
+    def connection(origin)
+      @mutex.synchronize do
+        @connections[origin] ||= Faraday.new(url: origin) do |conn|
+          conn.headers["User-Agent"] = PineSandbox::USER_AGENT
+          conn.options.open_timeout = Adapters::CoordinatorAdapter::DEFAULT_OPEN_TIMEOUT
+          conn.options.timeout = Adapters::CoordinatorAdapter::DEFAULT_HTTP_TIMEOUT
+          conn.adapter Faraday.default_adapter
+        end
+      end
+    end
+
+    # Sends one storage request with the token as its bearer. `op` names it
+    # in errors.
+    def storage_request(token, method, route, op:, params: {}, json: nil, headers: {})
+      transport(op) do
+        connection(token.endpoint).run_request(method, route, nil, nil) do |req|
+          req.params.update(params)
+          req.headers["Authorization"] = "Bearer #{token.access_token}"
+          req.headers["Accept"] = "application/json"
+          headers.each { |name, value| req.headers[name] = value }
+          if json
+            req.headers["Content-Type"] = "application/json"
+            req.body = JSON.generate(json)
+          end
+        end
+      end
+    end
+
+    # Runs the block, a request safe to send again, once more after each
+    # transport fault or answer the storage retry rule allows, with
+    # RetryPolicy's transient backoff, up to RetryPolicy::TRANSIENT_ATTEMPTS
+    # sends, and returns the last answer. Yields whether this send is a
+    # resend, which may find the first one's work already done.
+    def resending
+      attempt = 0
+      loop do
+        attempt += 1
+        begin
+          response = yield attempt > 1
+        rescue PineSandbox::ConnectionError, PineSandbox::TimeoutError
+          raise if attempt >= RetryPolicy::TRANSIENT_ATTEMPTS
+        else
+          return response unless retry_status?(response.status) && attempt < RetryPolicy::TRANSIENT_ATTEMPTS
+        end
+        @clock.sleep(RetryPolicy.transient_backoff(attempt, @clock))
+      end
+    end
+
+    # Opens a resumable upload of `size` bytes to the object `name` and
+    # returns its session URI.
+    def start_upload(token, name, size, content_type, note)
+      body = { name: name, contentType: content_type }
+      body[:metadata] = { "pine-note" => note } unless note.nil?
+      route = "upload/#{objects_route(token)}"
+      op = "POST /#{route}"
+      # Starting a session writes nothing, and a session a lost answer left
+      # unused expires on its own, so a start is sent again.
+      response = resending do
+        storage_request(
+          token, :post, route, op: op,
+          params: { "uploadType" => "resumable", "name" => name }, json: body,
+          headers: { "X-Upload-Content-Type" => content_type, "X-Upload-Content-Length" => size.to_s }
+        )
+      end
+      raise_storage_error!(response, op: op) unless response.success?
+
+      session = response.headers["location"].to_s
+      raise PineSandbox::Error, PineSandbox.with_context("storage opened no upload session", op: op) if session.empty?
+
+      session
+    end
+
+    # Sends the upload's bytes to its session and returns the saved object.
+    # A PUT that ends without the whole file (a dropped connection, an answer
+    # worth retrying, or a 308 that kept only part) is followed, after a
+    # wait, by asking storage how much it kept; the rest goes in the next PUT.
+    # The budget counts tries in a row that moved nothing.
+    def send_upload(session, upload, content_type)
+      op = "PUT #{URI(session).path}"
+      offset = 0
+      failures = 0
+      loop do
+        outcome = upload_call(op) { put_bytes(session, upload, offset, content_type) }
+        until finished?(outcome)
+          raise_upload_failure!(outcome, op) unless interrupted?(outcome)
+
+          failures += 1
+          raise_upload_failure!(outcome, op) if failures > RetryPolicy::STREAM_RECONNECT_BUDGET
+          @clock.sleep(RetryPolicy.stream_backoff(failures, @clock))
+          outcome = upload_call(op) { query_upload(session, upload.size, content_type) }
+          break if outcome.is_a?(Faraday::Response) && outcome.status == 308
+        end
+        return parse_answer(outcome, op: op) if finished?(outcome)
+
+        kept = kept_bytes(outcome)
+        failures = 0 if kept > offset
+        offset = kept
+      end
+    end
+
+    # The session URI is the upload's credential, so these PUTs carry no
+    # Authorization. Once storage keeps every byte, the PUT asks for the
+    # finished upload instead.
+    def put_bytes(session, upload, offset, content_type)
+      return query_upload(session, upload.size, content_type) if upload.size.positive? && offset >= upload.size
+
+      upload.from(offset) do |body|
+        connection(origin(session)).put(session) do |req|
+          req.headers["Content-Type"] = content_type
+          req.headers["Content-Length"] = (upload.size - offset).to_s
+          req.headers["Content-Range"] = "bytes #{offset}-#{upload.size - 1}/#{upload.size}" if upload.size.positive?
+          req.body = body
+        end
+      end
+    end
+
+    def query_upload(session, size, content_type)
+      connection(origin(session)).put(session) do |req|
+        req.headers["Content-Type"] = content_type
+        req.headers["Content-Length"] = "0"
+        req.headers["Content-Range"] = "bytes */#{size}"
+        req.body = ""
+      end
+    end
+
+    # An upload request's response, or the transport fault that ended it.
+    def upload_call(op)
+      transport(op) { yield }
+    rescue PineSandbox::ConnectionError, PineSandbox::TimeoutError => e
+      e
+    end
+
+    def finished?(outcome) = outcome.is_a?(Faraday::Response) && [200, 201].include?(outcome.status)
+
+    def interrupted?(outcome)
+      !outcome.is_a?(Faraday::Response) || outcome.status == 308 || retry_status?(outcome.status)
+    end
+
+    # Raises why an upload stopped: its transport fault, storage's refusal,
+    # or, after a 308, that storage stopped taking bytes.
+    def raise_upload_failure!(outcome, op)
+      raise outcome unless outcome.is_a?(Faraday::Response)
+      if outcome.status == 308
+        raise PineSandbox::Error, PineSandbox.with_context("storage stopped the upload without finishing it", op: op)
+      end
+
+      raise_storage_error!(outcome, op: op)
+    end
+
+    # The bytes storage holds, from a 308's `Range: bytes=0-N` (none without it).
+    def kept_bytes(response)
+      last = response.headers["range"].to_s[/\Abytes=0-(\d+)\z/, 1]
+      last ? Integer(last, 10) + 1 : 0
+    end
+
+    # Passes the file at `path` to the block in chunks, each byte once, and
+    # returns how many it passed. After a dropped connection or an answer
+    # worth retrying it waits and asks again from the next byte with a Range request pinned
+    # to the version the first answer named, so a file replaced meanwhile
+    # fails (storage's 412) instead of joining two versions. The budget
+    # counts tries in a row that received nothing. The block's own error
+    # ends the read as it is.
+    def receive(path, &sink)
+      received = 0
+      failures = 0
+      generation = nil
+      loop do
+        before = received
+        begin
+          read_object(path, from: received, generation: generation) do |chunk, headers|
+            generation ||= headers["x-goog-generation"]
+            sink.call(chunk)
+            received += chunk.bytesize
+          end
+          return received
+        rescue BlockError => e
+          raise e.error
+        rescue PineSandbox::Error => e
+          raise unless resumable?(e)
+
+          failures = received > before ? 1 : failures + 1
+          raise if failures > RetryPolicy::STREAM_RECONNECT_BUDGET
+
+          @clock.sleep(RetryPolicy.stream_backoff(failures, @clock))
+        end
+      end
+    end
+
+    # Whether a failed read is worth resuming: a dropped connection, a
+    # timeout, or an answer worth retrying.
+    def resumable?(error)
+      case error
+      when PineSandbox::ConnectionError, PineSandbox::TimeoutError then true
+      when ApiError then retry_status?(error.status.to_i)
+      else false
+      end
+    end
+
+    # Whether a storage answer of `status` is worth sending again, by the rule
+    # every SDK shares (contract/storage-retry.json): a request timeout, a 429
+    # and any 5xx but 501. A 412 means the file changed under a read pinned to
+    # its version, so it never is.
+    def retry_status?(status) = status == 408 || status == 429 || (status >= 500 && status != 501)
+
+    # GETs the file's bytes from byte `from` on, passing each new chunk of a
+    # successful answer, with its headers, to the block. A read from a later
+    # byte asks for `generation` only. Any other answer raises before a
+    # chunk: ArtifactNotFoundError for a missing file.
+    def read_object(path, from: 0, generation: nil, &sink)
+      with_token do |token|
+        route, label = object_route(token, "#{token.prefix}#{path}")
+        stream_media(token, route, "GET /#{label}", path, from, generation, sink)
+      end
+    end
+
+    def stream_media(token, route, op, path, from, generation, sink)
+      delivered = 0
+      # The bytes at the answer's start that were passed on before, known
+      # once the first chunk shows the answer.
+      repeated = nil
+      deliver = lambda do |chunk, answer|
+        repeated ||= repeated_bytes(answer, from, op)
+        delivered += chunk.bytesize
+        fresh = chunk.byteslice([repeated, chunk.bytesize].min..)
+        repeated -= chunk.bytesize - fresh.bytesize
+        pass_on(sink, fresh, answer) unless fresh.empty?
+      end
+      response = StreamedRead.read(deliver) do |on_data|
+        transport(op) do
+          connection(token.endpoint).get(route) do |req|
+            req.params["alt"] = "media"
+            req.headers["Authorization"] = "Bearer #{token.access_token}"
+            if from.positive?
+              req.headers["Range"] = "bytes=#{from}-"
+              req.params["ifGenerationMatch"] = generation if generation
+            end
+            req.options.on_data = on_data
+          end
+        end
+      end
+      raise_storage_error!(response, op: op, path: path) unless response.success?
+      # Net::HTTP ends a body that stops short of its length like a complete
+      # one, so a connection dropped mid-file is caught here.
+      declared = declared_bytes(response)
+      if declared && delivered < declared
+        raise PineSandbox::ConnectionError,
+              PineSandbox.with_context("storage connection ended after #{delivered} of #{declared} bytes", op: op)
+      end
+      response
+    end
+
+    # How many bytes at the start of a media answer to a read from byte
+    # `from` were passed on before: `from` when storage sends the whole file,
+    # none when it sends the range asked for. A range from anywhere else is
+    # PineSandbox::Error. `answer` is the Faraday env or response.
+    def repeated_bytes(answer, from, op)
+      return 0 unless from.positive?
+      return from unless answer.status == 206
+
+      range = answer_headers(answer)["content-range"].to_s
+      start = range[/\Abytes (\d+)-/, 1]
+      return 0 if start && Integer(start, 10) == from
+
+      raise PineSandbox::Error,
+            PineSandbox.with_context("storage resumed the artifact at the wrong place (Content-Range #{range.inspect})", op: op)
+    end
+
+    # The bytes a media answer says it carries, when it says so plainly (not
+    # for a compressed one, whose length is of the compressed bytes).
+    def declared_bytes(response)
+      encoding = response.headers["content-encoding"].to_s
+      return unless encoding.empty? || encoding.casecmp?("identity")
+
+      range = response.headers["content-range"].to_s.match(%r{\Abytes (\d+)-(\d+)/})
+      return Integer(range[2], 10) - Integer(range[1], 10) + 1 if response.status == 206 && range
+
+      length = response.headers["content-length"].to_s
+      Integer(length, 10) if length.match?(/\A\d+\z/)
+    end
+
+    # Passes a chunk, with its answer's headers, to the block.
+    def pass_on(sink, chunk, answer) = StreamedRead.pass(sink, chunk, answer_headers(answer))
+
+    # The headers of `answer`, a Faraday env or response.
+    def answer_headers(answer) = answer.respond_to?(:response_headers) ? answer.response_headers : answer.headers
+
+    # Maps a transport fault to the SDK's typed errors. `op` carries no query,
+    # so an upload session's id never reaches a message.
+    def transport(op)
+      yield
+    rescue Faraday::TimeoutError => e
+      raise PineSandbox::TimeoutError, PineSandbox.with_context("storage request timed out: #{e.message}", op: op)
+    rescue Faraday::ConnectionFailed, Faraday::SSLError => e
+      raise PineSandbox::ConnectionError, PineSandbox.with_context("storage connection failed: #{e.message}", op: op)
+    end
+
+    # Raises the error for a storage answer that isn't a success, of the
+    # operation `op`. For a call on one file (`path`), a 404 is
+    # ArtifactNotFoundError; anything else is the status tier's ApiError with
+    # storage's own message. Its #retryable? is the storage rule's.
+    def raise_storage_error!(response, op:, path: nil)
+      body = parse_error_answer(response.body)
+      detail = body["error"].is_a?(Hash) ? body["error"]["message"].to_s : ""
+      fields = { status: response.status, response_body: response.body.to_s,
+                 problem_extensions: { "op" => op, "retryable" => retry_status?(response.status) } }
+      error =
+        if response.status == 404 && path
+          ArtifactNotFoundError.new(path: path, error_message: "no artifact at #{path}", **fields)
+        else
+          message = detail.empty? ? "storage request failed (HTTP #{response.status})" : detail
+          status_tier_class_for(response.status).new(error_message: message, **fields)
+        end
+      seconds = Integer(response.headers["retry-after"].to_s.strip, 10, exception: false)
+      error.retry_after = seconds if seconds&.positive?
+      raise error
+    end
+
+    # A success answer's JSON object. Any other body is an answer the storage
+    # protocol doesn't allow.
+    def parse_answer(response, op:)
+      parsed = JSON.parse(response.body.to_s)
+      return parsed if parsed.is_a?(Hash)
+
+      raise PineSandbox::Error, PineSandbox.with_context("storage answered with JSON that isn't an object", op: op)
+    rescue JSON::ParserError
+      raise PineSandbox::Error, PineSandbox.with_context("storage answered with a body that isn't JSON", op: op)
+    end
+
+    # An error answer's JSON object, or {} when its body is none: the error
+    # keeps the raw body either way.
+    def parse_error_answer(body)
+      parsed = JSON.parse(body.to_s)
+      parsed.is_a?(Hash) ? parsed : {}
+    rescue JSON::ParserError
+      {}
+    end
+
+    # The JSON API route of the objects in the token's bucket.
+    def objects_route(token) = "storage/v1/b/#{escape(token.bucket)}/o"
+
+    # The JSON API route of the object `name`, and the same route with
+    # "{object}" for the name, for errors.
+    def object_route(token, name)
+      objects = objects_route(token)
+      ["#{objects}/#{escape(name)}", "#{objects}/{object}"]
+    end
+
+    # Percent-encodes every byte but the unreserved ones, "/" and " " included.
+    def escape(segment)
+      segment.to_s.b.gsub(/[^A-Za-z0-9\-._~]/n) { |byte| format("%%%02X", byte.ord) }
+    end
+
+    def origin(url)
+      uri = URI(url)
+      "#{uri.scheme}://#{uri.host}#{":#{uri.port}" unless uri.port == uri.default_port}"
+    end
+  end
+end