Software Notes | Eze's Website

I built a Stripe-based billing system

2026-07-04T00:00:00Z

I built a Stripe-based billing system | Eze's Website

I built a Stripe-based billing system

Sat, Jul 4 2026

I am at the end of an intense ~4 months of re-building a self-serve billing system backed by the Stripe API at my employer. We flipped on the feature flag a few days ago, making it available for new customers. A few random tidbits of knowledge I collected along the way:

Parse and validate the Stripe subscription object

The Stripe subscription API returns json data representing the state of the subscription at that moment. It is likely your integration only considers a subset of subscription states valid. Make that explicit by parsing and validating this json into your own Subscription object. Design the rest of the code to use this internal subscription object. Make it such that it is easy to create an in-memory representation of your customer that has all the information necessary to understand the state they are in.

Functional core, imperative shell

The plan update path is the most involved part of our integration. Instead of discrete plans for a customer to pick from, we allow more fine-grained customization to the features within the plan. Each feature has it's own pricing curve. The pricing of some features depends on the cost of others. The customer can also come back and update their selection mid-cycle. Some changes apply immediately, others are scheduled for the end of their billing cycle.

So a plan update is non-trivial. One strategy I used to tame this complexity is to only make network requests at the "edges" of the system. At one end, we request the Stripe subscription along with other relevant resources like subscription schedule, product, price and discount objects. Database reads are also done at this point. This bundle of data is passed to the "functional" core. This part of the code only operates on in-memory objects and is responsible for implementing the business rules related to updating a plan. It performs no I/O. It returns a set of data structures that represent the parameters needed to update the Stripe subscription into its desired state. At the other edge of the system, we take these output params, create a Stripe API request and send it.

Since Stripe requests are not randomly strewn around your business logic, you can thoroughly test the most important (and potentially most complex) part of your integration in seconds. This is a huge deal for gaining confidence in changes. Billing code tends to be daunting for newcomers because it moves money. Anything we can do to reduce the barrier to maintaing it is welcome.

Furthermore, you now get "preview" functionality for free. With some work, you can take a description of a change a customer would like to make and preview how that would affect their future state without actually modifying anything in Stripe. I think this is pretty cool.

Try to use Stripe prorations

If a customer makes a plan change in the middle of their cycle, we credit them for unused time, and potentially charge them for the remaining time on the new product. Stripe subscriptions support this. Use it. Don't do what we did. At the time of writing, Stripe's proration logic is mostly all-or-nothing: Time-based proration for all subscription items, or no proration at all. This felt too restrictive to us. So we initially decided to pass "prorations": "none" on all our requests and do manual prorations because we had slightly niche logic for one of our products. Right before we shipped the new system, I spent an evening deleting all the manual proration code I had written and using Stripe's proration logic instead.

I think it's easy to fall into this trap. If it's the first time you are doing it, the proration formula seems easy enough. But it interacts with the rest of your billing decisions in interesting ways. Here are some questions to ask yourself before sinking time into it:

How bad would it be if you just used Stripe prorations? If it's not a complete deal-breaker for your integration, consider adjusting your business rules so you can use Stripe's default behavior.
Can your subscriptions have flat dollar discounts? If so, think deeply about how these interact with prorations.
Do you ever issue a credit to a customer? If so, how do you know how much they previously paid? Imagine a customer paid on the 1st, someone gave them a discount on the 2nd, and they made a plan change on the 3rd that would involve a credit proration. Though their subscription has a discount, the credit should not consider it since they did not have it when you charged them.
Does your Finance team need proration invoices to look a certain way? A keyword is "revenue recognition".
Do you have any flows where the customer can update their billing cycle immediately? This would involve a credit for unused time on their old plan and a charge for the new plan. If these are two separate invoices, their order matters. If the credit invoice applies after the charge, the customer might not be able to use that credit till their next invoice, which might not be soon.

Incremental progress

I am not even close to being done with this work. The next chunk of work is migrating old customers to the new system. This will take a while. But it is a big relief to finally merge my 3-month old branch into master. Identifying milestones at which you can ship something is really useful. It is unlikely you'll be able support all possible customer states in one go. Whenever I think I finally understand how things work, Finance surprises me yet again with an example of a weird customer we sold a weird plan to this one time. Release something that works for an initial batch of users, and slowly expand from there.

Speeding up an HTML tokenizer

2026-05-29T00:00:00Z

Speeding up an HTML tokenizer | Eze's Website

Speeding up an HTML tokenizer

Fri, May 29 2026

I wrote and HTML parser, and a week or so ago I became dissatisfied with how the tokenizer was implemented. I made some changes:

Before:

$ go test --run '$^' --bench 'BenchmarkHtmlTokenizer' --benchmem --count=5
goos: linux
goarch: amd64
pkg: eze.works/go/gsx
cpu: 13th Gen Intel(R) Core(TM) i5-13400T
BenchmarkHtmlTokenizer-16    	       4	 270036084 ns/op	198183348 B/op	 3218584 allocs/op
BenchmarkHtmlTokenizer-16    	       4	 271043490 ns/op	197710172 B/op	 3211666 allocs/op
BenchmarkHtmlTokenizer-16    	       4	 273574498 ns/op	197710152 B/op	 3211666 allocs/op
BenchmarkHtmlTokenizer-16    	       4	 276339333 ns/op	197710200 B/op	 3211667 allocs/op
BenchmarkHtmlTokenizer-16    	       4	 275311635 ns/op	197710160 B/op	 3211666 allocs/op
PASS
ok  	eze.works/go/gsx	5.536s

After:

$ go test --run '$^' --bench 'BenchmarkHtmlTokenizer' --benchmem --count=5
goos: linux
goarch: amd64
pkg: eze.works/go/gsx
cpu: 13th Gen Intel(R) Core(TM) i5-13400T
BenchmarkHtmlTokenizer-16    	       6	 176753957 ns/op	25887232 B/op	  237496 allocs/op
BenchmarkHtmlTokenizer-16    	       6	 174922978 ns/op	25578853 B/op	  232892 allocs/op
BenchmarkHtmlTokenizer-16    	       6	 174573735 ns/op	25578850 B/op	  232892 allocs/op
BenchmarkHtmlTokenizer-16    	       6	 176337642 ns/op	25579737 B/op	  232893 allocs/op
BenchmarkHtmlTokenizer-16    	       6	 185298979 ns/op	25578866 B/op	  232892 allocs/op
PASS
ok  	eze.works/go/gsx	5.363s

The tokenizer now runs roughly 35% faster and consumes 87% less memory. The benchmark is tokenizing a 16mb file: the raw HTML contents of the full HTML spec page. Go ahead, try to open that link, your browser will probably hiccup 1I usually append /multipage to the link when I'm actually trying to reference the spec. . It's the only page that seems to give my browser a problem. A worthy candidate.

The benchmark is simple. The file is read into memory from disk, then I track the resource usage of tokenizing the whole thing. 2And by "track", I mean, I just call the function. Go makes it stupid easy to get started with profiling.

I'll explain the changes I made using the following HTML snippet as an example:

<lol< cLAsS\x00="box">&amp;</lol">

Imagine that \x00is a null byte (i.e. a zero byte). A spec compliant tokenier must interpret this as:

(tagstart) name=lol< attributes=[(class�, box)]
(text) content=&
(tagend) name=lol"
(eof)

No, you are not missing a font. That's the actual unicode replacement character appended to the attribute name as the spec requires.
For tokenizing HTML, you can't use zero copy techniques to avoid allocating token data. The contents of the returned tokens might not even exist in the input.

The most obvious structure for a returned token is:

type Attr struct {
    Name  string 
    Value string
}
type Token struct {
    Kind TokenKind
    Data string
    Attrs []Attr
}

My original tokenizer implementation was creating new strings as the input was processed. It would then return a []Tokenat the very end.

This worked fine, and was not a problem for my usage. But unfortunately I have enough knowledge of how memory works to be disgusted by the repeated allocations the runtime is likely making. Additionally, from what I understand about the Go garbage collector, it needs to scan through all pointers in the program to figure out what objects are still "alive". This seems to imply that generally 3The Go runtime is complex enough that this is not always true. The only way to be sure is to measure and investigate. , the more pointers the program has, the more work the garbage colector has to do.
My tokenizer was materializing a huge slice of Token structs, filled to the brim with string pointers to arbitrary places on the heap. I started to feel bad for the machine.

The first change I made was to avoid returning the full list of tokens all at once. I made the tokenizer function like an iterator; returning one token at a time. The complete list is not necessary because the parser only ever processes one token at a time 4I think this change is worth doing in the context of a GC like go's that traces pointers. Fewer pointers for the GC to trace is a good thing. In the absence of a shadow process using resources to scan your heap, this change might not be as beneficial? Idk. .

The second change was to stuff all the token data into a contiguous buffer. This buffer is likely to be slightly smaller than the original input, so you can pre-allocate the capacity ahead of time 5This is actually important. The returned tokens keep the backing buffer alive. If in the middle of tokenizing, the buffer needs to be reallocated, you'll end up with two or more big buffers hanging out in memory. . This coalesces thousands of little allocations into one big one. So in our example, the tokenizer would gradually accumulate a single buffer whith the following contents:

lol<class�box&lol"

The strings within the tokens then become pointers into this buffer, at different offsets. To do this, the tokenizer would need to keep track of where the current token's data starts and ends in this big buffer. Then when a token is about to be emitted you do:

data := buf[start:end]
ptr := unsafe.SliceData(data)
return unsafe.String(ptr, len(data))

You can then return the same Token structure outlined earlier, but the strings are now all pointing into the same allocation. This incantation is necessary because in almost all cases using the natural string(buf[start:end])will allocate, defeating the purpose of the buffer. Using unsafe.String here is safe to do because the buffer is append only, so the underlying bytes that form the string do not change after creation.

Self-referential rust data structures

2026-04-22T00:00:00Z

Self-referential rust data structures | Eze's Website

Self-referential rust data structures

Wed, Apr 22 2026

Here is a candid shot of me reading this blog post about the pain of self-referential data structures in rust.

Seeing someone who clearly knows more than me also struggle here was very validating. It's interesting that once you get into this space, the same names, blog posts and techniques start popping up. It's full of tradeofs. Are you ok with not freeing individual items in your self-referential structure? Do you need stuff to be shared across threads? Are you OK with leaking your use of an arena to users of your library? Do you have brain cells to spare?

My own experience in this comes from evolving my very own HTML toolkit. One of the things the library allows you to do is construct and manipulate HTML nodes. To do this you need to build a DOM-like structure, which implies parent, sibling, and child pointers. I've re-implemented this library at least three times. Once using bumpalo, another time using a plain Vec with indices and the third (and final) time using strong/weak pointers. The first two were techniques covered in the blog post.

I admit that once the article wandered into "Generativity", my eyes starting glazing over. I don't doubt that for the author's use case, the type gymnastics become necessary. And really, that's the point of their talk. But there is a sad user experience cliff here I think. The other option would be to give up and use unsafe, but then you'd have g͇̫͛͆̾ͫ̑͆l͖͉̗̩̳̟̍ͫͥͨe̠̅s problems.

Pick the right data structure

2026-01-25T00:00:00Z

Pick the right data structure | Eze's Website

Pick the right data structure

Sun, Jan 25 2026

I was reminded yesterday of the importance of finding the right data structure for a problem. I have this custom HTML parser I've written, and part of the implementation involves detecting named character references. Named character references are things like & or >. The HTML spec defines the complete list. There are about 2000 of them, and a good parser needs to recognize them and replace them with the unicode bytes they represent.

