Add copilot/claude instructions
This commit is contained in:
parent
f69c3e9c3c
commit
3c994a7343
1
.github/copilot-instructions.md
vendored
Symbolic link
1
.github/copilot-instructions.md
vendored
Symbolic link
@ -0,0 +1 @@
|
|||||||
|
../CLAUDE.md
|
||||||
163
CLAUDE.md
Normal file
163
CLAUDE.md
Normal file
@ -0,0 +1,163 @@
|
|||||||
|
# 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 pooled monotonic readers with cryptographically secure seeding for 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
|
||||||
Loading…
x
Reference in New Issue
Block a user