The changes noted within this
vNEXT
section have not been released yet. New PRs and commits which introduce changes should include an entry in thisvNEXT
section as part of their development. When a release is being prepared, a new header will be (manually) created below and the appropriate changes within that release will be moved into the new section.
- Nothing yet! Stay tuned!
- Introduce
@core/v0.2
support with thefor:
directive argument which was introduced to the core specification in specs-core#9. Supergraphs (which are@core
schemas in the way they're implemented) which were generated with a composer tool (e.g.,rover
) that produces@core
schemas with thev0.1
specification are still valid and backwards compatible. The newly introducedfor:
argument allows a@core
directive to specify its criticality to the gateway (or any consumer). Thefor:
argument is optional - its absence means that the directive requires no additional support from the consumer. Its two available optionsEXECUTION
andSECURITY
both require explicit support from the consumer, else the consumer should fail to start / update to this unsupported schema. For more information on supergraphs see our documentation or learn how to generate them in our federation quickstart. PR #957
- Reverts PR #159 which propogated subgraph execution errors directly to the client. While desirable in practice, this somewhat recent introduction would seem to beg for a different implementation, given that the pain points of introducing it seem to be currently outweighing the gains. Happy to revisit this with additional feedback on the tracking issue that has been opened to re-visit this. In the interim, we are offering a release that reverts this change. Issue #974 Apollo Server Issue #5550 PR #982
- Only changes to tests related to the change in
@apollo/federation@0.29.0
which renamedbuildFederatedSchema
tobuildSubgraphSchema
. (See PR #915 for details.)
- OpenTelemetry will now include the GraphQL
operationName
in span attributes, following up on the initial implementation introduced in v0.31.0 via #836 PR #942
- In
RemoteGraphQLDataSource
, if the subgraph response has acache-control
header, use it to affect the current request's overall cache policy. You can disable this by passinghonorSubgraphCacheControlHeader: false
to theRemoteGraphQLDataSource constructor
. This feature is only enabled when your subgraph is running Apollo Server 3.0.2 or later. PR #870 Related docs PR - Provide the full incoming
GraphQLRequestContext
toGraphQLDataSource.process
, as well as akind
allowing your implementation to differentiate between requests that come from incoming GraphQL operations, health checks, and schema fetches. PR #870 Issue #419 Issue #835
- Narrow
graphql
peer dependency to a more fitting range^15.4.0
based on our current usage of the package. This requirement was introduced by, but not captured in, changes within the recently released@apollo/gateway@0.35.0
. As such, this change will be released as apatch
since the breaking change already accidentally happened and this is a correction to that oversight. PR #913
- Fixes bug where one
onSchemaChange
listener throwing would prevent otheronSchemaChange
listeners from being notified. PR #738 - Adds
onSchemaLoadOrUpdate
method to register listeners for schema load and updates, and to receive both the API schema and the core supergraph SDL.onSchemaChange
has been deprecated in favor of this method. Note thatonSchemaChange
listeners are not notified when loading schemas from static gateway configurations, whileonSchemaLoadOrUpdate
listeners are notified. PR #738
- Change default managed federation mechanism over to use Apollo's new Uplink service. This service handles composition and sends the entire supergraph to the gateway. Previously the gateway was responsible for downloading each service's SDL from GCS and handling the composition itself. If you have any issues trying to use this new behavior, you may use the gateway config option
schemaConfigDeliveryEndpoint: null
to continue using the previous mechanism for the time being. If you were previously setting theexperimental_schemaConfigDeliveryEndpoint
config option, you will need to update the name of the option itself (or you can remove it entirely if you were using Apollo's Uplink service). PR #881 - Introduce support for removing @inaccessible elements from the API schema. PR #807
- Call
toAPISchema
within the try/catch block inloadStatic
. PR #894 - Remove
query
andvariables
from downstream subgraph error extensions, as well as path from the error itself in the final response. This affects specifically errors with the codeDOWNSTREAM_SERVICE_ERROR
. Themessage
andserviceName
will continue to exist on the error. These can also be redacted (within ApolloServer) usingformatError
or thewillSendResponse
anddidEncounterError
plugin hooks. If you wish to bring back the existing behavior you may change your downstream service implementation to addquery
,variables
, andpath
(all of which are available to the downstream service; on Apollo Server, this can be done with a plugin that implementsdidEncounterError
andwillSendResponse
hooks that pluck the properties from therequestContext
and put them back on theextensions
. PR #900
- Only changes in the similarly versioned
@apollo/federation
(v0.26.0) package.
- This release updates dependencies so that it will support the final release of Apollo Server 3 when it is released. (Since 0.29, it has supported preview releases of Apollo Server 3.) There are no code changes.
- Move otel dependencies from
peerDependencies
to actualdependencies
. Also rename otel trace labels to@apollo/gateway/0.31.0
(or whatever the current version installed happens to be) PR #848
- OpenTelemetry instrumentation. PR #836
- Send error reports to a configurable endpoint when providing the
APOLLO_OUT_OF_BAND_REPORTER_ENDPOINT
env variable. Using the Apollo URLhttps://uplink.api.apollographql.com/monitoring
is recommended unless you have a custom configuration. Reports will only be sent if the env variable is set. PR #777
- More work towards compatibility with Apollo Server 3 preview releases. PR #822
- This release is intended to be compatible with preview releases of Apollo Server 3. The
apollo
option toApolloGateway.load
now can accept the signature sent by AS2 (which always includesgraphVariant
) or AS3 (which never does), and the dependencies on Apollo Server packages allow for preview releases as well as the AS2 versions. (However, it was not quite enough for AS3 compatibility; see 0.29.1 above.) PR #819 PR #819
- Fix plan querying a subgraph with an interface it doesn't know due to directives PR #805 Issue #801
- Take subtypes into account when matching type conditions to extract representations. PR #804
- Expand the range of supported
node
versions in the package'sengines
specifier to include the now-tested Node.js16
. PR #713
- Update version of
@apollo/query-planner
which was uninstallable due to a missing dependency. Related PR: PR #709
- Fix query plans missing fields in some situations involving nested type conditions. PR #652 Issue #396
- Fix condition would could result in duplicate fetches within query plans. PR #671
- Update
apollo-graphql
dependency which resolves a missing dependency (sha.js
) within that package. PR #699
- Avoid small potential performance concern/observation introduced in v0.21.0 which unnecessarily
JSON.stringify
'd the same object twice during requests to upstream subgraphs. PR #673 - Allow passing a function to the
introspectionHeaders
field when constructing anApolloGateway
instance. This allows for producing dynamic introspection headers per request. PR #607 - Will no longer calculate the automated persisted query (APQ) hash when
apq
is not set totrue
on theRemoteGraphQLDataSource
. PR #672
- Allow passing a function to the
introspectionHeaders
field when constructing anApolloGateway
instance. This allows for producing dynamic introspection headers per request. PR #607 - Updates
@apollo/query-planner
dependency to v0.1.1, which no longer depends on@apollo/query-planner-wasm
. PR #643
- Re-introduce TypeScript query planner to the gateway. This change should effectively be an implementation detail - it's undergone extensive testing to ensure compatibility with current query plans. PR #622
- BREAKING - All references to CSDL within the gateway have been updated to its latest iteration
Supergraph SDL
which is very similar in spirit, but implements the currently-being-introduced core and join specs. This includes changes to recent external API additions like thecsdl
andexperimental_updateCsdl
gateway constructor options. PR #622 - Update query planner API. With the query planner back in TypeScript, we can modify the QP API in such a way that prevents double parsing and schema building. PR #628
- Improved query plan execution by pruning entities which are
undefined
or didn't match specified type conditions after a priorFetchNode
execution. After pruning, only the remaining entities will be fetched in the dependentFetchNode
execution. If NO entities remain, the request will not be made. PR #612
- Add support for an upcoming mechanism for fetching a graph's schema and configuration when using managed federation. In this release, the new mechanism is opt-in, and users shouldn't use enable it unless instructed by Apollo to do so. PR #458 PR #585
- Provide
context
as a fourth, optional argument toRemoteGraphQLDataSource.didEncounterError
. This is a non-breaking change which allows implementors to read and modify thecontext
object which is already similarly available in other hooks. PR #600
- deps(@apollo/query-planner-wasm
): Adjust the packaging to ensure that
dist/` packages were published by the CI publishing pipeline. PR #557
- deps(
@apollo/query-planner-wasm
): Fix an error caused by a lacking relatively prefix on the items inexports
, following up PR #270
- Re-publish with adjustment to
lerna.json
to ensure that the newly-introduced@apollo/query-planner
package (which wraps@apollo/query-planner-wasm
) is published by the release pipeline. This is important because@apollo/gateway
now depends on@apollo/query-planner
as of PR #453
- BREAKING: Make all
protected
gateway fields and methodsprivate
(exceptloadServiceDefinitions
). If you currently depend on the ability to override any of these currentlyprotected
members ofApolloGateway
please let us know by opening or commenting on an existing an issue on this repository. For additional context on whyloadServiceDefinitions
remainsprotected
(for now) please read the associated PR description and linked issue. PR #539 - deps(
@apollo/query-planner-wasm
): This dependency has been bumped to a version that emits an ECMAScript module (ESM) in addition to the current CommonJS (CJS) bundle. This may help facilitate interoperability with bundlers thwarted by the presence of the WASM module (.wasm
) within in this dependency since its inception and included in@apollo/gateway
sincev0.20.1
. PR #270 Issue #255
- Only changes in the similarly versioned
@apollo/federation
package.
- Adjust quoting on "invalid state" error message introduced in PR #452 to properly reveal the unknown state. PR #460
- If you are on v2.18 or v2.19 of Apollo Server, you should upgrade to Apollo Server v2.20 before upgrading to this version, or your Node process may not shut down properly after stopping your Apollo Server.. Code that calls
ApolloGateway.load
is now expected to callApolloGateway.stop
. If you don't do that and you're using managed federation orexperimental_pollInterval
, the background polling interval will now keep a Node process alive rather than allowing it to exit if it's the only remaining event loop handler. Generally,ApolloServer
is what callsApolloGateway.load
, and if you use at least v2.20.0 of Apollo Server,ApolloServer.stop()
will invokeApolloGateway.stop()
. There's a bit of a hack where ApolloGateway does the old behavior if it believes that it is being called by a version of Apollo Server older than v2.18.0. So if you are manually callingApolloGateway.load
from your code, make sure to callApolloGateway.stop
when you're done, and don't use this version with Apollo Server v2.18 or v2.19. PR #452 apollo-server Issue #4428 - Simplify startup code paths. This is technically only intended to be an internal restructure, but it's substantial enough to warrant a changelog entry for observability in case of any unexpected behavioral changes. PR #440
- Include original error during creation of
GraphQLError
indownstreamServiceError()
. PR #309 - Gateway accepts
csdl
for startup configuration, uses CSDL internally for schema object creation. PR #278 - Add
Promise<T>
generic type info to fix typescript errors PR #324 - Update apollo-server-* deps PR #325
- Update version of
@apollo/federation
- No changes, but please note that
v0.21.2
was a botched release, with no update to the@apollo/query-planner-wasm
package that was needed. If you're seeing an error similar toThis data graph is missing a valid configuration. unreachable
, please upgrade to at least this patch release.
- Whenever "AccessDenied" 403 error comes from Apollo, provide a useful error message indicating how to resolve the problem. PR #245
- Only changes in the similarly versioned
@apollo/federation
package.
- Fix
Cannot convert undefined or null to object
error which occurred when nullable variables were declared/used within an operation (i.e.query
) document butvariables
was undefined on the request. PR #167 Issue #196 - When using a custom
fetcher
on aRemoteGraphQLDataSource
, use that fetcher'sRequest
initialization in order to satisfy and of its own implementation details. This is necessary, for example, when usingmake-fetch-happen
. PR #188 Issue #191
- Adjust a
preinstall
script which was only intended to be executed by the monorepo tool-chain, not merely by installing the@apollo/gateway
package as a dependency in another project. PR #185 Issue #184
- Read managed federation configuration from the
apollo
option toApolloGateway.load
rather than the deprecatedengine
option, when available (ie, when running Apollo Server v2.18+), and update error messages referring to the old Engine and Graph Manager product names. PR #148 - FIX: Directives which are located on inline fragments should not be skipped and should be sent to the service PR #178
- FIX: Minifying a String argument should escape quotes and slashes PR #174
- Replace the query planner implementation with a new implementation written in rust and integrated into the gateway via wasm. PR #4534
- Only changes in the similarly versioned
@apollo/federation
package.
- Only changes in the similarly versioned
@apollo/federation
package.
- Only changes in the similarly versioned
@apollo/federation
package.
- FIX: Pass null required fields correctly within the parent object to resolvers. When a composite field was null, it would sometimes be expanded into an object with all null subfields and passed to the resolver. This fix prevents this expansion and sets the field to null, as originally intended. PR #4157
- FIX: Prevent gateway from entering an inoperable state after an initial configuration load failure. PR #4277
- The
RemoteGraphQLDataSource
'sdidEncounterError
method will now receiveResponse
as the third argument when it is available, making its signature(error: Error, fetchRequest: Request, fetchResponse?: Response)
. This compliments the existingRequest
type it was already receiving. Both of these types are HTTP WHATWG Fetch API types, notGraphQLRequest
,GraphQLResponse
types.
- BREAKING: Move federation metadata from custom objects on schema nodes over to the
extensions
field on schema nodes which are intended for metadata. This is a breaking change because it narrows thegraphql
peer dependency from^14.0.2
to^14.5.0
which is whenextensions
were introduced for all Type System objects. PR #4313
- Only changes in the similarly versioned
@apollo/federation
package.
- The default branch of the repository has been changed to
main
. As this changed a number of references in the repository'spackage.json
andREADME.md
files (e.g., for badges, links, etc.), this necessitates a release to publish those changes to npm. PR #4302 - FIX: The cache implementation for the HTTP-fetcher which is used when communicating with the Apollo Registry when the gateway is configured to use managed federation will no longer write to its cache when it receives a 304 response. This is necessary since such a response indicates that the cache used to conditionally make the request must already be present. This does not affect GraphQL requests at runtime, only the polling and fetching mechanism for retrieving composed schemas under manged federation. PR #4325
- FIX: The
mergeFieldNodeSelectionSets
method no longer mutates original FieldNode objects. Before, it was updating the selection set of the original object, corrupting the data accross requests.
- Only changes in the similarly versioned
@apollo/federation
package.
- Bumped the version of
apollo-server-core
, but no other changes!
- Only changes in the similarly versioned
@apollo/federation
package.
- Only changes in the similarly versioned
@apollo/federation
package.
- NEW: Provide the
requestContext
as an argument to the experimental callback functionexperimental_didResolveQueryPlan
. #4173
- This updates a dependency of
apollo-server-core
that is only used for its TypeScript typings, not for any runtime dependencies. The reason for the upgrade is that theapollo-server-core
package (again, used only for types!) was affected by a GitHub Security Advisory. See the relatedCHANGELOG.md
for Apollo Server for more details, including a link to the advisory.
- FIX: Collapse nested required fields into a single body in the query plan. Before, some nested fields' selection sets were getting split, causing some of their subfields to be dropped when executing the query. This fix collapses the split selection sets into one. #4064
-
NEW: Provide the ability to pass a custom
fetcher
duringRemoteGraphQLDataSource
construction to be used when executing operations against downstream services. Providing a customfetcher
may be necessary to accommodate more advanced needs, e.g., configuring custom TLS certificates for internal services. PR #4149The
fetcher
specified should be a compliant implementor of the Fetch API standard. This addition compliments, though is still orthognonal to, similar behavior originally introduced in #3783, which allowed customization of the implementation used to fetch gateway configuration and federated SDL from services in managed and unmanaged modes, but didn't affect the communication that takes place during operation execution.For now, the default
fetcher
will remain the same (node-fetch
) implementation. A future major-version bump will update it to be consistent with other feature-rich implementations of the Fetch API which are used elsewhere in the Apollo Server stack where we usemake-fetch-happen
. In all likelihood,ApolloGateway
will pass its ownfetcher
to theRemoteGraphQLDataSource
during service initialization.
- BREAKING: Use a content delivery network for managed configuration, fetch storage secrets and composition configuration from different domains: https://storage-secrets.api.apollographql.com and https://federation.api.apollographql.com. Please mind any firewall for outgoing traffic. #4080
- FIX: Correctly handle unions with nested conditions that have no
possibleTypes
#4071 - FIX: Normalize root operation types when reporting to Apollo Graph Manager. Federation always uses the default names
Query
,Mutation
, andSubscription
for root operation types even if downstream services choose different names; now we properly normalize traces received from downstream services in the same way. #4100
- BREAKING: Drop support for Node.js 8 and Node.js 10. This is being done primarily for performance gains which stand to be seen by transpiling to a newer ECMAScript target. For more details, see the related PR. #4031
- Performance: Cache stringified representations of downstream query bodies within the query plan to address performance cost incurred by repeatedly
print
ing the sameDocumentNode
s with thegraphql
printer. This improvement is more pronounced on larger documents. PR #4018 - Deprecation: Deprecated the
ENGINE_API_KEY
environment variable in favor of its new name,APOLLO_KEY
. The new name mirrors the name used within Apollo Graph Manager. Aside from the rename, the functionality remains otherwise identical. Continued use ofENGINE_API_KEY
will result in deprecation warnings being printed to the server console. Support forENGINE_API_KEY
will be removed in a future, major update. #3923 - Deprecation: Deprecated the
APOLLO_SCHEMA_TAG
environment variable in favor of its new name,APOLLO_GRAPH_VARIANT
. The new name mirrors the name used within Apollo Graph Manager. Aside from the rename, the functionality remains otherwise identical. Use of the now-deprecated name will result in a deprecation warning being printed to the server console. Support will be removed entirely in a future, major update. To avoid misconfiguration, runtime errors will be thrown if the new and deprecated versions are both set. #3855 - Add inadvertently excluded
apollo-server-errors
runtime dependency. #3927
- FIX: Resolve condition which surfaced in
0.14.0
which prevented loading the configuration using managed federation. PR #3979
- Several previously unhandled Promise rejection errors stemming from, e.g. connectivity, failures when communicating with Apollo Graph Manager within asynchronous code are now handled. PR #3811
- Provide a more helpful error message when encountering expected errors. PR #3811
- General improvements and clarity to error messages and logging. PR #3811
- Warn of a possible misconfiguration when local service configuration is provided (via
serviceList
orlocalServiceList
) and a remote Apollo Graph Manager configuration is subsequently found as well. PR #3868 - During composition, the unavailability of a downstream service in unmanaged federation mode will no longer result in a partially composed schema which merely lacks the types provided by the downed service. This prevents unexpected validation errors for clients querying a graph which lacks types which were merely unavailable during the initial composition but were intended to be part of the graph. PR #3867
- Support providing a custom logger implementation (e.g.
winston
,bunyan
, etc.) to capture gateway-sourced console output. This allows the use of existing, production logging facilities or the possibiltiy to use advanced structure in logging, such as console output which is encapsulated in JSON. The same PR that introduces this support also introduces alogger
property to theGraphQLRequestContext
that is exposed toGraphQLDataSource
s and Apollo Server plugins, making it possible to attach additional properties (as supported by the logger implementation) to specific requests, if desired, by leveraging custom implementations in those components respectively. When not provided, these will still output toconsole
. PR #3894 - Drop use of
loglevel-debug
. This removes the very long date and time prefix in front of each log line and also the support for theDEBUG=apollo-gateway:
environment variable. Both of these were uncommonly necessary or seldom used (with the environment variable also being undocumented). The existing behavior can be preserved by providing alogger
that usesloglevel-debug
, if desired, and more details can be found in the PR. PR #3896 - Fix Typescript generic typing for datasource contexts #3865 This is a fix for the
TContext
typings of the gateway's exposedGraphQLDataSource
implementations. In their current form, they don't work as intended, or in any manner that's useful for typing thecontext
property throughout the class methods. This introduces a type argumentTContext
to the class itself (which defaults toRecord<string, any>
for existing implementations) and removes the non-operational type arguments on the class methods themselves. - Implement retry logic for requests to GCS PR #3836 Note: coupled with this change is a small alteration in how the gateway polls GCS for updates in managed mode. Previously, the tick was on a specific interval. Now, every tick starts after the round of fetches to GCS completes. For more details, see the linked PR.
- Gateway issues health checks to downstream services via
serviceHealthCheck
configuration option. Note: expected behavior differs between managed and unmanaged federation. See PR for new test cases and documentation. #3930
- BREAKING: The behavior and signature of
RemoteGraphQLDataSource
'sdidReceiveResponse
method has been changed. No changes are necessary unless your implementation has overridden the default behavior of this method by either extending the class and overriding the method or by providingdidReceiveResponse
as a parameter to theRemoteGraphQLDataSource
's constructor options. Implementations which have provided their owndidReceiveResponse
using either of these methods should view the PR linked here for details on what has changed. PR #3743 - NEW: Setting the
apq
option totrue
on theRemoteGraphQLDataSource
will enable the use of automated persisted queries (APQ) when sending queries to downstream services. Depending on the complexity of queries sent to downstream services, this technique can greatly reduce the size of the payloads being transmitted over the network. Downstream implementing services must also support APQ functionality to participate in this feature (Apollo Server does by default unless it has been explicitly disabled). As with normal APQ behavior, a downstream server must have received and registered a query once before it will be able to serve an APQ request. #3744 - NEW: Experimental feature: compress downstream requests via generated fragments #3791 This feature enables the gateway to generate fragments for queries to downstream services in order to minimize bytes over the wire and parse time. This can be enabled via the gateway config by setting
experimental_autoFragmentization: true
. It is currently disabled by default. - Introduce
make-fetch-happen
package. RemovecachedFetcher
in favor of the caching implementation provided by this package. #3783
- Update to include fixes from
@apollo/federation
.
- Reduce interface expansion for types contained to a single service #3582
- Instantiate one
CachedFetcher
per gateway instance. This resolves a condition where multiple federated gateways would utilize the same cache store could result in anExpected undefined to be a GraphQLSchema
error. #3704 - Gateway: minimize downstream request size #3737
- experimental: Allow configuration of the query plan store by introducing an
experimental_approximateQueryPlanStoreMiB
property to theApolloGateway
constructor options which overrides the default cache size of 30MiB. #3755
- Fix onSchemaChange callbacks for unmanaged configs #3605
- Gateway over-merging fields of unioned types #3581
- Begin supporting executable directives in federation #3464
- Fix Gateway / Playground Query Plan view #3418
- Gateway schema change listener bug + refactor #3411 introduces a change to the
experimental_didUpdateComposition
hook andexperimental_pollInterval
configuration behavior.- Previously, the
experimental_didUpdateComposition
hook wouldn't be reliably called unless theexperimental_pollInterval
was set. If it was called, it was sporadic and didn't necessarily mark the timing of an actual composition update. After this change, the hook is called on a successful composition update. - The
experimental_pollInterval
configuration option now affects both the GCS polling interval when gateway is configured for managed federation, as well as the polling interval of services. The former being newly introduced behavior.
- Previously, the
- Gateway cached DataSource bug #3412 introduces a fix for managed federation users where
DataSource
s wouldn't update correctly if a service's url changed. This bug was introduced with heavier DataSource caching in #3388. By inspecting theurl
as well,DataSource
s will now update correctly when a composition update occurs. - Gateway - don't log updates on startup #3421 Fine tune gateway startup logging - on load, instead of logging an "update", log the service id, variant, and mode in which gateway is running.
- Add export for experimental observability functions types. #3371
- Fix double instantiation of DataSources #3388
- Fix debug query plan logging #3376
- Add
context
object toGraphQLDataSource.didReceiveResponse
arguments #3360
- Make service definition cache local to ApolloGateway object #3191
- Fix value type behavior within composition and execution #3182
- Validate variables at the gateway level #3213
- Optimize buildQueryPlan when two FetchGroups are on the same service #3135
- Construct and use RemoteGraphQLDataSource to issue introspection query to Federated Services #3120
- Add experimental observability functions #3110
- Handle
null
@requires selections correctly during execution #3138
- Proxy errors from downstream services #3019
- Handle schema defaultVariables correctly within downstream fetches #2963
- Fix
@requires
bug preventing array and null values. PR #2928
- Relax constraints of root operation type names in validation #2783
- Resolve an issue with _proto_ pollution in deepMerge() #2779