rooibos 0.6.2 → 0.7.0

data/lib/rooibos/router/flow/outward.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # :stopdoc:
+    module Flow
+      # Outward flow: messages traveling toward the root.
+      #
+      # Observe → intercept.
+      class Outward < Data.define(:observes, :receives, :routes)
+        include Dispatch
+
+        # Sentinel: intercept consumed the bubble. Non-nil so
+        # Transition#with_command replaces the original Command::Bubble
+        # instead of preserving it via the nil no-op.
+        INTERCEPTED = Object.new.freeze
+
+        def call(message, model)
+          transition = run_all(observes, message, model)
+          config = Configuration.new(message:, model: transition.model)
+          intercept_first_matching(receives, config, transition) ||
+            transition
+        end
+
+        private def intercept_first_matching(rules, config, transition)
+          rules.each do |rule|
+            new_transition = rule.apply_if_matches(config, routes) or next
+            return transition
+                .with_model(new_transition.model)
+                .with_command(new_transition.command || INTERCEPTED)
+          end
+          nil
+        end
+      end
+    end
+    private_constant :Flow
+  end
+end

data/lib/rooibos/router/guard.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # :stopdoc:
+    # Normalizes guard options into a callable.
+    class Guard < Data.define(:callable)
+      @scope = []
+
+      def self.scoped(callable)
+        @scope.push(callable)
+        yield
+      ensure
+        @scope.pop
+      end
+
+      def self.from(guard: nil, when: nil, unless: nil, if: nil, only: nil, except: nil, skip: nil)
+        when_guard = binding.local_variable_get(:when) ||
+          binding.local_variable_get(:if) ||
+          binding.local_variable_get(:only)
+        unless_guard = binding.local_variable_get(:unless) ||
+          binding.local_variable_get(:except) ||
+          binding.local_variable_get(:skip)
+        normalized = guard || when_guard
+        normalized = -> (msg, model) { !unless_guard.call(msg, model) } if unless_guard
+        new(callable: apply_scope(normalized))
+      end
+
+      private_class_method def self.apply_scope(callable)
+        @scope.inject(callable) do |inner, outer|
+          if inner
+            -> (msg, model) { outer.call(msg, model) && inner.call(msg, model) }
+          else
+            outer
+          end
+        end
+      end
+
+      def arity
+        callable&.arity || 2
+      end
+
+      def call(message, model)
+        return true unless callable
+        callable.arity.zero? ? callable.call : callable.call(message, model)
+      end
+    end
+    private_constant :Guard
+  end
+end

data/lib/rooibos/router/predicate.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # :stopdoc:
+    module Predicate
+      # Matches key events by symbol.
+      class Events < Data.define(:keys)
+        def initialize(keys:)
+          super(keys: Array(keys))
+        end
+
+        def arity = 2
+
+        def call(message, _model)
+          message.respond_to?(:to_sym) && keys.include?(message.to_sym)
+        end
+      end
+
+      # Matches routed messages by envelope.
+      class Routed < Data.define(:envelope)
+        def arity = 2
+
+        def call(message, _model)
+          message.is_a?(Message::Routed) && message.envelope == envelope
+        end
+      end
+
+      # Matches routed messages by any of the given envelopes.
+      class RoutedEnvelopes < Data.define(:envelopes)
+        def initialize(envelopes:)
+          super(envelopes: Array(envelopes))
+        end
+
+        def arity = 2
+
+        def call(message, _model)
+          message.routed? && envelopes.include?(message.envelope)
+        end
+      end
+
+      # Matches messages by class.
+      class InstancesOf < Data.define(:klass)
+        def arity = 2
+
+        def call(message, _model)
+          message.is_a?(klass)
+        end
+      end
+
+      # Matches all messages.
+      class Always < Data.define
+        def arity = 2
+        def call(_message, _model) = true
+      end
+    end
+    private_constant :Predicate
+  end
+end

data/lib/rooibos/router/registry/actions.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # :stopdoc:
+    # Collection of named actions.
+    class Actions < Data.define(:rules)
+      include Enumerable
+
+      def initialize(rules: [])
+        super
+      end
+
+      def add(name, handler)
+        action = if handler.is_a?(Module)
+          RoutedAction.new(name: name.to_sym, fragment: handler)
+        else
+          LambdaAction.new(name: name.to_sym, handler:)
+        end
+        rules << action
+      end
+
+      def [](name)
+        find { |action| action.name == name.to_sym } or
+          raise ArgumentError, "Unknown action: #{name}"
+      end
+
+      def each(&block)
+        return rules.each unless block
+        rules.each { |action| block.call(action) }
+      end
+    end
+    private_constant :Actions
+  end
+end

data/lib/rooibos/router/registry/forwards.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # :stopdoc:
+    # Collection of forwards
+    class Forwards < Data.define(:rules)
+      include Registry
+
+      def initialize(rules: [])
+        super
+      end
+
+      def add_instances_of(klass, to: nil, as: nil, broadcast: false, broadcast_to: nil) = add(Forward.new(
+        predicate: Predicate::InstancesOf.new(klass:),
+        targets: resolve_targets(to:, broadcast:, broadcast_to:),
+        envelope: as
+      ))
+
+      def add_events(keys, to:, as: nil, guard: nil, when: nil, unless: nil) = add(Forward.new(
+        predicate: Predicate::Events.new(keys:),
+        targets: to,
+        envelope: as,
+        guard: Guard.from(guard:, when: binding.local_variable_get(:when), unless: binding.local_variable_get(:unless))
+      ))
+
+      def add_routed(envelopes, to:, as: nil) = add(Forward.new(
+        predicate: Predicate::RoutedEnvelopes.new(envelopes:),
+        targets: to,
+        envelope: as
+      ))
+
+      def add_custom(predicate, to:, as: nil, **guard_opts) = add(Forward.new(
+        predicate:,
+        targets: to,
+        envelope: as,
+        guard: Guard.from(**guard_opts)
+      ))
+
+      private def resolve_targets(to:, broadcast:, broadcast_to:)
+        if broadcast
+          ALL_ROUTES
+        elsif broadcast_to
+          broadcast_to
+        else
+          to
+        end
+      end
+    end
+    private_constant :Forwards
+  end
+end

data/lib/rooibos/router/registry/observes.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # :stopdoc:
+    # Collection of observe rules.
+    class Observes < Data.define(:rules, :actions)
+      include Registry
+
+      def initialize(rules: [], actions:)
+        super
+      end
+
+      def add_events(keys, handler, **guard_opts) = add(Observe.new(
+        predicate: Predicate::Events.new(keys:),
+        action: resolve(handler),
+        guard: Guard.from(**guard_opts)
+      ))
+
+      def add_routed(envelope, handler, guard: nil) = add(Observe.new(
+        predicate: Predicate::Routed.new(envelope:),
+        action: resolve(handler),
+        guard: Guard.from(guard:)
+      ))
+
+      def add_instances_of(klass, handler, guard: nil) = add(Observe.new(
+        predicate: Predicate::InstancesOf.new(klass:),
+        action: resolve(handler),
+        guard: Guard.from(guard:)
+      ))
+
+      def add_all(handler, **guard_opts) = add(Observe.new(
+        predicate: Predicate::Always.new,
+        action: resolve(handler),
+        guard: Guard.from(**guard_opts)
+      ))
+
+      def add_custom(predicate, handler, **guard_opts) = add(Observe.new(
+        predicate:,
+        action: resolve(handler),
+        guard: Guard.from(**guard_opts)
+      ))
+
+      private def resolve(handler)
+        return actions[handler] if handler.is_a?(Symbol)
+        LambdaAction.new(name: nil, handler:)
+      end
+    end
+    private_constant :Observes
+  end
+end

