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

Clarify HEAD /media responses

Browse Source
This commit is contained in:
hzrd149
2026-04-11 11:46:50 -05:00
parent d02c5fc7dd
commit c996e37aa6
2 changed files with 11 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
buds/05.md
+10 -3
View File
@@ -42,17 +42,20 @@ Servers MAY require authorization when processing media as defined by [BUD-11](.
## HEAD /media
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.
Clients can use it to avoid uploading media that would be rejected, and servers can use it to evaluate whether a media-processing request would be accepted based on the supplied metadata and current server policy.
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 an HTTP status code and an optional custom header `X-Reason` to indicate a human readable message about the upload requirements.
This pre-flight request is only an optimization. Clients MAY skip it entirely, and the result is not a guarantee of the eventual `PUT /media` outcome because server state may change between requests.
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 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.
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. |
| `200 OK` | Based on the supplied headers and current server policy, the media-processing request would be accepted and the client MAY proceed with `PUT /media`. |
| `400 Bad Request` | The request headers are malformed. |
| `401 Unauthorized` | Authorization is required and missing or invalid. |
| `402 Payment Required` | Payment is required before the media-processing request 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 media would exceed server size limits. |
@@ -62,6 +65,10 @@ Servers SHOULD use the following status codes for `HEAD /media` responses:
If included, `X-Reason` MUST be treated as a human readable diagnostic message only and clients MUST NOT parse it for control flow.
Clients that do not implement this optimization may still perform `PUT /media` directly, and servers MUST handle that correctly.
After receiving `200 OK` from `HEAD /media`, clients MUST still be prepared for `PUT /media` to return either `200 OK` or `201 Created`, depending on how the media-processing result is handled by the server.
## Limitations
The goal of this endpoint is to provide a simple "trusted" optimization endpoint clients can use to optimize media for distribution.
buds/07.md
+1 -1
View File
@@ -16,7 +16,7 @@ Some endpoints a server may require payment for:
- [`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
- [`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 the optional `HEAD /upload`-style preflight is supported )
- [`HEAD /media`](./05.md) and [`PUT /media`](./05.md) to require payment for media optimizations ( if the optional `HEAD /media`-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.