SNOW-2439940: Deprecated custom revocation error classes in OCSP (#2748)

Author: sfc-gh-turbaszek

DESCRIPTION.md

@@ -12,6 +12,7 @@ Source code is also available at: https://github.com/snowflakedb/snowflake-conne
   - Made the parameter `server_session_keep_alive` in `SnowflakeConnection` skip checking for pending async queries, providing faster connection close times especially when many async queries are executed.
   - Fix string representation of INTERVAL YEAR and INTERVAL MONTH types.
   - Log a warning when using http protocol for OAuth urls.
+  - Deprecated support for custom revocation error classes in OCSP response cache deserialization. By default, only `RevocationCheckError` exceptions are deserialized from OCSP cache. Custom exception classes can be temporarily enabled by setting the `SNOWFLAKE_ENABLE_CUSTOM_REVOCATION_ERRORS` environment variable to `true` or `1`, but this support will be removed in a future release.
 
 - v4.2.0(January 07,2026)
   - Added `SnowflakeCursor.stats` property to expose granular DML statistics (rows inserted, deleted, updated, and duplicates) for operations like CTAS where `rowcount` is insufficient.

src/snowflake/connector/constants.py

@@ -442,6 +442,7 @@ class IterUnit(Enum):
 ENV_VAR_PARTNER = "SF_PARTNER"
 ENV_VAR_TEST_MODE = "SNOWFLAKE_TEST_MODE"
 ENV_VAR_DISABLE_PLATFORM_DETECTION = "SNOWFLAKE_DISABLE_PLATFORM_DETECTION"
+ENV_VAR_ENABLE_CUSTOM_REVOCATION_ERRORS = "SNOWFLAKE_ENABLE_CUSTOM_REVOCATION_ERRORS"
 
 # Boolean positive values (lowercased) for environment variable checks
 ENV_VAR_BOOL_POSITIVE_VALUES_LOWERCASED = ["true"]

src/snowflake/connector/ocsp_snowflake.py

@@ -10,6 +10,7 @@
 import sys
 import tempfile
 import time
+import warnings
 from base64 import b64decode, b64encode
 from datetime import datetime, timezone
 from logging import getLogger
@@ -28,7 +29,10 @@
 
 from snowflake.connector import SNOWFLAKE_CONNECTOR_VERSION
 from snowflake.connector.compat import OK, urlsplit, urlunparse
-from snowflake.connector.constants import HTTP_HEADER_USER_AGENT
+from snowflake.connector.constants import (
+    ENV_VAR_ENABLE_CUSTOM_REVOCATION_ERRORS,
+    HTTP_HEADER_USER_AGENT,
+)
 from snowflake.connector.errorcode import (
     ER_INVALID_OCSP_RESPONSE_SSD,
     ER_INVALID_SSD,
@@ -122,19 +126,40 @@ def deserialize_exception(exception_dict: dict | None) -> Exception | None:
                 return
             exc_class = exception_dict.get("class")
             exc_module = exception_dict.get("module")
+
+            # For RevocationCheckError, deserialize directly
+            if (
+                exc_class == "RevocationCheckError"
+                and exc_module == "snowflake.connector.errors"
+            ):
+                return RevocationCheckError(
+                    msg=exception_dict["msg"],
+                    errno=exception_dict.get("errno", ER_OCSP_RESPONSE_LOAD_FAILURE),
+                )
+
+            # For non-RevocationCheckError, always try to deserialize to detect failures
             try:
-                if (
-                    exc_class == "RevocationCheckError"
-                    and exc_module == "snowflake.connector.errors"
+                module = importlib.import_module(exc_module)
+                exc_cls = getattr(module, exc_class)
+                custom_exc = exc_cls(exception_dict["msg"])
+
+                # If env var is set, return the custom exception with deprecation warning
+                if os.getenv(ENV_VAR_ENABLE_CUSTOM_REVOCATION_ERRORS, "").lower() in (
+                    "true",
+                    "1",
                 ):
-                    return RevocationCheckError(
-                        msg=exception_dict["msg"],
-                        errno=exception_dict["errno"],
+                    warnings.warn(
+                        "Support for custom revocation error classes will be removed in a future release.",
+                        DeprecationWarning,
+                        stacklevel=3,
                     )
-                else:
-                    module = importlib.import_module(exc_module)
-                    exc_cls = getattr(module, exc_class)
-                    return exc_cls(exception_dict["msg"])
+                    return custom_exc
+
+                # Otherwise, convert to RevocationCheckError
+                return RevocationCheckError(
+                    msg=exception_dict["msg"],
+                    errno=exception_dict.get("errno", ER_OCSP_RESPONSE_LOAD_FAILURE),
+                )
             except Exception as deserialize_exc:
                 logger.debug(
                     f"hitting error {str(deserialize_exc)} while deserializing exception,"

test/unit/test_ocsp.py

@@ -862,7 +862,8 @@ def verify_none(origin_cache, loaded_cache):
         ):
             assert key1 == key2 and value1 == value2
 
-    def verify_exception(_, loaded_cache):
+    def verify_exception_default(_, loaded_cache):
+        """Test default behavior: custom exceptions are converted to RevocationCheckError"""
         exc_1 = loaded_cache[(b"key1", b"key2", b"key3")].exception
         exc_2 = loaded_cache[(b"key4", b"key5", b"key6")].exception
         exc_3 = loaded_cache[(b"key7", b"key8", b"key9")].exception
@@ -871,6 +872,25 @@ def verify_exception(_, loaded_cache):
             and exc_1.raw_msg == "error"
             and exc_1.errno == 1
         )
+        # By default, custom exceptions (ValueError) are converted to RevocationCheckError
+        assert isinstance(exc_2, RevocationCheckError)
+        assert (
+            isinstance(exc_3, RevocationCheckError)
+            and "while deserializing ocsp cache, please try cleaning up the OCSP cache under directory"
+            in exc_3.msg
+        )
+
+    def verify_exception_deprecated(_, loaded_cache):
+        """Test deprecated behavior with env var: custom exceptions are preserved"""
+        exc_1 = loaded_cache[(b"key1", b"key2", b"key3")].exception
+        exc_2 = loaded_cache[(b"key4", b"key5", b"key6")].exception
+        exc_3 = loaded_cache[(b"key7", b"key8", b"key9")].exception
+        assert (
+            isinstance(exc_1, RevocationCheckError)
+            and exc_1.raw_msg == "error"
+            and exc_1.errno == 1
+        )
+        # With env var set, custom exceptions are preserved
         assert isinstance(exc_2, ValueError) and str(exc_2) == "value error"
         assert (
             isinstance(exc_3, RevocationCheckError)
@@ -886,6 +906,7 @@ def verify_exception(_, loaded_cache):
     )
     verify(verify_none, origin_cache)
 
+    # Test default behavior (no env var)
     origin_cache = copy.deepcopy(test_cache)
     origin_cache.update(
         {
@@ -900,4 +921,27 @@ def verify_exception(_, loaded_cache):
             ),
         }
     )
-    verify(verify_exception, origin_cache)
+    verify(verify_exception_default, origin_cache)
+
+    # Test deprecated behavior (with env var set)
+    with mock.patch.dict(
+        os.environ, {"SNOWFLAKE_ENABLE_CUSTOM_REVOCATION_ERRORS": "true"}
+    ):
+        origin_cache = copy.deepcopy(test_cache)
+        origin_cache.update(
+            {
+                (b"key1", b"key2", b"key3"): OCSPResponseValidationResult(
+                    exception=RevocationCheckError(msg="error", errno=1),
+                ),
+                (b"key4", b"key5", b"key6"): OCSPResponseValidationResult(
+                    exception=ValueError("value error"),
+                ),
+                (b"key7", b"key8", b"key9"): OCSPResponseValidationResult(
+                    exception=json.JSONDecodeError("json error", "doc", 0)
+                ),
+            }
+        )
+        with pytest.warns(
+            DeprecationWarning, match="Support for custom revocation error classes"
+        ):
+            verify(verify_exception_deprecated, origin_cache)