[tyffical]

Motivation

• APPS-2958: a framed app's backend call times out after 2 minutes without a reply, and the parent's consent dialog can stay open longer than that.
• The parent needs a way to say "still working on this call" without being able to hold a call forever.
• Stack, merged bottom-up:
  1. [APPS-2947 Add: return connection IDs from debugBundle and attach the bundle to framed backend calls]([APPS-2947] Add: return connection IDs from debugBundle and attach the bundle to framed backend calls #566)
  2. [APPS-2947 Fix: fail the build on connection IDs read from objects that calls or aliases write to]([APPS-2947] Fix: fail the build on connection IDs read from objects that calls or aliases write to #619)
  3. [APPS-2958 Add: list each backend function's action calls in the debugBundle response]([APPS-2958] Add: list each backend function's action calls in the debugBundle response #607)
  4. [APPS-2958 Add: list each action call's static inputs in the debugBundle response]([APPS-2958] Add: list each action call's static inputs in the debugBundle response #610)
  5. this PR

Architecture

sequenceDiagram
    participant F as Frame (app)
    participant P as Parent page
    F->>P: app-builder:run-query, requestId
    Note over F: 2-minute wait and 60-minute cap start
    P->>F: app-builder:run-query:keepalive, same requestId
    Note over F: 2-minute wait restarts, cap unchanged
    P->>F: app-builder:run-query:response, same requestId
    Note over F: call settles, timers cleared

Loading

• A keepalive counts only from the recipient a response would be accepted from, and only for the pending requestId.
• POSTMESSAGE_MAX_WAIT_MS (60 minutes) is a safety net for a parent that never answers, not a deadline for the user. Both limits are wall-clock deadlines, so time the machine spends asleep counts toward them.

Changes

7 changes across protocol.ts, the postMessage transport, the dev client, test helpers and the README

What changed	File
Add the app-builder:run-query:keepalive message type	packages/plugins/apps/src/backend/protocol.ts
Re-arm a pending call's wall-clock timeout on a keepalive from its recipient, capped by POSTMESSAGE_MAX_WAIT_MS	packages/plugins/apps/src/backend/client/transports/post-message-transport/post-message-transport.ts
Add the IframeQueryKeepAlive type	packages/plugins/apps/src/backend/client/transports/post-message-transport/types.ts
Learn the parent's origin from a keepalive, as from a pong or response	packages/plugins/apps/src/backend/client/dev-client/dev-client.ts
Add keepAlive() to the shared fake window	packages/tests/src/_jest/helpers/fakeWindow.ts
Cover re-arm, timeout after the last keepalive, '*' posts, wrong source, wrong origin, unknown id, after reply, sleep, the cap and origin learning	post-message-transport.test.ts, dev-client.test.ts
Document the framed call protocol and the keepalive	packages/plugins/apps/README.md

QA Instructions

• Test URL: https://github.com/DataDog/build-plugins/pull/609/checks (CI on the head)

yarn build:all
# Expected: exit 0 ✅ VERIFIED

yarn test:unit packages/plugins/apps/src/backend/client/transports/post-message-transport/post-message-transport.test.ts
# Expected: Tests: 42 passed, 42 total ✅ VERIFIED

TMPDIR=<a dir under /private/tmp> yarn test:unit packages/plugins/apps/src --testPathIgnorePatterns network-guard
# Expected: Test Suites: 44 passed; Tests: 1027 passed ✅ VERIFIED (macOS needs a TMPDIR outside /var; CI on Linux doesn't)

yarn test:unit packages/plugins/apps/src/vite/network-guard.test.ts
# Expected: Tests: 129 passed, 129 total ✅ VERIFIED (run without TMPDIR set)

yarn lint && yarn typecheck:all && yarn cli integrity
# Expected: all exit 0, integrity leaves no extra changes ✅ VERIFIED

Fail-before

yarn test:unit packages/plugins/apps/src/backend/client/transports/post-message-transport/post-message-transport.test.ts packages/plugins/apps/src/backend/client/dev-client/dev-client.test.ts -t keepalive
# Expected on this head: Tests: 11 passed ✅ VERIFIED
# Expected with post-message-transport.ts and dev-client.ts restored to the parent branch: 7 failed (re-arm, timeout after the last keepalive, '*' posts, both sleep cases, the cap, origin learning), 4 passed (the "ignore" cases) ✅ VERIFIED

• No browser QA: nothing in this repo sends a keepalive yet; the parent page that will send it lives outside this repo.

Blast Radius

• No feature flag. Risk: Low. Only framed backend calls change, and only when the parent sends the new message.
• A parent that never sends a keepalive sees the same 2-minute timeout as before; one that does can keep a call pending for up to 60 minutes.

Out of Scope / Follow-ups

1 item deferred

Item	Status	Next step
Send the keepalive from the parent page while its consent dialog is open	Independent	The parent page's owner adds it, using the README section

Documentation

• Framed backend function calls in the Apps plugin README.

🤖 Generated with Claude Code

[datadog-prod-us1-5]

🎉 All green!

🧪 All tests passed
❄️ No new flaky tests detected

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 95492e6 | Docs | View more details | Give us feedback!}