Upload Finalization Contracts

This document captures the provider-direct portion of the upload finalization contract. The complete upload service still owns session-kind validation, quota accounting, verified blob finalization, retry behavior, and cleanup. This page records the storage-path rule that those flows must consume.

Provider Direct Resumable Upload

OneDrive and similar providers expose a stateful upload session. The browser uploads ranges to the provider URL; AsterDrive does not relay the data path.

Initialization

• The connector must select ProviderResumable(FrontendDirect) and the driver must expose provider_resumable with frontend_direct_upload = true.
• Fragment size must satisfy the provider minimum, maximum, and alignment constraints.
• create_frontend_upload_session(object_temp_key) receives an object path generated by nondedup_storage_path_for_policy().
• The object path comes from the policy connector descriptor:
  • opaque_uuid: files/{upload_id}
  • original_filename: files/{upload_id}/{normalized_filename}
• OneDrive declares original_filename, so the Graph item keeps the original filename and can return it from a direct download URL.
• Upload naming must not be inferred from ProviderResumable or DriverType inside upload services.
• The upload URL is a write credential and is encrypted in upload_sessions.provider_session_ciphertext.

Data Path

The browser sends PUT requests with Content-Range to the provider upload URL without AsterDrive credentials. The frontend follows next_expected_ranges; non-final fragments obey the provider alignment requirement. The provider completes the item after the final range.

Progress and Completion

Progress decrypts the provider session metadata and queries the provider session. Completion reads metadata from object_temp_key and verifies that the actual size equals session.total_size before verified blob finalization and database quota accounting.

Cleanup Matrix

Initialization and finalization must retain both provider resources and AsterDrive object paths:

abort provider upload session
delete object_temp_key / named OneDrive UUID namespace

The implementation must attempt abort and delete independently for:

Abort	Delete	Result
success	success	cleanup succeeds
failure	success	abort error is returned
success	failure	delete error is returned
failure	failure	both errors are retained

Database persistence failure, upload-id collision, session encryption failure, empty provider URL, and database finalization failure require the same explicit cleanup ownership.

Compatibility

Legacy OneDrive objects may use files/{upload_id}. They remain readable and deletable. In provider_native mode they can continue to use Graph direct download, which may expose the provider’s UUID filename; in strict_current mode the download service uses relay streaming so the current AsterDrive filename is applied. No legacy-name check is performed unless the administrator selects strict_current.

See Object Naming and OneDrive Direct Downloads for the full connector capability, path, and download acceptance matrix.