]> Emilia Capital

joost@emilia.capital https://joost.blog/

Web and Internet Transport HTTP redirect debugging observability http header This document defines the Redirect-By HTTP response header field. It allows the software component whose decision determined an HTTP redirect to identify itself, so that an operator diagnosing a redirect can determine which component was responsible for it. The field succeeds the widely deployed, non-standard X-Redirect-By header, which this document deprecates.

Introduction An HTTP request for a given URL is frequently redirected by one of several independent components before it reaches an origin resource: a Content Delivery Network (CDN) edge rule, a reverse proxy, a load balancer, a Content Management System (CMS), or an application plugin may each issue a redirect. When such a redirect is misconfigured, an operator inspecting the response sees only the status code and the Location field (). Neither identifies which component in the chain produced the redirect. Diagnosis then proceeds by disabling components one at a time until the responsible one is found, which is slow and error prone. This document defines the Redirect-By response header field, whose value names the software component whose decision determined the redirect. Its presence turns an opaque redirect into a self-describing one: the responsible component is named in the response itself. The convention is widely deployed under the non-standard name X-Redirect-By. Since version 5.1, WordPress core has, by default, emitted X-Redirect-By on every redirect generated through wp_redirect(); wp_safe_redirect() delegates to that function. WordPress exposes the value through a filter so that themes and plugins can identify themselves . TYPO3 emits the field from its redirect and shortcut-handling middleware . This demonstrates deployment across multiple independent implementations and a large installed base; this document does not attempt to quantify the proportion of all HTTP redirects that carry the field. The header was originally proposed in . discourages the "X-" prefix for newly defined header fields but makes no recommendation about whether an existing "X-" field ought to migrate. This document chooses migration: it defines Redirect-By as the successor field, specified as a Structured Field , and deprecates X-Redirect-By while registering it so the registry reflects what is on the wire (, ). Existing implementations can send Redirect-By alongside X-Redirect-By during the transition ().

Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. The term "redirect" refers to a response with a 3xx (Redirection) status code (), other than 304 (Not Modified), that contains a Location field. The "redirect decision-maker" is the component whose decision determines the Location field of a redirect response. It is not necessarily the HTTP server or intermediary that serializes or forwards that response.

The Redirect-By Field The "Redirect-By" response header field allows the redirect decision-maker to identify itself. A redirect decision-maker MAY include a Redirect-By field in the response. When present, its value SHOULD begin with a URI that identifies the component, such as the component's home page. A URI avoids collisions between components that share a name and removes ambiguity about which component is meant. The remainder of the String MAY contain human-readable diagnostic context that helps an operator distinguish where the redirect came from, such as the installation, deployment, handler, function, plugin, or rule. For example: This document defines no structure for the additional context. Recipients MUST treat the entire String as opaque and MUST NOT assume that either the URI or additional context can be extracted from it. The field is informational and intended for human diagnosis of redirects. A recipient MUST NOT treat the presence, absence, or value of Redirect-By as altering the meaning of the redirect; the Location field and status code retain their full semantics independent of it. A recipient MUST NOT base automated decisions on the value: for example, it MUST NOT follow or ignore a redirect depending on whether the value matches a particular identifier, such as "https://cms.example.com/". A recipient that does not understand the field ignores it, as with any unrecognized field ().

Syntax Redirect-By is an Item Structured Field . Its value MUST be a String () naming the redirect decision-maker; this document defines no parameters. For example: or, with human-readable diagnostic context: Redirect-By is a singleton field, not a list. A sender MUST NOT generate more than one Redirect-By field line in a response. A recipient MUST process the field as a Structured Field Item; if that parsing fails, or the value is not a String, the recipient MUST ignore the field. This rule also disposes of duplicate field lines: combining them into a single value () produces a value that does not parse as an Item, so the field is ignored. The deployed X-Redirect-By field carries the identifier as free-form text rather than as a Structured Field; see .

Multiple Redirects and Intermediaries Where a request passes through several components that each redirect, each redirect is a separate response with its own decision-maker. Because a redirect is resolved one hop at a time, the value on any single response identifies the one component that determined the Location field for that hop. An intermediary that forwards a redirect response without changing its Location field SHOULD NOT add or modify Redirect-By, even if it modifies other parts of the response, such as the status code. An intermediary that changes the Location field thereby becomes the redirect decision-maker and MUST replace any existing Redirect-By value with its own identifier or remove the field.

Relationship to X-Redirect-By The information carried by Redirect-By has been deployed at scale under the non-standard name X-Redirect-By, which carries the identifier as free-form text: a sequence of visible ASCII characters, possibly with interior spaces, without Structured Field serialization. recommends against the "X-" prefix for new fields and against assuming any semantic distinction based only on whether a name has that prefix. This document deprecates X-Redirect-By and defines the following migration behavior:

