commit 9067b69eace785c3f99936a5fced60e546dc209c Author: Jesús Pérez Date: Wed Nov 19 17:37:06 2025 +0000 chore: init repo 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 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + >_ + + + + + + + + + + + + + + >_ + + + + + + + + + + + + + + >_ + + + + + + + + + + + + + + >_ + + + + + + + + + + + + + + >_ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +