diff --git a/README.md b/README.md index 45c35f8..e8fb010 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,7 @@ BUDs or **Blossom Upgrade Documents** are short documents that outline an additi - [BUD-08: Nostr File Metadata Tags](./buds/08.md) - [BUD-09: Blob Report](./buds/09.md) - [BUD-10: Blossom URI Schema](./buds/10.md) +- [BUD-11: Local Blob Cache](./buds/11.md) ## Endpoints diff --git a/buds/11.md b/buds/11.md new file mode 100644 index 0000000..9b4adb5 --- /dev/null +++ b/buds/11.md @@ -0,0 +1,107 @@ +# BUD-11 + +## Local Blob Cache + +`draft` `optional` + +This document defines the specification for a local blob cache server that can be hosted on `127.0.0.1:24242` to provide fast, local access to cached blobs or proxy requests to other public Blossom servers. + +## Server Address + +A local blob cache server MUST be accessible on `http://127.0.0.1:24242`. The port `24242` is chosen to align with the Nostr event kind used for Blossom authorization events. + +## Health Check Endpoint + +The server MUST respond with a 2xx HTTP status code (typically `200 OK`) on the `HEAD /` endpoint to allow local applications to easily detect if the cache server is available. + +The `HEAD /` endpoint MUST return a 2xx HTTP status code. The response MUST NOT include a response body per [RFC 7231](https://www.rfc-editor.org/rfc/rfc7231#section-4.3.2). + +This endpoint enables simple health checks: + +```bash +curl -I http://127.0.0.1:24242/ +``` + +## Access Control + +The server SHOULD NOT require any authentication for blob downloads or uploads. All requests MUST be served without requiring an `Authorization` header. + +If an implementation needs to add access control, it SHOULD restrict access based on IP address to ensure requests only come from `127.0.0.1`. This ensures that local applications can freely access cached blobs without the overhead of signing authorization events. + +## Blob Retrieval + +The server MUST implement the `GET /` and `HEAD /` endpoints as defined in [BUD-01](./01.md#get-sha256---get-blob): + +1. The server MUST accept optional file extensions in the URL (e.g., `/.pdf`) +2. The server MUST set appropriate `Content-Type` headers or default to `application/octet-stream` + +## Range Requests + +To better support mobile devices, video files, or low bandwidth connections, implementations SHOULD support range requests ([RFC 7233 section 3](https://www.rfc-editor.org/rfc/rfc7233#section-3)) on the `GET /` endpoint and signal support using the `accept-ranges: bytes` and `content-length` headers on the `HEAD /` endpoint. + +See [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests) for more details. + +## Proxy Hints + +The server SHOULD accept [BUD-10](./10.md) query parameters `xs` (server) and `as` (author) hints on the `GET /` endpoint to enable proxying blob requests to other Blossom servers when the blob is not available in the local cache. + +### Query Parameter Format + +When a blob is not found in the local cache, the server MAY use the following query parameters to attempt retrieval from other Blossom servers: + +- `xs=` - One or more server hints where the blob may be available +- `as=` - One or more author pubkeys whose server lists may contain the blob + +### Example Request + +``` +GET /b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.example.com&as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0 +``` + +### Proxy Behavior + +When the server receives a request with proxy hints and the blob is not in the local cache: + +1. The server SHOULD attempt to retrieve the blob from the servers specified in the `xs` parameters +2. If `xs` hints fail, the server MAY attempt to retrieve the blob using the `as` parameters by: + - Fetching the author's [BUD-03](./03.md) server list (`kind:10063`) + - Attempting to retrieve the blob from servers in the author's list +3. If the blob is successfully retrieved, the server SHOULD: + - Cache the blob locally for future requests + - Return the blob to the client with appropriate headers +4. If the blob cannot be retrieved from any hint, the server MUST return a `404 Not Found` response + +This proxy functionality allows the local cache server to act as a transparent proxy, automatically fetching and caching blobs from remote Blossom servers when needed. + +## CORS Headers + +The server MUST set the `Access-Control-Allow-Origin: *` header on all responses to ensure compatibility with web applications, as specified in [BUD-01](./01.md#cross-origin-headers). + +## Use Cases + +A local blob cache server enables several use cases: + +- **Fast Local Access**: Applications can check the local cache first before making network requests to remote Blossom servers +- **Offline Access**: Previously cached blobs remain accessible even when network connectivity is unavailable +- **Bandwidth Savings**: Reduces redundant downloads of frequently accessed blobs +- **Development**: Provides a simple local server for testing Blossom applications without requiring remote server access + +## Implementation Notes + +- The server SHOULD implement efficient blob storage, such as using the sha256 hash as the filename or storage key +- The server SHOULD implement cache eviction policies (e.g., LRU, size-based limits) to manage storage +- The server SHOULD validate that downloaded blobs match their sha256 hash before caching +- The server MAY implement the `HEAD /` endpoint to allow clients to check blob availability without downloading + +## Example Implementation Flow + +1. Client requests blob: `GET http://127.0.0.1:24242/` +2. Server checks local cache +3. If found: Return blob immediately +4. If not found and proxy hints provided: + - Attempt to fetch from `xs` server hints + - If that fails, attempt to fetch using `as` author hints + - Cache the blob if successfully retrieved + - Return the blob to the client +5. If not found and no proxy hints: Return `404 Not Found` +