activestorage-multi_node_disk 0.1.0

data/lib/active_storage/multi_node_disk/test_helper.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "rack/mock"
+require "tmpdir"
+require "fileutils"
+
+module ActiveStorage
+  module MultiNodeDisk
+    # Fake nodes for a host's specs: no network, the gem's real endpoint.
+    #
+    #   include ActiveStorage::MultiNodeDisk::TestHelper
+    #
+    #   node_b = multi_node_disk_node("node-b")
+    #   multi_node_disk_move(blob, to: node_b)
+    #   multi_node_disk_cluster("node-b" => node_b, "node-c" => :missing) do |requests|
+    #     expect(blob.download).to eq(bytes)
+    #   end
+    module TestHelper
+      # A node's answer when no service stands for it in the cluster.
+      BEHAVIOURS = %i[missing timeout down wrong].freeze
+
+      # Another node: a MultiNodeDiskService with its own disk root, named
+      # like the app's service.
+      #
+      # @param node [String]
+      # @param root [String]
+      # @return [ActiveStorage::Service::MultiNodeDiskService]
+      def multi_node_disk_node(node, root: Dir.mktmpdir("multi_node_disk-#{node}-"))
+        here = MultiNodeDisk.service
+        ActiveStorage::Service::MultiNodeDiskService.new(root: root, node: node, nodes: here.nodes).tap { |there| there.name = here.name }
+      end
+
+      # Moves a blob's file from this node's disk to another node's.
+      #
+      # @param blob [ActiveStorage::Blob]
+      # @param to [ActiveStorage::Service::MultiNodeDiskService]
+      def multi_node_disk_move(blob, to:)
+        target = to.path_for(blob.key)
+        FileUtils.mkdir_p(File.dirname(target))
+        FileUtils.mv(blob.service.path_for(blob.key), target)
+        to
+      end
+
+      # Runs the block with the other nodes answering in process: a service
+      # through the gem's endpoint, :missing with a 404 as itself, :wrong
+      # with bytes that are not the file, :timeout by never answering, :down
+      # by refusing the connection; a node not listed is :down.
+      #
+      # @param nodes [Hash{String => ActiveStorage::Service::MultiNodeDiskService, Symbol}]
+      # @param remote_addr [String] the caller's IP as the endpoint sees it
+      # @yieldparam requests [Array<Hash>] method, node, url and header names (never values)
+      def multi_node_disk_cluster(nodes = {}, remote_addr: "127.0.0.1", **named, &block)
+        requests = []
+        client = Cluster.new(nodes.merge(named.transform_keys(&:to_s)), remote_addr, requests)
+        MultiNodeDisk.with_config(http_client: client) { block.call(requests) }
+      end
+
+      # The fake transport behind multi_node_disk_cluster.
+      class Cluster
+        def initialize(nodes, remote_addr, requests)
+          @nodes = nodes
+          @remote_addr = remote_addr
+          @requests = requests
+          @lock = Mutex.new
+        end
+
+        def call(method, url, headers:, node:, open_timeout:, read_timeout:)
+          @lock.synchronize { @requests << {method: method, node: node, url: url, headers: headers.keys} }
+          behaviour = @nodes.fetch(node, :down)
+          case behaviour
+          when :missing then Response.new(404, "", {NODE_HEADER => node})
+          when :wrong then Response.new(200, "not the file", {NODE_HEADER => node})
+          when :timeout then sleep
+          when :down then raise Errno::ECONNREFUSED, node
+          else serve(behaviour, method, url, headers)
+          end
+        end
+
+        private
+
+        def serve(service, method, url, headers)
+          # The engine's own path: whatever precedes the mount (a public
+          # prefix such as /app) is the host's proxy's business.
+          path = URI(url).path.sub(/\A.*?#{Regexp.escape(MultiNodeDisk.mount_path)}/, "")
+          env = Rack::MockRequest.env_for(path, :method => method.to_s.upcase, "REMOTE_ADDR" => @remote_addr)
+          headers.each { |name, value| env["HTTP_#{name.upcase.tr("-", "_")}"] = value }
+          env[SERVICE_ENV_KEY] = service
+          status, response_headers, body = Engine.call(env)
+          content = +""
+          body.each { |part| content << part }
+          body.close if body.respond_to?(:close)
+          Response.new(status, content, response_headers.to_h)
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/multi_node_disk/unavailable.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module MultiNodeDisk
+    # Some node that may hold the file did not answer as itself: a
+    # connection error, a timeout, a 5xx, a refusal, or another node
+    # answering in its place. Worth retrying.
+    class Unavailable < ActiveStorage::Error
+      include FileError
+
+      private
+
+      def describe = "#{node} is not answering"
+    end
+  end
+end

data/lib/active_storage/multi_node_disk/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module MultiNodeDisk
+    VERSION = "0.1.0"
+  end
+end

data/lib/active_storage/multi_node_disk.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "socket"
+require "rails"
+require "active_storage"
+require "active_storage/engine"
+require "action_controller"
+require "zeitwerk"
+
+loader = Zeitwerk::Loader.for_gem_extension(ActiveStorage)
+# Active Storage's Configurator requires the service by path
+# (`service: MultiNodeDisk` in storage.yml), as it does S3Service.
+loader.ignore("#{__dir__}/service")
+# Active Job is optional: the job loads only in :job delete mode.
+loader.ignore("#{__dir__}/multi_node_disk/delete_job.rb")
+loader.setup
+# Also by constant, for code that names the class before storage.yml built it.
+ActiveStorage::Service.autoload(:MultiNodeDiskService, "active_storage/service/multi_node_disk_service")
+
+module ActiveStorage
+  # Helpers for ActiveStorage::Service::MultiNodeDiskService, a Disk service
+  # for apps on several nodes, each with its own disk.
+  #
+  # 1. Upload: Disk writes the file to this node's disk.
+  # 2. Read, exist?: this disk first; else every other node is asked in
+  #    parallel (FanOut), and the first answer that matches the blob's size
+  #    and checksum wins.
+  # 3. Delete: this disk, then every other node.
+  # 4. A node's endpoint (BlobsController) answers from its own disk only,
+  #    so a hop never fans out.
+  #
+  # Defaults are plain Rails 8.1; a host changes them once, in an
+  # initializer (`ActiveStorage::MultiNodeDisk.configure`).
+  module MultiNodeDisk
+    # Every endpoint response names the node that answered.
+    NODE_HEADER = "X-Multi-Node-Disk-Node"
+    # Rack env key naming the service an in-process request is answered from
+    # (TestHelper). HTTP cannot set it: header keys are HTTP_*.
+    SERVICE_ENV_KEY = "active_storage_multi_node_disk.service"
+
+    class << self
+      # @return [ActiveStorage::MultiNodeDisk::Configuration]
+      def config
+        @config ||= Configuration.new
+      end
+
+      # Sets the hooks, in an initializer.
+      #
+      # @yieldparam config [ActiveStorage::MultiNodeDisk::Configuration]
+      # @raise [ConfigurationError] once the app has booted (frozen)
+      def configure
+        raise ConfigurationError, "configure runs in an initializer; the configuration is frozen after boot" if config.frozen?
+
+        yield config
+      end
+
+      # Validates and freezes the configuration (the engine, after boot),
+      # and checks storage.yml: at most one MultiNodeDisk service (the
+      # endpoint serves one disk root), with a node list.
+      #
+      # @param services [Hash] storage.yml, by service name
+      # @return [ActiveStorage::MultiNodeDisk::Configuration]
+      def finalize!(services = service_configurations)
+        check_services!(services)
+        return config if config.frozen?
+
+        config.validate!.freeze
+        warn_unprotected
+        config
+      end
+
+      # The cache of node addresses for the :ip check.
+      #
+      # @return [NodeAddresses]
+      def node_addresses
+        @node_addresses ||= NodeAddresses.new
+      end
+
+      attr_writer :node_addresses
+
+      # Where the endpoint is mounted: under Active Storage's routes prefix.
+      #
+      # @return [String]
+      def mount_path
+        "#{ActiveStorage.routes_prefix || "/rails/active_storage"}/multi_node_disk"
+      end
+
+      # Runs the block with some options replaced (tests).
+      #
+      # @param overrides [Hash{Symbol => Object}]
+      def with_config(**overrides)
+        previous = config
+        @config = previous.merge(**overrides)
+        yield
+      ensure
+        @config = previous
+      end
+
+      # The app's MultiNodeDisk service (storage.yml has at most one).
+      #
+      # @return [ActiveStorage::Service::MultiNodeDiskService, nil]
+      def service
+        name = service_configurations.find { |_, options| options.to_h.with_indifferent_access[:service].to_s == "MultiNodeDisk" }&.first
+        ActiveStorage::Blob.services.fetch(name) if name
+      end
+
+      # storage.yml, read as Active Storage reads it (which it does only
+      # when ActiveStorage::Blob first loads).
+      #
+      # @return [Hash]
+      def service_configurations
+        configured = Rails.configuration.active_storage.service_configurations
+        return configured.to_h if configured
+
+        file = Rails.root.join("config/storage/#{Rails.env}.yml")
+        file = Rails.root.join("config/storage.yml") unless file.exist?
+        file.exist? ? ActiveSupport::ConfigurationFile.parse(file).to_h : {}
+      end
+
+      # Runs the block on behalf of someone (a job's user): remote fetches and
+      # deletes in it record them, here and on the node that answers.
+      #
+      # @param requester [Hash, nil] e.g. {id:, label:, type:}; never a secret
+      def with_requester(requester, &)
+        Requester.with(requester, &)
+      end
+
+      # @return [Hash, nil] the requester with_requester set
+      def current_requester
+        Requester.current
+      end
+
+      # The shared node token from Rails credentials (`multi_node_disk.token`).
+      #
+      # @return [String, nil]
+      def credentials_token
+        Rails.application.credentials.dig(:multi_node_disk, :token).presence
+      end
+
+      # Instruments `<event>.multi_node_disk`. Payloads never carry a token.
+      #
+      # @param event [Symbol]
+      # @param payload [Hash]
+      def instrument(event, payload = {}, &)
+        ActiveSupport::Notifications.instrument("#{event}.multi_node_disk", payload, &)
+      end
+
+      private
+
+      # One warning at boot in production while the endpoint has no check.
+      def warn_unprotected
+        return unless Rails.env.production? && service&.auth_modes == [:none]
+
+        Rails.logger&.warn("[ActiveStorage::MultiNodeDisk] auth is :none: anyone who can reach #{mount_path} can read and delete files. Set config.auth to :token, :ip or [:ip, :token].")
+      end
+
+      def check_services!(services)
+        ours = services.to_h.select { |_, options| options.to_h.with_indifferent_access[:service].to_s == "MultiNodeDisk" }
+        raise ConfigurationError, "storage.yml has #{ours.size} MultiNodeDisk services (#{ours.keys.join(", ")}); one serves the endpoint" if ours.size > 1
+
+        ours.each do |name, options|
+          next unless options.to_h.with_indifferent_access[:nodes].nil? && config.nodes.nil?
+
+          raise ConfigurationError, "storage.yml #{name}: MultiNodeDisk needs nodes: (or config.nodes)"
+        end
+      end
+    end
+  end
+end
+
+# Loaded now, so Rails sees the engine (its controller, job and routes).
+require "active_storage/multi_node_disk/engine"

data/lib/active_storage/service/multi_node_disk_service.rb

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+require "active_storage/service/disk_service"
+require "active_storage/multi_node_disk"
+
+module ActiveStorage
+  # = Active Storage \Multi-Node \Disk \Service
+  #
+  # Disk for an app on several nodes, each with its own disk. A file stays on
+  # the disk of the node that received it. When a file is not on this disk,
+  # every other node is asked at once and the first copy that matches the
+  # blob wins; a delete deletes here and on every other node. Nothing is
+  # recorded, so existing blobs work as they are.
+  #
+  #   local:
+  #     service: MultiNodeDisk
+  #     root: <%= Rails.root.join("storage") %>
+  #     nodes: [app1.internal, app2.internal]
+  #
+  # Differs from Disk only in download, download_chunk, exist?, delete and
+  # open, each calling super for a file on this disk. Keys without a blob
+  # row (variants) and url, delete_prefixed and compose stay Disk's: local.
+  class Service::MultiNodeDiskService < Service::DiskService
+    LOCAL_DELETE = :active_storage_multi_node_disk_local_delete
+
+    # @param root [String] this node's storage directory, as Disk
+    # @param nodes [Array<String>, nil] every node, this one included (else config.nodes)
+    # @param node [String, nil] this node (else config.current_node)
+    # @param open_timeout [Numeric, nil] seconds (else config.open_timeout)
+    # @param read_timeout [Numeric, nil] seconds (else config.read_timeout)
+    # @param auth [Symbol, Array<Symbol>, nil] the endpoint's checks (else config.auth)
+    # @param allowed_ips [Array<String>, nil] for :ip (else config.allowed_ips)
+    def initialize(root:, public: false, nodes: nil, node: nil, open_timeout: nil, read_timeout: nil, auth: nil, allowed_ips: nil, **options)
+      super(root: root, public: public, **options)
+      @nodes_option = nodes
+      @node_option = node
+      @open_timeout = seconds!(:open_timeout, open_timeout)
+      @read_timeout = seconds!(:read_timeout, read_timeout)
+      @auth = auth && MultiNodeDisk::Configuration.auth_modes(auth)
+      @allowed_ips = MultiNodeDisk::Configuration.ip_list(allowed_ips)
+    end
+
+    # Disk's upload. A file that fails its checksum is deleted here only,
+    # never on the other nodes (Disk cleans up through #delete).
+    def upload(key, io, checksum: nil, **)
+      previous = ActiveSupport::IsolatedExecutionState[LOCAL_DELETE]
+      ActiveSupport::IsolatedExecutionState[LOCAL_DELETE] = true
+      super
+    ensure
+      ActiveSupport::IsolatedExecutionState[LOCAL_DELETE] = previous
+    end
+
+    # Disk's download. A whole file is checked against its blob; a file not
+    # on this disk comes from the first node with a matching copy.
+    def download(key, &block)
+      blob = remote_blob(key)
+      if blob.nil?
+        block ? super : verify_local(key, super)
+      elsif block
+        instrument(:streaming_download, key: key) { each_chunk(fetch(key, blob), &block) }
+      else
+        instrument(:download, key: key) { fetch(key, blob) }
+      end
+    end
+
+    def download_chunk(key, range)
+      blob = remote_blob(key)
+      return super unless blob
+
+      instrument(:download_chunk, key: key, range: range) { fetch(key, blob).byteslice(range) }
+    end
+
+    # Whether any node has the file (presence, as Disk: not its checksum).
+    def exist?(key)
+      blob = remote_blob(key)
+      return super unless blob
+
+      instrument(:exist, key: key) do |payload|
+        payload[:exist] = exist_elsewhere?(key, blob)
+      end
+    end
+
+    # Deletes the file here, then on every other node: inline in :sync mode
+    # (raising, as other services raise on a failed delete, once every node
+    # was tried), or through DeleteJob in :job mode.
+    #
+    # @raise [MultiNodeDisk::Unavailable] in :sync mode, naming the nodes that did not confirm
+    def delete(key)
+      super
+      return if ActiveSupport::IsolatedExecutionState[LOCAL_DELETE] || other_nodes.empty?
+
+      config = MultiNodeDisk.config
+      if config.delete_mode.to_s == "job"
+        queue = config.delete_job_queue || ActiveStorage.queues[:purge]
+        job = config.delete_job
+        requester = MultiNodeDisk.current_requester || config.audit_requester&.call(nil)
+        (queue ? job.set(queue: queue) : job).perform_later(name.to_s, key, other_nodes, requester&.as_json)
+      else
+        failed = delete_elsewhere(key)
+        raise config.error_mapper.call(MultiNodeDisk::Unavailable.new(nodes: failed, key: key, reason: "delete not confirmed")) if failed.any?
+      end
+    end
+
+    # Disk's open, with the integrity check raising the gem's Mismatch
+    # (through the host's error_mapper). Errors from the block are its own.
+    def open(key, checksum: nil, verify: true, **options)
+      super(key, checksum: checksum, verify: false, **options) do |file|
+        verify_file(key, file, checksum) if verify
+        yield file
+      end
+    end
+
+    # @return [String] this node's name
+    # @raise [MultiNodeDisk::ConfigurationError] when it resolves blank
+    def node
+      found = (@node_option.presence || MultiNodeDisk.config.resolve(:current_node)).to_s
+      raise MultiNodeDisk::ConfigurationError, "MultiNodeDisk: the current node resolved blank" if found.empty?
+
+      found
+    end
+
+    # @return [Array<String>] every node, this one included
+    # @raise [MultiNodeDisk::ConfigurationError] when no list is set
+    def nodes
+      list = @nodes_option.nil? ? MultiNodeDisk.config.resolve(:nodes) : @nodes_option
+      raise MultiNodeDisk::ConfigurationError, "MultiNodeDisk needs nodes: in storage.yml (or config.nodes)" if list.nil?
+
+      Array(list).map { |entry| entry.to_s.strip }.reject(&:empty?).uniq
+    end
+
+    # @return [Array<Symbol>] the endpoint's checks: [:none], [:token], [:ip] or [:ip, :token]
+    def auth_modes
+      @auth || MultiNodeDisk::Configuration.auth_modes(MultiNodeDisk.config.auth)
+    end
+
+    # @return [Array<IPAddr>] who may call the endpoint under :ip
+    def allowed_ips
+      @allowed_ips || MultiNodeDisk::Configuration.ip_list(MultiNodeDisk.config.allowed_ips) || MultiNodeDisk.node_addresses.for(nodes)
+    end
+
+    # @param key [String]
+    # @return [Boolean] the file is on this node's disk
+    def local?(key)
+      File.exist?(path_for(key))
+    end
+
+    # Sends a delete to some nodes (all the others by default).
+    #
+    # @param key [String]
+    # @param nodes [Array<String>]
+    # @return [Array<String>] the nodes that did not confirm
+    def delete_elsewhere(key, nodes: other_nodes)
+      started = clock
+      blob = ActiveStorage::Blob.find_by(key: key)
+      outcomes = ask(nodes, :delete, key, blob, :delete) do |answering, response|
+        (response.status == 204 && answered_by?(answering, response)) ? :deleted : :failed
+      end
+      MultiNodeDisk.instrument(:delete, key: key, outcomes: outcomes)
+      failed = outcomes.select { |_, outcome| outcome == :failed }.keys
+      audit(:remote_delete, failed.any? ? :error : :deleted, key, blob, outcomes, started)
+      failed
+    end
+
+    private
+
+    def other_nodes = nodes - [node]
+
+    def seconds!(option, value)
+      return if value.nil?
+      return value if MultiNodeDisk::Configuration.seconds?(value)
+
+      raise MultiNodeDisk::ConfigurationError, "MultiNodeDisk #{option}: in storage.yml must be a positive, finite number of seconds"
+    end
+
+    def open_timeout = @open_timeout || MultiNodeDisk.config.open_timeout
+
+    def read_timeout = @read_timeout || MultiNodeDisk.config.read_timeout
+
+    # The blob to look for elsewhere: nil when the file is here, or when no
+    # blob row has the key (a variant: Disk's own, local behaviour).
+    def remote_blob(key)
+      return if local?(key)
+
+      ActiveStorage::Blob.find_by(key: key)
+    end
+
+    # The first copy from another node that matches the blob.
+    def fetch(key, blob)
+      started = clock
+      winner = nil
+      outcomes = ask(other_nodes, :get, key, blob, :read) do |answering, response|
+        next :failed unless response.status == 200
+        next(winner = response.body) && :hit if matches?(blob, response.body)
+
+        MultiNodeDisk.instrument(:mismatch, key: key, node: answering, byte_size: response.body.to_s.bytesize)
+        :mismatch
+      end
+      MultiNodeDisk.instrument(:fetch, key: key, outcomes: outcomes)
+      audit(:fetch, fetch_result(winner, outcomes), key, blob, outcomes, started)
+      winner || raise_for(outcomes, key: key, filename: blob.filename)
+    end
+
+    def fetch_result(winner, outcomes)
+      return :served if winner
+      return :error if outcomes.value?(:failed)
+
+      outcomes.value?(:mismatch) ? :mismatch : :not_found
+    end
+
+    def audit(action, result, key, blob, outcomes, started)
+      MultiNodeDisk::AuditLog.record({
+        action: action, result: result, key: key, filename: blob&.filename&.to_s, byte_size: blob&.byte_size,
+        node: outcomes.key(:hit), from_node: node, outcomes: outcomes, auth: auth_modes, hop: false,
+        duration_ms: ((clock - started) * 1000).round(1)
+      })
+    end
+
+    def clock = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    def exist_elsewhere?(key, blob)
+      outcomes = ask(other_nodes, :head, key, blob, :read) { |_, response| (response.status == 200) ? :hit : :failed }
+      MultiNodeDisk.instrument(:exist, key: key, outcomes: outcomes)
+      return true if outcomes.value?(:hit)
+      return false unless outcomes.value?(:failed)
+
+      raise_for(outcomes, key: key, filename: blob.filename)
+    end
+
+    # Asks the nodes at once. The block classifies a response; a 404 from
+    # the node addressed is :missing; an error, another node answering 404,
+    # a node with no token and a node that never answered are :failed.
+    # Stops at the first :hit.
+    #
+    # @return [Hash{String => Symbol}] each node's outcome
+    def ask(targets, method, key, blob, action)
+      requests = targets.to_h { |target| [target, request_for(method, target, key, blob, action)] }
+      outcomes = {}
+      MultiNodeDisk::FanOut.run(requests.compact, deadline: open_timeout + read_timeout) do |answering, result|
+        outcomes[answering] = classify(answering, result) { |response| yield(answering, response) }
+        outcomes[answering] == :hit
+      end
+      targets.each { |target| outcomes[target] ||= outcomes.value?(:hit) ? :skipped : :failed }
+      outcomes
+    end
+
+    def classify(answering, result)
+      return :failed unless result.is_a?(MultiNodeDisk::Response)
+      return :missing if result.status == 404 && answered_by?(answering, result)
+
+      yield result
+    end
+
+    def answered_by?(target, response)
+      response.header(MultiNodeDisk::NODE_HEADER) == target
+    end
+
+    # The hooks run here, on the caller's thread; the callable returned runs
+    # only the transport. Under :token, nil when no token is configured for
+    # the node (so it counts as failed, unasked).
+    def request_for(method, target, key, blob, action)
+      config = MultiNodeDisk.config
+      url = config.url_for.call(target, key).to_s
+      raise MultiNodeDisk::ConfigurationError, "MultiNodeDisk url_for must return an https URL" unless url.start_with?("https://")
+
+      headers = {config.hop_header => node}
+      requester = MultiNodeDisk::Requester.encode(MultiNodeDisk.current_requester || config.audit_requester&.call(nil))
+      headers[config.requester_header] = requester if requester
+      if auth_modes.include?(:token)
+        token = config.resolve(:token_for, target, blob, action).presence
+        return unless token
+
+        headers["Authorization"] = "Bearer #{token}"
+      end
+      client = config.http_client
+      timeouts = {open_timeout: open_timeout, read_timeout: read_timeout}
+      -> { MultiNodeDisk::Response.new(*client.call(method, url, headers: headers, node: target, **timeouts).to_a) }
+    end
+
+    def raise_for(outcomes, key:, filename:)
+      failed = outcomes.select { |_, outcome| outcome == :failed }.keys
+      mismatched = outcomes.select { |_, outcome| outcome == :mismatch }.keys
+      error =
+        if failed.any? then MultiNodeDisk::Unavailable.new(nodes: failed, key: key, filename: filename)
+        elsif mismatched.any? then MultiNodeDisk::Mismatch.new(nodes: mismatched, key: key, filename: filename)
+        else MultiNodeDisk::NotHere.new(nodes: nodes, key: key, filename: filename)
+        end
+      raise MultiNodeDisk.config.error_mapper.call(error)
+    end
+
+    def verify_local(key, bytes)
+      blob = ActiveStorage::Blob.find_by(key: key)
+      return bytes if blob.nil? || matches?(blob, bytes)
+
+      mismatch_here(key, blob.filename)
+    end
+
+    def verify_file(key, file, checksum)
+      return if checksum.present? && ActiveStorage.checksum_implementation.file(file.path).base64digest == checksum
+
+      mismatch_here(key, ActiveStorage::Blob.find_by(key: key)&.filename)
+    end
+
+    def mismatch_here(key, filename)
+      MultiNodeDisk.instrument(:mismatch, key: key, node: node)
+      raise MultiNodeDisk.config.error_mapper.call(MultiNodeDisk::Mismatch.new(nodes: node, key: key, filename: filename))
+    end
+
+    def matches?(blob, bytes)
+      bytes = bytes.to_s
+      bytes.bytesize == blob.byte_size &&
+        (blob.checksum.blank? || ActiveStorage.checksum_implementation.base64digest(bytes) == blob.checksum)
+    end
+
+    def each_chunk(bytes)
+      offset = 0
+      while offset < bytes.bytesize
+        yield bytes.byteslice(offset, 5.megabytes)
+        offset += 5.megabytes
+      end
+    end
+  end
+end

data/lib/activestorage-multi_node_disk.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Bundler requires a gem by its name; the code lives under active_storage/.
+require "active_storage/multi_node_disk"

data/lib/generators/active_storage/multi_node_disk/install_generator.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module ActiveStorage
+  module MultiNodeDisk
+    # `bin/rails g active_storage:multi_node_disk:install [--audit]`: the
+    # initializer, and with --audit the host's migration for the audit
+    # table (as Blazer's install generator writes its own). Nothing here runs
+    # a migration.
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.join(__dir__, "templates")
+
+      class_option :audit, type: :boolean, default: false, desc: "Add the migration for the :table audit sink"
+
+      # @return [void]
+      def copy_initializer
+        template "initializer.rb", "config/initializers/active_storage_multi_node_disk.rb"
+      end
+
+      # @return [void]
+      def copy_audit_migration
+        return unless options[:audit]
+
+        migration_template "create_audits.rb", "db/migrate/create_active_storage_multi_node_disk_audits.rb", migration_version: migration_version
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+
+      def table_name
+        "#{ActiveStorage::MultiNodeDisk.config.table_name_prefix}audits"
+      end
+
+      # Short and explicit: Oracle before 12.2 allows 30 characters.
+      def index_name
+        "i_#{ActiveStorage::MultiNodeDisk.config.table_name_prefix.split("_").map(&:first).join}_audits_created_at"
+      end
+    end
+  end
+end