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.
- package/README.md +14 -10
- package/dist/admin/Account.svelte +2 -0
- package/dist/admin/Admin.svelte +14 -1
- package/dist/admin/AssetAttachment.svelte +1 -3
- package/dist/admin/AssetAttachment.svelte.d.ts +0 -1
- package/dist/admin/BlueprintFields.svelte +0 -3
- package/dist/admin/BlueprintFields.svelte.d.ts +0 -1
- package/dist/admin/Editor.svelte +0 -1
- package/dist/admin/Fields.svelte +0 -7
- package/dist/admin/Fields.svelte.d.ts +0 -1
- package/dist/admin/Gallery.svelte +2 -6
- package/dist/admin/Gallery.svelte.d.ts +0 -1
- package/dist/admin/LinkField.svelte +0 -3
- package/dist/admin/LinkField.svelte.d.ts +0 -1
- package/dist/admin/MediaLibrary.svelte +10 -7
- package/dist/admin/MediaPicker.svelte +7 -15
- package/dist/admin/MediaPicker.svelte.d.ts +0 -1
- package/dist/admin/ThemePicker.svelte +72 -0
- package/dist/admin/ThemePicker.svelte.d.ts +18 -0
- package/dist/admin/UploadButton.svelte +2 -1
- package/dist/admin/UploadProgress.svelte +24 -0
- package/dist/admin/UploadProgress.svelte.d.ts +7 -0
- package/dist/admin/client.d.ts +3 -670
- package/dist/admin/client.js +2 -1
- package/dist/admin/components/ui/alert/alert.svelte.d.ts +3 -13
- package/dist/admin/components/ui/attachment/attachment-media.svelte.d.ts +3 -13
- package/dist/admin/components/ui/attachment/attachment.svelte.d.ts +6 -26
- package/dist/admin/components/ui/badge/badge.svelte.d.ts +7 -25
- package/dist/admin/components/ui/button/button.svelte.d.ts +15 -53
- package/dist/admin/components/ui/toggle/toggle.svelte.d.ts +6 -26
- package/dist/admin/generated/admin.css +529 -101
- package/dist/admin/theme-context.d.ts +7 -0
- package/dist/admin/theme-context.js +3 -0
- package/dist/admin/theme.d.ts +7 -0
- package/dist/admin/theme.js +14 -0
- package/dist/admin/types.d.ts +2 -1
- package/dist/admin/uploads.d.ts +8 -1
- package/dist/admin/uploads.js +94 -16
- package/dist/blueprints/files.js +1 -0
- package/dist/blueprints/load.js +7 -2
- package/dist/blueprints/types.d.ts +4 -1
- package/dist/cli/doctor.d.ts +3 -1
- package/dist/cli/doctor.js +85 -30
- package/dist/cli/files.d.ts +2 -6
- package/dist/cli/files.js +11 -2
- package/dist/cli/index.js +99 -31
- package/dist/cli/scaffold.js +8 -8
- package/dist/cli/setup.js +16 -26
- package/dist/cli/upgrade.js +21 -2
- package/dist/env.d.ts +32 -0
- package/dist/env.js +53 -3
- package/dist/server/admin-load.d.ts +13 -5
- package/dist/server/admin-load.js +6 -1
- package/dist/server/api-access.d.ts +4 -0
- package/dist/server/api-access.js +15 -2
- package/dist/server/api-pagination.d.ts +3 -0
- package/dist/server/api.js +5 -2
- package/dist/server/auth.d.ts +10 -9
- package/dist/server/cms.d.ts +65 -18
- package/dist/server/cms.js +62 -6
- package/dist/server/db/migration-data.js +4 -0
- package/dist/server/db/migrations/0009_local_media.sql +9 -0
- package/dist/server/db/migrations/meta/0009_snapshot.json +1763 -0
- package/dist/server/db/migrations/meta/_journal.json +7 -0
- package/dist/server/db/schema.d.ts +119 -2
- package/dist/server/db/schema.js +15 -3
- package/dist/server/hooks.js +155 -81
- package/dist/server/media/contracts.d.ts +115 -0
- package/dist/server/media/contracts.js +12 -0
- package/dist/server/media/deletions.d.ts +2 -1
- package/dist/server/media/deletions.js +3 -3
- package/dist/server/media/delivery.js +7 -11
- package/dist/server/media/import-r2.d.ts +56 -0
- package/dist/server/media/import-r2.js +342 -0
- package/dist/server/media/processor-child.d.ts +2 -0
- package/dist/server/media/processor-child.js +236 -0
- package/dist/server/media/processor.d.ts +51 -0
- package/dist/server/media/processor.js +135 -0
- package/dist/server/media/render-math.d.ts +24 -0
- package/dist/server/media/render-math.js +50 -0
- package/dist/server/media/runner.d.ts +30 -1
- package/dist/server/media/runner.js +418 -165
- package/dist/server/media/service.d.ts +56 -10
- package/dist/server/media/service.js +309 -98
- package/dist/server/media/storage.d.ts +5 -0
- package/dist/server/media/storage.js +279 -0
- package/dist/server/media/svg.d.ts +5 -0
- package/dist/server/media/svg.js +142 -0
- package/dist/server/media/upload-ticket.d.ts +12 -0
- package/dist/server/media/upload-ticket.js +35 -0
- package/dist/server/media/verify.d.ts +36 -0
- package/dist/server/media/verify.js +109 -0
- package/dist/server/platform/http.d.ts +27 -0
- package/dist/server/platform/http.js +77 -0
- package/dist/server/platform/index.d.ts +52 -0
- package/dist/server/platform/index.js +98 -0
- package/dist/server/platform/snapshots.d.ts +18 -0
- package/dist/server/platform/snapshots.js +110 -0
- package/dist/server/platform/volume.d.ts +20 -0
- package/dist/server/platform/volume.js +60 -0
- package/dist/worker/svg.d.ts +1 -5
- package/dist/worker/svg.js +2 -142
- package/docs/acceptance.md +6 -4
- package/docs/api.md +41 -3
- package/docs/cloudflare.md +48 -142
- package/docs/content.md +2 -2
- package/docs/deployment.md +159 -57
- package/docs/forms.md +1 -1
- package/docs/media.md +85 -21
- package/docs/package.md +21 -18
- package/docs/plans/0.7-self-hosted.md +264 -0
- package/docs/releases.md +17 -1
- package/docs/upgrades.md +35 -6
- package/package.json +36 -37
- package/templates/Dockerfile +28 -0
- package/templates/integration.ts +18 -2
- package/templates/railpack.json +1 -1
- package/templates/sandcms/blueprints/files/image.yaml +1 -1
- package/templates/sandcms/config.yaml +0 -1
- package/dist/cli/cloudflare.d.ts +0 -8
- package/dist/cli/cloudflare.js +0 -135
- package/templates/sandcms/worker/index.ts +0 -1
- package/templates/sandcms/worker/local.ts +0 -1
- 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
|
|
63
|
+
## Media uploads
|
|
64
64
|
|
|
65
|
-
|
|
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
|
-
|
|
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
|
|
package/docs/cloudflare.md
CHANGED
|
@@ -1,173 +1,79 @@
|
|
|
1
|
-
# Cloudflare
|
|
1
|
+
# Cloudflare: legacy import and optional CDN
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
7
|
+
## Import R2 media
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
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
|
|
14
|
+
bun x --no-install sandcms media import-r2
|
|
16
15
|
```
|
|
17
16
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
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
|
-
|
|
23
|
+
The token is never accepted as an argument. The import:
|
|
34
24
|
|
|
35
|
-
|
|
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
|
-
|
|
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
|
-
|
|
37
|
+
Then check the site and run:
|
|
40
38
|
|
|
41
|
-
|
|
42
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
52
|
+
Do not delete the bucket before step 3: until then it is the only off-server copy of the originals.
|
|
74
53
|
|
|
75
|
-
##
|
|
54
|
+
## Optional CDN caching
|
|
76
55
|
|
|
77
|
-
|
|
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: "
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
71
|
+
2. **Private routes and query requests** — _Bypass cache_, ordered after broader rules:
|
|
168
72
|
|
|
169
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
```
|