Health check for liveliness, useReadinessCheck plugin for readiness (#1808)

Author: enisdenjo

.changeset/rotten-ghosts-design.md

@@ -0,0 +1,5 @@
+---
+'graphql-yoga': major
+---
+
+Drop `readinessCheckEndpoint` and introduce `useReadinessCheck` plugin

packages/graphql-yoga/__integration-tests__/readiness-checks.spec.ts

@@ -1,16 +1,11 @@
 import { createYoga } from 'graphql-yoga'
 
-describe('health checks', () => {
+describe('health check', () => {
   it('return 200 status code for health check endpoint', async () => {
     const yoga = createYoga({
       logging: false,
     })
-    const result = await yoga.fetch('http://yoga/health', {
-      method: 'GET',
-    })
+    const result = await yoga.fetch('http://yoga/health')
     expect(result.status).toBe(200)
-    expect(await result.json()).toEqual({
-      message: 'alive',
-    })
   })
 })

packages/graphql-yoga/__tests__/health-checks.spec.ts renamed to packages/graphql-yoga/__tests__/health-check.spec.ts

@@ -0,0 +1,126 @@
+import { createYoga, createSchema } from 'graphql-yoga'
+import { useReadinessCheck } from '../src/plugins/useReadinessCheck'
+
+describe('Readiness Check', () => {
+  const schema = createSchema({
+    typeDefs: /* GraphQL */ `
+      type Query {
+        hello: String!
+      }
+    `,
+    resolvers: {
+      Query: {
+        async hello() {
+          return 'world'
+        },
+      },
+    },
+  })
+
+  it('should respond with 200 if check returns nothing', async () => {
+    const yoga = createYoga({
+      schema,
+      plugins: [
+        useReadinessCheck({
+          check: async () => {
+            // noop
+          },
+        }),
+      ],
+    })
+
+    const response = await yoga.fetch('http://yoga/ready')
+    expect(response.status).toBe(200)
+  })
+
+  it('should respond with 200 if check returns true', async () => {
+    const yoga = createYoga({
+      schema,
+      plugins: [
+        useReadinessCheck({
+          check: async () => {
+            return true
+          },
+        }),
+      ],
+    })
+
+    const response = await yoga.fetch('http://yoga/ready')
+    expect(response.status).toBe(200)
+  })
+
+  it('should respond with 503 if check returns false', async () => {
+    const yoga = createYoga({
+      schema,
+      plugins: [
+        useReadinessCheck({
+          check: async () => {
+            return false
+          },
+        }),
+      ],
+    })
+
+    const response = await yoga.fetch('http://yoga/ready')
+    expect(response.status).toBe(503)
+  })
+
+  it('should respond with 503 and the error message if check throws an error', async () => {
+    const message = 'Not good, not bad.'
+
+    const yoga = createYoga({
+      schema,
+      plugins: [
+        useReadinessCheck({
+          check: async () => {
+            throw new Error(message)
+          },
+        }),
+      ],
+    })
+
+    const response = await yoga.fetch('http://yoga/ready')
+    expect(response.status).toBe(503)
+    expect(response.headers.get('content-type')).toBe(
+      'text/plain; charset=utf-8',
+    )
+    expect(await response.text()).toBe(message)
+  })
+
+  it('should respond with 503 and empty body if check throws not an error', async () => {
+    const yoga = createYoga({
+      schema,
+      plugins: [
+        useReadinessCheck({
+          check: async () => {
+            throw 1
+          },
+        }),
+      ],
+    })
+
+    const response = await yoga.fetch('http://yoga/ready')
+    expect(response.status).toBe(503)
+    expect(response.headers.get('content-type')).toBeNull()
+    expect(await response.text()).toBe('')
+  })
+
+  it('should respond with the response from check', async () => {
+    const message = 'I am a-ok!'
+
+    const yoga = createYoga({
+      schema,
+      plugins: [
+        useReadinessCheck({
+          check: async ({ fetchAPI }) => {
+            return new fetchAPI.Response(message, { status: 201 })
+          },
+        }),
+      ],
+    })
+
+    const response = await yoga.fetch('http://yoga/ready')
+    expect(response.status).toBe(201)
+    expect(await response.text()).toBe(message)
+  })
+})

packages/graphql-yoga/__tests__/readiness-check.spec.ts

@@ -8,5 +8,6 @@ export type { GraphiQLOptions } from './plugins/useGraphiQL.js'
 export type { Plugin } from './plugins/types.js'
 export { shouldRenderGraphiQL, renderGraphiQL } from './plugins/useGraphiQL.js'
 export { useSchema } from './plugins/useSchema.js'
+export { useReadinessCheck } from './plugins/useReadinessCheck.js'
 export * from './schema.js'
 export * from './subscription.js'

packages/graphql-yoga/src/index.ts

@@ -1,66 +1,29 @@
-import { createGraphQLError } from '@graphql-tools/utils'
 import { YogaLogger } from '../logger.js'
 import { Plugin } from './types.js'
 
 export interface HealthCheckPluginOptions {
   id?: string
   logger?: YogaLogger
-  healthCheckEndpoint?: string
-  readinessCheckEndpoint?: string
+  endpoint?: string
 }
 
 export function useHealthCheck({
   id = Date.now().toString(),
   logger = console,
-  healthCheckEndpoint = '/health',
-  readinessCheckEndpoint = '/readiness',
+  endpoint = '/health',
 }: HealthCheckPluginOptions = {}): Plugin {
   return {
-    async onRequest({ request, endResponse, fetchAPI, url }) {
+    async onRequest({ endResponse, fetchAPI, url }) {
       const { pathname: requestPath } = url
-      if (requestPath === healthCheckEndpoint) {
-        logger.debug(`Responding Health Check`)
-        const response = new fetchAPI.Response(
-          JSON.stringify({
-            message: 'alive',
-          }),
-          {
-            status: 200,
-            headers: {
-              'Content-Type': 'application/json',
-              'x-yoga-id': id,
-            },
+      if (requestPath === endpoint) {
+        logger.debug('Responding Health Check')
+        const response = new fetchAPI.Response(null, {
+          status: 200,
+          headers: {
+            'x-yoga-id': id,
           },
-        )
+        })
         endResponse(response)
-      } else if (requestPath === readinessCheckEndpoint) {
-        logger.debug(`Responding Readiness Check`)
-        const readinessResponse = await fetchAPI.fetch(
-          request.url.replace(readinessCheckEndpoint, healthCheckEndpoint),
-        )
-        const { message } = await readinessResponse.json()
-        if (
-          readinessResponse.status === 200 &&
-          readinessResponse.headers.get('x-yoga-id') === id &&
-          message === 'alive'
-        ) {
-          const response = new fetchAPI.Response(
-            JSON.stringify({
-              message: 'ready',
-            }),
-            {
-              status: 200,
-              headers: {
-                'Content-Type': 'application/json',
-              },
-            },
-          )
-          endResponse(response)
-        } else {
-          throw createGraphQLError(
-            `Readiness check failed with status ${readinessResponse.status}`,
-          )
-        }
       }
     },
   }

packages/graphql-yoga/src/plugins/useHealthCheck.ts

@@ -0,0 +1,63 @@
+import { Plugin, FetchAPI } from 'graphql-yoga'
+
+export interface ReadinessCheckPluginOptions {
+  /**
+   * Under which endpoint do you want the readiness check to be?
+   *
+   * @default /ready
+   */
+  endpoint?: string
+  /**
+   * The check for whether the service is ready to perform.
+   *
+   * You should check here whether the services Yoga depends on
+   * are ready and working, for example: is the database up and running?
+   *
+   * - Returning `true` or nothing will respond with a 200 OK.
+   * - Returning `false` or throwing an error will respond with a 503 Service Unavailable.
+   * - Returning a `Response` will have the readiness check respond with it.
+   *
+   * Beware that if an instance of `Error` is thrown, its message will be present in the
+   * response body. Be careful which information you expose.
+   */
+  check: (payload: {
+    request: Request
+    fetchAPI: FetchAPI
+  }) => void | boolean | Response | Promise<void | boolean | Response>
+}
+
+/**
+ * Adds a readiness check for Yoga by simply implementing the `check` option.
+ */
+export function useReadinessCheck({
+  endpoint = '/ready',
+  check,
+}: ReadinessCheckPluginOptions): Plugin {
+  return {
+    async onRequest({ request, endResponse, fetchAPI, url }) {
+      const { pathname: requestPath } = url
+      if (requestPath === endpoint) {
+        let response: Response
+        try {
+          const readyOrResponse = await check({ request, fetchAPI })
+          if (typeof readyOrResponse === 'object') {
+            response = readyOrResponse
+          } else {
+            response = new fetchAPI.Response(null, {
+              status: readyOrResponse === false ? 503 : 200,
+            })
+          }
+        } catch (err) {
+          const isError = err instanceof Error
+          response = new fetchAPI.Response(isError ? err.message : null, {
+            status: 503,
+            headers: isError
+              ? { 'content-type': 'text/plain; charset=utf-8' }
+              : {},
+          })
+        }
+        endResponse(response)
+      }
+    },
+  }
+}

packages/graphql-yoga/src/plugins/useReadinessCheck.ts

@@ -117,13 +117,6 @@ export type YogaServerOptions<
    */
   graphqlEndpoint?: string
 
-  /**
-   * Readiness check endpoint
-   *
-   * @default "/readiness"
-   */
-  readinessCheckEndpoint?: string
-
   /**
    * Readiness check endpoint
    *
@@ -331,8 +324,7 @@ export class YogaServer<
       useHealthCheck({
         id: this.id,
         logger: this.logger,
-        healthCheckEndpoint: options?.healthCheckEndpoint,
-        readinessCheckEndpoint: options?.readinessCheckEndpoint,
+        endpoint: options?.healthCheckEndpoint,
       }),
       options?.cors !== false && useCORS(options?.cors),
       options?.graphiql !== false &&