rooibos 0.5.0 → 0.6.1

data/lib/rooibos/command/all.rb

@@ -7,39 +7,92 @@
 
 module Rooibos
   module Command
-    # An aggregating parallel command.
-    All = Data.define(:envelope, :commands, :nested) do
+    # Aggregates parallel commands and returns all results together.
+    #
+    # Dashboards load user profiles, settings, and stats before rendering.
+    # Fetching sequentially is slow. Fire-and-forget batches lose correlation
+    # between commands and their results.
+    #
+    # This command runs children in parallel and collects their results into
+    # a single <tt>Message::All</tt> response. Pattern-match on the envelope
+    # to correlate results. Each result appears in the same order as commands.
+    #
+    # Use it for coordinated fetches where you need all results before proceeding.
+    #
+    # Prefer the <tt>Command.all</tt> factory method for convenience.
+    #
+    # === Example
+    #
+    #   # Using the factory method (recommended)
+    #   Command.all(:dashboard,
+    #     Command.http(:get, "/users", :_),
+    #     Command.http(:get, "/stats", :_),
+    #   )
+    #
+    #   # Using the class directly
+    #   All.new(:dashboard,
+    #     Command.http(:get, "/users", :_),
+    #     Command.http(:get, "/stats", :_),
+    #   )
+    #
+    #   # Pattern-match on the aggregated result
+    #   def update(message, model)
+    #     case message
+    #     in { type: :all, envelope: :dashboard, results: [users, stats] }
+    #       model.with(users:, stats:, loading: false)
+    #     end
+    #   end
+    class All < Data.define(:envelope, :commands, :nested)
       include Custom
 
-      def self.new(tag, *args)
-        # DWIM: detect nested vs splatted based on call-site arity
-        if args.size == 1 && args.first.is_a?(Array)
-          commands = args.first
-          nested = true
-        else
-          commands = args
-          nested = false
-        end
+      class << self
+        undef_method :new
+
+        # Creates an aggregating parallel command.
+        #
+        # [tag] Symbol to tag the result message.
+        # [args] Commands to run in parallel. Pass as multiple arguments
+        #        or a single array.
+        #
+        # === Example
+        #
+        #   All.new(:dashboard,
+        #     Command.http(:get, "/users", :_),
+        #     Command.http(:get, "/stats", :_),
+        #   )
+        def new(tag, *args)
+          # DWIM: flatten single-array arg to support both call patterns
+          nested = args.size == 1 && args.first.is_a?(Array)
+          commands = [args].flatten(2)
 
-        if RatatuiRuby::Debug.enabled?
-          commands.each do |cmd|
-            unless Ractor.shareable?(cmd)
-              raise Rooibos::Error::Invariant,
-                "Command is not Ractor-shareable: #{cmd.inspect}\n" \
-                  "Use Ractor.make_shareable or a Data.define command."
+          if RatatuiRuby::Debug.enabled?
+            commands.each do |cmd|
+              unless Ractor.shareable?(cmd)
+                raise Rooibos::Error::Invariant,
+                  "Command is not Ractor-shareable: #{cmd.inspect}\n" \
+                    "Use Ractor.make_shareable or a Data.define command."
+              end
             end
           end
-        end
 
-        instance = allocate
-        instance.__send__(:initialize, envelope: tag, commands: commands.freeze, nested:)
-        instance
+          instance = allocate
+          instance.__send__(:initialize, envelope: tag, commands: commands.freeze, nested:)
+          instance
+        end
       end
 
+      # Executes all child commands in parallel and aggregates results.
+      #
+      # Sends <tt>Message::All</tt> when all children complete. Results appear
+      # in the same order as commands. If canceled, sends <tt>Message::Canceled</tt>.
+      #
+      # [out] Outlet for sending messages.
+      # [token] Cancellation token from the runtime.
       def call(out, token)
         # Early return for empty commands - prevents hang from zip_futures([])
         if commands.empty?
-          response = Message::All.new(envelope:, results: [].freeze, nested:)
+          results = [] #: Array[Object]
+          response = Message::All.new(envelope:, results: results.freeze, nested:)
           out.put(Ractor.make_shareable(response))
           return
         end
