shared-http-cache 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SorinGFS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/index.js

@@ -0,0 +1,116 @@
+'use strict';
+// utility for fetching multiple URLs with HTTP caching management
+const cacache = require('cacache');
+// cacache wrapper
+class SharedHttpCache {
+    constructor(options = {}) {
+        Object.assign(this, { cacheDir: '.cache', awaitStorage: false }, options);
+        this.store = cacache;
+    }
+    /**
+     * Fetch multiple resources with HTTP cache support.
+     * @param {Array<{url:string,integrity?:string,options?:RequestInit,callback:(result:{buffer:Buffer,headers:Headers,fromCache:boolean})=>void}>} requests
+     * @returns {Promise<this|{url: string, headers?: Headers, error: Error }[]>}
+     * @see [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit), [Headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers) MDN references
+     */
+    async fetch(requests) {
+        const errors = [];
+        const parseHeader = (string) => {
+            if (!string || typeof string !== 'string') return {};
+            const result = {};
+            for (const part of string.split(',').reverse()) {
+                const [key, value] = part.trim().split('=');
+                result[key] = value === undefined ? true : Number.isNaN(+value) ? value : +value;
+            }
+            return result;
+        };
+        const isFresh = (file, requestCacheControl = {}) => {
+            const storedCacheControl = parseHeader(file.metadata.headers['cache-control']);
+            const previousAge = Number(file.metadata.headers['age'] || 0);
+            const currentAge = previousAge + (Date.now() - file.time) / 1000;
+            let lifetime; // Response freshness lifetime (s-maxage > max-age > Expires)
+            if (storedCacheControl['s-maxage'] !== undefined) lifetime = storedCacheControl['s-maxage'];
+            else if (storedCacheControl['max-age'] !== undefined) lifetime = storedCacheControl['max-age'];
+            else {
+                const expires = Date.parse(file.metadata.headers['expires'] || '');
+                lifetime = !Number.isNaN(expires) ? Math.max(0, (expires - file.time) / 1000) : 0;
+            }
+            if (requestCacheControl['max-age'] !== undefined) lifetime = Math.min(lifetime, requestCacheControl['max-age']);
+            const remainingLifetime = lifetime - currentAge;
+            if (requestCacheControl['min-fresh'] !== undefined && remainingLifetime < requestCacheControl['min-fresh']) return false;
+            if (remainingLifetime >= 0) return true; // not stale
+            const maxStale = requestCacheControl['max-stale'];
+            if (maxStale !== undefined) {
+                if (maxStale === true) return true; // unspecified max-stale → accept any staleness
+                if (currentAge <= lifetime + maxStale) return true;
+            }
+            return false;
+        };
+        await Promise.all(
+            requests.map(async (request) => {
+                const { url, options = {}, integrity, callback } = request;
+                if (!options.method) options.method = 'GET';
+                if (!options.headers) options.headers = {};
+                Object.keys(options.headers).some((key) => key.toLowerCase() === 'cache-control' && (options.headers['cache-control'] = options.headers[key]));
+                Object.keys(options.headers).some((key) => key.toLowerCase() === 'authorization' && (options.headers['authorization'] = options.headers[key]));
+                // prettier-ignore
+                let response, buffer, headers, fromCache = true;
+                try {
+                    const requestCacheControl = parseHeader(options.headers['cache-control']);
+                    const file = await this.store.get.info(this.cacheDir, url);
+                    const isFreshFile = file && isFresh(file, requestCacheControl);
+                    if (file) {
+                        const responseCacheControl = parseHeader(file.metadata.headers['cache-control']);
+                        if (!isFreshFile && requestCacheControl['only-if-cached']) throw new Error('HTTP error! status: 504 Only-If-Cached');
+                        if (!isFreshFile || requestCacheControl['no-cache'] || responseCacheControl['no-cache']) fromCache = false;
+                        if (requestCacheControl['max-stale'] && (responseCacheControl['must-revalidate'] || responseCacheControl['proxy-revalidate'])) fromCache = false;
+                        if (fromCache) {
+                            buffer = (await this.store.get(this.cacheDir, url)).data;
+                            headers = file.metadata.headers;
+                        }
+                    } else {
+                        fromCache = false;
+                        if (requestCacheControl['only-if-cached']) throw new Error('HTTP error! status: 504 Only-If-Cached');
+                    }
+                    if (!fromCache) {
+                        if (file && file.metadata.headers['etag']) options.headers['if-none-match'] = file.metadata.headers['etag'];
+                        if (file && file.metadata.headers['last-modified']) options.headers['if-modified-since'] = file.metadata.headers['last-modified'];
+                        response = await fetch(url, options);
+                        if (response.status === 304) {
+                            buffer = (await this.store.get(this.cacheDir, url)).data;
+                            headers = { ...file.metadata.headers, ...Object.fromEntries(response.headers.entries()) };
+                            fromCache = true;
+                        } else if (response.ok) {
+                            buffer = Buffer.from(await response.arrayBuffer());
+                            headers = Object.fromEntries(response.headers.entries());
+                        } else {
+                            if (response.status === 410) {
+                                this.store.rm.entry(this.cacheDir, url, { removeFully: true });
+                                this.store.rm.content(this.cacheDir, file.integrity);
+                            }
+                            throw new Error(`HTTP error! status: ${response.status}`);
+                        }
+                    }
+                    // chance to preform content validation before saving it to disk
+                    if (typeof callback === 'function') callback({ buffer, headers, fromCache });
+                    if (!fromCache || response?.status === 304) {
+                        const responseCacheControl = parseHeader(headers['cache-control']);
+                        if (options.method !== 'GET') return;
+                        if (responseCacheControl['no-store'] || responseCacheControl['private']) return;
+                        if (requestCacheControl['no-store'] || requestCacheControl['authorization']) return;
+                        const store = async () => {
+                            await this.store.rm.entry(this.cacheDir, url, { removeFully: true });
+                            await this.store.put(this.cacheDir, url, buffer, integrity ? { metadata: { headers }, integrity } : { metadata: { headers } });
+                        };
+                        this.awaitStorage ? await store() : store();
+                    }
+                } catch (error) {
+                    errors.push({ url, headers, error });
+                }
+            }),
+        );
+        return errors.length ? Promise.reject(errors) : Promise.resolve(this);
+    }
+}
+// export
+module.exports = SharedHttpCache;

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "shared-http-cache",
+  "version": "1.0.0",
+  "description": "Node.Js Utility for fetching multiple HTTP resources with browser-like cache management.",
+  "keywords": [
+    "http-cache",
+    "cache",
+    "cacache",
+    "rfc9111",
+    "cache-manager",
+    "http-cache-semantics"
+  ],
+  "homepage": "https://github.com/SorinGFS/shared-http-cache#readme",
+  "bugs": {
+    "url": "https://github.com/SorinGFS/shared-http-cache/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SorinGFS/shared-http-cache.git"
+  },
+  "license": "MIT",
+  "author": "SorinGFS",
+  "type": "commonjs",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "cacache": "^20.0.3"
+  }
+}

