Refactor GraphQL Server and CreateYoga to Support "api serve" with Fastify Server

[dthyresson]

As part of the effort to have fastify plugins for running the redwood api and web servers, this PR refactors parts of the graphql-server package so it too can be used in a more "serverful" manner.

And, in doing so, begin the support for "RedwoodJS Realtime" via GraphQL subscriptions and Live Queries when deployed with a stateful server and memory stores.

This PR:

• creates of the createYoga portion on the createGraphQLHandler so it can be used by both the serverless function graphql and a
• new Fastify "plugin" that creates a server and registers yoga as a handler
• adds a new allowGraphiQL option because when running even in dev as yarn rw api serve this is considered production and both introspection and the playground are disabled. Now, you can control both and allow the playground to be used with rw ap serve
• updates the server file template to include a yoga server to experiment with

Use

The server.ts here creates a server and also sets up subscription and live query support (in the playground only, there is no web side support yet to actually listen or subscribe).

Currently, the types and resolvers are added to the RedwoodJS GraphQL schema via the extra schemaOptions option when merging the schema from the sdls, services and directives.

// api/src/server.ts

import path from 'path'

import { useLiveQuery } from '@envelop/live-query'
import chalk from 'chalk'
import { config } from 'dotenv-defaults'
import Fastify from 'fastify'
import { OperationTypeNode } from 'graphql'

import {
  coerceRootPath,
  redwoodFastifyWeb,
  redwoodFastifyAPI,
  redwoodFastifyGraphQLServer,
  DEFAULT_REDWOOD_FASTIFY_CONFIG,
} from '@redwoodjs/fastify'
import { getPaths, getConfig } from '@redwoodjs/project-config'

import directives from 'src/directives/**/*.{js,ts}'
import sdls from 'src/graphql/**/*.sdl.{js,ts}'
import services from 'src/services/**/*.{js,ts}'

import { liveQueryStore, liveSchema } from './graphql/liveSchema'
import { subscriptions, pubSub } from './graphql/subscriptions'
import { logger } from './lib/logger'

async function serve() {
  // Load .env files
  const redwoodProjectPaths = getPaths()
  const redwoodConfig = getConfig()

  const apiRootPath = coerceRootPath(redwoodConfig.web.apiUrl)
  const port = redwoodConfig.web.port

  const tsServer = Date.now()

  config({
    path: path.join(redwoodProjectPaths.base, '.env'),
    defaults: path.join(redwoodProjectPaths.base, '.env.defaults'),
    multiline: true,
  })

  console.log(chalk.italic.dim('Starting API and Web Servers...'))

  // Configure Fastify
  const fastify = Fastify({
    ...DEFAULT_REDWOOD_FASTIFY_CONFIG,
  })

  await fastify.register(redwoodFastifyWeb)

  await fastify.register(redwoodFastifyAPI, {
    redwood: {
      apiRootPath,
    },
  })

  await fastify.register(redwoodFastifyGraphQLServer, {
    loggerConfig: {
      logger: logger,
      options: { query: true, data: true, level: 'trace' },
    },
    graphiQLEndpoint: '/yoga',
    sdls,
    services,
    directives,
    allowedOperations: [
      OperationTypeNode.SUBSCRIPTION,
      OperationTypeNode.QUERY,
      OperationTypeNode.MUTATION,
    ],
    allowIntrospection: true,
    allowGraphiQL: true,
    schemaOptions: { ...subscriptions, ...liveSchema },
    context: { pubSub },
    extraPlugins: [useLiveQuery({ liveQueryStore })],
  })

  // Start

  fastify.listen({ port })

  fastify.ready(() => {
    console.log(chalk.italic.dim('Took ' + (Date.now() - tsServer) + ' ms'))
    const on = chalk.magenta(`http://localhost:${port}${apiRootPath}`)
    const webServer = chalk.green(`http://localhost:${port}`)
    const apiServer = chalk.magenta(`http://localhost:${port}`)
    console.log(`Web server started on ${webServer}`)
    console.log(`API serving from ${apiServer}`)
    console.log(`API listening on ${on}`)
    const graphqlEnd = chalk.magenta(`${apiRootPath}graphql`)
    console.log(`GraphQL serverless function endpoint at ${graphqlEnd}`)
  })

  process.on('exit', () => {
    fastify.close()
  })
}

serve()

Note: I just realized that this example doesn't mix both LQ and Subs due to the way I set the schemaOptions. But both do work independently. Hence, why need a way to merge these into there schema in the next iteration.

Important here is to "allow" subscriptions, introspection and graphiql.

// api/src/graphql/liveSchema.ts

import { astFromDirective } from '@graphql-tools/utils'
import { GraphQLLiveDirective } from '@n1ru4l/graphql-live-query'
import { InMemoryLiveQueryStore } from '@n1ru4l/in-memory-live-query-store'

export const liveQueryStore = new InMemoryLiveQueryStore()

type Bid = {
  amount: number
}

type Auction = {
  id: string
  title: string
  bids: Bid[]
}

const auctions: Auction[] = [
  { id: '1', title: 'Digital-only PS5', bids: [{ amount: 100 }] },
]

export const liveSchema = {
  typeDefs: [
    /* GraphQL */ `
      type Query {
        auction(id: ID!): Auction
      }
      type Auction {
        id: ID!
        title: String!
        highestBid: Bid
        bids: [Bid!]!
      }
      type Bid {
        amount: Int!
      }
      type Mutation {
        bid(input: BidInput!): Bid
      }
      input BidInput {
        auctionId: ID!
        amount: Int!
      }
    `,
    astFromDirective(GraphQLLiveDirective),
  ],
  resolvers: {
    Query: {
      auction: (_, { id }) => auctions.find((a) => a.id === id),
    },
    Mutation: {
      bid: async (_, { input }) => {
        const { auctionId, amount } = input

        const index = auctions.findIndex((a) => a.id === auctionId)

        const bid = { amount }

        auctions[index].bids.push(bid)

        liveQueryStore.invalidate(`Auction:${auctionId}`)

        return bid
      },
    },
    Auction: {
      highestBid: ({ bids }: Auction) => {
        const [max] = bids.sort((a, b) => b.amount - a.amount)

        return max
      },
    },
  },
}

and Subscriptions

// api/src/graphql/subscriptions.ts

import { createPubSub } from '@graphql-yoga/node'

export const pubSub = createPubSub<{
  newMessage: [payload: { from: string; body: string }]
}>()

export const subscriptions = {
  typeDefs: [
    /* GraphQL */ `
      type Subscription {
        countdown(from: Int!, interval: Int!): Int!
      }
      type Query {
        room(id: ID!): [Message!]!
      }

      type Mutation {
        send(input: SendMessageInput!): Message!
      }

      type Subscription {
        newMessage(roomId: ID!): Message!
      }

      type Message {
        from: String
        body: String
      }

      input SendMessageInput {
        roomId: ID!
        from: String!
        body: String!
      }
    `,
  ],
  resolvers: {
    Query: {
      room: () => [],
    },
    Mutation: {
      send: (_, { input }, { pubSub }) => {
        const { roomId, ...newMessage } = input
        console.log('newMessage', newMessage)
        console.log('roomId', roomId)

        pubSub.publish('newMessage', roomId, newMessage)

        return newMessage
      },
    },
    Subscription: {
      countdown: {
        async *subscribe(_, { from, interval }) {
          for (let i = from; i >= 0; i--) {
            await new Promise((resolve) =>
              setTimeout(resolve, interval ?? 1000)
            )
            yield { countdown: i }
          }
        },
      },
      newMessage: {
        subscribe: (_, { roomId }, { pubSub }) =>
          pubSub.subscribe('newMessage', roomId),
        resolve: (payload) => payload,
      },
    },
  },
}

Next Steps

There are many next steps to support realtime and GraphQL Subscriptions and Live Queries.

• figure out web side needs for Apollo Client
• What is the DX and how best to organize Subscription and LiveQuery types and resolvers

[dthyresson]

Have started the work to merge in project subscriptions into the over schema and resolvers.

[dthyresson]

I have subscriptions and live queries running in a test app with this PR.

Server File Setup

Note here that you'll import a glob of subscriptions just like you'd do with RedwoodDirectives.

import path from 'path'

import { useLiveQuery } from '@envelop/live-query'
import { astFromDirective } from '@graphql-tools/utils'
import { GraphQLLiveDirective } from '@n1ru4l/graphql-live-query'
import chalk from 'chalk'
import { config } from 'dotenv-defaults'
import Fastify from 'fastify'
import { OperationTypeNode } from 'graphql'

import {
  coerceRootPath,
  redwoodFastifyWeb,
  redwoodFastifyAPI,
  redwoodFastifyGraphQLServer,
  DEFAULT_REDWOOD_FASTIFY_CONFIG,
} from '@redwoodjs/fastify'
import { getPaths, getConfig } from '@redwoodjs/project-config'

import directives from 'src/directives/**/*.{js,ts}'
import sdls from 'src/graphql/**/*.sdl.{js,ts}'
import services from 'src/services/**/*.{js,ts}'
import subscriptions from 'src/subscriptions/**/*.{js,ts}'

import { liveQueryStore } from 'src/services/auctions/auctions'

import { logger } from './lib/logger'
async function serve() {
  // Load .env files
  const redwoodProjectPaths = getPaths()
  const redwoodConfig = getConfig()

  const apiRootPath = coerceRootPath(redwoodConfig.web.apiUrl)
  const port = redwoodConfig.web.port

  const tsServer = Date.now()

  config({
    path: path.join(redwoodProjectPaths.base, '.env'),
    defaults: path.join(redwoodProjectPaths.base, '.env.defaults'),
    multiline: true,
  })

  console.log(chalk.italic.dim('Starting API and Web Servers...'))

  // Configure Fastify
  const fastify = Fastify({
    ...DEFAULT_REDWOOD_FASTIFY_CONFIG,
  })

  await fastify.register(redwoodFastifyWeb)

  await fastify.register(redwoodFastifyAPI, {
    redwood: {
      apiRootPath,
    },
  })

  await fastify.register(redwoodFastifyGraphQLServer, {
    loggerConfig: {
      logger: logger,
      options: { query: true, data: true, level: 'trace' },
    },
    graphiQLEndpoint: '/yoga',
    sdls,
    services,
    directives,
    subscriptions,
    allowedOperations: [
      OperationTypeNode.SUBSCRIPTION,
      OperationTypeNode.QUERY,
      OperationTypeNode.MUTATION,
    ],
    allowIntrospection: true,
    allowGraphiQL: true,
    schemaOptions: { typeDefs: [astFromDirective(GraphQLLiveDirective)] },
    extraPlugins: [useLiveQuery({ liveQueryStore })],
  })

  // Start

  fastify.listen({ port })

  fastify.ready(() => {
    console.log(chalk.italic.dim('Took ' + (Date.now() - tsServer) + ' ms'))
    const on = chalk.magenta(`http://localhost:${port}${apiRootPath}`)
    const webServer = chalk.green(`http://localhost:${port}`)
    const apiServer = chalk.magenta(`http://localhost:${port}`)
    console.log(`Web server started on ${webServer}`)
    console.log(`API serving from ${apiServer}`)
    console.log(`API listening on ${on}`)
    const graphqlEnd = chalk.magenta(`${apiRootPath}graphql`)
    console.log(`GraphQL serverless function endpoint at ${graphqlEnd}`)
  })

  process.on('exit', () => {
    fastify.close()
  })
}

serve()

Subscriptions

• put in api/src/subscriptions like you would Redwood Directives
• we have the concept of a redwoodSubscription and can make a generator for it like directives -- or g realtime and have the option to setup a subscription of live query perhaps

A subscription file can be

import gql from 'graphql-tag'

export const schema = gql`
  type Subscription {
    countdown(from: Int!, interval: Int!): Int!
  }
`

const countdown = {
  countdown: {
    async *subscribe(_, { from, interval }) {
      for (let i = from; i >= 0; i--) {
        await new Promise((resolve) => setTimeout(resolve, interval ?? 1000))
        yield { countdown: i }
      }
    },
  },
}

export default countdown

or for a newMessage

import { createPubSub } from '@graphql-yoga/node'
import gql from 'graphql-tag'

import { logger } from 'src/lib/logger'

export const pubSubNewMessage = createPubSub<{
  newMessage: [payload: { from: string; body: string }]
}>()

export const schema = gql`
  type Subscription {
    newMessage(roomId: ID!): Message!
  }
`

const newMessage = {
  newMessage: {
    subscribe: (_, { roomId }) => {
      logger.debug({ roomId }, 'newMessage subscription')

      return pubSubNewMessage.subscribe(roomId)
    },
    resolve: (payload) => {
      logger.debug({ payload }, 'newMessage subscription resolve')

      return payload
    },
  },
}

