uploadcare-ruby 4.4.3 → 5.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9bf27040e7e061caf3e4810f1e40ab9421f0a063eee05b2338a4b1e7255524bd
-  data.tar.gz: b41c835893fc836263ba7e354fce6427a9fbbaec26efbea485fac9874d162af1
+  metadata.gz: de585668a800a9c568b1c24ee4458a9347ca6d33b7ef89c395959682a0904b84
+  data.tar.gz: 866e8cbadbe47bae82d442d99a4dd5c4d5174fe7d18829b4d6a98658000975b0
 SHA512:
-  metadata.gz: 810bd3ad7369ddbb2f44a932d12699c5b969bec1feb33ade6805a31a61d18afc102043ba1e61b0b53c7996956c4b6c8496a8e807598436d7325ad33c3a3bf33e
-  data.tar.gz: ef9f05f9f586ba804de9e424ee9634abaebf8cff8a7d47be13147206fa2ff3e3adeac56f61f8ea54ccea77e36a523df100438647df01a92c0f1e0f42d5dff5b3
+  metadata.gz: 1f57d707ac7d812cf8a68c9328cc0ff29b81863d3f680a0be802f8c32423e9e369f78083edf035c195972abcff3a20fa2e6ea122b85f3de5a3cb496928b2831e
+  data.tar.gz: 0d0cca16356a961e43bfa8b04f21bbab6b166c0fdb57af4e392ba57a39ae2eb15236d3810d684e70d304562bb21c952ffba9e8a7256b277bfc449b431166a5a0

data/.env.example

@@ -0,0 +1,7 @@
+# Uploadcare API credentials
+# Copy this file to .env and fill in your actual keys (for local development only).
+# Never commit real credentials. See MIGRATING_V5.md for v5 client-first setup details.
+# Get your keys from: https://app.uploadcare.com/projects/-/api-keys/
+
+UPLOADCARE_PUBLIC_KEY=your_public_key_here
+UPLOADCARE_SECRET_KEY=your_secret_key_here

data/.github/workflows/gem-push.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v5
 
       - name: Release Gem
         if: contains(github.ref, 'refs/tags/v')

data/.github/workflows/ruby.yml

@@ -2,7 +2,7 @@
 # They are provided by a third-party and are governed by
 # separate terms of service, privacy policy, and support
 # documentation.
-# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# This workflow installs Ruby, runs tests, and runs style checks in a dedicated job.
 # For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
 
 name: Ruby
@@ -16,13 +16,12 @@ jobs:
     strategy:
       matrix:
         ruby-version:
-          - 3.0
-          - 3.1
-          - 3.2
           - 3.3
+          - 3.4
+          - 4.0
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v5
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
@@ -30,26 +29,24 @@ jobs:
         ruby-version: ${{ matrix.ruby-version }}
         bundler-cache: true
     - name: Run tests
-      run: bundle exec rake
+      # Keep test invocation on rake tasks so repository-local pre/post hooks stay centralized.
+      run: bundle exec rake spec
       env:
         UPLOADCARE_PUBLIC_KEY: demopublickey
-        UPLOADCARE_SECRET_KEY: demoprivatekey
+        UPLOADCARE_SECRET_KEY: demosecretkey
 
   style-check:
     runs-on: ubuntu-latest
-    continue-on-error: true
     strategy:
       matrix:
         ruby-version:
-          - 3.3
+          - 4.0
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v5
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{ matrix.ruby-version }}
         bundler-cache: true
-    - name: Install Rubocop
-      run: gem install rubocop
     - name: Check codestyle
-      run: rubocop
+      run: bundle exec rubocop

data/.gitignore

@@ -18,3 +18,12 @@ Gemfile.lock
 .ruby-version
 project_files
 *.gem
+.vscode/
+.DS_Store
+.claude/
+.kiro/
+.agents/
+
+# Environment variables (API keys)
+.env
+.env.local

data/.rubocop.yml

@@ -1,6 +1,18 @@
+plugins:
+  - rubocop-rake
+  - rubocop-rspec
+
 AllCops:
   NewCops: enable
