File uploads and the image pipeline

D9 was "a user uploads a ten megabyte photo from their phone, and it is served to every visitor at ten megabytes". It is the most predictable performance problem in web software, it is never the thing anybody plans for, and it has a second half nobody mentions: that photo arrives with the GPS coordinates of the house it was taken in.

This chapter is what a file field does, what happens to an image between the form and the disk, and the two attacks that live in this feature.

A file field, and what it stores

grit generate resource Product \
  --fields "name:string, photo:file, gallery:files"

file is one, files is many. The column does not hold a path. It holds a structured reference:

{
  "url": "https://cdn.example.com/u/2026/10/x7f3.webp",
  "key": "u/2026/10/x7f3.webp",
  "name": "kitchen-final.jpg",
  "mime": "image/webp",
  "size": 147204,
  "width": 1600,
  "height": 1067,
  "thumbnail_url": ".../x7f3_thumb.webp",
  "format": "webp",
  "optimised": true
}

Where the bytes go

• S3, R2, Spaces
• Production. Any S3-compatible object store
• MinIO
• The same API, in Docker, for local development
• Local disk
• STORAGE_DRIVER=local. No object store at all

The local driver is the one to use while learning. It needs nothing running, and uploads land in a directory the API serves.

What happens to an image on the way in

Every image field runs through a profile. The default one is a set of decisions somebody would otherwise have to research:

func DefaultProfile() Profile {
    return Profile{
        Max:        Fit(1600, 1600),
        Quality:    0.82,
        Format:     Auto,
        Renditions: map[string]Size{"thumb": Fill(400, 400)},
        OnError:    StoreOriginal,
        MaxPixels:  50_000_000,
    }
}

• 1600
• Covers a 2x retina display at a typical content width. Storing more is paying to keep pixels no browser will draw
• 0.82
• The point at which JPEG is visually indistinguishable from source. Below about 0.75, gradients and skin show artifacts
• 400
• The thumbnail an admin row or a card grid needs at 2x
• Auto
• Encode to the best format the client can take, usually WebP

Measured on a 5.3 MB phone photo: 147 KB out, including the thumbnail. That is D9 closed, and it happened without anybody remembering to do it.

Three more things happen in the same pass, and two of them are not about size.

EXIF orientation is applied. A portrait photo from a phone is usually stored landscape with a rotation flag, and a naive decode produces a sideways thumbnail.

Metadata is stripped. Including GPS coordinates. A photograph taken at home and uploaded to a public listing carries the house's location in a field nobody looks at, and stripping it is not a feature request anybody files: it is something a framework should do by default.

Renditions are derived. The thumbnail comes from the decoded original rather than from the resized copy, so it is not a resize of a resize.

Your own profile, when the default is wrong

media.Define("product-image", media.Profile{
    Max:        media.Fit(2400, 2400),
    Quality:    0.9,
    Renditions: map[string]media.Size{
        "thumb": media.Fill(400, 400),
        "card":  media.Fit(800, 0),
    },
})

A clothing retailer wants more pixels and higher quality than a blog does. A document scan wants no lossy compression at all. The profile is the one place that decision lives, rather than being spread across the upload handler, the list page and whatever the mobile app does.

The chainable API is there when you need something bespoke:

img, err := media.Open(file)
thumb, err := img.Cover(150, 150).ToWebP().Encode()
large, err := img.Fit(1600, 0).Quality(80).ToJPEG().Encode()

An operation that fails does not panic and does not return its own error. The error travels down the chain and comes out of Encode or Store, which is what makes the chain readable.

The decompression bomb, which the size limit cannot see

MaxPixels: 50_000_000

This is the line that stops a specific attack, and it is worth understanding because the obvious defence does not work.

A solid-colour PNG compresses to almost nothing whatever its dimensions. *165 kilobytes on the wire can be 144 megapixels decoded.* Measured, one such upload allocated 224 MB, and ten concurrent uploads would have been 2.2 GB, which is the process gone.

Your file size limit cannot see it, because on disk the file is small. The header is read first, the pixel count is computed before any pixels are allocated, and an image claiming more than the profile allows is refused without being decoded.

When the pipeline fails

OnError: StoreOriginal

A transform that fails stores the original untouched and marks the refoptimised: false. The alternative, Reject, refuses the upload.

Storing a large image is a worse outcome than storing a small one, and both are much better than losing the user's file because your encoder did not like something. The failures are findable afterwards, and a reprocess pass can retry them.

Uploading from the frontend

The admin has a dropzone component, and the generated form uses it for anyfile or files field. Behind it is an ordinary multipart POST:

const body = new FormData()
body.append("file", file)

const res = await fetch(`${API}/api/v1/uploads`, {
  method: "POST",
  body,                       // no Content-Type header
  credentials: "include",
})

For very large files, the direct-to-storage path skips the API: the client asks for a presigned URL, uploads straight to the bucket, and tells the API the key. The image helpers run the same transform afterwards, so a presigned upload is not a way around the pipeline.

Serving them

Three things make the difference between a fast page and a slow one, and none of them is the upload:

Use the thumbnail in lists. A table of fifty rows showing full-size images is fifty megabytes for fifty thumbnails.

Give the browser the dimensions. They are in the ref, so pass them to the image component and the layout stops jumping.

Let the CDN cache it. Objects are content-addressed by key, so a long cache lifetime is safe: a changed image is a new key.

grit new gallery && cd gallery
grit generate resource Photo \
  --fields "caption:string, image:file, album:belongs_to:Album"
grit generate resource Album --fields "name:string"
grit migrate && grit start

exiftool kitchen.jpg | grep -i "gps\|orientation"

python -c "from PIL import Image; \
Image.new('RGB',(12000,12000),'blue').save('bomb.png')"

Assignment

Commit your work with the message Uploads - Assignment One, exactly as written, so the leaderboard can score it.