After developing for some years REST API-s with Express and Sequelize ORM I felt that it was the time to try something new. During my research for other NodeJS Web Frameworks I came across Fastify. Among other features, selling point that caught me off was their official benchmark which shows this framework being 4x faster than Express. Afterwards I was really curious what's the developer experience with this framework. For this reason I developed a simple REST API about task management which development stages will be detailed throughout this article.

Another focus of this article was the ORM selection. It is very important to avoid any performance bottleneck in the data layer which may be introduced by a particular ORM. For me as a developer, Sequelize provides a very friendly user interface but at what cost? Of course performance!

First things first

The first step in this journey is to create a fastify project. We can use the fastify-cli. For this project I decided to go ahead with strong type safety by using Typescript. The command used to create a project with typescript support is as following:

npx fastify-cli generate <app-name> --lang=ts

A database and and table will be required for this tutorial. The following SQL snippet of code defines required tasks table:

CREATE TYPE task_status AS ENUM('backlog', 'pending', 'failed', 'done');

CREATE TABLE tasks(
    id SERIAL PRIMARY KEY,
    title VARCHAR(30) NOT NULL,
    "description" VARCHAR(256) NOT NULL,
    "status" task_status NOT NULL,
    start_time TIMESTAMP NOT NULL,
    end_time TIMESTAMP NOT NULL,
    deleted BOOLEAN DEFAULT FALSE
);

Picking up an ORM

One of the most critical parts of a backend app is the Data Layer. This layer is mostly represented by ORM. With a poor choice, the ORM can negatively affect the app performance.

As a Go developer I used to work with Sqlboiler ORM. I was really amazed how it provided the functionalities by avoiding the reflection as much as possible. The ORM itself is schema which means that the models are generated from the database schema. This philosophy has the following benefits:

• Work with existing databases: Don't be the tool to define the schema, that's better left to other tools.
• ActiveRecord-like productivity: Eliminate all sql boilerplate, have relationships as a first-class concept.
• Optimize hot paths by generating specific code for each schema model.

The biggest performance gain is due to the fact that for specific models, specific like hand-roled queries are generated. This allows for hot path optimization.

Unfortunately, in the NodeJS environment all ORM seems to be code-first. They are more focused on being user friendly than performant. In my opinion a balance between user-friendliness and performance of an ORM  must be established. However, during my ORM research I came across Objection.js which is built on top of a highly performanc query builder called Knex. This convinced me to some degree so I picked it.

Unfortunately I did no benchmarks to confirm my choice of ORM, but I was based on an external benchmark. After a close inspection of the benchmark, it can be concluded that the benchmark involves also the network overhead incurred by HTTP request and database connection. For a more fair experiment, both of them must be crossed out from the benchmark by mocking the database driver. Despite of that, Objections was more performant than Sequelize.

Setting up Data Layer

At first I was trying to reinvent the wheel by introducing some infrastructure services which are used among different API-s during the app lifecycle. After reading this article I realized that I was doing it in a wrong way. Fastify allows us to declare plugins to handle such kind of services. More specifically in the README of the plugins folder the following note is written:

Plugins define behavior that is common to all the routes in your application. Authentication, caching, templates, and all the other crosscutting concerns should be handled by plugins placed in this folder.

With that in mind, I created a database plugin with the following code:

// src/plugins/database.ts
import Knex = require('knex')
import { Model } from 'objection';
import config from '../config'
import fp from 'fastify-plugin'

export interface DBConfig {
    
}

export default fp<DBConfig>(async (fastify, opts) => {
    const knex = Knex(config.development.database)
    Model.knex(knex);

    await checkHeartbeat(knex);
    
    fastify.decorate('knex', knex)
});

async function checkHeartbeat(knex: Knex<any,unknown[]>) {
    await knex.raw('SELECT 1')
}

After the Knex instance is created, it does not check if the given configuration is correct. For that we need to make a random query by calling checkHeartbeat.

After that we need to define a model for our task entity. We create a folder called models under src folder.

// src/models/task.ts
import { Model } from 'objection'

export default class Task extends Model {
    id!: number
    title!: string
    description!: string
    status!: string
    startTime!: Date
    endTime!: Date
    deleted!: boolean
    
