mirror of
https://github.com/n8n-io/n8n.git
synced 2026-05-24 05:15:16 +02:00
156 lines
4.2 KiB
Markdown
156 lines
4.2 KiB
Markdown
# Implementation Phases
|
|
|
|
This document maps interfaces to implementation phases to help developers focus on what's needed when.
|
|
|
|
## Phase 1.1: Core Runtime Package (MVP)
|
|
|
|
**Goal**: Basic expression evaluation working in CLI/backend
|
|
|
|
**Interfaces Needed**:
|
|
- `RuntimeBridge` - Main bridge interface
|
|
- `BridgeConfig` (without `debug` field)
|
|
- `RuntimeHostInterface` - Runtime-to-host communication
|
|
- `RuntimeGlobals` - Globals injected into runtime
|
|
- `WorkflowDataProxy` - Data access helper
|
|
- `IExpressionEvaluator` - Public API
|
|
- `EvaluatorConfig` (without observability)
|
|
- `WorkflowData` - Input data format
|
|
- `EvaluateOptions` (basic)
|
|
|
|
**Implementations Required**:
|
|
- `IsolatedVmBridge` - For CLI/backend
|
|
- `ExpressionEvaluator` - Main evaluator class
|
|
- Runtime code (runs inside isolate, bundled via esbuild)
|
|
- Lazy loading proxies
|
|
- Expression code cache (per-evaluator, caches tournament-transformed code)
|
|
|
|
**Can Skip**:
|
|
- Observability (use `NoOpProvider` stub)
|
|
- Debug mode
|
|
- Specific error types (use generic `Error`)
|
|
- Web Workers
|
|
- Task runners
|
|
|
|
## Phase 0.2: Observability Infrastructure (PARALLEL)
|
|
|
|
**Goal**: Add metrics, traces, and logs
|
|
|
|
**Interfaces Needed**:
|
|
- `ObservabilityProvider`
|
|
- `MetricsAPI`
|
|
- `TracesAPI`
|
|
- `LogsAPI`
|
|
- `Span`
|
|
|
|
**Implementations Required**:
|
|
- `NoOpProvider` (zero overhead when disabled)
|
|
- `OpenTelemetryProvider`
|
|
- `PostHogProvider` (optional)
|
|
- `CompositeProvider` (use multiple providers)
|
|
|
|
**Integration**:
|
|
- Add to `EvaluatorConfig.observability`
|
|
- Emit metrics/traces from evaluator and bridge
|
|
- Smart sampling implementation
|
|
|
|
## Phase 1.2: Isolate Pooling
|
|
|
|
**Goal**: Handle concurrent evaluations
|
|
|
|
**New Interfaces**: None (uses existing `RuntimeBridge`)
|
|
|
|
**Implementations Required**:
|
|
- `IsolatePool` class
|
|
- Pool configuration
|
|
- Acquire/release mechanism
|
|
- Disposal detection and replacement
|
|
|
|
## Phase 1.3: Extension Framework
|
|
|
|
**Goal**: 100% test compatibility
|
|
|
|
**New Interfaces**: None
|
|
|
|
**Implementation**: Extension functions in runtime
|
|
|
|
## Phase 1.4: Error Handling
|
|
|
|
**Goal**: Graceful error handling with clear messages
|
|
|
|
**Interfaces Needed**:
|
|
- `ExpressionError`
|
|
- `MemoryLimitError`
|
|
- `TimeoutError`
|
|
- `SecurityViolationError`
|
|
- `SyntaxError`
|
|
|
|
**Implementation**: Error handling in all code paths
|
|
|
|
## Phase 2+: Future Enhancements
|
|
|
|
### Web Worker Support
|
|
**Interfaces**: Already defined (same `RuntimeBridge`)
|
|
|
|
**Implementations**:
|
|
- `WebWorkerBridge`
|
|
- Runtime bundled as ESM
|
|
- Note: No lazy loading initially (pre-fetch data)
|
|
|
|
### Chrome DevTools Debugging
|
|
**Config**: `BridgeConfig.debug` field
|
|
|
|
**Implementation**:
|
|
- Inspector protocol integration
|
|
- Debug mode in IsolatedVmBridge
|
|
|
|
### Task Runner Integration (Architecture TBD)
|
|
|
|
Task runners already have process-level isolation. Expression evaluation happens **inside the task runner** (no IPC to worker needed).
|
|
|
|
**Option A**: Use `IsolatedVmBridge` locally within task runner
|
|
- Adds another sandbox layer for extra security
|
|
- Task runner creates local evaluator instance
|
|
- No lazy loading needed (task runner has all data)
|
|
|
|
**Option B**: Evaluate directly without extra sandbox
|
|
- Reuse task runner's existing process isolation
|
|
- Simpler, potentially faster
|
|
- May be sufficient given process-level isolation
|
|
|
|
**Decision pending** - will be made during Phase 2+ implementation.
|
|
|
|
---
|
|
|
|
## Quick Start Guides
|
|
|
|
### For Frontend Developers (Web Worker Integration)
|
|
|
|
**Phase 1**: Skip - Web Workers are Phase 2+
|
|
|
|
**Phase 2**: Focus on:
|
|
1. `RuntimeBridge` interface - Your bridge must implement this
|
|
2. `BridgeConfig` - Configuration options
|
|
3. `WorkflowDataProxy` - How to structure data
|
|
4. Ignore: Observability interfaces (optional)
|
|
|
|
**Key Difference**: Web Workers can't do lazy loading initially, so you'll need to pre-fetch all data before calling `execute()`.
|
|
|
|
### For CLI/Backend Developers
|
|
|
|
**Phase 1.1**: Focus on:
|
|
1. `IsolatedVmBridge` implementation
|
|
2. `ExpressionEvaluator` class
|
|
3. Runtime code (runs inside isolate)
|
|
4. Code cache implementation
|
|
|
|
**Use**: `NoOpProvider` for observability initially
|
|
|
|
**Phase 0.2**: Add real observability providers
|
|
|
|
### For Testing
|
|
|
|
Integration tests use `IsolatedVmBridge` directly (see `src/__tests__/integration.test.ts`).
|
|
|
|
All interfaces in `src/types/` are stable enough to write against before the
|
|
bridge implementation lands.
|