Skip to content

Define conflict and reuse rules for custom upload keys - #2033

Open
Zetazzz wants to merge 6 commits into
mainfrom
codex/upload-key-conflict-contract
Open

Zetazzz wants to merge 6 commits into
mainfrom
codex/upload-key-conflict-contract

Conversation

@Zetazzz

@Zetazzz Zetazzz commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Uploading a file should return a reference to its contents. Once a file is confirmed, another upload must not change what its existing references read. For example, changing a site's logo means obtaining a reference to the new image and updating the site to use it. Uploading the image alone should leave the site unchanged.

The current custom-key flow already compares content hashes when checking for reuse. The problem is what happens on a mismatch: an upload can receive a write URL for a location already in use.

Proposed API contract

  • Within the same bucket, if a custom key names a confirmed file with the same content hash and the caller is authorized to reuse it, return its existing reference without issuing a write URL.
  • If the key is occupied by different content, reject the request without issuing a write URL. Knowing a key or a checksum does not grant access. Preserve existing authorization boundaries without disclosing details of inaccessible files.
  • A new upload must not overwrite a pending or confirmed original, or a system-generated derivative. Preserve checksum and upload-ID signing.
  • Until a business record explicitly switches references, it must keep reading the original content, whether the other upload succeeds, fails, or is still pending.

Implementation scope and concurrency

Keep the implementation in CNC. CNC DB changes and bucket policy changes are out of scope. If CNC can reliably detect that another upload already holds the same key in the same bucket, it should decline the competing request without issuing a write URL. Document which concurrent cases the implementation protects and which races remain with the existing database. Do not claim that a preflight check alone guarantees exclusive access across requests.

This is a design-only draft with an empty commit. It proposes no code, schema, or bucket policy changes. The implementation and the exact response for an in-flight duplicate are left open. No tests were run because there are no file changes.

@Zetazzz
Zetazzz marked this pull request as ready for review November 19, 2026 02:39
@luxor-code-review

luxor-code-review Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

Review complete. 🟠 2 high

💬 Inline comments (1)

  • 🟠 Content-addressed path skips the advisory lock entirely — plugin.ts:588
📍 Findings outside the diff (1) — 🟠 1 high — defects on lines GitHub can't attach comments to

🟠 High — Provisioned CORS rules omit If-None-Match, breaking browser PUTs · cors.ts:36–46 · file not in diff

// packages/bucket-provisioner/src/cors.ts
36	      allowedHeaders: [
37	        'Content-Type',
38	        'Content-Length',
39	        'Content-MD5',
40	        'x-amz-content-sha256',
41	        'x-amz-checksum-sha256',
42	        'x-amz-meta-upload-id',
43	        'x-amz-date',
44	        'x-amz-security-token',
45	        'Authorization',
46	      ],

The create-only presigned PUT now requires the client to send If-None-Match: * (signed via signableHeaders in graphile/graphile-presigned-url-plugin/src/s3-signer.ts:115), but the provisioned CORS rules omit it from allowedHeaders. If-None-Match is not a CORS-safelisted header, so a browser fetch PUT for a custom-key upload triggers a preflight that S3 answers without Access-Control-Allow-Headers: if-none-match, and the browser blocks the upload before it reaches S3. Every browser-based named upload fails even though the server-side flow and Node integration tests pass.


This PR lets clients reserve specific object keys in S3: the plugin now acquires pg_try_advisory_xact_lock, checks key occupancy, purges stale reservations, and records the file before issuing a presigned URL, while s3-signer.ts signs conditional PUTs with If-None-Match: * when createOnly is set. Seed data enables allow_custom_keys on the public bucket and the integration/unit tests cover reservation, conflict, and dedup liveness.

Files Change
graphile/graphile-presigned-url-plugin/src/plugin.ts Adds occupancy check, advisory locking, stale-reservation purge, uploadKeyConflict, and allow_custom_keys gating for both single and bulk upload paths
graphile/graphile-presigned-url-plugin/src/s3-signer.ts, src/types.ts, src/file-not-replaceable.ts, src/storage-file-recorder.ts Signs If-None-Match: * for create-only uploads, adds the conflict error class and createOnly/custom-key typing, exposes upload headers in the payload
graphile/graphile-presigned-url-plugin/__tests__/*, graphql/server-test/__tests__/upload.integration.test.ts Adds custom-key reservation/conflict unit tests, S3 signer integration tests, and end-to-end upload tests migrated to env-driven credentials
graphql/server-test/__fixtures__/seed/simple-seed-storage/test-data.sql Seeds allow_custom_keys = true for the public bucket

Reviewed commit: 01973e0

@luxor-code-review luxor-code-review Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adds custom-key upload reservations to the presigned-URL plugin via transaction-scoped advisory locks, create-only (If-None-Match) presigned PUTs, UPLOAD_KEY_CONFLICT semantics, and an allow_custom_keys bucket flag with matching seed and test coverage.

Key findings

  • 🟠 Content-addressed path skips the advisory lock entirely — plugin.ts:588
  • 🟠 Provisioned CORS rules omit If-None-Match, breaking browser PUTs — cors.ts:36

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant