feat(Feat/error handling): Handled GraphQL errors according to the graphql error guide (#41)

* docs: add graphql status description

* chore: remove old stuff

* Merge branch 'main' of https://github.com/Ho-s/NestJS-GraphQL-TypeORM-PostgresQL into feat/error-handling

* fix: update no-unused-vars rule in ESLint configuration

* feat: add GraphQL exception silencer filter

* feat: implement base exception handling with customizable messages

* feat: replace BadRequestException with CustomConflictException for username conflict

* feat: implement custom error handling with GraphQL error formatter and HTTP status plugin

* docs: add ref about graphql built in error

* refactor: replace UnauthorizedException with CustomUnauthorizedException and update error handling across strategies and services

* feat: add GraphQL request validation for content type and handle Not Acceptable responses

Author: Ho-s

README.md

@@ -32,6 +32,7 @@ NestJS boilerplate with TypeORM, GraphQL and PostgreSQL
   - [7.1. Protected Queries/Mutation By Role](#71-protected-queriesmutation-by-role)
   - [7.2. GraphQL Query To Select and Relations](#72-graphql-query-to-select-and-relations)
   - [7.3. Field-Level Permission](#73-field-level-permission)
+  - [7.4. GraphQL Status Code](#74-graphql-status-code)
 
 - [8. Custom CRUD](#8-custom-crud)
 
@@ -290,6 +291,11 @@ With this API, if the client request includes the field "something," a `Forbidde
 
 There might be duplicate code when using this guard alongside `other interceptors`(name: `UseRepositoryInterceptor`) in this boilerplate. In such cases, you may need to adjust the code to ensure compatibility.
 
+### 7.4. GraphQL Status Code
+
+Based on the GraphQL status code standard, we write status codes accordingly.
+You can see more details [here](./graphql-status-code.md).
+
 ## 8. Custom CRUD
 
 To make most of GraphQL's advantage, We created its own api, such as GetMany or GetOne.
@@ -503,8 +509,6 @@ db.public.registerFunction({
 - [x] Divide usefactory
 - [x] SWC Compiler
 - [x] Refresh Token
-- [ ] Redis
-- [ ] ElasticSearch
 - [x] Caching
 - [ ] Graphql Subscription
 - [x] Remove lodash

error.md

@@ -48,6 +48,10 @@ export default [
       '@typescript-eslint/explicit-function-return-type': 'off',
       '@typescript-eslint/explicit-module-boundary-types': 'off',
       '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-unused-vars': [
+        'warn',
+        { argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
+      ],
     },
   },
 ];

eslint.config.mjs

@@ -0,0 +1,98 @@
+# GraphQL Response Status Codes
+
+- [HTTP Status Codes](#http-status-codes)
+  - [✅ 200 OK Responses](#200-ok-responses)
+    - [Successful Request](#✅-successful-request)
+    - [Partial Success](#⚠️-partial-success-some-data--some-errors)
+    - [No Data (e.g., NotFoundErrorException)](#⚠️-no-data-eg-notfounderrorexception)
+  - [❌ Non-200 Responses](#non-200-responses)
+    - [Bad Request (Invalid JSON, Syntax Error, etc.)](#❌-bad-request-invalid-json-syntax-error-etc)
+    - [Authentication/Authorization Failure](#❌-authenticationauthorization-failure)
+    - [Unsupported Accept Header](#❌-unsupported-accept-header)
+    - [Internal Server Error](#❌-internal-server-error)
+- [Summary Table](#summary-table)
+- [References](#references)
+
+## HTTP Status Codes
+
+GraphQL generally follows standard HTTP status code conventions, with some GraphQL-specific nuances.
+
+### 200 OK Responses
+
+#### ✅ Successful Request
+
+- **HTTP Status Code**: `200 OK`
+- **Data**: Not `null`
+- **Errors**: `N/A`
+
+#### ⚠️ Partial Success (Some Data & Some Errors)
+
+- **HTTP Status Code**: `200 OK`
+- **Data**: Not `null`
+- **Errors**: `Array<GraphQLError>` (length ≥ 1)
+
+#### ⚠️ No Data (e.g., NotFoundErrorException)
+
+When a GraphQL response includes only errors and no data, the [GraphQL over HTTP specification](https://github.com/graphql/graphql-over-http/blob/main/spec/GraphQLOverHTTP.md#applicationjson) mandates the use of `200 OK`.
+
+- **HTTP Status Code**: `200 OK`
+- **Data**: `null`
+- **Errors**: `Array<GraphQLError>` (length ≥ 1)
+
+### Non-200(OK) Responses
+
+#### ❌ Bad Request (Invalid JSON, Syntax Error, etc.)
+
+Used when the GraphQL request is malformed or invalid.
+
+- **HTTP Status Code**: `400 Bad Request`
+- **Data**: `null`
+- **Errors**: `Array<GraphQLError>` (length = 1)
+
+ref: [built-in-error-codes](https://www.apollographql.com/docs/apollo-server/data/errors#built-in-error-codes)
+
+#### ❌ Authentication/Authorization Failure
+
+Used when the request is unauthenticated or the client lacks required permissions.
+
+- **HTTP Status Code**: `401 Unauthorized`, `403 Forbidden`
+- **Data**: `null`
+- **Errors**: `Array<GraphQLError>` (length = 1)
+
+#### ❌ Unsupported Accept Header
+
+Returned when the request’s `Accept` header does not include `application/graphql-response+json`.
+
+While most GraphQL errors are handled via a custom `formatError`, HTTP-level errors like `406 Not Acceptable` should be handled early (e.g., using middleware and apply globally).
+
+- **HTTP Status Code**: `406 Not Acceptable`
+- **Data**: `null`
+- **Errors**: `Array<GraphQLError>` (length = 1)
+
+#### ❌ Internal Server Error
+
+Used when an unexpected server-side error or unhandled exception occurs.
+
+- **HTTP Status Code**: `500 Internal Server Error`
+- **Data**: `null`
+- **Errors**: `Array<GraphQLError>` (length = 1)
+
+## Summary Table
+
+| Scenario                      | HTTP Status | Data | Errors |
+| ----------------------------- | ----------- | ---- | ------ |
+| Success                       | 200         | ✅   | ❌     |
+| Partial Success               | 200         | ✅   | ✅     |
+| No Data                       | 200         | ❌   | ✅     |
+| Invalid Request (Syntax, etc) | 400         | ❌   | ✅     |
+| Auth Failure                  | 401 / 403   | ❌   | ✅     |
+| Unsupported Accept Header     | 406         | ❌   | ✅     |
+| Internal Server Error         | 500         | ❌   | ✅     |
+
+## References
+
+This error-handling approach follows the [GraphQL over HTTP specification](https://graphql.github.io/graphql-over-http/draft/), which is currently in draft status and subject to change.
+
+- [GraphQL over HTTP - Status Codes](https://graphql.org/learn/serving-over-http/#status-codes)
+- [GraphQL Over HTTP Specification (GitHub)](https://github.com/graphql/graphql-over-http/blob/main/spec/GraphQLOverHTTP.md)
+- [GraphQL over HTTP (Draft)](https://graphql.github.io/graphql-over-http/draft/)

graphql-status-code.md

@@ -1,10 +1,11 @@
-import { BadRequestException, Injectable } from '@nestjs/common';
+import { Injectable } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
 import { JwtService } from '@nestjs/jwt';
 
 import * as bcrypt from 'bcrypt';
 
 import { SignInInput, SignUpInput } from 'src/auth/inputs/auth.input';
+import { CustomConflictException } from 'src/common/exceptions';
 import { EnvironmentVariables } from 'src/common/helper/env.validation';
 import { UtilService } from 'src/common/util/util.service';
 import { User } from 'src/user/entities/user.entity';
@@ -58,12 +59,12 @@ export class AuthService {
   }
 
   async signUp(input: SignUpInput): Promise<JwtWithUser> {
-    const doesExistId = await this.userService.getOne({
+    const doesExist = await this.userService.getOne({
       where: { username: input.username },
     });
 
-    if (doesExistId) {
-      throw new BadRequestException('Username already exists');
+    if (doesExist) {
+      throw new CustomConflictException({ property: 'username' });
     }
 
     const user = await this.userService.create({ ...input, role: 'user' });

src/auth/auth.service.ts

@@ -1,9 +1,10 @@
-import { Injectable, UnauthorizedException } from '@nestjs/common';
+import { Injectable } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
 import { PassportStrategy } from '@nestjs/passport';
 
 import { ExtractJwt, Strategy, VerifiedCallback } from 'passport-jwt';
 
+import { CustomUnauthorizedException } from 'src/common/exceptions';
 import { EnvironmentVariables } from 'src/common/helper/env.validation';
 
 import { AuthService } from '../auth.service';
@@ -35,7 +36,7 @@ export class JwtRefreshStrategy extends PassportStrategy(
 
       done(null, userData);
     } catch (err) {
-      throw new UnauthorizedException('Error', err.message);
+      throw new CustomUnauthorizedException({ message: err.message });
     }
   }
 }

src/auth/strategies/jwt-refresh.strategy.ts

@@ -1,9 +1,10 @@
-import { Injectable, UnauthorizedException } from '@nestjs/common';
+import { Injectable } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
 import { PassportStrategy } from '@nestjs/passport';
 
 import { ExtractJwt, Strategy, VerifiedCallback } from 'passport-jwt';
 
+import { CustomUnauthorizedException } from 'src/common/exceptions';
 import { EnvironmentVariables } from 'src/common/helper/env.validation';
 
 import { UserService } from '../../user/user.service';
@@ -29,7 +30,7 @@ export class JwtStrategy extends PassportStrategy(Strategy, 'jwt') {
 
       done(null, userData);
     } catch (err) {
-      throw new UnauthorizedException('Error', err.message);
+      throw new CustomUnauthorizedException({ message: err.message });
     }
   }
 }

src/auth/strategies/jwt.strategy.ts

@@ -1,8 +1,10 @@
-import { Injectable, UnauthorizedException } from '@nestjs/common';
+import { Injectable } from '@nestjs/common';
 import { PassportStrategy } from '@nestjs/passport';
 
 import { Strategy } from 'passport-local';
 
+import { CustomUnauthorizedException } from 'src/common/exceptions';
+
 import { AuthService } from '../auth.service';
 import { SignInInput } from '../inputs/auth.input';
 
@@ -18,7 +20,7 @@ export class LocalStrategy extends PassportStrategy(Strategy, 'local') {
     const user = this.authService.validateUser({ username, password });
 
     if (!user) {
-      throw new UnauthorizedException();
+      throw new CustomUnauthorizedException();
     }
 
     return user;

src/auth/strategies/local.strategy.ts

@@ -1,5 +1,5 @@
 import { ApolloDriverConfig } from '@nestjs/apollo';
-import { Injectable } from '@nestjs/common';
+import { Injectable, Logger } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
 import { GqlOptionsFactory } from '@nestjs/graphql';
 
@@ -11,7 +11,7 @@ import GraphQLJSON from 'graphql-type-json';
 import { join } from 'path';
 import { cwd } from 'process';
 
-import { formatError } from '../format/graphql-error.format';
+import { httpStatusPlugin } from '../exceptions/exception.plugin';
 
 @Injectable()
 export class GraphqlConfigService
@@ -29,14 +29,14 @@ export class GraphqlConfigService
       sortSchema: true,
       playground: false,
       plugins: [
+        httpStatusPlugin,
         this.configService.get('NODE_ENV') === 'production'
           ? ApolloServerPluginLandingPageProductionDefault()
           : ApolloServerPluginLandingPageLocalDefault(),
       ],
 
       context: ({ req }) => ({ req }),
       cache: 'bounded',
-      formatError,
     };
   }
 }

src/common/config/graphql-config.service.ts

@@ -0,0 +1,11 @@
+import { ArgumentsHost, Catch, ExceptionFilter } from '@nestjs/common';
+import { GqlArgumentsHost } from '@nestjs/graphql';
+
+@Catch()
+export class GraphQLExceptionSilencer implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    GqlArgumentsHost.create(host);
+
+    throw exception;
+  }
+}