mirror of
https://github.com/hzrd149/blossom.git
synced 2026-10-30 09:47:33 +00:00
51 lines
1.8 KiB
Markdown
51 lines
1.8 KiB
Markdown
# BUD-14
|
|
|
|
## Blob Previews
|
|
|
|
`draft` `optional`
|
|
|
|
Defines how Blossom servers can advertise preview images for blobs using the HTTP `Link` response header as specified by [RFC 8288](https://www.rfc-editor.org/rfc/rfc8288.html).
|
|
|
|
## Preview discovery
|
|
|
|
On successful `HEAD /<sha256>` and `GET /<sha256>` responses, servers MAY include a `Link` response header with `rel="preview"` to advertise a preview representation of the blob.
|
|
|
|
Example:
|
|
|
|
```http
|
|
HEAD /b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf HTTP/1.1
|
|
|
|
HTTP/1.1 200 OK
|
|
Content-Type: application/pdf
|
|
Content-Length: 184292
|
|
Link: </thumbnails/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.jpg>; rel="preview"
|
|
```
|
|
|
|
The link target MAY be an absolute URL or a relative reference resolved according to [RFC 8288](https://www.rfc-editor.org/rfc/rfc8288.html).
|
|
|
|
## Preview representation
|
|
|
|
The link target identifies a preview representation of the blob.
|
|
|
|
The preview representation SHOULD be returned as an `image/*` resource.
|
|
|
|
The preview URL is implementation-defined and is not required to be a Blossom blob URL or any other [BUD-01](./01.md) endpoint.
|
|
|
|
Servers MAY generate previews eagerly, lazily, or on demand.
|
|
|
|
Servers MAY omit the `Link` header when no preview is available.
|
|
|
|
## Client behavior
|
|
|
|
Clients SHOULD use `HEAD /<sha256>` to discover previews without downloading the original blob.
|
|
|
|
Clients MAY also inspect `GET /<sha256>` responses for the same `Link` header.
|
|
|
|
Clients MUST NOT assume the preview URL can be derived from the blob URL.
|
|
|
|
Clients SHOULD treat the preview as an optional hint and fall back gracefully when the `Link` header is absent or the preview resource cannot be fetched.
|
|
|
|
## Notes
|
|
|
|
Servers MAY also expose the same preview URL using the NIP-94 `thumb` tag described in [BUD-08](./08.md).
|