1223 lines
40 KiB
JavaScript
1223 lines
40 KiB
JavaScript
'use strict'
|
|
|
|
const util = require('../core/util')
|
|
const { kRedirectCacheControl } = require('../core/symbols')
|
|
const {
|
|
parseCacheControlHeader,
|
|
hasInvalidCacheControlDirective,
|
|
parseVaryHeader,
|
|
hasVaryStar,
|
|
isInvalidOrWildcardVaryHeader,
|
|
isEtagUsable
|
|
} = require('../util/cache')
|
|
|
|
/**
|
|
* A suppressed redirect hop recorded by the redirect handler. Carried on
|
|
* {@link kRedirectCacheControl} and inspected by the cache handler before the
|
|
* final response is stored under the original request key.
|
|
*
|
|
* @typedef {object} RedirectHop
|
|
* @property {number} statusCode The hop's response status code (e.g. 302).
|
|
* @property {import('../../types/header.d.ts').IncomingHttpHeaders} headers The hop's response headers.
|
|
* @property {number} receivedAt The time the hop's response headers were received.
|
|
*/
|
|
const { parseHttpDate } = require('../util/date.js')
|
|
|
|
function noop () {}
|
|
|
|
class CacheController {
|
|
#blocked = false
|
|
#downstreamPaused = false
|
|
|
|
constructor (target) {
|
|
this.target = target
|
|
}
|
|
|
|
block () {
|
|
this.#blocked = true
|
|
}
|
|
|
|
release () {
|
|
this.#blocked = false
|
|
if (!this.#downstreamPaused) {
|
|
this.target.resume()
|
|
}
|
|
}
|
|
|
|
pause () {
|
|
this.#downstreamPaused = true
|
|
this.target.pause()
|
|
}
|
|
|
|
resume () {
|
|
this.#downstreamPaused = false
|
|
if (!this.#blocked) {
|
|
this.target.resume()
|
|
}
|
|
}
|
|
|
|
abort (reason) {
|
|
this.target.abort(reason)
|
|
}
|
|
|
|
get paused () { return this.#downstreamPaused }
|
|
get aborted () { return this.target.aborted }
|
|
get reason () { return this.target.reason }
|
|
get rawHeaders () { return this.target.rawHeaders }
|
|
set rawHeaders (value) { this.target.rawHeaders = value }
|
|
get rawTrailers () { return this.target.rawTrailers }
|
|
set rawTrailers (value) { this.target.rawTrailers = value }
|
|
}
|
|
|
|
/**
|
|
* @param {string | URL} a
|
|
* @param {string | URL} b
|
|
* @returns {boolean}
|
|
*/
|
|
function sameOrigin (a, b) {
|
|
try {
|
|
return new URL(String(a)).origin === new URL(String(b)).origin
|
|
} catch {
|
|
return String(a) === String(b)
|
|
}
|
|
}
|
|
|
|
// Status codes that we can use some heuristics on to cache
|
|
const HEURISTICALLY_CACHEABLE_STATUS_CODES = [
|
|
200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414, 501
|
|
]
|
|
|
|
// Status codes which semantic is not handled by the cache
|
|
// https://datatracker.ietf.org/doc/html/rfc9111#section-3
|
|
// This list should not grow beyond 206 unless the RFC is updated
|
|
// by a newer one including more. Please introduce another list if
|
|
// implementing caching of responses with the 'must-understand' directive.
|
|
const NOT_UNDERSTOOD_STATUS_CODES = [
|
|
206
|
|
]
|
|
|
|
const MAX_RESPONSE_AGE = 2147483647000
|
|
|
|
// Retention for revalidation-only entries (zero freshness lifetime but a
|
|
// validator present); each successful revalidation re-stores the entry.
|
|
const REVALIDATION_ONLY_RETENTION = 86400000 // 24 hours
|
|
|
|
function trimOWS (value) {
|
|
return value.replace(/^[\t ]+|[\t ]+$/g, '')
|
|
}
|
|
|
|
function arrayIncludes (array, value) {
|
|
for (let i = 0; i < array.length; i++) {
|
|
if (array[i] === value) {
|
|
return true
|
|
}
|
|
}
|
|
|
|
return false
|
|
}
|
|
|
|
function appendVaryValues (target, varyValue) {
|
|
if (Array.isArray(varyValue)) {
|
|
for (let i = 0; i < varyValue.length; i++) {
|
|
target.push(varyValue[i])
|
|
}
|
|
} else if (varyValue != null) {
|
|
target.push(varyValue)
|
|
}
|
|
}
|
|
|
|
function appendConnectionHeaderTokens (headersToRemove, connectionHeader) {
|
|
const values = Array.isArray(connectionHeader) ? connectionHeader : [connectionHeader]
|
|
|
|
for (let i = 0; i < values.length; i++) {
|
|
const tokens = values[i].split(',')
|
|
for (let j = 0; j < tokens.length; j++) {
|
|
headersToRemove.push(trimOWS(tokens[j]).toLowerCase())
|
|
}
|
|
}
|
|
}
|
|
|
|
function getSameOriginPath (cacheKey, location) {
|
|
if (typeof location !== 'string') {
|
|
return undefined
|
|
}
|
|
|
|
let originUrl
|
|
let requestUrl
|
|
let locationUrl
|
|
try {
|
|
originUrl = new URL(cacheKey.origin)
|
|
requestUrl = new URL(cacheKey.path, originUrl)
|
|
locationUrl = new URL(location, requestUrl)
|
|
} catch {
|
|
return undefined
|
|
}
|
|
|
|
if (locationUrl.origin !== originUrl.origin) {
|
|
return undefined
|
|
}
|
|
|
|
return locationUrl.pathname + locationUrl.search
|
|
}
|
|
|
|
function deleteCachedUri (store, cacheKey, path) {
|
|
deleteCachedValue(store, {
|
|
...cacheKey,
|
|
path
|
|
})
|
|
|
|
for (let i = 0; i < util.safeHTTPMethods.length; i++) {
|
|
const method = util.safeHTTPMethods[i]
|
|
if (method !== cacheKey.method) {
|
|
deleteCachedValue(store, {
|
|
...cacheKey,
|
|
method,
|
|
path
|
|
})
|
|
}
|
|
}
|
|
}
|
|
|
|
function deleteLocationTargets (store, cacheKey, headerValue) {
|
|
if (headerValue === undefined) {
|
|
return
|
|
}
|
|
|
|
const values = Array.isArray(headerValue) ? headerValue : [headerValue]
|
|
for (let i = 0; i < values.length; i++) {
|
|
const path = getSameOriginPath(cacheKey, values[i])
|
|
if (path !== undefined) {
|
|
deleteCachedUri(store, cacheKey, path)
|
|
}
|
|
}
|
|
}
|
|
|
|
function invalidateUnsafeRequest (store, cacheKey, resHeaders) {
|
|
deleteCachedUri(store, cacheKey, cacheKey.path)
|
|
deleteLocationTargets(store, cacheKey, resHeaders.location)
|
|
deleteLocationTargets(store, cacheKey, resHeaders['content-location'])
|
|
}
|
|
|
|
/**
|
|
* Whether the original request carried a credential that is not reflected in
|
|
* the cache key. The memory/sqlite stores key an entry on origin, method, path
|
|
* and `vary` only, so a credentialed request that is redirected to a resource
|
|
* that varies per principal must not be stored under the original (alias) key:
|
|
* a later caller would be served the first principal's body. The set mirrors the
|
|
* request credentials the redirect handler strips across origins (`authorization`,
|
|
* `cookie`, `proxy-authorization`).
|
|
*
|
|
* @param {import('../../types/header.d.ts').IncomingHttpHeaders | undefined} headers
|
|
* @returns {boolean}
|
|
*/
|
|
function requestCarriesCredentials (headers) {
|
|
return headers != null && (
|
|
Object.hasOwn(headers, 'authorization') ||
|
|
Object.hasOwn(headers, 'cookie') ||
|
|
Object.hasOwn(headers, 'proxy-authorization')
|
|
)
|
|
}
|
|
/**
|
|
* @typedef {import('../../types/dispatcher.d.ts').default.DispatchHandler} DispatchHandler
|
|
*
|
|
* @implements {DispatchHandler}
|
|
*/
|
|
class CacheHandler {
|
|
/**
|
|
* @type {import('../../types/cache-interceptor.d.ts').default.CacheKey}
|
|
*/
|
|
#cacheKey
|
|
|
|
/**
|
|
* @type {import('../../types/cache-interceptor.d.ts').default.CacheHandlerOptions['type']}
|
|
*/
|
|
#cacheType
|
|
|
|
/**
|
|
* @type {number | undefined}
|
|
*/
|
|
#cacheByDefault
|
|
|
|
/**
|
|
* @type {import('../../types/cache-interceptor.d.ts').default.CacheStore}
|
|
*/
|
|
#store
|
|
|
|
/**
|
|
* @type {import('../../types/dispatcher.d.ts').default.DispatchHandler}
|
|
*/
|
|
#handler
|
|
|
|
/**
|
|
* @type {CacheController | undefined}
|
|
*/
|
|
#downstreamController
|
|
|
|
/**
|
|
* @type {import('node:stream').Writable | undefined}
|
|
*/
|
|
#writeStream
|
|
|
|
/**
|
|
* The URLs visited while following redirects, shared by reference from the
|
|
* redirect handler through the request context. Carries the suppressed hops'
|
|
* status/headers under {@link kRedirectCacheControl}.
|
|
* @type {URL[] | undefined}
|
|
*/
|
|
#history
|
|
|
|
/**
|
|
* @param {import('../../types/cache-interceptor.d.ts').default.CacheHandlerOptions} opts
|
|
* @param {import('../../types/cache-interceptor.d.ts').default.CacheKey} cacheKey
|
|
* @param {import('../../types/dispatcher.d.ts').default.DispatchHandler} handler
|
|
*/
|
|
constructor ({ store, type, cacheByDefault }, cacheKey, handler) {
|
|
this.#store = store
|
|
this.#cacheType = type
|
|
this.#cacheByDefault = cacheByDefault
|
|
this.#cacheKey = cacheKey
|
|
this.#handler = handler
|
|
}
|
|
|
|
onRequestStart (controller, context) {
|
|
this.#writeStream?.destroy()
|
|
this.#writeStream = undefined
|
|
this.#downstreamController = new CacheController(controller)
|
|
// The redirect handler threads the list of visited URLs through the
|
|
// handler-chain context. Keep a reference to it (it is mutated as redirects
|
|
// are followed) so onResponseStart can tell which request actually produced
|
|
// the response. Unlike the request options object, this reference is not
|
|
// broken by an interceptor that copies the options between the cache and
|
|
// the redirect.
|
|
this.#history = context?.history
|
|
this.#handler.onRequestStart?.(this.#downstreamController, context)
|
|
}
|
|
|
|
onBodySent (chunk) {
|
|
this.#handler.onBodySent?.(chunk)
|
|
}
|
|
|
|
onRequestSent () {
|
|
this.#handler.onRequestSent?.()
|
|
}
|
|
|
|
onRequestUpgrade (_controller, statusCode, headers, socket) {
|
|
this.#handler.onRequestUpgrade?.(this.#downstreamController, statusCode, headers, socket)
|
|
}
|
|
|
|
/**
|
|
* @param {import('../../types/dispatcher.d.ts').default.DispatchController} controller
|
|
* @param {number} statusCode
|
|
* @param {import('../../types/header.d.ts').IncomingHttpHeaders} resHeaders
|
|
* @param {string} statusMessage
|
|
*/
|
|
onResponseStart (
|
|
controller,
|
|
statusCode,
|
|
resHeaders,
|
|
statusMessage
|
|
) {
|
|
const downstreamOnHeaders = () =>
|
|
this.#handler.onResponseStart?.(
|
|
this.#downstreamController,
|
|
statusCode,
|
|
resHeaders,
|
|
statusMessage
|
|
)
|
|
const handler = this
|
|
|
|
if (
|
|
!arrayIncludes(util.safeHTTPMethods, this.#cacheKey.method) &&
|
|
statusCode >= 200 &&
|
|
statusCode <= 399
|
|
) {
|
|
// Successful response to an unsafe method, delete it from cache
|
|
// https://www.rfc-editor.org/rfc/rfc9111.html#name-invalidating-stored-response
|
|
invalidateUnsafeRequest(this.#store, this.#cacheKey, resHeaders)
|
|
return downstreamOnHeaders()
|
|
}
|
|
|
|
// A credential-bearing request that was redirected must not have the final
|
|
// hop's response stored under the original request's key. The cache key
|
|
// does not include the credential, and the redirect target may vary per
|
|
// principal (e.g. `/me` -> `/profile/{user}`), so replaying the body under
|
|
// the alias key would leak one principal's data to another — or to an
|
|
// unauthenticated caller — from a shared cache. The final hop's permissive
|
|
// cache-control (e.g. `public`) does not authorize this: the credential was
|
|
// presented to the original hop, not the resource that actually produced
|
|
// the body. Fail closed. A history with more than one entry means at least
|
|
// one redirect was actually followed (a single non-redirected hop records
|
|
// exactly one entry), so a plain revalidation is not mistaken for a redirect.
|
|
if (
|
|
this.#history && this.#history.length > 1 &&
|
|
requestCarriesCredentials(this.#cacheKey.headers)
|
|
) {
|
|
return downstreamOnHeaders()
|
|
}
|
|
|
|
// A cross-origin redirect can change the origin that actually produced the
|
|
// final response. Keying that response on the original (trusted) origin
|
|
// would let a redirect target control an entry for a URL the application
|
|
// trusts. Every hop in the redirect chain must stay on the cache key's
|
|
// origin. An intermediate cross-origin hop can bounce back to the trusted
|
|
// origin (or to any cacheable asset there) even when the final response
|
|
// comes from the trusted origin, so checking only the final URL is not
|
|
// enough.
|
|
if (this.#history && this.#history.length > 0) {
|
|
for (const hopUrl of this.#history) {
|
|
if (!sameOrigin(hopUrl.origin, this.#cacheKey.origin)) {
|
|
return downstreamOnHeaders()
|
|
}
|
|
}
|
|
}
|
|
|
|
// A redirect hop that is not forwarded can still carry a storage policy
|
|
// (for example `no-store`, `private` for a shared cache, `no-cache`,
|
|
// `must-revalidate`, zero freshness, or `Vary: *`) that the final response
|
|
// body does not inherit. Honor it, otherwise a redirect that must not be
|
|
// stored (or that selects a private/authenticated target) could be
|
|
// laundered into a cacheable final response under the original key.
|
|
const now = Date.now()
|
|
const redirectHopInfo = this.#history?.[kRedirectCacheControl]
|
|
const redirectPolicy = redirectHopInfo?.length > 0
|
|
? getRedirectPolicy(
|
|
this.#cacheType,
|
|
this.#cacheKey.method,
|
|
redirectHopInfo,
|
|
this.#cacheKey.headers,
|
|
this.#cacheByDefault,
|
|
now
|
|
)
|
|
: undefined
|
|
if (redirectHopInfo?.length > 0 && redirectPolicy === undefined) {
|
|
return downstreamOnHeaders()
|
|
}
|
|
|
|
const cacheControlHeader = resHeaders['cache-control']
|
|
const cacheControlDirectives = cacheControlHeader ? parseCacheControlHeader(cacheControlHeader) : {}
|
|
|
|
if (revalidationResponseDisallowsCachedReuse(this.#cacheType, resHeaders, cacheControlDirectives)) {
|
|
deleteCachedValue(this.#store, this.#cacheKey)
|
|
return downstreamOnHeaders()
|
|
}
|
|
|
|
const heuristicallyCacheable = resHeaders['last-modified'] && arrayIncludes(HEURISTICALLY_CACHEABLE_STATUS_CODES, statusCode)
|
|
if (
|
|
!cacheControlHeader &&
|
|
!resHeaders['expires'] &&
|
|
!heuristicallyCacheable &&
|
|
!this.#cacheByDefault
|
|
) {
|
|
if (statusCode === 304 && resHeaders.vary && isInvalidOrWildcardVaryHeader(resHeaders.vary)) {
|
|
deleteCachedValue(this.#store, this.#cacheKey)
|
|
}
|
|
|
|
// Don't have anything to tell us this response is cacheable and we're not
|
|
// caching by default
|
|
return downstreamOnHeaders()
|
|
}
|
|
|
|
if (!canCacheResponse(this.#cacheType, this.#cacheKey.method, statusCode, resHeaders, cacheControlDirectives, this.#cacheKey.headers)) {
|
|
if (statusCode === 304 && (cacheControlHeader || revalidationResponseDisallowsCachedReuse(this.#cacheType, resHeaders, cacheControlDirectives))) {
|
|
deleteCachedValue(this.#store, this.#cacheKey)
|
|
}
|
|
|
|
return downstreamOnHeaders()
|
|
}
|
|
|
|
const resAge = Object.hasOwn(resHeaders, 'age') ? getAge(resHeaders.age) : undefined
|
|
if (resAge !== undefined && resAge >= MAX_RESPONSE_AGE) {
|
|
// Response considered stale
|
|
deleteCachedValueIfNotModified(statusCode, this.#store, this.#cacheKey)
|
|
return downstreamOnHeaders()
|
|
}
|
|
|
|
const resDate = Object.hasOwn(resHeaders, 'date') ? getDate(resHeaders.date) : undefined
|
|
if (resDate === null) {
|
|
deleteCachedValueIfNotModified(statusCode, this.#store, this.#cacheKey)
|
|
return downstreamOnHeaders()
|
|
}
|
|
|
|
const apparentAge = resDate ? Math.max(0, now - resDate.getTime()) : 0
|
|
const currentAge = Math.max(apparentAge, resAge ?? 0)
|
|
|
|
const hasValidator =
|
|
(typeof resHeaders.etag === 'string' && isEtagUsable(resHeaders.etag)) ||
|
|
typeof resHeaders['last-modified'] === 'string'
|
|
|
|
const staleAt =
|
|
determineStaleAt(this.#cacheType, now, resAge, resHeaders, resDate, cacheControlDirectives, hasValidator) ??
|
|
this.#cacheByDefault
|
|
// Zero freshness lifetime but a validator: stale from the start, yet still
|
|
// storable since each reuse is preceded by a revalidation request.
|
|
// https://www.rfc-editor.org/rfc/rfc9111.html#section-5.2.2.4
|
|
const revalidationOnly = staleAt === 0 && hasValidator
|
|
if (staleAt === undefined || (currentAge >= staleAt && !revalidationOnly)) {
|
|
if (cacheControlHeader || staleAt !== undefined) {
|
|
deleteCachedValueIfNotModified(statusCode, this.#store, this.#cacheKey)
|
|
}
|
|
|
|
return downstreamOnHeaders()
|
|
}
|
|
|
|
const baseTime = now - currentAge
|
|
let absoluteStaleAt = staleAt + baseTime
|
|
if (redirectPolicy !== undefined) {
|
|
absoluteStaleAt = Math.min(absoluteStaleAt, redirectPolicy.staleAt)
|
|
}
|
|
if (now >= absoluteStaleAt && !revalidationOnly) {
|
|
// Response is already stale
|
|
deleteCachedValueIfNotModified(statusCode, this.#store, this.#cacheKey)
|
|
return downstreamOnHeaders()
|
|
}
|
|
|
|
// Union the `Vary` of every suppressed redirect hop with the final
|
|
// response's `Vary`. A 3xx hop that negotiates its target on `Authorization`
|
|
// / `Cookie` (or any other header) must make the stored entry vary on those
|
|
// headers too, or an authenticated user's private response would be served
|
|
// to unrelated callers.
|
|
let varyDirectives
|
|
const combinedVary = []
|
|
if (redirectHopInfo) {
|
|
for (const hop of redirectHopInfo) {
|
|
appendVaryValues(combinedVary, hop?.headers?.vary)
|
|
}
|
|
}
|
|
appendVaryValues(combinedVary, resHeaders.vary)
|
|
if (combinedVary.length > 0) {
|
|
for (const varyHeader of combinedVary) {
|
|
if (hasVaryStar(varyHeader)) {
|
|
// `Vary: *` means the response can never be reused (RFC 9111 §4.1)
|
|
return downstreamOnHeaders()
|
|
}
|
|
}
|
|
if (this.#cacheKey.headers) {
|
|
varyDirectives = parseVaryHeader(combinedVary, this.#cacheKey.headers)
|
|
if (!varyDirectives) {
|
|
// Parse error
|
|
return downstreamOnHeaders()
|
|
}
|
|
}
|
|
}
|
|
|
|
// When the entry was folded from a redirect chain, the final response's
|
|
// stale-serving directives (RFC 5861) must not outlive the hops' freshness.
|
|
// A hop that grants no `stale-while-revalidate` / `stale-if-error` caps
|
|
// stale serving at its freshness, so the final response cannot launder a
|
|
// stale-serving window past the hop-bounded `staleAt`. Drop those directives
|
|
// (and keep the `proxy-revalidate` the hop policy may require) so the entry
|
|
// revalidates at `staleAt` instead of being served stale for the final
|
|
// response's window.
|
|
let effectiveCacheControlDirectives = cacheControlDirectives
|
|
if (redirectPolicy !== undefined) {
|
|
effectiveCacheControlDirectives = { ...cacheControlDirectives }
|
|
delete effectiveCacheControlDirectives['stale-while-revalidate']
|
|
delete effectiveCacheControlDirectives['stale-if-error']
|
|
if (redirectPolicy.requiresRevalidation === true) {
|
|
effectiveCacheControlDirectives['proxy-revalidate'] = true
|
|
}
|
|
}
|
|
|
|
const cachedAt = baseTime
|
|
const deleteAt = determineDeleteAt(baseTime, now, effectiveCacheControlDirectives, absoluteStaleAt)
|
|
const strippedHeaders = stripNecessaryHeaders(resHeaders, cacheControlDirectives)
|
|
|
|
/**
|
|
* @type {import('../../types/cache-interceptor.d.ts').default.CacheValue}
|
|
*/
|
|
const value = {
|
|
statusCode,
|
|
statusMessage,
|
|
headers: strippedHeaders,
|
|
vary: varyDirectives,
|
|
cacheControlDirectives: effectiveCacheControlDirectives,
|
|
cachedAt,
|
|
staleAt: absoluteStaleAt,
|
|
deleteAt
|
|
}
|
|
|
|
// Not modified, re-use the cached value
|
|
// https://www.rfc-editor.org/rfc/rfc9111.html#name-handling-304-not-modified
|
|
if (statusCode === 304) {
|
|
let done = false
|
|
const finish304 = () => {
|
|
if (done) {
|
|
return
|
|
}
|
|
done = true
|
|
this.#downstreamController.release()
|
|
}
|
|
|
|
// The cached body below is replayed to the downstream handler from later
|
|
// stream ticks (or an iterator loop), outside the dispatcher's own error
|
|
// handling, so a throwing downstream handler must be converged to a
|
|
// per-request error instead of escaping as an uncaught exception.
|
|
const failReplay = (err) => {
|
|
if (done) {
|
|
return
|
|
}
|
|
done = true
|
|
// Abort the revalidation request: this releases the paused origin
|
|
// response (freeing the connection) and routes the error through
|
|
// CacheHandler.onResponseError, which destroys the cache write stream
|
|
// and forwards the error downstream exactly once.
|
|
controller.abort(err)
|
|
}
|
|
|
|
const handle304 = (cachedValue) => {
|
|
if (!cachedValue) {
|
|
// Do not create a new cache entry, as a 304 won't have a body - so cannot be cached.
|
|
downstreamOnHeaders()
|
|
finish304()
|
|
return
|
|
}
|
|
|
|
// Re-use the cached value: statuscode, statusmessage, headers and body
|
|
value.statusCode = cachedValue.statusCode
|
|
value.statusMessage = cachedValue.statusMessage
|
|
value.etag = cachedValue.etag
|
|
value.vary = varyDirectives ?? cachedValue.vary
|
|
value.headers = { ...cachedValue.headers, ...strippedHeaders }
|
|
|
|
downstreamOnHeaders()
|
|
|
|
this.#writeStream = this.#store.createWriteStream(this.#cacheKey, value)
|
|
|
|
if (!this.#writeStream || !cachedValue?.body) {
|
|
finish304()
|
|
return
|
|
}
|
|
|
|
if (typeof cachedValue.body.values === 'function') {
|
|
const bodyIterator = cachedValue.body.values()
|
|
|
|
const streamCachedBody = () => {
|
|
if (done) {
|
|
return
|
|
}
|
|
try {
|
|
for (const chunk of bodyIterator) {
|
|
const full = this.#writeStream?.write(chunk) === false
|
|
this.#handler.onResponseData?.(this.#downstreamController, chunk)
|
|
// when stream is full stop writing until we get a 'drain' event
|
|
if (full) {
|
|
return
|
|
}
|
|
}
|
|
finish304()
|
|
} catch (err) {
|
|
failReplay(err)
|
|
}
|
|
}
|
|
|
|
this.#writeStream
|
|
.on('error', function () {
|
|
handler.#writeStream = undefined
|
|
handler.#store.delete(handler.#cacheKey)
|
|
// Keep replaying downstream without the store
|
|
streamCachedBody()
|
|
})
|
|
.on('drain', () => {
|
|
streamCachedBody()
|
|
})
|
|
.on('close', function () {
|
|
if (handler.#writeStream === this) {
|
|
handler.#writeStream = undefined
|
|
// Keep replaying downstream without the store
|
|
streamCachedBody()
|
|
}
|
|
})
|
|
|
|
streamCachedBody()
|
|
} else if (typeof cachedValue.body.on === 'function') {
|
|
// Readable stream body (e.g. from async/remote cache stores)
|
|
cachedValue.body
|
|
.on('data', (chunk) => {
|
|
try {
|
|
this.#writeStream?.write(chunk)
|
|
this.#handler.onResponseData?.(this.#downstreamController, chunk)
|
|
} catch (err) {
|
|
cachedValue.body.destroy()
|
|
failReplay(err)
|
|
}
|
|
})
|
|
.on('end', () => {
|
|
this.#writeStream?.end()
|
|
finish304()
|
|
})
|
|
.on('error', () => {
|
|
this.#writeStream = undefined
|
|
this.#store.delete(this.#cacheKey)
|
|
finish304()
|
|
})
|
|
|
|
this.#writeStream
|
|
.on('error', function () {
|
|
handler.#writeStream = undefined
|
|
handler.#store.delete(handler.#cacheKey)
|
|
})
|
|
.on('close', function () {
|
|
if (handler.#writeStream === this) {
|
|
handler.#writeStream = undefined
|
|
}
|
|
})
|
|
} else {
|
|
finish304()
|
|
}
|
|
}
|
|
|
|
/**
|
|
* @type {import('../../types/cache-interceptor.d.ts').default.CacheValue}
|
|
*/
|
|
const result = this.#store.get(this.#cacheKey)
|
|
// A 304 ends before the cached body is replayed. Keep the origin
|
|
// response paused until replay is complete.
|
|
this.#downstreamController.block()
|
|
controller.pause()
|
|
if (result && typeof result.then === 'function') {
|
|
result.then(handle304, () => handle304(undefined)).catch((err) => {
|
|
controller.abort(err)
|
|
})
|
|
} else {
|
|
handle304(result)
|
|
}
|
|
} else {
|
|
if (typeof resHeaders.etag === 'string' && isEtagUsable(resHeaders.etag)) {
|
|
value.etag = resHeaders.etag
|
|
}
|
|
|
|
this.#writeStream = this.#store.createWriteStream(this.#cacheKey, value)
|
|
|
|
if (!this.#writeStream) {
|
|
return downstreamOnHeaders()
|
|
}
|
|
|
|
this.#writeStream
|
|
.on('drain', () => controller.resume())
|
|
.on('error', function () {
|
|
// TODO (fix): Make error somehow observable?
|
|
handler.#writeStream = undefined
|
|
|
|
// Delete the value in case the cache store is holding onto state from
|
|
// the call to createWriteStream
|
|
handler.#store.delete(handler.#cacheKey)
|
|
})
|
|
.on('close', function () {
|
|
if (handler.#writeStream === this) {
|
|
handler.#writeStream = undefined
|
|
}
|
|
|
|
// TODO (fix): Should we resume even if was paused downstream?
|
|
controller.resume()
|
|
})
|
|
|
|
downstreamOnHeaders()
|
|
}
|
|
}
|
|
|
|
onResponseData (controller, chunk) {
|
|
if (this.#writeStream?.write(chunk) === false) {
|
|
controller.pause()
|
|
}
|
|
|
|
this.#handler.onResponseData?.(this.#downstreamController, chunk)
|
|
}
|
|
|
|
onResponseEnd (controller, trailers) {
|
|
this.#writeStream?.end()
|
|
this.#handler.onResponseEnd?.(this.#downstreamController, trailers)
|
|
}
|
|
|
|
onResponseError (controller, err) {
|
|
this.#writeStream?.destroy(err)
|
|
this.#writeStream = undefined
|
|
this.#handler.onResponseError?.(this.#downstreamController, err)
|
|
}
|
|
}
|
|
|
|
/**
|
|
* @param {import('../../types/cache-interceptor.d.ts').default.CacheStore} store
|
|
* @param {import('../../types/cache-interceptor.d.ts').default.CacheKey} cacheKey
|
|
*/
|
|
function deleteCachedValue (store, cacheKey) {
|
|
try {
|
|
store.delete(cacheKey)?.catch?.(noop)
|
|
} catch {
|
|
// Fail silently
|
|
}
|
|
}
|
|
|
|
function deleteCachedValueIfNotModified (statusCode, store, cacheKey) {
|
|
if (statusCode === 304) {
|
|
deleteCachedValue(store, cacheKey)
|
|
}
|
|
}
|
|
|
|
/**
|
|
* @param {import('../../types/cache-interceptor.d.ts').default.CacheOptions['type']} cacheType
|
|
* @param {import('../../types/header.d.ts').IncomingHttpHeaders} resHeaders
|
|
* @param {import('../../types/cache-interceptor.d.ts').default.CacheControlDirectives} cacheControlDirectives
|
|
* @returns {boolean}
|
|
*/
|
|
function revalidationResponseDisallowsCachedReuse (cacheType, resHeaders, cacheControlDirectives) {
|
|
return cacheControlDirectives['no-store'] === true ||
|
|
(cacheType === 'shared' && (
|
|
cacheControlDirectives.private === true ||
|
|
Object.hasOwn(resHeaders, 'set-cookie')
|
|
)) ||
|
|
(resHeaders.vary ? isInvalidOrWildcardVaryHeader(resHeaders.vary) : false)
|
|
}
|
|
|
|
/**
|
|
* @see https://www.rfc-editor.org/rfc/rfc9111.html#name-storing-responses-to-authen
|
|
*
|
|
* @param {import('../../types/cache-interceptor.d.ts').default.CacheOptions['type']} cacheType
|
|
* @param {string} method
|
|
* @param {number} statusCode
|
|
* @param {import('../../types/header.d.ts').IncomingHttpHeaders} resHeaders
|
|
* @param {import('../../types/cache-interceptor.d.ts').default.CacheControlDirectives} cacheControlDirectives
|
|
* @param {import('../../types/header.d.ts').IncomingHttpHeaders} [reqHeaders]
|
|
*/
|
|
function canCacheResponse (cacheType, method, statusCode, resHeaders, cacheControlDirectives, reqHeaders) {
|
|
if (!arrayIncludes(util.safeHTTPMethods, method)) {
|
|
return false
|
|
}
|
|
// Status code must be final and understood.
|
|
if (statusCode < 200 || arrayIncludes(NOT_UNDERSTOOD_STATUS_CODES, statusCode)) {
|
|
return false
|
|
}
|
|
// Responses with neither status codes that are heuristically cacheable, nor "explicit enough" caching
|
|
// directives, are not cacheable. "Explicit enough": see https://www.rfc-editor.org/rfc/rfc9111.html#section-3
|
|
if (!arrayIncludes(HEURISTICALLY_CACHEABLE_STATUS_CODES, statusCode) && !resHeaders['expires'] &&
|
|
!cacheControlDirectives.public &&
|
|
cacheControlDirectives['max-age'] === undefined &&
|
|
// RFC 9111: a private response directive, if the cache is not shared
|
|
!(cacheControlDirectives.private && cacheType === 'private') &&
|
|
!(cacheControlDirectives['s-maxage'] !== undefined && cacheType === 'shared')
|
|
) {
|
|
return false
|
|
}
|
|
|
|
if (cacheControlDirectives['no-store']) {
|
|
return false
|
|
}
|
|
|
|
if (cacheType === 'shared' && (
|
|
cacheControlDirectives.private === true ||
|
|
Object.hasOwn(resHeaders, 'set-cookie')
|
|
)) {
|
|
return false
|
|
}
|
|
|
|
// https://www.rfc-editor.org/rfc/rfc9111.html#section-4.1-5
|
|
if (resHeaders.vary && hasVaryStar(resHeaders.vary)) {
|
|
return false
|
|
}
|
|
|
|
// https://www.rfc-editor.org/rfc/rfc9111.html#name-storing-responses-to-authen
|
|
if (reqHeaders != null && Object.hasOwn(reqHeaders, 'authorization')) {
|
|
if (
|
|
!cacheControlDirectives.public &&
|
|
!cacheControlDirectives['s-maxage'] &&
|
|
!cacheControlDirectives['must-revalidate']
|
|
) {
|
|
return false
|
|
}
|
|
|
|
if (typeof reqHeaders.authorization !== 'string') {
|
|
return false
|
|
}
|
|
|
|
if (
|
|
Array.isArray(cacheControlDirectives['no-cache']) &&
|
|
arrayIncludes(cacheControlDirectives['no-cache'], 'authorization')
|
|
) {
|
|
return false
|
|
}
|
|
|
|
if (
|
|
Array.isArray(cacheControlDirectives['private']) &&
|
|
arrayIncludes(cacheControlDirectives['private'], 'authorization')
|
|
) {
|
|
return false
|
|
}
|
|
}
|
|
|
|
return true
|
|
}
|
|
|
|
/**
|
|
* Determine the absolute freshness deadline imposed by all suppressed redirect
|
|
* hops. Returning `undefined` means at least one hop cannot safely be folded
|
|
* into the final response under the original request key.
|
|
*
|
|
* @param {import('../../types/cache-interceptor.d.ts').default.CacheOptions['type']} cacheType
|
|
* @param {string} method
|
|
* @param {RedirectHop[]} redirectHops
|
|
* @param {import('../../types/header.d.ts').IncomingHttpHeaders} reqHeaders
|
|
* @param {number | undefined} cacheByDefault
|
|
* @param {number} now
|
|
* @returns {{ staleAt: number, requiresRevalidation: boolean } | undefined}
|
|
*/
|
|
function getRedirectPolicy (cacheType, method, redirectHops, reqHeaders, cacheByDefault, now) {
|
|
let staleAt = Infinity
|
|
let requiresRevalidation = false
|
|
|
|
for (const hop of redirectHops) {
|
|
const hopPolicy = getRedirectHopPolicy(cacheType, method, hop, reqHeaders, cacheByDefault)
|
|
if (hopPolicy === undefined || hopPolicy.staleAt <= now) {
|
|
return undefined
|
|
}
|
|
|
|
staleAt = Math.min(staleAt, hopPolicy.staleAt)
|
|
requiresRevalidation ||= hopPolicy.requiresRevalidation
|
|
}
|
|
|
|
return { staleAt, requiresRevalidation }
|
|
}
|
|
|
|
/**
|
|
* Calculate one redirect hop's absolute freshness deadline using the same age,
|
|
* date, expiration, invalid-directive, and heuristic rules as a final response.
|
|
*
|
|
* @param {import('../../types/cache-interceptor.d.ts').default.CacheOptions['type']} cacheType
|
|
* @param {string} method
|
|
* @param {RedirectHop} hop
|
|
* @param {import('../../types/header.d.ts').IncomingHttpHeaders} reqHeaders
|
|
* @param {number | undefined} cacheByDefault
|
|
* @returns {{ staleAt: number, requiresRevalidation: boolean } | undefined}
|
|
*/
|
|
function getRedirectHopPolicy (cacheType, method, hop, reqHeaders, cacheByDefault) {
|
|
if (!Number.isInteger(hop?.statusCode) || !Number.isFinite(hop?.receivedAt)) {
|
|
return undefined
|
|
}
|
|
|
|
const hopHeaders = hop.headers ?? {}
|
|
const cacheControlHeader = hopHeaders['cache-control']
|
|
const hopCacheControl = cacheControlHeader
|
|
? parseCacheControlHeader(cacheControlHeader)
|
|
: {}
|
|
|
|
// https://www.rfc-editor.org/rfc/rfc9111.html#section-4.1-5
|
|
if (hopHeaders.vary && hasVaryStar(hopHeaders.vary)) {
|
|
return undefined
|
|
}
|
|
|
|
if (hopCacheControl['no-store'] === true) {
|
|
return undefined
|
|
}
|
|
|
|
// A qualified `private` directive still marks the named fields as private.
|
|
// Folding a redirect that says `private="location"` would preserve the
|
|
// private target choice in the final body even though a shared cache is not
|
|
// allowed to store that Location field.
|
|
if (cacheType === 'shared' && Object.hasOwn(hopCacheControl, 'private')) {
|
|
return undefined
|
|
}
|
|
|
|
// These directives require the hop to be revalidated before reuse. Since the
|
|
// cache stores only the final response, it cannot independently validate the
|
|
// suppressed redirect response.
|
|
if (
|
|
Object.hasOwn(hopCacheControl, 'no-cache') ||
|
|
hopCacheControl['must-revalidate'] === true ||
|
|
(cacheType === 'shared' && hopCacheControl['proxy-revalidate'] === true)
|
|
) {
|
|
return undefined
|
|
}
|
|
|
|
const heuristicallyCacheable =
|
|
hopHeaders['last-modified'] &&
|
|
arrayIncludes(HEURISTICALLY_CACHEABLE_STATUS_CODES, hop.statusCode)
|
|
if (
|
|
!cacheControlHeader &&
|
|
!hopHeaders.expires &&
|
|
!heuristicallyCacheable &&
|
|
!cacheByDefault
|
|
) {
|
|
return undefined
|
|
}
|
|
|
|
if (!canCacheResponse(cacheType, method, hop.statusCode, hopHeaders, hopCacheControl, reqHeaders)) {
|
|
return undefined
|
|
}
|
|
|
|
const age = Object.hasOwn(hopHeaders, 'age') ? getAge(hopHeaders.age) : undefined
|
|
if (age !== undefined && age >= MAX_RESPONSE_AGE) {
|
|
return undefined
|
|
}
|
|
|
|
const responseDate = Object.hasOwn(hopHeaders, 'date') ? getDate(hopHeaders.date) : undefined
|
|
if (responseDate === null) {
|
|
return undefined
|
|
}
|
|
|
|
const apparentAge = responseDate ? Math.max(0, hop.receivedAt - responseDate.getTime()) : 0
|
|
const currentAge = Math.max(apparentAge, age ?? 0)
|
|
const hasValidator =
|
|
(typeof hopHeaders.etag === 'string' && isEtagUsable(hopHeaders.etag)) ||
|
|
typeof hopHeaders['last-modified'] === 'string'
|
|
const freshnessLifetime =
|
|
determineStaleAt(
|
|
cacheType,
|
|
hop.receivedAt,
|
|
age,
|
|
hopHeaders,
|
|
responseDate,
|
|
hopCacheControl,
|
|
hasValidator
|
|
) ?? cacheByDefault
|
|
|
|
if (freshnessLifetime === undefined) {
|
|
return undefined
|
|
}
|
|
|
|
return {
|
|
staleAt: hop.receivedAt - currentAge + freshnessLifetime,
|
|
// RFC 9111 §5.2.2.10: s-maxage implies proxy-revalidate for shared caches.
|
|
requiresRevalidation: cacheType === 'shared' && Object.hasOwn(hopCacheControl, 's-maxage')
|
|
}
|
|
}
|
|
|
|
/**
|
|
* @param {string | string[]} dateHeader
|
|
* @returns {Date | null | undefined}
|
|
*/
|
|
function getDate (dateHeader) {
|
|
let dateValue = dateHeader
|
|
if (Array.isArray(dateValue)) {
|
|
if (dateValue.length !== 1) {
|
|
return null
|
|
}
|
|
|
|
dateValue = dateValue[0]
|
|
}
|
|
|
|
if (typeof dateValue !== 'string') {
|
|
return null
|
|
}
|
|
|
|
return parseHttpDate(dateValue)
|
|
}
|
|
|
|
/**
|
|
* @param {string | string[]} ageHeader
|
|
* @returns {number | undefined}
|
|
*/
|
|
function getAge (ageHeader) {
|
|
let ageValue = ageHeader
|
|
if (Array.isArray(ageValue)) {
|
|
if (ageValue.length !== 1) {
|
|
return MAX_RESPONSE_AGE
|
|
}
|
|
|
|
ageValue = ageValue[0]
|
|
}
|
|
|
|
if (typeof ageValue !== 'string' || !/^[\t ]*[0-9]+[\t ]*$/.test(ageValue)) {
|
|
return MAX_RESPONSE_AGE
|
|
}
|
|
|
|
const age = BigInt(ageValue.replace(/^[\t ]+|[\t ]+$/g, ''))
|
|
if (age >= BigInt(MAX_RESPONSE_AGE / 1000)) {
|
|
return MAX_RESPONSE_AGE
|
|
}
|
|
|
|
return Number(age) * 1000
|
|
}
|
|
|
|
/**
|
|
* @param {import('../../types/cache-interceptor.d.ts').default.CacheOptions['type']} cacheType
|
|
* @param {number} now
|
|
* @param {number | undefined} age
|
|
* @param {import('../../types/header.d.ts').IncomingHttpHeaders} resHeaders
|
|
* @param {Date | undefined} responseDate
|
|
* @param {import('../../types/cache-interceptor.d.ts').default.CacheControlDirectives} cacheControlDirectives
|
|
* @param {boolean} hasValidator whether the response has a validator (etag or
|
|
* last-modified) that revalidation requests can be made with
|
|
*
|
|
* @returns {number | undefined} time that the value is stale at in seconds or undefined if it shouldn't be cached
|
|
*/
|
|
function determineStaleAt (cacheType, now, age, resHeaders, responseDate, cacheControlDirectives, hasValidator) {
|
|
if (cacheType === 'shared') {
|
|
// Prioritize s-maxage since we're a shared cache
|
|
// s-maxage > max-age > Expire
|
|
// https://www.rfc-editor.org/rfc/rfc9111.html#section-5.2.2.10-3
|
|
if (hasInvalidCacheControlDirective(cacheControlDirectives, 's-maxage')) {
|
|
return 0
|
|
}
|
|
|
|
const sMaxAge = cacheControlDirectives['s-maxage']
|
|
if (sMaxAge !== undefined) {
|
|
if (sMaxAge > 0) {
|
|
return sMaxAge * 1000
|
|
}
|
|
|
|
// Immediately stale, but storable if we can revalidate it before reuse.
|
|
return 0
|
|
}
|
|
}
|
|
|
|
if (hasInvalidCacheControlDirective(cacheControlDirectives, 'max-age')) {
|
|
return 0
|
|
}
|
|
|
|
const maxAge = cacheControlDirectives['max-age']
|
|
if (maxAge !== undefined) {
|
|
if (maxAge > 0) {
|
|
return maxAge * 1000
|
|
}
|
|
|
|
// Immediately stale, but storable if we can revalidate it before reuse.
|
|
return 0
|
|
}
|
|
|
|
if (Object.hasOwn(resHeaders, 'expires')) {
|
|
// https://www.rfc-editor.org/rfc/rfc9111.html#section-5.3
|
|
if (typeof resHeaders.expires !== 'string') {
|
|
return 0
|
|
}
|
|
|
|
const expiresDate = parseHttpDate(resHeaders.expires)
|
|
if (!expiresDate) {
|
|
return 0
|
|
}
|
|
|
|
if (now >= expiresDate.getTime()) {
|
|
return 0
|
|
}
|
|
|
|
if (responseDate) {
|
|
if (responseDate >= expiresDate) {
|
|
return 0
|
|
}
|
|
|
|
const freshnessLifetime = expiresDate.getTime() - responseDate.getTime()
|
|
if (age !== undefined && age >= freshnessLifetime) {
|
|
return 0
|
|
}
|
|
|
|
return freshnessLifetime
|
|
}
|
|
|
|
return expiresDate.getTime() - now
|
|
}
|
|
|
|
if (typeof resHeaders['last-modified'] === 'string') {
|
|
// https://www.rfc-editor.org/rfc/rfc9111.html#name-calculating-heuristic-fresh
|
|
const lastModified = parseHttpDate(resHeaders['last-modified'])
|
|
if (lastModified) {
|
|
if (lastModified.getTime() >= now) {
|
|
return undefined
|
|
}
|
|
|
|
const responseAge = now - lastModified.getTime()
|
|
|
|
return responseAge * 0.1
|
|
}
|
|
}
|
|
|
|
if (cacheControlDirectives.immutable) {
|
|
// https://www.rfc-editor.org/rfc/rfc8246.html#section-2.2
|
|
return 31536000000
|
|
}
|
|
|
|
if (cacheControlDirectives['no-cache'] === true && hasValidator) {
|
|
// No freshness source, but a validator lets us revalidate before reuse.
|
|
// https://www.rfc-editor.org/rfc/rfc9111.html#section-5.2.2.4
|
|
return 0
|
|
}
|
|
|
|
return undefined
|
|
}
|
|
|
|
/**
|
|
* @param {number} baseTime
|
|
* @param {number} cachedAt
|
|
* @param {import('../../types/cache-interceptor.d.ts').default.CacheControlDirectives} cacheControlDirectives
|
|
* @param {number} staleAt
|
|
*/
|
|
function determineDeleteAt (baseTime, cachedAt, cacheControlDirectives, staleAt) {
|
|
let staleWhileRevalidate = -Infinity
|
|
let staleIfError = -Infinity
|
|
let immutable = -Infinity
|
|
|
|
if (cacheControlDirectives['stale-while-revalidate']) {
|
|
staleWhileRevalidate = staleAt + (cacheControlDirectives['stale-while-revalidate'] * 1000)
|
|
}
|
|
|
|
if (cacheControlDirectives['stale-if-error']) {
|
|
staleIfError = staleAt + (cacheControlDirectives['stale-if-error'] * 1000)
|
|
}
|
|
|
|
if (cacheControlDirectives.immutable && staleWhileRevalidate === -Infinity && staleIfError === -Infinity) {
|
|
immutable = cachedAt + 31536000000
|
|
}
|
|
|
|
// When no stale directives or immutable flag, add a revalidation buffer
|
|
// equal to the freshness lifetime so the entry survives past staleAt long
|
|
// enough to be revalidated instead of silently disappearing.
|
|
//
|
|
// Response Date headers only have second precision, so baseTime can trail the
|
|
// actual cache insertion time by up to ~1s. Pad the buffer by that bounded
|
|
// skew so short-lived entries do not disappear exactly when they should be
|
|
// revalidated.
|
|
if (staleWhileRevalidate === -Infinity && staleIfError === -Infinity && immutable === -Infinity) {
|
|
const freshnessLifetime = staleAt - baseTime
|
|
if (freshnessLifetime <= 0) {
|
|
// Revalidation-only entry: no freshness lifetime to size the buffer on,
|
|
// so retain it for a bounded window instead.
|
|
return cachedAt + REVALIDATION_ONLY_RETENTION
|
|
}
|
|
const datePrecisionPadding = Math.min(Math.max(cachedAt - baseTime, 0), 1000)
|
|
return staleAt + freshnessLifetime + datePrecisionPadding
|
|
}
|
|
|
|
return Math.max(staleAt, staleWhileRevalidate, staleIfError, immutable)
|
|
}
|
|
|
|
/**
|
|
* Strips headers required to be removed in cached responses
|
|
* @param {import('../../types/header.d.ts').IncomingHttpHeaders} resHeaders
|
|
* @param {import('../../types/cache-interceptor.d.ts').default.CacheControlDirectives} cacheControlDirectives
|
|
* @returns {Record<string, string | string []>}
|
|
*/
|
|
function stripNecessaryHeaders (resHeaders, cacheControlDirectives) {
|
|
const headersToRemove = [
|
|
'connection',
|
|
'proxy-authenticate',
|
|
'proxy-authentication-info',
|
|
'proxy-authorization',
|
|
'proxy-connection',
|
|
'te',
|
|
'transfer-encoding',
|
|
'upgrade',
|
|
// We'll add age back when serving it
|
|
'age'
|
|
]
|
|
|
|
if (resHeaders['connection']) {
|
|
appendConnectionHeaderTokens(headersToRemove, resHeaders['connection'])
|
|
}
|
|
|
|
if (Array.isArray(cacheControlDirectives['no-cache'])) {
|
|
headersToRemove.push(...cacheControlDirectives['no-cache'])
|
|
}
|
|
|
|
if (Array.isArray(cacheControlDirectives['private'])) {
|
|
headersToRemove.push(...cacheControlDirectives['private'])
|
|
}
|
|
|
|
let strippedHeaders
|
|
for (const headerName of headersToRemove) {
|
|
if (Object.hasOwn(resHeaders, headerName)) {
|
|
strippedHeaders ??= { ...resHeaders }
|
|
delete strippedHeaders[headerName]
|
|
}
|
|
}
|
|
|
|
return strippedHeaders ?? resHeaders
|
|
}
|
|
|
|
module.exports = CacheHandler
|