github.com/caddyserver/caddy/v2/modules/caddyhttp/rewrite

No package summary is available.

Package

Files: 2. Third party imports: 1. Imports from organisation: 0. Tests: 0. Benchmarks: 0.

Vars

Interface guard

Types

Rewrite

Rewrite is a middleware which can rewrite/mutate HTTP requests.

The Method and URI properties are "setters" (the request URI will be overwritten with the given values). Other properties are "modifiers" (they modify existing values in a differentiable way). It is atypical to combine the use of setters and modifiers in a single rewrite.

To ensure consistent behavior, prefix and suffix stripping is performed in the URL-decoded (unescaped, normalized) space by default except for the specific bytes where an escape sequence is used in the prefix or suffix pattern.

For all modifiers, paths are cleaned before being modified so that multiple, consecutive slashes are collapsed into a single slash, and dot elements are resolved and removed. In the special case of a prefix, suffix, or substring containing "//" (repeated slashes), slashes will not be merged while cleaning the path so that the rewrite can be interpreted literally.

Field name	Field type	Comment
Method	`string`	Changes the request's HTTP verb.
URI	`string`	Changes the request's URI, which consists of path and query string. Only components of the URI that are specified will be changed. For example, a value of "/foo.html" or "foo.html" will only change the path and will preserve any existing query string. Similarly, a value of "?a=b" will only change the query string and will not affect the path. Both can also be changed: "/foo?a=b" - this sets both the path and query string at the same time. You can also use placeholders. For example, to preserve the existing query string, you might use: "?{http.request.uri.query}&a=b". Any key-value pairs you add to the query string will not overwrite existing values (individual pairs are append-only). To clear the query string, explicitly set an empty one: "?"
StripPathPrefix	`string`	Strips the given prefix from the beginning of the URI path. The prefix should be written in normalized (unescaped) form, but if an escaping (`%xx`) is used, the path will be required to have that same escape at that position in order to match.
StripPathSuffix	`string`	Strips the given suffix from the end of the URI path. The suffix should be written in normalized (unescaped) form, but if an escaping (`%xx`) is used, the path will be required to have that same escape at that position in order to match.
URISubstring	`[]substrReplacer`	Performs substring replacements on the URI.
PathRegexp	`[]*regexReplacer`	Performs regular expression replacements on the URI path.
Query	`*queryOps`	Mutates the query string of the URI.
logger	`*zap.Logger`	No comment on field.

queryOps

queryOps describes the operations to perform on query keys: add, set, rename and delete.

Field name	Field type	Comment
Rename	`[]queryOpsArguments`	Renames a query key from Key to Val, without affecting the value.
Set	`[]queryOpsArguments`	Sets query parameters; overwrites a query key with the given value.
Add	`[]queryOpsArguments`	Adds query parameters; does not overwrite an existing query field, and only appends an additional value for that key if any already exist.
Replace	`[]*queryOpsReplacement`	Replaces query parameters.
Delete	`[]string`	Deletes a given query key by name.

queryOpsArguments

This type doesn't have documentation.

Field name	Field type	Comment
Key	`string`	A key in the query string. Note that query string keys may appear multiple times.
Val	`string`	The value for the given operation; for add and set, this is simply the value of the query, and for rename this is the query key to rename to.

queryOpsReplacement

This type doesn't have documentation.

Field name	Field type	Comment
Key	`string`	The key to replace in the query string.
Search	`string`	The substring to search for.
SearchRegexp	`string`	The regular expression to search with.
Replace	`string`	The string with which to replace matches.
re	`*regexp.Regexp`	No comment on field.

regexReplacer

regexReplacer describes a replacement using a regular expression.

Field name	Field type	Comment
Find	`string`	The regular expression to find.
Replace	`string`	The substring to replace with. Supports placeholders and regular expression capture groups.
re	`*regexp.Regexp`	No comment on field.

substrReplacer

substrReplacer describes either a simple and fast substring replacement.

Field name	Field type	Comment
Find	`string`	A substring to find. Supports placeholders.
Replace	`string`	The substring to replace with. Supports placeholders.
Limit	`int`	Maximum number of replacements per string. Set to <= 0 for no limit (default).

