Improved external composition UX (#6752)

jdolle · web-flow · commit d0404db1cb01 · 2025-04-23T13:53:32.000-07:00
diff --git a/.changeset/tasty-poems-run.md b/.changeset/tasty-poems-run.md
@@ -0,0 +1,6 @@
+---
+'hive': patch
+---
+
+Improve external composer UX: Handle network errors gracefully, do not use native composer when
+testing, and improve settings UI
diff --git a/packages/services/api/src/modules/schema/providers/schema-manager.ts b/packages/services/api/src/modules/schema/providers/schema-manager.ts
@@ -447,15 +447,10 @@ export class SchemaManager {
       },
     });
 
-    const [project, organization] = await Promise.all([
-      this.storage.getProject({
-        organizationId: selector.organizationId,
-        projectId: selector.projectId,
-      }),
-      this.storage.getOrganization({
-        organizationId: selector.organizationId,
-      }),
-    ]);
+    const project = await this.storage.getProject({
+      organizationId: selector.organizationId,
+      projectId: selector.projectId,
+    });
 
     if (project.type !== ProjectType.FEDERATION) {
       throw new HiveError(
@@ -481,11 +476,8 @@ export class SchemaManager {
         ],
         {
           external: project.externalComposition,
-          native: this.checkProjectNativeFederationSupport({
-            project,
-            organization,
-            targetId: null,
-          }),
+          // when testing external composition, do not use native composition during the check
+          native: false,
           contracts: null,
         },
       );
diff --git a/packages/services/schema/src/composition-worker.ts b/packages/services/schema/src/composition-worker.ts
@@ -1,5 +1,7 @@
 import * as crypto from 'node:crypto';
 import type { MessagePort } from 'node:worker_threads';
+// IMPORTANT: Must use "type" to avoid runtime dependency
+import type { FastifyBaseLogger } from 'fastify';
 import type { Logger } from '@hive/api';
 import { CompositionResponse } from './api';
 import { createComposeFederation, type ComposeFederationArgs } from './composition/federation';
@@ -51,7 +53,7 @@ export function createCompositionWorker(args: {
         if (message.data.type === 'federation') {
           const composeFederation = createComposeFederation({
             decrypt,
-            logger: baseLogger.child({ reqId: message.data.args.requestId }) as any,
+            logger: baseLogger.child({ reqId: message.data.args.requestId }) as FastifyBaseLogger,
             requestTimeoutMs: message.data.requestTimeoutMs,
           });
           const composed = await composeFederation(message.data.args);
diff --git a/packages/services/schema/src/lib/compose.ts b/packages/services/schema/src/lib/compose.ts
@@ -32,24 +32,21 @@ const EXTERNAL_COMPOSITION_RESULT = z.union([
       supergraph: z.string(),
       sdl: z.string(),
     }),
-    includesNetworkError: z.boolean().optional().default(false),
+    includesNetworkError: z.boolean().default(false),
   }),
   z.object({
     type: z.literal('failure'),
     result: z.object({
-      supergraph: z.string().optional(),
-      sdl: z.string().optional(),
+      supergraph: z.string().nullish(),
+      sdl: z.string().nullish(),
       errors: z.array(
         z.object({
           message: z.string(),
-          source: z
-            .union([z.literal('composition'), z.literal('graphql')])
-            .optional()
-            .transform(value => value ?? 'graphql'),
+          source: z.union([z.literal('composition'), z.literal('graphql')]).default('graphql'),
         }),
       ),
     }),
-    includesNetworkError: z.boolean().optional().default(false),
+    includesNetworkError: z.boolean().default(false),
   }),
 ]);
 
