phronomy 0.26.0 → 0.27.0

data/lib/phronomy/storage/backend.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Storage
+    # Neutral storage SPI. Domain resource declarations are supplied by composition.
+    # @api public
+    class Backend
+      REQUIRED_CAPABILITIES = {spi_version: 2, atomic_resources: true,
+                               record_cas: true, stream_cas: true, conditional_unique: true,
+                               guarded_checks: true, nested_savepoints: true}.freeze
+      attr_reader :resources, :view
+
+      # @api public
+      def initialize(resources:)
+        unless resources.is_a?(Array) && resources.all? { |resource| resource.is_a?(Resource) }
+          raise UnsupportedBackendError, "SPI 2 requires Resource declarations"
+        end
+        @resources = resources.to_h { |resource| [resource.id, resource] }.freeze
+        raise UnsupportedBackendError, "duplicate resource identity" unless @resources.length == resources.length
+        @resources.each_value do |resource|
+          next unless resource.guard
+          anchor = @resources[resource.guard.fetch(:resource)]
+          raise UnsupportedBackendError, "guard must name a registered records resource" unless anchor && anchor.kind == :records
+        end
+        @view = View.new(self)
+      end
+
+      # Reject the previous eight-repository SPI before constructing domain wrappers.
+      # @api public
+      def self.validate_capabilities!(backend)
+        capabilities = backend.respond_to?(:capabilities) ? backend.capabilities : {}
+        missing = REQUIRED_CAPABILITIES.reject { |key, value| capabilities.is_a?(Hash) && capabilities[key] == value }
+        unless missing.empty? && backend.respond_to?(:view) && backend.respond_to?(:transaction)
+          raise UnsupportedBackendError, "Persistence requires Storage SPI 2: #{missing.keys.join(", ")}"
+        end
+      end
+
+      # @api public
+      def capabilities
+        REQUIRED_CAPABILITIES.transform_values { |value| (value == true) ? false : value }.freeze
+      end
+
+      # All declared resources participate in one atomic transaction domain.
+      # Record and stream revisions provide compare-and-swap conflict detection.
+      # This does not
+      # mean cross-process Workflow admission or distributed locking.
+      # Storage failures whose commit outcome is fundamentally unknown remain
+      # database failures; Phronomy does not claim exactly-once semantics.
+      # Explicit nesting uses savepoints. Non-local block exits raise and roll back.
+      # @api public
+      def transaction
+        current_view&.validate!
+        storage_transaction do |context|
+          scope = Scope.new
+          bound = View.new(self, scope: scope, context: context)
+          views = stack
+          views.push(bound)
+          completed = false
+          begin
+            result = yield bound
+            scope.check!
+            completed = true
+            result
+          ensure
+            scope.close!
+            views.pop
+            Thread.current.thread_variable_get(:phronomy_storage_scopes)&.delete(self) if views.empty?
+            if !completed && $!.nil?
+              raise TransactionError, "transaction block must complete normally; non-local exit rolled back"
+            end
+          end
+        end
+      end
+
+      # @api private
+      def current_view
+        Thread.current.thread_variable_get(:phronomy_storage_scopes)&.dig(self)&.last.tap { |bound| bound&.validate! }
+      end
+
+      # @api private
+      def execute(context, operation, resource, **arguments)
+        send(operation, context, resource, **arguments)
+      end
+
+      private
+
+      def stack
+        scopes = Thread.current.thread_variable_get(:phronomy_storage_scopes)
+        unless scopes
+          scopes = {}
+          Thread.current.thread_variable_set(:phronomy_storage_scopes, scopes)
+        end
+        scopes[self] ||= []
+      end
+
+      def storage_transaction
+        raise UnsupportedBackendError, "backend must implement an atomic storage transaction"
+      end
+    end
+  end
+end

data/lib/phronomy/storage/backends/in_memory.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Phronomy
+  module Storage
+    module Backends
+      # One Monitor and snapshot cover every declared resource and nested scope.
+      # @api public
+      class InMemory < Backend
+        # @api public
+        def initialize(resources: [])
+          super
+          @monitor = Monitor.new
+          @state = resources.to_h { |resource| [resource.id, {}] }
+        end
+
+        # @api public
+        def capabilities = REQUIRED_CAPABILITIES
+
+        private
+
+        def storage_transaction
+          @monitor.synchronize do
+            snapshot = Marshal.load(Marshal.dump(@state))
+            completed = false
+            begin
+              result = yield @state
+              completed = true
+              result
+            ensure
+              @state.replace(snapshot) unless completed
+            end
+          end
+        end
+
+        def bucket(state, resource) = state.fetch(resource.id)
+
+        def read_record(state, resource, key:)
+          value = bucket(state, resource)[key]
+          value && Entry::Record.new(**value.to_h)
+        end
+
+        def lock_guard(state, resource, key:)
+          raise NotFoundError, "guard record not found: #{resource.id}/#{key}" unless bucket(state, resource).key?(key)
+          true
+        end
+
+        def guard_record(state, resource, key:, attributes: {}, creating: false)
+          guard = resource.guard
+          return unless guard
+          anchor = resources.fetch(guard.fetch(:resource))
+          return if creating && anchor.equal?(resource) && guard[:via] == :key
+          guard_key = [:key, :stream].include?(guard[:via]) ? key : attributes.fetch(guard[:via])
+          lock_guard(state, anchor, key: guard_key)
+        end
+
+        def check_unique(state, resource, entry)
+          resource.unique.each do |constraint|
+            next if constraint[:fields].any? { |key| entry.attributes[key].nil? }
+            next unless constraint.fetch(:where).all? { |key, value| entry.attributes[key] == value }
+            conflict = bucket(state, resource).values.any? do |other|
+              other.key != entry.key && constraint[:where].all? { |k, val| other.attributes[k] == val } && constraint[:fields].all? { |k| other.attributes[k] == entry.attributes[k] }
+            end
+            raise UniqueConstraintError.new(resource: resource, constraint: constraint[:name]) if conflict
+          end
+        end
+
+        def insert_record(state, resource, entry:)
+          raise ConflictError, "duplicate record identity" if bucket(state, resource).key?(entry.key)
+          guard_record(state, resource, key: entry.key, attributes: entry.attributes, creating: true)
+          check_unique(state, resource, entry)
+          bucket(state, resource)[entry.key] = entry
+          Entry::Record.new(**entry.to_h)
+        end
+
+        def replace_record(state, resource, entry:, expected_revision:, expected_attributes:)
+          current = bucket(state, resource)[entry.key] || raise(NotFoundError, "record not found: #{entry.key}")
+          guard_record(state, resource, key: entry.key, attributes: current.attributes)
+          raise ConflictError, "record revision conflict" unless current.revision == expected_revision
+          unless expected_attributes.all? { |key, value| current.attributes[key] == value } && resource.immutable_attributes.all? { |key| current.attributes[key] == entry.attributes[key] }
+            raise ConflictError, "record attribute precondition failed"
+          end
+          check_unique(state, resource, entry)
+          bucket(state, resource)[entry.key] = entry
+          Entry::Record.new(**entry.to_h)
+        end
+
+        def delete_record(state, resource, key:, expected_revision:)
+          current = bucket(state, resource)[key]
+          if !expected_revision.equal?(Records::UNCHECKED) && (!current || current.revision != expected_revision)
+            raise ConflictError, "record deletion revision conflict"
+          end
+          return nil unless current
+          guard_record(state, resource, key: key, attributes: current.attributes)
+          bucket(state, resource).delete(key)
+          nil
+        end
+
+        def scan_records(state, resource, equals:, after:, limit:)
+          entries = bucket(state, resource).values.select { |entry| (!after || entry.key.b > after.b) && equals.all? { |key, value| entry.attributes[key] == value } }.sort_by { |entry| entry.key.b }
+          entries = entries.first(limit) if limit
+          entries.map { |entry| Entry::Record.new(**entry.to_h) }.freeze
+        end
+
+        def delete_matching_records(state, resource, equals:)
+          if resource.guard && ![:key, :stream].include?(resource.guard[:via])
+            raise ArgumentError, "deletion must constrain its guard attribute" unless equals.key?(resource.guard[:via])
+            guard_record(state, resource, key: "unused", attributes: equals)
+          end
+          scan_records(state, resource, equals: equals, after: nil, limit: nil).each do |entry|
+            delete_record(state, resource, key: entry.key, expected_revision: Records::UNCHECKED)
+          end
+          nil
+        end
+
+        def append_stream(state, resource, stream:, expected_head:, entries:)
+          guard_record(state, resource, key: stream)
+          stored = bucket(state, resource).fetch(stream, [])
+          raise ConflictError, "stream head conflict" unless stored.length == expected_head
+          raise ConflictError, "duplicate stream entry identity" unless (stored.map(&:id) & entries.map(&:id)).empty?
+          appended = entries.each_with_index.map { |entry, index| Entry::Stream.new(position: expected_head + index + 1, id: entry.id, record: entry.record) }
+          bucket(state, resource)[stream] = stored + appended unless appended.empty?
+          appended.map { |entry| Entry::Stream.new(**entry.to_h) }.freeze
+        end
+
+        def read_stream(state, resource, stream:, after:, limit:)
+          selected = bucket(state, resource).fetch(stream, []).select { |entry| entry.position > after }
+          selected = selected.first(limit) if limit
+          selected.map { |entry| Entry::Stream.new(**entry.to_h) }.freeze
+        end
+
+        def stream_head(state, resource, stream:) = bucket(state, resource).fetch(stream, []).length
+
+        def delete_stream(state, resource, stream:)
+          guard_record(state, resource, key: stream)
+          bucket(state, resource).delete(stream)
+          nil
+        end
+
+        def put_blob(state, resource, blob:)
+          stored = bucket(state, resource)[blob.key]
+          raise BlobConflictError, "blob bytes are immutable" if stored && stored.bytes != blob.bytes
+          stored ||= bucket(state, resource)[blob.key] = blob
+          Entry::Blob.new(**stored.to_h)
+        end
+
+        def fetch_blob(state, resource, key:)
+          stored = bucket(state, resource)[key] || raise(NotFoundError, "blob not found: #{key}")
+          Entry::Blob.new(**stored.to_h)
+        end
+
+        def blob_exists(state, resource, key:) = bucket(state, resource).key?(key)
+      end
+    end
+  end
+end

