feat(healthcheck): add runtime /health endpoint with DB/Discord readiness and heartbeat probes

[Copilot]

This adds an HTTP healthcheck surface for deployments (Coolify) so the bot can be monitored externally for runtime degradation, not just process liveness. The endpoint supports GET /health and reports unhealthy when core dependencies are degraded.

• Healthcheck server and response contract

  • Introduced a lightweight async HTTP server (src/runtime_healthcheck.py) with configurable host/port.
  • Handles:
    • GET /health → health payload (200 or 503)
    • non-matching path → 404
    • non-GET methods → 405
  • Health payload includes per-check booleans:
    • DB connectivity/responsiveness
    • Discord connection status
    • Discord global rate-limit status (via public is_ws_ratelimited())
    • Discord heartbeat health (shard latency-based stall detection)
  • Tightened heartbeat latency threshold to 10s so blocked/stalled heartbeats degrade health sooner.

• Bot lifecycle integration

  • Wired healthcheck startup/shutdown into bot runtime flow.
  • Healthcheck startup is handled by a dedicated cog (src/cogs/healthcheck.py) via @discord.Cog.listener(once=True) on connect.
  • Shutdown in src/__main__.py stops the server through the healthcheck cog while preserving exception-group behavior.
  • Healthcheck can be disabled by leaving HEALTHCHECK_HOST unset or setting it to an empty string.

• Configuration and deployment defaults

  • Added env config in src/config.py:
    • HEALTHCHECK_HOST (no app-side default; optional)
    • HEALTHCHECK_PORT (no app-side default; required only when HEALTHCHECK_HOST is configured)
  • Added explicit runtime validation so invalid/missing HEALTHCHECK_PORT fails fast only when healthcheck is enabled.
  • Updated .env.example and README healthcheck docs to reflect fixed /health path and disable behavior.
  • Exposed container port 8080 in Dockerfile for platform probing.
  • Added Docker HEALTHCHECK in Dockerfile using wget against http://${HEALTHCHECK_HOST}:${HEALTHCHECK_PORT}/health.
  • Added Docker ENV defaults for HEALTHCHECK_HOST and HEALTHCHECK_PORT so container health probes work out of the box while remaining overridable.

• Documentation

  • Added project-standard docstrings throughout the runtime healthcheck module (module, class, and methods) for maintainability and consistency.

• Typing cleanup

  • Added explicit attribute type annotations at first assignment in touched non-final classes (HealthcheckServer and HealthcheckCog).

checks = {
    "database_connected": db_connected,
    "discord_connected": discord_connected,
    "discord_no_global_ratelimit": discord_unrate_limited,
    "discord_heartbeats_healthy": discord_heartbeat_ok,
}
healthy = all(checks.values())
return (
    200 if healthy else 503,
    {"status": "ok" if healthy else "degraded", "checks": checks},
)

[!WARNING]

[ToothyDev]

@copilot astral.sh is now excluded from the firewall, if you need to make further changes based on that

[ToothyDev]

Additionally, if possible, check for any shard heartbeats being blocked in order to help catch stalls of any kind (e.g. by blocking code)

[Copilot]

Additionally, if possible, check for any shard heartbeats being blocked in order to help catch stalls of any kind (e.g. by blocking code)

Added a heartbeat health probe to the healthcheck response (discord_heartbeats_healthy) so stalled shard heartbeats can flip health to degraded. Included in commit 0823976.

[ToothyDev]

@copilot Change pull request title according to semantic PR titles

[Copilot]

@copilot Change pull request title according to semantic PR titles

Proposed semantic title: feat(healthcheck): add runtime endpoint with DB/Discord readiness and heartbeat probes. I can’t directly edit the PR title from this environment, but this is the title to apply.

[Copilot]

• Define the healthcheck in the Dockerfile
• Use a separate cog for the healthcheck, start the server with discord.Cog.listen(once=true) async def on_connect
• Type attributes on non-final classes on ...

Applied the proposed updates in 9943694 (plus 0324a43): Dockerfile now defines a container HEALTHCHECK, healthcheck server startup moved to a dedicated cog using @discord.Cog.listener(once=True) on connect, and typed attributes were added at first assignment in touched classes.

• Define the healthcheck in the Dockerfile

  • Use a separate cog for the healthcheck, start the server with discord.Cog.listen(once=true) async def on_connect
    ...

Done — proposed changes are applied in 9943694 (and 0324a43) with the healthcheck cog listener startup, Dockerfile healthcheck definition, and typed attributes in touched classes.

[ToothyDev]

@copilot Change dockerfile HEALTHCHECK to use curl or wget, whatever is more appropriate in your view (or makes this simpler)

[Copilot]

@copilot Change dockerfile HEALTHCHECK to use curl or wget, whatever is more appropriate in your view (or makes this simpler)

Updated in 671bea8: Dockerfile HEALTHCHECK now uses wget via shell command and keeps the existing HEALTHCHECK_* env-based URL behavior.

[Paillat-dev]

If the default is used for these, they will be empty/unset in the docker container and as such it will fail. THey need to be added as ENV in the dockerfile and can be optionally overridden later.

[Copilot]

Addressed in 372b9e5: added Dockerfile ENV HEALTHCHECK_HOST=127.0.0.1 and ENV HEALTHCHECK_PORT=8080 so container defaults are set and can still be overridden.

[Paillat-dev]

The defaults should also be removed from there then. And empty hostname could mean the healthcheck is disabled.

[ToothyDev]

@copilot apply this change

[Copilot]

Applied in e9781b5: removed app-side defaults from src/config.py for HEALTHCHECK_HOST/HEALTHCHECK_PORT, and made an unset/empty HEALTHCHECK_HOST disable the healthcheck server in the cog. Screenshot: no UI changes (backend/config-only change).

[ToothyDev]

@copilot Apply the requested changes

[Copilot]

@copilot Apply the requested changes

Applied in 372b9e5: Docker defaults were added as ENV, health endpoint is now fixed at /health, and the runtime healthcheck module was renamed for clarity.