DEV Community: zenstok

🎬 M3U8 to MP4 — The Easiest Way to Convert Videos, Instantly & Privately

zenstok — Mon, 16 Jun 2025 08:19:31 +0000

You’ve been there.

You find the perfect video, try to download it... and what do you get? A weird .m3u8 file. No MP4. No playback. Just confusion.

We get it — it’s frustrating. That’s why we built a better way.

🚀 Introducing: Instant M3U8 to MP4 Conversion

No installs. No extensions. No waiting. Just your browser.

Paste a link. Get your MP4. That’s it.

Here’s why it hits different:

✅ 100% free — and always will be
✅ Unlimited conversions — as long as your browser can handle it
✅ No file size limits — works even for big videos
✅ Works in-browser — no downloads, no setup
✅ Lightning fast — converts in seconds

🔒 Privacy-First, No Exceptions

We don’t see your files. Everything happens locally, right inside your browser tab.

No uploads
No snooping
No third-party servers
Zero data exposure

You keep your files. We just help you convert them — fast.

📦 Got a `.zip` of the playlist files instead of a link?

No problem. Drop it in. You’ll still get an MP4.

Try it now → https://www.m3u8-to-mp4-converter.com/

And yes — it really is that simple.

How to Avoid the Single-Threaded Trap in JavaScript

zenstok — Fri, 01 Nov 2024 08:59:29 +0000

JavaScript is often described as single-threaded, which means it executes one task at a time. But does this imply that every piece of code runs in complete isolation, with no ability to handle other tasks while waiting for asynchronous operations like HTTP responses or database requests? The answer is no! In fact, JavaScript’s event loop and promises allow it to handle asynchronous tasks efficiently while other code continues to run.

The truth is javascript is indeed single-threaded, however, misunderstanding how this works can lead to common pitfalls. One such trap is managing asynchronous operations like API requests, especially when trying to control access to shared resources without causing race conditions. Let's explore a real-world example and see how poor implementation can lead to serious bugs.

I encountered a bug in an application that required logging into a backend service to update data. Upon logging in, the app would receive an access token with a specified expiration date. Once this expiration date passed, we needed to re-authenticate before making any new requests to the update endpoint. The challenge arose because the login endpoint was throttled to a maximum of one request every five minutes, while the update endpoint needed to be called more frequently within that same five-minute window. It was critical for the logic to function correctly, yet the login endpoint was occasionally triggered multiple times within the five-minute interval, leading to the update endpoint failing to work. While there were times when everything functioned as expected, this intermittent bug presented a more serious risk, as it could give a false sense of security at first, making it seem like the system was operating properly.

To illustrate this example, we're using a very basic NestJS app that includes the following services:

AppService: Acts as a controller to simulate two variants— the bad version, which sometimes works and sometimes doesn't, and the good version, which is guaranteed to always function properly.
BadAuthenticationService: Implementation for the bad version.
GoodAuthenticationService: Implementation for the good version.
AbstractAuthenticationService: Class responsible for maintaining the shared state between the GoodAuthenticationService and BadAuthenticationService.
LoginThrottleService: Class that simulates the throttling mechanism of the login endpoint for the backend service.
MockHttpService: Class that helps simulate HTTP requests.
MockAwsCloudwatchApiService: Simulates an API call to the AWS CloudWatch logging system.

I won't show the code for all these classes here; you can find it directly in the GitHub repository. Instead, I will focus specifically on the logic and what needs to be changed for it to work correctly.

The Bad Approach:

@Injectable()
export class BadAuthenticationService extends AbstractAuthenticationService {
  async loginToBackendService() {
    this.loginInProgress = true; // this is BAD, we are inside a promise, it's asynchronous. it's not synchronous, javascript can execute it whenever it wants

    try {
      const response = await firstValueFrom(
        this.httpService.post(`https://backend-service.com/login`, {
          password: 'password',
        }),
      );

      return response;
    } finally {
      this.loginInProgress = false;
    }
  }

  async sendProtectedRequest(route: string, data?: unknown) {
    if (!this.accessToken) {
      if (this.loginInProgress) {
        await new Promise((resolve) => setTimeout(resolve, 1000));
        return this.sendProtectedRequest(route, data);
      }

      try {
        await this.awsCloudwatchApiService.logLoginCallAttempt();
        const { data: loginData } = await this.loginToBackendService();
        this.accessToken = loginData.accessToken;
      } catch (e: any) {
        console.error(e?.response?.data);
        throw e;
      }
    }

    try {
      const response = await firstValueFrom(
        this.httpService.post(`https://backend-service.com${route}`, data, {
          headers: {
            Authorization: `Bearer ${this.accessToken}`,
          },
        }),
      );

      return response;
    } catch (e: any) {
      if (e?.response?.data?.statusCode === 401) {
        this.accessToken = null;
        return this.sendProtectedRequest(route, data);
      }
      console.error(e?.response?.data);
      throw e;
    }
  }
}

Why This Is a Bad Approach:

In the BadAuthenticationService, the method loginToBackendService sets this.loginInProgress to true when initiating a login request. However, since this method is asynchronous, it does not guarantee that the login status will be updated immediately. This could lead to multiple concurrent calls to the login endpoint within the throttling limit.
When sendProtectedRequest detects that the access token is absent, it checks if a login is in progress. If it is, the function waits for a second and then retries. However, if another request comes in during this time, it can trigger additional login attempts. This can lead to multiple calls to the login endpoint, which is throttled to allow only one call every minute. As a result, the update endpoint may fail intermittently, causing unpredictable behavior and a false sense of security when the system appears to be functioning properly at times.

In summary, the problem lies in the improper handling of asynchronous operations, which leads to potential race conditions that can break the logic of the application.

The Good Approach:

@Injectable()
export class GoodAuthenticationService extends AbstractAuthenticationService {
  async loginToBackendService() {
    try {
      const response = await firstValueFrom(
        this.httpService.post(`https://backend-service.com/login`, {
          password: 'password',
        }),
      );

      return response;
    } finally {
      this.loginInProgress = false;
    }
  }

  async sendProtectedRequest(route: string, data?: unknown) {
    if (!this.accessToken) {
      if (this.loginInProgress) {
        await new Promise((resolve) => setTimeout(resolve, 1000));
        return this.sendProtectedRequest(route, data);
      }

      // Critical: Set the flag before ANY promise call
      this.loginInProgress = true;

      try {
        await this.awsCloudwatchApiService.logLoginCallAttempt();
        const { data: loginData } = await this.loginToBackendService();
        this.accessToken = loginData.accessToken;
      } catch (e: any) {
        console.error(e?.response?.data);
        throw e;
      }
    }

    try {
      const response = await firstValueFrom(
        this.httpService.post(`https://backend-service.com${route}`, data, {
          headers: {
            Authorization: `Bearer ${this.accessToken}`,
          },
        }),
      );

      return response;
    } catch (e: any) {
      if (e?.response?.data?.statusCode === 401) {
        this.accessToken = null;
        return this.sendProtectedRequest(route, data);
      }
      console.error(e?.response?.data);
      throw e;
    }
  }
}

Why This Is a Good Approach:

In the GoodAuthenticationService, the loginToBackendService method is structured to handle the login logic efficiently. The key improvement is the management of the loginInProgress flag. It is set after confirming that an access token is absent and before any asynchronous operations begin. This ensures that once a login attempt is initiated, no other login calls can be made concurrently, effectively preventing multiple requests to the throttled login endpoint.

Demo Instructions

Clone the Repository:

git clone https://github.com/zenstok/nestjs-singlethread-trap.git

Install the Necessary Dependencies:

cd nestjs-singlethread-trap
npm install

Run the Application:

npm run start

Simulate requests:

To simulate two requests with the bad version, call:

http://localhost:3000/simulate-2-requests-bad-version

To simulate two requests with the good version, call:

http://localhost:3000/simulate-2-requests-good-version

Conclusion: Avoiding JavaScript's Single-Threaded Pitfalls

While JavaScript is single-threaded, it can handle asynchronous tasks like HTTP requests efficiently using promises and the event loop. However, improper handling of these promises, particularly in scenarios involving shared resources (like tokens), can lead to race conditions and duplicate actions.
The key takeaway is to synchronize asynchronous actions like logins to avoid such traps. Always ensure that your code is aware of ongoing processes and handles requests in a way that guarantees proper sequencing, even when JavaScript is multitasking behind the scenes.

If you haven't already joined the Rabbit Byte Club, now is your chance to hop into a thriving community of software enthusiasts, tech founders, and non-tech founders. Together, we share knowledge, learn from each other, and prepare to build the next big startup. Join us today and be part of an exciting journey towards innovation and growth!

Introducing Rabbit Byte Club Discord Community

zenstok — Mon, 28 Oct 2024 09:11:46 +0000

🚀 Exciting News! Rabbit Byte Club Has Launched!

I’m thrilled to announce the start of Rabbit Byte Club’s community on Discord! For anyone passionate about software development, business, and tech innovation, this is your chance to join a community dedicated to elevating global software quality through shared ideas and expertise.

🎁 Early Member Benefits:
Lifetime Access: The first 50 members who join the Rabbit Byte Discord community will receive lifetime access to my future paid articles on RabbitByte.club, completely free of charge!
Exclusive Support: Direct access to me to discuss your software ideas, challenges, and questions. I’ll be offering my time to help you solve issues, all for free.

🌟 Invest Early, Reap the Benefits!
With over 25,000 views on my posts, I’m excited to launch Rabbit Byte Club’s premium mentorship packages starting at 50 EUR for 30 minutes or 80 EUR for an hour. If you are among the first 5 people to join the Discord community and subscribe to the newsletter on RabbitByte.club, you’ll receive a free 30-minute consultation each month, valued at 50 EUR! This means you can gain up to 600 EUR in value each year at no cost, as long as the mentorship program is in place. Whether you’re a tech founder, a software engineer facing complex issues, or a non-tech founder looking to build your software vision, I’ll be there to support you.
Starting November 1st, 1:1 mentoring sessions will be open for booking, and subscriptions will be available. Spots are limited, so make sure to grab yours early!
Join us today on Discord and secure your place in a growing community where ideas, expertise, and resources are shared freely to foster innovation.

Let’s build something amazing together!
Community link: https://discord.com/invite/qum7KGX3

How to Create and Download Files of Unlimited Size in node.js/NestJS

zenstok — Sun, 06 Oct 2024 15:26:44 +0000

Hey, folks! Have you ever wondered if it's possible to send a file of unlimited size to your users, all while giving them real-time feedback during the download process? Well, today, we're diving into exactly that. Let’s explore how we can achieve this in NestJS using one of Node.js's most powerful features—Streams.

In this guide, I’m not just going to show you how to download files of unlimited size—I’ll also walk you through the magic of streams and how they really work behind the scenes.

The Scenario: A Manager's Report Download

Imagine a manager needs to download a dynamically generated report containing invoice data, based on a user-defined date range. The twist? We have no idea how big the report will be because the user sets the parameters. We need to stream this data efficiently without overwhelming our server’s memory. Here’s where chunked transfer encoding comes into play. By setting the Transfer-Encoding header to chunked (learn more here), we can send the data in chunks, eliminating the need for a predetermined file size.

But wait—how do we handle massive file sizes? The answer is simple: Node.js Streams.

Why Not Buffers?

At first, you might think we can handle this using file buffers. However, buffers are limited by the server’s memory. If you’re dealing with large files, buffers will quickly hit a ceiling. Instead, we turn to streams, which are the backbone of Node.js when it comes to data management.

Streams process data in small chunks, sending it out without holding everything in memory. This way, we can handle "infinite" files, or at least ones large enough to blow your mind.

What are streams?

Streams in Node.js are powerful objects that let us process batches of data without loading everything into memory. Instead of holding the entire dataset, streams process chunks of data and pass them along as they go. So, because they don’t hold all the data in memory, they can handle massive files. But where do these chunks go? They’re passed on to other streams!

There are two key types of streams you’ll be working with in Node.js: readable and writable streams.

Let’s break it down with an example:

If you’re reading a file’s contents, you’d use the fs.createReadStream method. This returns a readable stream object, which gives you chunks of the file’s data bit by bit.

But once you’ve read the data, how do you send it to the user as an HTTP response?

Well, here’s the cool part: in Node.js, the response object itself is a writable stream. What does that mean? It means you can take the data you’re reading from the readable stream and send it directly to the writable stream (the HTTP response) using a method called .pipe.

With just a few lines of code, the .pipe method lets you effortlessly stream file content directly to the client as an HTTP response—no need to worry about memory limits or large file sizes. Simple, right?

The Three Methods to Stream Large Files in NestJS

We’ll walk through three different ways to stream large files in NestJS, ranging from basic to more advanced, giving you both performance and flexibility.

The Easy Version: Node.js Out of the Box
The Performant Version: String-Based Stream Chunks
The Buffer Version: For When Precision Matters

1. The Easy Version

In this approach, we use Node.js's built-in interfaces to handle the heavy lifting for us. Here’s what the controller code looks like:

@Get('/simple')
@Header('Content-Disposition', `attachment; filename="bigJson.json"`)
@Header('Content-Type', 'application/json')
@Header('Transfer-Encoding', 'chunked')
getBigFileSimple(@Res() res: Response) {
  this.simpleService.getBigFile(res);
}

The @Header decorators set the file to be an attachment, specify the content type, and enable chunked transfer encoding. This allows us to send the file in parts without knowing its total size upfront.

In our service, we have the following method:

@Injectable()
export class SimpleService {
  constructor(private readonly jsonService: JsonService) {}

  getBigFile(res: Response) {
    return this.jsonService.createBigJsonFileStream().pipe(res);
  }
}

With just one line of code, we pipe the file stream to the response! This elegant solution leverages Node.js's stream piping, making it both simple and powerful.

Now, you might wonder—what exactly is this createBigJsonFileStream() method doing?

@Injectable()
export class JsonService {
  createBigJsonFileStream(rowsLength = 25000000): Readable {
    let currentRow = 1;
    rowsLength = this.getRandomLengthFromRange(rowsLength / 2, rowsLength);

    const stream = new Readable({
      read() {
        if (currentRow === 1) {
          this.push('[');
          this.push(`{"id":${currentRow},"name":"element${currentRow}"},`);
        } else if (currentRow === rowsLength) {
          this.push(`{"id":${currentRow},"name":"element${currentRow}"}`);
          this.push(']');
          this.push(null);
        } else {
          this.push(`{"id":${currentRow},"name":"element${currentRow}"},`);
        }
        currentRow++;
      },
    });

    return stream;
  }

  private getRandomLengthFromRange(min: number, max: number): number {
    return Math.floor(Math.random() * (max - min + 1) + min);
  }
}

In this case, we’re not serving a file from disk. Remember, the scenario we’re addressing is where a manager wants to download a report, choosing their own start and end dates. This means we need to dynamically generate the file based on the user's request. And how do we do that? You guessed it—with streams!

What’s happening here?

We’re creating a readable stream using Node.js’s Readable constructor (documentation here). We’re keeping things simple by focusing on the required read() method.

Here’s how it works: every time the stream has data to offer, the read() method is called. As long as we keep pushing data into the stream (and don’t push null), the stream will stay active and keep sending data.

In this example, we’ve set a rowsLength—the total number of rows our JSON file will have. (Note: We’re dynamically altering the rowsLength to simulate the manager selecting a start and end date, creating a random value to represent the report’s size.) Based on this, we push one row at a time into the stream. It’s that simple! We’re dynamically creating a huge JSON file, sending data chunk by chunk, and handling it all seamlessly without loading everything into memory.

2. The Performant Version: String-Based Chunks

In this approach, we fine-tune performance by manually controlling how the data is written to the response stream:

@Injectable()
export class PerformantService {
  constructor(private readonly jsonService: JsonService) {}

  getBigFile(res: Response) {
    const jsonStream = this.jsonService.createBigJsonFileStream();
    jsonStream.setEncoding('utf-8');
    let chunkSize = 0;
    let bigChunk = '';

    jsonStream.on('data', (chunk: string) => {
      bigChunk += chunk;
      chunkSize++;
      if (chunkSize === 1000) {
        const writable = res.write(bigChunk);
        if (!writable) {
          jsonStream.pause();
        }
        bigChunk = '';
        chunkSize = 0;
      }
    });

    res.on('drain', () => {
      jsonStream.resume();
    });

    jsonStream.on('error', (err) => {
      console.error(err);
      res.end();
    });

    jsonStream.on('end', () => {
      if (bigChunk.length) {
        res.write(bigChunk);
      }
      res.end();
    });
  }
}

So, what do we have here?

What do we have here? Well, the logic might look a bit complex, but that's because we’re handling the process of writing to the res writable stream manually. Why? We believe that our approach is faster than simply piping the stream.

So, how do we do it? First, we set the encoding of our JSON stream to UTF-8 using jsonStream.setEncoding('utf-8');. This ensures that instead of receiving default Buffer objects from the stream, we get data as UTF-8 encoded strings.

Next, we define two variables: chunkSize, initialized to 0, and bigChunk, an empty string. The cool thing about streams is that we can listen to events on them. For example, the data event gives us a data chunk every time the stream is read. But when is read called? It's triggered as soon as the readable stream is instantiated and continues until all the data is read—pretty cool, right? We know the stream has finished reading when we hit the end event.

Now, when data arrives from the stream, we want to be efficient. Instead of sending small chunks to the res stream, we batch 1,000 chunks together and send them as one large chunk to our HTTP response, which is itself a writable stream. But wait—why does the write method return a boolean? This introduces us to a crucial concept in Node.js streams: backpressure. As Node.js describes it, “backpressure occurs when data builds up behind a buffer during data transfer.” In simpler terms, it means the res stream is telling us, "Slow down! I can't keep up!"" The solution? We stop sending data! This is done by calling jsonStream.pause(), which halts the stream from reading further.

But what happens next? Now, we need to listen for another stream event—this time on the res writable stream. We need the stream to signal when it has recovered from the backpressure. This is where the "drain" event comes in. The "drain" event is emitted when it’s appropriate to resume writing data to the stream. So, once we catch this event, we simply resume reading from our big JSON stream!

Finally, when the JSON stream reaches the end event, we check if there’s any leftover data in bigChunk and write it to the res stream. After that, we call res.end() to signal that the response is complete.

And just like that, we’ve manually controlled how the data flows through the streams, handled backpressure, and delivered a dynamic file as a response!

3. The Buffer Version: Chunking with Buffers

For a more complex scenario, say we want to send large buffer chunks. Here's how we can handle it:

@Injectable()
export class BufferService {
  constructor(private readonly jsonService: JsonService) {}

  getBigFile(res: Response) {
    const jsonStream = this.jsonService.createBigJsonFileStream();

    const sendingChunkSize = 50 * 1024 * 1024; // 50 MiBs, Make sure to set the sending chunk size larger than the chunk buffer size to avoid unnecessary iterations in the while loop.
    let currentChunkSize = 0;
    let sendingChunk = Buffer.alloc(sendingChunkSize);

    jsonStream.on('data', (chunk: Buffer) => {
      while (chunk.byteLength > 0) {
        const availableSpace = sendingChunkSize - currentChunkSize;

        if (chunk.byteLength <= availableSpace) {
          // If the chunk fits within the remaining space
          chunk.copy(sendingChunk, currentChunkSize);
          currentChunkSize += chunk.byteLength;
          break;
        }

        // Fill the remaining space in the sendingChunk
        chunk.subarray(0, availableSpace).copy(sendingChunk, currentChunkSize);
        currentChunkSize += availableSpace;

        // Send the filled buffer
        const writable = res.write(sendingChunk);

        if (!writable) {
          jsonStream.pause();
        }

        // Reset for the next chunk
        sendingChunk = Buffer.alloc(sendingChunkSize);
        currentChunkSize = 0;
        chunk = chunk.subarray(availableSpace); // Process the rest of the chunk
      }
    });

    res.on('drain', () => {
      jsonStream.resume(); // Resume when writable
    });

    jsonStream.on('end', () => {
      // Send any remaining data that hasn't been flushed
      if (currentChunkSize > 0) {
        res.write(sendingChunk.subarray(0, currentChunkSize));
      }
      res.end();
    });

    jsonStream.on('error', (err) => {
      console.error(err); // Log error for debugging
      res.end();
    });
  }
}

Oh no, what’s going on here? It looks so complicated!

Well, that’s because it is a bit tricky! But here’s the backstory: we received a request from our boss to send file downloads in chunks of 50 MiB, because he has blazing-fast internet, he wants to take full advantage of it.

So, what’s the plan?

We start by setting our sending chunk size to 50 MiB. Next, we initialize a currentChunkSize variable to 0 and create a new buffer object, allocating exactly 50 MiB of memory.

Now, here’s where it gets interesting. Since we’re using fixed-size buffers, we need to ensure that all the JSON data fits perfectly within the allocated space. To do this, we calculate the available space in the current sending chunk. As long as the JSON chunk fits within the remaining space, we copy it to the sending chunk and update the currentChunkSize:

chunk.copy(sendingChunk, currentChunkSize);
currentChunkSize += chunk.byteLength;

The copy() method copies the bytes from the chunk buffer into sendingChunk, starting at the currentChunkSize (which marks the first free byte in the buffer).

What if the available space is larger than the JSON chunk?

This is where things get a bit messy! In this case, we need to extract exactly the right number of bytes from the JSON chunk to fill the available space in the sending chunk. Once it’s perfectly full, we send the chunk to the HTTP response.

After that, we reset the sendingChunk to a fresh buffer and set currentChunkSize back to 0.

But what about the rest of the JSON chunk?

Good question! Any remaining data in the JSON chunk is processed in the next iteration of our loop. The loop ensures that this remaining data is added to the new sendingChunk. This loop continues as long as the JSON chunk is larger than the available space in the buffer.

Technically, we could set the buffer size to send chunks as small as 1 byte to the response stream, but that would be incredibly inefficient. So, to avoid unnecessary iterations in the while loop, it’s important to set a reasonable chunk size.

Demo

For the demo, let's git clone the project here. After cloning, install the dependencies using npm install, and then run the project with npm run start.

On the index page, you’ll find a tutorial that explains how to call each version in action, as shown in the screenshot below:

Conclusion

By leveraging the power of Node.js streams, we can deliver files of virtually any size without consuming large amounts of memory. Whether you're aiming for simplicity, performance, or handling large buffer sizes, these approaches have you covered.

I hope this guide helped you understand how to work with large file downloads in NestJS. Have any ideas or topics you'd like me to cover next? Drop a comment! And don’t forget to subscribe to my newsletter on rabbitbyte.club for more tips!

Part 3/3: How to Implement Refresh Tokens through Http-Only Cookie in NestJS and React

zenstok — Mon, 02 Sep 2024 06:45:11 +0000

Hello everyone,

Welcome to the final episode of our three-part series on token management in a NestJS + React application. In the first two posts, we walked through the process of implementing refresh token logic by storing tokens in local storage. Today, we’ll advance to a more secure method by implementing HTTP-only cookies for refresh tokens.

Why Use HTTP-Only Cookies?

HTTP-only cookies allow us to store sensitive data, such as refresh tokens, in a way that cannot be accessed by JavaScript. This means that even if there are vulnerabilities in your code or third-party libraries, a hacker won't be able to retrieve the refresh token.

