mirror of
https://github.com/coleam00/Archon.git
synced 2025-12-30 21:49:30 -05:00
Document ETag implementation and limitations
- Add concise documentation explaining current ETag implementation - Document that we use simple equality check, not full RFC 7232 - Clarify this works for our browser-to-API use case - Note limitations for future CDN/proxy support Addresses Code Rabbit feedback about RFC compliance by documenting the known limitations of our simplified implementation. 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
39
PRPs/ai_docs/ETAG_IMPLEMENTATION.md
Normal file
39
PRPs/ai_docs/ETAG_IMPLEMENTATION.md
Normal file
@@ -0,0 +1,39 @@
|
||||
# ETag Implementation
|
||||
|
||||
## Current Implementation
|
||||
|
||||
Our ETag implementation provides efficient HTTP caching for polling endpoints to reduce bandwidth usage.
|
||||
|
||||
### What It Does
|
||||
- **Generates ETags**: Creates MD5 hashes of JSON response data
|
||||
- **Checks ETags**: Simple string equality comparison between client's `If-None-Match` header and current data's ETag
|
||||
- **Returns 304**: When ETags match, returns `304 Not Modified` with no body (saves bandwidth)
|
||||
|
||||
### How It Works
|
||||
1. Server generates ETag from response data using MD5 hash
|
||||
2. Client sends previous ETag in `If-None-Match` header
|
||||
3. Server compares ETags:
|
||||
- **Match**: Returns 304 (no body)
|
||||
- **No match**: Returns 200 with new data and new ETag
|
||||
|
||||
### Example
|
||||
```python
|
||||
# Server generates: ETag: "a3c2f1e4b5d6789"
|
||||
# Client sends: If-None-Match: "a3c2f1e4b5d6789"
|
||||
# Server returns: 304 Not Modified (no body)
|
||||
```
|
||||
|
||||
## Limitations
|
||||
|
||||
Our implementation is simplified and doesn't support full RFC 7232 features:
|
||||
- ❌ Wildcard (`*`) matching
|
||||
- ❌ Multiple ETags (`"etag1", "etag2"`)
|
||||
- ❌ Weak validators (`W/"etag"`)
|
||||
- ✅ Single ETag comparison only
|
||||
|
||||
This works perfectly for our browser-to-API polling use case but may need enhancement for CDN/proxy support.
|
||||
|
||||
## Files
|
||||
- Implementation: `python/src/server/utils/etag_utils.py`
|
||||
- Tests: `python/tests/server/utils/test_etag_utils.py`
|
||||
- Used in: Progress API, Projects API polling endpoints
|
||||
Reference in New Issue
Block a user