Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
py 312 lines 10.5 KB
Raw
1 """
2 Toolkit version deprecation warnings.
3
4 When a request resolves to a deprecated toolkit version, the API adds a
5 ``Composio-Deprecated-Toolkits`` response header (an RFC 9651 structured-field
6 list). This module parses that header from an ``httpx`` response event hook
7 installed below the generated client, and warns once per process for each
8 deprecated toolkit version it sees. The response body is never read.
9
10 Example header::
11
12 "GMAIL";version="20250114_00";deprecated=@1779840000;sunset=@1787788800;reason="lifecycle"
13
14 Kept intentionally equivalent to the TypeScript SDK's
15 ``ts/packages/core/src/utils/toolkitDeprecation.ts``.
16 """
17
18 from __future__ import annotations
19
20 import logging
21 import re
22 import threading
23 import typing as t
24 import warnings
25 from dataclasses import dataclass
26 from datetime import datetime, timezone
27
28 import httpx
29
30 from composio.exceptions import ComposioDeprecationWarning
31 from composio.utils.toolkit_version import normalize_toolkit_slug
32
33 #: Response header name. ``httpx.Headers`` lookups are case-insensitive.
34 HEADER = "composio-deprecated-toolkits"
35
36 #: Anchor of the docs section every warning points at.
37 DOCS_URL = "https://docs.composio.dev/docs/tools-direct/toolkit-versioning#deprecation-and-sunset"
38
39 #: Versions named per toolkit before the formatter collapses the rest into "and N more".
40 _MAX_VERSIONS_PER_LINE = 5
41
42 #: The three limits below mirror the ``composio_client._deprecation`` module,
43 #: which reads the same kind of server-controlled header.
44 #: A header longer than this is ignored whole rather than parsed.
45 _MAX_HEADER_LENGTH = 2048
46 #: A header holding any of these is ignored whole, so nothing partially cleaned reaches the log.
47 _CONTROL_CHARACTERS = re.compile(r"[\x00-\x1f\x7f]")
48 #: Keys the process will ever record; past this, new versions are neither recorded nor warned about.
49 _MAX_TRACKED_VERSIONS = 1024
50
51 _logger = logging.getLogger(__name__)
52
53 _SF_STRING = re.compile(r'^"((?:[^"\\]|\\.)*)"$')
54 _SF_DATE = re.compile(r"^@(-?\d{1,15})$")
55 _SF_ESCAPE = re.compile(r"\\(.)")
56
57
58 @dataclass(frozen=True)
59 class DeprecatedToolkit:
60 """One item of the ``Composio-Deprecated-Toolkits`` header."""
61
62 slug: str
63 version: str
64 deprecated_at: t.Optional[datetime] = None
65 sunset_at: t.Optional[datetime] = None
66 reason: t.Optional[str] = None
67
68 @property
69 def key(self) -> str:
70 """Once-per-process dedupe key, ``UPPER(slug)@version``."""
71 return f"{self.slug.upper()}@{self.version}"
72
73
74 _warned: set[str] = set()
75 _lock = threading.Lock()
76
77
78 def _split_outside_quotes(value: str, delimiter: str) -> list[str]:
79 """Split ``value`` on ``delimiter`` outside double-quoted strings.
80
81 Backslash escapes inside the quotes are honoured. Empty pieces are dropped
82 and the rest are stripped of surrounding whitespace.
83 """
84 pieces: list[str] = []
85 current: list[str] = []
86 in_string = False
87 index = 0
88 while index < len(value):
89 char = value[index]
90 if in_string:
91 current.append(char)
92 if char == "\\" and index + 1 < len(value):
93 index += 1
94 current.append(value[index])
95 elif char == '"':
96 in_string = False
97 elif char == '"':
98 in_string = True
99 current.append(char)
100 elif char == delimiter:
101 pieces.append("".join(current))
102 current = []
103 else:
104 current.append(char)
105 index += 1
106 pieces.append("".join(current))
107 return [piece.strip() for piece in pieces if piece.strip()]
108
109
110 def _decode_sf_string(raw: str) -> t.Optional[str]:
111 """Decode an sf-string; ``None`` unless it is complete and validly escaped."""
112 match = _SF_STRING.match(raw)
113 if match is None:
114 return None
115 invalid = False
116
117 def _unescape(escape: re.Match[str]) -> str:
118 nonlocal invalid
119 char = escape.group(1)
120 if char in ('"', "\\"):
121 return char
122 invalid = True
123 return ""
124
125 decoded = _SF_ESCAPE.sub(_unescape, match.group(1))
126 return None if invalid else decoded
127
128
129 def _decode_sf_date(raw: str) -> t.Optional[datetime]:
130 """Decode an sf-date (``@`` plus Unix seconds) into an aware UTC datetime."""
131 match = _SF_DATE.match(raw)
132 if match is None:
133 return None
134 try:
135 return datetime.fromtimestamp(int(match.group(1)), tz=timezone.utc)
136 except (OverflowError, OSError, ValueError):
137 return None
138
139
140 def _parse_item(item: str) -> t.Optional[DeprecatedToolkit]:
141 """Parse one list item; ``None`` when the slug or a known parameter is invalid."""
142 pieces = _split_outside_quotes(item, ";")
143 if not pieces:
144 return None
145 head, *params = pieces
146 slug = _decode_sf_string(head)
147 if not slug:
148 return None
149 version: t.Optional[str] = None
150 deprecated_at: t.Optional[datetime] = None
151 sunset_at: t.Optional[datetime] = None
152 reason: t.Optional[str] = None
153 for param in params:
154 key, separator, raw_value = param.partition("=")
155 if not separator:
156 continue
157 key = key.strip()
158 raw_value = raw_value.strip()
159 if key == "version":
160 version = _decode_sf_string(raw_value)
161 if not version:
162 return None
163 elif key == "reason":
164 reason = _decode_sf_string(raw_value)
165 if not reason:
166 return None
167 elif key == "deprecated":
168 deprecated_at = _decode_sf_date(raw_value)
169 if deprecated_at is None:
170 return None
171 elif key == "sunset":
172 sunset_at = _decode_sf_date(raw_value)
173 if sunset_at is None:
174 return None
175 # Unknown parameters are ignored.
176 if version is None:
177 return None
178 return DeprecatedToolkit(
179 slug=slug,
180 version=version,
181 deprecated_at=deprecated_at,
182 sunset_at=sunset_at,
183 reason=reason,
184 )
185
186
187 def parse_deprecated_toolkits_header(value: str) -> list[DeprecatedToolkit]:
188 """Parse a ``Composio-Deprecated-Toolkits`` header value.
189
190 Items that fail to parse are dropped silently; garbage input yields an
191 empty list. Never raises.
192 """
193 try:
194 entries: list[DeprecatedToolkit] = []
195 for item in _split_outside_quotes(value, ","):
196 entry = _parse_item(item)
197 if entry is not None:
198 entries.append(entry)
199 return entries
200 except Exception: # pragma: no cover - defensive, the parser is total
201 return []
202
203
204 def _iso_date(value: datetime) -> str:
205 return value.astimezone(timezone.utc).date().isoformat()
206
207
208 def _pin_hint(slug: str, docs_url: str) -> str:
209 config_key = normalize_toolkit_slug(slug)
210 env_var = f"COMPOSIO_TOOLKIT_VERSION_{slug.upper()}"
211 return (
212 f'Pin a newer version with toolkit_versions={{"{config_key}": "<version>"}} '
213 f"or {env_var}. See {docs_url}."
214 )
215
216
217 def _format_single(entry: DeprecatedToolkit, docs_url: str) -> str:
218 sentence = (
219 f"[Deprecation] Toolkit {entry.slug.upper()} version {entry.version} "
220 "was deprecated"
221 )
222 if entry.deprecated_at is not None:
223 sentence += f" on {_iso_date(entry.deprecated_at)}"
224 if entry.reason is not None:
225 sentence += f" ({entry.reason})"
226 if entry.sunset_at is not None:
227 sentence += f" and will stop working on {_iso_date(entry.sunset_at)}"
228 return f"{sentence}. {_pin_hint(entry.slug, docs_url)}"
229
230
231 def _format_group(
232 slug: str, entries: t.Sequence[DeprecatedToolkit], docs_url: str
233 ) -> str:
234 versions = [entry.version for entry in entries]
235 named = ", ".join(versions[:_MAX_VERSIONS_PER_LINE])
236 remaining = len(versions) - _MAX_VERSIONS_PER_LINE
237 listed = f"{named} and {remaining} more" if remaining > 0 else named
238 sentence = f"[Deprecation] Toolkit {slug} versions {listed} are deprecated"
239 sunsets = sorted(
240 entry.sunset_at for entry in entries if entry.sunset_at is not None
241 )
242 if sunsets:
243 sentence += f" and the earliest will stop working on {_iso_date(sunsets[0])}"
244 return f"{sentence}. {_pin_hint(slug, docs_url)}"
245
246
247 def format_warnings(
248 entries: t.Sequence[DeprecatedToolkit], docs_url: str = DOCS_URL
249 ) -> list[str]:
250 """Render one warning line per toolkit slug.
251
252 A slug with a single deprecated version gets the full sentence with its
253 dates and reason; a slug with several names at most five versions and
254 collapses the rest into "and N more".
255 """
256 groups: dict[str, list[DeprecatedToolkit]] = {}
257 for entry in entries:
258 groups.setdefault(entry.slug.upper(), []).append(entry)
259 return [
260 _format_single(group[0], docs_url)
261 if len(group) == 1
262 else _format_group(slug, group, docs_url)
263 for slug, group in groups.items()
264 ]
265
266
267 def warn_deprecated_toolkits(headers: httpx.Headers, docs_url: str = DOCS_URL) -> None:
268 """Warn once per process for each deprecated toolkit version in ``headers``."""
269 value = headers.get(HEADER)
270 if not value:
271 return
272 if len(value) > _MAX_HEADER_LENGTH or _CONTROL_CHARACTERS.search(value):
273 return
274 entries = parse_deprecated_toolkits_header(value)
275 fresh: list[DeprecatedToolkit] = []
276 with _lock:
277 for entry in entries:
278 if entry.key in _warned or len(_warned) >= _MAX_TRACKED_VERSIONS:
279 continue
280 _warned.add(entry.key)
281 fresh.append(entry)
282 for line in format_warnings(fresh, docs_url):
283 warnings.warn(line, ComposioDeprecationWarning, stacklevel=2)
284
285
286 def response_hook(response: httpx.Response) -> None:
287 """``httpx`` response event hook. Never raises and never reads the body."""
288 try:
289 warn_deprecated_toolkits(response.headers)
290 except Exception: # noqa: BLE001 - a warning must never fail a call
291 _logger.debug("Failed to inspect the toolkit deprecation header", exc_info=True)
292
293
294 def install_hook(client: httpx.Client) -> None:
295 """Append :func:`response_hook` to ``client`` once, keeping existing hooks.
296
297 ``httpx.Client.event_hooks`` is a plain attribute holding the live dict in
298 the pinned httpx, so appending to its ``response`` list takes effect
299 immediately; the assignment below also covers an httpx that returns a copy.
300 """
301 hooks = client.event_hooks
302 response_hooks = list(hooks.get("response", []))
303 if any(hook is response_hook for hook in response_hooks):
304 return
305 response_hooks.append(response_hook)
306 client.event_hooks = {**hooks, "response": response_hooks}
307
308
309 def _reset_for_tests() -> None:
310 """Clear the once-per-process record. Tests only."""
311 with _lock:
312 _warned.clear()