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	Purge the Cloudflare cache tag `gcs-key:<object-key>` from the Cloudflare Dashboard or Cache Purge API.
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`	Deterministic cache tag derived directly from the GCS object key.
`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. The Worker attaches the object key directly as the Cloudflare cache tag, prefixed with gcs-key:.

gcs-key:images/image.jpg

Purge behavior:

Step	What happens
Identify object key	`https://test.tgtcdn.com/images/image.jpg` maps to object key `images/image.jpg`.
Compute cache tag	Add the `gcs-key:` prefix: `gcs-key:images/image.jpg`.
Purge by Dashboard	Cloudflare Dashboard > Caching > Configuration > Purge Cache > Custom Purge > Tags.
Purge by API	Send `{"tags":["gcs-key:images/image.jpg"]}` to the Cloudflare zone purge endpoint.
Validate	Request the same raw and transformed URLs again and confirm stale content is gone.

API example:

ZONE_ID="aacac726952b470209b3c31c95ea0b17"

curl -X POST "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/purge_cache" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"tags":["gcs-key:images/image.jpg"]}'

Do not exact-purge /cdn-cgi/image/... transformed URLs. Cloudflare rejects exact purges for resized image URLs; purge the gcs-key:<object-key> tag instead.

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 cache tag `gcs-key:<object-key>` through Cloudflare Dashboard or API.

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.

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"

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`	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.