API Overview

This page summarizes the public Rust API surface of the Cobble crates.

cobble (Core Crate)

Primary Types

Type	Description
`SingleDb`	Single-machine embedded database (wraps Db + Coordinator)
`Db`	Shard database for distributed deployments
`ReadOnlyDb`	Read-only snapshot access
`Reader`	Snapshot-following read proxy (visibility advances by snapshot cadence)
`DbCoordinator`	Global snapshot coordinator

Scan Types

Type	Description
`ScanPlan`	Distributed scan plan from a global snapshot
`ScanSplit`	Serializable unit of scan work (one per shard)
`ScanSplitPartition`	Pair of `before` / `after` splits around one bucket/key boundary
`ScanSplitScanner`	Iterator over key-value pairs within a split

Configuration Types

Type	Description
`Config`	Main database configuration
`CoordinatorConfig`	Coordinator configuration
`VolumeDescriptor`	Storage volume descriptor
`VolumeUsageKind`	Volume usage kind enum
`ReadOptions`	Point lookup options
`ScanOptions`	Scan/iteration options
`WriteOptions`	Write operation options

Filesystem Extension Types

Type / Function	Description
`ProcessFileSystemRequest`	Request context passed to process-level custom filesystem resolution (original and normalized base dir, parsed URL, credentials, custom options).
`ProcessFileSystemRegistry`	Trait for host-side custom filesystem resolution (`try_init`).
`register_process_custom_file_system_registry(...)`	Registers one process-level custom filesystem registry used as fallback when built-in resolution/access fails.
`clear_process_custom_file_system_registry()`	Clears the current process-level custom filesystem registry.

Resolution order is built-in first, then process-level fallback. If a custom registry is configured, Cobble also falls back when built-in filesystem initialization succeeds but the initial access probe fails.

Metadata & Schema Types

Type	Description
`Schema`	Current raw schema with family-local metadata
`SchemaBuilder`	Schema evolution builder; column-family aware via optional family arguments
`ShardSnapshotInput`	Shard snapshot DTO used by the coordinator
`GlobalSnapshotManifest`	Materialized global snapshot manifest

Column Family Model

The default family is default.
Plain raw put / merge / delete / get / scan APIs use the default family.
Raw Rust selects other families through WriteOptions::with_column_family, ReadOptions::for_column_in_family / for_columns_in_family / with_column_family, and ScanOptions::with_column_family.
Named families are created through SchemaBuilder, not through config.
Distributed routing stays bucket-only, but for Reader and ScanPlan, the column family should be selected through options. That means only one family is read or scan per operation.

ColumnFamilyOptions and TTL Behavior

SchemaBuilder::set_column_family_options allows setting ColumnFamilyOptions for each family, which currently only includes value_has_ttl. Setting this to false allows the cobble optimize storage for values without TTL.
value_has_ttl controls whether write-time TTL input is effective in that family:
- true: write-time TTL may set expiration
- false: write-time TTL input is ignored

Compaction Types

Type	Description
`RemoteCompactionServer`	Remote compaction worker server

Key Operations

SingleDb

SingleDb::open(config) -> Result<SingleDb>
SingleDb::resume(config, global_snapshot_id) -> Result<SingleDb>
db.put(bucket, key, column, value) -> Result<()>
db.put_with_options(bucket, key, column, value, &WriteOptions::with_column_family("metrics")) -> Result<()>
db.merge(bucket, key, column, value) -> Result<()>
db.delete(bucket, key, column) -> Result<()>
db.get_with_options(bucket, key, &read_options) -> Result<Option<Vec<Option<Bytes>>>>
db.scan_with_options(bucket, range, &ScanOptions::for_column(0).with_column_family("metrics")) -> Result<DbIterator<'_>>
db.snapshot() -> Result<u64>
db.snapshot_with_callback(callback) -> Result<u64>

Db

Db::open(config, bucket_ranges) -> Result<Db>
Db::open_from_snapshot(config, snapshot_id, db_id) -> Result<Db>
Db::open_new_with_snapshot(config, snapshot_id, source_db_id) -> Result<Db>
Db::open_new_with_manifest_path(config, manifest_path) -> Result<Db>
ReadOnlyDb::open_with_db_id(config, snapshot_id, db_id) -> Result<ReadOnlyDb>
db.current_schema() -> Arc<Schema>
db.update_schema() -> SchemaBuilder
db.put(bucket, key, column, value) -> Result<()>
db.get_with_options(bucket, key, &read_options) -> Result<Option<Vec<Option<Bytes>>>>
db.scan(bucket, range) -> Result<DbIterator<'_>>
db.scan_bounds(bucket, start_key_inclusive, end_key_exclusive) -> Result<DbIterator<'_>>
db.scan_with_options(bucket, range, &scan_options) -> Result<DbIterator<'_>>
db.scan_with_options_bounds(bucket, start_key_inclusive, end_key_exclusive, &scan_options) -> Result<DbIterator<'_>>
read_only.scan(bucket, range) -> Result<DbIterator<'static>>
read_only.scan_bounds(bucket, start_key_inclusive, end_key_exclusive) -> Result<DbIterator<'static>>
read_only.scan_with_options(bucket, range, &scan_options) -> Result<DbIterator<'static>>
read_only.scan_with_options_bounds(bucket, start_key_inclusive, end_key_exclusive, &scan_options) -> Result<DbIterator<'static>>
db.snapshot() -> Result<u64>
db.snapshot_with_callback(callback) -> Result<u64>
db.cancel_snapshot(snapshot_id) -> Result<bool>
db.expire_snapshot(snapshot_id) -> Result<bool>
db.retain_snapshot(snapshot_id) -> bool
db.shard_snapshot_input(snapshot_id) -> Result<ShardSnapshotInput>

