# 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-Reason` 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 blob's MIME type, like `application/pdf` or `image/png`.

### 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-Reason` with a human readable error message.

Some examples of error messages:

```http
HTTP/1.1 400 Bad Request
X-Reason: Invalid X-SHA-256 header format. Expected a string.
```

```http
HTTP/1.1 401 Unauthorized
X-Reason: Authorization required for uploading video files.
```

```http
HTTP/1.1 403 Forbidden
X-Reason: SHA-256 hash banned.
```

```http
HTTP/1.1 411 Length Required
X-Reason: Missing X-Content-Length header.
```

```http
HTTP/1.1 413 Content Too Large
X-Reason: File too large. Max allowed size is 100MB.
```

```http
HTTP/1.1 415 Unsupported Media Type
X-Reason: Unsupported file type.
```