transloadit 3.1.2 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5b731d1993f71f5eed4e04c06a57bb5e74aa1df9b91bf0af31fee5957da71f1
-  data.tar.gz: b191d41e32ec32d1c08824897c394a3ecd567a871338814315c9e66a6ad3157a
+  metadata.gz: 2c1220e478a424b85d5ac449fd7facf3790af3091a69435699a49480853b86fe
+  data.tar.gz: 544d23e833e4ee095744d91f948ca7bfc7616bb70e5d576042d44b3032510307
 SHA512:
-  metadata.gz: bf2ba9d4356a6872af095bc41ce0162901de894aaa018a2a144d3109c4c718ee4328b748536515a80f18c85d1a9d3ca7f650ca7f9d8031c011fac3efde7def20
-  data.tar.gz: 8c984d38f260faf2690b00527fb1afc897cd515140ab2e8639de1b3bc45581e566c7f6c8cc7dddb04210fe344b4a939373d0f351932343f249cbf57ed2479785
+  metadata.gz: 69178ed10b8fc21cd0c342e32aeecad79d886721e2c08b7df69e85a3d965faacef50054973a5b6dca7c72b885166a5f371416c641685df6679481d2e310dd0c8
+  data.tar.gz: 4a2393daa75a76414b208891d63a2d2d0a88e2c50e22da4b634a33fe7696cb084348fb26b1e823c5b45ca6feda168b12e8450a7dfa290a40d7e7bd29ea082d19

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,20 @@
+### Unreleased
+
+### 4.1.0 / 2026-10-18
+
+- Add `uploads: {name => io}` to Assembly options and `create!` for named multipart uploads, separate from signed JSON Instructions.
+- Send custom `fields` only in signed JSON, preserving numbers, booleans, arrays, objects, and null without duplicate form fields.
+- Keep IOs in legacy `fields` working as named uploads throughout v4, omit them from JSON, and warn to migrate to `uploads` before the next major release. Positional `file_N` uploads and `create!(fields: metadata)` overrides remain supported.
+- Restore in-memory uploads to their original position on rate-limit retries and raise a clear `IOError` when a non-seekable upload cannot be retried.
+
+### 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/Gemfile

@@ -5,4 +5,8 @@ gem "minitest"
 gem "simplecov"
 gem "simplecov-cobertura"
 
+# Ruby 3.1 resolves MultiJson 1.19, which cannot parse JSON 3 (ruby-sdk#89).
+# Keep its test bundle compatible without restricting consumers on newer Rubies.
+gem "json", "< 3.0" if RUBY_VERSION.start_with?("3.1.")
+
 gemspec

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:
@@ -168,6 +171,38 @@ files = [open('puppies.jpg'), open('kittens.jpg'), open('ferrets.jpg')]
 response = assembly.create! *files
 ```
 
+For names that match a Step's `use.fields` selector, pass `uploads: {name => io}`
+to `assembly` or `create!`. Uploads are multipart parts and are excluded from
+the signed JSON Instructions. Open files in binary mode and close them after
+the request; the SDK leaves caller-owned files open.
+
+```ruby
+File.open('puppies.jpg', 'rb') do |photo|
+  response = transloadit.assembly(
+    steps: {
+      resize: {
+        robot: '/image/resize',
+        use: {fields: ['photo']},
+        width: 320,
+        height: 240
+      }
+    },
+    uploads: {photo: photo},
+    fields: {count: 2, enabled: false, details: {caption: 'Puppies'}}
+  ).create!
+end
+```
+
+Alternatively, use `assembly.create!(uploads: {photo: photo}, fields: metadata)`.
+Per-call `uploads` and `fields` each replace the corresponding Assembly option;
+`uploads: {}` clears only the `uploads` option. Legacy IOs configured in `fields`
+remain uploads for compatibility. Positional files still use `file_0`,
+`file_1`, and so on, and take precedence over named uploads with those names.
+Upload values must respond to `read`; the names `params` and `signature` are reserved.
+For rate-limit retries, in-memory uploads must also support `pos` and `seek`;
+the SDK restores their original position. A non-seekable upload raises `IOError`
+if a retry is needed, instead of sending consumed bytes again.
+
 ### 3. Parallel Assembly
 
 Transloadit allows you to perform several processing steps in parallel. You
@@ -223,9 +258,10 @@ has some nice examples for that.
 
 ### 5. Using fields
 
-Transloadit allows you to submit form field values that you'll get back in the
-notification. This is quite handy if you want to add additional custom metadata
-to the upload itself. You can use fields like the following:
+Transloadit allows you to submit custom metadata that you'll get back in the
+notification. `fields` is included once in the signed JSON Instructions and is
+never duplicated as form fields. Numbers, booleans, arrays, objects, and null
+retain their JSON types. You can use fields like the following:
 
 ```ruby
 require 'transloadit'
