Documentation for new request pipeline life-cycle hooks/p… #2008

abernix · 2018-11-21T15:33:39Z

This is still WIP, but aims to document some of the new functionality and flexibility introduced in Apollo Server 2.2's new request pipeline (See #1795 for implementation details).

Early feedback appreciated! (The best bet to review this is likely to check the Netlify preview)

This is still WIP, but aims to demonstrate some of the new functionality and flexibility introduced in Apollo Server 2.2's new request pipeline (See #1795 for implementation details).

This doesn't address any feedback in particular, I just woke up and decided to re-write a bunch of it.

Whoaa512 · 2019-01-18T23:28:39Z

@abernix Had a look at the preview, and I'm curious what the main differences are between this and the extensions API?

peggyrayzis

Love how thorough these docs are, great job @abernix! 🎉 Before we merge, I'd love to see some more info on why plugins are useful for GraphQL developers and what some concrete use cases are. Right now, everything feels a bit abstract. When we release extension points like this (Apollo Link comes to mind on the client), often contributors will build out our suggested use cases for us, so it's a good opportunity to inspire contributors to build their own plugins.

peggyrayzis · 2019-01-16T20:17:32Z

docs/source/features/plugins.md

+## Overview
+
+The default Apollo Server installation is designed for a reliable out-of-the-box experience with as little configuration as possible.  In order to provide additional features, Apollo Server supports _plugins_ which can interface with various stages of server operation and each request/response cycle.
+


Add a sentence or two about why plugins are valuable for developers with some potential use cases -- it's unclear right now why someone would want to read this docs page.

Thoughts?

Suggested change

For example, these life-cycle hooks might be used to:

* Change the HTTP response code depending on the result of the operation's execution using the `willSendResponse` life-cycle hook.

* Implement rate-limiting for certain IP addresses using the `requestDidStart` life-cycle hook.

peggyrayzis · 2019-01-16T20:18:54Z

docs/source/features/plugins.md

