Whistle Network Debugging Proxy

Whistle is a cross-platform network capturing and debugging tool based on Node.js. It is designed to intercept and modify network traffic across various protocols and proxy modes.

Key Capabilities:

• Protocol Support: Captures and modifies HTTP, HTTPS, HTTP/2, WebSocket, and TCP traffic.
• Proxy Modes: Supports HTTP, HTTPS, Socks, and reverse proxying.
• Built-in Debugging Tools:
  • Weinre: Remote DOM inspection.
  • Console: Viewing console logs.
  • Composer: Request replay and editing.
• Extensibility: Supports plugins to extend rules and UI functionality, and can be used as an NPM module.
• Cross-Platform: Works on macOS, Windows, Linux (Ubuntu/Fedora), and headless Linux servers.

The file protocol maps requests to the local file system, returning the content of local files as responses. This is useful for setting up local development servers, debugging local front-end files, mocking APIs with JSON, or serving static resources.

Key Difference from resBody:

• file protocol: Requests are not sent to the backend server. Whistle reads the local file and returns it immediately (200 OK).
• resBody protocol: The request is sent to the backend server, and the server's response body is then replaced with your content.

Basic Syntax:

pattern file://(value) [lineProps...] [filters...]

# Map a domain to a local directory
www.example.com/path file:///Users/username/projects/my-site

# Windows system path
www.example.com/path file://D:\projects\my-site

The auth protocol is used to automatically add the Authorization header for HTTP Basic Authentication to matching requests. It simplifies the process by handling the Base64 encoding of credentials for you.

Note: This protocol only supports Basic Authentication. For other methods like Bearer tokens or OAuth, use the reqHeaders protocol to set the Authorization header manually.

https://api.example.com/ auth://admin:secret

Every Whistle rule follows a consistent basic syntax structure used to modify requests and responses. A rule consists of four parts:

1. pattern (Required): An expression that matches the request URL.
2. operation (Required): An instruction in the format protocol://value (e.g., proxy://127.0.0.1:8080).
3. lineProps (Optional): Additional configurations that apply only to the current rule.
4. filters (Optional): Filtering conditions used to precisely control when the rule takes effect.

Basic syntax:

pattern operation [lineProps...] [filters...]

Use Throttle protocols to simulate network latency or limit bandwidth. Available protocols include:

• reqDelay: Delay requests.
• resDelay: Delay responses.
• reqSpeed: Limit request speed.
• resSpeed: Limit response speed.

The reqRules protocol allows you to apply multiple rules to a single matching request in a batch. This is useful for handling complex scenarios where a request needs to undergo several transformations or operations sequentially.

Syntax

pattern reqRules://value [filters...]

Parameters

• pattern: An expression that matches the request URL.
• value: The content of the rule. Supported types include:
  • Directory or file paths
  • Remote URLs
  • Inline/embedded values
• filters (optional): Filters to refine the match based on request URL, method, headers, body, or response status code and headers.

* file://(<div>hello<div>)
* resAppend://(test)

www.example.com/path reqRules://{test.txt} reqRules://{test2.txt}

The xtpl rule is a fall-through version of the tpl rule. It allows you to serve local file contents as a template, but unlike the standard tpl rule, it does not fail if the local file is missing.

• If the file exists: It returns the local file contents (identical to tpl).
• If the file does not exist: It allows the normal network request to proceed instead of returning a 404 error.

pattern xtpl://value [filters...]

Whistle provides several advanced rule and configuration features (available since v2.9):

Rule Enhancements

• Grouping and Visibility: Rules support grouping and the ability to view Enabled Rules.
• Matching Probability: You can set the probability of a rule matching using the syntax includeFilter://chance:0.5.
• Deletion Protocol: Use the delete:// protocol to delete request parameters, cookies, and other data.

Configuration

• Default Config: Support loading default configurations via the ~/.whistlerc file.
• Embedded Values: Embedded values have independent scopes for Rules, Plugins, and Header Rules.

Whistle supports various network and proxy configurations (available since v2.9):

• Localhost Compatibility: localhostCompatible mode is enabled by default.
• Protocols: Supports https-proxy and internal-http-proxy protocols.
• Proxy Configuration: proxy and pac configurations can use lineProps://proxyHostOnly to ensure the proxy is only effective when a specific host is configured.
• IPv6: Support for IPv6-only networks.
• SOCKS: Support for SOCKS proxy and custom DNS servers.

It is important to choose the correct protocol based on whether you want to preserve the original response:

• resPrepend: Adds content to the beginning of the response. The original content remains intact.
• resBody: Replaces the entire response content. The original content is discarded.

The xsocks rule is a pass-through version of the socks rule. It is designed to provide fallback behavior when a proxy connection fails.

• Success Case: If the connection to the target proxy is established successfully, xsocks behaves identically to the standard socks rule.
• Failure Case: If the connection to the target proxy fails, xsocks ignores the matching rule and allows the normal network request to proceed. In contrast, the standard socks rule would abort the request upon failure.

# Example pattern matching
example.com xsocks://127.0.0.1:1080