hecks 3.5.0 → 3.7.0

data/lib/hecks/adapters/driven/governance_authorization.rb

@@ -111,9 +111,9 @@ module Hecks
         unless providers.size == 1
           raise Runtime::WiringError,
                 "#{providers.size} loaded chapters provide \"authorization\"" \
-                "#{" (#{providers.map(&:name).sort.join(', ')})" unless providers.empty?} — " \
+                "#{" (#{providers.map(&:name).sort.join(", ")})" unless providers.empty?} — " \
                 "a role lookup needs exactly one (framework members declaring it: " \
-                "#{Framework.providers_of(Bluebook::Capabilities::AUTHORIZATION).join(', ')})"
+                "#{Framework.providers_of(Bluebook::Capabilities::AUTHORIZATION).join(", ")})"
         end
 
         providers.first.provided_verb(Bluebook::Capabilities::AUTHORIZATION, key)

data/lib/hecks/adapters/driven/heki/journal.rb

@@ -57,21 +57,22 @@ module Hecks
         def replay_journal(records)
           return records unless File.exist?(@journal_path)
 
-          File.foreach(@journal_path) do |line|
-            entry = JSON.parse(line)
-            id    = entry.fetch("id")
-
-            case entry.fetch("operation")
-            when "save"   then records[id] = entry.fetch("state")
-            when "delete" then records.delete(id)
-            else raise Malformed, "#{@journal_path}: unknown journal operation #{entry.fetch('operation').inspect}"
-            end
-          end
+          File.foreach(@journal_path) { |line| replay_line(records, JSON.parse(line)) }
           records
         rescue JSON::ParserError => e
           raise Malformed, "#{@journal_path}: json error: #{e.message}"
         end
 
+        def replay_line(records, entry)
+          id = entry.fetch("id")
+
+          case entry.fetch("operation")
+          when "save"   then records[id] = entry.fetch("state")
+          when "delete" then records.delete(id)
+          else raise Malformed, "#{@journal_path}: unknown journal operation #{entry.fetch("operation").inspect}"
+          end
+        end
+
         def append_entry(operation, id, state)
           encoded = Ports::Persistence::StateCodec.encode(@aggregate, state)
           line = "#{JSON.generate(operation: operation, id: id.to_s, state: encoded, mirrors: @entry_mirrors)}\n"

data/lib/hecks/adapters/driven/heki/saga_store.rb

@@ -27,15 +27,13 @@ module Hecks
         # @param domain [String] the owning domain, carried in the record and filtered on read
         # @param process_manager [String] the process manager's name
         # @param correlation [String] the instance's correlation value
-        # @param state [String] the saga's current state name
-        # @param memory [Hash] the saga's working memory to persist
-        # @param completed_compensations [Array] completed compensable legs; `[]` when none
+        # @param checkpoint [Hash{String => Object}] the saga's `"state"` (name), `"memory"`
+        #   (working memory) and `"completed_compensations"` (compensable legs; `[]` when none)
         # @return [Hash{String => Hash}] the full records Hash after the write; callers ignore it
-        def save_saga(domain, process_manager, correlation, state, memory, completed_compensations = [])
+        def save_saga(domain, process_manager, correlation, checkpoint)
           key    = key_for(domain, process_manager, correlation)
           record = { "domain" => domain, "process_manager" => process_manager,
-                     "correlation" => correlation, "state" => state, "memory" => memory,
-                     "completed_compensations" => completed_compensations }
+                     "correlation" => correlation }.merge(checkpoint)
 
           with_lock do
             append_entry("save", key, record)

data/lib/hecks/adapters/driven/heki/sagas.rb

@@ -0,0 +1,55 @@
+module Hecks
+  module Adapters
+    class Heki
+      # The saga-checkpoint surface of the file-backed store: each call delegates to a
+      # `SagaStore` kept in a sibling file pair, scoped by the adapter's domain name.
+      module Sagas
+        # Checkpoints one saga instance in a sibling file pair (`SagaStore`).
+        #
+        # @param process_manager [String, Symbol] the process manager's name, compared as
+        #   `.to_s`
+        # @param correlation [String, Symbol, Object] the instance's correlation value, compared
+        #   as `.to_s`
+        # @param state [String, Symbol] the saga's current state name, compared as `.to_s`
+        # @param memory [Hash] the saga's working memory to persist
+        # @param completed_compensations [Array] the ledger of completed compensable legs;
+        #   `[]` when none
+        # @return [Hash{String => Hash}] `SagaStore`'s internal records Hash after the write;
+        #   callers ignore it
+        def save_saga(process_manager:, correlation:, state:, memory:, completed_compensations: [])
+          checkpoint = { "state" => state.to_s, "memory" => memory, "completed_compensations" => completed_compensations }
+          saga_store.save_saga(@domain, process_manager.to_s, correlation.to_s, checkpoint)
+        end
+
+        # Removes a finished saga instance's checkpoint; a missing one is not an error.
+        #
+        # @param process_manager [String, Symbol] the process manager's name, compared as
+        #   `.to_s`
+        # @param correlation [String, Symbol, Object] the instance's correlation value, compared
+        #   as `.to_s`
+        # @return [Hash{String => Hash}] `SagaStore`'s internal records Hash after the delete;
+        #   callers ignore it
+        def delete_saga(process_manager:, correlation:)
+          saga_store.delete_saga(@domain, process_manager.to_s, correlation.to_s)
+        end
+
+        # Yields every checkpointed saga instance of this domain, for boot-time rehydration.
+        #
+        # @yieldparam process_manager [String] the process manager's name
+        # @yieldparam correlation [String] the instance's correlation value
+        # @yieldparam state [String] the saga's state name
+        # @yieldparam memory [Hash{Symbol => Object}] the saga's memory, Symbol keys at every
+        #   depth
+        # @yieldparam completed_compensations [Array] the completed-compensation ledger
+        # @return [Enumerator, Hash{String => Hash}] an enumerator when no block is given
+        def each_saga(&) = saga_store.each_saga(@domain, &)
+
+        private
+
+        def saga_store
+          @saga_store ||= SagaStore.new(File.dirname(@path))
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/heki.rb

@@ -3,6 +3,7 @@ require "fileutils"
 require_relative "heki/snapshot"
 require_relative "heki/journal"
 require_relative "heki/saga_store"
+require_relative "heki/sagas"
 require_relative "../../ports/persistence/append_only"
 require_relative "../../ports/query/in_memory"
 require_relative "in_memory_ordering"
@@ -17,6 +18,7 @@ module Hecks
     class Heki
       include Snapshot
       include Journal
+      include Sagas
 
       MAGIC = "HEKI".freeze
       HEADER_BYTES = 8
@@ -37,16 +39,7 @@ module Hecks
         @journal_path = "#{@path}.journal"
         @events = []
         # Saga scope; falls back to the aggregate's name for a directly built adapter.
-        @domain = (
-          if settings.key?(:domain)
-            settings[:domain]
-          elsif settings.key?("domain")
-            settings["domain"]
-          else
-            aggregate.name
-          end
-        ).to_s
-
+        @domain = setting(settings, :domain, aggregate.name).to_s
         FileUtils.mkdir_p(File.dirname(@path))
       end
 
@@ -116,13 +109,7 @@ module Hecks
       def project(entry)
         removed = entry.delete? ? store[entry.id] : nil
         current = read
-        if entry.save?
-          current[entry.id] = Ports::Persistence::StateCodec.encode(@aggregate, entry.state)
-          projected = Runtime::Instance.new(aggregate: @aggregate, id: entry.id, state: entry.state)
-        else
-          current.delete(entry.id)
-          projected = removed && instance(entry.id, removed)
-        end
+        projected = entry.save? ? apply_save(current, entry) : apply_delete(current, entry, removed)
         write(current)
         @store = current
         projected
@@ -146,7 +133,7 @@ module Hecks
       # @param id [String, Object] the record's identity, compared as `id.to_s`
       # @return [Boolean] true when a record was found and deleted, false when there was none
       #   and nothing was journaled
-      def delete(id)
+      def delete(id) # rubocop:disable Naming/PredicateMethod -- the repository port's verb, answering whether a record existed
         return false unless find(id)
 
         entry = Ports::Persistence::Entry.new(operation: "delete", id: id.to_s, state: nil)
@@ -163,49 +150,16 @@ module Hecks
       # @return [Array<Runtime::Event>] the adapter's in-memory event log, including `event`
       def record_event(event) = @events << event
 
-      # Checkpoints one saga instance in a sibling file pair (`SagaStore`).
-      #
-      # @param process_manager [String, Symbol] the process manager's name, compared as
-      #   `.to_s`
-      # @param correlation [String, Symbol, Object] the instance's correlation value, compared
-      #   as `.to_s`
-      # @param state [String, Symbol] the saga's current state name, compared as `.to_s`
-      # @param memory [Hash] the saga's working memory to persist
-      # @param completed_compensations [Array] the ledger of completed compensable legs;
-      #   `[]` when none
-      # @return [Hash{String => Hash}] `SagaStore`'s internal records Hash after the write;
-      #   callers ignore it
-      def save_saga(process_manager:, correlation:, state:, memory:, completed_compensations: [])
-        saga_store.save_saga(@domain, process_manager.to_s, correlation.to_s, state.to_s, memory, completed_compensations)
-      end
+      private
 
-      # Removes a finished saga instance's checkpoint; a missing one is not an error.
-      #
-      # @param process_manager [String, Symbol] the process manager's name, compared as
-      #   `.to_s`
-      # @param correlation [String, Symbol, Object] the instance's correlation value, compared
-      #   as `.to_s`
-      # @return [Hash{String => Hash}] `SagaStore`'s internal records Hash after the delete;
-      #   callers ignore it
-      def delete_saga(process_manager:, correlation:)
-        saga_store.delete_saga(@domain, process_manager.to_s, correlation.to_s)
+      def apply_save(current, entry)
+        current[entry.id] = Ports::Persistence::StateCodec.encode(@aggregate, entry.state)
+        Runtime::Instance.new(aggregate: @aggregate, id: entry.id, state: entry.state)
       end
 
-      # Yields every checkpointed saga instance of this domain, for boot-time rehydration.
-      #
-      # @yieldparam process_manager [String] the process manager's name
-      # @yieldparam correlation [String] the instance's correlation value
-      # @yieldparam state [String] the saga's state name
-      # @yieldparam memory [Hash{Symbol => Object}] the saga's memory, Symbol keys at every
-      #   depth
-      # @yieldparam completed_compensations [Array] the completed-compensation ledger
-      # @return [Enumerator, Hash{String => Hash}] an enumerator when no block is given
-      def each_saga(&) = saga_store.each_saga(@domain, &)
-
-      private
-
-      def saga_store
-        @saga_store ||= SagaStore.new(File.dirname(@path))
+      def apply_delete(current, entry, removed)
+        current.delete(entry.id)
+        removed && instance(entry.id, removed)
       end
 
       def instance(id, record)
@@ -227,19 +181,20 @@ module Hecks
 
       # `dir: :default` means no setting; a Symbol would make `File.join` raise TypeError.
       def resolve_path(settings, root)
-        declared =
-          if settings.key?(:dir)
-            settings[:dir]
-          elsif settings.key?("dir")
-            settings["dir"]
-          else
-            "data"
-          end
+        declared = setting(settings, :dir, "data")
         declared = "data" if declared == :default
         dir      = declared.start_with?("/") ? declared : File.join(root || Dir.pwd, declared)
 
         File.join(dir, "#{@aggregate.storage_name}.heki")
       end
+
+      # A setting read under its Symbol key, then its String key, then `default`.
+      def setting(settings, key, default)
+        return settings[key] if settings.key?(key)
+        return settings[key.to_s] if settings.key?(key.to_s)
+
+        default
+      end
     end
   end
 end

data/lib/hecks/adapters/driven/in_memory_ordering.rb

@@ -25,12 +25,7 @@ module Hecks
       def ordered(records, aggregate:, order_by:, direction:)
         return records unless order_by
 
-        name = order_by.to_s.split(".").first
-        unless aggregate.lifecycle&.field.to_s == name || aggregate.attribute(name)
-          raise Runtime::WiringError,
-                "#{aggregate.name} has no attribute #{order_by.inspect} to order by"
-        end
-
+        require_orderable!(aggregate, order_by)
         path = sortable_path(aggregate, order_by)
         spec = QuerySpecification::Common::OrderBy.new(field: order_by, direction: direction)
         Ports::Query::Ordering.apply(records, spec, nil, identity: ->(record) { record.id.to_s }) do |record|
@@ -38,6 +33,40 @@ module Hecks
         end
       end
 
+      # Refuses an `order_by` that names neither an attribute nor the lifecycle field.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate being ordered
+      # @param order_by [String, Symbol] a dotted attribute path
+      # @return [void]
+      # @raise [Runtime::WiringError] if the path's first segment names nothing orderable
+      def require_orderable!(aggregate, order_by)
+        name = order_by.to_s.split(".").first
+        return if lifecycle_field?(aggregate, name) || aggregate.attribute(name)
+
+        raise Runtime::WiringError, "#{aggregate.name} has no attribute #{order_by.inspect} to order by"
+      end
+
+      # Whether `name` is the aggregate's lifecycle field.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate to ask
+      # @param name [String] an attribute name
+      # @return [Boolean] true when `name` is the lifecycle field
+      def lifecycle_field?(aggregate, name)
+        aggregate.lifecycle&.field.to_s == name
+      end
+
+      # Picks the member of a value object that orders it.
+      #
+      # Numeric member, else the sole attribute, else `value`; kept in lockstep with
+      # `SqlQueryBuilder#query_expression` so Memory and SQL order rows identically.
+      #
+      # @param shape [Bluebook::ValueObject] the value object type
+      # @return [String] the member name
+      def orderable_member(shape)
+        shape.attributes.find { |a| %w[Integer Float].include?(a.type) }&.name ||
+          shape.sole_attribute&.name || "value"
+      end
+
       # Resolves the dotted path `FieldPath.dig` should read to compare a value object field.
       #
       # @param aggregate [Bluebook::Aggregate] the aggregate `field` belongs to
@@ -51,16 +80,12 @@ module Hecks
         return field.to_s unless path.empty?
 
         attribute = aggregate.attribute(name)
-        return field.to_s if aggregate.lifecycle&.field.to_s == name || attribute.nil?
+        return field.to_s if lifecycle_field?(aggregate, name) || attribute.nil?
 
         vo = aggregate.value_object(attribute.type)
         return field.to_s unless vo
 
-        # Numeric member, else the sole attribute, else `value`; kept in lockstep with
-        # `SqlQueryBuilder#query_expression` so Memory and SQL order rows identically.
-        member = vo.attributes.find { |a| %w[Integer Float].include?(a.type) }&.name ||
-                 vo.sole_attribute&.name || "value"
-        "#{name}.#{member}"
+        "#{name}.#{orderable_member(vo)}"
       end
     end
   end

data/lib/hecks/adapters/driven/lambda/client.rb

@@ -64,7 +64,7 @@ module Hecks
 
           if response.function_error
             raise Runtime::WiringError,
-                  "Lambda #{@function_name} (#{response.function_error}): #{body['errorMessage'] || body}"
+                  "Lambda #{@function_name} (#{response.function_error}): #{body["errorMessage"] || body}"
           end
 
           body

data/lib/hecks/adapters/driven/lambda.rb

@@ -25,14 +25,7 @@ module Hecks
       #   to resolve which function to call; nil falls further back to `domain`
       def initialize(aggregate:, settings: {}, root: nil)
         @aggregate = aggregate
-        domain =
-          if settings.key?(:domain)
-            settings[:domain]
-          elsif settings.key?("domain")
-            settings["domain"]
-          else
-            aggregate.name
-          end
+        domain = setting(settings, :domain, aggregate.name)
         region = setting(settings, :region, "us-east-1")
         # Explicit function name, for deployments whose function is not `hecks-<domain>`.
         function = setting(settings, :function, nil)

data/lib/hecks/adapters/driven/memory/outbox_rows.rb

@@ -0,0 +1,76 @@
+module Hecks
+  module Adapters
+    class Memory
+      # The in-process transactional outbox: rows move pending, claimed, delivered without a
+      # database, held in the adapter's `@outbox` and `@outbox_deliveries`. See `Runtime::Outbox`.
+      module OutboxRows
+        # Holds new outbox rows, skipping any whose `delivery_id` is already held.
+        #
+        # @param rows [Array<Runtime::Outbox::Row>] pending rows to enqueue; each accepted row
+        #   has its `id` assigned in place
+        # @return [Array<Runtime::Outbox::Row>] the rows actually enqueued, `[]` when every one
+        #   was a duplicate
+        def outbox_enqueue(rows)
+          rows.filter_map do |row|
+            next nil if @outbox_deliveries.key?(row.delivery_id)
+
+            row.id = @outbox.size + 1
+            @outbox << row
+            @outbox_deliveries[row.delivery_id] = true
+            row
+          end
+        end
+
+        # Marks a pending outbox row claimed and counts the delivery attempt.
+        #
+        # @param id [Integer] the row id `outbox_enqueue` assigned
+        # @return [Boolean] true when the row was pending and is now claimed; false when it is
+        #   unknown or not pending
+        def outbox_claim(id) # rubocop:disable Naming/PredicateMethod
+          row = outbox_row(id)
+          return false unless row&.pending?
+
+          row.status = "claimed"
+          row.attempts += 1
+          true
+        end
+
+        # Records a delivery outcome on an outbox row, whatever status it held.
+        #
+        # @param id [Integer] the row id `outbox_enqueue` assigned
+        # @param status [String, Symbol] the new status, one of `Runtime::Outbox::STATUSES`;
+        #   not validated here
+        # @param error [String, nil] the failure description, or nil to clear it
+        # @return [Boolean] true when the row exists and was updated; false when no row has `id`
+        def outbox_settle(id, status:, error: nil) # rubocop:disable Naming/PredicateMethod
+          row = outbox_row(id) or return false
+          row.status = status.to_s
+          row.error  = error
+          true
+        end
+
+        # Lists outbox rows in enqueue order, as copies a caller may mutate freely.
+        #
+        # @param status [String, Symbol, nil] only rows with this status; nil lists every row
+        # @return [Array<Runtime::Outbox::Row>] shallow copies of the matching rows, `[]` when
+        #   none match
+        def outbox_rows(status: nil)
+          rows = status ? @outbox.select { |row| row.status == status.to_s } : @outbox
+          rows.map(&:dup)
+        end
+
+        private
+
+        # Finds a held outbox row by id in constant time.
+        #
+        # Ids are assigned as the 1-based position at enqueue and rows are never
+        # removed, so the id is the row's index plus one.
+        def outbox_row(id)
+          return nil unless id.is_a?(Integer) && id >= 1
+
+          @outbox[id - 1]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/memory/shared_elements/values.rb

@@ -0,0 +1,117 @@
+require_relative "../../../../freezer"
+require_relative "../../../../ports/persistence/state_codec"
+require_relative "../../../../runtime/value"
+
+module Hecks
+  module Adapters
+    class Memory
+      class SharedElements
+        # The value-object half of element sharing: a single attribute holding one value object
+        # that can hold a list is copied once, and a later version of it reuses the copies of the
+        # list elements it still holds.
+        module Values
+          private
+
+          # The attributes of the aggregate that hold one value object able to hold a list, by
+          # name. A value object with no list in it is small and is left to the codec.
+          def growable_values
+            @growable_values ||= @aggregate.attributes.each_with_object({}) do |attribute, found|
+              next if attribute.list? || attribute.reference?
+
+              shape = value_object_of(attribute)
+              found[attribute.name.to_sym] = attribute if shape && growable?(shape, [])
+            end
+          end
+
+          def value_object_of(attribute)
+            return nil unless @aggregate.respond_to?(:value_object)
+
+            Runtime::Value.value_object_for(@aggregate, attribute.type.to_s)
+          end
+
+          def growable?(shape, seen)
+            return false if seen.include?(shape)
+
+            shape.attributes.any? do |attribute|
+              next false if attribute.reference?
+              next true if attribute.list?
+
+              nested = value_object_of(attribute)
+              nested ? growable?(nested, seen + [shape]) : false
+            end
+          end
+
+          # The growable value-object attributes of `state` holding a frozen value of their type.
+          def journal_values(state)
+            return {} unless state.is_a?(Hash)
+
+            growable_values.each_with_object({}) do |(name, attribute), found|
+              value = state[name]
+              found[name] = [attribute, value] if value.is_a?(Runtime::Value) && sharable_value?(attribute, value)
+            end
+          end
+
+          def sharable_value?(attribute, value)
+            value.frozen? && value.type_name == value_object_of(attribute).hecks_name
+          end
+
+          # The growable value-object attributes of `decoded` holding a frozen Hash: a copy this
+          # table made, or one a caller froze.
+          def live_values(decoded)
+            return {} unless decoded.is_a?(Hash)
+
+            growable_values.each_with_object({}) do |(name, attribute), found|
+              copy = decoded[name]
+              found[name] = [attribute, copy] if copy.is_a?(Hash) && copy.frozen?
+            end
+          end
+
+          # The frozen codec copy of one value object. A list it holds is rebuilt from the copies
+          # of its elements, so a new version of the value costs the new elements, not all of them.
+          def journal_value(attribute, value)
+            known = @journal[value]
+            return known if known
+
+            copy = build_value_copy(attribute, value)
+            @copies[copy.freeze] = true
+            @journal[value] = copy
+          end
+
+          def build_value_copy(attribute, value)
+            fields = value.raw_fields
+            lists  = value_lists(attribute, fields)
+            held   = fields.merge(lists.transform_values { nil })
+            copy   = Ports::Persistence::StateCodec.copy_list_element(@aggregate, attribute, held)
+            copy.each_value { |inner| Freezer.deep(inner) }
+            lists.each { |name, (list_attribute, elements)| copy[name] = journal_list(list_attribute, elements) }
+            copy
+          end
+
+          def value_lists(attribute, fields)
+            list_attributes(value_object_of(attribute)).each_with_object({}) do |(name, list_attribute), found|
+              elements = fields[name]
+              found[name] = [list_attribute, elements] if elements.is_a?(Array)
+            end
+          end
+
+          # The hydrated value for one frozen copy, its lists rebuilt from the hydrated elements
+          # already held.
+          def live_value(attribute, copy)
+            known = @live[copy]
+            return known if known
+
+            lists  = value_lists(attribute, copy)
+            fields = copy.merge(lists.to_h { |name, (list_attribute, elements)| [name, live_list(list_attribute, elements)] })
+            live   = Runtime::Value.trusting_stored_state do
+              Runtime::Value.for_attribute(@aggregate, attribute, fields)
+            end
+            return live unless @copies.key?(copy)
+
+            @journal[live] = copy
+            @live[copy] = live
+          end
+        end
+      end
+    end
+  end
+end