Major update: Apollo Server 5 migration with breaking changes

[icebob]

Summary

This PR upgrades the Moleculer Apollo Server integration from Apollo Server 2 to Apollo Server 5, bringing significant modernization and breaking changes.

Breaking Changes

• Apollo Server 5: Complete migration from Apollo Server 2 to 5
• Node.js Requirements: Now requires Node.js >= 20.x.x (updated from >= 10.x)
• File Upload Removal: Removed GraphQL file upload support (Apollo Server 3+ no longer supports it)
• Healthcheck Removal: Built-in healthcheck endpoint removed (Apollo Server 4+ no longer supports it)
• WebSocket Subscriptions: Rewritten subscription implementation from graphql-subscriptions to graphql-ws
• GraphQL Playground: Replaced with Apollo Sandbox (Apollo Server 3+ default)

Major Updates

• Modern Tooling: Migrated from legacy ESLint config to flat config format
• GitHub Actions: Updated CI workflow to use latest actions (v4) and test on Node.js 20.x, 22.x, 24.x
• Dependencies: Updated all dependencies to latest compatible versions
• TypeScript: Improved TypeScript definitions in index.d.ts
• Testing: Comprehensive integration test suite rewrite
• Examples: Updated all examples to work with Apollo Server 5
• Async Methods: Made makeExecutableSchema and generateGraphQLSchema methods async for better async/await support

Removed Features

• File upload examples and documentation
• Legacy Apollo Server 2/3 configuration options
• Health check examples (examples/health/)
• Upload examples (examples/upload/)

Files Changed

• Complete rewrite of core service logic in src/service.js
• Updated src/ApolloServer.js for Apollo Server 5 compatibility
• Modernized configuration files (eslint.config.js, prettier.config.js)
• Enhanced examples with Apollo Server 5 patterns
• Comprehensive test suite updates
• Updated TypeScript definitions for async method signatures

This is a major version bump (0.4.0) due to the breaking changes introduced by the Apollo Server 5 migration.

[kthompson23]

@icebob This is awesome!

A little while ago I discovered a race condition in prepareGraphQLSchema(). Since the call to this.apolloServer.stop() is async, a second request can enter prepareGraphQLSchema(). During peak times we noticed 502 errors.

We're running a local patch where we wrapped prepareGraphQLSchema() with an async mutex, which resolved the issue. I don't know if you can think of another way to solve that problem but I could open a PR against the master branch or I could send you our patch.

[icebob]

@kthompson23 please share your solution

[kthompson23]

@kthompson23 please share your solution

@icebob Here's my branch.
master...kthompson23:moleculer-apollo-server:mutex-lock-schema-rebuild

I added the async-mutex package and wrapped the schema rebuild in the prepareGraphQLSchema method with a mutex.

[icebob]

I added the async-mutex package and wrapped the schema rebuild in the prepareGraphQLSchema method with a mutex.

@kthompson23 Are there any reason of using async-mutex library instead of a simple "preparing: boolean` property what I set to true at the fbeginning of the methods and return if true to avoid parallel executions?
Because I've checked the package and it's a 100KB package for solving a simple problem

[kthompson23]

I added the async-mutex package and wrapped the schema rebuild in the prepareGraphQLSchema method with a mutex.

@kthompson23 Are there any reason of using async-mutex library instead of a simple "preparing: boolean` property what I set to true at the fbeginning of the methods and return if true to avoid parallel executions? Because I've checked the package and it's a 100KB package for solving a simple problem

@icebob The issue is that prepareGraphQLSchema is async and stops the apollo server. When the apollo server is stopped, we can't handle any other requests until the schema is rebuilt and the apollo server is started. A boolean could stop other requests from attempting to rebuild the schema/shut down the apollo server but it can't pause execution until the schema is rebuilt and the apollo server started. This race condition results in 504 errors.

[icebob]

@kthompson23 do you have any idea how I can reproduce this situation in integration tests?

[kthompson23]

@kthompson23 do you have any idea how I can reproduce this situation in integration tests?

I'm not entirely sure. When I first "audited" this code, I decided to add the mutex because I thought we were doing redundant work. Two requests can enter prepareGraphQLSchema, which results in the schema being rebuilt twice and the graphql.schema.updated broker broadcast firing twice. I was pleasantly surprised when this resolved the 504 errors we were experiencing.

What if you first called invalidateGraphQLSchema(), then make two or more graphql requests in parallel?