transloadit 3.1.2 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5b731d1993f71f5eed4e04c06a57bb5e74aa1df9b91bf0af31fee5957da71f1
-  data.tar.gz: b191d41e32ec32d1c08824897c394a3ecd567a871338814315c9e66a6ad3157a
+  metadata.gz: fc246e913322624e733835f51e2924112ec4131af0930694ae322da3a10ea9e7
+  data.tar.gz: 79bd642651fd5d6b3c0f3153bfb9d44c6f78b16a7b91171d094e227b430f8949
 SHA512:
-  metadata.gz: bf2ba9d4356a6872af095bc41ce0162901de894aaa018a2a144d3109c4c718ee4328b748536515a80f18c85d1a9d3ca7f650ca7f9d8031c011fac3efde7def20
-  data.tar.gz: 8c984d38f260faf2690b00527fb1afc897cd515140ab2e8639de1b3bc45581e566c7f6c8cc7dddb04210fe344b4a939373d0f351932343f249cbf57ed2479785
+  metadata.gz: 6ab26e103e6653f9b4126aed543446c6080e6bd30f1348cecefa38bb8406c706ec289e61e9c36c27512535f8590908ca15473cb042bf6ea38ebacac3eb7cd0a8
+  data.tar.gz: ef78d102680364717e5d4a4193a15cd553a7296478da13134c0cefa65fcc96138acca340990c7173b04e34fa741825788527d5d067e53eab057656acbf20bf1d

data/.gitattributes

@@ -1,5 +1,44 @@
-*.jpg binary
-*.jpeg binary
-*.png binary
-*.mp3 binary
-*.flac binary
+/.yarn/**            linguist-vendored
+/.yarn/releases/*    binary
+/.yarn/plugins/**/*  binary
+/.pnp.*              binary linguist-generated
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.aac filter=lfs diff=lfs merge=lfs -text
+*.ai filter=lfs diff=lfs merge=lfs -text
+*.avi filter=lfs diff=lfs merge=lfs -text
+*.bmp filter=lfs diff=lfs merge=lfs -text
+*.br filter=lfs diff=lfs merge=lfs -text
+*.cr2 filter=lfs diff=lfs merge=lfs -text
+*.dll filter=lfs diff=lfs merge=lfs -text
+*.doc filter=lfs diff=lfs merge=lfs -text
+*.docx filter=lfs diff=lfs merge=lfs -text
+*.exe filter=lfs diff=lfs merge=lfs -text
+*.flac filter=lfs diff=lfs merge=lfs -text
+*.gif filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.ico filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.JPG filter=lfs diff=lfs merge=lfs -text
+*.m4a filter=lfs diff=lfs merge=lfs -text
+*.m4v filter=lfs diff=lfs merge=lfs -text
+*.mkv filter=lfs diff=lfs merge=lfs -text
+*.mov filter=lfs diff=lfs merge=lfs -text
+*.mp3 filter=lfs diff=lfs merge=lfs -text
+*.mp4 filter=lfs diff=lfs merge=lfs -text
+*.ogg filter=lfs diff=lfs merge=lfs -text
+*.pages filter=lfs diff=lfs merge=lfs -text
+*.pdf filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.PNG filter=lfs diff=lfs merge=lfs -text
+*.psd filter=lfs diff=lfs merge=lfs -text
+*.pxm filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.tif filter=lfs diff=lfs merge=lfs -text
+*.tiff filter=lfs diff=lfs merge=lfs -text
+*.webm filter=lfs diff=lfs merge=lfs -text
+*.webp filter=lfs diff=lfs merge=lfs -text
+*.woff2 filter=lfs diff=lfs merge=lfs -text
+*.xlsx filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text

data/.github/workflows/ci.yml

@@ -13,32 +13,33 @@ jobs:
     strategy:
       matrix:
         ruby:
