need documentation about return code and how it may map to gRPC error code

[steverawlins-zebra]

I check the UNIX return code ($?) after executing grpcurl. It returns 0 for Success, as expected. Non-zero return codes, however, are garbled by what appears to be an extraneous bit.

For example, NOT FOUND is 5, but grpcurl returns 69. For INVALID_ARGUMENT (3), but grpcurl returns 67.

There is an extraneous bit in position 6 (lower-order bits are in position 0-3 and you find what I believe is the true code there)

0100 0101 = 0x45 but should be 5

You made need to use the GoLang "status" package https://pkg.go.dev/google.golang.org/grpc/status ~ > grpcurl -d '{ "source_system" : "UNKNOWN" }' -plaintext localhost:9090 tenant.TenantService.GetByEntitlementTenantId ERROR: Code: InvalidArgument Message: ~ > echo $? 67

Note that Success maps to 0 properly, as shown below:

~ > grpcurl -d '{ "tenant_id" : "5c7e1395-d2ab-4d91-b9f8-40d783cf6e12" }' -plaintext localhost:9090 tenant.TenantService.Get { "tenant_id": "5c7e1395-d2ab-4d91-b9f8-40d783cf6e12", "tenant_name": "Full Story", "created_time": "2021-02-24T00:46:33.533Z", "updated_time": "2021-02-24T00:46:33.533Z", "created_by": "Jason" } ~ > echo $? 0

[mawippel]

The answer to that can be found in lines 39 and 725.

To avoid confusion between program error codes and the gRPC response
status codes 'Cancelled' and 'Unknown', 1 and 2 respectively,
the response status codes emitted use an offest of 64

[steverawlins-zebra]

My reading of the standards is that, beyond zero, there really are not any. Furthermore, this article implies that 64-128 are taken! So, confusing story and perhaps better to have left the exit code alone so that grpcurl reports back using the grpc standard error codes.

https://unix.stackexchange.com/questions/110348/how-do-i-get-the-list-of-exit-codes-and-or-return-codes-and-meaning-for-a-comm

It appears that the only "standard" is 0 (zero) meaning success.

[jhump]

better to have left the exit code alone so that grpcurl reports back using the grpc standard error codes

Not all errors are grpc error codes. The program exits with 2 for incorrect usage (consistent with many unix programs including bash builtins) and 1 as a catch-all for other kinds of errors that do not come from the server's response. As indicated by @mawippel, the offset is intentional to avoid overloading these codes.

This is a mismatch with how you were hoping/expecting it to behave, but it is not a bug and is intentional. Changing it now would be backwards incompatible with any scripts written with the the proper logic to ascertain the gRPC code.

[steverawlins-zebra]

Thank you, Josh. I discovered the flag -format-error which returns the gRPC error code in a way that I can use in my tests.

I humbly recommend that you document the 64+x offset somewhere other than the code; perhaps in the README or the -help because it is important to know if you are coding scripts. You could mention that format-error returns, for NOT-FOUND, the expected value as JSON, which is a very nice feature. Great tool!

{ "code": 5 }

[jhump]

I've renamed the issue so it's a doc issue.