DEV Community: Justin - FromTheArchitect

Excavating Legacy ETL: The AI Never Asserts a Fact It Could Look Up

Justin - FromTheArchitect — Tue, 25 Aug 2026 23:00:00 +0000

Every platform modernisation programme has the same first act, and it is never the interesting one. Before anyone gets to write a line of dbt, somebody has to work out what the current thing actually does.

In the SAP BusinessObjects Data Services case — BODS, if you've had the pleasure — that means inheriting a few hundred dataflows whose authors left the organisation years ago. The logic lives in exported XML. The business rationale lived in the heads of people who are now at other companies. Nobody can tell you which flows are duplicates, which ones nothing reads any more, or what any given one is for. There is a spreadsheet somewhere claiming to be an inventory. It is wrong in ways nobody can enumerate.

This is archaeology. It is also, on paper, the exact shape of problem that large language models should eat for breakfast: mountains of semi-structured text, pattern recognition, summarisation into prose a human can read.

So I tried the obvious thing, and the obvious thing failed in a way that turned out to be the most useful finding of the whole exercise.

Why pointing an LLM at the XML doesn't work

Paste a BODS dataflow export into a chat window and ask what it does, and you get an answer. It is fluent, well-structured, and mostly correct.

Mostly is the problem.

The output is a blend of two very different things: columns and mappings that are genuinely in the XML, and plausible-sounding business context that is not. AMOUNT_USD is a currency-normalised revenue measure — fine, that's a reasonable inference. But it will also tell you, with identical confidence and no change of register, that the flow runs nightly, or that STATUS follows the standard active/inactive convention, or that a column feeds the finance dashboard. None of those facts are in the file. They are priors about what ETL usually looks like, rendered in the same voice as the facts.

For most LLM tasks that's an acceptable cost. For this one it's fatal, because on a migration the facts are the deliverable. A spec that gets the join predicate subtly wrong doesn't fail loudly — it produces a fact table where every row has silently been stamped with the wrong foreign key. You find out during reconciliation, six weeks and a lot of goodwill later.

The failure mode isn't that the model can't read the XML. It reads it fine. The failure mode is that the output gives you no way to tell which sentences came from the file and which came from the model's expectations, and a human reviewer holding a 40-page spec cannot re-derive every claim by hand. That's the whole reason you asked for help in the first place.

So I stopped trying to make the model more accurate, and changed what it was allowed to do.

The one rule the whole design hangs on

The system I ended up with — etl-archaeologist — is built around a single constraint:

The AI never asserts a fact it could look up. The deterministic layer never interprets.

Two layers, one hard boundary. A plain Python layer parses the BODS exports into a fact store: sources, targets, columns, datatypes, mapping expressions, column lineage, join predicates, cross-flow dependencies. No model involved. Same input, same facts, every time.

An agent layer then reads that store and writes the parts a script genuinely cannot: what the pipeline is for, what the grain and keys probably are, whether to lift-and-shift it or redesign it, whether to migrate it at all.

That split sounds like process pedantry. It isn't — it's what makes the output reviewable. Every factual section of a finished spec traces to a row in a database. Every interpretive sentence carries (inferred — confirm with SME). A reviewer reading the spec knows, at every line, whether they're checking a fact or challenging a judgement. Those are completely different cognitive tasks and mixing them is what makes AI-generated documentation exhausting to review.

Layer one: facts

The extractor is unglamorous on purpose. lxml in, DuckDB out, about 150 lines:

CREATE TABLE dataflow      (df_name TEXT, job TEXT, project TEXT, source_file TEXT);
CREATE TABLE reads         (df_name TEXT, object_key TEXT, datastore TEXT, table_name TEXT);
CREATE TABLE writes        (df_name TEXT, object_key TEXT, datastore TEXT, table_name TEXT);
CREATE TABLE column_def    (df_name TEXT, col_name TEXT, datatype TEXT, mapping_text TEXT);
CREATE TABLE column_lineage(df_name TEXT, target_col TEXT, src_table TEXT, src_col TEXT);
CREATE TABLE source_column (df_name TEXT, datastore TEXT, table_name TEXT, col_name TEXT);
CREATE TABLE predicate     (df_name TEXT, predicate_text TEXT);
CREATE TABLE predicate_ref (df_name TEXT, src_table TEXT, src_col TEXT);

Predicates get stored twice, which looks redundant until you need it. predicate keeps the join or filter expression as verbatim text, because that's what has to be reproduced exactly on the target platform. predicate_ref holds the same expression exploded into the individual source columns it touches — the extractor regexes table.column references out of the predicate and keeps the ones that resolve to a real source table. Without that second table, any column used only as a join key looks unreferenced, and the dead-code query below would confidently recommend dropping the very columns holding the estate together.

The one piece that needed actual thought is column lineage. A BODS dataflow isn't a single mapping step; it's a chain of transforms, and most columns pass through several of them untouched before landing in the target. If you only record each hop, the final target column's origin is a graph walk away. So the extractor threads origins forward hop by hop — a mapped column records the source columns its expression references, a generated column (a surrogate key, an SCD date) records that it was generated, and a pass-through column inherits whatever the upstream column already knew:

else:  # pass-through: inherit the upstream column's origin
    prev = acc.get(frm, {"src": set(), "expr": "«pass-through»", ...})
    info = {"src": set(prev["src"]), "expr": prev["expr"], ...}

By the last transform, every target column knows the source columns it came from and the expression that produced it. That's the fact an SME can confirm or deny in five seconds, and it's the one an LLM is most tempted to smooth over.

The thing I underrated going in: this layer is not just an input to the AI. It's the test oracle. Because it's exact and reproducible, you can later use it to check the agent's homework — which turns out to be the entire trick.

Layer two: the questions one file can't answer

A second deterministic pass looks across all pipelines at once, because there is a whole class of question that no amount of careful reading of a single export can answer. "Is this a duplicate?" is unanswerable from inside the file.

Four queries do most of the work. Dependencies are a join between who writes an object and who reads it. Duplicate candidates are pairs of flows writing the same target, scored by column-set Jaccard overlap. Dead-flow candidates are flows nothing else reads. And dead code — my favourite, because it's pure profit — is source columns pulled into a flow and then never referenced by any mapping or any predicate, which is where predicate_ref earns its place:

SELECT sc.df_name, sc.table_name, sc.col_name
FROM source_column sc
WHERE NOT EXISTS (SELECT 1 FROM column_lineage cl
                  WHERE cl.df_name=sc.df_name AND cl.src_table=sc.table_name AND cl.src_col=sc.col_name)
  AND NOT EXISTS (SELECT 1 FROM predicate_ref pr
                  WHERE pr.df_name=sc.df_name AND pr.src_table=sc.table_name AND pr.src_col=sc.col_name)

Across seven pipelines that found seven columns being extracted for no reason at all. On a real estate that number is a rounding error on the migration effort you don't have to spend.

Worth being precise about what "dead" means here, because it's narrower than it sounds. The column never reaches the target, so nothing downstream of this flow can be reading it — that part is safe. What it doesn't mean is that the column is dead in the source system. Another flow may well use it, and something outside BODS almost certainly does. The finding is "stop pulling this column into this pipeline", not "drop this column".

Jaccard — intersection over union — is about as crude as similarity metrics get, and I chose it for that. It needs no tuning and no threshold anyone will argue about in a workshop, and the hard part of the question has already been answered by the join: these two flows write the same table. The score only has to rank what's left for a human to look at. I don't know it's the right metric. I know it hasn't yet surfaced a pair that wasn't worth two minutes of attention.

Notice what all four have in common: they're detection, not judgement. Exact, exhaustive, auditable, and completely free of opinion. Which is exactly what you want feeding the next layer.

Layer three: making "look it up" cheaper than guessing

The boundary between the layers only holds if the agent has an easy way to actually look things up. So the fact store — the DuckDB file — gets a fact server in front of it: a read-only MCP interface exposing list_pipelines, get_pipeline_facts, rationalisation_report, and a general query for anything the first three don't cover. Store is the data; server is the only door the agent gets to walk through, and the door is deliberately one-way:

def _query(sql: str):
    s = sql.strip().lower()
    if not (s.startswith("select") or s.startswith("with")):
        raise ValueError("read-only fact store: only SELECT / WITH queries are allowed")
    return _q(sql)

This is the part I'd most encourage people to steal. Telling a model "don't hallucinate" is a wish. Giving it a cheap, obvious, structured way to get the real answer is a design. When the ground truth is one tool call away, the model reaches for it — and when it does invent something anyway, the same tool is sitting right there to catch it.

Layer four: the part that actually needs judgement

With facts handled, what's left for the agent is genuinely interesting, and it's more than prose polish.

Take the dead-flow signal. The detector flagged four candidates, all with identical structural evidence: nothing else in the corpus reads your output. Deterministically they are indistinguishable. And yet the right answer differs for every one of them, because "no downstream consumer in the BODS metadata" means completely different things depending on what the flow is:

A monthly sales aggregate with no downstream reader isn't dead. It's terminal — the consumer is a BI tool the fact store cannot see. Keep, and go confirm the dashboard exists.
A conformed product dimension with no downstream reader is the same story, only more so — a conformed dimension exists precisely so that things outside the warehouse can slice on it. Keep, verify.
A customer SCD2 history table — same shape again. It's a history mart. Terminal by design.
A two-column pass-through in an isolated Legacy project, reading a source table literally named OLD_ACCOUNTS, writing to a staging area, referenced by nothing: that one is a genuine orphan. Retire.

One signal, four different verdicts, and the discriminator in every case is context that lives nowhere in the metadata — naming conventions, which datastore the target sits in, what kind of table it is, whether "terminal" is normal for that kind of table. That's the work. The detector found the candidates; the agent adjudicated them; and it overruled the detector three times out of four, which is precisely what you want a judgement layer to do.

The second thing the agent is good at is smelling migration risk in an expression. From the order fact load:

ifthenelse(ORDERS.CURRENCY = 'USD', ORDERS.AMOUNT, ORDERS.AMOUNT * 0.66)

A hard-coded FX rate. One rate, for every currency, for all time. The agent flagged it — and then, correctly, refused to fix it: preserve 0.66 exactly through cutover so reconciliation is byte-for-byte, and raise the rate-table question as a deferred redesign afterwards. That's the right call and it's a slightly subtle one. The instinct on seeing bad code is to improve it. The instinct that survives a migration is to reproduce it faithfully and change it in a separate, visible step.

The find I liked most, though, came out of the duplicate pair. Two flows both writing DIM_CUSTOMER, 60% column overlap, obviously redundant. But look at how each one derives STATUS:

DF_DIM_CUSTOMER          ifthenelse(CUSTOMER.ACTIVE_FLG = 'Y', 'ACTIVE', 'INACTIVE')
DF_DIM_CUSTOMER_REFRESH  ifthenelse(CUSTOMER.ACTIVE_FLG = 'A', 'ACTIVE', 'INACTIVE')

Same column, same source, different sentinel. 'Y' in one, 'A' in the other. Merge those two flows by picking whichever expression you happened to be looking at, and you silently flip the active/inactive status of some portion of the customer base. It's a two-character difference across two files, and it went straight into the report as a hard blocker on the merge. That's the class of thing manual archaeology misses at 3pm on a Thursday, and it's a good illustration of what the two-layer split buys you: the comparison was deterministic, the significance was judgement, and neither layer could have produced the finding alone.

Fixed templates, because consistency is a feature

Every agent-authored artefact fills a fixed template — one for pipeline specs, one for the portfolio report, one for verification verdicts. Same headings, same order, every run, with - none where a section is empty rather than the section quietly vanishing.

This is a small thing that pays continuously. Consistent structure means specs diff cleanly — against each other and against their own previous versions — reviewers build muscle memory, and changing the house style is a one-file edit instead of a re-prompt. Mostly it kills a whole category of drift you'd otherwise catch by feel, late, in review.

The gate: assume the spec is wrong

Here's the honest bit. Everything above still leaves you with output from a non-deterministic process. Constraints reduce the error rate; they don't take it to zero. Trusting the specs because the architecture is nice would be exactly the mistake I started out trying to avoid.

So the last step is an adversarial verification pass. One subagent per spec, with an explicit brief: try to break it. Assume every factual claim is wrong until ground truth proves it right. Do not read the spec and then go looking for support — establish ground truth independently first, from the fact store and the raw XML, then extract every factual claim from the spec and classify it: SUPPORTED, UNSUPPORTED, CONTRADICTED, or MISLABELLED.

The output is a claim-by-claim table with a PASS/FAIL verdict:

Claim	Status	Evidence
Dead code: `OLD_ACCOUNTS.CLOSED_DT` read but never mapped	SUPPORTED	facts `unused_source_columns = [{OLD_ACCOUNTS, CLOSED_DT}]`; XML declares `CLOSED_DT` in `<DISource>` schema but it is absent from the `Query` transform output schema
Join/filter predicates: none	SUPPORTED	facts `predicates = []` — genuinely empty. The added "None" line is accurate, not invented

That second row is the one that made me trust the design. The verifier didn't just check that the stated facts were right; it checked that a claim of absence was honest. "There are no filters here" is exactly the kind of statement that's easy to write and easy to be wrong about.

The obvious objection is that I've now got a non-deterministic process checking a non-deterministic process, and that's fair. The verifier is an agent too; it can miss things. What it can't easily do is miss things in the same direction as the author, because it isn't reading the author's reasoning — it goes back to the fact store and the raw XML and builds its own picture first. Two independent passes over the same ground truth have to fail in correlated ways to let an error through, which is a meaningfully harder thing to do by accident. That's a reduction in risk, not a proof of correctness, and it's exactly why the gate needs calibrating rather than trusting.

Which is what the planted errors are for. Two things came out of running the gate for real. First, on a deliberate planted-error test it caught every injected error while still passing the clean spec — so it isn't just manufacturing objections to look diligent. Second, and more usefully, it caught a defect I wasn't looking for: a spec that had been correct when written and had gone stale, because a new pipeline was added to the corpus afterwards and its dependency list no longer reflected reality.

That reframed the whole thing for me. I built the gate expecting to catch hallucination. What it actually earns its keep on is staleness — documentation drifting behind the source. Which, if you think about it, is the failure mode that has plagued every hand-written data dictionary ever produced. The difference is that here regenerating and re-verifying costs minutes, so the documentation can be treated as derived rather than authored, and re-derived whenever the source moves.

What I'd tell someone starting this

Split facts from judgement before you write a single prompt — not as a review step afterwards, as an architecture. If a script can determine it, a script should determine it, and the model should be reading the script's output rather than the raw source. Every other decision here fell out of that one, including the ones I didn't see coming.

The corollary is that ground truth has to be cheap to reach. A read-only fact server does more for accuracy than any amount of prompt engineering about accuracy, because it changes the economics rather than the instructions: guessing has to be the more expensive option, or eventually it won't be the one taken.

Then label inference at the sentence level. A disclaimer at the top of a document is decoration — a reviewer stops seeing it by page two. (inferred — confirm with SME) sitting in front of the specific claim is a routing instruction: this line is for the data owner, that line is for the migration engineer.

And when you verify, verify against the source rather than the summary. A checker that reads the spec and goes looking for support will find it every time; one that reconstructs ground truth independently and then hunts for contradictions is doing a completely different job, and only the second one tells you anything you didn't already believe.

Then the caveats, because I said I'd be honest about them.

The corpus I've been describing is synthetic — deliberately planted with a known answer key so I could measure whether the method recovers the truths rather than just producing confident-looking documents. It's a test of the approach, not a sample of any real estate, and no production data goes anywhere near it. Real BODS XML also nests its attributes differently to my samples, so pointing this at a live export means recalibrating the XPath in the extractor once. That's the only part that changes — but it does have to change, and I'd expect it to be a fiddlier afternoon than it sounds.

The larger limit is that detection only sees what BODS records. It cannot see Tableau, Athena, or the analyst with a scheduled query nobody remembers writing. That's precisely why every retire and merge recommendation is gated on a human plus external-consumer evidence rather than fired automatically — the tool is allowed to nominate, never to decide.

None of this made the model smarter. It made the model's job smaller. The interesting judgement — is this dead, is this a duplicate, is that hard-coded rate a bug or a contract — is exactly as hard as it was before, and it's still the reason anyone is doing the work. What changed is that it's no longer tangled up with a hundred low-level facts a database can answer exactly, and a reviewer can finally tell the two apart at a glance.

Archaeology, done properly, is mostly about knowing which layer you're digging in.

The etl-archaeologist tooling was written with Claude Code — the co-author trailers are in its commit history. The two-layer split and the constraint it hangs on are mine; most of the implementation is not. I didn't keep the prompt transcripts, which for a post arguing you should be able to audit what the AI did is an omission I notice.

Two YubiKeys, One Prompt Too Many

Justin - FromTheArchitect — Thu, 20 Aug 2026 23:00:00 +0000

I carry two YubiKeys. One lives on my keyring, one lives in a drawer, and both are enrolled everywhere that matters. A hardware token with no backup is a single point of failure you have chosen on purpose.

For months I had a small irritation I never bothered to chase. Some days git push asked for my PIN, I typed it, and it worked. Other days it asked for my PIN, failed, and then asked again, and the second one worked. Same command, same repo, same laptop. The variable turned out to be which of the two keys happened to be in the USB port.

It is a five-second annoyance — and I hit it maybe fifteen times a day.

What was actually happening

Both keys are sk-ssh-ed25519 credentials, and both get loaded into the gnome-keyring agent automatically:

$ ssh-add -l
256 SHA256:5imEVNLX...  yk1-12345678 (ED25519-SK)
256 SHA256:ATug2xnP...  yk2-12345679 (ED25519-SK)

I had no ~/.ssh/config at all. Without one, ssh offers the agent's keys in the order the agent hands them over, and the server takes the first one it recognises. GitHub has both of these enrolled, so it accepts the first offer every time. Which means ssh commits to yk1 before anything has checked whether the token in the port can actually satisfy it.

With yk1 in the port, that guess is right and you see one prompt. With yk2 in the port, ssh asks the attached token to sign for a credential it has never heard of. You get a PIN dialog, you type your PIN, it fails, ssh falls through to the second key, and that one works.

The detail that makes this worse than it needs to be is how these keys were generated. Both are resident keys with user verification required. The flags byte in the private key blob is 0x25, which decodes, using the constant names from OpenSSH's sk-api.h, as:

0x25 = SSH_SK_USER_PRESENCE_REQD | SSH_SK_USER_VERIFICATION_REQD | SSH_SK_RESIDENT_KEY

USER_VERIFICATION_REQD is what turns this from invisible into annoying, and the ordering that causes it sits above the token rather than inside it. Before ssh can request an assertion at all, the client has to obtain a PIN/UV auth token from the authenticator, and that is the step that puts the dialog on screen. Only after you have typed the PIN does the assertion request go down the wire, and only then does the key answer that it has never held this credential. Without the flag, the wrong-key attempt would fail silently and I would never have noticed.

The information was already there

Here is the part I feel slightly silly about. Look at the comments on those keys again:

yk1-12345678
yk2-12345679

Past me, generating these, had already written the serial number of the owning YubiKey into each key's comment. The mapping from "which token is plugged in" to "which key can possibly work" had been sitting in ssh-add -l output the entire time, and I had spent months not reading it.

OpenSSH gives you exactly the right hook for this. Match exec runs a shell command and applies the block if it exits zero:

Match host github.com,gitlab.com exec "%d/.ssh/yk-plugged 12345678"
    IdentityFile ~/.ssh/id_ed25519_sk_yk1
    IdentitiesOnly yes

Match host github.com,gitlab.com exec "%d/.ssh/yk-plugged 12345679"
    IdentityFile ~/.ssh/id_ed25519_sk_yk2
    IdentitiesOnly yes

Note the host criterion, because leaving it off is the mistake that turns a papercut fix into a bad afternoon. Match exec on its own applies to every destination, and the first block that matches pins IdentitiesOnly and a single IdentityFile for whatever you happen to be connecting to. Every other host, with every other key, stops authenticating.

IdentitiesOnly yes is the load-bearing line, and it is the one people leave out. I had assumed the name meant "ignore the agent". The -v output says otherwise: the agent still returns both keys. What the option actually restricts is which of them are eligible to be offered: only the ones whose public half matches an IdentityFile entry in scope. Two keys in, one considered.

That matching is also why the IdentityFile paths have to exist on disk even though the keys live in the agent. Since these are resident credentials, it is entirely possible to arrive on a fresh machine, pull them off the token with ssh-add -K, and have nothing in ~/.ssh at all. In that state the blocks match nothing and do nothing, which is confusing for about ten minutes.

If neither serial matches, no block applies, and you fall back to the old behaviour of trying everything. That is the correct failure mode: a config that gets worse than no config when it does not understand the situation is a config you will eventually curse. If both keys happen to be attached, both blocks match and both IdentityFile entries land in scope (IdentityFile accumulates across directives, unlike most keywords), so you are back to a coin flip and possibly one doomed prompt. Correct behaviour, but it does mean the fix looks broken if you plug in the drawer key without unplugging the keyring one.

The bit that was actually hard

Match exec runs on every single ssh invocation. Every git fetch, every scp, every ssh -G a tool makes to introspect your config. Whatever goes in there has to be cheap.

My first instinct was to read the serial out of sysfs, the way you would for most USB devices. That does not work:

$ cat /sys/bus/usb/devices/3-4/serial

$ cat /sys/bus/usb/devices/3-4/product
YubiKey OTP+FIDO+CCID

Empty. A YubiKey does not publish its serial in the USB device descriptor. You have to ask the device over one of its application interfaces, which in practice means ykman:

$ ykman list --serials
12345678

That call takes about 350 milliseconds on my laptop, most of it spent bringing the CCID interface up. Two Match exec blocks means two invocations, so seven tenths of a second on every git operation in order to save five seconds fifteen times a day. The arithmetic does not work.

So the helper caches. The question is what to key the cache on, and "a timeout" is the wrong answer. A 60-second TTL buys you either a minute of wrong answers after a swap or a minute of pointless ykman calls, and you get to choose which.

There is a better key available. The Linux USB stack assigns a device number on enumeration, and it increments. Swap tokens, even into the same physical port, and the number changes:

# yk1 attached
/sys/bus/usb/devices/3-4/  busnum=3 devnum=10

# swapped to yk2, same port
/sys/bus/usb/devices/3-4/  busnum=3 devnum=11

# swapped back to yk1
/sys/bus/usb/devices/3-4/  busnum=3 devnum=12

That gives a cache key derived from the thing whose change I care about. Reading it costs a cat of a sysfs file. No timeout, no staleness window, no daemon watching udev.

#!/bin/sh
# Exit 0 if a YubiKey with the given serial number is attached.
set -eu
want=$1

