API with NestJS #71. Introduction to feature flags

August 22, 2022

This entry is part 71 of 121 in the API with NestJS

With feature flags (also referred to as feature toggles), we can modify our application’s behavior without changing the code. In this article, we explain the purpose of feature flags. We also show how to implement them ourselves and discuss the pros and cons.

You can find the code from this article in this repository.

The idea behind feature flags

Thanks to feature flags, we can switch a certain functionality on and off during runtime without the need to deploy any new code.

async register(@Body() registrationData: RegisterDto) {

const user = await this.authenticationService.register(registrationData);

const isEmailConfirmationEnabled = await this.featureFlagsService.isEnabled('email-confirmation');

if (isEmailConfirmationEnabled) {

await this.emailConfirmationService.sendVerificationLink(

registrationData.email,

);

}

return user;

}

A feature flag, at its core, is a boolean value that we can toggle and use in if statements.

Benefits of feature flags

One of the main benefits of feature flags is that merging our changes into the master branch does not necessarily mean delivering the new feature to our users. Therefore, we get a lot of control over our application.

For example, feature flags are part of the Trunk Based Development practice, where we merge our code to the master branch very often. Since merging does not mean exposing the new feature to the users, we can merge features we haven’t finished. Thanks to that, the new feature can undergo the code review process in chunks instead of dumping a lot of code in a single pull request. The above can make it significantly easier for our teammates to review our new code.

Also, feature flags can help us minimize risks associated with deployments. If the QA team notices that the latest changes don’t work as expected in the production environment, reverting them is as easy as switching the toggle. Besides the QA team, we can also notice the issue through a monitoring system we have in place. A good example would be a sudden spike in the response time of some endpoints in our API.

Besides the above, we could build a more sophisticated feature flags system or use a third-party tool with functionalities like A/B testing. With that, we can present two versions of our application to users and determine which one they like the most.

Drawbacks of feature flags

While feature flags can benefit our application, they are not a perfect solution. They add complexity to our code that can make it harder to understand. But, what’s even worse, they create a lot of various versions of our application that, ideally, should be tested separately. For example, if we have five feature flags, it gives us 32 possible combinations.

There are two possible values for each of the five feature flags, and 2⁵ equals 32. This would be even more complicated if we would have feature flags that can have values other than booleans.

Until we test each of them separately, we can’t be entirely sure if not a single one of the combinations has an unexpected side effect. Five feature flags might seem like not a lot, but manually testing 32 separate versions of our application is probably unrealistic. It would be reasonable only to verify the combinations we expect to happen in production, but that requires that we understand the project and the business domain very well. The more flags we have, the more difficult it is to verify.

Because of that, feature flags need to be short-lived. Although it is easy to add a feature flag, it can cause us more and more effort to maintain it the longer we keep it. Therefore, we should retire the feature flag once we know that a particular feature works correctly.

Having feature flags can encourage us to merge features that are not yet finished because they are hidden behind a feature flag. We need to be very careful, though, because there is a chance that a feature might leak out by accident if not encapsulated correctly. Having to test that adds even more complexity to testing.

Implementing feature flags with NestJS

We probably want different values for feature flags in different environments, for example, in staging and production. We would also like to change the feature flags without modifying the codebase and deploying.

The most straightforward way of doing the above is storing our feature flags in a database. First, let’s define an entity for our feature flag.

featureFlag.entity.ts

import { Column, Entity, PrimaryGeneratedColumn } from 'typeorm';

@Entity()

class FeatureFlag {

@PrimaryGeneratedColumn('identity', {

generatedIdentity: 'ALWAYS',

})

id: number;

@Column({ unique: true })

name: string;

@Column()

isEnabled: boolean;

}

export default FeatureFlag;

If you want to know more about identity columns, check out Serial type versus identity columns in PostgreSQL and TypeORM

Adding, modifying, and removing feature flags is relatively straightforward. We can fit all of it into a simple service.

featureFlags.service.ts

import {

HttpException,

HttpStatus,

Injectable,

NotFoundException,

} from '@nestjs/common';

import FeatureFlag from './featureFlag.entity';

import { InjectRepository } from '@nestjs/typeorm';

import { Repository } from 'typeorm';

import CreateFeatureFlagDto from './dto/createFeatureFlag.dto';

import UpdateFeatureFlagDto from './dto/updateFeatureFlag.dto';

import PostgresErrorCode from '../database/postgresErrorCode.enum';

@Injectable()