However, even with HTTP-only cookies, there's still a risk of requests being made on behalf of the user through XSS attacks. The key advantage is that hackers will not be able to access the value of the refresh token directly; they would need to execute targeted XSS attacks on the application's endpoints, which requires prior knowledge of the system.

Why Not Store Both Access and Refresh Tokens in HTTP-Only Cookies?

By keeping the access token out of cookies, we protect against CSRF (Cross-Site Request Forgery) attacks. To mitigate XSS attacks, we set a short expiry time on the access token, limiting the damage even if it’s compromised.

Should We Worry About CSRF on the /refresh-tokens Endpoint?

Not really. Since this endpoint doesn’t compromise the system or user data, CSRF attacks here are less of a concern.

Enhancing Security: Hashing Refresh Tokens

To further improve security, we also hash the refresh tokens in the database. We use a hashing algorithm without salt, allowing us to reproduce the same hash for previously used tokens to check if they have been blacklisted. With this improvement, in case of database leaks, the hacker will not be able to read any refresh tokens!

Getting Started

To begin, ensure you've completed the guides in Part 1 and Part 2 for app installation. Afterward, follow these steps to implement the necessary changes.

If you want to jump straight into the code, you can check out the repository here on the "part-3" branch.

Step 1: Define Cookie Configuration and Helper Function

First, set up a cookie configuration and create a helper function to extract the refresh token from cookies:

import { Request } from 'express';

export const cookieConfig = {
  refreshToken: {
    name: 'refreshToken',
    options: {
      path: '/', // For production, use '/auth/api/refresh-tokens'. We use '/' for localhost in order to work on Chrome.
      httpOnly: true,
      sameSite: 'strict' as 'strict',
      secure: true,
      maxAge: 1000 * 60 * 60 * 24 * 30, // 30 days; must match Refresh JWT expiration.
    },
  },
};

export const extractRefreshTokenFromCookies = (req: Request) => {
  const cookies = req.headers.cookie?.split('; ');
  if (!cookies?.length) {
    return null;
  }

  const refreshTokenCookie = cookies.find((cookie) =>
    cookie.startsWith(`${cookieConfig.refreshToken.name}=`)
  );

  if (!refreshTokenCookie) {
    return null;
  }

  return refreshTokenCookie.split('=')[1] as string;
};

Step 2: Enable CORS to Accept Cookies

Ensure the CORS policy allows credentials so that our backend can receive cookies from the frontend:

app.enableCors({ origin: true, credentials: true }); // Set the correct origin for production.

Step 3: Update the Token Generation Method

Modify the generateTokenPair method to set the refresh token as an HTTP-only cookie whenever it's called:

async generateTokenPair(
  user: Express.User,
  res: Response,
  currentRefreshToken?: string,
  currentRefreshTokenExpiresAt?: Date,
) {
  const payload = { sub: user.id, role: user.role };

  res.cookie(
    cookieConfig.refreshToken.name,
    await this.generateRefreshToken(
      user,
      currentRefreshToken,
      currentRefreshTokenExpiresAt,
    ),
    {
      ...cookieConfig.refreshToken.options,
    },
  );

  return {
    access_token: this.jwtService.sign(payload), // JWT module is configured in auth.module.ts for access token.
  };
}

Step 4: Update JWT Strategy to Use Cookies

Modify the refresh JWT strategy to retrieve the token from cookies instead of using bearer token authentication:

jwtFromRequest: ExtractJwt.fromExtractors([
  (req: Request) => extractRefreshTokenFromCookies(req),
]),

Step 5: Adjust Token Handling and Add Cookie Clearing Endpoint

When calling the /refresh-tokens endpoint, the token should now be extracted from the HTTP-only cookie, replacing the previous method of using Bearer authorization.

Additionally, we must implement a /clear-auth-cookie endpoint to remove the cookie. This endpoint should be invoked during the logout action on the frontend. The reason for this is that HTTP-only cookies cannot be cleared programatically from the frontend, so this ensures the user is properly logged out.

@Public()
@UseGuards(JwtRefreshAuthGuard)
@Post('refresh-tokens')
refreshTokens(
  @Req() req: Request,
  @Res({ passthrough: true }) res: Response,
) {
  if (!req.user) {
    throw new InternalServerErrorException();
  }

  return this.authRefreshTokenService.generateTokenPair(
    (req.user as any).attributes,
    res,
    extractRefreshTokenFromCookies(req) as string,
    (req.user as any).refreshTokenExpiresAt,
  );
}

@Public()
@Post('clear-auth-cookie')
clearAuthCookie(@Res({ passthrough: true }) res: Response) {
  res.clearCookie(cookieConfig.refreshToken.name);
}

Step 6: Update Frontend Logic

Now regarding the frontend project, we will actually simplify the logic a little bit.

Remove Refresh Token from Local Storage:

Clear any references to the refresh token in the AuthClientStore class:

const ACCESS_TOKEN_KEY = "rabbit.byte.club.access.token";

class AuthClientStore {
  static getAccessToken() {
    return localStorage.getItem(ACCESS_TOKEN_KEY);
  }

  static setAccessToken(token: string) {
    localStorage.setItem(ACCESS_TOKEN_KEY, token);
  }

  static removeAccessToken(): void {
    localStorage.removeItem(ACCESS_TOKEN_KEY);
  }
}

export default AuthClientStore;

Update Request Methods:

Remove the refreshToken variable from the sendProtectedRequest method, as it's no longer needed.

const sendProtectedRequest = (
  method: ApiMethod,
  path: string,
  // eslint-disable-next-line
  body?: any,
  init?: RequestInit,
) => {
  const authToken = AuthClientStore.getAccessToken();
  if (!authToken) {
    throw new Error("No auth token found");
  }

  return sendRequest(method, path, body, authToken, init);
};

Include Credentials in Requests:

Very important: Update the login and refresh token API integration methods to include credentials, ensuring that cookies can be set and sent correctly.

  const login = async (email: string, password: string) => {
    const response = await sendRequest(
      ApiMethod.POST,
      routes.auth.login,
      {
        email,
        password,
      },
      undefined,
      { credentials: "include" }, // Required update
    );

    AuthClientStore.setAccessToken(response.access_token);

    return response;
  };

  const refreshTokens = async () => {
    clearTimeout(timeout);
    if (!debouncedPromise) {
      debouncedPromise = new Promise((resolve, reject) => {
        debouncedResolve = resolve;
        debouncedReject = reject;
      });
    }

    timeout = setTimeout(() => {
      const executeLogic = async () => {
        const response = await sendRequest(
          ApiMethod.POST,
          routes.auth.refreshTokens,
          undefined,
          undefined,
          { credentials: "include" }, // Required update
        );

        AuthClientStore.setAccessToken(response.access_token);
      };

      executeLogic().then(debouncedResolve).catch(debouncedReject);

      debouncedPromise = null;
    }, 200);

    return debouncedPromise;
  };

Define Clear Auth Cookie API Call:

Implement the clearAuthCookie API call:

   const clearAuthCookie = () => {
     return sendRequest(
       ApiMethod.POST,
       routes.auth.clearAuthCookie,
       undefined,
       undefined,
       { credentials: "include" },
     );
   };

Call clearAuthCookie on Logout:

Ensure the auth cookie is cleared on logout:

   const logout = () => {
     AuthClientStore.removeAccessToken();
     return clearAuthCookie();
   };

And that's it! With these steps, the refresh token logic is now integrated into an HTTP-only cookie. You can proceed to Part 2 of the tutorial to test the solution.

If you'd like me to cover more interesting topics about the node.js ecosystem, feel free to leave your suggestions in the comments section. Don't forget to subscribe to my newsletter on rabbitbyte.club for updates!

Part 2/3: How to Integrate Refresh Tokens in React

zenstok — Tue, 30 Jul 2024 07:26:36 +0000

Hello, guys!

On the premise that our App is immune to XSS attacks, we will store both access & refresh tokens in the local storage. For this, we will use React which escapes any values embedded in JSX before rendering them, greatly helping us in countering XSS attacks.

This is the second episode in our three-part series on implementing refresh tokens. In our previous article, we explored how to implement refresh tokens in NestJS. Be sure to check it out if you're looking to easily run the demo from this tutorial.

While storing both access and refresh tokens in local storage is convenient, it does come with security risks. Even with robust XSS attack prevention, there's still a vulnerability to attacks via third-party libraries. Fortunately, in the final episode of this series, we'll demonstrate how to securely store refresh tokens using HTTP-only cookies, which enhances security.

Implementation overview

To keep the application straightforward, we've implemented only the core features necessary to demonstrate the functionality. Here’s what we aim to achieve and some potential caveats to be aware of:

Objectives:

Persistent Authentication: We want the user to remain authenticated even after refreshing the page.
Automatic Logout: The user should be logged out automatically when an API endpoint returns a 401 Unauthorized response.
Seamless Data Access: When calling a protected endpoint, the app should retrieve data if a valid refresh token exists. If the first request returns a 401, the app should attempt to refresh the tokens. Only if the subsequent request after refreshing also fails with a 401 should the user be logged out.

Potential Caveat:

A notable issue is that the refresh token endpoint call invalidates the previous refresh token. This can create a problem if /auth/refresh-tokens is called more than once concurrently, as it may lead to inconsistencies or failures in token handling. To mitigate this, we must ensure that the refresh token is not requested multiple times concurrently, even if multiple protected requests are made across the app.

If you want to jump directly to the GitHub repo to see how we did it, you can check it out here.

Getting started

Since the authentication state is a global concept in the app, we need to ensure that every component can access this state. The best way to manage this is by using React Context to define a global context provider. We will look into this later in the tutorial.

First, we define a class responsible for managing the manipulation of local storage keys for access and refresh tokens:

const ACCESS_TOKEN_KEY = "rabbit.byte.club.access.token";
const REFRESH_TOKEN_KEY = "rabbit.byte.club.refresh.token";

class AuthClientStore {
  static getAccessToken() {
    return localStorage.getItem(ACCESS_TOKEN_KEY);
  }

  static setAccessToken(token: string) {
    localStorage.setItem(ACCESS_TOKEN_KEY, token);
  }

  static removeAccessToken(): void {
    localStorage.removeItem(ACCESS_TOKEN_KEY);
  }

  static getRefreshToken() {
    return localStorage.getItem(REFRESH_TOKEN_KEY);
  }

  static setRefreshToken(token: string) {
    localStorage.setItem(REFRESH_TOKEN_KEY, token);
  }

  static removeRefreshToken(): void {
    localStorage.removeItem(REFRESH_TOKEN_KEY);
  }
}

export default AuthClientStore;

Next, we define a useApi hook, which abstracts how requests are sent to our app server, both protected and unprotected:

import AuthClientStore from "../../auth/client-store/auth-client-store.ts";
import { ApiMethod } from "../types.ts";

const apiUrl = import.meta.env.VITE_API_BASE_URL as string;

const sendRequest = (
  method: ApiMethod,
  path: string,
  // eslint-disable-next-line
  body?: any,
  authToken?: string | null,
  init?: RequestInit,
) => {
  return fetch(apiUrl + path, {
    method,
    ...(body && { body: JSON.stringify(body) }),
    ...init,
    headers: {
      "Content-Type": "application/json",
      ...(authToken && { Authorization: `Bearer ${authToken}` }),
      ...init?.headers,
    },
  }).then((response) => {
    if (response.status >= 400) {
      throw response;
    }
    return response.json();
  });
};

const sendProtectedRequest = (
  method: ApiMethod,
  path: string,
  // eslint-disable-next-line
  body?: any,
  useRefreshToken = false,
  init?: RequestInit,
) => {
  const authToken = useRefreshToken
    ? AuthClientStore.getRefreshToken()
    : AuthClientStore.getAccessToken();
  if (!authToken) {
    throw new Error("No auth token found");
  }

  return sendRequest(method, path, body, authToken, init);
};

export const useApi = () => {
  return { sendRequest, sendProtectedRequest };
};

Please note that the sendProtectedRequest method accepts an optional useRefreshToken parameter. This is used exclusively by routes that refresh the token, as they require the refresh token for bearer authentication. In all other cases, the default behavior is to use the access token.

Now we need to define a useAuthApi hook where the magic happens.

First, we will use useApi hook from which we need to call sendRequest and sendProtectedRequest methods:

export const useAuthApi = () => {
  const { sendRequest, sendProtectedRequest } = useApi();
}

Implementing Authentication: Login, Logout, and Token Refresh

Now, let's define the login function, which, upon successful authentication, will set the access and refresh tokens in the local storage.

export const useAuthApi = () => {
  const { sendRequest, sendProtectedRequest } = useApi();

  const login = async (email: string, password: string) => {
    const response = await sendRequest(ApiMethod.POST, routes.auth.login, {
      email,
      password,
    });

    AuthClientStore.setAccessToken(response.access_token);
    AuthClientStore.setRefreshToken(response.refresh_token);

    return response;
  };
}

Next, the logout function is straightforward: it simply removes the access and refresh tokens from local storage.

export const useAuthApi = () => {
  const { sendRequest, sendProtectedRequest } = useApi();

  const login = async (email: string, password: string) => {
    const response = await sendRequest(ApiMethod.POST, routes.auth.login, {
      email,
      password,
    });

    AuthClientStore.setAccessToken(response.access_token);
    AuthClientStore.setRefreshToken(response.refresh_token);

    return response;
  };

  const logout = () => {
    AuthClientStore.removeAccessToken();
    AuthClientStore.removeRefreshToken();
  };
}

An essential method to define is refreshTokens, which has a simple logic similar to the login function:

const refreshTokens = async () => {
  const response = await sendProtectedRequest(
    ApiMethod.POST,
    routes.auth.refreshTokens,
    undefined,
    AuthClientStore.getRefreshToken(),
  );

  AuthClientStore.setAccessToken(response.access_token);
  AuthClientStore.setRefreshToken(response.refresh_token);
};

Note that because the refresh tokens endpoint requires the refresh token as an authentication method, we pass the refresh token as a parameter to sendProtectedRequest so it uses the refresh token as the bearer instead of the default access token used for other requests.

Is this all we need for the refreshTokens method? Well, keep in mind that each call to refresh the access token will invalidate the previous refresh tokens. So, if two parts of the app concurrently need to refresh the access token, one request might fail because the first request will invalidate the refresh token being used. Therefore, it's crucial to ensure this method is called only once. To manage this logic efficiently, we need to decorate this method a little bit.

Debouncing Refresh Tokens Requests and Managing Authentication State

To handle cases where multiple parts of the app might concurrently call the refresh tokens method, we need to debounce these calls so that only one request is made. We also need to ensure that each caller receives the same access and refresh token pair. Here's how we achieve this:

First, we define some variables outside of the hook to manage the debounce logic:

/*
 * These variables are used to debounce the refreshTokens function
 */
let debouncedPromise: Promise<unknown> | null = null;
let debouncedResolve: (...args: unknown[]) => void;
let debouncedReject: (...args: unknown[]) => void;
let timeout: number;

Now, we update the refreshTokens method to include debouncing:

const refreshTokens = async () => {
  clearTimeout(timeout);
  if (!debouncedPromise) {
    debouncedPromise = new Promise((resolve, reject) => {
      debouncedResolve = resolve;
      debouncedReject = reject;
    });
  }

  timeout = setTimeout(() => {
    const executeLogic = async () => {
      const response = await sendProtectedRequest(
        ApiMethod.POST,
        routes.auth.refreshTokens,
        undefined,
        AuthClientStore.getRefreshToken(),
      );

      AuthClientStore.setAccessToken(response.access_token);
      AuthClientStore.setRefreshToken(response.refresh_token);
    };

    executeLogic().then(debouncedResolve).catch(debouncedReject);

    debouncedPromise = null;
  }, 200);

  return debouncedPromise;
};

Here’s how it works:

We clear the timeout whenever a new caller invokes this method within a 200ms window, effectively debouncing the calls.
The debouncedPromise ensures that all callers receive the same promise, which resolves or rejects when the token refresh logic completes.
After processing, debouncedPromise is reset to handle new calls later.

Next, we define a method that acts as a gatekeeper for protected API routes. It attempts a request and, if it fails with a 401 (Unauthorized) error, refreshes the access token and retries the request:

const sendAuthGuardedRequest = async (
  userIsNotAuthenticatedCallback: () => void,
  method: ApiMethod,
  path: string,
  body?: any,
  init?: RequestInit,
) => {
  try {
    return await sendProtectedRequest(method, path, body, undefined, init);
  } catch (e) {
    if (e?.status === 401) {
      try {
        await refreshTokens();
      } catch (e) {
        userIsNotAuthenticatedCallback();
        throw e;
      }
      return await sendProtectedRequest(method, path, body, undefined, init);
    }

    throw e;
  }
};

The userIsNotAuthenticatedCallback parameter allows the authentication context provider to update the global auth state, which any component in the app can listen to.

Finally, we define a method for checking if the user is authenticated by calling the /auth/me endpoint. This should be executed on app startup:

const me = (userIsNotAuthenticatedCallback: () => void) => {
  return sendAuthGuardedRequest(
    userIsNotAuthenticatedCallback,
    ApiMethod.GET,
    routes.auth.me,
  ) as Promise<User>;
};

Our hook is now complete, this is the full version of it:

/*
 * These variables are used to debounce the refreshTokens function
 */
let debouncedPromise: Promise<unknown> | null;
let debouncedResolve: (...args: unknown[]) => void;
let debouncedReject: (...args: unknown[]) => void;
let timeout: number;

export const useAuthApi = () => {
  const { sendRequest, sendProtectedRequest } = useApi();

  const login = async (email: string, password: string) => {
    const response = await sendRequest(ApiMethod.POST, routes.auth.login, {
      email,
      password,
    });

    AuthClientStore.setAccessToken(response.access_token);
    AuthClientStore.setRefreshToken(response.refresh_token);

    return response;
  };

  const logout = () => {
    AuthClientStore.removeAccessToken();
    AuthClientStore.removeRefreshToken();
  };
  const refreshTokens = async () => {
    clearTimeout(timeout);
    if (!debouncedPromise) {
      debouncedPromise = new Promise((resolve, reject) => {
        debouncedResolve = resolve;
        debouncedReject = reject;
      });
    }

    timeout = setTimeout(() => {
      const executeLogic = async () => {
        const response = await sendProtectedRequest(
          ApiMethod.POST,
          routes.auth.refreshTokens,
          undefined,
          AuthClientStore.getRefreshToken(),
        );

        AuthClientStore.setAccessToken(response.access_token);
        AuthClientStore.setRefreshToken(response.refresh_token);
      };

      executeLogic().then(debouncedResolve).catch(debouncedReject);

      debouncedPromise = null;
    }, 200);

    return debouncedPromise;
  };

  const sendAuthGuardedRequest = async (
    userIsNotAuthenticatedCallback: () => void,
    method: ApiMethod,
    path: string,
    // eslint-disable-next-line
    body?: any,
    init?: RequestInit,
  ) => {
    try {
      return await sendProtectedRequest(method, path, body, undefined, init);
    } catch (e) {
      if (e?.status === 401) {
        try {
          await refreshTokens();
        } catch (e) {
          userIsNotAuthenticatedCallback();
          throw e;
        }
        return await sendProtectedRequest(method, path, body, undefined, init);
      }

      throw e;
    }
  };

  const me = (userIsNotAuthenticatedCallback: () => void) => {
    return sendAuthGuardedRequest(
      userIsNotAuthenticatedCallback,
      ApiMethod.GET,
      routes.auth.me,
    ) as Promise<User>;
  };

  return { login, logout, me, sendAuthGuardedRequest };
};

Implementing the Auth Provider component

Now let's have a look at our auth provider component, responsible with our global auth state.

type ContextType = {
  isAuthenticated: boolean;
  login(email: string, password: string): Promise<void>;
  logout(): void;
  me(): Promise<User>;
  sendAuthGuardedRequest(
    method: ApiMethod,
    path: string,
    // eslint-disable-next-line
    body?: any,
    init?: RequestInit,
  ): Promise<unknown>;
};

const AuthContext = createContext<ContextType | undefined>(undefined);

function AuthProvider({ children }: { children: ReactNode }) {
  const [isAuthenticated, setIsAuthenticated] = useState(false);
  const {
    login: authLogin,
    logout: authLogout,
    me: authMe,
    sendAuthGuardedRequest: authSendAuthGuardedRequest,
  } = useAuthApi();

  const login = async (email: string, password: string) => {
    try {
      await authLogin(email, password);
      setIsAuthenticated(true);
    } catch (e) {
      setIsAuthenticated(false);
      throw e;
    }
  };

  const logout = () => {
    authLogout();
    setIsAuthenticated(false);
  };

  const me = async () => {
    const user = await authMe(() => {
      setIsAuthenticated(false);
    });
    setIsAuthenticated(true);

    return user;
  };

  const sendAuthGuardedRequest = async (
    method: ApiMethod,
    path: string,
    // eslint-disable-next-line
    body?: any,
    init?: RequestInit,
  ) => {
    return authSendAuthGuardedRequest(
      () => {
        setIsAuthenticated(false);
      },
      method,
      path,
      body,
      init,
    );
  };

  return (
    <AuthContext.Provider
      value={{
        isAuthenticated,
        login,
        logout,
        me,
        sendAuthGuardedRequest,
      }}
    >
      {children}
    </AuthContext.Provider>
  );
}

export { AuthProvider, AuthContext };

In this implementation, we’ve essentially wrapped the authentication API hook methods and manage the isAuthenticated state based on API responses. The final method in this component is very important: it is used by all other hooks or components that need to perform protected requests to our API. By incorporating the userIsNotAuthenticated callback, we ensure that when an endpoint call fails due to token expiration, the authentication state is updated. This approach allows the isAuthenticated state to be set to false, prompting all components across the app to adjust their behavior accordingly.

Next, we’ll define a useAuthContext hook to simplify access to the authentication state:

export const useAuthContext = () => {
  const ctx = useContext(AuthContext);

  if (!ctx) {
    throw new Error("useAuthContext must be within AuthProvider");
  }

  return ctx;
};

Wrapping Your App with AuthProvider

Ensure your application is wrapped with the AuthProvider to provide authentication state to all components.

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <AuthProvider>
      <App />
    </AuthProvider>
  </React.StrictMode>,
);

Next, we’ll define a useUserApi hook to handle API methods related to user operations:

export const useUserApi = () => {
  const { sendAuthGuardedRequest } = useAuthContext();

  const findAllUsers = async (
    limit: number,
    offset: number,
  ): Promise<FindAllUsersResponse> => {
    const queryString = buildQueryParams([
      { key: "limit", value: limit.toString() },
      { key: "offset", value: offset.toString() },
    ]);

    return sendAuthGuardedRequest(
      ApiMethod.GET,
      routes.user.findAll + queryString,
    );
  };

  const findOneUser = async (id: number): Promise<User> => {
    return sendAuthGuardedRequest(ApiMethod.GET, routes.user.findOne(id));
  };

  return { findAllUsers, findOneUser };
};

Note how we are using the sendAuthGuardedRequest method from the auth context.

Now, let's take a look at our App component.

