Extension reference
To build an extension step by step, start with Writing extensions.
The folder
Section titled “The folder”request-tools/ extension.json the manifest request-tools.exe the program for Windows request-tools the program for macOS extension.log made by zhttp: what the program wrote to its error outputExtensions go in:
| System | Folder |
|---|---|
| Windows | %AppData%\zhttp\extensions |
| macOS | ~/Library/Application Support/zhttp/extensions |
Settings › Extensions › Open folder opens it. Each extension has its own folder, named after its id. zhttp reads the folders when it starts, and again each time you switch an extension on or off. It empties extension.log each time the extension starts.
extension.json
Section titled “extension.json”| Field | Needed | |
|---|---|---|
id |
Yes | The name of the extension’s folder |
name |
Yes | Its name in Settings › Extensions |
version |
No | Shown beside the name |
description |
No | A line or two under the name, saying what it does |
run |
Yes | The program to start, relative to the folder, for windows, macos or linux. One is needed for the system zhttp runs on |
viewers |
No | Tabs |
commands |
No | Right-click items |
hooks |
No | Rules that change traffic |
watch |
No | URLs to watch |
If zhttp can’t use an extension.json, Settings › Extensions shows why, and the extension doesn’t run.
viewers
Section titled “viewers”Each viewer is a tab on the requests or responses it matches, after Raw.
| Field | |
|---|---|
name |
What the program knows it by. No two viewers can share one |
title |
The tab’s name |
on |
request or response |
url |
The URLs whose requests or responses get the tab |
commands
Section titled “commands”Each command is an item in a request’s right-click menu, under Extensions.
| Field | |
|---|---|
name |
What the program knows it by. No two commands can share one |
title |
The item’s name |
Each hook is a rule the user can add from the Breakpoints panel’s +. It changes the requests or responses the rule matches before they go on.
| Field | |
|---|---|
name |
What the program knows it by. No two hooks can share one |
title |
The rule’s name in + and in the rule list |
on |
request or response |
url |
The URL a new rule starts with. The user can change it |
| Field | |
|---|---|
url |
zhttp tells the extension about each exchange whose URL this matches, once its response has arrived in full |
URL patterns
Section titled “URL patterns”A pattern matches the whole URL, query string included, ignoring case. * stands for any run of characters.
| Pattern | Matches |
|---|---|
* |
Every URL |
*/api/* |
Every URL with /api/ in it |
https://example.com/* |
Everything on example.com over HTTPS |
*.json |
URLs that end in .json, with no query string |
The C# library
Section titled “The C# library”Add Zhttp.Extensions from NuGet with dotnet add package Zhttp.Extensions. It works with Native AOT.
Extension
Section titled “Extension”await new Extension() .Viewer("base64", async (shown, capture) => View.Plain("…")) .RunAsync();| Method | Handler | Runs when |
|---|---|---|
Viewer(name, handler) |
(Shown, Capture) → Task<View> |
Someone opens the viewer’s tab, or clicks ↻ in it |
Command(name, handler) |
(Picked, Capture) → Task<CommandResult> |
Someone picks the command from the right-click menu |
Hook(name, handler) |
(Hooked, Capture) → Task<Message> |
A request or response matches one of the hook’s rules |
Watch(handler) |
(Watched, Capture) → Task |
A response arrives in full on a URL in watch |
RunAsync() |
Call it last. It answers zhttp until zhttp stops the extension |
Each name matches one in extension.json. zhttp can run several handlers at once, on different threads, so lock anything they share.
What a handler is given
Section titled “What a handler is given”| Type | Properties |
|---|---|
Shown |
Session, Id: the exchange the tab is showing |
Picked |
Session, Ids: the exchanges the user selected |
Hooked |
Session, Id, and Message: the request or response to change |
Watched |
Session, Id, Method, Url, Status |
Session is the number of the session the exchange is in. Id names the exchange as "<connection>.<stream>", such as "12.3", the same ID the AI agent tools use.
What a handler returns
Section titled “What a handler returns”| Handler | Returns |
|---|---|
| Viewer | View.Plain(text) for text, or View.Json(json) for JSON. zhttp colours JSON but doesn’t reformat it |
| Command | new CommandResult(Message, Copy). zhttp shows Message as a notice and puts Copy on the clipboard. Either can be left out |
| Hook | The Message zhttp sends on in place of the one it gave you. Change the one you’re given and return it, or return a new one |
| Watch | Nothing |
Message
Section titled “Message”A request or a response.
| Member | |
|---|---|
Method, Url |
A request’s method and URL |
Status |
A response’s status code |
Headers |
A List<Header> in the order they travelled, without HTTP/2’s pseudo-headers such as :path. new Header(name, value) makes one |
Body |
The body as a byte[], with its Content-Encoding (gzip, br…) removed |
Header(name) |
The value of the first header called name, ignoring case, or null |
When a hook returns a message, zhttp compresses the body again as the message’s Content-Encoding header says, and corrects Content-Length. A request needs a method and a URL. A response needs a status from 200 to 599. Header names can’t contain spaces or :, and values can’t contain line breaks.
Capture
Section titled “Capture”Every handler gets a Capture as its second argument, for reading and marking the traffic zhttp captured. When a method fails, it throws a ZhttpException with the reason.
| Method | |
|---|---|
GetAsync(session, id) |
The Exchange: its Request and its Response, with bodies in full. Response is null until it arrives. Fails while a body is still arriving, or when it wasn’t captured in full |
FindAsync(session, terms, scopes, before, limit) |
The exchanges that hold every term, newest first, as ExchangeSummary: Id, Method, Url, Status, MediaType, Started |
MarkAsync(session, ids, comment, highlight) |
Leaves a comment, a highlight or both on exchanges, as the user does |
FindAsync looks for the terms in the parts scopes turns on, such as new Scopes(Url: true, ResponseBody: true). The others are RequestHeaders, RequestBody and ResponseHeaders. With no terms, it lists every exchange. before keeps only those that started before that exchange. limit is 1 to 1000, or 0 for 100.
MarkAsync’s highlight is red, orange, yellow, green, blue or purple, or none to take it off. A comment of only spaces takes the comment off. null leaves either as it is.
Time limits and failures
Section titled “Time limits and failures”| What | Time limit | When it fails or runs out of time |
|---|---|---|
| Starting | 10 seconds | Settings › Extensions shows why under its name |
| A hook | 5 seconds | The request is dropped, or the response reaches the app as a 502 that says why |
| A viewer | 30 seconds | The tab shows the error |
| A command | 30 seconds | A notice shows the error |
| A watcher | None | The error goes to extension.log |
| Stopping | 2 seconds | zhttp ends the program |
A rule whose extension is off, removed or not running fails the same way a hook does. See Rules.
The protocol
Section titled “The protocol”The C# library handles the protocol for you. You only need it to write an extension in another language, and Extension examples has one in Go and one in Rust.
zhttp starts the program in its folder and talks to it in JSON-RPC 2.0 over its standard input and output, one message a line in UTF-8. A line carries a whole body, so it can be megabytes long. Read lines without a length limit. Standard output carries messages and nothing else, and standard error goes to extension.log.
Calls go both ways and can overlap. zhttp can send a call before you’ve answered the last one, and you can call zhttp while you handle one. Match each answer to its call by id.
Here is a conversation, where → is zhttp writing to the program and ← is the program writing to zhttp:
→ {"jsonrpc":"2.0","id":1,"method":"hello","params":{"protocol":1}}← {"jsonrpc":"2.0","id":1,"result":{}}→ {"jsonrpc":"2.0","id":2,"method":"command","params":{"command":"copy-urls","session":1,"ids":["7.1"]}}← {"jsonrpc":"2.0","id":1,"method":"get","params":{"session":1,"id":"7.1"}}→ {"jsonrpc":"2.0","id":1,"result":{"request":{"method":"GET","url":"https://api.example.com/a","headers":[["accept","*/*"]],"body":""},"response":{"status":200,"headers":[["content-type","application/json"]],"body":"eyJvayI6dHJ1ZX0="}}}← {"jsonrpc":"2.0","id":2,"result":{"message":"Copied 1 URLs","copy":"https://api.example.com/a\n"}}→ {"jsonrpc":"2.0","method":"shutdown","params":{}}Messages
Section titled “Messages”A request or a response is:
{ "method": "POST", "url": "https://api.example.com/a", "headers": [["content-type", "application/json"]], "body": "eyJvayI6dHJ1ZX0=" }headers are [name, value] pairs in the order they travelled, without HTTP/2’s pseudo-headers. body is base64, with its Content-Encoding removed. A request has method and url. A response has status instead.
What zhttp calls
Section titled “What zhttp calls”| Method | Params | Answer with |
|---|---|---|
hello |
{ "protocol": 1 } |
{}. zhttp sends it first |
view |
{ "viewer", "session", "id" } |
{ "format", "text" }, where format is "text" or "json" |
command |
{ "command", "session", "ids" } |
{ "message", "copy" }. Both are optional |
hook |
{ "hook", "session", "id", "message" } |
{ "message" }: the message to send on |
watched |
{ "session", "id", "method", "url", "status" } |
Nothing. It’s a notification, with no id |
shutdown |
{} |
Nothing. Exit within 2 seconds |
To refuse a call, answer with a JSON-RPC error. zhttp shows its message to the user.
What the program can call
Section titled “What the program can call”| Method | Params | zhttp answers |
|---|---|---|
get |
{ "session", "id" } |
{ "request", "response" }. response is null until it arrives |
find |
{ "session", "terms", "scopes", "before", "limit" } |
{ "exchanges": [{ "id", "method", "url", "status", "media_type", "started" }] }, newest first |
mark |
{ "session", "ids", "comment", "highlight" } |
{} |
scopes is an object with any of url, request_headers, request_body, response_headers and response_body set to true. before, limit, comment and highlight can be left out, and work as in Capture.