PR #35301: feat(api): add async response_mode for workflow execution

• Repository: langgenius/dify
• Author: Umair706
• State: open | merged: False
• Link: https://github.com/langgenius/dify/pull/35301

Description (problem / solution / changelog)

[!IMPORTANT]

1. Make sure you have read our contribution guidelines
2. Ensure there is an associated issue and you have been assigned to it
3. Use the correct syntax to link this PR: Fixes #<issue number>.

Fixes #35327

Summary

Add response_mode: "async" to POST /v1/workflows/run — a true fire-and-forget mode that returns 202 Accepted with a workflow_run_id immediately, instead of holding an HTTP connection open. Clients poll results via the existing GET /v1/workflows/run/{id} endpoint.

Motivation: Currently Dify only supports blocking (wait for result) and streaming (hold SSE connection). Both require holding an HTTP connection open for the entire workflow duration. This causes HTTP timeouts on long workflows, and stuck "running" status when SSE connections drop (#26169). The async mode solves this with a standard REST 202+poll pattern.

Core changes

• Accept "async" in WorkflowRunPayload.response_mode
• Add generate_async() to AppGenerateService — pre-creates a WorkflowRun row with status=SCHEDULED, dispatches to the existing Celery task, returns the workflow_run_id without subscribing to Redis pub/sub events
• Add WorkflowRunTriggeredFrom.API_ASYNC enum value for audit trail
• Preserve triggered_from during repository session.merge() so async runs keep their api-async label

Production safeguards

• Idempotency-Key header support (Redis-backed, 24h TTL) — prevents duplicate workflow execution on client retry
• Per-tenant concurrency guard (SQL COUNT query, default limit 50) — returns 429 Too Many Requests when exceeded
• Zombie reaper Celery Beat task — force-fails WorkflowRun rows stuck in SCHEDULED (>5min) or RUNNING (>30min). This also fixes #26169 for existing streaming/blocking modes.

Files changed

Closes #24263 Fixes #26169

Screenshots

N/A — backend-only change, no UI modifications.

Checklist

• This change requires a documentation update, included: Dify Document
• I understand that this PR may be closed in case there was no previous discussion or issues. (This doesn't apply to typos!)
• I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
• I've updated the documentation accordingly.
• I ran make lint and make type-check (backend) and cd web && pnpm exec vp staged (frontend) to appease the lint gods

Changed files

• api/.env.example (modified, +5/-0)
• api/configs/feature/__init__.py (modified, +16/-0)
• api/controllers/service_api/app/workflow.py (modified, +55/-4)
• api/core/repositories/sqlalchemy_workflow_execution_repository.py (modified, +1/-0)
• api/extensions/ext_celery.py (modified, +7/-0)
• api/models/enums.py (modified, +1/-0)
• api/schedule/reap_zombie_workflow_runs_task.py (added, +46/-0)
• api/services/app_generate_service.py (modified, +222/-1)
• api/tasks/app_generate/workflow_execute_task.py (modified, +36/-2)
• api/tests/unit_tests/core/repositories/test_sqlalchemy_workflow_execution_repository.py (modified, +27/-0)
• api/tests/unit_tests/schedule/test_reap_zombie_workflow_runs_task.py (added, +102/-0)
• api/tests/unit_tests/services/test_app_generate_service_async.py (added, +288/-0)
• api/tests/unit_tests/tasks/test_workflow_execute_task_error_handling.py (added, +223/-0)
• docker/.env.example (modified, +5/-0)
• docker/docker-compose.yaml (modified, +4/-0)