ContextQMD
Back to Whistle

proxy (http-proxy)

docs/en/docs/rules/proxy.md

2.10.43.4 KB
Original Source

proxy (http-proxy)

The proxy (or http-proxy) directive forwards matching requests through a specified HTTP proxy server. These two directives have identical functionality and can be used interchangeably.

Rule Syntax

txt
pattern proxy://ipOrDomain[:port] [filters...]
# Equivalent:
pattern http-proxy://ipOrDomain[:port] [filters...]

port is optional. If left blank, the default port 80 will be used.

ParametersDescriptionDetailed Documentation
patternAn expression to match the request URLMatch Pattern Documentation
valueIP + optional port or domain name + optional port
⚠️ Loading data from files/remote URLs is not supportedOperation Instruction Documentation
filtersOptional filters. Supports matching:
• Request URL/Method/Headers/Content
• Response Status Code/HeadersFilter Documentation

Configuration Example

txt
# Proxy requests to the HTTP proxy: `127.0.0.1:80`
www.example.com/path proxy://127.0.0.1 # Default port 80

# Proxy all requests for the current domain to the HTTP proxy: `127.0.0.1:8080`
www.example.com proxy://127.0.0.1:8080

# You can also use a domain name.
www.example.com/path proxy://test.proxy.com # Default port 80
www.example.com proxy://test.proxy.com:8080

Advanced Usage

After proxying a request to the upstream proxy, by default the upstream proxy will use DNS to obtain the server IP address based on the requested domain name before continuing the request. If you want the upstream proxy to continue the request based on a specific IP address and port, you can do this:

txt
# Using query parameters
www.example.com proxy://127.0.0.1:8080?host=1.1.1.1
www.example.com proxy://127.0.0.1:8080?host=1.1.1.1:8080

# Enable via directive
www.example.com proxy://127.0.0.1:8080 1.1.1.1 enable://proxyHost
www.example.com proxy://127.0.0.1:8080 1.1.1.1:8080 enable://proxyHost

1.1.1.1 is equivalent to host://1.1.1.1

Matching precedence with host

Default behavior

When a request matches both host and proxy rules:

  • Only the host rule takes effect
  • The proxy rule is automatically ignored

Modify Priority

Configuration MethodSyntaxEffect
Prioritize proxyenable://proxyFirst or lineProps://proxyFirstOnly proxy takes effect (overrides host)
Both take effectenable://proxyHost or lineProps://proxyHostBoth proxy and host take effect

Usage Recommendations

  • Use the default behavior in most scenarios
  • Use proxyFirst only when special proxy logic is required
  • Use proxyHost when dual matching is required

Notes

The host protocol only applies to the substituted URL (i.e., the Final URL shown in the Overview). If the Final URL is empty, it will take effect on the original request URL.

For example, with the rule:

www.example.com/api www.example.com 127.0.0.1:1234

A request to https://www.example.com/api/path will be processed by Whistle, and the Final URL becomes https://www.example.com/path. As a result, it will not match 127.0.0.1:1234.

If you want to match the substituted request, you can modify the rules as follows:

www.example.com/api www.example.com  
www.example.com 127.0.0.1:1234