Cursor rule

1---
2description: Golang basic rules
3globs: *.go,**/*.go
4alwaysApply: false
5---
6# Golang Best Practices
7 
8## Go Version
9- Code can use Go 1.24 features and improvements
10- Reference: 
11- Key enhancements to leverage:
12  - Release notes: @https://tip.golang.org/doc/go1.24
13  - Generic type aliases (`type JSONMap[T any] = map[string]T`)
14  - New `AddCleanup` and weak references for resource management
15  - Improved JSON handling with `omitzero` tag
16  - New cryptography packages from x/crypto
17  - Testing improvements with `b.Loop()` and test analyzers
18  - `os.Root` for filesystem sandboxing
19  - Tool dependency management with `go get -tool`
20  - Optimized map implementation for faster lookups
21 
22## Language Features
23- Use built-in functions `min`, `max`, and `clear` (Go 1.21+)
24  - `min(x, y)` and `max(x, y)` to get smaller/larger of two values
25  - `clear(m)` to empty maps or slices in one call
26- Take advantage of improved generic type inference (Go 1.21+)
27  - Let compiler infer type arguments when possible
28  - Write clear function signatures to help type inference
29- Benefit from fixed loop variable capture (Go 1.22+)
30  - Each iteration now has its own copy of variables
31  - No need for manual variable capture in loops with goroutines
32- Use enhanced range loops:
33  - Range over integers directly: `for i := range 10 { ... }` (Go 1.22+)
34  - Range over iterator functions (Go 1.23+)
35- Use generic type aliases for API clarity (Go 1.24)
36 
37## Standard Library Enhancements
38- Use the `slices` package (Go 1.21+) for operations:
39  - `slices.Index`, `slices.Contains`, `slices.Clone`, `slices.Compare`
40  - `slices.Concat` (Go 1.22+) to concatenate multiple slices
41- Use the `maps` package (Go 1.21+) for map operations:
42  - `maps.Keys(m)` to get a slice of map keys
43  - `maps.Clone(m)` to copy a map
44- Leverage the `cmp` package (Go 1.21+) for comparisons
45- Adopt `log/slog` for structured logging (Go 1.21+)
46- Use `math/rand/v2` for random data generation (Go 1.22+)
47- Utilize enhanced HTTP routing with new `ServeMux` patterns (Go 1.22+)
48- Use `database/sql.Null[T]` for nullable fields (Go 1.22+)
49- Use JSON struct tags effectively, including `omitzero` (Go 1.24)
50- Prefer standard library crypto packages including new ones (Go 1.24)
51 
52## Project Structure
53- Set appropriate Go version in go.mod to enable new compiler checks
54- Use `go mod tidy -diff` (Go 1.23+) to preview dependency changes
55- `main.go` is reserved exclusively for application entry point
56- All internal packages must reside under `internal/` directory
57- Public packages should be placed in `pkg/` directory
58- Group related functionality into coherent packages
59- Use `cmd/` directory for multiple entry points
60- Place test files next to the code they test with `_test.go` suffix
61- Manage tool dependencies with `go get -tool` (Go 1.24)
62 
63## Code Organization
64- Package names should be concise and meaningful
65- One package per directory
66- Avoid circular dependencies between packages
67- Use meaningful directory names that match package names
68- Keep interfaces close to where they are used
69- Follow standard Go project layout conventions
70 
71## Context and Resource Management
72- Always pass context.Context as the first parameter for operations that may be cancelled
73- Implement proper context cancellation for all network operations
74- Use context timeouts for external service calls
75- Chain contexts appropriately without losing parent cancellation
76- Always cancel derived contexts with `defer cancel()`
77- Ensure goroutines are properly terminated when context is cancelled
78- Monitor goroutine leaks using runtime statistics
79- Limit concurrency with contexts or semaphores
80- Use `os.Root` (Go 1.24) to sandbox filesystem access
81  - Reliable protection against path traversal vulnerabilities
82  - Basic usage pattern:
83```go
84    // Open a directory for sandboxed access
85    root, err := os.OpenRoot("/safe/directory")
86    if err != nil {
87        return err
88    }
89    defer root.Close()
90    
91    // All operations are contained within the root directory
92    file, err := root.Open("config.json")      // Opens /safe/directory/config.json
93    file, err := root.Open("../config.json")   // Still opens /safe/directory/config.json
94    
95    // Create subdirectories safely
96    err := root.Mkdir("uploads", 0755)         // Creates /safe/directory/uploads
97    
98    // For recursive operations, use OpenRoot again
99    subdir, err := root.OpenRoot("uploads")    // Opens /safe/directory/uploads as a new Root
100    defer subdir.Close()
101```
102  - Handles symlinks securely (will not follow symlinks outside the root directory)
103  - Prevents time-of-check/time-of-use (TOCTOU) race conditions
104  - Platform-specific implementations (Unix uses openat, Windows uses handle restrictions)
105  - See also: https://go.dev/blog/osroot for complete documentation
106- Consider `runtime.AddCleanup` (Go 1.24) for finalizers if needed
107- Explore `runtime/weak` package (Go 1.24) for weak references in caches
108 
109## File System Security
110- Use `os.Root` for all operations where filenames are untrusted or externally provided
111- Replace common unsafe patterns with safe equivalents:
112  - Instead of: `os.Open(filepath.Join(baseDir, untrustedPath))`
113  - Use: `os.OpenInRoot(baseDir, untrustedPath)` (Go 1.24)
114- When building a wrapped filesystem with custom validation, use `os.Root`:
115```go
116  // Example secureFS implementation with os.Root
117  type secureFS struct {
118      baseDir string
119      root    *os.Root
120  }
121  
122  func newSecureFS(baseDir string) (*secureFS, error) {
123      // Create base directory if needed
124      if err := os.MkdirAll(baseDir, 0755); err != nil {
125          return nil, err
126      }
127      
128      // Open sandboxed root 
129      root, err := os.OpenRoot(baseDir)
130      if err != nil {
131          return nil, err
132      }
133      
134      return &secureFS{
135          baseDir: baseDir,
136          root:    root,
137      }, nil
138  }
139  
140  // Methods operate within sandbox
141  func (fs *secureFS) OpenFile(relativePath string, flag int, perm os.FileMode) (*os.File, error) {
142      // All paths are relative to root, cannot escape
143      return fs.root.OpenFile(relativePath, flag, perm)
144  }
145```
146- For edge cases where extra layers of protection are needed, combine `os.Root` with:
147  - `filepath.IsLocal()` - Validates paths don't contain traversal components
148  - `filepath.EvalSymlinks()` - Resolves symlinks before validation
149- Remember `os.Root` limitations:
150  - Not all operations available (e.g., no `RemoveAll`)
151  - Implementation varies by platform (see docs for platform-specific details)
152 
153## Code Style
154- Functions should be focused and concise (typically under 50 lines)
155- Keep cognitive complexity low (aim for under 50)
156- Use switch statements instead of long if-else chains
157- Combine related parameter types into structs when function has more than 3 parameters
158- Combine parameter types when multiple parameters have the same type (`func(a, b string)` instead of `func(a string, b string)`)
159- Use consistent naming conventions:
160  - Use MixedCaps or mixedCaps rather than underscores
161  - Use short, clear variable names
162  - Acronyms should be consistently cased (HTTP, URL, ID)
163- Document exported functions, types, and packages
164- Name return values in function signatures for better documentation and to avoid gocritic unnamedResult errors, especially for functions returning multiple values of the same type
165- Avoid duplicate imports of the same package
166- Group similar declarations together
167- Order struct fields to minimize padding
168 
169## Error Handling
170- Always check error returns, including from defer statements
171- Use errors.Is() and errors.As() for error comparison instead of == or != operators
172- Use error wrapping with fmt.Errorf("... %w", err) to preserve error types
173- Create custom error types or sentinel errors for important error cases
174- Propagate context.Canceled and context.DeadlineExceeded properly
175- Return errors, don't panic (especially in libraries)
176- Return early for error conditions
177- Implement proper error logging and tracing
178- Check errors from all I/O operations, especially in defer statements
179- Consider errors.Join (Go 1.20+) to combine multiple errors into one
180 
181## Resource Management and Leak Prevention
182- Implement proper resource cleanup in defer statements
183- Always check errors returned from cleanup operations in defer statements
184- Use sync.WaitGroup to wait for goroutines to complete
185- Close channels when no longer needed
186- Implement proper connection pooling with maximum limits
187- Use resource pooling for frequently created/destroyed objects
188- Monitor goroutine count and resource usage
189- Implement circuit breakers for external service calls
190- Use leaktest in tests to detect goroutine leaks
191- Implement proper cleanup for temporary resources
192- Monitor system resources (file descriptors, memory, etc.)
193- Use `runtime.AddCleanup` (Go 1.24) instead of SetFinalizer for cleaner finalizers
194- Explore weak references (Go 1.24) for caches that shouldn't prevent GC
195 
196## Performance and Safety
197- Use pointers for large structs or when mutation is needed
198- Implement proper mutex locks for shared resources
199- Pre-allocate slices when size is known
200- Use sync.Pool for frequently allocated objects
201- Avoid unnecessary string concatenation; use strings.Builder
202- Use buffered I/O operations
203- Implement proper connection pooling
204- Use sync.Map for concurrent map access
205- Avoid multiplication of time durations (use time.Duration directly)
206- Pass large structs by pointer to avoid copying
207- Combine multiple append operations into a single call when possible
208- Leverage modern Go features:
209  - Range over function types for cleaner iteration (Go 1.23+)
210  - Profile Guided Optimization for performance-critical code
211  - Improved timer implementation (Go 1.23+)
212  - New atomic operations
213  - Optimized map implementation (Go 1.24)
214- Use generics where appropriate, with improved type inference (Go 1.21+)
215- Benefit from GC tuning improvements (Go 1.21+) for reduced tail latency
216 
217## Defensive Programming
218- Validate all input parameters
219- Check slice bounds before accessing elements
220- Verify map keys exist before access
221- Handle nil pointer cases explicitly
222- Don't check for nil before using len() on slices or maps (len() is defined as zero for nil slices/maps)
223- Never pass nil contexts; use context.TODO() or context.Background() if unsure
224- Use consistent, typed string keys for context values (avoid raw string type)
225- Use context.Context for cancellation and timeouts
226- Implement proper timeouts for network operations
227- Use proper input sanitization
228- Implement rate limiting where appropriate
229 
230## Testing
231- Write table-driven tests for all packages
232- Use subtests (t.Run) for logically grouped cases
233- Name test functions correctly (TestXxx, BenchmarkXxx, etc.)
234- Use t.Cleanup() for test cleanup instead of custom solutions
235- Use t.TempDir() for temporary test directories
236- Use t.Setenv() to set environment variables for tests
237- Use t.Parallel() when tests can run concurrently
238- Implement benchmark tests with b.Loop() (Go 1.24) instead of manual loops
239- Use the Go fuzzing engine with FuzzXxx functions
240- Profile and optimize iteratively using Go's built-in tools
241- Regularly run go vet with test analyzers (Go 1.24) to catch test mistakes
242 
243## Cross-Platform Compatibility
244- Use filepath.Join instead of string concatenation for paths
245- Use os.PathSeparator when necessary
246- Handle file permissions appropriately
247- Use build tags for platform-specific code
248- Test on both Linux and Darwin regularly
249- Use proper line endings
250- Handle filesystem case sensitivity differences
251- Use os.Root (Go 1.24) for sandboxed filesystem access
252  - Be aware of platform-specific behavior:
253  - On Unix: Uses openat() family of syscalls for secure access
254  - On Windows: Uses handle-based access and prevents traversal 
255  - On WASI: Uses the WASI preview 1 filesystem API
256  - On js/WASM: May be vulnerable to TOCTOU races (check docs)
257 
258## Documentation
259- Document all exported types, functions, and packages
260- Include examples in documentation
261- Provide usage examples in README
262- Document any platform-specific considerations
263- Include license information
264- Document build and test procedures
265 
266## Dependencies
267- Minimize external dependencies
268- Use go.mod for dependency management
269- Pin dependency versions
270- Update go version in go.mod to latest supported version
271- Run go mod tidy regularly (or go mod tidy -diff in Go 1.23+)
272- Manage tool dependencies with go get -tool (Go 1.24)
273- Regularly update dependencies
274- Audit dependencies for security issues
275- Document required external services
276 
277## Monitoring and Observability
278- Implement proper logging with log/slog (Go 1.21+)
279- Use structured logging formats
280- Include trace IDs in logs
281- Implement metrics collection
282- Add health check endpoints
283- Include proper debugging information
284- Implement proper panic recovery
285 
286## Security
287- Use proper input validation
288- Implement secure password handling
289- Use proper encryption for sensitive data
290- Implement rate limiting
291- Use proper authentication and authorization
292- Handle sensitive data appropriately
293- Implement secure session management
294- Use latest crypto packages from standard library (Go 1.24)
295- Consider FIPS 140-3 compliance mechanisms (Go 1.24)
296 
297## Build and Deployment
298- Use proper build tags
299- Implement proper versioning
300- Implement proper signal handling
301- Use proper environment variable handling
302- Implement graceful shutdown
303- Handle configuration properly
304- Use new octal literal style (0o644 instead of 0644)
305- Set up CI/CD pipelines with linter checks and tests
306- Consider Profile-Guided Optimization (PGO) for performance-critical applications
307 
308## Tools
309- Use go vet with stdversionanalyzer to check version compatibility
310- Use go vet test analyzer (Go 1.24) to catch test mistakes
311- Run golangci-lint regularly with appropriate linters:
312  - durationcheck: For detecting incorrect operations with time.Duration
313  - errcheck: To ensure error returns are checked
314  - errorlint: To enforce errors.Is/errors.As usage
315  - gocognit: To keep cognitive complexity manageable
316  - gocritic: To detect various code improvement opportunities
317  - gosimple: To simplify code
318  - ineffassign: To detect ineffectual assignments
319  - staticcheck: For wide range of code improvements
320  - unconvert: To eliminate unnecessary type conversions
321- Configure linter settings via .golangci.yml file
322- Consider enabling Go telemetry (opt-in) to help improve Go
323- Use go env -changed to identify non-default environment settings
324- Leverage go mod tidy -diff to preview dependency changes
325- Use godebug directive in go.mod for debugging settings
326- Run tests with the race detector for non-trivial concurrent code