data/lib/rooibos/router/registry/otherwises.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # :stopdoc:
+    # Collection of otherwise rules.
+    class Otherwises < Data.define(:rules)
+      include Registry
+
+      def initialize(rules: [])
+        super
+      end
+
+      def add(route_to:, **guard_opts)
+        super(Otherwise.new(
+          target: route_to,
+          guard: Guard.from(**guard_opts)
+        ))
+      end
+    end
+    private_constant :Otherwises
+  end
+end

data/lib/rooibos/router/registry/receives.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # :stopdoc:
+    # Collection of receive rules.
+    class Receives < Data.define(:rules, :actions)
+      include Registry
+
+      def initialize(rules: [], actions:)
+        super
+      end
+
+      def add_events(keys, handler, **guard_opts) = add(Receive.new(
+        predicate: Predicate::Events.new(keys:),
+        action: resolve(handler),
+        guard: Guard.from(**guard_opts)
+      ))
+
+      def add_routed(envelope, handler, guard: nil) = add(Receive.new(
+        predicate: Predicate::Routed.new(envelope:),
+        action: resolve(handler),
+        guard: Guard.from(guard:)
+      ))
+
+      def add_instances_of(klass, handler, guard: nil) = add(Receive.new(
+        predicate: Predicate::InstancesOf.new(klass:),
+        action: resolve(handler),
+        guard: Guard.from(guard:)
+      ))
+
+      def add_all(handler, **guard_opts) = add(Receive.new(
+        predicate: Predicate::Always.new,
+        action: resolve(handler),
+        guard: Guard.from(**guard_opts)
+      ))
+
+      def add_custom(predicate, handler, guard: nil) = add(Receive.new(
+        predicate:,
+        action: resolve(handler),
+        guard: Guard.from(guard:)
+      ))
+
+      private def resolve(handler)
+        return actions[handler] if handler.is_a?(Symbol)
+        LambdaAction.new(name: nil, handler:)
+      end
+    end
+    private_constant :Receives
+  end
+end

data/lib/rooibos/router/registry/routes.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # :stopdoc:
+    class Routes
+      include Enumerable
+
+      def initialize(routes = Set.new) = @routes = routes
+
+      def add(route)
+        @routes << route
+        route
+      end
+
+      def for(identifier)
+        case identifier
+        when Module then unique(identifier) { |r| r.fragment == identifier }
+        when Symbol then unique(identifier) { |r| r.prefix == identifier }
+        else identifier
+        end
+      end
+
+      def each(&block)
+        return @routes.each unless block
+        @routes.each { |route| block.call(route) }
+      end
+
+      def subset(targets)
+        resolved = targets.filter_map { |t| self.for(t) }
+        Routes.new(resolved.to_set)
+      end
+
+      def broadcast(message, model)
+        reduce(Transition.initial(model)) do |transition, route|
+          new_model, command = route.delegate(message, transition.model)
+          transition.with_model(new_model).with_added_command(command)
+        end
+      end
+
+      def broadcast_to(prefixes, message, model)
+        subset(prefixes).broadcast(message, model)
+      end
+
+      private def unique(identifier, &)
+        matches = @routes.select(&)
+        raise Rooibos::Error::Invariant, "Ambiguous route: #{identifier} matches #{matches.size} routes. Capture the Route returned by `route` and pass it to `to:` to disambiguate." if matches.size > 1
+        matches.first
+      end
+    end
+    private_constant :Routes
+  end
+end

data/lib/rooibos/router/registry.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # :stopdoc:
+    # Common behavior for Rule collections.
+    # Classes including this must define :rules as a Data member.
+    module Registry
+      include Enumerable
+
+      def add(rule) = rules << rule
+
+      def each(&block)
+        return rules.each unless block
+        rules.each { |rule| block.call(rule) }
+      end
+    end
+    private_constant :Registry
+  end
+end

