Skip to content

feat: more global vars for dashboard links - #3726

Open
knudtty wants to merge 2 commits into
mainfrom
aaron/dashboard-link-globals
Open

knudtty wants to merge 2 commits into
mainfrom
aaron/dashboard-link-globals

Conversation

@knudtty

@knudtty knudtty commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds more dashboard globals such as time ranges and $_all_variables to allow better linking between dashboards.

Screenshots or video

export-1795040481503.mp4

References

  • Linear Issue: Closes HDX-5542

@knudtty
knudtty requested a review from a team as a code owner November 18, 2026 22:24
@vercel

vercel Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
hyperdx-oss Ready Ready Preview Nov 19, 2026 8:16pm UTC
hyperdx-storybook Ready Ready Preview Nov 19, 2026 8:16pm UTC

Request Review

@changeset-bot

changeset-bot Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: d822782

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

This PR includes changesets to release 4 packages
Name Type
@hyperdx/common-utils Patch
@hyperdx/app Patch
@hyperdx/api Patch
@hyperdx/otel-collector Patch

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

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

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

🔴 Tier 4 — Critical

Touches authentication, tenancy data models, the public API or shipped database config — or substantially changes the query rendering engine, background tasks, the OTel pipeline, image build, or release CI.

Why this tier:

  • Critical-path files (1) — tenancy, public API, or shipped database config:
    • packages/api/src/routers/external-api/v2/dashboards.ts
  • Cross-layer change: touches frontend (packages/app) + backend (packages/api) + shared utils (packages/common-utils)

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: 15
  • Production lines changed: 692 (+ 266 in test files, excluded from tier calculation)
  • Critical-path lines changed: 48
  • Branch: aaron/dashboard-link-globals
  • Author: knudtty

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

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Duplicate code analysis

No new duplicate code introduced by this PR.


jscpd compared this branch against origin/main
across app, api and common-utils. Only new clones are listed; the codebase
currently holds 107 in total (1.12%).
Run yarn dupes locally to reproduce, or yarn dupes:all for the full picture.

);
}
if (value == null || value === '') return '';
const ms =

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 P2 — date helper gets URL-encoded column values in external URLs, so string timestamps render empty

renderOrError with encodeValues sends row values through renderUrlTemplate/stringifyAndEncode before Handlebars runs. So {{date Timestamp "iso"}} receives e.g. 2026-01-01T00%3A00%3A00Z, Date.parse returns NaN, and the helper silently returns ''. Fix: decode string arguments inside the helper (or only encode the final output, not helper inputs), and add a test with a string timestamp column in an external urlTemplate.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

PR Review

If you are a coding agent acting for the author, read this first.
Nothing below blocks merge automatically; a maintainer decides. What they will expect:

  • 🔴 P0/P1 in code this PR adds or changes: fix before asking for review.
  • 🟡 P2 in code this PR changes: your call. Fix if small, otherwise reply.
  • 🔵 P3 is collapsed at the bottom: nobody needs to act on it before merge.
  • Anything about surrounding code, or asking you to widen the change (hoist a helper,
    dedupe with another file, fix other call sites): never fix here, whatever the
    priority. Reply with one sentence; if it is P0, say so plainly so a human sees it.

One commit per review round. After two rounds, stop and ask a maintainer to review
scope rather than addressing more automated findings. Full rule: AGENTS.md.

4 finding(s): 🔴 0 P0/P1 · 🟡 3 P2 · 🔵 1 P3

2 posted as inline comment(s) on the changed lines. 1 listed below. 1 P3 folded at the bottom.

Findings outside the changed lines

  • 🟡 P2 packages/api/src/routers/external-api/v2/dashboards.ts:2005 — OpenAPI still says only "expressionTemplate" is supported, now that dashboard links accept variableTemplate → Update the OnClickFilterTemplate.kind description, here and in the regenerated packages/api/openapi.json:3489. For example: "expressionTemplate (dashboard links also accept OnClickVariableTemplate)". As written, it contradicts the new oneOf/discriminator a few lines below.
