Skip to main content
Scripts are JavaScript files stored in ~/.httpmon/scripts/. Each script has YAML frontmatter inside JS comments and exports onRequest and/or onResponse hooks.

​
Script file format

// ---
// name: Add Auth Header
// match:
//   - "*://api.example.com/*"
// enabled: true
// ---

function onRequest(ctx) {
  ctx.headers["Authorization"] = "Bearer my-token";
}

function onResponse(ctx) {
  // modify response here
}
The frontmatter is delimited by // --- lines. Each YAML line is prefixed with // .

​
Frontmatter fields

FieldTypeRequiredDescription
namestringyesDisplay name shown in the scripts manager
matchstring[]yesURL patterns to match (glob with * wildcards)
enabledboolnoDefaults to true if omitted

​
onRequest(ctx)

Runs before the request is sent upstream.
PropertyTypeAccessDescription
ctx.methodstringread/writeHTTP method
ctx.urlstringread/writeFull URL
ctx.headersobjectread/writeRequest headers
ctx.bodystringreadRequest body
ctx.blockedboolwriteSet to true to block the request

​
onResponse(ctx)

Runs before the response reaches the client.
PropertyTypeAccessDescription
ctx.statusintread/writeStatus code
ctx.headersobjectread/writeResponse headers
ctx.bodystringreadResponse body

​
ctx.respondWith(options)

Short-circuits the normal proxy flow and returns a synthetic response. Available in both onRequest and onResponse. In onRequest, calling respondWith stops script execution immediately. The request is never sent upstream. In onResponse, execution continues after the call.
OptionTypeDescription
statusintResponse status code (defaults to 200)
bodystringResponse body
headersobjectResponse headers as key-value pairs
filestringPath to a local file to serve as the response body
When you use file, the content-type is auto-detected from the file extension. The file and body options are mutually exclusive. 
function onRequest(ctx) {
  ctx.respondWith({
    status: 200,
    body: '{"mocked": true}',
    headers: {"Content-Type": "application/json"}
  });
}

function onRequest(ctx) {
  ctx.respondWith({file: "./mock.json"});
}

​
ctx.breakpoint()

Pauses the flow for interactive editing in the TUI. You can inspect and modify headers and body before the flow continues. 
function onRequest(ctx) {
  ctx.breakpoint();
}

​
ctx.readFile(path)

Reads a file from disk and returns its contents as a string. Returns null if the file does not exist. Paths are resolved relative to the script’s directory. 
function onRequest(ctx) {
  var data = ctx.readFile("./fixtures/response.json");
  ctx.respondWith({body: data});
}

​
URL match patterns

Match patterns use glob syntax with * wildcards. The format is scheme://host/path.
  • * in the scheme position matches any scheme (http or https).
  • * in the host matches a single domain label (*.example.com matches api.example.com but not a.b.example.com).
  • * in the path matches any substring including slashes.
Matching is case-insensitive.
PatternMatches
*://api.example.com/*Any request to api.example.com
*://*.example.com/api/*Any subdomain of example.com under /api/
*://*/*All URLs