hecks 2.9.0 → 3.0.0

data/lib/hecks/cli/shape.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../../hecks"
+# The `:shape` projection reads `Runtime::StorageShape`, which lives in the era persistence plugin
+# core does not load by default (ADR 0033).
+require_relative "../ports/persistence/plugins/era"
+
+module Hecks
+  module CLI
+    # The command behind `hecks shape` and `hecks shape`: a bluebook's storage-shape projection, the
+    # same hash PostgresEra mints an era's label from, so two runs diff to show whether a bluebook
+    # change would bump an era.
+    module Shape
+      module_function
+
+      # Prints the projection of a bluebook file as JSON, or one `<Domain> <label>` line per domain
+      # of a directory (files in subdirectories are not read).
+      #
+      # @param argv [Array<String>] the bluebook file or directory, first
+      # @param program [String] the name the usage message calls this command by
+      # @return [void]
+      # @raise [SystemExit] when `argv` is empty, the path is missing or holds no bluebook
+      def call(argv, program: "hecks shape")
+        target = argv.first or abort "usage: #{program} <bluebook | directory of *.bluebook files>"
+        puts render(target)
+      rescue Runtime::NotFound => e
+        abort e.message
+      end
+
+      # @param target [String] a bluebook file, or a directory of them
+      # @return [String] the storage-shape projection as JSON for a file, or one
+      #   `<Domain> <label>` line per domain for a directory
+      # @raise [Runtime::NotFound] if the path does not exist or holds no bluebook
+      def render(target)
+        raise Runtime::NotFound, "#{target} does not exist" unless File.exist?(target)
+
+        directory = File.directory?(target)
+        files = directory ? Dir[File.join(target, "*.bluebook")] : [target]
+        raise Runtime::NotFound, "no *.bluebook files in #{target}" if files.empty?
+
+        registry = load_files(files)
+        return labels(registry) if directory
+
+        bluebook = registry.bluebooks.values.first or raise Runtime::NotFound, "#{target} declares no bluebook"
+        JSON.pretty_generate(Projector.call(:shape, bluebook: bluebook))
+      end
+
+      # @param files [Array<String>] bluebook files
+      # @return [Runtime::Registry] a registry holding every bluebook the files declare
+      def load_files(files)
+        registry = Runtime::Registry.new
+        loading  = Ports::Loading.bootstrap
+        Hecks.with_registry(registry) do
+          loading.load_library
+          files.each { |file| Kernel.eval(File.read(file), TOPLEVEL_BINDING, File.expand_path(file), 1) }
+        end
+        registry
+      end
+
+      # @param registry [Runtime::Registry] a loaded registry
+      # @return [String] one `<Domain> <label>` line per bluebook, sorted by name
+      def labels(registry)
+        registry.bluebooks.sort_by { |name, _| name.to_s }
+                .map { |name, bluebook| "#{name} #{Runtime::StorageShape.mint_label(bluebook)}" }
+                .join("\n")
+      end
+    end
+  end
+end

data/lib/hecks/cli/smoke_http.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "json"
+require "optparse"
+
+module Hecks
+  module CLI
+    # One run of the checks against one service.
+    class SmokeHttp
+      # The signature header value for a body, per scheme.
+      module Signature
+        SCHEMES = %w[timestamped sha256 hex].freeze
+
+        module_function
+
+        # Signs a body the way the chosen scheme's sender would.
+        def header_value(scheme, secret, body, at: Time.now)
+          case scheme
+          when "timestamped"
+            stamp = at.to_i
+            "t=#{stamp},v1=#{digest(secret, "#{stamp}.#{body}")}"
+          when "sha256" then "sha256=#{digest(secret, body)}"
+          when "hex" then digest(secret, body)
+          else raise ArgumentError, "unknown scheme #{scheme.inspect}; expected one of #{SCHEMES.join(', ')}"
+          end
+        end
+
+        # Computes the keyed digest every scheme is built from.
+        def digest(secret, text)
+          OpenSSL::HMAC.hexdigest("SHA256", secret, text)
+        end
+      end
+
+      # Runs the checks as the `hecks smoke_http` script does: settings from the arguments and the
+      # environment, a refusal worded with the program's name.
+      #
+      # @param argv [Array<String>] the flags, consumed
+      # @param env [Hash{String => String}] the environment defaults
+      # @param program [String] the name a refusal is prefixed with
+      # @return [Integer] the exit status: 1 when any check failed
+      # @raise [SystemExit] when the settings are refused
+      def self.main(argv, env: ENV, program: "hecks smoke_http")
+        new(settings(argv, env)).run
+      rescue ArgumentError, OptionParser::ParseError, Errno::ENOENT => e
+        abort "#{program}: #{e.message}"
+      end
+
+      # Reads the command line and environment into the settings a run needs.
+      #
+      # @param argv [Array<String>] the flags, consumed
+      # @param env [Hash{String => String}] the environment defaults
+      # @return [Hash{Symbol => String}] the settings
+      # @raise [ArgumentError] if the path or the secret is missing or the scheme is unknown
+      def self.settings(argv, env)
+        options = {}
+        parser(options).parse!(argv)
+        resolve(options, env)
+      end
+
+      # Merges explicit options over the environment's defaults and validates the result.
+      #
+      # @param options [Hash{Symbol => String}] the settings offered explicitly
+      # @param env [Hash{String => String}] the environment defaults
+      # @return [Hash{Symbol => String}] the settings
+      # @raise [ArgumentError] if the path or the secret is missing or the scheme is unknown
+      def self.resolve(options, env)
+        settings = {
+          url: env.fetch("SMOKE_TARGET_URL", "http://127.0.0.1:4322"), path: env["SMOKE_WEBHOOK_PATH"],
+          secret: env["SMOKE_WEBHOOK_SECRET"], header: env.fetch("SMOKE_SIGNATURE_HEADER", "X-Signature"),
+          scheme: env.fetch("SMOKE_SIGNATURE_SCHEME", "timestamped")
+        }.merge(options)
+        validate!(settings)
+        settings
+      end
+
+      # @api private
+      def self.parser(options)
+        OptionParser.new do |parser|
+          %i[url path secret header scheme payload health_path state_path].each do |name|
+            flag = "--#{name.to_s.tr('_', '-')}"
+            parser.on("#{flag} VALUE") { |value| options[name] = value }
+          end
+          parser.on("--payload-file FILE") { |file| options[:payload] = File.read(file) }
+        end
+      end
+
+      # Refuses settings a run cannot start from.
+      #
+      # @param settings [Hash{Symbol => String}] the settings to judge
+      # @return [void]
+      # @raise [ArgumentError] if the path or the secret is missing or the scheme is unknown
+      def self.validate!(settings)
+        raise ArgumentError, "no webhook path: pass --path or set SMOKE_WEBHOOK_PATH" if settings[:path].to_s.empty?
+        raise ArgumentError, "no signing secret: set SMOKE_WEBHOOK_SECRET (or pass --secret)" if settings[:secret].to_s.empty?
+        return if Signature::SCHEMES.include?(settings[:scheme])
+
+        raise ArgumentError, "unknown scheme #{settings[:scheme].inspect}; expected one of #{Signature::SCHEMES.join(', ')}"
+      end
+
+      # @param settings [Hash{Symbol => String}] validated settings
+      # @param out [IO] where the checks are reported
+      def initialize(settings, out: $stdout)
+        @settings = settings
+        @out = out
+        @failures = []
+        @target = URI(settings.fetch(:url))
+      end
+
+      def run
+        @out.puts "== signed webhook checks against #{@target}#{@settings[:path]} =="
+        check_health
+        check_unsigned
+        check_wrong_secret
+        check_tampered_body
+        check_signed
+        check_repeat
+        summarize
+      end
+
+      private
+
+      def check(label)
+        @out.print "  #{label}... "
+        yield
+        @out.puts "ok"
+      rescue StandardError => e
+        @out.puts "FAILED: #{e.message}"
+        @failures << label
+      end
+
+      def check_health
+        return unless @settings[:health_path]
+
+        check("GET #{@settings[:health_path]} answers 200") { expect_status(get(@settings[:health_path]), 200) }
+      end
+
+      def check_unsigned
+        check("a delivery with no signature is refused") { expect_refused(post(payload, {})) }
+      end
+
+      def check_wrong_secret
+        check("a delivery signed with the wrong secret is refused") do
+          expect_refused(post(payload, signature_header("not-the-secret-#{run_id}", payload)))
+        end
+      end
+
+      # A trailing space is enough: the signature covers the exact bytes.
+      def check_tampered_body
+        check("a delivery whose body changed after signing is refused") do
+          expect_refused(post("#{payload} ", signature_header(@settings.fetch(:secret), payload)))
+        end
+      end
+
+      def check_signed
+        check("a correctly signed delivery is accepted") { expect_success(post(payload, signed_headers)) }
+      end
+
+      def check_repeat
+        check("a repeated delivery of the same payload is accepted again, not an error") do
+          before = state
+          expect_success(post(payload, signed_headers))
+          after = state
+          raise "the state changed on a repeated delivery:\n    before #{before}\n    after  #{after}" unless before == after
+        end
+      end
+
+      def summarize
+        if @failures.empty?
+          @out.puts "\nSMOKE HTTP PASSED"
+          0
+        else
+          @out.puts "\nSMOKE HTTP FAILED (#{@failures.size}):"
+          @failures.each { |label| @out.puts "  - #{label}" }
+          1
+        end
+      end
+
+      def run_id
+        @run_id ||= "smoke-#{Process.pid}-#{rand(1_000_000)}"
+      end
+
+      def payload
+        @payload ||= @settings[:payload] || JSON.generate(id: run_id, type: "smoke.ping")
+      end
+
+      def signed_headers
+        signature_header(@settings.fetch(:secret), payload)
+      end
+
+      def signature_header(secret, body)
+        { @settings.fetch(:header) => Signature.header_value(@settings.fetch(:scheme), secret, body) }
+      end
+
+      def state
+        @settings[:state_path] ? get(@settings[:state_path]).body : nil
+      end
+
+      def get(path)
+        request(Net::HTTP::Get.new(URI.join(@target, path)))
+      end
+
+      def post(body, headers)
+        req = Net::HTTP::Post.new(URI.join(@target, @settings.fetch(:path)))
+        headers.each { |name, value| req[name] = value }
+        req["Content-Type"] = "application/json"
+        req.body = body
+        request(req)
+      end
+
+      def request(req)
+        options = { use_ssl: req.uri.scheme == "https", read_timeout: 8, open_timeout: 8 }
+        Net::HTTP.start(req.uri.host, req.uri.port, **options) { |http| http.request(req) }
+      end
+
+      def expect_status(res, code)
+        raise "expected #{code}, got #{res.code}" unless res.code.to_i == code
+      end
+
+      def expect_success(res)
+        raise "expected 2xx, got #{res.code}: #{res.body.to_s[0, 200]}" unless res.code.to_i.between?(200, 299)
+      end
+
+      def expect_refused(res)
+        raise "expected a 4xx refusal, got #{res.code}" unless res.code.to_i.between?(400, 499)
+      end
+    end
+  end
+end

data/lib/hecks/cli/smoke_test.rb

@@ -3,7 +3,7 @@ require_relative "../bluebook/smoke_test"
 
 module Hecks
   module CLI
-    # The command behind `bin/smoke_test` and `hecks smoke_test`: boots a real domain
+    # The command behind `hecks smoke_test`: boots a real domain
     # and dispatches one synthesized call per declared command and report
     # (`Bluebook::SmokeTest`), printing every failure rather than the first.
     #
@@ -14,8 +14,10 @@ module Hecks
       module_function
 
       def call(argv, root:)
-        dir_arg = argv.first
-        targets = dir_arg ? [dir_arg] : Dir.glob("#{root}/examples/*/").map { |d| d.chomp("/") }.select { |d| wired?(d) }
+        missing = argv.reject { |dir| File.directory?(dir) }
+        abort "smoke_test: no such domain #{missing.first.inspect}" unless missing.empty?
+
+        targets = argv.empty? ? Dir.glob("#{root}/examples/*/").map { |d| d.chomp("/") }.select { |d| wired?(d) } : argv
         abort "no wired example domains found (none of examples/* has a .hecksagon)" if targets.empty?
 
         ok = targets.reduce(true) { |all_ok, dir| clean?(dir) && all_ok }

data/lib/hecks/cli/spec_example.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "rspec/core"
+
+module Hecks
+  module CLI
+    # The command behind `hecks run_spec_example`: runs one spec file filtered to one example
+    # through `RSpec::Core::Runner`, so a `hecks quality_control log --demonstration` string
+    # needs no `-e` quoting.
+    module SpecExample
+      USAGE = "usage: hecks run_spec_example <spec_file> <example description substring>"
+
+      module_function
+
+      # Runs the example whose description contains the substring.
+      #
+      # @param argv [Array<String>] the spec file, then the description substring
+      # @return [Integer] RSpec's own exit status: 0 when every example passed
+      # @raise [SystemExit] with the usage line unless exactly two arguments are given
+      def call(argv)
+        abort USAGE if argv.length != 2
+
+        RSpec::Core::Runner.run(["--example", argv[1], argv[0]])
+      end
+    end
+  end
+end

