Christophilus

Why hasn't X given us a productivity boost?

Sun, 22 Feb 2026 12:00:00 GMT

Why hasn't X given us a productivity boost?

I've heard this question many times through the years, where X is Windows, OOP, the internet, blockchain, agile, AI, etc.

Sometimes, the answer is that X is overrated. Sometimes it's that you're doing X wrong. Sometimes it's because you don't have an X-sized problem. For instance, most businesses didn't have a blockchain-sized problem.

The question I'm asked most often today is, "Why hasn't AI lived up to the hype?" There are a number of reasons. Today, I want to talk about one. And to do that, I'll focus on AI in the enterprise. And to do that, I want to first talk about agile.

I used to hear, "We adopted agile, and things got worse!"

When people tell me, "We adopted agile," what they almost always mean is, "Management forced a daily standup on the entire engineering org without bothering to get buy-in from anyone."

Management forces their team into a new process without first thinking through the second-order effects.

Let's think about that 15 minute standup. You block out 15 minutes every morning, but it really lasts 30 minutes because Bill always rambles on and on while everyone's eyes glaze over. What is the true cost of that meeting? Well, when an engineer sees a meeting on their calendar, they think, "I can't do any deep work for at least an hour ahead of that."

It takes time to get into deep work, so no one attempts it when they know they'll be interrupted by a meeting just as they're getting into their flow. Every meeting that lasts N minute probably costs you around N + 60 minutes of deep work. But there's also the post-meeting doledrums. I don't know any developer who leaves a standup energized and ready to dive into work. Instead, they take a break, reset and get into a good head-space. So, there's easily another 10-15 minute buffer following a standup. That 15 minute standup that last 30 minutes actually costs you closer to 100 minutes. Per day.

That's not exactly accurate. I do work before the standup, but I don't do deep work. I do tedious work like reviewing GitHub issues, checking email, etc. This is work that I'd probably do at some point in my day, anyway, but the standup is forcing me to do it at a time of day when I'm more capable of doing deep work-- rather than at the end of the day when my mind is better spent on shallower tasks. So, there's a real cost to that morning standup. The cost is fuzzy, and you can disagree with my numbers, but it's a real and recurring cost.

Let's be conservative and call the true cost of a standup 1 hour. That's 1/8th of your engineering hours wasted. The decision to adopt agile cost your engineering team 12% of their time budget.

A standup arguably has some value, but it's not worth 12% of your engineering costs.

But that's not the only problem. You're paying a bigger time penalty than you probably realize, but you're also paying a morale penalty. Forcing tedious, useless meetings on developers-- and in most organizations, for most of the engineers, standups are pretty useless. Maybe not 100% useless, but let's call it 80% useless. For mediocre engineering teams this isn't a huge deal. But good engineering teams will resent this. The more time-wasting bureaucratic friction you add to your engineering org, the more likely you are to nudge your best engineers towards the exit, and the more likely you are to retain the mediocre engineers.

The point is, top-down decisions without buy-in happen all the time, and have plenty of second order effects and far-reaching consequences.

What does this have to do with AI? The same management mindset that forced their teams to use "agile" forces their teams to use AI. There are huge engineering orgs that have made AI usage as part of their employee evaluations-- not using AI enough? You're on an improvement plan. What are the second-order effects of this?

Resentment, active sabotage, ridiculous workarounds and gaming the system-- all sorts of second order effects. But, productivity? No. Not because AI is a useless or unproductive tool, but because forcing AI into an org that doesn't want it, doesn't know how to use it, isn't optimized for it, and (often) actively resents it-- that will produce a lot of things, but it won't produce productivity.

Why hasn't AI given a measurable, objective performance boost to big enterprises? It's because the problems big enterprises have are not AI-shaped. They are cultural. And a broken culture is probably the hardest thing to mend.

Preventing the Collapse of Civilization

Wed, 21 Jan 2026 12:00:00 GMT

Preventing the Collapse of Civilization

In 2019, Jon Blow gave a talk called Preventing the Collapse of Civilization. He presents a historical walkthrough of technology which has been lost over the millenia, and ends with a warning that this could happen to us.

In the light of agentic coding agents, this talk seems even more prescient.

Claude Code Example

Fri, 09 Jan 2026 12:00:00 GMT

Claude Code Example

I've used Claude Code off an on for around a year, using it heavily in the last few months. I thought it might be helpful for others (and maybe my future self) if I jotted down an example scenario and a specific prompt I used.

Overly general guidance

I recently asked it to build a feature for me-- a calendar view that organization admins could use to see all scheduled activity across their entire organization. An organization might have multiple instructors, each of which is creating and leading multiple courses, any of which might have scheduled meetings and modules. Each course has its own calendar view, but until recently, there was no way for admins to get a high-level calendar view for the entire organization.

So, I tasked Claude Code with this, and it built it in a few minutes. It didn't take long before I realized the solution was pretty terrible.

Claude had:

