ratatui_ruby-tea 0.3.1 → 0.4.0

data/examples/verify_readme_usage/app.rb

@@ -13,9 +13,12 @@ require "ratatui_ruby/tea"
 class VerifyReadmeUsage
   # [SYNC:START:mvu]
   Model = Data.define(:text)
-  MODEL = Model.new(text: "Hello, Ratatui! Press 'q' to quit.")
 
-  VIEW = -> (model, tui) do
+  Init = -> do
+    Model.new(text: "Hello, Ratatui! Press 'q' to quit.")
+  end
+
+  View = -> (model, tui) do
     tui.paragraph(
       text: model.text,
       alignment: :center,
@@ -27,7 +30,7 @@ class VerifyReadmeUsage
     )
   end
 
-  UPDATE = -> (msg, model) do
+  Update = -> (msg, model) do
     if msg.q? || msg.ctrl_c?
       RatatuiRuby::Tea::Command.exit
     else
@@ -36,7 +39,7 @@ class VerifyReadmeUsage
   end
 
   def run
-    RatatuiRuby::Tea.run(model: MODEL, view: VIEW, update: UPDATE)
+    RatatuiRuby::Tea.run(VerifyReadmeUsage)
   end
   # [SYNC:END:mvu]
 end

data/lib/ratatui_ruby/tea/command/all.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Tea
+    module Command
+      # An aggregating parallel command.
+      All = Data.define(:envelope, :commands, :nested) do
+        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
+
+          if RatatuiRuby::Debug.enabled?
+            commands.each do |cmd|
+              unless Ractor.shareable?(cmd)
+                raise RatatuiRuby::Error::Invariant,
+                  "Command is not Ractor-shareable: #{cmd.inspect}\n" \
+                    "Use Ractor.make_shareable or a Data.define command."
+              end
+            end
+          end
+
+          instance = allocate
+          instance.__send__(:initialize, envelope: tag, commands: commands.freeze, nested:)
+          instance
+        end
+
+        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:)
+            out.put(Ractor.make_shareable(response))
+            return
+          end
+
+          child_lifecycle = Lifecycle.new
+
+          futures = commands.map do |command|
+            Concurrent::Promises.future do
+              child_channel = Concurrent::Promises::Channel.new
+              child_outlet = Outlet.new(child_channel, lifecycle: child_lifecycle)
+              command.call(child_outlet, token)
+              child_channel.pop
+            end
+          end
+
+          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?
+
+          shareable_results = Ractor.make_shareable(all_done.value!)
+          response = Message::All.new(envelope:, results: shareable_results, nested:)
+          out.put(Ractor.make_shareable(response))
+        end
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/tea/command/batch.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Tea
+    module Command
+      # A fire-and-forget parallel command.
+      #
+      # Applications fetch data from multiple sources. Dashboard panels load
+      # users, stats, and notifications. Waiting sequentially is slow.
+      # Managing threads and error handling manually is error-prone.
+      #
+      # 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>.
+      #
+      # Use it for parallel fetches, concurrent refreshes, or any work that
+      # does not need coordinated results.
+      #
+      # === Example
+      #
+      #   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]
+      #     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
+
+          if RatatuiRuby::Debug.enabled?
+            commands.each do |cmd|
+              unless Ractor.shareable?(cmd)
+                raise RatatuiRuby::Error::Invariant,
+                  "Command is not Ractor-shareable: #{cmd.inspect}\n" \
+                    "Use Ractor.make_shareable or a Data.define command."
+              end
+            end
+          end
+
+          instance = allocate
+          instance.__send__(:initialize, commands: commands.freeze)
+          instance
+        end
+
+        # Call it
+        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
+
+          # 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?
+        end
+      end
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/tea/command/custom.rb

@@ -39,7 +39,7 @@ module RatatuiRuby
       #       ws.on_message { |msg| out.put(:ws_message, msg) }
       #       ws.connect
       #
-      #       until token.cancelled?
+      #       until token.canceled?
       #         ws.ping
       #         sleep 1
       #       end

