Feature: Auto-Discovery for n8n Workflows

Implements automatic discovery of n8n workflows as OpenAI models via tags,
eliminating the need for manual models.json maintenance.

## Overview

The bridge can now automatically discover n8n workflows tagged with
'n8n-openai-model' and expose them as OpenAI models. This is an opt-in
experimental feature that maintains full backward compatibility.

## Key Features

- Automatic discovery via n8n API and workflow tags
- Configurable polling interval (60-600 seconds)
- Graceful fallback to existing models.json if API unavailable
- Exponential backoff after consecutive failures
- Admin endpoints for manual trigger and reload
- Hybrid mode: Runtime discovery with models.json as cache

## Implementation

New Files:
- src/services/modelDiscoveryService.js - Core discovery service
- tests/services/modelDiscoveryService.test.js - 17 unit tests
- tests/benchmark-discovery.test.js - 11 performance tests

Modified Files:
- src/config.js - New environment variables
- src/n8nClient.js - Added getWorkflows() and extractWebhookUrl()
- src/server.js - Discovery service integration
- tests/load/mock-n8n-server.js - n8n API simulation
- Makefile - Restructured load test targets
- README.md - Comprehensive documentation (marked experimental)

## Testing

- 198 tests passing (was 166)
- Coverage: 77.06% overall, 94.89% for discovery service
- Load tests for both manual config and auto-discovery modes
- Performance: 500 workflows processed in <1s

## Configuration

Enable auto-discovery:
- AUTO_FETCH_MODELS_BY_TAG=true
- AUTO_DISCOVERY_TAG=n8n-openai-model
- AUTO_DISCOVERY_POLLING=300
- N8N_API_URL=https://n8n.yourdomain.com
- N8N_API_BEARER_TOKEN=your-token

## Breaking Changes

None. Default behavior unchanged (AUTO_FETCH_MODELS_BY_TAG=false).

## Deprecations

- N8N_BEARER_TOKEN -> Use N8N_WEBHOOK_BEARER_TOKEN (with warning)

## Documentation

- README restructured: Manual setup first, auto-discovery as advanced feature
- Edge cases documented (duplicate workflow names)
- Migration guide included
- All emojis removed from codebase

## Code Quality

- Systematic code review completed
- Mock server pagination fixed
- Config validation at startup
- Duplicate workflow names behavior documented

Author: sveneisenschmidt

.env.example

@@ -5,7 +5,21 @@ PORT=3333
 BEARER_TOKEN=your-secret-api-key-here
 
 # n8n Configuration
+# N8N_BEARER_TOKEN is deprecated, use N8N_WEBHOOK_BEARER_TOKEN instead
 N8N_BEARER_TOKEN=
+N8N_WEBHOOK_BEARER_TOKEN=
+N8N_API_BEARER_TOKEN=
+
+# n8n URLs
+N8N_API_URL=https://n8n.yourdomain.com
+N8N_WEBHOOK_BASE_URL=https://n8n.yourdomain.com
+
+# Auto-Discovery Configuration
+# Set to 'true' to automatically discover workflows tagged with AUTO_DISCOVERY_TAG
+AUTO_FETCH_MODELS_BY_TAG=false
+AUTO_DISCOVERY_TAG=n8n-openai-model
+# Polling interval in seconds (60-600, 0 to disable polling after initial discovery)
+AUTO_DISCOVERY_POLLING=300
 
 # Models Configuration
 MODELS_CONFIG=./models.json

.github/workflows/README.md

@@ -139,13 +139,13 @@ gh pr merge --squash --delete-branch
 
 #### 4. Automatic Release Process
 After merge to `main` (with `release` label):
-1. ✅ `release-on-merge` workflow triggers
-2. ✅ Finds latest tag (e.g., `v0.0.6`)
-3. ✅ Creates new tag (e.g., `v0.0.7`)
-4. ✅ Creates GitHub Release with auto-generated notes
-5. ✅ Docker image builds for amd64 and arm64
-6. ✅ Image pushed to `ghcr.io/sveneisenschmidt/n8n-openai-bridge`
-7. ✅ Tagged with `0.0.7`, `0.0`, `0`, and `latest`
+1. OK `release-on-merge` workflow triggers
+2. OK Finds latest tag (e.g., `v0.0.6`)
+3. OK Creates new tag (e.g., `v0.0.7`)
+4. OK Creates GitHub Release with auto-generated notes
+5. OK Docker image builds for amd64 and arm64
+6. OK Image pushed to `ghcr.io/sveneisenschmidt/n8n-openai-bridge`
+7. OK Tagged with `0.0.7`, `0.0`, `0`, and `latest`
 
 **That's it!** Everything happens in one workflow - no manual steps needed.
 
@@ -205,17 +205,17 @@ After release `v1.0.0`, the following tags are available:
 Configure in GitHub Settings → Branches → Branch protection rules:
 
 ### Main Branch
-- ✅ Require a pull request before merging
-- ✅ Require approvals: 1
-- ✅ Dismiss stale pull request approvals when new commits are pushed
-- ✅ Require status checks to pass before merging:
+- OK Require a pull request before merging
+- OK Require approvals: 1
+- OK Dismiss stale pull request approvals when new commits are pushed
+- OK Require status checks to pass before merging:
   - `test`
   - `docker-build`
   - `lint`
   - `security-scan`
-- ✅ Require branches to be up to date before merging
-- ✅ Require conversation resolution before merging
-- ✅ Do not allow bypassing the above settings
+- OK Require branches to be up to date before merging
+- OK Require conversation resolution before merging
+- OK Do not allow bypassing the above settings
 
 ## Secrets Configuration
 

.github/workflows/ci.yml

@@ -96,11 +96,11 @@ jobs:
           echo "Waiting for container to start..."
           for i in {1..30}; do
             if docker logs test-container 2>&1 | grep -q "Server running on port"; then
-              echo "✓ Container started"
+              echo "OK Container started"
               break
             fi
             if [ $i -eq 30 ]; then
-              echo "✗ Container failed to start"
+              echo "FAIL Container failed to start"
               docker logs test-container
               exit 1
             fi

.github/workflows/manual-docker-build.yml

@@ -60,7 +60,7 @@ jobs:
 
       - name: Summary
         run: |
-          echo "✅ Docker images published for ${{ inputs.version_tag }}:"
+          echo "OK Docker images published for ${{ inputs.version_tag }}:"
           echo ""
           echo "- ghcr.io/${{ github.repository_owner }}/n8n-openai-bridge:latest"
           echo "- ghcr.io/${{ github.repository_owner }}/n8n-openai-bridge:${{ steps.version.outputs.version }}"

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help build rebuild start stop restart clean logs test test-unit test-image test-all test-load verify
+.PHONY: help build rebuild start stop restart clean logs test test-unit test-image test-all test-load test-load-discovery verify
 
 help:
 	@echo "Available commands:"
@@ -14,11 +14,12 @@ help:
 	@echo "  make clean       - Stop and remove containers, images, and volumes"
 	@echo ""
 	@echo "Testing:"
-	@echo "  make test              - Run all tests (unit + image build)"
-	@echo "  make test-unit         - Run unit tests for server logic only"
-	@echo "  make test-image        - Run Docker image build validation tests"
-	@echo "  make test-all          - Alias for test"
-	@echo "  make test-load         - Run load tests with k6 (20 users, 1min)"
+	@echo "  make test                    - Run all tests (unit + image build)"
+	@echo "  make test-unit               - Run unit tests for server logic only"
+	@echo "  make test-image              - Run Docker image build validation tests"
+	@echo "  make test-load               - Run all load tests (manual config + auto-discovery)"
+	@echo "  make test-load-manual-config - Run load tests (manual models.json mode)"
+	@echo "  make test-load-discovery     - Run load tests (auto-discovery mode)"
 
 rebuild: stop build start
 	@echo "Rebuild complete!"
