[feature] Caddy handlers separation

caddy/Caddyfile.local

@@ -1,24 +1,20 @@
-# Filename: caddy/Caddyfile
-
 # This global options block explicitly disables Caddy's automatic HTTPS feature.
-# This is the most reliable way to ensure Caddy acts as a simple HTTP proxy.
+# This is the most reliable way to ensure Caddy acts as a simple HTTP proxy locally.
 {
-    auto_https off
+	auto_https off
 }
 
-# This is a robust configuration for a containerized environment.
 # It tells Caddy to listen on its internal port 80 for any incoming hostname.
-# Docker Compose maps your host port (8080) to this container port.
+# Docker maps our host port (8080) to this container port.
 :80 {
-    # Define a logging format for easier debugging.
-    log {
-        output stdout
-        format console
-    }
+	# Define a logging format for easier debugging.
+	log {
+		output stdout
+		format console
+	}
 
-    # Reverse proxy all incoming requests to the 'api' service.
-    # The service name 'api' is resolved by Docker's internal DNS to the
-    # correct container IP on the 'caddy_net' network.
-    # The API container listens on port 8080 (from your ENV_HTTP_PORT).
-    reverse_proxy api:8080
+	# Reverse proxy all incoming requests to the 'api' service.
+	# 	- The service name 'api' is resolved by Docker's internal DNS to the correct container IP on the 'caddy_net' network.
+	# 	- The API container listens on port 8080 (from the ENV_HTTP_PORT).
+	reverse_proxy api:8080
 }

caddy/Caddyfile.prod

@@ -1,19 +1,18 @@
-# Filename: caddy/Caddyfile.prod
 # Caddy will automatically provision a Let's Encrypt certificate.
 
 oullin.io {
 	# Enable compression to reduce bandwidth usage.
 	encode gzip zstd
 
 	# Add security-related headers to protect against common attacks.
+	# 	- Strict-Transport-Security: Enable HSTS to ensure browsers only connect via HTTPS.
+	# 	- X-Frame-Options: Prevent clickjacking attacks.
+	# 	- X-Content-Type-Options: Prevent content type sniffing.
+	# 	- Referrer-Policy: Enhances user privacy.
 	header {
-		# Enable HSTS to ensure browsers only connect via HTTPS.
 		Strict-Transport-Security "max-age=31536000;"
-		# Prevent clickjacking attacks.
 		X-Frame-Options "SAMEORIGIN"
-		# Prevent content type sniffing.
 		X-Content-Type-Options "nosniff"
-		# Enhances user privacy.
 		Referrer-Policy "strict-origin-when-cross-origin"
 	}
 
@@ -26,28 +25,30 @@ oullin.io {
 		format json
 	}
 
-	# Reverse-proxy all requests to the Go API, forwarding Host + auth headers
-	reverse_proxy {
-		# Tell Caddy which upstream to send to
-		to api:8080
-
-		# Preserve the original Host header
-		header_up Host {host}
-
-		# Forward the client-sent auth headers
-		header_up X-API-Username {http.request.header.X-API-Username}
-		header_up X-API-Key {http.request.header.X-API-Key}
-		header_up X-API-Signature {http.request.header.X-API-Signature}
-
-		# *** DEBUG: echo back to client what Caddy actually saw ***
-		# header_down X-Debug-Username {http.request.header.X-API-Username}
-		# header_down X-Debug-Key {http.request.header.X-API-Key}
-		# header_down X-Debug-Signature {http.request.header.X-API-Signature}
-
-		# Transport timeouts
-		transport http {
-			dial_timeout 10s
-			response_header_timeout 30s
+	# API handler.
+	# 	- Reverse-proxy all requests to the Go API, forwarding Host + auth headers.
+	#	- to: Tell Caddy which upstream to send to.
+	#	- header_up: Preserve the original Host header.
+	#	- header_up X-*: Forward the client headers.
+	handle_path /api/* {
+		reverse_proxy to api:8080 {
+			header_up Host {host}
+			header_up X-API-Username {http.request.header.X-API-Username}
+			header_up X-API-Key {http.request.header.X-API-Key}
+			header_up X-API-Signature {http.request.header.X-API-Signature}
+
+			transport http {
+				dial_timeout 10s
+				response_header_timeout 30s
+			}
 		}
 	}
+
+	# Default handler.
+	# 	- Route all other traffic to the Vue frontend app.
+	#	- `web_caddy_prod` is the Vue app's container name.
+	# 	- source: https://github.com/oullin/web
+	handle {
+		reverse_proxy web_caddy_prod:80
+	}
 }

caddy/readme.md

@@ -0,0 +1,8 @@
+# Debugging
+
+### Headers
+```text
+header_down X-Debug-Username {http.request.header.X-API-Username}
+header_down X-Debug-Key {http.request.header.X-API-Key}
+header_down X-Debug-Signature {http.request.header.X-API-Signature}
+```

config/makefile/app.mk

@@ -1,6 +1,7 @@
 .PHONY: fresh audit watch format run-cli validate-caddy
 
-APP_CADDY_CONFIG_FILE ?= caddy/Caddyfile.prod
+APP_CADDY_CONFIG_PROD_FILE ?= caddy/Caddyfile.prod
+APP_CADDY_CONFIG_LOCAL_FILE ?= caddy/Caddyfile.local
 
 format:
 	gofmt -w -s .
@@ -54,5 +55,7 @@ run-cli:
 # --- Mac:
 #     Needs to be locally installed: https://formulae.brew.sh/formula/caddy
 validate-caddy:
-	caddy fmt --overwrite $(APP_CADDY_CONFIG_FILE)
-	caddy validate --config $(APP_CADDY_CONFIG_FILE)
+	caddy fmt --overwrite $(APP_CADDY_CONFIG_PROD_FILE)
+	caddy validate --config $(APP_CADDY_CONFIG_PROD_FILE)
+	caddy fmt --overwrite $(APP_CADDY_CONFIG_LOCAL_FILE)
+	caddy validate --config $(APP_CADDY_CONFIG_LOCAL_FILE)