@@ -243,6 +279,17 @@ transloadit.assembly(
 ).create! open('/PATH/TO/FILE.mpg')
 ```
 
+`create!(fields: metadata)` also sets custom fields and replaces any metadata
+configured on the Assembly. Uploads and metadata may use the same name.
+
+For compatibility, IO values passed directly in a `fields` hash still upload
+under their field names throughout v4, but emit a deprecation warning. They are
+excluded from JSON; other values in that hash remain custom metadata. Migrate
+from `assembly(fields: {photo: file, count: 2})` to
+`assembly(uploads: {photo: file}, fields: {count: 2})` before the next major release.
+Explicit `uploads` take precedence over legacy IOs with the same name. Existing
+`assembly(fields: {photo: file}).create!(fields: metadata)` calls continue working.
+
 ### 6. Notify URL
 
 If you want to be notified when the processing is finished you can provide
@@ -461,6 +508,11 @@ for the latest [git main](https://rubydoc.info/github/transloadit/ruby-sdk/main/
 Please see [ci.yml](https://github.com/transloadit/ruby-sdk/tree/main/.github/workflows/ci.yml) for a list of supported ruby versions. It may also work on older Rubies, but support for those is not guaranteed. If it doesn't work on one of the officially supported Rubies, please file a
 [bug report](https://github.com/transloadit/ruby-sdk/issues). Compatibility patches for other Rubies are welcome.
 
+On Ruby 3.1, add `gem "json", "< 3.0"` to your application's Gemfile while
+[the older MultiJson/JSON compatibility issue](https://github.com/transloadit/ruby-sdk/issues/89)
+is open. Ruby 3.2 and newer can use JSON 3 with
+[MultiJson 1.21.2 or newer](https://github.com/sferik/multi_json/releases/tag/v1.21.2).
+
 ### Ruby 2.x
 
 If you still need support for Ruby 2.x, 2.0.1 is the last version that supports it.

data/lib/transloadit/assembly.rb

@@ -44,25 +44,45 @@ class Transloadit::Assembly < Transloadit::ApiModel
   #   @option params [String] :template_id the ID of a
   #     {template}[https://transloadit.com/templates] to use instead of
   #     specifying params here directly
+  #   @option params [Hash] :fields custom metadata, retained as typed JSON
+  #   @option params [Hash<String, IO>] :uploads named multipart uploads;
+  #     overrides the Assembly's uploads when supplied (use {} to clear them)
   #
   def create!(*ios, **params)
     params[:steps] = _wrap_steps_in_hash(params[:steps]) unless params[:steps].nil?
 
+    legacy_uploads, = _split_fields(options[:fields])
+    if params.key?(:fields)
+      uploads, params[:fields] = _split_fields(params[:fields])
+      legacy_uploads.merge!(uploads)
+    end
+    unless legacy_uploads.empty?
+      warn "Passing upload IOs in fields is deprecated; use uploads: {name => io} instead."
+    end
+
     extra_params = {}
-    extra_params.merge!(options[:fields]) if options[:fields]
+    [legacy_uploads, params.delete(:uploads) { options[:uploads] }].compact.each do |uploads|
+      uploads.each do |name, io|
+        name = name.to_s
+        raise ArgumentError, "Upload name #{name.inspect} is reserved" if %w[params signature].include?(name)
+        raise ArgumentError, "Upload #{name.inspect} must be an IO responding to read" unless io.respond_to?(:read)
+
+        extra_params[name] = io
+      end
+    end
+    # Keep positional file_N uploads and their precedence for existing callers.
+    ios.each_with_index { |io, i| extra_params["file_#{i}"] = io }
+    upload_positions = _upload_positions(extra_params.values)
 
     trials = options[:tries] || DEFAULT_TRIES
     (1..trials).each do |trial|
-      # update the payload with file entries
-      ios.each_with_index { |f, i| extra_params.update "file_#{i}": f }
-
       response = _do_request(
         "/assemblies", params, "post", extra_params
       ).extend!(Transloadit::Response::Assembly)
 
       return response unless response.rate_limit?
 
-      _handle_rate_limit!(response, ios, trial < trials)
+      _handle_rate_limit!(response, upload_positions, trial < trials)
     end
   end
 
@@ -123,14 +143,37 @@ class Transloadit::Assembly < Transloadit::ApiModel
   # @return [Hash] a Transloadit-compatible Hash of the Assembly's contents
   #
   def to_hash
-    options.merge(
+    result = options.merge(
       auth: transloadit.to_hash,
       steps: steps
-    ).delete_if { |k, v| v.nil? }
+    )
+    result.delete(:uploads)
+    _, result[:fields] = _split_fields(result[:fields]) if result[:fields]
+    result.delete_if { |_, value| value.nil? }
   end
 
   private
 
+  # Legacy fields may contain both named IOs and metadata. Only metadata belongs
+  # in the signed JSON; the IOs remain supported as uploads throughout v4.
+  def _split_fields(fields)
+    return [{}, nil] if fields.nil?
+
+    fields.partition { |_, value| value.respond_to?(:read) }.map(&:to_h)
+  end
+
+  def _upload_positions(uploads)
+    uploads.filter_map do |io|
+      # The transport reopens path-backed uploads for each attempt.
+      next if io.respond_to?(:path) && io.path
+
+      position = io.pos if io.respond_to?(:pos) && io.respond_to?(:seek)
+      [io, position]
+    rescue IOError, SystemCallError
+      [io, nil]
+    end
+  end
+
   #
   # Returns a Transloadit-compatible Hash wrapping the +steps+ passed to it.
   # Accepts any supported format the +steps+ could come in.
@@ -143,27 +186,43 @@ 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
 
   #
-  # Stays idle for certain time and then reopens assembly files for reprocessing.
+  # Restores in-memory upload positions and waits before retrying.
   # Should be called when assembly rate limit is reached.
   #
   # @param  [Response] response  assembly response that comes with a rate limit
-  # @param [Array<IO>] ios the files sent for the assembly to process.
+  # @param [Array<Array>] upload_positions IOs and their positions before upload
   #
-  def _handle_rate_limit!(response, ios, is_retrying)
+  def _handle_rate_limit!(response, upload_positions, is_retrying)
     if is_retrying
+      upload_positions.each do |io, position|
+        raise IOError if position.nil?
+
+        io.seek(position)
+      rescue IOError, SystemCallError
+        raise IOError, "Cannot retry a non-seekable upload; use a file or an IO supporting pos and seek"
+      end
       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