got 14.5.0 → 14.6.1

package/dist/source/core/index.js

@@ -1,8 +1,6 @@
 import process from 'node:process';
 import { Buffer } from 'node:buffer';
-import { Duplex } from 'node:stream';
-import { gunzip, inflate, brotliDecompress } from 'node:zlib';
-import { promisify } from 'node:util';
+import { Duplex, Transform } from 'node:stream';
 import http, { ServerResponse } from 'node:http';
 import timer from '@szmarczak/http-timer';
 import CacheableRequest, { CacheError as CacheableCacheError, } from 'cacheable-request';
@@ -19,14 +17,18 @@ import calculateRetryDelay from './calculate-retry-delay.js';
 import Options from './options.js';
 import { isResponseOk } from './response.js';
 import isClientRequest from './utils/is-client-request.js';
-import isUnixSocketURL from './utils/is-unix-socket-url.js';
+import isUnixSocketURL, { getUnixSocketPath } from './utils/is-unix-socket-url.js';
 import { RequestError, ReadError, MaxRedirectsError, HTTPError, TimeoutError, UploadError, CacheError, AbortError, } from './errors.js';
+import { generateRequestId, publishRequestCreate, publishRequestStart, publishResponseStart, publishResponseEnd, publishRetry, publishError, publishRedirect, } from './diagnostics-channel.js';
 const supportsBrotli = is.string(process.versions.brotli);
+const supportsZstd = is.string(process.versions.zstd);
 const methodsWithoutBody = new Set(['GET', 'HEAD']);
 // Methods that should auto-end streams when no body is provided
 const methodsWithoutBodyStream = new Set(['OPTIONS', 'DELETE', 'PATCH']);
 const cacheableStore = new WeakableMap();
 const redirectCodes = new Set([300, 301, 302, 303, 304, 307, 308]);
