hecks 3.5.0 → 3.7.0

data/lib/hecks/adapters/driven/postgres/outbox.rb

@@ -6,6 +6,25 @@ module Hecks
     # Outbox storage shared by `Postgres` and `PostgresEra`; needs `@db` and `table`.
     # See `Runtime::Outbox` for the four verbs.
     module PostgresOutbox
+      CREATE_OUTBOX_TABLE = <<~SQL.freeze
+        CREATE TABLE IF NOT EXISTS hecks_outbox (
+          id           bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+          delivery_id  text NOT NULL UNIQUE,
+          event_uid    text NOT NULL,
+          aggregate    text NOT NULL,
+          domain       text NOT NULL,
+          kind         text NOT NULL,
+          consumer     text NOT NULL,
+          event        jsonb NOT NULL,
+          status       text NOT NULL DEFAULT 'pending',
+          attempts     integer NOT NULL DEFAULT 0,
+          error        text,
+          enqueued_at  timestamptz NOT NULL DEFAULT now(),
+          claimed_at   timestamptz,
+          settled_at   timestamptz
+        )
+      SQL
+
       # Runs the block inside one Postgres transaction, joining an already-open one.
       #
       # Re-entrant: PG refuses BEGIN inside BEGIN, so an inner call joins the open one.
@@ -34,11 +53,7 @@ module Hecks
       # @raise [PG::Error] if an insert fails
       def outbox_enqueue(rows)
         rows.filter_map do |row|
-          result = pg_exec_params(
-            "INSERT INTO hecks_outbox (delivery_id, event_uid, aggregate, domain, kind, consumer, event, status, attempts) " \
-            "VALUES ($1, $2, $3, $4, $5, $6, $7, 'pending', 0) ON CONFLICT (delivery_id) DO NOTHING RETURNING id",
-            [row.delivery_id, row.event_uid, row.aggregate, row.domain, row.kind, row.consumer, JSON.generate(row.event)]
-          )
+          result = insert_outbox_row(row)
           next nil if result.ntuples.zero?
 
           row.id = result[0]["id"].to_i
@@ -91,37 +106,30 @@ module Hecks
           sql << " AND status = $2"
           binds << status.to_s
         end
-        pg_exec_params("#{sql} ORDER BY id", binds).map do |row|
-          Runtime::Outbox::Row.new(
-            id: row["id"].to_i, delivery_id: row["delivery_id"], event_uid: row["event_uid"], aggregate: row["aggregate"],
-            domain: row["domain"], kind: row["kind"], consumer: row["consumer"],
-            event: JSON.parse(row["event"], symbolize_names: true), status: row["status"],
-            attempts: row["attempts"].to_i, error: row["error"]
-          )
-        end
+        pg_exec_params("#{sql} ORDER BY id", binds).map { |row| outbox_row_from(row) }
       end
 
       private
 
+      def insert_outbox_row(row)
+        pg_exec_params(
+          "INSERT INTO hecks_outbox (delivery_id, event_uid, aggregate, domain, kind, consumer, event, status, attempts) " \
+          "VALUES ($1, $2, $3, $4, $5, $6, $7, 'pending', 0) ON CONFLICT (delivery_id) DO NOTHING RETURNING id",
+          [row.delivery_id, row.event_uid, row.aggregate, row.domain, row.kind, row.consumer, JSON.generate(row.event)]
+        )
+      end
+
+      def outbox_row_from(row)
+        Runtime::Outbox::Row.new(
+          id: row["id"].to_i, delivery_id: row["delivery_id"], event_uid: row["event_uid"], aggregate: row["aggregate"],
+          domain: row["domain"], kind: row["kind"], consumer: row["consumer"],
+          event: JSON.parse(row["event"], symbolize_names: true), status: row["status"],
+          attempts: row["attempts"].to_i, error: row["error"]
+        )
+      end
+
       def create_outbox_table!
-        @db.exec(<<~SQL)
-          CREATE TABLE IF NOT EXISTS hecks_outbox (
-            id           bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
-            delivery_id  text NOT NULL UNIQUE,
-            event_uid    text NOT NULL,
-            aggregate    text NOT NULL,
-            domain       text NOT NULL,
-            kind         text NOT NULL,
-            consumer     text NOT NULL,
-            event        jsonb NOT NULL,
-            status       text NOT NULL DEFAULT 'pending',
-            attempts     integer NOT NULL DEFAULT 0,
-            error        text,
-            enqueued_at  timestamptz NOT NULL DEFAULT now(),
-            claimed_at   timestamptz,
-            settled_at   timestamptz
-          )
-        SQL
+        @db.exec(CREATE_OUTBOX_TABLE)
         @db.exec("CREATE INDEX IF NOT EXISTS idx_hecks_outbox_status ON hecks_outbox(aggregate, status)")
       end
     end

data/lib/hecks/adapters/driven/postgres/repository.rb

@@ -0,0 +1,190 @@
+module Hecks
+  module Adapters
+    class Postgres
+      # The repository surface: find, list, count, and the journal-then-project writes.
+      module Repository
+        # Reads the current row for one aggregate identity, stamped with its stored version.
+        #
+        # @param id [String, Object] the aggregate identity, bound as `id.to_s`
+        # @return [Runtime::Instance, nil] the decoded record with `version` set, or nil when
+        #   no row has that id
+        # @raise [PG::Error] if the statement fails; a `PG::ConnectionBad` also triggers a
+        #   reconnect for the next caller
+        def find(id)
+          result = pg_exec_params("SELECT * FROM #{quoted_table} WHERE id = $1", [id.to_s])
+          return nil if result.ntuples.zero?
+
+          instance_from_row(result[0])
+        end
+
+        # Lists every stored record, ordered by id unless an ordering attribute is given.
+        #
+        # order_by is a runtime value, whitelisted the same way Sqlite#all does.
+        #
+        # @param order_by [String, Symbol, nil] attribute (or dotted value-object path) to sort
+        #   by, with id as the tie-break; nil orders by id alone
+        # @param direction [Symbol, String] `:asc` or `:desc`, case-insensitive; anything else
+        #   sorts ascending
+        # @return [Array<Runtime::Instance>] the decoded records with `version` set, `[]` when
+        #   the table is empty
+        # @raise [Runtime::WiringError] if `order_by` names no attribute of the aggregate
+        # @raise [PG::Error] if the statement fails
+        def all(order_by: nil, direction: :asc)
+          pg_exec("SELECT * FROM #{quoted_table} #{order_sql(order_by, direction)}").map { |row| instance_from_row(row) }
+        end
+
+        # Counts the rows in the aggregate's table, deleted records excluded.
+        #
+        # @return [Integer] number of current records
+        # @raise [PG::Error] if the statement fails
+        def count = pg_exec("SELECT COUNT(*) FROM #{quoted_table}")[0]["count"].to_i
+
+        # Upserts or deletes the aggregate's row for one journal entry, bumping its version.
+        #
+        # `expected_version` requests optimistic-concurrency CAS; nil back means it didn't match.
+        #
+        # @param entry [Ports::Persistence::Entry] the save or delete to materialize
+        # @param expected_version [Integer, nil] the `hecks_version` the row must still hold for
+        #   an update to apply; nil writes unconditionally. Ignored for a delete
+        # @return [Runtime::Instance, PG::Result, nil] a new instance with `version` set, nil on
+        #   CAS mismatch, or the `DELETE` statement's `PG::Result`
+        # @raise [PG::Error] if the statement fails
+        def project(entry, expected_version: nil)
+          advance_checkpoint!(entry.sequence) if entry.sequence
+          return pg_exec_params("DELETE FROM #{quoted_table} WHERE id = $1", [entry.id]) if entry.delete?
+
+          instance = Runtime::Instance.new(aggregate: @aggregate, id: entry.id, state: entry.state)
+          stamp_version(instance, pg_exec_params(*upsert_statement(instance, expected_version)))
+        end
+
+        # Deletes every row of the aggregate's table and its journal; events, saga rows and
+        # outbox rows are left in place.
+        #
+        # @return [Adapters::Postgres] self
+        # @raise [PG::Error] if a statement fails
+        def reset!
+          pg_exec("DELETE FROM #{quoted_table}")
+          pg_exec("DELETE FROM #{quoted_entry_table}")
+          self
+        end
+
+        # Journals and upserts an instance's current state atomically.
+        #
+        # One transaction, so a crash between the journal insert and the row upsert
+        # can never leave the two disagreeing.
+        #
+        # @param instance [Runtime::Instance] the instance to store
+        # @return [Runtime::Instance] a new instance over the saved state, `version` set to the
+        #   row's new `hecks_version`
+        # @raise [PG::Error] if either statement fails; the transaction is rolled back
+        def save(instance)
+          entry = Ports::Persistence::Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
+          transaction do
+            append(entry)
+            project(entry)
+          end
+        end
+
+        # Stores an entry under a per-identity advisory lock and reports whether it inserted,
+        # replaced or conflicted, so two concurrent creators of one id cannot both insert.
+        #
+        # @param entry [Ports::Persistence::Entry] the save to store
+        # @param insert_only [Boolean] when true, an existing row is left untouched
+        # @return [Symbol] `:inserted`, `:replaced`, or `:conflicted` when `insert_only` met an
+        #   existing row and nothing was written
+        # @raise [PG::Error] if a statement fails; the transaction is rolled back
+        def atomic_put(entry, insert_only: false)
+          status = nil
+          transaction { status = put_entry(entry, insert_only) }
+          status
+        end
+
+        # Journals a delete and removes the row atomically, whether or not a row exists.
+        #
+        # @param id [String, Object] the aggregate identity, journalled as `id.to_s`
+        # @return [Boolean] always true
+        # @raise [PG::Error] if either statement fails; the transaction is rolled back
+        def delete(id) # rubocop:disable Naming/PredicateMethod -- the repository port's verb, not a question
+          entry = Ports::Persistence::Entry.new(operation: "delete", id: id.to_s, state: nil)
+          transaction do
+            append(entry)
+            project(entry)
+          end
+          true
+        end
+
+        private
+
+        # The instance with the version the upsert returned; nil when the CAS guard matched no row.
+        def stamp_version(instance, result)
+          return nil if result.ntuples.zero?
+
+          instance.version = result[0]["hecks_version"].to_i
+          instance
+        end
+
+        # `order_by` is a runtime value, so it is checked against the aggregate before use.
+        def order_sql(order_by, direction)
+          return "ORDER BY id" 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
+
+          spec = QuerySpecification::Common::OrderBy.new(field: order_by, direction: direction)
+          "ORDER BY #{order_clause(spec, nil)}"
+        end
+
+        # The upsert statement and its binds. `expected_version` adds the optimistic-concurrency
+        # guard, so a stale writer's update matches no row.
+        def upsert_statement(instance, expected_version)
+          fields = persisted_fields
+          values = [instance.id.to_s] + fields.map { |field| encode_field(field, instance[field[:name]]) } + [1]
+          sql = upsert_sql(fields)
+          return ["#{sql} RETURNING hecks_version", values] unless expected_version
+
+          values += [expected_version]
+          ["#{sql} WHERE #{quoted_table}.hecks_version = $#{values.size} RETURNING hecks_version", values]
+        end
+
+        def upsert_sql(fields)
+          columns = ["id"] + fields.map { |field| field[:name].to_s } + ["hecks_version"]
+          "INSERT INTO #{quoted_table} (#{columns.map { |c| quote_ident(c) }.join(", ")}) " \
+            "VALUES (#{(1..columns.size).map { |n| "$#{n}" }.join(", ")}) " \
+            "ON CONFLICT (id) DO UPDATE SET #{update_assignments(fields).join(", ")}"
+        end
+
+        def update_assignments(fields)
+          fields.map { |field| "#{quote_ident(field[:name])} = EXCLUDED.#{quote_ident(field[:name])}" } +
+            ["hecks_version = #{quoted_table}.hecks_version + 1"]
+        end
+
+        # Takes the per-identity advisory lock, then journals and projects unless an
+        # `insert_only` put finds the row already there.
+        def put_entry(entry, insert_only)
+          pg_exec_params(
+            "SELECT pg_advisory_xact_lock(" \
+            "hashtext(current_schema() || ':' || $1), hashtext($2))",
+            [table, entry.id.to_s]
+          )
+          exists = !pg_exec_params("SELECT 1 FROM #{quoted_table} WHERE id = $1", [entry.id.to_s]).ntuples.zero?
+          return :conflicted if insert_only && exists
+
+          append(entry)
+          project(entry)
+          exists ? :replaced : :inserted
+        end
+
+        # Stamps `.version` from `hecks_version` so a later CAS save has something
+        # to check against.
+        def instance_from_row(row)
+          instance = Runtime::Instance.new(aggregate: @aggregate, id: row["id"], state: decode(row))
+          instance.version = row["hecks_version"].to_i
+          instance
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+module Hecks
+  module Adapters
+    class Postgres
+      # Saga checkpoints, scoped by the adapter's domain.
+      module Sagas
+        # Upserts one saga instance's checkpoint, keyed by domain, process manager and
+        # correlation.
+        #
+        # @param process_manager [String, Symbol] the process manager's name
+        # @param correlation [String, Object] the instance's correlation value, stored as
+        #   `correlation.to_s`
+        # @param state [String, Symbol] the saga's current state name
+        # @param memory [Hash] the saga's memory; must be JSON-serializable
+        # @param completed_compensations [Array] the ledger of completed compensable legs; must
+        #   be JSON-serializable
+        # @return [PG::Result] the upsert's result; callers ignore it
+        # @raise [PG::Error] if the statement fails
+        def save_saga(process_manager:, correlation:, state:, memory:, completed_compensations: [])
+          pg_exec_params(
+            "INSERT INTO hecks_saga_instances (domain, process_manager, correlation, state, memory, completed_compensations) " \
+            "VALUES ($1, $2, $3, $4, $5, $6) " \
+            "ON CONFLICT (domain, process_manager, correlation) DO UPDATE " \
+            "SET state = EXCLUDED.state, memory = EXCLUDED.memory, " \
+            "completed_compensations = EXCLUDED.completed_compensations, updated_at = now()",
+            [@domain, process_manager.to_s, correlation.to_s, state.to_s, JSON.generate(memory),
+             JSON.generate(completed_compensations)]
+          )
+        end
+
+        # Removes a finished saga instance's checkpoint; a missing row is not an error.
+        #
+        # @param process_manager [String, Symbol] the process manager's name
+        # @param correlation [String, Object] the instance's correlation value, matched as
+        #   `correlation.to_s`
+        # @return [PG::Result] the delete's result; callers ignore it
+        # @raise [PG::Error] if the statement fails
+        def delete_saga(process_manager:, correlation:)
+          pg_exec_params(
+            "DELETE FROM hecks_saga_instances WHERE domain = $1 AND process_manager = $2 AND correlation = $3",
+            [@domain, process_manager.to_s, correlation.to_s]
+          )
+        end
+
+        # Yields every checkpointed saga instance of this adapter's domain, for
+        # `Registry#rehydrate_sagas!` to restore at boot.
+        #
+        # @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, `[]`
+        #   when the column is NULL
+        # @return [Enumerator, PG::Result] an enumerator over the same five values when no block
+        #   is given; otherwise the query result
+        # @raise [PG::Error] if the statement fails
+        def each_saga
+          return enum_for(:each_saga) unless block_given?
+
+          pg_exec_params(
+            "SELECT process_manager, correlation, state, memory, completed_compensations " \
+            "FROM hecks_saga_instances WHERE domain = $1",
+            [@domain]
+          ).each do |row|
+            yield row["process_manager"], row["correlation"], row["state"],
+                  JSON.parse(row["memory"], symbolize_names: true),
+                  JSON.parse(row["completed_compensations"] || "[]", symbolize_names: true)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/postgres/schema_builder.rb

@@ -1,4 +1,5 @@
 require "digest"
+require_relative "ddl"
 
 module Hecks
   module Adapters
@@ -11,43 +12,30 @@ module Hecks
         def create_aggregate_table!
           columns = persisted_fields.map { |field| "#{quote_ident(field[:name])} #{field[:sql_type]}" }
           @db.exec(
-            "CREATE TABLE IF NOT EXISTS #{quoted_table} (id text PRIMARY KEY#{', ' unless columns.empty?}#{columns.join(', ')})"
+            "CREATE TABLE IF NOT EXISTS #{quoted_table} (id text PRIMARY KEY#{", " unless columns.empty?}#{columns.join(", ")})"
           )
           # CREATE TABLE IF NOT EXISTS never adds a column to an existing table, so
           # the bookkeeping column is healed on every boot.
           @db.exec("ALTER TABLE #{quoted_table} ADD COLUMN IF NOT EXISTS hecks_version bigint NOT NULL DEFAULT 1")
-          # Same healing for declared attributes: existing rows get NULL, as an unset
-          # optional attribute would.
+          add_missing_columns!
+          ensure_indexes!
+        end
+
+        # Same healing for declared attributes: existing rows get NULL, as an unset
+        # optional attribute would.
+        def add_missing_columns!
           persisted_fields.each do |field|
             @db.exec("ALTER TABLE #{quoted_table} ADD COLUMN IF NOT EXISTS " \
                      "#{quote_ident(field[:name])} #{field[:sql_type]}")
           end
