Provide a setter for emulator host

[Gerschtli]

Is your feature request related to a problem? Please describe.

When I write an integration test and I use a new emulator instance every test with different port numbers, I need to copy the setup logic from FirestoreOptions.Builder.build to configure the connection.

Describe the solution you'd like

I would like to see a setter for the emulator host value, which overrides the value of FIRESTORE_EMULATOR_HOST.
I tried to implement it to clarify my intention:

commit d5e6586e3ba78f3cda6dec0b6a0fb9dcec807cfb
Author: Tobias Happ <tobias.happ@gmx.de>
Date:   2020-08-06 21:31:12 +0200

    feat: add getEmulatorHost for FirestoreOptions
---
 .../google/cloud/firestore/FirestoreOptions.java   | 23 +++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/google-cloud-firestore/src/main/java/com/google/cloud/firestore/FirestoreOptions.java b/google-cloud-firestore/src/main/java/com/google/cloud/firestore/FirestoreOptions.java
index a65abca..4542504 100644
--- a/google-cloud-firestore/src/main/java/com/google/cloud/firestore/FirestoreOptions.java
+++ b/google-cloud-firestore/src/main/java/com/google/cloud/firestore/FirestoreOptions.java
@@ -63,6 +63,7 @@ public final class FirestoreOptions extends ServiceOptions<Firestore, FirestoreO
   private final boolean timestampsInSnapshotsEnabled;
   private final TransportChannelProvider channelProvider;
   private final CredentialsProvider credentialsProvider;
+  private final String emulatorHost;
 
   public static class DefaultFirestoreFactory implements FirestoreFactory {
 
@@ -117,12 +118,17 @@ public final class FirestoreOptions extends ServiceOptions<Firestore, FirestoreO
     return channelProvider;
   }
 
+  public String getEmulatorHost() {
+    return emulatorHost;
+  }
+
   public static class Builder extends ServiceOptions.Builder<Firestore, FirestoreOptions, Builder> {
 
     @Nullable private String databaseId = null;
     @Nullable private Boolean timestampsInSnapshotsEnabled = null;
     @Nullable private TransportChannelProvider channelProvider = null;
     @Nullable private CredentialsProvider credentialsProvider = null;
+    @Nullable private String emulatorHost = null;
 
     private Builder() {}
 
@@ -132,6 +138,7 @@ public final class FirestoreOptions extends ServiceOptions<Firestore, FirestoreO
       this.timestampsInSnapshotsEnabled = options.timestampsInSnapshotsEnabled;
       this.channelProvider = options.channelProvider;
       this.credentialsProvider = options.credentialsProvider;
+      this.emulatorHost = options.emulatorHost;
     }
 
     /**
@@ -189,6 +196,16 @@ public final class FirestoreOptions extends ServiceOptions<Firestore, FirestoreO
       return this;
     }
 
+    /**
+     * Sets the emulator host to use with this Firestore client.
+     *
+     * @param emulatorHost The Firestore emulator host to use with this client.
+     */
+    public Builder setEmulatorHost(@Nonnull String emulatorHost) {
+      this.emulatorHost = emulatorHost;
+      return this;
+    }
+
     @Override
     @Nonnull
     public FirestoreOptions build() {
@@ -201,7 +218,9 @@ public final class FirestoreOptions extends ServiceOptions<Firestore, FirestoreO
       }
 
       // Override credentials and channel provider if we are using the emulator.
-      String emulatorHost = System.getenv(FIRESTORE_EMULATOR_SYSTEM_VARIABLE);
+      if (emulatorHost == null) {
+        emulatorHost = System.getenv(FIRESTORE_EMULATOR_SYSTEM_VARIABLE);
+      }
       if (emulatorHost != null) {
         // Try creating a host in order to validate that the host name is valid.
         try {
@@ -290,6 +309,8 @@ public final class FirestoreOptions extends ServiceOptions<Firestore, FirestoreO
         builder.credentialsProvider != null
             ? builder.credentialsProvider
             : GrpcTransportOptions.setUpCredentialsProvider(this);
+
+    this.emulatorHost = builder.emulatorHost;;
   }
 
   private static class FirestoreDefaults implements ServiceDefaults<Firestore, FirestoreOptions> {

Describe alternatives you've considered

The alternative is to copy the setup logic used in FirestoreOptions.Builder.build but this does unnecessarily increase code duplication and complexity.

Additional information

I would like to contribute to help this feature request get implemented. I am looking forward for your feedback!

[wu-hui]

Hi @Gerschtli

Thank you so much for helping to make our SDK better!

I think having a host settings on top of env variable is very helpful for integration tests, can you open up a PR if that is OK with you?

Also, changing public API surface requires to be reviewed by our API team (across all SDKs), so the actual approval for you PR might come a bit slow.

Thank you again!

[BenWhitehead]

One thing to keep in mind as you are working on this. When an emulator is connected to there is additional setup that has to take place. Hopefully, adding the parameter will be enough and the rest of the code will be just fine, however if not; things to look into:

1. Ensure that the connection to the emulator is plaintext since the emulator only supports http
2. Ensure that the credentials pass the necessary headers to allow the emulator to perform admin actions see EmulatorCredentials

[wu-hui]

FWIW, you can also just use below snippet to setup tests against emulator:

    FirestoreOptions firestoreOptions = FirestoreOptions.newBuilder()
            .setChannelProvider(InstantiatingGrpcChannelProvider.newBuilder()
                    .setEndpoint("localhost:8080")
                    .setChannelConfigurator(
                            new ApiFunction<ManagedChannelBuilder, ManagedChannelBuilder>() {
                              @Override
                              public ManagedChannelBuilder apply(ManagedChannelBuilder input) {
                                return input.usePlaintext();
                              }
                            })
                    .build())
            .setCredentials(new FirestoreOptions.EmulatorCredentials())
            .build();
    Firestore firestore = firestoreOptions.getService();

[Gerschtli]

Thank you for your responses. I will try creating a PR for this.

@wu-hui Yes this works, but why should a user of the library copy-paste this snippet over and over? A more concise API would be easier to understand and maintain.