Solution</th>	Version</th>	Run Time</th>	Speedup</th></tr></thead>
Part 1</td>	`naive</code></td>`	`118.16 ms</code></td>`	`1.0x</code></td></tr>`
</td>	`naive + no alloc</code></td>`	`53.2 ms</code></td>`	`2.2x</code></td></tr>`
</td>	`optimized</code></td>`	`20.04 ms</code></td>`	`5.9x</code></td></tr>`
</td>	`optimized + no alloc</code></td>`	`10.2 ms</code></td>`	`11.6x</code></td></tr>`
Part 2</td>	`naive</code></td>`	`4.01 s</code></td>`	`1.0x</code></td></tr>`
</td>	`naive + no alloc</code></td>`	`1.81 s</code></td>`	`2.2x</code></td></tr>`
</td>	`optimized</code></td>`	`778.41 ms</code></td>`	`5.2x</code></td></tr>`
</td>	`optimized + no alloc</code></td>`	`358.53 ms</code></td>`	11.2x</code></td></tr> </tbody></table> Environment</h4> I ran these tests using Go version go1.22.3 linux/amd64</code>, on a ThinkPad X1 Extreme Gen 4i, rocking an 11th Gen Intel i7-11800H (16) @ 4.600GHz (reported by neofetch</code>)</p> All code for this and other solutions can be found on GitHub</a></p> "I think you might be a scam" - A Lesson in Customer Discovery 2024-03-20T00:00:00+00:00 Learning how to talk to customers has been a fun aspect of building a business. Although, it is by no means "easy." Like many engineers, I struggle with this, because what we really</em> know how to do is write code, and we think if we just buckle down and knock it out quickly, we could validate our idea that way.</p> That might work for some product ideas, but I'm becoming increasingly convinced that "build first" approaches are a great way to waste a bunch of time, effort, and money towards building a product nobody cares about.</p> I'm not alone in this way of thinking, and it certainly wasn't my idea. My mentor at the startup incubator I'm currently in encouraged me to stop building and actually talk to some customers. I definitely wasn't thrilled to hear that at first. I thought I had a strong sense of what I should build, but he rightfully challenged me on those assumptions.</p> The Mom Test</h2> I sighed and took a step back, and started to learn how to approach customer discovery. My mentor recommended The Mom Test</a>, and now I couldn't agree more. It's a concise little book that gives you that real, practical advice on how to approach customer discovery, with a particular emphasis on not biasing the prospect.</em> As Rob Fitzpatrick outlines his approach, he details a particular mistake he finds a lot of entrepreneurs making, where they'll pitch an idea and immediately ask "What do you think? Is it a good idea?" This leads to all sorts of psychological issues surrounding human behavior.</p> The basic issue is that, nobody wants to hurt your feelings. When they are really thinking "meh, I'm not sure why I would use that." Or, "I really don't want to switch products right now.", they are telling you "Yeah sounds great! Let me know when it launches." You walk away feeling like a business genius, but in reality, they just told you what they thought you wanted to hear. This is particularly the case when the person you are pitching your idea to is your mom. But friends and colleagues are guilty of the same thing.</p> So, how do we address that problem? Just ask people questions about their lives and jobs.</em> You can start out pretty broad, but it's OK to narrow focus around the industry and problem you are interested in. The idea is that by having casual conversations, you let your potential customer tell you what their problems actually are, not what you assume them to be. By hearing the same problems come up across multiple customer calls (the amount varies), you can build way more confidence in your solution as something people will actually buy. I can't do the entire book justice in this post, so if this idea sounds interesting to you, definitely pick up a copy and read it. (Not a paid promotion, I really just think this book is incredible.)</p> I took a lot of the advice and strategy of the book to heart and set out on finding contacts. I was able to lean on my network for this a little bit, but I've also had to do some cold outreach via email. Waiting for my network to follow up was just taking too long. My product revolves around the volunteering space and fortunately, the space is huge. There is no shortage of non-profit organizations. I was able to email 7 solid prospects in one morning just by looking at my city's chamber of commerce website.</p> What I didn't fully take into consideration was how my language might sound to some of those prospects. One of them in particular responded in a way I never expected.</p> Bitter cold outreach</h2> I actually have no real idea how to approach cold calling, and in what was perhaps an overly enthusiastic email power session one Friday morning, I sent this out to a prospective customer.</p> Hello [redacted],</p> My name is Nick and I'm part of a startup program at Iowa State, where I'm doing research on volunteer management and organization. I came across [redacted; org name] and am interested in learning more about your organization and volunteer program - what works for you, and maybe some of the challenges. It seems like [redacted; org name] has a wide range of roles volunteers can fill!</p> Would a member of your team have 20 or 30 minutes to chat with me over the phone sometime next week? I have nothing to sell, I'm just interested in learning more about how your volunteer program operates.</p> I really appreciate your time!</p> Thank you,</p> Nick</p> </blockquote> If you happen to be an expert in cold calling and outreach, I'm sure there are aspects of this email you may find pretty funny.</strong> I acknowledge that and I'm looking into how to improve it. In the meantime, please bear with me. I'm an engineer.</p> I fired off that email and hoped to get a response the following week. Sure enough, it came through.</p> Hello Nick,</p> Thank you for reaching out to us.</p> Could you provide me with a little more details of what information you're looking to gather? Let me know and I would be happy to help if I can.</p> Thanks and make it a great day.</p> [redacted; name]</p> Volunteer Services Coordinator</p> </blockquote> Fair enough. I could see how my initial message might not be clear to somebody, and they just want to be protective of their time. No problem.</p> Hi [redacted],</p> Thank you for your response!</p> I'm looking to learn more about your volunteer program, in terms of how it operates. Thinking about the "lifecycle" of a volunteer - how they show interest, how they get approved / onboarded, and how they schedule shifts. I'm interested in hearing specifically how you do those kinds of things today, tools you use, and where you see some of the challenges. I am hoping to develop new solutions for this space, but I first need to validate some of my assumptions about the process across different organizations.</p> Hopefully that makes sense. Happy to address any other questions!</p> Thank you,</p> Nick</p> </blockquote> I sent that reply at 9:00 AM, and at 4:00 PM, I received the following.</p> Hello Nick,</p> I have to be honest with you... there are a couple red flags to know if this is a scam or not so I'm going to pass on providing our information.</p> Thank you.</p> [redacted]</p> </blockquote> ...</p> I was honestly shocked.</p> Maybe it's just me, but if I think something is a scam, the last thing I do is reply to it. Oh, I definitely want to - especially so I can mess with them - but I know I'm better off not engaging.</p> (Although, the lone "Thank you." is probably my favorite part.)</p> In all seriousness, I expected to be ghosted by a few contacts, but I never expected to be told I might be somebody trying to execute a scam. I re-read my messages probably a dozen times, pouring over every word, trying to figure out what I said that was so concerning.</p> I did end up sending a response that I won't show here. I wasn't mean or snarky with them, and even apologized for how I came across, but it's just a little embarrassing. I probably over explained what I was trying to do, and even mentioned things like "I didn't lead with that information (about my company and idea) because I didn't want to bias you." It's absolutely the truth, but I'm sure they don't really care at this point. Phrasing it that way might even come across as me essentially admitting I was trying to play some scammer Jedi mind-trick I was certain would win them over, but now that they've caught me, we can get to the "real" facts to calm their nerves.</p> I can laugh about this experience now, but it definitely rocked me at first. It sucks to be told something so blatantly wrong, especially when you make the effort to be as cordial and concise as possible. It also made me wonder if the people who ghosted me did so because I came across in a sketchy way.</p> Moving forward, I will definitely adjust my approach. I think the biggest lessons are,</p> Don't be afraid to say you are a software developer trying to build a new product.</strong> Saying you have an idea isn't the same as telling them what the idea is, and I think my prospective contact would have appreciated knowing what exactly I was attempting to do up front. Framing it as "just a conversation" works for some people, but others might find that to be a little odd.</p> </li> Stop talking so much like an engineer.</strong> In my follow-up response to their question about what exactly I was looking for, I threw out words like "lifecycle" and started to describe the problem as I would describe it to another engineer. I went way over the top with detail when I should have just said, "Oh my gosh, I'm sorry I wasn't clear. I really just want to learn more about your organization so I can better understand the problems facing volunteer organizers. I do some volunteering myself and I'm curious if other organizations are facing the same problems."</p> </li> </ul> Even with all that, you can't win them all. People will ghost you, and they may not be very helpful. The goal is to keep talking with people who are willing to talk with you until you stop hearing new information. Then, go build a kick-ass product.</p> And if you're going to scam anybody, find your own strategy. This one is mine.</p> Static Site Generators: Not Just for Blogs 2023-12-11T00:00:00+00:00 Static site generators have become popular within the technical and programming focused communities. They are fast, focused programs that allow anybody with a little bit of HTML and CSS skill to produce a blog or product page quickly, write all their content (typically) using markdown</a> in a simple folder structure, and commit it all to git. Truly a gift and a joy to work with, compared to something like Wordpress.</p> Cloudflare</a> defines a static site generator (SSG) as "a tool that generates a full static HTML website based on raw data and a set of templates"</strong>. In this context, "static" means that the end result of the build is a set of HTML pages that don't change when the page is refreshed, not that those pages never</em> change.</p> Static site generators are incredibly powerful tools available for modern web development and I think a lot of developers are missing out on what they offer in terms of development time, hosting cost, and overall simplicity.</p> Blog Bias</h2> Blogs are common examples that come up when researching static site generators and how they can be used. This makes a lot of sense, as once blog posts are published, they rarely change, and they need to load quickly. In the context of a company blog, SEO is a major factor as well, since search engine crawlers need to parse content quickly.</p> Unfortunately, I think a lot of the understanding around static site generation ends here, even among web developers. For a long time, I was in this camp as well. I knew I could use static site generation effectively for my blog site, or a simple "about" page here or there, and maybe even a legal statement or privacy policy. Basically, anything where the content could be shown in a long, continuous block of text.</p> This understanding makes some product pages, or pages that require laying out collections of blocks in a grid-like structure difficult to reason about, and nearly impossible to build in some cases. If I can only store content in a big blob of text, and each document in my repository is a single page, how would I break it up so I can spread out the content to different sections of the page and style it appropriately? Worse yet, how would the non-technical team members update copy on the page without having to dig around in the HTML directly?</p> Options for managing structured content</h2> I'm going to use zola</a> as my static site generator of choice and show some examples of creating and rendering "non-blog" content, in a few different ways. This is only because I'm the most familiar with it, but there are lots of good options out there, such as hugo</a>. They may or may not work in exactly the same way, but what's important here is taking the ideas and expanding our understanding of how we can utilize SSGs to their full potential.</p> 1. Section and Page Metadata</h3> Sometimes called "front matter", each section or page of our site can have metadata associated with it.</p> Even in the case of a blog, you'll see this metadata above the markdown content, enclosed in some kind of marker, to separate it from the main content of the post. This would include things like title</code>, description</code>, author</code>, and date</code>, and read by the static site generator itself to organize and template the page. The front matter of this post looks like,</p> +++ </span>title = "Static Site Generators: Not Just for Blogs" </span>description = "Static generation should be the default" </span>date = 2023-12-11 </span>[taxonomies] </span>tags = [ "web" ] </span>+++ </span></code></pre> The easiest way to add structured data to this page would be to use the built-in [extra]</code> field for our custom content.</p> +++ </span>... </span> </span>[extra] </span>seo_keywords = "please, read, my, blog" </span>+++ </span></code></pre> Then, inside of the template that renders the page, we can include these keywords in our block that allows for <meta></code> tag keywords to be added,</p> {% extends "base.html" %} </span> </span>{% block title %}{{ page.title }}{% endblock %} </span>{% block seo_keywords %}{{ page.extra.seo_keywords }}{% endblock %} </span></code></pre> which could generate HTML that looks like this,</p> # template </span><</span>meta </span>name</span>="</span>keywords</span>" </span>content</span>="</span>{% block seo_keywords %}{% endblock seo_keywords %}</span>"> </span> </span># rendered </span><</span>meta </span>name</span>="</span>keywords</span>" </span>content</span>="</span>please, read, my, blog</span>"> </span></code></pre> To build upon this example, imagine instead we had a product page and we wanted to specify a list of features.</p> +++ </span>... </span> </span>[extra] </span> </span>[[extra.features]] </span>headline = "Amazing Feature" </span>description = "Do something amazing." </span> </span>[[extra.features]] </span>headline = "Awesome Feature" </span>description = "Do something awesome, instead." </span>+++ </span></code></pre> Here, we have separated the content of each feature item from the display and styling of them. In our template, we can now iterate over each of these feature items and place them however we want on the page, using the page.extra.features</code> array.</p> 2. Data in templates</h3> In many cases, it's useful to store website copy (especially marketing copy) in a content management system (CMS), where non-technical team members can edit and review content before it goes live on the website.</p> The section and page metadata approach falls a bit short, since it still requires modifying files locally and committing them to git.</p> Fortunately, zola</code> offers a load_data</code></a> function to bring in data from a remote source, within a template.</p> As an example, we can build up a SaaS pricing page this way, using an endpoint in our hypothetical CMS.</p> {% set token = get_env(name="API_TOKEN") %} </span>{% set data = load_data(url="https://my.cms.com/api/data/pricing", format="json", headers=["Accept=application/json", "Authorization=Bearer " ~ token]) %} </span> </span><h1>{{ data.tiers[0].name }}</h1> </span><ul> </span>{% for feature in data.tiers[0].features %} </span> <li>{{ feature }}</li> </span>{% endfor %} </span></ul> </span></code></pre> The "url" passed to load_data</code> can be a local file as well, if it makes sense to store that JSON locally.</p> </blockquote> This gives us the flexibility to put content somewhere else that is more accessible to a wider group of people on our team. Any change in the CMS can be detected (hopefully via a webhook) and the site can be rebuilt, previewed and pushed to production.</p> Side note</strong>: static site generators are fast</em>. This entire site builds in just under 100ms.</p> </blockquote> 3. Automated markdown file generation</h3> Finally, there is always the option to generate a set of markdown files to be placed in the content</code> directory. This is the approach I've taken for the bips.dev</a> site, where each BIP is a separate page, with front matter and markdown generated from a script that uses pandoc</code></a> to translate the media wiki format to markdown.</p> Admittingly, it's a bit of a hack, but it does work. Large documentation sites could be built this way with content from a CMS. This method would be needed whenever the actual structure of the site is dictated by some other source. In the case of bips.dev</code>, that source is a public git repository</a>.</p> Simple as the default</h2> TL;DR</strong></p> With the proliferation and increasing sophistication of SSGs, I think the time has come where we can say that the default</em> choice of any "non-application" website should be static generation. Statically generated sites are faster to develop, easier to host, and easier to reason about over the lifetime of the project.</p> I want to be explicit in stating what I hope is the obvious: If you are building a highly interactive application with lots of business logic, obviously</em> a fully featured programming language and deployment environment is going to be a better option. I think that statically generated sites still offer some room to include interaction and business logic with client-side Javascript (alpine.js</a> is a great candidate here), and that can always be included as part of your templates and build output.</p> I would even go so far as to say that needing to have a few business logic endpoints shouldn't completely eliminate the possibility of using a static site generator, as you could simply have a reverse proxy forward those requests to an application server, and just serve the static content for everything else. Some judgement would need to be exercised there, to see if it makes sense for the use-case, but I would still take a moment to see if that model could satisfy your requirements.</p> On the infrastructure side, hosting a statically generated site is just about the easiest thing to do. From a self-hosted nginx</code> instance to a managed platform that watches for changes in your git repo and builds the latest version of the site with automatic certificate renewal, there are tons of reliable options.</p> A recent website rebuild I worked on spent far more time than necessary dealing with the heavy frontend framework that was chosen, mainly because the full scope of how static site generators could be used wasn't known at the time.</p> It's tempting to reach for those languages and tools, since they are familiar to a lot of developers. At some point though, we have to use the best tool for the job, and bringing along all of React to build out a few product pages just doesn't seem like the way to go.</p> I could be way behind on this. If you're reading and find all of it to be blatantly obvious, or something that was figured out years ago, awesome! In my recent experience, there is still a lack of understanding around SSGs, and I hope we'll see a renaissance soon, where the simple choice is the default choice.</p> Building a nostr client [1] 2023-08-31T00:00:00+00:00 Welcome to the second installation of the "Building a nostr client" series. The goal of this series is to walk through building a simple nostr client in Rust. If you haven't seen the first post here</a>, I would recommend doing so, as we'll build on those concepts. Also, if you aren't familiar with nostr and why I'm doing this, that would be a good place to start as well!</p> In the last post we discussed the basic data structures of the protocol; how to build them, and what basic Event signing could look like.</p> In this post, I want to start connecting to relays, and build a simple TUI (terminal user interface) to display events.</p> Building on prior art...</h3> When I first considered doing this series of posts, I had the thought that I would do pretty much everything "from scratch". Essentially, use libraries available to me in Rust, but nothing nostr specific. After finding the nostr crate</a> and giving it some thought, I decided that I would, at the very least, use its core data structures, event generation and signing capabilities to build my client. yukibtc</a> and other contributors have done an incredible job with this crate so far. Much better than I could do. It's easy to understand and quite comprehensive.</p> So, in the interest of time, and future-proofing this project (I know I'd have to refactor my code to use the nostr</code> crate at some point anyway), I'll be using that crate moving forward. Even so, I want to explore some different methods of relay interaction that depart from the sibling nostr-sdk</a> crate, so we'll have plenty of code to write there.</p> Moving on!</p> Relays</h3> Relays are the backbone of the nostr protocol. They are responsible for accepting events and sending them on to interested clients. By design, there are many relays a client could possibly connect to. Some require payment for access, but many are free. Some are built for a specific community or topic in mind, but most right now seem to be pretty free-form. If one relay goes down, for any reason, temporarily or permanently, clients can just connect to another.</p> Clients connect to relays and send events (or "notes") across them, and clients on the other end set up filters</em> for those events. Not every user is automatically connected to every other user, as they would be on the global feed of a centralized platform, so there are some issues around discovery, as you need to know which relays people are posting to. But, in practice, it's not a big deal. (And there are some NIPs out there attempting to mitigate this.)</p> As you start to think about how a client should interact with its configured relays, you tend to realize:</p> There is no "should".</strong> Other than the basic data over-the-wire requirements of the protocol, clients can and actively do all sorts of things to transmit and receive events to and from relays. Without The Algorithm</a> handed down from on high, there are really no rules here. You want events chronologically? Great. You want events from your followed accounts and the accounts they follow? Sure. Only show events whose ID ends with the hex digit f</code>? I guess. Allow the user to selectively send events to some relays but not others? Yes, absolutely.</p> </li> It's suprisingly deep.</strong> There are a lot of practical elements to consider when building a client's view of the nostr world, especially in a "twitter-like" way. Generally you want to have the option of viewing something other than the "global" feed of all their connected relays, as it can either be extremely spammy, or just too much information, too quickly. So, you need some kind of view filtering, even if it's just showing events from the user's followed accounts. Also, what if the user is away from the client for a while (say a month) and decides to come back? Do you start showing them events from exactly where they left off? It might take them a while to scroll through and catch up to current events. Do you fetch older events if they scroll in reverse chronological order? How many do you fetch at a time?</p> </li> </ol> I could go on with plenty more rhetorical questions related to client/relay interaction. It really is the wild west right now and there are a lot of opportunities to innovate in this space.</p> All that being said, I want to start as simple as possible. For now, we will support showing events from the user's followed accounts, in the order we receive them. But first, we need to connect to some relays.</p> Finding a connection <3</h4> Connecting to a relay is relatively</em> straightforward in principle, but somewhat difficult to manage in practice.</p> Fortunately, the really low-level details are already handled for us in a crate called tokio-tungstenite</a>. tungstenite</code> is a popular Rust crate for handling WebSocket</a> connections, which nostr uses for its protocol communication layer. The "tokio" side of this crate just brings it into the most popular ecosystem for asynchronous programming in Rust... tokio</a>.</p> I believe the primary motivating factor for using WebSockets in nostr instead of some other transport protocol is that WebSockets are everywhere</em>, especially modern web browsers. This means clients can work within or (in our case) outside a browser context. It also means clients can make one connection to a relay, and reuse that same connection for multiple things, reducing some of the connection overhead on the server.</p> </blockquote> Another quick caveat: Like many aspects of this series, especially related to Rust, I certainly cannot do the asynchronous programming story justice here. It's another huge topic, deserving of near book-length treatments itself. Very simply put, asynchronous programming allows applications that primarily do I/O to scale quite far, with fewer resources. This is because I/O related tasks generally take waaaay longer than the tasks a CPU must perform, due to the high latency of the I/O device (disk, network, etc). Therefore, we can tell the asynchronous runtime we anticipate running some long I/O task, and that it can literally wait</em> for that task to complete, while another task on the CPU runs</em>, typically on the same thread.</p> </blockquote> Essentially, we need to start a bunch of tasks that send and receive events from configured relays on their own time, and have another task that is aggregating these events together in some way: de-duplicating them, showing them to the user, saving them to disk, etc.</p> So, we need a way to spawn the async I/O task for each relay we want to interact with, and then communicate with that task using nifty little tools called "channels". I'll try to illustrate how this is going to look.</p> Architecture</h4> Relays are implemented as a Rust struct</code> type, with a few properties. First, it must be configured with a WebSocket URL, which is published by a relay operator, and is up to our client to store and use. Internally, a Relay</code> must also create and reference a "channel", that is used by the client to communicate with it asynchronously. These are tokio::sync::mpsc</code></a> channels ("multiple producer, single consumer"</strong>), and aren't exposed directly to the client, but is indirectly through a function interface, as illustrated below. Relays are created in a disconnected</code> state.</p> </div> These "control" messages are used to tell the relay to send us events that match a certain filter (as defined by NIP-01</a>), publish our own events, or disconnect. They must be sent over a channel that the Relay</code> manages since there is an underlying async task that must listen for events from the relay and be responsive.</p> But first, we have to actually connect to the relay with its WebSocket address, and receive those events from it. When we call the Relay::connect()</code> method, we use the tungstenite</code> crate underneath to open a WebSocket connection, and spin up an async task to handle the "up" stream (messages to</em> the relay), and the "down" stream (messages from</em> the relay). These "up" and "down" handles are also part of a Stream</code> construct that is well beyond the scope of this post, but for our purposes, "up" is like a mpsc::Sender</code> and "down" is like a mpsc::Receiver</code>.</p> </div> These relay messages are written over the wire as Message</code> types from the tungstenite</code> crate, and are translated from the nostr::ClientMessage</code> and to nostr::RelayMessage</code> types.</p> Lastly, we have to consider how it looks when there are multiple relays involved, as is expected within a nostr client. When the Relay::connect()</code> method is called, it expects to be given a mpsc::Sender</code> side of a channel, which can be cloned and given to every</em> relay we are interested in. These "producers" will all funnel to one "consumer" (mpsc::Receiver</code>), which acts as our firehose of events coming from all relays we have a connection with. There's nothing required about this, it just makes it easier to deal with in a simple implementation like this one. We can treat all Relay</code> structs as if they were one big set of relays, producing a single stream of events.</p> </div> As far as technical implementation details, there's a lot left to go over here. I think the best way to think about this is you have an async task ("thread") driving the inbound/outbound connection with the WebSocket relay itself, and another, at the client level, that is driving the state of the Relay</code> struct, and that is why we need to use async channels behind Arc<Mutex<...>></code> primitives, so they can be safely cloned and shared throughout the client as necessary. The Relay</code> struct is a effectively just a handle over a set of common data structures, making the initial connection and shuffling data between this async task boundary.</p> With that, we have a very</em> simple nostr client interacting with relays! Here is some sample output that just shows us connected to two major public relays, sending a filter for all kind 1</code> events after the current timestamp. When the user hits Ctrl-C, we disconnect from each relay and shutdown.</p> $</span> RUST_LOG=info cargo run </span> </span>Compiling</span> roostr v0.1.0 (/var/home/nickmonad/code/nostr/roostr) </span> </span>Finished</span> dev </span>[</span>unoptimized + debuginfo</span>]</span> target(s) </span>in</span> 3.07s </span> </span>Running </span>`</span>target/debug/roostr</span>` </span>[2023-08-26T19:59:28Z</span> WARN roostr] relay sent non-event message: EndOfStoredEvents(SubscriptionId("</span>51102577c2f141aa2a06a10d3c2106b5</span>")) </span>[2023-08-26T19:59:28Z</span> WARN roostr] relay sent non-event message: EndOfStoredEvents(SubscriptionId("</span>5854bf7126a9337f9c35ea55dfdd5227</span>")) </span>[2023-08-26T19:59:43Z</span> INFO roostr] EventId(0x078495389530eff3f78e86dcb14095f4c10d0bc80e9b1f5f0fa9bdab7c8a3c45) </span>[2023-08-26T19:59:45Z</span> INFO roostr] EventId(0x48627557bcac6d61d35946a74e5f3cf63a1057a0852b17f22d45bf530eaab8a3) </span>[2023-08-26T19:59:46Z</span> INFO roostr] EventId(0xe5954fe675db03fc5f0a1b4ea5d19f8de6fbd2cbf4be670fbd145652387d5136) </span>[2023-08-26T19:59:49Z</span> INFO roostr] EventId(0xfa9d99dc2e1a1e3c7c61dbb26d3929d1c0f82ec513d86403eb1790bcd6d1c25e) </span>[2023-08-26T19:59:50Z</span> INFO roostr] EventId(0xf2fe94cf82fb3d6dc39811320d43a9cbd0e1eaeb04ff7fb0a03ddea983a4ec21) </span>[2023-08-26T19:59:50Z</span> INFO roostr] EventId(0xf2fe94cf82fb3d6dc39811320d43a9cbd0e1eaeb04ff7fb0a03ddea983a4ec21) </span>[2023-08-26T19:59:50Z</span> INFO roostr] EventId(0xe4410e2d3714de65f21aa494ec89fb9e38ec69c05402143c5395cfe0df4e81fb) </span>[2023-08-26T19:59:53Z</span> INFO roostr] EventId(0x14b7f5f38998a93bb9dda045b72d55a3bab61bde4481b65c415e5503c61eb40c) </span>[2023-08-26T19:59:53Z</span> INFO roostr] EventId(0x953c7bb5884b57b98f54ddf227a8b437c3e061525e29a132c69f7848085df218) </span>[2023-08-26T19:59:55Z</span> INFO roostr] EventId(0x9f4a511bd1f6b02ccb4c4daea54a51b5daef6d78b126219fa234962efc5d8de7) </span>[2023-08-26T20:00:03Z</span> INFO roostr] EventId(0x84fec22e2056751d54c323fa4ff6ac3217d352f6f73eff84779fa3f7e5d48291) </span>[2023-08-26T20:00:07Z</span> INFO roostr] EventId(0xf7119e7250a7f6eaea5058254d850dcb7882428535f1aba1a3e511c5229aa00f) </span>^C[2023-08-26T20:00:11Z</span> WARN roostr] shutting down! </span>[2023-08-26T20:00:11Z</span> WARN roostr::relay] </span>[</span>"</span>wss://relay.damus.io/</span>"</span>]</span> user disconnect </span>[2023-08-26T20:00:11Z</span> WARN roostr::relay] </span>[</span>"</span>wss://nostr-pub.wellorder.net/</span>"</span>]</span> user disconnect </span></code></pre> The inital messages showing EndOfStoredEvents</code> from each configured relay are due to the fact we set the since</code> value on our filter message to be Timestamp::now()</code> and the relay is just saying, "eveything after this will be in real-time."</p> </blockquote> TUI</h3> Now that we have events coming in from the relay, we can start on the real client</em> functionality. As I stated earlier, this can go really deep on implementation, and wide on feature set. I want to keep things really simple, so it won't do much for now.</p> To help set some direction on where to focus next, I think we can break it down like so:</p> First, read a list of public keys to "follow" from a local config file.</li> Using the public keys present in that config, setup and send filters to each relay, asking first for kind 0</code> events associated with the public key(s), giving us "profile" metadata, like the user's preferred display name, followed by kind 1</code> events, the actual text notes, from the past day</strong>. (Arbitrary choice.)</li> Listening on the aggregated event stream, use some kind of mechanism to ensure that events aren't shown twice, in the case where a followed public key is published to more than one of the relays we are interested in. This is quite common, and must be handled by pretty much every client. There are really straightforward ways of handling this, using a list or map, but those come with tradeoffs in performance and memory usage over time. We could use a SQLite based implemention, which I think would be ideal for a client like this, but for now, let's just use a simple in-memory set, and vector (list) of events.</li> Build a simple TUI (terminal user interface) for showing the events and navigating through the list.</li> </ul> This is the simplest possible start I can imagine, while building something at least marginally useful. Many factors of a "real" client won't be considered here, but, it'll be fun to continue adding features over time.</p> Starting up</h4> First, we need to read our config file, and create our primary mpsc</code> channels. One for that relay "firehose" mentioned above, and another for terminal events (user input, resize notifications, etc). The first block here is our example config.toml</code> file.</p> follow </span>= [ </span> "</span>npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkwsyjh6w6</span>", </span># fiatjaf </span> "</span>npub1sg6plzptd64u62a878hep2kev88swjh3tw00gjsfl8f237lmu63q0uf63m</span>", </span># jack </span> "</span>npub1qny3tkh0acurzla8x3zy4nhrjz5zd8l9sy9jys09umwng00manysew95gx</span>", </span># odell </span>] </span> </span>[[relay]] </span>url </span>= "</span>wss://relay.damus.io</span>" </span> </span>[[relay]] </span>url </span>= "</span>wss://nostr-pub.wellorder.net</span>" </span></code></pre> In the long term, the config for roostr</code> would be more related to behavior, and not have hardcoded npubs or relay URLs. These would be requested the first time a user started the client, and stored in a local database. Pubkeys to follow would ideally come from nostr kind:3</code> events, published via our user's pubkey, but I decided not to implement that right now, since we don't have a database yet.</p> </blockquote> #[</span>tokio</span>::</span>main</span>] </span>async </span>fn </span>main</span>() -> anyhow::Result<()> { </span> </span>// send logs to stderr </span> env_logger::builder().</span>target</span>(Target::Stderr).</span>init</span>(); </span> </span>// load config </span> </span>let</span> config = Config::load("</span>config.toml</span>").await?; </span> </span> </span>// event/relay message bus </span> </span>let </span>(tx, </span>mut</span> rx) = mpsc::channel::<RelayMessage>(</span>1024</span>); </span> </span>// events from terminal </span> </span>let </span>(events, </span>mut</span> input) = mpsc::channel::<TermEvent>(</span>10</span>); </span></code></pre> Now, we can initialize our Relay</code> structs, one for each URL we have listed in our configuration.</p> </span>// filter for all kind:0 metadata objects </span> </span>let</span> metadata = Filter::new() </span> .</span>kind</span>(Kind::Metadata) </span> .</span>authors</span>(config.follows.</span>clone</span>()); </span> </span> </span>// filter for all kind:1 notes </span> </span>let</span> notes = Filter::new() </span> .</span>kind</span>(Kind::TextNote) </span> .</span>authors</span>(config.follows.</span>clone</span>()) </span> .</span>since</span>(Timestamp::now().</span>sub</span>(</span>ONE_DAY</span>)); </span>// statically defined `Duration` value </span> </span> </span>// instantiate configured relays </span> </span>let mut</span> relays: Vec<Relay> = vec![]; </span> </span>for</span> relay in config.relays { </span> </span>let</span> r = Relay::new(relay.url.</span>clone</span>()); </span> r.</span>connect</span>(tx.</span>clone</span>()).await?; </span> </span> r.</span>send</span>(ClientMessage::new_req( </span> SubscriptionId::generate(), </span> vec![metadata.</span>clone</span>(), notes.</span>clone</span>()], </span> )) </span> .await?; </span> </span> relays.</span>push</span>(r); </span> } </span></code></pre> Processing and displaying events</h4> Once the client has completed this initial startup, it can run its primary processing loop, reading events from the relays, and user input from the terminal.</p> Since we aren't using SQLite right now as we prove all this out, we'll use an in-memory "database" structure.</p> // Simple "database" implementation, </span>// storing a list of Events, and a map of Metadata objects, accessible via pubkey </span>#[</span>derive</span>(Default)] </span>pub struct </span>Database { </span> </span>pub </span>events</span>: Vec<Event>, </span> </span>pub </span>metadata</span>: HashMap<String, Metadata>, </span>} </span></code></pre> The metadata</code> attribute is important, as we want to show every pubkey's "username" as they have published them under the kind:0</code> event. Since we have a filter setup for those, we can update this struct as a mapping between the followed pubkeys and their metadata. The events</code> attribute is a simple vector of all the kind:1</code> events we receive.</p> Obviously, this isn't really scalable for "real-world" usage. We'd ideally push these to a local SQLite file, and maybe use these in-memory structures for a bounded cache. Just indefinitely growing this vector isn't efficient at all, but again, this is more of a proof-of-concept.</p> </blockquote> Finally, we can run our primary loop. Essentially, the client blocks while it waits for one of two types of events: user input or relay events. For user events, the TUI will be given those events (other than the quit event), and it will update its own state, like which nostr note is selected based on user selection. For relay events, the database is updated. Incoming nostr events are de-duplicated, and then stored in the event list.</p> // setup our "database" and set of "seen" events, for de-duplication </span>let mut</span> database = Database::default(); </span>let mut</span> seen: HashSet<EventId> = HashSet::new(); </span> </span>// setup tui </span>let mut</span> tui = Tui::new()?; </span>tui.</span>events</span>(events); </span>// initial draw </span>tui.</span>draw</span>(&database); </span> </span>// main event loop </span>// as messages/events come in, de-duplicate them </span>// and store them for display on the UI </span>loop </span>{ </span> tokio::select! { </span> </span>// get events from the terminal </span> event = input.</span>recv</span>() => { </span> </span>match</span> event { </span> Some(event) => { </span> </span>if let </span>TermEvent::Key(KeyEvent{ code, .. }) = event { </span> </span>if</span> code == KeyCode::Char('</span>q</span>') { </span> </span>// user quit - disconnect from relays </span> log::warn!("</span>[client] user quit!</span>"); </span> </span>disconnect</span>(relays).await.</span>unwrap</span>(); </span> </span>break</span>; </span> } </span> } </span> </span> </span>// pass event to TUI struct, so it can update its own state </span> tui.</span>update</span>(event, &database); </span> }, </span> _ => {} </span> } </span> } </span> </span> </span>// get events from relay(s) </span> msg = rx.</span>recv</span>() => { </span> </span>match</span> msg { </span> Some(msg) => { </span> </span>match</span> msg { </span> RelayMessage::Event { event, .. } => { </span> </span>match</span> event.kind { </span> Kind::Metadata => { </span> </span>// update metadata map, from pubkey to metadata </span> </span>let</span> metadata = Metadata::from_json(&event.content).</span>unwrap</span>(); </span> database.metadata.</span>insert</span>(event.pubkey.</span>to_string</span>(), metadata); </span> }, </span> Kind::TextNote => { </span> </span>// process note, ignore if we have seen already </span> </span>if </span>!seen.</span>contains</span>(&event.id) { </span> database.events.</span>push</span>(event.</span>as_ref</span>().</span>clone</span>()); </span> seen.</span>insert</span>(event.id); </span> } </span> } </span> _ => {} </span> } </span> }, </span> _ => log::warn!("</span>relay sent non-event message: {:?}</span>", msg) </span> } </span> } </span> None => { </span> log::warn!("</span>all relay senders dropped</span>"); </span> </span>break</span>; </span> } </span> } </span> } </span> } </span> </span> </span>// event(s) processed, draw another "frame" </span> tui.</span>draw</span>(&database); </span>} </span></code></pre> In both cases, after the event is processed, the TUI is re-drawn. In principle, there is some contention here. If there is a delay in processing a relay event, user events will have to wait as they queue from the terminal input thread, potentially causing a lag in the responsiveness. But, in practice, espcially in this case, the relay event processing is so minimal, that it doesn't have an impact. If there were heavier processing involved, the client would likely have to split off that processing onto another async task or thread and signal its completion back to this thread.</p> As for the actual processing requirements and performance of re-drawing the TUI, we don't have to worry about that in practice either, since it's just... outputing text to the terminal.</p> Since this post is already way too long, I'll pass on explaining the actual TUI rendering in detail. Suffice it to say, I chose to use ratatui</a>, the successor to tui-rs</code>. It provides really simple ways to put the terminal in the correct mode it needs to be in, and build up layout components.</p> Demo!</h3> This may not render correctly on mobile.</p> </blockquote>

