Change of behaviour regarding execution of micro tasks since Node.js 26.4.0, maybe related to `mocha`, maybe related to NAN native modules

Start with the supplied Mocha test and compare behavior between Node.js 26.3.0, 26.4.0, 26.9.0, and the latest checkout, including the Debug assertion failure. Read the NAN worker callback and .mocharc.json setup described in the report, then trace the microtask and nextTick execution path. Done means reproducing the race reliably, identifying the responsible Node.js behavior, and adding a regression test that passes without the manual checkpoint workaround.

Version

v26.9.0

Platform

Happens on all tested platforms: Linux, Windows and macOS.

Subsystem

No response

What steps will reproduce the bug?

The bug is difficult to reproduce. It appears to be a race condition. The best I have is a mocha test that reproduces it 9 out of 10 times on all platforms. At the moment I haven't been able to reproduce it without a NAN native module and mocha, but it does not appear to be a NAN problem.

The problem can happen with https://github.com/mmomtchev/node-gdal-async, latest git version, built with node-pre-gyp.

This mocha test does it:

const gdal = require('..')
const { assert } = require('chai')
const process = require('node:process')

describe('test', () => {
  it('srsAsync', (done) => {
    const ds = gdal.open(`${__dirname}/data/dem_azimuth50_pa.img`)
    ds.srsAsync.then((srs) => {
      assert.isTrue(srs.toWKT().indexOf('PROJCS["WGS_1984_Albers"') > -1)
      done()
    }).catch((err) => done(err))
  })
})

The srsAsync getter simply resolves a raw v8 Promise using a class that inherits from the async worker in NAN. It does not call makeCallback or JavaScript at all:

template <class GDALType> void GDALPromiseWorker<GDALType>::HandleOKCallback() {
  Nan::HandleScope scope;
  auto context = Nan::GetCurrentContext();
  v8::Local<v8::Promise::Resolver> resolver = Nan::New(*resolver_handle);
  resolver->Resolve(context, this->ProduceRVal()).FromJust();
}

Adding a manual execution of the micro tasks queue with performCheckPoint:

Nan::GetCurrentContext()->GetMicrotaskQueue()->PerformCheckpoint(isolate);

in the HandleOKCallback solves the problem, however to the best of my knowledge, a native module is not supposed to do this and there are other more complex cases that are not covered by this workaround.

How often does it reproduce? Is there a required condition?

.mocharc.json has to include tsx - however this is only the trigger and the test file can very well be JavaScript.

What is the expected behavior? Why is that the expected behavior?

After returning from the native module, the micro tasks queue is run.

What do you see instead?

After returning from the native module, the micro tasks queue is not run, leading to Node.js being blocked on the event loop with pending Promise handlers and/or process.nextTick callbacks.

Additional information

The change appeared between Node.js 26.3.0 and Node.js 26.4.0 but the precise modification might be simply a trigger for the race condition.

It does also happen with the latest git checkout.

What is remarkable is that the latest git checkout built in Debug mode crashes with a failed assert while running the micro tasks queue on the same mocha test. I do not know if this is related.

Also simply adding

setInterval(() => console.log('.'), 10)

to any affected program solves the problem completely since the micro tasks are regularly run. If the timer runs every 5s, then you get 5s timeouts when this happens.