laantungir/blossom
1
0
Fork 0
mirror of https://github.com/hzrd149/blossom.git synced 2025-12-08 14:58:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

switch URI to use "blossom" instead of "blob"

Browse Source
This commit is contained in:
hzrd149
2025-11-05 13:48:17 -06:00
parent 05a6c68dd8
commit 342cae9e51
2 changed files with 32 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@@ -26,7 +26,7 @@ BUDs or **Blossom Upgrade Documents** are short documents that outline an additi
- [BUD-07: Payment required](./buds/07.md) - [BUD-07: Payment required](./buds/07.md)
- [BUD-08: Nostr File Metadata Tags](./buds/08.md) - [BUD-08: Nostr File Metadata Tags](./buds/08.md)
- [BUD-09: Blob Report](./buds/09.md) - [BUD-09: Blob Report](./buds/09.md)
- [BUD-10: Blob URI Schema](./buds/10.md) - [BUD-10: Blossom URI Schema](./buds/10.md)
## Endpoints ## Endpoints

62
buds/10.md
View File

@@ -1,6 +1,6 @@
# BUD-10 # BUD-10
## Blob URI Schema ## Blossom URI Schema
`draft` `optional` `draft` `optional`
@@ -8,15 +8,15 @@ Defines a URI schema for referencing Blossom blobs similar to magnet links. This
## URI Format ## URI Format
The `blob:` URI schema MUST follow this format: The `blossom:` URI schema MUST follow this format:
``` ```
blob:<sha256>.<ext>[?param1=value1&param2=value2...] blossom:<sha256>.<ext>[?param1=value1&param2=value2...]
``` ```
### Components ### Components
- `blob:` - The URI scheme identifier - `blossom:` - The URI scheme identifier
- `<sha256>` - A 64 character lowercase hexadecimal sha256 hash of the blob - `<sha256>` - A 64 character lowercase hexadecimal sha256 hash of the blob
- `.<ext>` - A file extension (e.g., `.pdf`, `.png`, `.jpg`, `.mp4`). If the file extension is unknown, it MUST default to `.bin` - `.<ext>` - A file extension (e.g., `.pdf`, `.png`, `.jpg`, `.mp4`). If the file extension is unknown, it MUST default to `.bin`
- `[?params]` - Optional query parameters for discovery hints - `[?params]` - Optional query parameters for discovery hints
@@ -24,15 +24,15 @@ blob:<sha256>.<ext>[?param1=value1&param2=value2...]
### Examples ### Examples
``` ```
blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf
blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.example.com blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.example.com
blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.png?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292 blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.png?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292
blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.bin blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.bin
``` ```
## Query Parameters ## Query Parameters
The `blob:` URI MAY include the following optional query parameters to assist with blob discovery: The `blossom:` URI MAY include the following optional query parameters to assist with blob discovery:
### `as` - Author ### `as` - Author
@@ -42,12 +42,12 @@ Clients can use this parameter to lookup the author's [BUD-03](./03.md) server l
Example: Example:
``` ```
blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0 blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0
``` ```
Multiple authors: Multiple authors:
``` ```
blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&as=781208004e09102d7da3b7345e64fd193cd1bc3fce8fdae6008d77f9cabcd036 blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&as=781208004e09102d7da3b7345e64fd193cd1bc3fce8fdae6008d77f9cabcd036
``` ```
### `xs` - Server ### `xs` - Server
@@ -58,17 +58,17 @@ The value SHOULD be a domain name only. Clients MUST assume the server operates
Example: Example:
``` ```
blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth
``` ```
With optional scheme: With optional scheme:
``` ```
blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=https://cdn.satellite.earth blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=https://cdn.satellite.earth
``` ```
Multiple servers: Multiple servers:
``` ```
blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth&xs=blossom.primal.net blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth&xs=blossom.primal.net
``` ```
### `sz` - Size ### `sz` - Size
@@ -82,7 +82,7 @@ The `sz` parameter MAY be used to specify the size of the blob in bytes. This ca
Example: Example:
``` ```
blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?sz=184292 blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?sz=184292
``` ```
The size MUST be a positive integer representing the exact number of bytes in the blob. Clients SHOULD verify that the downloaded blob size matches the `sz` parameter if provided. The size MUST be a positive integer representing the exact number of bytes in the blob. Clients SHOULD verify that the downloaded blob size matches the `sz` parameter if provided.
@@ -92,23 +92,23 @@ The size MUST be a positive integer representing the exact number of bytes in th
All parameters MAY be combined in a single URI: All parameters MAY be combined in a single URI:
``` ```
blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth&as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&xs=blossom.primal.net&sz=184292 blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth&as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&xs=blossom.primal.net&sz=184292
``` ```
## Client Implementation ## Client Implementation
### Parsing blob URIs ### Parsing blossom URIs
When parsing a `blob:` URI, clients MUST: When parsing a `blossom:` URI, clients MUST:
1. Verify the URI starts with the `blob:` scheme 1. Verify the URI starts with the `blossom:` scheme
2. Extract the 64 character hexadecimal sha256 hash 2. Extract the 64 character hexadecimal sha256 hash
3. Extract the file extension (which MUST be present) 3. Extract the file extension (which MUST be present)
4. Parse any query parameters (`as`, `xs`, and `sz`) into appropriate types to handle multiple values 4. Parse any query parameters (`as`, `xs`, and `sz`) into appropriate types to handle multiple values
### Resolution Strategy ### Resolution Strategy
When resolving a `blob:` URI to retrieve the actual blob, clients SHOULD attempt retrieval in the following order: When resolving a `blossom:` URI to retrieve the actual blob, clients SHOULD attempt retrieval in the following order:
1. **Server Hints**: If the URI contains `xs` parameters, attempt to retrieve the blob from each specified server in the order they appear 1. **Server Hints**: If the URI contains `xs` parameters, attempt to retrieve the blob from each specified server in the order they appear
- For servers without a protocol scheme, try `https://` first, then `http://` - For servers without a protocol scheme, try `https://` first, then `http://`
@@ -132,7 +132,7 @@ When downloading is complete, if the `sz` parameter was provided, clients SHOULD
Given this URI: Given this URI:
``` ```
blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.example.com&as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292 blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.example.com&as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292
``` ```
A client would: A client would:
@@ -144,9 +144,9 @@ A client would:
5. Verify the downloaded blob is exactly `184292` bytes 5. Verify the downloaded blob is exactly `184292` bytes
6. If still not found, fallback to well-known servers or local cache 6. If still not found, fallback to well-known servers or local cache
### Creating and Sharing blob URIs ### Creating and Sharing blossom URIs
When creating or sharing a `blob:` URI, clients MUST: When creating or sharing a `blossom:` URI, clients MUST:
1. Always include the sha256 hash 1. Always include the sha256 hash
2. Always include a file extension - if the file extension is unknown or cannot be determined, default to `.bin` (similar to how [BUD-01](./01.md#get-sha256---get-blob) defaults the MIME type to `application/octet-stream`) 2. Always include a file extension - if the file extension is unknown or cannot be determined, default to `.bin` (similar to how [BUD-01](./01.md#get-sha256---get-blob) defaults the MIME type to `application/octet-stream`)
@@ -162,12 +162,12 @@ Example of creating a URI after upload:
```javascript ```javascript
// After uploading to cdn.satellite.earth // After uploading to cdn.satellite.earth
const uri = `blob:${sha256}.${ext}?xs=cdn.satellite.earth&as=${userPubkey}&sz=${size}`; const uri = `blossom:${sha256}.${ext}?xs=cdn.satellite.earth&as=${userPubkey}&sz=${size}`;
``` ```
## Use Cases ## Use Cases
The `blob:` URI schema enables several use cases: The `blossom:` URI schema enables several use cases:
- **Decentralized Content Addressing**: Share content by hash with discovery hints instead of relying on a single server URL - **Decentralized Content Addressing**: Share content by hash with discovery hints instead of relying on a single server URL
- **Resilient Links**: Links that can survive server outages by including multiple server hints or author information - **Resilient Links**: Links that can survive server outages by including multiple server hints or author information
@@ -177,31 +177,31 @@ The `blob:` URI schema enables several use cases:
### Minimal URI ### Minimal URI
``` ```
blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf
``` ```
### Unknown File Type ### Unknown File Type
``` ```
blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.bin blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.bin
``` ```
### With Single Server Hint ### With Single Server Hint
``` ```
blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth
``` ```
### With Size and Author ### With Size and Author
``` ```
blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292 blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292
``` ```
### Full Featured URI ### Full Featured URI
``` ```
blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth&xs=blossom.primal.net&as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292 blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth&xs=blossom.primal.net&as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292
``` ```
### Image with Multiple Authors and Servers ### Image with Multiple Authors and Servers
``` ```
blob:a7b3c2d1e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1.png?xs=cdn.example.com&xs=media.nostr.build&as=781208004e09102d7da3b7345e64fd193cd1bc3fce8fdae6008d77f9cabcd036&as=b53185b9f27962ebdf76b8a9b0a84cd8b27f9f3d4abd59f715788a3bf9e7f75e&sz=2547831 blossom:a7b3c2d1e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1.png?xs=cdn.example.com&xs=media.nostr.build&as=781208004e09102d7da3b7345e64fd193cd1bc3fce8fdae6008d77f9cabcd036&as=b53185b9f27962ebdf76b8a9b0a84cd8b27f9f3d4abd59f715788a3bf9e7f75e&sz=2547831
``` ```