refactor: make HttpCall context explicit

[aajtodd]

Issue \

related: https://github.com/awslabs/smithy-kotlin/issues/935

Description of changes

This PR refactors the HttpCall and HttpResponse types to not be data classes and documents the structured concurrency relationships related to servicing an HTTP response body

• Added a new supplementary doc describing the coroutine scopes in play for an operation
• Updated HttpCall to implement CoroutineScope
• Updated HttpCall to cancel in flight work whenever the call context does not immediately transition to the completed state.
  • The only reason it SHOULDN'T be completed is if there are remaining background coroutines active. We may find this to be too aggressive cancellation policy in time or across different engines. Time will tell.
• Updated HttpCall to be an open class that engines can override. This allows the new cancelInFlight method to overridden by sub-classes to implement engine specific all cancellation.
• Updated HttpResponse to be a sealed interface rather than a data class
• Threaded a CoroutineScope argument through toSdkByteReadChannel
• Refactored HttpDeserialize to take HttpCall instead of just HttpResponse. This is to allow a fix for #935 where we need to launch background work related to fulfilling the event stream response.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[sonarcloud[bot]]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
1 Code Smell

No Coverage information
0.0% Duplication