    static tableName = 'tasks'
}

Fastify philosophy on creating REST APIs

Before diving straight into API development, I think it is best to think a bit about the anatomy of a fastify route declaration. This would help us to see the big picture and plan a better organization of the code for the route declaration which must be clear and easy to maintain.

Traditionally, when we talk about structure of an API endpoint we are referring to a path which is string, and the handler which is the function that is executed when a request hits the endpoint's path. Usually, the handler contains following logic blocks:

1. parse request body/parameters
2. validate the obtained input
3. process business logic

Fastify handlers are much more different. Due to the architecture enforced by the framework, a handler should not contain parsing or validation logic. When setting up a route, we can configure the model where the request input should be deserialized into, and a validation schema which should be satisfied in order to process the request, otherwise a status code of 400 which indicates a bad request will be sent to the client. S0 only the business logic is left to be processed in the handler. Let's see the example of creating a task:

// src/routes/api/tasks/index.ts
fastify.post<{Body: Task, Reply: Task}>(
  '/',
  {
    schema: {
      body: TaskSchema
    }, 
  },
  async (req, res) => {
    try {
      return TaskService.createTask(req.body)
    }
    catch(err: any) {
      return err;
    }
  }
)

1. in line 2 a route at path POST /api/tasks is being declared
2. generic types are used to specify the types of the body being received  and the reply that should be sent; in case we return in handler an object whose type is not task, an error is thrown; this guarantees strong type safety.
3. in line 3 the path is specified; please see fastify-autoload to get more contexts how routes are registered with this plugin.
4. in line 5 we setup the schema for validation; I have created a folder at src/schemas which contains all validation schemas.
5. in line 9 the handler is declared

The validation task schema used at line 6:

// src/schemas/task_schema.ts
import { Type } from "@sinclair/typebox";

export const RequiredTaskSchema = Type.Object({
    id: Type.Optional(Type.Integer()),
    title: Type.String(),
    description: Type.String(),
    status: Type.String(),
    start_time: Type.Optional(Type.String()),
    end_time: Type.Optional(Type.String()),
    deleted: Type.Optional(Type.Boolean())
});

In order to keep handlers as slim as possible I decided to extract all business logic in a separate layer called services. I went with static methods instead of creating a service object instance for each request. Here is the declaration of TaskService.createTask used at line 11:

// src/services/task_service.ts
static async createTask(task: Task): Promise<Task> {
    return await Task.query().insert(task);
}

With this philosophy we provide a better encapsulation of the business logic. At the same time, we prevent ending up with large route files which are difficult to read and maintain.

Other APIs

In this section I will talk about remaining APIs such as: list tasks, get, update and delete a particular task.

List Task API - [GET] /api/tasks

Route declaration for getting the list of tasks:

// src/routes/api/tasks/index.ts
fastify.get<{Querystring: ListQueryOptions, Reply: Task[]}>(
  '/',
  {
    schema: {
      querystring: ListQueryOptionsSchema,
    },
  },
  async (req, res) => {
    return await TaskService.getTaskList(req.query)
  }
  
)

This API accepts query parameters defined by ListQueryOptionsSchema. Here is the declaration of the type and the validation schema:

// src/types/list_query_options.ts
import { Type } from '@sinclair/typebox'

export interface ListQueryOptions {
    page: number
    count: number
    query: string
}

export const ListQueryOptionsSchema = Type.Object({
    page: Type.Integer(),
    count: Type.Integer(),
    query: Type.Optional(Type.String())
})

Reading ListQueryOptionsSchema definition we can see that both page and count are mandatory.  This is done just for demonstration purposes. It is pretty doable to have both these parameters as optional and fill them by default values.

However it is really important to put a limit in the count because the API can be exploited by hackers in a DDOS attack which can lead to a high consumption of the resources.

The business logic for getTaskList:

// src/services/task_service.ts
static async getTaskList(lso: ListQueryOptions): Promise<Task[]> {
    const offset = lso.count * (lso.page - 1)
    return await Task.query()
        .where('deleted', false)
        .limit(lso.count)
        .offset(offset);
}

This is an excellent example how the service is helping in keep the route declaration code as small as possible.

Get Task by Id - [GET] /api/tasks/:id\

