DEV Community: Hayatudeen Abdulrahman

API Testing 101: A Beginner's Guide to Testing Nodejs APIs with Jest and Supertest

Hayatudeen Abdulrahman — Fri, 28 Jul 2023 17:28:50 +0000

Software testing
- What is API testing?
- Importance of API testing
Types of Testing
- Unit testing
- Integration testing
Testing frameworks and libraries
Express server setup
Testing the book API with Jest and Supertest
Conclusion

In today’s fast-paced software development world, testing is becoming an essential part of the software development life cycle, and with the increasing rise of web and mobile applications, bug-free, reliable, and efficient APIs are crucial to meeting various business needs.

This guide will provide a starting point for Node.js developers who want to understand the fundamentals of testing and writing API tests for backend applications using Jest and Supertest.

We will cover topics like software testing, types of testing, testing frameworks, and a step-by-step walk-through of a sample test code for a basic create, read, update, and delete (CRUD) operations API.

To follow the guide completely, you’re required to know the fundamentals of building an API with Node.js as well as any Node.js framework (e.g., Express.js, Nest.js, etc.). However, you can follow the first few sections before the code section with little-to-no knowledge of backend development.

Software testing

Firstly, let us know what software testing is before proceeding to understand API testing. According to a post on IBM, software testing is the process of evaluating and verifying that a software product or application does what it is supposed to do. It involves providing edge cases to test that the application works as expected.

What is API testing?

It’s simply a form of software testing that evaluates and verifies that an API functions as expected. It is done to test the API’s security, performance, and reliability. It generally involves simulating a request to the API endpoints to test that the responses match the expected results.

Importance of API testing

According to a survey conducted by SmartBear in 2020, 90% of organizations said they either currently have or plan to have a formal API testing process in place in the near future. This highlights the importance of API testing and the shift towards it.

A 2020 survey by smartBear illustrating the importance of API testing in business organizations.

The following are more benefits of API testing:

It ensures that the API returns correct responses every time.
It helps to identify security vulnerabilities to prevent the API from being compromised by attackers.
It allows for detailed and accurate documentation of the API.
It can help identify performance issues.
It helps to deliver a high-quality API with fewer bugs.

Types of Testing

There are many types of testing, but we will be looking at the two most common types of testing for backend developers.

Unit testing

Unit testing is a type of testing that focuses on testing individual components of a codebase. In API development, unit testing is used to test individual routes, middlewares, or functions without considering their interaction with other components of the system like databases, caching systems, internal services, or other external services.

Integration testing

Integration testing is a type of testing that tests logically grouped modules together. It also focuses on testing the interaction between different components or services of an application. In API development, integration testing is used to test the interaction between the API’s routes, databases, middlewares, or functions with each other as well as other internal or external services.

Testing frameworks and libraries

Testing frameworks and libraries are software applications or packages that are used to perform testing in software development. There are several testing tools and libraries for different purposes and programming languages. However, the common testing frameworks and libraries for Node.js applications and APIs are listed below:

Jest
Supertest
Mocha
Superagent

Let’s take a look at what Jest and Supertest do.

Jest: Jest is a testing framework or tool that is used to write tests for any JavaScript codebase, including Node.js projects. It’s easy to use, well-documented, has little-to-no configuration, and can be customized to meet one’s needs.

Supertest: Supertest is a testing library that is used to test Node.js APIs. It is best used along with a testing framework like Jest or Mocha.

In the next sections, we’ll be looking at how to use Jest and Supertest to test a Node.js (Express) API.

Express server setup

In this section, we’ll be developing a book API that allows for creating, retrieving, updating, and deleting books from a database.

NB: The code in this section was created only to demonstrate the basic concepts of testing an API and is, by no means, an example of how a modern web API or test should be made or structured.

Before we proceed, make sure you have Node.js installed on your machine.

Follow the steps below to set up an Express server:

Firstly, create a new directory for the book API and open it in your preferred editor.
Navigate to the directory in your terminal and run npm init -y to initialize a new Node.js project.
In your terminal, run npm install express mongoose to install the express and mongoose packages.
Now, create a new file named server.js and add the following code to it:

const express = require('express');
const mongoose = require('mongoose');

// Create a schema for your data
const bookSchema = new mongoose.Schema({
  title: String,
  author: String,
  genre: String
});

// Create a model based on the schema
const Book = mongoose.model('Book', bookSchema);

// Create an Express app
const app = express();
app.use(express.json());

app.get('/', (req, res) => {
  res.json({ text: 'Server started on port 3001' })
})

// Create a new book
app.post('/books', (req, res) => {
  const { title, author, genre } = req.body;
  const book = new Book({
    title,
    author,
    genre
  });

  book.save().then((result) => {
    res.json(result);
  }).catch((error) => {
    res.status(500).json({ error: 'Error creating book' });
  });
});

// Get all books
app.get('/books', (req, res) => {
  Book.find().then((books) => {
    res.json(books);
  }).catch((error) => {
    res.status(500).json({ error: 'Error retrieving books' });
  });
});

// Get a single book by ID
app.get('/books/:id', (req, res) => {
  const { id } = req.params;

  Book.findById(id).then((book) => {
    if (book) {
      res.json(book);
    } else {
      res.status(404).json({ error: 'Book not found' });
    }
  }).catch((error) => {
    res.status(500).json({ error: 'Error retrieving book' });
  });
});

// Update a book by ID
app.put('/books/:id', (req, res) => {
  const { id } = req.params;
  const { title, author, genre } = req.body;

  Book.findByIdAndUpdate(id, {
    title,
    author,
    genre
  }, { new: true }).then((book) => {
    if (book) {
      res.json(book);
    } else {
      res.status(404).json({ error: 'Book not found' });
    }
  }).catch((error) => {
    res.status(500).json({ error: 'Error updating book' });
  });
});

// Delete a book by ID
app.delete('/books/:id', (req, res) => {
  const { id } = req.params;

  Book.findByIdAndRemove(id).then((book) => {
    if (book) {
      res.json(book);
    } else {
      res.status(404).json({ error: 'Book not found' });
    }
  }).catch((error) => {
    res.status(500).json({ error: 'Error deleting book' });
  });
});

// Start the server
const server = app.listen(3001, async () => {
  console.log('Server started on port 3001');
  await mongoose.connect('mongodb+srv://technical-guide:uQxSkFkzgx29r3E8@test-cluster.ne5tsho.mongodb.net/book-api?retryWrites=true&w=majority', {
    useNewUrlParser: true,
    useUnifiedTopology: true
  });
});

module.exports = server;

Save the file, return to your terminal, and run node server.js. You should have something like this:

We’ve successfully created a basic CRUD API with Express.js and MongoDB.

Since this guide is mainly focused on testing, I will briefly explain what the above API does without being too detailed.

The book API allows users to interact with a collection of books. It establishes a connection to a MongoDB database and defines a schema for the book data. Users can create a new book by sending a POST request with the book's details, retrieve all books with a GET request, fetch a specific book by its ID using a GET request with the corresponding book ID, update a book's information by sending a PUT request with the updated details and the book's ID, and delete a book by its ID using a DELETE request. And the server runs on port 3000.

Testing the book API with Jest and Supertest

To start testing the book API with Jest and Supertest, we would need to first download the two packages by navigating to the project’s directory and then running npm install --save-dev jest and npm install --save-dev supertest. The --save-dev flag is used to install the packages as development dependencies.

Next, create a file named server.test.js. This is where our test code will live. We’re saving the file with a file extension of test.js because Jest recognizes files with this extension as test files.

Now, copy the code below into the server.test.js file (the explanation comes briefly).

const request = require('supertest');
const app = require('./server');
const mongoose = require('mongoose');

describe('Book API Endpoints', () => {
  let bookId;

  afterAll((done) => {
    app.close(done);
    mongoose.disconnect();
  });

  it('should create a new book', async () => {
    const res = await request(app)
      .post('/books')
      .send({
        title: 'Test Book',
        author: 'Test Author',
        genre: 'Test Genre',
      });

    expect(res.statusCode).toEqual(200);
    expect(res.body.title).toEqual('Test Book');
    expect(res.body.author).toEqual('Test Author');
    expect(res.body.genre).toEqual('Test Genre');
    bookId = res.body._id;
  });

  it('should get all books', async () => {
    const res = await request(app).get('/books');
    expect(res.statusCode).toEqual(200);
    expect(Array.isArray(res.body)).toBeTruthy();
  });

  it('should get a single book by ID', async () => {
    const res = await request(app).get(`/books/${bookId}`);
    expect(res.statusCode).toEqual(200);
    expect(res.body.title).toEqual('Test Book');
    expect(res.body.author).toEqual('Test Author');
    expect(res.body.genre).toEqual('Test Genre');
  });

  it('should update a book', async () => {
    const res = await request(app)
      .put(`/books/${bookId}`)
      .send({
        title: 'Updated Book',
        author: 'Updated Author',
        genre: 'Updated Genre',
      });
    expect(res.statusCode).toEqual(200);
    expect(res.body.title).toEqual('Updated Book');
    expect(res.body.author).toEqual('Updated Author');
    expect(res.body.genre).toEqual('Updated Genre');
  });

  it('should delete a book', async () => {
    const res = await request(app).delete(`/books/${bookId}`);
    expect(res.statusCode).toEqual(200);
    expect(res.body.title).toEqual('Updated Book');
    expect(res.body.author).toEqual('Updated Author');
    expect(res.body.genre).toEqual('Updated Genre');
  });
});