-          - 3.0
-          - 3.1
-          - 3.2
-          - 3.3
-          - jruby
-          - truffleruby
+          - "3.1"
+          - "3.2"
+          - "3.3"
+          - "3.4"
+          - "4.0"
       fail-fast: false
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+        with:
+          lfs: true
       - uses: actions/setup-node@v4
         with:
           node-version: 20
       - run: npm install -g tsx
-      - uses: ruby/setup-ruby@v1
+      - uses: ruby/setup-ruby@afeafc3d1ab54a631816aba4c914a0081c12ff2f
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
       - run: bundle exec standardrb
       - name: Run tests
         env:
-          COVERAGE: ${{ matrix.ruby == '3.3' && '1' || '0' }}
-          TEST_NODE_PARITY: ${{ matrix.ruby == '3.3' && '1' || '0' }}
+          COVERAGE: ${{ matrix.ruby == '4.0' && '1' || '0' }}
+          TEST_NODE_PARITY: ${{ matrix.ruby == '4.0' && '1' || '0' }}
         run: bundle exec rake test
       - name: Upload coverage to Codecov
-        if: matrix.ruby == '3.3'
-        uses: codecov/codecov-action@v5
+        if: matrix.ruby == '4.0'
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: ./coverage/coverage.json
@@ -53,10 +54,12 @@ jobs:
       TRANSLOADIT_KEY: ${{ secrets.TRANSLOADIT_KEY }}
       TRANSLOADIT_SECRET: ${{ secrets.TRANSLOADIT_SECRET }}
     steps:
-      - uses: actions/checkout@v3
-      - uses: ruby/setup-ruby@v1
+      - uses: actions/checkout@v4
+        with:
+          lfs: true
+      - uses: ruby/setup-ruby@afeafc3d1ab54a631816aba4c914a0081c12ff2f
         with:
-          ruby-version: 3.3
+          ruby-version: "4.0"
           bundler-cache: true
       - name: Ensure e2e credentials are configured
         if: ${{ env.TRANSLOADIT_KEY == '' || env.TRANSLOADIT_SECRET == '' }}

data/.gitignore

@@ -16,4 +16,4 @@ env.sh
 .env
 vendor/bundle/
 .docker-cache/
-.cache/rubocop_cache/04e06e0faf5ad652d8bcbcfd85bac5f6c32e711e/3031a80880d8a984708138f0d003f77c4bad2648
+.cache/

data/.standard.yml

@@ -0,0 +1,2 @@
+ignore:
+  - ".docker-cache/**/*"

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+### 4.0.0 / 2026-09-03
+
+- BREAKING: Replace the long-dormant `rest-client` transport with Faraday 2 and `faraday-multipart`.
+- BREAKING: Raise the minimum supported Ruby version from 3.0 to 3.1.
+- Keep HTTP client types out of SDK responses and exceptions while preserving response status, headers, body access, multipart ordering, and rate-limit retries.
+- Add a [v3 to v4 migration guide](MIGRATING_TO_V4.md).
+- Test all Ruby versions from the supported minimum through Ruby 4.0.
+
 ### 3.1.2 / 2025-10-29
 
 - Compress e2e fixture asset to keep gem size close to previous releases (kvz)

data/Dockerfile

@@ -1,6 +1,6 @@
 # syntax=docker/dockerfile:1
 
-FROM ruby:3.3 AS base
+FROM ruby:4.0 AS base
 
 RUN apt-get update \
     && apt-get install -y --no-install-recommends \

data/MIGRATING_TO_V4.md

