Work in progress Blossom BUD-05

2025-12-08 14:58:49 +00:00 · 2024-07-21 17:30:23 +02:00
parent 2dae1b0b24
commit 54cb633750
2 changed files with 117 additions and 0 deletions
--- a/buds/02.md
+++ b/buds/02.md
@@ -19,6 +19,28 @@ A blob descriptor is a JSON object containing `url`, `sha256`, `size`, `type`, a
 - `size` The size of the blob in bytes
 - `type` (optional) The MIME type of the blob
 - `uploaded` The unix timestamp of when the blob was uploaded to the server
+- `compressed` (optional) A JSON object containing the `sha256`, `size`, `library`, `version`, and `parameters` JSON object containing the compression parameters `quality` and `mode`. This field is optional and should only be included if the blob was compressed
+
+Blob Descriptor example:
+```json
+{
+  "sha256": "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553",
+  "uploaded": 1708773959,
+  "size": 123456,
+  "type": "application/pdf",
+  "compressed": {
+    "sha256": "e2e2e1d2b9c04e2a9914c245e3f789d230e3c2d5e3a0f5c6e4b4e3f9c7d4f3e2",
+    "size": 56789,
+    "library": "brotli",
+    "version": "1.0.7",
+    "parameters": {
+      "quality": 11,
+      "mode": "text"
+    }
+  }
+}
+
+```

 Servers may include additional fields in the descriptor like `magnet`, `infohash`, or `ipfs` depending on other protocols they support

--- a/buds/05.md
+++ b/buds/05.md
@@ -0,0 +1,95 @@
+BUD-05
+======
+
+Deterministic File Compression
+---------------
+
+`draft` `optional`
+
+## Overview
+
+This document outlines the implementation of a deterministic file compression method for Blossom, specifying the metadata that must be stored for each compressed blob and the endpoint for retrieving this metadata. 
+
+## Server Adaptation
+
+File storage servers `MUST` store the following metadata for each compressed blob:
+
+- File hash (sha256)
+- Uploaded timestamp (uploaded)
+- Original file size (size)
+- Original file type (type)
+- Compressed file hash (compressed.sha256)
+- Compressed file size (compressed.size)
+- Compression library (compression.library)
+- Compression library version (compression.version)
+- Compression library parameters (compression.parameters)
+
+Servers `MUST` normalize the blob metadata to ensure that the same compressed blob with the same parameters will always produce the same result, thereby ensuring deterministic compression and anonymizing any potential user data.
+
+## GET /metadata - Retrieve blob metadata
+
+The GET /metadata/<sha256> endpoint `MUST` return a [Blob Descriptor](https://github.com/hzrd149/blossom/blob/master/buds/02.md#blob-descriptor) containing the metadata fields for the requested blob or an error object if the blob does not exist.
+
+The endpoint `MUST` accept an optional file extension in the URL. ie. `.pdf`, `.png`, etc
+
+Example response:
+
+```json
+{
+  "url": "cdn.nostrcheck.me/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553",
+  "sha256": "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553",
+  "uploaded": 1708773959,
+  "size": 123456,
+  "type": "application/pdf",
+  "compressed": {
+    "sha256": "e2e2e1d2b9c04e2a9914c245e3f789d230e3c2d5e3a0f5c6e4b4e3f9c7d4f3e2",
+    "size": 56789,
+    "library": "brotli",
+    "version": "1.0.7",
+    "parameters": {
+      "quality": 11,
+      "mode": "text"
+    }
+  }
+}
+
+```
+
+## Example Flow
+
+1. Client signs authorization event and uploads blob to Server A with 'compress' field set to true
+1. Server A compresses the blob using it's preferred library and parameters
+1. Server A stores the blob metadata
+1. Server A returns [Blob Descriptor](./02.md#blob-descriptor)
+1. (Optional) Client verify the metadata matches the original blob compressing and comparing the blob locally with the same returned parameters
+1. Client uploads the compressed blob to Server B using the original authorization event and the 'compress' field set to false.
+
+1. Server B verifies blob hash metadata matches `x` tag in authorization event
+1. Server B stores the blob metadata
+1. Server B returns [Blob Descriptor](./02.md#blob-descriptor)
+1. (Optional) Client verify the metadata matches the original blob compressing the blob locally with the same parameters
+
+(optional using the /mirror endpoint)
+
+1. Client sends the `url` to Server C `/mirror` using the original authorization event
+1. Server C downloads blob from Server A or B using the url field
+1. Server C verifies downloaded blob hash matches `x` tag in authorization event
+1. Server C verify the metadata matches the original blob compressing the blob locally with the same parameters
+1. Server C returns [Blob Descriptor](./02.md#blob-descriptor)
+
+
+
+## Accepted Libraries, Versions, and Parameters
+
+The following libraries, versions, and parameters are accepted for deterministic compression:
+
+(This is just a DEMO table, the actual table will be updated with the final list of libraries, versions, and parameters)
+
+| Library | Version | Quality Range | Modes                  |
+|---------|---------|---------------|------------------------|
+| Brotli  | 1.0.7   | 0-11          | text, font, generic    |
+| Gzip    | 1.10    | 0-9           | text, font, generic    |
+| Zstd    | 1.4.5   | 1-22          | text, font, generic    |
+| Lz4     | 1.9.2   | 1-12          | text, font, generic    |
+
+