GraphQL Workers Subscriptions

2023

A library/framework built on Cloudflare Workers providing distributed, topic-based GraphQL subscriptions.

We built this library at BubblyDoo to allow us to use GraphQL subscriptions in a distributed, serverless environment. It solves the problem of needing to have a single server to handle subscriptions, which is not possible in a serverless environment. The library uses Cloudflare Workers, Durable Objects and D1 to provide a fully serverless solution for GraphQL subscriptions.

It supports subscription payload filtering (powered by in-database SQLite JSON matching).

Visit the demo (open two tabs, one to "Say" and one to "Listen")

It allows us to write code like this:

mutation Say {
  greet(greeting: "hi!")
}

subscription Listen {
  greetings {
    greeting
  }
}

subscription ListenToHi {
  greetings(greeting: "hi!") {
    greeting
  }
}

export const schema = makeExecutableSchema({
  typeDefs: /* GraphQL */ `
    type Greeting {
      greeting: String
    }
    type Subscription {
      greetings(greeting: String): Greeting
    }
    type Mutation {
      greet(greeting: String!): String
    }
  `,
  resolvers: {
    Mutation: {
      greet: async (root, args, context, info) => {
        context.publish("GREETINGS", {
          greetings: { greeting: args.greeting },
        });
        return "ok";
      },
    },
    Subscription: {
      greetings: {
        subscribe: subscribe("GREETINGS", {
          filter: (root, args, context, info) => {
            return args.greeting
              ? { greetings: { greeting: args.greeting } }
              : {};
          },
        }),
      },
    },
  },
});

As we're no longer actively using GraphQL, it would be nice to rewrite this in a more generic way to support other protocols as well, such as tRPC.

There were quite some challenges in getting this to work. For example, we had resort to some

"hacks"

to integrate it in the existing GraphQL ecosystem, as subscription handlers are supposed to be async generators.

This library was made together with my colleague

Izidor

🔧 GraphQL🔧 Cloudflare Workers🔧 WebSockets

export const schema = makeExecutableSchema({ typeDefs: /* GraphQL */ ` type Greeting { greeting: String } type Subscription { greetings(greeting: String): Greeting } type Mutation { greet(greeting: String!): String } `, resolvers: { Mutation: { greet: async (root, args, context, info) => { context.publish("GREETINGS", { greetings: { greeting: args.greeting }, }); return "ok"; }, }, Subscription: { greetings: { subscribe: subscribe("GREETINGS", { filter: (root, args, context, info) => { return args.greeting ? { greetings: { greeting: args.greeting } } : {}; }, }), }, }, }, });