Handle compressed responses and cache

Author: joshuanapoli

.github/workflows/license-check-python.yml

@@ -10,30 +10,8 @@ jobs:
     steps:
       - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
 
-      - name: Create GitHub App Token able to read all CVector repos
-        id: app
-        uses: actions/create-github-app-token@v2
+      - name: Check Python licenses
+        uses: CVector-Energy/pyproject-license-check@main
         with:
           app-id: ${{ vars.APP_ID }}
-          private-key: ${{ secrets.APP_PRIVATE_KEY }}
-          owner: ${{ github.repository_owner }}
-          permission-contents: read
-
-      - name: Set up uv
-        uses: astral-sh/setup-uv@5a7eac68fb9809dea845d802897dc5c723910fa3 # v7.1.3
-
-      - name: Configure git to use app token for private repos
-        run: |
-          git config --global url."https://x-access-token:${{ steps.app.outputs.token }}@github.com/".insteadOf "https://github.com/"
-
-      - name: Run license check
-        run: |
-          SKIP_DEPS=(
-            cvec-commons  # Internal library, not published to PyPI
-            wrapt         # BSD-2-Clause license
-          )
-          find . \( -name 'pyproject.toml' -o -name 'requirements.txt' \) -print0 | \
-            xargs -0 -r uvx licensecheck@2025.1.0 --zero \
-              --skip-dependencies "${SKIP_DEPS[@]}" \
-              --ignore-licenses MPL \
-              --requirements-paths
+          app-private-key: ${{ secrets.APP_PRIVATE_KEY }}

src/cvec/cvec.py

@@ -1,12 +1,17 @@
+import gzip
 import json
 import logging
 import os
+import time
+import zlib
 from datetime import datetime
 from typing import Any, Dict, List, Optional
 from urllib.error import HTTPError, URLError
 from urllib.parse import urlencode, urljoin
 from urllib.request import Request, urlopen
 
+from cvec.http_cache import CacheEntry, parse_max_age
+
 from cvec.models.agent_post import AgentPost, AgentPostRecommendation, AgentPostTag
 from cvec.models.eav_column import EAVColumn
 from cvec.models.eav_filter import EAVFilter
@@ -53,6 +58,9 @@ def __init__(
         self._publishable_key = None
         self._api_key = api_key or os.environ.get("CVEC_API_KEY")
 
+        # HTTP cache for GET requests
+        self._cache: Dict[str, CacheEntry] = {}
+
         if not self.host:
             raise ValueError(
                 "CVEC_HOST must be set either as an argument or environment variable"
@@ -105,8 +113,51 @@ def _get_headers(self) -> Dict[str, str]:
             "Authorization": f"Bearer {self._access_token}",
             "Content-Type": "application/json",
             "Accept": "application/json",
+            "Accept-Encoding": "gzip, deflate",
         }
 
+    @staticmethod
+    def _read_response(response: Any) -> tuple[bytes, str]:
+        """Read and decompress response body.
+
+        Returns:
+            Tuple of (decompressed data, content type)
+        """
+        raw = response.read()
+        encoding = response.headers.get("Content-Encoding", "")
+        if encoding == "gzip":
+            raw = gzip.decompress(raw)
+        elif encoding == "deflate":
+            raw = zlib.decompress(raw)
+        content_type: str = response.headers.get("content-type", "")
+        return raw, content_type
+
+    @staticmethod
+    def _parse_response_body(response_data: bytes, content_type: str) -> Any:
+        """Parse response body based on content type."""
+        if content_type == "application/vnd.apache.arrow.stream":
+            return response_data
+        return json.loads(response_data.decode("utf-8"))
+
+    def _process_response(self, response: Any, url: str, method: str) -> Any:
+        """Read, decompress, parse, and optionally cache a response."""
+        response_data, content_type = self._read_response(response)
+        parsed = self._parse_response_body(response_data, content_type)
+
+        if method == "GET":
+            cache_control = response.headers.get("Cache-Control", "")
+            max_age = parse_max_age(cache_control)
+            if max_age is not None:
+                etag = response.headers.get("ETag", "") or None
+                self._cache[url] = CacheEntry(
+                    data=parsed,
+                    etag=etag,
+                    max_age=max_age,
+                    stored_at=time.monotonic(),
+                )
+
+        return parsed
+
     def _make_request(
         self,
         method: str,
@@ -124,6 +175,17 @@ def _make_request(
             if filtered_params:
                 url = f"{url}?{urlencode(filtered_params)}"
 
+        # Check cache for GET requests
+        if method == "GET" and url in self._cache:
+            entry = self._cache[url]
+            if time.monotonic() - entry.stored_at < entry.max_age:
+                return entry.data
+            # Stale entry with ETag: use conditional request
+            if entry.etag:
+                if headers is None:
+                    headers = {}
+                headers["If-None-Match"] = entry.etag
+
         request_headers = self._get_headers()
         if headers:
             request_headers.update(headers)
@@ -140,16 +202,16 @@ def make_http_request() -> Any:
                 url, data=request_body, headers=request_headers, method=method
             )
             with urlopen(req) as response:
-                response_data = response.read()
-                content_type = response.headers.get("content-type", "")
-
-                if content_type == "application/vnd.apache.arrow.stream":
-                    return response_data
-                return json.loads(response_data.decode("utf-8"))
+                return self._process_response(response, url, method)
 
         try:
             return make_http_request()
         except HTTPError as e:
+            # Handle 304 Not Modified
+            if e.code == 304 and method == "GET" and url in self._cache:
+                entry = self._cache[url]
+                entry.stored_at = time.monotonic()
+                return entry.data
             # Handle 401 Unauthorized with token refresh
             if e.code == 401 and self._access_token and self._refresh_token:
                 try:
@@ -164,12 +226,7 @@ def make_http_request() -> Any:
                         url, data=request_body, headers=request_headers, method=method
                     )
                     with urlopen(req) as response:
-                        response_data = response.read()
-                        content_type = response.headers.get("content-type", "")
-
-                        if content_type == "application/vnd.apache.arrow.stream":
-                            return response_data
-                        return json.loads(response_data.decode("utf-8"))
+                        return self._process_response(response, url, method)
                 except (HTTPError, URLError, ValueError, KeyError) as refresh_error:
                     logger.warning(
                         "Token refresh failed, continuing with original request: %s",

src/cvec/http_cache.py

@@ -0,0 +1,32 @@
+"""In-memory HTTP cache for GET requests with Cache-Control and ETag support."""
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+
+@dataclass
+class CacheEntry:
+    """A cached HTTP response."""
+
+    data: Any
+    etag: Optional[str]
+    max_age: int
+    stored_at: float
+
+
+def parse_max_age(header: Optional[str]) -> Optional[int]:
+    """Parse max-age value from a Cache-Control header.
+
+    Returns:
+        The max-age value in seconds, or None if not present.
+    """
+    if header is None:
+        return None
+    for directive in header.split(","):
+        directive = directive.strip()
+        if directive.startswith("max-age="):
+            try:
+                return int(directive[len("max-age=") :])
+            except ValueError:
+                return None
+    return None