TrailersSource

[swankjesse]

I’ve got a sketch for the proper API for trailers:

class Response private constructor(
  ...
  private val trailersSource: TrailersSource,
) {
 
  /**
   * Blocks until the trailers are available
   * to read, and returns them.
   *
   * It is not safe to call this concurrently with
   * code that is processing the response body.
   * If you call this without consuming the complete
   * response body, any remaining bytes in the response
   * body will be discarded before trailers are returned.
   *
   * If [Call.cancel] is called while this is
   * blocking, this call will immediately throw. 
   *
   * @throws IllegalStateException if the response is closed.
   * @throws IOException if the trailers cannot be
   *     loaded, such as if the network connection is
   *     dropped.
   */
  @Throws(IOException)
  fun trailers(): Headers {
    return trailersSource.get()
  }
  
  class Builder {
    fun headers(headers: Headers): Builder

    fun status(status: Int): Builder

    fun body(source: BufferedSource): Builder

    fun body(
      source: BufferedSource, 
      trailersSource: TrailersSource = TrailersSource.EMPTY,
    ): Builder

    fun build(): Response
  }
}

fun interface TrailersSource {
  /**
   * Returns the trailers, blocking if they need
   * to be loaded.
   */
  @Throws(IOException::class)
  fun get(): Headers
  
  companion object { 
    val EMPTY: TrailersSource()
  }
}

There’s a promise in this doc that our current code doesn’t implement: it will discard the response body until trailers can be processed. We should do that, especially because the response body may be logically fully consumed without reading all of its bytes. For example, if the response is a JSON with a trailing \r\n, the JSON library probably won’t discard that trailing character for us.