hecks 5.0.0 → 7.0.0

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "json"
+require "hecks/ports/persistence/plugins/era"
+require_relative "../../../../shape_ledger"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        # What a boot of each bluebook under a domain directory would resolve, answered by
+        # `Runtime::EraStatus`, the resolution the boot itself records, against the database each
+        # bluebook's own world declares. Both queries only read: the connection refuses writes.
+        module BootStatus
+          # Each bluebook's boot status: from its own database when it declares one, else from the
+          # committed ledger and its edges (`source` says which).
+          #
+          # @param domain [Hash, String] the domain directory
+          # @return [Hash] `text:` the status as JSON, one row per bluebook
+          # @raise [Runtime::NotFound] if the directory cannot be loaded or a database refuses
+          def boot_status(domain:)
+            answering do
+              directory = plain(domain)
+              registry = Hecks.describe(directory).registry
+              JSON.pretty_generate(with_ledger(directory, registry, Runtime::EraStatus.rows(registry, directory)))
+            end
+          end
+
+          # What a boot would resolve for each bluebook, from its own database only: status, held
+          # and current labels, the ordinal it reads, and the reason. A bluebook bound to a store
+          # that holds no eras answers `no_eras`.
+          #
+          # @param domain [Hash, String] the domain directory
+          # @return [Hash] `text:` the resolution as JSON, one row per bluebook
+          # @raise [Runtime::NotFound] if the directory cannot be loaded or a database refuses
+          def boot_resolution(domain:)
+            answering do
+              directory = plain(domain)
+              rows = Runtime::EraStatus.rows(Hecks.describe(directory).registry, directory)
+              JSON.pretty_generate({ "domain" => directory, "bluebooks" => rows })
+            end
+          end
+
+          private
+
+          # The rows, with each `no_eras` row answered by the ledger instead.
+          def with_ledger(directory, registry, rows)
+            ledger = ShapeLedger::Status.of(directory, registry: registry)["bluebooks"] if no_database?(rows)
+            bluebooks = rows.to_h { |name, row| [name, row["source"] == "none" ? ledger.fetch(name, row) : row] }
+            { "domain" => directory, "bluebooks" => bluebooks }
+          end
+
+          def no_database?(rows) = rows.each_value.any? { |row| row["source"] == "none" }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        # The dry run of `write_translation`: the edge that would be written, and the files it would
+        # delete, answered as text and written nowhere.
+        module Composition
+          # The composed edge `write_translation` would write, under comments that say which files
+          # it would remove.
+          #
+          # @param domain [Hash, String] the domain directory
+          # @return [Hash] `text:` the edge file's text, or the sentence that says nothing is to be written
+          # @raise [Runtime::NotFound] if the domain holds no eras, cannot be loaded, or its chain
+          #   cannot be composed
+          def compose_translation(domain:)
+            answering do
+              held = HeldDomain.open(plain(domain))
+              refuse_incapable!(held)
+              held.reading { |lineage| composition_text(held, lineage) }
+            end
+          end
+
+          private
+
+          def composition_text(held, lineage)
+            plan = translation_plan(held, lineage)
+            return plan.message if plan.message
+
+            notes = ["# Would write #{plan.path}."]
+            notes += plan.removals.map { |path| "# Would delete #{path}." }
+            [*notes, plan.text.chomp].join("\n")
+          end
+        end
+      end
+    end
+  end
+end

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