Package: groovy.http

## [Groovy] Class HttpBuilder.Config

- groovy.http.HttpBuilder.Config

-     static final class HttpBuilder.Config
      extends Object

  Configuration DSL used to create an HttpBuilder.

  Since:
    6.0.0

- - ### Properties Summary

    Properties
    Type | Name and description
    --- | ---
    `URI` | `baseUri` Absolute base URI used to resolve relative request URIs.
    `Closure<?>` | `clientConfigurer` Optional hook for advanced HttpClient.Builder customization.
    `boolean` | `confineToBaseUri` Whether request URIs are confined to baseUri.
    `Duration` | `connectTimeout` Timeout applied when opening connections.
    `boolean` | `followRedirects` Whether redirects should be followed automatically.
    `Map<String, String>` | `headers` Headers added to every request created by the builder.
    `Duration` | `requestTimeout` Timeout applied to each request when not overridden.

  - ### Constructor Summary

    Constructors
    Constructor and description
    `HttpBuilder.Config()`

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `void` | `baseUri(Object value)` Sets the absolute base URI used for relative requests.
    `` | `void` | `clientConfig(Closure<?> configurer)` Provides direct access to the underlying `HttpClient.Builder` for advanced configuration (authenticator, SSL context, proxy, cookie handler, etc.).
    `` | `void` | `confineToBaseUri(boolean value)` Confines every request to the configured baseUri.
    `` | `void` | `connectTimeout(Duration value)` Sets the client connect timeout.
    `` | `void` | `followRedirects(boolean value)` Enables or disables automatic redirect following.
    `` | `void` | `header(String name, Object value)` Adds a default header to every request.
    `` | `void` | `headers(Map<String, ?> values)` Adds multiple default headers to every request.
    `` | `void` | `requestTimeout(Duration value)` Sets the default request timeout.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Property Detail

    - #### URI baseUri

      Absolute base URI used to resolve relative request URIs.

    - #### Closure<?> clientConfigurer

      Optional hook for advanced HttpClient.Builder customization.

    - #### boolean confineToBaseUri

      Whether request URIs are confined to baseUri. When enabled, requests that resolve to a different origin (scheme, host, or effective port) or escape the base path prefix are rejected with a SecurityException. Requires `baseUri` to be configured.

    - #### Duration connectTimeout

      Timeout applied when opening connections.

    - #### boolean followRedirects

      Whether redirects should be followed automatically. When enabled, a hop that leaves the origin of the first request sheds the caller's headers; see followRedirects(boolean) for the full policy. Defaults to `false`, returning any 3xx response to the caller as-is.

    - #### final Map<String, String> headers

      Headers added to every request created by the builder.

    - #### Duration requestTimeout

      Timeout applied to each request when not overridden.

  - ### Constructor Detail

    - #### HttpBuilder.Config()

  - ### Method Detail

    - #### void baseUri(Object value)

      Sets the absolute base URI used for relative requests.

      Parameters:
        `value` - the base URI as a URI or coercible string

    - #### void clientConfig(@DelegatesTo(value=HttpClient.Builder, strategy=Closure.DELEGATE_FIRST)
      Closure<?> configurer)

      Provides direct access to the underlying `HttpClient.Builder` for advanced configuration (authenticator, SSL context, proxy, cookie handler, etc.).

      Redirect policy is the exception: it is owned by followRedirects so that every hop can be gated against confinement and against the origin the caller's headers were set for. A redirect policy set on the raw builder here is overridden.

      Parameters:
        `configurer` - a closure taking an `HttpClient.Builder`

    - #### void confineToBaseUri(boolean value)

      Confines every request to the configured baseUri. Absolute request URIs pointing at another origin, and relative URIs that walk above the base path (e.g. via `..` or a leading `/`), are rejected with a SecurityException instead of being executed.

      Parameters:
        `value` - `true` to reject requests that escape the base URI

    - #### void connectTimeout(Duration value)

      Sets the client connect timeout.

      Parameters:
        `value` - the connection timeout

    - #### void followRedirects(boolean value)

      Enables or disables automatic redirect following. When enabled, at most five hops are followed, rewriting methods like HttpClient.Redirect#NORMAL: 301/302 downgrade `POST` to `GET` (dropping the body), 303 downgrades everything except `HEAD` to `GET`, and 307/308 preserve the method and body.

      Headers are treated as configured for one origin: the scheme, host, and effective port of the first request. A hop that stays on that origin keeps every header. A hop that leaves it sheds all caller-supplied headers — builder defaults and per-request headers alike — for the remainder of the chain, including any later hop back to the original origin. The one exception is `Content-Type`, which stays with a 307/308 hop that forwards the body it describes. A hop from an https URL to a plain http one is never followed; the 3xx is returned to the caller. Callers who need credentials sent to a redirect target on another origin should issue a request to that target directly.

      Parameters:
        `value` - `true` to follow redirects

    - #### void header(String name, Object value)

      Adds a default header to every request.

      Parameters:
        `name` - the header name
        `value` - the header value

    - #### void headers(Map<String, ?> values)

      Adds multiple default headers to every request.

      Parameters:
        `values` - the headers to add

    - #### void requestTimeout(Duration value)

      Sets the default request timeout.

      Parameters:
        `value` - the request timeout