Eryph Go Client

The official Go client library for Eryph - the open-source infrastructure platform for creating and managing cloud-native virtual machines.

Features

• 🔐 OAuth2 JWT Authentication - Secure authentication using RSA private keys (RFC 7523)
• 🌍 Cross-Platform - Native support for Windows, Linux, and macOS
• 📁 Hierarchical Configuration - Automatic credential discovery across multiple locations
• 🔄 Automatic Token Refresh - Seamless token management with 5-minute expiration buffer
• ⚡ Generated API Client - Modern Go client generated from OpenAPI specifications
• 🎯 Operation Tracking - Monitor long-running operations to completion
• 🧪 Comprehensive Testing - Full unit, integration, and end-to-end test coverage

Quick Start

Installation

go get github.com/eryph-org/go-client/runtime
go get github.com/eryph-org/go-client/compute

Basic Usage

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "github.com/eryph-org/go-client/compute"
    "github.com/eryph-org/go-client/runtime"
)

func main() {
    // Create client with automatic credential discovery
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    client, err := compute.NewClient(ctx, &runtime.ClientOptions{
        Scopes: []string{"compute:read", "compute:write"},
    })
    if err != nil {
        log.Fatalf("Failed to create client: %v", err)
    }

    // List all catlets (virtual machines)
    catlets, err := client.API().CatletsListWithResponse(ctx, nil)
    if err != nil {
        log.Fatalf("Failed to list catlets: %v", err)
    }

    fmt.Printf("Found %d catlets:\n", len(catlets.JSON200.Value))
    for _, catlet := range catlets.JSON200.Value {
        fmt.Printf("- %s (%s): %v\n", catlet.Name, catlet.Id, catlet.Status)
    }
}

Authentication

The Eryph Go Client uses OAuth2 with JWT Bearer Assertion (RFC 7523) for secure authentication. No client secrets are required - only RSA private keys.

Configuration Discovery

The client automatically discovers credentials from multiple locations in this order:

1. Current Directory: ./.eryph/
2. User Home: ~/.config/eryph/ (Linux/macOS) or %APPDATA%\eryph\ (Windows)
3. System: /etc/eryph/ (Linux/macOS) or %PROGRAMDATA%\eryph\ (Windows)

Configuration Format

Configuration files use JSON format with .config extension:

{
  "defaultClientId": "my-client",
  "clients": [
    {
      "id": "my-client", 
      "name": "My Application"
    }
  ],
  "endpoints": {
    "identity": "https://identity.example.com",
    "compute": "https://compute.example.com"
  }
}

Private keys are stored separately in the private/ subdirectory as PEM files.

API Coverage

The client provides access to all Eryph APIs:

• Catlets - Virtual machine lifecycle management
• Networks - Virtual networking configuration
• Projects - Resource organization and access control
• Genes - VM templates and image management
• Operations - Asynchronous operation tracking

Examples

See the examples/ directory for complete working examples:

• basic_auth/ - Authentication and client setup
• create_catlet/ - Create and manage virtual machines
• list_resources/ - Query resources across projects

Development

Prerequisites

• Go 1.21 or later
• pnpm for build tooling
• eryph-zero for E2E testing (Windows only)

Building

# Install dependencies
pnpm install

# Build all platforms
pnpm run build

# Run tests
go test ./...

# Run E2E tests (requires eryph-zero)
go test ./e2e -v

Architecture

The project uses a monorepo structure with Go workspaces:

go-client/
├── runtime/           # Core authentication & configuration  
├── compute/           # Compute API client
├── compute_api/       # Generated API client (from OpenAPI)
├── cmd/eryph-cli/     # CLI application
└── e2e/              # End-to-end tests

Contributing

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

Reporting Issues

• 🐛 Bug Reports: Use the issue tracker with bug template
• 💡 Feature Requests: Use the issue tracker with feature template
• 🔒 Security Issues: Email security@eryph.io

License

This project is licensed under the MIT License - see the LICENSE file for details.

Links

• 🌐 Website: eryph.io
• 📚 Documentation: docs.eryph.io
• 💬 Community: Discord
• 🐙 Source Code: GitHub

---

Made with ❤️ by the Eryph community