data/lib/hecks/cli/statements.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "../../hecks"
+
+module Hecks
+  module CLI
+    # The command behind `hecks statements`: prints a booted domain's declared facts as plain
+    # English sentences, through `Projections::Statements`.
+    module Statements
+      USAGE = "usage: hecks statements <domain-path> <ChapterName>"
+
+      module_function
+
+      # Boots the domain and prints one sentence per declared fact of the named chapter.
+      #
+      # @param argv [Array<String>] the domain path, then the chapter's name
+      # @param cwd [String] what a relative domain path resolves against
+      # @param out [IO] where the sentences go
+      # @return [Integer] the exit status, 0 once printed
+      # @raise [SystemExit] with the usage line when an argument is missing
+      def call(argv, cwd: Dir.pwd, out: $stdout)
+        domain_path, chapter_name = argv
+        abort USAGE unless domain_path && chapter_name
+
+        runtime = Hecks.boot(File.expand_path(domain_path, cwd))
+        chapter = runtime.registry.bluebook(chapter_name)
+        Hecks::Projector.call(:statements, bluebook: chapter).each { |statement| out.puts statement }
+        0
+      end
+    end
+  end
+end

data/lib/hecks/cli/stores.rb

@@ -3,8 +3,8 @@ require_relative "../../hecks"
 
 module Hecks
   module CLI
-    # The command behind `bin/stores` and `hecks stores`: every aggregate's current
-    # records as JSON (the head, not the journal — see `bin/history` for that).
+    # The command behind `hecks stores`: every aggregate's current
+    # records as JSON (the head, not the journal — see `hecks history` for that).
     module Stores
       module_function
 
@@ -13,10 +13,9 @@ module Hecks
       # @param argv [Array<String>] the domain directory, first
       # @param program [String] the name the error message calls this command by
       # @return [void]
-      # @raise [IndexError] when `argv` is empty
-      # @raise [SystemExit] when the domain directory does not exist
+      # @raise [SystemExit] when `argv` is empty or the domain directory does not exist
       def call(argv, program:)
-        domain = argv.fetch(0)
+        domain = argv.first or abort "usage: #{program} <domain>"
         unless Dir.exist?(domain)
           warn "#{program}: no such domain #{domain.inspect}"
           exit 1

