Expose Undici's ProxyAgent and setGlobalDispatcher within Node

[pimterry]

Originally posted by @pimterry in #42814 (comment)

As a motivating example: I'd love to automatically support global Fetch in https://www.npmjs.com/package/global-agent (drop-in lib to make all Node HTTP use the system proxy) but even though Node bundles Undici AFAICT this isn't possible without adding a full separate Undici dep to that lib, which would more than double its size, just [EDIT: largely] to ship code that's already present in Node itself.

This would be immediately solved if ProxyAgent and setGlobalDispatcher were exposed explicitly somewhere in future.

I've just done a quick test on main in Undici: exposing ProxyAgent & setGlobalDispatcher explicitly increases the Undici bundle size from 334.2kb to 336.0kb (+1.8kb / +0.5%).

Could these APIs be included and exposed in future? Agents for HTTP are a very core API that it would be useful to have usable out of the box, the equivalent functionality is usable OOTB for the legacy http module APIs, and 2kb is not a significant jump in bundle size for this functionality.

[targos]

setGlobalDispatcher is exposed:

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

[pimterry]

Replying to the last comment from @mcollina in the previous issue:

I would recommend opening up a separate issue about this topic and bringing it to the TSC. I don't think the whole of Undici has the stability guarantees needed to be part of the Node.js LTS cycle yet.

This makes sense! I'm not aware of Undici's process around stability guarantees like this, but I can understand how there are constraints there.

I do understand this isn't a top top priority since installing & importing Undici elsewhere is a usable workaround, so there's certainly no rush just would justify shipping an unstable API unnecessarily. I do think that the current situation isn't a good end state though, and there are good options we can aim for to fix this, so it would be great to find agreement to aim in that direction in the medium term.

I'm not sure how to take anything to the TSC, but very happy to be included on any discussion of this any time.

[pimterry]

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

That's does work as a workaround, but it's not especially nice as the official API for this, and I think ProxyAgent needs to be available too to make this usable for global Fetch.

[mcollina]

I don't think we should expose undici further until we want to consider fetch as stable.

[sosoba]

@mcollina
I don't think we should expose undici further until we want to consider fetch as stable.

2022-11-14, Version 19.1.0

• drop fetch experimental warning (Matteo Collina) lib: drop fetch experimental warning #45287

[mcollina]

That does not mark it stable, on purpose. It's the first step on that journey. This is something we might want to consider right now.

[mcollina]

In the TSC meeeting of today, we decided that we are going to support HTTP_PROXY, HTTPS_PROXY and NO_PROXY env variables directly in Undici: nodejs/undici#1650.

[GabenGar]

How is it going to handle different casing rules?

[gp-jameskyburz]

so, there is no way to set a dispatcher on a per-call basis yet?

The easiest way is to pass { dispatcher: x } on each undici call, otherwise there is a factory method if using a global dispatcher.

Below accesses the internals of undici to get Agent, the factory method uses either Pool, or Client.

/**
 * Use the undici internals shipped with Node.js
 */
function getUndiciInternals() {
  /* We need to call fetch for the globalDispatcher to be available */
  fetch().catch(() => {})
  const globalDispatcherSymbol = Symbol.for('undici.globalDispatcher.1')
  const agent = globalThis[globalDispatcherSymbol]
  /* get access to the factory to avoid needing to reference Pool, and Client */
  const agentFactorySymbol = Object.getOwnPropertySymbols(agent).find((x) => x.toString() === 'Symbol(factory)')
  const agentFactory = agent[agentFactorySymbol]
  const Agent = agent.constructor

  return {
    globalDispatcherSymbol,
    Agent,
    agentFactory,
  }
}

class MyDispatcher extends undici.Agent {
  constructor(options) {
    super({
      ...options,
      factory(url, options_) {
        // can pass other options here too :)
        return undici.agentFactory(url, options_)
      },
    })
  }
}
globalThis[undici.globalDispatcherSymbol] = new MyDispatcher()

[mcollina]

@nodejs/tsc I think we need to make a decision here. Do we want to expose the bundled undici or not? Even if not, we should at least provide some API to get the undici Agent because people are doing all kind of hacks to get it.

[nikelborm]

Press 👍🏻 if you think Undici should be exposed and 👎🏻 if not

[ert78gb]

we should at least provide some API to get the undici Agent because people are doing all kind of hacks to get it.

Developers try to find a solution to their problem. We can call it hack.

This is why I suggested to expose the whole undici ~1 year ago.

[hansott]

Would be nice to expose using node:undici (so that global fetch is the same as import { fetch } from 'node:undici')

[JamesKyburz]

Would be nice to expose using node:undici (so that global fetch is the same as import { fetch } from 'node:undici')

I like the idea of exporting node:undici fetch would be optional as it's already a global, just like it's optional to import process from node:process. The main benefit for me is not having to ship undici for AWS Lambda if all we want is to have a custom dispatcher.

[avivkeller]

9/4 Meeting

• Expose Undici's ProxyAgent and setGlobalDispatcher within Node #43187
  • Two parts
    • For Node.js 23 do we want automatic support for HTTP_PROXY?, most frequent reason to
      have access to undici from Node.js versus installing undici
    • Problems exposing undici, cannot provide same stability guarantees
    • Michael, can we expose HTTP_PROXY without exposing undici
    • Marco, should we create a new namespace for undici
    • Paolo, in favor as well, yes lets create a new namespace
      • if we expose undici, then it would be experimental and we can break whenever. That would
        be an approach.
    • Marco, if requires new namespace, but at some point it would need to be as stable as the
      other APIs
    • Matteo, exposing has a lot of issues, keeping outside of core enabled a lot of
      experimentation and speed. Barrier to entry is lower. But also less stable, some back and
      forth
    • Paolo, already have similar situation with llhttp, 3 release lines, if we choose to expose
      undici can start to follow same approach. We would then have to start maintaining 3 different
      versions of undici.
    • Michael we are always in angst over thing that break, even if experimental so not really as
      easy as we break at will, better to wait until rate of change drops
    • Richard, llhttp is not quite the same as undici because we don’t expose it directly to users,
      ie we can swap (and did swap) the implementation behind the scenes.
    • Matteo has 3 parts
      • the part we bundle in Node.js which is the Web standard part
      • the part which is the public Undici API, quite large, has lots of agents, complex to address
        lots of use cases. For example dispatchers, but they expose some very low level API.
      • Generic question is people want to expose global dispatcher and access to dispatcher,
        those have been relatively stable in API, minus the fact that we just changed the expose API.

9/11 Meeting

• Expose Undici's ProxyAgent and setGlobalDispatcher within Node #43187
• We discussed last time, there was openness to including more of Undici but not all, remove
  from agenda for now.

[mbrevda]

there was openness to including more of Undici but not all

Any more background on this?

[Fonger]

What about exposing normal Agent from undici too? I just need custom DNS lookup function and I shouldn't use ProxyAgent.

[timtucker-dte]

We wound up going down the path of including undici directly for most of what we're doing (using request and overriding the global dispatcher to use a custom lookup function)

With Node 22 including the web socket implementation, we went ahead and preemptively switched to that on Node 20 as well.

Having to include it manually isn't that big of a deal as long as it plays nicely together (i.e.: not needing to set 2 "global" dispatchers to cover anything that feeds through the native fetch).

[JakobJingleheimer]

9/11 Meeting

Expose Undici's ProxyAgent and setGlobalDispatcher within Node #43187
We discussed last time, there was openness to including more of Undici but not all, remove from agenda for now.

Sooo is it happening?

[mcollina]

@JakobJingleheimer it needs a champion.