laantungir/blossom
1
0
Fork 0
mirror of https://github.com/hzrd149/blossom.git synced 2026-08-08 23:34:41 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add HTTP status codes to BUD-04

Browse Source
This commit is contained in:
hzrd149
2026-04-10 12:34:48 -05:00
parent 5d92ee621f
commit 183e1b3131
4 changed files with 25 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+2 -2
View File
@@ -22,7 +22,7 @@ BUDs or **Blossom Upgrade Documents** are short documents that outline an additi
- [BUD-03: User Server List](./buds/03.md)
- [BUD-04: Mirroring blobs](./buds/04.md)
- [BUD-05: Media optimization](./buds/05.md)
- [BUD-06: Upload requirements](./buds/06.md)
- [BUD-06: Upload requirements](./buds/06.md) _(moved to [BUD-02](./buds/02.md#head-upload---upload-requirements-optional))_
- [BUD-07: Payment required](./buds/07.md)
- [BUD-08: Nostr File Metadata Tags](./buds/08.md)
- [BUD-09: Blob Report](./buds/09.md)
@@ -36,7 +36,7 @@ Blossom Servers expose a few endpoints for managing blobs
- `GET /<sha256>` (optional file `.ext`) [BUD-01](./buds/01.md#get-sha256---get-blob)
- `HEAD /<sha256>` (optional file `.ext`) [BUD-01](./buds/01.md#head-sha256---has-blob)
- `PUT /upload` [BUD-02](./buds/02.md#put-upload---upload-blob)
- `HEAD /upload` [BUD-06](./buds/06.md#head-upload---upload-requirements)
- `HEAD /upload` [BUD-02](./buds/02.md#head-upload---upload-requirements-optional)
- `GET /list/<pubkey>` [BUD-02](./buds/02.md#get-listpubkey---list-blobs-unrecommended) _(unrecommended)_
- `DELETE /<sha256>` [BUD-02](./buds/02.md#delete-sha256---delete-blob)
- `PUT /mirror` [BUD-04](./buds/04.md#put-mirror---mirror-blob)
buds/02.md
-1
View File
@@ -65,7 +65,6 @@ Servers SHOULD use the following status codes for `PUT /upload` responses:
| `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.
buds/04.md
+23 -3
View File
@@ -19,8 +19,8 @@ Clients MUST pass the URL of the remote blob as a stringified JSON object in the
}
```
The endpoint MUST return a [Blob Descriptor](#blob-descriptor) and a `2xx` status code if the mirroring was successful
or a `4xx` status code and error message if it was not.
If the blob was newly mirrored and stored, the endpoint MUST respond with `201 Created` and a [Blob Descriptor](#blob-descriptor) in the response body.
If the blob already exists, the endpoint MUST respond with `200 OK` and a [Blob Descriptor](#blob-descriptor) in the response body.
The destination server SHOULD use the `Content-Type` header returned from the origin server to infer the mime type of
the blob. If the `Content-Type` header is not present the destination server SHOULD attempt to detect the `Content-Type`
@@ -28,7 +28,27 @@ from the blob contents and file extension, falling back to `application/octet-st
Servers MAY use the `Content-Length` header to determine the size of the blob.
Servers MAY reject a mirror 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 MAY reject a mirror request for any reason and MUST respond with the appropriate HTTP status code and an error message explaining the reason for the rejection.
### Status codes
Servers SHOULD use the following status codes for `PUT /mirror` responses:
| Status Code | Meaning |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `200 OK` | The blob already exists and the server is returning the existing [Blob Descriptor](./02.md#blob-descriptor). |
| `201 Created` | The blob was mirrored and stored successfully and the server is returning its [Blob Descriptor](./02.md#blob-descriptor). |
| `400 Bad Request` | The request body is malformed or the `url` is invalid. |
| `401 Unauthorized` | Authorization is required and missing or invalid. See [BUD-11](./11.md#endpoint-authorization-requirements). |
| `402 Payment Required` | Payment is required before mirroring can proceed. See [BUD-07](./07.md). |
| `403 Forbidden` | The request is understood but not allowed by server policy. |
| `409 Conflict` | The mirrored blob hash does not match the authorized `x` tag. |
| `413 Content Too Large` | The mirrored blob exceeds server size limits. |
| `415 Unsupported Media Type` | The mirrored blob type is not supported. |
| `429 Too Many Requests` | The client has exceeded a rate limit or quota. |
| `502 Bad Gateway` | The server could not fetch the blob from the origin URL or the origin response was unusable. |
If included, `X-Reason` MUST be treated as a human readable diagnostic message only and clients MUST NOT parse it for control flow.
### Upload Authorization
buds/05.md
-1
View File
@@ -33,7 +33,6 @@ Servers SHOULD use the following status codes for `PUT /media` responses:
| `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