Crate dog_blob 

dog-blob: Production-ready blob storage infrastructure

dog-blob provides streaming-first, resumable, range-friendly blob storage for DogRS applications with zero boilerplate. It’s designed to eliminate all the routine media handling code that services shouldn’t have to write.

Key Features

• Streaming-first: Handle huge video files without buffering entire content in memory
• Multipart/resumable uploads: Built-in coordination for large files with automatic fallback
• Range requests: First-class support for video/audio scrubbing and partial content delivery
• Storage agnostic: Works with any backend (S3, filesystem, memory, custom implementations)
• Server agnostic: No HTTP coupling - works with any protocol (HTTP, gRPC, CLI, background jobs)
• Zero boilerplate: Services focus on business logic, not media mechanics

Quick Start

use dog_blob::prelude::*;
use tokio_util::io::ReaderStream;
use std::io::Cursor;
 
// 1. Create adapter with S3-compatible storage
let store = dog_blob::S3CompatibleStore::from_env()?;
let adapter = BlobAdapter::new(store, BlobConfig::default());
 
// 2. Create context for your tenant/user
let ctx = BlobCtx::new("my-app".to_string())
    .with_actor("user-123".to_string());
 
// 3. Upload a file
let data = b"Hello, world!";
let stream = ReaderStream::new(Cursor::new(data));
let put_request = BlobPut::new()
    .with_content_type("text/plain")
    .with_filename("hello.txt");
 
let receipt = adapter.put(ctx.clone(), put_request, Box::pin(stream)).await?;
 
// 4. Download with range support
let opened = adapter.open(ctx, receipt.id, None).await?;

Architecture

dog-blob follows a clean separation of concerns:

┌─────────────────┐
│   Your Service  │  ← Business logic only
├─────────────────┤
│   BlobAdapter   │  ← Media coordination
├─────────────────┤
│   BlobStore     │  ← Storage primitives
└─────────────────┘

The key insight: BlobAdapter is infrastructure, not a service. You embed it in your services:

use dog_blob::prelude::*;
 
pub struct MediaService {
    blobs: BlobAdapter,  // This is all you need!
}
 
impl MediaService {
    pub async fn upload_photo(&self, tenant_id: String, data: Vec<u8>) -> BlobResult<String> {
        let ctx = BlobCtx::new(tenant_id);
        let stream = futures::stream::once(async { Ok(bytes::Bytes::from(data)) });
         
        // One line handles all the blob complexity
        let receipt = self.blobs.put(ctx, BlobPut::new(), Box::pin(stream)).await?;
         
        Ok(receipt.id.to_string())
    }
}

Re-exports

pub use adapter::BlobAdapter;

pub use store::BlobInfo;

pub use store::BlobMetadata;

pub use store::BlobStore;

pub use store::MultipartBlobStore;

pub use store::SignedUrlBlobStore;

pub use store::BlobKeyStrategy;

pub use store::DefaultKeyStrategy;

pub use store::PutResult;

pub use store::GetResult;

pub use store::ObjectHead;

pub use store::StoreCapabilities;

Modules

adapter

prelude

Prelude for convenient imports

store

Structs

BlobConfig

Configuration for blob operations

BlobCtx

Context for blob operations (tenant, user, request info)

BlobId

Unique identifier for a blob

BlobPut

Request to store a blob

BlobReceipt

Receipt returned after successfully storing a blob

ByteRange

Byte range for partial content requests

ChunkSession

State tracking for a chunked upload session

ChunkSessionId

Unique identifier for a chunked upload session

DefaultUploadCoordinator

Default upload coordinator that handles both native multipart and staged assembly

MemoryUploadSessionStore

Simple in-memory upload session store provided by dog-blob

OpenedBlob

Result of opening a blob for reading

PartReceipt

Receipt for an uploaded part

ResolvedRange

Range information for partial content

S3CompatibleStore

Generic S3-compatible blob store implementation

S3Config

S3-compatible configuration from environment variables

UploadId

Unique identifier for an upload session

UploadIntent

Intent to upload a blob

UploadProgress

Progress tracking for upload sessions

UploadRules

Rules for multipart uploads

UploadSession

Upload session state

Enums

BlobError

Errors that can occur during blob operations

ChunkResult

Result of uploading a chunk

UploadStatus

Status of an upload session

Traits

UploadCoordinator

Coordinates multipart and resumable uploads

UploadSessionStore

Storage for upload session state

Type Aliases

BlobResult

Result type for blob operations

ByteStream

Stream of bytes for blob content