Implement server redirection. Fixes #789

Author: bgrainger

docs/content/api/MySqlConnector/MySqlConnectionStringBuilder/ServerRedirectionMode.md

@@ -0,0 +1,18 @@
+---
+title: MySqlConnectionStringBuilder.ServerRedirectionMode property
+---
+
+# MySqlConnectionStringBuilder.ServerRedirectionMode property
+
+```csharp
+public MySqlServerRedirectionMode ServerRedirectionMode { get; set; }
+```
+
+## See Also
+
+* enum [MySqlServerRedirectionMode](../../MySqlServerRedirectionModeType/)
+* class [MySqlConnectionStringBuilder](../../MySqlConnectionStringBuilderType/)
+* namespace [MySqlConnector](../../MySqlConnectionStringBuilderType/)
+* assembly [MySqlConnector](../../../MySqlConnectorAssembly/)
+
+<!-- DO NOT EDIT: generated by xmldocmd for MySqlConnector.dll -->

docs/content/api/MySqlConnector/MySqlConnectionStringBuilderType.md

@@ -55,6 +55,7 @@ public sealed class MySqlConnectionStringBuilder : DbConnectionStringBuilder
 | [Pooling](../MySqlConnectionStringBuilder/Pooling/) { get; set; } |  |
 | [Port](../MySqlConnectionStringBuilder/Port/) { get; set; } |  |
 | [Server](../MySqlConnectionStringBuilder/Server/) { get; set; } |  |
+| [ServerRedirectionMode](../MySqlConnectionStringBuilder/ServerRedirectionMode/) { get; set; } |  |
 | [ServerRsaPublicKeyFile](../MySqlConnectionStringBuilder/ServerRsaPublicKeyFile/) { get; set; } |  |
 | [ServerSPN](../MySqlConnectionStringBuilder/ServerSPN/) { get; set; } |  |
 | [SslCa](../MySqlConnectionStringBuilder/SslCa/) { get; set; } |  |

docs/content/api/MySqlConnector/MySqlServerRedirectionModeType.md

@@ -0,0 +1,26 @@
+---
+title: MySqlServerRedirectionMode
+---
+
+# MySqlServerRedirectionMode enumeration
+
+Server redirection configuration.
+
+```csharp
+public enum MySqlServerRedirectionMode
+```
+
+## Values
+
+| name | value | description |
+| --- | --- | --- |
+| Disabled | `0` | Server redirection will not be performed. |
+| Preferred | `1` | Server redirection will occur if possible, otherwise the original connection will be used. |
+| Required | `2` | Server redirection must occur, otherwise connecting fails. |
+
+## See Also
+
+* namespace [MySqlConnector](../../MySqlConnectorNamespace/)
+* assembly [MySqlConnector](../../MySqlConnectorAssembly/)
+
+<!-- DO NOT EDIT: generated by xmldocmd for MySqlConnector.dll -->

docs/content/api/MySqlConnectorAssembly.md

@@ -48,6 +48,7 @@ title: MySqlConnector
 | delegate [MySqlRowUpdatedEventHandler](../MySqlConnector/MySqlRowUpdatedEventHandlerType/) |  |
 | class [MySqlRowUpdatingEventArgs](../MySqlConnector/MySqlRowUpdatingEventArgsType/) |  |
 | delegate [MySqlRowUpdatingEventHandler](../MySqlConnector/MySqlRowUpdatingEventHandlerType/) |  |
+| enum [MySqlServerRedirectionMode](../MySqlConnector/MySqlServerRedirectionModeType/) | Server redirection configuration. |
 | enum [MySqlSslMode](../MySqlConnector/MySqlSslModeType/) | SSL connection options. |
 | class [MySqlTransaction](../MySqlConnector/MySqlTransactionType/) | [`MySqlTransaction`](../MySqlConnector/MySqlTransactionType/) represents an in-progress transaction on a MySQL Server. |
 

docs/content/api/MySqlConnectorNamespace.md