data/lib/phronomy/storage/blob_conflict_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Storage
+    # A neutral storage contract failure.
+    # @api public
+    class BlobConflictError < ConflictError
+    end
+  end
+end

data/lib/phronomy/storage/blobs.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Storage
+    # Immutable byte values sharing the same transaction domain as other resources.
+    # @api public
+    class Blobs
+      attr_reader :resource
+      def initialize(view, resource) = (@view, @resource = view, resource)
+
+      # @api public
+      def put_if_absent(key:, bytes:, attributes:)
+        @view.validate!
+        blob = Entry::Blob.new(key: key, bytes: bytes, attributes: resource.validate_attributes(attributes))
+        @view.perform(:put_blob, resource, blob: blob)
+      end
+
+      # @api public
+      def fetch(key)
+        @view.validate!
+        @view.perform(:fetch_blob, resource, key: Validation.key(key))
+      end
+
+      # @api public
+      def exist?(key)
+        @view.validate!
+        @view.perform(:blob_exists, resource, key: Validation.key(key))
+      end
+    end
+  end
+end

data/lib/phronomy/storage/condition.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Storage
+    # A deliberately closed set of conditions; no payload predicates or callbacks.
+    # @api public
+    module Condition
+      RevisionIs = Data.define(:resource, :key, :expected) do
+        def initialize(resource:, key:, expected:)
+          super(resource: Resource.normalize_reference(resource), key: Validation.key(key), expected: Validation.revision(expected))
+        end
+      end
+      StreamHeadIs = Data.define(:resource, :stream, :expected) do
+        def initialize(resource:, stream:, expected:)
+          super(resource: Resource.normalize_reference(resource), stream: Validation.key(stream), expected: Validation.revision(expected))
+        end
+      end
+      NoRows = Data.define(:resource, :index, :equals) do
+        def initialize(resource:, index:, equals:)
+          super(resource: Resource.normalize_reference(resource), index: index, equals: Validation.immutable(equals))
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/storage/condition_failed_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Storage
+    # A neutral storage contract failure.
+    # @api public
+    class ConditionFailedError < ConflictError
+      attr_reader :condition
+      # @api public
+      def initialize(condition)
+        @condition = condition
+        super("storage condition failed: #{condition.class.name}")
+      end
+    end
+  end
+end