# Fingerprint the attached Yubico (vendor 1050) USB devices.
fp=
for d in /sys/bus/usb/devices/*/; do
    [ -r "$d/idVendor" ] || continue
    [ "$(cat "$d/idVendor")" = 1050 ] || continue
    fp="$fp$(cat "$d/busnum")-$(cat "$d/devnum"),"
done
[ -n "$fp" ] || exit 1  # nothing attached; no point spawning ykman

# Deliberately no /tmp fallback; see below.
cache=${XDG_RUNTIME_DIR:?}/yk-serials
if [ -r "$cache" ] && [ "$(head -n1 "$cache")" = "$fp" ]; then
    serials=$(tail -n +2 "$cache")
else
    serials=$(ykman list --serials 2>/dev/null) || serials=
    # Don't cache a failed lookup (busy pcscd, ykman missing); it would stick
    # until the next replug.
    if [ -n "$serials" ]; then
        tmp=$cache.$$
        (umask 077; printf '%s\n%s\n' "$fp" "$serials" >"$tmp") && mv -f "$tmp" "$cache"
    fi
fi

printf '%s\n' "$serials" | grep -qx -- "$want"

Two details in there are scar tissue rather than design. The early exit when no Yubico device is present keeps ykman from being spawned at all on a laptop with nothing plugged in, which is the common case when I am working offline. And declining to cache an empty result matters because a transient failure — a busy pcscd, a ykman that is not installed yet — would otherwise be cached against a fingerprint that stays valid until the next replug.

The hard requirement on XDG_RUNTIME_DIR is there for a related reason. It is torn down at logout, so the cache can never outlive a boot. Fall back to /tmp on a system where /tmp survives a reboot and the fingerprint stops meaning anything: device numbers are allocated from the low end again after every boot, so a stale entry has a very good chance of matching one.

Warm, the helper returns in about 9ms. Resolving the whole config with both Match blocks in it (ssh -G github.com) comes to 87ms, the remainder being ssh's own startup rather than anything I added. Cold, on the first connection after a swap, you pay the 350ms once.

Checking it actually works

ssh -v is useful here because it prints the whole decision path, key by key, rather than just the result. With the backup key in the port:

debug1: get_agent_identities: agent returned 2 keys
debug1: Will attempt key: ~/.ssh/id_ed25519_sk_yk2 ED25519-SK
debug1: Offering public key: ~/.ssh/id_ed25519_sk_yk2 ED25519-SK
debug1: Server accepts key: ~/.ssh/id_ed25519_sk_yk2 ED25519-SK
Authenticated to github.com using "publickey".

Two keys in, one attempt out. agent returned 2 keys alongside a single Offering public key is the whole fix between them: the agent's inventory is unchanged, and the filtering happened before anything went out on the wire, let alone reached the token.

I tested the other direction too, and I want to be honest about what that proved, because it is less than it looks. With yk1 attached, the run is identical and authentication succeeds on the first attempt. But that direction already worked before any of this, purely because id_ed25519_sk_yk1 sorts before id_ed25519_sk_yk2 and got offered first by luck. The value of testing it was confirming I had not broken the path that was fine. The yk2 case is the one that fixed a real failure.

That asymmetry is also why the bug survived so long. Half my usage was already correct, so it never looked like a broken configuration — it looked like the drawer key being flaky.

What this does not fix

It does not remove the PIN prompt. It removes the doomed one. I still verify and still touch, which is the entire reason for carrying a hardware token at all; a change that removed those would be trading the whole point for a fraction of a second.

There is one theoretical hole. USB device numbers wrap at 128, so a sufficiently unlucky sequence of replugs could land on a device number matching the cached one while holding a different token. The cost would be a single stale prompt, self-correcting on the next swap. I thought about defending against it for about a minute and then decided that engineering around a 1-in-128 chance of reproducing the exact bug I started with was not a good use of an afternoon.

The general shape

Match exec is the most underused thing in ssh_config. Most people know Match host and stop there, and then work around everything else with wrapper scripts or shell aliases or a mess of -i flags in their git remotes. But the predicate can be any command — which means your ssh config can respond to essentially any fact about the machine it is running on: which VPN is up, which network you are on, whether a particular file exists, which hardware token is in the port.

The constraint that makes it interesting is that it sits in the hot path of every connection, so the fact you want has to be cheap to establish. Half the work here was not "how do I select the right key", which is four lines. It was "how do I answer a 350ms question in under 10ms without ever answering it wrong". That is a caching problem, and the trick is nearly always the same — find the thing that already changes when your answer changes, and key on that instead of on the clock.

Setup notes: Fedora, OpenSSH 10.2p1, YubiKey 5C NFC on firmware 5.4.3, keys held by the gnome-keyring agent at $XDG_RUNTIME_DIR/gcr/ssh. Serial numbers in the examples are made up; use your own from ykman list --serials.

Reviewed with Claude, which caught the unscoped Match blocks and an error in how I'd explained the PIN/UV ordering. Prose and conclusions are mine.

Building GNOME Apps with Rust, Part 6: Fetching Feeds

Justin - FromTheArchitect — Tue, 18 Aug 2026 23:16:31 +0000

This is Part 6 of a series taking a GNOME app from an empty directory to GNOME Circle. Part 5 wired the sidebar to a real Feed GObject and a feed-selected signal — selecting a row updates the content pane and prints a line to the terminal. This is the post where that line stops being a placeholder and becomes a real network fetch.

The click that still does nothing real

Select This Week in GNOME, then select Hacker News. The placeholder swaps in the new name and URL — everything the app knows about that feed, and none of what's actually in it. Every Feed in the sidebar has a uri pointing at a real RSS or Atom document on the actual internet, and nothing in the codebase has ever asked one of them what's there.

The obvious fix — fetch the URL when feed-selected fires — is one line of code and the wrong line of code. GTK doesn't have a spare thread lying around to do that on, and the thread it does have is busy.

By the end of this post, selecting Hacker News in the sidebar prints real headlines to the terminal, fetched over the network, without the window so much as flickering. We'll build a Tokio runtime alongside GTK's own, give Feed somewhere to put what it fetches, and draw a hard line neither executor is allowed to cross.

The freeze

Wire the obvious fix into the feed-selected handler first, so you can watch it fail:

obj.connect_closure(
    "feed-selected",
    false,
    glib::closure_local!(move |_window: &super::GazetteWindow, feed: Feed| {
        // Don't do this.
        std::thread::sleep(std::time::Duration::from_secs(2));
        eprintln!("fetched (fake): {}", feed.name());
    }),
);

std::thread::sleep stands in for "network request in flight." Run the app and click a feed. For two seconds the window stops responding to anything — no hover states, no resize, no cursor blink, nothing repaints. Click a different feed while the first is still "fetching" and the click doesn't register until the sleep ends; it queues up invisibly and the window only notices you clicked at all once the first one finishes.

If you have GTK Inspector open (GTK_DEBUG=interactive, or Ctrl+Shift+I) while you try this, its own live views stall for the same two seconds — Inspector needs the app's main loop to be responsive to answer its own queries, so a frozen loop is invisible to Inspector too. Worth knowing the next time you're not sure whether your code froze or something else did.

Revert the handler to the logging-only version from Part 5 before continuing. The freeze was the demonstration, not a step you keep.

One main loop, nothing else runs until you give it back

GTK schedules everything through a single glib::MainContext, running cooperatively on a single thread: one job finishes before the next one starts. When you clicked a feed a moment ago, the redraw that should have shown the hover state, the cursor update, the eventual repaint once the click registered — all of it queued behind your feed-selected handler, waiting for std::thread::sleep to let go of the only thread any of it can run on.

That's a deliberate tradeoff. Exactly one thread ever touches a widget, so there's no locking, no data races, no Mutex<Widget>. The price is that the one thread has to keep coming back. Block it — a sleep, a synchronous file read, a blocking network call, anything — and every other queued job waits behind you.

This is also why "just spawn a thread and do it there" isn't a fix, only a different failure. Almost every GTK/GObject type is !Send: the bindings won't even let you move a Feed or a widget handle across a thread boundary — it's a compile error, not a runtime one. GObject's own machinery assumes single-threaded access and doesn't defend against concurrent calls from a second thread. A background thread can compute a result, but it can't hand that result to a widget directly. Something still has to get the result back onto the one thread allowed to touch GTK state.

Two executors, one job each

The pattern that resolves this has a name because the shape recurs in every GTK app that talks to a network: two executors, each with a rule it never breaks.

The GLib main loop owns every widget, every GObject, every signal, and it must never block.

Tokio owns anything that can block — the network request here, file I/O or database queries later. It runs on its own thread pool, and it never touches a widget or a GObject directly. That's its rule.

The two only meet at one seam: a future running on the GLib main context can .await a handle to work Tokio is doing, and when that work finishes, execution resumes back on the main context with the result now sitting there as a plain value. Nothing crosses except that value — no Feed, no gtk::Label, nothing GTK owns ever travels to a Tokio thread, and no raw socket or blocking read ever runs on the GLib thread. The rest of this post is standing up both executors and building that one seam.

Standing up the second executor

Add the dependencies:

tokio = { version = "1.53.1", features = ["rt-multi-thread", "net", "time"] }
feed-rs = "2.4.0"
reqwest = { version = "0.12", default-features = false, features = ["rustls-tls"] }

rt-multi-thread gives the runtime its worker threads; net and time give it the I/O and timer drivers reqwest — and any future tokio::time::sleep — actually needs. That matters more than it looks like it should: reqwest also depends on tokio and pulls in net/time itself, and Cargo unifies features across the whole dependency graph. Leave them off tokio's own line and the project still compiles today, by accident of what else happens to be in Cargo.toml. It breaks the day reqwest changes its feature list, or the day someone copies this dependency line into a project with no reqwest in it.

reqwest with default-features = false and rustls-tls pulls in a pure-Rust TLS stack instead of linking against the system's OpenSSL — one less thing the Flatpak manifest needs to account for. The 0.12 pin is deliberate too: 0.13 renamed that feature to rustls and made it the default backend, which would leave the line above redundant rather than wrong, but 0.12 is what this post was written and tested against, and mixing versions is a worse trap than an old pin.

The runtime itself is built once, in main(), before the GTK application exists:

// The second executor. Built before the GTK application and dropped
// after it exits, so it outlives every fetch that borrows its handle —
// the GLib main loop is the other executor, and it never blocks
// waiting on this one.
let tokio_runtime = tokio::runtime::Builder::new_multi_thread()
    .worker_threads(2)
    .thread_name("gazette-fetch")
    .enable_all()
    .build()
    .expect("failed to build Tokio runtime");

let app = GazetteApplication::new(
    "io.github.fromthearchitect.gazette",
    &gio::ApplicationFlags::empty(),
    tokio_runtime.handle().clone(),
);

let exit_code = app.run();

// `tokio_runtime` would drop here anyway at end of scope; the explicit
// drop just documents the ordering. `Runtime::drop` blocks this thread
// until every worker stops and abandons whatever tasks haven't
// finished — abrupt, not a cooperative cancel — which is still better
// than a fetch outliving the window that would have consumed it.
drop(tokio_runtime);
exit_code

app.run() blocks until the GTK application quits — that's the GLib main loop, occupying this thread for the entire life of the app. The Tokio runtime doesn't need this thread; Builder::new_multi_thread spins up its own worker threads (two of them here, named for easy identification in a debugger) and hands back a Runtime you only need to keep alive, not sit inside. tokio_runtime.handle().clone() is the thing that actually travels: a cheap, cloneable reference that can schedule work onto the runtime from any thread, including the GLib main thread.

One trap worth flagging on its own: forgetting .enable_all() fails silently until the first real request. A Builder without it produces a runtime with no I/O or timer driver — a different gap from the missing Cargo features above, this one is about whether a correctly-compiled runtime instance turns its drivers on. It builds fine, main() runs fine, the window opens fine, and the first time a spawned task tries to do the thing a runtime is for — reqwest::get or tokio::time::sleep — it panics with a message about no I/O driver running. The bug is invisible until the exact code path that needs the missing driver executes, which is exactly the fetch path this post is building.

That Handle needs a home the rest of the app can reach. GazetteApplication already owns everything else global to a running instance, so it owns this too — the same OnceCell shape Part 5 used for feeds: OnceCell<gio::ListStore> on the window: set once, read forever after.

#[derive(Debug, Default)]
pub struct GazetteApplication {
    // The second executor. Built once in `main()`, before the GTK
    // application runs, and outlives every fetch that borrows it.
    pub tokio: OnceCell<tokio::runtime::Handle>,
}

impl GazetteApplication {
    pub fn new(
        application_id: &str,
        flags: &gio::ApplicationFlags,
        tokio: tokio::runtime::Handle,
    ) -> Self {
        let app: Self = glib::Object::builder()
            .property("application-id", application_id)
            .property("flags", flags)
            .property("resource-base-path", "/io/github/fromthearchitect/gazette")
            .build();
        app.imp()
            .tokio
            .set(tokio)
            .expect("tokio handle set once at construction");
        app
    }

    /// The shared Tokio runtime handle — the executor every network fetch
    /// runs on. Available from any `GazetteWindow` via its `application()`.
    pub fn tokio_handle(&self) -> tokio::runtime::Handle {
        self.imp().tokio.get().expect("tokio handle set").clone()
    }
}

build() returns a fully constructed object. If GazetteApplication ever grows a constructed() that reaches for tokio_handle(), it will find the cell empty — constructed() runs during build(), before the line that sets tokio ever executes. Today's code escapes that trap by timing rather than by ordering: nothing that needs the handle runs until GTK calls activate, and activate doesn't fire until app.run(), long after new has returned with tokio set. Any window can reach the runtime through window.application(), downcast to GazetteApplication, and call tokio_handle().

Fetching, off the main thread

The fetch itself lives in a new file, src/fetch.rs, deliberately separate from feed.rs:

use std::fmt;

/// A single parsed entry from a feed. Plain data — not a GObject. It's
/// built on the Tokio runtime and only crosses onto the GLib main context
/// as a value, via `Feed::set_items`.
#[derive(Debug, Clone)]
pub struct FeedItem {
    pub title: String,
    pub link: String,
    pub summary: Option<String>,
}

#[derive(Debug)]
pub enum FetchError {
    Request(reqwest::Error),
    Parse(feed_rs::parser::ParseFeedError),
}

impl fmt::Display for FetchError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            FetchError::Request(e) => write!(f, "request failed: {e}"),
            FetchError::Parse(e) => write!(f, "couldn't parse feed: {e}"),
        }
    }
}

/// Fetches and parses a feed at `uri`. Runs entirely on the Tokio runtime —
/// nothing in this function, or anything it calls, touches a widget or a
/// GObject. That's what makes it safe to run off the GLib main thread.
pub async fn fetch_feed(uri: &str) -> Result<Vec<FeedItem>, FetchError> {
    let response = reqwest::get(uri)
        .await
        .map_err(FetchError::Request)?
        .error_for_status()
        .map_err(FetchError::Request)?;

    let bytes = response.bytes().await.map_err(FetchError::Request)?;

    let parsed = feed_rs::parser::parse(&bytes[..]).map_err(FetchError::Parse)?;

    Ok(parsed
        .entries
        .into_iter()
        .map(|entry| FeedItem {
            title: entry
                .title
                .map(|text| text.content)
                .unwrap_or_else(|| "Untitled".to_string()),
            link: entry
                .links
                .first()
                .map(|link| link.href.clone())
                .unwrap_or_default(),
            summary: entry.summary.map(|text| text.content),
        })
        .collect())
}

FeedItem is a plain struct rather than a glib::wrapper! type, and that matters: constructing a GObject means calling into GObject's type system, and this function has no business doing that from a Tokio worker thread. fetch_feed produces data; something back on the main thread decides what GObject, if any, that data becomes.

error_for_status() matters more than it looks. Without it, reqwest::get resolves Ok for a 404, a 500, or a hosting provider's error interstitial — the HTTP request itself succeeded even though the content is a lie. Skip the check and feed_rs::parser::parse gets handed an HTML error page instead of a feed, fails to parse it, and the caller sees FetchError::Parse for what was actually a request-level failure. Checking status before reading the body is what keeps Request meaning "didn't get a real feed body at all" — whether the cause is DNS, a timeout, or a 404 — and Parse meaning "got a body and it wasn't a feed."

feed_rs::parser::parse takes anything implementing std::io::Read (a byte slice qualifies) and returns entries regardless of whether the source was RSS or Atom. Gazette's four sample feeds are a mix of both — This Week in GNOME and From the Architect are Atom, LWN and the Hacker News mirror are RSS — and fetch_feed doesn't need to know or care which. That format detection is feed-rs's job, done once, before any of Gazette's code sees an entry.

One thing worth knowing, not fixing here: reqwest::get is a convenience function that builds a fresh Client — and with it, a fresh connection pool and TLS session — on every call. Fine for a post about the boundary between two executors, wasteful in code that fetches the same handful of feeds over and over. Building a Client once and sharing it alongside the Tokio handle is a refinement for a later post, once persistence is in the picture.

Crossing back

The feed-selected handler is where the two executors actually meet:

obj.connect_closure(
    "feed-selected",
    false,
    glib::closure_local!(move |window: &super::GazetteWindow, feed: Feed| {
        eprintln!("feed selected: {} ({})", feed.name(), feed.uri());

        // The GLib executor owns `feed` and `window`; the Tokio
        // executor (below) only ever sees the URI string it needs
        // to fetch. Neither side touches the other's objects
        // directly — the `.await` on the join handle is the only
        // crossing.
        let tokio_handle = window
            .application()
            .and_downcast::<crate::application::GazetteApplication>()
            .expect("window has a GazetteApplication")
            .tokio_handle();
        let uri = feed.uri();

        glib::MainContext::default().spawn_local(async move {
            let result = tokio_handle
                .spawn(async move { crate::fetch::fetch_feed(&uri).await })
                .await;

            match result {
                Ok(Ok(items)) => feed.set_items(items),
                Ok(Err(fetch_err)) => {
                    eprintln!("fetch failed for {}: {fetch_err}", feed.name());
                }
                Err(join_err) => {
                    eprintln!(
                        "fetch task for {} did not complete: {join_err}",
                        feed.name()
                    );
                }
            }
        });
    }),
);

Read it from the outside in. glib::MainContext::default().spawn_local(async move { ... }) schedules the outer future on the GLib main context — the same executor that owns every widget — running it cooperatively alongside everything else, exactly like a signal handler. Because it's confined to the main context, it's allowed to hold feed and eventually call feed.set_items(...). That's still executor-one territory.

Inside it, tokio_handle.spawn(async move { crate::fetch::fetch_feed(&uri).await }) hands the actual work to executor two. Handle::spawn returns immediately with a JoinHandle; it doesn't block the caller, which is the entire point of calling it from the main thread. .awaiting that JoinHandle is where the outer future pauses: control genuinely returns to the GLib main loop, which goes on painting, handling input, and dispatching other signals while Tokio's worker threads do the fetch. When the Tokio task finishes, the main loop resumes this specific future exactly where it left off, back on the main thread, with result now holding a value.

Why Ok(Ok(items)) and not just Ok(items)? Two different things can go wrong, and they're wrapped separately. The outer Result comes from JoinHandle itself — its Err means the spawned task panicked or was cancelled, a Tokio-level failure that has nothing to do with feeds. The inner Result is fetch_feed's own Result<Vec<FeedItem>, FetchError>, a normal, expected outcome of trying to fetch something over a network that might be down. Matching both layers explicitly is what forces you to decide what each one means, rather than letting ? collapse them into a single generic failure.

And a specific footgun: tokio::spawn(...), the free function, panics here — tokio_handle.spawn(...) doesn't. The free function only works from inside a future that's already running on a Tokio runtime. Called from the GLib main thread, which isn't inside any Tokio runtime, it panics; the exact wording has changed across Tokio versions, but it always amounts to "no runtime found in this context." Handle::spawn, called on the Handle cloned out in main(), is explicitly designed to work from any thread, runtime or not — that's the entire reason GazetteApplication stores a Handle instead of a Runtime. If you ever see that panic, you've reached for the free function where you needed the handle.

Run the app now. Click Hacker News: after a brief pause — a real network round trip, with the window still live under your cursor — real headlines appear on stderr. Click LWN.net Headlines before the first fetch has printed anything, and both proceed independently.

Feed remembers what it fetched

set_items is doing real work in that handler, and Feed needs somewhere to put what it's given:

use crate::fetch::FeedItem;

#[derive(Debug, Default, Properties)]
#[properties(wrapper_type = super::Feed)]
pub struct Feed {
    #[property(get, set)]
    pub name: RefCell<String>,
    #[property(get, set)]
    pub uri: RefCell<String>,
    #[property(get, set)]
    pub unread_count: Cell<u32>,

    // Plain data, not a property: `Vec<FeedItem>` has no `glib::Value`
    // mapping, and nothing outside this module needs to bind to it
    // directly. `items()` and `set_items()` are the accessors.
    pub items: RefCell<Vec<FeedItem>>,
}

impl Feed {
    pub fn items(&self) -> Vec<FeedItem> {
        self.imp().items.borrow().clone()
    }

    /// Replaces this feed's items and emits `items-updated`. The count
    /// crossing over from a real fetch is what makes `unread-count` real
    /// too, rather than the placeholder zero every sample feed starts with.
    pub fn set_items(&self, items: Vec<FeedItem>) {
        self.set_unread_count(items.len() as u32);
        self.imp().items.replace(items);
        self.emit_by_name::<()>("items-updated", &[]);
    }
}

items isn't a #[property]: a Vec<FeedItem> has no glib::Value representation the way a String or a u32 does, and nothing outside Feed needs to bind a widget to the raw list. It's a RefCell for the same reason selected_feed was one back in Part 5 — a value that changes over the object's life, read from one place (items()), written from one place (set_items()).

The items-updated signal was declared back in Part 2, on a Feed that never actually got new items, then Part 5 dropped it entirely to avoid emitting ceremony for nothing. It comes back here on the same impl block that already derives Feed's properties — with one change from Part 2's sketch:

#[glib::derived_properties]
impl ObjectImpl for Feed {
    fn signals() -> &'static [Signal] {
        static SIGNALS: OnceLock<Vec<Signal>> = OnceLock::new();
        SIGNALS.get_or_init(|| vec![Signal::builder("items-updated").build()])
    }
}

Part 2's version carried a u32 payload — the new item count, passed directly on the signal. This one carries nothing. Feed has an unread-count property now, so a listener that wants the count can just read feed.unread_count() instead of catching it off the emission. A signal that announces something changed and lets listeners go look is easier to evolve than one that ships a payload every listener has to keep accepting — that's the shape the rest of this post builds on.

#[glib::derived_properties] has to stay on this impl, even though signals() has nothing to do with properties: it's what generates properties(), property(), and set_property() from the #[property] fields on the struct above. Drop it while adding signals() and every #[property] accessor Feed already has — name(), uri(), set_unread_count() — silently stops working.

What's different now is that set_items is the only thing that ever emits items-updated, and it's only ever called with data that actually came off the network. set_unread_count runs first, before the emit, and the count that shows up in the sidebar is the number of items this fetch found.

That's a narrower claim than "unread," on purpose. Every fetch sets unread-count to the total item count, not the count of items the user hasn't seen. Refetch a feed after reading everything in it and the badge goes straight back up to the full number. unread_count is standing in for a property Gazette doesn't have the machinery to compute correctly yet — real read-tracking needs per-item state, which doesn't exist until this series adds persistence. Until then, read the name as aspirational, not as a bug you need to chase.

A consumer for items-updated

set_items emits; something has to be listening. Each sample feed gets a logging handler when the store is built, in constructed():

let store = gio::ListStore::new::<Feed>();
for (name, uri) in SAMPLE_FEEDS {
    let feed = Feed::new(name, uri);

    // Reacting to items-updated is a separate job from fetching
    // them — the fetch (wired below, on feed-selected) never
    // logs directly, it just calls `feed.set_items(...)`.
    feed.connect_closure(
        "items-updated",
        false,
        glib::closure_local!(move |feed: Feed| {
            let items = feed.items();
            eprintln!("{}: {} items", feed.name(), items.len());
            for item in items.iter().take(3) {
                eprintln!("  - {}", item.title);
            }
        }),
    );

    store.append(&feed);
}

Notice the fetch code in feed-selected never calls eprintln! on success. It just calls feed.set_items(items) and stops. Printing what arrived is this closure's job, connected once per feed, entirely separate from the code that went and got the data. That's the same lesson Part 5 landed with the placeholder binding and the feed-selected logger: fetching is one job, reacting to what was fetched is another, and the signal between them is what keeps neither one needing to know the other exists. A future persistence layer connects its own handler to items-updated later without touching a line of fetch.rs.

Sharp edges

A RefCell borrow held across an .await fails the same way a borrow held across a signal emit did in Part 5, just harder to spot. The failure shape: let items = self.items.borrow_mut(); some_future.await; inside a spawn_local block, where the code resumed after the .await — or a handler running on a different turn of the main loop, if the borrow escapes further — tries to borrow the same cell. Signal handlers run synchronously, so a Part 5-style borrow panic happens right where you'd look for it. An .await point hands control back to the main loop for an arbitrary amount of time: anything else the loop dispatches in between, including another handler that reaches for the same RefCell, can trigger the panic somewhere that looks nothing like the code that caused it. Keep borrows scoped tightly, and never hold one across an .await.

What happens if you click the same feed five times in a row? Five independent fetches run concurrently, each racing to call set_items on the same Feed when it finishes — last one to land wins, and items-updated fires five times for one selection. Harmless for a post about the executor boundary, but worth knowing before you go adding a refresh action, which makes hammering that shortcut the obvious next thing to try. A real fix would track the in-flight JoinHandle on Feed and abort or ignore a new request while one's outstanding — outside this post's scope, but that's where the fix would go.

window.application() returns None before the window has one, and expect turns that into a panic. In practice this never fires here: GazetteWindow::new always takes an application, and nothing runs feed-selected before the window exists. The expect documents an invariant rather than checking one — this window always has an application by the time it can receive input. If you ever construct a GazetteWindow without one, a test most likely, this is where it breaks.

What we have so far

Selecting a feed now does real work. A Tokio runtime, built once alongside the GTK application and never touched by it directly, does the actual fetching and parsing, and the only thing that ever crosses back onto the GLib main thread is a Result full of plain data. Feed::items-updated fires for real for the first time since Part 2 declared it, driven by whatever feed-rs found at the far end of a real URL.

Nothing about this displays anywhere yet — the items live in a RefCell a logging handler reads, and the sidebar still shows nothing but a name and a count. The fetch mechanism this post built doesn't need to change at all to support that; it already hands off a Vec<FeedItem> to whatever wants to render it.

What comes next

That's the gap the next post closes: an article list for the selected feed, a content pane for the selected article, and the adaptive layout that collapses both into a single pane on a narrow window. The two-executor pattern from this post doesn't change to support any of it.

Further out, unread_count and items want somewhere durable to live, so a refetch doesn't erase read state and a restart doesn't lose it either. That's the persistence layer this series has been setting up for since the OnceCell and RefCell conventions in Part 5 — a real place for items-updated to write to, instead of a logging handler standing in for one.

The source code at the end of this post lives on the part-6 branch of fromthearchitect/gnome-rust-gazette.

Moments: The Photo App I Built to Win an Argument

Justin - FromTheArchitect — Fri, 14 Aug 2026 08:17:33 +0000

A phone call with a mate turned into a wager: could AI actually build a real application from scratch? Five months, 898 commits and 40,000 lines of Rust later, here's the verdict — and the app.

It started with a phone call

Like most of my questionable decisions, this one started on the phone with a mate, talking about technology the way we always do. The conversation drifted, as every technical conversation eventually does now, into AI. And we ended up circling the same question everyone circles: is this stuff actually capable of building real software, or is it just very confident autocomplete?

He was the sceptic. I was less sure. I'd been watching AI coding tools long enough to see signs they could do more than trivial hello-world demos — I'd even written about the right way to work with them more than a year earlier. But I don't think either of us honestly believed the answer would be a full-featured desktop application.

So I did the thing you should never do on a phone call after 9pm: I made a declaration. I would definitively prove, one way or the other, whether AI could build a real application from scratch.

Not from a single prompt. That's a stupid idea, and it's a strawman both camps love: the boosters because it makes a great demo, the sceptics because it makes a great failure. I mean built the way software actually gets built: architecture, iteration, review, tests, releases. Using the pair programming approach I'd already laid out on this blog — human as navigator, AI as driver, with the conversation between them doing the real work.

If it failed, I'd write that post. It would have been an easier post to write, honestly. This is the other one.

Picking a fight worth having

If you're going to test whether AI can build real software, the project has to be real: something with real complexity, a demanding platform, and a reason to exist beyond the experiment.

I've been an on-again, off-again Linux user for the best part of thirty years. The kernel was never the problem. The desktop was never really the problem either, especially lately. The thing that has always dragged me back to commercial operating systems is the application ecosystem. It's better today than it has ever been, thanks to an enormous number of dedicated open source developers. But there are still categories where the open source options simply don't compete with their commercial rivals. Photos. Email. The apps your family actually touches.

And that second part matters, because this wasn't abstract for me. I've been trying to move my family away from Apple Photos, and self-hosted Immich is a brilliant back end for that. But my family has spent too many years inside the Apple ecosystem to accept a web interface for something as personal as their photo library. They want a real application. Native, fast, polished. The kind of thing the Linux desktop is chronically short of.

So that was the wager, fully formed: a modern GTK4/libadwaita photo management application for the GNOME desktop, written in Rust. (All the cool kids use Rust. It's been a long time since I was a kid.)

There was one more reason this experiment appealed to me, and it's the one I suspect resonates with most working engineers. My background is software engineering. I've built some large, complex, performance-critical systems for companies big and small. Building software has never been the hard part. Finding the time has. A career plus a family leaves you time-poor in exactly the way that kills side projects, and it's why I'd never seriously committed to a sizable open source project before. If AI could compress the gap between the architecture in my head and working code on disk, the economics of contributing to open source change completely — not just for me, for every experienced engineer who's been sitting on the sidelines for the same reason.

What it was actually like

Five months later I can tell you the answer to the wager, but the honest version of this story is the middle, not the ending. Because the first few weeks were not smooth.

The early problems were all variations on the same theme: an AI will cheerfully solve the problem in front of it with no memory of how it solved the same problem last Tuesday. I'd find duplicate implementations of the same logic in different corners of the codebase. I'd find three different patterns for the same category of problem, each locally reasonable, collectively a mess. I had to learn the right size to chunk features — too big and the AI loses the thread, too small and you spend more time briefing than you save.

But the biggest lesson was about architecture, and it's the one I'd put on a poster. Claude's instinct is to reach the outcome in front of it as fast as possible. It is genuinely good at that. What it does not do — unless you make it — is weigh that outcome against the long-term shape of the system. Left unsupervised, you get software that works today and calcifies by next month. Which, now that I write it down, also describes plenty of human teams I've worked with.

So the collaboration settled into a division of labour that will look very familiar to anyone who read my pair programming post:

Mine: application architecture, design, and feature management. Every structural decision — the backend abstraction, the sync model, the storage layout — came from me. I was the navigator, holding the long-term picture.
Claude's: the code. The overwhelming majority of the actual Rust was written by the AI, driving under direction.
Ours: the review loop. Every change went through a pull request, reviewed and audited before merge — the same discipline I'd demand on any professional team. No PR process, no experiment; it's the review loop that makes the whole thing defensible.

Part way through I added a technique I now consider essential: adversarial review. Don't let the AI that wrote the code be the only AI that reads it. A second model — or even the same model under a deliberately hostile prompt — catches code smells, duplication and quiet regressions far earlier than a friendly one does. The author is always too fond of its own work. That turns out to be true of machines too.

Somewhere in those months, the experiment stopped feeling like an experiment. That's the part I didn't expect. Within days it was apparent that working this way wasn't just possible — it was preferred. I wasn't tolerating the AI to prove a point. I was reaching for it because the loop of architect–direct–review–refine was producing better software, faster, than I would have produced alone in the hours I actually have.

The verdict

Here's what the wager produced:

~40,000 lines of Rust, GTK4 and libadwaita
898 commits over five months, first commit 22 March 2026
Every change human-reviewed before merge, through a PR workflow
Releases through v0.4.1, shipped as Flatpak bundles with checksums, and GPG signatures on signed releases
Built almost entirely in evenings and spare hours: the time budget of a person with a job and a family, not a funded team

Now overlay the cost lens, because this is where the wager stops being a curiosity and starts being an economic argument. The entire AI side of this project ran on a Claude Code subscription — I started on the Pro plan and very quickly determined it wasn't enough, so most of the project was built on the Max 5x tier, at roughly AU$150 a month. During heavy development I'd regularly burn through 80–90% of my weekly token allocation, but I never went over it. So call it $150 a month, all in, for a coding partner that helped produce a 40,000-line application. That's not cheap as subscriptions go, and I won't pretend it's nothing — but weighed against what it unlocked, I found it an easy cost to justify. For me, the constraint was never the money. It was only ever the time. I'll admit I spent more evenings on this than my family would have liked while it was all coming together. Now that we have a functioning app, it's consuming far less of them.

And here is the verdict, as plainly as I can put it: AI can absolutely build a real application — but not alone, and that's precisely the point. The single-prompt fantasy is still a fantasy. What is real, right now, is an experienced engineer setting the architecture and standards, an AI doing the driving, and a review process keeping everyone honest. That combination settled the phone argument — and it removed the constraint that has kept me, and I suspect a great many engineers like me, out of open source for years.

I called my mate to concede that neither of us had been right. He's yet to install a Linux desktop, so I'm calling it a draw.

Meet Moments

Enough about the wager — here's the app.

Moments is a photo management application for the GNOME desktop. It's built for exactly the situation my family is in: your photos live either on your own disk or on a self-hosted Immich server, and you want a fast, native way to actually browse them.

It talks to a local folder or to an Immich server. The Immich backend caches metadata and thumbnails locally in SQLite, so browsing, searching and anything you've already opened works fully offline; a photo you've never viewed before will fetch its full-resolution original on demand, then keep it in a local cache for next time. The grid is keyset-paginated with six zoom levels, and it stays smooth through large libraries.

Beyond that:

RAW and modern formats — CR2, NEF, ARW, DNG and friends, alongside JPEG, PNG, WebP, HEIC and TIFF
Video — import and playback via GStreamer
Albums, People and Favourites — including face data synced from Immich
EXIF metadata — camera, lens, exposure and GPS in the detail panel
Non-destructive rotate, flip and crop, with adjustments and filters behind experimental flags

It's GPL-3.0-or-later, and it's a real daily-driver application — my family's photo library runs on it.

Installing it takes a download and two commands. Every release ships a single-file Flatpak bundle (with checksums, and GPG signatures on signed releases):

flatpak install --user moments-<version>-x86_64.flatpak
flatpak run io.github.justinf555.Moments

Grab the latest bundle from the releases page.

The Flathub question

The obvious question is why those two commands aren't just flatpak install flathub io.github.justinf555.Moments. That deserves a straight answer, because it's part of this story too.

I submitted Moments to Flathub on 27 March 2026, five days after the project's first commit — early, deliberately, so the review could run alongside development. The submission worked through the normal review cycle: manifest fixes, portal permissions, test builds passing on both architectures.

Then, at the end of May, Flathub changed its inclusion policy. The new rule is a blanket one: "Applications containing AI-generated or AI-assisted code, documentation, or any other content are not allowed." Not AI-generated slop with no human behind it — which the previous policy already prohibited, rightly — but AI-assisted anything. Two days after the policy landed, my submission was closed. The full exchange is public, and I'd encourage you to read it and draw your own conclusions rather than take my summary of it. Read closely and you'll notice I described the AI's share of the codebase as "parts of the app" in that thread — more of it than I was comfortable admitting mid-argument, if I'm honest. This post is the fuller account.

I withdrew the submission, and I said my piece on the way out, which I'll stand behind here rather than repeat at length: the old policy drew the correct line — AI-generated code with no human behind it, not allowed; AI-assisted code that a human reviewed, tested and stands behind, allowed. The new policy erases that line. It stops judging software by whether it's good, tested and maintained, and starts judging it by how it was typed.

I understand where the policy comes from. Maintainers are drowning in low-effort AI submissions, and I have real sympathy for that — I wrote a whole post about the open source community's fraught relationship with AI before I was ever personally on the receiving end of it. Flathub's repo, Flathub's rules. But I think the blanket version of the rule is a mistake, and I think this app is a concrete counterexample: working GPL software, architected and reviewed by a human, in a category the Linux desktop has needed for decades. The policy does allow exceptions for "mature, well-maintained projects", so perhaps Moments and Flathub will meet again down the track. The door's open on my side.

In the meantime, the Flatpak bundles work everywhere Flatpak does, and updates are one download away.

What I'd ask of you

Three things, in order:

Install it. Point it at a folder of photos or an Immich server and see what you think. It's a download and two commands.
Star the repo. github.com/justinf555/Moments — discovery is the thing losing Flathub actually cost this project, and a star is the closest substitute GitHub offers.
Tell me what's broken or missing. Issues for bugs and feature requests, Discussions for everything else. This is the part of open source no AI can do: real people, with real photo libraries, telling you what actually matters.

And if you're an experienced engineer who's been sitting on an idea for years because you couldn't find the time — that's the real takeaway of the wager. The time problem is the one that just changed. Go and settle an argument of your own.

Building GNOME Apps with Rust, Part 5: State and Signals

Justin - FromTheArchitect — Mon, 10 Aug 2026 09:39:54 +0000

This is Part 5 of a series taking a GNOME app from an empty directory to GNOME Circle. Part 4 replaced our XML templates with Blueprint and grew the window into the real Gazette layout — a sidebar, a content pane, and three typed widget handles waiting for behaviour. This is the post where they get some.

If the GObject machinery in here feels unfamiliar — mod imp, properties, signals — Part 2 is the reference. This is where those patterns stop being theoretical.

The click that goes nowhere

Right now, clicking a sidebar row does nothing. GTK draws a selection highlight, the row picks up its hover state, and that's it — our code never sees the click. The whole point of the sidebar is that it drives the content pane, and we haven't wired that yet.

By the end of this post, selecting a row drives everything to its right. The shape I keep coming back to in GTK apps is a chain — model to list to selection to signal to content — and getting those links in the right order is half the work. The other half is interior mutability: where state lives, when RefCell earns its place, when OnceCell does, and why the Rc<RefCell<T>> reflex most of us carry over from non-GUI Rust almost never belongs in a mod imp-shaped app. I'll take each one where it comes up rather than in the abstract.

Concretely, we'll build a real Feed GObject with name and uri properties, swap that frozen sidebar row for a gio::ListStore<Feed> seeded with four real feeds, define a custom feed-selected(Feed) signal on the window, and make the content pane react — feed name as the title, URL as the description, the empty-state placeholder showing only when nothing's selected. That feed-selected signal is the seam Part 6 plugs Tokio into: the synchronous handler we write here gets joined by an asynchronous fetch handler that lives entirely in another file, and designing for that boundary now is the quieter lesson of the post.

Feed, for real

Part 2 sketched a Feed GObject — a title, an items-updated signal, the whole mod imp apparatus. None of it landed in source. We got away with it because Parts 3 through 4 only needed widgets, not data. That ends here. Before we can have a sidebar that means something, we need a model for what the sidebar contains.

Create src/feed.rs:

use gtk::glib;
use gtk::glib::Properties;
use gtk::prelude::*;
use gtk::subclass::prelude::*;
use std::cell::RefCell;

mod imp {
    use super::*;

    #[derive(Debug, Default, Properties)]
    #[properties(wrapper_type = super::Feed)]
    pub struct Feed {
        #[property(get, set)]
        pub name: RefCell<String>,
        #[property(get, set)]
        pub uri: RefCell<String>,
    }

    #[glib::object_subclass]
    impl ObjectSubclass for Feed {
        const NAME: &'static str = "GazetteFeed";
        type Type = super::Feed;
    }

    #[glib::derived_properties]
    impl ObjectImpl for Feed {}
}

glib::wrapper! {
    pub struct Feed(ObjectSubclass<imp::Feed>);
}

impl Feed {
    pub fn new(name: &str, uri: &str) -> Self {
        glib::Object::builder()
            .property("name", name)
            .property("uri", uri)
            .build()
    }
}

Three things stand out against that Part 2 sketch. I left the signals out: items-updated was the right instinct — feeds change when fresh content arrives — but with no fetching code yet, emitting it would be ceremony for nothing, so it comes back in Part 6 alongside the Tokio fetcher that gives it something to announce. The properties use #[derive(Properties)] paired with #[glib::derived_properties], which is the modern declaration form: the macro generates the properties(), set_property(), and property() boilerplate from the struct fields, where the older tutorials you'll still find hand-roll glib::ParamSpecString::builder("name").build(). Identical runtime behaviour, dramatically less typing, one fewer place to fat-finger a property name. And each field sits in a RefCell because properties have to be settable through GObject's runtime API — that demands interior mutability, and RefCell is the simplest answer for fields written occasionally and read everywhere.

One thing about that NAME constant: it's the GObject type name registered with the runtime. Prefix it with the application — GazetteFeed, not just Feed — so it doesn't collide with another library's Feed type. Names are global; collisions abort the process at type registration. Once your app loads a Feed type, no other library in the same process can.

Wire the module into src/main.rs:

mod application;
mod config;
mod feed;
mod window;

use self::application::GazetteApplication;
use self::feed::Feed;
use self::window::GazetteWindow;

Feed is now a real type the rest of the codebase can build on.

A list bound to a model

The sidebar in window.blp currently has one hard-coded row:

ListBox feed_list {
  selection-mode: single;
  styles ["navigation-sidebar"]

  ListBoxRow {
    child: Label {
      label: _("All Articles");
      halign: start;
      margin-start: 12;
      margin-end: 12;
      margin-top: 6;
      margin-bottom: 6;
    };
  }
}

That row is frozen in the markup. It can't grow, shrink, or change without touching the .blp file. Real apps don't work that way — feeds get added, removed, renamed. The markup needs to describe the shape of a row, and the runtime needs to produce one row per item in some collection. GTK has a name for this pattern: model/view binding.

Strip the inner ListBoxRow out. The new sidebar block:

content: ScrolledWindow {
  child: ListBox feed_list {
    selection-mode: single;
    styles ["navigation-sidebar"]
  };
};

Empty ListBox. The rows come from Rust now.

In src/window.rs, add the imports we'll need and grow the imp struct:

use std::cell::{OnceCell, RefCell};

use adw::subclass::prelude::*;
use gtk::prelude::*;
use gtk::{gio, glib};

use crate::Feed;

const SAMPLE_FEEDS: &[(&str, &str)] = &[
    ("This Week in GNOME", "https://thisweek.gnome.org/index.xml"),
    ("LWN.net Headlines",  "https://lwn.net/headlines/newrss"),
    ("Hacker News",        "https://hnrss.org/frontpage"),
    ("From the Architect", "https://fromthearchitect.dev/index.xml"),
];

mod imp {
    use super::*;

    #[derive(Debug, Default, gtk::CompositeTemplate)]
    #[template(resource = "/io/github/fromthearchitect/gazette/window.ui")]
    pub struct GazetteWindow {
        #[template_child]
        pub split_view: TemplateChild<adw::NavigationSplitView>,
        #[template_child]
        pub feed_list: TemplateChild<gtk::ListBox>,
        #[template_child]
        pub placeholder: TemplateChild<adw::StatusPage>,

        pub feeds: OnceCell<gio::ListStore>,
        pub selected_feed: RefCell<Option<Feed>>,
    }

    // ... ObjectSubclass impl unchanged
}

Two new fields. In the window's ObjectImpl::constructed, populate the store and bind it:

impl ObjectImpl for GazetteWindow {
    fn constructed(&self) {
        self.parent_constructed();

        let store = gio::ListStore::new::<Feed>();
        for (name, uri) in SAMPLE_FEEDS {
            store.append(&Feed::new(name, uri));
        }
        self.feeds.set(store.clone()).expect("feeds set once");

        self.feed_list.bind_model(Some(&store), |item| {
            let feed = item.downcast_ref::<Feed>().expect("item is a Feed");
            gtk::Label::builder()
                .label(feed.name())
                .halign(gtk::Align::Start)
                .margin_start(12)
                .margin_end(12)
                .margin_top(6)
                .margin_bottom(6)
                .build()
                .upcast()
        });
    }
}

bind_model takes the store and a closure, and it accepts our store because gio::ListStore implements gio::ListModel — it binds against that trait, not the concrete type. That indirection is the part I actually care about: it's what lets me wrap the store in a sort or filter model later without rewriting this call, which is exactly the refactor Gazette grows into once feeds need ordering. The mechanics from there are unremarkable — gtk::ListBox runs the closure once per item at bind time, then again whenever the model's items-changed signal reports an add or change, and because the closure returns a bare gtk::Widget, ListBox wraps it in a GtkListBoxRow so we never construct one ourselves.

Run the app. The sidebar now shows four feeds — This Week in GNOME, LWN.net Headlines, Hacker News, From the Architect — and you can click between them. Selection still doesn't do anything, but the rows are real.

One trap worth flagging — and a clarification about what that generic actually buys you. gio::ListStore::new::<Feed>() parameterises the store on the Rust side, and that's worth doing: it keeps the typed API honest and documents what the store holds. But it's a Rust-side convenience, not a hard runtime guarantee — at the GObject level the store holds plain glib::Object. So items coming back out of it — through item(), or through the ListModel interface a sort or filter model would hand you — still arrive as glib::Object and need the explicit and_downcast::<Feed>() you'll see in the selection handler shortly. Parameterise with your concrete type, but treat it as intent and documentation, not as enforcement at the model boundary.

Where state lives

The imp struct now carries two things that aren't template children: feeds and selected_feed. This is the right place for them. State on a GObject lives in the inner imp struct, never on the outer wrapper.

The reason is structural. GazetteWindow — the outer type — is a thin handle. glib::wrapper! makes it a transparent newtype around a refcounted pointer. Add a field to the outer type and you've added a field that won't be shared between clones of the handle, won't be visible across closures, and won't survive being passed back through GTK's C API. None of those failure modes is loud; the code compiles, the field exists, you set it, and then a second handle to the "same" window can't see what you wrote.

The inner imp::GazetteWindow, by contrast, is the actual heap-allocated object. There's exactly one of it per window, all handles point to it, and any code holding a handle can reach into it via obj.imp(). State you want every part of the app to agree on goes there.

This is one of the framework's rules rather than something you can derive from first principles, and I learned it the slow way — by adding a field to the outer type, setting it, and then losing an afternoon to state that silently wasn't shared between two handles to the "same" window. Memorise it — state lives in imp — and a surprising number of the architectural questions you might have about a GTK Rust app stop being questions.

Which cell?

feeds: OnceCell<gio::ListStore> and selected_feed: RefCell<Option<Feed>> — two different cells for two different lifetimes, and the difference is the whole point. The feeds store is built once in constructed() and read forever after, never replaced; that's exactly what OnceCell is for, and its set returning Err when it's already been set means the code asserts that contract for me instead of trusting me to remember it. The selected_feed changes every time the user picks a different row, so it needs the ongoing mutability RefCell gives. (A third category needs no cell at all: values the GObject machinery sets once at construction — template children, derived properties — that your own code never touches again.)

RefCell adds a runtime borrow check: borrow() and borrow_mut() panic if you take incompatible borrows at once. In this domain that's exactly what I want — GTK callbacks run on the main thread one at a time, so the panic only fires when my code has gone re-entrant in a way I didn't notice, and the first time it happened to me it pointed straight at a bug class I'd otherwise have spent an afternoon bisecting.

Notice the gio::ListStore itself isn't wrapped in RefCell, even though we mutate it constantly with store.append(...). ListStore is a GObject, and GObjects do their own reference counting and stay mutable through their GObject API without needing Rust-side cells. Wrapping it would compile but be redundant — you'd be borrow-checking access to a pointer.

My rule of thumb, after enough of these: template children and properties are naked fields with the right macro attribute; anything that owns a GObject — a gio::ListStore, another widget — is a naked field or an OnceCell, never a RefCell; a Rust value that genuinely mutates gets a RefCell, or a Cell if it's Copy; and a value set once and read everywhere gets a OnceCell. Once that split is reflexive, most of the "which wrapper goes here?" questions stop being questions.

Wiring selection, and the `clone!` macro

The rows render but selecting them does nothing. Wire selection up:

let obj = self.obj();
self.feed_list.connect_row_selected(glib::clone!(
    #[weak] obj,
    move |_, row| {
        let feed = row
            .and_then(|row| row.index().try_into().ok())
            .and_then(|i: u32| obj.imp().feeds.get().unwrap().item(i))
            .and_downcast::<Feed>();

        obj.imp().selected_feed.replace(feed.clone());

        if let Some(feed) = feed {
            obj.emit_by_name::<()>("feed-selected", &[&feed]);
        }
    }
));

(We define the feed-selected signal in the next section. Pretend it exists for a moment.)

The glib::clone! macro is doing a lot of work. Without it, the equivalent is:

let obj_weak = obj.downgrade();
self.feed_list.connect_row_selected(move |_, row| {
    let Some(obj) = obj_weak.upgrade() else { return };
    // ... rest of the closure ...
});

The macro hides the downgrade() / upgrade() dance. The #[weak] attribute means the closure holds a weak reference to obj: it doesn't keep the window alive. When the closure runs, the macro tries to upgrade the weak reference; if the window is gone, the closure returns early.

The alternative is #[strong], which captures by clone, incrementing the refcount. You almost never want that for a closure connected to one of the window's own widgets, because it builds a reference cycle:

The window owns the widget.
The widget owns the signal handler (the closure).
The closure now strongly owns the window.

The window can't drop because the widget's closure points to it; the widget can't drop because the window owns it; the closure can't drop because the widget holds it. Your app appears to leak windows on close. #[weak] breaks the cycle — the closure points weakly back at the window, and when the window's last strong reference is released, the chain unwinds cleanly.

This is the most common GTK Rust memory leak I run into, and it hides well: most apps have one window for their whole lifetime, so nothing looks wrong until you write a multi-window app — or, in my case, a test that spun windows up and tore them down in a loop, where the slowly climbing memory finally gave it away. The fix is always the same: weak the captures into widget-connected closures.

(One bit of translation if you're reading older code: the clone!(@weak obj => move |...| {...}) syntax was deprecated in glib 0.20. The #[weak] attribute form is the current spelling. They behave identically.)

A custom signal on `GazetteWindow`

The selection handler emits feed-selected, but we haven't defined it. Adding a custom signal is the same pattern as Part 2's Feed::items-updated, plugged into the window instead of the model.

In mod imp in src/window.rs, give ObjectImpl a signals() method:

use std::sync::OnceLock;
use glib::subclass::Signal;

impl ObjectImpl for GazetteWindow {
    fn signals() -> &'static [Signal] {
        static SIGNALS: OnceLock<Vec<Signal>> = OnceLock::new();
        SIGNALS.get_or_init(|| {
            vec![Signal::builder("feed-selected")
                .param_types([Feed::static_type()])
                .build()]
        })
    }

    fn constructed(&self) {
        self.parent_constructed();
        // ... store setup, bind_model, connect_row_selected ...
    }
}

signals() is a static method GObject calls once, when the type is first registered, to learn what signals it defines. The OnceLock cache is conventional — GObject doesn't require it, but it means the vec! allocation only runs once. (Note this is std::sync::OnceLock, the thread-safe one: a static has to be Sync, so the single-threaded std::cell::OnceCell we reached for in the imp fields wouldn't compile here — same family, different guarantees.) Our signal is named "feed-selected" and carries one parameter, a Feed.

That's enough to make the emit_by_name call in the selection handler legal. But a signal with no listeners does nothing — so let's give it a consumer. The handler decides what to do when a feed is selected: update the placeholder.

let obj = self.obj();
obj.connect_closure(
    "feed-selected",
    false,
    glib::closure_local!(
        #[weak] obj,
        move |_window: &super::GazetteWindow, feed: Feed| {
            let imp = obj.imp();
            imp.placeholder.set_icon_name(Some("rss-symbolic"));
            imp.placeholder.set_title(&feed.name());
            imp.placeholder.set_description(Some(&feed.uri()));
        }
    ),
);

A few new pieces:

connect_closure is the lower-level form of signal connection. We need it because the signal is custom — there's no auto-generated connect_feed_selected method, so we connect by name.
glib::closure_local! wraps the Rust closure in a glib::Closure the GObject system can store. It's the bridge between Rust closures and GObject's signal machinery, and it accepts the same #[weak] / #[strong] attributes as clone!.
false is the after flag — whether this handler runs before or after the other handlers connected to the signal. It's easy to read it as "after the default handler," but that's a separate mechanism (the handler baked into the type definition); after only orders you against the other external connections. With a single handler it makes no difference; by convention, pass false unless you specifically need to run last.

Two handlers now exist on feed-selected: the implicit one in connect_row_selected that emits it, and the explicit one in connect_closure that consumes it. Neither side names the other; the signal is all they share.

Run the app. Click This Week in GNOME; the content pane updates to show the feed name as the title and the URL as the description. Click Hacker News; it switches. Selection has meaning now.

When `Rc<RefCell<T>>` isn't the answer

The instinct, especially coming from non-GUI Rust, is to reach for Rc<RefCell<T>> whenever two closures need to share mutable state — it's the canonical answer to "shared mutable state without locks," and my first couple of GTK apps were quietly littered with it.

Suppose both connect_row_selected and the feed-selected handler wanted to read the currently-selected Feed. The wrong instinct produces this:

// Don't do this.
let selected = std::rc::Rc::new(std::cell::RefCell::new(None::<Feed>));

let selected_clone = selected.clone();
self.feed_list.connect_row_selected(move |_, row| {
    *selected_clone.borrow_mut() = /* derive feed from row */ None;
});