There are a few things to keep in mind:

The only reasonable way to parse HTML is byte by byte 1Technically you iterate over unicode scalar values, but for this explanation, that detail does not matter. .
Some of the named character references are prefixes to other ones (e.g, ∉ and &notindot). So you can't simply stop on the first match.

My initial implementation stored the named character references in a hardcoded map. Once I hit an ampersand, I would begin accumulating subsequent bytes into a temporary buffer. For each new byte, I would iterate through the keys of the map, looking for named character references that started with whatever was currently in my temporary buffer. This worked, so I moved on.

Yesterday, I was finally putting the library to real use. When loaded with a browser, the HTML file in question happened to have ~2.2MB of source html/css/js. Not that big, but much bigger than any input I had used while testing the HTML parser. Parsing was taking ~8 seconds.

pprof revealed the CPU was spending most of its time in the state for parsing character references. This makes sense: I was looping through all the keys in the map for each byte inside that state. But it wasn't necessary to do all that work. All I wanted to do was to check if at least one element in the hardcoded map started with the contents of my temporary buffer. With that fixed, runtime was down to ~3 seconds. Progress, but pprof still showed the same function taking up most of the execution time.

There were no real improvements I could make without changing how I stored and accessed the character reference map. I needed a way to quickly identify which character references were prefixed by the current contents of the temporary buffer. I knew about tries and that they were supposed to solve this exact problem, but I was not familiar with them and had not implemented one before.

So I pasted my code into Claude and asked:

I've written an html tokenizer in go. From profiling, it seems a lot of time is spent in the named character state. Specifically iterating through the pre-built character reference map. What can I do to speed that up?

Claude:

Option 1:
Use a Trie Data Structure (Best Option) Replace the map with a trie (prefix tree) for O(n) lookups where n is the length of the reference, not the number of entries:

type trieNode struct {
    children    map[rune]*trieNode
    replacement string // non-empty if this is a valid end point
}

type charRefTrie struct {
    root *trieNode
}

func buildCharRefTrie() *charRefTrie {
    root := &trieNode{children: make(map[rune]*trieNode)}
    
    for key, value := range characterReferenceMap {
        node := root
        for _, ch := range key {
            if node.children[ch] == nil {
                node.children[ch] = &trieNode{children: make(map[rune]*trieNode)}
            }
            node = node.children[ch]
        }
        node.replacement = value
    }
    
    return &charRefTrie{root: root}
}

I pasted this code verbatim into my project, adjusted the named character state, fixed an off-by-one error and profiled again: 76ms2There could be a whole other post here about how useful LLMs are for learning from first principles. This is not that post. .

The fix makes sense intuitively: by using trie, I am slowly narrowing down the list of potential named character references with each byte, instead of looking at all of them over and over again. But a speedup from 8000ms to 76ms almost makes me ashamed of how wasteful the original implementation was. All because I picked the wrong data structure.

Why isn't anyhow implemented using Box?

2025-12-13T00:00:00Z

Why isn't anyhow implemented using Box<dyn std::error::Error>? | Eze's Website

Why isn't anyhow implemented using Box<dyn std::error::Error>?

Sat, Dec 13 2025

The anyhow crate is a popular pick for handling errors in Rust applications. The protagonist of the crate is the anyhow::Error type, which can wrap anything that implements std::error::Error

If I were to implement a catch-all error type to wrap any other error type, I would probably define it like this:

struct Error {
    inner: Box<dyn std::error::Error>
}

impl<E: std::error::Error + 'static> From<E> for Error {
    fn from(value: E) -> Error {
        Error { inner: Box::new(value) }
    }
}

anyhow does it quite differently:

#[repr(transparent)]
pub struct Error {
    inner: Own<ErrorImpl>,
}

#[repr(C)]
pub(crate) struct ErrorImpl<E = ()> {
    vtable: &'static ErrorVTable,
    backtrace: Option<Backtrace>,
    _object: E,
}

It's written this way to save space. My Error struct is 16 bytes long 1Assuming a 16-bit architecture because a boxed trait object is represented as a "fat pointer". The anyhow implementation is originally based on the fehler crate, which in turn is based on the failure crate. Upon hitting 1.0, fehler's author wrote a blog post, which contained this illuminating nugget about a new feature flag:

The Error type, which uses heap allocation and dynamic dispatch, is designed for cases in which errors are very infrequent. For this reason, it is valuable to avoid pessimizing the happy path by making the Result type overly large. By default, the Error type is the size of two pointers - one to some data in the heap, and one to a vtable. With the small-error feature turned on, the size is cut in half to one pointer. This works by storing the vtable inline inside of the Error type’s heap representation, instead of storing it next to the heap allocated pointer. The interior of the Error type is then a dynamically sized type, but the pointer to it just a single pointer instead of a wide pointer like trait objects are.

So the grandfather of anyhow was implemented the same way I would do it2In older versions of rust, you would write Box<Trait> to denote a boxed trait object. , and the vtable business is an optimization that unfortunately pessimizes the clarity of the code.

That leaves that weird Own type:

#[repr(transparent)]
pub struct Own<T>
where
    T: ?Sized,
{
    pub ptr: NonNull<T>,
}

In fact, the file where it's defined contains two other types: Ref & Mut. Since vtables involve playing around with raw pointers, these types were added to give back some measure of type safety when doing so.

How I think about technical debt

2025-12-12T00:00:00Z

How I think about technical debt | Eze's Website

How I think about technical debt

Fri, Dec 12 2025

Working at a venture-funded startup has added some nuance to how I think about technical debt: it's not about the debt itself, but the interest rate.

