Expand description
plcbundle-rs: high-performance PLC bundle access, DID resolution, and tooling
This crate provides BundleManager and supporting types to work with PLC repositories
consisting of compressed JSONL bundle files. It focuses on:
- Fast random access via multi-frame compression and metadata offsets
- A memory-efficient DID index for lookups across bundles and mempool
- Query, export, verification, and sync utilities
§Quickstart
use plcbundle::{BundleManager, ManagerOptions, QuerySpec, BundleRange, QueryMode};
use std::path::PathBuf;
let mgr = BundleManager::new(PathBuf::from("/data/plc"), ManagerOptions::default())?;
// Resolve a DID
let resolved = mgr.resolve_did("did:plc:abcdef...")?;
assert!(resolved.locations_found >= 0);
// Query a bundle range
let spec = QuerySpec { bundles: BundleRange::Range(1, 10), filter: None, query: String::new(), mode: QueryMode::All };
for item in mgr.query(spec) { let _ = item?; }§Features
- Sync new bundles from a PLC source with deduplication and verified hashes
- Export results in JSONL with optional compression
- Rollback, migrate, clean, and rebuild indices
Modules§
- constants
- Global constants and helpers for filenames/paths, networking defaults, compression, index settings, and position conversions
- did_
index - Memory-mapped DID index with 256 shards and delta segments; packed
OpLocationencodes global position and nullified flag; supports build, verify, repair, and sampling - format
- Formatting helpers for bytes, durations, rates, and numbers used across CLI/server/library components
- handle_
resolver - AT Protocol handle resolver client using XRPC; includes validation and normalization helpers
- index
- Bundle repository index: load/save, sequence validation, and rebuild from bundle metadata
- mempool
- Persistent pre-bundle operation store with strict chronological validation, CID deduplication, incremental saving, and fast DID lookups
- plc_
client - Rate-limited HTTP client for PLC directory: fetch operations and DID documents with retries/backoff and token-bucket limiting
- processor
- Query engine and processor supporting simple path and JMESPath queries with parallel bundle processing and batched output
- remote
- Remote client for plcbundle instances: fetch index, bundles, operations, and DID documents; includes local index loader and URL normalization
- resolver
- DID resolution: build PLC DID state and convert to W3C DID Documents; handles legacy fields and endpoint normalization
- runtime
- Graceful shutdown coordination for server and background tasks, with unified shutdown future and fatal-error handling
- server
- sync
- PLC synchronization: events and logger, boundary-CID deduplication, one-shot and continuous modes, and robust error/backoff handling
Structs§
- Bundle
Info - Aggregated bundle information with optional details
- Bundle
Manager - High-level manager for PLC bundle repositories
- Chain
Verify Result - Result of chain verification across multiple bundles
- Chain
Verify Spec - Specification for chain verification
- Clean
Preview - Clean
Preview File - Clean
Result - DIDIndex
Stats - Export
Iterator - Export
Spec - Specification for export operations
- Info
Flags - Flags controlling
get_bundle_infodetail inclusion - Load
Options - Options controlling bundle loading behavior
- Load
Result - Result from a bundle load operation
- Manager
Options - Options for configuring BundleManager initialization
- Manager
Stats - Operation
- PLC Operation
- Operation
Filter - Operation
Request - Operation
Result - Result for single-operation fetch with timing
- Operation
With Location - Operation with location information (bundle number and position)
- Options
- Configuration options for the PLC bundle processor
- Options
Builder - Builder for Options
- Query
Iterator - Query
Spec - Specification for querying bundles
- Range
Iterator - Rebuild
Stats - Statistics from DID index rebuild
- Resolve
Result - Rollback
File Stats - Rollback
Plan - Plan produced by
rollback_plan - Rollback
Result - Result returned by
rollback - Rollback
Spec - Specification for rollback execution
- Verify
Result - Result of verifying a single bundle
- Verify
Spec - Specification for bundle verification
- Warm
UpSpec - Specification for cache warm-up
Enums§
- Bundle
Range - Bundle selection for queries, exports, and verification
- Export
Format - Output format for export
- Query
Mode - Sync
Result - Result of a sync_next_bundle operation
- Warm
UpStrategy - Strategy selection for warm-up
Traits§
- Into
Manager Options - Trait to allow passing ManagerOptions or using defaults