laantungir/blossom
1
0
Fork 0
mirror of https://github.com/hzrd149/blossom.git synced 2026-10-05 15:38:22 +00:00
Code Issues Packages Projects Releases Wiki Activity

Make HTTP great again

Browse Source 
Add specific status codes to endpoints for clarity
This commit is contained in:
hzrd149
2026-04-06 11:18:28 -05:00
parent 234e0e01d3
commit 5d92ee621f
7 changed files with 232 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files
buds/01.md
+34 -4
View File
@@ -46,12 +46,26 @@ guarantee this are:
1. Proxying the blob through the Blossom server, allowing it to override headers such as `Content-Type`. 1. Proxying the blob through the Blossom server, allowing it to override headers such as `Content-Type`.
2. Manipulating the redirect URL to include a file extension that matches the blob type, such as `.pdf`, `.png`, etc. If 2. Manipulating the redirect URL to include a file extension that matches the blob type, such as `.pdf`, `.png`, etc. If
the server is unable to determine the MIME type of the blob, it MUST default to `application/octet-stream` and MAY the server is unable to determine the MIME type of the blob, it MUST default to `application/octet-stream` and MAY
include a file extension in the URL that reflects the blob type (e.g. `.bin`, `.dat`, etc.). include a file extension in the URL that reflects the blob type (e.g. `.bin`, `.dat`, etc.).
### Get Authorization (optional) ### Status codes
Servers MAY require authorization when retrieving blobs, as defined by [BUD-11](./11.md#endpoint-authorization-requirements). Servers SHOULD use the following status codes for `GET /<sha256>` responses:
| Status Code | Meaning |
| --------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `200 OK` | The blob exists and is returned in the response body. |
| `206 Partial Content` | The blob exists and the server is fulfilling a valid `Range` request. |
| `307 Temporary Redirect` | The blob is temporarily available from another URL containing the same sha256. |
| `308 Permanent Redirect` | The blob is permanently available from another URL containing the same sha256. |
| `400 Bad Request` | The sha256 path, optional file extension, or request headers are malformed. |
| `401 Unauthorized` | Authorization is required and missing or invalid. See [BUD-11](./11.md#endpoint-authorization-requirements). |
| `403 Forbidden` | The request is understood but not allowed by server policy. |
| `404 Not Found` | The blob does not exist. |
| `416 Range Not Satisfiable` | The blob exists but the requested byte range is invalid or outside the blob size. |
| `429 Too Many Requests` | The client has exceeded a rate limit or quota. |
| `503 Service Unavailable` | The retrieval service is temporarily unavailable. |
## HEAD /sha256 - Has Blob ## HEAD /sha256 - Has Blob
@@ -62,6 +76,22 @@ The endpoint MUST respond with the same `Content-Type` and `Content-Length` head
The endpoint MUST accept an optional file extension in the URL similar to the `GET /<sha256>` endpoint. ie. `.pdf`, `.png`, etc The endpoint MUST accept an optional file extension in the URL similar to the `GET /<sha256>` endpoint. ie. `.pdf`, `.png`, etc
### Status codes
Servers SHOULD use the following status codes for `HEAD /<sha256>` responses:
| Status Code | Meaning |
| ------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `200 OK` | The blob exists and the server returns the same metadata headers as `GET /<sha256>` without a response body. |
| `307 Temporary Redirect` | The blob is temporarily available from another URL containing the same sha256. |
| `308 Permanent Redirect` | The blob is permanently available from another URL containing the same sha256. |
| `400 Bad Request` | The sha256 path, optional file extension, or request headers are malformed. |
| `401 Unauthorized` | Authorization is required and missing or invalid. See [BUD-11](./11.md#endpoint-authorization-requirements). |
| `403 Forbidden` | The request is understood but not allowed by server policy. |
| `404 Not Found` | The blob does not exist. |
| `429 Too Many Requests` | The client has exceeded a rate limit or quota. |
| `503 Service Unavailable` | The retrieval service is temporarily unavailable. |
## Range requests ## Range requests
To better support mobile devices, video files, or low bandwidth connections. servers should support range requests ([RFC 7233 section 3](https://www.rfc-editor.org/rfc/rfc7233#section-3)) on the `GET /<sha256>` endpoint and signal support using the `accept-ranges: bytes` and `content-length` headers on the `HEAD /<sha256>` endpoint To better support mobile devices, video files, or low bandwidth connections. servers should support range requests ([RFC 7233 section 3](https://www.rfc-editor.org/rfc/rfc7233#section-3)) on the `GET /<sha256>` endpoint and signal support using the `accept-ranges: bytes` and `content-length` headers on the `HEAD /<sha256>` endpoint
buds/02.md
+88 -20
View File
@@ -1,12 +1,14 @@
# BUD-02 # BUD-02
## Blob upload and management ## Blob upload
`draft` `optional` `draft` `optional`
_All pubkeys MUST be in hex format_ _All pubkeys MUST be in hex format_
Defines the `/upload`, `/list` and `DELETE /<sha256>` endpoints Defines the `HEAD /upload` and `PUT /upload` endpoints.
The `/list/<pubkey>` and `DELETE /<sha256>` endpoints are defined in [BUD-12](./12.md).
## Blob Descriptor ## Blob Descriptor
@@ -36,44 +38,110 @@ Example:
## PUT /upload - Upload Blob ## PUT /upload - Upload Blob
The `PUT /upload` endpoint MUST accept binary data in the request body. 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. 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. 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. If the blob was newly stored, the endpoint MUST respond with `201 Created` and 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. If the blob already exists, the endpoint MUST respond with `200 OK` and a [Blob Descriptor](#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](#blob-descriptor). |
| `201 Created` | The blob was stored successfully and the server is returning its [Blob Descriptor](#blob-descriptor). |
| `400 Bad Request` | The request headers or body are malformed. |
| `401 Unauthorized` | Authorization is required and missing or invalid. See [BUD-11](./11.md#endpoint-authorization-requirements). |
| `402 Payment Required` | Payment is required before the upload can proceed. See [BUD-07](./07.md). |
| `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. |
| `507 Insufficient Storage` | The server cannot store the blob. |
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) ### 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. 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) ## HEAD /upload - Upload requirements (Optional)
Servers MAY require authorization when uploading blobs, as defined by [BUD-11](./11.md#endpoint-authorization-requirements). Servers MAY implement `HEAD /upload` as an optimization step before `PUT /upload`.
Clients can use it to avoid uploading blobs that would be rejected, and servers can use it to avoid receiving blobs that are already stored or would fail validation.
## GET /list/pubkey - List Blobs (Unrecommended) This pre-flight request is only an optimization. Clients MAY skip it entirely, and the result is not a guarantee of the eventual `PUT /upload` outcome because server state may change between requests.
**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 `HEAD /upload` endpoint MUST use the `X-SHA-256`, `X-Content-Type` and `X-Content-Length` headers sent by client to get the sha256 hash, MIME type and size of the blob that will be uploaded, returning an HTTP status code and an optional custom header `X-Reason` to indicate a human readable message about the upload requirements. Because `HEAD` responses do not include a message body, clients MUST determine the result from the status code and response headers alone.
The `/list/<pubkey>` endpoint MUST return a JSON array of [Blob Descriptor](#blob-descriptor) that were uploaded by the specified pubkey ### Headers
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 - `X-SHA-256`: A lowercase hex-encoded sha256 string that represents the blob's 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`.
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 ### Status codes
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 Servers SHOULD use the following status codes for `HEAD /upload` responses:
### List Authorization | Status Code | Meaning |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `200 OK` | The blob already exists on the server and the client MAY skip the `PUT /upload` request. |
| `204 No Content` | The upload would be accepted and the client MAY proceed with `PUT /upload`. |
| `400 Bad Request` | The request headers are malformed. |
| `401 Unauthorized` | Authorization is required and missing or invalid. See [BUD-11](./11.md#endpoint-authorization-requirements). |
| `402 Payment Required` | Payment is required before the upload can proceed. See [BUD-07](./07.md). |
| `403 Forbidden` | The request is understood but not allowed by server policy. |
| `411 Length Required` | A required `X-Content-Length` header is missing. |
| `413 Content Too Large` | The blob would exceed 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. |
| `503 Service Unavailable` | The upload service is temporarily unavailable. |
Servers MAY require authorization when listing blobs as defined by [BUD-11](./11.md#endpoint-authorization-requirements). If included, `X-Reason` MUST be treated as a human readable diagnostic message only and clients MUST NOT parse it for control flow.
## DELETE /sha256 - Delete Blob Clients that do not implement this optimization may still perform `PUT /upload` after receiving `200 OK`, and servers MUST handle that correctly.
Servers MUST accept `DELETE` requests to the `/<sha256>` endpoint ### Examples
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 Example request from the client:
### Delete Authorization ```http
X-Content-Type: application/pdf
X-Content-Length: 184292
X-SHA-256: 88a74d0b866c8ba79251a11fe5ac807839226870e77355f02eaf68b156522576
```
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.** Example response from the server if the blob already exists:
```http
HTTP/1.1 200 OK
```
Example response from the server if the upload may proceed:
```http
HTTP/1.1 204 No Content
```
If the upload cannot proceed, the server SHOULD return one of the status codes defined above. The server MAY include `X-Reason` with a human readable error message.
Some examples of error messages:
```http
HTTP/1.1 400 Bad Request
X-Reason: Invalid X-SHA-256 header format. Expected a string.
```
```http
HTTP/1.1 413 Content Too Large
X-Reason: File too large. Max allowed size is 100MB.
```
buds/05.md
+39 -3
View File
@@ -13,8 +13,27 @@ The server SHOULD perform any optimizations or conversions it deems necessary in
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. 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 success, the endpoint MUST respond with `200 OK` and 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. On failure, the endpoint MUST return an appropriate `4xx` or `5xx` status code and an error message explaining the reason for the rejection.
### PUT /media status codes
Servers SHOULD use the following status codes for `PUT /media` responses:
| Status Code | Meaning |
| ---------------------------- | -------------------------------------------------------------- |
| `200 OK` | The media was accepted, processed, and stored successfully. |
| `400 Bad Request` | The request headers or body are malformed. |
| `401 Unauthorized` | Authorization is required and missing or invalid. |
| `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 media exceeds server size limits. |
| `415 Unsupported Media Type` | The media type is not supported. |
| `422 Unprocessable Content` | The media is well-formed but cannot be processed successfully. |
| `429 Too Many Requests` | The client has exceeded a rate limit or quota. |
| `503 Service Unavailable` | The media processing service is temporarily unavailable. |
| `507 Insufficient Storage` | The server cannot store the processed media. |
### Upload Authorization ### Upload Authorization
@@ -22,7 +41,24 @@ Servers MAY require authorization when processing media as defined by [BUD-11](.
## HEAD /media ## HEAD /media
Servers MUST respond to `HEAD` requests on the `/media` endpoint in a similar way to the `HEAD /upload` endpoint defined in [BUD-06](./06.md) Servers MAY implement `HEAD /media` as an optimization step before `PUT /media`.
Clients can use it to avoid uploading media that would be rejected, and servers can use it to reject requests before receiving the full body.
The `HEAD /media` endpoint MUST use the `X-SHA-256`, `X-Content-Type` and `X-Content-Length` headers sent by client to get the sha256 hash, MIME type and size of the media 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.
Servers SHOULD use the following status codes for `HEAD /media` responses:
| Status Code | Meaning |
| ---------------------------- | ----------------------------------------------------------- |
| `200 OK` | The request is acceptable and the upload may proceed. |
| `400 Bad Request` | The request headers are malformed. |
| `401 Unauthorized` | Authorization is required and missing or invalid. |
| `403 Forbidden` | The request is understood but not allowed by server policy. |
| `411 Length Required` | A required `X-Content-Length` header is missing. |
| `413 Content Too Large` | The media would exceed server size limits. |
| `415 Unsupported Media Type` | The media type is not supported. |
| `429 Too Many Requests` | The client has exceeded a rate limit or quota. |
| `503 Service Unavailable` | The media processing service is temporarily unavailable. |
## Limitations ## Limitations
buds/06.md
+2 -64
View File
@@ -4,68 +4,6 @@
`draft` `optional` `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. The `HEAD /upload` endpoint definition has been merged into [BUD-02](./02.md#head-upload---upload-requirements-optional) so it lives next to `PUT /upload`.
## HEAD /upload - Upload requirements This optional preflight endpoint remains intended as an optimization so clients and servers can avoid uploading blobs that would be rejected or that already exist.
The `HEAD /upload` endpoint MUST use the `X-SHA-256`, `X-Content-Type` and `X-Content-Length` headers sent by client to get the sha256 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 lowercase hex-encoded sha256 string that represents the blob's 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
Servers MAY require authorization for this endpoint as defined by [BUD-11](./11.md#endpoint-authorization-requirements).
### Examples
Example request from the client:
```http
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
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
HTTP/1.1 400 Bad Request
X-Reason: Invalid X-SHA-256 header format. Expected a string.
```
```http
HTTP/1.1 401 Unauthorized
X-Reason: Authorization required for uploading video files.
```
```http
HTTP/1.1 403 Forbidden
X-Reason: SHA-256 hash banned.
```
```http
HTTP/1.1 411 Length Required
X-Reason: Missing X-Content-Length header.
```
```http
HTTP/1.1 413 Content Too Large
X-Reason: File too large. Max allowed size is 100MB.
```
```http
HTTP/1.1 415 Unsupported Media Type
X-Reason: Unsupported file type.
```
buds/07.md
+6 -8
View File
@@ -1,8 +1,6 @@
BUD-07 # BUD-07
======
Paid upload and download ## Paid upload and download
---------------
`draft` `optional` `draft` `optional`
@@ -14,11 +12,11 @@ Some servers MAY require payment for uploads, downloads, or any other endpoint.
Some endpoints a server may require payment for: Some endpoints a server may require payment for:
- [`HEAD /upload`](./06.md) to signal that payment is required for the `PUT` request ( if [BUD-06](./06.md) is supported ) - [`HEAD /upload`](./02.md#head-upload---upload-requirements-optional) to signal that payment is required for the `PUT` request ( if that optional endpoint is supported )
- [`PUT /upload`](./02.md#put-upload---upload-blob) to require payment for uploads - [`PUT /upload`](./02.md#put-upload---upload-blob) to require payment for uploads
- [`HEAD /<sha256>`](./01.md#head-sha256---has-blob) to signal that payment is required for the `GET` request - [`HEAD /<sha256>`](./01.md#head-sha256---has-blob) to signal that payment is required for the `GET` request
- [`GET /<sha256>`](./01.md#get-sha256---get-blob) to require payment for downloads ( maybe charge by MB downloaded? ) - [`GET /<sha256>`](./01.md#get-sha256---get-blob) to require payment for downloads ( maybe charge by MB downloaded? )
- [`HEAD /media`](./05.md) and [`PUT /upload`](./05.md) to require payment for media optimizations ( if [BUD-06](./06.md) is supported ) - [`HEAD /media`](./05.md) and [`PUT /upload`](./05.md) to require payment for media optimizations ( if the optional `HEAD /upload`-style preflight is supported )
When payment is required, the server MUST include one or more `X-{payment_method}` header(s), each corresponding to a supported payment method. When payment is required, the server MUST include one or more `X-{payment_method}` header(s), each corresponding to a supported payment method.
@@ -46,7 +44,7 @@ When using the X-Cashu header, the server MUST adhere to the [NUT-24](https://gi
Example for cashu: Example for cashu:
```http ```http
HTTP/1.1 402 Payment Required HTTP/1.1 402 Payment Required
X-Cashu: creqApWF0gaNhdGVub3N0cmFheKlucHJvZmlsZTFxeTI4d3VtbjhnaGo3dW45ZDNzaGp0bnl2OWtoMnVld2Q5aHN6OW1od2RlbjV0ZTB3ZmprY2N0ZTljdXJ4dmVuOWVlaHFjdHJ2NWhzenJ0aHdkZW41dGUwZGVoaHh0bnZkYWtxcWd5ZGFxeTdjdXJrNDM5eWtwdGt5c3Y3dWRoZGh1NjhzdWNtMjk1YWtxZWZkZWhrZjBkNDk1Y3d1bmw1YWeBgmFuYjE3YWloYjdhOTAxNzZhYQphdWNzYXRhbYF4Imh0dHBzOi8vbm9mZWVzLnRlc3RudXQuY2FzaHUuc3BhY2U X-Cashu: creqApWF0gaNhdGVub3N0cmFheKlucHJvZmlsZTFxeTI4d3VtbjhnaGo3dW45ZDNzaGp0bnl2OWtoMnVld2Q5aHN6OW1od2RlbjV0ZTB3ZmprY2N0ZTljdXJ4dmVuOWVlaHFjdHJ2NWhzenJ0aHdkZW41dGUwZGVoaHh0bnZkYWtxcWd5ZGFxeTdjdXJrNDM5eWtwdGt5c3Y3dWRoZGh1NjhzdWNtMjk1YWtxZWZkZWhrZjBkNDk1Y3d1bmw1YWeBgmFuYjE3YWloYjdhOTAxNzZhYQphdWNzYXRhbYF4Imh0dHBzOi8vbm9mZWVzLnRlc3RudXQuY2FzaHUuc3BhY2U
``` ```
@@ -71,7 +69,7 @@ The client MUST provide the payment proof when re-trying the request using the s
- For lightning the payment proof should be the preimage of the payment request according to [BOLT-11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md). - For lightning the payment proof should be the preimage of the payment request according to [BOLT-11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md).
Schema: Schema:
```http ```http
X-{payment_method}: "<encoded_payment_proof_according_to_{payment_method}_spec>" X-{payment_method}: "<encoded_payment_proof_according_to_{payment_method}_spec>"
``` ```
buds/11.md
+3 -3
View File
@@ -14,7 +14,7 @@ All authorization tokens:
- MUST have the `content` set to a human readable string explaining intended use to the user. For example `Upload Blob`, `Delete old blobs`, `List Images`, etc. - MUST have the `content` set to a human readable string explaining intended use to the user. For example `Upload Blob`, `Delete old blobs`, `List Images`, etc.
- MUST have a [NIP-40](https://github.com/nostr-protocol/nips/blob/master/40.md) `expiration` tag set to a unix timestamp at which the token should be considered expired. - MUST have a [NIP-40](https://github.com/nostr-protocol/nips/blob/master/40.md) `expiration` tag set to a unix timestamp at which the token should be considered expired.
- MUST have a `t` tag with a verb of `get`, `upload`, `list`, `delete`, or `media`. The value of the `t` tag MUST correspond to the action performed by the target endpoint, as defined in the section [Endpoint Authorization Requirements](#endpoint-authorization-requirements). - MUST have a `t` tag with a verb of `get`, `upload`, `list`, `delete`, or `media`. The value of the `t` tag MUST correspond to the action performed by the target endpoint, as defined in the section [Endpoint Authorization Requirements](#endpoint-authorization-requirements).
@@ -70,8 +70,8 @@ To validate an authorization token, a server MUST perform the following checks:
The table below defines, for each endpoint, the required `t` tag action, the implied blob hash (if any), and whether at least one matching `x` tag is required. The table below defines, for each endpoint, the required `t` tag action, the implied blob hash (if any), and whether at least one matching `x` tag is required.
| Endpoint | Required `t` | Implied Blob Hash | `x` Tag Requirement | | Endpoint | Required `t` | Implied Blob Hash | `x` Tag Requirement |
|----------------------|--------------|-------------------------------|---------------------| | -------------------- | ------------ | ---------------------------- | ------------------- |
| `GET /<sha256>` | `get` | `<sha256>` from the URL | optional | | `GET /<sha256>` | `get` | `<sha256>` from the URL | optional |
| `HEAD /<sha256>` | `get` | `<sha256>` from the URL | optional | | `HEAD /<sha256>` | `get` | `<sha256>` from the URL | optional |
| `PUT /upload` | `upload` | `X-SHA-256` request header | required | | `PUT /upload` | `upload` | `X-SHA-256` request header | required |
buds/12.md
+60
View File
@@ -0,0 +1,60 @@
# BUD-12
## Blob management endpoints
`draft` `optional`
_All pubkeys MUST be in hex format_
Defines the `/list/<pubkey>` and `DELETE /<sha256>` endpoints.
The [Blob Descriptor](./02.md#blob-descriptor) type is defined in [BUD-02](./02.md).
## 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](./02.md#blob-descriptor) objects 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.
### Status codes
Servers SHOULD use the following status codes for `GET /list/<pubkey>` responses:
| Status Code | Meaning |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `200 OK` | The list request succeeded and the response body contains an array of [Blob Descriptor](./02.md#blob-descriptor) objects. |
| `400 Bad Request` | The query parameters are malformed. |
| `401 Unauthorized` | Authorization is required and missing or invalid. See [BUD-11](./11.md#endpoint-authorization-requirements). |
| `402 Payment Required` | Payment is required before listing blobs. See [BUD-07](./07.md). |
| `403 Forbidden` | The request is understood but not allowed by server policy. |
| `429 Too Many Requests` | The client has exceeded a rate limit or quota. |
| `503 Service Unavailable` | The listing service is temporarily unavailable. |
If included, `X-Reason` MUST be treated as a human readable diagnostic message only and clients MUST NOT parse it for control flow.
## DELETE /sha256 - Delete Blob
Servers MUST accept `DELETE` requests to the `/<sha256>` endpoint.
### Status codes
Servers SHOULD use the following status codes for `DELETE /<sha256>` responses:
| Status Code | Meaning |
| ------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `200 OK` | The blob was deleted successfully and the response may include a body. |
| `204 No Content` | The blob was deleted successfully and the response body is empty. |
| `401 Unauthorized` | Authorization is required and missing or invalid. See [BUD-11](./11.md#endpoint-authorization-requirements). |
| `402 Payment Required` | Payment is required before deleting the blob. See [BUD-07](./07.md). |
| `403 Forbidden` | The request is understood but not allowed by server policy. |
| `404 Not Found` | The blob does not exist or is not available for deletion. |
| `429 Too Many Requests` | The client has exceeded a rate limit or quota. |
| `503 Service Unavailable` | The deletion service is temporarily unavailable. |
If included, `X-Reason` MUST be treated as a human readable diagnostic message only and clients MUST NOT parse it for control flow.
Multiple `x` tags in the authorization token MUST NOT be interpreted as the user requesting to delete multiple blobs.