atscan.net
High-performance implementation of plcbundle written in Rust
docs: rewrite README
tree.fail
+160
-2
+160
-2
README.md
+160
-2
README.md
···
1
1
# plcbundle-rs
2
2
3
-
Main purpose of this package is to provide universal and simple interface, as Rust library or C/GO bindings for manipulation with plcbundle repository.
3
+
A high-performance [plcbundle](https://tangled.org/atscan.net/plcbundle/) management tool and library written in Rust.
4
+
5
+
## Overview
6
+
7
+
`plcbundle-rs` provides a universal and efficient interface for managing PLC bundle repositories. It offers:
8
+
9
+
- **Rust Library**: Core functionality with a clean, high-level API
10
+
- **CLI Tool**: Comprehensive command-line interface for bundle operations
11
+
- **HTTP Server**: Built-in server with WebSocket support
12
+
- **FFI Bindings**: C and Go bindings for cross-language integration
13
+
14
+
## Features
15
+
16
+
- ✅ **Bundle Management**: Load, inspect, and manipulate PLC bundles
17
+
- ✅ **DID Resolution**: Resolve DIDs and query operations
18
+
- ✅ **Synchronization**: Sync with remote PLC servers
19
+
- ✅ **Verification**: Verify bundle integrity and operation chains
20
+
- ✅ **Query & Export**: Flexible querying and export capabilities
21
+
- ✅ **Index Management**: Efficient DID indexing and lookup
22
+
- ✅ **Performance**: Memory-mapped files, parallel processing, and optimized data structures
23
+
24
+
## Installation
25
+
26
+
### From Source
27
+
28
+
```bash
29
+
# Clone the repository
30
+
git clone https://tangled.org/atscan.net/plcbundle-rs
31
+
cd plcbundle-rs
32
+
33
+
# Build with default features (CLI)
34
+
cargo build --release
35
+
36
+
# Install the CLI tool
37
+
cargo install --path .
38
+
```
39
+
40
+
### As a Library
41
+
42
+
Add to your `Cargo.toml`:
43
+
44
+
```toml
45
+
[dependencies]
46
+
plcbundle = "0.9"
47
+
```
48
+
49
+
## Quick Start
50
+
51
+
### CLI Usage
52
+
53
+
```bash
54
+
# Initialize a new repository
55
+
plcbundle init --origin https://plc.directory
56
+
57
+
# Sync with remote server
58
+
plcbundle sync
59
+
60
+
# Query operations for a DID
61
+
plcbundle did <did:plc:...>
62
+
63
+
# Export bundles
64
+
plcbundle export --format ndjson
65
+
66
+
# Start HTTP server
67
+
plcbundle server --port 8080
68
+
69
+
# View repository status
70
+
plcbundle status
71
+
```
72
+
73
+
### Library Usage
74
+
75
+
```rust
76
+
use plcbundle::{BundleManager, ManagerOptions};
77
+
78
+
// Initialize manager
79
+
let manager = BundleManager::new(
80
+
"/path/to/bundles",
81
+
ManagerOptions::default()
82
+
)?;
83
+
84
+
// Resolve a DID
85
+
let doc = manager.resolve_did("did:plc:example")?;
86
+
87
+
// Query operations
88
+
let ops = manager.get_did_operations("did:plc:example")?;
89
+
90
+
// Load a bundle
91
+
let result = manager.load_bundle(1, Default::default())?;
92
+
```
93
+
94
+
## Project Structure
95
+
96
+
```
97
+
plcbundle-rs/
98
+
├── src/
99
+
│ ├── lib.rs # Library entry point
100
+
│ ├── manager.rs # Core BundleManager API
101
+
│ ├── cli/ # CLI commands
102
+
│ ├── server/ # HTTP server implementation
103
+
│ └── ... # Core modules
104
+
├── bindings/
105
+
│ └── go/ # Go FFI bindings
106
+
├── docs/ # Documentation
107
+
│ ├── API.md # API reference
108
+
│ ├── BUNDLE_FORMAT.md # Bundle format specification
109
+
│ └── ...
110
+
└── tests/ # Integration tests
111
+
```
112
+
113
+
## Documentation
114
+
115
+
- [API Documentation](docs/API.md) - Complete API reference
116
+
- [Bundle Format](docs/BUNDLE_FORMAT.md) - Bundle file format specification
117
+
- [Logging](docs/LOGGING.md) - Logging configuration
118
+
- [Specification](docs/specification.md) - PLC specification
119
+
120
+
## Development
121
+
122
+
### Building
123
+
124
+
```bash
125
+
# Build with all features
126
+
cargo build --all-features
127
+
128
+
# Run tests
129
+
cargo test
130
+
131
+
# Generate documentation
132
+
cargo doc --open
133
+
```
134
+
135
+
### Features
136
+
137
+
- `cli` (default): Enables CLI functionality
138
+
- `server`: Enables HTTP server and WebSocket support
139
+
140
+
### Running Tests
141
+
142
+
```bash
143
+
# Run all tests
144
+
cargo test
145
+
146
+
# Run specific test suite
147
+
cargo test --test manager
148
+
cargo test --test server --features server
149
+
```
4
150
5
151
## 🚨 Important for Contributors and AI Assistants
6
152
7
153
**Please read [`RULES.md`](RULES.md) before contributing or generating code.**
8
154
9
-
Key principle: **CLI commands and server code NEVER open bundle files directly** - all operations go through the `BundleManager` API.
155
+
Key principle: **CLI commands and server code NEVER open bundle files directly** - all operations go through the `BundleManager` API.
156
+
157
+
## License
158
+
159
+
Dual-licensed under MIT OR Apache-2.0
160
+
161
+
## Author
162
+
163
+
Tree <tree@tree.fail>
164
+
165
+
## Repository
166
+
167
+
https://tangled.org/atscan.net/plcbundle-rs