First-party relay

battery/relay is a declarative reverse proxy that serves third-party services — analytics vendors, chat widgets, error trackers — from your own origin. You declare one mount path and, under it, a fixed list of routes: prefix, upstream, allowed methods. Visitors' browsers then talk to https://your-app.example.com/__gofastr/t/... instead of the vendor's domain, and your strict default Content-Security-Policy (default-src 'self') stays untouched: no script-src or connect-src exceptions, no third-party cookies on your origin, no vendor DNS on your pages. It is a framework.Plugin, not a Battery: no dependencies, no workers, one shared HTTP transport whose idle connections close on app shutdown.

Wiring

import (
	"github.com/DonaldMurillo/gofastr/battery/relay"
	"github.com/DonaldMurillo/gofastr/framework"
)

app := framework.NewApp(
	framework.WithConfig(framework.AppConfig{Name: "myapp"}),
)
r := relay.New(relay.Config{
	// Path defaults to "/__gofastr/t"; any absolute path works.
	Routes: []relay.Route{
		{
			Prefix:   "e/",   // subtree: POST /t/e/{rest} → plausible.io/api/event/{rest}
			Upstream: "https://plausible.io/api/event",
			Methods:  []string{"POST"},
		},
		{
			Prefix:   "js/",   // GET /t/js/{rest} → plausible.io/js/{rest}
			Upstream: "https://plausible.io/js",
			Methods:  []string{"GET"},
			CacheOK:  true,   // immutable, versioned scripts may cache
		},
	},
})
app.RegisterPlugin(r)

Point the vendor's client SDK at the mount with Base() instead of hard-coding the prefix:

plausibleBase := r.Base() + "/e"

New panics on invalid config (unknown scheme, http:// to a non-loopback host, an internal/private upstream, empty Methods, traversal in a prefix, a mount colliding with a reserved /__gofastr/... route). A misdeclared relay is a programmer error you want at startup, not a runtime surprise.

Route table semantics

• The request's query string passes through verbatim (/t/e/x?v=2 → upstream …/x?v=2); analytics SDKs need it.
• Methods are an allow-list. Empty is invalid — be explicit. Anything undeclared gets 405 with an Allow header; tails under no declared prefix get 404. A permitted HEAD response forwards no body, so its representation's Content-Type and positive Content-Length do not trigger body-type refusal.
• Bodies are capped per route at MaxBodyBytes (default 8 MiB), covering both declared Content-Length and chunked bodies → 413. The same budget bounds the upstream's response. Its status and headers are already sent when the cap is reached, so the relay aborts the stream: the client sees a broken response, never a clean one cut short. A response of exactly the budget arrives whole.
• Content types are an allow-list too. A route relays script (text/javascript, application/javascript), text/css, images, fonts, JSON (application/json and any application/*+json) and text/plain. Anything else the vendor sends, text/html above all, is replaced with a plain 502. A route that relays a vendor's iframe page opts the type back in with ContentTypes: []string{"text/html"} (lowercase type/subtype, no parameters; New panics otherwise). An SVG passes with Content-Security-Policy: sandbox added, unless the route names image/svg+xml in ContentTypes. A body with no Content-Type goes out as application/octet-stream. The check guards a body: a response that forwards none (a 204 or 304, a Content-Length: 0, or a chunked body that ends before its first byte) passes whatever its type, so a beacon endpoint answering 204 or an empty 200 under text/html stays the success it was upstream.
• Caching: CacheOK: false (default) forces Cache-Control: no-store on every response. CacheOK: true passes upstream cache headers through, for immutable versioned assets. 304 Not Modified always passes through.

The hardening contract

None of this is configurable. The relay is on your public edge, so its posture is fixed:

Threat model

This is not an open proxy. An open proxy takes a URL from the request and fetches it; the relay takes nothing. Every route names its upstream at construction, request data cannot select scheme, host, or port (verified by hostile-tail tests in battery/relay), credentials flow neither direction, and the outbound surface per route is bounded by the method list and the body cap.

A relayed response runs as your app. It answers on your origin, so an HTML page from the vendor, whether an error page that echoes the query string or a compromised vendor, would be script with your cookies and your CSP's blessing: reflected XSS. That is why the relay refuses document types by default and adds nosniff, and why opting text/html in with Route.ContentTypes means trusting that vendor as much as your own code. Prefer pointing the iframe at the vendor's own origin.

Egress is your cost now. Every relayed byte leaves from your servers, and every request your page makes to the vendor is a request an attacker can also make to your wallet: the mount is public unless you gate it (see below). The 8 MiB default body cap is a brake, not a budget — think before raising it.

Ad-block honesty. Serving the vendor first-party defeats domain-based block lists (the request no longer goes to plausible.io, it goes to you). It does NOT defeat path-based lists: ad-blockers that ship generic rules for /api/event, /collect, /analytics style paths will match those same paths under your mount. That is why the default Path is the neutral /__gofastr/t and prefixes are yours to choose: pick names that describe YOUR integration (t/e, t/js), not the vendor's vocabulary, and don't expect immunity — visitors who block trackers on behavior rather than origin will still block.

Common mistakes

• Forgetting auth.CSRF() when you add app.Use(auth.CSRF(...)) app-wide. The relay's POST routes are form-less beacons; a global CSRF middleware 403s them because they carry no token. Exempt the mount: app.Use(auth.CSRF(auth.WithCSRFSkipPaths("/__gofastr/t/"))) — the credential-stripping contract above is what makes this safe: no cookies reach the vendor, so there is nothing to forge with.
• Gating the relay behind auth.RequireSession. Analytics and error-tracking beacons fire before login and from logged-out pages; a session gate turns your first-party numbers into "only logged-in users". Gate per-route with your own middleware if you must, not app-wide.
• Assuming ad-block immunity. First-party origin defeats domain-based lists only. Path-based lists still match; see "Ad-block honesty" above.
• Raising MaxBodyBytes without thinking. The cap is an egress brake: every accepted byte is billed to your upstream bandwidth. Beacon endpoints need kilobytes; if a vendor wants 100 MiB uploads through your relay, that traffic belongs on the vendor's own origin, not yours.