uploadcare-rails 5.0.0.rc1 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e298d6f7b6671b0c29b4a040208d9c9a8d3def62b758a9489e64cacc989ffb5f
-  data.tar.gz: fdf9c58bad10d03b151d1f8414443aae1f7a64fbf91898af09986b59d26e68f9
+  metadata.gz: 6236e99b256e9622e9e4a806dc2e909fe43a6ef59b25ae013ce5e2b7826fff1b
+  data.tar.gz: de2380e25b4493e825359eb162e85fc38ccdbc32f8aeed38d31add0ec0a2a329
 SHA512:
-  metadata.gz: 7551eee19f17587751135df4b7d230ca47c72c5d6385cf7fd53e30fbe340386c6e2355ad14afff9da4676f4fa10c832099a258d29aecae0999798a2a3b011c31
-  data.tar.gz: 15188e878f0e66d778ae02fce2df71c6a3d0ae8f35d47ee9cad9f640636e486929d881af6e7504bbd41b04ad70656b0c2a890e4885bf580798737d150422f127
+  metadata.gz: eced3cce170c1e69bc1616617cf66357c0d37e96f75e0e27b905a45d791cd8d058ceebf02e0c8300e8cc27e562664f135719311743c3c6c141d8c29157207fd3
+  data.tar.gz: 627150f81723e25667c88cd250b43f677048431e0da359f4cfdc0b187f2d62ddab0c209b245548baf0444f703b62a9140b70b65ada26cb846014cbb0faab3217

data/CHANGELOG.md

@@ -6,11 +6,76 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## Unreleased
 
+## 5.0.0 - 2026-05-17
+
+This is the stable release of the v5 rewrite.
+
+There are no breaking API changes from `5.0.0.rc1`. This release promotes the
+rewrite to the stable line, removes prerelease dependency pins, and hardens the
+release workflow for tag-based RubyGems publishing.
+
+See [MIGRATING_V5.md](MIGRATING_V5.md)
+for the migration guide and [docs/release-notes-5.0.0.md](docs/release-notes-5.0.0.md)
+for release notes and examples.
+
+### Added
+
+* Active Storage service integration through `ActiveStorage::Service::UploadcareService`
+* Uploadcare-backed Active Storage preview and remote variant processing support
+* `Uploadcare::Rails.client` as the default Rails client entry point
+* explicit multi-account usage through `Uploadcare::Client`
+* `has_uploadcare_file` and `has_uploadcare_files` model macros
+* `uploadcare_file_field`, `uploadcare_files_field`, and matching FormBuilder helpers
+* `Uploadcare::Rails::AttachedFile` and `Uploadcare::Rails::AttachedFiles` wrappers
+* `rails g uploadcare_config` support for `config/uploadcare.yml`
+* Rails 7.2, 8.0, and 8.1 test matrix coverage
+* Ruby 3.3, 3.4, and experimental Ruby 4.0 CI coverage
+
+### Changed
+
+* Re-centered the gem around `uploadcare-ruby` 5.x instead of maintaining a
+  second API wrapper layer in `uploadcare-rails`
+* Simplified the documented public API to the Rails integration surface
+* Configuration now loads from `config/uploadcare.yml` when present and still
+  supports `Uploadcare::Rails.configure`
+* Active Storage service defaults to public URL mode and supports configurable
+  HTTP timeouts (`open_timeout`, `read_timeout`, `write_timeout`)
+* Mongoid hooks prefer `after_commit` callbacks when available, with fallback
+  to `after_save`/`after_destroy`
+* README and migration docs now describe the v5 client-first API and upgrade path
+
+### Fixed
+
+* Edit-form uploader prefill now binds `value` to `<uc-form-input>` instead of
+  leaking into `<uc-config>`
+* Active Storage blob-key to UUID cache writes are synchronized for thread safety
+* Variant and preview remote-processing paths avoid redundant API roundtrips for
+  CDN URL resolution
+* `AttachedFile#store` avoids a redundant file pre-fetch before storing
+* Uploadcare uploader helper options now warn on unknown keys and support
+  Rails-style `data: { ... }` passthrough attributes
+* SQL wildcard escaping in `delete_prefixed`
+* nil-key SDK configuration synchronization
+* tag-based gem publishing now validates the release tag against the gem version
+  before pushing to RubyGems
+
+### Removed
+
+* `mount_uploadcare_file`
+* `mount_uploadcare_file_group`
+* `uploadcare_uploader_field`
+* `uploadcare_uploader_field_tag`
+* `f.uploadcare_file`
+* `Uploadcare::Rails::File`
+* `Uploadcare::Rails::Group`
+* low-level uploader composition helpers from the documented public API
+* stale migration guides that described the pre-rewrite compatibility surface
+
 ## 5.0.0.rc1 - 2026-03-24
 
 This is the first release candidate for the 5.0 rewrite.
 
