Allow conditional capture of response stream with body inspection handler

[julealgon]

Proposal

BodyInspectionHandlerOption should provide a way to only intercept responses under specific conditions, such as only for specific status codes, or only when no factory is registered for that response in the proxy (when it "doesn't know how to parse the contents").

The current implementation is wasteful as it will unconditionally copy the stream's contents every single time, which does not align with consumer flows where we only want to inspect the contents on specific situations.

Context

We have an API that does not itself produce any 400 BadRequest results, so its OpenApi document does not contain that possibility. However, we have seen in our production environment some bad requests coming out of it. We suspect the 400 responses are coming from Azure API Management, where our API is hosted.

Because it is not explicitly mapped in the OpenAPI spec, we need a way to access the contents of the body only when kiota has failed to parse that response (or, as a fallback, we would only want to check 400 responses but that is more specific).

With the current implementation of BodyInspectionHandlerOption and BodyInspectionHandler, the consumer is forced to always inspect either the request or response: there is no way to do so conditionally.

Workarounds

As of now I don't see any option to make this conditional unless we decided to implement our own HttpClient delegating handler, defeating the entire purpose of the body inspection handler.

For now, we'll go ahead with always requesting the response body but only evaluate it when an ApiException is thrown, but this will end up consuming significantly more memory for us for no particular reason.

Related:

• http - implement body inspection handler #482

[Rans4ckeR]

Also as a consequence I believe every request needs to be wrapped in a try/catch/finally block to dispose the stream.

This stream is not disposed of by kiota, you need to take care of that.

In the code below in case of an ApiException the StreamReader will by default close the stream. But for a succesful response the stream will not be closed, hence the finally block.

var bodyInspectionHandlerOption = new BodyInspectionHandlerOption
{
    InspectResponseBody = true
};

try
{
    var response = await client.PostAsync(request, q => q.Options.Add(bodyInspectionHandlerOption)).ConfigureAwait(false);
}
catch (ApiException ex)
{
    using var reader = new StreamReader(bodyInspectionHandlerOption.ResponseBody, Encoding.UTF8);
    string response = await reader.ReadToEndAsync().ConfigureAwait(ConfigureAwaitOptions.None);

    logger.LogErrorMessage(response);
}
finally
{
    await bodyInspectionHandlerOption.ResponseBody.DisposeAsync().ConfigureAwait(false);
}