ubiquiti-clients/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build and Test Commands

# Build library packages
go build ./pkg/...

# Build CLI tool
go build ./cmd/...

# Run all tests
go test ./...

# Run tests for a specific package
go test ./pkg/toughswitch/...

# Run a single test
go test ./pkg/toughswitch/... -run TestClient_AddDel

# Tidy module dependencies
go mod tidy

Architecture

This repository provides Go client libraries for interacting with Ubiquiti network devices via reverse-engineered REST APIs.

Package Structure

• pkg/toughswitch/ - Client for ToughSwitch devices (e.g., TS-8-PRO)
• pkg/edgeos/ - Client for EdgeOS devices (EdgeRouter, EdgeSwitch)
• cmd/ - Optional CLI tool using cobra (work in progress)

Client Design Pattern

Both packages follow the same multi-device client pattern:

1. Client - Top-level struct holding a map of deviceClient instances keyed by host
2. deviceClient - Per-device HTTP client with authentication state (token for ToughSwitch, cookies for EdgeOS)
3. Config - Device connection settings (host, credentials, TLS options, timeout)

Key characteristics:

• Thread-safe: Uses sync.RWMutex for device map access and sync.Mutex for per-device operations
• Auto-login: Automatically authenticates on 401 responses and retries the request
• Concurrent multi-device: GetAll* methods use sync.WaitGroup.Go() for parallel queries

API Pattern

Each package exposes:

• MustNew(ctx, []Config) - Constructor that accepts multiple device configs
• Add(cfg) / Del(host) - Dynamic device management
• Get<Resource>(ctx, host) - Single device query
• GetAll<Resources>(ctx) - Parallel query across all devices, returns map[string]*Resource

Authentication

• ToughSwitch: Token-based via x-auth-token header from /api/v1.0/user/login
• EdgeOS: Cookie-based from /api/login2 endpoint

Testing

Tests use mockTransport implementing http.RoundTripper to mock HTTP responses without network calls.