function App() {
  const { isAuthenticated, login, logout, me } = useAuthContext();
  const [appIsLoading, setAppIsLoading] = useState(true);

  const { findAllUsers } = useUserApi();

  useEffect(() => {
    me()
      .catch(() => {})
      .finally(() => setAppIsLoading(false));
  }, []);

  if (appIsLoading) {
    return <div>Loading...</div>;
  }

  if (!isAuthenticated) {
    return (
      <form
        style={ display: "flex", flexDirection: "column", gap: 16 }
        onSubmit={(e) => {
          e.preventDefault();
          login(e.target[0].value, e.target[1].value);
        }}
      >
        <div>Authentication</div>
        <input placeholder="Email" />
        <input placeholder="Password" type="password" />
        <button type="submit">Login</button>
      </form>
    );
  }

  return (
    <>
      <div>
        <a href="https://rabbitbyte.club" target="_blank">
          <img
            src={rabitByteClubLogo}
            className="logo"
            alt="logo-rabbit-byte"
          />
        </a>
      </div>
      <h1>Rabbit Byte Club</h1>
      <div style={{ display: "flex", gap: 16 }}>
        <button
          onClick={() => {
            for (let i = 0; i < 5; i++) {
              findAllUsers(10, 0);
            }
          }}
        >
          Simulate 5 concurrent requests
        </button>
        <button onClick={() => logout()}>Logout</button>
      </div>
    </>
  );
}

export default App;

We define an appLoading state, which is set to false once the /auth/me endpoint completes, regardless of success or failure. While the user is not authenticated, we display the login form.

If the user is authenticated, a button is provided to simulate 5 concurrent requests, allowing you to test the logic easily in the demo.

DEMO

Prerequisites:

To test the feature quickly and easily, set the JWT access token expiration to 10 seconds in your backend application:

JwtModule.registerAsync({
  inject: [ConfigService],
  useFactory: (configService: ConfigService<EnvironmentVariables>) => ({
    secret: configService.get('jwtSecret'),
    signOptions: { expiresIn: '10s' },
  }),
}),

Set the JWT refresh token expiration to 30 seconds:

    const newRefreshToken = this.jwtService.sign(
      { sub: authUserId },
      {
        secret: this.configService.get('jwtRefreshSecret'),
        expiresIn: '30s',
      },
    );

Additionally, you may want to temporarily disable throttling on the refresh tokens endpoint:

// @Throttle({
//   short: { limit: 1, ttl: 1000 },
//   long: { limit: 2, ttl: 60000 },
// })
@ApiBearerAuth()
@Public()
@UseGuards(JwtRefreshAuthGuard)
@Post('refresh-tokens')
refreshTokens(@Request() req: ExpressRequest) {
  if (!req.user) {
    throw new InternalServerErrorException();
  }
  return this.authRefreshTokenService.generateTokenPair(
    (req.user as any).attributes,
    req.headers.authorization?.split(' ')[1],
    (req.user as any).refreshTokenExpiresAt,
  );
}

Steps to Run the Demo:

Clone the Github Project:

   git clone https://github.com/zenstok/react-auth-refresh-token-example

Install dependencies:

   npm install

Run the App:

   npm run dev

Ensure Backend is Running:

Navigate to the backend directory and run:

   yarn dc up

Fill in users in the database if needed:

In a new terminal in backend directory run:

   yarn dc-db-init

Log In:

Enter the following credentials on the login screen:

Email: admin@admin.com
Password: 1234

Test Functionality:

After logging in, you will see two buttons: Simulate 5 Concurrent Requests and Log Out.

Open your browser's Network tab.
Click Simulate 5 Concurrent Requests.

You will see the effect of the refresh token logic in action.

The app will wait for a single call to the refresh tokens endpoint and then rerun the requests. Success!

Verification of Objectives:

Persistent Authentication: Refresh the page and ensure you remain authenticated. ✅
Automatic Logout: Log in and wait for more than 30 seconds. After pressing Simulate 5 Concurrent Requests, confirm that you are logged out. ✅

Seamless Data Access: When calling a protected endpoint, the app should return data if a valid refresh token exists. ✅

Conclusion

I hope this tutorial has been helpful in your journey to implement refresh tokens in React. Stay tuned for the final episode of this series, where we'll swap the backend and frontend logic to use HTTP-only cookies for the refresh token.

Post Creation:
Check out Part 3 of this series, where we update the app to use HTTP-only cookies for refresh tokens.

Part 1/3: How to Implement Refresh Tokens with Token Rotation in NestJS

zenstok — Thu, 06 Jun 2024 08:27:20 +0000

In this episode, we will learn how to implement refresh tokens using local storage as a strategy for storing both access and refresh tokens. If you want to jump directly to the GitHub repo, you can access it here.

Prerequisites

Before diving into this guide, it's important to have some experience with NestJS and the implementation of Passport strategies in NestJS. If you're not familiar with these topics, please visit the following articles from the NestJS documentation:

Passport Integration

Why Do We Use Refresh Tokens?

Even though we use HTTPS to encrypt network traffic, there are additional steps we can take to prevent malicious users from stealing access tokens through methods like social engineering or library hacks. Refresh tokens allow a user to stay logged in for a long time without needing to log in again, provided they are active users. We can log them out after a set period, such as six months, if they have been inactive.

Why use refresh tokens instead of a single access token with a long or no expiration date? Because we want to counter token theft with short-lived access tokens, so attackers are likely to obtain expired tokens. Additionally, refresh tokens can provide a way to revoke user access without resetting the JWT signing key and logging out all users.

Implementation Overview

When we log in for the first time, we receive a token pair that includes an access token and a refresh token. As the access token approaches expiration, we can obtain a new token pair by requesting a new set of tokens from our authentication server. The server will provide the new token pair only if the refresh token is provided.

Why do you think I mentioned receiving a new token pair consisting of both access token and refresh token? If I have the refresh token with a long expiration date, wouldn't it have been sufficient to just get a new access token? Well, storing the refresh token with long expiration date invalidates the logic that hackers obtain short-lived tokens that are likely to be expired. Furthermore, this approach eliminates the possibility of implementing the 'permanently logged in' users feature, even if they are active. So, what we do is when we request a new token pair, we immediately invalidate the previous refresh token through a mechanism called refresh token rotation.

Refresh Token Rotation

Refresh token rotation operates by generating a blacklist which will "force invalidate" previously used refresh tokens. When a new token pair is requested, we utilize a refresh token and then include this used refresh token in our blacklist. This means that if a hacker gains control of a refresh token, it will already be invalid if the user has refreshed their token pair.

But what if the hacker gets a fresh, valid refresh token? You've got two options: if you spot the hack right away, though that's unlikely, you can quickly get a new token pair to make the hacker's refresh token worthless. If the hacker uses your refresh token and it's marked invalid, there's not much you can do. They might have access to your app indefinitely until you change the JWT signing key. To stop this, we can store the refresh token in an HTTP-only cookie and guard against CSRF attacks. That way, even if your app has XSS vulnerabilities, the hacker can't read the refresh token. If you're interested in an article about storing refresh tokens in HTTP-only cookies, leave a comment, and I'll get right on it.

Getting Started

For this article, we'll focus on the core logic and keep the app simple.

Clone the project from GitHub and start the Docker containers:

yarn dc up

Pre-fill your database with two users:

yarn dc-db-init

Access Swagger at localhost:3000/docs to log in. For the admin user, use:
Email: admin@admin.com
Password: 1234

Our app allows refreshing the token pair by calling the /refresh-tokens endpoint. When called with a refresh token as bearer auth, it invalidates the previous token. Try calling the endpoint twice with the same token to see the 401 Unauthorized error on the second call.

The core logic is in the authentication module. We have three guards:

Local Auth Guard: For initial authentication with email and password.
JWT Auth Guard: Protects all app routes globally, defined as an APP_GUARD in app.module.ts, uses access token for validation.
JWT Refresh Auth Guard: Guards the /refresh-tokens endpoint, uses refresh token for validation.

The critical aspect here is the interaction between access tokens and refresh tokens, so I'll skip discussing the local auth guard. For the JWT auth guard, we utilize the JWT strategy from the 'passport-jwt' package.

In the following section, we define how to extract the JWT from the request and the JWT signature key, which we set in the environment. In the validate method, we receive the payload of the JWT, which we use to retrieve the user ID and verify if the user exists in the database before granting access if true.

export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor(
    private userService: UserService,
    configService: ConfigService<EnvironmentVariables>,
  ) {
    super({
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      ignoreExpiration: false,
      secretOrKey: configService.get('jwtSecret'),
    });
  }

  async validate(payload: any): Promise<User | null> {
    const authUser = await this.userService.findOne(payload.sub);
    if (!authUser) {
      throw new UnauthorizedException();
    }
    return authUser;
  }
}

Similarly, for the JWT refresh auth guard, we employ the same JWT strategy from the 'passport-jwt' package. The distinction here from the JWT strategy file is that we utilize a different secret key for JWT token generation, and we return both the user attributes and the refresh token expiration date. This expiration date becomes necessary later in the process.

@Injectable()
export class JwtRefreshStrategy extends PassportStrategy(Strategy, 'jwt-refresh') {
  constructor(
    private userService: UserService,
    configService: ConfigService<EnvironmentVariables>,
  ) {
    super({
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      ignoreExpiration: false,
      secretOrKey: configService.get('jwtRefreshSecret'),
    });
  }

  async validate(payload: any) {
    const authUser = await this.userService.findOne(payload.sub);
    if (!authUser) {
      throw new UnauthorizedException();
    }
    return {
      attributes: authUser,
      refreshTokenExpiresAt: new Date(payload.exp * 1000),
    };
  }
}

In the authentication.controller's login method, we observe that we call the login method, which, in turn, invokes the generateTokenPair from our AuthRefreshTokenService. It's important to note that we also implement a throttle mechanism to limit the number of requests on the login route, thereby preventing brute force attacks, with a maximum of 2 requests per second and a maximum of 5 login attempts per 60 seconds.

@Throttle({ short: { limit: 2, ttl: 1000 }, long: { limit: 5, ttl: 60000 } })
@ApiBody({ type: UserLoginDto })
@Public()
@UseGuards(LocalAuthGuard)
@Post('login')
login(@Request() req: any) {
  return this.authenticationService.login(req.user);
}

From within authentication service:

login(user: User) {
  return this.authRefreshTokenService.generateTokenPair(user);
}

The auth.refresh.token.service.ts looks like this:

export class AuthRefreshTokenService {
  constructor(
    private jwtService: JwtService,
    private configService: ConfigService<EnvironmentVariables>,
    @InjectRepository(AuthRefreshToken)
    private authRefreshTokenRepository: Repository<AuthRefreshToken>,
  ) {}

  async generateRefreshToken(authUserId: number, currentRefreshToken?: string, currentRefreshTokenExpiresAt?: Date) {
    const newRefreshToken = this.jwtService.sign(
      { sub: authUserId },
      { secret: this.configService.get('jwtRefreshSecret'), expiresIn: '30d' },
    );

    if (currentRefreshToken && currentRefreshTokenExpiresAt) {
      if (await this.isRefreshTokenBlackListed(currentRefreshToken, authUserId)) {
        throw new UnauthorizedException('Invalid refresh token.');
      }

      await this.authRefreshTokenRepository.insert({
        refreshToken: currentRefreshToken,
        expiresAt: currentRefreshTokenExpiresAt,
        userId: authUserId,
      });
    }

    return newRefreshToken;
  }

  private isRefreshTokenBlackListed(refreshToken: string, userId: number) {
    return this.authRefreshTokenRepository.existsBy({ refreshToken, userId });
  }

  async generateTokenPair(user: User, currentRefreshToken?: string, currentRefreshTokenExpiresAt?: Date) {
    const payload = { email: user.email, sub: user.id };
    return {
      access_token: this.jwtService.sign(payload),
      refresh_token: await this.generateRefreshToken(user.id, currentRefreshToken, currentRefreshTokenExpiresAt),
    };
  }

