795 lines
17 KiB
Markdown
795 lines
17 KiB
Markdown
# api.func Usage Examples
|
|
|
|
## Overview
|
|
|
|
This document provides practical usage examples for `api.func` functions, covering common scenarios, integration patterns, and best practices.
|
|
|
|
## Basic API Setup
|
|
|
|
### Standard API Initialization
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
# Standard API setup for LXC containers
|
|
|
|
source api.func
|
|
|
|
# Set up diagnostic reporting
|
|
export DIAGNOSTICS="yes"
|
|
export RANDOM_UUID="$(uuidgen)"
|
|
|
|
# Set container parameters
|
|
export CT_TYPE=1
|
|
export DISK_SIZE=8
|
|
export CORE_COUNT=2
|
|
export RAM_SIZE=2048
|
|
export var_os="debian"
|
|
export var_version="12"
|
|
export NSAPP="plex"
|
|
export METHOD="install"
|
|
|
|
# Report installation start
|
|
post_to_api
|
|
|
|
# Your installation code here
|
|
# ... installation logic ...
|
|
|
|
# Report completion
|
|
if [[ $? -eq 0 ]]; then
|
|
post_update_to_api "success" 0
|
|
else
|
|
post_update_to_api "failed" $?
|
|
fi
|
|
```
|
|
|
|
### VM API Setup
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
# API setup for VMs
|
|
|
|
source api.func
|
|
|
|
# Create diagnostics file for VM
|
|
mkdir -p /usr/local/community-scripts
|
|
echo "DIAGNOSTICS=yes" > /usr/local/community-scripts/diagnostics
|
|
|
|
# Set up VM parameters
|
|
export RANDOM_UUID="$(uuidgen)"
|
|
export DISK_SIZE="20G"
|
|
export CORE_COUNT=4
|
|
export RAM_SIZE=4096
|
|
export var_os="ubuntu"
|
|
export var_version="22.04"
|
|
export NSAPP="nextcloud"
|
|
export METHOD="install"
|
|
|
|
# Report VM installation start
|
|
post_to_api_vm
|
|
|
|
# Your VM installation code here
|
|
# ... VM creation logic ...
|
|
|
|
# Report completion
|
|
post_update_to_api "success" 0
|
|
```
|
|
|
|
## Error Description Examples
|
|
|
|
### Basic Error Explanation
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
source api.func
|
|
|
|
# Explain common error codes
|
|
echo "Error 0: '$(get_error_description 0)'"
|
|
echo "Error 1: $(get_error_description 1)"
|
|
echo "Error 127: $(get_error_description 127)"
|
|
echo "Error 200: $(get_error_description 200)"
|
|
echo "Error 255: $(get_error_description 255)"
|
|
```
|
|
|
|
### Error Code Testing
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
source api.func
|
|
|
|
# Test all error codes
|
|
test_error_codes() {
|
|
local codes=(0 1 2 127 128 130 137 139 143 200 203 205 255)
|
|
|
|
for code in "${codes[@]}"; do
|
|
echo "Code $code: $(get_error_description $code)"
|
|
done
|
|
}
|
|
|
|
test_error_codes
|
|
```
|
|
|
|
### Error Handling with Descriptions
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
source api.func
|
|
|
|
# Function with error handling
|
|
run_command_with_error_handling() {
|
|
local command="$1"
|
|
local description="$2"
|
|
|
|
echo "Running: $description"
|
|
|
|
if $command; then
|
|
echo "Success: $description"
|
|
return 0
|
|
else
|
|
local exit_code=$?
|
|
local error_msg=$(get_error_description $exit_code)
|
|
echo "Error $exit_code: $error_msg"
|
|
return $exit_code
|
|
fi
|
|
}
|
|
|
|
# Usage
|
|
run_command_with_error_handling "apt-get update" "Package list update"
|
|
run_command_with_error_handling "nonexistent_command" "Test command"
|
|
```
|
|
|
|
## API Communication Examples
|
|
|
|
### LXC Installation Reporting
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
source api.func
|
|
|
|
# Complete LXC installation with API reporting
|
|
install_lxc_with_reporting() {
|
|
local app="$1"
|
|
local ctid="$2"
|
|
|
|
# Set up API reporting
|
|
export DIAGNOSTICS="yes"
|
|
export RANDOM_UUID="$(uuidgen)"
|
|
export CT_TYPE=1
|
|
export DISK_SIZE=10
|
|
export CORE_COUNT=2
|
|
export RAM_SIZE=2048
|
|
export var_os="debian"
|
|
export var_version="12"
|
|
export NSAPP="$app"
|
|
export METHOD="install"
|
|
|
|
# Report installation start
|
|
post_to_api
|
|
|
|
# Installation process
|
|
echo "Installing $app container (ID: $ctid)..."
|
|
|
|
# Simulate installation
|
|
sleep 2
|
|
|
|
# Check if installation succeeded
|
|
if [[ $? -eq 0 ]]; then
|
|
echo "Installation completed successfully"
|
|
post_update_to_api "success" 0
|
|
return 0
|
|
else
|
|
echo "Installation failed"
|
|
post_update_to_api "failed" $?
|
|
return 1
|
|
fi
|
|
}
|
|
|
|
# Install multiple containers
|
|
install_lxc_with_reporting "plex" "100"
|
|
install_lxc_with_reporting "nextcloud" "101"
|
|
install_lxc_with_reporting "nginx" "102"
|
|
```
|
|
|
|
### VM Installation Reporting
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
source api.func
|
|
|
|
# Complete VM installation with API reporting
|
|
install_vm_with_reporting() {
|
|
local app="$1"
|
|
local vmid="$2"
|
|
|
|
# Create diagnostics file
|
|
mkdir -p /usr/local/community-scripts
|
|
echo "DIAGNOSTICS=yes" > /usr/local/community-scripts/diagnostics
|
|
|
|
# Set up API reporting
|
|
export RANDOM_UUID="$(uuidgen)"
|
|
export DISK_SIZE="20G"
|
|
export CORE_COUNT=4
|
|
export RAM_SIZE=4096
|
|
export var_os="ubuntu"
|
|
export var_version="22.04"
|
|
export NSAPP="$app"
|
|
export METHOD="install"
|
|
|
|
# Report VM installation start
|
|
post_to_api_vm
|
|
|
|
# VM installation process
|
|
echo "Installing $app VM (ID: $vmid)..."
|
|
|
|
# Simulate VM creation
|
|
sleep 3
|
|
|
|
# Check if VM creation succeeded
|
|
if [[ $? -eq 0 ]]; then
|
|
echo "VM installation completed successfully"
|
|
post_update_to_api "success" 0
|
|
return 0
|
|
else
|
|
echo "VM installation failed"
|
|
post_update_to_api "failed" $?
|
|
return 1
|
|
fi
|
|
}
|
|
|
|
# Install multiple VMs
|
|
install_vm_with_reporting "nextcloud" "200"
|
|
install_vm_with_reporting "wordpress" "201"
|
|
```
|
|
|
|
## Status Update Examples
|
|
|
|
### Success Reporting
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
source api.func
|
|
|
|
# Report successful installation
|
|
report_success() {
|
|
local operation="$1"
|
|
|
|
export DIAGNOSTICS="yes"
|
|
export RANDOM_UUID="$(uuidgen)"
|
|
|
|
echo "Reporting successful $operation"
|
|
post_update_to_api "success" 0
|
|
}
|
|
|
|
# Usage
|
|
report_success "container installation"
|
|
report_success "package installation"
|
|
report_success "service configuration"
|
|
```
|
|
|
|
### Failure Reporting
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
source api.func
|
|
|
|
# Report failed installation
|
|
report_failure() {
|
|
local operation="$1"
|
|
local exit_code="$2"
|
|
|
|
export DIAGNOSTICS="yes"
|
|
export RANDOM_UUID="$(uuidgen)"
|
|
|
|
local error_msg=$(get_error_description $exit_code)
|
|
echo "Reporting failed $operation: $error_msg"
|
|
post_update_to_api "failed" $exit_code
|
|
}
|
|
|
|
# Usage
|
|
report_failure "container creation" 200
|
|
report_failure "package installation" 127
|
|
report_failure "service start" 1
|
|
```
|
|
|
|
### Conditional Status Reporting
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
source api.func
|
|
|
|
# Conditional status reporting
|
|
report_installation_status() {
|
|
local operation="$1"
|
|
local exit_code="$2"
|
|
|
|
export DIAGNOSTICS="yes"
|
|
export RANDOM_UUID="$(uuidgen)"
|
|
|
|
if [[ $exit_code -eq 0 ]]; then
|
|
echo "Reporting successful $operation"
|
|
post_update_to_api "success" 0
|
|
else
|
|
local error_msg=$(get_error_description $exit_code)
|
|
echo "Reporting failed $operation: $error_msg"
|
|
post_update_to_api "failed" $exit_code
|
|
fi
|
|
}
|
|
|
|
# Usage
|
|
report_installation_status "container creation" 0
|
|
report_installation_status "package installation" 127
|
|
```
|
|
|
|
## Advanced Usage Examples
|
|
|
|
### Batch Installation with API Reporting
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
source api.func
|
|
|
|
# Batch installation with comprehensive API reporting
|
|
batch_install_with_reporting() {
|
|
local apps=("plex" "nextcloud" "nginx" "mysql")
|
|
local ctids=(100 101 102 103)
|
|
|
|
# Set up API reporting
|
|
export DIAGNOSTICS="yes"
|
|
export RANDOM_UUID="$(uuidgen)"
|
|
export CT_TYPE=1
|
|
export DISK_SIZE=8
|
|
export CORE_COUNT=2
|
|
export RAM_SIZE=2048
|
|
export var_os="debian"
|
|
export var_version="12"
|
|
export METHOD="install"
|
|
|
|
local success_count=0
|
|
local failure_count=0
|
|
|
|
for i in "${!apps[@]}"; do
|
|
local app="${apps[$i]}"
|
|
local ctid="${ctids[$i]}"
|
|
|
|
echo "Installing $app (ID: $ctid)..."
|
|
|
|
# Set app-specific parameters
|
|
export NSAPP="$app"
|
|
|
|
# Report installation start
|
|
post_to_api
|
|
|
|
# Simulate installation
|
|
if install_app "$app" "$ctid"; then
|
|
echo "$app installed successfully"
|
|
post_update_to_api "success" 0
|
|
((success_count++))
|
|
else
|
|
echo "$app installation failed"
|
|
post_update_to_api "failed" $?
|
|
((failure_count++))
|
|
fi
|
|
|
|
echo "---"
|
|
done
|
|
|
|
echo "Batch installation completed: $success_count successful, $failure_count failed"
|
|
}
|
|
|
|
# Mock installation function
|
|
install_app() {
|
|
local app="$1"
|
|
local ctid="$2"
|
|
|
|
# Simulate installation
|
|
sleep 1
|
|
|
|
# Simulate occasional failures
|
|
if [[ $((RANDOM % 10)) -eq 0 ]]; then
|
|
return 1
|
|
fi
|
|
|
|
return 0
|
|
}
|
|
|
|
batch_install_with_reporting
|
|
```
|
|
|
|
### Error Analysis and Reporting
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
source api.func
|
|
|
|
# Analyze and report errors
|
|
analyze_and_report_errors() {
|
|
local log_file="$1"
|
|
|
|
export DIAGNOSTICS="yes"
|
|
export RANDOM_UUID="$(uuidgen)"
|
|
|
|
if [[ ! -f "$log_file" ]]; then
|
|
echo "Log file not found: $log_file"
|
|
return 1
|
|
fi
|
|
|
|
# Extract error codes from log
|
|
local error_codes=$(grep -o 'exit code [0-9]\+' "$log_file" | grep -o '[0-9]\+' | sort -u)
|
|
|
|
if [[ -z "$error_codes" ]]; then
|
|
echo "No errors found in log"
|
|
post_update_to_api "success" 0
|
|
return 0
|
|
fi
|
|
|
|
echo "Found error codes: $error_codes"
|
|
|
|
# Report each unique error
|
|
for code in $error_codes; do
|
|
local error_msg=$(get_error_description $code)
|
|
echo "Error $code: $error_msg"
|
|
post_update_to_api "failed" $code
|
|
done
|
|
}
|
|
|
|
# Usage
|
|
analyze_and_report_errors "/var/log/installation.log"
|
|
```
|
|
|
|
### API Health Check
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
source api.func
|
|
|
|
# Check API connectivity and functionality
|
|
check_api_health() {
|
|
echo "Checking API health..."
|
|
|
|
# Test prerequisites
|
|
if ! command -v curl >/dev/null 2>&1; then
|
|
echo "ERROR: curl not available"
|
|
return 1
|
|
fi
|
|
|
|
# Test error description function
|
|
local test_error=$(get_error_description 127)
|
|
if [[ -z "$test_error" ]]; then
|
|
echo "ERROR: Error description function not working"
|
|
return 1
|
|
fi
|
|
|
|
echo "Error description test: $test_error"
|
|
|
|
# Test API connectivity (without sending data)
|
|
local api_url="http://api.community-scripts.org/dev/upload"
|
|
if curl -s --head "$api_url" >/dev/null 2>&1; then
|
|
echo "API endpoint is reachable"
|
|
else
|
|
echo "WARNING: API endpoint not reachable"
|
|
fi
|
|
|
|
echo "API health check completed"
|
|
}
|
|
|
|
check_api_health
|
|
```
|
|
|
|
## Integration Examples
|
|
|
|
### With build.func
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
# Integration with build.func
|
|
|
|
source core.func
|
|
source api.func
|
|
source build.func
|
|
|
|
# Set up API reporting
|
|
export DIAGNOSTICS="yes"
|
|
export RANDOM_UUID="$(uuidgen)"
|
|
|
|
# Container creation with API reporting
|
|
create_container_with_reporting() {
|
|
local app="$1"
|
|
local ctid="$2"
|
|
|
|
# Set container parameters
|
|
export APP="$app"
|
|
export CTID="$ctid"
|
|
export var_hostname="${app}-server"
|
|
export var_os="debian"
|
|
export var_version="12"
|
|
export var_cpu="2"
|
|
export var_ram="2048"
|
|
export var_disk="10"
|
|
export var_net="vmbr0"
|
|
export var_gateway="192.168.1.1"
|
|
export var_ip="192.168.1.$ctid"
|
|
export var_template_storage="local"
|
|
export var_container_storage="local"
|
|
|
|
# Report installation start
|
|
post_to_api
|
|
|
|
# Create container using build.func
|
|
if source build.func; then
|
|
echo "Container $app created successfully"
|
|
post_update_to_api "success" 0
|
|
return 0
|
|
else
|
|
echo "Container $app creation failed"
|
|
post_update_to_api "failed" $?
|
|
return 1
|
|
fi
|
|
}
|
|
|
|
# Create containers
|
|
create_container_with_reporting "plex" "100"
|
|
create_container_with_reporting "nextcloud" "101"
|
|
```
|
|
|
|
### With vm-core.func
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
# Integration with vm-core.func
|
|
|
|
source core.func
|
|
source api.func
|
|
source vm-core.func
|
|
|
|
# Set up VM API reporting
|
|
mkdir -p /usr/local/community-scripts
|
|
echo "DIAGNOSTICS=yes" > /usr/local/community-scripts/diagnostics
|
|
|
|
export RANDOM_UUID="$(uuidgen)"
|
|
|
|
# VM creation with API reporting
|
|
create_vm_with_reporting() {
|
|
local app="$1"
|
|
local vmid="$2"
|
|
|
|
# Set VM parameters
|
|
export APP="$app"
|
|
export VMID="$vmid"
|
|
export var_hostname="${app}-vm"
|
|
export var_os="ubuntu"
|
|
export var_version="22.04"
|
|
export var_cpu="4"
|
|
export var_ram="4096"
|
|
export var_disk="20"
|
|
|
|
# Report VM installation start
|
|
post_to_api_vm
|
|
|
|
# Create VM using vm-core.func
|
|
if source vm-core.func; then
|
|
echo "VM $app created successfully"
|
|
post_update_to_api "success" 0
|
|
return 0
|
|
else
|
|
echo "VM $app creation failed"
|
|
post_update_to_api "failed" $?
|
|
return 1
|
|
fi
|
|
}
|
|
|
|
# Create VMs
|
|
create_vm_with_reporting "nextcloud" "200"
|
|
create_vm_with_reporting "wordpress" "201"
|
|
```
|
|
|
|
### With error_handler.func
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
# Integration with error_handler.func
|
|
|
|
source core.func
|
|
source error_handler.func
|
|
source api.func
|
|
|
|
# Enhanced error handling with API reporting
|
|
enhanced_error_handler() {
|
|
local exit_code=${1:-$?}
|
|
local command=${2:-${BASH_COMMAND:-unknown}}
|
|
|
|
# Get error description from api.func
|
|
local error_msg=$(get_error_description $exit_code)
|
|
|
|
# Display error information
|
|
echo "Error $exit_code: $error_msg"
|
|
echo "Command: $command"
|
|
|
|
# Report error to API
|
|
export DIAGNOSTICS="yes"
|
|
export RANDOM_UUID="$(uuidgen)"
|
|
post_update_to_api "failed" $exit_code
|
|
|
|
# Use standard error handler
|
|
error_handler $exit_code $command
|
|
}
|
|
|
|
# Set up enhanced error handling
|
|
trap 'enhanced_error_handler' ERR
|
|
|
|
# Test enhanced error handling
|
|
nonexistent_command
|
|
```
|
|
|
|
## Best Practices Examples
|
|
|
|
### Comprehensive API Integration
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
# Comprehensive API integration example
|
|
|
|
source core.func
|
|
source api.func
|
|
|
|
# Set up comprehensive API reporting
|
|
setup_api_reporting() {
|
|
# Enable diagnostics
|
|
export DIAGNOSTICS="yes"
|
|
export RANDOM_UUID="$(uuidgen)"
|
|
|
|
# Set common parameters
|
|
export CT_TYPE=1
|
|
export DISK_SIZE=8
|
|
export CORE_COUNT=2
|
|
export RAM_SIZE=2048
|
|
export var_os="debian"
|
|
export var_version="12"
|
|
export METHOD="install"
|
|
|
|
echo "API reporting configured"
|
|
}
|
|
|
|
# Installation with comprehensive reporting
|
|
install_with_comprehensive_reporting() {
|
|
local app="$1"
|
|
local ctid="$2"
|
|
|
|
# Set up API reporting
|
|
setup_api_reporting
|
|
export NSAPP="$app"
|
|
|
|
# Report installation start
|
|
post_to_api
|
|
|
|
# Installation process
|
|
echo "Installing $app..."
|
|
|
|
# Simulate installation steps
|
|
local steps=("Downloading" "Installing" "Configuring" "Starting")
|
|
for step in "${steps[@]}"; do
|
|
echo "$step $app..."
|
|
sleep 1
|
|
done
|
|
|
|
# Check installation result
|
|
if [[ $? -eq 0 ]]; then
|
|
echo "$app installation completed successfully"
|
|
post_update_to_api "success" 0
|
|
return 0
|
|
else
|
|
echo "$app installation failed"
|
|
post_update_to_api "failed" $?
|
|
return 1
|
|
fi
|
|
}
|
|
|
|
# Install multiple applications
|
|
apps=("plex" "nextcloud" "nginx" "mysql")
|
|
ctids=(100 101 102 103)
|
|
|
|
for i in "${!apps[@]}"; do
|
|
install_with_comprehensive_reporting "${apps[$i]}" "${ctids[$i]}"
|
|
echo "---"
|
|
done
|
|
```
|
|
|
|
### Error Recovery with API Reporting
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
source api.func
|
|
|
|
# Error recovery with API reporting
|
|
retry_with_api_reporting() {
|
|
local operation="$1"
|
|
local max_attempts=3
|
|
local attempt=1
|
|
|
|
export DIAGNOSTICS="yes"
|
|
export RANDOM_UUID="$(uuidgen)"
|
|
|
|
while [[ $attempt -le $max_attempts ]]; do
|
|
echo "Attempt $attempt of $max_attempts: $operation"
|
|
|
|
if $operation; then
|
|
echo "Operation succeeded on attempt $attempt"
|
|
post_update_to_api "success" 0
|
|
return 0
|
|
else
|
|
local exit_code=$?
|
|
local error_msg=$(get_error_description $exit_code)
|
|
echo "Attempt $attempt failed: $error_msg"
|
|
|
|
post_update_to_api "failed" $exit_code
|
|
|
|
((attempt++))
|
|
|
|
if [[ $attempt -le $max_attempts ]]; then
|
|
echo "Retrying in 5 seconds..."
|
|
sleep 5
|
|
fi
|
|
fi
|
|
done
|
|
|
|
echo "Operation failed after $max_attempts attempts"
|
|
return 1
|
|
}
|
|
|
|
# Usage
|
|
retry_with_api_reporting "apt-get update"
|
|
retry_with_api_reporting "apt-get install -y package"
|
|
```
|
|
|
|
### API Reporting with Logging
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
source api.func
|
|
|
|
# API reporting with detailed logging
|
|
install_with_logging_and_api() {
|
|
local app="$1"
|
|
local log_file="/var/log/${app}_installation.log"
|
|
|
|
# Set up API reporting
|
|
export DIAGNOSTICS="yes"
|
|
export RANDOM_UUID="$(uuidgen)"
|
|
export NSAPP="$app"
|
|
|
|
# Start logging
|
|
exec > >(tee -a "$log_file")
|
|
exec 2>&1
|
|
|
|
echo "Starting $app installation at $(date)"
|
|
|
|
# Report installation start
|
|
post_to_api
|
|
|
|
# Installation process
|
|
echo "Installing $app..."
|
|
|
|
# Simulate installation
|
|
if install_app "$app"; then
|
|
echo "$app installation completed successfully at $(date)"
|
|
post_update_to_api "success" 0
|
|
return 0
|
|
else
|
|
local exit_code=$?
|
|
local error_msg=$(get_error_description $exit_code)
|
|
echo "$app installation failed at $(date): $error_msg"
|
|
post_update_to_api "failed" $exit_code
|
|
return $exit_code
|
|
fi
|
|
}
|
|
|
|
# Mock installation function
|
|
install_app() {
|
|
local app="$1"
|
|
echo "Installing $app..."
|
|
sleep 2
|
|
return 0
|
|
}
|
|
|
|
# Install with logging and API reporting
|
|
install_with_logging_and_api "plex"
|
|
```
|