sandcms 0.6.3 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (124) hide show
  1. package/README.md +14 -10
  2. package/dist/admin/Account.svelte +2 -0
  3. package/dist/admin/Admin.svelte +14 -1
  4. package/dist/admin/AssetAttachment.svelte +1 -3
  5. package/dist/admin/AssetAttachment.svelte.d.ts +0 -1
  6. package/dist/admin/BlueprintFields.svelte +0 -3
  7. package/dist/admin/BlueprintFields.svelte.d.ts +0 -1
  8. package/dist/admin/Editor.svelte +0 -1
  9. package/dist/admin/Fields.svelte +0 -7
  10. package/dist/admin/Fields.svelte.d.ts +0 -1
  11. package/dist/admin/Gallery.svelte +2 -6
  12. package/dist/admin/Gallery.svelte.d.ts +0 -1
  13. package/dist/admin/LinkField.svelte +0 -3
  14. package/dist/admin/LinkField.svelte.d.ts +0 -1
  15. package/dist/admin/MediaLibrary.svelte +10 -7
  16. package/dist/admin/MediaPicker.svelte +7 -15
  17. package/dist/admin/MediaPicker.svelte.d.ts +0 -1
  18. package/dist/admin/ThemePicker.svelte +72 -0
  19. package/dist/admin/ThemePicker.svelte.d.ts +18 -0
  20. package/dist/admin/UploadButton.svelte +2 -1
  21. package/dist/admin/UploadProgress.svelte +24 -0
  22. package/dist/admin/UploadProgress.svelte.d.ts +7 -0
  23. package/dist/admin/client.d.ts +3 -670
  24. package/dist/admin/client.js +2 -1
  25. package/dist/admin/components/ui/alert/alert.svelte.d.ts +3 -13
  26. package/dist/admin/components/ui/attachment/attachment-media.svelte.d.ts +3 -13
  27. package/dist/admin/components/ui/attachment/attachment.svelte.d.ts +6 -26
  28. package/dist/admin/components/ui/badge/badge.svelte.d.ts +7 -25
  29. package/dist/admin/components/ui/button/button.svelte.d.ts +15 -53
  30. package/dist/admin/components/ui/toggle/toggle.svelte.d.ts +6 -26
  31. package/dist/admin/generated/admin.css +529 -101
  32. package/dist/admin/theme-context.d.ts +7 -0
  33. package/dist/admin/theme-context.js +3 -0
  34. package/dist/admin/theme.d.ts +7 -0
  35. package/dist/admin/theme.js +14 -0
  36. package/dist/admin/types.d.ts +2 -1
  37. package/dist/admin/uploads.d.ts +8 -1
  38. package/dist/admin/uploads.js +94 -16
  39. package/dist/blueprints/files.js +1 -0
  40. package/dist/blueprints/load.js +7 -2
  41. package/dist/blueprints/types.d.ts +4 -1
  42. package/dist/cli/doctor.d.ts +3 -1
  43. package/dist/cli/doctor.js +85 -30
  44. package/dist/cli/files.d.ts +2 -6
  45. package/dist/cli/files.js +11 -2
  46. package/dist/cli/index.js +99 -31
  47. package/dist/cli/scaffold.js +8 -8
  48. package/dist/cli/setup.js +16 -26
  49. package/dist/cli/upgrade.js +21 -2
  50. package/dist/env.d.ts +32 -0
  51. package/dist/env.js +53 -3
  52. package/dist/server/admin-load.d.ts +13 -5
  53. package/dist/server/admin-load.js +6 -1
  54. package/dist/server/api-access.d.ts +4 -0
  55. package/dist/server/api-access.js +15 -2
  56. package/dist/server/api-pagination.d.ts +3 -0
  57. package/dist/server/api.js +5 -2
  58. package/dist/server/auth.d.ts +10 -9
  59. package/dist/server/cms.d.ts +65 -18
  60. package/dist/server/cms.js +62 -6
  61. package/dist/server/db/migration-data.js +4 -0
  62. package/dist/server/db/migrations/0009_local_media.sql +9 -0
  63. package/dist/server/db/migrations/meta/0009_snapshot.json +1763 -0
  64. package/dist/server/db/migrations/meta/_journal.json +7 -0
  65. package/dist/server/db/schema.d.ts +119 -2
  66. package/dist/server/db/schema.js +15 -3
  67. package/dist/server/hooks.js +155 -81
  68. package/dist/server/media/contracts.d.ts +115 -0
  69. package/dist/server/media/contracts.js +12 -0
  70. package/dist/server/media/deletions.d.ts +2 -1
  71. package/dist/server/media/deletions.js +3 -3
  72. package/dist/server/media/delivery.js +7 -11
  73. package/dist/server/media/import-r2.d.ts +56 -0
  74. package/dist/server/media/import-r2.js +342 -0
  75. package/dist/server/media/processor-child.d.ts +2 -0
  76. package/dist/server/media/processor-child.js +236 -0
  77. package/dist/server/media/processor.d.ts +51 -0
  78. package/dist/server/media/processor.js +135 -0
  79. package/dist/server/media/render-math.d.ts +24 -0
  80. package/dist/server/media/render-math.js +50 -0
  81. package/dist/server/media/runner.d.ts +30 -1
  82. package/dist/server/media/runner.js +418 -165
  83. package/dist/server/media/service.d.ts +56 -10
  84. package/dist/server/media/service.js +309 -98
  85. package/dist/server/media/storage.d.ts +5 -0
  86. package/dist/server/media/storage.js +279 -0
  87. package/dist/server/media/svg.d.ts +5 -0
  88. package/dist/server/media/svg.js +142 -0
  89. package/dist/server/media/upload-ticket.d.ts +12 -0
  90. package/dist/server/media/upload-ticket.js +35 -0
  91. package/dist/server/media/verify.d.ts +36 -0
  92. package/dist/server/media/verify.js +109 -0
  93. package/dist/server/platform/http.d.ts +27 -0
  94. package/dist/server/platform/http.js +77 -0
  95. package/dist/server/platform/index.d.ts +52 -0
  96. package/dist/server/platform/index.js +98 -0
  97. package/dist/server/platform/snapshots.d.ts +18 -0
  98. package/dist/server/platform/snapshots.js +110 -0
  99. package/dist/server/platform/volume.d.ts +20 -0
  100. package/dist/server/platform/volume.js +60 -0
  101. package/dist/worker/svg.d.ts +1 -5
  102. package/dist/worker/svg.js +2 -142
  103. package/docs/acceptance.md +6 -4
  104. package/docs/api.md +41 -3
  105. package/docs/cloudflare.md +48 -142
  106. package/docs/content.md +2 -2
  107. package/docs/deployment.md +159 -57
  108. package/docs/forms.md +1 -1
  109. package/docs/media.md +85 -21
  110. package/docs/package.md +21 -18
  111. package/docs/plans/0.7-self-hosted.md +264 -0
  112. package/docs/releases.md +17 -1
  113. package/docs/upgrades.md +35 -6
  114. package/package.json +36 -37
  115. package/templates/Dockerfile +28 -0
  116. package/templates/integration.ts +18 -2
  117. package/templates/railpack.json +1 -1
  118. package/templates/sandcms/blueprints/files/image.yaml +1 -1
  119. package/templates/sandcms/config.yaml +0 -1
  120. package/dist/cli/cloudflare.d.ts +0 -8
  121. package/dist/cli/cloudflare.js +0 -135
  122. package/templates/sandcms/worker/index.ts +0 -1
  123. package/templates/sandcms/worker/local.ts +0 -1
  124. package/templates/sandcms/worker/wrangler.jsonc +0 -6
