Overview

Date: 2026-05-11

Time: 15:56

Overview

The watchdog module monitors game servers managed by ftl2-servercraft and automatically tears them down when they've been empty for a configurable grace period. It runs as an async loop that polls player count via game-specific scripts, tracks empty/unreachable state, and orchestrates a backup-then-destroy sequence when shutdown conditions are met. It communicates status through a shared ServerState object (for TUI display) and a log callback.

Usage Patterns

The single entry point is run_watchdog(), called with a server config, mutable state object, and logging function:

await run_watchdog(
    config=server_config,      # ServerConfig with IP, paths, timing
    state=server_state,        # ServerState mutated in-place for TUI
    log_callback=log_fn,       # Callable[[str], None] for activity log
)

The function runs until one of three exits: (1) grace period expires and server is torn down, (2) server becomes unreachable 3 times consecutively and is torn down, or (3) state.watchdog_active is set to False externally (user stop).

API and Configuration

Key configuration from ServerConfig:

• grace_period — seconds to wait after server empties before teardown
• poll_interval — seconds between player count checks
• slack_channel — Slack channel for teardown notifications
• inventorypath / statepath — FTL2 inventory and state file paths
• script — identifies which game script to load via scripts.get_script()

FTL2 automation context is configured with:

• Secret bindings for LINODETOKEN and SLACKTOKEN (via Vault)
• failfast=True, autoinstall_deps=True

Hardcoded: 600s warmup before first poll (server boot time).

Key Behaviors

• Warmup delay: Sleeps 600 seconds before first poll to let the server finish starting.
• Consecutive failure threshold: 3 unreachable polls triggers emergency backup + teardown. Individual failures just log and continue.
• Backup-before-destroy: Both the empty-grace and unreachable paths attempt backup first. If backup fails, teardown is aborted and status set to error.
• Slack notifications: Sent on teardown but failures are silently swallowed (except Exception: pass).
• Grace period cancellation: If a player joins during the grace period, the timer resets completely.
• State mutation: The state object is updated in-place throughout — status, playercount, emptysince, watchdogactive, ipaddress, last_error. The TUI reads these fields.
• Clean user stop: When state.watchdog_active is set False externally, the loop exits and status reverts to "provisioned" or "stopped" based on actual provisioning state.

Relationships

• ftl2.automation — async context manager providing the FTL2 runtime (ftl object) for running modules
• .config.ServerConfig — server definition (IP lookup, paths, timing, script selection)
• .scripts — game-specific script interface; getscript() returns an object with getplayercount(), backupworld(), saveandstop(), destroy()
• community.general.linode_v4 — Linode API module (used by destroy scripts)
• community.general.slack — Slack notification module (called directly via ftl.local)
• ServerState — shared mutable object read by the TUI layer for real-time display
• HashiCorp Vault — secrets resolved at automation context creation via secret_bindings