WIP - Feature/v2 initial modules rest client

README.md

@@ -1,21 +1,37 @@
 # <p align="center">Golang client for XenOrchestra API</p>
 
-This is a Golang module for the [XenOrchestra](https://github.com/vatesfr/xen-orchestra) JSON-RPC API.
+This is a Golang module for the [XenOrchestra](https://github.com/vatesfr/xen-orchestra) API. It provides two client implementations:
 
-It is used in the [terraform-provider-xenorchestra](https://github.com/vatesfr/terraform-provider-xenorchestra) Terraform provider.
+- **v1**: Uses the JSON-RPC API (legacy)
+- **v2**: Uses the REST API (WIP, should be used in parallel with v1 for missing endpoints, until v2 is fully released)
 
 ## 📚 Documentation 
 
-TODO
+### v1 Documentation
+
+The v1 client uses the JSON-RPC API and is primarily used in the [terraform-provider-xenorchestra](https://github.com/vatesfr/terraform-provider-xenorchestra) Terraform provider.
+
+### v2 Documentation
+
+The v2 client uses the REST API and provides a more modern, type-safe interface. Comprehensive documentation is available in the `docs/v2` directory:
+
+- [Overview](docs/v2/01-overview.md) - Introduction and key features
+- [Architecture](docs/v2/02-architecture.md) - Design patterns and components
+- [Migration Guide](docs/v2/03-migration-guide.md) - How to migrate from v1 to v2
+- [Service Implementation Guide](docs/v2/04-service-implementation.md) - How to add new services
 
 ## 🧑🏻‍💻 Usage
 
 ```shell
 go get github.com/vatesfr/xenorchestra-go-sdk
 ```
 
-See [examples](https://github.com/vatesfr/xenorchestra-go-sdk/tree/main/examples).
+### Examples
+
+The SDK includes examples for both v1 and v2 clients:
 
+- [v1 Examples](examples/v1) - Examples using the JSON-RPC API
+- [v2 Examples](examples/v2) - Examples using the REST API
 
 ## 🍰 Contributing    
 

docs/v2/01-overview.md

@@ -0,0 +1,85 @@
+# Xen Orchestra Go SDK v2
+
+## Overview
+
+The Xen Orchestra Go SDK v2 provides a modern, type-safe interface to interact with the Xen Orchestra API. This version moves from the JSON-RPC API used in v1 to a REST API implementation, offering significant improvements in usability, maintainability, and type safety.
+
+## Key Features
+
+- **REST API Support**: Uses Xen Orchestra's modern REST API
+- **Type Safety**: Leverages Go generics for type-safe API interactions
+- **Method Chaining**: Improved API ergonomics with `client.VM().Create()` pattern
+- **Context Support**: All operations support context for better timeout and cancellation handling
+- **UUID Support**: Native UUID type support instead of string IDs
+- **Structured Logging**: Built-in logging with configurable verbosity levels
+- **Interface-Based Design**: Clean interfaces for better testability and mocking
+- **Go Mocking**: Mocking is supported for all interfaces by adding the `//go:generate mockgen` tag in the interface file
+
+## Installation
+
+```bash
+go get github.com/vatesfr/xenorchestra-go-sdk/v2
+```
+
+## Quick Start
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "time"
+
+    "github.com/vatesfr/xenorchestra-go-sdk/pkg/config"
+    v2 "github.com/vatesfr/xenorchestra-go-sdk/v2"
+)
+
+func main() {
+    // Create a context with timeout
+    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+    defer cancel()
+
+    // Initialize configuration
+    cfg, err := config.New()
+    if err != nil {
+        panic(err)
+    }
+
+    // Create client
+    client, err := v2.New(cfg)
+    if err != nil {
+        panic(err)
+    }
+
+    // List all VMs
+    vms, err := client.VM().List(ctx)
+    if err != nil {
+        panic(err)
+    }
+
+    // Display VMs
+    fmt.Printf("Found %d VMs\n", len(vms))
+    for i, vm := range vms {
+        fmt.Printf("%d. %s (ID: %s, Power: %s)\n", i+1, vm.NameLabel, vm.ID, vm.PowerState)
+    }
+}
+```
+
+## Environment Variables
+
+The SDK uses the following environment variables for configuration:
+
+- `XOA_URL`: URL of the Xen Orchestra server
+- `XOA_USER`: Username for authentication
+- `XOA_PASSWORD`: Password for authentication
+- `XOA_INSECURE`: Set to "true" to skip TLS certificate verification
+- `XOA_DEVELOPMENT`: Set to "true" to enable development mode with additional logging
+- `XOA_RETRY_MODE`: Retry strategy ("none" or "backoff")
+- `XOA_RETRY_MAX_TIME`: Maximum time to wait between retries (default: 5 minutes)
+
+## Next Steps
+
+- [Architecture Guide](02-architecture.md) - Learn about the design patterns used in the SDK
+- [Migration Guide](03-migration-guide.md) - Migrate from v1 to v2
+- [Service Implementation Guide](04-service-implementation.md) - Learn how to add new services

docs/v2/02-architecture.md

@@ -0,0 +1,213 @@
+# Architecture Guide
+
+The v2 SDK uses a clean, interface-based architecture that makes it easy to use, test, and extend. This document explains the key architectural components.
+
+## Component Overview
+
+
+The SDK consists of these main components:
+
+```
+v2/
+├── client/ # HTTP client implementation
+├── xo.go # Main client entry point
+pkg/
+├── config/ # Configuration handling
+├── payloads/ # API data structures
+├── services/ # Service implementations
+├── library/ # Service interfaces
+├── vm/ # VM service implementation
+└── ... # Other service implementations
+internal/
+└── common/ # Shared utilities
+├── core/ # Core types and constants
+└── logger/ # Logging implementation
+```
+
+
+## Key Design Patterns
+
+### Interface-Based Design
+
+The SDK uses interfaces to define service contracts in the `library` package. These interfaces define the operations available for each resource type.
+
+Example from `library/vm.go`:
+
+```go
+type VM interface {
+    GetByID(ctx context.Context, id uuid.UUID) (*payloads.VM, error)
+    List(ctx context.Context) ([]*payloads.VM, error)
+    Create(ctx context.Context, vm *payloads.VM) (*payloads.VM, error)
+    // ... other methods
+}
+```
+
+This approach allows for:
+- Clear API documentation
+- Easy mocking for tests
+- Swappable implementations
+
+### Service Registry Pattern
+
+The `XOClient` struct acts as a registry for service implementations, providing a coherent API for accessing different services:
+
+```go
+// In v2/xo.go
+type XOClient struct {
+    vmService library.VM
+    // other services will be added here
+}
+
+func (c *XOClient) VM() library.VM {
+    return c.vmService
+}
+```
+
+This allows for method chaining like `client.VM().Create(...)`.
+
+### Generic HTTP Methods
+
+The client package uses Go generics to provide type-safe HTTP methods:
+
+```go
+// In client/client.go
+func TypedGet[P any, R any](ctx context.Context, c *Client, endpoint string, params P, result *R) error {
+    // implementation
+}
+```
+
+This makes service implementations cleaner and more type-safe.
+
+### Payload Structs
+
+API data structures are defined in the `payloads` package, separate from service logic:
+
+```go
+// In pkg/payloads/vm.go
+type VM struct {
+    ID              uuid.UUID         `json:"id,omitempty"`
+    NameLabel       string            `json:"name_label"`
+    NameDescription string            `json:"name_description"`
+    // ... other fields
+}
+```
+
+## Client Initialization Flow
+
+1. Configuration is loaded from environment variables or provided directly
+2. The HTTP client is created with the appropriate authentication
+3. Service implementations are initialized
+4. The main client registers all services
+5. The client is ready to use
+
+## Async Operations
+
+Some API operations (like VM creation) are asynchronous. The SDK handles this by:
+
+1. Making the initial request that returns a task URL
+2. Polling the task status until completion
+3. Retrieving the final result when the task succeeds
+
+This is encapsulated in service methods for a clean API.
+
+## Error Handling
+
+Errors are propagated from the HTTP client to the service methods and finally to the caller. Detailed error information is available to help diagnose issues.
+
+## Logging
+
+The SDK uses a structured logger based on zap for efficient and informative logging. Log levels are automatically adjusted based on whether the SDK is in development or production mode.
+
+
+## Key Design Patterns
+
+### Interface-Based Design
+
+The SDK uses interfaces to define service contracts in the `library` package. These interfaces define the operations available for each resource type.
+
+Example from `library/vm.go`:
+
+```go
+type VM interface {
+    GetByID(ctx context.Context, id uuid.UUID) (*payloads.VM, error)
+    List(ctx context.Context) ([]*payloads.VM, error)
+    Create(ctx context.Context, vm *payloads.VM) (*payloads.VM, error)
+    // ... other methods
+}
+```
+
+This approach allows for:
+- Clear API documentation
+- Easy mocking for tests
+- Swappable implementations
+
+### Service Registry Pattern
+
+The `XOClient` struct acts as a registry for service implementations, providing a coherent API for accessing different services:
+
+```go
+// In v2/xo.go
+type XOClient struct {
+    vmService library.VM
+    // other services will be added here
+}
+
+func (c *XOClient) VM() library.VM {
+    return c.vmService
+}
+```
+
+This allows for method chaining like `client.VM().Create(...)`.
+
+### Generic HTTP Methods
+
+The client package uses Go generics to provide type-safe HTTP methods:
+
+```go
+// In client/client.go
+func TypedGet[P any, R any](ctx context.Context, c *Client, endpoint string, params P, result *R) error {
+    // implementation
+}
+```
+
+This makes service implementations cleaner and more type-safe.
+
+### Payload Structs
+
+API data structures are defined in the `payloads` package, separate from service logic:
+
+```go
+// In pkg/payloads/vm.go
+type VM struct {
+    ID              uuid.UUID         `json:"id,omitempty"`
+    NameLabel       string            `json:"name_label"`
+    NameDescription string            `json:"name_description"`
+    // ... other fields
+}
+```
+
+## Client Initialization Flow
+
+1. Configuration is loaded from environment variables or provided directly
+2. The HTTP client is created with the appropriate authentication
+3. Service implementations are initialized
+4. The main client registers all services
+5. The client is ready to use
+
+## Async Operations
+
+Some API operations (like VM creation) are asynchronous. The SDK handles this by:
+
+1. Making the initial request that returns a task URL
+2. Polling the task status until completion
+3. Retrieving the final result when the task succeeds
+
+This is encapsulated in service methods for a clean API.
+
+## Error Handling
+
+Errors are propagated from the HTTP client to the service methods and finally to the caller. Detailed error information is available to help diagnose issues.
+
+## Logging
+
+The SDK uses a structured logger based on zap for efficient and informative logging. Log levels are automatically adjusted based on whether the SDK is in development or production mode.