Your first Starlark script

Drive the proxy from a Starlark script (a sandboxed Python dialect) instead of Java: answer a request, add headers, and watch the script reload when you edit it. Use this page to get started; Scripting with Starlark and the Starlark API cover everything else.

Write the script

Save this as hello.star. Every hook is optional; these two run for every request and every response:

def on_request(req, ctx):
    if req.path == "/hello":
        return response(200, "hello from Starlark\n")   # answer without contacting the server
    req.headers["X-Client"] = ctx.client_ip              # add a header to what goes upstream

def on_response(req, res, ctx):
    res.headers["X-Scripted"] = "yes"

Run it

Scripting is in the microproxy-starlark module; its -all jar has the launcher and every optional feature built in (Install):

MICROPROXY_VERSION=0.4.1-SNAPSHOT
java -jar microproxy-starlark/target/microproxy-starlark-${MICROPROXY_VERSION}-all.jar --port 8080 --script hello.star

$ curl -s -x http://127.0.0.1:8080 http://example.com/hello
hello from Starlark
$ curl -s -o /dev/null -D - -x http://127.0.0.1:8080 http://example.com/ | grep -i x-scripted
X-Scripted: yes

Add --mitm to run the same hooks on the requests inside HTTPS connections (see MITM, certificates and TLS).

Edit it while it runs

The proxy re-reads the script when the file changes (checked at most once a second). An edit that does not compile is logged and the previous version stays in use; --script-no-reload turns reloading off. Scripts are sandboxed: no file, network or process access, and each hook call has a budget of steps, time and memory (Budgets and measurements).

From Java

The same script, embedded: one ScriptedProxy is the filters source and the chained proxy manager (for an upstream hook).

ScriptedProxy script = ScriptedProxy.builder(Path.of("hello.star")).build();
MicroProxy.bootstrap().withPort(8080).withFiltersSource(script).withChainProxyManager(script).start();

Next steps

• Scripting with Starlark: routing (upstream), interception decisions, failures, authentication, WebSockets, frames, TCP, UDP and QUIC hooks, with examples.
• Starlark API: every hook, object, built-in and module.