Locator

A Locator describes where inside a request or response to look for a value — the URL path, a query parameter, a header, a cookie, or a field inside the body. Locators appear in every rule that needs to find data: under rewrite.requests[], rewrite.responses[], capture.tokens.requests[], and capture.tokens.responses[].

Each locator has a scope (which part of the packet) and, for body scopes, a format (how to parse it). Different scopes accept different fields.

Scope summary

Scope	Compatible with	Key/value?	Notes
`url_path`	requests only	no	Search/match against the URL path.
`url_query`	requests only	yes	Iterate the URL query parameters.
`headers`	requests and responses	yes	Iterate HTTP headers.
`cookies`	requests and responses	yes	`Cookie` header on requests; `Set-Cookie` on responses.
`body` + `raw`	requests and responses	no	Treat the body as opaque text; regex only.
`body` + `json`	requests and responses	yes	Parse the body as JSON; `match_key` is a JSON Path.
`body` + `form`	requests only	yes	Parse the body as `application/x-www-form-urlencoded`.

A scope is key/value when it has both a key and a value (URL query parameters, headers, cookies, JSON keys, form fields). For these scopes:

match_key and match_value are required when the locator is consumed by a normal rewrite or capture rule.
They are optional when the locator is used with a rewrite whose action is create — because there is nothing to find, only something to add.

For non-key/value scopes (url_path, body raw) only match_value applies.

All match_key and match_value fields use the String Matcher syntax — glob by default, regex when prefixed with ~, with ${param} substitution and capture groups (${0} … ${N}).

URL path

Searches inside the URL path of the request.

locator: { scope: "url_path", match_value: '/test' }

Field	Type	Required	Description
`scope`	string	yes	Must equal `"url_path"`.
`match_value`	[matcher]	yes	Pattern matched against the URL path.

URL query

Iterates the URL query string. Key/value scope.

locator: { scope: "url_query", match_key: "boop", match_value: '*' }

Field	Type	Required	Description
`scope`	string	yes	Must equal `"url_query"`.
`match_key`	[matcher]	yes ¹	The query parameter name to search for.
`match_value`	[matcher]	yes ¹	Pattern matched against the parameter's value.

¹ Optional when used with rewrite.action: "create".

Headers

Iterates HTTP headers. Key/value scope. Works for requests and responses.

locator: {
  scope: "headers",
  match_key: "User-Agent",
  match_value: '~(.*\\sChrome\\/)([0-9\\.]*)(.*)'
}

Field	Type	Required	Description
`scope`	string	yes	Must equal `"headers"`.
`match_key`	[matcher]	yes ¹	The header name to search for.
`match_value`	[matcher]	yes ¹	Pattern matched against the header value.

Cookies

Iterates cookies. On requests these come from Cookie headers; on responses from Set-Cookie headers. Key/value scope.

locator: { scope: "cookies", match_key: "lab", match_value: '~([Aa]kira)' }

Field	Type	Required	Description
`scope`	string	yes	Must equal `"cookies"`.
`match_key`	[matcher]	yes ¹	The cookie name to search for.
`match_value`	[matcher]	yes ¹	Pattern matched against the cookie value.

Body

The body scope requires an additional format field describing how to parse the payload.

`format: "raw"`

Treat the body as a single string. Suitable for any content type. Not a key/value scope.

locator: {
  scope: "body",
  format: "raw",
  match_value: '~([a-zA-Z0-9.]+%40[a-zA-Z0-9.]+)'
}

Field	Type	Required	Description
`scope`	string	yes	Must equal `"body"`.
`format`	string	yes	Must equal `"raw"`.
`match_value`	[matcher]	yes	Must use regex (`~...`). Cannot be empty.

warning

With format: "raw", match_value must be a regular expression — glob patterns are rejected at load time with the error "`locator.match_value` must use regular expressions with body raw locators". The same field cannot be empty.

`format: "json"`

Parse the body as JSON. Key/value scope. Compatible with requests and responses.

locator: {
  scope: "body",
  format: "json",
  match_key: '~/email/',
  match_value: '~([a-zA-Z0-9.]+)@[a-zA-Z0-9.]+'
}

Field	Type	Required	Description
`scope`	string	yes	Must equal `"body"`.
`format`	string	yes	Must equal `"json"`.
`match_key`	[json_path]	yes ¹	A JSON Path expression selecting one or more JSON keys.
`match_value`	[matcher]	yes ¹	Pattern matched against the selected keys' string values.

`format: "form"`

Parse the body as application/x-www-form-urlencoded. Key/value scope. Requests only.

locator: { scope: "body", format: "form", match_key: 'email' }

Field	Type	Required	Description
`scope`	string	yes	Must equal `"body"`.
`format`	string	yes	Must equal `"form"`.
`match_key`	string	yes ¹	The form field name.
`match_value`	[matcher]	yes ¹	Pattern matched against the form field's value.

Capture groups

When match_value is a regular expression, its capture groups become available to the consuming rule as ${0}, ${1}, …, ${N} — for example in rewrite.value, rewrite.chained_value, cookie.value, or token.value. See String Matcher → Capture groups for details.

Scope summary​

URL path​

URL query​

Headers​

Cookies​

Body​

format: "raw"​

format: "json"​

format: "form"​

Capture groups​

See also​