feat(external-api): round-trip dashboard containers, tabs, and tile container/tab refs by alex-fedotyev · Pull Request #2201 · hyperdxio/hyperdx

alex-fedotyev · 2026-05-05T20:19:22Z

Summary

PR #2015 added a dashboard organization layer (containers with optional tabs, plus per-tile containerId and tabId) but the v2 external API was not updated to round-trip the new fields. External integrations that build dashboards programmatically had no way to use the new layer.

This wires the full set of fields through CREATE / GET / LIST / UPDATE on /api/v2/dashboards. Dashboards saved without containers round-trip unchanged.

Closes #2150. Follow-up to #2015 (commit 7665fbe).

What's in scope

Dashboard body Zod schema gains containers: DashboardContainer[]? (imported from @hyperdx/common-utils) and the tile schema gains containerId? and tabId?.
convertToExternalDashboard now emits containers (only when at least one is present, so dashboards without the layer round-trip with the field absent).
convertTileToExternalChart and convertToInternalTileConfig propagate containerId and tabId. The legacy series-format translator in externalApi.ts also propagates them so both code paths preserve the fields.
The containers: 1 projection is added to the Mongoose find and findOne calls.
New cross-field validation on the body schema:
- container ids unique within a dashboard
- tab ids unique within a container
- tile containerId resolves to a real container
- tile tabId resolves to a tab inside that container
- tile tabId requires containerId to be set
OpenAPI JSDoc additions for DashboardContainer, DashboardContainerTab, the new tile fields, and the new dashboard field on Dashboard / CreateDashboardRequest / UpdateDashboardRequest. openapi.json regenerated.
A changeset entry.

Out of scope

The legacy type: 'section' discriminator removed in refactor: Unify section/group into single Group with collapsible/bordered options #2015 (commit 7665fbe). Not emitted, not validated against. Legacy documents parse cleanly via Zod's strip-unknown.
Container-level repeat field (future work per refactor: Unify section/group into single Group with collapsible/bordered options #2015 review notes).
The MCP hyperdx_save_dashboard tool is unchanged in this PR. Its inline inputSchema does not yet expose containers, and adding it there is its own follow-up; doing both at once would tangle two surfaces.
Heatmap chart-type round-trip and on-tile onClick are tracked separately.

Tier

The triage classifier marks packages/api/src/routers/external-api/v2/* as critical-path, so this lands as Tier 4 by directory rule, even though the diff is small (~284 prod lines) and additive. Splitting further would separate the body schema, the conversion utilities, and the route wiring from each other and not actually reduce review burden. Happy to break this up if there's a preferred way to slice it.

Test plan

yarn ci:lint (lint + tsc + spectral) on @hyperdx/common-utils, @hyperdx/api, @hyperdx/app
yarn knip (no new unused exports)
Integration: yarn jest dashboards.test.ts -t "Containers and tabs" — all 8 new tests pass
Integration: full yarn jest dashboards.test.ts — 86/86 tests pass (no regressions in old or new format suites)
Integration: yarn jest src/mcp/__tests__/dashboards.test.ts — 19/19 MCP dashboard tests pass (the MCP body schema shares with the external API body schema, so this confirms the new validations don't break the MCP path)
openapi.json regenerated and committed; spectral lint passes

…ontainer/tab refs (#2150) PR #2015 added a dashboard organization layer (containers with optional tabs, tiles join a container via containerId and a tab via tabId) but the v2 external API was not updated to round-trip the new fields. External integrations that build dashboards programmatically had no way to use the new layer. This wires the full set of fields through CREATE / GET / LIST / UPDATE. Dashboards saved without containers round-trip unchanged (Mongoose returns an empty array for missing containers, so the conversion only emits the field when at least one container is present). The body schema validates that: - container ids are unique within the dashboard - tab ids are unique within their container - tile.containerId resolves to a real container - tile.tabId resolves to a tab inside the tile's container - tile.tabId requires tile.containerId to be set Tests cover create + get round-trip, update round-trip with re-homing tiles and dropping a container, optional-field defaults, all five validation rejections, and the no-containers backward-compat case. The conversion utilities also pick up containerId / tabId on the tile itself: convertToInternalTileConfig now extends its pick list (was the specific bug v2 of the plan missed) and the legacy series translator in externalApi.ts also propagates the fields so both code paths preserve them. Refs #2150, follows up on #2015 (7665fbe).

vercel · 2026-05-05T20:19:27Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hyperdx-oss	Ready	Preview, Comment	May 5, 2026 8:50pm

changeset-bot · 2026-05-05T20:19:31Z

🦋 Changeset detected

Latest commit: 6884d0a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@hyperdx/api	Minor
@hyperdx/app	Minor
@hyperdx/otel-collector	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2026-05-05T20:19:39Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hyperdx-oss	Building	Preview, Comment	May 5, 2026 8:19pm

github-actions · 2026-05-05T20:20:03Z

🔴 Tier 4 — Critical

Touches auth, data models, config, tasks, OTel pipeline, ClickHouse, or CI/CD.

Why this tier:

Critical-path files (2):
- packages/api/src/routers/external-api/v2/dashboards.ts
- packages/api/src/routers/external-api/v2/utils/dashboards.ts

Review process: Deep review from a domain expert. Synchronous walkthrough may be required.
SLA: Schedule synchronous review within 2 business days.

Stats

Production files changed: 5
Production lines changed: 288 (+ 361 in test files, excluded from tier calculation)
Branch: alex/HDX-2150-external-api-containers-tabs
Author: alex-fedotyev

To override this classification, remove the review/tier-4 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

github-actions · 2026-05-05T20:21:30Z

PR Review

✅ No critical issues found.

The implementation is clean, additive, and well-tested. A few minor observations:

⚠️ containers: [] persists as empty array in MongoDB → When a PUT sends containers: [] to clear containers, the DB stores [] but reads back as absent (because convertToExternalDashboard only emits the field when length > 0). This is functionally correct from the API perspective but leaves a stale [] in the DB. A $unset when the array is empty would be cleaner, though this is not a bug.
ℹ️ Double iteration over containers in buildDashboardBodySchema → The uniqueness check for container IDs and the tab ID uniqueness check are two separate forEach loops. These could be merged into one pass. Minor efficiency nit, not a correctness issue.
✅ Validation is thorough: unknown containerId, unknown tabId, tabId without containerId, duplicate container IDs, duplicate tab IDs within a container — all covered with tests.
✅ Both code paths handled: the new config-format path (convertTileToExternalChart/convertToInternalTileConfig) and the legacy series-format path (translateExternalChartToTileConfig in externalApi.ts) both propagate containerId/tabId.
✅ Projections updated in both GET / and GET /:id; findOneAndUpdate in PUT uses { new: true } without a restricting projection so the returned document includes containers.
✅ Test coverage: 8 integration tests covering round-trips, backward compat, and all validation rejection cases. 86/86 existing tests unaffected.

Empty-string values previously passed per-field validation and only hit the cross-field check (no container has id ''). Adding .min(1) matches the shared DashboardContainerSchema pattern and surfaces a field-level error instead.

github-actions · 2026-05-05T20:24:20Z

E2E Test Results

✅ All tests passed • 159 passed • 3 skipped • 1168s

Status	Count
✅ Passed	159
❌ Failed	0
⚠️ Flaky	4
⏭️ Skipped	3

Tests ran across 4 shards in parallel.

View full report →

After reading notes/principles/external-api-audit.md and walking through the UI surface (useDashboardContainers.tsx, DashboardContainer.tsx, GroupTabBar.tsx), three gaps were caught that the initial implementation missed. - OpenAPI parity: TileBase.containerId / tabId now declare minLength: 1 to match the Zod schema's z.string().min(1).optional(). The Zod fix landed in the previous commit but the OpenAPI didn't pick up the constraint until JSDoc was updated and openapi.json regenerated. - Test gap: explicit empty containers: [] now has its own round-trip test. The conversion normalizes [] back to absent on read (the existing length-guard makes this work), but the behavior wasn't asserted. - Test gap: tile.containerId or tile.tabId set to an empty string is now explicitly rejected. Previously this would have failed cross-field validation only because no real container has id "", not because the tile-level rule fired. UI invariants the API stays permissive about (auto-fixed by the UI rather than rejected) are documented in the per-feature code map under notes/repo-conventions/hyperdx/dashboards-containers-tabs.md in the workspace.

github-actions Bot added the review/tier-4 Critical — deep review + domain expert sign-off label May 5, 2026

vercel Bot deployed to Preview May 5, 2026 20:22 View deployment

vercel Bot deployed to Preview May 5, 2026 20:26 View deployment

vercel Bot deployed to Preview May 5, 2026 20:50 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(external-api): round-trip dashboard containers, tabs, and tile container/tab refs#2201

feat(external-api): round-trip dashboard containers, tabs, and tile container/tab refs#2201
alex-fedotyev wants to merge 3 commits intomainfrom
alex/HDX-2150-external-api-containers-tabs

alex-fedotyev commented May 5, 2026

Uh oh!

vercel Bot commented May 5, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented May 5, 2026 •

edited

Loading

Uh oh!

vercel Bot commented May 5, 2026

Uh oh!

github-actions Bot commented May 5, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 5, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 5, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

alex-fedotyev commented May 5, 2026

Summary

What's in scope

Out of scope

Tier

Test plan

Uh oh!

vercel Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel Bot commented May 5, 2026

Uh oh!

github-actions Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔴 Tier 4 — Critical

Uh oh!

github-actions Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review

Uh oh!

github-actions Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

E2E Test Results

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

vercel Bot commented May 5, 2026 •

edited

Loading

changeset-bot Bot commented May 5, 2026 •

edited

Loading

github-actions Bot commented May 5, 2026 •

edited

Loading

github-actions Bot commented May 5, 2026 •

edited

Loading

github-actions Bot commented May 5, 2026 •

edited

Loading