fasterthanlime

Introducing facet: Reflection for Rust

Thanks to my sponsors: medzernik, Kyle Lacy, Mike English, clement, Elnath, you got maiL, Chris Sims, Brandon Piña, Ben Mitchell, Ben Wishovich, Bob Ippolito, Ronen Ulanovsky, jer, Max Heaton, Astrid, Paul Marques Mota, Kai Kaufman, Lyssieth, Jonathan Adams, David Cornu and 266 more medzernik, Kyle Lacy, Mike English, clement, Elnath, you got maiL, Chris Sims, Brandon Piña, Ben Mitchell, Ben Wishovich, Bob Ippolito, Ronen Ulanovsky, jer, Max Heaton, Astrid, Paul Marques Mota, Kai Kaufman, Lyssieth, Jonathan Adams, David Cornu, Zeeger Lubsen, Justin Smith, Chirag Jain, Ula, Thehbadger, Wyatt Herkamp, Jan-Stefan Janetzky, Òscar Pérez, René Ribaud, Kamran Khan, compwhizii, Cole Tobin, Chris Emery, Makoto Nakashima, Richard Stephens, Scott Steele, Walther, Marcus Griep, Tobias Bahls, Beat Scherrer, Vladimir, Romet Tagobert, Ronen Cohen, Cole Kurkowski, Thor Kamphefner, C J Silverio, Sawyer Knoblich, James Rhodes, James Leitch, Michael, Corey Alexander, Josh Triplett, Garret Kelly, Aljaz Erzen, Dylan Anthony, Geoffrey Thomas, Andrew Neth, Mikkel Rasmussen, Stephan Buys, Blake Johnson, prairiewolf, Guillaume Demonet, Elendol, pinkhatbeard, Tabitha, e9zaktw1, Ivo Murrell, Justin Ossevoort, Matt Jackson, Samit Basu, Toon Willems, Michal Hošna, Tiziano Santoro, Berkus Decker, Ross Williams, Geoff Cant, Raphaël Thériault, xales, Zaki, Lena Schönburg, Julian Schmid, Steven Pham, Marcin Kołodziej, Christian Bourjau, Mason Ginter, Benjamin Röjder Delnavaz, ofrighil, Neil Blakey-Milner, Torben Clasen, Nicholas Orta, Senyo Simpson, Luke Yue, Marc-Andre Giroux, Joseph Montanaro, Matěj Volf, Tanner Muro, ZacJW, Yufan Lou, milan, Marty Penner, std__mpa, Gioele Pannetto, Gorazd Brumen, Matt Heise, L0r3m1p5um, notryanb, Zachary Thomas, Niels Abildgaard, ACRL, Sarah Berrettini, Urs Metz, Aleksandre Khokhiashvili, Chris Walker, Michael Mrozek, Christoph Grabo, Mateusz Wykurz, budrick, Jesse Luehrs, Alan O'Donnell, Paige Ruten, Noel, Menno Finlay-Smits, Xavier Groleau, Sam Leonard, Borys Minaiev, Luuk, Hamilton Chapman, Richard Pringle, Marie Janssen, Chris Biscardi, Lucille Blumire, Max von Forell, Colin VanDervoort, Braidon Whatley, Michał Bartoszkiewicz, Matthew T, Daniel Papp, Radu Matei, Ian McLinden, Paul Horn, Olly Swanson, Guillaume E, Daniel Strittmatter, Sean Bryant, Cass, G, Yann Schwartz, Tyler Bloom, Jan De Landtsheer, Mikko Leppänen, Guilherme Neubaner, Manuel Hutter, Shane Lillie, Damir Vandic, Dom, Alex Rudy, Justy, Jim, Adrián Garnier Artiñano, Nyefan, genny, Marco Carmosino, Luke Konopka, callym, Andy Gocke, Chris, Horváth-Lázár Péter, Dimitri Merejkowsky, John VanEnk, David Barsky, Mathias Brossard, Isak Sunde Singh, Evan Relf, Hadrien G., Lennart Oldenburg, Ryan, Alex Krantz, Dave Minter, Joshua Roesslein, Mattia Valzelli, Jean-David Gadina, Matt Campbell, Marcus Griep, Elijah Voigt, Pete Bevin, WeblWabl, Dirkjan Ochtman, belzael, Guy Waldman, johbii, Michał Zalewski, Marky Mark, Xirvik Servers, jatescher, Luiz Ferraz, Aalekh Patel, Matt Jadczak, Johnathan Pagnutti, Henrik Tudborg, Christopher Valerio, Diego Roig, Romain Kelifa, Laine Taffin Altman, Valentin Mariette, Boris Dolgov, Taneli Kaivola, Chris Thackrey, Jörn Huxhorn, Olivia Crain, bbutkovic, Enrico Zschemisch, anichno, hgranthorner, Philipp Hatt, Jelle Besseling, Peter Shih, Seth, Philipp Gniewosz, Antoine Rouaze, Andronik, Jon Gjengset, Daniel Silverstone, villem, Rufus Cable, Yves, Timothée Gerber, Victor Song, old.woman.josiah, Dominik Wagner, Sindre Johansen, Jack Maguire, SeniorMars, DaVince, Geoffroy Couprie, Arjen Laarhoven, Wojciech Smołka, Mario Fleischhacker, Simon Menke, traxys, Herman J. Radtke III, teor, Antoine PESTEL-ROPARS, Beth Rennie, John Horowitz, Andrew Henshaw, Max Bruckner, Adam Lassek, Egor Ternovoi, Mark Tomlin, Duane Sibilly, Josiah Bull, Tyler Schmidtke, ShikChen, Pete LeVasseur, Daniel Wagner-Hall, Brooke Tilley, Malik Bougacha, Antoine Boegli, David White, Ives van Hoorne, Sylvie Nightshade, Ahmad Alhashemi, Marcus Brito, Scott Sanderson, Mark, David E Disch, Mark Old, playest, Eugene Bulkin, Raine Godmaire, Nicolas Riebesel, Nicholas, Jack Duvall, Zoran Zaric, AdrianEddy, Adam Gutglick, avborhanian, qrpth, James Brown, Andy F, Aiden Scandella, Michael Alyn Miller, Santiago Lema, Integer 32, LLC, Jake Demarest-Mays, Yuriy Taraday

Early access (152 days early) sponsored by Depot

Accelerate your Docker image builds and GitHub Actions workflows. Easily integrate with your existing CI provider and dev workflows to save hours of build time.

Start a free trial · See the policy

I have long been at war against Rust compile times.

Part of the solution for me was to buy my way into Apple Silicon dreamland, where builds are, like… faster. I remember every time I SSH into an x86_64 server, even the nice 64-core ones.

And another part was, of course, to get dirty with Rust itself.

I wrote Why is my Rust build so slow?, which goes in-depth into rust build performance, down to rustc self-profiling even!

I wrote an entire series about nixpkgs, I switched to earthly, then it died, so I switched off of earthly, and now, well now I’m like everyone else, humbly writing Dockerfiles.

But no. No, I’m not like everyone else. They said Rust wasn’t dynamic linking friendly well I made it play nice with tools like dylo and rubicon, solving issues like “woops, tokio thinks there’s one distinct runtime per dynamic object”.

And I was able to ship the software that powers my website, which is called home and is now open-source, by the way, as a collection of dynamic libraries, which was great for fast deploys, since each library made for a natural container image layer. No code changes = re-used layer, as simple as that.

And then I stopped using dynamic linking for my blog because I thought rustc’s built-in support for dynamic linking might work for me, which involved removing all my custom stuff, (and finally reverting to upstream tokio, which was a relief), and when I realized that, haha no, rustc’s dynamic linking support does NOT work for me at all, then I didn’t feel like going back, and I decided to attack the problem from another angle.

The main reason I care about build times is because I want to iterate quickly.

Despite Rust’s “if it compiles it probably runs, and if it runs it probably does the right thing” ideal, I want to be able to make changes to my website and see the result fast enough.

And when I’m done with changes locally and I want to deploy them, I want CI to run fast! So that it can be packaged up as a container image, and deployed all around the world, to however many PoPs I’ve decided I can afford this month, and then Kubernetes takes care of doing the rollout, but let’s not get our paws dirty with that.

