hecks 6.0.0 → 7.0.0

data/lib/hecks/hecks/adapters/journal_store/readings/event_trace/outcomes.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        module EventTrace
+          # What became of one event for one listener. The outbox row for the pair is the record:
+          # its status (`delivered`, `pending`, `claimed`, `failed`, `refused`) and, for a refusal
+          # or failure, its reason. Where no row exists, a later event the listener's trigger
+          # emits is read as delivery (`evidence: "inferred_event"`); else it is `no record`.
+          class Outcomes
+            # @param registry [Runtime::Registry] a described registry
+            # @param rows [Array<Hash>] outbox rows from the event's database
+            # @param events [Array<Hash>] the events traced, to look for what a trigger emitted
+            def initialize(registry, rows, events)
+              @registry = registry
+              @held = rows.map { |row| row.merge("event" => JSON.parse(row["event"].to_s)) }
+                          .group_by { |row| [row["consumer"], *held_key(row["event"])] }
+              @peers = events.group_by { |event| held_key(event, "aggregate_id") }
+              @events = events
+            end
+
+            # @param event [Hash] a recorded event
+            # @param subscriber [Hash] a listener description from {Subscribers}
+            # @return [Hash] `outcome`, `evidence` and, when known, `reason`
+            def for(event, subscriber)
+              row = row_for(event, subscriber[:consumer])
+              return from_row(row) if row
+
+              emitted?(event, subscriber) ? { outcome: "delivered", evidence: "inferred_event" } : none
+            end
+
+            private
+
+            def none = { outcome: "no record", evidence: "none" }
+
+            def from_row(row)
+              { outcome: row["status"], evidence: "outbox", reason: row["error"] }.compact
+            end
+
+            # The same event can be recorded twice in one second (a ring of reactions), so rows and
+            # events of one identity pair off from the newest end: the log shows the newest events
+            # and each has had one row per listener.
+            def row_for(event, consumer)
+              peers = @peers.fetch(held_key(event, "aggregate_id"), [])
+              rows = @held.fetch([consumer, *held_key(event, "aggregate_id")], [])
+              slot = rows.size - (peers.size - peers.index(event))
+              rows[slot] if slot >= 0
+            end
+
+            def held_key(event, id = "id") = [event["name"], event[id].to_s, event["occurred_at"].to_s]
+
+            def emitted?(event, subscriber)
+              names = emitted_by(subscriber[:reaches])
+              @events.any? { |later| later["id"].to_i > event["id"].to_i && names.include?(later["name"]) }
+            end
+
+            def emitted_by(verb)
+              command = command_of(verb)
+              Array(command&.emits).map { |name| Naming.unqualified(name.to_s) }
+            end
+
+            def command_of(verb)
+              domain, aggregate, name = Naming.split_verb(verb)
+              held = @registry.bluebook(domain)&.aggregate(aggregate) if name
+              held&.commands&.find { |command| command.name == name }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/journal_store/readings/event_trace/postgres_reader.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "reader"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        module EventTrace
+          # A PostgresEra database over a session that refuses every write.
+          class PostgresReader < Reader
+            # @param name [String] the bluebook the settings belong to, for refusals
+            # @param settings [Hash] the world's persistence settings
+            # @return [PostgresReader]
+            def self.open(name, settings)
+              db = Hecks::Adapters::PostgresEra.connect_for(name, settings, provision: false)
+              db.exec("SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY")
+              new(db)
+            end
+
+            def initialize(db)
+              super()
+              @db = db
+            end
+
+            # Closes the connection.
+            def close = @db.close
+
+            private
+
+            def run(sql, binds)
+              numbered = sql.gsub("?").with_index(1) { |_, index| "$#{index}" }
+              @db.exec_params(numbered, binds).to_a
+            end
+
+            def json(column, field) = "#{column}->>'#{field}'"
+
+            def table?(name) = !@db.exec_params("SELECT to_regclass($1::text)", [name]).getvalue(0, 0).nil?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/journal_store/readings/event_trace/reader.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        module EventTrace
+          # What a trace asks of one open database, whichever engine holds it: the recorded events
+          # that match a selection, the outbox rows that answer them, and the names that ever
+          # occurred. The two engines differ only in how they bind a value, read a JSON field and
+          # run a statement; a subclass supplies those.
+          class Reader
+            COLUMNS = "id, name, aggregate, aggregate_id, payload, occurred_at"
+
+            # @param selection [Selection] which events to trace
+            # @return [Array<Hash>] the newest matching events, oldest first
+            def events(selection)
+              return [] unless table?("events")
+
+              where, binds = conditions(selection)
+              sql = "SELECT #{COLUMNS} FROM events#{where} ORDER BY id DESC LIMIT #{selection.last.to_i}"
+              run(sql, binds).reverse
+            end
+
+            # @return [Array<Hash>] every distinct `name`/`aggregate` pair the log holds
+            def occurred
+              table?("events") ? run("SELECT DISTINCT name, aggregate FROM events", []) : []
+            end
+
+            # @param events [Array<Hash>] events as {#events} answers them
+            # @return [Array<Hash>] the outbox rows whose event has one of these identities
+            def outbox_for(events)
+              ids = events.map { |event| event["aggregate_id"].to_s }.uniq
+              return [] if ids.empty? || !table?("hecks_outbox")
+
+              sql = "SELECT id, consumer, status, error, event FROM hecks_outbox WHERE #{json("event", "id")} " \
+                    "IN (#{(["?"] * ids.size).join(", ")}) ORDER BY id"
+              run(sql, ids)
+            end
+
+            private
+
+            def conditions(selection)
+              parts = []
+              binds = []
+              add(parts, binds, "name = ?", selection.event)
+              add(parts, binds, "(aggregate_id = ? OR #{json("payload", "run")} = ?)", selection.run, twice: true)
+              [parts.empty? ? "" : " WHERE #{parts.join(" AND ")}", binds]
+            end
+
+            def add(parts, binds, clause, value, twice: false)
+              return if value.to_s.empty?
+
+              parts << clause
+              binds.push(value.to_s, *(twice ? [value.to_s] : []))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/journal_store/readings/event_trace/report.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "stores"
+require_relative "sqlite_reader"
+require_relative "postgres_reader"
+require_relative "subscribers"
+require_relative "outcomes"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        module EventTrace
+          # Which events to trace: by bare event name, by the run (a record's identity or the
+          # `run` field of its payload), or the newest `last`; `database` keeps the stores whose
+          # location contains the text.
+          Selection = Struct.new(:event, :run, :last, :database)
+
+          # The trace itself: per store, the events found, who listens to each and what became of
+          # it; the events nobody listens to; the policies whose event never occurred.
+          class Report
+            NO_LOG = "Memory keeps no log: nothing was recorded to trace"
+
+            # @param registry [Runtime::Registry] a described registry
+            # @param selection [Selection] what to trace
+            def initialize(registry, selection)
+              @registry = registry
+              @selection = selection
+              @subscribers = Subscribers.new(registry)
+            end
+
+            # @return [Hash] `summary`, `stores`, `events`, `no_subscriber` and `never_occurred`
+            def to_h
+              read = Stores.of(@registry, only: @selection.database).map { |store| read_store(store) }
+              events = read.flat_map { |entry| entry[:events] }
+              never = never_occurred(read)
+              { summary: Summary.line(read, events, never), stores: read.map { |entry| entry[:store] },
+                events: events, no_subscriber: unheard(events), never_occurred: never }
+            end
+
+            private
+
+            def unheard(events) = events.select { |row| row[:subscribers].empty? }.map { |row| row[:event] }
+
+            def read_store(store)
+              reader = connect(store)
+              return { store: describe(store, unreadable(store)), events: [] } unless reader
+
+              read_from(store, reader)
+            ensure
+              reader&.close
+            end
+
+            def unreadable(store) = store.kind == :none ? NO_LOG : "absent: no database yet"
+
+            def read_from(store, reader)
+              found = reader.events(@selection)
+              outcomes = Outcomes.new(@registry, reader.outbox_for(found), found)
+              { store: describe(store, "read", found.size), events: found.map { |e| row(store, e, outcomes) },
+                occurred: reader.occurred }
+            end
+
+            def connect(store)
+              case store.kind
+              when :sqlite then SqliteReader.open(store.key)
+              when :postgres then PostgresReader.open(store.name, store.settings)
+              end
+            end
+
+            def describe(store, state, events = 0)
+              { database: store.key, adapter: store.adapter, state: state, events: events }
+            end
+
+            def row(store, event, outcomes)
+              subs = @subscribers.for_event(event["name"], event["aggregate"])
+              { database: store.key, event: identity(event),
+                subscribers: subs.map { |sub| sub.merge(outcomes.for(event, sub)) } }
+            end
+
+            def identity(event)
+              event.slice("id", "name", "aggregate", "aggregate_id", "occurred_at").transform_keys(&:to_sym)
+            end
+
+            def never_occurred(read)
+              return nil if read.none? { |entry| entry[:occurred] }
+
+              seen = read.flat_map { |entry| entry[:occurred] || [] }
+              @subscribers.policies_all.reject { |policy| occurred?(policy, seen) }.map { |p| p.slice(:consumer, :on) }
+            end
+
+            def occurred?(policy, seen)
+              name = Naming.unqualified(policy[:on])
+              qualifier = Naming.qualifier(policy[:on])
+              seen.any? { |s| s["name"] == name && (qualifier.nil? || Naming.demodulise(s["aggregate"]) == qualifier) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/journal_store/readings/event_trace/sqlite_reader.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "reader"
+require_relative "../sqlite_status/read_only"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        module EventTrace
+          # A SQLite file opened read-only, so reading it makes no file beside it (see
+          # {SqliteStatus::ReadOnly}).
+          class SqliteReader < Reader
+            # @param path [String] the database file
+            # @return [SqliteReader, nil] nil when the file does not exist
+            def self.open(path)
+              new(SqliteStatus::ReadOnly.open(path)) if File.file?(path)
+            end
+
+            def initialize(db)
+              super()
+              @db = db
+              @db.results_as_hash = true
+            end
+
+            # Closes the database.
+            def close = @db.close
+
+            private
+
+            def run(sql, binds) = @db.execute(sql, binds)
+
+            def json(column, field) = "json_extract(#{column}, '$.#{field}')"
+
+            def table?(name)
+              @db.execute("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?", [name]).any?
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/journal_store/readings/event_trace/stores.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "../sqlite_status/read_only"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        module EventTrace
+          # The databases a registry's aggregates are persisted in, each with how it is read. An
+          # aggregate bound to Memory (or to an adapter with no event log) yields a store that is
+          # named but cannot be opened, so the trace can say why it has nothing to show.
+          class Stores
+            SQLITE = %w[Sqlite SqlitePersistence].freeze
+            POSTGRES = %w[PostgresEra].freeze
+
+            # One place events are kept: `kind` is `:sqlite`, `:postgres` or `:none`.
+            Store = Struct.new(:kind, :adapter, :key, :name, :settings)
+
+            # @param registry [Runtime::Registry] a described registry
+            # @param only [String, nil] keep only stores whose database contains this text
+            # @return [Array<Store>] one per distinct database, in the order aggregates name them
+            def self.of(registry, only: nil)
+              found = new(registry).stores
+              only.to_s.empty? ? found : found.select { |store| store.key.to_s.include?(only.to_s) }
+            end
+
+            def initialize(registry)
+              @registry = registry
+            end
+
+            # @return [Array<Store>] the distinct stores
+            def stores
+              all = @registry.bluebooks.values.flat_map { |bluebook| bound(bluebook) }
+              all.uniq(&:key)
+            end
+
+            private
+
+            def bound(bluebook)
+              bluebook.aggregates.filter_map { |aggregate| store_for(bluebook, aggregate) }
+            rescue Runtime::WiringError
+              []
+            end
+
+            def store_for(bluebook, aggregate)
+              adapter = Ports::Persistence::BindingPolicy.resolve(@registry, bluebook.name, aggregate).adapter.to_s
+              settings = settings_for(bluebook, aggregate, adapter)
+              build(bluebook.name, adapter, settings)
+            end
+
+            def settings_for(bluebook, aggregate, adapter)
+              declared = @registry.binding_settings(bluebook.name, Ports::Persistence::VERB, adapter)
+              @registry.with_adapter_defaults(adapter, aggregate, declared).transform_keys(&:to_sym)
+            end
+
+            def build(name, adapter, settings)
+              kind = kind_of(adapter)
+              key = kind == :none ? adapter : location(kind, settings)
+              Store.new(kind, adapter, key, name, settings)
+            end
+
+            def kind_of(adapter)
+              return :sqlite if SQLITE.include?(adapter)
+
+              POSTGRES.include?(adapter) ? :postgres : :none
+            end
+
+            def location(kind, settings)
+              database = settings[:database].to_s
+              return [database, settings[:schema]].compact.join("#") if kind == :postgres
+
+              database.start_with?("/") ? database : File.join(@registry.root || Dir.pwd, database)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/journal_store/readings/event_trace/subscribers.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        module EventTrace
+          # Who listens to an event, read from the bluebooks alone: every policy (an `across` policy
+          # and a `for_each` fan-out included, an `ask` as the verb the hecksagon resolved) and
+          # every process manager that starts, ends or handles the event. The consumer name is the
+          # one the outbox records, so a subscriber and its row meet on it.
+          class Subscribers
+            # @param registry [Runtime::Registry] a described registry
+            def initialize(registry)
+              @registry = registry
+            end
+
+            # @param name [String] the event's bare name
+            # @param aggregate [String] the aggregate that emitted it, as the log records it
+            # @return [Array<Hash>] one description per listener, the emitting domain's first
+            def for_event(name, aggregate)
+              emitting = Naming.demodulise(aggregate)
+              domain = aggregate.to_s.split("::", 2).first
+              Runtime::Outbox.bluebooks_home_first(@registry, domain).flat_map do |bluebook|
+                policies(bluebook, name, emitting) + sagas(bluebook, name)
+              end
+            end
+
+            # @return [Array<Hash>] every policy, with the event it listens to
+            def policies_all
+              @registry.bluebooks.values.flat_map { |bluebook| bluebook.policies.map { |p| describe(bluebook, p) } }
+            end
+
+            private
+
+            def policies(bluebook, name, emitting)
+              bluebook.policies.select { |policy| listens?(policy, name, emitting) }.map { |p| describe(bluebook, p) }
+            end
+
+            def listens?(policy, name, emitting)
+              policy.event_name == name && (policy.event_qualifier.nil? || policy.event_qualifier == emitting)
+            end
+
+            def describe(bluebook, policy)
+              { consumer: "policy:#{bluebook.name}::#{policy.name}", kind: "policy", on: policy.on_event.to_s,
+                reaches: reaches(bluebook, policy), across: policy.target_domain&.to_s,
+                where: present(policy.where), for_each: present(policy.for_each) }.compact
+            end
+
+            def present(text) = text.to_s.empty? ? nil : text.to_s
+
+            def reaches(bluebook, policy)
+              return policy.reaches if policy.trigger_command.to_s.empty?
+
+              "#{policy.target_domain || bluebook.name}::#{policy.trigger_command}"
+            end
+
+            def sagas(bluebook, name)
+              bluebook.process_managers.select { |pm| handles?(pm, name) }.map do |manager|
+                { consumer: "saga:#{bluebook.name}::#{manager.name}", kind: "saga" }
+              end
+            end
+
+            def handles?(manager, name)
+              manager.starts_on == name || manager.ends_on == name || !manager.handler_for(name).nil?
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/journal_store/readings/event_trace/summary.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        module EventTrace
+          # The one line that closes a trace.
+          module Summary
+            OUTCOMES = %w[delivered refused pending claimed failed].freeze
+
+            module_function
+
+            # @param read [Array<Hash>] the stores as read
+            # @param events [Array<Hash>] the traced event rows
+            # @param never [Array<Hash>, nil] the policies whose event never occurred, or nil
+            # @return [String] the line
+            def line(read, events, never)
+              "#{events.size} events in #{read.size} store(s); outcomes: #{outcomes(events)}; " \
+                "#{events.count { |row| row[:subscribers].empty? }} without a subscriber; #{unheard(never)}"
+            end
+
+            # @return [String] the count of each outcome found, in a fixed order
+            def outcomes(events)
+              counts = events.flat_map { |row| row[:subscribers] }.map { |sub| sub[:outcome] }.tally
+              parts = (OUTCOMES + ["no record"]).filter_map { |name| "#{counts[name]} #{name}" if counts[name] }
+              parts.empty? ? "none" : parts.join(", ")
+            end
+
+            # @return [String] how many policies never saw their event, in the stores read
+            def unheard(never)
+              never ? "#{never.size} policies whose event never occurred (in the stores read)" : "never-occurred unknown"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/journal_store/readings/event_trace.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "event_trace/summary"
+require_relative "event_trace/report"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        # Whether events are seen and answered: each event in a domain's log, the policies that
+        # listen to it (read from the bluebooks) and what became of each delivery (read from the
+        # store's outbox). Every store is opened read-only and the domain is never booted, so a
+        # trace cannot claim or settle a row.
+        module EventTrace
+          DEFAULT_LAST = 20
+
+          # @param domain [Hash, String] the domain directory
+          # @param event [Hash, String, nil] a bare event name to trace
+          # @param run [Hash, String, nil] a run key: a record's identity or its payload's `run`
+          # @param last [Hash, Integer, nil] how many of the newest events to trace (default 20)
+          # @param database [Hash, String, nil] keep only the stores whose location contains this
+          # @return [Hash] `text:` the trace as JSON
+          # @raise [Runtime::NotFound] if the directory cannot be loaded or a database refuses
+          def event_trace(domain:, event: nil, run: nil, last: nil, database: nil)
+            answering do
+              selection = EventTrace::Selection.new(*[event, run].map { |v| plain(v) }, count(plain(last)), plain(database))
+              JSON.pretty_generate(Report.new(Hecks.describe(plain(domain)).registry, selection).to_h)
+            end
+          end
+
+          private
+
+          def count(last) = last.to_s.empty? ? DEFAULT_LAST : last.to_i
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/journal_store/readings/mint_plan/command_line.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "../../../../../quality_control/adapters/qa_auto_mint"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        module MintPlan
+          # The command line that runs the mint the plan found would go ahead: the Hecks domain's
+          # `Era.mint_held!`, or the ledger's `Maintenance.mint_era!`. Whatever the run supplies
+          # is a `<placeholder>`; the rest is read from the store. `--confirm` is added when the
+          # auto-mint rule (`QaAutoMint.held_reason`) holds the mint for the owner.
+          class CommandLine
+            # @param held [HeldDomain] the loaded domain
+            # @param verdict [LineageManager::MintDecision::Verdict] the decision
+            # @param latest [Hash] the latest held era
+            # @param watermark [Integer] the live watermark
+            def initialize(held, verdict, latest, watermark)
+              @held = held
+              @verdict = verdict
+              @latest = latest
+              @watermark = watermark
+            end
+
+            # @return [String] the command line
+            def to_s
+              return held_line if @held.domain_name == "Hecks"
+
+              [*ledger_line, ("--confirm" if confirm?)].compact.join(" ")
+            end
+
+            private
+
+            def held_line
+              "exe/hecks Era.mint_held! run.value=<run-id> rehearsal_verdict.value=#{@verdict.verdict} " \
+                "watermark.value=#{@watermark} --confirm"
+            end
+
+            def ledger_line
+              ["exe/hecks Maintenance.mint_era! run.value=<run-id> domain=#{@held.domain_name} era=#{@latest[:ordinal] + 1}",
+               "sha.value=<landing-sha> branch=<branch> rehearsal_ref=<rehearsal-run-id> watermark=#{@watermark}",
+               "rehearsal_verdict.value=#{@verdict.verdict} refusal_total=0 ledger_dir=#{@held.directory}"]
+            end
+
+            # The owner's confirmation, unless the auto-mint rule lets the mint run without it.
+            def confirm?
+              from = @latest[:label]
+              facts = { verdict: @verdict, from: from }.merge(QaAutoMint.edge_facts(@held, @held.directory, from))
+              !QaAutoMint.held_reason(facts, refusal_total: 0).nil?
+            end
+          end
+        end
+      end
+    end
+  end
+end