Apollo Server 3.0 Roadmap

[abernix]

👋😃

This issue is to raise awareness into new developments and ideas for Apollo Server 3.x including any related, incremental steps which are worth addressing along the way. Some of this is likely to change, but we're very excited to start thinking about the next steps for Apollo Server, and I hope to share some of that excitement with you.

Since it was released last July, the number of Apollo Server 2.x installations have more than doubled so there are a lot of new learnings worth taking away from that growth. In Apollo Server 3.x, we want to continue to build on the feedback we've received from the community, and improve the project's extensibility through schema composition, federation and other pluggable plumbing.

While I realize there are likely many avenues worth exploring, I hope this issue can rally some constructive conversation which will help guide more specific designs. In time, several major bullet-points below will surface as new, dedicated issues (or develop within existing issues, where appropriate), but in terms of the high-level goals, here's what we're thinking:

• Plug-ability and extensibility.

  Apollo Server aims to provide sensible and opinionated defaults, while allowing customization and integrations. Some existing functionality could be abstracted out and live on as plugins, letting those who want a more vanilla approach to have it. Evolving the experimental plugin API, which surfaced in Apollo Server 2.2, should encourage those patterns and help build a vibrant plugin ecosystem that caters to specific needs — e.g. logging, metric reporting, authentication, error handling, etc. Most of this is possible with the existing plugin API, but we anticipate the implementation of some new integration hooks. 2008, 1795

• Introduce patterns for modular GraphQL service development.

  GraphQL services combine schema construction and its request processing into a single unit, decoupled from the framework and compatible with tooling. They can be moved to different environments (e.g. between development and production) and tested without a complete server. These are new concepts, so we suspect we might see these in experimental phases prior to 3.x.

• Improve integration with existing frameworks.

  A GraphQL service can run in many environments and Apollo Server integrates with express, koa, AWS Lambda, Azure, and more. Several popular issues have shown us that we're taking an over-opinionated/under-configurable approach. We need to reconsider the applyMiddleware approach and use patterns that are more natural for particular environments. 2244, 1308, 1646, 1117

• Be lean and courteous to non-Node.js environments.

  It should be possible to configure Apollo Server in a way that it can execute in "no-frills" JavaScript engines which offer different functionality than the complete Node.js runtime. Examples of such runtimes are "worker" deployments (i.e. Cloudflare Workers, Fly Edge Apps, etc.) which run on "bare" V8 or other JavaScript engines. Some progress has been made on this already, but we could do more. We should prefer native Node.js APIs when they're available, but that luxury should be abstracted away in a manner which can be polyfilled with alternative implementations or have its functionality limited gracefully when unavailable. 2162 1572

• Unify diverging request pipelines.

  Apollo Server supports WebSockets out of the box. However, its execution is disconnected from the main request pipeline. This divergence means operations over WebSockets won't benefit from the parsed/validated document cache, Apollo Platform support, plugin life-cycle hooks, etc. While HTTP makes sense for many cases, Apollo Server should be able to "speak GraphQL" easily over other transports and by unifying the two current request pipelines, we hope to make the main request pipeline more flexible.

• Federation support.
  Within one graph, which composes multiple GraphQL services together and provides a single entry-point, individual GraphQL services are served by Apollo Server instances which support their portion of the graph. For GraphQL services, the plugin API should provide the integration points which allow the appropriate changes to a schema and allow them to participate in a federated architecture. These same hooks should prove to be useful hooks for additional plugin functionality which relates to schema building and transformation.

On behalf of the Apollo team, I hope this provides some exciting and useful insight into what we're thinking as we move toward a 3.x. It's entirely possible that we're missing important items here, but we felt it was best to get the discussion planted. Feel free to comment with anything else you feel would be important for this release.

[dylang]

