rooibos 0.5.0

data/lib/rooibos/command/custom.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Command
+    # Mixin for user-defined custom commands.
+    #
+    # Custom commands extend Rooibos with side effects: WebSockets, gRPC, database polls,
+    # background tasks. The runtime dispatches them in threads and routes results
+    # back as messages.
+    #
+    # Include this module to identify your class as a command. The runtime uses
+    # +rooibos_command?+ to distinguish commands from plain models. Override
+    # +rooibos_cancellation_grace_period+ if your cleanup takes longer than 100 milliseconds.
+    #
+    # Use it to build real-time features, long-polling connections, or background workers.
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   class WebSocketCommand
+    #     include Rooibos::Command::Custom
+    #
+    #     def initialize(url)
+    #       @url = url
+    #     end
+    #
+    #     def call(out, token)
+    #       ws = WebSocket::Client.new(@url)
+    #       ws.on_message { |msg| out.put(:ws_message, msg) }
+    #       ws.connect
+    #
+    #       until token.canceled?
+    #         ws.ping
+    #         sleep 1
+    #       end
+    #
+    #       ws.close
+    #     end
+    #
+    #     # WebSocket close handshake needs extra time
+    #     def rooibos_cancellation_grace_period
+    #       5.0
+    #     end
+    #   end
+    #--
+    # SPDX-SnippetEnd
+    #++
+    module Custom
+      # Brand predicate for command identification.
+      #
+      # The runtime calls this to distinguish commands from plain models.
+      # Returns <tt>true</tt> unconditionally.
+      #
+      # You do not need to override this method.
+      def rooibos_command?
+        true
+      end
+
+      # Cleanup time after cancellation is requested. In seconds.
+      #
+      # When the runtime cancels your command (app exit, navigation, explicit cancel),
+      # 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.
+      # A WebSocket open for 15 minutes is fine. This timeout only applies to the
+      # cleanup phase after cancellation is requested.
+      #
+      # Override this method to specify how long your cleanup takes:
+      #
+      # - <tt>0.5</tt> — Quick HTTP abort, no cleanup needed
+      # - <tt>2.0</tt> — Default, suitable for most commands
+      # - <tt>5.0</tt> — WebSocket close handshake with remote server
+      # - <tt>Float::INFINITY</tt> — Never force-kill (database transactions)
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   # Database transactions should never be interrupted mid-write
+      #   def rooibos_cancellation_grace_period
+      #     Float::INFINITY
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def rooibos_cancellation_grace_period
+        0.1
+      end
+    end
+  end
+end

data/lib/rooibos/command/http.rb

@@ -0,0 +1,192 @@
+# 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 Rooibos
+  module Command
+    # Alias to Message::HttpResponse for backwards compatibility.
+    # 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
+      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 Rooibos::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 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? && 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? && 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? && timeout && !Ractor.shareable?(timeout)
+          raise Rooibos::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 Rooibos::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 rooibos_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 Rooibos::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

data/lib/rooibos/command/lifecycle.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  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?(:rooibos_cancellation_grace_period) ?
+          command.rooibos_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?(:rooibos_cancellation_grace_period) ?
+            command.rooibos_cancellation_grace_period : 0.1
+          entry.future.wait(grace.finite? ? grace : nil)
+        end
+      end
+    end
+  end
+end

data/lib/rooibos/command/outlet.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+require "ratatui_ruby"
+
+module Rooibos
+  module Command
+    # Messaging gateway for custom commands.
+    #
+    # Custom commands run in background threads. They produce results that the
+    # main loop consumes.
+    #
+    # Managing queues and message formats manually is tedious. It scatters queue
+    # logic across your codebase and makes mistakes easy.
+    #
+    # This class wraps the queue with a clean API. Call +put+ to send tagged
+    # messages. Debug mode validates Ractor-shareability.
+    #
+    # Use it to send results from HTTP requests, WebSocket streams, or database polls.
+    #
+    # === Example (One-Shot)
+    #
+    # Commands run in their own thread. Blocking calls work fine:
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   class FetchUserCommand
+    #     include Rooibos::Command::Custom
+    #
+    #     def initialize(user_id)
+    #       @user_id = user_id
+    #     end
+    #
+    #     def call(out, _token)
+    #       response = Net::HTTP.get(URI("https://api.example.com/users/#{@user_id}"))
+    #       user = JSON.parse(response)
+    #       out.put(:user_fetched, Ractor.make_shareable(user: user))
+    #     rescue => e
+    #       out.put(:user_fetch_failed, error: e.message.freeze)
+    #     end
+    #   end
+    #--
+    # SPDX-SnippetEnd
+    #++
+    #
+    # === Example (Long-Running)
+    #
+    # Commands that loop check the cancellation token:
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   class PollerCommand
+    #     include Rooibos::Command::Custom
+    #
+    #     def call(out, token)
+    #       until token.canceled?
+    #         data = fetch_batch
+    #         out.put(:batch, Ractor.make_shareable(data))
+    #         sleep 5
+    #       end
+    #       out.put(:poller_stopped)
+    #     end
+    #   end
+    #--
+    # SPDX-SnippetEnd
+    #++
+    class Outlet
+      # Creates an outlet for the given message queue.
+      #
+      # The runtime provides the message queue and lifecycle. Custom commands receive
+      # the outlet as their first argument.
+      #
+      # [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
+
+      # :nodoc: Internal infrastructure for nested command lifecycle sharing.
+      attr_reader :live
+
+      # Sends a message to the runtime.
+      #
+      # Custom commands produce results. Those results feed back into your
+      # update function. This method handles the wiring.
+      #
+      # Call with one argument to send it directly. Call with multiple
+      # arguments and they arrive as an array.
+      #
+      # Use it for complex data flows or transports Rooibos 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 Rooibos::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
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   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 source(command, token, timeout: 30.0)
+        @live.run_sync(command, token, timeout:)
+      end
+    end
+  end
+end

data/lib/rooibos/command/wait.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Command
+    # A one-shot timer command.
+    #
+    # Applications need timed events. Notification auto-dismissal,
+    # debounced search, and animation frames all depend on delays.
+    # Building timers from scratch with threads is error-prone.
+    # Cancellation is tricky.
+    #
+    # This command waits, then sends a message. It responds to
+    # cancellation cooperatively. When cancelled, it sends
+    # <tt>Command.cancel(self)</tt> so you know the timer stopped.
+    #
+    # Use it for delayed actions, debounced inputs, or animation loops.
+    #
+    # === Example: Notification dismissal
+    #
+    #   def update(msg, model)
+    #     case msg
+    #     in :save_clicked
+    #       [model.with(notification: "Saved!"), Command.wait(3.0, :dismiss)]
+    #     in :dismiss
+    #       [model.with(notification: nil), nil]
+    #     in Command::Cancel
+    #       [model.with(notification: nil), nil]  # User navigated away
+    #     end
+    #   end
+    #
+    # === Example: Animation loop
+    #
+    #   def update(msg, model)
+    #     case msg
+    #     in :start_animation
+    #       [model.with(frame: 0), Command.tick(0.1, :animate)]
+    #     in :animate
+    #       frame = (model.frame + 1) % 10
+    #       [model.with(frame:), Command.tick(0.1, :animate)]
+    #     end
+    #   end
+    Wait = Data.define(:seconds, :envelope) do
+      include Custom
+
+      # Cooperative cancellation needs no grace period.
+      # The command responds instantly to cancellation via
+      # <tt>Concurrent::Cancellation.timeout</tt>.
+      def rooibos_cancellation_grace_period
+        0
+      end
+
+      # Executes the timer.
+      #
+      # Waits for <tt>seconds</tt>, then sends <tt>TimerResponse</tt>.
+      # If cancelled, sends <tt>Command.cancel(self)</tt> instead.
+      #
+      # [out] Outlet for sending messages.
+      # [token] Cancellation token from the runtime.
+      def call(out, token)
+        start_time = Time.now
+        timer_cancellation, _origin = Concurrent::Cancellation.timeout(seconds)
+        combined = token.join(timer_cancellation)
+        combined.origin.wait
+
+        if token.canceled?
+          out.put(Command.cancel(self))
+        else
+          elapsed = Time.now - start_time
+          response = Message::Timer.new(envelope:, elapsed:)
+          out.put(Ractor.make_shareable(response))
+        end
+      end
+    end
+  end
+end