loopback-context

⚠️ 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.

Overview

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.

WARNING

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.

Known issues

  • 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.

Installation

$ 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.

Usage

Setup cls-hooked

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