  @Cron(CronExpression.EVERY_DAY_AT_6AM)
  async clearExpiredRefreshTokens() {
    await this.authRefreshTokenRepository.delete({ expiresAt: LessThanOrEqual(new Date()) });
  }
}

Looking at generateRefreshToken method, we generate a new refresh token with a 30-days expiration. If we don't receive the optional currentRefreshToken and currentRefreshTokenExpiresAt parameters, we simply return the newly created refresh token, as expected after a successful login.

Examining the refreshTokens method below in the authentication controller, we notice the implementation of a throttle mechanism: a maximum of 1 request per second or 2 requests per 60 seconds. We invoke generateTokenPair with user attributes, the used refresh token, and its expiration date:

@Throttle({
  short: { limit: 1, ttl: 1000 },
  long: { limit: 2, ttl: 60000 },
})
@ApiBearerAuth()
@Public()
@UseGuards(JwtRefreshAuthGuard)
@Post('refresh-tokens')
refreshTokens(@Request() req: ExpressRequest) {
  if (!req.user) {
    throw new InternalServerErrorException();
  }
  return this.authRefreshTokenService.generateTokenPair(
    (req.user as any).attributes,
    req.headers.authorization?.split(' ')[1],
    (req.user as any).refreshTokenExpiresAt,
  );
}

The generateTokenPair method of AuthRefreshTokenService, when invoked with currentRefreshToken and currentRefreshTokenExpiresAt, checks if the current token is blacklisted and throws an error if it's reused. For the first-time usage, it inserts this token into our auth refresh tokens database table, effectively acting as our blacklist.

In the final method of our service, we have a cron job responsible for deleting all refresh tokens whose expiration date has passed, as we no longer need to retain them in the database.

This is part 1 of a 3-episode series. In the next episode, I will show you how to manage access and refresh tokens easily in a React app. In episode 3, we'll delve deeper into storing the refresh token in an HTTP-only cookie instead of local storage. This approach prevents attackers from reading the refresh token, even if your app is vulnerable to XSS attacks.

Post Creation:
Check out Part 2 of this series, where we integrate this backend with a React App.

NestJS Dependency Injection in Worker Threads

zenstok — Mon, 18 Mar 2024 07:16:59 +0000

There may be cases when you need to do CPU-intensive tasks on the backend like big JSON parsing, video encoding, compression, etc. If you have at least 2 cores in your processor's configuration you can run javascript in parallel for these tasks and not block the main thread of the NestJS app that handles client requests.

An excellent way of doing this is by using node.js worker threads.

You shouldn't use worker threads for I/O operations as node.js already gracefully handles this for you.

If you're eager to dive into the complete example right away, you can check out the GitHub repo for the full example.

In order to illustrate this, we will use a very simple service that calculates the fibonacci sum, which is a CPU-intensive task, a great candidate for node.js worker threads!

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

@Injectable()
export class FibonacciService {
  fibonacci(n) {
    if (n <= 1) {
      return 1;
    }
    return this.fibonacci(n - 1) + this.fibonacci(n - 2);
  }
}

Now, let's dive into the code snippet that launches the worker thread:

import { Injectable, Logger } from '@nestjs/common';
import { Worker, isMainThread } from 'worker_threads';
import workerThreadFilePath from './worker-threads/config';

@Injectable()
export class AppService {
  private readonly logger = new Logger(AppService.name);

  checkMainThread() {
    this.logger.debug(
      'Are we on the main thread here?',
      isMainThread ? 'Yes.' : 'No.',
    );
  }

  // do not run this from the worker thread or you will spawn an infinite number of threads in cascade
  runWorker(fibonacci: number): string {
    this.checkMainThread();

    const thisService = this;
    const worker = new Worker(workerThreadFilePath, {
      workerData: fibonacci,
    });
    worker.on('message', (fibonacciSum) => {
      thisService.logger.verbose('Calculated sum', fibonacciSum);
    });
    worker.on('error', (e) => console.log('on error', e));
    worker.on('exit', (code) => console.log('on exit', code));

    return 'Processing the fibonacci sum... Check NestJS app console for the result.';
  }
}

As we can see from the snippet above, we defined a new worker, gave it a path to a file to be executed by the worker, and gave it as param the workerData. Worker data is data sent from the main thread to the other thread.

We are using the constant workerThreadFilePath from associated config file on the same level in the directory tree so we can safely use the path for the worker thread regardless of where the app is deployed.

// it will import the compiled js file from dist directory
const workerThreadFilePath = __dirname + '/findFibonacciSum.js';

export default workerThreadFilePath;

Take a note that we are using the js extension here because the transpiled output of typescript, as we know, it's javascript.

Let's explore the file which will be executed in the worker thread:

import { NestFactory } from '@nestjs/core';
import { workerData, parentPort } from 'worker_threads';
import { AppModule } from '../app.module';
import { FibonacciService } from '../fibonacci/fibonacci.service';
import { AppService } from '../app.service';

async function run() {
  const app = await NestFactory.createApplicationContext(AppModule);
  const appService = app.get(AppService);
  const fibonacciService = app.get(FibonacciService);

  const fibonacciNumber: number = workerData; // this is data received from main thread


  // here we apply business logic inside the worker thread
  appService.checkMainThread();
  const fibonacciSum = fibonacciService.fibonacci(fibonacciNumber);
  parentPort.postMessage(fibonacciSum);
}

run();

In order to have access to dependency injection in our NestJs app in the thread, we leverage Nest standalone application which is a wrapper around the Nest IoC container, which holds all instantiated classes.

Now, we can execute any method from any service.

Caveats:

Be cautious when using dependency injection from NestJS in a worker thread, as it comes with a cost. The startup process of the NestJS app must be awaited before accessing the dependency injection. Therefore, utilize this method only if absolutely necessary, or if the startup bottleneck is negligible in terms of overall performance.
If your app setup is starting processes that you don't want to run on the separate thread you will need to configure your app module into a dynamic module to accept a parameter to not initiate the setup. Example:

const app = await NestFactory.createApplicationContext(
  AppModule.register({ attachRabbitMqConsumers: false }),
);

Click here for the github repo.

Part 3/3: How to deploy a production app to Kubernetes (GKE)

zenstok — Wed, 13 Sep 2023 10:36:49 +0000

Introduction:
This blog post is the final installment of a three-part series dedicated to scaling a NestJS chat app to handle millions of users. In the first two episodes, we discussed the scaling process and demonstrated how to deploy it locally using Docker and Minikube. However, in this final episode, our focus shifts to deploying the app in a production environment on Google Kubernetes Engine (GKE). If you want to jump directly to a working solution, you can check out the deploy-on-gke branch of the GitHub repository here.

While it is recommended to read the previous episodes for a comprehensive understanding of the scaling process, this post can also serve as a standalone guide specifically for deploying the app to GKE in a production-ready manner. By the end of this episode, you will possess all the necessary tools and knowledge to successfully deploy your NestJS chat app on GKE, ready to handle high user loads.

Section 1: Prerequisites
Before diving into the deployment process, ensure you have the following prerequisites in place:

A Google Cloud account.
The Google Cloud SDK installed on your local machine (you can find installation instructions here).
Basic familiarity with Docker and Kubernetes concepts.

Section 2: Creating a GKE Cluster
The first step is to set up a GKE cluster, which will serve as the runtime environment for your application. Here are the steps:

Create a new Google Cloud project through the GUI and ensure billing is activated.

Enable the Kubernetes Engine API for the newly created project (billing should be activated).

Switch to the Google Cloud CLI and authenticate using the command gcloud auth login.
Make sure your active project with billing activated is set to the correct one by running gcloud config set project <YOUR-PROJECT-ID>.
Create a Kubernetes cluster using the command gcloud container clusters create scale-chat-app-cluster.

This process may take a little time. Afterward, create a static external IP address, which is needed to make your app accessible over the internet:

gcloud compute addresses create tutorial-ip --global

Check the details of the newly created IP address:

gcloud compute addresses describe --global tutorial-ip

Now, update your DNS records for your chosen domain to point to this IP address.

Section 3: Containerizing Your Application
To deploy your application to Kubernetes, it must be packaged into a container image. For this tutorial, we've already published the Docker image on Docker Hub as a public image here. Docker Hub serves as a container registry from which your Kubernetes app will retrieve the container image. If you want to use a private image, you can do so. If you're interested in learning how to publish your own image, you can follow a Docker tutorial here.

Section 4: Defining Kubernetes Deployment and Service YAML
In this section, we'll delve into the Kubernetes Deployment and Service YAML files. These files define how your application should be deployed and exposed. We'll discuss key parameters and provide examples to help you create your own YAML files.

To start, use the Kubernetes YAML files from the previous tutorial. What you'll need to add:
- A GKE Ingress Controller. An ingress controller receives and load-balances traffic from outside Kubernetes to pods running in a Kubernetes cluster.
- A default backend for this Ingress. Any requests that don't match the paths in the rules field are sent to the Service and port specified in the defaultBackend field. We will have an Ingress with no rules so that all requests are sent to this default backend.
- Annotations for the Ingress to capture the IP address set above.
- A managed certificate service where we will define the domains we own so that the app can point to that domain and have SSL.
- A frontend config that will automatically redirect all requests to HTTPS.
- A readiness probe configuration in our deployment config to inform GKE about pod health (for this, you will also need to implement a health route, which is a route that always returns a 200 status on GET).

The ingress config looks like this:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: backend-ingress
  annotations:
    kubernetes.io/ingress.global-static-ip-name: tutorial-ip
    networking.gke.io/managed-certificates: managed-cert
    kubernetes.io/ingress.class: "gce"
    networking.gke.io/v1beta1.FrontendConfig: ssl-redirect
  labels:
    app: backend
spec:
  defaultBackend:
    service:
      name: backend-service
      port:
        number: 3000

The backend config looks like this:

apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  name: my-backendconfig
spec:
  timeoutSec: 120

The backend service should be annotated with your backend config:

apiVersion: v1
kind: Service
metadata:
  name: backend-service
  labels:
    app: backend
  annotations:
    cloud.google.com/backend-config: '{"ports": {"3000":"my-backendconfig"}}'

The frontend config looks like this:

apiVersion: networking.gke.io/v1beta1
kind: FrontendConfig
metadata:
  name: ssl-redirect
spec:
  redirectToHttps:
    enabled: true

The managed certificate looks like this:

apiVersion: networking.gke.io/v1
kind: ManagedCertificate
metadata:
  name: managed-cert
spec:
  domains:
    - subdomain.put-your-domain-here.com

The readiness probe looks like this: (It has to be added in backend-deployment.yaml at spec.template.spec.containers)

          readinessProbe:
            httpGet:
              path: "/health"
              port: 3000
            initialDelaySeconds: 10
            timeoutSeconds: 5

If your Docker image is private, you will need to create a Kubernetes secret to store your Docker private image credentials. However, for the purpose of this tutorial, we will continue using the public image we've used in our previous episodes.

Here's how to create a Kubernetes secret for private Docker images:

kubectl create secret docker-registry regcred \
    --docker-server=https://index.docker.io/v1 \
    --docker-username=<your-name> \
    --docker-password=<your-password> \
    --docker-email=<your-email>

Please note that this example assumes you are using Docker Hub as your registry. If you are using a different Docker registry, make sure to set the --docker-server option accordingly to match your registry's URL.

In your backend-deployment yaml spec (spec.template.spec.imagePullSecrets), you will have to add this secret in order to be able to pull the image:

      imagePullSecrets:
        - name: regcred

Section 5: Deploying Your Application to GKE
Now, it's time to deploy your application to the GKE cluster. Follow these steps:

