mobility_active_storage 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d4544d367fbdc080f61260f4706289e6fa009088ab73399ee5ee4efbe1597f2f
+  data.tar.gz: cb31f79f1ba41e277fe74bd2a707e3a861a756b1e6c4659434ae5dac4312a19c
+SHA512:
+  metadata.gz: 260385aedbb5bf84fa7c244a669b108fa3b6a7671d48228e70f617fa2656c53bf03fc90ee1993ee3d9513b26701226dad5572afdcea6be1dd53e00253eb8c941
+  data.tar.gz: 8ffb358c2898f8ae304c43f135e97ad4105e9fa97ba419b1c6af823e8afe26f621c85f343b2f092273441f777a1f1bc50d84089ddb440283dc7283005d2337bf

data/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+## [Unreleased]
+
+Pre-release fixes from a security review of the initial commit.
+
+- A `fallback:` read option is now honoured only where the attribute actually configures
+  fallbacks. Previously `document(fallback: :ja)` cross-read another locale even on an attribute
+  declaring `fallbacks: false`, so the declaration was not enforceable by a caller forwarding
+  untrusted options. Matches Mobility, whose fallbacks plugin is inert when `fallbacks: false`.
+- `with_attached_*` scopes now validate the current locale against the attribute's configured
+  locales, raising the same `MobilityActiveStorage::Error` as the read path instead of an
+  `ActiveRecord::AssociationNotFoundError` about a generated association name.
+- The lazily built fallback proxy classes are now guarded by a mutex.
+- Translated attachments are no longer merged into `attributes`, `translated_attributes` or
+  `attribute_names_for_serialization` by Mobility's `attribute_methods` plugin. The value there
+  was a live `ActiveStorage::Attached` proxy referencing the record, so `attributes.to_json` and
+  `as_json` raised `SystemStackError` and `Model.new(record.attributes)` raised `ArgumentError`.
+  Rails' own `has_one_attached` puts nothing in `attributes`; this now matches. (`attribute_methods:
+  false` is not a workaround -- Mobility 1.3.2 accepts and silently ignores it.)
+- Querying a translated attachment now raises `MobilityActiveStorage::Error` with an explanation
+  instead of a `NoMethodError` from inside Mobility's query plugin.
+- The test harness now enables `attribute_methods`, `query`, `dirty` and `fallthrough_accessors`,
+  which it previously did not, so the suite exercises a maximal Mobility configuration.
+- Raised the `activerecord` / `activestorage` floor to `>= 7.2.3.2`, the earliest release clearing
+  every current Active Storage advisory. Rails 7.0 and 7.1 are end-of-life with no fix available for
+  those advisories, and this gem serves more attachments through exactly the affected paths.
+- CI runs a Rails 7.2/8.0/latest matrix on Ruby 3.2 through 4.0, plus `bundler-audit`. Actions are
+  pinned by SHA.
+- README: strong-parameters guidance for the per-locale writers, and Rails version security notes.
+
+## [0.1.0] - 2026-08-07
+
+- Initial release.
+- `has_one_translated_attached` and `has_many_translated_attached` macros on Active Record models.
+- `Mobility::Backends` registrations for `:active_storage` and `:active_storage_many`.
+- Per-locale attachments stored under locale-suffixed Active Storage attachment names
+  (`document_en`, `document_fr`), requiring no migration.
+- Opt-in per-attribute fallbacks, where reads resolve through the fallback chain while writes
+  stay in the current locale.
+- `#{attribute}_locales` and a current-locale `with_attached_#{attribute}` scope.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"mobility_active_storage" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["barnaclebarnes@mac.com"](mailto:"barnaclebarnes@mac.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Glen Barnes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,247 @@
+# mobility_active_storage
+
+Translated [Active Storage](https://guides.rubyonrails.org/active_storage_overview.html)
+attachments for [Mobility](https://github.com/shioyama/mobility).
+
+Attach a different file per locale under a single attribute name:
+
+```ruby
+class Product < ApplicationRecord
+  extend Mobility
+
+  translates :title, :description, type: :string   # ordinary Mobility text
+  has_one_translated_attached  :document
+  has_many_translated_attached :photos
+end
+```
+
+```ruby
+product.document.attach(io: pdf, filename: "manual.pdf", content_type: "application/pdf")
+
+Mobility.with_locale(:fr) do
+  product.document.attach(io: pdf_fr, filename: "manuel.pdf", content_type: "application/pdf")
+end
+
+product.document                              # => the :en file
+Mobility.with_locale(:fr) { product.document } # => the :fr file
+product.document_fr                            # => the :fr file
+```
+
+## No migration required
+
+Active Storage's `active_storage_attachments.name` column is a plain string, so each locale is
+stored as an ordinary attachment whose name carries the locale:
+
+| name          | record_type | record_id | blob_id |
+| ------------- | ----------- | --------- | ------- |
+| `document_en` | Product     | 1         | 10      |
+| `document_fr` | Product     | 1         | 11      |
+
+Each is declared with a real `has_one_attached` / `has_many_attached` under the hood, so variants,
+previews, direct uploads, `purge`, `dependent: :purge_later` on destroy, and the generated
+`document_en_attachment` / `document_en_blob` / `with_attached_document_en` all keep working
+exactly as Rails defines them.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "mobility_active_storage"
+```
+
+You need Active Storage installed (`bin/rails active_storage:install`) and Mobility configured.
+Mobility does not need any translation tables for attachments — if attachments are all you
+translate, [installing Mobility without tables](https://github.com/shioyama/mobility#activerecord-rails)
+is enough.
+
+`extend Mobility` is optional: the macros extend the model for you if it isn't already.
+
+## Usage
+
+### Reading and writing
+
+Everything Active Storage's own proxy supports works, scoped to the current locale:
+
+```ruby
+product.document.attach(uploaded_file)
+product.document.attached?      # => true
+product.document.filename       # => "manual.pdf"
+product.document.purge          # purges only the current locale's file
+product.document = nil          # detaches only the current locale's file
+
+product.photos.attach(one, two) # appends, per locale
+product.photos = [one]          # replaces the current locale's collection
+```
+
+Assignment works on unsaved records and in `create`, so form params flow through normally:
+
+```ruby
+Product.create!(title: "Widget", document: params[:document])
+```
+
+### Generated methods
+
+For `has_one_translated_attached :document`:
+
+| Method                        | Description                                              |
+| ----------------------------- | -------------------------------------------------------- |
+| `document`                    | `ActiveStorage::Attached::One` for the current locale     |
+| `document=`                   | Attach/detach in the current locale                       |
+| `document_en`, `document_fr`  | A specific locale (dashed locales normalize: `pt_br`)     |
+| `document?`                   | Whether a file is attached in the current locale          |
+| `document_locales`            | Locales that actually have an attachment, e.g. `[:en, :fr]` |
+| `Product.with_attached_document` | Eager-loads whichever locale is current                 |
+
+`has_many_translated_attached :photos` mirrors these with `ActiveStorage::Attached::Many`.
+
+### Fallbacks
+
+Off by default. Enable per attribute:
+
+```ruby
+has_one_translated_attached :document, fallbacks: true          # I18n's chain, ending at the default locale
+has_one_translated_attached :document, fallbacks: { fr: :en }   # explicit
+```
+
+Reads then resolve through the chain, while **writes always stay in the current locale** — so
+attaching, purging or detaching under a fallback never touches the file you fell back to:
+
+```ruby
+product.document.attach(en_file)               # :en has a file, :fr does not
+
+Mobility.with_locale(:fr) do
+  product.document.filename                    # => the :en file
+  product.document(fallback: false).attached?  # => false
+  product.document.attach(fr_file)             # creates document_fr; document_en untouched
+end
+```
+
+Pass `fallback: :ja` or `fallback: [:ja, :en]` to override the chain for a single read. That
+override only applies where fallbacks are configured — an attribute declaring no fallbacks cannot be
+talked into one by a read option, so `fallbacks: false` is enforceable even if a caller forwards
+untrusted options into the reader. This matches Mobility, whose fallbacks plugin is inert when
+`fallbacks: false`.
+
+### Options
+
+Both macros accept:
+
+- `fallbacks:` — `true`, or a hash such as `{ fr: :en }`. Default `false`.
+- `locales:` — which locales to declare attachments for. Defaults to `Mobility.available_locales`.
+- any remaining options are forwarded to Rails, e.g. `service:`, `strict_loading:`, `dependent:`.
+
+```ruby
+has_one_translated_attached :document, locales: %i[en fr], service: :s3, strict_loading: true
+```
+
+### Using the backend directly
+
+The macros are sugar over ordinary Mobility backends, which you can also use directly:
+
+```ruby
+translates :document, backend: :active_storage
+translates :photos,   backend: :active_storage_many
+```
+
+The macros additionally switch off the Mobility plugins that assume a scalar value. Declaring the
+backend directly means doing that yourself, for whichever of them you have enabled:
+
+```ruby
+translates :document, backend: :active_storage, fallbacks: false, cache: false, dirty: false
+```
+
+Passing an option for a plugin you have *not* enabled raises `Mobility::Pluggable::InvalidOptionKey`,
+so pass only the ones that apply. Keeping attachments out of `attributes` is handled by the backend
+itself, so it applies on this path too.
+
+## Strong parameters
+
+Each locale gets its own set of writers. `has_one_translated_attached :document` on a four-locale
+app defines `document=`, `document_en=`, `document_fr=`, `document_ja=`, `document_pt_br=` (plus the
+`_attachment=` / `_blob=` association writers Rails generates), and they all work through mass
+assignment. That is inherent to `has_one_attached`, but the names are not obvious from the single
+macro call in your model.
+
+Permit only the bare attribute name, which routes through Mobility to the current locale:
+
+```ruby
+params.expect(product: [:title, :document, photos: []])
+```
+
+Permit the `_<locale>` variants only where a locale switcher genuinely needs them. A blanket
+`permit!`, or a filter matching `/\Adocument/`, would let a user overwrite a locale they were never
+editing — and with fallbacks enabled, that changes what other locales serve too.
+
+## Rails compatibility
+
+Requires **Rails >= 7.2.3.2** and Ruby >= 3.2. Tested in CI against Rails 7.2, 8.0 and latest, on
+Ruby 3.2 through 4.0.
+
+The floor is deliberately a patch level rather than a minor version. Rails 7.0 and 7.1 are
+end-of-life and carry Active Storage advisories with no fix available — path traversal and glob
+injection in `DiskService`, a content-type bypass in direct uploads, and DoS via `Range` requests in
+proxy mode. Since this gem's whole purpose is to serve more attachments through exactly those paths,
+it does not support them. 7.2.3.2 is the earliest release that clears every current Active Storage
+advisory; the equivalent for the 8.0 series is 8.0.5.1.
+
+Run [bundler-audit](https://github.com/rubysec/bundler-audit) or Dependabot in your application to
+stay ahead of new advisories.
+
+## Notes and limitations
+
+**Locales are read when the class body runs.** Attachments are declared for
+`Mobility.available_locales` at that moment, so adding a locale needs a code reload. Pass
+`locales:` to pin the set explicitly.
+
+**Mobility's `fallbacks` plugin is disabled for these attributes**, and this gem implements
+fallbacks itself. Mobility's plugin triggers on a `nil` read, but an attachment reader has to
+return a proxy even when nothing is attached, or `product.document.attach(...)` would fail on a
+record with no file yet.
+
+**The `cache` plugin is disabled** for these attributes, since it would memoize a proxy resolved
+through a fallback and keep returning the fallback locale's file after a later attach.
+
+**Dirty tracking is not supported.** Mobility's `dirty` plugin compares scalar values; it is
+disabled for these attributes. Active Storage's own `attachment_changes` still works.
+
+**Attachment attributes are kept out of `attributes`.** Mobility's `attribute_methods` plugin
+merges every translated attribute into `attributes`, `translated_attributes` and
+`attribute_names_for_serialization`. For an attachment that value would be a live
+`ActiveStorage::Attached` proxy holding a reference back to the record, which makes the hash
+unserialisable (`attributes.to_json` and `as_json` recurse until the stack overflows) and unusable
+for mass assignment (`Model.new(record.attributes)` raises `ArgumentError`, since Active Storage
+rejects a proxy as an attachable). Rails' own `has_one_attached` puts nothing in `attributes`, and
+neither does this gem — a proxy is not a serialisable value. Translated *text* attributes are
+unaffected and still appear as Mobility intends.
+
+Note that `attribute_methods: false` is not a workaround: Mobility 1.3.2 accepts the option and
+silently ignores it, because the plugin's `initialize_hook` is gated on `dependencies_satisfied?`
+rather than on the option value.
+
+**Querying is not supported.** `Product.i18n.where(document: ...)` is not meaningful for
+attachments — there is no comparable column, only rows in `active_storage_attachments`. The
+backend raises `MobilityActiveStorage::Error` explaining this rather than failing obscurely inside
+Arel. Query the attachments directly, filtering on `name` (for example `"document_en"`).
+
+## Development
+
+```sh
+bin/setup
+bundle exec rake        # tests + rubocop
+
+# against a specific Rails version
+BUNDLE_GEMFILE=gemfiles/rails_7.2.gemfile bundle install
+BUNDLE_GEMFILE=gemfiles/rails_7.2.gemfile bundle exec rake test
+```
+
+The suite boots a minimal `Rails::Application` in `test/test_helper.rb` against in-memory SQLite,
+so there is no dummy app to maintain.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/barnaclebarnes/mobility_active_storage.
+
+## License
+
+Available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/mobility_active_storage/attribute_methods_exclusion.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module MobilityActiveStorage
+  # Keeps translated attachments out of the attribute hashes.
+  #
+  # Mobility's attribute_methods plugin merges every translated attribute into +attributes+. For
+  # an attachment that value is a live +ActiveStorage::Attached+ proxy holding a reference back to
+  # the record, so the hash cannot be serialised (+to_json+ recurses until the stack blows) and
+  # cannot be fed back into +Model.new+ (Active Storage rejects a proxy as an attachable). Rails'
+  # own +has_one_attached+ puts nothing in +attributes+; this restores that.
+  #
+  # Overriding +translated_attributes+ also cleans +attributes+: the plugin defines the latter as
+  # +super.merge(translated_attributes)+, and that inner call dispatches from the record, so it
+  # reaches this module first.
+  #
+  # Prepended rather than included, which matters. +include+ places this module *behind* any
+  # Mobility module added afterwards, and re-including an already-included module does not move it
+  # forward -- so a second +translates+ call (a second attachment macro, or a later
+  # +translates :title+) would merge its name back in after the filter had run. A prepended module
+  # stays ahead of every later include. Verified against Ruby's method resolution, not assumed.
+  module AttributeMethodsExclusion
+    # Registers +attribute+ on +model_class+ and installs the filter. Called from the backends'
+    # setup blocks rather than from the macros, so that declaring the backend directly with
+    # `translates :document, backend: :active_storage` is covered too.
+    def self.install(model_class, attribute)
+      model_class.translated_attachment_attribute_names << attribute.to_s
+
+      # Nothing to filter unless the plugin that does the merging is loaded -- and `super` in
+      # #translated_attributes would have nothing to reach.
+      return unless Mobility.translations_class.included_plugins
+                            .map { |plugin| Mobility::Plugins.lookup_name(plugin) }
+                            .include?(:attribute_methods)
+
+      model_class.prepend(self)
+    end
+
+    def translated_attributes
+      super.except(*self.class.translated_attachment_attribute_names)
+    end
+
+    private
+
+    def attribute_names_for_serialization
+      return unless defined?(super)
+
+      super - self.class.translated_attachment_attribute_names
+    end
+  end
+end

data/lib/mobility_active_storage/backend.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "backend_methods"
+
+module MobilityActiveStorage
+  # Mobility backend for a single translated Active Storage attachment.
+  #
+  # @example
+  #   class Product < ApplicationRecord
+  #     extend Mobility
+  #     translates :document, backend: :active_storage
+  #   end
+  #
+  #   product.document.attach(io: file, filename: "en.pdf", content_type: "application/pdf")
+  #   Mobility.with_locale(:fr) { product.document.attach(...) }
+  class Backend
+    include Mobility::Backend
+    include BackendMethods
+
+    setup do |attributes, options, backend_class|
+      attributes.each do |attribute|
+        options[:locales].each do |locale|
+          has_one_attached :"#{attribute}_#{Mobility.normalize_locale(locale)}",
+                           **options[:attached_options]
+        end
+
+        # Eager-loads whichever locale is current when the scope is evaluated. Validates the
+        # locale the same way the read path does.
+        scope :"with_attached_#{attribute}", lambda {
+          name = backend_class.attachment_name_for(attribute, Mobility.locale)
+          includes("#{name}_attachment": :blob)
+        }
+
+        define_method(:"#{attribute}_locales") { mobility_backends[attribute].locales }
+
+        # An attachment proxy is not a serialisable value, and Rails does not put one in
+        # `attributes` either. Installed here rather than in the macro so that declaring
+        # this backend directly through `translates` is covered too.
+        AttributeMethodsExclusion.install(self, attribute)
+      end
+    end
+
+    private
+
+    def attached_class
+      ActiveStorage::Attached::One
+    end
+
+    def fallback_attached_class
+      FallbackAttached.one
+    end
+
+    def build_change(name, value)
+      if value.nil? || value == ""
+        ActiveStorage::Attached::Changes::DeleteOne.new(name, model)
+      else
+        ActiveStorage::Attached::Changes::CreateOne.new(name, model, value)
+      end
+    end
+  end
+end

data/lib/mobility_active_storage/backend_methods.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "i18n/locale/fallbacks"
+
+module MobilityActiveStorage
+  # Behaviour shared by the has_one and has_many attachment backends.
+  #
+  # A translated attachment is stored as N ordinary Active Storage attachments whose
+  # +name+ column carries the locale, e.g. +document_en+ and +document_fr+. Each one is
+  # declared with a real +has_one_attached+ / +has_many_attached+ in the backend's setup
+  # block, so Rails' own associations, upload callbacks, scopes and purge-on-destroy
+  # behaviour apply unchanged.
+  #
+  # Backends must +include Mobility::Backend+ *before* this module, so that the overrides here
+  # (notably +each_locale+ and +present?+) take precedence over Mobility::Backend's generic
+  # implementations.
+  module BackendMethods
+    def self.included(base)
+      raise Error, "#{base} must include Mobility::Backend before #{self}" unless base < Mobility::Backend
+
+      base.extend(ClassMethods)
+    end
+
+    # Class-level configuration shared by both backends.
+    module ClassMethods
+      def valid_keys
+        %i[locales attachment_fallbacks attached_options]
+      end
+
+      def configure(options)
+        options[:locales] = Array(options[:locales] || Mobility.available_locales).map(&:to_sym)
+        options[:attached_options] ||= {}
+        options[:attachment_fallbacks] = build_fallbacks(options[:attachment_fallbacks])
+      end
+
+      # Locale-suffixed attachment name, rejecting locales this attribute was not configured
+      # for. Shared by the read path and by the eager-loading scopes, so both fail the same way
+      # rather than the scope leaking an ActiveRecord::AssociationNotFoundError about a
+      # generated association name.
+      def attachment_name_for(attribute, locale)
+        normalized = Mobility.normalize_locale(locale)
+        return "#{attribute}_#{normalized}" if normalized_locales.include?(normalized)
+
+        raise Error, "#{model_class.name} has no translated #{attribute} attachment for " \
+                     "locale #{locale.inspect}. Configured locales: " \
+                     "#{options[:locales].map(&:to_s).join(", ")}."
+      end
+
+      def configured_locale?(locale)
+        normalized_locales.include?(Mobility.normalize_locale(locale))
+      end
+
+      # Mobility's query plugin asks the backend for an Arel node so it can build a predicate.
+      # An attachment is a row in active_storage_attachments, not a comparable column value, so
+      # there is nothing meaningful to compare. Fail with an explanation rather than the
+      # NoMethodError a missing `[]` would otherwise produce.
+      def [](name, _locale)
+        raise Error, "cannot query translated attachment #{name} -- attachments are not " \
+                     "comparable values. Query ActiveStorage::Attachment directly, filtering " \
+                     "on name (for example \"#{name}_#{Mobility.normalize_locale}\")."
+      end
+
+      def normalized_locales
+        @normalized_locales ||= options[:locales].map { |locale| Mobility.normalize_locale(locale) }
+      end
+
+      private
+
+      def build_fallbacks(option)
+        case option
+        when true then FallbackChain.new({})
+        when Hash then FallbackChain.new(option)
+        else false
+        end
+      end
+    end
+
+    # Resolves a locale to the chain of locales to try, in order.
+    #
+    # Mirrors Mobility's own fallbacks plugin: an explicit map is honoured first, then I18n's
+    # configured fallbacks when the application has them enabled, and the default locale always
+    # terminates the chain. Resolved on each read so that changes to +I18n.default_locale+ or
+    # +I18n.fallbacks+ are picked up.
+    class FallbackChain
+      def initialize(map)
+        @fallbacks = I18n::Locale::Fallbacks.new(map)
+      end
+
+      def [](locale)
+        chain = @fallbacks[locale]
+        chain |= I18n.fallbacks[locale] if I18n.respond_to?(:fallbacks)
+        chain | [I18n.default_locale]
+      end
+    end
+
+    # Returns the Active Storage proxy for +locale+.
+    #
+    # Always returns a proxy, never nil, so that +record.document.attach(...)+ works on a
+    # record with nothing attached yet. Falls back to another locale only when the attribute
+    # was configured with fallbacks and the current locale has nothing attached.
+    #
+    # @param [Symbol] locale
+    # @return [ActiveStorage::Attached::One, ActiveStorage::Attached::Many]
+    def read(locale, fallback: true, **kwargs)
+      proxy = attached(locale)
+      return proxy if proxy.attached?
+
+      # Mobility's convention: an explicitly requested locale never falls back.
+      return proxy if fallback == false || kwargs[:locale]
+
+      fallback_locale = fallback_chain(locale, fallback).find do |candidate|
+        configured?(candidate) && attached(candidate).attached?
+      end
+      return proxy unless fallback_locale
+
+      # Reads resolve through the fallback locale; writes stay in the requested locale.
+      fallback_attached_class.new(attachment_name(locale), model, attachment_name(fallback_locale))
+    end
+
+    # Stages the attachment change for +locale+.
+    #
+    # Deliberately mutates +attachment_changes+ rather than calling +attach+.
+    # +ActiveStorage::Attached::One#attach+ is implemented as
+    # +record.public_send("document_en=", attachable)+, and Mobility's locale accessors take
+    # precedence over Active Storage's generated writer -- so calling +attach+ here would
+    # re-enter this same method. Writing the change directly makes both entry paths converge.
+    def write(locale, value, **)
+      name = attachment_name(locale)
+      model.attachment_changes[name] = build_change(name, value)
+      value
+    end
+
+    # Whether the attribute has an attachment in +locale+ (honouring fallbacks).
+    def present?(locale, **options)
+      read(locale, **options).attached?
+    end
+
+    # Yields each configured locale that actually has an attachment.
+    def each_locale
+      options[:locales].each { |locale| yield locale if attached(locale).attached? }
+    end
+
+    # The Active Storage proxy for +locale+, without any fallback handling.
+    def attached(locale)
+      @attached ||= {}
+      @attached[Mobility.normalize_locale(locale)] ||=
+        attached_class.new(attachment_name(locale), model)
+    end
+
+    private
+
+    def attachment_name(locale)
+      self.class.attachment_name_for(attribute, locale)
+    end
+
+    def configured?(locale)
+      self.class.configured_locale?(locale)
+    end
+
+    # +fallback: :fr+ or +fallback: [:fr, :es]+ overrides the configured chain for one read.
+    #
+    # An attribute that declares no fallbacks cannot be talked into one by a read option, so a
+    # +fallbacks: false+ declaration is enforceable: otherwise any reader that forwards
+    # caller-controlled options (a serializer, a GraphQL resolver) would become a cross-locale
+    # read. This matches Mobility, whose fallbacks plugin is inert when +fallbacks: false+.
+    def fallback_chain(locale, fallback)
+      fallbacks = options[:attachment_fallbacks]
+      return [] unless fallbacks
+      return Array(fallback) unless fallback == true
+
+      fallbacks[locale]
+    end
+  end
+end

data/lib/mobility_active_storage/fallback_attached.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module MobilityActiveStorage
+  # Attached proxies used when a read resolves through a fallback locale.
+  #
+  # Reads (+attached?+, +filename+, +url+, iteration) resolve to the fallback locale's
+  # attachment, but every write -- +attach+, +purge+, +purge_later+, +detach+ -- stays bound to
+  # the locale actually being read. Without that split, +product.document.attach(file)+ under a
+  # fallback would overwrite the fallback locale's file instead of creating one for the
+  # current locale.
+  #
+  # The classes are built lazily: Active Storage's classes are autoloaded by its engine, which
+  # has not necessarily run at the point this gem is required from a Gemfile.
+  module FallbackAttached
+    # Guards the lazy build. Two threads racing here would both +const_set+, emitting an
+    # "already initialized constant" warning and handing callers structurally distinct classes,
+    # which would then fail each other's +is_a?+ checks.
+    BUILD_MUTEX = Mutex.new
+
+    class << self
+      def one
+        @one || BUILD_MUTEX.synchronize { @one ||= const_set(:One, build_one) }
+      end
+
+      def many
+        @many || BUILD_MUTEX.synchronize { @many ||= const_set(:Many, build_many) }
+      end
+
+      private
+
+      def build_one
+        build(::ActiveStorage::Attached::One) do
+          # The fallback locale's attachment stands in when this locale has none.
+          def attachment
+            own.attachment || record.public_send(:"#{fallback_name}_attachment")
+          end
+        end
+      end
+
+      def build_many
+        build(::ActiveStorage::Attached::Many) do
+          def attachments
+            own.attachments.presence || record.public_send(:"#{fallback_name}_attachments")
+          end
+
+          def blobs
+            own.blobs.presence || record.public_send(:"#{fallback_name}_blobs")
+          end
+        end
+      end
+
+      def build(plain_class, &reads)
+        Class.new(plain_class) do
+          attr_reader :fallback_name
+
+          define_method(:initialize) do |name, record, fallback_name|
+            super(name, record)
+            @fallback_name = fallback_name
+          end
+
+          # This locale as an ordinary Active Storage proxy. Writes delegate here so that
+          # Rails' own logic runs, bound to this locale's attachment name.
+          define_method(:own) { plain_class.new(name, record) }
+
+          def attach(*attachables) = own.attach(*attachables)
+          def purge = own.purge
+          def purge_later = own.purge_later
+          def detach = own.detach
+
+          class_eval(&reads)
+        end
+      end
+    end
+  end
+end

data/lib/mobility_active_storage/many_backend.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "backend_methods"
+
+module MobilityActiveStorage
+  # Mobility backend for a translated collection of Active Storage attachments.
+  #
+  # @example
+  #   class Product < ApplicationRecord
+  #     extend Mobility
+  #     translates :photos, backend: :active_storage_many
+  #   end
+  #
+  #   product.photos.attach(first, second)
+  #   Mobility.with_locale(:fr) { product.photos.attach(other) }
+  class ManyBackend
+    include Mobility::Backend
+    include BackendMethods
+
+    setup do |attributes, options, backend_class|
+      attributes.each do |attribute|
+        options[:locales].each do |locale|
+          has_many_attached :"#{attribute}_#{Mobility.normalize_locale(locale)}",
+                            **options[:attached_options]
+        end
+
+        scope :"with_attached_#{attribute}", lambda {
+          name = backend_class.attachment_name_for(attribute, Mobility.locale)
+          includes("#{name}_attachments": :blob)
+        }
+
+        define_method(:"#{attribute}_locales") { mobility_backends[attribute].locales }
+
+        # An attachment proxy is not a serialisable value, and Rails does not put one in
+        # `attributes` either. Installed here rather than in the macro so that declaring
+        # this backend directly through `translates` is covered too.
+        AttributeMethodsExclusion.install(self, attribute)
+      end
+    end
+
+    private
+
+    def attached_class
+      ActiveStorage::Attached::Many
+    end
+
+    def fallback_attached_class
+      FallbackAttached.many
+    end
+
+    # Mirrors the writer that has_many_attached generates, including carrying pending uploads
+    # across successive assignments so `attach` can append to an unsaved record.
+    def build_change(name, value)
+      attachables = Array(value).compact_blank
+
+      return ActiveStorage::Attached::Changes::DeleteMany.new(name, model) if attachables.none?
+
+      ActiveStorage::Attached::Changes::CreateMany.new(
+        name, model, attachables,
+        pending_uploads: model.attachment_changes[name].try(:pending_uploads)
+      )
+    end
+  end
+end

data/lib/mobility_active_storage/model.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module MobilityActiveStorage
+  # Class macros mixed into ActiveRecord::Base.
+  module Model
+    # Declares a single translated attachment.
+    #
+    #   class Product < ApplicationRecord
+    #     has_one_translated_attached :document
+    #     has_one_translated_attached :manual, fallbacks: true, service: :s3
+    #   end
+    #
+    # @param name [Symbol] attribute name
+    # @param fallbacks [Boolean, Hash] +true+ to fall back through I18n's chain, or an explicit
+    #   hash such as <tt>{ fr: :en }</tt>. Defaults to no fallback.
+    # @param locales [Array<Symbol>, nil] locales to declare attachments for. Defaults to
+    #   +Mobility.available_locales+ at the time the class body runs.
+    # @param attached_options [Hash] forwarded to +has_one_attached+ (+:service+,
+    #   +:strict_loading+, +:dependent+).
+    def has_one_translated_attached(name, fallbacks: false, locales: nil, **attached_options)
+      translated_attachment(name, :active_storage, fallbacks, locales, attached_options)
+    end
+
+    # Declares a translated collection of attachments. Options match
+    # {#has_one_translated_attached}; +attached_options+ is forwarded to +has_many_attached+.
+    def has_many_translated_attached(name, fallbacks: false, locales: nil, **attached_options)
+      translated_attachment(name, :active_storage_many, fallbacks, locales, attached_options)
+    end
+
+    # Attribute names declared through the attachment macros, including any inherited from a
+    # superclass. Used to keep attachments out of the hashes Mobility's attribute_methods plugin
+    # builds; see {AttributeMethodsExclusion}.
+    def translated_attachment_attribute_names
+      @translated_attachment_attribute_names ||=
+        if superclass.respond_to?(:translated_attachment_attribute_names)
+          superclass.translated_attachment_attribute_names.dup
+        else
+          []
+        end
+    end
+
+    private
+
+    def translated_attachment(name, backend, fallbacks, locales, attached_options)
+      extend Mobility unless singleton_class.include?(Mobility)
+
+      enabled = enabled_mobility_plugins
+
+      translates name, **{
+        backend: backend,
+        locales: locales,
+        attachment_fallbacks: fallbacks,
+        attached_options: attached_options
+      }.merge(plugin_overrides(locales, enabled))
+    end
+
+    # Mobility plugins that assume a scalar value, and so must be turned off per attribute.
+    # Only keys for plugins actually enabled are returned: Mobility raises InvalidOptionKey for
+    # an option belonging to a plugin that is not loaded.
+    def plugin_overrides(locales, enabled)
+      overrides = {}
+
+      # The fallbacks plugin consumes the `fallback:` read option before the backend sees it,
+      # and triggers only on a nil read -- but an attachment reader must always return a proxy.
+      # This gem implements attachment fallbacks itself instead.
+      overrides[:fallbacks] = false if enabled.include?(:fallbacks)
+
+      # The cache plugin would memoize a proxy that was resolved through a fallback, so a later
+      # attach in the current locale would keep returning the fallback locale's file.
+      overrides[:cache] = false if enabled.include?(:cache)
+
+      # Dirty tracking compares scalar values; attachment proxies are not comparable.
+      overrides[:dirty] = false if enabled.include?(:dirty)
+
+      # Keep locale accessors in step with the locales we actually declared attachments for.
+      overrides[:locale_accessors] = locales if locales && enabled.include?(:locale_accessors)
+
+      overrides
+    end
+
+    def enabled_mobility_plugins
+      Mobility.translations_class.included_plugins.map { |plugin| Mobility::Plugins.lookup_name(plugin) }
+    end
+  end
+end

data/lib/mobility_active_storage/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MobilityActiveStorage
+  VERSION = "0.1.0"
+end

data/lib/mobility_active_storage.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "mobility"
+require "active_support"
+
+require_relative "mobility_active_storage/version"
+
+module MobilityActiveStorage
+  class Error < StandardError; end
+end
+
+require_relative "mobility_active_storage/attribute_methods_exclusion"
+require_relative "mobility_active_storage/fallback_attached"
+require_relative "mobility_active_storage/backend"
+require_relative "mobility_active_storage/many_backend"
+require_relative "mobility_active_storage/model"
+
+Mobility::Backends.register_backend(:active_storage, MobilityActiveStorage::Backend)
+Mobility::Backends.register_backend(:active_storage_many, MobilityActiveStorage::ManyBackend)
+
+ActiveSupport.on_load(:active_record) do
+  extend MobilityActiveStorage::Model
+end

data/sig/mobility_active_storage.rbs

@@ -0,0 +1,49 @@
+module MobilityActiveStorage
+  VERSION: String
+
+  class Error < StandardError
+  end
+
+  # Class macros mixed into ActiveRecord::Base.
+  module Model
+    def has_one_translated_attached: (
+      Symbol name,
+      ?fallbacks: bool | Hash[Symbol, Symbol | Array[Symbol]],
+      ?locales: Array[Symbol]?,
+      **untyped attached_options
+    ) -> void
+
+    def has_many_translated_attached: (
+      Symbol name,
+      ?fallbacks: bool | Hash[Symbol, Symbol | Array[Symbol]],
+      ?locales: Array[Symbol]?,
+      **untyped attached_options
+    ) -> void
+  end
+
+  module BackendMethods
+    def read: (Symbol locale, ?fallback: bool | Symbol | Array[Symbol], **untyped) -> untyped
+    def write: (Symbol locale, untyped value, **untyped) -> untyped
+    def present?: (Symbol locale, **untyped) -> bool
+    def each_locale: () { (Symbol) -> void } -> void
+    def attached: (Symbol locale) -> untyped
+
+    class FallbackChain
+      def initialize: (Hash[Symbol, untyped] map) -> void
+      def []: (Symbol locale) -> Array[Symbol]
+    end
+  end
+
+  class Backend
+    include BackendMethods
+  end
+
+  class ManyBackend
+    include BackendMethods
+  end
+
+  module FallbackAttached
+    def self.one: () -> Class
+    def self.many: () -> Class
+  end
+end

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: mobility_active_storage
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Glen Barnes
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.2.3.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.2.3.2
+- !ruby/object:Gem::Dependency
+  name: activestorage
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.2.3.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.2.3.2
+- !ruby/object:Gem::Dependency
+  name: mobility
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: |
+  Adds has_one_translated_attached and has_many_translated_attached to Active Record models,
+  letting a single attachment name hold a different file per locale via Mobility. Requires no
+  migration: each locale is stored as an ordinary Active Storage attachment whose name carries
+  the locale suffix.
+email:
+- barnaclebarnes@mac.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/mobility_active_storage.rb
+- lib/mobility_active_storage/attribute_methods_exclusion.rb
+- lib/mobility_active_storage/backend.rb
+- lib/mobility_active_storage/backend_methods.rb
+- lib/mobility_active_storage/fallback_attached.rb
+- lib/mobility_active_storage/many_backend.rb
+- lib/mobility_active_storage/model.rb
+- lib/mobility_active_storage/version.rb
+- sig/mobility_active_storage.rbs
+homepage: https://github.com/barnaclebarnes/mobility_active_storage
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/barnaclebarnes/mobility_active_storage
+  changelog_uri: https://github.com/barnaclebarnes/mobility_active_storage/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.17
+specification_version: 4
+summary: Translated Active Storage attachments for Mobility.
+test_files: []