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 386 lines 13.3 KB
Raw
1 /**
2 * The fake Composio deployment: one process that answers for every host the
3 * `composio` binary talks to (backend, Dashboard, agents service, GitHub
4 * releases, PostHog), keeps a journal of what it received, and can be told to
5 * misbehave per route.
6 */
7
8 import { createServer as createHttpServer } from 'node:http';
9 import type { IncomingMessage, Server, ServerResponse } from 'node:http';
10 import { createServer as createHttpsServer } from 'node:https';
11 import type { AddressInfo } from 'node:net';
12 import {
13 describeFault,
14 errorEnvelope,
15 FaultController,
16 HTML_ERROR_PAGE,
17 MALFORMED_JSON_BODY,
18 type Fault,
19 } from './faults';
20 import { identify, Journal, type RequestIdentity, type ServiceRole } from './journal';
21 import { matchPath, type Route, type RouteContext, type RouteResult } from './route';
22 import { ROUTES } from './routes';
23 import { tlsMaterial } from './tls';
24 import { World, type SeededProject } from './world';
25
26 /** The base URLs of the fake, as seen from one vantage point. */
27 export interface FakeUrls {
28 /** `COMPOSIO_BASE_URL`, `COMPOSIO_AGENTS_BASE_URL`, `COMPOSIO_GITHUB_API_BASE_URL`, `COMPOSIO_GITHUB_URL`. */
29 readonly http: string;
30 /** `COMPOSIO_WEB_URL`. */
31 readonly https: string;
32 readonly posthog: string;
33 }
34
35 export interface FakeComposio {
36 readonly world: World;
37 readonly journal: Journal;
38 readonly faults: FaultController;
39 /** URLs a process on the host uses. */
40 readonly host: FakeUrls;
41 /** URLs a process inside a container uses. */
42 readonly docker: FakeUrls;
43 /** PEM certificate the Dashboard listener presents; trust it with `NODE_EXTRA_CA_CERTS`. */
44 readonly caCert: string;
45 /**
46 * The environment that points every host the binary talks to at this fake.
47 * `dashboard: false` leaves `COMPOSIO_WEB_URL` unset, which keeps consumer
48 * executions on the backend transport.
49 */
50 readonly cliEnv: (options?: { dashboard?: boolean }) => Record<string, string>;
51 readonly close: () => Promise<void>;
52 }
53
54 const roleOf = (path: string, viaTls: boolean): ServiceRole => {
55 if (path.startsWith('/api/cli/trpc/')) return 'dashboard';
56 if (path.startsWith('/api/v3/') || path.startsWith('/api/v3.1/')) return 'backend';
57 if (path.startsWith('/api/')) return 'agents';
58 if (path.startsWith('/repos/')) return 'github-api';
59 if (path.includes('/releases/download/')) return 'github-download';
60 if (path.startsWith('/posthog')) return 'posthog';
61 return viaTls ? 'dashboard' : 'unknown';
62 };
63
64 const readBody = (request: IncomingMessage): Promise<string> =>
65 new Promise((resolve, reject) => {
66 const chunks: Uint8Array[] = [];
67 request.on('data', (chunk: Uint8Array) => chunks.push(chunk));
68 request.on('end', () => resolve(new TextDecoder().decode(Buffer.concat(chunks))));
69 request.on('error', reject);
70 });
71
72 const parseJson = (text: string): unknown => {
73 if (text.trim() === '') return undefined;
74 try {
75 return JSON.parse(text) as unknown;
76 } catch {
77 // Kept as text so the journal still shows what arrived.
78 return text;
79 }
80 };
81
82 const toHeaders = (request: IncomingMessage): Headers => {
83 const headers = new Headers();
84 for (const [name, value] of Object.entries(request.headers)) {
85 if (value === undefined) continue;
86 headers.set(name, Array.isArray(value) ? value.join(', ') : value);
87 }
88 return headers;
89 };
90
91 interface Planned {
92 readonly status: number;
93 readonly headers: Record<string, string>;
94 readonly body: Uint8Array;
95 }
96
97 const plan = (result: RouteResult): Planned => {
98 const status = result.status ?? 200;
99 if (result.bytes !== undefined) {
100 return {
101 status,
102 headers: { 'content-type': 'application/octet-stream', ...result.headers },
103 body: result.bytes,
104 };
105 }
106 if (result.text !== undefined) {
107 return {
108 status,
109 headers: { 'content-type': 'text/plain; charset=utf-8', ...result.headers },
110 body: new TextEncoder().encode(result.text),
111 };
112 }
113 return {
114 status,
115 headers: { 'content-type': 'application/json', ...result.headers },
116 body: new TextEncoder().encode(result.json === undefined ? '' : JSON.stringify(result.json)),
117 };
118 };
119
120 const jsonPlan = (status: number, json: unknown, headers: Record<string, string> = {}): Planned =>
121 plan({ status, json, headers });
122
123 /** The answer a fault dictates. `null` drops the connection without a response. */
124 const distort = async (
125 fault: Fault,
126 honest: Planned
127 ): Promise<{ planned: Planned; cutAfter?: number } | null> => {
128 switch (fault.kind) {
129 case 'status':
130 return {
131 planned: jsonPlan(
132 fault.status,
133 fault.body ??
134 errorEnvelope({
135 status: fault.status,
136 message: fault.message ?? `Injected HTTP ${fault.status}`,
137 slug: fault.slug ?? `Injected_${fault.status}`,
138 code: fault.code,
139 }),
140 { ...fault.headers }
141 ),
142 };
143 case 'delay':
144 await Bun.sleep(fault.ms);
145 return { planned: honest };
146 case 'reset':
147 return null;
148 case 'reset-mid-body':
149 return { planned: honest, cutAfter: Math.max(1, Math.floor(honest.body.length / 2)) };
150 case 'malformed-json':
151 return { planned: plan({ status: 200, text: MALFORMED_JSON_BODY, headers: honest.headers }) };
152 case 'schema-drift': {
153 const drifted = fault.transform(JSON.parse(new TextDecoder().decode(honest.body)));
154 return { planned: jsonPlan(honest.status, drifted) };
155 }
156 case 'html':
157 return {
158 planned: plan({
159 status: fault.status ?? 502,
160 text: HTML_ERROR_PAGE,
161 headers: { 'content-type': 'text/html; charset=utf-8' },
162 }),
163 };
164 case 'empty-body':
165 return { planned: plan({ status: 200, json: undefined }) };
166 }
167 };
168
169 const send = (response: ServerResponse, planned: Planned, cutAfter?: number): void => {
170 response.writeHead(planned.status, {
171 ...planned.headers,
172 'content-length': String(planned.body.length),
173 });
174 if (cutAfter === undefined) {
175 response.end(planned.body);
176 return;
177 }
178 // The declared length is never delivered: the client sees the body end early.
179 response.write(planned.body.subarray(0, cutAfter));
180 setTimeout(() => response.socket?.destroy(), 50);
181 };
182
183 const labelled = (world: World, identity: RequestIdentity): SeededProject | undefined =>
184 identity.project ? world.projectByLabel(identity.project) : undefined;
185
186 const authorize = (
187 route: Route,
188 identity: RequestIdentity,
189 world: World
190 ): { project: SeededProject | undefined } | { denied: Planned } => {
191 if (route.auth === 'none') return { project: labelled(world, identity) };
192
193 const unauthorized = (message: string): { denied: Planned } => ({
194 denied: jsonPlan(401, errorEnvelope({ status: 401, message, slug: 'Auth_InvalidApiKey' })),
195 });
196 if (identity.keyClass === 'none') return unauthorized('No API key provided');
197 if (!identity.keyKnown) return unauthorized('Invalid API key');
198
199 if (route.auth === 'key') return { project: labelled(world, identity) };
200
201 if (route.auth === 'user') {
202 return identity.keyClass === 'user'
203 ? { project: labelled(world, identity) }
204 : unauthorized('This endpoint requires a user API key');
205 }
206
207 // A user key sent without `x-org-id` and `x-project-id` acts on the org's
208 // default project, the one `auth/session/info` reports for that key.
209 return { project: labelled(world, identity) ?? world.defaultProject };
210 };
211
212 const listen = (server: Server): Promise<number> =>
213 new Promise((resolve, reject) => {
214 server.once('error', reject);
215 server.listen({ host: '0.0.0.0', port: 0 }, () => {
216 server.off('error', reject);
217 resolve((server.address() as AddressInfo).port);
218 });
219 });
220
221 const closeServer = (server: Server): Promise<void> =>
222 new Promise(resolve => {
223 server.closeAllConnections();
224 server.close(() => resolve());
225 });
226
227 /** Starts the fake on two free ports (HTTP, and HTTPS for the Dashboard). */
228 export const startFakeComposio = async (
229 options: {
230 routes?: ReadonlyArray<Route>;
231 /** The one user API key this deployment issued; defaults to the seeded key. */
232 userApiKey?: string;
233 } = {}
234 ): Promise<FakeComposio> => {
235 const world = new World({ userApiKey: options.userApiKey });
236 const journal = new Journal();
237 const faults = new FaultController();
238 // Suite-specific routes come first so they can shadow a seeded one.
239 const routes = [...(options.routes ?? []), ...ROUTES];
240 const tls = tlsMaterial();
241 let urls: { host: FakeUrls; docker: FakeUrls } | undefined;
242
243 const handler = (viaTls: boolean) => (request: IncomingMessage, response: ServerResponse) => {
244 void (async () => {
245 const url = new URL(request.url ?? '/', 'http://fake.invalid');
246 const method = request.method ?? 'GET';
247 const headers = toHeaders(request);
248 const body = parseJson(await readBody(request));
249 const identity = identify(headers, world);
250 const role = roleOf(url.pathname, viaTls);
251
252 let params: Record<string, string> = {};
253 const route = routes.find(candidate => {
254 if (candidate.method !== method) return false;
255 const captured = matchPath(candidate.path, url.pathname);
256 if (captured) params = captured;
257 return captured !== undefined;
258 });
259
260 let acted: RouteResult['acted'];
261 let effect: RouteResult['effect'];
262 let tool: RouteResult['tool'];
263 let scoped: SeededProject | undefined;
264 const honest = (): Planned => {
265 if (!route) {
266 return jsonPlan(
267 404,
268 errorEnvelope({
269 status: 404,
270 message: `The fake backend has no route for ${method} ${url.pathname}`,
271 slug: 'Fake_UnhandledRoute',
272 })
273 );
274 }
275 const access = authorize(route, identity, world);
276 if ('denied' in access) return access.denied;
277 if (route.auth === 'project') scoped = access.project;
278 const context: RouteContext = {
279 world,
280 identity,
281 params,
282 query: url.searchParams,
283 body,
284 headers,
285 urls: { backend: urls!.docker.http, dashboard: urls!.docker.https },
286 project: access.project,
287 };
288 const result = route.handle(context);
289 acted = result.acted;
290 effect = result.effect;
291 tool = result.tool;
292 return plan(result);
293 };
294
295 const fault = faults.take(route?.name ?? null, method, url.pathname);
296 // A fault that replaces the answer must not also let the route act.
297 const replaces =
298 fault !== undefined &&
299 fault.kind !== 'delay' &&
300 fault.kind !== 'schema-drift' &&
301 fault.kind !== 'reset-mid-body';
302 const honestPlan = replaces ? jsonPlan(200, {}) : honest();
303 const outcome = fault ? await distort(fault, honestPlan) : { planned: honestPlan };
304
305 journal.record({
306 role,
307 method,
308 path: url.pathname,
309 query: Object.fromEntries(url.searchParams),
310 route: route?.name ?? null,
311 keyClass: identity.keyClass,
312 keyKnown: identity.keyKnown,
313 orgId: identity.orgId,
314 project: acted?.project !== undefined ? acted.project : (scoped?.label ?? identity.project),
315 requestedProject: identity.project,
316 projectFrom:
317 acted?.project !== undefined && acted.project !== identity.project
318 ? 'route'
319 : identity.project !== null
320 ? identity.keyClass === 'project'
321 ? 'project-key'
322 : 'scope-headers'
323 : scoped
324 ? 'key-default'
325 : null,
326 userId: acted?.userId ?? null,
327 body,
328 status: outcome?.planned.status ?? 0,
329 effect: effect ?? null,
330 tool: tool ?? null,
331 fault: fault ? describeFault(fault) : null,
332 });
333
334 if (outcome === null) {
335 request.socket.destroy();
336 return;
337 }
338 send(response, outcome.planned, outcome.cutAfter);
339 })().catch(error => {
340 // A handler bug must fail the test that triggered it, not hang the client.
341 send(
342 response,
343 jsonPlan(
344 500,
345 errorEnvelope({
346 status: 500,
347 message: `Fake backend handler threw: ${error instanceof Error ? error.message : String(error)}`,
348 slug: 'Fake_HandlerThrew',
349 })
350 )
351 );
352 });
353 };
354
355 const httpServer = createHttpServer(handler(false));
356 const httpsServer = createHttpsServer({ key: tls.key, cert: tls.cert }, handler(true));
357 const [httpPort, httpsPort] = await Promise.all([listen(httpServer), listen(httpsServer)]);
358
359 const urlsFor = (hostname: string): FakeUrls => ({
360 http: `http://${hostname}:${httpPort}`,
361 https: `https://${hostname}:${httpsPort}`,
362 posthog: `http://${hostname}:${httpPort}/posthog/i/v0/e/`,
363 });
364 urls = { host: urlsFor('localhost'), docker: urlsFor('host.docker.internal') };
365 const docker = urls.docker;
366
367 return {
368 world,
369 journal,
370 faults,
371 host: urls.host,
372 docker,
373 caCert: tls.cert,
374 cliEnv: ({ dashboard = true } = {}) => ({
375 COMPOSIO_BASE_URL: docker.http,
376 ...(dashboard ? { COMPOSIO_WEB_URL: docker.https } : {}),
377 COMPOSIO_AGENTS_BASE_URL: docker.http,
378 COMPOSIO_GITHUB_API_BASE_URL: docker.http,
379 COMPOSIO_GITHUB_URL: docker.http,
380 COMPOSIO_POSTHOG_INGEST_URL: docker.posthog,
381 }),
382 close: async () => {
383 await Promise.all([closeServer(httpServer), closeServer(httpsServer)]);
384 },
385 };
386 };