DEV Community: Randall

How I Host a Bot in 50,000 Discord Servers For Free

Randall — Sat, 12 Jul 2025 15:35:54 +0000

When I talk to other developers about my Discord bot they tend to be surprised that I operate it for free using widely available free tiers on cloud platforms, despite it being in nearly 50,000 servers.

So I thought I would write an article detailing how that works. I'll reveal where I host it, early technical decisions that made the bot lean, optimizations I've made, and what I could do better.

Where it's hosted 🖥

Of course in order to host a bot for free, one needs, drum roll please 🥁, free hosting.

The bot is hosted in Oracle Cloud. Their free tier allows you to create a VPS with up to 24 GB of RAM and 4 vCPUs, which is pretty wild compared to most other free tiers at similar providers, which offer more like 1 GB. Note that only ARM cores are available for this.

I'm currently using 18 GB of RAM for the bot server and 3 vCPUs. Not only is this sufficient, it's actually pretty overkill, and I expect I could scale the bot to at least 150k servers without any changes.

Although ARM cores might sound like a negative, the benchmarks I ran before moving the bot here actually showed the Oracle ARM cores outperforming Intel and AMD cores at Digital Ocean and Vultr (even their "high frequency" and "high performance" offerings), at least on the SQLite and image rendering benchmarks I used.

The ARM cores also look very cost effective even if you're paying. I've been pretty impressed with Oracle's offering honestly. Downtime has been minimal as well, I only remember one extended downtime of around 4 hours in the 2 years that the bot has been there.

One caveat is if you browse Reddit and such, you'll find some stories of Oracle randomly shutting free tier users down. I actually upgraded to a paid account and I pay for a small amount (like $2/month) of object storage for personal file backups using Duplicati, so that might get me onto the nice list. In the event, I haven't had any problems personally.

Cloud Run Functions ☁️

I don't need to do this anymore like I used to, since the free Oracle instance is so overkill, but a couple of the bot's features are deployed as Google Cloud Run functions (it's Google's answer to AWS Lambda).

Both of the features deployed this way use a few hundred megabytes of RAM to hold dictionaries in memory. By deploying those features as Cloud Run functions, the main bot server doesn't need to pony up the RAM for that. That all gets spun up on a separate server somewhere else in the magical Google cloud, and the main bot server just makes an HTTP request to the Cloud Run function.

So I basically use Cloud Run functions as extra free RAM for these memory-intensive features (and free CPU cycles too, although that's less critical since I've always had more CPU headroom). These features can feel more sluggish sometimes due to the phenomenon of cold starts but that's not a deal breaker.

Google Cloud has a very generous free tier that easily covers all of my usage of Cloud Run functions.

Logging and Error Reporting ⚠️

Logs are sent to Google Cloud Logging, and error level logs automatically flow to Google Cloud Error Reporting from there. Once again, this is all covered under the free tier, with room to spare.

Additionally, a separate bot in my support server allows moderators to trigger PagerDuty, which will call my cell phone and wake me up from my beauty sleep if any exceptionally serious situation arises. Fortunately, this has never needed to be used. As you may have guessed, this is covered under PagerDuty's free tier.

Language and Runtime </>

The bot is built with JavaScript and runs with Node.js. While JavaScript is not a particularly fast language in general, a lot of the bot's heavy lifting plays nicely to the strengths of Node.js. A lot of it happens in highly optimized native code within the V8 engine powering Node.js.

For example JSON parsing (which the bot needs to perform for every event it receives from Discord) is implemented in C++ in the V8 engine, and is very fast. The cost of then throwing the parsed object over the fence into JavaScript land is relatively minimal, and the work done on it by JavaScript code is pretty minimal as well in most cases (we'll get more into that later).

Node.js probably isn't the optimal choice here, and a bot written in C++ or Rust would likely perform better (depending on the bot library), but Node.js is likely going to beat other popular choices including Python, Java, and C#, and may even give Go a good run for its money. (Sorry, I don't have benchmarks, that's just my educated guess)

Library 📕

Choosing a bot library is just as important, maybe even more important, than choosing a language.

Background: The Discord API consists of a websocket API (for receiving events in real time) and a REST API (for performing actions). Neither are trivial to use, especially the former. Fortunately, there are community-maintained libraries for most popular programming languages to simplify interactions with the Discord APIs.

Bot developers almost always choose one of these libraries rather than trying to reinvent the wheel. When I made this choice way back in 2016, there were two main options for Node.js: discord.js and Eris.

discord.js was known as being more feature-rich, having great documentation, and having a welcoming community, while Eris was known for being much faster and leaner, having a somewhat more gatekeepy community, and being used by most of the popular Node.js bots who needed its vertical scalability.

At the time, I didn't have any ambitions of scaling my bot to tens of thousands of servers, but a lot of the bots I knew and respected used Eris, and I wasn't intimidated by its reputation since I wasn't a beginner. So I ended up choosing Eris, which was definitely the right choice in hindsight.

Nowadays, discord.js has improved its performance to an extent, while Eris has fragmented due to the main maintainers apparently moving on. My bot is using Dysnomia now which is a fork of Eris that aims to carry the torch onward, but that's a pretty niche setup by this point.

Library Optimizations ➕

The nature of the Discord API requires keeping a lot of information in a cache. For example, after your bot connects to the websocket API and an event happens involving user A, Discord will send your bot miscellaneous information about user A such as their username, avatar, account creation date, and more. Later, when another event involving user A occurs, Discord might not send you that extra information, under the assumption that you cached it previously.

This cached data is managed by whichever bot library you chose, and is generally kept in the bot process's memory. This cached data can easily get into the multi-gigabyte range for bots in thousands or tens of thousands of servers.

How a bot's library manages this cache data is a major factor in how well the bot scales. Eris (and by extension Dysnomia) is relatively efficient at this compared to other bot libraries. On the other hand, its cache customization options aren't very comprehensive. One option it does provide is allowing you to customize the message cache size, and this is a pretty significant one. I set this to zero in my bot, because my bot never needs to access previously-sent messages. If I remember correctly, the default is to cache the most recent 100 messages in each channel. For a bot in 50,000 servers, that can be millions of messages and multiple gigabytes of memory.

Another important optimization is to only enable Gateway Intents that you actually need. If at all possible, avoid the PRESENCE_UPDATE intent like the plague. Having that intent enabled can massively increase the number of events your bot receives (you'll receive an event any time anybody's online status changes in any server). Enabling PRESENCE_UPDATE actually requires approval from Discord now if your bot is in more than 100 servers, so this is a decision most developers don't need to grapple with - Discord will force it off for you unless you really need it.

The Hot Path 🔥

The bot receives an event for every message sent in any server it's present in. That averages to around 100-200 events per second.

At least 99.9% of those messages aren't intended for the bot, so the bot just has to look at the message, decide "this isn't for me", and do nothing. The faster we can do that, the better. Here's some of the key code involved in that:

processInput(bot, msg) {
  let serverId = msg.channel.guild ? msg.channel.guild.id : msg.channel.id;
  let prefixes = this.persistence_.getPrefixesForServer(serverId);
  let msgContent = msg.content;

  msgContent = msgContent.replace('\u3000', ' ');
  let spaceIndex = msgContent.indexOf(' ');
  let commandText = '';
  if (spaceIndex === -1) {
    commandText = msgContent;
  } else {
    commandText = msgContent.substring(0, spaceIndex);
  }

  commandText = commandText.toLowerCase();

  for (let prefix of prefixes) {
    for (let command of this.commands_) {
      for (let alias of command.aliases) {
        const prefixedAlias = prefix + alias;
        if (commandText === prefixedAlias) {
          return this.executeCommand_(bot, msg, command, msgContent, spaceIndex, prefix);
        }
      }
    }
  }

  return false;
}

This code actually isn't very micro-optimized. Looking at it now, I can imagine how we could do better (mainly by avoiding the creation of new strings). But here's the important bit that we're getting right:

let prefixes = this.persistence_.getPrefixesForServer(serverId);

This is fetching the custom command prefixes for the current Discord server. If you don't know what that means, consider that by default all the bot's command are prefixed/namespaced with k!. For example: k!help, k!about, etc. But what if there's another bot that uses the same prefix, and it also has a k!help command? Fortunately, the bot allows server admins to change the k! prefix to something else to disambiguate (or if they just prefer using some other prefix).

This is a per-server setting that's saved in the database, but this code here to fetch it is synchronous, and that's the key optimization. All command prefixes are cached in process memory to avoid needing any inter-process communication in this hot path. Making hundreds of calls per second to a database or cache instance, while possible, would add significant load and would concretely impact scalability.

Not all bots can avoid database queries in their hot paths. If you have a bot that grants users XP for every message they send, then you have to make a database query, there's no way around it (although you could batch many XP increments together and flush them to the database in groups).

What Could I Do Better? 👀

The main choice I made that doesn't align so well with keeping the bot lean is using MongoDB as the database. Here's the output from top on the server as we speak, sorted by memory usage:

Mongo is using a bit over 3 gigabytes of resident memory, an amount that is similar to the bot process itself. Now to be fair, I could reduce that by setting --wiredTigerCacheSizeGB a lot lower and any performance degradation would probably be pretty minimal. Since the bot has over 9 gigabytes of available memory, and over 3 gigabytes completely free, there's just no need.

I could have used PostgreSQL instead and it likely would have given me a bit more RAM headroom and a lot more CPU headroom, but the real resource-miser move would have been to use SQLite, which would have been sufficient for this bot. SQLite is often misunderstood as a toy database, and it's further often assumed that that alleged toy-ness also means it has poor performance. While it's a nuanced topic, that's a broadly unfair assessment as SQLite avoids overhead from...

Inter-process communication (this one's big)
Access control
Row-level locking
...more

SQLite doesn't have a lot of these big-boy features, which gives it a performance boost for low-concurrency access patterns (which is the case for my bot).

That said, I'm comfortable with the decision to use Mongo in hindsight. I used it as a learning opportunity to learn a new database, it fits on the instance, I like the official tools (Mongo Compass), and it gets me where I need to go. But it would be on the chopping block if I needed to claw back more memory and CPU headroom.

Conclusion

Welp that's how I do it! It's a combination of utilizing the great free hosting options available, choosing fast dependencies, and making a few targeted optimizations. Feel free to comment if you have any questions or comments.

Reflections on Generative AI

Randall — Fri, 04 Jul 2025 16:40:12 +0000

AI. It's my turn to talk about it.

🚀 We're in the Future

First I have to point out how cool of a world we now live in. Generative AI may seem normal by now, almost mundane. But when I step back and try to look at it from a fresh perspective, it's the most spectacular and unexpected technology of my lifetime. In early 2022, if you had showed me Claude Sonnet 4 iteratively implementing a feature while writing tests in Cursor and asked me to predict when such technology would be invented, I would have guessed the 2040s at the earliest. Yet here we are just a few years later in 2025.

A lot of Sci-Fi AIs suddenly look plausible with current technology. HAL 9000 from 2001: A Space Odyssey, the terminal AIs in Book of the Long Sun, Auntie Dot from Halo: Reach, to name a few. These AIs are all flawed and are not AGI (as OpenAI defines it at least) but they are able to understand what is said to them, speak intelligently, synthesize information, and make decisive decisions in general contexts, not unlike our quaint little ChatGPT 4o can today.

🧮 The Accelerationists and the Luddites

Where does it go from here? Visions are polarized, especially in the industries generative AI is being adopted in. Some get hyped about the impending singularity whenever a new model is released. Others shrug it off as being of little consequence.

I suspect many in both camps are coming from places of fear, but with different, almost opposite sources. The "Luddites" are afraid of being replaced by AI and marginalized as a result. While many of the Accelerationists already feel marginalized, or are haunted by an 'is this all there is?' kind of ennui, or fear humanity as a whole is careening towards a cliff. For them, the tantalizing Sci-Fi future that AI seems to herald is the cure.

When we see viewpoints get so polarized, historically that seems to be a great hint about how it's really going to unfold. Ultimately the truth is going to lie somewhere in between the two poles, likely pretty close to the center. The software industry will be disrupted (I think this is irrefutable by this point). But are we going to be uploading our minds to computers and lording over our own star systems next year? Probably not.

Generative AI will continue to disrupt industries. We'll get better and better at applying it. But as we do so its limitations will become more and more clear, leaving us far short of any utopian (or dystopian) vision.

This doesn't preclude those possibilities eventually, as technology only improves, but rather than a sudden radical upheaval we're more likely to experience years that don't look much different from the previous, despite significant changes on the decade timescale. This is how it's always been.

💀 My Death as an Artist

Outsiders imagine programming as a pretty rote and mechanical task. Someone decides what the computer should do, and the programmer sits down and "types it in". But if you're reading this, you know that's not how it works.

We code with our own voices, and no two programmers make all of the same decisions. We get better at it (and sometimes worse) over time, but there's no universal ideal that we converge on. We remain unique, like painters or authors, and we take pride in our work.

But when AI writes code, I don't feel like it's mine. Sure, I'll make tweaks by hand and prompt the AI to make changes, but I don't rewrite it into my own voice, there would be no point using AI then.

So I find that I don't care about code that AI generates for me. I still care about the architectural choices and the functionality, but I become detached from the microscopic details of the code and any artistry that might have been there. And I worry this detachment might hurt the product itself, that's something I’m still trying to navigate effectively.

This is why I haven't been using AI much for personal projects. I use Copilot autocomplete, but I rarely prompt AIs to write large pieces of code for me. I might be sacrificing efficiency, but I find it more fun this way. I get into the flow and care about the code.

🦋 The Struggle as Metamorphosis

What's going to happen to beginner programmers in this age of AI? There's a lot of trepidation about this, and it's well-deserved. I'm not talking about the idea of AI replacing programmers, but rather how beginner programmers will (or won't) emerge from their cocoons one day as expert programmers.

I vividly remember the first program I ever wrote. It was a script for Garry's Mod in 2006. It was about 50 lines long. It was attached to an AK-47, and if you picked up that AK-47, it froze you in place until you admitted in chat to being a n00b. It was trivial, but it took me about a week of banging my head on it late into the night struggling to interpret Lua documentation like ancient hieroglyphs. For that time, I was obsessed with it and thought about little else. When I was done, I knew the basics about variables, functions, and events.

But now? ChatGPT could spit that out for me in 30 seconds. Nobody needs to struggle to build something like that anymore. I could have it working in no time, but I'd hardly learn a thing from the experience.

The fact that AI is capable of this doesn't just deprive beginners of valuable learning experiences. That part has a clear, if painful, solution for anyone disciplined enough (just resist the temptation and don't use AI during your formative stages).

No. More insidiously, it's also deeply demoralizing.

For as long as I can remember, I have dreamt of being a respected electronic music producer. It's my secret life goal. I've never dedicated the time to it that a life goal deserves, but I have dabbled with it and know basic DAW (Digital Audio Workstation) usage.

Until recently, this basic knowledge made me a better electronic music producer than the 99.9% of humanity that has never touched a DAW before. But that's no longer the case. I now have thousands of hours to go until I'm half as good as the AI music generators that everyone now has access to. Realizing this, I now struggle more than ever to put in effort. Beginner programmers are experiencing the same thing.

Where does this lead economically? The world still needs programmers with deep technical expertise, but the pipeline from beginner to expert is being squeezed. On one extreme, it's possible that AI will win the race. That is, AI replaces all or almost all programmers in the 30-40 years between now and when the current generation of programmers retires. 30-40 years is a long time, after all. On the other extreme, maybe we end up in a Dune-like world largely starved of the talent still needed to maintain the machines built by previous generations. As usual, the reality is likely somewhere in between, perhaps with "vibe coding" as the main development style, supported by a caste of (perhaps mostly older) programmers who uniquely retain the ability to go deeper.

And where does it lead us as artists? I fear that, like the act of using AI to write code that's not my own, the watering down of the learning experience may be another factor that could drain life from the experience of programming, especially for those too young to have experienced it.

☁️ The Realization of the Dream

There's another interpretation we can take of my experience with music. Sure, I might now be farther than ever from micromanaging those sine waves and drum loops into a unique and personal thing of beauty. And yet paradoxically, I'm closer than ever to making something. I can, and have, dreamt something up, asked an AI to build it for me, and received a pretty good result. This is true of music and digital art as well (including the cover image of this very article). No, it doesn't feel like it's truly mine, nor is it exactly what I had envisioned, but at least it's something - something I'm currently incapable of building otherwise.

Moreover, I expect this experience to become more personal over time, not less, as the tools will come with more customizability to help us achieve exactly the sound/look that we had imagined.

I expect this will happen with programming as well. The tools will do better at doing what we ask and realizing our dreams exactly. For me as an experienced programmer, that makes it feel less personal (since I'm not writing the code myself). But for a non-programmer, it's more personal (because they can get exactly what they envisioned without compromise).

This is the bright side of applying AI to any art (including programming). It can help anyone become a builder, and realize dreams that may otherwise have been out of reach, or at least locked behind thousands of hours of study and practice.

Conclusion

I do have some more thoughts but I like that this is ending on a positive note, and it's long enough already, so I will wrap it up here.

The impacts of AI on our society are already far-reaching and will become even more so. We'll all be winners in some ways and losers in others. I am struggling with a sense of loss in the AI age, but also optimistic about the opportunities it comes with. We're not just changing how we build things, but what we can build, and that's exciting.

What do you think?

🏖️ Going Against the Grain

Randall — Thu, 25 Apr 2024 19:32:05 +0000

I was reflecting recently on habits and practices I have that go against the common wisdom of the software development industry. Do you have any?

Here are some of mine:

I don't ask a lot of questions

I often hear that one should ask as many questions as possible, especially when onboarding onto a new project. That has never been my style though. Instead, I like to answer my own questions by digging through code, stepping through it in a debugger, experimenting, reading old commit messages, things like that. I definitely do ask questions, but it's somewhat of a last resort for me when I either can't find the answer myself, or really need to know the answer ASAP.

When I answer my own question like this, I don't just get the answer to the question I'm asking, I also stumble upon the answers to a lot of other questions I haven't even asked yet. That doesn't really happen when I just ask someone my question and they tell me the answer.

I credit this habit for why I often seem to get a reputation for knowing a lot about code I didn't even write. Also it helps me operate when there's nobody I can ask about something (often happens in freelancing).

I write lots of integration tests, few unit tests

Usually I hear that one should write a lot of unit tests, some component tests, and a few integration tests. I generally do the opposite, and write many integration tests and few unit tests. Here are some reasons why I think this works:

Integration tests are the best at telling you if your application actually works. The goal of software engineering is never really "write a function that does X", it's always "write an interface via which some external actor can do X", and that's what integration tests test.
Integration tests can often survive refactoring and other overhauls intact. Let's consider an HTTP API server. You're going to want to have a stable API with request and response schemas that stay the same regardless of any internal refactoring you do. If a test targets that stable API, then it can remain unchanged and valid even if you completely rewrite all the code under the hood. In contrast big refactors often necessitate big changes to unit tests and especially component tests, which makes the refactor costlier and also introduces the possibility of breaking a test and having it pass when it shouldn't.
Other developers and QA engineers can write integration tests without having whitebox insight into the internal code. If you can setup a good set of utilities for writing API-level tests and shoot some example tests and API documentation over to QA, they can start adding more tests while knowing little to nothing about the internals. In addition, since integration tests are less likely to need changes, you're less likely to need to update tests written by someone else (which is often pretty difficult) when you make changes.

I definitely write unit and component tests but I reserve them for certain conditions like:

Pure functions that implement complex and well-defined algorithms. We often need such functions to be rock solid and have many tests that run quickly. And if the expected behavior is well-defined, we're less likely to change it in a way that requires changing/rewriting tests.
If it's difficult to test certain behavior from higher level tests (sometimes this is true just due to the type of application you're building - for instance, UI tests can be very cumbersome to write).

I don't like frameworks

While I respect the structure that frameworks can impart on a project (especially a big project) and the magic they provide, I find that the magic is sometimes more of a curse than a blessing.

The more magical a framework is, the more times I experience the magic of "I don't understand why this doesn't work..." and spend a day waving my trial-and-error wand at it until I reach the nirvana of "now it works but I still don't understand why..." and move onto the next thing.

When I keep things simple and work with lower-level tools, I stumble upon puzzles much less often and can work through them much more quickly. Also I have more flexibility to build exactly what I need, without bumping into the railings that opinionated frameworks often present.

That said, it's a balancing act to be sure. I don't build applications in assembly just because "it's the least magical". Sometimes opinionated frameworks can do things that would be really hard or time consuming to do otherwise, and for bigger teams they can help everyone stay on the same page.

What about you?

How do you rebel against the common wisdom?

By the way, I don't claim to be objectively correct on any of those practices, it's just how I work, for better or for worse!

🏁🐘Winning Race Conditions With PostgreSQL

Randall — Sat, 17 Feb 2024 17:13:16 +0000

Race conditions suck! They can be extremely difficult to debug, and often only occur naturally in production at the most critical moments (times of high traffic). Fortunately, many databases (such as PostgreSQL) give us powerful tools to manage and avoid race conditions.

In this article, we will do a deep dive into how to avoid race conditions while using PostgreSQL, focusing especially on enforcing uniqueness constraints. We'll start with some simpler cases, then move on to more complex ones, so feel free to skip down depending on your level of experience.

This article assumes that you are familiar with race conditions, why they happen, and why they suck. (if you aren't familiar, don't worry, you will learn the hard way soon enough! We all do.) The later cases also assume at least an intermediate knowledge of relational databases.

This article will use the Node.js pg library for examples.

Let's just dive right in and look at some different cases where our code and data are vulnerable to race conditions, and find out how to fix them.

Case 1: Simple Uniqueness

Most applications do not allow two users to share the same email address. If a user tries to register with an email already registered by another account, registration should fail.

One might write such a uniqueness check in JavaScript like this:

async function registerUser(email, hashedPassword) {
  const existingUserResult = await pool.query(
    'SELECT 1 FROM "user" WHERE email = ?;',
    [email],
  );

  if (existingUserResult.rows.length > 0) {
    throw new Error('User already exists');
  }

  await pool.query(
    'INSERT INTO "user" VALUES (?, ?);',
    [email, hashedPassword],
  );
}

But this code is vulnerable to race conditions. If two users try to sign up at the exact same time with the same email, then it's possible for a sequence of events like this to happen:

User #1 SELECT operation
User #2 SELECT operation
User #1 INSERT operation
User #2 INSERT operation

Since the SELECT operations happen for both users before the INSERT happens for either one, both users will survive the duplicate-check and proceed to the INSERT operation. The nature of asynchronous programming allows such sequences of events.

Fortunately this problem is really easy to fix, we just need to add a UNIQUE constraint to the email column in the user table. We can do this when creating the table:

CREATE TABLE "user" (
  "email" VARCHAR UNIQUE NOT NULL,
  "hashedPassword" NOT NULL
);

Or later, by using ALTER TABLE.

By setting a UNIQUE constraint on the email column, we are telling the database that no two rows may have the same value for email, and the database itself will enforce this for us. Even if the two INSERTs happen at exactly the same time, concurrency features in the database guarantee that only one will succeed and the other will error.

Case 2: Compound Uniqueness

Let's say we're running a multi-user blogging application, like Dev.to, and we want to allow users to create one highlighted post per week. Our posts table might look like this:

CREATE TABLE "posts" (
  "userId" INT NOT NULL,
  "createdAt" TIMESTAMP WITHOUT TIMEZONE NOT NULL,
  "highlighted" BOOLEAN NOT NULL,
  "postContent" TEXT NOT NULL
);

We could write code similar to the first example, with a uniqueness check like this:

const existingWeeklyHighlightedPostResult = await pool.query(
  `
    SELECT 1
    FROM "posts"
    WHERE
      "userId" = ?
      AND
      "highlighted" IS TRUE
      AND
      /* "createdAt" is greater than the first moment
       * of the current week */
      "createdAt" >= DATE_TRUNC('week', NOW());
  `,
  [userId],
);

if (existingWeeklyHighlightedPostResult.rows.length > 0) {
  throw new Error('You already have a highlighted post this week');
}

However this would have the same issue. If a user submits two highlighted posts at the same time, both of them might pass this uniqueness check. Maybe the user accidentally double-clicked the submit button, or maybe they're trying to exploit this to get more ad revenue 🤷

Like last time, can we create a UNIQUE constraint to help us? Yes! Even though we store an exact timestamp rather than the week that a post was created in, PostgreSQL's support of indexes on expressions gives us what we need. Further, we need to use the partial index feature to only enforce this constraint on highlighted posts:

CREATE UNIQUE INDEX "one_highlighted_post_per_week_constraint"
ON "posts" ("userId", DATE_TRUNC('week', "createdAt"))
WHERE "highlighted" IS TRUE;

With this UNIQUE index, the database will not not allow two rows to both have "highlighted" IS TRUE and to have the same combination of userId, DATE_TRUNC('week', "createdAt"). In other words, a user may only have one highlighted post per week.

For any rows where "highlighted" IS FALSE, they are exempt from this constraint and we can insert as many of them as we want.

Case 3: Compound Multiple Uniqueness

Same case as above, but rather than one highlighted post per week, we want to allow users to make three highlighted posts per week. Can we do this with a UNIQUE constraint like we did above?

Once again, yes, but the solution here may be a bit more convoluted. First, we create the same posts table, but instead of a BOOLEAN highlighted column we add an INT weeklyHighlightedPostNumber column:

CREATE TABLE "posts" (
  "userId" INT NOT NULL,
  "createdAt" TIMESTAMP WITHOUT TIME ZONE NOT NULL,
  "weeklyHighlightedPostNumber" INT,
  "postContent" TEXT NOT NULL
);

If a post is highlighted, then its "weeklyHighlightedPostNumber" will be an integer. If the post is not highlighted, "weeklyHighlightedPostNumber" will be NULL.

Now we add a constraint that forces weeklyHighlightedPostNumber to be a number between 1 and 3, if it's not NULL:

ALTER TABLE "posts" ADD CONSTRAINT num_weekly_posts_constraint CHECK
(
  ("weeklyHighlightedPostNumber" IS NULL)
  OR
  ("weeklyHighlightedPostNumber" BETWEEN 1 AND 3)
);

Now we can add a UNIQUE constraint:

CREATE UNIQUE INDEX "three_highlighted_posts_per_week_constraint"
ON "posts" (
  "userId",
  DATE_TRUNC('week', "createdAt"),
  "weeklyHighlightedPostNumber"
)
WHERE "weeklyHighlightedPostNumber" IS NOT NULL;

This will enforce that for any highlighted posts (rows with non-NULL "weeklyHighlightedPostNumber"), they may not have the same combination of "userId", DATE_TRUNC('week', "createdAt"), and "weeklyHighlightedPostNumber". Since the earlier constraint requires "weeklyHighlightedPostNumber" to be between 1 and 3, this limits us to 3 highlighted posts per week per user.

This does mean that when inserting a post, you need to figure out the next available post number. We can do this with a bit of SQL in our INSERT operation. This solution also handles gaps (for example if you have three highlighted posts and delete the second one). It does start getting a little hairy, but check it out:

async function createHighlightedPost(userId, content) {
  const insertResult = await pool.query(
    `
      WITH next_highlighted_post_num AS MATERIALIZED (
        SELECT series_num
        FROM GENERATE_SERIES(1, 3) AS series_num
        WHERE NOT EXISTS (
          SELECT *
          FROM posts
          WHERE
            posts."userId" = $1
            AND
            DATE_TRUNC('week', NOW()) <= posts."createdAt"
            AND
            posts."weeklyHighlightedPostNumber" = series_num
        )
        LIMIT 1
      )
      INSERT INTO posts
      SELECT $1, NOW(), series_num, $2
      FROM next_highlighted_post_num;    
      `,
    [userId, content],
  );

  if (insertResult.rowCount === 0) {
    throw new Error('Could not create highlighted post');
  }
}

Of course you could instead just write a simple SELECT query to get all currently existing "weeklyHighlightedPostNumber"s for the given user and current week, and write JavaScript code to choose the new row's "weeklyHighlightedPostNumber" to INSERT.

Case 4: Compound Referential Uniqueness

This case will be similar to case #2, but instead of "one highlighted post per week", we'll modify the condition slightly to "must wait 7 days before making another highlighted post".

In case #2, if a user makes a highlighted post on a Wednesday, they're next able to make one at the start of the next week (Monday).

But here in case #4, if a user makes a highlighted post on a Wednesday, they have to wait until the same time next Wednesday before they can make another.

This would require any constraint to reference the user's previous highlighted post creation date, which is something that typical UNIQUE constraints simply cannot do. To solve this we'll need to bust out some extra features: transactions and advisory locks.

This will be the final and trickiest case that we look at.

We will use the same table schema as in case #2:

CREATE TABLE "posts" (
  "userId" INT NOT NULL,
  "createdAt" TIMESTAMP WITHOUT TIMEZONE NOT NULL,
  "highlighted" BOOLEAN NOT NULL,
  "postContent" TEXT NOT NULL
);

And here is a solution in JavaScript:

async function createHighlightedPost(userId, content) {
  const postInsertLockNamespace = 5000;
  const queryRunner = await pool.connect();

  try {
    await queryRunner.query('BEGIN TRANSACTION;');

    await queryRunner.query(
      'SELECT PG_ADVISORY_XACT_LOCK(?, ?);',
      [postInsertLockNamespace, userId],
    );

    const existingWeeklyHighlightedPosts = await pool.query(
      `
        SELECT 1
        FROM posts
        WHERE
          "userId" = ?
          AND
          highlighted IS TRUE
          AND
          "createdAt" >= NOW() - INTERVAL '1 week'
      `,
      [userId],
    );

    if (existingWeeklyHighlightedPosts.rows.length > 0) {
      throw new Error(
        'Already have a highlighted post in the previous seven days'
      );
    }

    await queryRunner.query(
      'INSERT INTO "posts" VALUES (?, ?, ?, ?);',
      [userId, new Date(), true, content],
    );

    await queryRunner.query('COMMIT');
  } catch (err) {
    await queryRunner.query('ROLLBACK');
    throw err;
  } finally {
    queryRunner.release();
  }
}

For this to work, anything which is going to modify (INSERT, UPDATE, or DELETE) records in the posts table should first SELECT PG_ADVISORY_XACT_LOCK(5000, userId);. This takes a lock, and any other transaction that tries to take a lock with the same arguments will have to wait for it to be released. If we're careful to always take this lock before modifying posts, we can trust that after we take the lock, nothing else will modify posts for that user until after we release the lock. This means after we do the SELECT statement to get existingWeeklyHighlightedPosts, we know that the result of that will remain correct until after our INSERT completes and the transaction commits. This effectively prevents a user from submitting a highlighted post if they have already submitted one in the past seven days, even if they are spamming us with parallel post requests.

However, it can be hard to make sure that your code is well-behaved and always takes the lock before modifying posts, especially if other developers are working on the same codebase (or some psycho (totally not yourself of course) logs in with pgAdmin and runs random queries!). If anyone does not properly take the lock before inserting, then this approach breaks.

To help a little bit, we can create a trigger that automatically takes the lock whenever you INSERT or UPDATE or DELETE rows in this table. That would look like this:

CREATE FUNCTION "take_post_modify_lock_function"() 
RETURNS TRIGGER
LANGUAGE PLPGSQL
AS $$
BEGIN
  IF OLD."userId" IS NOT NULL THEN
    PERFORM PG_ADVISORY_XACT_LOCK(5000, OLD."userId");
  END IF;

  IF NEW."userId" IS NOT NULL THEN
    PERFORM PG_ADVISORY_XACT_LOCK(5000, NEW."userId");
  END IF;

  RETURN NEW;
END;
$$;

CREATE TRIGGER "take_post_modify_lock_trigger"
BEFORE INSERT OR UPDATE OR DELETE ON "posts"
FOR EACH ROW
EXECUTE PROCEDURE "take_post_modify_lock_function"();

This trigger will force any modification of posts to take the lock, so you don't need to remember to do it in code when you modify posts.

You do still need to do it in code before SELECTing to verify your constraint condition though. There is no such thing as SELECT triggers, and even if there were, taking the lock would be wasteful for queries that don't really need to take it (like when you're fetching a list of posts to display on the homepage). If you don't take the lock before SELECTing, then someone else might get the lock and do an INSERT before you do the INSERT you're planning to do based on the results of the SELECT.

‡ The 5000 chosen above for the first argument to PG_ADVISORY_XACT_LOCK() is arbitrary. We could have chosen any other number. What's important is that it should be different from any other types of locks you create, so that locks with different meanings don't overlap. For example if we had another table comments and wanted to do a similar thing with locks, we could use 5001 for it.

SERIALIZABLE Transaction Isolation Level

There's actually some secret alternative magic sauce that can make this all work without any explicit locking, and that's the SERIALIZABLE transaction isolation level. Most SQL databases have this, but it's often a bit different between them. For example PostgreSQL's version provides much stronger guarantees than MySQL's version (which can be a little deceptive).

When you use the SERIALIZABLE transaction isolation level and you do a SELECT inside of a transaction, PostgreSQL "remembers" what you SELECTed, and if any data changes before the transaction finishes in a way that would cause your SELECT query to have returned a different result, then your transaction will get a "serialization failure" and have to ROLLBACK.

I cannot stress enough that this is an extremely powerful feature and if you simply switch it on (as the default: ALTER DATABASE <DATABASE NAME> SET DEFAULT_TRANSACTION_ISOLATION TO SERIALIZABLE;) and consistently use transactions, then you can write your code without having to think about explicit locking. However there are a number of guidelines and pitfalls you have to be aware of:

Use explicit transactions (BEGIN TRANSACTION; statement) for any operations you do that execute more than one SQL statement (such as the createHighlightedPost() JavaScript function we looked at above).
Avoid running any transactions with lower isolation levels, and be very careful if you do, since it can be harder to reason about how transactions with different isolation levels interact.
Be ready to retry transactions, since you may encounter serialization failures pretty regularly, which is normal and expected.
Keep transactions as short as possible, since having more transactions running at any given time will increase the chance of serialization failures.
Understand that the predicate locking used by SERIALIZABLE transactions does introduce some non-trivial overhead.
Be aware that certain patterns don't work well under SERIALIZABLE transaction isolation level. For example using SELECT ... FOR UPDATE SKIP LOCKED to implement a highly concurrent queue will not work (you'll just get bombarded with serialization failures).
Make sure you have indexes that support your queries, since transactions that have to do full table scans can greatly increase the amount of serialization failures.

