hecks 3.5.0 → 3.7.0

data/lib/hecks/cli/seed_semantics_corpus.rb

@@ -38,20 +38,26 @@ module Hecks
       # @return [Integer] the exit status, always 0
       def call(root:, env: ENV, out: $stdout)
         only = env.fetch("SEED", nil)
-        seeded = corpus_paths(root).filter_map do |path, domain, full|
-          fixture = JSON.parse(File.read(path))
-          name = File.basename(path, ".json")
-          next if only ? only != name : fixture.key?("expect")
-
-          fixture["domain"] ||= domain if domain
-          fixture["expect"] = expectation_for(root, fixture, full: full)
-          File.write(path, "#{JSON.pretty_generate(fixture)}\n")
-          name
-        end
+        seeded = corpus_paths(root).filter_map { |path, domain, full| seed_fixture(root, path, domain, full, only) }
         report(out, seeded)
         0
       end
 
+      # Seeds one fixture unless it already carries an expect (or is not the one named).
+      #
+      # @api private
+      # @return [String, nil] the fixture's name when it was written
+      def seed_fixture(root, path, domain, full, only)
+        fixture = JSON.parse(File.read(path))
+        name = File.basename(path, ".json")
+        return if only ? only != name : fixture.key?("expect")
+
+        fixture["domain"] ||= domain if domain
+        fixture["expect"] = expectation_for(root, fixture, full: full)
+        File.write(path, "#{JSON.pretty_generate(fixture)}\n")
+        name
+      end
+
       # @param root [String] the checkout
       # @return [Array<Array>] `[path, domain_to_add_or_nil, full_expect?]` for every seedable file
       def corpus_paths(root)
@@ -72,17 +78,31 @@ module Hecks
       def expectation_for(root, fixture, full: false)
         result = Hecks::Fuzzing::Replay.call(File.join(root, fixture["domain"]), fixture["steps"])
         expect = {
-          "refusals"  => JSON.parse(JSON.generate(result[:refusals])).each { |r| r["kind"] = r["kind"]&.split("::")&.last },
-          "instances" => JSON.parse(JSON.generate(result[:instances])),
-          "events"    => JSON.parse(JSON.generate(result[:events])).each { |e| e.delete("occurred_at") }
+          "refusals"  => kind_names(result[:refusals]),
+          "instances" => roundtrip(result[:instances]),
+          "events"    => without_timestamps(result[:events])
         }
-        return expect unless full
+        full ? expect.merge!(conformance_expectation(result)) : expect
+      end
+
+      # @api private
+      def kind_names(refusals) = roundtrip(refusals).each { |r| r["kind"] = r["kind"]&.split("::")&.last }
 
+      # @api private
+      def without_timestamps(events) = roundtrip(events).each { |e| e.delete("occurred_at") }
+
+      # @api private
+      # @return [Hash{String => Array}] the queries, sagas, dry runs and reactions a run froze
+      def conformance_expectation(result)
         # instances_at is Replay's per-query snapshot for the property harness, not an outcome.
-        expect["queries"] = JSON.parse(JSON.generate(result[:queries].map { |q| q.except(:instances_at) }))
-        expect.merge!(CONFORMANCE_KEYS.drop(1).to_h { |k| [k, JSON.parse(JSON.generate(result[k.to_sym]))] })
+        queries = roundtrip(result[:queries].map { |q| q.except(:instances_at) })
+        { "queries" => queries }.merge(CONFORMANCE_KEYS.drop(1).to_h { |k| [k, roundtrip(result[k.to_sym])] })
       end
 
+      # @api private
+      # @return [Object] `value` as JSON would hand it back: String keys, plain collections
+      def roundtrip(value) = JSON.parse(JSON.generate(value))
+
       # @param out [IO] where the report goes
       # @param seeded [Array<String>] the fixtures written
       # @return [void]
@@ -90,7 +110,7 @@ module Hecks
         if seeded.empty?
           out.puts "nothing to seed — every fixture carries its expect (pass SEED=<name> to re-seed one deliberately)"
         else
-          out.puts "seeded: #{seeded.join(', ')}"
+          out.puts "seeded: #{seeded.join(", ")}"
           out.puts "review each expect against docs/semantics/bluebook-semantics.md before committing — " \
                    "it is the definition now"
         end

data/lib/hecks/cli/smoke_http/checks.rb

@@ -0,0 +1,66 @@
+module Hecks
+  module CLI
+    class SmokeHttp
+      # The signed-webhook checks a run makes, each reported ok or failed.
+      module Checks
+        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
+      end
+    end
+  end
+end

data/lib/hecks/cli/smoke_http/settings.rb

@@ -0,0 +1,63 @@
+require "optparse"
+
+module Hecks
+  module CLI
+    class SmokeHttp
+      # Reads the command line and environment into the settings a run needs; `SmokeHttp`
+      # extends it, so these are its class methods.
+      module Settings
+        # 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 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 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 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 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
+      end
+    end
+  end
+end

data/lib/hecks/cli/smoke_http/transport.rb

