*
 * As persistence, implementations of this interface must also provide storage of cookies. Simple
 * implementations may store cookies in memory; sophisticated ones may use the file system or
 * database to hold accepted cookies. The [cookie storage model][rfc_6265_53] specifies policies for
 * updating and expiring cookies.
 *

# Basic Usage

```kotlin
  private val client: OkHttpClient = OkHttpClient.Builder()
      .cache(Cache(
          directory = File(application.cacheDir, "http_cache"),
          // $0.05 worth of phone storage in 2020
          maxSize = 50L * 1024L * 1024L // 50 MiB
      ))
      .build()
```

## EventListener events 

Cache Events are exposed via the EventListener API.  Typical scenarios are below.

 * class to read a response that is larger than the entire memory allocated to the current process.
 * It can even stream a response larger than the total storage on the current device, which is a
 * common requirement for video streaming applications.
 *
 * Because this class does not buffer the full response in memory, the application may not

    try {
      editor?.abort()
    } catch (_: IOException) {
    }
  }

  /**
   * Initialize the cache. This will include reading the journal files from the storage and building
   * up the necessary in-memory cache information.
   *
   * The initialization time may vary depending on the journal file size and the current actual

 *  New: Use TLSv1.3 when running on JDK 8u261 or newer.
 *  New: `QueueDispatcher.clear()` may be used to reset a MockWebServer instance.
 *  New: `FileDescriptor.toRequestBody()` may be particularly useful for users of Android's Storage
    Access Framework.
 *  Upgrade: [Kotlin 1.5.31][kotlin_1_5_31].
 *  Upgrade: [Okio 3.0.0][okio_3_0_0].


## Version 5.0.0-alpha.2

_2021-01-30_

  private val algorithmParameters: DerAdapter<Any?> =
    Adapters.usingTypeHint { typeHint ->
      when (typeHint) {
        // This type is pretty strange. The spec says that for certain algorithms we must encode null
        // when it is present, and for others we must omit it!
        // https://tools.ietf.org/html/rfc4055#section-2.1

    internal var noTransform: Boolean = false
    internal var immutable: Boolean = false

    /** Don't accept an unvalidated cached response. */
    fun noCache() = commonNoCache()

    /** Don't store the server's response in any cache. */
    fun noStore() = commonNoStore()

    /**
     * Only accept the response if it is in the cache. If the response isn't cached, a `504

    `Handshake.get()` with a null TLS version, you must instead now provide a
    non-null `TlsVersion`. Cache responses persisted prior to OkHttp 3.0 did not
    store a TLS version; for these unknown values the handshake is defaulted to
    `TlsVersion.SSL_3_0`.

 *  New: Upgrade to Okio 1.13.0.

     ```xml
     <dependency>
       <groupId>com.squareup.okio</groupId>

        .minFresh(3, TimeUnit.SECONDS)
        .onlyIfCached()
        .noTransform()
        .immutable()
        .build()
    assertThat(cacheControl.toString()).isEqualTo(
      "no-cache, no-store, max-age=1, max-stale=2, min-fresh=3, only-if-cached, " +
        "no-transform, immutable",
    )
    assertThat(cacheControl.noCache).isTrue()
    assertThat(cacheControl.noStore).isTrue()

internal fun CacheControl.commonToString(): String {
  var result = headerValue
  if (result == null) {
    result =
      buildString {
        if (noCache) append("no-cache, ")
        if (noStore) append("no-store, ")
        if (maxAgeSeconds != -1) append("max-age=").append(maxAgeSeconds).append(", ")
        if (sMaxAgeSeconds != -1) append("s-maxage=").append(sMaxAgeSeconds).append(", ")
        if (isPrivate) append("private, ")