mirror of
https://github.com/hzrd149/blossom.git
synced 2026-01-24 22:28:51 +00:00
108 lines
5.3 KiB
Markdown
108 lines
5.3 KiB
Markdown
# 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`
|
|
|