hecks 2.6.0 → 2.8.0

data/lib/hecks/ports/persistence/plugins/era/expected_era.rb

@@ -0,0 +1,132 @@
+require "json"
+require "net/http"
+require "uri"
+
+module Hecks
+  module Runtime
+    module EraCheck
+      # The read side of the era gate, for a deploy operator rather than a boot:
+      # asks a running host which era it reports at `GET /version` and compares
+      # it with an allow-list file of the eras that should be running.
+      #
+      # `EraCheck.check!` decides at boot, against the store, whether a host may
+      # run on an era. This answers the question after a roll, from outside:
+      # did the host that came up report an era the operator expects? The two
+      # never share state. The host's own `GET /version` document
+      # (`rust/host/src/server.rs`, `version_body`) is the only input, so a
+      # rollback to an older image, or a fork of the journal back onto an older
+      # era, shows up here as an era missing from the list.
+      #
+      # ## The allow-list file
+      #
+      # One era id per line. Blank lines and lines starting with `#` are
+      # ignored, and so is a trailing ` # comment`. A file that lists no era
+      # means "only check that the host reports one", so a first roll can be
+      # checked before any era id is known. The generated `expected-era` file
+      # (`Deploy::Scripts`) has this shape.
+      #
+      # `bin/check_era` is the command-line wrapper.
+      module ExpectedEra
+        # The host could not be reached, or did not answer with a `200`.
+        class Unreachable < StandardError; end
+
+        # The host answered, but not with a `/version` document carrying an era.
+        class BadResponse < StandardError; end
+
+        # What a comparison concluded.
+        #
+        # @!attribute [r] status
+        #   @return [Symbol] `:match`, `:unlisted` (no era on the list, one reported) or `:mismatch`
+        # @!attribute [r] era
+        #   @return [String] the era the host reported
+        # @!attribute [r] allowed
+        #   @return [Array<String>] the eras the list accepts
+        Verdict = Struct.new(:status, :era, :allowed) do
+          # Tells whether the roll is acceptable.
+          #
+          # @return [Boolean] true unless the reported era is off the list
+          def ok? = status != :mismatch
+        end
+
+        module_function
+
+        # Reads the eras out of an allow-list file's text.
+        #
+        # @param text [String] the file's contents
+        # @return [Array<String>] the era ids in file order, without comments or blanks
+        def parse(text)
+          text.each_line.filter_map do |line|
+            entry = line.strip.sub(/\s+#.*\z/, "")
+            entry unless entry.empty? || entry.start_with?("#")
+          end
+        end
+
+        # Builds the `/version` URL from what an operator gave.
+        #
+        # @param url [String] a host's base URL, or its `/version` URL itself
+        # @return [String] the URL to request
+        def version_url(url)
+          base = url.to_s.chomp("/")
+          base.end_with?("/version") ? base : "#{base}/version"
+        end
+
+        # Asks a host which era it reports.
+        #
+        # @param url [String] the host's base URL, or its `/version` URL
+        # @param timeout [Numeric] seconds allowed for connecting and for reading
+        # @return [String] the `era` the host's `/version` document carries
+        # @raise [Unreachable] if the request fails or the status is not `200`
+        # @raise [BadResponse] if the body is not JSON or its `era` is not a non-empty string
+        def fetch_era(url, timeout: 10)
+          response = get(version_url(url), timeout)
+          raise Unreachable, "#{version_url(url)} answered #{response.code}" unless response.code == "200"
+
+          era = JSON.parse(response.body)["era"]
+          raise BadResponse, "#{version_url(url)} carries no era" unless era.is_a?(String) && !era.empty?
+
+          era
+        rescue JSON::ParserError, TypeError
+          raise BadResponse, "#{version_url(url)} did not answer a JSON version document"
+        end
+
+        # Compares a reported era with an allow-list.
+        #
+        # @param era [String] the era the host reported
+        # @param allowed [Array<String>] the eras the list accepts; empty accepts any
+        # @return [Verdict] `:unlisted` when the list is empty, else `:match` or `:mismatch`
+        def verdict(era, allowed)
+          status = if allowed.empty? then :unlisted
+                   elsif allowed.include?(era) then :match
+                   else :mismatch
+                   end
+          Verdict.new(status, era, allowed)
+        end
+
+        # Fetches the host's era and compares it with an allow-list file.
+        #
+        # @param url [String] the host's base URL, or its `/version` URL
+        # @param file [String] path of the allow-list file
+        # @param timeout [Numeric] seconds allowed for connecting and for reading
+        # @return [Verdict] the comparison
+        # @raise [Errno::ENOENT] if the allow-list file does not exist
+        # @raise [Unreachable] see `fetch_era`
+        # @raise [BadResponse] see `fetch_era`
+        def check(url, file, timeout: 10)
+          allowed = parse(File.read(file))
+          verdict(fetch_era(url, timeout: timeout), allowed)
+        end
+
+        def get(url, timeout)
+          uri = URI.parse(url)
+          Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                              open_timeout: timeout, read_timeout: timeout) do |http|
+            http.request(Net::HTTP::Get.new(uri.request_uri, "Accept" => "application/json"))
+          end
+        rescue SystemCallError, SocketError, Timeout::Error, IOError, URI::InvalidURIError => e
+          raise Unreachable, "#{url} could not be reached: #{e.message}"
+        end
+        private_class_method :get
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/plugins/era/lineage.rb