@@ -0,0 +1,136 @@
+# Migrating from v3 to v4
+
+Version 4 replaces the `rest-client` HTTP transport with Faraday 2. Most applications only use the
+Transloadit API exposed by this gem and do not need code changes. The migration is a major release
+because v3 also delegated undocumented methods to RestClient response objects and exposed
+RestClient exception inheritance.
+
+Version 4 requires Ruby 3.1 or newer. The final v3 release allowed Ruby 3.0, so applications still
+running Ruby 3.0 must upgrade Ruby before updating this gem.
+
+## Update the dependency
+
+Once v4 is released, update the application Gemfile and bundle:
+
+```ruby
+gem "transloadit", "~> 4.0"
+```
+
+```shell
+bundle update transloadit
+```
+
+The SDK installs Faraday and its multipart middleware. Applications do not need to add Faraday
+directly. Remove an explicit `rest-client` dependency only if the application does not use it for
+anything else. Version 4 no longer installs or loads the `RestClient` constant on the application's
+behalf.
+
+## Responses
+
+Use the SDK-owned response API:
+
+```ruby
+response = transloadit.assembly.get(assembly_id)
+
+response["ok"]
+response[:assembly_id]
+response.body
+response.headers
+response.code
+response.status
+```
+
+`code` continues to return the integer HTTP status, and `status` is its new explicit alias. Header
+names remain normalized to lowercase symbols with underscores, for example
+`response.headers[:retry_after]`.
+
+HTTP error statuses still return `Transloadit::Response` objects. They are not converted into
+transport exceptions:
+
+```ruby
+response = transloadit.assembly.get(assembly_id)
+
+if response.code >= 400
+  warn response["error"]
+end
+```
+
+### Remove raw RestClient response usage
+
+In v3, `Transloadit::Response` delegated unknown methods to a `RestClient::Response`. Version 4 no
+longer exposes the underlying HTTP client. Replace calls to RestClient-specific response methods
+with the SDK-owned response API above.
+
+For example:
+
+```ruby
+# v3: relied on the delegated RestClient object
+response.raw_headers
+
+# v4
+response.headers
+```
+
+If an application relies on another delegated method that has no equivalent, open an issue with the
+use case before upgrading.
+
+## Request failures
+
+Network, TLS, and timeout failures now raise `Transloadit::Exception::RequestFailed` instead of a
+RestClient exception:
+
+```ruby
+# v3
+begin
+  transloadit.assembly.get(assembly_id)
+rescue RestClient::Exception => error
+  warn error.message
+end
+
+# v4
+begin
+  transloadit.assembly.get(assembly_id)
+rescue Transloadit::Exception::RequestFailed => error
+  warn error.message
+end
+```
+
+The original adapter exception is retained as `error.cause` for diagnostics. Avoid branching on its
+class so application behavior does not become coupled to Faraday.
+
+## Rate-limit failures
+
+Continue rescuing the SDK exception directly:
+
+```ruby
+begin
+  assembly.create!(file)
+rescue Transloadit::Exception::RateLimitReached => error
+  retry_after = error.response.wait_time
+end
+```
+
+`RateLimitReached` remains a `StandardError` and retains its Transloadit response through
+`error.response`, but it no longer inherits from `RestClient::RequestEntityTooLarge`. Replace code
+that rescues the RestClient superclass with the SDK exception.
+
+## Uploaded file handles
+
+Version 4 does not close path-backed file objects supplied by the caller. Prefer a block so ownership
+is explicit:
+
+```ruby
+File.open("video.mp4", "rb") do |file|
+  assembly.create!(file)
+end
+```
+
+Multipart field order is unchanged: `params` and `signature` are sent before file bodies.
+
+## Upgrade checklist
+
+- Update the gem and run the application's request and upload tests.
+- Replace rescues of `RestClient::Exception` and `RestClient::RequestEntityTooLarge`.
+- Replace calls to delegated RestClient response methods.
+- Confirm the application closes files that it opens.
+- Remove the direct `rest-client` dependency if nothing else uses it.

data/README.md

