doc(dispatch, urlbuilder): document subdomain-based routing support

Expand documentation to cover subdomain parsing (`SubdomainFromHost`) and URL generation (`SubdomainURL`) in `urlbuilder`. Update `dispatch` package docs to explain `HostHasSubdomain` matcher for subdomain-based request routing. This enables flexible routing scenarios such as S3 virtual-hosted-style addressing.

Author: mallardduck

pkg/dispatch/dispatch.go

@@ -1,6 +1,6 @@
 // Package dispatch provides a router-agnostic HTTP request dispatcher that
-// routes to handlers based on Matcher conditions (query parameters, and
-// eventually other request attributes like headers).
+// routes to handlers based on Matcher conditions — query parameters, headers,
+// and Host-header subdomain checks.
 //
 // A Dispatcher implements http.Handler and can be used with any Go HTTP router.
 // Routes are evaluated in specificity order — the first route whose matchers
@@ -15,6 +15,20 @@
 //	})
 //
 //	http.Handle("/bucket", d)  // works with any router
+//
+// # Host-based dispatch
+//
+// HostHasSubdomain matches when the request's Host header is a subdomain of
+// a configured canonical domain (see pkg/urlbuilder's SubdomainFromHost for
+// exact semantics). This is the building block for serving two addressing
+// styles from one process — e.g. S3 path-style vs. virtual-hosted-style
+// requests, or per-tenant subdomains — by routing the subdomain case to one
+// handler and falling through to Default for everything else:
+//
+//	d := dispatch.New(func(b *dispatch.Builder) {
+//	    b.When(dispatch.HostHasSubdomain("s3.example.com")).Do(vhostRouter.ServeHTTP)
+//	    b.Default(pathRouter.ServeHTTP)
+//	})
 package dispatch
 
 import (

pkg/urlbuilder/doc.go

@@ -69,6 +69,26 @@
 //	// Development: S3_CANONICAL_DOMAIN=""
 //	// Production:  S3_CANONICAL_DOMAIN="s3.example.com"
 //
+// # Subdomain-Style Addressing
+//
+// SubdomainFromHost and Builder.SubdomainURL are general host-based routing
+// primitives for apps that address a resource via a subdomain label rather
+// than (or in addition to) a URL path — e.g. S3 virtual-hosted-style bucket
+// access ("mybucket.s3.example.com") or per-tenant subdomains.
+//
+//	// Resolve a label from an inbound request's Host header.
+//	label, ok := urlbuilder.SubdomainFromHost(r.Host, "s3.example.com")
+//	// label == "mybucket", ok == true for Host: mybucket.s3.example.com
+//
+//	// Build a subdomain-style URL for a given label.
+//	urls := urlbuilder.New("s3.example.com")
+//	url, ok := urls.SubdomainURL("mybucket", "/path/to/object.txt")
+//	// url == "https://mybucket.s3.example.com/path/to/object.txt"
+//
+// Pairing SubdomainFromHost with pkg/dispatch's HostHasSubdomain matcher lets
+// a single process serve both addressing styles, dispatching per request
+// based on whether Host resolves to a subdomain.
+//
 // For complete documentation and examples, see:
 // https://github.com/mallardduck/teapot-router/blob/main/docs/URLBUILDER.md
 package urlbuilder