@@ -159,7 +159,7 @@ module Hecks
           # aware, same as `apply_drop` above (`apply_backfill`'s own
           # header) — a bare name was the only shape this ever needed
           # until a value object gained new required members with zero
-          # source data of their own (found live: lifeadelics' Attendee
+          # source data of their own (found live: a client site's Attendee
           # redesign, commit 4326dcd).
           @backfills.each { |backfill| apply_backfill(state, backfill) }
           Entry.new(operation: entry.operation, id: entry.id, state: state, mirrors: entry.mirrors)

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage/era_store.rb

@@ -24,7 +24,7 @@ module Hecks
           #   the domain holds none; keys are `:ordinal` (Integer), `:hash` and `:label` (String,
           #   nil until `mint_name!` names the era), `:held_text` (String) and `:watermark`
           #   (Integer journal ordinal the era was cut at, nil for era 1)
-          # @raise [Runtime::WiringError] if a held text no longer matches its stored digest
+          # @raise [Runtime::WiringError] if a held text does not match its stored digest
           def eras
             @db.exec_params(
               "SELECT ordinal, hash, label, held_text, watermark, held_digest, held_projection::text " \
@@ -153,7 +153,7 @@ module Hecks
           # Reports the ordinal of the newest era the domain holds.
           #
           # @return [Integer] the highest held ordinal, or 1 when no era is held yet
-          # @raise [Runtime::WiringError] if a held text no longer matches its stored digest
+          # @raise [Runtime::WiringError] if a held text does not match its stored digest
           def current_era
             held = eras
             held.empty? ? 1 : held.last[:ordinal]

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage/head_compiler.rb

@@ -553,7 +553,7 @@ module Hecks
           # `full:` forces a rebuild from the raw journal. The tail-merge
           # needs it: it moves every watermark to the new tip, so every
           # ancestor matview's cut goes stale in the same statement, and
-          # layering on one would carry a cut that no longer exists.
+          # layering on one would carry a cut that does not exist.
           #
           # The live half reads the snapshot table, not `WHERE era = era AND
           # aggregate = name` over the raw journal — that would be a

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage_manager/minter.rb

@@ -107,7 +107,7 @@ module Hecks
           # --approve` and bound to what was actually reviewed: this
           # edge's parsed content, and the journal as it stood when the
           # samples were read. A journal that has advanced past the
-          # review invalidates it — the approved samples no longer cover
+          # review invalidates it — the approved samples do not cover
           # the data.
           #
           # @param bluebook [Bluebook::Chapter] the domain, named in the refusal

data/lib/hecks/ports/persistence/plugins/era/translation/rule_compiler.rb

@@ -64,7 +64,7 @@ module Hecks
         # real, live gap for any new required value-object member with no
         # source data at all — `compute` cannot fill it either, since its
         # own guard requires a real, already-present field to consume
-        # (found live: lifeadelics' Attendee redesign, commit 4326dcd,
+        # (found live: a client site's Attendee redesign, commit 4326dcd,
         # needed exactly this and had nothing that worked).
         declared.backfills.each do |backfill|
           expression = compile_backfill(expression, backfill)
@@ -120,23 +120,29 @@ module Hecks
 
       # A compute is the one rule whose SQL is its only implementation
       # — evaluated exclusively inside the compiled head, never
-      # in-process. The old field is exposed under its own name (as
-      # text, exactly as the author's expression expects to cast it).
+      # in-process. The source is read as a path through
+      # `hecks_tr_extract`, bare or a dotted value-object member alike,
+      # the same way the destination goes through `path_literal`. The
+      # source's value is exposed to the author's SQL as text under a
+      # column named by the source exactly as declared (`price_cents`,
+      # or `"price.cents"` for a dotted member), and the whole record
+      # stays readable as `__s`.
       #
       # @param expression [String] the SQL expression built so far by `compile_rules`, read as
       #   `__s` inside the compute's own SQL
       # @param compute [Bluebook::TranslationCompute] the declared compute rule
       # @return [String] `expression` wrapped so the compute's field lands at its declared
-      #   destination when the source field is present, unchanged otherwise
+      #   destination when the source path is present, unchanged otherwise
       def compile_compute(expression, compute)
         from = compute.from.to_s
         to = compute.to.to_s
-        "(SELECT CASE WHEN __s ? #{text_literal(from)} THEN " \
-          "hecks_tr_insert(__s - #{text_literal(from)}, #{path_literal(to)}, to_jsonb((#{compute.sql})), " \
+        "(SELECT CASE WHEN (__x).present THEN " \
+          "hecks_tr_insert((__x).remaining, #{path_literal(to)}, to_jsonb((#{compute.sql})), " \
           "#{text_literal("compute #{from} to: #{to}")}) " \
           "ELSE __s END " \
           "FROM (SELECT (#{expression}) AS __s) __outer, " \
-          "LATERAL (SELECT (__s ->> #{text_literal(from)}) AS #{quote(from)}) __fields)"
+          "LATERAL (SELECT hecks_tr_extract(__s, #{path_literal(from)}) AS __x) __extract, " \
+          "LATERAL (SELECT (__s #>> #{path_literal(from)}) AS #{quote(from)}) __fields)"
       end
 
       # A newly added, required attribute with no source at all — the

data/lib/hecks/ports/persistence/plugins/era.rb

@@ -12,10 +12,13 @@ module Hecks
     module Persistence
       module Plugins
         # ADR 0033 — requiring this file is installing the plugin. Nothing in
-        # Hecks core requires it; an app that binds `PostgresEra`, or wants
-        # schema-translation support at all, requires it explicitly — the
-        # same shape every adapter-specific spec fixture already uses to
-        # load one particular `.adapter` file rather than all of them.
+        # Hecks core requires it. A boot loads it on demand for a domain that
+        # binds `PostgresEra` (`Runtime::Loader.load_bound_adapters!` resolves the
+        # adapter, which autoloads this file, before the gates are collected). An
+        # app that wants schema-translation support without binding `PostgresEra`
+        # requires it explicitly, the same shape every adapter-specific spec
+        # fixture already uses to load one particular `.adapter` file rather than
+        # all of them.
         module Era
           module_function
 

data/lib/hecks/ports/persistence/postgres_dump/connection.rb

@@ -0,0 +1,73 @@
+require "uri"
+
+module Hecks
+  module Ports
+    module Persistence
+      class PostgresDump
+        # A Postgres connection URL, split so a password reaches the tools run
+        # against it through their environment and never on a command line, where
+        # any user of the machine can read it from the process list.
+        class Connection
+          # @param url [String] a `postgres://` or `postgresql://` URL
+          # @raise [PostgresDump::Error] if `url` is not a Postgres URL
+          def initialize(url)
+            @uri = URI.parse(url)
+            raise Error, "not a postgres URL" unless %w[postgres postgresql].include?(@uri.scheme)
+          end
+
+          # Names the database the URL points at.
+          #
+          # @return [String] the database name, empty when the URL names none
+          def database
+            @uri.path.to_s.delete_prefix("/")
+          end
+
+          # Points the same server and credentials at another database.
+          #
+          # @param name [String] the database to connect to instead
+          # @return [Connection] a new connection; this one is unchanged
+          def with_database(name)
+            copy = @uri.dup
+            copy.path = "/#{name}"
+            self.class.new(copy.to_s)
+          end
+
+          # Lists the connection settings the URL carries, in `PG.connect` keyword form.
+          #
+          # @return [Hash{Symbol => String, Integer}] `host`, `port`, `user`, `password`,
+          #   `dbname` and `sslmode`, each only when the URL gives one; the user and password
+          #   are percent-decoded
+          def settings
+            {
+              host: (@uri.host unless @uri.host.to_s.empty?), port: @uri.port,
+              user: decode(@uri.user), password: decode(@uri.password),
+              dbname: (database unless database.empty?), sslmode: URI.decode_www_form(@uri.query.to_s).to_h["sslmode"]
+            }.compact
+          end
+
+          # Builds the libpq environment variables for a child process.
+          #
+          # @return [Hash{String => String}] `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`,
+          #   `PGDATABASE` and `PGSSLMODE`, each only when `settings` has the matching key
+          def env
+            settings.to_h { |key, value| ["PG#{key.to_s.sub('dbname', 'database').upcase}", value.to_s] }
+          end
+
+          # Opens a connection with the `pg` gem.
+          #
+          # @return [PG::Connection] an open connection; the caller closes it
+          def connect
+            require "pg"
+            PG.connect(**settings)
+          end
+
+          private
+
+          def decode(value)
+            value && URI.decode_www_form_component(value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/postgres_dump.rb

@@ -0,0 +1,125 @@
+require "open3"
+require "securerandom"
+require_relative "postgres_dump/connection"
+
+module Hecks
+  module Ports
+    module Persistence
+      # Dumps one schema of a Postgres database and proves the dump restores.
+      #
+      # ## What the proof is
+      #
+      # A dump nobody has restored is a hope. After `pg_dump` writes the file,
+      # the dump is restored into a scratch database (on the source server, or on a
+      # separate `verify_url` server such as the one the dump will be loaded
+      # into) and every table's row count is compared with the source. That shows
+      # the dump is complete and loadable. It does not re-derive current state
+      # from an event journal, so a caller who needs that proves it separately.
+      #
+      # ## Credentials
+      #
+      # URLs are split by `Connection`: the password travels in the child
+      # process's environment, never in `argv`.
+      #
+      # ## Requirements
+      #
+      # The `pg` gem, and `pg_dump` and `pg_restore` on `PATH` at a version no older
+      # than the server's. Neither the gem nor the tools are a dependency of
+      # hecks; nothing here loads until a dump is asked for.
+      class PostgresDump
+        # Raised for a refusal or a failed tool.
+        class Error < StandardError; end
+
+        # What a verified dump holds.
+        #
+        # @!attribute [r] tables
+        #   @return [Hash{String => Integer}] row count of every table in the schema, by name
+        Result = Struct.new(:tables, keyword_init: true)
+
+        # @param url [String] the source database's `postgres://` URL
+        # @param schema [String] the schema to dump, a plain identifier
+        # @param verify_url [String, nil] the server to restore into for the proof; the source
+        #   server when nil
+        # @raise [Error] if `schema` is not a plain identifier or a URL is not a Postgres URL
+        def initialize(url:, schema:, verify_url: nil)
+          raise Error, "schema #{schema.inspect} is not a plain identifier" unless schema.to_s.match?(/\A[a-z_][a-z0-9_]*\z/i)
+
+          @schema = schema
+          @source = Connection.new(url)
+          @verify = Connection.new(verify_url || url)
+        end
+
+        # Writes a custom-format dump of the schema and proves it restores.
+        #
+        # @param dest [String] the file to write
+        # @return [Result] the verified row counts
+        # @raise [Error] if the schema has no tables, a tool fails, the database refuses, or
+        #   the restored counts differ from the source's
+        def call(dest)
+          require "pg"
+          raise Error, "schema #{@schema} has no tables in #{@source.database}" if counting(@source) { |db| counts(db) }.empty?
+
+          run("pg_dump", @source, "--format=custom", "--no-owner", "--no-privileges", "--schema=#{@schema}", "--file=#{dest}")
+          expected = counting(@source) { |db| counts(db) }
+          verify_restore(dest, expected)
+          Result.new(tables: expected)
+        rescue PG::Error => e
+          raise Error, "database error (#{e.class}): #{e.message.lines.first.to_s.strip}"
+        end
+
+        private
+
+        def verify_restore(dump, expected)
+          scratch = "dump_verify_#{Process.pid}_#{SecureRandom.hex(3)}"
+          counting(@verify) do |admin|
+            admin.exec("CREATE DATABASE #{admin.quote_ident(scratch)}")
+            begin
+              target = @verify.with_database(scratch)
+              run("pg_restore", target, "--no-owner", "--no-privileges", "--exit-on-error", "--dbname=#{scratch}", dump)
+              actual = counting(target) { |db| counts(db) }
+              raise Error, mismatch(expected, actual) unless actual == expected
+            ensure
+              drop(admin, scratch)
+            end
+          end
+        end
+
+        def counting(connection)
+          db = connection.connect
+          yield db
+        ensure
+          db&.close
+        end
+
+        def counts(db)
+          names = db.exec_params("SELECT table_name FROM information_schema.tables " \
+                                 "WHERE table_schema = $1 AND table_type = 'BASE TABLE' ORDER BY 1", [@schema])
+                    .map { |row| row["table_name"] }
+          names.to_h do |name|
+            [name, db.exec("SELECT count(*) FROM #{db.quote_ident(@schema)}.#{db.quote_ident(name)}").getvalue(0, 0).to_i]
+          end
+        end
+
+        def mismatch(expected, actual)
+          differing = (expected.keys | actual.keys).reject { |name| expected[name] == actual[name] }
+          detail = differing.map { |name| "#{name} (source #{expected[name].inspect}, restored #{actual[name].inspect})" }
+          "the restored dump disagrees with the source for #{detail.join(', ')}; " \
+            "if the database took writes during the dump, dump it again"
+        end
+
+        def drop(admin, scratch)
+          admin.exec("DROP DATABASE IF EXISTS #{admin.quote_ident(scratch)} WITH (FORCE)")
+        rescue PG::Error => e
+          warn "could not drop scratch database #{scratch} (#{e.class}); drop it by hand"
+        end
+
+        def run(tool, connection, *)
+          _out, err, status = Open3.capture3(connection.env, tool, *)
+          raise Error, "#{tool} failed: #{err.lines.first(3).join.strip}" unless status.success?
+        rescue Errno::ENOENT
+          raise Error, "#{tool} is not on PATH"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/repository_factory.rb

@@ -30,8 +30,8 @@ module Hecks
         #   lacks `append`, `project` or `entries`
         def build(registry, domain, aggregate, bind, recover: true, settings_verb: VERB)
           registry.check_verb(bind)
-          settings = (registry.world(domain)&.for_binding(settings_verb, bind.adapter) || {})
-                     .reject { |key, _| key.to_sym == :role }
+          settings = registry.binding_settings(domain, settings_verb, bind.adapter)
+                             .reject { |key, _| key.to_sym == :role }
           registry.check_settings(bind, settings)
           # The domain, the resolved era, and (for an old checkout) the era
           # that superseded it ride along after the declared-settings

data/lib/hecks/ports/persistence/state_codec.rb

@@ -44,7 +44,7 @@ module Hecks
       # drops a key, nil or not: a stored nil stays a stored nil.
       #
       # It never touches an undeclared key's value — a retired field, or a
-      # member a value object no longer declares, is exactly what an Era
+      # member a value object does not declare, is exactly what an Era
       # translation (rename/move/drop) still has to read. Its key keeps its
       # spelling below the top level; at the top level every key is a
       # symbol, declared or not, because every adapter has always

data/lib/hecks/ports/persistence.rb

@@ -17,6 +17,10 @@ require_relative "persistence/remote_runtime"
 require_relative "persistence/null_saga_store"
 require_relative "persistence/state_codec"
 
+# Loaded on first mention: nothing about a domain's own boot needs the dump
+# tooling, and it wants the optional `pg` gem.
+Hecks::Ports::Persistence.autoload(:PostgresDump, File.join(__dir__, "persistence/postgres_dump"))
+
 module Hecks
   module Ports
     # Reopened once `BindingPolicy`/`RepositoryFactory` (required above) are