common/CLAUDE.md

CLAUDE.md

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

Commands

Testing

• Run all tests: go test ./...
• Run tests with verbose output: go test -v ./...
• Run tests for specific package: go test ./config
• Run specific test: go test -run TestConfigBool ./config

Building

• Build all packages: go build ./...
• Check module dependencies: go mod tidy
• Verify dependencies: go mod verify

Code Quality

• Format code: go fmt ./...
• Vet code: go vet ./...
• Run static analysis: staticcheck ./... (if available)

Architecture

This is a common library (go.ntppool.org/common) providing shared infrastructure for the NTP Pool project. The codebase emphasizes observability, security, and modern Go practices.

Core Components

Web Service Foundation:

• ekko/ - Enhanced Echo web framework with pre-configured middleware (OpenTelemetry, Prometheus, logging, security headers)
• health/ - Standalone health check HTTP server with /__health endpoint
• metricsserver/ - Prometheus metrics exposure via /metrics endpoint

Observability Stack:

• logger/ - Structured logging with OpenTelemetry trace integration and multiple output formats
• tracing/ - OpenTelemetry distributed tracing with OTLP export support
• metricsserver/ - Prometheus metrics with custom registry

Configuration & Environment:

• config/ - Environment-based configuration with code-generated accessors (config_accessor.go)
• version/ - Build metadata and version information with Cobra CLI integration

Security & Communication:

• apitls/ - TLS certificate management with automatic renewal via certman
• kafka/ - Kafka client wrapper with TLS support for log streaming
• xff/fastlyxff/ - Fastly CDN IP range management for trusted proxy handling

Utilities:

• ulid/ - Thread-safe ULID generation with monotonic ordering
• timeutil/ - JSON-serializable duration types
• types/ - Shared data structures (LogScoreAttributes for NTP server scoring)

Key Patterns

Functional Options: Used extensively in ekko/ for flexible service configuration Interface-Based Design: CertificateProvider in apitls/ for pluggable certificate management Context Propagation: Throughout the codebase for cancellation and tracing Graceful Shutdown: Implemented in web servers and background services

Dependencies

The codebase heavily uses:

• Echo web framework with custom middleware stack
• OpenTelemetry for observability (traces, metrics, logs)
• Prometheus for metrics collection
• Kafka for message streaming
• Cobra for CLI applications

Code Generation

config/config_accessor.go is generated - modify config.go and regenerate accessors when adding new configuration options.

Package Overview

apitls/

TLS certificate management with automatic renewal support via certman. Provides a CA pool for trusted certificates and interfaces for pluggable certificate providers. Used for secure inter-service communication.

config/

Environment-based configuration system with code-generated accessor methods. Handles deployment mode, hostname configuration, and TLS settings. Provides URL building utilities for web and management interfaces.

ekko/

Enhanced Echo web framework wrapper with pre-configured middleware stack including OpenTelemetry tracing, Prometheus metrics, structured logging, gzip compression, and security headers. Supports HTTP/2 with graceful shutdown.

health/

Standalone HTTP health check server that runs independently from the main application. Exposes /__health endpoint with configurable health handlers, timeouts, and graceful shutdown capabilities.

kafka/

Kafka client wrapper with TLS support for secure log streaming. Provides connection management, broker discovery, and reader/writer factories with compression and batching optimizations.

logger/

Structured logging system with OpenTelemetry trace integration. Supports multiple output formats (text, OTLP) with configurable log levels, systemd compatibility, and context-aware logging.

metricsserver/

Dedicated Prometheus metrics HTTP server with custom registry isolation. Exposes /metrics endpoint with OpenMetrics support and graceful shutdown handling.

timeutil/

JSON-serializable duration types that support both string parsing ("30s", "5m") and numeric nanosecond values. Compatible with configuration files and REST APIs.

tracing/

OpenTelemetry distributed tracing setup with support for OTLP export via gRPC or HTTP. Handles resource detection, propagation, and automatic instrumentation with configurable TLS.

types/

Shared data structures for the NTP Pool project. Currently contains LogScoreAttributes for NTP server scoring with JSON and SQL database compatibility.

ulid/

Thread-safe ULID (Universally Unique Lexicographically Sortable Identifier) generation using cryptographically secure randomness. Optimized for simplicity and performance in high-concurrency environments.

version/

Build metadata and version information system with Git integration. Provides CLI commands for Cobra and Kong frameworks, Prometheus build info metrics, and semantic version validation.

xff/fastlyxff/

Fastly CDN IP range management for trusted proxy handling. Parses Fastly's IP ranges JSON file and generates Echo framework trust options for proper client IP extraction.

Go Development Best Practices

Code Style

• Follow standard Go formatting (go fmt ./...)
• Use go vet ./... for static analysis
• Run staticcheck ./... when available
• Prefer short, descriptive variable names
• Use interfaces for testability and flexibility

Error Handling

• Always handle errors explicitly
• Use errors.Join() for combining multiple errors
• Wrap errors with context using fmt.Errorf("context: %w", err)
• Return early on errors to reduce nesting

Testing

• Write table-driven tests when testing multiple scenarios
• Use t.Helper() in test helper functions
• Test error conditions, not just happy paths
• Use testing.Short() for integration tests that can be skipped

Concurrency

• Use contexts for cancellation and timeouts
• Prefer channels for communication over shared memory
• Use sync.Once for one-time initialization
• Always call defer cancel() after context.WithCancel()

Performance

• Use sync.Pool for frequently allocated objects
• Prefer slices over arrays for better performance
• Use strings.Builder for string concatenation in loops
• Profile before optimizing with go tool pprof

Observability

• Use structured logging with key-value pairs
• Add OpenTelemetry spans for external calls
• Include trace IDs in error messages
• Use metrics for monitoring application health

Dependencies

• Keep dependencies minimal and well-maintained
• Use go mod tidy to clean up unused dependencies
• Pin major versions to avoid breaking changes
• Prefer standard library when possible

Security

• Never log sensitive information (passwords, tokens)
• Use crypto/rand for cryptographic randomness
• Validate all inputs at API boundaries
• Use TLS for all network communication