That means I end up building my website’s software a lot! And I’ve had a chance to look at build timings a lot! And, well, I have a couple of big C dependencies, like zstandard or libjxl, a couple of big Rust dependencies like tantivy, and… a couple other dependencies that showed up a lot, like syn and serde.

I’ve done the homework before, in The virtue of unsynn: the syn crate is often in the critical path of builds — using causal profiling, we established that making syn magically faster would in fact make our builds faster.

And I say “our builds”, comrade, because if you go check now, there’s a very solid chance your project depends on syn.

My CMS, home, depends on syn 1 through 6 different paths…

…and on syn 2 through 25 different paths!! That’s not a mistake!

There’s two versions of thiserror, clap of course, async-trait, displaydoc, various futures macros, perfect hash maps, tokio macros, tracing, zerovec, zeroize, zerofrom, yoke, so and so forth, and of course, serde.

And… I can see myself replacing some things on that list, but serde… serde’s a tough one. As of May 2025, syn is the most downloaded crate ever at 900 million downloads, and serde is a close eleventh, with 540 million downloads.

These crates’ popularity is well-deserved, due to how useful they are. But the more I looked into them, and the more I became dissatisfied.

A person’s natural reaction to having a crate that builds slowly might be to split it into multiple crates. But with serde’s approach, that does not make much of a difference.

And to understand why, we must talk about monomorphization.

Let’s say you have a bunch of types. Because you have an API and you have JSON payloads, and, well, you have a catalog:

…and it keeps going:

And going:

And going. Let’s say because you have good instincts, you’re putting all that in a bigapi-types crate.

Then, for narration purposes, you have this in a bigapi-indirection crate:

And finally, you have an application, bigapi-cli, that merely calls do_ser_stuff:

If we’re going solely by quantity of code, the CLI should be super fast to build, indirection as well, it’s just a couple calls, and bigapi-types should be super slow, since it has all those struct definitions and a function to generate a mock catalog!

Well, on a cold debug build, our intuition is correct:

On a cold release build, it’s very much not:

indirection takes the bulk of the build times, why? Because serde_json::to_string_pretty and serde_json::from_str are generic functions, which get instantiated in the bigapi-indirection crate.

Every time we touch bigapi-indirection, even just to change a string constant, we pay for that cost all over again:

If we touch bigapi-types, it’s even worse! Even though all I did was change a string value in generate_mock_catalog, we’re good to rebuild everything:

That’s monomorphization: all generic functions in Rust are instantiated: the generic type parameters like T or K or V are replaced with concrete types.

We can see just how often that happens with cargo-llvm-lines:

Cool Bear's hot tip

Omitting --release gives slightly different results — LLVM is not the only one doing optimizations!

We have about 40 copies of a bunch of different generic serde methods, specialized for our given types. This makes serde fast, and it also makes our build slow.

And our binary a bit plus-sized:

This is fundamental to how serde works. miniserde, same author, works differently, but I can’t test it, because neither uuid nor chrono have miniserde feature, and I can’t be bothered to fork it.

I adopted a different strategy. I figured that a second serde would be a very hard sell. It would have to be so much better. The first one was so good, so adequate, that it would be very difficult to convince people to move to something different!

So I decided that whatever I replace serde with, it will not be faster, it will have other characteristics that I care about.

For example if we fork our program to use facet instead of serde:

To these:

The indirect crate now uses facet-json for JSON, and facet-pretty instead of Debug:

And then let’s assume we make a new CLI that depends on that indirect crate, How does it compare to our older, serde-powered version?

I want to mention that I’m not entirely happy with the numbers we’re going to see, but I thought it was important a factual survey of the current state of facet, and use the frustration that it generates in me as motivation to keep working on it.

But hey, as of yesterday, we’re faster in one benchmark against serde-json! If you serialize a 100 kilobyte string, then we only take 451 microseconds on whatever machine CodSpeed uses:

Back to our sample program, things don’t look as good:

Our program is even bigger than before.

And this time, it’s harder to figure out why. Trying out cargo-bloat on the serde version, we can clearly see where all the code is going:

But on the facet version… std is the main offender?

