838 lines
32 KiB
TypeScript
838 lines
32 KiB
TypeScript
/**
|
|
* src/analytics/dashboards/dashboard-document.ts
|
|
* ===============================================
|
|
* BI-P060 — ANALYTICS DASHBOARD MODEL.
|
|
*
|
|
* BI-P002 already named `DashboardDefinition` and `DashboardVersion` and gave
|
|
* them storage (sql/008). What it did not give them is a BODY: `layout_json`
|
|
* is a string, and a string can hold anything — including a Superset export
|
|
* that only Superset can read back. This module is that body, and its whole
|
|
* point is the DoD:
|
|
*
|
|
* "A native SIAX dashboard can be reconstructed without Superset."
|
|
*
|
|
* Reconstruction is not a claim you can make by writing a type. It is provable
|
|
* exactly once you can take a document and produce, for every widget, a
|
|
* runnable `AnalyticsQueryRequest` (BI-P016) plus a rendering spec, with no
|
|
* vendor identifier anywhere in the plan. `planDashboard()` is that function
|
|
* and `tests/analytics/dashboard-model.test.ts` runs it over a document
|
|
* carrying Superset ids, asserting the plan is complete and vendor-free.
|
|
*
|
|
* THE VENDOR RULE, stated once: a Superset/Metabase/Cube identifier may be
|
|
* carried as `vendor_ref` for round-tripping, and it is
|
|
* - never a widget's source of truth (a widget with only a vendor_ref is
|
|
* REFUSED — it is precisely the document that cannot be reconstructed),
|
|
* - never part of the canonical hash (so re-exporting to a new Superset
|
|
* instance does not fabricate a new dashboard version).
|
|
*
|
|
* NO SQL LIVES HERE either. Widget sources are metric/dimension NAMES that
|
|
* resolve through the catalog, and query widgets are validated by
|
|
* `parseAnalyticsQueryRequest`, which rejects `sql`, `where`, `tenant_id` and
|
|
* every other smuggling key structurally. A dashboard is therefore not a new
|
|
* way into the engine; it is a saved set of contract requests.
|
|
*/
|
|
import crypto from 'node:crypto';
|
|
import { SiaxError } from '../../platform/errors';
|
|
import {
|
|
parseAnalyticsQueryRequest,
|
|
TIME_GRAINS,
|
|
type AnalyticsFilter,
|
|
type AnalyticsQueryRequest,
|
|
type FilterOperator,
|
|
type TimeGrain,
|
|
} from '../contract/query-request';
|
|
|
|
// ── vocabulary ─────────────────────────────────────────────────────────────
|
|
|
|
/**
|
|
* Visualization types. A CLOSED list, deliberately engine-neutral: these are
|
|
* SIAX chart kinds (DES1GN BI-P051..P057 renders them), not Superset viz_type
|
|
* strings. A document naming `echarts_timeseries` is a Superset document.
|
|
*/
|
|
export const VISUALIZATION_TYPES = [
|
|
'big_number',
|
|
'line',
|
|
'area',
|
|
'bar',
|
|
'stacked_bar',
|
|
'pie',
|
|
'table',
|
|
'pivot_table',
|
|
'scatter',
|
|
'heatmap',
|
|
'funnel',
|
|
'map',
|
|
] as const;
|
|
export type VisualizationType = (typeof VISUALIZATION_TYPES)[number];
|
|
|
|
export const REFRESH_MODES = ['manual', 'interval', 'scheduled'] as const;
|
|
export type RefreshMode = (typeof REFRESH_MODES)[number];
|
|
|
|
/**
|
|
* Who may open the dashboard. `roles` are cl0ud role names (BI-P033 decides,
|
|
* this only declares). There is deliberately NO tenant field: a dashboard is
|
|
* stored inside a tenant, and a document that could name one would be a way to
|
|
* ask for another tenant's dashboard — the INF0 Wave-2 shape.
|
|
*/
|
|
export const DASHBOARD_VISIBILITIES = ['private', 'tenant', 'roles'] as const;
|
|
export type DashboardVisibility = (typeof DASHBOARD_VISIBILITIES)[number];
|
|
|
|
export const PARAMETER_TYPES = ['string', 'number', 'date', 'enum'] as const;
|
|
export type ParameterType = (typeof PARAMETER_TYPES)[number];
|
|
|
|
// ── the document ───────────────────────────────────────────────────────────
|
|
|
|
/** Grid placement. A 12-column grid, matching the portal layout (BI-P062). */
|
|
export interface WidgetLayout {
|
|
x: number;
|
|
y: number;
|
|
w: number;
|
|
h: number;
|
|
}
|
|
|
|
/** A saved dashboard filter. Its VALUES are data; its dimension is a name. */
|
|
export interface DashboardFilter {
|
|
filter_id: string;
|
|
label: string;
|
|
/** Caller-facing dimension name, resolved through the catalog downstream. */
|
|
dimension: string;
|
|
operator: FilterOperator;
|
|
/** Default values, or `{{param}}` references to a declared parameter. */
|
|
default_values?: string[];
|
|
/** May a viewer change it? A locked filter is how row scoping is saved. */
|
|
locked?: boolean;
|
|
}
|
|
|
|
/** A declared parameter. Widgets and filters may reference it as `{{name}}`. */
|
|
export interface DashboardParameter {
|
|
name: string;
|
|
type: ParameterType;
|
|
required: boolean;
|
|
default_value?: string;
|
|
/** Required for `enum`; a closed list is the only way a value can be trusted. */
|
|
allowed_values?: string[];
|
|
}
|
|
|
|
/** A widget backed by ONE metric — the common case, and the cheapest to plan. */
|
|
export interface MetricWidgetSource {
|
|
kind: 'metric';
|
|
dataset: string;
|
|
metric: string;
|
|
dimensions?: string[];
|
|
grain?: TimeGrain;
|
|
limit?: number;
|
|
}
|
|
|
|
/** A widget backed by a saved contract request (still no SQL, by construction). */
|
|
export interface QueryWidgetSource {
|
|
kind: 'query';
|
|
/** Parsed with `parseAnalyticsQueryRequest` at validation time, not at render time. */
|
|
request: AnalyticsQueryRequest;
|
|
}
|
|
|
|
export type WidgetSource = MetricWidgetSource | QueryWidgetSource;
|
|
|
|
export interface VisualizationSpec {
|
|
type: VisualizationType;
|
|
/** Field roles by NAME. `x`/`y` name metrics or dimensions in the source. */
|
|
encoding: {
|
|
x?: string;
|
|
y?: string[];
|
|
series?: string;
|
|
value?: string;
|
|
};
|
|
/** Presentation-only knobs. Bounded scalars; never code, never a template. */
|
|
options?: Record<string, string | number | boolean>;
|
|
}
|
|
|
|
export interface DashboardWidget {
|
|
widget_id: string;
|
|
title: string;
|
|
source: WidgetSource;
|
|
visualization: VisualizationSpec;
|
|
layout: WidgetLayout;
|
|
/** filter_ids this widget honours. Empty means "all dashboard filters". */
|
|
filter_bindings?: string[];
|
|
/** Advisory only: excluded from the canonical hash, never a source of truth. */
|
|
vendor_ref?: VendorRef;
|
|
}
|
|
|
|
/** A foreign system's id for the same object. Round-tripping aid, nothing more. */
|
|
export interface VendorRef {
|
|
system: string;
|
|
id: string;
|
|
}
|
|
|
|
export interface DashboardRefresh {
|
|
mode: RefreshMode;
|
|
/** Required for `interval`. */
|
|
interval_seconds?: number;
|
|
/** Required for `scheduled`. */
|
|
cron?: string;
|
|
/**
|
|
* The staleness the OWNER accepts. BI-P026 computes actual freshness; this
|
|
* is the number that makes a freshness verdict actionable rather than
|
|
* decorative, and BI-P105 reads it when deciding whether a pre-aggregate may
|
|
* serve this dashboard.
|
|
*/
|
|
max_staleness_seconds: number;
|
|
}
|
|
|
|
export interface DashboardPermissions {
|
|
visibility: DashboardVisibility;
|
|
/** Required (non-empty) when visibility is `roles`. */
|
|
roles?: string[];
|
|
/** Optional cl0ud entitlement key (BI-P079). */
|
|
required_entitlement?: string;
|
|
}
|
|
|
|
/** BI-P060's canonical document, field-for-field with the program's list. */
|
|
export interface DashboardDocument {
|
|
id: string;
|
|
title: string;
|
|
description?: string;
|
|
layout: { grid_columns: number; row_height_px: number };
|
|
filters: DashboardFilter[];
|
|
widgets: DashboardWidget[];
|
|
parameters: DashboardParameter[];
|
|
refresh: DashboardRefresh;
|
|
permissions: DashboardPermissions;
|
|
/** Document schema version — bumped when THIS shape changes, not per edit. */
|
|
version: number;
|
|
vendor_ref?: VendorRef;
|
|
}
|
|
|
|
export const DASHBOARD_DOCUMENT_KEYS = [
|
|
'id',
|
|
'title',
|
|
'description',
|
|
'layout',
|
|
'filters',
|
|
'widgets',
|
|
'parameters',
|
|
'refresh',
|
|
'permissions',
|
|
'version',
|
|
'vendor_ref',
|
|
] as const;
|
|
|
|
/**
|
|
* Keys that mean "this document is really a Superset export". Named
|
|
* explicitly so the refusal explains the architecture instead of saying
|
|
* "unknown key"; the unknown-key rule below catches everything else anyway.
|
|
*/
|
|
const VENDOR_NATIVE_KEYS = new Set([
|
|
'slice_id',
|
|
'slice_name',
|
|
'viz_type',
|
|
'datasource',
|
|
'datasource_id',
|
|
'datasource_type',
|
|
'form_data',
|
|
'query_context',
|
|
'chart_id',
|
|
'dashboard_id_superset',
|
|
'position_json',
|
|
'json_metadata',
|
|
'card_id',
|
|
'cube',
|
|
]);
|
|
|
|
/** Keys that would turn a dashboard into an SQL surface. */
|
|
const SQL_SMELLING_KEYS = new Set([
|
|
'sql',
|
|
'query_text',
|
|
'statement',
|
|
'expression',
|
|
'where',
|
|
'having',
|
|
'raw',
|
|
'tenant',
|
|
'tenant_id',
|
|
'project_id',
|
|
'database',
|
|
'table',
|
|
]);
|
|
|
|
const MAX_WIDGETS = 60;
|
|
const MAX_FILTERS = 32;
|
|
const MAX_PARAMETERS = 24;
|
|
const MAX_NAME_LENGTH = 128;
|
|
const MAX_TITLE_LENGTH = 200;
|
|
const MAX_GRID_COLUMNS = 24;
|
|
const MIN_REFRESH_INTERVAL_SECONDS = 10;
|
|
const MAX_STALENESS_SECONDS = 30 * 24 * 3600;
|
|
/** `{{param}}` — the only templating the document has, and it binds a VALUE. */
|
|
const PARAM_REFERENCE = /^\{\{\s*([A-Za-z][A-Za-z0-9_]{0,63})\s*\}\}$/;
|
|
const IDENTIFIER = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/;
|
|
|
|
function invalid(detail: string): never {
|
|
throw new SiaxError('INVALID_REQUEST', '0pt.analytics.dashboard', detail);
|
|
}
|
|
|
|
function asObject(raw: unknown, what: string): Record<string, unknown> {
|
|
if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) invalid(`${what} must be an object`);
|
|
return raw as Record<string, unknown>;
|
|
}
|
|
|
|
function rejectUnknownKeys(obj: Record<string, unknown>, allowed: readonly string[], what: string): void {
|
|
for (const key of Object.keys(obj)) {
|
|
if (allowed.includes(key)) continue;
|
|
if (VENDOR_NATIVE_KEYS.has(key)) {
|
|
invalid(
|
|
`"${key}" in ${what} is a vendor-native field — a SIAX dashboard is defined by metrics, ` +
|
|
`queries and a visualization spec, not by a BI tool's internal ids (BI-P060). ` +
|
|
`Carry the id in "vendor_ref" if you need to round-trip it.`,
|
|
);
|
|
}
|
|
if (SQL_SMELLING_KEYS.has(key)) {
|
|
invalid(`"${key}" in ${what} is not part of the dashboard model — dashboards do not carry SQL`);
|
|
}
|
|
invalid(`unknown field "${key}" in ${what}`);
|
|
}
|
|
}
|
|
|
|
function asString(raw: unknown, what: string, max = MAX_NAME_LENGTH): string {
|
|
if (typeof raw !== 'string') invalid(`${what} must be a string`);
|
|
const v = raw.trim();
|
|
if (!v) invalid(`${what} must not be empty`);
|
|
if (v.length > max) invalid(`${what} exceeds ${max} characters`);
|
|
return v;
|
|
}
|
|
|
|
function asIdentifier(raw: unknown, what: string): string {
|
|
const v = asString(raw, what);
|
|
if (!IDENTIFIER.test(v)) invalid(`${what} is not a valid identifier`);
|
|
return v;
|
|
}
|
|
|
|
function asInteger(raw: unknown, what: string, min: number, max: number): number {
|
|
if (typeof raw !== 'number' || !Number.isFinite(raw)) invalid(`${what} must be a finite number`);
|
|
if (!Number.isInteger(raw)) invalid(`${what} must be an integer`);
|
|
if (raw < min || raw > max) invalid(`${what} must be between ${min} and ${max}`);
|
|
return raw;
|
|
}
|
|
|
|
function parseVendorRef(raw: unknown, what: string): VendorRef {
|
|
const obj = asObject(raw, what);
|
|
rejectUnknownKeys(obj, ['system', 'id'], what);
|
|
return { system: asString(obj.system, `${what}.system`), id: asString(obj.id, `${what}.id`, 256) };
|
|
}
|
|
|
|
// ── parsing ────────────────────────────────────────────────────────────────
|
|
|
|
function parseParameter(raw: unknown, i: number): DashboardParameter {
|
|
const what = `parameters[${i}]`;
|
|
const obj = asObject(raw, what);
|
|
rejectUnknownKeys(obj, ['name', 'type', 'required', 'default_value', 'allowed_values'], what);
|
|
const name = asIdentifier(obj.name, `${what}.name`);
|
|
const type = asString(obj.type, `${what}.type`);
|
|
if (!(PARAMETER_TYPES as readonly string[]).includes(type)) invalid(`${what}.type is not a parameter type`);
|
|
if (typeof obj.required !== 'boolean') invalid(`${what}.required must be a boolean`);
|
|
const p: DashboardParameter = { name, type: type as ParameterType, required: obj.required };
|
|
if (obj.default_value !== undefined)
|
|
p.default_value = asString(obj.default_value, `${what}.default_value`, 4096);
|
|
if (obj.allowed_values !== undefined) {
|
|
if (!Array.isArray(obj.allowed_values) || obj.allowed_values.length === 0)
|
|
invalid(`${what}.allowed_values must be a non-empty array`);
|
|
p.allowed_values = obj.allowed_values.map((v, j) => asString(v, `${what}.allowed_values[${j}]`, 4096));
|
|
}
|
|
if (p.type === 'enum' && !p.allowed_values) {
|
|
invalid(`${what} is an enum parameter with no allowed_values — an unbounded enum is a free-text field`);
|
|
}
|
|
if (p.required && p.default_value !== undefined) {
|
|
invalid(`${what} is required AND has a default — a default makes "required" unenforceable`);
|
|
}
|
|
return p;
|
|
}
|
|
|
|
function parseFilter(raw: unknown, i: number, parameterNames: Set<string>): DashboardFilter {
|
|
const what = `filters[${i}]`;
|
|
const obj = asObject(raw, what);
|
|
rejectUnknownKeys(obj, ['filter_id', 'label', 'dimension', 'operator', 'default_values', 'locked'], what);
|
|
const filter_id = asIdentifier(obj.filter_id, `${what}.filter_id`);
|
|
const label = asString(obj.label, `${what}.label`, MAX_TITLE_LENGTH);
|
|
const dimension = asString(obj.dimension, `${what}.dimension`);
|
|
const operator = asString(obj.operator, `${what}.operator`) as FilterOperator;
|
|
const f: DashboardFilter = { filter_id, label, dimension, operator };
|
|
if (obj.default_values !== undefined) {
|
|
if (!Array.isArray(obj.default_values)) invalid(`${what}.default_values must be an array`);
|
|
f.default_values = obj.default_values.map((v, j) => {
|
|
const s = asString(v, `${what}.default_values[${j}]`, 4096);
|
|
const m = PARAM_REFERENCE.exec(s);
|
|
if (m && !parameterNames.has(m[1])) {
|
|
invalid(`${what}.default_values[${j}] references undeclared parameter "${m[1]}"`);
|
|
}
|
|
return s;
|
|
});
|
|
}
|
|
if (obj.locked !== undefined) {
|
|
if (typeof obj.locked !== 'boolean') invalid(`${what}.locked must be a boolean`);
|
|
f.locked = obj.locked;
|
|
}
|
|
return f;
|
|
}
|
|
|
|
function parseVisualization(raw: unknown, what: string): VisualizationSpec {
|
|
const obj = asObject(raw, what);
|
|
rejectUnknownKeys(obj, ['type', 'encoding', 'options'], what);
|
|
const type = asString(obj.type, `${what}.type`);
|
|
if (!(VISUALIZATION_TYPES as readonly string[]).includes(type)) {
|
|
invalid(
|
|
`${what}.type "${type}" is not a SIAX visualization type — the canonical list is engine-neutral ` +
|
|
`so a chart survives a BI engine swap (BI-P060)`,
|
|
);
|
|
}
|
|
const encodingRaw = asObject(obj.encoding ?? {}, `${what}.encoding`);
|
|
rejectUnknownKeys(encodingRaw, ['x', 'y', 'series', 'value'], `${what}.encoding`);
|
|
const encoding: VisualizationSpec['encoding'] = {};
|
|
if (encodingRaw.x !== undefined) encoding.x = asString(encodingRaw.x, `${what}.encoding.x`);
|
|
if (encodingRaw.series !== undefined)
|
|
encoding.series = asString(encodingRaw.series, `${what}.encoding.series`);
|
|
if (encodingRaw.value !== undefined) encoding.value = asString(encodingRaw.value, `${what}.encoding.value`);
|
|
if (encodingRaw.y !== undefined) {
|
|
if (!Array.isArray(encodingRaw.y)) invalid(`${what}.encoding.y must be an array`);
|
|
encoding.y = encodingRaw.y.map((v, j) => asString(v, `${what}.encoding.y[${j}]`));
|
|
}
|
|
const spec: VisualizationSpec = { type: type as VisualizationType, encoding };
|
|
if (obj.options !== undefined) {
|
|
const options = asObject(obj.options, `${what}.options`);
|
|
const out: Record<string, string | number | boolean> = {};
|
|
for (const [k, v] of Object.entries(options)) {
|
|
if (!IDENTIFIER.test(k)) invalid(`${what}.options key "${k}" is not an identifier`);
|
|
if (typeof v === 'string') {
|
|
if (v.length > 256) invalid(`${what}.options.${k} exceeds 256 characters`);
|
|
out[k] = v;
|
|
} else if (typeof v === 'number') {
|
|
if (!Number.isFinite(v)) invalid(`${what}.options.${k} must be finite`);
|
|
out[k] = v;
|
|
} else if (typeof v === 'boolean') {
|
|
out[k] = v;
|
|
} else {
|
|
invalid(`${what}.options.${k} must be a string, number or boolean — options are not a payload`);
|
|
}
|
|
}
|
|
spec.options = out;
|
|
}
|
|
return spec;
|
|
}
|
|
|
|
function parseSource(raw: unknown, what: string): WidgetSource {
|
|
const obj = asObject(raw, what);
|
|
const kind = asString(obj.kind, `${what}.kind`);
|
|
if (kind === 'metric') {
|
|
rejectUnknownKeys(obj, ['kind', 'dataset', 'metric', 'dimensions', 'grain', 'limit'], what);
|
|
const source: MetricWidgetSource = {
|
|
kind: 'metric',
|
|
dataset: asString(obj.dataset, `${what}.dataset`),
|
|
metric: asString(obj.metric, `${what}.metric`),
|
|
};
|
|
if (obj.dimensions !== undefined) {
|
|
if (!Array.isArray(obj.dimensions)) invalid(`${what}.dimensions must be an array`);
|
|
source.dimensions = obj.dimensions.map((d, j) => asString(d, `${what}.dimensions[${j}]`));
|
|
}
|
|
if (obj.grain !== undefined) {
|
|
const grain = asString(obj.grain, `${what}.grain`);
|
|
if (!(TIME_GRAINS as readonly string[]).includes(grain)) invalid(`${what}.grain is not a time grain`);
|
|
source.grain = grain as TimeGrain;
|
|
}
|
|
if (obj.limit !== undefined) source.limit = asInteger(obj.limit, `${what}.limit`, 1, 100_000);
|
|
return source;
|
|
}
|
|
if (kind === 'query') {
|
|
rejectUnknownKeys(obj, ['kind', 'request'], what);
|
|
// parseAnalyticsQueryRequest is the SQL boundary: it is why a query widget
|
|
// cannot become an SQL widget by adding a field.
|
|
return { kind: 'query', request: parseAnalyticsQueryRequest(obj.request) };
|
|
}
|
|
invalid(
|
|
`${what}.kind must be "metric" or "query" — a widget with no reconstructable source cannot be ` +
|
|
`rendered without the tool that exported it (BI-P060 DoD)`,
|
|
);
|
|
}
|
|
|
|
function parseWidget(raw: unknown, i: number, gridColumns: number): DashboardWidget {
|
|
const what = `widgets[${i}]`;
|
|
const obj = asObject(raw, what);
|
|
rejectUnknownKeys(
|
|
obj,
|
|
['widget_id', 'title', 'source', 'visualization', 'layout', 'filter_bindings', 'vendor_ref'],
|
|
what,
|
|
);
|
|
const widget_id = asIdentifier(obj.widget_id, `${what}.widget_id`);
|
|
const title = asString(obj.title, `${what}.title`, MAX_TITLE_LENGTH);
|
|
const source = parseSource(obj.source, `${what}.source`);
|
|
const visualization = parseVisualization(obj.visualization, `${what}.visualization`);
|
|
|
|
const layoutObj = asObject(obj.layout, `${what}.layout`);
|
|
rejectUnknownKeys(layoutObj, ['x', 'y', 'w', 'h'], `${what}.layout`);
|
|
const layout: WidgetLayout = {
|
|
x: asInteger(layoutObj.x, `${what}.layout.x`, 0, gridColumns - 1),
|
|
y: asInteger(layoutObj.y, `${what}.layout.y`, 0, 10_000),
|
|
w: asInteger(layoutObj.w, `${what}.layout.w`, 1, gridColumns),
|
|
h: asInteger(layoutObj.h, `${what}.layout.h`, 1, 200),
|
|
};
|
|
if (layout.x + layout.w > gridColumns) {
|
|
invalid(`${what}.layout overflows the ${gridColumns}-column grid (x=${layout.x}, w=${layout.w})`);
|
|
}
|
|
|
|
const widget: DashboardWidget = { widget_id, title, source, visualization, layout };
|
|
if (obj.filter_bindings !== undefined) {
|
|
if (!Array.isArray(obj.filter_bindings)) invalid(`${what}.filter_bindings must be an array`);
|
|
widget.filter_bindings = obj.filter_bindings.map((b, j) =>
|
|
asIdentifier(b, `${what}.filter_bindings[${j}]`),
|
|
);
|
|
}
|
|
if (obj.vendor_ref !== undefined) widget.vendor_ref = parseVendorRef(obj.vendor_ref, `${what}.vendor_ref`);
|
|
return widget;
|
|
}
|
|
|
|
/**
|
|
* Parse an untrusted dashboard document. Fail-closed everywhere: a field this
|
|
* function does not understand is a refusal, because "ignored for now" is how
|
|
* a Superset-only document ends up stored as canonical truth.
|
|
*/
|
|
export function parseDashboardDocument(raw: unknown): DashboardDocument {
|
|
const obj = asObject(raw, 'dashboard document');
|
|
rejectUnknownKeys(obj, DASHBOARD_DOCUMENT_KEYS, 'dashboard document');
|
|
|
|
const id = asIdentifier(obj.id, 'id');
|
|
const title = asString(obj.title, 'title', MAX_TITLE_LENGTH);
|
|
const version = asInteger(obj.version, 'version', 1, 1_000_000);
|
|
|
|
const layoutObj = asObject(obj.layout, 'layout');
|
|
rejectUnknownKeys(layoutObj, ['grid_columns', 'row_height_px'], 'layout');
|
|
const layout = {
|
|
grid_columns: asInteger(layoutObj.grid_columns, 'layout.grid_columns', 1, MAX_GRID_COLUMNS),
|
|
row_height_px: asInteger(layoutObj.row_height_px, 'layout.row_height_px', 8, 400),
|
|
};
|
|
|
|
const rawParameters = obj.parameters ?? [];
|
|
if (!Array.isArray(rawParameters)) invalid('parameters must be an array');
|
|
if (rawParameters.length > MAX_PARAMETERS) invalid(`at most ${MAX_PARAMETERS} parameters`);
|
|
const parameters = rawParameters.map((p, i) => parseParameter(p, i));
|
|
const parameterNames = new Set(parameters.map((p) => p.name));
|
|
if (parameterNames.size !== parameters.length) invalid('parameters contains duplicate names');
|
|
|
|
const rawFilters = obj.filters ?? [];
|
|
if (!Array.isArray(rawFilters)) invalid('filters must be an array');
|
|
if (rawFilters.length > MAX_FILTERS) invalid(`at most ${MAX_FILTERS} filters`);
|
|
const filters = rawFilters.map((f, i) => parseFilter(f, i, parameterNames));
|
|
const filterIds = new Set(filters.map((f) => f.filter_id));
|
|
if (filterIds.size !== filters.length) invalid('filters contains duplicate filter_id');
|
|
|
|
if (!Array.isArray(obj.widgets)) invalid('widgets must be an array');
|
|
if (obj.widgets.length === 0) invalid('a dashboard with no widgets has nothing to reconstruct');
|
|
if (obj.widgets.length > MAX_WIDGETS) invalid(`at most ${MAX_WIDGETS} widgets`);
|
|
const widgets = obj.widgets.map((w, i) => parseWidget(w, i, layout.grid_columns));
|
|
if (new Set(widgets.map((w) => w.widget_id)).size !== widgets.length) {
|
|
invalid('widgets contains duplicate widget_id');
|
|
}
|
|
for (const w of widgets) {
|
|
for (const b of w.filter_bindings ?? []) {
|
|
if (!filterIds.has(b)) invalid(`widget "${w.widget_id}" binds undeclared filter "${b}"`);
|
|
}
|
|
}
|
|
|
|
const refreshObj = asObject(obj.refresh, 'refresh');
|
|
rejectUnknownKeys(refreshObj, ['mode', 'interval_seconds', 'cron', 'max_staleness_seconds'], 'refresh');
|
|
const mode = asString(refreshObj.mode, 'refresh.mode');
|
|
if (!(REFRESH_MODES as readonly string[]).includes(mode)) invalid('refresh.mode is not a refresh mode');
|
|
const refresh: DashboardRefresh = {
|
|
mode: mode as RefreshMode,
|
|
max_staleness_seconds: asInteger(
|
|
refreshObj.max_staleness_seconds,
|
|
'refresh.max_staleness_seconds',
|
|
1,
|
|
MAX_STALENESS_SECONDS,
|
|
),
|
|
};
|
|
if (refresh.mode === 'interval') {
|
|
refresh.interval_seconds = asInteger(
|
|
refreshObj.interval_seconds,
|
|
'refresh.interval_seconds',
|
|
MIN_REFRESH_INTERVAL_SECONDS,
|
|
86_400,
|
|
);
|
|
if (refreshObj.cron !== undefined) invalid('refresh.cron is meaningless when mode is "interval"');
|
|
} else if (refresh.mode === 'scheduled') {
|
|
refresh.cron = asString(refreshObj.cron, 'refresh.cron', 128);
|
|
if (refreshObj.interval_seconds !== undefined) {
|
|
invalid('refresh.interval_seconds is meaningless when mode is "scheduled"');
|
|
}
|
|
} else if (refreshObj.interval_seconds !== undefined || refreshObj.cron !== undefined) {
|
|
invalid('refresh.mode is "manual" but a schedule was supplied');
|
|
}
|
|
|
|
const permObj = asObject(obj.permissions, 'permissions');
|
|
rejectUnknownKeys(permObj, ['visibility', 'roles', 'required_entitlement'], 'permissions');
|
|
const visibility = asString(permObj.visibility, 'permissions.visibility');
|
|
if (!(DASHBOARD_VISIBILITIES as readonly string[]).includes(visibility)) {
|
|
invalid('permissions.visibility is not a visibility');
|
|
}
|
|
const permissions: DashboardPermissions = { visibility: visibility as DashboardVisibility };
|
|
if (permObj.roles !== undefined) {
|
|
if (!Array.isArray(permObj.roles)) invalid('permissions.roles must be an array');
|
|
permissions.roles = permObj.roles.map((r, i) => asIdentifier(r, `permissions.roles[${i}]`));
|
|
}
|
|
if (permissions.visibility === 'roles' && (permissions.roles ?? []).length === 0) {
|
|
invalid(
|
|
'permissions.visibility is "roles" with no roles — an empty role list reads as "deny all" to one ' +
|
|
'implementation and "allow all" to the next; say which',
|
|
);
|
|
}
|
|
if (permObj.required_entitlement !== undefined) {
|
|
permissions.required_entitlement = asIdentifier(
|
|
permObj.required_entitlement,
|
|
'permissions.required_entitlement',
|
|
);
|
|
}
|
|
|
|
const doc: DashboardDocument = {
|
|
id,
|
|
title,
|
|
layout,
|
|
filters,
|
|
widgets,
|
|
parameters,
|
|
refresh,
|
|
permissions,
|
|
version,
|
|
};
|
|
if (obj.description !== undefined) doc.description = asString(obj.description, 'description', 2000);
|
|
if (obj.vendor_ref !== undefined) doc.vendor_ref = parseVendorRef(obj.vendor_ref, 'vendor_ref');
|
|
return doc;
|
|
}
|
|
|
|
// ── canonical hash ─────────────────────────────────────────────────────────
|
|
|
|
/**
|
|
* Stable ordering of every field that MEANS something, with `vendor_ref`
|
|
* omitted at both levels. Two documents that render identically hash
|
|
* identically even if their JSON key order differs or one of them has been
|
|
* round-tripped through a BI tool; a document whose meaning changed hashes
|
|
* differently. That is what makes `DashboardVersion.layout_hash` a usable
|
|
* identity for BI-P061 rollback.
|
|
*/
|
|
function canonicalize(doc: DashboardDocument): unknown {
|
|
return [
|
|
doc.id,
|
|
doc.title,
|
|
doc.description ?? '',
|
|
doc.version,
|
|
[doc.layout.grid_columns, doc.layout.row_height_px],
|
|
doc.parameters
|
|
.map((p) => [p.name, p.type, p.required, p.default_value ?? '', [...(p.allowed_values ?? [])].sort()])
|
|
.sort((a, b) => String(a[0]).localeCompare(String(b[0]))),
|
|
doc.filters
|
|
.map((f) => [f.filter_id, f.label, f.dimension, f.operator, f.default_values ?? [], f.locked ?? false])
|
|
.sort((a, b) => String(a[0]).localeCompare(String(b[0]))),
|
|
doc.widgets
|
|
.map((w) => [
|
|
w.widget_id,
|
|
w.title,
|
|
w.source.kind === 'metric'
|
|
? [
|
|
'metric',
|
|
w.source.dataset,
|
|
w.source.metric,
|
|
w.source.dimensions ?? [],
|
|
w.source.grain ?? '',
|
|
w.source.limit ?? 0,
|
|
]
|
|
: ['query', canonicalRequest(w.source.request)],
|
|
[
|
|
w.visualization.type,
|
|
w.visualization.encoding.x ?? '',
|
|
w.visualization.encoding.y ?? [],
|
|
w.visualization.encoding.series ?? '',
|
|
w.visualization.encoding.value ?? '',
|
|
Object.keys(w.visualization.options ?? {})
|
|
.sort()
|
|
.map((k) => [k, (w.visualization.options ?? {})[k]]),
|
|
],
|
|
[w.layout.x, w.layout.y, w.layout.w, w.layout.h],
|
|
[...(w.filter_bindings ?? [])].sort(),
|
|
])
|
|
.sort((a, b) => String(a[0]).localeCompare(String(b[0]))),
|
|
[
|
|
doc.refresh.mode,
|
|
doc.refresh.interval_seconds ?? 0,
|
|
doc.refresh.cron ?? '',
|
|
doc.refresh.max_staleness_seconds,
|
|
],
|
|
[
|
|
doc.permissions.visibility,
|
|
[...(doc.permissions.roles ?? [])].sort(),
|
|
doc.permissions.required_entitlement ?? '',
|
|
],
|
|
];
|
|
}
|
|
|
|
function canonicalRequest(r: AnalyticsQueryRequest): unknown {
|
|
return [
|
|
r.dataset,
|
|
[...r.metrics],
|
|
[...r.dimensions],
|
|
r.filters.map((f) => [f.dimension, f.operator, f.values ?? []]),
|
|
r.timeRange
|
|
? [r.timeRange.dimension ?? '', r.timeRange.from ?? '', r.timeRange.to ?? '', r.timeRange.grain ?? '']
|
|
: [],
|
|
(r.orderBy ?? []).map((o) => [o.ref, o.direction]),
|
|
r.limit ?? 0,
|
|
r.format ?? 'json',
|
|
];
|
|
}
|
|
|
|
/** sha256 of the canonical form. Fills `DashboardVersion.layout_hash`. */
|
|
export function dashboardDocumentHash(doc: DashboardDocument): string {
|
|
return crypto
|
|
.createHash('sha256')
|
|
.update(JSON.stringify(canonicalize(doc)))
|
|
.digest('hex');
|
|
}
|
|
|
|
// ── reconstruction (the DoD) ───────────────────────────────────────────────
|
|
|
|
export interface PlannedWidget {
|
|
widget_id: string;
|
|
title: string;
|
|
/** Runnable, contract-valid, engine-neutral. This is the DoD in one field. */
|
|
request: AnalyticsQueryRequest;
|
|
visualization: VisualizationSpec;
|
|
layout: WidgetLayout;
|
|
}
|
|
|
|
export interface DashboardPlan {
|
|
dashboard_id: string;
|
|
title: string;
|
|
document_hash: string;
|
|
grid_columns: number;
|
|
widgets: PlannedWidget[];
|
|
/** Parameter values actually bound, after defaults. Reported, not implied. */
|
|
bound_parameters: Record<string, string>;
|
|
}
|
|
|
|
export interface PlanOptions {
|
|
/** Caller-supplied parameter values. Validated against the declarations. */
|
|
parameters?: Record<string, string>;
|
|
/** Filter ids a viewer switched off. `locked` filters cannot be switched off. */
|
|
disabled_filter_ids?: string[];
|
|
}
|
|
|
|
function bindParameters(doc: DashboardDocument, supplied: Record<string, string>): Record<string, string> {
|
|
const bound: Record<string, string> = {};
|
|
const declared = new Set(doc.parameters.map((p) => p.name));
|
|
for (const name of Object.keys(supplied)) {
|
|
if (!declared.has(name)) invalid(`parameter "${name}" is not declared by this dashboard`);
|
|
}
|
|
for (const p of doc.parameters) {
|
|
const value = supplied[p.name] ?? p.default_value;
|
|
if (value === undefined) {
|
|
if (p.required) invalid(`required parameter "${p.name}" was not supplied`);
|
|
continue;
|
|
}
|
|
if (p.allowed_values && !p.allowed_values.includes(value)) {
|
|
invalid(`parameter "${p.name}" value is not in its allowed_values`);
|
|
}
|
|
if (p.type === 'number' && !Number.isFinite(Number(value))) {
|
|
invalid(`parameter "${p.name}" is declared number but "${value}" is not numeric`);
|
|
}
|
|
if (p.type === 'date' && Number.isNaN(Date.parse(value))) {
|
|
invalid(`parameter "${p.name}" is declared date but "${value}" is not an ISO date`);
|
|
}
|
|
bound[p.name] = value;
|
|
}
|
|
return bound;
|
|
}
|
|
|
|
function resolveFilterValues(f: DashboardFilter, bound: Record<string, string>): string[] | undefined {
|
|
if (!f.default_values) return undefined;
|
|
return f.default_values.map((v) => {
|
|
const m = PARAM_REFERENCE.exec(v);
|
|
if (!m) return v;
|
|
const value = bound[m[1]];
|
|
if (value === undefined) {
|
|
invalid(`filter "${f.filter_id}" references parameter "${m[1]}", which has no value`);
|
|
}
|
|
return value;
|
|
});
|
|
}
|
|
|
|
/**
|
|
* Turn a dashboard document into runnable analytics requests.
|
|
*
|
|
* This IS BI-P060's DoD. If this function returns a plan, the dashboard can be
|
|
* rendered by anything that can execute `AnalyticsQueryRequest` and draw the
|
|
* twelve visualization types — Superset not required, not consulted, and not
|
|
* present anywhere in the output.
|
|
*/
|
|
export function planDashboard(doc: DashboardDocument, options: PlanOptions = {}): DashboardPlan {
|
|
const bound = bindParameters(doc, options.parameters ?? {});
|
|
const disabled = new Set(options.disabled_filter_ids ?? []);
|
|
for (const f of doc.filters) {
|
|
if (disabled.has(f.filter_id) && f.locked) {
|
|
invalid(
|
|
`filter "${f.filter_id}" is locked and cannot be disabled — locked filters are how a saved ` +
|
|
`dashboard pins its scope, and a viewer removing one silently widens the result set`,
|
|
);
|
|
}
|
|
}
|
|
|
|
const widgets = doc.widgets.map((w) => {
|
|
const applicable = doc.filters.filter(
|
|
(f) =>
|
|
!disabled.has(f.filter_id) &&
|
|
(w.filter_bindings === undefined || w.filter_bindings.length === 0
|
|
? true
|
|
: w.filter_bindings.includes(f.filter_id)),
|
|
);
|
|
const dashboardFilters: AnalyticsFilter[] = applicable.map((f) => {
|
|
const values = resolveFilterValues(f, bound);
|
|
const af: AnalyticsFilter = { dimension: f.dimension, operator: f.operator };
|
|
if (values !== undefined) af.values = values;
|
|
return af;
|
|
});
|
|
|
|
const base =
|
|
w.source.kind === 'metric'
|
|
? {
|
|
dataset: w.source.dataset,
|
|
metrics: [w.source.metric],
|
|
dimensions: w.source.dimensions ?? [],
|
|
filters: [] as AnalyticsFilter[],
|
|
...(w.source.grain ? { timeRange: { grain: w.source.grain } } : {}),
|
|
...(w.source.limit ? { limit: w.source.limit } : {}),
|
|
}
|
|
: {
|
|
...w.source.request,
|
|
timeRange: w.source.request.timeRange,
|
|
};
|
|
|
|
// Re-parse the merged request rather than trusting the merge: the filters
|
|
// we just added come from the document, and a document is untrusted input
|
|
// even after it has been stored.
|
|
const request = parseAnalyticsQueryRequest({
|
|
...base,
|
|
filters: [...(w.source.kind === 'query' ? w.source.request.filters : []), ...dashboardFilters],
|
|
});
|
|
|
|
return {
|
|
widget_id: w.widget_id,
|
|
title: w.title,
|
|
request,
|
|
visualization: w.visualization,
|
|
layout: w.layout,
|
|
};
|
|
});
|
|
|
|
return {
|
|
dashboard_id: doc.id,
|
|
title: doc.title,
|
|
document_hash: dashboardDocumentHash(doc),
|
|
grid_columns: doc.layout.grid_columns,
|
|
widgets,
|
|
bound_parameters: bound,
|
|
};
|
|
}
|