Replace rest-client with Faraday

[tim-kos]

Summary

• replace the dormant rest-client dependency with Faraday 2 and faraday-multipart
• preserve GET, POST, PUT, DELETE, multipart upload ordering, MIME detection, response status/header/body access, and rate-limit retries
• stop exposing HTTP-client response objects through Transloadit::Response
• add Transloadit::Exception::RequestFailed and retain the original transport failure as its cause
• keep RateLimitReached#response while making the exception SDK-owned
• add a focused transport-compatibility test matrix, including Rails-style uploaded files
• add and link a v3→v4 migration guide covering every intentional compatibility change
• document the migration as breaking for the next major release

Why

The latest rest-client gem release is from 2019, and prospective customers have identified it as a reason not to adopt the Ruby SDK. Faraday is actively maintained and is already familiar in the Rails ecosystem.

This change also establishes an SDK-owned transport boundary. A future HTTP-client migration will no longer require changing response or exception types.

Compatibility

The documented SDK response behavior remains available:

• response.body
• response.headers
• response.code
• response.status
• hash-style response access
• Assembly reload/cancel/status helpers
• multipart uploads and rate-limit retries

This should ship in a major release because consumers may currently rely on undocumented RestClient delegation or rescue RestClient exception classes directly. See the migration guide for concrete before/after examples and an upgrade checklist.

Test coverage

The compatibility suite explicitly covers:

• signed GET query serialization and machine-specific hosts
• signed, form-encoded POST, PUT, and DELETE bodies
• SDK-owned response bodies, normalized headers, and code/status on non-2xx responses
• redirect responses without unintended following
• ordered multipart fields, multiple files, MIME detection, and caller-owned file handles
• Rails-style original_filename and content_type
• adapter failures wrapped as RequestFailed with the original cause
• response replacement during reload/cancel
• rate-limit retries and exception response access
• isolated loading without defining RestClient
• the existing live end-to-end Assembly upload

Verification

• full test suite: 122 runs, 235 assertions, 0 failures, 0 errors
• coverage: 99.7% lines, 94.0% branches
• StandardRB on all changed Ruby files
• Ruby syntax checks on all changed Ruby files and the gemspec
• gem build, including the migration guide in the packaged gem
• GitHub CI on Ruby 3.1, 3.2, and 3.3
• live end-to-end upload job

[codecov-commenter]

Codecov Report

❌ Patch coverage is 93.22034% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 98.21%. Comparing base (86fb0f9) to head (1ccb45e).

Files with missing lines	Patch %	Lines
lib/transloadit/request.rb	88.57%	0 Missing and 4 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #77      +/-   ##
==========================================
- Coverage   99.02%   98.21%   -0.82%     
==========================================
  Files           9        9              
  Lines         308      336      +28     
  Branches       44       38       -6     
==========================================
+ Hits          305      330      +25     
+ Misses          3        1       -2     
- Partials        0        5       +5     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.