open_from_snapshot preserves the source db identity and snapshot directory. open_new_with_snapshot restores from the source snapshot but assigns a fresh db id and starts a new snapshot chain. open_new_with_manifest_path does the same thing when your checkpoint metadata already stores the exact source manifest path.

Snapshot lifecycle notes:

db.snapshot() returns a snapshot id after the async materialization flow has been scheduled.
db.snapshot_with_callback(...) delivers a ShardSnapshotInput once manifest publication finishes.
db.cancel_snapshot(snapshot_id) only succeeds before manifest publication completes.
db.expire_snapshot(snapshot_id) releases snapshot ownership and file references.
db.retain_snapshot(snapshot_id) keeps a completed snapshot alive across retention passes.

Reader

Reader::open_current(reader_config) -> Result<Reader>
reader.get_with_options(bucket, key, &read_options) -> Result<Option<Vec<Option<Bytes>>>>
reader.current_global_snapshot() -> &GlobalSnapshotManifest
reader.refresh() -> Result<()>

Scan

ScanPlan::new(manifest) -> ScanPlan // bucket-only
plan.splits() -> Vec<ScanSplit>
split.split_after(bucket, key) -> Result<ScanSplitPartition>
split.create_scanner(config, &scan_options) -> Result<ScanSplitScanner> // choose non-default family here via ScanOptions
for row in scanner { let (bucket, key, columns) = row?; }

cobble-data-structure (Structured Wrappers)

Types

Type	Description
`StructuredSingleDb`	Structured SingleDb wrapper
`StructuredDb`	Structured Db wrapper
`StructuredReadOnlyDb`	Structured ReadOnlyDb wrapper
`StructuredReader`	Structured Reader wrapper
`StructuredScanPlan`	Structured scan plan
`StructuredScanSplit`	Structured scan split with optional resume/end boundary metadata
`StructuredScanSplitScanner`	Structured scan scanner yielding `(bucket, key, columns)` rows
`StructuredRemoteCompactionServer`	Remote compaction with structured merge ops

Structured values are represented with StructuredColumnValue and configured by StructuredSchema (Bytes / List column types).

StructuredSchema is also family-aware: column_families() returns per-family typed columns keyed by family name and always includes default, while StructuredSchemaBuilder methods accept Option<String> family arguments. Structured wrappers use StructuredWriteOptions / StructuredReadOptions / StructuredScanOptions for family selection.

StructuredDb also mirrors the new bounds-scan entrypoints: scan_bounds(...) and scan_with_options_bounds(...) use the same inclusive-start / exclusive-end semantics as raw Db.

cobble-web-monitor

Types

Type	Description
`MonitorConfig`	Web monitor configuration
`MonitorServer`	HTTP server for monitoring dashboard
`MonitorServerHandle`	Handle to control the running server

cobble-java

The Java API mirrors the Rust API. See Java Bindings for usage details. On the Java side, restore flows are exposed as Db.restore(..., boolean newDbId) and Db.restoreWithManifest(...).

Java Classes

Class	Rust Equivalent
`io.cobble.SingleDb`	`SingleDb`
`io.cobble.Db`	`Db`
`io.cobble.ReadOnlyDb`	`ReadOnlyDb`
`io.cobble.Reader`	`Reader`
`io.cobble.Config`	`Config`
`io.cobble.ReadOptions` / `ScanOptions` / `WriteOptions`	Raw family-aware options
`io.cobble.Schema` / `SchemaBuilder`	Raw schema view and evolution builder
`io.cobble.ShardSnapshot` / `GlobalSnapshot`	Snapshot DTOs that preserve named family mapping
`io.cobble.ScanPlan`	`ScanPlan`
`io.cobble.ScanSplit`	`ScanSplit`
`io.cobble.ScanCursor`	Raw scan iterator cursor
`io.cobble.DirectColumns`	Zero-copy raw direct read view
`io.cobble.DirectEncodedRow`	Raw encoded direct row view with InputStream-based column decoder
`io.cobble.DirectScanCursor` / `DirectScanEntry`	Raw direct scan cursor and row view
`io.cobble.ProcessFileSystems`	Process-level custom filesystem registration entrypoint
`io.cobble.ProcessFileSystemRequest`	Java DTO for fallback filesystem resolution context
`io.cobble.CustomFileSystemRegistry`	Java callback interface for resolving custom filesystems
`io.cobble.CustomFileSystem`	Java filesystem abstraction consumed by Cobble JNI
`io.cobble.CustomRandomAccessFile`	Random-read file abstraction; supports optional direct read path via `supportDirect()` / `readAtDirect(...)`
`io.cobble.CustomSequentialWriteFile`	Sequential-write file abstraction; supports optional direct write path via `supportDirect()` / `writeDirect(...)`
`io.cobble.structured.SingleDb`	Structured `SingleDb`
`io.cobble.structured.Db`	Structured `Db`
`io.cobble.structured.Schema` / `StructuredSchemaBuilder`	Structured family-aware schema API
`io.cobble.structured.DirectListValueBuilder`	Reusable direct builder for Cobble core list payloads
`io.cobble.structured.StructuredScanSplit`	Structured distributed split
`io.cobble.structured.ScanCursor`	Structured scan iterator cursor
`io.cobble.structured.DirectRow`	Structured zero-copy direct read view, including direct list-element accessors
`io.cobble.structured.DirectEncodedRow`	Structured encoded direct row view with InputStream-based BYTES/LIST decoders
`io.cobble.structured.DirectScanCursor` / `DirectScanRow`	Structured direct scan cursor and row view