data/lib/ratatui_ruby/tea/command/http.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+require "net/http"
+require "uri"
+
+module RatatuiRuby
+  module Tea
+    module Command
+      # Alias to Message::HttpResponse for backwards compatibility.
+      # New code should use RatatuiRuby::Tea::Message::HttpResponse.
+      HttpResponse = Message::HttpResponse
+
+      # An HTTP request command.
+      Http = Data.define(:method, :url, :envelope, :headers, :body, :timeout, :parser) do
+        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)
+
+          # Auto-spread single array argument
+          return new(*args.first) if args.size == 1 && args.first.is_a?(Array)
+
+          # 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)
+
+          # Ractor validation
+          if RatatuiRuby::Debug.enabled? && !Ractor.shareable?(url)
+            raise RatatuiRuby::Error::Invariant,
+              "URL is not Ractor-shareable: #{url.inspect}\n" \
+                "Use a frozen string or Ractor.make_shareable."
+          end
+
+          if RatatuiRuby::Debug.enabled? && headers && !Ractor.shareable?(headers)
+            raise RatatuiRuby::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? && body && !Ractor.shareable?(body)
+            raise RatatuiRuby::Error::Invariant,
+              "Body is not Ractor-shareable: #{body.inspect}\n" \
+                "Use a frozen string or Ractor.make_shareable."
+          end
+
+          if RatatuiRuby::Debug.enabled? && envelope && !Ractor.shareable?(envelope)
+            raise RatatuiRuby::Error::Invariant,
+              "Envelope is not Ractor-shareable: #{envelope.inspect}\n" \
+                "Use a frozen string, symbol, or Ractor.make_shareable."
+          end
+
+          if RatatuiRuby::Debug.enabled? && timeout && !Ractor.shareable?(timeout)
+            raise RatatuiRuby::Error::Invariant,
+              "Timeout is not Ractor-shareable: #{timeout.inspect}\n" \
+                "Use a number 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? && parser && !Ractor.shareable?(parser)
+            raise RatatuiRuby::Error::Invariant,
+              "Parser is not Ractor-shareable: #{parser.inspect}\n" \
+                "Use a frozen Method object or Ractor.make_shareable."
+          end
+
+          # 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
+
+        # Net::HTTP is blocking; no cooperative cancellation possible.
+        # Grace period = 0 means runtime can force-kill immediately.
+        def tea_cancellation_grace_period = 0
+
+        def self.parse_dwim_args(args, method_kw, url_kw, envelope_kw, body_kw, method_keywords)
+          # Handle keyword method shortcuts: get: 'url'
+          if method_keywords.any?
+            method_key, url = method_keywords.first
+            # Check for conflicts with method: keyword
+            if method_kw && method_kw != method_key
+              raise ArgumentError, "Conflicting method specified: #{method_key}: and method: #{method_kw}"
+            end
+            # Check for conflicts with url: keyword
+            if url_kw && url_kw != url
+              raise ArgumentError, "Conflicting url specified: #{method_key}: provides url but url: also given"
+            end
+            return [method_key, url, url, body_kw]
+          end
+
+          # If keywords provided, use them directly
+          return [method_kw, url_kw, envelope_kw, body_kw] if args.empty?
+
+          case args
+          in [String => url]
+            # Http.new('url') → GET, URL as envelope
+            [:get, url, url, body_kw]
+          in [String => url, Symbol => envelope]
+            # Http.new('url', :tag) → GET, custom envelope
+            [:get, url, envelope, body_kw]
+          in [Symbol => method, String => url]
+            # Http.new(:delete, 'url') → method, URL as envelope
+            [method, url, url, body_kw]
+          in [Symbol => method, String => url, Symbol => envelope]
+            # Http.new(:delete, 'url', :tag) → method, custom envelope
+            [method, url, envelope, body_kw]
+          in [Symbol => method, String => url, String => body]
+            # Http.new(:post, 'url', 'body') → method, URL as envelope, body
+            [method, url, url, body]
+          in [Symbol => method, String => url, String => body, Symbol => envelope]
+            # Http.new(:post, 'url', 'body', :tag) → method, custom envelope, body
+            [method, url, envelope, body]
+          else
+            raise ArgumentError, "Invalid arguments for Http.new: #{args.inspect}"
+          end
+        end
+        private_class_method :parse_dwim_args
+
+        def call(out, token)
+          return if token.canceled?
+
+          uri = URI(url)
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == "https"
+          if timeout
+            http.open_timeout = timeout
+            http.read_timeout = timeout
+          end
+
+          klass = case method
+                  when :get    then Net::HTTP::Get
+                  when :post   then Net::HTTP::Post
+                  when :put    then Net::HTTP::Put
+                  when :patch  then Net::HTTP::Patch
+                  when :delete then Net::HTTP::Delete
+          end
+          request = klass.new(uri)
+          request.body = body if body
+          headers&.each { |key, value| request[key] = value }
+          response = http.request(request)
+
+          response_body = response.body.freeze
+          response_headers = response.each_header.to_h.freeze
+          response_status = response.code.to_i
+
+          # Invoke parser with positional params if provided
+          parsed_body = if parser
+            parser.call(response_body, response_headers, response_status)
+          else
+            response_body
+          end
+
+          # Validate parsed body is Ractor-shareable in debug mode
+          if RatatuiRuby::Debug.enabled? && parser && !Ractor.shareable?(parsed_body)
+            raise RatatuiRuby::Error::Invariant,
+              "Parsed body is not Ractor-shareable: #{parsed_body.class}\n" \
+                "Parser must return frozen/shareable data. Use .freeze or Ractor.make_shareable."
+          end
+
+          out.put(Ractor.make_shareable(HttpResponse.new(
+            envelope:,
+            status: response_status,
+            body: parsed_body,
+            headers: response_headers,
+            error: nil
+          )))
+        rescue => e
+          out.put(Ractor.make_shareable(HttpResponse.new(
+            envelope:,
+            status: nil,
+            body: nil,
+            headers: nil,
+            error: e.message.freeze
+          )))
+        end
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/tea/command/lifecycle.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Tea
+    module Command
+      # Coordinates command execution across the runtime.
+      #
+      # Commands run off the main thread. Both the runtime and nested commands
+      # via <tt>Outlet#source</tt> share cancellation tokens. Racing results
+      # against cancellation is repetitive. Tracking active commands is tedious.
+      #
+      # This class centralizes that logic. It races results against cancellation
+      # and timeout. Commands that ignore cancellation are orphaned until
+      # process exit. Cooperative cancellation is the only way to exit cleanly.
+      #
+      # 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)
+
+        # Creates a lifecycle manager.
+        #
+        # The runtime creates one at startup. All outlets share it. Child commands
+        # from <tt>Outlet#source</tt> inherit the same lifecycle for consistent
+        # thread management.
+        def initialize
+          @active = Concurrent::Map.new
+        end
+
+        # Runs a command synchronously, returning its result.
+        #
+        # Spawns a thread, races the result against cancellation and timeout.
+        # On cancellation, waits the grace period then kills the thread if needed.
+        #
+        # [command] Callable with <tt>call(out, token)</tt>.
+        # [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.
+        # Raises if the child raised.
+        def run_sync(command, token, timeout:)
+          return nil if token.canceled?
+
+          child_channel = Concurrent::Promises::Channel.new
+          child_outlet = Outlet.new(child_channel, lifecycle: self)
+
+          exception = nil
+          Concurrent::Promises.future do
+            command.call(child_outlet, token)
+          rescue => e
+            exception = e
+          end
+
+          # Race: pop result vs cancellation vs timeout
+          pop_future = Concurrent::Promises.future { child_channel.pop(timeout, :timeout) }
+          Concurrent::Promises.any_event(pop_future, token.origin).wait
+
+          # Cooperative cancellation only — misbehaving commands are orphaned
+          return nil if token.canceled?
+
+          if exception
+            raise exception.is_a?(Exception) ? exception : RuntimeError.new(exception.to_s)
+          end
+
+          result = pop_future.value
+          return nil if result == :timeout
+
+          result
+        end
+
+        # Runs a command asynchronously, tracking it for later cancellation.
+        #
+        # 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.
+        #
+        # [command] Callable with <tt>call(out, token)</tt>.
+        # [channel] Channel to push results and errors to.
+        #
+        # Returns a hash with <tt>:future</tt> and <tt>:origin</tt> for tracking.
+        def run_async(command, channel)
+          cancellation, origin = Concurrent::Cancellation.new
+          outlet = Outlet.new(channel, lifecycle: self)
+
+          future = Concurrent::Promises.future do
+            command.call(outlet, cancellation)
+          rescue => e
+            channel.push Command::Error.new(command:, exception: e)
+          end
+
+          entry = Entry.new(future:, origin:)
+          @active[command] = entry
+          entry
+        end
+
+        # Cancels a running command, waiting for its grace period.
+        #
+        # Signals cancellation, waits for the command's grace period, then
+        # removes it from tracking. Does nothing if the command isn't tracked.
+        #
+        # [command] The command to cancel (must be the same object passed to run_async).
+        def cancel(command)
+          entry = @active[command]
+          return unless entry&.future&.pending?
+
+          entry.origin.resolve # Signal cancellation
+
+          grace = command.respond_to?(:tea_cancellation_grace_period) ?
+            command.tea_cancellation_grace_period : 0.1
+          entry.future.wait(grace.finite? ? grace : nil)
+
+          @active.delete(command)
+        end
+
+        # Cancels all active commands and waits for them to complete.
+        #
+        # Iterates through all tracked commands, signals cancellation, and waits
+        # for each command's grace period. Called at runtime shutdown.
+        def shutdown
+          @active.each do |command, entry|
+            entry.origin.resolve # Signal cancellation
+
+            grace = command.respond_to?(:tea_cancellation_grace_period) ?
+              command.tea_cancellation_grace_period : 0.1
+            entry.future.wait(grace.finite? ? grace : nil)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/tea/command/outlet.rb

