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
ts 271 lines 10.4 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 below the generated client, through a
7 * `fetch` wrapper, and warns once per process for each deprecated toolkit
8 * version it sees. The response itself is never read, cloned or altered.
9 *
10 * Example header:
11 *
12 * "GMAIL";version="20250114_00";deprecated=@1779840000;sunset=@1787788800;reason="lifecycle"
13 */
14 import { z } from 'zod';
15 import logger from './logger';
16 import { normalizeToolkitSlug } from './toolkitVersion';
17
18 /** Response header name. `Headers.get` is case-insensitive. */
19 export const TOOLKIT_DEPRECATION_HEADER = 'composio-deprecated-toolkits';
20
21 /** Anchor of the docs section every warning points at. */
22 export const TOOLKIT_DEPRECATION_DOCS_URL =
23 'https://docs.composio.dev/docs/tools-direct/toolkit-versioning#deprecation-and-sunset';
24
25 /** Versions named per toolkit before the formatter collapses the rest into "and N more". */
26 const MAX_VERSIONS_PER_LINE = 5;
27
28 /**
29 * The three limits below mirror the `@composio/client` deprecation module,
30 * which reads the same kind of server-controlled header.
31 */
32 /** A header longer than this is ignored whole rather than parsed. */
33 const MAX_HEADER_LENGTH = 2048;
34 /** A header holding any of these is ignored whole, so nothing partially cleaned reaches the log. */
35 const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/;
36 /** Keys the process will ever record; past this, new versions are neither recorded nor warned about. */
37 const MAX_TRACKED_VERSIONS = 1024;
38
39 const DeprecatedToolkitEntrySchema = z.object({
40 slug: z.string().min(1),
41 version: z.string().min(1),
42 deprecatedAt: z.date().optional(),
43 sunsetAt: z.date().optional(),
44 reason: z.string().min(1).optional(),
45 });
46
47 export type DeprecatedToolkitEntry = z.infer<typeof DeprecatedToolkitEntrySchema>;
48
49 /** Keys (`UPPER(slug)@version`) already warned about in this process. */
50 const warnedToolkitVersions = new Set<string>();
51
52 const dedupeKey = (entry: Pick<DeprecatedToolkitEntry, 'slug' | 'version'>): string =>
53 `${entry.slug.toUpperCase()}@${entry.version}`;
54
55 /**
56 * Splits `value` on `delimiter` characters that sit outside double-quoted
57 * strings, honouring backslash escapes inside the quotes. Empty pieces are
58 * dropped and the rest are trimmed.
59 */
60 const splitOutsideQuotes = (value: string, delimiter: string): string[] => {
61 const pieces: string[] = [];
62 let current = '';
63 let inString = false;
64 for (let index = 0; index < value.length; index++) {
65 const char = value[index];
66 if (inString) {
67 current += char;
68 if (char === '\\' && index + 1 < value.length) {
69 index += 1;
70 current += value[index];
71 } else if (char === '"') {
72 inString = false;
73 }
74 } else if (char === '"') {
75 inString = true;
76 current += char;
77 } else if (char === delimiter) {
78 pieces.push(current);
79 current = '';
80 } else {
81 current += char;
82 }
83 }
84 pieces.push(current);
85 return pieces.map(piece => piece.trim()).filter(piece => piece.length > 0);
86 };
87
88 /**
89 * Decodes an sf-string (`"..."` with `\"` and `\\` escapes). Returns
90 * `undefined` for anything that is not a complete, validly escaped sf-string.
91 */
92 const decodeSfString = (raw: string): string | undefined => {
93 const match = /^"((?:[^"\\]|\\.)*)"$/.exec(raw);
94 if (match === null) return undefined;
95 let invalidEscape = false;
96 const decoded = match[1].replace(/\\(.)/g, (_whole, escaped: string) => {
97 if (escaped === '"' || escaped === '\\') return escaped;
98 invalidEscape = true;
99 return '';
100 });
101 return invalidEscape ? undefined : decoded;
102 };
103
104 /** Decodes an sf-date (`@` followed by Unix seconds). */
105 const decodeSfDate = (raw: string): Date | undefined => {
106 const match = /^@(-?\d{1,15})$/.exec(raw);
107 if (match === null) return undefined;
108 const date = new Date(Number(match[1]) * 1000);
109 return Number.isNaN(date.getTime()) ? undefined : date;
110 };
111
112 /** Header parameters the SDK understands, by wire name. */
113 const KNOWN_PARAMETERS = new Map<
114 string,
115 { name: Exclude<keyof DeprecatedToolkitEntry, 'slug'>; kind: 'string' | 'date' }
116 >([
117 ['version', { name: 'version', kind: 'string' }],
118 ['reason', { name: 'reason', kind: 'string' }],
119 ['deprecated', { name: 'deprecatedAt', kind: 'date' }],
120 ['sunset', { name: 'sunsetAt', kind: 'date' }],
121 ]);
122
123 /**
124 * Parses one list item: an sf-string slug followed by `;key=value` parameters.
125 * Unknown parameters are ignored; a known parameter with the wrong type drops
126 * the item.
127 */
128 const parseItem = (item: string): DeprecatedToolkitEntry | undefined => {
129 const [head, ...params] = splitOutsideQuotes(item, ';');
130 if (head === undefined) return undefined;
131 const candidate: Record<string, unknown> = { slug: decodeSfString(head) };
132 for (const param of params) {
133 const separator = param.indexOf('=');
134 if (separator === -1) continue;
135 const key = param.slice(0, separator).trim();
136 const rawValue = param.slice(separator + 1).trim();
137 const field = KNOWN_PARAMETERS.get(key);
138 if (field === undefined) continue;
139 const decoded = field.kind === 'string' ? decodeSfString(rawValue) : decodeSfDate(rawValue);
140 if (decoded === undefined) return undefined;
141 candidate[field.name] = decoded;
142 }
143 const parsed = DeprecatedToolkitEntrySchema.safeParse(candidate);
144 return parsed.success ? parsed.data : undefined;
145 };
146
147 /**
148 * Parses a `Composio-Deprecated-Toolkits` header value. Items that fail to
149 * parse are dropped silently; garbage input yields an empty array. Never throws.
150 */
151 export function parseDeprecatedToolkitsHeader(value: string): DeprecatedToolkitEntry[] {
152 try {
153 const entries: DeprecatedToolkitEntry[] = [];
154 for (const item of splitOutsideQuotes(value, ',')) {
155 const entry = parseItem(item);
156 if (entry !== undefined) entries.push(entry);
157 }
158 return entries;
159 } catch {
160 return [];
161 }
162 }
163
164 const isoDate = (date: Date): string => date.toISOString().slice(0, 10);
165
166 const pinHint = (slug: string, docsUrl: string): string => {
167 const configKey = normalizeToolkitSlug(slug);
168 const envVar = `COMPOSIO_TOOLKIT_VERSION_${slug.toUpperCase()}`;
169 return `Pin a newer version with toolkitVersions: { ${configKey}: '<version>' } or ${envVar}. See ${docsUrl}.`;
170 };
171
172 const formatSingle = (entry: DeprecatedToolkitEntry, docsUrl: string): string => {
173 let sentence = `[Deprecation] Toolkit ${entry.slug.toUpperCase()} version ${entry.version} was deprecated`;
174 if (entry.deprecatedAt !== undefined) sentence += ` on ${isoDate(entry.deprecatedAt)}`;
175 if (entry.reason !== undefined) sentence += ` (${entry.reason})`;
176 if (entry.sunsetAt !== undefined)
177 sentence += ` and will stop working on ${isoDate(entry.sunsetAt)}`;
178 return `${sentence}. ${pinHint(entry.slug, docsUrl)}`;
179 };
180
181 const formatGroup = (slug: string, entries: DeprecatedToolkitEntry[], docsUrl: string): string => {
182 const versions = entries.map(entry => entry.version);
183 const named = versions.slice(0, MAX_VERSIONS_PER_LINE).join(', ');
184 const remaining = versions.length - MAX_VERSIONS_PER_LINE;
185 const list = remaining > 0 ? `${named} and ${remaining} more` : named;
186 let sentence = `[Deprecation] Toolkit ${slug} versions ${list} are deprecated`;
187 const sunsets = entries
188 .map(entry => entry.sunsetAt)
189 .filter((date): date is Date => date !== undefined)
190 .sort((a, b) => a.getTime() - b.getTime());
191 if (sunsets.length > 0) {
192 sentence += ` and the earliest will stop working on ${isoDate(sunsets[0])}`;
193 }
194 return `${sentence}. ${pinHint(slug, docsUrl)}`;
195 };
196
197 /**
198 * Renders one warning line per toolkit slug. A slug with a single deprecated
199 * version gets the full sentence with its dates and reason; a slug with several
200 * names at most five versions and collapses the rest into "and N more".
201 */
202 export function formatToolkitDeprecationWarnings(
203 entries: DeprecatedToolkitEntry[],
204 docsUrl: string = TOOLKIT_DEPRECATION_DOCS_URL
205 ): string[] {
206 const groups = new Map<string, DeprecatedToolkitEntry[]>();
207 for (const entry of entries) {
208 const slug = entry.slug.toUpperCase();
209 const group = groups.get(slug);
210 if (group === undefined) groups.set(slug, [entry]);
211 else group.push(entry);
212 }
213 return Array.from(groups, ([slug, group]) =>
214 group.length === 1 ? formatSingle(group[0], docsUrl) : formatGroup(slug, group, docsUrl)
215 );
216 }
217
218 /**
219 * Parses the header on `response`, drops versions already warned about in this
220 * process, records the new ones and warns once per formatted line.
221 */
222 const warnDeprecatedToolkits = (response: Response): void => {
223 const value = response.headers.get(TOOLKIT_DEPRECATION_HEADER);
224 if (value === null || value.length === 0) return;
225 if (value.length > MAX_HEADER_LENGTH || CONTROL_CHARACTERS.test(value)) return;
226 if (warnedToolkitVersions.size >= MAX_TRACKED_VERSIONS) return;
227 const fresh: DeprecatedToolkitEntry[] = [];
228 for (const entry of parseDeprecatedToolkitsHeader(value)) {
229 const key = dedupeKey(entry);
230 if (warnedToolkitVersions.has(key) || warnedToolkitVersions.size >= MAX_TRACKED_VERSIONS)
231 continue;
232 warnedToolkitVersions.add(key);
233 fresh.push(entry);
234 }
235 for (const line of formatToolkitDeprecationWarnings(fresh)) {
236 logger.warn(line);
237 }
238 };
239
240 /**
241 * Wraps a `fetch` implementation so every response is checked for the
242 * `Composio-Deprecated-Toolkits` header. The wrapper is `this`-independent,
243 * returns the response unchanged on every path and never fails a call over
244 * the header: any error while inspecting it is logged at debug and swallowed.
245 *
246 * When no `baseFetch` is given, `globalThis.fetch` is resolved per call so a
247 * runtime that installs or replaces `fetch` after construction still works.
248 */
249 export function createToolkitDeprecationFetch(
250 baseFetch?: typeof globalThis.fetch
251 ): typeof globalThis.fetch {
252 return async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
253 const target = baseFetch ?? globalThis.fetch;
254 const response = await target(input, init);
255 try {
256 warnDeprecatedToolkits(response);
257 } catch (error) {
258 try {
259 logger.debug('Failed to inspect the toolkit deprecation header', error);
260 } catch {
261 // The fallback is best-effort too: a sink that throws must not fail the call.
262 }
263 }
264 return response;
265 };
266 }
267
268 /** Clears the once-per-process record. Tests only. */
269 export function _resetToolkitDeprecationWarningsForTests(): void {
270 warnedToolkitVersions.clear();
271 }