-          ensure_indexes!
         end
 
         def create_entry_table!
-          @db.exec(<<~SQL)
-            CREATE TABLE IF NOT EXISTS #{quoted_entry_table} (
-              sequence     bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
-              aggregate_id text NOT NULL,
-              operation    text NOT NULL DEFAULT 'save',
-              state        jsonb NOT NULL,
-              mirrors      jsonb
-            )
-          SQL
+          @db.exec(format(Ddl::ENTRY_TABLE, table: quoted_entry_table))
         end
 
         def create_event_table!
-          @db.exec(<<~SQL)
-            CREATE TABLE IF NOT EXISTS events (
-              id           bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
-              name         text NOT NULL,
-              aggregate    text NOT NULL,
-              aggregate_id text NOT NULL,
-              payload      jsonb,
-              occurred_at  text
-            )
-          SQL
+          @db.exec(Ddl::EVENTS)
           # Backs #events_for's per-record lookup (a `corrects` command's history read).
           @db.exec(
             "CREATE INDEX IF NOT EXISTS hecks_events_aggregate_id_idx ON events (aggregate, aggregate_id)"
@@ -58,30 +46,14 @@ module Hecks
         # already had projected into it — shared across every aggregate, since it is keyed
         # by table name rather than declared per aggregate.
         def create_checkpoint_table!
-          @db.exec(<<~SQL)
-            CREATE TABLE IF NOT EXISTS hecks_checkpoints (
-              aggregate_table text PRIMARY KEY,
-              last_sequence   bigint NOT NULL DEFAULT 0
-            )
-          SQL
+          @db.exec(Ddl::CHECKPOINTS)
           # CREATE TABLE IF NOT EXISTS never adds a column to an existing table, so
           # the bookkeeping column is healed on every boot, same as create_aggregate_table!.
           @db.exec("ALTER TABLE hecks_checkpoints ADD COLUMN IF NOT EXISTS compacted_through bigint NOT NULL DEFAULT 0")
         end
 
         def create_saga_table!
-          @db.exec(<<~SQL)
-            CREATE TABLE IF NOT EXISTS hecks_saga_instances (
-              domain               text NOT NULL,
-              process_manager      text NOT NULL,
-              correlation          text NOT NULL,
-              state                text NOT NULL,
-              memory               jsonb NOT NULL,
-              completed_compensations  jsonb NOT NULL DEFAULT '[]'::jsonb,
-              updated_at           timestamptz NOT NULL DEFAULT now(),
-              PRIMARY KEY (domain, process_manager, correlation)
-            )
-          SQL
+          @db.exec(Ddl::SAGA_INSTANCES)
           # Heals a table created before this column existed.
           @db.exec("ALTER TABLE hecks_saga_instances ADD COLUMN IF NOT EXISTS completed_compensations jsonb " \
                    "NOT NULL DEFAULT '[]'::jsonb")