Backend Cafe

React Server-Side Streaming with Fastify

Manuel Spigolon — Mon, 16 Mar 2026 09:30:00 GMT

React 18+ introduced renderToPipeableStream, a powerful API for streaming server-rendered HTML to the browser. Instead of waiting for the entire page to render before sending it to the client, you can start sending HTML as soon as it's ready.

In this article, we'll build a minimal Fastify server that streams a React component to the browser using Node.js streams. No build tools, no TypeScript — just a simple setup you can run in seconds.

Setting up the project

We'll use Node.js 20+ and Fastify v5 for this tutorial. Since we're using React.createElement directly, we don't need JSX or any build step.

mkdir fastify-react-streaming
cd fastify-react-streaming

npm init es6 --yes

npm install fastify@5 react@19 react-dom@19

How does reply.hijack() work?

By default, Fastify manages the response lifecycle for you: it serializes your return value, sets headers, and sends the response. But sometimes you need full control over the raw Node.js http.ServerResponse, for example when you want to pipe a stream directly to the client.

That's what reply.hijack() does. When you call it, Fastify steps aside and hands you the raw response object via reply.raw.

From that point on, you are responsible for writing headers, sending data, and ending the response.

This is exactly what we need for React streaming: renderToPipeableStream expects a writable Node.js stream to pipe into, and reply.raw is just that.

Streaming a React component

Create a file named app.js:

import Fastify from 'fastify'
import React from 'react'
import { renderToPipeableStream } from 'react-dom/server'

const app = Fastify({ logger: true })

app.get('/', async (req, reply) => {
  reply.hijack()

  const stream = renderToPipeableStream(
    React.createElement('div', null, 'Hello from React streaming!'),
    {
      onShellReady () {
        reply.raw.setHeader('Content-Type', 'text/html; charset=utf-8')
        stream.pipe(reply.raw)
      },
      onShellError (err) {
        reply.raw.statusCode = 500
        reply.raw.setHeader('Content-Type', 'text/html; charset=utf-8')
        reply.raw.end('Something went wrong')
        console.error(err)
      },
      onError (err) {
        console.error(err)
      }
    }
  )
})

await app.listen({ port: 3000 })

Let's break down what's happening:

reply.hijack() tells Fastify we'll manage the response ourselves. Without this, Fastify would try to send its own response and conflict with our stream.
renderToPipeableStream takes a React element and returns a stream object. We use React.createElement directly instead of JSX, so no build step is needed.
onShellReady fires when the initial HTML shell is ready to be sent. At this point, we set the Content-Type header and pipe the stream into reply.raw — the underlying Node.js response.
onShellError fires if the initial shell fails to render — before any HTML has been sent to the client. Since the response hasn't started yet, we can still set a proper status code and send a fallback HTML page. This is the right place to handle fatal rendering failures.
onError handles errors that occur after the shell has been sent and streaming has begun. At that point, headers and status code are already flushed, so we can only log the error.

Start the server:

node app.js

Open http://localhost:3000 in your browser and you'll see the streamed HTML response.

Why streaming matters

For this simple example, the difference between streaming and a regular renderToString call is negligible. But streaming becomes important when your React tree includes:

boundaries with async data fetching: the shell is sent immediately while suspended parts stream in later.
Large component trees: the browser can start parsing and displaying HTML before the server finishes rendering everything.

The onShellReady callback is the key: it fires as soon as the content above any boundary is ready, letting the browser start rendering right away.

Summary

With just a few lines of code, we've set up React server-side streaming in Fastify using reply.hijack() and renderToPipeableStream. No bundlers, no JSX compilation! Just Node.js, React, and Fastify working together.

The source code for this project is available on GitHub.

If you enjoyed this article, comment, share and follow me on Twitter!

Signing git commits with GPG

Manuel Spigolon — Sun, 18 Jan 2026 09:02:13 GMT

Did you see the "Verified" badge on some GitHub commits and wonder how to get it for your own commits?

Well,GitHub shows the ‘Verified’ badge when a commit has a valid signature from a trusted key (GPG, SSH, S/MIME, or GitHub’s own). In this article we’ll focus on the GPG path: generating a key pair, registering the public key with GitHub, matching the key’s email to your GitHub account, and configuring git to sign your commits so GitHub can verify them.

A signature proves the commit came from someone who controls a specific private key, instead of just "whatever machine happened to use your name and email" in the git config. For example, a dummy attack could be to commit code on a Pull Request on behalf of another developer, by using their name and email in the commit metadata to trick maintainers into thinking the commit is legitimate and merging it without proper review.

In fact, by simply changing the git config user name and email, you can impersonate anyone:

With the "Verified" badge, you will get trust for your contributions and it defends against impersonation.

So, would you like to learn how to sign your git commits with GPG? Let's get started!

Setup GPG

First, you need to have GPG (GNU Privacy Guard) installed on your machine (available for Windows, macOS, and Linux). GPG is an open-source implementation of the OpenPGP standard used for public-key cryptography, primarily for encrypting data, signing data, and managing cryptographic keys.
It works by maintaining a keyring of public and private keys and applying asymmetric cryptography for key exchange and identity verification, often combined with symmetric cryptography for actual data encryption.

The gpg-agent is a long-running background process that handles private key operations on GPG’s behalf: it securely caches decrypted private keys in memory, prompts for passphrases, integrates with smart cards or hardware tokens, and exposes a socket-based API so GPG and other tools don’t repeatedly access private key material. In practice, GPG delegates all sensitive key usage to gpg-agent, which reduces passphrase prompts, centralizes key protection, and limits how often private keys are decrypted.

That sounds complicated, but don't worry; once it is configured, it will work seamlessly in the background!

If you are using macOS, the easiest way to install GPG is by using Homebrew:

brew install gnupg

Pinentry

Another important component is the pinentry program, which is a collection of simple user interface dialogs used by GPG and gpg-agent to securely prompt users for sensitive information, such as passphrases or PINs. It ensures that sensitive data is entered in a secure manner, preventing exposure to other applications or potential keyloggers.

To install it, you can follow the official website or use your system package manager again:

brew install pinentry-mac

To configure gpg-agent to use pinentry, you need to edit (or create) the gpg-agent.conf file located in the GPG home directory (usually ~/.gnupg/):

echo "pinentry-program /usr/local/bin/pinentry-mac" >> ~/.gnupg/gpg-agent.conf
# Restart gpg-agent to apply the changes
gpgconf --kill gpg-agent

💡 The ~/.gnupg/gpg-agent.conf file may include the default-cache-ttl and max-cache-ttl settings to control how long the passphrase is cached in memory

Good, if you have GPG installed, the gpg command should be available in your terminal and we can start using it.

Create a GPG key pair

To sign your git commits, you need to create a GPG key pair (a public key and a private key). Creating a GPG key pair can be done using the following command:

gpg --full-generate-key

This will prompt you to select some options for your key pair; let's go through them briefly:

Key type: You can choose the default option by pressing Enter. Select the option based on the supported algorithms of your environment. In our case, ECC is a good choice because GitHub supports it
Elliptic curve: You can choose the default option (Curve 25519) by pressing Enter
Key expiration: You can choose how long the key will be valid. It is a good practice to set an expiration date for security reasons such as 1y (1 year) in case you stop using a laptop or device
Real name: Enter your full name as you want it to appear in the commit signature
Email address: Enter the email address associated with your GitHub account
Comment: Add a comment to help you identify the key later
Passphrase: Choose a strong passphrase to protect your private key. Don't forget it! Here we expect pinentry to prompt you for it.

To list the keys you have created, you can use the following command:

# list private (secret) keys
gpg --list-secret-keys --keyid-format=long

The output will look like this:

sec   ed25519/CACEF4B5F2457FA1 2026-01-17 [SC] [expires: 2027-01-17]
      3FDF83A1577BED43B90F0D63CACEF4B5F2457FA1
uid                 [ultimate] Backend Cafe (Demo cert) 
ssb   cv25519/D732AC59B5E3FC30 2026-01-17 [E] [expires: 2027-01-17]

In this example, the GPG key ID is CACEF4B5F2457FA1, take note of it because we will need it later.

Verify GPG signing works

To verify that GPG signing works, we can just sign a test message:

echo "test" | gpg --default-key CACEF4B5F2457FA1 --sign --armor

This should prompt you for your passphrase (handled by pinentry) and output a signed message block like this:

gpg: using "CACEF4B5F2457FA1" as default secret key for signing
-----BEGIN PGP MESSAGE-----

owGbwMvMwCV26tyXrZ9c6xcynuZOYsjMXra[...truncated for brevity...]
V98zj+7xb4EP/2rw9pVWn3rMBAA===ma+I
-----END PGP MESSAGE-----

If everything works fine, you can proceed to the next step.

Configure GitHub to verify your GPG signatures

To configure GitHub to verify your GPG signatures, you need to add your public GPG key to your GitHub account. First, export your public GPG key using the following command:

gpg --armor --export CACEF4B5F2457FA1

This will output something like this:

-----BEGIN PGP PUBLIC KEY BLOCK-----

mDMEaWulshYJKwYBBAHaRw8B[...truncated for brevity...]
-----END PGP PUBLIC KEY BLOCK-----

Now copy the entire output (including the -----BEGIN PGP PUBLIC KEY BLOCK----- and -----END PGP PUBLIC KEY BLOCK----- lines) and go to your GitHub account settings at:

Navigate to Settings > SSH and GPG keys > New GPG key

Or just go to this URL https://github.com/settings/gpg/new.

Paste your public GPG key into the "Key" field and click on the "Add GPG key" button to save it. Now GitHub will be able to verify your signed commits.

Configure Git to sign commits by default

The last step is to configure your local git to sign commits by default using your GPG key. You can do this by running the following commands:

git config --global user.signingkey CACEF4B5F2457FA1
git config --global commit.gpgSign true
git config --global gpg.program gpg

This will edit your ~/.gitconfig file to include the following lines:

[user]
    name = Demo cert
    email = be@demo.com
    signingkey = CACEF4B5F2457FA1
[commit]
    gpgsign = true
[gpg]
    program = gpg

Test it!

Fantastic! Now everything is set up, and it is time to test it! Create a new git commit in any of your repositories and push the code to GitHub. After pushing, go to the commit page on GitHub, and you should see the "Verified" badge next to your commit message!

Backup your GPG keys

It is crucial to back up your GPG keys, especially the private key, as losing it means you won't be able to sign commits and you will need to create a new key pair. You can back up your keys by exporting them to a file:

# export private (secret) key
gpg --export-secret-keys --armor CACEF4B5F2457FA1 > CACEF4B5F2457FA1-secret.asc

Make sure to store this file in a safe place, preferably in an offline location such as an encrypted USB drive.

To restore your keys from the backup file, you can use the following command:

gpg --import CACEF4B5F2457FA1-secret.asc

That's it!

Summary

This guide shows you how to get the “Verified” badge on your GitHub commits by generating a GPG key pair, configuring gpg-agent and pinentry, and registering your public key with GitHub.

It walks through creating and testing your key, setting git to sign commits automatically, and safely backing up your private key so you don’t lose your signing identity.

If you enjoyed this article, comment, share and follow me on X!

Beyond Vibe Coding

Maksim Sinik — Thu, 07 Aug 2025 17:03:42 GMT

Marcus gets a "quick fix" request from his product manager. The user authentication flow needs "just a small tweak", maybe an hour of work. He fires up his AI coding assistant and starts exploring the auth module.

Three hours later, Marcus has rewritten two components, discovered a hidden dependency that breaks when touched, and created a bug that affects the shopping cart in an unexpected way. His AI assistant has been helpful, but keeps suggesting solutions that create new problems. The "quick fix" is now a two-day refactor, and nobody understands why.

Meanwhile, Sarah, on the same team, receives a similar request. But Sarah works differently. She spends time analyzing the authentication system's history, documenting potential ripple effects, and mapping out an implementation strategy before writing any code. Only then does she engage her AI assistant, but now with rich context about business constraints, technical dependencies, and architectural patterns. The result: a clean solution written in thirty minutes, almost entirely by the AI, that integrates seamlessly with existing systems.

Same team. Same AI tools. Completely different outcomes.

The difference? Sarah treats her AI assistant as a collaborative partner in understanding, not just a code generator. She's evolved beyond vibe coding.

When AI Amplifies Chaos

Vibe coding isn't new. Developers have been copying and pasting from Stack Overflow for years. However, AI has made this dangerous: you can now transition from a gut feeling to production bugs in seconds, not hours.

"I'll figure it out as I go."

"This feels like the right approach."

"Let's just try it and see what happens."

These phrases define vibe coding, development driven by intuition and reactive problem-solving, as well as whatever knowledge happens to be in someone's head at the moment.

Here's the problem: AI makes bad practices faster, not better practices easier. When you prompt an AI with "make this work," you get code that works in isolation but breaks everything else. When your context is "fix this bug," you get a fix that creates three new bugs.

This is where the evolution matters. AI tools excel at generating code quickly. They struggle to understand why that code matters, what it affects, and how it fits into the larger system. The key insight is that without structured context management, your AI assistant becomes a speedy way to create very sophisticated technical debt.

However, when you evolve your approach, moving from vibe coding to systematic context building, AI becomes something entirely different: a partner that amplifies good practices instead of accelerating bad ones. How do you evolve from Marcus's chaotic approach to Sarah's systematic method? How do you build that kind of contextual thinking?

My Journey: Discovering Context by Evolution

Two months ago, I was Marcus. I'd get a feature request, fire up Claude Code, and start coding immediately. Sometimes it worked brilliantly. Sometimes I'd create more problems than I solved.

My first breakthrough came when I realized I needed better implementation patterns. I created a specialized "executor" agent, a Claude session focused solely on writing clean, consistent code. This helped, but I continued to encounter architectural problems.

So I built a "planner" agent to design before implementing. Now I had two agents: one for planning and one for execution. Better, but still missing something crucial. My plans kept hitting unexpected constraints because I didn't understand the existing system well enough.

That led to my "discoverer" agent, designed to understand legacy systems and business context before planning began. Three agents working in sequence: discover, plan, execute. Each one created a richer context that the next consumed.

But complex features needed more than this linear flow. I found myself needing strategic analysis upfront, systematic work breakdown, and ongoing project monitoring. What started as a single "executor" agent evolved into six specialized reasoning capabilities, each designed to excel in a specific type of contextual thinking.

This evolution taught me something profound: I wasn't just building better AI tools for myself, I was discovering a systematic approach to managing context throughout development. What I now call Contextual Intelligence.

Enter Contextual Intelligence

What if your AI assistant knew not just what to build, but why you're building it, how it connects to existing systems, and what success actually looks like?

Contextual Intelligence is the disciplined practice of ensuring the correct information reaches the right decisions at the right time. Instead of losing context between phases, you deliberately capture, enrich, and transfer understanding so that each development decision builds on accumulated knowledge rather than fragmented assumptions.

This isn't about having smarter AI tools or better prompts. It's about fundamentally changing how we structure the relationship between human insight and AI capability. Instead of treating AI as a better search engine or a faster code generator, contextual Intelligence treats AI as a collaborative partner in building and maintaining understanding.

Every development decision requires context, but we treat context like magic. It exists in someone's head, gets lost in Slack threads, or lives in comments that nobody remembers writing. Rebuilding a fragmented context can lead to poor decisions, resulting in subpar code and accumulating technical debt.

Contextual Intelligence operates on four core principles:

Capturing: Document not just what you're building, but why you're building it, what constraints shape the solution, and what success looks like from multiple perspectives. This extends beyond the requirements to encompass business context, technical constraints, and stakeholder expectations.
Processing: Transform raw information into decision-ready insights through specialized analysis. Instead of a generic "understand the codebase," you get targeted investigations: "identify authentication patterns that will be affected by this change" or "map business rules that constrain this feature."
Transferring: Ensure context flows between phases without degradation. The person implementing code has access to the strategic reasoning behind architectural decisions. The person debugging production issues understands the business constraints that shaped the original feature.
Specializing: Match different types of contextual reasoning to different kinds of problems. Strategic analysis requires different thinking patterns than implementation planning, which differs from production debugging. Each specialized approach amplifies AI assistance in its specific domain.

The breakthrough isn't just organizing context better. It's recognizing that AI excels at this kind of systematic context management when properly guided.

Contextual Intelligence doesn't replace existing methodologies, such as Domain-Driven Design, Event Storming, or Architecture Decision Records. Instead, it amplifies them. Your DDD sessions generate richer context when guided by strategic analysis. Your ADRs become more comprehensive when informed by systematic discovery. Your architectural patterns integrate more smoothly when implementation follows contextual planning.

The key insight is that AI excels at this kind of cross-methodology context synthesis when it is adequately specialized for each type of reasoning.

Beyond Tools: A Way of Thinking

Experienced engineers already have a structured approach to the problems. They know what information matters when discussing business stakeholders versus troubleshooting production issues. They understand which parts of the codebase will be affected by a new feature. They can estimate refactoring efforts because they grasp the full scope of changes.

The transformation occurs when these thinking patterns become well-known and repeatable:

Explicit: Everyone knows what type of thinking is needed when
Systematic: Consistent approaches rather than ad hoc reactions
Transferable: New team members learn proven patterns, not personal preferences
Augmentable: AI assistance amplifies good practices instead of accelerating bad ones
Iterative: Teams can refine and enhance their approaches over time

