DEV Community: Antonio Villagra De La Cruz

Password-less Authentication Using Magic Links

Antonio Villagra De La Cruz — Sun, 17 Apr 2022 16:12:51 +0000

Passwords have been, for better or for worse, a staple in our digital life since the advent of the Internet. Authenticating ourselves on the Internet has required passwords, but are there other ways we can prove we have access to an account.

In this article, after I rant a bit against passwords, we will look at implementing magic links, a password-less authentication method.

Password-based authentications are flawed in practice

In theory, passwords provide a high level of security, as only the rightful owner should know it. In practice though, passwords are inherently insecure. As much as 80% of data breaches are due to poor password hygiene, meaning people reusing passwords, or using simple-to-guess passwords. That in turn is due to password fatigue given the staggering number of tools and services we now use on-line.

An existing solution is to use password managers to generate strong unique passwords and store them safely. Again, this works great in practice, until your password manager gets hacked, which unfortunately happens more often than it should. Luckily some services provide multi-factor authentication (MFA), which requires another means of authentication on top of your password. That is usually a one-time password (OTP) sent via SMS, a unique code from an app using WebAuthn, or a notification on your registered phone. At this point, it's fair to wonder what the primary password is used for.

Another aspect to the discussion is also the non-negligible number of users who end up using the reset password flow to authenticate. That flow pretty much resembles password-less authentication using magic links, which is what we are looking at implementing here. Finally, implementing a password-less authentication method means that passwords need not be handled and stored by your service, limiting the risk of mishandling and leaks, because, let's be honest, storing passwords properly isn't so straightforward.

Password-less authentication with magic links

Password-less authentication is a method to authenticate a user without the use of a password. This includes a lot of different techniques such as:

One-Time Passwords
WebAuthn
Possession of a unique device (phone, hardware key)
Possession of a unique bio-metric trait (face, fingerprint)
Magic links

Each technique has their pros and cons, but in this article we will focus on magic links. This technique involves sending a link by email or SMS to a user trying to authenticate to our service. The link is unique, and when clicked, authenticates the user in their browser. In a way, it is a similar flow to the reset password flow, albeit without passwords.

Some of the pros of using magic links include:

no passwords for the user to manager or for you to store;
more secure than passwords in practice;
simple process which only requires the user to have valid email address.

Some of the cons of using magic links include:

the authentication method is as secure as the user's email box, but that is already the case for reset password flows;
it requires users to open their email clients to login to your service, which adds friction;
they don't play well with password managers.

Security risks of magic links (and how to mitigate them)

A disclaimer first: I am not a security expert, so I might miss some important security risks regarding magic links. The following is only to the best of my knowledge on the subject.

Guessable links

The most obvious security risk is if someone other than the user can guess the authentication link, in which case the attacker can authenticate as the user.

There are a few strategies that we can use to fend those attacks off:

Generate cryptographic random tokens with enough entropy, which will make it almost impossible to guess.

Recommendations on the length of the tokens will vary, but the benefit of magic links is that users don't need to type the token in as they would for MFA using an OTP for example. That means that we can make those tokens at least 32-bit long, or even 64-bit long without impacting user experience.

When generating the token, use a cryptographic strong random generator. In JavaScript land for example, don't use Math.random(), but instead the crypto library in Node, or bcrypt from npm.

Add a validity time limit on the magic links

The previous point should already make our links safe, but by time-bounding our magic links, we dramatically reduce the window of opportunity for an attack to be successful at guessing the link. This advice is similar to password reset flows. As a rule of thumb, a magic link should be valid for maximum 5 to 15 minutes.

Replay attacks

In replay attacks, an attacker is able to capture and reuse a link that was already used by a legitimate user. As the token appears in clear text in the link (either as a parameter or a query string), it is possible that a hostile agent can read it, and reuse it.

The simplest mitigation strategy here is to ensure that our magic links can only be used once, which would render replay attacks void.

Man-In-The-Middle (MITM) attacks

At the end of the day, the security of magic link authentication resides in the security of the user's email inbox, and the belief that the link arrives into the ends of the user who requested it. The security of a user's email account is, of course, out of scope, but we can fend off man-in-the-middle (MITM) attacks.

As the link and token are sent in plain format, it is not impossible for an attacker to intercept the message and try to authenticate with said link. To protect against that threat, we can fingerprint the browser from which the user requested the magic link. A simple strategy would be to attach a cookie, or save a token in the user's browser, and send that value back when they click on the magic link. Only the user who requested the link can therefore successfully authenticate.

If the user's email account is compromised, there is unfortunately little we can do, but the same is true with classic password workflows, and in particular password reset flows.

Implementing magic links

Now that we have looked at magic links, how they work, and what are the main security threats and mitigations, let's write an implementation of magic links.

For this example, we will be using JavaScript, Node and Prisma (an ORM for PostgreSQL, MySQL, and MongoDB).

To implement magic links, we need a few things:

Generate a link with a random token
Validate the link and token to authenticate the user

Scaffolding

To follow this mini-tutorial, you need to have Node installed on your computer. The latest version the better!

We start with a basic express app:

mkdir node-magic-link
cd node-magic-link
npm init -y
npm install express

We then create an index.js file inside our project. For now, let's just write a very basic express app:
index.js

const express = require("express");

const app = express();
const port = process.env.PORT || 3000;

app.get("/", (req, res) => {
  res.send("Hello, world!");
});

app.listen(port, () => {
  console.log(`Listening on port ${port}`);
});

We can run this app from the command line using:

node index.js

We should see in the console: Listening on port 3000. If we open http://localhost:3000 in our browser, we should see the text "Hello, world!".

Alright, so let's dive into it!

Data Model

To support our magic link password-less authentication, we will build a bare bones data model using SQLite and Prisma. The benefit of SQLite is that it is basically just a file on your computer, so there is no need to set something more complex like a PostgreSQL or Mongo database locally.

Using Prisma allows us to abstract away the underlying database, as the same code can be used for SQLite, PostgreSQL and MySQL, and with minimal changes with MongoDB. Prisma also has other advantages, so do check it out!

To get started with Prisma, run the following in your project folder:

npm i -D prisma
npm i @prisma/client

To initialize a new Prisma project:

npx prisma init --datasource-provider sqlite

This will generate a file shema.prisma in a new ./prisma folder:

// This is your Prisma schema file,
// learn more about it in the docs: https://pris.ly/d/prisma-schema

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")
}

Note that you can later change the datasource provider in ./primsa/schema.prisma.

In our exercise, we only need a User model and a MagicLink model. For simplicity, our models look like follows:
./prisma/schema.prisma

model User {
  id         String      @id @default(uuid())
  name       String
  email      String      @unique
  magicLinks MagicLink[]
}

model MagicLink {
  id         String   @id @default(uuid())
  token      String
  userId     String
  user       User     @relation(fields: [userId], references: [id])
  validUntil DateTime
}

From this model definition, Prisma generates the following migration after running npx prisma migrate dev:
./prisma/migrations/**/migration.sql

-- CreateTable
CREATE TABLE "User" (
    "id" TEXT NOT NULL PRIMARY KEY,
    "name" TEXT NOT NULL,
    "email" TEXT NOT NULL
);

-- CreateTable
CREATE TABLE "MagicLink" (
    "id" TEXT NOT NULL PRIMARY KEY,
    "token" TEXT NOT NULL,
    "userId" TEXT NOT NULL,
    "validUntil" DATETIME NOT NULL,
    "isUsed" BOOLEAN NOT NULL DEFAULT false,
    CONSTRAINT "MagicLink_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User" ("id") ON DELETE RESTRICT ON UPDATE CASCADE
);

-- CreateIndex
CREATE UNIQUE INDEX "User_email_key" ON "User"("email");

We have a User table with an id as a primary key, a name as a string, and an email as a string with a "unique" constraint. We also have a MagicLink table with an id as primary key, a token as a string, a validUntil as a date, an isUsed value as a boolean, and a userId as a foreign key referencing the User table.

Generate magic link

Let's now look at the link generation!

For simplicity, we will return a bare bones form to the user in the root router:
index.js

app.get("/", (req, res) => {
  res.send(`
    <html lang="en">
    <body>
      <form method="POST" action="/auth/link">
        <p>Enter your email to login</p>
        <label>Email: <input type="email" name="email" required/></label>
        <button type="submit">Go</button>
      </form>
    </body>
    </html>
  `);
});

To handle the form submission, we need to install body-parser and register it as follows:

npm i body-parser

index.js

const express = require("express");
const bodyParser = require("body-parser");

const app = express();
const port = process.env.PORT || 3003;

app.use(bodyParser.urlencoded());

...

We also need to register the route the form is submitting to:
index.js

...

const { PrismaClient } = require("@prisma/client");
const db = new PrismaClient();

...
app.post("/auth/link", async (req, res) => {
  // 1. Retrieve the value of the email from the request object
  const email = req.body.email;

  // 2. Find the corresponding user
  const user = await db.user.findUnique({ where: { email } });
  if (!user) {
    return res.sendStatus(404); // User not found!
  }

  // 3. Generate a random token and a corresponding link
  const token = crypto.randomBytes(64).toString("hex");
  const link = `${
    req.protocol + "://" + req.get("host")
  }/auth/login?token=${token}`;

  // 4. Don't forget to attach a validity limit!
  const validUntil = new Date(Date.now() + 15 * 60 * 1000); // in 15 minutes

  // 5. Save the token in the database
  await db.magicLink.create({
    data: {
      userId: user.id,
      token,
      validUntil,
    },
  });

  // 6. Send the link by email
  sendEmail(email, link);

  // 7. We're done here!
  res.redirect(`/auth/link/sent?email=${email}`);
});

Here is an example of link generated by this code:
http://localhost:3000/auth/login?token=7d8e18a2ec1a7ace4b623d8eacb392b1748807048aa56a5188b4b7a418e9d88d145bb2ee098df1c1b8ce87c15a42949f0b1bc8761991751305e1dcb19ce78c61

For the following code to work properly, we need to create at least one user in our database. This can be done directly via Prisma Studio, which you can open in your browser with the following command:

npx prisma studio

Here, you can navigate to the User table and add a new row with some dummy data.

We also need a dummy sendEmail() function and a handler for the route /auth/link/sent:

function sendEmail(to, body) {
  console.log(to, body);
}

app.get("/auth/link/sent", (req, res) => {
  const email = req.query.email;

  res.send(`
  <html lang="en">
  <body>
    <p>Link sent to <strong>${email}</strong>.</p>
  </body>
  </html>
  `);
});

Validate magic link

If we have a look at the link we created to authenticate our users, when visiting that link they will make a GET request to /auth/login, so we need to handle that as follows:

app.get("/auth/login", async (req, res) => {
  // 1. Retrieve the token from the query string of the request
  const token = req.query.token;
  if (!token) {
    return res.sendStatus(400);
  }

  // 2. Validate token
  const magicLink = await db.magicLink.findFirst({
    where: { token, isUsed: false,  validUntil: { gte: new Date() } },
  });
  if (!magicLink) {
    return res.sendStatus(404);
  }

  // 3. Mark the link as used, to avoid replay attacks
  await db.magicLink.update({
    data: { isUsed: true },
    where: { id: magicLink.id },
  });

  // 4. Create a user session and redirect the user
  // TODO: this will depend on your exact app setup ...
  const user = await db.user.findUnique({ where: { id: magicLink.userId } });

  res.send({ user });
});

Here we simply read the token from the request query string and we make sure that this token is still valid. If the token is valid, we mark it as used. In our example, we simply return the user, but in a real-world application you would then authenticate the user and redirect them appropriately.

Bonus: fingerprint user's browser

If you recall the brief security discussion around magic links, you can see that we have fend off a few attack scenarios, namely the guessable links and replay attacks. There is still a very minimal risk of MITM attacks, and a simple way to work around them is to fingerprint the browser from where the origin request has been made.

To do that, we will be generating another random token, and setting it as a cookie on the user's browser. This cookie will then be sent automatically by the browser when the user clicks on the magic link, and we can thus verify that the link was opened in the same browser it was requested.

To handle cookies with express we need to install another middleware, namely cookie-parser:

npm i cookie-parser

index.js

const express = require("express");
const bodyParser = require("body-parser");
const cookieParser = require("cookie-parser");

const app = express();
const port = process.env.PORT || 3003;

app.use(bodyParser.urlencoded());
app.use(cookieParser());

...

We also need to store the cookie token in our database, so we need to add a field to our MagicLink model:
./prisma/schema.prisma

model MagicLink {
  id          String   @id @default(uuid())
  token       String
  cookieToken String
  userId      String
  user        User     @relation(fields: [userId], references: [id])
  validUntil  DateTime
  isUsed      Boolean  @default(false)
}

Finally, we need to generate that cookie token when the user requests a magic link, store it in our database, and set it on their browser:
index.js

app.post("/auth/link", async (req, res) => {
  // 1. Retrieve the value of the email from the request object
  const email = req.body.email;

  // 2. Find the corresponding user
  const user = await db.user.findUnique({ where: { email } });
  if (!user) {
    return res.sendStatus(404); // User not found!
  }

  // 3. Generate a random token and a corresponding link
  const token = crypto.randomBytes(64).toString("hex");
  const link = `${
    req.protocol + "://" + req.get("host")
  }/auth/login?token=${token}`;

  // 4. Don't forget to attach a validity limit!
  const validUntil = new Date(Date.now() + 15 * 60 * 1000); // in 15 minutes

  // 5. Generate a cookie token
  const cookieToken = crypto.randomBytes(64).toString("hex");

  // 6. Save the tokens in the database
  await db.magicLink.create({
    data: {
      userId: user.id,
      token,
      validUntil,
    },
  });

  // 7. Send the link by email
  sendEmail(email, link);

  // 8. Set the cookie on the user's browser
  res.cookie("node-magic-link-check", cookieToken, { httpOnly: true });

  // 9. We're done here!
  res.redirect(`/auth/link/sent?email=${email}`);
});

Note the changes made on steps 5., 6. and 8..

And we validate the presence of the cookie when validating the link before authenticating:

app.get("/auth/login", async (req, res) => {
  // 1. Retrieve the token from the query string of the request
  const token = req.query.token;
  if (!token) {
    return res.sendStatus(400);
  }

  // 2. Retrieve the cookie token from the cookies
  const cookieToken = req.cookies["node-magic-link-check"];
  if (!cookieToken) {
    return res.sendStatus(400);
  }

  // 3. Validate tokens
  const magicLink = await db.magicLink.findFirst({
    where: {
      token,
      cookieToken,
      isUsed: false,
      validUntil: { gte: new Date() },
    },
  });
  if (!magicLink) {
    return res.sendStatus(404);
  }

  // 4. Clear the cookie
  res.cookie("node-magic-link-check", "");

  // 5. Mark the link as used, to avoid replay attacks
  await db.magicLink.update({
    data: { isUsed: true },
    where: { id: magicLink.id },
  });

  // 6. Create a user session and redirect the user
  // TODO: this will depend on your exact app setup ...
  const user = await db.user.findUnique({ where: { id: magicLink.userId } });

  res.send({ user });
});

Here we just add some checks on step 2. and 3.. Then we clear it in step 4..

And that rounds up, our look at password-less authentication using magic links!

Some Thoughts on Improving Tech On-boarding

Antonio Villagra De La Cruz — Sat, 08 Jan 2022 03:12:35 +0000

New year, new you, new job?

As this is on-boarding season, I thought it would be interesting to go over some personal thoughts on how to improve the tech on-boarding process. As usual, a small disclaimer that this is my personal perspective on the matter through the lenses of software engineering, and as such will not apply in most other contexts. Yet, I hope some of the thoughts shared hereafter prove useful and do inspire you to build a better process.

Instead of focusing on common advice around on-boarding best practices, I'll go over a few more specific ideas that I believe will help improve your existing process.

Treat your code as if it were open source

There are some benefits in treating your code base as if it were open source, and one of them is better on-boarding. Some traits of open source software that you can borrow are documentation, open culture, and shared code ownership.

At the root of any open source project, you usually find a README.md file that provides an overview of the project, how to run it, and how to contribute. While your product and code base might be slightly more complex than the average open source project, having clear documentation facilitates on-boarding. Be careful though, outdated documentation is worst than no documentation. At a minimum, you should have clear guidelines as to how the code is structured, how to set up and run a local environment, and how the team collaborates and works together. Ideally the code itself is also documented with high-quality comments explaining the why instead of the what or the how.

Having an open culture, where all decisions are made in public and clearly documented, can also prove useful when on-boarding a new colleague. Not only will that provide some context around the product and the code, but it will also show how decisions are made and what are the team dynamics. It will also provide a template and invite new colleagues to share their ideas.

As much as possible, create an environment of shared code ownership. Instilling code reviews and standards across teams is an easy way to achieve that. The goal should be that every engineer has enough knowledge on all parts of the code that they can work on them. This also facilitates on-boarding, as such a set up would help new colleagues grasp the intricacies of the code base.

Treating code as open source becomes even more paramount in a remote setup!

Pairing is your super-power

Assigning a buddy to new joiners is a staple in most on-boarding processes, but it is even more important for software engineers, as usually there is a lot of context around the product and the code base that isn't captured in documentation.

As much as possible, encourage buddies to pair program with the new joiners in the first few weeks. Make buddying an explicit part of their occupation in those weeks so that they can provide the best support to new joiners. Organize regular check-ins where you can get continuous feedback on the on-boarding process. Keep track of areas where there seems to be more of a struggle. Getting all that data is eased with a buddy system as the feedback loop is almost instantaneous.

Finally, create spaces beyond your buddy system to help your new colleagues socialize. Make it part of the on-boarding process that they meet people from other teams and other functions in the company. That will break silos early on and create a stronger sense of belonging.

As with the previous point, pairing becomes even more primordial in a remote setup!

Find an adequate first task

The last point I wanted to touch upon is finding an adequate first task, as this can help set a positive trajectory for your new colleagues if done well. The first task should have low coupling, be non-trivial, and generate high impact.

Ideally, the first task should not need deep knowledge of the code base or the product. Your new colleague won't be equipped yet to fully grasp the nuances, and they might get discouraged by the time it might take them to wrap their head around all the edge cases. It also shouldn't be on the critical path of the product, nor should it be an urgent feature. The last thing you want is for their first task to end up breaking some critical part of your product, or missing a deadline. A good first task could be additive rather than an incremental improvement of an existing feature. It should have low coupling with the existing code base if possible. That way, you reduce the risk of the task breaking or having to be rushed.

This will depend on the level of seniority of your new colleague, but try to make the first task a non-trivial one and set the level of complexity so that it is still an interesting challenge. Writing tests or fixing bugs are, in my opinion, terrible first tasks. Instead, make the first task pure product work. Paired with a buddy system, working on a slightly challenging task will naturally provide opportunities to pair and exchange ideas. It also signals to the new colleague that they are valued and trusted to work on complex topics. Quick wins are fine, but creating space for new joiners to fully experience the life cycle of building a non-trivial feature will help down the line. Allow them to showcase what they can do from the get-go! Careful though on not making the first task too challenging as that might backfire and lead to a loss of motivation and self-esteem.

Finally, pick a first task with high impact, either for the business or for the company. Not only will that improve their self-esteem as their work will immediately create value, but it might already create synergies with existing team members.

Of course, as with most professional endeavors, it helps to also set clear expectation and entertain an open feedback culture.

Ultimately, everyone is different, and the best on-boarding process is the one that can adapt to the uniqueness of every new colleague while equipping them with the right environment for them to succeed.

Happy on-boarding!

Why you should be continually interviewing

Antonio Villagra De La Cruz — Wed, 27 Oct 2021 22:23:39 +0000

I usually don't share pieces of advice I haven't applied myself, but in this case, the epiphany came before the practice: you should be always interviewing!

Interviewing is a skill

This is particularly true in software engineering, but might be very relevant regardless of your position: interviewing is a skill. Nothing in your day-to-day occupancy, nor in your studies really prepares you for interviewing. And as with every other skill, it needs practice to improve over time. Similarly to how you might play 2 hours of chess every week to improve your game, you should be having the same outlook about interviewing.

By continually interviewing, not only will you improve your interviewing skills over time, but you will also gain confidence in your pitch and your answers. Instead of waiting to need a new job, you can always be interviewing and try different approaches on how you write your CV, how you present yourself, how you answer common interview questions and how those resonate with your interviewers.

A/B testing different approaches in low-stress situations will help you hone your discourse, and you will be a lot more prepared when you indeed need to find a new job. Compared to someone who might only interview every 2-3 years, your continuous practice puts you at a clear unfair advantage!

Interviewing allows you to better understand the market and know your worth

This is again particularly true in software engineering, but the job market is constantly evolving (and happens to be pretty hot right now!). Putting yourself out there, even if you are satisfied with your current position, will help you keep up to date with the market. What new technologies are coming up? How are salaries and compensation packages evolving in the market? Which cool new companies are hiring right now? Information is power, and having an up-to-date notion of the market and of your worth is priceless. And the easiest way to achieve that is by continually interviewing.

