Lesson 5 — Corrections to Lesson 4

What an adversarial review caught when checked against real httpkit source + GCS docs · a production incident
← Back to Lesson 4 · Reference →

Scorecard

Correction 1 — the "header conflict" was fiction

Lesson 4 said:

"Adding an Authorization header on top would conflict with GCS's own auth validation."

This is false on two counts, both verifiable in the actual httpkit source.

httpkit never auto-adds Authorization

handleOptions in httpkit/request/v2/request.go (in the wrapper source) only sets headers the caller explicitly passed via WithHeader:

// the wrapper source
func handleOptions(req *http.Request, opts *options) {
    if len(opts.headers) > 0 {
        req.Header = opts.headers   // only what the caller passed
    }
    if opts.username != "" || opts.password != "" {
        req.SetBasicAuth(opts.username, opts.password)
    }
}

No Authorization header would ever appear on a GCS request unless we explicitly sent one. The "conflict" scenario can't even arise.

What httpkit DOES inject — and why GCS doesn't care

// the wrapper source — runs on every request
otel.GetTextMapPropagator().Inject(ctx, propagation.HeaderCarrier(req.Header))
// adds: traceparent, tracestate

GCS ignores unknown request headers — traceparent and tracestate are simply not part of its signed policy, so they pass through harmlessly. There is no rejection, no 400, no conflict.

Correction 2 — GCS does not always return 204

Lesson 4 said:

"GCS pre-signed POST returns HTTP 204 or 200 with an empty body on success."

The real GCS behaviour, from the docs, depends on the success_action_status form field:

Our code discards the body unconditionally:

// download_and_upload_reserved.go
io.Copy(io.Discard, resp.Body)
return nil

What held up — and why it matters

Five claims survived. Two are worth re-stating because the review strengthened the evidence behind them:

Claim 5 — the limit+1 bug is real (confirmed via Go stdlib)

io.LimitReader(r, n) returns exactly n bytes when the underlying reader holds exactly n bytes, then EOF. So in the standard path:

n, _ := io.Copy(fw, io.LimitReader(body, limit))
if n == limit { /* reject */ }   // a file EXACTLY limit bytes is wrongly rejected

The reserved path's limit+1 with n > limit is the correct formulation. This is a genuine latent bug in DownloadAndUploadFile, confirmed not just by reading our code but by the documented semantics of io.LimitReader.

Claim 2 — "field order doesn't matter" is unverified, not proven

The GCS docs explicitly require the file field to be last. They do not document whether the order of the other (non-file) fields matters. Our code relies on Go's randomized map iteration for those fields and assumes order-independence. No evidence contradicts this in practice, but it is an assumption, not a documented guarantee. Flagging it as "safe because documented" (as Lesson 4 implied) overstated the certainty.

The meta-lesson