ETag-based HTTP Response Caching

2.0.3 · deprecated · verified Wed Apr 22

request-etag is a small, in-memory module designed for ETag-based HTTP response caching. It manages the `If-None-Match` header automatically for subsequent GET requests to the same URL, retrieving cached bodies for 304 Not Modified responses. The package currently leverages `lru-cache` for its underlying caching mechanism, which can be configured with options like `max` size. Crucially, `request-etag` defaults to using the `request` library as its HTTP client, which has been officially deprecated and is no longer maintained since February 11th, 2020. While an alternative HTTP client can be injected, it *must* adhere to the `request` library's API signature. The package's current stable version is 2.0.3, but its reliance on a deprecated core dependency suggests a slow or inactive release cadence, limiting its suitability for new projects. Its primary differentiator is its focused, lightweight approach to abstracting ETag caching logic.

Common errors

```
My request is not being cached, even though I expect it to be.
```
cause The HTTP method used for the request was not GET. `request-etag` only caches GET requests.

fix Ensure that the HTTP request you are attempting to cache is a GET request.
```
My request is not being cached, even though I expect it to be.
```
cause The server response did not include an ETag header, which is essential for `request-etag` to identify and manage cached resources.

fix Check the server's configuration to confirm that `ETag` headers are being sent for the resources you wish to cache.
```
My request is not being cached, even though I expect it to be.
```
cause The outbound request included a non-empty `Cookie` header, which `request-etag` interprets as a reason not to cache the response.

fix Remove any `Cookie` headers from requests that you intend for `request-etag` to cache. If cookies are necessary, `request-etag` cannot cache that specific response.
```
TypeError: Cannot read properties of undefined (reading 'call') or similar when using a custom HTTP client.
```
cause The custom HTTP client provided to the `ETagRequest` constructor does not precisely match the expected API signature of the deprecated `request` library.

fix Verify that your custom HTTP client's function signature and callback arguments (specifically `(error, response, body)`) perfectly mimic those of the `request` library, as `request-etag` relies on this specific interface.

Warnings

breaking Critical security vulnerability and maintenance risk due to reliance on the deprecated 'request' library. The 'request' package is no longer maintained, meaning it won't receive security updates or bug fixes.
Fix: Do not use `request-etag` in new projects. For existing projects, it is imperative to provide an alternative, maintained HTTP client (e.g., `axios`, `node-fetch`, or `undici` wrapped to match `request`'s API) to the `ETagRequest` constructor. Consider migrating to a more modern and actively maintained caching solution.
gotcha The module is explicitly designed for GET requests only; other HTTP methods (POST, PUT, DELETE, etc.) will not be cached.
Fix: Ensure all requests intended for caching are GET requests. For other methods, `request-etag` will not provide caching benefits.
gotcha Caching will not occur if the HTTP response lacks an ETag header, or if the request includes a non-empty `Cookie` header.
Fix: Verify that your server is configured to send `ETag` headers for cacheable resources. Avoid sending `Cookie` headers with requests if you intend `request-etag` to cache their responses.
gotcha The underlying HTTP client provided to `ETagRequest` must strictly adhere to the API signature of the deprecated `request` library.
Fix: When overriding the default client, ensure your custom client function accepts `(url, callback)` or `(options, callback)` and specifically uses the `(error, response, body)` callback signature, as expected by `request-etag`.
gotcha Responses with bodies larger than the configured `max` cache size (set in `cacheConfig`) will not be stored in the cache.
Fix: Adjust the `max` configuration option in `cacheConfig` to accommodate the maximum expected size of the response bodies you wish to cache. If bodies exceed this, they will be fetched every time.

Install

npm install request-etag npm
yarn add request-etag yarn
pnpm add request-etag pnpm

Imports

ETagRequest
wrong:
```
import ETagRequest from 'request-etag';
```
correct:
```
const ETagRequest = require('request-etag');
```
The package uses CommonJS `require` syntax for its default export. Direct ESM `import` is not supported without a CommonJS wrapper or bundler configuration due to its age.
ETagRequest constructor
wrong:
```
const eTagRequest = new ETagRequest(cacheConfig);
```
correct:
```
const eTagRequest = new ETagRequest(cacheConfig, modernHttpClient);
```
The default HTTP client is the deprecated `request` library. It is strongly recommended to provide an alternative, modern, and maintained HTTP client (wrapped to match `request`'s API signature) as the second argument to the constructor.
Callback signature
```
eTagRequest(url, function (error, response, body) { /* ... */ });
```
The callback function adheres to the `(error, response, body)` signature, mimicking the `request` library's callback pattern for consistent handling of HTTP responses.

Quickstart

This quickstart demonstrates how to initialize `request-etag` with a cache configuration and perform ETag-aware GET requests, showing the behavior of both initial 200 OK and subsequent 304 Not Modified responses with cached bodies.

const ETagRequest = require('request-etag');
const request = require('request'); // In a real application, use a modern HTTP client compatible with 'request' API

// Configure the cache, e.g., max 10MB to store response bodies
const cacheConfig = {
    max: 10 * 1024 * 1024 // 10MB limit for the cache
};

// Initialize ETagRequest. In a production environment, 'request' should be replaced 
// with a modern, maintained HTTP client that provides the same API signature.
const eTagRequest = new ETagRequest(cacheConfig, request);

// Define a target URL for caching
const urlToCache = 'https://www.google.com/'; 

console.log('--- First request (expecting 200 OK) ---');
eTagRequest(urlToCache, function (error, response, body) {
    if (error) {
        console.error('Initial request failed:', error);
        return;
    }

    if (response.statusCode === 200) {
        console.log(`Status: ${response.statusCode} - Body retrieved from actual HTTP response.`);
        // console.log(body.substring(0, 100) + '...'); // Log a snippet of the body
    } else {
        console.log(`Initial request unexpected status: ${response.statusCode}`);
    }

    console.log('\n--- Second request (expecting 304 Not Modified from cache) ---');
    eTagRequest(urlToCache, function (error2, response2, body2) {
        if (error2) {
            console.error('Second request failed:', error2);
            return;
        }

        if (response2.statusCode === 304) {
            console.log(`Status: ${response2.statusCode} - Body retrieved from internal cache.`);
            // console.log(body2.substring(0, 100) + '...'); // Log a snippet of the cached body
        } else if (response2.statusCode === 200) {
            console.log(`Status: ${response2.statusCode} - Unexpected 200 on second request, cache might be bypassed.`);
        } else {
            console.log(`Second request unexpected status: ${response2.statusCode}`);
        }
    });
});

view raw JSON →