Script API - httpmon

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

Field	Type	Required	Description
`name`	string	yes	Display name shown in the scripts manager
`match`	string[]	yes	URL patterns to match (glob with `*` wildcards)
`enabled`	bool	no	Defaults to `true` if omitted

onRequest(ctx)

Runs before the request is sent upstream.

Property	Type	Access	Description
`ctx.method`	string	read/write	HTTP method
`ctx.url`	string	read/write	Full URL
`ctx.headers`	object	read/write	Request headers
`ctx.body`	string	read/write	Request body
`ctx.blocked`	bool	write	Set to `true` to block the request

onResponse(ctx)

Runs before the response reaches the client.

Property	Type	Access	Description
`ctx.status`	int	read/write	Status code
`ctx.headers`	object	read/write	Response headers
`ctx.body`	string	read/write	Response body
`ctx.respondWith()`	function		Replace the response entirely
`ctx.breakpoint()`	function		Pause the response for interactive editing
`ctx.readFile(path)`	function		Read a file relative to the script directory

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.

Option	Type	Description
`status`	int	Response status code (defaults to `200`)
`body`	string	Response body
`headers`	object	Response headers as key-value pairs
`file`	string	Path 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.

Pattern	Matches
`://api.example.com/`	Any request to api.example.com
`://.example.com/api/*`	Any subdomain of example.com under /api/
`:///*`	All URLs

​Script file format

​Frontmatter fields

​onRequest(ctx)

​onResponse(ctx)

​ctx.respondWith(options)

​ctx.breakpoint()

​ctx.readFile(path)

​URL match patterns