BUD-11 local blob cache

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
 

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 /<sha256>` and `HEAD /<sha256>` 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., `/<sha256>.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 /<sha256>` endpoint and signal support using the `accept-ranges: bytes` and `content-length` headers on the `HEAD /<sha256>` 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 /<sha256>` 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=<server>` - One or more server hints where the blob may be available
+- `as=<pubkey>` - 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 /<sha256>` endpoint to allow clients to check blob availability without downloading
+
+## Example Implementation Flow
+
+1. Client requests blob: `GET http://127.0.0.1:24242/<sha256>`
+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`
+