let selected_clone = selected.clone();
obj.connect_closure("feed-selected", false, glib::closure_local!(
    move |_window: &super::GazetteWindow, _feed: Feed| {
        let _current = selected_clone.borrow();
        // ...
    }
));

This compiles, runs, and is reasonable Rust outside the GTK context. Inside it, the state belongs in imp:

self.feed_list.connect_row_selected(glib::clone!(
    #[weak] obj,
    move |_, row| {
        let feed = /* derive feed from row */;
        obj.imp().selected_feed.replace(feed);
    }
));

Both closures already reach the same selected_feed through obj.imp(). There's no need for an additional Rc — GObject's reference counting is the Rc. There's no need for a separate RefCell — the field is already in one on the imp struct.

The rule of thumb: any time you find yourself typing Rc<RefCell<T>> inside an imp block, stop. The state you're trying to share lives on the imp; closures reach it through obj.imp(); the GObject lifecycle handles the sharing. It can be appropriate at the edges of a system — prototyping a small example without a wrapping GObject — but inside a real GObject-based architecture, it's a smell.

Binding the view to state

The placeholder updates imperatively inside the feed-selected handler — three set_* calls per selection. bind_property promises to replace that with a declarative link, and the tempting move is to drop it straight into the handler:

// Tempting, and wrong.
feed.bind_property("name", &*imp.placeholder, "title")
    .sync_create()
    .build();

