From 1ff5103c73c921c8faa82ef3342d904a7f6a8e22 Mon Sep 17 00:00:00 2001 From: Francis Lavoie Date: Mon, 21 Jun 2021 13:50:32 -0400 Subject: [PATCH] docs: Clarify `uri` syntax, replacement variables (#173) - The syntax definition was confusing because it was mixing one-of options and optional arguments which are only relevant for certain options. - Add notes about replacement capture groups. Wording could probably be improved here. Point is, capture groups are supported, using Golang's syntax (doesn't use Caddy's placeholder syntax, which can be a gotcha) - Add similar directives section, mainly to point out that `handle_path` can be used instead in many situations to save a line. The note about `rewrite` is kinda redundant with the small paragraph at the top though. Should we move that explanation down into `Similar directives`? --- src/docs/markdown/caddyfile/directives/uri.md | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/src/docs/markdown/caddyfile/directives/uri.md b/src/docs/markdown/caddyfile/directives/uri.md index e414efc..ae9413b 100644 --- a/src/docs/markdown/caddyfile/directives/uri.md +++ b/src/docs/markdown/caddyfile/directives/uri.md @@ -11,10 +11,13 @@ This directive is distinct from [`rewrite`](rewrite) in that `uri` _partially_ c ## Syntax +Multiple different operations are supported: + ```caddy-d -uri [] strip_prefix|strip_suffix|replace|path_regexp \ - \ - [ []] +uri [] strip_prefix +uri [] strip_suffix +uri [] replace [] +uri [] path_regexp ``` - The first (non-matcher) argument specifies the operation: @@ -23,10 +26,18 @@ uri [] strip_prefix|strip_suffix|replace|path_regexp \ - **replace** performs a substring replacement across the whole URI. - **path_regexp** performs a regular expression replacement on the path portion of the URI. - **<target>** is the prefix, suffix, or search string/regular expression. If a prefix, the leading forward slash may be omitted, since paths always start with a forward slash. -- **<replacement>** is the replacement string (only valid with `replace` and `path_regexp`). +- **<replacement>** is the replacement string (only valid with `replace` and `path_regexp`). Supports using capture groups with `$name` or `${name}` syntax, or with a number for the index, such as `$1`. See the [Go documentation](https://golang.org/pkg/regexp/#Regexp.Expand) for details. - **<limit>** is an optional limit to the maximum number of replacements (only valid with `replace`). +## Similar directives + +Some other directives can also manipulate the request URI. + +- [`rewrite`](rewrite) will change the entire path and query to a new value, instead of doing a partial change like `uri` does. +- [`handle_path`](handle_path) does the same as [`handle`](handle), but it strips a prefix from the request before running its handlers. Can be used instead of `uri strip_prefix` to save a line of config in many situations. + + ## Examples Strip `/api` from the beginning of all request paths: