hecks 2.8.0 → 3.0.0

data/lib/hecks/doors/handle.rb

@@ -0,0 +1,206 @@
+require_relative "../naming"
+require_relative "../runtime/caller"
+require_relative "../ports/authorization"
+
+module Hecks
+  module Doors
+    # A record in hand: what `Pizza.create_pizza!(...)` and `Pizza.find(id)`
+    # give back. One shared class per aggregate; verbs are per-handle singleton methods.
+    #
+    #     Pizza.create_pizza!(...).add_topping!(...).purchase!(...)
+    class Handle
+      attr_reader :id
+
+      # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted
+      #   dispatcher this record's verbs, `events` and `reload` go through
+      # @param domain [String] the owning chapter's name, the first half of `fqn`
+      # @param aggregate [Bluebook::Aggregate] the IR of the aggregate this record is one of
+      # @param instance [Runtime::Instance] the stored record; its `id` and `state` are
+      #   read once here and the instance itself is not retained
+      def initialize(dispatcher:, domain:, aggregate:, instance:)
+        @dispatcher = dispatcher
+        @domain     = domain
+        @ir         = aggregate
+        @id         = instance.id
+        @state      = instance.state
+        define_reference_accessors
+        define_verb_methods
+      end
+
+      # Reads one field's raw stored value, without hydrating a reference the way the
+      # reference accessor of the same name does.
+      #
+      # @param key [Symbol, String] the attribute name
+      # @return [Object, nil] the value held in state (a scalar, a value object, a list,
+      #   or a referenced record's id); `nil` when the field is unset or not in state
+      def [](key) = redacted(key.to_sym)
+
+      # Answers the record's state as a Hash, with `:id` merged in last so it
+      # always wins over a same-named `id` attribute (BurningManPrep::Item).
+      #
+      # @return [Hash{Symbol => Object}] every state field by attribute name, plus `:id`
+      def to_h = @state.to_h { |key, _| [key, redacted(key)] }.merge(id: @id)
+
+      # Names the aggregate this record belongs to, in the form every dispatch verb and
+      # event is addressed by.
+      #
+      # @return [String] the fully qualified aggregate name, such as `"Pizzas::Pizza"`
+      def fqn = "#{@domain}::#{@ir.hecks_name}"
+
+      # Lists the events this one record has emitted, filtered out of the dispatcher's
+      # whole event log on each call.
+      #
+      # @return [Array<Runtime::Event>] this record's events in the order the log holds
+      #   them; `[]` when it has emitted none
+      def events
+        @dispatcher.events.select { |event| event.aggregate == fqn && event.id == @id }
+      end
+
+      # Refreshes this handle's state from the repository, picking up writes made through
+      # another handle or door. Keeps the current state when the record is not found.
+      #
+      # @return [Doors::Handle] this handle, so the call chains
+      # @raise [Runtime::WiringError] if the aggregate's persistence bind cannot be
+      #   resolved into a repository
+      def reload
+        stored = repository.find(@id)
+        @state = stored.state if stored
+        self
+      end
+
+      # Equality is (fqn, id): two handles to the same record are equal, and
+      # `other.is_a?(self.class)` can't tell aggregates apart since they share one class.
+      #
+      # @param other [Object] anything; only another `Handle` can be equal
+      # @return [Boolean] true when `other` is a `Handle` with the same `fqn` and `id`
+      def ==(other) = other.is_a?(Handle) && other.fqn == fqn && other.id == @id
+      alias eql? ==
+      def hash = [Handle, fqn, @id].hash
+
+      def inspect
+        fields = @state.map { |key, value| "#{key}=#{value.inspect}" }.join(" ")
+        "#<#{@ir.hecks_name} #{@id} #{fields}>"
+      end
+      alias to_s inspect
+
+      # Answers a field reader: `pizza.name` reads `name` out of state. A
+      # declared field not yet written arrives here too, as `nil`.
+      #
+      # @param name [Symbol] the method called, read as an attribute or lifecycle field name
+      # @param args [Array<Object>] ignored by a reader; passed on to `super` otherwise
+      # @param kwargs [Hash{Symbol => Object}] ignored by a reader; passed on to `super` otherwise
+      # @return [Object, nil] the field's value; `nil` when nothing is written yet
+      # @raise [NoMethodError] if `name` is neither a key in state nor a declared field
+      def method_missing(name, *args, **kwargs, &)
+        return redacted(name) if @state.key?(name) || reader?(name)
+
+        super
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @state.key?(name) || reader?(name) || super
+      end
+
+      private
+
+      def repository = @dispatcher.registry.repository(@domain, @ir)
+
+      # Masks any Privacy::Marking leaf the caller isn't granted to read, and
+      # masks an unidentified caller outright (a leak is worse than a refusal
+      # commands allow). Nesting is masked one level deep only.
+      def redacted(field)
+        raw = @state[field]
+        rows = marked_paths.select { |row| row[:attribute_path][:value].to_s.split(".", 2).first == field.to_s }
+        return raw if rows.empty?
+
+        rows.each do |row|
+          path = row[:attribute_path][:value].to_s
+          next if authorized_for?(row[:readable_by][:value].to_s)
+
+          segments = path.split(".", 2)
+          if segments.size == 1
+            raw = "[redacted]"
+          elsif raw.is_a?(Runtime::Value)
+            raw = raw.with(segments[1], "[redacted]")
+          end
+        end
+
+        raw
+      end
+
+      # Cached per handle so an unattached-Privacy domain never pays for a query
+      # dispatch on every read.
+      def marked_paths
+        return @marked_paths if defined?(@marked_paths)
+        return @marked_paths = [] unless @dispatcher.registry.bluebook("Privacy")
+
+        @marked_paths = @dispatcher.query("Privacy::Marking.ForDomain", domain: fqn)
+      end
+
+      # False outright for an unidentified caller or an unattached domain, never
+      # the weak fallback a command's own role check allows.
+      def authorized_for?(role)
+        caller = Runtime::Caller.current
+        return false unless caller&.actor_id
+        return false unless @dispatcher.registry.authorization_provider_for(@domain)
+
+        Ports::Authorization.holds_role?(@dispatcher.registry, actor_id: caller.actor_id, role: role,
+                                                                 as_of: caller.as_of, scope: caller.scope)
+      end
+
+      def reader?(name)
+        !@ir.attribute(name).nil? || @ir.lifecycle&.field&.to_sym == name
+      end
+
+      # Real singleton methods, not method_missing: a verb named `freeze` or
+      # `send` (both real, e.g. Account::Freeze, ExternalTransfer::Send) would
+      # otherwise silently hit the Kernel method instead of dispatching.
+      def define_verb_methods
+        @ir.commands.reject(&:creates?).each do |command|
+          define_singleton_method("#{Naming.snake(command.hecks_name)}!") do |**args|
+            run(command, **args)
+          end
+        end
+      end
+
+      # `@ir.identified_by` is only the single-head shorthand (nil for a
+      # composite identity, e.g. SafeDepositBox's branch_code/box_number);
+      # this reads every head through `identity_heads` instead.
+      def run(command, **args)
+        @state = @dispatcher.dispatch("#{fqn}.#{command.hecks_name}", to: @id, with: args).instance.state
+        self
+      end
+
+      # Lazy hop: `transfer.source_account` resolves to the actual record only
+      # when called; nothing loads until then, so chains like
+      # `payment.disputed_by_customer.name` stay lazy at every step.
+      #
+      # Defined before verb methods so a same-named verb wins the name on the
+      # rare collision; `initialize` calls this first for that reason.
+      #
+      # The accessor is named like the attribute itself, never `<name>_id`
+      # (ADR 0025) — `piece.account` and `piece[:account]` (bracket access,
+      # the raw id) never collide despite sharing a name.
+      def define_reference_accessors
+        @ir.attributes.select(&:reference?).each do |attribute|
+          target = attribute.type.resolve
+          # Cross-domain, or otherwise unresolvable — no accessor rather than a guess.
+          next unless target
+
+          domain     = @domain
+          field      = attribute.name
+          list       = attribute.list?
+          target_fqn = "#{domain}::#{target.hecks_name}"
+
+          define_singleton_method(field) do
+            value = self[field]
+            door = Object.const_get(target_fqn)
+            next Array(value).map { |identity| door.find(identity) } if list
+
+            value && door.find(value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/doors/json_door.rb

@@ -0,0 +1,132 @@
+require "json"
+require_relative "handle"
+require_relative "command_request"
+require_relative "../naming"
+require_relative "../runtime/errors"
+require_relative "../runtime/value"
+
+module Hecks
+  module Doors
+    # The JSON door: translates URL segments and parsed JSON bodies to and from the facade.
+    # No HTTP lives here; every miss raises `Runtime::NotFound`, distinguished by message.
+    module JsonDoor
+      module_function
+
+      # Resolves a domain name and an aggregate name, as two URL segments carry them, to
+      # that aggregate's door.
+      #
+      # The name is checked against the current boot's IR before Ruby's constant table, so
+      # a stale same-named constant from an earlier boot is never returned.
+      #
+      # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted dispatcher
+      # @param domain [String, Symbol] the chapter name, such as `"Banking"`
+      # @param name [String, Symbol] the aggregate's declared name, such as `"Customer"`
+      # @return [Module] the aggregate door installed at `domain::name`
+      # @raise [Runtime::NotFound] if the chapter or its aggregate is not declared
+      # @raise [NameError] if the aggregate has no facade constant (`install_doors: false`)
+      def aggregate(dispatcher, domain, name)
+        ir = dispatcher.registry.bluebook(domain)&.aggregate(name)
+        raise Runtime::NotFound, "#{domain} declares no aggregate named #{name.inspect}" unless ir
+
+        Object.const_get("#{domain}::#{ir.hecks_name}")
+      end
+
+      # Names the door method that creates a record of this aggregate: the first command
+      # it declares that `creates?`, spelled as a Ruby caller would (`"create_pizza!"`).
+      #
+      # @param klass [Module] an aggregate door, as `aggregate` returns
+      # @return [String] the method name to `public_send` to the door
+      # @raise [Runtime::NotFound] if the aggregate declares no creating command
+      def creating_command(klass)
+        creating = klass.ir.commands.find(&:creates?)
+        raise Runtime::NotFound, "#{klass.ir.hecks_name} declares no creating command" unless creating
+
+        "#{Naming.snake(creating.hecks_name)}!"
+      end
+
+      # Confirms that a command name arriving as text is one a `Handle` of this aggregate
+      # answers, before a caller `public_send`s it.
+      #
+      # A `Handle` defines only the non-creating commands, so the creating command is
+      # rejected here rather than failing later as a raw `NoMethodError`.
+      #
+      # @param klass [Module] an aggregate door, as `aggregate` returns
+      # @param name [String, Symbol] the wanted method name with its bang, such as
+      #   `"add_topping!"`
+      # @return [String] `name` as a String, unchanged, when a `Handle` answers it
+      # @raise [Runtime::NotFound] if no non-creating command has that method name
+      def validate_command!(klass, name)
+        wanted = name.to_s
+        dispatchable = klass.ir.commands.reject(&:creates?).map { |command| "#{Naming.snake(command.hecks_name)}!" }
+        return wanted if dispatchable.include?(wanted)
+
+        raise Runtime::NotFound, "#{klass.ir.hecks_name} declares no command named #{wanted.inspect}"
+      end
+
+      # Fetches one record by id, raising instead of answering nil on a miss.
+      #
+      # @param klass [Module] an aggregate door, as `aggregate` returns
+      # @param id [String] the record's identity, as the URL carried it
+      # @return [Doors::Handle] the record in hand
+      # @raise [Runtime::NotFound] if the repository holds no record with that id
+      def find!(klass, id)
+        klass.find(id) or raise Runtime::NotFound, "no #{klass.ir.hecks_name} found for id #{id.inspect}"
+      end
+
+      # Converts every Hash key to a Symbol, at every depth of a parsed JSON body.
+      #
+      # @param value [Hash, Array, Object] parsed JSON: a Hash or Array is walked, any
+      #   other value is a leaf
+      # @return [Hash{Symbol => Object}, Array, Object] a new structure of the same shape
+      #   with Symbol keys; a leaf is returned as it came
+      def deep_symbolize(value)
+        case value
+        when Hash  then value.to_h { |k, v| [k.to_sym, deep_symbolize(v)] }
+        when Array then value.map { |item| deep_symbolize(item) }
+        else value
+        end
+      end
+
+      # Unwraps a record, a query row, or any value holding `Runtime::Value`s into plain
+      # Hashes, Arrays and scalars a JSON encoder can walk.
+      #
+      # Delegates to `Runtime::Value.materialize`; the only addition is `#to_h` on a
+      # `Handle`, which `materialize` does not recognize.
+      #
+      # @param value [Doors::Handle, Runtime::Value, Hash, Array, Object] what to unwrap;
+      #   a `Handle` is read through its `to_h`, so its `:id` comes along
+      # @return [Hash, Array, Object] the same data with every `Runtime::Value` replaced
+      #   by a Hash of its fields; any other value is returned as it came
+      def materialize(value)
+        value = value.to_h if value.is_a?(Handle)
+        Runtime::Value.materialize(value)
+      end
+
+      # Turns a command's JSON body, raw or already parsed, into the `to:`/`with:`
+      # envelope a dispatcher takes. The result splats into `Dispatcher#dispatch`.
+      #
+      # @param body [String, Hash] raw JSON text, or the Hash it parses to
+      # @param receiver [Symbol, nil] `:aggregate`, `:entity`, or `nil` for none
+      #   (see `CommandRequest.normalize`)
+      # @param legacy_receiver [Symbol, String, Hash{Symbol => Symbol, String}, nil] the flat key,
+      #   or pair of keys, a body without `to` may name its receiver under; `nil` accepts none
+      # @return [Hash{Symbol => Object}] `{ with: facts }`, plus `to:` unless `receiver` is `nil`
+      # @raise [JSON::ParserError] if `body` is a String that is not valid JSON
+      # @raise [Runtime::TypeMismatch] if the body is not a JSON object or its routing is malformed
+      # @raise [ArgumentError] if `receiver` is not `nil`, `:aggregate` or `:entity`
+      def command_request(body, receiver:, legacy_receiver: nil)
+        input = body.is_a?(String) ? parse(body) : body
+        CommandRequest.normalize(input, receiver: receiver, legacy_receiver: legacy_receiver)
+      end
+
+      # Parses a raw request body, leaving keys as Strings. `JSON::ParserError` propagates
+      # unwrapped.
+      #
+      # @param raw_json [String] JSON text, such as a POST body
+      # @return [Hash{String => Object}, Array, String, Numeric, Boolean, nil] whatever
+      #   the text encodes
+      # @raise [JSON::ParserError] if the text is not valid JSON
+      def parse(raw_json) = JSON.parse(raw_json)
+    end
+  end
+end

data/lib/hecks/doors/launcher_options.rb

@@ -0,0 +1,129 @@
+require_relative "../ports/identity_generation"
+require_relative "../runtime/errors"
+require_relative "cli_door"
+
+module Hecks
+  module Doors
+    # What a domain's world file adds to its generated launcher, all of it opt-in.
+    #
+    # A `.world` that declares a `launcher` setting switches these on for that chapter; a
+    # domain without one keeps the launcher's plain forms exactly:
+    #
+    #     launcher "Launcher", run_keys: true, failure_states: %w[flagged failed],
+    #                          names: { "mcp" => "serve_mcp" }
+    #
+    # - **run_keys** mints the `run` key of a creating command that was given none.
+    # - **failure_states** are the lifecycle states `--wait` reports as a failure (exit 1).
+    # - **names** maps a launcher name to the command it stands for (see `CliProjector`).
+    module LauncherOptions
+      SETTING = "launcher".freeze
+      WAIT    = "--wait".freeze
+      RUN_KEY = "run.value".freeze
+
+      module_function
+
+      # Reads a chapter's `launcher` setting.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
+      # @param chapter [String] the chapter the command line speaks to
+      # @return [Hash{Symbol => Object}, nil] the setting, or nil when the chapter did not opt in
+      def settings(runtime, chapter)
+        return unless runtime.respond_to?(:registry)
+
+        found = runtime.registry.world(chapter)&.for_verb(SETTING)
+        found.nil? || found.empty? ? nil : found
+      end
+
+      # The options the launcher's projection is asked for: the program's name, the chapter's
+      # launcher names, and whether run keys are minted (so help shows them optional).
+      #
+      # @param settings [Hash, nil] the chapter's `launcher` setting
+      # @param program [String] how the caller was invoked
+      # @return [Hash{Symbol => Object}] the options `Projector::CliProjector` reads
+      def projection(settings, program)
+        { program: program, names: settings && settings[:names], mint_run_keys: settings && settings[:run_keys] }
+      end
+
+      # Takes `--wait` out of a verb's words, unless the verb declares a `wait` argument of its own.
+      #
+      # `--wait=false` (or `no`, `0`, `off`) is a `--wait` that was switched off; a bare `--wait`
+      # may be followed by its Boolean word.
+      #
+      # @param spec [Hash] the verb's projected spec
+      # @param words [Array<String>] the words after the verb
+      # @return [Array(Array<String>, Boolean)] the remaining words, and whether `--wait` was given
+      # @raise [Runtime::TypeMismatch] if `--wait=` carries something that is not a Boolean word
+      def take_wait(spec, words)
+        return [words, false] unless words.any? { |word| wait_word?(word) }
+        return [words, false] if spec[:arguments].any? { |argument| argument[:path].split(".").first == "wait" }
+
+        wait  = false
+        rest  = []
+        queue = words.dup
+        until queue.empty?
+          word = queue.shift
+          wait_word?(word) ? wait ||= CliDoor.boolean(wait_value(word, queue)) : rest << word
+        end
+        [rest, wait]
+      end
+
+      # @api private
+      def wait_word?(word) = word == WAIT || word.start_with?("#{WAIT}=")
+
+      # The Boolean word a `--wait` carries: after `=`, or the next word when it is one.
+      # @api private
+      def wait_value(word, queue)
+        return word.split("=", 2).last if word.include?("=")
+
+        CliDoor::BOOLEAN_WORDS.key?(queue.first.to_s.downcase) ? queue.shift : "true"
+      end
+
+      # Whether a question's text answer reports a gap, which `--wait` turns into a failing exit.
+      #
+      # The coverage checks end their report with a `GAP (n)` heading; a non-zero count is a
+      # finding, and a CI stage that waits on the question fails on it.
+      #
+      # @param text [String, nil] the question's text answer
+      # @return [Boolean] whether a `GAP (n)` heading with n above zero is in the text
+      def gap_reported?(text)
+        text.is_a?(String) && text.match?(/^GAP \((?!0\))\d+\)/)
+      end
+
+      # Mints the `run` key a creating command was not given, when the domain opted in.
+      #
+      # An explicit key always wins. Nothing is minted for a command that acts on an existing
+      # record. When no identity adapter is bound the run is refused, saying to name a key,
+      # rather than sent on without one.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
+      # @param spec [Hash] the verb's projected spec
+      # @param args [Hash] the parsed arguments
+      # @param settings [Hash, nil] the chapter's `launcher` setting
+      # @return [Array(Hash, String)] the arguments, and the key minted (nil when none was)
+      # @raise [Runtime::NotFound] if a key is owed but no identity adapter is bound
+      def run_key(runtime, spec, args, settings)
+        return [args, nil] unless settings && settings[:run_keys] && spec[:creates]
+        return [args, nil] unless spec[:arguments].any? { |argument| argument[:path] == RUN_KEY }
+        return [args, nil] if args.key?(:run) || !runtime.respond_to?(:registry)
+
+        key = Ports::IdentityGeneration.uuid(runtime.registry)
+        [args.merge(run: { value: key }), key]
+      rescue Runtime::WiringError => e
+        raise Runtime::NotFound, "cannot mint a run key (#{e.message.lines.first.strip}); name one with run=<key>"
+      end
+
+      # Whether a settled record sits in one of the chapter's failure states.
+      #
+      # @param aggregate [Bluebook::Aggregate, nil] the record's aggregate
+      # @param state [Hash, nil] the record's state
+      # @param settings [Hash, nil] the chapter's `launcher` setting
+      # @return [Boolean] false when the aggregate has no lifecycle
+      def failed?(aggregate, state, settings)
+        field = aggregate&.lifecycle&.field
+        return false unless field && state
+
+        Array(settings && settings[:failure_states]).map(&:to_s).include?(state[field.to_sym].to_s)
+      end
+    end
+  end
+end