@@ -64,7 +64,7 @@ module RatatuiRuby
       #     include Tea::Command::Custom
       #
       #     def call(out, token)
-      #       until token.cancelled?
+      #       until token.canceled?
       #         data = fetch_batch
       #         out.put(:batch, Ractor.make_shareable(data))
       #         sleep 5
@@ -76,26 +76,64 @@ module RatatuiRuby
       # SPDX-SnippetEnd
       #++
       class Outlet
-        # Creates an outlet for the given queue.
+        # Creates an outlet for the given message queue.
         #
-        # The runtime provides the queue. Custom commands receive the outlet as
-        # their first argument.
+        # The runtime provides the message queue and lifecycle. Custom commands receive
+        # the outlet as their first argument.
         #
-        # [queue] A <tt>Thread::Queue</tt> or compatible object.
-        def initialize(queue)
-          @queue = queue
+        # [message_queue] A <tt>Concurrent::Promises::Channel</tt> or compatible object.
+        # [lifecycle] A <tt>Lifecycle</tt> for managing nested command execution.
+        def initialize(message_queue, lifecycle:)
+          @message_queue = message_queue
+          @live = lifecycle
         end
 
-        # Sends a tagged message to the runtime.
+        # :nodoc: Internal infrastructure for nested command lifecycle sharing.
+        attr_reader :live
+
+        # Sends a message to the runtime.
         #
