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,20 +73,47 @@ 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,
+            connect=2,
+            read=2,
+        ),
+        socket_options=socket_options,
+    )
+    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.sessions.Session()
+    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:
@@ -221,8 +257,29 @@ 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.
+    """
+    log = logging.getLogger("posthog")
+    body = kwargs.copy()
+    body["sentAt"] = datetime.now(tz=tzutc()).isoformat()
+    url = remove_trailing_slash(host or DEFAULT_HOST) + "/flags/?v=2"
+    body["api_key"] = api_key
+    json_data = json.dumps(body, cls=DatetimeSerializer)
+    log.debug("making request: %s to url: %s", json_data, url)
+    headers = {"Content-Type": "application/json", "User-Agent": USER_AGENT}
+    data: Union[str, bytes] = json_data
+    if gzip:
+        headers["Content-Encoding"] = "gzip"
+        buf = BytesIO()
+        with GzipFile(fileobj=buf, mode="w") as gz:
+            gz.write(json_data.encode("utf-8"))
+        data = buf.getvalue()
+
+    res = _get_flags_session().post(url, data=data, headers=headers, timeout=timeout)
     return _process_response(
         res, success_message="Feature flags evaluated successfully"
     )

posthog/test/test_request.py

@@ -12,13 +12,15 @@
     DatetimeSerializer,
     GetResponse,
     KEEP_ALIVE_SOCKET_OPTIONS,
+    RETRY_STATUS_FORCELIST,
     QuotaLimitError,
     _mask_tokens_in_url,
     batch_post,
     decide,
     determine_server_host,
     disable_connection_reuse,
     enable_keep_alive,
+    flags,
     get,
     set_socket_options,
 )
@@ -393,3 +395,78 @@ def test_set_socket_options_is_idempotent():
         assert session1 is session2
     finally:
         set_socket_options(None)
+
+
+class TestRetryConfiguration(unittest.TestCase):
+    """Tests for retry configuration in feature flag requests."""
+
+    def test_retry_status_forcelist_contains_expected_codes(self):
+        """Verify RETRY_STATUS_FORCELIST contains the expected status codes."""
+        # 408 Request Timeout - client took too long to send request
+        # 500 Internal Server Error - transient server issue
+        # 502 Bad Gateway - upstream issue
+        # 503 Service Unavailable - temporary overload
+        # 504 Gateway Timeout - upstream timeout
+        expected = [408, 500, 502, 503, 504]
+        self.assertEqual(RETRY_STATUS_FORCELIST, expected)
+
+    def test_retry_status_forcelist_excludes_rate_limits(self):
+        """Verify 429 (rate limit) is NOT in RETRY_STATUS_FORCELIST."""
+        # Rate limits shouldn't be retried - need to wait, not hammer
+        self.assertNotIn(429, RETRY_STATUS_FORCELIST)
+
+    def test_retry_status_forcelist_excludes_quota_errors(self):
+        """Verify 402 (payment required/quota) is NOT in RETRY_STATUS_FORCELIST."""
+        # Quota errors won't resolve with retries
+        self.assertNotIn(402, RETRY_STATUS_FORCELIST)
+
+
+class TestFlagsSession(unittest.TestCase):
+    """Tests for flags session configuration."""
+
+    @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)