+
+The `plugins` array is an array of plugins.  They might be provided as a module (and optionally published to a registry — e.g. npm) or defined in-line within the `ApolloServer` constructor.  Plugins should be defined correctly and the requirements of building a plugin are explained in the plugin [definition](#definition) section below.
+
+> **Note:** If a plugin is provided by a package published to a registry (for example, npm), that package must be installed using `npm install <plugin>` or `yarn add <plugin>` prior to use.  In-line plugins or plugins which reside locally do not need to be installed.


I think we can remove this note, since the vast majority of people reading this know how to install a package from a registry.

peggyrayzis · 2019-01-16T20:25:15Z

docs/source/features/plugins.md

+  plugins: [
+
+    /* A plugin installed from the npm registry. */
+    require('apollo-server-operation-registry')({ /* options */ }),


Semantically, wouldn't most people define variables at the top of the file when they load their modules? I think it's more readable to define const OperationRegistry = require('apollo-server-operation-registry') at the top of the file and pass OperationRegistry({ /* options */ }) to the plugin array. We can use the line highlighting feature in the code block to draw their attention to both areas of the file.

Maybe; patterns will vary! But this is a fair suggestion.

Here's what it would look like with your suggestion applied: https://5c5ad797c4ed1300088f2dca--apollo-server-docs.netlify.com/docs/apollo-server/features/plugins.html

I thiiinnk...I'm indifferent. The primary reason I had it the other way was to tightly-couple the three examples together. Also, if you think this looks good in the preview, do you think I should change the ./localPluginModule import (below) as well?

docs/source/features/plugins.md

peggyrayzis · 2019-01-30T14:16:53Z

docs/_config.yml

@@ -27,6 +27,7 @@ sidebar_categories:
    - features/creating-directives
    - features/authentication
    - features/testing
+    - features/plugins


I feel like we should rearchitect the sidebar -- features seems like it's getting too long. What do you think?

I think that's an accurate statement, but I might hold off until we've done some additional Apollo Server 3 planning. Suggestions welcomed though!

docs/source/features/plugins.md

peggyrayzis · 2019-01-30T14:22:01Z

docs/source/features/plugins.md

+
+> **Note:** Currently the `pluginInfo` is undefined, but future additions to the plugin API will enable this functionality.  For now, the factory function facilities are in place to use, but `pluginInfo` is simply not available.
+
+## Events


I think this section should be higher up the hierarchy chain, possibly even above the definition, since it's core to understanding plugins. Then, we can pull Server lifecycle events and Request lifecycle events into their own headings with all of the lifecycle methods as subheadings. Right now, it looks strange in the deploy preview that all of the methods are on the same hierarchy level as Server lifecycle events and Request lifecycle events.

I think that's a great suggestion; even though it slightly compromises the hierarchy, since it moves Events away from the event details that were under it, I think I like it better too.

Though it's possible that the oddness is partially because we only show the top few levels of headings on the sidebar.

Let me know what you think on https://5c5add5794fb530008ede1aa--apollo-server-docs.netlify.com/docs/apollo-server/features/plugins.html#Events?

peggyrayzis · 2019-01-30T14:23:04Z

docs/source/features/plugins.md

+
+## Events
+
+There are two main categories of events: server life-cycle events and request life-cycle events.


Do we want to drop the dash in between life-cycle? In the React docs, they spell it without the dash. https://reactjs.org/docs/state-and-lifecycle.html

Let's drop it! (It's hard to say; life-cycle has almost a billion matches on Google and lifecycle only has 128 million. Hard to know if "lifecycle" is more closely associated with CS, but I digress.)

My vote would be that we do it consistently across all our documentation, and based on this search, that would be lifecycle. I'll make the change in a follow-up commit.

docs/source/features/plugins.md

Co-Authored-By: abernix <git@jro.cc>

abernix · 2019-02-01T12:12:42Z

docs/_config.yml

@@ -27,6 +27,7 @@ sidebar_categories:
    - features/creating-directives
    - features/authentication
    - features/testing
+    - features/plugins


I think that's an accurate statement, but I might hold off until we've done some additional Apollo Server 3 planning. Suggestions welcomed though!

abernix · 2019-02-06T12:16:29Z

docs/source/features/plugins.md

+## Overview
+
+The default Apollo Server installation is designed for a reliable out-of-the-box experience with as little configuration as possible.  In order to provide additional features, Apollo Server supports _plugins_ which can interface with various stages of server operation and each request/response cycle.
+


Thoughts?

Suggested change

For example, these life-cycle hooks might be used to:

* Change the HTTP response code depending on the result of the operation's execution using the `willSendResponse` life-cycle hook.

* Implement rate-limiting for certain IP addresses using the `requestDidStart` life-cycle hook.

docs/source/features/plugins.md

abernix · 2019-02-06T12:27:41Z

docs/source/features/plugins.md

+
+## Events
+
+There are two main categories of events: server life-cycle events and request life-cycle events.


Let's drop it! (It's hard to say; life-cycle has almost a billion matches on Google and lifecycle only has 128 million. Hard to know if "lifecycle" is more closely associated with CS, but I digress.)

My vote would be that we do it consistently across all our documentation, and based on this search, that would be lifecycle. I'll make the change in a follow-up commit.

…her docs.

docs/source/features/plugins.md

Ref: https://github.com/apollographql/apollo-server/pull/2008/files#r248437859

Ref: https://github.com/apollographql/apollo-server/pull/2008/files#r252275456

abernix

Thanks for the feedback, @peggyrayzis! I think I've addressed it. Let me know what you think!

abernix · 2019-02-06T12:55:00Z

docs/source/features/plugins.md