This compiles and looks right — select a feed, the title updates — and I shipped exactly this shape once and didn't notice for weeks. The catch is that the handler runs once per selection, so every click builds a fresh glib::Binding and nothing tears down the previous one. Click between four feeds and the placeholder's title now has four live bindings pointing at it, each holding a reference to a feed. They stay quiet only because a feed's name never changes after creation — and the moment it does, which is exactly what Part 6's fetcher will make happen, every stale binding fires and an unselected feed can overwrite the selected one's title. A binding built in a per-event handler is a leak with a delay on it.

The fix isn't to manage the binding's lifetime by hand. It's to notice what the placeholder actually is: a pure function of which feed is selected. That's state, and we have a rule for state — it lives in imp. Promote selected_feed from a plain field to a GObject property, and the placeholder can bind to it once, for the life of the window.

Add the Properties derive to the window's imp struct and annotate the field:

#[derive(Debug, Default, gtk::CompositeTemplate, glib::Properties)]
#[properties(wrapper_type = super::GazetteWindow)]
#[template(resource = "/io/github/fromthearchitect/gazette/window.ui")]
pub struct GazetteWindow {
    #[template_child]
    pub split_view: TemplateChild<adw::NavigationSplitView>,
    #[template_child]
    pub feed_list: TemplateChild<gtk::ListBox>,
    #[template_child]
    pub placeholder: TemplateChild<adw::StatusPage>,

    pub feeds: OnceCell<gio::ListStore>,
    #[property(get, set, nullable)]
    pub selected_feed: RefCell<Option<Feed>>,
}

Add #[glib::derived_properties] above the window's impl ObjectImpl block — the same pairing Feed already uses. nullable is what lets the property hold None: nothing is selected at startup, and the user can clear the selection later.

The selection handler now sets the property instead of replacing the cell directly. Going through the generated setter is what emits notify::selected-feed, and that notification drives the binding:

self.feed_list.connect_row_selected(glib::clone!(
    #[weak] obj,
    move |_, row| {
        let feed = row
            .and_then(|row| row.index().try_into().ok())
            .and_then(|i: u32| obj.imp().feeds.get().unwrap().item(i))
            .and_downcast::<Feed>();

        obj.set_selected_feed(feed.as_ref());

        if let Some(feed) = feed {
            obj.emit_by_name::<()>("feed-selected", &[&feed]);
        }
    }
));

Then bind the placeholder to the property once, in constructed:

obj.bind_property("selected-feed", &*self.placeholder, "title")
    .transform_to(|_, feed: Option<Feed>| {
        Some(feed.map_or_else(
            || "No Feed Selected".to_string(),
            |feed| feed.name(),
        ))
    })
    .sync_create()
    .build();

obj.bind_property("selected-feed", &*self.placeholder, "description")
    .transform_to(|_, feed: Option<Feed>| {
        Some(feed.map_or_else(
            || "Select a feed from the sidebar to see its articles.".to_string(),
            |feed| feed.uri(),
        ))
    })
    .sync_create()
    .build();

transform_to runs whenever the source changes, mapping the selected Feed to a string for the target. The None arm matters as much as the Some arm: when the selection clears, the binding restores the empty-state text — the placeholder handles deselection for free, with no code in the handler. sync_create() copies the current value (None at startup) the moment the binding is built, which is why the placeholder reads "No Feed Selected" before anything is clicked.

With the placeholder now driven by the property, the feed-selected placeholder handler has nothing left to do — delete it. And that deletion sharpens the point about routing through a signal. Reflecting state in the UI — the title just following the selection — is a binding's job: declarative, set up once. Acting on a change — fetching the feed, logging, anything with a side effect — is a signal's job, and feed-selected stays exactly for that. The placeholder was never really a signal consumer; it was a view of state, and now it's wired that way.

So what does listen to feed-selected now? For the moment, a logger — proof the seam works:

obj.connect_closure(
    "feed-selected",
    false,
    glib::closure_local!(
        move |_window: &super::GazetteWindow, feed: Feed| {
            eprintln!("feed selected: {} ({})", feed.name(), feed.uri());
        }
    ),
);

Run, click feeds, watch the terminal. Two independent things now happen on every selection: the placeholder updates through the property binding, and the log prints through the signal handler — and neither is wired to the other. Part 6 connects a second handler to the same signal, an async fetcher that reads the feed's URL, and it slots in without the binding or this logger ever knowing it arrived.

Sharp edges

A few things that bite, all on the GObject-runtime seam where Rust's compile-time guarantees stop and GObject's runtime conventions begin.

Signal names aren't checked

emit_by_name::<()>("feed-selected", ...) compiles fine if you typo the name. It fails at runtime when the type system can't find a signal by that exact string, and panics with a message about a name lookup miss. There's no compile-time check. The remedies: care, integration tests that exercise every signal path, or const-ing the name in one place and using it in both signals() and the emit sites.

`connect_row_selected` fires with `None` on deselection

When the selection clears — programmatically, or because something else takes focus — row is None. Code that always assumes a feed exists goes quietly wrong. Branch on row early; the Option is part of the API for a reason.

Borrow panics inside signal handlers

If you hold a RefCell borrow across a signal emission and a handler for that signal tries to borrow the same cell, you panic — signal handlers run synchronously, so the emit doesn't return until they're done. The shape that triggers it: let mut state = self.thing.borrow_mut(); followed immediately by obj.emit_by_name::<()>(...), still inside that borrow. The fix is to scope the borrow tightly so it ends before you emit. (The derived property setters are safe here: each scopes its own borrow_mut, writes, and returns before GObject emits notify.)

Kebab-case at the GObject level, snake_case in Rust

A struct field selected_feed becomes the property selected-feed in bind_property and friends, with accessors selected_feed() / set_selected_feed(...) on the Rust side. The derive macro does the conversion. Mistype the kebab-case form — bind_property("selected_feed", ...) — and the binding fails to find a property by that name. Not silently: GLib prints a g_warning to stderr and the binding does nothing.

What we have so far

Selecting a feed does something. The structure model → list → selection → signal → content is in place, and four real RSS feeds populate the sidebar at startup. The state we added — feeds: OnceCell<gio::ListStore>, selected_feed as a nullable property — lives in imp, where the GObject machinery already manages sharing across closures and lifetimes. Rc<RefCell<T>> doesn't appear anywhere in this codebase, and probably won't.

The feed-selected signal is a deliberate seam. The placeholder doesn't even use it — selection state flows through a property binding instead, because reflecting state and reacting to events are different jobs. The signal is for reacting: right now a single logging handler listens.

What comes next

That logging handler is a placeholder for the real one. Part 6 — Fetching Feeds — connects an asynchronous fetcher to feed-selected: it hits each feed's URL, parses the RSS or Atom response, and emits the items-updated signal we deferred back at the top of this post as articles arrive.

That fetcher needs a runtime GTK doesn't have. Part 6 explains why GTK is single-threaded around a single main loop, why blocking that loop freezes the window, and how the two-executor pattern lets Tokio do network work without ever touching a widget on the wrong thread. The seam we built here is what it plugs into.

The source code at the end of this post lives on the part-5 branch of fromthearchitect/gnome-rust-gazette.

Four Ways the Outbox Bit Me

Justin - FromTheArchitect — Tue, 02 Jun 2026 22:00:00 +0000

In the previous post I described an architecture where the Moments library doesn't know that sync exists. Services record Mutation values into a one-method trait; one implementation writes to an outbox table, another does nothing. The library code is identical regardless of which backend it's running under, and a third backend could be added without touching the library at all. The architecture is sound. I still believe in it.

The first six weeks of running it were a different story. Four bugs in particular are worth describing, because each one tells you something the diagrams don't. Two are about the abstraction — assumptions the trait quietly makes about how the world works, and what breaks when the world doesn't cooperate. Two are about the substrate — the boring queue-and-retry machinery underneath the trait, which has its own opinions about how things should be done. Clean architecture doesn't relieve you of the substrate's problems. It just gives you one place to deal with them.

1. The pull-delete loop

The first bug was the most embarrassing one, and the cleanest illustration of a hidden assumption in the design.

The symptom, as a user would see it: trash a photo on your phone via the Immich mobile app. Watch it disappear from the desktop a few seconds later when the next pull cycle arrives. Watch it reappear a few seconds after that. Watch it disappear again. The asset ping-pongs across the network, never settling, every thirty seconds, forever — or at least until you notice and start digging.

The mechanics: the pull-side handler for AssetDeleteV1 called MediaService::delete_permanently, which dutifully recorded an AssetDeleted mutation into the outbox, which the push manager dutifully tried to send back to the server, which had just told us the asset was gone. Server says delete → local deletes → outbox records delete → push tries to delete on server → server returns 404, push gives up. So far so harmless. But the next pull cycle then re-emits the original delete (because the server is still asserting "this asset has been deleted, here's the event"), and we go around again.

The recorder-based design has a hidden assumption baked into it: mutations have a single source, and that source is the user sitting at the desktop. The whole point of recording mutations is to push them to the server. When the server starts producing mutations — and in a two-way sync, of course it does — the recorder happily reports those back to the server too, and the system feeds on its own output.

The fix (commit f097174) was a Library::delete_permanently_from_sync variant that takes the same code path except it skips the recorder. The _from_sync naming convention now appears wherever pull-side handlers mutate the library — there's a _from_sync for trash, for restore, for the album mutations, and so on. Each one is a tiny duplicate of its normal counterpart, with the recorder call removed. It feels redundant, and it is, but the redundancy is the whole point: pull is the local equivalent of "don't echo back what you were just told", and the duplication makes the don't-echo explicit at every call site.

There were two alternatives I considered. One was a thread-local "I am inside the sync handler" flag that the recorder would check; that's a kind of magic that hides the directional question rather than answering it. The other was a parameter on every service method indicating origin; that pushes the question into every signature instead of into a single naming convention. The _from_sync approach won because it makes the asymmetry visible exactly where it matters and nowhere else.

The architectural lesson, stated generally: a recorder-based design implicitly assumes mutations have a single source. The moment a second source appears, you have to mark it in the code, or you get an infinite loop with a polite retry interval.

2. Retry, backoff, and the death of multi-id rows

The second bug is one of substrate, not abstraction. It would have bitten any outbox-based design, regardless of how the recorder was shaped.

The first version of the outbox stored multi-id mutations as a single row. AssetTrashed { ids: [a, b, c] } produced one outbox row with a JSON-encoded array of ids. It was simpler. The mutation type kept its natural shape — "the user trashed three photos" is a single mental event, after all — and the database had three fewer rows to deal with.

It was also wrong, in three independent ways.

The first was partial progress. The push call for that row was, internally, a loop over the ids making per-asset API calls. If the server accepted three of five ids and then the connection dropped, there was no way to record the partial success. The next retry would re-send all five, and the server's behaviour on the already-trashed ones was implementation-defined enough that I didn't trust it.

The second was blast radius. If a single id in the batch was the cause of a permanent failure — say, the user trashed an asset, then permanently deleted it elsewhere, then triggered a sync — the batch would fail forever on that one bad asset. The other four perfectly good operations were dragged into the dead-letter queue alongside it.

The third was per-batch backoff. Exponential backoff on the batch row meant one bad asset could starve the entire trash pipeline behind it. Asset X fails three times, the row sleeps for ten minutes, all five operations wait. Asset X fails again, the row sleeps for an hour. Operations Y and Z, which would have succeeded immediately, are blocked on Asset X's bad behaviour.

The fix (commit 77d9647) rewrote Mutation::to_outbox_rows() to produce one row per entity, and added per-row retry/backoff machinery: attempts and next_attempt_at columns, exponential backoff capped at one hour, a DeadLetter status after ten consecutive failures so a permanently bad row stops being retried. AssetTrashed { ids: [a, b, c] } now produces three rows. Each one is independently retryable, independently dead-letterable, independently backed off.

I want to make this lesson explicit because it took me three iterations to internalise: the unit of retry should be the unit of failure. If a single id can fail independently, each id needs its own row. The temptation to compact the outbox is real — fewer rows feels cleaner, the JSON arrays are tidier in the schema browser — but the cost shows up under exactly the conditions you can't easily reproduce in development.

This isn't a recorder bug. It's a queue-design bug, and would have happened with a channel, a Kafka topic, or a hand-rolled WAL. But it's still a bug the architecture made me responsible for, because the trait that the architecture promises is only as good as the queue underneath it.

3. Identity across the round-trip

The third bug was the one that taught me the difference between decoupling and ignoring.

MediaId and AlbumId are local UUIDs that Moments generates when an asset or album is first created on the desktop. Immich also generates UUIDs for assets and albums on its end — those land in a column called external_id. The two are not the same. The local id is the row's primary key forever; the external id is stamped onto the row once the push succeeds and the pull cycle confirms the asset is now visible server-side.

So far so reasonable. Now consider the lifecycle of a freshly imported photo. The user drops a JPEG into the import folder. MediaService::import generates a fresh MediaId, writes a row, records an AssetImported mutation. The push manager picks up the outbox row, uploads the file, receives the Immich asset id from the response, stamps it into media.external_id. Beautiful. Then the next pull cycle, dutifully fetching everything the server knows about, streams an AssetV1 event for that same asset.

The original handler for AssetV1 did INSERT OR REPLACE INTO media (id, external_id, …). The id it inserted was a freshly-generated local UUID — because that's how the pull handler always created assets. The pull handler had no way to know that this asset already existed locally under a different local id, because the only thing connecting them was the external_id column it was about to overwrite.

The result: a brand-new row, with a brand-new MediaId, replacing the original one. Every album-membership row pointing at the original MediaId now dangled. The asset appeared in the timeline grid but not in any of the albums the user had just added it to. Worse, the original row's on-disk thumbnail and cached EXIF data were now associated with an id that no longer existed in media.

Commits d43859f and 1692881 fixed this by making MediaId and AlbumId round-trip stable. On inbound sync, every handler looks up the existing row by external_id first. If a row already exists with that external id, the handler reuses its MediaId and updates fields in place, never minting a new one. The local id becomes the durable identity; the external id is the bridge that lets inbound sync find it again.

The general lesson — and this one took me by surprise — is that "an outbox decouples local mutations from remote sync" is technically true and architecturally meaningless if the identity of an entity doesn't survive the round-trip. The decoupling is between the two flows of operations, not between the two namespaces of identifiers. Those namespaces still have to be reconciled somewhere, and the schema is the natural place. You need a column, or a constraint, or a lookup convention that lets inbound sync recognise "this thing already exists" rather than treating every server-side row as a first-time event.