Let's go through the test code.

We import the necessary modules, including request, a Supertest method that allows you to interact with your server as if it were running and receiving real HTTP requests. We’re also importing app from our server.js file and mongoose for database operations.

The Jest describe function is used to group related test cases. In this case, all the test cases are related to the Book API endpoints.

The afterAll hook provided by Jest is used to close the server and disconnect from the MongoDB database after all the test cases in the test suite are executed. This ensures that we clean up resources after testing; otherwise, Jest wouldn’t exit after the test completes.

Each test case is represented by an it block, which contains the test name and the test code.

The test cases use Supertest to make HTTP requests to the API endpoints and check the responses against the expected results using the expect function.

In the first test case, we create a new book by sending a POST request to the /books endpoint and checking if the response status code is 200 (OK) and if the response body contains the correct book information.

We save the bookId from the response for later use in other test cases.

In the second test case, we fetch the book that we created in the previous test case. We do this by sending a GET request to the endpoint /books/:id, where :id is the bookId of the book we created in the first test case.

In the third test case, we update the book's information. We do this by sending a PUT request to the /books/:id endpoint with the updated book data. Again, we use the bookId variable we saved in the first test case to target the specific book we created earlier.

In the fourth test case, we delete the book that we created in the first test case. We do this by sending a DELETE request to the /books/:id endpoint, using the bookId variable to target the specific book.

Now, we have everything set up to run the tests for our Book API. To do that, we need to add a test script to the package.json file:

"scripts": {
    "test": "jest --testTimeout 20000"
},

In the "scripts" section of the package.json file, we add a "test" script that runs Jest with a test timeout of 20,000 milliseconds (20 seconds). The test timeout is essential to allow enough time for the API tests to complete because they involve interactions with the database.

To run the tests, open your terminal and run the following command:

npm test

Jest will execute the test cases in the server.test.js file, and you should see the test results in the terminal.

Hurray. The test passed. Congratulations on writing your first test!

Conclusion

In conclusion, this beginner's guide has provided you with a solid starting point for understanding API testing and how to test Node.js APIs using Jest and Supertest. To further enhance your skills, I encourage you to explore additional resources available online, including the official documentation for Jest and Supertest. Also, Practising with various testing scenarios will help you gain confidence and expertise in API testing, making you a more proficient developer in today's software development landscape.

Socket.IO Authentication System With JWT

Hayatudeen Abdulrahman — Thu, 08 Jun 2023 20:19:43 +0000

Overview
The Authentication System
- Database Model
- Express Authentication Handlers
- Socket Server Setup
Client-Side Connection
Conclusion

There are few resources to explore when it comes to authenticating socket.io connections. I recently finished a programming project that involved authenticating socket connections. During the project, I tried my best to search for resources that explained how to create an authentication system for socket.io connections, but to no avail. They were either not useful for my project's use case or were unclear. With some effort, I was able to build a secure authentication system for the server so that every connecting client will be authenticated before a connection is established.

In this article, I will be taking you through the step-by-step process of building a secure socket.io authentication system with JSON web tokens (JWT). The knowledge can also be transferred to other authentication libraries, like passport.js or other programming languages' authentication libraries, as I will be using NodeJs.

Let's dive in!

Overview

I will be explaining every detail of the example codes to let everyone follow along regardless of the tech stacks they are familiar with.

However, we will build the authentication system using a MongoDB User collection, an http server, an Express app, and a socket.io server instance. Additionally, I will provide a sample client-side code to demonstrate its use case.

The User collection is used to store and retrieve the users' credentials.

The http server is used to listen to HTTP and socket connection requests.

The express app is used to set up function handlers that handle the registration and log-in authentication endpoints. A response containing a JSON web token (JWT) is expected on successful authentication.

The socket.io server instance is responsible for managing socket connection events. A middleware function is utilized to validate the JWT sent by the client, ensuring that only authenticated users make socket connection requests.

The client-side code is used to make HTTP requests to the authentication endpoints and stores the JWT response, which is then used to make web socket connection requests to the socket.io server instance.

The Authentication System

In this section, we build the authentication system. From the database model to the socket.io server instance authentication middleware setup.

Database Model

Let's start by creating the User model schema.

const mongoose = require('mongoose');

const userSchema = new mongoose.Schema({
    username: String,
    email: String,
    password: String,
  });

const User = mongoose.model('User', userSchema);

module.exports = User;

We import the mongoose module, which provides the functionality to define and interact with MongoDB schemas and models.

A userSchema is created using the mongoose.Schema constructor, specifying the structure and data types of the user object. The schema includes fields for username, email, and password, each of type String.

The userSchema is then used to create a User model. This model allows for interaction with the 'User' collection in the connected MongoDB database.

Finally, the User model is exported to make it available for use in the authentication system.

Express Authentication Handlers

Here, we'll be creating the handler functions for the registration and log-in endpoints using Express.

First of all, let's import the necessary modules.

const express = require('express');
const bcrypt = require('bcrypt');
const jwt = require('jsonwebtoken');
const User = require("models/user.model");

In the code above, the express, bcrypt, and jsonwebtoken module are all being assigned to their respective variables. Additionally, the User database model is imported to enable the storage and verification of user information.

Next, we create the Express app.

const app = express();
app.use(express.json());

// Register API endpoint
app.post('/auth/register', registerUser);

// Login API endpoint
app.post('/auth/login', loginUser);

We begin by invoking the express() function provided by the express module, which allows us to register endpoints along with their respective handler functions. Additionally, we attach the express.json() middleware to parse JSON request payloads. Two POST methods are subsequently added to the Express app, enabling it to handle client requests at the /auth/register and /auth/login endpoints. These requests are handled by the registerUser and loginUser handler functions, respectively.

Next, we proceed to develop the logic for the registerUser handler function.

// User Registration Handler Function
async function registerUser(req, res) {
  try {
    const { username, email, password } = req.body;

    // Check if the username or email already exists
    const existingUser = await User.findOne().or([{ username }, { email }]);
    if (existingUser) {
      return res.status(400).json({ message: 'Username or email already exists' });
    }

    // Hash the password
    const hashedPassword = await bcrypt.hash(password, 10);

    // Create a new user
    const newUser = new User({
      username,
      email,
      password: hashedPassword,
    });

    // Save the user to the database
    await newUser.save();
    res.status(201).json({ message: 'Registration successful' });
  } catch (error) {
    console.error('Registration error', error);
    res.status(500).json({ message: 'Registration error' });
  }
}

We begin by destructuring the username, email, and password from the req.body object, which contains the request body sent by the client. Next, we perform a check for the uniqueness of the email and username by searching for them in the database. If either of them is found, a 400 bad request response is returned. Otherwise, the function proceeds to hash the password using the bcrypt.hash() function provided by the bcrypt module. The hashed password, along with the destructured username and email properties, are then saved to the database for persistence. In the absence of errors, a 201 created response is returned. However, if any error occurs during the execution of the handler function, a 500 internal server error response is returned.

Next, we proceed to develop the logic for the loginUser handler function.

// ...

// User Login Handler Function
async function loginUser(req, res) {
  try {
    const { username, password } = req.body;

    // Check if the username exists
    const user = await User.findOne({ username });
    if (!user) {
      return res.status(400).json({ message: 'Invalid username or password' });
    }

    // Compare the password
    const isPasswordValid = await bcrypt.compare(password, user.password);
    if (!isPasswordValid) {
      return res.status(400).json({ message: 'Invalid username or password' });
    }

    // Generate a JWT
    const token = jwt.sign({ userId: user._id }, process.env.SECRET_KEY);

    res.json({ token, message: 'Login successful' });
  } catch (error) {
    console.error('Login error', error);
    res.status(500).json({ message: 'Login error' });
  }
}

// ...

We first verify if the destructured username exists in the database. If it does not exist, a 400 bad request response is returned. Also, if the destructured password does not match the user-stored password in the database, a 400 bad response is returned. However, if the passwords match, we proceed to generate a JWT token using the jsonwebtoken module. This token is generated by setting the userId key to the value of the _id property of the User, which is automatically assigned by MongoDB to each saved user information. Assuming no errors occur, a response containing the generated token is returned.

Next, we export the Express app.

// ...
module.exports = app;

The complete code for the authentication endpoints can be found below.

const express = require('express');
const bcrypt = require('bcrypt');
const jwt = require('jsonwebtoken');
const User = require("models/user.model");

const app = express();
app.use(express.json());

// Register API endpoint
app.post('/auth/register', registerUser);

// Login API endpoint
app.post('/auth/login', loginUser);

// User Registration Handler Function
async function registerUser(req, res) {
  try {
    const { username, email, password } = req.body;

    // Check if the username or email already exists
    const existingUser = await User.findOne().or([{ username }, { email }]);
    if (existingUser) {
      return res.status(400).json({ message: 'Username or email already exists' });
    }

    // Hash the password
    const hashedPassword = await bcrypt.hash(password, 10);

    // Create a new user
    const newUser = new User({
      username,
      email,
      password: hashedPassword,
    });

    // Save the user to the database
    await newUser.save();
    res.json({ message: 'Registration successful' });
  } catch (error) {
    console.error('Registration error', error);
    res.status(500).json({ message: 'Registration error' });
  }
}

