Custom Commands Design (rooibos)

This document describes the architectural design and guiding principles of custom commands in rooibos. It is intended for contributors, architects, and AI agents working on the codebase.

Core Abstractions

Custom commands extend Rooibos with user-defined side effects: WebSockets, gRPC, database polling, background workers. The architecture provides four key components:

Guiding Design Principles

1. Messaging Gateway over Raw Queue

Commands produce messages. Those messages cross threads. Without abstraction, queue manipulation scatters across the codebase.

The Outlet wraps the internal queue with a domain-specific API. Commands call out.put(:tag, data) instead of managing queue details. Debug mode validates Ractor-shareability automatically—commands cannot accidentally push unshareable data.

This implements the Messaging Gateway pattern from Enterprise Integration Patterns. The Outlet is a Facade (Gang of Four) over the queue, and acts as a Channel Adapter translating command results into update function messages.

2. Cooperative Cancellation over Thread Termination

Long-running commands block the event loop. WebSocket listeners, database pollers, and streaming connections run indefinitely until stopped. Stopping them abruptly corrupts state.

Thread#kill terminates immediately. Mutexes may deadlock. Resources may leak. Database transactions may abort mid-write.

The CancellationToken signals cancellation requests. Commands check token.canceled? periodically and stop at safe points. Cleanup code runs. Resources release. Transactions commit.

Configurable grace periods accommodate different cleanup needs:

• 0.5 seconds — Quick HTTP abort, minimal cleanup

• 2.0 seconds — Default, suitable for most commands

• 5.0 seconds — WebSocket close handshake with remote server

• Float::INFINITY — Wait indefinitely for cooperative exit (database transactions)

3. Command Identity via Object Reference

The runtime tracks active commands by their object identity. When the update function returns Command.cancel(handle), the runtime looks up that exact object in its registry and signals its token.

Class-based commands get unique identity automatically—each MyCommand.new produces a distinct object. Reusable lambdas and procs share identity. Dispatch them twice, and cancellation would affect both.

Command.custom(callable) wraps a callable in a unique container. Each call produces a distinct handle. Store it in your model. Cancel it later by returning Command.cancel(handle).

4. Automatic Error Propagation

Commands run in threads. Exceptions bubble up silently. The update function never sees them. Backtraces written to STDERR corrupt the TUI display.

The runtime catches unhandled exceptions and pushes Command::Error to the queue. This is automatic—commands do not rescue exceptions unless they want custom handling. The update function pattern-matches on Command::Error and reacts appropriately.

This mirrors the sentinel pattern used for Command::Exit and Command::Cancel.

Error categorization: We use a single Command::Error sentinel for all command exceptions. Distinguishing “framework bugs” vs “user bugs” at the sentinel level adds complexity with marginal benefit. Instead, exception classes provide the signal:

The update function can pattern-match on error_msg.exception.class if it needs to distinguish sources.

5. Ractor Readiness

This design is forward-compatible with Ruby’s Ractor-based parallelism.

What’s already shareable:

Debug mode validation:

In debug mode, Rooibos validates Ractor shareability at dispatch time. Ractor.shareable?(command) catches most issues. The Outlet’s put method validates messages before pushing them to the queue.

Why Thread dispatch is Ractor-safe:

Commands execute in Threads within the main Ractor. Only messages (via Outlet) cross the shareability boundary. The CancellationToken stays within its Thread—never shared across Ractors. The @active_commands hash is local to the Runtime (main Ractor).

When Ruby evolves to true Ractor parallelism, this design upgrades transparently: commands are already validated as shareable, so they could be sent to worker Ractors without code changes.

Pattern Lineage

This design implements several established patterns from the software architecture literature.

Design Patterns (Gang of Four)

Enterprise Integration Patterns (Hohpe & Woolf)

Cancellation Patterns

Prior Art

The Elm Architecture (TEA)

Redux Ecosystem

Redux Saga’s put() is the direct inspiration for out.put(). The Saga pattern—long-running processes that listen for actions and dispatch new ones—maps directly to Rooibos’s custom commands.

Ruby Ecosystem

Key Influences Summary

Further Reading

External Resources

• Elm Guide — Official Elm documentation covering commands and effects

• BubbleTea — Go TUI framework based on The Elm Architecture

• Redux Saga — Saga pattern and put() effect documentation

• Enterprise Integration Patterns — Messaging patterns reference by Hohpe & Woolf

Academic References

1. Gamma, Helm, Johnson, Vlissides (1994). Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley.

2. Command, Facade, Mediator, State patterns

3. Fowler, M. (2002). Patterns of Enterprise Application Architecture. Addison-Wesley.

4. Gateway pattern

5. Hohpe, G. & Woolf, B. (2003). Enterprise Integration Patterns. Addison-Wesley.

6. Messaging Gateway, Message Channel, Point-to-Point Channel, Channel Adapter

7. Joshi, U. (2023). Patterns of Distributed Systems. Addison-Wesley.

8. Write-Ahead Log, Thread Pool