data/lib/phronomy/storage/conflict_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Storage
+    # A storage identity, revision, or position precondition failed.
+    # @api public
+    class ConflictError < Phronomy::Error; end
+  end
+end

data/lib/phronomy/{persistence → storage}/durable_record.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  class Persistence
+  module Storage
     # Immutable logical record exchanged across the Persistence Backend SPI.
     #
     # Phronomy owns +record_type+, +format_version+, and the semantic meaning of
@@ -28,20 +28,20 @@ module Phronomy
       # @api public
       def initialize(record_type: MISSING, format_version: MISSING, payload: MISSING)
         if record_type.equal?(MISSING)
-          raise Phronomy::Persistence::SerializationError, "durable record_type is missing"
+          raise Phronomy::Storage::SerializationError, "durable record_type is missing"
         end
         if format_version.equal?(MISSING)
-          raise Phronomy::Persistence::SerializationError, "durable format_version is missing"
+          raise Phronomy::Storage::SerializationError, "durable format_version is missing"
         end
         if payload.equal?(MISSING)
-          raise Phronomy::Persistence::SerializationError, "durable payload is missing"
+          raise Phronomy::Storage::SerializationError, "durable payload is missing"
         end
         unless record_type.is_a?(String)
-          raise Phronomy::Persistence::SerializationError,
+          raise Phronomy::Storage::SerializationError,
             "durable record_type must be a String"
         end
         unless format_version.is_a?(String)
-          raise Phronomy::Persistence::SerializationError,
+          raise Phronomy::Storage::SerializationError,
             "durable format_version must be a String"
         end
 
@@ -51,10 +51,10 @@ module Phronomy
         validate_payload!(payload)
         @payload = immutable_copy(payload)
         freeze
-      rescue Phronomy::Persistence::SerializationError
+      rescue Phronomy::Storage::SerializationError
         raise
       rescue => error
-        raise Phronomy::Persistence::SerializationError, error.message
+        raise Phronomy::Storage::SerializationError, error.message
       end
 
       # Returns an independent immutable record with the same logical value.
@@ -75,26 +75,26 @@ module Phronomy
 
       def validate_header!
         if record_type.empty?
-          raise Phronomy::Persistence::SerializationError,
+          raise Phronomy::Storage::SerializationError,
             "durable record_type must not be empty"
         end
 
         return if FORMAT_VERSION_PATTERN.match?(format_version)
 
-        raise Phronomy::Persistence::SerializationError,
+        raise Phronomy::Storage::SerializationError,
           "invalid durable format_version: #{format_version.inspect}"
       end
 
       def validate_payload!(payload)
         unless payload.is_a?(Hash)
-          raise Phronomy::Persistence::SerializationError,
+          raise Phronomy::Storage::SerializationError,
             "durable payload must be a Hash"
         end
 
         Phronomy::CanonicalJSON.dump(payload)
         true
       rescue ArgumentError => error
-        raise Phronomy::Persistence::SerializationError,
+        raise Phronomy::Storage::SerializationError,
           "durable payload is not canonical JSON compatible: #{error.message}"
       end
 

