343 lines
38 KiB
Markdown
343 lines
38 KiB
Markdown
# api.func Execution Flowchart
|
|
|
|
## Main API Communication Flow
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ API Communication Initialization │
|
|
│ Entry point when api.func functions are called by installation scripts │
|
|
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ Prerequisites Check │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ Prerequisites Validation │ │
|
|
│ │ │ │
|
|
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
|
│ │ │ Check curl │ │ Check │ │ Check │ │ │
|
|
│ │ │ Availability │ │ Diagnostics │ │ Random UUID │ │ │
|
|
│ │ │ │ │ Setting │ │ │ │
|
|
│ │ │ • command -v │ │ • DIAGNOSTICS │ │ • RANDOM_UUID │ │
|
|
│ │ │ curl │ │ = "yes" │ │ not empty │ │
|
|
│ │ │ • Return if │ │ • Return if │ │ • Return if │ │
|
|
│ │ │ not found │ │ disabled │ │ not set │ │
|
|
│ │ │ │ │ │ │ │ │
|
|
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ Data Collection │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ System Information Gathering │ │
|
|
│ │ │ │
|
|
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
|
│ │ │ Get PVE │ │ Collect │ │ Prepare JSON │ │ │
|
|
│ │ │ Version │ │ Environment │ │ Payload │ │
|
|
│ │ │ │ │ Variables │ │ │ │
|
|
│ │ │ • pveversion │ │ • CT_TYPE │ │ • Create JSON │ │
|
|
│ │ │ command │ │ • DISK_SIZE │ │ structure │ │
|
|
│ │ │ • Parse version │ │ • CORE_COUNT │ │ • Include all │ │
|
|
│ │ │ • Extract │ │ • RAM_SIZE │ │ variables │ │
|
|
│ │ │ major.minor │ │ • var_os │ │ • Format for API │ │
|
|
│ │ │ │ │ • var_version │ │ │ │
|
|
│ │ │ │ │ • NSAPP │ │ │ │
|
|
│ │ │ │ │ • METHOD │ │ │ │
|
|
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ API Request Execution │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ HTTP Request Processing │ │
|
|
│ │ │ │
|
|
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
|
│ │ │ Prepare │ │ Execute │ │ Handle │ │ │
|
|
│ │ │ Request │ │ HTTP Request │ │ Response │ │
|
|
│ │ │ │ │ │ │ │ │
|
|
│ │ │ • Set API URL │ │ • curl -s -w │ │ • Capture HTTP │ │
|
|
│ │ │ • Set headers │ │ "%{http_code}" │ │ status code │ │
|
|
│ │ │ • Set payload │ │ • POST request │ │ • Store response │ │
|
|
│ │ │ • Content-Type │ │ • JSON data │ │ • Handle errors │ │
|
|
│ │ │ application/ │ │ • Follow │ │ gracefully │ │
|
|
│ │ │ json │ │ redirects │ │ │ │
|
|
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## LXC API Reporting Flow
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ POST_TO_API() Flow │
|
|
│ Send LXC container installation data to API │
|
|
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ LXC Data Preparation │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ LXC-Specific Data Collection │ │
|
|
│ │ │ │
|
|
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
|
│ │ │ Set LXC │ │ Include LXC │ │ Set Status │ │ │
|
|
│ │ │ Type │ │ Variables │ │ Information │ │
|
|
│ │ │ │ │ │ │ │ │
|
|
│ │ │ • ct_type: 1 │ │ • DISK_SIZE │ │ • status: │ │
|
|
│ │ │ • type: "lxc" │ │ • CORE_COUNT │ │ "installing" │ │
|
|
│ │ │ • Include all │ │ • RAM_SIZE │ │ • Include all │ │
|
|
│ │ │ LXC data │ │ • var_os │ │ tracking data │ │
|
|
│ │ │ │ │ • var_version │ │ │ │
|
|
│ │ │ │ │ • DISABLEIP6 │ │ │ │
|
|
│ │ │ │ │ • NSAPP │ │ │ │
|
|
│ │ │ │ │ • METHOD │ │ │ │
|
|
│ │ │ │ │ • pve_version │ │ │ │
|
|
│ │ │ │ │ • random_id │ │ │ │
|
|
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ JSON Payload Creation │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ JSON Structure Generation │ │
|
|
│ │ │ │
|
|
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
|
│ │ │ Create JSON │ │ Validate │ │ Format for │ │ │
|
|
│ │ │ Structure │ │ Data │ │ API Request │ │
|
|
│ │ │ │ │ │ │ │ │
|
|
│ │ │ • Use heredoc │ │ • Check all │ │ • Ensure proper │ │
|
|
│ │ │ syntax │ │ variables │ │ JSON format │ │
|
|
│ │ │ • Include all │ │ are set │ │ • Escape special │ │
|
|
│ │ │ required │ │ • Validate │ │ characters │ │
|
|
│ │ │ fields │ │ data types │ │ • Set content │ │
|
|
│ │ │ • Format │ │ • Handle │ │ type │ │
|
|
│ │ │ properly │ │ missing │ │ │ │
|
|
│ │ │ │ │ values │ │ │ │
|
|
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## VM API Reporting Flow
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ POST_TO_API_VM() Flow │
|
|
│ Send VM installation data to API │
|
|
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ VM Data Preparation │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ VM-Specific Data Collection │ │
|
|
│ │ │ │
|
|
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
|
│ │ │ Check │ │ Set VM │ │ Process Disk │ │ │
|
|
│ │ │ Diagnostics │ │ Type │ │ Size │ │
|
|
│ │ │ File │ │ │ │ │ │
|
|
│ │ │ │ │ • ct_type: 2 │ │ • Remove 'G' │ │
|
|
│ │ │ • Check file │ │ • type: "vm" │ │ suffix │ │
|
|
│ │ │ existence │ │ • Include all │ │ • Convert to │ │
|
|
│ │ │ • Read │ │ VM data │ │ numeric value │ │
|
|
│ │ │ DIAGNOSTICS │ │ │ │ • Store in │ │
|
|
│ │ │ setting │ │ │ │ DISK_SIZE_API │ │
|
|
│ │ │ • Parse value │ │ │ │ │ │
|
|
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ VM JSON Payload Creation │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ VM-Specific JSON Structure │ │
|
|
│ │ │ │
|
|
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
|
│ │ │ Include VM │ │ Set VM │ │ Format VM │ │ │
|
|
│ │ │ Variables │ │ Status │ │ Data for API │ │
|
|
│ │ │ │ │ │ │ │ │
|
|
│ │ │ • DISK_SIZE_API │ │ • status: │ │ • Ensure proper │ │
|
|
│ │ │ • CORE_COUNT │ │ "installing" │ │ JSON format │ │
|
|
│ │ │ • RAM_SIZE │ │ • Include all │ │ • Handle VM- │ │
|
|
│ │ │ • var_os │ │ tracking │ │ specific data │ │
|
|
│ │ │ • var_version │ │ information │ │ • Set appropriate │ │
|
|
│ │ │ • NSAPP │ │ │ │ content type │ │
|
|
│ │ │ • METHOD │ │ │ │ │ │
|
|
│ │ │ • pve_version │ │ │ │ │ │
|
|
│ │ │ • random_id │ │ │ │ │ │
|
|
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Status Update Flow
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ POST_UPDATE_TO_API() Flow │
|
|
│ Send installation completion status to API │
|
|
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ Update Prevention Check │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ Duplicate Update Prevention │ │
|
|
│ │ │ │
|
|
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
|
│ │ │ Check │ │ Set Flag │ │ Return Early │ │ │
|
|
│ │ │ POST_UPDATE_ │ │ if First │ │ if Already │ │
|
|
│ │ │ DONE │ │ Update │ │ Updated │ │
|
|
│ │ │ │ │ │ │ │ │
|
|
│ │ │ • Check if │ │ • Set │ │ • Return 0 │ │
|
|
│ │ │ already │ │ POST_UPDATE_ │ │ • Skip API call │ │
|
|
│ │ │ updated │ │ DONE=true │ │ • Prevent │ │
|
|
│ │ │ • Prevent │ │ • Continue │ │ duplicate │ │
|
|
│ │ │ duplicate │ │ with update │ │ requests │ │
|
|
│ │ │ requests │ │ │ │ │ │
|
|
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ Status and Error Processing │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ Status Determination │ │
|
|
│ │ │ │
|
|
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
|
│ │ │ Determine │ │ Get Error │ │ Prepare Status │ │ │
|
|
│ │ │ Status │ │ Description │ │ Data │ │
|
|
│ │ │ │ │ │ │ │ │
|
|
│ │ │ • status: │ │ • Call │ │ • Include status │ │
|
|
│ │ │ "success" or │ │ get_error_ │ │ • Include error │ │
|
|
│ │ │ "failed" │ │ description() │ │ description │ │
|
|
│ │ │ • Set exit │ │ • Get human- │ │ • Include random │ │
|
|
│ │ │ code based │ │ readable │ │ ID for tracking │ │
|
|
│ │ │ on status │ │ error message │ │ │ │
|
|
│ │ │ • Default to │ │ • Handle │ │ │ │
|
|
│ │ │ error if │ │ unknown │ │ │ │
|
|
│ │ │ not set │ │ errors │ │ │ │
|
|
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ Status Update API Request │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ Status Update Payload Creation │ │
|
|
│ │ │ │
|
|
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
|
│ │ │ Create │ │ Send Status │ │ Mark Update │ │ │
|
|
│ │ │ Status JSON │ │ Update │ │ Complete │ │
|
|
│ │ │ │ │ │ │ │ │
|
|
│ │ │ • Include │ │ • POST to │ │ • Set │ │
|
|
│ │ │ status │ │ updatestatus │ │ POST_UPDATE_ │ │
|
|
│ │ │ • Include │ │ endpoint │ │ DONE=true │ │
|
|
│ │ │ error │ │ • Include JSON │ │ • Prevent further │ │
|
|
│ │ │ description │ │ payload │ │ updates │ │
|
|
│ │ │ • Include │ │ • Handle │ │ • Complete │ │
|
|
│ │ │ random_id │ │ response │ │ process │ │
|
|
│ │ │ │ │ gracefully │ │ │ │
|
|
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Error Description Flow
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ GET_ERROR_DESCRIPTION() Flow │
|
|
│ Convert numeric exit codes to human-readable explanations │
|
|
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ Error Code Classification │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ Error Code Categories │ │
|
|
│ │ │ │
|
|
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
|
│ │ │ General │ │ Network │ │ LXC-Specific │ │ │
|
|
│ │ │ System │ │ Errors │ │ Errors │ │
|
|
│ │ │ Errors │ │ │ │ │ │
|
|
│ │ │ │ │ • 18: Connection│ │ • 100-101: LXC │ │
|
|
│ │ │ • 0-9: Basic │ │ failed │ │ install errors │ │
|
|
│ │ │ errors │ │ • 22: Invalid │ │ • 200-209: LXC │ │
|
|
│ │ │ • 126-128: │ │ argument │ │ creation errors │ │
|
|
│ │ │ Command │ │ • 28: No space │ │ │ │
|
|
│ │ │ errors │ │ • 35: Timeout │ │ │ │
|
|
│ │ │ • 129-143: │ │ • 56: TLS error │ │ │ │
|
|
│ │ │ Signal │ │ • 60: SSL cert │ │ │ │
|
|
│ │ │ errors │ │ error │ │ │ │
|
|
│ │ │ • 152: Resource │ │ │ │ │ │
|
|
│ │ │ limit │ │ │ │ │ │
|
|
│ │ │ • 255: Unknown │ │ │ │ │ │
|
|
│ │ │ critical │ │ │ │ │ │
|
|
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ Error Message Return │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ Error Message Formatting │ │
|
|
│ │ │ │
|
|
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
|
│ │ │ Match Error │ │ Return │ │ Default Case │ │ │
|
|
│ │ │ Code │ │ Description │ │ │ │
|
|
│ │ │ │ │ │ │ │ │
|
|
│ │ │ • Use case │ │ • Return │ │ • Return "Unknown │ │
|
|
│ │ │ statement │ │ human- │ │ error code │ │
|
|
│ │ │ • Match │ │ readable │ │ (exit_code)" │ │
|
|
│ │ │ specific │ │ message │ │ • Handle │ │
|
|
│ │ │ codes │ │ • Include │ │ unrecognized │ │
|
|
│ │ │ • Handle │ │ context │ │ codes │ │
|
|
│ │ │ ranges │ │ information │ │ • Provide fallback │ │
|
|
│ │ │ │ │ │ │ message │ │
|
|
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Integration Points
|
|
|
|
### With Installation Scripts
|
|
- **build.func**: Sends LXC installation data
|
|
- **vm-core.func**: Sends VM installation data
|
|
- **install.func**: Reports installation status
|
|
- **alpine-install.func**: Reports Alpine installation data
|
|
|
|
### With Error Handling
|
|
- **error_handler.func**: Provides error explanations
|
|
- **core.func**: Uses error descriptions in silent execution
|
|
- **Diagnostic reporting**: Tracks error patterns
|
|
|
|
### External Dependencies
|
|
- **curl**: HTTP client for API communication
|
|
- **Community Scripts API**: External API endpoint
|
|
- **Network connectivity**: Required for API communication
|