Brua

The single URL

One URL per asset that the edge resolves from the request, the query overrides, the JSON pointer, and how long each thing is cached.

Every asset has one URL that works in a plain <img> with no script: the edge picks the file from the request. The SDKs don't need it, since they choose the file themselves from the JSON, but email, markdown, a CMS field or a quick test do.

What it negotiates on

Header Picks
Accept AVIF, WebP or PNG
Sec-CH-Prefers-Color-Scheme Light or dark
Sec-CH-Prefers-Reduced-Motion The animation or its still
Accept-Language The language variant, and the alt text's language on the JSON
Sec-CH-DPR The scale
Sec-CH-Width The width from the ladder

The response says what it used: Vary lists the headers that mattered for this asset, Accept-CH asks the browser to send the hints, and Content-Location names the file that was chosen. An <img> gets a still even for an animation, since it can't play Lottie or Rive; players read those variants from the JSON.

Shell
curl -I https://cdn.brua.dev/assets/991ceed8-a70e-4a5f-b3d3-e0b6b3d93e44/bridge -H 'Accept: image/avif' -H 'Sec-CH-Width: 240'

Query overrides

Each dimension has a query parameter that overrides the header, for places that send no hints: ?w=640, ?dpr=2, ?scheme=dark, ?motion=reduce, ?lang=nb. A URL with an override doesn't vary on that header, so a CDN or a proxy in front caches it cleanly.

URL
https://cdn.brua.dev/assets/991ceed8-a70e-4a5f-b3d3-e0b6b3d93e44/bridge?scheme=dark&dpr=2&lang=en

The three URL forms

URL What it is Cached
{base}/{id}.json The current release as an AssetResponse, with every variant; ?lang= picks the alt text's language. What the SDKs read. A minute
{base}/{id} The single URL of the current release; follows every merge. A minute
{base}/{id}/{version} The single URL of one version. A year, immutable
{base}/{id}/{version}/{file} A variant file, as the JSON lists them. A year, immutable

A request for an id that has nothing released answers 404 for a minute, so a typo doesn't hammer the origin. The Asset-Release header on the JSON and the versionless URL says which release served it.

Next