Route declaration for getting a task by id:

// src/routes/api/tasks/index.ts
fastify.get<{ Params: PathIdParam, Reply: Task | Error}>(
  '/:id',
  {
    schema: {
      params: PathIdParamSchema,
    }
  },
  async (req, res) => {
    try {
      return await TaskService.getTask(req.params.id);
    }
    catch(err: any) {
      return err;
    }
  }
)

The API requires a path parameter which is used to specify the resource id.  PathIdParamSchema is the validation schema and PathIdParam is the type which declares the id parameter. Here is the relevant code:

// src/types/path_id_param.ts
import { Type } from "@sinclair/typebox";

export interface PathIdParam {
    id: number
}

export const PathIdParamSchema = Type.Object({
    id: Type.Integer()
})

Relevant code of service method getTask:

// src/services/task_service.ts
static async getTask(id: number): Promise<Task> {
    const task = await Task.query()
        .findById(id)
        .where('deleted', false);

    if (!task) {
        throw new httpErrors.NotFound()
    }

    return task;
}

Update Task by Id - [PUT] /api/tasks/:id

Route declaration for updating a task:

// src/routes/api/tasks/index.ts
fastify.put<{Params: PathIdParam, Body: Task, Reply: Task | Error}>(
  '/:id',
  {
    schema: {
      params: PathIdParamSchema,
      body: TaskSchema
    },
  },
  async (req, res) => {
    req.body.id = req.params.id;
    try {
      return await TaskService.updateTask(req.body)
    }
    catch(err: any) {
      return err
    }
  }
)

The route configuration is almost identical with the previous one. However, here we are accepting a body which uses task schema for validating the body.

The relevant code of service method updateTask:

// src/services/task_service.ts
static async updateTask(task: Task): Promise<Task> {
    const oldTask = await this.getTask(task.id);

    return await oldTask.$query().updateAndFetch(task);
}

Delete Task by Id - [DELETE] /api/tasks/:id

Route declaration for deleting a task:

// src/routes/api/tasks/index.ts
fastify.delete<{Params: PathIdParam, Reply: Task | Error}>(
  '/:id',
  {
    schema: {
      params: PathIdParamSchema,
    },
  },
  async (req, res) => {
    try {
      return await TaskService.deleteTask(req.params.id)
    }
    catch(err: any) {
      return err
    }
  }
)

The route configuration is identical with the configuration of the route of getting a task by id.

The relevant code of service method deleteTask:

// src/services/task_service.ts
static async deleteTask(id: number): Promise<Task> {
    const t = await this.getTask(id);

    await t.$query().updateAndFetch({
        deleted: true
    });

    return t;
}

Conclusion

Creating blazing fast REST API-s with NodeJS has never been easier and developer friendly than it is now. With fastify framework we can take advantage of declarative programming to setup route validation for input and output formats. However, we need to be careful about the usage of a particular ORM as it can dramatically affect the performance of the application. In the NodeJS environment, ORM-s are more focused on being user-friendly than performant. In my opinion a balance between them must be established.

The source code can be found here

When developing backend applications, in order to provide a functionality, we may need to interact with other REST services. Most popular services may have client libraries in different languages like C#, JS, Python. However, there are situations where a service provider does not offer such library for the language that we are currently working with. What to do in such case? Can't we just do some HTTP request directly in our business logic? What about authentication, how to handle expirable tokens? These and more questions will be answered in this article.

First things first

For the sake of this article, I picked Cat API which as stated in the official page offers an API for retrieving cat information such breeds, categories etc.

A public service API all about Cats, free to use when making your fancy new App, Website or Service.

Cat API does not offer a client library for consuming the service in Go. So we are going to create it for Go.

Creating the client

GoLang is more of a functional language but it also supports development in OOP style to some degree by offering interfaces and structs. In our case we are going to use a struct for the client which will hold all information needed by the client to operate.

type CatApiClient struct {
	host       url.URL
	accessKey  string
	version    string
	httpClient *http.Client
}

• host: it is the URL of the service and in our case is: https://api.thecatapi.com.
• accessKey: you can get one by signing up at Cat API.
• version: it is the api version such as v1, v2 etc.
• httpClient: it is the http client which carries out http requests for the client and is reused throughout the lifecycle of the client for efficiency.

