palyrad) and CLI are correctly configured, secured, and maintainable.
1. Setup and Onboarding Infrastructure
The setup process is the primary entry point for new users. It handles configuration generation, TLS scaffolding, and identity initialization.1.1 Init Modes and Scaffolding
The CLI supports two primary initialization modes defined inInitModeArg:
- Local: Configures the runtime for the current machine, typically using loopback interfaces crates/palyra-cli/src/lib.rs#150-155.
- Remote: Configures a gateway intended to be accessed over a network, requiring more stringent TLS and authentication settings crates/palyra-cli/src/args/tests.rs#33-44.
1.2 The Operator Wizard
TheOnboardingWizard is an interactive (or non-interactive) engine that guides the user through complex configuration steps. It uses a generic WizardBackend trait to support both terminal-based interaction and automated flag-based setup.
Key Components:
WizardSession: Tracks the state of the onboarding process crates/palyra-cli/src/commands/operator_wizard.rs#10-15.OnboardingMutationPlan: A data structure that accumulates proposed changes (e.g., ports, bind profiles, API keys) before they are committed to disk crates/palyra-cli/src/commands/operator_wizard.rs#168-194.InitTlsScaffoldArg: Determines how certificates are generated (e.g.,self-signedfor quick starts) crates/palyra-cli/src/args/init.rs#77.
Onboarding Flow Logic
The following diagram illustrates how thepalyra setup command transitions from user input to a functional RootFileConfig.
Title: Onboarding and Setup Data Flow
Sources: crates/palyra-cli/src/commands/operator_wizard.rs#239-250, crates/palyra-cli/src/lib.rs#95-100, crates/palyra-cli/src/commands/operator_wizard.rs#168-194
2. Doctor: Diagnostic and Recovery Framework
TheDoctor system is a multi-tiered diagnostic framework designed to detect configuration drift, filesystem corruption, and stale runtime artifacts.
2.1 Diagnostic Framework
The system runs a series ofDoctorCheck routines. Each check returns a DoctorSeverity (Info, Warning, Error, Critical) and a DoctorReport.
Core Checks include:
- Configuration Integrity: Validates
palyra.tomlagainst the current schema version crates/palyra-cli/src/commands/doctor/recovery.rs#182-184. - Registry Normalization: Checks for corruption in
auth_profiles.tomlandaccess_registry.jsoncrates/palyra-cli/src/commands/doctor/recovery.rs#195-205. - Stale Artifacts: Identifies temporary files or runtime PIDs older than defined thresholds (e.g.,
DOCTOR_STALE_RUNTIME_MAX_AGE) crates/palyra-cli/src/commands/doctor/recovery.rs#41-43.
2.2 Recovery and Repair
Whenpalyra doctor --repair is invoked, the system generates a DoctorRepairPlan.
Implementation Details:
DoctorRepairStep: Represents a single atomic fix (e.g.,RestoreConfigBackup) crates/palyra-cli/src/commands/doctor/recovery.rs#105-118.DoctorRecoveryManifest: A JSON ledger of all changes made during a repair session, including SHA256 hashes of files before and after the operation crates/palyra-cli/src/commands/doctor/recovery.rs#141-155.- Rollback: Uses the manifest to revert files to their
before_sha256state via therollback_runflag crates/palyra-cli/src/commands/doctor/recovery.rs#56-57.
3. Connectivity Probes and Health
The CLI provides two levels of connectivity verification:health and status.
3.1 Health Probes
Thepalyra health command executes a narrow liveness/readiness probe. It attempts to reach both the HTTP Admin surface and the gRPC Gateway surface crates/palyra-cli/tests/help_snapshots/root-help-unix.txt#9.
- HTTP Probe: Validates that the Axum server is routing requests and the
HealthResponseis valid crates/palyra-cli/src/lib.rs#145-148. - gRPC Probe: Checks the
GatewayServiceavailability usingMAX_GRPC_ATTEMPTSwith exponential backoff crates/palyra-cli/src/lib.rs#147-148.
3.2 System Status
Thestatus command provides a broader snapshot, including:
- Transport Status: mTLS certificate validity and socket binding crates/palyra-cli/tests/help_snapshots/root-help-unix.txt#11.
- Admin Status: Feature flags, migration status, and rollout state crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#88-93.
4. Sandbox and Environment Checks
Before execution, Palyra performs “Sandbox Checks” to ensure the host environment supports the requested isolation tiers.| Tier | Mechanism | CLI Diagnostic Command |
|---|---|---|
| Tier-A | Wasmtime / WASM | palyra sandbox explain --runtime wasm |
| Tier-C | bwrap (Linux) / sandbox-exec (macOS) | palyra sandbox explain --runtime process-runner |
sandbox command group inspects effective policies and validates that binary dependencies (like bwrap) are present in the system path crates/palyra-cli/tests/help_snapshots/root-help-unix.txt:33, 89.
5. Support Bundle System
For troubleshooting complex issues, thesupport-bundle command aggregates diagnostics into a single portable archive.
Data Inclusion:
- Redacted Config: The
palyra.tomlis included, but sensitive keys are filtered usingredact_secret_config_valuescrates/palyra-cli/src/lib.rs#100-105. - Logs: Recent entries from the SQLite-backed
JournalStorecrates/palyra-cli/src/args/tests.rs#171-182. - Doctor Report: The output of the latest diagnostic run crates/palyra-cli/src/commands/doctor/recovery.rs#5-7.