@@ -46,6 +46,7 @@ title: MySqlConnector
 | delegate [MySqlRowUpdatedEventHandler](../MySqlConnector/MySqlRowUpdatedEventHandlerType/) |  |
 | class [MySqlRowUpdatingEventArgs](../MySqlConnector/MySqlRowUpdatingEventArgsType/) |  |
 | delegate [MySqlRowUpdatingEventHandler](../MySqlConnector/MySqlRowUpdatingEventHandlerType/) |  |
+| enum [MySqlServerRedirectionMode](../MySqlConnector/MySqlServerRedirectionModeType/) | Server redirection configuration. |
 | enum [MySqlSslMode](../MySqlConnector/MySqlSslModeType/) | SSL connection options. |
 | class [MySqlTransaction](../MySqlConnector/MySqlTransactionType/) | [`MySqlTransaction`](../MySqlConnector/MySqlTransactionType/) represents an in-progress transaction on a MySQL Server. |
 

docs/content/connection-options.md

@@ -372,8 +372,9 @@ These are the other options that MySqlConnector supports. They are set to sensib
         <dt>Random</dt>
         <dd>Servers are tried in a random order.</dd>
         <dt>LeastConnections</dt>
-        <dd>Servers are tried in ascending order of number of currently-open connections in this connection pool. Requires <code>Pooling=True</code>.
+        <dd>Servers are tried in ascending order of number of currently-open connections in this connection pool. Requires <code>Pooling=True</code>.</dd>
       </dl>
+    </td>
   </tr>
   <tr id="NoBackslashEscapes">
     <td>No Backslash Escapes, NoBackslashEscapes</td>
@@ -390,6 +391,22 @@ These are the other options that MySqlConnector supports. They are set to sensib
     <td>false</td>
     <td>When set to <code>false</code> or no (strongly recommended), security-sensitive information, such as the password, is not returned as part of the connection string if the connection is open or has ever been in an open state. Resetting the connection string resets all connection string values, including the password. Recognized values are true, false, yes, and no.</td>
   </tr>
+  <tr id="ServerRedirectionMode">
+    <td>ServerRedirectionMode, Server Redirection Mode</td>
+    <td>Disabled</td>
+    <td><p>Whether to use server redirection. The options include:</p>
+      <dl>
+        <dt>Disabled</dt>
+        <dd>Server redirection is not used. All connections go through the proxy server (if there is one).</dd>
+        <dt>Preferred</dt>
+        <dd>If the server supports redirection, a redirected connection will be attempted. If it’s successful, the redirected connection will be used; otherwise, the original connection will be used.</dd>
+        <dt>Required</dt>
+        <dd>The server must support redirection, and making a redirected connection must be successful; otherwise, an exception will be thrown.</dd>
+      </dl>
+      <p>Server Redirection is supported by Azure Database for MySQL if the <code>redirect_enabled</code> server parameter is set to <code>ON</code>.</p>
+      <p>This option is only respected if <code>Pooling=True</code>.
+    </td>
+  </tr>
   <tr id="ServerRsaPublicKeyFile">
     <td>ServerRsaPublicKeyFile, Server RSA Public Key File</td>
     <td></td>

src/MySqlConnector/Core/ConnectionPool.cs

