plcbundle 0.9.0-alpha.2

DID PLC Bundle Management Tool
Documentation

plcbundle-rs

A high-performance plcbundle management tool and library written in Rust.

Overview

plcbundle-rs provides a universal and efficient interface for managing PLC bundle repositories. It offers:

  • Rust Library: Core functionality with a clean, high-level API
  • CLI Tool: Comprehensive command-line interface for bundle operations
  • HTTP Server: Built-in server with WebSocket support
  • FFI Bindings: C and Go bindings for cross-language integration

Features

  • ✅ Bundle Management: Load, inspect, and manipulate PLC bundles
  • ✅ DID Resolution: Resolve DIDs and query operations
  • ✅ Synchronization: Sync with remote PLC servers
  • ✅ Verification: Verify bundle integrity and operation chains
  • ✅ Query & Export: Flexible querying and export capabilities
  • ✅ Index Management: Efficient DID indexing and lookup
  • ✅ Performance: Memory-mapped files, parallel processing, and optimized data structures

Installation

From Source

# Clone the repository
git clone https://tangled.org/atscan.net/plcbundle-rs
cd plcbundle-rs

# Build with default features (CLI, Server)
cargo build --release

# Install the binary
cargo install --path .

# or simply run
./target/release/plcbundle --help

As a Library

Add to your Cargo.toml:

[dependencies]
plcbundle = "0.9"

Quick Start

CLI Usage

# Initialize a new repository
plcbundle init --origin https://plc.directory

# Sync with remote server
plcbundle sync

# Query operations for a DID
plcbundle did <did:plc:...>

# Export bundles
plcbundle export --format ndjson

# Start HTTP server
plcbundle server --port 8080

# View repository status
plcbundle status

Library Usage

use plcbundle::{BundleManager, ManagerOptions};

// Initialize manager
let manager = BundleManager::new(
    "/path/to/bundles",
    ManagerOptions::default()
)?;

// Resolve a DID
let doc = manager.resolve_did("did:plc:example")?;

// Query operations
let ops = manager.get_did_operations("did:plc:example")?;

// Load a bundle
let result = manager.load_bundle(1, Default::default())?;

Project Structure

plcbundle-rs/
├── src/
│   ├── lib.rs              # Library entry point
│   ├── manager.rs          # Core BundleManager API
│   ├── cli/                # CLI commands
│   ├── server/             # HTTP server implementation
│   └── ...                 # Core modules
├── bindings/
│   └── go/                 # Go FFI bindings
├── docs/                   # Documentation
│   ├── API.md             # API reference
│   ├── BUNDLE_FORMAT.md   # Bundle format specification
│   └── ...
└── tests/                  # Integration tests

Documentation

Development

Building

# Build with all features
cargo build --all-features

# Run tests
cargo test

# Generate documentation
cargo doc --open

Features

  • cli (default): Enables CLI functionality
  • server: Enables HTTP server and WebSocket support

Running Tests

# Run all tests
cargo test

# Run specific test suite
cargo test --test manager
cargo test --test server --features server

🚨 Important for Contributors and AI Assistants

Please read RULES.md before contributing or generating code.

Key principle: CLI commands and server code NEVER open bundle files directly - all operations go through the BundleManager API.

License

Dual-licensed under MIT OR Apache-2.0

Author

Tree tree@tree.fail

Repository

https://tangled.org/atscan.net/plcbundle-rs