Update AS4 Plugin Docs (#6873)

Co-authored-by: Trevor Scheer <trevor.scheer@gmail.com>

Author: rkoron007

.changeset/empty-peaches-heal.md

@@ -0,0 +1,2 @@
+---
+---

docs/source/api/plugin/cache-control.md docs/source/api/plugin/cache-control.mdxdocs/source/api/plugin/cache-control.md renamed to docs/source/api/plugin/cache-control.mdx

@@ -5,62 +5,58 @@ api_reference: true
 
 ## Using the plugin
 
-This API reference documents the `ApolloServerPluginCacheControl` plugin.
+This article documents the options for the `ApolloServerPluginCacheControl` plugin, which you can import from `@apollo/server/plugin/cacheControl`.
 
-This plugin enables your GraphQL server to specify a cache policy at the field level, either statically in your schema with the `@cacheControl` directive, or dynamically in your resolvers via the `info.cacheControl` API. It also by default sets the `cache-control` HTTP response header. This page is a reference for the options available in configuring the plugin; more background and examples are available in [the caching documentation](../../performance/caching/).
+This plugin enables your GraphQL server to specify a cache policy at the field level, either statically in your schema with the `@cacheControl` directive, or dynamically in your resolvers via the `info.cacheControl` API. It also sets the `cache-control` HTTP response header by default. See [Server-side caching](../../performance/caching/) for more information and examples.
+
+> To use the `@cacheControl` directive, you must first [define it in your schema](../../performance/caching/#in-your-schema-static).
 
 Apollo Server installs this plugin by default in all servers, with its default configuration.  You typically do not have to install this plugin yourself; you only need to do so if you want to provide non-default configuration.
 
-If you want to configure this plugin, import it from the `apollo-server-core` package and pass it to your `ApolloServer` in the `plugins` array:
+If you want to configure the `ApolloServerPluginCacheControl` plugin, import it and pass it to your `ApolloServer` constructor's `plugins` array:
+
+<MultiCodeBlock>
 
-```js
-import { ApolloServer } from "apollo-server";
-import {
-  ApolloServerPluginCacheControl,
-  ApolloServerPluginLandingPageLocalDefault,
-} from "apollo-server-core";
+```ts
+import { ApolloServer } from '@apollo/server';
+import { ApolloServerPluginCacheControl } from '@apollo/server/plugin/cacheControl';
 
 const server = new ApolloServer({
   typeDefs,
   resolvers,
-  csrfPrevention: true,
-  cache: "bounded",
   plugins: [
     ApolloServerPluginCacheControl({
       // Cache everything for 1 second by default.
       defaultMaxAge: 1,
       // Don't send the `cache-control` response header.
       calculateHttpHeaders: false,
     }),
-    ApolloServerPluginLandingPageLocalDefault({ embed: true }),
   ],
 });
 ```
 
+</MultiCodeBlock>
+
 If you don't want to use cache control at all, you can explicitly disable it with the `ApolloServerPluginCacheControlDisabled` plugin:
 
-```js
-import { ApolloServer } from "apollo-server";
-import {
-  ApolloServerPluginCacheControlDisabled,
-  ApolloServerPluginLandingPageLocalDefault,
-} from "apollo-server-core";
+<MultiCodeBlock>
+
+```ts
+import { ApolloServer } from '@apollo/server';
+import { ApolloServerPluginCacheControlDisabled } from '@apollo/server/plugin/disabled';
 
 const server = new ApolloServer({
   typeDefs,
   resolvers,
-  csrfPrevention: true,
-  cache: "bounded",
   plugins: [
     ApolloServerPluginCacheControlDisabled(),
-    ApolloServerPluginLandingPageLocalDefault({ embed: true }),
   ],
 });
 ```
 
-(The plugin does not have much of an effect on your app if you do not use the `@cacheControl` directive or use the `info.cacheControl` API; there might be a very slight performance improvement from disabling the plugin if you do not use it.)
+</MultiCodeBlock>
 
-Note that in Apollo Server 3, the cache control plugin does *not* define the `@cacheControl` directive for you; if you want to use the directive, you must [define the `@cacheControl` directive in your schema](../..//performance/caching/#in-your-schema-static).
+The plugin doesn't affect your app much if you don't use the `@cacheControl` directive or the `info.cacheControl` API. If you don't currently use it, there might be a very slight performance improvement from disabling the plugin.
 
 ## Options
 
@@ -83,7 +79,9 @@ Note that in Apollo Server 3, the cache control plugin does *not* define the `@c
 </td>
 <td>
 
-By default, root fields and fields that return a composite type (object, interface, or union) are considered to be uncacheable (`maxAge` 0) unless a cache hint is explicitly provided via `@cacheControl` or `info.cacheControl`. You can set this option to make the default `maxAge` for these larger than 0; this will effectively cause all requests to be be cacheable. (This option was popular in Apollo Server 2 largely as a workaround for the problem solved by the [`@cacheControl(inheritMaxAge: true)`](../../performance/caching/#in-your-schema-static) directive argument; consider using `inheritMaxAge` instead of `defaultMaxAge` in Apollo Server 3.) You can read more about [`defaultMaxAge` in the caching documentation](../../performance/caching/#default-maxage).
+By default, root fields and fields that return a composite type (object, interface, or union) are considered to be uncacheable (`maxAge` 0) unless a cache hint is explicitly provided via `@cacheControl` or `info.cacheControl`. You can set this option to make the default `maxAge` for these larger than 0; this will effectively cause all requests to be cacheable.
+
+This option was popular in Apollo Server 2 as a workaround for the problem solved by the [`@cacheControl(inheritMaxAge: true)`](../../performance/caching/#in-your-schema-static) directive argument. See [Default `maxAge`](../../performance/caching/#default-maxage) for more details.
 
 </td>
 </tr>

docs/source/api/plugin/drain-http-server.mdx

@@ -5,59 +5,62 @@ api_reference: true
 
 ## Using the plugin
 
-This API reference documents the `ApolloServerPluginDrainHttpServer` plugin.
+This article documents the options for the `ApolloServerPluginDrainHttpServer` plugin, which you can import from `@apollo/server/plugin/drainHttpServer`.
 
-This plugin is designed for use with [`apollo-server-express` and other framework-specific packages](../../integrations/middleware/#all-supported-packages) which are built on top of [Node `http.Server`s](https://nodejs.org/api/http.html#http_class_http_server). It is highly recommended that you use this plugin with packages like `apollo-server-express` if you want your server to shut down gracefully.
+This plugin is designed for use with `expressMiddleware` and other framework integrations built on top of [Node `http.Server`s](https://nodejs.org/api/http.html#http_class_http_server). **We highly recommend** using this plugin to ensure your server shuts down gracefully.
 
-You do not need to explicitly use this plugin with the batteries-included `apollo-server` package: that package automatically uses this plugin internally.
+> You do not need to use this plugin with the `startStandaloneServer` function; it automatically handles server draining.
 
-When you use this plugin, Apollo Server will drain your HTTP server when you call the `stop()` method (which is also called for you when the `SIGTERM` and `SIGINT` signals are received, unless disabled with the [`stopOnTerminationSignals` constructor option](../apollo-server/#stoponterminationsignals)). Specifically, it will:
+When you use this plugin, Apollo Server will drain your HTTP server when you call the `stop()` method (which is also called for you when the `SIGTERM` and `SIGINT` signals are received, unless disabled with the [`stopOnTerminationSignals` constructor option](../apollo-server/#stoponterminationsignals)).
 
-* Stop listening for new connections
-* Close idle connections (i.e., connections with no current HTTP request)
-* Close active connections whenever they become idle
-* Wait for all connections to be closed
-* After a grace period, if any connections remain active, forcefully close them.
+Specifically, it will:
 
-This plugin is exported from the `apollo-server-core` package. It is tested with `apollo-server-express`, `apollo-server-koa`, and `apollo-server-fastify`. (If you're using Hapi, you should instead use the `ApolloServerPluginStopHapiServer` plugin exported from the `apollo-server-hapi` package.)
+- Stop listening for new connections
+- Close idle connections (i.e., connections with no current HTTP request)
+- Close active connections whenever they become idle
+- Wait for all connections to be closed
+- After a grace period, if any connections remain active, forcefully close them.
 
-Here's a basic example of how to use it with Express. See the [framework integrations docs](../../integrations/middleware/) for examples of how to use it with other frameworks.
+<!-- TODO(AS4) add link to other integration article once it exists -->
+This plugin is exported from the `@apollo/server` package.  Here's a basic example of how to use it with Express:
 
 <MultiCodeBlock>
 
 ```ts title="index.ts"
-const express = require('express');
-const { ApolloServer } = require('apollo-server-express');
-const {
-  ApolloServerPluginDrainHttpServer,
-  ApolloServerPluginLandingPageLocalDefault,
-} = require('apollo-server-core');
-const { typeDefs, resolvers } = require('./schema');
-const http = require('http');
+import { ApolloServer } from '@apollo/server';
+import { expressMiddleware } from '@apollo/server/express4';
+import { ApolloServerPluginDrainHttpServer } from '@apollo/server/plugin/drainHttpServer';
+import express from 'express';
+import http from 'http';
+import cors from 'cors';
+import { json } from 'body-parser';
+import { typeDefs, resolvers } from './schema';
+
+interface MyContext {
+  token?: String;
+}
 
 async function startApolloServer() {
   const app = express();
   // Our httpServer handles incoming requests to our Express app.
   // Below, we tell Apollo Server to "drain" this httpServer,
   // enabling our servers to shut down gracefully.
   const httpServer = http.createServer(app);
-  const server = new ApolloServer({
+  const server = new ApolloServer<MyContext>({
     typeDefs,
     resolvers,
-    csrfPrevention: true,
-    cache: 'bounded',
-    plugins: [
-      ApolloServerPluginDrainHttpServer({ httpServer }),
-      ApolloServerPluginLandingPageLocalDefault({ embed: true }),
-    ],
+    plugins: [ApolloServerPluginDrainHttpServer({ httpServer })],
   });
-
   await server.start();
-
-  // Mount Apollo middleware here.
-  server.applyMiddleware({ app });
+  app.use('/graphql',
+    cors<cors.CorsRequest>(),
+    json(),
+    expressMiddleware(server, {
+      context: async ({ req }) => ({ token: req.headers.token }),
+    }),
+  );
   await new Promise<void>(resolve => httpServer.listen({ port: 4000 }, resolve));
-  console.log(`🚀 Server ready at http://localhost:4000${server.graphqlPath}`);
+  console.log(`🚀 Server ready at http://localhost:4000/graphql`);
   return { server, app };
 }
 ```