hecks 2.8.0 → 3.0.0

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,29 +3,21 @@ 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.
     #
-    # It needs a real `.hecksagon`: a bare `.bluebook` with nothing bound to an
-    # adapter has nothing to run commands against. A failure may be a domain bug or
-    # a value the synthesizer's naive choices (0, an empty list, "smoke-test") cannot
-    # satisfy; the message underneath says which. Smoke-testing proves nothing
+    # Needs a real `.hecksagon`; a failure may be a domain bug or a value the
+    # synthesizer's naive choices cannot satisfy — smoke-testing proves nothing
     # crashes, not that an answer is right.
     module SmokeTest
       module_function
 
-      # Smoke-tests the domain `argv` names, or every wired domain under
-      # `root/examples/`, and exits with the verdict.
-      #
-      # @param argv [Array<String>] an optional domain directory
-      # @param root [String] the directory whose `examples/*` are tested when `argv`
-      #   names no domain
-      # @return [void]
-      # @raise [SystemExit] always: 0 when clean, 1 with failures or no domain found
       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 }
@@ -35,10 +27,6 @@ module Hecks
         exit(ok ? 0 : 1)
       end
 
-      # Says whether `dir`, or something nested under it, is a bindable domain.
-      #
-      # @param dir [String] a directory to check
-      # @return [Boolean] true if `dir` contains at least one `.hecksagon` file
       def wired?(dir) = !Dir.glob(File.join(dir, "**/*.hecksagon")).empty?
 
       # @api private

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,9 +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 rather than the journal (`bin/history` prints the
-    # full write history).
+    # 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
 
@@ -14,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