Store OpenAPI specs and GraphQL snapshots in the blob seam, not integration.config

RhysSullivan · RhysSullivan · commit 6e8705d23e8a · 2026-06-11T19:50:54.000-07:00
integration.config inlined the full resolved OpenAPI spec text (and any
GraphQL introspection snapshot), so every integrations list loaded
multi-MB build artifacts it immediately discarded — in production the
worst tenant paid 48 MB per list call and /api/integrations p95 ran ~8s,
with ~97% of slow traces inside the single integration.findMany span.

The resolved text now lives in the plugin blob store, content-addressed
(spec/&lt;sha256&gt;, introspection/&lt;sha256&gt;) and org-owned; the config keeps
only the hash. Day-to-day reads (list, invoke) touch nothing but the
small relational rows: invoke still runs off stored operation bindings,
and its store-miss fallback recompiles from the blob — the only
invoke-path spec read left.

ResolveToolsInput now carries the plugin's typed store so resolveTools
can load the blob (it had no ctx). Legacy rows that still inline the
text decode and resolve unchanged through a shared loader until the
backfill rewrites them. Blobs are never deleted on integration removal:
content addressing means another integration in the tenant may share
the hash, and re-puts are idempotent.

The openapi getConfig endpoint also stops serving the spec text — no
client read it, and it shipped megabytes to the configure UI.
diff --git a/packages/core/sdk/src/blob.ts b/packages/core/sdk/src/blob.ts
@@ -157,6 +157,17 @@ export const makeInMemoryBlobStore = (): BlobStore => {
   };
 };
 
+/** Hex SHA-256 of a UTF-8 string — the content-address key plugins use for
+ *  write-once blobs (`put(key(hash), …)` is then idempotent and orphaned
+ *  writes are harmless). Web Crypto, so it runs on Workers/Bun/Node alike. */
+export const sha256Hex = (text: string): Effect.Effect<string> =>
+  Effect.promise(async () => {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join(
+      "",
+    );
+  });
+
 const blobId = (namespace: string, key: string): string => JSON.stringify([namespace, key]);
 
 type BlobRow = {
diff --git a/packages/core/sdk/src/executor.ts b/packages/core/sdk/src/executor.ts
@@ -1834,6 +1834,7 @@ export const createExecutor = <const TPlugins extends readonly AnyPlugin[] = rea
             config: decodeJsonColumn(integrationRow.config),
             connection: ref,
             template: existingRow ? AuthTemplateSlug.make(existingRow.template) : null,
+            storage: runtime.storage,
             getValue: () => resolveConnectionValueByRef(ref),
             getValues: () => resolveConnectionValuesByRef(ref),
           })