data/lib/phronomy/storage/entry.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Storage
+    # Values crossing the driver boundary never expose mutable storage state.
+    # @api public
+    module Entry
+      Record = Data.define(:key, :revision, :attributes, :record) do
+        def initialize(key:, revision:, attributes:, record:)
+          super(key: Validation.key(key), revision: Validation.revision(revision),
+                attributes: Validation.attributes(attributes), record: Validation.record(record))
+        end
+      end
+      Append = Data.define(:id, :record) do
+        def initialize(id:, record:)
+          super(id: Validation.key(id), record: Validation.record(record))
+        end
+      end
+      Stream = Data.define(:position, :id, :record) do
+        def initialize(position:, id:, record:)
+          super(position: Validation.revision(position), id: Validation.key(id), record: Validation.record(record))
+        end
+      end
+      Blob = Data.define(:key, :bytes, :attributes) do
+        def initialize(key:, bytes:, attributes:)
+          raise ArgumentError, "blob bytes must be a String" unless bytes.is_a?(String)
+          super(key: Validation.key(key), bytes: bytes.dup.force_encoding(Encoding::BINARY).freeze,
+                attributes: Validation.attributes(attributes))
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/storage/guard_ref.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Storage
+    # A stable existing record used as a transaction lock anchor.
+    # @api public
+    GuardRef = Data.define(:resource, :key) do
+      def initialize(resource:, key:)
+        super(resource: Resource.normalize_reference(resource), key: Validation.key(key))
+      end
+    end
+  end
+end

data/lib/phronomy/storage/not_found_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Storage
+    # A requested stored record does not exist.
+    # @api public
+    class NotFoundError < Phronomy::Error; end
+  end
+end

