MONGOCRYPT-763 add in-place retry API

[mdb-ad]

Add in-place retry API to better support drivers that fan out KMS requests.

[addaleax]

I think this comment could be expanded a bit regarding the specific situations in which this method should be called and what exactly "reset" means w.r.t. the state of the kms handle?

[kevinAlbs]

Suggested change

	// Feed part of a response
	ASSERT_OK(mongocrypt_kms_ctx_feed(kms_ctx, TEST_FILE("./test/data/kms-aws/encrypt-response-partial.txt")),
	kms_ctx);
	// Assume a network error and reset the context.
	// Mark a network error.
	ASSERT_OK(mongocrypt_kms_ctx_fail(kms_ctx), kms_ctx);
	// Reset the context.

I expect feeding a partial response is not needed. If a driver gets a network error, the protocol expects the driver to call mongocrypt_kms_ctx_fail.

[kevinAlbs]

Suggest removing http from the name and documentation. I expect it may simplify the protocol to always call this function on error to check if a retry is needed. For example:

static bool
handle_kms_with_retry (mongocrypt_kms_ctx_t *kms, _state_machine_t *state_machine, bson_error_t *error)
{
   while (!handle_kms (kms, state_machine, error)) {
      // Error occurred.
      if (mongocrypt_kms_ctx_should_retry (kms)) {
         mongocrypt_kms_ctx_reset (kms);
         continue; // Retry.
      }
      return false; // Return error.
   }
   return true;
}

[kevinAlbs]

Suggest also documenting the in-place protocol in integrating.md.

[kevinAlbs]

Suggested change

	HTTP/1.1 200 OK
	x-amzn-RequestId: deeb35e5-4ecb-4bf1-9af5-84a54ff0af0e
	Content-Type: appli
	HTTP/1.1 200 OK
	x-amzn-RequestId: deeb35e5-4ecb-4bf1-9af5-84a54ff0af0e
	Content-Type: application/x-amz-json-1.1
	Content-Length: 446
	Connection: close
	{"KeyId": "arn:aws:k

Suggest including all headers and part of body. Otherwise, this sequence appears to succeed:

ASSERT_OK(mongocrypt_kms_feed(kms, TEST_FILE("./test/data/kms-aws/encrypt-response-partial.txt")), kms);
ASSERT_OK(mongocrypt_kms_feed(kms, TEST_FILE("./test/data/kms-aws/encrypt-response.txt")), kms);

I expect this is due to the extra headers being ignored. With this suggestion, the second call fails.

[kevinAlbs]

Consider adding an error check in mongocrypt_kms_ctx_feed, like:

if (mongocrypt_kms_ctx_should_retry_http(kms)) {
    CLIENT_ERR("Attempting to feed to KMS request requiring retry. Reset first.");
    return false;
}

That may help a driver identify a missing call to mongocrypt_kms_ctx_reset. I expect it may be difficult to diagnose a missing reset call.