@villedemontreal/correlation-id 5.3.2

package/src/middleware/correlationIdMiddleware.test.ts

@@ -0,0 +1,335 @@
+import { assert } from 'chai';
+import * as express from 'express';
+import httpHeaderFieldsTyped from 'http-header-fields-typed';
+import * as request from 'supertest';
+import { correlationIdService } from '../services/correlationIdService';
+import { setTestingConfigurations } from '../utils/testingConfigurations';
+import { createCorrelationIdMiddleware } from './correlationIdMiddleware';
+
+function delay(millis: number): Promise<void> {
+  return new Promise<void>(resolve =>
+    setTimeout(() => {
+      resolve();
+    }, millis)
+  );
+}
+
+// ==========================================
+// Set Testing configurations
+// ==========================================
+setTestingConfigurations();
+
+const uuidMatcher: RegExp = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+// ==========================================
+// Correlation ID service
+// ==========================================
+// tslint:disable-next-line: max-func-body-length
+describe('Correlation ID Middleware', () => {
+  it('should generate correlation id if it doesnt exists', async () => {
+    const app: express.Application = express();
+    app.use(createCorrelationIdMiddleware());
+    app.get('/', (req, res) => {
+      const actual = correlationIdService.getId();
+      assert.match(actual, uuidMatcher);
+      res.end();
+    });
+
+    await request(app)
+      .get('/')
+      .send();
+  });
+
+  it('should get correlation id from incoming request', async () => {
+    const testId: string = 'correlation-id-123';
+
+    const app: express.Application = express();
+    app.use(createCorrelationIdMiddleware());
+    app.get('/', (req, res) => {
+      const actual = correlationIdService.getId();
+      assert.strictEqual(actual, testId, 'getId() should return id from x-correlation-id header of inbound request');
+      res.end();
+    });
+
+    await request(app)
+      .get('/')
+      .set(httpHeaderFieldsTyped.X_CORRELATION_ID, testId)
+      .send();
+  });
+
+  it('should maintain correlation id with async callbacks', async () => {
+    const testId: string = 'correlation-id-123';
+
+    let actual = '';
+    let actual2 = '';
+    const app: express.Application = express();
+    app.use(createCorrelationIdMiddleware());
+    app.get('/', async (req, res, next) => {
+      actual = correlationIdService.getId();
+      setTimeout(() => {
+        actual2 = correlationIdService.getId();
+        res.end();
+      }, 250);
+    });
+
+    assert.isUndefined(correlationIdService.getId());
+    await request(app)
+      .get('/')
+      .set(httpHeaderFieldsTyped.X_CORRELATION_ID, testId)
+      .send();
+
+    assert.isUndefined(correlationIdService.getId());
+    assert.strictEqual(actual, testId, 'getId() should return id from x-correlation-id header of inbound request');
+    assert.strictEqual(actual2, testId, 'getId() should return id from x-correlation-id header of inbound request');
+  });
+
+  it('should maintain correlation id with async/await operations', async () => {
+    const testId: string = 'correlation-id-123';
+
+    let actual = '';
+    let actual2 = '';
+    const app: express.Application = express();
+    app.use(createCorrelationIdMiddleware());
+    app.get('/', async (req, res, next) => {
+      try {
+        actual = correlationIdService.getId();
+        await delay(250);
+        actual2 = correlationIdService.getId();
+      } catch (e) {
+        next(e);
+      } finally {
+        res.end();
+      }
+    });
+
+    assert.isUndefined(correlationIdService.getId());
+    await request(app)
+      .get('/')
+      .set(httpHeaderFieldsTyped.X_CORRELATION_ID, testId)
+      .send();
+
+    assert.isUndefined(correlationIdService.getId());
+    assert.strictEqual(actual, testId, 'getId() should return id from x-correlation-id header of inbound request');
+    assert.strictEqual(actual2, testId, 'getId() should return id from x-correlation-id header of inbound request');
+  });
+
+  it('should keep correlation ids in nested requests', async () => {
+    const testId: string = 'correlation-id-123';
+    const testId2: string = 'correlation-id-456';
+
+    let actual = '';
+    let actual2 = '';
+    let actual3 = '';
+    let actual4 = '';
+    let actual5 = '';
+    const app: express.Application = express();
+    app.use(createCorrelationIdMiddleware());
+    app.get('/', async (req, res, next) => {
+      try {
+        actual = correlationIdService.getId();
+        await delay(250);
+        actual2 = correlationIdService.getId();
+        await request(app)
+          .get('/foo')
+          .set(httpHeaderFieldsTyped.X_CORRELATION_ID, testId2)
+          .send();
+        actual3 = correlationIdService.getId();
+      } catch (e) {
+        next(e);
+      } finally {
+        res.end();
+      }
+    });
+    app.get('/foo', async (req, res, next) => {
+      try {
+        actual4 = correlationIdService.getId();
+        await delay(250);
+        actual5 = correlationIdService.getId();
+      } catch (e) {
+        next(e);
+      } finally {
+        res.end();
+      }
+    });
+
+    assert.isUndefined(correlationIdService.getId());
+    await request(app)
+      .get('/')
+      .set(httpHeaderFieldsTyped.X_CORRELATION_ID, testId)
+      .send();
+
+    assert.isUndefined(correlationIdService.getId());
+    assert.strictEqual(actual, testId, 'getId() should return id from x-correlation-id header of inbound request');
+    assert.strictEqual(actual2, testId, 'getId() should return id from x-correlation-id header of inbound request');
+    assert.strictEqual(actual3, testId, 'getId() should return id from x-correlation-id header of inbound request');
+    assert.strictEqual(actual4, testId2, 'getId() should return id from x-correlation-id header of inbound request');
+    assert.strictEqual(actual5, testId2, 'getId() should return id from x-correlation-id header of inbound request');
+  });
+
+  // tslint:disable: no-console
+  it('should keep correlation ids separated in parallel requests', async function() {
+    this.timeout(5000);
+    const testId: string = 'correlation-id-123';
+    const testId2: string = 'correlation-id-456';
+
+    let actual = '';
+    let actual2 = '';
+    let actual4 = '';
+    let actual5 = '';
+    let unlock: any;
+    const lock = new Promise(async (resolve, reject) => {
+      unlock = resolve;
+    });
+    const app: express.Application = express();
+    app.use(createCorrelationIdMiddleware());
+    app.get('/', async (req, res, next) => {
+      try {
+        actual = correlationIdService.getId();
+        console.log('start of req1', actual);
+        await lock;
+        actual2 = correlationIdService.getId();
+        console.log('end of req1', actual2);
+      } catch (e) {
+        next(e);
+      } finally {
+        res.end();
+      }
+    });
+    app.get('/foo', async (req, res, next) => {
+      try {
+        actual4 = correlationIdService.getId();
+        console.log('start of req2', actual4);
+        unlock();
+        await this.timeout(200);
+        actual5 = correlationIdService.getId();
+        console.log('end of req2', actual5);
+      } catch (e) {
+        next(e);
+      } finally {
+        res.end();
+      }
+    });
+
+    console.log('send req1');
+    assert.isUndefined(correlationIdService.getId());
+    const req1 = request(app)
+      .get('/')
+      .set(httpHeaderFieldsTyped.X_CORRELATION_ID, testId)
+      .send();
+    console.log('send req2');
+    assert.isUndefined(correlationIdService.getId());
+    const req2 = request(app)
+      .get('/foo')
+      .set(httpHeaderFieldsTyped.X_CORRELATION_ID, testId2)
+      .send();
+    await Promise.all([req1, req2]);
+    assert.isUndefined(correlationIdService.getId());
+    assert.strictEqual(actual, testId, 'getId() should return id from x-correlation-id header of inbound request');
+    assert.strictEqual(actual2, testId, 'getId() should return id from x-correlation-id header of inbound request');
+    assert.strictEqual(actual4, testId2, 'getId() should return id from x-correlation-id header of inbound request');
+    assert.strictEqual(actual5, testId2, 'getId() should return id from x-correlation-id header of inbound request');
+  });
+
+  it('should work with operations causing errors', async () => {
+    const testId: string = 'correlation-id-123';
+
+    let actual = '';
+    const app: express.Application = express();
+    app.use(createCorrelationIdMiddleware());
+    app.get('/', (req, res, next) => {
+      actual = correlationIdService.getId();
+      throw new Error('some error');
+    });
+
+    assert.isUndefined(correlationIdService.getId());
+    const result = await request(app)
+      .get('/')
+      .set(httpHeaderFieldsTyped.X_CORRELATION_ID, testId)
+      .send();
+    assert.strictEqual(result.status, 500);
+    assert.isUndefined(correlationIdService.getId());
+    assert.strictEqual(actual, testId, 'getId() should return id from x-correlation-id header of inbound request');
+  });
+
+  it('a filter can be specified', async () => {
+    const testId: string = 'correlation-id-123';
+
+    const filter = (req: express.Request): boolean => {
+      if (req.path.startsWith('/ok/')) {
+        return true;
+      }
+      return false;
+    };
+
+    const app: express.Application = express();
+    app.use(createCorrelationIdMiddleware(filter));
+
+    app.get('/ok/1', (req, res) => {
+      const actual = correlationIdService.getId();
+      assert.strictEqual(actual, testId, 'getId() should return id from x-correlation-id header of inbound request');
+      res.end();
+    });
+    app.get('/ok/2', (req, res) => {
+      const actual = correlationIdService.getId();
+      assert.strictEqual(actual, testId, 'getId() should return id from x-correlation-id header of inbound request');
+      res.end();
+    });
+    app.get('/notok/1', (req, res) => {
+      const actual = correlationIdService.getId();
+      assert.isUndefined(actual);
+      res.end();
+    });
+
+    await request(app)
+      .get('/ok/1')
+      .set(httpHeaderFieldsTyped.X_CORRELATION_ID, testId)
+      .send();
+
+    await request(app)
+      .get('/ok/2')
+      .set(httpHeaderFieldsTyped.X_CORRELATION_ID, testId)
+      .send();
+
+    await request(app)
+      .get('/notok/1')
+      .set(httpHeaderFieldsTyped.X_CORRELATION_ID, testId)
+      .send();
+  });
+
+  it('getCidInfo() cid received', async () => {
+    const testId: string = 'correlation-id-123';
+
+    const app: express.Application = express();
+    app.use(createCorrelationIdMiddleware());
+    app.get('/', (req, res) => {
+      const info = correlationIdService.getCidInfo(req);
+      assert.strictEqual(info.current, testId);
+      assert.strictEqual(info.receivedInRequest, testId);
+      assert.isUndefined(info.generated);
+
+      res.end();
+    });
+
+    await request(app)
+      .get('/')
+      .set(httpHeaderFieldsTyped.X_CORRELATION_ID, testId)
+      .send();
+  });
+
+  it('getCidInfo() cid generated', async () => {
+    const app: express.Application = express();
+    app.use(createCorrelationIdMiddleware());
+    app.get('/', (req, res) => {
+      const info = correlationIdService.getCidInfo(req);
+      assert.match(info.current, uuidMatcher);
+      assert.strictEqual(info.current, info.generated);
+      assert.isUndefined(info.receivedInRequest);
+
+      res.end();
+    });
+
+    await request(app)
+      .get('/')
+      .send();
+  });
+});

