*
 * Other exception types cancel the current call:
 *
 *  * For synchronous calls made with [Call.execute], the exception is propagated to the caller.
 *
 *  * For asynchronous calls made with [Call.enqueue], an [IOException] is propagated to the caller
 *    indicating that the call was canceled. The interceptor's exception is delivered to the current

    /**
     * Creates a new event source and immediately returns it. Creating an event source initiates an
     * asynchronous process to connect the socket. Once that succeeds or fails, `listener` will be
     * notified. The caller must cancel the returned event source when it is no longer in use.
     */
    fun newEventSource(
      request: Request,
      listener: EventSourceListener,
    ): EventSource
  }

  override fun request(): Request = originalRequest

  /**
   * Immediately closes the socket connection if it's currently held. Use this to interrupt an
   * in-flight request from any thread. It's the caller's responsibility to close the request body
   * and response body streams; otherwise resources may be leaked.
   *
   * This method is safe to be called concurrently, but provides limited guarantees. If a transport

  // These properties are guarded by [lock].

  /**
   * If true, no new exchanges can be created on this connection. It is necessary to set this to
   * true when removing a connection from the pool; otherwise a racing caller might get it from the
   * pool when it shouldn't. Symmetrically, this must always be checked before returning a
   * connection from the pool.
   *
   * Once true this is always true. Guarded by this.
   */

 *
 * Implementations authenticate by returning a follow-up request that includes an authorization
 * header, or they may decline the challenge by returning null. In this case the unauthenticated
 * response will be returned to the caller that triggered it.
 *
 * Implementations should check if the initial request already included an attempt to
 * authenticate. If so it is likely that further attempts will not be useful and the authenticator
 * should give up.

      client.newBuilder()
        .sslSocketFactory(handshakeCertificates.sslSocketFactory())
    }
  }

  /** Confirm that runtime exceptions thrown inside of OkHttp propagate to the caller.  */
  @Test
  fun unexpectedExceptionSync() {
    client =
      client.newBuilder()
        .dns { hostname: String? -> throw RuntimeException("boom!") }
        .build()

      mutablePos += bytesWritten
      mutableByteCount -= bytesWritten
    }
  }

  /**
   * Copy [byteCount] bytes from the file at [pos] into `sink`. It is the
   * caller's responsibility to make sure there are sufficient bytes to read: if there aren't this
   * method throws an `EOFException`.
   */
  fun read(
    pos: Long,
    sink: Buffer,
    byteCount: Long,
  ) {

    // 3 options here for ordering
    // 1) Legacy Platform - based on the Platform/Provider existing ordering in
    // sslSocket.enabledCipherSuites
    // 2) OkHttp Client - based on MODERN_TLS source code ordering
    // 3) Caller specified but assuming the visible defaults in MODERN_CIPHER_SUITES are rejigged
    // to match legacy i.e. the platform/provider
    //
    // Opting for 2 here and keeping MODERN_TLS in line with secure browsers.

 * Attempting to create new streams on these allocations will fail.
 *
 * Note that an allocation may be released before its stream is completed. This is intended to make
 * bookkeeping easier for the caller: releasing the allocation as soon as the terminal stream has
 * been found. But only complete the stream once its data stream has been exhausted.
 */
interface Connection {
  /** Returns the route used by this connection. */

    /**
     * Creates a new web socket and immediately returns it. Creating a web socket initiates an
     * asynchronous process to connect the socket. Once that succeeds or fails, `listener` will be
     * notified. The caller must either close or cancel the returned web socket when it is no longer
     * in use.
     */
    fun newWebSocket(
      request: Request,
      listener: WebSocketListener,
    ): WebSocket
  }