Health check for liveliness, useReadinessCheck plugin for readiness

[enisdenjo]

Closes #958

Prelude

"Readiness" and "liveliness" are types of health checks, they both are a health check but serve a different meaning:

• "Liveliness" checks whether the service is alive/running
• "Readiness" checks whether the service is ready to perform work

The difference is that a service can be live but not ready - for example, server has started but the database read replica is unavailable.

A liveliness check is something Yoga can offer out of the box because Yoga is a server and Yoga knows when it's alive/running. However, a readiness check is something Yoga cannot possibly figure out on its own, it is a check requiring user-land context.

Having said this, I propose dropping the built-in /ready route serving a "readiness" check and keeping the /health route for a liveliness check (a liveliness check is naturally interpreted as a health check).

Summary

• Drop "readiness" check - no more /readiness route, no more readinessCheckEndpoint
• Responding with just a 200 OK to a health check is more than enough, a JSON body is simply superfluous
• Introduce useReadinessCheck plugin under @graphql-yoga/plugin-readiness-check under core graphql-yoga

Using the readiness check plugin

*See tests and code docs for more usage ideas.

import { createYoga, useReadinessCheck } from 'graphql-yoga'
import { createServer } from 'node:http'
import { schema, checkDbAvailable } from './my-service';

const yoga = createYoga({
  schema,
  plugins: [
    useReadinessCheck({
      endpoint: '/ready', //default
      check: async () => {
        // if resolves, respond with 200 OK
        // if throw, respond with 504 Service Unavailable and error message as plaintext in body
        await checkDbAvailable()
      },
    }),
  ],
})

const readinessResponse = await yoga.fetch('http://yoga/ready')
const isReady = readinessResponse.ok;

TODO

• Write documentation for website
• Write migration from v2 for website
• Readiness plugin is very small and zero-deps, should it be a part of the core Yoga?

[changeset-bot]

🦋 Changeset detected

Latest commit: 89a732b

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

This PR includes changesets to release 15 packages

Name	Type
graphql-yoga	Major
@graphql-yoga/common	Patch
@graphql-yoga/node	Patch
@graphql-yoga/render-graphiql	Major
@graphql-yoga/plugin-apollo-inline-trace	Major
@graphql-yoga/plugin-apq	Major
@graphql-yoga/plugin-persisted-operations	Major
@graphql-yoga/plugin-response-cache	Major
apollo-federation-gateway-with-yoga	Patch
apollo-subgraph-with-yoga	Patch
graphql-lambda	Patch
cloudflare-advanced	Patch
cloudflare	Patch
hackernews	Patch
hello-world-benchmark	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]

✅ Benchmark Results

     ✓ no_errors
     ✓ expected_result

     checks.........................: 100.00% ✓ 90382      ✗ 0    
     data_received..................: 14 MB   449 kB/s
     data_sent......................: 5.2 MB  173 kB/s
     http_req_blocked...............: avg=1.61µs   min=900ns    med=1.4µs    max=1.6ms    p(90)=1.9µs    p(95)=2.2µs   
     http_req_connecting............: avg=4ns      min=0s       med=0s       max=183.61µs p(90)=0s       p(95)=0s      
   ✓ http_req_duration..............: avg=568.16µs min=348.63µs med=493.24µs max=26.5ms   p(90)=628.95µs p(95)=736.96µs
       { expected_response:true }...: avg=568.16µs min=348.63µs med=493.24µs max=26.5ms   p(90)=628.95µs p(95)=736.96µs
     http_req_failed................: 0.00%   ✓ 0          ✗ 45191
     http_req_receiving.............: avg=24.77µs  min=12.9µs   med=19.2µs   max=5.36ms   p(90)=30.9µs   p(95)=36.7µs  
     http_req_sending...............: avg=8.4µs    min=4.1µs    med=6.1µs    max=1.61ms   p(90)=13µs     p(95)=14.3µs  
     http_req_tls_handshaking.......: avg=0s       min=0s       med=0s       max=0s       p(90)=0s       p(95)=0s      
     http_req_waiting...............: avg=534.98µs min=331.02µs med=465.13µs max=26.37ms  p(90)=585.95µs p(95)=693.46µs
     http_reqs......................: 45191   1506.23542/s
     iteration_duration.............: avg=657.07µs min=405.93µs med=575.94µs max=27.15ms  p(90)=736.36µs p(95)=858.92µs
     iterations.....................: 45191   1506.23542/s
     vus............................: 1       min=1        max=1  
     vus_max........................: 1       min=1        max=1  

[github-actions]

🚀 Snapshot Release (alpha)

The latest changes of this PR are available as alpha on npm (based on the declared changesets):

Package	Version	Info
@graphql-yoga/apollo-link	1.0.0-alpha-20220929180530-a25088f2	npm ↗︎ unpkg ↗︎
@graphql-yoga/urql-exchange	1.0.0-alpha-20220929180530-a25088f2	npm ↗︎ unpkg ↗︎
@graphql-yoga/common	3.0.0-alpha-20220929180530-a25088f2	npm ↗︎ unpkg ↗︎
@graphql-yoga/redis-event-target	1.0.0-alpha-20220929180530-a25088f2	npm ↗︎ unpkg ↗︎
@graphql-yoga/typed-event-target	1.0.0-alpha-20220929180530-a25088f2	npm ↗︎ unpkg ↗︎
@graphql-yoga/graphiql	3.0.0-alpha-20220929180530-a25088f2	npm ↗︎ unpkg ↗︎
graphql-yoga	3.0.0-alpha-20220929180530-a25088f2	npm ↗︎ unpkg ↗︎
@graphql-yoga/node	3.0.0-alpha-20220929180530-a25088f2	npm ↗︎ unpkg ↗︎
@graphql-yoga/plugin-apollo-inline-trace	1.0.0-alpha-20220929180530-a25088f2	npm ↗︎ unpkg ↗︎
@graphql-yoga/plugin-apq	1.0.0-alpha-20220929180530-a25088f2	npm ↗︎ unpkg ↗︎
@graphql-yoga/plugin-persisted-operations	1.0.0-alpha-20220929180530-a25088f2	npm ↗︎ unpkg ↗︎
@graphql-yoga/plugin-response-cache	1.0.0-alpha-20220929180530-a25088f2	npm ↗︎ unpkg ↗︎
@graphql-yoga/render-graphiql	3.0.0-alpha-20220929180530-a25088f2	npm ↗︎ unpkg ↗︎
@graphql-yoga/subscription	3.0.0-alpha-20220929180530-a25088f2	npm ↗︎ unpkg ↗︎

[github-actions]

🚀 Website Preview

The latest changes to the website are available as preview in: https://5dd8edb0.graphql-yoga.pages.dev