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.
57 lines
2.3 KiB
Plaintext
57 lines
2.3 KiB
Plaintext
---
|
|
alwaysApply: true
|
|
---
|
|
|
|
# SteamCache2 Project Structure Guide
|
|
|
|
This is a high-performance Steam download cache written in Go. The main entry point is [main.go](mdc:main.go), which delegates to the command structure in [cmd/](mdc:cmd/).
|
|
|
|
## Core Architecture
|
|
|
|
- **Main Entry**: [main.go](mdc:main.go) - Simple entry point that calls `cmd.Execute()`
|
|
- **Command Layer**: [cmd/root.go](mdc:cmd/root.go) - CLI interface using Cobra, handles configuration loading and service startup
|
|
- **Core Service**: [steamcache/steamcache.go](mdc:steamcache/steamcache.go) - Main HTTP proxy and caching logic
|
|
- **Configuration**: [config/config.go](mdc:config/config.go) - YAML-based configuration management
|
|
- **Virtual File System**: [vfs/](mdc:vfs/) - Abstracted storage layer supporting memory and disk caches
|
|
|
|
## Key Components
|
|
|
|
### VFS (Virtual File System)
|
|
- [vfs/vfs.go](mdc:vfs/vfs.go) - Core VFS interface
|
|
- [vfs/memory/](mdc:vfs/memory/) - In-memory cache implementation
|
|
- [vfs/disk/](mdc:vfs/disk/) - Disk-based cache implementation
|
|
- [vfs/cache/](mdc:vfs/cache/) - Cache coordination layer
|
|
- [vfs/gc/](mdc:vfs/gc/) - Garbage collection algorithms (LRU, LFU, FIFO, etc.)
|
|
|
|
### Service Management
|
|
- Service detection via User-Agent patterns
|
|
- Support for multiple gaming services (Steam, Epic, etc.)
|
|
- SHA256-based cache key generation with service prefixes
|
|
|
|
### Advanced Features
|
|
- [vfs/adaptive/](mdc:vfs/adaptive/) - Adaptive caching strategies
|
|
- [vfs/predictive/](mdc:vfs/predictive/) - Predictive cache warming
|
|
- Request coalescing for concurrent downloads
|
|
- Range request support for partial content
|
|
|
|
## Development Workflow
|
|
|
|
Use the [Makefile](mdc:Makefile) for development:
|
|
- `make` - Run tests and build
|
|
- `make test` - Run all tests
|
|
- `make run` - Run the application
|
|
- `make run-debug` - Run with debug logging
|
|
|
|
## Testing
|
|
|
|
- Unit tests: [steamcache/steamcache_test.go](mdc:steamcache/steamcache_test.go)
|
|
- Integration tests: [steamcache/integration_test.go](mdc:steamcache/integration_test.go)
|
|
- Test cache data: [steamcache/test_cache/](mdc:steamcache/test_cache/)
|
|
|
|
## Configuration
|
|
|
|
Default configuration is generated in [config.yaml](mdc:config.yaml) on first run. The application supports:
|
|
- Memory and disk cache sizing
|
|
- Garbage collection algorithm selection
|
|
- Concurrency limits
|
|
- Upstream server configuration |