package/readme.md

@@ -0,0 +1,348 @@
+---
+
+title: Shared HTTP Cache
+
+description: Node.Js Utility for fetching multiple HTTP resources with browser-like cache management.
+
+---
+
+## Overview
+
+### Shared HTTP Cache Semantics
+
+This implementation models a shared HTTP cache that follows the semantics defined in [RFC 9111](https://datatracker.ietf.org/doc/html/rfc9111.html), with explicitly documented assumptions and controlled decisions. It uses a content-addressed cache through [cacache](https://github.com/npm/cacache) providing lockless, high-concurrency cache access, that along with the downloaded `content` is storing the associated `HTTP response headers` in the cache metadata. Overall, the design aims to provide `browser-like` caching behavior in a `Node.js` environment.
+
+### Scope and assumptions
+
+The cache is shared (not private) and applies shared-cache rules.
+
+- Privacy factors are considered while storing responses (`safe method` constraints, request `authorization`, response `cache-control="private"`).
+- No heuristic freshness is used.
+- Time calculations rely exclusively on locally recorded timestamps, not on server-provided `Date`.
+- Storage and eviction are deterministic; no background or implicit cleanup is assumed.
+
+### Request initialization and cache lookup
+
+Each request begins by determining whether a cached response exists.
+
+If no cached entry exists:
+
+- If the request requires `only-if-cached`, the cache returns a `504 HTTP status`.
+- Otherwise, the request is sent to the origin server.
+
+### Cache-control exclusions
+
+Two cache-control directives may short-circuit normal cache usage:
+
+- `no-cache` (request or response): cached data cannot be used without revalidation.
+- `no-store` (request or response): the response must not be stored.
+  When `no-store` applies, the response is served directly and bypasses storage entirely.
+
+### Freshness evaluation
+
+If a cached response exists and is not excluded, strict freshness is evaluated first, without considering `max-stale`.
+
+Freshness lifetime is computed from response headers:
+
+- `s-maxage` first, then `max-age`, if present
+- otherwise `Expires`, if present
+
+Current age is derived from local metadata:
+
+```excel-formula
+currentAge = now − storedTime + incomingAge
+```
+
+The `incomingAge` is taken from the stored response `age` header, if present.
+
+Remaining freshness:
+
+```excel-formula
+remainingFreshness = freshnessLifetime − currentAge
+```
+
+If `remainingFreshness ≥ 0`, the response is served as fresh.
+
+### Stale handling
+
+If the response is stale, `max-stale` on the request is evaluated.
+
+If `max-stale` value is unspecified → accept any staleness; otherwise the response is acceptable if:
+
+```excel-formula
+currentAge − freshnessLifetime ≤ max-stale
+```
+
+If staleness exceeds the acceptable `max-stale`, the cache proceeds toward revalidation or origin fetch.
+
+### Revalidation constraints
+
+Even if `max-stale` allows use of stale data:
+
+- `must-revalidate` or `proxy-revalidate` on the response forbids serving stale.
+- In that case, the cache must revalidate or fetch from the origin.
+- If `only-if-cached` also applies, the cache returns a `504 HTTP status` instead of revalidating.
+- If no revalidation constraint applies, stale content may be served.
+
+On revalidation, if the cached content includes `ETag` or `Last-Modified` automatically `If-None-Match` and `If-Modified-Since` headers are added to the request. Revalidated entries are explicitly replaced during each successful fetch to avoid unbounded growth in the index.
+
+### Origin request outcomes
+
+When a request is sent to the origin:
+
+- `2xx`: response is stored (unless restricted) and served.
+- `304 Not Modified`: cached metadata is updated; response is served as fresh.
+- `410 Gone`: cached entry is removed.
+- Other responses: treated as errors and returned directly.
+
+### Cleanup behavior
+
+The cache does not:
+
+- apply heuristic freshness
+- perform automatic eviction based on staleness
+
+However:
+
+- a `410 Gone` response explicitly removes the cached entry.
+- additional cleanup mechanisms are available to the user via the underlying storage system.
+
+## State diagram
+
+The accompanying state diagram represents the full decision flow:
+
+![Diagram](./docs/images/cache.png)
+
+Legend
+
+1. `no-cache` may appear on request or response and always requires revalidation.
+2. `no-store` may appear on request or response; [privacy factors](#scope-and-assumptions) are considered.
+3. [Freshness evaluation](#freshness-evaluation) excludes `max-stale` that is evaluated only after strict freshness fails.
+4. `410 Gone` [cleanup](#cleanup-behavior) is an explicit design choice to keep the cache coherent; no heuristic eviction is used.
+
+## Install
+
+```bash
+npm i shared-http-cache
+```
+
+## Usage
+
+### Init
+
+```ts
+new SharedHttpCache(options?) -> SharedHttpCache
+```
+
+### Create a shared HTTP cache instance.
+
+```js
+const SharedHttpCache = require('shared-http-cache');
+const sharedHttpCache = new SharedHttpCache();
+```
+
+### Init options
+
+```ts
+new SharedHttpCache({ cacheDir?: string, awaitStorage?: boolean }) -> SharedHttpCache
+```
+
+- `cacheDir`: cache storage directory (default `.cache`)
+- `awaitStorage`: await cache writes before continuing (default `false`)
+
+```js
+const sharedHttpCache = new SharedHttpCache({
+    cacheDir: '/tmp/http-cache',
+    awaitStorage: true,
+});
+```
+
+### Fetch
+
+`fetch` is the only method available. On success, `fetch` resolves to the same instance, enabling chained workflows.
+
+```ts
+sharedHttpCache.fetch(requests) -> Promise<this | Error[]>
+```
+
+**Syntax:**
+```ts
+fetch([{ url: string, integrity?: string, options?: RequestInit, callback?: function }]) -> Promise<this | Error[]>
+```
+
+### Simple fetch call
+
+```js
+await sharedHttpCache.fetch([
+    {
+        url: 'https://example.com/data.txt',
+        callback: ({ buffer }) => {
+            console.log(buffer.toString());
+        },
+    },
+]);
+```
+
+### Fetch with callback and error handling
+
+Errors encountered during fetches are collected, and the returned `promise` either `resolves` with the instance itself for successful fetches or `rejects` with a list of `errors` for failed requests.
+
+The response is converted into a [Buffer](https://nodejs.org/api/buffer.html) served to `callback`, then stored in the `cache` along with the `response headers`. For any other status code, unless `stale-if-error` is present, an `error` is thrown.
+
+```ts
+callback({ buffer: Buffer, headers: Headers, fromCache: boolean }) -> void
+```
+
+The `callback` provided for each request is executed before storing new content, allowing implementers to inspect, transform or validate the data before it's cached. The errors thrown by the `callback` are also catched and stored in the `errors` delivered by the `Promise.reject()`.
+
+```js
+await sharedHttpCache
+    .fetch([
+        {
+            url: 'https://example.com/data.txt',
+            callback: ({ buffer, headers, fromCache }) => {
+                console.log(buffer.toString());
+                console.log(headers);
+                console.log(fromCache);
+            },
+        },
+    ])
+    .catch((errors) => {
+        errors.forEach((entry) => {
+            console.error(entry.url, entry.error);
+        });
+    });
+```
+
+### Fetch with integrity
+
+```js
+await sharedHttpCache.fetch([
+    {
+        url: 'https://example.com/file.bin',
+        integrity: 'sha256-abcdef...',
+        callback: ({ buffer }) => {
+            console.log(buffer.length);
+        },
+    },
+]);
+```
+
+**Note:** `integrity `affects storage, not `callback` execution.
+
+### Fetch options
+
+```ts
+fetch.options -> RequestInit
+```
+
+`fetch.options` are passed directly to [node:fetch](https://nodejs.org/api/globals.html#fetch).
+They follow standard [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit) semantics ([method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), [credentials](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit#credentials), [headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers), [mode](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit#mode), [cache-mode](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit#cache), etc.).
+
+### Fetch with Accept: application/json
+
+```js
+await sharedHttpCache.fetch([
+    {
+        url: 'https://api.example.com/list',
+        options: {
+            headers: {
+                Accept: 'application/json',
+            },
+        },
+        callback: ({ buffer }) => {
+            console.log(buffer.toString());
+        },
+    },
+]);
+```
+
+### Fetch with Cache-Control: no-cache
+
+```js
+await sharedHttpCache.fetch([
+    {
+        url: 'https://example.com/data',
+        options: {
+            headers: {
+                'Cache-Control': 'no-cache',
+            },
+        },
+        callback: ({ fromCache }) => {
+            console.log(fromCache);
+        },
+    },
+]);
+```
+
+### Fetch with Cache-Control: max-stale
+
+```js
+await sharedHttpCache.fetch([
+    {
+        url: 'https://example.com/data',
+        options: {
+            headers: {
+                'Cache-Control': 'max-stale=3600',
+            },
+        },
+        callback: ({ fromCache }) => {
+            console.log(fromCache);
+        },
+    },
+]);
+```
+
+### Fetch with HEAD method
+
+```js
+await sharedHttpCache.fetch([
+    {
+        url: 'https://example.com/resource',
+        options: {
+            method: 'HEAD',
+        },
+        callback: ({ headers }) => {
+            console.log(headers);
+        },
+    },
+]);
+```
+
+### Storage management
+
+The underlying cache store (`cacache`) is exposed directly.
+
+```ts
+sharedHttpCache.store -> cacache
+```
+
+**Compacting (example with await)**
+
+```ts
+sharedHttpCache.store.verify(cacheDir) -> Promise<Object>
+```
+
+```js
+await sharedHttpCache.store.verify(sharedHttpCache.cacheDir);
+```
+
+**Listing (example with promise)**
+
+```js
+sharedHttpCache
+    .fetch(requests)
+    .then((sharedHttpCache) => sharedHttpCache.store.ls(sharedHttpCache.cacheDir))
+    .then(console.log)
+    .catch((errors) => console.error('Errors:', errors));
+```
+
+Other available operations
+
+- sharedHttpCache.store.put(...)
+- sharedHttpCache.store.get(...)
+- sharedHttpCache.store.get.info(...)
+- sharedHttpCache.store.rm.entry(...)
+- sharedHttpCache.store.rm.content(...)
+
+See full list of [cacache options](https://github.com/npm/cacache?tab=readme-ov-file#api).