A middleware that generates a unique Request ID for every incoming HTTP request in Koa.

# Using NPM
$ npm install --save @kasa/koa-request-id
# Using Yarn
$ yarn add @kasa/koa-request-id

• Koa 2.0+
• Node.js 8.0.0+

Use koa-request-id as a middleware for a koa app. By default, it generates a unique uuid (v4) and exposes it on the response via the X-Request-Id header. The id is also saved as part of the request state.

In the following example, the generated uuid is manually exposed on the body for debugging purposes:

const Koa = require('koa');
const requestId = require('@kasa/koa-request-id');
const app = new Koa();

app.use(requestId());
app.use(async ctx => {
  ctx.body = ctx.state.reqId;
});

app.listen(3000);

Execute a request to the running app:

❯ curl -v http://localhost:3000

< HTTP/1.1 200 OK
< X-Request-Id: a78598a4-6537-45eb-811c-fdc59602a54c

a78598a4-6537-45eb-811c-fdc59602a54c

Sometimes it is also useful to pass a custom id via a request header, specifically in tracking requests on the distributed system. Please note that the input id is not sanitized, so the usual precautions apply.

Using the above snippet to send a custom via the default X-Request-Id header:

❯ curl -v -H 'X-Request-Id: foobar' http://localhost:3000

< HTTP/1.1 200 OK
< X-Request-Id: foobar

foobar

You can create a new request id middleware by passing the relevant options to requestId;

// With default options
const middleware = requestId({
  query: null,
  header: 'X-Request-Id',
  exposeHeader: 'X-Request-Id',
  generator: require('uuid/v4')
});

These are the available config options for the middleware. All is optional. The middleware try to get the request id from X-Request-Id request header or generate a new request id using uuidv4 generator. Then, the request id will be set into ctx.state.reqId Koa context state object and X-Request-Id response header if any option is not specified.

{
  // Request query name to get the forwarded request id
  query: 'reqId',

  // Request header name to get the forwarded request id
  header: 'X-Transaction-Id',

  // Response header name
  exposeHeader: 'X-Transaction-Id',

  // Function to generate request id
  generator: () => Date.now().toString()
}

Please use the issue tracker to report any bugs or ask feature requests.

Provided under the terms of the MIT License.

Copyright © 2018-2019, Kasa.