Ensure you are in the correct Kubernetes context:

kubectl config get-contexts

If necessary, switch to the appropriate context:

kubectl config use-context <YOUR-CONTEXT-NAME>

Run the following command in your project directory:

kubectl apply -f k8s

You will need to wait for the Google-managed certificate to finish provisioning, which may take up to 60 minutes. You can check the status of the certificate using this command:

kubectl describe managedcertificate managed-cert

Section 6: Scaling and Managing Your Application
Kubernetes

GKE offers powerful scaling and management capabilities. For example, you can update the number of replicas or resources used per pod.

Add a resources variable to the containers in backend-deployment.yaml: (make sure the cluster has sufficient resources)

resources:
  limits:
    cpu: "2000m"    # Maximum CPU limit
    memory: "4Gi"   # Maximum memory limit
  requests:
    cpu: "1000m"    # Minimum CPU request
    memory: "1Gi"   # Minimum memory request

Section 7: Conclusion
In conclusion, Kubernetes GKE offers a scalable and reliable environment for deploying applications. Throughout this blog post, we've explored the essential configuration options necessary to successfully deploy your application in a production-ready environment.

If you wish to support me in creating high-quality articles about various complex software concepts, please subscribe to my newsletter on Rabbit Byte Club. It's a new project I'm starting with the aim of improving software product quality worldwide.

Part 2/3: Deploy Scalable NestJs Chat App to Kubernetes

zenstok — Thu, 15 Jun 2023 23:33:24 +0000

In our previous blog post, we explored how to write a scalable NestJS chat app using a distributed architecture and WebSockets for real-time communication. Building upon that, we will now dive deeper into improving the app's efficiency and deploying it on Kubernetes using minikube. If you're eager to check out the source code, you can find it in the GitHub repository here (make sure you check out on improved-version+deploy-on-kubernetes branch). Additionally, if you find this post useful, let me know in the comments, and I'll create another tutorial focusing on deploying a production app with Google Kubernetes Engine (GKE). This tutorial will cover essential features like configuring a static IP, associating a domain name, obtaining a TLS certificate for secure communication, and setting up a load balancer for distributing traffic between instances.

Improving the Previous Model

In the previous post, we stored an array of connected clients in each instance and triggered events to notify all instances about new messages. In this paradigm, we broadcast messages to all instances regardless if they have associated ws clients which needs to receive the message or not. To enhance this model and optimize the broadcasting process, we can leverage Redis. Here's how we can achieve this improvement:

Consolidating Redis Channels:
Instead of having three channels for different types of messages (send to all, send to many, send to one), we will use a single global channel for broadcasting global messages (send to all). Additionally, we will dynamically create user-specific channels in the format: ws_socket_client/{USER_ID}. Each instance that holds WebSocket clients will basically subscribe to these channels. This helps optimize the broadcasting process and ensures that messages are only sent to the relevant instances with the corresponding clients.
Implementation Changes:
To implement this change, we need to listen for WebSocket connect and disconnect events and subscribe/unsubscribe the Redis client to each client's respective channel. Here are the code changes:

In the constructor, we now subscribe only to the channel for sending messages to all clients:

this.subscriberRedis.subscribe(this.sendWsMessageToAllClientsRedisChannel);

Create a new private method to generate the user-specific channel name:

private getClientIdRedisChannel(userId: string) {
  return `${this.wsSocketClientRedisChannel}/${userId}`;
}

Subscribe to the user-specific channel in the addConnection method:

this.subscriberRedis.subscribe(this.getClientIdRedisChannel(userId));

Unsubscribe from the user-specific channel in the removeConnection method:

this.subscriberRedis.unsubscribe(this.getClientIdRedisChannel(client.userId));

Update the subscriber client to listen to the global channel for sending messages to all clients, as well as the user-specific channels:

this.subscriberRedis.on('message', (channel, message) => {
  const data = JSON.parse(message) as RedisPubSubMessage;
  if (data.from !== this.redisClientId) {
    switch (true) {
      case channel === this.sendWsMessageToAllClientsRedisChannel:
        this.sendMessageToAllClients(data.message, false);
        break;
      case channel.startsWith(this.wsSocketClientRedisChannel):
        this.sendMessageToClient(
          (data as RedisPubSubMessageWithClientId).clientId,
          data.message,
          false,
        );
        break;
      // no default
    }
  }
});

You will also notice that on this branch, I updated the chat gateway class, now it has 3 types of messages it subscribes to:

enum SubscribeMessageType {
  SendChatMessageToOneParticipant = 'send_chat_message_to_one_participant',
  SendChatMessageToManyParticipants = 'send_chat_message_to_many_participants',
  SendChatMessageToAllParticipant = 'send_chat_message_to_all_participants',
}

In order to test it in the browser, you can follow the previous tutorial where I discussed how to set up the database and how to obtain bearer tokens for authenticated users.
Also, the content of the websocket message should follow the format of our DTO classes so it can be received correctly:

export class SendMessageToAllDto {
  @IsString()
  @Length(1, 5000)
  message: string;
}

export class SendMessageToManyDto extends SendMessageToAllDto {
  @IsArray()
  @IsUUID(undefined, { each: true })
  participantIds: string[];
}

export class SendMessageToOneDto extends SendMessageToAllDto {
  @IsUUID()
  participantId: string;
}

For example if you want to send multiple messages you can use something like this in the browser:

users.forEach(user => ws.send(JSON.stringify({event: 'send_chat_message_to_one_participant', data: {message: 'test', participantId: user.id}})));

To test this improvement, connect and disconnect multiple clients in the browser and observe the behavior in the Docker console.

Deploying the Stack on Minikube

To deploy the chat app on Minikube for local development and testing, follow these steps:

Install Minikube by referring to the official tutorial at
https://kubernetes.io/docs/tasks/tools/.
Once Minikube is installed, start the Minikube cluster using the command:
```
minikube start
```
Inside the k8s directory, you'll find the deployment files for the backend, Redis, and PostgreSQL, along with the corresponding services and volumes. We have set up environment variables within the backend deployment to ensure connectivity with Redis and PostgreSQL. The deployment is configured with five replicas to create a total of five backend pods. To test the deployment locally, the backend service is set as a node port, allowing it to be exposed to your local machine.
To deploy the app, navigate to the project directory and run the following command:
```
kubectl apply -f k8s
```
This will set up the entire app along with its dependencies. Please note that we are using the zenstok/scalable-chat-app-example-backend image, which is built from the improved-version+deploy-on-kubernetes branch available at https://github.com/zenstok/nestjs-scalable-chat-app-example.
Initiate database inside kubernetes

Find a backend pod name:
```
kubectl get pods
```
Access a shell inside a backend pod:
```
kubectl exec -it backend-deployment-7ddd9c4769-fxqxg -- sh
```
Run db init command:
```
yarn db-init
```
If you want to port-forward kubernetes db to inspect it, you can do so by running:
```
kubectl port-forward deployment/postgres-deployment 5432:5432
```
To access the deployed service locally, expose it using the command:
```
minikube service backend-service
```
Interact with the deployed app locally and verify its behavior.

You will get something like this in the console:

It will start a tunnel for backend-service which can be accessed locally at this address (beware that the port might be different on your machine):
```
http://127.0.0.1:61939
```
Now you can interact with the app exactly as you interacted with the docker configured app.
For example, to access swagger docs, you just hit this in the browser:
```
http://127.0.0.1:61939/docs
```
Also, if you want to inspect the logs from all backend pods, you can do so by running:
```
kubectl logs -l app=backend -f
```
Once you have finished testing, clean up the Minikube cluster by deleting it:
```
minikube delete
```

In this blog post, we explored how to enhance the scalability of a NestJS chat app by leveraging Redis and implementing user-specific channels. By optimizing the broadcasting process, we reduced networking costs and improved overall efficiency. Additionally, we learned how to deploy the app on Kubernetes using Minikube for local development and testing.

Your feedback and comments are highly appreciated, so please share your thoughts and experiences. Stay tuned for new posts!

Part 1/3: How to Scale a Chat App to Millions of Users in NestJS

zenstok — Mon, 29 May 2023 11:31:00 +0000

Hello, in this guide, I will teach you how to scale a NestJS app to millions of users.

Prerequisites:

Experience with JavaScript.
Experience with NestJS.
Experience as a backend engineer.

Access the GitHub repository for this project here.

To scale your app, you will need to scale horizontally by creating multiple instances of your NestJS app.

Each instance of your app should have the following features:

WebSocket integrations that keep track of connected clients through websockets in a singleton memory array. (this is done by default when using nestjs, reference: Injection Scopes)
A Redis database publisher that announces new requests received by all other instances and a subscriber that listents to these requests. This is necessary because a client may send a request to one instance (e.g., instance number 3) and be registered as a websocket client there. However, the client may then send a request to another instance because you will have a load balancer installed (e.g., instance number 32), triggering a websocket chat notification. Unfortunately, this instance does not have the connected client in its singleton memory array. To handle this, the instance needs to announce the request to all other instances through Redis. The other instances can then look up their array of connected clients and notify them if a match is found.

Here's how you can achieve this:

Install websockets in your NestJS app. Follow the official NestJS guide. If you'd like to quickly jump out and see the GitHub repo for the full example, you can find it here.
Create the WebSocket client manager service (explained below).

After setting up websockets in your app, we need to define an entrypoint gateway for websockets.

@WebSocketGateway({ path: '/entrypoint' })
export class EntrypointGateway {}

Then, create a new lifecycle gateway that extends this entrypoint. This lifecycle gateway contains the logic to insert clients into the WebSocket client manager.

@Injectable()
export class LifecycleGateway
  extends EntrypointGateway
  implements OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect
{
  private readonly logger = new Logger(LifecycleGateway.name);

  constructor(
    private readonly jwtService: JwtService,
    private readonly wsClientManager: WsClientManager,
  ) {
    super();
  }

  afterInit() {
    this.logger.debug('Websockets initialized ' + this.constructor.name);
  }

  handleConnection(client: any) {
    const authUserTokenData = this.getDecodedAuthToken(client);

    if (!authUserTokenData) {
      client.close();
      return;
    }

    this.wsClientManager.addConnection(client, authUserTokenData);
  }

  handleDisconnect(client: any) {
    this.wsClientManager.removeConnection(client);
  }

  getDecodedAuthToken(client: any) {
    let decodedJwt: DecodedAuthToken | null = null;

    try {
      if (client.protocol) {
        decodedJwt = this.jwtService.verify(client.protocol, {
          secret: jwtConstants.secret,
        }) as DecodedAuthToken;
      }
    } catch (e) {}

    return decodedJwt;
  }
}

To inject the Redis connection into our app, we utilize @liaoliaots/nestjs-redis package with the following yarn command:

 yarn add @liaoliaots/nestjs-redis

Moving forward, we will add the Redis module configuration for subscriber and publisher channels.

RedisModule.forRootAsync({
  inject: [ConfigService],
  useFactory: async (config: ConfigService) => ({
    config: [
      {
        namespace: 'subscriber',
        host: config.get('REDIS_HOST'),
        port: config.get('REDIS_PORT'),
      },
      {
        namespace: 'publisher',
        host: config.get('REDIS_HOST'),
        port: config.get('REDIS_PORT'),
      },
    ],
  }),
}),

In the WebSocket client manager, you will find the following:

We generate a random Redis client using the crypto module's randomUUID from the official Node.js package.

Each NestJS app instance subscribes to the three Redis channels we defined:

SendWsMessageToAllClients
SendWsMessageToSomeClients
SendWsMessageToOneClient

When a NestJS instance receives a message, it first checks that the publisher is not the same as the subscriber. Then, it proceeds to send the message. However, this time, we set the shouldPublishToRedis parameter to false to avoid an infinite loop. The received message will be sent by each instance if it finds the clients in its singleton memory array.

