# 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