@growth-labs/cms 0.1.0

package/src/engine/foundry-dispatch.ts

@@ -0,0 +1,417 @@
+// Foundry dispatch + HMAC callback engine (bead-08).
+//
+// Backs the Foundry tab (spec §8 + §13.6). The dispatch hook is the seam —
+// the package never imports media-compute glue directly. The real capability
+// slug lives at the-foundry #558 (deferred); P3 dispatches only through the
+// injected FoundryDispatch provider.
+//
+// State machine: pending → queued → fetching → transcribing → transcoding →
+// ready | failed.  Advances are driven by HMAC-verified callback events keyed
+// on `processing_trigger_token` and deduplicated on `event_id`.
+
+import type { FoundryDispatch } from '../providers/types.js'
+import type { D1Database } from './d1.js'
+
+export type ProcessingState =
+	| 'pending'
+	| 'queued'
+	| 'fetching'
+	| 'transcribing'
+	| 'transcoding'
+	| 'ready'
+	| 'failed'
+
+const TERMINAL_STATES: ProcessingState[] = ['ready', 'failed']
+
+export interface DispatchResult {
+	correlationId: string
+	triggerToken: string
+}
+
+export interface CallbackInput {
+	eventId: string
+	eventKind: string
+	correlationId: string
+	triggerToken: string
+	nextState: ProcessingState
+	error?: string | null
+	transcript?: string | null
+	durationSeconds?: number | null
+	description?: string | null
+	excerpt?: string | null
+}
+
+async function sha256Hex(value: string): Promise<string> {
+	const bytes = new TextEncoder().encode(value)
+	const digest = await crypto.subtle.digest('SHA-256', bytes)
+	return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('')
+}
+
+function slugPart(value: string): string {
+	return (
+		value
+			.trim()
+			.replace(/[^A-Za-z0-9_-]+/g, '-')
+			.replace(/^-+|-+$/g, '')
+			.slice(0, 80) || 'video'
+	)
+}
+
+function normalizeVideoId(value: string | null | undefined, fallback: string): string {
+	const candidate = value?.trim()
+	if (candidate && /^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(candidate)) return candidate
+	return slugPart(fallback)
+}
+
+function inferVideoSourceKind(sourceUrl: string): string {
+	try {
+		const host = new URL(sourceUrl).hostname.toLowerCase()
+		if (
+			host === 'dropbox.com' ||
+			host === 'www.dropbox.com' ||
+			host === 'dl.dropboxusercontent.com'
+		) {
+			return 'dropbox'
+		}
+	} catch {
+		// Let the host/Foundry side reject invalid source URLs with its normal diagnostics.
+	}
+	return 'http_url'
+}
+
+/**
+ * Dispatch a video or podcast content item to Foundry via the injected hook.
+ * Mints a fresh `processing_trigger_token` (UUID), calls
+ * `hook.dispatchVideo({ contentId, sourceUrl, kind })`, and writes
+ * `processing_correlation_id` + advances to `'queued'` in either
+ * `video_content` or `podcast_content`.
+ *
+ * Throws if the item is not a video/podcast.
+ */
+export async function dispatchToFoundry(
+	db: D1Database,
+	contentId: string,
+	hook: Pick<FoundryDispatch, 'dispatchVideo'>,
+): Promise<DispatchResult> {
+	const content = await db
+		.prepare('SELECT id, type, slug, title, description FROM content_items WHERE id = ? LIMIT 1')
+		.bind(contentId)
+		.first<{
+			id: string
+			type: string
+			slug: string
+			title: string
+			description: string | null
+		}>()
+	if (!content) {
+		throw new Error(`dispatchToFoundry: content ${contentId} not found`)
+	}
+
+	// Determine which media table owns this content id.
+	const videoRow = await db
+		.prepare(
+			'SELECT content_id, video_id, processing_source_url, processing_source_kind FROM video_content WHERE content_id = ?',
+		)
+		.bind(contentId)
+		.first<{
+			content_id: string
+			video_id: string
+			processing_source_url: string | null
+			processing_source_kind: string | null
+		}>()
+
+	let table: 'video_content' | 'podcast_content'
+	let sourceUrl: string
+	let kind: string
+	let sourceKind: string | null = null
+	let videoId: string | null = null
+
+	if (videoRow) {
+		table = 'video_content'
+		sourceUrl = videoRow.processing_source_url?.trim() ?? ''
+		if (!sourceUrl) {
+			throw new Error(`dispatchToFoundry: content ${contentId} has no video source URL`)
+		}
+		kind = 'video'
+		sourceKind = videoRow.processing_source_kind || inferVideoSourceKind(sourceUrl)
+		videoId = normalizeVideoId(videoRow.video_id, content.slug)
+	} else {
+		const podcastRow = await db
+			.prepare('SELECT content_id, audio_r2_key FROM podcast_content WHERE content_id = ?')
+			.bind(contentId)
+			.first<{ content_id: string; audio_r2_key: string | null }>()
+
+		if (!podcastRow) {
+			throw new Error(
+				`dispatchToFoundry: content ${contentId} is not a video or podcast — cannot dispatch`,
+			)
+		}
+		table = 'podcast_content'
+		sourceUrl = podcastRow.audio_r2_key?.trim() ?? ''
+		if (!sourceUrl) {
+			throw new Error(`dispatchToFoundry: content ${contentId} has no podcast audio R2 key`)
+		}
+		kind = 'podcast'
+		sourceKind = 'r2_key'
+		videoId = normalizeVideoId(content.slug, content.slug)
+	}
+
+	const triggerToken = crypto.randomUUID()
+	const processingTriggerTokenHash = `sha256:${await sha256Hex(triggerToken)}`
+	const { correlationId } = await hook.dispatchVideo({
+		contentId,
+		sourceUrl,
+		kind,
+		...(sourceKind ? { sourceKind } : {}),
+		...(videoId ? { videoId } : {}),
+		title: content.title,
+		description: content.description,
+		processingTriggerTokenHash,
+	})
+
+	const now = Math.floor(Date.now() / 1000)
+
+	if (table === 'video_content') {
+		await db
+			.prepare(
+				`UPDATE video_content
+         SET processing_state = 'queued',
+             video_id = ?,
+             processing_source_kind = ?,
+             processing_correlation_id = ?,
+             processing_trigger_token = ?,
+             processing_started_at = ?,
+             processing_completed_at = NULL,
+             processing_last_event_at = NULL,
+             processing_error = NULL,
+             source_fetched = 0,
+             transcript_ready = 0,
+             hls_ready = 0,
+             transcript_url = NULL,
+             hls_manifest_url = NULL,
+             hls_poster_url = NULL
+         WHERE content_id = ?`,
+			)
+			.bind(videoId, sourceKind, correlationId, triggerToken, now, contentId)
+			.run()
+	} else {
+		// podcast_content only has processing_trigger_token (migration 0006)
+		await db
+			.prepare('UPDATE podcast_content SET processing_trigger_token = ? WHERE content_id = ?')
+			.bind(triggerToken, contentId)
+			.run()
+	}
+
+	return { correlationId, triggerToken }
+}
+
+/**
+ * Apply a Foundry callback event to the state machine.
+ *
+ * - Deduplicates on `event_id`: if a row for this `event_id` already exists in
+ *   `foundry_callback_events`, returns `false` (no state change).
+ * - Verifies `triggerToken` matches the row's `processing_trigger_token`:
+ *   if it does not match, returns `false` (no state change).
+ * - On success: inserts the event row, advances `processing_state`, sets
+ *   `processing_completed_at` for terminal states, sets `processing_error`
+ *   on `failed`, returns `true`.
+ *
+ * Video callbacks advance `video_content.processing_state`. Podcast callbacks
+ * resolve by the same trigger token and hydrate the transcript/summary fields
+ * when the callback carries those values.
+ */
+export async function applyFoundryCallback(db: D1Database, input: CallbackInput): Promise<boolean> {
+	const {
+		eventId,
+		eventKind,
+		correlationId,
+		triggerToken,
+		nextState,
+		error,
+		transcript,
+		durationSeconds,
+		description,
+		excerpt,
+	} = input
+
+	// Deduplicate — attempt to insert; if event_id already exists, skip.
+	const existingEvent = await db
+		.prepare('SELECT event_id FROM foundry_callback_events WHERE event_id = ? LIMIT 1')
+		.bind(eventId)
+		.first<{ event_id: string }>()
+
+	if (existingEvent) {
+		return false // already processed — idempotent no-op
+	}
+
+	// Find the media row by triggerToken (unique per dispatch).
+	// The correlationId is recorded in the event log but is NOT used for lookup:
+	// multiple dispatches against the same or different items may share a
+	// correlationId (the stub always returns the same one in tests), so the
+	// trigger token is the authoritative identity for this callback.
+	const videoRow = await db
+		.prepare(
+			'SELECT content_id, processing_trigger_token FROM video_content WHERE processing_trigger_token = ? LIMIT 1',
+		)
+		.bind(triggerToken)
+		.first<{ content_id: string; processing_trigger_token: string | null }>()
+
+	const podcastRow = videoRow
+		? null
+		: await db
+				.prepare(
+					'SELECT content_id, processing_trigger_token FROM podcast_content WHERE processing_trigger_token = ? LIMIT 1',
+				)
+				.bind(triggerToken)
+				.first<{ content_id: string; processing_trigger_token: string | null }>()
+
+	if (!videoRow && !podcastRow) {
+		return false // no matching job for this trigger token
+	}
+
+	// Insert the event row.
+	const now = Math.floor(Date.now() / 1000)
+	await db
+		.prepare(
+			'INSERT INTO foundry_callback_events (event_id, event_kind, correlation_id, received_at) VALUES (?, ?, ?, ?)',
+		)
+		.bind(eventId, eventKind, correlationId, now)
+		.run()
+
+	// Advance the state machine.
+	const isTerminal = (TERMINAL_STATES as string[]).includes(nextState)
+
+	if (podcastRow) {
+		const nextTranscript =
+			typeof transcript === 'string' && transcript.trim() ? transcript.trim() : null
+		const nextDurationSeconds =
+			typeof durationSeconds === 'number' && Number.isFinite(durationSeconds)
+				? Math.max(0, Math.floor(durationSeconds))
+				: null
+		if (nextTranscript !== null || nextDurationSeconds !== null) {
+			await db
+				.prepare(
+					`UPDATE podcast_content
+					SET transcript = CASE WHEN ? THEN ? ELSE transcript END,
+						duration_seconds = CASE WHEN ? THEN ? ELSE duration_seconds END
+					WHERE content_id = ?`,
+				)
+				.bind(
+					nextTranscript !== null ? 1 : 0,
+					nextTranscript,
+					nextDurationSeconds !== null ? 1 : 0,
+					nextDurationSeconds,
+					podcastRow.content_id,
+				)
+				.run()
+		}
+
+		const nextDescription =
+			typeof description === 'string' && description.trim() ? description.trim() : null
+		const nextExcerpt = typeof excerpt === 'string' && excerpt.trim() ? excerpt.trim() : null
+		if (nextDescription !== null || nextExcerpt !== null) {
+			await db
+				.prepare(
+					`UPDATE content_items
+					SET description = CASE WHEN ? THEN ? ELSE description END,
+						excerpt = CASE WHEN ? THEN ? ELSE excerpt END,
+						updated_at = unixepoch()
+					WHERE id = ?`,
+				)
+				.bind(
+					nextDescription !== null ? 1 : 0,
+					nextDescription,
+					nextExcerpt !== null ? 1 : 0,
+					nextExcerpt,
+					podcastRow.content_id,
+				)
+				.run()
+		}
+
+		return true
+	}
+
+	if (!videoRow) return false
+	const row = videoRow
+
+	if (nextState === 'failed') {
+		await db
+			.prepare(
+				`UPDATE video_content
+         SET processing_state = ?,
+             processing_last_event_at = ?,
+             processing_completed_at = ?,
+             processing_error = ?
+         WHERE content_id = ?`,
+			)
+			.bind(nextState, now, now, error ?? null, row.content_id)
+			.run()
+	} else if (isTerminal) {
+		// 'ready'
+		await db
+			.prepare(
+				`UPDATE video_content
+         SET processing_state = ?,
+             processing_last_event_at = ?,
+             processing_completed_at = ?
+         WHERE content_id = ?`,
+			)
+			.bind(nextState, now, now, row.content_id)
+			.run()
+	} else {
+		await db
+			.prepare(
+				'UPDATE video_content SET processing_state = ?, processing_last_event_at = ? WHERE content_id = ?',
+			)
+			.bind(nextState, now, row.content_id)
+			.run()
+	}
+
+	return true
+}
+
+/**
+ * Verify a HMAC-SHA256 signature over `rawBody` using `secret`.
+ * The `signature` is expected as a lowercase hex string.
+ * Uses Web Crypto `crypto.subtle` and a constant-time comparison.
+ */
+export async function verifyHmac(
+	secret: string,
+	rawBody: string,
+	signature: string,
+): Promise<boolean> {
+	if (!signature) return false
+
+	let sigBytes: Uint8Array
+	try {
+		// Parse the hex signature
+		if (signature.length % 2 !== 0) return false
+		sigBytes = new Uint8Array(signature.length / 2)
+		for (let i = 0; i < signature.length; i += 2) {
+			const byte = Number.parseInt(signature.slice(i, i + 2), 16)
+			if (Number.isNaN(byte)) return false
+			sigBytes[i / 2] = byte
+		}
+	} catch {
+		return false
+	}
+
+	const key = await crypto.subtle.importKey(
+		'raw',
+		new TextEncoder().encode(secret),
+		{ name: 'HMAC', hash: 'SHA-256' },
+		false,
+		['sign'],
+	)
+
+	const expected = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(rawBody))
+	const expectedBytes = new Uint8Array(expected)
+
+	// Constant-time compare
+	if (expectedBytes.length !== sigBytes.length) return false
+	let diff = 0
+	for (let i = 0; i < expectedBytes.length; i++) {
+		diff |= expectedBytes[i] ^ sigBytes[i]
+	}
+	return diff === 0
+}