+// Track errors that have been processed by beforeError hooks to preserve custom error types
+const errorsProcessedByHooks = new WeakSet();
 const proxiedRequestEvents = [
     'socket',
     'connect',
@@ -35,6 +37,17 @@ const proxiedRequestEvents = [
     'upgrade',
 ];
 const noop = () => { };
+/**
+Stream transform that counts bytes passing through.
+Used to track compressed bytes before decompression for content-length validation.
+*/
+class ByteCounter extends Transform {
+    count = 0;
+    _transform(chunk, _encoding, callback) {
+        this.count += chunk.length;
+        callback(null, chunk);
+    }
+}
 export default class Request extends Duplex {
     // @ts-expect-error - Ignoring for now.
     ['constructor'];
@@ -43,26 +56,30 @@ export default class Request extends Duplex {
     options;
     response;
     requestUrl;
-    redirectUrls;
-    retryCount;
-    _stopRetry;
-    _downloadedSize;
-    _uploadedSize;
-    _stopReading;
-    _pipedServerResponses;
+    redirectUrls = [];
+    retryCount = 0;
+    _stopReading = false;
+    _stopRetry = noop;
+    _downloadedSize = 0;
+    _uploadedSize = 0;
+    _pipedServerResponses = new Set();
     _request;
     _responseSize;
     _bodySize;
-    _unproxyEvents;
+    _unproxyEvents = noop;
     _isFromCache;
-    _triggerRead;
-    _cancelTimeouts;
-    _removeListeners;
+    _triggerRead = false;
+    _jobs = [];
+    _cancelTimeouts = noop;
+    _removeListeners = noop;
     _nativeResponse;
-    _flushed;
-    _aborted;
+    _flushed = false;
+    _aborted = false;
+    _expectedContentLength;
+    _byteCounter;
+    _requestId = generateRequestId();
     // We need this because `this._request` if `undefined` when using cache
-    _requestInitialized;
+    _requestInitialized = false;
     constructor(url, options, defaults) {
         super({
             // Don't destroy immediately, as the error may be emitted on unsuccessful retry
@@ -70,23 +87,8 @@ export default class Request extends Duplex {
             // It needs to be zero because we're just proxying the data to another stream
             highWaterMark: 0,
         });
-        this._downloadedSize = 0;
-        this._uploadedSize = 0;
-        this._stopReading = false;
-        this._pipedServerResponses = new Set();
-        this._unproxyEvents = noop;
-        this._triggerRead = false;
-        this._cancelTimeouts = noop;
-        this._removeListeners = noop;
-        this._jobs = [];
-        this._flushed = false;
-        this._requestInitialized = false;
-        this._aborted = false;
-        this.redirectUrls = [];
-        this.retryCount = 0;
-        this._stopRetry = noop;
         this.on('pipe', (source) => {
-            if (source?.headers) {
+            if (this.options.copyPipedHeaders && source?.headers) {
                 Object.assign(this.options.headers, source.headers);
             }
         });
@@ -104,6 +106,12 @@ export default class Request extends Duplex {
                 this.options.url = '';
             }
             this.requestUrl = this.options.url;
+            // Publish request creation event
+            publishRequestCreate({
+                requestId: this._requestId,
+                url: this.options.url?.toString() ?? '',
+                method: this.options.method,
+            });
         }
         catch (error) {
             const { options } = error;
@@ -112,7 +120,18 @@ export default class Request extends Duplex {
             }
             this.flush = async () => {
                 this.flush = async () => { };
-                this.destroy(error);
+                // Defer error emission to next tick to allow user to attach error handlers
+                process.nextTick(() => {
+                    // _beforeError requires options to access retry logic and hooks
+                    if (this.options) {
+                        this._beforeError(error);
+                    }
+                    else {
+                        // Options is undefined, skip _beforeError and destroy directly
+                        const requestError = error instanceof RequestError ? error : new RequestError(error.message, error, this);
+                        this.destroy(requestError);
+                    }
+                });
             };
             return;
         }
@@ -263,6 +282,8 @@ export default class Request extends Duplex {
                     if (this.destroyed) {
                         return;
                     }
+                    // Capture body BEFORE hooks run to detect reassignment
+                    const bodyBeforeHooks = this.options.body;
                     try {
                         for (const hook of this.options.hooks.beforeRetry) {
                             // eslint-disable-next-line no-await-in-loop
@@ -270,14 +291,58 @@ export default class Request extends Duplex {
                         }
                     }
                     catch (error_) {
-                        void this._error(new RequestError(error_.message, error, this));
+                        void this._error(new RequestError(error_.message, error_, this));
                         return;
                     }
                     // Something forced us to abort the retry
                     if (this.destroyed) {
                         return;
                     }
-                    this.destroy();
+                    // Preserve stream body reassigned in beforeRetry hooks.
+                    const bodyAfterHooks = this.options.body;
+                    const bodyWasReassigned = bodyBeforeHooks !== bodyAfterHooks;
+                    // Resource cleanup and preservation logic for retry with body reassignment.
+                    // The Promise wrapper (as-promise/index.ts) compares body identity to detect consumed streams,
+                    // so we must preserve the body reference across destroy(). However, destroy() calls _destroy()
+                    // which destroys this.options.body, creating a complex dance of clear/restore operations.
+                    //
+                    // Key constraints:
+                    // 1. If body was reassigned, we must NOT destroy the NEW stream (it will be used for retry)
+                    // 2. If body was reassigned, we MUST destroy the OLD stream to prevent memory leaks
+                    // 3. We must restore the body reference after destroy() for identity checks in promise wrapper
+                    // 4. We cannot use the normal setter after destroy() because it validates stream readability
+                    if (bodyWasReassigned) {
+                        const oldBody = bodyBeforeHooks;
+                        // Temporarily clear body to prevent destroy() from destroying the new stream
+                        this.options.body = undefined;
+                        this.destroy();
+                        // Clean up the old stream resource if it's a stream and different from new body
+                        // (edge case: if old and new are same stream object, don't destroy it)
+                        if (is.nodeStream(oldBody) && oldBody !== bodyAfterHooks) {
+                            oldBody.destroy();
+                        }
+                        // Restore new body for promise wrapper's identity check
+                        // We bypass the setter because it validates stream.readable (which fails for destroyed request)
+                        // Type assertion is necessary here to access private _internals without exposing internal API
+                        if (is.nodeStream(bodyAfterHooks) && (bodyAfterHooks.readableEnded || bodyAfterHooks.destroyed)) {
+                            throw new TypeError('The reassigned stream body must be readable. Ensure you provide a fresh, readable stream in the beforeRetry hook.');
+                        }
+                        this.options._internals.body = bodyAfterHooks;
+                    }
+                    else {
+                        // Body wasn't reassigned - use normal destroy flow which handles body cleanup
+                        this.destroy();
+                        // Note: We do NOT restore the body reference here. The stream was destroyed by _destroy()
+                        // and should not be accessed. The promise wrapper will see that body identity hasn't changed
+                        // and will detect it's a consumed stream, which is the correct behavior.
+                    }
+                    // Publish retry event
+                    publishRetry({
+                        requestId: this._requestId,
+                        retryCount: this.retryCount + 1,
+                        error: typedError,
+                        delay: backoff,
+                    });
                     this.emit('retry', this.retryCount + 1, error, (updatedOptions) => {
                         const request = new Request(options.url, updatedOptions, options);
                         request.retryCount = this.retryCount + 1;
@@ -368,8 +433,28 @@ export default class Request extends Duplex {
         if (this._request) {
             this._request.destroy();
         }
-        if (error !== null && !is.undefined(error) && !(error instanceof RequestError)) {
-            error = new RequestError(error.message, error, this);
+        // Workaround: http-timer only sets timings.end when the response emits 'end'.
+        // When a stream is destroyed before completion, the 'end' event may not fire,
+        // leaving timings.end undefined. This should ideally be fixed in http-timer
+        // by listening to the 'close' event, but we handle it here for now.
+        // Only set timings.end if there was no error or abort (to maintain semantic correctness).
+        const timings = this._request?.timings;
+        if (timings && is.undefined(timings.end) && !is.undefined(timings.response) && is.undefined(timings.error) && is.undefined(timings.abort)) {
+            timings.end = Date.now();
+            if (is.undefined(timings.phases.total)) {
+                timings.phases.download = timings.end - timings.response;
+                timings.phases.total = timings.end - timings.start;
+            }
+        }
+        // Preserve custom errors returned by beforeError hooks.
+        // For other errors, wrap non-RequestError instances for consistency.
+        if (error !== null && !is.undefined(error)) {
+            const processedByHooks = error instanceof Error && errorsProcessedByHooks.has(error);
+            if (!processedByHooks && !(error instanceof RequestError)) {
+                error = error instanceof Error
+                    ? new RequestError(error.message, error, this)
+                    : new RequestError(String(error), {}, this);
+            }
         }
         callback(error);
     }
@@ -386,6 +471,22 @@ export default class Request extends Duplex {
         super.unpipe(destination);
         return this;
     }
+    _checkContentLengthMismatch() {
+        if (this.options.strictContentLength && this._expectedContentLength !== undefined) {
+            // Use ByteCounter's count when available (for compressed responses),
+            // otherwise use _downloadedSize (for uncompressed responses)
+            const actualSize = this._byteCounter?.count ?? this._downloadedSize;
+            if (actualSize !== this._expectedContentLength) {
+                this._beforeError(new ReadError({
+                    message: `Content-Length mismatch: expected ${this._expectedContentLength} bytes, received ${actualSize} bytes`,
+                    name: 'Error',
+                    code: 'ERR_HTTP_CONTENT_LENGTH_MISMATCH',
+                }, this));
+                return true;
+            }
+        }
+        return false;
+    }
     async _finalizeBody() {
         const { options } = this;
         const { headers } = options;
@@ -473,86 +574,19 @@ export default class Request extends Duplex {
             || statusCode === 204
             || statusCode === 205
             || statusCode === 304;
-        const nativeResponse = response;
         if (options.decompress && !hasNoBody) {
+            // When strictContentLength is enabled, track compressed bytes by listening to
+            // the native response's data events before decompression
+            if (options.strictContentLength) {
+                this._byteCounter = new ByteCounter();
+                this._nativeResponse.on('data', (chunk) => {
+                    this._byteCounter.count += chunk.length;
+                });
+            }
             response = decompressResponse(response);
         }
-        // For revalidated cached responses (304 Not Modified), cacheable-request may return
-        // a ResponseLike object with the body stored in a .body property but not pushed into
-        // the stream. The stream is created and may be ended without data, and the 'end' event is
-        // never emitted, causing Got to hang waiting for it. Detect and fix this.
-        const nativeAsAny = nativeResponse;
-        if (nativeAsAny.body) {
-            // Mark the response as complete immediately (ResponseLike doesn't have req.res.complete)
-            nativeResponse.complete = true;
-            response.complete = true;
-            // Use setImmediate to check if this is a stuck revalidated response
-            setImmediate(() => {
-                // Check if the stream ended with no data (revalidated response)
-                if (nativeResponse.readableEnded && !nativeResponse.readableLength) {
-                    // The body is in nativeAsAny.body but was never pushed to the stream.
-                    // We need to push it to the native response so it flows through decompression if needed.
-                    try {
-                        // Push the body to the native stream
-                        nativeResponse.push(nativeAsAny.body);
-                        // eslint-disable-next-line unicorn/no-array-push-push
-                        nativeResponse.push(null);
-                        // Update download size with the cached body length
-                        let bodyLength = 0;
-                        if (Buffer.isBuffer(nativeAsAny.body)) {
-                            bodyLength = nativeAsAny.body.length;
-                        }
-                        else if (typeof nativeAsAny.body === 'string') {
-                            bodyLength = Buffer.byteLength(nativeAsAny.body);
-                        }
-                        this._downloadedSize += bodyLength;
-                    }
-                    catch {
-                        // If push fails (stream already ended), we need to decompress manually for compressed responses
-                        const encoding = nativeResponse.headers['content-encoding'];
-                        if (encoding && Buffer.isBuffer(nativeAsAny.body)) {
-                            // Decompress the body based on the encoding
-                            let decompressAsync;
-                            switch (encoding) {
-                                case 'gzip': {
-                                    decompressAsync = promisify(gunzip);
-                                    break;
-                                }
-                                case 'deflate': {
-                                    decompressAsync = promisify(inflate);
-                                    break;
-                                }
-                                case 'br': {
-                                    decompressAsync = promisify(brotliDecompress);
-                                    break;
-                                }
-                                default: {
-                                    break;
-                                }
-                            }
-                            if (decompressAsync) {
-                                // Decompress asynchronously and set rawBody
-                                void decompressAsync(nativeAsAny.body).then((decompressed) => {
-                                    response.rawBody = decompressed;
-                                    this._downloadedSize += nativeAsAny.body.length;
-                                    response.emit('end');
-                                }).catch(() => {
-                                    // Decompression failed, use compressed body as-is
-                                    response.rawBody = nativeAsAny.body;
-                                    response.emit('end');
-                                });
-                                return;
-                            }
-                        }
-                        // Not compressed or decompression not needed, set rawBody directly
-                        response.rawBody = nativeAsAny.body;
-                        response.emit('end');
-                    }
-                }
-            });
-        }
         const typedResponse = response;
-        typedResponse.statusMessage = typedResponse.statusMessage ?? http.STATUS_CODES[statusCode];
+        typedResponse.statusMessage = typedResponse.statusMessage || http.STATUS_CODES[statusCode]; // eslint-disable-line @typescript-eslint/prefer-nullish-coalescing -- The status message can be empty.
         typedResponse.url = options.url.toString();
         typedResponse.requestUrl = this.requestUrl;
         typedResponse.redirectUrls = this.redirectUrls;
@@ -564,6 +598,35 @@ export default class Request extends Duplex {
         this._isFromCache = typedResponse.isFromCache;
         this._responseSize = Number(response.headers['content-length']) || undefined;
         this.response = typedResponse;
+        // Publish response start event
+        publishResponseStart({
+            requestId: this._requestId,
+            url: typedResponse.url,
+            statusCode,
+            headers: response.headers,
+            isFromCache: typedResponse.isFromCache,
+        });
+        // Workaround for http-timer bug: when connecting to an IP address (no DNS lookup),
+        // http-timer sets lookup = connect instead of lookup = socket, resulting in
+        // dns = lookup - socket being a small positive number instead of 0.
+        // See https://github.com/sindresorhus/got/issues/2279
+        const { timings } = response;
+        if (timings?.lookup !== undefined && timings.socket !== undefined && timings.connect !== undefined && timings.lookup === timings.connect && timings.phases.dns !== 0) {
+            // Fix the DNS phase to be 0 and set lookup to socket time
+            timings.phases.dns = 0;
+            timings.lookup = timings.socket;
+            // Recalculate TCP time to be the full time from socket to connect
+            timings.phases.tcp = timings.connect - timings.socket;
+        }
+        // Workaround for http-timer limitation with HTTP/2:
+        // When using HTTP/2, the socket is a proxy that http-timer discards,
+        // so lookup, connect, and secureConnect events are never captured.
+        // This results in phases.request being NaN (undefined - undefined).
+        // Set it to undefined to be consistent with other unavailable timings.
+        // See https://github.com/sindresorhus/got/issues/1958
+        if (timings && Number.isNaN(timings.phases.request)) {
+            timings.phases.request = undefined;
+        }
         response.once('error', (error) => {
             this._aborted = true;
             // Force clean-up, because some packages don't do this.
@@ -573,11 +636,14 @@ export default class Request extends Duplex {
         });
         response.once('aborted', () => {
             this._aborted = true;
-            this._beforeError(new ReadError({
-                name: 'Error',
-                message: 'The server aborted pending request',
-                code: 'ECONNRESET',
-            }, this));
+            // Check if there's a content-length mismatch to provide a more specific error
+            if (!this._checkContentLengthMismatch()) {
+                this._beforeError(new ReadError({
+                    name: 'Error',
+                    message: 'The server aborted pending request',
+                    code: 'ECONNRESET',
+                }, this));
+            }
         });
         const rawCookies = response.headers['set-cookie'];
         if (is.object(options.cookieJar) && rawCookies) {
@@ -639,7 +705,11 @@ export default class Request extends Duplex {
                         return;
                     }
                     // Redirecting to a different site, clear sensitive data.
-                    if (redirectUrl.hostname !== url.hostname || redirectUrl.port !== url.port) {
+                    // For UNIX sockets, different socket paths are also different origins.
+                    const isDifferentOrigin = redirectUrl.hostname !== url.hostname
+                        || redirectUrl.port !== url.port
+                        || getUnixSocketPath(url) !== getUnixSocketPath(redirectUrl);
+                    if (isDifferentOrigin) {
                         if ('host' in updatedOptions.headers) {
                             delete updatedOptions.headers.host;
                         }
@@ -659,12 +729,18 @@ export default class Request extends Duplex {
                         redirectUrl.password = updatedOptions.password;
                     }
                     this.redirectUrls.push(redirectUrl);
-                    updatedOptions.prefixUrl = '';
                     updatedOptions.url = redirectUrl;
                     for (const hook of updatedOptions.hooks.beforeRedirect) {
                         // eslint-disable-next-line no-await-in-loop
                         await hook(updatedOptions, typedResponse);
                     }
+                    // Publish redirect event
+                    publishRedirect({
+                        requestId: this._requestId,
+                        fromUrl: url.toString(),
+                        toUrl: redirectUrl.toString(),
+                        statusCode,
+                    });
                     this.emit('redirect', updatedOptions, typedResponse);
                     this.options = updatedOptions;
                     await this._makeRequest();
@@ -684,13 +760,40 @@ export default class Request extends Duplex {
             this._beforeError(new HTTPError(typedResponse));
             return;
         }
+        // Store the expected content-length from the native response for validation.
+        // This is the content-length before decompression, which is what actually gets transferred.
+        // Skip storing for responses that shouldn't have bodies per RFC 9110.
+        // When decompression occurs, only store if strictContentLength is enabled.
+        const wasDecompressed = response !== this._nativeResponse;
+        if (!hasNoBody && (!wasDecompressed || options.strictContentLength)) {
+            const contentLengthHeader = this._nativeResponse.headers['content-length'];
+            if (contentLengthHeader !== undefined) {
+                const expectedLength = Number(contentLengthHeader);
+                if (!Number.isNaN(expectedLength) && expectedLength >= 0) {
+                    this._expectedContentLength = expectedLength;
+                }
+            }
+        }
         // Set up end listener AFTER redirect check to avoid emitting progress for redirect responses
-        const endStream = () => {
+        response.once('end', () => {
+            // Validate content-length if it was provided
+            // Per RFC 9112: "If the sender closes the connection before the indicated number
+            // of octets are received, the recipient MUST consider the message to be incomplete"
+            if (this._checkContentLengthMismatch()) {
+                return;
+            }
             this._responseSize = this._downloadedSize;
             this.emit('downloadProgress', this.downloadProgress);
+            // Publish response end event
+            publishResponseEnd({
+                requestId: this._requestId,
+                url: typedResponse.url,
+                statusCode,
+                bodySize: this._downloadedSize,
+                timings: this.timings,
+            });
             this.push(null);
-        };
-        response.once('end', endStream);
+        });
         this.emit('downloadProgress', this.downloadProgress);
         response.on('readable', () => {
             if (this._triggerRead) {
@@ -715,12 +818,22 @@ export default class Request extends Duplex {
             if (destination.headersSent) {
                 continue;
             }
-            // eslint-disable-next-line guard-for-in
+            // Check if decompression actually occurred by comparing stream objects.
+            // decompressResponse wraps the response stream when it decompresses,
+            // so response !== this._nativeResponse indicates decompression happened.
+            const wasDecompressed = response !== this._nativeResponse;
             for (const key in response.headers) {
-                const isAllowed = options.decompress ? key !== 'content-encoding' : true;
-                const value = response.headers[key];
-                if (isAllowed) {
-                    destination.setHeader(key, value);
+                if (Object.hasOwn(response.headers, key)) {
+                    const value = response.headers[key];
+                    // When decompression occurred, skip content-encoding and content-length
+                    // as they refer to the compressed data, not the decompressed stream.
+                    if (wasDecompressed && (key === 'content-encoding' || key === 'content-length')) {
+                        continue;
+                    }
+                    // Skip if value is undefined
+                    if (value !== undefined) {
+                        destination.setHeader(key, value);
+                    }
                 }
             }
             destination.statusCode = statusCode;
@@ -756,6 +869,13 @@ export default class Request extends Duplex {
     _onRequest(request) {
         const { options } = this;
         const { timeout, url } = options;
+        // Publish request start event
+        publishRequestStart({
+            requestId: this._requestId,
+            url: url?.toString() ?? '',
+            method: options.method,
+            headers: options.headers,
+        });
         timer(request);
         this._cancelTimeouts = timedOut(request, timeout, url);
         if (this.options.http2) {
@@ -805,6 +925,19 @@ export default class Request extends Duplex {
         if (is.nodeStream(body)) {
             body.pipe(currentRequest);
         }
+        else if (is.buffer(body)) {
+            // Buffer should be sent directly without conversion
+            this._writeRequest(body, undefined, () => { });
+            currentRequest.end();
+        }
+        else if (is.typedArray(body)) {
+            // Typed arrays should be treated like buffers, not iterated over
+            // Create a Uint8Array view over the data (Node.js streams accept Uint8Array)
+            const typedArray = body;
+            const uint8View = new Uint8Array(typedArray.buffer, typedArray.byteOffset, typedArray.byteLength);
+            this._writeRequest(uint8View, undefined, () => { });
+            currentRequest.end();
+        }
         else if (is.asyncIterable(body) || (is.iterable(body) && !is.string(body) && !isBuffer(body))) {
             (async () => {
                 try {
@@ -832,47 +965,111 @@ export default class Request extends Duplex {
         }
     }
     _prepareCache(cache) {
-        if (!cacheableStore.has(cache)) {
-            const cacheableRequest = new CacheableRequest(((requestOptions, handler) => {
-                const result = requestOptions._request(requestOptions, handler);
-                // TODO: remove this when `cacheable-request` supports async request functions.
-                if (is.promise(result)) {
-                    // We only need to implement the error handler in order to support HTTP2 caching.
-                    // The result will be a promise anyway.
-                    // @ts-expect-error ignore
-                    result.once = (event, handler) => {
-                        if (event === 'error') {
-                            (async () => {
-                                try {
-                                    await result;
-                                }
-                                catch (error) {
-                                    handler(error);
-                                }
-                            })();
+        if (cacheableStore.has(cache)) {
+            return;
+        }
+        const cacheableRequest = new CacheableRequest(((requestOptions, handler) => {
+            /**
+            Wraps the cacheable-request handler to run beforeCache hooks.
+            These hooks control caching behavior by:
+            - Directly mutating the response object (changes apply to what gets cached)
+            - Returning `false` to prevent caching
+            - Returning `void`/`undefined` to use default caching behavior
+
+            Hooks use direct mutation - they can modify response.headers, response.statusCode, etc.
+            Mutations take effect immediately and determine what gets cached.
+            */
+            const wrappedHandler = handler ? (response) => {
+                const { beforeCacheHooks, gotRequest } = requestOptions;
+                // Early return if no hooks - cache the original response
+                if (!beforeCacheHooks || beforeCacheHooks.length === 0) {
+                    handler(response);
+                    return;
+                }
+                try {
+                    // Call each beforeCache hook with the response
+                    // Hooks can directly mutate the response - mutations take effect immediately
+                    for (const hook of beforeCacheHooks) {
+                        const result = hook(response);
+                        if (result === false) {
+                            // Prevent caching by adding no-cache headers
+                            // Mutate the response directly to add headers
+                            response.headers['cache-control'] = 'no-cache, no-store, must-revalidate';
+                            response.headers.pragma = 'no-cache';
+                            response.headers.expires = '0';
+                            handler(response);
+                            // Don't call remaining hooks - we've decided not to cache
+                            return;
                         }
-                        else if (event === 'abort' || event === 'destroy') {
-                            // The empty catch is needed here in case when
-                            // it rejects before it's `await`ed in `_makeRequest`.
-                            (async () => {
-                                try {
-                                    const request = (await result);
-                                    request.once(event, handler);
-                                }
-                                catch { }
-                            })();
+                        if (is.promise(result)) {
+                            // BeforeCache hooks must be synchronous because cacheable-request's handler is synchronous
+                            throw new TypeError('beforeCache hooks must be synchronous. The hook returned a Promise, but this hook must return synchronously. If you need async logic, use beforeRequest hook instead.');
                         }
-                        else {
-                            /* istanbul ignore next: safety check */
-                            throw new Error(`Unknown HTTP2 promise event: ${event}`);
+                        if (result !== undefined) {
+                            // Hooks should return false or undefined only
+                            // Mutations work directly - no need to return the response
+                            throw new TypeError('beforeCache hook must return false or undefined. To modify the response, mutate it directly.');
                         }
-                        return result;
-                    };
+                        // Else: void/undefined = continue
+                    }
                 }
-                return result;
-            }), cache);
-            cacheableStore.set(cache, cacheableRequest.request());
-        }
+                catch (error) {
+                    // Convert hook errors to RequestError and propagate
+                    // This is consistent with how other hooks handle errors
+                    if (gotRequest) {
+                        gotRequest._beforeError(error instanceof RequestError ? error : new RequestError(error.message, error, gotRequest));
+                        // Don't call handler when error was propagated successfully
+                        return;
+                    }
+                    // If gotRequest is missing, log the error to aid debugging
+                    // We still call the handler to prevent the request from hanging
+                    console.error('Got: beforeCache hook error (request context unavailable):', error);
+                    // Call handler with response (potentially partially modified)
+                    handler(response);
+                    return;
+                }
+                // All hooks ran successfully
+                // Cache the response with any mutations applied
+                handler(response);
+            } : handler;
+            const result = requestOptions._request(requestOptions, wrappedHandler);
+            // TODO: remove this when `cacheable-request` supports async request functions.
+            if (is.promise(result)) {
+                // We only need to implement the error handler in order to support HTTP2 caching.
+                // The result will be a promise anyway.
+                // @ts-expect-error ignore
+                result.once = (event, handler) => {
+                    if (event === 'error') {
+                        (async () => {
+                            try {
+                                await result;
+                            }
+                            catch (error) {
+                                handler(error);
+                            }
+                        })();
+                    }
+                    else if (event === 'abort' || event === 'destroy') {
+                        // The empty catch is needed here in case when
+                        // it rejects before it's `await`ed in `_makeRequest`.
+                        (async () => {
+                            try {
+                                const request = (await result);
+                                request.once(event, handler);
+                            }
+                            catch { }
+                        })();
+                    }
+                    else {
+                        /* istanbul ignore next: safety check */
+                        throw new Error(`Unknown HTTP2 promise event: ${event}`);
+                    }
+                    return result;
+                };
+            }
+            return result;
+        }), cache);
+        cacheableStore.set(cache, cacheableRequest.request());
     }
     async _createCacheableRequest(url, options) {
         return new Promise((resolve, reject) => {
@@ -884,9 +1081,15 @@ export default class Request extends Duplex {
                 response._readableState.autoDestroy = false;
                 if (request) {
                     const fix = () => {
+                        // For ResponseLike objects from cache, set complete to true if not already set.
+                        // For real HTTP responses, copy from the underlying response.
                         if (response.req) {
                             response.complete = response.req.res.complete;
                         }
+                        else if (response.complete === undefined) {
+                            // ResponseLike from cache should have complete = true
+                            response.complete = true;
+                        }
                     };
                     response.prependOnceListener('end', fix);
                     fix();
@@ -915,7 +1118,14 @@ export default class Request extends Duplex {
             }
         }
         if (options.decompress && is.undefined(headers['accept-encoding'])) {
-            headers['accept-encoding'] = supportsBrotli ? 'gzip, deflate, br' : 'gzip, deflate';
+            const encodings = ['gzip', 'deflate'];
+            if (supportsBrotli) {
+                encodings.push('br');
+            }
+            if (supportsZstd) {
+                encodings.push('zstd');
+            }
+            headers['accept-encoding'] = encodings.join(', ');
         }
         if (username || password) {
             const credentials = Buffer.from(`${username}:${password}`).toString('base64');
@@ -928,12 +1138,10 @@ export default class Request extends Duplex {
                 headers.cookie = cookieString;
             }
         }
-        // Reset `prefixUrl`
-        options.prefixUrl = '';
         let request;
         for (const hook of options.hooks.beforeRequest) {
             // eslint-disable-next-line no-await-in-loop
-            const result = await hook(options);
+            const result = await hook(options, { retryCount: this.retryCount });
             if (!is.undefined(result)) {
                 // @ts-expect-error Skip the type mismatch to support abstract responses
                 request = () => result;
@@ -947,6 +1155,8 @@ export default class Request extends Duplex {
             this._requestOptions._request = request;
             this._requestOptions.cache = options.cache;
             this._requestOptions.body = options.body;
+            this._requestOptions.beforeCacheHooks = options.hooks.beforeCache;
+            this._requestOptions.gotRequest = this;
             try {
                 this._prepareCache(options.cache);
             }
@@ -973,15 +1183,15 @@ export default class Request extends Duplex {
             if (isClientRequest(requestOrResponse)) {
                 this._onRequest(requestOrResponse);
             }
-            else if (this.writable) {
+            else if (this.writableEnded) {
+                void this._onResponse(requestOrResponse);
+            }
+            else {
                 this.once('finish', () => {
                     void this._onResponse(requestOrResponse);
                 });
                 this._sendBody();
             }
-            else {
-                void this._onResponse(requestOrResponse);
-            }
         }
         catch (error) {
             if (error instanceof CacheableCacheError) {
@@ -992,26 +1202,58 @@ export default class Request extends Duplex {
     }
     async _error(error) {
         try {
-            if (error instanceof HTTPError && !this.options.throwHttpErrors) {
+            if (this.options && error instanceof HTTPError && !this.options.throwHttpErrors) {
                 // This branch can be reached only when using the Promise API
                 // Skip calling the hooks on purpose.
                 // See https://github.com/sindresorhus/got/issues/2103
             }
-            else {
-                for (const hook of this.options.hooks.beforeError) {
-                    // eslint-disable-next-line no-await-in-loop
-                    error = await hook(error);
+            else if (this.options) {
+                const hooks = this.options.hooks.beforeError;
+                if (hooks.length > 0) {
+                    for (const hook of hooks) {
+                        // eslint-disable-next-line no-await-in-loop
+                        error = await hook(error);
+                        // Validate hook return value
+                        if (!(error instanceof Error)) {
+                            throw new TypeError(`The \`beforeError\` hook must return an Error instance. Received ${is.string(error) ? 'string' : String(typeof error)}.`);
+                        }
+                    }
+                    // Mark this error as processed by hooks so _destroy preserves custom error types.
+                    // Only mark non-RequestError errors, since RequestErrors are already preserved
+                    // by the instanceof check in _destroy (line 642).
+                    if (!(error instanceof RequestError)) {
+                        errorsProcessedByHooks.add(error);
+                    }
                 }
             }
         }
         catch (error_) {
             error = new RequestError(error_.message, error_, this);
         }
+        // Publish error event
+        publishError({
+            requestId: this._requestId,
+            url: this.options?.url?.toString() ?? '',
+            error,
+            timings: this.timings,
+        });
         this.destroy(error);
+        // Manually emit error for Promise API to ensure it receives it.
+        // Node.js streams may not re-emit if an error was already emitted during retry attempts.
+        // Only emit for Promise API (_noPipe = true) to avoid double emissions in stream mode.
+        // Use process.nextTick to defer emission and allow destroy() to complete first.
+        // See https://github.com/sindresorhus/got/issues/1995
+        if (this._noPipe) {
+            process.nextTick(() => {
+                this.emit('error', error);
+            });
+        }
     }
     _writeRequest(chunk, encoding, callback) {
         if (!this._request || this._request.destroyed) {
-            // Probably the `ClientRequest` instance will throw
+            // When there's no request (e.g., using cached response from beforeRequest hook),
+            // we still need to call the callback to allow the stream to finish properly.
+            callback();
             return;
         }
         this._request.write(chunk, encoding, (error) => {
@@ -1120,4 +1362,10 @@ export default class Request extends Duplex {
     get reusedSocket() {
         return this._request?.reusedSocket;
     }
+    /**
+    Whether the stream is read-only. Returns `true` when `body`, `json`, or `form` options are provided.
+    */
+    get isReadonly() {
+        return !is.undefined(this.options?.body) || !is.undefined(this.options?.json) || !is.undefined(this.options?.form);
+    }
 }