Doctor Diagnostic System
The Doctor system is responsible for inspecting the local environment, identifying configuration drifts, corrupted state files, or connectivity issues, and providing a path to remediation. It operates viaDoctorCheck units that can perform both diagnostics and repair actions.
Implementation and Data Flow
The core logic resides incrates/palyra-cli/src/commands/doctor/recovery.rs. The system follows a structured execution flow:
- Environment Probing: Captures the current
state_rootandconfig_pathcrates/palyra-cli/src/commands/doctor/recovery.rs#60-64. - Diagnostic Execution: Runs a suite of checks across various subsystems (Auth, Browser, Node, Routines).
- Plan Generation: If issues are found, the system generates a
DoctorRepairPlancontaining specificDoctorRepairStepitems crates/palyra-cli/src/commands/doctor/recovery.rs#172-176. - Repair/Rollback: Applies changes to the filesystem, creating backups for every destructive action to allow for later rollbacks crates/palyra-cli/src/commands/doctor/recovery.rs#141-155.
Doctor Execution Model
The system supports multiple execution modes defined byDoctorExecutionMode crates/palyra-cli/src/commands/doctor/recovery.rs#66-74:
Diagnostics: Read-only inspection.RepairPreview: Generates a plan without applying changes (Dry Run).RepairApply: Executes the remediation steps.RollbackApply: Reverts a previousDoctorrun using the storedDoctorRecoveryManifest.
Key Components & Entities
| Entity | Description | Location |
|---|---|---|
DoctorCommandRequest | CLI arguments for the doctor command (strict, repair, force, etc.) | crates/palyra-cli/src/commands/doctor/recovery.rs#48-57 |
DoctorExecutionReport | The final output containing both diagnostics and recovery results. | crates/palyra-cli/src/commands/doctor/recovery.rs#76-83 |
DoctorRecoveryManifest | A JSON file tracking changes made during a repair for rollback purposes. | crates/palyra-cli/src/commands/doctor/recovery.rs#141-155 |
DoctorRepairKind | Enum defining specific repair logic (e.g., MigrateConfigVersion, BackfillAccessRegistry). | crates/palyra-cli/src/commands/doctor/recovery.rs#178-237 |
Doctor Diagnostic Logic Flow
The following diagram bridges the diagnostic logic to the code entities that manage state and recovery. “Doctor Diagnostic & Recovery Flow” Sources: crates/palyra-cli/src/commands/doctor/recovery.rs#8-102, crates/palyra-cli/src/commands/doctor/recovery.rs#141-176CLI Parity Matrix
Palyra maintains a strict parity matrix to ensure that the CLI surface remains consistent across updates and platforms. This is enforced through automated tests that compare the liveclap command tree against a canonical matrix definition.
Parity Verification Framework
The parity system uses aCliParityMatrix crates/palyra-cli/src/cli_parity.rs#96-99 defined in tests/cli_parity_matrix.toml.
- Status Levels: Commands are categorized as
done,partial,intentional_deviation, orcapability_gatedcrates/palyra-cli/src/cli_parity.rs#9-16. - Verification: The function
build_cli_parity_reportcrates/palyra-cli/src/cli_parity.rs#165 traverses the liveClapCommandtree to verify:- Presence of subcommands.
- Existence of required aliases (e.g.,
setupmust have aliasinit) crates/palyra-cli/tests/cli_parity_matrix.toml#30. - Existence of required flags (e.g.,
--profile,--config) crates/palyra-cli/tests/cli_parity_matrix.toml#8.
Help Snapshot Testing
To prevent regressions in documentation and UI, the CLI uses help snapshot testing. Each entry in the parity matrix can point to a snapshot file crates/palyra-cli/src/cli_parity.rs#30-38.- Platform Specificity: The system supports
unix_fileandwindows_filesnapshots to account for platform-specific path separators or global options crates/palyra-cli/src/cli_parity.rs#41-51. - Automated Validation: The test
cli_parity_report_matches_committed_snapshotensures the generated markdown report matches the committed version intests/cli_parity_report.mdcrates/palyra-cli/tests/cli_parity.rs#73-79.
CLI Parity Architecture
“CLI Parity Validation System” Sources: crates/palyra-cli/src/cli_parity.rs#155-200, crates/palyra-cli/tests/cli_parity.rs#56-70Remote Diagnostics (Console API)
The daemon provides an HTTP interface for the Web Console to interact with the Doctor system. This allows operators to run diagnostics and view recovery jobs remotely.- Endpoints:
GET /console/v1/doctor/jobs: Lists recent recovery jobs crates/palyra-daemon/src/transport/http/handlers/console/doctor.rs#3-18.POST /console/v1/doctor/jobs: Initiates a new diagnostic or repair job crates/palyra-daemon/src/transport/http/handlers/console/doctor.rs#20-28.GET /console/v1/doctor/jobs/:job_id: Retrieves detailed status of a specific job crates/palyra-daemon/src/transport/http/handlers/console/doctor.rs#30-45.
DoctorExecutionReport structure to ensure parity between local and remote management.
Sources: crates/palyra-daemon/src/transport/http/handlers/console/doctor.rs#1-46, crates/palyra-cli/src/commands/doctor/recovery.rs#77-83