@@ -58,7 +111,7 @@ module Rooibos
         all_done = Concurrent::Promises.zip_futures(*futures)
         Concurrent::Promises.any_event(all_done, token.origin).wait
 
-        return out.put(Command.cancel(self)) if token.canceled?
+        return out.put(Message::Canceled.new(command: self)) if token.canceled?
 
         shareable_results = Ractor.make_shareable(all_done.value!)
         response = Message::All.new(envelope:, results: shareable_results, nested:)

data/lib/rooibos/command/batch.rb

@@ -15,61 +15,88 @@ module Rooibos
     #
     # This command runs children in parallel. Each child sends its own messages
     # independently. The batch completes when all children finish or when
-    # cancellation fires. On cancellation, emits <tt>Command.cancel(self)</tt>.
+    # cancellation fires. On cancellation, emits <tt>Message::Canceled</tt>.
     #
     # Use it for parallel fetches, concurrent refreshes, or any work that
     # does not need coordinated results.
     #
+    # Prefer the <tt>Command.batch</tt> factory method for convenience.
+    #
     # === Example
     #
+    #   # Using the factory method (recommended)
+    #   Command.batch(
+    #     Command.http(:get, "/users", :users),
+    #     Command.http(:get, "/stats", :stats),
+    #   )
+    #
+    #   # Using the class directly
+    #   Batch.new(
+    #     Command.http(:get, "/users", :users),
+    #     Command.http(:get, "/stats", :stats),
+    #   )
+    #
+    #   # Handle each response independently
     #   def update(msg, model)
     #     case msg
-    #     in :refresh_all
-    #       batch = Command.batch(
-    #         Command.http(:get, "/users", :users),
-    #         Command.http(:get, "/stats", :stats),
-    #       )
-    #       [model.with(loading: true), batch]
-    #     in :users | :stats
-    #       [model.with(msg => data), nil]
+    #     in { type: :http, envelope: :users, body: }
+    #       model.with(users: JSON.parse(body))
+    #     in { type: :http, envelope: :stats, body: }
+    #       model.with(stats: JSON.parse(body))
     #     end
     #   end
     class Batch < Data.define(:commands) do
       include Custom
 
-      # Initialize
-      def self.new(*args)
-        # DWIM: accept (cmd1, cmd2) or ([cmd1, cmd2])
-        commands = (args.size == 1 && args.first.is_a?(Array)) ? args.first : args
+      class << self
+        undef_method :new
 
-        if RatatuiRuby::Debug.enabled?
-          commands.each do |cmd|
-            unless Ractor.shareable?(cmd)
-              raise Rooibos::Error::Invariant,
-                "Command is not Ractor-shareable: #{cmd.inspect}\n" \
-                  "Use Ractor.make_shareable or a Data.define command."
+        # Creates a parallel batch command.
+        #
+        # [args] Commands to run in parallel. Pass as multiple arguments
+        #        or a single array.
+        #
+        # === Example
+        #
+        #   Batch.new(cmd1, cmd2, cmd3)
+        #   Batch.new([cmd1, cmd2, cmd3])
+        def new(*args)
+          # DWIM: accept (cmd1, cmd2) or ([cmd1, cmd2])
+          commands = (args.size == 1 && args.first.is_a?(Array)) ? args.first : args
+
+          if RatatuiRuby::Debug.enabled?
+            commands.each do |cmd|
+              unless Ractor.shareable?(cmd)
+                raise Rooibos::Error::Invariant,
+                  "Command is not Ractor-shareable: #{cmd.inspect}\n" \
+                    "Use Ractor.make_shareable or a Data.define command."
+              end
             end
           end
-        end
 
-        instance = allocate
-        instance.__send__(:initialize, commands: commands.freeze)
-        instance
+          instance = allocate
+          instance.__send__(:initialize, commands: commands.freeze)
+          instance
+        end
       end
 
-      # Call it
+      # Executes all child commands in parallel.
+      #
+      # Each child sends its results independently via the runtime.
+      # When all complete, sends <tt>Message::Batch</tt>. If canceled,
+      # sends <tt>Message::Canceled</tt> instead.
+      #
+      # [out] Outlet for sending messages.
+      # [token] Cancellation token from the runtime.
       def call(out, token)