nickmonad

Working software runs locally

2026-03-30T00:00:00+00:00

I've been thinking a lot about testing recently.

Although, it's kind of a "blessing and a curse" situation. A blessing in the sense that I've had the opportunity to work on some interesting problems, with some very interesting tools. At work, we've been testing a product that does simulation testing and as a result, I've seen some of the most powerful software I've ever seen in my professional career. How is it a curse? Well, testing complex software is... complex. And an increased focus on testing is usually done after a handful of stressful situations.

In any case, this recent focus on testing has reinforced my feeling that all software should be able to run locally, on every developer's machine in the organization, all the time, with minimal friction.

Of course, the software I'm working on can always run on my machine, in the sense that all computers can (theoretically) run all software. What I mean by "run" is more practical and pertinent to testing. I'm talking specifically about the ability to start something locally, run a few commands against it, or throw some predefined requests at it, to see how it behaves. This also includes external dependencies, to a reasonable degree of fidelity.

In my experience, having the ability to do this repeatedly and reliably increases my ability to understand and confidently change the system I'm working on.

As an example of this, I recently found myself trying to debug a configuration issue in a deployed testing environment. My initial instinct was to stay as close to the deployment as possible, in order to be certain I was making the correct changes. After an embarrassing amount of time fumbling around with these settings, I finally remembered that I had a script laying around that could run this component locally. Moving my efforts to my own machine made a huge difference! I didn't have to wait nearly as long for the service to redeploy after a configuration change, and I was able to prove the problem persisted, regardless of the runtime platform. Having this kind of tight feedback loop gave me the confidence to dig more into the code and finally find the bug. Once I had a working hypothesis based on the code, I could validate it within seconds.

