mirror of
https://github.com/hzrd149/blossom.git
synced 2026-09-13 22:25:06 +00:00
Define POST mirroring and endpoint discovery
This commit is contained in:
hzrd149
@@ -37,7 +37,8 @@ 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 /<sha256>` [BUD-13](./buds/13.md#put-sha256---upload-blob) _(also supports remote source URLs)_
|
||||
- `PUT /<sha256>` [BUD-13](./buds/13.md#put-sha256---upload-blob)
|
||||
- `POST /<sha256>` [BUD-13](./buds/13.md#post-sha256---mirror-blob) _(optional mirroring)_
|
||||
- `HEAD /upload` [BUD-06](./buds/06.md#head-upload---upload-requirements-optional)
|
||||
- `GET /list/<pubkey>` [BUD-12](./buds/12.md#get-listpubkey---list-blobs-unrecommended) _(unrecommended)_
|
||||
- `DELETE /<sha256>` [BUD-12](./buds/12.md#delete-sha256---delete-blob)
|
||||
|
||||
+49
-1
@@ -11,10 +11,50 @@ _All pubkeys MUST be in hex format_
|
||||
Servers MUST set the `Access-Control-Allow-Origin: *` header on all responses to ensure compatibility with applications hosted on other domains.
|
||||
|
||||
For [preflight](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#preflighted_requests) (`OPTIONS`) requests,
|
||||
servers MUST also set, at minimum, the `Access-Control-Allow-Headers: Authorization, *` and `Access-Control-Allow-Methods: GET, HEAD, PUT, DELETE` headers.
|
||||
servers MUST also set, at minimum, the `Access-Control-Allow-Headers: Authorization, *` header.
|
||||
|
||||
Servers MUST set `Access-Control-Allow-Methods` as described in [Feature discovery](#feature-discovery).
|
||||
|
||||
The header `Access-Control-Max-Age: 86400` MAY be set to cache the results of a preflight request for 24 hours.
|
||||
|
||||
## Feature discovery
|
||||
|
||||
Independent operations that use the same resource path SHOULD use distinct HTTP methods when possible. When an endpoint feature is identified by an HTTP method, servers MUST advertise support for that feature through the method lists defined below. Clients MUST NOT be required to submit the operation and inspect its error response or `X-Reason` value to determine whether the method is supported.
|
||||
|
||||
Clients MAY send `OPTIONS` to a specific endpoint path to discover the features supported for that endpoint. Servers MUST respond to `OPTIONS` for every recognized endpoint path, even when the resource identified by the path does not exist. Servers MAY respond with either `200 OK` or `204 No Content` and MUST NOT include a response body.
|
||||
|
||||
A successful `OPTIONS` response MUST include both of the following headers:
|
||||
|
||||
- `Allow`: The complete list of HTTP methods the server currently supports for the target endpoint.
|
||||
- `Access-Control-Allow-Methods`: The same list of supported methods, allowing browser clients to use CORS preflight responses for feature discovery.
|
||||
|
||||
Servers MUST include `OPTIONS` in both method lists. Servers MUST include methods for optional features only when those features are supported for the target endpoint. For example, a server supporting direct uploads and mirroring on `/<sha256>` as defined in [BUD-13](./13.md) would return:
|
||||
|
||||
```http
|
||||
HTTP/1.1 204 No Content
|
||||
Allow: GET, HEAD, PUT, POST, DELETE, OPTIONS
|
||||
Access-Control-Allow-Methods: GET, HEAD, PUT, POST, DELETE, OPTIONS
|
||||
Access-Control-Allow-Headers: Authorization, *
|
||||
Access-Control-Expose-Headers: Allow
|
||||
Access-Control-Allow-Origin: *
|
||||
```
|
||||
|
||||
A server supporting direct uploads but not mirroring would omit `POST`:
|
||||
|
||||
```http
|
||||
HTTP/1.1 204 No Content
|
||||
Allow: GET, HEAD, PUT, DELETE, OPTIONS
|
||||
Access-Control-Allow-Methods: GET, HEAD, PUT, DELETE, OPTIONS
|
||||
```
|
||||
|
||||
Servers MUST include `Access-Control-Expose-Headers: Allow` on `OPTIONS` responses so browser clients can inspect the `Allow` header.
|
||||
|
||||
Clients MUST treat a method as unsupported when `OPTIONS` does not return a successful response or when the method is absent from either advertised method list.
|
||||
|
||||
When a server recognizes an HTTP method but does not support it for the target endpoint, it MUST respond with `405 Method Not Allowed` and MUST include an `Allow` header containing the methods currently supported for that endpoint.
|
||||
|
||||
The advertised methods describe endpoint capabilities only. They do not guarantee that a specific request will be accepted. Servers MAY still reject a request because of authorization, payment, rate limits, storage limits, media type restrictions, or other server policies.
|
||||
|
||||
## Error responses
|
||||
|
||||
Every time a server sends an error response (HTTP status codes >=400), it MAY include a human-readable header `X-Reason` that can be displayed to the user.
|
||||
@@ -32,6 +72,10 @@ The endpoint MUST accept an optional file extension in the URL. ie. `.pdf`, `.pn
|
||||
Regardless of the file extension, the server MUST return the MIME type of the blob in the `Content-Type` header. If the
|
||||
server does not know the MIME type of the blob, it MUST default to `application/octet-stream`
|
||||
|
||||
### Checking support
|
||||
|
||||
Clients SHOULD send `OPTIONS /<sha256>` using any syntactically valid hash. Blob retrieval is supported when both `Allow` and `Access-Control-Allow-Methods` include `GET`; the hash does not need to identify an existing blob.
|
||||
|
||||
### Proxying and Redirection (Optional)
|
||||
|
||||
If the endpoint returns a redirection 3xx status code such as 307 or 308 ([RFC 9110 section
|
||||
@@ -76,6 +120,10 @@ 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
|
||||
|
||||
### Checking support
|
||||
|
||||
Clients SHOULD send `OPTIONS /<sha256>` using any syntactically valid hash. Blob metadata checks are supported when both `Allow` and `Access-Control-Allow-Methods` include `HEAD`; clients MUST NOT interpret a `404` response to `HEAD /<sha256>` as lack of endpoint support.
|
||||
|
||||
### Status codes
|
||||
|
||||
Servers SHOULD use the following status codes for `HEAD /<sha256>` responses:
|
||||
|
||||
@@ -48,6 +48,10 @@ If the blob already exists, the endpoint MUST respond with `200 OK` and a [Blob
|
||||
|
||||
Servers MUST handle uploads correctly regardless of whether the client performed a `HEAD /upload` request first.
|
||||
|
||||
### Checking support
|
||||
|
||||
Clients SHOULD send `OPTIONS /upload` as defined in [BUD-01](./01.md#feature-discovery). This legacy upload endpoint is supported when both `Allow` and `Access-Control-Allow-Methods` include `PUT`; the presence of `HEAD` alone only indicates support for [BUD-06](./06.md).
|
||||
|
||||
### Status codes
|
||||
|
||||
Servers SHOULD use the following status codes for `PUT /upload` responses:
|
||||
|
||||
+1
-1
@@ -31,7 +31,7 @@ The `.content` field is not used.
|
||||
|
||||
When uploading blobs clients MUST attempt to upload the blob to at least the first `server` listed in the users server list.
|
||||
|
||||
Optionally clients MAY upload the blob to all the servers or mirror the blob to the other servers if they support [BUD-04](./04.md)
|
||||
Optionally clients MAY upload the blob to all the servers or mirror the blob to other servers using [`POST /<sha256>` from BUD-13](./13.md#post-sha256---mirror-blob) when supported.
|
||||
|
||||
This ensures that the blob is available in multiple locations in the case one of the servers goes offline.
|
||||
|
||||
|
||||
+5
-1
@@ -6,7 +6,7 @@
|
||||
|
||||
Defines the `/mirror` endpoint.
|
||||
|
||||
New clients and servers SHOULD use the remote source upload mode of [`PUT /<sha256>` from BUD-13](./13.md#remote-source-upload) instead. That flow uses the blob hash in the URL, supports one or more remote source URLs, and reuses the same [BUD-11](./11.md) `upload` authorization token that a direct `PUT /<sha256>` upload uses.
|
||||
New clients and servers SHOULD use [`POST /<sha256>` from BUD-13](./13.md#post-sha256---mirror-blob) instead. That flow uses the blob hash in the path, accepts one or more HTTP URLs or [BUD-10](./10.md) Blossom URIs in the request body, cleanly separates mirroring from direct uploads, and reuses the same [BUD-11](./11.md) `upload` authorization token that a direct `PUT /<sha256>` upload uses.
|
||||
|
||||
## PUT /mirror - Mirror Blob
|
||||
|
||||
@@ -32,6 +32,10 @@ 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 status code and an error message explaining the reason for the rejection.
|
||||
|
||||
### Checking support
|
||||
|
||||
Clients SHOULD send `OPTIONS /mirror` as defined in [BUD-01](./01.md#feature-discovery). This legacy mirroring endpoint is supported when both `Allow` and `Access-Control-Allow-Methods` include `PUT`; new clients SHOULD still prefer `POST /<sha256>` when available.
|
||||
|
||||
### Status codes
|
||||
|
||||
Servers SHOULD use the following status codes for `PUT /mirror` responses:
|
||||
|
||||
+9
-1
@@ -16,6 +16,10 @@ Clients SHOULD include `Content-Type` and `Content-Length` headers specifying th
|
||||
On success, the endpoint MUST respond with either `200 OK` or `201 Created` and a [Blob Descriptor](#blob-descriptor) in the response body. Clients MUST treat both status codes as successful media creation.
|
||||
On failure, the endpoint MUST return an appropriate `4xx` or `5xx` status code and an error message explaining the reason for the rejection.
|
||||
|
||||
### Checking support
|
||||
|
||||
Clients SHOULD send `OPTIONS /media` as defined in [BUD-01](./01.md#feature-discovery). Media processing is supported when both `Allow` and `Access-Control-Allow-Methods` include `PUT`; the presence of `HEAD` separately indicates support for the optional acceptance check below.
|
||||
|
||||
### PUT /media status codes
|
||||
|
||||
Servers SHOULD use the following status codes for `PUT /media` responses:
|
||||
@@ -48,6 +52,10 @@ This pre-flight request is only an optimization. Clients MAY skip it entirely, a
|
||||
|
||||
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.
|
||||
|
||||
### Checking support
|
||||
|
||||
Clients SHOULD send `OPTIONS /media` as defined in [BUD-01](./01.md#feature-discovery). The media acceptance check is supported when both `Allow` and `Access-Control-Allow-Methods` include `HEAD`; support for `PUT /media` alone does not imply support for this optimization.
|
||||
|
||||
Servers SHOULD use the following status codes for `HEAD /media` responses:
|
||||
|
||||
| Status Code | Meaning |
|
||||
@@ -82,4 +90,4 @@ Clients MAY let a user selected a "trusted processing" server for uploading imag
|
||||
|
||||
Once a server has been selected, the client uploads the original media to the `/media` endpoint of the trusted server and get the optimized blob back.
|
||||
|
||||
Then the client can call the `/mirror` endpoint on other servers to distribute the blob.
|
||||
Then the client can call [`POST /<sha256>` from BUD-13](./13.md#post-sha256---mirror-blob) on other servers to distribute the blob.
|
||||
|
||||
@@ -19,6 +19,10 @@ Clients that want to check whether a blob already exists on the server SHOULD us
|
||||
|
||||
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.
|
||||
|
||||
### Checking support
|
||||
|
||||
Clients SHOULD send `OPTIONS /upload` as defined in [BUD-01](./01.md#feature-discovery). This acceptance check is supported when both `Allow` and `Access-Control-Allow-Methods` include `HEAD`; support for `PUT /upload` does not imply support for this optimization.
|
||||
|
||||
### Headers
|
||||
|
||||
- `X-SHA-256`: A lowercase hex-encoded sha256 string that represents the blob's hash.
|
||||
|
||||
@@ -14,6 +14,7 @@ Some endpoints a server may require payment for:
|
||||
|
||||
- [`HEAD /upload`](./06.md#head-upload---upload-requirements-optional) to signal that payment is required for the `PUT /<sha256>` request ( if that optional endpoint is supported )
|
||||
- [`PUT /<sha256>`](./13.md#put-sha256---upload-blob) to require payment for uploads
|
||||
- [`POST /<sha256>`](./13.md#post-sha256---mirror-blob) to require payment for mirroring
|
||||
- [`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 /media`](./05.md) to require payment for media optimizations ( if the optional `HEAD /media`-style preflight is supported )
|
||||
|
||||
+2
-2
@@ -4,13 +4,13 @@
|
||||
|
||||
`draft` `optional`
|
||||
|
||||
Describes how a server could return nostr [NIP-94 File Metadata](https://github.com/nostr-protocol/nips/blob/master/94.md) tags from the `PUT /<sha256>` and `/mirror` endpoints
|
||||
Describes how a server could return nostr [NIP-94 File Metadata](https://github.com/nostr-protocol/nips/blob/master/94.md) tags from the `PUT /<sha256>`, `POST /<sha256>`, and legacy `/mirror` endpoints
|
||||
|
||||
### Returning tags
|
||||
|
||||
As described in [BUD-02](./02.md#blob-descriptor) servers MAY add any additional fields to a blob descriptor
|
||||
|
||||
Servers MAY return an additional `nip94` field in the [blob descriptor](./02.md#blob-descriptor) from the `PUT /<sha256>` or `/mirror` endpoints
|
||||
Servers MAY return an additional `nip94` field in the [blob descriptor](./02.md#blob-descriptor) from the `PUT /<sha256>`, `POST /<sha256>`, or legacy `/mirror` endpoints
|
||||
|
||||
The `nip94` field should contain a JSON array with KV pairs as defined in [NIP-94](https://github.com/nostr-protocol/nips/blob/master/94.md)
|
||||
|
||||
|
||||
@@ -28,6 +28,10 @@ The clients can include `e` or `p` tags to point to the event or the profile tha
|
||||
|
||||
Server MUST respond to a report request with a success code or a code in the 4xx/5xx range if there was any error.
|
||||
|
||||
#### Checking support
|
||||
|
||||
Clients SHOULD send `OPTIONS /report` as defined in [BUD-01](./01.md#feature-discovery). Blob reporting is supported when both `Allow` and `Access-Control-Allow-Methods` include `PUT`.
|
||||
|
||||
### Client behavior
|
||||
|
||||
The clients can show a blob report button on posts or in blob details. Or its RECOMMENDED to merge this with normal nostr report and send it to both relays and blossom server. other clients can receive it from relays and hide or blur reported blob from trusted friends.
|
||||
|
||||
@@ -75,6 +75,7 @@ The table below defines, for each endpoint, the required `t` tag action, the imp
|
||||
| `GET /<sha256>` | `get` | `<sha256>` from the URL | optional |
|
||||
| `HEAD /<sha256>` | `get` | `<sha256>` from the URL | optional |
|
||||
| `PUT /<sha256>` | `upload` | `<sha256>` from the URL | required |
|
||||
| `POST /<sha256>` | `upload` | `<sha256>` from the URL | required |
|
||||
| `HEAD /upload` | `upload` | `X-SHA-256` request header | required |
|
||||
| `DELETE /<sha256>` | `delete` | `<sha256>` from the URL | required |
|
||||
| `GET /list/<pubkey>` | `list` | — | not applicable |
|
||||
|
||||
@@ -20,6 +20,10 @@ The endpoint MUST support `cursor` and `limit` query parameters for cursor based
|
||||
|
||||
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.
|
||||
|
||||
### Checking support
|
||||
|
||||
Clients SHOULD send `OPTIONS /list/<pubkey>` with a syntactically valid hex pubkey as defined in [BUD-01](./01.md#feature-discovery). Listing is supported when both `Allow` and `Access-Control-Allow-Methods` include `GET`, but remains optional and unrecommended when available.
|
||||
|
||||
### Status codes
|
||||
|
||||
Servers SHOULD use the following status codes for `GET /list/<pubkey>` responses:
|
||||
@@ -40,6 +44,10 @@ If included, `X-Reason` MUST be treated as a human readable diagnostic message o
|
||||
|
||||
Servers MUST accept `DELETE` requests to the `/<sha256>` endpoint.
|
||||
|
||||
### Checking support
|
||||
|
||||
Clients SHOULD send `OPTIONS /<sha256>` using any syntactically valid hash as defined in [BUD-01](./01.md#feature-discovery). Deletion is supported when both `Allow` and `Access-Control-Allow-Methods` include `DELETE`; this does not guarantee that the caller may delete a particular blob.
|
||||
|
||||
### Status codes
|
||||
|
||||
Servers SHOULD use the following status codes for `DELETE /<sha256>` responses:
|
||||
|
||||
+85
-34
@@ -10,52 +10,33 @@ This document supersedes the `PUT /upload` endpoint definition from [BUD-02](./0
|
||||
|
||||
Servers that implement this document MAY continue to support the `PUT /upload` endpoint from [BUD-02](./02.md) for compatibility.
|
||||
|
||||
Defines the `PUT /<sha256>` endpoint.
|
||||
Defines the `PUT /<sha256>` and `POST /<sha256>` endpoints.
|
||||
|
||||
The [Blob Descriptor](./02.md#blob-descriptor) type is defined in [BUD-02](./02.md).
|
||||
|
||||
The `<sha256>` path segment MUST be a lowercase hex-encoded sha256 hash of the blob being stored.
|
||||
|
||||
## PUT /sha256 - Upload Blob
|
||||
|
||||
The `PUT /<sha256>` endpoint MUST accept binary data in the request body.
|
||||
The `<sha256>` path segment MUST be a lowercase hex-encoded sha256 hash of the blob being stored.
|
||||
|
||||
When the request body is binary data, 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.
|
||||
|
||||
For binary uploads, clients SHOULD include `Content-Type` and `Content-Length` headers specifying the MIME type and size of the blob.
|
||||
Clients SHOULD include `Content-Type` and `Content-Length` headers specifying the MIME type and size of the blob.
|
||||
|
||||
If the computed sha256 of a binary request body does not match the `<sha256>` path segment, the server MUST reject the request with `409 Conflict` and MUST NOT persist the blob.
|
||||
If the computed sha256 of the request body does not match the `<sha256>` path segment, the server MUST reject the request with `409 Conflict` and MUST NOT persist the blob.
|
||||
|
||||
### Remote Source Upload
|
||||
|
||||
Servers MAY also accept one or more `url` query parameters that tell the server to fetch the blob from remote URLs instead of receiving the blob bytes in the request body. This rolls the mirroring flow from [BUD-04](./04.md) into the same path-addressed upload endpoint and allows clients to reuse the same [BUD-11](./11.md) `upload` authorization token as long as at least one `x` tag matches the `<sha256>` path.
|
||||
|
||||
When one or more `url` query parameters are present, the request body MUST be empty and servers MUST ignore `Content-Type` and `Content-Length` as blob metadata. If a client sends both `url` query parameters and a non-empty request body, servers MUST reject the request with `400 Bad Request`.
|
||||
|
||||
To provide a single remote source, clients MUST send one `url` query parameter:
|
||||
|
||||
```http
|
||||
PUT /b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553?url=https%3A%2F%2Fcdn.example.com%2Fb1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf
|
||||
```
|
||||
|
||||
To provide multiple remote sources, clients MUST repeat the `url` query parameter:
|
||||
|
||||
```http
|
||||
PUT /b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553?url=https%3A%2F%2Fcdn-a.example.com%2Fb1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf&url=https%3A%2F%2Fcdn-b.example.com%2Fb1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf
|
||||
```
|
||||
|
||||
Remote source URLs MUST be URL-encoded absolute `http` or `https` URLs. Servers MUST reject requests that include invalid `url` parameters with `400 Bad Request`.
|
||||
|
||||
When multiple `url` query parameters are provided, servers MAY try any or all of the URLs in any order. Servers MUST only store the blob if the sha256 hash of the fetched bytes matches the `<sha256>` path segment. If the fetched blob hash does not match the `<sha256>` path segment, the server MUST reject the request with `409 Conflict` and MUST NOT persist the blob.
|
||||
|
||||
The destination server SHOULD use the `Content-Type` header returned from the successful origin response 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` from the blob contents and file extension, falling back to `application/octet-stream` if it cannot determine the type.
|
||||
|
||||
Servers MAY use the origin `Content-Length` header to reject blobs that exceed server size limits before downloading the full response.
|
||||
Servers MUST reject `PUT /<sha256>` requests containing one or more `url` query parameters with `400 Bad Request`. Remote source references are only accepted in the request body of `POST /<sha256>`.
|
||||
|
||||
If the blob was newly stored, the endpoint MUST respond with `201 Created` and a [Blob Descriptor](./02.md#blob-descriptor) in the response body.
|
||||
If the blob already exists, the endpoint MUST respond with `200 OK` and a [Blob Descriptor](./02.md#blob-descriptor) in the response body.
|
||||
|
||||
Servers MUST handle uploads correctly regardless of whether the client performed a `HEAD /upload` request first.
|
||||
|
||||
### Checking support
|
||||
|
||||
Clients SHOULD send `OPTIONS /<sha256>` using any syntactically valid hash as defined in [BUD-01](./01.md#feature-discovery). Path-based uploads are supported when both `Allow` and `Access-Control-Allow-Methods` include `PUT`; the presence or absence of `POST` independently indicates mirroring support.
|
||||
|
||||
### Status codes
|
||||
|
||||
Servers SHOULD use the following status codes for `PUT /<sha256>` responses:
|
||||
@@ -64,20 +45,90 @@ Servers SHOULD use the following status codes for `PUT /<sha256>` responses:
|
||||
| ---------------------------- | ------------------------------------------------------------------------------------------------------------ |
|
||||
| `200 OK` | The blob already exists and the server is returning the existing [Blob Descriptor](./02.md#blob-descriptor). |
|
||||
| `201 Created` | The blob was stored successfully and the server is returning its [Blob Descriptor](./02.md#blob-descriptor). |
|
||||
| `400 Bad Request` | The sha256 path, request headers, body, or remote URL parameters are malformed. |
|
||||
| `400 Bad Request` | The sha256 path, request headers, body, or 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 the upload can proceed. See [BUD-07](./07.md). |
|
||||
| `403 Forbidden` | The request is understood but not allowed by server policy. |
|
||||
| `409 Conflict` | The sha256 from the path does not match the request body or fetched remote blob. |
|
||||
| `409 Conflict` | The sha256 from the path 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. |
|
||||
| `502 Bad Gateway` | The server could not fetch the blob from any remote URL or every 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.
|
||||
|
||||
### File extension normalization (Optional)
|
||||
## POST /sha256 - Mirror Blob
|
||||
|
||||
Servers MAY accept `POST /<sha256>` requests containing one or more source references that tell the server where to fetch the blob. This replaces the mirroring flow from [BUD-04](./04.md) while retaining the blob hash in the path and allowing clients to reuse the same [BUD-11](./11.md) `upload` authorization token as long as at least one `x` tag matches the `<sha256>` path.
|
||||
|
||||
The request body MUST be UTF-8 plain text containing one source reference per line. Clients SHOULD set the `Content-Type` header to `text/plain; charset=utf-8`. Servers MUST accept lines separated by either LF or CRLF, MUST accept a final line without a trailing newline, and MUST ignore empty lines. Leading and trailing ASCII whitespace is not part of a source reference and MUST be removed from each line.
|
||||
|
||||
The request `Content-Type` and `Content-Length` headers describe the source list itself and MUST NOT be used as metadata for the mirrored blob.
|
||||
|
||||
Each non-empty line MUST be one of the following:
|
||||
|
||||
- An absolute `http` or `https` URL.
|
||||
- A valid [`blossom:` URI from BUD-10](./10.md).
|
||||
|
||||
The request body MUST contain at least one valid source reference after empty lines are removed. Servers MUST reject an empty body, invalid UTF-8, or any malformed or unsupported source reference with `400 Bad Request`.
|
||||
|
||||
To provide a single HTTP source, clients MUST send one line:
|
||||
|
||||
```http
|
||||
POST /b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553
|
||||
Content-Type: text/plain; charset=utf-8
|
||||
|
||||
https://cdn.example.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf
|
||||
```
|
||||
|
||||
Clients MAY mix HTTP URLs and Blossom URIs in the same request body:
|
||||
|
||||
```http
|
||||
POST /b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553
|
||||
Content-Type: text/plain; charset=utf-8
|
||||
|
||||
https://cdn-a.example.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf
|
||||
https://cdn-b.example.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf
|
||||
blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn-c.example.com&as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0
|
||||
```
|
||||
|
||||
For a `blossom:` URI, the sha256 hash in the URI MUST match the `<sha256>` path segment. Servers MUST reject the request with `409 Conflict` if any `blossom:` URI contains a different hash. Servers MUST resolve valid `blossom:` URIs using the [BUD-10 resolution strategy](./10.md#resolution-strategy).
|
||||
|
||||
When multiple source references are provided, servers MAY try any or all of them in any order. Servers MUST only store the blob if the sha256 hash of the fetched bytes matches the `<sha256>` path segment. If the fetched blob hash does not match the `<sha256>` path segment, the server MUST reject the request with `409 Conflict` and MUST NOT persist the blob.
|
||||
|
||||
The destination server SHOULD use the `Content-Type` header returned from the successful origin response 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` from the blob contents and file extension, falling back to `application/octet-stream` if it cannot determine the type.
|
||||
|
||||
Servers MAY use the origin `Content-Length` header to reject blobs that exceed server size limits before downloading the full response.
|
||||
|
||||
If the blob was newly stored, the endpoint MUST respond with `201 Created` and a [Blob Descriptor](./02.md#blob-descriptor) in the response body.
|
||||
If the blob already exists, the endpoint MUST respond with `200 OK` and a [Blob Descriptor](./02.md#blob-descriptor) in the response body.
|
||||
|
||||
### Checking support
|
||||
|
||||
Clients SHOULD send `OPTIONS /<sha256>` using any syntactically valid hash as defined in [BUD-01](./01.md#feature-discovery). Mirroring is supported when both `Allow` and `Access-Control-Allow-Methods` include `POST`; a server MAY advertise `PUT` while omitting `POST` when it supports direct uploads only.
|
||||
|
||||
### Status codes
|
||||
|
||||
Servers SHOULD use the following status codes for `POST /<sha256>` 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 sha256 path or request body is malformed, empty, or contains an unsupported source reference. |
|
||||
| `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. |
|
||||
| `405 Method Not Allowed` | The server does not support mirroring and returns an `Allow` header listing its supported methods. |
|
||||
| `409 Conflict` | The sha256 from the path does not match a `blossom:` URI or the fetched remote blob. |
|
||||
| `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 resolve or fetch the blob from any source reference, or every 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.
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user