-        futures = commands.map do |command|
-          Concurrent::Promises.future { command.call(out, token) }
-        end
-
-        all_done = Concurrent::Promises.zip_futures(*futures)
-        Concurrent::Promises.any_event(all_done, token.origin).wait
+        handles = commands.map { |cmd| out.standing(cmd, token) }
+        out.wait(*handles, token:)
 
-        # Re-raise any child exception for runtime to wrap in Command::Error
-        futures.each { |f| raise f.reason if f.rejected? }
-
-        out.put(Command.cancel(self)) if token.canceled?
+        if token.canceled?
+          out.put(Message::Canceled.new(command: self))
+        else
+          out.put(Message::Batch.new(command: self))
+        end
       end
     end
     end

data/lib/rooibos/command/custom.rb

@@ -71,7 +71,7 @@ module Rooibos
       # it calls <tt>token.cancel!</tt> and waits this long for your command to stop.
       # If your command does not exit within this window, it is force-killed.
       #
-      # *This is NOT a lifetime limit.* Your command runs indefinitely until cancelled.
+      # *This is NOT a lifetime limit.* Your command runs indefinitely until canceled.
       # A WebSocket open for 15 minutes is fine. This timeout only applies to the
       # cleanup phase after cancellation is requested.
       #
@@ -99,6 +99,89 @@ module Rooibos
       def rooibos_cancellation_grace_period
         0.1
       end
+
+      # Infrastructure methods to exclude from introspection.
+      # Computed once from bare prototypes.
+      INFRASTRUCTURE_METHODS = begin
+        bare_data = Data.define(:_)
+        bare_struct = Struct.new(:_)
+
+        methods = Object.public_instance_methods +
+          bare_data.public_instance_methods +
+          bare_struct.public_instance_methods
+
+        # PP methods can error when called on objects without pretty_print override
+        methods += %i[
+          pretty_print
+          pretty_print_cycle
+          pretty_print_instance_variables
+          pretty_print_inspect
+]
+
+        methods.uniq.freeze
+      end
+      private_constant :INFRASTRUCTURE_METHODS
+
+      # Deconstructs for hash-based pattern matching.
+      #
+      # Introspects public query methods (CQS: zero-arity, no side effects) and
+      # returns a hash suitable for +case+/+in+ matching. Excludes infrastructure
+      # methods from Object, Data, and Struct.
+      #
+      # Always includes +:type+ as a snake_case symbol of the class name.
+      # Anonymous classes default to +:custom+.
+      #
+      # Data.define members are automatically included since they generate
+      # public accessor methods.
+      #
+      # This is a naive but practical default. Override for:
+      # - Hot paths (introspects methods on every call)
+      # - Ghost methods via +method_missing+/+respond_to_missing?+
+      # - Methods with optional arguments (only zero-arity detected)
+      #
+      # @param keys [Array<Symbol>, nil] Limit output to specific keys for performance.
+      #   Pass +nil+ to include all keys.
+      # @return [Hash{Symbol => Object}] Deconstructed hash with +:type+ discriminator.
+      #
+      # @example Pattern matching with Data.define command
+      #   case msg
+      #   in { type: :http_response, envelope: :users, status: 200 }
+      #     # handle success
+      #   end
+      def deconstruct_keys(keys)
+        class_name = self.class.name&.split("::")&.last
+        type_name = if class_name
+          class_name
+            .gsub(/([a-z])([A-Z])/, '\1_\2')
+            .downcase
+            .to_sym
+        else
+          :custom
+        end
+
+        result = { type: type_name }
+
+        # Include Data.define/Struct members
+        if self.class.respond_to?(:members)
+          klass = self.class #: Class & _HasMembers
+          klass.members.each do |member|
+            next if keys && !keys.include?(member)
+            result[member] = public_send(member)
+          end
+        end
+
+        # Include public zero-arity query methods (excluding infrastructure)
+        # Use Kernel#public_method to avoid collision with Data.define :method member
+        get_method = Kernel.instance_method(:public_method)
+        (public_methods - INFRASTRUCTURE_METHODS).each do |method_name|
+          next if method_name.to_s.end_with?("=", "!")
+          next unless get_method.bind_call(self, method_name).arity.zero?
+          next if keys && !keys.include?(method_name)
+          result[method_name] = public_send(method_name)
+        end
+
+        result
+      end
     end
   end
 end

