Add urllib3-based retry for feature flag requests

Use urllib3's built-in Retry mechanism for feature flag POST requests
instead of application-level retry logic. This is simpler and leverages
well-tested library code.

Key changes:
- Add `RETRY_STATUS_FORCELIST` = [408, 500, 502, 503, 504]
- Add `_build_flags_session()` with POST retries and `status_forcelist`
- Update `flags()` to use dedicated flags session
- Add tests for retry configuration and session usage

The flags session retries on:
- Network failures (connect/read errors)
- Transient server errors (408, 500, 502, 503, 504)

It does NOT retry on:
- 429 (rate limit) - need to wait, not hammer
- 402 (quota limit) - won't resolve with retries

Author: haacked

posthog/request.py

@@ -8,7 +8,6 @@
 from io import BytesIO
 from typing import Any, List, Optional, Tuple, Union
 
-
 import requests
 from dateutil.tz import tzutc
 from requests.adapters import HTTPAdapter  # type: ignore[import-untyped]
@@ -42,6 +41,9 @@
     if hasattr(socket, attr):
         KEEP_ALIVE_SOCKET_OPTIONS.append((socket.SOL_TCP, getattr(socket, attr), value))
 
+# Status codes that indicate transient server errors worth retrying
+RETRY_STATUS_FORCELIST = [408, 500, 502, 503, 504]
+
 
 def _mask_tokens_in_url(url: str) -> str:
     """Mask token values in URLs for safe logging, keeping first 10 chars visible."""
@@ -71,6 +73,7 @@ def init_poolmanager(self, *args, **kwargs):
 
 
 def _build_session(socket_options: Optional[SocketOptions] = None) -> requests.Session:
+    """Build a session for general requests (batch, decide, etc.)."""
     adapter = HTTPAdapterWithSocketOptions(
         max_retries=Retry(
             total=2,
@@ -79,12 +82,38 @@ def _build_session(socket_options: Optional[SocketOptions] = None) -> requests.S
         ),
         socket_options=socket_options,
     )
-    session = requests.sessions.Session()
+    session = requests.Session()
+    session.mount("https://", adapter)
+    return session
+
+
+def _build_flags_session(
+    socket_options: Optional[SocketOptions] = None,
+) -> requests.Session:
+    """
+    Build a session for feature flag requests with POST retries.
+
+    Feature flag requests are idempotent (read-only), so retrying POST
+    requests is safe. This session retries on transient server errors
+    (408, 5xx) and network failures.
+    """
+    adapter = HTTPAdapterWithSocketOptions(
+        max_retries=Retry(
+            total=2,
+            connect=2,
+            read=2,
+            status_forcelist=RETRY_STATUS_FORCELIST,
+            allowed_methods=["POST"],
+        ),
+        socket_options=socket_options,
+    )
+    session = requests.Session()
     session.mount("https://", adapter)
     return session
 
 
 _session = _build_session()
+_flags_session = _build_flags_session()
 _socket_options: Optional[SocketOptions] = None
 _pooling_enabled = True
 
@@ -95,6 +124,12 @@ def _get_session() -> requests.Session:
     return _build_session(_socket_options)
 
 
+def _get_flags_session() -> requests.Session:
+    if _pooling_enabled:
+        return _flags_session
+    return _build_flags_session(_socket_options)
+
+
 def set_socket_options(socket_options: Optional[SocketOptions]) -> None:
     """
     Configure socket options for all HTTP connections.
@@ -103,11 +138,12 @@ def set_socket_options(socket_options: Optional[SocketOptions]) -> None:
         from posthog import set_socket_options
         set_socket_options([(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)])
     """
-    global _session, _socket_options
+    global _session, _flags_session, _socket_options
     if socket_options == _socket_options:
         return
     _socket_options = socket_options
     _session = _build_session(socket_options)
+    _flags_session = _build_flags_session(socket_options)
 
 
 def enable_keep_alive() -> None:
@@ -145,6 +181,7 @@ def post(
     path=None,
     gzip: bool = False,
     timeout: int = 15,
+    session: Optional[requests.Session] = None,
     **kwargs,
 ) -> requests.Response:
     """Post the `kwargs` to the API"""
