org.apache.hc.core5.http.protocol

## Class ForwardedRequest

- java.lang.Object
- - org.apache.hc.core5.http.protocol.ForwardedRequest

- All Implemented Interfaces:
    HttpRequestInterceptor

      @Contract(threading=IMMUTABLE)
      public class ForwardedRequest
      extends Object
      implements HttpRequestInterceptor

  This request interceptor can be used by an HTTP proxy or an intermediary to add a Forwarded header to outgoing request messages. The Forwarded header is used to capture information about the intermediate nodes that a request has passed through. This information can be useful for security purposes or for debugging purposes.

  The Forwarded header consists of a list of key-value pairs separated by semicolons. The keys that can be used in the Forwarded header include "host", "port", "proto", "for", and "by". The host key is used to specify the host name or IP address of the request authority. The port key is used to specify the port number of the request authority. The proto key is used to specify the protocol version of the request. The for key is used to specify the IP address of the client making the request. The by key is used to specify the IP address of the node adding the Forwarded header.

  When multiple proxy servers are involved in forwarding a request, each proxy can add its own Forwarded header to the request. This allows for the capture of information about each intermediate node that the request passes through.

  The ForwardedRequest class adds the Forwarded header to the request by implementing the process() method of the HttpRequestInterceptor interface. The method retrieves the ProtocolVersion and `URIAuthority` from the `HttpContext`. The ProtocolVersion is used to determine the proto key value and the `URIAuthority` is used to determine the host and port key values. The method also retrieves the `EndpointDetails` from the `HttpContext`, if it exists. The `EndpointDetails` is used to determine the by and for key values. If a Forwarded header already exists in the request, the existing header is not overwritten; instead, the new header value is appended to the existing header value, with a comma separator.

  Since:
    5.3

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static HttpRequestInterceptor` | `INSTANCE` Singleton instance.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ForwardedRequest()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `process(HttpRequest request, EntityDetails entity, HttpContext localContext)` The process method adds a Forwarded header to an HTTP request containing information about the intermediate nodes that the request has passed through.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### INSTANCE

          public static final HttpRequestInterceptor INSTANCE

      Singleton instance.

  - ### Constructor Detail

    - #### ForwardedRequest

          public ForwardedRequest()

  - ### Method Detail

    - #### process

          public void process(HttpRequest request,
                              EntityDetails entity,
                              HttpContext localContext)
                       throws HttpException,
                              IOException

      The process method adds a Forwarded header to an HTTP request containing information about the intermediate nodes that the request has passed through. If a Forwarded header already exists in the request, the new header value is appended to the existing header value, with a comma separator.

      The method retrieves the `ProtocolVersion` and `URIAuthority` from the HttpContext. The ProtocolVersion is used to determine the proto key value and the URIAuthority is used to determine the host and port key values. The method also retrieves the EndpointDetails from the `HttpContext`, if it exists. The `EndpointDetails` is used to determine the by key value.

      Specified by:
        `process` in interface `HttpRequestInterceptor`
      Parameters:
        `request` - the HTTP request to which the Forwarded header is to be added (not `null`)
        `entity` - the entity details of the request (can be `null`)
        `localContext` - the HTTP context in which the request is being executed (not `null`)
      Throws:
        `HttpException` - if there is an error processing the request
        `IOException` - if an IO error occurs while processing the request
        `ProtocolException` - if the request authority is not specified

Copyright © 2005–2021 The Apache Software Foundation. All rights reserved.