files.com 1.1.768 → 1.1.769

data/spec/models/file_transfer_spec.rb

@@ -0,0 +1,346 @@
+require "spec_helper"
+require "stringio"
+require "tmpdir"
+require "zlib"
+require_relative "../support/transfer_server"
+
+RSpec.describe Files::File, "transfers" do
+  # 22,528 bytes that include every byte value, so text handling would show.
+  let(:payload) { (0..255).map(&:chr).join.b * 88 }
+  let(:signed_target) { "/objects/report.bin?X-Amz-Credential=fixture%2Fcredential&X-Amz-Signature=fixture-signature" }
+  let(:sink) { StringIO.new("".b) }
+  let(:servers) { [] }
+  # A fixture server that pops this waits until the example closes it.
+  let(:server_gate) { Queue.new }
+
+  around do |example|
+    original = [ Files.api_key, Files.base_url, Files.max_network_retries, Files.session_id, Files.workspace_id ]
+    Files.api_key = "fixture-api-key"
+    Files.max_network_retries = 0
+    Files.session_id = "fixture-session"
+    Files.workspace_id = 7
+    example.run
+  ensure
+    Files.api_key, Files.base_url, Files.max_network_retries, Files.session_id, Files.workspace_id = original
+  end
+
+  after do
+    server_gate.close
+    servers.each(&:close)
+  end
+
+  def serve(response = nil, &respond)
+    respond ||= ->(client) { client.write(response) }
+    TransferServer.new(&respond).tap { |server| servers << server }
+  end
+
+  def remote_file(server)
+    described_class.new(path: "report.bin", download_uri: server.url(signed_target))
+  end
+
+  def response(...)
+    TransferServer.response(...)
+  end
+
+  def fixed_length(body, declared_bytes: body.bytesize)
+    response("200 OK", { "Content-Length" => declared_bytes }, body)
+  end
+
+  # A body in chunked transfer coding. An incomplete one stops before the final
+  # zero-length chunk, as when the connection drops.
+  def chunked(*chunks, complete: true)
+    encoded = chunks.map { |chunk| "#{chunk.bytesize.to_s(16)}\r\n#{chunk}\r\n" }.join
+    complete ? "#{encoded}0\r\n\r\n" : encoded
+  end
+
+  describe ".upload_file" do
+    it "raises the filesystem error when the local source does not exist" do
+      Dir.mktmpdir do |dir|
+        missing_path = File.join(dir, "missing.bin")
+
+        expect { described_class.upload_file(missing_path, "report.bin") }.to raise_error(Errno::ENOENT)
+      end
+    end
+  end
+
+  describe "#download_content" do
+    def download(raw_response, range: [])
+      server = serve(raw_response)
+      remote_file(server).download_content(sink, range: range)
+      server
+    end
+
+    it "writes a fixed-length body exactly and leaves the caller's IO open" do
+      download(fixed_length(payload))
+
+      expect(sink.string).to eq(payload)
+      expect(sink).not_to be_closed
+    end
+
+    it "writes a gzip body decompressed, although Content-Length counts compressed bytes" do
+      zipped = Zlib.gzip(payload)
+
+      download(response("200 OK", { "Content-Encoding" => "gzip", "Content-Length" => zipped.bytesize }, zipped))
+
+      expect(sink.string).to eq(payload)
+    end
+
+    it "writes the requested range of a partial-content response" do
+      part = payload.byteslice(4, 8)
+
+      server = download(response("206 Partial Content", { "Content-Range" => "bytes 4-11/#{payload.bytesize}", "Content-Length" => 8 }, part), range: [ 4, 11 ])
+
+      expect(sink.string).to eq(part)
+      expect(server.requests.map { |request| request.headers["range"] }).to eq([ "bytes=4-11" ])
+    end
+
+    it "writes a gzip-encoded range exactly as sent, without decompressing it" do
+      part = Zlib.gzip(payload).byteslice(0, 50)
+
+      download(response("206 Partial Content", { "Content-Encoding" => "gzip", "Content-Range" => "bytes 0-49/451", "Content-Length" => 50 }, part), range: [ 0, 49 ])
+
+      expect(sink.string).to eq(part)
+    end
+
+    it "writes a chunked body" do
+      download(response("200 OK", { "Transfer-Encoding" => "chunked" }, chunked(payload.byteslice(0, 4096), payload.byteslice(4096..))))
+
+      expect(sink.string).to eq(payload)
+    end
+
+    it "writes a body that ends when the server closes the connection" do
+      download(response("200 OK", {}, payload))
+
+      expect(sink.string).to eq(payload)
+    end
+
+    it "accepts an empty body" do
+      download(fixed_length(""))
+
+      expect(sink.string).to be_empty
+      expect(sink).not_to be_closed
+    end
+
+    it "requests the signed URL exactly as issued, without Files.com credentials" do
+      server = download(fixed_length(payload))
+
+      expect(server.requests.map(&:target)).to eq([ signed_target ])
+      expect(server.requests.first.headers.keys).not_to include("authorization", "x-filesapi-key", "x-filesapi-auth", "x-files-workspace-id")
+    end
+
+    it "raises EOFError when a fixed-length body ends early and leaves the caller's IO open for a retry" do
+      server = serve(fixed_length(payload.byteslice(0, 4096), declared_bytes: payload.bytesize))
+
+      expect { remote_file(server).download_content(sink) }.to raise_error(EOFError, "Transfer response ended after 4096 of 22528 bytes")
+      expect(server.requests.size).to eq(1)
+      expect(sink).not_to be_closed
+    end
+
+    it "raises EOFError when a partial-content body ends early" do
+      server = serve(response("206 Partial Content", { "Content-Range" => "bytes 4-11/#{payload.bytesize}", "Content-Length" => 8 }, payload.byteslice(4, 4)))
+
+      expect { remote_file(server).download_content(sink, range: [ 4, 11 ]) }.to raise_error(EOFError, "Transfer response ended after 4 of 8 bytes")
+    end
+
+    it "raises EOFError when a gzip-encoded range ends early, since Net::HTTP passes ranges through as sent" do
+      part = Zlib.gzip(payload).byteslice(0, 50)
+      server = serve(response("206 Partial Content", { "Content-Encoding" => "gzip", "Content-Range" => "bytes 0-49/451", "Content-Length" => 50 }, part.byteslice(0, 25)))
+
+      expect { remote_file(server).download_content(sink, range: [ 0, 49 ]) }.to raise_error(EOFError, "Transfer response ended after 25 of 50 bytes")
+    end
+
+    it "raises EOFError when an identity-encoded body ends early" do
+      server = serve(response("200 OK", { "Content-Encoding" => "identity", "Content-Length" => payload.bytesize }, payload.byteslice(0, 4096)))
+
+      expect { remote_file(server).download_content(sink) }.to raise_error(EOFError, "Transfer response ended after 4096 of 22528 bytes")
+    end
+
+    it "raises EOFError when a chunked body ends early, without requesting and writing it again" do
+      first_chunk = payload.byteslice(0, 4096)
+      server = serve(response("200 OK", { "Transfer-Encoding" => "chunked" }, chunked(first_chunk, complete: false)))
+
+      expect { remote_file(server).download_content(sink) }.to raise_error(EOFError)
+      expect(server.requests.size).to eq(1)
+      expect(sink.string).to eq(first_chunk)
+    end
+
+    it "raises for a refused transfer with an empty body and closes the caller's IO, without revealing the signed URL" do
+      server = serve(response("503 Service Unavailable", { "Content-Length" => 0 }))
+
+      expect { remote_file(server).download_content(sink) }.to raise_error(Net::HTTPFatalError, '503 "Service Unavailable"') { |error|
+        expect(error.full_message).not_to include("/objects/", "X-Amz", "fixture-signature")
+      }
+      expect(sink).to be_closed
+    end
+
+    it "does not write a refused transfer's error body" do
+      error_body = "<Error>Expired</Error>"
+      server = serve(response("403 Forbidden", { "Content-Length" => error_body.bytesize }, error_body))
+
+      expect { remote_file(server).download_content(sink) }.to raise_error(Net::HTTPClientException, '403 "Forbidden"')
+      expect(sink.string).to be_empty
+    end
+
+    it "raises the caller IO's own write error, even when closing that IO fails too" do
+      write_error = IOError.new("destination is full")
+      failing_sink = Class.new(StringIO) do
+        define_method(:<<) { |_bytes| raise write_error }
+
+        def close
+          super
+          raise IOError, "close failed too"
+        end
+      end.new
+      server = serve(fixed_length(payload))
+
+      expect { remote_file(server).download_content(failing_sink) }.to raise_error(IOError) { |error| expect(error).to equal(write_error) }
+      expect(failing_sink).to be_closed
+      expect(server.requests.size).to eq(1)
+    end
+  end
+
+  describe "#download_file" do
+    it "raises when the body ends early and closes the local file it created" do
+      server = serve(fixed_length(payload.byteslice(0, 4096), declared_bytes: payload.bytesize))
+
+      Dir.mktmpdir do |dir|
+        local_path = File.join(dir, "report.bin")
+
+        expect { remote_file(server).download_file(local_path) }.to raise_error(EOFError)
+        expect(ObjectSpace.each_object(File).select { |file| file.path == local_path }).to all(be_closed)
+      end
+    end
+  end
+
+  describe "#read_io" do
+    def open_pipes
+      ObjectSpace.each_object(Files::SizableIO).reject(&:closed?)
+    end
+
+    # Returns a file whose read_io has received the first 4096 of 22,528 bytes.
+    # The connection then drops, or later when the example closes server_gate,
+    # so the download fails while the caller is reading.
+    def file_whose_download_fails_later(drop_connection: true)
+      server = serve do |client|
+        client.write(fixed_length(payload.byteslice(0, 4096), declared_bytes: payload.bytesize))
+        server_gate.pop
+      end
+      file = remote_file(server)
+      file.read_io
+      server_gate.close if drop_connection
+      file
+    end
+
+    {
+      "read" => ->(reader) { reader.read },
+      "read(n) until eof?" => ->(reader) { reader.read(1024) until reader.eof? },
+      "gets" => ->(reader) { nil while reader.gets },
+      "readline" => ->(reader) { loop { reader.readline } },
+      "readpartial" => ->(reader) { loop { reader.readpartial(1024) } },
+      "each_line" => ->(reader) { reader.each_line.to_a },
+      "each" => ->(reader) { reader.each(&:itself) },
+    }.each do |reading, read_to_end|
+      it "raises a download failure that happens after reading began through #{reading}, then closes quietly" do
+        reader = file_whose_download_fails_later.read_io
+
+        expect { read_to_end.call(reader) }.to raise_error(EOFError, "Transfer response ended after 4096 of 22528 bytes")
+        expect { reader.close }.not_to raise_error
+        expect(reader).to be_closed
+      end
+    end
+
+    it "raises from eof? a failure that happens after the last full read" do
+      reader = file_whose_download_fails_later(drop_connection: false).read_io
+      expect(reader.read(4096).bytesize).to eq(4096)
+      server_gate.close
+
+      expect { reader.eof? }.to raise_error(EOFError, "Transfer response ended after 4096 of 22528 bytes")
+      expect { reader.close }.not_to raise_error
+    end
+
+    it "raises a download failure that happens after reading began from Files::File#read" do
+      file = file_whose_download_fails_later
+
+      expect { file.read }.to raise_error(EOFError, "Transfer response ended after 4096 of 22528 bytes")
+    ensure
+      file&.read_io&.close
+    end
+
+    it "raises from close a failure that IO.copy_stream read past" do
+      reader = file_whose_download_fails_later.read_io
+
+      Dir.mktmpdir do |dir|
+        copied_bytes = File.open(File.join(dir, "report.bin"), "wb") { |copy| IO.copy_stream(reader, copy) }
+        expect(copied_bytes).to eq(4096)
+      end
+      expect { reader.close }.to raise_error(EOFError, "Transfer response ended after 4096 of 22528 bytes")
+      expect(reader).to be_closed
+    end
+
+    it "raises from close a refusal that arrives after read_io stops waiting, releasing the pipe" do
+      server = serve do |client|
+        server_gate.pop
+        client.write(response("403 Forbidden", { "Content-Length" => 7 }, "refused"))
+      end
+      pipes_before = open_pipes
+      reader = remote_file(server).read_io # returns after its five-second wait for the first bytes
+      server_gate.close
+
+      nil while reader.getbyte
+
+      expect { reader.close }.to raise_error(Net::HTTPClientException, '403 "Forbidden"') { |close_error|
+        expect { reader.error! }.to raise_error(Net::HTTPClientException) { |stored_error| expect(stored_error).to equal(close_error) }
+      }
+      expect(open_pipes - pipes_before).to be_empty
+    end
+
+    it "does not let close replace an exception the caller is already raising" do
+      reader = file_whose_download_fails_later.read_io
+      callers_error = RuntimeError.new("caller failed")
+
+      expect {
+        begin
+          nil while reader.getbyte
+          raise callers_error
+        ensure
+          reader.close
+        end
+      }.to raise_error(RuntimeError) { |error| expect(error).to equal(callers_error) }
+      expect(reader).to be_closed
+    end
+
+    it "stops downloading once the caller closes the reader" do
+      body_bytes = 32 * 1024 * 1024 # far more than socket and pipe buffers hold
+      block = ("x" * 65_536).b
+      sent_everything = false
+      server = serve do |client|
+        client.write(response("200 OK", { "Content-Length" => body_bytes }))
+        (body_bytes / block.bytesize).times { client.write(block) }
+        sent_everything = true
+      end
+
+      reader = remote_file(server).read_io
+      reader.read(1024)
+      reader.close
+      server.close # returns once the server has stopped writing
+
+      expect(sent_everything).to be(false)
+    end
+
+    it "raises a refused transfer and closes the pipe it created" do
+      server = serve(response("403 Forbidden", { "Content-Length" => 0 }))
+      pipes_before = open_pipes
+
+      expect { remote_file(server).read_io }.to raise_error(Net::HTTPClientException, '403 "Forbidden"')
+      expect(open_pipes - pipes_before).to be_empty
+    end
+
+    it "raises a failed metadata lookup instead of returning an empty reader" do
+      not_found = { error: "Not Found", 'http-code': 404, type: "not-found" }.to_json
+      server = serve(response("404 Not Found", { "Content-Type" => "application/json", "Content-Length" => not_found.bytesize }, not_found))
+      Files.base_url = server.url("")
+
+      expect { described_class.new(path: "report.bin").read_io }.to raise_error(Files::NotFoundError)
+    end
+  end
+end

