hecks 3.10.0 → 3.12.0

data/lib/hecks/doors/cli_runner.rb

@@ -1,66 +0,0 @@
-require "json"
-require_relative "cli_door"
-require_relative "command_request"
-require_relative "json_door"
-require_relative "launcher_options"
-require_relative "../projector"
-require_relative "../ports/clock"
-require_relative "cli_runner/answers"
-require_relative "cli_runner/resolution"
-require_relative "cli_runner/settling"
-require_relative "cli_runner/streaming"
-require_relative "cli_runner/suggestions"
-
-module Hecks
-  module Doors
-    # Parses and dispatches a command line against a `Projector::CliProjector` projection.
-    # Does no IO: it answers `[text, status]` and leaves printing and exiting to its callers.
-    module CliRunner
-      # The class an adapter raises when the tool it wraps refuses.
-      TOOL_REFUSAL = "Hecks::Adapters::ConsoleCapture::Failure".freeze
-      # The words that open the query namespace; `ask` is the older spelling.
-      QUERY_WORDS = %w[query ask].freeze
-
-      extend Resolution
-      extend Suggestions
-      extend Answers
-      extend Settling
-      extend Streaming
-
-      module_function
-
-      # Runs one command line against a booted domain and answers the text to print.
-      # The booted domain's own chapter is projected, or an attached one its first word names.
-      #
-      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
-      # @param argv [Array<String>] an optional `query` (or `ask`), the command or query name, then
-      #   `path=value` pairs; `--help`, `-h`, `help` or nothing answers usage
-      # @param program [String] how the caller was invoked, echoed in usage and hints
-      # @return [Array(String, Integer)] the text and the status: 0 answered, 1 refused or misused
-      # @raise [Runtime::WiringError] if a repository or the clock adapter cannot be resolved
-      # @raise [Runtime::StaleWrite] if concurrent writers beat the command through every retry
-      def call(runtime:, argv:, program: "hecks run")
-        plan = resolve(runtime, argv, program)
-        return plan[:answer] if plan[:answer]
-
-        dispatch(runtime, plan[:spec], plan[:name], plan[:rest], plan[:program], plan[:asking],
-                 bluebook: plan[:bluebook], launcher: plan[:launcher])
-      end
-
-      # Answers a command line that asks only for usage, from the projection alone.
-      #
-      # Needs a registry and no bound adapter, so a `Runtime::Loader::Described` serves: the
-      # help text, the no-argument usage, a command's `--help` and an unknown one's hint all come
-      # out byte-identical to `call`'s.
-      #
-      # @param runtime [#registry] a booted domain, or what `Hecks.describe` answers
-      # @param argv [Array<String>] as for `call`
-      # @param program [String] how the caller was invoked
-      # @return [Array(String, Integer), nil] the text and status, or nil when the line would
-      #   run a command or question and so needs a booted domain
-      def usage(runtime:, argv:, program: "hecks run")
-        UsageCache.fetch(runtime, argv, program, audience: audience_key) { resolve(runtime, argv, program)[:answer] }
-      end
-    end
-  end
-end

data/lib/hecks/doors/command_request.rb

