From 023f256e006e73831d012bf95d8743a92be18d3a Mon Sep 17 00:00:00 2001 From: yiling Date: Thu, 28 May 2026 10:43:54 +0800 Subject: [PATCH] refactor(error): refactor standard throws to non-retryable ApplicationFailure in workflows and activities --- AGENTS.md | 2 + src/transcode/activities/transcode.ts | 8 +++- src/transcode/workflows/transcode.ts | 8 +++- src/workflow/activities/agent.ts | 15 +++++++- src/workflow/activities/ai.ts | 43 ++++++++++++++++++---- src/workflow/activities/db.ts | 4 +- src/workflow/workflows/ai-transcription.ts | 5 ++- 7 files changed, 71 insertions(+), 14 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index adc14c41..78c7e92e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -308,6 +308,8 @@ We use a custom workflow engine that supports both **Local** (polling-based) and To prevent Temporal from indefinitely retrying fatal, expected business validation failures (e.g., missing records, invalid configurations, missing parameters), **never throw standard `Error` objects from workflow or activity logic.** Instead, throw a non-retryable `ApplicationFailure`. +**Mandatory Requirement**: You **MUST** set `nonRetryable: true` in the options object passed to `ApplicationFailure.create`. Standard errors or `ApplicationFailure` objects without `nonRetryable: true` will cause Temporal to retry the activity or workflow indefinitely. + - **Workflow Boundary**: In workflows, import `ApplicationFailure` from `@temporalio/workflow`: ```typescript import { ApplicationFailure } from '@temporalio/workflow' diff --git a/src/transcode/activities/transcode.ts b/src/transcode/activities/transcode.ts index 99d4ce85..e2665b11 100644 --- a/src/transcode/activities/transcode.ts +++ b/src/transcode/activities/transcode.ts @@ -2,6 +2,7 @@ import { prisma } from '@/db' import { s3Service } from '@/services/s3/s3' import { transcodeService } from '@/transcode/transcode' import { metadataService } from '@/services/metadata/metadata' +import { ApplicationFailure } from '@temporalio/activity' import * as path from 'path' import * as fs from 'fs' @@ -279,7 +280,12 @@ export async function updateAssetMediaActivity(params: UpdateAssetMediaActivityP include: { storageKey: true }, }) const key = asset?.storageKey?.key - if (!asset || !key) throw new Error('Asset not found or has no key') + if (!asset || !key) { + throw ApplicationFailure.create({ + message: 'Asset not found or has no key', + nonRetryable: true, + }) + } const infoKey = path.join(path.dirname(key), 'info.json') const buffer = Buffer.from(JSON.stringify(params.mediaInfo)) diff --git a/src/transcode/workflows/transcode.ts b/src/transcode/workflows/transcode.ts index a93a4b7b..d571ec76 100644 --- a/src/transcode/workflows/transcode.ts +++ b/src/transcode/workflows/transcode.ts @@ -1,4 +1,5 @@ import type { WorkflowTask } from '@/generated/prisma/client' +import { ApplicationFailure } from '@temporalio/workflow' import { getActivities, executeActivity, @@ -39,7 +40,12 @@ export async function transcodeMedia(task: WorkflowTask): Promise { // 2. Get Asset const asset = await executeActivity(TaskQueueDb, getAssetActivity, task.assetId) const key = asset?.storageKey?.key - if (!asset || !key) throw new Error('Asset not found or has no key') + if (!asset || !key) { + throw ApplicationFailure.create({ + message: 'Asset not found or has no key', + nonRetryable: true, + }) + } // 3. Get Worker-Specific Queue for Transcode workerQueue = await executeActivity(TaskQueueTranscode, getTranscodeWorkerQueueActivity) diff --git a/src/workflow/activities/agent.ts b/src/workflow/activities/agent.ts index cad690b0..4ba0bb86 100644 --- a/src/workflow/activities/agent.ts +++ b/src/workflow/activities/agent.ts @@ -4,6 +4,7 @@ import { s3Service } from '@/services/s3/s3' import { type AgentTool } from '@earendil-works/pi-agent-core' import { type ImageContent } from '@earendil-works/pi-ai' import { type Usage } from '@/services/ai/provider/provider' +import { ApplicationFailure } from '@temporalio/activity' interface AgentExecutionContext { agent: unknown @@ -30,8 +31,18 @@ async function executeAgentPrompt(params: { const teamSkills = context.teamSkills const allowedDomains = context.allowedDomains - if (!agent.provider) throw new Error('agent has no provider configured') - if (!agent.modelRef) throw new Error('agent has no model configured') + if (!agent.provider) { + throw ApplicationFailure.create({ + message: 'agent has no provider configured', + nonRetryable: true, + }) + } + if (!agent.modelRef) { + throw ApplicationFailure.create({ + message: 'agent has no model configured', + nonRetryable: true, + }) + } const providerName = agent.provider.name const modelId = agent.modelRef.modelId diff --git a/src/workflow/activities/ai.ts b/src/workflow/activities/ai.ts index cd6cfea9..ecd8dbe2 100644 --- a/src/workflow/activities/ai.ts +++ b/src/workflow/activities/ai.ts @@ -10,6 +10,7 @@ import * as fs from 'fs' import * as os from 'os' import * as path from 'path' import { promisify } from 'util' +import { ApplicationFailure } from '@temporalio/activity' const execAsync = promisify(exec) @@ -26,7 +27,10 @@ function providerFactory(providerName: string, config: PrismaJson.AiProviderSett pKey = AiProvider.ElevenLabs break default: - throw new Error(`Unsupported provider: ${providerName}`) + throw ApplicationFailure.create({ + message: `Unsupported provider: ${providerName}`, + nonRetryable: true, + }) } switch (pKey) { @@ -40,7 +44,10 @@ function providerFactory(providerName: string, config: PrismaJson.AiProviderSett // eslint-disable-next-line @typescript-eslint/no-explicit-any -- provider config requires a broad casting since it is a JSON property of the provider model return new ElevenLabsProvider(config as any) default: - throw new Error(`Provider implementation for ${providerName} not found`) + throw ApplicationFailure.create({ + message: `Provider implementation for ${providerName} not found`, + nonRetryable: true, + }) } } @@ -68,10 +75,22 @@ export async function generateEmbeddingActivity(params: GenerateEmbeddingParams) const { agent, asset, dbProvider } = params.context as any const config = agent.config as unknown as PrismaJson.AgentConfig - if (!config.provider) throw new Error('embedding provider not configured') - if (!config.model) throw new Error('embedding model not configured') + if (!config.provider) { + throw ApplicationFailure.create({ + message: 'embedding provider not configured', + nonRetryable: true, + }) + } + if (!config.model) { + throw ApplicationFailure.create({ + message: 'embedding model not configured', + nonRetryable: true, + }) + } - if (!asset.mediaType) throw new Error('asset has no media type') + if (!asset.mediaType) { + throw ApplicationFailure.create({ message: 'asset has no media type', nonRetryable: true }) + } const p = providerFactory(config.provider, dbProvider.config as PrismaJson.AiProviderSettings) @@ -85,12 +104,15 @@ export async function generateEmbeddingActivity(params: GenerateEmbeddingParams) const isVideo = asset.mediaType.startsWith('video/') if (!isImage && !isVideo) { - throw new Error(`unsupported media type for embeddings: ${asset.mediaType}`) + throw ApplicationFailure.create({ + message: `unsupported media type for embeddings: ${asset.mediaType}`, + nonRetryable: true, + }) } const key = asset.storageKey?.key if (!key) { - throw new Error(`asset has no key`) + throw ApplicationFailure.create({ message: 'asset has no key', nonRetryable: true }) } const { buffer: data } = await s3Service.getObject(process.env.S3_BUCKET || 'shumai', key) @@ -109,7 +131,12 @@ export async function generateEmbeddingActivity(params: GenerateEmbeddingParams) `ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "${tmpFile}"`, ) const duration = parseFloat(stdout.trim()) - if (isNaN(duration)) throw new Error('failed to parse video duration') + if (isNaN(duration)) { + throw ApplicationFailure.create({ + message: 'failed to parse video duration', + nonRetryable: true, + }) + } const chunkSize = 60.0 for (let start = 0.0; start < duration; start += chunkSize) { diff --git a/src/workflow/activities/db.ts b/src/workflow/activities/db.ts index d7e20f57..7f642683 100644 --- a/src/workflow/activities/db.ts +++ b/src/workflow/activities/db.ts @@ -211,7 +211,9 @@ export async function createCommentActivity(params: CreateCommentParams) { where: { id: params.assetId }, include: { project: true }, }) - if (!asset || !asset.project) throw new Error('asset or project not found') + if (!asset || !asset.project) { + throw ApplicationFailure.create({ message: 'asset or project not found', nonRetryable: true }) + } const teamId = asset.project.teamId // Ensure user exists for agent diff --git a/src/workflow/workflows/ai-transcription.ts b/src/workflow/workflows/ai-transcription.ts index 7538fbfd..b372527a 100644 --- a/src/workflow/workflows/ai-transcription.ts +++ b/src/workflow/workflows/ai-transcription.ts @@ -68,7 +68,10 @@ export async function aiTranscriptionMedia(task: WorkflowTask): Promise { }) if (generatedFiles.length === 0) { - throw new Error('Failed to extract audio for transcription') + throw ApplicationFailure.create({ + message: 'Failed to extract audio for transcription', + nonRetryable: true, + }) } // Simulate work