refactor: rename RefreshResult to ConnectionInfo (#334)

Renaming RefreshResult to ConnectionInfo to be better aligned
with other Connector libraries.

Aligning file names with that of Cloud SQL Python Connector by splitting
refresh.py into refresh_utils.py and connection_info.py

Author: jackwotherspoon

google/cloud/alloydb/connector/refresh.py renamed to google/cloud/alloydb/connector/connection_info.py

@@ -14,9 +14,6 @@
 
 from __future__ import annotations
 
-import asyncio
-from datetime import datetime
-from datetime import timezone
 import logging
 import ssl
 from tempfile import TemporaryDirectory
@@ -31,39 +28,8 @@
 
 logger = logging.getLogger(name=__name__)
 
-# _refresh_buffer is the amount of time before a refresh's result expires
-# that a new refresh operation begins.
-_refresh_buffer: int = 4 * 60  # 4 minutes
 
-
-def _seconds_until_refresh(
-    expiration: datetime, now: datetime = datetime.now(timezone.utc)
-) -> int:
-    """
-    Calculates the duration to wait before starting the next refresh.
-    Usually the duration will be half of the time until certificate
-    expiration.
-
-    Args:
-        expiration (datetime.datetime): Time of certificate expiration.
-        now (datetime.datetime): Current time (UTC)
-    Returns:
-        int: Time in seconds to wait before performing next refresh.
-    """
-
-    duration = int((expiration - now).total_seconds())
-
-    # if certificate duration is less than 1 hour
-    if duration < 3600:
-        # something is wrong with certificate, refresh now
-        if duration < _refresh_buffer:
-            return 0
-        # otherwise wait until 4 minutes before expiration for next refresh
-        return duration - _refresh_buffer
-    return duration // 2
-
-
-class RefreshResult:
+class ConnectionInfo:
     """
     Manages the result of a refresh operation.
 
@@ -91,8 +57,6 @@ def __init__(
         self.context.check_hostname = False
         # force TLSv1.3
         self.context.minimum_version = ssl.TLSVersion.TLSv1_3
-        # add request_ssl attribute to ssl.SSLContext, required for pg8000 driver
-        self.context.request_ssl = False  # type: ignore
         # unpack certs
         ca_cert, cert_chain = certs
         # get expiration from client certificate
@@ -108,15 +72,3 @@ def __init__(
             )
             self.context.load_cert_chain(cert_chain_filename, keyfile=key_filename)
             self.context.load_verify_locations(cafile=ca_filename)
-
-
-async def _is_valid(task: asyncio.Task) -> bool:
-    try:
-        result = await task
-        # valid if current time is before cert expiration
-        if datetime.now(timezone.utc) < result.expiration:
-            return True
-    except Exception:
-        # suppress any errors from task
-        logger.debug("Current refresh result is invalid.")
-    return False

google/cloud/alloydb/connector/instance.py

@@ -23,12 +23,12 @@
 from google.auth.credentials import TokenState
 from google.auth.transport import requests
 
+from google.cloud.alloydb.connector.connection_info import ConnectionInfo
 from google.cloud.alloydb.connector.exceptions import IPTypeNotFoundError
 from google.cloud.alloydb.connector.exceptions import RefreshError
 from google.cloud.alloydb.connector.rate_limiter import AsyncRateLimiter
-from google.cloud.alloydb.connector.refresh import _is_valid
-from google.cloud.alloydb.connector.refresh import _seconds_until_refresh
-from google.cloud.alloydb.connector.refresh import RefreshResult
+from google.cloud.alloydb.connector.refresh_utils import _is_valid
+from google.cloud.alloydb.connector.refresh_utils import _seconds_until_refresh
 
 if TYPE_CHECKING:
     import ssl
@@ -117,15 +117,15 @@ def __init__(
         self._current: asyncio.Task = self._schedule_refresh(0)
         self._next: asyncio.Task = self._current
 
-    async def _perform_refresh(self) -> RefreshResult:
+    async def _perform_refresh(self) -> ConnectionInfo:
         """
         Perform a refresh operation on an AlloyDB instance.
 
         Retrieves metadata and generates new client certificate
         required to connect securely to the AlloyDB instance.
 
         Returns:
-            RefreshResult: Result of the refresh operation.
+            ConnectionInfo: Result of the refresh operation.
         """
         self._refresh_in_progress.set()
         logger.debug(f"['{self._instance_uri}']: Entered _perform_refresh")
@@ -168,7 +168,7 @@ async def _perform_refresh(self) -> RefreshResult:
         finally:
             self._refresh_in_progress.clear()
 
-        return RefreshResult(ip_addr, priv_key, certs)
+        return ConnectionInfo(ip_addr, priv_key, certs)
 
     def _schedule_refresh(self, delay: int) -> asyncio.Task:
         """
@@ -178,12 +178,12 @@ def _schedule_refresh(self, delay: int) -> asyncio.Task:
             delay (int): Time in seconds to sleep before performing refresh.
 
         Returns:
-            asyncio.Task[RefreshResult]: A task representing the scheduled
+            asyncio.Task[ConnectionInfo]: A task representing the scheduled
                 refresh operation.
         """
         return asyncio.create_task(self._refresh_operation(delay))
 
-    async def _refresh_operation(self, delay: int) -> RefreshResult:
+    async def _refresh_operation(self, delay: int) -> ConnectionInfo:
         """
         A coroutine that sleeps for the specified amount of time before
         running _perform_refresh.
@@ -192,7 +192,7 @@ async def _refresh_operation(self, delay: int) -> RefreshResult:
             delay (int): Time in seconds to sleep before performing refresh.
 
         Returns:
-            RefreshResult: Refresh result for an AlloyDB instance.
+            ConnectionInfo: Refresh result for an AlloyDB instance.
         """
         refresh_task: asyncio.Task
         try:
@@ -251,7 +251,7 @@ async def connection_info(self, ip_type: IPTypes) -> Tuple[str, ssl.SSLContext]:
             Tuple[str, ssl.SSLContext]: AlloyDB instance IP address
                 and configured TLS connection.
         """
-        refresh: RefreshResult = await self._current
+        refresh: ConnectionInfo = await self._current
         ip_address = refresh.ip_addrs.get(ip_type.value)
         if ip_address is None:
             raise IPTypeNotFoundError(

google/cloud/alloydb/connector/refresh_utils.py

@@ -0,0 +1,65 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime
+from datetime import timezone
+import logging
+
+logger = logging.getLogger(name=__name__)
+
+# _refresh_buffer is the amount of time before a refresh's result expires
+# that a new refresh operation begins.
+_refresh_buffer: int = 4 * 60  # 4 minutes
+
+
+def _seconds_until_refresh(
+    expiration: datetime, now: datetime = datetime.now(timezone.utc)
+) -> int:
+    """
+    Calculates the duration to wait before starting the next refresh.
+    Usually the duration will be half of the time until certificate
+    expiration.
+
+    Args:
+        expiration (datetime.datetime): Time of certificate expiration.
+        now (datetime.datetime): Current time (UTC)
+    Returns:
+        int: Time in seconds to wait before performing next refresh.
+    """
+
+    duration = int((expiration - now).total_seconds())
+
+    # if certificate duration is less than 1 hour
+    if duration < 3600:
+        # something is wrong with certificate, refresh now
+        if duration < _refresh_buffer:
+            return 0
+        # otherwise wait until 4 minutes before expiration for next refresh
+        return duration - _refresh_buffer
+    return duration // 2
+
+
+async def _is_valid(task: asyncio.Task) -> bool:
+    try:
+        result = await task
+        # valid if current time is before cert expiration
+        if datetime.now(timezone.utc) < result.expiration:
+            return True
+    except Exception:
+        # suppress any errors from task
+        logger.debug("Current refresh result is invalid.")
+    return False

tests/unit/test_refresh.py renamed to tests/unit/test_connection_info.py

@@ -23,42 +23,12 @@
 from cryptography.hazmat.primitives.asymmetric import rsa
 from mocks import FakeInstance
 
-from google.cloud.alloydb.connector.refresh import _seconds_until_refresh
-from google.cloud.alloydb.connector.refresh import RefreshResult
+from google.cloud.alloydb.connector.connection_info import ConnectionInfo
 
 
-def test_seconds_until_refresh_over_1_hour() -> None:
+def test_ConnectionInfo_init_(fake_instance: FakeInstance) -> None:
     """
-    Test _seconds_until_refresh returns proper time in seconds.
-    If expiration is over 1 hour, should return duration/2.
-    """
-    now = datetime.now()
-    assert _seconds_until_refresh(now + timedelta(minutes=62), now) == 31 * 60
-
-
-def test_seconds_until_refresh_under_1_hour_over_4_mins() -> None:
-    """
-    Test _seconds_until_refresh returns proper time in seconds.
-    If expiration is under 1 hour and over 4 minutes,
-    should return duration-refresh_buffer (refresh_buffer = 4 minutes).
-    """
-    now = datetime.now(timezone.utc)
-    assert _seconds_until_refresh(now + timedelta(minutes=5), now) == 60
-
-
-def test_seconds_until_refresh_under_4_mins() -> None:
-    """
-    Test _seconds_until_refresh returns proper time in seconds.
-    If expiration is under 4 minutes, should return 0.
-    """
-    assert (
-        _seconds_until_refresh(datetime.now(timezone.utc) + timedelta(minutes=3)) == 0
-    )
-
-
-def test_RefreshResult_init_(fake_instance: FakeInstance) -> None:
-    """
-    Test to check whether the __init__ method of RefreshResult
+    Test to check whether the __init__ method of ConnectionInfo
     can correctly initialize TLS context.
     """
     key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
@@ -79,7 +49,6 @@ def test_RefreshResult_init_(fake_instance: FakeInstance) -> None:
         "UTF-8"
     )
     certs = (ca_cert, [client_cert, intermediate_cert, root_cert])
-    refresh = RefreshResult(fake_instance.ip_addrs, key, certs)
+    refresh = ConnectionInfo(fake_instance.ip_addrs, key, certs)
     # verify TLS requirements
     assert refresh.context.minimum_version == ssl.TLSVersion.TLSv1_3
-    assert refresh.context.request_ssl is False

tests/unit/test_instance.py

@@ -21,13 +21,13 @@
 from mocks import FakeAlloyDBClient
 import pytest
 
+from google.cloud.alloydb.connector.connection_info import ConnectionInfo
 from google.cloud.alloydb.connector.exceptions import IPTypeNotFoundError
 from google.cloud.alloydb.connector.exceptions import RefreshError
 from google.cloud.alloydb.connector.instance import _parse_instance_uri
 from google.cloud.alloydb.connector.instance import IPTypes
 from google.cloud.alloydb.connector.instance import RefreshAheadCache
-from google.cloud.alloydb.connector.refresh import _is_valid
-from google.cloud.alloydb.connector.refresh import RefreshResult
+from google.cloud.alloydb.connector.refresh_utils import _is_valid
 from google.cloud.alloydb.connector.utils import generate_keys
 
 
@@ -125,7 +125,7 @@ async def test_RefreshAheadCache_close() -> None:
 
 @pytest.mark.asyncio
 async def test_perform_refresh() -> None:
-    """Test that _perform refresh returns valid RefreshResult"""
+    """Test that _perform refresh returns valid ConnectionInfo"""
     keys = asyncio.create_task(generate_keys())
     client = FakeAlloyDBClient()
     cache = RefreshAheadCache(
@@ -299,6 +299,6 @@ async def test_force_refresh_cancels_pending_refresh() -> None:
         assert await pending_refresh
     # verify pending_refresh has now been cancelled
     assert pending_refresh.cancelled() is True
-    assert isinstance(await cache._current, RefreshResult)
+    assert isinstance(await cache._current, ConnectionInfo)
     # close instance
     await cache.close()

tests/unit/test_refresh_utils.py

@@ -0,0 +1,48 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from datetime import datetime
+from datetime import timedelta
+from datetime import timezone
+
+from google.cloud.alloydb.connector.refresh_utils import _seconds_until_refresh
+
+
+def test_seconds_until_refresh_over_1_hour() -> None:
+    """
+    Test _seconds_until_refresh returns proper time in seconds.
+    If expiration is over 1 hour, should return duration/2.
+    """
+    now = datetime.now()
+    assert _seconds_until_refresh(now + timedelta(minutes=62), now) == 31 * 60
+
+
+def test_seconds_until_refresh_under_1_hour_over_4_mins() -> None:
+    """
+    Test _seconds_until_refresh returns proper time in seconds.
+    If expiration is under 1 hour and over 4 minutes,
+    should return duration-refresh_buffer (refresh_buffer = 4 minutes).
+    """
+    now = datetime.now(timezone.utc)
+    assert _seconds_until_refresh(now + timedelta(minutes=5), now) == 60
+
+
+def test_seconds_until_refresh_under_4_mins() -> None:
+    """
+    Test _seconds_until_refresh returns proper time in seconds.
+    If expiration is under 4 minutes, should return 0.
+    """
+    assert (
+        _seconds_until_refresh(datetime.now(timezone.utc) + timedelta(minutes=3)) == 0
+    )