mirror of
https://github.com/community-scripts/ProxmoxVED.git
synced 2026-02-25 05:57:26 +00:00
Replace Go API with PocketBase; update docs
Remove the old Go/Mongo API (api/main.go, go.mod, go.sum, .env.example) and switch telemetry backend to PocketBase (http://db.community-scripts.org). Update documentation and flowcharts to reflect the PocketBase collection (_dev_telemetry_data), new REST endpoints (POST/PATCH/GET), field schema, and revised api.func integration (LXC/VM reporting and status updates). Misc scripts and helpers were adjusted (misc/api.func, misc/build.func, misc/error_handler.func) and a new misc/ingest.go was added. This consolidates telemetry to a hosted PocketBase instance and updates docs and integration points accordingly.
This commit is contained in:
CanbiZ (MickLesk)
@@ -1,5 +1,9 @@
|
||||
# api.func Execution Flowchart
|
||||
|
||||
## Overview
|
||||
|
||||
This document illustrates the execution flow of `api.func` functions. The backend is **PocketBase** at `http://db.community-scripts.org`, collection `_dev_telemetry_data`.
|
||||
|
||||
## Main API Communication Flow
|
||||
|
||||
```
|
||||
@@ -10,333 +14,321 @@
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ 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 │ │
|
||||
│ │ │ │ │ │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
│ Prerequisites Check │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Prerequisites Validation │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────────┐ │ │
|
||||
│ │ │ Check curl │ │ Check │ │ Check │ │ │
|
||||
│ │ │ Availability │ │ DIAGNOSTICS │ │ RANDOM_UUID │ │ │
|
||||
│ │ │ │ │ │ │ │ │ │
|
||||
│ │ │ • command -v │ │ • Must be "yes" │ │ • Must not be │ │ │
|
||||
│ │ │ curl │ │ • Return if │ │ empty │ │ │
|
||||
│ │ │ • Return if │ │ "no" or unset │ │ • Return if │ │ │
|
||||
│ │ │ not found │ │ │ │ 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 │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
│ Data Collection │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ System Information Gathering │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────────┐ │ │
|
||||
│ │ │ Get PVE │ │ Collect Env │ │ Build JSON │ │ │
|
||||
│ │ │ Version │ │ Variables │ │ Payload │ │ │
|
||||
│ │ │ │ │ │ │ │ │ │
|
||||
│ │ │ • pveversion │ │ • CT_TYPE │ │ • Heredoc JSON │ │ │
|
||||
│ │ │ command │ │ • DISK_SIZE │ │ • Include all │ │ │
|
||||
│ │ │ • Parse version │ │ • CORE_COUNT │ │ fields │ │ │
|
||||
│ │ │ • Fallback: │ │ • RAM_SIZE │ │ • status = │ │ │
|
||||
│ │ │ "not found" │ │ • var_os │ │ "installing" │ │ │
|
||||
│ │ │ │ │ • 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 │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
│ PocketBase API Request │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ HTTP Request Processing │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────────┐ │ │
|
||||
│ │ │ Prepare │ │ Execute │ │ Handle │ │ │
|
||||
│ │ │ Request │ │ HTTP POST │ │ Response │ │ │
|
||||
│ │ │ │ │ │ │ │ │ │
|
||||
│ │ │ • URL: │ │ • curl -s -w │ │ • Check HTTP │ │ │
|
||||
│ │ │ PB_API_URL │ │ "%{http_code}"│ │ 200/201 │ │ │
|
||||
│ │ │ • Method: POST │ │ • -X POST │ │ • Extract "id" │ │ │
|
||||
│ │ │ • Content-Type: │ │ • -L (follow │ │ from response │ │ │
|
||||
│ │ │ application/ │ │ redirects) │ │ • Store in │ │ │
|
||||
│ │ │ json │ │ • JSON body │ │ PB_RECORD_ID │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └──────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## LXC API Reporting Flow
|
||||
## LXC API Reporting Flow — `post_to_api()`
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ POST_TO_API() Flow │
|
||||
│ Send LXC container installation data to API │
|
||||
│ post_to_api() Flow │
|
||||
│ POST → Create LXC telemetry record in PocketBase │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ 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 │
|
||||
│ Prerequisites: curl? ──► DIAGNOSTICS="yes"? ──► RANDOM_UUID set? │
|
||||
│ (return silently on any failure) │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ 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 │
|
||||
│ LXC Data Preparation │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────┐ ┌───────────────────┐ │
|
||||
│ │ Set LXC type │ │ Collect variables │ │ Set initial │ │
|
||||
│ │ │ │ │ │ status │ │
|
||||
│ │ • ct_type: 1 │ │ • DISK_SIZE │ │ │ │
|
||||
│ │ • type: "lxc" │ │ • CORE_COUNT │ │ • status: │ │
|
||||
│ │ │ │ • RAM_SIZE │ │ "installing" │ │
|
||||
│ │ │ │ • var_os, var_version│ │ • random_id: │ │
|
||||
│ │ │ │ • NSAPP, METHOD │ │ RANDOM_UUID │ │
|
||||
│ │ │ │ • pve_version │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────────┘ └───────────────────┘ │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ 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 │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
│ POST → PB_API_URL │
|
||||
│ http://db.community-scripts.org/api/collections/_dev_telemetry_data/records │
|
||||
│ │
|
||||
│ Response (HTTP 200/201): │
|
||||
│ { "id": "abc123def456789", ... } │
|
||||
│ │ │
|
||||
│ └──► PB_RECORD_ID = "abc123def456789" │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Error Description Flow
|
||||
## VM API Reporting Flow — `post_to_api_vm()`
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ GET_ERROR_DESCRIPTION() Flow │
|
||||
│ Convert numeric exit codes to human-readable explanations │
|
||||
│ post_to_api_vm() Flow │
|
||||
│ POST → Create VM telemetry record in PocketBase │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ 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 │ │ │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
│ Read /usr/local/community-scripts/diagnostics │
|
||||
│ Extract DIAGNOSTICS=yes/no from file │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ 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 │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
│ Prerequisites: curl? ──► DIAGNOSTICS="yes"? ──► RANDOM_UUID set? │
|
||||
│ (return silently on any failure) │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ VM Data Preparation │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────┐ ┌───────────────────┐ │
|
||||
│ │ Set VM type │ │ Process disk size │ │ Set initial │ │
|
||||
│ │ │ │ │ │ status │ │
|
||||
│ │ • ct_type: 2 │ │ • Strip 'G' suffix │ │ │ │
|
||||
│ │ • type: "vm" │ │ "20G" → 20 │ │ • status: │ │
|
||||
│ │ │ │ • Store in │ │ "installing" │ │
|
||||
│ │ │ │ DISK_SIZE_API │ │ • random_id: │ │
|
||||
│ │ │ │ │ │ RANDOM_UUID │ │
|
||||
│ └─────────────────┘ └─────────────────────┘ └───────────────────┘ │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ POST → PB_API_URL │
|
||||
│ http://db.community-scripts.org/api/collections/_dev_telemetry_data/records │
|
||||
│ │
|
||||
│ Response (HTTP 200/201): │
|
||||
│ { "id": "xyz789abc012345", ... } │
|
||||
│ │ │
|
||||
│ └──► PB_RECORD_ID = "xyz789abc012345" │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Status Update Flow — `post_update_to_api()`
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ post_update_to_api(status, exit_code) Flow │
|
||||
│ PATCH → Update existing PocketBase record with final status │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Duplicate Prevention Check │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌──────────────────────────────────────────────┐ │
|
||||
│ │ Check │ │ POST_UPDATE_DONE == "true"? │ │
|
||||
│ │ POST_UPDATE_ │───►│ │ │
|
||||
│ │ DONE flag │ │ YES → return 0 (skip PATCH) │ │
|
||||
│ │ │ │ NO → continue │ │
|
||||
│ └─────────────────┘ └──────────────────────────────────────────────┘ │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│ (first call only)
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Prerequisites: curl? ──► DIAGNOSTICS="yes"? ──► RANDOM_UUID set? │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Status Mapping │
|
||||
│ │
|
||||
│ Input $1 │ PocketBase status │ exit_code │ error │
|
||||
│ ─────────────────┼─────────────────────┼──────────────┼────────────────────── │
|
||||
│ "done"/"success" │ "sucess" │ 0 │ "" │
|
||||
│ "failed" │ "failed" │ from $2 │ explain_exit_code() │
|
||||
│ anything else │ "unknown" │ from $2 │ explain_exit_code() │
|
||||
│ │
|
||||
│ Note: PocketBase schema spells it "sucess" intentionally │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Record ID Resolution │
|
||||
│ │
|
||||
│ ┌──────────────────────────┐ ┌──────────────────────────────────────┐ │
|
||||
│ │ PB_RECORD_ID set? │ │ Fallback: GET lookup │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ YES → use PB_RECORD_ID │ │ GET PB_API_URL │ │
|
||||
│ │ │ │ ?filter=(random_id='UUID') │ │
|
||||
│ │ NO → try GET lookup ───┼───►│ &fields=id │ │
|
||||
│ │ │ │ &perPage=1 │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ │ │ Extract "id" from response │ │
|
||||
│ │ │ │ If not found → set flag, return │ │
|
||||
│ └──────────────────────────┘ └──────────────────────────────────────┘ │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ PATCH Request │
|
||||
│ │
|
||||
│ PATCH → PB_API_URL/{record_id} │
|
||||
│ http://db.community-scripts.org/api/collections/_dev_telemetry_data/ │
|
||||
│ records/{record_id} │
|
||||
│ │
|
||||
│ Payload: │
|
||||
│ { │
|
||||
│ "status": "sucess" | "failed" | "unknown", │
|
||||
│ "error": "..." | "", │
|
||||
│ "exit_code": 0 | <numeric> │
|
||||
│ } │
|
||||
│ │
|
||||
│ ──► POST_UPDATE_DONE = true (prevents future calls) │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Error Description Flow — `explain_exit_code()`
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ explain_exit_code(code) Flow │
|
||||
│ Convert numeric exit codes to human-readable descriptions │
|
||||
│ Canonical function — used by api.func AND error_handler.func │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Exit Code Classification (non-overlapping ranges) │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌──────────────────┐ ┌──────────────────────────┐ │
|
||||
│ │ Generic/Shell │ │ curl/wget │ │ APT/DPKG │ │
|
||||
│ │ 1–2 │ │ 6, 7, 22, 28, 35│ │ 100–102, 255 │ │
|
||||
│ └─────────────────┘ └──────────────────┘ └──────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌──────────────────┐ ┌──────────────────────────┐ │
|
||||
│ │ System/Signals │ │ Systemd/Service │ │ Python/pip/uv │ │
|
||||
│ │ 124–143 │ │ 150–154 │ │ 160–162 │ │
|
||||
│ └─────────────────┘ └──────────────────┘ └──────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌──────────────────┐ ┌──────────────────────────┐ │
|
||||
│ │ PostgreSQL │ │ MySQL/MariaDB │ │ MongoDB │ │
|
||||
│ │ 170–173 │ │ 180–183 │ │ 190–193 │ │
|
||||
│ └─────────────────┘ └──────────────────┘ └──────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌──────────────────┐ │
|
||||
│ │ Proxmox │ │ Node.js/npm │ │
|
||||
│ │ 200–231 │ │ 243–249 │ │
|
||||
│ └─────────────────┘ └──────────────────┘ │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ case "$code" in │
|
||||
│ <matched>) echo "<description>" ;; │
|
||||
│ *) echo "Unknown error" ;; │
|
||||
│ esac │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Complete Installation Lifecycle
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ Installation Script (e.g. build.func / vm-core.func) │
|
||||
└────────┬─────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ 1. source api.func
|
||||
│ 2. Set DIAGNOSTICS, RANDOM_UUID, NSAPP, etc.
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ post_to_api() / post_to_api_vm() │
|
||||
│ │
|
||||
│ POST → PB_API_URL │
|
||||
│ Body: { ..., "status": "installing", "random_id": "..." } │
|
||||
│ │
|
||||
│ Response → PB_RECORD_ID = "abc123def456789" │
|
||||
└────────┬─────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ 3. Installation proceeds...
|
||||
│ (container/VM creation, package install, etc.)
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ post_update_to_api("done", 0) │
|
||||
│ or │
|
||||
│ post_update_to_api("failed", $exit_code) │
|
||||
│ │
|
||||
│ PATCH → PB_API_URL/{PB_RECORD_ID} │
|
||||
│ Body: { "status": "sucess", "error": "", "exit_code": 0 } │
|
||||
│ or { "status": "failed", "error": "...", "exit_code": N }│
|
||||
│ │
|
||||
│ POST_UPDATE_DONE = true │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 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
|
||||
- **build.func**: Calls `post_to_api()` for LXC creation, then `post_update_to_api()` on completion
|
||||
- **vm-core.func**: Calls `post_to_api_vm()` for VM creation, then `post_update_to_api()` on completion
|
||||
- **install.func / alpine-install.func**: Reports installation status via `post_update_to_api()`
|
||||
|
||||
### With Error Handling
|
||||
- **error_handler.func**: Provides error explanations
|
||||
- **core.func**: Uses error descriptions in silent execution
|
||||
- **Diagnostic reporting**: Tracks error patterns
|
||||
- **error_handler.func**: Uses `explain_exit_code()` for human-readable error messages
|
||||
- **Diagnostic reporting**: PocketBase records track error patterns anonymously
|
||||
|
||||
### External Dependencies
|
||||
- **curl**: HTTP client for API communication
|
||||
- **Community Scripts API**: External API endpoint
|
||||
- **Network connectivity**: Required for API communication
|
||||
- **curl**: HTTP client for PocketBase API communication
|
||||
- **PocketBase**: Backend at `http://db.community-scripts.org`
|
||||
- **Network connectivity**: Required for API communication (failures are silently ignored)
|
||||
|
||||
Reference in New Issue
Block a user