blossom/buds/04.md

BUD-04

Mirroring blobs

draft optional

Defines the /mirror endpoint

PUT /mirror - Mirror Blob

A server MAY expose a PUT /mirror endpoint to allow users to copy a blob from a URL instead of uploading it

Clients MUST pass the URL of the remote blob as a stringified JSON object in the request body

// request body...
{
  "url": "https://cdn.satellite.earth/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf"
}

The endpoint MUST return a Blob Descriptor and a 2xx status code if the mirroring was successful or a 4xx status code and error message if it was not.

The destination server SHOULD use the Content-Type header returned from the origin server to infer the mime type of the blob. If the Content-Type header is not present the destination server SHOULD attempt to detect the Content-Type from the blob contents and file extension, falling back to application/octet-stream if it cannot determine the type.

Servers MAY use the Content-Length header to determine the size of the blob.

Servers MAY reject a mirror request for any reason and MUST respond with the appropriate HTTP 4xx status code and an error message explaining the reason for the rejection.

Upload Authorization

Servers MAY require authorization when mirroring blobs as defined by BUD-11.

Example Flow

1. Client signs an upload authorization token and uploads blob to Server A
2. Server A returns a Blob Descriptor with the url
3. Client sends the url to Server B /mirror using the original upload authorization token
4. Server B downloads the blob from Server A using the url
5. Server B verifies the downloaded blob hash matches the x tag in the authorization token
6. Server B returns a Blob Descriptor