@@ -198,8 +195,20 @@ export async function composeExternalFederation(args: {
 
   if (!parseResult.success) {
     args.logger.error('External composition failure: invalid shape of data: %o', parseResult.error);
-
-    throw new Error(`External composition failure: invalid shape of data`);
+    return {
+      type: 'failure',
+      result: {
+        supergraph: null,
+        sdl: null,
+        errors: [
+          {
+            message: 'External composition failure: invalid shape of data',
+            source: 'composition',
+          },
+        ],
+      },
+      includesNetworkError: false,
+    };
   }
 
   if (parseResult.data.type === 'success') {
@@ -314,6 +323,10 @@ async function callExternalService(
       },
       timeout: {
         request: timeoutMs,
+        // connecting should be quick
+        lookup: 10_000,
+        connect: 10_000,
+        secureConnect: 10_000,
       },
     });
 
@@ -329,7 +342,7 @@ async function callExternalService(
         span.setAttribute('error.type', error.name);
 
         logger.error(
-          'Network error without response. (errorName=%s, errorMessage=%s)',
+          'Network error during external composition without response. (errorName=%s, errorMessage=%s)',
           error.name,
           error.message,
         );
@@ -341,7 +354,7 @@ async function callExternalService(
             supergraph: null,
             errors: [
               {
-                message: `External composition network failure. Is the service reachable?`,
+                message: `A network error occurred during external composition: "${error.message}"`,
                 source: 'graphql',
               },
             ],
diff --git a/packages/web/app/src/components/project/settings/external-composition.tsx b/packages/web/app/src/components/project/settings/external-composition.tsx
@@ -1,4 +1,4 @@
-import { useCallback, useState } from 'react';
+import { useCallback, useEffect, useState } from 'react';
 import { useForm } from 'react-hook-form';
 import { useMutation, useQuery } from 'urql';
 import { z } from 'zod';
@@ -21,7 +21,7 @@ import { Switch } from '@/components/v2';
 import { FragmentType, graphql, useFragment } from '@/gql';
 import { useNotifications } from '@/lib/hooks';
 import { zodResolver } from '@hookform/resolvers/zod';
-import { CheckIcon, Cross2Icon, UpdateIcon } from '@radix-ui/react-icons';
+import { CheckIcon, Cross2Icon, ReloadIcon, UpdateIcon } from '@radix-ui/react-icons';
 
 const ExternalCompositionStatus_TestQuery = graphql(`
   query ExternalCompositionStatus_TestQuery($selector: TestExternalSchemaCompositionInput!) {
@@ -73,14 +73,20 @@ const ExternalCompositionForm_ProjectFragment = graphql(`
   }
 `);
 
+enum TestState {
+  LOADING,
+  ERROR,
+  SUCCESS,
+}
+
 const ExternalCompositionStatus = ({
   projectSlug,
   organizationSlug,
 }: {
   projectSlug: string;
   organizationSlug: string;
 }) => {
-  const [query] = useQuery({
+  const [{ data, error: gqlError, fetching }, executeTestQuery] = useQuery({
     query: ExternalCompositionStatus_TestQuery,
     variables: {
       selector: {
@@ -90,33 +96,84 @@ const ExternalCompositionStatus = ({
     },
     requestPolicy: 'network-only',
   });
+  const error = gqlError?.message ?? data?.testExternalSchemaComposition?.error?.message;
+  const testState = fetching
+    ? TestState.LOADING
+    : error
+      ? TestState.ERROR
+      : data?.testExternalSchemaComposition?.ok?.externalSchemaComposition?.endpoint
+        ? TestState.SUCCESS
+        : null;
+
+  const [hidden, setHidden] = useState<boolean>();
+
+  useEffect(() => {
+    // only hide the success icon after the duration
+    if (testState !== TestState.SUCCESS) return;
+    const timerId = setTimeout(() => {
+      if (testState === TestState.SUCCESS) {
+        setHidden(false);
+      }
+    }, 5000);
 
-  const error = query.error?.message ?? query.data?.testExternalSchemaComposition?.error?.message;
+    return () => {
+      clearTimeout(timerId);
+    };
+  }, [testState]);
 
   return (
     <TooltipProvider delayDuration={100}>
-      {query.fetching ? (
+      {testState === TestState.LOADING ? (
         <Tooltip>
           <TooltipTrigger>
-            <UpdateIcon className="size-5 animate-spin text-gray-500" />
+            <UpdateIcon
+              className="size-5 animate-spin cursor-default text-gray-500"
+              onClick={e => e.preventDefault()}
+            />
           </TooltipTrigger>
-          <TooltipContent side="right">Connecting...</TooltipContent>
+          <TooltipContent side="left">Connecting...</TooltipContent>
         </Tooltip>
-      ) : null}
-      {error ? (
+      ) : (
         <Tooltip>
           <TooltipTrigger>
-            <Cross2Icon className="size-5 text-red-500" />
+            <ReloadIcon
+              className="size-5"
+              onClick={e => {
+                e.preventDefault();
+                setHidden(true);
+                executeTestQuery();
+              }}
+            />
+          </TooltipTrigger>
+          <TooltipContent side="top" className="mr-1">
+            Execute test
+          </TooltipContent>
+        </Tooltip>
+      )}
+      {testState === TestState.ERROR ? (
+        <Tooltip defaultOpen>
+          <TooltipTrigger>
+            <Cross2Icon
+              className="size-5 cursor-default text-red-500"
+              onClick={e => e.preventDefault()}
+            />
           </TooltipTrigger>
-          <TooltipContent side="right">{error}</TooltipContent>
+          <TooltipContent side="right" className="max-w-sm">
+            {error}
+          </TooltipContent>
         </Tooltip>
       ) : null}
-      {query.data?.testExternalSchemaComposition?.ok?.externalSchemaComposition?.endpoint ? (
+      {testState === TestState.SUCCESS && !hidden ? (
         <Tooltip>
           <TooltipTrigger>
-            <CheckIcon className="size-5 text-green-500" />
+            <CheckIcon
+              className="size-5 cursor-default text-green-500"
+              onClick={e => e.preventDefault()}
+            />
           </TooltipTrigger>
-          <TooltipContent side="right">Service is available</TooltipContent>
+          <TooltipContent side="right" className="max-w-sm">
+            Service is available
+          </TooltipContent>
         </Tooltip>
       ) : null}
     </TooltipProvider>
@@ -148,6 +205,8 @@ const ExternalCompositionForm = ({
   project: FragmentType<typeof ExternalCompositionForm_ProjectFragment>;
   organization: FragmentType<typeof ExternalCompositionForm_OrganizationFragment>;
   endpoint?: string;
+  isNativeCompositionEnabled?: boolean;
+  onClickDisable?: () => void;
 }) => {
   const project = useFragment(ExternalCompositionForm_ProjectFragment, props.project);
   const organization = useFragment(
@@ -176,10 +235,11 @@ const ExternalCompositionForm = ({
       },
     }).then(result => {
       if (result.data?.enableExternalSchemaComposition?.ok) {
-        notify('External composition enabled', 'success');
         const endpoint =
           result.data?.enableExternalSchemaComposition?.ok.externalSchemaComposition?.endpoint;
 
+        notify('External composition enabled.', 'success');
+
         if (endpoint) {
           form.reset(
             {
@@ -230,10 +290,10 @@ const ExternalCompositionForm = ({
               <FormItem>
                 <FormLabel>HTTP Endpoint</FormLabel>
                 <FormDescription>A POST request will be sent to that endpoint</FormDescription>
-                <div className="flex w-full max-w-sm items-center space-x-2">
+                <div className="flex w-full items-center space-x-2">
                   <FormControl>
                     <Input
-                      className="w-96 shrink-0"
+                      className="max-w-md shrink-0"
                       placeholder="Endpoint"
                       type="text"
                       autoComplete="off"
@@ -265,7 +325,7 @@ const ExternalCompositionForm = ({
                 </FormDescription>
                 <FormControl>
                   <Input
-                    className="w-96"
+                    className="w-full max-w-md"
                     placeholder="Secret"
                     type="password"
                     autoComplete="off"
@@ -279,10 +339,26 @@ const ExternalCompositionForm = ({
           {mutation.error && (
             <div className="mt-2 text-xs text-red-500">{mutation.error.message}</div>
           )}
-          <div>
+          {props.isNativeCompositionEnabled ? (
+            <DocsNote warn className="mt-0 max-w-2xl">
+              Native Federation v2 composition is currently enabled. Until native composition is
+              disabled, External Schema Composition won't have any effect.
+            </DocsNote>
+          ) : null}
+          <div className="flex flex-row items-center gap-x-8">
             <Button type="submit" disabled={form.formState.isSubmitting}>
-              Save
+              Save Configuration
             </Button>
+            {props.onClickDisable ? (
+              <Button
+                variant="destructive"
+                type="button"
+                disabled={mutation.fetching || form.formState.isSubmitting}
+                onClick={props.onClickDisable}
+              >
+                Disable External Composition
+              </Button>
+            ) : null}
           </div>
         </form>
       </Form>
@@ -403,27 +479,25 @@ export const ExternalCompositionSettings = (props: {
             )}
           </div>
         </CardTitle>
+        <CardDescription className="max-w-2xl">
+          For advanced users, you can configure an endpoint for external schema compositions. This
+          can be used to implement custom composition logic.
+        </CardDescription>
         <CardDescription>
-          <ProductUpdatesLink href="#native-composition">
-            Enable native Apollo Federation v2 support in Hive
+          <ProductUpdatesLink href="https://the-guild.dev/graphql/hive/docs/features/external-schema-composition">
+            Read about external schema composition in our documentation.
           </ProductUpdatesLink>
         </CardDescription>
       </CardHeader>
 
       <CardContent>
-        {isNativeCompositionEnabled && isEnabled ? (
-          <DocsNote warn className={isFormVisible ? 'mb-6 mt-0' : ''}>
-            It appears that Native Federation v2 Composition is activated and will be used instead.
-            <br />
-            External composition won't have any effect.
-          </DocsNote>
-        ) : null}
-
         {isFormVisible ? (
           <ExternalCompositionForm
             project={project}
             organization={organization}
             endpoint={externalCompositionConfig?.endpoint}
+            isNativeCompositionEnabled={isNativeCompositionEnabled}
+            onClickDisable={() => handleSwitch(false)}
           />
         ) : (
           <Button disabled={mutation.fetching} onClick={() => handleSwitch(true)}>
diff --git a/packages/web/app/src/components/project/settings/native-composition.tsx b/packages/web/app/src/components/project/settings/native-composition.tsx
@@ -227,7 +227,9 @@ export function NativeCompositionSettings(props: {
         <CardTitle>
           <a id="native-composition">Native Federation v2 Composition</a>
         </CardTitle>
-        <CardDescription>Native Apollo Federation v2 support for your project.</CardDescription>
+        <CardDescription>
+          Recommended for most users. Use native Apollo Federation v2 composition for your project.
+        </CardDescription>
 
         {display !== 'enabled' ? (
           <CardDescription>
diff --git a/packages/web/app/src/pages/project-settings.tsx b/packages/web/app/src/pages/project-settings.tsx
diff --git a/packages/web/docs/src/components/cli-errors.tsx b/packages/web/docs/src/components/cli-errors.tsx