In Go specification there are no constructors and for struct initialization we use functions. To create and initialize a CatApiClient, the function constructor is declared as following:

func NewClient(host, accessKey, v string) (*CatApiClient, error) {
	u, err := url.Parse(host)
	if err != nil {
		return nil, ErrInvalidHost
	}

	apiClient := &CatApiClient{host: *u, accessKey: accessKey, version: v}

	// create default http client which will execute requests.
	apiClient.httpClient = &http.Client{Timeout: 10 * time.Second}

	return apiClient, nil
}

Before continuing, we need struct entities where response serialized data will be deserialized into. Lets take for example /breeds API which returns a list of breeds. In order to get the response format we make a request in Postman at breeds API and we get a response like this:

[
    {
        "weight": {
            "imperial": "7  -  10",
            "metric": "3 - 5"
        },
        "id": "abys",
        "name": "Abyssinian",
        "cfa_url": "http://cfa.org/Breeds/BreedsAB/Abyssinian.aspx",
        "vetstreet_url": "http://www.vetstreet.com/cats/abyssinian",
        "vcahospitals_url": "https://vcahospitals.com/know-your-pet/cat-breeds/abyssinian",
        "temperament": "Active, Energetic, Independent, Intelligent, Gentle",
        "origin": "Egypt",
        "country_codes": "EG",
        "country_code": "EG",
        "description": "The Abyssinian is easy to care for, and a joy to have in your home. They’re affectionate cats and love both people and other animals.",
        "life_span": "14 - 15",
        "indoor": 0,
        "lap": 1,
        "alt_names": "",
        "adaptability": 5,
        "affection_level": 5,
        "child_friendly": 3,
        "dog_friendly": 4,
        "energy_level": 5,
        "grooming": 1,
        "health_issues": 2,
        "intelligence": 5,
        "shedding_level": 2,
        "social_needs": 5,
        "stranger_friendly": 5,
        "vocalisation": 1,
        "experimental": 0,
        "hairless": 0,
        "natural": 1,
        "rare": 0,
        "rex": 0,
        "suppressed_tail": 0,
        "short_legs": 0,
        "wikipedia_url": "https://en.wikipedia.org/wiki/Abyssinian_(cat)",
        "hypoallergenic": 0,
        "reference_image_id": "0XYvRd7oD",
        "image": {
            "id": "0XYvRd7oD",
            "width": 1204,
            "height": 1445,
            "url": "https://cdn2.thecatapi.com/images/0XYvRd7oD.jpg"
        }
    },
    ...
]

We need to convert the object inside the JSON array to a Go struct. Luckily for as there is an online tool where we can create the required Go struct for that JSON Object.

We  change struct name from AutoGenerated to Breed and save it in a file breed.go. You may also extract abstract struct such Image property and store it in a separate struct like ImageDescriptor(this is not required)

Now that we have the required data models for the breed API we can continue to the next topic.

Create client helper methods

For maximum code reusability, it is necessary to see the big picture and think about it before going straight into writing a certain functionality. With that I mean that we need to think about authentication and request construction which both can be reused between different API calls. This increases code reusability and it is easier to maintain. A total disaster would be if such logic is scattered among  different API and when we find a bug in one API we would need to review and fix all API-s where such logic is copy-pasted. So its is a maintenance nightmare.

For the Cat API I created a generic purpose method for performing a GET request. It takes three parameters as shown in the following code snippet:

• path: defines the path of the request without including host or version; both host and version are handled automatically inside this function.
• query: it is basically a map with query parameters that will be appended to the request
• output: it is the structure where the response will we deserialized into; for example for breed list we pass a pointer to a Breed slice.

func (c *CatApiClient) execGet(path string, query url.Values, output interface{}) error {
	url := c.host
	url.Path = "/" + c.version + path

	fmt.Println(url.String())

	req, err := http.NewRequest(http.MethodGet, url.String(), nil)
	if err != nil {
		return err
	}
    
        req.Header.Add("x-api-key", c.accessKey)

	req.URL.RawQuery = query.Encode()

	resp, err := c.httpClient.Do(req)
	if err != nil {
		return err
	}
	defer resp.Body.Close()
    
	if resp.StatusCode != 200 {
		errBytes, _ := io.ReadAll(resp.Body)
		return errors.New(string(errBytes))
	}

	dec := json.NewDecoder(resp.Body)
	return dec.Decode(output)
}

