Package org.gradle.caching.http

# Class HttpBuildCache

java.lang.Object
org.gradle.caching.configuration.AbstractBuildCache
org.gradle.caching.http.HttpBuildCache

All Implemented Interfaces:
  `BuildCache`

public abstract class HttpBuildCache extends AbstractBuildCache
Configuration object for the HTTP build cache. Cache entries are loaded via GET and stored via PUT requests.

A successful GET request must return a response with status 200 (cache hit) or 404 (cache miss), with cache hit responses including the cache entry as the response body. A successful PUT request must return any 2xx response.

PUT requests may also return a 413 Payload Too Large response to indicate that the payload is larger than can be accepted. This is useful when `isUseExpectContinue()` is enabled.

Redirecting responses may be issued with 301, 302, 303, 307 or 308 responses. Redirecting responses to PUT requests must use 307 or 308 to have the PUT replayed. Otherwise, the redirect will be followed with a GET request.

Any other type of response will be treated as an error, causing the remote cache to be disabled for the remainder of the build.

When credentials are configured (see `getCredentials()`), they are sent using HTTP Basic Auth.

Requests that fail during request transmission, after having established a TCP connection, will automatically be retried. This includes dropped connections, read or write timeouts, and low level network failures such as a connection resets.

Since:
  3.5

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `HttpBuildCache()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `credentials(Action<? super HttpBuildCacheCredentials> configuration)`
  Configures the credentials used to access the HTTP cache backend.
  `HttpBuildCacheCredentials`
  `getCredentials()`
  Returns the credentials used to access the HTTP cache backend.
  `@Nullable URI`
  `getUrl()`
  Returns the URI to the cache.
  `boolean`
  `isAllowInsecureProtocol()`
  Specifies whether it is acceptable to communicate with a build cache over an insecure HTTP connection.
  `boolean`
  `isAllowUntrustedServer()`
  Specifies whether it is acceptable to communicate with an HTTP build cache backend with an untrusted SSL certificate.
  `boolean`
  `isUseExpectContinue()`
  Specifies whether HTTP expect-continue should be used for store requests.
  `void`
  `setAllowInsecureProtocol(boolean allowInsecureProtocol)`
  Specifies whether it is acceptable to communicate with a build cache over an insecure HTTP connection.
  `void`
  `setAllowUntrustedServer(boolean allowUntrustedServer)`
  Specifies whether it is acceptable to communicate with an HTTP build cache backend with an untrusted SSL certificate.
  `void`
  `setUrl(String url)`
  Sets the URL of the cache.
  `void`
  `setUrl(@Nullable URI url)`
  Sets the URL of the cache.
  `void`
  `setUrl(URL url)`
  Sets the URL of the cache.
  `void`
  `setUseExpectContinue(boolean useExpectContinue)`
  Specifies whether HTTP expect-continue should be used for store requests.

  ### Methods inherited from class org.gradle.caching.configuration.AbstractBuildCache

  `isEnabled, isPush, setEnabled, setPush`

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

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

- ## Constructor Details

  - ### HttpBuildCache

    public HttpBuildCache()

- ## Method Details

  - ### getUrl

    public @Nullable URI getUrl()
    Returns the URI to the cache.

  - ### setUrl

    public void setUrl(String url)
    Sets the URL of the cache. The URL must end in a '/'.

  - ### setUrl

    public void setUrl(URL url) throws URISyntaxException
    Sets the URL of the cache. The URL must end in a '/'.
    Throws:
      `URISyntaxException`

  - ### setUrl

    public void setUrl(@Nullable URI url)
    Sets the URL of the cache. The URL must end in a '/'.

  - ### getCredentials

    public HttpBuildCacheCredentials getCredentials()
    Returns the credentials used to access the HTTP cache backend.

  - ### credentials

    public void credentials(Action<? super HttpBuildCacheCredentials> configuration)
    Configures the credentials used to access the HTTP cache backend.

  - ### isAllowUntrustedServer

    public boolean isAllowUntrustedServer()
    Specifies whether it is acceptable to communicate with an HTTP build cache backend with an untrusted SSL certificate.

    The SSL certificate for the HTTP build cache backend may be untrusted since it is internally provisioned or a self-signed certificate.

    In such a scenario, you can either configure the build JVM environment to trust the certificate, or set this property to `true` to disable verification of the server's identity.

    Allowing communication with untrusted servers keeps data encrypted during transmission, but makes it easier for a man-in-the-middle to impersonate the intended server and capture data.

    This value has no effect if a server is specified using the HTTP protocol (i.e. has SSL disabled).

    Since:
      4.2

  - ### setAllowUntrustedServer

    public void setAllowUntrustedServer(boolean allowUntrustedServer)
    Specifies whether it is acceptable to communicate with an HTTP build cache backend with an untrusted SSL certificate.
    Since:
      4.2
    See Also:
      - `isAllowUntrustedServer()`

  - ### isAllowInsecureProtocol

    public boolean isAllowInsecureProtocol()
    Specifies whether it is acceptable to communicate with a build cache over an insecure HTTP connection.

    For security purposes this intentionally requires a user to opt-in to using insecure protocols on case by case basis.

    Gradle intentionally does not offer a global system/gradle property that allows a universal disable of this check.

    Allowing communication over insecure protocols allows for a man-in-the-middle to impersonate the intended server, and gives an attacker the ability to serve malicious executable code onto the system.

    See also: Want to take over the Java ecosystem? All you need is a MITM!

    Since:
      6.0

  - ### setAllowInsecureProtocol

    public void setAllowInsecureProtocol(boolean allowInsecureProtocol)
    Specifies whether it is acceptable to communicate with a build cache over an insecure HTTP connection.
    Since:
      6.0
    See Also:
      - `isAllowInsecureProtocol()`

  - ### setUseExpectContinue

    public void setUseExpectContinue(boolean useExpectContinue)
    Specifies whether HTTP expect-continue should be used for store requests.
    Since:
      7.2

  - ### isUseExpectContinue

    public boolean isUseExpectContinue()
    Specifies whether HTTP expect-continue should be used for store requests. This value defaults to `false`. When enabled, whether or not a store request would succeed is checked with the server before attempting. This is particularly useful when potentially dealing with large artifacts that may be rejected by the server with a 413 Payload Too Large response, as it avoids the overhead of transmitting the large file just to have it rejected. This fail-fast behavior comes at the expense of extra marginal overhead for successful requests, due to the extra network communication required by the initial check. Note: not all HTTP servers support expect-continue.
    Since:
      7.2
    See Also:
      - `setUseExpectContinue(boolean)`