644 lines
17 KiB
Markdown
644 lines
17 KiB
Markdown
# api.func Integration Guide
|
|
|
|
## Overview
|
|
|
|
This document describes how `api.func` integrates with other components in the Proxmox Community Scripts project, including dependencies, data flow, and API surface.
|
|
|
|
## Dependencies
|
|
|
|
### External Dependencies
|
|
|
|
#### Required Commands
|
|
- **`curl`**: HTTP client for API communication
|
|
- **`uuidgen`**: Generate unique identifiers (optional, can use other methods)
|
|
|
|
#### Optional Commands
|
|
- **None**: No other external command dependencies
|
|
|
|
### Internal Dependencies
|
|
|
|
#### Environment Variables from Other Scripts
|
|
- **build.func**: Provides container creation variables
|
|
- **vm-core.func**: Provides VM creation variables
|
|
- **core.func**: Provides system information variables
|
|
- **Installation scripts**: Provide application-specific variables
|
|
|
|
## Integration Points
|
|
|
|
### With build.func
|
|
|
|
#### LXC Container Reporting
|
|
```bash
|
|
# build.func uses api.func for container reporting
|
|
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() {
|
|
# Set container parameters
|
|
export CT_TYPE=1
|
|
export DISK_SIZE="$var_disk"
|
|
export CORE_COUNT="$var_cpu"
|
|
export RAM_SIZE="$var_ram"
|
|
export var_os="$var_os"
|
|
export var_version="$var_version"
|
|
export NSAPP="$APP"
|
|
export METHOD="install"
|
|
|
|
# Report installation start
|
|
post_to_api
|
|
|
|
# Container creation using build.func
|
|
# ... build.func container creation logic ...
|
|
|
|
# Report completion
|
|
if [[ $? -eq 0 ]]; then
|
|
post_update_to_api "success" 0
|
|
else
|
|
post_update_to_api "failed" $?
|
|
fi
|
|
}
|
|
```
|
|
|
|
#### Error Reporting Integration
|
|
```bash
|
|
# build.func uses api.func for error reporting
|
|
handle_container_error() {
|
|
local exit_code=$1
|
|
local error_msg=$(get_error_description $exit_code)
|
|
|
|
echo "Container creation failed: $error_msg"
|
|
post_update_to_api "failed" $exit_code
|
|
}
|
|
```
|
|
|
|
### With vm-core.func
|
|
|
|
#### VM Installation Reporting
|
|
```bash
|
|
# vm-core.func uses api.func for VM reporting
|
|
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() {
|
|
# Set VM parameters
|
|
export DISK_SIZE="${var_disk}G"
|
|
export CORE_COUNT="$var_cpu"
|
|
export RAM_SIZE="$var_ram"
|
|
export var_os="$var_os"
|
|
export var_version="$var_version"
|
|
export NSAPP="$APP"
|
|
export METHOD="install"
|
|
|
|
# Report VM installation start
|
|
post_to_api_vm
|
|
|
|
# VM creation using vm-core.func
|
|
# ... vm-core.func VM creation logic ...
|
|
|
|
# Report completion
|
|
post_update_to_api "success" 0
|
|
}
|
|
```
|
|
|
|
### With core.func
|
|
|
|
#### System Information Integration
|
|
```bash
|
|
# core.func provides system information for api.func
|
|
source core.func
|
|
source api.func
|
|
|
|
# Get system information for API reporting
|
|
get_system_info_for_api() {
|
|
# Get PVE version using core.func utilities
|
|
local pve_version=$(pveversion | awk -F'[/ ]' '{print $2}')
|
|
|
|
# Set API parameters
|
|
export var_os="$var_os"
|
|
export var_version="$var_version"
|
|
|
|
# Use core.func error handling with api.func reporting
|
|
if silent apt-get update; then
|
|
post_update_to_api "success" 0
|
|
else
|
|
post_update_to_api "failed" $?
|
|
fi
|
|
}
|
|
```
|
|
|
|
### With error_handler.func
|
|
|
|
#### Error Description Integration
|
|
```bash
|
|
# error_handler.func uses api.func for error descriptions
|
|
source core.func
|
|
source error_handler.func
|
|
source api.func
|
|
|
|
# Enhanced error handler 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
|
|
}
|
|
```
|
|
|
|
### With install.func
|
|
|
|
#### Installation Process Reporting
|
|
```bash
|
|
# install.func uses api.func for installation reporting
|
|
source core.func
|
|
source api.func
|
|
source install.func
|
|
|
|
# Installation with API reporting
|
|
install_package_with_reporting() {
|
|
local package="$1"
|
|
|
|
# Set up API reporting
|
|
export DIAGNOSTICS="yes"
|
|
export RANDOM_UUID="$(uuidgen)"
|
|
export NSAPP="$package"
|
|
export METHOD="install"
|
|
|
|
# Report installation start
|
|
post_to_api
|
|
|
|
# Package installation using install.func
|
|
if install_package "$package"; then
|
|
echo "$package installed successfully"
|
|
post_update_to_api "success" 0
|
|
return 0
|
|
else
|
|
local exit_code=$?
|
|
local error_msg=$(get_error_description $exit_code)
|
|
echo "$package installation failed: $error_msg"
|
|
post_update_to_api "failed" $exit_code
|
|
return $exit_code
|
|
fi
|
|
}
|
|
```
|
|
|
|
### With alpine-install.func
|
|
|
|
#### Alpine Installation Reporting
|
|
```bash
|
|
# alpine-install.func uses api.func for Alpine reporting
|
|
source core.func
|
|
source api.func
|
|
source alpine-install.func
|
|
|
|
# Alpine installation with API reporting
|
|
install_alpine_with_reporting() {
|
|
local app="$1"
|
|
|
|
# Set up API reporting
|
|
export DIAGNOSTICS="yes"
|
|
export RANDOM_UUID="$(uuidgen)"
|
|
export NSAPP="$app"
|
|
export METHOD="install"
|
|
export var_os="alpine"
|
|
|
|
# Report Alpine installation start
|
|
post_to_api
|
|
|
|
# Alpine installation using alpine-install.func
|
|
if install_alpine_app "$app"; then
|
|
echo "Alpine $app installed successfully"
|
|
post_update_to_api "success" 0
|
|
return 0
|
|
else
|
|
local exit_code=$?
|
|
local error_msg=$(get_error_description $exit_code)
|
|
echo "Alpine $app installation failed: $error_msg"
|
|
post_update_to_api "failed" $exit_code
|
|
return $exit_code
|
|
fi
|
|
}
|
|
```
|
|
|
|
### With alpine-tools.func
|
|
|
|
#### Alpine Tools Reporting
|
|
```bash
|
|
# alpine-tools.func uses api.func for Alpine tools reporting
|
|
source core.func
|
|
source api.func
|
|
source alpine-tools.func
|
|
|
|
# Alpine tools with API reporting
|
|
run_alpine_tool_with_reporting() {
|
|
local tool="$1"
|
|
|
|
# Set up API reporting
|
|
export DIAGNOSTICS="yes"
|
|
export RANDOM_UUID="$(uuidgen)"
|
|
export NSAPP="alpine-tools"
|
|
export METHOD="tool"
|
|
|
|
# Report tool execution start
|
|
post_to_api
|
|
|
|
# Run Alpine tool using alpine-tools.func
|
|
if run_alpine_tool "$tool"; then
|
|
echo "Alpine tool $tool executed successfully"
|
|
post_update_to_api "success" 0
|
|
return 0
|
|
else
|
|
local exit_code=$?
|
|
local error_msg=$(get_error_description $exit_code)
|
|
echo "Alpine tool $tool failed: $error_msg"
|
|
post_update_to_api "failed" $exit_code
|
|
return $exit_code
|
|
fi
|
|
}
|
|
```
|
|
|
|
### With passthrough.func
|
|
|
|
#### Hardware Passthrough Reporting
|
|
```bash
|
|
# passthrough.func uses api.func for hardware reporting
|
|
source core.func
|
|
source api.func
|
|
source passthrough.func
|
|
|
|
# Hardware passthrough with API reporting
|
|
configure_passthrough_with_reporting() {
|
|
local hardware_type="$1"
|
|
|
|
# Set up API reporting
|
|
export DIAGNOSTICS="yes"
|
|
export RANDOM_UUID="$(uuidgen)"
|
|
export NSAPP="passthrough"
|
|
export METHOD="hardware"
|
|
|
|
# Report passthrough configuration start
|
|
post_to_api
|
|
|
|
# Configure passthrough using passthrough.func
|
|
if configure_passthrough "$hardware_type"; then
|
|
echo "Hardware passthrough configured successfully"
|
|
post_update_to_api "success" 0
|
|
return 0
|
|
else
|
|
local exit_code=$?
|
|
local error_msg=$(get_error_description $exit_code)
|
|
echo "Hardware passthrough failed: $error_msg"
|
|
post_update_to_api "failed" $exit_code
|
|
return $exit_code
|
|
fi
|
|
}
|
|
```
|
|
|
|
### With tools.func
|
|
|
|
#### Maintenance Operations Reporting
|
|
```bash
|
|
# tools.func uses api.func for maintenance reporting
|
|
source core.func
|
|
source api.func
|
|
source tools.func
|
|
|
|
# Maintenance operations with API reporting
|
|
run_maintenance_with_reporting() {
|
|
local operation="$1"
|
|
|
|
# Set up API reporting
|
|
export DIAGNOSTICS="yes"
|
|
export RANDOM_UUID="$(uuidgen)"
|
|
export NSAPP="maintenance"
|
|
export METHOD="tool"
|
|
|
|
# Report maintenance start
|
|
post_to_api
|
|
|
|
# Run maintenance using tools.func
|
|
if run_maintenance_operation "$operation"; then
|
|
echo "Maintenance operation $operation completed successfully"
|
|
post_update_to_api "success" 0
|
|
return 0
|
|
else
|
|
local exit_code=$?
|
|
local error_msg=$(get_error_description $exit_code)
|
|
echo "Maintenance operation $operation failed: $error_msg"
|
|
post_update_to_api "failed" $exit_code
|
|
return $exit_code
|
|
fi
|
|
}
|
|
```
|
|
|
|
## Data Flow
|
|
|
|
### Input Data
|
|
|
|
#### Environment Variables from Other Scripts
|
|
- **`CT_TYPE`**: Container type (1 for LXC, 2 for VM)
|
|
- **`DISK_SIZE`**: Disk size in GB
|
|
- **`CORE_COUNT`**: Number of CPU cores
|
|
- **`RAM_SIZE`**: RAM size in MB
|
|
- **`var_os`**: Operating system type
|
|
- **`var_version`**: OS version
|
|
- **`DISABLEIP6`**: IPv6 disable setting
|
|
- **`NSAPP`**: Namespace application name
|
|
- **`METHOD`**: Installation method
|
|
- **`DIAGNOSTICS`**: Enable/disable diagnostic reporting
|
|
- **`RANDOM_UUID`**: Unique identifier for tracking
|
|
|
|
#### Function Parameters
|
|
- **Exit codes**: Passed to `get_error_description()` and `post_update_to_api()`
|
|
- **Status information**: Passed to `post_update_to_api()`
|
|
- **API endpoints**: Hardcoded in functions
|
|
|
|
#### System Information
|
|
- **PVE version**: Retrieved from `pveversion` command
|
|
- **Disk size processing**: Processed for VM API (removes 'G' suffix)
|
|
- **Error codes**: Retrieved from command exit codes
|
|
|
|
### Processing Data
|
|
|
|
#### API Request Preparation
|
|
- **JSON payload creation**: Format data for API consumption
|
|
- **Data validation**: Ensure required fields are present
|
|
- **Error handling**: Handle missing or invalid data
|
|
- **Content type setting**: Set appropriate HTTP headers
|
|
|
|
#### Error Processing
|
|
- **Error code mapping**: Map numeric codes to descriptions
|
|
- **Error message formatting**: Format error descriptions
|
|
- **Unknown error handling**: Handle unrecognized error codes
|
|
- **Fallback messages**: Provide default error messages
|
|
|
|
#### API Communication
|
|
- **HTTP request preparation**: Prepare curl commands
|
|
- **Response handling**: Capture HTTP response codes
|
|
- **Error handling**: Handle network and API errors
|
|
- **Duplicate prevention**: Prevent duplicate status updates
|
|
|
|
### Output Data
|
|
|
|
#### API Communication
|
|
- **HTTP requests**: Sent to community-scripts.org API
|
|
- **Response codes**: Captured from API responses
|
|
- **Error information**: Reported to API
|
|
- **Status updates**: Sent to API
|
|
|
|
#### Error Information
|
|
- **Error descriptions**: Human-readable error messages
|
|
- **Error codes**: Mapped to descriptions
|
|
- **Context information**: Error context and details
|
|
- **Fallback messages**: Default error messages
|
|
|
|
#### System State
|
|
- **POST_UPDATE_DONE**: Prevents duplicate updates
|
|
- **RESPONSE**: Stores API response
|
|
- **JSON_PAYLOAD**: Stores formatted API data
|
|
- **API_URL**: Stores API endpoint
|
|
|
|
## API Surface
|
|
|
|
### Public Functions
|
|
|
|
#### Error Description
|
|
- **`get_error_description()`**: Convert exit codes to explanations
|
|
- **Parameters**: Exit code to explain
|
|
- **Returns**: Human-readable explanation string
|
|
- **Usage**: Called by other functions and scripts
|
|
|
|
#### API Communication
|
|
- **`post_to_api()`**: Send LXC installation data
|
|
- **`post_to_api_vm()`**: Send VM installation data
|
|
- **`post_update_to_api()`**: Send status updates
|
|
- **Parameters**: Status and exit code (for updates)
|
|
- **Returns**: None
|
|
- **Usage**: Called by installation scripts
|
|
|
|
### Internal Functions
|
|
|
|
#### None
|
|
- All functions in api.func are public
|
|
- No internal helper functions
|
|
- Direct implementation of all functionality
|
|
|
|
### Global Variables
|
|
|
|
#### Configuration Variables
|
|
- **`DIAGNOSTICS`**: Diagnostic reporting setting
|
|
- **`RANDOM_UUID`**: Unique tracking identifier
|
|
- **`POST_UPDATE_DONE`**: Duplicate update prevention
|
|
|
|
#### Data Variables
|
|
- **`CT_TYPE`**: Container type
|
|
- **`DISK_SIZE`**: Disk size
|
|
- **`CORE_COUNT`**: CPU core count
|
|
- **`RAM_SIZE`**: RAM size
|
|
- **`var_os`**: Operating system
|
|
- **`var_version`**: OS version
|
|
- **`DISABLEIP6`**: IPv6 setting
|
|
- **`NSAPP`**: Application namespace
|
|
- **`METHOD`**: Installation method
|
|
|
|
#### Internal Variables
|
|
- **`API_URL`**: API endpoint URL
|
|
- **`JSON_PAYLOAD`**: API request payload
|
|
- **`RESPONSE`**: API response
|
|
- **`DISK_SIZE_API`**: Processed disk size for VM API
|
|
|
|
## Integration Patterns
|
|
|
|
### Standard Integration Pattern
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
# Standard integration pattern
|
|
|
|
# 1. Source core.func first
|
|
source core.func
|
|
|
|
# 2. Source api.func
|
|
source api.func
|
|
|
|
# 3. Set up API reporting
|
|
export DIAGNOSTICS="yes"
|
|
export RANDOM_UUID="$(uuidgen)"
|
|
|
|
# 4. Set application parameters
|
|
export NSAPP="$APP"
|
|
export METHOD="install"
|
|
|
|
# 5. Report installation start
|
|
post_to_api
|
|
|
|
# 6. Perform installation
|
|
# ... installation logic ...
|
|
|
|
# 7. Report completion
|
|
post_update_to_api "success" 0
|
|
```
|
|
|
|
### Minimal Integration Pattern
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
# Minimal integration pattern
|
|
|
|
source api.func
|
|
|
|
# Basic error reporting
|
|
export DIAGNOSTICS="yes"
|
|
export RANDOM_UUID="$(uuidgen)"
|
|
|
|
# Report failure
|
|
post_update_to_api "failed" 127
|
|
```
|
|
|
|
### Advanced Integration Pattern
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
# Advanced integration pattern
|
|
|
|
source core.func
|
|
source api.func
|
|
source error_handler.func
|
|
|
|
# Set up comprehensive 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"
|
|
|
|
# Enhanced error handling with API reporting
|
|
enhanced_error_handler() {
|
|
local exit_code=${1:-$?}
|
|
local command=${2:-${BASH_COMMAND:-unknown}}
|
|
|
|
local error_msg=$(get_error_description $exit_code)
|
|
echo "Error $exit_code: $error_msg"
|
|
|
|
post_update_to_api "failed" $exit_code
|
|
error_handler $exit_code $command
|
|
}
|
|
|
|
trap 'enhanced_error_handler' ERR
|
|
|
|
# Advanced operations with API reporting
|
|
post_to_api
|
|
# ... operations ...
|
|
post_update_to_api "success" 0
|
|
```
|
|
|
|
## Error Handling Integration
|
|
|
|
### Automatic Error Reporting
|
|
- **Error Descriptions**: Provides human-readable error messages
|
|
- **API Integration**: Reports errors to community-scripts.org API
|
|
- **Error Tracking**: Tracks error patterns for project improvement
|
|
- **Diagnostic Data**: Contributes to anonymous usage analytics
|
|
|
|
### Manual Error Reporting
|
|
- **Custom Error Codes**: Use appropriate error codes for different scenarios
|
|
- **Error Context**: Provide context information for errors
|
|
- **Status Updates**: Report both success and failure cases
|
|
- **Error Analysis**: Analyze error patterns and trends
|
|
|
|
### API Communication Errors
|
|
- **Network Failures**: Handle API communication failures gracefully
|
|
- **Missing Prerequisites**: Check prerequisites before API calls
|
|
- **Duplicate Prevention**: Prevent duplicate status updates
|
|
- **Error Recovery**: Handle API errors without blocking installation
|
|
|
|
## Performance Considerations
|
|
|
|
### API Communication Overhead
|
|
- **Minimal Impact**: API calls add minimal overhead
|
|
- **Asynchronous**: API calls don't block installation process
|
|
- **Error Handling**: API failures don't affect installation
|
|
- **Optional**: API reporting is optional and can be disabled
|
|
|
|
### Memory Usage
|
|
- **Minimal Footprint**: API functions use minimal memory
|
|
- **Variable Reuse**: Global variables reused across functions
|
|
- **No Memory Leaks**: Proper cleanup prevents memory leaks
|
|
- **Efficient Processing**: Efficient JSON payload creation
|
|
|
|
### Execution Speed
|
|
- **Fast API Calls**: Quick API communication
|
|
- **Efficient Error Processing**: Fast error code processing
|
|
- **Minimal Delay**: Minimal delay in API operations
|
|
- **Non-blocking**: API calls don't block installation
|
|
|
|
## Security Considerations
|
|
|
|
### Data Privacy
|
|
- **Anonymous Reporting**: Only anonymous data is sent
|
|
- **No Sensitive Data**: No sensitive information is transmitted
|
|
- **User Control**: Users can disable diagnostic reporting
|
|
- **Data Minimization**: Only necessary data is sent
|
|
|
|
### API Security
|
|
- **HTTPS**: API communication uses secure protocols
|
|
- **Data Validation**: API data is validated before sending
|
|
- **Error Handling**: API errors are handled securely
|
|
- **No Credentials**: No authentication credentials are sent
|
|
|
|
### Network Security
|
|
- **Secure Communication**: Uses secure HTTP protocols
|
|
- **Error Handling**: Network errors are handled gracefully
|
|
- **No Data Leakage**: No sensitive data is leaked
|
|
- **Secure Endpoints**: Uses trusted API endpoints
|
|
|
|
## Future Integration Considerations
|
|
|
|
### Extensibility
|
|
- **New API Endpoints**: Easy to add new API endpoints
|
|
- **Additional Data**: Easy to add new data fields
|
|
- **Error Codes**: Easy to add new error code descriptions
|
|
- **API Versions**: Easy to support new API versions
|
|
|
|
### Compatibility
|
|
- **API Versioning**: Compatible with different API versions
|
|
- **Data Format**: Compatible with different data formats
|
|
- **Error Codes**: Compatible with different error code systems
|
|
- **Network Protocols**: Compatible with different network protocols
|
|
|
|
### Performance
|
|
- **Optimization**: API communication can be optimized
|
|
- **Caching**: API responses can be cached
|
|
- **Batch Operations**: Multiple operations can be batched
|
|
- **Async Processing**: API calls can be made asynchronous
|