Interviewing sometimes feels like being mainly luck. If you only interview when changing jobs (which might be on average every 2-3 years), you are limiting your range of options to the companies currently hiring when you are scooting for opportunities. Instead, if you are continually interviewing, you are always on top of any opportunity. And who knows, maybe you will find a unique opportunity that you might have missed have you not being interviewing in that precise moment!

Interviewing is an easy way to build connections

In an environment that is probably going to be a lot more remote than it used to be, building connections might become more complicated. Something I particularly enjoy about interviews (both giving and taking them), is that you have a chance to create a connection with fellow engineers. You get to see what other people are working on, and how they are thinking about solving some common challenges.

You basically get to network for free when interviewing. And if eventually you might not be ready to jump ships, the connections you've made throughout the process might prove valuable down the line. Similarly, if you don't go all the way through an interview process, you might still learn from the experience and come out with a few new connections!

Finally, I wanted to quickly touch on a topic that does come up with such advice: aren't you just wasting other people's time by interviewing "for practice"? My main counter-argument here is that it is the company's job to ensure they are spending their time wisely with regards to hiring. For all you know, you might end up changing jobs if the final offer is attractive enough.

And with that, let me dust off my resume and start applying!

Some guiding principles on how I write my resume

Antonio Villagra De La Cruz — Wed, 20 Oct 2021 19:48:07 +0000

As the tech hiring market is getting hotter by the day, I thought it might be helpful to share some guiding principles that I've followed over the years when crafting my resume.

A quick disclaimer first: those principles have served me well so far in my career and have allowed me to work for companies in 3 continents, but it is true that even if I would identify as part of an underrepresented group in tech, I do have (unfortunately) a certain amount of privilege by being a man in tech. As such, your millage will definitely vary a lot depending on your situation. Yet, hopefully some of those principles and tips will prove useful to your very own situation!

Let's first look at some overarching principles about the form.

Keep it short

No matter how interesting your life is, limit yourself to one single page. Even though it might seem like a tough constrain, there are multiple benefits to it.

Most importantly, it'll restrict the information that you can put on your resume, and will force you to carefully choose what to include. To borrow Parkinson's law which states that "work expands so as to fill the time available for its completion", by limiting our resume to only one single page we avoid the trap of filling it with irrelevant information. To quote the French author Antoine de Saint Exupéry, "perfection is finally attained not when there is no longer anything to add, but when there is no longer anything to take away". As such, aim for perfection, keep it short!

Your resume needs not be exhaustive, it just needs to get you through to an interview!

Keep it consistent

Unless your resume is bad, in which case maybe consistency might not be something you should aim for, try to keep everything in your resume consistent.

Things to pay some particular attention are using similar fonts for similar content, using similar formatting for similar content as well, and having similar spacing between sections. If you use a type of bullet point for a list, keep it across your resume. If you are starting some sentences in your work experience with a verb in the past, do so for all of your work experience. Make sure that across your resume, information follows a pattern. In some sense, your resume needs to follow a theme. Ideally nothing should look too out of place.

Lower the cognitive load of scanning your resume by keeping it consistent!

Keep it easily scannable

By keeping your resume short and consistent, you already facilitate the work of recruiters scanning through your resume.

To go one step further, and make your resume as easily scannable as possible, use font size and weight to create hierarchy in your resume. Using font color (I like to play with shades of grey) also help communicate hierarchy. In some cases, it might make sense to highlight some key information. Not getting too creative with the layout also helps make the content more readable.

Make it as easy as possible for people looking at your resume to find the information they are looking for!

Keep it visually pleasing

It doesn't need to be a piece of art, but your resume needs to be visually pleasing.

The people reviewing your resume are (for the most part) humans just like you. As such, there will be inherent biases towards how a resume looks like. The expected formats can greatly differ depending on countries, but aesthetic is most likely equally important across the board. Visually pleasing doesn't mean needing to craft a complex and stunning design, but making conscious choices in regards to fonts, colors, and layout. If possible, put in more thoughts than just copying a template from the Internet.

Unfortunately, resumes are partially judged by their cover, so try to make it as pleasing as possible!

Now, let's look at the content of the resume.

Personal details

Being extremely minimalist in terms of personal details might be a smart way to circumvent some unconscious bias. I would recommend to only put your name and a professional email address in your resume. Don't give any more chances for people reviewing your resume than necessary to discriminate on any personal details.

If possible, adding a quick summary can help your profile stand-out and be more memorable. As an example, I have been using some variations of the follow summary:
"Multicultural software engineer passionate about building products that empower people".

Work experience

Now into the most important section of your resume, if you already have some work experience!

Work experience should ideally be listed in anti-chronological order, with your position and the name of the company clearly stated. You can either add the duration of your stay at the company or the dates of employment. A short paragraph giving some quick context about the company and your overall role can help add some more context.

Main achievements should then come below in bullet points. As long as you are consistent, you can start with a verb in the past tense, or the present preterit, or a noun. Try to limit the number of list items to between 3 and 5. Make sure that each bullet point adds value to your profile, and that there are no superfluous words. If you can add any metrics you have improved, the better! You can also either add a list of skills under each work experience, or have them listed in a separate section of your resume.

Limit yourself to the last 3 to 5 relevant work experiences. If you have had more jobs, you can simply state the position you held, the name of the company, and the dates of employment.

Skills

Be strategic when listing your skills. Don't add every single technology you've had the chance to try out. Add skills on which you feel comfortable holding an opinionated discussion.

While staying truthy, if possible, match the list of skills with the skills listed in the job ad you are applying for. Avoid trying to quantify your level of expertise in each skill other than maybe in number of years (so, no fancy progress bars or star ratings).

Education

The more advanced you are in your career, the smaller this section should become. Some essentials are your degrees, where you earned them, and when. Try to use the official naming conventions for them, this is not the place you want to get creative!

If you are early on in your career, feel free to also add the key courses you have attended. In some places, the expectation is to also add your grades, but I would personally avoid that elsewhere.

Side projects

Quick disclaimer: it is totally fine to not have any side projects. Living your life is way more important than building yet another weather app or URL shortener (ahem ...).

If you do enjoy building (or doing) things on the side, that is an asset that you want to put forward on your resume! Keep it as concise as possible though, with just a title, a quick description and maybe a link, as this will mostly serve as hooks during subsequent interviews and make your profile stand-out more.

Achievements

I personally have a hard time bragging about my achievements (maybe because I don't feel like I have achieved that much?), but if you have, please do add it in your resume!

Interests

This section is often absent from most resumes, yet I believe it provides to most value towards making your profile unique. Having common interests with a potential interviewer can also help create a connection easier.

If you are going to list your interests, try to be specific and avoid vague ones like "reading books", "traveling the world", or "watching movies".

Finally, I also wanted to quickly touch on the subject of cover letters.

If you are planning on sending a generic cover letter, I would simply not bother. If you are applying to a big company, that might not matter much at the end, but when applying to smaller companies, a personal well-crafted cover letter might help you get a foot in the door.

Some guidelines (some quite similar to those for resumes) when writing a cover letter:

Keep it short and go straight to the point
Make it relevant to the position and company you are applying for

Ultimately, the goal of a cover letter is to show that you understand and align with the company's mission and values, and that you possess the skills to make you successful in the position you are applying for.

And of course, always proof-read anything you send into the wild!

That's all folks!

I hope you at least found one useful piece of information in this post, and all the best for your job search and interviews!

Let's go CSRF-ing!

Antonio Villagra De La Cruz — Wed, 13 Oct 2021 19:35:53 +0000

Get your surfboard ready, we are heading to the sea ... and the less than relaxed and laid back world of CSRF (pronounced "sea surf") attacks!

What is CSRF?

Cross-Site Request Forgery (abbreviated as CSRF or XSRF) is an exploit which tricks a web application into sending a malicious request on behalf of an authenticated user. It is also known as one-click attack, session riding, hostile linking, or cross-site reference forgery. This allows an attacker to trick a web application into executing any actions of their choosing as if they were the authenticated user.

Fundamentally, a CSRF attack relies on user's identity on a given web application and the web application's server's trust in that identity. As the attacker does not receive the response of the malicious request, only requests with side effect present a risk vector (for example: a request that transfers funds, changes passwords, ...).

In order for a CSRF attack to be successful, an attacker needs to have knowledge of the APIs they are targeting to be able to craft a valid request. They also need to make use of social engineering to trick users to visit a web page in their control or open an email they sent, and in some cases, albeit not necessarily, interact with said page or email. The victims should also be logged into the specific service when the attack is performed. These conditions make such attacks somewhat complex, but in most severe cases (for example, targeting a user with administrative rights), CSRF attacks can potentially lead to the compromise of the entire web application.

Some major CSRF attacks include:

Netflix's website in 2006 (when Netflix was still renting DVDs!), which allowed attackers to order DVDs for a victim, change the shipping address, or fully compromise the account by changing the login credentials.
ING Direct's online banking web application, which allowed attackers to transfer money from victims' accounts.
YouTube's website in 2008, which allowed attackers to perform nearly all actions as a given user.

Any web application that accepts HTTP requests from an authenticated user and does not implement a verification mechanism to ensure that the request is unique to the user's session is potentially vulnerable.

How does a CSRF attack work?

The vulnerability lies in the fact that a web application will trust any request sent by the user's browser as legitimate, even if the request was not meant to be sent by the user, but crafted by a malicious actor. From the server perspective though, the request looks totally valid and legitimate as if it was sent by the user themselves. This allows a malicious actor to basically impersonate a user. This particular attack works because authentication tokens are usually stored in cookies, and most browsers will send said cookies with each request.

[1] Alice logs into her bank account online portal. This sets a session cookie (A) that will be automatically sent with every subsequent request Alice's browser makes to the bank web app.
[2] Alice sends money to Bob. Attached with the request sent by her browser is the session cookie (A) previously generated. That allows the bank's backend to authenticate Alice and ensure the request is legitimate.
[3] In the meantime, Mallory crafts a script that will send a similar request, but sending money to her account instead. See below for more details on how to craft such scripts.
[4] Using social engineering, Mallory tricks Alice into visiting her website, which then tricks Alice's browser into sending Mallory's request to the bank's backend.
[5] Because the request stemmed from Alice's browser, it has Alice's session cookie (A) attached to it. The bank application is then tricked into believing this request comes from Alice and is legitimate, hence transferring money to Mallory.

URL-based attack

The most basic form of CSRF attack is URL-based. An attacker crafts a GET request with the desired URL, and embeds said URL in an image, for example. That image can then be sent via email to the victim or hosted in a website owned by the attacker that the victim then visits.

Let's say that there exists a banking web application built solely using GET requests, which stores session tokens in cookies, and that has no CSRF prevention method implemented.

For Alice to send $100 to Bob, the app will make the following request:
GET https://some-random-bank.com/transfer?account=BOB&amout=100

With that information in mind, Mallory can craft a valid request that would send her $1,000, namely:
GET https://some-random-bank.com/transfer?account=MAL&amount=1000

Now, for the social engineering part of the attack, Mallory embeds that URL into a zero-size image that she attaches to an email she sends Alice:

<img src="https://some-random-bank.com/transfer?account=MAL&amount=1000" width="0" height="0" border="0" />

When opening the email, Alice won't see anything suspicious, but her browser will make that request, and if Alice is logged in her online banking web application, the transaction will be successful and Mallory will receive $1,000 from Alice!

This works because the session cookies that authenticate Alice from the bank's application's perspective will be automatically attached to and sent with the malicious request.

Form-based attack

Alright, so I guess we can agree that using GET requests to perform actions with side-effects is not ideal. Unfortunately, using POST requests won't save us!

It might take Mallory a couple of lines of code more, but it is still possible (and quite trivial) to craft a POST request that can take advantage of a CSRF vulnerability.

Let's keep our online banking application from the previous example, only this time, the request to make a transfer is:

POST https://some-random-bank.com/transfer

account=BOB&amount=100

Now, Mallory cannot simply use a link or an image, but she can use a form, which she can embed in a web page she controls.

<form action="https://some-random-bank.com/transfer" method="POST">
  <input type="hidden" name="account" value="MAL" />
  <input type="hidden" name="amount" value="1000" />
  <input type="submit" value="Click here" />
</form>

As with the URL-based attacks, Alice doesn't even need to interact with the web page that includes the malicious form, as Mallory can automatically submit it when Alice visits her web page:

<body onload="document.forms[0].submit()">
  ...
  <form ...
</body>

All cookies (including authentication ones) will again be sent with the request, and Mallory pockets yet again $1,000!

XHR-based attack

OK, this is great, but what if we use a JSON API, and actually use other HTTP verbs such as PUT or DELETE? Well, still no luck!

Let's keep using the same banking example. This time, the request to transfer money is as follows:

PUT https://some-random-bank.com/transfer

{ "account": "BOB", "amount": 100 }

In that case, Mallory will have to work a little bit harder, but it is still a handful of lines of code:

<script>
function put() {
  var x = new XMLHttpRequest();
  x.open("PUT", "https://some-random-bank.com/transfer", true);
  x.setRequestHeader("Content-Type", "application/json");
  x.send(JSON.stringify({ "account": "MAL", "amount": 1000 }));
}
</script>

<body onload="put()">
  ...
</body>

Fortunately, this request will not execute in modern browsers thanks to same-origin policy restrictions, which is enabled by default. Careful though with allowing cross-origin requests, as that can allow attackers to bypass those restrictions. In particular, using the following CORS header will make the above CSRF attack possible:
Access-Control-Allow-Origin: *.

How to protect a web app from CSRF attacks?

Now that we have a better understanding of the risks of CSRF attacks, how do we protect a web application from such vulnerabilities?

Methods that do NOT work

Let's first look at some methods that do not work in protecting a web application from CSRF attacks and why that is the case.

Secret Cookie

One way one might think of preventing CSRF is by using a secret cookie to store the session token. Unfortunately, this method fails because all cookies, including secret cookies, are sent with every request.

Only POST Requests

Some past CSRF vulnerabilities came from the fact that some web application were using GET request to perform side effects on the server. Besides being a poor practice, this made URL-based CSRF attacks trivial to implement.

Hence, can the solution be only using POST requests? Unfortunately, as seen in the previous section, it is still possible to craft CSRF attacks using POST (or any other HTTP) requests.

Multi-Step Transactions

Maybe using multi-step transactions then? For example, we can require a first request to make a bank transfer, and a second to confirm? Unfortunately, this method also fails, as long as the attacker can predict the steps needed and craft malicious requests.

Prevention methods

Let's now look at some prevention techniques that do work in protecting a web application from CSRF attacks and why that is the case.

Synchroniser Token Pattern

One of the most common prevention methods is to generate a token on the server. A token can be generated per request or per session, the latter being slightly less secure but more convenient. The token is then sent with each request and validated before performing said request. The token is usually embedded in a hidden form field, or in a custom header. This means that a malicious CSRF request will not possess the token and will fail validation on the server, as only cookies are sent automatically, and the attacker has no way of accessing data on the web page.

For example, the server-side rendered HTML for a form could look like:

<form action="/transfer" method="POST">
  <input type="hidden" name="CSRFToken" value="BfbhY4e/7Qa7iWUMV09r5lm0mAdXnDHGBdYfgHCMnKf8yuxVcULDdEYSDYotrpmoo2NKGzuDyHjzD74QUyfq5g==">
  ...
</form>

Taking another look at our previous example with Alice and Mallory, by implementing this method, Alice's request to transfer money to Bob will contain the CSRF token, whereas Mallory has no way of guessing its value (even if she knows that she must also send a token), hence her malicious request won't be valid from the server's perspective.

This method is what most popular web frameworks implement.

Double Submit Cookie

If maintaining state on the server side is an issue, we can use the double submit cookie technique. The idea here is to send a random value both in a cookie and as part of the request (in a parameter or a header). If both values match, the server accepts the request as legitimate and proceeds.

This method works because the attacker doesn't have access to the value of the token stored in the cookie. Thus, when crafting the malicious request, they cannot include the same value as part of the request. The value in the cookie will automatically be sent to the server, but the validation will fail.

As subdomains can write cookies to the parent domain over HTTP, this technique only works if all subdomains are properly secured and only accept HTTPS. It is also possible to secure the cookie by using the __Host- cookie prefix. Another way to enhance the security of this method is to use an encrypted cookie to store the token.

SameSite Cookie Attribute

The SameSite cookie attribute aims to mitigate CSRF vulnerabilities by providing a hint to browsers if they should submit cookies with cross-origin requests.

Possible values are Strict, Lax, and None.

Strict prevents any cross-origin request to carry cookies. This means for example, that if you follow a link to a service where you are authenticated, the page that will be displayed won't be able to authenticate you, as no cookies will be submitted. This might not always be the intended user experience.

Lax, which is the default in some modern browsers, provides a better user experience while still ensuring that only top level navigation and safe HTTP method request are submitted with cookies.

This method is unfortunately not sufficient to fully protect users from CSRF attacks, and should instead be used in conjunction with previous methods.

Origin Headers

This method relies on examining HTTP request header values, in particular to find out the source origin (where is the request coming from) and the target origin (where is the request going to). If both values match, the server proceeds with the request as legitimate.

The reliability of the value in those headers come from the fact that they can only be set by the browser as they are in the forbidden headers list, meaning that they cannot be set programmatically.

The drawback of this method is that it can be difficult to accurately retrieve the values for source origin and target origin.

Custom Request Headers

An alternate method that works for AJAX or API endpoints is to set a custom request header, with the presence of this header being validated on the server. This method relies on same-origin policy to ensure that only JavaScript from the legitimate domain can set those headers.

This is a particularly attractive method for REST services, as it doesn't require the server to maintain any state. Unfortunately, this method doesn't cover vulnerabilities on <form>s.

The security of this method also depends on having robust CORS settings (as cross-origin requests with custom headers are pre-flighted and might expose the list of custom headers).

User Interaction Defense

Finally, we can also fend off CSRF attacks by altering the user interaction flow of certain actions. For example, we can ask the user to re-enter their password to confirm certain actions (like transferring funds).

This will impact the user experience though, so it might not make sense to solely rely on this technique to secure an entire web application.

Some implementations in popular web frameworks

As CSRF vulnerabilities basically exist in any web application with authentication, most web frameworks implement some sort of protection against them. Let's look at a few examples:

Django

Django implements a middleware and template tag to mitigate CSRF attacks. Note that "login CSRF" attacks are also covered. The CSRF middleware is activated by default.

For server-rendered markup, we can add the CSRF token in any form like follows:

<form method="post">{% csrf_token %}

For AJAX requests, a custom X-CSRFToken header needs to be appended to the requests. The value of the token can either be retrieved from a csrfToken cookie, or directly from the server-rendered markup:

{% csrf_token %}
<script>
  const csrftoken = document.querySelector('[name=csrfmiddlewaretoken]').value;
</script>

For more details, including how to handle some edge cases, feel free to check the official documentation: https://docs.djangoproject.com/en/3.2/ref/csrf/

Laravel

Laravel automatically generates CSRF tokens for each user session. It also uses a middleware by default to check the validate of said tokens.

The token can be accessed on the server via the following methods:

use Illuminate\Http\Request;

Route::get('/token', function (Request $request) {
    $token = $request->session()->token();
    // or
    $token = csrf_token();
});

For server-rendered markup, the following code allows to embed the token in forms:

<form method="POST" action="/profile">
    @csrf
    <!-- Equivalent to... -->
    <input type="hidden" name="_token" value="{{ csrf_token() }}" />
</form>

For AJAX request, the token can be retrieved from a meta tag and sent as a custom X-CSRF-TOKEN header:

<meta name="csrf-token" content="{{ csrf_token() }}">

$.ajaxSetup({
    headers: {
        'X-CSRF-TOKEN': $('meta[name="csrf-token"]').attr('content')
    }
});

Finally, the token is also set in a secure cookie XSRF-TOKEN.

For more details, including how to handle some edge cases, feel free to check the official documentation: https://laravel.com/docs/8.x/csrf

Express

Express doesn't implement mitigation for CSRF attacks by default, but provides an npm package: csurf.

That package can be used to implement either the synchroniser token pattern (which requires a session middleware such as express-session), or the double submit cookie method (which requires the cookie-parser middleware).

The value of the token can be retrieved via the req object:

req.csrfToken();

For server-rendered markup, the following code can be used:

var cookieParser = require('cookie-parser')
var csrf = require('csurf')
var bodyParser = require('body-parser')
var express = require('express')

// setup route middlewares
var csrfProtection = csrf({ cookie: true })
var parseForm = bodyParser.urlencoded({ extended: false })

// create express app
var app = express()

// parse cookies
// we need this because "cookie" is true in csrfProtection
app.use(cookieParser())

app.get('/form', csrfProtection, function (req, res) {
  // pass the csrfToken to the view
  res.render('send', { csrfToken: req.csrfToken() })
})

app.post('/process', parseForm, csrfProtection, function (req, res) {
  res.send('data is being processed')
})

<form action="/process" method="POST">
  <input type="hidden" name="_csrf" value="{{ csrfToken }}">

  Favorite color: <input type="text" name="favoriteColor">
  <button type="submit">Submit</button>
</form>

For AJAX request, the token can be retrieved from a meta tag and sent as a custom CSRF-Token header:

<meta name="csrf-token" content="{{ csrfToken }}">

// Read the CSRF token from the <meta> tag
var token = document.querySelector('meta[name="csrf-token"]').getAttribute('content')

// Make a request using the Fetch API
fetch('/process', {
  credentials: 'same-origin', // <-- includes cookies in the request
  headers: {
    'CSRF-Token': token // <-- is the csrf token as a header
  },
  method: 'POST',
  body: {
    favoriteColor: 'blue'
  }
})

Finally, in some cases it might also be possible to send the token via a cookie, most notably for single-page applications:

app.all('*', function (req, res) {
  res.cookie('XSRF-TOKEN', req.csrfToken())
  res.render('index')
})

For more details, including how to handle some edge cases, feel free to check the official documentation: http://expressjs.com/en/resources/middleware/csurf.html

Spring

Spring provides CSRF mitigation by default since Spring Security 4.0.

For server-rendered markup, the following example shows how to embed a CSRF token to a form:

<c:url var="logoutUrl" value="/logout"/>
<form action="${logoutUrl}"
    method="post">
<input type="submit"
    value="Log out" />
<input type="hidden"
    name="${_csrf.parameterName}"
    value="${_csrf.token}"/>
</form>

For AJAX requests, the token can be embedded in a meta tag and retrieved via JavaScript on the client:

<html>
<head>
    <meta name="_csrf" content="${_csrf.token}"/>
    <!-- default header name is X-CSRF-TOKEN -->
    <meta name="_csrf_header" content="${_csrf.headerName}"/>
    <!-- ... -->
</head>
<!-- ... -->

$(function () {
var token = $("meta[name='_csrf']").attr("content");
var header = $("meta[name='_csrf_header']").attr("content");
$(document).ajaxSend(function(e, xhr, options) {
    xhr.setRequestHeader(header, token);
});
});

It is also possible to persist the CSRF token in a cookie, by default XSRF-TOKEN, and expect the value back in a custom X-XSRF-TOKEN header.

For more details, including how to handle some edge cases, feel free to check the official documentation: https://docs.spring.io/spring-security/site/docs/5.0.x/reference/html/csrf.html

Login CSRF

A related type of attack that we haven't discussed at all so far is login CSRF. This attack is somewhat similar to the previous we have discussed, but targets login forms, making the impact and risk different.

Login CSRF can be mitigated by creating pre-sessions and embedding the token in the login form, or using any of the techniques previously discussed.

References

Building a link shortening service

Antonio Villagra De La Cruz — Wed, 06 Oct 2021 18:24:07 +0000

Time for a nice little side project: let's build a link shortening service!

Actually, more than giving you all the code to achieve it, we will go over the process of spec'ing and architecting one such service, following a given set of constraints.

Product constraints

Links can be long and cumbersome to pass around. Most existing link shortening which are free, usually might be collecting extra data on their usage. Hence, the idea of building a simple, free, open-source, safe, and privacy-conscious link shortening service.

As this is a very self-contained problem, we can cover all its use cases in just two user stories:

As a user, I want to be able to paste a link I want to shorten and be given back a shortened link.
As a user, when opening a shortened link, I want to be redirected to the original link.

Technical specifications

API

Most links are shared over the web. As such, we will be building a web application. That means that we will have a client and a server communicating over some sort of API, so let's start by defining that API.

Users can interact with our application in two ways: either when creating a short link from a given link, or when accessing a shortened link and being redirected to the original link.

Creating a shortened link

To create a shortened link, we will expose an endpoint that implements a POST request. To keep it as RESTful as possible, we implement this endpoint against a /link path.

This endpoint expects a body with a link property being a string, and it returns a corresponding hash (more on that in the implementation!).

POST /link
body:
  link: String
returns:
  hash: String

Retrieving the original link from a hash

The opposite operation of creating a shortened link, is retrieving the original link. Similarly to the above endpoint, we follow RESTful principles and implement a GET request on the path /link.

This endpoint expects the hash as a query parameter, and returns the corresponding link.

GET /link
params:
  hash: String
returns:
  link: String

Data Model

The data model to support this application is fairly straightforward. As we will be using a PostgreSQL database, we will create the following table to persist the needed data:

CREATE TABLE IF NOT EXISTS links (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  hash VARCHAR(8),
  url TEXT,
  created_at TIMESTAMP DEFAULT NOW()
);

We won't be storing anything else: simple and private!

Read operations will heavily rely on hash, as such, it might be a good idea to create an index on that column:

CREATE UNIQUE INDEX IF NOT EXISTS hash_idx on links (hash);

Cron jobs

As we want to provide this service for free, we might need to keep within reasonable quotas from cloud providers. Hence, to limit the size of the database, we will automatically delete older links to provide space for newer ones.

To achieve that, we will run a cron job every 24 hours and delete all links older than 30 days.

"Hashing" procedure

Finally onto the "hashing" function. There are a lot of great libraries implementing hashing functions that we could use, but to keep our guarantee to have a link live only for 30 days, instead we will be using a random string generator.

In that sense, we are not so much hashing as just pairing a link with a random string. This also means that, unlike with hashing, the same link will generate different "hashes". This is, again, in line with how we have defined our requirements, but might not be the ideal solution in other scenarios.

The string we will generate will be comprised of all 26 letters of the English alphabet, both lower case and upper case, which mean that a 4-character random string will yield about 7 million unique random strings. That number goes up to about 380 million with a 5-character random string, and up to about 19 billion with a 6-character string. Here, we can strike a balance between the size of the final hash and the possible unique permutations.

(Partial) implementation

We will be implementing this service using as much vanilla Go, PostgreSQL, JavaScript, HMTL, and CSS as possible.

Quick disclaimer before we dive into the implementation. I am not the most experienced Go developper, and as such the way I've decided to structure the code might not be the most idiomatic way to do so, but it was the way that made most sense to me.

Static assets

All static assets (HTML, JavaScript and CSS) live inside the public folder, and are served by our web server directly. This might not be the most scalable approach, but let's not get into premature optimisation.

main.go

func main() {
    ...
    // Static assets
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        http.ServeFile(w, r, "public/index.html")
    })
    http.Handle("/static/",
        http.StripPrefix("/static/", http.FileServer(http.Dir("./public"))),
    )
    ...
}

