fix(mobile-recording): never lose a meeting capture on offline stop, oversize, or re-record

This commit is contained in:
Yun Chan 2026-09-28 02:16:24 +09:00
parent 80538c0f23
commit 5b1621d314
9 changed files with 1238 additions and 56 deletions

View file

@ -0,0 +1,18 @@
import type { LocalAudioInput } from './audio-import-types';
/**
* Who may delete the original audio when a hand-off fails before the audio
* is safely persisted somewhere else.
*
* A capture is the only copy of what the user said, so a failed hand-off must
* leave it recoverable for the caller (Record keeps it as a recovered
* recording the user can process again or discard explicitly). Picked and
* shared files are app-owned temporary copies of a file the user still has
* elsewhere, so they are cleaned up as before.
*/
export function mayDiscardOriginalOnFailure(source: LocalAudioInput['source']): boolean {
return source !== 'recording';
}
/** What prepareRecordedAudio does with the capture when validation rejects it. */
export type InvalidRecordingPolicy = 'dispose' | 'retain';

View file

@ -1,10 +1,22 @@
import type { RecordedAudio } from '../../lib/audio-recorder';
import type { LocalAudioInput } from './audio-import-types';
import type { InvalidRecordingPolicy } from './audio-input-ownership';
import { validateLocalAudio } from './audio-validation';
export interface PrepareRecordedAudioOptions {
/**
* 'dispose' (default) deletes a capture that fails validation, which suits
* ephemeral dictation (Talk). 'retain' leaves it untouched so the caller can
* keep it recoverable: a long meeting over the upload size limit must not
* be deleted the moment the user presses STOP.
*/
onInvalid?: InvalidRecordingPolicy;
}
export async function prepareRecordedAudio(
recording: RecordedAudio,
dispose: () => Promise<void>,
options: PrepareRecordedAudioOptions = {},
): Promise<LocalAudioInput> {
try {
return await validateLocalAudio({
@ -18,7 +30,7 @@ export async function prepareRecordedAudio(
dispose,
});
} catch (error) {
await dispose();
if ((options.onInvalid ?? 'dispose') === 'dispose') await dispose();
throw error;
}
}

View file

@ -8,14 +8,15 @@ import {
type LocalAudioInput,
} from '../import/audio-import-types';
import { processAudioInput } from '../import/audio-transcription-service';
import {
failMeetingRecording,
markMeetingProcessingFailure,
queueMeetingRecording,
} from '../meetings/meetings-service';
import { mayDiscardOriginalOnFailure } from '../import/audio-input-ownership';
import { createUuidV4 } from '../../lib/random-id';
import { createQueueRepository, type QueueRepository } from './durable-queue-repository';
import { createRetryScheduler, type RetryScheduler } from './retry-scheduler';
import {
classifyMarkQueuedFailure,
meetingsServiceLifecyclePort,
type MeetingLifecyclePort,
} from './meeting-lifecycle-port';
const STORAGE_KEY = '@d3ro/audio-processing-queue/v1';
const QUEUE_DIRECTORY = `${Dirs.DocumentDir}/d3ro-processing-queue`;
@ -51,6 +52,13 @@ export interface DurableQueueItem {
lastErrorMessage: string | null;
createdAtMs: number;
updatedAtMs: number;
/**
* True while the server has not yet been told that this meeting capture
* stopped and is waiting for processing. Absent on non-meeting items and on
* items persisted before this field existed (their enqueue only kept the
* item after that call had succeeded).
*/
meetingQueuePending?: boolean;
}
export type DurableQueueEvent =
@ -125,7 +133,8 @@ function parseQueue(raw: string | null): DurableQueueItem[] {
(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)
typeof item.updatedAtMs === 'number' && Number.isFinite(item.updatedAtMs) &&
(item.meetingQueuePending === undefined || typeof item.meetingQueuePending === 'boolean')
);
});
}
@ -137,6 +146,8 @@ const repository: QueueRepository<DurableQueueItem> = createQueueRepository({
parse: parseQueue,
});
let meetingLifecycle: MeetingLifecyclePort = meetingsServiceLifecyclePort;
const scheduler: RetryScheduler = createRetryScheduler({
now: () => Date.now(),
setTimer: (callback, delayMs) => setTimeout(callback, delayMs),
@ -176,22 +187,34 @@ function fileExtension(fileName: string, mimeType: string): string {
return 'audio';
}
/**
* Makes the audio durable and nothing else: copy into queue storage, verify
* the copy, persist the item. The caller's original is released only after
* the item is persisted. When persisting fails, a recording is left untouched
* so the caller can keep it recoverable; an imported temporary copy is
* cleaned up as before. Server state transitions happen later, in the
* retryable processing step, so a network error can never undo a persisted
* item.
*/
export async function enqueueAudioProcessing(
input: LocalAudioInput,
options: { userId: string; languageCode: MeetingLanguage; meetingId?: string },
): Promise<DurableQueueItem> {
const releaseOnFailure = async (): Promise<void> => {
if (mayDiscardOriginalOnFailure(input.source)) await input.dispose();
};
if (!/^[0-9a-f-]{36}$/i.test(options.userId)) {
await input.dispose();
await releaseOnFailure();
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();
await releaseOnFailure();
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;
let item: DurableQueueItem;
try {
await ensureQueueDirectory();
await FileSystem.cp(input.path, target);
@ -200,7 +223,7 @@ export async function enqueueAudioProcessing(
throw new AudioPipelineError('file-read', 'Durable audio copy could not be verified');
}
const now = Date.now();
const item: DurableQueueItem = {
const created: DurableQueueItem = {
schemaVersion: 1,
id,
userId: options.userId,
@ -222,25 +245,19 @@ export async function enqueueAudioProcessing(
lastErrorMessage: null,
createdAtMs: now,
updatedAtMs: now,
...(options.meetingId !== undefined ? { meetingQueuePending: true } : {}),
};
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;
await mutateQueue(items => [...items.filter(current => current.id !== id), created]);
item = created;
} catch (error) {
if (persisted) await mutateQueue(items => items.filter(item => item.id !== id));
await removeOwnedFile(target).catch(() => undefined);
await releaseOnFailure().catch(() => undefined);
throw error;
} finally {
await input.dispose();
}
// The durable copy now owns the audio; the original is no longer needed.
await input.dispose().catch(() => undefined);
emit({ type: 'changed', item });
return item;
}
function queueInput(item: DurableQueueItem): LocalAudioInput {
@ -286,33 +303,59 @@ async function reportMeetingFailure(
terminal: boolean,
): Promise<void> {
if (item.meetingId === null) return;
const meetingId = item.meetingId;
const idempotencyKey = await FileSystem.hash(item.path, 'SHA-256')
.then(hash => `mobile-meeting:${item.meetingId}:${hash.toLowerCase()}`)
.then(hash => `mobile-meeting:${meetingId}:${hash.toLowerCase()}`)
.catch(() => null);
if (idempotencyKey !== null) {
try {
await markMeetingProcessingFailure(
item.userId,
item.meetingId,
await meetingLifecycle.markProcessingFailure({
userId: item.userId,
meetingId,
idempotencyKey,
error.code,
error.message.slice(0, MAX_ERROR_LENGTH),
errorCode: error.code,
errorMessage: error.message.slice(0, MAX_ERROR_LENGTH),
terminal,
);
});
return;
} catch {
// Upload failures happen before the server processing job exists.
}
}
if (terminal) {
await failMeetingRecording(
await meetingLifecycle.failRecording(
item.userId,
item.meetingId,
meetingId,
error.message.slice(0, MAX_ERROR_LENGTH),
).catch(() => undefined);
}
}
/**
* First, retryable processing step for a meeting capture: tell the server the
* recording stopped and is queued. Runs until it succeeds once per item. A
* reachable server that says the meeting is not recordable is not asked again
* (see classifyMarkQueuedFailure), while an unreachable one leaves the item
* for a later attempt instead of spending an upload on it.
*/
async function markMeetingQueued(item: DurableQueueItem): Promise<DurableQueueItem> {
if (item.meetingId === null || item.meetingQueuePending !== true) return item;
try {
await meetingLifecycle.markQueued(item.userId, item.meetingId, item.durationMs ?? 0);
} catch (cause) {
if (classifyMarkQueuedFailure(cause) === 'retry') {
throw new AudioPipelineError('persist', 'Meeting recording could not be marked as queued', cause);
}
}
// Discarded while the call was in flight: do not resurrect the item.
if (discardedItems.has(item.id)) {
throw new AudioPipelineError('cancelled', 'Queued audio processing was cancelled');
}
const updated: DurableQueueItem = { ...item, meetingQueuePending: false, updatedAtMs: Date.now() };
await replaceItem(updated);
return updated;
}
async function processItemCore(item: DurableQueueItem): Promise<AudioPipelineResult> {
if (!(await FileSystem.exists(item.path))) {
throw new AudioPipelineError('file-read', 'Queued audio file is missing');
@ -329,6 +372,7 @@ async function processItemCore(item: DurableQueueItem): Promise<AudioPipelineRes
};
await replaceItem(current);
try {
current = await markMeetingQueued(current);
const result = await processAudioInput(queueInput(current), {
expectedUserId: current.userId,
languageCode: current.languageCode,
@ -520,4 +564,11 @@ export const durableQueueTestContract = {
retryDelayMs,
ownedQueuePath,
parseQueue,
/** Swaps the meeting lifecycle port; returns a function restoring the default. */
useMeetingLifecyclePort(port: MeetingLifecyclePort): () => void {
meetingLifecycle = port;
return () => {
meetingLifecycle = meetingsServiceLifecyclePort;
};
},
};

View file

@ -0,0 +1,67 @@
import {
failMeetingRecording,
markMeetingProcessingFailure,
queueMeetingRecording,
} from '../meetings/meetings-service';
/**
* Server-side meeting state transitions the durable queue needs. The queue
* owns the local audio; these calls only tell the server what happened to it,
* so none of them may decide whether the local audio survives.
*/
export interface MeetingLifecyclePort {
/** Idempotent: recording -> processing with the captured duration. */
markQueued(userId: string, meetingId: string, durationMs: number): Promise<void>;
markProcessingFailure(failure: {
userId: string;
meetingId: string;
idempotencyKey: string;
errorCode: string;
errorMessage: string;
terminal: boolean;
}): Promise<void>;
failRecording(userId: string, meetingId: string, errorMessage: string): Promise<void>;
}
export const meetingsServiceLifecyclePort: MeetingLifecyclePort = {
async markQueued(userId, meetingId, durationMs) {
await queueMeetingRecording(userId, meetingId, durationMs);
},
async markProcessingFailure(failure) {
await markMeetingProcessingFailure(
failure.userId,
failure.meetingId,
failure.idempotencyKey,
failure.errorCode,
failure.errorMessage,
failure.terminal,
);
},
async failRecording(userId, meetingId, errorMessage) {
await failMeetingRecording(userId, meetingId, errorMessage);
},
};
/**
* What a failed markQueued means for the queued item.
*
* - 'retry': the server could not be reached or refused the session for now
* (network, auth, server, conflict). Keep the item and try again later;
* uploading now would fail for the same reason.
* - 'proceed': the server answered that the meeting is not in a recordable
* state (validation, forbidden, not-found), e.g. after this item already
* failed terminally once and the user retries it. Marking it queued will
* never succeed, so stop asking and let processing, whose begin step is the
* authoritative transition, decide.
*/
export type MeetingQueueFailurePolicy = 'retry' | 'proceed';
const NOT_RECORDABLE_CODES: ReadonlySet<string> = new Set(['validation', 'forbidden', 'not-found']);
export function classifyMarkQueuedFailure(error: unknown): MeetingQueueFailurePolicy {
// Structural check: meetings-service maps every RPC failure to a
// MeetingServiceError whose `code` is one of its MeetingServiceErrorCode.
if (!(error instanceof Error) || error.name !== 'MeetingServiceError') return 'retry';
const code: unknown = (error as Error & { code?: unknown }).code;
return typeof code === 'string' && NOT_RECORDABLE_CODES.has(code) ? 'proceed' : 'retry';
}