+  plugins: [
+
+    /* A plugin installed from the npm registry. */
+    require('apollo-server-operation-registry')({ /* options */ }),


Maybe; patterns will vary! But this is a fair suggestion.

Here's what it would look like with your suggestion applied: https://5c5ad797c4ed1300088f2dca--apollo-server-docs.netlify.com/docs/apollo-server/features/plugins.html

I thiiinnk...I'm indifferent. The primary reason I had it the other way was to tightly-couple the three examples together. Also, if you think this looks good in the preview, do you think I should change the ./localPluginModule import (below) as well?

abernix · 2019-02-06T13:16:32Z

docs/source/features/plugins.md

+
+> **Note:** Currently the `pluginInfo` is undefined, but future additions to the plugin API will enable this functionality.  For now, the factory function facilities are in place to use, but `pluginInfo` is simply not available.
+
+## Events


I think that's a great suggestion; even though it slightly compromises the hierarchy, since it moves Events away from the event details that were under it, I think I like it better too.

Though it's possible that the oddness is partially because we only show the top few levels of headings on the sidebar.

Let me know what you think on https://5c5add5794fb530008ede1aa--apollo-server-docs.netlify.com/docs/apollo-server/features/plugins.html#Events?

abernix · 2019-02-06T13:16:58Z

docs/source/features/plugins.md

+
+### `willSendResponse`
+
+> TODO


Worth leaving myself a comment that this is still TODO and waiting to be filled out.

abernix · 2019-02-06T13:17:11Z

docs/source/features/plugins.md

+
+### `executionDidStart`
+
+> TODO


(As I mentioned at the bottom of #2714) This adds a new life-cycle event to the new request pipeline API called `didEncounterErrors`, which receives `requestContext`'s **unformatted** `errors`. (The `requestContext` represents an individual request within Apollo Server.) These `errors` give access to potentially different `errors` than those received within `response.errors`, which are sent to the client and available on the `willSendResponse` life-cycle hook, since they are **not** passed through the `formatError` transformation. This can allow plugin implementers to take advantage of the actual errors and properties which may be pruned from the error before transmission to the client. While most other request pipeline life-cycle events provide a guarantee of their arguments, this `didEncounterErrors` will have a little bit less certainty since the errors could have happened in parsing, validation, or execution, and thus different contracts would have been made (e.g. we may not have been able to negotiate a `requestContext.document` if we could not parse the operation). This still needs tests and I suspect I'll have some additional changes prior to this becoming official, but it can ship as-is for now and will live in the Apollo Server 2.6.0 alpha for the time-being. Use with minimal risk, but with the caveat that the final API may change. Also, I'll need to add docs to #2008.

dylang · 2019-07-03T16:59:52Z

docs/source/features/plugins.md

+> TODO
+
+```typescript
+willSendResponse?(


can this be used to modify the response before returning, such as adding additional metrics?

Thanks for including this. If we wanted to alter the extensions object in the response, I noticed that only Approach 1 worked. This feels a little counter-intuitive for devs used to functional programming where state-in -> function -> state out.

// Approach 1: Direct mutation of object const helloPlugin1 = { requestDidStart() { return { willSendResponse(requestContext) { requestContext.response.extensions.randomField = 'Hello World!'; }, }; }, }; // Approach 2: clone and return object const _ = require('lodash'); const helloPlugin2 = { requestDidStart() { return { willSendResponse(requestContext) { const newReqContext = _.cloneDeep(requestContext); newReqContext.response.extensions.randomField = 'Hello World!'; return newReqContext; }, }; }, };

dylang · 2019-07-03T17:00:49Z

docs/source/features/plugins.md

+> TODO
+
+```typescript
+didEncounterErrors?(


Can this be used in place of formatErrors because it is async and has access to context?

a-ursino · 2019-08-28T11:05:17Z

Hi @abernix thanks for the work on the docs.

Using didEncounterErrors to log errors what is the best way to check for validation errors? They sit under the GraphQLError like errors during the execution phase.

nwalters512 · 2019-10-03T19:46:37Z

One major omission from these docs is an explanation of why functions can be returned from the *didStart hooks. It looks like they'll be invoked as "end hooks", but I had to look at the source to figure out what these are:

apollo-server/packages/apollo-server-core/src/utils/dispatcher.ts

Line 64 in 1acf62d

const didEndHook = method.apply(target, args);

. Would be great to have this mentioned in the final version of the docs!

* WIP on plugins copyedit * Fix a broken internal link * Finished edit minus TODO functions * Recategorize plugins article and fill in TODOs

nether-cat

Great work, thank you very much @abernix! ❤️

My understanding from looking at actual plugin implementations is, one may not only observe and change the contents of requests / responses but one might also be able to interrupt or control the flow of the request pipeline, e.g. by throwing an error or rejecting a promise in appropriate situations – maybe also by delegating execution to a different operation than the one resolved..?

I personally would love to read a little bit about the request lifecycle hooks' return values and suggest to put in something about possible effects respectively. I believe many readers could even much easier realize the potential value of creating their own plugin then... 💡

Besides this suggestion, I really like the explanations / docs you provided. Thanks again! 👍

nether-cat · 2019-10-21T21:02:36Z

docs/source/integrations/plugins.md

+
+The `didResolveOperation` event fires after the `graphql` library successfully
+determines the operation to execute from a request's `document` AST. At this stage,
+both the `operationName` string and `operation` AST are available.


I think the aforementioned bits about the return value's "purpose" or possible effects (might only be one additional sentence per event) could just be added here and in the other paragraphs respectively.

nether-cat · 2019-10-21T21:19:34Z

docs/source/integrations/plugins.md

+
+* [`parsingDidStart`](#parsingdidstart)
+* [`validationDidStart`](#validationdidstart)
+* [`didResolveOperation`](#didresolveoperation)


responseForOperation should also be included, shouldn't it? I think it was added later only a while ago, see here.

abernix · 2019-11-05T14:30:09Z

@nether-cat (and @nwalters512, prior to that) I think these are all great suggestions, but at this point, I think we should just land this documentation so it actually gets discovered. It's been sitting here for too long now!

Please feel free to open follow-up PRs (or at least issues to track your suggestions), particularly for the recently added responseForOperation! Such contributions would be very much appreciated!

nether-cat · 2019-11-05T17:16:01Z

@abernix I agree! I remember me kind of having a hard time with this topic, until I did not only find your PR, but also realized that there even was a preview available :D

nwalters512 · 2019-11-06T03:15:08Z

@abernix I've opened a PR with those changes: #3475

docs(plugins): Beginnings of the documentation for plugins.

cb072cf

This is still WIP, but aims to demonstrate some of the new functionality and flexibility introduced in Apollo Server 2.2's new request pipeline (See #1795 for implementation details).

abernix requested review from peggyrayzis and martijnwalraven November 21, 2018 15:33

Editorial and clean-up on top of my previous documentation attempt.

0a8c729

This doesn't address any feedback in particular, I just woke up and decided to re-write a bunch of it.

abernix mentioned this pull request Jan 15, 2019

Cache successfully parsed and validated documents for future requests. #2111

Merged

martijnwalraven mentioned this pull request Jan 27, 2019

Re-add dynamic validation by request #2232

Closed

3 tasks

peggyrayzis requested changes Jan 30, 2019

View reviewed changes

abernix mentioned this pull request Feb 4, 2019

Add context parameter to validationDidStart and parsingDidStart #1653

Closed

3 tasks

Apply suggestions from code review

49077b6

Co-Authored-By: abernix <git@jro.cc>

abernix commented Feb 6, 2019

View reviewed changes

abernix added 2 commits February 6, 2019 14:33

docs: change "life-cycle" to "lifecycle", for consistency with our ot…

21254be

…her docs.

Apply suggestions from code review

42a1b2b

abernix commented Feb 6, 2019

View reviewed changes

docs/source/features/plugins.md Outdated Show resolved Hide resolved

abernix added 4 commits February 6, 2019 14:36

Update docs/source/features/plugins.md

77a84f8

docs: Assign external plugin to symbol at top, with other imports.

7ced2b5

Ref: https://github.com/apollographql/apollo-server/pull/2008/files#r248437859

docs: Fix incorrect line-highlights after previous commit.

9b51768

docs: Hoist "Events" higher in the doc, above "Definition".

fe35e0d

Ref: https://github.com/apollographql/apollo-server/pull/2008/files#r252275456

abernix commented Feb 6, 2019

View reviewed changes

This was referenced Feb 20, 2019

throwing AuthenticationError should set the response status to 401 Unauthorized #1709

Closed

Apollo Server 3.0 Roadmap #2360

Closed

abernix mentioned this pull request Apr 26, 2019

Execute some function before each query or mutation? #2609

Closed

abernix added 2 commits May 24, 2019 19:36

Merge branch 'master' into abernix/docs-plugins

75bcdc2

Add plugins in new Gatsby theme.

a4d2168

abernix mentioned this pull request May 24, 2019

Server crashes on every calls when extension returns a promise #2038

Closed

abernix mentioned this pull request May 24, 2019

Add didEncounterErrors to request pipeline API. #2719

Merged

MichalLytek mentioned this pull request May 28, 2019

Using Query-Complexity with ApolloServer and problem accessing req MichalLytek/type-graphql#344

Closed

abernix mentioned this pull request Jun 30, 2019

feat: pass context to formatErrors #2140

Closed

4 tasks

dylang reviewed Jul 3, 2019

View reviewed changes

zionts mentioned this pull request Jul 8, 2019

Apollo testing - query finish event #2537

Closed

abernix mentioned this pull request Jul 8, 2019

Asynchronous handlers in Request Pipeline #2062

Closed

trevor-scheer mentioned this pull request Jul 8, 2019

Requiring auth header for introspection queries #1933

Closed

abernix mentioned this pull request Jul 9, 2019

Continuation-Local set in express middleware lost inside resolvers #2042

Closed

michaelbromley mentioned this pull request Jul 26, 2019

Interceptor doesn't get all resolved properties nestjs/graphql#320

Closed

Merge branch 'master' into abernix/docs-plugins

27423cf

abernix requested a review from StephenBarlow as a code owner August 15, 2019 17:06

StephenBarlow mentioned this pull request Aug 20, 2019

Edits on Apollo Server metrics article #3180

Merged

trevor-scheer mentioned this pull request Sep 9, 2019

How to add or modify a response header in ApolloServer? #3264

Closed

abernix mentioned this pull request Oct 12, 2019

Edits from @StephenBarlow to "Plugins" article #3189

Merged

abernix and others added 3 commits October 12, 2019 20:19

Merge branch 'master' into abernix/docs-plugins

006bbf2

Edits from @StephenBarlow to "Plugins" article (#3189)

b5c689c

* WIP on plugins copyedit * Fix a broken internal link * Finished edit minus TODO functions * Recategorize plugins article and fill in TODOs

Merge branch 'master' into abernix/docs-plugins

7411295

nether-cat suggested changes Oct 21, 2019

View reviewed changes

nether-cat reviewed Oct 21, 2019

View reviewed changes

Merge branch 'master' into abernix/docs-plugins

2e37a13

abernix requested a review from trevor-scheer as a code owner November 5, 2019 14:23

abernix changed the title ~~[WIP] Documentation for new request pipeline life-cycle hooks/plugins.~~ Documentation for new request pipeline life-cycle hooks/p… Nov 5, 2019

abernix merged commit 05ddd22 into master Nov 5, 2019

abernix deleted the abernix/docs-plugins branch November 5, 2019 14:30

nwalters512 mentioned this pull request Nov 6, 2019

Docs for request lifecycle end hooks and responseForOperation #3475

Merged

github-actions bot locked as resolved and limited conversation to collaborators Apr 21, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation for new request pipeline life-cycle hooks/p… #2008

Documentation for new request pipeline life-cycle hooks/p… #2008

abernix commented Nov 21, 2018 •

edited

Whoaa512 commented Jan 18, 2019

peggyrayzis left a comment

peggyrayzis Jan 16, 2019

abernix Feb 6, 2019 •

edited

peggyrayzis Jan 16, 2019

peggyrayzis Jan 16, 2019

abernix Feb 6, 2019

peggyrayzis Jan 30, 2019

abernix Feb 1, 2019

peggyrayzis Jan 30, 2019

abernix Feb 6, 2019

peggyrayzis Jan 30, 2019

abernix Feb 6, 2019

abernix Feb 1, 2019

abernix Feb 6, 2019 •

edited

abernix Feb 6, 2019

abernix left a comment

abernix Feb 6, 2019

abernix Feb 6, 2019

abernix Feb 6, 2019

abernix Feb 6, 2019

dylang Jul 3, 2019

abernix Oct 12, 2019

hochoy Jul 10, 2020 •

edited

dylang Jul 3, 2019

abernix Oct 12, 2019

a-ursino commented Aug 28, 2019 •

edited

nwalters512 commented Oct 3, 2019

nether-cat left a comment

nether-cat Oct 21, 2019

nether-cat Oct 21, 2019 •

edited

abernix commented Nov 5, 2019

nether-cat commented Nov 5, 2019

nwalters512 commented Nov 6, 2019

		## Overview

		The default Apollo Server installation is designed for a reliable out-of-the-box experience with as little configuration as possible. In order to provide additional features, Apollo Server supports _plugins_ which can interface with various stages of server operation and each request/response cycle.

+For example, these life-cycle hooks might be used to:
+* Change the HTTP response code depending on the result of the operation's execution using the `willSendResponse` life-cycle hook.
+* Implement rate-limiting for certain IP addresses using the `requestDidStart` life-cycle hook.


		The `plugins` array is an array of plugins. They might be provided as a module (and optionally published to a registry — e.g. npm) or defined in-line within the `ApolloServer` constructor. Plugins should be defined correctly and the requirements of building a plugin are explained in the plugin [definition](#definition) section below.

		> Note: If a plugin is provided by a package published to a registry (for example, npm), that package must be installed using `npm install <plugin>` or `yarn add <plugin>` prior to use. In-line plugins or plugins which reside locally do not need to be installed.


		> Note: Currently the `pluginInfo` is undefined, but future additions to the plugin API will enable this functionality. For now, the factory function facilities are in place to use, but `pluginInfo` is simply not available.

		## Events


		## Events

		There are two main categories of events: server life-cycle events and request life-cycle events.

Documentation for new request pipeline life-cycle hooks/p… #2008

Documentation for new request pipeline life-cycle hooks/p… #2008

Conversation

abernix commented Nov 21, 2018 • edited

Whoaa512 commented Jan 18, 2019

peggyrayzis left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

abernix Feb 6, 2019 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

abernix Feb 6, 2019 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

abernix left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hochoy Jul 10, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

a-ursino commented Aug 28, 2019 • edited

nwalters512 commented Oct 3, 2019

nether-cat left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nether-cat Oct 21, 2019 • edited

Choose a reason for hiding this comment

abernix commented Nov 5, 2019

nether-cat commented Nov 5, 2019

nwalters512 commented Nov 6, 2019

abernix commented Nov 21, 2018 •

edited

abernix Feb 6, 2019 •

edited

abernix Feb 6, 2019 •

edited

hochoy Jul 10, 2020 •

edited

a-ursino commented Aug 28, 2019 •

edited

nether-cat Oct 21, 2019 •

edited