Skip to content

feat(ui): show the cache time in the viewer's locale and time zone - #564

Merged
jsenecal merged 3 commits into
mainfrom
feat/port-t1-timestamps
Nov 21, 2026
Merged

jsenecal merged 3 commits into
mainfrom
feat/port-t1-timestamps

Conversation

@jsenecal

Copy link
Copy Markdown
Collaborator

Piece T1 of #550. Base: main. Port of hyperglass-ng PR jsenecal#138.

Problem

The backend sends the query timestamp as naive UTC: Query.__init__ sets datetime.now(UTC).strftime("%Y-%m-%d %H:%M:%S"), for example 2026-11-20 08:00:00, and a cache hit returns the stored copy of that string. The cached-result tooltip in components/results/individual.tsx showed it as received, through the default web.text.cache_icon Cached from {time} UTC. Viewers had to convert it to their own time.

That tooltip is the only absolute timestamp the UI shows a viewer. The other uses were checked and are left alone, as #551 says:

  • Route age in the structured BGP table (components/output/fields.tsx Age) is a relative age ("an hour"). Its tooltip holds the absolute time from dayjs.utc(...).toString(), labelled UTC, which is correct.
  • Copy to clipboard (hooks/use-table-to-string.ts) writes Timestamp: <timestamp> UTC and the route age with a UTC time. That text is pasted into tickets and compared with router logs, so it stays in UTC, and it is correct.

Change

  • util/timestamp.ts (new): formatTimestamp(value, { locale?, timeZone? }).
    • It accepts only the backend's YYYY-MM-DD HH:MM:SS and ISO 8601 date-times (T, an optional fraction, an optional Z or ±HH:MM offset), checked with a strict pattern and field ranges. A value without a zone is UTC. A value with Z or an offset keeps it.
    • Anything else is returned unchanged, including 12, abc 2026, 2026-13-45 99:99:99, 2026-02-30 00:00:00 and a date without a time. The fork's helper used dayjs.utc, which accepted the first two as dates and rolled the third over into 2027.
    • Epoch numbers aren't accepted, since nothing sends them yet. The history and share pieces can add them.
    • It formats with Intl.DateTimeFormat and { dateStyle: 'medium', timeStyle: 'long' }, in the viewer's locale and time zone (both can be overridden, which the tests use). The locale decides the 12- or 24-hour clock, as Cached-result time is shown in UTC instead of the viewer's time zone #551 says. The long time style includes the zone name or offset (for example EST, GMT+9, UTC−5, depending on the locale and zone), so a local time can't be mistaken for UTC. The month is written out, so 11/20 and 20/11 can't be confused in en-US.
  • components/results/individual.tsx: the tooltip passes formatTimestamp(data.timestamp) as {time}. The diff is the import and the cacheLabel line only. It doesn't touch the isError/errorMsg code (fix(ui): flag a failed query that has no error body #542) or the header buttons (fix(ui): give the icon-only result buttons an accessible name #534).
  • web.text.cache_icon default: Cached from {time} UTC → Cached from {time} (models/config/web.py, .samples/sample_config.yaml, complete-config.mdx sample and table, web-ui.mdx table, regenerated UI fixture).
  • CHANGELOG.md: a Changed entry with the default change.