You begin accumulating technical debt the moment you check in some new code. By checking the code in, you are committing your team to the continued maintenance of the functionality you added. On its own, there is nothing inherently good or bad about this debt. What matters is the ongoing cost: the time and effort it takes to change or understand the code later. This is the interest on the technical debt. If a piece of code makes people go "kinda terrified to change the logic here tbh", then you are paying high interest on this code whenever someone interacts with it. The only code with a 0% interest rate is no code at all.

Writing code is only worth it when the benefits it grants are worth the maintenance costs. It might be worth it to write high-interest code if you think it will hardly be changed, but think hard about writing medium-interest code for foundational parts of the system that will be frequently touched.

This type of thinking makes it possible to talk more clearly about paying off technical debt. It is possible to build a collective understanding around how certain corners of a system cost more to change than others. It's likely that high-interest parts of the code are more prone to bugs. Working on high-interest code does not spark joy. I might even try to avoid it by taking on technical debt elsewhere. Given enough churn in a high-interest part of the codebase, there are real impacts on new feature velocity, employee retention and product health. This is language that startups understand. The problem is no longer about some code being inherently "bad" with the only solution being to "fix it". It is now about lowering the interest the company is paying on the code, which can take many forms: rewriting it, refactoring it, replacing it with a third-party library, requesting fewer changes in the affected area etc.

The AT protocol is interesting

2025-10-24T00:00:00Z

The AT protocol is interesting | Eze's Website

The AT protocol is interesting

Fri, Oct 24 2025

Although I have had a bluesky account for almost a year now, I have not really given the technology it is built on, AT proto, much thought. Until yesterday. 1This surge is likely because I enabled pi-hole on my local network and immediately blocked *.ycombinator.com. I suddenly have a lot of free, productive time.

These three resources whet my appetite to learn more:

"Open Social"archived: I thought this explained the core of "Why AT proto" so well, I read it to my (non-technical) wife, and even she started to get it. I really think the ability to take your social media connections, likes, follows, media and general digital belongings elsewhere is appealing to regular folk.
"AT Proto for Engineers"archived: This is a wonderful high level view of how the protocol works. Lots of diagrams. Clearly explained. 10/10 have read through 3 times. It's titled "for distributed system engineers", but I think that's misleading; I think any software developer generally familiar with how web apps & backends & databases work would understand this.
"Turning a database inside out"archived: A talk on applying database implementation details to general application design. If you liked the previous link, then this is good supporting material.

Implementing a basic css selector engine

2025-10-02T00:00:00Z

Implementing a basic css selector engine | Eze's Website

Implementing a basic css selector engine

Thu, Oct 2 2025

I recently found myself forced to write a CSS selector engine. Figuring it out was extremely rewarding, so it thought it might be useful to write down the intuition about how you might do this.

By "CSS engine", I am referring to code that takes a css selector like p > [data-selected="yes"]and uses it to find matching HTML nodes. This assumes that you have a tree of HTML nodes to search over. The specific implementation does not matter, but your node API needs to have a way to get previous, preceding, parent and ancestor elements given a starting node.

The goal is to have an API that allows you to do this:

for node in start.select("p > li[href]") {
  // do something
}

I'll use the following selector as an example: body > span p + li. Think of it this way: The selector imposes certain constraints that nodes must satisfy in order to match:

The node must be a "li" element.
At least one of the nodes that matched the preivous step must have an immediate preceding sibling that is a "p" element.
At least one of the nodes that matched the previous step must have an ancestor that is a "span" element.
At least one of the nodes that matched the previous step must have a direct parent that is a "body" element.

We break down to the selector into four "checks":

[body ">"] [span " "] [p "+"] [li]

Each check specifies what to look for and where to look for it. The "what to look for" part is what the CSS specification calls a "compound selector"; Things like "div", "#container" and "[data-state|='selected']".The "where to look for it" part is what the CSS specification calls "combinators"; Things like ">", "~", and "+". To check if an element A matches a selector, we need to pass A "through" this stack of checks. Every check performs the same steps:

Takes a node as input
Applies the combinator 1But what combinator do we apply to the last li selector? For my algorithm, I decided to tack on a synthetic "identity" combinator that just passes on the node it was given. So if you get a li, you are going to be using that same li in the next step (as opposed to its ancestors or previous sibling for example). to the node to transform it into the list of nodes to consider.
Tests the compound selector against each node we are considering. If a node matches, pass it on to the next check.

An element matches if at least one of these paths makes it through the entire stack of checks.

Here is my my version of this. It is surprisingly not that much code at all once you figure out the how to do it. Pretty neat!

Just a matter of time

2025-09-21T00:00:00Z

Just a matter of time | Eze's Website

Just a matter of time

Sun, Sep 21 2025

I'm really happy with my latest creation: htmlite. It's an html toolkit for parsing, manipulating and generating html. It's currently part of the tooling that powers this site.

I'm not proud of it because it's technically interesting or anything, but because it took a lot of patience to work through. The core of the library is an implementation of the HTML tokenization spec. It's quite long for starters. At the time of writing, it's described as a state machine with 80 states. To someone unfamiliar with specs like this, it took a while to understand how to read the thing. It also takes some creative thinking to translate some of the spec operations into code.

But it was worth it! Parsing HTML was something I once thought I wasn't smart enough to do properly. That is no longer the case and it feels wonderful. It didn't take some big revelation or jump in intelligence. It was just a matter of time.

Stop doing templating languages

2025-09-02T00:00:00Z

Stop doing templating languages | Eze's Website

Stop doing templating languages

Tue, Sep 2 2025

I think HTML templating languages like jinja2, handlebars and go templates are the wrong solution. If what you are doing makes you reach for these tools, consider using a general programming language instead. HTML templating languages limit you to the subset of general programming patterns the language author has chosen to implement.

You don't have to do a lot of templating before thinking to yourself:

It would be nice to extract this section and use it in all these other places without repeating myself too much.
—A developer creating a site using an HTML templating language, probably