In retrospect, the lesson is obvious. In practice, it costs you a weekend the first time, because the bug is invisible in any test where the asset is created locally or fetched from the server but never both. The minimum reproducer is a real round-trip, and you don't usually write tests that span import → push → pull on the same asset.

4. Reset semantics, or: what does the server mean by "start over"

The fourth bug is the one that taught me sync protocols are not what they appear to be.

Immich's sync protocol can send a SyncResetV1 message when the last checkpoint is more than thirty days stale. The semantics, in the spec, are roughly: "your understanding of my state is too old to be incrementally caught up. Treat what follows as a complete re-emission of everything I know about."

The naive interpretation is "wipe the local cache and re-fetch everything." That interpretation is catastrophic for an offline-first store. The user has locally-imported, not-yet-pushed assets sitting in their library. Those have no external_id because the server has never heard of them. A blind wipe would delete the user's recent imports the moment the sync handshake decided their checkpoint was stale — and "stale" in this protocol can mean as little as a month of laptop-closed time.

The first version of the reset handler tried to be careful. It built a HashSet<MediaId> of every local asset at the start of the reset cycle, removed each id as the stream re-emitted it, and at end-of-stream deleted whatever was left over. That at least filtered to "things the server should have known about". It still had three latent bugs, and I'll only name them briefly because the full catalogue is in the design doc.

First, namespace confusion. media.id is the local UUID; the stream's entity_id is the Immich UUID. The set was being keyed on one and reduced by the other, so the set never actually shrank — every reset cycle wiped the entire library. Second, locally-imported rows (external_id IS NULL) shouldn't have been candidates at all, but the set didn't filter them out. Third, albums and asset_faces had no orphan tracking, so they leaked across resets entirely.

Commits e54e037 and 3e24d9f rewrote the whole thing into a heartbeat-based reconciliation, which is the kind of state-machine design that's interesting on its own merits. On SyncResetV1 the reset handler captures the current timestamp as a "checkpoint" and clears the per-entity-type ack cursors. Nothing gets deleted yet. Every entity-handler — AssetV1, AlbumV1, PersonV1, AssetFaceV1 — has an UPDATE table SET last_seen_at = now() WHERE id = ? baked into it. Any locally-driven server interaction (a push completion, a favorite round-trip) bumps the same column.

On SyncCompleteV1, four targeted sweeps run — on media, albums, people, and asset_faces — each filtering rows where last_seen_at < checkpoint. The media and albums sweeps add external_id IS NOT NULL as a guard, which is the single line of defence between a reset cycle and the user's local-only imports. people and asset_faces don't need that guard: nothing local creates them — they only exist once the server emits them. The whole scheme is crash-safe by accident: partial heartbeats persist across a process restart, so an interrupted reset cycle finishes correctly on the next pull rather than starting over.

The lesson is broader than reset. "Reset" in a sync protocol is not "delete everything." It's "re-establish ground truth without losing what only you know about." The set of things only-you-know-about is — for an offline-first store — every row without an external_id plus every locally-mutated field that hasn't yet been pushed. If your reset handler doesn't have a name for that set, your reset handler is going to delete it.

This is the bug that has the least to do with the recorder trait itself. It belongs to the broader category of "things you only discover once you have the architecture, the outbox, and a real round-trip running long enough to encounter a thirty-day boundary." But it earned its place on this list because it follows the same shape as the others: the architecture didn't cause it, the architecture didn't prevent it, but the architecture is what gave us one well-defined place to fix it.

What the four have in common

The bugs span the two categories the intro set out — abstraction (1 and 3) and substrate (2 and 4) — and what they share, across both, is that none of them required changing the architecture. Bug 1 added a _from_sync variant alongside the user-facing method, not a new trait or a new flag on the recorder. Bug 2 rewrote to_outbox_rows() and added retry columns to the schema; the recorder trait was untouched. Bug 3 changed how inbound handlers look up existing rows; nothing above the schema cared. Bug 4 added a single column (last_seen_at) and four sweep queries; the trait, the enum, the outbox table layout, the library services — all unchanged.

That's the dividend the architecture actually pays. The bugs are real, expensive, and embarrassing in their own ways. None of them propagated upward. The library still doesn't know sync exists. It just describes what it changed, and lets the substrate — and the people maintaining it — pay the round-trip's price.

Why Open Source Doesn't Embrace AI

Justin - FromTheArchitect — Wed, 27 May 2026 12:19:50 +0000

A week ago I would have told you the open source community rejected AI for four obvious reasons. Then I tried defending each one properly. Most of them collapse under scrutiny — and what's left is a much more tractable conversation.

The conventional answer

Every maintainer I know has roughly the same three or four complaints about AI tooling.

First, nobody can tell where the training data came from, which sits badly with a culture obsessed with provenance. Second, maintainers are drowning in AI-generated PRs and CVE reports — Daniel Stenberg's posts on the curl side of this are now the canonical example. Third, AI shortcuts the old apprenticeship loop where contributors learned a codebase by earning review trust over months. And fourth, the power asymmetry: frontier models need hyperscaler capital, which sits uneasily inside a movement built on "you can read, modify, and redistribute the thing."

This is the standard pitch. Put it in front of any contributor at FOSDEM and you'd get nods all the way down. It's also the position I'd have given you a week ago, before I tried to defend it in detail and realised most of it doesn't actually hold up.

The win-win argument

The most common pushback I hear from developers is straightforward. If AI is trained on open source, and then used to write more open source, surely that's a win for everyone. The argument, basically, is that open source taught the model, and the model now helps people ship more open source.

The first-order answer is that the value doesn't circulate. Code goes in to the model for free, gets laundered through training, and comes back out behind a paywall rented from a private company. The contributor whose code shaped GPT-5 or Claude or Copilot doesn't get a cut, doesn't get attribution, and pays the same subscription fee as everyone else. Compare that to how open source normally compounds: I fix a bug in libcurl, the fix lives in libcurl, every downstream user benefits, the project is permanently better. With LLMs, the upstream project gets nothing.

That answer is satisfying. It's also where the argument starts to wobble.

The RHEL problem

The community's case against AI extraction has to reckon with the fact that it has cheerfully tolerated extraction at far larger scale for decades.

Red Hat ships kernel patches upstream, but Satellite, Insights, and Ansible Automation Platform are proprietary. They made billions off a kernel they didn't write, restricted source distribution to paying customers in 2023, and remain consistently in the top tier of corporate contributors to Linux. The community grumbled and kept using RHEL. Cloud provider extraction hit Elasticsearch and MongoDB hard enough that both re-licensed in self-defence — Elastic directly aimed at AWS, MongoDB preemptively against the whole cloud category — and we still all use AWS. Amazon Linux 2023 is a downstream of Fedora. They keep the orchestration plane closed. Nobody is staging a boycott.

If RHEL gets a pass for closed-source Satellite while making billions off a kernel they didn't write, the AI critique can't just be "they made money off the commons." That proves too much. It rules out the entire managed-services industry that open source has come to depend on.

What Valve actually shows

Valve is probably the strongest counter-example the anti-AI position has. The Steam Deck ships KDE Plasma in desktop mode, so Valve's Steam Deck work funds a consultancy — Techpaladin since 2025, Blue Systems before that — which in turn employs a substantial slice of the KDE Plasma development team, including Nate Graham and David Edmundson. Valve also funds Mesa, kernel graphics, Wine, gamescope, and PipeWire work through similar arrangements. KDE Plasma on Wayland in 2026 is dramatically better than it was in 2022, and a non-trivial chunk of that is Valve money.

But the reason it works matters, because it doesn't generalise the way the community sometimes wants it to.

Valve is redistributing GPL'd binaries on every Deck they ship. The licence compels everything that follows. They have to provide source, they have to comply with copyleft, and funding upstream is partly enlightened self-interest because the alternative is forking the world and maintaining it forever. That's not moral generosity, it's licence physics. The Linux kernel made them play by Linux's rules.

AI vendors don't redistribute the code. They train on it. Whether that triggers any licence at all is the entire legal question — and so far courts have leaned toward "no, it doesn't." Which means the Valve comparison isn't actually telling us what we want it to tell us. It's telling us that when distribution triggers copyleft, copyleft works. It says nothing about what happens when distribution doesn't enter the picture.

Inspiration is not copying

This is the part of the argument I've moved most on, and the part the strong anti-AI position has the most trouble with.

If copyright treated "learning from code" as infringement, the software industry would collapse under its own weight. Every senior engineer I know has spent years reading other people's code and unconsciously carrying patterns forward. I learned how to structure a GTK app by reading Builder's plugin code. Half of what I know about production C came from reading curl. None of that gave libcurl or Builder a claim on what I write next. The uncomfortable part is that LLMs industrialise that process at a scale humans never could — and a lot of the community's gut reaction is to that scale shift, not to the legal question underneath it.

The honest legal question isn't "is training infringement." US courts so far appear sympathetic to transformative-use arguments around training when the training data was lawfully acquired — Anthropic's $1.5B settlement in Bartz v. Anthropic last year over books obtained from piracy sites is the live counter-example, and it carves the question into two pieces. Training on lawfully-licensed text looks defensible; how the corpus was assembled is its own front. And the EU is heading somewhere different again. The remaining interesting question is "is the output infringement when it reproduces training data verbatim." That's at least a problem courts can reason about.

And once you separate "training happened" from "specific expression was reproduced," software starts looking awkwardly unlike most of the creative media copyright was designed around. There are only so many ways to write code.

Copyright law already has a concept for this — it's called merger. If there are only a handful of sensible ways to express something, copyright protection gets very thin. Nobody owns the canonical for loop. Nobody owns the standard shape of a quicksort or a binary search. There's a related doctrine called scènes à faire for stock elements that are unavoidable in a genre. Google v. Oracle (2021) touched adjacent territory — the Court treated Java's declaring code as highly functional and ultimately ruled Google's use fair, with functional constraint as one of the factors that pulled the analysis in Google's direction.

Apply this to the AI debate and a lot of the "look, the model emitted GPL code!" claims get weaker on inspection. Train on enough code and exact matches alone stop telling you very much — most non-trivial codebases share enough surface patterns that something is going to collide. The real legal test isn't "does the output match." It's "does the output match in ways that have no functional justification."

Strong evidence of copying: idiosyncratic variable names, distinctive comment style, unusual algorithmic choices, reproduced bugs, copyright headers emitted verbatim, an author's specific tics. The famous Copilot examples — the Quake III fast inverse square root with the // what the fuck? comment intact, full GPL licence headers — are real and damning. They have no merger defence.

Weak evidence of copying: a quicksort that looks like every other quicksort, a hash function that matches because there are six reasonable ways to write one, boilerplate that converges because boilerplate converges. A court applying merger doctrine would throw most of these out without breaking a sweat.

So the actual remaining infringement concern isn't "regurgitation happens." It's targeted regurgitation of idiosyncratic, non-functionally-constrained expression. Exact-match suppression is tractable, and some vendors are already doing it. Detecting transformed or partially memorised output is much harder in practice, and that's where the real engineering work sits. But it's still engineering work, not a philosophical impasse.

What actually remains

Once you get past the slogans, the objections narrow pretty quickly. None of what remains is wrong. None of it is what the discourse usually sounds like.

The first is auditability. Open source culture runs on receipts — git blame, mailing list archives, CVE databases, sign-off lines — the whole apparatus is built around being able to trace value to its source. RHEL's contribution to the commons is auditable down to the patch. Valve's is auditable down to the developer. AI vendors offer no equivalent. The training corpus is undisclosed, the weights are closed, and there's no way to compute what fraction of a model's capability came from your project versus someone else's. The objection isn't really "you took our code." It's "you took our code and we have no way to audit what happened next." That's a process complaint, but it's a legitimate one, and it could in principle be answered.

The second is targeted regurgitation — the case where models emit idiosyncratic chunks of training data verbatim, not statistical convergence on standard patterns but actual reproduction of distinctive expression. This is a real infringement concern, but it's an engineering one. Exact-match detection is solved. Semantically equivalent memorisation isn't. The work is real, but the problem is bounded.

The third is harder, because it doesn't have a copyright answer at all. A human inspired by reading Linux gets a modest productivity boost on their next project — they still have to write it. An LLM trained on Linux gives every developer using it a substantial productivity boost, sold by subscription, to millions of users. The legal status is the same as the inspired human. The economic transfer is wildly different. Copyright was never designed to police that gap, because until now the gap didn't exist — inspiration was bounded by human cognitive throughput. This is a real concern, but it's a policy question about whether we want a new tax or licence regime for industrial-scale inspiration. Conflating it with copyright, the way most of the community rhetoric does, is sloppy — copyright doesn't cover what we're actually upset about.

Three things, then. Publish training corpora. Suppress idiosyncratic regurgitation. Have a serious conversation about whether productivity transfers at this scale need a policy response. None of it requires rejecting AI.

The reframe

Which brings me to the position I've actually landed on, which is that the community has been judging AI vendors by the wrong standard.

In the open source communities I'm part of — GNOME, Rust crates ecosystem, the desktop Linux world — AI-assisted development is already flowing back into public codebases at substantial scale. Every Rust crate, every GTK widget, every kernel patch that gets shipped faster because someone had a competent pair programmer in their editor is contribution to the commons. It just doesn't show up on the AI vendor's ledger. If you measure contribution by what ends up in the commons rather than what the model vendor open-sources, the ledger might already be net positive. We're measuring the wrong column.

The community's current position is, I think, partly a category error. It's judging AI vendors by the standard we apply to forges — GitHub, GitLab, SourceHut — when the closer analogue is compilers and IDEs. Nobody demanded GCC's optimisation heuristics be reproducible from public data, or that JetBrains open-source IntelliJ before you were allowed to write Linux patches in it. The analogy isn't perfect — compilers don't ingest copyrighted corpora the way foundation models do — but culturally we treated those things as productivity tools rather than infrastructure providers. We judged them by what their users produced.

There's a coherent version of the pro-AI argument that says: AI vendors are toolmakers, not platform owners. Judge them by what their users produce. And the produce here is overwhelmingly more open source, faster.

Most contributors I know already use these tools. The real issue is what would let maintainers admit that publicly without feeling like they're conceding the entire argument — and the answer, when you work it out, turns out to be a fairly short list. Receipts, regurgitation suppression, and an honest policy conversation about productivity transfer. That's all of it.

Compared to where the discourse usually sits, that's a much shorter list than the rhetoric suggests.

How My Library Code Has No Idea It Has a Sync Backend

Justin - FromTheArchitect — Tue, 19 May 2026 22:00:00 +0000

Half of the library code in Moments, my photo manager, calls a one-method trait after every database write. That trait has two implementations. One of them returns Ok(()) and does nothing else. From inside the library, there is no way to tell which one is wired up.

That is the entire architecture of how Moments syncs to Immich — and the entire reason the local backend, which has no sync at all, is the same program as the Immich one.

This post is about that trait, the enum it consumes, the outbox table underneath it, and the architectural property they buy together: a library that has no idea it has a sync backend, and a sync backend that's purely additive to it.

The offline-first problem

Moments has two backends. The local backend stores photos on disk and indexes them in SQLite. The Immich backend talks to a self-hosted Immich server but caches everything in the same SQLite schema — the UI reads from the local DB either way, and an Immich library works fully offline after initial sync.

That means local writes have two possible destinations. Always the local DB. Sometimes — if the backend happens to be Immich — also a remote server, eventually, when the network cooperates. "Trash these three assets" should commit locally, return immediately, and arrange for the server to be told later. "Create this album" should be visible in the UI the moment the row hits the database, regardless of whether the push call has happened, will happen, or will fail and retry six times.

The naive answer is to give every service a reference to the sync layer. MediaService::trash calls sync.enqueue_trash(ids) after writing to the DB. AlbumService::create calls sync.enqueue_album_created(album). It works for the Immich backend. It also pollutes the local backend, which has no sync, with either a second constructor for every service or an Option<SyncHandle> carried everywhere it's irrelevant. Every service in the library starts to know that there is such a thing as sync.

What I wanted instead was: services produce a value describing what they changed, and someone else decides whether to do anything about it.

The vocabulary

The value is Mutation, in src/library/mutation.rs. It is an enum of state changes the library has just committed:

#[derive(Debug, Clone)]
pub enum Mutation {
    AssetTrashed       { ids: Vec<MediaId> },
    AssetFavorited     { ids: Vec<MediaId>, favorite: bool },
    AssetDeleted       { items: Vec<(MediaId, Option<String>)> },
    AlbumCreated       { id: AlbumId, name: String },
    AlbumMediaAdded    { album_id: AlbumId, media_ids: Vec<MediaId> },
    AssetEditsApplied  { id: MediaId },
    // …
}

Eighteen variants in total — asset lifecycle, album lifecycle, edit application, stacks, tags, people. The shape matters more than the count: every variant names a state change the database has just committed.

The discipline that keeps this enum small is what it deliberately isn't. There are no *Requested variants — UI intent isn't a mutation, it's a method call on a service. There are no *Result variants — results are return values. There are no UI hint variants like ThumbnailReady — those are events on a specific service's event emitter and don't belong here.

A Mutation is one thing: a state change the database has just committed, that might need to leave the machine. Nothing more.

The trait

MutationRecorder is in src/library/recorder.rs. It is the entire interface between the library and whatever wants to know what changed:

#[async_trait]
pub trait MutationRecorder: Send + Sync {
    async fn record(&self, mutation: &Mutation) -> Result<(), LibraryError>;
}

That is it. One method, async, takes a borrowed Mutation, returns an error if recording itself failed. Services hold an Arc<dyn MutationRecorder> and call it after a successful write:

pub async fn trash(&self, ids: Vec<MediaId>) -> Result<(), LibraryError> {
    self.repo.trash(&ids).await?;
    self.recorder.record(&Mutation::AssetTrashed { ids }).await?;
    Ok(())
}

A service has no idea what the recorder does with the mutation. It might write a row to a queue table. It might publish to a message broker. It might do absolutely nothing.

Two strategies, one of which is empty

There are exactly two implementations, both in src/sync/outbox/mod.rs.

The first is the entire point of the design:

pub struct NoOpRecorder;

#[async_trait]
impl MutationRecorder for NoOpRecorder {
    async fn record(&self, _mutation: &Mutation) -> Result<(), LibraryError> {
        Ok(())
    }
}

The local backend takes NoOpRecorder. Every service in the library still calls recorder.record(...) after every mutation. Those calls do nothing.

The code path is identical to the Immich one. No if backend == local anywhere in the services. No second constructor. Just a vtable dispatch and an Ok(()).

The second is the implementation that does the actual work:

pub struct QueueWriterOutbox { repo: OutboxRepository }

#[async_trait]
impl MutationRecorder for QueueWriterOutbox {
    async fn record(&self, mutation: &Mutation) -> Result<(), LibraryError> {
        for row in mutation.to_outbox_rows() {
            self.repo.insert(&row).await?;
        }
        Ok(())
    }
}

QueueWriterOutbox is used by the Immich backend. It serialises the mutation into one or more rows in a sync_outbox table — multi-id mutations like AssetTrashed { ids: [a, b, c] } fan out to three rows so retries can be per-entity rather than per-batch. The schema is unsurprising: id, entity_type, entity_id, action, payload (JSON), created_at, plus status, attempts, next_attempt_at, and last_error for retry bookkeeping. This is the transactional outbox pattern, more commonly seen in service-to-service messaging, applied here to client-server sync — with one small adaptation to the trait signature I'll come to in the next section.

The mapping from Mutation to OutboxRow lives in src/sync/outbox/mutation.rs and is genuinely boring — a match on the variant producing an entity_type string, an entity_id, an action verb, and an optional JSON payload. It is the kind of code that should be boring; the interesting part has already happened.

My favourite test in this codebase

My favourite test in Moments doesn't assert on database state. It doesn't assert on side effects. It asserts on a sequence of Mutations the library produced — on what the library said it did, in its own vocabulary, in order. That test works because the third implementation of MutationRecorder lives in src/library/recorder.rs:

#[derive(Default)]
pub(crate) struct CapturingRecorder {
    recorded: Mutex<Vec<Mutation>>,
}

impl CapturingRecorder {
    pub(crate) fn snapshot(&self) -> Vec<Mutation> {
        self.recorded.lock().unwrap().clone()
    }
}

#[async_trait]
impl MutationRecorder for CapturingRecorder {
    async fn record(&self, mutation: &Mutation) -> Result<(), LibraryError> {
        self.recorded.lock().unwrap().push(mutation.clone());
        Ok(())
    }
}

Service tests construct a Library with Arc::new(CapturingRecorder::default()) and then assert on the recorded sequence after exercising a method. "When I trash three assets, then create an album from two of them, the recorder should see AssetTrashed followed by AlbumCreated followed by AlbumMediaAdded." That assertion is a stronger property than "the database ends up in the right state", because it pins down the intent surface the library exposes to anything that might eventually act on it — including providers that don't exist yet.

This is what the trait actually buys: not two production strategies, but three perspectives on the same library code — a no-op that proves the local backend doesn't care, a queue writer that ships changes upstream, and a capturing fixture that pins down what services promise. None of them required a single change to the services themselves.

Dependency injection: sync as someone else's problem

The wiring happens in exactly one place. Library::open takes the recorder as a parameter and threads it into every service:

pub async fn open(
    bundle: Bundle,
    mode: LocalStorageMode,
    db: Database,
    recorder: Arc<dyn MutationRecorder>,
    resolver: Arc<dyn OriginalResolver>,
) -> Result<Self, LibraryError> {
    db.open(&bundle.database.join("moments.db")).await?;

    let albums  = AlbumService::new(db.clone(), Arc::clone(&recorder));
    let faces   = FacesService::new(db.clone(), bundle.thumbnails.clone(), Arc::clone(&recorder));
    let editing = EditingService::new(db.clone(), Arc::clone(&recorder));
    let media   = MediaService::new(db.clone(), bundle.originals.clone(), mode,
                                    Arc::clone(&recorder), resolver);
    // …

    Ok(Self { albums, faces, editing, media, /* … */, recorder })
}

The local backend's caller hands in Arc::new(NoOpRecorder). The Immich backend's caller hands in Arc::new(QueueWriterOutbox::new(db.clone())), and separately starts a background PushManager that drains the same table.

That single substitution — the choice of recorder at the call site — is the only thing in the system that knows whether sync is happening. Everything below it is identical. From the library's point of view, sync is someone else's problem: it dutifully describes what it changed and trusts that someone, somewhere, may care.

The drain side

For completeness: src/sync/providers/immich/push.rs is the PushManager. It is a long-running Tokio task that wakes up on an interval, reads up to a hundred pending rows from sync_outbox, deserialises each back into an OutboxMutation, makes the appropriate Immich API call, and marks the row done or failed. There is exponential backoff on failure, a DeadLetter status after ten consecutive failures, and a MAX_BACKOFF_SECS cap so attempt ten doesn't sleep for seventeen hours.

It is the side of the system that has to know about HTTP, retries, idempotency, and Immich-specific endpoints. It is also the side that doesn't exist at all when you're running the local backend, because nobody constructed it.

The pull side (pull.rs + handlers/) is the reverse direction — POST /sync/stream streams server-side changes back into the local DB. It does not go through the recorder: pull-driven changes are server-originated, and recording them would feed the server's own news straight back into the outbox heading the other way.

