Document named-routes & invoke, polish reverse_proxy

src/docs/markdown/caddyfile/concepts.md

@@ -14,9 +14,10 @@ This document will help you learn about the HTTP Caddyfile in detail.
 3. [Matchers](#matchers)
 4. [Placeholders](#placeholders)
 5. [Snippets](#snippets)
-6. [Comments](#comments)
-7. [Environment variables](#environment-variables)
-8. [Global options](#global-options)
+6. [Named Routes](#named-routes)
+7. [Comments](#comments)
+8. [Environment variables](#environment-variables)
+9. [Global options](#global-options)
 
 
 ## Structure
@@ -28,6 +29,7 @@ The Caddyfile's structure can be described visually:
 Key points:
 
 - An optional [**global options block**](#global-options) can be the very first thing in the file.
+- [Snippets](#snippets) or [named routes](#named-routes) may optionally appear next.
 - Otherwise, the first line of the Caddyfile is **always** the [address(es)](#addresses) of the site to serve.
 - All [directives](#directives) and [matchers](#matchers) **must** go in a site block. There is no global scope or inheritance across site blocks.
 - If there is only one site block, its curly braces `{ }` are optional.
@@ -88,17 +90,17 @@ If a request matches multiple site blocks, the site block with the most specific
 [**Directives**](/docs/caddyfile/directives) are functional keywords which customize how the site is served. They **must** appear within site blocks. For example, a complete file server config might look like this:
 
 ```caddy
-localhost
-
+localhost {
 	file_server
+}
 ```
 
 Or a reverse proxy:
 
 ```caddy
-localhost
-
+localhost {
 	reverse_proxy localhost:9000
+}
 ```
 
 In these examples, [`file_server`](/docs/caddyfile/directives/file_server) and [`reverse_proxy`](/docs/caddyfile/directives/reverse_proxy) are directives. Directives are the first word on a line in a site block.
@@ -108,11 +110,11 @@ In the second example, `localhost:9000` is an **argument** because it appears on
 Sometimes directives can open their own blocks. **Subdirectives** appear on the beginning of each line within directive blocks:
 
 ```caddy
-localhost
-
+localhost {
 	reverse_proxy localhost:9000 localhost:9001 {
 		lb_policy first
 	}
+}
 ```
 
 Here, `lb_policy` is a subdirective to [`reverse_proxy`](/docs/caddyfile/directives/reverse_proxy) (it sets the load balancing policy to use between backends).
@@ -333,6 +335,27 @@ b.example.com {
 ```
 
 
+## Named Routes
+
+Named routes use syntax similar to [snippets](#snippets); they're a special block defined outside of site blocks, prefixed with `&(` and ending in `)` with the name in between.
+
+```caddy
+&(app-proxy) {
+	reverse_proxy app-01:8080 app-02:8080 app-03:8080
+}
+```
+
+And then you can reuse this named route within any site:
+
+```caddy-d
+invoke app-proxy
+```
+
+This is particularly useful to reduce memory usage if the same route is needed in many different sites, or if multiple different matcher conditions are needed to invoke the same route.
+
+See the [`invoke` directive](/docs/caddyfile/directives/invoke) documentation for more details.
+
+
 ## Comments
 
 Comments start with `#` and proceed until the end of the line:

src/docs/markdown/caddyfile/directives.md

@@ -54,6 +54,7 @@ Directive | Description
 **[handle_path](/docs/caddyfile/directives/handle_path)** | Like handle, but strips path prefix
 **[header](/docs/caddyfile/directives/header)** | Sets or removes response headers
 **[import](/docs/caddyfile/directives/import)** | Include snippets or files
+**[invoke](/docs/caddyfile/directives/invoke)** | Invoke a named route
 **[log](/docs/caddyfile/directives/log)** | Enables access/request logging
 **[map](/docs/caddyfile/directives/map)** | Maps an input value to one or more outputs
 **[method](/docs/caddyfile/directives/method)** | Change the HTTP method internally
@@ -143,6 +144,7 @@ push
 templates
 
 # special routing & dispatching directives
+invoke
 handle
 handle_path
 route

src/docs/markdown/caddyfile/directives/invoke.md

@@ -0,0 +1,56 @@
+---
+title: invoke (Caddyfile directive)
+---
+
+# invoke
+
+Invokes a [named route](/docs/caddyfile/concepts#named-routes).
+
+This is useful when paired with HTTP handler directives that have their own in-memory state, or if they are expensive to provision on load. If you have hundreds of sites or more, invoking a named route can help reduce memory usage.
+
+<aside class="tip">
+	
+Unlike [`import`](/docs/caddyfile/directives/import), `invoke` does not support arguments, but you may use [`vars`](/docs/caddyfile/directives/vars) to define variables that can be used within the named route.
+
+</aside>
+
+## Syntax
+
+```caddy-d
+invoke [<matcher>] <route-name>
+```
+
+- **&lt;route-name&gt;** is the name of the previously defined route that should be invoked. If the route is not found, then an error will be triggered.
+
+
+## Examples
+
+Defines a [named route](/docs/caddyfile/concepts#named-routes) with a [`reverse_proxy`](/docs/caddyfile/directives/reverse_proxy) which can be reused in multiple sites, with the same in-memory load balancing state reused for every site.
+
+```caddy
+&(app-proxy) {
+	reverse_proxy app-01:8080 app-02:8080 app-03:8080 {
+		lb_policy least_conn
+		health_uri /healthz
+		health_interval 5s
+	}
+}
+
+# Apex domain allows accessing the app via an /app subpath
+# and the main site otherwise.
+example.com {
+	handle_path /app* {
+		invoke app-proxy
+	}
+
+	handle {
+		root * /srv
+		file_server
+	}
+}
+
+# The app is also accessible via a subdomain.
+app.example.com {
+	invoke app-proxy
+}
+```

src/docs/markdown/caddyfile/directives/reverse_proxy.md

@@ -234,7 +234,7 @@ Append the results of multiple dynamic upstream modules. Useful if you want redu
 
 ### Load balancing
 
-Load balancing is used whenever more than one upstream is defined.
+Load balancing is used whenever more than one upstream is defined. This is enabled by default, with the `random` load balancing policy.
 
 - **lb_policy** <span id="lb_policy"/> is the name of the load balancing policy, along with any options. Default: `random`.
 
@@ -295,13 +295,13 @@ Load balancing is used whenever more than one upstream is defined.
 
 #### Active health checks
 
-Active health checks perform health checking in the background on a timer:
+Active health checks perform health checking in the background on a timer. To enable this, `health_uri` or `health_port` are required.
 
 - **health_uri** <span id="health_uri"/> is the URI path (and optional query) for active health checks.
 
 - **health_port** <span id="health_port"/> is the port to use for active health checks, if different from the upstream's port.
 
-- **health_interval** <span id="health_interval"/> is a [duration value](/docs/conventions#durations) that defines how often to perform active health checks.
+- **health_interval** <span id="health_interval"/> is a [duration value](/docs/conventions#durations) that defines how often to perform active health checks. Default: `30s`.
 
 - **health_timeout** <span id="health_timeout"/> is a [duration value](/docs/conventions#durations) that defines how long to wait for a reply before marking the backend as down.
 
@@ -315,7 +315,7 @@ Active health checks perform health checking in the background on a timer:
 
 #### Passive health checks
 
-Passive health checks happen inline with actual proxied requests:
+Passive health checks happen inline with actual proxied requests. To enable this, `fail_duration` is required.
 
 - **fail_duration** <span id="fail_duration"/>  is a [duration value](/docs/conventions#durations) that defines how long to remember a failed request. A duration > `0` enables passive health checking; the default is `0` (off). A reasonable starting point might be `30s` to balance error rates with responsiveness when bringing an unhealthy upstream back online; but feel free to experiment to find the right balance for your usecase.