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.