I hope the templating language you picked supports arbitrary user-defined snippets with the capacity to pass arguments. If you were using a normal language, you would use a regular function and move on.

This is mostly a public reminder to myself because I foolishly once thought writing a templating language was a good idea. I learned a lot in the process though, so I have no regrets. Once I got the basics working, I quickly realized that to make it useful, you basically have to implement variables, functions, arguments, loops etc... And at that point, why not just use an existing language?

A peek inside the rust bumpalo crate

2025-08-30T00:00:00Z

A peek inside the rust bumpalo crate | Eze's Website

A peek inside the rust bumpalo crate

Sat, Aug 30 2025

Using the rust bumpalo crate has opened my eyes to what you can do with alternative memory allocation strategies. I usually don't think to look at the code of low-level libraries; I'm afraid I won't understand. But I'm trying to get rid of that habit. Humans wrote this code after all, surely I can understand it given enough time and patience.

Why bumpalo?

The problem

I briefly covered that in a previous note. I needed a collection of nodes where (among other things) each node keeps track of its siblings. I chose to do this using shared references; each node stores shared references to its next and previous sibling. These references need to point somewhere, so I need a collection that owns the actual nodes:

use std::cell::Cell;

#[derive(Default)]
struct MyNode<'a> {
    next: Cell<Option<&'a MyNode<'a>>>,
    prev: Cell<Option<&'a MyNode<'a>>>,
}

fn main() {
    let mut nodes = vec![
        MyNode::default(),
        MyNode::default(),
        MyNode::default(),
    ];

    // We can manipulate the pointers!
    // This is the begining of a nice tree API!
    &nodes[0].next.set(Some(&nodes[1]));
    &nodes[1].prev.set(Some(&nodes[0]));
    &nodes[1].next.set(Some(&nodes[2]));
    &nodes[2].prev.set(Some(&nodes[1]));
    
    // Uh oh. I guess not
    // Error: cannot borrow `nodes` as mutable because it is also borrowed as immutable
    // nodes.push(MyNode::default());
}

Everything is great until the last line. The crux of the problem is that you can't be sure that a pointer to an element in a Vec continues to be valid after you've added a new element to the Vec; it could have copied all its elements somewhere else and your pointer now points to garbage. The rust compiler prevents you from doing this by enforcing that you can't have any existing references into the vec when calling nodes.push.

Thank you rustc, but that disrupts my plans >:(

The solution

Thankfully bumpalo exists. You can think of it as Vec that lets you push a new element into it and guarantees that all existing references are stable.

When you push an object into a Vec, it asks the system memory allocator for a chunk of memory, and stores your object in there. As you keep pushing, you use up that space. At some point you won't have any more space.

Vec handles this by asking the system memory allocator for a bigger chunk of space, copying all existing objects to that new space and appending your new element.

bumpalo does something different: It asks the system memory allocator for a bigger chunk of space, records the address of the old chunk of space in it, then adds your new element to it.

This means that existing references remain valid! The following compiles:

use std::cell::Cell;
use bumpalo::Bump;

#[derive(Default)]
struct MyNode<'a> {
    next: Cell<Option<&'a MyNode<'a>>>,
    prev: Cell<Option<&'a MyNode<'a>>>,
}

fn main() {
    // The collection of nodes
    let nodes = Bump::new();
    
    let a = nodes.alloc(MyNode::default());
    let b = nodes.alloc(MyNode::default());
    let c = nodes.alloc(MyNode::default());

    // We can manipulate the pointers
    a.next.set(Some(b));
    b.prev.set(Some(a));
    b.next.set(Some(c));
    c.prev.set(Some(b));
    
    nodes.alloc(MyNode::default());
}

So how does bumpalo do it?

Diagram time. This is what a non-empty Bump looks like:

+----------+
| metadata |
+----------+ <--------------------------- +
                                          | 
+------------------------+----------+ --- +
|___CCCCCCBBBBBBBBBBBAAAA| metadata |
+------------------------+----------+ <--------------------------- +
                                                                   |
+------------------------------------------------+----------+ ---- +
|_____FFFFFFFFFFFFFFFFFEEEEEEEEEDDDDDDDDDDDDDDDDD| metadata | 
+------------------------------------------------+----------+ <--- +
                                                                   |  
+------------------------+ --------------------------------------- +
| let bump = Bump::new() |
+----------------------- +

Our non-empty bump variable points to a sort of linked list of data + metadata objects. In the code, metadata is called a ChunkFooter, and is where the book-keeping information is stored.

The cells with letters (e.g. A, B, C) represent arbitrary bytes. Consecutive cells of the same letter represent one "object" that was allocated in the bump. Unlike Vec, Bump can store any type of object.

What does an empty bump look like?

+----------+
| metadata |
+----------+

It's represented as an "empty" chunk footer.

The first call to Bump::alloc(<blah>) causes bumpalo to request a chunk of empty space from the system memory allocator. It creates a new chunk footer with ChunkFooter::prev pointing to the initial empty chunk footer and writes it to the end of the space it was just given.

+----------+
| metadata |
+----------+ <--------------------------- +
                                          |
+------------------------+----------+ --- +
|________________________| metadata |   
+------------------------+----------+
                         ^
                         ^
      [metadata.ptr points here now]

The new chunk's ChunkFooter::ptr is a pointer that starts out pointing to the start of metadata. To allocate our object, we calculate how many bytes we need to store it, then decrement ptr by that amount. We then write our object to the space pointed to by the footer's newly updated ptr.

+----------+
| metadata |
+----------+ <--------------------------- +
                                          |
+------------------------+----------+ --- +
|__________________AAAAAA| metadata |   
+------------------------+----------+
                   ^
                   ^
      [metadata.ptr points here now]

If the object we are trying to allocate is larger than the availble space in the current chunk, we allocate another chunk, setting it's ChunkFooter::prev pointer to the old one. And so on.

