[PD1-921] Handle compressed responses and cache

[joshuanapoli]

Reduce data egress cost and average latency by adding support for compressed responses (br, gzip, deflate) and client cache. Client cache size is limited and evicts based on the earliest response expiration deadline.

Tested in the scope of https://github.com/CVector-Energy/cvec-backend/pull/157

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the client's network efficiency by integrating support for compressed HTTP responses and implementing a robust client-side caching mechanism. These changes are designed to reduce data transfer costs and improve the average response latency for API calls by avoiding redundant data fetching and processing.

Highlights

• HTTP Compression Support: Implemented automatic decompression for gzip and deflate encoded responses, and added the Accept-Encoding header to requests to signal support for these compressions.
• Client-Side HTTP Caching: Introduced an in-memory cache for GET requests, supporting Cache-Control (max-age) and ETag headers. This includes logic for serving fresh cached data, making conditional requests (If-None-Match) for stale entries, and handling 304 Not Modified responses.

Changelog

• src/cvec/cvec.py
  • Added imports for gzip, time, zlib, CacheEntry, and parse_max_age to support compression and caching.
  • Initialized an in-memory _cache dictionary within the CVec client for storing HTTP responses.
  • Included Accept-Encoding: gzip, deflate in the default request headers to inform servers of compression capabilities.
  • Introduced _read_response method to handle reading and decompressing gzip and deflate encoded response bodies.
  • Added _parse_response_body method to parse response data based on its content type (JSON or Apache Arrow stream).
  • Implemented _process_response to orchestrate reading, decompression, parsing, and optionally caching of HTTP responses.
  • Integrated cache lookup logic into _make_request for GET requests, checking for fresh entries and preparing conditional requests with If-None-Match for stale entries.
  • Modified _make_request to handle 304 Not Modified HTTP errors by returning cached data and refreshing its stored_at timestamp.
  • Refactored the original response reading and parsing logic into the new _process_response method for cleaner code.
• src/cvec/http_cache.py
  • Created a new module to define the CacheEntry dataclass for structuring cached HTTP response data, including ETag, max-age, and storage timestamp.
  • Implemented the parse_max_age function to extract the max-age directive from Cache-Control headers.
• tests/test_http_cache.py
  • Added a new test file containing unit and integration tests for the HTTP caching functionality.
  • Included tests for parse_max_age helper function.
  • Verified CacheEntry dataclass creation and behavior.
  • Tested cache storage for new responses with max-age and ETag.
  • Confirmed fresh cache hits return cached data without making new HTTP calls.
  • Validated that stale cache entries with ETag trigger conditional requests using If-None-Match.
  • Ensured 304 Not Modified responses correctly return cached data and refresh the stored_at timestamp.
  • Confirmed POST requests are not cached.
  • Verified responses without Cache-Control max-age are not cached.
  • Tested that different URLs are cached separately.
• tests/test_http_compression.py
  • Added a new test file with tests for HTTP compression support.
  • Verified that the Accept-Encoding: gzip, deflate header is sent in requests.
  • Confirmed that gzip-compressed JSON responses are correctly decompressed.
  • Ensured that deflate-compressed JSON responses are correctly decompressed.
  • Validated that uncompressed responses are handled without modification.
  • Tested that gzip-compressed Apache Arrow stream responses are correctly decompressed.

Ignored Files

• Ignored by pattern: .github/workflows/** (1)
  • .github/workflows/license-check-python.yml

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces support for compressed responses (gzip, deflate) and client-side caching for GET requests, which is a great step towards improving performance and reducing data egress costs. The implementation is well-structured, with caching logic neatly encapsulated in a new http_cache.py module and response processing refactored into dedicated helper methods. The caching mechanism correctly handles Cache-Control: max-age, ETag/If-None-Match headers, and 304 Not Modified responses. Furthermore, the new functionality is thoroughly covered by new test suites for both compression and caching. I have one minor suggestion to make the code even more robust by preventing a potential side effect.

[alok27a]

Thank you!