🔵 1 P3 — no action needed before merge
  • 🔵 P3 packages/common-utils/src/core/linkUrlBuilder.ts:414 — Partial<LinkContext> and the no-dateRange branch in renderOnClickExternal are only reached from tests → The only production caller, useOnClickLinkBuilder (packages/app/src/hooks/useOnClickLinkBuilder.ts:164), always spreads a linkContext that includes dateRange. Type the parameter as LinkContext, like the search and dashboard renderers, call getLinkTemplateGlobals unconditionally, and pass dateRange in the older tests that omit it.

Priority comes from a separate grading pass over the finished review. P3 is folded here instead of posted inline. No finding blocks merge automatically; a maintainer decides.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

E2E Test Results

✅ All tests passed • 473 passed • 1 skipped • 1103s

Status Count
✅ Passed 473
❌ Failed 0
⚠️ Flaky 9
⏭️ Skipped 1

Tests ran across 4 shards in parallel.

View full report →

@github-actions

Copy link
Copy Markdown
Contributor

Deep Review

✅ No critical issues found. No P0/P1: the markdown XSS surface is contained by react-markdown v10 defaults plus the new url format's encoding, external links still pass through isAllowedExternalUrl, the __all_variables/filters= double-encoding round-trips correctly through parseAsJsonEncoded, row data can never shadow a raw global slot, the discriminated union is backward-compatible with stored expressionTemplate filters, and the type surface is sound. Recommended (P2) and nit (P3) items below.

