Add built-in HEALTHCHECK_PATH setting

Requests to this path return a 200 response before host validation,
HTTPS redirect, or any other middleware runs. This avoids common issues
with load balancers and PaaS health checkers that use internal hostnames
or plain HTTP.

Author: davegaeddert

plain/plain/http/README.md

@@ -15,6 +15,7 @@
     - [Default response headers](#default-response-headers)
 - [Content Security Policy (CSP)](#content-security-policy-csp)
 - [Middleware](#middleware)
+- [Healthcheck](#healthcheck)
 - [Exceptions](#exceptions)
 - [FAQs](#faqs)
 - [Installation](#installation)
@@ -309,6 +310,22 @@ class TimingMiddleware(HttpMiddleware):
         return response
 ```
 
+## Healthcheck
+
+The `HEALTHCHECK_PATH` setting provides a built-in healthcheck endpoint for load balancers, Kubernetes probes, and PaaS platforms like Railway.
+
+```python
+# app/settings.py
+HEALTHCHECK_PATH = "/up/"
+```
+
+When set, requests to this exact path return a `200` response before any other middleware runs — bypassing host validation, HTTPS redirects, and authentication. This avoids two common issues with health checkers:
+
+1. **ALLOWED_HOSTS rejection** — the health checker uses an internal hostname not in the allowlist
+2. **HTTPS redirect loops** — the health checker sends plain HTTP without proxy headers
+
+By default, `HEALTHCHECK_PATH` is empty (disabled).
+
 ## Exceptions
 
 Raise exceptions to return specific HTTP error responses.

plain/plain/internal/handlers/base.py

@@ -22,6 +22,7 @@
 
 # These middleware classes are always used by Plain.
 BUILTIN_BEFORE_MIDDLEWARE = [
+    "plain.internal.middleware.healthcheck.HealthcheckMiddleware",  # Respond to healthcheck before anything else
     "plain.internal.middleware.hosts.HostValidationMiddleware",  # Validate Host header first
     "plain.internal.middleware.headers.DefaultHeadersMiddleware",  # Runs after response, to set missing headers
     "plain.internal.middleware.https.HttpsRedirectMiddleware",  # Runs before response, to redirect to HTTPS quickly

plain/plain/internal/middleware/healthcheck.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from plain.http import HttpMiddleware, Response
+from plain.runtime import settings
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from plain.http import Request
+
+
+class HealthcheckMiddleware(HttpMiddleware):
+    def __init__(self, get_response: Callable[[Request], Response]):
+        super().__init__(get_response)
+        self.healthcheck_path = settings.HEALTHCHECK_PATH
+
+    def process_request(self, request: Request) -> Response:
+        if self.healthcheck_path and request.path_info == self.healthcheck_path:
+            return Response("ok", content_type="text/plain", status_code=200)
+
+        return self.get_response(request)

plain/plain/runtime/global_settings.py

@@ -33,6 +33,12 @@
 # - "192.168.1.0/24" matches IP addresses in that CIDR range
 ALLOWED_HOSTS: list[str] = []
 
+# Path for the built-in healthcheck endpoint.
+# When set, requests to this exact path return a 200 "ok" response
+# before host validation, HTTPS redirect, or any other middleware runs.
+# Example: HEALTHCHECK_PATH = "/up/"
+HEALTHCHECK_PATH: str = ""
+
 # Default headers for all responses.
 # Header values can include {request.attribute} placeholders for dynamic content.
 # Example: "script-src 'nonce-{request.csp_nonce}'" will use the request's nonce.