Blobinator #

Tools and HTTP service for temporary binary blob storage.

Blobinator is a Dart package that provides a key-value store for binary data with versioning, TTL (time-to-live), and HTTP API support. Perfect for temporary file storage, caching, and data exchange.

Features #

• Multiple Storage Backends: In-memory SQLite, file-based SQLite, and hybrid (memory + disk, experimental)
• Versioning: Optimistic concurrency control with automatic version generation
• TTL Support: Automatic expiration and cleanup of expired blobs
• HTTP API: RESTful endpoints for blob operations via built-in server
• CLI Tools: Command-line interface for both server and client operations
• Performance: Optimized SQLite configuration with WAL mode and maintenance tasks

Quick Start #

As a Library #

import 'package:blobinator/blobinator.dart';

// Create in-memory storage
final blobinator = await Blobinator.inMemory();

// Store binary data
final key = 'my-key'.codeUnits;
final data = 'Hello, World!'.codeUnits;
await blobinator.updateBlob(key, data, ttl: Duration(minutes: 30));

// Retrieve data
final blob = await blobinator.getBlob(key);
print(utf8.decode(blob!.bytes)); // Hello, World!

// Clean up
await blobinator.close();

HTTP Server #

# Start server with in-memory storage
dart run blobinator serve --port 8080

# Start with file-based storage
dart run blobinator serve --port 8080 --path /path/to/storage.db

# Start with hybrid storage (memory cache + disk persistence)
dart run blobinator serve --port 8080 --hybrid --path /path/to/storage.db

CLI Client #

# Store blob from file
dart run blobinator client --url http://localhost:8080 update --key mykey --input data.bin --ttl 1h

# Retrieve blob to stdout
dart run blobinator client --url http://localhost:8080 get --key mykey

# Get metadata
dart run blobinator client --url http://localhost:8080 get-metadata --key mykey

# Delete blob
dart run blobinator client --url http://localhost:8080 delete --key mykey

# Server status
dart run blobinator client --url http://localhost:8080 status

Storage Backends #

• In-Memory: Fast, volatile storage using SQLite's :memory: database
• File-Based: Persistent SQLite database stored on disk
• Hybrid: Combines fast in-memory access with automatic migration to disk for persistence

HTTP API #

• GET /status - Server statistics
• HEAD /blobs/{key} - Blob metadata
• GET /blobs/{key} - Retrieve blob
• PUT /blobs/{key} - Create/update blob
• DELETE /blobs/{key} - Delete blob

Supports UTF-8 and base64-encoded keys, version-based updates, and TTL parameters.

Installation #

Add to your pubspec.yaml:

dependencies:
  blobinator: ^0.1.2

Or install globally:

dart pub global activate blobinator

Configuration #

final config = BlobinatorConfig(
  keyMaxLength: 1024,        // Maximum key size
  valueMaxLength: 10 * 1024, // Maximum value size  
  defaultTtl: Duration(hours: 1), // Default expiration
);

Example #

See example/example.dart for a comprehensive demonstration of HTTP client usage including:

• Basic CRUD operations
• Version-based optimistic concurrency control
• TTL functionality
• Different key formats (UTF-8, binary, special cases)
• Error handling and edge cases

dart run example/example.dart

For more details, see the API documentation and examples in the repository.