And that's the core of it really as far as I can tell. There is a lot of code to handle proper alignment calculation, optimizations and allocating more complex objects. But at the heart of bumpalo is a linked list of heap-allocated byte buffers. Because objects that are allocated are never moved, even when appending the linked list:

Bump can add elements without requiring a unique reference
You can keep shared references to objects in bump for as long as the bump lives.

What are the tradeoffs of this approach?

bumpalo is not a magical "better Vec".

Its construction guarantees that references to items within it remain stable, so you can't de-allocate individual items.
Because it uses Cell, you can't share references to Bump across threads (though you can move the owned Bump into a thread).

👾

Self-referential Rust structs using arena allocation

2025-08-14T00:00:00Z

Self-referential Rust structs using arena allocation | Eze's Website

Self-referential Rust structs using arena allocation

Thu, Aug 14 2025

A lot of ink has been spilled on the topic of self-referential structures in Rust. I won't pile on.

I stumbled across a different pattern for achieving them in this github repo.

I found it useful for creating a tree of nodes that refer to each other after parsing some HTML.

Arena Allocator + std::cell::Cell:

pub struct Node<'a> {
    kind: NodeKind<'a>,
    parent: Cell<Option<&'a Node<'a>>>,
    previous_sibling: Cell<Option<&'a Node<'a>>>,
    next_sibling: Cell<Option<&'a Node<'a>>>,
    first_child: Cell<Option<&'a Node<'a>>>,
    last_child: Cell<Option<&'a Node<'a>>>,
}

... where 'a is the lifetime of the arena allocator 1 bumpalo has served me well. you are using.

This works because:

The compiler knows the size of the struct. All the Nodes are behind a & indirection.
Cell allows you to retrieve and mutate values from behind shared references (i.e. &) as long as the value is Copy. &Node is Copy because it's a pointer.
Parsing functions can receive an arena allocator as argument, allocate their nodes into the arena and return references to nodes whose lifetime is tied to the arena.

For my use case:

It is much better than using indices instead of references because you don't have to pass around the the list of objects everywhere.
It is much better than Rc<RefCell<...>> because you don't have to worry about overlapping borrow_mut() calls.

It feels like alien tech 👾

Make stuff up

2025-06-17T00:00:00Z

Make stuff up | Eze's Website

Make stuff up

Tue, Jun 17 2025

A recent Signals & Threads episode touched on how Jane street uses their own custom protocols for network communication. Internally, their services do not use HTTP, but instead speak a custom protocol over TCP/UCP. I vaguely remember a similar thing being mentioned by Matt Godbolt in his Two's Complement podcast; he was talking about how web dev in finance firms looks very different. Their UI's usually just open up a websocket connection and speak a custom protocol with the server.

I wish more people built exactly what they needed. No one cares about your needs more than you do, so inventing a protocol that solves your exact problems shouldn't be off the table 1As long as you document it.. You do not need permission to deviate from the well-worn, standard path. It's software! It's mostly an imaginary world to begin with. You can go your own way when it makes sense.

Parsing network streams

2025-06-11T00:00:00Z

Parsing network streams | Eze's Website

Parsing network streams

Wed, Jun 11 2025

I have often wondered what the "right" way to parse network streams is. Unlike parsing a file or something in-memory, parsing from the network often involves the annoying call to read(). It's annoying because you don't know how many bytes you'll get back. You could get 1 byte. You could also get 4k bytes.

My first stab at getting around this was to always read 1 byte at a time 1On its own, parsing byte-by-byte would be "slow" because each call to read() would involve an "expensive" network syscall. But I was doing this in Rust, which comes with a free abstraction around buffered reading, making this not such a bad idea. , and make my parsing code a state machine. Parsing with a state machine is "cool" in a weird sort of way, but it's also a pain to maintain and understand, especially for protocols as lenient as HTTP/1.1.

I have since moved away from that approach. For HTTP/1.1 in particular, I have found that it's much easier to buffer until you see a byte that indicates the end of a section. For example, to read the request line, you continuously read from the network socket until you see a \r\n or \n, then you take that chunk and parse it.

Until today, I wasn't sure how applicable this approach is to other protocols. To my surprise, the Beej guy that wrote the guide to network programming in C also recently wrote about just this topic. It appears that this "buffering until you get a complete message" is exactly how this sort of thing is done.

This is a nice affirmation that if you spend enough time trying to re-invent a wheel, you'll eventually stumble upon the best practices around wheel making. All on your own.

Elixir's mix tool is actually simple

2025-05-26T00:00:00Z

Elixir's mix tool is actually simple | Eze's Website

Elixir's mix tool is actually simple

Mon, May 26 2025

The mix tool is an elixir script. It's entry point is Mix.ClI.main(). When you execute mix at your shell that is all that is called1Remember that elixir is written in erlang. Erlang is able to find the compiled Mix.CLI module because the elixir shell script gives the erl executable a list of places to look for compiled beam modules. .

The Mix.CLI module simply compiles the mix.exs file in the current directory and stores the configuration in memory. It then looks for a Task with the same name as the argument it was given, compiles it and executes it.

Tasks define their own command line arguments, help, and behavior. It's a neat way to structure an extendable command line program.

How does Elixir's EEx work?

2025-05-25T00:00:00Z

How does Elixir's EEx work? | Eze's Website

How does Elixir's EEx work?

Sun, May 25 2025

Elixir's builtin templating library, EEx, is nifty. The more I understand it, the more interesting it becomes. Unlike most of the standard library, the documentation for EEx is sparse. But fear not, all software can be understood.

How do templating engines usually work?

On the surface, EEx is like other templating languages: the API accepts arbitrary text optionally sprinkled with special placeholders that are evaluated with a runtime-supplied object.

They all look like this:

Template.render("Hello {{ @who }}", { who: "world" })
=> "Hello world"

