yoohoo
This commit is contained in:
376
docs/API.md
Normal file
376
docs/API.md
Normal file
@@ -0,0 +1,376 @@
|
||||
# WiseTLP API Documentation
|
||||
|
||||
This document provides detailed information about WiseTLP's internal APIs and interfaces.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [System Detection API](#system-detection-api)
|
||||
- [AI Client API](#ai-client-api)
|
||||
- [TLP Management API](#tlp-management-api)
|
||||
- [Security API](#security-api)
|
||||
- [Configuration API](#configuration-api)
|
||||
- [Types and Structures](#types-and-structures)
|
||||
|
||||
## System Detection API
|
||||
|
||||
The system detection module provides comprehensive Linux system information gathering.
|
||||
|
||||
### `system.DetectSystem(ctx context.Context) (*Info, error)`
|
||||
|
||||
Detects basic system information including distribution, version, and package manager.
|
||||
|
||||
**Parameters:**
|
||||
- `ctx`: Context for cancellation and timeout control
|
||||
|
||||
**Returns:**
|
||||
- `*Info`: Basic system information structure
|
||||
- `error`: Error if detection fails
|
||||
|
||||
**Example:**
|
||||
```go
|
||||
ctx := context.Background()
|
||||
info, err := system.DetectSystem(ctx)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
fmt.Printf("Distribution: %s %s\n", info.Distribution, info.Version)
|
||||
```
|
||||
|
||||
### `system.GatherSystemInfo(ctx context.Context) (*types.SystemInfo, error)`
|
||||
|
||||
Collects comprehensive system information including hardware, power management, and kernel details.
|
||||
|
||||
**Parameters:**
|
||||
- `ctx`: Context for cancellation and timeout control
|
||||
|
||||
**Returns:**
|
||||
- `*types.SystemInfo`: Complete system information structure
|
||||
- `error`: Error if gathering fails
|
||||
|
||||
**Gathered Information:**
|
||||
- CPU details (model, cores, frequency, governor)
|
||||
- Memory information (total, available, swap)
|
||||
- Battery information (if present)
|
||||
- Power supply status
|
||||
- Kernel information and parameters
|
||||
- Hardware details (chassis, manufacturer, storage)
|
||||
- Distribution information
|
||||
|
||||
## AI Client API
|
||||
|
||||
The AI client module handles communication with various AI service providers.
|
||||
|
||||
### `ai.NewClient(config *types.AIConfig, logger *utils.Logger) *Client`
|
||||
|
||||
Creates a new AI client with the specified configuration.
|
||||
|
||||
**Parameters:**
|
||||
- `config`: AI service configuration
|
||||
- `logger`: Logger instance for structured logging
|
||||
|
||||
**Returns:**
|
||||
- `*Client`: Configured AI client instance
|
||||
|
||||
### `ai.ConfigureClient(logger *utils.Logger) (*Client, error)`
|
||||
|
||||
Interactively configures an AI client by prompting the user for provider selection and credentials.
|
||||
|
||||
**Parameters:**
|
||||
- `logger`: Logger instance
|
||||
|
||||
**Returns:**
|
||||
- `*Client`: Configured AI client
|
||||
- `error`: Configuration error
|
||||
|
||||
### `(*Client).GenerateConfig(ctx context.Context, sysInfo *types.SystemInfo, preferences *types.UserPreferences) (*types.TLPConfiguration, error)`
|
||||
|
||||
Generates an optimized TLP configuration using AI based on system information and user preferences.
|
||||
|
||||
**Parameters:**
|
||||
- `ctx`: Context for request timeout
|
||||
- `sysInfo`: Complete system information
|
||||
- `preferences`: User power management preferences
|
||||
|
||||
**Returns:**
|
||||
- `*types.TLPConfiguration`: Generated TLP configuration
|
||||
- `error`: Generation error
|
||||
|
||||
## TLP Management API
|
||||
|
||||
The TLP management module handles TLP installation, configuration, and validation.
|
||||
|
||||
### `tlp.NewManager(logger *utils.Logger) *Manager`
|
||||
|
||||
Creates a new TLP manager instance.
|
||||
|
||||
**Parameters:**
|
||||
- `logger`: Logger instance
|
||||
|
||||
**Returns:**
|
||||
- `*Manager`: TLP manager instance
|
||||
|
||||
### `(*Manager).GetStatus(ctx context.Context) (*types.TLPStatus, error)`
|
||||
|
||||
Retrieves the current TLP installation and configuration status.
|
||||
|
||||
**Returns:**
|
||||
- `*types.TLPStatus`: Current TLP status
|
||||
- `error`: Status retrieval error
|
||||
|
||||
### `(*Manager).Install(ctx context.Context, sysInfo *system.Info) error`
|
||||
|
||||
Installs TLP using the appropriate package manager for the detected distribution.
|
||||
|
||||
**Parameters:**
|
||||
- `ctx`: Context for operation timeout
|
||||
- `sysInfo`: System information for package manager selection
|
||||
|
||||
**Returns:**
|
||||
- `error`: Installation error
|
||||
|
||||
**Supported Package Managers:**
|
||||
- apt (Ubuntu, Debian)
|
||||
- dnf (Fedora, RHEL, CentOS)
|
||||
- pacman (Arch, Manjaro)
|
||||
- zypper (openSUSE)
|
||||
- yum (Legacy RHEL/CentOS)
|
||||
- apk (Alpine)
|
||||
|
||||
### `(*Manager).ApplyConfig(ctx context.Context, config *types.TLPConfiguration) error`
|
||||
|
||||
Applies a TLP configuration to the system.
|
||||
|
||||
**Parameters:**
|
||||
- `ctx`: Context for operation timeout
|
||||
- `config`: TLP configuration to apply
|
||||
|
||||
**Returns:**
|
||||
- `error`: Application error
|
||||
|
||||
**Operations:**
|
||||
1. Validates configuration
|
||||
2. Backs up existing configuration
|
||||
3. Writes new configuration
|
||||
4. Reloads TLP service
|
||||
|
||||
### `(*Manager).ValidateConfig(config *types.TLPConfiguration) error`
|
||||
|
||||
Validates a TLP configuration for correctness and safety.
|
||||
|
||||
**Parameters:**
|
||||
- `config`: Configuration to validate
|
||||
|
||||
**Returns:**
|
||||
- `error`: Validation error
|
||||
|
||||
## Security API
|
||||
|
||||
The security module handles API key storage and privilege escalation.
|
||||
|
||||
### `security.NewKeyStore() (*KeyStore, error)`
|
||||
|
||||
Creates a new encrypted key store for API keys.
|
||||
|
||||
**Returns:**
|
||||
- `*KeyStore`: Key store instance
|
||||
- `error`: Initialization error
|
||||
|
||||
### `(*KeyStore).StoreAPIKey(provider, apiKey string) error`
|
||||
|
||||
Securely stores an API key for a provider.
|
||||
|
||||
**Parameters:**
|
||||
- `provider`: AI service provider name
|
||||
- `apiKey`: API key to store
|
||||
|
||||
**Returns:**
|
||||
- `error`: Storage error
|
||||
|
||||
**Security Features:**
|
||||
- AES-GCM encryption
|
||||
- Master password protection
|
||||
- Secure file permissions (0600)
|
||||
|
||||
### `(*KeyStore).RetrieveAPIKey(provider string) (string, error)`
|
||||
|
||||
Retrieves and decrypts an API key for a provider.
|
||||
|
||||
**Parameters:**
|
||||
- `provider`: AI service provider name
|
||||
|
||||
**Returns:**
|
||||
- `string`: Decrypted API key
|
||||
- `error`: Retrieval error
|
||||
|
||||
### `security.NewPrivilegeManager(logger *utils.Logger) *PrivilegeManager`
|
||||
|
||||
Creates a new privilege manager for secure elevation.
|
||||
|
||||
### `(*PrivilegeManager).EscalateIfNeeded(args []string, operation string) error`
|
||||
|
||||
Escalates privileges using sudo if not already running as root.
|
||||
|
||||
**Parameters:**
|
||||
- `args`: Command arguments for elevated execution
|
||||
- `operation`: Description of operation requiring elevation
|
||||
|
||||
**Returns:**
|
||||
- `error`: Escalation error
|
||||
|
||||
## Configuration API
|
||||
|
||||
The configuration module handles user preference gathering and processing.
|
||||
|
||||
### `config.GatherUserPreferences() (*types.UserPreferences, error)`
|
||||
|
||||
Interactively gathers user preferences for power management.
|
||||
|
||||
**Returns:**
|
||||
- `*types.UserPreferences`: User preferences
|
||||
- `error`: Gathering error
|
||||
|
||||
**Collected Preferences:**
|
||||
- Power profile (balanced, performance, power saving, custom)
|
||||
- Use case (general, development, gaming, server, multimedia, office)
|
||||
- Battery priority (balanced, runtime, longevity)
|
||||
- Performance mode (adaptive, maximum, efficient)
|
||||
- Special requirements
|
||||
- Custom settings
|
||||
|
||||
### `config.ValidatePreferences(preferences *types.UserPreferences) error`
|
||||
|
||||
Validates user preferences for consistency and conflicts.
|
||||
|
||||
**Parameters:**
|
||||
- `preferences`: Preferences to validate
|
||||
|
||||
**Returns:**
|
||||
- `error`: Validation error
|
||||
|
||||
### `config.GetRecommendedSettings(preferences *types.UserPreferences) map[string]string`
|
||||
|
||||
Generates recommended TLP settings based on user preferences.
|
||||
|
||||
**Parameters:**
|
||||
- `preferences`: User preferences
|
||||
|
||||
**Returns:**
|
||||
- `map[string]string`: Recommended TLP settings
|
||||
|
||||
## Types and Structures
|
||||
|
||||
### SystemInfo
|
||||
|
||||
Complete system information structure containing:
|
||||
|
||||
```go
|
||||
type SystemInfo struct {
|
||||
CPU CPUInfo `json:"cpu"`
|
||||
Memory MemoryInfo `json:"memory"`
|
||||
Battery *BatteryInfo `json:"battery,omitempty"`
|
||||
PowerSupply PowerSupplyInfo `json:"power_supply"`
|
||||
Kernel KernelInfo `json:"kernel"`
|
||||
Distribution DistributionInfo `json:"distribution"`
|
||||
Hardware HardwareInfo `json:"hardware"`
|
||||
TLPStatus TLPStatus `json:"tlp_status"`
|
||||
}
|
||||
```
|
||||
|
||||
### UserPreferences
|
||||
|
||||
User power management preferences:
|
||||
|
||||
```go
|
||||
type UserPreferences struct {
|
||||
PowerProfile PowerProfile `json:"power_profile"`
|
||||
UseCase UseCase `json:"use_case"`
|
||||
BatteryPriority BatteryPriority `json:"battery_priority"`
|
||||
PerformanceMode PerformanceMode `json:"performance_mode"`
|
||||
CustomSettings map[string]interface{} `json:"custom_settings"`
|
||||
SpecialRequirements []string `json:"special_requirements"`
|
||||
}
|
||||
```
|
||||
|
||||
### TLPConfiguration
|
||||
|
||||
Generated TLP configuration:
|
||||
|
||||
```go
|
||||
type TLPConfiguration struct {
|
||||
Settings map[string]string `json:"settings"`
|
||||
Description string `json:"description"`
|
||||
Rationale map[string]string `json:"rationale"`
|
||||
Warnings []string `json:"warnings"`
|
||||
Generated time.Time `json:"generated"`
|
||||
SystemInfo *SystemInfo `json:"system_info"`
|
||||
Preferences *UserPreferences `json:"preferences"`
|
||||
}
|
||||
```
|
||||
|
||||
### AIConfig
|
||||
|
||||
AI service configuration:
|
||||
|
||||
```go
|
||||
type AIConfig struct {
|
||||
Provider AIProvider `json:"provider"`
|
||||
APIKey string `json:"-"` // Never serialized
|
||||
Endpoint string `json:"endpoint"`
|
||||
Model string `json:"model"`
|
||||
MaxTokens int `json:"max_tokens"`
|
||||
Temperature float64 `json:"temperature"`
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
All APIs follow Go's standard error handling patterns:
|
||||
|
||||
- Functions return `error` as the last return value
|
||||
- Errors are wrapped with context using `fmt.Errorf`
|
||||
- Custom error types are used for specific error conditions
|
||||
- Logging is performed at appropriate levels
|
||||
|
||||
## Context Usage
|
||||
|
||||
All long-running operations accept a `context.Context` parameter for:
|
||||
|
||||
- Cancellation support
|
||||
- Timeout handling
|
||||
- Request tracing
|
||||
- Graceful shutdown
|
||||
|
||||
## Logging
|
||||
|
||||
WiseTLP uses structured logging throughout:
|
||||
|
||||
```go
|
||||
logger := utils.NewLogger()
|
||||
logger.Info("Operation completed", "duration", elapsed, "items", count)
|
||||
logger.Error("Operation failed", "error", err, "context", ctx)
|
||||
```
|
||||
|
||||
Log levels:
|
||||
- `Debug`: Detailed debugging information
|
||||
- `Info`: General operational information
|
||||
- `Warn`: Warning conditions
|
||||
- `Error`: Error conditions
|
||||
|
||||
## Testing
|
||||
|
||||
All APIs include comprehensive unit tests:
|
||||
|
||||
```bash
|
||||
# Run API tests
|
||||
go test ./internal/...
|
||||
go test ./pkg/...
|
||||
|
||||
# Run with coverage
|
||||
go test -cover ./...
|
||||
```
|
||||
|
||||
Test patterns:
|
||||
- Table-driven tests for multiple scenarios
|
||||
- Mock interfaces for external dependencies
|
||||
- Integration tests for component interactions
|
||||
- Error condition testing
|
||||
Reference in New Issue
Block a user