laantungir/blossom
1
0
Fork 0
mirror of https://github.com/hzrd149/blossom.git synced 2026-08-11 08:27:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

Simplify mirror uploads

Browse Source
This commit is contained in:
hzrd149
2026-06-25 11:57:41 -05:00
parent ef8859e763
commit 14d7ff8e82
3 changed files with 44 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+3 -3
View File
@@ -20,7 +20,7 @@ BUDs or **Blossom Upgrade Documents** are short documents that outline an additi
- [BUD-01: Server requirements and blob retrieval](./buds/01.md)
- [BUD-02: Blob upload and management](./buds/02.md)
- [BUD-03: User Server List](./buds/03.md)
- [BUD-04: Mirroring blobs](./buds/04.md)
- [BUD-04: Mirroring blobs](./buds/04.md) _(unrecommended)_
- [BUD-05: Media optimization](./buds/05.md)
- [BUD-06: Upload requirements](./buds/06.md)
- [BUD-07: Payment required](./buds/07.md)
@@ -37,11 +37,11 @@ Blossom Servers expose a few endpoints for managing blobs
- `GET /<sha256>` (optional file `.ext`) [BUD-01](./buds/01.md#get-sha256---get-blob)
- `HEAD /<sha256>` (optional file `.ext`) [BUD-01](./buds/01.md#head-sha256---has-blob)
- `PUT /<sha256>` [BUD-13](./buds/13.md#put-sha256---upload-blob)
- `PUT /<sha256>` [BUD-13](./buds/13.md#put-sha256---upload-blob) _(also supports remote source URLs)_
- `HEAD /upload` [BUD-06](./buds/06.md#head-upload---upload-requirements-optional)
- `GET /list/<pubkey>` [BUD-12](./buds/12.md#get-listpubkey---list-blobs-unrecommended) _(unrecommended)_
- `DELETE /<sha256>` [BUD-12](./buds/12.md#delete-sha256---delete-blob)
- `PUT /mirror` [BUD-04](./buds/04.md#put-mirror---mirror-blob)
- `PUT /mirror` [BUD-04](./buds/04.md#put-mirror---mirror-blob) _(unrecommended)_
- `HEAD /media` [BUD-05](./buds/05.md#head-media)
- `PUT /media` [BUD-05](./buds/05.md#put-media)
- `PUT /report` [BUD-09](./buds/09.md)
buds/04.md
+8 -6
View File
@@ -2,13 +2,15 @@
## Mirroring blobs
`draft` `optional`
`draft` `optional` `unrecommended`
Defines the `/mirror` endpoint
Defines the `/mirror` endpoint.
New clients and servers SHOULD use the remote source upload mode of [`PUT /<sha256>` from BUD-13](./13.md#remote-source-upload) instead. That flow uses the blob hash in the URL, supports one or more remote source URLs, and reuses the same [BUD-11](./11.md) `upload` authorization token that a direct `PUT /<sha256>` upload uses.
## 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
@@ -19,8 +21,8 @@ Clients MUST pass the URL of the remote blob as a stringified JSON object in the
}
```
If the blob was newly mirrored and stored, the endpoint MUST respond with `201 Created` and a [Blob Descriptor](#blob-descriptor) in the response body.
If the blob already exists, the endpoint MUST respond with `200 OK` and a [Blob Descriptor](#blob-descriptor) in the response body.
If the blob was newly mirrored and stored, the endpoint MUST respond with `201 Created` and a [Blob Descriptor](./02.md#blob-descriptor) in the response body.
If the blob already exists, the endpoint MUST respond with `200 OK` and a [Blob Descriptor](./02.md#blob-descriptor) in the response body.
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`
@@ -46,7 +48,7 @@ Servers SHOULD use the following status codes for `PUT /mirror` responses:
| `413 Content Too Large` | The mirrored blob exceeds server size limits. |
| `415 Unsupported Media Type` | The mirrored blob type is not supported. |
| `429 Too Many Requests` | The client has exceeded a rate limit or quota. |
| `502 Bad Gateway` | The server could not fetch the blob from the origin URL or the origin response was unusable. |
| `502 Bad Gateway` | The server could not fetch the blob from the origin URL or the origin response was unusable. |
If included, `X-Reason` MUST be treated as a human readable diagnostic message only and clients MUST NOT parse it for control flow.
buds/13.md
+33 -6
View File
@@ -17,13 +17,39 @@ The [Blob Descriptor](./02.md#blob-descriptor) type is defined in [BUD-02](./02.
## PUT /sha256 - Upload Blob
The `PUT /<sha256>` endpoint MUST accept binary data in the request body.
The `<sha256>` path segment MUST be a lowercase hex-encoded sha256 hash of the request body.
The `<sha256>` path segment MUST be a lowercase hex-encoded sha256 hash of the blob being stored.
The server MUST NOT modify the blob in any way and MUST compute the sha256 hash over the exact bytes received. This requirement ensures that users can re-upload blobs to other servers without discrepancies.
When the request body is binary data, the server MUST NOT modify the blob in any way and MUST compute the sha256 hash over the exact bytes received. This requirement ensures that users can re-upload blobs to other servers without discrepancies.
Clients SHOULD include `Content-Type` and `Content-Length` headers specifying the MIME type and size of the data.
For binary uploads, clients SHOULD include `Content-Type` and `Content-Length` headers specifying the MIME type and size of the blob.
If the computed sha256 of the request body does not match the `<sha256>` path segment, the server MUST reject the request with `409 Conflict` and MUST NOT persist the blob.
If the computed sha256 of a binary request body does not match the `<sha256>` path segment, the server MUST reject the request with `409 Conflict` and MUST NOT persist the blob.
### Remote Source Upload
Servers MAY also accept one or more `url` query parameters that tell the server to fetch the blob from remote URLs instead of receiving the blob bytes in the request body. This rolls the mirroring flow from [BUD-04](./04.md) into the same path-addressed upload endpoint and allows clients to reuse the same [BUD-11](./11.md) `upload` authorization token as long as at least one `x` tag matches the `<sha256>` path.
When one or more `url` query parameters are present, the request body MUST be empty and servers MUST ignore `Content-Type` and `Content-Length` as blob metadata. If a client sends both `url` query parameters and a non-empty request body, servers MUST reject the request with `400 Bad Request`.
To provide a single remote source, clients MUST send one `url` query parameter:
```http
PUT /b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553?url=https%3A%2F%2Fcdn.example.com%2Fb1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf
```
To provide multiple remote sources, clients MUST repeat the `url` query parameter:
```http
PUT /b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553?url=https%3A%2F%2Fcdn-a.example.com%2Fb1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf&url=https%3A%2F%2Fcdn-b.example.com%2Fb1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf
```
Remote source URLs MUST be URL-encoded absolute `http` or `https` URLs. Servers MUST reject requests that include invalid `url` parameters with `400 Bad Request`.
When multiple `url` query parameters are provided, servers MAY try any or all of the URLs in any order. Servers MUST only store the blob if the sha256 hash of the fetched bytes matches the `<sha256>` path segment. If the fetched blob hash does not match the `<sha256>` path segment, the server MUST reject the request with `409 Conflict` and MUST NOT persist the blob.
The destination server SHOULD use the `Content-Type` header returned from the successful origin response 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 origin `Content-Length` header to reject blobs that exceed server size limits before downloading the full response.
If the blob was newly stored, the endpoint MUST respond with `201 Created` and a [Blob Descriptor](./02.md#blob-descriptor) in the response body.
If the blob already exists, the endpoint MUST respond with `200 OK` and a [Blob Descriptor](./02.md#blob-descriptor) in the response body.
@@ -38,15 +64,16 @@ Servers SHOULD use the following status codes for `PUT /<sha256>` responses:
| ---------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `200 OK` | The blob already exists and the server is returning the existing [Blob Descriptor](./02.md#blob-descriptor). |
| `201 Created` | The blob was stored successfully and the server is returning its [Blob Descriptor](./02.md#blob-descriptor). |
| `400 Bad Request` | The sha256 path, request headers, or body are malformed. |
| `400 Bad Request` | The sha256 path, request headers, body, or remote URL parameters are malformed. |
| `401 Unauthorized` | Authorization is required and missing or invalid. See [BUD-11](./11.md#endpoint-authorization-requirements). |
| `402 Payment Required` | Payment is required before the upload can proceed. See [BUD-07](./07.md). |
| `403 Forbidden` | The request is understood but not allowed by server policy. |
| `409 Conflict` | The sha256 from the URL does not match the request body. |
| `409 Conflict` | The sha256 from the path does not match the request body or fetched remote blob. |
| `411 Length Required` | A required `Content-Length` header is missing. |
| `413 Content Too Large` | The blob exceeds server size limits. |
| `415 Unsupported Media Type` | The blob type is not supported. |
| `429 Too Many Requests` | The client has exceeded a rate limit or quota. |
| `502 Bad Gateway` | The server could not fetch the blob from any remote URL or every origin response was unusable. |
If included, `X-Reason` MUST be treated as a human readable diagnostic message only and clients MUST NOT parse it for control flow.