BlobService
BlobStore service: content-addressed chunk storage for large values. Values >= 4KB are split into 256KB chunks identified by SHA-256 hash. Content-addressing provides automatic deduplication.
Proto source
Transport
All methods are available via:
- gRPC on port 7080 — native high-performance API
- REST/JSON on port 7081 — HTTP/JSON transcoding via embedded structured-proxy
Methods
UploadBlob
Upload a blob as a stream of chunks. Returns the BlobRef (ordered chunk IDs + total size) for later retrieval.
HTTP: POST /v1/blobs
Request: stream BlobChunk
| Field | Type | Description |
|---|---|---|
data | bytes | Chunk data (up to 256KB per message). |
sequence | uint32 | Chunk sequence number (0-based, for ordering verification). |
Response: UploadBlobResponse
| Field | Type | Description |
|---|---|---|
blob_id | string | Unique blob identifier (hex-encoded composite of chunk hashes). |
chunk_ids | string[] | Ordered list of SHA-256 chunk hashes (hex, 64 chars each). |
total_size | uint64 | Total size of the uploaded blob in bytes. |
dedup_chunks | uint32 | Number of chunks that were deduplicated (already existed). |
DownloadBlob
Download a blob by its chunk IDs, returned as a stream of chunks.
HTTP: GET /v1/blobs/{blob_id}
Request: DownloadBlobRequest
| Field | Type | Description |
|---|---|---|
blob_id | string | Blob identifier returned from UploadBlob. |
Response: stream BlobChunk
| Field | Type | Description |
|---|---|---|
data | bytes | Chunk data (up to 256KB per message). |
sequence | uint32 | Chunk sequence number (0-based, for ordering verification). |
DeleteBlob
Delete a blob and its unreferenced chunks.
HTTP: DELETE /v1/blobs/{blob_id}
Request: DeleteBlobRequest
| Field | Type | Description |
|---|---|---|
blob_id | string | Blob identifier. |
Response: DeleteBlobResponse
| Field | Type | Description |
|---|---|---|
chunks_deleted | uint32 | Number of chunks actually deleted (excludes shared chunks still referenced). |
GetBlobMeta
Get blob metadata (chunk count, total size) without downloading.
HTTP: GET /v1/blobs/{blob_id}/meta
Request: GetBlobMetaRequest
| Field | Type | Description |
|---|---|---|
blob_id | string | Blob identifier. |
Response: BlobMeta
| Field | Type | Description |
|---|---|---|
blob_id | string | Blob identifier. |
total_size | uint64 | Total size in bytes. |
chunk_count | uint32 | Number of chunks. |
chunk_ids | string[] | Ordered list of SHA-256 chunk hashes. |
Types
BlobChunk
A single blob chunk in a streaming upload/download.
| Field | Type | Description |
|---|---|---|
data | bytes | Chunk data (up to 256KB per message). |
sequence | uint32 | Chunk sequence number (0-based, for ordering verification). |
BlobMeta
Blob metadata.
| Field | Type | Description |
|---|---|---|
blob_id | string | Blob identifier. |
total_size | uint64 | Total size in bytes. |
chunk_count | uint32 | Number of chunks. |
chunk_ids | string[] | Ordered list of SHA-256 chunk hashes. |
DeleteBlobRequest
Request to delete a blob.
| Field | Type | Description |
|---|---|---|
blob_id | string | Blob identifier. |
DeleteBlobResponse
Response after blob deletion.
| Field | Type | Description |
|---|---|---|
chunks_deleted | uint32 | Number of chunks actually deleted (excludes shared chunks still referenced). |
DownloadBlobRequest
Request to download a blob.
| Field | Type | Description |
|---|---|---|
blob_id | string | Blob identifier returned from UploadBlob. |
GetBlobMetaRequest
Request for blob metadata.
| Field | Type | Description |
|---|---|---|
blob_id | string | Blob identifier. |
UploadBlobResponse
Response after a complete blob upload.
| Field | Type | Description |
|---|---|---|
blob_id | string | Unique blob identifier (hex-encoded composite of chunk hashes). |
chunk_ids | string[] | Ordered list of SHA-256 chunk hashes (hex, 64 chars each). |
total_size | uint64 | Total size of the uploaded blob in bytes. |
dedup_chunks | uint32 | Number of chunks that were deduplicated (already existed). |