Implementing Contextual Intelligence: The Persona Approach

Traditional development is prone to inevitable information loss. The business analyst who understood edge cases isn't the person writing code. The architect who made trade-off decisions isn't debugging production issues months later. The developer who built the feature is no longer maintaining it.

Requirements documents get stale. Architecture decisions get forgotten. Implementation details exist only in someone's head until they leave the company.

Contextual Intelligence flips this pattern. Each development phase enriches the context for the next phase. Instead of progressive information loss, you get progressive context accumulation.

After months of developing these specialized agents, I discovered that Nicholas Zakas had published a similar concept in his article "A persona-based approach to AI-assisted programming". Interestingly, I had been calling my agents by functional names, "the discoverer," "the planner," "the executor", until reading his work made me realize I was essentially creating personas for different types of reasoning. This insight led me to fully embrace the persona concept.

Where Zakas focuses on leveraging the strengths of different AI models for distinct roles, my approach emphasizes building and transferring persistent understanding between development phases. Both approaches share the core insight that specialized AI agents outperform generic assistants. However, they solve different problems.

The persona approach I developed identifies six distinct agents, each designed to excel at specific types of contextual reasoning:

🔮 The Farseer - Strategic Contextual Intelligence

Transforms "this sounds good" into a systematic feasibility assessment

Before Sarah started coding, she analyzed whether the authentication change aligned with the product roadmap, identified potential conflicts with upcoming features, and assessed technical risks. The Farseer persona transforms "this sounds good" into a systematic feasibility assessment by asking: What business constraints will this change reveal? What technical debt will it expose? Which stakeholders need to approve this direction?

👻 The Spiritwalker - Archaeological Contextual Intelligence

Bridges knowledge gaps between system experts and newcomers

The Spiritwalker helped Sarah understand why the authentication system was built the way it was, what constraints had shaped its design, and which assumptions still held true. This persona specializes in legacy system discovery, excavating the historical context buried in code comments, Git history, and institutional memory to prevent "simple changes" from becoming unexpected refactorings.

🦏 The Kodo - Architectural Contextual Intelligence

Creates implementable designs before coding begins

Instead of figuring out the architecture while coding, the Kodo persona maps out technical approaches upfront. Sarah knew exactly how his change would integrate with existing patterns, what new patterns might be required, and, most importantly, how to minimize complexity rather than inadvertently increase it.

⚔️ The Chieftain - Organizational Contextual Intelligence

Breaks overwhelming requirements into manageable work

Complex features often conceal multiple user stories disguised as a single requirement. The Chieftain persona systematically decomposes features by user impact, technical dependency, and risk profile, transforming "add social login" into separate stories for OAuth integration, user migration, privacy compliance, and error handling, each with clear acceptance criteria.

🗡️ The Grunt - Implementation Contextual Intelligence

Delivers consistent quality through systematic patterns

The Grunt persona ensures implementation follows established team patterns and quality standards. Far from mindless execution, this persona applies hard-won implementation wisdom: which error handling patterns work in this codebase, how to write maintainable tests, and when to refactor versus working around existing code.

🧙 The Witchdoctor - Diagnostic Contextual Intelligence

Provides early warning systems for project health

Projects fail gradually, then suddenly. The Witchdoctor persona monitors system health through multiple lenses: Are implementation decisions aligning with architectural plans? Is technical debt accumulating faster than expected? Are stakeholder expectations drifting from actual capabilities? Early warning systems prevent minor problems from escalating into project-crippling crises.

Making It Real: Building the System

The evolution from those initial throw-away Claude Code sessions to systematic contextual Intelligence didn't happen overnight. Once I recognized the pattern, I had to figure out how to make it work reliably.

The key insight was that each persona needed to both consume context from previous phases and generate enriched context for the next. This isn't just about having six different AI assistants. It's about creating a context pipeline where understanding accumulates and transfers.

Here's how it works in practice:

The Farseer analyzes a business request and saves strategic context, including market constraints, business priorities, and technical feasibility boundaries. This context becomes the foundation that The Spiritwalker uses to determine which parts of the existing system are relevant to this specific change.

The Spiritwalker's archaeological findings inform The Kodo, which now possesses both business context and system understanding to create architectural plans that respect existing patterns while achieving business goals.

The Kodo's technical design guides The Chieftain in breaking down work into stories that reflect both the technical realities and business priorities. Each story carries forward the accumulated understanding.

The Grunt implements these stories with full context about why each decision was made, what constraints matter, and how the code fits into the larger system vision.

Finally, The Witchdoctor monitors progress with a complete understanding of what success looks like from business, technical, and organizational perspectives.

At each handoff, context isn't lost. On the contrary, it's enriched. By the time you're implementing, you're not coding from requirements. You're coding from understanding.

This is what transforms vibe coding into systematic development: persistent context that flows between specialized reasoning capabilities, each adding its own layer of insight while preserving everything that came before.

A Quick Note on Naming (Yes, I love The Frozen Throne)

Before you think I've lost my mind with these agent names, let me explain: they're all borrowed from "Warcraft 3: The Frozen Throne" orc units, and it turns out that Blizzard's game designers accidentally created perfect metaphors for software development workflows. The Farseer has "Farsight" to reveal distant areas of the map, just like strategic planning reveals business landscapes. The Spiritwalker exists in ethereal form to bridge different worlds, much like bridging knowledge gaps in legacy systems. The Kodo Beast devours enemies whole and uses war drums to boost nearby allies, which is basically what good architecture does to complexity. The Grunt is the reliable warrior who actually gets stuff done. And the Witchdoctor places sentry wards across the battlefield for early warning systems, exactly like project health monitoring.

The more I thought about it, the more I realized these fantasy units capture the essence of different types of contextual reasoning better than any corporate buzzwords ever could. Plus, "Farseer Analysis" sounds way more interesting than "Strategic Requirements Assessment."

The Path Forward

Marcus is still debugging his "quick fix." Sarah shipped her change and moved on to implementing the next feature with confidence.

The transformation isn't about having a better AI tool. It's about evolving your relationship with AI from a reactive assistant to a collaborative partner in building understanding.

You don't need to implement all six personas to start reaping the benefits. Choose the area where you struggle most: strategic alignment, system understanding, architectural planning, work breakdown, implementation quality, or project monitoring. Build contextual Intelligence in that one area, and watch how it transforms not just your code, but your entire development process.

Over the next six posts, I'll share the specific configurations, prompts, and workflows that make each persona effective. However, the real journey begins with recognizing that context isn't magic. It's a discipline. And disciplines can be learned, systematized, and shared.

Ready to evolve beyond vibe coding?

A Note on AI Tool Dependencies: This approach relies on the availability and effectiveness of AI assistance. The personas, prompts, and workflows I'll share are built for current AI capabilities. As these tools evolve, the specific implementations will need to adapt, but the underlying principles of structured context management remain tool-agnostic.

Next up: Part 1: The Farseer*, From gut feelings to systematic feasibility assessment, plus the complete Claude agent implementation for strategic analysis.*

Handling HTTP timeouts in Fastify

Manuel Spigolon — Fri, 30 May 2025 08:10:08 GMT

The hardest part of my job is thinking like a malicious user... or like an AI in its early stages of writing HTTP servers!
This exercise is not easy because I love my clients' HTTP requests, and I'm sure they love my server!
But that is not always the case... for this reason, we must be prepared to handle unexpected situations.

In this article, we will explore all the options available in Fastify to handle timeouts!
A poorly implemented client or a malicious user could kill your server if we are not careful!

How many timeouts do I need?

Before listing all the timeout options available in Fastify, let's take a moment to understand the HTTP request lifecycle and identify where we need to set timeouts.

In the following diagram, we can see a simplified HTTP request lifecycle that includes the most important steps:

Establishing a TCP connection to create a socket.
TLS handshake (if using HTTPS).
At this stage, the socket is open, and the server is waiting for the client to send the HTTP request as the protocol requires.
The server receives the request and processes it.
The server sends the response to the client.
The server either closes the connection or keeps it alive for future requests using the same socket.

In the diagram, the timeouts are represented with a clock icon ⏰.
So, let's review them all (note that the default values are Fastify defaults, not the Node.js ones):

Timeout setting	Description
`headersTimeout`	Specifies the number of milliseconds to wait for the complete HTTP headers to be received. If the headers are not received within this period, the connection is terminated. Default: `no-limit`
`requestTimeout`	Defines the maximum duration, in milliseconds, to wait for the entire request from the client. If the request body isn't fully received within this time frame, the connection is closed. Default: `no-limit`.
`connectionTimeout` (aka `timeout`)	Sets the socket inactivity timeout in milliseconds. If there's no activity on the socket for the specified duration, the server closes the connection. Default: `no-limit`
`keepAliveTimeout`	Determines the time, in milliseconds, to wait for additional requests on a persistent connection (keep-alive). If no new request is received within this period, the server closes the connection. Default: 72 seconds
`connectionsCheckingInterval`	Sets the interval value, in milliseconds, to check for request and headers timeout in incomplete requests. Default: 30,000

Wow, that's a lot of timeouts! But why do we need all of them?

All these timeouts are crucial to ensuring that the server can handle incoming requests efficiently and prevent resource exhaustion. Otherwise, a malicious user could send a request with a large payload and keep the connection open indefinitely, causing the server to run out of memory or file descriptors!

For example, headersTimeout ensures that the server doesn't wait indefinitely for the client to send the headers.
This option helps prevent the Slowloris attack, where an attacker sends headers very slowly to keep the connection open and exhaust server resources.

Now that we understand timeouts and their importance, let's see how to set them up in Fastify.

Setting up timeouts in Fastify

To configure timeouts in Fastify, we must pass the options when creating the Fastify instance.
Here's a TL;DR example:

import fastify from "fastify";

const app = fastify({
  // 2 minutes: a reasonable timeout for processing requests, balancing performance and user experience
  connectionTimeout: 120_000,

  // 1 minute: suitable for most payloads, including moderate file uploads
  requestTimeout: 60_000,

  // 10 seconds: ensures efficient resource usage for idle connections
  keepAliveTimeout: 10_000,

  http: {
    // 15 seconds: prevents slow clients from holding connections too long
    headersTimeout: 15_000,
  },
});

These are general recommendations, and the actual values may vary based on your application and use case.
Be sure to think about the following:

Protect the server: Prevent resource exhaustion by limiting how long connections can remain open or idle.
Enhance client experience: Provide sufficient time for legitimate requests, even under less-than-ideal network conditions.
Balance performance and security: Avoid excessively long timeouts that could lead to inefficiency or abuse, while ensuring the server remains responsive.

Now, let's test the timeouts!
I created a simple Fastify v5 server and a client to test the timeouts.
For the sake of simplicity, the code can be found on GitHub and is not included in this article.

Testing timeouts

If you have downloaded and installed the code from the GitHub repository, we can run the server with Node.js v20+ and the following command, and we can set the timeouts via optional arguments:

# To start the server
node server.js --connectionTimeout 10000 \
  --requestTimeout 20000 \
  --keepAliveTimeout 5000 \
  --headersTimeout 30000 \
  --handlerTimeout 5000 \
  --connectionsCheckingInterval 10000

Then, we can run the client with the following command, where we can set the payload and header rate:

--headerRate: we send a header every headerRate milliseconds
--payloadRate: we send a byte every payloadRate milliseconds
--keepAlive: if set, the client will keep the connection alive but will not send any new request

# To start the client
node low-level-client.js --headerRate 1000 \
  --payloadRate 1000

Cool! Now we can test the timeouts by running a simple command!

Test the `headersTimeout`

Straight to the point: let's test the headersTimeout by sending a request with a very slow header rate.

# Set the header timeout to half a second
node server.js --headersTimeout 500

# Set the header rate to 1 second
node low-level-client.js --headerRate 1000

The expected output is a timeout error, because the server will wait for 500 milliseconds to collect all the headers, but the client will send one header every second.

But, if we run those commands, we will see that the server will not throw any error 😱!

➜ node low-level-client.js --headerRate 1000
Connected to server
Sent Header: Host: localhost
Sent Header: User-Agent: Slow-Client
Sent Header: Accept: application/json
Sent Header: Content-Type: application/json
Sent Header: Content-Length: 83
Sent Header: Connection: keep-alive
Finished sending headers. Now sending body...
{"message":"Hello, this is a slow request!","timestamp":"2025-03-30T14:02:08.156Z"}

Received response: HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
content-length: 17
Date: Sun, 30 Mar 2025 14:02:22 GMT
Connection: keep-alive
Keep-Alive: timeout=72

{"hello":"world"}
Disconnected from server after 14338 ms

The reason is that Node.js does not check the timeouts so frequently. Actually, the default connectionsCheckingInterval configuration is set to 30 seconds, so the server will check the timeouts every 30 seconds.

This makes sense, because checking all the sockets every few milliseconds would be a waste of CPU resources. As always, we developers need to find a balance between performance and security.

So, for the sake of this article, let's set the connectionsCheckingInterval to 100 milliseconds to appreciate the timeouts in real time, or if you would like to see a real Slowloris attack in action, set the headerRate to 60 seconds!

node server.js --headersTimeout 500 \
  --connectionsCheckingInterval 1000

node low-level-client.js --headerRate 2000

Cool! Now we can see the timeout in action:

Connected to server
Sent Header: Host: localhost
Received response: HTTP/1.1 408 Request Timeout
Content-Length: 71
Content-Type: application/json

{"error":"Request Timeout","message":"Client Timeout","statusCode":408}
Disconnected from server after 549 ms

Test result

Now, we can run a lot of tests with different timeouts and payloads to see how the server behaves. Here is a summary of the tests I ran (considering the connectionsCheckingInterval set to 100 milliseconds):

Test	Client args	Server args	Result
Slow Headers	`--headerRate 1000`	`--headersTimeout 500`	Timeout error: because the server will wait for 500ms to receive the headers, but the client will send one header every second.
Slow Payload	`--payloadRate 1000`	`--requestTimeout 5000`	Timeout error: because the server will wait for five seconds to receive the payload, but the client will send one byte every second.
Keep-Alive Connection	`--payloadRate 1 --keepAlive`	`--keepAliveTimeout 4000`	After completing the request, the socker will be ended by the server after four seconds.
Slow Server handler	`--headerRate 1`	`--connectionTimeout 10000 --handlerTimeout 60000`	Timeout error: because the server will wait for ten seconds to process the whole request, but the server handler will take 60 seconds to process the request.

Now we can see that the server is able to handle the timeouts correctly and, the client is able to receive the timeout errors.

Use those scripts to test the timeouts in your own environment and see how they behave.

Summary

In this article, we explored the different timeouts available in Fastify and how to configure them.
We also tested them with a simple Fastify server and a custom socket.
We learned that timeouts are essential for preventing resource exhaustion and ensuring that
the server efficiently handles incoming requests.

Keep in mind that every application is different, but we should never forget to set timeouts!

If you enjoyed this article, you might like "Accelerating Server-Side Development with Fastify".
Comment, share and follow me on X/Twitter!

Managing Request-Scoped Data in Fastify

Manuel Spigolon — Wed, 02 Apr 2025 06:44:06 GMT

I was looking at the Fastify plugin list and found myself asking, "What is this @fastify/request-context plugin?"
So, I checked it out, and here I am, writing a post about it to share what it is and how it can be useful for you!

What is AsyncLocalStorage?

Managing state across asynchronous operations has always been a challenge in Node.js.
Traditional methods like passing context objects through function parameters or using global variables are the easiest way to share data across functions. However, they can quickly become unmanageable, especially in large applications with deeply nested asynchronous calls, making the code difficult to test.

This is where AsyncLocalStorage, a core module introduced in Node.js 13, comes in handy.
It provides a way to store and retrieve data that persists through an asynchronous execution context. Unlike global variables, which are shared across all requests, AsyncLocalStorage allows developers to maintain request-scoped data, meaning each incoming request gets its own isolated storage.

This feature seems to overlap with Fastify's Decorators, but it's not the same. Let's see why!

How It Works

The basic idea behind AsyncLocalStorage is that it creates an execution context that is preserved throughout asynchronous operations, even across setTimeout or database queries.

Here’s a simple example with comments:

import { AsyncLocalStorage } from "async_hooks";

// Create a new instance of AsyncLocalStorage that will be unique per application
const appAsyncLocalStorage = new AsyncLocalStorage();

// Simulate an incoming request every 2 seconds
setInterval(() => {
  // Generate a random request ID that will be unique per request
  const requestId = Math.random().toString(36).substring(7);

  // Run the `reqHandler` function in the AsyncLocalStorage context
  // This creates the context and binds the `store` object to it
  const store = { requestId };
  appAsyncLocalStorage.run(store, function reqHandler() {
    logWithRequestId("Processing request...");
    setTimeout(() => logWithRequestId("Finished processing."), 3_000);
  });
}, 2_000);

// Main business logic function
// Through `appAsyncLocalStorage.getStore()`, we can access the `store` object
// that was bound to the AsyncLocalStorage context in `reqHandler`
function logWithRequestId(message) {
  const store = appAsyncLocalStorage.getStore();
  const requestId = store?.requestId || "unknown";
  console.log(`[Request ${requestId}]: ${message}`);
}

