Add support for adding base-route for Runtime (#1506)

## Why make this change?
SWA or any other front end can interact with DAB using a path-based
routing mechanism, where they may use a path (`base-route`) to redirect
requests to DAB (refer to the bug encountered:
#1420). This
`base-route` gets stripped off when the request lands at DAB.
Consequently, DAB is not even aware of anything like a `base-route`
being used by the front end.
This poses a problem in generation of the `nextLink`, where the
`nextLink` which DAB generates, does not contain the `base-route` and
consequently when the front end receives the next request, it does not
find the base route in the request URL and hence, has no idea where to
redirect the request to.

Using the newly added option to configure base route for rest requests
via the config (CLI option - `--runtime.base-route`), the front-end like
SWA can make DAB aware that they are using a base route to redirect
requests to DAB. DAB can then accordingly account for the base route
while generating the `nextLink` for paginated responses.
## What is this change?

1. Added feature to specify `base-route` in global runtime settings in
the config which can be via CLI as well using `--runtime.base-route
`option in the `dab init` command. By default, it will be initialized as
null. When the base-route is a non-empty string, it will be included in
the generated nextLink. This feature is only supported when
`authentication provider == StaticWebApps`. We throw an exception when
base-route is configured for non-SWA providers.
2. Extended functionality of `Utils.IsApiPathValid(string? apiPath,
ApiType apiType)` method to `Utils.IsUriComponentValid(string?
uriComponent)` because similar validations are required for api
properties: `rest.path`/ `runtime.base-route`/ `graphql.path`, all of
which are part of the request URI.
3. Renamed `RuntimeConfigValidator.ValidateRestPathForRelationalDbs()`
to `RuntimeConfigValidator.ValidateRestURI()`.
4. Renamed `RuntimeConfigValidator.ValidateGraphQLPath()` to
`RuntimeConfigValidator.ValidateGraphQLURI()` so that we follow same
convention between rest and gql.

## Q&A

1. Will this require updating an already created configuration file? 
No, the existing config file will work perfectly fine. The base-route is
totally an optional feature.
2. Will a default value be implicitly used if the new base path config
property is not set?
The default value for the base-route is null. This essentially means
that base-route will not come into the picture.
3. What is the default value and does the value differ between dev/prod
swa/non-swa?
The default value will be same irrespective of dev/prod/swa/non-swa
environment and equal to null.

So to say, the **change is not a breaking change and we are totally
backwards compatible**.

## How was this tested?
- [x] Integration Tests - Was added to `ConfigurationTests.cs` to assert
that the generated nextLink contains the base-route.
- [x] Unit tests - were added to `ConfigValidationUnitTests.cs` to
confirm that we throw proper exceptions when runtime base-route is
formatted incorrectly (contains reserved characters or doesn't start
with a '/') or when base-route is configured for non-SWA authentication
providers.

---------

Co-authored-by: Aaron Powell <me@aaron-powell.com>
Co-authored-by: Sean Leonard <sean.leonard@microsoft.com>
Co-authored-by: Aniruddh Munde <anmunde@microsoft.com>

Author: 4 people

src/Cli.Tests/EndToEndTests.cs

@@ -104,8 +104,7 @@ public void TestInitForCosmosDBPostgreSql()
     [TestMethod]
     public void TestInitializingRestAndGraphQLGlobalSettings()
     {
-        string[] args = { "init", "-c", TEST_RUNTIME_CONFIG_FILE, "--database-type", "mssql", "--rest.path", "/rest-api",
-                          "--rest.disabled", "--graphql.path", "/graphql-api" };
+        string[] args = { "init", "-c", TEST_RUNTIME_CONFIG_FILE, "--database-type", "mssql", "--rest.path", "/rest-api", "--rest.disabled", "--graphql.path", "/graphql-api" };
         Program.Execute(args, _cliLogger!, _fileSystem!, _runtimeConfigLoader!);
 
         Assert.IsTrue(_runtimeConfigLoader!.TryLoadConfig(TEST_RUNTIME_CONFIG_FILE, out RuntimeConfig? runtimeConfig));
@@ -720,4 +719,40 @@ public async Task TestExitOfRuntimeEngineWithInvalidConfig(
 
         process.Kill();
     }
+
+    /// <summary>
+    /// Test to verify that when base-route is configured, the runtime config is only successfully generated when the
+    /// authentication provider is Static Web Apps.
+    /// </summary>
+    /// <param name="authProvider">Authentication provider specified for the runtime.</param>
+    /// <param name="isExceptionExpected">Whether an exception is expected as a result of test run.</param>
+    [DataTestMethod]
+    [DataRow("StaticWebApps", false)]
+    [DataRow("AppService", true)]
+    [DataRow("AzureAD", true)]
+    public void TestBaseRouteIsConfigurableForSWA(string authProvider, bool isExceptionExpected)
+    {
+        string[] initArgs = { "init", "-c", TEST_RUNTIME_CONFIG_FILE, "--host-mode", "development", "--database-type", "mssql",
+            "--connection-string", "localhost:5000", "--auth.provider", authProvider, "--runtime.base-route", "base-route" };
+
+        if (!Enum.TryParse(authProvider, ignoreCase: true, out EasyAuthType _))
+        {
+            string[] audIssuers = { "--auth.audience", "aud-xxx", "--auth.issuer", "issuer-xxx" };
+            initArgs = initArgs.Concat(audIssuers).ToArray();
+        }
+
+        Program.Execute(initArgs, _cliLogger!, _fileSystem!, _runtimeConfigLoader!);
+
+        if (isExceptionExpected)
+        {
+            Assert.IsFalse(_runtimeConfigLoader!.TryLoadConfig(TEST_RUNTIME_CONFIG_FILE, out RuntimeConfig? runtimeConfig));
+            Assert.IsNull(runtimeConfig);
+        }
+        else
+        {
+            Assert.IsTrue(_runtimeConfigLoader!.TryLoadConfig(TEST_RUNTIME_CONFIG_FILE, out RuntimeConfig? runtimeConfig));
+            Assert.IsNotNull(runtimeConfig);
+            Assert.AreEqual("/base-route", runtimeConfig.Runtime.BaseRoute);
+        }
+    }
 }

src/Cli.Tests/TestHelper.cs

@@ -849,52 +849,6 @@ public static Process ExecuteDabCommand(string command, string flags)
             }
         }";
 