That's where the similarity ends. Most template libraries take the input text and break it into "instructions":

"Hello {{ @who }}!"
      |
      |
      v
[Text("Hello "), Expr("@who"), Text("!")]

They then go through this list, executing the code that matches the instruction using the runtime-provided object to lookup variables, and building up the output string along the way. More complex constructs like loops can be implemented by emitting "goto" instructions and keeping track of a loop counter. 1A good, readable example of this is the TinyTemplate.

These libraries "execute" the template as they go, just like interpreters.

EEx on the other hand is more of a compiler. When you call it, it does not output a string. It outputs Elixir code.

EEx outputs Elixir code!

Note that I'll be only talking about the EEx.compile_string/2 function, as all other functions in the EEx module depend on it.

The docs for EEx do explicitely say that this function compiles a string into an Elixir syntax tree. But I was still surprised when I actually internalized it.

Take the string one <%= "two" %> three <%= "four" %> five for example. If you gave the equivalent of this to another templating library , you would expect to get back one two three four five. But that is not what you get from EEx.

iex(5)> EEx.compile_string(~s(one <%= "two" %> three <%= "four" %> five))
{:__block__, [],
 [
   {:=, [],
    [
      {:arg0, [], EEx.Engine},
      {{:., [], [{:__aliases__, [alias: false], [:String, :Chars]}, :to_string]},
       [], ["two"]}
    ]},
   {:=, [],
    [
      {:arg1, [], EEx.Engine},
      {{:., [], [{:__aliases__, [alias: false], [:String, :Chars]}, :to_string]},
       [], ["four"]}
    ]},
   {:<<>>, [],
    [
      "one ",
      {:"::", [], [{:arg0, [], EEx.Engine}, {:binary, [], EEx.Engine}]},
      " three ",
      {:"::", [], [{:arg1, [], EEx.Engine}, {:binary, [], EEx.Engine}]},
      " five"
    ]}
 ]}

I'll walk through how to read this indented data structure in another post, but for now it's important to understand that this data structure is Elixir code. The Elixir code you write is actually the textual/human representation of this data. When you execute the textual representation of Elixir code, the compiler transforms it to this data structure. It's just Elixir tuples. Just like any other pieace of data, you can save this to a variable, write it to a file, or even send it over the network.

The docs call this an Abstract Syntax Tree" or a quoted expression. I think that distinction blurs the fact that this datastructure is the language. And the language is data. 2Hey! that sounds familiar.

You can see the human representation of this data structure:

iex(8)> EEx.compile_string(~s(one <%= "two" %> three <%= "four" %> five))
        |> Macro.to_string()
        |> IO.puts()
arg0 = String.Chars.to_string("two")
arg1 = String.Chars.to_string("four")
<<"one ", arg0::binary, " three ", arg1::binary, " five">>
:ok

Instead of printing out one two three four five, EEx handed us a sequence of expressions that evaluate to a binary/string with the contents one two three four five. It compiled the string template to executable code.

So how does it work?

The EEx.Compiler module converts the input template into a list of what I'll be calling "chunks". For example:

~s(one <%= "two" %> three <%= "four" %> five)

... gets converted to ...

[
  {:text, ~c"one ", %{line: 1, column: 1}},
  {:expr, ~c"=", ~c" \"two\" ", %{line: 1, column: 5}},
  {:text, ~c" three ", %{line: 1, column: 17}},
  {:expr, ~c"=", ~c" \"four\" ", %{line: 1, column: 24}},
  {:text, ~c" five", %{line: 1, column: 37}},
  {:eof, %{line: 1, column: 42}}
]

Text outside the special markers is represented as a tuple tagged with :text. Elixir expressions inside the special markers are tagged with :expr.

The docs don't explicitly mention this, but EEx also supports block syntax. Tuples tagged with :start_expr, :middle_expr and :end_expr are used for this case. You can do this:

"""
Listing:
<%= for post <- posts do %>
  Name: <%= post.title %>
  Href: <%= post.href %>
<% end %>
"""

... or even this ...

"""
<%= if true do %>
  "something"
<% else %>
  "something else"
<% end %>
"""

The last example gets converted to the following chunks:

[
  {:start_expr, ~c"=", ~c" if true do ", %{line: 1, column: 1}},
  {:text, ~c"\n  \"something\"\n", %{line: 1, column: 18}},
  {:middle_expr, [], ~c" else ", %{line: 3, column: 1}},
  {:text, ~c"\n  \"something else\"\n", %{line: 3, column: 11}},
  {:end_expr, [], ~c" end ", %{line: 5, column: 1}},
  {:text, ~c"\n", %{line: 5, column: 10}},
  {:eof, %{line: 6, column: 1}}
]

The EEx.Compiler.compile function calls the similarly named function in the EEx.Engine module for each of these chunks, pasing in the chunk as well as accumulated state.

In the default EEx.Engine implementation, the accumulated always has this structure:

%{ binary: [ ... ], dynamic: [ ... ], vars_count: num }

This makes sense when you realize that compiling the template always returns code with the following structure:

# The "dynamic" section
# A variable declaration for each non text "chunk" in the template
arg0 = String.Chars( ... )
arg1 = String.Chars( ... )

# The "binary" section
# A binary as the last expression
<<"verbatim text from template", arg0::binary , "text", arg1::binary>>

The vars_count is used to keep a counter to generate the argX variable names. The binary list contains the :text chunks. The dynamic list contains AST/quoted expressions/Elixir code for the expressions inside the special markers.

The job of EEx.Engine is to build up this accumulated state as it's handed the chunks of the template. EEx.Engine.handle_body is called at the very end with the accumulated state in order to build generate the Elixir code. The "secret weapon" that makes this possible is that Elixir already exposes functions that take the textual representation of Elixir code and turn it into data.

Notes on elixir compilation

2025-05-23T00:00:00Z

