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

[abernix]

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)

[Whoaa512]

@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]

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.

[abernix]

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]

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]

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.

[abernix]

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?

[peggyrayzis]

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

[abernix]

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!

[peggyrayzis]

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.

[abernix]

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]

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

[abernix]

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.

[abernix]

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]

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.

[abernix]

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.

[abernix]

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

[abernix]

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]

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]

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

[abernix]

TODO.

[dylang]

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

[abernix]

Yes!

[hochoy]

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]

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

[abernix]

Also, yes!

[a-ursino]

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]

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!

[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]

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]

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

[abernix]

@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]

@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]

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