Some service client calls are throwing exceptions that aren't annotated

[tscni]

Take for example PredictionServiceClient:

google-cloud-php/Retail/src/V2/Gapic/PredictionServiceGapicClient.php

Lines 423 to 425 in d108fd6

	* @throws ApiException if the remote call fails
	*/
	public function predict($placement, $userEvent, array $optionalArgs = [])

PredictionServiceClient::predict() declares that it can throw Google\ApiCore\ApiException, but there's no mention of the GuzzleHttp\Exception\GuzzleExceptions that it will throw e.g. as part of the authentication flow.

I brought this up in googleapis/gax-php#474, but it seems on the side of google/gax this behavior is intended.
(see also that issue for a reproduction case)

Thus the exception signatures on these clients are currently unreliable.

[bshaffer]

@tscni thank you for reporting this issue! You are correct that the underlying auth library can throw a Guzzle exception. We can look at updating the PHPDoc to reflect this.

The interesting thing to me though is that using HTTP to call the OAuth2 token endpoint is something the the library should only be doing in very rare cases. As long as you use Service Account Credentials, the underlying auth library will sign a JWT token with those credentials and call the Retail API directly.

Looking at your example code in the linked issue (thank you for providing it!), you're using user credentials (client_id/client_secret) instead of service account credentials (private_key_id,private_key). Is this intentional (e.g. your library is making calls on behalf of a 3rd party and so needs to use 3LO auth flow), or is this a case where you could switch to using Service Account Credentials instead?

[tscni]

The actual issue behind it is that we use several of these APIs (not just retail) in local dev environments that occasionally don't have an active internet connection. There we don't use service accounts but rather generated user credentials.

Obviously that's not too important. The more important part is that we start to doubt the reliability of the library and rather tend to put all related calls in a try ... catch(Throwable) block.
Maybe there are other exception types that might be thrown in some edge case circumstances?
(I.e. it's more a theoretical than a practical issue)

I actually don't quite understand why you wouldn't want to wrap the Guzzle exceptions in an ApiException to keep the API surface simple.