Adapting the pattern

The classical transactional outbox pattern — the one I borrowed the name and the table from — requires the business write and the outbox INSERT to share a single database transaction. That's the whole point of the pattern: if the entity write commits, the outbox row commits with it; if either fails, both roll back. Atomicity is what guarantees the consumer eventually sees every committed change.

Moments needs that guarantee, non-negotiably. If trash returns success to the caller, the outbox row must be there waiting for the push manager. Otherwise the local state silently drifts ahead of the server: the user trashes a photo, the desktop hides it, the server never hears about it, and the next pull cycle dutifully restores it. A sync layer that loses writes is worse than no sync layer at all — once the user catches it doing that, they stop trusting it for everything else.

The adaptation is small but load-bearing. The trait signature I've shown so far is simplified for exposition; the real one takes a transaction handle, and the three implementations all thread it through. Services own the transaction lifecycle, and both the repository write and the recorder call happen inside the same transaction:

#[async_trait]
pub trait MutationRecorder: Send + Sync {
    async fn record(
        &self,
        tx: &mut sqlx::Transaction<'_, Sqlite>,
        mutation: &Mutation,
    ) -> Result<(), LibraryError>;
}

// in MediaService:
pub async fn trash(&self, ids: &[MediaId]) -> Result<(), LibraryError> {
    let mut tx = self.db.begin().await?;
    self.repo.trash_in_tx(&mut tx, ids).await?;
    self.recorder
        .record(&mut tx, &Mutation::AssetTrashed { ids: ids.to_vec() })
        .await?;
    tx.commit().await?;
    Ok(())
}

QueueWriterOutbox::record uses the transaction handle to insert into sync_outbox inside the same transaction the service is about to commit. If the insert fails, the ? propagates and tx.commit() is never called; the business write rolls back with it. The local database and the outbox share a fate by construction — neither can be ahead of the other.

NoOpRecorder ignores the transaction parameter entirely. The local backend pays for opening and committing a transaction the recorder didn't touch — a small, fixed cost on every mutation, in exchange for the library never having to know which recorder it's been given. That's the price of the abstraction, and it's the only price the abstraction asks the local backend to pay.

An honest aside, because the timing is too good to leave out. I drafted this section assuming the code matched the design above. Then I went to check. It didn't. The actual service code commits the repository write and then calls the recorder in a second, separate await — and at most call sites the recorder error is logged and swallowed rather than propagated. A recorder failure can silently leave the local state ahead of the outbox, which is exactly the failure mode this section claims is impossible by construction. I filed the bug while finishing this paragraph.

The design above is the design. The code is catching up.

Adding a third backend

The shape of the substitution generalises beyond Immich. Adding a Nextcloud backend tomorrow would touch zero lines in src/library/. The services already produce Mutations. The outbox table is provider-agnostic. The new code lives entirely in src/sync/providers/nextcloud/: an HTTP client, a push manager that drains the outbox into Nextcloud's API, and a pull manager that streams server-side changes back into the local DB. The wiring in main swaps QueueWriterOutbox in as the recorder, starts the Nextcloud managers, and is done.

That doesn't make a new backend free — push and pull are still real work, with their own retry semantics and identity gotchas — but it does make the cost proportional to what's actually different. The 99% of the app that doesn't care which server it's talking to doesn't have to be told.

Why a trait, and not a channel

The same job could be done with an mpsc::UnboundedSender<Mutation> — services hold a sender and push mutations into it; a consumer task somewhere pulls them out. A channel even handles NoOpRecorder naturally: open a channel and never spawn a consumer — the sends just buffer.

But a channel ties the producer and the consumer to a specific lifecycle. Who closes the sender? When? What happens when the buffer fills? Is the consumer guaranteed to run, and if not, are the dropped messages a bug or a feature? The trait sidesteps all of this by making "what to do with a mutation" a synchronous decision at the point of production. NoOpRecorder returns immediately. QueueWriterOutbox writes a row and returns. CapturingRecorder pushes onto a vec and returns. There is no pending state, no backpressure, no "what if the consumer crashed" failure mode lurking in the design. The service doesn't have to reason about whether its mutation was received, because reception is part of the same await as the rest of the operation.

A Box<dyn Fn(Mutation)> closure could work too, and would even be slightly cheaper. The reason the trait wins isn't performance; it's naming. NoOpRecorder, QueueWriterOutbox, CapturingRecorder — each one is a documented, importable type that says what role it plays. A closure is anonymous; it can do anything; you cannot grep for who's using it. The trait makes the contract a concrete thing that can be referred to in design documents and PR descriptions, and the production implementations a fixed, small set that anyone can enumerate.

The verb "record" matters too. "Emit" or "publish" or "broadcast" would have invited fan-out — and fan-out is exactly the property Mutation has been built to avoid. There is one recipient, statically chosen at Library::open time. "Record" implies durability and report-after-the-fact, which is what services actually do: they write to the database, then they describe what they wrote. The naming makes the contract harder to violate.

What I'd tell myself

If I were starting the Immich backend again, I would write MutationRecorder and NoOpRecorder on day one, before there was anything that needed syncing, and have services call it from the start. The local backend would carry a NoOpRecorder it would never need, and when the Immich backend arrived months later, nothing in the services would change. That's the value the trait actually provides: not a separation of concerns at the API surface, but the freedom to add an entire concern later without rewriting what's already there.

The library doesn't know sync exists. grep -rn 'crate::sync' src/library/ returns six matches: five are #[cfg(test)] imports of NoOpRecorder from test helpers, one a comment pointer. Production imports: zero. From the inside, the local backend and the Immich backend are the same program; the only difference is what an Arc<dyn …> happens to do.

The Shape of Decoupling

Justin - FromTheArchitect — Tue, 12 May 2026 07:01:30 +0000

There is a moment in every codebase where someone draws a box on a whiteboard, labels it EventBus, and draws arrows fanning out to every other box. The room nods. It looks like architecture. It looks like the right architecture — loosely coupled, extensible, the textbook answer to "how do we let many components react to one thing happening?"

That diagram is a trap. I drew it for Moments, my photo manager, in late March 2026. I had the design reviewed by an external UI architect. I shipped it in April across six phased PRs. And on the third of May I deleted the whole thing in a single commit titled, with some satisfaction:

refactor: delete EventBus, AppEvent, library/commands, MediaClient v1 — closes #580

This is what I learned about why the bus was wrong, what replaced it, and the broader pattern: an event bus is decoupling-by-indirection, and the indirection itself is the cost.

What the bus looked like

The original design was, by the standards of the form, a good one. A single EventBus lived on the GTK main thread. Background Tokio tasks pushed AppEvents into it via a Send + Clone sender. glib::idle_add_once drained the queue and fanned out to subscribers. Subscriptions were RAII-handle-based with re-entrancy-safe deferred drops. It had tests. It had a design doc. It worked.

Here is the central type — the bit that everything else depended on:

#[derive(Debug, Clone)]
pub enum AppEvent {
    Error(String),
    ThumbnailReady { media_id: MediaId },

    // Commands: UI intent → library command handler
    TrashRequested { ids: Vec<MediaId> },
    FavoriteRequested { ids: Vec<MediaId>, state: bool },
    AddToAlbumRequested { album_id: AlbumId, ids: Vec<MediaId> },
    CreateAlbumRequested { name: String, ids: Vec<MediaId> },
    DeleteAlbumRequested { ids: Vec<AlbumId> },
    // ...

    // Results: command handler → subscribers
    MediaTrashed { ids: Vec<MediaId> },
    AlbumCreated { album: Album },
    // ...
}

By the time I deleted it, AppEvent had twenty-one variants in a single file, split into "commands" (UI intent) and "results" (library outcomes). Buttons emitted *Requested events. A CommandHandler trait dispatched each one to a struct in src/commands/. Library backends emitted *Result events. Widgets subscribed to whichever results they cared about and patched their ListStore models.

It was internally consistent, and it was wrong.

Where it started hurting

There was no single bug big enough to justify deleting it. There was just the same small bug, in slightly different costumes, every week.

