mirrors/caddy-website
1
0
Fork 0
mirror of https://github.com/caddyserver/website.git synced 2025-04-22 04:56:17 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions
caddy-website/src/docs/markdown/caddyfile/directives/uri.md
Francis Lavoie 1ff5103c73
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`?
2021-06-21 11:50:32 -06:00

2.4 KiB
Raw Blame History

title
uri (Caddyfile directive)

uri

Manipulates a request's URI. It can strip path prefix/suffix or replace substrings on the whole URI.

This directive is distinct from rewrite in that uri partially changes the URI, rather than setting it to something completely different as rewrite does. While rewrite is treated specially as an internal redirect, uri is just another handler.

Syntax

Multiple different operations are supported:

uri [<matcher>] strip_prefix <target>
uri [<matcher>] strip_suffix <target>
uri [<matcher>] replace      <target> <replacement> [<limit>]
uri [<matcher>] path_regexp  <target> <replacement>
  • The first (non-matcher) argument specifies the operation:
    • strip_prefix strips a prefix from the path, if it has the prefix.
    • strip_suffix strips a suffix from the path, if it has the suffix.
    • 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). Supports using capture groups with $name or ${name} syntax, or with a number for the index, such as $1. See the Go documentation 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 will change the entire path and query to a new value, instead of doing a partial change like uri does.
  • handle_path does the same as 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:

uri strip_prefix /api

Strip .php from the end of all request paths:

uri strip_suffix .php

Replace "/docs/" with "/v1/docs/" in any request URI:

uri replace /docs/ /v1/docs/

Collapse all repeated slashes in the request path (but not the request query) to a single slash:

uri path_regexp /{2,} /