DEV Community: Jérôme Navez

Spring Boot - Implementing a Distributed Task Scheduler (without queue)

Jérôme Navez — Sat, 14 Oct 2023 15:13:35 +0000

When developing a service, one of the challenges you could face is the need to execute tasks that run automatically and periodically.
Those tasks could contain undefined and/or unpredictable amounts of work and load, so the need to have a scalable architecture is strong.

Limiting the implementation of this challenge to simple @Scheduled annotations is not enough to support horizontal scaling. Indeed, for each instance sharing the same launch configuration, a @Scheduled method will trigger its task as many times as there are instances running.

To solve that, the classic approach would be to use a queue. One task scheduler sends the tasks info in a queue and multiple consumers poll this queue to execute the tasks. Depending on the load, more or fewer consumer instances are launched.

While this architecture is certainly a good choice, it may not fit your technical constraints and needs. This also obliges you to bring the concept of messaging to your project.

In this article, we will see how we can rethink this challenge by avoiding relying on a Publisher-Consumers architecture but by relying on a relational database and its locking mechanisms.

Let's rethink the problem

What are we trying to achieve here?

We want:

to make sure that the tasks run once;
to trigger those tasks periodically;
to distribute the load between consumers.

Let's see how we can achieve that using Spring Boot and a relational database.

Step 1: Defining the consumer tasks

We first need to define the tasks. We create a service containing one method per identified task.

@Configuration
@EnableScheduling
public class TaskScheduler {
    @Scheduled(fixedDelay = 5, timeUnit = TimeUnit.MINUTES)
    public void scrapSourceWebsite() {
        // ...
    }

    @Scheduled(fixedDelay = 10, timeUnit = TimeUnit.MINUTES)
    public void moveDeletedToColdStorage() {
        // ...
    }

    // Other tasks
}

Notice that those methods are launched periodically using the @Scheduled annotation. At each run, the method will check if the task associated with the method can be executed.

The period can be 30 seconds, 5 minutes, or even a CRON expression. Depending on your business needs.

We will come back to the implementation of the methods later.

Step 2: Defining the DB entries

Now that we have defined our service tasks, we can start defining our DB table and entries.

CREATE TABLE task_lock
(
    task_id         VARCHAR(64)       NOT NULL,
    last_execution   bigint DEFAULT 0 NOT NULL,
    PRIMARY KEY (task_id)
);

INSERT INTO task_lock (task_id) VALUES ('scrap_website');
INSERT INTO task_lock (task_id) VALUES ('move_to_cold');

Our table is composed of the task ID and the timestamp of the last execution. This timestamp will be used to evaluate the time since the last execution, thus defining when the task needs to be executed again.
We have one row per task, those are the rows that the instance running the task will lock during the time of execution.

Step 3: Implementing the locking query

This third step is about being able to effectively lock a row of the table using JPA annotations. Locking this row will have as effect that any other query will not be able to retrieve it. Meaning that the other service instances will not be able to acquire the lock.

@Repository
public interface TaskLockRepository extends JpaRepository<TaskLockEntity, String> {

    @Lock(LockModeType.PESSIMISTIC_WRITE)
    @QueryHints({
        @QueryHint(name = "jakarta.persistence.lock.timeout", value = "1000")
    })
    Optional<ProviderLockEntity> findByTaskIdAndLastExecutionLessThan(String taskId, long timestamp);
}

We use a pessimistic write lock. When acquired, the lock will stay alive during the time of the transaction. If not acquired, the query will return an empty optional. When trying to acquire a lock, a timeout can be used to define the maximum time a query will wait for a lock to be released (1 second in our example).

Let's suppose that we have 2 instances running:

scrap_website is ready to be executed;
instance 1 executes the scheduled method scrapSourceWebsite();
Instance 1 queries the database and locks "scrap_website";
instance 2 executes the scheduled method scrapSourceWebsite();
Instance 2 queries the database and gets no results because it cannot lock the already locked row.

Step 4: Linking everything together

Now that we have our main components and the repository, it's time to write down our task-scheduling logic. Let's come back to our entry component.

@Configuration
@EnableScheduling
public class TaskScheduler {

    private final TaskLockRepository taskLockRepository;
    // Other dependencies

    public TaskScheduler(TaskLockRepository taskLockRepository) {
        this.taskLockRepository = taskLockRepository;
    }

    @Transactional
    @Scheduled(fixedDelay = 5, timeUnit = TimeUnit.MINUTES)
    public void scrapSourceWebsite() {
        long currentTime = System.currentTimeMillis();
        long scheduledRate = Duration.of(1, ChronoUnit.HOURS).toMillis(); // 1h
        taskLockRepository.findByTaskIdAndLastExecutionLessThan("scrap_website", currentTime - scheduledRate)
            .ifPresent(scrapingTask -> {
                // Execute scraping task...
                scrapingTask.setLastExecution(System.currentTimeMillis());
            });
    }

    @Transactional
    @Scheduled(fixedDelay = 10, timeUnit = TimeUnit.MINUTES)
    public void moveDeletedToColdStorage() {
        long currentTime = System.currentTimeMillis();
        long scheduledRate = Duration.of(6, ChronoUnit.HOURS).toMillis(); // 6h
        taskLockRepository.findByTaskIdAndLastExecutionLessThan("move_to_cold", currentTime - scheduledRate)
            .ifPresent(moveToCold -> {
                // Execute migration of deleted to cold storage...
                moveToCold.setLastExecution(System.currentTimeMillis());
            });
    }

    // Other tasks
}

As stated above, the query needs to run in a transaction.
You need to define the period associated with the task (scheduledRate). Respectively 1 and 6 hours in our example. You should use configuration properties if you want to do it the nice way.

This period and the current timestamp will be used to determine if the task can be picked. If the row is already locked or if the last execution time is too close, the instance will not acquire the lock and the method will end.

On the other hand, if the lock is acquired, the task is executed and the timestamp of this execution is saved in the task entity.

What if the task fails?

The transaction will rollback, nothing will be saved, and the lock will be released. Then another instance will be able to require the lock and retry the task.

Depending on your business, you may need to disable a task for a given time if a failure occurs. You will need to handle the error within the transaction.

Example of deactivating a task during 3 hours:

public class TaskScheduler {

    // dependencies

    @Transactional
    @Scheduled(fixedDelay = 5, timeUnit = TimeUnit.MINUTES)
    public void scrapSourceWebsite() {
        long currentTime = System.currentTimeMillis();
        long scheduledRate = Duration.of(1, ChronoUnit.HOURS).toMillis();
        taskLockRepository.findByTaskIdAndLastExecutionLessThanAndDeactivatedUntilLessThan("scrap_website", currentTime - scheduledRate, currentTime)
            .ifPresent(scrapingTask -> {
                try {
                    // Execute scraping task...
                    scrapingTask.setLastExecution(System.currentTimeMillis());
                } catch (Esception e) {
                    // Deactivating for 3 hours
                    scrapingTask.setDeactivatedUntil(System.currentTimeMillis() + Duration.of(3, ChronoUnit.HOURS).toMillis()); // 3h
                }
            });
    }

    // Other tasks
}

Side note: When your query method begins to be this long (63 characters 🤯), you should consider rewriting it into JPQL or hiding it behind another method.

What if the instance fails and crashes?

This could happen but we are still safe. The worker will stop responding to the database. The transaction will time out in the database and the lock will be released. How much time will it take? It depends on your database configuration.

How to monitor the instances load?

Monitoring the instance load is crucial to determine if more or fewer instances need to be launched. One way is to use a ThreadPoolTaskExecutor to launch the tasks. Then you need to monitor this ThreadPoolTaskExecutor to get the current number of tasks being executed among all the instances.

Combined with a good monitoring system, Micrometer's metrics will be your best allies here.

What if we need parameters to those tasks?

Indeed, the example is very simple. In real conditions, you could have parameters for those tasks, tasks that need to run the night only, etc. The principle stays the same as long as you lock the row associated with the task.

Suppose we have a scraping task that needs a website in parameter. We will have this table:

Website	Last execution timestamp
amazom.com	1234
bol.com	1267

The SQL query simply needs to find the first row and order by the timestamp (amazom.com). Then, the first row being already locked, the next first visible row will be bol.com.

Compared to the Producer-Consumer approach

Let's take a step back and compare the Locking Task Scheduling to the classic Producer-Consumer.

Pros:

Easy to put in place if you already have a SQL database;
No need to add the messaging concept to the stack;
Error outcome is easy to handle.

Cons:

No task payload, limited number of parameters;
Require locking capabilities on database.

Wrap up

We saw an approach to implementing a task-scheduling based on database locks. While this technique is not meant to completely replace the producer-consumer method, it proposes another way of tackling similar challenges. This other way of tackling the challenge offers different possibilities and can give you more flexibility on task definition and scheduling.

Whether you pick Producer-Consumers or Locking Task Scheduler architecture, choosing the right implementation is a risky task. That kind of implementation risk can be mitigated using the Onion Architecture. In a previous article, I explained how you can implement this architecture in Spring Boot projects.

A better architecture for your Angular projects

Jérôme Navez — Sat, 24 Jun 2023 10:56:31 +0000

Conceptually, this architecture could be applied to any frontend framework. Since I have more knowledge of Angular than the other frontend frameworks, I will write Angular examples when necessary.

If you wish to directly jump to the architecture, click or tap here.

Before rushing into the technical parts, let's ask ourselves:

Why focus on the frontend architecture?

While putting in place a backend architecture is common sense, it may be harder to have a clean architecture on the frontend side.

For multiple reasons.

Javascript Frameworks

Historically, new Javascript framework were popping every day. Being able to master a framework takes time and effort. You need a strong experience to know every capability of a framework and figure out what to do when facing a programmatic challenge.

Currently, the frontend frameworks seem to be dominated by React, Angular and Vue for some years know. This brings stability. Some pattern and architectural concept are shared among them.

Frontend concepts

Frontend uses a lot of concepts that you need to know in order to code your product. Concepts that you don't meet when working on backend.

Some of the challenges and concepts a frontend developer meet every day:

State management to enhance the single source of truth;
Asynchronous code to not block your UI;
Combining UX modularity and Code modularity.

Backend vs Frontend architecture

This reason is very influenced by my own perception of IT architecture and what I see in some projects around me.

Less effort is put into the frontend architectures while more effort is put in the backend architectures.

Some would say that business logic and security are sensitive backend topics. Those two things must be rock solid. While the frontend is just there to "display things from the backend".

Indeed, the frontend is nothing without a strong backend. But the reverse is also valuable. Having a strong backend, you don't want a weak frontend full of bugs and hard to maintain to communicate with your backend.

Refactoring frontend code is way harder

Disclaimer: I mainly use IntelliJ IDEA.

Modern IDE has strong refactoring capabilities for Java projects. Renaming filenames and moving classes from package to package is easy.

I cannot tell the same for Angular projects. Imports unchanged, NgModule not updated, etc. I always have the feeling that some "smart links" are missing between files.

By highlighting the separation of concern with a good architecture, the number of those refactoring will decrease and be easier to process.

Base principles

You may or may not agree with all of those reasons, but you certainly agree on the fact that the frontend architecture deserves time and effort to be well organized.

The main goal of an architecture is to reduce the coupling between the elements that compose the software. Separation of concern, modularity, abstraction, etc are the main ideas to achieve that.

Unfortunately, the frontend frameworks suffer from two specific issues that need to be tackled to reach this goal:

The business logic tends to be split across multiple components;
There is a risk of data being contained in multiple places, increasing the chance to use outdated or unsynchronized data.

Given those objectives and issues, the following architecture put its prioritizes on:

Stateless components;
Single source of truth;
Separation of concern;

The SCA architecture

We need a catchy name. Let's call this architecture the SCA architecture: the Simple and Clean Angular architecture.

Let's dive into the graph:

The architecture is composed of 4 big parts:

Components
Domain
Store
Infrastructure (most of the time, the clients)

Depending on your project and uses cases, you may also use the local storage or the session storage. Those belong to the infrastructure.

The store could also be categorized as an infrastructure layer. But since it deserves special attention, let's keep it as a separate part.

Domain

This is the center of our application. It's composed of services. It can be one simple service or multiple separated services. The domain layer should represent the use-cases, so you need to organize them as logically as possible.

The domain exposes methods that are actions available for the components. Those actions execute business logic, use the infrastructure, and/or modify the state of the store.

The domain also exposes selectors that are Observables being selections of the store. RxJs operators can be applied to this selection, but the final result must always be based on the store value only. They emit each time the selection is modified. Those exposed selectors have a business meaning.

Selector example:



userAge$ = this.store.select(state => state.userDetails.birthdayDate)
    .pipe(
        map(birthdayDate => getAge(birthdayDate))
    );

The domain should be independent of the framework used as much as possible. We should be able to migrate the domain logic from the angular project to any other TypeScript project with very few efforts. Of course, there will always be the @Injectable and @NgModule decorators, but you get the idea.

Components

Components are there for two reasons:

Display information in a beautiful way;
Catch the user inputs.

The user inputs are interpreted and trigger a dedicated action from the domain layer. If required, additional data can be sent in argument of this action.

The information displayed comes from the selectors exposed. The Observables are used in the template and no business logic should be applied to them.

Those two only responsibilities make the components stateless, no logic is executed from information handled by the component.

Clients & infrastructure

The infrastructure layers are dependencies needed by the domain layer to perform its actions. It can be web clients, communications with Local storage, or any other dependency that can be abstracted from the domain layer.

The infrastructure layer contains services with very simple code that is only related to the usage of the dependency. Optionally, it can contain mappers if needed.

Client service example:



@Injectable()
export class ItemClient {

    constructor(private httpClient: HttpClient){}

    postItem(item: Item): Observable<Item> {
        return this.httpClient.post<Item>(API_PATH, item);
    }
}

Store

The store is composed of:

The state of the application;
Some reducer methods that can modify the state;
Some selectors, being Observables that emit the modifications of the state.

It should only contain store-related logic. No business logic and no call to another infrastructure layer.

The store can be implemented using any technology. You can either use a library like NgRx or NGXS. Another solution is to create your own store using a BehaviorSubject.

Let's focus on the store

Let's come back to the store and how to implement it. When choosing the store you will use, you need to select the one that respects your architecture. You need to make sure that this store is hidden behind an abstraction to not pollute your domain layer with store-related code.

NgRx could be your choice, but it's maybe not the right one.

The issue with NgRx

Here is the state management proposed by NgRx:

NgRx comes with a concept that breaks our architectural rules: the effects. Using the concept of effects, you execute business logic in the store layer and directly contact the client layer. You end up with logic being executed in two places: the domain layer and the store layer.

NgRx is great, but it comes with its proper architecture which is not compatible with our SCA architecture. Except if you remove the use of effects.

Another solution could be to create a simple custom store.

Custom store

State, actions, selectors and reducers, those 4 store concepts can be built around a BehaviorSubject. This kind of observable is a great help to play with data.

Here is an example of a custom state:



import {BehaviorSubject, distinctUntilChanged, map, Observable} from "rxjs";

export class Store<T> {

  private state$: BehaviorSubject<T>;

  constructor(initialState: T) {
    this.state$ = new BehaviorSubject<T>(initialState);
  }

  /**
   * This method provides an observable representing a part of the state.
   * @param selectFn defines a method that select a subpart U the state T
   */
  public select<U>(selectFn: (state: T) => U): Observable<U> {
    return this.state$.asObservable().pipe(map(selectFn), distinctUntilChanged());
  }

  /**
   * This method is used to update the state
   * @param reduceFn defines a method that transform the state to another state
   */
  public update(reduceFn: (state: T) => T): void {
    this.state$.next(reduceFn(this.state$.getValue()));
  }
}

The select method will be used by the selectors. The update method will reduce the state according to the action.

But it's not enough, this store needs to be instantiated and used by a service:



@Injectable()
export class ItemStore {

  store = new Store<Item[]>([]);

  items$ = this.store.select(items => items);

  item$ = (itemId: number) =>
    this.store.select(items => items.find(item => item.id === itemId) as Item);

  initialize(initialItems: Item[]): void {
    this.store.update(_ => initialItems);
  }

  remove(id: number): void {
    this.store.update(state => state.filter(item => item.id !== id));
  }

  add(item: Item): void {
    this.store.update(state => [...state, item])
  }
}

The service exposes selectors and actions that have a meaning for the domain layer. It is then ready to be used by the domain layer.

Proof of Concept Project

I made a little playground application In Angular and Spring Boot. The frontend part uses the SCA architecture as described above. Take a look to see a concrete example!

Task Manager Playground

Next step

If we take a look at the graph of the SCA architecture, we notice that the dependencies lead from the components to the infrastructure layers. Meaning that it's possible to inject a client into a component.

Of course, this is wrong, but there is a solution to avoid that: The inversion of dependency. Those of you who follow my blog know that I have made a little POC of how to apply the Onion Architecture on a SpringBoot project. The next step is to apply the same principles to the SCA architecture.

So hold on and prepare yourself for the next article: The SCAO architecture: the Simple and Clean Angular Onion architecture.

Happy coding!

Make your microservices tastier by using the Onion architecture

Jérôme Navez — Thu, 25 May 2023 23:03:59 +0000

Most of the traditional architectures are subject to raising issues of separation of concerns by increasing the coupling between the component. Being too permissive, those architectures stay in the theoretical concepts and do not force the developers to apply its principles.

Jump to the Onion architecture

The Layered Architecture

The most natural architecture when building a microservice is the Layered architecture. The Layered architecture provides guidelines to separate your service into 3 layers, from the presentation to the database. But nothing stops the developers from using entities and repositories in the presentation layer. This is mainly because of the direction of the dependencies going from the presentation to the persistence.

Compared to the Layered architecture, the Onion architecture provides a similar way of separating your classes in modules, but by adding the usage of a specific pattern to solve this dependency issue.

By browsing the web, you can find many documents about the Onion architecture, some terms that you could see in those documents may differ from the terms used in this article. Different terms, but same principles.

The Onion Architecture

Without further notice, let’s jump into the Onion architecture:

The center of the graph is the domain model: our business objects and the relations between those objects. Those objects are “clean” and are only meant to describe our business in the best possible way. By clean, I mean that they don’t contain any JSON, JPA, or XML annotations.

Around the domain model, we find our domain services. This is the business logic, our use-cases. The domain services strongly rely on the domain objects.

The controllers (and the scheduled jobs) are the entry modules of the architecture. Thus they need to call the domain services to respond to the frontend or other clients.

The persistence module and the clients module are part of the infrastructure. Here, “Infrastructure” is a conceptual term used to group all the modules related to persistence, external communications, and any other module that the domain needs to process its tasks. The term “clients” refer to components that interact with other microservices or with external services. They are the clients of those services.

Principle

The base principle of the Onion architecture is that the module dependencies lead to the domain module. Meaning that the persistence module and the clients depend on the domain module. This is the main difference with the Layered rchitecture where the dependency go from the domain to the persistence module.

More generically, the external layers depend on the inner layers.

This ecosystem can be represented as an onion. A microservice project is therefore an onion. The center is sweet and must be protected from outside threats. The Onion architecture enhances this protection by blocking the domain module from accessing the infrastructure layer.

While the Layered architecture provides guidelines to structure and to place our code in the right place, the Onion architecture provides barriers to force the devs to apply those guidelines. That’s what makes this architecture so strong.

Let’s zoom into the presentation layer and the way it interacts with the domain module.

Presentation Layer And Facades

Facades are not defined in the Onion architecture but are nice to have. In our case, they can help us to have a clearer view of our presentation module.

Each RestController contains very little logic and has its Facade.



@Service
@Validated
@RequiredArgsConstructor
public class TaskManagerFacade {

    /* dependencies: mapper, domain service */
    private final DtoMapper dtoMapper;
    private final TaskService taskService;

    @Secured("ROLE_VIEWER")
    public List<TaskDto> getTasks() {
        List<TaskDto> tasks = taskService.getTasks();
        return dtoMapper.toDto(tasks);
    }

    @Secured("ROLE_EDITOR")
    public TaskDto addTask(@Valid TaskDto taskDto) {
        Task task = dtoMapper.toModel(taskDto);
        Task savedTask = taskService.add(task);
        return dtoMapper.toDto(savedTask);
    }
}

The Facades follow this structure:

Mapping the DTO arguments into domain models (DTO → Model);
Calling the domain service;
Mapping and returning the result into a DTO (Model → DTO).

More roles are given to the Facades as they act as guardians of our microservice for aggressions coming from the outside:

Security and access (@PreAuthorize, @Secured)
DTO validations (with @Validated and @Valid)

Depending on your business, a Facade could also “link” domain services between them and act as an orchestrator of services. In this case, more logic could be written in Facades. As long as no logic is executed on DTOs.

Persistence Layer, Gateways, And Adapters

As stated above, the inner layer needs the infrastructure layer to process its tasks.

Let’s take the example of a business use case that needs to store information. While the more natural way would be to import a repository in the service, the Onion architecture relies on another pattern to achieve this, the inversion of dependency.

Inversion of dependency

The domain module will define an interface containing all the methods he needs to communicate with a persistence module, the Gateway. The Gateway contains methods with arguments and return types from the domain model.



public interface PersistenceGateway {
    List<Task> getTasks();

    Item saveTask(Task task);
}

This way, the domain explicitly states that it’s required to implement those methods to make the microservice work. It doesn’t care about how the methods are implemented and what technologies and libraries are used to achieve it.

The persistence module is required to implement the Gateway to be compliant with the domain. The Adapter takes care of this responsibility and is the entry point of the module. This is where the dependency from the persistence module to the domain module appears.



@Service
@RequiredArgsConstructor
public class PersistenceAdapter implements PersistenceGateway {

    /* dependencies: repository, mapper, query builder etc */
    private final EntityMapper entityMapper;
    private final TaskRepository taskRepository;

    @Override
    public List<Task> getTasks() {
        List<TaskEntity> taskEntities = taskRepository.findAll();
        return entityMapper.toModel(taskEntities);
    }

    @Override
    public Task saveTask(Task task) {
        Task taskEntity = entityMapper.toEntity(task);
        Task savedTaskEntity = taskRepository.save(taskEntity);
        return entityMapper.toModel(savedTaskEntity);
    }
}

Those method implementations follow this structure:

Mapping the arguments into entities or queries (Model → Entity);
Execute the query;
Mapping and returning the query result into a domain model (Entity → Model).

The Adapter needs to adapt itself to the Gateway. Most of the time, one Adapter mechanism will be needed to communicate. But as for every class, if the number of methods grows too much, it might be wise to split the Adapters and the Gateways into multiple classes.

This Gateway/Adapter is transposable to other infrastructure modules as the clients module. In this case, the mapper would map between our model and DTOs provided by the external service.

We can see multiple advantages to this dependency inversion, here are some of them:

Enhance Domain Driven Design;
Protect our model from API changes in Clients;
Possibility to have multiple Adapters for one Gateway;
Easier to test our domain;
Domain being independent of any dependency choice.

Running everything in a Spring Boot Project

Now that we have our domain, presentation, and persistence modules, we want to launch everything in a Spring Boot application. To achieve this, we need an application module.



├── spring-project
    ├── app
    ├── domain
    ├── persistence
    └── presentation

Application module

This module is a no-code module. Its responsibility is only to provide a way to make everything run together. It imports persistence, presentation, and domain modules in its pom.xml (or build.gradle).



<project>

    <!-- ... -->

    <dependencies>
        <dependency>
            <groupId>com.woodchopper.tuto.onion</groupId>
            <artifactId>presentation</artifactId>
        </dependency>
        <dependency>
            <groupId>com.woodchopper.tuto.onion</groupId>
            <artifactId>domain</artifactId>
        </dependency>
        <dependency>
            <groupId>com.woodchopper.tuto.onion</groupId>
            <artifactId>persistence</artifactId>
        </dependency>
    </dependencies>
</project>

The only source class present in this module is the Spring Boot application class containing the main method:



public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

The module also contains the different property files needed to run the application. The integration tests responsible fortesting the flows from the controllers to the repository are written in this module.

What and how to test?

Ideally, we should be able to cover the entire project with our tests. Two kinds of tests can be made:

Unit testing on a targeted class;
Integration testing on an endpoint.

Unit tests

Each class containing logic code needs to be tested. logic code means business logic but also mapping logic.

Integration tests

Those tests provide a way to cover the global microservice flows. The goal is not to cover each specific case of the mapper or the domain services.

This will also allow the developer to cover the Adapters and Facades. Hence, the security and the validation behaviors will be tested.

Those tests are located in the application module since they need the Spring Boot context to be launched. They will mainly use MockMvc as their main tool.

Proof of Concept Project

I made a little playground application In Angular and Spring Boot. The backend part uses the Onion architecture as described above. Take a look to see a concrete example!

Task Manager Playground

Conclusion

We saw a way to implement the Onion architecture in a SpringBoot microservice. While this architecture certainly comes with more classes than the Layered architecture, its structure enhances the maintainability by imposing a strong structure.

Happy coding!

Angular Access Right And Feature Toggle By Extending NgIf!

Jérôme Navez — Thu, 13 Apr 2023 13:39:48 +0000

Jump to final solution

During your Angular journey, you could be invested into a development that implies hiding elements to some kind of users depending access right or roles. You could even need to hide complete features from you Angular client waiting for the backend to be implemented or waiting for the feature to be officially released to the public.

I can already hear it from you, when it comes to display or hide components or other elements from a template, the first thing that comes in mind is to create a directive. It's reusable and we love reusable things.

