Skip to content

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.

  1. Make the project and add the Zhttp.Extensions library:

    dotnet new console -n request-tools
    cd request-tools
    dotnet add package Zhttp.Extensions
  2. Replace request-tools.csproj with 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>

    PublishAot makes dotnet publish build one program that runs without .NET installed. The None line copies extension.json next to it.

  3. Make a file called extension.json in 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, version and description. The id must match the name of the folder you install the extension in, and run names the program zhttp starts on each system.

In extension.json, a tab is a viewer. Add one:

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": "*" }
]
}
  • name is what your code calls it.
  • title is the tab’s name in zhttp.
  • on puts the tab on the request or the response.
  • url picks 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:

Program.cs
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.

  1. 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 use osx-x64.

  2. Restart zhttp so it finds the new folder.

  3. Open Settings › Extensions and switch Request tools on.

  4. 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.

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:

  1. Switch the extension off in Settings › Extensions.
  2. Run the same dotnet publish command.
  3. 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.

Right-click items are commands. Add one to extension.json:

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.

A hook changes requests or responses on their way through. Add one to extension.json:

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.

A watcher hears about every response that finishes on a URL it watches. It needs no rule. Add watch to extension.json:

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.

  • 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.log in the extension’s folder.

  • Console.WriteLine writes to extension.log too. 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.

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": "*" }
]
}
Program.cs
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();

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.

  1. Publish for each system into the same folder. win-x64 runs on every Windows PC, Arm ones included. osx-arm64 runs on Macs with Apple silicon. To cover Intel Macs too, publish osx-arm64 and osx-x64 into two folders, arm64 and x64, and join them into one program:

    lipo -create -output request-tools arm64/request-tools x64/request-tools
  2. Leave out the .pdb files. zhttp doesn’t need them.

  3. 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.