History

Project the heavy schema columns off the tool hot paths (#970)

Every invoke loaded the full tool row — including input_schema and output_schema JSON it never reads — and tools.list loaded every tool's schemas unbounded just to project metadata, so list cost scaled with schema bytes rather than tool count. The same shape of waste the spec inlining had, in miniature, across the tool table. The core DB wrapper now exposes fumadb's column projection (select), typed per table with the result narrowed to the chosen columns. The invoke lookup, tools.list, and the not-found suggestion queries select TOOL_INVOCATION_COLUMNS — everything but the two schema columns. The plugin invokeTool contract documents this as ToolInvocationRow (no plugin read the schemas off the row; operation details ride in plugin storage or annotations). tools.schema (describe) is unchanged and remains the schema-bearing surface. One test moved from asserting schemas on tools.list to tools.schema — that list behavior is exactly what this change removes.

Rhys Sullivan committed 5 months ago

Commit 247634b1 parent 757cc966 files · +194 −22Browse files

Unified · Split

6 files
  1. packages/core/sdk/src/core-schema.ts +19 −0
  2. packages/core/sdk/src/executor.ts +45 −15
  3. packages/core/sdk/src/index.ts +1 −0
  4. packages/core/sdk/src/plugin.ts +3 −3
  5. packages/plugins/openapi/src/sdk/non-json-body.test.ts +5 −4
  6. packages/plugins/openapi/src/sdk/tool-row-projection.test.ts +121 −0
packages/core/sdk/src/core-schema.ts+19−0
@@ -288,6 +288,25 @@ export type ConnectionRow = FumaRow<CoreSchema["connection"]>; · 287 unmodified lines
288export type OAuthClientRow = FumaRow<CoreSchema["oauth_client"]>;288export type OAuthClientRow = FumaRow<CoreSchema["oauth_client"]>;
289export type OAuthSessionRow = FumaRow<CoreSchema["oauth_session"]>;289export type OAuthSessionRow = FumaRow<CoreSchema["oauth_session"]>;
290export type ToolRow = FumaRow<CoreSchema["tool"]>;290export type ToolRow = FumaRow<CoreSchema["tool"]>;
291/** The tool-row projection the invoke/list hot paths load: everything except
292 * the heavy `input_schema`/`output_schema` JSON, which only `tools.schema`
293 * (describe) needs. Plugin `invokeTool` receives this shape — operation
294 * details ride in plugin storage or `annotations`, not the row schemas. */
295export type ToolInvocationRow = Omit<ToolRow, "input_schema" | "output_schema">;
296/** The columns backing {@link ToolInvocationRow}, for `select` projections. */
297export const TOOL_INVOCATION_COLUMNS = [
298 "tenant",
299 "owner",
300 "subject",
301 "integration",
302 "connection",
303 "plugin_id",
304 "name",
305 "description",
306 "annotations",
307 "created_at",
308 "updated_at",
309] as const satisfies readonly (keyof ToolRow)[];
291export type DefinitionRow = FumaRow<CoreSchema["definition"]>;310export type DefinitionRow = FumaRow<CoreSchema["definition"]>;
292export type ToolPolicyRow = FumaRow<CoreSchema["tool_policy"]>;311export type ToolPolicyRow = FumaRow<CoreSchema["tool_policy"]>;
293export type PluginStorageRow = FumaRow<CoreSchema["plugin_storage"]>;312export type PluginStorageRow = FumaRow<CoreSchema["plugin_storage"]>;
packages/core/sdk/src/executor.ts+45−15
@@ -28,10 +28,12 @@ import type { · 27 unmodified lines
28import {28import {
29 coreSchema,29 coreSchema,
30 isToolPolicyAction,30 isToolPolicyAction,
31 TOOL_INVOCATION_COLUMNS,
31 type ConnectionRow,32 type ConnectionRow,
32 type CoreSchema,33 type CoreSchema,
33 type IntegrationRow,34 type IntegrationRow,
34 type OAuthClientRow,35 type OAuthClientRow,
36 type ToolInvocationRow,
35 type ToolRow,37 type ToolRow,
36 type ToolPolicyRow,38 type ToolPolicyRow,
37} from "./core-schema";39} from "./core-schema";
@@ -513,7 +515,13 @@ const connectionItemIds = (row: ConnectionRow): Record<string, string> => { · 475 unmodified lines
513 return decoded as Record<string, string>;515 return decoded as Record<string, string>;
514};516};
515 517
516const rowToTool = (row: ToolRow, annotations?: ToolAnnotations): Tool => {518// Accepts a projected row (the invoke/list paths select away the heavy
519// schema columns); `Tool.inputSchema`/`outputSchema` are optional and stay
520// absent for those callers — `tools.schema` is the schema-bearing surface.
521const rowToTool = (
522 row: ToolInvocationRow & Partial<Pick<ToolRow, "input_schema" | "output_schema">>,
523 annotations?: ToolAnnotations,
524): Tool => {
517 const owner = row.owner as Owner;525 const owner = row.owner as Owner;
518 const integration = IntegrationSlug.make(row.integration);526 const integration = IntegrationSlug.make(row.integration);
519 const connection = ConnectionName.make(row.connection);527 const connection = ConnectionName.make(row.connection);
@@ -539,16 +547,29 @@ const rowToTool = (row: ToolRow, annotations?: ToolAnnotations): Tool => { · 19 unmodified lines
539type AnyCb = ConditionBuilder<Record<string, AnyColumn>>;547type AnyCb = ConditionBuilder<Record<string, AnyColumn>>;
540type CoreTableName = keyof CoreSchema & string;548type CoreTableName = keyof CoreSchema & string;
541type CoreRow<TName extends CoreTableName> = FumaRow<CoreSchema[TName]>;549type CoreRow<TName extends CoreTableName> = FumaRow<CoreSchema[TName]>;
550type CoreColumn<TName extends CoreTableName> = keyof CoreRow<TName> & string;
542type CoreWhere = (b: AnyCb) => Condition | boolean;551type CoreWhere = (b: AnyCb) => Condition | boolean;
543type CoreFindManyOptions = {552type CoreFindManyOptions<TName extends CoreTableName = CoreTableName> = {
544 readonly where?: CoreWhere;553 readonly where?: CoreWhere;
545 readonly limit?: number;554 readonly limit?: number;
546 readonly offset?: number;555 readonly offset?: number;
547 readonly orderBy?:556 readonly orderBy?:
548 | readonly [string, "asc" | "desc"]557 | readonly [string, "asc" | "desc"]
549 | readonly (readonly [string, "asc" | "desc"])[];558 | readonly (readonly [string, "asc" | "desc"])[];
559 /** Column projection (fumadb `select`). Omit for all columns. Use on hot
560 * paths whose rows carry heavy JSON columns the caller discards — e.g. a
561 * tool row is ~KBs of schemas but invoke routing needs only the names. */
562 readonly select?: readonly CoreColumn<TName>[];
550};563};
551type CoreFindFirstOptions = Omit<CoreFindManyOptions, "limit" | "offset">;564type CoreFindFirstOptions<TName extends CoreTableName = CoreTableName> = Omit<
565 CoreFindManyOptions<TName>,
566 "limit" | "offset"
567>;
568/** The narrowed row a projected query returns: the selected columns keep
569 * their types, everything else is absent. */
570type CoreProjectedRow<TName extends CoreTableName, TSelect> = TSelect extends readonly (infer K)[]
571 ? Pick<CoreRow<TName>, Extract<K, keyof CoreRow<TName>>>
572 : CoreRow<TName>;
552 573
553type LooseStorageDb = {574type LooseStorageDb = {
554 readonly count: (tableName: string, options?: unknown) => Promise<number>;575 readonly count: (tableName: string, options?: unknown) => Promise<number>;
@@ -603,20 +624,20 @@ const makeCoreDb = (fuma: ReturnType<typeof makeFumaClient>) => ({ · 48 unmodified lines
603 fuma.use(`${tableName}.deleteMany`, (db) =>624 fuma.use(`${tableName}.deleteMany`, (db) =>
604 asLooseStorageDb(db).deleteMany(tableName, options),625 asLooseStorageDb(db).deleteMany(tableName, options),
605 ),626 ),
606 findFirst: <TName extends CoreTableName>(627 findFirst: <TName extends CoreTableName, const TOptions extends CoreFindFirstOptions<TName>>(
607 tableName: TName,628 tableName: TName,
608 options: CoreFindFirstOptions,629 options: TOptions,
609 ): Effect.Effect<CoreRow<TName> | null, StorageFailure> =>630 ): Effect.Effect<CoreProjectedRow<TName, TOptions["select"]> | null, StorageFailure> =>
610 fuma.use(`${tableName}.findFirst`, (db) =>631 fuma.use(`${tableName}.findFirst`, (db) =>
611 asLooseStorageDb(db).findFirst(tableName, options),632 asLooseStorageDb(db).findFirst(tableName, options),
612 ) as Effect.Effect<CoreRow<TName> | null, StorageFailure>,633 ) as Effect.Effect<CoreProjectedRow<TName, TOptions["select"]> | null, StorageFailure>,
613 findMany: <TName extends CoreTableName>(634 findMany: <TName extends CoreTableName, const TOptions extends CoreFindManyOptions<TName>>(
614 tableName: TName,635 tableName: TName,
615 options: CoreFindManyOptions = {},636 options: TOptions = {} as TOptions,
616 ): Effect.Effect<readonly CoreRow<TName>[], StorageFailure> =>637 ): Effect.Effect<readonly CoreProjectedRow<TName, TOptions["select"]>[], StorageFailure> =>
617 fuma.use(`${tableName}.findMany`, (db) =>638 fuma.use(`${tableName}.findMany`, (db) =>
618 asLooseStorageDb(db).findMany(tableName, options),639 asLooseStorageDb(db).findMany(tableName, options),
619 ) as Effect.Effect<readonly CoreRow<TName>[], StorageFailure>,640 ) as Effect.Effect<readonly CoreProjectedRow<TName, TOptions["select"]>[], StorageFailure>,
620 updateMany: <TName extends CoreTableName>(641 updateMany: <TName extends CoreTableName>(
621 tableName: TName,642 tableName: TName,
622 options: {643 options: {
@@ -2300,6 +2321,9 @@ export const createExecutor = <const TPlugins extends readonly AnyPlugin[] = rea · 1677 unmodified lines
2300 2321
2301 const toolsList = (filter?: ToolListFilter): Effect.Effect<readonly Tool[], StorageFailure> =>2322 const toolsList = (filter?: ToolListFilter): Effect.Effect<readonly Tool[], StorageFailure> =>
2302 Effect.gen(function* () {2323 Effect.gen(function* () {
2324 // Projected: the list surface is metadata (address, description,
2325 // annotations) — loading every tool's input/output schema JSON made
2326 // an unbounded list scale with schema bytes, not tool count.
2303 const rows = yield* core.findMany("tool", {2327 const rows = yield* core.findMany("tool", {
2304 where: (b: AnyCb) =>2328 where: (b: AnyCb) =>
2305 b.and(2329 b.and(
@@ -2311,6 +2335,7 @@ export const createExecutor = <const TPlugins extends readonly AnyPlugin[] = rea · 5 unmodified lines
2311 ? true2335 ? true
2312 : b("connection", "=", String(filter.connection)),2336 : b("connection", "=", String(filter.connection)),
2313 ),2337 ),
2338 select: TOOL_INVOCATION_COLUMNS,
2314 });2339 });
2315 const includeBlocked = filter?.includeBlocked ?? false;2340 const includeBlocked = filter?.includeBlocked ?? false;
2316 const policyRows = yield* core.findMany("tool_policy", {});2341 const policyRows = yield* core.findMany("tool_policy", {});
@@ -2650,7 +2675,7 @@ export const createExecutor = <const TPlugins extends readonly AnyPlugin[] = rea · 333 unmodified lines
2650 2675
2651 const TOOL_SUGGESTION_LIMIT = 5;2676 const TOOL_SUGGESTION_LIMIT = 5;
2652 2677
2653 const toolSuggestions = (rows: readonly ToolRow[]): readonly ToolAddress[] =>2678 const toolSuggestions = (rows: readonly ToolInvocationRow[]): readonly ToolAddress[] =>
2654 rows.map((row) => rowToTool(row).address);2679 rows.map((row) => rowToTool(row).address);
2655 2680
2656 const toolRowsForConnectionWhere = (parsed: ParsedToolAddress) => (b: AnyCb) =>2681 const toolRowsForConnectionWhere = (parsed: ParsedToolAddress) => (b: AnyCb) =>
@@ -2662,7 +2687,7 @@ export const createExecutor = <const TPlugins extends readonly AnyPlugin[] = rea · 5 unmodified lines
2662 2687
2663 const searchToolRowsForConnection = (2688 const searchToolRowsForConnection = (
2664 parsed: ParsedToolAddress,2689 parsed: ParsedToolAddress,
2665 ): Effect.Effect<readonly ToolRow[], StorageFailure> =>2690 ): Effect.Effect<readonly ToolInvocationRow[], StorageFailure> =>
2666 core.findMany("tool", {2691 core.findMany("tool", {
2667 where: (b: AnyCb) =>2692 where: (b: AnyCb) =>
2668 b.and(2693 b.and(
@@ -2674,15 +2699,17 @@ export const createExecutor = <const TPlugins extends readonly AnyPlugin[] = rea · 5 unmodified lines
2674 ),2699 ),
2675 orderBy: ["name", "asc"],2700 orderBy: ["name", "asc"],
2676 limit: TOOL_SUGGESTION_LIMIT,2701 limit: TOOL_SUGGESTION_LIMIT,
2702 select: TOOL_INVOCATION_COLUMNS,
2677 });2703 });
2678 2704
2679 const findToolRowsForConnection = (2705 const findToolRowsForConnection = (
2680 parsed: ParsedToolAddress,2706 parsed: ParsedToolAddress,
2681 ): Effect.Effect<readonly ToolRow[], StorageFailure> =>2707 ): Effect.Effect<readonly ToolInvocationRow[], StorageFailure> =>
2682 core.findMany("tool", {2708 core.findMany("tool", {
2683 where: toolRowsForConnectionWhere(parsed),2709 where: toolRowsForConnectionWhere(parsed),
2684 orderBy: ["name", "asc"],2710 orderBy: ["name", "asc"],
2685 limit: TOOL_SUGGESTION_LIMIT,2711 limit: TOOL_SUGGESTION_LIMIT,
2712 select: TOOL_INVOCATION_COLUMNS,
2686 });2713 });
2687 2714
2688 const execute = (2715 const execute = (
@@ -2743,7 +2770,9 @@ export const createExecutor = <const TPlugins extends readonly AnyPlugin[] = rea · 54 unmodified lines
2743 return yield* new ToolNotFoundError({ address });2770 return yield* new ToolNotFoundError({ address });
2744 }2771 }
2745 2772
2746 // Find the tool row.2773 // Find the tool row — projected: invoke needs routing/policy fields
2774 // only, never the multi-KB input/output schema JSON (`tools.schema`
2775 // is the schema-bearing surface).
2747 const row = yield* core.findFirst("tool", {2776 const row = yield* core.findFirst("tool", {
2748 where: (b: AnyCb) =>2777 where: (b: AnyCb) =>
2749 b.and(2778 b.and(
@@ -2752,6 +2781,7 @@ export const createExecutor = <const TPlugins extends readonly AnyPlugin[] = rea · 2 unmodified lines
2752 b("connection", "=", String(parsed.connection)),2781 b("connection", "=", String(parsed.connection)),
2753 b("name", "=", String(parsed.tool)),2782 b("name", "=", String(parsed.tool)),
2754 ),2783 ),
2784 select: TOOL_INVOCATION_COLUMNS,
2755 });2785 });
2756 if (!row) {2786 if (!row) {
2757 const searchMatches = yield* searchToolRowsForConnection(parsed);2787 const searchMatches = yield* searchToolRowsForConnection(parsed);
packages/core/sdk/src/index.ts+1−0
@@ -122,6 +122,7 @@ export { · 121 unmodified lines
122 type OAuthClientRow,122 type OAuthClientRow,
123 type OAuthSessionRow,123 type OAuthSessionRow,
124 type ToolRow,124 type ToolRow,
125 type ToolInvocationRow,
125 type DefinitionRow,126 type DefinitionRow,
126 type ToolPolicyRow,127 type ToolPolicyRow,
127 type PluginStorageRow,128 type PluginStorageRow,
packages/core/sdk/src/plugin.ts+3−3
@@ -14,7 +14,7 @@ import type { · 13 unmodified lines
14 IntegrationDisplayDescriptor,14 IntegrationDisplayDescriptor,
15 RegisterIntegrationInput,15 RegisterIntegrationInput,
16} from "./integration";16} from "./integration";
17import type { ToolRow } from "./core-schema";17import type { ToolInvocationRow } from "./core-schema";
18import type {18import type {
19 AuthTemplateSlug,19 AuthTemplateSlug,
20 ConnectionName,20 ConnectionName,
@@ -339,7 +339,7 @@ export interface InvokeToolInput<TStore = unknown> { · 318 unmodified lines
339 readonly ctx: PluginCtx<TStore>;339 readonly ctx: PluginCtx<TStore>;
340 /** Already-loaded per-connection tool row (carries integration, connection,340 /** Already-loaded per-connection tool row (carries integration, connection,
341 * owner, name, schemas). */341 * owner, name, schemas). */
342 readonly toolRow: ToolRow;342 readonly toolRow: ToolInvocationRow;
343 /** The resolved credential to apply to the outbound request. */343 /** The resolved credential to apply to the outbound request. */
344 readonly credential: ToolInvocationCredential;344 readonly credential: ToolInvocationCredential;
345 readonly args: unknown;345 readonly args: unknown;
@@ -460,7 +460,7 @@ export interface PluginSpec< · 114 unmodified lines
460 readonly ctx: PluginCtx<TStore>;460 readonly ctx: PluginCtx<TStore>;
461 readonly integration: IntegrationSlug;461 readonly integration: IntegrationSlug;
462 readonly connection: ConnectionName;462 readonly connection: ConnectionName;
463 readonly toolRows: readonly ToolRow[];463 readonly toolRows: readonly ToolInvocationRow[];
464 }) => Effect.Effect<Record<string, ToolAnnotations>, unknown>;464 }) => Effect.Effect<Record<string, ToolAnnotations>, unknown>;
465 465
466 /** Plugin-side cleanup when a connection is removed. */466 /** Plugin-side cleanup when a connection is removed. */
packages/plugins/openapi/src/sdk/non-json-body.test.ts+5−4
@@ -297,10 +297,11 @@ describe("OpenAPI non-JSON request body dispatch", () => { · 296 unmodified lines
297 baseUrl: "https://example.com",297 baseUrl: "https://example.com",
298 });298 });
299 299
300 const tools = yield* executor.tools.list();300 // `tools.schema` is the schema-bearing surface — `tools.list` is
301 const submit = tools.find((t) => String(t.address) === String(conn.address("body.submit")));301 // metadata-only (the hot path projects the schema columns away).
302 expect(submit).toBeDefined();302 const view = yield* executor.tools.schema(conn.address("body.submit"));
303 const schema = submit!.inputSchema as {303 expect(view).not.toBeNull();
304 const schema = view!.inputSchema as {
304 properties?: {305 properties?: {
305 contentType?: { enum?: string[]; default?: string };306 contentType?: { enum?: string[]; default?: string };
306 };307 };
packages/plugins/openapi/src/sdk/tool-row-projection.test.ts+121−0
@@ -0,0 +1,121 @@
1// ---------------------------------------------------------------------------
2// Tool-row projection coverage. The invoke and list hot paths select away the
3// heavy input_schema/output_schema JSON (TOOL_INVOCATION_COLUMNS) — a tool row
4// is ~KBs of schemas, but routing/policy needs only the names. These tests pin
5// the contract through a real dynamic integration:
6// - tools.list returns metadata without the schemas,
7// - invoke works end-to-end off the projected row,
8// - tools.schema (describe) still serves the full schemas.
9// ---------------------------------------------------------------------------
10
11import { describe, expect, it } from "@effect/vitest";
12import { Effect, Schema } from "effect";
13import { FetchHttpClient, HttpServerRequest } from "effect/unstable/http";
14import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
15
16import {
17 createExecutor,
18 AuthTemplateSlug,
19 ConnectionName,
20 IntegrationSlug,
21 ToolAddress,
22} from "@executor-js/sdk";
23import { makeTestConfig, memoryCredentialsPlugin } from "@executor-js/sdk/testing";
24import { variable } from "@executor-js/sdk/http-auth";
25
26import { openApiPlugin } from "./plugin";
27import { serveOpenApiHttpApiTestServer, unwrapInvocation } from "../testing";
28
29const testPlugins = (httpClientLayer = FetchHttpClient.layer) =>
30 [openApiPlugin({ httpClientLayer }), memoryCredentialsPlugin()] as const;
31
32const EchoHeaders = Schema.Struct({
33 "x-api-key": Schema.optional(Schema.String),
34});
35
36const EchoGroup = HttpApiGroup.make("items").add(
37 HttpApiEndpoint.get("echoHeaders", "/echo-headers", { success: EchoHeaders }),
38);
39const TestApi = HttpApi.make("testApi").add(EchoGroup);
40
41const EchoGroupLive = HttpApiBuilder.group(TestApi, "items", (handlers) =>
42 handlers.handle("echoHeaders", () =>
43 Effect.gen(function* () {
44 const req = yield* HttpServerRequest.HttpServerRequest;
45 return EchoHeaders.make({ "x-api-key": req.headers["x-api-key"] });
46 }),
47 ),
48);
49
50const apiKeyTemplate = {
51 slug: AuthTemplateSlug.make("apiKey"),
52 type: "apiKey" as const,
53 headers: { "x-api-key": [variable("token")] },
54};
55
56const setup = Effect.gen(function* () {
57 const server = yield* serveOpenApiHttpApiTestServer({
58 api: TestApi,
59 handlersLayer: EchoGroupLive,
60 });
61 const executor = yield* createExecutor(makeTestConfig({ plugins: testPlugins() }));
62 yield* executor.openapi.addSpec({
63 spec: { kind: "blob", value: server.specJson },
64 slug: "proj_api",
65 baseUrl: server.baseUrl,
66 authenticationTemplate: [apiKeyTemplate],
67 });
68 yield* executor.connections.create({
69 owner: "org",
70 name: ConnectionName.make("main"),
71 integration: IntegrationSlug.make("proj_api"),
72 template: AuthTemplateSlug.make("apiKey"),
73 value: "secret-key-123",
74 });
75 return executor;
76});
77
78const TOOL_ADDRESS = ToolAddress.make("tools.proj_api.org.main.items.echoHeaders");
79
80describe("tool-row projection on hot paths", () => {
81 it.effect("tools.list returns metadata without loading the schema columns", () =>
82 Effect.scoped(
83 Effect.gen(function* () {
84 const executor = yield* setup;
85 const tools = yield* executor.tools.list({
86 integration: IntegrationSlug.make("proj_api"),
87 });
88 const tool = tools.find((entry) => entry.address === TOOL_ADDRESS);
89 expect(tool).toBeDefined();
90 expect(tool!.description.length).toBeGreaterThan(0);
91 // The list surface is metadata-only: the projected query never loads
92 // input/output schema JSON, so the Tool carries none.
93 expect(tool!.inputSchema).toBeUndefined();
94 expect(tool!.outputSchema).toBeUndefined();
95 }),
96 ),
97 );
98
99 it.effect("invoke routes and executes off the projected row", () =>
100 Effect.scoped(
101 Effect.gen(function* () {
102 const executor = yield* setup;
103 const result = unwrapInvocation(yield* executor.execute(TOOL_ADDRESS, {})).data as {
104 "x-api-key"?: string;
105 };
106 expect(result["x-api-key"]).toBe("secret-key-123");
107 }),
108 ),
109 );
110
111 it.effect("tools.schema still serves the full schemas", () =>
112 Effect.scoped(
113 Effect.gen(function* () {
114 const executor = yield* setup;
115 const schema = yield* executor.tools.schema(TOOL_ADDRESS);
116 expect(schema).not.toBeNull();
117 expect(schema!.outputSchema).toBeDefined();
118 }),
119 ),
120 );
121});

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t