From c996e37aa67cd2c15e4becaca5cd12e7378aa95d Mon Sep 17 00:00:00 2001 From: hzrd149 Date: Sat, 11 Apr 2026 11:46:50 -0500 Subject: [PATCH] Clarify HEAD /media responses --- buds/05.md | 13 ++++++++++--- buds/07.md | 2 +- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/buds/05.md b/buds/05.md index a0d57b9..13d8a43 100644 --- a/buds/05.md +++ b/buds/05.md @@ -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. diff --git a/buds/07.md b/buds/07.md index e7a9eb9..81360e0 100644 --- a/buds/07.md +++ b/buds/07.md @@ -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 /`](./01.md#head-sha256---has-blob) to signal that payment is required for the `GET` request - [`GET /`](./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.