data/lib/hecks/cli/stress_concurrency_specs.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "etc"
+require "open3"
+require "fileutils"
+
+module Hecks
+  module CLI
+    # The command behind `hecks stress_concurrency`: reruns the thread-safety specs under many
+    # seeds, several OS processes at a time. A clean run shows only "not in this many tries", never
+    # "impossible".
+    #
+    # CI can call it gated to pull requests that touch `lib/hecks/runtime/**`, as its own job so the
+    # repetition does not tax the single-pass suite; a GitHub Actions matrix leg can also run
+    # `--runs 1 --parallel 1 --seed-start N`.
+    module StressConcurrencySpecs
+      # The specs that prove a shared-state race is closed, listed by hand: a glob would also
+      # catch specs that only use threads for fixture setup. In-process specs share no external
+      # resource, so concurrent copies are safe.
+      PARALLEL_SAFE_SPEC_FILES = [
+        "spec/runtime/dispatcher_spec.rb",
+        "spec/adapters/driven/in_process_concurrent_dispatch_spec.rb"
+      ].freeze
+
+      # The Postgres spec drops and recreates one fixed database, so overlapping copies would fail
+      # with `PG::ConnectionBad`; it runs one process at a time.
+      SERIAL_ONLY_SPEC_FILES = [
+        "spec/adapters/driven/postgres_concurrent_dispatch_spec.rb"
+      ].freeze
+
+      USAGE = <<~TEXT
+        Usage: hecks stress_concurrency [--runs N] [--parallel N] [--seed-start N]
+
+          --runs N        How many times to run EACH group below (default 30).
+                           Each run uses a different --seed (seed-start + run
+                           index).
+          --parallel N    How many parallel-safe-group runs to have going as
+                           separate OS processes AT THE SAME TIME (default: this
+                           machine's own core count, via Etc.nprocessors) — real
+                           concurrent scheduler/CPU contention, not just varied
+                           seeds one after another. The Postgres-backed group
+                           always runs one process at a time regardless of this
+                           flag.
+          --seed-start N  First --seed value (default 1); runs use seed_start,
+                           seed_start + 1, ... seed_start + runs - 1.
+
+        Exits 0 if every run's every example passed, 1 if anything failed -
+        failing runs' full output is saved under tmp/stress-failures/
+        for a real repro (same seed, same command, just add CI=true).
+      TEXT
+
+      module_function
+
+      # Runs both groups under every seed and reports.
+      #
+      # @param argv [Array<String>] `--runs N`, `--parallel N`, `--seed-start N`, `--help`
+      # @param root [String] the checkout the specs run in
+      # @param out [IO] where the progress and verdict go
+      # @return [Integer] 0 when every run passed (or for `--help`), 1 on flakiness, 64 for an
+      #   unknown argument
+      def call(argv, root:, out: $stdout)
+        argv = argv.dup
+        settings = { runs: 30, parallel: Etc.nprocessors, seed_start: 1 }
+        status = parse!(argv, settings, out)
+        return status if status
+
+        results = run_all(root, settings, out)
+        report(root, results, out)
+      end
+
+      # @param argv [Array<String>] the arguments; consumed
+      # @param settings [Hash{Symbol => Integer}] filled in from the flags
+      # @param out [IO] where the usage goes for `--help`
+      # @return [Integer, nil] an exit status to stop with, or nil to go on
+      def parse!(argv, settings, out)
+        flags = { "--runs" => :runs, "--parallel" => :parallel, "--seed-start" => :seed_start }
+        until argv.empty?
+          arg = argv.shift
+          if flags.key?(arg)
+            settings[flags[arg]] = Integer(argv.shift)
+          elsif %w[--help -h].include?(arg)
+            out.puts USAGE
+            return 0
+          else
+            warn "unrecognized argument: #{arg.inspect} (--help for usage)"
+            return 64
+          end
+        end
+        nil
+      end
+
+      # @param root [String] the checkout the specs run in
+      # @param settings [Hash{Symbol => Integer}] `runs`, `parallel` and `seed_start`
+      # @param out [IO] where the progress goes
+      # @return [Array<Hash>] one result per run
+      def run_all(root, settings, out)
+        runs = settings[:runs]
+        seed_start = settings[:seed_start]
+        seeds = (seed_start...(seed_start + runs)).to_a
+        out.puts "Stress-running the parallel-safe group #{runs} time(s) (#{settings[:parallel]} at a time), " \
+                 "seeds #{seed_start}..#{seed_start + runs - 1}:"
+        PARALLEL_SAFE_SPEC_FILES.each { |f| out.puts "  - #{f}" }
+        out.puts "...and the Postgres-backed group #{runs} time(s), ONE PROCESS AT A TIME:"
+        SERIAL_ONLY_SPEC_FILES.each { |f| out.puts "  - #{f}" }
+        out.puts
+
+        results = []
+        seeds.each_slice(settings[:parallel]) do |batch|
+          batch_results = run_batch(root, PARALLEL_SAFE_SPEC_FILES, batch, label: "parallel-safe")
+          results.concat(batch_results)
+          batch_results.each { |result| out.print result[:success] ? "." : "F" }
+          out.flush
+        end
+        seeds.each do |seed|
+          result = run_once(root, SERIAL_ONLY_SPEC_FILES, seed, label: "postgres (serial)")
+          results << result
+          out.print result[:success] ? "." : "F"
+          out.flush
+        end
+        out.puts
+        out.puts
+        results
+      end
+
+      # `CI=true` un-excludes the `io: true` Postgres spec, which self-skips without a reachable
+      # server.
+      #
+      # @param root [String] the checkout to run in
+      # @param spec_files [Array<String>] the spec files
+      # @param seed [Integer] the `--seed` value
+      # @param label [String] which group this run belongs to
+      # @return [Hash] `label`, `seed`, `success`, `output` and how to `reproduce` it
+      def run_once(root, spec_files, seed, label:)
+        command = ["bundle", "exec", "rspec", *spec_files, "--seed", seed.to_s, "--format", "progress"]
+        stdout, status = Open3.capture2e({ "CI" => "true" }, *command, chdir: root)
+        { label: label, seed: seed, success: status.success?, output: stdout,
+          reproduce: "CI=true bundle exec rspec #{spec_files.join(' ')} --seed #{seed}" }
+      end
+
+      # One thread per child process: `Open3.capture2e` already spawns a real process per call.
+      #
+      # @param root [String] the checkout to run in
+      # @param spec_files [Array<String>] the spec files
+      # @param seeds [Array<Integer>] the seeds to run at the same time
+      # @param label [String] which group these runs belong to
+      # @return [Array<Hash>] one result per seed
+      def run_batch(root, spec_files, seeds, label:)
+        seeds.map { |seed| Thread.new { run_once(root, spec_files, seed, label: label) } }.map(&:value)
+      end
+
+      # @param root [String] the checkout; failing runs' output is saved under its `tmp/`
+      # @param results [Array<Hash>] every run's result
+      # @param out [IO] where the verdict goes
+      # @return [Integer] 0 when every run passed, else 1
+      def report(root, results, out)
+        failures = results.reject { |r| r[:success] }
+        if failures.empty?
+          out.puts "CLEAN — #{results.size}/#{results.size} runs passed. " \
+                   "No new flakiness beyond a single ordinary `rspec` run found in this many tries."
+          return 0
+        end
+
+        dir = File.join(root, "tmp/stress-failures")
+        FileUtils.mkdir_p(dir)
+        out.puts "FOUND FLAKINESS — #{failures.size}/#{results.size} runs failed:"
+        failures.each do |failure|
+          path = File.join(dir, "#{failure[:label].tr(' ', '_').gsub(/[()]/, '')}-seed#{failure[:seed]}.log")
+          File.write(path, failure[:output])
+          out.puts "  [#{failure[:label]}] seed #{failure[:seed]} — output saved to #{path.sub("#{root}/", '')}"
+          out.puts "    reproduce: #{failure[:reproduce]}"
+        end
+        out.puts
+        1
+      end
+    end
+  end
+end