Ref #519 -- Extend CLI HTTPS support and verbosity

* Enable default support for X-forwarded headers to handle HTTPS redirects.
* Add more error handling to descritive outputs to support user debugging effors.

Author: codingjoe

docs/container.md

@@ -34,9 +34,14 @@ urlpatterns = [
 … and then run the health check command:
 
 ```shell
-python manage.py health_check health_check-container localhost:8000
+python manage.py health_check health_check-container localhost:8000 --forwarded-host example.com
 ```
 
+> [!IMPORTANT]
+> When using the `health_check` command, ensure that the host is included in your `ALLOWED_HOSTS` setting.
+> The command automatically uses the first entry from `ALLOWED_HOSTS` for the `X-Forwarded-Host` header if available.
+> For SSL-enabled applications, use the `--forwarded-proto https` flag.
+
 Your host name and port may vary depending on your container setup.
 
 ## Configuration Examples
@@ -80,13 +85,18 @@ spec:
         - name: web
           image: my-django-image:latest
           livenessProbe:
-            exec:
-              command:
-                - python
-                - manage.py
-                - health_check
-                - health_check-container
-                - web:8000
+            httpGet:
+              path: /container/health/
+              port: 8000
+              httpHeaders:
+                - name: X-Forwarded-Proto
+                  value: https
+                - name: X-Forwarded-Host
+                  value: example.com  # Use your actual domain from ALLOWED_HOSTS
             periodSeconds: 60
             timeoutSeconds: 10
 ```
+
+> [!TIP]
+> Configure `X-Forwarded-Host` to match your domain from `ALLOWED_HOSTS` and set `X-Forwarded-Proto` to `https` if your application enforces SSL.
+> See Django's [USE_X_FORWARDED_HOST](https://docs.djangoproject.com/en/stable/ref/settings/#std-setting-USE_X_FORWARDED_HOST) and [SECURE_PROXY_SSL_HEADER](https://docs.djangoproject.com/en/stable/ref/settings/#secure-proxy-ssl-header) settings.

health_check/management/commands/health_check.py

@@ -1,14 +1,28 @@
+import os
 import sys
 import urllib.error
 import urllib.request
 
+from django.conf import settings
 from django.core.management.base import BaseCommand
-from django.urls import reverse
+from django.urls import NoReverseMatch, reverse
 
 
 class Command(BaseCommand):
     help = "Run health checks and exit 0 if everything went well."
 
+    @property
+    def default_forwarded_host(self):
+        return (
+            settings.ALLOWED_HOSTS[0].strip(".")
+            if settings.ALLOWED_HOSTS and settings.ALLOWED_HOSTS[0] != "*"
+            else None
+        )
+
+    @property
+    def default_addrport(self):
+        return ":".join([os.getenv("HOST", "127.0.0.1"), os.getenv("PORT", "8000")])
+
     def add_arguments(self, parser):
         parser.add_argument(
             "endpoint",
@@ -19,28 +33,90 @@ def add_arguments(self, parser):
             "addrport",
             nargs="?",
             type=str,
-            help="Optional port number, or ipaddr:port (default: localhost:8000)",
-            default="localhost:8000",
+            default=self.default_addrport,
+            help=f"Optional port number, or ipaddr:port (default: :{self.default_addrport})",
+        )
+        parser.add_argument(
+            "--forwarded-host",
+            type=str,
+            default=self.default_forwarded_host,
+            help=f"Value for X-Forwarded-Host header (default: {self.default_forwarded_host})",
+        )
+        parser.add_argument(
+            "--forwarded-proto",
+            type=str,
+            choices=["http", "https"],
+            default="https",
+            help="Value for X-Forwarded-Proto header (default: https)",
+        )
+        parser.add_argument(
+            "--timeout",
+            type=int,
+            default=5,
+            help="Timeout in seconds for the health check request (default: 5 seconds)",
         )
 
     def handle(self, *args, **options):
         endpoint = options.get("endpoint")
-        path = reverse(endpoint)
-        host, sep, port = options.get("addrport").partition(":")
-        url = f"http://{host}:{port}{path}" if sep else f"http://{host}{path}"
-        request = urllib.request.Request(  # noqa: S310
-            url, headers={"Accept": "text/plain"}
+        try:
+            path = reverse(endpoint)
+        except NoReverseMatch as e:
+            self.stderr.write(
+                f"Could not resolve endpoint {endpoint!r}: {e}\n"
+                "Please provide a valid URL pattern name for the health check endpoint."
+            )
+            sys.exit(2)
+        addrport = options.get("addrport")
+        proto = (
+            "https"
+            if settings.SECURE_SSL_REDIRECT and not settings.USE_X_FORWARDED_HOST
+            else "http"
         )
+        url = f"{proto}://{addrport}{path}"
+
+        headers = {"Accept": "text/plain"}
+
+        # Add X-Forwarded-Host header
+        if forwarded_host := options.get("forwarded_host"):
+            headers["X-Forwarded-Host"] = forwarded_host
+
+        # Add X-Forwarded-Proto header
+        if forwarded_proto := options.get("forwarded_proto"):
+            headers["X-Forwarded-Proto"] = forwarded_proto
+
+        if options.get("verbosity", 1) >= 2:
+            self.stdout.write(
+                f"Checking health endpoint at {url!r} with headers: {headers}"
+            )
+
+        request = urllib.request.Request(url, headers=headers)  # noqa: S310
         try:
-            response = urllib.request.urlopen(request)  # noqa: S310
+            response = urllib.request.urlopen(request, timeout=options["timeout"])  # noqa: S310
         except urllib.error.HTTPError as e:
-            # 500 status codes will raise HTTPError
-            self.stdout.write(e.read().decode("utf-8"))
-            sys.exit(1)
+            match e.code:
+                case 500:  # Health check failed
+                    self.stdout.write(e.read().decode("utf-8"))
+                    sys.exit(1)
+                case 400:
+                    self.stderr.write(
+                        f'"{url}" is not reachable: {e.reason}\nPlease check your ALLOWED_HOSTS setting or use the --forwarded-host option.'
+                    )
+                    sys.exit(2)
+                case _:
+                    self.stderr.write(
+                        "Unexpected HTTP error "
+                        f"when trying to reach {url!r}: {e}\n"
+                        f"You may have selected an invalid endpoint {endpoint!r}"
+                        f" or another application is running on {addrport!r}."
+                    )
+                    sys.exit(2)
         except urllib.error.URLError as e:
             self.stderr.write(
-                f'"{url}" is not reachable: {e.reason}\nPlease check your ALLOWED_HOSTS setting.'
+                f'"{url}" is not reachable: {e.reason}\nPlease check your server is running and reachable.'
             )
             sys.exit(2)
+        except TimeoutError as e:
+            self.stderr.write(f"Timeout when trying to reach {url!r}: {e}")
+            sys.exit(2)
         else:
             self.stdout.write(response.read().decode("utf-8"))

tests/test_management.py

@@ -64,3 +64,39 @@ def test_handle__url_error__connection_refused(self):
         assert exc_info.value.code == 2
         error_output = stderr.getvalue()
         assert "not reachable" in error_output
+
+    def test_handle__forwarded_host(self, live_server):
+        """Set X-Forwarded-Host header when --forwarded-host is provided."""
+        parsed = urlparse(live_server.url)
+        addrport = f"{parsed.hostname}:{parsed.port}"
+
+        stdout = StringIO()
+        stderr = StringIO()
+        call_command(
+            "health_check",
+            "health_check_test",
+            addrport,
+            forwarded_host="example.com",
+            stdout=stdout,
+            stderr=stderr,
+        )
+        output = stdout.getvalue()
+        assert "OK" in output or "working" in output
+
+    def test_handle__forwarded_proto(self, live_server):
+        """Set X-Forwarded-Proto header when --forwarded-proto is provided."""
+        parsed = urlparse(live_server.url)
+        addrport = f"{parsed.hostname}:{parsed.port}"
+
+        stdout = StringIO()
+        stderr = StringIO()
+        call_command(
+            "health_check",
+            "health_check_test",
+            addrport,
+            forwarded_proto="https",
+            stdout=stdout,
+            stderr=stderr,
+        )
+        output = stdout.getvalue()
+        assert "OK" in output or "working" in output