Let's continue our story with our second example. We need to implement a directive that hide the element based on a given feature. Let us suppose that we have a feature called: githubLogin. Basically, this feature active the authentication via GitHub.

Creating the directive (the naive way)

And Abracadabra, we have our nice FeatureToggleDirective.

@Directive({ selector: '[feature]' })
export class FeatureToggleDirective implements OnInit {

    constructor(
        private viewContainer: ViewContainerRef,
        private featureService: FeatureService) {
    }

    @Input()
    feature: string;

    ngOnInit() {
        if (this.featureService.isDisabled(this.feature)) {
            this.hide();
        }
    }

    private hide(): void {
        this.viewContainer.clear();
    }
}

It's used like this :

<button [feature]="'githubLogin'">Login via GitHub</button>

Meaning that the button Login via GitHub is displayed if the feature is enabled.

So here we are, we created our directive, and you noticed that I used ViewContainerRef to hide the content. It's a choice, I could also inject ElementRef and use

this.elementRef.nativeElement.style.display = 'none';

to hide the content. Both solutions are valid, and we will go further in the comparison since it's not the goal of this article.

Can we do better?

Of course, we can do better! What if we want to change the behavior of this directive to be more dynamic and flexible.

For example, being able to use it when the feature name is given asynchronously:

<button [feature]="featureName$ | async">Login via GitHub</button>

We would need to use a setter or implement OnChange.

We could also decide to display a message explaining why this feature is disabled. By providing a fallback template to the directive:

<button [feature]="'githubLogin'" [featureFallbackTemplate]="fallback">Login via GitHub</button>
<ng-template #fallback>Sorry, the GitHub feature is not yet available</ng-template>

There is so much work to do to make our directive completely robust. At some point, it begins to be as dynamic and robust as another directive that we all know...

Extending `NgIf`

The subtitle says it all, why not reusing the code of NgIf. It has been proved that it works. It's the most used directive in the Angular world ("ngIf" gives 4M file results in Github!). So what do we do ? Do we copy the NgIf solution? What about extending NgIf? Yes, sounds good!

Let's take a look at the NgIf code. We notice 4 methods: 3 setters and one private method where all the magic occurs.

Since our directive has its own selector name feature, we need to rename the setters with feature, featureThen, and featureElse. Each of those methods will act as a proxy and call the corresponding setter in NgIf class.

We also need to add the FeatureService logic in the feature setter. Our condition returns a boolean, so we set the type of the NgIf to boolean.

@Directive({ selector: '[feature]' })
export class FeatureToggleDirective extends NgIf<boolean> {

  @Input()
  set feature(feature: string) {
    this.ngIf = this.featureService.isEnabled(feature);
  }

  @Input()
  set featureThen(templateRef: TemplateRef<NgIfContext<boolean>>|null) {
    this.ngIfThen = templateRef;
  }

  @Input()
  set featureElse(templateRef: TemplateRef<NgIfContext<boolean>>|null) {
    this.ngIfElse = templateRef
  }

  constructor(private featureService: FeatureService ,_viewContainer: ViewContainerRef, templateRef: TemplateRef<NgIfContext<boolean>>) {
    super(_viewContainer, templateRef);
  }
}

And that's it, you can now use all the power of NgIf with your feature toggle directive! Amazing, isn't it?

Some usage examples

Some examples of how we can use our directive:

Simple form with shorthand syntax:

<button *feature="'githubLogin'">GiHub login</button>

Simple form with expanded syntax:

<ng-template [feature]="'githubLogin'">
    <button>GiHub login</button>
</ng-template>

Shorthand form with an else block:

<button *feature="'githubLogin'; else fallback">GiHub login</button>

<ng-template #fallback>
    <i>Sorry, the feature is not yet available</i>
</ng-template>

Shorthand form with then and else blocks:

<ng-container *feature="'githubLogin'; then github; else fallback">GiHub login</ng-container>

<ng-template #github>
    <button>GiHub login</button>
</ng-template>
<ng-template #fallback>
    <i>Sorry, the feature is not yet available</i>
</ng-template>

Working example

Take a look at the working online example here: StackBlitz. Play with it and fork it!

Conclusion

We created a highly reusable directive based on a simple feature toggle example. There are plenty of other features that could reuse NgIf. I hope this article will give you more ideas and uses cases to build even more directives of this kind.

Happy coding!