Document HttpClient usage with encoder/decoder and proper disposal

[asarkar]

It's unclear how encoder/decoder (or codecs as known pre Netty 5) are to be used with HttpClient. It's also unclear how and when to properly dispose a HttpClientResponse. Consider the following Kotlin client code:

return response
  .flatMap {
      val statusCode = it.status().code()
      when (statusCode) {
          in 200..399 -> {
              // this ain't exactly reactive, but will do
              it.receive()
                .aggregate()
                .asString(StandardCharsets.UTF_8)
                .flatMap {
                    it.let {
                        val tree = objectMapper.readTree(it)
                        val status = tree.path("Outcome").textValue()
                        when (status) {
                            "Success" -> {
                                // parse response
                            }
                            else -> Mono.error(IOException("Server returned error: $status"))
                        }
                    }
                }
          }
          else -> Mono.error(IOException("Server returned HTTP status code: $statusCode"))
      }
  }
  .doOnError { it.printStackTrace() }
  .blockOptional(Duration.ofSeconds(10L))
  .orElseGet { Collections.emptyList() }

It's not exactly pretty due to deep nesting, which could be avoided if I could somehow register success and error handlers (based on response status). Also, the response is never disposed, which could lead to resource leak.

There is no documentation on HttpClient usage or best practices, and yes, I've looked at HttpClientTest.java before opening this issue. I understand that Spring WebClient might address these concerns, but WebClient isn't a standalone module, and I don't need the additional baggage that comes with WebFlux otherwise.