ServiceBinding docs/tests

Author: jdcormie

binder/src/main/java/io/grpc/binder/internal/Bindable.java

@@ -48,7 +48,16 @@ interface Observer {
     void onUnbound(Status reason);
   }
 
-  /** Fetches details about the remote service from PackageManager *before* binding to it. */
+  /**
+   * Fetches details about the remote service from PackageManager without binding to it.
+   *
+   * <p>Resolving an untrusted address before binding to it lets you "screen" out problematic
+   * servers before giving them a chance to run. However, note that the identity/existence of the
+   * resolved Service can change between the time this method returns and the time you actually
+   * bind/connect to it. For example, suppose the target package gets uninstalled right after this
+   * method returns. In {@link Observer#onBound}, you should verify that the server you resolved is
+   * the same one you connected to.
+   */
   @AnyThread
   ServiceInfo resolve() throws StatusException;
 

binder/src/test/java/io/grpc/binder/internal/ServiceBindingTest.java

@@ -19,6 +19,7 @@
 import static android.content.Context.BIND_AUTO_CREATE;
 import static android.os.Looper.getMainLooper;
 import static com.google.common.truth.Truth.assertThat;
+import static org.junit.Assert.assertThrows;
 import static org.junit.Assert.fail;
 import static org.robolectric.Shadows.shadowOf;
 
@@ -35,6 +36,7 @@
 import androidx.test.core.app.ApplicationProvider;
 import io.grpc.Status;
 import io.grpc.Status.Code;
+import io.grpc.StatusException;
 import io.grpc.binder.BinderChannelCredentials;
 import io.grpc.binder.internal.Bindable.Observer;
 import java.util.Arrays;
@@ -79,6 +81,7 @@ public void setUp() {
 
     // Don't call onServiceDisconnected() upon unbindService(), just like the real Android doesn't.
     shadowApplication.setUnbindServiceCallsOnServiceDisconnected(false);
+    shadowApplication.setBindServiceCallsOnServiceConnectedDirectly(false);
 
     binding = newBuilder().build();
     shadowOf(getMainLooper()).idle();
@@ -283,18 +286,30 @@ public void testBindWithTargetUserHandle() throws Exception {
 
   @Test
   public void testResolve() throws Exception {
+    serviceInfo.processName = "x"; // ServiceInfo has no equals() so look for one distinctive field.
+    shadowOf(appContext.getPackageManager()).addOrUpdateService(serviceInfo);
     ServiceInfo resolvedServiceInfo = binding.resolve();
-    assertThat(resolvedServiceInfo.packageName).isEqualTo(serviceInfo.packageName);
-    assertThat(resolvedServiceInfo.name).isEqualTo(serviceInfo.name);
+    assertThat(resolvedServiceInfo.processName).isEqualTo(serviceInfo.processName);
   }
 
   @Test
   @Config(sdk = 33)
   public void testResolveWithTargetUserHandle() throws Exception {
+    serviceInfo.processName = "x"; // ServiceInfo has no equals() so look for one distinctive field.
+    // Robolectric just ignores the user arg to resolveServiceAsUser() so this is all we can do.
+    shadowOf(appContext.getPackageManager()).addOrUpdateService(serviceInfo);
     binding = newBuilder().setTargetUserHandle(generateUserHandle(/* userId= */ 0)).build();
     ServiceInfo resolvedServiceInfo = binding.resolve();
-    assertThat(resolvedServiceInfo.packageName).isEqualTo(serviceInfo.packageName);
-    assertThat(resolvedServiceInfo.name).isEqualTo(serviceInfo.name);
+    assertThat(resolvedServiceInfo.processName).isEqualTo(serviceInfo.processName);
+  }
+
+  @Test
+  public void testResolveNonExistentServiceThrows() throws Exception {
+    ComponentName doesNotExistService = new ComponentName("does.not.exist", "NoService");
+    binding = newBuilder().setTargetComponent(doesNotExistService).build();
+    StatusException statusException = assertThrows(StatusException.class, binding::resolve);
+    assertThat(statusException.getStatus().getCode()).isEqualTo(Code.UNIMPLEMENTED);
+    assertThat(statusException.getStatus().getDescription()).contains("does.not.exist");
   }
 
   @Test