data/lib/rooibos/command/http.rb

@@ -14,80 +14,135 @@ module Rooibos
     # New code should use Rooibos::Message::HttpResponse.
     HttpResponse = Message::HttpResponse
 
-    # An HTTP request command.
-    Http = Data.define(:method, :url, :envelope, :headers, :body, :timeout, :parser) do
+    # Performs HTTP requests and sends the response as a message.
+    #
+    # Applications fetch data from APIs. Users expect responsive interfaces
+    # while requests complete. Managing HTTP connections, timeouts, and
+    # threading manually is error-prone.
+    #
+    # This command executes HTTP requests off the main thread. The runtime
+    # dispatches it and routes the response back to your update function
+    # as a <tt>Message::HttpResponse</tt>.
+    #
+    # Use it to fetch API data, post forms, or interact with web services.
+    #
+    # Prefer the <tt>Command.http</tt> factory method for convenience.
+    # The constructor supports flexible DWIM (Do What I Mean) arity.
+    #
+    # === Example
+    #
+    #   # Using the factory method (recommended)
+    #   Command.http(:get, "/api/users", :users)
+    #   Command.http(get: "/api/users", envelope: :users)
+    #   Command.http(:post, "/api/users", '{"name":"Jo"}', :created)
+    #
+    #   # Using the class directly
+    #   Http.new(:get, "/api/users", :users)
+    #
+    #   # Pattern-match on the response
+    #   def update(message, model)
+    #     case message
+    #     in { type: :http, envelope: :users, status: 200, body: }
+    #       model.with(users: JSON.parse(body))
+    #     in { type: :http, envelope: :users, error: }
+    #       model.with(error:)
+    #     end
+    #   end
+    class Http < Data.define(:method, :url, :envelope, :headers, :body, :timeout, :parser)
       include Custom
 
-      def self.new(*args, method: nil, url: nil, envelope: nil, headers: nil, body: nil, timeout: nil, parser: nil,
-        get: nil, post: nil, put: nil, patch: nil, delete: nil
-      )
-        # Auto-splat single hash argument
-        return new(**args.first) if args.size == 1 && args.first.is_a?(Hash)
+      class << self
+        undef_method :new
 
-        # Auto-spread single array argument
-        return new(*args.first) if args.size == 1 && args.first.is_a?(Array)
+        # Creates an HTTP request command.
+        #
+        # Supports flexible DWIM arity for convenience:
+        # <tt>Http.new("url")</tt>:: GET, URL as envelope
+        # <tt>Http.new("url", :tag)</tt>:: GET, custom envelope
+        # <tt>Http.new(:post, "url")</tt>:: POST, URL as envelope
+        # <tt>Http.new(:post, "url", :tag)</tt>:: POST, custom envelope
+        # <tt>Http.new(:post, "url", "body", :tag)</tt>:: POST with body
+        # <tt>Http.new(get: "url")</tt>:: keyword shortcut
+        #
+        # [method] HTTP method symbol: <tt>:get</tt>, <tt>:post</tt>,
+        #          <tt>:put</tt>, <tt>:patch</tt>, or <tt>:delete</tt>.
+        # [url] Request URL (String).
+        # [envelope] Symbol to tag the response message.
+        # [headers] Optional hash of HTTP headers.
+        # [body] Optional request body (String).
+        # [timeout] Optional timeout in seconds (default 10).
+        # [parser] Optional callable to transform response body.
+        def new(*args, method: nil, url: nil, envelope: nil, headers: nil, body: nil, timeout: nil, parser: nil,
+          get: nil, post: nil, put: nil, patch: nil, delete: nil
+        )
+          # Auto-splat single hash argument
+          return new(**args.first) if args.size == 1 && args.first.is_a?(Hash)
 
