phronomy 0.26.0 → 0.28.0

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

data/lib/phronomy/storage/records.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Storage
+    # Compare-and-write records and declared equality indexes.
+    # @api public
+    class Records
+      UNCHECKED = Object.new.freeze
+      attr_reader :resource
+      def initialize(view, resource) = (@view, @resource = view, resource)
+
+      # @api public
+      def insert(key:, revision:, attributes:, record:)
+        @view.validate!
+        entry = Entry::Record.new(key: key, revision: revision, attributes: resource.validate_attributes(attributes), record: record)
+        @view.perform(:insert_record, resource, entry: entry)
+      end
+
+      # @api public
+      def read(key)
+        @view.validate!
+        @view.perform(:read_record, resource, key: Validation.key(key))
+      end
+
+      # @api public
+      def fetch(key)
+        read(key) || raise(NotFoundError, "record not found: #{resource.id}/#{key}")
+      end
+
+      # @api public
+      def replace(key:, expected_revision:, next_revision:, attributes:, record:, expected_attributes: {})
+        @view.validate!
+        expected = Validation.revision(expected_revision)
+        entry = Entry::Record.new(key: key, revision: next_revision, attributes: resource.validate_attributes(attributes), record: record)
+        raise ConflictError, "replace must advance revision exactly once" unless next_revision == expected + 1
+        expected_values = resource.validate_attributes(expected_attributes, partial: true)
+        @view.perform(:replace_record, resource, entry: entry, expected_revision: expected, expected_attributes: expected_values)
+      end
+
+      # @api public
+      def delete(key:, expected_revision: UNCHECKED)
+        @view.validate!
+        expected = expected_revision.equal?(UNCHECKED) ? UNCHECKED : Validation.revision(expected_revision)
+        @view.perform(:delete_record, resource, key: Validation.key(key), expected_revision: expected)
+      end
+
+      # @api public
+      def scan(index:, equals:, after: nil, limit: nil)
+        @view.validate!
+        values = resource.index_values(index, equals)
+        @view.perform(:scan_records, resource, equals: values, after: after.nil? ? nil : Validation.key(after), limit: Validation.limit(limit))
+      end
+
+      # @api public
+      def delete_matching(index:, equals:)
+        @view.validate!
+        @view.perform(:delete_matching_records, resource, equals: resource.index_values(index, equals))
+      end
+    end
+  end
+end

data/lib/phronomy/storage/resource.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Storage
+    # Immutable logical schema. Physical drivers receive a separate mapping.
+    # @api public
+    class Resource
+      TYPES = [:string, :integer, :boolean, :nullable_string, :nullable_integer, :nullable_boolean].freeze
+      attr_reader :id, :kind, :attributes, :immutable_attributes, :indexes, :unique, :guard
+
+      # Normalize a schema object or ID before constructing guards and conditions.
+      # @api private
+      def self.normalize_reference(value)
+        value.is_a?(Resource) ? value : Validation.key(value)
+      end
+
+      # @api public
+      def initialize(id:, kind:, attributes: {}, immutable_attributes: [], indexes: {}, unique: [], guard: nil)
+        @id = Validation.key(id)
+        @kind = kind
+        @attributes = Validation.immutable(attributes)
+        @immutable_attributes = Validation.immutable(immutable_attributes)
+        @indexes = Validation.immutable(indexes)
+        @unique = Validation.immutable(unique)
+        @guard = Validation.immutable(guard)
+        validate_shape!
+        validate_indexes!
+        validate_guard!
+        validate_unique!
+        freeze
+      end
+
+      # @api public
+      def validate_attributes(values, partial: false)
+        valid = values.is_a?(Hash) && (values.keys - attributes.keys).empty? && (partial || values.keys.sort == attributes.keys.sort)
+        unless valid
+          raise ArgumentError, "attributes do not match #{id}"
+        end
+        values = values.to_h do |name, value|
+          type = attributes.fetch(name)
+          if type.to_s.start_with?("nullable_") && value.nil?
+            [name, nil]
+          else
+            [name, typed_value(name, type, value)]
+          end
+        end
+        if guard && values.key?(guard[:via])
+          values[guard[:via]] = Validation.key(values.fetch(guard[:via]))
+        end
+        Validation.attributes(values)
+      end
+
+      # @api public
+      def index_values(index, equals)
+        fields = indexes.fetch(index) { raise ArgumentError, "unknown index: #{index}" }
+        raise ArgumentError, "index attributes must match exactly" unless equals.is_a?(Hash) && equals.keys.sort == fields.sort
+        validate_attributes(equals, partial: true)
+      end
+
+      private
+
+      def validate_shape!
+        raise ArgumentError, "unsupported resource kind" unless [:records, :streams, :blobs].include?(kind)
+        unless attributes.is_a?(Hash) && attributes.keys.all? { |key| key.is_a?(Symbol) } && attributes.values.all? { |type| TYPES.include?(type) }
+          raise ArgumentError, "invalid attribute declarations"
+        end
+        unless field_list?(immutable_attributes, empty: true) && indexes.is_a?(Hash) && unique.is_a?(Array)
+          raise ArgumentError, "invalid resource declarations"
+        end
+        if kind != :records && (!immutable_attributes.empty? || !indexes.empty? || !unique.empty?)
+          raise ArgumentError, "only records declare indexes, uniqueness and immutable attributes"
+        end
+        raise ArgumentError, "streams have no indexed attributes" if kind == :streams && !attributes.empty?
+      end
+
+      def validate_indexes!
+        unless indexes.all? { |name, fields| name.is_a?(Symbol) && field_list?(fields) }
+          raise ArgumentError, "indexes need names and known distinct fields"
+        end
+      end
+
+      def validate_unique!
+        names = unique.map do |constraint|
+          unless constraint.is_a?(Hash) && constraint.keys.sort == [:fields, :name, :where] &&
+              constraint[:name].is_a?(Symbol) && field_list?(constraint[:fields])
+            raise ArgumentError, "invalid unique constraint"
+          end
+          validate_attributes(constraint.fetch(:where), partial: true)
+          constraint[:name]
+        end
+        raise ArgumentError, "unique constraints need distinct names" unless names.uniq == names
+      end
+
+      def validate_guard!
+        return unless guard
+        unless guard.is_a?(Hash) && guard.keys.sort == [:resource, :via] && guard[:resource].is_a?(String)
+          raise ArgumentError, "invalid guard declaration"
+        end
+        Validation.key(guard[:resource])
+        allowed = case kind
+        when :records then [:key, *attributes.select { |_, type| type == :string }.keys]
+        when :streams then [:stream]
+        else []
+        end
+        raise ArgumentError, "invalid guard key" unless allowed.include?(guard[:via])
+        if kind == :records && guard[:via] != :key && !immutable_attributes.include?(guard[:via])
+          raise ArgumentError, "guard attributes must be immutable"
+        end
+      end
+
+      def field_list?(values, empty: false)
+        values.is_a?(Array) && (empty || !values.empty?) && values.uniq == values && (values - attributes.keys).empty?
+      end
+
+      def typed_value(name, type, value)
+        valid = case type.to_s.delete_prefix("nullable_")
+        when "string" then value.is_a?(String) && value.valid_encoding? && !value.include?("\0")
+        when "integer" then value.is_a?(Integer)
+        when "boolean" then value.equal?(true) || value.equal?(false)
+        end
+        raise ArgumentError, "invalid #{id}.#{name}" unless valid
+        value.is_a?(String) ? value.encode(Encoding::UTF_8) : value
+      end
+    end
+  end
+end

data/lib/phronomy/storage/scope.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Storage
+    # One synchronous transaction lifetime, independent of physical rollback.
+    # @api private
+    class Scope
+      def initialize
+        @thread = Thread.current
+        @active = true
+        @failed = false
+      end
+
+      def check!
+        raise TransactionError, "transaction belongs to another execution context" unless @thread.equal?(Thread.current)
+        raise TransactionError, "transaction scope is closed" unless @active
+        raise TransactionError, "transaction scope has failed; leave it before continuing" if @failed
+        true
+      end
+
+      def fail! = @failed = true
+      def close! = @active = false
+    end
+  end
+end