export default class FeatureFlagsService {

constructor(

@InjectRepository(FeatureFlag)

private featureFlagsRepository: Repository<FeatureFlag>,

) {}

getAll() {

return this.featureFlagsRepository.find();

}

getByName(name: string) {

return this.featureFlagsRepository.findOneBy({ name });

}

async create(featureFlag: CreateFeatureFlagDto) {

try {

const newFlag = await this.featureFlagsRepository.create(featureFlag);

await this.featureFlagsRepository.save(newFlag);

return newFlag;

} catch (error) {

if (error?.code === PostgresErrorCode.UniqueViolation) {

throw new HttpException(

'Feature flag with that name already exists',

HttpStatus.BAD_REQUEST,

);

}

throw new HttpException(

'Something went wrong',

HttpStatus.INTERNAL_SERVER_ERROR,

);

}

async update(id: number, featureFlag: UpdateFeatureFlagDto) {

try {

await this.featureFlagsRepository.update(id, featureFlag);

} catch (error) {

if (error?.code === PostgresErrorCode.UniqueViolation) {

throw new HttpException(

'Feature flag with that name already exists',

HttpStatus.BAD_REQUEST,

);

}

throw new HttpException(

'Something went wrong',

HttpStatus.INTERNAL_SERVER_ERROR,

);

}

const updatedFeatureFlag = await this.featureFlagsRepository.findOne({

where: {

id,

});

if (updatedFeatureFlag) {

return updatedFeatureFlag;

}

throw new NotFoundException();

}

async delete(id: number) {

const deleteResponse = await this.featureFlagsRepository.delete(id);

if (!deleteResponse.affected) {

throw new NotFoundException();

}

async isEnabled(name: string) {

const featureFlag = await this.getByName(name);

if (!featureFlag) {

return false;

}

return featureFlag.isEnabled;

}

The above service is a good candidate for caching. If you want to know how to do it, check out API with NestJS #23. Implementing in-memory cache to increase the performance and API with NestJS #24. Cache with Redis. Running the app in a Node.js cluster

Besides creating a service, we can also define a controller that allows us to manage feature flags through the REST API.

featureFlags.controller.ts

import {

Body,

ClassSerializerInterceptor,

Controller,

Delete,

Get,

Param,

Patch,

Post,

UseGuards,

UseInterceptors,

} from '@nestjs/common';

import FeatureFlagsService from './featureFlags.service';

import JwtAuthenticationGuard from '../authentication/jwt-authentication.guard';

import CreateFeatureFlagDto from './dto/createFeatureFlag.dto';

import FindOneParams from '../utils/findOneParams';

import UpdateFeatureFlagDto from './dto/updateFeatureFlag.dto';

@Controller('feature-flags')

@UseInterceptors(ClassSerializerInterceptor)

export default class FeatureFlagsController {

constructor(private readonly featureFlagsService: FeatureFlagsService) {}

@Get()

getAll() {

return this.featureFlagsService.getAll();

}

@Post()

@UseGuards(JwtAuthenticationGuard)

async create(@Body() featureFlag: CreateFeatureFlagDto) {

return this.featureFlagsService.create(featureFlag);

}

@Patch(':id')

@UseGuards(JwtAuthenticationGuard)

async updateCategory(

@Param() { id }: FindOneParams,

@Body() category: UpdateFeatureFlagDto,

) {

return this.featureFlagsService.update(id, category);

}

@Delete(':id')

@UseGuards(JwtAuthenticationGuard)

async deleteCategory(@Param() { id }: FindOneParams) {

return this.featureFlagsService.delete(id);

}

It might be a good idea to develop a designated frontend application that uses the above API so that it is easy to use.

Checking the feature flags

The most straightforward way to check if a feature flag is enabled is using our FeatureFlagsService directly.

authentication.controller.ts

import {

Body,

Controller,

Post,

ClassSerializerInterceptor,

UseInterceptors,

} from '@nestjs/common';

import { AuthenticationService } from './authentication.service';

import RegisterDto from './dto/register.dto';

import { EmailConfirmationService } from '../emailConfirmation/emailConfirmation.service';

import FeatureFlagsService from '../featureFlags/featureFlags.service';

@Controller('authentication')

@UseInterceptors(ClassSerializerInterceptor)

export class AuthenticationController {

constructor(

private readonly authenticationService: AuthenticationService,

private readonly emailConfirmationService: EmailConfirmationService,

private readonly featureFlagsService: FeatureFlagsService,

) {}

@Post('register')

async register(@Body() registrationData: RegisterDto) {

const user = await this.authenticationService.register(registrationData);

const isEmailConfirmationEnabled = await this.featureFlagsService.isEnabled('email-confirmation');

if (isEmailConfirmationEnabled) {

await this.emailConfirmationService.sendVerificationLink(

registrationData.email,

);

}

return user;

}

// ...

}

The above approach might be fine if our feature is small and straightforward. But unfortunately, it could be challenging to track where we’ve used the sendVerificationLink method. So a better approach might be to use the FeatureFlagsService in the EmailConfirmationService.

emailConfirmation.service.ts

import { Injectable } from '@nestjs/common';

import { JwtService } from '@nestjs/jwt';

import { ConfigService } from '@nestjs/config';

import VerificationTokenPayload from './verificationTokenPayload.interface';

import EmailService from '../email/email.service';

import { UsersService } from '../users/users.service';

import FeatureFlagsService from '../featureFlags/featureFlags.service';

@Injectable()

export class EmailConfirmationService {

constructor(

private readonly jwtService: JwtService,

private readonly configService: ConfigService,

private readonly emailService: EmailService,

private readonly usersService: UsersService,

private readonly featureFlagsService: FeatureFlagsService,

) {}

private isEnabled() {

return this.featureFlagsService.isEnabled('email-confirmation');

}

public async sendVerificationLink(email: string) {

if (!(await this.isEnabled())) {

return;

}

const payload: VerificationTokenPayload = { email };

const token = this.jwtService.sign(payload, {

secret: this.configService.get('JWT_VERIFICATION_TOKEN_SECRET'),

expiresIn: `${this.configService.get(

'JWT_VERIFICATION_TOKEN_EXPIRATION_TIME',

)}s`,

});

const url = `${this.configService.get(

'EMAIL_CONFIRMATION_URL',

)}?token=${token}`;

const text = `Welcome to the application. To confirm the email address, click here: ${url}`;

return this.emailService.sendMail({

to: email,

subject: 'Email confirmation',

text,

});

}

// ...

}

Disabling API endpoints

Besides affecting services, we might want to disable an API endpoint defined in a controller.

emailConfirmation.controller.ts

@Post('confirm')

async confirm(@Body() confirmationData: ConfirmEmailDto, @Req() request: RequestWithUser) {

const isEmailConfirmationEnabled = await this.featureFlagsService.isEnabled(

'email-confirmation',

);

if (!isEmailConfirmationEnabled) {

throw new NotFoundException(`Cannot ${request.method} ${request.url}`);

}

const email = await this.emailConfirmationService.decodeConfirmationToken(

confirmationData.token,

);

await this.emailConfirmationService.confirmEmail(email);

}

Unfortunately, the above logic can get quite repetitive. To deal with this, we can create a guard using the mixin pattern.

featureFlag.guard.ts

import {

CanActivate,

ExecutionContext,

Injectable,

mixin,

NotFoundException,

Type,

} from '@nestjs/common';

import FeatureFlagsService from './featureFlags.service';

function FeatureFlagGuard(featureFlagName: string): Type<CanActivate> {

@Injectable()

class Guard implements CanActivate {

constructor(private readonly featureFlagsService: FeatureFlagsService) {}

async canActivate(context: ExecutionContext) {

const isEnabled = await this.featureFlagsService.isEnabled(

featureFlagName,

);

if (!isEnabled) {

const httpContext = context.switchToHttp();

const request = httpContext.getRequest();

throw new NotFoundException(`Cannot ${request.method} ${request.url}`);

}

return true;

}

return mixin(Guard);

}

export default FeatureFlagGuard;

If you want to know more about mixins, check out API with NestJS #57. Composing classes with the mixin pattern

Now, the above guard is very straightforward and makes our code clean and simple.

emailConfirmation.controller.ts

import {

Controller,

ClassSerializerInterceptor,

UseInterceptors,

Post,

Body,

UseGuards,

Req,

} from '@nestjs/common';

import ConfirmEmailDto from './confirmEmail.dto';

import { EmailConfirmationService } from './emailConfirmation.service';

import JwtAuthenticationGuard from '../authentication/jwt-authentication.guard';

import RequestWithUser from '../authentication/requestWithUser.interface';

import FeatureFlagGuard from '../featureFlags/featureFlag.guard';

@Controller('email-confirmation')

@UseInterceptors(ClassSerializerInterceptor)

export class EmailConfirmationController {

constructor(

private readonly emailConfirmationService: EmailConfirmationService,

) {}

@Post('confirm')

@UseGuards(FeatureFlagGuard('email-confirmation'))

async confirm(@Body() confirmationData: ConfirmEmailDto) {

const email = await this.emailConfirmationService.decodeConfirmationToken(

confirmationData.token,

);

await this.emailConfirmationService.confirmEmail(email);

}

@Post('resend-confirmation-link')

@UseGuards(JwtAuthenticationGuard)

@UseGuards(FeatureFlagGuard('email-confirmation'))

async resendConfirmationLink(@Req() request: RequestWithUser) {

await this.emailConfirmationService.resendConfirmationLink(request.user.id);

}

Summary

In this article, we’ve gone through the feature flags and their benefits and drawbacks. While they might help us with the process of reviewing and deploying our code, we need to be aware that they might make testing more complicated. Also, we should remove the flags we don’t need anymore.

Besides the above, we’ve also implemented a mechanism for managing feature flags using a PostgreSQL database. While doing so, we’ve used the feature flags directly through a service and a guard. There is still more to feature flags, such as A/B testing, but this is a topic for a separate article, so stay tuned!

Series Navigation<< API with NestJS #70. Defining dynamic modulesAPI with NestJS #72. Working with PostgreSQL using raw SQL queries >>