makes HTTP and HTTPS calls. It lets you specify which responses to return and
then verify that requests were made as expected.

Because it exercises your full HTTP stack, you can be confident that you're
testing everything. You can even copy & paste HTTP responses from your real web
server to create representative test cases. Or test that your code survives in
awkward-to-reproduce situations like 500 errors or slow-loading responses.

   * [response]. Returns null if the challenge cannot be satisfied.
   *
   * The route is best effort, it currently may not always be provided even when logically
   * available. It may also not be provided when an authenticator is re-used manually in an
   * application interceptor, such as when implementing client-specific retries.
   */
  @Throws(IOException::class)
  fun authenticate(
    route: Route?,
    response: Response,

    require(length < bytesOut.size - lastFrame.start)

    // Move everything from bytesOut into a new buffer.
    val fullBuffer = Buffer()
    bytesOut.read(fullBuffer, bytesOut.size)

    // Copy back all but what we're truncating.
    fullBuffer.read(bytesOut, lastFrame.start + length)
    outFrames.add(OutFrame(lastFrame.sequence, lastFrame.start, true))
    return writer
  }

  fun takeFrame(): InFrame = inFrames.take()

Events
======

Events allow you to capture metrics on your application’s HTTP calls. Use events to monitor:

 * The size and frequency of the HTTP calls your application makes. If you’re making too many calls, or your calls are too large, you should know about it!
 * The performance of these calls on the underlying network. If the network’s performance isn’t sufficient, you need to either improve the network or use less of it.

### EventListener

#### Shared reader thread

We can't rely on application threads to read data from the socket. Application threads are transient: sometimes they're reading and writing and sometimes they're off doing application-layer things. But the socket is permanent, and it needs constant attention: we dispatch all incoming frames so the connection is good-to-go when the application layer needs it.

    try {
      while (tcpConnectsInFlight.isNotEmpty() || routePlanner.hasNext()) {
        if (routePlanner.isCanceled()) throw IOException("Canceled")

        // Launch a new connection if we're ready to.
        val now = taskRunner.backend.nanoTime()
        var awaitTimeoutNanos = nextTcpConnectAtNanos - now
        var connectResult: ConnectResult? = null

      // Parse each header.
      for (i in 0 until responseHeaders.size) {
        if (!responseHeaders.name(i).equals(HEADER_WEB_SOCKET_EXTENSION, ignoreCase = true)) {
          continue // Not a header we're interested in.
        }
        val header = responseHeaders.value(i)

        // Parse each extension.
        var pos = 0
        while (pos < header.length) {

          result.add(trustedCert)
        }
        if (verifySignature(trustedCert, trustedCert, result.size - 2)) {
          return result // The self-signed cert is a root CA. We're done.
        }
        foundTrustedCertificate = true
        continue
      }

      // Search for the certificate in the chain that signed this certificate. This is typically

import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public final class PostMultipart {
  /**
   * The imgur client ID for OkHttp recipes. If you're using imgur for anything other than running
   * these examples, please request your own client ID! https://api.imgur.com/oauth2
   */
  private static final String IMGUR_CLIENT_ID = "9199fdef135c122";

The response answers the request with a code (like 200 for success or 404 for not found), headers, and its own optional body.

## Rewriting Requests

When you provide OkHttp with an HTTP request, you’re describing the request at a high-level: _“fetch me this URL with these headers.”_ For correctness and efficiency, OkHttp rewrites your request before transmitting it.