Skip to content

armgit / fli

Public Imported from GitHub
0

Google Flights MCP, CLI and Python Library

feat: clear TLS certificate errors and CA-bundle support (carries forward #164) (#251)

Punit Arani9982aff5de34
diff --git a/CLAUDE.md b/CLAUDE.md
index 1b13d7c..65779a8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -171,6 +171,11 @@ Consequences to keep in mind when changing search code:
- `FLI_SOCS_COOKIE` overrides the pre-accepted `SOCS` consent cookie the client
sends so EU/EEA IPs skip Google's consent interstitial; set it empty to send
no cookie.
+- `FLI_CA_BUNDLE` (then `CURL_CA_BUNDLE`, then `REQUESTS_CA_BUNDLE`) points the
+ client at a custom CA bundle for networks behind a TLS-intercepting
+ corporate proxy. A bad or missing path raises `SearchCertificateError`
+ (`error_type: "certificate_error"`) naming the variable; the client does
+ not retry it, since a fixed bundle either verifies or it doesn't.
## Key Files and Entry Points
@@ -284,6 +289,7 @@ as-is rather than renamed for the MCP tools.
| `parse_error` | `false` | Google served a page fli couldn't read. Usually (not always) a regional consent/blocked interstitial. Not retryable as-is; set `FLI_SOCS_COOKIE` (EU/EEA) and retry — don't just retry the same request unchanged. |
| `rejected_error` | `false` | Google refused the RPC outright (e.g. `get_booking_options`'s `GetBookingResults` call today — see above). Deterministic; retrying the same request will not help. |
| `timeout` | `true` | The request to Google Flights timed out. See retry guidance below. |
+| `certificate_error` | `false` | TLS certificate verification failed, most often behind a TLS-intercepting corporate proxy. Deterministic; set `FLI_CA_BUNDLE` (or `CURL_CA_BUNDLE` / `REQUESTS_CA_BUNDLE`) and try again — retrying unchanged will not help. |
| `connection_error` | `true` | A network/DNS issue prevented reaching Google Flights. See retry guidance below. |
| `http_error` | `true` iff `http_status` is 429 or 5xx | Non-2xx HTTP response from Google; check `http_status`. See retry guidance below. |
| `search_error` | `false` | Any other typed search-client failure not covered above. |
diff --git a/README.md b/README.md
index c1b3b8f..191487e 100644
--- a/README.md
+++ b/README.md
@@ -218,6 +218,13 @@ What that means in practice:
interstitial, which serves no `ds:1` blob. The client sends a pre-accepted
`SOCS` consent cookie by default; set `FLI_SOCS_COOKIE` to change the value,
or to an empty string to send none.
+* **`FLI_CA_BUNDLE` / `CURL_CA_BUNDLE` / `REQUESTS_CA_BUNDLE`.** Behind a
+ TLS-intercepting corporate proxy, set one of these (checked in that order)
+ to a PEM CA bundle path. A bad or missing path, or a certificate the bundle
+ doesn't cover, raises `SearchCertificateError` naming the variable — the
+ client does not retry it, since a fixed bundle either verifies or it doesn't.
+ Read once per worker thread on its first request; changing the value
+ doesn't affect a thread's already-created session.
## CLI Usage
diff --git a/docs/guides/mcp.md b/docs/guides/mcp.md
index ef8908b..e6bbde4 100644
--- a/docs/guides/mcp.md
+++ b/docs/guides/mcp.md
@@ -318,6 +318,7 @@ vocabulary once.
| `parse_error` | `false` | Google served a page fli couldn't read. Usually (not always) a regional consent/blocked interstitial. Not retryable as-is; set `FLI_SOCS_COOKIE` (EU/EEA) and retry — don't just retry the same request unchanged. |
| `rejected_error` | `false` | Google refused the RPC outright (e.g. `get_booking_options`'s `GetBookingResults` call today). Deterministic; retrying the same request will not help. |
| `timeout` | `true` | The request to Google Flights timed out. See retry guidance below. |
+| `certificate_error` | `false` | TLS certificate verification failed, most often behind a TLS-intercepting corporate proxy. Deterministic; set `FLI_CA_BUNDLE` (or `CURL_CA_BUNDLE` / `REQUESTS_CA_BUNDLE`) to a CA bundle path and try again — retrying unchanged will not help. |
| `connection_error` | `true` | A network/DNS issue prevented reaching Google Flights. See retry guidance below. |
| `http_error` | `true` iff `http_status` is 429 or 5xx | Non-2xx HTTP response from Google; check `http_status`. See retry guidance below. |
| `search_error` | `false` | Any other typed search-client failure not covered above. |
@@ -382,6 +383,23 @@ The MCP server can be configured via environment variables:
| `FLI_MCP_DEFAULT_DEPARTURE_WINDOW` | Default departure window (HH-HH) | null |
| `FLI_MCP_MAX_RESULTS` | Maximum results returned | null (no limit) |
+The underlying Google Flights HTTP client (shared with the CLI, not
+`FLI_MCP_`-prefixed) also honors these variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `FLI_TIMEOUT` | Request timeout in seconds | 60 |
+| `FLI_SOCS_COOKIE` | Consent cookie sent to skip Google's EU/EEA interstitial; set empty to send none | a pre-accepted value |
+| `FLI_CA_BUNDLE` | Path to a PEM CA bundle for networks with a custom certificate authority (e.g. a TLS-intercepting corporate proxy) | unset |
+| `CURL_CA_BUNDLE` | Fallback CA bundle path, used when `FLI_CA_BUNDLE` is unset | unset |
+| `REQUESTS_CA_BUNDLE` | Fallback CA bundle path, used when the two above are unset | unset |
+
+If a search fails with `error_type: "certificate_error"`, configure one of
+the CA bundle variables above instead of disabling TLS verification. These
+are read once per worker thread, the first time that thread makes a
+request — for a long-running MCP server process, restart it after changing
+one so already-created sessions pick up the new value.
+
## Example Conversations
Once configured with Claude Desktop, you can have natural conversations:
diff --git a/fli/cli/errors.py b/fli/cli/errors.py
index 2045f42..ce9f3df 100644
--- a/fli/cli/errors.py
+++ b/fli/cli/errors.py
@@ -19,6 +19,7 @@ import typer
from fli.cli.console import console
from fli.core.errors import classify_error
from fli.search.exceptions import (
+ SearchCertificateError,
SearchClientError,
SearchConnectionError,
SearchHTTPError,
@@ -35,6 +36,8 @@ def _friendly_message(exc: BaseException) -> str:
"""Return the short, user-facing message for ``exc``."""
if isinstance(exc, SearchTimeoutError):
return f"Request timed out. {exc}"
+ if isinstance(exc, SearchCertificateError):
+ return f"TLS certificate error. {exc}"
if isinstance(exc, SearchConnectionError):
return f"Network error. {exc}"
if isinstance(exc, SearchHTTPError):
diff --git a/fli/core/errors.py b/fli/core/errors.py
index 9d76697..9d6f229 100644
--- a/fli/core/errors.py
+++ b/fli/core/errors.py
@@ -34,6 +34,9 @@ PR #164 already independently converged on, and names *what happened*
(usually, but not always, a consent/blocked interstitial — see
``FLI_SOCS_COOKIE`` below). ``"rejected_error"``, ``"unsupported_error"``
and ``"validation_error"`` are new additions both surfaces now share.
+``"certificate_error"`` is a later addition, carried forward from PR #164 —
+its ``error_type`` naming was never released, so it was free to pick, and
+follows the same "name what happened" convention as ``parse_error``.
- ``validation_error`` (not retryable): bad parameters — pydantic
``ValidationError``, ``fli.core.parsers.ParseError``, or a bare
@@ -48,6 +51,12 @@ and ``"validation_error"`` are new additions both surfaces now share.
refused the RPC outright (e.g. booking options); deterministic,
retrying will not help.
- ``timeout`` (retryable): ``SearchTimeoutError``.
+- ``certificate_error`` (not retryable): ``SearchCertificateError`` — a
+ ``SearchConnectionError`` subclass, checked first: TLS certificate
+ verification failed, most often behind a TLS-intercepting corporate
+ proxy. Deterministic for a fixed CA bundle configuration, so retrying
+ unchanged will not help; set ``FLI_CA_BUNDLE`` (or ``CURL_CA_BUNDLE`` /
+ ``REQUESTS_CA_BUNDLE``) to point at the right CA bundle and try again.
- ``connection_error`` (retryable): ``SearchConnectionError``.
- ``http_error`` (retryable iff ``http_status`` is 429 or 5xx):
``SearchHTTPError``, with the status in ``http_status`` when known.
@@ -74,6 +83,7 @@ from typing import Any
from pydantic import ValidationError
from fli.search.exceptions import (
+ SearchCertificateError,
SearchClientError,
SearchConnectionError,
SearchHTTPError,
@@ -132,6 +142,12 @@ def classify_error(exc: BaseException) -> ErrorClassification:
"""
if isinstance(exc, SearchTimeoutError):
return ErrorClassification("timeout", retryable=True)
+ if isinstance(exc, SearchCertificateError):
+ # Checked before its parent SearchConnectionError: a bad or missing
+ # CA bundle / an untrusted certificate is deterministic for a fixed
+ # environment, unlike a transient DNS blip or dropped connection —
+ # so, unlike connection_error, this is not retryable.
+ return ErrorClassification("certificate_error", retryable=False)
if isinstance(exc, SearchConnectionError):
return ErrorClassification("connection_error", retryable=True)
if isinstance(exc, SearchHTTPError):
diff --git a/fli/search/__init__.py b/fli/search/__init__.py
index 79410f7..94b8022 100644
--- a/fli/search/__init__.py
+++ b/fli/search/__init__.py
@@ -1,5 +1,6 @@
from .dates import DatePrice, SearchDates
from .exceptions import (
+ SearchCertificateError,
SearchClientError,
SearchConnectionError,
SearchHTTPError,
@@ -17,6 +18,7 @@ __all__ = [
"SearchClientError",
"SearchTimeoutError",
"SearchConnectionError",
+ "SearchCertificateError",
"SearchHTTPError",
"SearchParseError",
"SearchRejectedError",
diff --git a/fli/search/client.py b/fli/search/client.py
index 1dcbdfe..942d4b2 100644
--- a/fli/search/client.py
+++ b/fli/search/client.py
@@ -24,10 +24,11 @@ import os
import threading
from typing import TYPE_CHECKING, Any
-from tenacity import retry, stop_after_attempt, wait_exponential
+from tenacity import retry, retry_if_not_exception_type, stop_after_attempt, wait_exponential
from fli.search._concurrency import TokenBucketRateLimiter
from fli.search.exceptions import (
+ SearchCertificateError,
SearchClientError,
SearchConnectionError,
SearchHTTPError,
@@ -82,6 +83,42 @@ DEFAULT_SOCS_COOKIE = (
)
SOCS_COOKIE = os.environ.get("FLI_SOCS_COOKIE", DEFAULT_SOCS_COOKIE)
+# A TLS-intercepting corporate proxy re-signs Google's certificate with a
+# private CA that curl's bundled trust store doesn't know about, so every
+# request fails verification. Checked in this order: FLI_CA_BUNDLE (this
+# client's own override) first, then CURL_CA_BUNDLE and REQUESTS_CA_BUNDLE —
+# the conventions curl and python-requests already use — so a developer who
+# has one of those set for other tools does not have to duplicate it, while
+# an explicit FLI_-prefixed value always wins.
+_CA_BUNDLE_ENV_VARS = ("FLI_CA_BUNDLE", "CURL_CA_BUNDLE", "REQUESTS_CA_BUNDLE")
+
+
+def _ca_bundle_from_env() -> str | None:
+ """Return the first configured CA bundle path from the supported env vars.
+
+ A configured path that is not a readable file raises
+ :class:`SearchCertificateError` naming both the variable and the path —
+ almost always a typo or a bundle that hasn't been mounted into a
+ container yet, and worth failing on immediately with a clear message
+ rather than surfacing later as a confusing curl error.
+
+ Called once per thread, from ``Client._session()`` when that thread's
+ session is first created — see its docstring for the caching
+ consequence (changing the env var afterwards does not affect an
+ already-created session).
+ """
+ for name in _CA_BUNDLE_ENV_VARS:
+ value = os.environ.get(name)
+ if not value:
+ continue
+ if not os.path.isfile(value) or not os.access(value, os.R_OK):
+ raise SearchCertificateError(
+ f"{name} points to a CA bundle path that does not exist or "
+ f"is not readable: {value!r}"
+ )
+ return value
+ return None
+
class Client:
"""HTTP client with built-in rate limiting, retry and user agent impersonation functionality.
@@ -106,7 +143,17 @@ class Client:
self._rate_limiter = TokenBucketRateLimiter(calls=calls_per_second, period=1.0)
def _session(self) -> Session:
- """Return this thread's ``Session``, creating it on first use."""
+ """Return this thread's ``Session``, creating it on first use.
+
+ The CA-bundle env vars (see ``_ca_bundle_from_env``) and
+ ``SOCS_COOKIE`` are only read the first time *this thread* needs a
+ session — once created, a thread's session is cached for its
+ lifetime (and the module-level singleton in ``get_client()``
+ extends that across the whole process). Changing ``FLI_CA_BUNDLE``
+ (or the other two) after a session already exists has no effect on
+ it; only a new thread, or a fresh ``Client()``, picks up the
+ change.
+ """
session = getattr(self._sessions, "session", None)
if session is None:
# Deferred import: ``curl_cffi`` is heavy (~100ms cold) and
@@ -118,6 +165,9 @@ class Client:
session.headers.update(self.DEFAULT_HEADERS)
if SOCS_COOKIE:
session.cookies.set("SOCS", SOCS_COOKIE, domain=".google.com")
+ ca_bundle = _ca_bundle_from_env()
+ if ca_bundle:
+ session.verify = ca_bundle
self._sessions.session = session
return session
@@ -134,7 +184,20 @@ class Client:
# Request entry points
# ------------------------------------------------------------------
- @retry(stop=stop_after_attempt(3), wait=wait_exponential(), reraise=True)
+ # A bad CA bundle path or an untrusted certificate is deterministic for
+ # a fixed environment — retrying the identical request three times with
+ # backoff before the user ever sees the actionable message just wastes
+ # their time, so SearchCertificateError is the one failure mode this
+ # decorator does not retry. retry_if_not_exception_type() sees the
+ # *wrapped* type here, not the raw curl exception: `except Exception`
+ # below always re-raises via `_wrap_request_error(...)` before this
+ # decorator's predicate ever runs.
+ @retry(
+ stop=stop_after_attempt(3),
+ wait=wait_exponential(),
+ retry=retry_if_not_exception_type(SearchCertificateError),
+ reraise=True,
+ )
def get(self, url: str, **kwargs: Any) -> Response:
"""Make a rate-limited GET request with automatic retries."""
self._rate_limiter.acquire()
@@ -146,7 +209,12 @@ class Client:
except Exception as e:
raise _wrap_request_error("GET", url, e) from e
- @retry(stop=stop_after_attempt(3), wait=wait_exponential(), reraise=True)
+ @retry(
+ stop=stop_after_attempt(3),
+ wait=wait_exponential(),
+ retry=retry_if_not_exception_type(SearchCertificateError),
+ reraise=True,
+ )
def post(self, url: str, **kwargs: Any) -> Response:
"""Make a rate-limited POST request with automatic retries."""
self._rate_limiter.acquire()
@@ -159,6 +227,16 @@ class Client:
raise _wrap_request_error("POST", url, e) from e
+# libcurl's CURLE_PEER_FAILED_VERIFICATION code. curl_cffi's own
+# ``code2error`` dispatch maps this 1:1 to ``CertificateVerifyError`` on
+# both 0.15.0 and 0.16.3 (exceptions.py's CODE2ERROR table has no other
+# entry for it in either version), so the isinstance() check below is
+# normally enough on its own — see is_untyped_certificate_error in
+# _wrap_request_error for what this constant backs and why it's kept
+# despite being unreachable on those two versions.
+_CURLE_PEER_FAILED_VERIFICATION = 60
+
+
def _wrap_request_error(method: str, url: str, exc: BaseException) -> SearchClientError:
"""Map curl-cffi / network errors into our typed ``SearchClientError`` family.
@@ -177,6 +255,36 @@ def _wrap_request_error(method: str, url: str, exc: BaseException) -> SearchClie
from curl_cffi.requests import exceptions as curl_exc
host = _host_from_url(url)
+
+ # ``CertificateVerifyError`` is itself an ``SSLError`` -> ``ConnectionError``
+ # subclass, so this must run before the generic ``curl_exc.ConnectionError``
+ # branch below or a bad certificate would silently read as a vague "check
+ # your connection" message instead of naming the fix. Two independent
+ # forward-compat guards, kept as separate named conditions since they
+ # guard against different future breakages:
+ #
+ # - is_typed_certificate_error: the normal case today. ``getattr(...,
+ # ())`` keeps this safe if a future curl_cffi release ever drops the
+ # class entirely — ``isinstance(exc, ())`` is simply always False.
+ # - is_untyped_certificate_error: belt-and-suspenders for a future
+ # release that raises the plain ``SSLError``/``ConnectionError`` base
+ # class with the same code instead of the ``CertificateVerifyError``
+ # subclass (see ``_CURLE_PEER_FAILED_VERIFICATION`` above — confirmed
+ # unreachable on curl_cffi 0.15.0/0.16.3, kept anyway).
+ certificate_error_cls = getattr(curl_exc, "CertificateVerifyError", ())
+ is_typed_certificate_error = certificate_error_cls and isinstance(exc, certificate_error_cls)
+ is_untyped_certificate_error = (
+ isinstance(exc, curl_exc.ConnectionError)
+ and getattr(exc, "code", None) == _CURLE_PEER_FAILED_VERIFICATION
+ )
+ if is_typed_certificate_error or is_untyped_certificate_error:
+ env_vars = ", ".join(_CA_BUNDLE_ENV_VARS)
+ return SearchCertificateError(
+ f"TLS certificate verification failed for Google Flights ({host}). "
+ f"If your network uses a custom certificate authority (e.g. a "
+ f"TLS-intercepting corporate proxy), set one of {env_vars} to a "
+ f"CA bundle path and try again."
+ )
if isinstance(exc, curl_exc.Timeout):
return SearchTimeoutError(
f"Timed out talking to Google Flights ({host}). "
diff --git a/fli/search/exceptions.py b/fli/search/exceptions.py
index 3e92063..4a45891 100644
--- a/fli/search/exceptions.py
+++ b/fli/search/exceptions.py
@@ -21,6 +21,19 @@ class SearchConnectionError(SearchClientError):
"""A network/DNS issue prevented us from reaching Google Flights."""
+class SearchCertificateError(SearchConnectionError):
+ """TLS certificate verification failed while reaching Google Flights.
+
+ A subclass of :class:`SearchConnectionError` rather than a sibling —
+ it *is* a connection failure — but it is deterministic for a given CA
+ bundle configuration (unlike a transient DNS blip or dropped packet),
+ so callers classify and retry it differently. See
+ ``fli.search.client._ca_bundle_from_env`` and ``FLI_CA_BUNDLE`` /
+ ``CURL_CA_BUNDLE`` / ``REQUESTS_CA_BUNDLE`` for the fix a user behind a
+ TLS-intercepting corporate proxy needs.
+ """
+
+
class SearchHTTPError(SearchClientError):
"""Google Flights returned a non-2xx HTTP response."""
diff --git a/tests/cli/test_dates.py b/tests/cli/test_dates.py
index 408bce7..a5cc12c 100644
--- a/tests/cli/test_dates.py
+++ b/tests/cli/test_dates.py
@@ -11,6 +11,7 @@ from fli.models import Airline
from fli.models.google_flights.base import TripType
from fli.search import DatePrice
from fli.search.exceptions import (
+ SearchCertificateError,
SearchClientError,
SearchConnectionError,
SearchHTTPError,
@@ -451,6 +452,11 @@ def test_dates_json_invalid_airport_code(runner, mock_search_dates, mock_console
# Released v0.9.0 CLI --format json values — must not move.
pytest.param(SearchTimeoutError("slow"), "timeout", True, id="timeout"),
pytest.param(SearchConnectionError("no route"), "connection_error", True, id="connection"),
+ # Fix round 1 (I3): certificate_error is a SearchConnectionError
+ # subclass but, unlike its parent, deterministic — not retryable.
+ pytest.param(
+ SearchCertificateError("bad cert"), "certificate_error", False, id="certificate"
+ ),
pytest.param(SearchHTTPError("bad gw", status_code=502), "http_error", True, id="http-5xx"),
pytest.param(
SearchClientError("generic"), "search_error", False, id="generic-search-error"
diff --git a/tests/cli/test_errors.py b/tests/cli/test_errors.py
index aa7f474..59c57bc 100644
--- a/tests/cli/test_errors.py
+++ b/tests/cli/test_errors.py
@@ -11,6 +11,7 @@ from fli.cli.errors import _write_log, json_error_payload, report_cli_error
from fli.cli.main import app
from fli.core.parsers import ParseError
from fli.search.exceptions import (
+ SearchCertificateError,
SearchClientError,
SearchConnectionError,
SearchHTTPError,
@@ -67,6 +68,9 @@ def test_write_log_creates_file_with_traceback(tmp_path):
# T10 fix round 2 report's "Behaviour changes" section.
(SearchTimeoutError("timed out"), "timeout", True),
(SearchConnectionError("dns"), "connection_error", True),
+ # Carried forward from PR #164 (T23): a SearchConnectionError
+ # subclass, but deterministic — not retryable, unlike its parent.
+ (SearchCertificateError("bad cert"), "certificate_error", False),
(SearchHTTPError("403", status_code=403), "http_error", False),
(SearchClientError("generic"), "search_error", False),
(RuntimeError("boom"), "unexpected_error", False),
@@ -175,6 +179,7 @@ def test_multi_command_reports_unsupported(runner, tmp_path):
"exc, expected_msg",
[
(SearchTimeoutError("slow"), "Request timed out. slow"),
+ (SearchCertificateError("bad cert"), "TLS certificate error. bad cert"),
(SearchConnectionError("dns"), "Network error. dns"),
(SearchHTTPError("403", status_code=403), "Google Flights error. 403"),
(SearchClientError("generic failure"), "Search failed. generic failure"),
diff --git a/tests/cli/test_flights.py b/tests/cli/test_flights.py
index b3d20a1..4f9acb4 100644
--- a/tests/cli/test_flights.py
+++ b/tests/cli/test_flights.py
@@ -10,6 +10,7 @@ from fli.cli.main import app
from fli.models import Airline, Airport, FlightLeg, FlightResult, SeatType
from fli.models.google_flights.base import TripType
from fli.search.exceptions import (
+ SearchCertificateError,
SearchClientError,
SearchConnectionError,
SearchHTTPError,
@@ -256,6 +257,11 @@ def test_flights_json_stubbed_blocked_page(runner, mock_search_flights, mock_con
# Released v0.9.0 CLI --format json values — must not move.
pytest.param(SearchTimeoutError("slow"), "timeout", True, id="timeout"),
pytest.param(SearchConnectionError("no route"), "connection_error", True, id="connection"),
+ # Fix round 1 (I3): certificate_error is a SearchConnectionError
+ # subclass but, unlike its parent, deterministic — not retryable.
+ pytest.param(
+ SearchCertificateError("bad cert"), "certificate_error", False, id="certificate"
+ ),
pytest.param(SearchHTTPError("bad gw", status_code=502), "http_error", True, id="http-5xx"),
pytest.param(
SearchClientError("generic"), "search_error", False, id="generic-search-error"
diff --git a/tests/conftest.py b/tests/conftest.py
index d43c662..ccecd13 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -38,6 +38,29 @@ def pin_today(monkeypatch):
return _pin
[email protected](autouse=True)
+def _scrub_ca_bundle_env(monkeypatch):
+ """Clear FLI_CA_BUNDLE / CURL_CA_BUNDLE / REQUESTS_CA_BUNDLE for every test.
+
+ ``fli.search.client._ca_bundle_from_env()`` reads these on first use of a
+ thread's session and raises ``SearchCertificateError`` if a configured
+ path is not a readable file. An ambient value is very plausible on a
+ developer machine or CI runner behind a corporate proxy, and since fli
+ reads these variables it is load-bearing. Without this fixture, any test
+ that indirectly builds a fresh session — a CLI command, a bare
+ ``Client()``/``get_client()`` — on a machine with e.g. a stale
+ ``CURL_CA_BUNDLE=/no/longer/there`` would
+ fail with an unrelated ``SearchCertificateError`` instead of exercising
+ the behavior actually under test. Autouse, session-wide, so no test file
+ has to remember to opt in; a test that wants to exercise the CA-bundle
+ mechanism itself sets the variable(s) back with ``monkeypatch.setenv``
+ after this fixture has already cleared them.
+ """
+ monkeypatch.delenv("FLI_CA_BUNDLE", raising=False)
+ monkeypatch.delenv("CURL_CA_BUNDLE", raising=False)
+ monkeypatch.delenv("REQUESTS_CA_BUNDLE", raising=False)
+
+
def pytest_addoption(parser) -> None:
"""Add options to pytest."""
parser.addoption("--fuzz", action="store_true", help="Run fuzz tests")
diff --git a/tests/core/test_error_type_parity.py b/tests/core/test_error_type_parity.py
index a047ae8..3b59019 100644
--- a/tests/core/test_error_type_parity.py
+++ b/tests/core/test_error_type_parity.py
@@ -62,6 +62,7 @@ from fli.mcp.server import (
_execute_flight_search,
)
from fli.search.exceptions import (
+ SearchCertificateError,
SearchClientError,
SearchConnectionError,
SearchHTTPError,
@@ -116,6 +117,11 @@ _INSTANCES: dict[type, BaseException] = {
ValueError: ValueError("bad date range"),
ValidationError: _pydantic_validation_error(),
Exception: Exception("totally unclassified"),
+ # Carried forward from PR #164 (T23): a SearchConnectionError subclass,
+ # but deterministic for a fixed CA bundle — checked separately so CLI
+ # and MCP agree it is certificate_error/not-retryable, not the parent's
+ # connection_error/retryable.
+ SearchCertificateError: SearchCertificateError("bad cert"),
}
diff --git a/tests/core/test_errors.py b/tests/core/test_errors.py
index 9931ad3..52096b2 100644
--- a/tests/core/test_errors.py
+++ b/tests/core/test_errors.py
@@ -25,6 +25,7 @@ from pydantic import BaseModel, ValidationError
from fli.core.errors import ErrorClassification, classify_error
from fli.core.parsers import ParseError
from fli.search.exceptions import (
+ SearchCertificateError,
SearchClientError,
SearchConnectionError,
SearchHTTPError,
@@ -56,6 +57,13 @@ _EXPECTED: dict[type, tuple[type[BaseException], tuple[str, bool]]] = {
SearchClientError: (SearchClientError("boom"), ("search_error", False)),
SearchTimeoutError: (SearchTimeoutError("timed out"), ("timeout", True)),
SearchConnectionError: (SearchConnectionError("no route"), ("connection_error", True)),
+ # A SearchConnectionError subclass, but deterministic (a fixed CA bundle
+ # / certificate either verifies or it doesn't) — unlike its parent, not
+ # retryable. See classify_error()'s docstring and PR #164.
+ SearchCertificateError: (
+ SearchCertificateError("bad cert"),
+ ("certificate_error", False),
+ ),
SearchHTTPError: (SearchHTTPError("bad response", status_code=500), ("http_error", True)),
SearchRejectedError: (SearchRejectedError(13), ("rejected_error", False)),
SearchUnsupportedError: (SearchUnsupportedError("multi-city"), ("unsupported_error", False)),
diff --git a/tests/mcp/test_error_type_responses.py b/tests/mcp/test_error_type_responses.py
index 5f2aeaa..58d115c 100644
--- a/tests/mcp/test_error_type_responses.py
+++ b/tests/mcp/test_error_type_responses.py
@@ -28,6 +28,7 @@ from fli.mcp.server import (
_find_airports_impl,
)
from fli.search.exceptions import (
+ SearchCertificateError,
SearchClientError,
SearchConnectionError,
SearchHTTPError,
@@ -55,6 +56,15 @@ def _raiser(exc: BaseException):
_SEARCH_CLIENT_ERROR_CASES = [
pytest.param(SearchTimeoutError("slow"), "timeout", True, id="timeout"),
pytest.param(SearchConnectionError("no route"), "connection_error", True, id="connection"),
+ # Carried forward from PR #164 (T23): a TLS certificate failure must be
+ # visible to MCP clients as its own, non-retryable error_type — not
+ # folded into its retryable parent, connection_error.
+ pytest.param(
+ SearchCertificateError("TLS certificate verification failed"),
+ "certificate_error",
+ False,
+ id="certificate",
+ ),
pytest.param(
SearchHTTPError("bad gateway", status_code=502), "http_error", True, id="http-5xx"
),
diff --git a/tests/search/test_client_errors.py b/tests/search/test_client_errors.py
new file mode 100644
index 0000000..7dbd781
--- /dev/null
+++ b/tests/search/test_client_errors.py
@@ -0,0 +1,420 @@
+"""Tests for TLS certificate error classification and CA-bundle configuration.
+
+Carries forward the TLS half of PR #164 (the `error_type` half already
+landed via PR #248's shared classifier). Every test below explicitly
+clears/sets all three CA-bundle env vars — never relies on ambient state —
+so a developer's own `REQUESTS_CA_BUNDLE` (common on corporate machines)
+can't leak into the assertions.
+"""
+
+from __future__ import annotations
+
+import pytest
+from curl_cffi.requests import exceptions as curl_exc
+
+import fli.search.client as client_module
+from fli.search.client import Client, _ca_bundle_from_env, _wrap_request_error
+from fli.search.exceptions import SearchCertificateError, SearchConnectionError
+
+
[email protected](autouse=True)
+def _clean_ca_bundle_env(monkeypatch):
+ """Clear all three CA-bundle env vars before every test in this module.
+
+ Individual tests opt back in with ``monkeypatch.setenv`` for the
+ variable(s) they care about — this fixture only guarantees no ambient
+ value (e.g. a developer's own ``REQUESTS_CA_BUNDLE``) leaks in.
+
+ Fix round 1 (C1) added an equivalent autouse fixture to
+ ``tests/conftest.py`` that clears the same three variables for the
+ *whole* suite, which makes the delenv calls here mechanically
+ redundant. Kept anyway, deliberately: this file's entire subject is
+ CA-bundle env var behavior, so a reader should be able to trust its
+ isolation by reading this file alone, without having to go verify
+ conftest.py also does it — explicit beats implicit for the one file
+ where it's the whole point.
+ """
+ monkeypatch.delenv("FLI_CA_BUNDLE", raising=False)
+ monkeypatch.delenv("CURL_CA_BUNDLE", raising=False)
+ monkeypatch.delenv("REQUESTS_CA_BUNDLE", raising=False)
+
+
[email protected](autouse=True)
+def _reset_client_singleton():
+ """Each test starts with a clean singleton so tests don't share state."""
+ original = client_module.client
+ client_module.client = None
+ yield
+ client_module.client = original
+
+
+# ---------------------------------------------------------------------------
+# _ca_bundle_from_env: precedence, empty values, and bad paths
+# ---------------------------------------------------------------------------
+
+
+class TestCaBundleFromEnv:
+ def test_fli_ca_bundle_wins_over_the_others(self, monkeypatch, tmp_path):
+ fli_bundle = tmp_path / "fli.pem"
+ curl_bundle = tmp_path / "curl.pem"
+ requests_bundle = tmp_path / "requests.pem"
+ for path in (fli_bundle, curl_bundle, requests_bundle):
+ path.write_text("cert data", encoding="utf-8")
+
+ monkeypatch.setenv("FLI_CA_BUNDLE", str(fli_bundle))
+ monkeypatch.setenv("CURL_CA_BUNDLE", str(curl_bundle))
+ monkeypatch.setenv("REQUESTS_CA_BUNDLE", str(requests_bundle))
+
+ assert _ca_bundle_from_env() == str(fli_bundle)
+
+ def test_curl_ca_bundle_wins_over_requests_ca_bundle(self, monkeypatch, tmp_path):
+ curl_bundle = tmp_path / "curl.pem"
+ requests_bundle = tmp_path / "requests.pem"
+ for path in (curl_bundle, requests_bundle):
+ path.write_text("cert data", encoding="utf-8")
+
+ monkeypatch.delenv("FLI_CA_BUNDLE", raising=False)
+ monkeypatch.setenv("CURL_CA_BUNDLE", str(curl_bundle))
+ monkeypatch.setenv("REQUESTS_CA_BUNDLE", str(requests_bundle))
+
+ assert _ca_bundle_from_env() == str(curl_bundle)
+
+ def test_falls_back_to_requests_ca_bundle_alone(self, monkeypatch, tmp_path):
+ requests_bundle = tmp_path / "requests.pem"
+ requests_bundle.write_text("cert data", encoding="utf-8")
+
+ monkeypatch.delenv("FLI_CA_BUNDLE", raising=False)
+ monkeypatch.delenv("CURL_CA_BUNDLE", raising=False)
+ monkeypatch.setenv("REQUESTS_CA_BUNDLE", str(requests_bundle))
+
+ assert _ca_bundle_from_env() == str(requests_bundle)
+
+ def test_empty_values_are_skipped_in_favor_of_the_next_variable(self, monkeypatch, tmp_path):
+ """An empty string (not unset) should be treated the same as unset."""
+ requests_bundle = tmp_path / "requests.pem"
+ requests_bundle.write_text("cert data", encoding="utf-8")
+
+ monkeypatch.setenv("FLI_CA_BUNDLE", "")
+ monkeypatch.setenv("CURL_CA_BUNDLE", "")
+ monkeypatch.setenv("REQUESTS_CA_BUNDLE", str(requests_bundle))
+
+ assert _ca_bundle_from_env() == str(requests_bundle)
+
+ def test_no_variables_set_returns_none(self, monkeypatch):
+ monkeypatch.delenv("FLI_CA_BUNDLE", raising=False)
+ monkeypatch.delenv("CURL_CA_BUNDLE", raising=False)
+ monkeypatch.delenv("REQUESTS_CA_BUNDLE", raising=False)
+
+ assert _ca_bundle_from_env() is None
+
+ def test_missing_path_raises_certificate_error_naming_the_variable(self, monkeypatch, tmp_path):
+ missing = tmp_path / "does-not-exist.pem"
+ monkeypatch.setenv("FLI_CA_BUNDLE", str(missing))
+ monkeypatch.delenv("CURL_CA_BUNDLE", raising=False)
+ monkeypatch.delenv("REQUESTS_CA_BUNDLE", raising=False)
+
+ with pytest.raises(SearchCertificateError) as exc_info:
+ _ca_bundle_from_env()
+ assert "FLI_CA_BUNDLE" in str(exc_info.value)
+ assert str(missing) in str(exc_info.value)
+
+ def test_directory_path_is_not_a_readable_file(self, monkeypatch, tmp_path):
+ """A directory passes ``os.access`` but is not a bundle — ``isfile`` must reject it."""
+ directory = tmp_path / "not-a-file"
+ directory.mkdir()
+ monkeypatch.delenv("FLI_CA_BUNDLE", raising=False)
+ monkeypatch.setenv("CURL_CA_BUNDLE", str(directory))
+ monkeypatch.delenv("REQUESTS_CA_BUNDLE", raising=False)
+
+ with pytest.raises(SearchCertificateError) as exc_info:
+ _ca_bundle_from_env()
+ assert "CURL_CA_BUNDLE" in str(exc_info.value)
+
+ def test_bad_path_in_lower_priority_variable_still_raises(self, monkeypatch, tmp_path):
+ """Precedence is only for *finding* the bundle — a bad path never falls through."""
+ missing = tmp_path / "missing.pem"
+ monkeypatch.delenv("FLI_CA_BUNDLE", raising=False)
+ monkeypatch.delenv("CURL_CA_BUNDLE", raising=False)
+ monkeypatch.setenv("REQUESTS_CA_BUNDLE", str(missing))
+
+ with pytest.raises(SearchCertificateError, match="REQUESTS_CA_BUNDLE"):
+ _ca_bundle_from_env()
+
+
+# ---------------------------------------------------------------------------
+# _session(): applies the configured bundle, keeps the SOCS cookie either way
+# ---------------------------------------------------------------------------
+
+
+class TestSessionCaBundle:
+ def test_session_uses_configured_ca_bundle(self, monkeypatch, tmp_path):
+ ca_bundle = tmp_path / "custom-ca.pem"
+ ca_bundle.write_text("cert data", encoding="utf-8")
+
+ monkeypatch.setenv("FLI_CA_BUNDLE", str(ca_bundle))
+ monkeypatch.delenv("CURL_CA_BUNDLE", raising=False)
+ monkeypatch.delenv("REQUESTS_CA_BUNDLE", raising=False)
+
+ # A fresh Client — _session() is cached per-thread, so an existing
+ # instance would silently reuse a session built before the env was
+ # patched.
+ client = Client()
+ session = client._session()
+
+ assert session.verify == str(ca_bundle)
+
+ def test_session_leaves_default_verify_when_unconfigured(self, monkeypatch):
+ monkeypatch.delenv("FLI_CA_BUNDLE", raising=False)
+ monkeypatch.delenv("CURL_CA_BUNDLE", raising=False)
+ monkeypatch.delenv("REQUESTS_CA_BUNDLE", raising=False)
+
+ client = Client()
+ session = client._session()
+
+ assert session.verify is True
+
+ def test_socs_cookie_still_set_when_ca_bundle_configured(self, monkeypatch, tmp_path):
+ ca_bundle = tmp_path / "custom-ca.pem"
+ ca_bundle.write_text("cert data", encoding="utf-8")
+ monkeypatch.setenv("FLI_CA_BUNDLE", str(ca_bundle))
+ monkeypatch.setattr(client_module, "SOCS_COOKIE", "TESTSOCS")
+
+ client = Client()
+ session = client._session()
+
+ assert session.cookies.get("SOCS", domain=".google.com") == "TESTSOCS"
+
+ def test_socs_cookie_still_set_when_ca_bundle_unconfigured(self, monkeypatch):
+ monkeypatch.setattr(client_module, "SOCS_COOKIE", "TESTSOCS")
+
+ client = Client()
+ session = client._session()
+
+ assert session.cookies.get("SOCS", domain=".google.com") == "TESTSOCS"
+
+ def test_bad_ca_bundle_raises_on_first_session_access(self, monkeypatch, tmp_path):
+ missing = tmp_path / "missing-ca.pem"
+ monkeypatch.setenv("FLI_CA_BUNDLE", str(missing))
+
+ client = Client()
+
+ with pytest.raises(SearchCertificateError, match="FLI_CA_BUNDLE"):
+ client._session()
+
+
+# ---------------------------------------------------------------------------
+# _wrap_request_error: certificate mapping, checked before the generic
+# connection/SSL mapping, without disturbing the existing mappings.
+# ---------------------------------------------------------------------------
+
+
+class TestWrapRequestErrorCertificate:
+ def test_certificate_verify_error_maps_to_search_certificate_error(self):
+ exc = curl_exc.CertificateVerifyError("unable to get local issuer certificate", 60, None)
+
+ wrapped = _wrap_request_error("GET", "https://www.google.com/travel/flights", exc)
+
+ assert isinstance(wrapped, SearchCertificateError)
+ assert "TLS certificate verification failed" in str(wrapped)
+ assert "FLI_CA_BUNDLE" in str(wrapped)
+ assert "CURL_CA_BUNDLE" in str(wrapped)
+ assert "REQUESTS_CA_BUNDLE" in str(wrapped)
+
+ def test_certificate_verify_error_is_not_reported_as_plain_connection_error(self):
+ """A cert failure is a SSLError/ConnectionError subclass — order matters.
+
+ Without checking CertificateVerifyError first, the generic
+ ``isinstance(exc, curl_exc.ConnectionError)`` branch below would
+ catch it and report a vague "check your connection" message instead
+ of naming the fix.
+ """
+ exc = curl_exc.CertificateVerifyError("self signed certificate", 60, None)
+
+ wrapped = _wrap_request_error("GET", "https://www.google.com/", exc)
+
+ assert type(wrapped) is SearchCertificateError
+ assert type(wrapped) is not SearchConnectionError
+
+ def test_code_60_on_a_bare_connection_error_also_maps_to_certificate_error(self):
+ """Forward-compat: if a future curl_cffi ever raises the base class directly.
+
+ In the installed curl_cffi (0.15.0), ``code2error`` deterministically
+ maps ``CurlECode.PEER_FAILED_VERIFICATION`` (60) to
+ ``CertificateVerifyError`` specifically — this exact shape is not
+ reachable through today's request path. It mirrors the
+ ``getattr(curl_exc, "CertificateVerifyError", ())`` forward-compat
+ guard already used below: cheap insurance against a future release
+ raising the plain base class with the same code instead.
+ """
+ exc = curl_exc.ConnectionError("SSL peer certificate could not be verified", 60, None)
+
+ wrapped = _wrap_request_error("GET", "https://www.google.com/", exc)
+
+ assert isinstance(wrapped, SearchCertificateError)
+
+ def test_timeout_still_maps_to_search_timeout_error(self):
+ exc = curl_exc.Timeout("curl: (28) timed out", 28, None)
+ wrapped = _wrap_request_error("GET", "https://www.google.com/", exc)
+ from fli.search.exceptions import SearchTimeoutError
+
+ assert isinstance(wrapped, SearchTimeoutError)
+
+ def test_plain_connection_error_still_maps_to_search_connection_error(self):
+ exc = curl_exc.ConnectionError("dns lookup failed", 6, None)
+ wrapped = _wrap_request_error("GET", "https://www.google.com/", exc)
+
+ assert isinstance(wrapped, SearchConnectionError)
+ assert not isinstance(wrapped, SearchCertificateError)
+
+ def test_http_error_still_maps_to_search_http_error(self):
+ from unittest.mock import MagicMock
+
+ from fli.search.exceptions import SearchHTTPError
+
+ mock_response = MagicMock()
+ mock_response.status_code = 403
+ exc = curl_exc.HTTPError("403 Forbidden", 403, mock_response)
+ exc.response = mock_response
+
+ wrapped = _wrap_request_error("POST", "https://www.google.com/", exc)
+
+ assert isinstance(wrapped, SearchHTTPError)
+ assert wrapped.status_code == 403
+
+
+# ---------------------------------------------------------------------------
+# No retry for deterministic certificate failures.
+# ---------------------------------------------------------------------------
+
+
+class TestCertificateErrorIsNotRetried:
+ """A bad CA path or an untrusted certificate never fixes itself on retry.
+
+ ``Client.get``/``post`` retry everything by default (3 attempts,
+ exponential backoff) — that is right for a transient connection blip but
+ wastes the user's time (and the retry backoff) on a deterministic TLS
+ failure before they ever see the actionable message. ``wait`` is patched
+ to zero so a retried test does not actually sleep through the backoff.
+ """
+
+ @pytest.fixture(autouse=True)
+ def _no_sleep(self, monkeypatch):
+ """Replace both methods' backoff with an instant wait for this class."""
+ from tenacity import wait_none
+
+ monkeypatch.setattr(Client.get.retry, "wait", wait_none())
+ monkeypatch.setattr(Client.post.retry, "wait", wait_none())
+
+ def test_certificate_error_is_attempted_exactly_once(self, monkeypatch):
+ client = Client()
+ monkeypatch.setattr(client._rate_limiter, "acquire", lambda: None)
+
+ calls = {"count": 0}
+
+ class _FakeSession:
+ def get(self, url, **kwargs):
+ calls["count"] += 1
+ raise curl_exc.CertificateVerifyError("bad cert", 60, None)
+
+ monkeypatch.setattr(client, "_session", lambda: _FakeSession())
+
+ with pytest.raises(SearchCertificateError):
+ client.get("https://www.google.com/travel/flights")
+
+ assert calls["count"] == 1
+
+ def test_plain_connection_error_is_still_retried_three_times(self, monkeypatch):
+ client = Client()
+ monkeypatch.setattr(client._rate_limiter, "acquire", lambda: None)
+
+ calls = {"count": 0}
+
+ class _FakeSession:
+ def get(self, url, **kwargs):
+ calls["count"] += 1
+ raise curl_exc.ConnectionError("dns lookup failed", 6, None)
+
+ monkeypatch.setattr(client, "_session", lambda: _FakeSession())
+
+ with pytest.raises(SearchConnectionError):
+ client.get("https://www.google.com/travel/flights")
+
+ assert calls["count"] == 3
+
+ def test_bad_ca_bundle_path_raised_from_session_creation_is_attempted_once_on_get(
+ self, monkeypatch
+ ):
+ """Fix round 1 (M1): the *session-creation* shape, not just the request shape.
+
+ The other tests in this class fake ``_session()`` to return a stub
+ whose ``.get``/``.post`` raises a curl-level error — that covers a
+ certificate rejected *during the request*. A bad ``FLI_CA_BUNDLE``
+ path instead makes ``_ca_bundle_from_env()`` raise
+ ``SearchCertificateError`` directly *inside* ``_session()``, before
+ any request is even attempted (see ``Client._session``). Nothing
+ upstream of ``_wrap_request_error``'s
+ ``isinstance(exc, SearchClientError): return exc`` short-circuit
+ cares which of the two raised it, but a regression that moved
+ ``_ca_bundle_from_env()``'s call site outside ``get``/``post``'s
+ ``try`` block (or outside ``_session()`` entirely) would not be
+ caught by the other tests in this class, since they never make
+ ``_session()`` itself raise.
+ """
+ client = Client()
+ monkeypatch.setattr(client._rate_limiter, "acquire", lambda: None)
+
+ calls = {"count": 0}
+
+ def _raise_bad_bundle():
+ calls["count"] += 1
+ raise SearchCertificateError(
+ "FLI_CA_BUNDLE points to a CA bundle path that does not exist "
+ "or is not readable: '/nonexistent/bad-bundle.pem'"
+ )
+
+ monkeypatch.setattr(client, "_session", _raise_bad_bundle)
+
+ with pytest.raises(SearchCertificateError):
+ client.get("https://www.google.com/travel/flights")
+
+ assert calls["count"] == 1
+
+ def test_bad_ca_bundle_path_raised_from_session_creation_is_attempted_once_on_post(
+ self, monkeypatch
+ ):
+ client = Client()
+ monkeypatch.setattr(client._rate_limiter, "acquire", lambda: None)
+
+ calls = {"count": 0}
+
+ def _raise_bad_bundle():
+ calls["count"] += 1
+ raise SearchCertificateError(
+ "FLI_CA_BUNDLE points to a CA bundle path that does not exist "
+ "or is not readable: '/nonexistent/bad-bundle.pem'"
+ )
+
+ monkeypatch.setattr(client, "_session", _raise_bad_bundle)
+
+ with pytest.raises(SearchCertificateError):
+ client.post("https://www.google.com/travel/flights")
+
+ assert calls["count"] == 1
+
+ def test_certificate_error_from_post_is_also_attempted_exactly_once(self, monkeypatch):
+ client = Client()
+ monkeypatch.setattr(client._rate_limiter, "acquire", lambda: None)
+
+ calls = {"count": 0}
+
+ class _FakeSession:
+ def post(self, url, **kwargs):
+ calls["count"] += 1
+ raise curl_exc.CertificateVerifyError("bad cert", 60, None)
+
+ monkeypatch.setattr(client, "_session", lambda: _FakeSession())
+
+ with pytest.raises(SearchCertificateError):
+ client.post("https://www.google.com/travel/flights")
+
+ assert calls["count"] == 1