Add Go Client Library for A.P.E. API

[GorillaGigabytes]

Summary

Create a Go client library that provides a convenient, type-safe interface for interacting with the A.P.E. (Authorized Primate Encryption) API. This will allow other Go applications to easily integrate with A.P.E. for secrets management without having to handle HTTP requests manually.

Problem Statement

Currently, developers need to manually craft HTTP requests using libraries like net/http or third-party HTTP clients to interact with A.P.E. This approach:

• Requires manual handling of authentication tokens
• Lacks type safety for request/response structures
• Has no built-in retry logic or error handling
• Requires developers to understand the raw API endpoints
• Makes it difficult to maintain consistency across different applications

Proposed Solution

Develop a comprehensive Go client library (github.com/the-monkeys/ape/client) that provides:

Core Features

• Type-safe API methods for all A.P.E. endpoints
• Automatic authentication handling (JWT token management)
• AppRole authentication support for machine-to-machine communication
• Automatic token renewal when tokens expire
• Built-in retry logic with exponential backoff
• Structured error handling with custom error types
• Connection pooling and HTTP client optimization
• Context support for request cancellation and timeouts

API Coverage

The client should support all current A.P.E. API endpoints:

Authentication

• Login(roleID, secretID string) (*AuthResponse, error)
• RefreshToken() error

Secret Management

• CreateSecret(path string, data map[string]interface{}) (*SecretResponse, error)
• GetSecret(path string) (*SecretResponse, error)
• DeleteSecret(path string) error
• ListSecrets(path string) (*SecretListResponse, error)

AppRole Management

• CreateAppRole(roleName string, role *AppRole) (*AppRoleResponse, error)

Health & Status

• Health() (*HealthResponse, error)

Example Usage

package main

import (
    "context"
    "log"
    
    "github.com/the-monkeys/ape/client"
)

func main() {
    // Initialize client
    config := &client.Config{
        Address:  "http://localhost:8080",
        RoleID:   "your-role-id",
        SecretID: "your-secret-id",
    }
    
    apeClient, err := client.New(config)
    if err != nil {
        log.Fatal(err)
    }
    
    // Authenticate (handled automatically)
    ctx := context.Background()
    
    // Create a secret
    secretData := map[string]interface{}{
        "username": "dbuser",
        "password": "secretpass123",
    }
    
    _, err = apeClient.CreateSecret(ctx, "myapp/database", secretData)
    if err != nil {
        log.Fatal(err)
    }
    
    // Retrieve a secret
    secret, err := apeClient.GetSecret(ctx, "myapp/database")
    if err != nil {
        log.Fatal(err)
    }
    
    username := secret.Data["username"].(string)
    password := secret.Data["password"].(string)
    
    log.Printf("DB Credentials - User: %s, Pass: %s", username, password)
}

Implementation Details

Project Structure

client/
├── client.go           # Main client implementation
├── auth.go            # Authentication handling
├── config.go          # Configuration structures
├── errors.go          # Custom error types
├── types.go           # Request/Response types
├── secrets.go         # Secret management methods
├── approle.go         # AppRole management methods
├── retry.go           # Retry logic implementation
└── examples/
    ├── basic_usage.go
    ├── with_retry.go
    └── batch_operations.go

Configuration Options

type Config struct {
    // Required
    Address  string // A.P.E. server address
    RoleID   string // AppRole ID for authentication
    SecretID string // AppRole Secret ID
    
    // Optional
    HTTPTimeout    time.Duration // Default: 30s
    RetryAttempts  int          // Default: 3
    RetryDelay     time.Duration // Default: 1s
    MaxRetryDelay  time.Duration // Default: 30s
    TLSConfig      *tls.Config  // For HTTPS
    Logger         Logger       // Custom logger interface
}

Error Handling

type APIError struct {
    StatusCode int
    Message    string
    Path       string
    Method     string
}

type AuthError struct {
    Message string
    Reason  string // "expired", "invalid", "forbidden"
}

Testing Requirements

• Unit tests for all client methods
• Integration tests against a running A.P.E. server
• Mock server tests for error scenarios
• Benchmark tests for performance
• Example code that compiles and runs

Documentation Requirements

• Comprehensive README with usage examples
• GoDoc comments for all public APIs
• Code examples for common use cases
• Integration guide for different authentication methods

Acceptance Criteria

• Client library compiles without errors
• All A.P.E. API endpoints are supported
• Automatic authentication and token renewal works
• Retry logic handles temporary failures
• Context cancellation is respected
• Unit test coverage > 80%
• Integration tests pass against live A.P.E. server
• Documentation is complete and accurate
• Example applications demonstrate real-world usage

Dependencies

• Go 1.21+ (to match A.P.E. server requirements)
• Standard library only (minimize external dependencies)
• Optional: golang.org/x/time/rate for rate limiting

Breaking Changes

This is a new feature, so no breaking changes to existing code.

Migration Guide

N/A - This is a new client library.

Additional Context

• The client should follow Go best practices and idioms
• Consider implementing interfaces for easier testing and mocking
• The client should be thread-safe for concurrent usage
• Include proper logging for debugging and monitoring
• Consider adding metrics collection hooks for observability

Related Issues

• None currently

Labels

• enhancement
• go
• client-library
• api
• good-first-issue (for documentation parts)

---

Priority: Medium
Estimated Effort: 1-2 weeks
Assignee: TBD