data/lib/phronomy/storage/record_codec.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Storage
+    # Shared record-envelope and scalar validation; domain schemas live with their domains.
+    # @api private
+    module RecordCodec
+      private
+
+      def current_payload!(record, record_type:, format_version:, keys:, label:)
+        unless record.is_a?(Phronomy::Storage::DurableRecord)
+          raise Phronomy::Storage::SerializationError,
+            "backend returned #{record.class}; expected Storage::DurableRecord"
+        end
+        unless record.record_type == record_type
+          raise Phronomy::Storage::SerializationError,
+            "durable record type mismatch: expected #{record_type.inspect}, " \
+            "got #{record.record_type.inspect}"
+        end
+        unless record.format_version == format_version
+          raise Phronomy::Storage::SerializationError,
+            "unsupported #{record_type} format version: #{record.format_version.inspect}; " \
+            "current version is #{format_version.inspect}"
+        end
+        validate_exact_keys!(record.payload, keys, label: label)
+        record.payload
+      end
+
+      def validate_allowed_keys!(hash, required_keys:, optional_keys:, label:)
+        unless hash.is_a?(Hash)
+          raise Phronomy::Storage::SerializationError, "#{label} must be a Hash"
+        end
+        unless hash.keys.all? { |key| key.is_a?(String) }
+          raise Phronomy::Storage::SerializationError,
+            "#{label} keys must all be String"
+        end
+
+        actual = hash.keys.sort
+        missing = required_keys.sort - actual
+        unknown = actual - (required_keys + optional_keys).sort
+        return hash if missing.empty? && unknown.empty?
+
+        details = []
+        details << "missing=#{missing.inspect}" unless missing.empty?
+        details << "unknown=#{unknown.inspect}" unless unknown.empty?
+        raise Phronomy::Storage::SerializationError,
+          "#{label} schema mismatch (#{details.join(", ")})"
+      end
+
+      def validate_exact_keys!(hash, expected_keys, label:)
+        unless hash.is_a?(Hash)
+          raise Phronomy::Storage::SerializationError, "#{label} must be a Hash"
+        end
+        unless hash.keys.all? { |key| key.is_a?(String) }
+          raise Phronomy::Storage::SerializationError,
+            "#{label} keys must all be String"
+        end
+
+        actual = hash.keys.sort
+        expected = expected_keys.sort
+        return hash if actual == expected
+
+        missing = expected - actual
+        unknown = actual - expected
+        details = []
+        details << "missing=#{missing.inspect}" unless missing.empty?
+        details << "unknown=#{unknown.inspect}" unless unknown.empty?
+        raise Phronomy::Storage::SerializationError,
+          "#{label} schema mismatch (#{details.join(", ")})"
+      end
+
+      def top_level_string_keys(value, label:)
+        unless value.is_a?(Hash)
+          raise Phronomy::Storage::SerializationError, "#{label} must be a Hash"
+        end
+        value.each_with_object({}) do |(key, child), result|
+          unless key.is_a?(String) || key.is_a?(Symbol)
+            raise Phronomy::Storage::SerializationError,
+              "#{label} key must be String or Symbol, got #{key.class}"
+          end
+          string_key = key.to_s
+          if result.key?(string_key)
+            raise Phronomy::Storage::SerializationError,
+              "#{label} contains duplicate key after normalization: #{string_key.inspect}"
+          end
+          result[string_key] = child
+        end
+      end
+
+      def require_nonempty_string!(hash, key, label:)
+        value = hash.fetch(key)
+        return value if value.is_a?(String) && !value.empty?
+
+        raise Phronomy::Storage::SerializationError,
+          "#{label} #{key} must be a non-empty String"
+      end
+
+      def require_optional_string!(hash, key, label:)
+        value = hash.fetch(key)
+        return value if value.nil? || value.is_a?(String)
+
+        raise Phronomy::Storage::SerializationError,
+          "#{label} #{key} must be a String or nil"
+      end
+
+      def require_integer!(hash, key, label:)
+        value = hash.fetch(key)
+        return value if value.is_a?(Integer)
+
+        raise Phronomy::Storage::SerializationError,
+          "#{label} #{key} must be an Integer"
+      end
+
+      def require_positive_integer!(hash, key, label:)
+        value = hash.fetch(key)
+        return value if value.is_a?(Integer) && value.positive?
+
+        raise Phronomy::Storage::SerializationError,
+          "#{label} #{key} must be a positive Integer"
+      end
+
+      def require_nonnegative_integer!(hash, key, label:)
+        value = hash.fetch(key)
+        return value if value.is_a?(Integer) && value >= 0
+
+        raise Phronomy::Storage::SerializationError,
+          "#{label} #{key} must be a non-negative Integer"
+      end
+
+      def require_boolean!(hash, key, label:)
+        value = hash.fetch(key)
+        return value if boolean?(value)
+
+        raise Phronomy::Storage::SerializationError,
+          "#{label} #{key} must be true or false"
+      end
+
+      def require_enum_string!(hash, key, allowed, label:)
+        value = hash.fetch(key)
+        return value if value.is_a?(String) && allowed.include?(value)
+
+        raise Phronomy::Storage::SerializationError,
+          "#{label} #{key} must be one of #{allowed.inspect}"
+      end
+
+      def require_canonical_hash!(hash, key, label:)
+        value = hash.fetch(key)
+        unless value.is_a?(Hash)
+          raise Phronomy::Storage::SerializationError,
+            "#{label} #{key} must be a Hash"
+        end
+        Phronomy::CanonicalJSON.dump(value)
+        value
+      rescue ArgumentError => error
+        raise Phronomy::Storage::SerializationError,
+          "#{label} #{key} is not canonical JSON compatible: #{error.message}"
+      end
+
+      def boolean?(value)
+        value.equal?(true) || value.equal?(false)
+      end
+
+      def build_record(record_type, format_version, payload)
+        Phronomy::Storage::DurableRecord.new(
+          record_type: record_type,
+          format_version: format_version,
+          payload: payload
+        )
+      end
+
+      def serialization_error(prefix, error)
+        raise Phronomy::Storage::SerializationError,
+          "#{prefix}: #{error.class}: #{error.message}"
+      end
+    end
+  end
+end