[APPS] Add backend function connection support by sdkennedy2 · Pull Request #331 · DataDog/build-plugins

sdkennedy2 · 2026-04-27T21:37:11Z

Motivation

High Code App backend functions today fail at runtime when they call an action that requires a connectionId (e.g. @datadog/action-catalog/openai/openai#chatCompletion). The Action Platform server rejects the call with Access denied for connection {uuid}. Add it to the allowed list in the step configuration. because the build plugin never tells the server which connections each function is allowed to use.

This PR implements the Backend Function Connections RFC, which chose a single-file approach: customers maintain a centralized connections.ts at the project root listing every connection their app uses, and the build plugin reads it once at build time to feed both the production upload manifest and the dev-preview request body.

CLI tooling and the ESLint rule from the RFC's Future Enhancements section are intentionally out of scope.

Changes

Customer-facing surface

Customers add a connections.ts (or .tsx / .js / .jsx) at the project root. Either CONNECTIONS (uppercase) or connections (lowercase) is accepted as the export name:

// connections.ts
export const CONNECTIONS = {
    OPEN_AI: '9e51df63-7cba-4067-a1fc-a156195074e8',
    SLACK:   '321d6080-5c01-4793-be58-475f0f20e801',
} as const;

Backend functions reference connection IDs as before (literal UUIDs or via CONNECTIONS.OPEN_AI once they import it). On npm run build, the plugin emits a manifest.json at the root of the upload ZIP with the per-function allowed connection IDs nested under backend.functions, keyed by encoded query name. Every backend function key gets the same allowedConnectionIds array (the union from connections.ts). The server-side actions runtime supports per-function distinct lists, but the RFC explicitly chose the flat union.

{
  "backend": {
    "functions": {
      "631339bbf278cb23b10f1118572d0e3d21166de9e4363c6941d055c9f1b19ea1.helloBackend": {
        "allowedConnectionIds": [
          "321d6080-5c01-4793-be58-475f0f20e801",
          "9e51df63-7cba-4067-a1fc-a156195074e8"
        ]
      }
    }
  }
}

For dev preview, the same list is forwarded inside inputs.allowedConnectionIds of the /api/v2/app-builder/queries/preview-async request body, matching the action shape the server expects.

QA Instructions

End-to-end against a scaffolded high-code-app (e.g. ~/dd/web-ui/test-action-catalog-app):

No connections file, build path — remove any connections.ts, run npm run build with logLevel: 'debug'. Expect manifest.json at the root of the upload ZIP with backend.functions[<key>].allowedConnectionIds: [] for every function.
With connections file, build path — add connections.ts exporting two UUIDs, npm run build, inspect the assembled ZIP — root manifest.json should contain every backend-function key under backend.functions, each with both UUIDs in allowedConnectionIds.
Dev preview — with DD_API_KEY / DD_APP_KEY set and a connections.ts containing the OpenAI UUID, add a backend function calling chatCompletionAction({ ..., connectionId: '...' }). npm run dev, click the action — request should succeed (no Access denied for connection ...). Edit connections.ts to remove the UUID, re-trigger — should fail with the expected denial. Verifies handleHotUpdate-driven re-extraction.
Lowercase variant — rename the export to export const connections = { ... }, repeat steps 2–3. Behavior should be identical.
Strict failure modes — OPEN_AI: process.env.OPEN_AI_ID → npm run build fails with a framed error pointing at the offending node. default export form → fails with connections file must define "export const CONNECTIONS" (or "connections") = { ... }.
Unit tests — yarn test:unit packages/plugins/apps (171 tests pass, including 26 extractor tests covering both export-name variants, buildStart/handleHotUpdate test groups, and a dev-server allowedConnectionIds assertion).
E2E tests — yarn test:e2e packages/tests/src/e2e/appsPlugin (60 tests pass, including the new root manifest.json shape assertion).

Blast Radius

Only affects customers building high-code apps (@datadog/vite-plugin with apps.enable). Other bundlers and other plugin features are untouched.
Strict failure mode: unresolvable values inside connections.ts now fail the build where they previously didn't. Customers without a connections.ts see no change — the manifest is emitted with empty allowedConnectionIds arrays, matching pre-existing behavior (no connection-using actions allowed).
The dev preview now sends allowedConnectionIds inside the inputs field of the preview-async request body. This is additive — empty list means same behavior as today.
Shipping path: this is the first PR implementing the RFC. CLI helper and ESLint rule are deferred to follow-ups per RFC Future Enhancements.

Documentation

sdkennedy2 · 2026-04-27T21:37:28Z

[APPS] Add @datadog/eslint-plugin-apps with valid-connections-file rule #332
[APPS] Add backend function connection support #331 👈 (View in Graphite)
master

This stack of pull requests is managed by Graphite. Learn more about stacking.

sdkennedy2 · 2026-04-27T21:38:28Z

@codex review
@cursor review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4e3230b4ae

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

sdkennedy2 · 2026-04-28T14:25:36Z

@codex review
@cursor review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4c0359d4fc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-04-28T14:34:03Z

+            log.debug(`Refreshed connection IDs from ${connectionsPath} (${connectionIds.length})`);
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            log.error(`Failed to refresh connection IDs: ${message}`);


Clear stale connection IDs after failed HMR refresh

When connections.ts has already loaded IDs and a later edit makes server.transformRequest/extraction fail, this catch only logs the error while connectionRegistry keeps the previous array. The dev middleware calls getConnectionIds() on each /__dd/executeAction, so previews keep sending removed connection IDs until another successful refresh or a server restart; because these IDs are an allowlist, a failed refresh should clear or block the registry instead of reusing stale permissions.

Useful? React with 👍 / 👎.

sdkennedy2 · 2026-04-28T16:29:47Z

@codex review
@cursor review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1c34e58376

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

sdkennedy2 · 2026-04-28T17:10:49Z

@codex review

…ward allowedConnectionIds to dev preview

…nnections.ts

…s validation - buildStart now uses server.transformRequest in dev (vite serve), where this.load returns a ModuleInfo proxy whose `code` getter throws. server is captured via configureServer, which fires before buildStart in dev. - buildStart logs the framed [connections] error before re-throwing so it survives any masking by downstream closeBundle errors (e.g. error-tracking sourcemaps' "No output files found"). - extractConnectionIds now derives line:col from node.start byte offsets (which SWC produces) against the source text. Previously the loc?.start branch was dead — rollup's parser doesn't emit ESTree loc info.

…pdated RFC

…ction errors

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8ba24f1659

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

sarenji

Some thoughts

sarenji · 2026-04-28T20:38:09Z

+    test('Should throw when both "connections" and "CONNECTIONS" are exported', () => {
+        const ast = program([
+            exportConnections([stringProperty('A', 'uuid-1')], 'connections'),
+            exportConnections([stringProperty('B', 'uuid-2')], 'CONNECTIONS'),
+        ]);
+        expect(() => extractConnectionIds(ast, filePath, '')).toThrow(
+            'multiple top-level "export const CONNECTIONS" (or "connections") declarations are not allowed',
+        );
+    });


Out of curIosity, why should we support both cases? Do we need to, or can we pick one?

Thats fair pushback. I just thought it was an easy foot gun to make. I plan on adding a couple eslint rules perhaps we standardize on the uppercase version and we can avoid the footgun with linting.

sarenji · 2026-04-28T20:39:05Z

+                {
+                    type: 'SpreadElement',
+                    argument: { type: 'Identifier', name: 'other' },
+                } as SpreadElement,


Does satisfies work here in place of as?

sarenji · 2026-04-28T20:43:39Z

+    // surfaces immediately.
+    describe('framed source location from parseAst', () => {
+        test('Should include line:col when value is not a string literal', async () => {
+            const { parseAst } = await import('rollup/parseAst');


Why is this dynamically imported? Also why rollup's AST parser specifically? I feel like something should expose the parser somewhere that we can use instead of doing this.

sarenji · 2026-04-28T20:50:35Z

+        const middleware = createDevServerMiddleware({
+            viteBuild: mockViteBuild,
+            getBackendFunctions: () => mockFunctions,
+            getConnectionIds: () => [],
+            auth: mockAuth,
+            projectRoot: '/project',
+            log: mockLog,
+        });


Nice, this is a much better interface

sarenji · 2026-04-28T20:53:14Z

+            const inputs = (
+                capturedBody as {
+                    data: {
+                        attributes: { query: { properties: { spec: { inputs: unknown } } } };
+                    };
+                }
+            ).data.attributes.query.properties.spec.inputs as {
+                allowedConnectionIds: string[];
+            };


This is an awkward construction especially when capturedBody is set to unknown and inputs is also set to unknown

That is wild. Claude wrote that. I glossed over the tests, I usually don't invest too much resources in unit test coverage during the design partner phase since nothing is really set in stone and things are likely to change.

This line is pretty egregious though haha. Happy to fix it.

sarenji · 2026-04-28T20:55:24Z

-/**
- * Returns the Vite-specific plugin hooks for the apps plugin.
- *
- * Production (closeBundle): builds backend functions (if any) then uploads
- * all assets sequentially.
- *
- * Dev (configureServer): registers middleware for local backend function
- * testing when auth credentials are available.
- */


Please restore this comment

I actually intentionally removed it because I thought it was weird describing all of the inner functions at the top (claude wanted to add even more to it as the complexity of the plugin grew), but it could be useful to differentiate the production versus dev. I'm not particularly opinionated. I can add it back.

sarenji · 2026-04-28T20:58:49Z

There's a lot of mocking and extracting in the new helper functions at the top... is there a way to simplify without faking everything? The more mocks/fakes there are, the less confidence I have in the code

I wonder if we should just exclude index.ts from unit tests and rely on the e2e test. This file mostly just glues everything together and it might just be better to verify everything works end to end.

We could in a later PR just refactor index.ts and pull out distinct pieces and create unit tests for them directly for example:

Upload function

Registry functions

etc

sarenji · 2026-04-28T21:13:46Z

+        );
+        expect(Object.keys(manifest.backend.functions).sort()).toEqual(expectedKeys.sort());
+        for (const entry of Object.values(manifest.backend.functions)) {
+            expect(Array.isArray(entry.allowedConnectionIds)).toBe(true);


Are we able to test the values of the array as well, or are we satisfied with an Array.isArray check?

… assertion

yoannmoinet

Overall looks good to me.
Just a nit on some error handling that can be misleading.

yoannmoinet · 2026-04-30T14:08:06Z

+        } catch {
+            // not found at this extension — try the next.
+        }


This will swallow any errors, not just the "not found" errors.
Maybe a specific gate of ENOENT errors only would be necessary.
Unless we're ok with this.

sdkennedy2 · 2026-05-04T14:47:03Z

@codex review
@cursor review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c605f1893d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-05-04T14:51:45Z

+                if (filePath) {
+                    this.addWatchFile(filePath);
+                }


Watch for newly added connection files

In vite build --watch this only registers the selected file when one already exists, so a watch session that starts without connections.* will never rerun when the developer later adds connections.ts/.js, and a session that starts with a lower-priority file will not notice a newly added higher-priority one. Because buildStart is the only production path that refreshes connectionRegistry, the uploaded manifest keeps an empty or stale allowedConnectionIds list until the process is restarted.

Useful? React with 👍 / 👎.

sdkennedy2 changed the title ~~[APPS] Add connections.ts support: emit backend/manifest.json and forward allowedConnectionIds to dev preview~~ [APPS] Add connections.ts support — emit backend/manifest.json and forward allowedConnectionIds to dev preview Apr 27, 2026

chatgpt-codex-connector Bot reviewed Apr 27, 2026

View reviewed changes

Comment thread packages/plugins/apps/src/vite/dev-server.ts

chatgpt-codex-connector Bot reviewed Apr 28, 2026

View reviewed changes

Comment thread packages/plugins/apps/src/vite/index.ts Outdated

sdkennedy2 changed the title ~~[APPS] Add connections.ts support — emit backend/manifest.json and forward allowedConnectionIds to dev preview~~ [APPS] Add backend function connection support Apr 28, 2026

sdkennedy2 changed the title ~~[APPS] Add backend function connection support~~ [APPS] Add connections.ts support — emit manifest.json and forward allowedConnectionIds to dev preview Apr 28, 2026

sdkennedy2 force-pushed the sdkennedy2/apps-emit-connections-manifest branch from 1c34e58 to ce1106b Compare April 28, 2026 16:42

sdkennedy2 added 7 commits April 28, 2026 13:11

[APPS] Add connections.ts support: emit backend/manifest.json and for…

513da3c

…ward allowedConnectionIds to dev preview

Move buildStart into vite sub-plugin to drop unsafe cast on this.load

808fd00

Trim verbose comments in apps plugin entry and vite hooks

ef8ff68

Accept either 'connections' or 'CONNECTIONS' as the export name in co…

5bd5aef

…nnections.ts

Move manifest.json to zip root and nest under backend.functions per u…

cbd16e2

…pdated RFC

Refresh connections registry via server.watcher; fail-closed on extra…

e7ee68b

…ction errors

sdkennedy2 force-pushed the sdkennedy2/apps-emit-connections-manifest branch from 8ba24f1 to e7ee68b Compare April 28, 2026 17:11

sdkennedy2 changed the title ~~[APPS] Add connections.ts support — emit manifest.json and forward allowedConnectionIds to dev preview~~ [APPS] Add backend function connection support Apr 28, 2026

chatgpt-codex-connector Bot reviewed Apr 28, 2026

View reviewed changes

Comment thread packages/plugins/apps/src/index.ts Outdated

Comment thread packages/plugins/apps/src/vite/index.ts

sdkennedy2 added 2 commits April 28, 2026 13:25

Inline describeNode helper and drop unused Expression import

2b56c08

Defer reading buildRoot in connections registry until configResolved

3173652

sdkennedy2 marked this pull request as ready for review April 28, 2026 17:39

sdkennedy2 requested a review from yoannmoinet as a code owner April 28, 2026 17:39

sarenji reviewed Apr 28, 2026

View reviewed changes

sdkennedy2 mentioned this pull request Apr 29, 2026

[APPS] Add @datadog/eslint-plugin-apps with valid-connections-file rule #332

Draft

Tighten connections export name to CONNECTIONS only; add E2E manifest…

b64302d

… assertion

sdkennedy2 force-pushed the sdkennedy2/apps-emit-connections-manifest branch from 6f12a4e to b64302d Compare April 30, 2026 13:53

yoannmoinet approved these changes Apr 30, 2026

View reviewed changes

Use injected Vite parser for connection IDs

c605f18

chatgpt-codex-connector Bot reviewed May 4, 2026

View reviewed changes

Conversation

sdkennedy2 commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Changes

Customer-facing surface

QA Instructions

Blast Radius

Documentation

Uh oh!

sdkennedy2 commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sdkennedy2 commented Apr 27, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

sdkennedy2 commented Apr 28, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

sdkennedy2 commented Apr 28, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

sdkennedy2 commented Apr 28, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

sarenji left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yoannmoinet left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sdkennedy2 commented May 4, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

sdkennedy2 commented Apr 27, 2026 •

edited

Loading

sdkennedy2 commented Apr 27, 2026 •

edited

Loading