Notes on elixir compilation | Eze's Website

Notes on elixir compilation

Fri, May 23 2025

Elixir is not a self-hosted language. The compiler is implemented in erlang. It is organized into various modules in lib/elixir/src.

The elixir and elixirc commands are shell scripts that run the erl command, giving it the compiled elixir erlang module, and executing its start_cli function.

Because the elixir compiler is written in erlang, bootstraping is straightforward. The makefile:

Compiles the elixir compiler written in erlang into erlang bytecode.
Starts the now-compiled elixir compiler application, and uses it to compile the standard library that is written in Elixir

Put simply, the elixir compiler is erlang code that recognizes elixir syntax, and transforms it into the erlang Abstract Format. Don't let the name scare you though, this "Abstract Format" is very concrete and is essentially erlang data-structures representing the AST of erlang code. The elixir compiler then feeds this Abstract Format into the erlang compile module.

I think it's pretty neat that erlang exposes a function to compile erlang AST into bytecode that can run on the erlang VM. This is probably a big reason why the elixir compiler can be maintained by a single person.

Optimizing HTML images as a post-processing step

2024-03-30T00:00:00Z

Optimizing HTML images as a post-processing step | Eze's Website

Optimizing HTML images as a post-processing step

Sat, Mar 30 2024

I have been working on a new marketing site for my employer. The design includes a lot of high resolution image assets. To keep the site snappy, it's useful to avoid downloading huge images when not necessary. On a mobile phone for example, the image could be several time smaller without looking different to the human eye. The standard approach to optimize images is to generate multiple versions of the image at different sizes, then use the image srcset attribute to tell the browser which version to load. These are called "responsive images".

This is what the markup for a responsive image might look like:

<img
  srcset="elva-fairy-480w.jpg 480w, elva-fairy-800w.jpg 800w"
  sizes="(max-width: 600px) 480px,
         800px"
  src="elva-fairy-800w.jpg"
  alt="Elva dressed as a fairy" />

I don't want to manually figure this out whenever I need to insert an image. We are using Hugo, so my first thought was to write a partial archived that did all the work to make a simple <img> tag responsive. Like a gift from above, that same day, jampack was posted to Hacker News. Jampack archived is a CLI tool that takes a static site as input (e.g. a folder with a bunch of HTML, CSS, JS & assets) and optimizes it by doing exactly what I had set out to do and more. This means I can continue to write standard unresponsive <img> tags but still get responsive images in the final output of the site. All for the cheap price of four new words added to the build script:

npx @divriots/jampack ./public

My joy is immense.

Time for Computers

2023-11-04T00:00:00Z

Time for Computers | Eze's Website

Time for Computers

Sat, Nov 4 2023

The basic unit for CPU time is a nanosecond. This is too small a measure to develop an intuition for. But you can build intuition by comparison. In the "Time for Computers" episode of the Two's Complement podcast, Matt Godbolt tries to tackle this by comparing the CPU time scale with a human time scale. This really helped me, so i'm reproducing a hand-wavy transcription of that scale here:

The basic unit of work a CPU can do is an instruction cycle. During the cycle the CPU will fetch an instruction, decode it and execute it.

CPUs take 1 cycle to do elementary operations like addition, subtraction, XOR's and such. A CPU cycle takes a third of a nanosecond. Charitably, we'll say a human doing the same kind of operation would take 1 second.

So that's our scale: 1/3 nanosecond for a CPU is like 1 second for a homo sapiens.

The next type of operation a CPU does is multiplying. It takes anywhere between 4 and 6 cycles for a CPU to do multiplication. That works out as ~1.3 nanoseconds, which in human time is 4 seconds. Now that's still plausible. You could imagine someone who is good at mental math taking about that long to compute 398 times 16 (...i am not good at mental math).

Next up is division If you don't have some sort of look up table, you will need to use pencil and paper to manually calculate. That intuition is about right for CPUs. They can't do division that much better than humans can. Integer division is anywhere between 30 - 100 cycles (10 - 33 ns), which in our scale is anywhere between 30 seconds to a minute and a half of human time. This makes sense if you imagine the CPU needing to take out a pencil and paper.

CPUs read from memory as well. We are told that memory is slow, which is why we have CPU caches that are supposed to make things go faster.

An access to L1 cache is the fastest thing you can get. It's a tiny cache right next to the CPU on the order of 32K bytes in size. It takes 3 CPU cycles to read from L1, which is ~3 seconds in human terms. That's a bit like retrieving information from the sticky-note on your desk.

L2 cache is a bigger, further away cache. If we were comparing L1 to a sticky-note, L2 is like a set of ring-binders you have on the shelves behind you. Accessing L2 is 10 cycles away, which in human terms would be 10 seconds away. Seems a bit quick for a human, but it's within the realm of possibility.

L3 is the final cache layer shared between CPUs. That takes about ~40 cycles to get information, which is 40 seconds in human time.

Now if have to hit main memory, we are talking 100 - 120 nanoseconds. That is 6 minutes of human time. A trip down the elevator to the archives to get the book you need and go back up the elevator and back up to the office to put it in cache. In the working life of a computer whose working job is adding numbers together, that's twiddling your thumbs or taking a tea break. That's why all these performance geeks hate missing their cache so much

Now for the scary part. Reading from an SSD takes about 50 microseconds (not nano anymore!)...which is 2 whole days of human time. That's ordering something on amazon.com whenever you ask your CPU to read a file from disk. Disgusting. I will never use disk again /s.

If you are using a spinning disk whose head is not positioned in the right place and has to seek to the right sector, we are talking 1 - 10 milliseconds...which is 1 - 12 months in human months...

At the far end of this scale is rebooting the computer. Assuming it takes 5 minutes to do so (plausible depending on your computer), that's 32 millennia in human years. A civilization-ending event for your CPU. Think again before rebooting your computers.