From 81bd6f856f11ab1d70dea72dfbfecf49de564903 Mon Sep 17 00:00:00 2001 From: hzrd149 Date: Mon, 9 Sep 2024 14:57:46 -0500 Subject: [PATCH] simplify media endpoint --- buds/02.md | 2 +- buds/05.md | 76 +++++++++++------------------------------------------- 2 files changed, 16 insertions(+), 62 deletions(-) diff --git a/buds/02.md b/buds/02.md index 3b9b7f0..21db72b 100644 --- a/buds/02.md +++ b/buds/02.md @@ -47,7 +47,7 @@ Servers MAY reject an upload for any reason and should respond with the appropri Servers MUST accept an authorization event when uploading blobs and should perform additional checks 1. The `t` tag MUST be set to `upload` -2. MUST contain at least one `x` tag matching the sha256 hash of the blob being uploaded +2. MUST contain at least one `x` tag matching the sha256 hash of the body of the request Example Authorization event: diff --git a/buds/05.md b/buds/05.md index 97d92b7..42233f6 100644 --- a/buds/05.md +++ b/buds/05.md @@ -1,21 +1,10 @@ -BUD-05 -====== +# BUD-05 Media optimization endpoints `draft` `optional` -Defines the `PUT /media`, `GET /media/` and `DELETE /media/` 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`)** +Defines the `PUT /media` endpoint for processing and optimizing media ## PUT /media @@ -23,65 +12,30 @@ The `PUT /media` endpoint MUST accept binary data in the body of the request and 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) +The endpoint MUST respond with a `2xx` status and a [blob descriptor](./02.md#blob-descriptor) of the new processed blob -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 +Servers MAY reject media uploads 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 +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 +If a server requires an `upload` authorization event it MUST preform all the checks outlined in the [`/upload`](./02.md#upload-authorization-required) endpoint -## GET /media/task +## Limitations -Servers may expose a `GET /media/` endpoint to allow clients to get the results or check on the progress of a task +This endpoint is intentionally limited to optimizing a single blob with the goal of making it easier to distribute -The endpoint MUST return a `2xx` status code and a [task object](#task-object) if a task with `` exists or an [error response](./01.md#error-responses) +How the blob is optimized is the sole respirability of the server and the client should have no say in what optimization process is used -The `blob` field MUST be set to a [Blob Descriptor](./02.md#blob-descriptor) when the task `status` is `complete` +The goal of this endpoint is to provide a simple "trusted" optimization endpoint clients can use to optimize media for distribution -Servers may delete (or forget) tasks after a self determined amount of time after the task status is `complete` +If a longer optimization or transformation process is needed, or if the client needs to specify how a blob should be transformed. there are other tools and protocol that should be used. -## DELETE /media/task +## Client Implementation -Servers may expose a `DELETE /media/` endpoint to allow clients to cancel a processing request +Clients MAY let a user selected a "trusted processing" server for uploading images or short videos -## Examples +Once a server has been selected, the client can upload the original media to the `/media` endpoint of the trusted server and get the optimized blob back -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 - } -} -``` +Then optionally the client can ask the user to sign another `upload` authorization event for the new optimized blob and call the `/mirror` endpoint on other servers to distribute the blob