* fix: critical memory leak from per-session database connections (#542)
Each MCP session was creating its own database connection (~900MB),
causing OOM kills every ~20 minutes with 3-4 concurrent sessions.
Changes:
- Add SharedDatabase singleton pattern - all sessions share ONE connection
- Reduce session timeout from 30 min to 5 min (configurable)
- Add eager cleanup for reconnecting instances
- Fix telemetry event listener leak
Memory impact: ~900MB/session → ~68MB shared + ~5MB/session overhead
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Conceived by Romuald Czlonkowski - https://www.aiadvisors.pl/en
* fix: resolve test failures from shared database race conditions
- Fix `shutdown()` to respect shared database pattern (was directly closing)
- Add `await this.initialized` in both `close()` and `shutdown()` to prevent
race condition where cleanup runs while initialization is in progress
- Add double-shutdown protection with `isShutdown` flag
- Export `SharedDatabaseState` type for proper typing
- Include error details in debug logs
- Add MCP server close to `shutdown()` for consistency with `close()`
- Null out `earlyLogger` in `shutdown()` for consistency
The CI test failure "The database connection is not open" was caused by:
1. `shutdown()` directly calling `this.db.close()` which closed the SHARED
database connection, breaking subsequent tests
2. Race condition where `shutdown()` ran before initialization completed
Conceived by Romuald Członkowski - www.aiadvisors.pl/en
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* test: add unit tests for shared-database module
Add comprehensive unit tests covering:
- getSharedDatabase: initialization, reuse, different path error, concurrent requests
- releaseSharedDatabase: refCount decrement, double-release guard
- closeSharedDatabase: state clearing, error handling, re-initialization
- Helper functions: isSharedDatabaseInitialized, getSharedDatabaseRefCount
21 tests covering the singleton database connection pattern used to prevent
~900MB memory leaks per session.
Conceived by Romuald Członkowski - www.aiadvisors.pl/en
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Fixed a critical bug where workflow mutation data was corrupted during
serialization to Supabase. The recursive toSnakeCase() function was
converting nested workflow data, mangling:
- Connection keys (node names like "Webhook" → "_webhook")
- Node field names (typeVersion → type_version)
Solution: Replace recursive conversion with selective mutationToSupabaseFormat()
that only converts top-level field names to snake_case while preserving
nested workflow data exactly as-is.
Impact:
- 98.9% of workflow mutations had corrupted data
- Deployability rate improved from ~21% to ~68%
Changes:
- src/telemetry/batch-processor.ts: New selective converter
- tests/unit/telemetry/batch-processor.test.ts: 3 new regression tests
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Romuald Członkowski <romualdczlonkowski@MacBook-Pro-Romuald.local>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
* feat: add comprehensive telemetry for partial workflow updates
Implement telemetry infrastructure to track workflow mutations from
partial update operations. This enables data-driven improvements to
partial update tooling by capturing:
- Workflow state before and after mutations
- User intent and operation patterns
- Validation results and improvements
- Change metrics (nodes/connections modified)
- Success/failure rates and error patterns
New Components:
- Intent classifier: Categorizes mutation patterns
- Intent sanitizer: Removes PII from user instructions
- Mutation validator: Ensures data quality before tracking
- Mutation tracker: Coordinates validation and metric calculation
Extended Components:
- TelemetryManager: New trackWorkflowMutation() method
- EventTracker: Mutation queue management
- BatchProcessor: Mutation data flushing to Supabase
MCP Tool Enhancements:
- n8n_update_partial_workflow: Added optional 'intent' parameter
- n8n_update_full_workflow: Added optional 'intent' parameter
- Both tools now track mutations asynchronously
Database Schema:
- New workflow_mutations table with 20+ fields
- Comprehensive indexes for efficient querying
- Supports deduplication and data analysis
This telemetry system is:
- Privacy-focused (PII sanitization, anonymized users)
- Non-blocking (async tracking, silent failures)
- Production-ready (batching, retries, circuit breaker)
- Backward compatible (all parameters optional)
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
* fix: correct SQL syntax for expression index in workflow_mutations schema
The expression index for significant changes needs double parentheses
around the arithmetic expression to be valid PostgreSQL syntax.
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
* fix: enable RLS policies for workflow_mutations table
Enable Row-Level Security and add policies:
- Allow anonymous (anon) inserts for telemetry data collection
- Allow authenticated reads for data analysis and querying
These policies are required for the telemetry system to function
correctly with Supabase, as the MCP server uses the anon key to
insert mutation data.
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
* fix: reduce mutation auto-flush threshold from 5 to 2
Lower the auto-flush threshold for workflow mutations from 5 to 2 to ensure
more timely data persistence. Since mutations are less frequent than regular
telemetry events, a lower threshold provides:
- Faster data persistence (don't wait for 5 mutations)
- Better testing experience (easier to verify with fewer operations)
- Reduced risk of data loss if process exits before threshold
- More responsive telemetry for low-volume mutation scenarios
This complements the existing 5-second periodic flush and process exit
handlers, ensuring mutations are persisted promptly.
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
* fix: improve mutation telemetry error logging and diagnostics
Changes:
- Upgrade error logging from debug to warn level for better visibility
- Add diagnostic logging to track mutation processing
- Log telemetry disabled state explicitly
- Add context info (sessionId, intent, operationCount) to error logs
- Remove 'await' from telemetry calls to make them truly non-blocking
This will help identify why mutations aren't being persisted to the
workflow_mutations table despite successful workflow operations.
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
* feat: enhance workflow mutation telemetry for better AI responses
Improve workflow mutation tracking to capture comprehensive data that helps provide better responses when users update workflows. This enhancement collects workflow state, user intent, and operation details to enable more context-aware assistance.
Key improvements:
- Reduce auto-flush threshold from 5 to 2 for more reliable mutation tracking
- Add comprehensive workflow and credential sanitization to mutation tracker
- Document intent parameter in workflow update tools for better UX
- Fix mutation queue handling in telemetry manager (flush now handles 3 queues)
- Add extensive unit tests for mutation tracking and validation (35 new tests)
Technical changes:
- mutation-tracker.ts: Multi-layer sanitization (workflow, node, parameter levels)
- batch-processor.ts: Support mutation data flushing to Supabase
- telemetry-manager.ts: Auto-flush mutations at threshold 2, track mutations queue
- handlers-workflow-diff.ts: Track workflow mutations with sanitized data
- Tests: 13 tests for mutation-tracker, 22 tests for mutation-validator
The intent parameter messaging emphasizes user benefit ("helps to return better response") rather than technical implementation details.
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* chore: bump version to 2.22.16 with telemetry changelog
Updated package.json and package.runtime.json to version 2.22.16.
Added comprehensive CHANGELOG entry documenting workflow mutation
telemetry enhancements for better AI-powered workflow assistance.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
Co-Authored-By: Claude <noreply@anthropic.com>
* fix: resolve TypeScript lint errors in telemetry tests
Fixed type issues in mutation-tracker and mutation-validator tests:
- Import and use MutationToolName enum instead of string literals
- Fix ValidationResult.errors to use proper object structure
- Add UpdateNodeOperation type assertion for operation with nodeName
All TypeScript errors resolved, lint now passes.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
- Fix event validator to not filter out generic 'key' property
- Handle compound key terms (apikey, api_key) while allowing standalone 'key'
- Fix batch processor test expectations to account for circuit breaker limits
- Adjust dead letter queue test to expect 25 items due to circuit breaker opening after 5 failures
- Fix test mocks to fail for all retry attempts before adding to dead letter queue
All 252 telemetry tests now passing with 90.75% code coverage
- Fix fake timer issues in rate-limiter and batch-processor tests
- Add proper timer handling for vitest fake timers
- Handle timer.unref() compatibility with fake timers
- Add test environment detection to skip timeouts in tests
This resolves the CI timeout issues where tests would hang indefinitely.
Major improvements to telemetry system addressing code review findings:
Architecture & Modularization:
- Split 636-line TelemetryManager into 7 focused modules
- Separated concerns: event tracking, batch processing, validation, rate limiting
- Lazy initialization pattern to avoid early singleton creation
- Clean separation of responsibilities
Security & Privacy:
- Added comprehensive input validation with Zod schemas
- Sanitization of sensitive data (URLs, API keys, emails)
- Expanded sensitive key detection patterns (25+ patterns)
- Row Level Security on Supabase backend
- Added data deletion contact info (romuald@n8n-mcp.com)
Performance & Reliability:
- Sliding window rate limiter (100 events/minute)
- Circuit breaker pattern for network failures
- Dead letter queue for failed events
- Exponential backoff with jitter for retries
- Performance monitoring with overhead tracking (<5%)
- Memory-safe array limits in rate limiter
Testing:
- Comprehensive test coverage (87%+ for core modules)
- Unit tests for all new modules
- Integration tests for MCP telemetry
- Fixed test isolation issues
Data Management:
- Clear user consent in welcome message
- Batch processing with deduplication
- Automatic workflow flushing
BREAKING CHANGE: TelemetryManager constructor is now private, use getInstance()
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