The code here is quite uneventful, as we serve index.html on the root path, and then setup a file server for the rest of the assets.

API

As we are trying to be as vanilla as possible (i.e. mostly using the standard library), we will be implementing the API in a fairly exotic manner: we will define API routes and methods in functions.

In our case, we really only have one route and 2 methods, so the code is fairly straightforward:

api/api.go

package api

import (
    "net/http"
    "url-shortener/api/handlers"
)

func Link(w http.ResponseWriter, r *http.Request) {
    var status int
    var data string

    switch r.Method {
    case "POST":
        status, data = handlers.CreateHash(r)
    case "GET":
        status, data = handlers.GetLink(r)
    default:
        status = http.StatusNotImplemented
        data = ""
    }

    w.WriteHeader(status)

    if data != "" {
        w.Header().Set("Content-Type", "application/json")
        w.Write([]byte(data))
    }
}

Handlers are also functions that return (int, string), which correspond to the status code and any JSON string we'd like to send back to the client.

Here is for example GetLink():

api/handler/get_link.go

package handlers

import (
    "log"
    "net/http"
    "url-shortener/db"
)

func GetLink(r *http.Request) (int, string) {
    hash := r.URL.Query().Get("hash")
    if hash == "" {
        return http.StatusBadRequest, ""
    }

    log.Printf("Redirecting from hash: '%s'", hash)

    link, err := db.SelectLink(hash)
    if err != nil {
        log.Printf("Link not found for hash: '%s'. Error: %v\n", hash, err)
        return http.StatusNotFound, ""
    }

    return http.StatusOK, `{"link": "` + link + `"}`
}

Finally, we register the main API handler function in main.go:

func main() {
    // API
    http.HandleFunc("/api/link", api.Link)
    ...
}

Data layer

To continue with our constraint of mostly using the standard library, we will be writing all our database queries in .sql files, which we then need to read and pass to a PostgreSQL driver (in this case pgx).

Because we want our service to be able to run from slate environments, we need to surface a way to create the needed data model. We also want to read our SQL files into variables once and then just handle strings throughout the lifetime of the application.

db/db.go

package db

import (
    "context"
    "io/ioutil"
    "log"
    "os"

    "github.com/jackc/pgx/v4/pgxpool"
)

func Init() {
    // Check needed tables are created
    ...

    // Create needed tables
    ...

    // Read other SQL files to be used in API handlers
    initQuerries()
}

The file that does most of the heavy lifting in terms of providing an interface to the handlers is dbquerries.go where we read the SQL files and surface functions for the defined database operations:

db/dbquerries.go

package db

import (
    "context"
    "io/ioutil"
    "log"
)

var insertLinkSQL []byte
var selectLinkSQL []byte

func initQuerries() {
    var err error

    insertLinkSQL, err = ioutil.ReadFile("db/sql/insert-link.sql")
    if err != nil {
        log.Fatalf("Error while reading file 'db/sql/insert-link.sql': %v\n", err)
    }

    selectLinkSQL, err = ioutil.ReadFile("db/sql/select-link.sql")
    if err != nil {
        log.Fatalf("Error while reading file 'db/sql/select-link.sql': %v\n", err)
    }
}

func InsertLink(hash string, link string) error {
    dbpool, err := getPool()
    if err != nil {
        log.Printf("Unable to connect to database: %v\n", err)
        return err
    }
    defer dbpool.Close()

    _, err = dbpool.Exec(context.Background(), string(insertLinkSQL), hash, link)

    return err
}

func SelectLink(hash string) (string, error) {
    dbpool, err := getPool()
    if err != nil {
        log.Printf("Unable to connect to database: %v\n", err)
        return "", err
    }
    defer dbpool.Close()

    var link string
    err = dbpool.QueryRow(context.Background(), string(selectLinkSQL), hash).Scan(&link)

    return link, err
}

And here are the corresponding SQL files:

db/sql/insert-link.sql

INSERT INTO links (
  hash,
  url
) VALUES ($1, $2);

db/sql/select-link.sql

SELECT url 
FROM links 
WHERE hash = $1;

Cron job

Probably the least interesting for last, we again look at simplicity over scalability here, and with simply define tickers inside our jobs (or just one for now really!).

cron/cron.go

package cron

func Init() {
    AutoDeleteLinksJob()
}

The Init() function is called in main.go when starting the server, and it contains all the existing jobs, in this case just the following one:

cron/auto-cleanup.go

package cron

import (
    "time"
    "url-shortener/db"
)

func AutoDeleteLinksJob() {
    db.DeleteOldLinks()

    ticker := time.NewTicker(24 * time.Hour)
    go func() {
        for range ticker.C {
            db.DeleteOldLinks()
        }
    }()
}

