kandev/apps/backend/internal/agentctl/server/api/AGENTS.md

agentctl API package notes

Scoped guidance for apps/backend/internal/agentctl/server/api/. Covers patterns that aren't obvious from reading the code in isolation.

Reverse-proxy body rewriting (port_proxy.go)

The port proxy's ModifyResponse hook scans HTML responses to inject the inspector script (html_injector.go). For that scan to work, the body must arrive uncompressed.

Don't decompress manually. Instead, in the Rewrite hook, delete Accept-Encoding on the outbound request:

r.Out.Header.Del("Accept-Encoding")

net/http.Transport then adds its own Accept-Encoding: gzip and auto-decompresses before ModifyResponse runs. Leaving the client's value intact (e.g. gzip, br, deflate) skips Transport's auto-decompression — the body arrives compressed and any byte scan corrupts it.

After rewriting the body in injectScriptsIntoResponse:

• resp.Header.Del("Content-Encoding")
• Set both resp.Header["Content-Length"] and resp.ContentLength (forgetting either causes chunked-encoding mismatches in the browser).

Tested in port_proxy_test.go::TestCreatePortProxy_StripsAcceptEncodingAndInjectsHTML.

Iframe-blocking headers

stripIframeSecurityHeaders removes Content-Security-Policy, Content-Security-Policy-Report-Only, and X-Frame-Options from proxied HTML responses. This is scoped to HTML responses only (gated by Content-Type in ModifyResponse); other content types pass through with headers intact.