From 9b4599eec94d9a1a22ef51aefaa0512f1556872a Mon Sep 17 00:00:00 2001 From: Francis Lavoie Date: Wed, 12 May 2021 15:21:32 -0400 Subject: [PATCH] docs: A few fixes, one more example (#164) - Change wildcard certs patterns from h3 to h2 header - Clean up `encode.md` a bit - Add TOC entry for `handle_response` - Add response matcher docs for `handle_response` (copied from `encode.md`) - Add example for `handle_response` for handling by status code --- .../markdown/caddyfile/directives/encode.md | 4 +-- .../caddyfile/directives/reverse_proxy.md | 31 ++++++++++++++++++- src/docs/markdown/caddyfile/patterns.md | 2 +- 3 files changed, 33 insertions(+), 4 deletions(-) diff --git a/src/docs/markdown/caddyfile/directives/encode.md b/src/docs/markdown/caddyfile/directives/encode.md index 8d34f33..6df2b3b 100644 --- a/src/docs/markdown/caddyfile/directives/encode.md +++ b/src/docs/markdown/caddyfile/directives/encode.md @@ -30,7 +30,7 @@ encode [] { - **gzip** enables Gzip compression, optionally at the specified level. - **zstd** enables Zstandard compression. - **minimum_length** the minimum number of bytes a response should have to be encoded (default: 512). -- **match** is a [Response matcher](#responsematcher). Only matching Responses are encoded. The default looks like this: +- **match** is a [response matcher](#response-matcher). Only matching responses are encoded. The default looks like this: ```caddy-d match { @@ -60,7 +60,7 @@ By HTTP status code. ### header -See Request matcher [header](/docs/caddyfile/matchers#header). +See the [header](/docs/caddyfile/matchers#header) request matcher for the supported syntax. ## Examples diff --git a/src/docs/markdown/caddyfile/directives/reverse_proxy.md b/src/docs/markdown/caddyfile/directives/reverse_proxy.md index 9f986bc..6cb21f6 100644 --- a/src/docs/markdown/caddyfile/directives/reverse_proxy.md +++ b/src/docs/markdown/caddyfile/directives/reverse_proxy.md @@ -16,6 +16,7 @@ Proxies requests to one or more backends with configurable transport, load balan - [Transports](#transports) - [The `http` transport](#the-http-transport) - [The `fastcgi` tranport](#the-fastcgi-transport) +- [Intercepting responses](#intercepting-responses) - [Examples](#examples) @@ -259,11 +260,26 @@ transport fastcgi { The reverse proxy can be configured to intercept responses from the backend. To facilitate this, response matchers can be defined (similar to the syntax for request matchers) and the first matching `handle_response` route will be invoked. When this happens, the response from the backend is not written to the client, and the configured `handle_response` route will be executed instead, and it is up to that route to write a response. -- **@name** is the name of a response matcher. As long as each response matcher has a unique name, multiple matchers can be defined. A response can be matched on the status code and presence or value of a response header. +- **@name** is the name of a [response matcher](#response-matcher). As long as each response matcher has a unique name, multiple matchers can be defined. A response can be matched on the status code and presence or value of a response header. - **handle_response** defines the route to execute when matched by the given matcher (or, if a matcher is omitted, all responses). The first matching block will be applied. Inside a `handle_response` block, any other [directives](/docs/caddyfile/directives) can be used. +#### Response matcher +**Response matchers** can be used to filter (or classify) responses by specific criteria. +##### status + +```caddy-d +status +``` + +By HTTP status code. + +- **<code...>** is a list of HTTP status codes. Special cases are `2xx`, `3xx`, ... which match against all status codes in the range of 200-299, 300-399, ... respectively + +##### header + +See the [header](/docs/caddyfile/matchers#header) request matcher for the supported syntax. ## Examples @@ -333,3 +349,16 @@ reverse_proxy localhost:8080 { } } ``` + +Custom error page for errors from upstream: + +``` +reverse_proxy localhost:8080 { + @error status 500 503 + handle_response @error { + root * /path/to/error/pages + rewrite /{http.reverse_proxy.status_code}.html + file_server + } +} +``` diff --git a/src/docs/markdown/caddyfile/patterns.md b/src/docs/markdown/caddyfile/patterns.md index d6bae0d..d85bc5f 100644 --- a/src/docs/markdown/caddyfile/patterns.md +++ b/src/docs/markdown/caddyfile/patterns.md @@ -128,7 +128,7 @@ redir /remove/ /remove Using a redirect, the client will have to re-issue the request, enforcing a single acceptable URI for a resource. -### Wildcard certificates +## Wildcard certificates If you need to serve multiple subdomains with the same wildcard certificate, the best way to handle them is with a Caddyfile like this, making use of the [`handle`](/docs/caddyfile/directives/handle) directive and [`host`](/docs/caddyfile/matchers#host) matchers: