Adam Nelson

Chatterbox: Federated Chat that Doesn't Suck

Unknown — Wed, 03 Sep 2025 00:00:00 +0000

Have you used Matrix? Do you like it? Trick question, of course you don’t. It seems like nobody likes Matrix, at least not once they’re familiar with its… quirks. It’s frustratingly overengineered, difficult to work with, full of bugs, and its insistence on E2EE makes it hard for nontechnical users to comprehend.

For the past several months, I’ve been working on a better solution for federated chat. Chatterbox is a new protocol that, I hope, will make federated chatrooms actually nice to use. It’s still in development; currently, I don’t have any working software to show, just the plan and the API.

But, in case it sounds interesting to you, here’s some of its key features:

User-friendly defaults: The default experience uses ordinary password login and does not ask you to save a recovery key or anything else complicated. There will be a default flagship instance at cbox.cx</code> that is only used to host user accounts that federate to other servers. </li>
Client-to-server federation: When you connect to an instance other than your home instance, your client connects directly to it, and your home instance doesn’t know. </li>
Optional public key auth: Power users can choose to identify themselves with a self-managed Ed25519 keypair. The default password login lets the server manage your private key, but you can switch to a personal key any time. </li>
Credible exit: Users can move between instances, switch public keys, and revoke keys. If you manage your own key, you can move servers even after your home server goes down or bans you. </li>
No E2EE by default: Depending on your perspective this may or may not be a good thing. But in my experience Matrix E2EE is more trouble than it’s worth for 90% of use cases, and there are plenty of uses that don’t need any more encryption than HTTPS. Future versions may add optional E2EE DMs via MLS. </li>
Bot API: Extra features can be added via bot users, which have access to additional API features like annotating existing messages and receiving private /</code>-commands. Link previews, for example, are implemented as a bot, but, unlike Matrix’s maubot, the preview appears an an annotation on the message, not a separate message. </li>
Optional replication: Servers and rooms exist on one instance by default (avoiding the Matrix issue of overloading your server by joining a large room), but can optionally be replicated across multiple instances, for high availability or as part of a migration process. </li>
Simple, easy-to-implement protocol: The protocol is a single WebSocket connection with Protobuf messages, using a simple custom RPC system. The entire API is defined in one .proto</code> file. (I considered switching to a REST API</a> but decided to simplify the WebSocket API instead.) </li> </ul> Interested? I’ll hopefully have more information soon, but for now you can read the work-in-progress chatterbox.proto</code></a> that defines the entire protocol. Let me know what you think on Mastodon; I’ll post updates there with the tag #Chatterbox</code>.

Why not REST? Unknown — Sat, 30 Aug 2025 00:00:00 +0000 When writing a README for Chatterbox (my attempt at a new federated chat protocol), I wanted to explain all of my design choices. One that quickly gave me trouble was the API’s format: it uses Protobuf over a single WebSocket connection, instead of a REST API. Why did I do it this way? The obvious answer is that it’s just interesting to me. I have a lot of trouble choosing boring technology</a>, because I have to keep the project interesting enough for me to stick to it. I reimplemented something like gRPC on top of WebSockets as SockRPC</a>, in order to ensure browser compatibility and avoid the HTTP/2 requirement, and, while it’s not terribly complicated, it’s still a barrier to understanding the protocol, so I need a reason why it’s necessary. But, as I tried to give a better explanation, every reason I could find rang hollow: Performance? This is the main one, and WebSockets+Protobuf are almost certainly faster than REST+JSON, but it’s not like I’ve actually profiled anything. How much of a difference is it? Is it enough to matter? </li> Simplicity of sessions and pubkey challenge auth? Chatterbox uses public key authentication, and one websocket connection with one auth challenge at the beginning is simpler. But it’s not that hard to have a REST auth endpoint that generates a JWT after completing a challenge. </li> Security? Several open chat and social media protocols, including Matrix, have made the mistake of leaving their uploaded media URLs open to the world, no auth required. Streaming everything over websocket makes this impossible by design. But is this much added complexity (streaming media over websocket in chunks!) really necessary to prevent a simple mistake that could be mentioned in the spec? </li> Succinct documentation? In theory, the entire Chatterbox protocol can be defined in one .proto</code> file</a>, using gRPC’s service definition syntax (since SockRPC reimplements gRPC). But that’s not quite true: there’s SockRPC itself, as well as out-of-band alternate authentication methods like OAuth. With a basic REST API, I could use Swagger, which actually has widespread tooling support. </li> Binary data? The protocol uses binary public keys and UUIDv7s everywhere, not to mention timestamps, and by using Protobuf I’ve been able to avoid committing to a specific string representation of any of these. With JSON (or REST URLs, even without JSON) I’d have to represent all of these as strings. </li> </ul> None of these seems like a big enough deal to justify adding more implementation barriers in the form of a new RPC protocol that will need to be ported to each new language that implements a Chatterbox client or server. So what’s standing in the way of me making it a boring old REST API? Event streaming, mostly. Chatterbox, as currently defined, has 3 types of streams: user event streams (one per client), server event streams (one per server the user has joined), and room event streams (one per room, but only one should be open at a time). These will have to be implemented with either WebSockets or Server-Sent Events. SSE is the simpler approach: just give each type of event its own URL. But, surprisingly, SSE has a limit on the number of open connections</a>, so this won’t work reliably unless I enforce HTTP/2 (at which point why not just use gRPC?). So we’re back to WebSockets, now as part of the API instead of the whole thing. And this still makes it inelegant: WebSockets can’t be described by Swagger, for example. Certainly it would be much simpler to describe and implement a WebSocket connection that does simple pub/sub on event streams using JSON instead of a full RPC protocol with error handling and 3 types of streaming calls. There are a bunch of places to land in this design space and I’m unsure what’s worth prioritizing. Do I use REST with WebSockets just for events, but use Protobuf or CBOR instead of JSON (and accept that that prevents me from desribing the API with Swagger)? Maybe I should do REST+JSON for everything but the WebSockets, which can use a binary format? Should I stop trying to force something clever and just make it all JSON? If you have thoughts or feedback, you can reply on Mastodon</a>. Maybe Everything Is a Coroutine Unknown — Mon, 12 Feb 2024 00:00:00 +0000 I was inspired, after reading the excellent blog post Let Futures Be Futures</a>, by the author’s thought experiment of a language in which all functions are coroutines and this is used to express asynchronicity: async functions can yield a type called Pending</code> when awaiting some async action, while pure, synchronous functions can yield Never</code>, indicating that they never yield at all. The more I thought about this, the more I realized that a strongly-typed language in which every function is a coroutine could actually have a lot of nice properties. I’ve come up with a design with several cool features, including: A type system in which coroutines are basically state machines</li> A typed (algebraic) effect system based on coroutines Functions can be generic over effects and purity</li> Effects can be “intercepted” by a caller and faked</li> </ul> </li> A powerful exception system based on simple sum types An exception pass-through system that feels like a saner, generic version of checked exceptions</li> Common Lisp-style resumable conditions</li> </ul> </li> Immutable data structures and pure-by-default functions, but with the ability to use mutation in algorithms, by keeping all mutation in a function’s scope and using coroutines to control state</li> </ul> How does it work? There are three key features: sequence types, the coroutine for loop, and the pass operator. Sequence Types</h2> Ordinary functions have argument types and a return type: fib(n: Int) -> Int </code></pre> In this everything-is-a-coroutine language, instead of a return type, every function has a sequence type. This is a sum type describing every type that the function can yield and every type that it can be resumed with after a yield. For example, a coroutine version of fib</code> that, instead of returning the n</code>th Fibonacci number, yields an infinite sequence of the Fibonacci numbers: fib() -> Int() </code></pre> The ()</code> means that, after the coroutine yields an Int</code>, it can be resumed with no arguments. Because there is no base case (no branch that cannot be resumed), this coroutine must be infinite; it continues until the caller chooses not to resume it. Consider instead a coroutine that yields a finite sequence of Int</code>s: factors(n: Int) -> Int() | Void </code></pre> This sequence type has two cases: either it emits an Int</code> and can be resumed with no arguments, or it emits nothing and cannot be resumed. Notice the syntax of Void</code>: a type with no parentheses is a valid sequence type. This means that the ordinary function fib(n: Int) -> Int</code> is a valid coroutine as well—it yields Int</code> once, then cannot be resumed. Pure functions are a subset of coroutines! These strongly-typed coroutines are essentially state machines. Let’s define an additional piece of syntax: a symbol :foo</code> is a unique singleton object whose type is also :foo</code>. Using symbols, we can define a simple state machine for a door: door() -> | :open(:close) | :closed(:open | :lock) | :locked(:unlock) </code></pre> Each state accepts only a specific set of actions. An open door can only be closed; a locked door can only be unlocked; a closed door can be opened or locked. Coroutine For Loop</h2> But how do we use these coroutines? The syntax for basic function calls remains the same; if a coroutine has only no-resume types in its sequence type, then it can be used directly as an argument or assigned to a variable. For more complex coroutines, there is a for loop syntax. Consider the door state machine from before; this is an example of a for loop that uses it: for (door()) { | :locked -> continue(:unlock) | :closed -> continue(:open) | :open -> break } </code></pre> This loop pattern-matches on the values yielded by door</code>. The branches use the familiar keywords continue</code> and break</code>, but continue</code> takes arguments now: it resumes for</code>’s coroutine with new arguments, which must match the argument type of the current branch of the sequence type. The loop does not end until it encounters a break</code>. We can add some conveniences for the common case of coroutines that yield a list of values without any resume arguments. continue()</code> is inferred at the end of blocks whose resume type is ()</code>, break</code> is inferred at the end of blocks with no resume type, Void</code> branches can be omitted, and wildcard matches are assumed to not match Void</code>. def someNumbers() -> Int() | Void { yield 1 yield 2 yield 3 } var total for (someNumbers()) { n -> total += n } </code></pre> The Pass Operator</h2> Extending this coroutine syntax to support algebraic effects and error handling is straightforward. Errors can be yielded as ordinary values, which usually do not resume: divide(divisor: Int, dividend: Int) -> DivideByZeroError | Int </code></pre> Algebraic effects can be yielded, presumably all the way up to the main function, which will then resume with a response to the given effect. These get complex, but I’ll introduce syntax sugar to deal with these huge signatures later. readFile(filename: String) -> | IOFileStat(FileError | FileInfo) | IOFileRead(FileError | Bytes) | FileError | Bytes </code></pre> But actually using effects and errors with the mechanisms we already have (for loops and yield</code>) would be extremely cumbersome. It would look a lot like Go: manually checking for error states or effects everywhere, just to yield</code> them to the next level in the stack. readConfigJson(filename: String) -> | IOFileStat(FileError | FileInfo) | IOFileRead(FileError | Bytes) | FileError | JsonParseError | JsonFormatError | ConfigFile { for (readFile(filename)) { | IOFileStat a -> continue(yield a) | IOFileRead a -> continue(yield a) | FileError e -> yield e | Bytes data -> // borrowing some Scala syntax parseJson(data) match { | JsonParseError e -> yield e | JsonValue json -> yield parseConfigFile(json) } } } </code></pre> The common pattern here is a -> continue(yield a)</code> (for branches that resume) and e -> yield e</code> (for branches that don’t). This pattern is so common in this style of code that it deserves its own piece of syntax sugar: the pass operator, ^</code>. Placing ^</code> before an expression causes any value yielded by that expression that can be directly yielded (as continue (yield a)</code> or just yield a</code>) to be yielded. In other words, it causes any types contained in the function’s sequence type to be passed through from this expression to the caller. This greatly simplifies the example function: readConfigJson(filename: String) -> | IOFileStat(FileError | FileInfo) | IOFileRead(FileError | Bytes) | FileError | JsonParseError | JsonFormatError | ConfigFile { val data = ^readFile(filename) val json = ^parseJson(data) yield parseConfigFile(json) } </code></pre> The sequence type is still a mess, though. And there’s another problem: what if a function yields a bunch of effect types, but also a type that you want to capture in a variable… that also happens to be in your function’s sequence type? Here are some changes that solve these problems: The keyword infer Type</code> can be used in any branch of the sequence type; its type is inferred as all subtypes of Type</code> that are yielded by the function. Values passed through by the ^</code> operator are included in this inference. infer Type(*)</code> also infers the resume arguments; this can infer multiple branches.</li> </ul> </li> The ^</code> operator can occur in front of sequence type branches. This causes ^</code> in the function body to only pass through types that also have a ^</code> in front of them in the sequence type.</li> A block or keyword, like nopass</code>, could prevent a type from being passed through; this would work like a catch block, ensuring the function can handle a specific yielded type.</li> </ul> With these changes, and assuming that supertypes FileIO</code> and Error</code> exist, the function becomes even simpler! readConfigJson(filename: String) -> ^infer IOFile(*) | ^infer Error | ConfigFile { val data = ^readFile(filename) val json = ^parseJson(data) yield parseConfigFile(json) } </code></pre> Putting it All Together</h2> These three key features are a surprisingly solid core for a language, but they aren’t a full language on their own. They could fit into several different language designs, but, in my opinion, the ideal language built on this foundation would have: Strict functional purity outside of algebraic effects and mutable local variables. You can only perform side effects by yielding effect objects from main</code>. Mutable local variables can still allow for efficient mutable data structures, thanks to coroutines. A mutable, resizeable array type can exist, but it cannot be yielded, passed as an argument, or stored in a struct. Structures of these arrays can then be manipulated by passing a coroutine into a function, then using actions yielded by that coroutine to manipulate the arrays defined in that function’s scope.</li> </ul> </li> Immutable, nominally-typed structs with subtyping.</li> A generic tuple type, allowing for tuples-with-symbols message passing a la Erlang, but strongly typed.</li> Full higher-order generics. This allows functions to be generic over purity and generic over checked exceptions, two qualities that are very rarely found in type systems.</li> Type aliases for sequence types, which can include multiple branches. The syntax for this would likely use (*)</code>. For example, you can define type Ints -> Int() | Void</code>—the -></code> indicates that it’s a sequence type—and then use it like this: someFunction() -> Ints(*)</code>. Using these types, functions can take sequence arguments. For example, sum(seq -> Ints(*)) -> Int</code> is a sum function over a finite sequence of Int</code>. It can be called with sum(someFunction())</code>, and the entire sequence returned by someFunction</code> will be passed in to sum</code>.</li> A syntax for standalone sequences should also exist, basically the coroutine equivalent of an IIFE</a>. For example, -> { yield 1 }</code> would be a sequence of type -> Int</code> by default, but could also be explicitly typed: -> Int() | Void { yield 1 }</code>.</li> Sequence literals could be written with square brackets: [1, 2, 3]</code> would be syntax sugar for -> Int() | Void { yield 1; yield 2; yield 3 }</code>.</li> </ul> </li> </ul> I have no idea when I’ll find the time to actually work on this, but I’d like to see this language come together. I feel like this everything-is-a-coroutine type system has a lot of potential as a new architecture for functional programming. Parentheses are Just Typechecking Unknown — Tue, 22 Jun 2021 00:00:00 +0000 Consider this Scheme expression, taken from the Rosetta Code example for the Mandelbrot set</a>: An Object-Oriented Language for the '20s Unknown — Fri, 12 Mar 2021 00:00:00 +0000 Object-oriented programming is out of fashion now, and it has been for a while. Rarely are new programming languages intentionally object-oriented. And there are good reasons for this: OO often requires a lot of boilerplate, it forces code into unnatural object hierarchies, and it encourages hidden mutable state. But, if we made a new statically-typed OO language from scratch in 2021, something in the vein of Java or C#, taking everything we’ve learned from functional programming and a decade-plus of scathing OO criticism, could we fix this? Especially if we had no expectation of compatibility with legacy code? Converting CJK Fonts to WOFF is Harder Than You'd Think Unknown — Sat, 09 May 2020 00:00:00 +0000 tl;dr: Don’t even try online converters. They’ll drop the CJK characters. Just install woff-tools</code> and/or woff2</code> on your own machine. Most Linux package managers will have them; on Windows, you can use the EXEs in this GitHub repo</a>. </blockquote> A few days ago, I needed to install a web font (Noto Sans JP</a>) for Japanese text on a site I was working on. The site supports IE11, so I would at least need a WOFF file, and a WOFF2 for newer browsers. The obvious place to look was Google Fonts. It used to provide a ZIP download of any web font in multiple formats (at least TTF, WOFF, and WOFF2). But Google Fonts seems to have removed this feature; ZIP downloads only include OTF files now. If I wanted IE11 support, I’d need to convert these to WOFF.