package/docs/api.md CHANGED
@@ -60,11 +60,49 @@ curl --fail-with-body "$CMS_ORIGIN/api/cms/content/save" \
60
60
 
61
61
  The mutation and stored response commit together. Repeating the same endpoint and JSON payload with the same retry key returns the original response without repeating the mutation, even after publication or subsequent edits. Reusing that retry key with a different endpoint or payload returns 409. Payload fingerprints ignore JSON object property order. Failed writes do not consume the retry key. Idempotency-Key replays are honored for 48 hours and survive server restarts. Expired receipts are pruned in a successful content-write transaction at most once per minute per database connection; a requested receipt's expiration is always checked. After 48 hours the same retry key is treated as a new request, so inspect current content before retrying an old create. Failed requests are revalidated on retry. Retry keys are scoped to the credential: keep using the same API key when retrying. Content mutations made with API keys are audited with the owner and key ID. Read the current document again before making a later edit; a replayed response describes the original operation.
62
62
 
63
- ## Media mapping
63
+ ## Media uploads
64
64
 
65
- Use `media/upload` with `{ "name": "image.jpg", "type": "image/jpeg", "size": 12345, "blueprint": "image" }`, PUT the exact bytes to the returned presigned `upload.url`, then call `media/upload/complete` with `{ "id": "MEDIA_ID" }`. Completion is idempotent. Poll `media/list` until the asset is ready before publishing documents that reference its ID. See [the media workflow](media.md).
65
+ Files upload to the site in chunks of at most 8 MB, so no single request is large. A key with write access may upload:
66
66
 
