feat(api): use custom apollo plugin to render sandbox

pujitm · pujitm · commit b73e76cb53c2 · 2025-01-15T16:36:12.000-05:00
diff --git a/api/src/unraid-api/graph/graph.module.ts b/api/src/unraid-api/graph/graph.module.ts
@@ -3,7 +3,6 @@ import { ApolloDriver } from '@nestjs/apollo';
 import { Module } from '@nestjs/common';
 import { GraphQLModule } from '@nestjs/graphql';
 
-import { ApolloServerPluginLandingPageLocalDefault } from '@apollo/server/plugin/landingPage/default';
 import { NoUnusedVariablesRule, print } from 'graphql';
 import {
     DateTimeResolver,
@@ -16,37 +15,16 @@ import {
 import { GRAPHQL_INTROSPECTION } from '@app/environment';
 import { GraphQLLong } from '@app/graphql/resolvers/graphql-type-long';
 import { typeDefs } from '@app/graphql/schema/index';
-import { getters } from '@app/store';
 import { idPrefixPlugin } from '@app/unraid-api/graph/id-prefix-plugin';
 
 import { ConnectResolver } from './connect/connect.resolver';
 import { ConnectService } from './connect/connect.service';
 import { NetworkResolver } from './network/network.resolver';
 import { ResolversModule } from './resolvers/resolvers.module';
+import { sandboxPlugin } from './sandbox-plugin';
 import { ServicesResolver } from './services/services.resolver';
 import { SharesResolver } from './shares/shares.resolver';
 
-/** The initial query displayed in the Apollo sandbox */
-const initialDocument = `query ExampleQuery {
-  notifications {
-    id
-    overview {
-      unread {
-        info
-        warning
-        alert
-        total
-      }
-      archive {
-        info
-        warning
-        alert
-        total
-      }
-    }
-  }
-}`;
-
 @Module({
     imports: [
         ResolversModule,
@@ -59,23 +37,7 @@ const initialDocument = `query ExampleQuery {
                 extra,
             }),
             playground: false,
-            plugins: GRAPHQL_INTROSPECTION
-                ? [
-                      ApolloServerPluginLandingPageLocalDefault({
-                          footer: false,
-                          includeCookies: true,
-                          document: initialDocument,
-                          embed: {
-                              initialState: {
-                                  sharedHeaders: {
-                                      'x-csrf-token': getters.emhttp().var.csrfToken ?? 'no csrf token',
-                                  },
-                              },
-                          },
-                      }),
-                      idPrefixPlugin,
-                  ]
-                : [idPrefixPlugin],
+            plugins: GRAPHQL_INTROSPECTION ? [sandboxPlugin, idPrefixPlugin] : [idPrefixPlugin],
             subscriptions: {
                 'graphql-ws': {
                     path: '/graphql',
diff --git a/api/src/unraid-api/graph/sandbox-plugin.ts b/api/src/unraid-api/graph/sandbox-plugin.ts
@@ -0,0 +1,82 @@
+import { HttpException, HttpStatus } from '@nestjs/common';
+
+import type { ApolloServerPlugin, GraphQLServerContext, GraphQLServerListener } from '@apollo/server';
+
+/** The initial query displayed in the Apollo sandbox */
+const initialDocument = `query ExampleQuery {
+    notifications {
+      id
+      overview {
+        unread {
+          info
+          warning
+          alert
+          total
+        }
+        archive {
+          info
+          warning
+          alert
+          total
+        }
+      }
+    }
+  }`;
+
+/** helper for raising precondition failure errors during an http request. */
+const preconditionFailed = (preconditionName: string) => {
+    throw new HttpException(`Precondition failed: ${preconditionName} `, HttpStatus.PRECONDITION_FAILED);
+};
+
+/**
+ * Renders the sandbox page for the GraphQL server with Apollo Server landing page configuration.
+ * 
+ * @param service - The GraphQL server context object
+ * @returns Promise that resolves to an Apollo `LandingPage`, or throws a precondition failed error
+ * @throws {Error} When downstream plugin components from apollo are unavailable. This should never happen.
+ * 
+ * @remarks
+ * This function configures and renders the Apollo Server landing page with:
+ * - Disabled footer
+ * - Enabled cookies
+ * - Initial document state
+ * - Shared headers containing CSRF token
+ */
+async function renderSandboxPage(service: GraphQLServerContext) {
+    const { getters } = await import('@app/store');
+    const { ApolloServerPluginLandingPageLocalDefault } = await import(
+        '@apollo/server/plugin/landingPage/default'
+    );
+    const plugin = ApolloServerPluginLandingPageLocalDefault({
+        footer: false,
+        includeCookies: true,
+        document: initialDocument,
+        embed: {
+            initialState: {
+                sharedHeaders: {
+                    'x-csrf-token': getters.emhttp().var.csrfToken,
+                },
+            },
+        },
+    });
+    if (!plugin.serverWillStart) return preconditionFailed('serverWillStart');
+    const serverListener = await plugin.serverWillStart(service);
+
+    if (!serverListener) return preconditionFailed('serverListener');
+    if (!serverListener.renderLandingPage) return preconditionFailed('renderLandingPage');
+    return serverListener.renderLandingPage();
+}
+
+/**
+ * Apollo plugin to render the GraphQL Sandbox page on-demand based on current server state.
+ * 
+ * Usually, the `ApolloServerPluginLandingPageLocalDefault` plugin configures its
+ * parameters once, during server startup. This plugin defers the configuration
+ * and rendering to request-time instead of server startup.
+ */
+export const sandboxPlugin: ApolloServerPlugin = {
+    serverWillStart: async (service) =>
+        ({
+            renderLandingPage: () => renderSandboxPage(service),
+        }) satisfies GraphQLServerListener,
+};
