ldap-rest 0.0.1 → 0.1.1

package/docs/plugins/DEVELOPMENT.md

@@ -61,6 +61,54 @@ export default class MyPlugin extends DmPlugin {
 - **this.logger**: Winston logger instance
 - **this.registeredHooks**: Access to global hook registry
 
+### Error Handling and Server Resilience
+
+LDAP-Rest includes robust error handling to ensure the server remains operational even when plugins encounter errors:
+
+#### Global Error Handling
+
+The server automatically catches and handles:
+
+- **Uncaught exceptions** in plugin code
+- **Unhandled promise rejections**
+- **Errors in async route handlers**
+
+All errors are logged with full stack traces without crashing the server.
+
+#### Using asyncHandler
+
+For async route handlers, **always use the `asyncHandler` wrapper**:
+
+```typescript
+import DmPlugin, { asyncHandler } from '../../abstract/plugin';
+
+export default class MyPlugin extends DmPlugin {
+  api(app: Express): void {
+    // ✅ Correct: Errors are automatically caught
+    app.get(
+      '/api/data',
+      asyncHandler(async (req, res) => {
+        const data = await someAsyncOperation();
+        res.json(data);
+      })
+    );
+
+    // ❌ Wrong: Errors can crash the server
+    app.get('/api/data', async (req, res) => {
+      const data = await someAsyncOperation();
+      res.json(data);
+    });
+  }
+}
+```
+
+The `asyncHandler` is exported from:
+
+- `ldap-rest/abstract/plugin` (recommended for plugins)
+- `ldap-rest` (for external use)
+
+See [Exposing API Endpoints](#exposing-api-endpoints) for detailed examples.
+
 ---
 
 ## Creating Your Plugin
@@ -78,7 +126,7 @@ Create a file in `src/plugins/<category>/<pluginName>.ts`:
  */
 import type { Express, Request, Response } from 'express';
 
-import DmPlugin, { type Role } from '../../abstract/plugin';
+import DmPlugin, { type Role, asyncHandler } from '../../abstract/plugin';
 import type { DM } from '../../bin';
 import type { Hooks } from '../../hooks';
 
@@ -104,12 +152,15 @@ export default class WebhookNotifier extends DmPlugin {
 
   // Register API endpoints
   api(app: Express): void {
-    app.get(`${this.config.api_prefix}/v1/webhook/status`, (req, res) => {
-      res.json({
-        status: 'active',
-        url: this.config.webhook_url,
-      });
-    });
+    app.get(
+      `${this.config.api_prefix}/v1/webhook/status`,
+      asyncHandler(async (req, res) => {
+        res.json({
+          status: 'active',
+          url: this.config.webhook_url,
+        });
+      })
+    );
   }
 
   // Register hooks
@@ -152,15 +203,17 @@ Create a standalone file anywhere on your system, e.g., `/opt/custom-plugins/my-
  * External plugin example
  * This plugin can be loaded from anywhere
  */
-import type { Express } from 'express';
+import type { Express, Request, Response } from 'express';
 
 // Import from ldap-rest (if installed as npm package)
-// import DmPlugin from 'ldap-rest/plugin';
+// import DmPlugin, { asyncHandler } from 'ldap-rest/plugin';
 
 // Or use relative path to node_modules
 import DmPlugin from './node_modules/ldap-rest/dist/abstract/plugin.js';
 import type { DM } from './node_modules/ldap-rest/dist/bin/index.js';
 import type { Hooks } from './node_modules/ldap-rest/dist/hooks.js';
+// Import asyncHandler for error handling
+import { asyncHandler } from './node_modules/ldap-rest/dist/lib/utils.js';
 
 export default class ExternalAuditPlugin extends DmPlugin {
   name = 'externalAudit';
@@ -174,12 +227,15 @@ export default class ExternalAuditPlugin extends DmPlugin {
   }
 
   api(app: Express): void {
-    app.get(`${this.config.api_prefix}/v1/audit/stats`, (req, res) => {
-      res.json({
-        message: 'External plugin API',
-        auditEnabled: true,
-      });
-    });
+    app.get(
+      `${this.config.api_prefix}/v1/audit/stats`,
+      asyncHandler(async (req: Request, res: Response) => {
+        res.json({
+          message: 'External plugin API',
+          auditEnabled: true,
+        });
+      })
+    );
   }
 
   hooks: Hooks = {
@@ -551,81 +607,118 @@ hooks: Hooks = {
 
 ### Exposing API Endpoints
 
-Create REST API endpoints for your plugin:
+Create REST API endpoints for your plugin. **Important:** Always use the `asyncHandler` wrapper for async routes to ensure errors are properly handled and don't crash the server.
 
 ```typescript
+import DmPlugin, { asyncHandler } from '../../abstract/plugin';
+
 api(app: Express): void {
-  // GET endpoint
+  // GET endpoint with asyncHandler
   app.get(
     `${this.config.api_prefix}/v1/myplugin/status`,
-    async (req: Request, res: Response) => {
-      try {
-        const status = await this.getStatus();
-        res.json({ success: true, data: status });
-      } catch (error) {
-        res.status(500).json({
-          success: false,
-          error: error.message
-        });
-      }
-    }
+    asyncHandler(async (req: Request, res: Response) => {
+      const status = await this.getStatus();
+      res.json({ success: true, data: status });
+    })
   );
 
-  // POST endpoint with body
+  // POST endpoint with body validation
   app.post(
     `${this.config.api_prefix}/v1/myplugin/process`,
-    async (req: Request, res: Response) => {
-      try {
-        // Validate request body
-        if (!req.body || !req.body.data) {
-          return res.status(400).json({
-            success: false,
-            error: 'data is required'
-          });
-        }
-
-        const result = await this.processData(req.body.data);
-        res.json({ success: true, data: result });
-      } catch (error) {
-        this.logger.error('Process failed:', error);
-        res.status(500).json({
+    asyncHandler(async (req: Request, res: Response) => {
+      // Validate request body
+      if (!req.body || !req.body.data) {
+        return res.status(400).json({
           success: false,
-          error: error.message
+          error: 'data is required'
         });
       }
-    }
+
+      const result = await this.processData(req.body.data);
+      res.json({ success: true, data: result });
+    })
   );
 
   // PUT endpoint
   app.put(
     `${this.config.api_prefix}/v1/myplugin/config`,
-    async (req: Request, res: Response) => {
-      try {
-        await this.updateConfig(req.body);
-        res.json({ success: true });
-      } catch (error) {
-        res.status(500).json({ success: false, error: error.message });
-      }
-    }
+    asyncHandler(async (req: Request, res: Response) => {
+      await this.updateConfig(req.body);
+      res.json({ success: true });
+    })
   );
 
   // DELETE endpoint
   app.delete(
     `${this.config.api_prefix}/v1/myplugin/cache`,
-    async (req: Request, res: Response) => {
-      try {
-        await this.clearCache();
-        res.json({ success: true, message: 'Cache cleared' });
-      } catch (error) {
-        res.status(500).json({ success: false, error: error.message });
-      }
-    }
+    asyncHandler(async (req: Request, res: Response) => {
+      await this.clearCache();
+      res.json({ success: true, message: 'Cache cleared' });
+    })
   );
 
   this.logger.info('MyPlugin API endpoints registered');
 }
 ```
 
+#### Error Handling Best Practices
+
+The `asyncHandler` wrapper automatically catches errors and passes them to the global error middleware. This ensures:
+
+- **Server stability**: Exceptions in routes won't crash the server
+- **Consistent error responses**: All errors return proper HTTP 500 responses
+- **Automatic logging**: Errors are logged with full stack traces
+- **Clean code**: No need for try/catch blocks in every route
+
+**Without asyncHandler (DON'T DO THIS):**
+
+```typescript
+// ❌ BAD: Unhandled async errors can crash the server
+app.get('/api/data', async (req, res) => {
+  const data = await fetchData(); // If this throws, server crashes
+  res.json(data);
+});
+```
+
+**With asyncHandler (RECOMMENDED):**
+
+```typescript
+// ✅ GOOD: Errors are caught and handled gracefully
+app.get(
+  '/api/data',
+  asyncHandler(async (req, res) => {
+    const data = await fetchData(); // If this throws, error is logged and 500 returned
+    res.json(data);
+  })
+);
+```
+
+**Custom error handling:**
+
+```typescript
+// You can still handle specific errors manually
+app.post(
+  '/api/process',
+  asyncHandler(async (req, res) => {
+    try {
+      const result = await processData(req.body);
+      res.json({ success: true, data: result });
+    } catch (error) {
+      if (error instanceof ValidationError) {
+        // Handle specific error types
+        return res.status(400).json({
+          success: false,
+          error: 'Validation failed',
+          details: error.details,
+        });
+      }
+      // Re-throw to let asyncHandler handle it
+      throw error;
+    }
+  })
+);
+```
+
 ### Logging
 
 Use the provided logger with appropriate levels:
@@ -781,7 +874,7 @@ Here's a complete, production-ready plugin that sends webhook notifications on L
 import type { Express, Request, Response } from 'express';
 import crypto from 'crypto';
 
-import DmPlugin, { type Role } from '../../abstract/plugin';
+import DmPlugin, { type Role, asyncHandler } from '../../abstract/plugin';
 import type { DM } from '../../bin';
 import type { Hooks } from '../../hooks';
 import type { AttributesList, ModifyRequest } from '../../lib/ldapActions';
@@ -854,7 +947,7 @@ export default class NotificationPlugin extends DmPlugin {
     // Get webhook stats
     app.get(
       `${this.config.api_prefix}/v1/notifications/stats`,
-      (req: Request, res: Response) => {
+      asyncHandler(async (req: Request, res: Response) => {
         res.json({
           success: true,
           data: {
@@ -863,23 +956,16 @@ export default class NotificationPlugin extends DmPlugin {
             enabledEvents: Array.from(this.enabledEvents),
           },
         });
-      }
+      })
     );
 
     // Test webhook
     app.post(
       `${this.config.api_prefix}/v1/notifications/test`,
-      async (req: Request, res: Response) => {
-        try {
-          await this.sendWebhook('test', 'test', { message: 'Test webhook' });
-          res.json({ success: true, message: 'Test webhook sent' });
-        } catch (error) {
-          res.status(500).json({
-            success: false,
-            error: (error as Error).message,
-          });
-        }
-      }
+      asyncHandler(async (req: Request, res: Response) => {
+        await this.sendWebhook('test', 'test', { message: 'Test webhook' });
+        res.json({ success: true, message: 'Test webhook sent' });
+      })
     );
 
     this.logger.info('NotificationPlugin API registered');

package/docs/testing-with-embedded-ldap.md

@@ -0,0 +1,347 @@
+# Testing with Embedded LDAP Server
+
+## Overview
+
+The test suite now includes an **embedded LDAP server** that runs automatically in Docker when no external LDAP is configured. This provides:
+
+- ✅ **Zero-configuration testing** - Works out of the box in CI/CD
+- ✅ **Isolation** - Each test run gets a fresh LDAP instance
+- ✅ **Flexibility** - Use either embedded or external LDAP
+- ✅ **Fast** - Server starts in ~2-3 seconds
+
+## How It Works
+
+### Automatic Server Selection
+
+The test framework automatically detects which LDAP server to use:
+
+```
+┌─────────────────────────────────────┐
+│ Test starts                         │
+└──────────────┬──────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────┐
+│ Check environment variables:        │
+│ - DM_LDAP_URL                       │
+│ - DM_LDAP_DN                        │
+│ - DM_LDAP_PWD                       │
+│ - DM_LDAP_BASE                      │
+└──────────────┬──────────────────────┘
+               │
+        ┌──────┴──────┐
+        │             │
+        ▼             ▼
+  ┌─────────┐   ┌──────────┐
+  │ All set │   │ Missing  │
+  └────┬────┘   └─────┬────┘
+       │              │
+       ▼              ▼
+  ┌─────────────┐  ┌────────────────┐
+  │ Use         │  │ Start embedded │
+  │ external    │  │ Docker LDAP    │
+  │ LDAP        │  │ server         │
+  └─────────────┘  └────────────────┘
+```
+
+### Test Output Examples
+
+**With embedded LDAP (default):**
+
+```
+🚀 Setting up global test environment...
+
+ℹ️  No external LDAP configured, starting embedded LDAP server...
+
+Starting LDAP test server on port 36759...
+✓ LDAP test server started on port 36759 (container: ldap-test-...)
+Loading initial LDIF from .../base-structure.ldif...
+✓ Initial LDIF loaded
+✓ Embedded LDAP server ready
+  URL: ldap://localhost:36759
+  Base DN: dc=example,dc=com
+```
+
+**With external LDAP:**
+
+```
+🚀 Setting up global test environment...
+
+✓ Using external LDAP server
+  URL: ldap://my-server:389
+  Base DN: dc=company,dc=com
+```
+
+## Usage
+
+### Running Tests
+
+**Using embedded LDAP (no setup required):**
+
+```bash
+npm test
+npm run test:one test/plugins/ldap/flatGeneric.test.ts
+```
+
+**Using external LDAP:**
+
+```bash
+export DM_LDAP_URL=ldap://localhost:389
+export DM_LDAP_DN=cn=admin,dc=example,dc=com
+export DM_LDAP_PWD=secret
+export DM_LDAP_BASE=dc=example,dc=com
+
+npm test
+```
+
+### In CI/CD
+
+**GitHub Actions example:**
+
+```yaml
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+        # No LDAP setup needed - embedded server starts automatically!
+```
+
+## LDAP Fixtures
+
+The embedded server loads pre-configured test data:
+
+### Base Structure (`test/fixtures/base-structure.ldif`)
+
+- **Branches:**
+  - `ou=users,dc=example,dc=com` (B2C users)
+  - `ou=groups,dc=example,dc=com` (B2C groups)
+  - `ou=nomenclature,dc=example,dc=com` (reference data)
+
+- **Test Users:**
+  - `john.doe@example.com` / password: `password123`
+  - `jane.smith@example.com` / password: `password123`
+
+- **Test Groups:**
+  - `cn=admins` (contains john.doe, jane.smith)
+
+- **Nomenclature Data:**
+  - Titles: Dr, Mr, Ms
+  - List Types: openList, memberRestrictedList
+  - Mailbox Types: group, mailingList, teamMailbox
+
+### B2B Organizations (`test/fixtures/b2b-organizations.ldif`)
+
+For future B2B testing:
+
+- **Acme Corporation** (`o=acme-corp`)
+  - Users: alice@acme-corp.example.com, bob@acme-corp.example.com
+  - Groups: engineering, management
+
+- **Beta Industries** (`o=beta-industries`)
+  - Users: charlie@beta-industries.example.com
+  - Groups: sales
+
+## Implementation Details
+
+### Key Files
+
+```
+test/
+├── setup.ts                      # Global test hooks
+├── helpers/
+│   ├── ldapServer.ts            # LDAP Docker server management
+│   ├── env.ts                   # Environment detection
+│   └── testSetup.ts             # Helper to access server in tests
+└── fixtures/
+    ├── base-structure.ldif      # B2C test data
+    └── b2b-organizations.ldif   # B2B test data (future)
+```
+
+### How It Works Internally
+
+1. **Startup** (`test/setup.ts:mochaHooks.beforeAll`):
+   - Check if `DM_LDAP_*` env vars are set
+   - If yes → use external LDAP
+   - If no → start Docker container with OpenLDAP
+   - Load fixtures from `test/fixtures/*.ldif`
+   - Set environment variables for DM
+
+2. **During Tests**:
+   - All tests use `process.env.DM_LDAP_*` transparently
+   - Works exactly the same whether using embedded or external LDAP
+
+3. **Cleanup** (`test/setup.ts:mochaHooks.afterAll`):
+   - Stop and remove Docker container (only if embedded)
+   - External LDAP is left untouched
+
+### Environment Variables Set
+
+When using embedded LDAP, these are automatically set:
+
+```bash
+DM_LDAP_URL=ldap://localhost:<random-port>
+DM_LDAP_DN=cn=admin,dc=example,dc=com
+DM_LDAP_PWD=adminpassword
+DM_LDAP_BASE=dc=example,dc=com
+DM_LDAP_TOP_ORGANIZATION=dc=example,dc=com
+DM_JAMES_WEBADMIN_URL=http://localhost:8000
+DM_JAMES_WEBADMIN_TOKEN=test-token
+```
+
+## Accessing the LDAP Server in Tests
+
+### Standard Usage (via DM)
+
+Most tests don't need direct LDAP access - they test via the API:
+
+```typescript
+import { DM } from '../../../src/bin';
+
+describe('My plugin', () => {
+  let server: DM;
+
+  before(async () => {
+    server = new DM(); // Reads env vars automatically
+    await server.ready;
+  });
+
+  it('should work', async () => {
+    // Test via API
+    const res = await request.get('/api/v1/users');
+    expect(res.status).to.equal(200);
+  });
+});
+```
+
+### Direct LDAP Access
+
+For tests that need direct LDAP operations:
+
+```typescript
+import { getTestLdapServer } from '../helpers/testSetup';
+
+describe('Advanced LDAP test', () => {
+  it('should perform raw LDAP operations', async () => {
+    const server = getTestLdapServer();
+
+    // Direct LDAP search
+    const result = await server.search('(uid=john.doe)', ['cn', 'mail']);
+    expect(result).to.include('john.doe');
+
+    // Load additional test data
+    await server.loadLdif(`
+      dn: uid=test,ou=users,dc=example,dc=com
+      objectClass: inetOrgPerson
+      uid: test
+      cn: Test User
+      sn: User
+      mail: test@example.com
+    `);
+  });
+});
+```
+
+## Requirements
+
+- **Docker** must be installed and running
+- Tests will fail gracefully if Docker is not available
+- Port range 30000-40000 must be available (for random port assignment)
+
+## Troubleshooting
+
+### Container Won't Start
+
+```bash
+# Check Docker is running
+docker ps
+
+# Check for conflicting containers
+docker ps -a | grep ldap-test
+
+# Clean up old test containers
+docker rm -f $(docker ps -a | grep ldap-test | awk '{print $1}')
+```
+
+### Tests Timeout
+
+Increase timeout in your test if LDAP is slow to start:
+
+```typescript
+before(async function () {
+  this.timeout(120000); // 2 minutes
+  // ...
+});
+```
+
+### Wrong LDAP Data
+
+The embedded server loads fresh data on each run. If you see stale data, you're likely connected to an external LDAP server. Check:
+
+```bash
+echo $DM_LDAP_URL
+# Should be empty or ldap://localhost:<high-port>
+```
+
+## Migration Guide
+
+### Existing Tests
+
+No changes needed! Tests using `skipIfMissingEnvVars()` will now always pass:
+
+```typescript
+// Before: Would skip if no external LDAP
+import { skipIfMissingEnvVars, LDAP_ENV_VARS } from '../../helpers/env';
+
+describe('My test', () => {
+  before(function () {
+    skipIfMissingEnvVars(this, [...LDAP_ENV_VARS]); // Still works!
+  });
+});
+
+// Now: Runs with embedded LDAP automatically
+```
+
+### New Tests
+
+Simply write tests without any LDAP setup:
+
+```typescript
+import { DM } from '../../../src/bin';
+
+describe('New plugin', () => {
+  let server: DM;
+
+  before(async () => {
+    server = new DM(); // That's it!
+    await server.ready;
+  });
+
+  it('should work', () => {
+    // Your test here
+  });
+});
+```
+
+## Future Enhancements
+
+- [ ] Support for loading custom fixtures per test suite
+- [ ] B2B organization fixtures automatically loaded
+- [ ] LDAP server connection pooling across test files
+- [ ] Parallel test execution with multiple LDAP containers