-        # Builds an array <tt>[tag, *payload]</tt> and pushes it to the queue.
-        # The update function pattern-matches on the tag.
+        # Custom commands produce results. Those results feed back into your
+        # update function. This method handles the wiring.
         #
-        # Debug mode validates Ractor-shareability. It raises <tt>Error::Invariant</tt>
-        # if the message is not shareable. Production skips this check.
+        # Call with one argument to send it directly. Call with multiple
+        # arguments and they arrive as an array.
         #
-        # [tag] Symbol identifying the message type.
-        # [payload] Additional arguments. Freeze them or use <tt>Ractor.make_shareable</tt>.
+        # Use it for complex data flows or transports Tea doesn't ship with.
+        #
+        # === Example
+        #
+        #   out.put(:done)              # Update receives :done
+        #   out.put(current_user)       # Update receives current_user
+        #   out.put(:user, alice)       # Update receives [:user, alice]
+        #
+        # Debug mode validates Ractor-shareability.
+        def put(*args)
+          message = (args.size == 1) ? args.first : args.freeze
+
+          if RatatuiRuby::Debug.enabled? && !Ractor.shareable?(message)
+            raise RatatuiRuby::Error::Invariant,
+              "Message is not Ractor-shareable: #{message.inspect}\n" \
+                "Use Ractor.make_shareable or Object#freeze."
+          end
+
+          @message_queue.push(message)
+        end
+
+        # Runs a child command synchronously within a custom command.
+        #
+        # Use this to orchestrate multi-step workflows: fetch one result, then
+        # use it to compose the next command.
+        #
+        # The child runs asynchronously in a future. This method blocks until
+        # the child calls +put+, cancellation occurs, or the timeout expires.
+        #
+        # [command] A callable (lambda or Custom command) with +call(out, token)+.
+        # [token]   The parent's cancellation token, passed through to the child.
+        # [timeout] Max seconds to wait for the child's result (default: 30.0).
+        #
+        # Returns the message from the child, or +nil+ if cancelled/timed out.
+        # Raises if the child command raised an exception.
         #
         # === Example
         #
@@ -104,22 +142,16 @@ module RatatuiRuby
         # SPDX-FileCopyrightText: 2026 Kerrick Long
         # SPDX-License-Identifier: MIT-0
         #++
-        #   out.put(:user_fetched, user: Ractor.make_shareable(user))
-        #   out.put(:error, message: "Connection failed".freeze)
-        #   out.put(:progress, percent: 42)  # Integers are always shareable
+        #   def call(out, token)
+        #     user_result = out.source(fetch_user_cmd, token)
+        #     return if user_result.nil?
+        #     out.put(:user_loaded, user: user_result)
+        #   end
         #--
         # SPDX-SnippetEnd
         #++
-        def put(tag, *payload)
-          message = [tag, *payload].freeze
-
-          if RatatuiRuby::Debug.enabled? && !Ractor.shareable?(message)
-            raise RatatuiRuby::Error::Invariant,
-              "Message is not Ractor-shareable: #{message.inspect}\n" \
-                "Use Ractor.make_shareable or Object#freeze."
-          end
-
-          @queue << message
+        def source(command, token, timeout: 30.0)
+          @live.run_sync(command, token, timeout:)
         end
       end
     end