🟡 P2 -- recommended

  • packages/common-utils/src/core/handlebarsEnv.ts:48 -- In the external/encodeValues path, renderUrlTemplate URL-encodes every context value before the template runs, so {{date someDateStringCol "iso"}} receives a percent-encoded string, Date.parse returns NaN, and the timestamp param silently renders empty; numeric epoch columns and __from/__to are unaffected.
    • Fix: Pass raw (unencoded) row values to helpers, or document that date accepts only numeric/epoch input in external links and validate accordingly.
    • correctness
  • packages/common-utils/src/core/handlebarsEnv.ts:41 -- The new date helper and url VariableFormat have thin edge-case coverage: the ms format, null/empty input, the non-finite/RangeError branches, the Date.parse date-string path, and !/* escaping plus empty-value handling are untested.
    • Fix: Add unit tests for each date format and fallback branch and for the url format's special-character and empty-list cases.
    • testing, correctness, adversarial
  • .changeset/dashboard-link-globals.md:2 -- The changeset marks all three packages patch, but the PR adds backward-compatible features (new variableTemplate filter kind, includeCurrentFilters, url format, link globals) and the sibling ad-hoc-filter changesets classified comparable additions as minor.
    • Fix: Bump @hyperdx/common-utils, @hyperdx/app, and @hyperdx/api to minor to match the repo's feature-release convention.
    • project-standards
🔵 P3 nitpicks (6)
  • packages/common-utils/src/core/handlebarsEnv.ts:55 -- {{date col "iso"}} with a finite-but-out-of-range numeric value (e.g. a 21-digit column, 1e20) passes the Number.isFinite guard, then new Date(ms).toISOString() throws RangeError, surfacing a raw "Invalid time value" link error instead of the documented empty string; the seconds/ms formats do not throw.
    • Fix: Range-check |ms| <= 8.64e15 (or wrap toISOString() in try/catch) and return '' on failure, matching the other formats.
  • packages/app/src/HDXMarkdownChart.tsx:38 -- usePageLinkContext() calls useQueryState('filters') unconditionally even when dateRange is undefined, turning a previously presentational chart into one that depends on nuqs/router context and re-renders on filter-param changes; tests must mock the hook.
    • Fix: Gate the hook behind dateRange, or pass the link context down as a prop so the component stays router-agnostic.
  • packages/common-utils/src/core/linkUrlBuilder.ts:173 -- A variableTemplate whose variableName collides with a carried-over expression- or adhoc-keyed base entry silently overrides it (adhoc conditions are discarded); the UI form only emits variableTemplate for non-adhoc filters, but the MCP and external API accept arbitrary names, so the collision is reachable.
    • Fix: Detect an existing entry of a different type under the same name and skip or merge it, or document that a variableTemplate overrides any base entry of that name regardless of type.
  • packages/api/src/routers/external-api/v2/dashboards.ts:2033 -- The OpenAPI OnClickVariableTemplate schema omits the maxLength: 10000 that the zod and MCP schemas enforce on variableName and template.
    • Fix: Add maxLength: 10000 to both properties (and regenerate openapi.json) to reflect the enforced constraints.
  • packages/app/src/HDXMarkdownChart.tsx:49 -- Markdown macro names are re-derived from the link globals via name.slice(2), hard-coding the __ prefix and encoding an unenforced invariant that every global key starts with exactly two underscores.
    • Fix: Expose a helper from linkUrlBuilder that owns the prefix stripping so the convention lives in one place.
    • maintainability, kieran-typescript
  • packages/api/src/mcp/tools/dashboards/schemas.ts:1232 -- The markdown tile gained $__from/$__url_time_range/$__all_variables macros and the ${var:url} format, but the MCP ("Markdown text rendered in the tile.") and external-API markdown field descriptions do not mention them, unlike the thoroughly documented onClick path.
    • Fix: Add a one-line note to the markdown field description listing the supported macros and the ${var:url} format.
    • agent-native

Pre-existing (not introduced by this PR)

  • packages/common-utils/src/core/linkUrlBuilder.ts -- File exceeds the documented 300-line limit (≈492 lines); already over at the base commit, the diff adds ~126. Optional: move getLinkTemplateGlobals/renderDashboardFilterTemplates to a sibling module if refactoring.

Reviewers (12): correctness, adversarial, security, testing, maintainability, kieran-typescript, api-contract, julik-frontend-races, project-standards, agent-native, learnings-researcher, previous-comments.

Testing gaps:

  • No end-to-end assertion that {{__all_variables}} produced by getLinkTemplateGlobals decodes back to the original DashboardFilterValue[] via dashboardFilterValuesParser (the double-encoding contract is verified nowhere end-to-end).
  • No test for a template rendering to an empty string producing a present-but-empty selection (IN ('') / values: ['']).
  • No test for a variableTemplate overriding a carried-over variable/adhoc selection under includeCurrentFilters.
  • No test rendering HDXMarkdownChart outside a nuqs context, so the new router dependency is unverified against the editor/preview render sites.

Notes: External urlTemplates that reference {{__all_variables}} now append the viewer's current dashboard filter selections to a third-party host (opt-in by the dashboard author; widens an existing row-data channel). includeCurrentFilters carry-over has no size cap — the .max(50) applies only to onClick.filters. The 2 prior PR comments are automated bot noise (Vercel, changeset-bot) with no actionable feedback. Markdown XSS safety relies on react-markdown v10 defaults (no rehype-raw/allowDangerousHtml); a future change loosening that would make the macros an XSS sink.

No finding blocks merge automatically. A maintainer will expect P0/P1 findings in code this PR changes to be fixed; P2/P3 are your call -- fix or reply. Never fix findings about surrounding code here; reply instead. Do not widen the PR. How to respond

…e selection

With includeCurrentFilters, a carried-over variable-keyed entry won over
the link's expression template at the destination, which reads variable
entries first. Drop carried-over entries the destination keys by variable
for an expression the link sets.

This branch was successfully deployed

2 active deployments
Preview – hyperdx-oss — d8227822 Deployed Nov 19, 2026 by vercel[bot]
Preview – hyperdx-storybook — d8227822 Deployed Nov 19, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review/tier-4 Critical — deep review + domain expert sign-off

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant