Master Whistle: A Node‑Based Web Debugging Proxy for Developers

Overview

Whistle is a Node‑based cross‑platform web debugging proxy that intercepts HTTP(S) and WebSocket traffic, allowing developers to view, modify, or mock requests and responses. It functions similarly to Fiddler or Charles but is driven by text‑based rule configuration.

Installation & Startup

# Install globally
sudo npm i -g whistle

# Start the proxy
w2 start

After starting, open http://local.whistlejs.com/#network to access the web UI. Configure browsers or other applications to use the proxy port (default 8899).

Core Rule Syntax

Host binding – emulate OS host file entries: 192.168.0.1 mydomain.com Request replacement – redirect a request to another URL: https://m.baidu.com https://wq.jd.com/ Status code override – force a response code: https://m.baidu.com statusCode://404 Inject JavaScript into HTML pages:

https://wq.jd.com js://{test.js}
https://wq.jd.com js:///Users/myname/test/test.js

Inject CSS into HTML pages: https://wq.jd.com css://{test.css} Append or replace response body for text resources:

http://mydomain.com/style.css resAppend://{myAppend.css}
http://mydomain.com/style.css resBody://{myResBody.css}

Weinre debugging – add a remote inspection script: https://wq.jd.com weinre://debug_mypage Full protocol list is documented in the Whistle protocol reference.

Typical Workflows

Identify the target URL to modify.

Write a rule using a URI protocol (e.g., statusCode://).

Provide protocol parameters (e.g., statusCode://404).

Rules can manipulate request/response headers, query strings, user‑agent, cookies, and body content.

Advanced Usage

1. Replace Local Host File

Whistle’s host syntax mirrors the OS hosts file, enabling browser‑level host overrides without cache delays. Multiple host sets (dev, test, etc.) can be managed in the Rules UI.

2. Multi‑Device Proxy

Set a mobile device’s Wi‑Fi proxy to the host machine’s IP and port 8899 to capture mobile traffic.

Configure other desktop applications (e.g., WeChat DevTools) similarly.

All devices must be on the same LAN.

3. HTTP ↔ HTTPS Mapping

Map an online HTTPS domain to a local HTTP server for testing:

https://wq.jd.com http://localhost:9000

HTTPS interception requires installing Whistle’s generated certificate on each client device.

4. Mock Data with whistle.vase

# Install the mock plugin
npm i -g whistle.vase

Create a rule named mock_json_demo using the Mock template:

{
  "list|5": [{
    "name": "@string",
    "avatar": "http://lorempixel.com/100/100/",
    "id|+1": 10000
  }]
}

Link a URL to the mock template:

http://mock.local/data.json vase://mock_json_demo

Visiting the URL returns generated JSON. For dynamic behavior, use a script template that can read request parameters and output JSON or JSONP. Example script:

var json = merge({
  page: req.query.pi,
  total: 60
}, render('mock_json_demo', null, 'mock'));
if (req.query.callback) {
  out(header('content-type', 'application/javascript; charset=utf8'));
  out(req.query.callback + '(' + json + ')');
} else {
  out(header('content-type', 'application/json; charset=utf8'));
  out(json);
}

Configure the rule:

http://mock.local/data.json vase://json_engine_script

Access http://mock.local/data.json?callback=cb&pi=1 to see dynamic JSON or JSONP.

5. Sharing Rules

Because Whistle rules are plain text, they can be shared between development and testing teams, reducing duplication. Teams may run a dedicated mock server while Whistle handles request forwarding.

Limitations

WebSocket and image debugging support is limited, and Whistle does not provide built‑in account sharing or configuration synchronization.

References

Whistle documentation: https://avwo.github.io/whistle/

whistle.vase plugin: https://github.com/whistle-plugins/whistle.vase

Mock library: https://github.com/nuysoft/Mock/wiki