-  TargetRubyVersion: 3.0
+  # RuboCop currently supports up to 3.5; CI still tests this gem on Ruby 4.0.
+  TargetRubyVersion: 3.4
+  SuggestExtensions: false
+  Exclude:
+    - 'examples/**/*'
+    - 'tmp/**/*'
+    - 'spec/support/**/*'
+    - 'api_examples/support/**/*'
+    - 'vendor/bundle/**/*'
 
 Layout/LineLength:
   Max: 120
@@ -10,31 +22,106 @@ Layout/LineLength:
 Lint/IneffectiveAccessModifier:
   Enabled: false
 
-Style/HashTransformKeys:
-  Exclude:
-    - 'lib/uploadcare/entity/decorator/paginator.rb'
-    - 'lib/uploadcare/client/conversion/video_conversion_client.rb'
-    - 'lib/uploadcare/entity/file.rb'
-
 Metrics/BlockLength:
+  Max: 30
   Exclude:
     - 'bin/'
     - 'spec/**/*'
     - 'uploadcare-ruby.gemspec'
+    - 'api_examples/support/**/*.rb'
+
+Metrics/ClassLength:
+  Max: 200
+  Exclude:
+    - 'spec/**/*'
 
 Metrics/ModuleLength:
+  Max: 100
   Exclude:
     - 'spec/**/*'
+    - 'api_examples/support/**/*.rb'
 
 Metrics/MethodLength:
-  Max: 20
+  Max: 30
+  Exclude:
+    - 'api_examples/support/**/*.rb'
+
+Metrics/AbcSize:
+  Max: 28
+  Exclude:
+    - 'api_examples/support/**/*.rb'
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+  Exclude:
+    - 'api_examples/support/**/*.rb'
+
+Metrics/PerceivedComplexity:
+  Max: 11
+  Exclude:
+    - 'api_examples/support/**/*.rb'
+
+Metrics/ParameterLists:
+  Max: 8
+  Exclude:
+    - 'spec/**/*'
 
 Style/Documentation:
   Enabled: false
 
+Style/ClassAndModuleChildren:
+  EnforcedStyle: compact
+
 Style/OptionalBooleanParameter:
   AllowedMethods: ['create']
 
 Style/FrozenStringLiteralComment:
   Exclude:
     - 'api_examples/**/*'
+
+Style/ArgumentsForwarding:
+  Enabled: false
+
+Gemspec/RequiredRubyVersion:
+  Enabled: false
+
+RSpec/ContextWording:
+  Prefixes:
+    - when
+    - with
+    - without
+    - if
+    - unless
+    - for
+
+# Kept intentionally for API-integration style specs where strict unit-style cops add noise.
+RSpec/AnyInstance:
+  Enabled: false
+
+RSpec/DescribedClass:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+RSpec/MultipleMemoizedHelpers:
+  Enabled: false
+
+RSpec/NestedGroups:
+  Enabled: false
+
+# Existing test suite uses classic doubles/spies heavily; keep these disabled until specs are migrated.
+RSpec/DescribeClass:
+  Enabled: false
+
+RSpec/MessageSpies:
+  Enabled: false
+
+RSpec/StubbedMock:
+  Enabled: false
+
+RSpec/VerifiedDoubles:
+  Enabled: false

data/CHANGELOG.md

@@ -1,12 +1,82 @@
 # Changelog
 
