Skip to content

Latest commit

 

History

History
73 lines (50 loc) · 2.32 KB

06.md

File metadata and controls

73 lines (50 loc) · 2.32 KB

BUD-06

Upload requirements

draft optional

Defines how clients can verify if the upload can be completed before sending the blob to the server. This mechanism helps prevent unnecessary traffic to other endpoints by rejecting files based on their hash, size, MIME type or other server-specific requirements.

HEAD /upload - Upload requirements

The HEAD /upload endpoint MUST use the X-SHA-256, X-Content-Type and X-Content-Length headers sent by client to get the SHA-256 hash, MIME type and size of the blob that will be uploaded, returning a HTTP status code and a custom header X-Reason to indicate some human readable message about the upload requirements.

Headers

  • X-SHA-256: A string that represents the blob's SHA-256 hash.
  • X-Content-Length: An integer that represents the blob size in bytes.
  • X-Content-Type: A string that specifies the blob's MIME type, like application/pdf or image/png.

Upload Authorization

The HEAD /upload endpoint MAY accept an upload authorization event using the Authorization header similar to what is used in the PUT /upload endpoint

If the server requires authorization to upload it may respond with the 401 status code, or if authorization was provided and is invalid or not permitted it may respond with 403 status code

Examples

Example request from the client:

X-Content-Type: application/pdf
X-Content-Length: 184292
X-SHA-256: 88a74d0b866c8ba79251a11fe5ac807839226870e77355f02eaf68b156522576

Example response from the server if the upload can be done:

HTTP/1.1 200 OK

If the upload cannot proceed, the server MUST return an appropriate 4xx HTTP status code and a custom header X-Reason with a human readable error message.

Some examples of error messages:

HTTP/1.1 400 Bad Request
X-Reason: Invalid X-SHA-256 header format. Expected a string.
HTTP/1.1 401 Unauthorized
X-Reason: Authorization required for uploading video files.
HTTP/1.1 403 Forbidden
X-Reason: SHA-256 hash banned.
HTTP/1.1 411 Length Required
X-Reason: Missing X-Content-Length header.
HTTP/1.1 413 Content Too Large
X-Reason: File too large. Max allowed size is 100MB.
HTTP/1.1 415 Unsupported Media Type
X-Reason: Unsupported file type.