67
- Upload initiation is **not retry-safe** and returns 400 if `Idempotency-Key` is supplied; retain the returned media ID and upload URL instead of starting another upload after receiving a response. A lost initialization response can leave an unused upload session; agents must inspect all pages of `media/list` before retrying. There is no content-hash deduplication. The endpoint accepts JSON metadata, not multipart bytes; a retry receipt around asynchronous remote signing would not guarantee atomic creation. `media/update` takes `{ "id": "MEDIA_ID", "metadata": { "alt": "Description" } }`; `media/retry` and `media/delete` take `{ "id": "MEDIA_ID" }`. Content retry receipts do not apply to these endpoints.
67
+ 1. **Initiate.** `POST /api/cms/media/upload` with `{ "name": "image.jpg", "type": "image/jpeg", "size": 12345, "blueprint": "image" }`. The response is:
68
+
69
+ ```json
70
+ {
71
+ "id": "MEDIA_ID",
72
+ "url": "https://cms.example.com/api/cms/media/upload/MEDIA_ID",
73
+ "chunkSize": 8388608,
74
+ "headers": { "x-sandcms-upload": "TICKET" },
75
+ "expiresAt": 1794887592789
76
+ }
77
+ ```
78
+
79
+ 2. **Send chunks.** Split the file into `chunkSize` pieces; only the last may be shorter. Send each with `PUT {url}?index=N` (N from 0), the raw bytes as the body, your `x-api-key`, and every header from `headers`. Chunks may be re-sent; a re-sent chunk replaces the earlier copy. `Content-Length` is optional.
80
+ 3. **Complete.** `POST /api/cms/media/upload/complete` with `{ "id": "MEDIA_ID" }` once every chunk is stored. Completion is idempotent. The file is then validated and processed in the background; poll `media/list` until the asset is `ready` before publishing documents that reference its ID.
81
+
82
+ To **resume** after an interruption, `GET {url}` with the same headers returns `{ "received": [0, 1, 2], "chunkSize": 8388608, "complete": false }`; send the missing indexes, then complete. `"complete": true` means the chunks were already assembled (for example, a completion response was lost): call complete again without sending chunks. A 404 or 410 means the upload is gone; start a new one. The ticket is bound to the asset, the declared type and size, and the same user: the session or any of that user's API keys may send its chunks. An upload with no chunk for 15 minutes expires and must be started again. Requests other than chunks are limited to 1 MB.
83
+
84
+ ```sh
85
+ FILE=photo.jpg
86
+ UPLOAD=$(curl --fail-with-body "$CMS_ORIGIN/api/cms/media/upload" \
87
+ -H "x-api-key: $SANDCMS_API_KEY" -H 'content-type: application/json' \
88
+ --data "{\"name\":\"$FILE\",\"type\":\"image/jpeg\",\"size\":$(wc -c < "$FILE"),\"blueprint\":\"image\"}")
89
+ URL=$(jq -r .url <<< "$UPLOAD")
90
+ TICKET=$(jq -r '.headers["x-sandcms-upload"]' <<< "$UPLOAD")
91
+ split -b 8388608 -d -a 4 "$FILE" chunk-
92
+ i=0
93
+ for part in chunk-*; do
94
+ curl --fail-with-body -X PUT "$URL?index=$i" --data-binary @"$part" \
95
+ -H "x-api-key: $SANDCMS_API_KEY" -H "x-sandcms-upload: $TICKET"
96
+ i=$((i + 1))
97
+ done
98
+ curl --fail-with-body "$CMS_ORIGIN/api/cms/media/upload/complete" \
99
+ -H "x-api-key: $SANDCMS_API_KEY" -H 'content-type: application/json' \
100
+ --data "{\"id\":\"$(jq -r .id <<< "$UPLOAD")\"}"
101
+ ```
102
+
103
+ Upload initiation is **not retry-safe** and returns 400 if `Idempotency-Key` is supplied; retain the returned media ID and URL and resume instead of starting another upload. A lost initiation response can leave an unused upload, which expires; agents must inspect all pages of `media/list` before retrying. There is no content-hash deduplication. `media/update` takes `{ "id": "MEDIA_ID", "metadata": { "alt": "Description" } }`; `media/retry` and `media/delete` take `{ "id": "MEDIA_ID" }`. Content retry receipts do not apply to these endpoints. See [the media workflow](media.md#uploads).
104
+
105
+ The upload flow changed in 0.7.0: earlier releases returned a presigned R2 URL that took the whole file in one `PUT`. Clients written for that flow must switch to chunks.
68
106
 
69
107
  `media/delete` returns `{ "ok": true }` once deletion is durably accepted. References and active variants are cleared immediately. If processing is active or storage is unavailable, the asset remains in `media/list` with status `deleting` until background cleanup succeeds. Repeated deletion requests are safe; deleting assets cannot be edited, retried, or selected in content.
70
108
 
@@ -1,173 +1,79 @@
1
- # Cloudflare setup and operations
1
+ # Cloudflare: legacy import and optional CDN
2
2
 
3
- SandCMS uses one Worker and one **private** R2 bucket per environment. The Worker signs direct browser uploads and accepts authenticated finalization and named variant requests, encodes images and inspects dimensions with remote transformations, and streams completed variants to authenticated CMS requests. It serves originals only to the processor using short-lived, signed source URLs. Keep staging and production resources separate.
3
+ From 0.7.0, SandCMS stores and processes images on the site's own volume and no longer uses a Cloudflare Worker or R2. This guide covers sites created before 0.7.0: importing their R2 media once, then removing the Worker and bucket. The last section describes optional CDN caching in front of any site.
4
4
 
5
- Website proxy caching is optional and separate from Worker deployment. Public image URLs remain on the website at `/_sandcms/media/{key}`. Enabling the website's Cloudflare proxy lets the CDN cache authorized image responses. No second bucket, object copying, public R2 access, or publication marker is needed.
5
+ The Worker source, the `sandcms/worker` and `sandcms/worker/local` exports, `createCMS({ workerUrl, workerToken })` and the `SANDCMS_WORKER_URL` / `SANDCMS_WORKER_TOKEN` variables are deprecated and kept through 0.7.x so the old Worker stays deployable until the import is verified. `sandcms worker update` and Cloudflare setup have been removed.
6
6
 
7
- ## Local development
7
+ ## Import R2 media
8
8
 
9
- 1. Generate a random secret of at least 32 characters.
10
- 2. Put the same value as `SANDCMS_WORKER_TOKEN` in both ignored `.env.local` and ignored `sandcms/worker/.dev.vars`.
11
- 3. Use `http://localhost:8787` as `media.workerUrl` (the starter default).
12
- 4. Run the local Worker, then restart the website:
9
+ Run this once per site, in a maintenance window, while the old protocol-6 Worker (0.6.2 or later) is still deployed. Follow the [0.7.0 upgrade checklist](upgrades.md#070-upgrade-checklist) up to the deploy first: the site runs 0.7.0, migration `0009_local_media` is applied, and `SANDCMS_WORKER_URL` and `SANDCMS_WORKER_TOKEN` are still set. The volume needs free space of at least three times the site's current media.
10
+
11
+ Images are unavailable on the site until they are imported: a variant that is not on disk yet returns 404. Then run, in the site's container (or a one-off container with the same volume and environment):
13
12
 
14
13
  ```sh
15
- bun x wrangler dev sandcms/worker/local.ts --config sandcms/worker/wrangler.jsonc --local --port 8787
14
+ bun x --no-install sandcms media import-r2
16
15
  ```
17
16
 
18
- The loopback-only `sandcms/worker/local` entry emulates S3 presigned PUTs with the shared CMS token, so local development needs no R2 API credentials. Never deploy this entry; the production `index.ts` remains unchanged. The local Worker uses simulated R2 and `cf.image` transformations for metadata inspection and encoding. Local processing checks format, dimensions, signed-source routing, and storage; production quality and limits require staging verification. The [offline Images implementation supports only a subset of transformations](https://developers.cloudflare.com/images/optimization/binding/). Automated tests need no production resources and do not exercise the Cloudflare CDN.
19
-
20
- For quality checks, use a deployed staging Worker or remote development with a dedicated staging Worker configuration bound to a staging R2 bucket. Before running `wrangler dev --remote`, verify that the configuration's `MEDIA` binding targets staging, including any `preview_bucket_name` override, and select that configuration explicitly with `--config`. Remote development connects to the configured real remote resources; it does not automatically isolate storage and could otherwise write test uploads and variants to production. See [Cloudflare's development modes](https://developers.cloudflare.com/workers/local-development/).
21
-
22
- ## Provisioning and deployment
23
-
24
- Setup optionally uses the existing Wrangler login, asks for an account, displays project-derived Worker/R2 names, checks collisions, creates the resources, sets Worker secrets (including bucket-scoped R2 signing credentials entered through masked prompts), and deploys. It writes non-secret names/URLs to tracked config and secrets to ignored environment files. The CLI does not store Wrangler credentials. Setup does not configure the website's DNS proxy or Cache Rules; complete those steps separately below.
25
-
26
- - Keep R2 public access disabled, including `r2.dev`. Do not attach a public custom domain to the bucket.
27
- - Set `media.workerUrl` to the deployed Worker URL, or use the server-only `SANDCMS_WORKER_URL` environment override.
28
- - Supply the same secret as `SANDCMS_WORKER_TOKEN` to both the website and the Worker.
29
- - Use project-owned resources. The repository's `sandcms-local-media` name is a local example, not a production bucket to reuse.
30
-
31
- The `IMAGES` binding is no longer required: both dimension inspection (`format=json`) and encoding use remote transformations. Existing project-owned configurations may retain the unused binding. Ensure image transformations are enabled for the Worker’s account and that its own hostname is an allowed source. Cloudflare supports `cf.image` on Worker zones, including `workers.dev`. The Worker constructs source URLs from its request origin; use the deployed hostname for `media.workerUrl` and avoid redirects or rewrites on `/internal/source/*`.
17
+ | Option | Default |
18
+ | ---------------------- | --------------------------------------------------------------------------- |
19
+ | `--worker-url URL` | `SANDCMS_WORKER_URL`, then `media.workerUrl` in `sandcms/config.yaml` |
20
+ | `--worker-token-stdin` | Reads the token from standard input instead of `SANDCMS_WORKER_TOKEN` |
21
+ | `--database PATH` | `SANDCMS_DATABASE`; media goes to `SANDCMS_MEDIA_DIR` or `media/` beside it |
32
22
 
33
- Signed source URLs are processor credentials, scoped to one asset and valid at the source for five minutes. Do not log or expose them, and bypass CDN cache rules on `/internal/*`. Source responses use `private, no-store`; Cloudflare maintains its own transformation cache keyed by the signed URL, which is not purged by token expiry. No `origin-auth: share-publicly` setting or public R2 bucket is needed. See [media privacy](media.md#privacy-and-publication). Never forward the CMS bearer token to a source URL.
23
+ The token is never accepted as an argument. The import:
34
24
 
35
- ### Direct upload configuration
25
+ - refuses to start while uploads are in progress (`upload_sessions` rows) or legacy BLOB uploads are queued (`uploads` rows). Let them finish or expire first;
26
+ - checks the Worker's token and protocol, then holds the media processor lease for the whole run, so the website renders nothing meanwhile. If the website is processing, it waits up to two minutes;
27
+ - downloads each raster original through the Worker's `/internal/source/{id}` route, using short-lived signed URLs minted locally from the token. The Worker checks them against its own hostname, so use its deployed URL, not a proxy or redirect;
28
+ - uses the sanitized `svg-1.svg` variant as both original and variant for SVGs, which the source route does not serve;
29
+ - downloads every ready variant through `/internal/media/{key}`, including older versions that are no longer active, since caches may still hold their URLs;
30
+ - skips assets being deleted, and reports assets with neither an original nor ready variants in R2 (for example expired uploads) as skipped;
31
+ - fills each image's width and height and each variant's ETag, and keeps asset IDs, variant keys and preset versions, so public URLs and published content are unchanged;
32
+ - runs four assets at a time and retries network errors and Worker 5xx responses with backoff;
33
+ - ends by verifying that every original and ready variant exists on disk with the expected size.
36
34
 
37
- The browser uploads to the R2 S3 API endpoint using a 15-minute presigned PUT URL. The bucket remains private. The CMS receives JSON metadata only; `BODY_SIZE_LIMIT=1M` is sufficient for its default JSON request limit. Existing customized host limits are preserved.
35
+ It prints one line per asset, then a summary, and exits nonzero if any file failed. The run is resumable: files already imported are kept and not downloaded again, so fix the cause and run the same command again until it succeeds.
38
36
 
39
- Set these **Worker** secrets with `bun x wrangler secret put NAME --config sandcms/worker/wrangler.jsonc`:
37
+ Then check the site and run:
40
38
 
41
- - `SANDCMS_CF_ACCOUNT_ID`: the Cloudflare account containing the bucket.
42
- - `SANDCMS_R2_BUCKET_NAME`: exactly the bucket bound as `MEDIA`.
43
- - `SANDCMS_R2_ACCESS_KEY_ID` and `SANDCMS_R2_SECRET_ACCESS_KEY`: an R2 S3 API token with Object Read & Write access restricted to that bucket. These are separate from Wrangler credentials and `SANDCMS_WORKER_TOKEN`; never put them in browser or website configuration.
44
-
45
- For a jurisdiction-specific endpoint, set optional Worker `SANDCMS_R2_ENDPOINT` to its HTTPS S3 endpoint. The endpoint and bucket must address the same bucket as `MEDIA`.
46
-
47
- Configure bucket CORS in R2 Settings for every authorized admin origin (merge with existing project-owned rules):
48
-
49
- ```json
50
- [
51
- {
52
- "AllowedOrigins": ["https://www.example.com"],
53
- "AllowedMethods": ["PUT"],
54
- "AllowedHeaders": ["Content-Type"],
55
- "MaxAgeSeconds": 3600
56
- }
57
- ]
39
+ ```sh
40
+ bun x --no-install sandcms media verify
58
41
  ```
59
42
 
60
- Add an R2 object lifecycle rule expiring objects under **only** `incoming/` after one day. This bounds cleanup of abandoned transfers and objects recreated by replaying an unexpired PUT URL. Do not apply this rule to originals or variants. Finalization retries must complete before lifecycle expiration; otherwise the editor must upload again.
61
-
62
- The signature binds the object key, method, content type and expiry. It is not a byte-range upload policy: declared size is checked by the CMS before signing and actual size is checked by the Worker before acceptance. A client can write an oversized staging object, but it cannot be accepted as an original. Treat upload URLs as temporary write credentials and keep them out of logs. See [R2 presigned URLs](https://developers.cloudflare.com/r2/api/s3/presigned-urls/) and [bucket CORS](https://developers.cloudflare.com/r2/buckets/cors/).
63
-
64
- Later deploys are explicit:
43
+ Imported variants keep Cloudflare's encoding. New variants are encoded by sharp under the same preset version, so an image's sizes may differ slightly in quality. To re-encode everything with sharp, run `sandcms media rebuild --force` (URLs stay the same; CDN and browser caches keep old copies until they expire).
65
44
 
66
- ```sh
67
- bun x --no-install sandcms worker update
68
- bun x --no-install sandcms doctor
69
- ```
45
+ ## Remove the Worker and bucket
70
46
 
71
- Worker updates verify recorded resource ownership. The current CMS/Worker protocol is **6**. The Worker also accepts protocols 3, 4 and 5 for existing website processes and legacy BLOB transfers, allowing the Worker to be deployed first. Direct uploads require protocol 4 or later. Focal-point crops require protocol 5 or later, and batched variant processing requires the protocol-6 Worker. Configure signing credentials, CORS and lifecycle cleanup, deploy the Worker, then migrate the database and deploy the website. The retained incremental migration adds `upload_sessions` without changing old media or pending BLOBs; follow the [upgrade workflow](upgrades.md).
47
+ 1. Remove `SANDCMS_WORKER_URL` and `SANDCMS_WORKER_TOKEN` from the site's environment and redeploy. `media.workerUrl` in `sandcms/config.yaml` is ignored and can be removed.
48
+ 2. Delete the project-owned `sandcms/worker/` directory and the `worker:dev` script, if present. `sandcms setup` and `sandcms upgrade` leave these files alone and report them as removable.
49
+ 3. Wait for a volume backup, restore it somewhere and confirm it contains the originals (`media/originals/`) and a database snapshot.
50
+ 4. Delete the Worker (`bun x wrangler delete --config sandcms/worker/wrangler.jsonc`, before removing that file, or from the Cloudflare dashboard), the R2 bucket, its bucket-scoped R2 API token and its CORS and lifecycle rules.
72
51
 
73
- For deployments still using legacy public Worker `/media/*` URLs, deploy a protocol-3 Worker to close that route, update manually constructed URLs to the CMS routes, and purge old Worker URL caches. Legacy browser copies may have a one-year immutable lifetime and cannot be recalled. Confirm bucket public access is disabled before relying on draft privacy.
52
+ Do not delete the bucket before step 3: until then it is the only off-server copy of the originals.
74
53
 
75
- ## Website proxy and public image caching
54
+ ## Optional CDN caching
76
55
 
77
- The origin authorizes an image using current published references and active variants, then marks its successful response cacheable:
56
+ A CDN in front of the site is optional. Public variants are served with:
78
57
 
79
58
  ```http
80
59
  Cache-Control: public, max-age=86400, s-maxage=2592000
81
- ETag: "object-validator"
82
- ```
83
-
84
- This gives browsers one day of freshness and shared caches 30 days. A browser hit needs no network request; a CDN hit avoids the CMS, SQLite, Worker, and R2 entirely. A cache miss still uses the CMS → Worker → R2 path. The Worker and R2 remain private. TTL specifies freshness, not guaranteed cache retention.
85
-
86
- Draft-only images return an uncached 404. Authenticated previews at `/api/cms/media/` and delivery errors retain `private, no-store`. Public responses do not vary by cookie. Conditional requests reaching the origin still check publication before returning `304`.
87
-
88
- ### Enable the website proxy
89
-
90
- 1. Deploy the updated website and Worker. The former `no-store` public policy cannot be fixed by simply enabling the proxy.
91
- 2. In the website's Cloudflare zone, change the website hostname's DNS record to **Proxied** (orange cloud).
92
- 3. Use **Full (strict)** SSL/TLS with a valid origin certificate. Keep website `SANDCMS_ORIGIN` and SvelteKit `paths.origin` configured to the public HTTPS origin; see [host configuration](deployment.md#host-configuration).
93
- 4. In **Rules → Cache Rules**, add the two rules below, replacing `www.example.com` with the actual website hostname. Repeat for any other hostname that serves the website.
94
-
95
- Do not change trusted-client-IP settings just to enable caching. Trust a proxy header only after configuring the origin so clients cannot spoof it; see [deployment guidance](deployment.md#host-configuration).
96
-
97
- ### Rule 1: SandCMS public images
98
-
99
- Paste this into the expression editor:
100
-
101
- ```text
102
- (http.host eq "www.example.com" and starts_with(http.request.uri.path, "/_sandcms/media/") and http.request.uri.query eq "")
60
+ ETag: "…"
103
61
  ```
104
62
 
105
- Set:
106
-
107
- | Setting | Value |
108
- | ------------------------- | -------------------------------------------------------- |
109
- | Cache eligibility | Eligible for cache |
110
- | Edge TTL | Use cache-control header if present, bypass cache if not |
111
- | Browser TTL | Respect origin |
112
- | Status code TTL overrides | None |
113
- | Cache key | Default; retain query strings, do not add cookies |
114
-
115
- Do not select **Ignore cache-control header and use this TTL**: errors must remain uncached. Do not apply the public-image policy to the whole website. GET/HEAD handling is left to Cloudflare and the origin; the expression intentionally has no method restriction so URL purging can match it.
116
-
117
- ### Rule 2: SandCMS private routes and query requests
118
-
119
- Place this bypass rule after any broader cache rules that might otherwise match it:
120
-
121
- ```text
122
- (http.host eq "www.example.com" and (http.request.uri.path eq "/admin" or starts_with(http.request.uri.path, "/admin/") or http.request.uri.path eq "/api/cms" or starts_with(http.request.uri.path, "/api/cms/") or http.request.uri.query ne ""))
123
- ```
124
-
125
- Set **Cache eligibility → Bypass cache**. This deliberately bypasses all query-bearing URLs, including content previews and rejected image transformation queries. It avoids sharing a cached ordinary page with a preview request. Other application caching needs can be configured separately with equally explicit rules.
126
-
127
- Audit existing rules for conflicts: a later whole-site override can defeat these settings; a blanket bypass-on-cookie rule can prevent public image cache hits for signed-in visitors. Never bypass origin privacy directives to work around a cache miss. These rules govern image delivery; they do not enable public HTML caching.
128
-
129
- Cloudflare documents the [proxied DNS requirement](https://developers.cloudflare.com/cache/how-to/cache-rules/), [Cache Rule settings and TTL overrides](https://developers.cloudflare.com/cache/how-to/cache-rules/settings/), [rule ordering](https://developers.cloudflare.com/cache/how-to/cache-rules/order/), and [origin cache-control behavior](https://developers.cloudflare.com/cache/concepts/cache-control/).
130
-
131
- ### Verify delivery
132
-
133
- Use a real published image URL, with no query string. Run the GET twice (rather than relying only on HEAD):
134
-
135
- ```sh
136
- MEDIA_URL='https://www.example.com/_sandcms/media/REPLACE_WITH_ACTUAL_VARIANT_KEY'
137
- curl -sS -D - -o /dev/null "$MEDIA_URL"
138
- curl -sS -D - -o /dev/null "$MEDIA_URL"
139
- ```
140
-
141
- Expect HTTP 200, the public cache policy, an ETag, no `Set-Cookie` or `Vary: Cookie`, and eventually `CF-Cache-Status: HIT` (often `MISS` on the first request). `Age` indicates time in the shared cache. Requests may reach different cache locations, so an immediate HIT is not guaranteed. For conditional delivery, copy the actual ETag:
142
-
143
- ```sh
144
- curl -sS -D - -o /dev/null -H 'If-None-Match: "REPLACE_WITH_ACTUAL_ETAG"' "$MEDIA_URL"
145
- ```
146
-
147
- Expect 304 when the representation is unchanged. The CDN may answer this itself. To verify origin revocation after unpublishing, purge the exact image URL first or use a controlled direct-origin request; a CDN hit is allowed to keep serving the previously public image.
148
-
149
- Also check:
150
-
151
- - A never-published image returns 404 and `private, no-store` on repeated public requests, including with `If-None-Match: *`.
152
- - A signed-out preview request returns 401 and `private, no-store`.
153
- - A signed-in preview succeeds but remains `private, no-store`, without an ETag or CDN HIT. Inspect it in browser developer tools without sharing session cookies.
154
- - An image URL with `?width=100` returns an uncached 404, even after warming the ordinary URL.
155
- - Publishing that previously private image immediately makes the origin return 200; a cached negative response must not delay publication.
156
-
157
- If a public image remains `BYPASS` or `DYNAMIC`, inspect response headers, proxy status, Development Mode, and matching Cache Rules using Cloudflare Trace. Check for upstream `Set-Cookie`, old `no-store` responses, and conflicting cookie bypass rules. See [uncached-response troubleshooting](https://developers.cloudflare.com/cache/troubleshooting/investigating-uncached-responses/).
158
-
159
- ### Unpublishing, deletion, and purging
160
-
161
- Unpublishing or removing the last published reference immediately denies new origin requests. It does not recall cached images. Cloudflare may keep serving a fresh copy for the remaining shared-cache lifetime; browsers may keep using their cached copy. A cold cache can return 404 while another location still serves 200. This is the intended tradeoff for fast public delivery.
63
+ Browsers keep them for a day and shared caches for 30 days. Editor previews at `/api/cms/media/` and all errors use `private, no-store`. With Cloudflare proxying the site's hostname (DNS record **Proxied**, SSL/TLS **Full (strict)**), add two Cache Rules, replacing `www.example.com`:
162
64
 
163
- SandCMS does **not** automatically purge Cloudflare. For deliberate removal, unpublish/remove the reference (or delete the asset) first, then use **Caching → Configuration → Purge Cache → Custom Purge** to purge every affected full public variant URL. Purging before revoking origin access allows the cache to refill. There can be several formats and sizes per image. See [purge by URL](https://developers.cloudflare.com/cache/how-to/purge-cache/purge-by-single-file/).
65
+ 1. **Public images** — _Eligible for cache_, Edge TTL _Use cache-control header if present, bypass cache if not_, Browser TTL _Respect origin_:
164
66
 
165
- A CDN purge cannot clear visitor browser caches or downloaded files. Changed image bytes must get a new URL; never overwrite an existing variant to try to force an update. Ordinary text edits and publication require no purge or file movement.
67
+ ```text
68
+ (http.host eq "www.example.com" and starts_with(http.request.uri.path, "/_sandcms/media/") and http.request.uri.query eq "")
69
+ ```
166
70
 
167
- For rollback, bypass the public-media path and purge its cached URLs. Disabling the proxy also bypasses CDN delivery but does not clear existing browser copies. The application still serves images with the public browser-cache policy unless that policy is changed in code.
71
+ 2. **Private routes and query requests** — _Bypass cache_, ordered after broader rules:
168
72
 
169
- ## Staging verification
73
+ ```text
74
+ (http.host eq "www.example.com" and (http.request.uri.path eq "/admin" or starts_with(http.request.uri.path, "/admin/") or http.request.uri.path eq "/api/cms" or starts_with(http.request.uri.path, "/api/cms/") or http.request.uri.query ne ""))
75
+ ```
170
76
 
171
- Before production, run setup with a staging project name and authorized Wrangler login. Confirm account selection, collision handling, Worker/bucket ownership, secrets, deployed URL, and `worker update`. Exercise remote transformations with the chosen format/quality/size matrix, large and transparent images, SVG sanitization, retries, restart recovery, and rebuilds while published images stay live. Verify a real image larger than 20 MB and a 100 MB upload produce ready variants; check the 100 MP boundary and rejection above it. Confirm unsigned, expired, tampered, and wrong-asset source URLs fail, source responses are uncached, and failed transformations never expose originals as variants. Verify the remote path works on the actual deployed hostname; local tests cannot establish that Cloudflare’s production fetch and caching configuration is correct.
77
+ Do not use _Ignore cache-control header_: errors must stay uncached. Upload chunks go to `/api/cms/media/upload/…` and must not be cached or buffered; the second rule covers them. Behind Cloudflare, set the client IP header to `cf-connecting-ip`; see [client IP](deployment.md#client-ip-behind-a-reverse-proxy).
172
78
 
173
- Then enable proxy caching on a staging website hostname and complete the checks above. Local automated tests cover access checks, conditional requests, and headers; actual edge HIT behavior, rule precedence, purging, image quality, and production limits require this deployed verification. Record that evidence separately from local test results.
79
+ Unpublishing or deleting an image immediately denies new origin requests but does not recall cached copies. SandCMS does not purge the CDN. For deliberate removal, unpublish or delete first, then purge every affected variant URL (several sizes and formats per image). Never overwrite bytes under an existing URL to force an update; preset changes produce new URLs.
package/docs/content.md CHANGED
@@ -169,7 +169,7 @@ export const load = async (event) => {
169
169
  };
170
170
  ```
171
171
 
172
- `cms.read` returns `{ id, data }` or null. Without an authenticated `cmsPreview` request it reads only published data. Preview uses an entry ID and the existing session; it is not an anonymous token. The loader and hook set `private, no-store` and noindex. A draft can preview at a developer-defined path before publication. Do not prerender preview-aware routes or independently cache their draft data. Each route must opt in by calling the preview-aware loader.
172
+ `cms.read` returns `{ id, data }` or null. Without an authenticated `cmsPreview` request it reads only published data. Preview uses an entry ID and the existing session; it is not an anonymous token. The loader and hook set `private, no-store` and noindex; a route can call `cms.read` several times during one preview, and `cmsHandle` overrides any application `cache-control` on preview responses. A draft can preview at a developer-defined path before publication. Do not prerender preview-aware routes or independently cache their draft data. Each route must opt in by calling the preview-aware loader.
173
173
 
174
174
  Other server APIs:
175
175
 
@@ -233,7 +233,7 @@ File blueprints live alongside content blueprints, conventionally in `sandcms/bl
233
233
  id: image
234
234
  kind: file
235
235
  label: Image
236
- accept: [image/jpeg, image/png, image/webp, image/avif, image/gif, image/svg+xml]
236
+ accept: [image/jpeg, image/png, image/webp, image/avif, image/gif, image/tiff, image/svg+xml]
237
237
  fields:
238
238
  alt: { type: text, label: Alternative text }
239
239
  ```