Files
headroom/tests/test_cache/test_google.py
Abhay Singh 7ce2580ff9 fix(cache/google): tolerate timezone-aware cache expiry timestamps (#3210)
## Description

`GoogleCacheOptimizer` tracks Google `CachedContent` lifecycles via
`CachedContentInfo`, whose `is_expired` / `ttl_remaining_seconds` /
`age_seconds` compared a stored `expires_at` / `created_at` against a
**naive** `datetime.now()`:

```python
@property
def is_expired(self) -> bool:
    return datetime.now() >= self.expires_at
```

The documented integration registers the timestamp straight off Google's
SDK:

```python
cached_content = genai.caching.CachedContent.create(model=..., contents=..., ttl=timedelta(hours=1))
optimizer.register_cache(cache_id=cached_content.name, ..., expires_at=cached_content.expire_time)
```

`CachedContent.expire_time` is a timezone-**aware** RFC3339 value.
Comparing or subtracting it against a naive `datetime.now()` raises
`TypeError: can't compare offset-naive and offset-aware datetimes`. This
crashes `register_cache` itself (it logs `ttl_remaining_seconds`), and
every consumer of `is_expired`: `get_reusable_cache`,
`cleanup_expired_caches`, and the `list_*` helpers. A single aware entry
also poisons `cleanup_expired_caches`, which iterates `is_expired` over
the whole registry. `CachedContentInfo.from_dict` reconstructs the same
aware value from a persisted `expires_at`, so the crash survives a
save/restore round-trip.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/cache/google.py`: added a `_now_matching(reference)` helper
that returns `datetime.now(reference.tzinfo)`, and use it in
`CachedContentInfo.is_expired`, `ttl_remaining_seconds`, and
`age_seconds`. "Now" is anchored to the same awareness as the value it
is measured against, so an aware `expires_at` compares against an aware
now, and a naive one keeps the exact prior behavior
(`datetime.now(None)` is naive local time).
- `tests/test_cache/test_google.py`: added
`test_cache_registration_accepts_aware_expiry`,
`test_cache_lookup_expired_aware`, and
`test_from_dict_roundtrip_preserves_aware_expiry`.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality

### Test Output

```text
tests/test_cache/test_google.py  ->  21 passed in 0.72s
uvx ruff@0.16.2 check headroom/cache/google.py tests/test_cache/test_google.py  ->  All checks passed!
uvx mypy@1.20.2 headroom/cache/google.py  ->  Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: Windows 11, Python 3.12.11, project venv, pytest 9.1.1,
ruff 0.16.2 and mypy 1.20.2 via uvx.
- Exact command / steps: before the fix, `optimizer.register_cache(...,
expires_at=datetime.now(timezone.utc) + timedelta(hours=1))` raised
`TypeError: can't subtract offset-naive and offset-aware datetimes` at
`google.py:108` (`ttl_remaining_seconds`, called from `register_cache`'s
log line). After the fix, the same call registers cleanly,
`get_reusable_cache` returns the entry, `cleanup_expired_caches` returns
`[]`, an aware past-expiry entry reports `is_expired == True`, and naive
registrations behave exactly as before (`is_expired == False`,
`ttl_remaining_seconds > 0`).
- Observed result: aware and naive expiry timestamps both work; no
`TypeError`; naive-path values unchanged.
- Not tested: no live `genai.caching.CachedContent.create` call (the
optimizer intentionally makes no API calls); the aware timestamp Google
returns is reproduced with `datetime.now(timezone.utc)`, which has the
same awareness.

## Runtime Rollout Safety

- Rollout-managed feature(s): none. `GoogleCacheOptimizer` is an
SDK-side cache lifecycle utility (`headroom.cache`), not a
rollout-channel-gated runtime feature.
- Minimum rollout channel: N/A.
- Stable/default behavior changed: no. Naive timestamps take
`datetime.now(None)`, identical to the previous `datetime.now()`; only
the previously-crashing aware case changes, from `TypeError` to a
correct comparison.
- Kill switch / disable path: N/A.
- Unsafe override required: no.
- Qualification impact: none; behavior for existing naive callers is
byte-for-byte unchanged.
- Rollback path: revert this PR; the properties return to a naive
`datetime.now()`.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation (N/A:
internal behavior, unchanged semantics)
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md`

## Additional Notes

`_now_matching` is deliberately minimal: it does not rewrite stored
timestamps or change the serialization format, so a mixed registry of
naive and aware entries each compare correctly on their own terms. This
matches the module's existing convention of leaving caller-supplied
timestamps as-is.
2026-09-25 11:07:54 -05:00

323 lines
11 KiB
Python

"""Tests for GoogleCacheOptimizer."""
from datetime import datetime, timedelta, timezone
import pytest
from headroom.cache import CacheConfig, GoogleCacheOptimizer, OptimizationContext
from headroom.cache.base import CacheStrategy
from headroom.cache.google import (
GOOGLE_CACHE_DISCOUNT,
GOOGLE_MIN_CACHE_TOKENS,
CacheabilityAnalysis,
CachedContentInfo,
)
class TestGoogleCacheOptimizer:
"""Test GoogleCacheOptimizer functionality."""
@pytest.fixture
def optimizer(self):
"""Create optimizer instance."""
return GoogleCacheOptimizer()
@pytest.fixture
def context(self):
"""Create optimization context."""
return OptimizationContext(
provider="google",
model="gemini-1.5-pro",
)
def test_optimizer_properties(self, optimizer):
"""Test optimizer properties."""
assert optimizer.name == "google-cached-content"
assert optimizer.provider == "google"
assert optimizer.strategy == CacheStrategy.CACHED_CONTENT
def test_enforces_minimum_tokens(self):
"""Test that Google's minimum is enforced."""
config = CacheConfig(min_cacheable_tokens=100)
optimizer = GoogleCacheOptimizer(config)
assert optimizer.config.min_cacheable_tokens >= GOOGLE_MIN_CACHE_TOKENS
def test_optimize_below_threshold(self, optimizer, context):
"""Test optimization with content below threshold."""
messages = [
{"role": "system", "content": "Short system prompt."},
{"role": "user", "content": "Hello!"},
]
result = optimizer.optimize(messages, context)
assert result.metrics.cacheable_tokens < GOOGLE_MIN_CACHE_TOKENS
assert any("32K" in w for w in result.warnings)
def test_optimize_above_threshold(self, optimizer, context):
"""Test optimization with content above threshold."""
# Create content above 32K tokens
messages = [
{"role": "system", "content": "You are helpful. " * 15000},
{"role": "user", "content": "Hello!"},
]
result = optimizer.optimize(messages, context)
assert result.metrics.cacheable_tokens > 0
if result.metrics.cacheable_tokens >= GOOGLE_MIN_CACHE_TOKENS:
assert result.metrics.estimated_savings_percent == GOOGLE_CACHE_DISCOUNT * 100
def test_analyze_cacheability(self, optimizer, context):
"""Test cacheability analysis."""
messages = [
{"role": "system", "content": "Short"},
{"role": "user", "content": "Hello!"},
]
analysis = optimizer.analyze_cacheability(messages, context)
assert isinstance(analysis, CacheabilityAnalysis)
assert analysis.total_tokens > 0
assert analysis.tokens_below_minimum > 0
assert analysis.is_cacheable is False
assert len(analysis.recommendations) > 0
def test_cache_registration(self, optimizer):
"""Test registering a cache."""
cache_info = optimizer.register_cache(
cache_id="test-cache-123",
content_hash="abc123",
token_count=50000,
expires_at=datetime.now() + timedelta(hours=1),
)
assert cache_info.cache_id == "test-cache-123"
assert cache_info.content_hash == "abc123"
assert cache_info.token_count == 50000
assert not cache_info.is_expired
assert cache_info.ttl_remaining_seconds > 0
def test_cache_lookup(self, optimizer):
"""Test looking up a registered cache."""
optimizer.register_cache(
cache_id="test-cache-456",
content_hash="def456",
token_count=50000,
expires_at=datetime.now() + timedelta(hours=1),
)
found = optimizer.get_reusable_cache("def456")
assert found is not None
assert found.cache_id == "test-cache-456"
def test_cache_lookup_expired(self, optimizer):
"""Test that expired caches are not returned."""
optimizer.register_cache(
cache_id="expired-cache",
content_hash="expired123",
token_count=50000,
expires_at=datetime.now() - timedelta(hours=1),
)
found = optimizer.get_reusable_cache("expired123")
assert found is None
def test_cache_registration_accepts_aware_expiry(self, optimizer):
"""A timezone-aware ``expires_at`` must not crash lifecycle checks.
Google's ``genai.caching.CachedContent.expire_time`` is an aware
RFC3339 value, and the documented integration registers it directly.
Comparing it against a naive ``datetime.now()`` raised
``TypeError: can't compare offset-naive and offset-aware datetimes``,
which crashed ``register_cache`` itself (it logs ``ttl_remaining_seconds``)
and every ``is_expired`` consumer.
"""
aware_future = datetime.now(timezone.utc) + timedelta(hours=1)
cache_info = optimizer.register_cache(
cache_id="aware-cache",
content_hash="aware123",
token_count=50000,
expires_at=aware_future,
)
assert not cache_info.is_expired
assert cache_info.ttl_remaining_seconds > 0
assert cache_info.age_seconds >= 0
# Lookup and cleanup iterate is_expired over the registry.
assert optimizer.get_reusable_cache("aware123") is not None
assert optimizer.cleanup_expired_caches() == []
def test_cache_lookup_expired_aware(self, optimizer):
"""An already-expired aware cache is recognized as expired, not crashed."""
aware_past = datetime.now(timezone.utc) - timedelta(hours=1)
cache_info = optimizer.register_cache(
cache_id="aware-expired",
content_hash="awareexp123",
token_count=50000,
expires_at=aware_past,
)
assert cache_info.is_expired
assert optimizer.get_reusable_cache("awareexp123") is None
def test_from_dict_roundtrip_preserves_aware_expiry(self):
"""``to_dict``/``from_dict`` of an aware timestamp stays comparable."""
info = CachedContentInfo(
cache_id="rt",
content_hash="rt123",
created_at=datetime.now(timezone.utc),
expires_at=datetime.now(timezone.utc) + timedelta(hours=1),
token_count=50000,
)
restored = CachedContentInfo.from_dict(info.to_dict())
assert restored.is_expired is False
assert restored.ttl_remaining_seconds > 0
def test_cache_lookup_insufficient_ttl(self, optimizer):
"""Test that caches with insufficient TTL are not returned."""
optimizer.register_cache(
cache_id="short-ttl-cache",
content_hash="shortttl123",
token_count=50000,
expires_at=datetime.now() + timedelta(seconds=30),
)
# Default min_ttl is 60 seconds
found = optimizer.get_reusable_cache("shortttl123")
assert found is None
def test_extend_cache_ttl(self, optimizer):
"""Test extending cache TTL."""
optimizer.register_cache(
cache_id="extend-cache",
content_hash="extend123",
token_count=50000,
expires_at=datetime.now() + timedelta(hours=1),
)
new_expires = datetime.now() + timedelta(hours=2)
updated = optimizer.extend_cache_ttl("extend-cache", new_expires)
assert updated is not None
assert updated.expires_at == new_expires
def test_remove_cache(self, optimizer):
"""Test removing a cache."""
optimizer.register_cache(
cache_id="remove-cache",
content_hash="remove123",
token_count=50000,
expires_at=datetime.now() + timedelta(hours=1),
)
removed = optimizer.remove_cache("remove-cache")
assert removed is True
found = optimizer.get_reusable_cache("remove123")
assert found is None
def test_cleanup_expired_caches(self, optimizer):
"""Test cleaning up expired caches."""
# Register expired cache
optimizer.register_cache(
cache_id="cleanup-expired",
content_hash="cleanup123",
token_count=50000,
expires_at=datetime.now() - timedelta(hours=1),
)
expired_ids = optimizer.cleanup_expired_caches()
assert "cleanup-expired" in expired_ids
def test_list_caches(self, optimizer):
"""Test listing caches."""
optimizer.register_cache(
cache_id="list-cache-1",
content_hash="list1",
token_count=50000,
expires_at=datetime.now() + timedelta(hours=1),
)
optimizer.register_cache(
cache_id="list-cache-2",
content_hash="list2",
token_count=50000,
expires_at=datetime.now() + timedelta(hours=2),
)
caches = optimizer.list_caches()
assert len(caches) >= 2
def test_get_statistics(self, optimizer):
"""Test getting statistics."""
optimizer.register_cache(
cache_id="stats-cache",
content_hash="stats123",
token_count=50000,
expires_at=datetime.now() + timedelta(hours=1),
)
stats = optimizer.get_statistics()
assert "active_caches" in stats
assert "caches_created" in stats
assert stats["caches_created"] >= 1
def test_prepare_cache_creation(self, optimizer, context):
"""Test preparing cache creation parameters."""
messages = [
{"role": "system", "content": "You are helpful. " * 15000},
{"role": "user", "content": "Hello!"},
]
params = optimizer.prepare_cache_creation(messages, context)
if params is not None:
assert "contents" in params
assert "ttl" in params
assert "display_name" in params
def test_build_request_with_cache(self, optimizer):
"""Test building request with cache."""
messages = [
{"role": "system", "content": "System prompt"},
{"role": "user", "content": "User message"},
]
request = optimizer.build_request_with_cache(messages, "cache-123")
assert "cached_content" in request
assert request["cached_content"] == "cache-123"
assert "contents" in request
def test_export_import_registry(self, optimizer):
"""Test exporting and importing cache registry."""
optimizer.register_cache(
cache_id="export-cache",
content_hash="export123",
token_count=50000,
expires_at=datetime.now() + timedelta(hours=1),
)
exported = optimizer.export_cache_registry()
assert len(exported) >= 1
new_optimizer = GoogleCacheOptimizer()
imported = new_optimizer.import_cache_registry(exported)
assert imported >= 1
def test_cached_content_info_serialization(self):
"""Test CachedContentInfo serialization."""
info = CachedContentInfo(
cache_id="test",
content_hash="hash",
created_at=datetime.now(),
expires_at=datetime.now() + timedelta(hours=1),
token_count=50000,
)
data = info.to_dict()
restored = CachedContentInfo.from_dict(data)
assert restored.cache_id == info.cache_id
assert restored.content_hash == info.content_hash
assert restored.token_count == info.token_count