diff --git a/buds/04.md b/buds/04.md index 474fce8..dd041d9 100644 --- a/buds/04.md +++ b/buds/04.md @@ -8,7 +8,7 @@ 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 +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 @@ -23,19 +23,19 @@ Clients MAY set the `Authorization` header to an upload authorization event defi The `/mirror` endpoint MUST download the blob from the specified URL and verify that there is at least one `x` tag in the authorization event matching the sha256 hash of the download blob -**Multiple `x` tags in the authorization event MUST NOT be interpreted as the user requesting a bulk mirror.** +**Multiple `x` tags in the authorization event MUST NOT be interpreted as the user requesting to mirror multiple blobs.** -The endpoint MUST return a [Blob Descriptor](#blob-descriptor) if the mirroring was successful or an error object if it was not +The endpoint MUST return a [Blob Descriptor](#blob-descriptor) and a `2xx` status code if the mirroring was successful or a `4xx` status code and error messageif it was not -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 SHOULD re-use the `Content-Type` header returned from the request to the URL to discover the mime type of the blob. If the `Content-Type` header is not returned they SHOULD attempt to use the file extension in the URL to guess the mime type. -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 +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. ## Example Flow -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) +1. Client signs an `upload` authorization event and uploads blob to Server A +1. Server A returns a [Blob Descriptor](./02.md#blob-descriptor) with the `url` +1. Client sends the `url` to Server B `/mirror` using the original `upload` authorization event +1. Server B downloads the blob from Server A using the `url` +1. Server B verifies the downloaded blob hash matches the `x` tag in the authorization event +1. Server B returns a [Blob Descriptor](./02.md#blob-descriptor)