feat(discovery): add provider-neutral server discovery core

.github/workflows/CI-unit-tests-tsan.yml

@@ -1,8 +1,8 @@
 name: CI-unit-tests-tsan
 run-name: '${{ github.event.workflow_run && github.event.workflow_run.head_branch || github.ref_name }} ${{ github.workflow }} ${{ github.event.workflow_run && github.event.workflow_run.head_sha || github.sha }}'
 
-# Builds the mysqlx + plugin-chassis unit tests with WITHTSAN=1 and
-# runs them under ThreadSanitizer to catch race conditions. Closes
+# Builds the mysqlx, plugin-chassis, and provider-neutral IAM concurrency tests
+# with WITHTSAN=1 and runs them under ThreadSanitizer to catch race conditions. Closes
 # Phase 2 of issue #5675.
 #
 # Architecture (vs. the earlier closed PR #5720):
@@ -120,7 +120,7 @@ jobs:
       run: |
         make ubuntu24-tap
 
-    - name: Run mysqlx-tsan-g1 TAP group inside Docker
+    - name: Run concurrency TAP group inside Docker
       # Run the TSAN-instrumented unit tests INSIDE the same Docker
       # image used for the build — same source mount at /opt/proxysql,
       # same toolchain, same libstdc++/libgcc that the binaries linked

README.md

@@ -76,6 +76,8 @@ tar xzf proxysql-<version>-linux-amd64.tar.gz
 The archive contains `bin/proxysql`, a sample `etc/proxysql.cnf`, the `systemd/`
 units, and helper tools. The v4.0 build additionally ships the runtime plugins
 under `lib/proxysql/` (`ProxySQL_MySQLX_Plugin.so`, `ProxySQL_GenAI_Plugin.so`).
+See [AWS locality-aware backend selection](doc/aws-locality-awareness.md) for
+the optional external-provider contract and MySQL configuration controls.
 
 Alternatively you can also use the available repositories:
 

deps/Makefile

@@ -2,7 +2,11 @@
 
 PROXYSQL_PATH := $(shell while [ ! -f ./src/proxysql_global.cpp ]; do cd ..; done; pwd)
 
+.DEFAULT_GOAL := default
+
 include $(PROXYSQL_PATH)/include/makefiles_vars.mk
+include $(PROXYSQL_PATH)/common_mk/openssl_flags.mk
+include $(PROXYSQL_PATH)/common_mk/openssl_version_check.mk
 
 
 # to compile libmariadb_client with support for valgrind enabled, run:
@@ -80,10 +84,6 @@ default: $(targets)
 
 ### deps targets
 
-include $(PROXYSQL_PATH)/common_mk/openssl_flags.mk
-include $(PROXYSQL_PATH)/common_mk/openssl_version_check.mk
-
-
 libinjection/libinjection/src/libinjection.a:
 	cd libinjection && rm -rf libinjection-*/ || true
 	cd libinjection && tar -zxf libinjection-3.10.0.tar.gz
@@ -277,6 +277,7 @@ endif
 	cd mariadb-client-library/mariadb_client && patch -p0 < ../ma_password.c.patch
 #	cd mariadb-client-library/mariadb_client && patch libmariadb/ma_secure.c < ../ma_secure.c.patch
 	cd mariadb-client-library/mariadb_client && patch -p0 < ../mysql.h.patch
+	cd mariadb-client-library/mariadb_client && patch -p0 < ../tls_server_name.patch
 	cd mariadb-client-library/mariadb_client && patch -p0 < ../ma_priv.h.patch
 	cd mariadb-client-library/mariadb_client && patch -p0 < ../ma_alloc.c.patch
 	cd mariadb-client-library/mariadb_client && patch -p0 < ../ma_charset.c.patch

deps/mariadb-client-library/mariadb_lib.c.patch

@@ -69,7 +69,7 @@ index e8db51a0..684aff1a 100644
      mysql->stmts= NULL;
    }
  }
