How 70-10/proxy-cache-server works
Main Components
• Client Applications – External clients making HTTP requests.
• Proxy Cache Server – The core component that intercepts requests.
• Cache Store – The file-based storage (as described in the README) where responses are maintained. Although the directory “cache/” isn’t explicitly in the file tree, its structure is described in the documentation.
• API Server – The upstream (base) API (configured by the environment variable PROXY_CACHE_SERVER_BASE_URL) from which data is fetched when a cache miss occurs.
• CLI Tools – Various commands such as “serve” to start the server and “cache-list” for listing cache entries. These are implemented under src/cli/commands/ and also include test files, ensuring proper operation.
File Structure for Architectural Clues
• The “src” directory contains the implementation logic:
• cache.ts and list-cache.ts implement the core caching functionalities.
• The “cli” subdirectory with commands (cache, serve) suggests a command-driver pattern for managing different aspects of the proxy’s operation.
• The “models” folder defines the data structures (e.g., cache-entry, cache-content) for handling cached data.
• The “bin” directory with index.ts likely acts as the entry point to the application.
• Test files are provided in both “src” and “tests” directories to ensure robust functionality.
• Configuration and environment setup (e.g., bun.lockb, tsconfig.json, and development container files) indicate an emphasis on a reliable development environment with hot reloading support.
Mapping Data Flow and Interactions
• Incoming Request Flow:
1. A client makes an HTTP request.
2. The Proxy Cache Server first checks if a corresponding cached response exists (by keying on HTTP method, path, and sorted query parameters).
3. If a hit is found, the server returns the cached response.
4. On a cache miss:
• The request is forwarded to the API Server.
• The response is received (including headers, status, and body).
• This response is then saved to the Cache Store following the directory pattern described.
• Finally, the response is sent back to the client.
• CLI Interactions:
• The “cache-list” command fetches and formats the listing of cached responses. This output helps administrators audit or debug the cache.
• The “serve” command is used to start the proxy server, possibly triggering hot-reloading based on the project’s dev container and watch configurations.
Architectural Patterns and Technology Stack
• Architectural Pattern: A proxy/middleware design that intercepts HTTP requests, combined with a caching strategy based on the file system storage.
• Design Principles: Separation of concerns between handling HTTP requests, managing cache logic, and performing CLI-based administrative tasks.
• Technologies: TypeScript (as indicated by source files and tsconfig), Bun as the runtime (noted by bun.lockb and the use of bun commands), and various Node-like development tools (dev containers, GitHub workflows).