Technical Manual sections
Reference › Technical Manual › Uploads
Kitten parses request bodies with @small-web/kitten-busboy, its own fork of express-busboy. Each HTTP route parses its own body, after Polka has chosen it, with a parser that createBodyParser() in src/lib/body.ts creates from kitten-busboy’s parser(). It parses URL-encoded, JSON, and multipart bodies into request.body, adds request.rawBody for a body that isn’t multipart (e.g., to validate a webhook’s signature), and writes uploaded files to the app’s uploads/ folder. The parser marks the request (parsingStarted), so a request is parsed at most once, and a request that no route responds to is never parsed.
Only routes that require sign-in or export
authorisestore files. A post route accepts uploads when it requires sign-in (🔒) or exportsauthorise, in the app or in Kitten’s internal web app. For any other request, Kitten parses the fields and discards the files, and kitten-busboy records the number of files it discarded inrequest.discardedFiles.Limits. Each parser resolves each limit from the route’s
uploadLimitsexport, thenkitten.uploadLimits, then the default inDEFAULT_UPLOAD_LIMITS(src/lib/uploadLimits.ts), skipping a value that isn’t a number. It reads them on every request. Kitten checks thekitten.uploadLimitsobject at start-up and each route’suploadLimitsexport when the route loads (see Initialisation (asynchronous) and Other HTTP routes). When a request goes over a limit, the body parser discards all files in the request, setsrequest.limit, and passes the request on. A POST route then calls itsonUploadLimitexport, if it has one, for the limits a person can exceed (fileSize,files,fieldSize, andbody). For any other limit, or when there is noonUploadLimitexport, the route throws anUploadLimitError(src/lib/uploadLimits.ts), and the error handler responds to it with a 413 page. Its log line mentions where the limit is set: the route’suploadLimitsexport, thekitten.uploadLimitsobject, or Kitten’s default. (See Other HTTP routes for the other route types.)Records. PostRoute creates an
Uploadobject for each file, exposes them asrequest.uploads, and stores each one inkitten._db.uploads, anUploadscollection keyed by upload id (src/Uploads.ts). Each entry ofrequest.uploadsis the object that JSDB stores, so a route that setsupload.public = trueon it persists the change. A new upload’spublicproperty isfalse.Serving. The
downloadHandler()function in src/Uploads.ts serves /uploads/<id>/ with theContent-Security-Policy: sandboxheader. It serves PNG, JPEG, GIF, WebP, and AVIF images, audio, video, and plain text inline, and every other type (including SVG images) as an attachment. It serves every type as an attachment at /uploads/<id>/download/ (Upload.downloadPath). It serves an upload whosepublicproperty is exactlytrueto anyone, with theAccess-Control-Allow-Origin: *header from the CORS middleware. It serves any other upload only to a signed-in session, with theCache-Control: privateheader and noAccess-Control-Allow-Originheader, and refuses anyone else withrequireSignIn(), as the route handler does for a 🔒 route.Existing uploads. The first time
InternalDatabase.initialise()opens the internal database withoutkitten._db.settings.existingUploadsMadePublic, it marks every upload public, apart from restore archives that earlier versions of Kitten left in the uploads store (uploads from thedataBackupFilefield), which contain the internal database. It then setsexistingUploadsMadePublic, so it never marks uploads public again.
Source code: