Storage

Public images on Cloudflare R2: an upload kind per image an owner has (an avatar, a logo), one hardened upload route, safe serving, and cleanup when owners or images go.

The kit stores public images in a Cloudflare R2 bucket (STORAGE), for the user or organization that owns them: an avatar, a logo. You describe each image as an upload kind; the kit does the rest:

  • POST /api/uploads/<kind> takes one image, checks it, re-encodes it and points the owner at it.
  • DELETE /api/uploads/<kind> clears it.
  • GET /api/files/<key> serves it to anyone with the URL.
  • Deleted owners' images are purged, and leftovers are swept weekly.

The app ships with one kind, user-avatar (the user's picture, uploaded from Profile). Add yours: Adding an Upload Kind.

Images Are Public to Anyone With the URL

A stored image is served without a session, to anyone who has its URL. URLs are unguessable (/api/files/<kind>/<ownerId>/<random uuid>.webp) and nothing lists them, but anyone you share a URL with, or who sees it in a page, can load it. Storage is for images you'd show on a profile or in a header, never for private files (documents, receipts, attachments): those need a session-checked download route, which this does not provide.

What Happens to an Upload

In this order, each step before any later one runs:

  1. Rate limits (uploads: 10 a minute per visitor; uploadsAll: 300 a minute for everyone).
  2. Signed in.
  3. The kind exists.
  4. The caller may write it: a user kind is always the caller's own image; an organization kind needs the kind's permission in the caller's active organization.
  5. The body: at most the kind's maxBytes (2 MB by default), exactly one file field. Nothing above reads it.
  6. The bytes are a PNG, JPEG or WebP (by their contents, never the file name or declared type), at most 4096 pixels a side and 2048 × 2048 pixels in all, not animated.
  7. Re-encoded to lossless WebP, shrunk to the kind's maxDimension (512 by default), never upscaled. Only the pixels survive: EXIF, GPS and anything else in the file are gone.
  8. Stored under a new key; the owner column moves to it only if nobody changed it since step 1; then the old image is deleted.

The owner is always taken from the session (the user, or the verified active organization), never from the request.

Answers

StatusBody codeWhen
200{ "url": "/api/files/…" }Stored; the owner points at url
204Removed (also when there was nothing to remove)
400invalid_requestNo file, an empty one, several, a text field, a broken or abandoned body
400unsupported_typeNot a PNG, JPEG or WebP (SVG, GIF, HTML…)
400too_large_dimensionsOver 4096 px a side or 2048 × 2048 px in all
400animated_not_supportedAn animated WebP
400invalid_imageThe file can't be decoded
401unauthenticatedSigned out
403forbiddenAn organization kind with no active organization, or without the kind's permission
404unknown_kindNo such kind
404not_foundThe owner was deleted meanwhile
409conflictAnother upload or removal for the same owner won the race; try again
413too_largeOver the kind's maxBytes
429RATE_LIMITEDOver a rate limit (Retry-After says when to come back)
500storage_unavailableR2 or the database failed; nothing changed
503unboundThe Worker has no STORAGE bucket (Running Storage)

Known Limits

  • EXIF orientation is ignored by the server. A phone JPEG that is sideways in its pixels and upright only through its EXIF tag is stored sideways when posted directly. @kit/storage/client redraws an image it has to shrink, which applies the rotation; one that already fits goes up as it is.
  • A replaced image may still show in a browser that cached the old URL until the page using the owner's URL reloads; the new image has a new URL.
  • Lossless WebP only: a 512 px photo is about 150–300 KB.