Ability for async functions to retreive their CLS context

[gireeshpunathil]

Is your feature request related to a problem? Please describe.
Please describe the problem you are trying to solve.

Right now, the AsyncLocalStorage object needs to be externally available for the async functions to avail the store.

Describe the solution you'd like
Please describe the desired behavior.

Implement a getContextCLS API that returns the AsyncLocalStorage object under which this asynchronous call was initiated. Return undefined, if it was not run under AsyncLocalStorage semantics.

Illustration:

const { AsyncLocalStorage } = require('async_hooks');

function main() {
  const cls1 = new AsyncLocalStorage();
  const cls2 = new AsyncLocalStorage();
  cls1.run(() => {
    const store = cls1.getStore()
    store.set('x', 'y')
    setTimeout(foo, 1000)
  })
  
  cls2.run(() => {
    const store = cls2.getStore()
    store.set('x', 'z')
    setTimeout(foo, 1000)
  })
}


function foo() {
  // obtain the cls object here that this async call was part of
  // for example:
  // const cls = getContextCLS()
  //  const store = cls.getStore()
  //  console.log(store.get('x')
  // prints 'y' and 'z' as and when those are called.
}

main()

Use case: in a concurrent workload scenario, it is not easy to maintain AsyncLocalStorage objects globally, and across multiple async function families.

Describe alternatives you've considered
Please describe alternative solutions or features you have considered.

Alternative is to share these objects globally (which is not very attractive)

[gireeshpunathil]

/cc @vdeturckheim

[addaleax]

My understanding is that there is no particular AsyncLocalStorage instance associated with any async call, so I’m not sure what getContextCLS() would actually return?

Alternative is to share these objects globally (which is not very attractive)

Why not? I think that’s the thing that conceptually makes the most sense here.

[vdeturckheim]

We did not want to make the AsyncLocalStorages globally availabed by default to let users hide their instance and prevent anyone from tempering with it.

As there might be multiple AsyncLocalStorage running on the same code, a method like getContextCLS() would return an array:

const { AsyncLocalStorage } = require('async_hooks');

const asl1 = new AsyncLocalStorage();
const asl2 = new AsyncLocalStorage();

asl1.run(new Map(), () => {
  asl2.run(new Map(), () => {
    AsyncLocalStorage.getActive(); // returns [asl1, asl2];
  });
});

I don't have strong opinions here appart that I'd like to leave the owner of an AsyncLocalStorage the ability to keep it private.

[gireeshpunathil]

@addaleax - the problem with the global approach is that we need to explicitly maintain the association of AsyncLocalStorage (let us call it ALS) with an async function. For example, in the code in the first comment, foo will be called from both the contexts, in arbitrary order. So even if we make cls1 and cls2 global, how do one decide which ALS to use (to access the store etc.)?

[addaleax]

@gireeshpunathil I think there might be a misunderstanding about how ALS works. In particular, AsyncLocalStorage instances are not async contexts.

So even if we make cls1 and cls2 global, how do one decide which ALS to use (to access the store etc.)?

I don’t quite understand this question… can you maybe give a more concrete use case as an example?

[gireeshpunathil]

sure:

• 10 clients connect to a server
• those clients share a common non-closure handler function that receive the server data
• each client is created within an ALS.run context, so all the callbacks emanating from that context are grouped under one ALS object.
• within the handler, I want to accumulate server data into their respective stores.
• at the end of each response, retrieve the data from the store, and process

Is it possible to achieve this using ALS APIs?

[ edit: couple of typos]

[vdeturckheim]

@gireeshpunathil in that case you would use one single ASL:

const asl = new AsyncLocalStorage();
server.on('request', (req, res) => {
    asl.run({ req, res}, () => {
       // all calls to asl.getStore() wil return {req, res}
    });
});

Would that make sense in your example?

[gireeshpunathil]

@vdeturckheim - here is a complete example that exemplifies my use case, but using your suggestion of using a single ALS:

const { AsyncLocalStorage } = require('async_hooks')
const http = require('http')
const cls = new AsyncLocalStorage()
let store
let index = 0

const server = http.createServer((q, r) => {
  r.end((index++).toString().repeat(1024 * 1024 * 10))
})

server.listen(12000, () => {
  cls.run(new Map(), () => {
    for(let i = 0; i < 10; i++) {
      const req = http.get('http://localhost:12000', (res) => {
        const data = ''
        store = cls.getStore()
        store.set('data', data)
        res.on('data', ondata)
        res.on('end', onend)
      })
      req.end()
    }
  })
})

function ondata(d) {
  // keep store globally due to a bug, ref: https://github.com/nodejs/node/issues/32060
  // const store = cls.getStore()
  if (store && store.has('data')) {
    let chunk = store.get('data')
    chunk += d
    store.set('data', chunk)
  } else {
    console.log('error...')
  }
}

function onend() {
  // let store = cls.getStore()
  if (store && store.has('data')) {
  let chunk = store.get('data')
   var re = new RegExp(chunk[0], 'g')
    console.log(`stream type: ${chunk[0]}`)
    console.log(`stream length: ${chunk.replace(re, '').length}`)
  } else {
    console.log('ended, but in error...')
  }
}

the test does these:

• sets up a server, that sends large buffers of data, filled with cardinal numbers, increasing per request
• sets up a single ALS object, and runs 10 clients inside
• sets up an empty store
• in the data callbacks, accumulate the instantaneous data with the store data
• in the end callbacks, retrieve the store data, and make sure they are homogeneous

the output shows they are not, instead the data is all clobbered between various responses

stream type: 9
stream length: 73947963
stream type: 9
stream length: 73948064
stream type: 9
stream length: 73948165
stream type: 9
stream length: 73948266
stream type: 9
stream length: 73948367
stream type: 9
stream length: 73948468
stream type: 9
stream length: 73948569
stream type: 9
stream length: 73948670
stream type: 9
stream length: 75498381
stream type: 9
stream length: 75498381

expected output:

stream type: 0
stream length: 0
stream type: 1
stream length: 0
stream type: 2
stream length: 0
stream type: 3
stream length: 0
stream type: 4
stream length: 0
stream type: 5
stream length: 0
stream type: 6
stream length: 0
stream type: 7
stream length: 0
stream type: 8
stream length: 0
stream type: 9
stream length: 0

[addaleax]

@gireeshpunathil

  cls.run(new Map(), () => {
    for(let i = 0; i < 10; i++) {

should be

  for(let i = 0; i < 10; i++) {
    cls.run(new Map(), () => {

otherwise all the requests share a single store.

[gireeshpunathil]

ok, I can test this with #32063 only, because with this change, we will have 10 stores, and with the getStore bug, I will have to manage them separately. Will test and get back, thanks!

[gireeshpunathil]

@addaleax - with the patch of your PR, and with your suggested patch, the code is working as expected, thanks!

so a single instance of AsyncLocalStorage is capable of handling multiple callback chains (families, groups, etc. whatever we call those), through giving access to the appropriate store when invoked within the asynchronous routines! then why we would multiple instances of AsyncLocalStorage in the first place (why the new operator) ?

that is what confused me.

However, with a single object able to anchor all the stores in an application, keeping it global makes sense to me, and that addresses my use case as well. Not sure if there are other scenarios where this is not the case. Keeping it open for a couple of days to see if any.

thanks once again!

[addaleax]

then why we would multiple instances of AsyncLocalStorage in the first place (why the new operator) ?

Because different AsyncLocalStorage instances can be used for different purposes or even from different npm modules, which should not conflict with each other. And in particular, the scopes that they use might not match; for example, in

cls1.run(new Map(), () => {
  cls2.run(new Map(), () => {
    x()
  });
  cls2.run(new Map(), () => {
    y()
  });
});

You’ll see x() and y() sharing a store as far as cls1 is concerned but having different stores as far as cls2 is concerned.

(But I mostly think it’s the fact that we don’t want ALS from different modules to conflict.)