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