Class RemoteJwksSource.Builder

java.lang.Object
com.revetsec.jose.RemoteJwksSource.Builder
Enclosing class:
RemoteJwksSource

@NotThreadSafe @CheckReturnValue public static final class RemoteJwksSource.Builder extends Object
Builds a RemoteJwksSource.

Each setter stores its value, and build() checks them all, in this order: each setting against its range, then the time-to-live order, then the unknown-key refresh cooldown against the minimum time to live; the minimum Java runtime; an injected client's redirect policy; then the URI. null restores a setting's default. Nothing here does I/O.

Since:
1.0.0
Author:
Mark Allen
  • Method Details

    • httpClient

      Sets the HTTP client to fetch with. Build rejects redirect following, an Authenticator or a CookieHandler without sending a request. The application owns injected TLS/proxy configuration and egress beyond URI checks.
      Parameters:
      httpClient - a client using Redirect.NEVER, with no Authenticator or CookieHandler; null restores the default, a process-wide client Revetsec creates on the first fetch
      Returns:
      this builder
      Since:
      1.0.0
    • outboundUriPolicy

      Sets the policy the URI must pass.
      Parameters:
      outboundUriPolicy - the policy; null restores the default, OutboundUriPolicy.defaultInstance()
      Returns:
      this builder
      Since:
      1.0.0
    • allowInsecureLoopback

      Sets whether plain http is allowed to a loopback address or to exactly localhost, for tests. A request to localhost reaches loopback only as the host's name resolution decides, which usually means its hosts file.
      Parameters:
      allowInsecureLoopback - whether to allow it; null restores the default, false
      Returns:
      this builder
      Since:
      1.0.0
    • clock

      Sets the clock for the time to live, cooldown, backoff and staleness. Outside tests, keep the default: a clock that stands still never lets the key set expire.
      Parameters:
      clock - the clock; null restores the default, Clock.systemUTC()
      Returns:
      this builder
      Since:
      1.0.0
    • requestTimeout

      Sets how long one fetch may take, which is also the deadline of a standalone call.
      Parameters:
      requestTimeout - from 1 to 60 seconds; null restores the default, 10 seconds
      Returns:
      this builder
      Since:
      1.0.0
    • minimumTimeToLive

      Sets the shortest time a fetched key set is cached, whatever its cache headers say. It must be at least the unknown-key refresh cooldown, so that the limit of two requests per cooldown holds back no refresh after expiry unless fetches were cut short; build() checks that.
      Parameters:
      minimumTimeToLive - from 30 seconds to 1 hour, and no shorter than the unknown-key refresh cooldown; null restores the default, 1 minute
      Returns:
      this builder
      Since:
      1.0.0
    • defaultTimeToLive

      Sets the time a fetched key set is cached when its response has neither max-age nor Expires.
      Parameters:
      defaultTimeToLive - from 30 seconds to 24 hours; null restores the default, 10 minutes
      Returns:
      this builder
      Since:
      1.0.0
    • maximumTimeToLive

      Sets the longest time a fetched key set is cached, whatever its cache headers say.
      Parameters:
      maximumTimeToLive - from 1 minute to 24 hours; null restores the default, 6 hours
      Returns:
      this builder
      Since:
      1.0.0
    • unknownKeyRefreshCooldown

      Sets the shortest time between two refreshes that tokens with unknown key IDs trigger. It is also the first step of the backoff after a failed fetch, and the window of the limit of two requests of any kind. It must be no longer than the minimum time to live, so that this limit holds back no refresh after expiry unless fetches were cut short; build() checks that.
      Parameters:
      unknownKeyRefreshCooldown - from 1 second to 10 minutes, and no longer than the minimum time to live; null restores the default, 30 seconds
      Returns:
      this builder
      Since:
      1.0.0
    • maximumStaleness

      Sets how long after it expires a key set may still answer for the keys it holds, while refreshes fail or are held back.
      Parameters:
      maximumStaleness - from zero, which never serves an expired key set, to 24 hours; null restores the default, 12 hours
      Returns:
      this builder
      Since:
      1.0.0
    • maximumResponseBytes

      Sets the largest key set response body accepted, in bytes.
      Parameters:
      maximumResponseBytes - from 16 KiB to 4 MiB; null restores the default, 256 KiB
      Returns:
      this builder
      Since:
      1.0.0
    • maximumKeys

      Sets the most keys a key set may hold, counting every element of its keys array, usable or not.
      Parameters:
      maximumKeys - from 1 to 1,000; null restores the default, 100
      Returns:
      this builder
      Since:
      1.0.0
    • observer

      Sets the observer that receives this source's events.
      Parameters:
      observer - the observer; null restores the default, JoseObserver.disabledInstance()
      Returns:
      this builder
      Since:
      1.0.0
    • acknowledgeUnpatchedRuntime

      Sets whether to allow a Java runtime below Revetsec's minimum for network I/O (17.0.3, or 18.0.1 on Java 18), whose TLS and certificate checks are exposed to CVE-2022-21449. The choice is reported to JoseObserver.didUseUnpatchedRuntime(String) when the source is built and on every fetch.
      Parameters:
      acknowledgeUnpatchedRuntime - whether to accept the risk; null restores the default, false
      Returns:
      this builder
      Since:
      1.0.0
    • build

      Builds the source, with no I/O.
      Returns:
      a new source
      Throws:
      IllegalArgumentException - if a setting is out of range, the time-to-live settings are not ordered minimum, default, maximum, the unknown-key refresh cooldown is longer than the minimum time to live, the injected client follows redirects, or the URI is not permitted
      IllegalStateException - if the Java runtime is below Revetsec's minimum for network I/O and that was not acknowledged
      Since:
      1.0.0