Host Lifecycle Step Logging Design

Goal

Provide granular, live progress feedback in the web GUI during lifecycle operations (initialize, start, stop, delete) without exposing sensitive internal paths or raw subprocess mechanics unless they fail.

Approach

Currently, l4d2ctl executes operations silently unless a subprocess fails. l4d2web captures stdout and stderr from l4d2ctl and pushes it to the browser via Server-Sent Events.

We will modify l4d2host/instances.py to emit safe, high-level step markers to stdout.

Since l4d2web uses subprocess.Popen(..., stdout=subprocess.PIPE) to execute l4d2ctl, any standard Python print(..., flush=True) in l4d2host will be naturally captured by job_worker.py and forwarded to the GUI as stdout events.

Logging Strategy

We will introduce an explicit _emit_step(msg: str, on_stdout: Callable | None, passthrough: bool) helper in l4d2host/instances.py to correctly route step output based on the calling context:

If on_stdout is provided (e.g. programmatic use), call it.
If passthrough is true (e.g. l4d2ctl CLI), print(..., flush=True).

Step Messages

initialize_instance

creating instance directories...
writing instance.env...
writing server.cfg...
initialization complete.

start_instance

mounting runtime overlay...
copying server.cfg to runtime...
starting systemd service...
start complete.

stop_instance

stopping systemd service...
unmounting runtime overlay...
stop complete.

delete_instance

stopping systemd service (if running)...
unmounting runtime overlay (if mounted)...
removing instance files...
delete complete.

File Changes

l4d2host/instances.py
- Add _emit_step helper.
- Insert calls to _emit_step at key locations in all lifecycle functions.
l4d2web/services/job_worker.py
- Add synthetic web-layer boundary logs (starting initialize for test-server, finished initialize successfully) to clearly distinguish the boundaries between multiple l4d2ctl operations in compound jobs like start (which calls initialize then start).

Safety & Secrets

print statements must not include full absolute paths (e.g. avoid printing /var/lib/left4me/runtime/alpha/merged).
print statements must not echo spec data or env vars that might contain future RCON passwords or sensitive args.

Test Impact

test_l4d2_facade.py and test_job_worker.py that use fake run_command handlers might need to explicitly emit stdout if tests assert exact sequences.
Existing tests that call initialize_instance without passthrough will silently ignore steps as expected.

2.7 KiB Raw Blame History