provctl/README.md

provctl - Machine Orchestration & Service Control Platform

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<Mutex<>>)
• Trait-based design for extensibility
• Full rustdoc for all public APIs

Quick Start

Installation

# Option 1: Use the installer
nu scripts/install-provctl.nu

# Option 2: Build manually
cargo build --release
./target/release/provctl --help

Basic Usage

# 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

cargo build --release

Test

cargo test --all

Lint & Format

cargo fmt --all
cargo clippy --all --all-targets

Documentation

cargo doc --open --no-deps

Integration with syntaxis-api

provctl provides service management for syntaxis-api:

# In syntaxis-api.nu wrapper:
provctl start syntaxis-api

# Or from provisioning schema:
provctl deploy --config provisioning/syntaxis-api.toml

See 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 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
• CLI Reference: See docs/CLI_GUIDE.md
• Documentation: See docs/ directory
• Architecture: See docs/ARCHITECTURE.md

---

Made with ❤️ for the Rust community