package/src/middleware/correlationIdMiddleware.ts

@@ -0,0 +1,45 @@
+import * as express from 'express';
+import httpHeaderFieldsTyped from 'http-header-fields-typed';
+import { constants } from '../config/constants';
+import { correlationIdService } from '../services/correlationIdService';
+
+/**
+ * Correlation ID Middleware
+ *
+ * @param filter a filter which is going to be called with the request to see if a
+ * colleration id scope must be managed or not.
+ */
+export let createCorrelationIdMiddleware = (
+  filter?: (req: express.Request) => boolean
+): ((req: express.Request, res: express.Response, next: express.NextFunction) => Promise<void>) => {
+  const correlationIdMiddleware = (
+    req: express.Request,
+    res: express.Response,
+    next: express.NextFunction
+  ): Promise<void> => {
+    if (filter && !filter(req)) {
+      next();
+    } else {
+      // ==========================================
+      // If a Correlation ID (cid) exists in the request
+      // it will be used. Otherwise, a new one is created.
+      //
+      // We add the cid to the response!
+      // ==========================================
+      let correlationId = req.get(httpHeaderFieldsTyped.X_CORRELATION_ID);
+      if (!correlationId) {
+        correlationId = correlationIdService.createNewId();
+        req[constants.requestExtraVariables.cidNew] = correlationId;
+      } else {
+        req[constants.requestExtraVariables.cidReceivedInRequest] = correlationId;
+      }
+      if (!res.headersSent) {
+        res.set(httpHeaderFieldsTyped.X_CORRELATION_ID, correlationId);
+      }
+      correlationIdService.withId(next, correlationId);
+    }
+    return null;
+  };
+
+  return correlationIdMiddleware;
+};

