---
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