activestorage-multi_node_disk 0.1.0

data/lib/active_storage/multi_node_disk/audit_log.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module MultiNodeDisk
+    # One audit entry per request the endpoint answered (served, refused or
+    # deleted) and per remote fetch or delete this node made, as one JSON
+    # document (schema VERSION) to the configured sink:
+    #
+    # - :file (default): a JSON line appended to config.audit_path;
+    # - :table: an Audit row (after the host ran the generator's migration);
+    # - :none: nothing; or any callable, given the entry.
+    #
+    # The same entry is instrumented as `audit.multi_node_disk`. It never
+    # holds a token, file contents or a signed URL. A sink that fails is
+    # logged and never fails the request.
+    module AuditLog
+      VERSION = 1
+
+      # @param entry [Hash] action, result, status, key and the rest
+      # @param request [ActionDispatch::Request, nil] the request answered, if any
+      # @param requester [Hash, nil] who the request is for (else the current one)
+      # @return [Hash] the entry written
+      def self.record(entry, request: nil, requester: MultiNodeDisk.current_requester)
+        config = MultiNodeDisk.config
+        document = {v: VERSION, at: Time.now.utc.iso8601(3)}.merge(entry)
+        document[:requester] = requester || config.audit_requester&.call(request)
+        document[:context] = config.audit_context&.call(request, document)
+        document = document.compact.as_json
+
+        MultiNodeDisk.instrument(:audit, document)
+        write(config.audit, document)
+        document
+      end
+
+      def self.write(sink, document)
+        case sink.to_s
+        when "none" then nil
+        when "file" then FileSink.instance.write(MultiNodeDisk.config.audit_path, document)
+        when "table" then Audit.create!(payload: document)
+        else sink.call(document)
+        end
+      rescue => error
+        Rails.logger&.error("[ActiveStorage::MultiNodeDisk] audit not written (#{error.class}: #{error.message})")
+      end
+      private_class_method :write
+    end
+  end
+end

data/lib/active_storage/multi_node_disk/configuration.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module ActiveStorage
+  module MultiNodeDisk
+    # The hooks a host may change. Each default is what a plain Rails 8.1 app
+    # would do; a host sets only what differs, in one initializer:
+    #
+    #   ActiveStorage::MultiNodeDisk.configure do |config|
+    #     config.url_for = ->(node, key) { "https://#{node}:8443#{ActiveStorage::MultiNodeDisk.mount_path}/blobs/#{key}" }
+    #   end
+    #
+    # The engine validates and freezes it when the app has booted; threads
+    # then share it read-only.
+    class Configuration
+      # Hooks that must be callables (the security hooks among them: a
+      # static `true` must never authenticate).
+      CALLABLES = %i[url_for authenticate error_mapper].freeze
+      # Hooks that may be a value or a callable.
+      VALUES = %i[current_node nodes token token_for].freeze
+      TIMEOUTS = %i[open_timeout read_timeout].freeze
+      OPTIONS = (CALLABLES + VALUES + TIMEOUTS + %i[auth allowed_ips http_client hop_header requester_header draw_routes delete_mode delete_job_queue delete_job_class audit audit_path audit_context audit_requester table_name_prefix]).freeze
+      AUTH_MODES = %i[none token ip].freeze
+      DELETE_MODES = %i[sync job].freeze
+      AUDIT_SINKS = %i[none file table].freeze
+      # Longest table_name_prefix: "<prefix>audits_seq" must fit in 30.
+      MAX_PREFIX = 30 - "audits_seq".length
+      HEADER_NAME = /\A[A-Za-z0-9-]+\z/
+
+      # @return [String, #call] this node: `-> String` (storage.yml `node:` wins)
+      attr_accessor :current_node
+      # @return [Array<String>, #call] every node: `-> Array` (storage.yml `nodes:` wins)
+      attr_accessor :nodes
+      # @return [#call] a node's URL for a file: `(node, key) -> String`, https only
+      attr_accessor :url_for
+      # @return [Symbol, Array<Symbol>] the endpoint's checks: :none (the
+      #   default: no check at all), :token, :ip, or [:ip, :token] (both)
+      attr_accessor :auth
+      # @return [Array<String>, nil] IPs and CIDRs for :ip (nil: every node's
+      #   addresses, resolved by DNS and refreshed every NodeAddresses::TTL)
+      attr_accessor :allowed_ips
+      # @return [String, #call] the shared token for :token: `-> String`
+      attr_accessor :token
+      # @return [String, #call] the token sent to a node: `(node, blob, action) -> String`
+      attr_accessor :token_for
+      # @return [#call] whether a token is a node's, for :token:
+      #   `(token, request) -> identity or nil` (nil refuses)
+      attr_accessor :authenticate
+      # @return [#call] `#call(method, url, headers:, node:, open_timeout:, read_timeout:) -> Response`;
+      #   called from several threads at once, so it must not share a connection
+      attr_accessor :http_client
+      # @return [String] the header that marks a node-to-node request
+      attr_accessor :hop_header
+      # @return [Numeric] seconds
+      attr_accessor :open_timeout, :read_timeout
+      # @return [#call] `(error) -> Exception`, raised in place of the gem's error
+      attr_accessor :error_mapper
+      # @return [Boolean] whether the gem mounts its endpoint at mount_path
+      attr_accessor :draw_routes
+      # @return [String] the header that carries the requester to another node
+      attr_accessor :requester_header
+      # @return [Symbol, #call] where audit entries go: :file (default),
+      #   :table, :none, or a callable given each entry
+      attr_accessor :audit
+      # @return [String, Pathname] the :file sink's file
+      attr_accessor :audit_path
+      # @return [#call, nil] more for each entry: `(request or nil, entry) -> Hash`
+      #   (the entry so far: action, key and the rest)
+      attr_accessor :audit_context
+      # @return [#call, nil] who it is for: `(request or nil) -> Hash`
+      #   (with_requester wins; the gem never reads it)
+      attr_accessor :audit_requester
+      # @return [String] the prefix of the gem's tables (the audit table)
+      attr_accessor :table_name_prefix
+      # @return [Symbol] how delete reaches the other nodes: :sync (inline,
+      #   raising Unavailable when one does not confirm) or :job (DeleteJob)
+      attr_accessor :delete_mode
+      # @return [String, Symbol, nil] DeleteJob's queue (nil: Active Storage's purge queue)
+      attr_accessor :delete_job_queue
+      # @return [String, Class, nil] a DeleteJob subclass (other retries)
+      attr_accessor :delete_job_class
+
+      def initialize
+        @current_node = -> { Socket.gethostname }
+        @nodes = nil
+        @url_for = ->(node, key) { "https://#{node}#{MultiNodeDisk.mount_path}/blobs/#{key}" }
+        @auth = :none
+        @allowed_ips = nil
+        @token = -> { MultiNodeDisk.credentials_token }
+        @token_for = ->(_node, _blob, _action) { MultiNodeDisk.config.resolve(:token) }
+        @authenticate = ->(token, _request) { :node if Configuration.token?(token) }
+        @http_client = NetHttpClient.new
+        @hop_header = "X-Multi-Node-Disk-Hop"
+        @open_timeout = 3
+        @read_timeout = 20
+        @error_mapper = ->(error) { error }
+        @draw_routes = true
+        @requester_header = "X-Multi-Node-Disk-Requester"
+        @audit = :file
+        @audit_path = Rails.root.join("tmp/multi_node_disk/audit.log")
+        @audit_context = nil
+        @audit_requester = nil
+        @table_name_prefix = "multi_node_disk_"
+        @delete_mode = :sync
+        @delete_job_queue = nil
+        @delete_job_class = nil
+      end
+
+      # The default authenticate: config.token (by default the credentials
+      # token), compared in constant time. No token configured: nobody.
+      #
+      # @param token [String, nil]
+      # @return [Boolean]
+      def self.token?(token)
+        expected = MultiNodeDisk.config.resolve(:token).to_s
+        expected.present? && token.present? && ActiveSupport::SecurityUtils.secure_compare(token, expected)
+      end
+
+      # @param auth [Symbol, String, Array]
+      # @return [Array<Symbol>] the modes
+      # @raise [ConfigurationError] for an unknown mode, none, or :none combined
+      def self.auth_modes(auth)
+        modes = Array(auth).map { |mode| mode.to_s.to_sym }.uniq
+        valid = modes.any? && (modes - AUTH_MODES).empty? && (modes == [:none] || !modes.include?(:none))
+        raise ConfigurationError, "ActiveStorage::MultiNodeDisk auth must be :none, :token, :ip or [:ip, :token] (got #{auth.inspect})" unless valid
+
+        modes
+      end
+
+      # @param list [Array<String>, nil]
+      # @return [Array<IPAddr>, nil]
+      # @raise [ConfigurationError] for an entry that is not an IP or CIDR
+      def self.ip_list(list)
+        return if list.nil?
+
+        Array(list).map { |entry| IPAddr.new(entry.to_s.strip) }
+      rescue IPAddr::Error
+        raise ConfigurationError, "ActiveStorage::MultiNodeDisk allowed_ips: #{list.inspect} holds an entry that is not an IP or CIDR"
+      end
+
+      # @param value [Object]
+      # @return [Boolean] a positive, finite number
+      def self.seconds?(value)
+        value.is_a?(Numeric) && value.positive? && value.finite?
+      end
+
+      # The option's value, called with the arguments when it is callable.
+      #
+      # @param option [Symbol]
+      # @return [Object]
+      def resolve(option, *args)
+        value = public_send(option)
+        value.respond_to?(:call) ? value.call(*args) : value
+      end
+
+      # @return [self]
+      # @raise [ConfigurationError] naming the first option that is wrong
+      def validate!
+        CALLABLES.each { |option| fail_option(option, "must respond to call") unless public_send(option).respond_to?(:call) }
+        %i[current_node token token_for].each { |option| string_or_callable!(option) }
+        Configuration.auth_modes(auth)
+        fail_option(:delete_mode, "must be :sync or :job") unless DELETE_MODES.include?(delete_mode.to_s.to_sym)
+        delete_job if delete_mode.to_s == "job"
+        Configuration.ip_list(allowed_ips)
+        fail_option(:nodes, "must be an Array or respond to call") unless nodes.nil? || nodes.is_a?(Array) || nodes.respond_to?(:call)
+        fail_option(:http_client, "must respond to call") unless http_client.respond_to?(:call)
+        %i[hop_header requester_header].each { |option| fail_option(option, "must be a header name") unless public_send(option).is_a?(String) && HEADER_NAME.match?(public_send(option)) }
+        %i[audit_context audit_requester].each { |option| fail_option(option, "must be nil or respond to call") unless public_send(option).nil? || public_send(option).respond_to?(:call) }
+        fail_option(:audit, "must be :file, :table, :none or respond to call") unless audit.respond_to?(:call) || AUDIT_SINKS.include?(audit.to_s.to_sym)
+        fail_option(:table_name_prefix, "must be a lowercase identifier prefix") unless table_name_prefix.is_a?(String) && table_name_prefix.match?(/\A[a-z][a-z0-9_]*\z/)
+        # "<prefix>audits_seq" (the sequence Oracle's adapter adds) within 30.
+        fail_option(:table_name_prefix, "must be at most #{MAX_PREFIX} characters (Oracle's 30-character names)") if table_name_prefix.length > MAX_PREFIX
+        TIMEOUTS.each { |option| fail_option(option, "must be a positive, finite number of seconds") unless Configuration.seconds?(public_send(option)) }
+        self
+      end
+
+      # The job for :job mode, loading Active Job and the gem's job.
+      #
+      # @return [Class]
+      # @raise [ConfigurationError] when Active Job is not available
+      def delete_job
+        begin
+          require "active_job"
+          require "active_storage/multi_node_disk/delete_job"
+        rescue LoadError => error
+          raise ConfigurationError, "ActiveStorage::MultiNodeDisk delete_mode :job needs Active Job (#{error.message})"
+        end
+        job = delete_job_class.is_a?(String) ? delete_job_class.constantize : (delete_job_class || DeleteJob)
+        fail_option(:delete_job_class, "must be ActiveStorage::MultiNodeDisk::DeleteJob or a subclass") unless job.is_a?(Class) && job <= DeleteJob
+        job
+      end
+
+      # A validated, frozen copy with some options replaced.
+      #
+      # @param overrides [Hash{Symbol => Object}]
+      # @return [Configuration]
+      def merge(**overrides)
+        unknown = overrides.keys - OPTIONS
+        raise ConfigurationError, "unknown option #{unknown.first}" if unknown.any?
+
+        dup.tap { |copy| overrides.each { |option, value| copy.public_send(:"#{option}=", value) } }.validate!.freeze
+      end
+
+      private
+
+      def string_or_callable!(option)
+        value = public_send(option)
+        fail_option(option, "must be a String or respond to call") unless value.is_a?(String) || value.respond_to?(:call)
+      end
+
+      def fail_option(option, problem)
+        raise ConfigurationError, "ActiveStorage::MultiNodeDisk config.#{option} #{problem}"
+      end
+    end
+  end
+end

