https://github.com/zhujun24/http-request-context
Store context in http request's lifecycle.
https://github.com/zhujun24/http-request-context
context http http-context middleware nodejs request request-context scoped
Last synced: 6 days ago
JSON representation
Store context in http request's lifecycle.
- Host: GitHub
- URL: https://github.com/zhujun24/http-request-context
- Owner: zhujun24
- License: mit
- Created: 2019-08-23T11:18:27.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2020-04-23T08:32:26.000Z (almost 6 years ago)
- Last Synced: 2025-09-28T18:38:05.904Z (5 months ago)
- Topics: context, http, http-context, middleware, nodejs, request, request-context, scoped
- Language: JavaScript
- Homepage:
- Size: 38.1 KB
- Stars: 7
- Watchers: 1
- Forks: 4
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: History.md
- License: LICENSE
Awesome Lists containing this project
README
# HTTP Request Context
[](https://www.npmjs.com/package/http-request-context)
[](https://travis-ci.org/zhujun24/http-request-context)
[](https://coveralls.io/github/zhujun24/http-request-context?branch=master)
[](https://snyk.io//test/github/zhujun24/http-request-context?targetFile=package.json)
[](https://app.fossa.com/projects/git%2Bgithub.com%2Fzhujun24%2Fhttp-request-context?ref=badge_shield)
[](https://www.npmjs.com/package/http-request-context)
[](https://www.npmjs.com/package/http-request-context)
[](https://www.npmjs.com/package/http-request-context)
[](https://www.npmjs.com/package/http-request-context)
[](https://www.npmjs.com/package/http-request-context)
Set and Get request-scoped context anywhere.
## Requirement
### Nodejs version >= 8.2.0
This module uses the newer [async_hooks](https://nodejs.org/api/async_hooks.html#async_hooks_async_hooks) API which is considered `Experimental` by Nodejs.
## Options
| Option | Description | Type | Default |
|:------------|:------------|:------------|:------------|
| interval | remove expired callstack interval(s) | Number | 10
| expire | callstack expire time(s)| Number | 150
| removeAfterFinish | remove callstack after [http.ServerResponse](https://nodejs.org/api/http.html#http_class_http_serverresponse) [finish](https://nodejs.org/api/http.html#http_event_finish) | Boolean | false
| removeAfterClose | remove callstack after [http.ServerResponse](https://nodejs.org/api/http.html#http_class_http_serverresponse) [close](https://nodejs.org/api/http.html#http_event_close_1) | Boolean | false
#### options.interval
Remove expired callstack interval, used like `setInterval(removeExpiredCallstack, interval)`.
#### options.expire
Callstack expire time, must be longer than full lifecycle of a request.
#### options.removeAfterFinish
It will actively remove the relevant callstack after [http.ServerResponse](https://nodejs.org/api/http.html#http_class_http_serverresponse) [finish](https://nodejs.org/api/http.html#http_event_finish).
If set to `true`, you can get the context synchronously in the finish event, but not asynchronous. The benefit is that it can improve the performance of this middleware.
#### options.removeAfterClose
This is very similar to `options.removeAfterFinish`, the difference is that after the close event.
Please Note! if set to `true`, in some cases, the close event may be caused by the client terminating the request, after the close event, we may still use the context after the incomplete asynchronous operation is completed, this will result in loss of context.
## Init Middleware
**This module is recommend as a "top-level" middleware for ensure all context can be tracked**
- `httpRequestContext.middleware(options)` Init Express middleware.
- `httpRequestContext.koaMiddleware(options)` Init Koa middleware.
## Set Context
- `httpRequestContext.set(key, value)` Set context anywhere.
- `httpRequestContext.set({ key: value })` This is also OK.
## Get Context
- `httpRequestContext.get(key)` Get the `[key]` attribute of the context.
- `httpRequestContext.get()` Gets an object containing all context properties.
## How to Use
see [example](https://github.com/zhujun24/http-request-context/tree/master/example) here.
### Install
```npm
npm install http-request-context --save
```
### Express
#### Init
```js
import httpRequestContext from 'http-request-context'
app.use(httpRequestContext.middleware())
```
#### Set Context
```js
import httpRequestContext from 'http-request-context'
// set context by key-value
app.use((req, res, next) => {
setTimeout(() => {
httpRequestContext.set('foo', 'bar')
next()
}, 100)
})
```
#### Get Context
```js
import httpRequestContext from 'http-request-context'
httpRequestContext.get('foo') // 'bar'
```
### Koa
#### Init
```js
import httpRequestContext from 'http-request-context'
app.use(httpRequestContext.koaMiddleware())
```
#### Set Context
```js
import httpRequestContext from 'http-request-context'
// set context by key-value
app.use(async (ctx, next) => {
await new Promise(resolve => {
setTimeout(() => {
httpRequestContext.set('user', 'user')
resolve()
}, 300)
})
await next()
})
```
##### Get Context
```js
import httpRequestContext from 'http-request-context'
httpRequestContext.get('foo') // 'bar'
```
## Lost Context Tips
#### http.ServerResponse close event
Sometimes, when client terminate request by close window or reload page, it will cause http.ServerResponse emit 'close' event, this event is trigger by root, so it break away from current request scope, in this case, we can add `res`(express) or `ctx.res`(koa) parameter to get context function to ensure context can be tracked, as follows:
```js
// Express
res.on('close', () => {
console.log('close', httpRequestContext.get('foo', res))
})
// Koa
ctx.res.on('close', () => {
console.log('close', httpRequestContext.get('foo', ctx.res))
})
```
#### MySQL
If you init mysql connect before http server start, you may get context undefined in mysql query callback scope.
[googleapis/cloud-trace-nodejs #946](https://github.com/googleapis/cloud-trace-nodejs/issues/946)
[nodejs/node #22360](https://github.com/nodejs/node/issues/22360)
```js
mysqlConnection.query('SELECT * FROM table', (error, results, fields) => {
httpRequestContext.get('foo') // undefined
})
```
You can use util.promisify to avoid it.
```js
util.promisify(mysqlConnection.query).bind(mysqlConnection)('SELECT * FROM table')
.then((results, fields) => {
httpRequestContext.get('foo') // 'bar'
})
.catch(error => {})
```