Writing extensions
An extension is a program that zhttp starts and talks to. Here you build one in C#, called Request tools, in four parts:
| Part | What it adds |
|---|---|
| A tab | A Base64 tab that shows a request’s body decoded from base64 |
| A right-click item | Copy URLs, which copies the URLs of the requests you pick |
| A rule | A rule that adds an X-Debug: 1 header to requests |
| A watcher | Highlights each response with a 5xx status in red |
The extension works after each part, so you can stop at any point. Extension examples has the same extension in Go and Rust, and the extension reference lists every field and method.
What you need
Section titled “What you need”- The .NET 10 SDK.
- The tools .NET uses to build a native program. On Windows, Visual Studio or its Build Tools with the Desktop development with C++ workload. On macOS, run
xcode-select --install.
Set up the project
Section titled “Set up the project”-
Make the project and add the
Zhttp.Extensionslibrary:dotnet new console -n request-toolscd request-toolsdotnet add package Zhttp.Extensions -
Replace
request-tools.csprojwith this:request-tools.csproj <Project Sdk="Microsoft.NET.Sdk"><PropertyGroup><OutputType>Exe</OutputType><TargetFramework>net10.0</TargetFramework><ImplicitUsings>enable</ImplicitUsings><Nullable>enable</Nullable><PublishAot>true</PublishAot></PropertyGroup><ItemGroup><PackageReference Include="Zhttp.Extensions" Version="1.0.0" /><None Include="extension.json" CopyToPublishDirectory="PreserveNewest" /></ItemGroup></Project>PublishAotmakesdotnet publishbuild one program that runs without .NET installed. TheNoneline copiesextension.jsonnext to it. -
Make a file called
extension.jsonin the same folder:extension.json {"id": "request-tools","name": "Request tools","version": "1.0.0","description": "Decodes base64 bodies, copies URLs, tags requests and flags server errors.","run": { "windows": "request-tools.exe", "macos": "request-tools" }}This file is the manifest. Settings › Extensions shows its
name,versionanddescription. Theidmust match the name of the folder you install the extension in, andrunnames the program zhttp starts on each system.
1. A tab
Section titled “1. A tab”In extension.json, a tab is a viewer. Add one:
{ "id": "request-tools", "name": "Request tools", "version": "1.0.0", "description": "Decodes base64 bodies, copies URLs, tags requests and flags server errors.", "run": { "windows": "request-tools.exe", "macos": "request-tools" }, "viewers": [ { "name": "base64", "title": "Base64", "on": "request", "url": "*" } ]}nameis what your code calls it.titleis the tab’s name in zhttp.onputs the tab on therequestor theresponse.urlpicks the requests that get the tab.*stands for any run of characters, so*is every request and*/api/*is those with/api/in their URL.
Replace Program.cs with:
using System.Text;using Zhttp.Extensions;
await new Extension() .Viewer("base64", async (shown, capture) => { var exchange = await capture.GetAsync(shown.Session, shown.Id); var text = Encoding.UTF8.GetString(exchange.Request.Body); var decoded = Convert.FromBase64String(text); return View.Plain(Encoding.UTF8.GetString(decoded)); }) .RunAsync();.Viewer("base64", …) runs when someone opens the tab. zhttp passes it the request’s session and ID, and capture.GetAsync reads the request and its response. The tab shows whatever the handler returns, either View.Plain for text or View.Json for JSON.
Install it
Section titled “Install it”-
Publish the extension straight into zhttp’s extensions folder:
Windows (PowerShell) dotnet publish -c Release -r win-x64 -o "$env:APPDATA\zhttp\extensions\request-tools"macOS dotnet publish -c Release -r osx-arm64 -o "$HOME/Library/Application Support/zhttp/extensions/request-tools"On a Windows PC with an Arm chip use
win-arm64, and on an Intel Mac useosx-x64. -
Restart zhttp so it finds the new folder.
-
Open Settings › Extensions and switch Request tools on.
-
Pick a request whose body is base64 and open its Base64 tab.
If the body isn’t base64, the tab shows the error, The input is not a valid Base-64 string…. Click ↻ in the tab to read the request again.
Change it and try again
Section titled “Change it and try again”zhttp keeps the program running while the extension is on, and Windows won’t let you replace a program that’s running. After each change:
- Switch the extension off in Settings › Extensions.
- Run the same
dotnet publishcommand. - Switch it on.
zhttp reads extension.json again when you switch the extension on, so new tabs, items and rules show up without a restart.
2. A right-click item
Section titled “2. A right-click item”Right-click items are commands. Add one to extension.json:
{ "id": "request-tools", "name": "Request tools", "version": "1.0.0", "description": "Decodes base64 bodies, copies URLs, tags requests and flags server errors.", "run": { "windows": "request-tools.exe", "macos": "request-tools" }, "viewers": [ { "name": "base64", "title": "Base64", "on": "request", "url": "*" } ], "commands": [ { "name": "copy-urls", "title": "Copy URLs" } ]}In Program.cs, add this before .RunAsync():
.Command("copy-urls", async (picked, capture) => { var urls = new StringBuilder(); foreach (var id in picked.Ids) { var exchange = await capture.GetAsync(picked.Session, id); urls.AppendLine(exchange.Request.Url); } return new CommandResult(Message: $"Copied {picked.Ids.Count} URLs", Copy: urls.ToString()); })picked.Ids holds the requests the user selected. zhttp puts Copy on the clipboard and shows Message as a notice. Leave out either one if you don’t need it.
Rebuild as in Change it and try again. Then select a few requests and right-click › Extensions › Copy URLs.
3. A rule
Section titled “3. A rule”A hook changes requests or responses on their way through. Add one to extension.json:
{ "id": "request-tools", "name": "Request tools", "version": "1.0.0", "description": "Decodes base64 bodies, copies URLs, tags requests and flags server errors.", "run": { "windows": "request-tools.exe", "macos": "request-tools" }, "viewers": [ { "name": "base64", "title": "Base64", "on": "request", "url": "*" } ], "commands": [ { "name": "copy-urls", "title": "Copy URLs" } ], "hooks": [ { "name": "debug-header", "title": "Add X-Debug header", "on": "request", "url": "*" } ]}A hook runs only on requests matched by a rule the user adds for it. url is the URL a new rule starts with, and the user can change it.
In Program.cs, add this before .RunAsync():
.Hook("debug-header", (hooked, capture) => { hooked.Message.Headers.Add(new Header("X-Debug", "1")); return Task.FromResult(hooked.Message); })hooked.Message is the request, with its method, URL, body, and headers in the order they were sent. zhttp sends on whatever you return. You get the body uncompressed, and zhttp compresses it again and corrects Content-Length.
Rebuild, then open the Breakpoints panel, click + and pick Add X-Debug header. Requests that match the rule’s URL now go out with X-Debug: 1.
A hook has 5 seconds. If it throws or runs out of time, zhttp drops the request. On a response hook, the app gets a 502 that says what went wrong.
4. A watcher
Section titled “4. A watcher”A watcher hears about every response that finishes on a URL it watches. It needs no rule. Add watch to extension.json:
{ "id": "request-tools", "name": "Request tools", "version": "1.0.0", "description": "Decodes base64 bodies, copies URLs, tags requests and flags server errors.", "run": { "windows": "request-tools.exe", "macos": "request-tools" }, "viewers": [ { "name": "base64", "title": "Base64", "on": "request", "url": "*" } ], "commands": [ { "name": "copy-urls", "title": "Copy URLs" } ], "hooks": [ { "name": "debug-header", "title": "Add X-Debug header", "on": "request", "url": "*" } ], "watch": [ { "url": "*" } ]}In Program.cs, add this before .RunAsync():
.Watch(async (watched, capture) => { if (watched.Status >= 500) { await capture.MarkAsync(watched.Session, [watched.Id], comment: "Server error", highlight: "red"); } })MarkAsync leaves a comment and a highlight on a request, as you would from its right-click menu. Rebuild, and each response with a 5xx status turns red with the comment Server error.
When something goes wrong
Section titled “When something goes wrong”-
Settings › Extensions shows the reason under the extension’s name, such as a mistake in
extension.json, a missing program, or a program that stopped. -
If a tab or a right-click item throws, the user sees the exception’s message. If a watcher throws, the message goes to
extension.login the extension’s folder. -
Console.WriteLinewrites toextension.logtoo. zhttp empties the file each time the extension starts. To log each response the watcher hears about, add this to it:Console.WriteLine($"{watched.Status} {watched.Url}");
Don’t write to standard output any other way, because zhttp reads its messages from there.
The whole extension
Section titled “The whole extension”{ "id": "request-tools", "name": "Request tools", "version": "1.0.0", "description": "Decodes base64 bodies, copies URLs, tags requests and flags server errors.", "run": { "windows": "request-tools.exe", "macos": "request-tools" }, "viewers": [ { "name": "base64", "title": "Base64", "on": "request", "url": "*" } ], "commands": [ { "name": "copy-urls", "title": "Copy URLs" } ], "hooks": [ { "name": "debug-header", "title": "Add X-Debug header", "on": "request", "url": "*" } ], "watch": [ { "url": "*" } ]}using System.Text;using Zhttp.Extensions;
await new Extension() .Viewer("base64", async (shown, capture) => { var exchange = await capture.GetAsync(shown.Session, shown.Id); var text = Encoding.UTF8.GetString(exchange.Request.Body); var decoded = Convert.FromBase64String(text); return View.Plain(Encoding.UTF8.GetString(decoded)); }) .Command("copy-urls", async (picked, capture) => { var urls = new StringBuilder(); foreach (var id in picked.Ids) { var exchange = await capture.GetAsync(picked.Session, id); urls.AppendLine(exchange.Request.Url); } return new CommandResult(Message: $"Copied {picked.Ids.Count} URLs", Copy: urls.ToString()); }) .Hook("debug-header", (hooked, capture) => { hooked.Message.Headers.Add(new Header("X-Debug", "1")); return Task.FromResult(hooked.Message); }) .Watch(async (watched, capture) => { if (watched.Status >= 500) { await capture.MarkAsync(watched.Session, [watched.Id], comment: "Server error", highlight: "red"); } }) .RunAsync();Share it
Section titled “Share it”To share an extension, you share its folder, with extension.json and a program for each system. Native AOT only builds for the system it runs on, so build the Windows program on Windows and the macOS program on a Mac.
-
Publish for each system into the same folder.
win-x64runs on every Windows PC, Arm ones included.osx-arm64runs on Macs with Apple silicon. To cover Intel Macs too, publishosx-arm64andosx-x64into two folders,arm64andx64, and join them into one program:lipo -create -output request-tools arm64/request-tools x64/request-tools -
Leave out the
.pdbfiles. zhttp doesn’t need them. -
Zip the folder and share it. People add it as in Install one.
macOS blocks a program downloaded from the internet unless Apple has notarized it, so sign and notarize the macOS program before you share it.