feat: document the errors that each endpoint throws in Swagger and Apollo (#1353)

* feat: document errors in swagger per endpoint

* fix: address code review feedback

* refactor: code improvements

* fix: additional code improvements based on code review feedback

* feat: document errors in apollo server playground

* fix: comment out log to avoid clutter

Author: krigol14

libraries/grpc-sdk/src/interfaces/Route.ts

@@ -1,5 +1,6 @@
 import { allowedTypes, ConduitModel, TYPE } from './Model.js';
 import { Indexable } from './Indexable.js';
+import { ModuleErrorDefinition } from '@conduitplatform/module-tools';
 
 export interface ConduitRouteParameters {
   params?: Indexable;
@@ -61,6 +62,7 @@ export interface ConduitRouteOptions {
   description?: string;
   middlewares?: string[];
   cacheControl?: string;
+  errors?: ModuleErrorDefinition[];
 }
 
 export interface ConduitRouteObject {

libraries/hermes/src/GraphQl/GraphQL.ts

@@ -177,7 +177,14 @@ export class GraphQLController extends ConduitRouter {
 
     let description = '';
     if (input.description) {
-      description = `""" ${input.description} """ `;
+      description = `""" ${input.description}`;
+      if (Array.isArray(input.errors) && input.errors.length > 0) {
+        description += `\n\nPossible errors:\n\n`;
+        input.errors.forEach((err: { conduitCode: string; description: string }) => {
+          description += `- ${err.conduitCode}: ${err.description}\n\n`;
+        });
+      }
+      description += ' """ ';
     }
 
     const finalName = description + name + params + ':' + returnType;

libraries/hermes/src/GraphQl/utils/Request.utils.ts

@@ -1,45 +1,44 @@
 import { ConduitGrpcSdk, ConduitError } from '@conduitplatform/grpc-sdk';
 import { GraphQLError } from 'graphql';
+import { mapGrpcErrorToHttp } from '../../Rest/util.js';
 
 export const errorHandler = (err: Error | ConduitError | any) => {
-  ConduitGrpcSdk.Logger.error(err);
   if (err.hasOwnProperty('status')) {
+    ConduitGrpcSdk.Logger.error(err);
     throw new GraphQLError(err.message, {
       extensions: { code: (err as ConduitError).status.toString() },
       originalError: err,
     });
-  } else if (err.hasOwnProperty('code')) {
-    switch (err.code) {
-      case 3:
-        throw new GraphQLError(err.details, {
-          extensions: { code: '400' },
-          originalError: err,
-        });
-      case 5:
-        throw new GraphQLError(err.details, {
-          extensions: { code: '404' },
-          originalError: err,
-        });
-      case 7:
-        throw new GraphQLError(err.details, {
-          extensions: { code: '403' },
-          originalError: err,
-        });
-      case 16:
-        throw new GraphQLError(err.details, {
-          extensions: { code: '401' },
-          originalError: err,
-        });
-      default:
-        throw new GraphQLError(err.details, {
-          extensions: { code: '500' },
-          originalError: err,
-        });
+  }
+  if (err.hasOwnProperty('code')) {
+    const { status } = mapGrpcErrorToHttp(err.code);
+    let parsed: { message: string; conduitCode: string } | null = null;
+    try {
+      parsed = JSON.parse(err.details);
+    } catch (e) {
+      // The below line is commented out to avoid cluttering the logs since most errors will not have a parsable details field.
+      // console.warn('Error parsing details:', e);
+    }
+    if (parsed && typeof parsed === 'object') {
+      ConduitGrpcSdk.Logger.error(parsed.message);
+      throw new GraphQLError(parsed.message, {
+        extensions: {
+          code: status,
+          conduitCode: parsed.conduitCode,
+        },
+        originalError: err,
+      });
+    } else {
+      ConduitGrpcSdk.Logger.error(err);
+      throw new GraphQLError(err.details, {
+        extensions: { code: status },
+        originalError: err,
+      });
     }
-  } else {
-    throw new GraphQLError(err.message, {
-      extensions: { code: '500' },
-      originalError: err,
-    });
   }
+  ConduitGrpcSdk.Logger.error(err);
+  throw new GraphQLError(err.message, {
+    extensions: { code: '500' },
+    originalError: err,
+  });
 };

libraries/hermes/src/Rest/Rest.ts

@@ -7,7 +7,7 @@ import {
   Router,
 } from 'express';
 import { SwaggerGenerator } from './Swagger.js';
-import { extractRequestData, validateParams } from './util.js';
+import { extractRequestData, mapGrpcErrorToHttp, validateParams } from './util.js';
 import { createHashKey, extractCaching } from '../cache.utils.js';
 import { ConduitRouter } from '../Router.js';
 import {
@@ -241,45 +241,41 @@ export class RestController extends ConduitRouter {
 
   handleError(res: Response): (err: Error | ConduitError) => void {
     return (err: Error | ConduitError | any) => {
-      ConduitGrpcSdk.Logger.error(err);
       if (err.hasOwnProperty('status')) {
+        ConduitGrpcSdk.Logger.error(err);
         return res.status((err as ConduitError).status).json({
           name: err.name,
           status: (err as ConduitError).status,
           message: err.message,
         });
       }
       if (err.hasOwnProperty('code')) {
-        let statusCode: number;
-        let name: string;
-        switch (err.code) {
-          case 3:
-            name = 'INVALID_ARGUMENTS';
-            statusCode = 400;
-            break;
-          case 5:
-            name = 'NOT_FOUND';
-            statusCode = 404;
-            break;
-          case 7:
-            name = 'FORBIDDEN';
-            statusCode = 403;
-            break;
-          case 16:
-            name = 'UNAUTHORIZED';
-            statusCode = 401;
-            break;
-          default:
-            name = 'INTERNAL_SERVER_ERROR';
-            statusCode = 500;
-            break;
+        const { status, name } = mapGrpcErrorToHttp(err.code);
+        let parsed: { message: string; conduitCode: string } | null = null;
+        try {
+          parsed = JSON.parse(err.details);
+        } catch (e) {
+          // The below line is commented out to avoid cluttering the logs since most errors will not have a parsable details field.
+          // console.warn('Error parsing details:', e);
+        }
+        if (parsed && typeof parsed === 'object') {
+          ConduitGrpcSdk.Logger.error(parsed.message);
+          return res.status(status).json({
+            name,
+            status,
+            message: parsed.message,
+            conduitCode: parsed.conduitCode,
+          });
+        } else {
+          ConduitGrpcSdk.Logger.error(err);
+          return res.status(status).json({
+            name,
+            status,
+            message: err.details,
+          });
         }
-        return res.status(statusCode).json({
-          name,
-          status: statusCode,
-          message: err.details,
-        });
       }
+      ConduitGrpcSdk.Logger.error(err);
       res.status(500).json({
         name: 'INTERNAL_SERVER_ERROR',
         status: 500,

libraries/hermes/src/Rest/Swagger.ts

@@ -5,6 +5,19 @@ import { SwaggerRouterMetadata } from '../types/index.js';
 import { ConduitRoute } from '../classes/index.js';
 import { importDbTypes } from '../utils/types.js';
 import { processSwaggerParams } from './SimpleTypeParamUtils.js';
+import { mapGrpcErrorToHttp } from './util.js';
+
+interface SwaggerExample {
+  name: string;
+  message: string;
+  conduitCode: string;
+}
+
+interface SwaggerResponseContent {
+  schema: { $ref: string };
+  example?: SwaggerExample;
+  examples?: Record<string, { value: SwaggerExample }>;
+}
 
 export class SwaggerGenerator {
   private _swaggerDoc: Indexable;
@@ -31,6 +44,24 @@ export class SwaggerGenerator {
           ModelId: {
             type: 'string',
           },
+          ErrorResponse: {
+            type: 'object',
+            properties: {
+              name: {
+                type: 'string',
+                description: 'HTTP error name',
+              },
+              message: {
+                type: 'string',
+                description: 'Error message',
+              },
+              conduitCode: {
+                type: 'string',
+                description: 'Conduit internal error code',
+              },
+            },
+            required: ['httpCode', 'conduitCode', 'description'],
+          },
         },
         securitySchemes: this._routerMetadata.securitySchemes,
       },
@@ -152,6 +183,70 @@ export class SwaggerGenerator {
       this._swaggerDoc.paths[path] = {};
       this._swaggerDoc.paths[path][method] = routeDoc;
     }
+
+    const errors = route.input.errors || [];
+    const errorGroups: Record<
+      string,
+      Record<
+        string,
+        { name: string; message: string; conduitCode: string; description: string }[]
+      >
+    > = {};
+    for (const error of errors) {
+      const { conduitCode, grpcCode, message, description } = error;
+      const { name, status } = mapGrpcErrorToHttp(grpcCode);
+      if (!errorGroups[status]) errorGroups[status] = {};
+      if (!errorGroups[status][conduitCode]) errorGroups[status][conduitCode] = [];
+      errorGroups[status][conduitCode].push({
+        name,
+        message,
+        conduitCode,
+        description,
+      });
+    }
+
+    for (const status in errorGroups) {
+      const allExamples: {
+        name: string;
+        message: string;
+        conduitCode: string;
+        description: string;
+      }[] = [];
+      for (const conduitCode in errorGroups[status]) {
+        allExamples.push(...errorGroups[status][conduitCode]);
+      }
+      const responseContent: { 'application/json': SwaggerResponseContent } = {
+        'application/json': {
+          schema: {
+            $ref: '#/components/schemas/ErrorResponse',
+          },
+        },
+      };
+      if (allExamples.length === 1) {
+        responseContent['application/json']['example'] = {
+          name: allExamples[0].name,
+          message: allExamples[0].message,
+          conduitCode: allExamples[0].conduitCode,
+        };
+      } else if (allExamples.length > 1) {
+        responseContent['application/json']['examples'] = {};
+        allExamples.forEach(example => {
+          const { name, message, conduitCode, description } = example;
+          if (responseContent['application/json']['examples']) {
+            responseContent['application/json']['examples'][description] = {
+              value: {
+                name,
+                message,
+                conduitCode,
+              },
+            };
+          }
+        });
+      }
+      routeDoc.responses[status] = {
+        content: responseContent,
+      };
+    }
   }
 
   private _extractMethod(action: string) {

libraries/hermes/src/Rest/util.ts

@@ -229,3 +229,24 @@ function validateType(
 function isValidDate(date: Date): boolean {
   return !isNaN(date.getHours());
 }
+
+export function mapGrpcErrorToHttp(gRPCErrorCode: number): {
+  name: string;
+  status: number;
+} {
+  switch (gRPCErrorCode) {
+    case 3:
+      return { name: 'INVALID_ARGUMENTS', status: 400 };
+    case 5:
+      return { name: 'NOT_FOUND', status: 404 };
+    // TODO: Enable this case once conflict error handling is implemented. Currently commented out to avoid introducing a breaking change.
+    // case 6:
+    //   return { name: 'CONFLICT', status: 409 };
+    case 7:
+      return { name: 'FORBIDDEN', status: 403 };
+    case 16:
+      return { name: 'UNAUTHORIZED', status: 401 };
+    default:
+      return { name: 'INTERNAL_SERVER_ERROR', status: 500 };
+  }
+}

libraries/module-tools/src/classes/ModuleError.ts

@@ -0,0 +1,18 @@
+import { GrpcError } from '@conduitplatform/grpc-sdk';
+import { ModuleErrorDefinition } from '../interfaces';
+
+export class ModuleError extends GrpcError {
+  debugLogInfo?: string;
+
+  constructor(errorDefinition: ModuleErrorDefinition, debugLogInfo?: string) {
+    const { grpcCode, conduitCode, message } = errorDefinition;
+    super(
+      grpcCode,
+      JSON.stringify({
+        message,
+        conduitCode: conduitCode,
+      }),
+    );
+    if (debugLogInfo) this.debugLogInfo = debugLogInfo;
+  }
+}

libraries/module-tools/src/index.ts

@@ -4,3 +4,4 @@ export * from './classes/index.js';
 export * from './helpers/index.js';
 export * from './routing/index.js';
 export * from './utilities/index.js';
+export * from './classes/ModuleError.js';

libraries/module-tools/src/interfaces/ModuleErrorDefinition.ts

@@ -0,0 +1,6 @@
+export interface ModuleErrorDefinition {
+  grpcCode: number;
+  conduitCode: string;
+  message: string;
+  description: string;
+}

libraries/module-tools/src/interfaces/index.ts

@@ -1,2 +1,3 @@
 export * from './ConduitService.js';
 export * from './ModuleLifecycleStage.js';
+export * from './ModuleErrorDefinition.js';