activestorage-aws-record 0.1.0

data/lib/active_storage/aws_record/variant_record.rb

@@ -0,0 +1,208 @@
+require 'base64'
+require 'active_storage/aws_record/item'
+require 'active_storage/aws_record/owner'
+
+module ActiveStorage
+  module AwsRecord
+    # Tracks a processed variant of a blob when
+    # +config.active_storage.track_variants+ is on. It is co-located in its
+    # blob's partition (+ns#Blob#<blob_id>+) with a sort key of
+    # +ns#VariantRecord#<variation_digest>+, so the (blob_id, variation_digest)
+    # pair is unique by construction and the blob and all its variants form one
+    # item collection. It is itself an attachment owner (+has_one_attached
+    # :image+); its owner +id+ is a reversible, +#+-free encoding of the natural
+    # key so +find(id)+ resolves it.
+    class VariantRecord
+      include ActiveStorage::AwsRecord::Item
+      include ActiveStorage::AwsRecord::Owner
+
+      ID_DELIMITER = ' '
+
+      # Raised internally when the variant row already exists (the conditional
+      # +Put+ lost the race), so create_or_find_by! can fall back to +find+ —
+      # while genuine post-write failures (e.g. the image attachment) propagate.
+      class CreateConflict < StandardError; end
+
+      string_attr :blob_id,          database_attribute_name: 'as_blob_id'
+      string_attr :variation_digest, database_attribute_name: 'as_variation_digest'
+      string_attr :entity,           database_attribute_name: 'as_entity', default_value: 'VariantRecord'
+
+      class << self
+        # Contract +find(id)+: decode the reversible id back to the natural key.
+        def find(id)
+          blob_id, variation_digest = decode_id(id)
+          find_by(blob_id: blob_id, variation_digest: variation_digest) ||
+            raise(ActiveStorage::RecordNotFound, "Couldn't find #{name} with id=#{id.inspect}")
+        rescue ArgumentError
+          raise ActiveStorage::RecordNotFound, "Couldn't find #{name} with id=#{id.inspect}"
+        end
+
+        def find_by(blob_id:, variation_digest:)
+          keys = logical_keys_for(blob_id.to_s, variation_digest)
+          get_item(**keys)
+        end
+
+        # Owner resolution for Active Storage (VariantRecord is an attachment owner
+        # via +image+). Delegate to the reversible-id +#find+: {Attachable}'s default
+        # +find_with_opts(hash_key => id)+ adapter cannot address the composite key.
+        def active_storage_find(id)
+          find(id)
+        end
+
+        # Race-safe creation: a conditional put on the variant's own key, paired
+        # with a check that the source blob still exists, so a variant can never
+        # be created against a just-purged blob. A condition failure (the variant
+        # already exists, or the blob is gone) falls back to find. The block (used
+        # by VariantWithRecord to +image.attach+ the processed file) runs before
+        # save so the queued image attachment is flushed by the save callbacks.
+        def create_or_find_by!(blob_id:, variation_digest:)
+          record = new(blob_id: blob_id.to_s, variation_digest: variation_digest)
+          yield record if block_given?
+          record.save!
+          record
+        rescue CreateConflict
+          # Only a genuine create conflict (the row already exists) falls back to
+          # find — a post-write failure (image attachment, blob gone) propagates.
+          # NOTE: the marker row commits just before its image attachment is
+          # flushed, so a *concurrent* processor that loses the race here can
+          # briefly observe the record before its image is attached (a transient
+          # that resolves once the winner finishes; like Active Storage's
+          # create-then-upload, but without AR's single enclosing transaction).
+          find_by(blob_id: blob_id, variation_digest: variation_digest) ||
+            raise(ActiveStorage::RecordNotSaved.new('Failed to create or find variant record', record))
+        end
+
+        # All variant records for a blob (used by Blob#destroy's variant sweep).
+        # Mode A: strong base-table query under the blob partition. Mode B: GSI.
+        def where_blob(blob_id)
+          schema = ActiveStorage::AwsRecord.schema
+          partition = ns_key('Blob', blob_id)
+          prefix = "#{ns_key('VariantRecord')}#{ActiveStorage::AwsRecord.config.separator}"
+          opts = {
+            key_condition_expression: '#h = :h AND begins_with(#r, :r)',
+            expression_attribute_values: { ':h' => partition, ':r' => prefix },
+          }
+          if schema.range_mode?
+            opts[:expression_attribute_names] = { '#h' => schema.partition_attr, '#r' => schema.sort_attr }
+            opts[:consistent_read] = true
+          else
+            opts[:index_name] = schema.index_name
+            opts[:expression_attribute_names] = { '#h' => schema.index_partition_attr, '#r' => schema.index_sort_attr }
+          end
+          query(opts).to_a
+        end
+
+        # Logical keys for a (blob_id, variation_digest) pair without an instance.
+        def logical_keys_for(blob_id, variation_digest)
+          {
+            h: ns_key('Blob', blob_id),
+            r: ns_key('VariantRecord', variation_digest),
+            item_id: ns_key('Blob', blob_id, 'VariantRecord', variation_digest),
+          }
+        end
+
+        def encode_id(blob_id, variation_digest)
+          Base64.urlsafe_encode64("#{blob_id}#{ID_DELIMITER}#{variation_digest}", padding: false)
+        end
+
+        def decode_id(id)
+          Base64.urlsafe_decode64(id).split(ID_DELIMITER, 2)
+        end
+      end
+
+      def logical_keys
+        self.class.logical_keys_for(blob_id, variation_digest)
+      end
+
+      # Persist the variant row transactionally *and* run the owner save/commit
+      # callbacks, so a queued +image+ attachment (from create_or_find_by!'s
+      # block) is saved and uploaded. Overrides Owner#save! to substitute the
+      # transactional create for aws-record's plain put. If a step *after* the row
+      # write fails (e.g. the image attachment), the half-written row is removed
+      # so it does not become a markerless "poison" record.
+      def save!(opts = {})
+        marker_written = false
+        completed = run_callbacks(:save) do
+          stamp_physical_keys!
+          if new_record?
+            transactional_create!
+            marker_written = true
+          end
+          true
+        end
+        raise ActiveStorage::RecordNotSaved.new('Save halted by a before_save callback', self) unless completed
+
+        run_callbacks(:commit)
+        self
+      rescue CreateConflict
+        raise
+      rescue StandardError
+        destroy_marker! if marker_written
+        raise
+      end
+
+      def save(opts = {})
+        save!(opts)
+        true
+      rescue ActiveStorage::RecordNotSaved, CreateConflict
+        false
+      end
+
+      # The owner id used as +record_id+ for the +image+ attachment; reversible
+      # so VariantRecord.find(id) resolves the natural key.
+      def id
+        return nil if blob_id.nil? || variation_digest.nil?
+
+        self.class.encode_id(blob_id, variation_digest)
+      end
+
+      private
+
+      def transactional_create!
+        blob_keys = ActiveStorage::AwsRecord::Blob.logical_keys_for(blob_id)
+        dynamodb_client.transact_write_items(
+          transact_items: [
+            { put: {
+              table_name: self.class.table_name,
+              item: save_values,
+              condition_expression: 'attribute_not_exists(#h)',
+              expression_attribute_names: { '#h' => schema.partition_attr },
+            } },
+            { condition_check: {
+              table_name: ActiveStorage::AwsRecord::Blob.table_name,
+              key: ActiveStorage::AwsRecord::Blob.physical_key(**blob_keys),
+              condition_expression: 'attribute_exists(#h)',
+              expression_attribute_names: { '#h' => schema.partition_attr },
+            } },
+          ]
+        )
+        mark_persisted!
+      rescue Aws::DynamoDB::Errors::TransactionCanceledException => e
+        # reasons[0] = the variant Put, reasons[1] = the blob existence check.
+        reasons = e.cancellation_reasons || []
+        put_failed  = reasons[0]&.code == 'ConditionalCheckFailed'
+        blob_failed = reasons[1]&.code == 'ConditionalCheckFailed'
+        # Only a pure put-conflict (variant exists, source blob still present) is
+        # a CreateConflict; if the blob is gone, surface a genuine failure.
+        raise CreateConflict if put_failed && !blob_failed
+
+        raise ActiveStorage::RecordNotSaved.new(e.message, self)
+      rescue Aws::DynamoDB::Errors::ConditionalCheckFailedException, Aws::Record::Errors::ConditionalWriteFailed,
+             Aws::Record::Errors::ValidationError => e
+        raise ActiveStorage::RecordNotSaved.new(e.message, self)
+      end
+
+      # Remove a half-written variant row (best effort) so a post-write failure
+      # does not leave a markerless record that blocks regeneration. Also purge
+      # the image attachment/blob if it was already created during +after_save+,
+      # so it is not orphaned.
+      def destroy_marker!
+        image.purge if image.attached?
+        dynamodb_client.delete_item(table_name: self.class.table_name, key: physical_key)
+        mark_destroyed!
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/active_storage/aws_record/version.rb

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

data/lib/active_storage/aws_record.rb

@@ -0,0 +1,148 @@
+require 'time'
+require 'aws-record'
+require 'globalid'
+require 'active_support'
+require 'active_support/core_ext/object/blank'
+require 'active_model'
+require 'active_storage'
+
+require 'active_storage/aws_record/version'
+require 'active_storage/aws_record/configuration'
+require 'active_storage/aws_record/schema'
+
+module ActiveStorage
+  # Active Storage *metadata* backend backed by Amazon DynamoDB through the
+  # +aws-record+ gem. Blob bytes flow through a normal Active Storage Service
+  # (Disk/S3); only blob/attachment/variant-record metadata lives in DynamoDB,
+  # in a single application-provided table (Single Table Design). See PLAN.md /
+  # README.md for the full design.
+  module AwsRecord
+    autoload :Persistence,   'active_storage/aws_record/persistence'
+    autoload :Item,          'active_storage/aws_record/item'
+    autoload :Attachable,    'active_storage/aws_record/attachable'
+    autoload :Owner,         'active_storage/aws_record/owner'
+    autoload :Relation,      'active_storage/aws_record/relation'
+    autoload :Transaction,        'active_storage/aws_record/transaction'
+    autoload :TransactionTooLarge, 'active_storage/aws_record/transaction'
+    autoload :Blob,          'active_storage/aws_record/blob'
+    autoload :Attachment,    'active_storage/aws_record/attachment'
+    autoload :VariantRecord, 'active_storage/aws_record/variant_record'
+    autoload :Tables,        'active_storage/aws_record/tables'
+
+    # Eager, load-time initialization keeps the shared mutable state fiber-safe
+    # under Falcon: the mutex exists before any fiber can race on the client, and
+    # the config/schema objects are created up front (never via +||=+).
+    @client_mutex = Mutex.new
+    @config = Configuration.new
+    @schema = nil
+    @dynamodb_client = nil
+
+    class << self
+      # @return [Configuration] the memoized gem configuration.
+      attr_reader :config
+
+      # @return [Schema, nil] the resolved table layout (set by {.install!}).
+      attr_reader :schema
+
+      # Yields {#config} for block-style configuration.
+      def configure
+        yield @config
+      end
+
+      # The shared +Aws::DynamoDB::Client+ every model uses. Built lazily but
+      # mutex-guarded so concurrent fibers cannot race two clients into existence.
+      #
+      # @return [Aws::DynamoDB::Client]
+      def dynamodb_client
+        @client_mutex.synchronize do
+          @dynamodb_client ||= @config.client || Aws::DynamoDB::Client.new(@config.client_options)
+        end
+      end
+
+      # Inject a client (tests / Railtie) and rewire the models to it.
+      def dynamodb_client=(client)
+        @client_mutex.synchronize { @dynamodb_client = client }
+        [Blob, Attachment, VariantRecord].each do |model|
+          model.configure_client(client: client) if model.respond_to?(:configure_client)
+        end
+        client
+      end
+
+      # Drop the memoized client/schema (tests, and the Railtie before re-boot).
+      def reset!
+        @client_mutex.synchronize do
+          @dynamodb_client = nil
+          @schema = nil
+        end
+      end
+
+      # Build a +#+-separated composite key, validating every segment is present
+      # (a blank segment would silently corrupt the key space). This is the gem's
+      # lightweight stand-in for an app-specific +compose_key+.
+      #
+      # @param parts [Array<#to_s>]
+      # @return [String]
+      def key(*parts)
+        separator = @config.separator
+        parts.each do |part|
+          raise ArgumentError, "key segment cannot be blank (parts: #{parts.inspect})" if part.nil? || part.to_s.empty?
+
+          if part.to_s.include?(separator)
+            raise ArgumentError, "key segment #{part.inspect} may not contain the separator #{separator.inspect} " \
+              "(parts: #{parts.inspect})"
+          end
+        end
+        parts.join(separator)
+      end
+
+      # Discover the table layout, declare the key attributes on the three models
+      # (now that their DB names are known), point them at the shared client, and
+      # set the table name. Idempotent; safe to call at every boot.
+      def install!
+        client = dynamodb_client
+        Tables.ensure! if @config.manage_table
+        @client_mutex.synchronize { @schema ||= Schema.discover(client, @config) }
+
+        [Blob, Attachment, VariantRecord].each do |model|
+          model.set_table_name(@config.table_name)
+          define_key_attributes!(model)
+          model.configure_client(client: client)
+        end
+      end
+
+      # Declare +has_one_attached+ on the gem's owner entities. Must run after
+      # Active Storage class indirection so the generic (non-AR) builder is used.
+      # Idempotent.
+      def install_attachments!
+        unless Blob.respond_to?(:reflect_on_attachment) && Blob.reflect_on_attachment(:preview_image)
+          Blob.has_one_attached :preview_image
+        end
+        unless VariantRecord.respond_to?(:reflect_on_attachment) && VariantRecord.reflect_on_attachment(:image)
+          VariantRecord.has_one_attached :image
+        end
+      end
+
+      private
+
+      # Declare the table's key attributes on a model using the discovered DB
+      # names. Ruby accessor names are gem-private (+dynamo_*+) so they never
+      # collide with entity attributes. In Mode B the numeric range key holds a
+      # constant and two extra string attributes carry the adjacency keys for the
+      # GSI.
+      def define_key_attributes!(model)
+        return if model.hash_key # already installed in this process
+
+        model.string_attr :dynamo_partition_key, hash_key: true, database_attribute_name: @schema.partition_attr
+        if @schema.range_mode?
+          model.string_attr :dynamo_range_key, range_key: true, database_attribute_name: @schema.sort_attr
+        else
+          model.integer_attr :dynamo_range_key, range_key: true, database_attribute_name: @schema.sort_attr
+          model.string_attr :dynamo_index_partition, database_attribute_name: @schema.index_partition_attr
+          model.string_attr :dynamo_index_sort, database_attribute_name: @schema.index_sort_attr
+        end
+      end
+    end
+  end
+end
+
+require 'active_storage/aws_record/railtie' if defined?(Rails::Railtie)

