Media¶
Purpose¶
The media domain (backend/internal/services/media/) is the client-facing edge for external media handling. It has three independent surfaces:
- Upload starters — issue short-lived presigned PUT URLs so the frontend uploads assets straight to S3, keeping backend egress out of the hot path.
- Klipy client config — delivers the Klipy API key, a per-user customer id and the ads flag to the signed-in client, which calls Klipy directly.
- Link-preview proxy — an SSRF-guarded, Redis-cached fetcher for Open Graph metadata used to render link cards.
The heavy asset lifecycle (key generation, per-kind MIME gating, size caps, the sync/async delete split, and key↔URL translation) lives in the platform-tier asset service, backend/internal/platform/assets/. The upload starters are thin handlers that delegate to it; other domains finalise uploads by verifying the returned key before persisting it.
Surface area¶
Routes are registered by backend/internal/services/media/routes.go and mounted in internal/wiring/router.go. Gates are passed in as func(http.Handler) http.Handler middleware.
| Group | Registrar | Gate |
|---|---|---|
/api/v1/uploads/* |
RegisterUploadRoutes |
JWT + email-verified |
/api/v1/klipy/* |
RegisterKlipyRoutes |
JWT + age-verified |
/api/v1/link-preview |
RegisterLinkPreviewRoute |
JWT + email-verified |
Upload starters¶
Every starter POSTs a { "content_type": "image/..." } body and returns { "key": "...", "upload_url": "https://..." }. The client PUTs the bytes to upload_url, then submits key back to the kind-specific finalise endpoint, which calls assets.AssertUploaded before mutating its model. upload_url is presigned with a short TTL (config.ObjectStorage.SignedURLTTL, default 30 minutes) and binds both Content-Type and the per-kind size cap into the signature, so S3 rejects a mismatched MIME or an oversized body.
| Endpoint | Asset kind | Finalise on |
|---|---|---|
POST /uploads/avatar |
AssetAvatar |
PUT /users/me/avatar |
POST /uploads/group-avatar |
AssetGroupAvatar |
PUT /dm/rooms/{id}/avatar (needs room_id) |
POST /uploads/chat-image |
AssetChatImage |
chat WebSocket message image_keys (needs room_id) |
POST /uploads/chat-image/batch |
AssetChatImage × N |
chat WebSocket message (one presign per content_types[i], capped at chat.MaxChatImagesPerMessage) |
POST /uploads/moment |
AssetMoment |
POST /moments |
POST /uploads/item-image |
AssetItemImage |
image_keys on POST /items or POST /items/{id}/photos |
POST /uploads/support-screenshot |
AssetSupportScreenshot |
screenshot_key on POST /support/cases |
POST /uploads/event-cover |
AssetEventCover |
cover_image on POST / PATCH /events |
POST /uploads/plan-cover |
AssetPlanCover |
cover_image_key on PATCH /plans/{id} |
Check-ins carry no artifact, so they never presign anything; POST /checkins takes its fields directly.
Klipy client config¶
Klipy requires API and media requests to come from the end user's device, so the backend does not proxy GIF traffic. KlipyHandler (klipy_handler.go) only hands the signed-in client what it needs to call https://api.klipy.com/api/v1/{key}/... itself.
| Method | Path | Returns |
|---|---|---|
| GET | /klipy/config |
{ads_enabled, api_key, customer_id} (Cache-Control: private, no-store) |
api_keyis the server-heldklipy.api_key(KLIPY_API_KEY). It is delivered at runtime so it is never baked into a build, and is never logged. With no key configured the endpoint returns503.customer_idis a stable, non-reversible per-user id: a truncated HMAC-SHA256 of the user id keyed by the API key. The client sends it to Klipy ascustomer_idand in the recent-endpoint path.ads_enabledisklipy.ads_enabled(truein eachconfig.<env>.yaml;KLIPY_ADS_ENABLED=falseturns ads off without a release) and the request's country not being in the EEA, the United Kingdom or Switzerland, where ads need consent. The country is Cloudflare'sCF-IPCountryheader, read only when the transport peer is a trusted proxy (api.FromTrustedProxy, the same CIDR policy as the client IP). A missing or unknown country (XX,T1, local dev) follows the flag.
The route group is JWT plus age-verified. The client holds the config in memory for the session (API client).
Link-preview proxy¶
LinkPreviewHandler (link_preview_handler.go) fetches Open Graph metadata for a URL and returns LinkPreviewResult (title, description, image, url, domain). GET /link-preview?url=<https-url>.
- SSRF defense. Only
httpsschemes are accepted; the hostname is resolved and any private / loopback / link-local IP is rejected. The shared SafeClient resolves and re-rejects non-public IPs at dial time, defeating DNS rebinding. - Caching. Results are cached in Redis under
link-preview:<sha256(url)>for 1 hour (viaplatform/cache). - Body cap. The response body is read with a 64 KB limit; OG tags are matched against both attribute orderings, falling back to
<title>. - Graceful miss. On fetch error or when nothing useful is found, the handler returns
200with anullbody so the client simply skips the card.
Asset model (platform tier)¶
The upload starters produce keys owned by assets.Service in backend/internal/platform/assets/assets.go. AssetKind is the closed enum of writable asset types; each maps to exactly one storage.Prefix, owns a MIME allowlist, a size cap, and a key-scoping rule.
AssetKind |
value | storage.Prefix |
MIME set | Size cap | Key scoping |
|---|---|---|---|---|---|
AssetAvatar |
avatar |
avatars/ |
image | 5 MB | owner-prefixed |
AssetGroupAvatar |
group-avatar |
group-avatars/ |
image | 5 MB | flat |
AssetChatImage |
chat-image |
chat-images/ |
image + HEIC | 10 MB | nested (chat-images/<room_id>/…) |
AssetMoment |
moment |
moments/ |
image + HEIC | 15 MB | owner-prefixed |
AssetEventCover |
event-cover |
event-covers/ |
image | 15 MB | flat |
AssetPlanCover |
plan-cover |
plan-covers/ |
image | 15 MB | flat |
AssetItemImage |
item-image |
item-images/ |
image + HEIC | 15 MB | owner-prefixed |
AssetSupportScreenshot |
support-screenshot |
support-screenshots/ |
image + HEIC | 10 MB | owner-prefixed, private (Tomoda accounts read it through signed URLs); starter limited to 10 per hour per account |
AssetGeoCoverSubmission |
geo-cover-submission |
geo-cover-submissions/ |
jpeg, png | 15 MB | owner-prefixed; starter limited to 10 per hour per account |
AssetStamp |
stamp |
stamps/ |
image | 20 MB | flat (curated) |
AssetStampBespoke |
stamp-bespoke |
stamps/bespoke/ |
image | 20 MB | flat (curated) |
AssetCurio |
curio |
curios/ |
image | 20 MB | flat (curated) |
The two MIME sets are imageMIMEs (jpeg, png, gif, webp) and imageMIMEsWithHEIC (+ heic, heif). HEIC is reserved for capture-flow kinds (chat images, moments, item images) where iOS native uploads land; picker-UI kinds stay on the narrower set.
Key vs. URL¶
Models persist only the key, either in an AssetKey column or inside a JSONB envelope (chat-image keys live under chat_messages metadata). URLs compose on read via storage.PublicURL, which delegates to assets.Service.URLFromKey (wired at boot with storage.SetPublicURLFunc so models/ stays free of services imports). This decouples persisted data from CDN domain / bucket changes. URLFromKey passes any input containing :// through unchanged, so OAuth picture URLs (Google / Apple) can share the same column.
Write + verify¶
| Method | Role |
|---|---|
IssueUploadURL |
Returns (key, uploadURL); the standard client path. Signs Content-Type + size cap into the presigned PUT. |
AssertUploaded |
Called by each finalise endpoint before persisting: re-checks the key's prefix, owner-scoping, and HEADs the object to confirm it exists under the cap. Defends against a client submitting someone else's key. |
UploadRaw |
Server-internal upload from an io.Reader (sim seeds, generated avatars). |
Delete¶
| Entry | Semantics | When |
|---|---|---|
Delete |
Synchronous; blocks until S3 returns. | Replace flows (avatar rotation) where the old key must be gone before the new one is persisted. |
EnqueueDelete |
Pushes a cleanup task to the Asynq queue; returns once Redis acknowledges. Failed deletes retry, then surface via the admin DLQ inspector. |
Hard-delete cascades (user deletion, moment purge) where the DB transaction must not block on S3. |
Both accept a raw key or a stored URL and refuse keys whose prefix IsCurated() (anything under stamps/, stamps/bespoke/, curios/), so user-facing code can never wipe an admin-managed stamp or curio. The async delete handler re-checks the same guard on dequeue.
Where to look¶
backend/internal/services/media/upload_handler.go— presigned upload startersbackend/internal/services/media/klipy_handler.go— Klipy client configbackend/internal/services/media/link_preview_handler.go— OG metadata proxy + SSRF guardbackend/internal/services/media/routes.go— route registrationbackend/internal/platform/assets/assets.go—Service,AssetKind,kindSpecs, delete policybackend/internal/storage/prefixes.go—Prefixenum,IsCurated,PublicURLwiringbackend/internal/storage/s3_storage.go—PresignPut(binds Content-Type + size into the signature)backend/internal/async/handlers/cleanup.go— async-side curated-prefix re-checkfrontend/services/presignedUpload.ts,klipyService.ts,linkPreviewService.ts— the frontend clients
Confirm (AssertUploaded) also reads the first bytes of the stored object and deletes it when they are not a supported image format.