The above code snippet provides the requestId to the logWithRequestId function without passing it as a parameter!
It still requires access to the appAsyncLocalStorage instance to retrieve the store object, but with a single variable, we can access everything we need throughout the request context.

Why Is This Important?

Without AsyncLocalStorage, you would need to manually pass the requestId to every function that requires it, which can be cumbersome and error-prone.
With AsyncLocalStorage, the context is automatically preserved throughout the request lifecycle, making it much easier to track request-specific data.

Think about all the times you've had to pass a logging or config object to every function.
Or when you manually tracked the start and end of a request.
Or even when you implemented a tracing system to follow requests through multiple services.

With AsyncLocalStorage, you can forget about that spaghetti code and focus on the request context's store!

How to Use the `@fastify/request-context` Plugin

Fastify already solves multiple problems with its decorators:

It provides logging through the request.log object.
It provides configuration through the fastify.config object, thanks to the @fastify/env plugin.
It supports Diagnostic Channels to track the request lifecycle.

The @fastify/request-context plugin takes things further by offering a structured way to manage request-scoped data without the hassle of manual context management.

Quick Start

After installing the plugin, you can register it in your Fastify application.
Let’s see a real-world example:

import Fastify from "fastify";
import fastifyRequestContext from "@fastify/request-context";

const app = Fastify({ logger: true });

app.register(fastifyRequestContext, {
  defaultStoreValues() {
    return {
      logicStep: [],
    };
  },
});

app.get("/", async function longHandler(req, reply) {
  const debugBusiness = req.requestContext.get("logicStep");

  // Simulate some business logic
  debugBusiness.push("Called external service 1");
  // Do something...
  debugBusiness.push("Processed external service 2");

  // Simulate an error
  throw new Error("Something went wrong 😱");
});

app.setErrorHandler(function (err, request, reply) {
  const debugBusiness = request.requestContext.get("logicStep");

  this.log.error({ err, debugBusiness }, "An error occurred");
  reply.status(500).send("Internal Server Error");
});

app.inject("/");

In this example, we have a Fastify application with a single route that simulates a complex business logic flow.
Thanks to the @fastify/request-context plugin, we can store the logicStep array in the request context and access it in every part of the application by accessing the request object.

The real power of this plugin is that you can access the logicStep array in the error handler without passing it through function parameters.
This allows you to push trace information across the entire application and log it when an error occurs, helping you understand what happened before the failure.

Manually passing request-specific data through function arguments makes the code messy and difficult to maintain.
With this plugin, you can access context-specific data anywhere in the request lifecycle without modifying function signatures.

`@fastify/request-context` vs Decorators

Why use the @fastify/request-context plugin and AsyncLocalStorage instead of Fastify's Request and Reply decorators?
Aren't they achieving the same goal?

Not exactly.

To understand the difference, let’s briefly look at how Fastify decorators work.
Fastify decorators mutate the Request and Reply prototypes, adding new properties to them.
Every time an HTTP request is received, Fastify creates new Request and Reply objects using these modified prototypes, automatically making decorators available.

Sounds great, right? But there’s a catch!

If you add reference-type objects (arrays or JSON objects) to the Request or Reply object, they will be shared across all requests.
If one request modifies them, it will affect all other requests!
This can lead to unexpected behavior and hard-to-track bugs.

Due to this, the Fastify team discouraged using reference-type objects in decorators starting from v5.

You can still use decorators for reference-type objects, but it becomes more complex and error-prone.
Here’s an example requiring two decorators and a lazy-loading approach:

app.decorateRequest('logicStepValue', null)
app.decorateRequest('logicStep', {
  getter () {
    this.logicStepValue ??= [];
    return this.logicStepValue;
  },
})

This is where the @fastify/request-context plugin shines.
It provides a structured, safe, and isolated way to manage request-specific data without the risk of data leakage across requests!

Summary

The @fastify/request-context plugin offers a structured, efficient way to manage request-scoped data in Fastify applications.
It simplifies code, improves maintainability, enhances logging, and makes debugging significantly easier.

By leveraging this plugin, you ensure that request-specific data remains consistent and accessible throughout the request lifecycle without unnecessary complexity.

If you enjoyed this article, you might like "Accelerating Server-Side Development with Fastify".
Comment, share, and follow me on X/Twitter!

Announcing the Fastify Mini Course

Manuel Spigolon — Sat, 01 Mar 2025 09:02:55 GMT

Dear Backend.cafe readers, I have something special for you! If you've ever wanted to master Fastify, the lightning-fast Node.js framework, you're in for a treat. Today, I’m launching Fastify Mini Course—a free resource designed to help you build high-performance APIs efficiently.

🚀 Why Fastify?

If you're a backend developer, you've probably worked with the http module. But have you considered switching to Fastify? Here’s why you should:

Blazing Fast: Up to 4x faster than the most popular Node.js frameworks.
Low Overhead: Optimized for performance and scalability.
Schema-Based Validation: First-class TypeScript support and JSON schema validation.
Modern Features: Built-in async/await, hooks, decorators, and powerful plugin system.

Whether you're an http pro or new to backend development, this mini-course will help you level up your skills!

📖 What’s Inside the Mini Course?

This course is bite-sized but powerful. You’ll learn:

✅ How to set up a Fastify project from scratch.
✅ Routing, request validation, and response serialization.
✅ Working with middleware, hooks, and decorators.
✅ Optimizing Fastify for production-ready performance.
✅ Real-world best practices.

The course is designed for maximum efficiency, so you can complete it in just a few hours and walk away with practical Fastify skills. You will get one email per day, each containing a short lesson and a hands-on exercise.

🎯 Who Is This For?

Developers who want to learn Fastify from scratch.
Anyone interested in improving API performance and scalability.
Engineers looking for a quick and structured way to learn Fastify.

📅 How to Get Access

It is available publicly at FastifyMiniCourse.com.

🚀 Get Ready to Build Faster APIs!

I can’t wait for you to try it out! If you have any questions or feedback, let’s discuss them in the comments.

Happy coding! 🎯

If you enjoyed this article, comment, share and follow me on X!

Master Node.js with the 5th Edition Cookbook

Manuel Spigolon — Wed, 23 Oct 2024 07:00:09 GMT

We are excited to announce that the Node.js Cookbook, 5th Edition is set to be released on November 15th, 2024!

This latest edition, authored by Bethany Griggs, is the ultimate guide for developers who want to master the Node.js v22 API and build scalable, high-performance applications.

The Node.js Cookbook is a trusted resource for new and experienced developers alike, packed with practical recipes and solutions to common Node.js challenges. Whether you're just starting your Node.js journey or looking to refine your skills, this book covers all the core topics, including asynchronous programming, file handling, HTTP servers, and much more.

As a special contribution, Manuel Spigolon had the pleasure of writing a chapter dedicated to the latest Fastify v5. Fastify is one of the fastest Node.js web frameworks, and in this chapter, you'll learn how to use it to build robust APIs effortlessly.

If you're eager to dive into Node.js or explore Fastify v5, you can preorder the book today at https://packt.link/0mNGV.

Don’t miss it!

How to implement video streaming with Fastify

Manuel Spigolon — Sat, 31 Aug 2024 05:00:10 GMT

In April 2021, I tweeted about a quick experiment where I streamed a large GoPro video using Fastify.

That initial experiment sparked some interest, and just a few months ago, a user reached out with an intriguing question: how could they modify the code to support stream segmentation? Specifically, they wanted users to be able to jump to different parts of the video, effectively allowing timeline scrubbing during playback. I considered this a fascinating challenge and decided to turn it into a blog post.

In this article, we'll explore how to implement video streaming with Fastify, focusing on handling range requests. This will enable smooth playback even with large video files, allowing users to seek through the video timeline effortlessly.

By the end of this post, you'll understand the key concepts behind video streaming in Node.js, how to use Fastify to serve video content efficiently, and how to handle range requests to enhance the user experience with precise control over video playback.

Setting up the project

Before we dive into the code, let's set up our project environment. We'll be using Node.js 20 and Fastify v4 for this tutorial. Additionally, you'll need a large video file to stream — I'll be using a GoPro video I filmed while riding a jet ski with my fiancée 😄

Here's how you can create and set up the project. I've also included some additional plugins we'll need to complete the exercise:

# Create a new directory for the project
mkdir fastify-video-streaming
cd fastify-video-streaming

# Initialize a new Node.js project with ES6 module support
npm init es6 --yes

# Install Fastify and necessary plugins
npm install fastify@4 fastify-range@1

With the project initialised and dependencies installed, we're ready to start building the video streaming server.

Getting ready to stream

With our project set up, it's time to start coding. We'll begin by initialising the Fastify application and setting up a basic route to serve an HTML page containing a video tag. This HTML page will be the frontend interface for our video streaming where users can play and seek through the video content.

First, create a new file named app.js in your project directory. Now, let's write the code to initialise the Fastify server and set up the root route to serve the HTML page:

import Fastify from 'fastify'
import * as fs from 'node:fs'

// Initialize the Fastify application with logging enabled
const app = Fastify({ logger: true })

// Set up a route to serve the HTML page
app.get('/', async () => {
  // Serve the index.html file from the project directory
  return fs.createReadStream('./index.html')
})

// Start the server and listen on port 8080
await app.listen({ port: 8080 })

Next, create an index.html file in the same directory to define the structure of our frontend and add the following basic code:

html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Video Streaming with Fastifytitle>
head>
<body>
    <h1>Fastify Video Streamingh1>
    <video controls width="600">
        <source src="/video-streaming" type="video/mp4">
        Your browser does not support the video tag.
    video>
body>
html>

This simple HTML page includes a video element that will request the video stream from our server via the /video-streaming route, which we'll implement next.

At this point, your Fastify server is set up to serve an HTML page that will act as the frontend for our video streaming application.

By running the node --watch app.js command in your terminal, you can start the server and access the page at http://localhost:8080 in your browser. You should see a basic page with a video player ready to stream content.

Streaming video content

With the basic setup in place, it's time to implement the core functionality of our streaming server: handling video content with support for range requests. This is what allows users to seek through the video timeline, providing a smooth and responsive playback experience.

Understanding range requests

The Range HTTP header is essential for streaming large files like videos. It allows the client (in this case, the browser) to request specific portions of a file rather than downloading the entire file in one go. This functionality is particularly useful for video streaming, as it lets users jump to different parts of the video without having to load the entire file.

The range request feature is defined by RFC 7233. When a browser sends a request for a video, it typically includes a Range header specifying the byte range it wants.

An example of a Range header might look like this:

Range: bytes=0-

The client is asking for the video file starting from byte 0 to the end. If the server supports range requests, it responds with a 206 Partial Content status and includes the requested byte range in the Content-Range header. Here's an example of the response headers:

Content-Range: bytes 0-1000000/2257069623

This header indicates that the server is sending bytes 0 to 1 MB of a total of 2.257.069.623 (>2GB!) bytes in the video file.

Now the browser knows how much of the video it has received, and it can request additional segments as needed without buffering the entire video. So, only when needed, the browser will request the next segment of the video such asking for bytes from 1MB:

Range: bytes=1000001-

Note that the Range header is typically used to request byte-ranges, but it can also be used to implement a pagination-like system where the range is a slice of a list of items — such as a range of users — because the specification allows custom units! This was an interesting topic on StackOverflow, and I am mentioning it because it can be an interesting exercise for the mind to compare and contrast different ideas between developers!

Implementing the `/video-streaming` route

Let’s add the /video-streaming route to our Fastify application to handle these range requests.

First, we must use the fastify-range plugin to easily parse the range header and extract the requested byte range. This plugin will add a request decorator to help us handle the range requests efficiently.

import fastifyRange from 'fastify-range'

// ...
app.register(fastifyRange)
// ...

Now we can focus on the /video-streaming route implementation. Note that the route name was defined in the src attribute of the tag in the index.html file.

app.get('/video-streaming', async (request, reply) => {
  const videoPath = '/path/to/your/video.mp4'
  const videoSize = fs.statSync(videoPath).size

  // Extract the range from the request headers
  const range = request.range(videoSize)
  request.log.info({ range })
  if (!range) {
    // If no valid range is found, throw a 416 error
    // as indicated by the RFC 7233
    const error = new Error('Range Not Satisfiable')
    error.statusCode = 416
    throw error
  }

  // Handle only the first range requested
  const singleRange = range.ranges[0]

  // Define the size of the chunk to send
  const chunkSize = 1 * 1e6 // 1MB
  const { start } = singleRange
  const end = Math.min(start + chunkSize, videoSize - 1)
  const contentLength = end - start + 1

  // Set the appropriate headers for range requests
  reply.headers({
    'Accept-Ranges': 'bytes',
    'Content-Range': `bytes ${start}-${end}/${videoSize}`,
    'Content-Length': contentLength
  })

  // Send a 206 Partial Content status code
  reply.code(206)
  reply.type('video/mp4')

  // Stream the requested chunk of the video file
  return fs.createReadStream(videoPath, { start, end })
})

The code above does the following:

Extracting the range: When the browser requests the video, it sends a Range header indicating the portion of the file it wants to download. We extract this range using the request.range(videoSize) method, which is provided by the fastify-range plugin. Note that we need to know the total size of the video file to validate the range because the browser might request a range that exceeds the file size.
Validating the range: If no valid range is provided or the range is unsatisfiable, the server responds with a 416 Range Not Satisfiable error. This indicates that the server cannot fulfil the request as specified.
Chunk size and byte ranges: We calculate the size of the chunk to send based on the requested range. In this case, we’ve set the chunk size to 1MB and it is up to the server implementation to choose the appropriate size. You may implement a more complex logic to determine the chunk size based on the client's bandwidth or device. The start and end variables define the exact byte range that will be streamed back to the client.
Setting headers: The server responds with a 206 Partial Content status and includes headers like Content-Range and Content-Length to inform the client of the specific byte range being sent.
Streaming the video: Finally, the server streams the requested portion of the video file using fs.createReadStream(videoPath, { start, end }). This allows the video player in the browser to play the video while additional portions are requested as needed.

With this implementation, our Fastify server is now capable of streaming video content efficiently, handling range requests to provide a seamless playback experience for users.

The HTML tag in our index.html file automatically handles range requests when a user interacts with the video's timeline controls. For instance, if a user clicks ahead to a different part of the video, the browser sends a new request with an updated Range header, prompting the server to deliver the corresponding video segment.

This mechanism ensures smooth playback and efficient use of bandwidth, as only the necessary parts of the video are loaded and played.

By implementing this route, we’ve enabled our server to stream large video files efficiently, providing users with the ability to navigate through the video timeline seamlessly.

Conclusion

In this tutorial, we explored how to build a video streaming server using Fastify and Node.js. We implemented a Fastify application capable of serving large video files with support for range requests. This approach allows users to interact with the video timeline, seamlessly streaming only the necessary parts of the video. The source code for this project is available on GitHub.

I want to point out that this implementation is a basic example to get you started with video streaming in Fastify. In a real-world scenario, we should consider additional features like caching, security, and performance optimisations to ensure a robust and reliable video streaming service, but now you have the tools to implement video streaming in your own projects, allowing users to enjoy a smooth and interactive video experience.

If you enjoyed this article, comment, share and follow me on Twitter!

Resume data replication in Postgres and Node.js

Manuel Spigolon — Mon, 22 Jul 2024 05:00:33 GMT

This article is a continuation of Real-time data Replication in Postgres and Node.js. Before reading this article, I recommend you read the previous one because it provides essential context to the points I cover.

In our previous article, we discussed how to replicate data from a Postgres database to a Node.js application in real-time using logical replication. However, if the Node.js application crashes or stops for some reason, the replication will cease, and we risk losing the data that our system produces in the meantime via another microservice or application.

In this article, I discuss how to resume replication from the last point where the Node.js application stopped by using a persistent replication slot in the Postgres database. This ensures that our application doesn't lose events produced by other microservices or applications during downtime.

Creating a replication slot

To resume replication, we need to create a replication slot in the Postgres database. A replication slot is a logical entity that keeps track of changes happening in the database and sends them to the subscriber. The postgres package we used in the previous article automatically created a replication slot for us, but it was not persistent, it was a TEMPORARY replication slot that was removed when the subscriber disconnected.

Since we want to resume replication from the last point where the Node.js application was stopped, we need to create a persistent replication slot. Let's create one in a new setup-replication.js file:

import pg from 'pg'
const { Client } = pg

const client = new Client({ user: 'postgres', password: 'foopsw' })
await client.connect()

await createReplicationSlotIfNotExists('foo_slot')

await client.end()

async function createReplicationSlotIfNotExists (slotName) {
  const slots = await client.query('SELECT * FROM pg_replication_slots WHERE slot_name = $1', [slotName])

  if (!slots.rows.length) {
    const newSlot = await client.query("SELECT * FROM pg_create_logical_replication_slot($1, 'pgoutput')", [slotName])
    console.log('Created replication slot', newSlot.rows[0])
  } else {
    console.log('Slot already exists', slots.rows[0])
  }
}

We are using the pg_replication_slots view to check whether a replication slot with the given name already exists. If it doesn't exist then we create a new replication slot using the pg_create_logical_replication_slot function.