As discussed previously, here we simply use a ticker to run a database query every 24 hours. That query simply deletes all links older than 30 days.

delete-links-old.sql

DELETE 
FROM links 
WHERE created_at < current_timestamp - interval '30 days';

There you have it! Probably not the most solid implementation, but it should do the job!

I hope this was either useful, or entertaining, or both! There is still a lot of room for improvement both in terms of product and of code, but hopefully this gives a good overview of what such a project can look like.

You can actually have a closer look at all the code base here:

AntonioVdlC / url-shortener

🔗 - Shortened links, no frills!

url-shortener

View on GitHub

What my ideal interview process looks like

Antonio Villagra De La Cruz — Mon, 27 Sep 2021 19:49:44 +0000

Talk with any software engineer, and they will gladly tell you that software engineer interviewing is sorely broken. There is an incessant thread of articles and opinions about how the interview process should be like. I contributed to the already vast literature around interviews a few years ago, when I wrote an article where I explored some learnings and personal opinions about interviews.

This time though, I'd like to look at the same problem but from a different perspective, trying to imagine and come up with what my ideal interview process, from a candidate's perspective, would look like.

By the very nature of this exercise, the result will be fairly biased to my own experience (and probably what I perceive as my own strengths). It will end up being more how I'd like to be interviewed rather than how software engineers should be interviewed, but it might still be useful and insightful, or at the very least trigger a constructive conversation on this topic.

Let's first look at some overarching guidelines I wish where built into all interview processes. At a minimum, interviews should be humane, transparent, and fair. Now what do I mean by that?

Interviews are (for the most part) human interactions. As a candidate, I would like to be treated as a fellow human, and the interviewers in the process should be cordial if not friendly. As much as possible, the interview process should be accommodating. I want to be in a position where I am comfortable enough to perform at my very best. Creating such an environment is also beneficial for the company, as they can assess candidates at their best. Being considerate of people's time is also something I wish to see in my ideal interview process. Do companies really need a week to get back to a candidate after a 30-minute interview? Ultimately, interviews should be treated as an exchange of ideas and a learning opportunity from both sides of the table.

My ideal interview process is transparent. Starting from the job description, it is clear what the company does, which are the requirements for the position, and what are the steps that comprise the interview process. During the interviews, I'd expect plenty of opportunities to ask questions about the company, the job, the team, etc ... Finally, regardless of if my profile ends up fitting the position and the company, detailed and actionable feedback should always be freely provided at the end of each step.

At last, as this is in a way a utopic exercise, my ideal interview process is fair. The company should have a clear idea of what signals they are looking for in a candidate, and how those signals correlate to success in the position they are interviewing for. As such, most questions asked during the interview process should be related to the actual day-to-day role. I would also expect the interview process to be as unbiased as possible. In practice, that means, among other things, having a multiple and diverse set of interviewers to interact with.

Now that we have set up some guidelines, let's get into the format my ideal interview process would have.

Of course, it all starts with the egg (or was it the chicken?): the job description. As described in the above section, the job description should be, among other things, as accurate as possible about the role. Do I need to perform guitar solos on a weekly basis? Then you probably don't need a rock-star engineer! In my ideal process, my resume (and cover letter if required), would be reviewed by a fellow human being. If my resume gets rejected, it would be highly appreciated to get some feedback as to why my profile didn't match, instead of a generic rejection email, or just plain silence. That is even more true if my application ends up being rejected, not by a human, but by an automated system.

Companies might base their decisions on a lot of diverse factors, but ultimately the interview process fits the purpose of assessing candidates for their skill set and their culture fit. A lot of keystrokes have been exchange about the best way to assess software engineering skills, with each side of the debate bringing up decent arguments. As this is my very own ideal interview process, I will unapologetically talk about my own perspective on the matter. Not everyone needs to have publicly available code (e.g. on GitHub), but if I make the effort to maintain open-source projects, I expect my interviewers to pick cues and signals from those, and only require coding challenges if they are unable to check all the signals they are looking for. Please, don't make me write yet another weather app as part of your interview process ...

Writing code is arguably the easiest part of the job as a software engineer. My ideal interview process would focus a lot more on understanding existing code, communicating as a team, and being able to understand and break down complex problems. None of that requires me to spend a week-end (or more) writing some useless code. Most interview rounds should be centered around conversations about tech, past experiences, and future perspectives. Culture fit should very closely tie to company values and have a predefined set of questions and signals to look for in candidates. Conversations about culture fit should provide enough room for candidates to reverse interview the company they are applying to.

Usual last steps in any interview process include reference calls and contract negotiations.

I've always doubted the actual utility of reference calls, other than checking that a candidate has worked with a couple of people with whom they got along well. The signals provided by reference checks are usually extremely skewed towards candidates, as most people won't volunteer references that might not talk in glowing terms about them. It feels like the very last chance companies give themselves to uncover any red flags their process might have missed. As such, my ideal interview process would go without any reference checks and instead trust itself and the interviewers to uncover all the needed signals to make an informed hiring decision.

Now, my ideal interview process will also go without any contract negotiations. Salaries and career paths should be completely transparent and clearly communicated during the interview process. Signals gathered from the process would then put me in the corresponding box in the grid. There is a lot to say about salary negotiation and how not having transparent compensation schemes in companies hurt underrepresented groups in the workplace, so I won't paraphrase what more eloquent people than me have expressed multiple times.

Finally, as signing a contract is usually the beginning of a journey, my ideal interview process would very naturally flow into my ideal on-boarding process, but that's probably a discussion for a different article!

If your company's interview process looks surprisingly similar to what I've described above, and you are looking for a software engineer, please feel free to reach out!

Optimising a JavaScript library with WebAssembly, a failed attempt!

Antonio Villagra De La Cruz — Tue, 21 Sep 2021 21:54:51 +0000

Rust is becoming more and more the language of choice to build tools for the web. Last example to date, Rome announced it will be using Rust.

Historically, Rust has also been one of the languages of choice to target WebAssembly, which has now shipped in all major browsers. One of the main benefit of using WebAssembly is that it is more performant than plain JavaScript code, in most cases. Hence, the idea to try and optimise the latest library I released (https://github.com/AntonioVdlC/range) by re-writting it in Rust!

But first things first. A very smart person once said that you could only improve what you could measure. So before going any further, let's look at how we can measure the performance of the @antoniovdlc/range library.

There are a few good options to run benchmarks in Node (for example, the aptly named benchmark library, or tiny-benchy which is used by Parcel), but for the sake of this exercise, let look into a lower-level API and directly use Node's perf_hooks

#!/usr/bin/env node

const { performance, PerformanceObserver } = require("perf_hooks");

const range = require("../dist/index.cjs");

const testBenchmark = performance.timerify(function testBenchmark() {
  let sum = 0;
  let i = 0;

  const r = range(0, process.env.SIZE);
  while (!r.next().done) {
    sum += i;
    i++;
  }

  return sum;
});

const obs = new PerformanceObserver((list) => {
  const entries = list.getEntries();
  const avgDuration =
    entries.reduce((sum, cur) => (sum += cur.duration), 0) / entries.length;

  console.log(`range(0, ${process.env.SIZE}): ${avgDuration}s`);
  obs.disconnect();
});

obs.observe({ entryTypes: ["function"] });

for (let i = 0; i < 1000; i++) {
  testBenchmark();
}

What the code above does is run 1,000 times a function which loops over a range of a given size and does a simple sum operation in each iteration. The benchmark is then calculated as the average time of all those 1,000 runs.

With the in hand, let's first look at the current implementation's performance:

range(0, 100): 0.007962769627571106s
range(0, 1000): 0.015898147106170653s
range(0, 10000): 0.08853049981594086s
range(0, 100000): 0.8147728093862534s
range(0, 1000000): 7.5012646638154985s

Honestly, not too shabby! Can we do better with Rust and WebAssembly?

If you want to follow along, please make sure to install Rust and its toolchain.

To compile our Rust code to WebAssembly, we will be using wasm-pack

It can be installed either with Cargo, or directly via npm:

npm i -D wasm-pack

We can then add the following script to our package.json:

{
  ...
  "scripts": {
    ...
    "build:wasm": "wasm-pack build --target nodejs"
  }
}

Now let's write some Rust code!

The first thing we will do is declare a struct called Range, which would be very similar to our implementation of ranges in JavaScript.

#[wasm_bindgen]
pub struct Range {
    _start: i32,
    _stop: i32,
    _step: i32,
    _inclusive: bool,

    // Counter used for iteration, so that we can iterate multiple times over
    // the same range
    i: i32,
}

#[wasm_bindgen]
impl Range {
    #[wasm_bindgen(constructor)]
    pub fn new(start: i32, stop: i32, step: i32, inclusive: bool) -> Range {
        Range {
            _start: start,
            _stop: stop,
            _step: if step != 0 { step } else { 1 },
            _inclusive: inclusive,
            i: start,
        }
    }
}

To surface a similar API to what we first implemented in JavaScript, we also write the following range function:

#[wasm_bindgen]
pub fn range(start: i32, stop: i32, step: i32, inclusive: bool) -> Result<Range, JsValue> {
    if start > stop {
        return Err(Error::new(
            (format!("Cannot create a range from {} to {}", start, stop)).as_str(),
        )
        .into());
    }

    return Ok(Range::new(start, stop, step, inclusive));
}

We can go on and implement the getters and other methods, but before investing too much on this exercise, let's focus on implementing the .next() method so that we can run our benchmarks on the compile WebAssembly code.

#[wasm_bindgen]
pub struct JsIteratorResult {
    pub value: Option<i32>,
    pub done: bool,
}

#[wasm_bindgen]
impl Range {
    #[wasm_bindgen]
    pub fn next(&mut self) -> JsIteratorResult {
        if self._inclusive && self.i <= self._stop || self.i < self._stop {
            let value = self.i;
            self.i = self.i + self._step;

            return JsIteratorResult {
                value: Some(value),
                done: false,
            };
        }

        self.i = self._start;

        return JsIteratorResult {
            value: None,
            done: true,
        };
    }
}

The above implementation is again extremely similar to the JavaScript code.

After compiling the above Rust code into WebAssembly, let's look at the benchmark ...

range(0, 100): 0.018000024318695067s
range(0, 1000): 0.09116293668746948s
range(0, 10000): 2.4152168154716493s
...

... and unfortunately, the numbers where more than disappointing.

It seems like the WebAssembly version of that specific library is orders of magnitude slower. This is probably mostly due to my inexperience with Rust and WebAssembly in general, and there are definitely ways to look deeper into what is causing such a lackluster performance, but it is also OK to fail, stop, and look for the next challenge!

This was an interesting experiment, and even though the end result wasn't as expected, it was still a great learning opportunity!

If you want to look and tinker around the full Rust code base, you can check out: https://github.com/AntonioVdlC/range/tree/wasm.

Maybe there are some obvious mistakes you can point me to!

Implementing ranges in JavaScript

Antonio Villagra De La Cruz — Tue, 14 Sep 2021 16:56:24 +0000

Ranges are natively supported by a few (popular) programming languages. They allow for iteration over a defined space, while not have a linear increase in their memory footprint (all ranges always store a similar amount of data).

Let's try adding a similar idiom to JavaScript!

One way to approach this challenge is to write a plugin for a transpiler (for example a babel plugin) that would allow the following syntax:

const range = (0..5)
for (let i of range){
  console.log(i)
  // 0, 1, 2, 3, 4
}

Instead, we will provide a similar functionality with vanilla JavaScript.

for (let i of range(0, 5)) {
  console.log(i)
  // 0, 1, 2, 3, 4
}

We does the range stop at 4 instead of 5? This is a design choice, and as most languages that have a built-in range as not inclusive of their last value, the range utility that we will build will follow a similar convention by default.

The above syntax also allows us to pass a third argument to the function to control the step in between each iteration:

for (let i of range(0, 10, 2)) {
  console.log(i)
  // 0, 2, 4, 6, 8
}

To start, let's create a class Range which will host the data needed for a range:

class Range {
  constructor(start, stop, step = 1) {
    this._start = Number(start);
    this._stop = Number(stop);
    this._step = Number(step);

    // Initialise a counter for iteration
    this.i = Number(start);
  }

  first() {
    return this._start;
  }

  last() {
    return this._stop;
  }

  step() {
    return this._step;
  }
}

We can now create a very basic (and not very useful) range:

const range = new Range(0, 10);

range.first(); // 0
range.last(); // 10
range.step(); // 1 (by default)

One of the main reasons we want ranges though is to iterate over them ... so let's implement iteration protocols in our Range class!

To do so, we need to implement a next() method, as well as a [Symbol.iterator] method.

class Range {
  constructor(start, stop, step = 1) {
    ...

    // Initialise a counter for iteration
    this.i = Number(start);
  }

  first() { ... }
  last() { ... }
  step() { ... }

  next() {
    if (this.i < this._stop) {
      const value = this.i;
      this.i += this._step;
      return { value, done: false };
    }

    return { value: undefined, done: true };
  }

  [Symbol.iterator]() {
    return this;
  }
}

Great! Now we can use our ranges as follow:

const range = new Range(0, 5)

for(let i of range) {
  console.log(i)
  // 0, 1, 2, 3, 4
}

const range = new Range(0, 5)

range.next() // { value: 0, done: false }
range.next() // { value: 1, done: false }
range.next() // { value: 2, done: false }
range.next() // { value: 3, done: false }
range.next() // { value: 4, done: false }
range.next() // { value: undefined, done: true }

There is one issue with our current implementation though, and that is that the range is depleted after a single iteration. We cannot reuse the same range in multiple consecutive loops.

Luckily, there is a one line fix to support that:

class Range {
  constructor(start, stop, step = 1) {
    ...

    // Initialise a counter for iteration
    this.i = Number(start);
  }

  first() { ... }
  last() { ... }
  step() { ... }

  next() {
    if (this.i < this._stop) {
      const value = this.i;
      this.i += this._step;
      return { value, done: false };
    }

    // We reset the value once we have iterated over all values so that
    // ranges are reusable.
    this.i = this._start;

    return { value: undefined, done: true };
  }

  [Symbol.iterator]() {
    return this;
  }
}

Finally, to achieve the semantics we defined at the beginning, we need to wrap our class creation in a function:

class Range { ... }

function range(start, stop, step = 1) {
  return new Range(start, stop, step);
}

for (let i of range(0, 5)) {
  console.log(i)
  // 0, 1, 2, 3, 4
}

Again, inspired by this blog post, I decided to build a library with the aforementioned features and much more! Check it out:

AntonioVdlC / range

⛰ - Implement ranges in JavaScript

range

Implement ranges in JavaScript.

Installation

This package is distributed via npm:

npm install @antoniovdlc/range

Motivation

Ranges are natively supported by a few (popular) programming languages. They allow for iteration over a defined space, while not having a linear increase in their memory footprint (all ranges always store a similar amount of data).

Usage

You can use this library either as an ES module or a CommonJS package:

import range from "@antoniovdlc/range";

- or -

const range = require("@antoniovdlc/range");

To create a range:

const start = 0;
const stop = 10;
const step = 2; // Defaults to `1` if not passed
const inclusive = true; // Defaults to `false` if not passed

const r = range(start, stop, step, inclusive);

You can also pass an options object for convenience:

const start = 0;

…

View on GitHub

Sorting an array in JavaScript, a utility perspective!

Antonio Villagra De La Cruz — Tue, 07 Sep 2021 19:49:18 +0000

If you have written some JavaScript and manipulate slightly complex data, you have had to write some code like this to sort an array of objects:

const data = [
  { name: "Alice", age: 22 },
  { name: "Bob", age: 32 },
  { name: "Carl", age: 63 },
  { name: "Clara", age: 28 },
  ...
];

data.sort(function(a, b) {
  if (a.name < b.name) {
    return -1;
  }

  if (a.name > b.name) {
    return 1;
  }

  return 0;
})

// Or, as a one-liner: 
data.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)

While this is perfectly fine for one-off sorting of shallow objects, it can get a bit more complex and repetitive when having to sort based on nested fields.

Something else you might have tripped on while using the native .sort() on arrays, is the following behaviour:

const array = [1, 2, 3, 10, 23]
console.log(array.sort())
// [1, 10, 2, 23, 3]

Indeed, by default, the comparison function used by .sort() treats each element as a string! To make the above example work, you need to pass a custom comparison function such as the following one-liner:

const array = [1, 23, 3, 10, 2]
console.log(array.sort((a, b) => a - b))
// [1, 2, 3, 10, 23]

As sorting is a common operation on arrays, a more scalable and less error-prone strategy would be to define common compare functions. Let's build said compare functions!

First, let's look at the API we would like to end up with:

const array = [1, 23, 3, 10, 2]
array.sort(numerically)
// Should be equivalent to:
array.sort((a, b) => a - b)

array.sort(numerically.desc)
// Should be equivalent to:
array.sort((a, b) => b - a)
// For completeness, we can also expose `numerically.asc`.

To achieve the above API, we can define numerically as follows:

function numerically (a, b) {
  return a - b;
}

As in JavaScript, (almost) everything is an object, we can then add a desc and an asc field to the numerically function as follows:

numerically.desc = function(a, b) {
  return b - a;
}

numerically.asc = function(a, b) {
  return numerically(a, b); // This works because we sort from lower to higher by default!
}

Now that we have defined compare functions to work on arrays holding primitives values, let's generalise it to arrays of objects:

const data = [
  { name: "Alice", age: 22 },
  { name: "Bob", age: 32 },
  { name: "Carl", age: 63 },
  { name: "Clara", age: 28 },
  ...
];

data.sort(alphabetically.by("name"))
// Should be equivalent to:
data.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)

To achieve that, let's create a small utility function that will help us retrieve the value of an object based on a key path:

function getValueByKey(obj, key) {
  return String(key)
    .split(".")
    .reduce((acc, cur) => acc?.[cur] ?? null, obj);
}

With the code above, we can do deep object look-ups!

With that in hand, let's add the following to our example alphabetically sort function:

function alphabetically (a, b) { ... }

alphabetically.desc = function(a, b) { ... }
alphabetically.asc = function(a, b) { ...}

alphabetically.by = function(key) {
  return function(a, b) {
    const aVal = getValueByKey(a, key);
    const bVal = getValueByKey(b, key);

    return a < b ? -1 : a > b ? 1 : 0;
  }
}

Alright, this works great for ascending order sorting, but how could we implement descending order? There are different ways of solving this:

