mirror of
https://github.com/community-scripts/ProxmoxVED.git
synced 2026-02-25 05:57:26 +00:00
Add docs for all files in /misc
This commit is contained in:
Michel Roegl-Brunner
347
docs/misc/error_handler.func/ERROR_HANDLER_FLOWCHART.md
Normal file
347
docs/misc/error_handler.func/ERROR_HANDLER_FLOWCHART.md
Normal file
@@ -0,0 +1,347 @@
|
||||
# error_handler.func Execution Flowchart
|
||||
|
||||
## Main Error Handling Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Error Handler Initialization │
|
||||
│ Entry point when error_handler.func is sourced by other scripts │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ CATCH_ERRORS() │
|
||||
│ Initialize error handling traps and strict mode │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Trap Setup Sequence │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────────┐ │
|
||||
│ │ Set Strict │ │ Set Error │ │ Set Signal │ │
|
||||
│ │ Mode │ │ Trap │ │ Traps │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • -Ee │ │ • ERR trap │ │ • EXIT trap │ │
|
||||
│ │ • -o pipefail │ │ • error_handler │ │ • INT trap │ │
|
||||
│ │ • -u (if │ │ function │ │ • TERM trap │ │
|
||||
│ │ STRICT_UNSET) │ │ │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Error Handler Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ ERROR_HANDLER() Flow │
|
||||
│ Main error handler triggered by ERR trap or manual call │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Error Detection │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Error Information Collection │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Get Exit │ │ Get Command │ │ Get Line │ │ │
|
||||
│ │ │ Code │ │ Information │ │ Number │ │ │
|
||||
│ │ │ │ │ │ │ │ │ │
|
||||
│ │ │ • From $? or │ │ • From │ │ • From │ │ │
|
||||
│ │ │ parameter │ │ BASH_COMMAND │ │ BASH_LINENO[0] │ │ │
|
||||
│ │ │ • Store in │ │ • Clean $STD │ │ • Default to │ │ │
|
||||
│ │ │ exit_code │ │ references │ │ "unknown" │ │ │
|
||||
│ │ │ │ │ • Store in │ │ • Store in │ │ │
|
||||
│ │ │ │ │ command │ │ line_number │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Success Check │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Exit Code Validation │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Check Exit │ │ Success │ │ Error │ │
|
||||
│ │ │ Code │ │ Path │ │ Path │ │
|
||||
│ │ │ │ │ │ │ │ │
|
||||
│ │ │ • If exit_code │ │ • Return 0 │ │ • Continue to │ │
|
||||
│ │ │ == 0 │ │ • No error │ │ error handling │ │
|
||||
│ │ │ • Success │ │ processing │ │ • Process error │ │
|
||||
│ │ │ • No error │ │ │ │ information │ │
|
||||
│ │ │ handling │ │ │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Error Processing │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Error Explanation │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Get Error │ │ Display Error │ │ Log Error │ │ │
|
||||
│ │ │ Explanation │ │ Information │ │ Information │ │ │
|
||||
│ │ │ │ │ │ │ │ │
|
||||
│ │ │ • Call │ │ • Show error │ │ • Write to debug │ │
|
||||
│ │ │ explain_exit_ │ │ message │ │ log if enabled │ │
|
||||
│ │ │ code() │ │ • Show line │ │ • Include │ │
|
||||
│ │ │ • Get human- │ │ number │ │ timestamp │ │
|
||||
│ │ │ readable │ │ • Show command │ │ • Include exit │ │
|
||||
│ │ │ message │ │ • Show exit │ │ code │ │
|
||||
│ │ │ │ │ code │ │ • Include command │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Silent Log Integration │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Silent Log Display │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Check Silent │ │ Display Log │ │ Exit with │ │
|
||||
│ │ │ Log File │ │ Content │ │ Error Code │ │
|
||||
│ │ │ │ │ │ │ │ │
|
||||
│ │ │ • Check if │ │ • Show last 20 │ │ • Exit with │ │
|
||||
│ │ │ SILENT_ │ │ lines │ │ original exit │ │
|
||||
│ │ │ LOGFILE set │ │ • Show file │ │ code │ │
|
||||
│ │ │ • Check if │ │ path │ │ • Terminate script │ │
|
||||
│ │ │ file exists │ │ • Format │ │ execution │ │
|
||||
│ │ │ • Check if │ │ output │ │ │ │
|
||||
│ │ │ file has │ │ │ │ │ │
|
||||
│ │ │ content │ │ │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Signal Handling Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Signal Handler Flow │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Signal Detection │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ SIGINT │ │ SIGTERM │ │ EXIT │ │ │
|
||||
│ │ │ (Ctrl+C) │ │ (Termination) │ │ (Script End) │ │ │
|
||||
│ │ │ │ │ │ │ │ │
|
||||
│ │ │ • User │ │ • System │ │ • Normal script │ │
|
||||
│ │ │ interruption │ │ termination │ │ completion │ │
|
||||
│ │ │ • Graceful │ │ • Graceful │ │ • Error exit │ │
|
||||
│ │ │ handling │ │ handling │ │ • Signal exit │ │
|
||||
│ │ │ • Exit code │ │ • Exit code │ │ • Cleanup │ │
|
||||
│ │ │ 130 │ │ 143 │ │ operations │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ ON_INTERRUPT() Flow │
|
||||
│ Handles SIGINT (Ctrl+C) signals │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Interrupt Processing │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ User Interruption Handling │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Display │ │ Cleanup │ │ Exit with │ │ │
|
||||
│ │ │ Message │ │ Operations │ │ Code 130 │ │ │
|
||||
│ │ │ │ │ │ │ │ │
|
||||
│ │ │ • Show │ │ • Stop │ │ • Exit with │ │
|
||||
│ │ │ interruption │ │ processes │ │ SIGINT code │ │
|
||||
│ │ │ message │ │ • Clean up │ │ • Terminate script │ │
|
||||
│ │ │ • Use red │ │ temporary │ │ execution │ │
|
||||
│ │ │ color │ │ files │ │ │ │
|
||||
│ │ │ • Clear │ │ • Remove lock │ │ │ │
|
||||
│ │ │ terminal │ │ files │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Exit Handler Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ ON_EXIT() Flow │
|
||||
│ Handles script exit cleanup │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Exit Cleanup │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Cleanup Operations │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Lock File │ │ Temporary │ │ Exit with │ │ │
|
||||
│ │ │ Cleanup │ │ File │ │ Original Code │ │ │
|
||||
│ │ │ │ │ Cleanup │ │ │ │
|
||||
│ │ │ • Check if │ │ • Remove │ │ • Exit with │ │
|
||||
│ │ │ lockfile │ │ temporary │ │ original exit │ │
|
||||
│ │ │ variable set │ │ files │ │ code │ │
|
||||
│ │ │ • Check if │ │ • Clean up │ │ • Preserve exit │ │
|
||||
│ │ │ lockfile │ │ process │ │ status │ │
|
||||
│ │ │ exists │ │ state │ │ • Terminate │ │
|
||||
│ │ │ • Remove │ │ │ │ execution │ │
|
||||
│ │ │ lockfile │ │ │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Error Code Explanation Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ EXPLAIN_EXIT_CODE() Flow │
|
||||
│ Converts numeric exit codes to human-readable explanations │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Error Code Classification │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Error Code Categories │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Generic/ │ │ Package │ │ Node.js │ │ │
|
||||
│ │ │ Shell │ │ Manager │ │ Errors │ │ │
|
||||
│ │ │ Errors │ │ Errors │ │ │ │
|
||||
│ │ │ │ │ │ │ • 243: Out of │ │
|
||||
│ │ │ • 1: General │ │ • 100: APT │ │ memory │ │
|
||||
│ │ │ error │ │ package │ │ • 245: Invalid │ │
|
||||
│ │ │ • 2: Shell │ │ error │ │ option │ │
|
||||
│ │ │ builtin │ │ • 101: APT │ │ • 246: Parse │ │
|
||||
│ │ │ misuse │ │ config error │ │ error │ │
|
||||
│ │ │ • 126: Cannot │ │ • 255: DPKG │ │ • 247: Fatal │ │
|
||||
│ │ │ execute │ │ fatal error │ │ error │ │
|
||||
│ │ │ • 127: Command │ │ │ │ • 248: Addon │ │
|
||||
│ │ │ not found │ │ │ │ failure │ │
|
||||
│ │ │ • 128: Invalid │ │ │ │ • 249: Inspector │ │
|
||||
│ │ │ exit │ │ │ │ error │ │
|
||||
│ │ │ • 130: SIGINT │ │ │ │ • 254: Unknown │ │
|
||||
│ │ │ • 137: SIGKILL │ │ │ │ fatal error │ │
|
||||
│ │ │ • 139: Segfault │ │ │ │ │ │
|
||||
│ │ │ • 143: SIGTERM │ │ │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Python │ │ Database │ │ Proxmox │ │ │
|
||||
│ │ │ Errors │ │ Errors │ │ Custom │ │ │
|
||||
│ │ │ │ │ │ │ Errors │ │
|
||||
│ │ │ • 210: Virtual │ │ • PostgreSQL: │ │ • 200: Lock file │ │
|
||||
│ │ │ env missing │ │ 231-234 │ │ failed │ │
|
||||
│ │ │ • 211: Dep │ │ • MySQL: 241- │ │ • 203: Missing │ │
|
||||
│ │ │ resolution │ │ 244 │ │ CTID │ │
|
||||
│ │ │ • 212: Install │ │ • MongoDB: 251- │ │ • 204: Missing │ │
|
||||
│ │ │ aborted │ │ 254 │ │ PCT_OSTYPE │ │
|
||||
│ │ │ │ │ │ │ • 205: Invalid │ │
|
||||
│ │ │ │ │ │ │ CTID │ │
|
||||
│ │ │ │ │ │ │ • 209: Container │ │
|
||||
│ │ │ │ │ │ │ creation failed │ │
|
||||
│ │ │ │ │ │ │ • 210: Cluster │ │
|
||||
│ │ │ │ │ │ │ not quorate │ │
|
||||
│ │ │ │ │ │ │ • 214: No storage │ │
|
||||
│ │ │ │ │ │ │ space │ │
|
||||
│ │ │ │ │ │ │ • 215: CTID not │ │
|
||||
│ │ │ │ │ │ │ listed │ │
|
||||
│ │ │ │ │ │ │ • 216: RootFS │ │
|
||||
│ │ │ │ │ │ │ missing │ │
|
||||
│ │ │ │ │ │ │ • 217: Storage │ │
|
||||
│ │ │ │ │ │ │ not supported │ │
|
||||
│ │ │ │ │ │ │ • 220: Template │ │
|
||||
│ │ │ │ │ │ │ path error │ │
|
||||
│ │ │ │ │ │ │ • 222: Template │ │
|
||||
│ │ │ │ │ │ │ download failed │ │
|
||||
│ │ │ │ │ │ │ • 223: Template │ │
|
||||
│ │ │ │ │ │ │ not available │ │
|
||||
│ │ │ │ │ │ │ • 231: LXC stack │ │
|
||||
│ │ │ │ │ │ │ upgrade failed │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Default Case │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Unknown Error Handling │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Check for │ │ Return │ │ Log Unknown │ │ │
|
||||
│ │ │ Unknown │ │ Generic │ │ Error │ │ │
|
||||
│ │ │ Code │ │ Message │ │ │ │
|
||||
│ │ │ │ │ │ │ • Log to debug │ │
|
||||
│ │ │ • If no match │ │ • "Unknown │ │ file if enabled │ │
|
||||
│ │ │ found │ │ error" │ │ • Include error │ │
|
||||
│ │ │ • Use default │ │ • Return to │ │ code │ │
|
||||
│ │ │ case │ │ caller │ │ • Include │ │
|
||||
│ │ │ │ │ │ │ timestamp │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Debug Logging Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Debug Log Integration │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Debug Log Writing │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Check Debug │ │ Write Error │ │ Format Log │ │ │
|
||||
│ │ │ Log File │ │ Information │ │ Entry │ │ │
|
||||
│ │ │ │ │ │ │ │ │
|
||||
│ │ │ • Check if │ │ • Timestamp │ │ • Error separator │ │
|
||||
│ │ │ DEBUG_LOGFILE │ │ • Exit code │ │ • Structured │ │
|
||||
│ │ │ set │ │ • Explanation │ │ format │ │
|
||||
│ │ │ • Check if │ │ • Line number │ │ • Easy to parse │ │
|
||||
│ │ │ file exists │ │ • Command │ │ • Easy to read │ │
|
||||
│ │ │ • Check if │ │ • Append to │ │ │ │
|
||||
│ │ │ file writable │ │ file │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Integration Points
|
||||
|
||||
### With core.func
|
||||
- **Silent Execution**: Provides error explanations for silent() function
|
||||
- **Color Variables**: Uses color variables for error display
|
||||
- **Log Integration**: Integrates with SILENT_LOGFILE
|
||||
|
||||
### With Other Scripts
|
||||
- **Error Traps**: Sets up ERR trap for automatic error handling
|
||||
- **Signal Traps**: Handles SIGINT, SIGTERM, and EXIT signals
|
||||
- **Cleanup**: Provides cleanup on script exit
|
||||
|
||||
### External Dependencies
|
||||
- **None**: Pure Bash implementation
|
||||
- **Color Support**: Requires color variables from core.func
|
||||
- **Log Files**: Uses standard file operations
|
||||
Reference in New Issue
Block a user