Skip to content

Extract Storage-only Smart CDN image package - #481

Merged
kvz merged 5 commits into
mainfrom
img-package
Aug 31, 2026
Merged

Extract Storage-only Smart CDN image package#481
kvz merged 5 commits into
mainfrom
img-package

Conversation

@kvz

@kvz kvz commented Aug 31, 2026

Copy link
Copy Markdown
Member

Why

Responsive Transloadit Storage previews should be a small reusable primitive, with image bytes
traveling directly from Smart CDN to the browser. The initial public-URL prototype still made an
arbitrary-origin Built-in part of the package contract; there are no adopters yet, so this PR
narrows that boundary before publication instead of carrying a risky compatibility surface.

What

  • adds a private @transloadit/img@0.0.0 workspace with a framework-neutral model, native
    <picture> rendering, and one configured Next.js Server Component
  • accepts only relative Transloadit Storage object paths through the native-looking
    src="website/photo.jpg" API, with intrinsic width/height
  • defaults to signed builtin/storage-preview@0.0.1 and permits one trusted factory-level Template
    override; individual images cannot select Templates
  • keeps direct signed Smart CDN delivery as the gallery default and supports an opt-in authorized
    redirect route for request-time object access checks and stable cached markup
  • validates Storage paths and prefixes, duplicate/unknown/tampered capabilities, bounded
    transformations, and strict boolean authorization without exposing object details
  • makes the lower-level @transloadit/utils candidate helper require both an explicit trusted
    Template and an explicit browser fallback URL; it no longer selects builtin/serve-image
  • cleans TypeScript output before packing so deleted artifacts cannot survive incremental builds

Security and performance evidence

  • the package never accepts arbitrary HTTP origins and never lets an image choose its Template
  • packed-fixture probes cover direct delivery, authorized GET/HEAD redirects, denied access,
    capability tampering, route binding, secret leakage, and private-path leakage
  • at 100 images, direct delivery produced 391,054 raw / about 25 KB Brotli HTML and zero app image
    requests; redirect delivery produced 280,008 raw / about 64 KB Brotli HTML plus 100 authorization
    redirects
  • the Next.js 16.3 fixture proves Partial Prerendering for direct delivery and static markup for
    redirect delivery
  • council review found the Template-input/fallback ambiguity; a fail-before/pass-after regression
    now keeps them separate. Its semver concern is intentionally handled as a patch replacement under
    the agreed zero-consumer policy for this newly introduced API.

Verification

  • yarn check
  • yarn verify:full
  • yarn release:pack:dry-run
  • yarn test:img:fixture
  • inspected the packed tarball to prove removed public-URL artifacts are absent

Rollout

Storage delivery depends on transloadit/api2#8844. Content can separately bridge its existing
public originals through a signed, origin-pinned workspace Template, then migrate those originals
to Transloadit Storage. Only after those consumers are deployed should API2 remove
builtin/serve-image; the dependency order and evidence live in
docs/prompts/2026-08-31-img-delivery-dx.md.

@kvz kvz changed the title Extract responsive Smart CDN image package Extract Storage-only Smart CDN image package Aug 31, 2026
@kvz
kvz merged commit ed75f00 into main Aug 31, 2026
13 checks passed
@kvz
kvz deleted the img-package branch August 31, 2026 13:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant