Is it possible to create a custom fetch with the dispatcher option preset

[gr2m]

The fetch method supports a dispatcher option:
https://undici.nodejs.org/#/?id=undicifetchinput-init-promise

Is it possible to create a new fetch instance with the dispatcher option preset?

Background is that we are upgrading @octokit to use the native fetch method by default. We currently support an agent option which I now understand is incompatible with undici's fetch. Instead of replacing the agent option with a dispatcher option, I wonder if we can have folks create a custom fetch method and pass that as the fetch option we already support.

Alternatively we could ask users to use undici.setGlobalDispatcher(dispatcher), but I wonder if that will break some use cases, hence the question.

Related question: Is the setGlobalDispatcher method also exposed in Node.js or do I have to install the undici npm package for that? And if I use the setGlobalDispatcher method, will it have the desired impact on the global fetch method?

[mcollina]

Is it possible to create a new fetch instance with the dispatcher option preset?

I don't understand the question, what kind of API are you looking for?
fetch() is just a function, so no one stops you from doing:

function myFetch (url, opts) {
  opts ||= {}
  opts.dispatcher = new MyAgent()
  return fetch(url, opts)
}

Or are you looking for some kind of other utilities?

Background is that we are upgrading https://github.com/octokit to use the native fetch method by default. We currently support an agent option which I now understand is incompatible with undici's fetch. Instead of replacing the agent option with a dispatcher option, I wonder if we can have folks create a custom fetch method and pass that as the fetch option we already support.

I like this approach a lot.

Related question: Is the setGlobalDispatcher method also exposed in Node.js or do I have to install the undici npm package for that? And if I use the setGlobalDispatcher method, will it have the desired impact on the global fetch method?

Calling setGlobalDispatcher() will also affect Node.js. It's built that way on purpose, so we could modify fetch() and other things.

Note that the implementation is trivial and it relies on a global symbol, so we could easily add it to core: https://github.com/nodejs/undici/blob/main/lib/global.js.

[targos]

It's possible to change the global dispatcher in Node.js using:

globalThis[Symbol.for('undici.globalDispatcher.1')] = yourDispatcher;

This will affect global fetch.

[gr2m]

Thank you both for your swift help ❤️

I know that Node's fetch support is experimental, so I assume nothing can be considered stable yet. But once it becomes stable, can you tell if globalThis[Symbol.for('undici.globalDispatcher.1')] will be considered part of the public API?

[mcollina]

You can consider it part of the public API, we should probably document it.

[longzheng]

Good to know that the globalThis method is considered public API so it's safe to use.

In case anyone else was looking for a way to overriding the global dispatcher with a new agent with some custom config options, here's an example

    // there is no official Node API to get the global dispatcher (as of Node 20.11.1)
    // getting the dispatcher from global is considered a public API https://github.com/nodejs/undici/discussions/2167#discussioncomment-6265039
    // hard-coded symbol for the undici global dispatcher https://github.com/nodejs/undici/blob/main/lib/global.js#L5
    const unidiciGlobalDispatcherSymbol = Symbol.for('undici.globalDispatcher.1');
    const undiciGlobalDispatcher = global[unidiciGlobalDispatcherSymbol];

    if (!undiciGlobalDispatcher) {
        throw new Error('Could not find the global Undici dispatcher, maybe not in node runtime?');
    }

    // initialize a new agent/dispatcher https://undici.nodejs.org/#/docs/api/Agent
    // inspired by https://github.com/orgs/nodejs/discussions/51260#discussioncomment-7949240
    const newDispatcher = new undiciGlobalDispatcher.constructor({
        // limit the number of client (host) connections
        // https://undici.nodejs.org/#/docs/api/Pool
        connections: 128,
    });

    // override the Undici global dispatcher
    global[unidiciGlobalDispatcherSymbol] = newDispatcher;