mirror of
https://github.com/hzrd149/blossom.git
synced 2026-10-30 09:47:33 +00:00
80 lines
4.6 KiB
Markdown
80 lines
4.6 KiB
Markdown
# BUD-02
|
|
|
|
## Blob upload and management
|
|
|
|
`draft` `optional`
|
|
|
|
_All pubkeys MUST be in hex format_
|
|
|
|
Defines the `/upload`, `/list` and `DELETE /<sha256>` endpoints
|
|
|
|
## 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](./01.md#get-sha256---get-blob) `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:
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
On success, the endpoint MUST respond with a `2xx` status code with a [Blob Descriptor](#blob-descriptor) in the response body.
|
|
On failure, the endpoint MUST return an appropriate `4xx` status code and an error message explaining the reason for the rejection.
|
|
|
|
### 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](./01.md#proxying-and-redirection-optional)), as external servers may rely on the file extension to serve the blob correctly.
|
|
|
|
### Upload Authorization (Optional)
|
|
|
|
Servers MAY require authorization when uploading blobs, as defined by [BUD-11](./11.md#endpoint-authorization-requirements).
|
|
|
|
## GET /list/pubkey - List Blobs (Unrecommended)
|
|
|
|
**Note:** The `/list` endpoint is optional and unrecommended. It is not necessary for all servers to implement the `/list` endpoint. Servers MAY implement this endpoint, but are not required to do so.
|
|
|
|
The `/list/<pubkey>` endpoint MUST return a JSON array of [Blob Descriptor](#blob-descriptor) that were uploaded by the specified pubkey
|
|
|
|
The endpoint MUST support `cursor` and `limit` query parameters for cursor based pagination. The `cursor` parameter MUST be the `sha256` hash of the last blob in the previous page, or omitted to request the first page. The `limit` parameter specifies the maximum number of results to return. The returned array of blob descriptors MUST be sorted by the `uploaded` date in descending order and MUST NOT include the blob at the cursor
|
|
|
|
The endpoint MAY support `since` and `until` query parameters to filter the list of blobs by their `uploaded` date. These parameters are deprecated for pagination purposes as they do not preserve server resources
|
|
|
|
Servers MAY reject a list request for any reason and MUST respond with the appropriate HTTP `4xx` status code and an error message explaining the reason for the rejection
|
|
|
|
### List Authorization
|
|
|
|
Servers MAY require authorization when listing blobs as defined by [BUD-11](./11.md#endpoint-authorization-requirements).
|
|
|
|
## DELETE /sha256 - Delete Blob
|
|
|
|
Servers MUST accept `DELETE` requests to the `/<sha256>` endpoint
|
|
|
|
Servers MAY reject a delete request for any reason and SHOULD respond with the appropriate HTTP `4xx` status code and an error message explaining the reason for the rejection
|
|
|
|
### Delete Authorization
|
|
|
|
Servers MAY require authorization when deleting blobs as defined by [BUD-11](./11.md#endpoint-authorization-requirements). **Multiple `x` tags in the authorization token MUST NOT be interpreted as the user requesting to delete multiple blobs.**
|