Waldemar
1e48e1b059
- Add comprehensive YAML configuration types for EdgeConnectConfig - Implement robust parser with validation and path resolution - Support both k8sApp and dockerApp configurations - Add comprehensive test coverage with real example parsing - Create validation for infrastructure uniqueness and port ranges - Generate instance names following pattern: appName-appVersion-instance 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
217 lines
9.8 KiB
Markdown
217 lines
9.8 KiB
Markdown
# EdgeXR Master Controller Go SDK - Implementation Plan
|
|
|
|
## Project Overview
|
|
|
|
Develop a comprehensive Go SDK for the EdgeXR Master Controller API. The SDK will provide typed, idiomatic Go interfaces for app lifecycle management, cloudlet orchestration, and edge deployment workflows.
|
|
|
|
## Technology Stack
|
|
|
|
- **Code Generation**: oapi-codegen for swagger-to-Go type generation
|
|
- **HTTP Client**: go-retryablehttp for robust networking with retry/backoff
|
|
- **CLI Framework**: Cobra + Viper (extending existing CLI)
|
|
- **Authentication**: Static Bearer token provider (MVP)
|
|
- **Testing**: testify + httptest for comprehensive testing
|
|
- **Tooling**: golangci-lint, standard Go toolchain
|
|
|
|
## Implementation Phases
|
|
|
|
### Phase 1: Foundation & Code Generation (Week 1)
|
|
|
|
#### 1.1 Project Structure Setup
|
|
- Add `/sdk` directory to existing edge-connect-client project
|
|
- Create subdirectories: `/sdk/edgeconnect`, `/sdk/internal/http`, `/sdk/examples`
|
|
- Update go.mod with dependencies: go-retryablehttp, testify
|
|
- Set up code generation tooling and make targets
|
|
|
|
#### 1.2 Code Generation Setup (skipped, oapi-codegen is unused )
|
|
- Install and configure oapi-codegen
|
|
- Create generation configuration targeting key swagger definitions
|
|
- Set up automated generation pipeline in Makefile/scripts
|
|
|
|
#### 1.3 Generate Core Types (skipped, oapi-codegen is unused )
|
|
- Generate Go types from swagger: RegionApp, RegionAppInst, RegionCloudlet
|
|
- Generate GPU driver types: RegionGPUDriver, GPUDriverBuildMember
|
|
- Create sdk/client/types.go with generated + manually curated types
|
|
- Add JSON tags and validation as needed
|
|
|
|
#### 1.4 Core Client Infrastructure
|
|
- Implement Client struct extending existing client patterns from prototype
|
|
- Create AuthProvider interface with StaticTokenProvider implementation
|
|
- Add configuration options pattern (WithHTTPClient, WithAuth, WithRetry)
|
|
- Implement NewClient() constructor with sensible defaults
|
|
|
|
#### 1.5 Basic HTTP Transport
|
|
- Create internal/http package with retryable HTTP client wrapper
|
|
- Implement context-aware request building and execution
|
|
- Add basic error wrapping for HTTP failures
|
|
- Create generic call[T]() function similar to existing prototype
|
|
|
|
### Phase 2: Core API Implementation (Week 2)
|
|
|
|
#### 2.1 App Management APIs
|
|
- Implement CreateApp() mapping to POST /auth/ctrl/CreateApp
|
|
- Add input validation and structured error handling
|
|
- Create unit tests with httptest mock server
|
|
- Document API mapping to swagger endpoints
|
|
|
|
#### 2.2 App Query and Lifecycle APIs
|
|
- Implement ShowApp() and ShowApps() mapping to POST /auth/ctrl/ShowApp
|
|
- Implement DeleteApp() mapping to POST /auth/ctrl/DeleteApp
|
|
- Add filtering and pagination support where applicable
|
|
- Create comprehensive unit test coverage
|
|
|
|
#### 2.3 AppInstance Creation APIs
|
|
- Implement CreateAppInst() mapping to POST /auth/ctrl/CreateAppInst
|
|
- Handle complex nested structures (AppKey, CloudletKey, Flavor)
|
|
- Add validation for required fields and relationships
|
|
- Test with realistic app instance configurations
|
|
|
|
#### 2.4 AppInstance Management APIs
|
|
- Implement ShowAppInst()/ShowAppInstances() for querying instances
|
|
- Implement RefreshAppInst() mapping to POST /auth/ctrl/RefreshAppInst
|
|
- Implement DeleteAppInst() mapping to POST /auth/ctrl/DeleteAppInst
|
|
- Add state management and status tracking
|
|
|
|
#### 2.5 HTTP Reliability - Basic Features
|
|
- Integrate go-retryablehttp with configurable retry policies
|
|
- Add exponential backoff with jitter for transient failures
|
|
- Implement context timeout and cancellation propagation
|
|
- Add request/response debug logging hooks
|
|
|
|
#### 2.6 Testing Framework
|
|
- Create comprehensive httptest-based mock server
|
|
- Write unit tests for all implemented API methods
|
|
- Test error conditions, timeouts, and retry behavior
|
|
- Add authentication provider unit tests
|
|
|
|
### Phase 3: Extended APIs & Reliability (Week 3)
|
|
|
|
#### 3.1 Cloudlet Management APIs
|
|
- Implement CreateCloudlet() and DeleteCloudlet() operations
|
|
- Add cloudlet state management and validation
|
|
- Create unit tests for cloudlet lifecycle operations
|
|
- Handle cloudlet-specific error conditions
|
|
|
|
#### 3.2 Cloudlet Resource APIs
|
|
- Implement GetCloudletManifest() mapping to POST /auth/ctrl/GetCloudletManifest
|
|
- Implement GetCloudletResourceUsage() mapping to POST /auth/ctrl/GetCloudletResourceUsage
|
|
- Add resource usage monitoring and reporting capabilities
|
|
- Test with various cloudlet configurations
|
|
|
|
#### 3.3 Enhanced Error Handling
|
|
- Create APIError struct with StatusCode, Code, Message, Body fields
|
|
- Map HTTP status codes to meaningful error types and constants
|
|
- Implement ErrResourceNotFound and other semantic error types
|
|
- Add error context with full request/response details for debugging
|
|
|
|
#### 3.4 Advanced Reliability Features
|
|
- Add retry policy configuration per operation type (idempotent vs stateful)
|
|
- Implement operation-specific timeout configurations
|
|
- Add circuit breaker hooks for optional client-side protection
|
|
- Create observability interfaces for metrics collection
|
|
|
|
#### 3.5 GPU Driver APIs (Optional Extension)
|
|
- Implement CreateGPUDriver() mapping to swagger GPU driver endpoints
|
|
- Implement GetGPUDriverBuildURL() for driver download workflows
|
|
- Add GPU driver lifecycle management
|
|
- Test GPU driver build and deployment scenarios
|
|
|
|
#### 3.6 Integration Testing
|
|
- Create integration test suite with configurable API endpoints
|
|
- Add environment-based test configuration (staging/prod endpoints)
|
|
- Test end-to-end workflows: app creation → instance deployment → cleanup
|
|
- Add performance benchmarks for critical API paths
|
|
|
|
### Phase 4: CLI Integration & Polish (Week 4)
|
|
|
|
#### 4.1 CLI Refactoring
|
|
- Refactor existing cmd/app.go to use new SDK instead of direct HTTP client
|
|
- Maintain full backward compatibility with existing CLI interface
|
|
- Update cmd/instance.go to leverage SDK's enhanced error handling
|
|
- Ensure configuration continuity (same config files, env vars, flags)
|
|
|
|
#### 4.2 New CLI Commands
|
|
- Add cloudlet management commands: `edge-connect cloudlet create/show/delete`
|
|
- Add cloudlet resource commands: `edge-connect cloudlet manifest/usage`
|
|
- Implement `edge-connect gpu` commands for GPU driver management
|
|
- Add batch operation commands for common deployment workflows
|
|
|
|
#### 4.3 Comprehensive Examples
|
|
- Write examples/deploy_app.go: complete app creation and deployment workflow
|
|
- Create examples/cloudlet_management.go: cloudlet lifecycle and monitoring
|
|
- Add examples/batch_operations.go: bulk app deployment and management
|
|
- Create examples/error_handling.go: demonstrating robust error handling patterns
|
|
|
|
#### 4.4 Documentation
|
|
- Write comprehensive README with API mapping to swagger endpoints
|
|
- Create godoc documentation for all public APIs and types
|
|
- Add migration guide from existing client patterns to new SDK
|
|
- Document authentication, configuration, and best practices
|
|
|
|
#### 4.5 Testing and Quality
|
|
- Add golangci-lint configuration and resolve all linting issues
|
|
- Achieve >90% test coverage across all packages
|
|
- Add integration test CI pipeline with test API endpoints
|
|
- Create performance regression test suite
|
|
|
|
#### 4.6 Release Preparation
|
|
- Add semantic versioning and release automation (goreleaser)
|
|
- Create changelog and release notes templates
|
|
- Add cross-platform build and distribution
|
|
- Performance optimization and memory usage analysis
|
|
|
|
## Acceptance Criteria
|
|
|
|
### MVP Completion
|
|
- [ ] SDK compiles and passes all tests with zero linter warnings
|
|
- [ ] Core APIs implemented: App and AppInstance full lifecycle management
|
|
- [ ] Authentication works with Bearer token against real MC endpoints
|
|
- [ ] CLI maintains backward compatibility while using new SDK internally
|
|
- [ ] Examples demonstrate real-world workflows with proper error handling
|
|
- [ ] Documentation maps SDK functions to swagger endpoints with citations
|
|
|
|
### Quality Gates
|
|
- [ ] >90% test coverage across sdk/client and sdk/internal packages
|
|
- [ ] Integration tests pass against staging MC environment
|
|
- [ ] Performance benchmarks show <500ms p95 for core operations
|
|
- [ ] Memory usage remains constant under load (no leaks)
|
|
- [ ] All examples run successfully and produce expected outputs
|
|
|
|
### Documentation Standards
|
|
- [ ] All public APIs have comprehensive godoc comments
|
|
- [ ] README includes quick start guide and common usage patterns
|
|
- [ ] Migration guide helps users transition from prototype client
|
|
- [ ] API mapping documentation references specific swagger endpoints
|
|
- [ ] Security and authentication best practices documented
|
|
|
|
## Risk Mitigation
|
|
|
|
### Technical Risks
|
|
- **Swagger spec changes**: Pin to specific swagger version, add change detection
|
|
- **API authentication changes**: Abstract auth via provider interface
|
|
- **Performance at scale**: Implement connection pooling and request batching
|
|
- **Breaking changes in dependencies**: Pin versions, gradual upgrade strategy
|
|
|
|
### Project Risks
|
|
- **Scope creep**: Focus on MVP core APIs first, defer advanced features to v1+
|
|
- **Integration complexity**: Maintain existing CLI behavior exactly during refactoring
|
|
- **Testing coverage gaps**: Prioritize integration tests for critical user workflows
|
|
- **Documentation debt**: Write docs incrementally during implementation, not after
|
|
|
|
## Success Metrics
|
|
|
|
- **Developer Adoption**: SDK reduces boilerplate code by >60% vs direct HTTP calls
|
|
- **Reliability**: <1% failure rate on retry-eligible operations under normal load
|
|
- **Performance**: API calls complete within 2x timeout of direct HTTP equivalent
|
|
- **Maintainability**: New API endpoints can be added with <4 hours effort
|
|
- **Documentation**: Developers can complete first integration within 30 minutes
|
|
|
|
## Next Steps
|
|
|
|
Upon approval of this plan:
|
|
1. Begin Phase 1.1 (Project Structure Setup)
|
|
2. Set up development environment with all required dependencies
|
|
3. Create initial PR with project structure and tooling setup
|
|
4. Begin iterative development following the phase breakdown above
|
|
|
|
This plan leverages the existing prototype's proven patterns while adding the robustness, typing, and extensibility needed for production SDK usage.
|