grpc-java/documentation/android-binderchannel-status-codes.md

Android gRPC/BinderChannel Status Codes

Background

BinderChannel is a gRPC transport that lets Android apps communicate across processes using familiar gRPC concepts and APIs. A BinderChannel-backed gRPC request can fail for many Android-specific reasons, both at ServiceConnection establishment and at transact() time. These transport-specific failures must be reported to clients using gRPC’s standard canonical status code abstraction. This document enumerates the BinderChannel errors one can expect to encounter, specifies a canonical status code mapping for each possibility and discusses how clients should handle them.

Status Code Mapping

Consider the table that follows as an BinderChannel-specific addendum to the “Codes that may be returned by the gRPC libraries” document. Mappings in that table that share a status code with one of the binder-specific mappings are repeated here for comparison.

#	Error Case	Android API Manifestation	Status Code	Expected Client Handling
1	Server app not installed	bindService() returns false	UNIMPLEMENTED “The operation is not implemented or is not supported / enabled in this service.”	Direct the user to install/reinstall the server app.
2	Old version of the server app doesn’t declare the target android.app.Service in its manifest.
3	Target android.app.Service is disabled
4	The whole server app is disabled
5	Server app predates the Android M permissions model and the user must review and approve some newly requested permissions before it can run.
6	Target android.app.Service doesn’t recognize grpc binding Intent (old version of server app?)	onNullBinding() ServiceConnection callback
7	Method not found on the io.grpc.Server (old version of server app?)	N/A
8	Request cardinality violation (old version of server app expects unary rather than streaming, say)
9	Old version of the server app exposes target android.app.Service but doesn’t android:export it.	bindService() throws SecurityException	PERMISSION_DENIED “The caller does not have permission to execute the specified operation …”
10	Target android.app.Service requires an <android:permission> that client doesn’t hold.			Prompt the user to grant the needed Android permission
11	Violations of the security policy for miscellaneous Android features like android:isolatedProcess, android:externalService, android:singleUser, instant apps, BIND_TREAT_LIKE_ACTIVITY, etc,			Give up - This is a programming or packaging error that only the app developer can fix.
12	Calling Android UID not allowed by ServerSecurityPolicy	N/A
13	Server Android UID not allowed by client’s SecurityPolicy
14	Server process crashed or killed with request in flight.	onDisconnected() ServiceConnection callback	UNAVAILABLE “The service is currently unavailable. This is most likely a transient condition, which can be corrected by retrying with a backoff ...”	Retry with exponential backoff and deadline (see ManagedChannelBuilder#enableRetry()
		onBinderDied() IBinder.DeathRecipient callback
		IBinder.transact() throws DeadObjectException
15	Server app is currently being upgraded to a new version	onBindingDied() ServiceConnection callback
16	The whole server app or the target android.app.Service was disabled
17	Binder transaction buffer overflow	IBinder.transact() throws TransactionTooLargeException
18	Source Context for bindService() is destroyed with a request in flight	onDestroy()	CANCELLED “The operation was cancelled, typically by the caller.”	Give up for now. (Re. 18: The caller can try again later when the user opens the source Activity or restarts the source Service)
19	Client application cancelled the request	N/A
19	Bug in Android itself or the way the io.grpc.binder transport uses it.	IBinder.transact() returns false	INTERNAL “This means that some invariants expected by the underlying system have been broken. … Reserved for serious errors.”	Give up - This is a programming error that only the app or grpc developers can fix
		bindService() throws IllegalArgumentException
20	Flow-control protocol violation	N/A
21	Can’t parse request/response proto

Ambiguity

We say a status code is ambiguous if it maps to two error cases that reasonable clients want to handle differently. For instance, a client may have good reasons to handle error cases 9 and 10 above differently. But they can’t do so based on status code alone because those error cases map to the same one.

In contrast, for example, even though error case 18 and 19 both map to the status code (CANCELLED), they are not ambiguous because we see no reason that clients would want to distinguish them. In both cases, clients will simply give up on the request.

Ambiguity of PERMISSION_DENIED and Mitigations

The mapping above has only one apparently ambiguous status code: PERMISSION_DENIED. However, this isn’t so bad because of the following:

The use of <android:permission>s for inter-app IPC access control (error case 10) is uncommon. Instead, we recommend that server apps only allow IPC from a limited set of client apps known in advance and identified by signature.

However, there may be gRPC server apps that want to use custom <android:permission>’s to let the end user decide which arbitrary other apps can make use of its gRPC services. In that case, clients should preempt error case 10 simply by checking whether they hold the required permissions before sending a request.

Server apps can avoid error case 9 by never reusing an android.app.Service as a gRPC host if it has ever been android:exported=false in some previous app version. Instead they should simply create a new android.app.Service for this purpose.

Only error cases 11 - 13 remain, making PERMISSION_DENIED unambiguous for the purpose of error handling. Reasonable client apps can handle it in a generic way by displaying an error message and/or proceeding with degraded functionality.

Non-Ambiguity of UNIMPLEMENTED

The UNIMPLEMENTED status code corresponds to quite a few different problems with the server app: It’s either not installed, too old, or disabled in whole or in part. Despite the diversity of underlying error cases, we believe most client apps will and should handle UNIMPLEMENTED in the same way: by sending the user to the app store to (re)install the server app. Reinstalling might be overkill for the disabled cases but most end users don't know what it means to enable/disable an app and there’s neither enough space in a UI dialog nor enough reader attention to explain it. Reinstalling is something users likely already understand and very likely to cure problems 1-8.

Detailed Discussion of Binder Failure Modes

IBinder.transact() returns false

According to the docs, false “generally means the transaction code was not understood.” This is true for synchronous transactions but all gRPC/BinderChannel transactions are FLAG_ONEWAY meaning the calling thread doesn’t wait around for the server to return from onTransact(). Examination of the AOSP source code shows several additional undocumented reasons transact() could return false but all of these cases should be impossible and aren’t things that reasonable apps want to handle.

IBinder.transact() Throws an Exception

According to the docs, transact() can throw RemoteException but the significance of this exception isn’t documented. By inspection of the AOSP source, we see there are several cases:

1. The remote process is no longer alive (android.os.DeadObjectException)
2. The IPC buffer is full (android.os.TransactionTooLargeException)
3. Certain internal errors from the underlying ioctl() system call.

Status code mappings:

Exception	Status Code	Rationale
android.os.DeadObjectException	UNAVAILABLE	So the caller can retry against a new incarnation of the server process
android.os.TransactionTooLargeException	UNAVAILABLE	These are usually transient. A retry is likely to succeed later when demand for the IPC buffer subsides.
Some other RemoteException	INTERNAL	So the caller doesn’t bother retrying
Some other RuntimeException	INTERNAL

bindService() returns false

According to the docs, this bindService() returns false when “the system couldn't find the service or if your client doesn't have permission to bind to it.” However, the part about permission is somewhat misleading.

According to a review of the AOSP source code, there are in fact several cases:

1. The target package is not installed
2. The target package is installed but does not declare the target Service in its manifest.
3. The target package requests dangerous permissions but targets sdk <= M and therefore requires a permissions review, but the caller is not running in the foreground and so it would be inappropriate to launch the review UI.

Status code mapping: UNIMPLEMENTED

(1) and (2) are interesting new possibilities unique to on-device RPC. (1) is straightforward and the most likely cause of (2) is that the user has an old version of the server app installed that predates its gRPC integration. Many clients will want to handle these cases, likely by directing the user to the app store in order to install/upgrade the server.

Unfortunately UNIMPLEMENTED doesn’t capture (3) but none of the other canonical status codes do either and we expect this case to be extremely rare.

bindService() throws SecurityException

According to the docs, SecurityException is thrown “if the calling app does not have permission to bind to the given service”. There are quite a few specific cases:

1. The target Service sets android:exported = “false” in its manifest but the caller is in a different app.
2. The target Service declares a required permission in its manifest but the calling package doesn’t have it.
3. The target Service is marked as android:singleton in the manifest but doesn’t hold the INTERACT_ACROSS_USERS permission.
4. The caller is an android:isolatedProcess.
5. The caller requested certain security-related flags on the binding without the necessary permission (gRPC/BinderChannel doesn’t do this)
6. … according to the source code, a long tail of unlikely security-related internal errors.

Status code mapping: PERMISSION_DENIED.

bindService() throws IllegalArgumentException

There are a couple cases:

1. The binding Intent is not explicit.
2. The binding Intent contains file descriptors.

Status Code mapping: INTERNAL. These cases should be impossible.

onBindingDied() ServiceConnection callback

According to the docs: “... This means the interface will never receive another connection. The application will need to unbind and rebind the connection to activate it again. This may happen, for example, if the application hosting the service it is bound to has been updated.”

Status code mapping: UNAVAILABLE

UNAVAILABLE is the best mapping since a retry is likely to succeed in the near future once the server application finishes updating.

onNullBinding() ServiceConnection callback

According to the docs: “Called when the service being bound has returned null from its onBind() method. This indicates that the attempting service binding represented by this ServiceConnection will never become usable.”

Status code mapping: UNIMPLEMENTED

UNIMPLEMENTED is used here because a retry is likely to fail for the same reason. The most likely root cause for a null binding is an older version of the server app where the android.app.Service exists but either doesn’t implement onBind() or doesn’t recognize the grpc.io.action.BIND Intent action.

onServiceDisconnected() ServiceConnection callback

According to the docs: “Called when a connection to the Service has been lost. This typically happens when the process hosting the service has crashed or been killed ...”

Status code mapping: UNAVAILABLE

UNAVAILABLE is used here since a retry is likely to succeed against a newly restarted instance of the server.

Response Parcel Contains an Exception

Android’s Parcel class exposes a mechanism for marshalling certain types of RuntimeExceptions between traditional Binder IPC peers. However we won’t consider this case because gRPC/BinderChannel doesn’t use this mechanism. In fact, all BinderChannel transactions are FLAG_ONE_WAY so there is no response Parcel.

Source Context for bindService() is Destroyed

The calling Activity or Service Context might be destroyed with a gRPC request in flight. Apps should cease operations when the Context hosting it goes away and this includes cancelling any outstanding RPCs.

Status code mapping: CANCELLED