ProxmoxVED/docs/misc/core.func/CORE_INTEGRATION.md

core.func Integration Guide

Overview

This document describes how core.func integrates with other components in the Proxmox Community Scripts project, including dependencies, data flow, and API surface.

Dependencies

External Dependencies

Required Commands

• pveversion: Proxmox VE version checking
• dpkg: Architecture detection
• ps: Process and shell detection
• id: User ID checking
• curl: Header file downloading
• swapon: Swap status checking
• dd: Swap file creation
• mkswap: Swap file formatting

Optional Commands

• tput: Terminal control (installed if missing)
• apk: Alpine package manager
• apt-get: Debian package manager

Internal Dependencies

error_handler.func

• Purpose: Provides error code explanations for silent execution
• Usage: Automatically loaded when silent() encounters errors
• Integration: Called via explain_exit_code() function
• Data Flow: Error code → explanation → user display

Integration Points

With build.func

System Validation

# build.func uses core.func for system checks
source core.func
pve_check
arch_check
shell_check
root_check

User Interface

# build.func uses core.func for UI elements
msg_info "Creating container..."
msg_ok "Container created successfully"
msg_error "Container creation failed"

Silent Execution

# build.func uses core.func for command execution
silent pct create "$CTID" "$TEMPLATE" \
    --hostname "$HOSTNAME" \
    --memory "$MEMORY" \
    --cores "$CORES"

With tools.func

Utility Functions

# tools.func uses core.func utilities
source core.func

# System checks
pve_check
root_check

# UI elements
msg_info "Running maintenance tasks..."
msg_ok "Maintenance completed"

Error Handling

# tools.func uses core.func for error handling
if silent systemctl restart service; then
    msg_ok "Service restarted"
else
    msg_error "Service restart failed"
fi

With api.func

System Validation

# api.func uses core.func for system checks
source core.func
pve_check
root_check

API Operations

# api.func uses core.func for API calls
msg_info "Connecting to Proxmox API..."
if silent curl -k -H "Authorization: PVEAPIToken=$API_TOKEN" \
    "$API_URL/api2/json/nodes/$NODE/lxc"; then
    msg_ok "API connection successful"
else
    msg_error "API connection failed"
fi

With error_handler.func

Error Explanations

# error_handler.func provides explanations for core.func
explain_exit_code() {
    local code="$1"
    case "$code" in
        1) echo "General error" ;;
        2) echo "Misuse of shell builtins" ;;
        126) echo "Command invoked cannot execute" ;;
        127) echo "Command not found" ;;
        128) echo "Invalid argument to exit" ;;
        *) echo "Unknown error code" ;;
    esac
}

With install.func

Installation Process

# install.func uses core.func for installation
source core.func

# System checks
pve_check
root_check

# Installation steps
msg_info "Installing packages..."
silent apt-get update
silent apt-get install -y package

msg_ok "Installation completed"

With alpine-install.func

Alpine-Specific Operations

# alpine-install.func uses core.func for Alpine operations
source core.func

# Alpine detection
if is_alpine; then
    msg_info "Detected Alpine Linux"
    silent apk add --no-cache package
else
    msg_info "Detected Debian-based system"
    silent apt-get install -y package
fi

With alpine-tools.func

Alpine Utilities

# alpine-tools.func uses core.func for Alpine tools
source core.func

# Alpine-specific operations
if is_alpine; then
    msg_info "Running Alpine-specific operations..."
    # Alpine tools logic
    msg_ok "Alpine operations completed"
fi

With passthrough.func

Hardware Passthrough

# passthrough.func uses core.func for hardware operations
source core.func

# System checks
pve_check
root_check

# Hardware operations
msg_info "Configuring GPU passthrough..."
if silent lspci | grep -i nvidia; then
    msg_ok "NVIDIA GPU detected"
else
    msg_warn "No NVIDIA GPU found"
fi

With vm-core.func

VM Operations

# vm-core.func uses core.func for VM management
source core.func

# System checks
pve_check
root_check

# VM operations
msg_info "Creating virtual machine..."
silent qm create "$VMID" \
    --name "$VMNAME" \
    --memory "$MEMORY" \
    --cores "$CORES"

msg_ok "Virtual machine created"

Data Flow

Input Data

Environment Variables

• APP: Application name for header display
• APP_TYPE: Application type (ct/vm) for header paths
• VERBOSE: Verbose mode setting
• var_os: OS type for Alpine detection
• PCT_OSTYPE: Alternative OS type variable
• var_verbose: Alternative verbose setting
• var_full_verbose: Debug mode setting

Command Parameters

• Function arguments: Passed to individual functions
• Command arguments: Passed to silent() function
• User input: Collected via read commands

Processing Data

System Information

• Proxmox version: Parsed from pveversion output
• Architecture: Retrieved from dpkg --print-architecture
• Shell type: Detected from process information
• User ID: Retrieved from id -u
• SSH connection: Detected from SSH_CLIENT environment

UI State

• Message tracking: MSG_INFO_SHOWN associative array
• Spinner state: SPINNER_PID and SPINNER_MSG variables
• Terminal state: Cursor position and display mode

Error Information

• Exit codes: Captured from command execution
• Log output: Redirected to temporary log files
• Error explanations: Retrieved from error_handler.func

Output Data

User Interface

• Colored messages: ANSI color codes for terminal output
• Icons: Symbolic representations for different message types
• Spinners: Animated progress indicators
• Formatted text: Consistent message formatting

System State

• Exit codes: Returned from functions
• Log files: Created for silent execution
• Configuration: Modified system settings
• Process state: Spinner processes and cleanup

