# EdgeXR Master Controller Go SDK

A comprehensive Go SDK for the EdgeXR Master Controller API, providing typed interfaces for edge application lifecycle management, cloudlet orchestration, and instance deployment workflows.

## Features

- **🔐 Dual Authentication**: Static Bearer tokens and username/password with token caching
- **📡 Resilient HTTP**: Built-in retry logic, exponential backoff, and context support
- **⚡ Type Safety**: Full type definitions based on EdgeXR API specifications
- **🧪 Comprehensive Testing**: Unit tests with mock servers and error condition coverage
- **📊 Streaming Responses**: Support for EdgeXR's streaming JSON response format
- **🔧 CLI Integration**: Drop-in replacement for existing edge-connect CLI

## Quick Start

### Installation

```go
import v2 "edp.buildth.ing/DevFW-CICD/edge-connect-client/v2/sdk/edgeconnect/v2"
```

### Authentication

```go
// Username/password (recommended)
client := v2.NewClientWithCredentials(baseURL, username, password)

// Static Bearer token
client := v2.NewClient(baseURL,
    v2.WithAuthProvider(v2.NewStaticTokenProvider(token)))
```

### Basic Usage

```go
ctx := context.Background()

// Create an application
app := &v2.NewAppInput{
    Region: "us-west",
    App: v2.App{
        Key: v2.AppKey{
            Organization: "myorg",
            Name:         "my-app",
            Version:      "1.0.0",
        },
        Deployment: "kubernetes",
        ImagePath:  "nginx:latest",
    },
}

if err := v2.CreateApp(ctx, app); err != nil {
    log.Fatal(err)
}

// Deploy an application instance
instance := &v2.NewAppInstanceInput{
    Region: "us-west",
    AppInst: v2.AppInstance{
        Key: v2.AppInstanceKey{
            Organization: "myorg",
            Name:         "my-instance",
            CloudletKey: v2.CloudletKey{
                Organization: "cloudlet-provider",
                Name:         "edge-cloudlet",
            },
        },
        AppKey: app.App.Key,
        Flavor: v2.Flavor{Name: "m4.small"},
    },
}

if err := v2.CreateAppInstance(ctx, instance); err != nil {
    log.Fatal(err)
}
```

## API Coverage

### Application Management
- `CreateApp()` → `POST /auth/ctrl/CreateApp`
- `ShowApp()` → `POST /auth/ctrl/ShowApp`
- `ShowApps()` → `POST /auth/ctrl/ShowApp` (multi-result)
- `DeleteApp()` → `POST /auth/ctrl/DeleteApp`

### Application Instance Management
- `CreateAppInstance()` → `POST /auth/ctrl/CreateAppInst`
- `ShowAppInstance()` → `POST /auth/ctrl/ShowAppInst`
- `ShowAppInstances()` → `POST /auth/ctrl/ShowAppInst` (multi-result)
- `RefreshAppInstance()` → `POST /auth/ctrl/RefreshAppInst`
- `DeleteAppInstance()` → `POST /auth/ctrl/DeleteAppInst`

### Cloudlet Management
- `CreateCloudlet()` → `POST /auth/ctrl/CreateCloudlet`
- `ShowCloudlet()` → `POST /auth/ctrl/ShowCloudlet`
- `ShowCloudlets()` → `POST /auth/ctrl/ShowCloudlet` (multi-result)
- `DeleteCloudlet()` → `POST /auth/ctrl/DeleteCloudlet`
- `GetCloudletManifest()` → `POST /auth/ctrl/GetCloudletManifest`
- `GetCloudletResourceUsage()` → `POST /auth/ctrl/GetCloudletResourceUsage`

## Configuration Options

```go
client := v2.NewClient(baseURL,
    // Custom HTTP client with timeout
    v2.WithHTTPClient(&http.Client{Timeout: 30 * time.Second}),

    // Authentication provider
    v2.WithAuthProvider(v2.NewStaticTokenProvider(token)),

    // Retry configuration
    v2.WithRetryOptions(v2.RetryOptions{
        MaxRetries:   5,
        InitialDelay: 1 * time.Second,
        MaxDelay:     30 * time.Second,
    }),

    // Request logging
    v2.WithLogger(log.Default()),
)
```

## Examples

### Simple App Deployment
```bash
# Run basic example
EDGEXR_USERNAME=user EDGEXR_PASSWORD=pass go run sdk/examples/deploy_app.go
```

### Comprehensive Workflow
```bash
# Run full workflow demonstration
cd sdk/examples/comprehensive
EDGEXR_USERNAME=user EDGEXR_PASSWORD=pass go run main.go
```

## Authentication Methods

### Username/Password (Recommended)
Uses the existing `/api/v1/login` endpoint with automatic token caching:

```go
client := v2.NewClientWithCredentials(baseURL, username, password)
```

**Features:**
- Automatic token refresh on expiry
- Thread-safe token caching
- 1-hour default cache duration
- Matches existing client authentication exactly

### Static Bearer Token
For pre-obtained tokens:

```go
client := v2.NewClient(baseURL,
    v2.WithAuthProvider(v2.NewStaticTokenProvider(token)))
```

## Error Handling

```go
app, err := v2.ShowApp(ctx, appKey, region)
if err != nil {
    // Check for specific error types
    if errors.Is(err, v2.ErrResourceNotFound) {
        fmt.Println("App not found")
        return
    }

    // Check for API errors
    var apiErr *v2.APIError
    if errors.As(err, &apiErr) {
        fmt.Printf("API Error %d: %s\n", apiErr.StatusCode, apiErr.Messages[0])
        return
    }

    // Network or other errors
    fmt.Printf("Request failed: %v\n", err)
}
```

## Testing

```bash
# Run all SDK tests
go test ./sdk/client/ -v

# Run with coverage
go test ./sdk/client/ -v -coverprofile=coverage.out
go tool cover -html=coverage.out

# Run specific test suites
go test ./sdk/client/ -v -run TestApp
go test ./sdk/client/ -v -run TestAuth
go test ./sdk/client/ -v -run TestCloudlet
```

## CLI Integration

The existing `edge-connect` CLI has been updated to use the SDK internally while maintaining full backward compatibility:

```bash
# Same commands, enhanced reliability
edge-connect app create --org myorg --name myapp --version 1.0.0 --region us-west
edge-connect instance create --org myorg --name myinst --app myapp --version 1.0.0
```

## Migration from Existing Client

The SDK provides a drop-in replacement with enhanced features:

```go
// Old approach
oldClient := &v2.EdgeConnect{
    BaseURL: baseURL,
    Credentials: v2.Credentials{Username: user, Password: pass},
}

// New SDK approach
newClient := v2.NewClientWithCredentials(baseURL, user, pass)

// Same method calls, enhanced reliability
err := newClient.CreateApp(ctx, input)
```

## Performance

- **Token Caching**: Reduces login API calls by >90%
- **Connection Pooling**: Reuses HTTP connections efficiently
- **Context Support**: Proper timeout and cancellation handling
- **Retry Logic**: Automatic recovery from transient failures

## Contributing

### Project Structure
```
sdk/
├── client/          # Public SDK interfaces
├── internal/http/   # HTTP transport layer
├── examples/        # Usage demonstrations
└── README.md        # This file
```

### Development
```bash
# Install dependencies
go mod tidy

# Generate types (if swagger changes)
make generate

# Run tests
make test

# Build everything
make build
```

## License

This SDK follows the same license as the parent edge-connect-client project.