+## 5.0.0.rc1 — 2026-04-22
+
+This release candidate is the first public v5 cut from the rewritten codebase.
+
+Please review [`MIGRATING_V5.md`](./MIGRATING_V5.md) before upgrading from v4.x.
+
+### Added
+
+* New client-first public API centered on `Uploadcare::Client`
+* Full endpoint-parity access through `client.api.rest` and `client.api.upload`
+* Canonical endpoint examples for the REST API and Upload API under `api_examples/`
+* Updated workflow-oriented examples under `examples/`
+* Multi-account configuration support through client-scoped `Uploadcare::Configuration`
+* Documented internal API surface through YARD for maintainers and integrators
+* Ruby 4.0 support in the test matrix
+
+### Changed
+
+* Replaced the older flatter API shape with a layered API:
+  * convenience layer for application code
+  * raw parity layer for exact endpoint access
+* Replaced `dry-configurable` with a plain Ruby configuration object
+* Replaced legacy HTTP and autoloading patterns with Faraday and Zeitwerk
+* Standardized resource and collection return types across the convenience layer
+* Reworked README, migration docs, and examples to match the current v5 API
+
+### Fixed
+
+* Upload IO normalization for both path-backed files and generic readable streams
+* Client/config scoping so resources do not silently fall back to the wrong account context
+* Video conversion `store` parameter normalization
+* Document conversion boolean option normalization to match video conversion behavior
+* REST request signing so the resolved `Content-Type` is the same value used for both signing and transmission
+* REST query signing to use the same parameter encoding style as request transmission
+* Multipart upload retry semantics so `max_retries` means retries after the initial attempt
+* Multipart upload part retries/timeouts now honor configuration (`max_upload_retries`, `upload_timeout`)
+* Multipart upload worker cancellation after first parallel upload error to avoid unnecessary in-flight uploads
+* Multipart upload start payload no longer sends unsupported `part_size` to `/multipart/start/`
+* Upload-from-URL polling now supports exponential backoff with a configurable cap
+* Example cleanup to avoid leaking temporary files and groups in the demo project
+* Standalone example loading and script execution
+* File metadata resource initialization now correctly assigns instance UUID
+* Upload API batch uploads now avoid filename collisions without mutating caller-visible filenames
+* REST authenticator now uses deterministic protocol-required digests (`MD5` body digest and `SHA1` HMAC digest)
+* Upload API debug logger now avoids emitting request/response headers and bodies by default
+* Thread-safe lazy memoization for client/accessor/API endpoint objects and CNAME cache internals
+
+### Removed
+
+* Support for Ruby versions below `3.3`
+* Legacy configuration and transport patterns that were no longer aligned with the v5 architecture
+### Risk & Rollout Notes
+* Ruby support baseline is now `>= 3.3`; verify application/runtime images before upgrading.
+* Recommended rc1 rollout: wire explicit `Uploadcare::Client` instances first, then migrate call sites incrementally.
+* Keep rollback simple by pinning to the latest v4 release if your app depends on removed internal APIs.
+
+## 4.5.0 — 2025-07-25
+### Added
+* **CDN Subdomain Support**: Added support for automatic subdomain generation to improve CDN performance and caching.
+  * New `CnameGenerator` class for generating CNAME prefixes based on public key using SHA256 hashing
+  * Configuration options:
+    * `use_subdomains` - Enable automatic subdomain generation (default: `false`)
+    * `cdn_base_postfix` - Base domain for subdomain generation (default: `https://ucarecd.net/`)
+    * `default_cdn_base` - Original CDN base URL (default: `https://ucarecdn.com/`)
+    * `cdn_base` - Dynamic CDN base selection based on subdomain configuration
+  * New `cdn_url` method for `File` and `Group` entities to get CDN URLs using configured base
+  * New `file_cdn_urls` method for `Group` entities to get CDN URLs of all files in a group without API requests
+* New `Uploadcare::Exception::ConfigurationError` for configuration-related errors
+* Ruby 3.4 support added to test matrix
+
 ## 4.4.3 — 2024-07-06
 
 ### Added
 * Multi page conversion parameter (`save_in_group`) added to `DocumentConverter#convert` options.
 
 ### Fixed
-* Fixed that signed URLs now work with ~ in the path. This also fixes signed URLs with grouped file URLs. 
+* Fixed that signed URLs now work with ~ in the path. This also fixes signed URLs with grouped file URLs.
 
 ## 4.4.2 — 2024-05-29
 

data/Gemfile

@@ -2,12 +2,29 @@
 
 source 'https://rubygems.org'
 
-gem 'byebug'
-gem 'rake'
-gem 'rspec'
-gem 'rubocop'
-gem 'vcr'
-gem 'webmock'
+group :development, :test do
+  # Ruby 3.4+ stopped shipping some stdlib components as default gems.
+  if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('3.4')
+    gem 'base64', require: false
+    gem 'cgi', require: false
+  end
+
+  # Ruby 4.1+ removes tsort from default gems.
+  gem('tsort', require: false) if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('4.1')
+
+  gem 'byebug'
+  gem 'dotenv', '~> 3.2' # For running examples with .env file
+  gem 'rake'
+  gem 'redcarpet'
+  gem 'rspec'
+  gem 'rubocop'
+  gem 'rubocop-rake'
+  gem 'rubocop-rspec'
+  gem 'simplecov', require: false
+  gem 'vcr'
+  gem 'webmock'
+  gem 'yard'
+end
 
 # Specify your gem's dependencies in uploadcare-ruby.gemspec
 gemspec

