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:
Rasmus Widing
2025-08-28 15:13:38 +03:00
parent 785d347f4a
commit 2e4e5fa7e3

View 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