@@ -19,6 +19,9 @@ _If you run Ruby on Rails and are looking to integrate with the browser for file
 gem install transloadit
 ```
 
+Upgrading from v3? See the [v4 migration guide](MIGRATING_TO_V4.md) for response, exception, and
+file-handle compatibility notes.
+
 ## Usage
 
 To get started, you need to require the 'transloadit' gem:

data/lib/transloadit/assembly.rb

@@ -143,11 +143,22 @@ class Transloadit::Assembly < Transloadit::ApiModel
     when nil then steps
     when Hash then steps
     when Transloadit::Step then steps.to_hash
-    else
-      if steps.uniq(&:name) != steps
+    when Array
+      names = steps.inject([]) do |array, step|
+        case step
+        when Transloadit::Step then array << step.name
+        when Hash then array + step.keys.map(&:to_s)
+        else
+          raise ArgumentError, "Unsupported array element"
+        end
+      end
+
+      if names.uniq != names
         raise ArgumentError, "There are different Assembly steps using the same name"
       end
       steps.inject({}) { |h, s| h.update s }
+    else
+      raise ArgumentError, "Unsupported steps class"
     end
   end
 
@@ -162,8 +173,6 @@ class Transloadit::Assembly < Transloadit::ApiModel
     if is_retrying
       warn "Rate limit reached. Waiting for #{response.wait_time} seconds before retrying."
       sleep response.wait_time
-      # RestClient closes file streams at the end of a request.
-      ios.collect! { |file| File.open file.path }
     else
       raise Transloadit::Exception::RateLimitReached.new(response)
     end

data/lib/transloadit/exception.rb

@@ -1,16 +1,24 @@
 require "transloadit"
 
-require "rest-client"
-
 module Transloadit::Exception
+  #
+  # Exception raised when an HTTP request cannot be completed.
+  # The original transport error is available through +cause+.
+  #
+  class RequestFailed < StandardError
+  end
+
   #
   # Exception raised when Rate limit error response is returned from the API.
   # See {Rate Limiting}[https://transloadit.com/docs/api-docs/#rate-limiting]
   #
-  class RateLimitReached < RestClient::RequestEntityTooLarge
-    def default_message
-      retry_msg = " Retry in #{@response.wait_time} seconds" if @response
-      "Transloadit Rate Limit Reached.#{retry_msg}"
+  class RateLimitReached < StandardError
+    # @return [Transloadit::Response] the API response that reported the rate limit
+    attr_reader :response
+
+    def initialize(response)
+      @response = response
+      super("Transloadit Rate Limit Reached. Retry in #{response.wait_time} seconds")
     end
   end
 

data/lib/transloadit/request.rb

@@ -1,6 +1,8 @@
 require "transloadit"
 
-require "rest-client"
+require "faraday"
+require "faraday/multipart"
+require "mime/types"
 require "openssl"
 
 #
@@ -47,7 +49,7 @@ class Transloadit::Request
   #
   def get(params = {})
     request! do
-      api[url.path + to_query(params)].get(API_HEADERS)
+      api.get(url.path + to_query(params), nil, API_HEADERS)
     end
   end
 
@@ -60,8 +62,10 @@ class Transloadit::Request
   #
   def delete(payload = {})
     request! do
-      options = {payload: to_payload(payload)}
-      api(options)[url.path].delete(API_HEADERS)
+      api.delete(url.path) do |request|
+        request.headers.update(API_HEADERS)
+        request.body = to_payload(payload)
+      end
     end
   end
 
@@ -74,7 +78,7 @@ class Transloadit::Request
   #
   def post(payload = {})
     request! do
-      api[url.path].post(to_payload(payload), API_HEADERS)
+      api.post(url.path, to_payload(payload), API_HEADERS)
     end
   end
 
@@ -87,7 +91,7 @@ class Transloadit::Request
   #
   def put(payload = {})
     request! do
-      api[url.path].put(to_payload(payload), API_HEADERS)
+      api.put(url.path, to_payload(payload), API_HEADERS)
     end
   end
 
@@ -118,12 +122,20 @@ class Transloadit::Request
   # hostname, then the hostname is used as the base endpoint of the API.
   # Otherwise uses the class-level API base.
   #
-  # @return [RestClient::Resource] the API endpoint for this instance
+  # @return [Faraday::Connection] the API endpoint for this instance
   #
-  def api(options = {})
+  def api
     @api ||= case url.host
-    when String then RestClient::Resource.new("#{url.scheme}://#{url.host}", options)
-    else RestClient::Resource.new("#{API_ENDPOINT.scheme}://#{API_ENDPOINT.host}", options)
+    when String then connection_for("#{url.scheme}://#{url.host}")
+    else connection_for("#{API_ENDPOINT.scheme}://#{API_ENDPOINT.host}")
+    end
+  end
+
+  def connection_for(base_url)
+    Faraday.new(url: base_url) do |connection|
+      connection.request :multipart
+      connection.request :url_encoded
+      connection.adapter Faraday.default_adapter
     end
   end
 
@@ -151,12 +163,33 @@ class Transloadit::Request
     sig = signature(new_payload[:params])
     new_payload[:signature] = sig unless sig.nil?
 
-    # Copy all values, excluding :params and :signature keys.
-    new_payload.update payload.reject { |key, _| key == :params || key == :signature }
+    payload.each do |key, value|
+      next if key == :params || key == :signature
+
+      new_payload[key] = upload?(value) ? multipart_file(value) : value
+    end
 
     new_payload
   end
 
+  def upload?(value)
+    value.respond_to?(:read)
+  end
+
+  def multipart_file(file)
+    path = file.path if file.respond_to?(:path)
+    filename = file.original_filename if file.respond_to?(:original_filename)
+    filename = File.basename(path) if filename.to_s.empty? && path
+    filename = "upload" if filename.to_s.empty?
+
+    content_type = file.content_type if file.respond_to?(:content_type)
+    content_type = MIME::Types.type_for(path).first&.content_type if content_type.to_s.empty? && path
+    content_type = "application/octet-stream" if content_type.to_s.empty?
+
+    source = path || file
+    Faraday::Multipart::FilePart.new(source, content_type, filename)
+  end
+
   #
   # Updates the GET/DELETE params hash to be compliant with the Transloadit
   # API by URI escaping and encoding the params hash, and attaching a
@@ -181,18 +214,17 @@ class Transloadit::Request
   end
 
   #
-  # Wraps a request's results in a Transloadit::Response, even if an exception
-  # is raised by RestClient.
+  # Wraps a request's result in a Transloadit::Response.
   #
   def request!(&request)
-    Transloadit::Response.new yield
-  rescue RestClient::Exception => e
-    # The response attribute can be nil, for example for RestClient::Exceptions::OpenTimeout exceptions.
-    # Then, we cannot convert them into a Transloadit::Response, so instead we raise them again for
-    # the user to be visible.
-    # See https://github.com/transloadit/ruby-sdk/issues/53
-    raise e if e.response.nil?
-    Transloadit::Response.new e.response
+    response = yield
+    Transloadit::Response.new(
+      body: response.body,
+      headers: response.headers,
+      status: response.status
+    )
+  rescue Faraday::Error
+    raise Transloadit::Exception::RequestFailed, "Transloadit request failed"
   end
 
   #

data/lib/transloadit/response.rb

@@ -1,20 +1,30 @@
 require "transloadit"
 
-require "rest-client"
-require "delegate"
-
-class Transloadit::Response < Delegator
+class Transloadit::Response
   autoload :Assembly, "transloadit/response/assembly"
 
   #
-  # Creates an enhanced response wrapped around a RestClient response.
+  # Creates a response without exposing the underlying HTTP client.
   #
-  # @param [RestClient::Response] response the JSON response to wrap
+  # @param [String] body the raw response body
+  # @param [Hash] headers the response headers
+  # @param [Integer] status the HTTP response status
   #
-  def initialize(response)
-    __setobj__(response)
+  def initialize(body:, headers:, status:)
+    @raw_body = body
+    @headers = normalize_headers(headers)
+    @status = status
   end
 
+  # @return [Hash] normalized response headers
+  attr_reader :headers
+
+  # @return [Integer] the HTTP response status
+  attr_reader :status
+
+  # RestClient exposed the status through +code+ in previous SDK versions.
+  alias_method :code, :status
+
   #
   # Returns the attribute from the JSON response.
   #
@@ -31,7 +41,7 @@ class Transloadit::Response < Delegator
   # @return [Hash] the parsed JSON body hash
   #
   def body
-    MultiJson.load __getobj__.body
+    MultiJson.load @raw_body
   end
 
   #
@@ -56,36 +66,28 @@ class Transloadit::Response < Delegator
     self
   end
 
-  protected
-
-  #
-  # The object to delegate method calls to.
-  #
-  # @return [RestClient::Response]
-  #
-  def __getobj__
-    @response
-  end
-
   #
-  # Sets the object to delegate method calls to.
+  # Replaces this response's HTTP data with another response's data.
   #
-  # @param  [RestClient::Response] response the response to delegate to
-  # @return [RestClient::Response]          the delegated response
-  #
-  def __setobj__(response)
-    @response = response
-  end
-
-  #
-  # Replaces the object this instance delegates to with the one the other
-  # object uses.
-  #
-  # @param  [Delegator] other       the object whose delegate to use
+  # @param  [Transloadit::Response] other the response whose data to use
   # @return [Transloadit::Response] this response
   #
   def replace(other)
-    __setobj__ other.__getobj__
+    @raw_body = other.raw_body
+    @headers = other.headers
+    @status = other.status
     self
   end
+
+  protected
+
+  attr_reader :raw_body
+
+  private
+
+  def normalize_headers(headers)
+    headers.to_h.each_with_object({}) do |(name, value), normalized|
+      normalized[name.to_s.downcase.tr("-", "_").to_sym] = value
+    end
+  end
 end

data/lib/transloadit/version.rb

@@ -1,3 +1,3 @@
 class Transloadit
-  VERSION = "3.1.2"
+  VERSION = "4.0.0"
 end

data/lib/transloadit.rb

@@ -2,7 +2,7 @@ require "multi_json"
 require "date"
 require "json"
 require "openssl"
-require "cgi"
+require "cgi/escape"
 require "uri"
 
 #

data/test/test_helper.rb

@@ -72,3 +72,29 @@ module TransloaditCliHelpers
 end
 
 Minitest::Test.include(TransloaditCliHelpers)
+
+module SingletonMethodOverrideHelpers
+  def with_singleton_method(target, name, implementation)
+    eigenclass = target.singleton_class
+
+    backup = "__orig_#{name}_for_test__"
+    had_method = eigenclass.method_defined?(name) || eigenclass.private_method_defined?(name)
+    eigenclass.send(:alias_method, backup, name) if had_method
+
+    target.define_singleton_method(name, &implementation)
+    yield
+  ensure
+    eigenclass = target.singleton_class
+    if eigenclass.method_defined?(name) || eigenclass.private_method_defined?(name)
+      eigenclass.send(:remove_method, name)
+    end
+    if had_method
+      eigenclass.send(:alias_method, name, backup)
+      if eigenclass.method_defined?(backup) || eigenclass.private_method_defined?(backup)
+        eigenclass.send(:remove_method, backup)
+      end
+    end
+  end
+end
+
+Minitest::Test.include(SingletonMethodOverrideHelpers)

data/test/unit/test_transloadit.rb

@@ -109,7 +109,7 @@ describe Transloadit do
 
     it "must produce Transloadit-compatible JSON output" do
       fixed_time = Time.utc(2025, 10, 28, 0, 0, 0)
-      Time.stub :now, fixed_time do
+      with_singleton_method(Time, :now, proc { fixed_time }) do
         _(@transloadit.to_json).must_equal MultiJson.dump(@transloadit.to_hash)
       end
     end