data/spec/models/persistence_spec.rb

@@ -0,0 +1,167 @@
+require "spec_helper"
+require_relative "../support/stubbed_api"
+
+RSpec.describe "Saving and updating models" do
+  include StubbedApi
+
+  let(:requests) { [] }
+
+  # The API's canonical form of a workspace name.
+  def canonical_workspace(env, id)
+    name = Faraday::Utils.parse_nested_query(env.body)["name"]
+    { id: id, name: name.strip.capitalize }
+  end
+
+  it "creates a new workspace with one POST, then updates the same object in place with one PATCH each" do
+    client = stubbed_api_client do |stub|
+      stub.post("/api/rest/v1/workspaces") do |env|
+        requests << :post
+        json_response(201, canonical_workspace(env, 42))
+      end
+      stub.patch("/api/rest/v1/workspaces/42") do |env|
+        requests << :patch
+        json_response(200, canonical_workspace(env, 42))
+      end
+    end
+    workspace = Files::Workspace.new({ name: " operations " }, api_key: "key-a", client: client)
+
+    expect(workspace.save).to be(true)
+    expect(workspace.attributes).to eq(id: 42, name: "Operations")
+
+    workspace.name = " finance "
+    expect(workspace.save).to be(true)
+    expect(workspace.name).to eq("Finance")
+
+    response, options = workspace.update(name: " legal ")
+    expect(response).to be_a(Files::Response)
+    expect(response.data).to eq(id: 42, name: "Legal")
+    expect(options).to include(api_key: "key-a", client: client)
+    expect(workspace.attributes).to eq(id: 42, name: "Legal")
+    expect(workspace.options).to include(api_key: "key-a", client: client)
+    expect(requests).to eq(%i[post patch patch])
+  end
+
+  it "leaves the object and its options unchanged when the update fails" do
+    client = stubbed_api_client do |stub|
+      stub.patch("/api/rest/v1/workspaces/42") { json_response(404, { error: "Workspace not found", type: "not-found" }) }
+    end
+    workspace = Files::Workspace.new({ id: 42, name: "Operations" }, api_key: "key-a")
+    workspace.name = "Finance"
+
+    expect { client.request { workspace.save } }.to raise_error(Files::NotFoundError, "Workspace not found")
+    expect(workspace.attributes).to eq(id: 42, name: "Finance")
+    expect(workspace.options).to eq(api_key: "key-a")
+  end
+
+  { "JSON null" => "null", "a JSON list" => "[]" }.each do |description, body|
+    it "rejects #{description} as the updated workspace, leaving the object and its options unchanged" do
+      client = stubbed_api_client do |stub|
+        stub.patch("/api/rest/v1/workspaces/42") do
+          requests << :patch
+          [ 200, { "Content-Type" => "application/json" }, body ]
+        end
+      end
+      workspace = Files::Workspace.new({ id: 42, name: "Operations" }, api_key: "key-a")
+      workspace.name = "Finance"
+
+      expect { client.request { workspace.save } }.to raise_error(Files::APIConnectionError) { |error|
+        expect(error).to be_an_instance_of(Files::APIConnectionError)
+        expect(error.http_body).to eq(body)
+      }
+      expect(workspace.attributes).to eq(id: 42, name: "Finance")
+      expect(workspace.options).to eq(api_key: "key-a")
+      expect(requests).to eq([ :patch ])
+    end
+  end
+
+  it "rejects JSON null as the created workspace, keeping the unsaved object and its options" do
+    client = stubbed_api_client do |stub|
+      stub.post("/api/rest/v1/workspaces") do
+        requests << :post
+        [ 201, { "Content-Type" => "application/json" }, "null" ]
+      end
+    end
+    workspace = Files::Workspace.new({ name: "Draft" }, api_key: "key-a")
+
+    expect { client.request { workspace.save } }.to raise_error(Files::APIConnectionError) { |error|
+      expect(error).to be_an_instance_of(Files::APIConnectionError)
+      expect(error.http_status).to eq(201)
+    }
+    expect(workspace.attributes).to eq(name: "Draft")
+    expect(workspace.options).to eq(api_key: "key-a")
+    expect(requests).to eq([ :post ])
+  end
+
+  it "rejects class-level responses of the wrong shape without changing options, and accepts empty ones" do
+    json = { "Content-Type" => "application/json" }
+    client = stubbed_api_client do |stub|
+      stub.get("/api/rest/v1/workspaces/42") { [ 200, json, "null" ] }
+      stub.patch("/api/rest/v1/workspaces/42") { [ 200, json, "null" ] }
+      stub.get("/api/rest/v1/file_actions/zip_list/null.zip") { [ 200, json, "null" ] }
+      stub.post("/api/rest/v1/file_actions/begin_upload/object.csv") { [ 200, json, { part_number: 1 }.to_json ] }
+      stub.post("/api/rest/v1/file_actions/begin_upload/null-part.csv") { [ 200, json, "[null]" ] }
+      stub.get("/api/rest/v1/workspaces/7") { json_response(200, {}) }
+      stub.get("/api/rest/v1/file_actions/zip_list/empty.zip") { json_response(200, []) }
+      stub.post("/api/rest/v1/file_actions/begin_upload/empty-part.csv") { json_response(200, [ {} ]) }
+    end
+    options = { api_key: "key-a" }
+
+    client.request do
+      expect { Files::Workspace.find(42, {}, options) }.to raise_error(Files::APIConnectionError, /a Workspace object/)
+      expect { Files::Workspace.update(42, { name: "Legal" }, options) }.to raise_error(Files::APIConnectionError, /a Workspace object/)
+      expect { Files::File.zip_list_contents("null.zip", {}, options) }.to raise_error(Files::APIConnectionError, /a list of ZipListEntry objects/)
+      expect { Files::File.begin_upload("object.csv", {}, options) }.to raise_error(Files::APIConnectionError, /a list of FileUploadPart objects/)
+      expect { Files::File.begin_upload("null-part.csv", {}, options) }.to raise_error(Files::APIConnectionError, /a list of FileUploadPart objects/)
+    end
+    expect(options).to eq(api_key: "key-a")
+
+    client.request do
+      expect(Files::Workspace.find(7, {}, options).attributes).to eq({})
+      expect(Files::File.zip_list_contents("empty.zip", {}, options)).to eq([])
+      expect(Files::File.begin_upload("empty-part.csv", {}, options).map { |part| [ part.class, part.attributes ] }).to eq([ [ Files::FileUploadPart, {} ] ])
+    end
+    expect(options).to include(api_key: "key-a", client: client)
+  end
+
+  it "refreshes each model from its own client, keeping false, zero, empty, null and decimal values" do
+    backend_client = stubbed_api_client do |stub|
+      stub.patch("/api/rest/v1/remote_mount_backends/7") do |env|
+        requests << [ :backend, env.request_headers["X-FilesAPI-Key"], env.request_headers["X-Files-Workspace-Id"] ]
+        json_response(200, { id: 7, enabled: false, fall: 0, status: "", canary_file_path: nil, min_free_cpu: "12.50" })
+      end
+    end
+    workspace_client = stubbed_api_client do |stub|
+      stub.patch("/api/rest/v1/workspaces/42") do |env|
+        requests << [ :workspace, env.request_headers["X-FilesAPI-Key"], env.request_headers["X-Files-Workspace-Id"] ]
+        json_response(200, canonical_workspace(env, 42))
+      end
+    end
+    backend = Files::RemoteMountBackend.new({ id: 7, enabled: true, fall: 3, status: "healthy", canary_file_path: "/health", min_free_cpu: "50" }, api_key: "key-b", workspace_id: 2, client: backend_client)
+    workspace = Files::Workspace.new({ id: 42, name: "Operations" }, api_key: "key-a", workspace_id: 1, client: workspace_client)
+
+    backend.enabled = false
+    expect(backend.save).to be(true)
+    workspace.update(name: "legal")
+
+    expect([ backend.enabled, backend.fall, backend.status, backend.canary_file_path ]).to eq([ false, 0, "", nil ])
+    expect(backend.min_free_cpu).to eq(BigDecimal("12.5"))
+    expect(backend.options).to include(api_key: "key-b", workspace_id: 2, client: backend_client)
+    expect(workspace.name).to eq("Legal")
+    expect(workspace.options).to include(api_key: "key-a", workspace_id: 1, client: workspace_client)
+    expect(requests).to eq([ [ :backend, "key-b", "2" ], [ :workspace, "key-a", "1" ] ])
+  end
+
+  it "saves a model that can only be updated with one PATCH to its path" do
+    client = stubbed_api_client do |stub|
+      stub.patch("/api/rest/v1/styles/team/reports") do
+        requests << :patch
+        json_response(200, { id: 5, path: "team/reports", logo_click_href: "https://example.test/" })
+      end
+    end
+    style = Files::Style.new({ path: "team/reports", logo_click_href: "https://example.test" }, api_key: "key-a", client: client)
+
+    expect(style.save).to be(true)
+    expect(style.attributes).to eq(id: 5, path: "team/reports", logo_click_href: "https://example.test/")
+    expect(requests).to eq([ :patch ])
+  end
+end

