add rough draft for media endpoint

buds/05.md

@@ -0,0 +1,87 @@
+BUD-05
+======
+
+Media optimization endpoints
+
+`draft` `optional`
+
+Defines the `PUT /media`, `GET /media/<task>` and `DELETE /media/<task>` endpoints for processing and optimizing media
+
+## Task Object
+
+The task object defines a long running media processing task on the server. A task MUST have the following fields
+
+ - `id` A unique id for the task **(required)**
+ - `status` The status of the job, either `running`, `complete`, or `canceled` **(required)**
+ - `message` A human-readable description of what is happening or the current status *(optional)*
+ - `progress` A number from 0 to 100 representing the percentage of the task that is complete *(optional)*
+ - `blob` A full [Blob Descriptor](./02.md#blob-descriptor) **(required when `complete`)**
+
+## PUT /media
+
+The `PUT /media` endpoint MUST accept binary data in the body of the request and MAY use the `Content-Type` and `Content-Length` headers to get the MIME type and size of the media
+
+The server should preform any optimizations or conversions it deems necessary in order to make the media more suitable for distribution
+
+The endpoint MUST return a status code of `202` with `Content-Type: application/json` and a [task object](#task-object) or an [error response](./01.md#error-responses)
+
+Servers MAY reject a media upload for any reason and should respond with the appropriate HTTP `4xx` status code and an error message explaining the reason for the rejection
+
+### Upload Authorization
+
+Servers may require an `upload` [authorization event](./02.md#upload-authorization-required) to identify the uploader
+
+If a server requires an `upload` authorization event it MUST preform all the [checks](./02.md#upload-authorization-required) that the `/upload` endpoint does, including that the `x` tag value matches the sha256 hash of the uploaded blob
+
+## GET /media/task
+
+Servers may expose a `GET /media/<task id>` endpoint to allow clients to get the results or check on the progress of a task
+
+The endpoint MUST return a `2xx` status code and a [task object](#task-object) if a task with `<task id>` exists or an [error response](./01.md#error-responses)
+
+The `blob` field MUST be set to a [Blob Descriptor](./02.md#blob-descriptor) when the task `status` is `complete`
+
+Servers may delete (or forget) tasks after a self determined amount of time after the task status is `complete`
+
+## DELETE /media/task
+
+Servers may expose a `DELETE /media/<task id>` endpoint to allow clients to cancel a processing request
+
+## Examples
+
+Upload image `PUT /media`
+```json
+{
+	"id": "0e81bf11-eb84-49b8-a7f0-4c7c60254f2e",
+	"status": "running",
+	"progress": 0,
+	"message": "Resizing Image"
+}
+```
+
+Example `GET /media/eb6e7ec1-b752-4740-91bb-9aaddf92bc57`:
+```json
+{
+	"id": "eb6e7ec1-b752-4740-91bb-9aaddf92bc57",
+	"status": "running",
+	"progress": 24,
+	"message": "Resizing Video"
+}
+```
+
+Example `GET /media/eb6e7ec1-b752-4740-91bb-9aaddf92bc57`:
+```json
+{
+	"id": "eb6e7ec1-b752-4740-91bb-9aaddf92bc57",
+	"status": "complete",
+	"progress": 100,
+	"message": "Finished optimizing video",
+	"blob": {
+		"url": "https://cdn.example.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.webm",
+		"sha256": "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553",
+		"size": 18431531,
+		"type": "video/webm",
+		"uploaded": 1722386093
+	}
+}
+```