(Thanks for all of you hard work on this! If my items are not relevant I'm happy to remove/move to tickets for the appropriate repos.)

The Apollo Server option called context runs once per request, not once per graphql query. This means, with batching, all of the graphql calls in that batch share the same context object created by this function.

It would be helpful if the context option was run once per graphql query and not request.

[dylang]

Tracing today goes as deep as the resolvers. It would be helpful if Apollo Server provided user-level methods to provide tracing details even deeper, such as tracking the database and REST calls made in the resolvers.

Ideally, the OpenTracing patterns would be followed.

[dylang]

tracing is a boolean read when Apollo Server starts and it adds tracing data to every graphql response. I don't know of a built-in way to toggle this, or prevent the tracing data from being sent to the client without a custom graphql extension to strip it out.

It might helpful for performance to enable tracing for things like Apollo Engine, but not including the tracing data in the HTTP response.

It might be helpful if there's an override, like a http header, for those times developers require tracing information sent to the client, such as investigating performance issues using the GraphQL playground feature.

[dylang]

Apollo Server config options are found at https://www.apollographql.com/docs/apollo-server/v2/api/apollo-server.html.

Not all options are documented, and some that are documented could benefit from a deeper dive or links to other places where developers can learn more about the config options.

It would be beneficial for developers if we could have a goal for v3 to have all configuration documented or linked to other places where useful information can be found.

A stretch goal from this may be documenting best practices for things like performance, memory usage, and security.

Config options not currently documented on that page

• modules?: GraphQLSchemaModule[];
• parseOptions?: GraphQLParseOptions;
• plugins?: PluginDefinition[];
• fieldResolver?: GraphQLFieldResolver<any, TContext>;
• dataSources?: () => DataSources<TContext>;

Examples of config could benefit from deeper documentation

debug: <Boolean>

Enables and disables development mode helpers. Defaults to true

• What are the development mode helpers and how do we use them to help us?
• Would it be a security or performance risk to enable this in production?
• Is it possible to enable this in production to investigate an issue?

validationRules: <Object>

Schema validation rules

• <Object> is not enough information here for somebody to make their own rules.
• What should we use this for?
• What happens if the rules are broken?

Note: The source code and TypeScript types are helpful to understand these, as well as the many open source projects, blog posts, and other parts of the documentation.

[FluorescentHallucinogen]

IMO, it would be a great idea to implement the previous roadmap before creating the new. 😜

I'm personally very interested in support of @live, @defer and @stream.

[schickling]

This looks great. Really looking forward to see this coming along!

It would be great to see how code-first frameworks such as nexus could work together with the idea of "modular GraphQL service development".

[abernix]

@dylang #2360 (comment)

The Apollo Server option called context runs once per request, not once per graphql query. This means, with batching, all of the graphql calls in that batch share the same context object created by this function. It would be helpful if the context option was run once per graphql query and not request.

In terms of breaking changes, this definitely seems like something worth considering for a major release. It's worth mentioning that this approach was initially by design on the premise that a performance win could be achieved through re-using dataloaders across multiple operations.

However, in practice we haven't seen it being recurrently problematic as batching is relatively underutilized, particularly one of the barriers to its adoption is that an entire batch is only as fast as its slowest operation. That said, I can't seem to recall this being opened in an issue so I'd highly encourage opening one to discuss what the implementation details might look like and how necessary important this might be.

There's some existing details on the matter in #1468 (comment) where @martijnwalraven discussed some of the current patterns which need to be improved. Some have been improved in the new request pipeline (#1795), but others, including this context-per-request matter are still outstanding.

Anyhow, maybe get an issue opened for this? (Or help locate an existing one?)

[jbaxleyiii]

@FluorescentHallucinogen we definitely want to support those directives as part of this work. In fact, the 3.0 roadmap is inspired by our first spike on defer last year which helped us to find the gaps in execution and transport configuration that the 3.0 looks to solve 😸

[abernix]

@dylang #2360 (comment)

Config options not currently documented on that page

• modules?: GraphQLSchemaModule[];
• parseOptions?: GraphQLParseOptions;
• plugins?: PluginDefinition[];
• fieldResolver?: GraphQLFieldResolver<any, TContext>;
• dataSources?: () => DataSources<TContext>;

These are great points, but I don't think we need to confine these to our roadmap. Some of the content for these options already exists and some of it is work in progress. It would be incredibly helpful if someone could open PRs to further define these (as noted, guided by the source code). Of particular note are also:

• The docs for data sources
• The in-progress docs for plugins
• parseOptions is relatively a straightforward pass-through.
• modules are somewhat experimental, mostly undocumented because we're still getting feedback, but all around could certainly be noted as such.

All great opportunities for contribution, pre 3.x!

[abernix]

@dylang #2360 (comment)

tracing is a boolean read when Apollo Server starts and it adds tracing data to every graphql response. I don't know of a built-in way to toggle this, or prevent the tracing data from being sent to the client without a custom graphql extension to strip it out.

It might helpful for performance to enable tracing for things like Apollo Engine, but not including the tracing data in the HTTP response.

By default, the tracing should only be included in the response if you've set tracing to true, not just when engine is true/enabled. Setting tracing to true is necessary for users who might still be using the Apollo Engine Proxy (which intercepts the tracing information from the extensions, transmits the metrics to Apollo Engine and strips these from the response). We now recommend using the built-in reporting in Apollo Server 2.x rather than this approach, which doesn't incur whatever penalty may exist from adding these to the response.

It might be helpful if there's an override, like a http header, for those times developers require tracing information sent to the client, such as investigating performance issues using the GraphQL playground feature.

Possibly! If you're suggesting programmatic enabling of tracing, I think that's worth considering but I don't think that needs be part of the v3 roadmap. I suspect this could be done via a plugin, and I think that once we move apollo-engine-reporting and apollo-tracing to use the new Plugin API (rather than graphql-extensions) it would be possible to even selectively enable that via an option or some sort of predicate function.

[abernix]

@FluorescentHallucinogen #2360 (comment)

Those features are still really important to us! The previous roadmap has them listed in the future section and they're still something we want to offer soon.

That said, we found bumps in the figurative "roads" that our last map guided us on, particularly when we went to start finalizing the work from #1287. That discovery made it clear that we needed to work on some of the issues we've identified above, particularly the work identified as Unify diverging request pipelines and Improve integration with existing frameworks.

[abernix]

@schickling #2360 (comment)

It would be great to see how code-first frameworks such as nexus could work together with the idea of "modular GraphQL service development".

Agree! My suspicion is that so long as nexus can generate SDL (it can), it should be able to participate as a GraphQL service within a federated graph. We'll have to explore this more as the details become more concrete.

[arnabkd]

I'm curious as to where Apollo is going in regards to schema first vs code first? See this blogpost by prisma:
https://www.prisma.io/blog/the-problems-of-schema-first-graphql-development-x1mn4cb0tyl3

[Ked57]

Hello guys, first I'd like to say you did an awesome work on the apollo-federation functionality. Still I ran into some problems and I believe many will, it's type and queries colision. We're trying to automaticaly stitch schemas from the generated SDL provided by prisma and some automaticaly generated types are begining to be a problem.

My point is, it would be awesome if the gateway referenced types with the name of the service first (ex service.type or service.query ) so we could ensure there's never going to be any type colision.

[jlarmstrongiv]

Improve integration with existing frameworks.

A GraphQL service can run in many environments and Apollo Server integrates with express, koa, AWS Lambda, Azure, and more. Several popular issues have shown us that we're taking an over-opinionated/under-configurable approach. We need to reconsider the applyMiddleware approach and use patterns that are more natural for particular environments. 2244, 1308, 1646, 1117

I had that exact problem, which led me to fork apollo-server-lambda to create my own apollo-server-agnostic.

While there’s more boilerplate code, having a version of ApolloServer that is not tied to any framework would give an escape hatch for code that is too tightly coupled or unsupported configurations. Just another possible solution to the problem ¯_(ツ)_/¯

[smolinari]

Thanks for the replies @abernix Jesse and @glasser David. I'll be so bold to reply myself, since I (also being presumptuous) think my post got the emotions going to motivate your replies.

I can't speak for everyone, and I never try to, so I'd like to say, I'm a bit less worried now. Thank you. But, only a bit. I'm sure this is a shared feeling though too.

My plans will be to continue to lurk the repo to watch the work being done and progress made, announcements said and if any are made.... promises kept (or at least clear effort to keep them). At the same time, I'll be doing the same over the next couple/ few months with one or two projects that look competitively promising.

The only other suggestion I'd like to make is to get back to a public plan of action (the road map). There doesn't need to be exact release dates, but there should be some semblance of timing and commitment on milestones, like in quarters, maybe? I think this was missing originally too to this post/ the project. I realize with a small team/ few resources, it's hard to make commitments, but I say, at least try, please. I know from other projects, it's not always making commitments perfectly that count, but showing the effort is made to try and make them happen. This is, after all, OSS. 👍

I'd also like to point out, and I think the discussion could get back to those topics, what I feel are important and needed developments of Apollo Server.

These features are (and not in any order of importance):

1. Federation. But, also with working subscriptions. I'll be honest, this feature is not seriously important to me currently, but in the future it will be. Put it this way, as you noted Jesse, it's the tool for large collaborative code bases. It's a development scaling mechanism. And, everyone's dream is to get to great scale, right? And not having full GraphQL functionality sort of seriously dampens dreams of using Apollo Server at scale (and especially for those who have reached it. These are people definitely leaving Apollo.....). Also, from another point of view....people that get to Apollo and see its initial potential, start using it, but also learn later, its scaling mechanism is missing features, that is a really big disappointment. That should be avoided at all costs.

2. Performance. This also goes in hand with the scaling dream too. When I look at the benchmarks linked above and also read about other experiences with higher loads than we are having currently, I'm hoping this won't be our concern. But, it's hard to not think it will be.

3. Websocket support. This seems to be all over the place currently and one of the main concerns that got me looking at alternatives. I'd like to see this feature as one of the first "attack points" in the roadmap. This should be just a matter of config for the server user/ consuming dev/ team.

4. An Exo-wish above and beyond any feature set. Get the excitement going again for the server and client combo. The client development seems to have taken most resources and gotten further faster (except I feel the concentration on React is overkill... just sayin 😄 ) I'd like to see that same kind of attention or maybe even split attentions (aka resources) on both packages more evenly, with someone (aka the leader) doing more community work too for both, together.... i.e. talking to what has happened, is going to happen and will happen to make sure the community is being taken along the journey for "Apollo". 😁

As you can see, my wish list isn't all too long. I'd love to see others' wishes too.

Apollo is a decent solution and could easily become the clear leader quickly again (from my perspective). I'm still at a "cross-my-fingers" point and would like to be in a "this-is-going-awesome" point of view for Apollo Server. I hope your work and effort along with the community's, will get us there. I'll try my best to help too, where I can.

Thanks again for the explanations. As I said, I am feeling a bit better. 😃 👍

Scott

[quant-daddy]

The only other suggestion I'd like to make is to get back to a public plan of action (the road map). There doesn't need to be exact release dates, but there should be some semblance of timing and commitment on milestones, like in quarters, maybe? I think this was missing originally too to this post/ the project. I realize with a small team/ few resources, it's hard to make commitments, but I say, at least try, please. I know from other projects, it's not always making commitments perfectly that count, but showing the effort is made to try and make them happen. This is, after all, OSS.

We need this!

[wabrit]

Another vote for subscription support in Apollo Federation; getting close to the point where we need to support a federated model and, regardless of the appeal of the Apollo Federation approach, not supporting subscriptions is a deal breaker and @graphql-tools/stitch would be the way to go.

[TechTeam12]

Will V3 apollo-server-lambda be designed to support both V1 and V2 of the HTTP API payload format?
https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html

[glen-84]

Will V3 apollo-server-lambda be designed to support both V1 and V2 of the HTTP API payload format?
https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html

There won't be any integration packages in v3:

Removal of all of the apollo-server-<integration> packages in favor of the default HTTP transport, along with copy-paste snippets in the documentation for other common patterns to deliver production-ready, out-of-the-box experiences.

(ref)

[glasser]

As a follow-up to my last comment: my top priority right now is coming up to speed on the current state of the Apollo Server project. This includes making a few important changes (see https://github.com/apollographql/apollo-server/milestone/55 for the next release milestone) as well as generally being on top of incoming issues and pull requests. (I didn't do myself any favors by going on vacation for a week right after starting, but I should catch up soon!) Once I feel a bit better informed, I plan to get back to this issue and Jesse's already existing Apollo Server 3 branch.

My guess is that the high level description of what AS3 will end up being will be less enabling the software to do new things, and more about removing things that make maintaining and improving AS challenging. Most of the changes will be focused on removing tight dependencies from AS on third-party software with their own release cycles (graphql-upload, graphql-subscriptions, graphql-playground, etc) so that we can focus on AS doing what it does best and those other projects doing what they do best. The goal of Apollo Server 3.0 will be much more about making it easy to do exciting things in AS 3.1, 3.2, 3.3, etc, rather than necessarily adding huge new paradigms itself. That said, more to come once all the low-hanging AS2 fruit is dealt with!

[Sytten]

I think at the bare minimum it needs to get rid of https://github.com/apollographql/subscriptions-transport-ws.
The rest works good enough, but subscriptions are a real pain right now (both client and server side).

[smolinari]

The goal of Apollo Server 3.0 will be much more about making it easy to do exciting things in AS 3.1, 3.2, 3.3, etc,

Awesome plan!!! Exciting is always good. Just please get a fair roadmap going for what you feel could come with the minor versions, let the community weigh in....... and off we go! 🚀 😁

Scott

[wmertens]

@Sytten subscriptions should be implemented with SSE, it's perfect for that and doesn't need any extra ports or servers. GraphQL only really uses one direction of the ws.

[nrobates]

Is there any real timeline or target date on when Federation will support subscriptions? This seems to be a fairly important need from people.

[glasser]

Status update on AS 3.0:

Since starting to actively maintain Apollo Server, my main goals have been to iterate quickly on new issues and pull requests with contributors, and to solve a serious startup error handling problem (#4981 destined for v2.22 very soon I hope).

Once v2.22 is out, my main Apollo Server focus will be getting Apollo Server 3 out the door. I have put off the serious deep dive research until this point; for example, I have not thoroughly studied the release-3.x branch that Jesse has been maintaining yet, nor have I even fully read the conversation on this issue.

The overall focus of Apollo Server 3.0 will be to decouple the apollo-server codebase from dependencies that make improving Apollo Server challenging. Packages like graphql-upload, subscriptions, playground, etc should have easy hooks to be integrated from the outside rather than having Apollo Server depend on a fixed version of the package from the inside. This might mean that upgrading to Apollo Server 3 itself might not be the most fulfilling experience, but hopefully it will enable 3.1, 3.2, 3.3 etc to be full of the features people have been waiting for.

As far as subscriptions itself goes, Apollo Server 2 has a superficial integration with subscriptions-transport-ws that doesn't tie in to the plugin system, federation, Studio reporting, etc. And subscriptions-transport-ws isn't even the best maintained package that solves this problem. So 3.0 will remove that integration. I do hope that we do the work to add subscription support to the Apollo server-side platform as a whole sometime soon, but I can't promise a timeline for that — that's a larger decision than just Apollo Server planning.

[JacoBass-work]

For those searching for a solution for subscriptions integration with Apollo Federation, it might be useful have a look at the following: https://www.youtube.com/watch?v=C5pSwLpjZM0&t=2s

[eliw00d]

I recently looked into server-side caching and was surprised to find out that invalidation was not included. However, in the Apollo Server 3.x documentation, there is this note:

Invalidation of whole-query cache through cache tags with CDN integration.

Does this mean that Apollo Server 3.x, out of the box, will be able to invalidate cache based on mutations similar to Apollo Client?

[glasser]

We now have a release PR tracking the 3.0 release: #5262

The rest of what we're finishing up as part of 3.0 is tracked in this project. Note that one of those cards (#5090) includes getting the ROADMAP.md in the repo up to date (it is currently quite dated).

I'm going to close this issue now, since the immediate AS3 roadmap is now part of the release PR/project, and the future roadmap has not yet been written.

[MWhite-22]

@Sytten subscriptions should be implemented with SSE, it's perfect for that and doesn't need any extra ports or servers. GraphQL only really uses one direction of the ws.

@wmertens Could you please expand on this? I am running in to a lot of problems with my planned ws use cases via apollo-server, and you appear to know of alternative solutions. Any help would be greatly appreciated.

[wmertens]

I have a WiP sseLink that opens an SSE channel when a subscription is requested.

• Only one channel is opened for all subscriptions.
• It is made secure by requiring a secret URL param to reconnect, and a different secret token to request a subscription.
  • You can reconnect to the channel via the secret URL, which disconnects the old connection and keeps sending you subscription results
  • To subscribe to new things, you pass the subscribe token that you get when you open the SSE channel
• A subscription query gets the token and an id added, and the server will send all subscription results into the channel tagged with the id.
• So the server gets the subscription via the normal graphql endpoint, and can do regular authentication/authorization on it

The link is mostly done but needs handling of edge cases, network loss etc.

You can actually open multiple SSE channels if you like, just a matter of passing the right token.