Justin Harms
3703e40442
- Introduced multiple new markdown files detailing caching patterns, configuration management, development workflows, Go language conventions, HTTP proxy patterns, logging and monitoring practices, performance optimization guidelines, project structure, security validation, and VFS architecture. - Each document outlines best practices, patterns, and guidelines to enhance the understanding and implementation of various components within the SteamCache2 project. - This documentation aims to improve maintainability, facilitate onboarding for new contributors, and ensure consistent application of coding and architectural standards across the codebase.
62 lines
2.5 KiB
Plaintext
62 lines
2.5 KiB
Plaintext
---
|
|
globs: *.go
|
|
---
|
|
|
|
# Go Language Conventions for SteamCache2
|
|
|
|
## Code Style
|
|
- Use `gofmt` and `goimports` for formatting
|
|
- Follow standard Go naming conventions (camelCase for private, PascalCase for public)
|
|
- Use meaningful variable names that reflect their purpose
|
|
- Prefer explicit error handling over panic (except in constructors where configuration is invalid)
|
|
|
|
## Package Organization
|
|
- Keep packages focused and cohesive
|
|
- Use internal packages for implementation details that shouldn't be exported
|
|
- Group related functionality together (e.g., all VFS implementations in `vfs/`)
|
|
- Use interface implementation verification: `var _ Interface = (*Implementation)(nil)`
|
|
- Create type aliases for backward compatibility when refactoring
|
|
- Use separate packages for different concerns (e.g., `vfserror`, `types`, `locks`)
|
|
|
|
## Error Handling
|
|
- Always handle errors explicitly - never ignore them with `_`
|
|
- Use `fmt.Errorf` with `%w` verb for error wrapping
|
|
- Log errors with context using structured logging (zerolog)
|
|
- Return meaningful error messages that help with debugging
|
|
- Create custom error types for domain-specific errors (see `vfs/vfserror/`)
|
|
- Use `errors.New()` for simple error constants
|
|
- Include relevant context in error messages (file paths, operation names)
|
|
|
|
## Testing
|
|
- All tests should run with a timeout (as per user rules)
|
|
- Use table-driven tests for multiple test cases
|
|
- Use `t.Helper()` in test helper functions
|
|
- Test both success and failure cases
|
|
- Use `t.TempDir()` for temporary files in tests
|
|
|
|
## Concurrency
|
|
- Use `sync.RWMutex` for read-heavy operations
|
|
- Prefer channels over shared memory when possible
|
|
- Use `context.Context` for cancellation and timeouts
|
|
- Be explicit about goroutine lifecycle management
|
|
- Use sharded locks for high-concurrency scenarios (see `vfs/locks/sharding.go`)
|
|
- Use `atomic.Value` for lock-free data structure updates
|
|
- Use `sync.Map` for concurrent map operations when appropriate
|
|
|
|
## Performance
|
|
- Use `io.ReadAll` sparingly - prefer streaming for large data
|
|
- Use connection pooling for HTTP clients
|
|
- Implement proper resource cleanup (defer statements)
|
|
- Use buffered channels when appropriate
|
|
|
|
## Logging
|
|
- Use structured logging with zerolog
|
|
- Include relevant context in log messages (keys, URLs, client IPs)
|
|
- Use appropriate log levels (Debug, Info, Warn, Error)
|
|
- Avoid logging sensitive information
|
|
|
|
## Memory Management
|
|
- Be mindful of memory usage in caching scenarios
|
|
- Use appropriate data structures for the use case
|
|
- Implement proper cleanup for long-running services
|
|
- Monitor memory usage in production |