Followed closely by our types crate, facet_deserialize, our indirection crate, t hen facet_json, facet_core, and others.

Interestingly, the code is spread rather well across different crates. What about build times? Do those pipeline at all?

On a cold debug build, bigapi-types takes longer, but it doesn’t block others from building the whole way:

On a cold release build, we can see that facet-deserialize, pretty, serialize, and json are all able to build concurrently! And any crate that is using indirection could also build alongside it — we can tell from the purple color there.

So, bigger binaries and more build times, at least for now. What do we get for that?

For starters, I don’t know if you noticed, but we lost the Debug implementation: we’re not using it to print the deserialized data, we’re using facet-pretty:

For a one-time cost, we get nice formatting with colors, and everyhting. It even supports redacting information!

Don’t want street numbers to show up in logs? Mark them as sensitive!

You can disable colors of course, and because facet-pretty relies on data rather than code, you could limit the depth of the information it prints — something the Debug trait definitely isn’t flexible enough for.

And that’s the whole idea of facet: the derive macro generates data instead of code.

Well, it also generates a lot of virtual tables so you can interact with arbitrary values at runtime, and those show up in cargo-llvm-lines:

Although I suspect there’s some low-hanging fruits left there in terms of binary size optimization because from the beginning, I have spent a couple hours focused on that, and that’s it.

So our executable shows nicely colored structs using the data exposed by facet, and using that same data, facet-json is able to serialize and deserialize our data, to and from the JSON format.

serde is the clear winner in terms of speed, I’ll let you check the up-to-date benchmarks for exact numbers, but at the time of this writing, we’re seeing facet-json be anywhere from 3 to 6 slower than serde-json:

Which doesn’t even look that bad if you put it on a log scale!

I wish I had the time to do something more rigorous or more automated, but alas, deadlines — for now this will have to do, and you’ll make me the promise that you will take those silly microbenchmarks with a grain of salt.

Because as far as I, the end-user, can tell, they’re both instant:

What about warm builds? Warm release builds, because we can barely see anything in debug builds — our big API isn’t that big, actually.

When changing a bit of bigapi-types-serde, we see this:

And when changing a bit of bigapi-types-facet, we see that:

We find ourselves in a somewhat similar situation, actually — those take approximately the same time.

Using -j1 like I did in my unsynn article, makes the situation even worse.

Hey, I can’t use just the tricks that make my crate looks good.

Now, I’m pretty optimistic about this, honestly, because I think we went a bit wild adding a bunch of market traits, and re-implementing standard traits for tuples if all the elements of a tuple implement that trait, for example — that’s not free!

Looking at cargo-llvm-lines again:

Why is call_once accounting for 33 thousand lines of LLVM IR? Why is set_numeric_value, which basically converts u64s into u16s and vice versa, account for over 6% of the total code? See, I wish I had time to look into it more right now, but it gives us kind of a baseline to go from, right?

Because the basic idea remains: it is a fixed cost. There’s only a handful of small generic functions in facet.json — very quickly, everything goes into reflection territory.

It’s not monomorphization at play — we’re using data generated by the derive macro, with structures like StructType:

With each field having an offset, and a shape of its own:

There are function pointers all around, to be able to invoked Display implementations, FromStr, comparison, etc. It’s all designed so that you can write code that is compiled once, which runs against arbitrary types.

Of course, that would require unsafe code to read and write from arbitrary memory locations.

So there’s a safe layer on top called facet-reflect, which lets you peek at values, for example we can navigate through these structs:

…to extract some field:

facet supports rename and rename_all, and it does so at the reflection level, not at the serialization level.

It also supports flatten!

On the write end of things, facet-reflect lets you build objects from scratch:

Here we’re showcasing bits of the API we use when we don’t know the shape, like iterating through fields, and also when we know the shape of some bit. We honestly Could’ve used set directly in that case, like so:

It’s really a matter of which parts of your program you statically know about, and which parts you don’t.

Looking at this, I’m thinking about several things: debug printing for sure, but also structured logging (a-la tracing), generating mock data for tests, and so on.

Even just for the serialization usecase, there’s much to be excited about.