data/spec/spec_helper.rb

@@ -1,5 +1,102 @@
 require "files.com"
+require "json"
+require "net/http"
 require "pathname"
+require "securerandom"
+
+# Examples tagged :with_test_folder send the generated SDK's real HTTP requests to the Files.com mock
+# server's simulator, never to Files.com. FILES_MOCK_SERVER_HOST and FILES_MOCK_SERVER_PORT name its
+# loopback address, and FILES_MOCK_SCHEMA_SHA256 the schema its readiness report must name (the
+# schema_sha256 in its lib/simulation/generation.json). When one is missing, or the server there is not
+# that simulator, the example fails before the SDK sends anything.
+module MockServerFixture
+  LOOPBACK_HOSTS = %w[127.0.0.1 ::1 localhost].freeze
+  READY_TIMEOUT = 30
+  # Not a real API key: the simulator accepts any key and journals it only by number.
+  API_KEY = "synthetic-mock-server-api-key".freeze
+  PARENT = Pathname.new("files_regional_worker")
+
+  def self.origin
+    values = %w[FILES_MOCK_SERVER_HOST FILES_MOCK_SERVER_PORT FILES_MOCK_SCHEMA_SHA256].to_h { |name| [ name, ENV[name].to_s.strip ] }
+    missing = values.select { |_, value| value.empty? }.keys
+    raise "Set #{missing.join(", ")} for the Files.com mock server's simulator; these examples never use Files.com." if missing.any?
+
+    host, port, schema = values.values
+    raise "FILES_MOCK_SERVER_HOST must be a loopback address (#{LOOPBACK_HOSTS.join(", ")}), not #{host.inspect}." unless LOOPBACK_HOSTS.include?(host)
+    raise "FILES_MOCK_SERVER_PORT must be a port number, not #{port.inspect}." unless port.match?(/\A\d{1,5}\z/) && port.to_i.between?(1, 65_535)
+
+    origin = "http://#{host == "::1" ? "[::1]" : host}:#{port}"
+    expected = { "status" => "ready", "mode" => "simulation", "contract_version" => 3, "schema_sha256" => schema }
+    reported = ready(origin).slice(*expected.keys)
+    raise "#{origin} is not the expected simulator: it reports #{reported}, not #{expected}." unless reported == expected
+
+    origin
+  end
+
+  # Waits up to READY_TIMEOUT for something to listen at origin. Whatever answers first decides: a
+  # legacy mock server or any other server has no readiness report.
+  def self.ready(origin)
+    deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + READY_TIMEOUT
+    begin
+      response = control(origin, "ready")
+    rescue SystemCallError, Net::OpenTimeout
+      raise "Nothing answered at #{origin} within #{READY_TIMEOUT} seconds." if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+
+      sleep 0.2
+      retry
+    end
+    raise "#{origin} answered #{response.code} for its readiness report, so it is not the simulator." unless response.code == "200"
+
+    JSON.parse(response.body)
+  rescue JSON::ParserError
+    raise "#{origin} answered its readiness report with something other than JSON, so it is not the simulator."
+  end
+
+  def self.control(origin, name)
+    uri = URI("#{origin}/__files_mock/v1/#{name}")
+    Net::HTTP.start(uri.hostname, uri.port, open_timeout: 5, read_timeout: 10) { |http| http.get(uri.request_uri) }
+  end
+
+  def self.journal(origin)
+    journal = JSON.parse(control(origin, "journal").body)
+    raise "The simulator's journal is incomplete, so it cannot show which requests the SDK sent." unless journal["complete"] == true
+
+    journal.fetch("entries")
+  end
+
+  # The API requests the example sent: each carried the same synthetic API key (the journal numbers keys
+  # and never records them), no session, and the Ruby SDK's User-Agent. Transfers to the upload and
+  # download URLs the simulator issued carry no credential, as presigned URLs do not.
+  def self.check_requests(origin, after)
+    entries = journal(origin).select { |entry| entry.fetch("seq") > after && entry.fetch("path").start_with?("/api/rest/v1/") }
+    raise "No API request reached the simulator." if entries.empty?
+
+    keys = entries.map { |entry| entry.dig("credentials", "api_key") }.uniq
+    raise "The SDK's requests carried API keys #{keys.inspect}, not one key on every request." unless keys.size == 1 && keys.first.is_a?(Integer)
+    raise "An SDK request carried a session." if entries.any? { |entry| entry.dig("credentials", "session") }
+
+    agents = entries.map { |entry| entry["user_agent"] }.uniq
+    raise "Requests came with User-Agents #{agents.inspect}, not only the Ruby SDK's." unless agents.all? { |agent| agent.to_s.start_with?("Files.com Ruby SDK v") }
+  end
+
+  # Deletes the example's folder with everything in it, then the sibling made beside it, checking after
+  # each delete that only that folder went: the parent stays, and the sibling, whose name begins with the
+  # example folder's, stays until its own delete.
+  def self.remove(created, test_folder, sibling, options)
+    if created.include?(test_folder)
+      Files::Folder.delete(test_folder.to_s, { recursive: true }, options)
+      left = [ test_folder, test_folder.join("nested") ].select { |folder| Files::Folder.exist?(folder.to_s, options) }
+      raise "Deleting #{test_folder} left #{left.join(", ")}." if left.any?
+    end
+    lost = [ PARENT, (sibling if created.include?(sibling)) ].compact.reject { |folder| Files::Folder.exist?(folder.to_s, options) }
+    raise "Deleting #{test_folder} also removed #{lost.join(", ")}." if lost.any?
+    return unless created.include?(sibling)
+
+    Files::Folder.delete(sibling.to_s, {}, options)
+    raise "Deleting #{sibling} left it." if Files::Folder.exist?(sibling.to_s, options)
+    raise "Deleting #{sibling} also removed #{PARENT}." unless Files::Folder.exist?(PARENT.to_s, options)
+  end
+end
 
 RSpec.configure do |config|
   config.expect_with :rspec do |expectations|