-        # DWIM: parse positional args and keyword method shortcuts
-        method_keywords = { get:, post:, put:, patch:, delete: }.compact
-        method, url, envelope, body = parse_dwim_args(args, method, url, envelope, body, method_keywords)
+          # Auto-spread single array argument
+          return new(*args.first) if args.size == 1 && args.first.is_a?(Array)
 
-        # Ractor validation
-        if RatatuiRuby::Debug.enabled? && !Ractor.shareable?(url)
-          raise Rooibos::Error::Invariant,
-            "URL is not Ractor-shareable: #{url.inspect}\n" \
-              "Use a frozen string or Ractor.make_shareable."
-        end
+          # DWIM: parse positional args and keyword method shortcuts
+          method_keywords = { get:, post:, put:, patch:, delete: }.compact
+          method, url, envelope, body = parse_dwim_args(args, method, url, envelope, body, method_keywords)
 
-        if RatatuiRuby::Debug.enabled? && headers && !Ractor.shareable?(headers)
-          raise Rooibos::Error::Invariant,
-            "Headers are not Ractor-shareable: #{headers.inspect}\n" \
-              "Use Ractor.make_shareable or freeze the hash and its contents."
-        end
+          # Ractor validation
+          if RatatuiRuby::Debug.enabled? && !Ractor.shareable?(url)
+            raise Rooibos::Error::Invariant,
+              "URL is not Ractor-shareable: #{url.inspect}\n" \
+                "Use a frozen string or Ractor.make_shareable."
+          end
 
-        if RatatuiRuby::Debug.enabled? && body && !Ractor.shareable?(body)
-          raise Rooibos::Error::Invariant,
-            "Body is not Ractor-shareable: #{body.inspect}\n" \
-              "Use a frozen string or Ractor.make_shareable."
-        end
+          if RatatuiRuby::Debug.enabled? && headers && !Ractor.shareable?(headers)
+            raise Rooibos::Error::Invariant,
+              "Headers are not Ractor-shareable: #{headers.inspect}\n" \
+                "Use Ractor.make_shareable or freeze the hash and its contents."
+          end
 
-        if RatatuiRuby::Debug.enabled? && envelope && !Ractor.shareable?(envelope)
-          raise Rooibos::Error::Invariant,
-            "Envelope is not Ractor-shareable: #{envelope.inspect}\n" \
-              "Use a frozen string, symbol, or Ractor.make_shareable."
-        end
+          if RatatuiRuby::Debug.enabled? && body && !Ractor.shareable?(body)
+            raise Rooibos::Error::Invariant,
+              "Body is not Ractor-shareable: #{body.inspect}\n" \
+                "Use a frozen string or Ractor.make_shareable."
+          end
 
-        if RatatuiRuby::Debug.enabled? && timeout && !Ractor.shareable?(timeout)
-          raise Rooibos::Error::Invariant,
-            "Timeout is not Ractor-shareable: #{timeout.inspect}\n" \
-              "Use a number or Ractor.make_shareable."
-        end
+          if RatatuiRuby::Debug.enabled? && envelope && !Ractor.shareable?(envelope)
+            raise Rooibos::Error::Invariant,
+              "Envelope is not Ractor-shareable: #{envelope.inspect}\n" \
+                "Use a frozen string, symbol, or Ractor.make_shareable."
+          end
 
-        # Parser validation
-        if parser && !parser.respond_to?(:call)
-          raise ArgumentError, "parser: must respond to :call"
-        end
+          if RatatuiRuby::Debug.enabled? && timeout && !Ractor.shareable?(timeout)
+            raise Rooibos::Error::Invariant,
+              "Timeout is not Ractor-shareable: #{timeout.inspect}\n" \
+                "Use a number or Ractor.make_shareable."
+          end
 
-        if RatatuiRuby::Debug.enabled? && parser && !Ractor.shareable?(parser)
-          raise Rooibos::Error::Invariant,
-            "Parser is not Ractor-shareable: #{parser.inspect}\n" \
-              "Use a frozen Method object or Ractor.make_shareable."
-        end
+          # Parser validation
+          if parser && !parser.respond_to?(:call)
+            raise ArgumentError, "parser: must respond to :call"
+          end
 
