Notable Learning.

/context

Context and role

/decision

The decision: designing the editor around its failure modes

The central piece of the product was the course editor for teachers: blocks of rich text, video, PDF and downloadable files, reorderable inside each lesson. I had built editors before — campaign modules and email templates in a financial system — and I knew where they break: not in the happy path, but at the edges. Before writing code, I presented to the team the three failure modes I had seen sink editors, and how I planned to design against them.

1. 01

   Perceived saving matters as much as actual saving

   A teacher who loses twenty minutes of work to an accidental reload or a dropped connection never trusts the product again. The save state had to be visible and honest: a discreet but always-present signal confirms when changes are safe, and toasts explain what happened when something fails — unexpected errors as part of the design, not as a patch added later.

2. 02

   Uploading files early creates orphans

   If every image is uploaded to the bucket at the moment the teacher inserts it, every abandoned draft leaves objects taking up storage forever. An explicit confirmation and cleanup strategy was needed.

3. 03

   An uploaded file is untrusted input

   Even if it comes from an authenticated user. Validation had to happen on the server and against the real content of the file, not against what the client says it is.

The team approved the approach and I implemented it. The final version of the file upload became a three-step flow that solves the three problems at once: an initiate route that issues a signed upload URL with the type and maximum size fixed cryptographically in the signature (enforced by GCS, not by the client), a direct upload from the browser to the bucket (the bytes never pass through the application server), and a finalize route that re-reads the first bytes of the object to validate on the server that the content is really a PDF, and deletes the object if validation fails — closing the door on orphans and on forged content at the same time.

/war

The war: the PDF that would not render

The bug that cost me the most time on the project looked trivial: PDFs uploaded by teachers did not show in the viewer. Blank screen. The confusing part was that images and videos, served by the same architecture — private bucket, authorized route, redirect to a signed URL — worked perfectly. The diagnosis turned out to be a chain of four stacked layers, where each fix uncovered the next one.

• layer 1

  Object metadata

  When a server delivers a file, the Content-Disposition header tells the browser what to do with it: inline means “display it in the page” and attachment means “download it”. GCS kept the attachment recorded at upload time, so the browser downloaded the PDF or navigated to it instead of showing it inside the lesson. The fix was to force inline when generating the signed URL, with filename sanitization so a malicious filename could not inject content into the header.

• layer 2

  CSP

  The Content Security Policy is an allowlist that declares which domains the application may communicate with; anything not on the list, the browser blocks. The little-known detail: when a request is redirected, the browser evaluates that list again against the final destination of the redirect, not only against the original URL. Our route redirected to the Google Cloud Storage domain, which was not on the list. It was a real and necessary fix — but it only moved the failure one step: from blocked by CSP to blocked by CORS.

• layer 3

  A hypothesis of mine that made things worse

  In an earlier attempt I had enabled withCredentials in the viewer — an option that tells the browser “include the cookies in this request” — with the theory that the viewer arrived without the session cookie. The theory was false, and the option had a hidden cost: when a request travels with cookies, the browser demands that every server in the chain respond with an explicit permission for credentialed requests, including GCS, which never sends it. My fix introduced a new blocker while trying to solve the original one. I had to undo my own change and verify it live against a real signed URL, watching the full negotiation pass in green. It looked solved. It wasn't.

• layer 4

  The root cause

  CORS is the mechanism the browser uses to decide whether a page may read data from another domain; every request carries an Origin header that identifies who makes it. The trap: react-pdf downloads the document with a fetch subject to CORS, and when that fetch is redirected to another domain, the specification forces the browser to replace the Origin with the word “null” — a deliberate mark of “this origin is no longer trustworthy after the redirect”. And no server can safely grant permission to “null”, because that same value is used by pages opened from local files and by sandboxed iframes. The request against the signed URL always died, no matter how correct the bucket configuration was. That is why images and videos never failed: img and video download their content in a relaxed mode (no-cors) where that rule does not apply.

/guards

Guards against regression

What remained is a test that explicitly asserts the absence of withCredentials — the most direct guard against repeating the failed attempt — a suite of 13 tests over the proxy route (ranges, conditionals, 304 responses without overwritten headers), server-side validation of the real file content, and upload limits enforced by the cryptographic signature instead of by the client.

Each failed attempt discarded a plausible hypothesis. The correct diagnosis was not visible until the upper layers were cleared.

/better

What I'd improve

The bucket CORS configuration lives outside the repository and is applied by hand per environment. A deploy to a new environment with an unconfigured bucket breaks the upload without any test detecting it. Today I would solve it with configuration as code from day one.

/closing

Closing

The project was delivered on time — June 12 — and the contract ended with the delivery. This project also produced the automated PR reviewer I built on Claude Code: the other half of this story.