data/lib/rooibos/router/route.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # :stopdoc:
+    Route = Data.define(:prefix, :fragment, :read, :write) do
+      def initialize(prefix:, fragment:, read: nil, write: nil)
+        super
+      end
+
+      def delegate(message, model)
+        nested_model = extract(model)
+        result = fragment::Update.call(message, nested_model)
+        transition = Transition.from(result, nested_model)
+        Transition.new(model: merge(model, transition.model), command: transition.command)
+      end
+
+      private def extract(model)
+        if read
+          read.call(model)
+        else
+          model.public_send(prefix)
+        end
+      end
+
+      private def merge(model, new_nested_model)
+        if write
+          write.call(model, new_nested_model)
+        else
+          model.with(prefix => new_nested_model)
+        end
+      end
+    end
+    private_constant :Route
+  end
+end

data/lib/rooibos/router/router_update.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # :stopdoc:
+    # Encapsulates dispatch logic - given frozen rule sets, processes messages.
+    class RouterUpdate < Data.define(:inward, :outward)
+      def call(message, model)
+        case message
+        when Message::Bubbled then dispatch_outward(message.message, model)
+        else dispatch_inward(message, model)
+        end
+      end
+
+      private def dispatch_inward(message, model)
+        transition = inward.call(message, model)
+        case transition.command
+        when Command::Bubble # Sentinel; not a real Command to be handled by the runtime
+          bubble_model, bubble_cmd = dispatch_outward(transition.command.message, transition.model)
+          transition = transition.with_model(bubble_model).with_command(bubble_cmd)
+        when Command::Batch
+          transition = extract_bubbles_from_batch(transition)
+        end
+        transition = transition.with(command: nil) if transition.command.equal?(Flow::Outward::INTERCEPTED)
+        transition.to_a
+      end
+
+      private def extract_bubbles_from_batch(transition)
+        bubbles, remaining = transition.command.extract_bubbles
+        return transition if bubbles.empty?
+
+        result = Transition.new(model: transition.model, command: remaining)
+        bubbles.each do |bubble|
+          model, cmd = dispatch_outward(bubble.message, result.model)
+          result = Transition.new(model:, command: result.command)
+          result = result.with_added_command(cmd) unless cmd.nil? || cmd.equal?(Flow::Outward::INTERCEPTED)
+        end
+        result
+      end
+
+      private def dispatch_outward(message, model)
+        outward.call(message, model).to_a
+      end
+    end
+    private_constant :RouterUpdate
+  end
+end

data/lib/rooibos/router/rule/forward.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # :stopdoc:
+    # Forward rule - matches messages and delegates to route(s)
+    class Forward < Data.define(:predicate, :targets, :envelope, :guard)
+      include Rule
+
+      def initialize(predicate:, targets: ALL_ROUTES, envelope: nil, guard: nil)
+        targets = Array(targets) unless targets == ALL_ROUTES
+        super
+      end
+
+      def apply(message, model, routes)
+        if targets == ALL_ROUTES
+          routes
+        else
+          routes.subset(targets)
+        end.broadcast(envelop(message), model)
+      end
+
+      private def envelop(message)
+        if envelope
+          Message::Routed.new(envelope:, event: message)
+        else
+          message
+        end
+      end
+    end
+    private_constant :Forward
+  end
+end

data/lib/rooibos/router/rule/observe.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # :stopdoc:
+    # Observe rule - matches messages, handles, and continues processing.
+    class Observe < Data.define(:predicate, :action, :guard)
+      include Rule
+
+      def apply(message, model, routes)
+        action.apply(message, model, routes)
+      end
+    end
+    private_constant :Observe
+  end
+end

data/lib/rooibos/router/rule/otherwise.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # :stopdoc:
+    # Rule for otherwise routing - routes unhandled messages to a fragment.
+    Otherwise = Data.define(:target, :guard, :predicate) do
+      include Rule
+
+      def initialize(target:, guard: nil, predicate: Predicate::Always.new)
+        super
+      end
+
+      def apply(message, model, routes)
+        routes.subset([target]).broadcast(message, model)
+      end
+    end
+    private_constant :Otherwise
+  end
+end