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

.env.example

@@ -1 +1,4 @@
-TOKEN="YOUR BOT TOKEN HERE"
+TOKEN="YOUR BOT TOKEN HERE"
+HEALTHCHECK_HOST="127.0.0.1"
+HEALTHCHECK_PORT="8080"
+HEALTHCHECK_PATH="/"

Dockerfile

@@ -28,4 +28,6 @@ RUN pip install -r requirements.txt
 COPY src/ ./src
 USER appuser
 
+EXPOSE 8080
+
 CMD ["python", "-m", "src"]

README.md

@@ -16,7 +16,22 @@ Versa is a simple utility Discord bot, with the main goal of being open source a
 
 #### ⚠ **Further support with self-hosting will not be provided.** ⚠
 
+### Healthcheck endpoint
+
+The bot exposes an HTTP healthcheck endpoint for deployment platforms (such as Coolify).
+
+- Method/path: `GET /` (configurable via `HEALTHCHECK_PATH`)
+- Default bind: `127.0.0.1:8080`
+- Config via env vars:
+  - `HEALTHCHECK_HOST`
+  - `HEALTHCHECK_PORT`
+  - `HEALTHCHECK_PATH`
+
+The endpoint returns:
+- `200` when DB is responsive, Discord is connected, and no global Discord rate-limit is active
+- `503` when any check is failing
+
 # License
 
 This project is licensed under AGPL-3.0. Forks and redistributions must remain open-source. See the LICENSE file for
-further info
+further info

src/__main__.py

@@ -4,7 +4,9 @@
 import discord
 
 from src import log_setup
+from src.config import HEALTHCHECK_HOST, HEALTHCHECK_PATH, HEALTHCHECK_PORT
 from src.database import init_db, shutdown_db
+from src.healthcheck import HealthcheckServer
 
 from .config import TOKEN
 
@@ -33,21 +35,44 @@ async def on_ready() -> None:
 
 async def start() -> None:
     original_exc = None
+    healthcheck_server = HealthcheckServer(
+        bot,
+        host=HEALTHCHECK_HOST,
+        port=HEALTHCHECK_PORT,
+        path=HEALTHCHECK_PATH,
+    )
     try:
         await init_db()
+        await healthcheck_server.start()
         async with bot:
             await bot.start(TOKEN)
     except Exception as e:  # noqa: BLE001
         original_exc = e
     finally:
+        healthcheck_stop_exc = None
+        try:
+            await healthcheck_server.stop()
+        except Exception as healthcheck_exc:  # noqa: BLE001
+            healthcheck_stop_exc = healthcheck_exc
+
         try:
             await shutdown_db()
         except Exception as e2:
             if original_exc:
                 msg = "Multiple errors happened when starting the bot"
 
                 raise ExceptionGroup(msg, [original_exc, e2]) from None
+            if healthcheck_stop_exc:
+                msg = "Multiple errors happened during shutdown"
+
+                raise ExceptionGroup(msg, [healthcheck_stop_exc, e2]) from None
             raise
+        if healthcheck_stop_exc:
+            if original_exc:
+                msg = "Multiple errors happened when starting the bot"
+
+                raise ExceptionGroup(msg, [original_exc, healthcheck_stop_exc]) from None
+            raise healthcheck_stop_exc
         if original_exc:
             raise original_exc
 

src/config.py

@@ -9,3 +9,10 @@
 
 DB_PATH = Path(os.getenv("DB_PATH") or Path("data/database.db")).absolute()
 DB_PATH.parent.mkdir(parents=True, exist_ok=True)
+
+HEALTHCHECK_HOST = os.getenv("HEALTHCHECK_HOST", "127.0.0.1")
+HEALTHCHECK_PORT = int(os.getenv("HEALTHCHECK_PORT", "8080"))
+HEALTHCHECK_PATH = os.getenv("HEALTHCHECK_PATH", "/")
+
+if not HEALTHCHECK_PATH.startswith("/"):
+    HEALTHCHECK_PATH = f"/{HEALTHCHECK_PATH}"

src/healthcheck.py

