Scripting

A script is a JavaScript file with up to two functions. HTTPGlass calls them for every message that matches the script’s pattern and sends on whatever you return.

// Runs before the request leaves your Mac.
function onRequest(context, url, request) {
  return request;
}

// Runs after the origin answers, before the app sees it.
function onResponse(context, url, request, response) {
  return response;
}

The hook names, argument order, and object shapes mirror Proxyman’s scripting API, so scripts written for it run here unchanged.

Adding a script

Select Scripts in the sidebar and pick a template, then give the script a pattern (the shared rule syntax) and, optionally, a method. A script with no pattern never runs, and the list says so. Two switches, Run onRequest and Run onResponse, turn either hook on or off without editing the code.

Templates

Template	What it does
Blank starter	Both hooks, with the objects you can touch spelled out in comments
Add an auth header	Attach a bearer token to every matched request
Force an error response	Answer with a `500` and a JSON body without touching the server
Edit a JSON field	Flip one value in the response
Strip tracking parameters	Remove `utm_*` query parameters before the request goes out
Log every response size	Write one line per response to the diagnostics log

The objects

url — the full URL as a string.

request

Property	Type	Notes
`method`	string	Change it to send a different method
`url`	string	Change it to rewrite the path and query (the host stays the same)
`path`	string	Path and query, read-only convenience
`headers`	object	Header name → value. Add, change, or `delete` keys
`body`	object, string, or `null`	See below
`bodyBase64`	string	Present only for binary bodies

response

Property	Type	Notes
`statusCode`	number
`headers`	object	As above
`body`	object, string, or `null`	See below
`bodyBase64`	string	Present only for binary bodies

context — context.log(text) writes a line to HTTPGlass’s diagnostics log, diag.log in ~/Library/Application Support/HTTPGlass. console.log, info, warn, error, and debug go to the same place. While you’re testing a script in the editor, the lines show in the Test pane.

Bodies

A JSON body (Content-Type: application/json or similar) arrives already parsed. Change fields on the object and HTTPGlass re-serialises it, updating Content-Length for you.
A text body arrives as a string.
A binary body arrives as body: null with the bytes in bodyBase64. Set bodyBase64 to replace it.
Assigning a plain object to body on a response that wasn’t JSON works; set headers["Content-Type"] too so the app parses it.

Reading a JSON body without changing it does not count as a change: HTTPGlass compares the result against what an untouched round trip would produce, not against the original bytes, so key reordering from re-serialisation never triggers a rewrite.

Return values

Return the request or response object to apply your changes. Return null (or nothing) to leave the message exactly as it was.

Testing a script

The editor has a Test pane. Enter a sample URL and body, click Run script, and see the resulting message plus every context.log line and any error, before the script touches live traffic. Syntax errors show as you type.

Limits and behaviour

Timeout — a hook that runs for more than two seconds is abandoned. The message passes through unchanged and the JavaScript engine is rebuilt before the next call.
Errors — an exception in a hook is logged to the diagnostics log with the script’s name; the message continues unchanged.
Order — several matching scripts run in list order, each one receiving the previous one’s output. Scripts run after Rewrite rules and before breakpoints.
Compression — when a script declares onResponse, HTTPGlass asks the server for an uncompressed response on matching requests so the body is editable.
Memory — the JavaScript engine is only loaded while at least one script is enabled, and released when none are. It is never loaded otherwise.
No network from scripts — there is no fetch; a script edits the message in front of it and nothing else.