Developer Guide: Target CDN Asset Delivery

This guide explains how to use test.tgtcdn.com for private GCS-backed image retrieval, Cloudflare-native image transformations, Scene7-style compatibility URLs, cache behavior, and purge by GCS object key.

Platform Summary

Capability	How it works in the POC
Native image retrieval	`https://test.tgtcdn.com/<object-key>` reads the original private GCS object through `cdn-gateway`.
Native image transforms	`https://test.tgtcdn.com/cdn-cgi/image/<options>/<object-key>` uses Cloudflare Image Transformations directly.
Compatibility image transforms	`https://test.tgtcdn.com/is/image/Target/<object-key>?<scene7-options>` routes through `image-url-translator`, then redirects to the native transform URL.
Cache purge	Operators purge by GCS key using `scripts/purge-env.mjs --asset-key <object-key>`, which purges the raw original URL and transformed variants tied to the same key.
Demo and health	`/demo` shows examples. `/health` shows POC status and recent asset activity.

Native Image Retrieval

Use raw object URLs when the page or application needs the original GCS object without resizing, format conversion, or quality changes.

https://test.tgtcdn.com/<object-key>

Known working example:

https://test.tgtcdn.com/images/image.jpg

Retrieval behavior:

Header or behavior	Meaning
`X-CDN-Origin: GCS`	The asset is served through the private GCS origin adapter.
`X-Origin-Mode: gcs-service-account`	The Worker authenticates to GCS using a service-account secret.
`X-Asset-Path: /images/image.jpg`	Public path mapped to the GCS object key.
`X-Cache-Tag: gcs-key:images-image.jpg:f0be210300cb`	Human-readable deterministic cache tag derived from the GCS object key plus a short hash suffix.
`CF-Cache-Status: HIT`	Repeat request is served from Cloudflare cache.

Native Image Transformations

Use native Cloudflare Image Transformations URLs when Target controls application or page markup. This is the preferred long-term path because the browser requests Cloudflare's image pipeline directly without a compatibility redirect.

https://test.tgtcdn.com/cdn-cgi/image/<options>/<object-key>

Example product detail image:

https://test.tgtcdn.com/cdn-cgi/image/width=1200,height=1200,quality=85,format=auto,fit=scale-down,metadata=none/images/image.jpg

Example product tile:

https://test.tgtcdn.com/cdn-cgi/image/width=400,height=400,quality=80,format=auto,fit=crop,metadata=none/images/image.jpg

Example responsive gallery markup:

<img
  src="https://test.tgtcdn.com/cdn-cgi/image/width=800,height=800,quality=80,format=auto,fit=scale-down,metadata=none/images/image.jpg"
  srcset="
    https://test.tgtcdn.com/cdn-cgi/image/width=300,height=300,quality=80,format=auto,fit=scale-down,metadata=none/images/image.jpg 300w,
    https://test.tgtcdn.com/cdn-cgi/image/width=400,height=400,quality=80,format=auto,fit=scale-down,metadata=none/images/image.jpg 400w,
    https://test.tgtcdn.com/cdn-cgi/image/width=600,height=600,quality=80,format=auto,fit=scale-down,metadata=none/images/image.jpg 600w,
    https://test.tgtcdn.com/cdn-cgi/image/width=800,height=800,quality=80,format=auto,fit=scale-down,metadata=none/images/image.jpg 800w,
    https://test.tgtcdn.com/cdn-cgi/image/width=1200,height=1200,quality=80,format=auto,fit=scale-down,metadata=none/images/image.jpg 1200w
  "
  sizes="(min-width: 992px) 60vw, 50vw"
  alt="Product image"
>

Transformation Defaults

Area	POC default
Supported compatibility widths	`300`, `320`, `400`, `480`, `600`, `640`, `670`, `800`, `960`, `980`, `1200`, `1280`, `1600`, `1920`
Product gallery widths	`300`, `400`, `600`, `800`, `1200`
Observed marketing/recommendation widths	`670`, `980`
Format for new markup	`format=auto`
Product gallery quality	`quality=80`
Detail/hero quality	`quality=85`
Compressed marketing quality	`quality=65` where already observed
Gallery/detail fit	`fit=scale-down`
Tile/marketing crop fit	`fit=crop`
Metadata	`metadata=none`

Each unique option set creates a separate cacheable image variant. Keep widths, quality levels, and fit modes intentional to avoid unnecessary variant growth.

Compatibility URL Translation

Use compatibility URLs when testing existing Scene7-style URLs or when URL generation cannot change yet.

https://test.tgtcdn.com/is/image/Target/<object-key>?wid=<width>&hei=<height>&qlt=<quality>&fmt=<format>&fit=<fit>

Example compatibility request:

https://test.tgtcdn.com/is/image/Target/images/image.jpg?wid=800&hei=800&qlt=80&fmt=pjpeg

Current flow:

/is/image/Target/... -> image-url-translator Worker -> 302 -> /cdn-cgi/image/...