diff --git a/packages/core/sdk/src/index.ts b/packages/core/sdk/src/index.ts
@@ -174,6 +174,7 @@ export {
   pluginBlobStore,
   makeInMemoryBlobStore,
   makeFumaBlobStore,
+  sha256Hex,
   type BlobStore,
   type PluginBlobStore,
   type OwnerPartitions,
diff --git a/packages/core/sdk/src/plugin.ts b/packages/core/sdk/src/plugin.ts
@@ -187,11 +187,16 @@ export interface PluginCtx<TStore = unknown> {
 // refresh / oauth.complete; the result is stamped with addresses and persisted.
 // ---------------------------------------------------------------------------
 
-export interface ResolveToolsInput {
+export interface ResolveToolsInput<TStore = unknown> {
   /** The catalog record (public projection) whose connection is being resolved. */
   readonly integration: Integration;
   /** The plugin's stored opaque config for that integration. */
   readonly config: IntegrationConfig;
+  /** The plugin's typed store — the same instance the extension ctx sees.
+   *  Lets spec-derived plugins load build artifacts kept behind the storage
+   *  facades (e.g. a content-addressed spec blob) instead of inlining them
+   *  in `config`. */
+  readonly storage: TStore;
   /** The connection whose tools are being resolved. */
   readonly connection: ConnectionRef;
   /** Which of the integration's declared auth methods the connection binds
@@ -443,7 +448,7 @@ export interface PluginSpec<
    *  create / refresh / oauth.complete; the result is stamped with addresses
    *  and persisted per-connection. Omit for plugins with no dynamic tools. */
   readonly resolveTools?: (
-    input: ResolveToolsInput,
+    input: ResolveToolsInput<TStore>,
   ) => Effect.Effect<ResolveToolsResult, StorageFailure>;
 
   /** Invoke a dynamic tool. Called when the static-handler map doesn't have the
diff --git a/packages/plugins/graphql/src/sdk/plugin.ts b/packages/plugins/graphql/src/sdk/plugin.ts
@@ -10,6 +10,7 @@ import {
   IntegrationDetectionResult,
   IntegrationSlug,
   mergeAuthTemplates,
+  sha256Hex,
   ToolName,
   ToolResult,
   type AuthMethodDescriptor,
@@ -413,17 +414,32 @@ const introspectHeadersForConnection = (
   return { headers, queryParams };
 };
 
-/** Introspect a config live or from its stored JSON, applying connection auth.
- *  `parseIntrospectionJson` short-circuits the network when a schema snapshot is
- *  present; otherwise this introspects the endpoint with the rendered credential. */
+/** Resolve a config's introspection snapshot text: legacy rows inline it in
+ *  `introspectionJson`; new rows point at the plugin blob store via
+ *  `introspectionHash`. Null when the integration has no snapshot (live
+ *  introspection territory). */
+const loadIntrospectionJson = (
+  storage: GraphqlStore,
+  config: GraphqlIntegrationConfig,
+): Effect.Effect<string | null, StorageFailure> => {
+  if (config.introspectionJson != null) return Effect.succeed(config.introspectionJson);
+  if (config.introspectionHash != null) return storage.getIntrospection(config.introspectionHash);
+  return Effect.succeed(null);
+};
+
+/** Introspect a config live or from its stored snapshot, applying connection
+ *  auth. A non-null `introspectionJson` (loaded via `loadIntrospectionJson`)
+ *  short-circuits the network; otherwise this introspects the endpoint with
+ *  the rendered credential. */
 const introspectForConnection = (
   config: GraphqlIntegrationConfig,
+  introspectionJson: string | null,
   values: Record<string, string | null>,
   templateSlug: AuthTemplateSlug | null,
   httpClientLayer: Layer.Layer<HttpClient.HttpClient>,
 ): Effect.Effect<IntrospectionResult, GraphqlIntrospectionError> => {
-  if (config.introspectionJson) {
-    return parseIntrospectionJson(config.introspectionJson);
+  if (introspectionJson != null) {
+    return parseIntrospectionJson(introspectionJson);
   }
   const auth = introspectHeadersForConnection(config, values, templateSlug);
   return introspect(
@@ -463,13 +479,15 @@ const materializeOperations = (
       Object.assign(queryParams, rendered.queryParams);
     }
 
-    const introspection = config.introspectionJson
-      ? yield* parseIntrospectionJson(config.introspectionJson)
-      : yield* introspect(
-          config.endpoint,
-          Object.keys(headers).length > 0 ? headers : undefined,
-          Object.keys(queryParams).length > 0 ? queryParams : undefined,
-        ).pipe(Effect.provide(httpClientLayer));
+    const introspectionJson = yield* loadIntrospectionJson(ctx.storage, config);
+    const introspection =
+      introspectionJson != null
+        ? yield* parseIntrospectionJson(introspectionJson)
+        : yield* introspect(
+            config.endpoint,
+            Object.keys(headers).length > 0 ? headers : undefined,
+            Object.keys(queryParams).length > 0 ? queryParams : undefined,
+          ).pipe(Effect.provide(httpClientLayer));
 
     const { result } = yield* extract(introspection).pipe(
       Effect.catch(() =>
@@ -577,55 +595,68 @@ const makeGraphqlExtension = (ctx: PluginCtx<GraphqlStore>) => {
     });
 
   const addIntegrationTransaction = (input: GraphqlAddIntegrationInput, slug: IntegrationSlug) =>
-    ctx.transaction(
-      Effect.gen(function* () {
-        const baseConfig = buildConfig(input);
-
-        // No pre-supplied schema → register WITHOUT introspecting. Tools (and
-        // their operation bindings) are produced lazily when a connection is
-        // created (`resolveTools`) / a tool is first invoked (`invokeTool`),
-        // using that connection's credential.
-        if (baseConfig.introspectionJson === undefined) {
-          yield* ctx.core.integrations.register({
+    Effect.gen(function* () {
+      const baseConfig = buildConfig(input);
+
+      // No pre-supplied schema → register WITHOUT introspecting. Tools (and
+      // their operation bindings) are produced lazily when a connection is
+      // created (`resolveTools`) / a tool is first invoked (`invokeTool`),
+      // using that connection's credential.
+      if (baseConfig.introspectionJson === undefined) {
+        yield* ctx.transaction(
+          ctx.core.integrations.register({
             slug,
             description: baseConfig.name,
             config: baseConfig,
             canRemove: true,
             canRefresh: true,
-          });
-          return { slug: String(slug), name: baseConfig.name, toolCount: 0 };
-        }
+          }),
+        );
+        return { slug: String(slug), name: baseConfig.name, toolCount: 0 };
+      }
 
-        // Pre-supplied introspection JSON: parse it offline (no network) and
-        // persist the operation bindings + snapshot so production stays offline.
-        const introspection = yield* parseIntrospectionJson(baseConfig.introspectionJson);
-        const { result } = yield* extract(introspection);
-        const prepared = prepareOperations(result.fields, introspection);
-
-        // Snapshot the resolved schema so tool production never needs a live
-        // HTTP layer (D6: tools are spec-derived and identical per connection).
-        const config = GraphqlIntegrationConfig.make({
-          ...baseConfig,
-          introspectionJson: JSON.stringify({ data: introspection }),
-        });
+      // Pre-supplied introspection JSON: parse it offline (no network) and
+      // persist the operation bindings + snapshot so production stays offline.
+      const introspection = yield* parseIntrospectionJson(baseConfig.introspectionJson);
+      const { result } = yield* extract(introspection);
+      const prepared = prepareOperations(result.fields, introspection);
+
+      // Snapshot the resolved schema so tool production never needs a live
+      // HTTP layer (D6: tools are spec-derived and identical per connection).
+      // The snapshot text goes to the plugin blob store (content-addressed,
+      // written OUTSIDE the transaction — re-puts are idempotent and an
+      // aborted register leaves only an unreferenced blob), and the config
+      // carries only its hash.
+      const snapshotJson = JSON.stringify({ data: introspection });
+      const introspectionHash = yield* sha256Hex(snapshotJson);
+      const { introspectionJson: _inline, ...withoutInline } = baseConfig;
+      const config = GraphqlIntegrationConfig.make({
+        ...withoutInline,
+        introspectionHash,
+      });
 
-        yield* ctx.storage.replaceOperations(String(slug), toStoredOperations(slug, prepared));
+      yield* ctx.storage.putIntrospection(introspectionHash, snapshotJson);
 
-        yield* ctx.core.integrations.register({
-          slug,
-          description: config.name,
-          config,
-          canRemove: true,
-          canRefresh: true,
-        });
+      yield* ctx.transaction(
+        Effect.gen(function* () {
+          yield* ctx.storage.replaceOperations(String(slug), toStoredOperations(slug, prepared));
 
-        return {
-          slug: String(slug),
-          name: config.name,
-          toolCount: prepared.length,
-        };
-      }),
-    );
+          yield* ctx.core.integrations.register({
+            slug,
+            description: config.name,
+            config,
+            canRemove: true,
+            canRefresh: true,
+          });
+        }),
+      );
+
+      return {
+        slug: String(slug),
+        name: config.name,
+        toolCount: prepared.length,
+      };
+    });
 
   const configureIntegration = (slug: string, input: GraphqlConfigureInput) =>
     Effect.gen(function* () {
@@ -649,6 +680,9 @@ const makeGraphqlExtension = (ctx: PluginCtx<GraphqlStore>) => {
         ...(current.introspectionJson !== undefined
           ? { introspectionJson: current.introspectionJson }
           : {}),
+        ...(current.introspectionHash !== undefined
+          ? { introspectionHash: current.introspectionHash }
+          : {}),
         ...((input.headers ?? current.headers) !== undefined
           ? { headers: input.headers ?? current.headers }
           : {}),
@@ -852,26 +886,30 @@ export const graphqlPlugin = definePlugin((options?: GraphqlPluginOptions) => {
     resolveTools: ({
       config,
       template,
+      storage,
       getValues,
     }: {
       readonly config: IntegrationConfig;
       readonly template: AuthTemplateSlug | null;
+      readonly storage: GraphqlStore;
       readonly getValues: () => Effect.Effect<Record<string, string | null>, unknown>;
     }) =>
       Effect.gen(function* () {
         const decoded = yield* decodeGraphqlIntegrationConfig(config).pipe(Effect.option);
         if (Option.isNone(decoded)) return { tools: [] };
         const graphqlConfig = decoded.value;
+        const introspectionJson = yield* loadIntrospectionJson(storage, graphqlConfig);
         // Live introspection (no stored snapshot) needs the connection's
         // credential inputs for auth-required endpoints; resolve them lazily.
         const values =
-          graphqlConfig.introspectionJson === undefined
+          introspectionJson == null
             ? yield* getValues().pipe(
                 Effect.catch(() => Effect.succeed({} as Record<string, string | null>)),
               )
             : ({} as Record<string, string | null>);
         const introspection = yield* introspectForConnection(
           graphqlConfig,
+          introspectionJson,
           values,
           template,
           options?.httpClientLayer ?? httpClientLayerFallback,
diff --git a/packages/plugins/graphql/src/sdk/store.ts b/packages/plugins/graphql/src/sdk/store.ts
@@ -71,6 +71,12 @@ const rowToOperation = (row: PluginStorageEntry): StoredOperation | null => {
   };
 };
 
+/** Blob key for an introspection snapshot's content hash. Content-addressed
+ *  so re-puts are idempotent and identical schemas share one blob per
+ *  partition. */
+export const introspectionBlobKey = (introspectionHash: string): string =>
+  `introspection/${introspectionHash}`;
+
 export interface GraphqlStore {
   /** Replace the stored operation bindings for an integration. */
   readonly replaceOperations: (
@@ -85,9 +91,20 @@ export interface GraphqlStore {
     integration: string,
   ) => Effect.Effect<readonly StoredOperation[], StorageFailure>;
   readonly removeOperations: (integration: string) => Effect.Effect<void, StorageFailure>;
+  /** Persist an introspection JSON snapshot under its content hash. Org-owned
+   *  and content-addressed; never removed on integration removal because
+   *  another integration in the tenant may share the hash. */
+  readonly putIntrospection: (
+    introspectionHash: string,
+    introspectionJson: string,
+  ) => Effect.Effect<void, StorageFailure>;
+  /** Load an introspection snapshot by content hash; null when absent. */
+  readonly getIntrospection: (
+    introspectionHash: string,
+  ) => Effect.Effect<string | null, StorageFailure>;
 }
 
-export const makeDefaultGraphqlStore = ({ pluginStorage }: StorageDeps): GraphqlStore => {
+export const makeDefaultGraphqlStore = ({ pluginStorage, blobs }: StorageDeps): GraphqlStore => {
   const listOperationRows = (integration: string) =>
     pluginStorage
       .list({
@@ -137,5 +154,12 @@ export const makeDefaultGraphqlStore = ({ pluginStorage }: StorageDeps): Graphql
       ),
 
     removeOperations,
+
+    putIntrospection: (introspectionHash, introspectionJson) =>
+      blobs.put(introspectionBlobKey(introspectionHash), introspectionJson, {
+        owner: CATALOG_OWNER,
+      }),
+
+    getIntrospection: (introspectionHash) => blobs.get(introspectionBlobKey(introspectionHash)),
   };
 };
diff --git a/packages/plugins/graphql/src/sdk/types.ts b/packages/plugins/graphql/src/sdk/types.ts
@@ -172,9 +172,13 @@ export const GraphqlIntegrationConfig = Schema.Struct({
   endpoint: Schema.String,
   /** Display name for the integration. */
   name: Schema.String,
-  /** Optional introspection JSON text (when the endpoint doesn't support
-   *  live introspection). */
+  /** Inlined introspection JSON text. Legacy rows only: new snapshots live in
+   *  the plugin blob store and the config carries `introspectionHash` instead,
+   *  so a multi-MB schema never rides along on catalog reads. */
   introspectionJson: Schema.optional(Schema.String),
+  /** Hex SHA-256 of the introspection JSON snapshot — the content address of
+   *  the blob (`introspection/<hash>` in the plugin blob store). */
+  introspectionHash: Schema.optional(Schema.String),
   /** Static headers applied to every request (and to add-time introspection). */
   headers: Schema.optional(Schema.Record(Schema.String, Schema.String)),
   /** Static query parameters applied to every request. */
diff --git a/packages/plugins/openapi/src/api/group.ts b/packages/plugins/openapi/src/api/group.ts
@@ -100,11 +100,12 @@ const IntegrationView = Schema.Struct({
   canRefresh: Schema.Boolean,
 });
 
-// The full opaque integration config, surfaced for the configure UX. Unlike
+// The integration config surfaced for the configure UX. Unlike
 // `IntegrationView` (catalog identity only), this carries the
-// `authenticationTemplate` the configure flow reads/writes.
+// `authenticationTemplate` the configure flow reads/writes. The spec text is
+// deliberately NOT served: it's a multi-MB build artifact in the plugin blob
+// store, and no client reads it (the configure UI only touches the template).
 const OpenApiConfigView = Schema.Struct({
-  spec: Schema.String,
   sourceUrl: Schema.optional(Schema.String),
   googleDiscoveryUrls: Schema.optional(Schema.Array(Schema.String)),
   baseUrl: Schema.optional(Schema.String),
diff --git a/packages/plugins/openapi/src/api/handlers.ts b/packages/plugins/openapi/src/api/handlers.ts
@@ -87,7 +87,6 @@ export const OpenApiHandlers = HttpApiBuilder.group(ExecutorApiWithOpenApi, "ope
           const config = yield* ext.getConfig(params.slug);
           return config
             ? {
-                spec: config.spec,
                 sourceUrl: config.sourceUrl,
                 googleDiscoveryUrls: config.googleDiscoveryUrls
                   ? [...config.googleDiscoveryUrls]
diff --git a/packages/plugins/openapi/src/sdk/config.ts b/packages/plugins/openapi/src/sdk/config.ts
@@ -15,9 +15,13 @@ import type { Authentication } from "./types";
 //
 // In v2 there are NO credential bindings, NO per-source secret slots, and NO
 // StoredSource credential config. The config carries only:
-//   - the OpenAPI spec text (inlined) OR the source URL to (re)fetch from,
+//   - the content hash of the spec blob (legacy rows inline the text instead)
+//     and/or the source URL to (re)fetch from,
 //   - the optional base URL override,
 //   - the auth templates a connection's value is rendered through.
+// The resolved spec text itself lives in the plugin blob store, keyed
+// `spec/<specHash>` — it's a build input for resolveTools/refresh, not data
+// any list/invoke path should pay to load.
 // ---------------------------------------------------------------------------
 
 const OAuthAuthenticationSchema = Schema.Struct({
@@ -31,8 +35,13 @@ const OAuthAuthenticationSchema = Schema.Struct({
 export const AuthenticationSchema = Schema.Union([OAuthAuthenticationSchema, ApiKeyAuthMethod]);
 
 export const OpenApiIntegrationConfigSchema = Schema.Struct({
-  /** Inlined OpenAPI document text (resolved + parsed source of truth). */
-  spec: Schema.String,
+  /** Inlined OpenAPI document text. Legacy rows only: new registrations store
+   *  the resolved text in the plugin blob store and carry `specHash` instead,
+   *  so multi-MB documents never ride along on catalog reads. */
+  spec: Schema.optional(Schema.String),
+  /** Hex SHA-256 of the resolved spec text — the content address of the spec
+   *  blob (`spec/<hash>` in the plugin blob store). */
+  specHash: Schema.optional(Schema.String),
   /** Origin URL the spec was fetched from, when known. Enables refresh. */
   sourceUrl: Schema.optional(Schema.String),
   /** Google Discovery bundle URLs, when the spec came from a Google bundle. */
diff --git a/packages/plugins/openapi/src/sdk/migrate-config.ts b/packages/plugins/openapi/src/sdk/migrate-config.ts
diff --git a/packages/plugins/openapi/src/sdk/plugin.ts b/packages/plugins/openapi/src/sdk/plugin.ts
diff --git a/packages/plugins/openapi/src/sdk/spec-blob.test.ts b/packages/plugins/openapi/src/sdk/spec-blob.test.ts
diff --git a/packages/plugins/openapi/src/sdk/store.ts b/packages/plugins/openapi/src/sdk/store.ts
