DOCSP-39164: Flutter: Change baseURL during runtime (#3239)

cbullinger · web-flow · commit ee4b327fdd4c · 2024-05-06T12:40:20.000-04:00
## Pull Request Info Jira ticket: https://jira.mongodb.org/browse/DOCSP-39164 - [Connect to App Services - Flutter SDK](https://preview-mongodbcbullinger.gatsbyjs.io/realm/docsp-39164-flutter-baseurl/sdk/flutter/app-services/connect-to-app/#connect-to-a-specific-server): New "Connect to a Specific Server" section with baseURL info. New "Connect to a Different Server During Runtime" subsection with info about the experimental API. - ### Reminder Checklist Before merging your PR, make sure to check a few things. - [x] Did you tag pages appropriately? - genre - meta.keywords - meta.description - [x] Describe your PR's changes in the Release Notes section - [x] Create a Jira ticket for related docs-app-services work, if any ### Release Notes - **Flutter SDK** - Atlas App Services/Connect to App Services: New "Connect to a Specific Server" section with baseURL info. New "Connect to a Different Server During Runtime" subsection with info about the experimental API. ### Review Guidelines [REVIEWING.md](https://github.com/mongodb/docs-realm/blob/master/REVIEWING.md)
diff --git a/examples/dart/pubspec.lock b/examples/dart/pubspec.lock
@@ -213,18 +213,18 @@ packages:
     dependency: transitive
     description:
       name: ejson
-      sha256: "2d69382ea016c5f38c9d966681b464ca23d5f594918d4cb7dfecf0a3dad31395"
+      sha256: f336c6fb6c5c97db8ae59ba8ed207f542241f1db39cf2ef03776d308de3432ff
       url: "https://pub.dev"
     source: hosted
-    version: "0.2.0-pre.1"
+    version: "0.3.0"
   ejson_annotation:
     dependency: transitive
     description:
       name: ejson_annotation
-      sha256: f14948884cf6d91e00c727d5ec6b2395bdcb511541aa7956e4e03b73cd089149
+      sha256: b265eea722ee340d77d1c36a55a1f963d517a0dabb569b0775664c319a4e3ebf
       url: "https://pub.dev"
     source: hosted
-    version: "0.2.0-pre.1"
+    version: "0.3.0"
   faker:
     dependency: "direct main"
     description:
@@ -437,26 +437,26 @@ packages:
     dependency: transitive
     description:
       name: realm_common
-      sha256: c4c994217c3f1dafdb3e36b5e3c75c6f4719fd5bd64f64a5acb79a5c962c018f
+      sha256: c04b64fcbcd0afd78c06939efdedb484417697242039d5bb0b07fa150c9c021d
       url: "https://pub.dev"
     source: hosted
-    version: "2.0.0"
+    version: "2.2.0"
   realm_dart:
     dependency: "direct main"
     description:
       name: realm_dart
-      sha256: "861b007dccf19ecfb1e7f47f2b0c246755b82c40e122d61fde18180dbbaf88a3"
+      sha256: b523d392ec614ccb358e64451aca4772d56db23f93e8f58dd1d1780dadc92706
       url: "https://pub.dev"
     source: hosted
-    version: "2.0.0"
+    version: "2.2.0"
   realm_generator:
     dependency: transitive
     description:
       name: realm_generator
-      sha256: "3cad739d4491bc5b4ccdd184083fd58f6899e410d0acda7448b60261639e2735"
+      sha256: a5c3c403add9d886c098509b49517f44f1d8b667ac0178f80f58fea5ce069fb8
       url: "https://pub.dev"
     source: hosted
-    version: "2.0.0"
+    version: "2.2.0"
   sane_uuid:
     dependency: transitive
     description:
@@ -674,4 +674,4 @@ packages:
     source: hosted
     version: "3.1.2"
 sdks:
-  dart: ">=3.2.0 <4.0.0"
+  dart: ">=3.3.0 <4.0.0"
diff --git a/examples/dart/pubspec.yaml b/examples/dart/pubspec.yaml
@@ -4,10 +4,10 @@ description: A simple command-line application using Realm Dart SDK.
 publish_to: none
 
 environment:
-  sdk: "^3.1.0"
+  sdk: ^3.3.0
 
 dependencies:
-  realm_dart: ^2.0.0
+  realm_dart: ^2.2.0
   path: ^1.8.2
   dart_jsonwebtoken: ^2.4.2
   faker: ^2.0.0
diff --git a/examples/dart/test/app_services_test.dart b/examples/dart/test/app_services_test.dart
@@ -3,9 +3,13 @@ import 'package:realm_dart/realm.dart';
 import "dart:io";
 import "dart:convert";
 import "dart:isolate";
+import 'utils.dart';
 
 void main() {
   const APP_ID = "example-testers-kvjdy";
+  const EDGE_SERVER_APP_ID = "sync-edge-server-cskhoow";
+  const baseUrl = 'http://localhost';
+  const newBaseUrl = 'https://services.cloud.mongodb.com';
 
   group('App Services client - ', () {
     test('Access App client', () {
@@ -29,24 +33,44 @@ void main() {
       expect(appConfig.defaultRequestTimeout, Duration(seconds: 120));
     });
 
-    test('BaseUrl not cached on App config', () {
-      final newUrl = Uri.parse('https://dart.dev');
-      
-      // Instantiate App with default BaseUrl
-      final appConfig = AppConfiguration(APP_ID,
-          defaultRequestTimeout: const Duration(seconds: 120)
-          );
+    test('Custom BaseUrl', () {
+      // :snippet-start: custom-base-url
+      // Specify a baseUrl to connect to a server other than the default
+      final appConfig =
+          AppConfiguration(APP_ID, baseUrl: Uri.parse('https://example.com'));
+
       var app = App(appConfig);
-      expect(app.baseUrl.toString(), 'https://realm.mongodb.com');
-
-      // Update with new BaseUrl
-      final newConfig = AppConfiguration(APP_ID,
-          defaultRequestTimeout: const Duration(seconds: 120), 
-          baseUrl:newUrl);
-      app = App(newConfig);
-      expect(app.baseUrl.toString(), 'https://dart.dev');
+      // :snippet-end:
+      expect(app.baseUrl.toString(), 'https://example.com');
     });
 
+    test('Change BaseUrl', () async {
+      // :snippet-start: change-base-url
+      // Specify a custom baseUrl to connect to.
+      // In this case, an Edge Server instance running on the device.
+      final appConfig = AppConfiguration(
+        EDGE_SERVER_APP_ID,
+        baseUrl: Uri.parse('http://localhost:80')
+        );
+
+      var app = App(appConfig);
+
+      // ... log in a user and use the app ...
+      // :remove-start:
+      expect(app.baseUrl.toString(), baseUrl);
+      await app.logIn(Credentials.anonymous());
+      expect(app.currentUser != null, true);
+      // :remove-end:
+
+      // Later, change the baseUrl to the default:
+      // https://services.cloud.mongodb.com
+      await app.updateBaseUrl(null);
+      // :snippet-end:
+      expect(app.baseUrl.toString(), newBaseUrl);
+    },
+        skip:
+            """Skipping until we get Edge Server running in a CI and we can write automated tests for full flow (this was tested locally and succeeded)""");
+
     test('Access App on background isolate by id', () async {
       // :snippet-start: access-app-by-id
       // Create an App instance once on main isolate,
diff --git a/source/examples/generated/flutter/app_services_test.snippet.change-base-url.dart b/source/examples/generated/flutter/app_services_test.snippet.change-base-url.dart
@@ -0,0 +1,14 @@
+// Specify a custom baseUrl to connect to.
+// In this case, an Edge Server instance running on the device.
+final appConfig = AppConfiguration(
+  EDGE_SERVER_APP_ID,
+  baseUrl: Uri.parse('http://localhost:80')
+  );
+
+var app = App(appConfig);
+
+// ... log in a user and use the app ...
+
+// Later, change the baseUrl to the default:
+// https://services.cloud.mongodb.com
+await app.updateBaseUrl(null);
diff --git a/source/examples/generated/flutter/app_services_test.snippet.custom-base-url.dart b/source/examples/generated/flutter/app_services_test.snippet.custom-base-url.dart
@@ -0,0 +1,5 @@
+// Specify a baseUrl to connect to a server other than the default
+final appConfig =
+    AppConfiguration(APP_ID, baseUrl: Uri.parse('https://example.com'));
+
+var app = App(appConfig);
diff --git a/source/sdk/flutter/app-services/connect-to-app.txt b/source/sdk/flutter/app-services/connect-to-app.txt
@@ -36,44 +36,44 @@ Access the App Client
 .. versionchanged:: 1.7.0
    ``App`` must be created on the main isolate.
 
-Create an ``App`` instance to access App Services features throughout your 
-client application. We recommend that you create the ``App`` instance only 
+Create an ``App`` instance to access App Services features throughout your
+client application. We recommend that you create the ``App`` instance only
 once on the main isolate, ideally as soon as the app starts.
 
-#. Get your App Services App's ID from the App Services UI. To learn how, 
+#. Get your App Services App's ID from the App Services UI. To learn how,
    refer to :ref:`Find your App ID <find-your-app-id>`.
 #. Create an :flutter-sdk:`AppConfiguration <realm/AppConfiguration-class.html>`
    object with your App's App ID as the argument.
 #. Create an :flutter-sdk:`App <realm/App-class.html>`
-   with the ``AppConfiguration`` you just created. In Flutter v1.7.0 and later, 
-   this must be done on the main isolate, otherwise the SDK throws an error.  
+   with the ``AppConfiguration`` you just created. In Flutter v1.7.0 and later,
+   this must be done on the main isolate, otherwise the SDK throws an error.
 
-After you create the ``App``, you can access the constructed ``App`` instance 
+After you create the ``App``, you can access the constructed ``App`` instance
 on a background isolate using ``App.getById``. Refer to the
-:ref:`Get App by ID <flutter-get-app-by-id>` section on this page for more 
+:ref:`Get App by ID <flutter-get-app-by-id>` section on this page for more
 information.
 
 .. literalinclude:: /examples/generated/flutter/app_services_test.snippet.access-app-client.dart
    :language: dart
 
 You can create multiple App client instances to connect to multiple
-Apps. All App client instances that share the same App ID use the same 
+Apps. All App client instances that share the same App ID use the same
 underlying connection.
 
 .. important:: Changing an App Config After Initializing the App
 
    .. versionchanged:: 1.8.0
       ``baseUrl`` is not cached in the ``AppConfiguration``
-   
-   When you initialize the App client, the configuration is cached internally. 
+
+   When you initialize the App client, the configuration is cached internally.
    Attempting to close and then re-open an App with a changed configuration
-   within the same process has no effect. The client continues to use the 
-   cached configuration. 
+   within the same process has no effect. The client continues to use the
+   cached configuration.
 
-   In Flutter SDK version 1.8.0 and later, the :flutter-sdk:`baseUrl <realm/AppConfiguration/baseUrl.html>` 
-   is *no longer* cached in the App configuration. This means that you can change the 
-   ``baseUrl``, and the App client will use the updated configuration. In 
-   earlier SDK versions, changes to the ``baseUrl`` in a cached App 
+   In Flutter SDK version 1.8.0 and later, the :flutter-sdk:`baseUrl <realm/AppConfiguration/baseUrl.html>`
+   is *no longer* cached in the App configuration. This means that you can change the
+   ``baseUrl``, and the App client will use the updated configuration. In
+   earlier SDK versions, changes to the ``baseUrl`` in a cached App
    configuration have no effect.
 
 .. _flutter-app-client-configuration:
@@ -91,7 +91,7 @@ To learn about the available configuration options, refer to the
 :flutter-sdk:`AppConfiguration <realm/AppConfiguration-class.html>` reference documentation.
 
 .. literalinclude:: /examples/generated/flutter/app_services_test.snippet.app-client-advanced-configuration.dart
-   :language: dart 
+   :language: dart
 
 .. note:: Connect Using Android 7 or Older
 
@@ -107,11 +107,64 @@ Get App by ID
 
 .. versionadded:: 1.7.0
 
-After you have created an ``App`` instance on the main isolate, you can access 
-the constructed instance on a background isolate by passing the App ID to the 
+After you have created an ``App`` instance on the main isolate, you can access
+the constructed instance on a background isolate by passing the App ID to the
 :flutter-sdk:`App.getById() <realm/App/getById.html>` method. Then, you can use it to work with the ``App`` and users as needed.
 
 .. literalinclude:: /examples/generated/flutter/app_services_test.snippet.access-app-by-id.dart
    :language: dart
    :emphasize-lines: 14
 
+.. _flutter-connect-to-specific-server:
+
+Connect to a Specific Server
+----------------------------
+
+By default, Atlas Device SDK connects to Atlas using the global ``baseUrl``
+of ``https://services.cloud.mongodb.com``. In some cases, you may want to
+connect to a different server:
+
+- Your App Services App uses local deployment, and you want to connect directly to a local ``baseUrl`` in your region. For more information, refer to the :ref:`<local-deployment>` App Services documentation.
+- You want to connect to an Edge Server instance. For more information, refer to
+  the :ref:`edge-server-connect-from-client` App Services documentation.
+
+You can specify a ``baseUrl`` in the
+:flutter-sdk:`AppConfiguration <realm/AppConfiguration-class.html>`:
+
+.. literalinclude:: /examples/generated/flutter/app_services_test.snippet.custom-base-url.dart
+   :language: dart
+
+Connect to a Different Server During Runtime
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.8.0
+.. versionchanged:: 2.2.0
+   ``updateBaseUrl`` accepts ``null`` value
+
+In some cases, you might want to change the ``baseUrl`` while the app is
+running. For example, you might want to roam between Edge Servers or
+move from an App Services connection to an Edge Server connection.
+
+To change the ``baseUrl`` during runtime, call the experimental
+:flutter-sdk:`app.updateBaseUrl <realm/App/updateBaseUrl.html>` method. You can
+pass ``null`` to reset the ``baseUrl`` to the default value.
+
+.. literalinclude:: /examples/generated/flutter/app_services_test.snippet.change-base-url.dart
+   :language: dart
+
+This API is experimental and may change in future releases.
+
+If you want to change the ``baseUrl`` after you have logged in a user and
+have opened a synced database, the app must perform a client reset. For more
+information, refer to :ref:`flutter-client-reset`.
+
+Perform the following in your code:
+
+1. :ref:`Pause the Sync session <flutter-pause-resume-sync>`
+2. Update the ``baseUrl`` using the ``app.updateBaseUrl`` method
+3. Re-authenticate the user to log in using the new ``baseUrl``
+4. Open a synced database pulling data from the new server
+
+Both the server and the client *must* be online for the user to authenticate and
+connect to the new server. If the server is not online or the client does not
+have a network connection, the user cannot authenticate and open the database.