@@ -1,119 +0,0 @@
-require_relative "../runtime/errors"
-
-module Hecks
-  module Doors
-    # Turns an external command request into the dispatcher's `to:`/`with:` envelope.
-    #
-    #   aggregate command: { to: "record-id", with: { declared: "facts" } }
-    #   entity command:    { to: { aggregate: "...", entity: "..." }, with: { ... } }
-    module CommandRequest
-      module_function
-
-      # Splits a request, explicit envelope or flat Hash, into routing (`to:`) and facts (`with:`).
-      # Keys are symbolized at every depth; in a flat Hash everything but the receiver is a fact.
-      #
-      # @param input [Hash] the request, with String or Symbol keys
-      # @param receiver [Symbol, nil] `:aggregate`, `:entity`, or `nil` for a command with none
-      # @param legacy_receiver [Symbol, String, Hash, nil] the flat key that may carry the
-      #   receiver instead of `to:`: a name for `:aggregate`, `{ aggregate:, entity: }` for
-      #   `:entity`
-      # @return [Hash{Symbol => Object}] `{ with: facts }`, plus `to:` when `receiver` is set
-      # @raise [Runtime::TypeMismatch] if the request is malformed or the route does not fit
-      #   the receiver kind
-      # @raise [ArgumentError] if `receiver` is not `nil`, `:aggregate` or `:entity`
-      def normalize(input, receiver:, legacy_receiver: nil)
-        request = symbolize(input)
-        raise Runtime::TypeMismatch, "a command request must be a hash" unless request.is_a?(Hash)
-
-        route, facts = split(request, receiver: receiver, legacy_receiver: legacy_receiver)
-        validate_route!(route, receiver)
-
-        envelope = { with: facts }
-        envelope[:to] = route if receiver
-        envelope
-      end
-
-      def split(request, receiver:, legacy_receiver:)
-        return split_envelope(request) if request.key?(:with)
-
-        flat  = request.dup
-        route = flat.delete(:to)
-        route = take_legacy_route(flat, receiver, legacy_receiver) if route.nil?
-        [route, flat]
-      end
-      private_class_method :split
-
-      def split_envelope(request)
-        loose = request.keys - [:to, :with]
-        unless loose.empty?
-          raise Runtime::TypeMismatch,
-                "an explicit command envelope takes routing in to: and facts in with:, not loose #{loose.sort.join(", ")}"
-        end
-
-        facts = request[:with]
-        raise Runtime::TypeMismatch, "with: must be a hash of command facts" unless facts.is_a?(Hash)
-
-        [request[:to], facts]
-      end
-      private_class_method :split_envelope
-
-      def take_legacy_route(flat, receiver, legacy_receiver)
-        return unless legacy_receiver
-
-        return flat.delete(legacy_receiver.to_sym) if receiver == :aggregate
-
-        return unless receiver == :entity && legacy_receiver.is_a?(Hash)
-
-        aggregate_key = legacy_receiver.fetch(:aggregate).to_sym
-        entity_key    = legacy_receiver.fetch(:entity).to_sym
-        return unless flat.key?(aggregate_key) || flat.key?(entity_key)
-
-        { aggregate: flat.delete(aggregate_key), entity: flat.delete(entity_key) }
-      end
-      private_class_method :take_legacy_route
-
-      # One self-contained check per closed receiver kind, plus a backstop.
-      def validate_route!(route, receiver)
-        case receiver
-        when nil then refuse_receiver(route)
-        when :aggregate then require_identity(route)
-        when :entity then require_entity_route(route)
-        else raise ArgumentError, "unknown receiver kind #{receiver.inspect}"
-        end
-      end
-      private_class_method :validate_route!
-
-      def refuse_receiver(route)
-        raise Runtime::TypeMismatch, "this command does not take a receiver in to:" unless route.nil?
-      end
-      private_class_method :refuse_receiver
-
-      def require_identity(route)
-        return unless route.nil? || route.to_s.empty? || route.is_a?(Hash)
-
-        raise Runtime::TypeMismatch, "to: must name the receiving aggregate identity"
-      end
-      private_class_method :require_identity
-
-      def require_entity_route(route)
-        raise Runtime::TypeMismatch, "to: for an entity command must contain aggregate: and entity:" unless route.is_a?(Hash)
-
-        extra = route.keys - [:aggregate, :entity]
-        missing = [:aggregate, :entity].select { |key| route[key].nil? || route[key].to_s.empty? }
-        return if extra.empty? && missing.empty?
-
-        raise Runtime::TypeMismatch, "to: for an entity command must contain only aggregate: and entity:"
-      end
-      private_class_method :require_entity_route
-
-      def symbolize(value)
-        case value
-        when Hash then value.to_h { |key, nested| [key.to_sym, symbolize(nested)] }
-        when Array then value.map { |nested| symbolize(nested) }
-        else value
-        end
-      end
-      private_class_method :symbolize
-    end
-  end
-end

data/lib/hecks/doors/handle.rb

@@ -1,208 +0,0 @@
-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]
-        marked_rows(field).each do |row|
-          raw = masked(raw, row) unless authorized_for?(row[:readable_by][:value].to_s)
-        end
-
-        raw
-      end
-
-      # The privacy markings that name `field` or a path beneath it.
-      def marked_rows(field)
-        marked_paths.select { |row| row[:attribute_path][:value].to_s.split(".", 2).first == field.to_s }
-      end
-
-      # `raw` with the marked leaf masked: the whole value for a marked field, one nested leaf of a
-      # value object for a marked path beneath it.
-      def masked(raw, row)
-        segments = row[:attribute_path][:value].to_s.split(".", 2)
-        return "[redacted]" if segments.size == 1
-
-        raw.is_a?(Runtime::Value) ? raw.with(segments[1], "[redacted]") : 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 { |attribute| define_reference_accessor(attribute) }
-      end
-
-      # One lazy reader for a reference attribute.
-      def define_reference_accessor(attribute)
-        target = attribute.type.resolve
-        # Cross-domain, or otherwise unresolvable — no accessor rather than a guess.
-        return unless target
-
-        target_fqn = "#{@domain}::#{target.hecks_name}"
-        define_singleton_method(attribute.name) do
-          value = self[attribute.name]
-          door = Object.const_get(target_fqn)
-          next Array(value).map { |identity| door.find(identity) } if attribute.list?
-
-          value && door.find(value)
-        end
-      end
-    end
-  end
-end

data/lib/hecks/doors/json_door.rb

@@ -1,132 +0,0 @@
-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