Functions

func (*Rewrite) Provision

Provision sets up rewr.

Uses: fmt.Errorf, regexp.Compile.

func (*queryOpsReplacement) Provision

Provision compiles the query replace operation regex.

Uses: fmt.Errorf, regexp.Compile.

func (Rewrite) CaddyModule

CaddyModule returns the Caddy module information.

func (Rewrite) Rewrite

rewrite performs the rewrites on r using repl, which should have been obtained from r, but is passed in for efficiency. It returns true if any changes were made to r.

Uses: caddyhttp.CleanPath, strings.Contains, strings.Cut, strings.HasPrefix, strings.ReplaceAll, strings.ToUpper, url.PathUnescape.

func (Rewrite) ServeHTTP

Uses: caddyhttp.LoggableHTTPRequest, zap.DebugLevel, zap.Object, zap.String.

Private functions

func applyQueryOps

References: strings.Contains, strings.HasPrefix, strings.Split, strings.TrimLeft.

func buildQueryString

buildQueryString takes an input query string and performs replacements on each component, returning the resulting query string. This function appends duplicate keys rather than replaces.

References: fmt.Sprintf, fmt.Stringer, strconv.Itoa, strings.Builder, strings.Index, url.QueryEscape.

func changePath

References: url.PathUnescape.

func init

References: httpcaddyfile.RegisterDirective, httpcaddyfile.RegisterHandlerDirective.

func parseCaddyfileHandlePath

parseCaddyfileHandlePath parses the handle_path directive. Syntax:

handle_path [<matcher>] {
    <directives...>
}

Only path matchers (with a / prefix) are supported as this is a shortcut for the handle directive with a strip_prefix rewrite.

References: caddyconfig.JSONModuleObject, caddyhttp.MatchPath, caddyhttp.Route, caddyhttp.Subroute, httpcaddyfile.ParseSegmentAsSubroute, json.RawMessage, strings.HasPrefix, strings.HasSuffix.

func parseCaddyfileMethod

parseCaddyfileMethod sets up a basic method rewrite handler from Caddyfile tokens. Syntax:

method [<matcher>] <method>

func parseCaddyfileRewrite

parseCaddyfileRewrite sets up a basic rewrite handler from Caddyfile tokens. Syntax:

rewrite [<matcher>] <to>

Only URI components which are given in <to> will be set in the resulting URI. See the docs for the rewrite handler for more information.

func parseCaddyfileURI

parseCaddyfileURI sets up a handler for manipulating (but not "rewriting") the URI from Caddyfile tokens. Syntax:

uri [<matcher>] strip_prefix|strip_suffix|replace|path_regexp <target> [<replacement> [<limit>]]

If strip_prefix or strip_suffix are used, then <target> will be stripped only if it is the beginning or the end, respectively, of the URI path. If replace is used, then <target> will be replaced with <replacement> across the whole URI, up to <limit> times (or unlimited if unspecified). If path_regexp is used, then regular expression replacements will be performed on the path portion of the URI (and a limit cannot be set).

References: strconv.Atoi.

func reverse

func trimPathPrefix

trimPathPrefix is like strings.TrimPrefix, but customized for advanced URI path prefix matching. The string prefix will be trimmed from the beginning of escapedPath if escapedPath starts with prefix. Rather than a naive 1:1 comparison of each byte to determine if escapedPath starts with prefix, both strings are iterated in lock-step, and if prefix has a '%' encoding at a particular position, escapedPath must also have the same encoding representation for that character. In other words, if the prefix string uses the escaped form for a character, escapedPath must literally use the same escape at that position. Otherwise, all character comparisons are performed in normalized/unescaped space.

References: strings.EqualFold, url.PathUnescape.

func do

References: strings.ReplaceAll.

func do

do performs the substring replacement on r.

References: caddyhttp.CleanPath, strings.Contains, strings.Replace.

Tests

Files: 1. Third party imports: 0. Imports from organisation: 0. Tests: 1. Benchmarks: 0.

Test functions

TestRewrite

References: http.Request, regexp.Compile.