@@ -165,7 +202,9 @@ def post(
             gz.write(data.encode("utf-8"))
         data = buf.getvalue()
 
-    res = _get_session().post(url, data=data, headers=headers, timeout=timeout)
+    res = (session or _get_session()).post(
+        url, data=data, headers=headers, timeout=timeout
+    )
 
     if res.status_code == 200:
         log.debug("data uploaded successfully")
@@ -221,8 +260,21 @@ def flags(
     timeout: int = 15,
     **kwargs,
 ) -> Any:
-    """Post the `kwargs to the flags API endpoint"""
-    res = post(api_key, host, "/flags/?v=2", gzip, timeout, **kwargs)
+    """
+    Post the kwargs to the flags API endpoint.
+
+    Uses a session configured to retry on transient server errors (408, 5xx)
+    and network failures. Retries are handled by urllib3 with exponential backoff.
+    """
+    res = post(
+        api_key,
+        host,
+        "/flags/?v=2",
+        gzip,
+        timeout,
+        session=_get_flags_session(),
+        **kwargs,
+    )
     return _process_response(
         res, success_message="Feature flags evaluated successfully"
     )

posthog/test/test_request.py

@@ -19,6 +19,7 @@
     determine_server_host,
     disable_connection_reuse,
     enable_keep_alive,
+    flags,
     get,
     set_socket_options,
 )
@@ -393,3 +394,66 @@ def test_set_socket_options_is_idempotent():
         assert session1 is session2
     finally:
         set_socket_options(None)
+
+
+class TestFlagsSession(unittest.TestCase):
+    """Tests for flags session configuration."""
+
+    def test_retry_status_forcelist_excludes_rate_limits(self):
+        """Verify 429 (rate limit) is NOT retried - need to wait, not hammer."""
+        from posthog.request import RETRY_STATUS_FORCELIST
+
+        self.assertNotIn(429, RETRY_STATUS_FORCELIST)
+
+    def test_retry_status_forcelist_excludes_quota_errors(self):
+        """Verify 402 (payment required/quota) is NOT retried - won't resolve."""
+        from posthog.request import RETRY_STATUS_FORCELIST
+
+        self.assertNotIn(402, RETRY_STATUS_FORCELIST)
+
+    @mock.patch("posthog.request._get_flags_session")
+    def test_flags_uses_flags_session(self, mock_get_flags_session):
+        """flags() uses the dedicated flags session, not the general session."""
+        mock_response = requests.Response()
+        mock_response.status_code = 200
+        mock_response._content = json.dumps(
+            {
+                "featureFlags": {"test-flag": True},
+                "featureFlagPayloads": {},
+                "errorsWhileComputingFlags": False,
+            }
+        ).encode("utf-8")
+
+        mock_session = mock.MagicMock()
+        mock_session.post.return_value = mock_response
+        mock_get_flags_session.return_value = mock_session
+
+        result = flags("test-key", "https://test.posthog.com", distinct_id="user123")
+
+        self.assertEqual(result["featureFlags"]["test-flag"], True)
+        mock_get_flags_session.assert_called_once()
+        mock_session.post.assert_called_once()
+
+    @mock.patch("posthog.request._get_flags_session")
+    def test_flags_no_retry_on_quota_limit(self, mock_get_flags_session):
+        """flags() raises QuotaLimitError without retrying (at application level)."""
+        mock_response = requests.Response()
+        mock_response.status_code = 200
+        mock_response._content = json.dumps(
+            {
+                "quotaLimited": ["feature_flags"],
+                "featureFlags": {},
+                "featureFlagPayloads": {},
+                "errorsWhileComputingFlags": False,
+            }
+        ).encode("utf-8")
+
+        mock_session = mock.MagicMock()
+        mock_session.post.return_value = mock_response
+        mock_get_flags_session.return_value = mock_session
+
+        with self.assertRaises(QuotaLimitError):
+            flags("test-key", "https://test.posthog.com", distinct_id="user123")
+
+        # QuotaLimitError is raised after response is received, not retried
+        self.assertEqual(mock_session.post.call_count, 1)