{ "type": "module", "source": "doc/api/api-redirecthandler.md", "modules": [ { "textRaw": "RedirectHandler", "name": "redirecthandler", "introduced_in": "v4.0.0", "type": "module", "stability": 2, "stabilityText": "Stable", "desc": "

A dispatch handler that follows HTTP redirects on behalf of another handler. It\nwraps a downstream handler and a dispatch function: when a redirectable\nresponse is received it transparently re-dispatches the request to the new\nlocation, forwarding the lifecycle callbacks to the wrapped handler only once a\nfinal (non-redirect) response is reached.

\n

Redirects are followed for the 300, 301, 302, 303, 307, and 308\nstatus codes, up to maxRedirections hops. Following the relevant HTTP\nspecifications, the method is downgraded to GET for 301/302 POST\nresponses and for 303 responses with any method other than HEAD, request\nbodies that have already been consumed are not replayed, and headers that refer\nto the original URL (such as host) are stripped on each hop, with additional\ncredential headers removed on cross-origin redirects.

\n
import { RedirectHandler } from 'undici'\n
\n
const { RedirectHandler } = require('undici')\n
\n

Most users do not construct RedirectHandler directly. The maxRedirections\noption on Dispatcher methods and the higher-level clients use it\ninternally.

", "classes": [ { "textRaw": "Class: `RedirectHandler`", "name": "RedirectHandler", "type": "class", "meta": { "added": [ "v4.0.0" ], "changes": [] }, "desc": "\n

Implements the DispatchHandler interface, delegating every callback to the\nwrapped handler while intercepting redirect responses.

", "signatures": [ { "textRaw": "`new RedirectHandler(dispatch, maxRedirections, opts, handler)`", "name": "RedirectHandler", "type": "ctor", "meta": { "added": [ "v4.0.0" ], "changes": [] }, "params": [ { "textRaw": "`dispatch` {Function} The dispatch function used to issue the original request and every subsequent redirect. Called as `dispatch(options, handler)`.", "name": "dispatch", "type": "Function", "desc": "The dispatch function used to issue the original request and every subsequent redirect. Called as `dispatch(options, handler)`." }, { "textRaw": "`maxRedirections` {number|null} The maximum number of redirects to follow. Must be a non-negative integer or `null`. When `null` or `0`, no redirects are followed and redirect responses are passed through to the wrapped `handler`.", "name": "maxRedirections", "type": "number|null", "desc": "The maximum number of redirects to follow. Must be a non-negative integer or `null`. When `null` or `0`, no redirects are followed and redirect responses are passed through to the wrapped `handler`." }, { "textRaw": "`opts` {DispatchOptions} The dispatch options for the request. In addition to the standard dispatch options, the following redirect-specific fields are recognized:", "name": "opts", "type": "DispatchOptions", "desc": "The dispatch options for the request. In addition to the standard dispatch options, the following redirect-specific fields are recognized:", "options": [ { "textRaw": "`throwOnMaxRedirect` {boolean} When `true`, an error is thrown once `maxRedirections` is reached instead of returning the last redirect response. **Default:** `false`.", "name": "throwOnMaxRedirect", "type": "boolean", "default": "`false`", "desc": "When `true`, an error is thrown once `maxRedirections` is reached instead of returning the last redirect response." }, { "textRaw": "`stripHeadersOnRedirect` {string}[] Header names to remove from the request on every redirect hop. **Default:** `null`.", "name": "stripHeadersOnRedirect", "type": "string", "default": "`null`", "desc": "[] Header names to remove from the request on every redirect hop." }, { "textRaw": "`stripHeadersOnCrossOriginRedirect` {string}[] Additional header names to remove from the request when a redirect points to a different origin. **Default:** `null`.", "name": "stripHeadersOnCrossOriginRedirect", "type": "string", "default": "`null`", "desc": "[] Additional header names to remove from the request when a redirect points to a different origin." } ] }, { "textRaw": "`handler` {DispatchHandler} The downstream handler that receives the lifecycle callbacks for the final response.", "name": "handler", "type": "DispatchHandler", "desc": "The downstream handler that receives the lifecycle callbacks for the final response." } ], "desc": "

Throws an InvalidArgumentError when maxRedirections is not a non-negative\ninteger, when throwOnMaxRedirect is not a boolean, or when either\nstripHeadersOnRedirect or stripHeadersOnCrossOriginRedirect is not an array of\nheader-name strings.

\n
import { Client, RedirectHandler } from 'undici'\n\nconst client = new Client('http://example.com')\nconst dispatch = client.dispatch.bind(client)\n\nconst handler = new RedirectHandler(dispatch, 5, {\n  method: 'GET',\n  path: '/',\n  origin: 'http://example.com',\n}, {\n  onRequestStart () {},\n  onResponseStart (controller, statusCode, headers) {\n    console.log(statusCode)\n  },\n  onResponseData (controller, chunk) {},\n  onResponseEnd () {},\n})\n\ndispatch({ method: 'GET', path: '/', origin: 'http://example.com' }, handler)\n
" } ], "classMethods": [ { "textRaw": "Static method: `RedirectHandler.buildDispatch(dispatcher, maxRedirections)`", "name": "buildDispatch", "type": "classMethod", "meta": { "added": [ "v7.0.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`dispatcher` {Dispatcher} The dispatcher whose `dispatch` method is wrapped.", "name": "dispatcher", "type": "Dispatcher", "desc": "The dispatcher whose `dispatch` method is wrapped." }, { "textRaw": "`maxRedirections` {number|null} The maximum number of redirects to follow. Must be a non-negative integer or `null`.", "name": "maxRedirections", "type": "number|null", "desc": "The maximum number of redirects to follow. Must be a non-negative integer or `null`." } ], "return": { "textRaw": "Returns: {Function} A `dispatch(options, handler)` function that wraps each call in a `RedirectHandler` before delegating to `dispatcher`.", "name": "return", "type": "Function", "desc": "A `dispatch(options, handler)` function that wraps each call in a `RedirectHandler` before delegating to `dispatcher`." } } ], "desc": "

Builds a redirect-aware dispatch function from an existing dispatcher. The\nreturned function has the same shape as dispatcher.dispatch but follows\nredirects automatically. Throws an InvalidArgumentError when\nmaxRedirections is not a non-negative integer.

\n
import { Client, RedirectHandler } from 'undici'\n\nconst client = new Client('http://example.com')\nconst dispatch = RedirectHandler.buildDispatch(client, 5)\n\ndispatch({ method: 'GET', path: '/', origin: 'http://example.com' }, {\n  onRequestStart () {},\n  onResponseStart (controller, statusCode) {\n    console.log(statusCode)\n  },\n  onResponseData () {},\n  onResponseEnd () {},\n})\n
" } ], "methods": [ { "textRaw": "`redirectHandler.onRequestStart(controller, context)`", "name": "onRequestStart", "type": "method", "meta": { "added": [ "v7.0.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`controller` {DispatchController} The controller for the in-flight request.", "name": "controller", "type": "DispatchController", "desc": "The controller for the in-flight request." }, { "textRaw": "`context` {Object} The dispatch context.", "name": "context", "type": "Object", "desc": "The dispatch context." } ] } ], "desc": "

Forwards the request-start event to the wrapped handler, augmenting context\nwith the current redirect history.

" }, { "textRaw": "`redirectHandler.onRequestUpgrade(controller, statusCode, headers, socket)`", "name": "onRequestUpgrade", "type": "method", "meta": { "added": [ "v7.0.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`controller` {DispatchController} The controller for the in-flight request.", "name": "controller", "type": "DispatchController", "desc": "The controller for the in-flight request." }, { "textRaw": "`statusCode` {number} The HTTP status code of the upgrade response.", "name": "statusCode", "type": "number", "desc": "The HTTP status code of the upgrade response." }, { "textRaw": "`headers` {Object} The response headers.", "name": "headers", "type": "Object", "desc": "The response headers." }, { "textRaw": "`socket` {Duplex} The upgraded socket.", "name": "socket", "type": "Duplex", "desc": "The upgraded socket." } ] } ], "desc": "

Forwards a connection upgrade to the wrapped handler.

" }, { "textRaw": "`redirectHandler.onResponseStart(controller, statusCode, headers, statusMessage)`", "name": "onResponseStart", "type": "method", "meta": { "added": [ "v7.0.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`controller` {DispatchController} The controller for the in-flight request.", "name": "controller", "type": "DispatchController", "desc": "The controller for the in-flight request." }, { "textRaw": "`statusCode` {number} The HTTP status code of the response.", "name": "statusCode", "type": "number", "desc": "The HTTP status code of the response." }, { "textRaw": "`headers` {Object} The response headers.", "name": "headers", "type": "Object", "desc": "The response headers." }, { "textRaw": "`statusMessage` {string} The HTTP status message.", "name": "statusMessage", "type": "string", "desc": "The HTTP status message." } ] } ], "desc": "

Inspects the response headers to decide whether to follow a redirect. When the\nstatus code is redirectable, the maxRedirections limit has not been reached, and\nthe request body has not been consumed, the location property is set, the method\nand headers are adjusted for the next hop, and the response is not forwarded.\nOtherwise the event is forwarded to the wrapped handler.

\n

Throws when throwOnMaxRedirect is true and the number of recorded redirects\nhas reached maxRedirections, and throws an InvalidArgumentError if a\nredirect loop is detected (for example when a Client or Pool is used\nfor a cross-origin redirect; use an Agent instead).

" }, { "textRaw": "`redirectHandler.onResponseData(controller, chunk)`", "name": "onResponseData", "type": "method", "meta": { "added": [ "v7.0.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`controller` {DispatchController} The controller for the in-flight request.", "name": "controller", "type": "DispatchController", "desc": "The controller for the in-flight request." }, { "textRaw": "`chunk` {Buffer} A chunk of the response body.", "name": "chunk", "type": "Buffer", "desc": "A chunk of the response body." } ] } ], "desc": "

Forwards body data to the wrapped handler. While a redirect is pending\n(location is set), the 3xx response body is ignored.

" }, { "textRaw": "`redirectHandler.onResponseEnd(controller, trailers)`", "name": "onResponseEnd", "type": "method", "meta": { "added": [ "v7.0.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`controller` {DispatchController} The controller for the in-flight request.", "name": "controller", "type": "DispatchController", "desc": "The controller for the in-flight request." }, { "textRaw": "`trailers` {Object} The response trailers.", "name": "trailers", "type": "Object", "desc": "The response trailers." } ] } ], "desc": "

Completes the response. When a redirect is pending, the request is re-dispatched\nto the new location; otherwise the end event is forwarded to the wrapped\nhandler.

" }, { "textRaw": "`redirectHandler.onResponseError(controller, error)`", "name": "onResponseError", "type": "method", "meta": { "added": [ "v7.0.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`controller` {DispatchController} The controller for the in-flight request.", "name": "controller", "type": "DispatchController", "desc": "The controller for the in-flight request." }, { "textRaw": "`error` {Error} The error that occurred.", "name": "error", "type": "Error", "desc": "The error that occurred." } ] } ], "desc": "

Forwards the error to the wrapped handler.

" } ], "properties": [ { "textRaw": "Type: {string|null}", "name": "location", "type": "string|null", "meta": { "added": [ "v4.0.0" ], "changes": [] }, "desc": "

The Location header value of the redirect currently being followed, or null\nwhen no redirect is pending and the response is being passed through to the\nwrapped handler.

" }, { "textRaw": "Type: {DispatchOptions}", "name": "opts", "type": "DispatchOptions", "meta": { "added": [ "v7.12.0" ], "changes": [] }, "desc": "

A copy of the dispatch options for the next request. It excludes the redirect\ncontrol fields (maxRedirections, stripHeadersOnRedirect, and\nstripHeadersOnCrossOriginRedirect) and is mutated on each hop to reflect the\nupdated method, path, origin, and headers.

" }, { "textRaw": "Type: {number|null}", "name": "maxRedirections", "type": "number|null", "meta": { "added": [ "v4.0.0" ], "changes": [] }, "desc": "

The maximum number of redirects this handler will follow.

" }, { "textRaw": "Type: {DispatchHandler}", "name": "handler", "type": "DispatchHandler", "meta": { "added": [ "v4.0.0" ], "changes": [] }, "desc": "

The wrapped downstream handler that receives the lifecycle callbacks for the final\nresponse.

" }, { "textRaw": "Type: {URL}[]", "name": "history", "type": "URL", "meta": { "added": [ "v4.0.0" ], "changes": [] }, "desc": "

The ordered list of URLs visited while following redirects. It is used to enforce\nmaxRedirections and to detect redirect loops.

", "shortDesc": "[]" } ] } ] } ] }