Attempted to use kysely (a database library we don't use)
Decided to pull all courses, instructors, and scheduled items into memory and do the filtering there rather than in Postgres
Sent the entire payload to the browser to do live-processing there
Made numerous glaring mistakes in the Preact layer

Some other things I've frequently seen Claude do:

N+1 queries where a single well-structured query (e.g. a merge or window function) would serve.
Improper data access validation (for example, not ensuring that ids sent from the client actually belong to / are accessible by the caller).

Specific guidance

So, here's how I guided it to properly implement the front-end for the calendar feature:

Browser

The calendar will be driven by a state object:

// Pseudo
type State = {
  // The 1st of the month being viewed
  start: Date;
  instructors:
    | { type: 'all' }
    | { type: 'some', ids: UUID[] }
  courses:
    | { type: 'all' }
    | { type: 'some', ids: UUID[] }
  items: Array<'modules' | 'meetings'>;
};

const defaultState = {
  start: now().onDay(1),
  guides: { type: 'all' },
  courses: { type: 'all' }
  items: ['modules', 'meetings'],
};

function Page(props) {
  const [state, setState] = useState<State>(() => {
    try {
      return JSON.parse(props.params.filter);
    } catch {
      return defaultState;
    }
  });

  // etc...
}

Note: We'll have a max size for the ids arrays-- maybe 10 or 20 or something.

When the state changes, we'll update the URL without triggering a re-render simply so that if the user refreshes, they'll see the same view, and they can also copy / paste the URL with other admins to share the view they're seeing.

// Pseudo
useDidUpdateEffect(() => {
  const queryStr = JSON.stringify(state);
  router.rewrite(`${location.pathname}?filter=${encodeURIComponent(queryStr)}`);
}, [state]);

The data we display (the side-nav courses, and the items in the calendar, etc) will be loaded from the server any time that filter changes. We can use a debounce if we like. All of this (including race-condition handling) is built into our existing useAsyncData hook:

const data = useAsyncData(() => rpx.adminCalendar.load({ ...state, timezone }), [state]);

Note: We may want to use Zod or something like it to parse the state rather than just parsing it as JSON, so that we force it to conform to the expected shape that we can pass directly to the rpx endpoint.

Remember to use a functional, immutable approach. Use simple state objects to avoid awkward equality checks and mutations:

// NO
const [selectedIds, setSelectedIds] = useState(new Set());
const toggleId = (id) => setSelectedIds((ids) => {
  if (ids.has(id)) {
    ids.delete(id);
  } else {
    ids.add(id);
  }
  return ids;
});

// YES
const [selectedIds, setSelectedIds] = useState([]);
const toggleId = (id) => setSelectedIds((ids) => {
  return ids.includes(id) ? ids.filter((x) => x !== id) : [...ids, id];
});

Server

The endpoint can probably query the information we need by using a single query. For any given date, we want to display the first 2 items, with meetings being prioritized over modules. We'll display + N more... and allow the user to click that to view all items for a specific date.

So, our RPC function will end up returning something like this:

type Item = {
  id: UUID;
  timestamp: Date;
  title: string;
  type: 'module' | 'meeting';
};

type DateResult = {
  date: Date;
  numItems: number;
  items: Item;
};

type ReturnType = {
  dates: DateResult[];
};

We can flesh it out more as we go.

We should probably use a window function or something like that to efficiently collect the items per date.
We need to ensure we use the passed timezone so we group the items into the proper date (e.g. an item might be Tuesday in UTC, but Wednesday in the caller's timezone)
Ensure the results all belong to the current organization, and that the caller is at least an active, valid admin in that organization

Where do we go from here?

Tue, 06 Jan 2026 12:00:00 GMT

Where do we go from here?

AI has changed the software engineering profession. Is this change permanent? If so, what does the profession look like moving forward? Are incoming grads screwed? Does experience matter at all? What should I do about my career if I'm not ready for early retirement, but am too old to make a significant career pivot?

I'll explore all of this and more below.

Is this permanent?

I think so, yeah. How could this all grind to a halt and reverse? The AI companies could go belly-up, but in that case, their existing models would be bought on the cheap by a big corp like Microsoft. The models won't disappear due to bankruptcy.

What about poisoning? Some disgruntled devs are attempting to disseminate LLM poison across the web. I think this is both wrong and futile. If the malcontents succeed in poisoning all future training attempts, the current models will become the permanent plateau. They're good enough as is, so poisoning won't give us a reversion to the good old days.

What does software engineering become?

The majority of work in this industry will be a combination of product management, micro-management of agent teams, and code reviewing.

A note about AI skepticism

Here, I'll take a moment to address AI skeptics. The skeptics claim that AI is only good for generating boilerplate code. It can't do anything novel or interesting. The only jobs it will automate are code-monkey jobs, and the interesting jobs will remain.

But, I think this is wrong. With guidance, agents can definitely generate code which has never existed before. If you think of a completely new concept, you will still build it on existing languages using variables, conditionals, and loops, or some higher level functional abstraction over those. Well, if you can write it, you can guide an agent to write it.

I've gotten Claude Code to write most of a password manager in Hare-- an obscure language that is almost certainly a tiny fraction of Claude's training data. It can do more than build trivial CRUD applications.

Are incoming grads screwed?

I don't know. Maybe. My advice to young people is to try to find work that they'll enjoy, that will contribute positively to society, and that will not be easy to automate away. Blue collar work clearly fits the bill: plumbers, builders, electricians, etc. Careers that will always require human discretion, or where human-to-human interaction is part of the point-- doctors, nurses, psychologists, etc.

If you're entrepreneurial, think about how you can provide value to people in your community. Be a value creator, and ideally, find a way to create value in the physical world.

Does experience matter at all?

Yeah. It does. The best way to guide an agent is to break a system down into clean modules with clear boundaries, so the agent can focus on specific subsystems without blowing up context or getting lost in the weeds. Without proper organization, a project will slowly become unmaintainable. This is true whether regardless of whether it's built by humans or by AI agents.

What should I do about my career?

Personally, I've avoided climbing the management ladder. I've been a team lead a few times, but that mostly involved hiring the right people and letting them do what they do best. I don't know that I want to spend the rest of my career coddling and babysitting LLMs. I don't see myself lasting very long if my job consists primarily in reviewing AI slop.

So, what's an engineer to do? To this, I don't yet have an answer. This year, I will discover whether or not I enjoy shifting primarily to product management.

Claude and Bun

Mon, 08 Dec 2025 12:00:00 GMT

Claude and Bun

I thought of this project after the Nth npm-related vulnerability. How realistic is it to build a low-dependency application, using Claude to generate code that you would normally pull in from npm?

I also wanted to do a deeper assessment of building something realistic in Bun.

Replacing npm with Claude Code

Most of the code in the project was written by Claude Code (Opus 4.5). I didn't review any of the tests or markdown files. I did however review the generated source code. For important files, my reviews were thorough(ish). For unimportant files (e.g. CSS), I just did a quick scan.

The results not excellent, but acceptable. Most of the time, its first solution was almost good enough. It went wrong in various ways. It tended to be overly verbose or inefficient in ways humans probably would have avoided. It sometimes solved problems by littering a module with effectful global mutatable state. It often generated code which was quite different in style from other code in the project (this may be due to me not properly shaping my claude.md or whatever).

That said, TypeScript and Biome helped guide things to a mostly consistent place faster than if I'd written all of this myself. The total effort I exerted to build this project was lower than if I'd built it myself.

Is it more secure than npm?

Maybe, maybe not. I have no doubt an astute security researcher could find vulnerabilities in this codebase. There are certainly fewer eyes on this than on a popular npm package. On the other hand, the code that is committed here gets reviewed rather than blindly pulled and updated (as is the case with every npm-based project I've ever been a part of). And I don't need to worry about the never ending upgrade cycle and resulting instability.

Benefits of DIY w/ Claude

With Claude, you can build a set of tools that fit you and your application. With npm, you end up cobbling together a bunch of disparate libraries, each with a distinct style and flavor, some of which are unpleasant.

With Claude, you build what you need. With npm, you are likely to pull in an overly general library that gives you the function you want along with 10 you don't.

Is it faster than npm?

No. Maybe? This project took quite a bit longer to to build than if I had simply run npm install a bunch of crap and then tossed the app together. About half of my time on the project was iterating on architecture / API design, and half was code-review and providing feedback to Claude.

However, now that the foundation is built, maybe it will be faster moving forward. I may build another demo project on top of this, and see how that goes.

What about Bun?

Let's move on to Bun.

So far, building on top of Bun has been excellent with on caveat.

Bun's SQL layer is incomplete:

No logging support
No transform support (e.g. no equivalent to Postgres.js transform: toCamel)
No support for streaming large resultsets

The first two aren't showstoppers. They're annoying, and require a bit more care when querying data. But the lack of streaming does make certain classes of applications impossible to build effectively (anything which needs to read massive amounts of data from a database for any purpose).

Conclusion

I quite enjoyed this. Claude Code with Opus 4.5 and Bun is a very nice combo. So nice, in fact, that Anthropic acquired Bun. If you've still not built anything with these two tools, I highly recommend giving it a try.

Podman dev environment

Fri, 06 Jun 2025 12:00:00 GMT

Podman dev environment

A couple years ago, after yet another egregious malicious npm package, I changed my dev environment.

A friend asked me to do a quick write-up, so here you go. You're welcome, Matt.

I run a lot of little local projects, each of which has their own dependencies. I don't trust the supply chain for all of my Neovim plugins, Ruby gems, Go deps, npm packages, etc. So, I decided to create a little tool based on Podman which allows me to quickly spin up a dev container in any given folder. And sandbox all of my dependencies-- including my dev tools-- inside it.

The workflow

I cd ./some/folder, then type dev sh, and I'm in a container with ./some/folder mounted at /src. That's it.

I generally spawn a few terminals and run dev sh in each: one for npm start or whatever, one for claude or my terminal-based AI agent, and one for nvim. Could I use tmux or Nvim to multiplex? Yes. Do I want to? No. I like letting my window manager handle this, and it's not a big enough hassle that I've ever considered automating it in any way.

Securityish

The containers don't have access to anything on the host machine other than the specific folder from which I ran my dev sh command and any ports which my .podman/env file directs it to expose.

Since it's podman, it is rootless. This means, if anything running in the container gets out onto my host machine, at least it won't be running with root privileges.

No orchestration

I install all of my dependencies in the container. This includes my editor (Neovim and various plugins), database (generally Postgres using pgenv), Claude Code, etc.

Basically, I treat my podman containers as if they're a traditional virtual machine. I put everything in there. I don't bother with docker compose or whatever. That's for CI and production pipelines. On my dev box, every project is a single container, and it's super simple.

Terminal-based tools work really well here. Neovim and Claude Code run in the containers, so I don't have to fiddle with trying to get my IDE or whatever to understand that I'm using docker.

I don't need to worry (as much) about Claude Code or a rogue Neovim plugin grabbing stuff they shouldn't. They can only grab what's in my container which is never super sensitive info.

Arch

I've used Debian, Fedora, and Arch-based images, but I've settled on Arch. This is mainly because I like to have the latest packages. If I need a specific version of a thing, I'll install that thing using a tool like pgenv for Postgres, or nvm for Node. For everything else, I just use Arch's package manager.

Niri

On my host machine, I run Fedora or Arch with Niri as the window manager. Niri is awesome. Spawning, switching between, and closing windows is natural, and my hands barely have to move to make it happen.

I never liked tiling WMs, because I can't do anything useful in a tiny square. Niri gives each window full height and a decent width by default, and simply places all of your windows in an infinite horizontal line. I quickly move between windows using the Super key + vim motions (e.g. Super+l focuses the window to the right Super+h focuses the window to the left). Resizing windows, moving them, stacking or unstacking them centering / uncentering them, etc are all very quick operations with efficient keybindings to keep me in my flow state.

Speaking of flow-state, I spawn a lot of ad-hoc terminal instances. I use the Foot terminal because it launches instantly and is very light-weight by modern terminal standards, so I can go from "I wonder what the output of foo bar is?" to spawning + running that command instantly without interrupting my flow-state.

Basically, Niri + Foot + Podman = <3.

Firebird

Thu, 05 Dec 2024 12:00:00 GMT

Firebird

While poking around with a play project, I was thinking, "Wouldn't it be nice if SQLite had a server mode?". It'd be nice to have a database that could give us the best of both worlds-- the simplicity of SQLite and the multi-client scalability of Postgres. You could build small projects with it, and if any of them ever needed to scale, no problemo.

Well, Firebird might be that database. It's an old database from the days of Pascal. It can be embedded, can run in embedded environments, and can run as a standalone server on a high-core, high-RAM beast of a machine.

Let's take a look.

Installation

Installation is pretty straightfoward. You download, unzip, and run an install script:

curl -O "https://github.com/FirebirdSQL/firebird/releases/download/v5.0.1/Firebird-5.0.1.1469-0-linux-x64.tar.gz"

tar -xvzf "Firebird-5.0.1.1469-0-linux-x64.tar.gz"

./Firebird-5.0.1.1469-0-linux-x64/install.sh

The instlal script prompts you to create a password for the sysdba user.

Everything is now installed in /opt/firebird. The server can be configured by editing /opt/firebird/firebird.conf. All binaries are in /opt/firebird/bin which you should add to your path.

To start Firebird in server mode, all you have to do is run:

firebird

Firebird comes with an example database: /opt/firebird/examples/empbuild/employee.fdb. Let's connect to that using the Firebird interactive tool isql.

# Replace "secret" with whatever password you set up previously
isql -user sysdba -password secret /opt/firebird/examples/empbuild/employee.fdb

Here, we can list the tables by running an isql-specific command show tables; or with a bit of standard SQL:

SELECT RDB$RELATION_NAME
FROM RDB$RELATIONS
WHERE RDB$SYSTEM_FLAG = 0 AND RDB$RELATION_TYPE = 0;

We see the following:

RDB$RELATION_NAME
=============================================================== 
COUNTRY
JOB
DEPARTMENT
EMPLOYEE
PROJECT
EMPLOYEE_PROJECT
PROJ_DEPT_BUDGET
SALARY_HISTORY
CUSTOMER
SALES

Let's have a look at the first employee record:

SELECT FIRST 1 * FROM employee;

If your terminal isn't wide, it might be hard to read the output due to text wrapping. You can run SET LIST ON; to change how the rows are printed.

Transactions

An interesting thing to note is that everything in Firebird happens in a transaction, and by default, the isolation level is snapshot. This caught me off-guard, as I've never used snapshot isolation in any other database.

To illustrate this, fire up two separate isql instances.

In one instance, modify the database:

UPDATE employee SET first_name='Bobby' WHERE emp_no=2;

Then, in both isql instances, retrieve that record:

SELECT first_name FROM employee WHERE emp_no=2;

One will show Bobby and one with show Robert.

That's because we haven't committed our transaction. In the isql where you ran the update, go ahead and run COMMIT;, then re-run the select queries.

There's no change! Bobby and Robert still show up.

That's because the "Robert" isql instance is viewing a snapshot of the database as it was when the database connection was established. To view the latest data, you have to COMMIT; there, too, and now you're looking at the latest version of the database.

As I said, this surprised me, since it's not the default behavior of any database I've ever used. The transaction levels can be controlled explicitly. See the docs and this blog post for details of how Firebird transactions work.

Are price controls defensible?

Thu, 19 Sep 2024 12:00:00 GMT

Are price controls defensible?

Are price controls defensible? John Kenneth Galbraith is the most competent, intelligent defender of price controls that I've come across. He was in charge of WWII price fixing— a scheme which most consider to have been a success. War is almost always inflationary. WWI certainly was. WWII much less so. In his book "Money: Whence It Came, Where It Went" Galbraith makes the heretical argument that peacetime governments should use price controls as a means of fighting inflation.

Such a proposal faces numerous challenges which Galbraith himself admits. Incompetent people tend to rise to power in government in general, and in the administration of monetary and fiscal policy in particular. Price controls work only when dealing with centralized corporations who have pricing power. They will not work when imposed on a broadly decentralized and highly competitive area of the market (such as groceries). There are two reasons such areas should be left alone. Competition naturally keeps margins low. Markets with many players— none of whom have pricing power— cannot be easily monitored and controlled. On the other hand, sectors with high pricing power— monopolistic, oligopolistic, and unionized areas of the economy— provide a large, convenient, manipulable target. There are fewer moving parts. There is a better paper trail. There is higher risk aversion. And because of pricing power, normal competitive market forces are either missing, ineffective, or greatly handicapped.

Such is my reduction of his argument.

Galbraith wrote during the mid seventies. His America still had strong unions. He wrote from the midst of spiraling inflation which worked something like this: a monopoly (let's say US Steel) raised its prices. The steel union wanted its cut, so it negotiated higher wages. Higher wages ate into profits, so the monopoly raised its prices again. The union wanted its cut, etc. Market forces did not soon arrest such a spiral. Inflation continued until the economy was wrecked and price increases could no longer be withstood.

In the 1970s, Galbraith noted, price controls already existed. They simply weren't government-imposed. Instead, the board of US Steel, or OPEC, or similarly monopolistic enterprises imposed their own— always bloated, often artificial— prices. Why not turn such power over to a government that could take macro economic health into consideration?

Modern economics is caught in an endless cycle of boom and bust. Inflation is fought only with a clumsy combination monetary and fiscal policy. Each cycle always ends in a painful period of high unemployment, civil unrest, and protracted recession or depression. In Galbraith's opinion, government-imposed price and wage controls could smooth the curves of such cycles thereby avoiding much of the massive economic pain associated with the deflationary side.

Such a system might bring other benefits. In WWII if a company was allowed to charge $20 per unit, it quickly found a way to produce that unit for less than $20. It also discovered how to produce and sold more units as a means to increase its net profit, if not its margins. A consequence was that production and productivity expanded massively.

My uninformed opinion

I am in no position to critique Galbraith. I'm an economically ignorant programmer who just so happens to have enjoyed reading his books. Thus what follows is a continuation of my lifelong habit of speaking overconfidently from a place of ignorance.

When it comes to peacetime price controls, I'm not as optimistic as Galbraith. Wartime controls had the necessary prerequisites of broad popular support and competent administrators. It is hard to imagine either of those prerequisites being found today.

To combat incompetence, Galbraith says that we must fire any administrators under whom economic policies fail. But such political will is unlikely to be found with any regularity. As always, we will end up with long tenured bureaucrats competent only at masking their incompetence with an obfuscating haze of sophisticated language.

Another problem with price controls is capital flight. In WWII, the best place to deploy your capital was the United States. Where else could you go? Europe with Hitler poised to seize your assets? Asia with the Japanese rampaging? The Soviet Union? Africa? Everywhere there was war, instability, and uncertainty. The only place to deploy capital with reasonable safety was United States. So, in WWII the US could impose a lot of economic restrictions on its corporations, and they just had to suck it up.

In peacetime, capital has a habit of fleeing restricted economies and finding freer ones. If you have some money to invest, and you're presented with two opportunities— both equal in every respect except that one has a government profit cap of 5%, and one has no such cap and a 10% expected return, where are you going to put your money? What holds for you holds in general. Capital will move towards profitable endeavors, even if that means overseas investment. The government will end up playing a game of whack-a-mole, plugging up holes in its price control schemes, restricting the ability for money to leave the country, etc. We've seen it in the Soviet Union. We've seen it in China. We've seen it in Turkey. We've seen it just about anywhere peacetime price controls have been implemented.

With all of that said, Galbraith is worth reading. He is thoughtful, intelligent, and witty. Everything I've read of his has given me both enjoyment and many long moments of reflection.

Communication Firehose

Fri, 06 Sep 2024 12:00:00 GMT

Communication Firehose

Without intentionality, you will find yourself at the center of a barrage of notifications. Each one clamoring for your attention. Each one giving you that dopamine hit. Each one making you feel productive. Each one distracting you from your actual work.

Busyness and productivity are rarely the same thing. (My most productive moments often happen in a hammock.) It's possible to be too busy to get anything meaningful done.

The big picture

What are the sources of interruption and distraction in your life? It's worth taking the time to reflect and write them down. Here's a helpful starting point:

SMS
Phone calls
Email
Slack
HelpScout
GitHub
Basecamp
Whatsapp
Twitter
Instagram
Facebook
Snapchat
Signal
HackerNews
Telegram
Folks walking into your office

"Wait, wait," some of you say. "You cheated there by tossing in a bunch of non-business social media platforms."

Well, you're a human being, not an AI chatbot. When you're assessing information and communication overload, you need to assess the entire picture, not just the 9-5.

If your job is to get focused, creative, deep-thinking work done, then your number one priority is to cull that long list of communication channels. If you can get it down to one or two, you win.

If you can get it to zero, you've accomplished Zen.

Potential for interruption is a productivity-killer

I've found that the potential for interruption is my real focus-killer. It's not the interruption that bothers me as much as it is the anticipation of interruption. The ever-present potential keeps my brain from sliding into that deep-focus groove. In the back of my head, there's always a little man reining me in and saying, "Woah woah! Slow down! There may be trouble around that corner!"

Every day, I set aside a place and time for uninterruptible focus.

My system

"What do I need to do next?"

I ask this question several times per day. There's a single place where I find the answer. That place is GitHub. I don't have to search across a broad range of tools to answer that question, and neither should you. Simplicity is they key to productivity.

I also don't participate in a long list of communication systems. When my GitHub notifications are clear, I'm done with communication. If something is really urgent, my teammates know to text or call me (my phone lets them through its 24/7 do-not-disturb mode).

By minimizing time spent on communication, I am able to maximize time spent delivering value. By having only one source of communication, I'm able to avoid the frictional cost of searching for information across a million different places. "Now, where did I have that conversation, again?" It's always GitHub.

Speaking from experience, that cost really adds up over time. It's well worth the effort to eliminate it. You may not be able to get yourself down to a single communication channel, but you'll benefit from being intentional about it. I've never been happier than I currently am, and my tightly-controlled communication strategy is a big part of why.

Why is deflation bad?

Fri, 30 Aug 2024 12:00:00 GMT

Why is deflation bad?

I recently argued that deflation ought to be a good thing. If everything gets less expensive over time, savers are rewarded, retirees on fixed pensions are rewarded, basic necessities become more affordable to more people. Shouldn't deflation be a boon to the poor? What's not to love? Well, plenty.

I'm reading Money by John Kenneth Galbraith. It is written with a dry wit that I find irresistible, and it's loaded with interesting tidbits. For example, Europe experienced a period of inflation after the New World was discovered. Large volumes of gold were imported, inflating the supply of supposedly "hard" money. It's a good example of monetary inflation, and also underscores a weakness in the gold standard.

Anyway, on the topic of deflation, Galbraith writes about a particular deflationary period. At the time, many farms were financed by loans. They had fixed payments similar to a mortgage, however, due to deflation, the farmers' income shrank. The price of a bushel of wheat dropped by something like 50% over the course of several years. Imagine if your boss cut your paycheck in half, but you still had to make the same mortgage or rent payments as before! That's the effect deflation has on debtors.

In a deflationary period, business are hesitant to finance expansion in part because they'll have to pay back the debt with more valuable currency. As a result, economic activity slows. As economic activity slows, business turns ever more sour, and employees must be laid off. Folks who are laid off are no longer able to afford their former way of life, so buying slows further, deepening the economic rut. Deflation can quickly lead to depression.

Our economy runs on debt. You might argue that it shouldn't, but as far as I can tell, every advanced economy that ever existed ran on debt. Unless we can invent a wholly different economic model, deflation will forever remain a real hazard.

I'll let Galbraith have the final word on the optimism with which we should greet economic innovation. "A constant in the history of money is that every remedy is reliably a source of new abuse."

Switching to Linux

Fri, 23 Aug 2024 12:00:00 GMT

Switching to Linux

In 2020, I switched to Linux. If you're considering making the switch, I recommend it. Here's my unsolicited advice.

Fedora

The Linux ecosystem presents you with a lot of choices. Distrohopping is a deep, unproductive rabbit hole. There's a distro for everyone, including some really esoteric ones. But, if you're just starting out, you'll do well to stick with a mainstream distro for a while-- some flavor of Debian or Fedora. Sticking with a major distro gives you a better chance of finding help online and better odds that the software you need is readily available.

If you have an NVIDIA graphics card, install Pop. Otherwise, I recommend Fedora because it's a good balance of up-to-date software, reasonable defaults, and an excellent out-of-the-box vanilla Gnome desktop.

Gnome

And that brings us to the desktop.

The Linux operating system is separate from the desktop experience. On Windows and OSX, the desktop and the OS are so intertwined that it's a distinction without a difference. With Linux, you have a number of desktop environments to choose from. You can also build your own by cobbling together a window manager (of which there are many) and various supporting tools.

Of all the Linux desktops, my preference is Gnome. Yours may be different, but I'd give Gnome a shot, as it's the most popular desktop, so you'll find a lot of support online around it. Gnome's UI is consistent-- fonts, padding, margins, iconography, etc-- and for me, this consistency makes a difference. In all of the other desktops I tried, there was just something off-- misalignments here, narrow padding there, inconsistencies that simply grated on my nerves.

Gnome's UI is minimal. It doesn't have a dock by default (though you can get one via extensions). It stays out of your way. For some, it takes a while to get used to. My advice is to try it for a while before you decide that it's not for you. If you can get used to it, it's a pleasant, polished experience.

Gaming

Valve has worked hard to make the Steam experience first-class on Linux. The Steam Deck is a Linux-powered handheld gaming system developed by Valve, so their commitment to Linux runs deep. Outside of Nintendo, I don't play any AAA games. My preference is for indie games, and every one I've tried has worked on Linux without a problem.

Window managers

At some point, you'll stumble across window managers. To oversimplify a bit, these are lightweight alternatives to desktop environments. They focus only on arranging windows. All of the other niceties of a desktop-- application launchers, control centers, etc-- are left up to you to install and configure as you see fit. Most window managers are tiling window managers I've never gotten the hang of them. I don't have any use for tiny, stacked windows. However, there is a window manager that I absolutely love, and that is niri.

Niri is a scrolling window manager, inspired by the PaperWM extension (which is the only Gnome extension I use). It arranges your windows on an infinite horizontal plane. You can quickly navigate forwards and backwards through your windows, hop between workspaces, etc without lifting your hands from your keyboard. I love it.

I'm writing this from Niri, running on Arch. It's a great combo for folks who don't mind spending a fair bit of time tinkering to get things set up just the way they like. You can easily install Niri on Fedora, and switch between it and Gnome without a hitch. I certainly wouldn't start with this setup, though, as it does require tinkering, and is not for beginners.

Hardware

If you're thinking of buying a new laptop, I've had great experiences with the Dell XPS lineup. Framework and system76 both have great reputations, too. My next laptop will probably be a framework. I tend to avoid Lenovo, even though it's a reputable Linux champ-- simply because I try to avoid 100% Chinese-owned electronics companies out of a (possibly misplaced) paranoia.

Have fun

Linux has come a long way since I first tried it in 2000. Back then, I mocked my Linux friends because they'd spend all of their time tinkering, configuring, and troubleshooting. I'd spend all my time building software and solving actual problems. I programmed circles around them, thanks to Windows 2000 and Visual C++ 6. Good times.

Today, Linux is a totally different beast. It works out of the box on most modern hardware. And installing software is often easier than on Windows or OSX, thanks to built-in package managers.

I've enjoyed Linux far more than I ever expected to. I made the switch when my Macbook broke down, and the repair was going to take a week. I threw Linux on an old laptop, and was off to the races. By the time my Macbook came back, I was done with OSX.

At first, I distro-hopped a lot: Fedora, Debian, Ubuntu, Pop, Arch, Void, Manjaro, Solus, and a bunch I don't even remember. I tried a bunch of WMs and DEs, and everything imaginable. It was fun!

But now, I've mostly settled and am focused on being productive. For me, that means Fedora or Arch, Gnome or Niri, and Neovim for just about everything (programming and composing nearly all written communication).

Your path will be different, and that's the beautiful thing about Linux.

Bun DIY: Tailwind Lite

Fri, 16 Aug 2024 12:00:00 GMT

Bun DIY: Tailwind Lite

When I started my zero-dependency Bun application experiment, I had no plans to build a CSS processing layer. My plan was to just hand-roll my CSS like any self-respecting neanderthal. But... I'd forgotten how much I like the convenience of fire and wheels and tools and suchlike. Within a few minutes, I was already well on my way to writing a steaming pile of unmaintainable spaghetti. Thus, I decided to write Tailwind from scratch with zero dependencies.

Here's what that looks like. Take a look under the hood, and poke around if you dare.

Building Tailwind from scratch

Tailwind is huge, and I don't use all of it. I figured the 80/20 rule would give me a good shot at building something useful without spending the rest of my life doing it.

What I built supports:

The basic rules (e.g. p-2 m-8 bg-red-600)
Pseudo selectors (e.g. hover:bg-blue-600)
Responsive breakpoints (e.g. md:w-full)
Dark / light mode (e.g. dark:bg-gray-800)
CSS file @tailwind base; and @tailwind utilities slots
Extracting rules from @layer utilities
Inlining relative @import files
Efficient, incremental builds in watch-mode
Customization via configuration
Reusing rules in CSS files with the @apply directive

I won't bore you with a comprehensive list of what the library doesn't support, but there are three big missing features that I should note:

No custom rules (e.g. text-[240rem])
No themes or plugins
Only basic @apply support— no pseudo-selectors

The lack of custom rules isn't a huge deal to me, as I never use them. If I really need a custom rule, I create one in my CSS file, generally in the utilities layer.

Themes and plugins are similarly not a thing I care about. Supporting them would probably add a lot of complexity, and I don't need them for my use-case.

As for the limited implementation of @apply, it turns out that you can get 80% of the value of the components layer by writing something like this:

@layer components {
  .yourselector {
    @apply bg-red-600 text-white;
    &:hover {
      @apply bg-sky-600;
    }
    @media (min-width: 48rem) {
      @apply w-full;
    }
  }
}

That is the equivalent of this Tailwind component:

@layer components {
  .yourselector {
    @apply bg-red-600 text-white hover:bg-sky-600 md:w-full;
  }
}

The inability to reuse breakpoints via @apply is probably the biggest drawback to my simplified approach.

How it works

The atomic-css layer works roughly like this:

Build the full configuration by merging the user and default configurations
Generate a (massive) rule lookup table based on the configuration
Load the CSS (any any CSS referenced by basic @import statements)
Extract utility rules from the CSS and update the lookup table with them
Expand the @apply directives based on the lookup table rules
Scan the source directories, extracting any Tailwind-like class names
Create a set of all of the referenced rules
Convert that set to the final CSS

For example, here's a simplified subset of the rules table that we generate from the config:

const rules = {
 'text-sky-500/50': {
    css: `color: rgb(14 165 233 / 0.5);`,
    // etc...
  },
};

When we scour the source for class names, we come across this: dark:hover:text-sky-500/50.

We parse this into two parts:

{
  pseudos: ['dark', 'hover'],
  name: 'text-sky-500/50',
}

We then look up the rule by name and find our definition.

Finally, we build an output rule:

{
  selector: '.dark dark\:hover\:text-sky-500\/50:hover',
  css: `color: rgb(14 165 233 / 0.5);`,
  // etc...
}

Before we write our final CSS, we deduplicate references, combine selectors where possible, etc, and finally write a CSS file that contains only the rules we actually use in our application, in a relatively compact form.

Everything was pretty simple to implement, but I did cut some corners. The CSS parser is particularly naive. It has many flaws. For example, it treats @layer base; and @layer 'base'; as two distinct values. But for my purposes, it's fine. It should gracefully handle all of the CSS I've ever written in my career.

The result

This was a lot more work than I anticipated— more than the single weekend that I usually allocate for such projects. Much of the work was copy / pasting rules from Tailwind's excellent docs. This was tedious. Maybe I should have automated it. Take a look at the rule-gen.ts file to see what I mean by tedious.

In the end, I got a working solution up and running fairly quickly. I'm sure there are plenty of bugs and unintentionally missing features, but the proof of concept is there. And even though it's not a thorough implementation, it's enough to warrant some observations.

The code is quite fast, and I haven't bothered to optimize it. It performs a full build of my $dayjob codebase in around 175 milliseconds compared to over 2 seconds for Tailwind. Incremental builds are similarly fast. This solves a real pain-point I've had with Tailwind, and makes me wonder if it's worth turning this into a full-fledged, production-ready library.

I'm not 100% sure exactly why it's so much faster, but I have a pretty good hunch:

I've only implemented a subset of Tailwind, so I'm doing less
Tailwind is pluggable— my library is not
Tailwind ties into postcss and other tools, where my tool is standalone
Tailwind supports complex rules which prevent the lookup table approach

I suspect this last point accounts for most of the difference. Converting a class name to a CSS rule is an O(1) operation for my library. Tailwind could use this same technique for many of its rules, but not for all of them (e.g. custom value class names wouldn't work), so I'd guess that Tailwind runs a less optimal, but more extensible algorithm for matching class names to rules.

Future optimizations n' such

The lookup table is big. Colors are to blame. For every color, we generate many rules: bg, text, border, gradient stops, etc, and all of the opacity variations of those. This consumes a few megs of RAM, and takes around 30ms to generate on my dev laptop. An optimization I may consider in the future is to lazily generate the opacity variants (e.g. text-white/50) rather than eagerly generating them.

Footnote: why Tailwind?

Before I wrap up, I thought I'd explain why I like Tailwind so much.

I've worked on web applications for over 20 years, and without fail, in every project I worked on, the CSS was the worst part.

We all know that we should generally avoid globals in our programs. Any seasoned programmer works to avoid side-effects. Avoiding global, mutable state produces simpler programs, as anyone who has flirted with functional programming can attest. And yet, with CSS, we essentially have a language in which all variables are global and any change you make will probably have unanticipated side-effects.

On a long-running, large project, the CSS requires superhuman discipline and organizational thought. Find a web application that is older than 5 years, and you'll find all sorts of dead CSS that is still sitting there because folks are too afraid to touch it. This is so common that you could accurately describe legacy CSS as an append-only language.

There are only two hard things in Computer Science: cache invalidation and naming things.

— Phil Karlton

CSS requires you to invent names. A lot of names. You have to name every. Single. Thing. Naming is hard, ergo CSS is hard.

Maintainable code requires two things: the ability to fearlessly delete and refactor, and the ability to reason locally. If you hop into a simple component you should be able to read it quickly from top to bottom, understand what it does, and make the changes you want. The more files you have to jump between, the harder this task becomes. Understandability is impeded by separating concerns across CSS / JS / HTML boundaries rather than across component boundaries. The traditional approach to hand-rolling CSS ensures that you're always jumping between at least two files in order to reason about a component.

Tailwind solves all of these problems, and it solves it elegantly. With Tailwind, you get:

Fearless refactoring
Minimal side-effects
Only the rules actively used by your application end up in your CSS
Far less time spent naming things
Locality of reasoning

Tailwind is functional programming for CSS. I love it.

Why write zero-dependency software?

Mon, 12 Aug 2024 12:00:00 GMT

Why write zero-dependency software?

Over the past few weeks, I've been tinkering with building a project from scratch in Bun. Here's why I'm doing this.

There are many examples of supply chain vulnerabilities. In particular, the JavaScript / TypeScript world has a reputation for pulling in dependencies for even the most basic needs. I once had a job working on a popular open source project whose package.json was over 1,700 lines long. It installed over 13,000 dependencies. It's impossible to reason about the security of such an application.

Building things yourself won't necessarily protect you from security vulnerabilities. In fact, you may be more likely to introduce vulnerabilities by building something from scratch. It's common knowledge, for example, that you shouldn't build your own encryption library, as you're likely to get things wrong, and a hacker will happily take advantage of that. That said, in general, if you minimize your dependencies, you shrink your attack surface.

When done right, building things yourself improves long-term maintainability. You're more likely to be able to fix bugs in small, simple, focused code you write than when you're dealing with large, general, and abstract third-party libraries. This isn't always true-- as anyone who has inherited someone else's spaghetti can attest. You can make a real mess of things when you build things yourself, and your home-grown solutions will likely be poorly documented compared to a popular npm package that solves a similar problem. Discernment is required.

There's another reason to build things from scratch: it's a fun way to learn.

This isn't a zero-dependency project! It requires Bun which itself pulls in a whole nest of dependencies (Zig, SQLite, JavaScriptCore, etc). It runs on a Linux distro which is a massive web of dependencies. It requires electricity from the nearby nuclear power plant which in turn requires uranium mines. This requires a somewhat advanced civilization with the ability to coordinate and secure supply chains. No project is an island unto itself.

— Hacker News Pedants, probably

As an educational device, I'm taking an extreme, impractical, and ill-advised hard-line approach on this side project. I'm not suggesting that anyone wages a total anti-dependency war at their day job. (I mean, if you want to lose your job, it's a creative way to quit. So there's that.) What I am suggesting is that the industry generally-- and JavaScript developers in particular-- could use a nudge towards reducing dependencies.

Simple dependencies

Fri, 09 Aug 2024 12:00:00 GMT

Simple dependencies

Simplicity. We all want it, yet it eludes us. We reach for complex tools to solve simple problems, but we all know that most problems are best solved by composing simple tools. Small teams can accomplish much, if they aren't overburdened by a poorly-fitting mishmash of tools.

It's a strange twist of psychology that leads us to reach for complexity. I don't know what's behind it, but I suspect there's some comfort in knowing, "This tool can do anything!" Most of the time, though, the sales pitch, "This can do anything!", should be viewed not as a bonus, but as a warning. You don't want a tool that can do anything. You want to solve a specific problem as directly, simply, and effectively as possible. These super flexible tools are almost never ideal for anything at all.

High-friction dependencies have multiplicative complexity. Each new not-quite-fitting dependency detracts from understandability in a non-linear way. It adds friction to maintenance tasks. Often, it degrades morale. If you dread touching a part of the system because it relies on a confusing mess of spaghetti dependencies, you're in the dependency doldrums, and your project is in trouble.

I have seen projects extend for months, and sometimes fail, simply because they were being built on the wrong (often very general, off-the-shelf) foundational tooling. I've been part of shipping solutions in the wake of such projects, and my success was almost entirely due to a focus on shipping something "good enough" with as simple a foundation as possible.

An example: a team had been working for several months-- close to a year, I think-- trying to solve a customer's problem. For their stack, they had chosen Sharepoint and SQL Server Reporting Services. The project never shipped. Trivial tasks would take them weeks. With a deadline fast approaching, I was brought in to turn things around. I asked, "What problem are we trying to solve for the customer?" It turned out to be a simple data-ingesting and reporting problem. My solution? A simple database, and a single ASP.NET page. This solution turned out to be an order of magnitude faster than the proposed solution, and probably several orders of magnitude simpler. It took maybe a week in total (including testing, Q/A, some design iterations), and our customers got what they needed.

This is not an isolated example. In my 20+ years as a software engineer, I have seen many examples of this same pathology.

How do you avoid this trap? How do you know if a tool is a good fit for the job? There's no surefire way. If you dread touching anything in the vicinity of the tool, that's a tell. But, that's a retrospective tell. Ideally, we'd have some rules of thumb which help us to avoid complexity in the first place.

Have a bias for building it in-house

This is my first rule of thumb. It's pejoratively known as "Not Invented Here Syndrome". And, it can lead to nasty results. You think that off-the-shelf system was bad? Wait till you get a load of the spaghetti our team slapped together last week! Good luck maintaining that monstrosity!

I think the downsides of NIH Syndrome are well known. But the upsides are rarely discussed.

First, if you have a decent team of engineers, they're unlikely to produce a terrible mess. They'll produce a mess-- we all do-- but it shouldn't be terrible.

Second, if it's your mess, you can generally find your way around it. Maintaining your own mess is almost always easier than maintaining someone else's.

Third, with just a bit of forethought, composing simple tools into a final solution can be done in such a way that each piece is quickly understandable, and removal of any given piece is relatively trivial.

Have a bias for deletability

If you must pull in a dependency, choose one that is easy to replace. This isn't always possible. Your ORM or database layer is generally difficult to replace. If you know the dependency will be hard to replace, spend some time finding exploring its rough edges and limitations before committing to it. This is usually best done by building a throwaway prototype that is as real-world as you can make it given your time constraints.

Ask questions first, shoot second

When considering a new problem for which there may be an existing off-the-shelf solution, here are some questions I use:

How hard is it to build a simple solution, following the 80/20 rule?
How many jobs does this potential dependency perform? The fewer the better.
How easy is it to rip out if it turns out to be a poor choice?
What are the potential pitfalls?
Where is it likely to go wrong?

Anyway

I'm not trying to convince you to write everything in Assembly. Tools are good. Abstraction is necessary. But the cost of the wrong tool, the wrong abstraction, is high, and these costs tend to compound. It's worth considering and eliminating simpler solutions before reaching for the big-fancy-complected-solve-it-all tool.

Bun DIY: Sessions

Fri, 02 Aug 2024 12:00:00 GMT

Bun DIY: Sessions

Sessions allow you to store data about a visitor of your site. It is usually used to identify who is making a request, but you can store any arbitrary data in a session. Sessions aren't baked into Bun, so we'll be building out a simple cookie-based session library in this article.

Approaches

There are two general ways to implement sessions:

Store session data in an encrypted cookie
Sotre session data in a database (Redis, Postgres, SQLite, etc), and store an unguessable random identifier in a cookie

To keep this article relatively short, we're only going to focus on one strategy, and that is the encrypted cookie approach. Using an encrypted cookie doesn't require us to manage a data store, and is generally transferrable to any project.

Generating session encryption keys

Since our sessions require encryption, we'll need some encryption keys, and we'll want to store these in our config (.env) so that sessions survive application restarts. To generate session encryption keys, run:

bun lib/sessions/genkey.ts

This will print a SESSION_KEYS environment variable to the console which you can place in your application config.

Alternatively, you can generate new session keys programmatically by calling the genkey function which is exported from lib/sessions:

import { genkey } from 'lib/sessions';

const key = await genkey();

Initializing the session middleware

To attach session capabilities to our server, we'll Initialize and attach the session middleware:

import { makeSessionMiddleware } from 'lib/sessions';

const sessionMiddleware = await makeSessionMiddleware();

const requestHandler = (req: Request): Response => new Response('TODO...');

Bun.serve({ port, fetch: sessionMiddlewa(requestHandler) });

By default, the session middleware reads the encryption keys from process.env.SESSION_KEYS. If you don't wish to use the SESSION_KEYS environment variable, you can pass your own keys into the middleware. Here's an example which is the equivalent of the previous one:

const sessionMiddleware = await makeSessionMiddleware({
  keys: process.env.SESSION_KEYS!.split(','),
});

Creating and updating a session

To create (or modify) a session, use the setSession function, passing it a response and the session data. It returns a response which has the session cookie set.

import { setSession } from 'lib/sessions';

function hello(req: SessionRequest<any>): Response {
  const response = new Response(`Hello, ${req.session.username}!`);
  return setSession(response, { username: 'Jimbo' });
}

A more realistic example might be a typical login response:

function loginRedirect(userId: string): Response {
  const response = new Response('', {
    status: 303,
    headers: {
      Location: '/',
    },
  });
  return setSession(response, { userId });
}

Reading session state

When a request has an active session, the session state can be accessed using the request.session property, as in this example request handler:

function hello(req: SessionRequest<any>): Response {
  return new Response(`Hello, ${req.session.username}!`);
}

Revoking a session / logging out

If you want to end a session (log out), call revokeSession like so:

import { revokeSession } from 'lib/sessions';

function logout(req: Request): Response {
  return revokeSession(
    new Response('', {
      status: 303,
      headers: {
        Location: '/login',
      },
    }),
  );
}

Key rotation

For security purposes, it makes sense to change your application's encryption key on a regular basis. If we only support one encryption key, changing that key would break all existing sessions, effectively logging out all users of your application. Since we presumably don't hate our users, we'll support up to N older encryption keys. N should be a small number, like 2-3. When we receive a request, we'll try to find the encryption key that was used to create the session cookie, and we'll re-encrypt the session with the latest key.

If the cookie is so old that its key has fallen off of our list, the user's session will fail to decrypt. In this scenario, we don't throw an exception. Instead, we write the error to the console, and treat the request as if it is unauthenticated (a logged out / undefined session).

Security implications

When we set the session cookie, we restrict it in a number of ways in order to avoid common security pitfalls.

First, we prefix our cookie name with __Host- which ensures our cookie is domain-locked. (Our full cookie name is __Host-session.)

Then, we give the cookie the following attributes.

Secure ensures that the cookie is not transmitted in plain text (it's only sent over https except on localhost)
HttpOnly prevents client-side scripts from accessing the cookie
SameSite=Strict prevents the browser from sending the cookie to other domains (mitigating some cross-site vulnerabilities)

The full cookie looks like this:

Set-Cookie: __Host-session={ENCRYPTED_VALUE}; SameSite=Strict; Secure; HttpOnly

For more details on cookies and security, see the MDN documentation.

Implementation details

Our session cookies are encrypted using AES-GCM-256. Our keys are represented as base64url encoded strings with some prefixes which allow us to support upgrading our encryption to a different algoirthm and key length.

Our key format is as follows:

{algorithm}:{key_length}:{base64url_encoded_key}

Here's an example key:

AES-GCM:256:avKuo13qK3JgbOJdAyeMkeZBRUOsR4AIj-qKWnlq-RI

It has a number of parts:

AES-GCM: the algorithm used to generate the key
256: the length used to generate the key
ww8fa... the key itself, encoded as a base64url string

Our session cookies will be of the form:

{iv}:{encrypted_state}

Here's an example session cookie:

S99Z8e_kYnv2tosXDyfQz:7oo-s0K66-A446xttFfoA6nXDskiQVUFNURowRgcsoM

Which breaks down like so:

S99...: the iv used during encryption
7oo... the encrypted session state

Missing features: session expiration, revocation, etc

This implementation is missing a number of features that you might consider table-stakes. You should be able to layer such features on top. For example, this implementation does not have a way to revoke all sessions for a specific user, but it can be built fairly easily by:

Adding created_at to the session state when you create a new session
Storing a sessions_revoked_at value in your database for each user
Creating a middleware that fetches the current user associated with the session
Nullifying any sessions whose created_at < sessions_revoked_at

Another feature we're lacking is automatic session expiration. Most of my users prefer to stay logged in to my apps until they manually opt to logout, so I'm fine with no expiration. It does potentially pose a security risk for very secure applications, however. If your application needs session expiration, it's pretty easy to layer on using the time stamp approach suggested above. You might also use standard cookie expiration.

Most other session features that I've ever needed can be similarly layered on top of our simple implementation, so I'll leave such exercises up to the reader.

Source

The source is below. For reference, the lib/middleware file looks like this:

import type { Server } from 'bun';

// The Bun Serve.fetch handler singnature
export type HTTPHandler = (request: Request, server: Server) => Response | Promise<Response>;

// The type signature of a middleware function
export type Middleware = (next: HTTPHandler) => HTTPHandler;

I wanted to write some tests for some of the internal functions in my session implementation, so I stored the bulk of the logic in lib/sessions/seessions.ts and wrote my tests against that. I then created an export of the public API in lib/sessions/index.ts which is detailed at the end of this article.

/**
 * This implements an encryption-based session cookie. We use AES-GCM-256
 * which is secure enough for our needs while still being fairly performant.
 *
 * This runs around 10K encrypt / decrypt operations in 350ms on my old
 * laptop, unplugged (low power mode). That's good enough.
 */

import type { Middleware } from 'lib/middleware';

/**
 * This is the type signature of a request that may have a session associated with it.
 */
export type SessionRequest<T> = Request & { session?: T };

/**
 * The type signature of a response that may have a session associated with it.
 */
export type SessionResponse<T> = Response & { session?: T };

/**
 * The arguments used to create the session middleware.
 */
type MiddlewareArgs = {
  keys?: string[];
};

/**
 * The start of the session cookie value.
 */
const sessionCookiePrefix = '__Host-session=';

/**
 * If response.session === revokeSymbol, it means the session should be cleared.
 */
const revokeSymbol = Symbol();

/**
 * The webcrypto object, pulled into a const for convenience.
 * See: https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API
 */
const crypto = globalThis.crypto;

/**
 * The algorithm we'll use to encrypt / decrypt session cookies.
 */
const algo = { name: 'AES-GCM', length: 256 };

/**
 * Convert an item to a base64url-encoded string.
 */
const toBase64Url = (arr: any) => Buffer.from(arr).toString('base64url');

/**
 * Converters for converting strings to / from Uint8Array.
 */
const textEncoder = new TextEncoder();
const textDecoder = new TextDecoder();

/**
 * Extract the session cookie from a request. Return undefined if
 * no session cookie is found. This returns the *encrypted* session
 * cookie. Exported for testing purposes.
 */
export function extractSessionCookie(req: { headers: Headers }) {
  const cookie = req.headers.get('cookie');
  if (!cookie) {
    return;
  }
  const extractSession = (start: number) => {
    const semi = cookie.indexOf(';', start);
    return cookie.slice(start, semi < 0 ? cookie.length : semi);
  };
  let prefix = sessionCookiePrefix;
  if (cookie.startsWith(prefix)) {
    return extractSession(prefix.length);
  }
  prefix = `; ${prefix}`;
  const index = cookie.indexOf(prefix);
  return index < 0 ? undefined : extractSession(index + prefix.length);
}

/**
 * Parse the serialized encryption keys into CryptoKey instances.
 */
async function parseKeys(keys?: string[]): Promise<CryptoKey[]> {
  if (!keys?.length) {
    console.error(
      [
        `No encryption keys were provided to session middleware.`,
        `To generate encryption keys, run:`,
        `bun lib/sessions/genkey.ts`,
      ].join('\n'),
    );
    throw new Error(`session middleware keys not provided`);
  }
  return Promise.all(
    keys.map(async (serializedKey) => {
      const [algoName, algoLength, key64] = serializedKey.split(':');
      return await crypto.subtle.importKey(
        'raw',
        Buffer.from(key64, 'base64url'),
        {
          name: algoName,
          length: parseInt(algoLength, 10),
        },
        true,
        ['encrypt', 'decrypt'],
      );
    }),
  );
}

/**
 * Encrypt the payload, returning "iv:ciphertext" where iv is the base64url
 * encoded iv value, and ciphertext is the base64url-encoded encrypted payload.
 */
async function encrypt(key: CryptoKey, data: string) {
  const iv = crypto.getRandomValues(new Uint8Array(16));
  const ciphertext: ArrayBuffer = await crypto.subtle.encrypt(
    { name: algo.name, iv },
    key,
    textEncoder.encode(data),
  );
  return `${toBase64Url(iv)}:${toBase64Url(ciphertext)}`;
}

/**
 * Decrypt data, which is expected to be of the form "iv:ciphertext" as
 * produced by the encrypt function.
 */
async function decrypt(key: CryptoKey, iv64: string, data64: string) {
  const plaintext = await crypto.subtle.decrypt(
    {
      name: algo.name,
      iv: Buffer.from(iv64, 'base64url'),
    },
    key,
    Buffer.from(data64, 'base64url'),
  );
  return textDecoder.decode(plaintext);
}

/**
 * Attempt to decrypt and parse the sesion cookie. If succesful, req.session
 * will be set to the parsed session state. This doesn't throw on error, but
 * it does log. The reason we avoid throwing is because we're going to get
 * errors during key rotation.
 */
async function parseSession(keys: CryptoKey[], req: SessionRequest<unknown>) {
  const encryptedSession = extractSessionCookie(req);
  if (!encryptedSession) {
    return;
  }
  const [iv64, data64] = encryptedSession.split(':', 4);
  for (const key of keys) {
    try {
      req.session = JSON.parse(await decrypt(key, iv64, data64));
      return key;
    } catch (err: any) {
      console.error(`[session] failed to decrypt or parse`, err.message);
    }
  }
}

/**
 * Write the specified value to the session cookie.
 */
async function writeSessionCookie(res: Response, value: string) {
  res.headers.append(
    'Set-Cookie',
    `${sessionCookiePrefix}${value}; SameSite=Strict; Secure; HttpOnly`,
  );
  return res;
}

/**
 * Generate a key which can be used for encrypting / decrypting session
 * cookies. This should be stored in .env or your application config.
 */
export async function genkey() {
  const key = await crypto.subtle.generateKey(algo, true, ['encrypt', 'decrypt']);
  const exported = await crypto.subtle.exportKey('raw', key);
  const key64 = toBase64Url(exported);
  return `${algo.name}:${algo.length}:${key64}`;
}

/**
 * Terminate the session, clearing the session cookie.
 */
export function revokeSession(res: Response) {
  return setSession(res, revokeSymbol);
}

/**
 * Create or modify the current session.
 */
export function setSession<T>(res: Response, data: T): SessionResponse<T> {
  const response = res as SessionResponse<T>;
  response.session = data;
  return response;
}

/**
 * Create a middleware function which attaches session state to incoming
 * requests, and sets / removes the session cookie from outgoing responses.
 */
export async function makeSessionMiddleware(args?: MiddlewareArgs): Promise<Middleware> {
  const keys = await parseKeys(args?.keys || process.env.SESSION_KEYS?.split(','));
  const [key] = keys;
  return (next) => async (req, server) => {
    const sessionRequest = req as SessionRequest<unknown>;
    const sessionKey = await parseSession(keys, sessionRequest);
    const res = (await next(sessionRequest, server)) as SessionResponse<unknown>;

    // The session has been revoked; remove the cookie.
    if (res.session === revokeSymbol) {
      return writeSessionCookie(res, '; Expires=0');
    }

    // If data is truthy, we've got a new session value (res.session), or we've
    // done a key rotation (sessionKey !== key) so we need to re-write the session.
    const data = res.session || (sessionKey !== key && sessionRequest.session);
    if (data) {
      return writeSessionCookie(res, await encrypt(key, JSON.stringify(data)));
    }
    return res;
  };
}

Public API

Here's the public API, exported from lib/sessions/index.ts:

export {
  type SessionRequest,
  type SessionResponse,
  genkey,
  revokeSession,
  setSession,
  makeSessionMiddleware,
} from './sessions';

Genkey

And lastly, here's lib/sessions/genkey.ts which can be used to generate new session keys from the command line:

/**
 * A script which generates a new session key and prints out the
 * SESSION_KEYS environment variable with the new key prefixed.
 *
 * bun lib/sessions/genkey.ts
 */

import { genkey } from './sessions';

// We'll only keep the previous 2 keys around. If you wish to keep
// more around for some reason, you can manually add them back to
// your config.
const keys = (process.env.SESSION_KEYS || '')
  .split(',')
  .filter((s) => s)
  .slice(0, 2);

console.log();
console.log('Save the follwing in your .env or your application config:');
console.log();
console.log(`SESSION_KEYS=${[await genkey(), ...keys].join(',')}`);
console.log();

Conclusion

And that's it; a basic session implementation with no dependencies outside of Bun itself. If you're interested in more Bun DIY articles, subscribe to the rss feed to get notified when I post new ones.

Bun DIY: Serving Static Assets

Fri, 26 Jul 2024 12:00:00 GMT

Bun DIY: Serving Static Assets

Today, we'll be building a small, zero-dependency HTTP handler for serving static assets using Bun. Serving static assets from Bun is pretty simple, but there are some things to consider:

Properly handling missing files
Protecting against path-exploits (e.g. requests like /assets/../.env should fail)
Using ETags to avoid unnecessary bandwidth consumption

Usage

Call makeStaticAssetHandler, and pass it the name of the folder whose contents you wish to serve. This returns an HTTP handler (req: Request) => Promise<Response> which can be used by Bun.serve or by a router, as in the following example:

route.add('get/assets/*path', makeStaticAssetHandler('assets'));

Handling missing files

When we get a request for a non-existent path, we want to return a 404. Checking if a file exists is trivial in bun:

const file = Bun.file(fullPath);
if (!(await file.exists())) {
  return new Response('File not found', { status: 404 });
}

Avoiding path exploits

Malicious users might try to request files that are outside of our static asset folders. For example, they might try to read our .env file by requesting: /assets/../.env. To mitigate against such requests, we'll use path.normalize. This function resolves all . and .. segments. Once that's done, we can check if the resulting path starts with the static asset folder prefix. If not, we'll return an HTTP 403 (Forbidden).

ETags

ETags allow clients to check if an asset has changed since it was last requested and only download it if so. It allows us to have the benefits of caching without resorting to old cache-busting hacks.

We'll use Bun's built-in sha256 hash support to compute ETags for any assets we serve. We'll toss the result into an in-memory cache to avoid re-computing the hash. Since our project will have a relatively small number of static assets, we won't bother with cache-eviction or anything like that. If you are building an application that will have a large or unknown number of static assets, then you should look into a different caching strategy. For example, you might pre-compute the etags and store them on disk alongside the assets (e.g. foo.png might have a foo.png.etag file), or you might use a LRU cache.

Source

Here's the source:

/**
 * This file contains logic for serving static assets out
 * of a folder. It is meant to be used in conjunction with
 * a router, rather than as traditional middleware.
 */
import path from 'node:path';

/**
 * Given a file, compoute its sha256 hash.
 */
async function computeFileSha256(filename: string) {
  const hasher = new Bun.CryptoHasher('sha256');
  const file = Bun.file(filename);
  const stream: any = file.stream();
  for await (const chunk of stream) {
    hasher.update(chunk);
  }
  return hasher.digest('base64');
}

/**
 * A memoized function which computes the sha256 hash of a file.
 * In dev-mode, we'll recompute the hash on each request. In
 * production, we'll cache it.
 */
const getEtag = (() => {
  if (process.env.NODE_ENV === 'development') {
    return computeFileSha256;
  }
  const cache: Record<string, string> = {};
  return async (filename: string) => {
    let hash = cache[filename];
    if (!hash) {
      hash = await computeFileSha256(filename);
      cache[filename] = hash;
    }
    return hash;
  };
})();

/**
 * Create a route-handler for serving static assets from a specific
 * folder. The route should define a "path" parameter, or the endpoint
 * will not work.
 *
 * Usage:
 *
 *   route.add('get/assets/*path', makeStaticAssetHandler('dist/img'));
 *   route.add('get/css/*path', makeStaticAssetHandler('dist/css'));
 */
export function makeStaticAssetHandler(folderPath: string) {
  return async (req: Request & { params: Record<string, string> }) => {
    // Compute the full path, normalizing out any .. and . segments
    const fullPath = path.normalize(path.join(folderPath, req.params.path));
    // We've got an invalid request, possibly someone malicious hunting for files
    if (!fullPath.startsWith(folderPath)) {
      return new Response('Invalid asset path', { status: 403 });
    }
    // Handle the 404 edge-case
    const file = Bun.file(fullPath);
    if (!(await file.exists())) {
      return new Response('File not found', { status: 404 });
    }
    // Compute the etag and send a 304 if the client already has the latest
    const etag = await getEtag(fullPath);
    if (etag === req.headers.get('If-None-Match')) {
      return new Response(null, { status: 304 });
    }
    return new Response(file, { headers: { ETag: etag } });
  };
}

My Full-Time Job Is Reading Hacker News

Fri, 19 Jul 2024 12:00:00 GMT

My Full-Time Job Is Reading Hacker News

Apple tells me I average 2.5 hours per day on my phone. If a full time job is 40 hours per week, I'll spend the equivalent of over 4 years per decade in the full-time job of pissing time away on my phone. Ah, the good life!

2.5 hours per day amounts to:

17 hours per week
38 days per year
22 work-weeks (of 40 hours) per year
9125 hours per decade.
380 days per decade
228 work-weeks per decade
4.3 work-years per decade

The little things add up, don't they?

National average

These stats are encouraging, putting my measly 2.5 hours to shame.

Among users aged 8-12 in the US, average entertainment screen time amounted to 5 hours 33 minutes [per day] in 2021.

That's 50 work weeks per year-- a full time job. Everything is fine, here. I'm sure this won't deepen the mental health crisis.

What worked

This got me thinking. Why do I reach for my phone? Maybe 25% of the time, it's for reasonable things-- reading a recipe, talking to a hooman, etc. 75% of the time, it's to escape the mundane. It's that 75% figure that I want to reduce.

Leaving my phone

By far the best thing I did was to leave my phone behind. When it's not in the same room with me, I become acutely aware of my impulses. I find myself reaching for the phantom phone. This produces a jarring "Oh yeah." moment which I use as a trigger to do something better:

Deep breathing
Jotting down thoughts on a notepad
Picking up a book

Books, pen, and paper

I found a few books that I've been meaning to read through, and put them in strategic locations: my nightstand where it replaces my nighttime news reading habit, the bathroom, ya know, and my office. For the same reason, I also added a pen and nice notepad to a few rooms (office, kitchen, nightstand). This has been marginally helpful in reducing screen-time, but has been quite nice in increasing my reading and writing throughput.

Detox weeks

My wife and I did a digital detox week. For that week, our phones become old-school house-phones. They are relegated to a specific spot, and we only check them the way we would have checked an old recording machine back in prehistoric times. This week was excellent. We've decided to do one a month.

Time-boxing Hacker News

Most of my idle phone time is spent reading Hacker News or the rabbit trails I find there. I love Hacker News. The conversations are high quality. The articles are interesting. It's the best place on the web, and that makes it dangerous if you want to reduce your screen time.

I gave myself a Hacker News time budget. One hour per week, on Saturday. I go to Algolia and scan the top stories for the week, build up a reading list of anything that seems worth deeper time, and quit.

On weeks where I do this, my screen-time goes down significantly.

What didn't work

I tried a few things that didn't work, either.

Grayscale

I converted my phone to grayscale. There's some evidence that it curbs phone addiction. It backfired for me. The web is a garish place, and grayscale gives it a minimal, pleasant uniformity.

Do not disturb

I keep my phone in do-not-disturb mode, with emergency pass through for work and other important contacts. Life is much more pleasant in do-not-disturb mode. But, it turns out, communication isn't the thing that draws me to my phone, so this had no impact on my numbers.

Results and takeaways

Writing this article triggered the frequency illusion. I've become much more conscious of flipping my phone out to escape the present moment. As a result, I've gotten a heck of a lot more done since my first draft.

My personal reform is too nascent for me dispense sage, condescending advice, but I can say that you should run the math on your own phone usage. The results may surprise you and just might be the kick in the pants you needed to get off your ass.

Bun: Zero-Dependency Server-Side JSX

Fri, 12 Jul 2024 12:00:00 GMT

Bun: Zero-Dependency Server-Side JSX

I'm building a little, zero-dependency application with Bun. Bun comes with JSX support out of the box, but it took a bit of digging to get things working with no dependencies.

I figured I'd explain the process.

tsconfig

First, we need to tell Bun / TypeScript where our JSX rendering logic lives. We'll put everything in lib/jsx:

Add the following compilerOptions to tsconfig.json:

"jsx": "react-jsx",
"jsxImportSource": "lib/jsx",

And modify your paths to have an entry like this:

"lib/*": ["./lib/*"]

So, with unrelated stuff omitted, your tsconfig.json should be a superset of this:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "lib/jsx",
    "baseUrl": ".",
    "paths": {
      "lib/*": ["./lib/*"]
    }
  }
}

lib/jsx

We'll put all of our logic into lib/jsx/index.ts, so go ahead and create that.

Bun and other transpilers expect a few other files which we'll need to create:

lib/jsx/jsx-runtime.ts
lib/jsx/jsx-dev-runtime.ts

And they both look like this:

export * from './index';

Now, let's write index.ts:

The bulk of the logic will be in our h function:

export function h(args) {
  console.log(args);
  return 'TODO...';
}

export const jsxDEV = h;
export const jsx = h;

You can test that by creating test.tsx:

console.log(<h1>It is now {new Date().toISOString()}</h1>);

If you run that using bun test.tsx, you'll see the shape of the args passed to the h function.

Escaping user input

Before we jump into the code, there's something worth noting. Bun comes with a handy escapeHTML function which I use in my JSX rendering logic. If you want to use any templates from the client, you'll want to use your own escape logic. It might look something like this:

const chars: Record<string, string> = {
  [`"`]: '&quot;',
  [`&`]: '&amp;',
  [`'`]: '&#x27;',
  [`<`]: '&lt;',
  [`>`]: '&gt;',
};

const htmlEscapeRegex = /["&'<>]/g;

function esc(s: string) {
  return s.replaceAll(htmlEscapeRegex, (ch) => chars[ch]);
}

Source

Here's a look at the final implementation:

// Bun / other transpilers expect these to be defined if jsx mode is
// react-jsx and jsxImportSource is used.
export const jsxDEV = h;
export const jsx = h;

// We'll use this to identify when a child is the result of a nested JSX
// expression. In that case, we don't want to escape the resulting HTML.
const $jsx = Symbol();

// This is what we'll return from our h function. It allows us to get access
// to the raw HTML. The $jsx property helps us identify JSX output when
// dealing with nested components.
export type JSXResult = {
  $jsx: Symbol;
  value: string;
};

// These are self-closing tags such as <img /> <br />, and need special
// treatment so that we avoid generating something invalid like <img></img>.
const voidElementNames = new Set([
  'area',
  'base',
  'br',
  'col',
  'embed',
  'hr',
  'img',
  'input',
  'link',
  'meta',
  'source',
  'track',
  'wbr',
]);

// Determine if arg is a potentially dangerous href value.
function isPotentiallyDangerousURL(arg: string) {
  return (
    // If the href contains a : (58 is the unicode value for :)
    (arg.includes(':') || arg.includes('&#58;')) &&
    // And it doesn't start with http:// or https://
    !fullyQualifiedURLRegex.test(arg)
  );
}

// Determine if a value is a JSXResult
function isJSXResult(o: any): o is JSXResult {
  return o?.$jsx === $jsx;
}

// Convert a child / children to HTML. We may get various shapes of
// data as children: strings / literal values / arrays / nested
// JSX values, etc.
function stringifyChild(child: any): string {
  if (Array.isArray(child)) {
    return child.map(stringifyChild).join('');
  }
  if (typeof child === 'string') {
    return Bun.escapeHTML(child);
  }
  if (isJSXResult(child)) {
    return child.value;
  }
  if (child != null && child !== false) {
    return Bun.escapeHTML(`${child}`);
  }
  return '';
}

// Convert an object to HTML attributes. We'll handle functions specially
// so that we can write simple event handlers on the server, and have the
// code execute on the client.
function stringifyAttrs(attrs: Record<string, any>) {
  let result = '';
  for (const k in attrs) {
    let value = attrs[k];

    // We want to specifically handle boolean attributes and treat them
    // as an add / remove operation. For example:
    //
    // <input checked={true} />  -> <input checked />
    // <input checked={false} /> -> <input />
    if (typeof value === 'boolean') {
      value && (result += ` ${k}`);
      continue;
    }

    // Convert functions to strings, presumably as an event-handler.
    // This would take something like this:
    //
    //   onClick={(e) => { document.title = e.target.textContent; }}>
    //
    // And convert it to this:
    //
    //   onClick="((e) => { document.title = e.target.textContent; })(event)"
    if (typeof value === 'function' && k.startsWith('on')) {
      value = `(${value})(event)`;
    }

    // It can be handy to embed view HTML as an attribute (e.g. so that client
    // scripts can then make use of conditional HTML). This allows us to do
    // something like this:
    //
    // data-moon-icon={<svg>...</svg>}
    if (isJSXResult(value)) {
      value = value.value;
    }
    // We want to disallow dangerous href values like javascript:alert("hi").
    if (typeof value === 'string' && k === 'href' && isPotentiallyDangerousURL(value)) {
      // We have a potentially dangerous href value, so we'll
      // make it blank.
      value = '';
    }
    result += ` ${k}="${Bun.escapeHTML(value)}"`;
  }
  return result;
}

// Fragments are how React and friends represent JSX results that contain
// multiple leafs without having a wrapper element.
export function Fragment(...args: Array<{ children: any[] }>) {
  return { $jsx, value: args.flatMap((arg) => stringifyChild(arg.children)).join('') };
}

// The first argument is either a tagName or a function. That is, it is either
// something like "div" or "h1", or it is a function which is itself a JSX
// component such as:
//
// const Hello(props) => <h1>Hello {props.name}</h1>
export function h(tagOrFn: string | ((props: any) => any), props: any): JSXResult {
  // We have a function component
  if (typeof tagOrFn === 'function') {
    const result = tagOrFn(props);
    // If a functioni component returns anything other than a JSXResult,
    // we don't want its output to show up in our final result.
    return isJSXResult(result) ? result : { $jsx, value: '' };
  }

  // We're dealing with a tagName like "h1", etc
  const { children, dangerouslySetInnerHTML, ...attrs } = props;
  const content = dangerouslySetInnerHTML
    ? dangerouslySetInnerHTML.__html
    : stringifyChild(children);

  // We have a self-closing tag
  if (voidElementNames.has(tagOrFn)) {
    return { $jsx, value: `<${tagOrFn}${stringifyAttrs(attrs)} />` };
  }
  return { $jsx, value: `<${tagOrFn}${stringifyAttrs(attrs)}>${content}</${tagOrFn}>` };
}

// This helper lets us change the shape of JSXResult without breaking
// callers.
export function renderToString(result: JSXResult) {
  return result.value;
}

Bun: DIY Live Reload

Thu, 04 Jul 2024 12:00:00 GMT

Bun: DIY Live Reload

Live reload lets you see changes instantly in your browser whenever you save any files. It's a must-have if you want to iterate quickly on any browser content. Live reload isn't baked into Bun, but it's fairly easy to wire up.

Here's an example of what we'll be building:

// Watch the css and dist directories, and refresh all browsers when
// any changes are detected. Browsers will also refresh when the server
// restarts.
const liveReload = makeLiveReloadMiddleware({ watchdirs: ['css', 'dist'] });

// Wrap our request handler in the middleware.
const requestHandler = liveReload(async (req) => {
  return new Response(someHTML, {
    headers: {
      'Content-Type': 'text/html',
    },
  });
});

// Create the server
Bun.serve({ port, fetch: requestHandler });

How it works

Middleware injects a script into all HTML payloads
The script long-polls the server
When the long-poll ends, the script reconnects, then hard-refreshes

The hackiest part is the way we inject the script into our responses. We detect any HTML responses, read their payload, and replace </head> with <script>...</script></head>. Definitely hacky, and if you have any massive, streaming HTML endpoints (e.g. that dumps a huge table out, or whatever), you may want to either optimize this implementation, or add the ability to ignore certain problematic endpoints.

Source

/**
 * This middleware provides live-reload functionality in dev-environments.
 * It intercepts any client requests made to a unique URL (endpointPath),
 * holding those connections open until a file change is detected.
 *
 * When we detect a file change, we'll respond to all connected clients,
 * sending them into refresh mode. They also go into refresh mode when
 * bun restarts (e.g. if running bun --watch, and making a change to a server
 * file).
 *
 * The hackiest part of this is the way we inject our live-reload script
 * into the head of all HTML responses.
 */

import type { Server } from 'bun';
import path from 'node:path';
import { watch } from 'fs';

// The Bun Serve.fetch handler singnature
type HTTPHandler = (request: Request, server: Server) => Response | Promise<Response>;

// The type signature of a middleware function
type Middleware = (next: HTTPHandler) => HTTPHandler;

/**
 * If running in dev-mode, watch the watchdirs folders for changes, and notify clients.
 */
export function makeLiveReloadMiddleware(opts: { watchdirs: string[] }): Middleware {
  // In non-dev environments, this middleware is a noop
  if (process.env.NODE_ENV !== 'development') {
    return (next) => next;
  }

  // An async function which will notify long-poll request handlers of file changes
  const waitForFileChange = makeFileWaiter(opts.watchdirs);

  // The endpoint for long-poll requests
  const endpointPath = '/livereload-0e4e2dfb-646b-4608-9943-ad3cad795856';

  // The script we'll inject to perform the long-poll from the browser
  const liveReloadScript = `<script>(${clientScript.toString()}("${endpointPath}"));</script>`;

  console.log(`[livereload] watching ${opts.watchdirs} for changes`);

  return function liveReloadMiddleware(next) {
    return async (req, server) => {
      // If our long-poll endpoint is being requested, we'll wait for a file
      // change, then we'll notify the client.
      if (req.url.endsWith(endpointPath)) {
        return new Response(await waitForFileChange(), {
          headers: { 'Content-Type': 'text/plain' },
        });
      }

// If it's not an HTML response, we'll just pass it along
const result = await next(req, server);
if (!result.headers.get('Content-Type')?.startsWith('text/html')) {
return result;
}

// We have an HTML response, so we'll inject our live reload script
const body = await result.text();
return new Response(body.replace('</head>', ${liveReloadScript}</head>), {
headers: result.headers,
});
};

  };
}

/**
 * This is the client-side function. We'll stringify this and inject
 * it into any HTML payload that has a `</head>` tag.
 */
async function clientScript(endpointPath: string) {
  // Detect when the user is navigating away, in which case we don't
  // want to interfere by refreshing.
  let navigating = false;
  window.addEventListener('beforeunload', () => {
    navigating = true;
  });

  // Show a little "Reconnecting..." message when we've lost
  // the server connection.
  function showStatus() {
    const el = document.createElement('div');
    el.innerHTML = `
      <div style="position: fixed; top: 0; left: 0; z-index: 10000; background: #800; padding: 2px 4px; text: white">
        Reconnecting...
      </div>
    `;
    document.body.append(el);
  }

  // Re-attempt the connection in a loop after which, refresh
  async function reconnect() {
    if (navigating) {
      return;
    }
    showStatus();
    let backoff = 10;
    for (let i = 0; i < 1000; ++i) {
      try {
        await fetch('/');
        break;
      } catch {
        await new Promise((r) => setTimeout(r, backoff));
        backoff = Math.min(backoff * 1.05, 500);
      }
    }
    !navigating && location.reload();
  }

  // Hit the middlware endpoint and wait for either a response or
  // a disconnect, sending us into the reconnect / refresh phase.
  fetch(endpointPath)
    .then((x) => x.text())
    .then(reconnect, reconnect);
}

// Make a function which can be used to wait for file changes in any
// of the specified directories.
function makeFileWaiter(watchdirs: string[]) {
  let reloadResolve: (s: string) => void;
  let reloadPromise: Promise<string>;

  const resetPromise = () => {
    reloadPromise = new Promise((resolve) => {
      reloadResolve = resolve;
    });
  };
  resetPromise();

  watchdirs.forEach((dir) => {
    watch(path.join(process.cwd(), dir), { recursive: true }, (_event, filename) => {
      const resolve = reloadResolve;
      resetPromise();
      resolve(filename || 'filechange');
    });
  });

  return () => reloadPromise;
}

Running A Bun Service On A Cheap VPS

Thu, 04 Jul 2024 12:00:00 GMT

Running A Bun Service On A Cheap VPS

Today, I spun up a Bun service on a Hetzner VPS. It was pretty straightforward, but I thought I'd share my notes.

Config

Spinning up a new VPS on Hetzner was simple. I took Hetzner's example config and tweaked it to include automatic updates:

#cloud-config
users:
  - name: {YOUR_USER_NAME}
    groups: users, admin
    sudo: ALL=(ALL) NOPASSWD:ALL
    shell: /bin/bash
    ssh_authorized_keys:
      - {YOUR_PUBLIC_SSH_KEY}
packages:
  - fail2ban
  - ufw
  - unattended-upgrades
  - apt-listchanges
package_update: true
package_upgrade: true
runcmd:
  - printf "[sshd]\nenabled = true\nbanaction = iptables-multiport" > /etc/fail2ban/jail.local
  - systemctl enable fail2ban
  - ufw allow ssh
  - ufw allow http
  - ufw allow https
  - ufw enable
  - sed -i -e '/^\(#\|\)PermitRootLogin/s/^.*$/PermitRootLogin no/' /etc/ssh/sshd_config
  - sed -i -e '/^\(#\|\)PasswordAuthentication/s/^.*$/PasswordAuthentication no/' /etc/ssh/sshd_config
  - sed -i -e '/^\(#\|\)KbdInteractiveAuthentication/s/^.*$/KbdInteractiveAuthentication no/' /etc/ssh/sshd_config
  - sed -i -e '/^\(#\|\)ChallengeResponseAuthentication/s/^.*$/ChallengeResponseAuthentication no/' /etc/ssh/sshd_config
  - sed -i -e '/^\(#\|\)MaxAuthTries/s/^.*$/MaxAuthTries 2/' /etc/ssh/sshd_config
  - sed -i -e '/^\(#\|\)AllowTcpForwarding/s/^.*$/AllowTcpForwarding no/' /etc/ssh/sshd_config
  - sed -i -e '/^\(#\|\)X11Forwarding/s/^.*$/X11Forwarding no/' /etc/ssh/sshd_config
  - sed -i -e '/^\(#\|\)AllowAgentForwarding/s/^.*$/AllowAgentForwarding no/' /etc/ssh/sshd_config
  - sed -i -e '/^\(#\|\)AuthorizedKeysFile/s/^.*$/AuthorizedKeysFile .ssh\/authorized_keys/' /etc/ssh/sshd_config
  - sed -i '$a AllowUsers {YOUR_USER_NAME}' /etc/ssh/sshd_config
  - systemctl enable unattended-upgrades
  - reboot

Verifying the SSH signature

My VPS was ready in a few seconds. (It was ready so fast, I thought maybe something hadn't worked.) When I first SSHed into the box, I was given a message like this:

The authenticity of host '...' can't be established.
ED25519 key fingerprint is SHA256:....

To verify the key, I ran:

ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

Installing Caddy

Once in, it was time to install Caddy:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

I hit https://{IP_ADDRESS} and saw a default Caddy page. Nice! It told me to do the following:

Point your domain's A/AAAA DNS records at this machine.
Upload your site's files to /var/www/html.
Edit your Caddyfile at /etc/caddy/Caddyfile:
    Replace :80 with your domain name
    Change the site root to /var/www/html
Reload the configuration: systemctl reload caddy
Visit your site!

I love the way Caddy presented that. This is the way dev-tooling should be. Anyway, I'm ignoring all of that advice, since I'm going to instead proxy a Bun service.

Hello, Bun!

I pointed a test domain at my IP address, installed Bun, then created a little hello-world script:

// /home/{YOUR_USER_NAME}/hello-world/hi.ts
const port = 3000;

Bun.serve({
  fetch(req) {
    return new Response("Hello, world!");
  },
});

console.log('Listening on', port);

Next, I ran my server manually:

bun hi.ts

And, I modified /etc/caddy/Caddyfile to look like this:

{DOMAIN_NAME} {
  reverse_proxy :3000
}

Hey, presto! Everything worked. I can now see Hello, world! over HTTPS from any browser on the planet. Neato.

Systemd

I want my Bun service to run automatically when the server restarts, or after a crash. To do that, I created a systemd service like so:

# /etc/systemd/system/hello-world.service
[Unit]
Description=Hello world web service
After=network.target

[Service]
Type=simple
User={YOUR_USER_NAME}
WorkingDirectory=/home/{YOUR_USER_NAME}/hello-world
ExecStart=/home/{YOUR_USER_NAME}/.bun/bin/bun run hi.ts
Restart=always

[Install]
WantedBy=multi-user.target

I enabled and started it:

sudo systemctl enable hello-world
sudo systemctl start hello-world

Checking the status of everything

Lastly, I created a cheatsheet of the stuff I might want to hop in and check later:

# Review statuses, logs, etc
# View unattended-upgrades logs here:
#
#   /var/log/unattended-upgrades/
#
sudo unattended-upgrades --dry-run --debug
sudo fail2ban-client status ssh
sudo ufw status
sudo systemctl status hello-world
sudo systemctl status caddy
sudo journalctl -u caddy -f

That's all, folks

And that's it. A working Bun service running on a cheap Hetzner VPS, served over https.

Happy hacking.