Stream and Images sources
Stream and Images are two of the eight source types. They are account-scoped, read through the read-only discovery token over the Cloudflare REST API rather than a Workers binding, alongside cf-config and Workers. Each captures an inventory of what exists, and optionally the bytes behind it.
What each captures
By default each source captures a metadata inventory, not the binary content. The bytes are an opt-in, covered below.
| Source | Default capture | Paging ceiling |
|---|---|---|
| Stream | One record per video, carrying the video’s metadata (name, signed-URL requirement, allowed origins, user metadata). | Listed in pages of up to 1000 videos, across up to 1000 pages. |
| Images | One record per image, carrying its metadata, plus one record holding the account-level variant definitions. | Listed in pages of up to 1000 images. |
When a listing reaches its ceiling, the record set carries an explicit _truncated marker rather than stopping silently, so a backup never looks complete when it is not.
Opt-in binary capture
Setting includeContent on one of these two sources captures the bytes as well as the inventory. It is off by default and is rejected on any other source type.
| Source | What includeContent adds |
|---|---|
| Stream | The video file (requested through the asynchronous downloads endpoint) and each caption track. |
| Images | The original image blob. |
The byte fetch is size-gated in byte-fetch.ts. A blob up to 32 MiB is buffered whole. A larger blob is streamed in 8 MiB windows when the origin supports HTTP range requests, up to the applicable record ceiling: around 3.66 GiB for a resumable, etag-pinned object, or lower (around 1.84 GiB) when the run cannot mid-record-resume it. A blob past that ceiling, or a larger blob whose origin does not support range requests, is not captured in band; the record carries an honest skipped marker rather than a partial value, and the object is recoverable out of band. Signing keys and push tokens are never captured.
How each restores
Both are reprovision-class source types: the snapshot is verified recoverable, and a restore re-provisions rather than blind-writes.
For Stream and Images, the engine has a media re-upload capability (media-restore.ts). It is opt-in, additive (create-only, it never deletes), and gated on a supplied media edit-token, the target account id, and an explicit confirm. An image is re-uploaded under its original id, so it keeps its identity. A video is re-uploaded through a direct creation, and Stream assigns a new uid, so the receipt reports the old-to-new id mapping. The whole-value upload is bounded at 25 MiB, and a single direct Stream upload at 200 MB (decimal, 200,000,000 bytes); anything larger stays out of band. This is a console v1 control: the restore flow’s “Media restore” disclosure takes the edit token and the account id, the dry-run plan shows which files an apply would upload, and an apply needs the same dual-control approval as any other restore.
Where this fits
- Sources overview places these two alongside the KV, R2, D1, Secrets Store, cf-config and Workers sources, sets out the binding-versus-token read split, and names the read-only “Read all resources” template the discovery token these sources read through is minted from.
- Selectors and scope explains how a downpipe selects what each source captures.
- Cloudflare token scopes covers the separate deploy token that changes the engine’s bindings, which these account-scoped sources need none of, and the edit-scoped token a configuration restore needs.
- What restore can and cannot write back covers the reprovision and out-of-band split across every source type.
Last updated .