-        public const string CONFIG_WITH_SINGLE_ENTITY =
-        @"{" +
-          @"""$schema"": """ + DAB_DRAFT_SCHEMA_TEST_PATH + @"""" + "," +
-          @"""data-source"": {
-          ""database-type"": ""mssql"",
-          ""connection-string"": ""localhost:5000"",
-          ""options"":{
-            ""set-session-context"": true
-          }
-        },
-        ""runtime"": {
-          ""rest"": {
-            ""path"": ""/api"",
-            ""enabled"": true
-          },
-          ""graphql"": {
-            ""path"": ""/graphql"",
-            ""enabled"": true,
-            ""allow-introspection"": true
-          },
-          ""host"": {
-            ""mode"": ""production"",
-            ""cors"": {
-              ""origins"": [],
-              ""allow-credentials"": false
-            },
-            ""authentication"": {
-              ""provider"": ""StaticWebApps""
-            }
-          }
-        },
-        ""entities"": {
-          ""book"": {
-            ""source"": ""s001.book"",
-            ""permissions"": [
-              {
-                ""role"": ""anonymous"",
-                ""actions"": [
-                  ""*""
-                ]
-              }
-            ]
-          }
-        }
-      }";
-
         public const string BASE_CONFIG =
           @"{" +
             @"""$schema"": """ + DAB_DRAFT_SCHEMA_TEST_PATH + @"""" + "," +

src/Cli.Tests/UtilsTests.cs

@@ -174,14 +174,14 @@ public void TestStoredProcedurePermissions(
     /// Test to verify that CLI is able to figure out if the api path prefix for rest/graphql contains invalid characters.
     /// </summary>
     [DataTestMethod]
-    [DataRow("/", ApiType.REST, true, DisplayName = "Only forward slash as api path")]
-    [DataRow("/$%^", ApiType.REST, false, DisplayName = "Api path containing only reserved characters.")]
-    [DataRow("/rest-api", ApiType.REST, true, DisplayName = "Valid api path")]
-    [DataRow("/graphql@api", ApiType.GraphQL, false, DisplayName = "Api path containing some reserved characters.")]
-    [DataRow("/api path", ApiType.REST, true, DisplayName = "Api path containing space.")]
-    public void TestApiPathIsWellFormed(string apiPath, ApiType apiType, bool expectSuccess)
+    [DataRow("/", true, DisplayName = "Only forward slash as api path")]
+    [DataRow("/$%^", false, DisplayName = "Api path containing only reserved characters.")]
+    [DataRow("/rest-api", true, DisplayName = "Valid api path")]
+    [DataRow("/graphql@api", false, DisplayName = "Api path containing some reserved characters.")]
+    [DataRow("/api path", true, DisplayName = "Api path containing space.")]
+    public void TestApiPathIsWellFormed(string apiPath, bool expectSuccess)
     {
-        Assert.AreEqual(expectSuccess, IsApiPathValid(apiPath, apiType));
+        Assert.AreEqual(expectSuccess, IsURIComponentValid(apiPath));
     }
 
     /// <summary>

src/Cli/Commands/InitOptions.cs

@@ -30,6 +30,7 @@ public InitOptions(
             string? audience = null,
             string? issuer = null,
             string restPath = RestRuntimeOptions.DEFAULT_PATH,
+            string? runtimeBaseRoute = null,
             bool restDisabled = false,
             string graphQLPath = GraphQLRuntimeOptions.DEFAULT_PATH,
             bool graphqlDisabled = false,
@@ -48,6 +49,7 @@ public InitOptions(
             Audience = audience;
             Issuer = issuer;
             RestPath = restPath;
+            RuntimeBaseRoute = runtimeBaseRoute;
             RestDisabled = restDisabled;
             GraphQLPath = graphQLPath;
             GraphQLDisabled = graphqlDisabled;
@@ -89,6 +91,9 @@ public InitOptions(
         [Option("rest.path", Default = RestRuntimeOptions.DEFAULT_PATH, Required = false, HelpText = "Specify the REST endpoint's default prefix.")]
         public string RestPath { get; }
 
+        [Option("runtime.base-route", Default = null, Required = false, HelpText = "Specifies the base route for API requests.")]
+        public string? RuntimeBaseRoute { get; }
+
         [Option("rest.disabled", Default = false, Required = false, HelpText = "Disables REST endpoint for all entities.")]
         public bool RestDisabled { get; }
 

src/Cli/ConfigGenerator.cs

@@ -9,6 +9,7 @@
 using Azure.DataApiBuilder.Config.Converters;
 using Azure.DataApiBuilder.Config.NamingPolicies;
 using Azure.DataApiBuilder.Config.ObjectModel;
+using Azure.DataApiBuilder.Core.Configurations;
 using Azure.DataApiBuilder.Service;
 using Cli.Commands;
 using Microsoft.Extensions.Logging;
@@ -87,6 +88,7 @@ public static bool TryCreateRuntimeConfig(InitOptions options, RuntimeConfigLoad
             DatabaseType dbType = options.DatabaseType;
             string? restPath = options.RestPath;
             string graphQLPath = options.GraphQLPath;
+            string? runtimeBaseRoute = options.RuntimeBaseRoute;
             Dictionary<string, JsonElement> dbOptions = new();
 
             HyphenatedNamingPolicy namingPolicy = new();
@@ -147,11 +149,33 @@ public static bool TryCreateRuntimeConfig(InitOptions options, RuntimeConfigLoad
                 return false;
             }
 
-            if (!IsApiPathValid(restPath, ApiType.REST) || !IsApiPathValid(options.GraphQLPath, ApiType.GraphQL))
+            if (!IsURIComponentValid(restPath))
             {
+                _logger.LogError($"{ApiType.REST} path {RuntimeConfigValidator.URI_COMPONENT_WITH_RESERVED_CHARS_ERR_MSG}");
                 return false;
             }
 
+            if (!IsURIComponentValid(options.GraphQLPath))
+            {
+                _logger.LogError($"{ApiType.GraphQL} path {RuntimeConfigValidator.URI_COMPONENT_WITH_RESERVED_CHARS_ERR_MSG}");
+                return false;
+            }
+
+            if (!IsURIComponentValid(runtimeBaseRoute))
+            {
+                _logger.LogError($"Runtime base-route {RuntimeConfigValidator.URI_COMPONENT_WITH_RESERVED_CHARS_ERR_MSG}");
+                return false;
+            }
+
+            if (runtimeBaseRoute is not null)
+            {
+                if (!Enum.TryParse(options.AuthenticationProvider, ignoreCase: true, out EasyAuthType easyAuthMode) || easyAuthMode is not EasyAuthType.StaticWebApps)
+                {
+                    _logger.LogError($"Runtime base-route can only be specified when the authentication provider is Static Web Apps.");
+                    return false;
+                }
+            }
+
             if (options.RestDisabled && options.GraphQLDisabled)
             {
                 _logger.LogError($"Both Rest and GraphQL cannot be disabled together.");
@@ -166,6 +190,12 @@ public static bool TryCreateRuntimeConfig(InitOptions options, RuntimeConfigLoad
                 restPath = "/" + restPath;
             }
 
+            // Prefix base-route with '/', if not already present.
+            if (runtimeBaseRoute is not null && !runtimeBaseRoute.StartsWith('/'))
+            {
+                runtimeBaseRoute = "/" + runtimeBaseRoute;
+            }
+
             // Prefix GraphQL path with '/', if not already present.
             if (!graphQLPath.StartsWith('/'))
             {
@@ -183,7 +213,8 @@ public static bool TryCreateRuntimeConfig(InitOptions options, RuntimeConfigLoad
                         Authentication: new(
                             Provider: options.AuthenticationProvider,
                             Jwt: (options.Audience is null && options.Issuer is null) ? null : new(options.Audience, options.Issuer)),
-                        Mode: options.HostMode)
+                        Mode: options.HostMode),
+                    BaseRoute: runtimeBaseRoute
                 ),
                 Entities: new RuntimeEntities(new Dictionary<string, Entity>()));
 

src/Cli/Utils.cs

@@ -9,7 +9,6 @@
 using Azure.DataApiBuilder.Config;
 using Azure.DataApiBuilder.Config.Converters;
 using Azure.DataApiBuilder.Config.ObjectModel;
-using Azure.DataApiBuilder.Service.Exceptions;
 using Cli.Commands;
 using Microsoft.Extensions.Logging;
 using static Azure.DataApiBuilder.Core.Configurations.RuntimeConfigValidator;
@@ -184,35 +183,25 @@ public static bool TryParseMappingDictionary(IEnumerable<string> mappingList, ou
         }
 
         /// <summary>
-        /// Returns true if the api path contains any reserved characters like "[\.:\?#/\[\]@!$&'()\*\+,;=]+"
+        /// Checks whether the URI component conforms with the expected behavior and does not contain any reserved characters.
         /// </summary>
-        /// <param name="apiPath">path prefix for rest/graphql apis</param>
-        /// <param name="apiType">Either REST or GraphQL</param>
-        public static bool IsApiPathValid(string? apiPath, ApiType apiType)
+        /// <param name="uriComponent">Path prefix/base route for REST/GraphQL APIs.</param>
+        public static bool IsURIComponentValid(string? uriComponent)
         {
-            // apiPath is null only in case of cosmosDB and apiType=REST. For this case, validation is not required.
-            // Since, cosmosDB do not support REST calls.
-            if (apiPath is null)
+            // uriComponent is null only in case of cosmosDB and apiType=REST or when the runtime base-route is specified as null.
+            // For these cases, validation is not required.
+            if (uriComponent is null)
             {
                 return true;
             }
 
-            // removing leading '/' before checking for forbidden characters.
-            if (apiPath.StartsWith('/'))
+            // removing leading '/' before checking for reserved characters.
+            if (uriComponent.StartsWith('/'))
             {
-                apiPath = apiPath.Substring(1);
+                uriComponent = uriComponent.Substring(1);
             }
 
-            try
-            {
-                DoApiPathInvalidCharCheck(apiPath, apiType);
-                return true;
-            }
-            catch (DataApiBuilderException ex)
-            {
-                _logger.LogError(ex.Message);
-                return false;
-            }
+            return !DoesUriComponentContainReservedChars(uriComponent);
         }
 
         /// <summary>

src/Config/ObjectModel/ApiType.cs

@@ -9,5 +9,7 @@ namespace Azure.DataApiBuilder.Config.ObjectModel;
 public enum ApiType
 {
     REST,
-    GraphQL
+    GraphQL,
+    // This is required to indicate features common between all APIs.
+    All
 }

src/Config/ObjectModel/AuthenticationOptions.cs

@@ -36,4 +36,10 @@ public record AuthenticationOptions(string Provider, JwtOptions? Jwt)
     /// </summary>
     /// <returns>True if the provider is enabled for JWT, otherwise false.</returns>
     public bool IsJwtConfiguredIdentityProvider() => !IsEasyAuthAuthenticationProvider() && !IsAuthenticationSimulatorEnabled();
+
+    /// <summary>
+    /// A shorthand method to determine whether Static Web Apps is configured for the current authentication provider.
+    /// </summary>
+    /// <returns>True if the provider is enabled for Static Web Apps, otherwise false.</returns>
+    public bool IsStaticWebAppsIdentityProvider() => EasyAuthType.StaticWebApps.ToString().Equals(Provider, StringComparison.OrdinalIgnoreCase);
 };

src/Config/ObjectModel/RuntimeOptions.cs

@@ -3,4 +3,4 @@
 
 namespace Azure.DataApiBuilder.Config.ObjectModel;
 
-public record RuntimeOptions(RestRuntimeOptions Rest, GraphQLRuntimeOptions GraphQL, HostOptions Host);
+public record RuntimeOptions(RestRuntimeOptions Rest, GraphQLRuntimeOptions GraphQL, HostOptions Host, string? BaseRoute = null);