-        # Method validation
-        unless %i[get post put patch delete].include?(method)
-          raise ArgumentError, "Unsupported HTTP method: #{method.inspect}"
-        end
+          if RatatuiRuby::Debug.enabled? && parser && !Ractor.shareable?(parser)
+            raise Rooibos::Error::Invariant,
+              "Parser is not Ractor-shareable: #{parser.inspect}\n" \
+                "Use a frozen Method object or Ractor.make_shareable."
+          end
 
-        instance = allocate
-        instance.__send__(:initialize, method:, url:, envelope:, headers:, body:, timeout: timeout || 10, parser:)
-        instance
+          # Method validation
+          unless %i[get post put patch delete].include?(method)
+            raise ArgumentError, "Unsupported HTTP method: #{method.inspect}"
+          end
+
+          instance = allocate
+          instance.__send__(:initialize, method:, url:, envelope:, headers:, body:, timeout: timeout || 10, parser:)
+          instance
+        end
       end
 
       # Net::HTTP is blocking; no cooperative cancellation possible.
       # Grace period = 0 means runtime can force-kill immediately.
       def rooibos_cancellation_grace_period = 0
 
-      def self.parse_dwim_args(args, method_kw, url_kw, envelope_kw, body_kw, method_keywords)
+      def self.parse_dwim_args(args, method_kw, url_kw, envelope_kw, body_kw, method_keywords) # :nodoc:
         # Handle keyword method shortcuts: get: 'url'
         if method_keywords.any?
           method_key, url = method_keywords.first
@@ -130,6 +185,17 @@ module Rooibos
       end
       private_class_method :parse_dwim_args
 
+      # Executes the HTTP request and sends the response.
+      #
+      # Sends <tt>Message::HttpResponse</tt> with status, body, and headers.
+      # On network errors, sends the same message type with <tt>error</tt>
+      # populated instead.
+      #
+      # Note: Ruby's <tt>Net::HTTP</tt> blocks until completion. Cancellation
+      # cannot interrupt a request in progress. The grace period is 0.
+      #
+      # [out] Outlet for sending messages.
+      # [token] Cancellation token from the runtime.
       def call(out, token)
         return if token.canceled?
 

data/lib/rooibos/command/lifecycle.rb

@@ -19,8 +19,7 @@ module Rooibos
     #
     # The framework creates one instance at startup. All outlets share it.
     class Lifecycle
-      # :nodoc: Internal representation of a tracked async command.
-      Entry = Data.define(:future, :origin)
+      Entry = Data.define(:future, :origin) # :nodoc: Internal representation of a tracked async command.
 
       # Creates a lifecycle manager.
       #
@@ -40,7 +39,7 @@ module Rooibos
       # [token]   Parent's cancellation token.
       # [timeout] Max wait seconds for the result.
       #
-      # Returns the child's message, or <tt>nil</tt> if cancelled or timed out.
+      # Returns the child's message, or <tt>nil</tt> if canceled or timed out.
       # Raises if the child raised.
       def run_sync(command, token, timeout:)
         return nil if token.canceled?
@@ -76,7 +75,7 @@ module Rooibos
       #
       # Spawns a future that executes the command. Tracks the command in the
       # active map for cancellation support. Errors are pushed to the channel
-      # as <tt>Command::Error</tt> messages.
+      # as <tt>Message::Error</tt> messages.
       #
       # [command] Callable with <tt>call(out, token)</tt>.
       # [channel] Channel to push results and errors to.
@@ -89,7 +88,7 @@ module Rooibos
         future = Concurrent::Promises.future do
           command.call(outlet, cancellation)
         rescue => e
-          channel.push Command::Error.new(command:, exception: e)
+          channel.push Message::Error.new(command:, exception: e)
         end
 
         entry = Entry.new(future:, origin:)
@@ -114,6 +113,7 @@ module Rooibos
         entry.future.wait(grace.finite? ? grace : nil)
 
         @active.delete(command)
+        entry # Return so caller can remove from pending_futures
       end
 
       # Cancels all active commands and waits for them to complete.