Overview

Date: 2026-05-11

Time: 15:16

Overview

FTL2's event streaming system enables real-time progress reporting during module execution. Modules can emit progress, log, and data events that stream to callers, supporting use cases like progress bars for file transfers, live log output, multi-host tracking, and rich terminal UIs. Events work for both local and remote (SSH) execution and are always captured in results even without an explicit callback.

Key Concepts

• Three event types: progress (percent/bytes tracking), log (leveled messages: info/warning/error), and data (raw stdout/stderr streams)
• Events are always captured in result.events regardless of whether a callback is registered
• Two built-in display options: EventProgressDisplay (Rich library, full-featured progress bars) and SimpleEventDisplay (lightweight text, no Rich dependency)
• Custom callbacks are plain functions that receive event dicts with an "event" key indicating type
• Multi-host tracking uses display.make_callback(host.name) to create per-host callbacks that render parallel progress bars
• Built-in module support: ftlcopy and ftlget_url emit progress events automatically during chunked transfers
• Ansible module compatibility: Bundled Ansible modules can import ftl2.events and emit events using the same API

Commands and Syntax

Running examples:

uv run python example_streaming.py                # local, no setup
docker-compose up -d && uv run python example_remote_streaming.py  # remote via Docker

Emitting events from modules:

from ftl2.events import emit_progress, emit_log, emit_data
emit_progress(percent=50, message="Copying file", current=512000, total=1024000, task_id="copy-1")
emit_log("message", level="info")       # levels: info, warning, error
emit_data("output\n", stream="stdout")

Streaming executor signatures:

• executelocalstreaming(modulepath, params, timeout=300, checkmode=False, event_callback=None) -> ExecutionResult
• executeremotestreaming(host, bundle_path, params, ...) -> ExecutionResult
• executeremotewithstagingstreaming(host, bundle, params, ...) -> ExecutionResult

Display setup:

# Rich display — use as context manager
display = EventProgressDisplay(console=None, show_log_events=True, show_data_events=False)
with display:
    result = await execute_local_streaming(path, params, event_callback=display.handle_event)

# Simple display — no context manager needed
display = SimpleEventDisplay(output=sys.stderr, show_log_events=True, show_data_events=False)

Relationships

• Module execution — streaming variants (executelocalstreaming, executeremotestreaming) extend the standard executor API with an event_callback parameter
• Gate modules / bundles — remote streaming requires a pre-built bundle; executeremotewithstagingstreaming handles staging automatically
• Ansible compatibility — Ansible modules running inside bundles can use ftl2.events directly, bridging the Ansible-to-FTL2 migration path
• Building applications — the display system (especially multi-host tracking) is key infrastructure for TUI-based apps like ftl2-servercraft
• Check mode — streaming executors accept check_mode=bool, tying into FTL2's idempotency/dry-run system

Exam-Relevant Points

• The three event types are progress, log, and data — emitted via emitprogress(), emitlog(), emit_data()
• Events are always captured in result.events even with no callback — callbacks are optional, not required
• EventProgressDisplay requires Rich; SimpleEventDisplay has no Rich dependency
• Multi-host progress uses display.makecallback(host.name) — not display.handleevent directly
• emitprogress optional parameters: current, total, taskid (for multi-task tracking)
• emit_log levels: info, warning, error
• Three streaming executor functions exist: local, remote (pre-staged bundle), and remote-with-auto-staging
• All streaming executors are async (await) and return ExecutionResult
• Default timeout for all streaming executors is 300 seconds
• Bundled Ansible modules can import and use ftl2.events — this is an FTL2-specific extension, not standard Ansible