• New implementations SHOULD send Redirect-By and SHOULD NOT send X-Redirect-By.
• Existing implementations that send X-Redirect-By SHOULD also send Redirect-By, and SHOULD stop sending X-Redirect-By once the recipients they serve recognize the new name.
• When an implementation sends both fields, both MUST name the same decision-maker, even though the serializations can differ: for example, X-Redirect-By: Yoast SEO Premium alongside Redirect-By: "Yoast SEO Premium".
• Recipients SHOULD recognize both names. A Redirect-By field that is not ignored under the rules of takes precedence over X-Redirect-By; a recipient MAY fall back to X-Redirect-By when Redirect-By is absent or ignored.

Deprecation records that use of the X-Redirect-By name is discouraged; it does not make existing responses that carry it invalid, and recipients are expected to keep recognizing the legacy name while it remains widely deployed.

Design Considerations

A Structured Field recommends that new HTTP fields use Structured Fields , and Redirect-By follows that recommendation. The deployed X-Redirect-By field predates this document and transmits its value as unquoted free-form text, so the two fields can differ on the wire: an identifier containing spaces is sent bare in X-Redirect-By but as a quoted String in Redirect-By. This document accepts that divergence. The value is always a String, never a Token. A single serialization supports both the recommended URI prefix and optional human-readable diagnostic context while keeping parsing simple. Migration already requires senders to adopt a new field name, so adopting the standard serialization at the same time costs little, and it buys well-defined parsing, an unambiguous rule for duplicate or combined field lines (), and the ability for future documents to extend the field with parameters.

Security Considerations Redirect-By is a voluntary disclosure of the identity of a redirecting component. It is not an authentication or integrity mechanism: its value is set by the sender and can be absent, forged, or copied, so a recipient MUST NOT rely on it to establish the provenance or trustworthiness of a redirect. Naming software in a response reveals information about a deployment that can aid an attacker in fingerprinting it. To limit this exposure, the value SHOULD be a coarse component identifier and SHOULD NOT include software versions, file system paths, internal host names, or the specific rule that matched. For example, "WordPress" is appropriate; "WordPress 6.5.2 via wp-content/plugins/acme/redirects.php:214" is not. The same applies to any additional diagnostic context carried after the URI: it SHOULD aid diagnosis without exposing internal host names or infrastructure details. Operators for whom any such disclosure is unacceptable can omit the field; it is optional.

Privacy Considerations The field describes server-side software, not the user. It carries no user identifier and introduces no new client-side state or tracking surface.

IANA Considerations IANA is requested to register the following two entries in the "Hypertext Transfer Protocol (HTTP) Field Name Registry" defined in . Redirect-By is requested as a permanent registration; the registry's procedure for permanent entries is Specification Required (), for which this document is the specification. X-Redirect-By is requested with a status of "deprecated", documenting the name under which the field was widely deployed before this document and recording that its use is discouraged (). Registering the ubiquitous legacy name is a record of existing practice, not the minting of a new "X-" field, and is therefore consistent with . Entry 1:

• Field Name: Redirect-By
• Status: permanent
• Structured Type: Item
• Reference: This document
• Comments: Successor to the deprecated X-Redirect-By field.

Entry 2:

• Field Name: X-Redirect-By
• Status: deprecated
• Structured Type: None
• Reference: This document
• Comments: Deprecated legacy name for the Redirect-By field ().

References Normative References The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. This document describes a set of data types and associated algorithms that are intended to make it easier and safer to define and handle HTTP header and trailer fields, known as "Structured Fields", "Structured Headers", or "Structured Trailers". It is intended for use by specifications of new HTTP fields. This document obsoletes RFC 8941. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References Historically, designers and implementers of application protocols have often distinguished between standardized and unstandardized parameters by prefixing the names of unstandardized parameters with the string "X-" or similar constructs. In practice, that convention causes more problems than it solves. Therefore, this document deprecates the convention for newly defined parameters with textual (as opposed to numerical) names in application protocols. This memo documents an Internet Best Current Practice. Many protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA). To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry. This is the third edition of this document; it obsoletes RFC 5226. Applications often use HTTP as a substrate to create HTTP-based APIs. This document specifies best practices for writing specifications that use HTTP to define new application protocols. It is written primarily to guide IETF efforts to define application protocols using HTTP for deployment on the Internet but might be applicable in other situations. This document obsoletes RFC 3205. WordPress n.d. TYPO3 n.d. n.d.

Acknowledgements The convention originated during the migration of The Guardian's website from guardian.co.uk to theguardian.com, in which multiple systems issued redirects simultaneously, and was first proposed publicly in . The author thanks the WordPress core contributors who implemented X-Redirect-By , and the maintainers of the other systems that adopted it, for establishing the deployed practice this document standardizes.