// User Login Handler Function
async function loginUser(req, res) {
  try {
    const { username, password } = req.body;

    // Check if the username exists
    const user = await User.findOne({ username });
    if (!user) {
      return res.status(400).json({ message: 'Invalid username or password' });
    }

    // Compare the password
    const isPasswordValid = await bcrypt.compare(password, user.password);
    if (!isPasswordValid) {
      return res.status(400).json({ message: 'Invalid username or password' });
    }

    // Generate a JWT
    const token = jwt.sign({ userId: user._id }, process.env.SECRET_KEY);

    res.json({ token, message: 'Login successful' });
  } catch (error) {
    console.error('Login error', error);
    res.status(500).json({ message: 'Login error' });
  }
}

module.exports = app;

Our Express app is now ready to be used.

Socket Server Setup

Now, let's set up the http and socket.io server instances for authentication.

const http = require('http');
const ioServer = require('socket.io');
const app = require('./app');

We begin by importing the http and socket.io modules, as well as our Express app.

Next, we proceed to create instances of the http and socket.io servers.

// Create server from express app
const server = http.createServer(app);

// Create the socket server instance
const io = ioServer(server);

We use the createServer() function provided by the http module to create an HTTP server instance. The Express app is then passed to the function to handle requests to the authentication endpoints. The http server is then used to create a socket.io server instance.

Next, we proceed to add the authentication middleware.