Pass another argument that can have either "desc" or"asc" values (defaults to "asc")
Append a - sign in the key (for example: sort(alphabetically.by("-name"))
Add .desc() and .asc() functions to our new function .by()

Either designs are fine, but to stay consistent with our previous utility function, we will be adding the ordering feature as follow:

data.sort(alphabetically.by("name").desc)

All implemented, it looks like:

function alphabetically (a, b, direction = 1) {
  if (a < b) {
    return -1 * direction;
  }

  if (a > b) {
    return 1 * direction;
  }

  return 0;
}

alphabetically.asc = (a, b) => alphabetically(a, b, 1);
alphabetically.desc = (a, b) => alphabetically(a, b, -1);

alphabetically.by = function(key) {
  function compareBy(a, b, direction = 1) {
    const aVal = getValueByKey(a, key);
    const bVal = getValueByKey(b, key);

    return aVal < bVal ? -1 * direction : aVal > bVal ? 1 * direction : 0;
  }

  compareBy.asc = (a, b) => compareBy(a, b, 1);
  compareBy.desc = (a, b) => compareBy(a, b, -1);

  return compareBy;
}

I found this exercise particularly interesting, and decided to build a library with some of the ideas discussed in this post. You can have a look at it here:

AntonioVdlC / sort

🔁 - Custom compare functions for sorting arrays

sort

Custom compare functions for sorting arrays.

Installation

This package is distributed via npm:

npm install @antoniovdlc/sort

Motivation

Sorting arrays is a common operation in JavaScript, so this library provides some common custom compare functions to have a more declarative way of sorting arrays.

Usage

You can use this library either as an ES module or a CommonJS package:

import { alphabetically, chronologically, numerically } from "@antoniovdlc/sort";

- or -

const { alphabetically, chronologically, numerically } = require("@antoniovdlc/sort");

Examples

All compare functions can be used out of the box for sorting as follows:

import { numerically } from "@antoniovdlc/sort";

const arr = [1, 2, 2, 23, 30, 4];
arr.sort(numerically); // [1, 2, 2, 4, 23, 30]

By default, sorting is doing in an ascending fashion. All…

View on GitHub

Template tags are just functions!

Antonio Villagra De La Cruz — Tue, 31 Aug 2021 17:20:23 +0000

A few years ago, ES6 introduced template literals, allowing among other things for multi-line strings, embedded expressions, and string interpolation.

That means that the following snippets of code could be written as follow:

console.log("This is the first line of a multi-line string.\n"
+ "And this is the second line!");

console.log(`This is the first line of a multi-line string.
And this is the second line!`);

const a = 22;
const b = 20;

console.log("The answer to the ultimate question of life, the universe, and everything is " + (a + b) + "!");

console.log(`The answer to the ultimate question of life, the universe, and everything is ${a + b}!`);

Template literals are already fairly useful with the above syntactic features, but there is more: template literals can be tagged!

Template tags are (mostly) functions that take in an array of strings as their first argument, and all expressions as the following arguments. Tags can then parse template literals as they see fit and return whichever value they see fit (not limited to strings).

const name1 = "Alice";
const name2 = "Bob";

function myTag (strings, fromName, toName) { 
  console.log(strings); // ["Template literal message from", " to ", " ..."]
  console.log(fromName); // "Alice"
  console.log(toName); // "Bob"

  ... 
}

console.log(myTag`Template literal message from ${name1} to ${name2} ...`);

If no tags are provided to the template literal, the default tag simply concatenates the strings and expressions into a single string, for example:

function defaultTag(strings, ...expressions) {
  let str = "";
  for (let i = 0, l = strings.length; i < l; i++) {
    str += strings[i] + (expressions[i] != null ? expressions[i] : "");
  }
  return str;
}


const name1 = "Alice";
const name2 = "Bob";
const a = 22;
const b = 20;

console.log(defaultTag`Template literal message from ${name1} to ${name2}: 'The answer to the ultimate question of life, the universe, and everything is ${a + b}!'`);

// "Template literal message from Alice to Bob: 'The answer to the ultimate question of life, the universe, and everything is 42}!'"

Note that there will always be more strings than expressions as empty strings will be added around expressions.

Now, we can probably build something a bit more interesting than just the default tag being applied to templates without tags!

Let's build a template tag that would allow us to format currency and numbers in certain ways. To better understand what we will build, let's look at an example:

const name = "Alice";
const number = 42;
const price = 20;

console.log(fmt`${name}:s has ${number}:n(1) oranges worth ${price}:c(USD)!`);
// "Alice has 42.0 oranges worth US$20.00!"

This particular example is based on this article by Jack Hsu about building an internationalization library with template tags. Definitely worth a read!
https://jaysoo.ca/2014/03/20/i18n-with-es2015-template-literals/

Here, we specify that the value interpolated by ${name} should be treated as a string, the value interpolated by ${number} should be displayed as a number with one digit, and that the value interpolated by ${price} should be displayed with the USD currency, all that while respecting the user's locale.

First, we need to define a way to extract the formatting information from the string literals:

const fmtRegex = /^:([a-z])(\((.+)\))?/;

function extractFormatOption(literal) {
  let format = "s";
  let option = null;

  const match = fmtRegex.exec(literal);
  if (match) {
    if (Object.keys(formatters).includes(match[1])) {
      format = match[1];
    }

    option = match[3];
  }

  return { format, option };
}

As an aside, every time I'm using regular expressions I am reminded of the following quote:

Some people, when confronted with a problem, think "I know, I'll use regular expressions." Now they have two problems. - Jamie Zawinski

But anyway, here we use a regular expression to match strings with our previously defined format, starting with : then a lower case letter, then an optional extra information in parenthesis.

The extractFormatOption() function simply helps us return the value of format and whatever option might have been passed as well. For example:

const { format, option } = extractFormatOption(`:c(USD)!`)
// format = "c"
// option = "USD"

Next, we need a way to actually format those values. We will use an object whose fields correspond to the potential values of format.

const formatters = {
  c(str, currency) {
    return Number(str).toLocaleString(undefined, {
      style: "currency",
      currency,
    });
  },
  n(str, digits) {
    return Number(str).toLocaleString(undefined, {
      minimumFractionDigits: digits,
      maximumFractionDigits: digits,
    });
  },
  s(str) {
    return str != null ? str.toLocaleString() : "";
  },
};

Finally, we update our defaultTag() function to support extra formatting:

function fmt(strings, ...expressions) {
  let str = "";
  for (let i = 0, l = strings.length; i < l; i++) {
    str += strings[i].replace(fmtRegex, "");

    const { format, option } = extractFormatOption(
      i + 1 < l ? strings[i + 1] : ""
    );

    str += formatters[format](expressions[i], option);
  }
  return str;
}

Here we do a look-ahead and extract any format and option indications in the template literal (which default to "s"), then apply the corresponding formatter to the current expression we are interpolating.

As I found that exercise actually quite useful, I've published an npm package with more formatting options:

AntonioVdlC / fmt-tag

🥨 - Format template literals

fmt-tag

Format template literals.

Installation

This package is distributed via npm:

npm install fmt-tag

Motivation

Template literals and template tags provide a unique API to build tools around strings. What started as a fun blog post about template tags ended up being this full-fledged library that might hopefully be useful to someone!

Usage

You can use this library either as an ES module or a CommonJS package:

import fmt from "fmt-tag";

- or -

const fmt = require("fmt-tag");

Please note that this library uses extensively Intl, which is not supported on older browsers (https://caniuse.com/?search=Intl) or Node versions < 16.

You can tag any template literal and append formatting hints right after interpolations to apply specific formatting to that substitutive value.

const name = "Alice";
const money = 20;
console.log(fmt`${name} has ${money

…

View on GitHub

An alternative approach to structuring a vuex store

Antonio Villagra De La Cruz — Tue, 24 Aug 2021 17:16:17 +0000

When using vuex to manage the state of a large-enough Vue project, it can sometimes be difficult to manage, even more so when using modules. Actions being dispatched are namespaced strings. Accessing the state in the store can sometimes be messy (getters are sometimes frown upon). Also, should the business logic be in an "action" or a "mutation" (or, even, in a "getter")?

To try to add a sensible approach to managing vuex stores, here is a proposal:

Modules, no name spaces

First, let's quickly look at the folder structure. The /store will be composed of a /modules folder, which will then host different subsets of state.

Each module will then have its folder (for example, store/modules/user), inside which there will be different files: actions.js, getters.js, mutations.js, state.js, types.js (more on that later), and finally index.js to wrap everything together.

The main difference with a more common setup is that we won't be using name spaces, as this would break the focal point of this approach: types.

Only getters, single mutation

Before looking into types though, another convention of this approach is to only use getters to access the state of the store. This might sound overkill if all the getters do is return a field of the state, but this approach brings consistency in accessing the store and will really shine with, you've guessed it, types!

For the sake of simplicity as well, we will only define a single mutation for each module as follow:

mutations.js

const mutations = {
  update(state, { key, value }) {
    state[key] = value;
  },
};

export default mutations;

All types

It is probably personal preference, but I particularly dislike having hand-written strings all over the code. For one, typos are very easily made, and static analysis tools (such as ESLint) can't really help you. You also need to remember how a particular action, or getter, is named, and that can become difficult to track when working on a large codebase and being part of a team.

For that reason, this whole approach is based on using constant variables instead of strings. Similarly to what I have seen in the redux world, we will be defining types for actions, getters, and keys (more on mutations later).

In practice, that means defining types like follows:

types.js

export const USER_GETTER_CURRENT = "g/user/current";
export const USER_GETTER_FEED = "g/user/feed";
export const USER_GETTER_OVERVIEW = "g/user/overview";

export const USER_ACTION_GET_CURRENT = "a/user/getCurrent";
export const USER_ACTION_GET_FEED = "a/user/getFeed";
export const USER_ACTION_GET_OVERVIEW = "a/user/getOverview";

export const USER_KEY_CURRENT = "k/user/current";
export const USER_KEY_FEED = "k/user/feed";
export const USER_KEY_OVERVIEW = "k/user/overview";
export const USER_KEY_DETAILS = "k/user/details";

Which will then be used in the other files of the module as such:
actions.js

import api from "@/api";

import {
  USER_ACTION_GET_CURRENT,
  USER_ACTION_GET_FEED,
  USER_ACTION_GET_OVERVIEW,
  USER_KEY_CURRENT,
  USER_KEY_FEED,
  USER_KEY_OVERVIEW,
} from "@/store/types";

const actions = {
  [USER_ACTION_GET_CURRENT]({ commit }) {
    return api.get(`/user`).then((res) => {
      commit("update", { key: USER_KEY_CURRENT, value: res.data });
    });
  },
  [USER_ACTION_GET_FEED]({ commit }) {
    return api.get(`/feed`).then((res) => {
      commit("update", { key: USER_KEY_FEED, value: res.data });
    });
  },
  [USER_ACTION_GET_OVERVIEW]({ commit }) {
    return api.get(`/overview`).then((res) => {
      commit("update", { key: USER_KEY_OVERVIEW, value: res.data });
    });
  },
};

export default actions;

getters.js

import {
  USER_GETTER_CURRENT,
  USER_GETTER_FEED,
  USER_GETTER_OVERVIEW,
  USER_KEY_CURRENT,
  USER_KEY_FEED,
  USER_KEY_OVERVIEW,
} from "@/store/types";

const getters = {
  [USER_GETTER_CURRENT](state) {
    return state[USER_KEY_CURRENT];
  },
  [USER_GETTER_FEED](state) {
    return state[USER_KEY_FEED];
  },
  [USER_GETTER_OVERVIEW](state) {
    return state[USER_KEY_OVERVIEW];
  },
};

export default getters;

state.js

import {
  USER_KEY_CURRENT,
  USER_KEY_FEED,
  USER_KEY_OVERVIEW,
  USER_KEY_DETAILS,
} from "@/store/types";

const state = () => ({
  [USER_KEY_CURRENT]: {},
  [USER_KEY_FEED]: [],
  [USER_KEY_OVERVIEW]: [],
  [USER_KEY_DETAILS]: {},
});

export default state;

This might seem like a lot of extra verbosity for an arguably minor problem, but stick with me, as this approach really shines when interacting with the store from components!

Blissful components

Finally, all this hard work leads us to the pay off!

To summarize, we have built our vuex store with the following guidelines:

modules, no name spaces
only getters, single mutation
all types

Now let's see how we might use this in components, and the main benefits of this approach:

App.vue

<template>
  ...
</template>

<script>
import { computed, ref } from "vue";
import { useStore } from "vuex";

import {
  USER_ACTION_GET_CURRENT,
  USER_GETTER_CURRENT,
} from "@/store/types";

...

export default {
  components: {
    ...
  },
  setup() {
    const store = useStore();
    store.dispatch({ type: USER_ACTION_GET_CURRENT });

    ...

    const user = computed(() => store.getters[USER_GETTER_CURRENT]);

    ...

    return {
      ...
    };
  },
};
</script>

Here we already see all the benefits of this approach:

we get strong guarantees that we won't write a type, if using static analysis tools like ESLint (we even get auto-complete in some IDEs).
we can see at a glance what actions a component might dispatch, and, because we can only access state through getters, we can also see at a glance which data is being accessed

So, there you have it. There are a bit more blows and whistles to gel all these bits together, but this is the gist of it.

Please feel free to also share any feedback you might have from your own experience using vuex to manage the state of a Vue application.