module Rooibos::Command::Custom

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

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

Public Instance Methods

rooibos_cancellation_grace_period ()

Source

# File lib/rooibos/command/custom.rb, line 99
def rooibos_cancellation_grace_period
  0.1
end

Cleanup time after cancellation is requested. In seconds.

When the runtime cancels your command (app exit, navigation, explicit cancel), it calls token.cancel! 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:

0.5 — Quick HTTP abort, no cleanup needed
2.0 — Default, suitable for most commands
5.0 — WebSocket close handshake with remote server
Float::INFINITY — Never force-kill (database transactions)

Example

# Database transactions should never be interrupted mid-write
def rooibos_cancellation_grace_period
  Float::INFINITY
end

rooibos_command? ()

Source

# File lib/rooibos/command/custom.rb, line 64
def rooibos_command?
  true
end

Brand predicate for command identification.

The runtime calls this to distinguish commands from plain models. Returns true unconditionally.

You do not need to override this method.