Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions apps/web/src/page/dashboards/kit/widget-data.ts
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,8 @@
readonly dataSource: unknown
readonly window: { readonly startTime: string; readonly endTime: string } | null
readonly widgetTimeRange?: Parameters<typeof planWidgetRequest>[0]["widgetTimeRange"]
/** The clock read a pinned relative range resolves on, so a re-plan between reads keeps its key. */
readonly clock?: Readonly<{ nowMs: number; snap: boolean }>
readonly maxDataPoints?: number
/** The board's variables: their names, and the values resolved so far. */
readonly variables?: Readonly<{
Expand Down Expand Up @@ -135,6 +137,7 @@
request,
dashboardWindow: input.window,
...(input.widgetTimeRange === undefined ? undefined : { widgetTimeRange: input.widgetTimeRange }),
...(input.clock === undefined ? undefined : input.clock),

Check warning on line 140 in apps/web/src/page/dashboards/kit/widget-data.ts

View check run for this annotation

Maple Review Bot / Maple / review

correctness: Pinned tiles ignore `clock`: `planWidgetRequest` has no such field

`planWidgetRequest`'s input carries `nowMs` and `snap`, never `clock` (`packages/query-engine/src/widget-request.ts:45`), so this property is dropped without a type error. A pinned tile still resolves its range on `Date.now()`, always snapped: after a Reload it stays a grid step behind the board, and the scene test passes only when the real 15 s grid moves.
Comment thread
Makisuo marked this conversation as resolved.
Resolved
...(input.maxDataPoints === undefined ? undefined : { maxDataPoints: input.maxDataPoints }),
...(input.variables === undefined ? undefined : { variableValues: input.variables.values }),
})
Expand Down
9 changes: 7 additions & 2 deletions apps/web/src/page/dashboards/view/model.ts
Original file line number Diff line number Diff line change
Expand Up @@ -154,10 +154,15 @@ export const Model = Schema.Struct({
document: Schema.NullOr(DashboardDocument),
/** The live board never answered within `COLLECTION_LOAD_TIMEOUT_MS`: the HTTP snapshot's state. */
snapshot: Snapshot,
/** The clock the window is resolved against: read on entry, Reload and a time range change. */
/** The clock the window is resolved against: read on entry, a range change, Reload and each tick. */
nowMs: Schema.NullOr(Schema.Number),
/** 0 snaps the window to the cache grid. */
/** Bumped by every Reload and auto-refresh tick; the Reload spinner ends on its own version. */
refreshVersion: Schema.Number,
/**
* What read `nowMs`. Only an explicit Reload leaves the window unsnapped and refetches held keys;
* an auto-refresh tick snaps, so a tile refetches only once its window reaches the next grid step.
*/
clockRead: Schema.Literals(["Navigation", "AutoRefresh", "Reload"]),
isReloading: Schema.Boolean,
/** The sections container's width; 0 until measured. */
gridWidth: Schema.Number,
Expand Down
39 changes: 30 additions & 9 deletions apps/web/src/page/dashboards/view/plan.ts
Original file line number Diff line number Diff line change
Expand Up @@ -43,11 +43,26 @@ export const isSameTimeRange = (a: TimeRange | null, b: TimeRange | null): boole
? b.type === "relative" && a.value === b.value
: b.type === "absolute" && a.startTime === b.startTime && a.endTime === b.endTime

/** Snapped on entry, unsnapped after a reload; a bad preset falls back to 1h. */
/**
* How a pass asks: `Load` fetches keys not held, `Refresh` refetches held ones too. `Tick` is an
* auto-refresh: `Load` for the requests, so a tile whose snapped window has not moved fetches nothing.
*/
export type PlanMode = Keyed.RequestMode | "Tick"

/** What `read` the clock picks: a tick plans as a `Tick`, a Reload refetches everything held. */
export const planModeOf = (clockRead: Model["clockRead"]): PlanMode =>
clockRead === "Reload" ? "Refresh" : clockRead === "AutoRefresh" ? "Tick" : "Load"

/** Snapped to the cache grid except after an explicit Reload, which wants "now". */
const clockOf = (model: Model) =>
model.nowMs === null ? null : { nowMs: model.nowMs, snap: model.clockRead !== "Reload" }

/** The board's window on the current clock; a bad preset falls back to 1h. */
export const windowOf = (model: Model, context: PageContext) => {
const timeRange = timeRangeOf(model)
if (timeRange === null || model.nowMs === null) return null
const options = { snap: model.refreshVersion === 0, timeZone: context.timeZone, nowMs: model.nowMs }
const clock = clockOf(model)
if (timeRange === null || clock === null) return null
const options = { ...clock, timeZone: context.timeZone }
return (
resolveTimeRangeWindow(timeRange, options) ??
resolveTimeRangeWindow({ type: "relative", value: "1h" }, options)
Expand Down Expand Up @@ -195,6 +210,7 @@ const sparklineGate = (
widget: Widget,
window: ReturnType<typeof windowOf>,
variables: ReturnType<typeof variablesOf>,
clock: ReturnType<typeof clockOf>,
): WidgetGate | null => {
const sparkline = widget.display.sparkline
if (widget.visualization !== "stat" || sparkline?.enabled !== true || sparkline.dataSource === undefined)
Expand All @@ -204,6 +220,7 @@ const sparklineGate = (
dataSource: sparkline.dataSource,
window,
...(widget.timeRange === undefined ? undefined : { widgetTimeRange: widget.timeRange }),
...(clock === null ? undefined : { clock }),
variables,
})
}
Expand All @@ -226,11 +243,13 @@ type OptionsPlan = ReturnType<typeof planVariableOptions>
const planTiles = (
model: Model,
context: PageContext,
mode: Keyed.RequestMode,
mode: PlanMode,
widgets: ReadonlyArray<Widget>,
options: OptionsPlan,
): Planned => {
const window = windowOf(model, context)
const clock = clockOf(model)
const requestMode = mode === "Tick" ? "Load" : mode
const withOptions = { ...model, variableOptions: options.variableOptions }
const variables = variablesOf(withOptions, context)
const initial: PlanState = {
Expand All @@ -252,17 +271,18 @@ const planTiles = (
dataSource: widget.dataSource,
window,
...(widget.timeRange === undefined ? undefined : { widgetTimeRange: widget.timeRange }),
...(clock === null ? undefined : { clock }),
maxDataPoints: maxDataPointsForWidth(slot.widthPx ?? DEFAULT_WIDGET_WIDTH_PX, panelType),
variables,
isNarrowed: slot.isNarrowed === true,
})
const gate = keptGate(planned, slot.gate)
const previousSpark = slot.sparkGate ?? null
const nextSparkGate = sparklineGate(context, widget, window, variables)
const nextSparkGate = sparklineGate(context, widget, window, variables, clock)
const sparkGate = nextSparkGate === null ? null : keptGate(nextSparkGate, previousSpark)
const isChanged = gate !== slot.gate || sparkGate !== previousSpark
// Still loading a window this refresh moved: wait for that answer, which re-plans the tile.
if (mode === "Refresh" && isInFlight(state.requests, slot))
if (mode !== "Load" && isInFlight(state.requests, slot))
return keep(!isChanged || slot.isStale === true ? slot : { ...slot, isStale: true })
// Off screen: keep what it shows, and fetch the new window once it scrolls back into view.
if (slot.isOffscreen === true)
Expand All @@ -271,7 +291,7 @@ const planTiles = (
? { ...slot, isStale: true }
: slot,
)
const tileMode = slot.isStale === true ? "Refresh" : mode
const tileMode = slot.isStale === true ? "Refresh" : requestMode
const asked = ask(ask(state, gate, slot.gate, tileMode), sparkGate, previousSpark, tileMode)
const { isStale: _stale, ...fresh } = slot
// An unchanged slot keeps its object: the tile's memo compares it by reference.
Expand All @@ -287,10 +307,11 @@ const planTiles = (
}

/** Every revealed tile and the variables' option lists, for a new window, document or variable. */
export const replan = (model: Model, context: PageContext, mode: Keyed.RequestMode): Planned => {
export const replan = (model: Model, context: PageContext, mode: PlanMode): Planned => {
const document = shownDocumentOf(model)
if (document === null) return { model, commands: [] }
return planTiles(model, context, mode, document.widgets, planVariableOptions(model, context, mode))
const options = planVariableOptions(model, context, mode === "Tick" ? "Load" : mode)
return planTiles(model, context, mode, document.widgets, options)
}

/** One tile revealed, measured or narrowed: no other tile's plan can have moved. */
Expand Down
87 changes: 80 additions & 7 deletions apps/web/src/page/dashboards/view/refresh.scene.test.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import { OrgId } from "@maple/domain"
import { DashboardDocument } from "@maple/domain/http"
import { makeRawSqlDataSource } from "@maple/widgets/dashboard"
import { Option, Result, Schema, Array as Arr, Record as Rec } from "effect"
import { describe, expect, test } from "vitest"
import type { PageContext } from "../../contract"
Expand Down Expand Up @@ -50,11 +51,11 @@ const throughput = {
layout: { x: 3, y: 0, w: 6, h: 4 },
}

const boardOf = (widgets: ReadonlyArray<unknown>) =>
const boardOf = (widgets: ReadonlyArray<unknown>, range = "6h") =>
Schema.decodeUnknownSync(DashboardDocument)({
id: "dash_platform",
name: "Platform overview",
timeRange: { type: "relative", value: "6h" },
timeRange: { type: "relative", value: range },
widgets,
createdAt: "2026-09-19T12:00:00.000Z",
updatedAt: "2026-09-28T12:00:00.000Z",
Expand All @@ -64,10 +65,10 @@ const boardOf = (widgets: ReadonlyArray<unknown>) =>
const run = (model: Model, messages: ReadonlyArray<Message>): Model =>
Arr.reduce(messages, model, (current, message) => pageUpdate(current, message).model)

const ready = (widgets: ReadonlyArray<unknown>): Model =>
const ready = (widgets: ReadonlyArray<unknown>, range?: string): Model =>
run(init({ dashboardId: "dash_platform", search: {} }, context).model, [
Message.CompletedReadClock({ nowMs: NOW }),
Message.UpdatedDashboard({ orgId, maybeDocument: Option.some(boardOf(widgets)) }),
Message.UpdatedDashboard({ orgId, maybeDocument: Option.some(boardOf(widgets, range)) }),
])

/** Every held request answered. */
Expand All @@ -84,8 +85,33 @@ const requestKeyOf = (model: Model, widgetId: string) => {
return gate?._tag === "Request" ? gate.request.key : null
}

const tick = (model: Model) =>
pageUpdate(run(model, [Message.TickedAutoRefresh()]), Message.CompletedReadClock({ nowMs: NOW + 60_000 }))
const tick = (model: Model, nowMs = NOW + 60_000) =>
pageUpdate(run(model, [Message.TickedAutoRefresh()]), Message.CompletedReadClock({ nowMs }))

const reloadAt = (model: Model, nowMs: number) =>
pageUpdate(run(model, [Message.ClickedReload()]), Message.CompletedReadClock({ nowMs }))

const sqlTile = (id: string, timeRange?: unknown) => ({
id,
visualization: "stat",
dataSource: makeRawSqlDataSource({
sql: `SELECT count() AS value, '${id}' AS tile FROM traces WHERE $__orgFilter AND $__timeFilter(Timestamp)`,
}),
display: { title: id, unit: "number" },
layout: { x: 0, y: 0, w: 3, h: 2 },
...(timeRange === undefined ? undefined : { timeRange }),
})

/** Answers each tick's fetches, ticking every `everyMs` for `forMs`; returns how many it fetched. */
const fetchesOverTicks = (start: Model, everyMs: number, forMs: number): number =>
Arr.reduce(
Arr.makeBy(Math.floor(forMs / everyMs), (i) => NOW + (i + 1) * everyMs),
{ model: start, total: 0 },
(state, nowMs) => {
const ticked = tick(state.model, nowMs)
return { model: answered(ticked.model), total: state.total + fetches(ticked.commands) }
},
).total

describe("dashboard refresh", () => {
test("an auto-refresh refetches only tiles in view; a scrolled-away tile fetches once it is back", () => {
Expand Down Expand Up @@ -125,7 +151,54 @@ describe("dashboard refresh", () => {
)
expect(fetches(settled.commands)).toBe(1)
expect(requestKeyOf(settled.model, "errors")).not.toBe(key)
expect(fetches(tick(answered(settled.model)).commands)).toBe(1)
expect(fetches(tick(answered(settled.model), NOW + 120_000).commands)).toBe(1)
})

test("a 30-day raw SQL board ticking every 10s fetches once per 30-minute grid step, not per tick", () => {
const board = answered(
run(ready([sqlTile("orders")], "30d"), [Message.RevealedWidget({ widgetId: "orders" })]),
)
expect(fetchesOverTicks(board, 10_000, 60 * 60_000)).toBe(2)
})

test("a tick that leaves the snapped window where it was asks for nothing", () => {
const board = answered(
run(ready([sqlTile("orders")]), [Message.RevealedWidget({ widgetId: "orders" })]),
)
const ticked = tick(board, NOW + 30_000)
expect(fetches(ticked.commands)).toBe(0)
expect(requestKeyOf(ticked.model, "orders")).toBe(requestKeyOf(board, "orders"))
})

test("an explicit Reload refetches at the true now, even within the same grid step", () => {
const board = answered(
run(ready([sqlTile("orders")]), [Message.RevealedWidget({ widgetId: "orders" })]),
)
const reloaded = reloadAt(board, NOW + 30_000)
expect(fetches(reloaded.commands)).toBe(1)
expect(requestKeyOf(reloaded.model, "orders")).not.toBe(requestKeyOf(board, "orders"))
})

test("ticks after a Reload return to the snapped grid once, then hold until it moves", () => {
const board = answered(
run(ready([sqlTile("orders")]), [Message.RevealedWidget({ widgetId: "orders" })]),
)
const reloaded = answered(reloadAt(board, NOW + 30_000).model)
const back = tick(reloaded, NOW + 40_000)
expect(fetches(back.commands)).toBe(1)
expect(requestKeyOf(back.model, "orders")).toBe(requestKeyOf(board, "orders"))
expect(fetches(tick(answered(back.model), NOW + 50_000).commands)).toBe(0)
})

test("a tile pinned to its own range resolves it on the clock read, so ticks share its key", () => {
const board = answered(
run(ready([sqlTile("recent", { type: "relative", value: "1h" })]), [
Message.RevealedWidget({ widgetId: "recent" }),
]),
)
const sameStep = tick(board, NOW + 10_000)
expect(fetches(sameStep.commands)).toBe(0)
expect(fetches(tick(answered(sameStep.model), NOW + 15_000).commands)).toBe(1)
})

test("a resize that keeps the chart's bucket keeps its request; one that changes it refetches", () => {
Expand Down
22 changes: 13 additions & 9 deletions apps/web/src/page/dashboards/view/update.ts
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,8 @@ import { FallbackReason, FetchDashboardFallback } from "./command-fallback"
import {
awaitsRefresh,
isSameTimeRange,
planModeOf,
type PlanMode,
replan,
replanTile,
shownDocumentOf,
Expand Down Expand Up @@ -83,6 +85,7 @@ export const init = (route: Route, _context: PageContext): Return => ({
snapshot: { _tag: "Idle" },
nowMs: null,
refreshVersion: 0,
clockRead: "Navigation",
isReloading: false,
gridWidth: 0,
widgets: {},
Expand Down Expand Up @@ -146,7 +149,8 @@ const isRangeMoved = (before: Model, after: Model): boolean => {
/** A `var-*` change re-plans the tiles that read the variable; a `range` change reads the clock first. */
export const routeChanged = (model: Model, route: Route, context: PageContext): Return => {
const next = { ...model, search: route.search }
if (isRangeMoved(model, next)) return { model: next, commands: [ReadClock()] }
if (isRangeMoved(model, next))
return { model: { ...next, clockRead: "Navigation" }, commands: [ReadClock()] }
return sameValues(variableValuesFromSearch(model.search), variableValuesFromSearch(route.search))
? { model: next }
: withReplan(next, context, "Load")
Expand Down Expand Up @@ -182,11 +186,11 @@ const editModeHref = (model: Model): string => {
return dashboardHref(model, { ...kept, mode: "edit" })
}

/** A new clock, an unsnapped window and the Reload spinner. */
const reload = (model: Model): Return => {
/** A new clock and the Reload spinner; a Reload also unsnaps the window, a tick keeps it snapped. */
const reload = (model: Model, clockRead: "AutoRefresh" | "Reload"): Return => {
const refreshVersion = model.refreshVersion + 1
return {
model: { ...model, refreshVersion, isReloading: true },
model: { ...model, refreshVersion, clockRead, isReloading: true },
commands: [ReadClock(), CompleteReloadSpin({ version: refreshVersion })],
}
}
Expand Down Expand Up @@ -294,7 +298,7 @@ const replanAfter = (stepped: Return, context: PageContext): Return => {
return { ...stepped, model: planned.model, commands: [...(stepped.commands ?? []), ...planned.commands] }
}

const withReplan = (model: Model, context: PageContext, mode: Keyed.RequestMode): Return => {
const withReplan = (model: Model, context: PageContext, mode: PlanMode): Return => {
const planned = replan(model, context, mode)
return { model: planned.model, commands: planned.commands }
}
Expand Down Expand Up @@ -349,7 +353,7 @@ const receiveDocument = (
const ended = cancelStaleGesture(settled, context)
// A new saved range this viewer shows: the clock is read first, and its answer plans.
const replanned: Return = isRangeMoved(model, ended.model)
? { model: ended.model, commands: [ReadClock()] }
? { model: { ...ended.model, clockRead: "Navigation" }, commands: [ReadClock()] }
: withReplan(ended.model, context, "Load")
const planned: Return = {
...replanned,
Expand Down Expand Up @@ -604,7 +608,7 @@ export const update = (model: Model, message: Message, context: PageContext): Re
? readSnapshot(model, "retry")
: { model, outMessage: PageOutMessage.RequestedReconnectOrgCollections() },
CompletedReadClock: ({ nowMs }) =>
withReplan({ ...model, nowMs }, context, model.refreshVersion > 0 ? "Refresh" : "Load"),
withReplan({ ...model, nowMs }, context, planModeOf(model.clockRead)),
MeasuredGrid: ({ width }) => cancelStaleGesture({ ...model, gridWidth: width }, context),
MeasuredWidget: ({ widgetId, widthPx }) => {
const slot = slotOf(model, widgetId)
Expand Down Expand Up @@ -703,8 +707,8 @@ export const update = (model: Model, message: Message, context: PageContext): Re
},
})
},
TickedAutoRefresh: () => reload(model),
ClickedReload: () => reload(model),
TickedAutoRefresh: () => reload(model, "AutoRefresh"),
ClickedReload: () => reload(model, "Reload"),
CompletedReloadSpin: ({ version }) =>
version === model.refreshVersion ? { model: { ...model, isReloading: false } } : { model },
ClickedToggleEdit: () => toggleEdit(model),
Expand Down
6 changes: 4 additions & 2 deletions apps/web/src/page/share/model.ts
Original file line number Diff line number Diff line change
Expand Up @@ -99,13 +99,15 @@ export const Model = Schema.Struct({
token: Schema.String,
search: ShareSearch,
resolve: Resolve,
/** Reloads and auto-refresh ticks so far (non-zero stops snapping). */
refreshTick: Schema.Number,
/** What read `nowMs`: only a Reload unsnaps the window and refetches tiles whose key held still. */
clockRead: Schema.Literals(["Navigation", "AutoRefresh", "Reload"]),
window: Schema.NullOr(ShareWindow),
/** Each mounted tile's measured `maxDataPoints`. */
options: Schema.Record(Schema.String, Schema.Number),
/** The request key each widget was last fetched under. */
requested: Schema.Record(Schema.String, Schema.String),
/** The key each widget's last answer failed under; a tick retries it once, until the retry answers. */
failedKeys: Schema.Record(Schema.String, Schema.String),
isFlushScheduled: Schema.Boolean,
/** Batches after the one in flight; each is awaited before the next is sent. */
queuedBatches: Schema.Array(QueuedBatch),
Expand Down
Loading
Loading