Note that we specified the pgoutput plugin in the function to decode the changes in the replication slot. This is the default plugin for logical replication, and it ships with Postgres. Be aware that there are other plugins, such as:

test_decoding plugin is the simplest plugin that ships with Postgres to start building your own custom plugin.
wal2json, which must be installed separately in the Postgres database, allowing you to use them in the pg_create_logical_replication_slot function.

Note that each plugin has its own advantages and disadvantages, so choose the one that best fits your use case. The biggest difference if you try to use test_decoding versus pgoutput is that the former does not accept a publication name as a parameter while the latter does. This means that you can use pgoutput to filter the changes you want to replicate, while test_decoding will replicate all changes in the database without filtering them!

Now, run the setup-replication.js file to create a replication slot!

Configuring the consumer

In the previous article, we already created the setup-consumer.js that creates the publications that our application is interested in. So, we can reuse the same file and just run it — if we haven't already.

As a reminder: you will first need to start the Postgres server and create the foo database.

Resuming the replication

We are ready to create a new consumer-resume.js file that will resume replication from the last point where the Node.js application was stopped, so let's jump into it:

import { LogicalReplicationService, PgoutputPlugin } from 'pg-logical-replication'

const client = new LogicalReplicationService({
  user: 'postgres',
  password: 'foopsw'
}, { acknowledge: { auto: false } })

client.on('data', async (lsn, log) => {
  if (log.tag === 'insert') {
    console.log(`${lsn}) Received insert: ${log.relation.schema}.${log.relation.name} ${log.new.id}`)
  } else if (log.relation) {
    console.log(`${lsn}) Received log: ${log.relation.schema}.${log.relation.name} ${log.tag}`)
  }

  await client.acknowledge(lsn)
})

const eventDecoder = new PgoutputPlugin({
  // Get a complete list of available options at:
  // https://www.postgresql.org/docs/16/protocol-logical-replication.html
  protoVersion: 4,
  binary: true,
  publicationNames: [
    'foo_odd',
    'foo_update_only'
  ]
})

console.log('Listening for changes...')
process.on('SIGINT', async () => {
  console.log('Stopping client...')
  await client.stop()
})

await client.subscribe(eventDecoder, 'foo_slot')

This time, we are using the pg-logical-replication package to demonstrate the resuming of replication. Its low-level API provides us more control over the replication process, otherwise we would not be able to configure the Plugin to receive only the changes we are interested in.

The code can be explained as follows:

We are creating a new LogicalReplicationService instance and passing the connection options to it. Note that we are setting the acknowledge.auto option to false to manually acknowledge the changes; otherwise, they would be automatically acknowledged. By setting this option to false, we gain even more control over the process.
We are listening to the data event to receive changes from the replication slot.
- At this point, you should process the log and apply your business logic. In this case, we're just logging the changes to the console.
- After processing the changes, you must acknowledge them using the acknowledge method; otherwise, the slot will not advance. The lsn (Log Sequence Number) is the unique identifier for each change in the database and is used to track changes in the replication slot.
We are creating a new PgoutputPlugin instance and passing it to the subscribe method to establish a connection with the replication slot.

To start the application, run the node consumer-resume.js file, and it will begin receiving changes from the replication slot. If we did all the steps correctly, you can start the node producer.js file that we wrote in the previous article to produce changes in the database and see the changes in the consumer application.

If you stop the consumer application by pressing Ctrl+C, the replication will stop, and the slot will not move forward. However, if you start the consumer-resume.js application again, it will resume replication from the last point where it was stopped! 🎉

Moreover, we can see that the output shows only the changes from the foo_odd and foo_update_only publications, which we configured in the PgoutputPlugin instance so we will see updates and inserts with odd id numbers only:

0/15648E0) Received insert: public.foo 18
0/15649A0) Received log: public.foo update
0/1564AF0) Received log: public.foo update
0/1564B80) Received insert: public.foo 20
0/1564C40) Received log: public.foo update
0/1564D90) Received log: public.foo update
0/1564E20) Received insert: public.foo 22
0/1564EE0) Received log: public.foo update
0/1565030) Received log: public.foo update
0/15650C0) Received insert: public.foo 24

Conclusion

In this article, we discussed how to resume replication from the last point where the Node.js application was stopped and all the code is save in this repository.

We created a persistent replication slot in the Postgres database and used the pg-logical-replication package to demonstrate resuming replication. This ensures that our application doesn't lose data produced by other microservices or applications during downtime.

In doing so, we did not change the producer.js file, which means that the producer can continue to produce changes in the database without any issues and the previous Publications setup is still valid: we just configured manually the replication slot and the new consumer.

Remember, the replication slot retains changes in the database until the slot is dropped or the changes are acknowledged by the subscriber. If not managed properly, this can lead to high disk usage because Postgres will keep the changes in the WAL logs indefinitely instead of removing them.

I hope you enjoyed this article and learned something new! Does it deserve a comment and a share? 🚀

Real-time data replication in Postgres and Node.js

Manuel Spigolon — Fri, 24 May 2024 06:50:12 GMT

In today's fast-paced digital landscape, businesses rely heavily on data to drive decision-making processes. Real-time data replication has emerged as a critical capability for organisations seeking to stay ahead of the curve, enabling them to synchronise data across multiple databases seamlessly. To make a few practical examples, real-time data replication is essential for scenarios such as:

Keeping different databases in sync, which is a typical scenario when a company acquires another company and needs to merge the data.
Relying on a database to trigger events in other systems; for example, when a new user is created in the database, a welcome email is sent without modifying existing code or introducing new architecture components like message queues.
Keeping an application's in-memory cache in sync with the database to improve the performance of read queries.
For high availability and disaster recovery scenarios.

As you can see, real-time data replication is a powerful tool that can be used in various scenarios to improve the performance, reliability and scalability of your applications.

In this blog post, we'll explore the power of Postgres replication management, to understand how to do a real-time data replication in Postgres with Node.js.
You will need to run some Docker commands to set up a Postgres instance with logical replication enabled, but it is a copy-paste operation.

Introduction to Postgres replication management

PostgreSQL is a powerful open-source relational database system known for its robust features and extensibility. One of its standout capabilities is replication management, allowing you to replicate data from one database to another in real-time. This feature is invaluable to organisations that require characteristics such as:

High availability: the primary database fails, and a standby server takes over seamlessly.
Load balancing: distributing read queries across multiple replicas to improve performance.
Data distribution: synchronising data across geographically distributed systems.

Postgres offers various mechanisms to support the listed scenarios where each solution has its strengths and use cases. To list a few:

Synchronous multimaster replication: a query must be committed on all nodes before returning to the client. Very high availability and data consistency but with a performance cost.
Write-ahead Log Shipping (WAL): the primary server sends WAL segments to standby servers, which replay them to stay in sync. It's a simple and reliable solution but with a potential for data loss.
Logical Replication: replicates individual changes (inserts, updates, deletes) rather than entire WAL segments. It's suitable for scenarios such as data warehousing, data distribution and selective replication. Moreover, it allows for more granular control over which tables and changes are replicated and it is possible to replicate data between different versions of Postgres or multiple sources!

The complete list of replication mechanisms can be found in the Postgres documentation.

In this blog post, we'll focus on Logical Replication mechanism.

The WAL file

The Write-ahead Log (WAL) is a fundamental concept in Postgres replication and we mentioned it in the previous section. The WAL is a file that stores all changes made to the database, such as inserts, updates and deletes, in a sequential manner. We could say that the WAL is our source of truth, and this file is handled by Postgres to guarantee data consistency and durability in case of a crash or disk failure.

We must discuss the WAL because it is the foundation of Postgres replication. We can configure Postgres to handle the WAL file, and we can use it to replicate data across multiple databases. So we must understand the wal_level configuration parameter. This parameter defines how much information is written to the WAL file. The possible values are:

minimal: only the information needed to recover from a crash is written to the WAL file.
replica: the default value, it writes enough information to support WAL archiving and replication.
logical: it stores the same information as replica and additional information needed for logical replication, so this configuration requires more disk space.

Developing a real-time data replication system with Node.js

To develop a real-time data replication system with Node.js, we must follow these steps:

Initialise the Postgres database.
Create a data producer we want to replicate.
Create a data consumer that replicates the data through the Postgres replication mechanism.

So let's start!

Setting up Postgres

We can start our journey into Postgres replication management by starting a Postgres instance and configuring it to support logical replication. Let's use Docker for this task:

docker run \
  --name demo-postgres \
  -p 5432:5432 \
  -e POSTGRES_PASSWORD=foopsw \
  postgres:16 \
  postgres -c "wal_level=logical"

This command will start a Postgres instance with logical replication enabled, and you can connect to it using the following command:

docker exec -it demo-postgres psql -U postgres

Now, from the Postgres shell, we can create a database and a table to work with:

CREATE TABLE IF NOT EXISTS foo (
  id SERIAL PRIMARY KEY,
  col1 VARCHAR,
  col2 INT
);

To check if the table was created successfully, the following command lists the user's tables in the database:

\dt

Creating a data producer

Now that we have our Postgres instance set up, let's create a Node.js application that acts as a data producer. This application will insert data into the foo table we created earlier and represent the source of data replication. It could be a web application, an IoT device, or any other data source you may have.

Let's create a producer.js file and implement the following logic:

It connects to the Postgres database.
Every second, it inserts a new row into the foo table or updates the last inserted row alternatively.
It listens for a SIGINT signal to gracefully close the connection.

import pg from 'pg' // ℹ️ npm install pg
const { Client } = pg

const client = new Client({
  user: 'postgres',
  password: 'foopsw'
})

await client.connect()

let counter = 0
let lastId = 0
const fakeUserInteraction = setInterval(async () => {
  if (counter % 2 === 0) {
    const res = await client.query('INSERT INTO foo (col1, col2) VALUES ($1, $2) RETURNING id', ['Hello world!', counter])
    lastId = res.rows[0].id
    console.log(`Inserted new row: ${lastId}`)
  } else {
    await client.query('UPDATE foo SET col1 = $1, col2 = $2 WHERE id = $3', ['Hello world!!!', 42, lastId])
    console.log(`Updated row ${lastId}`)
  }

  counter++
}, 1000)

process.on('SIGINT', async () => {
  clearInterval(fakeUserInteraction)
  await client.end()
})

To run this code the node producer.js command is enough.

Creating a data consumer

The data consumer is the other side of the replication process. It can be another Postgres instance, or even a different a different database engine. Postgres allows us to replicate the data seamlessly across different versions of the Postgres database just by configuring them accordingly (not the topic of this blog post, but there are good video tutorials for this use case).

Our use case is to replicate the data to a Node.js application! This application will connect to the Postgres database and listen for changes in the foo table using the logical replication mechanism.

Setting up the data consumer

To set up the data consumer, we must introduce some new Postgres concepts:

Publication: A publication defines a set of tables and changes to be replicated. We must create a publication to specify which tables and changes are replicated.
Subscription: A subscription defines the source of replication (e.g., primary server) and the target replica(s). We must create a subscription to subscribe to changes happening in the foo table.
Replication slot: A replication slot is like a bookmark in the WAL file that keeps track of the last WAL segment read by a client. It forces the primary server to retain the WAL segments required by any client that is using the replication slot.

We need to create all these objects in the Postgres database before we can start listening for changes. Let's do it programmatically with Node.js by creating a setup-consumer.js file:

import pg from 'pg'
const { Client } = pg

const client = new Client({ user: 'postgres', password: 'foopsw' })
await client.connect()

await createPublicationIfNotExists('foo_even', 'TABLE foo WHERE (id % 2 = 0);')
await createPublicationIfNotExists('foo_update_only', "TABLE foo WITH (publish = 'update');")

await client.end()

async function createPublicationIfNotExists (pubName, condition) {
  const pub = await client.query('SELECT * FROM pg_publication WHERE pubname = $1', [pubName])

  if (!pub.rows.length) {
    await client.query(`CREATE PUBLICATION ${pubName} FOR ${condition}`)
    console.log(`Created publication ${pubName}`)
  } else {
    await client.query(`ALTER PUBLICATION ${pubName} SET ${condition}`)
    console.log(`Updated publication ${pubName}`)
  }
}

The code shows how to create and update a publication. When a publication is created, it specifies:

Which tables and columns are included in the replication process?

If no columns are specified, all columns are included.
It is possible to list multiple tables or set FOR ALL TABLES; to include all tables in the replication process.

Which operations are included in the replication process?

The default is to include all operations (inserts, updates, deletes).
It is possible to specify only inserts, only updates, or only deletes.

We have created two publications in the code snippet above:

foo_even: it includes only rows where the id is an even number.
foo_update_only: it includes only updates.

As shown, the publications are very flexible and can be tailored to specific use cases.

Subscribing to changes

Finally, we are ready to create the consumer.js file to listen for changes in the foo table. To do so, we will use the postgres module because it provides a simple way to consume the logical replication data changes or we should implement the logical replication protocol ourselves. Alternatively, you can use the pg-logical-replication library — it depends on your preference.

To create the consumer.js file, we can use the following code snippet. So first we must connect to the Postgres database and list all the publications we want to subscribe to:

import postgres from 'postgres'

const sql = postgres({
  debug: true,
  user: 'postgres',
  password: 'foopsw',
  publications: [
    'foo_even',
    'foo_update_only'
  ]
})

Then we can subscribe to the changes happening in the foo table:

const eventPattern = '*:foo'
const { unsubscribe } = await sql.subscribe(
  eventPattern,
  (row, { command, relation, key, old }) => {
    console.log({
      command,
      row
    })
  },

  function onConnect () {
    // Callback on initial connect and potential reconnects
    console.log('Connected to the publication')
  }
)

process.on('SIGINT', async () => {
  await unsubscribe()
  process.exit()
})

If we run the node consumer.js command, we will see the console.log output every time the producer.js:

Insert a row with an even ID in the foo table.
Update a row in the foo table.

Note that the eventPattern is just a feature of the postgres module that allows us to filter the changes we are getting from the database. The main driver is and will always be the Postgres publication we created earlier with the setup-consumer.js script.

So far we did not create the Replication Slot, but the postgres module will do it for us by calling the CREATE_REPLICATION_SLOT command creating a TEMPORARY slot. Every subscription needs a Replication Slot to track the changes that they are consuming.

Note that the Replication Slot MUST be deleted or consumed by the client, otherwise — if it isn't then the WAL file in the primary server will not be truncated and the disk space will grow indefinitely! Luckily, the postgres module creates a temporary replication slot that is automatically deleted when the connection is closed.

Now our Node.js application is ready to listen for changes in the foo table and replicate them in real-time!

Conclusion

PostgreSQL's replication capabilities are a cornerstone of its reliability and scalability. We just scratched the surface of what is possible with Postgres replication management, but we have seen how to set up a real-time data replication system using Node.js and Postgres logical replication.

Another interesting use case is to use the logical replication mechanism to read all the changes happening in the database while the Node.js application was offline. This is possible by handling the Replication Slot manually and it can be done with the pg-logical-replication module's API, but this will be the topic of another blog post!

We hope this blog post has given you a good starting point to explore Postgres replication management further. Here are some resources to deepen your knowledge:

Comment and share if you enjoyed this article!

Create a Telegram Bot with Fastify from Scratch

Manuel Spigolon — Tue, 31 Oct 2023 07:03:09 GMT

In today's digital landscape, chatbots have become a ubiquitous part of our online interactions. These versatile and intelligent programs help automate tasks, answer queries, and provide a seamless conversational experience.

One popular platform for developing chatbots is Telegram, known for its user-friendly interface and robust features. If you've ever wondered how to create your very own Telegram bot, you're in the right place!

Today, we will build a Telegram bot from the ground up using the Fastify framework. Fastify is a high-performance web framework for Node.js, making it an excellent choice for developing web applications and APIs. By the end of this blog post, you'll have a fully functional Telegram bot!

So, let's dive into the process of creating your own Telegram bot with Fastify!

Setting up the Project

Our journey begins by setting up the foundation for our Telegram bot project. We've chosen to leverage Platformatic, a powerful tool that accelerates project setup, allowing you to hit the ground running. With just a few simple commands, Platformatic creates a complete Fastify application, preconfigured and ready to use, seamlessly connected to the most famous RDBMS Databases (we will use SQLite). This not only saves you time but also provides a solid base for your Telegram bot project.

To get started, run the following command:

npm create -y platformatic@1

You will be prompted with a few questions about your project. Here are the answers we recommend:

 Hello Eomm, welcome to Platformatic 1.2.0!
 Let's start by creating a new project.
? Which kind of project do you want to create? DB
? Where would you like to create your project? my-telegram-bot
? What database do you want to use? SQLite
? Do you want to use the connection string "sqlite://./db.sqlite"? Confirm
? What port do you want to use? 3042
? Do you want to run npm install? yes
? Do you want to create default migrations? yes
? Do you want to apply migrations? yes
? Do you want to create a plugin? yes
? Do you want to use TypeScript? no
? Do you want to create the github action to deploy this application to Platformatic Cloud? yes
? Do you want to enable PR Previews in your application? no

Now, if we move to the my-telegram-bot folder, we can start the server with the following command:

npm start

You can access the application at http://localhost:3042, where you'll find the default Platformatic welcome page.

Exploring the project structure, we can see that Platformatic has created many files and folders for us. Here is the most important ones:

platformatic.db.json: the configuration file of the project. It is the main file that Platformatic uses to understand how to build the project. You will recognize many Fastify's standard options here.
migrations/: the folder that contains the database migrations. The cool thing is that based on the database schema, Platformatic will provide to the application an object to interact with the database!
plugins/: the folder that contains the Fastify plugins. Platformatic will automatically register them for us!
routes/: the folder that contains custom Fastify routes. Platformatic will automatically register them for us!
.env: the file that contains the environment variables. Platformatic will automatically load them for us! (if we name them with the `PLT` prefix)_

I like to say that if you know Fastify, you know Platformatic! Platformatic is "just" Fastify with batteries included! Now that we have a solid foundation for our project, we can start building our Telegram bot!

Implementing the Telegram bot

Our first step on this Telegram bot creation journey involves setting up our bot on the Telegram platform. To achieve this, we'll interact with @BotFather, a official Telegram bot that assists in creating and managing other bots.

Start a chat with @BotFather
Execute the /newbot command
Choose a name for your bot (e.g. My Bot)
Choose a username for your bot (e.g. eommDemoBot)

Once you've completed these steps, you'll have obtained the token for your bot:

Now, integrate this token into your project by adding the following line to the .env file:

PLT_TELEGRAM_BOT_TOKEN=PUT_HERE_YOUR_TOKEN

To simplify the integration, we'll use the @eomm/fastify-telegram package. You can install this package with the following command: npm i @eomm/fastify-telegram.

Next, rename the plugins/example.js file to plugins/telegram.js and add the provided JavaScript code. This code configures the @eomm/fastify-telegram package and sets up your bot to respond to messages:

const fastifyTelegram = require('@eomm/fastify-telegram')

/** @param {import('fastify').FastifyInstance} app */
module.exports = async function telegramBotPlugin (app, opts) {
  await app.register(fastifyTelegram, {
    botToken: app.platformatic.configManager.env.PLT_TELEGRAM_BOT_TOKEN,
    decoratorBotName: 'bot',
    waitForHealthPolling: 2_000,
    onUnhandledError: async (err, ctx) => {
      app.log.error(err, `Ooops, encountered an error for "${ctx.updateType}"`)
      await ctx.reply('🙈 Ooops, something went wrong')
    }
  })

  app.bot.on('text', async (ctx) => {
    await ctx.reply('Hello World!')
  })
}

Let's analyze the code:

We export a standard Fastify plugin. Platformatic will automatically register it for us! Note the JSDOC comment that loads the type definition of the Fastify instance and allows us to use the app object with autocompletion.
We register the fastifyTelegram plugin as a normal Fastify plugin.
We pass the botToken option to the fastifyTelegram plugin using the Platformatic's configManager utility. This option is required and is the token we got from the BotFather.
We pass the decoratorBotName option to customize the name of the decorator that will be injected into the Fastify application.
We pass the onUnhandledError option to the fastifyTelegram plugin. This option is optional and is a function that will be called when an unhandled error occurs on our Bot logic. The plugin will automatically catch the error and call this function to avoid a server crash.
Finally, we register a listener for the text event of the app.bot. This object is a Telegraf bot instance that is automatically injected into the Fastify application by the fastifyTelegram plugin. You can customize the bot by adding listeners to the events you want to handle.

Now we can start the server with npm start and if we open a new chat with our bot, we should see the Hello World! message!

Under the hood, the @eomm/fastify-telegram plugin initiates a long polling process against the Telegram API, waiting for new messages from the Telegram servers.

Registering Users

Now that we have a working Telegram bot, we can start implementing the business logic. Registering users is an essential part of this process. To achieve this, we will use Platformatic's utilities to interact with the database.

You'll need to rewrite the migrations/001.do.sql file with the provided SQL schema. This migration will create a users table, allowing you to store user information:

CREATE TABLE users (
  id TEXT PRIMARY KEY,
  chat_id TEXT UNIQUE NOT NULL,
  full_name TEXT NOT NULL,
  username TEXT NOT NULL,
  lang CHAR(2) NOT NULL DEFAULT 'en',
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

This migration will create a users table automatically for us, just remember to delete the db.sqlite file before starting the server again.

Since the routes/ folder contains the business logic of our application, we can create a new file called routes/telegram-bot.js and add the following code:

/// 
'use strict'

/** @param {import('fastify').FastifyInstance} fastify */
module.exports = async function (app, opts) {
  app.bot.use(async function upsertUser (ctx, next) {
    const userId = ctx.update.message?.from.id || ctx.update.callback_query?.from.id
    const chatId = ctx.update.message?.chat.id || ctx.update.callback_query?.message?.chat.id

    const [user] = await app.platformatic.entities.user.find({
      where: { id: { eq: userId } }
    })

    if (user) {
      ctx.user = user
    } else {
      app.log.info('Creating new user', ctx.update.message.from)

      const fullName = ctx.update.message.from.first_name + (ctx.update.message.from.last_name ? ` ${ctx.update.message.from.last_name}` : '')
      const [newUser] = await app.platformatic.entities.user.insert({
        fields: ['id', 'fullName', 'username', 'lang'],
        inputs: [
          {
            id: userId,
            chatId,
            fullName,
            username: ctx.update.message.from.username || userId,
            lang: ctx.update.message.from.language_code
          }
        ]
      })

      ctx.user = newUser
    }

    return next()
  })

  app.bot.on('text', async (ctx) => {
    await ctx.reply(`Hello ${ctx.user.fullName}!`)
  })
}

Let's analyze the plugin logic:

We don't register any new routes, but we use the app.bot decorator to implement the business logic.
We use the app.bot.use method to register a middleware that will be executed for every message received from Telegram. This middleware will extract the userId and the chatId from the update and will search for the user in the database.
If the user exists, we will set the ctx.user property to the user object, enhancing the Telegraf's ctx object with the user information.
If the user doesn't exist, we will create a new user in the database and set the ctx.user property to the new user object.
Finally, we register another listener for the text event of the app.bot and we use the ctx.user property to customize the reply message.

With this logic in place, you can start the server with npm start. When you open a chat with your bot, you'll receive a personalized Hello {name}! message.

Summary

Congratulations! 🎉 You've just embarked on an exciting journey to create your very own Telegram bot from scratch. In this article, we've harnessed the power of Platformatic to expedite our project setup, establishing a solid foundation for our bot.
We've also delved into the process of generating a basic Telegram bot that responds to user messages and interacts with the database to register users.
Now the possibilities are endless, and your Telegram bot can be customized to suit your unique needs.

I build two complete Telegram bots with Platformatic if you want to see more examples:

telegram-bot-questions: a bot to ask questions to your team mates. It integrates with Google Sheets to store the answers and has a step by step guide to implement the bot.
telegram-bot-give-away: a bot to organize a custom give away.

If you want to learn how to deploy your Telegram bot to the cloud, check out the Platformatic Cloud documentation or leave a comment below and I'll write a new article about it!

The world of chatbot development is at your fingertips, and with each step, you're one step closer to mastering it. Happy coding! 🤖💬

If you enjoyed this article, comment, share and follow me on Twitter!

Fastify has a new Application Hook!

Manuel Spigolon — Mon, 18 Sep 2023 06:50:09 GMT

Fastify v4.23.0 has just been released, featuring a brand-new onListen Application hook. In this article, we'll explore what it is and how you can leverage it in your Fastify applications.

Understanding Fastify hooks

Fastify's hooks are a fundamental aspect of its design. Hooks are functions that get called at specific points in a component's lifecycle. They allow you to inject custom functionality at these crucial moments, thus altering the component's behavior.

Hooks are particularly useful for breaking down your application logic into reusable pieces that can be executed at specific times.

Fastify offers two primary types of hooks:

Application hooks: These consist of 5 hooks that are invoked in a specific order during the application's lifecycle.
Request/Reply hooks: There are a total of 10 hooks that are called in a specific order during the HTTP request lifecycle.

Each hook type serves a distinct purpose and comes with its own API. Before diving into the new onListen hook, let's briefly overview Fastify's hooks.

Application hooks

Application hooks allow you to customize how your Fastify application initializes and closes. These hooks play a crucial role in starting and stopping the application gracefully.

🛫 The application hooks during application startup include:

onRoute: Triggered when a route is registered.
onRegister: Invoked when an encapsulated plugin is registered.
onReady: Called when the application is ready but not yet listening to incoming requests.

If any of these hooks throw an error, the application won't start. These hooks are essential for performing mandatory checks before launching the application, and they execute in the order they are registered.

🛬 The application hooks during application shutdown are:

preClose: Executed before the application is closed, while HTTP requests are still being processed.
onClose: Triggered when the application no longer accepts new requests.

These hooks are handy for performing cleanup tasks before shutting down the application, such as closing a database connection. However, they behave differently when an error is thrown:

preClose hooks are executed in the order they are registered, and if one of them throws an error, subsequent hook functions are not executed. It is likely that you will not use this hook in your application.
onClose hooks are executed in the reverse order they are registered, and if one of them throws an error, the following hook functions are executed regardless.

You can find more details about these hooks in my Fastify book 📙!

The new `onListen` hook

With the release of Fastify v4.23.0, we introduce the sixth application hook: onListen. This hook is called when the application is ready, and the server is actively listening to incoming requests.

The API for the onListen hook is consistent with other application hooks, supporting both async/await and callback styles:

// async/await style
app.addHook('onListen', async function () {
  // Some async code
})

// or callback style
app.addHook('onListen', function (done) {
  // Some code
  const err = null;
  done(err)
})

In the application startup sequence, you can now list this new hook as the final step:

onRoute
onRegister
onReady
⭐️ onListen: Invoked when the application is ready, and the server is actively handling incoming requests.

It's essential to note that this hook has some differences compared to the others of the same type:

If the onListen hook throws an error, the application will still start anyway, similar to the behavior of the onClose hook.
Since the server is already processing HTTP requests, be cautious of potential race conditions if you attempt to load data needed by your routes.
If you don't call app.listen() in your tests, this hook will not be executed.

So, when should you use the onListen hook?

This hook was added in response to community requests to perform tasks that require the server to be actively listening to incoming requests. A common use case is loading external data from a remote service to populate the application cache.

The power of the onListen hook lies in its ability to load data asynchronously without blocking or delaying the application startup. It's perfect for loading non-mandatory data for your routes. If you need to load data that's essential for a decorator and must be available before the application starts, consider using the onReady hook instead.

Request/Reply hooks

While we won't delve into Request/Reply hooks in this article, you can find comprehensive information in the Fastify documentation or in chapter 4 of the detailed Fastify book 📙!

Summary

In this article, we've introduced the new onListen hook, explained how it works and highlighted its use cases. Fastify continues to evolve in response to the community's needs, and this hook is a prime example of that.

If you found this article helpful, please leave a comment, share it with others, and follow me on Twitter for more updates!

Streaming PostgreSQL data with Fastify

Manuel Spigolon — Tue, 22 Aug 2023 07:20:09 GMT

In recent years, we have been surrounded by cool, interactive data visualizations. These visualizations are powered by datasets stored in databases and made available through APIs.

Clients can then query the API and get the data they need to render the visualization.

But what happens when the dataset is enormous? And what if the query to access the data is complex and slow?

You may be used to adding a 'cool' loading animation to your visualization and waiting for the data to be loaded but this is not the best user experience.

So, we will see how to stream a massive amount of data from a PostgreSQL database to a Reactjs client!

Build the dataset

I will go fast here because this is not the main topic of this article, and the code is available on GitHub.

We will create two tables that represent our huge dataset:

Table	Rows	Description
`desks`	200,000	200 thousand desks in a building
`items`	10,000,000	10 million items on the desks

The query we are going to analyze is the following:

  WITH start_time AS (SELECT pg_sleep(1) AS start_time)
  SELECT items.id, desks.name, row_number() OVER (ORDER BY items.id) AS row_number
  FROM items
  INNER JOIN desks ON desks.id = items.desk_id
  CROSS JOIN start_time

It reads all the items and the desks they are on and returns the result with a row number.

Since the query is not too slow, we need to slow it down to simulate a real-world scenario with multiple joins and aggregations. The pg_sleep(1) forces PostgreSQL to wait for 1 second before returning the result.

Now we can start the PostgreSQL server with a quick Docker command:

docker run --rm -p 5432:5432 --name fastify-postgres -e POSTGRES_PASSWORD=postgres -d postgres:15-alpine

Finally, we can seed the database with the tables and the data with the node seed.js script on GitHub. It will take a few minutes to complete, but we will have a huge dataset to play with at the end!

Build the API

We are going to use Fastify to build the API, it has everything we need to build a fast and scalable API in no time 🎉.

But, before writing the code, we need to think about the API we want to build. Since we want to return a huge amount of data, we can't run the query and return the result in one shot: whatever server we use, it will run out of memory!

So we need to stream the result of the query to the client by using different techniques:

Batching: we can run the query in batches and return the result in chunks.
Streaming: we can stream the result of the query to the client as soon as we get the data.

The Batching approach can be implemented using the SQL language's LIMIT and OFFSET clauses. So we don't need any external library to implement it.

The Streaming approach is more complex, but it is more efficient and allows us to return the data as soon as we get it. A quick Google search will show you that a few libraries can help us with this task:

Both libraries are great, but the pg-query-stream has a better API, so we will use it.

Note
I tested both pg- libraries before noticing that pg-query-stream uses pg-cursor under the hood 😅 The performance of the two libraries is the same, so we will discuss pg-query-stream only.

Now that we know what to do, we can start writing the code!

Project setup

We will create a quick project setup. It is important to note that the code is not optimized for production use. This is to keep it as simple as possible.

If you want to learn more about Fastify, you may find the Fastify book helpful!

So, let's start creating a new project from scratch with the following commands:

# Create the project
mkdir fastify-postgres-high-volume
cd fastify-postgres-high-volume
npm init -y

# Install Fastify
npm install fastify @fastify/postgres

# Install the PostgreSQL driver and utilities
npm install pg pg-query-stream JSONStream

Create the app.js file with the following content:

const fs = require('fs').promises

// Create the Fastify server
const app = require('fastify')({ logger: true })

// A simple route to serve the Reactjs application
app.get('/', async function serveUi (request, reply) {
  reply.type('text/html')
  return fs.readFile('./index.html')
})

// Register the PostgreSQL plugin to connect to the database
app.register(require('@fastify/postgres'), {
  host: 'localhost',
  port: 5432,
  database: 'postgres',
  user: 'postgres',
  password: 'postgres',
  max: 20
})

// Register some plugins to implement the API - we will see them later
app.register(require('./lib/batch'))
app.register(require('./lib/stream'))

// Start the server
app.listen({ port: 8080, host: '0.0.0.0' })

It is time to scaffold the lib/batch.js plugin:

module.exports = async function (app, opts) {
  app.get('/api/batch', queryBatch)
}

async function queryBatch (request, reply) {
  const notImplemented = new Error('Not implemented')
  notImplemented.statusCode = 501
  throw notImplemented
}

Let's scaffold the lib/stream.js plugin too:

module.exports = async function (app, opts) {
  app.get('/api/stream', queryStream)
}

async function queryStream (request, reply) {
  const notImplemented = new Error('Not implemented')
  notImplemented.statusCode = 501
  throw notImplemented
}

We are going to implement the two plugins in the next sections.

The last thing we need to do is to create the index.html file that will be served by the server. I have created a simple Reactjs application in a single HTML file. You can find it on GitHub. The code is not important for this article, so I will not discuss it here; moreover, we need the API to be up and running to test the client, so we will explore it later.

At this point, we can start the server with the following command:

node app.js

💡 Node.js Tip
If you are running Node.js 20 or newer, you can use the node --watch app.js flag to reload the server when the code changes! It doesn't require any external library and is very useful during development.

Once the server is up and running, we can open the browser and navigate to http://localhost:8080 and we should see the index.html application!

We can now implement the API's business logic!

Implementing the Batching approach

The Batching approach is the most common one to implement since it is used broadly in the industry to paginate the results of a query. The idea is to run the query in batches and return the data chunks, so we need two inputs from the client:

limit: the number of rows to return in each chunk.
offset: the number of rows to skip before returning the batch result.

We can get these two values in the request.query object by adding a JSON schema to the route that validates the input:

app.get('/api/batch', {
  schema: {
    query: {
      type: 'object',
      properties: {
        offset: { type: 'number', default: 0 },
        limit: { type: 'number', default: 50_000 }
      }
    }
  }
}, queryBatch)

The queryBatch implementation will look like this:

async function queryBatch (request, reply) {
  // Get the input from the client
  const offset = request.query.offset
  const batchSize = request.query.limit

  // The slow query we want to run
  const slowQuery = `
    WITH start_time AS (SELECT pg_sleep(1) AS start_time)
    SELECT items.id, desks.name, row_number() OVER (ORDER BY items.id) AS row_number
    FROM items
    INNER JOIN desks ON desks.id = items.desk_id
    CROSS JOIN start_time

    OFFSET $1
    LIMIT $2;
  `

  // Run the query and return the result
  const result = await this.pg.query(slowQuery, [offset, batchSize])
  return result.rows
}

When the client calls the /api/batch route, the server will run the slowQuery and return the result.

The this.pg object is an Application Decorator injected by the @fastify/postgres plugin, and it is a PostgreSQL pool!

We can now test the API by running the following command:

curl http://localhost:8080/api/batch?offset=0&limit=10000

The server should return the first 10,000 rows of the result of the slowQuery! Note that the response will pop up in the terminal after 1 second at the latest 🐌.

Implementing the Streaming approach

The Streaming approach could be more complex to implement. However, thanks to the pg-query-stream library, it is not ✨.

The idea is to stream the result of the query to the client as soon as we get the data. So we need to create a stream that reads the result of the query and pipe it to the client. The input we need from the client is the limit only because we are going to stream the result and don't need to skip anything.

We can read the limit input from the request.query object by adding a JSON schema to the route that validates the input:

app.get('/api/stream', {
  schema: {
    query: {
      type: 'object',
      properties: {
        limit: { type: 'number', default: 50_000 }
      }
    }
  }
}, queryStream)

Now we can implement the queryStream function:

const QueryStream = require('pg-query-stream')
const JSONStream = require('JSONStream')

async function queryStream (request, reply) {
  // Get the PostgreSQL client from the pool
  const client = await this.pg.connect()

  // The slow query we want to run
  const slowQuery = `
    WITH start_time AS (SELECT pg_sleep(1) AS start_time)
    SELECT items.id, desks.name, row_number() OVER (ORDER BY items.id) AS row_number
    FROM items
    INNER JOIN desks ON desks.id = items.desk_id
    CROSS JOIN start_time

    LIMIT $1;
  `

  // Create a new stream that runs the query
  const query = new QueryStream(slowQuery, [request.query.limit], {
    highWaterMark: 500
  })

  // Run the query and return the stream
  const stream = client.query(query)
  stream.on('end', () => { client.release() })
  return stream.pipe(JSONStream.stringify())
}

Let's analyze the code:

We create a new PostgreSQL client by calling this.pg.connect() that returns an available client from the pool.
We create a new QueryStream that will run the same slowQuery as the batch implementation except for the OFFSET clause:
- It is important to note that we need to set the highWaterMark option to read a good amount of rows from the database. The default value is 16, which is too low for our use case!
We create a new stream by calling client.query(query) that will execute the query.
We must remember to listen for the end event of the stream to release the client back to the pool.
We return the stream piped to a JSONStream that will convert the result to a JSON string. Fastify will automatically manage the stream and send the result to the client!

We can now test the API by running the following command:

curl http://localhost:8080/api/stream?limit=10000

The server should return the first 10,000 rows of the result of the slowQuery!

You should see the result being streamed to the terminal as soon as the server gets the data from the database! There is no delay between the rows, so the client can start to render the data as soon as it gets it! The pop-up effect is gone! 🚀

Build the client

Now that we have the API up and running, we can build the client to test the API and see the effect of the two approaches. Since I like minimalism 🤣 and don't want to spend too much time on the client, I will use the Reactjs application I have created before.

It is a simple application with the following features:

An input to set globally for the application how many rows we must fetch from the API calls.
A button to call the /api/batch route and show the time it takes to get the result.
- An input to set the maximum number of rows to get for each batch: we can't get all the rows in one shot, or the server will run out of memory!
A button to call the /api/stream route and show the time it takes to get the result.

Here is a screenshot of the application:

Now, let's press the buttons and see what happens!

Results

If we press the buttons with the default values, we will get the following results:

It must be noted that the results include the time it takes to parse the data in the browser.

Before analyzing the results, let's try to play with the inputs to see how the results change.

What happens if we increase the batch size to 350,000?

The batch approach is much faster than before, and it beats the streaming method!

Let's analyze the results:

Total Rows	Batch Size	Batch Result Time (sec)	Stream Result Time (sec)	Number of Batches
500,000	50,000	~14	~7 🥇	10
500,000	350,000	~5 🥇	~7	2
1,000,000	350,000	~8 🥇	~15	3
3,000,000	350,000	~30 🥈	~30 🥈	9
3,500,000	350,000	~36	~34 🥇	10
5,000,000	350,000	~63	~53 🥇	15

Each test result is the best of 3 tests after refreshing the web page and clearing the cache. The Fastify server runs locally on a MacBook Pro 2019 and is never restarted during the tests.

The results are exciting! The streaming approach is faster than the batch approach when the number of batches (calculated by totalRows / batchSize) is higher or equal to 10.

Is this a general rule? Let's answer this question by doing some investigating!

Watch this video taken from the Chrome DevTools's Network tab about the 2nd test result:

We can see that the batch approach makes two requests to the server, while the streaming approach makes only one request. But the Content Download time is much higher for the streaming approach.

Could we improve it? Yes, of course!! Let's try to increase the highWaterMark option of the QueryStream to 5MB!

const query = new QueryStream(slowQuery, [request.query.limit], {
  highWaterMark: 5e6
})

Let's rerun the tests, and you should see that the total time takes ~4/5 seconds for the streaming approach (body parsing included)! The Content Download time is now ~2 seconds, so by increasing the highWaterMark, we speed up the download of the data x2!

Now, if we rerun the 3rd test with the new highWaterMark, the streaming approach ends in ~10 seconds, so we cut down the time by 1/3!

This means that the 10 batches rule is not a general rule to defeat the streaming approach, but it depends on how we configure our stream.

So the speed relation of the two approaches is the following:

Batching: If we have a small number of batches, the batch approach is faster to implement and run. But we can't increase the batch size too much to reduce the number of batches. The 350,000 rows batch size fetched ~30 MB of data; that's way too much for a single set but was helpful for our understanding.
Streaming: It is not always the fastest approach if we don't configure the stream properly. However, it is the most efficient approach because it doesn't require loading all the data in memory before sending it to the client. Moreover, it is the more stable approach in the long run because it doesn't require changing the batch size when the dataset grows, and it lets us build more responsive UI applications.

Summary

In this article, we have seen how to stream a massive amount of data from a PostgreSQL database to a Reactjs client! We explored two different approaches, and we have seen how to implement them with Fastify and the pg-query-stream library.

The performance of the two approaches has been compared, and we have seen that the streaming approach is the most efficient and stable in the long run — even if it is not always the fastest.

We analyzed the results and found a relation between each approach and its performance. Now you can choose the best approach for your use case by knowing the pros and cons of each approach!

If you enjoyed this article, comment, share and follow me on Twitter!

The Fastify book is out!

Maksim Sinik — Sun, 30 Jul 2023 14:42:45 GMT

Are you a mid/expert back-end engineer looking to build highly scalable and maintainable API servers? Are you already familiar with Node.js and other back-end frameworks? If so, then "Accelerating Server-Side Development with Fastify" is the book you've been waiting for!

About the Authors: Meet the team behind this comprehensive guide - Manuel Spigolon, a Senior Backend Developer at NeaForm, with expertise in Backend Software Development for IT Services; Maksim Sinik, a Senior Engineering Manager at TrustLayer Inc. in the Insurtech, Healthcare, and Logistics industries, specializing in Node.js Backend Scalability; and Matteo Collina, Co-Founder & CTO of Platformatic, a renowned Open Source author and core maintainer of Fastify.

Who is this Book For? This book targets mid/expert back-end engineers with prior experience in Node.js and other back-end frameworks. It assumes you are familiar with JavaScript and HTTP protocol but are looking to understand the unique selling points of Fastify. Whether you are developing a monolithic application or planning to transition to microservices, this guide will show you how to leverage Fastify's features for optimal results.

Why Choose "Accelerating Server-Side Development with Fastify"? While there are other books on Fastify, they often touch on various aspects of development without diving deep into creating scalable and maintainable applications. This book focuses solely on Fastify and delves into its core logic and features, helping you avoid common pitfalls and build highly responsive applications.

Learning Outcomes Throughout this book, you'll learn the following essential skills:

Understand encapsulation techniques implemented by Fastify.
Become proficient in using Fastify's unique features compared to other frameworks.
Learn to organize project structures and implement architectures for transitioning to microservices.
Develop a real-world project to put theory into practice.
Deploy, monitor, and handle errors in a running Fastify instance effectively.

Book Structure The book is divided into three parts, each addressing different aspects of Fastify development:

Part One: Fastify Basics

What is Fastify?
The Plugin System and the Boot Process
Working with Routes
Exploring Hooks
Exploring Validation and Serialization

Part Two: Building a Real-World Project

Project Structure and Configuration Management
Building a RESTful API
Authentication, Authorization, and Files Handling
Application Testing
Deployment and Process Monitoring for a Healthy Application
Meaningful Application Logging

Part Three: Advanced Topics

From a Monolith to Microservices
Performance Assessment and Improvement
Developing a GraphQL API
Type-Safe Fastify

If you're ready to accelerate your server-side development with Fastify, this comprehensive guide is a must-have for your toolkit!

For more updates and technical discussions, follow the authors on Twitter:

Maksim Sinik: @maksimsinik
Manuel Spigolon: @manueomm
Matteo Collina: @matteocollina

Or subscribe to this blog!

Get your copy of "Accelerating Server-Side Development with Fastify" today and embark on a journey towards building scalable and maintainable backend applications!

Validate the Fastify input with Joi

Manuel Spigolon — Mon, 10 Jul 2023 06:54:39 GMT

If you are an hapi developer, you may know the joi library. It is a powerful validation library that allows you to define programmatic schemas for your data and validate them with ease.

One of the hardest things about migrating from hapi to fastify is the complexity that’s involved for you to be able to keep using joi for the route's input validation.

But now, thanks to the joi-compiler library, you can use joi with fastify without any problem!

Note If you have been afraid to use it because it has very few downloads, don't worry — it is a new library and I'm the author. And, if you don't know me, I'm a Fastify core maintainer and I'm the co-author of the Fastify book too!

The joi-compiler module replaces the default ajv schema compiler with a joi-based one and allows you to use joi schemas to validate your data. Let's see how to use it!

Integrate `joi` with `fastify`

After you have installed the latest fastify@4 and joi-compiler module:

mkdir fastify-joi
cd fastify-joi
npm init -y
npm install --save fastify@4 joi-compiler

We can create a simple index.js file with the following content:

const fastify = require('fastify')
const JoiCompiler = require('joi-compiler')

// Instantiate the compiler
const joiCompilerInstance = JoiCompiler()

// Install it to Fastify
const app = fastify({
  schemaController: {
    bucket: joiCompilerInstance.bucket,
    compilersFactory: {
      buildValidator: joiCompilerInstance.buildValidator
    }
  }
})

// Use it!
const joiSchema = joiCompilerInstance.joi.object({
  foo: joiCompilerInstance.joi.string().required()
})

app.get('/', {
  handler: () => 'Hello World!',
  schema: {
    headers: joiSchema
  }
})

app.listen({ port: 3000 })

If you run this code, you will be able to test the joi validation with the following command:

curl -X GET http://localhost:3000/
# {"statusCode":400,"error":"Bad Request","message":"\"foo\" is required"}

curl -X GET http://localhost:3000/ -H "foo: bar"
# Hello World!

As you can see, the joi schema is working as expected! In a few lines of code, we have integrated joi with fastify and we are able to use it to validate the input of your application routes.

How it works

The joi-compiler module is a Fastify schema compiler, it is used by Fastify to build the components during the startup to guarantee the encapsulated feature.

For this reason, the joi-compiler can be configured in the schemaController option during the Fastify application creation.

Note
How the Fastify Schema Controller works is out of the scope of this article. But if you want to know more about it, you can read the Fastify book!

How to configure the `joi-compiler`

The JoiCompiler accepts an optional configuration object to customize the joi instance.

The default configuration is:

const joiCompilerInstance = JoiCompiler({
  // optionally: provide all the JOI options you need
  // Here is all the possible options: https://joi.dev/api/?v=17.9.1#anyvalidatevalue-options
  prefs: {
    stripUnknown: true
  },

  // optionally: an array with custom JOI extensions such as `@joi/date`
  extensions: [
  ],

  // optionally: if you want to use the async validation. Default: false
  asyncValidation: false
})

When you instantiate the joiCompilerInstance, the returned object has the following properties:

buildValidator: The function to pass to the schemaController option of Fastify.
bucket: The joi bucket that contains the schemas when you call the app.addSchema(joiSchema) method. You can omit this option if you don't use app.addSchema.
joi: A customized joi instance that contains the installed extensions, if there are any. It is a good practice to use this instance to build your schemas.

How to use `ajv` and `joi` together!

The power of Fastify is that you can use different schema compilers at the same time! Here is an example of how you can learn from the Fastify book:

const joiCompilerInstance = JoiCompiler()
const app = fastify()

app.post('/ajv', {
  handler: (request) => request.body,
  schema: {
    body: {
      type: 'object',
      properties: {
        toX: { const: 42 },
        toY: { const: 50 }
      }
    }
  }
})

app.register(async function pluginJoi (app, opts) {
  // Install the joi compiler into this encapsulated context!
  app.setSchemaController({
    bucket: joiCompilerInstance.bucket,
    compilersFactory: {
      buildValidator: joiCompilerInstance.buildValidator
    }
  })

  // Let's try to use the external schemas!
  app.addSchema({ $id: 'x', $value: 42 })
  app.addSchema({ $id: 'y', $value: 50 })

  app.post('/joi', {
    handler: (request) => request.body,
    schema: {
      body: Joi.object({
        toX: Joi.ref('$x'),
        toY: Joi.ref('$y')
      })
    }
  })
})

app.listen({ port: 3000 })

If you run this code, you will be able to use the ajv and joi validation in the same application! The ajv validation will be used for the /ajv route and the joi validation will be used for the /joi route.

Pretty cool, right?

Summary

The joi-compiler is a powerful tool that allows you to build and manage joi instances for Fastify out of the box in a few lines of code. If you're a joi user, joi-compiler is definitely worth checking out!

If you enjoyed this article comment, please share and follow @ManuEomm on Twitter!

Unlock the Power of Runtime Log Level Control

Manuel Spigolon — Sun, 04 Jun 2023 07:30:39 GMT

As a backend developer, logging is essential to monitoring and debugging applications. Traditionally, changing an application's log level required restarting it or modifying the configuration and redeploying it.

However, there are scenarios where changing the log level at runtime becomes necessary to monitor and troubleshoot applications efficiently. This article introduces the new fastify-log-controller plugin that enables changing the log level of your application at runtime without the need for restarts or resetting the in-memory state!

The wrong log level

Fastify is awesome, and it provides a lot of logging features out of the box:

One log level for the entire application
One log level for each encapsulated context
One log level for each route

This means that you can write this code to customize the log level of your application:

const fastify = require('fastify')({
  logger: {
    level: 'error', // 🔵 application log level
  },
})
fastify.register(somePlugin, {
  logLevel: 'info', // 🔵 encapsulated context log level
})
fastify.get('/some-route', {
  logLevel: 'debug', // 🔵 route log level
  handler: async () => {
    return { hello: 'world' }
  }
})

This feature is useful when you want to reduce the noise of the logs or increase the verbosity of a specific context or route. Although this feature is powerful, changing it at runtime by default is impossible.
So, if you don't implement a custom solution, you can't adapt to changing debugging or monitoring requirements without restarting the application! And in the worst case, you may need to redeploy the application if the log level is defined in the configuration file!

Sometimes, you may need to increase the log level to get more detailed logs for specific contexts or decrease it to reduce the noise. Having the ability to modify the log level dynamically can significantly enhance your application's debugging and monitoring capabilities, helping your support team troubleshoot issues faster 🚀!

How to change the log level at runtime

The fastify-log-controller plugin provides a simple and elegant solution to the problem of changing log levels at runtime.
By registering this plugin in your Fastify application, it automatically adds a new route at POST /log-level (configurable) that allows you to control the log levels for different encapsulated contexts!

To use this plugin, you need to follow these steps:

Install the plugin and register it in your Fastify application
Assign a unique name to each encapsulated context or route
Call the POST /log-level route to change the log level of a specific unique name

Here is the first step:

npm install fastify fastify-log-controller

Create a new file, example.js, and add the following scaffold:

async function example () {
  const app = require('fastify')({
    disableRequestLogging: true, // Disable the default request logging to reduce the noise
    logger: {
      level: 'error'
    }
  })
  // Register the plugin
  app.register(require('fastify-log-controller'))
  // 📝 ... Define your routes and encapsulated contexts ... 📝
  // Check that the route logs the `hello world` message!
  await app.listen({ port: 3000 })
}
example()

Now let's see how to change the log level of a specific encapsulated context.

Customize the log level of an encapsulated context

To customize the log level of an encapsulated context, you need to assign a unique name to it. So, modify the example.js file as follows:

  // .. app.register(require('fastify-log-controller'))
  const pluginFn = async function plugin (app, opts) {
    app.get('/', async function handler (request, reply) {
      request.log.info('info message')
      return { hello: 'world' }
    })
  }
  const pluginOpts = {
    logCtrl: { name: 'bar' } // ❗️ Set a unique name for the encapsulated context
  }
  // Create an encapsulated context with register and set the `logCtrl` option
  app.register(pluginFn, pluginOpts)
  // ... await app.listen({ port: 3000 })

Now, if you run the application with node example.js, you shouldn't see any log message in the console. Even if you call the / route, the log level is set to error, and the info message is not logged.

To change the log level of the bar encapsulated context, you need to call the POST /log-level route with the following payload:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"level": "debug", "contextName": "bar"}' \
  http://localhost:3000/log-level