I've come across a surprising number of situations where existing tooling in a codebase doesn't support this. Or, you can tell that it did at some point, but the specification for it has rotted to the point of being useless. At best, the service can be compiled and maybe a handful of integration tests can run. I can probably even deploy it! But, I can't run it in a mock environment locally. ^{1</a>}

It's interesting to me how this happens, because I don't think most systems start out this way. Running things locally is a critical part of the early development cycle. I think that over time as more external dependencies are added, and especially as the CI/CD pipeline matures, the ability to run a complex system locally moves further out of reach, mostly without even realizing it.

One reason I think this tends to happen is pressure to move quickly. If a team is under the gun to ship fast and there is infrastructure in place to do some quick validation in the deployed environment, it's easy to forget about the local experience.

Perhaps though, there's a sense that the local experience doesn't actually matter all that much, because true validation comes from production deployment. Charity Majors argues the point about validation in her (now famous?) article "I test in prod"</a>. I don't think she's arguing against running things locally (the word "local" isn't even in the article), but if the idea we should test in prod is taken to a sort of extreme, I can see how it would be easy to come to the conclusion that production is the only thing that matters, at the cost of other means of validation. I would argue that both matter: the ability to test locally, and test in production. 2</a>

Another reason I think local tooling degrades is the perception that it's not actually possible to bring up the system locally, in a way that a simulated "end-to-end" request could be satisfied. For the most part, I haven't ever found this to be true. There are tons of tools that make these setups possible: public docker images, docker compose, LocalStack, or straight up writing a custom fake or mock. All are viable options. 3</a>

My general perspective is that if a tool to mock/simulate an external dependency doesn't already exist and is accessible, it's at least worth considering building your own. This can even just be a handful of endpoints your specific system actually needs. Recently, I needed to mock an internal API layer so I could satisfy the system I was actually concerned about testing. All I needed to mock was 5 or 6 endpoints, from a system that actually has dozens. Finding a minimal footprint and starting there can go a long way. In this case, the mock was just a Python server passing some JSON back and forth, with a little bit of internal state.

Developing a habit and practice of this sets up for a lot of really interesting testing techniques way beyond manual validation. Simulation testing is one of those techniques, and it feels like a super power once you get the hang of it. Pierre Zemb goes into more detail on this in "Why Fakes Beat Mocks and Testcontainers"</a>.4</a>

At some point though, faking/mocking can get out of control. I understand the desire to not feel like we're maintaining a whole other system, with all of its complications and quirks. If that starts to happen, it might be worth thinking about how to bring in that other system you're mocking, and run it alongside your system. I think this is actually the preferred option. Especially if that other system's external dependencies could be mocked with a smaller footprint.

In the worst case, build what you can. It's OK to scope something down. A little bit goes a long way here and there's always some creativity involved. We make the perfect the enemy of the good far too often.

I want to be careful in setting the expectation here. I don't think I should be able to run a system at scale on my laptop. I'm not going to run Google's primary search infrastructure and recreate a production environment that serves billions of users. But, I do hope I would be able to at least run a minimally working version of it (or some critical component of it), in a way that approximates useful results. If I change some aspect of the code, I should be able to see the impact of that change.

Just like we consider failing unit tests to be a blocker for getting to production, I think we need to start considering a broken local setup to be a blocker. Certainly not in the absolute sense. If you need to ship a fix to production right now, please, do it. But, take the time to come back and tidy up. Under normal working conditions, we should not neglect the workspace right in front of us.

I have also come across situations where even compiling locally is too much to ask. At some point, the standard advice becomes "just push it to CI". This is probably the worst situation to be in. ↩</a> </li>

I agree with a lot of the conclusions in that article. And, at the time of this writing, Charity's article is nearly 7 years old. Since then, there has been a lot of development in deterministic simulation testing (DST), which can actually bring the chaos of a production environment to an environment where there's truly no risk. (See Antithesis</a>) Also, DST tends to be far more aggressive than any real production environment. I still think her fundamental conclusions are sound, but new tooling improves the pre-prod testing story significantly. Ensuring a system has strong and stable tooling for local testing actually sets it up nicely for simulation testing, which is a big reason why I'm advocating for it here. ↩</a> </li>

Yes, I am aware that LocalStack has done some weird things recently, with regards to access and pricing. I don't quite know what to make of it, but I remain hopeful that good tooling continues to be developed and is accessible to the broadest possible audience. ↩</a> </li>

Pierre specifically uses the term "fake" instead of "mock" to describe this technique. I think I would prefer the term "simulated", since it's so useful in the context of simulation, but "fake" works as well. The term mock might have some baggage associated with it, depending on who you're talking to. Whatever the term is for what I'm describing here, the main thing is to be on the same page with your colleagues. ↩</a> </li> </ol> </section>

Static Allocation with Zig

2025-12-29T00:00:00+00:00

Over the past few months I've been chipping away at a small Redis-compatible key/value server called kv</code></a>. The goal is to have something (mostly) production-ready, while implementing only a small subset of commands. The world doesn't necessarily need another key/value store, I'm just interested in implementing it in Zig and learning about some new (to me) techniques for systems programming.
One of those techniques is static memory allocation during initialization. The idea here is that all memory is requested and allocated from the OS at startup, and held until termination. I first heard about this while learning aboutTigerBeetle</a>, and they reference it explicitly in their development style guide dubbed "TigerStyle".
All memory must be statically allocated at startup. No memory may be dynamically allocated (or freed and reallocated) after initialization. This avoids unpredictable behavior that can significantly affect performance, and avoids use-after-free. As a second-order effect, it is our experience that this also makes for more efficient, simpler designs that are more performant and easier to maintain and reason about, compared to designs that do not consider all possible memory usage patterns upfront as part of the design. TigerStyle</a> </blockquote> Although, this isn't as straightforward as it might sound at first. The first question that comes to mind might be: "How much memory do I allocate?" Of course, the answer depends on the system. If we're writing a server, how many concurrent connections do we allow? How much space is each connection allowed to work with? How much data do we expect to process at any given time? Are there limits in response size? Do we need all the data at once, or can it streamed in some fashion? These are all questions that depend on the nature of the system and the context in which it will operate. I believe that going through the exercise of answering these questions is ultimately a good thing, as it seems to have a strong possibility of resulting in more stable systems, and forces us to understand the nature of our program at a deeper level.1</a> On the language front, I feel like Zig is currently the best option out there for doing this with relative ease, considering its design choices around explicit memory allocation and the std.mem.Allocator</code> interface, which allows the standard library to ship with a variety of different allocators. Let's take a look at how we can manage static allocation in kv</code>, considering three areas of request handling in sequence: connection handling, command parsing, and key/value storage. A lot of this is pretty new to me, and I'm still wrestling with all these concepts. (And learning Zig!) I'm sure there are better ways of handling this stuff. I'm presenting this as one possible implementation completed as a learning exercise. I'll speak more about the trade-offs and where I think it can go further at the end of this post. </blockquote> Connection Handling</h2> The first thing we have to consider is how data comes into the system, which we'll maintain through the concept of a Connection</code>. A connection represents the communication to a particular client that wants to access the key/value store. Since we're using io_uring</code> for asynchronous I/O, we have to keep some information around through the life-cycle of a request, so the kernel can use it. The space for that information is what we'll statically allocate and re-use across different connections as they come and go. const Connection = struct { completion: Completion = undefined, client: posix.socket_t = undefined, recv_buffer: *ByteArray, send_buffer: *ByteArray, }; </code></pre> Connections also must maintain something called a "completion". This detail is related to integration with io_uring</code>, the full details of which are outside the scope of this post. There are some good resources here</a> and here</a>. I also took some inspiration from TigerBeetle's IO module</a>. </blockquote> During initialization, we create three pools: one for the Connection structs themselves, one for receive buffers (requests), and one for send buffers (responses). When a request comes in to the server, a Connection is pulled from a std.heap.MemoryPool</code>, and then two buffers are associated with that Connection</code>. The buffers are implemented as ByteArray</code> structs, which are in turn allocated as part of a ByteArrayPool</code>. The ByteArrayPool</code> is custom and uses a free list</a> to keep track of which buffers are available to reserve for a new connection. const ConnectionPool = struct { const Pool = std.heap.MemoryPoolExtra(Connection, .{ .growable = false }); recv_buffers: ByteArrayPool, send_buffers: ByteArrayPool, connections: Pool, fn init( config: Config, gpa: std.mem.Allocator, ) !ConnectionPool { const allocation = config.allocation(); const recv_size = allocation.connection_recv_size; const send_size = allocation.connection_send_size; const pool = try Pool.initPreheated(gpa, config.connections_max); const recv_buffers = try ByteArrayPool.init(gpa, config.connections_max, recv_size); const send_buffers = try ByteArrayPool.init(gpa, config.connections_max, send_size); return .{ .recv_buffers = recv_buffers, .send_buffers = send_buffers, .connections = pool, }; } ... }; </code></pre> At runtime, connections are created and destroyed (marked as available) using these pools and no actual allocation needs to happen. If no Connection</code> is available in the pool, the request is rejected and the client will have to try again. This does mean that the server must be configured with an upper limit on the number of connections. Each connection must also have a limit on how much data it can receive and send. At first this might seem limiting, but in practice, it creates a more robust system. Databases in particular will enforce a limit on the number of active connections for that exact reason! For a backend, networked system like kv</code>, I would say something like 1000 active connections is a pretty reasonable limit. For a public facing system you'd likely want more. Of course, this should all be configurable by the user. The Config</code> struct given to the ConnectionPool</code> represents these user-configured options. Note that the Config</code> struct has a method .allocation()</code> which is computed after the options have been set. In this case, the connection_recv_size</code> and connection_send_size</code> depend on other options, such as config.key_count</code> and config.key_size_max</code>. We'll revisit those later. Now that data can get into the system, the next step is to parse out Redis commands. Command Parsing</h2> In an attempt to be compatible with Redis (at least a very small subset of it), kv</code> has to parse incoming commands following the Redis serialization protocol</a> ("RESP") format. Here's an example of an incoming GET key</code> command. *2\r\n$3\r\nGET\r\n$3\r\nkey\r\n </code></pre> I won't go into detail on how these commands are structured, the RESP document will do a much better job there. Basically, what we're looking at is "Here's an array with 2 elements. The first element has 3 characters, with the content GET</code> and the second element has 3 characters, with the content key</code>." In order to parse this command, we need to look at the buffer that contains the request data, create some kind of iterator over that buffer, and split each entry on the CRLF \r\n</code> byte sequence. Here's the signature for parse</code>, the function that does just that. pub fn parse(config: Config, alloc: std.mem.Allocator, buf: []const u8) !Command </code></pre> The allocator is used to create some book-keeping structure as we parse through the command. We need to create a list of []const u8</code> slices that points into the whole buffer and then is given to a command's parse()</code> function, once we know the command. This has the benefit of being a "zero copy" approach to parsing. No request data needs to be copied, only pointed to. Zig's std.heap.FixedBufferAllocator</code> is perfect for this kind of operation. During initialization, we ask for buffer space from a general purpose allocator, and pass it to the FixedBufferAllocator</code>. This allocator works as "bump" allocator, where each internal allocation happens in a linear fashion, up to the amount of available space. The trade-off here is that memory allocated within the fixed buffer can't be free'd directly. Instead, the entire buffer is reset after use, which simply resets an index back to 0</code>. (Just about as cheap as an operation can get!) Since our server is single-threaded2</a> and processes one request at a time, we can re-use this FixedBufferAllocator</code> across every request. After the request is processed, the response is copied to a Writer</code> object backed by the connection's send</code> buffer and the FixedBufferAllocator</code> is reset for the next request. Knowing how much space to give the FixedBufferAllocator</code> depends again on our system configuration. We need space for the ArrayList</code> of parsed command items, and space for any copied list items that are written back as a response during command execution. Parsing must be able to support the largest possible command (a list PUSH</code> of maximum size/length) and copying has to support the largest possible response (again, a maximally sized list). Copying has the extra consideration that we have to actually store the copied list items, which are duplicated when read from the key/value store. During parsing, we just need to keep slices into the request buffer. For the copied items, we need to keep a list of slices that point to the items, and the items themselves. As long as we give the FixedBufferAllocator</code> space, we can use it for all these (sub-)allocations. pub const Runner = struct { config: Config, fba: std.heap.FixedBufferAllocator, kv: *Store, pub fn init(config: Config, gpa: std.mem.Allocator, kv: *Store) !Runner { const L = config.list_length_max; const V = config.val_size_max; // ArrayList([]const u8) of largest possible command. // "[L/R]PUSH list item1 item2 ... itemL" const parse_cap = (1 + 1 + L); const parse_size: u64 = (parse_cap * @sizeOf([]const u8)); // ArrayList([]const u8) pointing to duplicated values. const copy_size = (L * @sizeOf([]const u8)); const copy_data = (L * V); const fba_size: u64 = parse_size + copy_size + copy_data; const buffer = try gpa.alloc(u8, fba_size); const fba = std.heap.FixedBufferAllocator.init(buffer); return .{ .config = config, .fba = fba, .kv = kv, }; } ... }; </code></pre> The underlying Store</code> will use the FixedBufferAllocator</code> to allocate an ArrayList</code> of fixed capacity (determined by config.list_length_max</code>) and then use the remaining space in the allocator for the copied data. Hopefully all is clear so far! Now we can move on to the core of the system: key/value storage. Key/Value Storage</h2> Perhaps obviously, the fundamental data structure in kv</code> is a hash map, used to associate user provided keys with user provided values. Without looking too closely at the standard library, if you grab one of the provided hash map implementations, it will accept a std.mem.Allocator</code> and hold onto the allocator for the lifetime of the map. When a key/value pair is added to the map, it will use that same allocator and request the appropriate amount of memory to store that data. This won't work for our case though, since we need to control allocation prior to adding any data to the map. Fortunately, Zig also provides an "unmanaged" version of a hash map. Generally, these unmanaged versions of data structures in the standard library mean that an allocator is not held by the structure itself. It's up to us to provide that allocator when needed. A cool trick we can play with an unmanaged map is ask it to ensure it has enough capacity up front, and then "assume" that capacity during runtime when adding data to it. The hashing and internal details are still handled by the map. var map: std.StringHashMapUnmanaged(Value) = .empty; try map.ensureTotalCapacity(gpa, capacity); </code></pre> The ensure</code> operation can fail with error.OutOfMemory</code>, which is OK during initialization. But, assuming this succeeds, we no longer need to pass an allocator when we store data in the map. store.map.putAssumeCapacity(key, value); </code></pre> This could in theory fail, in which case there would an assertion failure. It's ultimately up to us to check against the map's available capacity before calling this function. But, again, no allocation is required. Since the map itself doesn't do any allocation at runtime, we have to provide space for incoming keys and values. We'll reuse the same ByteArrayPool</code> implementation that we used for connection buffers. Basically, we have a big space allocated for keys and values and the hash map just maintains an association of pointers from keys to values. The key/value data isn't literally stored "in the map." The allocation that happens in ensureTotalCapacity</code> is for the internal book-keeping structure of the map, not for the user data. Navigating the map</h3> At the highest level, the primary challenge with storing keys and values in a statically allocated map is that we could get poor utilization of the allocated space, especially when we need to support keys pointed at lists as values. To illustrate this, let's say our map is configured to allocate space for 5 keys and 5 values. If each key maps to one value, we get perfect utilization. At the other extreme, if one key maps to a value containing a list of 5 elements, we have to use all the allocated value space for this one key, preventing other keys from using any value space, causing the map to be "biased". The store wouldn't be able to hold any more key/value pairs, even though there is allocated memory "on the table." Basically, the only way to mitigate this is to make sure there's enough allocated space for every key to hold a list of maximum size. This definitely inflates the amount of space we have to allocate, but the alternative is a system that doesn't support its configured properties. Every key must be able to store a list of maximum size, even if they don't during actual use. Another issue with static allocation in the context of a map is dealing with map deletions. Our std.StringHashMapUnmanaged</code> structure uses open-addressing and linear probing to place keys in the map when hash collisions occur. Deletions are tricky because they can break the map's ability to know if a key is actually present in the map. To handle this, a "tombstone" technique is used to mark a space as logically (but not physically) deleted in order to preserve accurate lookups. There's a lot more to figure out here, but it's my understanding that a map will have to periodically rehash the keys in order to reclaim space if too many tombstones pile up. When this occurs is still a bit of mystery to me. If it occurs when the map needs to grow to accommodate more key/value pairs, we'll never actually trigger that condition in a static context. If it occurs at some other point, based on number of keys compared to capacity, perhaps that could work. Or maybe, it's up to us to call rehash()</code> whenever it appears there is no space left, and try the operation again. All of this considered, I think a custom map implementation is more appropriate for the context of static allocation. This current implementation proves the concept, but definitely leaves room for improvement! Revisiting allocation size</h2> Now that we have a method for statically allocating space for these three components (connections, parsing, and storage), we can finally answer the first question: How much space do we allocate? In this current iteration of kv</code>, the answer can really only be determined after the fact, once configuration has been set and all the allocations have been made. There are five options that can be configured by the user, and two derived properties based on those options. pub const Config = struct { /// Allocation is a calculated set of values (in bytes), based on the given configuration. /// This informs static allocation requested at initialization. pub const Allocation = struct { connection_recv_size: u64, connection_send_size: u64, }; /// Maximum number of concurrent connections. connections_max: u32, /// Key count is the number of possible keys we can store. /// Internally, the store will allocate (key_count * list_length_max) number /// of values, such that each key could support the maximum number of list elements. key_count: u32, /// The maximum allowable key size in bytes. key_size_max: u32, /// The maximum allowable value size in bytes. val_size_max: u32, /// The maximum allowable length for a list as a value. list_length_max: u32, pub fn allocation(config: Config) Allocation { // ... calculate recv and send size .... return .{ .connection_recv_size = connection_recv_size, .connection_send_size = connection_send_size, }; } }; </code></pre> The connection_recv_size</code> and connection_send_size</code> properties of Allocation</code> depend on some details of the RESP protocol, but is mostly informed by our user configuration. In the interest of wrapping this post up, I'll gloss over those details, and encourage you to check out src/config.zig</code></a>. This Config</code> struct doesn't directly specify every aspect of allocation, but it does provide the basis for it. Something not listed in the Config</code> struct directly is the "list item pool", part of the key/value Store</code> struct. When keys point to lists as values, there is a linked list backing that value in the hash map, and we need a pool of structs to assist in the construction and iteration of that linked list. With some reasonable configuration options set, let's see just how much memory we allocate! $ zig build run config connections_max = 1000 key_count = 1000 key_size_max = 1024 val_size_max = 4096 list_length_max = 50 allocation connection_recv_size = 206299 connection_send_size = 205255 map capacity = 2048, map size = 0, available = 1638 total_requested_bytes = 748213015 ready! </code></pre> Everything here is measured in bytes, so we're looking at approximately 750 MB</code> of memory for the given configuration. total_requested_bytes</code> is a feature of Zig's std.heap.DebugAllocator</code>. The exact number of bytes will be different on each run, although it will hover around that value. I think the reason for this is how Zig requests pages of memory from the OS. It won't always be the same and the OS is very likely doing some fancy book-keeping of its own. If you play around with the configuration options and see how total_requested_bytes</code> changes, it might be surprising just how much memory is allocated up-front, before any of it is actually used! For example, if we double val_size_max</code> to 8192</code> and list_length_max</code> to 100</code>, we're looking at about 2.8 GB</code> of allocated memory. In the context of modern servers, this isn't a lot, but it can quickly grow as we adjust these parameters. Should we be asking ourselves: Is this inefficient? What if we don't use all that memory? Like all good engineering decisions, we have to consider them in the context of the problem we're trying to solve, and the guarantees we expect from our systems. With this design, ensuring that each request and each key/value pair can utilize the maximum configured space, seems like a worthy trade-off to make. Final thoughts</h2> Like most projects, this one took a lot longer than I expected! Trying to incorporate both io_uring</code> and static allocation was something I had never done before, but I'm pretty happy with the result. I'm looking forward to improving the internal hash map to better fit a static context, consider alternative allocator implementations to improve memory utilization, and incorporate fuzz testing to find the limits of the system. Checkout the code on GitHub</a>! Notes</h3> At the risk of stating the obvious, these limits can (and likely should) be configured at runtime by the user. These aren't values that have to be set at compile time and enforced upon all users in every context, although some might be. Again, it depends on which part of the system is using the memory. The point is that once the program starts it will allocate memory, but after that, it does not. ↩</a> </li> Going with a single-threaded design simplifies a lot! Even though processing in kv</code> is single-threaded, it still enjoys the benefits of I/O concurrency via io_uring</code>. The kernel handles writing responses back out to clients and waiting for that operation to complete, so we don't have to worry (as much) about slow clients. ↩</a> </li> </ol> </section>
Advent of Performance: Go Edition 2024-06-03T00:00:00+00:00 Every so often I like to spend some time working on Advent of Code</a> problems when I need a break from my primary projects. It's also a great way to learn a new language, or sharpen skills in one I already know. Another fun angle is to spend time making solutions fast. Usually, they are "fast enough" for the purposes of solving the problem and moving on, just to get the gist of how to think algorithmically. But, in some cases, there is an obvious slow down when going from part 1 to part 2 of a problem statement, which usually means there's a faster alternative. Day 4</a> from the 2015 problem set provided exactly that opportunity. Mining AdventCoin</h2> The problem statement for this day is essentially a simplified example of how bitcoin mining</a> works, by finding a hash collision. Given some input string (e.g. yzbqklnj</code>), the goal is to find some "nonce" integer, that when appended to the input string and hashed (using MD5), the resulting hash will have some number of leading zeros. For example, If your secret key is abcdef</code>, the answer is 609043</code>, because the MD5 hash of abcdef609043</code> starts with five zeroes (000001dbbfa...</code>), and it is the lowest such number to do so. </blockquote> Hashes can't be "reversed", meaning that the only way to do this is to try a bunch of nonces until we find a hash with the required number of leading zeros. Fortunately, Go's standard crypto</code> package gives us a function to compute an MD5 hash of a byte array, so we can do this pretty simply. func naive(input []byte, prefix string) string { seed := strings.TrimSpace(string(input)) nonce := 1 for { preimage := []byte(fmt.Sprintf("%s%d", seed, nonce)) hash := md5.Sum(preimage) if check(hash, prefix) { break // found nonce } nonce += 1 } return fmt.Sprintf("%d", nonce) } </code></pre> The check</code> function just formats the resulting hash in hex and looks at the prefix. We've separated it out so we can change it later... func check(hash [16]byte, prefix string) bool { hex := fmt.Sprintf("%x", hash) return strings.HasPrefix(hex, prefix) } </code></pre> Easy enough! We've solved Part 1. For part 2, we just have to run the same loop, but instead of looking for a hash with 5 leading zeros, we have to find one with 6 leading zeros. Updating our input and running it again... Oh. Well. It definitely takes longer. Noticeably longer. In these situations, you always wonder if something else went wrong and you've introduced an infinite loop. In this case, we definitely get correct output, but it's just slow. $ go build -o day4 solutions/day4/main.go # find hash with 5 leading zeros (00000) $ ./day4 -part 1 input/day4 282749 time: 134.816113ms # find hash with 6 leading zeros (000000) $ ./day4 -part 2 input/day4 9962624 time: 4.029076709s </code></pre> Technically, nothing is "wrong" with our algorithm here. It's just dealing with a much larger space of possibilities. Generally speaking, the more specific your target hash is, the longer it's going to take, effectively trying random nonce values until you find the needle in a ridiculously large haystack. Of course, Go is known for making concurrency relatively easy, so let's just spin up a goroutine for each CPU core and try as many different nonces as we can simultaneously. Originally, I had thought I would have runtime.NumCPU()</code> goroutines as "workers" crunching on our hash function, with another goroutine that would act as a "ticket counter", giving out the next nonce over a channel when a worker needed a new one after failing to find the desired hash prefix. Although, it didn't actually work. At least not in the way I expected. We got the right number, but it took even longer than the naive solution when looking for 6 leading zeros. I figured that the overhead of the coordination between all the goroutines was just too much to be worth the parallel effort. The hashing function is so quick that it was likely the workers were putting too much contention on the nonce channel, too quickly, causing a lot of runtime context switching and blocking. Actually making it fast</h2> I knew that parallelization was definitely the way to go here because each hashing function is completely independent of the other. No state needs to be carried over between testing nonce 32535</code> and nonce 871279</code>. Ultimately, that was the key insight needed to make this work. If we consider each worker in isolation, we can define a simple formula for determining the next nonce in its sequence to test. Just make it count upwards, skipping by some fixed amount each iteration. In this case, the number of goroutines. This way, each worker tests a unique sequence of integers, but doesn't overlap with any other worker. For simplicity, let's assume we have 4 workers. If they each count by 4, starting from a different place, they'll never overlap. worker 0 -> 0, 4, 8, 12, ... worker 1 -> 1, 5, 9, 13, ... worker 2 -> 2, 6, 10, 14, ... worker 3 -> 3, 7, 11, 15, ... </code></pre> Each worker can calculate this sequence with 2 constants, the "base" (starting point), and "N", the number of workers. nonce = base + (i * N) </code></pre> If i</code> increases indefinitely until we either find a solution, or are told to stop looking, we can parallelize this and eliminate virtually all coordination between each worker, until it needs to notify us of a solution. func optimized(input []byte, prefix string) string { seed := strings.TrimSpace(string(input)) numWorkers := runtime.NumCPU() // wait group ensures all goroutines clean up after cancellation var wg sync.WaitGroup // cancellable context is cancelled once a solution is found ctx, cancel := context.WithCancel(context.Background()) // given to each worker solution := make(chan int, 1) // spawn a worker for each CPU core for b := 0; b < numWorkers; b++ { wg.Add(1) go func(base, n int) { defer wg.Done() i := 0 for { select { case <-ctx.Done(): return default: nonce := base + (i * n) // independently calculate next nonce in sequence preimage := []byte(fmt.Sprintf("%s%d", seed, nonce)) hash := md5.Sum(preimage) if check(hash, prefix) { solution <- nonce return } i = i + 1 } } }(b, numWorkers) } winner := <-solution cancel() wg.Wait() return fmt.Sprintf("%d", winner) } </code></pre> And the result... $ ./day4 -part 2 input/day4 9962624 time: 3.976446064s $ ./day4 -part 2 -optimized input/day4 9962624 time: 699.66703ms </code></pre> Boom. Huge difference! This solution actually helps improve performance in part 1 as well. $ ./day4 -part 1 input/day4 282749 time: 119.919216ms $ ./day4 -part 1 -optimized input/day4 282749 time: 22.183944ms </code></pre> One more thing!</h2> Remember the check</code> function above? It encodes the resulting MD5 hash into hexadecimal and looks at that string to see if the nonce results in a hash with the desired number of leading zeros. Primarily leaning on fmt.Sprintf()</code> and the hex formatting directive, it requires allocating heap memory to build the hex string, which must be done on every iteration of the loop. Since all we really need to do is check the leading byte values of the hash, we can perform that check without any heap allocation at all. // Check if the given MD5 hash has the given leading number of zeros. func check(hash [16]byte, leading int) bool { numBytes := leading / 2 for i := 0; i < numBytes; i++ { if hash[i] != 0x00 { return false } } if leading%2 != 0 { // looking for odd number of zeros... // since each hex character represents 4 bits, we have to use a bit shift to check our last byte // in the hash if the desired number of leading zeros is odd. For example, if we are looking for // `000` (odd number of zeros), the byte sequence _could_ be `0x00 0x01`, or `0x00 0x02`, etc... // In this case, we bit shift the last byte to the right by 4, and check if that result is 0, // ignoring 4 least significant bits. // last index in hash to check is equal to `numBytes` because of the integer division above. // for example, if leading == 5, numBytes == 2 (due to integer division), and we need to // check the 3rd byte in the sequence (i.e. index 2) return (hash[numBytes] >> 4) == 0x00 } return true } </code></pre> Because a single digit of a hex value actually represents 4 bits, looking for 6 leading zeros in the resulting hash means we look at the first 3 bytes. (0x000000</code> split on each byte looks like 0x00 0x00 0x00</code>.) If we need to check for an odd number of leading zeros (say, 5 like in part 1), we can lean on some integer division and a modulo check to ensure we check the last byte in the sequence correctly. As we said, that last 0 to check only represents 4 bits, so we can use a bit shift to ignore the 4 least significant bits of the byte, and check that result against the 0x00</code> byte value. Assuming we get through those checks, we've found a solution! Looking at the run time, this updated version of check</code> improves performance across the board, in both the naive solution, and optimized solution that uses parallelization! $ ./day4 -part 1 input/day4 282749 time: 55.216603ms $ ./day4 -part 2 input/day4 9962624 time: 1.818860088s </code></pre> $ ./day4 -part 1 -optimized input/day4 282749 time: 11.829511ms $ ./day4 -part 2 -optimized input/day4 9962624 time: 319.841772ms </code></pre> Summary</h2> Here's a table summarizing the performance improvements for both part 1 and part 2. In each case, I ran the solutions 10 times and took the average of those reported run times, rounded to 2 decimal places. ("no alloc" means the version of check</code> that doesn't allocate a string and encode to hex) Solution</th> Version</th> Run Time</th> Speedup</th></tr></thead> Part 1</td> naive</code></td> 118.16 ms</code></td> 1.0x</code></td></tr> </td> naive + no alloc</code></td> 53.2 ms</code></td> 2.2x</code></td></tr> </td> optimized</code></td> 20.04 ms</code></td> 5.9x</code></td></tr> </td> optimized + no alloc</code></td> 10.2 ms</code></td> 11.6x</code></td></tr> Part 2</td> naive</code></td> 4.01 s</code></td> 1.0x</code></td></tr> </td> naive + no alloc</code></td> 1.81 s</code></td> 2.2x</code></td></tr> </td> optimized</code></td> 778.41 ms</code></td> 5.2x</code></td></tr> </td> optimized + no alloc</code></td> 358.53 ms</code></td> 11.2x</code></td></tr> </tbody></table> Environment</h4> I ran these tests using Go version go1.22.3 linux/amd64</code>, on a ThinkPad X1 Extreme Gen 4i, rocking an 11th Gen Intel i7-11800H (16) @ 4.600GHz (reported by neofetch</code>) All code for this and other solutions can be found on GitHub</a> "I think you might be a scam" - A Lesson in Customer Discovery 2024-03-20T00:00:00+00:00 Learning how to talk to customers has been a fun aspect of building a business. Although, it is by no means "easy." Like many engineers, I struggle with this, because what we really know how to do is write code, and we think if we just buckle down and knock it out quickly, we could validate our idea that way. That might work for some product ideas, but I'm becoming increasingly convinced that "build first" approaches are a great way to waste a bunch of time, effort, and money towards building a product nobody cares about. I'm not alone in this way of thinking, and it certainly wasn't my idea. My mentor at the startup incubator I'm currently in encouraged me to stop building and actually talk to some customers. I definitely wasn't thrilled to hear that at first. I thought I had a strong sense of what I should build, but he rightfully challenged me on those assumptions. The Mom Test</h2> I sighed and took a step back, and started to learn how to approach customer discovery. My mentor recommended The Mom Test</a>, and now I couldn't agree more. It's a concise little book that gives you that real, practical advice on how to approach customer discovery, with a particular emphasis on not biasing the prospect. As Rob Fitzpatrick outlines his approach, he details a particular mistake he finds a lot of entrepreneurs making, where they'll pitch an idea and immediately ask "What do you think? Is it a good idea?" This leads to all sorts of psychological issues surrounding human behavior. The basic issue is that, nobody wants to hurt your feelings. When they are really thinking "meh, I'm not sure why I would use that." Or, "I really don't want to switch products right now.", they are telling you "Yeah sounds great! Let me know when it launches." You walk away feeling like a business genius, but in reality, they just told you what they thought you wanted to hear. This is particularly the case when the person you are pitching your idea to is your mom. But friends and colleagues are guilty of the same thing. So, how do we address that problem? Just ask people questions about their lives and jobs. You can start out pretty broad, but it's OK to narrow focus around the industry and problem you are interested in. The idea is that by having casual conversations, you let your potential customer tell you what their problems actually are, not what you assume them to be. By hearing the same problems come up across multiple customer calls (the amount varies), you can build way more confidence in your solution as something people will actually buy. I can't do the entire book justice in this post, so if this idea sounds interesting to you, definitely pick up a copy and read it. (Not a paid promotion, I really just think this book is incredible.) I took a lot of the advice and strategy of the book to heart and set out on finding contacts. I was able to lean on my network for this a little bit, but I've also had to do some cold outreach via email. Waiting for my network to follow up was just taking too long. My product revolves around the volunteering space and fortunately, the space is huge. There is no shortage of non-profit organizations. I was able to email 7 solid prospects in one morning just by looking at my city's chamber of commerce website. What I didn't fully take into consideration was how my language might sound to some of those prospects. One of them in particular responded in a way I never expected. Bitter cold outreach</h2> I actually have no real idea how to approach cold calling, and in what was perhaps an overly enthusiastic email power session one Friday morning, I sent this out to a prospective customer. Hello [redacted], My name is Nick and I'm part of a startup program at Iowa State, where I'm doing research on volunteer management and organization. I came across [redacted; org name] and am interested in learning more about your organization and volunteer program - what works for you, and maybe some of the challenges. It seems like [redacted; org name] has a wide range of roles volunteers can fill! Would a member of your team have 20 or 30 minutes to chat with me over the phone sometime next week? I have nothing to sell, I'm just interested in learning more about how your volunteer program operates. I really appreciate your time! Thank you, Nick </blockquote> If you happen to be an expert in cold calling and outreach, I'm sure there are aspects of this email you may find pretty funny. I acknowledge that and I'm looking into how to improve it. In the meantime, please bear with me. I'm an engineer. I fired off that email and hoped to get a response the following week. Sure enough, it came through. Hello Nick, Thank you for reaching out to us. Could you provide me with a little more details of what information you're looking to gather? Let me know and I would be happy to help if I can. Thanks and make it a great day. [redacted; name] Volunteer Services Coordinator </blockquote> Fair enough. I could see how my initial message might not be clear to somebody, and they just want to be protective of their time. No problem. Hi [redacted], Thank you for your response! I'm looking to learn more about your volunteer program, in terms of how it operates. Thinking about the "lifecycle" of a volunteer - how they show interest, how they get approved / onboarded, and how they schedule shifts. I'm interested in hearing specifically how you do those kinds of things today, tools you use, and where you see some of the challenges. I am hoping to develop new solutions for this space, but I first need to validate some of my assumptions about the process across different organizations. Hopefully that makes sense. Happy to address any other questions! Thank you, Nick </blockquote> I sent that reply at 9:00 AM, and at 4:00 PM, I received the following. Hello Nick, I have to be honest with you... there are a couple red flags to know if this is a scam or not so I'm going to pass on providing our information. Thank you. [redacted] </blockquote> ... I was honestly shocked. Maybe it's just me, but if I think something is a scam, the last thing I do is reply to it. Oh, I definitely want to - especially so I can mess with them - but I know I'm better off not engaging. (Although, the lone "Thank you." is probably my favorite part.) In all seriousness, I expected to be ghosted by a few contacts, but I never expected to be told I might be somebody trying to execute a scam. I re-read my messages probably a dozen times, pouring over every word, trying to figure out what I said that was so concerning. I did end up sending a response that I won't show here. I wasn't mean or snarky with them, and even apologized for how I came across, but it's just a little embarrassing. I probably over explained what I was trying to do, and even mentioned things like "I didn't lead with that information (about my company and idea) because I didn't want to bias you." It's absolutely the truth, but I'm sure they don't really care at this point. Phrasing it that way might even come across as me essentially admitting I was trying to play some scammer Jedi mind-trick I was certain would win them over, but now that they've caught me, we can get to the "real" facts to calm their nerves. I can laugh about this experience now, but it definitely rocked me at first. It sucks to be told something so blatantly wrong, especially when you make the effort to be as cordial and concise as possible. It also made me wonder if the people who ghosted me did so because I came across in a sketchy way. Moving forward, I will definitely adjust my approach. I think the biggest lessons are, Don't be afraid to say you are a software developer trying to build a new product. Saying you have an idea isn't the same as telling them what the idea is, and I think my prospective contact would have appreciated knowing what exactly I was attempting to do up front. Framing it as "just a conversation" works for some people, but others might find that to be a little odd. </li> Stop talking so much like an engineer. In my follow-up response to their question about what exactly I was looking for, I threw out words like "lifecycle" and started to describe the problem as I would describe it to another engineer. I went way over the top with detail when I should have just said, "Oh my gosh, I'm sorry I wasn't clear. I really just want to learn more about your organization so I can better understand the problems facing volunteer organizers. I do some volunteering myself and I'm curious if other organizations are facing the same problems." </li> </ul> Even with all that, you can't win them all. People will ghost you, and they may not be very helpful. The goal is to keep talking with people who are willing to talk with you until you stop hearing new information. Then, go build a kick-ass product. And if you're going to scam anybody, find your own strategy. This one is mine. Static Site Generators: Not Just for Blogs 2023-12-11T00:00:00+00:00 Static site generators have become popular within the technical and programming focused communities. They are fast, focused programs that allow anybody with a little bit of HTML and CSS skill to produce a blog or product page quickly, write all their content (typically) using markdown</a> in a simple folder structure, and commit it all to git. Truly a gift and a joy to work with, compared to something like Wordpress. Cloudflare</a> defines a static site generator (SSG) as "a tool that generates a full static HTML website based on raw data and a set of templates". In this context, "static" means that the end result of the build is a set of HTML pages that don't change when the page is refreshed, not that those pages never change. Static site generators are incredibly powerful tools available for modern web development and I think a lot of developers are missing out on what they offer in terms of development time, hosting cost, and overall simplicity. Blog Bias</h2> Blogs are common examples that come up when researching static site generators and how they can be used. This makes a lot of sense, as once blog posts are published, they rarely change, and they need to load quickly. In the context of a company blog, SEO is a major factor as well, since search engine crawlers need to parse content quickly. Unfortunately, I think a lot of the understanding around static site generation ends here, even among web developers. For a long time, I was in this camp as well. I knew I could use static site generation effectively for my blog site, or a simple "about" page here or there, and maybe even a legal statement or privacy policy. Basically, anything where the content could be shown in a long, continuous block of text. This understanding makes some product pages, or pages that require laying out collections of blocks in a grid-like structure difficult to reason about, and nearly impossible to build in some cases. If I can only store content in a big blob of text, and each document in my repository is a single page, how would I break it up so I can spread out the content to different sections of the page and style it appropriately? Worse yet, how would the non-technical team members update copy on the page without having to dig around in the HTML directly? Options for managing structured content</h2> I'm going to use zola</a> as my static site generator of choice and show some examples of creating and rendering "non-blog" content, in a few different ways. This is only because I'm the most familiar with it, but there are lots of good options out there, such as hugo</a>. They may or may not work in exactly the same way, but what's important here is taking the ideas and expanding our understanding of how we can utilize SSGs to their full potential. 1. Section and Page Metadata</h3> Sometimes called "front matter", each section or page of our site can have metadata associated with it. Even in the case of a blog, you'll see this metadata above the markdown content, enclosed in some kind of marker, to separate it from the main content of the post. This would include things like title</code>, description</code>, author</code>, and date</code>, and read by the static site generator itself to organize and template the page. The front matter of this post looks like, +++ title = "Static Site Generators: Not Just for Blogs" description = "Static generation should be the default" date = 2023-12-11 [taxonomies] tags = [ "web" ] +++ </code></pre> The easiest way to add structured data to this page would be to use the built-in [extra]</code> field for our custom content. +++ ... [extra] seo_keywords = "please, read, my, blog" +++ </code></pre> Then, inside of the template that renders the page, we can include these keywords in our block that allows for <meta></code> tag keywords to be added, {% extends "base.html" %} {% block title %}{{ page.title }}{% endblock %} {% block seo_keywords %}{{ page.extra.seo_keywords }}{% endblock %} </code></pre> which could generate HTML that looks like this, # template <meta name="keywords" content="{% block seo_keywords %}{% endblock seo_keywords %}"> # rendered <meta name="keywords" content="please, read, my, blog"> </code></pre> To build upon this example, imagine instead we had a product page and we wanted to specify a list of features. +++ ... [extra] [[extra.features]] headline = "Amazing Feature" description = "Do something amazing." [[extra.features]] headline = "Awesome Feature" description = "Do something awesome, instead." +++ </code></pre> Here, we have separated the content of each feature item from the display and styling of them. In our template, we can now iterate over each of these feature items and place them however we want on the page, using the page.extra.features</code> array. 2. Data in templates</h3> In many cases, it's useful to store website copy (especially marketing copy) in a content management system (CMS), where non-technical team members can edit and review content before it goes live on the website. The section and page metadata approach falls a bit short, since it still requires modifying files locally and committing them to git. Fortunately, zola</code> offers a load_data</code></a> function to bring in data from a remote source, within a template. As an example, we can build up a SaaS pricing page this way, using an endpoint in our hypothetical CMS. {% set token = get_env(name="API_TOKEN") %} {% set data = load_data(url="https://my.cms.com/api/data/pricing", format="json", headers=["Accept=application/json", "Authorization=Bearer " ~ token]) %} <h1>{{ data.tiers[0].name }}</h1> <ul> {% for feature in data.tiers[0].features %} <li>{{ feature }}</li> {% endfor %} </ul> </code></pre> The "url" passed to load_data</code> can be a local file as well, if it makes sense to store that JSON locally. </blockquote> This gives us the flexibility to put content somewhere else that is more accessible to a wider group of people on our team. Any change in the CMS can be detected (hopefully via a webhook) and the site can be rebuilt, previewed and pushed to production. Side note: static site generators are fast. This entire site builds in just under 100ms. </blockquote> 3. Automated markdown file generation</h3> Finally, there is always the option to generate a set of markdown files to be placed in the content</code> directory. This is the approach I've taken for the bips.dev</a> site, where each BIP is a separate page, with front matter and markdown generated from a script that uses pandoc</code></a> to translate the media wiki format to markdown. Admittingly, it's a bit of a hack, but it does work. Large documentation sites could be built this way with content from a CMS. This method would be needed whenever the actual structure of the site is dictated by some other source. In the case of bips.dev</code>, that source is a public git repository</a>. Simple as the default</h2> TL;DR With the proliferation and increasing sophistication of SSGs, I think the time has come where we can say that the default choice of any "non-application" website should be static generation. Statically generated sites are faster to develop, easier to host, and easier to reason about over the lifetime of the project. I want to be explicit in stating what I hope is the obvious: If you are building a highly interactive application with lots of business logic, obviously a fully featured programming language and deployment environment is going to be a better option. I think that statically generated sites still offer some room to include interaction and business logic with client-side Javascript (alpine.js</a> is a great candidate here), and that can always be included as part of your templates and build output. I would even go so far as to say that needing to have a few business logic endpoints shouldn't completely eliminate the possibility of using a static site generator, as you could simply have a reverse proxy forward those requests to an application server, and just serve the static content for everything else. Some judgement would need to be exercised there, to see if it makes sense for the use-case, but I would still take a moment to see if that model could satisfy your requirements. On the infrastructure side, hosting a statically generated site is just about the easiest thing to do. From a self-hosted nginx</code> instance to a managed platform that watches for changes in your git repo and builds the latest version of the site with automatic certificate renewal, there are tons of reliable options. A recent website rebuild I worked on spent far more time than necessary dealing with the heavy frontend framework that was chosen, mainly because the full scope of how static site generators could be used wasn't known at the time. It's tempting to reach for those languages and tools, since they are familiar to a lot of developers. At some point though, we have to use the best tool for the job, and bringing along all of React to build out a few product pages just doesn't seem like the way to go. I could be way behind on this. If you're reading and find all of it to be blatantly obvious, or something that was figured out years ago, awesome! In my recent experience, there is still a lack of understanding around SSGs, and I hope we'll see a renaissance soon, where the simple choice is the default choice. Building a nostr client [1] 2023-08-31T00:00:00+00:00 Welcome to the second installation of the "Building a nostr client" series. The goal of this series is to walk through building a simple nostr client in Rust. If you haven't seen the first post here</a>, I would recommend doing so, as we'll build on those concepts. Also, if you aren't familiar with nostr and why I'm doing this, that would be a good place to start as well! In the last post we discussed the basic data structures of the protocol; how to build them, and what basic Event signing could look like. In this post, I want to start connecting to relays, and build a simple TUI (terminal user interface) to display events. Building on prior art...</h3> When I first considered doing this series of posts, I had the thought that I would do pretty much everything "from scratch". Essentially, use libraries available to me in Rust, but nothing nostr specific. After finding the nostr crate</a> and giving it some thought, I decided that I would, at the very least, use its core data structures, event generation and signing capabilities to build my client. yukibtc</a> and other contributors have done an incredible job with this crate so far. Much better than I could do. It's easy to understand and quite comprehensive. So, in the interest of time, and future-proofing this project (I know I'd have to refactor my code to use the nostr</code> crate at some point anyway), I'll be using that crate moving forward. Even so, I want to explore some different methods of relay interaction that depart from the sibling nostr-sdk</a> crate, so we'll have plenty of code to write there. Moving on! Relays</h3> Relays are the backbone of the nostr protocol. They are responsible for accepting events and sending them on to interested clients. By design, there are many relays a client could possibly connect to. Some require payment for access, but many are free. Some are built for a specific community or topic in mind, but most right now seem to be pretty free-form. If one relay goes down, for any reason, temporarily or permanently, clients can just connect to another. Clients connect to relays and send events (or "notes") across them, and clients on the other end set up filters for those events. Not every user is automatically connected to every other user, as they would be on the global feed of a centralized platform, so there are some issues around discovery, as you need to know which relays people are posting to. But, in practice, it's not a big deal. (And there are some NIPs out there attempting to mitigate this.) As you start to think about how a client should interact with its configured relays, you tend to realize: There is no "should". Other than the basic data over-the-wire requirements of the protocol, clients can and actively do all sorts of things to transmit and receive events to and from relays. Without The Algorithm</a> handed down from on high, there are really no rules here. You want events chronologically? Great. You want events from your followed accounts and the accounts they follow? Sure. Only show events whose ID ends with the hex digit f</code>? I guess. Allow the user to selectively send events to some relays but not others? Yes, absolutely. </li> It's suprisingly deep. There are a lot of practical elements to consider when building a client's view of the nostr world, especially in a "twitter-like" way. Generally you want to have the option of viewing something other than the "global" feed of all their connected relays, as it can either be extremely spammy, or just too much information, too quickly. So, you need some kind of view filtering, even if it's just showing events from the user's followed accounts. Also, what if the user is away from the client for a while (say a month) and decides to come back? Do you start showing them events from exactly where they left off? It might take them a while to scroll through and catch up to current events. Do you fetch older events if they scroll in reverse chronological order? How many do you fetch at a time? </li> </ol> I could go on with plenty more rhetorical questions related to client/relay interaction. It really is the wild west right now and there are a lot of opportunities to innovate in this space. All that being said, I want to start as simple as possible. For now, we will support showing events from the user's followed accounts, in the order we receive them. But first, we need to connect to some relays. Finding a connection <3</h4> Connecting to a relay is relatively straightforward in principle, but somewhat difficult to manage in practice. Fortunately, the really low-level details are already handled for us in a crate called tokio-tungstenite</a>. tungstenite</code> is a popular Rust crate for handling WebSocket</a> connections, which nostr uses for its protocol communication layer. The "tokio" side of this crate just brings it into the most popular ecosystem for asynchronous programming in Rust... tokio</a>. I believe the primary motivating factor for using WebSockets in nostr instead of some other transport protocol is that WebSockets are everywhere, especially modern web browsers. This means clients can work within or (in our case) outside a browser context. It also means clients can make one connection to a relay, and reuse that same connection for multiple things, reducing some of the connection overhead on the server. </blockquote> Another quick caveat: Like many aspects of this series, especially related to Rust, I certainly cannot do the asynchronous programming story justice here. It's another huge topic, deserving of near book-length treatments itself. Very simply put, asynchronous programming allows applications that primarily do I/O to scale quite far, with fewer resources. This is because I/O related tasks generally take waaaay longer than the tasks a CPU must perform, due to the high latency of the I/O device (disk, network, etc). Therefore, we can tell the asynchronous runtime we anticipate running some long I/O task, and that it can literally wait for that task to complete, while another task on the CPU runs, typically on the same thread. </blockquote> Essentially, we need to start a bunch of tasks that send and receive events from configured relays on their own time, and have another task that is aggregating these events together in some way: de-duplicating them, showing them to the user, saving them to disk, etc. So, we need a way to spawn the async I/O task for each relay we want to interact with, and then communicate with that task using nifty little tools called "channels". I'll try to illustrate how this is going to look. Architecture</h4> Relays are implemented as a Rust struct</code> type, with a few properties. First, it must be configured with a WebSocket URL, which is published by a relay operator, and is up to our client to store and use. Internally, a Relay</code> must also create and reference a "channel", that is used by the client to communicate with it asynchronously. These are tokio::sync::mpsc</code></a> channels ("multiple producer, single consumer"), and aren't exposed directly to the client, but is indirectly through a function interface, as illustrated below. Relays are created in a disconnected</code> state. </div> These "control" messages are used to tell the relay to send us events that match a certain filter (as defined by NIP-01</a>), publish our own events, or disconnect. They must be sent over a channel that the Relay</code> manages since there is an underlying async task that must listen for events from the relay and be responsive. But first, we have to actually connect to the relay with its WebSocket address, and receive those events from it. When we call the Relay::connect()</code> method, we use the tungstenite</code> crate underneath to open a WebSocket connection, and spin up an async task to handle the "up" stream (messages to the relay), and the "down" stream (messages from the relay). These "up" and "down" handles are also part of a Stream</code> construct that is well beyond the scope of this post, but for our purposes, "up" is like a mpsc::Sender</code> and "down" is like a mpsc::Receiver</code>. </div> These relay messages are written over the wire as Message</code> types from the tungstenite</code> crate, and are translated from the nostr::ClientMessage</code> and to nostr::RelayMessage</code> types. Lastly, we have to consider how it looks when there are multiple relays involved, as is expected within a nostr client. When the Relay::connect()</code> method is called, it expects to be given a mpsc::Sender</code> side of a channel, which can be cloned and given to every relay we are interested in. These "producers" will all funnel to one "consumer" (mpsc::Receiver</code>), which acts as our firehose of events coming from all relays we have a connection with. There's nothing required about this, it just makes it easier to deal with in a simple implementation like this one. We can treat all Relay</code> structs as if they were one big set of relays, producing a single stream of events. </div> As far as technical implementation details, there's a lot left to go over here. I think the best way to think about this is you have an async task ("thread") driving the inbound/outbound connection with the WebSocket relay itself, and another, at the client level, that is driving the state of the Relay</code> struct, and that is why we need to use async channels behind Arc<Mutex<...>></code> primitives, so they can be safely cloned and shared throughout the client as necessary. The Relay</code> struct is a effectively just a handle over a set of common data structures, making the initial connection and shuffling data between this async task boundary. With that, we have a very simple nostr client interacting with relays! Here is some sample output that just shows us connected to two major public relays, sending a filter for all kind 1</code> events after the current timestamp. When the user hits Ctrl-C, we disconnect from each relay and shutdown. $ RUST_LOG=info cargo run Compiling roostr v0.1.0 (/var/home/nickmonad/code/nostr/roostr) Finished dev [unoptimized + debuginfo] target(s) in 3.07s Running `target/debug/roostr` [2023-08-26T19:59:28Z WARN roostr] relay sent non-event message: EndOfStoredEvents(SubscriptionId("51102577c2f141aa2a06a10d3c2106b5")) [2023-08-26T19:59:28Z WARN roostr] relay sent non-event message: EndOfStoredEvents(SubscriptionId("5854bf7126a9337f9c35ea55dfdd5227")) [2023-08-26T19:59:43Z INFO roostr] EventId(0x078495389530eff3f78e86dcb14095f4c10d0bc80e9b1f5f0fa9bdab7c8a3c45) [2023-08-26T19:59:45Z INFO roostr] EventId(0x48627557bcac6d61d35946a74e5f3cf63a1057a0852b17f22d45bf530eaab8a3) [2023-08-26T19:59:46Z INFO roostr] EventId(0xe5954fe675db03fc5f0a1b4ea5d19f8de6fbd2cbf4be670fbd145652387d5136) [2023-08-26T19:59:49Z INFO roostr] EventId(0xfa9d99dc2e1a1e3c7c61dbb26d3929d1c0f82ec513d86403eb1790bcd6d1c25e) [2023-08-26T19:59:50Z INFO roostr] EventId(0xf2fe94cf82fb3d6dc39811320d43a9cbd0e1eaeb04ff7fb0a03ddea983a4ec21) [2023-08-26T19:59:50Z INFO roostr] EventId(0xf2fe94cf82fb3d6dc39811320d43a9cbd0e1eaeb04ff7fb0a03ddea983a4ec21) [2023-08-26T19:59:50Z INFO roostr] EventId(0xe4410e2d3714de65f21aa494ec89fb9e38ec69c05402143c5395cfe0df4e81fb) [2023-08-26T19:59:53Z INFO roostr] EventId(0x14b7f5f38998a93bb9dda045b72d55a3bab61bde4481b65c415e5503c61eb40c) [2023-08-26T19:59:53Z INFO roostr] EventId(0x953c7bb5884b57b98f54ddf227a8b437c3e061525e29a132c69f7848085df218) [2023-08-26T19:59:55Z INFO roostr] EventId(0x9f4a511bd1f6b02ccb4c4daea54a51b5daef6d78b126219fa234962efc5d8de7) [2023-08-26T20:00:03Z INFO roostr] EventId(0x84fec22e2056751d54c323fa4ff6ac3217d352f6f73eff84779fa3f7e5d48291) [2023-08-26T20:00:07Z INFO roostr] EventId(0xf7119e7250a7f6eaea5058254d850dcb7882428535f1aba1a3e511c5229aa00f) ^C[2023-08-26T20:00:11Z WARN roostr] shutting down! [2023-08-26T20:00:11Z WARN roostr::relay] ["wss://relay.damus.io/"] user disconnect [2023-08-26T20:00:11Z WARN roostr::relay] ["wss://nostr-pub.wellorder.net/"] user disconnect </code></pre> The inital messages showing EndOfStoredEvents</code> from each configured relay are due to the fact we set the since</code> value on our filter message to be Timestamp::now()</code> and the relay is just saying, "eveything after this will be in real-time." </blockquote> TUI</h3> Now that we have events coming in from the relay, we can start on the real client functionality. As I stated earlier, this can go really deep on implementation, and wide on feature set. I want to keep things really simple, so it won't do much for now. To help set some direction on where to focus next, I think we can break it down like so: First, read a list of public keys to "follow" from a local config file.</li> Using the public keys present in that config, setup and send filters to each relay, asking first for kind 0</code> events associated with the public key(s), giving us "profile" metadata, like the user's preferred display name, followed by kind 1</code> events, the actual text notes, from the past day. (Arbitrary choice.)</li> Listening on the aggregated event stream, use some kind of mechanism to ensure that events aren't shown twice, in the case where a followed public key is published to more than one of the relays we are interested in. This is quite common, and must be handled by pretty much every client. There are really straightforward ways of handling this, using a list or map, but those come with tradeoffs in performance and memory usage over time. We could use a SQLite based implemention, which I think would be ideal for a client like this, but for now, let's just use a simple in-memory set, and vector (list) of events.</li> Build a simple TUI (terminal user interface) for showing the events and navigating through the list.</li> </ul> This is the simplest possible start I can imagine, while building something at least marginally useful. Many factors of a "real" client won't be considered here, but, it'll be fun to continue adding features over time. Starting up</h4> First, we need to read our config file, and create our primary mpsc</code> channels. One for that relay "firehose" mentioned above, and another for terminal events (user input, resize notifications, etc). The first block here is our example config.toml</code> file. follow = [ "npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkwsyjh6w6", # fiatjaf "npub1sg6plzptd64u62a878hep2kev88swjh3tw00gjsfl8f237lmu63q0uf63m", # jack "npub1qny3tkh0acurzla8x3zy4nhrjz5zd8l9sy9jys09umwng00manysew95gx", # odell ] [[relay]] url = "wss://relay.damus.io" [[relay]] url = "wss://nostr-pub.wellorder.net" </code></pre> In the long term, the config for roostr</code> would be more related to behavior, and not have hardcoded npubs or relay URLs. These would be requested the first time a user started the client, and stored in a local database. Pubkeys to follow would ideally come from nostr kind:3</code> events, published via our user's pubkey, but I decided not to implement that right now, since we don't have a database yet. </blockquote> #[tokio::main] async fn main() -> anyhow::Result<()> { // send logs to stderr env_logger::builder().target(Target::Stderr).init(); // load config let config = Config::load("config.toml").await?; // event/relay message bus let (tx, mut rx) = mpsc::channel::<RelayMessage>(1024); // events from terminal let (events, mut input) = mpsc::channel::<TermEvent>(10); </code></pre> Now, we can initialize our Relay</code> structs, one for each URL we have listed in our configuration. // filter for all kind:0 metadata objects let metadata = Filter::new() .kind(Kind::Metadata) .authors(config.follows.clone()); // filter for all kind:1 notes let notes = Filter::new() .kind(Kind::TextNote) .authors(config.follows.clone()) .since(Timestamp::now().sub(ONE_DAY)); // statically defined `Duration` value // instantiate configured relays let mut relays: Vec<Relay> = vec![]; for relay in config.relays { let r = Relay::new(relay.url.clone()); r.connect(tx.clone()).await?; r.send(ClientMessage::new_req( SubscriptionId::generate(), vec![metadata.clone(), notes.clone()], )) .await?; relays.push(r); } </code></pre> Processing and displaying events</h4> Once the client has completed this initial startup, it can run its primary processing loop, reading events from the relays, and user input from the terminal. Since we aren't using SQLite right now as we prove all this out, we'll use an in-memory "database" structure. // Simple "database" implementation, // storing a list of Events, and a map of Metadata objects, accessible via pubkey #[derive(Default)] pub struct Database { pub events: Vec<Event>, pub metadata: HashMap<String, Metadata>, } </code></pre> The metadata</code> attribute is important, as we want to show every pubkey's "username" as they have published them under the kind:0</code> event. Since we have a filter setup for those, we can update this struct as a mapping between the followed pubkeys and their metadata. The events</code> attribute is a simple vector of all the kind:1</code> events we receive. Obviously, this isn't really scalable for "real-world" usage. We'd ideally push these to a local SQLite file, and maybe use these in-memory structures for a bounded cache. Just indefinitely growing this vector isn't efficient at all, but again, this is more of a proof-of-concept. </blockquote> Finally, we can run our primary loop. Essentially, the client blocks while it waits for one of two types of events: user input or relay events. For user events, the TUI will be given those events (other than the quit event), and it will update its own state, like which nostr note is selected based on user selection. For relay events, the database is updated. Incoming nostr events are de-duplicated, and then stored in the event list. // setup our "database" and set of "seen" events, for de-duplication let mut database = Database::default(); let mut seen: HashSet<EventId> = HashSet::new(); // setup tui let mut tui = Tui::new()?; tui.events(events); // initial draw tui.draw(&database); // main event loop // as messages/events come in, de-duplicate them // and store them for display on the UI loop { tokio::select! { // get events from the terminal event = input.recv() => { match event { Some(event) => { if let TermEvent::Key(KeyEvent{ code, .. }) = event { if code == KeyCode::Char('q') { // user quit - disconnect from relays log::warn!("[client] user quit!"); disconnect(relays).await.unwrap(); break; } } // pass event to TUI struct, so it can update its own state tui.update(event, &database); }, _ => {} } } // get events from relay(s) msg = rx.recv() => { match msg { Some(msg) => { match msg { RelayMessage::Event { event, .. } => { match event.kind { Kind::Metadata => { // update metadata map, from pubkey to metadata let metadata = Metadata::from_json(&event.content).unwrap(); database.metadata.insert(event.pubkey.to_string(), metadata); }, Kind::TextNote => { // process note, ignore if we have seen already if !seen.contains(&event.id) { database.events.push(event.as_ref().clone()); seen.insert(event.id); } } _ => {} } }, _ => log::warn!("relay sent non-event message: {:?}", msg) } } None => { log::warn!("all relay senders dropped"); break; } } } } // event(s) processed, draw another "frame" tui.draw(&database); } </code></pre> In both cases, after the event is processed, the TUI is re-drawn. In principle, there is some contention here. If there is a delay in processing a relay event, user events will have to wait as they queue from the terminal input thread, potentially causing a lag in the responsiveness. But, in practice, espcially in this case, the relay event processing is so minimal, that it doesn't have an impact. If there were heavier processing involved, the client would likely have to split off that processing onto another async task or thread and signal its completion back to this thread. As for the actual processing requirements and performance of re-drawing the TUI, we don't have to worry about that in practice either, since it's just... outputing text to the terminal. Since this post is already way too long, I'll pass on explaining the actual TUI rendering in detail. Suffice it to say, I chose to use ratatui</a>, the successor to tui-rs</code>. It provides really simple ways to put the terminal in the correct mode it needs to be in, and build up layout components. Demo!</h3> This may not render correctly on mobile. </blockquote>