Skip to content

02.md

Latest commit

 

History

History
73 lines (50 loc) · 4.76 KB

02.md

File metadata and controls

73 lines (50 loc) · 4.76 KB

BUD-02

Blob upload

draft optional

All pubkeys MUST be in hex format

Defines the PUT /upload endpoint.

The /list/<pubkey> and DELETE /<sha256> endpoints are defined in BUD-12.

Blob Descriptor

A blob descriptor is a JSON object containing url, sha256, size, type, and uploaded fields

  • url A publicly accessible URL to the BUD-01 GET /<sha256> endpoint with a file extension
  • sha256 The sha256 hash of the blob
  • size The size of the blob in bytes
  • type The MIME type of the blob (falling back to application/octet-stream if unknown)
  • uploaded The unix timestamp of when the blob was uploaded to the server

Servers MUST include a file extension in the URL in the url field to allow clients to easily embed the URL in social posts or other content

Servers MAY include additional fields in the descriptor like magnet, infohash, or ipfs depending on other protocols they support.

Example:

{
  "url": "https://cdn.example.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf",
  "sha256": "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553",
  "size": 184292,
  "type": "application/pdf",
  "uploaded": 1725105921
}

PUT /upload - Upload Blob

The PUT /upload endpoint MUST accept binary data in the request body. The server MUST NOT modify the blob in any way and MUST compute the sha256 hash over the exact bytes received. This requirement ensures that users can re-upload blobs to other servers without discrepancies.

Clients SHOULD include Content-Type and Content-Length headers specifying the MIME type and size of the data. Clients MAY provide an X-SHA-256 header containing the lowercase hex-encoded sha256 of the request body. A server MAY use this value to enforce rejection policies or perform authorization checks prior to persisting the blob.

If the blob was newly stored, the endpoint MUST respond with 201 Created and a Blob Descriptor in the response body. If the blob already exists, the endpoint MUST respond with 200 OK and a Blob Descriptor in the response body.

Servers MUST handle uploads correctly regardless of whether the client performed a HEAD /upload request first.

Status codes

Servers SHOULD use the following status codes for PUT /upload responses:

Status Code Meaning
200 OK The blob already exists and the server is returning the existing Blob Descriptor.
201 Created The blob was stored successfully and the server is returning its Blob Descriptor.
400 Bad Request The request headers or body are malformed.
401 Unauthorized Authorization is required and missing or invalid. See BUD-11.
402 Payment Required Payment is required before the upload can proceed. See BUD-07.
403 Forbidden The request is understood but not allowed by server policy.
409 Conflict The provided X-SHA-256 does not match the request body.
411 Length Required A required Content-Length header is missing.
413 Content Too Large The blob exceeds server size limits.
415 Unsupported Media Type The blob type is not supported.
429 Too Many Requests The client has exceeded a rate limit or quota.

If included, X-Reason MUST be treated as a human readable diagnostic message only and clients MUST NOT parse it for control flow.

File extension normalization (Optional)

When storing blobs, servers MAY normalise the file extension to a standard format (e.g. .pdf, .png, etc.) based on the MIME type of the blob. This can be especially useful when the GET /<sha256> endpoint is redirected to an external URL (see the proxying and redirection section from BUD-01), as external servers may rely on the file extension to serve the blob correctly.
⚡