https://github.com/kasa-network/koa-request-id

A middleware that adds a request id in Koa
https://github.com/kasa-network/koa-request-id

correlation-id koa koa-middleware koa2 koa2-middleware reqid request-id tracing

Last synced: 3 months ago
JSON representation

A middleware that adds a request id in Koa

• Host: GitHub
• URL: https://github.com/kasa-network/koa-request-id
• Owner: kasa-network
• License: mit
• Archived: true
• Created: 2018-10-29T05:51:53.000Z (about 6 years ago)
• Default Branch: master
• Last Pushed: 2019-03-09T15:47:52.000Z (almost 6 years ago)
• Last Synced: 2024-09-26T16:41:01.077Z (3 months ago)
• Topics: correlation-id, koa, koa-middleware, koa2, koa2-middleware, reqid, request-id, tracing
• Language: JavaScript
• Homepage:
• Size: 17.6 KB
• Stars: 5
• Watchers: 19
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

        


  
@kasa/koa-request-id





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





  

    

  

  

    

  

  

    

  

  

    

  

  

    

  

  

    

  






## Installation

```bash

# Using NPM

$ npm install --save @kasa/koa-request-id

# Using Yarn

$ yarn add @kasa/koa-request-id

```

### Dependencies

- [**Koa**](https://github.com/koajs/koa) 2.0+

- [**Node.js**](https://nodejs.org) 8.0.0+

## Usage

Use `koa-request-id` as a middleware for a [koa](https://github.com/koajs/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:

```js

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:

```bash

❯ 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:

```bash

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

< HTTP/1.1 200 OK

< X-Request-Id: foobar

foobar

```

## API

### Creating an middleware

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

```node

// With default options

const middleware = requestId({

  query: null,

  header: 'X-Request-Id',

  exposeHeader: 'X-Request-Id',

  generator: require('uuid/v4')

});

```

### Middleware Configuration

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.

```node

{

  // 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()

}

```

## Contributing

#### Bug Reports & Feature Requests

Please use the [issue tracker](https://github.com/kasa-network/koa-request-id/issues) to report any bugs or ask feature requests.

## License

Provided under the terms of the [MIT License](https://github.com/kasa-network/koa-request-id/blob/master/LICENSE).

Copyright © 2018-2019, [Kasa](http://www.kasa.network).