feat(storage): charge the OCI resume an admission unit, part 2 of 3 (upload-session-concurrency-cap plan: 12/12)

Stacked MRs

Part MR Scope LOC Target
1/3 !3315 (merged) CancelSession, the DELETE move, the resume's release 688 main
2/3 this MR turn the resume charge on 1053 main
3/3 !3317 (merged) handler tests and the e2e overfill 718 part 2

Merge order: !3315 (merged), then !3316 (merged), then !3317 (merged). Each is blocked by the one before.

!3317 (merged) needs a rebase onto 6181660d. Two of its test fakes must take the new purpose parameter, its gated stub should skip the acquire for a bodyless PUT, as the real store now does, and TestUploadDelete_CancelsWhileTheGateIsFull should stop expecting a bodyless PUT to shed.

Summary

Step 12, part 2 of 3. ResumeSession now takes one admission slot right before it opens the staging writer. So a docker push's PATCH requests, and any PUT that carries a final chunk, count against storage.max_concurrent_upload_sessions, and a full gate answers them 503 with a Retry-After (admission_source="oci_resume").

  • A miss, an expired row or another repository's id fails before the slot is taken.
  • Only a writable session keeps the slot. Every other path hands it back, D1b, D2a and D2b included.
  • A bodyless PUT only commits what earlier requests staged, so it takes no slot (ResumeToCommit), and a full gate never parks the last request of a push. Its session refuses Write and ReadFrom with ErrSessionCommitOnly.
  • The slot is taken before the writer opens, not on the first write, because the GCS writer fills a 256 KiB buffer when it resumes. A resume that waits at the gate holds no buffer.
  • A reservation works as on NewSession: an issued one is not charged again, a foreign one panics, on a bodyless commit too.
  • The floor warning now says that at a cap of 2, one docker push gets two of its five layer uploads.

Part 1 already moved DELETE off the resume, so a full gate cannot refuse a cancel.

Governing ADRs

  • ADR-003: this part makes the cap bound a push's layer uploads. No conflict: handbook!21493 merged on 2026-10-15 and removed ADR-003's cap paragraph, so ADR-003 carries no cap text and no longer gates this step.
  • ADR-004, ADR-011: no conflict.

Testing

  • New storage integration tests: a resume sheds at a full gate without opening a writer, the slot comes back on every path, failures before the acquire take no slot, a bodyless commit takes no slot at a full gate, the reservation rules, and a cancel at a full gate still tears the session down.
  • New OCI integration test: at a full gate a PATCH gets 503, then the bodyless PUT of the same session gets 201.
  • New conformance case, run on the stub and on Postgres: a commit-only session refuses Write and ReadFrom and still commits.
  • Every new branch and guard was mutation-checked: removing or inverting each one turns a test red.
  • Hooks pass. go vet -tags=integration is clean. golangci-lint --build-tags=integration finds nothing in this stack; its one finding is old, in internal/storage/driver/s3/driver_integration_test.go. The storage and OCI integration suites pass locally.
  • Checked at runtime on the full stack at 7b8235a5, before the bodyless-PUT change (S3 on MinIO, cap 1): PATCH and PUT at a full gate gave 503 and the shed counter rose, the slots gauge went back to 0, and at an 83MiB chunk size five concurrent PATCHes gave two accepted and three shed. Not re-run since: a bodyless PUT at a full gate now gets 201.
  • Not run yet: OCI conformance.
  • e2e: none here; part 3 adds the rows. docs/user: no change, troubleshooting.md already covers a push 503.

Plan and spec amendments

In the plan:

  • Steps 1 and 11: "5 MiB derives 18" is now 28, after !3047 (merged) and !3048 (merged).
  • Step 12: the old 64MiB S3 default is corrected.
  • Step 12: the rationale, the Acceptance line and the test-strategy line now say a bodyless PUT takes no slot. The rationale's "then cost nothing" was not true from the placement alone.
  • Naming Conventions: adds ResumePurpose and ErrSessionCommitOnly.
  • Dependencies: #1171 (closed) closed the S3-default gap. handbook!21493 merged on 2026-10-15 and removed the ADR-003 paragraph, so the Step 12 gate is discharged.

Size

1053 LOC: 146 code, 769 tests, 138 docs. Most of the tests are the acquire's integration cases. The bodyless-PUT commit (6181660d) changed 345 lines (72 code, 217 tests, 56 docs), most of it the new tests and the purpose parameter in 11 test fakes and the stub store.

Related to #1242 (closed)

Edited by Dzmitry (Dima) Meshcharakou

Merge request reports

Loading
Loading