hecks 3.10.0 → 3.11.0

data/lib/hecks/adapters/driving/command_request.rb

@@ -0,0 +1,121 @@
+require_relative "../../runtime/errors"
+
+module Hecks
+  module Adapters
+    module Driving
+      # 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, envelope or flat Hash, into routing (`to:`) and facts (`with:`),
+        # symbolizing keys at every depth; in a flat Hash all but the receiver are facts.
+        #
+        # @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
+end

data/lib/hecks/adapters/driving/handle.rb

@@ -0,0 +1,214 @@
+require_relative "../../naming"
+require_relative "../../runtime/caller"
+require_relative "../../ports/authorization"
+
+module Hecks
+  module Adapters
+    module Driving
+      # 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 aggregate module. Keeps the current state when the record is not found.
+        #
+        # @return [Adapters::Driving::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)
+
+          provider = @dispatcher.registry.provider_of(Bluebook::Capabilities::PRIVACY)
+          return @marked_paths = [] unless provider
+
+          verb = provider.provided_verb(Bluebook::Capabilities::PRIVACY, :markings_for)
+          @marked_paths = @dispatcher.query(verb, 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]
+            resolved = Object.const_get(target_fqn)
+            next Array(value).map { |identity| resolved.find(identity) } if attribute.list?
+
+            value && resolved.find(value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/json.rb

@@ -0,0 +1,136 @@
+require "json"
+require_relative "handle"
+require_relative "command_request"
+require_relative "../../naming"
+require_relative "../../runtime/errors"
+require_relative "../../runtime/value"
+
+module Hecks
+  module Adapters
+    module Driving
+      # The JSON adapter: 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 Json
+        module_function
+
+        # Resolves a domain name and an aggregate name, as two URL segments carry them, to
+        # that aggregate module.
+        #
+        # 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 module 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_driving: false`)
+        def aggregate(dispatcher, domain, name)
+          Admission.admit!(dispatcher.registry, "Json")
+          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 module 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 module, as `aggregate` returns
+        # @return [String] the method name to `public_send` to the module
+        # @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 module, 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 module, as `aggregate` returns
+        # @param id [String] the record's identity, as the URL carried it
+        # @return [Adapters::Driving::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 [Adapters::Driving::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 is badly routed
+        # @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
+end