data/MIGRATING_V5.md

@@ -0,0 +1,290 @@
+# Migrating From v4.x to v5
+
+Version 5 moves the gem to a client-first API with a clearer split between the convenience layer and the endpoint-parity API.
+
+The main migration rule is simple:
+
+- use `Uploadcare::Client` for application code
+- use `client.files`, `client.groups`, `client.uploads`, and the other domain accessors for normal workflows
+- use `client.api.rest` and `client.api.upload` when you need exact Uploadcare endpoint behavior
+
+## What Changed
+
+Version 5 introduces:
+
+- a client-scoped configuration model
+- first-class multi-account support
+- a convenience layer that returns resources and raises typed exceptions
+- a raw API layer that mirrors the REST and Upload APIs and returns `Uploadcare::Result`
+- a modernized internal structure built around Zeitwerk and Faraday
+
+Version 5 also raises the minimum supported Ruby version to `3.3`.
+The CI matrix for v5 verifies `3.3`, `3.4`, and `4.0`.
+
+If you run examples locally with `.env`, use it only for developer machines and never commit real keys.
+The examples expect `UPLOADCARE_PUBLIC_KEY` and `UPLOADCARE_SECRET_KEY` to come from environment variables.
+
+## Recommended Migration Order
+
+1. Introduce explicit `Uploadcare::Client` instances in your application.
+2. Move app-facing code to `client.files`, `client.groups`, `client.uploads`, `client.project`, `client.webhooks`, `client.file_metadata`, `client.addons`, and `client.conversions`.
+3. Keep `client.api.rest` and `client.api.upload` only where you need raw endpoint parity.
+4. Audit return-type and error-handling assumptions.
+5. Remove any app code that depends on internal transport classes.
+
+## Configuration
+
+### Before
+
+Typical v4 code relied more heavily on the process-wide configuration singleton.
+
+```ruby
+Uploadcare.configure do |config|
+  config.public_key = ENV.fetch("UPLOADCARE_PUBLIC_KEY")
+  config.secret_key = ENV.fetch("UPLOADCARE_SECRET_KEY")
+end
+```
+
+### After
+
+Global configuration still exists, but the preferred style is explicit clients.
+
+```ruby
+client = Uploadcare::Client.new(
+  public_key: ENV.fetch("UPLOADCARE_PUBLIC_KEY"),
+  secret_key: ENV.fetch("UPLOADCARE_SECRET_KEY")
+)
+```
+
+You can also build and copy configuration objects directly:
+
+```ruby
+base = Uploadcare::Configuration.new(
+  public_key: ENV.fetch("UPLOADCARE_PUBLIC_KEY"),
+  secret_key: ENV.fetch("UPLOADCARE_SECRET_KEY")
+)
+
+primary = Uploadcare::Client.new(config: base)
+secondary = Uploadcare::Client.new(
+  config: base.with(public_key: "other-public-key", secret_key: "other-secret-key")
+)
+```
+
+This is the intended approach for multi-tenant Rails apps and for integrations that need more than one Uploadcare project in one process.
+
+## Public API Mapping
+
+### Uploads
+
+```ruby
+# v4-ish
+Uploadcare::Uploader.upload(object: file, store: true)
+
+# v5
+client.files.upload(file, store: true)
+# or
+client.uploads.upload(file, store: true)
+```
+
+```ruby
+# v4-ish
+Uploadcare::Uploader.upload(object: url, store: true)
+
+# v5
+client.files.upload_from_url(url, store: true)
+```
+
+```ruby
+# v4-ish
+Uploadcare::Uploader.upload_from_url(url: url, async: true)
+
+# v5
+client.uploads.upload_from_url(url: url, async: true)
+```
+
+```ruby
+# v4-ish
+Uploadcare::Uploader.upload_from_url_status(token: token)
+
+# v5
+client.uploads.upload_from_url_status(token: token)
+```
+
+### Files
+
+```ruby
+# v4-ish
+Uploadcare::File.info(uuid: uuid)
+
+# v5
+client.files.find(uuid: uuid)
+```
+
+```ruby
+# v4-ish
+Uploadcare::File.list(options: { limit: 100 })
+
+# v5
+client.files.list(limit: 100)
+```
+
+```ruby
+# v4-ish
+Uploadcare::File.batch_store(uuids: uuids)
+
+# v5
+client.files.batch_store(uuids: uuids)
+```
+
+```ruby
+# v4-ish
+Uploadcare::File.batch_delete(uuids: uuids)
+
+# v5
+client.files.batch_delete(uuids: uuids)
+```
+
+### Groups
+
+```ruby
+# v4-ish
+Uploadcare::Group.create(uuids: uuids)
+
+# v5
+client.groups.create(uuids: uuids)
+```
+
+```ruby
+# v4-ish
+Uploadcare::Group.info(group_id: group_id)
+
+# v5
+client.groups.find(group_id: group_id)
+```
+
+### Metadata
+
+```ruby
+# v4-ish
+Uploadcare::FileMetadata.update(uuid: uuid, key: "key", value: "value")
+
+# v5
+client.file_metadata.update(uuid: uuid, key: "key", value: "value")
+```
+
+### Webhooks
+
+```ruby
+# v4-ish
+Uploadcare::Webhook.create(target_url: url)
+
+# v5
+client.webhooks.create(target_url: url)
+```
+
+### Add-ons
+
+```ruby
+# v4-ish
+Uploadcare::Addons.check_remove_bg_status(request_id: request_id)
+
+# v5
+client.addons.remove_bg_status(request_id: request_id)
+```
+
+## Top-Level Constants
+
+These top-level resource constants still exist:
+
+- `Uploadcare::File`
+- `Uploadcare::Group`
+- `Uploadcare::Project`
+- `Uploadcare::Webhook`
+- `Uploadcare::FileMetadata`
+- `Uploadcare::DocumentConversion`
+- `Uploadcare::VideoConversion`
+
+They remain useful for compatibility and for direct resource-oriented usage, but the main application entry point is now `Uploadcare::Client`.
+
+## Errors and Results
+
+### Convenience Layer
+
+The convenience layer unwraps results and raises typed exceptions.
+
+```ruby
+file = client.files.find(uuid: uuid)
+```
+
+Typical exceptions include:
+
+- `Uploadcare::Exception::RequestError`
+- `Uploadcare::Exception::InvalidRequestError`
+- `Uploadcare::Exception::NotFoundError`
+- `Uploadcare::Exception::UploadError`
+- `Uploadcare::Exception::MultipartUploadError`
+- `Uploadcare::Exception::UploadTimeoutError`
+- `Uploadcare::Exception::ThrottleError`
+
+### Raw API Layer
+
+The raw API layer returns `Uploadcare::Result`.
+
+```ruby
+result = client.api.rest.files.info(uuid: uuid)
+
+if result.success?
+  puts result.success
+else
+  warn result.error_message
+end
+```
+
+If your v4 code assumed direct hashes everywhere, decide explicitly whether it belongs on the convenience layer or the raw API layer.
+
+## Return Type Changes
+
+### Files and Groups
+
+Convenience methods now return resource objects and paginated collections:
+
+- `client.files.find` -> `Uploadcare::File`
+- `client.files.list` -> `Uploadcare::Collections::Paginated`
+- `client.groups.find` -> `Uploadcare::Group`
+
+### Batch Operations
+
+Batch operations return `Uploadcare::Collections::BatchResult`.
+
+```ruby
+result = client.files.batch_store(uuids: uuids)
+
+result.status
+result.result
+result.problems
+```
+
+### Conversions
+
+Document and video conversions are intentionally not perfectly symmetrical:
+
+- `client.conversions.documents.convert` returns the API response hash
+- `client.conversions.videos.convert` returns a `Uploadcare::VideoConversion` resource
+
+Audit conversion code carefully if you rely on exact return types.
+
+## Internal APIs
+
+Version 5 keeps the internal transport layer available and documented, but it is not the recommended primary surface for application code.
+
+If you need it:
+
+- `client.api.rest`
+- `client.api.upload`
+
+If you are wrapping the gem from another library, prefer these explicit raw API entry points over reaching into lower-level internals.
+
+## See Also
+
+- [README.md](./README.md)
+- [CHANGELOG.md](./CHANGELOG.md)