Michel Roegl-Brunner
960fddb9ee
Some checks failed
Bump build.func Revision / bump-revision (push) Has been cancelled
38 KiB
38 KiB
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