-@@ -2458,6 +2475,42 @@ mysql_close(MYSQL *mysql)
+@@ -2458,6 +2475,58 @@ mysql_close(MYSQL *mysql)
    return;
  }
 
@@ -85,6 +85,22 @@ index e8db51a0..684aff1a 100644
 +         mysql->options.reconnect=0;
 +        end_server(mysql);
 +      }
++      else if (mysql->options.extension &&
++               mysql->options.extension->async_context)
++      {
++        struct mysql_async_context *ctxt=
++          mysql->options.extension->async_context;
++        if (ctxt->pending_gai_res)
++        {
++          freeaddrinfo(ctxt->pending_gai_res);
++          ctxt->pending_gai_res= 0;
++        }
++        if (ctxt->pvio)
++        {
++          ma_pvio_close(ctxt->pvio);
++          ctxt->pvio= 0;
++        }
++      }
 +    }
 +    mysql_close_memory(mysql);
 +    mysql_close_options(mysql);

deps/mariadb-client-library/sslkeylogfile.patch

@@ -14,13 +14,14 @@ diff --git include/mysql.h include/mysql.h
 index 9ee86227..c07717c5 100644
 --- include/mysql.h
 +++ include/mysql.h
-@@ -257,7 +257,8 @@ extern const char *SQLSTATE_UNKNOWN;
+@@ -257,8 +257,9 @@ extern const char *SQLSTATE_UNKNOWN;
      MARIADB_OPT_RESTRICTED_AUTH,
      MARIADB_OPT_RPL_REGISTER_REPLICA,
      MARIADB_OPT_STATUS_CALLBACK,