data/lib/active_storage/multi_node_disk/configuration_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module MultiNodeDisk
+    # A hook is missing or of the wrong kind (raised at boot).
+    class ConfigurationError < StandardError; end
+  end
+end

data/lib/active_storage/multi_node_disk/delete_job.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module MultiNodeDisk
+    # The other nodes' deletes, when config.delete_mode is :job (the local
+    # copy is already gone). Idempotent: a node that answers 404 as itself
+    # has nothing left. Retried while a node does not confirm; a host
+    # changes the retries by subclassing (config.delete_job_class) and the
+    # queue with config.delete_job_queue. Loaded only in :job mode, so
+    # Active Job stays optional.
+    class DeleteJob < ActiveJob::Base
+      retry_on Unavailable, wait: :polynomially_longer, attempts: 10 do |job, error|
+        MultiNodeDisk.instrument(:delete_abandoned, key: job.arguments.second, nodes: error.nodes)
+      end
+
+      # @param service_name [String] the MultiNodeDisk service in storage.yml
+      # @param key [String]
+      # @param nodes [Array<String>] the nodes still to confirm
+      # @param requester [Hash, nil] who the delete was for (recorded again)
+      def perform(service_name, key, nodes, requester = nil)
+        service = ActiveStorage::Blob.services.fetch(service_name)
+        failed = MultiNodeDisk.with_requester(requester) { service.delete_elsewhere(key, nodes: nodes) }
+        raise Unavailable.new(nodes: failed, key: key, reason: "delete not confirmed") if failed.any?
+      end
+    end
+  end
+end