@@ -67,11 +68,9 @@ verify:
 test: test-unit test-image
 	@echo ""
 	@echo "======================================"
-	@echo "✓ All tests passed successfully!"
+	@echo "OK All tests passed successfully!"
 	@echo "======================================"
 
-test-all: test
-
 # Test 1: Unit tests for server logic
 test-unit:
 	@echo "======================================"
@@ -95,24 +94,55 @@ test-image:
 	@echo ""
 	@bash tests/test-image-build.sh
 
-# Test 3: Load testing with k6 (via docker-compose)
-test-load:
+# Test 3: Load testing with k6 (via docker-compose) - All modes
+test-load: test-load-manual-config test-load-discovery
+	@echo ""
+	@echo "======================================"
+	@echo "All load tests completed!"
+	@echo "======================================"
+
+# Test 3a: Load testing - Manual models.json configuration
+test-load-manual-config:
 	@echo ""
 	@echo "======================================"
-	@echo "Running Load Tests (20 users, 1min)"
+	@echo "Running Load Tests (Manual Config)"
+	@echo "20 users, 1min, models.json"
 	@echo "======================================"
 	@echo ""
 	@echo "Building images..."
-	@VUS=20 DURATION=1m docker compose -f docker/docker-compose.loadtest.yml build
+	@VUS=20 DURATION=1m AUTO_FETCH_MODELS_BY_TAG=false docker compose -f docker/docker-compose.loadtest.yml build
 	@echo ""
 	@echo "Starting services (mock-n8n, bridge, k6)..."
-	@VUS=20 DURATION=1m docker compose -f docker/docker-compose.loadtest.yml up --abort-on-container-exit --exit-code-from k6
+	@VUS=20 DURATION=1m AUTO_FETCH_MODELS_BY_TAG=false docker compose -f docker/docker-compose.loadtest.yml up --abort-on-container-exit --exit-code-from k6
 	@echo ""
 	@echo "Cleaning up..."
 	@docker compose -f docker/docker-compose.loadtest.yml down -v
 	@echo ""
-	@echo "✓ Load tests completed!"
+	@echo "OK Load tests (Manual Config) completed!"
 	@echo ""
 	@if [ -f tests/load/summary.json ]; then \
-		echo "📊 Detailed results saved to: tests/load/summary.json"; \
-	fi
+		echo "Detailed results saved to: tests/load/summary.json"; \
+	fi
+
+# Test 3b: Load testing - Auto-Discovery mode
+test-load-discovery:
+	@echo ""
+	@echo "======================================"
+	@echo "Running Load Tests (Auto-Discovery)"
+	@echo "20 users, 1min, auto-discovery mode"
+	@echo "======================================"
+	@echo ""
+	@echo "Building images..."
+	@VUS=20 DURATION=1m AUTO_FETCH_MODELS_BY_TAG=true N8N_API_BEARER_TOKEN=mock-token docker compose -f docker/docker-compose.loadtest.yml build
+	@echo ""
+	@echo "Starting services (mock-n8n, bridge, k6)..."
+	@VUS=20 DURATION=1m AUTO_FETCH_MODELS_BY_TAG=true N8N_API_BEARER_TOKEN=mock-token docker compose -f docker/docker-compose.loadtest.yml up --abort-on-container-exit --exit-code-from k6
+	@echo ""
+	@echo "Cleaning up..."
+	@docker compose -f docker/docker-compose.loadtest.yml down -v
+	@echo ""
+	@echo "OK Load tests (Auto-Discovery) completed!"
+	@echo ""
+	@if [ -f tests/load/summary.json ]; then \
+		echo "Detailed results saved to: tests/load/summary.json"; \
+	fi