⚠️ LoopBack 3 is in Maintenance LTS mode, only critical bugs and critical security fixes will be provided. (See Module Long Term Support Policy below.)
We urge all LoopBack 3 users to migrate their applications to LoopBack 4 as soon as possible. Refer to our Migration Guide for more information on how to upgrade.
Current context for LoopBack applications, based on cls-hooked.
This module is in Active LTS mode, new features are no longer accepted. (See Module Long Term Support Policy below.) LoopBack 3 users looking for new features are encouraged to upgrade to LoopBack 4. Refer to loopback-next#1849 for more information on how to upgrade.
cls-hooked
module uses undocumented AsyncWrap
API that was introduced to Node.js relatively recently. While this new API seems to be more reliable than the old async-listener
used by continuation-local-storage
, there are still cases where the context (local storage) is not preserved correctly. Please consider this risk before using loopback-context.
when, a popular Promise
implementation, breaks context propagation. Please consider using the
built-in Promise
implementation provided by Node.js or
Bluebird instead.
Express middleware chains which contain a "bad" middleware (i.e. one which breaks context propagation inside its function body, in a way mentioned in this doc) especially if called before other "good" ones needs refactoring, in order to prevent the context from getting mixed up among HTTP requests. See usage below for details.
Discussion: https://github.com/strongloop/loopback-context/issues/17
In general, any module that implements a custom task queue or a connection pool is prone to break context storage. This is an inherent problem of continuation local storage that needs to be fixed at lower level - first in Node.js core and then in modules implementing task queues and connection pools.
$ npm install --save loopback-context cls-hooked
Make sure you are running on a Node.js version supported by this module
(^4.5
, ^5.10
, ^6.0
, ^7.0
, ^8.2.1
or ^10.14
). When installing, check the output of npm install
and make sure there are no engine
related warnings.
To minimize the likelihood of loosing context in your application, you should
ensure that cls-hooked
is loaded as the first module of your application, so
that it can wrap certain Node.js APIs before any other modules start using these
APIs.
Our recommended approach is to add -r cls-hooked
to node's list of
arguments when starting your LoopBack application.
$ node -r cls-hooked .
If you are using a process manager like strong-pm
or pm2
, then consult
their documentation whether it's possible to configure the arguments used to
spawn worker processes. Note that slc run
does not support this feature yet,
see strong-supervisor#56.
Alternatively, you can add the following line as the first line of your main application file:
require('cls-hooked');
This approach should be compatible with all process managers, including
strong-pm
. However, we feel that relying on the order of require
st