Now, if you call the / route, you should see the info message in the console! Since the log level of the bar encapsulated context is set to debug, the info message is logged.

Note
Changing the log level of an encapsulated context will change the log level of all the routes registered in it!

Customize the log level of a route

To customize the log level of a route, you need to do the same thing as for the encapsulated context. In this case, you will need to wrap the route with the register method and set the logCtrl option as before.

So, modify the example.js file as follows:

  // .. app.register(require('fastify-log-controller'))
  const pluginFn = async function plugin (app, opts) {
    app.get('/', async function handler (request, reply) {
      request.log.info('info message')
      return { hello: 'world' }
    })
    // Wrap the route with register and set the `logCtrl` option as before
    app.register(async function subPlugin (app) {
      app.get('/route', {
        handler: (request, reply) => {
          request.log.info('info message')
          return {}
        }
      })
    }, { logCtrl: { name: 'foo' } })
  }
  // ... const pluginOpts = {

Now, if you run the application with node example.js, you shouldn't see any log message in the console. Even if you call the /route URL, the log level is set to error, and the info message is not logged.

To change the log level of the /route route, you need to call the POST /log-level route with the following payload:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"level": "debug", "contextName": "foo"}' \
  http://localhost:3000/log-level

Now, if you call the /route route, you should see the info message in the console and the bar encapsulated context is untouched!

Note
If you want more features, like changing the log level of the entire application, you can open a feature request!

Plugin options

The fastify-log-controller plugin accepts the following options:

optionKey: string (default: logCtrl).
The property name used to set the log level of an encapsulated context or route.
routeConfig: object (default: {}). The object can contain the Fastify route configuration. The configuration of the POST /log-level route. You can't change only the handler and schema properties, so you will be able to add an authentication strategy.

Summary

In this article, you have found a convenient solution to the problem of changing log levels at runtime in a Fastify application. By registering this plugin, you can dynamically control the log levels for different encapsulated contexts without needing application restarts or resetting the in-memory state.

This plugin introduces a new route at /log-level, allowing you to send a POST request to modify the log level for a specific encapsulated context. With the ability to adjust log levels at runtime, you can fine-tune your logging strategy, enabling more detailed logs for debugging or reducing noise in production environments.

If you want to go deeper into the encapsulated context concept, check out these sources:

If you enjoyed this article, comment, share and follow me on Twitter!

Official Release Date of 'Accelerating Server-Side Development with Fastify' Book

Manuel Spigolon — Mon, 22 May 2023 06:56:39 GMT

Me (Manuel Spigolon), Maksim Sinik and Matteo Collina are thrilled to share some exciting news with the Fastify community! After two years of hard work and dedication, we are delighted to announce the official release date of our book!

'Accelerating Server-Side Development with Fastify' will be released on 9th June 2023! 🗓️

This book aims to be the definitive resource for developers looking to harness the full potential of Fastify, a lightning-fast web framework for Node.js.

Build high-performance web applications with ease

'Accelerating Server-Side Development with Fastify' covers many topics. These include Fastify's core concepts, routing, plugins, testing, and deployment strategies. Whether you are a seasoned developer or just starting your journey with Fastify, this book will empower you to build high-performance web applications with ease.

What’s inside 'Accelerating Server-Side Development with Fastify':

Gain a deep understanding of Fastify's architecture and how it differs from other Node.js frameworks
Explore various routing techniques and advanced features to build robust APIs and microservices
Learn how to leverage Fastify's plugin system to enhance functionality and streamline development
Discover best practices for testing Fastify applications, ensuring code quality and reliability
Master deployment strategies, including containerization and serverless deployment options

Chapter list

Here is a list of the chapters included in the book:

Part 1: Fastify Basics

Chapter 1: What Is Fastify?
Chapter 2: The Plugin System and the Boot Process
Chapter 3: Working with Routes
Chapter 4: Exploring Hooks
Chapter 5: Exploring Validation and Serialization

Part 2: Build a Real-World Project

Chapter 6: Project Structure and Configuration Management
Chapter 7: Building a RESTful API
Chapter 8: Authentication and File Handling
Chapter 9: Application Testing
Chapter 10: Deployment and Process Monitoring for a Healthy Application
Chapter 11: Meaningful Application Logging

Part 3: Advanced Topics

Chapter 12: From a Monolith to Microservices
Chapter 13: Performance Assessment and Improvement
Chapter 14: Developing a GraphQL API
Chapter 15: Type-Safe Fastify

We hope you will find all the content helpful and that it will help you become a Fastify expert!

Pre-order your copy today!

Pre-order your copy today using the link below and start your journey to becoming a Fastify expert!

📖 Pre-order the 'Accelerating Server-Side Development with Fastify' book 📘

We hope it will serve as a valuable resource for the Fastify community.
We look forward to hearing your feedback on the book!

Acknowledgments

First and foremost, I would like to express our gratitude to the editor at Packt, whose guidance and support were instrumental in shaping this book. Their expertise and invaluable feedback helped us refine our ideas, ensuring that the content delivered met the highest standards. I noticed how much I improved as a writer during the writing process.

I would also like to extend my sincere thanks to Maksim and Matteo. Collaborating with such incredible individuals made the process enjoyable and enriched the book's overall quality. Their insights, technical prowess, and dedication to Fastify made a difference. Working on this project has been an honour.

Thank you, Manuel

If you enjoyed this article and that you’ll like 'Accelerating Server-Side Development with Fastify'. Comment, share and follow me on Twitter!

How to handle emojis in Nodejs

Manuel Spigolon — Tue, 09 May 2023 06:50:39 GMT

Every time I have to deal with emojis in Node.js, I have to google the same things over and over again. So I decided to write this post to have a reference for myself and you, dear reader.

If you know precisely why '😊'.length equals 2, you can skip this post; otherwise, let's see it together.

What is an emoji?

An emoji is a pictogram, and they surround us in our daily life 🧐 But what is an emoji from a technical point of view?

It is a Unicode character, and Unicode is a standard that defines a unique code point number for every character, letter, symbol, emoji, etc. in the world. A code point is a number that uniquely identifies a character, and it is represented in hexadecimal format: U+.

Let's see some examples:

Character	Code points
A	`U+0041`
😊	`U+1F60A`
🤌🏼	`U+1F90C` `U+1F3FC`
👨‍👧‍👦	`U+1F468` `U+200D` `U+1F467` `U+200D` `U+1F466`

As you can see, the character A and the 😊 emoji are represented by a single code point, while 🤌🏼 and 👨‍👧‍👦 has multiple code points, contrary to what I said in the introduction 😱!

This is because some characters are special abstract symbols used to combine other characters to form a single one or change their properties.

In this case, we can have two types of characters:

Character modifiers: a special character modifies one near character. This is the case of the 🤌🏼 emoji, which is the combination of the 🤌(U+1F90C) character and the 🏼(U+1F3FC) character.
Combining characters: a character that combines with other characters to form a single one or change its properties. This is the case of the 👨‍👧‍👦 emoji, which is the combination of:
- 👨(U+1F468)
- plus the ZWJ (U+200D) + 👧(U+1F467)
- plus the ZWJ (U+200D) + 👦(U+1F466)

Let's see them in detail.

Character modifiers

The Unicode standard defines a set of abstract characters that can be combined with other characters to change the appearance of another character or its phonetic transpilation.

An example is to change the emoji color by adding a modifier next to the emoji itself.
The colors are represented by five Fitzpatrick modifiers:

Modifier	Code point
🏼	`U+1F3FB`
🏼	`U+1F3FC`
🏽	`U+1F3FD`
🏾	`U+1F3FE`
🏿	`U+1F3FF`

So, if you print the 🤌 + 🏿, every Unicode viewer will render the 🤌🏾 emoji.

Combining characters

A combining character changes the character immediately before it by creating a new character.

This technique can be used to represent accents, diacritics, etc. An example is the ñ character, which is the combination of the n(U+006E) character and the ◌̃(U+0303) character or the Japanese ぴ character which is ひ(U+3072) and ゚(U+309A).

A special mention goes to the ZWJ (U+200D) zero-width joiner character, which is non-printable and is used to merge two or more characters into a single one. It is the case of the 👨‍👧‍👦 emoji, which is the combination of: 👨(U+1F468) + 👧(U+1F467) + 👦(U+1F466) as we read earlier. Every char depends on the previous one.

Note that the ZWJ character is not the only one used to combine emojis, but it is the most common one for Arabic or Indic scripts such as سلامU+200Dعلیکم will be shown as سلام‌علیکم in a browser.

We did a long introduction about Unicode. Nevertheless, we just scratched the surface of the standard, which is very complex and huge. We did not mention the Unicode Planes or the Grapheme concept, but we have enough knowledge to understand why '😊'.length equals 2.

Why `'😊'.length` is equal to 2

Before answering this question, we must understand how strings are represented in Node.js. So far, we have talked about Unicode characters as code points, but Node.js does not understand what a code point is. It only understands code units.

A code unit is the smallest unit of information that a system can manipulate. For example, in a 7-bit ASCII system, a code unit is a single byte. In a 16-bit Unicode system, a code unit is a 16-bit word.

Node.js (and its underlying V8 engine) sees strings as a sequence of 16-bit Unicode characters, so one code unit is 16 bits long.

The final step is understanding how to convert a code point to a code unit.

Let's say we want to convert the 😊 (U+1F60A) emoji to its code units. To do it, we can write this low-level code:

const codePoint = 'U+1F60A'; // 😊

// Convert the code point to a string.
// Remember that a code point is a hexadecimal number.
const codePointAsInteger = codePoint.split('U+').filter(c=>c).map((hex) => parseInt(hex, 16));

// Convert the code point to a string.
const codePointAsString = String.fromCodePoint(...codePointAsInteger);

// Convert the string input to an array of code units.
const codeUnits = toCodeUnits(codePointAsString);

console.log({
  codePoint,
  codePointAsInteger,
  codePointAsString,
  stringLength: codePointAsString.length,
  codeUnits,
  codeUnitAsString: String.fromCharCode(...codeUnits),
  codeUnitsLength: codeUnits.length,
});

function toCodeUnits(string) {
  const codeUnits = []

  for (let i = 0; i < string.length; i++) {
    const char = string[i]    
    const codePoint = char.codePointAt(0)
    codeUnits.push(codePoint)
  }

  return codeUnits
}

In the code above we are executing the following steps:

Convert the code point string to an integer array.
Convert the integer array to a string using String.fromCodePoint.
Convert the string to an array of code units.
Print the results.

Note that the code is not optimized, and it is not intended to be used in production.

The first step is to convert the code point string from the U+ format to an integer array.

Note
The code point can be declared as an integer just like this: const codePoint = 0x1F60A; (hexadecimal representation) or like a string const codePoint = '\u{1F60A}'; in UTF32 representation, but I find more interesting to show how to convert it from a Unicode format.

The second step is to convert the integer array to a string using String.fromCodePoint. We did not use the String.fromCharCode method because it does not support Unicode code points greater than 0xFFFF (or 65536 in decimal).

The third step is to convert the string to an array of code units. We did it by iterating over the string and calling the String.prototype.codePointAt method on each character.

The last step should print the following output:

{
  codePoint: 'U+1F60A',
  codePointAsInteger: [ 128522 ],
  codePointAsString: '😊',
  stringLength: 2,
  codeUnits: [ 55357, 56842 ],
  codeUnitAsString: '😊',
  codeUnitsLength: 2
}

As we can see, the 😊 emoji is represented by two code units: 55357 and 56842.

🏆 The Node.js string length is equal to the number of its code units. So, if the string has characters that require more than one code unit to be displayed, the string length will be greater than the character length.

Technical explanation

Previously we said that Node.js stores strings as a sequence of 16-bit Unicode characters. This means that it can store up to 65536 different characters. However, Unicode defines more than 65536 characters, so it uses a technique called surrogate pairs. Every character that requires more than 16 bits to be represented is split into two 16-bit code units.

Now, try to check the output for these code points:

const codePoint = 'U+1F468U+200DU+1F467U+200DU+1F466'; // 👨‍👧‍👦
const codePoint = 'U+1F90CU+1F3FC' // 🤌🏼

You will be surprised that the string length is 8 and 4, respectively.

How to count the number of characters in a string

But how can we count the number of characters in a string without using the String.length property?

A common solution is to use the String.normalize method to convert the string to a normalization form. Then, using the spread operator to convert the string to an array of code points will give us the number of characters in the string.

[...'ñañaña'.normalize()].length; // 6
[...'ñañaña'].length; // 9

In this example, the ñ is represented by two code points n(U+006E) + ◌̃(U+0303), but the normalize method will convert it to a single code point ñ(U+00F1).

Unfortunately, this does not work for all emojis:

[...'😊'.normalize()].length // 1
[...'🤌🏼'.normalize()].length // It is still 2!!!

So, we must adopt a new strategy by using Intl.Segmenter to split the string into segments and count the number of segments.

const segmenter = new Intl.Segmenter('en', { granularity: 'grapheme' });
[...segmenter.segment('🤌🏼')].length // 1 🎉

Note
It is available in Node.js since version 16.0.0 and it is not supported by all the browsers.

You may choose the best solution for your use case.

Summary

In this article, we learned how to convert a Unicode code point to a code unit and why String.length is not equal to the number of characters in a string. I tried to explain the concepts in a simple and accessible way. If you want to learn more about Unicode and Node.js, I recommend you to read these detailed articles:

https://mathiasbynens.be/notes/javascript-unicode
https://dmitripavlutin.com/what-every-javascript-developer-should-know-about-unicode/
https://tonsky.me/blog/unicode/

Other useful resources that I used to debug things are:

https://github.com/node-unicode/node-unicode-data to get all the Unicode data in Node.js.
https://codepoints.net/ to explore Unicode characters and code points.
https://www.compart.com/en/unicode/ to explore Unicode planes and groups.

If you enjoyed this article, comment, share and follow me on Twitter!

The Secrets Behind High Performance With Node.js

Manuel Spigolon — Sun, 16 Apr 2023 07:10:38 GMT

I always strive to write actionable articles, but let’s face it: improving code performance can be a bit intimidating. Not today, my friends!
In this post, I’ll share some lesser-known but highly effective strategies to speed up your codebase — starting tomorrow.
Get ready to learn some serious performance hacks!

During a starry evening, I happened to remember what I thought was a performant solution compared to what I see in the Node.js panorama, and I think it's worth sharing.

What I thought is that the fastest code implementation is achieved by using:

Esoteric data structures
Unknown algorithms
Bitwise operations
A master degree in rocket science

...and I was wrong!

Let me share some of the secrets behind high performance with Node.js.

Regular expressions are slow

The title explains it all — regular expressions are slow. If you see a regular expression in your code then that code can be optimized by removing the regular expression.

The error I was making is to think that regular expressions have a complexity of O(1), but they don't.
I know, I know, I was silly to think that.
Anyway, the regular expression complexity depends on the engine implementation. In Node.js, the RegExp engine is performed by V8 v10.2.x, which implements a backtracking algorithm with a complexity of O(2ⁿ)!

In fact, if you try to run this simple code:

/(a*)*b/.exec('a'.repeat(100))

It will take 90 seconds.
Instead, if you run the previous code with node --enable-experimental-regexp-engine-on-excessive-backtracks regexp.js, it will take only 0,01 seconds!!

The V8 flag --enable-experimental-regexp-engine-on-excessive-backtracks enables a new experimental non-backtracking RegExp engine. You can deepen this new algorithm by following the guidance in this V8 article.

So, the first takeaway is that regular expressions are slow, and you should avoid them as much as possible. If you can't avoid them, you should try to check the node --v8-options and verify if you can tune the default RegExp engine.

If you are interested in the topic then you can find out more by reading this article. It explains the complexity of regular expressions and compares the different algorithms.

You don't need regular expressions

Sorry to be so repetitive, but I must talk about regular expressions again.
Sometimes a regular expression seems to be the best solution, but it's not.

Let's take a look at the following code:

const utf8MimeType = /^text\/|^application\/(javascript|json)/
const isUtf8MimeType = utf8MimeTypeRE.test('application/json')

The code above is a simple check to verify if a MIME type is UTF-8 and matches multiple combinations of MIME types.

The code is simple, but it's not performant because it can be optimized by removing the regular expression:

function isUtf8MimeType (value) {
  const len = value.length
  return (
    (len > 21 && value.indexOf('application/javascript') === 0) ||
    (len > 14 && value.indexOf('application/json') === 0) ||
    (len > 5 && value.indexOf('text/') === 0)
  )
}

const isUtf8MimeType = isUtf8MimeType('application/json')

The latter code is faster than the former code because it doesn't use a regular expression.
What does "faster" mean?
The first code executes 10,632,205 ops/sec ±1.69% (191 runs sampled), while the second code executes 1,132,847,245 ops/sec ±0.15% (192 runs sampled). The second code is 106x times faster than the first code.

The code example is not trivial because it is one of Fastify's pieces of code! Uzlopak is one of the Fastify team members obsessed with performance.

Silly code is not so silly

There may be times when you think the source code is silly, but it's not.
Let's normalize an unknown input into a string array. If we can't normalize the input, we throw an error:

function normalizeList (val) {
  if (typeof val === 'string') {
    return [val]
  } else if (val === false) {
    return []
  } else if (Array.isArray(val)) {
    for (let i = 0, il = val.length; i < il; ++i) {
      if (typeof val[i] !== 'string') {
        throw new TypeError('must be array of strings or false')
      }
    }
    return val
  } else {
    throw new TypeError('must be array of strings or false')
  }
}

I'm sure this code works, but it may not pass a coding interview — it's too verbose, and there is a smell of duplication... but it is performant! The code above is 4x times faster than the nice and clean code below:

function normalizeList (val) {
  const list = [].concat(val || [])
  for (let i = 0; i < list.length; i++) {
    if (typeof list[i] !== 'string') {
      throw new TypeError('must be array of strings or false')
    }
  }
  return list
}

So it is important to understand that sometimes simple checks are faster than a single line of code. Let's call it an exit early pattern.
This doesn't mean that you should write verbose code, but you should be aware how to improve the performance:

Conditions that are more likely to be true should be checked first
Simple checks are faster than forcing a unique code path
A bit of duplication is better than a bit less performance

Another interesting example is to map all the supported ASCII characters to a Map object. In Fastify we did this too, and all in the name of performance. This new code helps us to reduce the complexity of the code by treating uppercase and lowercase characters as the same. For sure, this code would not pass a coding interview as well!

Performance shortcuts

Earlier, I mentioned that you should write readable code and prefer simple checks. However, it's worth mentioning that sometimes you may isolate a piece of code that is not readable, but it is faster.

A perfect example is the new Function usage. By writing:

const functionArgs = ['value']
const functionBody = 'return value[0].toUpperCase()'
const fn = new Function(...functionArgs, functionBody)

console.log(fn('Hello')) // prints H

You can create a function body at runtime by concatenating strings.

This technique is the secret sauce of Fastify's fast-json-stringify module. Another extreme example is the string.startsWith and string.endsWith methods.
If we want to check that a string starts with the foo string, we can generate a function body like the following:

const functionArgs = ['value']
const functionBody = `return value[0] === 'f' && value[1] === 'o' && value[2] === 'o'`
const fn = new Function(...functionArgs, functionBody)

console.log(fn('foo')) // prints true
console.log(fn('bar')) // prints false

The generated function is 14x times faster than the native method! This is the technique likely to be integrated into Fastify's code.

⚠️ Note that generating a function body at runtime could be unsafe if you are managing user input to generate the function. Be careful when you use this technique to make sure it improves the performance!

Know your language and runtime

Node.js is a JavaScript runtime, but it has its own peculiarities that you should know in order to be able to write performant code. If you deal with the Error object, or you have ever implemented a custom error, you should know about the Error.stackTraceLimit

The Error.stackTraceLimit is the maximum number of stack frames captured by the Error.stack property. The default value is 10, but you can change it to 0 when you don't need the complete stack trace, and this will improve the performance by 600x times!

This is an example of the most uncommon property of Node.js, but it is not always about tweaking the runtime, sometimes you need to know the best constructs to use in your code. RafaelGSS is a Node.js core contributor, and he has written a benchmark to compare the performance of the different operations in JavaScript.
For example:

Concatenating strings using ['a', 'b', 'c'].join('') is 100x slower than a + b + c!
The foreach loop is ~5% slower than the for loop!

The takeaway is to write readable and maintainable code, then optimize it by isolating the hot path and benchmarking it. The last step is to optimize the hot path, focusing on tiny pieces of code.

Use the right data structure

The data structure you use in your code can greatly impact your application's performance.

There is no slow programming language, just bad algorithms and data structures design.

Says Michele Riva in his talk at NodeConf EU 2022. That is incredibly true, and you should always consider the data structure you use in your code.

If you are looping an array repeatedly, it is essential to ask yourself if you can use a Map or a Set instead. A tree data structure is sometimes the best solution to run performant searches and traversals.

I can't suggest a simple rule for you to follow, but you should always think about the data structure you are using and the algorithm that uses it.
I find it useful to check the Big O notation cheat sheet of the data structure and to read some books about these topics.

Summary

In this article, we have seen how to improve the performance of a Node.js application by using and writing performant code and avoiding unnecessary operations.

Now, think about the application you are working on and try to speed it up by using the techniques we have highlighted in this article.

If you enjoyed this article, comment, share and follow me on Twitter! Remember to follow Uzlopak on GitHub to see his amazing work on Fastify!

Dynamic GraphQL queries with Mercurius

Manuel Spigolon — Sun, 19 Mar 2023 07:45:39 GMT

If you're using Fastify with Mercurius as your GraphQL adapter, you may be looking for some advanced usages. In this article, we'll explore a real world example with Dynamic GQL queries with Mercurius.

The example we will discuss is only one scenario that you may encounter as Software Engineer at NearForm! If you want to solve these kind of problems, we are hiring!

What are Dynamic GraphQL queries?

A dynamic GraphQL query is a query that is constructed at runtime, based on the needs of the client. This is useful when the client is uncertain of the structure of the data and needs to retrieve specific data based on conditions, or when the client needs to retrieve a subset of data depending on the user's role or permissions.

In our use case, we want to invert the control of query dynamicity from the client to the server. This means that the client will send a standard GQL query and the server will return the data based on:

The client's query
The user's role

It's important to note that we are not talking about returning a subset of a generic GraphQL type, but a completely different GraphQL type.

Defining the schema

When creating a GraphQL server, the first step is to define the schema. The GraphQL specification provides clear guidance on how to accomplish our target by utilizing GraphQL Unions.

Unions in GraphQL allow for multiple types to be returned from a single field, making it a powerful tool for querying related data. This can be especially useful when retrieving data from multiple types in a single query.

To begin, let's define our schema using GraphQL Unions.

type Query {
  searchData: Grid
}

union Grid = AdminGrid | ModeratorGrid | UserGrid


type AdminGrid {
  totalRevenue: Float
}

type ModeratorGrid {
  banHammer: Boolean
}

type UserGrid {
  basicColumn: String
}

As you can see, our schema includes a Query type with a searchData field that returns a Grid union type. This Grid union type can represent one of three possible types: AdminGrid, ModeratorGrid, or UserGrid.

Currently, the client can send a query using inline fragments like this:

query {
  searchData {
    ... on AdminGrid {
      totalRevenue
    }
    ... on ModeratorGrid {
      banHammer
    }
    ... on UserGrid {
      basicColumn
    }
  }
}

While this is a valid query, it is not the desired outcome. We aim to return a different type based on the user's role, so that the client can send a query like this:

query {
  searchData {
    totalRevenue
  }
}

It's important to note that the above query is not valid against the schema defined above, but with some additional implementation, we can make it work!

Implementing the business logic

Let's start building the basic implementation of our server. You can skip this section if you are already familiar with Fastify and Mercurius.

The first step is to install the necessary dependencies.

mkdir graphql-dynamic-queries
cd graphql-dynamic-queries
npm init -y
npm install fastify@4 mercurius@11

Now, copy the schema we defined above in a gql-schema.js file, then you need to create an app.js file where we will write our server:

const Fastify = require('fastify')
const GQL = require('mercurius')
const schema = require('./gql-schema')

// For simplicity, we will start the server only if started with `node app.js run`
if (process.argv[2] === 'run') {
  buildApp()
    .then(app => app.listen({ port: 8080 }))
}

async function buildApp () {
  const app = Fastify({ logger: true })

  await app.register(GQL, {
    schema,
    resolvers: {
      Query: {
        searchData: async function (root, args, context, info) {
          // TODO: implement the business logic
          return {}
        }
      },
      Grid: {
        resolveType (obj, context) {
          return getUserType(context)
        }
      }
    }
  })

  return app
}

module.exports = buildApp

function getUserType (context) {
  switch (context.reply.request.headers['x-user-type']) {
    case 'admin':
      return 'AdminGrid'
    case 'moderator':
      return 'ModeratorGrid'
    default:
      return 'UserGrid'
  }
}

To verify that everything is working, you can start the server running node app.js run and you should see the following output:

Server listening at http://127.0.0.1:8080

Great! Now we must list all the use cases we want to implement by adding some test cases.

Testing our server

We want to test our server with the following use cases:

A user with the admin role should be able to retrieve the totalRevenue field without inline fragments
A user with the moderator role should be able to retrieve the banHammer field without inline fragments
A user with the user role should be able to retrieve the basicColumn field without inline fragments
A user without the admin role should not be able to retrieve the totalRevenue field
A user without the moderator role should not be able to retrieve the banHammer field
A user without the user role should not be able to retrieve the basicColumn field
A user without any role should not be able to retrieve any field

We must install the required dependencies:

npm install tap@15 -D

We can write these tests in a test.js file.

const { test } = require('tap')

const buildApp = require('./app')

test('A user with the `admin` role should be able to retrieve the `totalRevenue` field without inline fragments', async t => {
  const app = await buildApp()
  const res = await doQuery(app, 'admin', `
    query {
      searchData {
        totalRevenue
      }
    }
  `)

  t.same(res.data.searchData, { totalRevenue: 42 })
})

// TODO: add the other tests

async function doQuery (app, userType, query) {
  const res = await app.inject({
    method: 'POST',
    url: '/graphql',
    headers: {
      'x-user-type': userType
    },
    body: {
      query
    }
  })

  return res.json()
}

For the sake of simplicity, we will not list all the tests here, but you can find the complete complete source code in the GitHub repository.

Running the tests with node test.js will fail because we have not implemented the business logic yet. So, let's start writing the code!

Implementing the server-side Dynamic Queries

To implement the business logic, there are these main steps:

Retrieve the user's role from the request headers
Manage the GraphQL query to return the correct type based on the user's role

Let's solve the first point.

How to retrieve the user's role

We can implement the user role retrieval by installing the mercurius-auth plugin.

npm i mercurius-auth@3

Then, we can register the plugin in our app.js file. To understand what the plugin does, you can read its documentation.

In the following example, we will compare the x-user-type HTTP header with the @auth directive we are going to define in the schema. If they match, the user will be authorized to access the field and run the query.

Let's start by defining the @auth directive in the schema:

directive @auth(
  role: String
) on OBJECT

# ..same as before

type AdminGrid @auth(role: "admin") {
  totalRevenue: Float
}

type ModeratorGrid @auth(role: "moderator") {
  banHammer: Boolean
}

type UserGrid @auth(role: "user") {
  basicColumn: String
}

Then, we can register the plugin in our app.js file and implement a simple searchData resolver:

async function buildApp () {
  const app = Fastify() // the same as before

  await app.register(GQL, {
    schema,
    resolvers: {
      Query: {
        searchData: async function (root, args, context, info) {
          switch (getUserType(context)) {
            case 'AdminGrid':
              return { totalRevenue: 42 }

            case 'ModeratorGrid':
              return { banHammer: true }

            default:
              return { basicColumn: 'basic' }
          }
        }
      },
    },
    Grid: {} // the same as before 
  })

  app.register(require('mercurius-auth'), {
    authContext (context) {
      return {
        identity: context.reply.request.headers['x-user-type']
      }
    },
    async applyPolicy (policy, parent, args, context, info) {
      const role = policy.arguments[0].value.value
      app.log.info('Applying policy %s on user %s', role, context.auth.identity)

      // we compare the schema role directive with the user role
      return context.auth.identity === role
    },
    authDirective: 'auth'
  })

  return app
}

Now, the user should be able to retrieve the totalRevenue field only if the x-user-type header is set to admin.

Nevertheless, we can't run the tests yet because we have not implemented the second point.

Implementing the Dynamic Queries

The last step is to implement the dynamic queries. Right now, our tests are failing with the following error:

"Cannot query field 'totalRevenue' on type 'Grid'. Did you mean to use an inline fragment on 'AdminGrid'?

The error is correct because we are not using inline fragments to query a Union type.

To overcome this issue, we can use the mercurius preValidation hook. Let's try to see how it works:

When a client sends a GraphQL query, the server will process the GQL Document in the preValidation hook, before validating the GQL against the GQL Schema.

In this hook, we can modify the GQL Document sent by the user to add the inline fragments. So, after the mercurius-auth plugin registration, we can add the following code:

async function buildApp () {
  const app = Fastify() // the same as before

  await app.register(GQL, {
    // the same as before 
  })

  app.register(require('mercurius-auth'), {
    // the same as before
  })

  app.graphql.addHook('preValidation', async (schema, document, context) => {
    const { visit } = require('graphql')

    const userType = getUserType(context)

    const newDocument = visit(document, {
      enter: (node) => {
        // We check if we must add the inline fragment
        const isMaskedQuery = node.kind === 'Field' &&
                              node.name.value === 'searchData' &&
                              node.selectionSet.selections.length === 1 &&
                              node.selectionSet?.selections.length > 0

        if (isMaskedQuery) {
          // This is the magic, we add a new inline fragment modifying the AST
          const nodeWithInlineFragment = {
            ...node,
            selectionSet: {
              kind: 'SelectionSet',
              selections: [
                {
                  kind: 'InlineFragment',
                  typeCondition: {
                    kind: 'NamedType',
                    name: {
                      kind: 'Name',
                      value: userType
                    }
                  },
                  selectionSet: node.selectionSet
                }
              ]
            }
          }
          return nodeWithInlineFragment
        }
      }
    })

    // We apply the new AST to the GQL Document
    document.definitions = newDocument.definitions
  })

  return app
}

In the previous code, we inspect the GraphQL Document Abstract Syntax Tree (AST) to determine if we need to add the inline fragment programmatically. If we recognize the query as a masked query, we add the inline fragment to the AST and return the modified AST to the GraphQL Document.

By doing this, Mercurius will process the modified GraphQL Document as if the user had sent it with the inline fragment. This means that it will:

Validate the GraphQL Document against the GraphQL Schema
Apply the authentication policy
Resolve the query

With this implementation, when running tests, everything should pass successfully.

Summary

We have seen how versatile Mercurius is and how simple it is to implement features like dynamic queries in a complex scenario. While the goal may seem challenging, this server-side implementation provides several benefits such as:

Avoiding breaking changes on the client side to support new features
Hiding GraphQL Types from the client through disabling schema introspection
Applying query optimizations for the client
Providing a specialized response based on the user type instead of a generic one.

This is just a small example of the possibilities when using Mercurius and manipulating the GraphQL Document.

If you have found this helpful, you may read other articles about Mercurius.

Now jump into the source code on GitHub and start to play with the GraphQL implemented in Fastify.

If you enjoyed this article comment, share and follow me on Twitter!

Backend Cafe

React Server-Side Streaming with Fastify

Setting up the project

How does reply.hijack() work?

Streaming a React component

Why streaming matters

Summary

Signing git commits with GPG

Setup GPG

Pinentry

Create a GPG key pair

Verify GPG signing works

Configure GitHub to verify your GPG signatures

Configure Git to sign commits by default

Test it!

Backup your GPG keys

Summary

Beyond Vibe Coding

When AI Amplifies Chaos

My Journey: Discovering Context by Evolution

Enter Contextual Intelligence

Beyond Tools: A Way of Thinking

Implementing Contextual Intelligence: The Persona Approach

🔮 The Farseer - Strategic Contextual Intelligence

👻 The Spiritwalker - Archaeological Contextual Intelligence

🦏 The Kodo - Architectural Contextual Intelligence

⚔️ The Chieftain - Organizational Contextual Intelligence

🗡️ The Grunt - Implementation Contextual Intelligence

🧙 The Witchdoctor - Diagnostic Contextual Intelligence

Making It Real: Building the System

A Quick Note on Naming (Yes, I love The Frozen Throne)

The Path Forward

Handling HTTP timeouts in Fastify

How many timeouts do I need?

Setting up timeouts in Fastify

Testing timeouts

Test the headersTimeout

Test result

Summary

Managing Request-Scoped Data in Fastify

What is AsyncLocalStorage?

How It Works

Why Is This Important?

How to Use the @fastify/request-context Plugin

Quick Start

@fastify/request-context vs Decorators

Summary

Announcing the Fastify Mini Course

🚀 Why Fastify?

📖 What’s Inside the Mini Course?

🎯 Who Is This For?

📅 How to Get Access

🚀 Get Ready to Build Faster APIs!

Master Node.js with the 5th Edition Cookbook

How to implement video streaming with Fastify

Setting up the project

Getting ready to stream

Streaming video content

Understanding range requests

Implementing the /video-streaming route

Conclusion

Resume data replication in Postgres and Node.js

Creating a replication slot

Configuring the consumer

Resuming the replication

Conclusion

Real-time data replication in Postgres and Node.js

Introduction to Postgres replication management

The WAL file

Developing a real-time data replication system with Node.js

Setting up Postgres

Creating a data producer

Creating a data consumer

Setting up the data consumer

Subscribing to changes

Conclusion

Create a Telegram Bot with Fastify from Scratch

Setting up the Project

Implementing the Telegram bot

Registering Users

Test the `headersTimeout`

How to Use the `@fastify/request-context` Plugin

`@fastify/request-context` vs Decorators

Implementing the `/video-streaming` route

The new `onListen` hook

Integrate `joi` with `fastify`

How to configure the `joi-compiler`

How to use `ajv` and `joi` together!

Why `'😊'.length` is equal to 2