A technical walkthrough of Vrows: mapping real URLs to /p/<scheme>/<host>/… paths, rewriting HTML with HTMLRewriter, patching CSS and script navigation, following redirects inside the Worker, and the Referer trick that rescues pages which build URLs for the wrong origin.
I built Vrows to find out what actually happens inside a web proxy that has to keep a page working. Fetching a URL is the easy 10%. The remaining 90% is making sure nothing the page does escapes the proxy. This post covers the mechanics; a companion post covers the safety and privacy side.
Proxied pages live under:
/p/<scheme>/<host>/<path>?<query>So https://example.com/a/b.html becomes /p/https/example.com/a/b.html. Because the real path structure is preserved, a relative reference such as ../img/x.png still resolves correctly against the proxied page — the browser does the work. A query-string scheme (/proxy?url=...) would break every relative URL and require rewriting them all.
proxyUrl() and realFromProxyPath() are exact inverses of each other, and they're the only place that mapping lives.
HTMLRewriterCloudflare's HTMLRewriter is a streaming, selector-based transformer: you attach handlers to elements and attributes and the response is transformed as it flows. The rewriter handles href, src, action, poster, data-src, formaction and the srcset family, skipping #fragment, javascript:, mailto:, data: and blob: values. A <base href> is honoured when resolving URLs and then removed, so the browser can't use it to resolve links outside the proxy, and a small client script is injected at the start of <head>.
Streaming matters: the page starts rendering before the whole body has been transformed.
url(...) and @import.location.href = '…' or location.assign(…), which would jump straight out of the proxy. The Worker rewrites those expressions to call a helper (window.__vrNav || location) that maps the destination back through the proxy. It is intentionally conservative: only files containing location, and only below a size cap (300 KB) are touched, because regex-rewriting minified code is risky and slow. Everything larger streams through unchanged.I treat the JS rewrite as best-effort, not a guarantee. That's the honest limit of this approach; a heavy single-page app may still escape.
The Worker calls fetch with redirect: 'manual' and walks the chain itself, up to 12 hops. Two reasons:
The method rules follow the HTTP spec: a 303, or a 301/302 after a POST, becomes a GET with the body dropped. A tiny retry handles the occasional 525/526 that Cloudflare-fronted sites return to Worker subrequests.
Client-side code sometimes constructs a URL against our origin — for example location.href = '/login'. Our origin has no /login. The Worker looks at the Referer, recovers which real site the page was proxying, and answers with a 307 to that site's /login through the proxy. It is a small fallback that fixes a surprising number of "works in the browser, breaks in the proxy" cases.
Downloads started by the app carry a hint parameter naming the originating page, since many CDNs check the Referer. The Worker removes it again without re-encoding the rest of the query, because signed URLs break if their query is re-serialised.
HTML is rewritten, CSS and small JS are patched, JSON for one specific host is filtered, and everything else streams through untouched, keeping content-length so video can seek. A short allow-list of response headers is forwarded; most request headers (cookie, origin, referer, sec-*) are dropped and replaced with values describing the proxied page, not the proxy.
Securing a Self-Hosted Web Proxy — SSRF Guards, Cookie Namespacing and an HttpOnly Access Key
The security decisions in Vrows, a web proxy on Cloudflare Workers: blocking private and loopback targets (SSRF), isolating per-site cookies under a prefixed name, protecting the proxy with an HttpOnly key cookie, and filtering ad requests where browser blockers can't reach.
Reading a Stream in the Browser — Chunk Boundaries, Markdown Re-renders and an innerHTML Risk
A review of the front end of a small streaming chatbot: reading an SSE response with fetch and getReader, why splitting each network chunk on newlines can drop tokens, the cost of re-rendering Markdown on every chunk, and why model output should be sanitised before innerHTML.
Building PSM — An Offline Music Player That Lives Entirely in the Browser
Notes from building PSM, an installable iPhone music PWA with no backend: why the library lives in IndexedDB, how the app is split into a thin data layer, one audio element and a store, and what a same-day v1 looked like commit by commit.