cloud/sdk/doc.go

// Package sdk provides enterprise-grade Go SDK for secure integration with VXControl Cloud Platform APIs.
//
// The SDK implements a comprehensive security framework featuring memory-hard proof-of-work
// protection, end-to-end AES-GCM encryption, Ed25519 signatures, and automatic retry logic.
// It offers 24 strongly-typed function patterns covering all request/response scenarios
// with built-in connection pooling, HTTP/2 support, and streaming architecture for
// high-performance integration with cloud services.
//
// # Architecture Overview
//
// The SDK consists of several core components working together:
//
//   - Call Generation: 24 strongly-typed function patterns for all API scenarios
//   - Transport Layer: HTTP/2 optimized transport with connection pooling
//   - Security Engine: PoW challenges, AES-GCM encryption, Ed25519 signatures
//   - License System: Cryptographic license validation with tier enforcement
//   - Logging Framework: Structured logging with configurable levels and formats
//
// # Quick Start
//
// Basic SDK usage involves defining client structure, configuring endpoints, and building:
//
//	import "github.com/vxcontrol/cloud/sdk"
//
//	// Define client with typed API functions
//	type Client struct {
//	    CheckUpdates  sdk.CallReqBytesRespBytes    // JSON request/response
//	    DownloadFile  sdk.CallReqQueryRespWriter   // Query params, stream response
//	    UploadData    sdk.CallReqReaderRespBytes   // Stream request, JSON response
//	}
//
//	// Configure endpoints
//	configs := []sdk.CallConfig{
//	    {
//	        Calls:  []any{&client.CheckUpdates},
//	        Host:   "api.example.com",
//	        Name:   "check_updates",
//	        Path:   "/api/v1/updates/check",
//	        Method: sdk.CallMethodPOST,
//	    },
//	    {
//	        Calls:  []any{&client.DownloadFile},
//	        Host:   "files.example.com",
//	        Name:   "download_file",
//	        Path:   "/files/:id",
//	        Method: sdk.CallMethodGET,
//	    },
//	}
//
//	// Initialize SDK with options
//	err := sdk.Build(configs,
//	    sdk.WithClient("MyApp", "1.0.0"),
//	    sdk.WithLicenseKey("XXXX-XXXX-XXXX-XXXX"),
//	    sdk.WithPowTimeout(30*time.Second),
//	    sdk.WithMaxRetries(3),
//	)
//	if err != nil {
//	    return err
//	}
//
//	// Use generated functions
//	updateData := []byte(`{"version": "1.0.0"}`)
//	response, err := client.CheckUpdates(context.Background(), updateData)
//
// # Call Function Types
//
// The SDK provides 24 strongly-typed function patterns covering all request/response scenarios:
//
// ## Basic Patterns (No Parameters)
//   - CallReqRespBytes: Simple GET endpoints returning JSON/binary data
//   - CallReqRespReader: File downloads or large data streams
//   - CallReqRespWriter: Direct output streaming to custom writers
//
// ## Query Parameter Patterns
//   - CallReqQueryRespBytes: Filtered queries (?limit=10&offset=20)
//   - CallReqQueryRespReader: Query-based file downloads
//   - CallReqQueryRespWriter: Query-based streaming responses
//
// ## Path Argument Patterns
//   - CallReqWithArgsRespBytes: RESTful resource access (/users/:id)
//   - CallReqWithArgsRespReader: Resource-specific file downloads
//   - CallReqWithArgsRespWriter: Resource-specific streaming
//
// ## Combined Patterns
//   - CallReqQueryWithArgsRespBytes: Path args + query params
//   - CallReqQueryWithArgsRespReader: Complex resource queries with streaming
//   - CallReqQueryWithArgsRespWriter: Advanced query scenarios
//
// ## Request Body Patterns
//   - CallReqBytesRespBytes: JSON API calls (POST/PUT with JSON payload)
//   - CallReqBytesRespReader: JSON request with streaming response
//   - CallReqBytesRespWriter: JSON request with writer output
//   - CallReqReaderRespBytes: File uploads with JSON response
//   - CallReqReaderRespReader: Stream-to-stream processing
//   - CallReqReaderRespWriter: Upload streaming with output streaming
//
// ## Advanced Combined Patterns
//   - CallReqBytesWithArgsRespBytes: RESTful updates with JSON payloads
//   - CallReqBytesWithArgsRespReader: Resource updates with streaming responses
//   - CallReqBytesWithArgsRespWriter: Resource updates with output streaming
//   - CallReqReaderWithArgsRespBytes: File uploads to specific resources
//   - CallReqReaderWithArgsRespReader: Stream processing with resource targeting
//   - CallReqReaderWithArgsRespWriter: Complex stream processing scenarios
//
// Example usage patterns:
//
//	// Simple JSON API
//	type API struct {
//	    GetUser    sdk.CallReqWithArgsRespBytes      // GET /users/:id
//	    UpdateUser sdk.CallReqBytesWithArgsRespBytes // PUT /users/:id + JSON body
//	    ListUsers  sdk.CallReqQueryRespBytes         // GET /users?limit=10
//	    UploadFile sdk.CallReqReaderRespBytes        // POST /upload + file stream
//	}
//
// # Security Framework
//
// ## Proof-of-Work Protection
//
// All API calls require solving memory-hard proof-of-work challenges:
//
//	// Automatic PoW solving process:
//	// 1. Request challenge ticket from server
//	// 2. Solve memory-hard puzzle (12-1024KB, variable AES iterations)
//	// 3. Include PoW signature with every API request
//	// 4. Server validates signature before processing
//
// PoW Algorithm Features:
//   - Memory-hard algorithm designed for GPU and FPGA resistance
//   - Dynamic difficulty scaling based on server load and license tier
//   - Variable parameters prevent hardware optimization (millions of combinations)
//   - Configurable timeout support for different hardware capabilities
//
// ## Cryptographic Protection
//
// Multi-layer encryption and signature system:
//
//	// Session Key Generation
//	sessionKey := [16]byte{} // AES-128 for request/response encryption
//	sessionIV := [16]byte{}  // Unique IV per request
//
//	// NaCL Key Exchange
//	clientPublic, clientPrivate := box.GenerateKey(rand.Reader)
//	sharedKey := box.Precompute(serverPublic, clientPrivate)
//
//	// Request Encryption
//	encryptedBody := EncryptStream(requestBody, sessionKey, sessionIV)
//
//	// Response Decryption
//	decryptedResponse := DecryptStream(responseBody, sessionKey, sessionIV)
//
// Cryptographic Features:
//   - AES-GCM streaming encryption with 1KB configurable chunks
//   - NaCL (Curve25519) key exchange for session key protection
//   - Ed25519 signatures for data integrity verification
//   - Forward secrecy through daily server key rotation
//
// ## License System
//
// Enterprise license validation with cryptographic verification:
//
//	// License introspection
//	info, err := sdk.IntrospectLicenseKey("XXXX-XXXX-XXXX-XXXX")
//	if err != nil {
//	    return err
//	}
//
//	// License properties
//	switch info.Type {
//	case sdk.LicenseExpireable:
//	    fmt.Printf("License expires: %v", info.ExpiredAt)
//	case sdk.LicensePerpetual:
//	    fmt.Println("Perpetual license")
//	}
//
//	// Feature flags
//	for i, flag := range info.Flags {
//	    fmt.Printf("Feature %d: %v", i, flag)
//	}
//
// License Features:
//   - Base32 encoding with validation checksums
//   - Cryptographic verification prevents tampering
//   - Expiration time validation with day-aligned precision
//   - Feature flags for tier-based access control
//   - PBKDF2-based fingerprinting for license correlation
//
// # Streaming Architecture
//
// ## Encryption Streaming
//
// Memory-efficient encryption for large data transfers:
//
//	// Encrypt large files without memory accumulation
//	file, err := os.Open("large-file.dat")
//	if err != nil {
//	    return err
//	}
//	defer file.Close()
//
//	// Create streaming encryptor
//	encryptedStream, err := sdk.EncryptStream(file, sessionKey, sessionIV)
//	if err != nil {
//	    return err
//	}
//	defer encryptedStream.Close()
//
//	// Stream encrypted data to destination
//	_, err = io.Copy(destination, encryptedStream)
//
// ## Decryption Streaming
//
// Streaming decryption with authentication validation:
//
//	// Decrypt response stream directly to file
//	outputFile, err := os.Create("decrypted-output.dat")
//	if err != nil {
//	    return err
//	}
//	defer outputFile.Close()
//
//	// Use DecryptProxy for direct streaming
//	err = sdk.DecryptProxy(encryptedResponse, outputFile, sessionKey, sessionIV)
//	if err != nil {
//	    return fmt.Errorf("decryption failed: %w", err)
//	}
//
// Streaming Features:
//   - Configurable chunk sizes (default 16KB, max 1MB)
//   - Per-chunk authentication prevents tampering
//   - Random nonces ensure GCM security properties
//   - No memory accumulation regardless of data size
//
// # Transport Layer
//
// ## HTTP/2 Optimization
//
// Production-optimized transport configuration:
//
//	transport := sdk.DefaultTransport()
//
//	// Customize for specific requirements
//	transport.MaxConnsPerHost = 500
//	transport.ResponseHeaderTimeout = 5 * time.Minute
//
//	err := sdk.Build(configs, sdk.WithTransport(transport))
//
// Transport Features:
//   - HTTP/2 with automatic protocol negotiation
//   - Connection pooling with configurable limits
//   - TLS 1.2+ with certificate validation
//   - Proxy support with environment variable detection
//
// ## Request Processing
//
// Complete request lifecycle with automatic security:
//
//	// SDK automatically handles:
//	// 1. PoW ticket acquisition
//	// 2. Challenge solving with configurable timeout
//	// 3. Request encryption and signing
//	// 4. Response decryption and validation
//	// 5. Error handling and retry logic
//
// Processing Features:
//   - Automatic retry logic for temporary errors
//   - Exponential backoff with server-provided timing
//   - Context cancellation support throughout
//   - Comprehensive error classification and handling
//
// # Error Handling
//
// ## Error Classification
//
// Structured error handling with automatic retry logic:
//
//	data, err := api.SomeCall(ctx, requestData)
//	if err != nil {
//	    switch {
//	    case errors.Is(err, sdk.ErrTooManyRequestsRPM):
//	        // Temporary: Will be retried automatically with server timing
//	        log.Info("Rate limited, retrying with backoff")
//
//	    case errors.Is(err, sdk.ErrForbidden):
//	        // Fatal: Check license validity or authentication
//	        log.Error("Access denied - verify license key")
//
//	    case errors.Is(err, sdk.ErrExperimentTimeout):
//	        // Temporary: Increase PoW timeout for slower systems
//	        log.Warn("PoW timeout - consider increasing timeout")
//
//	    default:
//	        log.Error("Unexpected error:", err)
//	    }
//	}
//
// ## Error Types
//
// Temporary Errors (automatically retried):
//   - ErrBadGateway: Server maintenance or overload
//   - ErrServerInternal: Temporary server issues
//   - ErrTooManyRequests: Standard rate limiting
//   - ErrTooManyRequestsRPM: Rate limiting with server-provided backoff
//   - ErrExperimentTimeout: PoW solving timeout (increase timeout or retry)
//
// Fatal Errors (no retry):
//   - ErrBadRequest: Invalid request format or parameters
//   - ErrForbidden: Invalid license or insufficient permissions
//   - ErrNotFound: Unknown endpoint or resource
//   - ErrTooManyRequestsRPH/RPD: Long-term rate limits exceeded
//   - ErrInvalidSignature: Cryptographic validation failure
//   - ErrReplayAttack: Security violation detected
//
// # Logging Integration
//
// ## Structured Logging
//
// Built-in logging framework with multiple adapters:
//
//	import "github.com/sirupsen/logrus"
//
//	// Use default logger
//	logger := sdk.DefaultLogger()
//	logger.SetLevel(sdk.LevelDebug)
//
//	// Or wrap existing logrus instance
//	logrusLogger := logrus.New()
//	logrusLogger.SetLevel(logrus.InfoLevel)
//	wrappedLogger := sdk.WrapLogrus(logrusLogger)
//
//	// Configure SDK with logger
//	err := sdk.Build(configs, sdk.WithLogger(wrappedLogger))
//
// ## Custom Logger Integration
//
// Implement Logger interface for custom logging backends:
//
//	type CustomLogger struct {
//	    // Your logging implementation
//	}
//
//	func (l *CustomLogger) SetLevel(level sdk.Level) { /* ... */ }
//	func (l *CustomLogger) GetLevel() sdk.Level { /* ... */ }
//	func (l *CustomLogger) WithError(err error) sdk.Entry { /* ... */ }
//	func (l *CustomLogger) WithField(key string, value any) sdk.Entry { /* ... */ }
//	// ... implement all Logger interface methods
//
// Logging Features:
//   - Contextual logging with fields and errors
//   - Configurable log levels (Trace, Debug, Info, Warn, Error, Fatal, Panic)
//   - Request tracing with timing and retry information
//   - Cryptographic operation logging for security auditing
//
// # Advanced Configuration
//
// ## Option Pattern
//
// Flexible SDK configuration using functional options:
//
//	err := sdk.Build(configs,
//	    // Required: Client identification
//	    sdk.WithClient("MySecurityTool", "2.1.0"),
//
//	    // Optional: License for premium features
//	    sdk.WithLicenseKey("XXXX-XXXX-XXXX-XXXX"),
//
//	    // Optional: Performance tuning
//	    sdk.WithPowTimeout(60*time.Second),    // For slower systems
//	    sdk.WithMaxRetries(5),                 // For unreliable networks
//
//	    // Optional: Custom transport
//	    sdk.WithTransport(customTransport),
//
//	    // Optional: Structured logging
//	    sdk.WithLogger(customLogger),
//
//	    // Optional: Installation tracking
//	    sdk.WithInstallationID(installationUUID),
//	)
//
// ## Transport Customization
//
// Advanced HTTP transport configuration:
//
//	transport := sdk.DefaultTransport()
//
//	// Corporate proxy configuration
//	proxyURL, _ := url.Parse("http://proxy.company.com:8080")
//	transport.Proxy = http.ProxyURL(proxyURL)
//
//	// Custom TLS configuration
//	transport.TLSClientConfig = &tls.Config{
//	    MinVersion: tls.VersionTLS12,
//	    // Add custom certificate validation
//	}
//
//	// Performance tuning
//	transport.MaxConnsPerHost = 500
//	transport.ResponseHeaderTimeout = 5 * time.Minute
//
//	err := sdk.Build(configs, sdk.WithTransport(transport))
//
// # Path Templates
//
// ## RESTful Resource Patterns
//
// Automatic path argument substitution for RESTful APIs:
//
//	// Configure endpoint with path arguments
//	{
//	    Calls:  []any{&client.GetUserPosts},
//	    Path:   "/users/:userId/posts/:postId",  // Path template
//	    Method: sdk.CallMethodGET,
//	}
//
//	// Generated function signature includes args parameter
//	posts, err := client.GetUserPosts(ctx, []string{"123", "456"})
//	// Generates: GET /users/123/posts/456
//
// ## Query Parameter Generation
//
// Automatic query string generation from Go models:
//
//	type QueryParams struct {
//	    Limit  int    `url:"limit"`
//	    Offset int    `url:"offset"`
//	    Filter string `url:"filter"`
//	}
//
//	params := QueryParams{Limit: 10, Offset: 20, Filter: "active"}
//
//	// Convert to query map for SDK
//	queryMap := map[string]string{
//	    "limit":  "10",
//	    "offset": "20",
//	    "filter": "active",
//	}
//
//	results, err := client.SearchItems(ctx, queryMap)
//	// Generates: GET /search?limit=10&offset=20&filter=active
//
// # Performance Optimization
//
// ## Connection Management
//
// Optimized connection pooling and reuse:
//
//	// Default settings optimized for production
//	transport := sdk.DefaultTransport()
//	// MaxIdleConns: 50 (total idle connections)
//	// MaxIdleConnsPerHost: 10 (per-host idle connections)
//	// MaxConnsPerHost: 300 (max active connections per host)
//	// IdleConnTimeout: 90s (idle connection lifetime)
//
// ## Streaming Performance
//
// Memory-efficient processing for large data:
//
//	// Upload large file without loading into memory
//	file, err := os.Open("large-dataset.json")
//	if err != nil {
//	    return err
//	}
//	defer file.Close()
//
//	stat, _ := file.Stat()
//	response, err := client.ProcessLargeData(ctx, file, stat.Size())
//
//	// Download large response directly to file
//	outputFile, err := os.Create("processed-result.json")
//	if err != nil {
//	    return err
//	}
//	defer outputFile.Close()
//
//	err = client.GetLargeResult(ctx, queryParams, outputFile)
//
// # License Management
//
// ## License Validation
//
// Comprehensive license verification and introspection:
//
//	// Validate license before SDK initialization
//	licenseInfo, err := sdk.IntrospectLicenseKey("XXXX-XXXX-XXXX-XXXX")
//	if err != nil {
//	    return fmt.Errorf("invalid license: %w", err)
//	}
//
//	if !licenseInfo.IsValid() {
//	    return fmt.Errorf("license is invalid or expired")
//	}
//
//	// Check license type and permissions
//	switch licenseInfo.Type {
//	case sdk.LicenseExpireable:
//	    if licenseInfo.IsExpired() {
//	        return fmt.Errorf("license expired on %v", licenseInfo.ExpiredAt)
//	    }
//	    fmt.Printf("License valid until %v", licenseInfo.ExpiredAt)
//
//	case sdk.LicensePerpetual:
//	    fmt.Println("Perpetual license - no expiration")
//	}
//
//	// Feature flag checking
//	if licenseInfo.Flags[0] {
//	    fmt.Println("Premium feature enabled")
//	}
//
// ## License Encoding
//
// Base32 encoding with multiple validation layers:
//
//	// License key format: XXXX-XXXX-XXXX-XXXX
//
// # Production Deployment
//
// ## Configuration Best Practices
//
// Recommended production configuration:
//
//	// Production-ready SDK setup
//	configs := []sdk.CallConfig{
//	    // ... your API endpoints
//	}
//
//	err := sdk.Build(configs,
//	    // Required: Application identification
//	    sdk.WithClient("YourApp", appVersion),
//
//	    // Recommended: License for premium features
//	    sdk.WithLicenseKey(os.Getenv("VXCONTROL_LICENSE")),
//
//	    // Performance: Adjust for your hardware
//	    sdk.WithPowTimeout(45*time.Second),
//	    sdk.WithMaxRetries(5),
//
//	    // Monitoring: Production logging
//	    sdk.WithLogger(productionLogger),
//
//	    // Identity: Stable installation tracking
//	    sdk.WithInstallationID(persistentInstallationID),
//	)
//
// ## Monitoring Integration
//
// SDK provides comprehensive metrics for monitoring:
//
//	// Logger captures:
//	// - Request timing and retry information
//	// - PoW solving performance and difficulty
//	// - Cryptographic operation success/failure
//	// - Network errors and recovery attempts
//	// - License validation and tier information
//
// ## Error Recovery
//
// Robust error handling for production environments:
//
//	// Automatic recovery scenarios:
//	// - Network timeouts: Automatic retry with exponential backoff
//	// - Rate limiting: Server-provided backoff timing respected
//	// - PoW timeouts: Configurable timeout with retry support
//	// - Server overload: Automatic retry with jittered delays
//	// - License issues: Clear error messages for resolution
//
// # Thread Safety
//
// All SDK operations are thread-safe and optimized for concurrent usage:
//
//	// Single SDK instance can handle concurrent requests
//	var client Client
//	sdk.Build(configs, options...)
//
//	// Safe concurrent API calls
//	go func() {
//	    client.CheckUpdates(ctx1, data1)
//	}()
//	go func() {
//	    client.ReportError(ctx2, data2)
//	}()
//
// Concurrency Features:
//   - Thread-safe connection pooling
//   - Concurrent PoW solving (one per request)
//   - Shared session key generation
//   - Atomic retry counters and statistics
//
// Thread Safety Implementation:
//   - Immutable configuration after Build()
//   - Per-request context isolation
//   - Lock-free hot paths for performance
//   - Safe concurrent access to shared resources
package sdk