Extensible DispatchHandler #1338

arontsang · 2022-04-13T20:06:05Z

This adds a plugin system that allows decorators to be added to the DispatchHandler as part of a pipeline.

I expect to see in future plugins such as (but not limited to):

Windows Authentication NTLM/Negotiate/Kerberos
Client side caching (Question: Does undici.fetch support RFC 7234? #1146)
Retry logic
Telemetry/Logging

This should support #491

ronag · 2022-04-14T05:39:10Z

I don't really see what this brings other than maybe better ergonomics? The dispatcher interface is already quite extensible? Could this live outside as an npm package?

mcollina

I see the need for better ergonomics for this, however I would not add any new globals for this. Could this be a feature of Agent instead?

arontsang · 2022-04-15T18:54:05Z

At the end of the day, this is simply a proposal. I expect some back and forth before a final revision. Personally, I'm not happy with the shape of the API, but I'm happy to take suggestions. Additionally, I'm considering switching to a DispatcherDecorator model, with a AgentBuilder for setting the global dispatcher.

…

On Thu, 14 Apr 2022, 15:08 Matteo Collina, ***@***.***> wrote: ***@***.**** requested changes on this pull request. I see the need for better ergonomics for this, however I would not add any new globals for this. Could this be a feature of Agent instead? — Reply to this email directly, view it on GitHub <#1338 (review)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AA46MLIICLNLN3DLSUXB6S3VE675FANCNFSM5TLXQTAQ> . You are receiving this because you authored the thread.Message ID: ***@***.***>

arontsang · 2022-04-15T19:32:34Z

Also, I'm having trouble coming up with an API that would not create a breaking change on a raw Client, whilst also extracting out the RedirectHandler.

…

On Sat, 16 Apr 2022, 02:53 Aron Tsang, ***@***.***> wrote: At the end of the day, this is simply a proposal. I expect some back and forth before a final revision. Personally, I'm not happy with the shape of the API, but I'm happy to take suggestions. Additionally, I'm considering switching to a DispatcherDecorator model, with a AgentBuilder for setting the global dispatcher. On Thu, 14 Apr 2022, 15:08 Matteo Collina, ***@***.***> wrote: > ***@***.**** requested changes on this pull request. > > I see the need for better ergonomics for this, however I would not add > any new globals for this. Could this be a feature of Agent instead? > > — > Reply to this email directly, view it on GitHub > <#1338 (review)>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/AA46MLIICLNLN3DLSUXB6S3VE675FANCNFSM5TLXQTAQ> > . > You are receiving this because you authored the thread.Message ID: > ***@***.***> >

mcollina · 2022-04-16T07:04:45Z

How would the DispatcherDecorator work?

arontsang · 2022-04-17T19:57:12Z

@mcollina Here is another commit showing what I mean arontsang@d54794f?diff=unified

In effect we add to the constructor of Dispatcher { interceptors: Record<string, DispatchInterceptor[]> }

Where type DispatchInterceptor = Dispatcher[kDispatch] => Dispatcher[kDispatch]
Where type Dispatcher[kDispatch] = (options: Dispatcher.DispatchOptions, handler: Dispatcher.DispatchHandlers) => boolean

We then reduce the array of DispatchInterceptors over this[kDispatch] to produce an intercepted dispatch method.

codecov-commenter · 2022-04-17T20:00:45Z

Codecov Report

Merging #1338 (3add5df) into main (84f56f7) will decrease coverage by 0.28%.
The diff coverage is 76.92%.

@@            Coverage Diff             @@
##             main    #1338      +/-   ##
==========================================
- Coverage   94.95%   94.67%   -0.29%     
==========================================
  Files          51       53       +2     
  Lines        4816     4862      +46     
==========================================
+ Hits         4573     4603      +30     
- Misses        243      259      +16

Impacted Files	Coverage Δ
lib/core/symbols.js	`100.00% <ø> (ø)`
lib/handler/DecoratorHandler.js	`11.11% <11.11%> (ø)`
lib/dispatcher-base.js	`91.48% <61.11%> (-7.23%)`	⬇️
index.js	`100.00% <100.00%> (ø)`
lib/agent.js	`100.00% <100.00%> (ø)`
lib/balanced-pool.js	`98.85% <100.00%> (+0.01%)`	⬆️
lib/client.js	`96.98% <100.00%> (-0.01%)`	⬇️
lib/handler/RedirectHandler.js	`91.13% <100.00%> (ø)`
lib/interceptor/redirectInterceptor.js	`100.00% <100.00%> (ø)`
lib/pool.js	`100.00% <100.00%> (ø)`
... and 2 more

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

arontsang · 2022-04-17T20:05:44Z

I've just noticed that ProxyAgent could be replaced with a DispatchInterceptor quite trivially.

mcollina

Good work! Could you run the benchmarks before/after? Could you document this new feature?

lib/dispatcher-base.js

types/dispatcher.d.ts

lib/interceptor/redirect.js

types/pool.d.ts

Add documentation

mcollina

Good work!

mcollina · 2022-04-22T08:52:32Z

docs/api/DispatchInterceptor.md

+'use strict'
+
+const clearHeadersInterceptor = dispatch => {
+  const DecoratorHandler = require('undici/lib/handler/decorator')


This is an internal library, let's not document it. If it needs to be exposed, please use the module entry point.

@mcollina I would prefer this to be exposed. I am actually trying to add support for NTLM undici, which doesn't seem like a great fit for being in mainline.

The only reason I am working on this is the fact that node.js has terrible support for socket based Auth. The socket is abstracted away completely.

Additionally, I suspect opening this up will allow for lots of extensions.

I've also noticed that http headers being of type ByteArray means that each extension is likely to be to decode utf8 once each...

Go ahead and expose it in this PR.

I've also noticed that http headers being of type ByteArray means that each extension is likely to be to decode utf8 once each...

What do you mean? Can you make an example?

@kibertoad this needs fixing, we should not be deep-requiring.

lib/dispatcher-base.js

mcollina · 2022-04-22T08:57:31Z

@ronag PTAL

arontsang · 2022-04-29T13:45:21Z

@ronag PTAL

@ronag Any chance you can take a look?

ronag · 2022-04-29T16:53:54Z

I'll have. A look next week.

arontsang · 2022-04-29T17:52:09Z

Thanks

…

On Sat, 30 Apr 2022, 00:54 Robert Nagy, ***@***.***> wrote: I'll have. A look next week. — Reply to this email directly, view it on GitHub <#1338 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AA46MLIK5FZFIM4M43CUDGLVHQH23ANCNFSM5TLXQTAQ> . You are receiving this because you authored the thread.Message ID: ***@***.***>

ronag · 2022-04-29T18:07:06Z

I think this can be achieved without modifying existing internals and I think I would maybe prefer that, i.e. implement a compose/decorate/intercept (or other name) function that implements a compose dispatcher that applies this logic. So it would essentially be possible to do the following without any modification of existing code:

const client = undici.intercept(new Client('https://localhost:3000', [ 
  dispatch => function insertHeader(opts, handler){
    opts.headers.push('Authorization', 'Bearer [Some token]')
    return dispatch(opts, handler)
  }
])

ronag · 2022-04-29T18:14:09Z

Or maybe:

const client = undici.compose(
  () => new Client('https://localhost:3000', 
  dispatch => function insertHeader(opts, handler){
    opts.headers.push('Authorization', 'Bearer [Some token]')
    return dispatch(opts, handler)
  }
)

ronag · 2022-04-29T18:15:30Z

undici.request(url, {
   decorate: [insertHeaders({ foo: 'bar' }, redirect({ maxRetries: 3 )]
})

ronag · 2022-04-29T18:17:15Z

This might need a few iterations and since it doesn't require any internal modifications we should consider whether or not we should first have it as an external package. Not saying we should. Just to consider.

arontsang · 2022-04-29T18:22:24Z

undici.request(url, {
   decorate: [insertHeaders({ foo: 'bar' }, redirect({ maxRetries: 3 )]
})

This would not work for my use case. I NEED to apply the decorator AT the client level of an Agent.

The decorator needs to be scoped to a single TCP connection to be able to implement NTLM authentication.

arontsang · 2022-04-29T18:23:52Z

Or maybe:

const client = undici.compose(
  () => new Client('https://localhost:3000', 
  dispatch => function insertHeader(opts, handler){
    opts.headers.push('Authorization', 'Bearer [Some token]')
    return dispatch(opts, handler)
  }
)

This works, but it would require an inordinate amount of boiler plate to bring up a full Agent with decorators at the right levels, Agent, Pool, Client etc...

kibertoad · 2022-09-03T13:20:25Z

@arontsang Can you provide any details on

Well, if you are already thinking about it. I would like to change the
interface for the DispatchHandler to return headers as string[] rather than
ByteArray[].

This would help reduce the number of Utf8 decodes.

? I can't find where in the code this is happening

kibertoad · 2022-09-03T13:20:59Z

@mcollina @ronag I've resolved conflicts and addressed all the outstanding comments, could you please rereview?

upd: type tests are failing, I'll fix them shortly, shouldn't affect any of the runtime code

kibertoad · 2022-09-03T16:10:33Z

@mcollina @ronag All green and ready for rereview.

mcollina · 2022-09-05T10:11:43Z

docs/api/DispatchInterceptor.md

+'use strict'
+
+const clearHeadersInterceptor = dispatch => {
+  const DecoratorHandler = require('undici/lib/handler/decorator')


@kibertoad this needs fixing, we should not be deep-requiring.

mcollina · 2022-09-05T10:13:02Z

docs/api/Pool.md

@@ -19,6 +19,7 @@ Extends: [`ClientOptions`](Client.md#parameter-clientoptions)

 * **factory** `(origin: URL, opts: Object) => Dispatcher` - Default: `(origin, opts) => new Client(origin, opts)`
 * **connections** `number | null` (optional) - Default: `null` - The number of `Client` instances to create. When set to `null`, the `Pool` instance will create an unlimited amount of `Client` instances.
+* **interceptors.Pool** `Array<DispatchInterceptor>` - Default: `[]` - A list of interceptors that are applied to the dispatch method. Additional logic can be applied (such as, but not limited to: 302 status code handling, authentication, cookies, compression and caching).


It's not clear this is { interceptors: { Pool: [] } }

fixed in all docs

kibertoad · 2022-09-05T21:57:11Z

@mcollina Comments addressed!

mcollina

I would avoid introducing any more global settings, could you avoid them? Thanxk

mcollina · 2022-09-06T07:25:54Z

lib/proxy-agent.js

@@ -42,7 +62,7 @@ class ProxyAgent extends DispatcherBase {

    const connect = buildConnector({ ...opts.proxyTls })
    this[kConnectEndpoint] = buildConnector({ ...opts.requestTls })
-    this[kClient] = new Client({ origin: opts.origin, connect })
+    this[kClient] = new Agent({ origin: opts.origin, connect })


Why this change?

const Client = require('./agent') const Agent = require('./agent')

Naming was confusing, they were exactly same thing. Am I missing anything?

Seems more like the import was incorrect?

ok, I'll fix it then

kibertoad · 2022-09-06T07:47:48Z

I would avoid introducing any more global settings, could you avoid them? Thanxk

@mcollina Do you mean new options for Client/Agent/Pool? Where would you place them instead?

mcollina

lgtm, that text was a leftover from a previous half-botched review

kibertoad · 2022-09-06T09:01:09Z

@mcollina @ronag What's left before this can be merged?
Also it would be great to release a new version sometime after the merge, would allow our team to start working on actual Undici interceptors :D

wong2 · 2022-09-22T08:31:43Z

Does this support async logic in interceptors? For example, read credentials from the disk in a request interceptor and then add them to request headers.

wong2 · 2022-09-22T09:38:18Z

Also I find it annoying when extending request headers in a request interceptor, the opts.headers type is vague, according to typescript declaration they could be IncomingHttpHeaders | string[] | null, which makes it hard when extending...

arontsang · 2022-10-11T08:32:42Z

I would need help with some of this. I am a dotnet Dev by trade, so a lot of it isn't my wheelhouse, for example, I don't know the Jest library inside and out... Would it be better if we put this into a branch?

…

On Tue, 28 Jun 2022, 00:01 Matteo Collina, ***@***.***> wrote: Let's go ahead and land. The code seems reasonable to me so far, minus all the comments. I'm 100% ok with semver-major changes on this one. Maybe we could classify interceptors as experimental? Could you address them @arontsang <https://github.com/arontsang>? Sorry for the long wait. — Reply to this email directly, view it on GitHub <#1338 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AA46MLL6GODF7EIVJEFHAKDVRHF7HANCNFSM5TLXQTAQ> . You are receiving this because you were mentioned.Message ID: ***@***.***>

arontsang · 2022-10-11T09:15:45Z

It can, but, that would get very complicated when we get to the point of having half a dozen of these things

…

On Sat, 30 Apr 2022, 02:07 Robert Nagy, ***@***.***> wrote: I think this can be achieved without modifying existing internals and I think I would maybe prefer that, i.e. implement a compose/decorate/intercept (or other name) function that implements a compose dispatcher that applies this logic. So it would essentially be possible to do the following without any modification of existing code: const insertHeaderInterceptor = dispatch => { return function InterceptedDispatch(opts, handler){ opts.headers.push('Authorization', 'Bearer [Some token]') return dispatch(opts, handler) }} const client = undici.intercept(new Client('https://localhost:3000', [ insertHeaderInterceptor ]) — Reply to this email directly, view it on GitHub <#1338 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AA46MLNQYNHYTC7F5R6PARTVHQQNLANCNFSM5TLXQTAQ> . You are receiving this because you authored the thread.Message ID: ***@***.***>

* Create DispatchInterceptors * Add Unit Tests, fix DispatchHandler typescript Add documentation * Switch to simple null check and shortcircuit bind * Add typescript test for Dispatcher events * Move build intecepted dispatch to top level * Restore lost method * Fix TS error * Address code review comments * Fix linting * Type improvements * Fix TS tests * Address code review comments * Fix TS test * Fix types * Address comments * Fix client construction Co-authored-by: Igor Savin <iselwin@gmail.com>

mcollina requested changes Apr 14, 2022

View reviewed changes

arontsang force-pushed the main branch from 6896e5c to d54794f Compare April 17, 2022 19:58

Create DispatchInterceptors

6ba0015

arontsang requested a review from mcollina April 17, 2022 20:05

mcollina reviewed Apr 17, 2022

View reviewed changes

lib/dispatcher-base.js Outdated Show resolved Hide resolved

types/dispatcher.d.ts Show resolved Hide resolved

lib/interceptor/redirect.js Outdated Show resolved Hide resolved

types/pool.d.ts Outdated Show resolved Hide resolved

Add Unit Tests, fix DispatchHandler typescript

80268c0

Add documentation

arontsang force-pushed the main branch from d54794f to 80268c0 Compare April 18, 2022 20:00

Switch to simple null check and shortcircuit bind

6b4ee13

arontsang force-pushed the main branch from ee376c5 to 6b4ee13 Compare April 19, 2022 15:14

Add typescript test for Dispatcher events

b37e39d

arontsang requested a review from mcollina April 21, 2022 17:18

mcollina reviewed Apr 22, 2022

View reviewed changes

Move build intecepted dispatch to top level

1f59ef8

kibertoad added 4 commits September 3, 2022 15:28

Fix TS error

02d9d3f

Address code review comments

673ffcb

Fix linting

a3e887b

Type improvements

1c7e7fb

Fix TS tests

1ba045d

mcollina reviewed Sep 5, 2022

View reviewed changes

kibertoad added 2 commits September 6, 2022 00:44

Address code review comments

9757dae

Fix TS test

498397b

Fix types

3add5df

mcollina approved these changes Sep 6, 2022

View reviewed changes

Address comments

9884bd7

mcollina approved these changes Sep 6, 2022

View reviewed changes

Fix client construction

66e7ea7

ronag approved these changes Sep 6, 2022

View reviewed changes

mcollina merged commit 33934f8 into nodejs:main Sep 6, 2022

ci010 mentioned this pull request Sep 18, 2022

Question: Does undici.fetch support RFC 7234? #1146

Open

ejizba mentioned this pull request Oct 24, 2022

esModuleInterop flag required to build TypeScript project referencing v5.11.0 #1727

Closed

Uzlopak mentioned this pull request Apr 9, 2024

test: duplicate jest unspecific tests to native runner #3075

Merged

Extensible DispatchHandler #1338

Extensible DispatchHandler #1338

Conversation

arontsang commented Apr 13, 2022 • edited

ronag commented Apr 14, 2022

mcollina left a comment

Choose a reason for hiding this comment

arontsang commented Apr 15, 2022 via email

arontsang commented Apr 15, 2022 via email

mcollina commented Apr 16, 2022

arontsang commented Apr 17, 2022

codecov-commenter commented Apr 17, 2022 • edited

Codecov Report

arontsang commented Apr 17, 2022

mcollina left a comment

Choose a reason for hiding this comment

mcollina left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mcollina commented Apr 22, 2022

arontsang commented Apr 29, 2022

ronag commented Apr 29, 2022

arontsang commented Apr 29, 2022 via email

ronag commented Apr 29, 2022 • edited

ronag commented Apr 29, 2022 • edited

ronag commented Apr 29, 2022 • edited

ronag commented Apr 29, 2022

arontsang commented Apr 29, 2022

arontsang commented Apr 29, 2022

kibertoad commented Sep 3, 2022

kibertoad commented Sep 3, 2022 • edited

kibertoad commented Sep 3, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kibertoad commented Sep 5, 2022

mcollina left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kibertoad commented Sep 6, 2022

mcollina left a comment

Choose a reason for hiding this comment

kibertoad commented Sep 6, 2022

wong2 commented Sep 22, 2022

wong2 commented Sep 22, 2022

arontsang commented Oct 11, 2022 via email

arontsang commented Oct 11, 2022 via email

arontsang commented Apr 13, 2022 •

edited

codecov-commenter commented Apr 17, 2022 •

edited

ronag commented Apr 29, 2022 •

edited

ronag commented Apr 29, 2022 •

edited

ronag commented Apr 29, 2022 •

edited

kibertoad commented Sep 3, 2022 •

edited