--    MARIADB_OPT_SERVER_PLUGINS
-+    MARIADB_OPT_SERVER_PLUGINS,
-+    MARIADB_OPT_SSL_KEYLOG_CALLBACK
+     MARIADB_OPT_SERVER_PLUGINS,
+-    MARIADB_OPT_TLS_SERVER_NAME = MARIADB_OPT_SERVER_PLUGINS + 2
++    MARIADB_OPT_SSL_KEYLOG_CALLBACK = MARIADB_OPT_SERVER_PLUGINS + 1,
++    MARIADB_OPT_TLS_SERVER_NAME = MARIADB_OPT_SERVER_PLUGINS + 2
    };
 
    enum mariadb_value {

deps/mariadb-client-library/tls_server_name.patch

@@ -0,0 +1,199 @@
+diff --git include/ma_common.h include/ma_common.h
+--- include/ma_common.h
++++ include/ma_common.h
+@@ -73,6 +73,7 @@ struct st_mysql_options_extension {
+   unsigned int tls_cipher_strength;
+   char *tls_version;
+   my_bool read_only;
++  char *tls_server_name;
+   char *connection_handler;
+   my_bool (*set_option)(MYSQL *mysql, const char *config_option, const char *config_value);
+   MA_HASHTBL userdata;
+diff --git include/ma_tls.h include/ma_tls.h
+--- include/ma_tls.h
++++ include/ma_tls.h
+@@ -148,6 +148,7 @@ int ma_pvio_tls_get_protocol_version_id(MARIADB_TLS *ctls);
+ void ma_tls_set_connection(MYSQL *mysql);
+
+ /* Function prototypes */
++const char *ma_tls_get_server_name(MYSQL *mysql);
+ MARIADB_TLS *ma_pvio_tls_init(MYSQL *mysql);
+ my_bool ma_pvio_tls_connect(MARIADB_TLS *ctls);
+ ssize_t ma_pvio_tls_read(MARIADB_TLS *ctls, const uchar *buffer, size_t length);
+diff --git include/mysql.h include/mysql.h
+--- include/mysql.h
++++ include/mysql.h
+@@ -260,6 +260,7 @@ extern const char *SQLSTATE_UNKNOWN;
+-    MARIADB_OPT_SERVER_PLUGINS
++    MARIADB_OPT_SERVER_PLUGINS,
++    MARIADB_OPT_TLS_SERVER_NAME = MARIADB_OPT_SERVER_PLUGINS + 2
+   };
+
+   enum mariadb_value {
+     MARIADB_CHARSET_ID,
+     MARIADB_CHARSET_NAME,
+diff --git libmariadb/ma_tls.c libmariadb/ma_tls.c
+--- libmariadb/ma_tls.c
++++ libmariadb/ma_tls.c
+@@ -51,6 +51,14 @@
+ my_bool ma_tls_initialized= FALSE;
+ unsigned int mariadb_deinitialize_ssl= 1;
+
++const char *ma_tls_get_server_name(MYSQL *mysql)
++{
++  if (mysql->options.extension && mysql->options.extension->tls_server_name &&
++      mysql->options.extension->tls_server_name[0])
++    return mysql->options.extension->tls_server_name;
++  return mysql->host;
++}
++
+ const char *tls_protocol_version[]=
+   {"SSLv3", "TLSv1.0", "TLSv1.1", "TLSv1.2", "TLSv1.3", "Unknown"};
+
+diff --git libmariadb/mariadb_lib.c libmariadb/mariadb_lib.c
+--- libmariadb/mariadb_lib.c
++++ libmariadb/mariadb_lib.c
+@@ -2304,6 +2304,7 @@ static void mysql_close_options(MYSQL *mysql)
+     free(mysql->options.extension->tls_fp_list);
+     free(mysql->options.extension->tls_pw);
+     free(mysql->options.extension->tls_version);
++    free(mysql->options.extension->tls_server_name);
+     free(mysql->options.extension->url);
+     free(mysql->options.extension->connection_handler);
+     free(mysql->options.extension->proxy_header);
+@@ -3768,6 +3769,9 @@ mysql_optionsv(MYSQL *mysql,enum mysql_option option, ...)
+   case MYSQL_OPT_TLS_VERSION:
+     OPT_SET_EXTENDED_VALUE_STR(&mysql->options, tls_version, (char *)arg1);
+     break;
++  case MARIADB_OPT_TLS_SERVER_NAME:
++    OPT_SET_EXTENDED_VALUE_STR(&mysql->options, tls_server_name, (char *)arg1);
++    break;
+   case MARIADB_OPT_IO_WAIT:
+     CHECK_OPT_EXTENSION_SET(&mysql->options);
+     mysql->options.extension->io_wait = (int(*)(my_socket, my_bool, int))arg1;
+@@ -3927,6 +3931,9 @@ mysql_get_optionv(MYSQL *mysql, enum mysql_option option, void *arg, ...)
+   case MYSQL_OPT_TLS_VERSION:
+     *((char **)arg)= mysql->options.extension ? mysql->options.extension->tls_version : NULL;
+     break;
++  case MARIADB_OPT_TLS_SERVER_NAME:
++    *((char **)arg)= mysql->options.extension ? mysql->options.extension->tls_server_name : NULL;
++    break;
+   case MYSQL_OPT_CONNECT_ATTRS:
+     /* mysql_get_optionsv(mysql, MYSQL_OPT_CONNECT_ATTRS, keys, vals, elements) */
+     {
+diff --git libmariadb/secure/gnutls.c libmariadb/secure/gnutls.c
+--- libmariadb/secure/gnutls.c
++++ libmariadb/secure/gnutls.c
+@@ -1176,6 +1176,7 @@ my_bool ma_tls_connect(MARIADB_TLS *ctls)
+   MYSQL *mysql= (MYSQL *)gnutls_session_get_ptr(ssl);
+   MARIADB_PVIO *pvio;
+   int ret;
++  const char *server_name;
+
+   if (!mysql)
+     return 1;
+@@ -1198,6 +1199,11 @@ my_bool ma_tls_connect(MARIADB_TLS *ctls)
+   gnutls_transport_set_int(ssl, mysql_get_socket(mysql));
+ #endif
+
++  server_name= ma_tls_get_server_name(mysql);
++  if (server_name && gnutls_server_name_set(ssl, GNUTLS_NAME_DNS,
++                                             server_name, strlen(server_name)) < 0)
++    return 1;
++
+   do {
+     ret = gnutls_handshake(ssl);
+   } while (ret < 0 && gnutls_error_is_fatal(ret) == 0);
+@@ -1359,7 +1365,7 @@ static int my_verify_callback(gnutls_session_t ssl)
+
+   if ((mysql->options.extension->tls_verify_server_cert))
+   {
+-    const char *hostname= mysql->host;
++    const char *hostname= ma_tls_get_server_name(mysql);
+
+     if (gnutls_certificate_verify_peers3 (ssl, hostname, &status) < 0)
+       return GNUTLS_E_CERTIFICATE_ERROR;
+diff --git libmariadb/secure/ma_schannel.c libmariadb/secure/ma_schannel.c
+--- libmariadb/secure/ma_schannel.c
++++ libmariadb/secure/ma_schannel.c
+@@ -300,7 +300,7 @@ SECURITY_STATUS ma_schannel_client_handshake(MARIADB_TLS *ctls)
+
+   sRet = InitializeSecurityContext(&sctx->CredHdl,
+                                     NULL,
+-                                    pvio->mysql->host,
++                                    (SEC_CHAR *)ma_tls_get_server_name(pvio->mysql),
+                                     SFlags,
+                                     0,
+                                     SECURITY_NATIVE_DREP,
+@@ -514,7 +514,7 @@ my_bool ma_schannel_verify_certs(MARIADB_TLS *ctls, BOOL verify_server_name)
+       pServerCert,
+       store,
+       crl_file != 0 || crl_path != 0,
+-      mysql->host,
++      ma_tls_get_server_name(mysql),
+       verify_server_name,
+       errmsg, sizeof(errmsg));
+
+diff --git libmariadb/secure/openssl.c libmariadb/secure/openssl.c
+--- libmariadb/secure/openssl.c
++++ libmariadb/secure/openssl.c
+@@ -463,6 +463,7 @@ my_bool ma_tls_connect(MARIADB_TLS *ctls)
+   MYSQL *mysql;
+   MARIADB_PVIO *pvio;
+   int rc;
++  const char *server_name;
+ #ifdef OPENSSL_USE_BIOMETHOD
+   BIO_METHOD *bio_method= NULL;
+   BIO *bio;
+@@ -486,6 +487,13 @@ my_bool ma_tls_connect(MARIADB_TLS *ctls)
+   SSL_set_fd(ssl, (int)mysql_get_socket(mysql));
+ #endif
+
++  server_name= ma_tls_get_server_name(mysql);
++  if (server_name && !SSL_set_tlsext_host_name(ssl, server_name))
++  {
++    ma_tls_set_error(mysql);
++    return 1;
++  }
++
+   while (try_connect && (rc= SSL_connect(ssl)) == -1)
+   {
+     switch((SSL_get_error(ssl, rc))) {
+@@ -659,6 +667,7 @@ int ma_tls_verify_server_cert(MARIADB_TLS *ctls)
+   MYSQL *mysql;
+   SSL *ssl;
+   MARIADB_PVIO *pvio;
++  const char *server_name;
+ #if !defined(HAVE_OPENSSL_CHECK_HOST)
+   X509_NAME *x509sn;
+   int cn_pos;
+@@ -673,7 +682,8 @@ int ma_tls_verify_server_cert(MARIADB_TLS *ctls)
+   mysql= (MYSQL *)SSL_get_app_data(ssl);
+   pvio= mysql->net.pvio;
+
+-  if (!mysql->host)
++  server_name= ma_tls_get_server_name(mysql);
++  if (!server_name)
+   {
+     pvio->set_error(mysql, CR_SSL_CONNECTION_ERROR, SQLSTATE_UNKNOWN,
+                     ER(CR_SSL_CONNECTION_ERROR), "Invalid (empty) hostname");
+@@ -687,8 +697,8 @@ int ma_tls_verify_server_cert(MARIADB_TLS *ctls)
+     return 1;
+   }
+ #ifdef HAVE_OPENSSL_CHECK_HOST
+-  if (X509_check_host(cert, mysql->host, strlen(mysql->host), 0, 0) != 1
+-     && X509_check_ip_asc(cert, mysql->host, 0) != 1)
++  if (X509_check_host(cert, server_name, strlen(server_name), 0, 0) != 1
++     && X509_check_ip_asc(cert, server_name, 0) != 1)
+     goto error;
+ #else
+   x509sn= X509_get_subject_name(cert);
+@@ -708,7 +718,7 @@ int ma_tls_verify_server_cert(MARIADB_TLS *ctls)
+   if ((size_t)ASN1_STRING_length(cn_asn1) != strlen(cn_str))
+     goto error;
+
+-  if (strcmp(cn_str, mysql->host))
++  if (strcmp(cn_str, server_name))
+     goto error;
+ #endif
+   X509_free(cert);

doc/PLUGIN_API.md

@@ -103,7 +103,7 @@ All types are defined in `include/ProxySQL_Plugin.h`:
 ```cpp
 struct ProxySQL_PluginDescriptor {
     const char *name;                         // Human-readable plugin name
-    uint32_t abi_version;                     // PROXYSQL_PLUGIN_ABI_VERSION (currently 5)
+    uint32_t abi_version;                     // PROXYSQL_PLUGIN_ABI_VERSION (1 through 9)
     proxysql_plugin_init_cb init;             // bool (*)(ProxySQL_PluginServices *)
     proxysql_plugin_start_cb start;           // bool (*)()
     proxysql_plugin_stop_cb stop;             // bool (*)()
@@ -115,7 +115,7 @@ struct ProxySQL_PluginDescriptor {
 | Field              | Type          | Description                                               |
 |--------------------|---------------|-----------------------------------------------------------|
 | `name`             | `const char*` | Plugin identifier, used in logging.                        |
-| `abi_version`      | `uint32_t`    | Set from `PROXYSQL_PLUGIN_ABI_VERSION`. Value `1` is the pre-chassis descriptor; `2` adds `register_schemas`; `3` adds `register_runtime_view`; `4` appends `db_kind` to runtime views; `5` appends optional Admin-mutex handoff callbacks to `ProxySQL_PluginCommandContext`. The current PROXYSQL40 core accepts `[1, 5]`. |
+| `abi_version`      | `uint32_t`    | Set from `PROXYSQL_PLUGIN_ABI_VERSION`. Value `1` is the pre-chassis six-field descriptor; ABI 2 adds `register_schemas`; ABI 3 adds `register_runtime_view`; ABI 4 adds the view's `db_kind`; ABI 5 adds optional Admin-mutex handoff callbacks and IAM provider install/limits; ABI 6 adds metadata-provider install; ABI 7 adds the MySQL locality projection callback; ABI 8 adds IAM provider rollback; ABI 9 adds provider-neutral server discovery services. A v3/v3.1 core rejects `abi_version > 1`; the current PROXYSQL40 core accepts `[1, 9]`. |
 | `init`             | callback      | Phase D — called with live services; register tables and commands here (or finish context setup if `register_schemas` already did it). |
 | `start`            | callback      | Phase E — start threads, open sockets, load config.        |
 | `stop`             | callback      | Called on shutdown.  Pairs with `init`, not `start`: if `init` returned true and `start` later failed, `stop` is still called so the plugin can release resources it allocated in `init`. |
@@ -128,7 +128,7 @@ Return `true` on success, `false` on failure. A `false` return from
 
 #### ABI version
 
-`include/ProxySQL_Plugin.h` exposes `PROXYSQL_PLUGIN_ABI_VERSION` (currently 5
+`include/ProxySQL_Plugin.h` exposes `PROXYSQL_PLUGIN_ABI_VERSION` (currently 9
 under PROXYSQL40, undefined in pre-chassis builds — the descriptor is then a
 legacy six-field struct with `abi_version = 1`). Plugins MUST assign
 `abi_version` from this macro rather than hard-coding a literal; the
@@ -168,9 +168,44 @@ struct ProxySQL_PluginServices {
     proxysql_plugin_register_command_alias_cb register_command_alias;
     // ABI 3 tail extension:
     proxysql_plugin_register_runtime_view_cb register_runtime_view;
+    // ABI 5 tail extensions, live only while init() is running:
+    proxysql_plugin_install_aws_iam_token_source_cb install_aws_iam_token_source;
+    proxysql_plugin_get_aws_iam_limits_cb get_aws_iam_limits;
+    // ABI 6 tail extension, live only while init() is running:
+    proxysql_plugin_install_aws_metadata_provider_cb install_aws_metadata_provider;
+    // ABI 7 tail extension, live during register_schemas() and init():
+    proxysql_plugin_refresh_mysql_aws_locality_stats_cb refresh_mysql_aws_locality_stats;
+    // ABI 8 tail extension, live only while init() is running:
+    proxysql_plugin_uninstall_aws_iam_token_source_cb uninstall_aws_iam_token_source;
 };
 ```
 
+`install_aws_iam_token_source` allows an optional external provider to supply
+IAM database-authentication tokens. The provider passes a newly allocated
+source, a destroy callback, and an extra `dlopen()` handle. Core retains that
+handle until all session leases drain, then destroys the source and closes the
+module. A plugin must not call this callback outside `init()` or retain the
+service pointer after initialization. Without an installed provider, IAM
+authentication remains available as a policy but fails closed.
+
+`install_aws_metadata_provider` installs an optional external asynchronous
+metadata provider for MySQL locality selection. Core owns the retained lease
+registry: new leases are rejected during shutdown, active manager/callback
+leases drain, the provider's `shutdown()` and destroy callback run, and the
+extra module handle closes last. Without an installed provider, locality uses
+configured weights and reports the fixed `provider_unavailable` category.
+
+`refresh_mysql_aws_locality_stats` projects the current MySQL-owned immutable
+locality snapshot into a schema supplied by the calling plugin. It performs no
+provider or network I/O and is live during `register_schemas()` so an external
+provider can register its stats table and runtime-view callback together.
+Public core deliberately registers no locality table on its own.
+
+`uninstall_aws_iam_token_source` lets the same plugin roll back its IAM source
+when a later initialization step fails. It rejects a null or different source,
+stops new leases, drains active leases, destroys the source, and releases the
+retained module handle before returning.
+
 ### Service Callbacks
 
 #### `register_table`
@@ -549,7 +584,7 @@ void register_stats_table(ProxySQL_PluginServices& services,
 - **No dependency resolution**: Plugins are loaded in the order listed in
   `proxysql.cnf`. If one plugin depends on another, the dependency must be
   listed first.
-- **ABI version range**: The current core accepts `abi_version` values in `[1, 5]`. Newly built plugins should set `abi_version = PROXYSQL_PLUGIN_ABI_VERSION`.
+- **ABI version range**: The current core accepts `abi_version` values in `[1, 9]`. Newly built plugins should set `abi_version = PROXYSQL_PLUGIN_ABI_VERSION`.
 - **Compiler coupling**: Plugins must match the ProxySQL core's C++ compiler
   and standard library due to `std::string` in `ProxySQL_PluginCommandResult`.
 

doc/README.md

@@ -51,4 +51,4 @@ Detailed technical documentation for specific components:
 
 ---
 
-> This approach provides the benefits of AI-generated assistance while being transparent about limitations and reducing verification overhead.
+> This approach provides the benefits of AI-generated assistance while being transparent about limitations and reducing verification overhead.