@ikualo/lib-error-backend v0.1.3

lib-error-backend

lib-error-backend is a library for error management for the Íkualo Microservices Ecosystem. This library creates a standard for creating, throwing and filtering errors in all microservices, for them to be organized, less error-prone and easier for developers to maintain and contribute to.

This library is centered around two core concepts:

• As we have lots of microservices in the Íkualo Ecosystem, we need a way to ensure all errors are thrown in the same way, shape, and form.
• As the project grows, we need to ensure that the microservices throw errors that can be easily traceable and manageable from any point in the system.

Getting Started

This library is expected to work primarily for applications running on Nest.js, as the filters, exceptions and other utilities are designed for this framework.

Installing the Library

Before using the library, we need to install it. We’ll use npm for this example:

!NOTE The recommended package manager in the Íkualo Organization is Yarn, but any other package manager can be used.

# Install the latest version.
npm install @ikualo/lib-error-backend@latest

!WARNING > This name might change in the future! As the development of the library grows, the name is ought to suffer some changes, and it might not be the same later.

Updating the Environment

The library makes use of the UNKNOWN_ERROR_CODE environment variable. This variable is set to know from which microservice the error is being thrown. If the environment variable is not set, the library will fill the code property with the value IKUALO-999.

Using the Library

For the usage of the library, we expect two different usages; the custom HTTP and RPC filters, and the throwing of exceptions. We’ll start registering the filters for the exceptions.

We’ll use the HTTP services as examples here, but the same can be done for an RPC service. The usage is the same, as the Nest.js documentation says.

Registering the Filters

There are 4 types of filters in the library, and they are as:

• CustomHttpExceptionFilter
• UnknownHttpExceptionFilter
• CustomRpcExceptionFilter
• UnknownRpcExceptionFilter

The custom filters are used to filter any custom exception that we would want to throw. The unknown filters are used to filter any other exception that the system would throw. We will see more about throwing exceptions later.

There are two main ways in which you might want to use the filters; registering the filter in a controller, and registering the filter globally. We recommend you do globally, but it’s not mandatory. We’ll see examples for both now.

!NOTE The usage of both of them at the same time is not mandatory. You can use one or another, but we strongly recommend you use both of them. This ensures that the microservice will behave as we all expect in the team.

Registering the Filters Globally

As seen in the Nest.js documentation, you can register filters globally. We would want to register the UnknownHttpExceptionFilter, and the CustomHttpExceptionFilter as global filters in the bootstraping file of the Nest.js application. Something like:

// src/main.ts

import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";

async function bootstrap() {
    const app = await NestFactory.create(AppModule);

    // Register them here.
    app.useGlobalFilters(
        new UnknownHttpExceptionFilter(),
        new CustomHttpExceptionFilter(),
    );

    await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

After doing this, the filters are registered globally, and any exception you throw from any controller or service, will be handled correctly. This is the recommended way to use this library.

Registering the Filters in a Controller

For this, we need to take into account the usage of filters from Nest.js, you can read more in their documentation. For now, we will create a simple test HTTP controller.

import { Controller, Get } from "@nestjs/common";

@Controller()
class TestController {
    @Get("string")
    getString(): number {
        return "Ikualo";
    }
}

After this, we want to add the two main filters from this library, made for the HTTP pipeline, the UnknownHttpExceptionFilter, and the CustomHttpExceptionFilter. Both of them are needed for using the full potential of this library, like:

import { Controller, Get, UseFilters } from "@nestjs/common";

import { UnknownHttpExceptionFilter } from "../lib/unknown-http-exception.filter";
import { CustomHttpExceptionFilter } from "../lib/custom-http-exception.filter";

@Controller()
@UseFilters(UnknownHttpExceptionFilter, CustomHttpExceptionFilter)
class TestController {
    @Get("string")
    getString(): number {
        return "Ikualo";
    }
}

!WARNING > This is not the recommended way to use the library. You can still use the filters with controllers, but you’ll have to write them on every controller you use, so it can introduce a lot of boiler plate, and you can forget to add the filter.

Throwing Exceptions

As we currently have in our simple test HTTP controller, everything should be fine. The service, when called, should return a string with the value: "Ikualo". To see the library in action, we would want to add a throw with the CustomHttpException exception, something like:

import { Controller, Get, UseFilters } from "@nestjs/common";

import { UnknownHttpExceptionFilter } from "../lib/unknown-http-exception.filter";
import { CustomHttpExceptionFilter } from "../lib/custom-http-exception.filter";
import { CustomHttpException } from "../lib/custom-http-exception";

@Controller()
@UseFilters(UnknownHttpExceptionFilter, CustomHttpExceptionFilter)
class TestController {
    @Get("string")
    getString(): number {
        throw new CustomHttpException({
            status: 500,
            code: "IKUALO-TEST-001",
            message: "This is an expected test exception!",
        });
    }
}

Throwing a CustomHttpException ensures that the CustomHttpExceptionFilter will handle the exception automatically as expected.

The Rust Book has a very interesting take in the Error Handling section of the book, and it talks about distinguishing between expected errors, unexpected errors and irrecoverable errors. The CustomHttpException is an example of an expected error.

When the system throws any other kind of exception, the UnknownHttpExceptionFilter will catch it, and return more information about it. This ensures that all microsystems in the Íkualo Ecosystem will throw the same kind of information in the errors. Just that some of them will be expected errors, and some others (hopefully none) will be unexpected errors.