Because we’re generating code and not data, entirely different JSON parsers can format on an even playing ground — they all have access to the exact same data.

For instance — serde-json is recursive.

If you, like me, have the darkness in your heart, it’s relatively easy to come up with a program that makes serde-json blow up your stack.

First you need a pretty large struct…

…then you generate a bunch of nested JSON…

And you have serde-json parse it!

And boom, stack overflow:

In release, the codegen is more efficient, so we need a bit more padding:

But the result is much the same!

LLDB helpfully shows us the stack trace:

To avoid that problem and since we were going to be slower anyway, facet-json takes an iterative approach instead.

We need to derive Facet instead of Deserialize, and mark each default field as default (there’s no implicit behavior for Option at this time):

And then use the from_str from facet-json, that’s it:

It works:

And you know what’s fun? The facet version, which works, is faster than the serde-json version, which crashes:

This means nothing, probably just macOS faults being slow, but I chuckled.

Like we’ve seen, facet-json, today, is iterative rather than recursive, and this comes at a cost. But there’s nothing preventing someone from coming up with a recursive implementation that’s faster.

We don’t use SIMD yet, but someone should! We’re not doing a tape-oriented approach to JSON decoding, but I hear it’s pretty cool!

I’d like the default facet-json implementation to remain flexible — did I mention it has nice errors?

I didn’t want to linger on that but, it’s nice to know where our tax dollars, I mean, our build minutes go, y’know?

Like I said: I want facet-json to remain flexible: I think it should support trailing commas if the deserializer is configured that way. I think it should support inline comments, again, if enabled in the configuration.

Also, I think there’s a way to support asynchronous I/O. After all, why not? All the state is already on the heap, pinned — an async runtime should have no issues with that.

In an opposite direction, if we find that using the heap is slow, we should try alternative allocators — arena allocators, bump allocators maybe? Or just something general-purpose but a little more modern than the system allocators. I haven’t done any benchmarks with jemalloc, mimalloc, or any of the others.

Back to flexibility, one cool thing we could do is have XPath-style selectors when deserializing, filtering nested data, maybe I only want the first 10 children of an array of a struct field of a struct field — the deserializer would do the minimum amount of work required to get me that, while still being able to validate that the data has the right shape — something a lot of people appreciate serde for.

And finally, a pipe dream of mine: Just-In-Time compilation (JIT) to enhance deserialization speed. Not just to be able to take advantage of the best possible instructions at runtime, but also to take advantage of what we observe from the data: if the object keys always go “one, four, two”, in that exact order, with “three” missing, then we can generate code at runtime optimized for that — but only once we’ve observed that pattern.

This is just the tip of the iceberg of what we can do with reflection.

Right now, we’re hitting limitations in the language: typeid isn’t const, and comparing two typeid in const is impossible. Cycles in constants are not supported, and there is no plan to support them for now — this means we have to add indirection through function pointers. Specialization is unstable, so we have to use autoderef tricks, inspired by the spez crate.

There’s a lot that isn’t ideal, but it’s such fun redesigning the entire ecosystem: we have crates for JSON, YAML, TOML, XDR, some work in progress for KDL, XML is up for grabs — and no @ or $-prefix required this time, let’s make them first-class citizens in facet.

I’d like a nice assertion library! Imagine facet-pretty but in your tests? I’d like… a property testing library based on facet. We know what we can mutate, where it is, we can check for invariants — with a few more custom attributes we could give enough information to know which values to generate instead of running the struct-level invariants method in a loop.

And something we haven’t explored at all yet? Facet for functions: manipulating values is all fun and games, and I’ve been fantasizing about an HTTP interface that lets me inspect the entire state of my program, but the next step is obviously an interactive REPL! Exposing functions that we can call dynamically, on top of which we could also build RPC, all with the same great tooling that is becoming a standard in the facet ecosystem.

And you know what’s a little like serialization and deserialization? FFI! Exchanging values with other languages, or maybe even, with databases — why couldn’t we have facet-sqlite? facet-postgres? These seem like natural fits.

There’s still a lot to do around here, and the churn is real — we’ve had major rewrites every other week — but I think the potential is enormous. Come hack with us! It’s fun!

Comment on /r/fasterthanlime