Merge pull request #28 from quentintaranpino/BUD06-upload-requirements

BUD-06 Upload requirements

README.md

@@ -16,9 +16,10 @@ Blossom Servers expose four 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 /upload` [BUD-2](./buds/02.md#put-upload---upload-blob)
+- `PUT /upload` [BUD-02](./buds/02.md#put-upload---upload-blob)
   - `Authentication`: Signed [nostr event](./buds/02.md#upload-authorization-required)
   - Return a blob descriptor
+- `HEAD /upload` [BUD-06](./buds/06.md#head-upload---upload-requirements)
 - `GET /list/<pubkey>` [BUD-02](./buds/02.md#get-listpubkey---list-blobs)
   - Returns an array of blob descriptors
   - `Authentication` _(optional)_: Signed [nostr event](./buds/02.md#list-authorization-optional)
@@ -39,6 +40,7 @@ See the [BUDs](./buds) folder and specifically [BUD-01](./buds/01.md) and [BUD-0
 - [BUD-02: Blob upload and management](./buds/02.md)
 - [BUD-03: User Server List](./buds/03.md)
 - [BUD-04: Mirroring blobs](./buds/04.md)
+- [BUD-06: Upload requirements](./buds/06.md)
 
 ## Event kinds
 

buds/06.md

@@ -0,0 +1,77 @@
+BUD-06
+======
+
+Upload requirements
+---------------
+
+`draft` `optional`
+
+Defines how clients can verify if the upload can be completed before sending the blob to the server. This mechanism helps prevent unnecessary traffic to other endpoints by rejecting files based on their hash, size, MIME type or other server-specific requirements.
+
+## HEAD /upload - Upload requirements
+
+The `HEAD /upload` endpoint `MUST` use the `X-SHA-256`, `X-Content-Type` and `X-Content-Length` headers sent by client to get the SHA-256 hash, MIME type and size of the blob that will be uploaded, returning a HTTP status code and a custom header `X-Upload-Message` to indicate some human readable message about the upload requirements.
+
+### Headers
+
+- `X-SHA-256`: A string that represents the blob's SHA-256 hash.
+- `X-Content-Length`: An integer that represents the blob size in bytes.
+- `X-Content-Type`: A string that specifies the fblobile's MIME type, like `application/pdf` or `image/png`.
+- `X-Upload-Message`: A human readable message that explains the reason why the upload cannot proceed.
+
+### Upload Authorization  
+
+The `HEAD /upload` endpoint MAY accept an `upload` authorization event using the `Authorization` header similar to what is used in the [`PUT /upload`](./02.md#upload-authorization-required) endpoint  
+
+If the server requires authorization to upload it may respond with the `401` status code, or if authorization was provided and is invalid or not permitted it may respond with `403` status code  
+
+### Examples
+
+Example request from the client:
+
+```http
+X-Content-Type: application/pdf
+X-Content-Length: 184292
+X-SHA-256: 88a74d0b866c8ba79251a11fe5ac807839226870e77355f02eaf68b156522576
+```
+
+Example response from the server if the upload can be done:
+
+```http
+HTTP/1.1 200 OK
+```
+
+If the upload cannot proceed, the server `MUST` return an appropriate `4xx` HTTP status code and a custom header `X-Upload-Message` with a human readable error message.  
+
+
+Some examples of error messages:
+
+```http
+HTTP/1.1 400 Bad Request
+X-Upload-Message: Invalid X-SHA-256 header format. Expected a string.
+```
+
+```http
+HTTP/1.1 401 Unauthorized  
+X-Upload-Message: Authorization required for uploading video files.
+```
+
+```http
+HTTP/1.1 403 Forbidden  
+X-Upload-Message: SHA-256 hash banned.
+```
+
+```http
+HTTP/1.1 411 Length Required  
+X-Upload-Message: Missing X-Content-Length header.
+```
+
+```http
+HTTP/1.1 413 Content Too Large
+X-Upload-Message: File too large. Max allowed size is 100MB.
+```
+
+```http
+HTTP/1.1 415 Unsupported Media Type
+X-Upload-Message: Unsupported file type.
+```