New Explicit Resource Management docs and improvements

[ardatan]

After the discussion with @n1ru4l ;
Some changes are done in @whatwg-node/server, so in order to configure the new feature (including the new hook);

• Allow to configure server adapter from Yoga options such as disposeOnProcessTerminate
• Allow to use the new hook
• Document dispose method, onDispose hook, ctx.waitUntil and everything related to the things related to the resource management and graceful shutdown

cc @EmrysMyrddin about graphql-hive/console#6128

[changeset-bot]

🦋 Changeset detected

Latest commit: 4e7f89d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 24 packages

Name	Type
@graphql-yoga/apollo-managed-federation	Patch
graphql-yoga	Patch
@graphql-yoga/nestjs	Patch
@graphql-yoga/render-graphiql	Patch
@graphql-yoga/plugin-apollo-inline-trace	Patch
@graphql-yoga/plugin-apollo-usage-report	Patch
@graphql-yoga/plugin-apq	Patch
@graphql-yoga/plugin-csrf-prevention	Patch
@graphql-yoga/plugin-defer-stream	Patch
@graphql-yoga/plugin-disable-introspection	Patch
@graphql-yoga/plugin-graphql-sse	Patch
@graphql-yoga/plugin-jwt	Patch
@graphql-yoga/plugin-persisted-operations	Patch
@graphql-yoga/plugin-prometheus	Patch
@graphql-yoga/plugin-response-cache	Patch
@graphql-yoga/plugin-sofa	Patch
apollo-federation-gateway-with-yoga	Patch
apollo-subgraph-with-yoga	Patch
graphql-lambda	Patch
cloudflare-advanced	Patch
cloudflare	Patch
nextjs-app	Patch
hello-world-benchmark	Patch
@graphql-yoga/nestjs-federation	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Apollo Federation Subgraph Compatibility Results

Federation 1 Support	Federation 2 Support
_service 🟢 @key (single) 🟢 @key (multi) 🟢 @key (composite) 🟢 repeatable @key 🟢 @requires 🟢 @provides 🟢 federated tracing 🟢	@link 🟢 @shareable 🟢 @tag 🟢 @override 🟢 @inaccessible 🟢 @composeDirective 🟢 @interfaceObject 🟢

Learn more:

• Apollo Federation Subgraph Specification
• Compatibility Tests

[github-actions]

✅ Benchmark Results

     ✓ no_errors{mode:graphql}
     ✓ expected_result{mode:graphql}
     ✓ no_errors{mode:graphql-jit}
     ✓ expected_result{mode:graphql-jit}
     ✓ no_errors{mode:graphql-response-cache}
     ✓ expected_result{mode:graphql-response-cache}
     ✓ no_errors{mode:graphql-no-parse-validate-cache}
     ✓ expected_result{mode:graphql-no-parse-validate-cache}
     ✓ no_errors{mode:uws}
     ✓ expected_result{mode:uws}

     checks.......................................: 100.00% ✓ 513342      ✗ 0     
     data_received................................: 2.1 GB  14 MB/s
     data_sent....................................: 103 MB  688 kB/s
     http_req_blocked.............................: avg=1.48µs   min=961ns    med=1.29µs   max=315.67µs p(90)=1.97µs   p(95)=2.16µs  
     http_req_connecting..........................: avg=2ns      min=0s       med=0s       max=141.89µs p(90)=0s       p(95)=0s      
     http_req_duration............................: avg=365.79µs min=219.2µs  med=331.35µs max=19.1ms   p(90)=477.29µs p(95)=502.51µs
       { expected_response:true }.................: avg=365.79µs min=219.2µs  med=331.35µs max=19.1ms   p(90)=477.29µs p(95)=502.51µs
     ✓ { mode:graphql-jit }.......................: avg=294.48µs min=219.2µs  med=276.69µs max=18.54ms  p(90)=310.37µs p(95)=328.86µs
     ✓ { mode:graphql-no-parse-validate-cache }...: avg=504.22µs min=414.2µs  med=478.11µs max=6.25ms   p(90)=525.91µs p(95)=579.22µs
     ✓ { mode:graphql-response-cache }............: avg=346.63µs min=269.72µs med=329.67µs max=6.58ms   p(90)=361.33µs p(95)=373.28µs
     ✓ { mode:graphql }...........................: avg=372.95µs min=282.59µs med=341.01µs max=19.1ms   p(90)=401.62µs p(95)=469.61µs
     ✓ { mode:uws }...............................: avg=348.93µs min=271.1µs  med=330.54µs max=6.07ms   p(90)=366.93µs p(95)=388.82µs
     http_req_failed..............................: 0.00%   ✓ 0           ✗ 256671
     http_req_receiving...........................: avg=32.99µs  min=16.24µs  med=32.63µs  max=2.94ms   p(90)=39.59µs  p(95)=42.44µs 
     http_req_sending.............................: avg=8.71µs   min=6.07µs   med=7.61µs   max=315.09µs p(90)=11.12µs  p(95)=12.33µs 
     http_req_tls_handshaking.....................: avg=0s       min=0s       med=0s       max=0s       p(90)=0s       p(95)=0s      
     http_req_waiting.............................: avg=324.08µs min=191.9µs  med=290.72µs max=18.9ms   p(90)=434.63µs p(95)=458.25µs
     http_reqs....................................: 256671  1711.114775/s
     iteration_duration...........................: avg=579.43µs min=393.28µs med=540.53µs max=19.93ms  p(90)=695.3µs  p(95)=726.58µs
     iterations...................................: 256671  1711.114775/s
     vus..........................................: 1       min=1         max=1   
     vus_max......................................: 2       min=2         max=2   

[github-actions]

💻 Website Preview

The latest changes are available as preview in: https://888bad4a.graphql-yoga.pages.dev

[Urigo]

what are the most common things people would use this for in Yoga?

[ardatan]

#3567 (comment)

@Urigo For example in Hive Client Plugin, it creates a queue of background HTTP calls sending the reports to Hive Console. And in case of shutdown, we need to flush the queue and make sure all reports are sent.
This is very similar in OTEL, Sentry and Prom.
Ideally they all should use ctx.waitUntil. In that case, CF Workers can handle it by themselves and in Node.js we handle it with .dispose method in our queue logic. But that usually doesn't happen when plugins use 3rd party SDKs like OTEL, Hive Client etc. But it is still ok when you use onDispose.

[dotansimha]

I feel like this part could have been part of the tab itself?

[dotansimha]

I mean, we can also explain the scope { ... } and put it next to the example.

[ardatan]

Does this look better now?

[Urigo]

#3567 (comment)

@Urigo For example in Hive Client Plugin, it creates a queue of background HTTP calls sending the reports to Hive Console. And in case of shutdown, we need to flush the queue and make sure all reports are sent. This is very similar in OTEL, Sentry and Prom. Ideally they all should use ctx.waitUntil. In that case, CF Workers can handle it by themselves and in Node.js we handle it with .dispose method in our queue logic. But that usually doesn't happen when plugins use 3rd party SDKs like OTEL, Hive Client etc. But it is still ok when you use onDispose.

so its not actually for gateway developers but just for plugin developers?

[ardatan]

so its not actually for gateway developers but just for plugin developers?

ctx.waitUntil is available wherever the context is available. It is part of the context. So it can be used by Yoga users inside the resolvers. Both waitUntil and onDispose hook are for the people who create their plugins, and most of the users have their own plugins.

[n1ru4l]

approved with one small name improvement. I don't like using these kind of abbreviations ("\w")