data/lib/activestorage-aws-record.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Gem entrypoint matching the gem name; delegates to the namespaced require.
+require 'active_storage/aws_record'

metadata

@@ -0,0 +1,166 @@
+--- !ruby/object:Gem::Specification
+name: activestorage-aws-record
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Thomas Witt
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activestorage
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: aws-record
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.15'
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-dynamodb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: globalid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: |
+  A metadata backend that lets Active Storage store its Blob, Attachment, and
+  VariantRecord rows in Amazon DynamoDB (through the aws-record gem) instead of
+  Active Record. Blob bytes still flow through any Active Storage Service
+  (Disk, S3, ...); only the metadata lives in DynamoDB. Implements the generic
+  custom Active Storage backend contract.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- PLAN.md
+- README.md
+- lib/active_storage/aws_record.rb
+- lib/active_storage/aws_record/attachable.rb
+- lib/active_storage/aws_record/attachment.rb
+- lib/active_storage/aws_record/blob.rb
+- lib/active_storage/aws_record/configuration.rb
+- lib/active_storage/aws_record/item.rb
+- lib/active_storage/aws_record/owner.rb
+- lib/active_storage/aws_record/persistence.rb
+- lib/active_storage/aws_record/railtie.rb
+- lib/active_storage/aws_record/relation.rb
+- lib/active_storage/aws_record/schema.rb
+- lib/active_storage/aws_record/tables.rb
+- lib/active_storage/aws_record/tasks.rake
+- lib/active_storage/aws_record/transaction.rb
+- lib/active_storage/aws_record/variant_record.rb
+- lib/active_storage/aws_record/version.rb
+- lib/activestorage-aws-record.rb
+homepage: https://github.com/thomaswitt/activestorage-aws-record
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/thomaswitt/activestorage-aws-record
+  source_code_uri: https://github.com/thomaswitt/activestorage-aws-record
+  changelog_uri: https://github.com/thomaswitt/activestorage-aws-record/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.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.12
+specification_version: 4
+summary: Run Active Storage on Amazon DynamoDB via aws-record.
+test_files: []