fix(kernel): gate max connections by wheel support

Signed-off-by: Vu Anh Phung <vu.phung@databricks.com>

Author: vuanhphung

src/databricks/sql/backend/kernel/client.py

@@ -156,7 +156,7 @@ def _kernel_session_accepts_kwarg(name: str) -> bool:
     ``**kwargs`` catch-all), so forwarding a kwarg it doesn't declare raises
     ``TypeError`` at construction, so we gate kwargs on what the installed
     wheel supports. Falls **closed** (returns ``False``) when the signature
-    can't be introspected because omitting an accepted telemetry kwarg is safer
+    can't be introspected because omitting an accepted optional kwarg is safer
     than forwarding an unsupported one.
     """
     try:
@@ -378,6 +378,9 @@ def open_session(
             # kernel's ``retry_*`` kwargs. Empty when at defaults.
             retry_kwargs = _kernel_retry_kwargs(self._retry_options)
             telemetry_kwargs = _kernel_telemetry_kwargs(self._telemetry_options)
+            max_connections_kwargs: Dict[str, Any] = {}
+            if _kernel_session_accepts_kwarg("max_connections"):
+                max_connections_kwargs["max_connections"] = self._max_connections
             # Forward caller / connector HTTP headers. The kernel applies
             # them on every request; a caller ``User-Agent`` is appended
             # to the kernel's base UA. Only pass the kwarg when there's
@@ -418,11 +421,11 @@ def open_session(
                 # strings).
                 intervals_as_string=True,
                 request_timeout_secs=self._request_timeout_secs,
-                max_connections=self._max_connections,
                 **auth_kwargs,
                 **tls_kwargs,
                 **retry_kwargs,
                 **telemetry_kwargs,
+                **max_connections_kwargs,
                 **http_headers_kwargs,
             )
         except Exception as exc:

tests/unit/test_kernel_client.py

@@ -452,21 +452,20 @@ def fake_session(**kw):
     assert captured["telemetry_circuit_breaker_enabled"] is False
 
 
-def test_open_session_omits_phase_7_kwargs_kernel_does_not_accept(monkeypatch):
-    """Phase-7 identity/telemetry kwargs must NOT be forwarded to a kernel
-    ``Session`` whose (fixed, no-``**kwargs``) constructor doesn't declare
-    them.
+def test_open_session_omits_optional_kwargs_kernel_does_not_accept(monkeypatch):
+    """Optional kwargs must NOT be forwarded to a kernel ``Session`` whose
+    fixed constructor doesn't declare them.
 
     The real ``databricks_sql_kernel.Session`` is a PyO3 class with a fixed
     signature. The other tests here use a ``**kwargs`` MagicMock that silently
     swallows unsupported kwargs; this fixed-signature fake proves the client
-    filters optional telemetry kwargs.
+    filters optional kwargs.
     """
     captured = {}
 
-    # Accept baseline connection/tls/retry/pool kwargs but no phase-7 identity
-    # or telemetry kwargs, and no **kwargs catch-all.
-    def fake_session_v0_2_0(
+    # Accept baseline connection/tls/retry kwargs but no max-connections,
+    # phase-7 identity, or telemetry kwargs, and no **kwargs catch-all.
+    def fake_session_without_optional_kwargs(
         host,
         http_path,
         *,
@@ -494,14 +493,15 @@ def fake_session_v0_2_0(
         complex_types_as_json=False,
         intervals_as_string=False,
         request_timeout_secs=None,
-        max_connections=None,
     ):
         captured["host"] = host
         sess = MagicMock()
         sess.session_id = "sess-id"
         return sess
 
-    monkeypatch.setattr(kernel_client._kernel, "Session", fake_session_v0_2_0)
+    monkeypatch.setattr(
+        kernel_client._kernel, "Session", fake_session_without_optional_kwargs
+    )
     monkeypatch.setattr(
         kernel_client.TelemetryHelper,
         "get_driver_system_configuration",
@@ -525,17 +525,18 @@ def fake_session_v0_2_0(
     kwargs = kernel_client._kernel_telemetry_kwargs(
         {"enable_telemetry": True, "telemetry_batch_size": 17}
     )
-    assert kwargs == {}, f"expected no phase-7 kwargs on 0.2.0 Session, got {kwargs}"
+    assert kwargs == {}, f"expected no unsupported phase-7 kwargs, got {kwargs}"
 
     c = kernel_client.KernelDatabricksClient(
         server_hostname="example.cloud.databricks.com",
         http_path="/sql/1.0/warehouses/abc",
         auth_provider=AccessTokenAuthProvider("dapi-test"),
         ssl_options=None,
+        max_connections=41,
         telemetry_options={"enable_telemetry": True, "telemetry_batch_size": 17},
     )
-    # Would raise TypeError: unexpected keyword argument if the client
-    # forwarded phase-7 kwargs the fixed-signature Session doesn't declare.
+    # Would raise TypeError if the client forwarded max-connections or
+    # phase-7 kwargs the fixed-signature Session doesn't declare.
     c.open_session(session_configuration=None, catalog=None, schema=None)
     assert captured["host"] == "example.cloud.databricks.com"