edge-connect-client/plan.md

# 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.