diff --git a/README.md b/README.md index 23c4615..c08495a 100644 --- a/README.md +++ b/README.md @@ -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 /` (optional file `.ext`) [BUD-01](./buds/01.md#get-sha256---get-blob) - `HEAD /` (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/` [BUD-02](./buds/02.md#get-listpubkey---list-blobs-unrecommended) _(unrecommended)_ - `DELETE /` [BUD-02](./buds/02.md#delete-sha256---delete-blob) - `PUT /mirror` [BUD-04](./buds/04.md#put-mirror---mirror-blob) diff --git a/buds/02.md b/buds/02.md index 09f9947..ffb00b5 100644 --- a/buds/02.md +++ b/buds/02.md @@ -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. diff --git a/buds/04.md b/buds/04.md index 572a9bd..742c58f 100644 --- a/buds/04.md +++ b/buds/04.md @@ -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 diff --git a/buds/05.md b/buds/05.md index e0bdc4b..34fef20 100644 --- a/buds/05.md +++ b/buds/05.md @@ -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