Merge pull request Sofie-Automation#1754 from bbc/feat/hook-on-snapshot-creation

feat: blueprint hooks on snapshot creation

Author: justandras

meteor/server/api/snapshot.ts

@@ -40,7 +40,7 @@ import { CURRENT_SYSTEM_VERSION } from '../migration/currentSystemVersion'
 import { isVersionSupported } from '../migration/databaseMigration'
 import { DBShowStyleVariant } from '@sofie-automation/corelib/dist/dataModel/ShowStyleVariant'
 import { Blueprint } from '@sofie-automation/corelib/dist/dataModel/Blueprint'
-import { IngestRundown, VTContent } from '@sofie-automation/blueprints-integration'
+import { BlueprintSnapshotType, IngestRundown, VTContent } from '@sofie-automation/blueprints-integration'
 import { MongoQuery } from '@sofie-automation/corelib/dist/mongo'
 import { importIngestRundown } from './ingest/http'
 import { DBRundownPlaylist } from '@sofie-automation/corelib/dist/dataModel/RundownPlaylist/RundownPlaylist'
@@ -327,7 +327,8 @@ function getPiecesMediaObjects(pieces: PieceGeneric[]): string[] {
 
 async function createRundownPlaylistSnapshot(
 	playlist: VerifiedRundownPlaylistForUserAction,
-	options: PlaylistSnapshotOptions
+	options: PlaylistSnapshotOptions,
+	reason?: string
 ): Promise<RundownPlaylistSnapshot> {
 	/** Max count of one type of items to include in the snapshot */
 	const LIMIT_COUNT = 500
@@ -343,6 +344,8 @@ async function createRundownPlaylistSnapshot(
 		playlistId: playlist._id,
 		full: !!options.withArchivedDocuments,
 		withTimeline: !!options.withTimeline,
+		snapshotId,
+		reason,
 	})
 	const coreResult = await queuedJob.complete
 	const coreSnapshot: CoreRundownPlaylistSnapshot = JSONBlobParse(coreResult.snapshotJson)
@@ -693,27 +696,71 @@ export async function storeSystemSnapshot(
 
 	return internalStoreSystemSnapshot(options, reason)
 }
+/**
+ * Runs {@link StudioJobs.OnSystemSnapshotCreated} for each studio after a snapshot is stored.
+ *
+ * Studio-scoped system snapshots run one job; full-system snapshots run one job per studio in the snapshot.
+ * Waits for each blueprint hook to finish; hook failures are logged and do not fail snapshot storage.
+ */
+async function queueOnSystemSnapshotCreatedJobs(
+	storedId: SnapshotId,
+	reason: string,
+	type: BlueprintSnapshotType,
+	options: SystemSnapshotOptions,
+	studioIds: StudioId[]
+): Promise<void> {
+	const fullSystem = !options.studioId
+
+	for (const studioId of studioIds) {
+		try {
+			const job = await QueueStudioJob(StudioJobs.OnSystemSnapshotCreated, studioId, {
+				snapshotId: storedId,
+				reason,
+				type,
+				options: {
+					studioId,
+					withDeviceSnapshots: options.withDeviceSnapshots,
+					fullSystem,
+				},
+			})
+			await job.complete
+		} catch (err) {
+			logger.error(
+				`OnSystemSnapshotCreated failed for snapshot ${storedId} (studio ${studioId}, withDeviceSnapshots=${options.withDeviceSnapshots}): ${stringifyError(err)}`
+			)
+		}
+	}
+}
+
 /** Take and store a system snapshot. For internal use only, performs no access control. */
 export async function internalStoreSystemSnapshot(options: SystemSnapshotOptions, reason: string): Promise<SnapshotId> {
 	check(options.studioId, Match.Optional(String))
 
 	const s = await createSystemSnapshot(options)
-	return storeSnaphot(s, reason)
+	const storedId = await storeSnaphot(s, reason)
+
+	// Full-system snapshots: one blueprint hook job per studio in the snapshot
+	const studioIds = options.studioId ? [options.studioId] : s.studios.map((studio) => studio._id)
+	if (studioIds.length > 0) {
+		await queueOnSystemSnapshotCreatedJobs(storedId, reason, 'system', options, studioIds)
+	}
+
+	return storedId
 }
 export async function storeRundownPlaylistSnapshot(
 	playlist: VerifiedRundownPlaylistForUserAction,
 	options: PlaylistSnapshotOptions,
 	reason: string
 ): Promise<SnapshotId> {
-	const s = await createRundownPlaylistSnapshot(playlist, options)
+	const s = await createRundownPlaylistSnapshot(playlist, options, reason)
 	return storeSnaphot(s, reason)
 }
 export async function internalStoreRundownPlaylistSnapshot(
 	playlist: DBRundownPlaylist,
 	options: PlaylistSnapshotOptions,
 	reason: string
 ): Promise<SnapshotId> {
-	const s = await createRundownPlaylistSnapshot(playlist, options)
+	const s = await createRundownPlaylistSnapshot(playlist, options, reason)
 	return storeSnaphot(s, reason)
 }
 export async function storeDebugSnapshot(
@@ -731,7 +778,13 @@ export async function storeDebugSnapshot(
 	assertConnectionHasOneOfPermissions(context.connection, ...PERMISSIONS_FOR_SNAPSHOT_MANAGEMENT)
 
 	const s = await createDebugSnapshot(studioId)
-	return storeSnaphot(s, reason)
+	const storedId = await storeSnaphot(s, reason)
+
+	await queueOnSystemSnapshotCreatedJobs(storedId, reason, 'debug', { studioId, withDeviceSnapshots: true }, [
+		studioId,
+	])
+
+	return storedId
 }
 export async function restoreSnapshot(
 	context: MethodContext,

packages/blueprints-integration/src/api/showStyle.ts

@@ -18,6 +18,8 @@ import type {
 	IFixUpConfigContext,
 	IOnTakeContext,
 	IOnSetAsNextContext,
+	IPlaylistSnapshotCreatedContext,
+	IBlueprintPlaylistSnapshotInfo,
 } from '../context/index.js'
 import type { IngestAdlib, ExtendedIngestRundown, IngestRundown } from '../ingest.js'
 import type { IBlueprintExternalMessageQueueObj } from '../message.js'
@@ -201,6 +203,25 @@ export interface ShowStyleBlueprintManifest<
 
 	// Events
 
+	/**
+	 * Called after a rundown playlist snapshot has been generated, before Meteor persists the snapshot file.
+	 *
+	 * Use this to run show-specific side effects (e.g. TSR actions) when a playlist snapshot is taken.
+	 * The callback receives {@link IPlaylistSnapshotCreatedContext} with `listPlayoutDevices` and `executeTSRAction`.
+	 *
+	 * For playlists containing multiple rundowns, only one show-style blueprint is invoked per snapshot:
+	 * current part, then next part, then first rundown by name.
+	 *
+	 * Errors are logged by Core and do not fail snapshot generation or storage.
+	 *
+	 * @param context Show-style and studio context with TSR actions for the studio worker job.
+	 * @param info Metadata about the snapshot (not the snapshot JSON).
+	 */
+	onPlaylistSnapshotCreated?: (
+		context: IPlaylistSnapshotCreatedContext,
+		info: IBlueprintPlaylistSnapshotInfo
+	) => Promise<void>
+
 	/**
 	 * Called at the final stage of RundownPlaylist activation, before the updated timeline is submitted to the Playout Gateway,
 	 * This is a good place to prepare any external systems for the rundown going live.

packages/blueprints-integration/src/api/studio.ts

@@ -9,6 +9,9 @@ import type {
 	IStudioBaselineContext,
 	IStudioUserContext,
 	IProcessIngestDataContext,
+	ISystemSnapshotCreatedContext,
+	IBlueprintSystemSnapshotInfo,
+	BlueprintSnapshotType as _BlueprintSnapshotType,
 } from '../context/index.js'
 import type { IBlueprintShowStyleBase } from '../showStyle.js'
 import type {
@@ -193,6 +196,27 @@ export interface StudioBlueprintManifest<
 		previousNrcsIngestRundown: IngestRundown | undefined,
 		changes: NrcsIngestChangeDetails | UserOperationChange | PlayoutOperationChange
 	) => Promise<void>
+
+	/**
+	 * Called after a system snapshot has been stored to disk.
+	 *
+	 * Use this to run studio-level side effects (e.g. TSR actions on playout devices) at snapshot time.
+	 * The callback receives {@link ISystemSnapshotCreatedContext} with `listPlayoutDevices` and `executeTSRAction`.
+	 *
+	 * Invoked once per studio:
+	 * - Studio-scoped snapshots (`studioId` in snapshot options): once for that studio.
+	 * - Full-system snapshots (no `studioId`): once per studio included in the snapshot.
+	 * - Debug snapshots: once for the target studio when `info.type` is `'debug'` ({@link _BlueprintSnapshotType}).
+	 *
+	 * Errors are logged by Core and do not fail snapshot storage.
+	 *
+	 * @param context Studio context and TSR actions for the studio worker job.
+	 * @param info Metadata about the snapshot (not the snapshot JSON).
+	 */
+	onSystemSnapshotCreated?: (
+		context: ISystemSnapshotCreatedContext,
+		info: IBlueprintSystemSnapshotInfo
+	) => Promise<void>
 }
 
 export interface BlueprintResultStudioBaseline {

packages/blueprints-integration/src/context/executeTsrActionContext.ts

@@ -2,7 +2,7 @@ import { PeripheralDeviceId } from '@sofie-automation/shared-lib/dist/core/model
 import { IBlueprintPlayoutDevice, TSR } from '../index.js'
 
 export interface IExecuteTSRActionsContext {
-	/** Returns a list of the PeripheralDevices */
+	/** Returns playout-gateway subdevices for the studio, or an empty list if none are configured. */
 	listPlayoutDevices(): Promise<IBlueprintPlayoutDevice[]>
 	/** Execute an action on a certain PeripheralDevice */
 	executeTSRAction(

packages/blueprints-integration/src/context/index.ts

@@ -9,6 +9,7 @@ export * from './playoutStore.js'
 export * from './processIngestDataContext.js'
 export * from './rundownContext.js'
 export * from './showStyleContext.js'
+export * from './snapshotContext.js'
 export * from './studioContext.js'
 export * from './syncIngestChangesContext.js'
 export * from './tTimersContext.js'

packages/blueprints-integration/src/context/snapshotContext.ts

@@ -0,0 +1,88 @@
+import type { IExecuteTSRActionsContext } from './executeTsrActionContext.js'
+import type { IShowStyleContext } from './showStyleContext.js'
+import type { IStudioContext } from './studioContext.js'
+
+/**
+ * How the system snapshot hook was triggered.
+ * - `system` — system snapshot (settings, REST, automatic snapshot before migration)
+ * - `debug` — debug snapshot capture from the rundown UI
+ */
+export type BlueprintSnapshotType = 'system' | 'debug'
+
+/** Options that were used when the system snapshot was created. */
+export interface IBlueprintSystemSnapshotOptions {
+	/** Studio this hook invocation runs for (same as context; use `fullSystem` for snapshot scope). */
+	studioId?: string
+	/** Whether peripheral device state snapshots were included in the stored snapshot file. */
+	withDeviceSnapshots?: boolean
+	/**
+	 * `true` when the stored snapshot is a full-system snapshot (all studios).
+	 * `false` when the snapshot was filtered to a single studio.
+	 */
+	fullSystem?: boolean
+}
+
+/**
+ * Metadata passed to {@link StudioBlueprintManifest.onSystemSnapshotCreated}.
+ * Does not include the snapshot file contents.
+ */
+export interface IBlueprintSystemSnapshotInfo {
+	/** Id of the stored snapshot (same value for every studio when `fullSystem` is true). */
+	snapshotId: string
+	/** Human-readable reason provided when the snapshot was requested (e.g. UI label, cron message). */
+	reason: string
+	type: BlueprintSnapshotType
+	/** Snapshot creation options relevant to this hook invocation. */
+	options: IBlueprintSystemSnapshotOptions
+}
+
+/**
+ * Context for {@link StudioBlueprintManifest.onSystemSnapshotCreated}.
+ * Provides studio config, mappings, and TSR device actions for the studio worker job.
+ */
+export interface ISystemSnapshotCreatedContext extends IStudioContext, IExecuteTSRActionsContext {}
+
+/** Options that were used when the playlist snapshot was generated. */
+export interface IBlueprintPlaylistSnapshotOptions {
+	/** When true, all part/piece instances are included; when false, only recent/non-reset instances. */
+	full: boolean
+	/** When true and the playlist is activated, the timeline is included in the snapshot data. */
+	withTimeline: boolean
+}
+
+/** Minimal playlist state exposed to the blueprint (not the full DB document). */
+export interface IBlueprintPlaylistSnapshotPlaylistInfo {
+	/** Playlist display name. */
+	name: string
+	/** Whether the playlist had an active activation at snapshot time. */
+	active: boolean
+	/** Whether the playlist was in rehearsal mode at snapshot time. */
+	rehearsal: boolean
+}
+
+/**
+ * Metadata passed to {@link ShowStyleBlueprintManifest.onPlaylistSnapshotCreated}.
+ * Does not include the snapshot file contents.
+ */
+export interface IBlueprintPlaylistSnapshotInfo {
+	/** Id assigned to this snapshot before generation completes. */
+	snapshotId: string
+	/** Id of the rundown playlist that was snapshotted. */
+	playlistId: string
+	/** Human-readable reason provided when the snapshot was requested. */
+	reason: string
+	/** Snapshot generation options. */
+	options: IBlueprintPlaylistSnapshotOptions
+	/** Summary of playlist state at snapshot time. */
+	playlist: IBlueprintPlaylistSnapshotPlaylistInfo
+}
+
+/**
+ * Context for {@link ShowStyleBlueprintManifest.onPlaylistSnapshotCreated}.
+ * Provides show-style and studio config, and TSR device actions.
+ *
+ * For playlists with multiple rundowns/show styles, only one show-style blueprint is invoked per snapshot.
+ * Rundown selection order: current part, then next part, then first rundown by name (see job-worker
+ * `pickRundownForPlaylistSnapshot`).
+ */
+export interface IPlaylistSnapshotCreatedContext extends IShowStyleContext, IExecuteTSRActionsContext {}

packages/corelib/src/worker/studio.ts

@@ -13,11 +13,12 @@ import {
 	RundownId,
 	RundownPlaylistId,
 	SegmentId,
+	SnapshotId,
 	StudioId,
 } from '../dataModel/Ids.js'
 import { JSONBlob } from '@sofie-automation/shared-lib/dist/lib/JSONBlob'
 import { CoreRundownPlaylistSnapshot } from '../snapshots.js'
-import { NoteSeverity } from '@sofie-automation/blueprints-integration'
+import { BlueprintSnapshotType, NoteSeverity } from '@sofie-automation/blueprints-integration'
 import { ITranslatableMessage } from '../TranslatableMessage.js'
 import { QuickLoopMarker } from '../dataModel/RundownPlaylist/RundownPlaylist.js'
 import { RundownTTimerIndex } from '../dataModel/RundownPlaylist/TTimers.js'
@@ -174,6 +175,11 @@ export enum StudioJobs {
 	 */
 	RestorePlaylistSnapshot = 'restorePlaylistSnapshot',
 
+	/**
+	 * Invoke {@link StudioBlueprintManifest.onSystemSnapshotCreated} for the studio after a system or debug snapshot is stored.
+	 */
+	OnSystemSnapshotCreated = 'onSystemSnapshotCreated',
+
 	/**
 	 * Run the Blueprint applyConfig for the studio
 	 */
@@ -357,10 +363,30 @@ export type DebugRegenerateNextPartInstanceProps = RundownPlayoutPropsBase
 export type DebugSyncInfinitesForNextPartInstanceProps = RundownPlayoutPropsBase
 
 export interface GeneratePlaylistSnapshotProps extends RundownPlayoutPropsBase {
-	// Include all Instances, or just recent ones
+	/** Include all part/piece instances, or only recent/non-reset instances. */
 	full: boolean
-	// Include the Timeline
+	/** Include the timeline if the playlist is activated. */
 	withTimeline: boolean
+	/** Id of the snapshot (assigned in Meteor before the worker job is queued). Passed to the playlist snapshot blueprint hook. */
+	snapshotId?: SnapshotId
+	/** Human-readable reason for creating the snapshot. Passed to the playlist snapshot blueprint hook. */
+	reason?: string
+}
+
+/** Props for {@link StudioJobs.OnSystemSnapshotCreated}. */
+export interface OnSystemSnapshotCreatedProps {
+	/** Id of the stored snapshot file. */
+	snapshotId: SnapshotId
+	/** Human-readable reason from the snapshot request. */
+	reason: string
+	type: BlueprintSnapshotType
+	/** Snapshot options; `studioId` is the studio this worker job runs for. */
+	options: {
+		studioId?: StudioId
+		withDeviceSnapshots?: boolean
+		/** True when the stored snapshot is a full-system snapshot (not filtered to a single studio). */
+		fullSystem?: boolean
+	}
 }
 export interface GeneratePlaylistSnapshotResult {
 	/**
@@ -499,6 +525,7 @@ export type StudioJobFunc = {
 
 	[StudioJobs.GeneratePlaylistSnapshot]: (data: GeneratePlaylistSnapshotProps) => GeneratePlaylistSnapshotResult
 	[StudioJobs.RestorePlaylistSnapshot]: (data: RestorePlaylistSnapshotProps) => RestorePlaylistSnapshotResult
+	[StudioJobs.OnSystemSnapshotCreated]: (data: OnSystemSnapshotCreatedProps) => void
 	[StudioJobs.DebugCrash]: (data: DebugRegenerateNextPartInstanceProps) => void
 
 	[StudioJobs.BlueprintUpgradeForStudio]: () => void

packages/documentation/docs/for-developers/for-blueprint-developers/intro.md

@@ -12,7 +12,7 @@ Documentation for this page is yet to be written.
 
 Technically, a Blueprint is a JavaScript object, implementing one of the `BlueprintManifestBase` interfaces.
 
-Sofie doesn't have a built-in package manager or import, so all dependencies need to be bundled into a single `*.js` file bundle using a bundler such as  [Rollup](https://rollupjs.org/) or [webpack](https://webpack.js.org/). The community has built a set of utilities called [SuperFlyTV/sofie-blueprint-tools](https://github.com/SuperFlyTV/sofie-blueprint-tools/) that acts as a nascent framework for building & bundling Blueprints written in TypeScript.
+Sofie doesn't have a built-in package manager or import, so all dependencies need to be bundled into a single `*.js` file bundle using a bundler such as [Rollup](https://rollupjs.org/) or [webpack](https://webpack.js.org/). The community has built a set of utilities called [SuperFlyTV/sofie-blueprint-tools](https://github.com/SuperFlyTV/sofie-blueprint-tools/) that acts as a nascent framework for building & bundling Blueprints written in TypeScript.
 
 :::info
 Note that the Runtime Environment for Blueprints in Sofie is plain JavaScript at [ES2015 level](https://en.wikipedia.org/wiki/ECMAScript_version_history#6th_edition_%E2%80%93_ECMAScript_2015), so other ways of building Blueprints are also possible.
@@ -28,10 +28,14 @@ Currently, there are three types of Blueprints:
 
 These blueprints interpret the data coming from the [NRCS](../../user-guide/installation/installing-a-gateway/rundown-or-newsroom-system-connection/intro.md), meaning that they need to support the particular data structures that a given Ingest Gateway uses to store incoming data from the Rundown editor. They will need to convert Rundown Pages, Cues, Items, pieces of show script and other types of objects into [Sofie concepts](../../user-guide/concepts-and-architecture.md) such as Segments, Parts, Pieces and AdLibs.
 
+Optional event hooks include playlist snapshot callbacks — see [Snapshot hooks](./snapshot-hooks.md).
+
 # Studio Blueprints
 
 These blueprints provide a "baseline" Timeline that is being used by your Studio whenever there isn't a Rundown active. They also handle combining Rundowns into RundownPlaylists. Via the [`applyConfig`](https://sofie-automation.github.io/sofie-core/typedoc/interfaces/_sofie-automation_blueprints-integration.StudioBlueprintManifest.html#applyconfig) method, these Blueprints enable a _Configuration-as-Code_ approach to configuring connections to various elements of your Control Room and Studio.
 
+Optional event hooks include system snapshot callbacks (with TSR device access) — see [Snapshot hooks](./snapshot-hooks.md).
+
 # System Blueprints
 
-These blueprints exist to allow a _Configuration-as-Code_ approach to an entire Sofie system. This is done via the [`applyConfig`](https://sofie-automation.github.io/sofie-core/typedoc/interfaces/_sofie-automation_blueprints-integration.SystemBlueprintManifest.html#applyconfig) providing personality information such as global system configuration or system-wide HotKeys via the Blueprints.
+These blueprints exist to allow a _Configuration-as-Code_ approach to an entire Sofie system. This is done via the [`applyConfig`](https://sofie-automation.github.io/sofie-core/typedoc/interfaces/_sofie-automation_blueprints-integration.SystemBlueprintManifest.html#applyconfig) providing personality information such as global system configuration or system-wide HotKeys via the Blueprints.