fix: update exception mapping on HTTP error responses

[chanseokoh]

The HTTP-to-Canonical code conversion (HttpJsonStatusCode.httpStatusToStatusCode()) is used only for error situations where a server returns a non-2xx HTTP status code. gax-java surfaces errors in terms of ApiExceptions, which are modeled precisely following the canonical status codes (go/canonical-codes). (That is, there's a one-to-one correspondence between the canonical error codes and the Java exceptions.) That's why and the only reason we need to interpret HTTP codes as canonical codes.

The previous implementation wasn't following the standardized mapping (go/http-canonical-mapping). Now we are trying to make this consistent across all languages. Therefore, this does introduce a breaking change in terms of which HTTP server response code is surfaced as which Java exception.

However, for the conventional commit message and the PR title, I'm not marking as a breaking change, as gax-httpjson hasn't GA'ed.

b/205195666

---

Appendix

The locations where the HTTP-to-canonical conversion takes place:

• HttpJsonExceptionCallable.onFailure(): HTTP error status is interpreted as canonical error status (via exception).

    public void onFailure(Throwable throwable) {
      if (throwable instanceof HttpResponseException) {
        HttpResponseException e = (HttpResponseException) throwable;
        // HttpResponseException.getStatusCode() returns HTTP code
        StatusCode statusCode = HttpJsonStatusCode.of(e.getStatusCode());
        boolean canRetry = retryableCodes.contains(statusCode.getCode());
        String message = e.getStatusMessage();
        ApiException newException =
            message == null
                ? ApiExceptionFactory.createException(throwable, statusCode, canRetry)
                : ApiExceptionFactory.createException(message, throwable, statusCode, canRetry);
        super.setException(newException);

• HttpJsonOperationSnapshot.Builder.setError(): the builder takes an HTTP code. Note there's no usage of setError() within gax-java. It is supposed to take HTTP code, but for some legacy reason, it treats 0 as a special case to indicate success (which is not ideal).

    public Builder setError(int httpStatus, String errorMessage) {
      this.errorCode =
          httpStatus == 0 ? HttpJsonStatusCode.of(Code.OK) : HttpJsonStatusCode.of(httpStatus);
      this.errorMessage = errorMessage;
      return this;
    }

[chanseokoh]

@meltsufin @vam-google ready for review. Check out the PR description for details.

[meltsufin]

LGTM.

[vam-google]

LGTM, but we need to test it with java-compute properly before GA, as it may affect its behavior and retries in particular.

[vam-google]

Is mapping 300s to unknown intentional and canonical behavior here?

[chanseokoh]

Yes, All 3xx's are mapped to UNKNOWN according to go/http-canonical-mapping.

[chanseokoh]

As mentioned in b/205195666, I have conducted multiple tests for this change, whose results seem all good. @vam-google merging this now, but if you want me to do some other tests, just let me know.