The method is also responsible for taking care of authentication. As it can be seen in the code, in the line 12 we add the x-api-key header to the request.

Get Breeds API

Finally all required logic is in place so we can with not much effort complete the first Cat API call. Making use of execGet too much logic is abstracted away and the GetBreeds method is soo thin as shown in the following snippet:

func (c *CatApiClient) GetBreeds(query url.Values) ([]*Breed, error) {
	var breeds []*Breed

	if err := c.execGet("/breeds", query, &breeds); err != nil {
		return nil, err
	}

	return breeds, nil
}

Basically we have 9 loc for one API. WHAAAA!

Search Breeds API

Let's extend the Cat API Client with a search functionality for demo purposes. The response format does not change so we have the Breed struct and all required data models in place.

func (c *CatApiClient) SearchBreeds(query url.Values) ([]*Breed, error) {
	var breeds []*Breed

	if err := c.execGet("/breeds/search", query, &breeds); err != nil {
		return nil, err
	}

	return breeds, nil
}

As expected also this API call did not forced us to write any extra logic for making a request to Cat API.

Lazy Authentication

There was a topic that I really wanted to discuss there about a specific scenario that I encountered at my work. What if our access key is expirale? In such case we would need to renew it. The best is to handle this process as smoothly as possible. Unfortunately, Cat API has a non expirable access key so the code from now on will be hypothetical just for demonstration purposes.

First of all we need a new method for handling refresh token/access key procedure. This method will be called in low level helper functions such as execGet for better code reusability.

func (c *CatApiClient) execGet(path string, query url.Values, output interface{}) error {
	if c.hasTokenExpired() {
		if err := c.refreshToken(); err != nil {
			return err
		}
	}

	url := c.host
	url.Path = "/" + c.version + path
    ...
}

func (c *CatApiClient) refreshToken() error {
	c.refreshMutex.Lock()

	if c.hasTokenExpired() == false {
		return nil
	}

	accessKey, err := retrieveNewToken("token refresh string or credentials")
	if err != nil {
		return err
	}

	c.accessKey = accessKey
	expiry := 120 * time.Second // define token expiry in seconds or whatever 		and add offset to avoid invalid expiry
	c.tokenExp = time.Now().Add(expiry)

	c.refreshMutex.Unlock()

	return nil
}

func (c *CatApiClient) hasTokenExpired() bool {
	t := time.Now()

	return t.After(c.tokenExp)
}

The refresh token procedure starts with a mutex lock. You may ask why we need one? In such case I did not want to call the retrieveToken multiple times to get different tokens because that would be just a waste of resources. Instead only one caller who gets the lock can enter inside the critical region(code between lock and unlock).

After the lock is passed, a check for token expiration is done. If the token has expired, a new one is retrieved calling retrieveNewToken. For other callers which are blocked by the mutex, this check condition will be satisfied as the token is renewed by the first call.

After the token is retrieved, client struct properties will be updated accordingly. Here it is important to mention the calculation of the expiry for the token. I would suggest to set an expiry earlier that the amount given in the service authentication specification by 5 - 10s so we avoid a false positive in token expiry check.

Conclusions

Sometimes we may  need to interact with external REST API services which may not have a client library in the language our application is being coded. In such case the best approach is to abstract the interaction with the said service in a dedicated entity for better testing and maintenance. It is critical to provide a smooth authentication mechanism which supports token token renewal under the hood. A good attention should be paid to the code reusability which is an investment in the long-term. It is necessary to see the big picture and think about it before going straight into writing a certain functionality.

The source code can be found there.

When getting into NodeJS, the first thing that might be a surprise is its single threaded model. Nowadays most OS support multi-core CPU architecture and threading which enables developers to perform multiple operations at the same time. But does NodeJS take advantage of multi-threading or it is really single threaded? How does it perform CPU-bound operations linked to hardware like I/O or other heavy operations like DNS lookup? I will try to give an answer to these questions throughout this article.