This approach also handles cases where a single user uses the app through multiple devices simultaneously (e.g., PC, mobile app). The user will receive chat notifications on all devices because, upon inspecting the code, you will notice that we are utilizing a map object. For every user ID, we store all associated WebSocket connected clients.

@Injectable()
export class WsClientManager {
  private readonly connectedClients = new Map<string, any[]>();
  private readonly redisClientId = `ws_socket_client-${crypto.randomUUID()}`;

  constructor(
    @InjectRedis('subscriber') private readonly subscriberRedis: Redis,
    @InjectRedis('publisher') private readonly publisherRedis: Redis,
  ) {
    this.subscriberRedis.subscribe(
      RedisSubscribeChannel.SendWsMessageToAllClients,
    );
    this.subscriberRedis.subscribe(
      RedisSubscribeChannel.SendWsMessageToSomeClients,
    );
    this.subscriberRedis.subscribe(
      RedisSubscribeChannel.SendWsMessageToOneClient,
    );

    this.subscriberRedis.on('message', (channel, message) => {
      const data = JSON.parse(message) as RedisPubSubMessage;
      if (data.from !== this.redisClientId) {
        switch (channel) {
          case RedisSubscribeChannel.SendWsMessageToAllClients:
            this.sendMessageToAllClients(data.message, false);
            break;
          case RedisSubscribeChannel.SendWsMessageToSomeClients:
            this.sendMessageToClients(
              (data as RedisPubSubMessageWithClientIds).clientIds,
              data.message,
              false,
            );
            break;
          case RedisSubscribeChannel.SendWsMessageToOneClient:
            this.sendMessageToClient(
              (data as RedisPubSubMessageWithClientId).clientId,
              data.message,
              false,
            );
            break;
        }
      }
    });
  }

  addConnection(client: any, authUserTokenData: DecodedAuthToken) {
    const userId = authUserTokenData.sub;

    this.setUserIdOnClient(client, userId);
    const clientsPool = this.getClientsPool(client);
    this.connectedClients.set(
      userId,
      clientsPool ? [...clientsPool, client] : [client],
    );

    setTimeout(() => {
      client.close(); // This will trigger removeConnection from the LifecycleGateway's handleDisconnect
    }, this.getConnectionLimit(authUserTokenData));
  }

  removeConnection(client: any) {
    const clientsPool = this.getClientsPool(client);
    const newPool = clientsPool!.filter((c) => c !== client);

    if (!newPool.length) {
      this.connectedClients.delete(client.userId);
    } else {
      this.connectedClients.set(client.userId, newPool);
    }
  }

  private setUserIdOnClient(client: any, userId: string) {
    client.userId = userId;
  }

  private getClientsPool(client: any) {
    return this.connectedClients.get(client.userId);
  }

  private getConnectionLimit(tokenData: DecodedAuthToken) {
    return tokenData.exp * 1000 - Date.now();
  }

  getConnectedClientIds() {
    const clientIds: string[] = [];

    const iterator = this.connectedClients.keys();
    let current = iterator.next();
    while (!current.done)

 {
      clientIds.push(current.value);
      current = iterator.next();
    }

    return clientIds;
  }

  sendMessageToClient(
    clientId: string,
    message: string,
    shouldPublishToRedis = true,
  ) {
    if (shouldPublishToRedis) {
      this.publisherRedis.publish(
        RedisSubscribeChannel.SendWsMessageToOneClient,
        JSON.stringify({
          message,
          clientId,
          from: this.redisClientId,
        }),
      );
    }

    const clientPool = this.connectedClients.get(clientId);

    if (clientPool) {
      clientPool.forEach((client) => {
        client.send(message);
      });
    }
  }

  sendMessageToClients(
    clientIds: string[],
    message: string,
    shouldPublishToRedis = true,
  ) {
    if (shouldPublishToRedis) {
      this.publisherRedis.publish(
        RedisSubscribeChannel.SendWsMessageToSomeClients,
        JSON.stringify({
          message,
          clientIds,
          from: this.redisClientId,
        }),
      );
    }

    this.connectedClients.forEach((clientPool, clientId) => {
      if (clientIds.includes(clientId)) {
        clientPool.forEach((client) => {
          client.send(message);
        });
      }
    });
  }

  sendMessageToAllClients(message: string, shouldPublishToRedis = true) {
    if (shouldPublishToRedis) {
      this.publisherRedis.publish(
        RedisSubscribeChannel.SendWsMessageToAllClients,
        JSON.stringify({
          message,
          from: this.redisClientId,
        }),
      );
    }

    this.connectedClients.forEach((clientPool) => {
      clientPool.forEach((client) => {
        client.send(message);
      });
    });
  }
}

Now it's time to test our app. First, clone the project. Make sure you have Docker installed.

This is the Dockerfile for our NestJS app (represents a single instance):

Dockerfile:

FROM node:18.13.0-alpine AS development

WORKDIR /usr/src/app
COPY package.json ./
COPY yarn.lock ./

RUN yarn install --frozen-lockfile \
&& yarn cache clean

COPY . .

RUN yarn build

CMD yarn install; yarn start:debug;

In the docker-compose file, we use our backend image generated from the Dockerfile above. We also have an Nginx server to act as a load balancer between app instances, Postgres as the database, and Redis as the centralized database used for communication between app instances. In this example, we simulate the presence of five NestJS app instances.

docker-compose.yml:

version: '3.7'

services:
  backend:
    image: scalable-chat-app-example-backend
    build:
      context: ./../
      dockerfile: ./docker/Dockerfile
      target: development
    volumes:
      - ./../:/usr/src/app
      - scalable-chat-app-example-backend-node-modules:/usr/src/app/node_modules
      - scalable-chat-app-example-backend-dist:/usr/src/app/dist
    ports:
      - '3000'
    networks:
      - mainnet
    depends_on:
      - postgres
      - redis
    restart: unless-stopped
    scale: 5

  nginx:
    container_name: scalable-chat-app-example-nginx-load-balancer
    image: nginx:latest
    volumes:
      - ./../nginx.conf:/etc/nginx/nginx.conf
    depends_on:
      - backend
    networks:
      - mainnet
    ports:
      - '3000:3000'

  postgres:
    container_name: scalable-chat-app-example-postgres-db
    image: postgres:15.0
    networks:
      - mainnet
    environment:
      TZ: ${DB_TIMEZONE}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: ${DB_NAME}
      PG_DATA: /var/lib/postgresql/data
    ports:
      - '5432:5432'
    volumes:
      - scalable-chat-app-example-pgdata:/var/lib/postgresql/data

  redis:
    container_name: scalable-chat-app-example-redis-db
    image: redis:7.0.7
    networks:
      - mainnet
    expose:
      - '6379'
    volumes:
      - scalable-chat-app-example-redisdata:/data

networks:
  mainnet:

volumes:
  scalable-chat-app-example-pgdata:
  scalable-chat-app-example-backend-node-modules:
  scalable-chat-app-example-backend-dist:
  scalable-chat-app-example-redisdata:

We also need the following Nginx configuration to handle WebSocket connections:

nginx.conf:

user nginx;
events {

    worker_connections 1000;
}
http {

    upstream app {

        server scalable-chat-app-example-backend-1:3000;
        server scalable-chat-app-example-backend-2:3000;
        server scalable-chat-app-example-backend-3:3000;
        server scalable-chat-app-example-backend-4:3000;
        server scalable-chat-app-example-backend-5:3000;
    }

    server {

        listen 3000;
        location / {

            proxy_pass http://app;
            # WebSocket support
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $http_connection;

        }
        client_max_body_size 1000M;
    }
}

To set up the example, navigate to the repository directory and execute the following three commands:

Copy sample.env:

cp sample.env .env

Run containers:

yarn dc up

Initiate docker database:

yarn dc-db-init

If you want to clean the project you can run the following command:

yarn dc-clean

Your database has 5 users initiated:

Each one of them has 1234 as password.

Open swagger at http://localhost:3000/docs.

Open as many browser tabs as you want and write the following code in each of them:

const ws = new WebSocket('ws://localhost:3000/entrypoint', 'introduceHereBearerTokenFromAuthLogin')

Check out your users table from docker database and extract them as a json so you can use the array of users in the browser.

Now, type the following in any browser window:

 users.forEach(user => ws.send(JSON.stringify({event: 'send_chat_message_to_participant', data: {message: 'test', participantId: user.id}})));

This will send individual chat message to all participants. You can also check docker logs to see it in action.

Regardless of which NestJS instance grabs the WebSocket connection, the messages are consistently sent to participants. This is how you scale a NestJS chat app to millions of users.

If you are interested in learning how to deploy this stack on Kubernetes, leave a comment and i will do the tutorial.

If you want to collaborate on potential start-up projects, you can reach me at: rares.tarabega27@gmail.com

Post Creation:
If you want to check out an improved and more efficient model for broadcasting messages between instances, as well as how to deploy this stack on Kubernetes, you can find Part 2 of this series here.

DEV Community: zenstok

🎬 M3U8 to MP4 — The Easiest Way to Convert Videos, Instantly & Privately

🚀 Introducing: Instant M3U8 to MP4 Conversion

Here’s why it hits different:

🔒 Privacy-First, No Exceptions

📦 Got a .zip of the playlist files instead of a link?

How to Avoid the Single-Threaded Trap in JavaScript

Why This Is a Bad Approach:

The Good Approach:

Why This Is a Good Approach:

Demo Instructions

Clone the Repository:

Install the Necessary Dependencies:

Run the Application:

Simulate requests:

Conclusion: Avoiding JavaScript's Single-Threaded Pitfalls

Introducing Rabbit Byte Club Discord Community

How to Create and Download Files of Unlimited Size in node.js/NestJS

The Scenario: A Manager's Report Download

Why Not Buffers?

What are streams?

Let’s break it down with an example:

The Three Methods to Stream Large Files in NestJS

1. The Easy Version

What’s happening here?

2. The Performant Version: String-Based Chunks

So, what do we have here?

3. The Buffer Version: Chunking with Buffers

What if the available space is larger than the JSON chunk?

But what about the rest of the JSON chunk?

Demo

Conclusion

Part 3/3: How to Implement Refresh Tokens through Http-Only Cookie in NestJS and React

Why Use HTTP-Only Cookies?

Why Not Store Both Access and Refresh Tokens in HTTP-Only Cookies?

Should We Worry About CSRF on the /refresh-tokens Endpoint?

Enhancing Security: Hashing Refresh Tokens

Getting Started

Step 1: Define Cookie Configuration and Helper Function

Step 2: Enable CORS to Accept Cookies

Step 3: Update the Token Generation Method

Step 4: Update JWT Strategy to Use Cookies

Step 5: Adjust Token Handling and Add Cookie Clearing Endpoint

Step 6: Update Frontend Logic

Part 2/3: How to Integrate Refresh Tokens in React

Implementation overview

Objectives:

Potential Caveat:

Getting started

Implementing Authentication: Login, Logout, and Token Refresh

Debouncing Refresh Tokens Requests and Managing Authentication State

Implementing the Auth Provider component

Wrapping Your App with AuthProvider

DEMO

Conclusion

Part 1/3: How to Implement Refresh Tokens with Token Rotation in NestJS

Prerequisites

Why Do We Use Refresh Tokens?

Implementation Overview

Refresh Token Rotation

Getting Started

NestJS Dependency Injection in Worker Threads

Part 3/3: How to deploy a production app to Kubernetes (GKE)

Part 2/3: Deploy Scalable NestJs Chat App to Kubernetes

Improving the Previous Model

Deploying the Stack on Minikube

Part 1/3: How to Scale a Chat App to Millions of Users in NestJS

📦 Got a `.zip` of the playlist files instead of a link?