mirror of
https://github.com/hzrd149/blossom.git
synced 2026-10-30 17:57:33 +00:00
70 lines
3.8 KiB
Markdown
70 lines
3.8 KiB
Markdown
# BUD-01
|
|
|
|
## Server requirements and blob retrieval
|
|
|
|
`draft` `mandatory`
|
|
|
|
_All pubkeys MUST be in hex format_
|
|
|
|
## Cross origin headers
|
|
|
|
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.
|
|
|
|
The header `Access-Control-Max-Age: 86400` MAY be set to cache the results of a preflight request for 24 hours.
|
|
|
|
## 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.
|
|
|
|
## Endpoints
|
|
|
|
All endpoints MUST be served from the root of the domain (eg. the `/upload` endpoint MUST be accessible from `https://cdn.example.com/upload`, etc). This allows clients to talk to servers interchangeably when uploading or retrieving blobs
|
|
|
|
## GET /sha256 - Get Blob
|
|
|
|
The `GET /<sha256>` endpoint MUST return the contents of the blob in the response body. the `Content-Type` header SHOULD beset to the appropriate MIME-type
|
|
|
|
The endpoint MUST accept an optional file extension in the URL. ie. `.pdf`, `.png`, etc
|
|
|
|
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`
|
|
|
|
### Proxying and Redirection (Optional)
|
|
|
|
If the endpoint returns a redirection 3xx status code such as 307 or 308 ([RFC 9110 section
|
|
15.4](https://datatracker.ietf.org/doc/html/rfc9110#name-redirection-3xx)), it MUST redirect to a URL containing the
|
|
same sha256 hash as the requested blob. This ensures that if a user copies or reuses the redirect URL, it will
|
|
contain the original sha256 hash.
|
|
|
|
While the final blob may not be served from a Blossom server (e.g. CDN, IPFS, object storage, etc.), the destination
|
|
server MUST set the `Access-Control-Allow-Origin: *` header on the response to allow cross-origin requests, as well as
|
|
the `Content-Type` and `Content-Length` headers to ensure the blob can be correctly displayed by clients. Two ways to
|
|
guarantee this are:
|
|
|
|
1. Proxying the blob through the Blossom server, allowing it to override headers such as `Content-Type`.
|
|
2. Manipulating the redirect URL to include a file extension that matches the blob type, such as `.pdf`, `.png`, etc. If
|
|
the server is unable to determine the MIME type of the blob, it MUST default to `application/octet-stream` and MAY
|
|
include a file extension in the URL that reflects the blob type (e.g. `.bin`, `.dat`, etc.).
|
|
|
|
### Get Authorization (optional)
|
|
|
|
Servers MAY require authorization when retrieving blobs, as defined by [BUD-11](./11.md#endpoint-authorization-requirements).
|
|
|
|
## HEAD /sha256 - Has Blob
|
|
|
|
The `HEAD /<sha256>` endpoint SHOULD be identical to the `GET /<sha256>` endpoint except that it MUST NOT return the
|
|
blob in the reponse body per [RFC 7231](https://www.rfc-editor.org/rfc/rfc7231#section-4.3.2)
|
|
|
|
The endpoint MUST respond with the same `Content-Type` and `Content-Length` headers as the `GET /<sha256>` endpoint.
|
|
|
|
The endpoint MUST accept an optional file extension in the URL similar to the `GET /<sha256>` endpoint. ie. `.pdf`, `.png`, etc
|
|
|
|
## Range requests
|
|
|
|
To better support mobile devices, video files, or low bandwidth connections. servers should support range requests ([RFC 7233 section 3](https://www.rfc-editor.org/rfc/rfc7233#section-3)) on the `GET /<sha256>` endpoint and signal support using the `accept-ranges: bytes` and `content-length` headers on the `HEAD /<sha256>` endpoint
|
|
|
|
See [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests) for more details
|