-See [MIGRATING_V5.md](https://github.com/uploadcare/uploadcare-rails/blob/5-0-stable/MIGRATING_V5.md) for the migration guide.
+See [MIGRATING_V5.md](MIGRATING_V5.md) for the migration guide.
 
 ### Changed
 

data/Gemfile

@@ -5,13 +5,13 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in uploadcare-rails.gemspec
 gemspec
 
-gem "uploadcare-ruby", "5.0.0.rc1"
+# Pin the released SDK for local and CI release validation.
+gem "uploadcare-ruby", "5.0.0"
 
 gem "http-parser", "~> 1.2", ">= 1.2.3"
 gem "rake", "~> 13.0.6"
 
 group :test do
-  gem "benchmark", "~> 0.4"
   gem "mongoid", "~> 9", require: false
   gem "ostruct"
   gem "rspec", "~> 3.12"
@@ -19,5 +19,4 @@ group :test do
   gem "rubocop-rails-omakase", require: false
   gem "vcr", "~> 6.1"
   gem "webmock", "~> 3.18"
-  gem "yard", "~> 0.9"
 end

data/MIGRATING_V5.md

@@ -1,6 +1,14 @@
 # Migrating to uploadcare-rails 5.0
 
-This guide covers migration from the older `uploadcare-rails` surface to the rewritten, client-first API released in `5.0.0.rc1`.
+This guide covers migration from the older `uploadcare-rails` surface to the rewritten, client-first API released in `5.0.0`.
+
+## Compatibility summary
+
+- Runtime minimums are Ruby 3.3+ and Rails 7.2+.
+- This is a breaking major upgrade from the pre-v5 API.
+- API usage now goes through `Uploadcare::Rails.client` or explicit `Uploadcare::Client` instances.
+- Active Storage direct uploads are not supported by `ActiveStorage::Service::UploadcareService`; use the Uploadcare uploader field helpers for browser direct uploads.
+- Custom per-tenant clients work with mounted objects and synchronous callbacks. Async callbacks use the default `Uploadcare::Rails.client`.
 
 The short version:
 

data/README.md

@@ -8,7 +8,7 @@
 
 `uploadcare-rails` is a Rails integration for Uploadcare built on top of the rewritten `uploadcare-ruby` client API.
 
-The current stable branch is shipping as the `5.0.0.rc1` release candidate line.
+The current stable branch is the `5.0` release line.
 
 The gem is centered on:
 
@@ -45,7 +45,7 @@ This version uses the new [Uploadcare File Uploader](https://uploadcare.com/docs
 Add the gem to your Gemfile:
 
 ```ruby
-gem "uploadcare-rails", "5.0.0.rc1"
+gem "uploadcare-rails", "~> 5.0"
 ```
 
 Then install:
@@ -63,7 +63,7 @@ gem "uploadcare-api_struct"
 You can also install the gem directly:
 
 ```bash
-gem install uploadcare-rails --pre -v 5.0.0.rc1
+gem install uploadcare-rails -v 5.0.0
 ```
 
 ## Configuration
@@ -535,6 +535,8 @@ Public utility constants:
 
 ## Useful links
 
+- [Release notes for 5.0.0](docs/release-notes-5.0.0.md)
+- [Migration guide for 5.0](MIGRATING_V5.md)
 - [Uploadcare File Uploader docs](https://uploadcare.com/docs/file-uploader/)
 - [Uploadcare Ruby SDK](https://github.com/uploadcare/uploadcare-ruby)
 - [Uploadcare API docs](https://uploadcare.com/docs/start/api/)

data/docs/release-notes-5.0.0.md

@@ -0,0 +1,128 @@
+# uploadcare-rails 5.0.0 release notes
+
+Release v5.0.0: stable rewrite on `uploadcare-ruby` 5.x.
+
+Must: publish `uploadcare-ruby` 5.0.0 first. CI/install will fail otherwise.
+
+Before tagging:
+
+- Verify CI: Rails 7.2, 8.0, 8.1 plus Active Storage.
+- Smoke-test one 4.x to 5.0 migration using [MIGRATING_V5.md](../MIGRATING_V5.md).
+- Tag and publish `uploadcare-rails` 5.0.0.
+
+Migration priority: test in this order.
+
+- Manual API wrappers: `Uploadcare::FileApi`, `Uploadcare::GroupApi`, `Uploadcare::UploadApi`
+- `mount_uploadcare_file` or `mount_uploadcare_file_group`
+- Removed uploader helper aliases
+- Active Storage
+
+Quick scan:
+
+```sh
+git grep -n "mount_uploadcare_file\|Uploadcare::FileApi\|Uploadcare::GroupApi\|Uploadcare::UploadApi\|uploadcare_uploader_field"
+```
+
+No API changes since `5.0.0.rc1`. Applications moving from 4.x or older should
+follow [MIGRATING_V5.md](../MIGRATING_V5.md).
+
+## Highlights
+
+- Client-first API: `Uploadcare::Rails.client` and `Uploadcare::Client`
+- Model macros: `has_uploadcare_file` and `has_uploadcare_files`
+- Uploader helpers: `uploadcare_file_field`, `uploadcare_files_field`, and FormBuilder equivalents
+- Wrapper objects: `Uploadcare::Rails::AttachedFile` and `Uploadcare::Rails::AttachedFiles`
+- Active Storage service: `ActiveStorage::Service::UploadcareService`
+- Active Storage preview and remote variant processing for Uploadcare-backed blobs
+- Rails 7.2+ and Ruby 3.3+ runtime baseline
+
+## Breaking changes
+
+- `mount_uploadcare_file` and `mount_uploadcare_file_group` are removed. Use `has_uploadcare_file` and `has_uploadcare_files`.
+- `uploadcare_uploader_field`, `uploadcare_uploader_field_tag`, and `f.uploadcare_file` are removed. Use `uploadcare_file_field`, `uploadcare_files_field`, `f.uploadcare_file_field`, and `f.uploadcare_files_field`.
+- `Uploadcare::Rails::File` and `Uploadcare::Rails::Group` are replaced by `Uploadcare::Rails::AttachedFile` and `Uploadcare::Rails::AttachedFiles`.
+- Manual API wrappers such as `Uploadcare::FileApi`, `Uploadcare::GroupApi`, and `Uploadcare::UploadApi` are no longer the public path. Use `Uploadcare::Rails.client` or explicit `Uploadcare::Client` instances.
+- `do_not_store:` is replaced by the positive `store_files_after_save` configuration.
+
+## Upgrade examples
+
+Model macros:
+
+```ruby
+class Post < ApplicationRecord
+  has_uploadcare_file :picture
+  has_uploadcare_files :attachments
+end
+```
+
+Uploader fields:
+
+```erb
+<%= form_with model: @post do |f| %>
+  <%= f.uploadcare_file_field :picture %>
+  <%= f.uploadcare_files_field :attachments, solution: "inline" %>
+  <%= f.submit %>
+<% end %>
+```
+
+Manual API usage:
+
+```ruby
+client = Uploadcare::Rails.client
+
+file = client.files.find(uuid: "2d33999d-c74a-4ff9-99ea-abc23496b052")
+group = client.groups.find(group_id: "dbc4e868-b7a6-43ff-a35f-2ebef935dc1b~2")
+project = client.project.current
+```
+
+Multi-account usage:
+
+```ruby
+client = Uploadcare::Client.new(
+  public_key: account.uploadcare_public_key,
+  secret_key: account.uploadcare_secret_key
+)
+
+client.files.find(uuid: "2d33999d-c74a-4ff9-99ea-abc23496b052")
+```
+
+Active Storage:
+
+```yml
+uploadcare:
+  service: Uploadcare
+  public_key: <%= ENV.fetch("UPLOADCARE_PUBLIC_KEY") %>
+  secret_key: <%= ENV.fetch("UPLOADCARE_SECRET_KEY") %>
+  public: true
+```
+
+```ruby
+config.active_storage.service = :uploadcare
+```
+
+## Operator notes
+
+- Must: publish `uploadcare-ruby` 5.0.0 first. CI/install will fail otherwise.
+- Verify: Rails 7.2, 8.0, 8.1 plus Active Storage specs are green before tagging.
+- Risk: `UploadcareService` does not support direct uploads or signed private URLs. Private blobs and direct client uploads will break.
+- Mitigation before tagging:
+  - Set service `public: true` for affected apps.
+  - Prefer uploader field helpers, not direct service calls.
+  - Smoke-test previews and remote variants end-to-end.
+- Per-tenant clients: use `uploadcare_client:` for mounted objects and synchronous callbacks. Async callbacks use `Uploadcare::Rails.client`.
+- Migration priority: test apps that use manual API wrappers, `mount_*` macros, uploader helper aliases, or Active Storage first.
+
+## Release checklist
+
+Do not skip:
+
+1. `bundle install` resolves `uploadcare-ruby (= 5.0.0)`.
+2. CI green: Rails 7.2, 8.0, 8.1 plus Active Storage specs.
+3. Tag: `git tag -a v5.0.0 -m "uploadcare-rails v5.0.0" && git push origin v5.0.0`.
+4. Publish: confirm the `Publish Gem` workflow uploads `uploadcare-rails-5.0.0.gem`.
+5. Post-release: smoke test a migrated app and verify Active Storage blobs, previews, and variants.
+
+Rollback policy:
+
+- If RubyGems rejects the gem before publish, delete the failed tag, fix, and retag.
+- If the gem is published, do not reuse the tag. Ship a patch release.

data/lib/uploadcare/rails/attached_file.rb

@@ -34,6 +34,7 @@ module Uploadcare
       end
 
       def store
+        ensure_uuid!("store file")
         resource = Uploadcare::Resources::File.new({ "uuid" => uuid }, resolve_client)
         resource.store
         file_info = file_info_from_resource(resource)
@@ -42,10 +43,12 @@ module Uploadcare
       end
 
       def delete
+        ensure_uuid!("delete file")
         resolve_client.files.batch_delete(uuids: [ uuid ])
       end
 
       def load(force: false)
+        ensure_uuid!("load file")
         ::Rails.cache.delete(cache_key) if force && caching_enabled?
 
         file_info = if caching_enabled?
@@ -86,6 +89,12 @@ module Uploadcare
         resolved_cdn_url = cdn_url.presence || resource_hash["cdn_url"].presence || resource_hash["url"]
         resource_hash.merge("cdn_url" => resolved_cdn_url)
       end
+
+      def ensure_uuid!(action)
+        return if uuid.present?
+
+        raise ArgumentError, "uuid is required to #{action}"
+      end
     end
   end
 end

data/lib/uploadcare/rails/attached_files.rb

@@ -42,6 +42,8 @@ module Uploadcare
       end
 
       def file_urls
+        return [] if cdn_url.blank?
+
         map_file_urls do |index|
           group_file_url(index)
         end
@@ -96,7 +98,11 @@ module Uploadcare
       end
 
       def group_file_url(index)
-        "#{cdn_url}nth/#{index}/"
+        "#{normalized_cdn_url}nth/#{index}/"
+      end
+
+      def normalized_cdn_url
+        cdn_url.end_with?("/") ? cdn_url : "#{cdn_url}/"
       end
 
       def map_file_urls(&block)

data/lib/uploadcare/rails/internal/active_storage_service_helpers.rb

@@ -57,10 +57,21 @@ module Uploadcare
 
         def build_request(uri, range)
           request = Net::HTTP::Get.new(uri)
-          request["Range"] = "bytes=#{range.begin}-#{range.end}" if range
+          request["Range"] = range_header(range) if range
           request
         end
 
+        def range_header(range)
+          range_end = range.end
+          range_end -= 1 if range_end && range.exclude_end?
+
+          if range_end && range.begin && range_end < range.begin
+            raise ArgumentError, "range end must be greater than or equal to range begin"
+          end
+
+          range_end ? "bytes=#{range.begin}-#{range_end}" : "bytes=#{range.begin}-"
+        end
+
         def request_streaming(http, request, &block)
           result = nil
 

data/lib/uploadcare/rails/internal/client_resolver.rb

@@ -6,12 +6,15 @@ module Uploadcare
       module ClientResolver
         def resolve_client(client_or_options = nil)
           case client_or_options
+          when nil
+            client
           when Uploadcare::Client
             client_or_options
           when Hash
             client(**client_or_options.symbolize_keys)
           else
-            client
+            raise ArgumentError,
+                  "uploadcare_client must be an Uploadcare::Client, Hash, or nil; got #{client_or_options.class}"
           end
         end
       end

data/lib/uploadcare/rails/internal/id_extractor.rb

@@ -10,7 +10,7 @@ module Uploadcare
           def call(input_str, regex = UUID_REGEX)
             return unless input_str.present?
 
-            input_str.match(regex).to_s
+            input_str.match(regex)&.to_s
           end
         end
       end

data/lib/uploadcare/rails/internal/uploader_field_helpers.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "action_view"
+require "json"
 require "set"
 
 module Uploadcare
@@ -70,7 +71,10 @@ module Uploadcare
         def uploadcare_config_tag(ctx_name:, **options)
           default_options = Uploadcare::Rails.configuration.uploader_config_attributes
 
-          normalize_key = ->(key) { key.to_s.tr("_", "-").to_sym }
+          normalize_key = lambda do |key|
+            attr_name = key.to_s.tr("_", "-")
+            attr_name == "public-key" ? :pubkey : attr_name.to_sym
+          end
           normalized_options = options.transform_keys(&normalize_key)
           filtered_options = filter_uploader_config_options(normalized_options)
 
@@ -94,7 +98,21 @@ module Uploadcare
           unknown_keys = options.keys - allowed.to_a - data_attributes[:consumed_keys]
           warn_unknown_uploader_options(unknown_keys) if unknown_keys.any?
 
-          options.slice(*allowed.to_a).merge(data_attributes[:attributes])
+          options
+            .slice(*allowed.to_a)
+            .transform_values { |value| format_uploader_config_value(value) }
+            .merge(data_attributes[:attributes])
+        end
+
+        def format_uploader_config_value(value)
+          case value
+          when Hash
+            JSON.generate(value)
+          when Array
+            value.join(",")
+          else
+            value
+          end
         end
 
         def extract_data_attributes(options)
@@ -143,7 +161,7 @@ module Uploadcare
         end
 
         def uploadcare_file_group_attribute?(object_name, method_name, object: nil)
-          model = object_name.to_s.camelize.safe_constantize || object&.class
+          model = object&.class || object_name.to_s.camelize.safe_constantize
           return false unless model
 
           checker = "has_uploadcare_files_for_#{method_name}?"

data/lib/uploadcare/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Uploadcare
   module Rails
-    VERSION = "5.0.0.rc1"
+    VERSION = "5.0.0"
   end
 end

data/uploadcare-rails.gemspec

@@ -15,13 +15,13 @@ Gem::Specification.new do |gem|
   gem.email         = [ 'hello@uploadcare.com' ]
   gem.summary       = 'Rails gem for Uploadcare'
   gem.description   = <<~DESCRIPTION
-    Rails API client (based on uploadcare-ruby) that handles uploads
-    and further operations with files by wrapping Uploadcare Upload and REST APIs.
+    Rails integration for Uploadcare built on uploadcare-ruby, with uploader
+    helpers, model macros, and Active Storage support.
   DESCRIPTION
   gem.metadata = {
     'source_code_uri' => 'https://github.com/uploadcare/uploadcare-rails',
     'bug_tracker_uri' => 'https://github.com/uploadcare/uploadcare-rails/issues',
-    'changelog_uri' => 'https://github.com/uploadcare/uploadcare-rails/blob/5-0-stable/CHANGELOG.md',
+    'changelog_uri' => 'https://github.com/uploadcare/uploadcare-rails/blob/main/CHANGELOG.md',
     'documentation_uri' => 'https://www.rubydoc.info/gems/uploadcare-rails/',
     'homepage_uri' => 'https://uploadcare.com/',
     'rubygems_mfa_required' => 'true'
@@ -37,13 +37,14 @@ Gem::Specification.new do |gem|
     'LICENSE.txt',
     'README.md',
     'CHANGELOG.md',
-    'MIGRATING_V5.md'
+    'MIGRATING_V5.md',
+    'docs/**/*.md'
   ]
 
   gem.extra_rdoc_files  = %w[README.md MIGRATING_V5.md LICENSE.txt]
-  gem.rdoc_options      = %w[--line-numbers --title Uploadcare --main README.rdoc --encoding=UTF-8]
+  gem.rdoc_options      = %w[--line-numbers --title Uploadcare --main README.md --encoding=UTF-8]
 
   gem.version = Uploadcare::Rails::VERSION
   gem.add_dependency 'rails', '>= 7.2'
-  gem.add_dependency 'uploadcare-ruby', '>= 5.0.0.rc1'
+  gem.add_dependency 'uploadcare-ruby', '>= 5.0.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: uploadcare-rails
 version: !ruby/object:Gem::Version
-  version: 5.0.0.rc1
+  version: 5.0.0
 platform: ruby
 authors:
 - "@dmitrijivanchenko (Dmitrij Ivanchenko), @T0mbery (Andrey Aksenov)"
@@ -30,17 +30,17 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.0.0.rc1
+        version: 5.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.0.0.rc1
+        version: 5.0.0
 description: |
-  Rails API client (based on uploadcare-ruby) that handles uploads
-  and further operations with files by wrapping Uploadcare Upload and REST APIs.
+  Rails integration for Uploadcare built on uploadcare-ruby, with uploader
+  helpers, model macros, and Active Storage support.
 email:
 - hello@uploadcare.com
 executables: []
@@ -56,6 +56,7 @@ files:
 - MIGRATING_V5.md
 - README.md
 - Rakefile
+- docs/release-notes-5.0.0.md
 - lib/active_storage/service/uploadcare_service.rb
 - lib/generators/templates/uploadcare_config.yml.erb
 - lib/generators/templates/uploadcare_js_initializer.js
@@ -97,7 +98,7 @@ licenses:
 metadata:
   source_code_uri: https://github.com/uploadcare/uploadcare-rails
   bug_tracker_uri: https://github.com/uploadcare/uploadcare-rails/issues
-  changelog_uri: https://github.com/uploadcare/uploadcare-rails/blob/5-0-stable/CHANGELOG.md
+  changelog_uri: https://github.com/uploadcare/uploadcare-rails/blob/main/CHANGELOG.md
   documentation_uri: https://www.rubydoc.info/gems/uploadcare-rails/
   homepage_uri: https://uploadcare.com/
   rubygems_mfa_required: 'true'
@@ -106,7 +107,7 @@ rdoc_options:
 - "--title"
 - Uploadcare
 - "--main"
-- README.rdoc
+- README.md
 - "--encoding=UTF-8"
 require_paths:
 - lib