API Surface

Public Functions

System Validation

• pve_check(): Proxmox VE version validation
• arch_check(): Architecture validation
• shell_check(): Shell validation
• root_check(): Privilege validation
• ssh_check(): SSH connection warning

User Interface

• msg_info(): Informational messages
• msg_ok(): Success messages
• msg_error(): Error messages
• msg_warn(): Warning messages
• msg_custom(): Custom messages
• msg_debug(): Debug messages

Spinner Control

• spinner(): Start spinner animation
• stop_spinner(): Stop spinner and cleanup
• clear_line(): Clear current terminal line

Silent Execution

• silent(): Execute commands with error handling

Utility Functions

• is_alpine(): Alpine Linux detection
• is_verbose_mode(): Verbose mode detection
• fatal(): Fatal error handling
• ensure_tput(): Terminal control setup

Header Management

• get_header(): Download application headers
• header_info(): Display header information

System Management

• check_or_create_swap(): Swap file management

Internal Functions

Initialization

• load_functions(): Function loader
• color(): Color setup
• formatting(): Formatting setup
• icons(): Icon setup
• default_vars(): Default variables
• set_std_mode(): Standard mode setup

Color Management

• color_spinner(): Spinner colors

Global Variables

Color Variables

• YW, YWB, BL, RD, BGN, GN, DGN, CL: Color codes
• CS_YW, CS_YWB, CS_CL: Spinner colors

Formatting Variables

• BFR, BOLD, HOLD, TAB, TAB3: Formatting helpers

Icon Variables

• CM, CROSS, INFO, OS, OSVERSION, etc.: Message icons

Configuration Variables

• RETRY_NUM, RETRY_EVERY: Retry settings
• STD: Standard mode setting
• SILENT_LOGFILE: Log file path

State Variables

• _CORE_FUNC_LOADED: Loading prevention
• __FUNCTIONS_LOADED: Function loading prevention
• SPINNER_PID, SPINNER_MSG: Spinner state
• MSG_INFO_SHOWN: Message tracking

Integration Patterns

Standard Integration Pattern

#!/usr/bin/env bash
# Standard integration pattern

# 1. Source core.func first
source core.func

# 2. Run system checks
pve_check
arch_check
shell_check
root_check

# 3. Set up error handling
trap 'stop_spinner' EXIT INT TERM

# 4. Use UI functions
msg_info "Starting operation..."

# 5. Use silent execution
silent command

# 6. Show completion
msg_ok "Operation completed"

Minimal Integration Pattern

#!/usr/bin/env bash
# Minimal integration pattern

source core.func
pve_check
root_check

msg_info "Running operation..."
silent command
msg_ok "Operation completed"

Advanced Integration Pattern

#!/usr/bin/env bash
# Advanced integration pattern

source core.func

# System validation
pve_check
arch_check
shell_check
root_check
ssh_check

# Error handling
trap 'stop_spinner' EXIT INT TERM

# Verbose mode handling
if is_verbose_mode; then
    msg_info "Verbose mode enabled"
fi

# OS-specific operations
if is_alpine; then
    msg_info "Alpine Linux detected"
    # Alpine-specific logic
else
    msg_info "Debian-based system detected"
    # Debian-specific logic
fi

# Operation execution
msg_info "Starting operation..."
if silent command; then
    msg_ok "Operation succeeded"
else
    msg_error "Operation failed"
    exit 1
fi

Error Handling Integration

Silent Execution Error Flow

silent() command
├── Execute command
├── Capture output to log
├── Check exit code
├── If error:
│   ├── Load error_handler.func
│   ├── Get error explanation
│   ├── Display error details
│   ├── Show log excerpt
│   └── Exit with error code
└── If success: Continue

System Check Error Flow

System Check Function
├── Check system state
├── If valid: Return 0
└── If invalid:
    ├── Display error message
    ├── Show fix instructions
    ├── Sleep for user to read
    └── Exit with error code

Performance Considerations

Loading Optimization

• Single Loading: _CORE_FUNC_LOADED prevents multiple loading
• Function Loading: __FUNCTIONS_LOADED prevents multiple function loading
• Lazy Loading: Functions loaded only when needed

Memory Usage

• Minimal Footprint: Core functions use minimal memory
• Variable Reuse: Global variables reused across functions
• Cleanup: Spinner processes cleaned up on exit

Execution Speed

• Fast Checks: System checks are optimized for speed
• Efficient Spinners: Spinner animation uses minimal CPU
• Quick Messages: Message functions optimized for performance

Security Considerations

Privilege Escalation

• Root Check: Ensures script runs with sufficient privileges
• Shell Check: Validates shell environment
• Process Validation: Checks parent process for sudo usage

Input Validation

• Parameter Checking: Functions validate input parameters
• Error Handling: Proper error handling prevents crashes
• Safe Execution: Silent execution with proper error handling

System Protection

• Version Validation: Ensures compatible Proxmox version
• Architecture Check: Prevents execution on unsupported systems
• SSH Warning: Warns about external SSH usage

Future Integration Considerations

Extensibility

• Function Groups: Easy to add new function groups
• Message Types: Easy to add new message types
• System Checks: Easy to add new system checks

Compatibility

• Version Support: Easy to add new Proxmox versions
• OS Support: Easy to add new operating systems
• Architecture Support: Easy to add new architectures

Performance

• Optimization: Functions can be optimized for better performance
• Caching: Results can be cached for repeated operations
• Parallelization: Operations can be parallelized where appropriate