update docs

Author: eteubert

document-engine/de-docker-compose/Caddyfile

@@ -1,25 +1,44 @@
+# Reverse proxy for local big-file testing that exercises the shared rendering
+# process without requiring TLS.
+#
+# The shared rendering feature (HTTP2_SHARED_RENDERING_PROCESS_ENABLE) reuses a
+# single pspdfkitd worker checkout across multiple tile requests that arrive as
+# HTTP/2 streams on the same Cowboy connection. The worker is cached in the
+# Cowboy connection process's dictionary, so multiplexing matters: requests on
+# the same HTTP/2 connection share a worker, requests on separate connections
+# do not.
+#
+# TLS is not needed for this to work. Caddy's h2c reverse_proxy uses Go's
+# http.Transport, which maintains a pool of HTTP/2 connections to the upstream
+# and multiplexes requests as streams onto them — regardless of whether the
+# browser-to-Caddy leg is HTTP/1.1 or HTTP/2. Multiple browser HTTP/1.1
+# requests are funnelled onto a single h2c upstream connection, giving Cowboy
+# the HTTP/2 stream multiplexing it needs.
+#
+# Non-tile traffic (uploads, dashboard, API) stays on HTTP/1.1 upstream to
+# avoid Cowboy's HTTP/2 reset-rate guard on large request bodies.
 {
-  auto_https off
+	auto_https off
 }
 
 :5000 {
-  request_body {
-    max_size 50GB
-  }
+	request_body {
+		max_size 50GB
+	}
 
-  # Match the tile-rendering route that needs an upstream HTTP/2 hop to exercise the shared rendering process code path.
-  @render_tiles path_regexp render_tiles ^/i/d/[^/]+/h/[^/]+/page-.*
+	# Match the tile-rendering route that needs an upstream HTTP/2 hop to exercise the shared rendering process code path.
+	@render_tiles path_regexp render_tiles ^/i/d/[^/]+/h/[^/]+/page-.*
 
-  handle @render_tiles {
-    reverse_proxy h2c://document-engine:5000
-  }
+	handle @render_tiles {
+		reverse_proxy h2c://document-engine:5000
+	}
 
-  handle {
-    reverse_proxy http://document-engine:5000 {
-      transport http {
-        versions 1.1
-        response_header_timeout 15m
-      }
-    }
-  }
+	handle {
+		reverse_proxy http://document-engine:5000 {
+			transport http {
+				versions 1.1
+				response_header_timeout 15m
+			}
+		}
+	}
 }

document-engine/de-docker-compose/README.md

@@ -84,7 +84,7 @@ Caddy is configured to:
 - Proxy `/i/d/.../h/.../page-*` tile-rendering requests upstream over HTTP/2
 - Keep all other upstream requests on HTTP/1.1 with `response_header_timeout 15m`
 
-The example still exposes the dashboard at `http://localhost:5000/dashboard`. That is intentional: the special HTTP/2 requirement applies to the upstream Caddy-to-Document-Engine hop for tile rendering, which is configured with cleartext HTTP/2 (`h2c`). If you also want browser-to-Caddy HTTP/2, the stack would need to switch to local HTTPS instead of the current `auto_https off` setup.
+The dashboard is exposed at plain `http://localhost:5000/dashboard`. TLS is not needed: Caddy's h2c reverse proxy uses Go's `http.Transport`, which multiplexes incoming HTTP/1.1 requests onto a single upstream HTTP/2 connection. This gives Document Engine the HTTP/2 stream multiplexing it needs to reuse a single rendering worker across concurrent tile requests.
 
 ## API usage examples