import type { MeetingLanguage } from '@d3ro/api-client'; import AsyncStorage from '@react-native-async-storage/async-storage'; import { Dirs, FileSystem } from 'react-native-file-access'; import { AudioPipelineError, type AudioPipelinePhase, type AudioPipelineResult, type LocalAudioInput, } from '../import/audio-import-types'; import { processAudioInput } from '../import/audio-transcription-service'; import { failMeetingRecording, markMeetingProcessingFailure, queueMeetingRecording, } from '../meetings/meetings-service'; import { createUuidV4 } from '../../lib/random-id'; const STORAGE_KEY = '@d3ro/audio-processing-queue/v1'; const QUEUE_DIRECTORY = `${Dirs.DocumentDir}/d3ro-processing-queue`; const MAX_ATTEMPTS = 8; const MAX_ERROR_LENGTH = 500; export type DurableQueueStatus = | 'pending' | 'running' | 'retry' | 'terminal' | 'cleanup'; export interface DurableQueueItem { schemaVersion: 1; id: string; userId: string; meetingId: string | null; path: string; uri: string; fileName: string; mimeType: string; sizeBytes: number; durationMs: number | null; source: LocalAudioInput['source']; languageCode: MeetingLanguage; status: DurableQueueStatus; phase: AudioPipelinePhase | null; attempts: number; uploadedBytes: number; nextAttemptAtMs: number; lastErrorCode: string | null; lastErrorMessage: string | null; createdAtMs: number; updatedAtMs: number; } export type DurableQueueEvent = | { type: 'changed'; item: DurableQueueItem } | { type: 'completed'; itemId: string; result: AudioPipelineResult } | { type: 'removed'; itemId: string }; export class QueuedAudioPendingError extends Error { constructor(public readonly item: DurableQueueItem) { super(item.lastErrorMessage ?? 'Audio processing is queued for retry'); this.name = 'QueuedAudioPendingError'; } } const listeners = new Set<(event: DurableQueueEvent) => void>(); let storageLock: Promise = Promise.resolve(); const runningUsers = new Set(); const scheduledRetries = new Map>(); const runningControllers = new Map(); const runningItemPromises = new Map>(); const discardedItems = new Set(); function emit(event: DurableQueueEvent): void { for (const listener of listeners) listener(event); } export function subscribeToDurableQueue( listener: (event: DurableQueueEvent) => void, ): () => void { listeners.add(listener); return () => listeners.delete(listener); } function queueId(): string { return createUuidV4(); } function ownedQueuePath(path: string): boolean { const prefix = `${QUEUE_DIRECTORY}/`; if (!path.startsWith(prefix)) return false; const name = path.slice(prefix.length); return !name.includes('/') && !name.includes('\\') && /^queued-[a-f0-9-]+\.[a-z0-9]{1,8}$/.test(name); } function parseQueue(raw: string | null): DurableQueueItem[] { if (raw === null) return []; let candidate: unknown; try { candidate = JSON.parse(raw); } catch { return []; } if (!Array.isArray(candidate)) return []; return candidate.filter((value): value is DurableQueueItem => { if (typeof value !== 'object' || value === null) return false; const item = value as Partial; return ( item.schemaVersion === 1 && typeof item.id === 'string' && item.id.length > 0 && typeof item.userId === 'string' && /^[0-9a-f-]{36}$/i.test(item.userId) && (item.meetingId === null || (typeof item.meetingId === 'string' && /^[0-9a-f-]{36}$/i.test(item.meetingId))) && typeof item.path === 'string' && ownedQueuePath(item.path) && item.uri === `file://${item.path}` && typeof item.fileName === 'string' && item.fileName.length > 0 && item.fileName.length <= 255 && typeof item.mimeType === 'string' && item.mimeType.startsWith('audio/') && typeof item.sizeBytes === 'number' && Number.isSafeInteger(item.sizeBytes) && item.sizeBytes > 0 && (item.durationMs === null || (typeof item.durationMs === 'number' && Number.isFinite(item.durationMs) && item.durationMs >= 0)) && (item.source === 'recording' || item.source === 'file-picker' || item.source === 'share-intent') && (item.languageCode === 'ko' || item.languageCode === 'en' || item.languageCode === 'ja' || item.languageCode === 'zh-cn') && (item.status === 'pending' || item.status === 'running' || item.status === 'retry' || item.status === 'terminal' || item.status === 'cleanup') && (item.phase === null || item.phase === 'validating' || item.phase === 'uploading' || item.phase === 'transcribing' || item.phase === 'saving') && typeof item.attempts === 'number' && Number.isSafeInteger(item.attempts) && item.attempts >= 0 && typeof item.uploadedBytes === 'number' && Number.isSafeInteger(item.uploadedBytes) && item.uploadedBytes >= 0 && item.uploadedBytes <= item.sizeBytes && typeof item.nextAttemptAtMs === 'number' && Number.isFinite(item.nextAttemptAtMs) && (item.lastErrorCode === null || (typeof item.lastErrorCode === 'string' && item.lastErrorCode.length <= 64)) && (item.lastErrorMessage === null || (typeof item.lastErrorMessage === 'string' && item.lastErrorMessage.length <= MAX_ERROR_LENGTH)) && typeof item.createdAtMs === 'number' && Number.isFinite(item.createdAtMs) && typeof item.updatedAtMs === 'number' && Number.isFinite(item.updatedAtMs) ); }); } async function readQueue(): Promise { await storageLock; return parseQueue(await AsyncStorage.getItem(STORAGE_KEY)); } async function mutateQueue( mutation: (items: DurableQueueItem[]) => DurableQueueItem[], ): Promise { let result: DurableQueueItem[] = []; const operation = storageLock.then(async () => { const current = parseQueue(await AsyncStorage.getItem(STORAGE_KEY)); result = mutation(current); if (result.length === 0) await AsyncStorage.removeItem(STORAGE_KEY); else await AsyncStorage.setItem(STORAGE_KEY, JSON.stringify(result)); }); storageLock = operation.catch(() => undefined); await operation; return result; } async function ensureQueueDirectory(): Promise { if (!(await FileSystem.exists(QUEUE_DIRECTORY))) await FileSystem.mkdir(QUEUE_DIRECTORY); if (!(await FileSystem.isDir(QUEUE_DIRECTORY))) { throw new AudioPipelineError('file-read', 'Durable audio queue storage is unavailable'); } } async function removeOwnedFile(path: string): Promise { if (!ownedQueuePath(path)) { throw new AudioPipelineError('cleanup', 'Refusing to remove audio outside the durable queue'); } if (await FileSystem.exists(path)) await FileSystem.unlink(path); } function fileExtension(fileName: string, mimeType: string): string { const matched = fileName.match(/\.([A-Za-z0-9]{1,8})$/)?.[1]?.toLowerCase(); if (matched !== undefined) return matched; if (mimeType === 'audio/wav' || mimeType === 'audio/x-wav') return 'wav'; if (mimeType === 'audio/mp4') return 'm4a'; return 'audio'; } export async function enqueueAudioProcessing( input: LocalAudioInput, options: { userId: string; languageCode: MeetingLanguage; meetingId?: string }, ): Promise { if (!/^[0-9a-f-]{36}$/i.test(options.userId)) { await input.dispose(); throw new AudioPipelineError('auth', 'A valid account is required for the processing queue'); } if (options.meetingId !== undefined && !/^[0-9a-f-]{36}$/i.test(options.meetingId)) { await input.dispose(); throw new AudioPipelineError('persist', 'Meeting id is invalid'); } const id = queueId(); const target = `${QUEUE_DIRECTORY}/queued-${id}.${fileExtension(input.fileName, input.mimeType)}`; let persisted = false; try { await ensureQueueDirectory(); await FileSystem.cp(input.path, target); const stat = await FileSystem.stat(target); if (stat.type !== 'file' || stat.size !== input.sizeBytes) { throw new AudioPipelineError('file-read', 'Durable audio copy could not be verified'); } const now = Date.now(); const item: DurableQueueItem = { schemaVersion: 1, id, userId: options.userId, meetingId: options.meetingId ?? null, path: target, uri: `file://${target}`, fileName: input.fileName, mimeType: input.mimeType, sizeBytes: input.sizeBytes, durationMs: input.durationMs, source: input.source, languageCode: options.languageCode, status: 'pending', phase: null, attempts: 0, uploadedBytes: 0, nextAttemptAtMs: now, lastErrorCode: null, lastErrorMessage: null, createdAtMs: now, updatedAtMs: now, }; await mutateQueue(items => [...items.filter(current => current.id !== id), item]); persisted = true; if (item.meetingId !== null) { await queueMeetingRecording( item.userId, item.meetingId, item.durationMs ?? 0, ); } emit({ type: 'changed', item }); return item; } catch (error) { if (persisted) await mutateQueue(items => items.filter(item => item.id !== id)); await removeOwnedFile(target).catch(() => undefined); throw error; } finally { await input.dispose(); } } function queueInput(item: DurableQueueItem): LocalAudioInput { return { uri: item.uri, path: item.path, fileName: item.fileName, mimeType: item.mimeType, sizeBytes: item.sizeBytes, durationMs: item.durationMs, source: item.source, dispose: async () => undefined, }; } function retryable(error: AudioPipelineError): boolean { return ( error.code === 'upload' || error.code === 'provider-unavailable' || error.code === 'transcription' || error.code === 'persist' || error.code === 'auth' ); } function retryDelayMs(attempt: number): number { return Math.min(15 * 60_000, 5_000 * (2 ** Math.min(16, Math.max(0, attempt - 1)))); } async function replaceItem(updated: DurableQueueItem): Promise { await mutateQueue(items => items.map(item => item.id === updated.id ? updated : item)); emit({ type: 'changed', item: updated }); } async function removeItem(item: DurableQueueItem): Promise { await mutateQueue(items => items.filter(candidate => candidate.id !== item.id)); emit({ type: 'removed', itemId: item.id }); } async function reportMeetingFailure( item: DurableQueueItem, error: AudioPipelineError, terminal: boolean, ): Promise { if (item.meetingId === null) return; const idempotencyKey = await FileSystem.hash(item.path, 'SHA-256') .then(hash => `mobile-meeting:${item.meetingId}:${hash.toLowerCase()}`) .catch(() => null); if (idempotencyKey !== null) { try { await markMeetingProcessingFailure( item.userId, item.meetingId, idempotencyKey, error.code, error.message.slice(0, MAX_ERROR_LENGTH), terminal, ); return; } catch { // Upload failures happen before the server processing job exists. } } if (terminal) { await failMeetingRecording( item.userId, item.meetingId, error.message.slice(0, MAX_ERROR_LENGTH), ).catch(() => undefined); } } async function processItemCore(item: DurableQueueItem): Promise { if (!(await FileSystem.exists(item.path))) { throw new AudioPipelineError('file-read', 'Queued audio file is missing'); } const controller = new AbortController(); runningControllers.set(item.id, controller); let current: DurableQueueItem = { ...item, status: 'running' as const, attempts: item.attempts + 1, lastErrorCode: null, lastErrorMessage: null, updatedAtMs: Date.now(), }; await replaceItem(current); try { const result = await processAudioInput(queueInput(current), { expectedUserId: current.userId, languageCode: current.languageCode, meetingId: current.meetingId ?? undefined, signal: controller.signal, onPhase: phase => { current = { ...current, phase, updatedAtMs: Date.now() }; emit({ type: 'changed', item: current }); }, onUploadProgress: uploadedBytes => { current = { ...current, uploadedBytes, updatedAtMs: Date.now() }; emit({ type: 'changed', item: current }); }, }); try { await removeOwnedFile(current.path); await removeItem(current); } catch (cleanupError) { current = { ...current, status: 'cleanup', lastErrorCode: 'cleanup', lastErrorMessage: cleanupError instanceof Error ? cleanupError.message : 'Audio cleanup failed', updatedAtMs: Date.now(), }; await replaceItem(current); } emit({ type: 'completed', itemId: current.id, result }); return result; } catch (cause) { const error = cause instanceof AudioPipelineError ? cause : new AudioPipelineError('transcription', 'Queued audio processing failed', cause); if (discardedItems.has(current.id)) { discardedItems.delete(current.id); await removeItem(current).catch(() => undefined); throw new AudioPipelineError('cancelled', 'Queued audio processing was cancelled', error); } const canRetry = retryable(error) && current.attempts < MAX_ATTEMPTS; current = { ...current, status: canRetry ? 'retry' : 'terminal', nextAttemptAtMs: canRetry ? Date.now() + retryDelayMs(current.attempts) : Number.MAX_SAFE_INTEGER, lastErrorCode: error.code, lastErrorMessage: error.message.slice(0, MAX_ERROR_LENGTH), updatedAtMs: Date.now(), }; await replaceItem(current); await reportMeetingFailure(current, error, !canRetry); if (canRetry) scheduleRetry(current.userId, current.nextAttemptAtMs); throw canRetry ? new QueuedAudioPendingError(current) : error; } finally { runningControllers.delete(item.id); } } function processItem(item: DurableQueueItem): Promise { const existing = runningItemPromises.get(item.id); if (existing !== undefined) return existing; const operation = processItemCore(item).finally(() => { if (runningItemPromises.get(item.id) === operation) { runningItemPromises.delete(item.id); } }); runningItemPromises.set(item.id, operation); return operation; } function scheduleRetry(userId: string, atMs: number): void { const existing = scheduledRetries.get(userId); if (existing !== undefined) clearTimeout(existing); const timer = setTimeout(() => { scheduledRetries.delete(userId); void resumeQueuedAudioForUser(userId).catch(() => undefined); }, Math.max(0, atMs - Date.now())); scheduledRetries.set(userId, timer); } export async function processQueuedAudioNow( userId: string, itemId: string, ): Promise { const item = (await readQueue()).find(candidate => candidate.id === itemId && candidate.userId === userId); if (item === undefined) throw new AudioPipelineError('file-read', 'Queued audio was not found'); return processItem(item); } export async function resumeQueuedAudioForUser(userId: string): Promise { if (runningUsers.has(userId)) return; runningUsers.add(userId); try { const items = (await readQueue()) .filter(item => item.userId === userId) .sort((left, right) => left.createdAtMs - right.createdAtMs); for (const item of items) { if (item.status === 'terminal') continue; if (item.status === 'cleanup') { try { await removeOwnedFile(item.path); await removeItem(item); } catch { scheduleRetry(userId, Date.now() + 60_000); } continue; } if (item.nextAttemptAtMs > Date.now()) { scheduleRetry(userId, item.nextAttemptAtMs); continue; } try { await processItem(item); } catch { // The item itself holds the truthful retry/terminal state. } } } finally { runningUsers.delete(userId); } } export async function listQueuedAudio(userId: string): Promise { return (await readQueue()).filter(item => item.userId === userId); } export async function retryQueuedAudio(userId: string, itemId: string): Promise { const items = await readQueue(); const item = items.find(candidate => candidate.id === itemId && candidate.userId === userId); if (item === undefined) throw new AudioPipelineError('file-read', 'Queued audio was not found'); await replaceItem({ ...item, status: 'retry', nextAttemptAtMs: Date.now(), lastErrorCode: null, lastErrorMessage: null, updatedAtMs: Date.now(), }); await resumeQueuedAudioForUser(userId); } export async function discardQueuedAudio(userId: string, itemId: string): Promise { const item = (await readQueue()).find(candidate => candidate.id === itemId && candidate.userId === userId); if (item === undefined) return; discardedItems.add(item.id); runningControllers.get(item.id)?.abort(); await removeOwnedFile(item.path); await removeItem(item); if (!runningControllers.has(item.id)) discardedItems.delete(item.id); } export async function clearQueuedAudioForUser(userId: string): Promise { const timer = scheduledRetries.get(userId); if (timer !== undefined) clearTimeout(timer); scheduledRetries.delete(userId); const owned = (await readQueue()).filter(item => item.userId === userId); const removedIds = new Set(); let firstRemovalError: unknown = null; for (const item of owned) { discardedItems.add(item.id); runningControllers.get(item.id)?.abort(); try { await removeOwnedFile(item.path); removedIds.add(item.id); } catch (error) { firstRemovalError ??= error; } if (!runningControllers.has(item.id)) discardedItems.delete(item.id); } await mutateQueue(items => items.filter(item => !removedIds.has(item.id))); if (firstRemovalError !== null) throw firstRemovalError; } export async function clearAllQueuedAudio(): Promise { const userIds = [...new Set((await readQueue()).map(item => item.userId))]; let firstError: unknown = null; for (const userId of userIds) { try { await clearQueuedAudioForUser(userId); } catch (error) { firstError ??= error; } } if (firstError !== null) throw firstError; } export const durableQueueTestContract = { storageKey: STORAGE_KEY, queueDirectory: QUEUE_DIRECTORY, retryDelayMs, ownedQueuePath, parseQueue, };