data/lib/active_storage/multi_node_disk/engine.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module MultiNodeDisk
+    # The endpoint other nodes call, isolated from the app: its controller,
+    # its routes and their helpers stay in this namespace. Mounted under
+    # Active Storage's own prefix (mount_path, by default
+    # /rails/active_storage/multi_node_disk), ahead of the app's routes so a
+    # catch-all cannot hide it; nothing is drawn at the app's root.
+    class Engine < ::Rails::Engine
+      isolate_namespace ActiveStorage::MultiNodeDisk
+
+      initializer "active_storage_multi_node_disk.routes" do |app|
+        app.routes.prepend do
+          if ActiveStorage::MultiNodeDisk.config.draw_routes
+            mount ActiveStorage::MultiNodeDisk::Engine => ActiveStorage::MultiNodeDisk.mount_path, :as => :active_storage_multi_node_disk
+          end
+        end
+      end
+
+      config.after_initialize { MultiNodeDisk.finalize! }
+    end
+  end
+end

data/lib/active_storage/multi_node_disk/fan_out.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module MultiNodeDisk
+    # Runs calls in parallel threads (at most MAX_THREADS at a time) under
+    # one deadline, and stops once the block says a result wins.
+    #
+    # 1. Each call runs in its own thread, inside the Rails executor. Calls
+    #    get everything from the caller: they must not touch the database or
+    #    host hooks, and a transport must be safe to call from several
+    #    threads at once.
+    # 2. Results arrive as calls finish; the block sees each one, on the
+    #    caller's thread.
+    # 3. The deadline starts here and covers the wait and the block; no call
+    #    starts after it. When it passes, or the block answers true, calls
+    #    still running are killed and joined within one shared JOIN_SECONDS
+    #    budget: their ensure blocks close what they opened; a thread still
+    #    alive after that is left to finish (it is already killed), and a
+    #    socket caught mid-connect is closed when it is collected.
+    # 4. Calls that never started (more nodes than threads, deadline gone)
+    #    have no result: the caller counts them as failed.
+    module FanOut
+      MAX_THREADS = 8
+      JOIN_SECONDS = 1
+
+      # @param calls [Hash{String => #call}] by node
+      # @param deadline [Numeric] seconds for the whole run
+      # @yieldparam node [String]
+      # @yieldparam result [Object, Exception] the call's value, or what it raised
+      # @yieldreturn [Boolean] true to stop
+      # @return [Hash{String => Object}] the results that arrived, by node
+      def self.run(calls, deadline:)
+        results = {}
+        pending = calls.to_a
+        running = {}
+        finished = Thread::Queue.new
+        stop_at = now + deadline
+
+        loop do
+          while running.size < MAX_THREADS && now < stop_at && (job = pending.shift)
+            running[job.first] = start(*job, finished)
+          end
+          break if running.empty?
+
+          remaining = stop_at - now
+          break unless remaining.positive? && (item = finished.pop(timeout: remaining))
+
+          node, result = item
+          running.delete(node)
+          results[node] = result
+          break if yield(node, result)
+        end
+        results
+      ensure
+        running&.each_value(&:kill)
+        cleanup_by = now + JOIN_SECONDS
+        running&.each_value { |thread| thread.join([cleanup_by - now, 0].max) }
+      end
+
+      def self.now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      def self.start(node, call, finished)
+        Thread.new do
+          Thread.current.report_on_exception = false
+          result = begin
+            Rails.application.executor.wrap { call.call }
+          rescue => error
+            error
+          end
+          finished << [node, result]
+        end
+      end
+      private_class_method :now, :start
+    end
+  end
+end

data/lib/active_storage/multi_node_disk/file_error.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module MultiNodeDisk
+    # What every file error carries, for triage: the nodes involved, the
+    # blob key and the file name.
+    module FileError
+      # @return [Array<String>]
+      attr_reader :nodes
+      # @return [String, nil]
+      attr_reader :key, :filename
+
+      # @param nodes [Array<String>, String, nil]
+      # @param key [String, nil]
+      # @param filename [String, nil]
+      # @param reason [String, nil] what the transport or the nodes said
+      def initialize(nodes: nil, key: nil, filename: nil, reason: nil)
+        @nodes = Array(nodes).map(&:to_s)
+        @key = key
+        @filename = filename&.to_s
+        super([describe, reason].compact.join(": "))
+      end
+
+      # @return [String] the nodes, for messages ("node-b and node-c")
+      def node
+        nodes.to_sentence.presence || "any node"
+      end
+
+      private
+
+      def file_label
+        filename.presence || key
+      end
+    end
+  end
+end

data/lib/active_storage/multi_node_disk/file_sink.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module ActiveStorage
+  module MultiNodeDisk
+    # The default audit sink: one JSON document per line, appended. A lock
+    # keeps this process's threads apart and flock keeps processes apart, so
+    # lines never interleave. Rotation is the host's (logrotate with
+    # copytruncate, or rename the file: the next write opens a new one).
+    class FileSink
+      # @return [FileSink] the process's sink
+      def self.instance
+        @instance ||= new
+      end
+
+      def initialize
+        @lock = Mutex.new
+      end
+
+      # @param path [String, Pathname]
+      # @param document [Hash]
+      def write(path, document)
+        line = "#{JSON.generate(document)}\n"
+        @lock.synchronize do
+          FileUtils.mkdir_p(File.dirname(path))
+          File.open(path, File::WRONLY | File::APPEND | File::CREAT, 0o640) do |file|
+            file.flock(File::LOCK_EX)
+            file.write(line)
+          ensure
+            file.flock(File::LOCK_UN)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/multi_node_disk/mismatch.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module MultiNodeDisk
+    # The bytes do not match the blob's size and checksum. An
+    # IntegrityError, as Active Storage raises.
+    class Mismatch < ActiveStorage::IntegrityError
+      include FileError
+
+      private
+
+      def describe = "#{file_label}: the bytes do not match the stored file (#{node})"
+    end
+  end
+end

data/lib/active_storage/multi_node_disk/net_http_client.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module ActiveStorage
+  module MultiNodeDisk
+    # The default transport: Net::HTTP, as Active Storage's own services
+    # use, with the system resolver. HTTPS verifies the certificate.
+    class NetHttpClient
+      METHODS = {get: Net::HTTP::Get, head: Net::HTTP::Head, delete: Net::HTTP::Delete}.freeze
+
+      # @param method [Symbol] :get, :head or :delete
+      # @param url [String]
+      # @param headers [Hash{String => String}]
+      # @param node [String] the node addressed (unused: the URL names it; a host client may pin to it)
+      # @param open_timeout [Numeric]
+      # @param read_timeout [Numeric]
+      # @return [Response]
+      def call(method, url, headers:, node:, open_timeout:, read_timeout:)
+        uri = URI(url)
+        request = METHODS.fetch(method).new(uri)
+        headers.each { |name, value| request[name] = value }
+        answer = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: open_timeout, read_timeout: read_timeout) do |http|
+          http.request(request)
+        end
+        Response.new(answer.code.to_i, answer.body.to_s, answer.each_header.to_h)
+      end
+    end
+  end
+end

data/lib/active_storage/multi_node_disk/node_addresses.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require "resolv"
+
+module ActiveStorage
+  module MultiNodeDisk
+    # The IP addresses of the nodes, for the endpoint's :ip check: resolved
+    # by DNS (a node may also be written as an IP), kept for TTL seconds,
+    # then resolved again. A node that fails to resolve keeps its last known
+    # addresses. One lock guards the cache, so threads share it safely.
+    class NodeAddresses
+      TTL = 60
+
+      Entry = Struct.new(:addresses, :expires_at)
+
+      # @param resolver [#getaddresses] Resolv by default
+      # @param clock [#call] monotonic seconds
+      def initialize(resolver: Resolv, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+        @resolver = resolver
+        @clock = clock
+        @entries = {}
+        @lock = Mutex.new
+      end
+
+      # @param nodes [Array<String>]
+      # @return [Array<IPAddr>]
+      def for(nodes)
+        @lock.synchronize { nodes.flat_map { |node| entry_for(node).addresses } }
+      end
+
+      private
+
+      def entry_for(node)
+        now = @clock.call
+        entry = @entries[node]
+        return entry if entry && entry.expires_at > now
+
+        @entries[node] = Entry.new(resolve(node) || entry&.addresses || [], now + TTL)
+      end
+
+      def resolve(node)
+        found = @resolver.getaddresses(node).map { |address| IPAddr.new(address) }
+        found.presence
+      rescue Resolv::ResolvError, IPAddr::Error, SocketError
+        nil
+      end
+    end
+  end
+end

data/lib/active_storage/multi_node_disk/not_here.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module MultiNodeDisk
+    # No node has the file: this disk does not, and every other node
+    # answered "not here" as itself. A FileNotFoundError, as Disk raises.
+    class NotHere < ActiveStorage::FileNotFoundError
+      include FileError
+
+      private
+
+      def describe = "#{file_label} is not on #{node}"
+    end
+  end
+end

data/lib/active_storage/multi_node_disk/requester.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module MultiNodeDisk
+    # Who a file operation is for, set around work that serves no request
+    # (a job): `ActiveStorage::MultiNodeDisk.with_requester(...) { blob.open { } }`.
+    # Kept per thread or fiber (Rails' isolation level), so concurrent work
+    # never shares it. The gem records and forwards it; it never reads it.
+    module Requester
+      KEY = :active_storage_multi_node_disk_requester
+      # Largest requester header sent or read, in bytes.
+      MAX_BYTES = 1024
+
+      # @return [Hash, nil]
+      def self.current
+        ActiveSupport::IsolatedExecutionState[KEY]
+      end
+
+      # @param requester [Hash, nil]
+      def self.with(requester)
+        previous = current
+        ActiveSupport::IsolatedExecutionState[KEY] = requester
+        yield
+      ensure
+        ActiveSupport::IsolatedExecutionState[KEY] = previous
+      end
+
+      # @param requester [Hash, nil]
+      # @return [String, nil] JSON for the header; nil when absent or too large
+      def self.encode(requester)
+        return if requester.nil?
+
+        json = JSON.generate(requester.as_json)
+        json if json.bytesize <= MAX_BYTES
+      end
+
+      # @param header [String, nil]
+      # @return [Hash, nil] the requester another node sent; nil when absent,
+      #   too large or not a JSON object
+      def self.decode(header)
+        return if header.blank? || header.bytesize > MAX_BYTES
+
+        found = JSON.parse(header)
+        found if found.is_a?(Hash)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/active_storage/multi_node_disk/response.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module MultiNodeDisk
+    # What an http_client returns: the status, the body and the headers
+    # (names in any case).
+    Response = Struct.new(:status, :body, :headers) do
+      # @param name [String]
+      # @return [String, nil]
+      def header(name)
+        wanted = name.downcase
+        Array((headers || {}).find { |key, _| key.to_s.downcase == wanted }&.last).first
+      end
+    end
+  end
+end