package/src/services/correlationIdService.test.ts

@@ -0,0 +1,255 @@
+// tslint:disable max-func-body-length
+
+import { assert } from 'chai';
+import { EventEmitter } from 'events';
+import { setTestingConfigurations } from '../utils/testingConfigurations';
+import { correlationIdService } from './correlationIdService';
+
+setTestingConfigurations();
+
+const uuidMatcher: RegExp = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+async function timeout(work: (params?: any) => any, ms: number = 50) {
+  return new Promise<void>(resolve =>
+    setTimeout(() => {
+      work();
+      resolve();
+    }, ms)
+  );
+}
+
+describe('Correlation Id Service', () => {
+  describe('createNewId', () => {
+    it('should return UUID', () => {
+      const cid = correlationIdService.createNewId();
+      assert.match(cid, uuidMatcher);
+    });
+  });
+
+  describe('withId correlator', () => {
+    it('with sync function', () => {
+      // GIVEN
+      const expectedResult: string = '⭐';
+
+      // WHEN
+      const result = correlationIdService.withId(() => {
+        const actual = correlationIdService.getId();
+        assert.match(actual, uuidMatcher, 'getId() should return a uuid');
+        return expectedResult;
+      });
+
+      // THEN
+      assert.strictEqual(result, expectedResult);
+    });
+
+    it('with async function', async () => {
+      let done: boolean = false;
+
+      const promise = correlationIdService.withId(async () => {
+        await timeout(() => {
+          const actual = correlationIdService.getId();
+          assert.match(actual, uuidMatcher, 'getId() should return a uuid');
+          done = true;
+        });
+      });
+
+      // "withId" doesn't care about a promise to be floating or not
+      assert.isFalse(done);
+      await promise;
+    });
+
+    it('with supplied id', () => {
+      const testId = 'id-1';
+      correlationIdService.withId(() => {
+        const actual = correlationIdService.getId();
+        assert.strictEqual(actual, testId, 'getId() should return supplied id');
+      }, testId);
+    });
+
+    it('with bound emitter', () => {
+      // GIVEN
+      const emitter = new EventEmitter();
+      let receivedValue = 0;
+      let receivedCid = '';
+      emitter.on('test', value => {
+        receivedValue = value;
+        receivedCid = correlationIdService.getId();
+      });
+
+      // WHEN
+      let boundEmitter: EventEmitter;
+      correlationIdService.withId(() => {
+        boundEmitter = correlationIdService.bind(emitter);
+        assert.strictEqual(boundEmitter, emitter);
+      }, 'foo');
+
+      // THEN
+      boundEmitter.emit('test', 33);
+      assert.equal(receivedValue, 33);
+      assert.equal(receivedCid, 'foo');
+    });
+
+    it('with bound function', () => {
+      // GIVEN
+      const func = (msg: string) => msg + correlationIdService.getId();
+
+      // WHEN
+      let boundFunc: (msg: string) => string;
+      correlationIdService.withId(() => {
+        boundFunc = correlationIdService.bind(func);
+      }, 'foo');
+
+      // THEN
+      const result = boundFunc('Bar-');
+      assert.equal(result, 'Bar-foo');
+    });
+
+    it('with bound method', () => {
+      // GIVEN
+      const instance = {
+        title: 'Hello-',
+        say(msg: string): string {
+          return this.title + msg + correlationIdService.getId();
+        }
+      };
+
+      // WHEN
+      correlationIdService.withId(() => {
+        instance.say = correlationIdService.bind(instance.say);
+      }, 'foo');
+
+      // THEN
+      const result = instance.say('Bar-');
+      assert.equal(result, 'Hello-Bar-foo');
+    });
+
+    it('with resolved promise', async () => {
+      let done: boolean = false;
+
+      const promise = correlationIdService.withId(() =>
+        Promise.resolve(correlationIdService.getId()).then(id => {
+          assert.match(id, uuidMatcher, 'Promise should resolve correlation id');
+          done = true;
+        })
+      );
+
+      // "withId" doesn't care about a promise to be floating or not
+      assert.isFalse(done);
+      await promise;
+    });
+
+    it('with nested functions', () => {
+      correlationIdService.withId(() => {
+        const cid1 = correlationIdService.getId();
+        assert.match(cid1, uuidMatcher, 'correlationIdService.getId() should return a UUID');
+
+        correlationIdService.withId(() => {
+          const cid2 = correlationIdService.getId();
+          assert.notEqual(cid2, cid1, 'correlationIdService.getId() should return a different id for every scope');
+          assert.match(cid2, uuidMatcher, 'correlationIdService.getId() should return a UUID');
+        });
+
+        const cid3 = correlationIdService.getId();
+        assert.strictEqual(cid3, cid1, 'correlationIdService.getId() should return the same id for the same scope');
+        assert.match(cid3, uuidMatcher, 'correlationIdService.getId() should return a UUID');
+      });
+    });
+
+    it('with async function', async function() {
+      const duration = 25;
+      setSlowThreshold(this, duration);
+
+      // GIVEN
+      const expectedResult: string = '⭐';
+
+      // WHEN
+      const result = await correlationIdService.withId(async () => {
+        assert.equal(correlationIdService.getId(), 'foo');
+        await timeout(() => {
+          assert.equal(correlationIdService.getId(), 'foo');
+        }, duration);
+        assert.equal(correlationIdService.getId(), 'foo');
+        return expectedResult;
+      }, 'foo');
+
+      // THEN
+      assert.strictEqual(result, expectedResult);
+    });
+  });
+
+  describe('withIdAsync correlator', () => {
+    it('with async function', async function() {
+      const duration = 25;
+      setSlowThreshold(this, duration);
+
+      // GIVEN
+      const expectedResult: string = '⭐';
+
+      // WHEN
+      const result = await correlationIdService.withIdAsync(async () => {
+        assert.equal(correlationIdService.getId(), 'foo');
+        await timeout(() => {
+          assert.equal(correlationIdService.getId(), 'foo');
+        }, duration);
+        assert.equal(correlationIdService.getId(), 'foo');
+        return expectedResult;
+      }, 'foo');
+
+      // THEN
+      assert.strictEqual(result, expectedResult);
+    });
+
+    it('with error in callback', async () => {
+      try {
+        await correlationIdService.withIdAsync(async () => {
+          assert.equal(correlationIdService.getId(), 'foo');
+          throw new Error('some error...');
+        }, 'foo');
+        assert.fail('expected error');
+      } catch (err) {
+        assert.equal(err.message, 'some error...');
+      }
+    });
+
+    it('with error after await', async function() {
+      const duration = 25;
+      setSlowThreshold(this, duration);
+
+      try {
+        await correlationIdService.withIdAsync(async () => {
+          assert.equal(correlationIdService.getId(), 'foo');
+          // tslint:disable-next-line: no-empty
+          await timeout(() => {}, duration);
+          throw new Error('some error...');
+        }, 'foo');
+        assert.fail('expected error');
+      } catch (err) {
+        assert.equal(err.message, 'some error...');
+      }
+    });
+
+    it('with nested async functions', async function() {
+      const duration = 25;
+      setSlowThreshold(this, 2 * duration);
+
+      await correlationIdService.withIdAsync(async () => {
+        assert.equal(correlationIdService.getId(), 'foo');
+        await timeout(async () => {
+          await correlationIdService.withIdAsync(async () => {
+            await timeout(() => {
+              assert.equal(correlationIdService.getId(), 'bar');
+            }, duration);
+          }, 'bar');
+        }, duration);
+        assert.equal(correlationIdService.getId(), 'foo');
+      }, 'foo');
+    });
+  });
+
+  function setSlowThreshold(context: Mocha.Context, expectedTestDuration: number) {
+    // Cf. https://mochajs.org/#test-duration
+    // 10: budgeted test case own processing time
+    // ×2: for the estimation to sit around "slow/2" in Mocha scale (and no warning shows up)
+    context.slow((expectedTestDuration + 10) * 2);
+  }
+});