n8n Mutex Lease Tokens for Hierarchical Namespaces + Rate Limit

Lock hierarchical namespaces in n8n with mutex lease tokens (plus optional rate limiting)

This sub-workflow acquires a mutex-style lease token for a dot-separated namespace (e.g., a.b) using an n8n Data Table. It can also enforce a token-bucket rate quota per namespace level—then returns the token, the claimed chain, and lease expiry details.

What this workflow does

• Accepts a required mutex namespace from a calling workflow (for example, a.b).
• Expands the namespace into a hierarchical chain (e.g., a and a.b) and uses the current execution ID as the candidate lock token.
• Checks the n8n Data Table for each chain level to see whether a lock is already leased or whether a configured rate window has been exceeded.
• If not available, it waits and re-checks (up to 10 seconds for busy locks, or until the rate window resets).
• Upserts each namespace level in the Data Table with:
  • currentToken (token based on execution ID)
  • validUntil set to a 60-second lease
  • updated rate-limit counters when rate limiting is enabled
• Verifies ownership by re-reading the Data Table. If any level wasn’t claimed correctly, it rolls back partial claims and retries after a short wait.

Use cases

• Prevent overlapping runs for operations scoped to tenant.resource (e.g., acme.sync), ensuring only one workflow holds the lease.
• Rate-limit expensive API calls per hierarchical key (e.g., per account and account.endpoint).
• Build safe concurrency controls for SaaS automation pipelines where multiple workflows contend for the same namespace.

Technical details

• Primary storage: n8n Data Table (rows keyed by mutex).
• Configurable columns: mutex, currentToken, validUntil, and optionally rateMax, rateWindowSeconds, rateUsed, rateWindowStart.
• Workflow nodes used: if, set, code, wait, limit, and hierarchical split-out logic.