mirror of
https://github.com/community-scripts/ProxmoxVED.git
synced 2026-02-25 05:57:26 +00:00
Add detailed documentation and refactor core functions
Expanded inline documentation and section headers across misc/api.func, misc/build.func, misc/core.func, misc/error_handler.func, and misc/install.func for improved maintainability and clarity. Refactored error handling to use centralized explain_exit_code and updated API telemetry/reporting logic. Enhanced modularity and structure of utility, validation, and setup functions, and improved comments for user guidance and developer onboarding.
This commit is contained in:
CanbiZ
295
misc/api.func
295
misc/api.func
@@ -2,77 +2,91 @@
|
||||
# Author: michelroegl-brunner
|
||||
# License: MIT | https://git.community-scripts.org/community-scripts/ProxmoxVED/raw/branch/main/LICENSE
|
||||
|
||||
get_error_description() {
|
||||
local exit_code="$1"
|
||||
case "$exit_code" in
|
||||
0) echo " " ;;
|
||||
1) echo "General error: An unspecified error occurred." ;;
|
||||
2) echo "Incorrect shell usage or invalid command arguments." ;;
|
||||
3) echo "Unexecuted function or invalid shell condition." ;;
|
||||
4) echo "Error opening a file or invalid path." ;;
|
||||
5) echo "I/O error: An input/output failure occurred." ;;
|
||||
6) echo "No such device or address." ;;
|
||||
7) echo "Insufficient memory or resource exhaustion." ;;
|
||||
8) echo "Non-executable file or invalid file format." ;;
|
||||
9) echo "Failed child process execution." ;;
|
||||
18) echo "Connection to a remote server failed." ;;
|
||||
22) echo "Invalid argument or faulty network connection." ;;
|
||||
28) echo "No space left on device." ;;
|
||||
35) echo "Timeout while establishing a connection." ;;
|
||||
56) echo "Faulty TLS connection." ;;
|
||||
60) echo "SSL certificate error." ;;
|
||||
100) echo "LXC install error: Unexpected error in create_lxc.sh." ;;
|
||||
101) echo "LXC install error: No network connection detected." ;;
|
||||
200) echo "LXC creation failed." ;;
|
||||
201) echo "LXC error: Invalid Storage class." ;;
|
||||
202) echo "User aborted menu in create_lxc.sh." ;;
|
||||
203) echo "CTID not set in create_lxc.sh." ;;
|
||||
204) echo "PCT_OSTYPE not set in create_lxc.sh." ;;
|
||||
205) echo "CTID cannot be less than 100 in create_lxc.sh." ;;
|
||||
206) echo "CTID already in use in create_lxc.sh." ;;
|
||||
207) echo "Template not found in create_lxc.sh." ;;
|
||||
208) echo "Error downloading template in create_lxc.sh." ;;
|
||||
209) echo "Container creation failed, but template is intact in create_lxc.sh." ;;
|
||||
125) echo "Docker error: Container could not start." ;;
|
||||
126) echo "Command not executable: Incorrect permissions or missing dependencies." ;;
|
||||
127) echo "Command not found: Incorrect path or missing dependency." ;;
|
||||
128) echo "Invalid exit signal, e.g., incorrect Git command." ;;
|
||||
129) echo "Signal 1 (SIGHUP): Process terminated due to hangup." ;;
|
||||
130) echo "Signal 2 (SIGINT): Manual termination via Ctrl+C." ;;
|
||||
132) echo "Signal 4 (SIGILL): Illegal machine instruction." ;;
|
||||
133) echo "Signal 5 (SIGTRAP): Debugging error or invalid breakpoint signal." ;;
|
||||
134) echo "Signal 6 (SIGABRT): Program aborted itself." ;;
|
||||
135) echo "Signal 7 (SIGBUS): Memory error, invalid memory address." ;;
|
||||
137) echo "Signal 9 (SIGKILL): Process forcibly terminated (OOM-killer or 'kill -9')." ;;
|
||||
139) echo "Signal 11 (SIGSEGV): Segmentation fault, possibly due to invalid pointer access." ;;
|
||||
141) echo "Signal 13 (SIGPIPE): Pipe closed unexpectedly." ;;
|
||||
143) echo "Signal 15 (SIGTERM): Process terminated normally." ;;
|
||||
152) echo "Signal 24 (SIGXCPU): CPU time limit exceeded." ;;
|
||||
255) echo "Unknown critical error, often due to missing permissions or broken scripts." ;;
|
||||
*) echo "Unknown error code ($exit_code)." ;;
|
||||
esac
|
||||
}
|
||||
# ==============================================================================
|
||||
# API.FUNC - TELEMETRY & DIAGNOSTICS API
|
||||
# ==============================================================================
|
||||
#
|
||||
# Provides functions for sending anonymous telemetry data to Community-Scripts
|
||||
# API for analytics and diagnostics purposes.
|
||||
#
|
||||
# Features:
|
||||
# - Container/VM creation statistics
|
||||
# - Installation success/failure tracking
|
||||
# - Error code mapping and reporting
|
||||
# - Privacy-respecting anonymous telemetry
|
||||
#
|
||||
# Usage:
|
||||
# source <(curl -fsSL .../api.func)
|
||||
# post_to_api # Report container creation
|
||||
# post_update_to_api # Report installation status
|
||||
#
|
||||
# Privacy:
|
||||
# - Only anonymous statistics (no personal data)
|
||||
# - User can opt-out via diagnostics settings
|
||||
# - Random UUID for session tracking only
|
||||
#
|
||||
# ==============================================================================
|
||||
|
||||
# ==============================================================================
|
||||
# SECTION 1: DEPENDENCY LOADING
|
||||
# ==============================================================================
|
||||
|
||||
# Load error_handler.func for explain_exit_code() function
|
||||
# This provides centralized error code descriptions (exit codes 1-255, shell, package managers, databases, custom Proxmox codes)
|
||||
if [[ -z "${COMMUNITY_SCRIPTS_BASE_URL:-}" ]]; then
|
||||
COMMUNITY_SCRIPTS_BASE_URL="https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main"
|
||||
fi
|
||||
|
||||
if ! declare -f explain_exit_code >/dev/null 2>&1; then
|
||||
source <(curl -fsSL "${COMMUNITY_SCRIPTS_BASE_URL}/misc/error_handler.func") || {
|
||||
echo "Failed to load error_handler.func" >&2
|
||||
return 1
|
||||
}
|
||||
fi
|
||||
|
||||
# ==============================================================================
|
||||
# SECTION 2: TELEMETRY FUNCTIONS
|
||||
# ==============================================================================
|
||||
|
||||
# ------------------------------------------------------------------------------
|
||||
# post_to_api()
|
||||
#
|
||||
# - Sends LXC container creation statistics to Community-Scripts API
|
||||
# - Only executes if:
|
||||
# * curl is available
|
||||
# * DIAGNOSTICS=yes
|
||||
# * RANDOM_UUID is set
|
||||
# - Payload includes:
|
||||
# * Container type, disk size, CPU cores, RAM
|
||||
# * OS type and version
|
||||
# * IPv6 disable status
|
||||
# * Application name (NSAPP)
|
||||
# * Installation method
|
||||
# * PVE version
|
||||
# * Status: "installing"
|
||||
# * Random UUID for session tracking
|
||||
# - Anonymous telemetry (no personal data)
|
||||
# ------------------------------------------------------------------------------
|
||||
post_to_api() {
|
||||
|
||||
if ! command -v curl &>/dev/null; then
|
||||
return
|
||||
fi
|
||||
if ! command -v curl &>/dev/null; then
|
||||
return
|
||||
fi
|
||||
|
||||
if [ "$DIAGNOSTICS" = "no" ]; then
|
||||
return
|
||||
fi
|
||||
if [ "$DIAGNOSTICS" = "no" ]; then
|
||||
return
|
||||
fi
|
||||
|
||||
if [ -z "$RANDOM_UUID" ]; then
|
||||
return
|
||||
fi
|
||||
if [ -z "$RANDOM_UUID" ]; then
|
||||
return
|
||||
fi
|
||||
|
||||
local API_URL="http://api.community-scripts.org/dev/upload"
|
||||
local pve_version="not found"
|
||||
pve_version=$(pveversion | awk -F'[/ ]' '{print $2}')
|
||||
local API_URL="http://api.community-scripts.org/dev/upload"
|
||||
local pve_version="not found"
|
||||
pve_version=$(pveversion | awk -F'[/ ]' '{print $2}')
|
||||
|
||||
JSON_PAYLOAD=$(
|
||||
cat <<EOF
|
||||
JSON_PAYLOAD=$(
|
||||
cat <<EOF
|
||||
{
|
||||
"ct_type": $CT_TYPE,
|
||||
"type":"lxc",
|
||||
@@ -89,41 +103,53 @@ post_to_api() {
|
||||
"random_id": "$RANDOM_UUID"
|
||||
}
|
||||
EOF
|
||||
)
|
||||
if [[ "$DIAGNOSTICS" == "yes" ]]; then
|
||||
RESPONSE=$(curl -s -w "%{http_code}" -L -X POST "$API_URL" --post301 --post302 \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$JSON_PAYLOAD") || true
|
||||
fi
|
||||
)
|
||||
if [[ "$DIAGNOSTICS" == "yes" ]]; then
|
||||
RESPONSE=$(curl -s -w "%{http_code}" -L -X POST "$API_URL" --post301 --post302 \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$JSON_PAYLOAD") || true
|
||||
fi
|
||||
|
||||
}
|
||||
|
||||
# ------------------------------------------------------------------------------
|
||||
# post_to_api_vm()
|
||||
#
|
||||
# - Sends VM creation statistics to Community-Scripts API
|
||||
# - Similar to post_to_api() but for virtual machines (not containers)
|
||||
# - Reads DIAGNOSTICS from /usr/local/community-scripts/diagnostics file
|
||||
# - Payload differences:
|
||||
# * ct_type=2 (VM instead of LXC)
|
||||
# * type="vm"
|
||||
# * Disk size without 'G' suffix (parsed from DISK_SIZE variable)
|
||||
# - Only executes if DIAGNOSTICS=yes and RANDOM_UUID is set
|
||||
# ------------------------------------------------------------------------------
|
||||
post_to_api_vm() {
|
||||
|
||||
if [[ ! -f /usr/local/community-scripts/diagnostics ]]; then
|
||||
return
|
||||
fi
|
||||
DIAGNOSTICS=$(grep -i "^DIAGNOSTICS=" /usr/local/community-scripts/diagnostics | awk -F'=' '{print $2}')
|
||||
if ! command -v curl &>/dev/null; then
|
||||
return
|
||||
fi
|
||||
if [[ ! -f /usr/local/community-scripts/diagnostics ]]; then
|
||||
return
|
||||
fi
|
||||
DIAGNOSTICS=$(grep -i "^DIAGNOSTICS=" /usr/local/community-scripts/diagnostics | awk -F'=' '{print $2}')
|
||||
if ! command -v curl &>/dev/null; then
|
||||
return
|
||||
fi
|
||||
|
||||
if [ "$DIAGNOSTICS" = "no" ]; then
|
||||
return
|
||||
fi
|
||||
if [ "$DIAGNOSTICS" = "no" ]; then
|
||||
return
|
||||
fi
|
||||
|
||||
if [ -z "$RANDOM_UUID" ]; then
|
||||
return
|
||||
fi
|
||||
if [ -z "$RANDOM_UUID" ]; then
|
||||
return
|
||||
fi
|
||||
|
||||
local API_URL="http://api.community-scripts.org/dev/upload"
|
||||
local pve_version="not found"
|
||||
pve_version=$(pveversion | awk -F'[/ ]' '{print $2}')
|
||||
local API_URL="http://api.community-scripts.org/dev/upload"
|
||||
local pve_version="not found"
|
||||
pve_version=$(pveversion | awk -F'[/ ]' '{print $2}')
|
||||
|
||||
DISK_SIZE_API=${DISK_SIZE%G}
|
||||
DISK_SIZE_API=${DISK_SIZE%G}
|
||||
|
||||
JSON_PAYLOAD=$(
|
||||
cat <<EOF
|
||||
JSON_PAYLOAD=$(
|
||||
cat <<EOF
|
||||
{
|
||||
"ct_type": 2,
|
||||
"type":"vm",
|
||||
@@ -140,57 +166,74 @@ post_to_api_vm() {
|
||||
"random_id": "$RANDOM_UUID"
|
||||
}
|
||||
EOF
|
||||
)
|
||||
if [[ "$DIAGNOSTICS" == "yes" ]]; then
|
||||
RESPONSE=$(curl -s -w "%{http_code}" -L -X POST "$API_URL" --post301 --post302 \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$JSON_PAYLOAD") || true
|
||||
fi
|
||||
)
|
||||
if [[ "$DIAGNOSTICS" == "yes" ]]; then
|
||||
RESPONSE=$(curl -s -w "%{http_code}" -L -X POST "$API_URL" --post301 --post302 \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$JSON_PAYLOAD") || true
|
||||
fi
|
||||
}
|
||||
|
||||
POST_UPDATE_DONE=false
|
||||
# ------------------------------------------------------------------------------
|
||||
# post_update_to_api()
|
||||
#
|
||||
# - Reports installation completion status to API
|
||||
# - Prevents duplicate submissions via POST_UPDATE_DONE flag
|
||||
# - Arguments:
|
||||
# * $1: status ("success" or "failed")
|
||||
# * $2: exit_code (default: 1 for failed, 0 for success)
|
||||
# - Payload includes:
|
||||
# * Final status (success/failed)
|
||||
# * Error description via get_error_description()
|
||||
# * Random UUID for session correlation
|
||||
# - Only executes once per session
|
||||
# - Silently returns if:
|
||||
# * curl not available
|
||||
# * Already reported (POST_UPDATE_DONE=true)
|
||||
# * DIAGNOSTICS=no
|
||||
# ------------------------------------------------------------------------------
|
||||
post_update_to_api() {
|
||||
|
||||
if ! command -v curl &>/dev/null; then
|
||||
return
|
||||
fi
|
||||
if ! command -v curl &>/dev/null; then
|
||||
return
|
||||
fi
|
||||
|
||||
if [ "$POST_UPDATE_DONE" = true ]; then
|
||||
return 0
|
||||
fi
|
||||
exit_code=${2:-1}
|
||||
local API_URL="http://api.community-scripts.org/dev/upload/updatestatus"
|
||||
local status="${1:-failed}"
|
||||
if [[ "$status" == "failed" ]]; then
|
||||
local exit_code="${2:-1}"
|
||||
elif [[ "$status" == "success" ]]; then
|
||||
local exit_code="${2:-0}"
|
||||
fi
|
||||
if [ "$POST_UPDATE_DONE" = true ]; then
|
||||
return 0
|
||||
fi
|
||||
exit_code=${2:-1}
|
||||
local API_URL="http://api.community-scripts.org/dev/upload/updatestatus"
|
||||
local status="${1:-failed}"
|
||||
if [[ "$status" == "failed" ]]; then
|
||||
local exit_code="${2:-1}"
|
||||
elif [[ "$status" == "success" ]]; then
|
||||
local exit_code="${2:-0}"
|
||||
fi
|
||||
|
||||
if [[ -z "$exit_code" ]]; then
|
||||
exit_code=1
|
||||
fi
|
||||
if [[ -z "$exit_code" ]]; then
|
||||
exit_code=1
|
||||
fi
|
||||
|
||||
error=$(get_error_description "$exit_code")
|
||||
error=$(explain_exit_code "$exit_code")
|
||||
|
||||
if [ -z "$error" ]; then
|
||||
error="Unknown error"
|
||||
fi
|
||||
if [ -z "$error" ]; then
|
||||
error="Unknown error"
|
||||
fi
|
||||
|
||||
JSON_PAYLOAD=$(
|
||||
cat <<EOF
|
||||
JSON_PAYLOAD=$(
|
||||
cat <<EOF
|
||||
{
|
||||
"status": "$status",
|
||||
"error": "$error",
|
||||
"random_id": "$RANDOM_UUID"
|
||||
}
|
||||
EOF
|
||||
)
|
||||
if [[ "$DIAGNOSTICS" == "yes" ]]; then
|
||||
RESPONSE=$(curl -s -w "%{http_code}" -L -X POST "$API_URL" --post301 --post302 \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$JSON_PAYLOAD") || true
|
||||
fi
|
||||
)
|
||||
if [[ "$DIAGNOSTICS" == "yes" ]]; then
|
||||
RESPONSE=$(curl -s -w "%{http_code}" -L -X POST "$API_URL" --post301 --post302 \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$JSON_PAYLOAD") || true
|
||||
fi
|
||||
|
||||
POST_UPDATE_DONE=true
|
||||
POST_UPDATE_DONE=true
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user