Conclusion

Sometimes having to worry about race conditions is a "good problem to have", since it suggests that you have a lot of users using your system. Hopefully they're paying you!

But as the user base grows, race conditions can cause more and more mysterious and crippling faults, and can sometimes even be caused on purpose by exploiters.

I hope this article gave you some new techniques to deal with these cases, and if you know of any other good ones, please share in the comments!

While writing this, I had a billion ideas for additional cases, footnotes, and asterisks, but couldn't include it all without making quite a mess. If you have any questions or are interested in additional cases, feel free to comment!

🤖Discord Bot Programmed ... in Discord!

Randall — Fri, 28 Apr 2023 12:30:00 +0000

Meet my bot Kiryu. His specialty is downloading JavaScript code from a Discord channel and executing it. To have Kiryu automatically add a role to new members who join my server, I write this message in the code channel:

Kiryu sees the message, extracts the JavaScript code, and eval()s it. Now whenever a new member joins, he will give them a role.

Here's another one. This one makes Kiryu automatically ban anyone who sends a message including a banned word:

Kiryu re-evaluates code when he starts, when a new message is created in the code channel, when a code message is updated, and when a code message is deleted, so his code always stays in sync with the code I have written in the code channel.

Source Code

Check out Kiryu's core code here. It's just one source file, less than 200 lines.

Run Your Own Instance

If you want to try running your own instance, I pushed an image to Docker Hub. You can easily launch an instance using Docker:

docker run \
  --name kiryu \
  --restart unless-stopped \
  -e PROGRAMMER_IDS='YOUR USER ID HERE' \
  -e BOT_TOKEN='YOUR BOT TOKEN HERE' \
  -e CODE_CHANNEL_IDS='YOUR CODE CHANNEL ID HERE' \
  -e LOG_CHANNEL_ID='YOUR LOG CHANNEL ID HERE' \
  -d \
  mistval/kiryu

If you don't know how to create a bot account, check out the start of this great article and follow the instructions up until you get a bot token, which you can then substitute into the command above, along with your user ID, the ID of the channel you want to write code in, and the channel where you want errors to be reported to.

Once the bot is online, try writing this in your code channel, surrounded by js code tags:

messageHandlers.push(
  (msg) => {
    if (msg.content === 'hello') {
      return msg.channel.createMessage('world');
    }
  },
);

The bot should react with a green checkmark. Then if you say hello (in a different channel), the bot should respond with world.

Handling Events

As you may have noticed, Kiryu has a built-in messageHandlers array as a convenience. Any function added to that array will be called for every new message that isn't a code message and isn't from a bot. Errors thrown from inside of message handler functions will be automatically reported to the log channel.