@@ -0,0 +1,45 @@
+require "net/http"
+
+module Hecks
+  module CLI
+    class SmokeHttp
+      # The HTTP calls a run makes to the service under check, and the status assertions on them.
+      module Transport
+        private
+
+        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
+end

data/lib/hecks/cli/smoke_http.rb

@@ -4,11 +4,18 @@ require "net/http"
 require "openssl"
 require "json"
 require "optparse"
+require_relative "smoke_http/settings"
+require_relative "smoke_http/checks"
+require_relative "smoke_http/transport"
 
 module Hecks
   module CLI
     # One run of the checks against one service.
     class SmokeHttp
+      include Checks
+      include Transport
+      extend Settings
+
       # The signature header value for a body, per scheme.
       module Signature
         SCHEMES = %w[timestamped sha256 hex].freeze
@@ -23,7 +30,7 @@ module Hecks
             "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(', ')}"
+          else raise ArgumentError, "unknown scheme #{scheme.inspect}; expected one of #{SCHEMES.join(", ")}"
           end
         end
 
@@ -47,58 +54,6 @@ module Hecks
         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)
@@ -121,62 +76,6 @@ module Hecks
 
       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
@@ -192,39 +91,6 @@ module Hecks
       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

@@ -17,14 +17,28 @@ module Hecks
         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
+        targets = targets_for(argv, root)
         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 }
+        finish(targets.reduce(true) { |all_ok, dir| clean?(dir) && all_ok })
+      end
 
+      # Prints the verdict and exits with its status.
+      #
+      # @api private
+      def finish(passed)
         puts
-        puts ok ? "Every declared command and report dispatched cleanly." : "SMOKE TEST FOUND PROBLEMS."
-        exit(ok ? 0 : 1)
+        puts passed ? "Every declared command and report dispatched cleanly." : "SMOKE TEST FOUND PROBLEMS."
+        exit(passed ? 0 : 1)
+      end
+
+      # The named domains, or every wired example under `root` when none is named.
+      #
+      # @api private
+      def targets_for(argv, root)
+        return argv unless argv.empty?
+
+        Dir.glob("#{root}/examples/*/").map { |d| d.chomp("/") }.select { |d| wired?(d) }
       end
 
       def wired?(dir) = !Dir.glob(File.join(dir, "**/*.hecksagon")).empty?

data/lib/hecks/cli/stores.rb

@@ -21,14 +21,17 @@ module Hecks
           exit 1
         end
 
-        registry = Hecks.boot(domain).registry
-        stores = registry.bluebooks.each_with_object({}) do |(name, bluebook), all|
+        puts JSON.generate(stores_of(Hecks.boot(domain).registry))
+      end
+
+      # @param registry [Runtime::Registry] a booted domain's registry
+      # @return [Hash{String => Hash}] each aggregate's dump, keyed by its storage name
+      def stores_of(registry)
+        registry.bluebooks.each_with_object({}) do |(name, bluebook), all|
           bluebook.aggregates.each do |aggregate|
             all[aggregate.storage_name] = data_for(registry.repository(name, aggregate))
           end
         end
-
-        puts JSON.generate(stores)
       end
 
       # Reads one aggregate's current records as plain JSON-ready hashes, ordered by id.

data/lib/hecks/cli/stress_concurrency_specs/reporting.rb

@@ -0,0 +1,44 @@
+require "fileutils"
+
+module Hecks
+  module CLI
+    module StressConcurrencySpecs
+      # The verdict of a stress run: the clean line, or each failing run's saved log and how to
+      # reproduce it. `StressConcurrencySpecs` extends it.
+      module Reporting
+        # @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
+
+          out.puts "FOUND FLAKINESS — #{failures.size}/#{results.size} runs failed:"
+          failures.each { |failure| save_failure(root, failure, out) }
+          out.puts
+          1
+        end
+
+        # Saves a failing run's full output and says where it went and how to reproduce it.
+        #
+        # @param root [String] the checkout; the log goes under its `tmp/stress-failures/`
+        # @param failure [Hash] a failed run's result
+        # @param out [IO] where the pointer goes
+        # @return [void]
+        def save_failure(root, failure, out)
+          dir = File.join(root, "tmp/stress-failures")
+          FileUtils.mkdir_p(dir)
+          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
+      end
+    end
+  end
+end

data/lib/hecks/cli/stress_concurrency_specs/usage.rb

@@ -0,0 +1,28 @@
+module Hecks
+  module CLI
+    module StressConcurrencySpecs
+      USAGE = <<~TEXT.freeze
+        Usage: hecks stress_concurrency [--runs N] [--parallel N] [--seed-start N]
+
+          --runs N        How many times to run EACH group below. 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; runs use seed_start,
+                           seed_start + 1, ... seed_start + runs - 1.
+
+        `hecks stress_concurrency` fills --runs and --seed-start from the defaults its
+        bluebook declares (`hecks stress_concurrency --help` shows them).
+
+        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
+    end
+  end
+end