data/lib/phronomy/storage/serialization_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Storage
+    # A value cannot be represented by the storage record contract.
+    # @api public
+    class SerializationError < Phronomy::Error; end
+  end
+end

data/lib/phronomy/storage/streams.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Storage
+    # Atomic ordered append with a per-stream head and entry identity.
+    # @api public
+    class Streams
+      attr_reader :resource
+      def initialize(view, resource) = (@view, @resource = view, resource)
+
+      # @api public
+      def append(stream:, expected_head:, entries:)
+        @view.validate!
+        key = Validation.key(stream)
+        expected = Validation.revision(expected_head)
+        raise ArgumentError, "entries must be an Array" unless entries.is_a?(Array)
+        values = entries.map do |entry|
+          raise SerializationError, "expected Entry::Append" unless entry.is_a?(Entry::Append)
+          Entry::Append.new(id: entry.id, record: entry.record)
+        end
+        raise ConflictError, "duplicate stream entry identity" unless values.map(&:id).uniq.length == values.length
+        @view.perform(:append_stream, resource, stream: key, expected_head: expected, entries: values.freeze)
+      end
+
+      # @api public
+      def read(stream:, after: 0, limit: nil)
+        @view.validate!
+        @view.perform(:read_stream, resource, stream: Validation.key(stream), after: Validation.revision(after), limit: Validation.limit(limit))
+      end
+
+      # @api public
+      def head(stream:)
+        @view.validate!
+        @view.perform(:stream_head, resource, stream: Validation.key(stream))
+      end
+
+      # @api public
+      def delete(stream:)
+        @view.validate!
+        @view.perform(:delete_stream, resource, stream: Validation.key(stream))
+      end
+    end
+  end
+end

data/lib/phronomy/storage/transaction_error.rb

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

data/lib/phronomy/storage/unique_constraint_error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Storage
+    # A neutral storage contract failure.
+    # @api public
+    class UniqueConstraintError < ConflictError
+      attr_reader :resource, :constraint
+      # @api public
+      def initialize(resource:, constraint:)
+        @resource = resource.id
+        @constraint = constraint
+        super("unique constraint #{resource.id}.#{constraint} failed")
+      end
+    end
+  end
+end

data/lib/phronomy/storage/unsupported_backend_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Storage
+    # A backend does not provide a required storage capability.
+    # @api public
+    class UnsupportedBackendError < Phronomy::Error; end
+  end
+end

data/lib/phronomy/storage/validation.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Storage
+    # Input validation shared by storage handles; no physical work happens here.
+    # @api private
+    module Validation
+      module_function
+
+      def key(value)
+        raise ArgumentError, "key must be a non-empty String" unless value.is_a?(String) && !value.empty?
+        result = value.encode(Encoding::UTF_8)
+        raise ArgumentError, "key must be valid UTF-8" unless result.valid_encoding? && !result.include?("\0")
+        result.dup.freeze
+      rescue EncodingError
+        raise ArgumentError, "key must be valid UTF-8"
+      end
+
+      def revision(value)
+        raise ArgumentError, "revision must be a non-negative Integer" unless value.is_a?(Integer) && value >= 0
+        value
+      end
+
+      def limit(value)
+        return nil if value.nil?
+        raise ArgumentError, "limit must be a positive Integer" unless value.is_a?(Integer) && value.positive?
+        value
+      end
+
+      def record(value)
+        raise SerializationError, "expected Storage::DurableRecord" unless value.is_a?(DurableRecord)
+        value.copy
+      end
+
+      def attributes(value)
+        unless value.is_a?(Hash) && value.all? { |name, item| name.is_a?(Symbol) && [String, Integer, TrueClass, FalseClass, NilClass].any? { |type| item.is_a?(type) } }
+          raise ArgumentError, "attributes must contain named scalar values"
+        end
+        immutable(value)
+      end
+
+      def immutable(value)
+        case value
+        when Hash then value.to_h { |k, v| [immutable(k), immutable(v)] }.freeze
+        when Array then value.map { |v| immutable(v) }.freeze
+        when String then value.dup.freeze
+        when Symbol, Integer, TrueClass, FalseClass, NilClass then value
+        else raise ArgumentError, "declarations must contain immutable scalar values"
+        end
+      end
+    end
+  end
+end