1---
2name: cdn
3description: serve content from the edge — content-addressed URLs, format negotiation, shadow branch rendering, and caching
4---
5
6# cdn
7
8sublimated serves content through a global CDN backed by content-addressed storage (CAS). every blob is immutable and cached aggressively at the edge.
9
10## content-addressed storage
11
12all content is stored by its BLAKE3 hash. same bytes = same hash = same URL forever. no cache invalidation needed — new content gets a new hash.
13
14upload content:
15```
16PUT https://api.sublimated.com/v1/spaces/{slug}/content
17Content-Type: application/octet-stream
18
19{raw bytes}
20```
21
22returns: `{ contentHash: "blake3-af13...", sha256Hash: "...", sizeBytes: 1234 }`
23
24download by hash:
25```
26GET https://api.sublimated.com/v1/spaces/{slug}/content/{hash}
27```
28
29check existence:
30```
31POST https://api.sublimated.com/v1/cas/check
32{ "hashes": ["blake3-af13...", "blake3-bc24..."] }
33```
34
35returns: `{ "have": [...], "missing": [...] }`
36
37## URL routing and format negotiation
38
39content is served at `sublimated.com/{space}/{path}` with format selection:
40
41explicit extension:
42- `/space/path/file.md` — raw markdown (CAS blob)
43- `/space/path/file.html` — rendered HTML (from shadow branch)
44- `/space/path/file.json` — AST JSON (from shadow branch parser)
45
46content negotiation (extensionless URLs):
47- `Accept: text/html` → rendered HTML
48- `Accept: text/markdown` → raw markdown
49- `Accept: application/json` → AST JSON
50- no Accept header → HTML (default)
51
52folder vs file conflict (`hello.md` + `hello/`):
53- `/hello` → the file (rendered as HTML)
54- `/hello/` (trailing slash) → folder index
55
56## shadow branch rendering
57
58the CDN resolves formats from shadow branches, computed automatically on push:
59
60- raw content → CAS blob via item's `contentHash`
61- rendered HTML → `refs/sbl/{branch}/html/{path}`
62- AST JSON → `refs/sbl/{branch}/markdown/{path}.ast.json`
63- metadata → `refs/sbl/{branch}/meta/{path}.json`
64
65shadow data is incremental — only changed items are reprocessed on push.
66
67## caching
68
69CAS blobs are cached at the edge using Cloudflare Cache API:
70- cache key = content hash (immutable, never invalidated)
71- TTL: 24h+ (content never changes, TTL only controls eviction)
72- per-colo caching: fills naturally as users access content from each location
73
74what is cached:
75- CAS blobs (API downloads and git clone)
76- materialized files (keyed by `materializedHash`)
77- git pack responses (keyed by ref + commit hash)
78
79what is NOT cached:
80- mutable data (item listings, space metadata, refs)
81- user-specific data (access rules, sessions, tokens)
82
83## large file uploads
84
85for files over 100MB, use presigned R2 upload:
86
87```
88POST https://api.sublimated.com/v1/spaces/{slug}/cas/presign
89```
90
91returns a presigned URL for direct R2 upload.
92
93## CDN URLs in feedback
94
95every write operation includes CDN URLs in the response:
96
97API response: `_meta.links.cdn: ["https://sublimated.com/space/path/file"]`
98
99git push: sideband line with view URL
100
101## see also
102
103- shadow-branches — how derived data is stored as orphan git refs
104- data-api — content upload and download endpoints
105- transforms — shadow branches that power format rendering
106- git-workflow — how pushes trigger CDN content updates