Multipart upload: Behavior and interfaces

Defines tenant-scoped resumable upload sessions with part checksums, expiry, complete-only-when-hash-matches, and abort cleanup so large files can resume without orphaned parts or cross-tenant keys.

Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.

Decision

Large uploads create a session with a tenant-scoped object key, an expiry, declared size, and a client-supplied object digest. Clients PUT numbered parts with per-part checksums. Complete succeeds only when parts are contiguous, limits in protocol.yaml are respected, and the concatenated digest matches. Abort or expiry deletes parts so incomplete data does not become a downloadable object. Session identifiers are not usable across tenants. Malware scanning of the published object is a related gate after complete. Authorized download of the published object is a related block.

Scope

• Session lifecycle, part limits, checksums, complete, abort, and sweeper.
• API behavior for large-file uploads in one tenant.
• Key layout {tenant_id}/uploads/{session_id}.

Outside this block

• Byte-range GET of published objects.
• Virus scanning and content-type policy after publish.
• Multipart protocols of a specific cloud vendor beyond the profile numbers.

Contract

• Sessions exist in the states listed in protocol.yaml; methods outside the allowed set fail closed.
• Parts outside min_part_bytes/max_part_bytes (except last part) are rejected; max_parts is 10000 in this profile.
• A part with a bad checksum_crc32c is not retained.
• POST_complete publishes only when parts are contiguous and SHA-256 matches object_sha256; otherwise upload_checksum_mismatch and state returns to open.
• Foreign-tenant session ids resolve as not_found with no part listing.
• Abort and expiry sweeper delete parts and prevent the key from being served as a completed object.

Implementation guidance

• Tenant checks live on session metadata, not inferred from object keys alone.
• Echo part numbers and checksums on status. Sweep expires_at even without abort.

Failure handling and safeguards

• Completing without a digest match never becomes completed. Missing object_sha256 refuses initiate.
• Expiry uses the store clock.

Verification and operations

• Tests: expiry, part checksum, object hash, cross-tenant hide, abort cleanup.
• Alert on sessions older than session_ttl_seconds. Profile sizes are not vendor defaults.

The executable-looking examples in this package are fixtures and acceptance contracts. Run python tools/validate.py from the collection root to check package structure and metadata; then implement and execute the scenarios in the target repository.

Adoption assumptions

• Names and numeric values in example.yaml are an adoption profile, not universal defaults.
• The adopting team must map actors, data classes, error vocabulary, and ownership to its system.

References

• No external normative source is required; this package defines a project decision.