@devries-cameron20 / composio Mirror · read-only / commits / c7ee77120
Fork 0

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

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 06:00 UTC

feat(core,python): handle rate limits in tool execution and connection polling (PLEN-4561)

Bucket enforcement makes the SDK's request patterns matter: TS tools.execute() spent one discovery request per call on a schema fetch, and waitForConnection polled every second. - TS tools.execute() reuses schemas: 5 minutes on latest, 1 hour on pinned versions, 500 entries per Tools instance. Failures aren't cached. - A 429 on a TS schema fetch or execution throws a rate-limit subclass of the existing error, with retryAfterSeconds and fixes that no longer blame the slug. isComposioRateLimitError catches both. - waitForConnection (TS, Python) backs off from 1s to 5s, keeps polling through a 429 within the timeout, and polls once more at the deadline. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

viraj committed Nov 3, 2026 at 14:34 UTC c7ee77120dc9e9e62938d46ec6cc4c2a5a3909b8
11 files changed +684 -64
.changeset/sdk-rate-limit-handling.md new
+5
@@ -0,0 +1,5 @@
1 +---
2 +'@composio/core': minor
3 +---
4 +
5 +Handle rate limits better: `tools.execute()` reuses tool schemas instead of fetching one per call, `waitForConnection()` backs off between polls and waits out a 429, and tool fetches and executions rejected with a 429 throw `ComposioToolFetchRateLimitError` or `ComposioToolExecutionRateLimitError` (check with `isComposioRateLimitError`).
docs/content/docs/tools-direct/authenticating-tools.mdx
+3 -1
@@ -559,11 +559,13 @@ done
559 </Tab>
560 </Tabs>
561
562 -The method continuously polls the Composio API until the connection:
562 +The method polls the Composio API, waiting 1 second between polls at first and up to 5 seconds later, until the connection:
563 - Becomes **ACTIVE** (returns the connected account)
564 - Enters a terminal state like **FAILED** or **EXPIRED** (throws an error)
565 - Exceeds the specified timeout (throws a timeout error)
566
567 +A rate-limited poll doesn't end the wait. The method waits as long as the response asks, within the timeout, and polls again.
568 +
569 ### Checking Connection Status
570
571 You can check the status of a connected account programmatically:
python/composio/core/models/connected_accounts.py
+54 -15
@@ -2,12 +2,14 @@ from __future__ import annotations
2
3 import functools
4 import logging
5 +import math
6 import time
7 import typing as t
8 import warnings
9 +from email.utils import parsedate_to_datetime
10
11 import typing_extensions as te
10 -from composio_client import BadRequestError, ConflictError, omit
12 +from composio_client import BadRequestError, ConflictError, RateLimitError, omit
13
14 from composio import exceptions
15 from composio.client import HttpClient
@@ -35,6 +37,11 @@ _TERMINAL_CONNECTION_STATES: t.FrozenSet[str] = frozenset(
37 {"FAILED", "EXPIRED", "REVOKED"}
38 )
39
40 +# Delay between `wait_for_connection` polls. Mirrors TS `ConnectionRequest.ts`.
41 +_INITIAL_POLL_DELAY_SECONDS = 1.0
42 +_MAX_POLL_DELAY_SECONDS = 5.0
43 +_POLL_DELAY_GROWTH = 1.5
44 +
45 # One-time-per-process guard so long-running services don't spam the deprecation
46 # warning on every initiate() call.
47 _legacy_initiate_warning_emitted = False
@@ -51,6 +58,20 @@ _REFRESH_VALIDATE_CREDENTIALS_IGNORED = (
58 )
59
60
61 +def _retry_after_seconds(error: RateLimitError) -> float:
62 + """Seconds a 429 asks the caller to wait, from its ``Retry-After`` header (seconds or an HTTP date); 0 if unusable."""
63 + value = error.response.headers.get("retry-after", "").strip()
64 + try:
65 + seconds = float(value)
66 + except ValueError:
67 + try:
68 + seconds = parsedate_to_datetime(value).timestamp() - time.time()
69 + except (TypeError, ValueError):
70 + return 0.0
71 + # `float()` also accepts "nan" and "inf", which aren't waits.
72 + return max(0.0, seconds) if math.isfinite(seconds) else 0.0
73 +
74 +
75 class ConnectionRequest(Resource):
76 """
77 A connection request.
@@ -87,28 +108,46 @@ class ConnectionRequest(Resource):
108 """
109 Wait for the connection to be established.
110
111 + The delay between polls grows from 1 second to 5 seconds, so a connection
112 + can be up to 5 seconds old when this returns. A rate-limited poll doesn't
113 + fail the wait: it waits as long as the response asks, within the timeout,
114 + and polls again.
115 +
116 :param timeout: The timeout to wait for the connection to be established.
117 :return: Connected account object.
118 """
119 timeout = self.DEFAULT_WAIT_TIMEOUT if timeout is None else timeout
120 deadline = time.time() + timeout
95 - while deadline > time.time():
96 - connection = self._client.connected_accounts.retrieve(nanoid=self.id)
97 - self.status = connection.status
98 - if self.status == "ACTIVE":
99 - return connection
100 - if self.status in _TERMINAL_CONNECTION_STATES:
101 - raise exceptions.SDKError(
121 + poll_delay = _INITIAL_POLL_DELAY_SECONDS
122 + while True:
123 + delay = poll_delay
124 + try:
125 + connection = self._client.connected_accounts.retrieve(nanoid=self.id)
126 + except RateLimitError as error:
127 + delay = max(delay, _retry_after_seconds(error))
128 + else:
129 + self.status = connection.status
130 + if self.status == "ACTIVE":
131 + return connection
132 + if self.status in _TERMINAL_CONNECTION_STATES:
133 + raise exceptions.SDKError(
134 + message=(
135 + f"Connection {self.id} entered terminal state "
136 + f"{self.status!r} before becoming active"
137 + ),
138 + )
139 +
140 + remaining = deadline - time.time()
141 + if remaining <= 0:
142 + raise exceptions.ComposioSDKTimeoutError(
143 message=(
103 - f"Connection {self.id} entered terminal state "
104 - f"{self.status!r} before becoming active"
144 + f"Timeout while waiting for connection {self.id} to be active"
145 ),
146 )
107 - time.sleep(1)
108 -
109 - raise exceptions.ComposioSDKTimeoutError(
110 - message=f"Timeout while waiting for connection {self.id} to be active",
111 - )
147 + # Stop at the deadline rather than past it, so the last poll happens
148 + # as the time runs out.
149 + time.sleep(min(delay, remaining))
150 + poll_delay = min(poll_delay * _POLL_DELAY_GROWTH, _MAX_POLL_DELAY_SECONDS)
151
152 @classmethod
153 def from_id(cls, id: str, client: HttpClient) -> te.Self:
python/tests/test_connected_accounts.py
+107 -1
@@ -4,8 +4,9 @@ import typing as t
4 import warnings
5 from unittest.mock import Mock, patch
6
7 +import httpx
8 import pytest
8 -from composio_client import BadRequestError, ConflictError, omit
9 +from composio_client import BadRequestError, ConflictError, RateLimitError, omit
10
11 from composio import exceptions
12 from composio.core.models.connected_accounts import (
@@ -127,6 +128,111 @@ class TestAuthScheme:
128 assert state["val"]["status"] == expected_status
129
130
131 +class TestConnectionRequestPolling:
132 + """Backoff and 429 handling, on a fake clock that only ``sleep`` moves."""
133 +
134 + @staticmethod
135 + def _clock(monkeypatch):
136 + clock = {"now": 0.0}
137 + monkeypatch.setattr(time, "time", lambda: clock["now"])
138 + monkeypatch.setattr(
139 + time, "sleep", lambda s: clock.__setitem__("now", clock["now"] + s)
140 + )
141 + return clock
142 +
143 + @staticmethod
144 + def _rate_limited(retry_after=None):
145 + headers = {} if retry_after is None else {"retry-after": retry_after}
146 + request = httpx.Request("GET", "https://backend.invalid")
147 + response = httpx.Response(429, headers=headers, request=request)
148 + return RateLimitError("slow down", response=response, body=None)
149 +
150 + @staticmethod
151 + def _request(client):
152 + return ConnectionRequest(
153 + id="conn-1", status="PENDING", redirect_url=None, client=client
154 + )
155 +
156 + def _poll_times(self, monkeypatch, timeout):
157 + clock = self._clock(monkeypatch)
158 + times = []
159 + pending = Mock(status="PENDING")
160 +
161 + def retrieve(nanoid):
162 + times.append(clock["now"])
163 + return pending
164 +
165 + client = Mock()
166 + client.connected_accounts.retrieve.side_effect = retrieve
167 + with pytest.raises(exceptions.ComposioSDKTimeoutError):
168 + self._request(client).wait_for_connection(timeout=timeout)
169 + return times
170 +
171 + def test_backs_off_from_1s_to_a_5s_cap(self, monkeypatch):
172 + times = self._poll_times(monkeypatch, 30.0)
173 + assert times[:7] == [0.0, 1.0, 2.5, 4.75, 8.125, 13.125, 18.125]
174 +
175 + def test_sends_about_16_requests_in_the_default_wait(self, monkeypatch):
176 + assert len(self._poll_times(monkeypatch, 60.0)) == 16
177 +
178 + def test_polls_one_last_time_at_the_deadline(self, monkeypatch):
179 + assert self._poll_times(monkeypatch, 3.0) == [0.0, 1.0, 2.5, 3.0]
180 +
181 + def test_waits_as_long_as_a_429_asks_then_keeps_polling(self, monkeypatch):
182 + clock = self._clock(monkeypatch)
183 + active = Mock(status="ACTIVE")
184 + client = Mock()
185 + client.connected_accounts.retrieve.side_effect = [
186 + self._rate_limited("10"),
187 + active,
188 + ]
189 +
190 + assert self._request(client).wait_for_connection(timeout=60.0) is active
191 + assert clock["now"] == 10.0
192 +
193 + def test_never_waits_past_the_timeout_for_a_429(self, monkeypatch):
194 + clock = self._clock(monkeypatch)
195 + client = Mock()
196 + client.connected_accounts.retrieve.side_effect = self._rate_limited("60")
197 +
198 + with pytest.raises(exceptions.ComposioSDKTimeoutError):
199 + self._request(client).wait_for_connection(timeout=5.0)
200 +
201 + assert clock["now"] == 5.0
202 + assert client.connected_accounts.retrieve.call_count == 2
203 +
204 + def test_reads_a_date_format_retry_after(self, monkeypatch):
205 + clock = self._clock(monkeypatch)
206 + # 1,000,000 seconds after the epoch, which is where the clock starts here.
207 + clock["now"] = 1_000_000.0
208 + client = Mock()
209 + client.connected_accounts.retrieve.side_effect = [
210 + self._rate_limited("Mon, 12 Jan 1970 13:47:00 GMT"),
211 + Mock(status="ACTIVE"),
212 + ]
213 +
214 + self._request(client).wait_for_connection(timeout=60.0)
215 +
216 + assert clock["now"] == 1_000_020.0
217 +
218 + @pytest.mark.parametrize(
219 + "retry_after", [None, "soon", "nan", "inf", "Thu, 01 Jan 1970 00:00:00 GMT"]
220 + )
221 + def test_keeps_its_usual_delay_without_a_usable_retry_after(
222 + self, monkeypatch, retry_after
223 + ):
224 + clock = self._clock(monkeypatch)
225 + client = Mock()
226 + client.connected_accounts.retrieve.side_effect = [
227 + self._rate_limited(retry_after),
228 + Mock(status="ACTIVE"),
229 + ]
230 +
231 + self._request(client).wait_for_connection(timeout=60.0)
232 +
233 + assert clock["now"] == 1.0
234 +
235 +
236 class TestConnectionRequest:
237 def test_wait_for_connection_returns_when_active(self, monkeypatch):
238 mock_client = Mock()
ts/packages/core/src/errors/ToolErrors.ts
+72 -1
@@ -1,6 +1,7 @@
1 import { APIError } from '@composio/client';
2 import { ComposioError, ComposioErrorOptions } from './ComposioError';
3 import { ComposioConnectedAccountNotFoundError } from './ConnectedAccountsErrors';
4 +import { getRetryAfterSeconds, isRateLimitResponse } from '../utils/rateLimit';
5
6 export const ToolErrorCodes = {
7 TOOLSET_NOT_DEFINED: 'TOOLSET_NOT_DEFINED',
@@ -54,7 +55,7 @@ export class ComposioToolNotFoundError extends ComposioError {
55 export class ComposioToolFetchError extends ComposioError {
56 constructor(
57 message: string = 'Failed to fetch tool',
57 - options: Omit<ComposioErrorOptions, 'code' | 'statusCode'> = {}
58 + options: Omit<ComposioErrorOptions, 'code'> = {}
59 ) {
60 super(message, {
61 ...options,
@@ -69,6 +70,40 @@ export class ComposioToolFetchError extends ComposioError {
70 }
71 }
72
73 +const RATE_LIMIT_FIXES = [
74 + 'Wait for the time given in retryAfterSeconds, then retry',
75 + 'Reduce how many requests this project sends per minute',
76 +];
77 +
78 +/** Error options for a 429. Leaves out an unknown wait, as `ComposioError` does for unset fields. */
79 +const rateLimitOptions = (cause: APIError, meta: Record<string, unknown>) => {
80 + const retryAfterSeconds = getRetryAfterSeconds(cause);
81 + return {
82 + cause,
83 + statusCode: 429,
84 + meta: retryAfterSeconds === undefined ? meta : { ...meta, retryAfterSeconds },
85 + possibleFixes: RATE_LIMIT_FIXES,
86 + };
87 +};
88 +
89 +/**
90 + * A tool schema fetch rejected with a 429. It is a `ComposioToolFetchError`, so existing handlers
91 + * still catch it. Use `isComposioRateLimitError` to catch rate limits from fetching and executing.
92 + */
93 +export class ComposioToolFetchRateLimitError extends ComposioToolFetchError {
94 + /** How long the API asked to wait, when the response said. */
95 + declare public readonly retryAfterSeconds?: number;
96 +
97 + constructor(message: string, cause: APIError, meta: Record<string, unknown> = {}) {
98 + const options = rateLimitOptions(cause, meta);
99 + super(message, options);
100 + if ('retryAfterSeconds' in options.meta) {
101 + this.retryAfterSeconds = getRetryAfterSeconds(cause);
102 + }
103 + this.name = 'ComposioToolFetchRateLimitError';
104 + }
105 +}
106 +
107 export class ComposioInvalidModifierError extends ComposioError {
108 constructor(
109 message: string = 'Invalid modifier',
@@ -101,6 +136,34 @@ export class ComposioToolExecutionError extends ComposioError {
136 }
137 }
138
139 +/**
140 + * A tool execution rejected with a 429. It is a `ComposioToolExecutionError`, so existing handlers
141 + * still catch it. Use `isComposioRateLimitError` to catch rate limits from fetching and executing.
142 + */
143 +export class ComposioToolExecutionRateLimitError extends ComposioToolExecutionError {
144 + /** How long the API asked to wait, when the response said. */
145 + declare public readonly retryAfterSeconds?: number;
146 +
147 + constructor(message: string, cause: APIError, meta: Record<string, unknown> = {}) {
148 + const options = rateLimitOptions(cause, meta);
149 + super(message, options);
150 + if ('retryAfterSeconds' in options.meta) {
151 + this.retryAfterSeconds = getRetryAfterSeconds(cause);
152 + }
153 + this.name = 'ComposioToolExecutionRateLimitError';
154 + }
155 +}
156 +
157 +/** Whether an error from fetching or executing a tool is the API rejecting the request with a 429. */
158 +export function isComposioRateLimitError(
159 + error: unknown
160 +): error is ComposioToolFetchRateLimitError | ComposioToolExecutionRateLimitError {
161 + return (
162 + error instanceof ComposioToolFetchRateLimitError ||
163 + error instanceof ComposioToolExecutionRateLimitError
164 + );
165 +}
166 +
167 export class ComposioInvalidToolArgumentsError extends ComposioError {
168 constructor(
169 message: string = 'Invalid tool arguments',
@@ -259,6 +322,14 @@ export const handleToolExecutionError = (tool: string, actualError: Error): Comp
322 }
323 }
324
325 + if (isRateLimitResponse(actualError)) {
326 + return new ComposioToolExecutionRateLimitError(
327 + `Rate limited while executing the tool ${tool}`,
328 + actualError,
329 + { slug: tool }
330 + );
331 + }
332 +
333 // Default error for all other cases
334 return new ComposioToolExecutionError(`Error executing the tool ${tool}`, {
335 cause: actualError,
ts/packages/core/src/models/ConnectedAccounts.ts
+2 -2
@@ -456,8 +456,8 @@ export class ConnectedAccounts {
456 /**
457 * Waits for a connection request to complete and become active.
458 *
459 - * This method continuously polls the Composio API to check the status of a connection
460 - * until it either becomes active, enters a terminal error state, or times out.
459 + * This method polls the Composio API, backing off from 1 second to 5 seconds between polls,
460 + * to check the status of a connection until it either becomes active, enters a terminal error state, or times out.
461 *
462 * @param {string} connectedAccountId - The ID of the connected account to wait for
463 * @param {number} [timeout=60000] - Maximum time to wait in milliseconds (default: 60 seconds)
ts/packages/core/src/models/ConnectionRequest.ts
+36 -34
@@ -19,6 +19,11 @@ import { ComposioConnectedAccountNotFoundError } from '../errors/ConnectedAccoun
19 import { telemetry } from '../telemetry/Telemetry';
20 import { transformConnectedAccountResponse } from '../utils/transformers/connectedAccounts';
21 import { ConnectionRequest, ConnectionRequestState } from '../types/connectionRequest.types';
22 +import { getRetryAfterSeconds, isRateLimitResponse } from '../utils/rateLimit';
23 +
24 +const INITIAL_POLL_DELAY_MS = 1000;
25 +const MAX_POLL_DELAY_MS = 5000;
26 +const POLL_DELAY_GROWTH = 1.5;
27
28 /**
29 * Creates a connection request object with methods to manage the connection lifecycle.
@@ -55,8 +60,11 @@ export function createConnectionRequest(
60 /**
61 * Waits for the connection request to complete and become active.
62 *
58 - * This method continuously polls the Composio API to check the status of the connection request
59 - * until it either becomes active, enters a terminal error state, or times out.
63 + * This method polls the Composio API to check the status of the connection request until it
64 + * either becomes active, enters a terminal error state, or times out. The delay between polls
65 + * grows from 1 second to 5 seconds, so a connection can be up to 5 seconds old when this returns.
66 + * A rate-limited poll doesn't fail the wait: it waits as long as the response asks, within the
67 + * timeout, and polls again.
68 *
69 * @param {number} [timeout=60000] - Maximum time to wait in milliseconds before timing out (default: 60 seconds)
70 * @returns {Promise<ConnectedAccountRetrieveResponse>} The final connected account response when successful
@@ -104,49 +112,43 @@ export function createConnectionRequest(
112 }
113 };
114
107 - try {
108 - const response = await client.connectedAccounts.retrieve(request.id);
109 - request.status = response.status;
110 - if (response.status === ConnectedAccountStatuses.ACTIVE) {
111 - return transformConnectedAccountResponse(response);
112 - }
113 - failIfTerminal(response);
114 - } catch (error) {
115 - if (error instanceof ComposioClient.NotFoundError) {
116 - throw new ComposioConnectedAccountNotFoundError(
117 - `Connected account with id ${request.id} not found`,
118 - {
119 - meta: {
120 - connectedAccountId: request.id,
121 - },
122 - }
123 - );
124 - } else {
125 - throw error;
126 - }
127 - }
115 + const deadline = Date.now() + timeout;
116 + let pollDelay = INITIAL_POLL_DELAY_MS;
117
129 - const start = Date.now();
130 - const pollInterval = 1000;
131 -
132 - while (Date.now() - start < timeout) {
118 + while (true) {
119 + let delay = pollDelay;
120 try {
121 const response = await client.connectedAccounts.retrieve(request.id);
135 -
122 request.status = response.status;
123 if (response.status === ConnectedAccountStatuses.ACTIVE) {
124 return transformConnectedAccountResponse(response);
125 }
140 -
126 failIfTerminal(response);
142 -
143 - await new Promise(resolve => setTimeout(resolve, pollInterval));
127 } catch (error) {
145 - throw error;
128 + if (error instanceof ComposioClient.NotFoundError) {
129 + throw new ComposioConnectedAccountNotFoundError(
130 + `Connected account with id ${request.id} not found`,
131 + {
132 + meta: {
133 + connectedAccountId: request.id,
134 + },
135 + }
136 + );
137 + }
138 + if (!isRateLimitResponse(error)) {
139 + throw error;
140 + }
141 + delay = Math.max(delay, (getRetryAfterSeconds(error) ?? 0) * 1000);
142 }
147 - }
143
149 - throw new ConnectionRequestTimeoutError(`Connection request timed out for ${request.id}`);
144 + const remaining = deadline - Date.now();
145 + if (remaining <= 0) {
146 + throw new ConnectionRequestTimeoutError(`Connection request timed out for ${request.id}`);
147 + }
148 + // Stop at the deadline rather than past it, so the last poll happens as the time runs out.
149 + await new Promise(resolve => setTimeout(resolve, Math.min(delay, remaining)));
150 + pollDelay = Math.min(pollDelay * POLL_DELAY_GROWTH, MAX_POLL_DELAY_MS);
151 + }
152 }
153
154 return request;
ts/packages/core/src/models/Tools.ts
+53 -7
@@ -43,6 +43,7 @@ import { ExecuteToolFn, GlobalExecuteToolFn } from '../types/provider.types';
43 import {
44 ComposioInvalidModifierError,
45 ComposioToolFetchError,
46 + ComposioToolFetchRateLimitError,
47 ComposioToolNotFoundError,
48 ComposioProviderNotDefinedError,
49 ComposioToolVersionRequiredError,
@@ -68,6 +69,7 @@ import {
69 transformExecuteResponse,
70 } from '../utils/transformers/toolRouterResponseTransform';
71 import { ComposioRequestCancelledError } from '../errors/SDKErrors';
72 +import { isRateLimitResponse } from '../utils/rateLimit';
73
74 const TOOL_ROUTER_SESSION_TOOLS_PAGE_LIMIT = 500;
75
@@ -98,6 +100,13 @@ function normalizeRawToolParameters(
100 return params;
101 }
102
103 +/** How long `execute()` reuses a schema fetched for `latest`, which can change at any release. */
104 +const LATEST_TOOL_SCHEMA_TTL_MS = 5 * 60 * 1000;
105 +/** How long `execute()` reuses a schema fetched for a pinned toolkit version. */
106 +const PINNED_TOOL_SCHEMA_TTL_MS = 60 * 60 * 1000;
107 +/** Most schemas `execute()` keeps per `Tools` instance; the oldest is dropped first. */
108 +const MAX_CACHED_TOOL_SCHEMAS = 500;
109 +
110 /**
111 * This class is used to manage tools in the Composio SDK.
112 * It provides methods to list, get, and execute tools.
@@ -123,6 +132,12 @@ export class Tools<
132 * Scoped per-instance so a fresh `Composio` starts with a clean slate.
133 */
134 private readonly warnedAutoUploadDisabledForTool = new Set<string>();
135 + /**
136 + * Schemas `execute()` already fetched, so repeated executions don't each spend a request.
137 + * Holds what `getRawComposioToolBySlug` returned with no `modifySchema`, so a caller's schema
138 + * modifiers never reach it.
139 + */
140 + private readonly executeToolSchemas = new Map<string, { tool: Tool; expiresAt: number }>();
141
142 constructor(client: ComposioClient, config?: ComposioConfig<TProvider>) {
143 if (!client) {
@@ -692,6 +707,13 @@ export class Tools<
707 if (error instanceof ComposioRequestCancelledError) {
708 throw error;
709 }
710 + if (isRateLimitResponse(error)) {
711 + throw new ComposioToolFetchRateLimitError(
712 + `Rate limited while retrieving tool with slug ${slug}`,
713 + error,
714 + { slug }
715 + );
716 + }
717 // The tools endpoint reports an unknown slug as 404 (or 400 for a
718 // malformed one). Anything else (401, 5xx, network) is not "not found",
719 // so keep the client error reachable as `cause` under a generic error.
@@ -1153,16 +1175,40 @@ export class Tools<
1175 const requestOptions: ComposioRequestOptions | undefined =
1176 options?.signal != null ? { signal: options.signal } : undefined;
1177
1156 - const tool = await this.getRawComposioToolBySlug(
1157 - slug,
1158 - {
1159 - version: executeParams.version,
1160 - },
1161 - requestOptions
1162 - );
1178 + const tool = await this.getToolSchemaForExecute(slug, executeParams.version, requestOptions);
1179 return this.executeWithTool(slug, executeParams, options, tool);
1180 }
1181
1182 + /** The tool's schema for `execute()`, fetched only if no unexpired copy is cached. Failures aren't cached. */
1183 + private async getToolSchemaForExecute(
1184 + slug: string,
1185 + version: string | undefined,
1186 + requestOptions: ComposioRequestOptions | undefined
1187 + ): Promise<Tool> {
1188 + const key = `${slug}\0${version ?? ''}`;
1189 + const cached = this.executeToolSchemas.get(key);
1190 + if (cached && cached.expiresAt > Date.now()) {
1191 + return cached.tool;
1192 + }
1193 +
1194 + const tool = await this.getRawComposioToolBySlug(slug, { version }, requestOptions);
1195 +
1196 + const resolvedVersion =
1197 + version ?? getToolkitVersion(tool.toolkit?.slug ?? 'unknown', this.toolkitVersions);
1198 + const ttlMs =
1199 + resolvedVersion === 'latest' ? LATEST_TOOL_SCHEMA_TTL_MS : PINNED_TOOL_SCHEMA_TTL_MS;
1200 + // Re-insert so a refreshed entry counts as the newest.
1201 + this.executeToolSchemas.delete(key);
1202 + if (this.executeToolSchemas.size >= MAX_CACHED_TOOL_SCHEMAS) {
1203 + const oldestKey = this.executeToolSchemas.keys().next().value;
1204 + if (oldestKey !== undefined) {
1205 + this.executeToolSchemas.delete(oldestKey);
1206 + }
1207 + }
1208 + this.executeToolSchemas.set(key, { tool, expiresAt: Date.now() + ttlMs });
1209 + return tool;
1210 + }
1211 +
1212 /**
1213 * Executes a tool based on a tool router session.
1214 *
ts/packages/core/src/utils/rateLimit.ts new
+25
@@ -0,0 +1,25 @@
1 +import { APIError } from '@composio/client';
2 +
3 +/** Whether a client error is the API rejecting the request with a 429. */
4 +export function isRateLimitResponse(error: unknown): error is APIError {
5 + return error instanceof APIError && error.status === 429;
6 +}
7 +
8 +/**
9 + * Seconds a 429 asks the caller to wait, from its `Retry-After` header (seconds or an HTTP date).
10 + * Undefined when the header is missing or unreadable.
11 + *
12 + * @internal
13 + */
14 +export function getRetryAfterSeconds(error: APIError): number | undefined {
15 + const value = error.headers?.get('retry-after')?.trim();
16 + if (!value) {
17 + return undefined;
18 + }
19 + const seconds = Number(value);
20 + if (Number.isFinite(seconds)) {
21 + return seconds >= 0 ? seconds : undefined;
22 + }
23 + const date = Date.parse(value);
24 + return Number.isNaN(date) ? undefined : Math.max(0, (date - Date.now()) / 1000);
25 +}
ts/packages/core/test/connectedAccounts/connectionRequest.test.ts
+124 -3
@@ -1,8 +1,12 @@
1 import { describe, it, expect, vi, beforeEach } from 'vitest';
2 import { createConnectionRequest } from '../../src/models/ConnectionRequest';
3 import { ConnectionRequest } from '../../src/types/connectionRequest.types';
4 -import ComposioClient, { ComposioError } from '@composio/client';
5 -import { ConnectionRequestFailedError, ConnectionRequestTimeoutError } from '../../src/errors';
4 +import ComposioClient, { APIError, ComposioError, RateLimitError } from '@composio/client';
5 +import {
6 + ComposioConnectedAccountNotFoundError,
7 + ConnectionRequestFailedError,
8 + ConnectionRequestTimeoutError,
9 +} from '../../src/errors';
10 import { ConnectedAccountStatuses } from '../../src/types/connectedAccounts.types';
11 import { AuthSchemeTypes } from '../../src/types/authConfigs.types';
12
@@ -19,7 +23,7 @@ describe('ConnectionRequest', () => {
23 const redirectUrl = 'https://example.com/callback';
24
25 beforeEach(() => {
22 - vi.clearAllMocks();
26 + vi.resetAllMocks();
27 // Reset timers before each test
28 vi.useRealTimers();
29 });
@@ -298,6 +302,123 @@ describe('ConnectionRequest', () => {
302 });
303 });
304
305 + describe('waitForConnection polling', () => {
306 + const pending = { id: connectedAccountId, status: ConnectedAccountStatuses.INITIATED };
307 + const rateLimited = (headers: Record<string, string> = {}) =>
308 + new RateLimitError(429, undefined, 'slow down', new Headers(headers));
309 + const start = (timeout?: number) => {
310 + vi.useFakeTimers();
311 + const request = createConnectionRequest(
312 + mockClient as unknown as ComposioClient,
313 + connectedAccountId
314 + );
315 + const result = request.waitForConnection(timeout).catch(error => error);
316 + return result;
317 + };
318 +
319 + /** Times of each poll, in ms since the wait started, up to `until`. */
320 + const pollTimes = async (until: number) => {
321 + const started = Date.now();
322 + const times: number[] = [];
323 + mockClient.connectedAccounts.retrieve.mockImplementation(async () => {
324 + times.push(Date.now() - started);
325 + return pending;
326 + });
327 + const result = start(until);
328 + await vi.advanceTimersByTimeAsync(until);
329 + return { times, result };
330 + };
331 +
332 + it('backs off from 1s to a 5s cap', async () => {
333 + vi.useFakeTimers();
334 + const { times, result } = await pollTimes(30000);
335 +
336 + expect(await result).toBeInstanceOf(ConnectionRequestTimeoutError);
337 + expect(times.slice(0, 7)).toEqual([0, 1000, 2500, 4750, 8125, 13125, 18125]);
338 + });
339 +
340 + it('sends about 16 requests in the default 60s wait', async () => {
341 + vi.useFakeTimers();
342 + const { times, result } = await pollTimes(60000);
343 +
344 + expect(await result).toBeInstanceOf(ConnectionRequestTimeoutError);
345 + expect(times).toHaveLength(16);
346 + });
347 +
348 + it('polls one last time at the deadline', async () => {
349 + vi.useFakeTimers();
350 + const { times, result } = await pollTimes(3000);
351 +
352 + expect(await result).toBeInstanceOf(ConnectionRequestTimeoutError);
353 + expect(times).toEqual([0, 1000, 2500, 3000]);
354 + });
355 +
356 + it('waits as long as a 429 asks, then keeps polling', async () => {
357 + mockClient.connectedAccounts.retrieve
358 + .mockRejectedValueOnce(rateLimited({ 'retry-after': '10' }))
359 + .mockResolvedValueOnce({
360 + ...pending,
361 + status: ConnectedAccountStatuses.ACTIVE,
362 + auth_config: { id: 'a', auth_scheme: 'OAUTH2', is_composio_managed: true },
363 + data: {},
364 + created_at: '2023-01-01T00:00:00Z',
365 + updated_at: '2023-01-01T00:00:00Z',
366 + status_reason: null,
367 + toolkit: { slug: 'test-toolkit' },
368 + });
369 +
370 + const result = start();
371 + await vi.advanceTimersByTimeAsync(9999);
372 + expect(mockClient.connectedAccounts.retrieve).toHaveBeenCalledTimes(1);
373 +
374 + await vi.advanceTimersByTimeAsync(1);
375 + expect(mockClient.connectedAccounts.retrieve).toHaveBeenCalledTimes(2);
376 + expect(await result).toHaveProperty('status', ConnectedAccountStatuses.ACTIVE);
377 + });
378 +
379 + it('never waits past the timeout for a 429', async () => {
380 + mockClient.connectedAccounts.retrieve.mockRejectedValue(rateLimited({ 'retry-after': '60' }));
381 +
382 + const result = start(5000);
383 + await vi.advanceTimersByTimeAsync(5000);
384 +
385 + expect(await result).toBeInstanceOf(ConnectionRequestTimeoutError);
386 + expect(mockClient.connectedAccounts.retrieve).toHaveBeenCalledTimes(2);
387 + });
388 +
389 + it('keeps its usual delay when a 429 has no usable Retry-After', async () => {
390 + mockClient.connectedAccounts.retrieve.mockRejectedValue(
391 + rateLimited({ 'retry-after': 'soon' })
392 + );
393 +
394 + const result = start(1000);
395 + await vi.advanceTimersByTimeAsync(1000);
396 +
397 + expect(await result).toBeInstanceOf(ConnectionRequestTimeoutError);
398 + expect(mockClient.connectedAccounts.retrieve).toHaveBeenCalledTimes(2);
399 + });
400 +
401 + it('still fails on other API errors', async () => {
402 + const serverError = new APIError(500, undefined, 'boom', new Headers());
403 + mockClient.connectedAccounts.retrieve.mockRejectedValueOnce(serverError);
404 +
405 + expect(await start()).toBe(serverError);
406 + });
407 +
408 + it('reports a connection deleted mid-wait as not found', async () => {
409 + mockClient.connectedAccounts.retrieve
410 + .mockResolvedValueOnce(pending)
411 + .mockRejectedValueOnce(
412 + new ComposioClient.NotFoundError(404, undefined, 'gone', new Headers())
413 + );
414 +
415 + const result = start();
416 + await vi.advanceTimersByTimeAsync(1000);
417 +
418 + expect(await result).toBeInstanceOf(ComposioConnectedAccountNotFoundError);
419 + });
420 + });
421 +
422 describe('serialization methods', () => {
423 it('should return a JSON-serializable object with toJSON()', () => {
424 // Create a connection request instance
ts/packages/core/test/tools/executeSchemaCache.test.ts new
+203
@@ -0,0 +1,203 @@
1 +import { describe, it, expect, vi, afterEach } from 'vitest';
2 +import ComposioClient, { Auth, createFetchTransport } from '@composio/client';
3 +import { Tools } from '../../src/models/Tools';
4 +import { ComposioRequestCancelledError } from '../../src/errors/SDKErrors';
5 +import { MockProvider } from '../utils/mocks/provider.mock';
6 +import { toolMocks } from '../utils/mocks/data.mock';
7 +import {
8 + ComposioToolExecutionError,
9 + ComposioToolExecutionRateLimitError,
10 + ComposioToolFetchError,
11 + ComposioToolFetchRateLimitError,
12 + isComposioRateLimitError,
13 +} from '../../src/errors/ToolErrors';
14 +
15 +vi.mock('../../src/telemetry/Telemetry', () => ({
16 + telemetry: { instrument: vi.fn() },
17 +}));
18 +
19 +const SLUG = 'GITHUB_GET_REPOS';
20 +const json = (body: unknown, status = 200, headers: Record<string, string> = {}) =>
21 + new Response(JSON.stringify(body), {
22 + status,
23 + headers: { 'content-type': 'application/json', ...headers },
24 + });
25 +const rateLimited = () =>
26 + json({ error: { message: 'slow down' } }, 429, { 'retry-after': '7', 'retry-after-ms': '1' });
27 +
28 +/** A real client whose schema and execute responses come from the given handlers. */
29 +const createTools = (
30 + options: {
31 + retrieve?: () => Response;
32 + execute?: () => Response;
33 + toolkitVersions?: Record<string, string>;
34 + } = {}
35 +) => {
36 + const retrieve = vi.fn(options.retrieve ?? (() => json(toolMocks.rawTool)));
37 + const execute = vi.fn(options.execute ?? (() => json(toolMocks.rawToolExecuteResponse)));
38 + const fetch = vi.fn<typeof globalThis.fetch>(async (input, init) => {
39 + const method = init?.method ?? (input instanceof Request ? input.method : 'GET');
40 + return method === 'GET' ? retrieve() : execute();
41 + });
42 + const client = new ComposioClient({
43 + auth: Auth.project('test-api-key'),
44 + baseURL: 'https://backend.invalid',
45 + transport: createFetchTransport({ fetch }),
46 + });
47 + const tools = new Tools(client, {
48 + provider: new MockProvider(),
49 + toolkitVersions: options.toolkitVersions,
50 + });
51 + return { tools, retrieve, execute };
52 +};
53 +
54 +const run = (tools: ReturnType<typeof createTools>['tools'], version?: string) =>
55 + tools.execute(SLUG, {
56 + userId: 'user_1',
57 + arguments: {},
58 + version,
59 + dangerouslySkipVersionCheck: true,
60 + });
61 +
62 +describe('tools.execute schema cache', () => {
63 + afterEach(() => {
64 + vi.useRealTimers();
65 + });
66 +
67 + it('fetches the schema once across executions of one tool', async () => {
68 + const { tools, retrieve, execute } = createTools();
69 +
70 + await run(tools);
71 + await run(tools);
72 + await run(tools);
73 +
74 + expect(retrieve).toHaveBeenCalledTimes(1);
75 + expect(execute).toHaveBeenCalledTimes(3);
76 + });
77 +
78 + it('keeps a separate entry per version', async () => {
79 + const { tools, retrieve } = createTools();
80 +
81 + await run(tools, '20250909_00');
82 + await run(tools, '20250910_00');
83 + await run(tools, '20250909_00');
84 +
85 + expect(retrieve).toHaveBeenCalledTimes(2);
86 + });
87 +
88 + it('refetches a latest schema after 5 minutes', async () => {
89 + vi.useFakeTimers({ toFake: ['Date'] });
90 + const { tools, retrieve } = createTools();
91 +
92 + await run(tools);
93 + vi.advanceTimersByTime(5 * 60 * 1000 - 1);
94 + await run(tools);
95 + expect(retrieve).toHaveBeenCalledTimes(1);
96 +
97 + vi.advanceTimersByTime(1);
98 + await run(tools);
99 + expect(retrieve).toHaveBeenCalledTimes(2);
100 + });
101 +
102 + it('keeps a pinned schema for an hour', async () => {
103 + vi.useFakeTimers({ toFake: ['Date'] });
104 + const { tools, retrieve } = createTools();
105 +
106 + await run(tools, '20250909_00');
107 + vi.advanceTimersByTime(60 * 60 * 1000 - 1);
108 + await run(tools, '20250909_00');
109 + expect(retrieve).toHaveBeenCalledTimes(1);
110 +
111 + vi.advanceTimersByTime(1);
112 + await run(tools, '20250909_00');
113 + expect(retrieve).toHaveBeenCalledTimes(2);
114 + });
115 +
116 + it('does not cache a failed fetch', async () => {
117 + const retrieve = vi
118 + .fn<() => Response>()
119 + .mockReturnValueOnce(json({ error: { message: 'bad' } }, 400))
120 + .mockReturnValue(json(toolMocks.rawTool));
121 + const { tools } = createTools({ retrieve });
122 +
123 + await expect(run(tools)).rejects.toThrow();
124 + await expect(run(tools)).resolves.toBeDefined();
125 + expect(retrieve).toHaveBeenCalledTimes(2);
126 + });
127 +
128 + it('still honors an aborted signal on a cache hit', async () => {
129 + const { tools, execute } = createTools();
130 + await run(tools);
131 +
132 + const error = await tools
133 + .execute(
134 + SLUG,
135 + { userId: 'user_1', arguments: {}, dangerouslySkipVersionCheck: true },
136 + { signal: AbortSignal.abort() }
137 + )
138 + .catch(e => e);
139 +
140 + expect(error).toBeInstanceOf(ComposioRequestCancelledError);
141 + expect(execute).toHaveBeenCalledTimes(1);
142 + });
143 +
144 + it('leaves getRawComposioToolBySlug uncached', async () => {
145 + const { tools, retrieve } = createTools();
146 +
147 + await tools.getRawComposioToolBySlug(SLUG);
148 + await tools.getRawComposioToolBySlug(SLUG);
149 +
150 + expect(retrieve).toHaveBeenCalledTimes(2);
151 + });
152 +});
153 +
154 +describe('rate limit errors', () => {
155 + it('reports a rejected schema fetch as a rate limit, not a bad slug', async () => {
156 + const { tools, execute } = createTools({ retrieve: rateLimited });
157 +
158 + const error = await run(tools).catch(e => e);
159 +
160 + expect(error).toBeInstanceOf(ComposioToolFetchRateLimitError);
161 + expect(error).toBeInstanceOf(ComposioToolFetchError);
162 + expect(isComposioRateLimitError(error)).toBe(true);
163 + expect(error.retryAfterSeconds).toBe(7);
164 + expect(error.statusCode).toBe(429);
165 + expect(error.possibleFixes.join(' ')).not.toContain('slug');
166 + expect(execute).not.toHaveBeenCalled();
167 + });
168 +
169 + it('reports a rejected execution as a rate limit, once', async () => {
170 + const { tools, execute } = createTools({ execute: rateLimited });
171 +
172 + const error = await run(tools).catch(e => e);
173 +
174 + expect(error).toBeInstanceOf(ComposioToolExecutionRateLimitError);
175 + expect(error).toBeInstanceOf(ComposioToolExecutionError);
176 + expect(isComposioRateLimitError(error)).toBe(true);
177 + expect(error.retryAfterSeconds).toBe(7);
178 + expect(error.statusCode).toBe(429);
179 + expect(execute).toHaveBeenCalledTimes(1);
180 + });
181 +
182 + it('leaves out retryAfterSeconds when the response gives no wait', async () => {
183 + const { tools } = createTools({
184 + retrieve: () => json({ error: { message: 'slow down' } }, 429, { 'retry-after-ms': '1' }),
185 + });
186 +
187 + const error = await run(tools).catch(e => e);
188 +
189 + expect(isComposioRateLimitError(error)).toBe(true);
190 + expect(Object.keys(error)).not.toContain('retryAfterSeconds');
191 + });
192 +
193 + it('does not report other failures as rate limits', async () => {
194 + const { tools } = createTools({
195 + retrieve: () => json({ error: { message: 'bad key' } }, 401),
196 + });
197 +
198 + const error = await run(tools).catch(e => e);
199 +
200 + expect(error).toBeInstanceOf(ComposioToolFetchError);
201 + expect(isComposioRateLimitError(error)).toBe(false);
202 + });
203 +});