The enum became a junk drawer. Every new feature added a request variant and a result variant. The file grew. Understanding what could fire meant scanning the whole enum. Worse, dead variants accumulated: refactor: remove dead AppEvent variants (#576) is a real commit, removing variants that had no subscribers anywhere. Nobody had noticed because the bus made the absence of subscribers invisible.

Double-update bugs. When the album-create button fires CreateAlbumRequested, the command handler calls the library, gets back an Album, and emits AlbumCreated. The album grid widget — which initiated the action — also subscribes to AlbumCreated, because how else would it learn? So the widget refreshes from the broadcast. But the widget's own code path knew the result first and tried to insert the row optimistically. Now you have two writers fighting over the same ListStore. The fix in any individual case is easy — guard with a flag, defer one path. The pattern of needing the fix everywhere is the smell.

Re-entrancy hazards. One commit message that survives in the history reads fix: defer navigate in ImportComplete handler to avoid bus re-entrancy. A subscriber to ImportComplete navigated to a new view. Navigating triggered unrealize on the old view. unrealize dropped a Subscription. Dropping a Subscription mutated the bus's subscriber list — while the bus was iterating it. The original design had anticipated this and added a "deferred removals" mechanism. That mechanism was a tax on every drop, paid forever, to fix a problem the bus itself created.

O(n) no-op events. During an Immich sync, the face-recognition service updates the face_count on every person row. There can be hundreds. Each update fired a result event. Each event hit every subscriber, even though face_count wasn't a property any GObject was bound to. The fix was to teach the service to skip emission for update_face_count. So now the service had to know which of its own state changes were "broadcast-worthy" — which is a leaky responsibility for a layer that shouldn't know who's listening at all.

You can't follow it at runtime. Set a breakpoint on bus.send(). Hit it. Where does control end up? Twelve subscribers across four widgets and two background services, in some order, on the next idle tick. Now do that for an interaction that fires three events. The bus had given me decoupling at the cost of being unable to read the program.

The translation layer was the first thing to fall. Library events arrived as a separate LibraryEvent enum and were translated into AppEvent at the boundary. The translation was pure ceremony. It came out in refactor: eliminate LibraryEvent → AppEvent translation loop (#520) — about three weeks after the bus shipped. That should have been the warning sign: the bus's main job had been routing events from one layer to another, and as soon as the layers started talking directly, the bus's reason for existing started to thin out.

What replaced it

The replacement is, deliberately, almost boring. Each library service holds its own typed EventEmitter<T> and emits a small enum specific to that service:

#[derive(Debug, Clone)]
pub enum AlbumEvent {
    AlbumAdded(AlbumId),
    AlbumUpdated(AlbumId),
    AlbumRemoved(AlbumId),
    AlbumMediaChanged(AlbumId),
}

Four variants. Owned by the album feature. Nothing about media, faces, sync, errors, or UI intent.

The EventEmitter<T> itself is a single file:

pub struct EventEmitter<T: Clone> {
    senders: Arc<Mutex<Vec<mpsc::UnboundedSender<T>>>>,
}

impl<T: Clone> EventEmitter<T> {
    pub fn subscribe(&self) -> mpsc::UnboundedReceiver<T> {
        let (tx, rx) = mpsc::unbounded_channel();
        self.senders.lock().expect("poisoned").push(tx);
        rx
    }

    pub fn emit(&self, event: T) {
        let mut senders = self.senders.lock().expect("poisoned");
        senders.retain(|tx| tx.send(event.clone()).is_ok());
    }
}

A subscriber gets a fresh receiver. Dead receivers prune themselves on the next emit. Clones share the same subscriber set. That is the entire primitive.

The service uses it in two places — once to expose subscription, once to emit:

pub struct AlbumService {
    db: Arc<Database>,
    events: EventEmitter<AlbumEvent>,
}

impl AlbumService {
    pub fn subscribe(&self) -> mpsc::UnboundedReceiver<AlbumEvent> {
        self.events.subscribe()
    }

    pub async fn delete_album(&self, id: &AlbumId) -> Result<()> {
        self.db.delete_album(id).await?;
        self.events.emit(AlbumEvent::AlbumRemoved(id.clone()));
        Ok(())
    }
}

On the GTK side, the client subscribes once at configure time and spawns a Tokio listener that dispatches model patches back to the main thread:

pub fn configure(&self, library: Arc<Library>, tokio: tokio::runtime::Handle,
                 events_rx: mpsc::UnboundedReceiver<AlbumEvent>) {
    let client_weak: glib::SendWeakRef<AlbumClientV2> = self.downgrade().into();
    tokio.spawn(Self::listen(events_rx, library, client_weak));
}

async fn listen(mut rx: mpsc::UnboundedReceiver<AlbumEvent>,
                library: Arc<Library>,
                client_weak: glib::SendWeakRef<AlbumClientV2>) {
    while let Some(event) = rx.recv().await {
        match event {
            AlbumEvent::AlbumRemoved(id) => {
                let weak = client_weak.clone();
                glib::idle_add_once(move || {
                    if let Some(client) = weak.upgrade() {
                        client.remove_from_models(&id);
                    }
                });
            }
            // ...
        }
    }
}

That is the whole architecture. There is no central registry. There is no AppEvent enum. The album feature defines its events, owns its emitter, and hands receivers to whoever asks. A new feature adds a new service with its own emitter; nothing in the existing code has to change.

The double-update fix that was a design fix

The most interesting thing about the new pattern isn't the channel itself. It's a small contract documented on every command method:

Client-initiated mutations don't emit events — the client patches its model directly in its callback.

When AlbumClientV2::create_album runs, it calls the service, gets back the new album, inserts it into its tracked models itself, and that's that. The service does not fire AlbumAdded for client-initiated work. The bus-era double-update bug cannot exist, because the broadcast path and the initiator path are no longer the same path.

The bus had pushed me toward "everyone reacts to everything uniformly", which sounds clean and is a lie — initiators always know more than subscribers. The new design lets the initiator use what it knows. Events are reserved for state changes the initiator didn't cause: a remote sync arriving, a background scan completing, a peer process writing the database.

What I'd tell myself in 2025

Three things, in order of how useful they would have been.

An event bus is decoupling-by-indirection. It feels like you've removed a dependency. You haven't. You've moved it into a giant enum that nobody owns and that everyone has to read to understand the program. The dependency is still there; you've just made it untyped, ungrep-able, and impossible to follow at runtime. A direct mpsc::UnboundedSender<AlbumEvent> from the album service to the album client is more coupled than a bus message of type AppEvent::AlbumCreated, and that coupling is exactly what makes the program legible.

The fan-out problem is rarer than you think. I had reached for a bus because "many subscribers might react to one event." In practice, almost every event in Moments has one or two subscribers, and the subscribers are statically known. A bus's variable, late-bound subscriber list buys you very little when the real subscriber set is "the album client and nothing else."

Architecture review can validate internal consistency but not problem fit. The bus design was reviewed and approved. The reviewer was right that, given the bus, the design was sound. They couldn't have told me — and I couldn't have asked — whether a bus was the right shape for the problem in the first place. That's a question only a few weeks of using it can answer, and in this case a few weeks were enough. Build the smallest version of the boring thing first. Earn the right to a bus.

The deletion commit removed about 1,200 lines net. The replacement, including EventEmitter and four service-specific event enums, is closer to 200. The bus had been doing what a thin wrapper around mpsc does, dressed up as architecture.

I don't regret building it — without the bus there'd be nothing concrete to compare against, and the lessons would have stayed in the realm of opinion. But if I were starting again, I would write pub fn subscribe(&self) -> mpsc::UnboundedReceiver<AlbumEvent> first and not draw the diagram at all.

Building GNOME Apps with Rust, Part 4: Blueprint

Justin - FromTheArchitect — Fri, 08 May 2026 13:10:53 +0000

This is Part 4 of a series taking a GNOME app from an empty directory to GNOME Circle. Part 3 walked through every file Builder generated for our gazette project. Now we're going to start changing things.

If you're new to this stack and wondering why GTK and libadwaita are separate libraries, why GObject's type system feels like 1990s C, or why Flatpak ships its own runtime alongside your app, there's a short companion piece on the history of the stack. Skim it for context or skip it for code.

The XML problem

At the end of Part 3, we had a working app. A header bar, a hamburger menu, a "Hello, World!" label, and a window.ui file that looked like this:

<?xml version="1.0" encoding="UTF-8"?>
<interface>
  <requires lib="gtk" version="4.0"/>
  <requires lib="Adw" version="1.0"/>
  <template class="GazetteWindow" parent="AdwApplicationWindow">
    <property name="title" translatable="yes">Gazette</property>
    <property name="default-width">800</property>
    <property name="default-height">600</property>
    <property name="content">
      <object class="AdwToolbarView">
        <child type="top">
          <object class="AdwHeaderBar">
            <child type="end">
              <object class="GtkMenuButton">
                <property name="primary">True</property>
                <property name="icon-name">open-menu-symbolic</property>
                <property name="tooltip-text"
                          translatable="yes">Main Menu</property>
                <property name="menu-model">primary_menu</property>
              </object>
            </child>
          </object>
        </child>
        ...

Read that aloud. Notice how much of it is structural noise — <object class="...">, <property name="...">, opening and closing tags wrapping single values. The actual information — "there's a header bar with a menu button on the right" — is buried under a layer of XML scaffolding. And we haven't even built any UI yet.

This isn't a fixable problem in XML. It's how XML works. So GNOME has a different answer.

Blueprint

Blueprint is a markup language built for GTK. It compiles to the same .ui XML GTK has always loaded — the runtime artefact is identical — but the file you actually write looks like real code:

using Gtk 4.0;
using Adw 1;

template $GazetteWindow : Adw.ApplicationWindow {
  title: _("Gazette");
  default-width: 800;
  default-height: 600;

  content: Adw.ToolbarView {
    [top]
    Adw.HeaderBar {
      [end]
      MenuButton {
        primary: true;
        icon-name: "open-menu-symbolic";
        tooltip-text: _("Main Menu");
        menu-model: primary_menu;
      }
    }

    content: Label label {
      label: _("Hello, World!");

      styles ["title-1"]
    };
  };
}

menu primary_menu {
  section {
    item {
      label: _("_Preferences");
      action: "app.preferences";
    }
    item {
      label: _("_Keyboard Shortcuts");
      action: "app.shortcuts";
    }
    item {
      label: _("_About Gazette");
      action: "app.about";
    }
  }
}

Same widget tree. Same template binding. Same translatable strings. About a third the line count, and you can actually scan the structure without your eyes glazing over.

Two bits of syntax are worth knowing up front. The $ on $GazetteWindow is there because it's a user-defined type — the compiler can't validate it against a .gir, so the $ is your acknowledgement that you know what you're doing. Built-in types like Adw.ApplicationWindow never need it. And [top], [end] are child types, equivalent to <child type="top"> in XML, placed immediately before the child they apply to. The rest — using for namespace imports, _("...") for translatable strings, styles ["..."] for CSS classes — you can pick up by porting.

Wiring Blueprint into the build

Blueprint is a separate compiler, not a built-in GTK feature. Before we change any UI, we need to teach Meson how to invoke it and update the GResource manifest to bundle the generated .ui files instead of the original ones.

Is `blueprint-compiler` available?

blueprint-compiler ships in the GNOME 50 SDK (which we upgraded to at the end of Part 3), so inside the Flatpak build sandbox we don't need to install anything. If you're targeting an older runtime where it isn't included, you'd add it as a module in the Flatpak manifest:

"modules" : [
    {
        "name" : "blueprint-compiler",
        "buildsystem" : "meson",
        "cleanup" : ["*"],
        "sources" : [
            {
                "type" : "git",
                "url" : "https://gitlab.gnome.org/GNOME/blueprint-compiler.git",
                "tag" : "v0.20.4"
            }
        ]
    },
    {
        "name" : "gazette",
        ...
    }
]

For us on GNOME 50, that block isn't necessary. Just confirming the binary exists is enough.

Updating `src/meson.build`

Open src/meson.build. We need to add a custom_target that runs blueprint-compiler batch-compile over our .blp files and produces matching .ui files in the build directory. Then we point the existing gnome.compile_resources call at those generated files via a dependency.

Here's the relevant addition, sitting just above the existing compile_resources call:

blueprints = custom_target('blueprints',
  input: files(
    'window.blp',
    'shortcuts-dialog.blp',
  ),
  output: '.',
  command: [
    find_program('blueprint-compiler'),
    'batch-compile',
    '@OUTPUT@',
    '@CURRENT_SOURCE_DIR@',
    '@INPUT@',
  ],
)

gnome.compile_resources('gazette',
  'gazette.gresource.xml',
  dependencies: blueprints,
  gresource_bundle: true,
  install: true,
  install_dir: pkgdatadir,
)

The dependencies: blueprints line is what ties the two together. Without it, Meson might try to compile resources before Blueprint has produced the .ui files, and you'll get a mystifying "file not found" error mid-build.

`gazette.gresource.xml` is unchanged

The resource manifest still references window.ui and shortcuts-dialog.ui. It doesn't mention .blp at all — and that's the part that catches people.

<?xml version="1.0" encoding="UTF-8"?>
<gresources>
  <gresource prefix="/io/github/fromthearchitect/gazette">
    <file preprocess="xml-stripblanks">window.ui</file>
    <file preprocess="xml-stripblanks">shortcuts-dialog.ui</file>
  </gresource>
</gresources>

That's because gnome.compile_resources looks for the listed files first in the source directory, then in the build directory — and our custom_target writes the generated .ui files into the build directory at exactly the right relative path. The Rust code referencing /io/github/fromthearchitect/gazette/window.ui doesn't know or care that the file went through a Blueprint compile step on the way in.

This is the bit I want you to internalise: Blueprint is purely a build-time concern. The runtime artefact is identical. If anything goes wrong at runtime, it's a GTK problem, not a Blueprint problem — and the error messages will reference XML structures because that's what GTK sees.

Updating `POTFILES.in`

Open po/POTFILES.in. Builder's scaffold lists one source file alongside the desktop integration files:

data/io.github.fromthearchitect.gazette.desktop.in
data/io.github.fromthearchitect.gazette.metainfo.xml.in
data/io.github.fromthearchitect.gazette.gschema.xml
src/window.ui

Two changes. First, point at window.blp instead of window.ui. Second, add shortcuts-dialog.blp — Builder doesn't list it, but the strings in there need extracting too:

data/io.github.fromthearchitect.gazette.desktop.in
data/io.github.fromthearchitect.gazette.metainfo.xml.in
data/io.github.fromthearchitect.gazette.gschema.xml
src/shortcuts-dialog.blp
src/window.blp

Why point at the .blp files rather than the generated .ui files? Gettext extracts strings by parsing source files for known patterns — _("...") in Blueprint, translatable="yes" in XML, gettext!() in Rust, etc. If POTFILES.in lists the generated .ui files, extraction will work, but the line numbers in your .po files will reference auto-generated paths in the build directory that change between builds. Pointing at the .blp source means translators see meaningful filenames and stable line numbers.

The Meson i18n module's xgettext invocation already scans for _(...) and C_(...) calls regardless of file type, so listing .blp files works without any Blueprint-specific extractor.

Porting the existing UI files

Now the actual conversion. Two files: window.ui and shortcuts-dialog.ui.

If you had dozens of files to convert, you'd run blueprint-compiler port from the project root and it would scan the project, generate .blp versions of every .ui file, and update the references for you. We've got two files, so it's just as quick to do it by hand and learn the syntax in the process.

`window.blp`

Delete src/window.ui. Create src/window.blp:

using Gtk 4.0;
using Adw 1;

template $GazetteWindow : Adw.ApplicationWindow {
  title: _("Gazette");
  default-width: 800;
  default-height: 600;

  content: Adw.ToolbarView {
    [top]
    Adw.HeaderBar {
      [end]
      MenuButton {
        primary: true;
        icon-name: "open-menu-symbolic";
        tooltip-text: _("Main Menu");
        menu-model: primary_menu;
      }
    }

    content: Label label {
      label: _("Hello, World!");

      styles ["title-1"]
    };
  };
}

menu primary_menu {
  section {
    item {
      label: _("_Preferences");
      action: "app.preferences";
    }
    item {
      label: _("_Keyboard Shortcuts");
      action: "app.shortcuts";
    }
    item {
      label: _("_About Gazette");
      action: "app.about";
    }
  }
}

Compare against the original XML if you want — every property, child, and string carries across one-to-one.

The one thing worth pointing out is Label label. In Blueprint, when you want to give a widget an ID (so the Rust side can grab it as a TemplateChild), you put the ID after the type, with no id: keyword. It feels weird at first if you're coming from XML's <object class="GtkLabel" id="label">, but it's consistent with how the rest of the language treats names.

`shortcuts-dialog.blp`

Builder's template for shortcuts-dialog.ui is built around Gtk.ShortcutsWindow, which was deprecated in GTK 4.18; libadwaita 1.8 shipped a successor, Adw.ShortcutsDialog. Since Part 3 put us on GNOME 50 (libadwaita 1.9), we'll port to the modern widget while we're already in the file.

Delete src/shortcuts-dialog.ui and create src/shortcuts-dialog.blp:

using Gtk 4.0;
using Adw 1;

Adw.ShortcutsDialog shortcuts_dialog {
  Adw.ShortcutsSection {
    title: C_("shortcut window", "General");

    Adw.ShortcutsItem {
      title: C_("shortcut window", "Show Shortcuts");
      action-name: "app.shortcuts";
    }

    Adw.ShortcutsItem {
      title: C_("shortcut window", "Quit");
      action-name: "app.quit";
    }
  }
}

C_("context", "string") is the Blueprint equivalent of XML's <attribute name="label" translatable="yes" context="shortcut window"> — gettext context lets translators distinguish the same English word used in different UI contexts. Builder generates these for shortcut dialogs because "General" might translate differently depending on whether it's a settings category or a shortcut group.

The other thing worth knowing about this file is the widget ID. shortcuts_dialog is what AdwApplication looks for: if a shortcuts-dialog.ui resource exists at the application's resource base path and its root widget is an AdwShortcutsDialog with that ID, the application class automatically installs an app.shortcuts action that presents the dialog, plus a Ctrl+? accelerator. That's why Part 3's menu could reference app.shortcuts even though we never defined it ourselves.

The migration mapping, if you're updating an older project: Gtk.ShortcutsWindow → Adw.ShortcutsDialog, Gtk.ShortcutsGroup → Adw.ShortcutsSection, Gtk.ShortcutsShortcut → Adw.ShortcutsItem. The old "view → section → group → shortcut" hierarchy collapsed to "section → item". Two features didn't survive the trip: gesture shortcuts and per-shortcut icons. If you needed those, you stay on the deprecated widget. We don't, so we don't.

Build it

Hit Run. If everything is wired correctly, the app builds and launches looking exactly like it did at the end of Part 3.

If you get build errors, the most common causes are:

Forgot the dependencies: blueprints line — error references window.ui not found.
Typo in a Blueprint file — the compiler error is good, but it points at line numbers in the .blp, not the generated XML.
Old .ui file still on disk — if you copied the .blp instead of replacing the .ui, both exist and the resource bundle will pick up whichever Meson finds first.

A clean rebuild (Builder's Build → Clean Build Output) clears up most of these.

Now we have a foundation. Let's actually use it.

A "Hello, World!" label is fine for proving the pipeline works. It is not Gazette. Gazette needs a sidebar of feeds and an articles pane. On a phone, only one shows at a time.

Libadwaita has a widget for this exact pattern: Adw.NavigationSplitView. Side-by-side on a wide screen, single-pane navigation when collapsed — at least, once you wire up the breakpoint that tells it when to collapse. We'll get to that.

Replace the contents of window.blp with this:

using Gtk 4.0;
using Adw 1;

template $GazetteWindow : Adw.ApplicationWindow {
  title: _("Gazette");
  default-width: 1000;
  default-height: 700;

  Adw.Breakpoint {
    condition ("max-width: 600sp")

    setters {
      split_view.collapsed: true;
    }
  }

  content: Adw.NavigationSplitView split_view {
    sidebar: Adw.NavigationPage {
      title: _("Feeds");

      child: Adw.ToolbarView {
        [top]
        Adw.HeaderBar {}

        content: ScrolledWindow {
          child: ListBox feed_list {
            selection-mode: single;

            styles ["navigation-sidebar"]

            ListBoxRow {
              child: Label {
                label: _("All Articles");
                halign: start;
                margin-start: 12;
                margin-end: 12;
                margin-top: 6;
                margin-bottom: 6;
              };
            }
          };
        };
      };
    };

    content: Adw.NavigationPage {
      title: _("Articles");

      child: Adw.ToolbarView {
        [top]
        Adw.HeaderBar {
          [end]
          MenuButton {
            primary: true;
            icon-name: "open-menu-symbolic";
            tooltip-text: _("Main Menu");
            menu-model: primary_menu;
          }
        }

        content: Adw.StatusPage placeholder {
          icon-name: "rss-symbolic";
          title: _("No Feed Selected");
          description: _("Select a feed from the sidebar to see its articles.");
        };
      };
    };
  };
}

menu primary_menu {
  section {
    item {
      label: _("_Preferences");
      action: "app.preferences";
    }
    item {
      label: _("_Keyboard Shortcuts");
      action: "app.shortcuts";
    }
    item {
      label: _("_About Gazette");
      action: "app.about";
    }
  }
}

The window is bigger by default — 1000x700 instead of 800x600 — to give two panes room to breathe. Adw.NavigationSplitView replaces the single Adw.ToolbarView, with a sidebar and a content, each holding an Adw.NavigationPage. Each pane gets its own Adw.ToolbarView and Adw.HeaderBar — the libadwaita pattern is that every pane owns its own chrome, so when the layout collapses on narrow screens each one has a working header bar with title and back button. The sidebar's ListBox carries the navigation-sidebar style class for the standard look; the content pane shows an Adw.StatusPage empty state using rss-symbolic from adwaita-icon-theme. The hamburger menu has moved to the content pane's header bar — that's where it lives in most GNOME apps with this layout (Files, Music, Lollypop, Apostrophe).

The bit that catches people: Adw.NavigationSplitView doesn't collapse on its own. Drop the window narrower without an Adw.Breakpoint and it just stays side-by-side, ignoring you. The breakpoint is what flips split_view.collapsed to true when the window narrows below 600 scaled pixels — adaptive behaviour is a property you set, not something the widget figures out. The sp unit (scaled pixels) means the threshold respects the user's text scaling factor, so the layout collapses at the same effective width regardless of how big they've made their fonts.

Hit Run again.

The hamburger menu wires up unchanged — same app.shortcuts, app.about, and (still unimplemented) app.preferences actions Builder generated in Part 3:

And dragging the window narrower trips the breakpoint, collapsing the split view to single-pane navigation:

The Rust side

Open src/window.rs. Right now it has one TemplateChild for the label we just deleted:

#[derive(Debug, Default, gtk::CompositeTemplate)]
#[template(resource = "/io/github/fromthearchitect/gazette/window.ui")]
pub struct GazetteWindow {
    #[template_child]
    pub label: TemplateChild<gtk::Label>,
}

Two things to update. First, the label field doesn't refer to anything any more — there's no Label label in the new window.blp. Second, we want typed handles to the new widgets so future posts can react to them.

Replace the struct with:

#[derive(Debug, Default, gtk::CompositeTemplate)]
#[template(resource = "/io/github/fromthearchitect/gazette/window.ui")]
pub struct GazetteWindow {
    #[template_child]
    pub split_view: TemplateChild<adw::NavigationSplitView>,
    #[template_child]
    pub feed_list: TemplateChild<gtk::ListBox>,
    #[template_child]
    pub placeholder: TemplateChild<adw::StatusPage>,
}

Note that the #[template(resource = ...)] path is unchanged. We didn't rename the resource path when we switched to Blueprint — window.ui is still what gets bundled into the gresource at /io/github/fromthearchitect/gazette/window.ui, it's just generated from window.blp now. Keeping the resource path stable is what lets the rest of the code be oblivious to the source format change.

Build and run. Same window, three new typed handles available for when we need them.

Sharp edges

Editor support

The official Blueprint compiler ships an LSP server. In GNOME Builder, support is built in — you get syntax highlighting, completion, and inline error markers automatically. In VS Code, install the Blueprint extension. In Neovim, configure nvim-lspconfig with blueprint_ls. The LSP knows about every property and signal of every widget — if you mistype defautl-width, you'll see the squiggle before you save.

Error message lineage

When Blueprint fails to compile, the error references your .blp file with helpful line and column numbers. When GTK fails to load a .ui template at runtime — usually because you referenced a widget that doesn't exist, or the parent doesn't match the Rust ParentType — the error references the generated .ui file. The line numbers won't match your .blp. That's fine, the structure does, but it catches everyone the first time.

Blueprint can't express everything

Blueprint covers the GTK Builder XML format completely, but a handful of edge cases require dropping back to either raw XML or runtime Rust code. The most common one I hit is custom GtkBuilder-loaded scriptable types where a property takes a complex serialised value. If you need it, you can mix .ui and .blp files in the same gresource — just list the .ui ones in the gazette.gresource.xml manifest and skip them in the Blueprint custom target.

Don't commit the generated `.ui` files

The build directory holds the generated XML. Builder's default .gitignore already excludes _build/, but if you set up a different build layout, double-check. Committing generated .ui files leads to merge conflicts every time someone tweaks a .blp.

What we have so far

A window.blp and shortcuts-dialog.blp instead of XML. A working sidebar + content layout that's adaptive on small screens. Three typed widget handles in Rust waiting for behaviour. The same single-instance app, the same gresource path, the same menu, the same translations — but the file you actually edit when you want to change the UI now reads like a tree, not a tag soup.

What comes next

We have widgets. We don't have any logic. Clicking a row in the sidebar does nothing. Adding a feed isn't possible. There's no state.

Part 5 is App Architecture Patterns — how to organise mutable state in a Rust GTK app without losing your mind. The big shape of it: GTK widgets aren't Send, Rc<RefCell<T>> is everywhere, the clone! macro keeps closures sane, and async work lives on Tokio while UI work lives on the GLib main loop. We'll set up the two-executor pattern and use it to wire the sidebar selection to the content pane via a real GObject signal.

That's the post where the patterns from Part 2 stop being theoretical.

The source code at the end of this post lives on the part-4 branch of fromthearchitect/gnome-rust-gazette.

Building GNOME Apps with Rust, Bonus: The Stack Underneath

Justin - FromTheArchitect — Fri, 08 May 2026 13:06:41 +0000

This is a bonus post in the series taking a GNOME app from an empty directory to GNOME Circle. It sits between Part 3 and Part 4 — read it if you want context, skip it if you want code.

By the end of Part 3 you had a running GTK 4 + libadwaita app with five trait implementations, a mod imp block, an adw::Application parent class, a meson.build next to your Cargo.toml, and a Flatpak manifest pinning a runtime version. None of those decisions arrived in 2026 fully formed. Each is a fossil of a specific argument that took years to settle.

This is the short version of those arguments. The platform you're writing against is shaped by five fights — over licence, components, design, toolkit independence, and distribution — and once you've heard the fights, the conventions stop feeling arbitrary.

1. The licence fight (1996–2000)

In 1996 the dominant Unix GUI toolkit was Motif, owned by the Open Software Foundation and proprietary in a way that mattered: you couldn't ship free software against it without commercial licensing. Spencer Kimball and Peter Mattis, two Berkeley undergrads writing the GIMP paint program, wrote their own toolkit instead and called it the GIMP Toolkit — GTK. Within a few years the toolkit had outgrown the paint program. It is now what most of the free desktop is built on.

The same year, Trolltech released Qt 1.0 and Matthias Ettrich announced KDE on top of it. Qt was technically excellent, but its licence wasn't one the Free Software Foundation recognised until 2000. Between 1996 and 2000, a substantial part of the GNU community considered KDE non-free regardless of source availability.

In August 1997, Miguel de Icaza and Federico Mena announced GNOME — explicitly framed as a free-software desktop that didn't depend on Qt. The technical justifications (component model, accessibility, language bindings) were in the announcement; the political one — you should not have to choose between a working desktop and a free-software stack — is what gave the project momentum. Qt was relicensed under the GPL in 2000 and the original objection mostly evaporated, but by then GNOME existed, had momentum, and had a 1.0 release on the way. The schism was permanent.

The through-line to your code: GNOME's founding pressure was licence purity, not technical superiority. Builder defaults to GPL-3.0-or-later when it scaffolds a project. Flathub's review process flags proprietary dependencies. Publishing through Flatpak rather than as a closed binary is implicit in every tutorial you'll read. None of this is convention; it's the residue of an argument from 1996.

2. The component dream that didn't pan out (1999–2008)

GNOME 1.0 shipped in 1999 against GTK+ 1.2. The project's name was the GNU Network Object Model Environment, and the network object model part was load-bearing. GNOME wasn't supposed to be a window manager and a panel. It was supposed to be a full component architecture: applications built out of embeddable, scriptable, network-transparent objects living inside each other's windows. The technology underneath was CORBA, and GNOME shipped its own implementation (ORBit) plus a higher-level component framework (Bonobo). The dream was that you'd embed a GNumeric spreadsheet inside an AbiWord document and edit it in place.

This wasn't a GNOME-specific bet. The whole industry was on it: Microsoft's COM and OLE, Sun's Java RMI, a decade of conference talks predicting that desktop apps would be rebuilt as orchestrations of small composable objects messaging each other. It didn't pan out. Components-via-IPC was the wrong abstraction at the application layer, and the lesson got learned the expensive way by everyone who'd bet on it.

The technology survived in a different shape. GLib 2.0 had shipped in 2002, and one of its contributions was to formalise GObject as a standalone type system — separable from GTK, and from the Bonobo component dream above it. That is the type system you're working against in Part 2's Feed and Part 3's GazetteWindow. The shape of it — inner/outer split, vtables, manual reference counting, registration macros — is a 1990s C solution to the object-oriented programming problem. It feels strange in Rust because it predates Rust by fifteen years. D-Bus survived for the same reason: deliberately small where CORBA was deliberately general, and it's how your single-instance behaviour works. GObject Introspection (2008) ships machine-readable type metadata alongside every GObject library, and it's the only reason the Rust bindings can be auto-generated and stay current.

A lot of GNOME's strangeness in 2026 is the residue of a 1990s bet that didn't pay off. The bet itself is gone. The infrastructure built to support it survived, got refactored, and is now the foundation everything else stands on.

3. The GNOME 3 reset (2011)

GNOME 2 had been the standard Linux desktop for a decade by 2010 — a panel, a menu, a taskbar, icons on the desktop. Boring, in the best sense.

April 2011 broke that. GNOME 3.0 shipped with a complete reset of the user-visible desktop: a full-screen Activities overview, dynamic workspaces, no taskbar, no minimise button, no system tray, no desktop icons. The argument from the design team was that those affordances were artefacts of a 1990s desktop that no longer matched how people actually used computers. The revolt was real and loud — whole distributions refused to ship it, two forks (MATE preserving GNOME 2 verbatim, Cinnamon fixing the new shell) emerged within a year, and Linus Torvalds publicly switched to Xfce.

Here's the part that's harder to write in 2026 than in 2012: the design has aged well. The Activities overview, dynamic workspaces, the deliberate absence of customisation knobs, the bias toward defending users from a thousand small decisions — these were unpopular in 2011 because they were unfamiliar. macOS, Windows 11, ChromeOS, every mobile OS — all the design idioms now look more like GNOME 3 than they look like GNOME 2.

Every libadwaita widget you reach for is a descendant of that design ethos. Adw.ApplicationWindow instead of Gtk.Window, Adw.ToolbarView containing the header bar, the absence of a system-tray API, the deliberately limited theming surface — these aren't arbitrary library decisions. They are the same opinionated-design argument from 2011, restated as code. Building Gazette to libadwaita conventions is, structurally, accepting GNOME 3's premise. Fifteen years on, the premise has stopped being controversial.

4. GTK 4 and the libadwaita split (2020–2021)

GTK 4.0 shipped in December 2020 after roughly four years of development. The whole rendering pipeline had been rewritten — widgets emit declarative render nodes that GSK (the new GTK Scene Kit) compiles into GPU-accelerated draw operations. That's why your Flatpak manifest from Part 3 has --device=dri even though you're shipping an RSS reader. It's not for graphics; it's because GSK exists, and GSK wants the GPU.

The other GTK 4 change is harder to see but more consequential. The toolkit was deliberately positioned this time not to be the GNOME-only library any more. GTK 3 had dragged the GNOME aesthetic along with it wherever it went. GTK 4 strips the GNOME-specific visual identity out and leaves a place where it can be added back, optionally, as a separate library.

That library is libadwaita, first released in December 2021. Its release announcement put the bargain plainly: GTK should grow independently of GNOME at its own pace; other GTK consumers — Inkscape, elementary OS — should be first-class citizens rather than second-class baggage; libadwaita itself should be another library you can choose to link against if you want to make your application fit well into GNOME. The Adwaita stylesheet — GTK 3's default look — moved out of GTK into libadwaita, and GTK 4 kept a renamed neutral copy.

Each adw:: import in application.rs and window.rs is a deliberate vote to be a GNOME app rather than a generic GTK one. Replace every adw:: symbol with its gtk:: equivalent and Gazette would still compile, still run, and still display a working window. It would just stop being a GNOME application. The line between the two is exactly the line GTK and libadwaita's architects drew in 2020 and 2021, restated in your use statements.

5. Flatpak and the runtime model (2015–)

Before Flatpak, a GNOME application's distribution problem was N × M × K. Forty-odd Linux distributions, each shipping a different GTK version, each on a different cadence, often two GNOME releases behind. When a user reported a bug you'd fixed eighteen months earlier, the answer was almost always which distro, which version, please file a bug with them. That isn't a release model. It's an apology.

Flatpak (originally xdg-app, started 2015 by Alex Larsson at Red Hat) ignores the host distribution's library versions entirely. Bundle the application with the runtime it expects, run it in a sandbox via bubblewrap, mediate everything else through portals. If your app needs org.gnome.Platform 50, Flatpak ships it alongside your app and the user's Debian or Fedora version is no longer your problem.

The runtime/SDK distinction in Part 3 is the literal embodiment of this model. org.gnome.Platform is what users get; org.gnome.Sdk is what you build against. Updating your manifest from "runtime-version": "48" to "50" isn't a build-system quirk. It's the act of saying I have tested this app against GNOME 50, here is what I'm shipping. The Flatpak manifest pinning a version, the --socket=wayland line, the --device=dri line — every one of those is a public commitment to a specific platform contract.

So

Each shape in your Part 3 project has a date and a reason now. The five trait implementations: GObject, formalised in 2002 because the 1990s component dream needed a separable type system. The mod imp block: that same 1990s C inheritance pattern restated as a Rust idiom. The adw::Application parent class: the 2020–2021 split between a deliberately neutral GTK 4 and a deliberately opinionated libadwaita, drawn in use statements. The meson.build next to Cargo.toml: the 2017–2019 migration that replaced autotools across the project. The Flatpak manifest: the 2015-onward distribution model that made same app, all distributions a viable promise.

History over. Part 4 is where the code resumes.

Building GNOME Apps with Rust, Part 3: Your First App

Justin - FromTheArchitect — Mon, 04 May 2026 13:43:25 +0000

This is Part 3 of a series that takes a GNOME application from an empty directory to acceptance into GNOME Circle. Part 2 covered GObject's type system — properties, signals, and the inner/outer type pattern. Now we'll use everything we learned to build a real application.

From theory to a running window

In Part 2 we built a GObject subclass by hand — a Feed model with properties and signals, no GTK in sight. That was deliberate. Understanding GObject's inner/outer type split, the ObjectSubclass trait, and the mod imp pattern is the foundation that everything else rests on.

Now we're going to see those same patterns in context. By the end of this post, you'll have a running GTK4 + libadwaita application with a header bar, a menu, keyboard shortcuts, and a properly structured project that's ready for Flatpak packaging. And you won't have written most of it by hand — GNOME Builder will generate it for you. Our job is to understand what it generated and why.

Creating the project in GNOME Builder

Open GNOME Builder and click Create New Project. Fill in the dialog like this:

Project Name: gazette
Application ID: io.github.fromthearchitect.gazette
Location: wherever you keep your projects
Language: Rust
License: GPL-3.0-or-later
Version Control: enabled
Template: GNOME Application

Click Create Project.

A note on application IDs

The application ID is a reverse domain name that uniquely identifies your app across the entire Linux desktop. It's used for the D-Bus service name, the GSettings schema path, the desktop file name, the icon name, and the Flatpak bundle ID. Everything keys off this single string.

The convention is to use a domain you control. If you're publishing to a GitHub organisation, io.github.yourorg.yourapp is the standard pattern. If you own a domain, use it: dev.fromthearchitect.gazette would also work. The important thing is that this ID is globally unique and stable — changing it later means renaming dozens of files and updating every reference.

Hit Run

Before we look at any code, hit the Run button (the play icon in the header bar) or press Ctrl+F5. Builder will configure the Flatpak environment, download the SDK if needed, compile the Rust code, bundle the resources, and launch the application.

The first build takes a while — Cargo is downloading and compiling every dependency inside the Flatpak sandbox. Subsequent builds are much faster thanks to caching.

When it finishes, you'll see this:

A window. A header bar with a title. A hamburger menu with Preferences, Keyboard Shortcuts, and About entries. A "Hello, World!" label in the centre. That's your application.

It doesn't look like much yet, but there's a surprising amount happening behind the scenes. Let's look at what Builder actually created.

The project structure

Here's what Builder generated:

gazette/
├── Cargo.toml
├── COPYING
├── meson.build
├── io.github.fromthearchitect.gazette.json
├── data/
│   ├── meson.build
│   ├── icons/
│   │   ├── meson.build
│   │   ├── hicolor/scalable/apps/
│   │   │   └── io.github.fromthearchitect.gazette.svg
│   │   └── hicolor/symbolic/apps/
│   │       └── io.github.fromthearchitect.gazette-symbolic.svg
│   ├── io.github.fromthearchitect.gazette.desktop.in
│   ├── io.github.fromthearchitect.gazette.gschema.xml
│   ├── io.github.fromthearchitect.gazette.metainfo.xml.in
│   └── io.github.fromthearchitect.gazette.service.in
├── po/
│   ├── LINGUAS
│   ├── POTFILES.in
│   └── meson.build
└── src/
    ├── meson.build
    ├── main.rs
    ├── application.rs
    ├── config.rs.in
    ├── window.rs
    ├── window.ui
    ├── shortcuts-dialog.ui
    └── gazette.gresource.xml

That's a lot of files for "Hello, World!" — and every single one of them is there for a reason. Here's what's in each group.

The Rust source code

main.rs — the entry point

mod application;
mod config;
mod window;

use self::application::GazetteApplication;
use self::window::GazetteWindow;

use config::{GETTEXT_PACKAGE, LOCALEDIR, PKGDATADIR};
use gettextrs::{bind_textdomain_codeset, bindtextdomain, textdomain};
use gtk::{gio, glib};
use gtk::prelude::*;

fn main() -> glib::ExitCode {
    // Set up gettext translations
    bindtextdomain(GETTEXT_PACKAGE, LOCALEDIR)
        .expect("Unable to bind the text domain");
    bind_textdomain_codeset(GETTEXT_PACKAGE, "UTF-8")
        .expect("Unable to set the text domain encoding");
    textdomain(GETTEXT_PACKAGE)
        .expect("Unable to switch to the text domain");

    // Load resources
    let resources = gio::Resource::load(
        PKGDATADIR.to_owned() + "/gazette.gresource"
    ).expect("Could not load resources");
    gio::resources_register(&resources);

    let app = GazetteApplication::new(
        "io.github.fromthearchitect.gazette",
        &gio::ApplicationFlags::empty(),
    );

    app.run()
}

Three things happen here before the application starts:

Gettext initialisation. This wires up the translation system so that strings marked as translatable in the UI files and source code can be looked up in the user's language. Even if you never translate your app, the plumbing needs to be in place.
Resource loading. The compiled GResource bundle (containing the UI templates, icons, and other assets) is loaded from disk and registered globally. After this call, any code can access bundled files by their resource path — for example, /io/github/fromthearchitect/gazette/window.ui.
Application creation and run. GazetteApplication::new() creates our application object, and app.run() hands control to the GLib main loop. The main loop processes events — user input, window management, D-Bus messages — until the application quits.

The config module isn't a regular Rust file — it's generated at build time by Meson from a template. More on that shortly.

application.rs — the GtkApplication subclass

This is where you'll recognise the GObject patterns from Part 2:

use gettextrs::gettext;
use adw::prelude::*;
use adw::subclass::prelude::*;
use gtk::{gio, glib};

use crate::config::VERSION;
use crate::GazetteWindow;

mod imp {
    use super::*;

    #[derive(Debug, Default)]
    pub struct GazetteApplication {}

    #[glib::object_subclass]
    impl ObjectSubclass for GazetteApplication {
        const NAME: &'static str = "GazetteApplication";
        type Type = super::GazetteApplication;
        type ParentType = adw::Application;
    }

    impl ObjectImpl for GazetteApplication {
        fn constructed(&self) {
            self.parent_constructed();
            let obj = self.obj();
            obj.setup_gactions();
            obj.set_accels_for_action("app.quit", &["<control>q"]);
        }
    }

    impl ApplicationImpl for GazetteApplication {
        fn activate(&self) {
            let application = self.obj();
            let window = application.active_window().unwrap_or_else(|| {
                let window = GazetteWindow::new(&*application);
                window.upcast()
            });
            window.present();
        }
    }

    impl GtkApplicationImpl for GazetteApplication {}
    impl AdwApplicationImpl for GazetteApplication {}
}

glib::wrapper! {
    pub struct GazetteApplication(ObjectSubclass<imp::GazetteApplication>)
        @extends gio::Application, gtk::Application, adw::Application,
        @implements gio::ActionGroup, gio::ActionMap;
}

Same pattern as Part 2's Feed: an inner type in mod imp that holds the state, ObjectSubclass to register it with GObject, and a glib::wrapper! macro to create the outer type. The difference is what we're subclassing — adw::Application instead of glib::Object — and the trait implementations that come with it.

ObjectImpl::constructed is called once when the application is first created. It's the place to set up actions and keyboard shortcuts. This is analogous to a constructor, but in GObject-land, construction happens in phases — constructed runs after all properties have been set.

ApplicationImpl::activate is the most important callback. It's called when the application is launched (or when the user tries to open a second instance). The pattern here is standard: check if there's already a window, create one if there isn't, and present it. This is how GNOME apps implement single-instance behaviour — the platform enforces one running instance per application ID, and subsequent launches just activate the existing one.

The impl GtkApplicationImpl and impl AdwApplicationImpl lines are empty but required. They tell the GObject type system that we're implementing the full trait chain from gio::Application through gtk::Application to adw::Application. If you leave one out, you'll get a compile error.

Further down in the file, there's the actions setup and the About dialog:

impl GazetteApplication {
    pub fn new(application_id: &str, flags: &gio::ApplicationFlags) -> Self {
        glib::Object::builder()
            .property("application-id", application_id)
            .property("flags", flags)
            .property("resource-base-path",
                       "/io/github/fromthearchitect/gazette")
            .build()
    }

    fn setup_gactions(&self) {
        let quit_action = gio::ActionEntry::builder("quit")
            .activate(move |app: &Self, _, _| app.quit())
            .build();
        let about_action = gio::ActionEntry::builder("about")
            .activate(move |app: &Self, _, _| app.show_about())
            .build();
        self.add_action_entries([quit_action, about_action]);
    }

    fn show_about(&self) {
        let window = self.active_window().unwrap();
        let about = adw::AboutDialog::builder()
            .application_name("Gazette")
            .application_icon("io.github.fromthearchitect.gazette")
            .developer_name("Unknown")
            .version(VERSION)
            .developers(vec!["Unknown"])
            .translator_credits(&gettext("translator-credits"))
            .copyright("© 2026 Unknown")
            .build();

        about.present(Some(&window));
    }
}

Notice the placeholder values — developer_name("Unknown"), developers(vec!["Unknown"]), copyright("© 2026 Unknown"). Builder generates these as placeholders. Replace them with your actual name before publishing your app.

GActions are GNOME's action system. Instead of connecting button clicks directly to functions, you define named actions (app.quit, app.about) and connect UI elements to those names. The menu items in the UI template reference app.about — the action system routes that to show_about(). This decoupling means you can trigger the same action from a menu, a keyboard shortcut, a command-line argument, or a D-Bus message.

The resource-base-path property tells the application where to look for automatically loaded resources. When we set it to /io/github/fromthearchitect/gazette, the application will automatically load the shortcuts dialog from that path without us doing anything extra.

window.rs — the application window

use gtk::prelude::*;
use adw::subclass::prelude::*;
use gtk::{gio, glib};

mod imp {
    use super::*;

    #[derive(Debug, Default, gtk::CompositeTemplate)]
    #[template(resource = "/io/github/fromthearchitect/gazette/window.ui")]
    pub struct GazetteWindow {
        #[template_child]
        pub label: TemplateChild<gtk::Label>,
    }

    #[glib::object_subclass]
    impl ObjectSubclass for GazetteWindow {
        const NAME: &'static str = "GazetteWindow";
        type Type = super::GazetteWindow;
        type ParentType = adw::ApplicationWindow;

        fn class_init(klass: &mut Self::Class) {
            klass.bind_template();
        }

        fn instance_init(obj: &glib::subclass::InitializingObject<Self>) {
            obj.init_template();
        }
    }

    impl ObjectImpl for GazetteWindow {}
    impl WidgetImpl for GazetteWindow {}
    impl WindowImpl for GazetteWindow {}
    impl ApplicationWindowImpl for GazetteWindow {}
    impl AdwApplicationWindowImpl for GazetteWindow {}
}

glib::wrapper! {
    pub struct GazetteWindow(ObjectSubclass<imp::GazetteWindow>)
        @extends gtk::Widget, gtk::Window, gtk::ApplicationWindow,
                 adw::ApplicationWindow,
        @implements gio::ActionGroup, gio::ActionMap;
}

impl GazetteWindow {
    pub fn new<P: IsA<gtk::Application>>(application: &P) -> Self {
        glib::Object::builder()
            .property("application", application)
            .build()
    }
}

The @implements list above is truncated for readability — the actual generated code also includes gtk::Accessible, gtk::Buildable, gtk::ConstraintTarget, gtk::Native, gtk::Root, gtk::ShortcutManager. See the source on the part-3 branch for the full version.

This introduces two new concepts: composite templates and the widget trait chain.

#[derive(gtk::CompositeTemplate)] connects this Rust struct to a UI definition file. The #[template(resource = "...")] attribute tells GTK where to find the template, and #[template_child] fields create typed references to named widgets in that template. Here, self.label gives us direct access to the GtkLabel widget with id="label" defined in the UI file.

The class_init and instance_init functions bind the template at the class level (once) and initialise it for each instance. This is boilerplate that every composite template widget needs.

The trait chain — WidgetImpl, WindowImpl, ApplicationWindowImpl, AdwApplicationWindowImpl — reflects the GTK class hierarchy. AdwApplicationWindow extends gtk::ApplicationWindow, which extends gtk::Window, which extends gtk::Widget. Each level of the hierarchy can override behaviour. For now, all these implementations are empty, but they must be present.

The UI template

window.ui

<?xml version="1.0" encoding="UTF-8"?>
<interface>
  <requires lib="gtk" version="4.0"/>
  <requires lib="Adw" version="1.0"/>
  <template class="GazetteWindow" parent="AdwApplicationWindow">
    <property name="title" translatable="yes">Gazette</property>
    <property name="default-width">800</property>
    <property name="default-height">600</property>
    <property name="content">
      <object class="AdwToolbarView">
        <child type="top">
          <object class="AdwHeaderBar">
            <child type="end">
              <object class="GtkMenuButton">
                <property name="primary">True</property>
                <property name="icon-name">open-menu-symbolic</property>
                <property name="tooltip-text"
                          translatable="yes">Main Menu</property>
                <property name="menu-model">primary_menu</property>
              </object>
            </child>
          </object>
        </child>
        <property name="content">
          <object class="GtkLabel" id="label">
            <property name="label"
                      translatable="yes">Hello, World!</property>
            <style>
              <class name="title-1"/>
            </style>
          </object>
        </property>
      </object>
    </property>
  </template>
  <menu id="primary_menu">
    <section>
      <item>
        <attribute name="label"
                   translatable="yes">_Preferences</attribute>
        <attribute name="action">app.preferences</attribute>
      </item>
      <item>
        <attribute name="label"
                   translatable="yes">_Keyboard Shortcuts</attribute>
        <attribute name="action">app.shortcuts</attribute>
      </item>
      <item>
        <attribute name="label"
                   translatable="yes">_About Gazette</attribute>
        <attribute name="action">app.about</attribute>
      </item>
    </section>
  </menu>
</interface>

This is GTK's XML-based UI definition format.

The <template> element defines a composite template — it's bound to the GazetteWindow class we defined in Rust. The parent attribute must match the ParentType in our ObjectSubclass implementation.

The widget hierarchy is:

AdwToolbarView — a libadwaita container that manages header bars and content areas
- AdwHeaderBar (top) — the standard GNOME header bar with the window title and controls
- GtkMenuButton — the hamburger menu button in the top-right corner
- GtkLabel (content) — our "Hello, World!" text

The <menu> element defines the hamburger menu model. Each item has a label (the _ prefix marks the keyboard accelerator character) and an action name. The app.about entry maps back to the action we defined in application.rs. The app.preferences action isn't connected yet — clicking it does nothing. The app.shortcuts action, however, already works: GTK automatically loads shortcuts-dialog.ui from the resource base path we set in application.rs. We'll wire up preferences in a later post.

The translatable="yes" attribute on strings marks them for extraction by gettext. Even if you don't plan to translate your app initially, marking strings as translatable from the start saves you from a painful retrofit later.

In Part 4, we'll convert this XML template to Blueprint, which is dramatically more readable. But it's worth understanding the XML format first, since Blueprint compiles to it — and when things go wrong, the error messages reference XML structures.

The build system

GNOME apps don't use Cargo as the top-level build system. They use Meson. Cargo still compiles the Rust code, but Meson orchestrates everything else — and there's a lot of "everything else" in a GNOME app.

Root meson.build

project('gazette', 'rust',
          version: '0.1.0',
    meson_version: '>= 1.0.0',
  default_options: [ 'warning_level=2', 'werror=false', ],
)

i18n = import('i18n')
gnome = import('gnome')

subdir('data')
subdir('src')
subdir('po')

gnome.post_install(
     glib_compile_schemas: true,
    gtk_update_icon_cache: true,
  update_desktop_database: true,
)

The root build file declares the project, imports the i18n and gnome Meson modules, and includes three subdirectories. The post_install block runs after installation to compile GSettings schemas, update the icon cache, and refresh the desktop file database. These are standard GNOME post-install steps — without them, your app's icon won't appear in the application launcher and your settings won't be accessible.

src/meson.build — where Rust meets Meson

pkgdatadir = get_option('prefix') / get_option('datadir') / meson.project_name()
gnome = import('gnome')

gnome.compile_resources('gazette',
  'gazette.gresource.xml',
  gresource_bundle: true,
  install: true,
  install_dir: pkgdatadir,
)

conf = configuration_data()
conf.set_quoted('VERSION', meson.project_version())
conf.set_quoted('GETTEXT_PACKAGE', 'gazette')
conf.set_quoted('LOCALEDIR', get_option('prefix') / get_option('localedir'))
conf.set_quoted('PKGDATADIR', pkgdatadir)

configure_file(
    input: 'config.rs.in',
    output: 'config.rs',
    configuration: conf
)

Here's what it handles:

Compiles GResources. The gazette.gresource.xml manifest lists the UI files and other assets that should be bundled. Meson compiles them into a single binary blob (gazette.gresource) and installs it alongside the binary.
Generates config.rs. The config.rs.in template contains placeholders like @VERSION@ and @PKGDATADIR@. Meson replaces them with real values at build time. This is how the Rust code knows where to find its installed resources — the paths are baked in at compile time.
Invokes Cargo. Further down in the file, Meson runs cargo build with the right flags and copies the resulting binary to the install location.

gazette.gresource.xml

<?xml version="1.0" encoding="UTF-8"?>
<gresources>
  <gresource prefix="/io/github/fromthearchitect/gazette">
    <file preprocess="xml-stripblanks">window.ui</file>
    <file preprocess="xml-stripblanks">shortcuts-dialog.ui</file>
  </gresource>
</gresources>

This manifest lists every file that should be compiled into the GResource bundle. The prefix attribute defines the virtual path — when our window template asks for /io/github/fromthearchitect/gazette/window.ui, it's loading from this bundle, not from the filesystem. The xml-stripblanks flag tells Meson to strip whitespace from the XML before bundling. It makes no real difference for an app this size, but it's standard practice and every GNOME app does it.

Whenever you add a new UI file, icon, or CSS stylesheet, it needs to be listed here.

Desktop integration files

The data/ directory contains files that integrate your application with the Linux desktop. None of these are specific to GNOME or GTK — they're freedesktop.org standards used across all Linux desktop environments.

Desktop file

[Desktop Entry]
Name=Gazette
Exec=gazette
Icon=io.github.fromthearchitect.gazette
Terminal=false
Type=Application
Categories=Utility;
Keywords=GTK;
StartupNotify=true
DBusActivatable=true

This tells the desktop environment how to launch your app, what icon to display, and what category to put it in. The .in suffix on the source file means Meson processes it through gettext to produce translated versions.

DBusActivatable=true means the app can be launched via D-Bus, which enables the single-instance behaviour we saw in application.rs.

GSettings schema

<schemalist gettext-domain="gazette">
  <schema id="io.github.fromthearchitect.gazette"
          path="/io/github/fromthearchitect/gazette/">
  </schema>
</schemalist>

GSettings is GNOME's configuration system — think of it as a typed key-value store for application preferences. The schema is empty now, but when we add user preferences (feed refresh interval, dark mode preference, etc.), this is where we'll define them.

AppStream metadata

The metainfo file is what Flathub and GNOME Software actually read when they display your app. Get it wrong and your app looks abandoned regardless of how polished the code is. Builder generated a placeholder — we'll fill it in properly when we prepare for Flathub submission in Part 9.

D-Bus service file

[D-BUS Service]
Name=io.github.fromthearchitect.gazette
Exec=@bindir@/gazette --gapplication-service

This tells D-Bus how to activate your application on demand. The @bindir@ placeholder is replaced by Meson at build time with the actual installation path.

The Flatpak manifest

{
    "id" : "io.github.fromthearchitect.gazette",
    "runtime" : "org.gnome.Platform",
    "runtime-version" : "48",
    "sdk" : "org.gnome.Sdk",
    "sdk-extensions" : [
        "org.freedesktop.Sdk.Extension.rust-stable"
    ],
    "command" : "gazette",
    "finish-args" : [
        "--share=network",
        "--share=ipc",
        "--socket=fallback-x11",
        "--device=dri",
        "--socket=wayland"
    ],
    ...
}

This defines how to build and sandbox the application as a Flatpak. The key fields:

runtime and runtime-version: The GNOME platform libraries your app links against at runtime. Version 48 corresponds to GNOME 48.
sdk: The matching SDK used at build time, which includes header files and development tools.
sdk-extensions: Additional SDK components — here, the Rust toolchain.
finish-args: The sandbox permissions your app needs. Network access, Wayland display, GPU acceleration. Every permission you add here needs to be justified when you submit to Flathub. You might wonder why an RSS reader needs --device=dri — GTK4 uses GPU-accelerated rendering by default, so it's a legitimate permission for virtually any GTK4 app.

Upgrading to the GNOME 50 platform

Builder generated this project against GNOME 48 — that's what the current template targets. But in Part 1, we installed the GNOME 50 SDK. Let's upgrade the Rust crates and Flatpak runtime to match.

Three files need changes:

1. Cargo.toml — Rust crate versions

The generated Cargo.toml uses gtk4 0.9 and libadwaita 0.7:

[dependencies]
gettext-rs = { version = "0.7", features = ["gettext-system"] }
gtk = { version = "0.9", package = "gtk4", features = ["gnome_47"] }

[dependencies.adw]
package = "libadwaita"
version = "0.7"
features = ["v1_6"]

Update it to the latest versions:

[dependencies]
gettext-rs = { version = "0.7", features = ["gettext-system"] }
gtk = { version = "0.11", package = "gtk4", features = ["gnome_50"] }
adw = { version = "0.9", package = "libadwaita", features = ["v1_9"] }

The version numbers here are the Rust crate versions, not the GTK version. gtk4 crate 0.11 wraps GTK 4.18, and libadwaita crate 0.9 wraps libadwaita 1.9. The gnome_50 feature flag is a convenience flag that enables all the version-specific API features matching the GNOME 50 SDK — it saves you from having to figure out which individual v4_xx flags correspond to which GNOME release.

2. Flatpak manifest — runtime version

In io.github.fromthearchitect.gazette.json, update the runtime version:

{
    "runtime-version" : "50",
}

This tells Flatpak to use the GNOME 50 runtime and SDK when building and running your app.

3. Rebuild

Hit Run in Builder again. Builder will download the GNOME 50 SDK if it's not already installed, rebuild the project against the new dependencies, and launch the app. If everything compiles and runs — and it should, since we haven't used any version-specific APIs yet — you're on the latest platform.

This kind of version bump is something you'll do roughly every six months as GNOME releases new platform versions. Getting comfortable with it now means it's routine rather than stressful later.

What we have so far

The thing that takes longest to internalise when you start GNOME development is how much of this is not GTK. The desktop file, the D-Bus service, the AppStream metadata, GSettings — these are platform concerns, not application concerns. Builder stitches them all together, but you need to know what they are and why they exist, or you'll never debug a broken Flatpak submission.

The application ID is the load-bearing string across all of it. It ties the desktop file to the D-Bus service to the GSettings schema to the Flatpak bundle. Getting this scaffolding right by hand would take hours of cross-referencing documentation. Builder gives it to you in thirty seconds.

What comes next

We've got a running app, but the UI is still "Hello, World!". Before we start building the actual RSS reader interface, we need a better way to describe user interfaces than raw XML.

In Part 4, we'll introduce Blueprint — a markup language that compiles to GTK's UI XML but is dramatically more readable. We'll convert the generated window template to Blueprint, build the initial Gazette layout with a sidebar and content pane, and start making it look like a real application.

The source code at the end of this post lives on the part-3 branch of fromthearchitect/gnome-rust-gazette. Subsequent posts in this series build on the same repo, with a branch per part.

DEV Community: Justin - FromTheArchitect

Excavating Legacy ETL: The AI Never Asserts a Fact It Could Look Up

Why pointing an LLM at the XML doesn't work

The one rule the whole design hangs on

Layer one: facts

Layer two: the questions one file can't answer

Layer three: making "look it up" cheaper than guessing

Layer four: the part that actually needs judgement

Fixed templates, because consistency is a feature

The gate: assume the spec is wrong

What I'd tell someone starting this

Two YubiKeys, One Prompt Too Many

What was actually happening

The information was already there

The bit that was actually hard

Checking it actually works

What this does not fix

The general shape

Building GNOME Apps with Rust, Part 6: Fetching Feeds

The click that still does nothing real

The freeze

One main loop, nothing else runs until you give it back

Two executors, one job each

Standing up the second executor

Fetching, off the main thread

Crossing back

Feed remembers what it fetched

A consumer for items-updated

Sharp edges

What we have so far

What comes next

Moments: The Photo App I Built to Win an Argument

It started with a phone call

Picking a fight worth having

What it was actually like

The verdict

Meet Moments

The Flathub question

What I'd ask of you

Building GNOME Apps with Rust, Part 5: State and Signals

The click that goes nowhere

Feed, for real

A list bound to a model

Where state lives

Which cell?

Wiring selection, and the clone! macro

A custom signal on GazetteWindow

When Rc<RefCell<T>> isn't the answer

Binding the view to state

Sharp edges

Signal names aren't checked

connect_row_selected fires with None on deselection

Borrow panics inside signal handlers

Kebab-case at the GObject level, snake_case in Rust

What we have so far

What comes next

Four Ways the Outbox Bit Me

1. The pull-delete loop

2. Retry, backoff, and the death of multi-id rows

3. Identity across the round-trip

4. Reset semantics, or: what does the server mean by "start over"

What the four have in common

Why Open Source Doesn't Embrace AI

The conventional answer

The win-win argument

The RHEL problem

What Valve actually shows

Inspiration is not copying

What actually remains

The reframe

How My Library Code Has No Idea It Has a Sync Backend

The offline-first problem

The vocabulary

The trait

Two strategies, one of which is empty

My favourite test in this codebase

Dependency injection: sync as someone else's problem

The drain side

Adapting the pattern

Adding a third backend

Wiring selection, and the `clone!` macro

A custom signal on `GazetteWindow`

When `Rc<RefCell<T>>` isn't the answer

`connect_row_selected` fires with `None` on deselection

Is `blueprint-compiler` available?

Updating `src/meson.build`

`gazette.gresource.xml` is unchanged

Updating `POTFILES.in`

`window.blp`

`shortcuts-dialog.blp`

Don't commit the generated `.ui` files