Compatibility parameter mapping:

Scene7-style option	POC behavior
`wid`	Maps to `width`. Unsupported between-values snap up to the next supported width.
`hei`	Maps to `height`. If width is snapped, height is scaled by the same ratio.
`qlt`	Maps to `quality`. POC-safe range is normalized to `60-90`.
`fmt=pjpeg`	Maps to `format=jpeg`. New native markup should use `format=auto`.
`fit=crop,1`	Maps to `fit=crop`.

Examples of compatibility normalization:

Request	Resolved behavior
`wid=500&hei=500`	`width=600,height=600`
`wid=1000&hei=430&fit=crop,1`	`width=1200,height=516,fit=crop`
`wid=670&hei=377&qlt=65&fmt=pjpeg&fit=crop,1`	Preserves `670x377`, maps to `quality=65,format=jpeg,fit=crop`

Compatibility URLs are useful for migration testing and noisy legacy URL handling. They are not the preferred final markup because the current implementation adds a browser redirect before the transformed image is fetched.

Cache And Purge Logic

Raw source assets and transformed variants are cached at Cloudflare. The same source image requested with different transform options creates distinct transformed variants.

Purge is based on the GCS object key. Operators provide the object key once, and the purge script derives the Cloudflare purge targets.

node scripts/purge-env.mjs test-tgtcdn --asset-key images/image.jpg \
  --evidence-out ws1-evidence/purge-images-image-by-tag.json

Purge behavior:

Step	What happens
Compute cache tag	`images/image.jpg` becomes `gcs-key:images-image.jpg:f0be210300cb`.
Purge transformed variants	Cloudflare purge API receives the derived `tags` purge target.
Purge raw original	Cloudflare purge API also receives the raw public URL, for example `https://test.tgtcdn.com/images/image.jpg`.
Record marker	The script posts a purge marker to `/api/purge-events` when `HEALTH_API_KEY` is available.
Validate	Evidence captures pre-purge `HIT`, immediate post-purge `MISS`, and post-warm `HIT`.

Why both tag and raw URL are used:

Tag purge invalidates transformed variants associated with the GCS key.
Exact raw URL purge invalidates the original object URL.
The operator only passes the GCS key; the script computes both purge targets.
The tag keeps the object key recognizable while the short hash suffix prevents collisions between similar keys.

When To Use Each Structure

Use case	Recommended structure
Original image delivery with no resize	Native retrieval: `/<object-key>`
New product page markup	Native transform: `/cdn-cgi/image/...`
Responsive `srcset` generated by Target	Native transform URLs with agreed widths
Existing Scene7-shaped URLs	Compatibility URL: `/is/image/Target/...`
URLs needing snapping, validation, or parameter cleanup	Compatibility Worker path
Stable legacy patterns that do not need complex logic	Future Transform Rule rewrite, documented separately in `config/IMAGE-COMPAT-RULES.md`
Same-key GCS overwrite	Purge by GCS key with `scripts/purge-env.mjs --asset-key <object-key>`

Observability And Tooling

Surface	Purpose
`/demo`	Visual image gallery showing raw and transformed delivery.
`/health`	POC health dashboard backed by Workers Analytics Engine.
`/api/assets`	Per-asset rollups for delivered assets and purge markers.
`scripts/test-developer-image-guide.mjs`	Live regression suite generated from this guide.
`scripts/purge-env.mjs`	Cache purge and evidence capture by URL or GCS object key.

Validation Commands

Validate raw native retrieval:

curl -I "https://test.tgtcdn.com/images/image.jpg"

Validate native transform delivery:

curl -I -H "Accept: image/webp" \
  "https://test.tgtcdn.com/cdn-cgi/image/width=640,quality=85,format=webp,fit=scale-down/images/image.jpg"

Validate compatibility behavior:

curl -IL "https://test.tgtcdn.com/is/image/Target/images/image.jpg?wid=1200&hei=1200&qlt=80"

Validate key-based purge behavior:

node scripts/purge-env.mjs test-tgtcdn --dry-run --asset-key images/image.jpg

Run the full guide-derived image suite:

node scripts/test-developer-image-guide.mjs

Expected signals:

Signal	Meaning
`HTTP 200` on raw retrieval	The original object was served.
`X-CDN-Origin: GCS`	Raw retrieval went through the private GCS gateway.
`X-Cache-Tag: gcs-key:images-image.jpg:f0be210300cb`	Raw retrieval is associated with the key-derived purge tag.
`HTTP 200` on native transform	The transformed image was served.
`cf-resized` response header	Cloudflare Image Transformations processed the image.
`HTTP 302` on compatibility URL	The compatibility Worker redirected to native `/cdn-cgi/image/...`.
`CF-Cache-Status: HIT` on repeat request	The asset or variant is cached at Cloudflare.

Target CDN asset-layer POC. This documentation content is generated from IMAGE-TRANSFORM-GUIDE.md, hosted on Cloudflare Pages, and exposed on /developer by a dedicated docs route.