io.use(async (socket, next) => {
        try {
            const token = socket.handshake.auth.token;

            // Verify and decode the JWT
            const decoded = jwt.verify(token, process.env.SECRET_KEY);

            // Get the user information from the database
            const user = await User.findById(decoded.userId);
            if (!user) {
                throw new Error('User not found');
            }

            // Attach the user object to the socket
            socket.user = user;
            next();
        } catch (error) {
            console.error('Authentication error', error);
            next(new Error('Authentication error'));
        }
    });

    io.on('connection', (socket) => {
        // Handle Events after authentication
    }

In the above code, when a client connects to the server, the middleware function io.use(), provided by the socket.io library, is invoked. Inside the function, we first retrieve the JWT token from the socket.handshake.auth.token property sent by the client during the handshake (connection). It then verifies and decodes the token using a secret key stored in an environment variable.

If the token is valid, the middleware retrieves the user information from the database based on the user ID extracted from the token. If the user is found, the user object is attached to the socket for future reference.

If any errors occur during the authentication process, such as an invalid token or user not found, an error is thrown, and the middleware calls the next() function with an error argument.

After successful authentication, the io.on('connection') event handler is triggered, allowing for further event handling and communication with the authenticated user.

The authentication system is now complete. But to listen to connections, the code below can be added or customized to your liking.

server.listen(PORT, () => {
    console.log(` Server started running at ${PORT}`);
});

Where PORT is the preferred port to listen to the connections. Also, don't forget to connect to your MongoDB collection before starting the server.

The complete code for the server setup can be found below.

const http = require('http');
const ioServer = require('socket.io');
const app = require('./app');
// Create server from express app
const server = http.createServer(app);

// Create the socket server instance
const io = ioServer(server);

io.use(async (socket, next) => {
        try {
            const token = socket.handshake.auth.token;

            // Verify and decode the JWT
            const decoded = jwt.verify(token, process.env.SECRET_KEY);

            // Get the user information from the database
            const user = await User.findById(decoded.userId);
            if (!user) {
                throw new Error('User not found');
            }

            // Attach the user object to the socket
            socket.user = user;
            next();
        } catch (error) {
            console.error('Authentication error', error);
            next(new Error('Authentication error'));
        }
    });

    io.on('connection', (socket) => {
        // Handle Events after authentication
    }

    server.listen(PORT, () => {
        console.log(` Server started running at ${PORT}`);
    });

Client-Side Connection

To demonstrate how the client-side can be set up to use the authentication system, we'll be using Axios to make requests to the authentication endpoints and use the retrieved token to connect to the socket.io server instance.

Let's start by registering a user.

const axios = require('axios');
const io = require('socket.io-client');

const username = 'HayatsCodes';
const email = 'hayatscodes@gmail.com';
const password = 123456;
let token;

try {
    const response = await axios.post(`http://localhost:${PORT}/auth/register`, {
      username,
      email,
      password,
    });
    console.log(response.data.message); // Registration successful
  } catch (error) {
      console.error(error);
  }

Firstly, the axios and socket.io-client libraries are imported.

Then, we are registering a user by making a POST request to the /auth/register endpoint of the server. The server URL is constructed using the PORT variable, which should contain the port number.

The user's username, email, and password are provided as the request payload. We use the await keyword to make the request and store the response in the response variable.

If the registration is successful, the messsage from the response is logged to the console.

If an error occurs during the registration process, the catch block is executed, and the error is logged to the console using console.error.

Now, let's sign in the registered user.

try {
      const response = await axios.post(`http://localhost:${PORT}/auth/login`, {
        username,
        password,
      });
      token = response.data.token;
      console.log(response.data.message); // login successful
    } catch (error) {
        console.error(error.response.data); 
    }
};

We're signing in the registered user by making a POST request to the /auth/login endpoint of the server while including the username and password in the request payload.

If the login is successful, the token is extracted from the response.data.token property, and the message is logged to the console.

The token is then assigned to the token variable for use in the socket.io client connection.

If an error occurs during the registration process, the catch block is executed, and the error is logged to the console using console.error.

Now let's connect to the socket.io server.

const client = io(`http://localhost:${PORT}`, {
      auth: {
        token
      }
});
// handle events
client.on('connect', () => { console.log('connected!') });
// Additional event handling can follow

In the above code snippet, we're establishing a client-side connection to the socket.io server using the io function provided by the socket.io-client library.

The io function is called with the socket server URL and an object as an argument, which includes the auth property. This property specifies the authentication token that will be sent to the server during the handshake process. The value of the earlier saved token variable from the login request is provided as the token value.

Once the connection is established, the client.on('connect') event handler is set up to listen for the 'connect' event. When the client successfully connects to the server, the callback function is executed, logging 'connected!' to the console.

Additional event handling and communication with the server can be added within the appropriate event handlers.

Conclusion

Building a secure authentication system for socket.io connections can be a challenging task due to the limited resources available. However, by leveraging JSON web tokens (JWT), it is possible to create a robust authentication system. In this article, we have covered the step-by-step process of building such a system, including setting up the database model, creating authentication endpoints with Express, implementing authentication middleware with socket.io, and demonstrating client-side connections using axios and the socket.io-client library. By following the provided code examples and explanations, developers can build their own secure authentication system for socket.io connections, allowing only authenticated users to establish connections and interact with the server.

How I Built a Command-Line Chat Application: Project Reflections

Hayatudeen Abdulrahman — Wed, 07 Jun 2023 22:20:05 +0000

Challenges
Lessons Learned
Contributions and Future Improvements
Project References
- Demo Video
- NPM Registry Link
- GitHub Link
Conclusion

In this article, we will delve into the challenges I encountered while developing the command-line chat application, along with the lessons I learned throughout the process. From the initial stages of structuring the application to tackling authentication issues and creating a user-friendly chat interface, I faced numerous obstacles that tested my problem-solving skills and programming knowledge.

Challenges

I faced several challenges from the idea stage to the deployment of the app. Below I list the major challenges I faced building the app:

App structure: I started building the app with no structure in mind, as I wanted to build fast and organize it later. Eventually, I struggled to organize the app for modularity. But the experience of structuring other backend projects and some little research on the MVC design pattern came in handy. I still think the app isn't well structured, though.
Authentication: This was one of the hardest features I had to implement. With vague documentation and few resources to explore the socket.io library authentication, I had to spend several hours making the authentication feature work as expected. I initially wanted to store the token on the user's machine but found it to be buggy. So I changed my mind and used HTTP requests to store and retrieve the token from the server.
The chat interface's home menu feature: I wanted the user to be able to go back to the home menu from the chat interface. I thought of using the inquirer.js prompts that were being used throughout the application. That was impossible because the readline interface continues to be displayed until it is closed. So I figured out that I could respond to the user's input to go back to the home menu. After that, re-rendering the home menu was also difficult. However, its implementation made the chat message interface code messy, and it also disobeyed the DRY principle.
Railway Redis: I've used Redis in development before but never in production. This project was my first time setting up Redis in production. Since I was deploying on Railway, it was supposed to be easier. But it took time for me to understand how to set up a Redis database, as their documentation wasn't really clear.
Publishing to NPM : Publishing my first NPM package was challenging. With little time before the project submission deadline, I learned how to publish on NPM and named the app terminal-chat-app. However, after installing the app from the NPM registry for manual testing, I realized I forgot to add the node shebang line to the app's node script. After correcting the issue, I encountered a version error while attempting to republish. Not knowing what to do, I deleted the package and got another error that I had to wait 24 hours to publish again. To meet the hackathon deadline, I temporarily changed the package name to tarminal-chat-app. However, I couldn't change the package name again because it now has more than 130 weekly downloads on NPM.

Lessons Learned

It's usually unclear at the beginning: I barely knew command-line and web socket programming before the project, and I was still able to make something out of those unfamiliar tools.
It takes time to build great stuff: I planned to finish the app in a few days, but it took me 2 weeks of debugging, problem-solving, and building to finish the app. Although, if I had known all or most of the technologies used, I would have finished earlier. But I realized that it's not the normal CRUD API that I'm used to building, so it took more time than expected.
The definition of a minimum viable product (MVP): A lot of features came to mind while building the app, but I had to settle for the easiest feature to implement and think of building upon that later. So if the app was a business product, I'd say what I built was the MVP.
Programming Fundamentals help a lot: Knowing some programming fundamentals makes things easier. From recursively calling functions to separating code for modularity, it helped make the project a success.
Build first, refactor later: I started building the app without having any code best practices in mind. It made building faster as I focused on solving the problem at hand rather than writing clean code. I only started refactoring after the app was ready and in good condition.

Contributions and Future Improvements

The project is open source, and everyone is free to contribute to it. Some of the improvements that can be made are:

Restructuring the app files for more modularity
Adding a private chat messaging feature
Adding a group messaging feature by asking for a code before joining
Better error handling
Tests for the client's code
Real-time notifications
Restore 10 or more of the previous messages
and more...

Project References

Conclusion

It was fun and challenging to build yet another project. From learning new and unfamiliar technologies to implementing several features, it was an enlightening and enriching experience. I look forward to building more and more as I search for my first job.

How I Built a Command-Line Chat Application: The Client Code Explained

Hayatudeen Abdulrahman — Wed, 07 Jun 2023 22:17:41 +0000

Client Authentication
- User Registration
- User Login
- User Token
Home Menu
- Creating Chat Rooms
- Joining Chat Rooms
- Exiting the App
User Interface
- Authentication Display Options
- Home Display Options
- Interface Rendering
- Chat Message Interface
The Socket Client and Node Script
- Socket Client Events
- The Node Script

In this section, We'll dive into the client-side code implementation. The chat application provides users with the ability to register, log in, create chat rooms, join existing chat rooms, and exchange messages with other users. We will dissect the client code, examining the authentication logic, user registration and login functionalities, as well as the menu options for creating and joining chat rooms. Additionally, we will explore the user interface rendering and the event handling using the socket.io-client library.

Client Authentication

Starting from the client's /src folder, the /auth folder contains the client's authentication logic. It has three files: registerUser.js, loginUser.js, and getToken.js.

User Registration

// registerUser.js
const { prompt } = require('inquirer');
const axios = require('axios');

const loginUser = require('./loginUser');

const registerUser = async () => {
  const questions = [
    {
      type: 'input',
      name: 'username',
      message: 'Enter your username:',
    },
    {
      type: 'input',
      name: 'email',
      message: 'Enter your email:',
    },
    {
      type: 'password',
      name: 'password',
      message: 'Enter your password:',
    },
  ];

  try {
    const answers = await prompt(questions);
    const { username, email, password } = answers;

    const response = await axios.post('https://terminal-chat-app-production.up.railway.app/auth/register', {
      username,
      email,
      password,
    });

    console.info(response.data.message); // Registration successful
    console.info('-----------------------');
    const token = loginUser(username, password, email);
    return token;
  } catch (error) {
    if ( error.response.data.message === 'Username or email already exists') {
      console.info(error.response.data.message);
      registerUser();
    } else {
      console.error(error.response.data);
    }
  }
};

module.exports = registerUser;

registerUser.js prompts users with a list of questions asking for their details. The answers are then sent in a post request to the server's registration endpoint.

After successful registration, the user is logged in with the registered details (we'll take a look at that in the next heading). A token is then retrieved from the login operation, which is then returned from the function.

Also, if a user enters an existing email or password, they are prompted again to enter their registration details.

User Login

// loginUser.js
const axios = require('axios');
const { prompt } = require('inquirer');

const loginUser = async (username, password, email = null) => {
  if (email) {
    try {
      const response = await axios.post('https://terminal-chat-app-production.up.railway.app/auth/login', {
        username,
        password,
      });

      const token = response.data.token;

      console.log(response.data.message); // login successful
      return token;

    } catch (error) {
      console.error(error.response.data); // login error
    }
  } else {
    const questions = [
      {
        type: 'input',
        name: 'username',
        message: 'Enter your username:',
      },
      {
        type: 'password',
        name: 'password',
        message: 'Enter your password:',
      },
    ];

    try {
      const answers = await prompt(questions);
      const { username, password } = answers;

      const response = await axios.post('https://terminal-chat-app-production.up.railway.app/auth/login', {
        username,
        password,
      });

      const token = response.data.token;
      console.log(response.data.message); // login successful
      return token;
    } catch (error) {
      if (error.response.data.message === 'Invalid username or password') {
        console.info(error.response.data.message);
        loginUser(username, password);
      } else {
        console.error(error.response.data); 
      }
    }
  }
};

module.exports = loginUser;

loginUser.js exports a loginUser function that takes three parameters, with the email parameter initially set to null.

Since the user's email is available during registration, it is used to handle user login immediately after registration. The username and password parameters are then used to quickly make a request to the server's login endpoint.

However, when the email remains null during normal login, the user is prompted to enter their username and password, which are then used to make a request to the server's login endpoint.

The user is also prompted again to enter their login details when invalid credentials are entered.

User Token

// getToken.js
const axios = require('axios');

module.exports = async (username) => {
    try {
        const response = await axios.get(`https://terminal-chat-app-production.up.railway.app/auth/tokens/${username}`);
        const token = response.data
        return token;
    } catch(error) {
        console.error(error.response.data); 
    }

}

getToken.js simply gets the user token with their username from the server's running Redis database.

Home Menu

Next, we move into the /menu folder. It contains the logic for the home menu options. There are three folders in it: createChatRoom.js, joinChatRoom.js, and exitApp.js.

Creating Chat Rooms

// createChatRoom.js
const { prompt } = require('inquirer');
const joinChatRoom = require('./joinChatRoom');
const axios = require('axios');
const question = [
  {
    type: 'input',
    name: 'roomName',
    message: 'Enter Room Name'
  }
]

module.exports = async function createChatRoom(client) {
  try {
    const answer = await prompt(question);
    const roomName = answer.roomName;

    const response = await axios.post('https://terminal-chat-app-production.up.railway.app/api/chatrooms', {
      roomName
    });
    const chatRoom = response.data;
    console.log(`${chatRoom} chat room created`);
    joinChatRoom(client, chatRoom);
    return chatRoom;
  } catch (error) {
    if (error.response.data.message) {
      console.info(error.response.data.message);
      createChatRoom(client); // Recursive call to prompt again
    } else {
      console.error(error);
    }
  }
};

createChatRoom.js exports a function that takes a single parameter, client.

It starts by prompting the user to enter a room name. The room name is then sent in a POST request to the server to store it in the database.

The user then joins the room created by passing client, which is a socket-client instance, and the room name to the joinChatRoom function (which will be explained later). The created chat room is then returned from the function.

If an error occurs, the user is prompted to create the chat room again.

Joining Chat Rooms

// joinChatRoom.js
const { prompt } = require('inquirer');
const axios = require('axios');

module.exports = async function joinChatRoom(client, chatRoom = null) {
    if (chatRoom) {
        client.emit('join', chatRoom);
    } else {
        const response = await axios.get('https://terminal-chat-app-production.up.railway.app/api/chatrooms');
        const chatRooms = response.data;
        const chatRoomsOption = [
            {
                type: 'list',
                name: 'selectedRoom',
                message: 'Choose a Chat Room:',
                choices: chatRooms,
            },
        ]
        const { selectedRoom } = await prompt(chatRoomsOption);
        client.emit('join', selectedRoom);
        return selectedRoom;
    }
}

joinChatRoom.js exports a function that takes two parameters: client, a socket.io-client instance, and chatRoom, which is set to null.

It triggers the join event immediately when the chatRoom is not null. This happens when a user finishes creating a new chat room in createChatRoom.js.

Also, if a user wants to join an existing room, the user is prompted to choose a room from the list of rooms retrieved from the server. The join event is then triggered, with the selected chat room sent to the socket.io server. The selected chat room is then returned from the function.

Exiting the App

// exitApp.js
module.exports = () => {
    console.info('Exited Terminal Chat App Successfully!');
    process.exit(0);
}

exitApp.js exports an anonymous function that simply performs a process termination operation. This terminates the app, and a message is logged on to the user's screen.

User Interface

Into the /views folder, there is the user interface logic. It consists of four files: getAuthOption.js, getMenuOption.js, renderInterface.js, and chatMessageInterface.js.

Authentication Display Options

// getAuthOptions.js
const { prompt } = require('inquirer');

function getAuthOption() {
  const authOptions = [
    {
      type: 'list',
      name: 'selectedOption',
      message: 'Authentication',
      choices: [
        { name: 'Register', value: 'Register', message: 'Create an account' },
        { name: 'Login', value: 'Login', message: 'Login to your account' },
        { name: 'Exit', value: 'Exit', message: 'Exit the App' },
      ]
    },
  ];

  return prompt(authOptions)
    .then(answers => answers.selectedOption);
}

module.exports = getAuthOption;

getAuthOption.js exports a function that prompts users to select an authentication option of either Register, Login, or Exit. It then returns the selected option.

Home Display Options

// getMenuOption.js
const { prompt } = require('inquirer');

function getMenuOption() {
  const menuOptions = [
    {
      type: 'list',
      name: 'selectedOption',
      message: 'Home',
      choices: [
        { name: 'Create-Chat-Room', value: 'Create-Chat-Room', message: 'Create a Chat Room' },
        { name: 'Join-Chat-Room', value: 'Join-Chat-Room', message: 'Join a Chat Room' },
        { name: 'Exit', value: 'Exit', message: 'Exit the App' },
      ]
    },
  ];

  return prompt(menuOptions)
    .then(answers => answers.selectedOption);
}

module.exports = getMenuOption;

getMenuOption.js exports a function that prompts users to select a home menu option of either Create-Chat-Room, Join-Chat-Room, or Exit. It then returns the selected option.

Interface Rendering

// renderInterface.js
const registerUser = require('../auth/registerUser');
const loginUser = require('../auth/loginUser');
const createChatRoom = require('../menu/createChatRoom');
const joinChatRoom = require('../menu/joinChatRoom');
const exitApp = require('../menu/exitApp');

const render = {
    'Register': registerUser,
    'Login': loginUser,
    'Create-Chat-Room': createChatRoom,
    'Join-Chat-Room': joinChatRoom,
    'Exit': exitApp
};

module.exports = render;

renderInterface.js exports a render object that stores the authentication and home menu options functions.

Chat Message Interface

// chatMessageInterface.js
const readline = require('readline');
const io = require('socket.io-client');
const exitApp = require('../menu/exitApp');
const getMenuOption = require('./getMenuOption');
const render = require('./renderInterface');
const getToken = require('../auth/getToken');
const attachEvents = require('../../attachEvents');

function chatMessageInterface(client, chatRoom) {
  console.info('----------------------------------------------');
  console.info('Press -h to go Home.');
  console.info('Press -e to Exit.');
  console.info('----------------------------------------------');

  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout
  });

  let clientUsername;

  // Event listener for the 'username' event
  client.on('username', (username) => {
    clientUsername = username;
  });

  rl.on('line', async (input) => {
    const message = input.trim();
    if (message === '-e') {
      rl.close(); // Close the readline interface
      exitApp();
    } else if (message === '-h') {
      // Check if the clientUsername is defined
      if (!clientUsername) {
        console.log('Waiting for username...');
        return;
      }

      const token = await getToken(clientUsername);
      client.disconnect();

      // create a new client connection
      const newClient = io('https://terminal-chat-app-production.up.railway.app', {
        auth: {
          token
        }
      });

      // Attach events to newClient
      attachEvents(newClient);

      // Display Home menu after successful authentication
      const homeOption = await getMenuOption();

      // Render menu interface according to what the user selects
      const chatRoom = await render[homeOption](newClient);

      // Start chat room messaging
      chatMessageInterface(newClient, chatRoom);
    }
    client.emit('chat message', chatRoom, message);
  });
}

module.exports = chatMessageInterface;

chatMessageInterface.js exports a function that takes two parameters: client, a socket.io-client instance, and chatRoom, the room where the chat is taking place.

It starts by logging some navigation information onto the user's terminal. It then creates a readline interface that allows for user inputs to be read.

The client listens for the username event and stores it in a clientUsername variable for later use.

The readline interface then listens for the line event which is triggered when a user enters a command-line input. The input is stored in a message variable, and this determines the next operation.

Next, the exitApp function is called when the message is -e.

If the message is -h, the client token is retrieved from the server before the client is disconnected from the socket.io server.

A new client connection is then created with the retrieved token to make sure the user is authenticated to create and join chat rooms. The other functions in the else if block will be explained later in the heading " The Node Script".

Also, if the message is neither -e nor -h, the chat message event is triggered and is used to send messages to other users in the chat room.

The Socket Client and Node Script

At the root of the client folder, there contains attachEvents.js, which attaches events to the socket.io-client instance, and commander.js, the client's interface node script.

Socket Client Events

// attachEvents.js
module.exports = (client) => {

    client.on('connect', () => { });

    // Handles 'chat message' event when another user sends a message
    client.on('chat message', (message) => {
      console.info(message);
    });

    client.on('joined', (info) => {
      console.info(info);
    });

    client.on('user joined', (info) => {
      console.info(info);
    });

    // // Handles 'user left' event when a user leaves a room
    client.on('user left', (info) => {
      console.info(info);
    });
}

attachEvents.js exports a function that takes the socket.io-client instance as a parameter. It listens to various events and specifies what to do when they're triggered.

The Node Script

#!/usr/bin/env node // commander.js
const { Command } = require('commander');
const io = require('socket.io-client');

const getAuthOption = require('./src/views/getAuthOption');
const getMenuOption = require('./src/views/getMenuOption');
const chatMessageInterface = require('./src/views/chatMessageInterface');
const render = require('./src/views/renderInterface');
const attachEvents = require('./attachEvents');

const program = new Command();

program.version('1.0.0').description('Terminal Chat App');

// Start Terminal chat app
program
  .description('Starts the Terminal chat app')
  .command('start').action(async () => {
    // Display Authentication menu
    const authOption = await getAuthOption();

    // Render authentication interface according to what the user selects
    const token = await render[authOption]();

    if (!token) {
      console.info('Authentication Error!');
      process.exit(1);
    }

    // connect to the socket server after authentication
    const client = io('https://terminal-chat-app-production.up.railway.app', {
      auth: {
        token
      }
    });

    // Attach events to client
    attachEvents(client);

    // Display Home menu after succesful authentication
    const homeOption = await getMenuOption();

    // Render menu interface according to what the user selects
    const chatRoom = await render[homeOption](client);

    // Start chat room messaging
    chatMessageInterface(client, chatRoom);
  }
  );

program.parse(process.argv);

The above file is a node script that uses the commander library for handling command-line arguments. The script only allows for the start command-line argument. This argument starts the app.

On starting the app, the authentication menu is displayed. The render object is then used to render what the user selects from the menu, and the result of the operation is stored in a token variable.

If a token was not returned from the previous operation, which translates to an authentication failure, the app is terminated. Otherwise, the app keeps running.

A socket.io-client instance is then created, and it uses the returned token for authentication when connecting to the socket.io server.

The home menu is displayed after a successful connection with the server. Again, the render object is then used to render what the user chooses from the home menu option. A chatRoom is returned from the operation.

The socket.io-client instance, along with the chatRoom, is then used to start the chat message interface.

The user can now start chatting with other users in the chat room in real-time.

The client code was published on the NPM registry. This is for easy access and installation on the command line anywhere in the world. You can run npm install tarminal-chat-app on your terminal to install the app.

In the next section, I review the challenges, lessons learned, and potential future improvements for the project.

How I Built a Command-Line Chat Application: The Server Code Explained

Hayatudeen Abdulrahman — Wed, 07 Jun 2023 22:14:38 +0000

Database Schema
- User and Chat Room Models
API Routes
- Authentication Route Handlers
- Authentication Router
- Chat Room Route Handlers
- Chat Room Router
Configuration and Utility
- MongoDB Configuration
- Redis Setup
The Express App, Socket Server, and HTTP Server
- The Express App
- The Socket Server Instance
- HTTP Server

Building a command-line chat application involves several components working seamlessly together. In this article, we'll dive into the server-side code that powers the application. We'll explore the database schema, API routes for authentication, chat room routes, configuration, and utility files, as well as the Express app, socket server, and HTTP server setup. So, let's begin our journey through the server code and unravel the backend logic behind this command-line chat application.

Database Schema

Starting from the server's /src folder, specifically the /models folder, let's take a look into the database schemas of both the user and the chat room.

User and Chat Room Models

// user.model.js
const mongoose = require('mongoose');

const userSchema = new mongoose.Schema({
    username: String,
    email: String,
    password: String,
  });

const User = mongoose.model('User', userSchema);

module.exports = User;


// chatRoom.model.js
const mongoose = require('mongoose');

const chatRoomSchema = new mongoose.Schema({
  roomName: {
    type: String,
    required: true,
  },
}, { timestamps: true }
);

const ChatRoom = mongoose.model('ChatRoom', chatRoomSchema);

module.exports = ChatRoom;

The two schemas use mongoose to create a valid MongoDB schema.

user.model.js defines a userSchema object with three fields: username, email, and password. This stores the user information in a MongoDB collection for authentication.

chatRoom.model.js defines a chatRoomSchema object with only one field: roomName. This allows for the addition and retrieval of chat rooms from the database.

They're both exported for use in the /routes folder.

API Routes

Moving into the /routes folder, it has two folders: /auth, which contains the authentication routes and handler functions; and /chatRoom, which contains the chat room route and handler functions.

Authentication Route Handlers

// auth.controller.js
const bcrypt = require('bcrypt');
const jwt = require('jsonwebtoken');
const User = require("../../models/user.model");
const redisClient = require('../../utils/redisClient');

// User Registration
async function registerUser(req, res) {
  try {
    const { username, email, password } = req.body;

    // Check if the username or email already exists
    const existingUser = await User.findOne().or([{ username }, { email }]);
    if (existingUser) {
      return res.status(400).json({ message: 'Username or email already exists' });
    }

    // Hash the password
    const hashedPassword = await bcrypt.hash(password, 10);

    // Create a new user
    const newUser = new User({
      username,
      email,
      password: hashedPassword,
    });

    // Save the user to the database
    await newUser.save();
    res.json({ message: 'Registration successful' });
  } catch (error) {
    console.error('Registration error', error);
    res.status(500).json({ message: 'Registration error' });
  }
}

async function loginUser(req, res) {
  try {
    const { username, password } = req.body;

    // Check if the username exists
    const user = await User.findOne({ username });
    if (!user) {
      return res.status(400).json({ message: 'Invalid username or password' });
    }

    // Compare the password
    const isPasswordValid = await bcrypt.compare(password, user.password);
    if (!isPasswordValid) {
      return res.status(400).json({ message: 'Invalid username or password' });
    }

    // Generate a JWT
    const token = jwt.sign({ userId: user._id }, process.env.SECRET_KEY);
    await redisClient.set(username, token);

    res.json({ token, message: 'Login successful' });
  } catch (error) {
    console.error('Login error', error);
    res.status(500).json({ message: 'Login error' });
  }
}

async function getToken(req, res) {
  try {
    const username = req.params.id;
    const token = await redisClient.get(username);
    if (token) {
      res.status(200).json(token);
    } else {
      res.status(400).json({ message: 'No token found' })
    }
  } catch (error) {
    res.status(500).json({ message: 'Couldn\'t get token' });
  }

}

module.exports = {
  registerUser,
  loginUser,
  getToken
}

auth.controller.js contains three handler functions: registerUser, loginUser, and getToken.

The registerUser function handles user registration. It initially compares the passed user details in the req.body object with all the user data stored in the database for uniqueness before proceeding to hash the user password for security. If there are no errors, the user details, including the hashed password, are saved to the database for persistence.

The loginUser function handles user login. It starts by checking for a valid user name being passed and then proceeds to compare the user password from the request with the user-stored hashed password in the database. With no errors, a new token is generated using the jsonwebtoken library. The token is then stored in a Redis database with the user's username set as the key.

The getToken function handles token transfers through HTTP requests. It simply gets a stored token with the user's username from the Redis database.

Authentication Router

// auth.route.js
const express = require('express');
const { registerUser, loginUser, getToken } = require('./auth.controller');

const authRouter = express.Router();

// Register API endpoint
authRouter.post('/register', registerUser);

// Login API endpoint
authRouter.post('/login', loginUser);

// Token API endpoint
authRouter.get('/tokens/:id', getToken);

module.exports = authRouter;

auth.route.js defines an authRouter variable, which is initialized as an Express router. The POST and GET HTTP methods are attached to the router to handle requests for the corresponding endpoints using the handler functions imported from auth.controller.js.

Chat Room Route Handlers

// chatRoom.controller.js
const ChatRoom = require("../../models/chatRoom.model");

async function createChatRoom(req, res) {
    try {
        const { roomName } = req.body;
        const isRoomExist = await ChatRoom.findOne({ roomName });
        if (isRoomExist) {
            res.status(409).json({ message: 'Chat room already exists' });
        } else {
            const chatRoom = new ChatRoom(req.body);
            const savedChatRoom = await chatRoom.save();
            res.status(201).json(savedChatRoom.roomName);
        }
    } catch (err) {
        res.status(500).json({message: 'Chat room creation failed'});
    }
}

async function joinChatRoom(req, res) {
    try {
        const chatRooms = await ChatRoom.find({}, 'roomName');
        const roomNames = chatRooms.map((chatRoom) => chatRoom.roomName);
        res.status(200).json(roomNames);
    } catch(err) {
        res.status(500).json({message: 'couldn\'t join chat room'});
    }
}

module.exports = {
    createChatRoom,
    joinChatRoom,
}

Two handler functions can be seen in the above code: createChatRoom and joinChatRoom.

createChatRoom handles chat room creation. It starts by checking if the room in the request body exists in the database and then proceeds to save the chat room to the database if there were no errors.

joinChatRoom on the other hand handles user joining of chat room. It simply retrieves all the created chat rooms from the database.

Chat Room Router

// chatRoom.route.js
const express = require('express');
const { createChatRoom, joinChatRoom } = require('./chatRoom.controller');

const chatRoomRouter = express.Router();

chatRoomRouter.post('/chatrooms', createChatRoom);
chatRoomRouter.get('/chatrooms', joinChatRoom);

module.exports = chatRoomRouter;

chatRoom.route.js uses the handler functions in chatRoom.controller.js to handle POST and GET requests for the /chatrooms endpoint.

Configuration and Utility

The /config and /utils folders contain the MongoDB and Redis connection setups, respectively.

MongoDB Configuration

// /mongo.js
const mongoose = require('mongoose');
require('dotenv').config();

const uri = process.env.MONGO_URI

async function mongoConnect() {
    await mongoose.connect(uri, {
        useNewUrlParser: true,
        useUnifiedTopology: true,
    });
}

module.exports = mongoConnect;

mongo.js, in the /config folder, exports a mongoConnect function that uses the environmental variable MONGO_URI to connect to the MongoDB database.

Redis Setup

// /utils/redisClient.js
const { createClient } = require('redis');
let redisClient;

if (process.env.NODE_ENV === 'production') {
    // Create a Redis client with the production redis url
    redisClient = createClient({
        url: `${process.env.REDIS_URL}`
    });

} else {
    // Create a Redis client with the default port
    redisClient = createClient();
}

redisClient.on('error', err => console.log('Redis Client Error', err));

module.exports = redisClient;

In the /utils folder, redisClient.js checks whether the code is running in production. If it is, redisClient is created with an object option that includes a url property. The value of this property is set to process.env.REDIS_URL, which is provided by Railway, a code deployment service. This allows for easy connection to a running Redis database. And if the code is not being run in production, redisClient is configured to connect to a running Redis database on the default port 6379 of the host's machine.

The Express App, Socket Server, and HTTP Server

At the root of the /server folder, there is app.js, the express app configuration; socketManager.js, the server's socket connections manager; and server.js, the HTTP server setup.

The Express App

// app.js
const express = require('express');
const authRouter = require('./src/routes/auth/auth.route');
const chatRoomRouter = require('./src/routes/chatRoom/chatRoom.route');

const app = express();
app.use(express.json());

app.use('/auth', authRouter);
app.use('/api', chatRoomRouter);

module.exports = app;

app.js exports an express app variable that uses both the authRouter and chatRoomRouter to handle requests for the /auth and /api endpoints.

The Socket Server Instance

// socketManager.js
const jwt = require('jsonwebtoken');
const User = require('./src/models/user.model');

module.exports = (io) => {
    // Authentication middleware
    io.use(async (socket, next) => {
        try {
            const token = socket.handshake.auth.token;

            // Verify and decode the JWT
            const decoded = jwt.verify(token, process.env.SECRET_KEY);

            // Get the user information from the database
            const user = await User.findById(decoded.userId);
            if (!user) {
                throw new Error('User not found');
            }

            // Attach the username property of the user object to the socket
            socket.username = user.username;
            next();
        } catch (error) {
            console.error('Authentication error', error);
            next(new Error('Authentication error'));
        }
    });

    io.on('connection', (socket) => {

        // Create a Map to track the room for each socket connection
        const socketRoomMap = new Map();

        // Handle 'join' event when a client joins the chat room
        socket.on('join', (room) => {
            // Emits the username to the client
            socket.emit('username', socket.username);

            socket.join(room);
            // console.log(socket.rooms);
            socketRoomMap.set(socket.username, room); // Store the room information for the socket connection
            socket.emit('joined', `You joined ${room}`);
            socket.broadcast.to(room).emit('user joined', `${socket.username} joined ${room}`);
        });

        // Handle 'chat message' event when a client sends a message
        socket.on('chat message', (room, message) => {
            socket.broadcast.to(room).emit('chat message', `${socket.username}: ${message}`);
        });

        // Handle 'disconnect' event when a client disconnects
        socket.on('disconnecting', () => {
            const room = socketRoomMap.get(socket.username); // Retrieve the room information for the socket connection
            if (room) {
                socket.broadcast.to(room).emit('user left', `${socket.username} left the chat room`);
                socketRoomMap.delete(socket.username); // Remove the room information for the socket connection
            }
        });
    });
}

socketManager.js exports an anonymous function that takes a single parameter, io. The parameter is an instance of the socket.io server and is used to manage socket connections.

It starts by using an authentication middleware that verifies the token sent by the connecting socket client. It then assigns the user associated with the token to the socket.username object property. This happens before any connection to the server to make sure only authenticated users can make requests to the socket.io server instance.

After successful authentication, the socket server instance (io) listens for the connection event. The event is triggered when a client successfully connects to the socket.io server instance.

A callback function that receives the connected socket client is then executed when the event is triggered. Inside the callback function, three event listeners are attached to the connected socket client: the join, chat message, and disconnecting events.

When the join event is triggered, the connected socket client first emits a username event. This event takes the socket.username object property in the socket.io server instance and sends it to the client. It then proceeds to join the room it received from the client. Also, it stores the room in a map object, with the key being the user's username. This is to be used when the user disconnects. It also emits the joined event to the connected client and the user joined event to other users in the chat room.

Next, when the chat message event is triggered, the callback function in the event simply broadcasts the received message from the client to all the users in the specified room except for the broadcasting user itself.

The disconnecting event is triggered when a user is about to disconnect from the socket.io server instance. The callback function defined in the event starts by retrieving the room saved in the map object with the disconnecting user's socket.username property. A user left event is then broadcasted to all the users in the retrieved room except the disconnecting user.

HTTP Server

const http = require('http');
const ioServer = require('socket.io');
const redisClient = require('./src/utils/redisClient');
const app = require('./app');
const mongoConnect = require('./src/config/mongo');
const socketManager = require('./socketManager');
require('dotenv').config();

// Create server from express app
const server = http.createServer(app);

// set up the socket server and allow all resource to access the server
const io = ioServer(server, { cors: { origin: "*" } });

// Manage socket connections
socketManager(io);

server.listen(3001, async () => {
    // Connect to Mongo
    await mongoConnect();
    // connect to redis
    await redisClient.connect();
    console.log('Server started running...');
});

server.js is the entry point of the /server folder. It starts by creating an HTTP server that uses an Express app to handle requests. It then proceeds to set up a socket.io server instance with the HTTP server. The socket instance is then passed as an argument to the socketManager function to manage socket connections. Finally, the HTTP server listens for requests on port 3001 and waits for a successful connection to the MongoDB and Redis databases before starting the server.

The server code was deployed to Railway for real-time communication between users around the world.

In the next section, we explain the client setup and the main features of the chat app.

How I Built a Command-Line Chat Application: Project Details

Hayatudeen Abdulrahman — Wed, 07 Jun 2023 22:04:41 +0000

Project Overview
Project Goals
Project Features
Project Structure

Building a project as a backend developer is not often fancy like that of a frontend developer. So I decided on creating a full-stack app, but with the command line being the user interface and an HTTP and socket server being the back end. The project has been on my mind, but I only got to work on it for the GitHub + DEV Hackathon.

Project Overview

Tarminal-chat-app is a command-line chat application that allows for real-time communication between users in a public chat room. The app aims to provide a seamless chat experience from the command line.

The command-line interface was built with commander.js and inquirer.js. It uses Axios for making HTTP requests to the server, while the socket.io-client library is used for establishing real-time communication with the server.

The server is an Express app that uses the socket.io library to enable real-time communication with the client. It uses mongoose for storing user data on MongoDB, bcrypt for hashing user passwords, jsonwebtoken for authentication, and redis for token storage.

Project Goals

The main goal of the project was to build a command-line application that lets users chat with each other across several different terminals.

The features I had in mind were private chat, group chat, and public chat messaging.

I did some research and got a general overview of what the app would look like.

From my research, I intended to make the user interface an NPM package and the server deployed somewhere online so that users could communicate with each other from their respective terminals.

Initially, I did not know how to meet the goals of the project. But as a software developer who knows some fundamentals, I believed it was something I could do.

During development, I changed my mind about the features and only implemented the public chat messaging feature. This feature allowed any user to create a chat room, which would be added to a list of chat rooms that any user could join and start messaging each other.

Project Features

The key features of the projects are:

Authentication: Each user is required to provide an email, username, and password during registration. It allows them to log in with their username and password on subsequent requests.
Username: This feature allows for the unique identification of users. It is being used to identify each user in the chat rooms after a successful login.
Creating and joining public chat rooms: Create-Chat-Room is a home menu option that allows any user to create a chat room and be added to a list of chat rooms that other users can join. Join-Chat-Room is also a home menu option but displays a list of chat rooms that can be joined. With either of the two options, the user is automatically brought to a chat message interface.
Chat message interface: This feature allows the user to type text-based messages into the command line. It is enabled only after a user successfully creates or joins a public chat room.
Real-time chat: The socket.io and socket.io-client libraries enable this feature to take user-typed messages from the command line and transmit them to all users in the chat room in real time.
The Home and Exit option: The 'Exit' option is available throughout the application. It can either be accessed by choosing the option in the authentication and home menu or by typing -e in the chat message interface. The 'Home' option can only be accessed in the chat message interface by typing -h.

Project Structure

The Model-View-Controller (MVC) design pattern inspired the structure of the project. The project is separated into two main folders: /server and /client.

The server folder includes the /src folder, where the database schemas, configurations, and REST API logic live; a /test folder, which contains the test cases for the API; app.js, where the Express app is configured; socketManager.js, where socket event management takes place for the server; .env, which contains environmental variables for the database and authentication; and server.js, which is the entry point of the server.

The client folder consists of the /src folder, which contains the logic for the main features of the app like authentication, user interface, and chat message interface; attachEvents.js, which contains socket events for the client; and commander.js, which is the node script for the user interface.

In the next section, I dive into the project's server codebase.

Introducing Terminal-Chat-App: Chat, Create, and Join Public Chat Rooms from the Command Line

Hayatudeen Abdulrahman — Tue, 23 May 2023 23:56:09 +0000

What I built

The Terminal Chat App is a command-line chat application that allows users to join public chat rooms and chat from the command-line interface. Users can also create new chat rooms and interact with other users in real-time

Category Submission: Wacky Wildcards

App Link

https://www.npmjs.com/package/tarminal-chat-app

Screenshots

Video demo

https://youtu.be/GfpvChlPq3g

Description

Features:
Command-line interface
Join public chat rooms
Create public chat rooms
Chat in real-time
User authentication

Link to Source Code

https://github.com/HayatsCodes/terminal-chat-app

Permissive License

MIT

Background (What made you decide to build this particular app? What inspired you?)

As a software engineer looking for my first job, I wanted to be challenged and get out of my comfort zone by building a novel real-life project. I actually had the idea before the hackathon but procrastinated. However, the hackathon refueled me to build the project.

How I built it (How did you utilize GitHub Actions or GitHub Codespaces? Did you learn something new along the way? Pick up a new skill?)

I'd never heard of GitHub codespaces before the hackathon, and I got to find out what I'd been missing all along. It was at least 3X faster than my normal local workspace because of the dedicated virtual machines of up to 32 cores (I used the 2-core machine, and it was still significantly faster than my machine). I loved the fact that I used the default Linux image and didn't need to configure the workspace to get stuff done. I was so excited about GitHub codespaces that I posted about it on LinkedIn and also wrote an article about it on DEV. It was fun building on GitHub codespaces and I'm glad to have discovered it through this hackathon. I only used GitHub actions to automate the server's API test.

Additional Resources/Info

The server was deployed to railway.app while the user interface was published on the NPM registry.

From Tutorial Hell to Project Heaven: 5 Lessons from My First Project

Hayatudeen Abdulrahman — Mon, 15 May 2023 13:29:31 +0000

Tutorial hell is every beginner's worst nightmare. We've all been there: we watch tons of tutorial videos but find it difficult to build a project from scratch. It's not because one doesn't understand the concepts taught in the tutorial, but because one is afraid of not knowing enough to start a project.

My first project was an opportunity for me to apply what I had learned in a comprehensive course and gain confidence in my skills.

However, building a project from scratch can be intimidating. I encountered several challenges while building my first project and learned things I could never have learned if I had relied solely on the course. Months later, that project is still one of my best backend projects.

When I started learning backend development, I took a 40+ hour course to start with. Halfway through, I had learned the most fundamental concepts to start building backend projects.
However, I got bored of the course and wanted to start building projects on my own. I was afraid to get started because I thought I wasn't ready until I finished the course.

Eventually, I took the leap to build my first API project. It was an API that gets over twenty thousand free fiction books available on Project Gutenberg's website.

At first, the idea was to build a basic book store API that allowed users to perform CRUD operations. However, I wanted to work on something unique and closely related to the project I did in the course, namely, an API that's not been implemented before.

After several days of trying things out myself, I had a well-working API. The project broke me out of tutorial hell and gave me the confidence to build several projects after that.

These are the 5 lessons I learned building my first project:

Fundamentals are enough to start building: Regardless of what you're trying to learn, knowing the fundamentals is enough to start building a project yourself. You don't have to learn every technology to start building things. Just start. I'd just learned NodeJS, Express, and MongoDB before my first project. That's just a fraction of the backend fundamentals, and I was able to build a live and usable project with it.
The earlier, the better: The earlier you start building projects, the easier it becomes for you to break out of tutorial hell. My first project gave me confidence to build more projects. It was hard at first, but it's now very easy for me to have an idea and start implementing it right away.
You understand more by doing: Watching or reading tutorials gives you a false sense of achievement. Fair enough; you might understand what's been taught in the tutorial, but you won't fully understand it without trying things out yourself. For example, the CRUD concept was very easy when I followed the course, but I didn't fully grasp it until I built my first project. API RESTful patterns were also difficult to grasp before my first project. Tutorials get you familiar with the concept, while projects solidify the knowledge.
You will most likely learn a new concept while building: Database pagination was something I never knew before my first project. Since I was working with over 20,000 books data, it was not efficient to get all of them at once. So I did some research and got to learn about pagination, which is simply resolving database queries by page. It improved the performance of the API significantly.
Concept retention is directly proportional to building: By building projects and implementing the concepts you've learned, you reinforce your understanding and solidify your knowledge. It's a hands-on approach that helps you internalize the concepts and retain them more effectively compared to passive learning methods like just watching or reading. Before backend development, I tried frontend development, and I would make sure to watch the whole course before implementing a project of my own. But I realized that I'd mostly forgotten the concepts taught in the course. The solution is to build on each concept or two or more related concepts. By building my first project, I retained most of the concepts I'd learned so far, which are still useful for me today.

In conclusion, my first project was a significant turning point in my learning journey. It helped me break free from tutorial hell and gave me the confidence to pursue more projects independently. Through the challenges I encountered while building my first project, I gained valuable insights and learned crucial lessons that have stayed with me.

In the end, it empowered me to embrace a project-driven approach to learning. It taught me the significance of building projects, practicing consistently, and seeking solutions through hands-on experience. I continue to carry these lessons with me as I tackle new challenges, and they have been instrumental in my growth as a developer.