@@ -19,14 +116,33 @@ RSpec.configure do |config|
   config.include_context "API Helpers", :with_test_folder
 
   config.around(:example, :with_test_folder) do |all|
-    @api_key = ENV["TEST_API_KEY"] || File.read("../../config/test_api_key.txt")
-    @test_folder = Pathname.new("files_regional_worker/#{SecureRandom.uuid}")
-    Files::Folder.exist?("files_regional_worker", api_key: @api_key)
-    Files::Folder.mkdir("files_regional_worker", {}, api_key: @api_key) unless Files::Folder.exist?("files_regional_worker", api_key: @api_key)
-    Files::Folder.mkdir(@test_folder.to_s, {}, api_key: @api_key)
+    base_url = Files.base_url
+    language = Files.language
+    origin = MockServerFixture.origin
+    Files.base_url = origin
+    after = MockServerFixture.journal(origin).map { |entry| entry.fetch("seq") }.max || 0
+    @api_key = MockServerFixture::API_KEY
+    @test_folder = MockServerFixture::PARENT.join(SecureRandom.uuid)
+    sibling = MockServerFixture::PARENT.join("#{@test_folder.basename}-sibling")
+    created = []
+    Files::Folder.mkdir(MockServerFixture::PARENT.to_s, {}, api_key: @api_key) unless Files::Folder.exist?(MockServerFixture::PARENT.to_s, api_key: @api_key)
+    [ sibling, @test_folder, @test_folder.join("nested") ].each do |folder|
+      Files::Folder.mkdir(folder.to_s, {}, api_key: @api_key)
+      created << folder
+    end
     all.run
   ensure
-    Files::Folder.delete(@test_folder.to_s, { recursive: true }, api_key: @api_key)
+    begin
+      if created&.any?
+        MockServerFixture.remove(created, @test_folder, sibling, { api_key: @api_key })
+        MockServerFixture.check_requests(origin, after)
+      end
+    ensure
+      Files.base_url = base_url
+      left_language = Files.language
+      Files.language = language
+    end
+    raise "The example left Files.language set to #{left_language.inspect}." unless left_language == language
   end
 
   config.shared_context_metadata_behavior = :apply_to_host_groups

data/spec/support/stubbed_api.rb

@@ -0,0 +1,14 @@
+# Specs that include this call the Files.com API through the SDK's own
+# connection, with only the network replaced by Faraday test stubs, so requests,
+# responses and errors take the real SDK path.
+module StubbedApi
+  def stubbed_api_client(&routes)
+    connection = Files::ApiClient.build_default_conn
+    connection.adapter :test, Faraday::Adapter::Test::Stubs.new(&routes)
+    Files::ApiClient.new(connection)
+  end
+
+  def json_response(status, body, headers = {})
+    [ status, { "Content-Type" => "application/json" }.merge(headers), body.to_json ]
+  end
+end