Heuristic:Langgenius Dify Workflow Draft Hash Sync
| Knowledge Sources | |
|---|---|
| Domains | Frontend, Debugging |
| Last Updated | 2026-02-12 08:00 GMT |
Overview
Concurrency rule for workflow draft synchronization: always read the latest hash immediately before sending the sync request, even if the request was queued earlier.
Description
The Dify workflow editor auto-saves draft changes to the backend. When a user modifies the workflow graph (adding nodes, editing connections, changing parameters), the frontend debounces these changes and queues sync requests. Each sync request must include the current graph hash to enable optimistic concurrency control on the backend.
The critical insight is that the hash must be read at request send time, not at queue time. Because multiple edits may occur while a request is queued, using the stale queue-time hash would cause the backend to reject the update or overwrite newer changes.
Usage
Apply this heuristic when implementing any optimistic concurrency control with queued/debounced requests, or when debugging workflow draft save failures where changes appear to be lost.
The Insight (Rule of Thumb)
- Action: Read the current graph hash from the store immediately before dispatching the HTTP request, not when the draft change event fires.
- Value: Prevents stale hash conflicts and ensures each request carries the most recent state.
- Trade-off: Minimal — one extra store read per request (nanoseconds).
Reasoning
The workflow editor fires many rapid state changes (drag node, type text, connect edges). These are debounced before syncing to reduce API calls. If the hash were captured at debounce time:
- User edits node A → hash H1 captured, sync queued
- User edits node B → hash H2 captured, new sync queued
- First sync fires with H1, but the actual graph state has moved to H2
- Backend receives H1, which is stale → potential conflict or data loss
By reading the hash at send time, both syncs use the latest hash, ensuring consistency.
Code evidence from `web/app/components/workflow-app/hooks/use-nodes-sync-draft.ts:114-116`:
// IMPORTANT: Always get the LATEST hash right before sending the request.
// Even if the request is queued, each request uses the most recent hash.