@@ -0,0 +1,139 @@
+import asyncio
+import json
+import logging
+from contextlib import suppress
+from typing import Any
+
+import discord
+from tortoise import Tortoise
+from tortoise.exceptions import ConfigurationError, DBConnectionError, OperationalError
+
+logger = logging.getLogger(__name__)
+
+_REQUEST_TIMEOUT_SECONDS = 5
+
+
+class HealthcheckServer:
+    def __init__(
+        self,
+        bot: discord.Bot,
+        *,
+        host: str,
+        port: int,
+        path: str = "/",
+    ) -> None:
+        self.bot = bot
+        self.host = host
+        self.port = port
+        self.path = path
+        self._server: asyncio.AbstractServer | None = None
+
+    async def start(self) -> None:
+        self._server = await asyncio.start_server(self._handle_connection, host=self.host, port=self.port)
+        logger.info("Healthcheck server listening on http://%s:%s%s", self.host, self.port, self.path)
+
+    async def stop(self) -> None:
+        if self._server is None:
+            return
+
+        self._server.close()
+        await self._server.wait_closed()
+        self._server = None
+
+    async def _handle_connection(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        response_status = 500
+        response_body: dict[str, Any] = {"status": "error"}
+
+        try:
+            request_line = await asyncio.wait_for(reader.readline(), timeout=_REQUEST_TIMEOUT_SECONDS)
+            if not request_line:
+                return
+
+            method, raw_target, _ = request_line.decode("utf-8", errors="replace").strip().split(maxsplit=2)
+            await self._consume_headers(reader)
+
+            target = raw_target.split("?", maxsplit=1)[0]
+            if method != "GET":
+                response_status = 405
+                response_body = {"status": "error", "reason": "method_not_allowed"}
+            elif target != self.path:
+                response_status = 404
+                response_body = {"status": "error", "reason": "not_found"}
+            else:
+                response_status, response_body = await self._health_response()
+        except (UnicodeDecodeError, ValueError):
+            response_status = 400
+            response_body = {"status": "error", "reason": "bad_request"}
+        except TimeoutError:
+            response_status = 408
+            response_body = {"status": "error", "reason": "request_timeout"}
+        finally:
+            writer.write(self._build_response(response_status, response_body))
+            with suppress(ConnectionError):
+                await writer.drain()
+
+            writer.close()
+            with suppress(ConnectionError):
+                await writer.wait_closed()
+
+    async def _health_response(self) -> tuple[int, dict[str, Any]]:
+        db_connected = await self._is_db_connected()
+        discord_connected = self._is_discord_connected()
+        discord_unrate_limited = self._is_discord_unrate_limited()
+
+        checks = {
+            "database_connected": db_connected,
+            "discord_connected": discord_connected,
+            "discord_no_global_ratelimit": discord_unrate_limited,
+        }
+        healthy = all(checks.values())
+        return (
+            200 if healthy else 503,
+            {
+                "status": "ok" if healthy else "degraded",
+                "checks": checks,
+            },
+        )
+
+    async def _is_db_connected(self) -> bool:
+        try:
+            connection = Tortoise.get_connection("default")
+            await connection.execute_query("SELECT 1")
+        except (ConfigurationError, DBConnectionError, OperationalError):
+            return False
+        return True
+
+    def _is_discord_connected(self) -> bool:
+        return self.bot.is_ready() and not self.bot.is_closed()
+
+    def _is_discord_unrate_limited(self) -> bool:
+        global_rate_limit_gate = getattr(self.bot.http, "_global_over", None)
+        if isinstance(global_rate_limit_gate, asyncio.Event):
+            return global_rate_limit_gate.is_set()
+        return not self.bot.is_ws_ratelimited()
+
+    async def _consume_headers(self, reader: asyncio.StreamReader) -> None:
+        while True:
+            line = await asyncio.wait_for(reader.readline(), timeout=_REQUEST_TIMEOUT_SECONDS)
+            if not line or line in {b"\r\n", b"\n"}:
+                return
+
+    def _build_response(self, status_code: int, body: dict[str, Any]) -> bytes:
+        status_text = {
+            200: "OK",
+            400: "Bad Request",
+            404: "Not Found",
+            405: "Method Not Allowed",
+            408: "Request Timeout",
+            500: "Internal Server Error",
+            503: "Service Unavailable",
+        }.get(status_code, "Internal Server Error")
+        payload = json.dumps(body, separators=(",", ":"), sort_keys=True).encode()
+        headers = (
+            f"HTTP/1.1 {status_code} {status_text}\r\n"
+            "Content-Type: application/json\r\n"
+            f"Content-Length: {len(payload)}\r\n"
+            "Connection: close\r\n"
+            "\r\n"
+        ).encode()
+        return headers + payload