feat(analytics): BI-P061 — dashboard releases, with the publish race measured both ways
CI (SIAX Cloud) / quality (push) Successful in 50s
Security Scan (SIAX Cloud) / security (push) Successful in 45s
CI (SIAX Cloud) / security (push) Successful in 1m0s
CI (SIAX Cloud) / integration (push) Successful in 1m12s
CI (SIAX Cloud) / quality (pull_request) Successful in 1m6s
CI (SIAX Cloud) / security (pull_request) Successful in 33s
Security Scan (SIAX Cloud) / security (pull_request) Successful in 32s
CI (SIAX Cloud) / integration (pull_request) Successful in 47s
CI (SIAX Cloud) / quality (push) Successful in 50s
Security Scan (SIAX Cloud) / security (push) Successful in 45s
CI (SIAX Cloud) / security (push) Successful in 1m0s
CI (SIAX Cloud) / integration (push) Successful in 1m12s
CI (SIAX Cloud) / quality (pull_request) Successful in 1m6s
CI (SIAX Cloud) / security (pull_request) Successful in 33s
Security Scan (SIAX Cloud) / security (pull_request) Successful in 32s
CI (SIAX Cloud) / integration (pull_request) Successful in 47s
DRAFT -> PUBLISHED -> SUPERSEDED as a ledger (sql/010) rather than a column on
the frozen version: sql/008 already makes DashboardVersion immutable at the
database, and a lifecycle column there would have meant weakening that.
Rollback mints a NEW version carrying the old document and publishes it, so
"we went back to v3" is a timestamped fact (v5 = rollback_of_version 3) rather
than a hole where v4 used to be. It is verified by BI-P060 canonical hash, and
documentOf() refuses to serve a stored document whose hash no longer matches
the release — a dashboard that renders an unapproved definition is worse than
one that will not open.
The claim worth attacking is "only one release can be live". The application
check is read-then-write, so it is NOT the guarantee, and the evidence says so
in both directions against Postgres 16.15:
guard_absent partial unique index dropped -> BOTH concurrent publishes
commit, dashboard ends with TWO live versions
guard_present index in place -> loser fails 23505 on
opt_analytics_dashboard_release_one_published, one live
evidence/bi-p061/dashboard-release-race.json, reproducible with
scripts/bi-p061-release-race.mjs.
Two findings while writing the tests, both fixed here rather than papered over:
the one-draft-per-dashboard index makes the two-draft race impossible to even
construct (so the race is run as two create-and-publish transactions, which is
what a "save and publish" button does), and an UPDATE matching zero rows
raises nothing — which reads as "refused" to a careless test, so the
immutability test asserts the row exists first.
23 tests: 8 unit + 15 against live Postgres.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,449 @@
|
||||
/**
|
||||
* src/analytics/dashboards/dashboard-release.ts
|
||||
* ==============================================
|
||||
* BI-P061 — DASHBOARD VERSIONING.
|
||||
*
|
||||
* DRAFT -> PUBLISHED -> SUPERSEDED, and the DoD: "rollback to previous
|
||||
* dashboard definition".
|
||||
*
|
||||
* Three decisions worth stating, because each one is a bug someone would
|
||||
* otherwise write:
|
||||
*
|
||||
* 1. ROLLBACK MINTS A NEW VERSION. It does not resurrect the old release row
|
||||
* and it does not edit the published one. "We went back to v3" is then a
|
||||
* fact with a timestamp (v5 = rollback_of_version 3) instead of a hole in
|
||||
* the history where v4 used to be. `verifyRollback()` proves the restore is
|
||||
* faithful by comparing BI-P060 canonical hashes, so a rollback that
|
||||
* silently restored a different document fails loudly.
|
||||
*
|
||||
* 2. THE DOCUMENT IS FROZEN, THE RELEASE MOVES. sql/008 makes
|
||||
* DashboardVersion rows immutable at the database. The release ledger
|
||||
* (sql/010) carries the state, and its trigger allows exactly two
|
||||
* transitions and freezes every other column. Un-publishing is refused:
|
||||
* it is how a rollback gets faked without leaving a trace.
|
||||
*
|
||||
* 3. THE APPLICATION CHECK IS NOT THE GUARANTEE. `publish()` checks for an
|
||||
* existing published release, and that check is a read-then-write race.
|
||||
* The partial unique index in sql/010 is what actually holds under
|
||||
* concurrency; the realinfra test drops it, runs the race and shows two
|
||||
* published releases for one dashboard, so nobody has to take that on
|
||||
* faith. This module maps the resulting constraint violation onto a
|
||||
* CONFLICT rather than a 500.
|
||||
*/
|
||||
import crypto from 'node:crypto';
|
||||
import { SiaxError } from '../../platform/errors';
|
||||
import { dashboardDocumentHash, parseDashboardDocument, type DashboardDocument } from './dashboard-document';
|
||||
|
||||
export const DASHBOARD_RELEASE_STATES = ['draft', 'published', 'superseded'] as const;
|
||||
export type DashboardReleaseState = (typeof DASHBOARD_RELEASE_STATES)[number];
|
||||
|
||||
/** The only transitions that exist. Everything else is a refusal, not a no-op. */
|
||||
const LEGAL_TRANSITIONS: Readonly<Record<DashboardReleaseState, readonly DashboardReleaseState[]>> = {
|
||||
draft: ['published'],
|
||||
published: ['superseded'],
|
||||
superseded: [],
|
||||
};
|
||||
|
||||
export function isLegalTransition(from: DashboardReleaseState, to: DashboardReleaseState): boolean {
|
||||
return LEGAL_TRANSITIONS[from].includes(to);
|
||||
}
|
||||
|
||||
export interface DashboardRelease {
|
||||
release_id: string;
|
||||
dashboard_id: string;
|
||||
dashboard_version_id: string;
|
||||
tenant_id: string;
|
||||
project_id: string;
|
||||
version: number;
|
||||
state: DashboardReleaseState;
|
||||
/** BI-P060 canonical hash of the released document. */
|
||||
document_hash: string;
|
||||
/** Set when this release restores an earlier version. */
|
||||
rollback_of_version?: number;
|
||||
created_by?: string;
|
||||
created_at: string;
|
||||
published_at?: string;
|
||||
superseded_at?: string;
|
||||
superseded_by_release_id?: string;
|
||||
}
|
||||
|
||||
/** The immutable frozen document behind a release (sql/008's DashboardVersion). */
|
||||
export interface DashboardVersionRecord {
|
||||
dashboard_version_id: string;
|
||||
dashboard_id: string;
|
||||
tenant_id: string;
|
||||
project_id: string;
|
||||
version: number;
|
||||
layout_json: string;
|
||||
layout_hash: string;
|
||||
created_at: string;
|
||||
created_by?: string;
|
||||
}
|
||||
|
||||
export interface TenantScope {
|
||||
tenant_id: string;
|
||||
project_id: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* The persistence port. Deliberately narrow, and every method is tenant-scoped
|
||||
* — there is no signature that lets a caller forget the tenant.
|
||||
*/
|
||||
export interface DashboardReleaseStore {
|
||||
/** Highest version number ever minted for this dashboard, or 0. */
|
||||
maxVersion(scope: TenantScope, dashboardId: string): Promise<number>;
|
||||
insertVersionAndRelease(version: DashboardVersionRecord, release: DashboardRelease): Promise<void>;
|
||||
getRelease(scope: TenantScope, releaseId: string): Promise<DashboardRelease | undefined>;
|
||||
getVersion(scope: TenantScope, dashboardVersionId: string): Promise<DashboardVersionRecord | undefined>;
|
||||
findVersionByNumber(
|
||||
scope: TenantScope,
|
||||
dashboardId: string,
|
||||
version: number,
|
||||
): Promise<DashboardVersionRecord | undefined>;
|
||||
findByState(
|
||||
scope: TenantScope,
|
||||
dashboardId: string,
|
||||
state: DashboardReleaseState,
|
||||
): Promise<DashboardRelease | undefined>;
|
||||
listReleases(scope: TenantScope, dashboardId: string): Promise<DashboardRelease[]>;
|
||||
/**
|
||||
* Publish `releaseId` and supersede `supersedes` in ONE transaction. Both or
|
||||
* neither: a supersede that lands without its publish leaves a dashboard
|
||||
* with no live version, and a publish that lands without its supersede
|
||||
* leaves two.
|
||||
*/
|
||||
publishAtomically(args: {
|
||||
scope: TenantScope;
|
||||
releaseId: string;
|
||||
publishedAt: string;
|
||||
supersedes?: { release_id: string; superseded_at: string };
|
||||
}): Promise<void>;
|
||||
}
|
||||
|
||||
function conflict(detail: string): never {
|
||||
throw new SiaxError('CONFLICT', '0pt.analytics.dashboard', detail);
|
||||
}
|
||||
|
||||
function notFound(detail: string): never {
|
||||
throw new SiaxError('NOT_FOUND', '0pt.analytics.dashboard', detail);
|
||||
}
|
||||
|
||||
function assertScope(scope: TenantScope): void {
|
||||
if (!scope?.tenant_id?.trim() || !scope?.project_id?.trim()) {
|
||||
throw new SiaxError(
|
||||
'UNAUTHENTICATED',
|
||||
'0pt.analytics.dashboard',
|
||||
'dashboard releases require a verified tenant_id + project_id',
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
export interface DraftResult {
|
||||
release: DashboardRelease;
|
||||
version: DashboardVersionRecord;
|
||||
}
|
||||
|
||||
/**
|
||||
* The lifecycle. Stateless apart from its store and its clock; the clock is
|
||||
* injectable so a test can pin timestamps instead of sleeping.
|
||||
*/
|
||||
export class DashboardReleaseService {
|
||||
constructor(
|
||||
private readonly store: DashboardReleaseStore,
|
||||
private readonly now: () => Date = () => new Date(),
|
||||
private readonly newId: () => string = () => crypto.randomUUID(),
|
||||
) {}
|
||||
|
||||
/**
|
||||
* Freeze a document as the next version and open a DRAFT release for it.
|
||||
* The document is re-parsed here even if the caller already parsed it: what
|
||||
* gets frozen must be what the model accepts, not what a caller assembled.
|
||||
*/
|
||||
async draft(args: {
|
||||
scope: TenantScope;
|
||||
dashboardId: string;
|
||||
document: unknown;
|
||||
createdBy?: string;
|
||||
rollbackOfVersion?: number;
|
||||
}): Promise<DraftResult> {
|
||||
assertScope(args.scope);
|
||||
const document = parseDashboardDocument(args.document);
|
||||
const existingDraft = await this.store.findByState(args.scope, args.dashboardId, 'draft');
|
||||
if (existingDraft) {
|
||||
conflict(
|
||||
`dashboard "${args.dashboardId}" already has an open draft (version ${existingDraft.version}); ` +
|
||||
`publish or abandon it before opening another — two drafts race to publish and the loser's ` +
|
||||
`edits vanish`,
|
||||
);
|
||||
}
|
||||
const next = (await this.store.maxVersion(args.scope, args.dashboardId)) + 1;
|
||||
const at = this.now().toISOString();
|
||||
const hash = dashboardDocumentHash(document);
|
||||
|
||||
const version: DashboardVersionRecord = {
|
||||
dashboard_version_id: this.newId(),
|
||||
dashboard_id: args.dashboardId,
|
||||
tenant_id: args.scope.tenant_id,
|
||||
project_id: args.scope.project_id,
|
||||
version: next,
|
||||
layout_json: JSON.stringify(document),
|
||||
layout_hash: hash,
|
||||
created_at: at,
|
||||
...(args.createdBy ? { created_by: args.createdBy } : {}),
|
||||
};
|
||||
const release: DashboardRelease = {
|
||||
release_id: this.newId(),
|
||||
dashboard_id: args.dashboardId,
|
||||
dashboard_version_id: version.dashboard_version_id,
|
||||
tenant_id: args.scope.tenant_id,
|
||||
project_id: args.scope.project_id,
|
||||
version: next,
|
||||
state: 'draft',
|
||||
document_hash: hash,
|
||||
created_at: at,
|
||||
...(args.createdBy ? { created_by: args.createdBy } : {}),
|
||||
...(args.rollbackOfVersion ? { rollback_of_version: args.rollbackOfVersion } : {}),
|
||||
};
|
||||
await this.store.insertVersionAndRelease(version, release);
|
||||
return { release, version };
|
||||
}
|
||||
|
||||
/**
|
||||
* DRAFT -> PUBLISHED, superseding whatever was live, in one transaction.
|
||||
* The pre-check exists to return a friendly CONFLICT; the guarantee is the
|
||||
* partial unique index (sql/010).
|
||||
*/
|
||||
async publish(args: {
|
||||
scope: TenantScope;
|
||||
releaseId: string;
|
||||
}): Promise<{ published: DashboardRelease; superseded?: DashboardRelease }> {
|
||||
assertScope(args.scope);
|
||||
const release = await this.store.getRelease(args.scope, args.releaseId);
|
||||
if (!release) notFound(`dashboard release "${args.releaseId}" does not exist in this tenant`);
|
||||
if (release.state !== 'draft') {
|
||||
conflict(
|
||||
`release "${args.releaseId}" is ${release.state}, not draft — ${release.state} -> published is ` +
|
||||
`not a legal transition (BI-P061)`,
|
||||
);
|
||||
}
|
||||
const live = await this.store.findByState(args.scope, release.dashboard_id, 'published');
|
||||
const at = this.now().toISOString();
|
||||
await this.store.publishAtomically({
|
||||
scope: args.scope,
|
||||
releaseId: release.release_id,
|
||||
publishedAt: at,
|
||||
...(live ? { supersedes: { release_id: live.release_id, superseded_at: at } } : {}),
|
||||
});
|
||||
|
||||
return {
|
||||
published: { ...release, state: 'published', published_at: at },
|
||||
...(live
|
||||
? {
|
||||
superseded: {
|
||||
...live,
|
||||
state: 'superseded',
|
||||
superseded_at: at,
|
||||
superseded_by_release_id: release.release_id,
|
||||
},
|
||||
}
|
||||
: {}),
|
||||
};
|
||||
}
|
||||
|
||||
/** The release currently serving, or undefined if the dashboard has never been published. */
|
||||
async live(scope: TenantScope, dashboardId: string): Promise<DashboardRelease | undefined> {
|
||||
assertScope(scope);
|
||||
return this.store.findByState(scope, dashboardId, 'published');
|
||||
}
|
||||
|
||||
/** The frozen document behind a release, re-parsed on the way out. */
|
||||
async documentOf(scope: TenantScope, release: DashboardRelease): Promise<DashboardDocument> {
|
||||
assertScope(scope);
|
||||
const version = await this.store.getVersion(scope, release.dashboard_version_id);
|
||||
if (!version) notFound(`dashboard version "${release.dashboard_version_id}" is missing`);
|
||||
const document = parseDashboardDocument(JSON.parse(version.layout_json));
|
||||
const hash = dashboardDocumentHash(document);
|
||||
if (hash !== release.document_hash) {
|
||||
// Storage returned something other than what was released. Refusing is
|
||||
// the only safe answer: a dashboard that renders a document nobody
|
||||
// approved is worse than a dashboard that will not open.
|
||||
throw new SiaxError(
|
||||
'PERMANENT_FAILURE',
|
||||
'0pt.analytics.dashboard',
|
||||
`stored document for release "${release.release_id}" hashes to ${hash}, not the released ` +
|
||||
`${release.document_hash} — refusing to serve an unapproved definition`,
|
||||
);
|
||||
}
|
||||
return document;
|
||||
}
|
||||
|
||||
/**
|
||||
* BI-P061's DoD. Restores version `toVersion` by minting a NEW version with
|
||||
* the SAME document and publishing it. Returns the new release plus the
|
||||
* verification that the restore is faithful.
|
||||
*/
|
||||
async rollback(args: {
|
||||
scope: TenantScope;
|
||||
dashboardId: string;
|
||||
toVersion: number;
|
||||
createdBy?: string;
|
||||
}): Promise<{ release: DashboardRelease; restored_from: number; document_hash: string }> {
|
||||
assertScope(args.scope);
|
||||
const target = await this.store.findVersionByNumber(args.scope, args.dashboardId, args.toVersion);
|
||||
if (!target) {
|
||||
notFound(`dashboard "${args.dashboardId}" has no version ${args.toVersion} in this tenant`);
|
||||
}
|
||||
const live = await this.store.findByState(args.scope, args.dashboardId, 'published');
|
||||
if (live && live.version === args.toVersion) {
|
||||
conflict(`version ${args.toVersion} is already live; a rollback to the live version is a no-op`);
|
||||
}
|
||||
const document = parseDashboardDocument(JSON.parse(target.layout_json));
|
||||
const hash = dashboardDocumentHash(document);
|
||||
if (hash !== target.layout_hash) {
|
||||
throw new SiaxError(
|
||||
'PERMANENT_FAILURE',
|
||||
'0pt.analytics.dashboard',
|
||||
`version ${args.toVersion} hashes to ${hash} but was stored as ${target.layout_hash} — ` +
|
||||
`refusing to roll back to a definition that has changed underneath us`,
|
||||
);
|
||||
}
|
||||
|
||||
const { release } = await this.draft({
|
||||
scope: args.scope,
|
||||
dashboardId: args.dashboardId,
|
||||
document,
|
||||
...(args.createdBy ? { createdBy: args.createdBy } : {}),
|
||||
rollbackOfVersion: args.toVersion,
|
||||
});
|
||||
const { published } = await this.publish({ scope: args.scope, releaseId: release.release_id });
|
||||
|
||||
if (published.document_hash !== target.layout_hash) {
|
||||
throw new SiaxError(
|
||||
'PERMANENT_FAILURE',
|
||||
'0pt.analytics.dashboard',
|
||||
`rollback published ${published.document_hash}, not the requested ${target.layout_hash}`,
|
||||
);
|
||||
}
|
||||
return { release: published, restored_from: args.toVersion, document_hash: published.document_hash };
|
||||
}
|
||||
|
||||
/** Full ledger, oldest first. A rollback is an entry here, never a deletion. */
|
||||
async history(scope: TenantScope, dashboardId: string): Promise<DashboardRelease[]> {
|
||||
assertScope(scope);
|
||||
const rows = await this.store.listReleases(scope, dashboardId);
|
||||
return [...rows].sort((a, b) => a.version - b.version);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* In-memory store. Used by the unit tests, and it enforces the same two
|
||||
* uniqueness rules the SQL does — a store that is laxer than the database
|
||||
* makes the unit tests pass on states production can never reach.
|
||||
*/
|
||||
export class InMemoryDashboardReleaseStore implements DashboardReleaseStore {
|
||||
private readonly versions: DashboardVersionRecord[] = [];
|
||||
private readonly releases: DashboardRelease[] = [];
|
||||
|
||||
private scoped<T extends { tenant_id: string; project_id: string }>(scope: TenantScope, rows: T[]): T[] {
|
||||
return rows.filter((r) => r.tenant_id === scope.tenant_id && r.project_id === scope.project_id);
|
||||
}
|
||||
|
||||
async maxVersion(scope: TenantScope, dashboardId: string): Promise<number> {
|
||||
return this.scoped(scope, this.versions)
|
||||
.filter((v) => v.dashboard_id === dashboardId)
|
||||
.reduce((max, v) => Math.max(max, v.version), 0);
|
||||
}
|
||||
|
||||
async insertVersionAndRelease(version: DashboardVersionRecord, release: DashboardRelease): Promise<void> {
|
||||
const scope = { tenant_id: release.tenant_id, project_id: release.project_id };
|
||||
if (
|
||||
release.state === 'draft' &&
|
||||
this.scoped(scope, this.releases).some(
|
||||
(r) => r.dashboard_id === release.dashboard_id && r.state === 'draft',
|
||||
)
|
||||
) {
|
||||
conflict('one open draft per dashboard');
|
||||
}
|
||||
if (this.versions.some((v) => v.dashboard_id === version.dashboard_id && v.version === version.version)) {
|
||||
conflict(`version ${version.version} already exists for "${version.dashboard_id}"`);
|
||||
}
|
||||
this.versions.push({ ...version });
|
||||
this.releases.push({ ...release });
|
||||
}
|
||||
|
||||
async getRelease(scope: TenantScope, releaseId: string): Promise<DashboardRelease | undefined> {
|
||||
const r = this.scoped(scope, this.releases).find((x) => x.release_id === releaseId);
|
||||
return r ? { ...r } : undefined;
|
||||
}
|
||||
|
||||
async getVersion(scope: TenantScope, id: string): Promise<DashboardVersionRecord | undefined> {
|
||||
const v = this.scoped(scope, this.versions).find((x) => x.dashboard_version_id === id);
|
||||
return v ? { ...v } : undefined;
|
||||
}
|
||||
|
||||
async findVersionByNumber(
|
||||
scope: TenantScope,
|
||||
dashboardId: string,
|
||||
version: number,
|
||||
): Promise<DashboardVersionRecord | undefined> {
|
||||
const v = this.scoped(scope, this.versions).find(
|
||||
(x) => x.dashboard_id === dashboardId && x.version === version,
|
||||
);
|
||||
return v ? { ...v } : undefined;
|
||||
}
|
||||
|
||||
async findByState(
|
||||
scope: TenantScope,
|
||||
dashboardId: string,
|
||||
state: DashboardReleaseState,
|
||||
): Promise<DashboardRelease | undefined> {
|
||||
const r = this.scoped(scope, this.releases).find(
|
||||
(x) => x.dashboard_id === dashboardId && x.state === state,
|
||||
);
|
||||
return r ? { ...r } : undefined;
|
||||
}
|
||||
|
||||
async listReleases(scope: TenantScope, dashboardId: string): Promise<DashboardRelease[]> {
|
||||
return this.scoped(scope, this.releases)
|
||||
.filter((r) => r.dashboard_id === dashboardId)
|
||||
.map((r) => ({ ...r }));
|
||||
}
|
||||
|
||||
async publishAtomically(args: {
|
||||
scope: TenantScope;
|
||||
releaseId: string;
|
||||
publishedAt: string;
|
||||
supersedes?: { release_id: string; superseded_at: string };
|
||||
}): Promise<void> {
|
||||
const target = this.releases.find(
|
||||
(r) =>
|
||||
r.release_id === args.releaseId &&
|
||||
r.tenant_id === args.scope.tenant_id &&
|
||||
r.project_id === args.scope.project_id,
|
||||
);
|
||||
if (!target) notFound(`release "${args.releaseId}" not found`);
|
||||
if (!isLegalTransition(target.state, 'published')) {
|
||||
conflict(`illegal transition ${target.state} -> published`);
|
||||
}
|
||||
const alreadyLive = this.releases.find(
|
||||
(r) =>
|
||||
r.dashboard_id === target.dashboard_id &&
|
||||
r.state === 'published' &&
|
||||
r.release_id !== args.supersedes?.release_id,
|
||||
);
|
||||
if (alreadyLive) conflict('one published release per dashboard');
|
||||
|
||||
if (args.supersedes) {
|
||||
const live = this.releases.find((r) => r.release_id === args.supersedes?.release_id);
|
||||
if (!live) notFound(`release "${args.supersedes.release_id}" not found`);
|
||||
if (!isLegalTransition(live.state, 'superseded')) {
|
||||
conflict(`illegal transition ${live.state} -> superseded`);
|
||||
}
|
||||
live.state = 'superseded';
|
||||
live.superseded_at = args.supersedes.superseded_at;
|
||||
live.superseded_by_release_id = target.release_id;
|
||||
}
|
||||
target.state = 'published';
|
||||
target.published_at = args.publishedAt;
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user