export default newMessage

Define SDL types

Here the rooms.sdl.ts defines the Message type used in the subscription and the mutation to send a new message

export const schema = gql`
  type Message {
    from: String
    body: String
  }

  type Query {
    room(id: ID!): [Message!]! @skipAuth
  }

  input SendMessageInput {
    roomId: ID!
    from: String!
    body: String!
  }

  type Mutation {
    send(input: SendMessageInput!): Message! @skipAuth
  }
`

Services

The api/src/services/rooms/rooms gets in in memory pubSub from the subscription and when sending a new message mutation, publishes onto pub sub

import { logger } from 'src/lib/logger'
import { pubSubNewMessage } from 'src/subscriptions/newMessage/newMessage'

export const room = ({ id }) => [id]

// important to be async!
export const send = async ({ input }) => {
  logger.debug({ input }, 'send input')

  const { roomId, ...newMessage } = input

  pubSubNewMessage.publish(roomId, newMessage)

  return input
}

Live Queries

The DX isn't 100% yet because the two parts to the server and yoga setup are:

• adding the live query directive to the graphql schema (done via schemaOptions in this example)
• adding the useLiveQuery plugin via extraPlugins
• Note that this useLiveQuery is using the in memory store created in auctions
• I could see a useRedwoodLiveQueryPlugin that does both
• Otherwise, the sdl and services are pretty standard

SDL Types

Here is an auctions.sdl.ts with basic query and mutation for making a bid and getting an auction

export const schema = gql`
  type Query {
    auction(id: ID!): Auction @skipAuth
  }

  type Auction {
    id: ID!
    title: String!
    highestBid: Bid
    bids: [Bid!]!
  }

  type Bid {
    amount: Int!
  }

  type Mutation {
    bid(input: BidInput!): Bid @skipAuth
  }

  input BidInput {
    auctionId: ID!
    amount: Int!
  }
`

Services

Here, there is a collection on auctions and can fetch an auction and make a bid on an auction.

When a bid is made, the Auction key is invalidated in the live query memory store.

import { InMemoryLiveQueryStore } from '@n1ru4l/in-memory-live-query-store'

import { logger } from 'src/lib/logger'

export const liveQueryStore = new InMemoryLiveQueryStore()

const auctions = [
  { id: '1', title: 'Digital-only PS5', bids: [{ amount: 100 }] },
]

export const auction = async ({ id }) => {
  const foundAuction = auctions.find((a) => a.id === id)
  logger.debug({ id, auction: foundAuction }, 'auction')
  return foundAuction
}

export const bid = async ({ input }) => {
  const { auctionId, amount } = input

  const index = auctions.findIndex((a) => a.id === auctionId)

  const bid = { amount }

  auctions[index].bids.push(bid)
  logger.debug({ auctionId, bid }, 'Added bid to auction')

  const key = `Auction:${auctionId}`
  liveQueryStore.invalidate(key)

  logger.debug({ key }, 'Invalidated auction key in liveQueryStore')

  return bid
}


export const Auction = {
  highestBid: (obj, { root }) => {
    const [max] = root.bids.sort((a, b) => b.amount - a.amount)

    logger.debug({ obj, root }, 'highestBid')

    return max
  },
}

[replay-io]

18 replays were recorded for e439eb7.

0 Failed

18 Passed

• useAuth hook, auth redirects checks
• Check that a specific blog post is prerendered
• Check that about is prerendered
• Check that homepage is prerendered
• Check that meta-tags are rendering the correct dynamic data
• Check that rehydration works for page not wrapped in Set
• Check that rehydration works for page with Cell in Set
• Check that rehydration works for page with code split chunks
• Check that you can navigate from home page to specific blog post
• Waterfall prerendering (nested cells)
• RBAC: Admin user should be able to delete contacts
• RBAC: Should not be able to delete contact as non-admin user
• Smoke test with dev server
• Smoke test with rw serve
• Loads Cell mocks when Cell is nested in another story
• Loads Cell Stories
• Loads MDX Stories
• Mocks current user, and updates UI while dev server is running

View test run on Replay ↗︎

[jtoar]

@dthyresson and I talked about this one; we're synced up on concerns and next steps and want to get this into main so development can keep going on other milestones.

[dthyresson]

woohoo