Merge pull request #11 from vatesfr/feature/v2-initial-modules-rest-client

Author: iButcat

.github/workflows/lint.yml

@@ -23,11 +23,11 @@ jobs:
       uses: actions/setup-go@v5
       with:
         # The versions of golangci-lint and setup-go here cross-depend and need to update together.
-        go-version: '1.23'
+        go-version: '1.24'
         # Either this action or golangci-lint needs to disable the cache
         cache: false
     - run: go mod tidy
     - name: golangci-lint
       uses: golangci/golangci-lint-action@v6
       with:
-        version: v1.63.2
+        version: v1.64.7

.gitignore

@@ -39,3 +39,6 @@ dist/
 .env
 .envrc
 .autoenv.zsh
+
+# goenv version file
+.go-version

.golangci.yml

@@ -22,3 +22,4 @@ linters-settings:
       - structtag
 run:
   timeout: 20m
+  go: '1.24'

Makefile

@@ -1,68 +1,92 @@
-SHELL := /bin/bash
+PROJECT_NAME := xenorchestra-go-sdk
+GO := go
+GOFLAGS :=
+MOCKGEN_VERSION := 1.6.0
 
-.DEFAULT_GOAL := all
-.PHONY: all
-all: ## build pipeline
-all: mod gen spell lint test
-
-.PHONY: precommit
-precommit: ## validate the branch before commit
-precommit: all vuln
+# Colors
+BLUE := \033[0;34m
+GREEN := \033[0;32m
+YELLOW := \033[0;33m
+RED := \033[0;31m
+NC := \033[0m # No Color
 
-.PHONY: ci
-ci: ## CI build pipeline
-ci: precommit diff
+.PHONY: all
+all: mod test lint
 
 .PHONY: help
 help:
-	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
-
-.PHONY: clean
-clean: ## remove files created during build pipeline
-	$(call print-target)
-	rm -rf dist
-	rm -f coverage.*
-	rm -f '"$(shell go env GOCACHE)/../golangci-lint"'
-	go clean -i -cache -testcache -modcache -fuzzcache -x
+	@echo "$(BLUE)Makefile for $(PROJECT_NAME)$(NC)"
+	@echo ""
+	@echo "$(YELLOW)Usage:$(NC)"
+	@echo "  make $(GREEN)<target>$(NC)"
+	@echo ""
+	@echo "$(YELLOW)Targets:$(NC)"
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  $(GREEN)%-15s$(NC) %s\n", $$1, $$2}'
 
 .PHONY: mod
-mod: ## go mod tidy
-	$(call print-target)
-	go mod tidy
+mod: 
+	@echo "$(BLUE)Running go mod tidy...$(NC)"
+	$(GO) mod tidy
+
+.PHONY: test
+test:
+	@echo "$(BLUE)Running tests...$(NC)"
+	$(GO) test -race -covermode=atomic -coverprofile=coverage.out ./...
+	$(GO) tool cover -html=coverage.out -o coverage.html
+	@echo "$(GREEN)Coverage report generated at coverage.html$(NC)"
 
-.PHONY: gen
-gen: ## go generate
-	$(call print-target)
-	go generate ./...
+.PHONY: test-v1
+test-v1: 
+	@echo "$(BLUE)Running v1 client tests...$(NC)"
+	$(GO) test -race ./client/...
 
-.PHONY: spell
-spell: ## misspell
-	$(call print-target)
-	misspell -error -locale=US -w **.md
+.PHONY: test-v2
+test-v2: 
+	@echo "$(BLUE)Running v2 client tests...$(NC)"
+	$(GO) test -race ./v2/... ./pkg/... ./internal/...
 
 .PHONY: lint
-lint: ## golangci-lint
-	$(call print-target)
+lint: 
+	@echo "$(BLUE)Running linter...$(NC)"
 	golangci-lint run
 
-.PHONY: vuln
-vuln: ## govulncheck
-	$(call print-target)
-	govulncheck ./...
+.PHONY: install-mockgen
+install-mockgen: 
+	@echo "$(BLUE)Installing mockgen v$(MOCKGEN_VERSION)...$(NC)"
+	$(GO) install github.com/golang/mock/mockgen@v$(MOCKGEN_VERSION)
 
-.PHONY: test
-test: ## go test
-	$(call print-target)
-	go test -race -covermode=atomic -coverprofile=coverage.out -coverpkg=./... ./...
-	go tool cover -html=coverage.out -o coverage.html
+.PHONY: mock
+mock: install-mockgen 
+	@echo "$(BLUE)Generating mocks...$(NC)"
+	$(GO) generate ./...
+
+.PHONY: run-example-v1
+run-example-v1: 
+	@echo "$(BLUE)Running v1 example...$(NC)"
+	$(GO) run ./examples/v1/user_demo.go
 
-.PHONY: diff
-diff: ## git diff
-	$(call print-target)
-	git diff --exit-code
-	RES=$$(git status --porcelain) ; if [ -n "$$RES" ]; then echo $$RES && exit 1 ; fi
+.PHONY: run-example-v2
+run-example-v2: 
+	@echo "$(BLUE)Running v2 example...$(NC)"
+	$(GO) run ./examples/v2/user_demo.go
 
+.PHONY: run-examples
+run-examples: run-example-v1 run-example-v2 
+	@echo "$(GREEN)All examples executed successfully$(NC)"
+
+.PHONY: clean
+clean: 
+	@echo "$(BLUE)Cleaning build artifacts...$(NC)"
+	rm -f coverage.out coverage.html
+	$(GO) clean -cache -testcache
 
-define print-target
-    @printf "Executing target: \033[36m$@\033[0m\n"
-endef
+.PHONY: vuln
+vuln: 
+	@echo "$(BLUE)Checking for vulnerabilities...$(NC)"
+	govulncheck ./...
+
+.PHONY: precommit
+precommit: 
+	@echo "$(BLUE)Running pre-commit checks...$(NC)"
+	pre-commit run --all-files
+	@echo "$(GREEN)Pre-commit checks passed!$(NC)"

README.md

@@ -1,26 +1,68 @@
 # <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    
 
 Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are **greatly appreciated**.
 
+### Development
+
+This project includes a Makefile to help with common development tasks:
+
+```shell
+# Run tests
+make test
+
+# Run specific client tests
+make test-v1
+make test-v2
+
+# Run linter
+make lint
+
+# Generate mocks
+make mock
+
+# Run examples
+make example-v1
+make example-v2
+
+# See all available commands
+make help
+```
+
 ## License
 
 MIT License

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