From f47e567147fbc26e71ec1340fd26a4f3b859f66f Mon Sep 17 00:00:00 2001 From: hzrd149 Date: Thu, 30 May 2024 17:50:16 -0500 Subject: [PATCH 1/3] mirror blobs --- buds/04.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 buds/04.md diff --git a/buds/04.md b/buds/04.md new file mode 100644 index 0000000..0ff2b11 --- /dev/null +++ b/buds/04.md @@ -0,0 +1,29 @@ +BUD-04 +====== + +Efficiently mirroring blobs +--------------------- + +`draft` `optional` + +If a server supports the `/upload` endpoint defined in [BUD-02](./02.md) it MAY also support an optional `url` query parameter in the URL ( eg. `/upload?url=https://cdn.satellite.earth/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf` ) + +If the `url` query parameter is specified the server MUST ignore the body and `Content-Type` of the request and download the raw binary blob data from the URL + +The server MUST verify the sha256 hash of the downloaded blob matches the `x` tag in the upload [authorization event](./02.md#upload-authorization-required) + +The server should re-use the `Content-Type` header returned from the URL to know the mime type of the blob. if none is returned it may use the file extension in the URL + +The endpoint MUST return a [Blob Descriptor](#blob-descriptor) if the mirroring was successful or an error object if it was not + +If no `url` query parameter is specified the server MUST follow the rules layed out in [BUD-02](./02.md) + +## Example Flow + +1. Client requests lists of blobs from Server A +1. Client signs an upload auth event for X +1. Client makes request `https://cdn.server-b.com/upload?url=https://cdn.server-a.com/.png` with authorization header +1. Server B receives request +1. Server B downloads blob from Server A using url query parameter +1. Server B verifies downloaded blob hash matches `x` tag in authorization header +1. Server B returns [Blob Descriptor](./02.md#blob-descriptor) From 0476b37945d84a1b584807ce9aefee9e7e42f02c Mon Sep 17 00:00:00 2001 From: hzrd149 Date: Fri, 31 May 2024 10:50:16 -0500 Subject: [PATCH 2/3] change to /mirror endpoint --- buds/04.md | 34 ++++++++++++++++++++++------------ 1 file changed, 22 insertions(+), 12 deletions(-) diff --git a/buds/04.md b/buds/04.md index 0ff2b11..c4e1d8d 100644 --- a/buds/04.md +++ b/buds/04.md @@ -1,29 +1,39 @@ BUD-04 ====== -Efficiently mirroring blobs +Mirroring blobs --------------------- `draft` `optional` -If a server supports the `/upload` endpoint defined in [BUD-02](./02.md) it MAY also support an optional `url` query parameter in the URL ( eg. `/upload?url=https://cdn.satellite.earth/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf` ) +Defines the `/mirror` endpoint -If the `url` query parameter is specified the server MUST ignore the body and `Content-Type` of the request and download the raw binary blob data from the URL +## PUT /mirror - Mirror Blob -The server MUST verify the sha256 hash of the downloaded blob matches the `x` tag in the upload [authorization event](./02.md#upload-authorization-required) +A server may expose a `PUT /mirror` endpoint to allow users to copy a blob from a URL instead of uploading it -The server should re-use the `Content-Type` header returned from the URL to know the mime type of the blob. if none is returned it may use the file extension in the URL +Clients MUST pass the URL of the remote blob as a stringified JSON object in the request body + +```json +// request body +{ "url": "https://cdn.satellite.earth/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf" } +``` + +Clients MUST set the `Authorization` header to an upload authorization event defined in [BUD-02](./02.md#upload-authorization-required) + +The `/mirror` endpoint MUST download the blob from the specified URL and verify the sha256 hash matches the `x` tag in the upload authorization event The endpoint MUST return a [Blob Descriptor](#blob-descriptor) if the mirroring was successful or an error object if it was not -If no `url` query parameter is specified the server MUST follow the rules layed out in [BUD-02](./02.md) +Servers should re-use the `Content-Type` header returned from the URL to discover the mime type of the blob. if none is returned it may use the file extension in the URL + +Servers MAY reject a mirror request for any reason and should respond with the appropriate HTTP `4xx` status code and an error message explaining the reason for the rejection ## Example Flow -1. Client requests lists of blobs from Server A -1. Client signs an upload auth event for X -1. Client makes request `https://cdn.server-b.com/upload?url=https://cdn.server-a.com/.png` with authorization header -1. Server B receives request -1. Server B downloads blob from Server A using url query parameter -1. Server B verifies downloaded blob hash matches `x` tag in authorization header +1. Client signs authorization event and uploads blob to Server A +1. Server A returns blob descriptor with `url` +1. Client sends the `url` to Server B `/mirror` using the original authorization event +1. Server B downloads blob from Server A using the url +1. Server B verifies downloaded blob hash matches `x` tag in authorization event 1. Server B returns [Blob Descriptor](./02.md#blob-descriptor) From 8d2b6b1da15b01ec69e1ce4ab70ffef9051efa84 Mon Sep 17 00:00:00 2001 From: hzrd149 Date: Fri, 31 May 2024 14:27:26 -0500 Subject: [PATCH 3/3] add mirror to readme --- README.md | 2 ++ buds/01.md | 2 +- buds/02.md | 2 +- buds/04.md | 2 +- 4 files changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 4879df7..ee195af 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,8 @@ Blossom Servers expose four endpoints for managing blobs - `Authentication` _(optional)_: Signed [nostr event](./buds/01.md#list-authorization-optional) - `DELETE /` [BUD-2](./buds/02.md#delete-sha256---delete-blob) - `Authentication`: Signed [nostr event](./buds/01.md#delete-authorization-required) +- `PUT /mirror` [BUD-04](./buds/04.md#put-mirror---mirror-blob) + - `Authentication`: Signed [nostr event](./buds/01.md#upload-authorization-required) ## Protocol specification (BUDs) diff --git a/buds/01.md b/buds/01.md index 813de13..813f8c0 100644 --- a/buds/01.md +++ b/buds/01.md @@ -2,7 +2,7 @@ BUD-01 ====== Server requirements and blob reterival ---------------------- +-------------------------------------- `draft` `mandatory` diff --git a/buds/02.md b/buds/02.md index 993b9c2..e645943 100644 --- a/buds/02.md +++ b/buds/02.md @@ -2,7 +2,7 @@ BUD-02 ====== Blob upload and management ---------------------- +-------------------------- `draft` `optional` diff --git a/buds/04.md b/buds/04.md index c4e1d8d..0b0191b 100644 --- a/buds/04.md +++ b/buds/04.md @@ -2,7 +2,7 @@ BUD-04 ====== Mirroring blobs ---------------------- +--------------- `draft` `optional`