The Nature of I/O and CPU Bound Operations

Peripheral devices require a way of communication with CPU to arrange their operations like data transfer etc. The most used modes of achieving such communication are: programmed I/O, interrupt initiated I/O, direct memory access. All of these modes require some kind interruption signal to notify the CPU to continue. This means that a waiting mechanism is needed for the data to be ready and process them chunk by chunk, but can we wait on the main thread? The answer is no because we have just one thread and this will result in a very high impact in performance and thus in scalability. Imagine that at one moment the application is serving 1000 clients and one of them just called an API which needs to perform some I/O by reading a file. At this point, the time needed to read that file will add up to the response time of all connected clients. Such situation can quickly escalate if several clients needs to perform I/O operations at the same time.

CPU-bound operations are also very demanding in CPU processing and they may take a considerable time to complete. During this period of time, the thread is completely busy and cannot process other operations.  In this category can be highlighted cryptographic algorithms such as PB2KF or DNS lookup which are very demanding in CPU processing.

NodeJS really needs to offload such kind of operation from the main thread in order to offer the promised scalability. That is achieved by taking the advantage of Libuv.

Libuv

At the core of NodeJS stands Libuv whose main functionality is to provide an engine for offloading heavy operations from the main thread. Here is a description from libuv repository

libuv is cross-platform support library which was originally written for Node.js. It’s designed around the event-driven asynchronous I/O model.

The library provides much more than a simple abstraction over different I/O polling mechanisms: ‘handles’ and ‘streams’ provide a high level abstraction for sockets and other entities; cross-platform file I/O and threading functionality is also provided, amongst other things.

Libuv is a library written in C which implements event loop queues and OS API calls.  Let's take a closer look into libuv internals.

Network I/O is performed in the main thread. Libuv takes advantage of asynchronous sockets which are polled using the best mechanism provided by the OS: epoll on Linux, kqueue on MacOS, event ports on SunOS and IOCP on Windows. During the loop iteration, the main thread will block for a specific amount of time waiting for the activity on the sockets which have been added to the poller and respective callbacks will be fired to indicate socket conditions(closed, open, ready to read / write).

On the other hand, functionalities that are synchronous by nature such as file I/O, are processed on a separate thread taken from a global thread pool. The same is done for some very expensive operations related to DNS such as getaddrinfo and getnameinfo.

Event Loop

Event Loop is an abstract concept which is used to model the event-driven architecture of NodeJS. It consist of six phases. Each phase has a dedicated FIFO queue of callbacks which are drained when the loop enters in that given phase.

As illustrated in the following diagram, a loop tick starts with timers, continues clock-wise to execute all phases and finishes with the execution of Close Callback phase. At the end, loop decides if it should continue another tick or exit there depending on the loop running mode(default, once, nowait) and whether there are active handles or not.

Note: As the execution of the loop progresses, more and more callback may be pushed into a given queue. This can block the event loop forever if we  make a high number of calls which adds to MicroTasks queue for example. This scenario can happen in the case when we call a Promise recursively. This does not apply to timers which despite of giving them a 0 threshold, the execution of them is delayed to the next loop tick, after which it is rescheduled again.

Timers

A timer specifies the threshold in ms after which its callback will be fired.

The loop starts with the timers phase. A timer's callback is executed as soon as its specified time threshold has passed. However, OS scheduling like process / thread priority or the execution of other callbacks in other phases may delay the execution of a timer. Technically, the polling time in poll phase adds up to the execution delay of a timer.

Pending Callback

After "Timers" phase, the loop enters into "Pending Callbacks" phase. This phase is dedicated for operation which could not be completed during the previous run of the loop. More precisely lets take a TCP socket ECONNREFUSED error as an example. Most operating systems will wait for a time threshold/timeout before reporting such problem and for that reason the throw of this error may be scheduled in the Pending Callback phase.

Idle, Prepare

This phase is completely dedicated for internal usage to libuv. For example, in this phase are initialized libuv handles such as TCP/UDP handles etc. Some handles may need some time to be ready like setting up a TCP connection and this phase is ideal for running post handle initializations.

Poll

This is one of the most important phases which takes care for the processing of I/O operations. It has two important tasks:

1. calculate timeout for I/O polling (it cannot wait forever because this will block the event loop)
2. drain poll event queue which is populated during the polling

How is  the polling timeout calculated? If we poll too much time, timers will be executed late and this impacts negatively their reliability. To understand this we need to dig deep in NodeJS source code at core.c.

int uv_run(uv_loop_t* loop, uv_run_mode mode) {
 	...
    timeout = 0;
    if ((mode == UV_RUN_ONCE && !ran_pending) || mode == UV_RUN_DEFAULT)
      timeout = uv_backend_timeout(loop);

    uv__io_poll(loop, timeout);
    ...
}

int uv_backend_timeout(const uv_loop_t* loop) {
  if (loop->stop_flag != 0)
    return 0;

  if (!uv__has_active_handles(loop) && !uv__has_active_reqs(loop))
    return 0;

  if (!QUEUE_EMPTY(&loop->idle_handles))
    return 0;

  if (!QUEUE_EMPTY(&loop->pending_queue))
    return 0;

  if (loop->closing_handles)
    return 0;

  return uv__next_timeout(loop);
}

From the given snippet of code,  uv_run is the main method which executes all phases. It can be seen that before jumping to the Poll Phase a timeout is calculated by calling uv_backend_timeout. If there are more pressing matters such as processing idle or active handles etc the loop will enter in the Poll phase but it will return early because the timeout is 0. Now for the timers, the polling timeout is calculated by calling uv__next_timeout which gets the nearest timer duration when the timer should be fired and this ensures that timers wont be blocked by polling for I/O.

When the watcher queue is empty, there is no need to wait for the calculated polling timeout because there are no I/O operations registered so the loop will move immediately to the Check phase.

Check Phase

This phase processes setImmediate callback queue. Based on my analysis of the source code, after the first immediate callback is processed, the MicroTask queue is exhausted implicitly as can be seen in the following code snippet by calling runNextTicks:

function processImmediate() {
    const queue = outstandingQueue.head !== null ?
      outstandingQueue : immediateQueue;
    let immediate = queue.head;

    // Clear the linked list early in case new `setImmediate()`
    // calls occur while immediate callbacks are executed
    if (queue !== outstandingQueue) {
      queue.head = queue.tail = null;
      immediateInfo[kHasOutstanding] = 1;
    }

    let prevImmediate;
    let ranAtLeastOneImmediate = false;
    while (immediate !== null) {
      if (ranAtLeastOneImmediate)
        runNextTicks();
      else
        ranAtLeastOneImmediate = true;
        
        ...
      }
    }

Here it is the definition of runNextTicks where runMicroTasks is invoked.

function runNextTicks() {
  if (!hasTickScheduled() && !hasRejectionToWarn())
    runMicrotasks();
  if (!hasTickScheduled() && !hasRejectionToWarn())
    return;

  processTicksAndRejections();
}

During my study of NodeJS source code I had a hard time figuring out how the MicroTask queue was handled. It seems that they are treated with a high priority after the nextTick callbacks.

Close Callbacks

This phase is dedicated to process callbacks that should be fired after a resource is destroyed abruptly such a socket for example where 'close' is invoked during this phase. However, in normal situations such events are dispatched by using nextTick.

process.nextTick

Technically, nextTick is part of asynchronous NodeJS API. It has a dedicated queue for queuing callbacks called nextTickQueue. This queue is exhausted after the current operation is completed, regardless of the current phase of the event loop.

This API is very powerful for executing logic at a very high priority, even higher than micro tasks. At the same time it should be used with caution as it can starve the event loop as stated in the official docs:

Looking back at our diagram, any time you call process.nextTick() in a given phase, all callbacks passed to process.nextTick() will be resolved before the event loop continues. This can create some bad situations because it allows you to "starve" your I/O by making recursive process.nextTick() calls, which prevents the event loop from reaching the poll phase.

References

• https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/
• https://www.cs.uic.edu/~jbell/CourseNotes/OperatingSystems/13_IOSystems.html
• https://www.geeksforgeeks.org/io-interface-interrupt-dma-mode/
• https://cfsamson.github.io/book-exploring-async-basics/6_epoll_kqueue_iocp.html