Getting Started with GitHub Codespaces on VS Code

Hayatudeen Abdulrahman — Sun, 14 May 2023 14:29:11 +0000

GitHub codespaces are one of the best development environments for developers. From a faster development environment to having access to a remote Linux environment, it's a workspace for all.
In this tutorial, I will be teaching you one of the many ways to use GitHub codespaces. Let's get started.

What are GitHub codespaces?

Before we get started with the tutorial, let's get to know more about GitHub codespaces and their features.

GitHub codespaces are development environments hosted in the cloud. It allows users to configure these environments according to their needs. Some of the configuration options include setting up the bash terminal, runtimes for popular languages like Python, PHP, and Node, git for version control, yarn for package installation, e.t.c.

GitHub codespaces run on dedicated virtual machines ranging from 2 cores to up to 32 cores. Users can connect to their codespaces from the browser or locally using IDEs like VS Code and JetBrains. Users get up to 60 hours of free usage every month.

Setting up VS Code as the default editor for GitHub codespaces

By default, when creating a new codespace, it opens in the VSCode web client. To open codespaces in your locally installed VS Code, you need to install the GitHub Codespaces extension for Visual Studio Code.

You can install GitHub codespaces here by clicking the install button on the page. Note that you must have Visual Studio Code installed locally for the install button to redirect you to VS Code.

Once you've installed the extension, you can now follow the following steps to set VS Code as your default editor for GitHub codespaces:

Visit GitHub and make sure you're signed in to your account.
Click your profile photo in the upper-right corner of any page.

Then click Settings from the drop-down menu.

In the left sidebar, scroll down and find the "Code, planning, and automation" section. Then click Codespaces.

Scroll down and find the "Editor preference" section. Then select Visual Studio Code.

GitHub codespaces will now open on the VS Code desktop application when you next create or open a codespace.

Configuring VS Code for GitHub Codespaces

Before we get started creating our own codespace in VS Code, you will need to sign into the GitHub codespace using your GitHub credentials:

Open VS Code, and in the Activity Bar, click the "Remote Explorer" icon.

At the top of the "Remote Explorer", you will see a dropdown menu. Select "GitHub Codespaces" from the dropdown.

Click on the "Sign in to GitHub" button.

You'll be prompted to sign in if you are not currently signed in to GitHub. Follow other instructions until you're back on the remote explorer again.

You're now signed in to GitHub codespaces.

Creating a GitHub Codespace in VS Code

Now that we've setup GitHub codespaces for VS Code, let's create a new codespace:

Click the "Remote Explorer" icon

Use your mouse to hover over the remote explorer panel. Then click the "+" icon.

A text box and a list of your repositories will be displayed. Type and select the repo name you want to create the codespace for.

You will be prompted to select a branch and a machine type. Go ahead and select your preferred settings.

You can now start to develop in the codespace in VS Code

Opening a GitHub Codespace in VS Code

Click the "Remote Explorer" icon.
In the "GitHub Codespaces" panel, hover over the codespace and select the plug icon to connect to the codespace.

You can now enjoy developing in your codespace.

Technologies and Tools - GitHub + DEV Hackathon Progress Update

Hayatudeen Abdulrahman — Thu, 11 May 2023 21:26:48 +0000

I did some research on the technologies and tools that will enable the project to be a success. So I will be listing the technologies I will be using for the projects in this article. I will be updating it as I build the app.

Language/Framework: NodeJS/Express

I'm a backend developer experienced with NodeJS and Express, so the app's interface and server will be built with these frameworks.

Command Line Libraries: Commander and Inquirer

I will be using these frameworks to build the command-line interface that will interact with the server.

Web Socket Library: Socket.io

I'm new to web sockets but found this to be the best library for real-time apps. This will facilitate real-time communication between the client and the server.

Idea: A Command-Line Chat Application - GitHub + DEV Hackathon Progress Update

Hayatudeen Abdulrahman — Thu, 11 May 2023 13:36:58 +0000

Hello DEVs. I'm excited to participate in my first hackathon. I got the idea for a command-line chat application a few weeks ago and have been procrastinating on it. But the GitHub + DEV Hackathon has reignited my interest in building the application.

The goal of this project is to create a real-time chat application that allows users to create and join room chats from the command line. The project is mostly targeted at anyone who is not afraid of the command line (lol).

The project falls under the Wacky Wildcards category of the hackathon. And I'm looking forward to building a silly and fun application.

I hope to learn new technologies and become a better developer while also winning some cool prizes by the end of the hackathon.

The JavaScript Assignment, Equality, and Strict Equality operators

Hayatudeen Abdulrahman — Sun, 28 Aug 2022 21:48:30 +0000

The equal (=), double equal (==), and triple equal (===) signs, which are respectively known as the assignment, equality, and strict equality operators in JavaScript, often confuse junior JavaScript developers. Inappropriate use of these operators can make programs run abnormally, sometimes without the compiler throwing an error, making codes difficult to debug.

In this article, I will explain what each of them does and how and when to use them.

Lets dive in!

The Assignment Operator (=)

The assignment operator is the same across all programming languages. As its name implies, in the simplest form, it is used to assign values to variables. The variable is on the left-hand side and the assigned value is on the right-hand side.

It can also be combined with the arithmetic operators to perform simple operations before assignment. For more on this, click here.

The above image illustrates the usage of the assignment operator and its shorthand forms.

It was coded as follows:

Line 1 declared a variable called newVariable.
Line 2 assigned the value 20 to newVariable.
Line 36 syntax is newVariable = newVariable <op> 10. Where <op> is replaced with the appropriate operator, e.g., line 3 is the same as newVariable = newVariable + 10 .

The assignment operator has right-to-left associativity, that is, operations are performed from right to left. Thus, line 3 of the code will add newVariable to 10 before assigning the result back to newVariable (itself).

The Equality Operator (==)

The equality operator, which has a double equal sign, is also similar across most programming languages.

The operator is used to compare two or more expressions and always evaluates to a true or false (boolean) value.

In the above code:

I assigned 100 to variable num1 and 300 to variable num2, then
num1 and num2 variables are compared and at the same time stored in a result variable.
And a false value is logged to the console since the values of num1 and num2 are not equal.

Before comparison, the operator also performs type conversion if necessary.

The above code compares a variable string of 10 with a variable number of 10 using the equality operator, and a true value is obtained, though theyre of different types.

There is also an inequality operator (!=) in JavaScript which does the exact opposite of the equality (==) operator.

Changing the equality operator in the above code to an inequality operator, a truthy value is obtained.

The Strict Equality Operator (===)

The strict equality operator, unlike the other two operators, is only available in two programming languages: PHP and JavaScript.

The operator works like the equality operator, except that it does not make a type conversion before comparison.

In the above diagram, a comparison using the strict equality operator, though having a value of 10 of different types, evaluates to false.

Using the strict equality operator is considered as best practice to avoid code bugs.

The strict inequality operator (!==) in JavaScript does the exact opposite of the strict equality (===) operator.

The above code checks if string 50 is not equal to number 50, using the strict equality operator, and it evaluates to true.

Check here for more on the difference between equality and strict equality operators.

Conclusion

In this article, I explain the difference between the assignment, equality, and strict equality operators. You should now be able to distinguish between the three operators as well as their use cases.

DEV Community: Hayatudeen Abdulrahman

API Testing 101: A Beginner's Guide to Testing Nodejs APIs with Jest and Supertest

Software testing

What is API testing?

Importance of API testing

Types of Testing

Unit testing

Integration testing

Testing frameworks and libraries

Express server setup

Testing the book API with Jest and Supertest

Conclusion

Socket.IO Authentication System With JWT

Overview

The Authentication System

Database Model

Express Authentication Handlers

Socket Server Setup

Client-Side Connection

Conclusion

How I Built a Command-Line Chat Application: Project Reflections

Challenges

Lessons Learned

Contributions and Future Improvements

Project References

Demo Video

NPM Registry Link

GitHub Link

Conclusion

How I Built a Command-Line Chat Application: The Client Code Explained

Client Authentication

User Registration

User Login

User Token

Home Menu

Creating Chat Rooms

Joining Chat Rooms

Exiting the App

User Interface

Authentication Display Options

Home Display Options

Interface Rendering

Chat Message Interface

The Socket Client and Node Script

Socket Client Events

The Node Script

How I Built a Command-Line Chat Application: The Server Code Explained

Database Schema

User and Chat Room Models

API Routes

Authentication Route Handlers

Authentication Router

Chat Room Route Handlers

Chat Room Router

Configuration and Utility

MongoDB Configuration

Redis Setup

The Express App, Socket Server, and HTTP Server

The Express App

The Socket Server Instance

HTTP Server

How I Built a Command-Line Chat Application: Project Details

Project Overview

Project Goals

Project Features

Project Structure

Introducing Terminal-Chat-App: Chat, Create, and Join Public Chat Rooms from the Command Line

What I built

Category Submission: Wacky Wildcards

App Link

Screenshots

Video demo

Description

Link to Source Code

Permissive License

Background (What made you decide to build this particular app? What inspired you?)

How I built it (How did you utilize GitHub Actions or GitHub Codespaces? Did you learn something new along the way? Pick up a new skill?)

Additional Resources/Info

From Tutorial Hell to Project Heaven: 5 Lessons from My First Project

Getting Started with GitHub Codespaces on VS Code