Cloud Connexa Go Client

The official Go client library for the Cloud Connexa API provides programmatic access to OpenVPN Cloud Connexa services.

Full CloudConnexa API v1.2.0 Support - Complete coverage of all public API endpoints with modern Go patterns.

Table of Contents

• Installation
• Quick Start
• Authentication
• Usage Examples
• API Coverage
• Configuration
• Testing
• Contributing
• Versioning
• License
• Support

Installation

Requires Go 1.25 or later.

go get github.com/openvpn/cloudconnexa-go-client/v2/cloudconnexa

Quick Start

package main

import (
    "fmt"
    "log"

    "github.com/openvpn/cloudconnexa-go-client/v2/cloudconnexa"
)

func main() {
    client, err := cloudconnexa.NewClient("https://myorg.api.openvpn.com", "client_id", "client_secret")
    if err != nil {
        log.Fatal(err)
    }

    // List networks
    networks, err := client.Networks.List()
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Found %d networks\n", len(networks))
}

Authentication

The client requires three parameters for authentication:

• api_url: Your organisation's API endpoint (e.g., https://myorg.api.openvpn.com)
• client_id: OAuth2 client ID
• client_secret: OAuth2 client secret

client, err := cloudconnexa.NewClient(apiURL, clientID, clientSecret)
if err != nil {
    return err
}

Usage Examples

Network Management

// Create a network
network := cloudconnexa.Network{
    Name:           "production-network",
    Description:    "Production environment network",
    InternetAccess: cloudconnexa.InternetAccessSplitTunnelOn,
    Egress:         true,
}

createdNetwork, err := client.Networks.Create(network)
if err != nil {
    log.Fatal(err)
}

// List networks with pagination
networks, pagination, err := client.Networks.GetByPage(1, 10)
if err != nil {
    log.Fatal(err)
}

// Update a network
updatedNetwork, err := client.Networks.Update(networkID, network)
if err != nil {
    log.Fatal(err)
}

// Delete a network
err = client.Networks.Delete(networkID)
if err != nil {
    log.Fatal(err)
}

User Management

// Create a user
user := cloudconnexa.User{
    Username:  "john.doe",
    Email:     "john.doe@company.com",
    FirstName: "John",
    LastName:  "Doe",
    GroupID:   "group-123",
}

createdUser, err := client.Users.Create(user)
if err != nil {
    log.Fatal(err)
}

// List users with filtering
users, err := client.Users.List("", "active")
if err != nil {
    log.Fatal(err)
}

// Get user by ID
user, err := client.Users.GetByID(userID)
if err != nil {
    log.Fatal(err)
}

Connector Management

// List connectors
connectors, err := client.Connectors.List()
if err != nil {
    log.Fatal(err)
}

// Create a connector
connector := cloudconnexa.Connector{
    Name:        "office-connector",
    Description: "Main office connector",
    NetworkID:   networkID,
}

createdConnector, err := client.Connectors.Create(connector)
if err != nil {
    log.Fatal(err)
}

Host Management

// List hosts
hosts, err := client.Hosts.List()
if err != nil {
    log.Fatal(err)
}

// Get host by ID
host, err := client.Hosts.GetByID(hostID)
if err != nil {
    log.Fatal(err)
}

DNS Records

// List DNS records
dnsRecords, err := client.DNSRecords.List()
if err != nil {
    log.Fatal(err)
}

// Create DNS record
record := cloudconnexa.DNSRecord{
    Domain:      "api.internal.company.com",
    Description: "Internal API endpoint",
    IPAddress:   "10.0.1.100",
}

createdRecord, err := client.DNSRecords.Create(record)
if err != nil {
    log.Fatal(err)
}

API Coverage

The client provides 100% coverage of the CloudConnexa API v1.2.0 with all public endpoints:

Core Resources

• Networks - Complete network lifecycle management (CRUD operations)
• Users - User management, authentication, and device associations
• User Groups - Group policies, permissions, and access control
• VPN Regions - Available VPN server regions and capabilities

Connectivity & Infrastructure

• Network Connectors - Site-to-site connectivity with IPsec tunnel support
• Host Connectors - Host-based connectivity and routing
• Hosts - Host configuration, monitoring, and IP services
• Routes - Network routing configuration and management

Services & Monitoring

• DNS Records - Private DNS management with direct endpoint access
• Host IP Services - Service definitions and port configurations
• Sessions - OpenVPN session monitoring and analytics
• Devices - Device lifecycle management and security controls

Security & Access Control

• Access Groups - Fine-grained access policies and rules
• Location Contexts - Location-based access controls
• Settings - System-wide configuration and preferences

API v1.1.0 Features

• Direct Endpoints: Optimised single-call access for DNS Records and User Groups
• Enhanced Sessions API: Complete OpenVPN session monitoring with cursor-based pagination
• Comprehensive Devices API: Full device management with filtering and bulk operations
• IPsec Support: Start/stop IPsec tunnels for Network Connectors
• Updated DTOs: Simplified data structures aligned with API v1.1.0

API v1.2.0 Features

• User Lifecycle Management: Activate and suspend users with dedicated endpoints
• Connector Lifecycle Management: Activate and suspend host and network connectors
• IPsec Enhancements: CloudConnexa public IP (serverIp), server ID, and connector state fields
• Licensed Status: Track licensing status for users and connectors (licensed field)

All Endpoints Support

• Pagination - Both cursor-based (Sessions) and page-based (legacy) pagination
• Error Handling - Structured error types with detailed messages
• Rate Limiting - Automatic retry with backoff when the API answers HTTP 429
• Type Safety - Strong typing with comprehensive validation
• Concurrent Safety - Thread-safe operations for production use
• Performance Optimized - Direct API calls where available

Configuration

Rate Limiting

The client does not throttle requests up front. A request rejected with HTTP 429 Too Many Requests is retried automatically: the client waits as long as the server asks through Retry-After or the X-RateLimit-Replenish-* headers (capped at 20 seconds), or backs off exponentially with jitter when no hint is present. Retries on the same client are queued one wait apart, and new requests queue behind them, so concurrent callers do not race each other for the same replenished token. GET requests and other requests are queued separately, matching the API's separate read and write limits. No other error is retried.

// Ten retries by default
client, err := cloudconnexa.NewClient(apiURL, clientID, clientSecret)

// Tune the retry budget
client, err := cloudconnexa.NewClientWithOptions(apiURL, clientID, clientSecret, &cloudconnexa.ClientOptions{
    MaxRetries: 20,
})

// Disable retries and get the 429 back immediately
client, err := cloudconnexa.NewClientWithOptions(apiURL, clientID, clientSecret, &cloudconnexa.ClientOptions{
    MaxRetries: -1,
})

// Log each retry
client, err := cloudconnexa.NewClientWithOptions(apiURL, clientID, clientSecret, &cloudconnexa.ClientOptions{
    OnRetry: func(req *http.Request, attempt int, wait time.Duration) {
        log.Printf("rate limited: %s %s, retry %d in %s", req.Method, req.URL.Path, attempt, wait)
    },
})

// Optional: pace requests proactively as well
client.UpdateRateLimiter = rate.NewLimiter(rate.Every(time.Second), 1)

When the retry budget is spent, the last 429 is returned as *cloudconnexa.ErrClientResponse.

Custom HTTP Client

import (
    "net/http"
    "time"
)

// Use custom HTTP client with timeout
httpClient := &http.Client{
    Timeout: 30 * time.Second,
}

client, err := cloudconnexa.NewClient(apiURL, clientID, clientSecret)
// Client uses default HTTP client with sensible timeouts

Error Handling

The client provides structured error types:

networks, err := client.Networks.List()
if err != nil {
    if clientErr, ok := err.(*cloudconnexa.ErrClientResponse); ok {
        fmt.Printf("API Error: %d - %s\n", clientErr.StatusCode, clientErr.Message)
    } else {
        fmt.Printf("Network Error: %v\n", err)
    }
}

Testing

Unit Tests

# Run unit tests
make test

# Run tests with coverage
go test -v -race -coverprofile=coverage.txt ./cloudconnexa/...

End-to-End Tests

# Run e2e tests (requires API credentials)
export CLOUDCONNEXA_BASE_URL="https://your-org.api.openvpn.com"
export CLOUDCONNEXA_CLIENT_ID="your-client-id"
export CLOUDCONNEXA_CLIENT_SECRET="your-client-secret"

make e2e

Linting

# Run linters
make lint

# Install golangci-lint if needed
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Development Setup

1. Fork the repository
2. Clone your fork
3. Install dependencies: make deps
4. Run tests: make test
5. Run linters: make lint
6. Submit a Pull Request

Code Standards

• Follow Go conventions and best practices
• Write comprehensive tests for new features
• Update documentation for API changes
• Use meaningful commit messages

Versioning

This project follows Semantic Versioning:

• Major version: Breaking API changes
• Minor version: New features, backward compatible
• Patch version: Bug fixes, backward compatible

Current version: v2.x.x

Changelog

See Releases for the detailed changelog.

License

Licensed under the Apache License, Version 2.0. See LICENSE file for details.

Support

Documentation

• Cloud Connexa API Documentation
• Go Package Documentation

Issues and Questions

• Bug reports: GitHub Issues
• Feature requests: GitHub Issues
• Security issues: Email security@openvpn.net

Requirements

• Go 1.25 or later
• Valid Cloud Connexa API credentials
• Network access to Cloud Connexa API endpoints