@@ -366,25 +366,50 @@ private async ValueTask<ServerSession> ConnectSessionAsync(string logMessage, in
 			if (Log.IsInfoEnabled())
 				Log.Info(logMessage, m_logArguments[0], session.Id);
 			var statusInfo = await session.ConnectAsync(ConnectionSettings, startTickCount, m_loadBalancer, ioBehavior, cancellationToken).ConfigureAwait(false);
+			Exception? redirectionException = null;
 
 			if (statusInfo is not null && statusInfo.StartsWith("Location: mysql://", StringComparison.Ordinal))
 			{
 				// server redirection string has the format "Location: mysql://{host}:{port}/user={userId}[&ttl={ttl}]"
 				Log.Info("Session{0} has server redirection header {1}", session.Id, statusInfo);
 
-				if (Utility.TryParseRedirectionHeader(statusInfo, out var host, out var port, out var user))
+				if (ConnectionSettings.ServerRedirectionMode == MySqlServerRedirectionMode.Disabled)
+				{
+					Log.Info("Pool{0} server redirection is disabled; ignoring redirection", m_logArguments);
+				}
+				else if (Utility.TryParseRedirectionHeader(statusInfo, out var host, out var port, out var user))
 				{
-					Log.Info("Session{0} found server redirection Host={1}; Port={2}; User={3}", session.Id, host, port, user);
-
 					if (host != ConnectionSettings.HostNames![0] || port != ConnectionSettings.Port || user != ConnectionSettings.UserID)
 					{
 						var redirectedSettings = ConnectionSettings.CloneWith(host, port, user);
 						Log.Info("Pool{0} opening new connection to Host={1}; Port={2}; User={3}", m_logArguments[0], host, port, user);
 						var redirectedSession = new ServerSession(this, m_generation, Interlocked.Increment(ref m_lastSessionId));
-						await redirectedSession.ConnectAsync(redirectedSettings, startTickCount, m_loadBalancer, ioBehavior, cancellationToken).ConfigureAwait(false);
-						Log.Info("Pool{0} closing Session{1} to use redirected Session{2} instead", m_logArguments[0], session.Id, redirectedSession.Id);
-						await session.DisposeAsync(ioBehavior, cancellationToken).ConfigureAwait(false);
-						return redirectedSession;
+						try
+						{
+							await redirectedSession.ConnectAsync(redirectedSettings, startTickCount, m_loadBalancer, ioBehavior, cancellationToken).ConfigureAwait(false);
+						}
+						catch (Exception ex)
+						{
+							Log.Warn(ex, "Pool{0} failed to connect redirected Session{1}", m_logArguments[0], redirectedSession.Id);
+							redirectionException = ex;
+						}
+
+						if (redirectionException is null)
+						{
+							Log.Info("Pool{0} closing Session{1} to use redirected Session{2} instead", m_logArguments[0], session.Id, redirectedSession.Id);
+							await session.DisposeAsync(ioBehavior, cancellationToken).ConfigureAwait(false);
+							return redirectedSession;
+						}
+						else
+						{
+							try
+							{
+								await redirectedSession.DisposeAsync(ioBehavior, cancellationToken).ConfigureAwait(false);
+							}
+							catch (Exception)
+							{
+							}
+						}
 					}
 					else
 					{
@@ -393,6 +418,11 @@ private async ValueTask<ServerSession> ConnectSessionAsync(string logMessage, in
 				}
 			}
 
+			if (ConnectionSettings.ServerRedirectionMode == MySqlServerRedirectionMode.Required)
+			{
+				Log.Error("Pool{0} requires server redirection but server doesn't support it", m_logArguments);
+				throw new MySqlException(MySqlErrorCode.UnableToConnectToHost, "Server does not support redirection", redirectionException);
+			}
 			return session;
 		}
 

src/MySqlConnector/Core/ConnectionSettings.cs

@@ -140,6 +140,7 @@ public ConnectionSettings(MySqlConnectionStringBuilder csb)
 			Keepalive = csb.Keepalive;
 			NoBackslashEscapes = csb.NoBackslashEscapes;
 			PersistSecurityInfo = csb.PersistSecurityInfo;
+			ServerRedirectionMode = csb.ServerRedirectionMode;
 			ServerRsaPublicKeyFile = csb.ServerRsaPublicKeyFile;
 			ServerSPN = csb.ServerSPN;
 			TreatTinyAsBoolean = csb.TreatTinyAsBoolean;
@@ -234,6 +235,7 @@ private static MySqlGuidFormat GetEffectiveGuidFormat(MySqlGuidFormat guidFormat
 		public uint Keepalive { get; }
 		public bool NoBackslashEscapes { get; }
 		public bool PersistSecurityInfo { get; }
+		public MySqlServerRedirectionMode ServerRedirectionMode { get; }
 		public string ServerRsaPublicKeyFile { get; }
 		public string ServerSPN { get; }
 		public bool TreatTinyAsBoolean { get; }
@@ -317,6 +319,7 @@ private ConnectionSettings(ConnectionSettings other, string host, int port, stri
 			Keepalive = other.Keepalive;
 			NoBackslashEscapes = other.NoBackslashEscapes;
 			PersistSecurityInfo = other.PersistSecurityInfo;
+			ServerRedirectionMode = other.ServerRedirectionMode;
 			ServerRsaPublicKeyFile = other.ServerRsaPublicKeyFile;
 			ServerSPN = other.ServerSPN;
 			TreatTinyAsBoolean = other.TreatTinyAsBoolean;

src/MySqlConnector/MySqlConnectionStringBuilder.cs

@@ -332,6 +332,12 @@ public bool PersistSecurityInfo
 			set => MySqlConnectionStringOption.PersistSecurityInfo.SetValue(this, value);
 		}
 
+		public MySqlServerRedirectionMode ServerRedirectionMode
+		{
+			get => MySqlConnectionStringOption.ServerRedirectionMode.GetValue(this);
+			set => MySqlConnectionStringOption.ServerRedirectionMode.SetValue(this, value);
+		}
+
 		[AllowNull]
 		public string ServerRsaPublicKeyFile
 		{
@@ -479,6 +485,7 @@ internal abstract class MySqlConnectionStringOption
 		public static readonly MySqlConnectionStringValueOption<bool> NoBackslashEscapes;
 		public static readonly MySqlConnectionStringValueOption<bool> OldGuids;
 		public static readonly MySqlConnectionStringValueOption<bool> PersistSecurityInfo;
+		public static readonly MySqlConnectionStringValueOption<MySqlServerRedirectionMode> ServerRedirectionMode;
 		public static readonly MySqlConnectionStringReferenceOption<string> ServerRsaPublicKeyFile;
 		public static readonly MySqlConnectionStringReferenceOption<string> ServerSPN;
 		public static readonly MySqlConnectionStringValueOption<bool> TreatTinyAsBoolean;
@@ -745,6 +752,10 @@ static MySqlConnectionStringOption()
 				keys: new[] { "Persist Security Info", "PersistSecurityInfo" },
 				defaultValue: false));
 
+			AddOption(ServerRedirectionMode = new(
+				keys: new[] { "Server Redirection Mode", "ServerRedirectionMode" },
+				defaultValue: MySqlServerRedirectionMode.Disabled));
+
 			AddOption(ServerRsaPublicKeyFile = new(
 				keys: new[] { "ServerRsaPublicKeyFile", "Server RSA Public Key File" },
 				defaultValue: ""));
@@ -805,7 +816,7 @@ private T ChangeType(object objectValue)
 					return (T) (object) false;
 			}
 
-			if ((typeof(T) == typeof(MySqlLoadBalance) || typeof(T) == typeof(MySqlSslMode) || typeof(T) == typeof(MySqlDateTimeKind) || typeof(T) == typeof(MySqlGuidFormat) || typeof(T) == typeof(MySqlConnectionProtocol) || typeof(T) == typeof(MySqlCertificateStoreLocation)) && objectValue is string enumString)
+			if ((typeof(T) == typeof(MySqlLoadBalance) || typeof(T) == typeof(MySqlSslMode) || typeof(T) == typeof(MySqlServerRedirectionMode) || typeof(T) == typeof(MySqlDateTimeKind) || typeof(T) == typeof(MySqlGuidFormat) || typeof(T) == typeof(MySqlConnectionProtocol) || typeof(T) == typeof(MySqlCertificateStoreLocation)) && objectValue is string enumString)
 			{
 				try
 				{

src/MySqlConnector/MySqlServerRedirectionMode.cs

@@ -0,0 +1,23 @@
+namespace MySqlConnector
+{
+	/// <summary>
+	/// Server redirection configuration.
+	/// </summary>
+	public enum MySqlServerRedirectionMode
+	{
+		/// <summary>
+		/// Server redirection will not be performed.
+		/// </summary>
+		Disabled,
+
+		/// <summary>
+		/// Server redirection will occur if possible, otherwise the original connection will be used.
+		/// </summary>
+		Preferred,
+
+		/// <summary>
+		/// Server redirection must occur, otherwise connecting fails.
+		/// </summary>
+		Required,
+	}
+}