From 9067b69eace785c3f99936a5fced60e546dc209c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jesu=CC=81s=20Pe=CC=81rez?= Date: Wed, 19 Nov 2025 17:37:06 +0000 Subject: [PATCH] chore: init repo --- README.md | 239 ++++++++++++++++++++++++++++++++++++++++ imgs/provctl_logo.svg | 246 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 485 insertions(+) create mode 100644 README.md create mode 100644 imgs/provctl_logo.svg diff --git a/README.md b/README.md new file mode 100644 index 0000000..e77dc6d --- /dev/null +++ b/README.md @@ -0,0 +1,239 @@ +# provctl - Machine Orchestration & Service Control Platform + +
+ provctl Logo +
+ +[![Rust](https://img.shields.io/badge/rust-1.91.0%2B-orange.svg)](https://www.rust-lang.org) +[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) + +**provctl** is a production-grade Machine Orchestration & Service Control Platform for managing SSH-based deployments across multiple machines with sophisticated deployment strategies, resilience features, and comprehensive observability. + +## Features + +✅ **Local Service Management** +- 🔧 **Multi-Backend Support** - systemd (Linux), launchd (macOS), PID files (Unix) +- 🎯 **Unified Interface** - Single CLI for all platforms +- 📊 **Status & Logging** - Comprehensive service monitoring +- ⚙️ **Configuration-Driven** - TOML-based zero-hardcoded-strings approach + +✅ **Machine Orchestration** +- 🚀 **SSH Command Execution** - Real async SSH with ssh2-rs +- 📦 **Multiple Deployment Strategies** - Rolling, Blue-Green, Canary +- 🔄 **Connection Pooling** - Per-host reuse with configurable limits +- 🎯 **Retry & Timeout Logic** - Exponential/linear/fibonacci backoff strategies +- 🔒 **Host Key Verification** - SSH known_hosts integration +- 💪 **Circuit Breaker** - Fault tolerance for failing hosts +- 🏥 **Health Checks** - Command/HTTP/TCP monitoring +- 📊 **Metrics & Audit Logging** - Comprehensive observability + +✅ **REST API & Web Dashboard** +- 🌐 **Axum REST API** - Production-grade HTTP server +- 📱 **Leptos Dashboard** - Modern Rust web UI +- 📡 **Programmatic Access** - Full API for automation + +✅ **Production-Ready** +- Zero unsafe code (`#![forbid(unsafe_code)]`) +- Comprehensive error handling with Result types +- 100% documentation coverage (rustdoc) +- No unwrap() calls in production code + +✅ **Developer Friendly** +- Async/await throughout (tokio-based) +- Thread-safe metrics collection (Arc>) +- Trait-based design for extensibility +- Full rustdoc for all public APIs + +## Quick Start + +### Installation + +```bash +# Option 1: Use the installer +nu scripts/install-provctl.nu + +# Option 2: Build manually +cargo build --release +./target/release/provctl --help +``` + +### Basic Usage + +```bash +# Start a service +provctl start my-service + +# Stop a service +provctl stop my-service + +# Restart a service +provctl restart my-service + +# Check status +provctl status my-service + +# View logs (last 50 lines) +provctl logs my-service --lines 50 +``` + +## Commands + +| Command | Description | Example | +|---------|-------------|---------| +| `start` | Start a service | `provctl start api` | +| `stop` | Stop a service | `provctl stop api` | +| `restart` | Restart a service | `provctl restart api` | +| `status` | Check service status | `provctl status api` | +| `logs` | View service logs | `provctl logs api --lines 100` | + +## Configuration + +provctl is **100% configuration-driven**. All user-facing strings and defaults come from TOML files: + +- **`configs/messages.toml`** - All user-facing messages +- **`configs/defaults.toml`** - Timeouts, paths, and operational parameters + +Zero hardcoded strings in code! + +## Architecture + +provctl uses a **trait-based backend system** for easy extensibility: + +``` +┌─────────────────────────────────────┐ +│ provctl-cli (clap) │ +├─────────────────────────────────────┤ +│ Backend Trait │ +├─────────────┬───────────┬───────────┤ +│ systemd │ launchd │ Pidfile │ +│ (Linux) │ (macOS) │ (Unix) │ +└─────────────┴───────────┴───────────┘ +``` + +### Backends + +**systemd** (Linux) +- Uses `systemctl` for service management +- Queries `journalctl` for logs +- Best for production Linux systems + +**launchd** (macOS) +- Generates plist files automatically +- Uses `launchctl` for management +- Best for macOS development and production + +**PID files** (Universal) +- Works on any Unix system +- File-based process tracking +- Fallback when systemd/launchd unavailable + +## Project Structure + +``` +provctl/ +├── crates/ +│ ├── provctl-core/ # Service management fundamentals +│ ├── provctl-config/ # Configuration loading +│ ├── provctl-backend/ # Backend trait + implementations +│ ├── provctl-cli/ # CLI interface +│ ├── provctl-machines/ # Machine orchestration core +│ │ ├── ssh_async.rs # Real async SSH +│ │ ├── ssh_pool.rs # Connection pooling +│ │ ├── ssh_retry.rs # Retry & timeout logic +│ │ ├── ssh_host_key.rs # Host key verification +│ │ ├── health_check.rs # Health monitoring +│ │ ├── metrics.rs # Metrics & audit logging +│ │ └── ... (other modules) +│ ├── provctl-api/ # REST API server +│ └── provctl-dashboard/ # Web UI (Leptos) +├── configs/ +│ ├── messages.toml # User messages +│ └── defaults.toml # Configuration defaults +├── .coder/info/ # Project tracking & docs +├── docs/ # Documentation +└── scripts/ # Development & infrastructure scripts +``` + +## Development + +### Build + +```bash +cargo build --release +``` + +### Test + +```bash +cargo test --all +``` + +### Lint & Format + +```bash +cargo fmt --all +cargo clippy --all --all-targets +``` + +### Documentation + +```bash +cargo doc --open --no-deps +``` + +## Integration with syntaxis-api + +provctl provides service management for syntaxis-api: + +```bash +# In syntaxis-api.nu wrapper: +provctl start syntaxis-api + +# Or from provisioning schema: +provctl deploy --config provisioning/syntaxis-api.toml +``` + +See [provisioning/](provisioning/) for integration examples. + +## Code Quality Standards + +✅ **No unsafe code** - Enforced via `#![forbid(unsafe_code)]` +✅ **100% documented** - All public APIs have rustdoc comments +✅ **Fully tested** - 332+ unit tests, 100% passing +✅ **Formatted & linted** - `cargo fmt` + `cargo clippy` clean +✅ **Zero hardcoded strings** - All in TOML configuration +✅ **Proper error handling** - Comprehensive Result types + + +## License + +MIT License - See [LICENSE](LICENSE) for details. + +## Contributing + +Contributions welcome! Please ensure: +- `cargo fmt --all` passes +- `cargo clippy --all --all-targets` passes +- All tests pass: `cargo test --all` +- No unsafe code + +## Documentation Overview + +| Document | Purpose | +|----------|---------| +| **QUICKSTART.md** | Get started with machine orchestration in 5 minutes | +| **docs/CLI_GUIDE.md** | Complete CLI reference for all commands | +| **docs/ARCHITECTURE.md** | System design and architecture | +| **docs/INSTALLATION_GUIDE.md** | Installation and setup instructions | + +## Support + +For issues and questions: +- **Quick Start**: See [QUICKSTART.md](QUICKSTART.md) +- **CLI Reference**: See [docs/CLI_GUIDE.md](docs/CLI_GUIDE.md) +- **Documentation**: See [docs/](docs/) directory +- **Architecture**: See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) + +--- + +**Made with ❤️ for the Rust community** diff --git a/imgs/provctl_logo.svg b/imgs/provctl_logo.svg new file mode 100644 index 0000000..fcd520a --- /dev/null +++ b/imgs/provctl_logo.svg @@ -0,0 +1,246 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + >_ + + + + + + + + + + + + + + >_ + + + + + + + + + + + + + + >_ + + + + + + + + + + + + + + >_ + + + + + + + + + + + + + + >_ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +