Merge pull request #74 from aaccioly-open-source/docs/make-file-extension-detection-mandatory

Clarify requirements around file extensions, Content-Type, Content-Length and redirection.

buds/01.md

@@ -79,8 +79,25 @@ The `GET /<sha256>` 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 /<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 `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.
 

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 /<sha256>` 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 /<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.
 
 ### Upload Authorization (Optional)
 

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.