Tests

  • util/timestamp.test.ts (new, 14 tests):
    • The backend's space form and ISO without Z are parsed as UTC; Z, +02:00 and a fractional -05:30 value keep their zone.
    • A conversion across the date line shows an offset (GMT+9).
    • The locale picks the clock: midnight in Toronto is 12:00:00 AM EST in en-US and 00:00:00 GMT-5 in en-GB; de-DE gives 20.11.2026, 09:00:00 MEZ.
    • Nine non-timestamps are returned unchanged.
    • Each case passes an explicit locale and display zone. The process time zone is pinned to Asia/Kolkata with vi.stubEnv('TZ', …), so reading a value as local time gives a different hour even on a UTC runner. CI runs in UTC, where local and UTC parsing look the same.
  • components/results/individual.test.tsx: the cache tooltip test (added in test(ui): cover results, layout and the index page #505) asserted the current behaviour, Cached from 2026-11-20 08:00:00 UTC. It now pins TZ=America/Toronto, computes expected = formatTimestamp(timestamp, { timeZone: 'America/Toronto' }) in the runner's locale, checks that expected differs from the raw value, and asserts the tooltip text is exactly Cached from ${expected}. It passes with LC_ALL set to C, fr_CA, fr_FR, ko_KR, th_TH, ar_EG and fa_IR, and with TZ=Pacific/Auckland.
  • models/tests/test_web_config.py: Text().cache_icon == "Cached from {time}". It fails with the old default.

Without the fix (origin/main's individual.tsx and fixture, new tests):

       × shows the cache time in a tooltip on wide screens, in the viewer's time zone 265ms
Expected: "Cached from Nov 20, 2026, 3:00:00 AM EST"
Received: "Cached from 2026-11-20 08:00:00 UTC"
      Tests  1 failed | 22 passed (23)

Mutations (each run of util/timestamp.test.ts + individual.test.tsx, 37 tests):

Mutation Result
Build the date as local time (new Date(y, m, …) instead of Date.UTC) 5 failed
Fall back to new Date(value) before the strict pattern 10 failed
No date range check 1 failed (2026-02-30)
No time range check 1 failed (24:00:00)
No offset range check 1 failed (+25:00)
No range checks at all 4 failed
Offset sign ignored 1 failed
Offset ignored 1 failed
Forced hourCycle: 'h23' 5 failed
timeStyle: 'medium' (no zone) 5 failed
Return Invalid Date instead of the input 9 failed
Raw timestamp in individual.tsx 1 failed (component test)
Old cache_icon default test_cache_icon_default_has_no_time_zone fails

With the fix:

  • Frontend: test Tests 228 passed (228) on Node 22. Also on Node 24 with LC_ALL=fr_CA.UTF-8 TZ=Pacific/Auckland. biome format, biome lint and tsc --noEmit are clean.
  • Backend: 4171 passed, 4 skipped; ruff check . is clean.

Changelog

  • Show the cached-result time in the viewer's locale and time zone, with the zone name or offset. The locale decides the 12- or 24-hour clock. Default change: web.text.cache_icon is now Cached from {time}; it was Cached from {time} UTC.

Notes

Closes #551

@jsenecal jsenecal added feature New feature or request frontend Next.js UI and the runtime UI build labels Nov 21, 2026
@jsenecal jsenecal self-assigned this Nov 21, 2026
@jsenecal
jsenecal requested a review from WilhelmZA November 21, 2026 06:01
@github-actions github-actions Bot added docs Improve documentation backend Python backend: API, models, state, execution labels Nov 21, 2026
@coveralls

coveralls commented Nov 21, 2026 •

Copy link
Copy Markdown

Coverage Status

coverage: 86.178% (+0.02%) from 86.156% — feat/port-t1-timestamps into main

@WilhelmZA WilhelmZA left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Reviewed at c27b538d.

formatTimestamp() parses the backend's naive UTC timestamp as UTC and formats it in the viewer's locale and time zone, and input that does not match is returned unchanged. The web.text.cache_icon default loses its UTC suffix in the model, the sample, both docs pages and the UI fixture, and CHANGELOG.md records it under Changed with a migration note. CI gate passes and both commits are verified.

Before approval:

  • #551 says it depends on #534 and #542 being merged, because both edit results/individual.tsx. #534 is merged and #542 is still open. This PR does not touch the isError or errorMsg code, so either merge #542 first and rebase, or note on #551 that the dependency on #542 is dropped.

#544 adds web.text fields in the same model block, docs tables and UI fixture, and #565 moves the cacheLabel line into ResultPanel. #566 and #567 also edit CHANGELOG.md.

Nits:

  • CHANGELOG.md: the new entry links only #551. The other Unreleased entries link the PR and the issue.
  • hyperglass/ui/util/timestamp.test.ts: the tests assert exact ICU output such as 'Nov 20, 2026, 3:00:00 AM EST'. Those strings come from the CLDR data that ships with Node, so a Node update can fail them without a code change. One exact string as a smoke check and formatToParts for the rest would be more stable.

@jsenecal

Copy link
Copy Markdown
Collaborator Author

Thanks.

WilhelmZA
WilhelmZA previously approved these changes Nov 21, 2026

@WilhelmZA WilhelmZA left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Approving at 06a7ee1e.

The new commit changes only CHANGELOG.md and hyperglass/ui/util/timestamp.test.ts. The tests now build each expected instant with Date.UTC and compare against Intl output, so they still fail if the UTC parsing, the time zone conversion or the pass-through of unmatched input breaks, and one exact string stays as a smoke check. The changelog entry links the PR, and the comment on #551 drops the dependency on #542. CI gate passes and all three commits are verified.

#542, #544 and #565 still overlap with this PR in results/individual.tsx and the web.text files, so the later ones need a rebase.

The backend sends the query timestamp as naive UTC ("2026-11-20 08:00:00"),
and the cached-result tooltip showed it as received after "Cached from".
Add formatTimestamp(), which parses such values as UTC (a value with its own
zone keeps it) and formats them with Intl.DateTimeFormat in the viewer's
locale and time zone, on a 24-hour clock with the zone name. Unparseable
input is returned unchanged.

The time is no longer UTC, so the default web.text.cache_icon drops the
word: "Cached from {time}".
Format with dateStyle "medium" and timeStyle "long" instead of forcing
hourCycle h23. The locale decides the 12- or 24-hour clock, as #551
specifies, and the long time style keeps the zone name or offset. A
forced h23 was also only partial: some locales (fr-CA, ko-KR, th-TH) use
their own long pattern once a zone name is requested.

Accept only the backend's "YYYY-MM-DD HH:MM:SS" and ISO 8601 date-times
(T, optional fraction, Z or offset), with range checks. dayjs accepted
"12" or "abc 2026" as dates and rolled "2026-13-45 99:99:99" over, so
non-timestamps were not returned unchanged.

The cache tooltip test now compares with formatTimestamp under a pinned
time zone, so it passes in any runner locale. Add the backend default
test for cache_icon, and link #551 in the changelog.
…R strings

Keep one exact string as a smoke check. The other cases format a known
instant with the same Intl options, so a Node or ICU update that changes
the CLDR text can't fail them without a code change. Link the PR in the
changelog entry.
@jsenecal

Copy link
Copy Markdown
Collaborator Author

Rebased onto main after #544 and #526 merged (b19100a); this needs another look, sorry for dismissing your approval. The code is unchanged: the range-diff shows only context changes.

CI here fails until #571 merges: main broke when #535 and #524 met.

@WilhelmZA WilhelmZA left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Approving at b19100af.

This is the rebase onto main after #544 and #526. The three commits carry the same changes I approved at 06a7ee1e: the range diff shows only context differences in the UI fixture (it keeps asPathTitle from #544) and in test_web_config.py. CI gate passes on the run that merged this head into main at f89ab22a. The one commit on main since then is #545, which changes only the query form files and none of the files or text keys this PR touches, and the merge with current main is clean. All three commits are verified.

#542 and #565 still change results/individual.tsx, so the later ones need a rebase.

@jsenecal
jsenecal merged commit 15457cf into main Nov 21, 2026
26 of 29 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

backend Python backend: API, models, state, execution docs Improve documentation feature New feature or request frontend Next.js UI and the runtime UI build reviewing Issue is being reviewed by maintainers

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Cached-result time is shown in UTC instead of the viewer's time zone

3 participants