feat(core): Replace unbounded expression code cache with LRU

[ivov]

https://linear.app/n8n/issue/CAT-2419

[cubic-dev-ai]

3 issues found across 7 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/@n8n/expression-runtime/src/evaluator/lru-cache.ts">

<violation number="1" location="packages/@n8n/expression-runtime/src/evaluator/lru-cache.ts:16">
P1: `get()` does not refresh recency until the cache is full, so recently accessed entries can still be evicted as oldest once capacity is reached.</violation>
</file>

<file name="packages/workflow/src/expression.ts">

<violation number="1" location="packages/workflow/src/expression.ts:215">
P2: According to linked Linear issue CAT-2419, this setting should come from `@n8n/config`; reading `process.env` directly here does not meet that requirement.</violation>

<violation number="2" location="packages/workflow/src/expression.ts:216">
P1: Validate the parsed cache size as a positive integer before using it; negative values currently cause evaluator initialization to throw.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Env as Environment Variables
    participant Workflow as Expression (Workflow)
    participant Evaluator as ExpressionEvaluator
    participant Cache as NEW: LruCache
    participant Tournament as Tournament (AST Transform)
    participant Obs as CHANGED: ObservabilityProvider
    participant Bridge as IsolatedVmBridge

    Note over Env, Evaluator: Initialization Phase
    Env->>Workflow: Get N8N_EXPRESSION_ENGINE_MAX_CODE_CACHE_SIZE
    Workflow->>Evaluator: NEW: Initialize with maxCodeCacheSize
    Evaluator->>Cache: NEW: Instantiate with capacity & eviction callback

    Note over Workflow, Bridge: Runtime Evaluation Flow
    Workflow->>Evaluator: evaluate(expression, data)
    Evaluator->>Cache: get(expression)
    
    alt Cache Hit
        Cache-->>Evaluator: transformedCode
        Evaluator->>Obs: NEW: Increment 'expression.code_cache.hit'
    else Cache Miss
        Cache-->>Evaluator: undefined
        Evaluator->>Obs: NEW: Increment 'expression.code_cache.miss'
        Evaluator->>Tournament: getExpressionCode(expression)
        Tournament-->>Evaluator: [transformedCode]
        
        Evaluator->>Cache: set(expression, transformedCode)
        opt NEW: If Capacity Exceeded
            Cache->>Evaluator: onEvict callback
            Evaluator->>Obs: NEW: Increment 'expression.code_cache.eviction'
        end
        Evaluator->>Obs: NEW: Update 'expression.code_cache.size' gauge
    end

    Evaluator->>Bridge: execute(transformedCode, data)
    Bridge-->>Evaluator: result
    Evaluator-->>Workflow: result

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[codecov]

Codecov Report

❌ Patch coverage is 16.66667% with 5 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
packages/workflow/src/expression.ts	16.66%	5 Missing ⚠️

📢 Thoughts on this report? Let us know!

[codecov]

Bundle Report

Changes will increase total bundle size by 781 bytes (0.0%) ⬆️. This is within the configured threshold ✅

Detailed changes

Bundle name	Size	Change
editor-ui-esm	42.93MB	781 bytes (0.0%) ⬆️

Affected Assets, Files, and Routes:

view changes for bundle: editor-ui-esm

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
assets/typescript.worker-*.js	127 bytes	10.67MB	0.0%
assets/worker-*.js	127 bytes	2.95MB	0.0%
assets/constants-*.js	165 bytes	2.9MB	0.01%
assets/ParameterInputList-*.js	88 bytes	1.47MB	0.01%
assets/index-*.js	-1.39kB	1.2MB	-0.12%
assets/users.store-*.js	493 bytes	1.08MB	0.05%
assets/index-*.css	-2.01kB	804.95kB	-0.25%
assets/_MapCache-*.js	131 bytes	592.51kB	0.02%
assets/WorkflowDiffView-*.js	1 bytes	203.91kB	0.0%
assets/usePostMessageHandler-*.js	194 bytes	128.4kB	0.15%
assets/WorkflowLayout-*.js	587 bytes	125.79kB	0.47%
assets/NodeCreator-*.js	101 bytes	101.18kB	0.1%
assets/useCanvasOperations-*.js	-5 bytes	91.27kB	-0.01%
assets/WorkflowHistory-*.js	1.55kB	71.13kB	2.23%
assets/CanvasRunWorkflowButton-*.js	40 bytes	58.65kB	0.07%
assets/WorkflowLayout-*.css	177 bytes	46.15kB	0.39%
assets/WorkflowHistory-*.css	173 bytes	30.74kB	0.57%
assets/WorkflowDiffView-*.css	572 bytes	24.88kB	2.35%
assets/useQuickConnect-*.js	-350 bytes	12.9kB	-2.64%
assets/expression-*.js	-6 bytes	220 bytes	-2.65%
assets/expression-*.js	6 bytes	226 bytes	2.73%

[codspeed]

Merging this PR will degrade performance by 17.13%

❌ 1 regressed benchmark
✅ 31 untouched benchmarks
⏩ 7 skipped benchmarks¹

⚠️ Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
❌	vm micro: Script Compilation - cache hit (repeated expression)	488.2 µs	589.1 µs	-17.13%

---

_{Comparing cat-2419 (2e99c22) with master (bf7379d)²}

Footnotes

1. 7 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

2. No successful run was found on master (884c34e) during the generation of this report, so bf7379d was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[despairblue]

Addressed the following:

• Gauge reset on dispose: expression.code_cache.size now emits 0 when the evaluator is disposed, preventing stale values in metrics backends. Added tests for both the miss-path gauge emission and the dispose reset.
• Test cleanup: Replaced the as ReturnType cast with vi.clearAllMocks() — both in beforeEach for inter-test isolation, and inline where mid-test state reset is needed.
• Benchmark timeout: initializeVmEvaluator now accepts an optional timeout parameter (defaults to 5000ms). The benchmark fixture passes 60s to avoid spurious timeouts under CodSpeed's instruction-counting instrumentation.

[n8n-assistant]

Got released with n8n@2.15.0