For other types of events, you can subscribe to them directly on the bot object, as shown in the very first image in this article when I subscribe to the guildMemberAdd event.

You can see the available events in the eris documentation here. Eris is a Discord bot library for Node.js. It's no longer well-maintained and it has never been as popular as the discord.js library, it's just what I'm personally used to, since I like it for performance reasons.

One gotcha here is that you have to be careful of double-subscribing to events, since the code in the code message may be evaluated multiple times. That's why I run bot.removeAllListeners('guildMemberAdd'); before subscribing to the event in the earlier example.

Module Loader

Kiryu can automatically download and install modules from npm. For one of Kiryu's fancier features, I use the @pagerduty/pdjs module. It's a library for interfacing with the PagerDuty API. Using Kiryu, moderators in my server have a way to open a PagerDuty incident, which will call my cell phone and wake me up from my beauty sleep. I have this feature because I have another bot in 30,000+ servers, and if something goes really wrong with it, I want to know ASAP!

The code for that feature is a bit longer, so I won't show it here, but here's a short example of using the hello-world-npm module to re-implement the above hello world command:

If Kiryu doesn't have that module downloaded already, he'll download it and exit. When he restarts (which he will do automatically, if you use the Docker command above) he will have the module available. (I couldn't find a way to load a new module into a running process)

Other Examples

If you want to see all the code that I'm running on Kiryu, feel free to check my server where I have the aforementioned PagerDuty command plus a few more, plus SQLite integration.

Security

I would be remiss if I didn't mention that downloading and eval()ing code from a Discord server isn't exactly an inherently secure thing to do. Although Kiryu is written to only evaluate code in messages sent by users whose IDs you specify in the PROGRAMMER_IDS environment variable, bugs in Kiryu or in Discord itself could lead to malicious code execution on the host machine.

Conclusion

So why am I coding a bot like this? Well, just because it's fun, and it's a cool thing to show off in my server. I wouldn't really recommend doing this for a major production bot, but it gets the job done for little chores in my server, and looks cool while doing it! If you're interested in trying Kiryu, or this technique more generally, I'd love to hear what you think in the comments!

🏺Database Architecture - History Over State

Randall — Sun, 02 Apr 2023 01:14:41 +0000

What should a database store? There are two broad ways of thinking about it:

A database should store state
A database should store history

Engineers tend to gravitate towards treating their database as a store of state. It is the more obvious approach, and it tends to be a bit simpler.

But it turns out that treating your database as a store of history instead can make your applications much more flexible and resilient. Let us take a look...

What's the difference?

Let us pretend we have a simple web game and we want to display a leaderboard to our users. Each match has one or more players, and each player earns zero or more points. We want to show a ranking of players by how many points they have earned in total:

Username	Points
John	150
Ife	125
Amir	98
Jane	50

If you treat the database as a state store

The engineer who treats their database as a state store simply makes a table to store the state of the leaderboard:

CREATE TABLE leaderboard (
  username VARCHAR UNIQUE NOT NULL PRIMARY KEY,
  points INTEGER NOT NULL
);

CREATE INDEX points_idx ON leaderboard (points DESC);

They start updating this new table whenever a player earns points, and they run a simple query on it to get the top 20 players:

SELECT *
FROM leaderboard
ORDER BY points DESC
LIMIT 20;

If you treat the database as a history store

The engineer who treats their database as a history store approaches this much differently. They do not store a leaderboard state. Rather, they store a match history. They create two tables like this:

CREATE TABLE "match" (
  match_id INTEGER UNIQUE NOT NULL PRIMARY KEY,
  start_time TIMESTAMP WITHOUT TIME ZONE NOT NULL,
  end_time TIMESTAMP WITHOUT TIME ZONE NOT NULL,
  map_name VARCHAR NOT NULL,
  game_mode VARCHAR NOT NULL
);

CREATE TABLE match_player (
  match_id INTEGER NOT NULL,
  username VARCHAR NOT NULL,
  points INTEGER NOT NULL,
  FOREIGN KEY (match_id) REFERENCES "match" (match_id)
);

When a match happens, the relevant information is inserted into the match and match_player tables. Now, to calculate the leaderboard, the engineer queries the database like so to aggregate all of the match history and dynamically generate a leaderboard:

SELECT username, SUM(points)
FROM match_player
GROUP BY username
ORDER BY SUM(points) DESC
LIMIT 20;

Rather than thinking "I need to store a leaderboard in the database", this engineer thinks "I need to store as much history and useful information in the database as I can. Oh and as an aside, that data needs to be at least sufficient to generate a leaderboard".

Perhaps you noticed that their leaderboard query does not even use the match table (it only uses match_player). Despite not needing game_mode and the other data there immediately, this engineer decided that it is an important part of the application's history, and therefore should be stored.

To make querying a little easier, this engineer might decide to create a leaderboard view, which is basically a saved query that can be queried like a table:

CREATE VIEW leaderboard AS (
  SELECT username, SUM(points)
  FROM match_player
  GROUP BY username
  ORDER BY SUM(points) DESC
  LIMIT 20
);

SELECT * FROM leaderboard;

In come the bugs and new features

The bug - One day you discover that a bug in your game is being exploited, and some users have been able to score an unfair number of points. You look back at your git history and determine that the bug was introduced on April 4. You look back in your logs and find some match IDs where the bug was certainly exploited, and you also determine that if anyone was able to score more than 50 points in a single match, they must have been exploiting.

What do you do? If you only have a stateful leaderboard table, the situation is more difficult. Somehow you have to try to determine which users have exploited the bug. Then what? Delete them from the leaderboard entirely? Deduct some of their points? How many?

For the engineer who stored match history, the situation is easier. They can delete the bugged matches, and any that happened after April 4 where a player scored more than 50 points. Problem solved.

The new feature - One day you decide you want to create monthly leaderboards. If you went with the state-store architecture, you need to create at least one entirely new table, and you will not be able to show leaderboards for months that have already passed. If you went with the history-store architecture, you already have all of the data you need retroactively, and you just need to write a new query.

We can never know what the future will hold, but as we can see, the engineer who treats their database as a history store is much more equipped to face whatever requirements come their way!

Performance

One might point out that constantly aggregating over an entire table of match history to compute a leaderboard is not efficient. While this approach scales further than you might think, at some point it really does become too much. What should we do then?

Fortunately, we do not need to ditch the history-centric architecture. There are at least a couple of big guns we can bring out to greatly improve performance:

Materialized Views

Some databases, such as PostgreSQL, have first-class support for a concept referred to as materialized views.

A materialized view is a table whose contents are computed based on a query. If you are familiar with regular (non-materialized) views, the main difference is that a materialized view is stored on disk. The contents of a materialized view are only re-computed when requested, via running the REFRESH MATERIALIZED VIEW statement.

In the leaderboard example, the engineer who went with the history-store architecture can create a materialized view exactly like they created the regular view, just by adding the MATERIALIZED keyword:

CREATE MATERIALIZED VIEW leaderboard AS (
  SELECT username, SUM(points)
  FROM match_player
  GROUP BY username
  ORDER BY SUM(points) DESC
  LIMIT 20
);

And they can query this leaderboard materialized view exactly like they would query a table. Even if the match_player table has a huge number of records, fetching the top 20 scorers will be fast, because the rows in the materialized view are pre-computed and stored on disk.

To recompute the leaderboard every hour, you could use pg_cron to set up a cron job in the database:

CREATE EXTENSION IF NOT EXISTS pg_cron;

SELECT cron.schedule(
  'leaderboard-refresh',
  '0 * * * *',
  'REFRESH MATERIALIZED VIEW CONCURRENTLY leaderboard'
);

(Your PostgreSQL installation might already have pg_cron available, but if not, you would need to install it)

Then your leaderboard will automatically update every hour.

An obvious shortcoming here is that the leaderboard data can be up to one hour stale. Another is that, even if we only refresh the view once per hour, there is still some point at which that might become unsustainable in terms of performance (it would likely take many billions of matches before we get there, but this might be more relevant if you want to update the leaderboard say, every five seconds).

Despite these shortcomings, a materialized view is often a great solution. But if you need completely up-to-date data, or you have an un-utterably huge amount of data to aggregate over, the next technique might serve you better...

Incremental View Maintenance (IVM)

Thinking about it logically, when a player wins a match, do we really need to re-compute the entire leaderboard? Couldn't we just find that user's leaderboard record, and update their points?

Yes indeed we can! This approach is sometimes referred to as Incremental View Maintenance. It has been proposed as a first-class feature in PostgreSQL, but is not yet shipped. However we can implement it ourselves.

The naive way to do it is to create a leaderboard table, then whenever you insert a new record into the match_player table, you also have code to do an update on the leaderboard table to update the participants' points.

This can be an okay approach, but it requires vigilance to make sure your code always updates the leaderboard table when it updates the match_player table. A better way is to use triggers. You can write a trigger function which runs automatically whenever you update the match_player table. Whether you add new match records, delete records, or update records, your trigger function can update the leaderboard table appropriately. Best of all, the trigger function lives in the database itself, and the database takes care of running it whenever the match_player table changes. A trigger function for this scenario could look like this:

CREATE OR REPLACE FUNCTION update_leaderboard_function()
RETURNS TRIGGER AS $$
BEGIN
  IF (TG_OP = 'INSERT')
  THEN
    -- If a new match_player record is being inserted, we
    -- do an upsert on the leaderboard table to increase
    -- the points of the leaderboard record corresponding
    -- to that username in the new match record.
    -- IMPORTANT: The leaderboard table must have a unique
    -- index on the username column
    INSERT INTO leaderboard (username, points) 
    VALUES (NEW.username, NEW.points)
    ON CONFLICT (username)
    DO UPDATE SET points = leaderboard.points + NEW.points;
  ELSEIF (TG_OP = 'DELETE')
  THEN
    -- If a match_player record is being deleted, we update
    -- the leaderboard table and decrease the leaderboard
    -- points of the user whose match record was deleted.
    UPDATE leaderboard
    SET points = leaderboard.points - OLD.points
    WHERE leaderboard.username = OLD.username;
  ELSEIF (TG_OP = 'UPDATE')
  THEN
    -- If a match_player record is being updated, we calculate
    -- the difference in points between the new record
    -- and the old record and add that to the points of
    -- the user whose match record was updated (the difference
    -- might be negative, in which case the user's position
    -- on the leaderboard would go down)
    UPDATE leaderboard
    SET points = leaderboard.points + (NEW.points - OLD.points)
    WHERE leaderboard.username = OLD.username;
  END IF;

  RETURN NULL;
END;
$$ LANGUAGE plpgsql;

CREATE OR REPLACE TRIGGER update_leaderboard_trigger
AFTER INSERT OR UPDATE OR DELETE ON match_player
FOR EACH ROW
EXECUTE FUNCTION update_leaderboard_function();

That might look big and scary if you haven't worked with triggers before, but what it does is pretty simple:

If you INSERT into the match_player table, it adds points to the leaderboard table.
If you DELETE from the match_player table, it deducts points from the leaderboard table.
If you UPDATE the match_player table, it calculates the change in points (since the function has access to both the NEW and OLD version of the row) and applies the difference to the leaderboard table.

So this trigger automatically keeps your leaderboard up to date in real time! (as long as you do not TRUNCATE the match_player table, at least).

By using materialized views and/or IVM, you get more or less the best of both worlds. You get performance that's nearly as good as the simpler state-store architecture, while having the flexibility of the history-store architecture. These approaches do kind of let some statefulness creep back in, but it can be worth it for the performance gains, and the history still remains the ultimate source of truth.

Conclusion

Should a database store state, or should it store history and compute state from history? It turns out that the history-store architecture holds a lot of really compelling advantages. Personally, it is how I always design database schemas now, although I certainly do make compromises in some scenarios.

What do you think? Are you familiar with both of these architectures? Is there a third, fourth, or fifth that we should be talking about?

I took a few shortcuts to cut down on a line of code here and there, such as not always specifying primary keys, and using username as a unique ID. These should not be considered good practices.

🙏Please, specify your units! 📏

Randall — Sat, 10 Sep 2022 01:20:26 +0000

What sucks about this code?

const success = myCache.mset([
    {key: "myKey", val: obj, ttl: 10000},
    {key: "myKey2", val: obj2},
]);

It's not clear at all clear if the ttl is 10,000 milliseconds, seconds, or something else. Just glancing at this code (and knowing that JavaScript setTimeout() uses milliseconds), you might be tempted to think it's in milliseconds. Wrong! It's in seconds!

This snippet is example code from the README of node-cache. This type of unclear code is really prevalent, so I'm not trying to pick on them in particular. Fortunately, the README does say that it's in seconds, but you have to RTFM to be sure, and who's got time for that?

Wouldn't it be nice if the ttl property were named ttlSeconds? Then it's instantly clear what it means to whoever is reading the code.

Or maybe there's an even better solution.

Datetimes

It's also pretty common for datetimes to be represented as an integer number of milliseconds (or seconds) since the Unix epoch ( 00:00:00 UTC on 1 January 1970). For example:

const myBirthday = 700876800000;

This sucks too. You might recognize this as very likely being a number of milliseconds since the Unix epoch, but you have no idea what date this represents.

How about this instead:

const myBirthday = new Date('1992-03-18T00:00:00.000Z');

Now whoever's reading this code knows exactly what date it represents, and code that accesses myBirthday does too. Surrounding code doesn't need tribal knowledge about whether this number is a number of seconds or milliseconds. It's a Date, and has a very specific meaning.

TimeSpans

Jumping back to TTL (time to live) again. A TTL is not a specific date and time, but a length of time (one second, one year, etc), so we can't use Date to represent it.

Naming your TTL property ttlSeconds for clarity is a fine solution in a lot of cases, but what if there were a datatype similar to Date for this?

Some languages actually have such features built in. JavaScript doesn't, but we can use a package like timespan.

import timespan from 'timespan';

const ttl = timespan.fromSeconds(50);

console.log(ttl.totalMilliseconds()); // 50000
console.log(ttl.totalSeconds()); // 50
console.log(ttl.totalMinutes()); // 0.8333333333333334

You can specify your TTL in whatever units you want, and the code you pass your TTL to can read it in whatever units it wants. You don't have to agree on units at all.

If only NASA used constructs like this, they may have been able to save a few bucks.

Conclusion

Just a short one I wanted to get off my chest here. Many bugs have their roots in mix-ups about what units are being used. Fortunately we have some tools at our disposal to mitigate these sort of risks. I wish I saw them used more often!

⚡ When Faster Isn't Better

Randall — Sat, 06 Aug 2022 00:21:00 +0000

Lately I keep hearing about Bun, a new JavaScript runtime meant to compete with Node.js and Deno. It's fast, they're saying, and indeed two of the three bullet points on its homepage are different ways of saying "it's fast".

Fast is sexy, developers love fast things, everyone does. But this kind of fast isn't likely to do you much good, and we're going to talk about why.

To be clear, I'm not trying to pick on Bun in particular. I actually know very little about it beyond what's on its homepage and what people say about it. It might be great. Regardless, the claims it makes and the way people talk about it make it a great starting point for this discussion, which is about math more than anything else.

"This Kind of Fast"

The graphics on Bun's homepage show it performing approximately 3x faster than Node.js on three CPU bound tasks which are typical of web server applications:

1: Rendering and serving (React) webpages:

2: Querying a SQLite database¹

3: Hashing a string

The Billion Dollar Server

While the graphics above show the humble Node.js server rendering and serving about 16,000 pages per second, that's for an unrealistically simple case: a page that just says "Hello World" and is presumably served to a client running on the same machine.

The humble Node.js server won't get anywhere near that throughput on real-world workloads. As a rough estimate, let's suppose that a Next.js application running on a single-core Node.js server can serve approximately 100 pages per second. And let's suppose that Fast Engine's 3x performance (again, I'm not picking on Bun, I swear!) holds true here, and it can serve 300 pages per second.

Another way to look at this is: Fast Engine can serve 300 pages per second running on just one server. If you're using Node.js, you would have to buy an extra two servers to achieve that same throughput.

Here's the thing. Three hundred pages per second is about twenty five million per day. That's about seven hundred and fifty million per month.

Let's slap Google AdSense on this baby:

Turns out their calculator only goes up to ten million page views per month, which would net us about $700,000 per year.

Meanwhile an extra two single-core servers will cost you around $10-$20 per month.

So Fast Engine is saving you ten bucks per month on your multi-million dollar gravy train. See the problem? You have better things to worry about than ten dollars, for example, what kind of private jet you're going to buy.

The 93.333 Millisecond Request

Okay, but if Fast Engine's throughput advantages don't really matter, what about its improved response time? Fast Engine finishes rendering the page faster, so visitors see it faster, and are more satisfied, right?

Actually, they won't notice or care. Roughly speaking, if the Node.js server can serve 100 pages per second, that implies that it spends about 10 milliseconds of CPU time on each page render. Meanwhile Fast Engine, serving 300 pages per second, spends about 3.33 milliseconds of CPU time on each page.

But the request duration from the user's browser to the server and back is dominated by the latency between them and the server, and potentially also the latency between the server and other APIs and databases. Consequently, running the same code on Fast Engine might reduce the total request duration from, say, 100ms to 93.333ms. Again, it's an improvement on paper, but no one will notice or care.

The $10,000 Developer

Let's say you're not convinced, and you decide to go with Fast Engine anyway, and hire a developer to build your server for you.

You might find that this project, which would take, say, three months to build on Node.js, will take four months to build on Fast Engine, due to Fast Engine being less compatible with popular modules, having a smaller community to get help from, etc.

In the US, employing a developer full-time for a month is likely to cost you at least ten thousand US dollars in total expenses. So while you may have saved ten dollars per month in server costs someday down the line when your service gets popular, and you may have shaved a few milliseconds off of request duration, you paid $10,000 for that, and got your product to market a month later. Those are not good trade-offs.

To be clear, it's not necessarily the case that the "faster" engine will take longer to write code for. That might not be true. The point is that before getting starry-eyed about fast technologies, there are other factors to consider, and in most cases you will save a lot more money if you prioritize developer efficiency over software execution efficiency.

The Number-Crunching Desktop

Time to start putting in a few asterisks. So far, we've been talking about web server applications, where the workloads tend to be IO-bound and horizontal scaling is relatively cheap, easy, and infinite.

These arguments don't necessarily apply well to other domains. For example in a graphics engine, rendering 3x as many frames per second would be a tremendous improvement. That would triple the frame rate!

Absolutely, screaming fast code has an important place in the world. But that place is not JavaScript code running on web servers.

The Snappy Lambda

One final thing I want to discuss is serverless compute platforms such as AWS Lambda and Google Cloud Functions.

If there's anywhere we need fast JavaScript servers, this is it, due to the problem of cold starts.

A cold start occurs when the serverless platform needs to spin up a new instance of your code in order to service increased traffic. This can involve unzipping dependencies, booting the runtime, establishing database sessions, and a variety of other relatively slow operations.

All of this can result in requests to your server sporadically being noticeably slow. If Fast Engine can significantly reduce how long cold starts take, that would be nice.

Still, the potential benefits here are fairly limited, as:

"According to an analysis of production Lambda workloads, cold starts typically occur in under 1% of invocations. The duration of a cold start varies from under 100 ms to over 1 second." - Amazon

Furthermore, a lot of the slow operations involved in cold starts have little to nothing to do with the engine that your code is running on, and would not be improved by a faster engine.

Conclusion

In a vacuum, 3x performance sounds great, and understandably sends a tingle of joy up the spine of any developer. But in truth it's pretty meaningless without a more careful examination of the use case and an understanding of exactly which sections of it are getting faster and which aren't.

Sometimes the slow thing is still plenty fast, and the fast thing isn't as much faster as it first appears. Sometimes it doesn't really matter much either way.

The average JavaScript web server is one such case. That being said, every situation is unique and every tool has its place.

What do you think?

Note #1 - The SQLite benchmark is more CPU bound than one might imagine. SQLite has internal caching, which lives in the same process as the client. Running the same query over and over will read data from the cache, though its size is limited.

🎩The Magic of || and && in JavaScript

Randall — Sat, 16 Jul 2022 20:34:18 +0000

In JavaScript, it's common to see code like this:

const color = options.color || 'red';

Or like this:

const name = data && data.name;

You might know what this code does, but maybe you don't know why. A couple of simple but very clever core language mechanics enable us to write code like this. Despite the clickbait title, there is (sadly) no magic involved. Let's take a look at what's really going on here.

In case you don't know what this code does: the former snippet provides a default value for the color variable. If options.color is a truthy value (such as a non-empty string), then color gets set to that value. But if options.color is a falsy value, such as undefined, then color gets set to the default value of 'red'.

The latter snippet guards against data being undefined (or null). If data is undefined, then trying to reference data.name directly will result in an error being thrown. But if we use the && trick, there will be no error in such a case. name will just be set to undefined.

Boolean Expressions and Short-Circuit Evaluation

To understand how this works, it's important to first understand short-circuit evaluation.

In a language like JavaScript, short-circuit evaluation means that when a JavaScript engine evaluates a boolean expression (such as a || b), it will only evaluate as much of the expression as it needs to, in order to find the answer.

In the expression a || b (meaning a OR b), think logically about what happens if a is true. If a is true, then it doesn't even matter what b is, right? b could be true, false, or anything else, and the result of a || b will be true regardless. If a is true, then a OR b is also true, period.

JavaScript engines are smart enough to know this too, and in practice it means that if a is true (or any other truthy value), the engine won't even bother looking at b.

To see this in action, you could try running the following code:

console.log(true || null.abc);

While it's illegal to try to reference a property on null, this code does not error, because the engine never evaluates the right-hand-side of the expression! It doesn't need to, because the left-hand-side is sufficient to answer the question on its own.

Boolean Operators Don't Return Boolean Values!

The second piece of the puzzle is what's returned by boolean operators, such as || and &&. Often, developers assume that these operators return boolean values, but that's actually not the case.

Try running this code:

console.log('a' || 'b');

It does NOT return true. It returns 'a'!

And this code:

console.log('a' && 'b');

returns 'b'!

What's going on here? This is the part that I find really clever. Boolean expressions do not return boolean values, they actually return the last thing that was evaluated.

Thanks to short-circuit evaluation, when evaluating the expression 'a' || 'b', the engine only evaluates the left-hand-side of the expression. That means that 'a' is the last thing that it evaluates in this expression. Therefore, the return value of the expression is 'a'.

In the expression 'a' && 'b', the left-hand-side of the expression is truthy, but because this is an AND operation, the engine still has to look at the right-hand-side to check if it's truthy or not. If it is, the expression is true. If it's not, then the expression is false. That means in this case, the final thing that's evaluated in this expression is 'b'. That's why 'b' is the return value of the expression.

Putting it Together

That's the theory, but we can boil it down into simpler-sounding rules that might make it easier to use in practice:

The || operator returns the thing on left-hand-side, if that thing is truthy. If it's not, it returns the thing on the right-hand-side.
The && operator returns the thing on the left-hand-side, if that thing is falsy. If it's not, it returns the thing on the right-hand-side.

Let's look at the examples from the top of the article again:

const color = options.color || 'red';

Applying rule #1, if options.color is truthy, the expression returns options.color. Otherwise, it returns 'red'.

const name = data && data.name;

Applying rule #2, if data is falsy, the expression returns data. Otherwise, it returns data.name.

Getting Fancy

You can get pretty fancy with this. For example, if you want to look at a property deep inside of an object, and provide a default value if it's not there, you could write code like this:

const name = (data && data.profile && data.profile.name) || 'Name Unknown';

If data is truthy, it will return the thing on the right. The thing on the right is yet another boolean expression, where if data.profile is truthy, it too will return the thing on the right. If any of this is falsy, then (data && data.profile && data.profile.name) will return the last thing it evaluated. Since that thing would be falsy, || will return the thing on the right-hand-side, 'Name Unknown'.

Does that sound a bit convoluted? I hope it does, and I wouldn't recommend writing code like this. It can get pretty hard to understand. But if you do understand it, then congratulations, you understand the magic of JavaScript boolean expressions.

Optional Chaining and Nullish-Coalescing

As an aside, while code like the above used to be somewhat common in JavaScript, the new-ish optional chaining and nullish-coalescing features give us a simpler way to do the same thing:

const name = data?.profile?.name ?? 'Name Unknown';

We won't dive into that, but it deserves mention.

Conclusion

JavaScript engines only evaluate the parts of a boolean expression that they need to, and boolean expressions return the last thing that was evaluated. That's it. It's a simple mechanism, but it enables some pretty magical-looking constructs. Hopefully this article helped unwind the mystery, and if you have any questions or comments please post them below!

Don't parse CSVs by hand!

Randall — Wed, 11 May 2022 22:52:53 +0000

I've seen custom JavaScript code to parse CSV data a number of times. It looks something like this:

const csvData = fs.readFileSync(csvFilePath, 'utf8');
const lines = csvData.split('\n');
const rows = lines.map(line => line.split(','));

So simple, and it may be fine if you're parsing a single static CSV file whose content you know. But if you're parsing unknown CSV files, don't do this, there are many ways it can break.

What Can Go Wrong

Escaped cells

Columns in a CSV file may contain commas. Such columns are typically escaped with quotes. The raw data for a row with such a column might look something like this:

Name,Best Line
Hamlet,"To be, or not to be"

Though the second line has two commas, this produces a table with two columns, not three:

Name	Best Line
Hamlet	To be, or not to be

This breaks the simple CSV parser implementation which just splits on ,.

Line Endings

The simple CSV parser implementation assumes LF line endings (\n), but text files, including CSV files, created on Windows will often have CRLF line endings (\r\n). Further, there may be line ending characters within escaped cells. Needless to say, these cases break the simple CSV parser implementation.

What to do instead

Bring in a library that's built for this. I like to use csv-parse. It's easy to use:

import { parse as csvParse } from 'csv-parse/sync';

const csvData = fs.readFileSync(csvFilePath, 'utf8');
const rows = csvParse(csvData);

That's it.

Conclusion

I know no one likes bringing in libraries to solve what seems to be a simple task, but parsing arbitrary CSVs correctly is actually a lot harder than it looks at first glance. Save yourself the pain, use someone else's battle-hardened parser.

Discord Webhook Powered Contact Form

Randall — Thu, 27 Jan 2022 02:17:55 +0000

Recently more and more people have been discovering the power of personal Discord servers. You can use them to store files, write notes, mess around with bots, and more.

In this article, I will show you how to hook up a contact form on your website to send mail to your Discord server. It's free, it's easy, and it does not even require a backend server.

Before getting started, you should know basic HTML and JavaScript, and you should have a Discord account and a private Discord server (use the plus button in the bottom left of the Discord desktop client to create one).

Creating a Webhook

First, we need to create a webhook in Discord. Decide which channel in your private server you want to receive mail in, and click the settings button. I'm going to use the #general channel:

In the settings window, go to the Integrations section, and click Create Webhook:

After the webhook has been created, give it a name (I chose Contacts), and click Copy Webhook URL. This will copy the webhook URL to your clipboard. We'll need it in a little bit.

Making the Contact Form

This article is going to focus on how to call the webhook via JavaScript, so I'm going to gloss over the HTML part a bit. If you want to follow along, you can copy and paste this code into a file called contact.html:

<html>
  <head>
    <!-- Bootstrap CSS -->
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-1BmE4kWBq78iYhFldvKuhfTAU6auU8tT94WrHftjDbrCEXSU1oBoqyl2QvZ6jIW3" crossorigin="anonymous">
  </head>
  <body class="container mt-5">
    <form onsubmit="sendContact(event)">
      <div class="mb-3">
        <label for="emailInput" class="form-label">Enter your email address</label>
        <input type="email" class="form-control" id="emailInput">
      </div>
      <div class="mb-3">
        <label for="messageInput" class="form-label">Enter your message</label>
        <textarea class="form-control" id="messageInput" rows="3"></textarea>
      </div>
      <button type="submit" class="btn btn-primary">Submit</button>
    </form>
    <script>
      async function sendContact(ev) {
      }
    </script>
  </body>
</html>

It's just really basic HTML boilerplate plus bootstrap to make things look slightly non-gross.

If you open the contact.html file in your browser, this is what you will see:

And if you click the Submit button, it will call the sendContact function, which does nothing!

So let's make it do something. Let's start writing code in the sendContact() function.

First, no surprises, let's prevent the default form submit action, and let's get the email address and message that the user input:

ev.preventDefault();

const senderEmail = document
  .getElementById('emailInput').value;
const senderMessage = document
  .getElementById('messageInput').value;

Next let's craft the body that we're going to send to the webhook. The body should be a Discord message object, which is clearly documented in the Discord API documentation.

In our case, we just want a message with a title and two sub-sections: Sender and Message. That's going to look like this:

const webhookBody = {
  embeds: [{
    title: 'Contact Form Submitted',
    fields: [
      { name: 'Sender', value: senderEmail },
      { name: 'Message', value: senderMessage }
    ]
  }],
};

Now we just use fetch to send the webhook. Remember that webhook URL you copied earlier? You'll need it here. Paste it in as the value of the webhookUrl variable:

const webhookUrl = 'YOUR URL HERE';

const response = await fetch(webhookUrl, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(webhookBody),
});

Then let's show an alert and tell the user whether the request was successful:

if (response.ok) {
  alert('I have received your message!');
} else {
  alert('There was an error! Try again later!');
}

That's it! Refresh the page, type in an email and message, and click Submit.

If you did everything right, you should hear a satisfying little ting sound from your Discord client telling you that there has been a new message in your server. Check it out:

With just a little bit of frontend code we now officially have our contact form sending mail to our private Discord server.

Full Code

Here's the full code that I used for this demo. Remember to replace YOUR URL HERE with your webhook URL.

<html>
  <head>
    <!-- Bootstrap CSS -->
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-1BmE4kWBq78iYhFldvKuhfTAU6auU8tT94WrHftjDbrCEXSU1oBoqyl2QvZ6jIW3" crossorigin="anonymous">
  </head>
  <body class="container mt-5">
    <form onsubmit="sendContact(event)">
      <div class="mb-3">
        <label for="emailInput" class="form-label">Enter your email address</label>
        <input type="email" class="form-control" id="emailInput">
      </div>
      <div class="mb-3">
        <label for="messageInput" class="form-label">Enter your message</label>
        <textarea class="form-control" id="messageInput" rows="3"></textarea>
      </div>
      <button type="submit" class="btn btn-primary">Submit</button>
    </form>
    <script>
      async function sendContact(ev) {
        ev.preventDefault();

        const senderEmail = document
          .getElementById('emailInput').value;
        const senderMessage = document
          .getElementById('messageInput').value;

        const webhookBody = {
          embeds: [{
            title: 'Contact Form Submitted',
            fields: [
              { name: 'Sender', value: senderEmail },
              { name: 'Message', value: senderMessage }
            ]
          }],
        };

        const webhookUrl = 'YOUR URL HERE';

        const response = await fetch(webhookUrl, {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
          },
          body: JSON.stringify(webhookBody),
        });

        if (response.ok) {
          alert('I have received your message!');
        } else {
          alert('There was an error! Try again later!');
        }
      }
    </script>
  </body>
</html>

A Word of Caution

It's important to understand that putting your webhook link into your frontend code means that a malicious actor could take it and use it in a script to spam you or even send you nasty images.

Fortunately, that's about the worst they could do. The link only allows sending messages in your server, and does not allow reading messages, taking any sort of administrative action, or really anything else.

So while embedding the webhook link into your small, personal website is likely going to be fine, I would not do this for anything major, or if I had a lot of tech-savvy enemies. I also would not do this in a Discord channel that many other people have read access to.

If you are concerned about these risks but you still want to use a Discord webhook for your contact form, you would need some sort of backend to be a middleman for the requests. In fact, I use that approach for my own personal site.

Blocked TLDs

It has come to my attention that this method does not work for *.tk domains. Discord seems to selectively not return the needed CORS headers for TLDs that it does not like. Besides getting a new domain, your only option involves proxying the request through a backend server.

Conclusion

Getting contact forms to work well (for free) can actually be harder than it sounds. I used to use Gmail's SMTP server via my personal website's backend for this, but it would frequently stop working for "security reasons" until I went into my account and reminded Google that it's legit traffic. I ended up swapping in a Discord webhook instead and haven't looked back. It's super convenient and easy to set up, and has worked very reliably.

👻The Nightmarishly Dangerous Default Behavior of setInterval()

Randall — Sat, 08 Jan 2022 18:07:14 +0000

So you want to send an HTTP request every delay number of milliseconds. Easy:

setInterval(
  () => {
    doRequest();
  },
  delay,
);

But what if delay is undefined?

Here's where it gets scary. It turns out that if delay is undefined (or null, NaN, etc), it will default to 1 millisecond! Enjoy your DoS attack!

I've seen this issue affect production systems on two occasions now, and both instances caused significant damage and required emergency maintenance.

A Safer setInterval()

If you're concerned about this possibility, you can replace setInterval with safer code. Execute this code as early as possible during initialization:

const oldSetInterval = setInterval;
globalThis.setInterval = (callback, delay, ...rest) => {
  if (typeof delay !== 'number' || delay < 1 || delay > 2147483647) {
    throw new Error(`Invalid interval delay: ${delay}`);
  }

  return oldSetInterval(callback, delay, ...rest);
};

This replaces the setInterval function globally with a wrapper that will throw an error if the delay argument is not a number or is outside of the valid range. No one likes errors, but it's usually better than accidentally making 1,000 requests per second!

Other Implementations of setInterval()

I've been talking about Node.js so far, and this behavior is clearly documented in the Node.js documentation.

But setInterval() is actually not part of the ECMAScript standard, and some of its details may vary across different JavaScript environments.

Here's some code you can execute to see what the default delay is in your environment:

let prev;
setInterval(() => {
  const cur = new Date().getTime();
  if (prev) {
    console.log(`MS elapsed: ${cur - prev}`);
  }

  prev = cur;
});

It looks like in Firefox, the default delay is 16 ms, while in Chrome it's 4. While the Node.js documentation states that it's 1 ms, my testing suggests that it's very inconsistent in Node.js, much more so than in browsers. I'm not sure why.

setTimeout()

To be clear, yes, setTimeout() does have exactly the same issue.

Conclusion

I don't know who thought it was a good idea to default the delay to a low number. Throwing an error when delay is invalid sounds like a much better idea to me. But whatever, it is what it is! We just have to understand it and be careful.