# heroforge Examples
This directory contains examples demonstrating the capabilities of heroforge.
## Quick Start
```bash
# Run any example
cargo run --example <example_name>
# Run with release optimizations (recommended for benchmarks)
cargo run --example <example_name> --release
```
## Examples Overview
### Basic Repository Operations
| `read_repo` | Read from an existing Heroforge repository | `cargo run --example read_repo -- path/to/repo.forge` |
| `find_and_read` | Find and read files using glob patterns | `cargo run --example find_and_read` |
| `print_file` | Print a file from a repository | `cargo run --example print_file -- <filepath>` |
### Repository Creation & Commits
| `version_test` | Create 10 versions of a file and verify with CLI | `cargo run --example version_test` |
| `branch_tag_test` | Test branches and tags functionality | `cargo run --example branch_tag_test` |
| `create_web_repo` | Create a repository for testing with heroforge web UI | `cargo run --example create_web_repo` |
| `full_demo` | Create complete project history with branches/tags | `cargo run --example full_demo` |
### Testing & Benchmarks
| `perf_test` | Performance benchmarks for all operations | `cargo run --example perf_test --release` |
| `comprehensive_test` | Test many edge cases (deep dirs, large files, etc.) | `cargo run --example comprehensive_test` |
| `stress_test` | Stress tests (200+ commits, concurrent repos) | `cargo run --example stress_test` |
### Sync Operations
| `sync_demo` | Demonstrate sync capabilities | `cargo run --example sync_demo` |
| `sync_test` | Test sync between local repositories | `cargo run --example sync_test` |
| `http_sync_test` | Test HTTP sync with heroforge server | `cargo run --example http_sync_test --features sync-http` |
| `tcp_sync_benchmark` | Benchmark TCP sync with compression/encryption | `cargo run --example tcp_sync_benchmark --features sync-tcp-full -- /path/to/repo.forge` |
### QUIC Protocol (requires `sync-quic` feature)
| `quic_server` | QUIC sync server | `cargo run --example quic_server --features sync-quic -- repo.forge <port>` |
| `quic_client` | QUIC sync client | `cargo run --example quic_client --features sync-quic -- repo.forge <server_addr>` |
| `quic_simple_test` | Simple QUIC connectivity test | `cargo run --example quic_simple_test --features sync-quic -- source.forge` |
| `quic_sync_benchmark` | Benchmark QUIC sync performance | `cargo run --example quic_sync_benchmark --features sync-quic --release -- /path/to/repo.forge` |
| `quic_incremental_sync_test` | Test incremental sync (1000 files, modify 4) | `cargo run --example quic_incremental_sync_test --features sync-quic --release` |
## Performance Testing
The `perf_test` example runs comprehensive performance benchmarks:
```bash
cargo run --example perf_test --release
```
This tests:
- Repository initialization
- Single-file commits (100 commits)
- Multi-file commits (50 files)
- Large file operations (1MB, 5MB)
- File listing and reading
- Branch and tag creation
- Check-in listing
Example output:
```
=== heroforge Performance Tests ===
Repository init: 18.44 ms
Initial check-in: 0.80 ms
100 single-file commits: 44.63 ms (0.45 ms/commit)
50-file commit: 1.42 ms (0.03 ms/file)
List 50 files: 0.06 ms
Read 50 files: 2.11 ms (0.04 ms/file)
Write 1 MB file: 3.94 ms (253.97 MB/s)
Read 1 MB file: 0.56 ms (1769.91 MB/s)
Create branch: 4.21 ms
Add tag: 0.97 ms
List 100 check-ins: 1.19 ms
List branches/tags: 0.07 ms (3 branches, 1 tags)
[PASS] All performance tests completed!
```
## TCP Sync Benchmark
To run the TCP sync benchmark, you need a Heroforge repository:
```bash
# First, get a Heroforge repository (e.g., clone the heroforge-scm repo)
heroforge clone https://heroforge-scm.org/home /tmp/heroforge-scm.forge
# Run the benchmark with all TCP features
cargo run --example tcp_sync_benchmark --features sync-tcp-full --release -- /tmp/heroforge-scm.forge
```
This benchmarks:
1. LZ4 compression only
2. No compression
3. LZ4 + ChaCha20-Poly1305 encryption
## QUIC Sync Benchmark
Similar to TCP, but using QUIC protocol with built-in TLS 1.3:
```bash
# Get a test repository
heroforge clone https://heroforge-scm.org/home /tmp/heroforge-scm.forge
# Run the QUIC benchmark
cargo run --example quic_sync_benchmark --features sync-quic --release -- /tmp/heroforge-scm.forge
```
## Incremental Sync Test
The `quic_incremental_sync_test` demonstrates efficient delta synchronization:
```bash
cargo run --example quic_incremental_sync_test --features sync-quic --release
```
This test:
1. Creates a repository with 1000 files
2. Syncs all files to a destination via QUIC
3. Modifies only 4 files in the source
4. Syncs again - **only 5 artifacts transfer** (4 files + 1 manifest)
Example output:
```
Initial sync:
- Artifacts sent: 1003
Incremental sync:
- Artifacts sent: 5
- Expected: ~5 (4 modified files + 1 manifest)
✓ TEST PASSED: Incremental sync correctly transferred only modified files!
```
## Feature Flags
Some examples require specific feature flags:
| Feature | Description | Examples |
| --------------- | -------------------------------------- | -------------------- |
| `sync-http` | HTTP sync support | `http_sync_test` |
| `sync-tcp-full` | TCP sync with compression + encryption | `tcp_sync_benchmark` |
| `sync-quic` | QUIC protocol sync | `quic_*` examples |
## Testing with Heroforge Web UI
Several examples create repositories you can explore with the Heroforge web UI:
```bash
# Run an example that creates a repo
cargo run --example create_web_repo
# Open with heroforge UI
heroforge ui /tmp/fossil_web_test/myproject.forge
```
Or use `full_demo` which automatically opens the UI:
```bash
cargo run --example full_demo
```
## Shell Script
The `quic_test.sh` script provides a quick way to test QUIC sync:
```bash
./examples/quic_test.sh
```