https-proxy

The https-proxy directive is used to forward matching requests through a specified HTTPS proxy server.

Rule Syntax

pattern https-proxy://ipOrDomain[:port] [filters...]

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

Parameters	Description	Detailed Documentation
pattern	An expression to match the request URL	Match Pattern Documentation
value	IP + optional port or domain name + optional port ⚠️ Loading data from files/remote URLs is not supported	Operation Instruction Documentation
filters	Optional filters. Supports matching: • Request URL/Method/Headers/Content • Response Status Code/Headers	Filters Documentation

Configuration Example

# Proxy requests to an HTTPS proxy: `127.0.0.1:443`
www.example.com/path https-proxy://127.0.0.1 # Default port 443

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

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

Advanced Usage

By default, the upstream proxy resolves the requested domain name. However, in some scenarios, you may want to force the proxy to access a specific target IP directly (skipping DNS resolution), for example:

• Bypassing DNS poisoning
• Directly accessing a specific backend IP
• Testing services in different environments

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

# Enabling via directives
www.example.com https-proxy://127.0.0.1:8080 1.1.1.1 enable://proxyHost
www.example.com https-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

Notes

The https-proxy 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 https-proxy://127.0.0.1:1234

When a request is made to https://www.example.com/api/path, Whistle processes it and changes the URL to https://www.example.com/path (this becomes the Final URL). Although the intention is to https-proxy this request to 127.0.0.1:1234, the https-proxy rule only matches the original domain www.example.com/api before substitution. Since the converted Final URL is now www.example.com/path, this rule will not be triggered.

To ensure the rule also applies to the substituted request, you can break it into two separate rules:

www.example.com/api www.example.com  
www.example.com https-proxy://127.0.0.1:1234

This way, the original request is first rewritten by the first rule, generating a new Final URL. Then, the second https-proxy rule matches this new URL and successfully proxies the request to 127.0.0.1:1234.