diff --git a/buds/01.md b/buds/01.md index c10a883..94243bf 100644 --- a/buds/01.md +++ b/buds/01.md @@ -79,8 +79,25 @@ The `GET /` endpoint MUST return the contents of the blob in the respons The endpoint MUST accept an optional file extension in the URL. ie. `.pdf`, `.png`, etc -If the endpoint returns a `301` or `302` redirect it MUST redirect to a URL containing the same sha256 hash as the requested blob. -This ensures that if a user was to copy or reuse the redirect URL it would still contain the original sha256 hash +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) @@ -131,7 +148,8 @@ Example event for retrieving multiple blobs from single server: ## HEAD /sha256 - Has Blob -The `HEAD /` endpoint SHOULD be identical to the `GET /` 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 `HEAD /` endpoint SHOULD be identical to the `GET /` 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 /` endpoint. diff --git a/buds/02.md b/buds/02.md index 7264be9..fa073b0 100644 --- a/buds/02.md +++ b/buds/02.md @@ -15,7 +15,7 @@ A blob descriptor is a JSON object containing `url`, `sha256`, `size`, `type`, a - `url` A publicly accessible URL to the [BUD-01](./01.md#get-sha256---get-blob) `GET /` endpoint with a file extension - `sha256` The sha256 hash of the blob - `size` The size of the blob in bytes -- `type` (optional) The MIME type of the blob +- `type` The MIME type of the blob (falling back to `application/octet-stream` if unknown) - `uploaded` The unix timestamp of when the blob was uploaded to the server Servers MUST include a file extension in the URL in the `url` field to allow clients to easily embed the URL in social posts or other content @@ -42,7 +42,15 @@ The endpoint MUST NOT modify the blob in any way and should return the exact sam The endpoint MUST return a [Blob Descriptor](#blob-descriptor) if the upload was successful or an error object if it was not -Servers MAY reject an upload for any reason and should respond with the appropriate HTTP `4xx` status code and an error message explaining the reason for the rejection +Servers MAY reject an upload for any reason and should respond with the appropriate HTTP `4xx` status code and an error +message explaining the reason for the rejection + +### 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 /` 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. ### Upload Authorization (Optional) diff --git a/buds/04.md b/buds/04.md index dde6fc4..67b013b 100644 --- a/buds/04.md +++ b/buds/04.md @@ -19,15 +19,20 @@ Clients MUST pass the URL of the remote blob as a stringified JSON object in the } ``` -Clients MAY set the `Authorization` header to an upload authorization event defined in [BUD-02](./02.md#upload-authorization-required). When using authorization, the event MUST be of type "upload". +Clients MAY set the `Authorization` header to an upload authorization event defined in [BUD-02](./02.md#upload-authorization-optional). When using authorization, the event MUST be of type "upload". The `/mirror` endpoint MUST download the blob from the specified URL and verify that there is at least one `x` tag in the authorization event matching the sha256 hash of the download blob **Multiple `x` tags in the authorization event MUST NOT be interpreted as the user requesting to mirror multiple blobs.** -The endpoint MUST return a [Blob Descriptor](#blob-descriptor) and a `2xx` status code if the mirroring was successful or a `4xx` status code and error messageif it was not +The endpoint MUST return a [Blob Descriptor](#blob-descriptor) and a `2xx` status code if the mirroring was successful +or a `4xx` status code and error message if it was not. -Servers SHOULD use the `Content-Type` header returned from the requested URL to infer the mime type of the blob. If the `Content-Type` header is not returned they SHOULD attempt to use the file extension in the URL or fallback to `application/octet-stream`. +The destination server SHOULD use the `Content-Type` header returned from the origin server 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 `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 `4xx` status code and an error message explaining the reason for the rejection.