<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Faizo — Writing</title>
  <subtitle>Engineering notes from building and running Discord apps.</subtitle>
  <link href="https://faizo.net/writing/feed.xml" rel="self" />
  <link href="https://faizo.net/writing/" />
  <id>https://faizo.net/writing/</id>
  <updated>2026-11-13T00:00:00Z</updated>
  <author><name>Faizo</name><uri>https://faizo.net/about/</uri></author>
  <entry>
    <title>Two moderators click Close at once: a compare-and-swap state machine in SQLite</title>
    <link href="https://faizo.net/writing/sqlite-compare-and-swap-state-machine/" />
    <id>https://faizo.net/writing/sqlite-compare-and-swap-state-machine/</id>
    <published>2026-11-13T00:00:00Z</published>
    <updated>2026-11-13T00:00:00Z</updated>
    <summary>How a Discord ticket bot stays correct under double clicks, stale buttons and restarts: every state change is one guarded UPDATE, and only the winner acts.</summary>
    <content type="html">&lt;p&gt;A support-ticket system for Discord sounds like the simplest kind of bot. A member presses a button, the bot creates a private channel, staff help, someone presses Close. The first version of mine was written that way: read the ticket, check its status, do the work.&lt;/p&gt;
&lt;p&gt;Real servers don't use it that politely. Two moderators press Close in the same second, and the channel can get two closing messages and two transcripts. A member double-clicks Open and can receive two tickets. Someone presses a Reopen button on a week-old message for a ticket that has since been deleted. A deploy restarts the service halfway through closing a ticket and can leave it with no buttons at all.&lt;/p&gt;
&lt;p&gt;Every one of those is the same bug. The code reads a status and then acts on it, and something changes in between. This article describes the rewrite that removed the gap.&lt;/p&gt;

&lt;h2 id=&quot;problem&quot;&gt;Why &quot;check, then act&quot; can't work here&lt;/h2&gt;
&lt;p&gt;Discord delivers each button click as a separate HTTP request. Two clicks arrive as two concurrent requests, handled by two tasks. Each one reads the ticket, sees &lt;code&gt;open&lt;/code&gt;, and proceeds to close it. No amount of care inside one handler helps, because each handler is correct on its own.&lt;/p&gt;
&lt;p&gt;A lock around the handler doesn't fix it either. A close takes several calls to Discord (post a message, change permissions, rename the channel, upload a transcript), which is seconds of work. Holding a lock across that makes every other click wait, and Discord requires an answer to an interaction within three seconds. A lock also disappears on restart, which is exactly when you need to know what was in progress.&lt;/p&gt;
&lt;p&gt;And buttons live forever. A message posted last month still has a working Close button on it. The state the button was drawn for and the state the ticket is in now can be completely different.&lt;/p&gt;

&lt;h2 id=&quot;cas&quot;&gt;One guarded write per transition&lt;/h2&gt;
&lt;p&gt;The fix is to make the database the only judge of whether a transition may happen, in a single statement:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-sql&quot;&gt;UPDATE tickets
   SET status = 'closing'
 WHERE id = ?1
   AND status = 'open';&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This is a compare-and-swap. The write only happens if the ticket is still in the state the caller believes it is in. SQLite runs one writer at a time, so of two simultaneous clicks exactly one statement changes a row. The handler then asks how many rows were changed:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-rust&quot;&gt;/// Move a ticket from one state to another. Returns false if it wasn't in from.
fn transition(&amp;amp;self, id: i64, from: Status, to: Status) -&amp;gt; rusqlite::Result&amp;lt;bool&amp;gt; {
    let changed = self.conn.execute(
        &amp;quot;UPDATE tickets SET status = ?3 WHERE id = ?1 AND status = ?2&amp;quot;,
        (id, from.as_str(), to.as_str()),
    )?;
    Ok(changed == 1)
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;Only the caller that gets true touches Discord.&lt;/strong&gt; The loser answers privately with &quot;this ticket is already being closed&quot; and does nothing else. There is no code path in the service that reads a status and then decides what to do to the ticket. That rule is the whole design, and it handles all three problems at once: the second moderator loses the swap, and so does the stale button, because a deleted ticket is not in the state its old button expects.&lt;/p&gt;

&lt;h2 id=&quot;states&quot;&gt;In-between states are real states&lt;/h2&gt;
&lt;p&gt;Because the work takes seconds, the state machine has states for &quot;work in progress&quot;:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;pending  → open → closing → closed
                  closing → locked → deleting → closed
                            locked → reopening → open&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;closing&lt;/code&gt;, &lt;code&gt;reopening&lt;/code&gt; and &lt;code&gt;deleting&lt;/code&gt; are claims. Winning the swap into one of them means &quot;this task now owns the ticket until it moves it on&quot;. Other clicks that arrive meanwhile fail their own swap, since no transition starts from a claimed state, and get the polite refusal.&lt;/p&gt;
&lt;p&gt;If the work fails partway (Discord returns an error, a permission is missing), the task swaps the ticket back to where it came from and tells the user why. The message distinguishes &quot;an admin needs to fix a permission&quot; from &quot;Discord was busy, try again&quot;, because the first never fixes itself and the second usually does.&lt;/p&gt;

&lt;h2 id=&quot;open&quot;&gt;Opening a ticket: reserve first&lt;/h2&gt;
&lt;p&gt;Opening is harder than closing, because there is no row to guard yet. The rules for opening are also richer: a member may have at most N open tickets, there may be a cooldown, and each ticket gets the next number in sequence.&lt;/p&gt;
&lt;p&gt;All of that happens in one &lt;code&gt;BEGIN IMMEDIATE&lt;/code&gt; transaction, which takes SQLite's write lock up front: check the member's open tickets against the limit, take the next ticket number, and insert a placeholder row in state &lt;code&gt;pending&lt;/code&gt;. Only after that commits does the bot start creating the channel. A double click runs the transaction twice, and the second run sees the first one's placeholder and is refused. That holds even on a server with no limit or cooldown configured, since the placeholder itself is the evidence.&lt;/p&gt;
&lt;p&gt;Two details keep reservations from causing their own problems. A failed open &lt;em&gt;deletes&lt;/em&gt; its placeholder instead of leaving a closed ticket behind, so a member isn't put on cooldown for a ticket they never got. And a placeholder older than five minutes is treated as abandoned.&lt;/p&gt;

&lt;h2 id=&quot;order&quot;&gt;Post the new buttons before removing the old ones&lt;/h2&gt;
&lt;p&gt;A review of the first rewrite caught an ordering mistake that the state machine alone doesn't prevent. To lock a ticket, the bot removes the &quot;Close&quot; controls and posts a banner with &quot;Reopen&quot; and &quot;Delete&quot;. My first version retired the old controls and then posted the new ones. If the second step failed, the ticket had no working buttons and nobody could do anything with it.&lt;/p&gt;
&lt;p&gt;The order is now always: post the new controls, then record the new state, then retire the old controls. If posting fails, the transition is rolled back and the old buttons are still there and still valid. At every moment the channel contains a set of buttons that matches the ticket's actual state.&lt;/p&gt;

&lt;h2 id=&quot;restart&quot;&gt;Surviving a restart&lt;/h2&gt;
&lt;p&gt;Deploys restart the service. A task that is halfway through closing a ticket when the process stops leaves the row in &lt;code&gt;closing&lt;/code&gt; forever, and since nothing transitions out of a claimed state, the ticket would be stuck.&lt;/p&gt;
&lt;p&gt;Two mechanisms handle this:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Drain on shutdown.&lt;/strong&gt; Long-running flows are spawned through a small task tracker. On a stop signal the service stops accepting requests and waits up to eight seconds for tracked tasks to finish, inside the ten seconds Docker allows before it kills the container. The web framework's own graceful shutdown doesn't wait for tasks you spawned yourself, so this has to be explicit.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Recover on startup.&lt;/strong&gt; Whatever was still in flight is put back to a resting state when the service boots: &lt;code&gt;pending&lt;/code&gt; reservations are dropped, &lt;code&gt;closing&lt;/code&gt; returns to &lt;code&gt;open&lt;/code&gt;, and &lt;code&gt;reopening&lt;/code&gt; and &lt;code&gt;deleting&lt;/code&gt; return to &lt;code&gt;locked&lt;/code&gt;. The rule for choosing the resting state follows from the previous section: go back to the state whose buttons are still on screen.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;tests&quot;&gt;Testing it&lt;/h2&gt;
&lt;p&gt;Unit tests on the store prove the swaps: two transitions from the same state, exactly one succeeds. That is necessary and nowhere near sufficient, because the bugs were in the flows around the swaps.&lt;/p&gt;
&lt;p&gt;So the main tests drive the real HTTP router with correctly signed interaction payloads, against a fake Discord API running in the same process. The fake is strict in the ways that matter: it refuses edits to an archived thread, and it refuses to lock a thread when the bot lacks the permission Discord requires for that. A flow that does its steps in the wrong order fails against the fake the same way it would fail against Discord, in a test instead of in someone's server. Any new flow gets its tests there first.&lt;/p&gt;

&lt;h2 id=&quot;summary&quot;&gt;Summary&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Never read a status and then act on it. Make the state change a single guarded &lt;code&gt;UPDATE … WHERE status = ?&lt;/code&gt; and check the affected-row count.&lt;/li&gt;
&lt;li&gt;Only the winner of the swap performs side effects. Everyone else gets a refusal.&lt;/li&gt;
&lt;li&gt;Give slow work its own claimed states, and roll back to the previous state on failure.&lt;/li&gt;
&lt;li&gt;To create something, reserve a placeholder row inside one write transaction first.&lt;/li&gt;
&lt;li&gt;Add the new controls before removing the old ones.&lt;/li&gt;
&lt;li&gt;On startup, return every claimed state to the resting state the user can still see.&lt;/li&gt;
&lt;/ul&gt;</content>
    <category term="Rust" />
    <category term="SQLite" />
    <category term="Discord API" />
  </entry>
  <entry>
    <title>ResizeObserver loop completed with undelivered notifications: the cause and the fix</title>
    <link href="https://faizo.net/writing/resizeobserver-loop-undelivered-notifications/" />
    <id>https://faizo.net/writing/resizeobserver-loop-undelivered-notifications/</id>
    <published>2026-11-13T00:00:00Z</published>
    <updated>2026-11-13T00:00:00Z</updated>
    <summary>What the ResizeObserver loop error means, why setting state inside the callback triggers it, and the one-frame deferral that stops it reaching your error handler.</summary>
    <content type="html">&lt;p&gt;My web app reports uncaught errors to a small endpoint, and anything that arrives there pages me. One of the first messages it ever sent was this:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ResizeObserver loop completed with undelivered notifications.&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Older versions of Chrome word the same condition as &lt;code&gt;ResizeObserver loop limit exceeded&lt;/code&gt;. Nothing on the page was broken. No user had seen anything wrong. But it had fired through &lt;code&gt;window.onerror&lt;/code&gt;, so it looked exactly like a crash. This article explains what the browser is actually telling you, which code pattern causes it, and how I stopped causing it instead of only muting it.&lt;/p&gt;

&lt;h2 id=&quot;what&quot;&gt;What the message means&lt;/h2&gt;
&lt;p&gt;A &lt;code&gt;ResizeObserver&lt;/code&gt; callback doesn't run at an arbitrary time. The browser delivers resize notifications at one specific point in each frame: after it has calculated layout and before it paints. That placement is what makes the API useful, because your callback sees final sizes and can still change things before the user sees the frame.&lt;/p&gt;
&lt;p&gt;It also creates an obvious problem. If your callback changes the page, layout has to run again, and that may resize more observed elements. The browser handles this with a loop: deliver notifications, lay out again, check for new size changes, deliver again. To guarantee the loop ends, each pass may only notify elements that sit &lt;em&gt;deeper&lt;/em&gt; in the DOM tree than the shallowest element notified in the previous pass. Changes can ripple downwards, but a callback can't keep re-triggering the element it was called for.&lt;/p&gt;
&lt;p&gt;When a pass ends and there are still size changes the browser isn't allowed to deliver, it gives up for this frame, postpones them to the next one, and dispatches an error event on the window with the message above. So the message means: &lt;strong&gt;a resize callback changed the size of something at the same depth or higher, in the same frame.&lt;/strong&gt; Usually that something is the observed element itself.&lt;/p&gt;
&lt;p&gt;The postponed notifications are not lost. They arrive one frame later. That is why the page keeps working, and why this &quot;error&quot; is closer to a warning. It is still worth fixing, for two reasons. The skipped pass means the user can see one frame of the wrong layout. And any error monitoring you run will count it as an uncaught exception.&lt;/p&gt;

&lt;h2 id=&quot;cause&quot;&gt;The pattern that causes it&lt;/h2&gt;
&lt;p&gt;In my case it was a toolbar that collapses its buttons as it gets narrower. The component observed its own width and stored it in state:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;useEffect(() =&amp;gt; {
  const observer = new ResizeObserver(([entry]) =&amp;gt; {
    setWidth(entry.contentRect.width); // re-renders inside the callback
  });
  observer.observe(barRef.current);
  return () =&amp;gt; observer.disconnect();
}, []);&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This looks harmless, and with many frameworks it is the first thing anyone writes. The trouble is what the state update does. In Preact (and in React, for updates flushed synchronously), setting state inside the callback can re-render the component and run its layout effects before the callback's delivery pass has finished. My toolbar's render then folded a button into an overflow menu, which changed the toolbar's content and so its size. The observed element was resized inside its own notification. The browser's next check found a new change on an element it was no longer allowed to notify in this frame, and the error fired.&lt;/p&gt;
&lt;p&gt;It never happened on every resize. It needed a resize that crossed one of the collapse thresholds, which is why it looked random in the reports.&lt;/p&gt;

&lt;h2 id=&quot;fix&quot;&gt;The fix: leave the frame before changing anything&lt;/h2&gt;
&lt;p&gt;The rule I now follow is simple: &lt;strong&gt;a ResizeObserver callback only records what it saw. It changes nothing until the next frame.&lt;/strong&gt; A &lt;code&gt;requestAnimationFrame&lt;/code&gt; hop is enough:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;function useElementWidth(ref) {
  const [width, setWidth] = useState(0);

  useEffect(() =&amp;gt; {
    let frame = 0;
    const observer = new ResizeObserver(([entry]) =&amp;gt; {
      const next = entry.contentRect.width;
      cancelAnimationFrame(frame);
      frame = requestAnimationFrame(() =&amp;gt; setWidth(next));
    });
    observer.observe(ref.current);
    return () =&amp;gt; {
      cancelAnimationFrame(frame);
      observer.disconnect();
    };
  }, [ref]);

  return width;
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The state update now happens at the start of the following frame, outside the delivery loop. If that render resizes the toolbar again, the observer simply reports it in that frame's own delivery pass, as a fresh notification. There is nothing left over for the browser to complain about.&lt;/p&gt;
&lt;p&gt;Three details matter:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Cancel the pending frame&lt;/strong&gt; when a newer notification arrives and when the component unmounts. Otherwise a late callback can set state on a component that is gone.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Keep the measurement in one hook.&lt;/strong&gt; Both of my toolbars use the same one, so nobody writes a new observer with a state update directly in the callback.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The cost is one frame of latency&lt;/strong&gt;, about 16 ms. For collapsing toolbar buttons nobody can see it. If you need the change to land in the same frame, write to the DOM directly inside the callback in a way that can't resize the observed element, such as changing a child that is absolutely positioned.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;not-fixes&quot;&gt;Things that look like fixes and aren't&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Wrapping the callback in try/catch.&lt;/strong&gt; Your callback doesn't throw. The browser raises the error itself after the loop, so there is nothing to catch.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Debouncing with a timer.&lt;/strong&gt; It works, but it adds visible lag and still needs the same cleanup. A single animation frame is the smallest delay that leaves the loop.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Only filtering the message in your error handler.&lt;/strong&gt; This hides your own layout feedback loops along with everyone else's. I do filter it (see below), but only after removing the cause from my own code.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;reporting&quot;&gt;Why I still drop it in error reporting&lt;/h2&gt;
&lt;p&gt;After the fix, the message still arrived now and then. Browser extensions and third-party scripts run ResizeObservers in the page too, and their loops raise the same window-level event, which my handler hears. The event carries a message and no useful stack, so there is nothing to tell me whose observer it was.&lt;/p&gt;
&lt;p&gt;So the reporter drops this exact message, and its older Chrome wording, before sending anything. I added the same rule to the server endpoint that receives the reports. That second copy is not redundant. The app is served from a service-worker cache, which means some visitors keep running an old bundle for weeks after I ship a fix. A filter that exists only in the newest client does nothing about reports from the old ones. I wrote more about that problem in &lt;a href=&quot;/writing/browser-extension-crash-reports/&quot;&gt;Your crash reporter is paging you for someone else's code&lt;/a&gt;.&lt;/p&gt;

&lt;h2 id=&quot;summary&quot;&gt;Summary&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;The message means a resize callback caused another resize the browser couldn't deliver in the same frame. Delivery is postponed, not lost.&lt;/li&gt;
&lt;li&gt;The usual cause is a state update inside the callback whose render changes the observed element's size.&lt;/li&gt;
&lt;li&gt;Record the size in the callback and apply it in &lt;code&gt;requestAnimationFrame&lt;/code&gt;. Cancel the frame on new notifications and on unmount.&lt;/li&gt;
&lt;li&gt;Filter the message in error reporting only after your own observers are clean, and filter it on the server too if old clients can linger.&lt;/li&gt;
&lt;/ul&gt;</content>
    <category term="JavaScript" />
    <category term="Web" />
    <category term="Front end" />
  </entry>
  <entry>
    <title>Why focus() silently failed for every reduced-motion user</title>
    <link href="https://faizo.net/writing/focus-fails-reduced-motion-visibility/" />
    <id>https://faizo.net/writing/focus-fails-reduced-motion-visibility/</id>
    <published>2026-11-13T00:00:00Z</published>
    <updated>2026-11-13T00:00:00Z</updated>
    <summary>A blanket prefers-reduced-motion rule made visibility a transition, so focus() on a just-revealed menu did nothing and keyboards couldn't open any menu.</summary>
    <content type="html">&lt;p&gt;For a long time, keyboard users of my app who had &quot;reduce motion&quot; switched on in their operating system could not use a single dropdown menu. They could open one with Enter. The arrow keys then did nothing, because focus never moved into the menu. Nothing was logged, no error was thrown, and every automated test passed. The cause was two reasonable pieces of CSS and JavaScript that only fail in combination.&lt;/p&gt;

&lt;h2 id=&quot;setup&quot;&gt;The two reasonable pieces&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Piece one: the reduced-motion reset.&lt;/strong&gt; Like many sites, mine carries the well-known blanket rule that switches off animation for people who ask for less motion:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-css&quot;&gt;@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The duration is a tiny value and not zero on purpose. With zero, no transition runs at all, so &lt;code&gt;transitionend&lt;/code&gt; and &lt;code&gt;animationend&lt;/code&gt; events never fire, and any code waiting for them hangs.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Piece two: the menu.&lt;/strong&gt; A dropdown has to be measured before it can be placed, because its position depends on its own size and on how much room the viewport has. So the menu component rendered its panel off-screen and invisible, measured it, then moved it into place, revealed it, and focused the first item. All of that happened synchronously in one step:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;// after measuring
panel.style.left = x + &amp;quot;px&amp;quot;;
panel.style.top = y + &amp;quot;px&amp;quot;;
panel.style.visibility = &amp;quot;visible&amp;quot;;
firstItem.focus();&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;visibility: hidden&lt;/code&gt; is a natural choice for the unplaced state. It keeps the element's layout box, so it can be measured, and it hides it from sight and from assistive technology.&lt;/p&gt;

&lt;h2 id=&quot;why&quot;&gt;Why they fail together&lt;/h2&gt;
&lt;p&gt;Three facts combine.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;1. Every element already has &lt;code&gt;transition-property: all&lt;/code&gt;.&lt;/strong&gt; That is the CSS default. Elements don't visibly transition only because the default &lt;em&gt;duration&lt;/em&gt; is zero. The reset rule gives every element a non-zero duration, so under reduced motion every property change on every element becomes a real transition, 0.01 ms long. That includes properties nobody thinks of as animated.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. &lt;code&gt;visibility&lt;/code&gt; can be transitioned.&lt;/strong&gt; It doesn't fade, but it does take part in transitions: the value switches between the two states over the transition's duration. At the instant a transition starts, the element's computed value is still the starting value.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. &lt;code&gt;focus()&lt;/code&gt; refuses hidden elements, quietly.&lt;/strong&gt; An element whose computed visibility is &lt;code&gt;hidden&lt;/code&gt; can't be focused. The method doesn't throw and returns nothing. Focus just stays where it was.&lt;/p&gt;
&lt;p&gt;Put together: the script set &lt;code&gt;visibility: visible&lt;/code&gt;, which under reduced motion started a 0.01 ms transition. On the very next line, with no time having passed, the first item's computed visibility was still &lt;code&gt;hidden&lt;/code&gt;. &lt;code&gt;focus()&lt;/code&gt; did nothing. A fraction of a millisecond later the menu was fully visible, with focus still on the button behind it. When I finally logged it on an affected machine, the result was exactly that:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;{ rowVisibility: &amp;quot;hidden&amp;quot;, tookFocus: false }&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Without reduced motion, the change applied instantly and focus landed. So the bug existed only for people who had turned the setting on, and nobody testing with default settings could ever see it.&lt;/p&gt;

&lt;h2 id=&quot;fix&quot;&gt;The fix&lt;/h2&gt;
&lt;p&gt;The menu no longer uses &lt;code&gt;visibility&lt;/code&gt; at all for its unplaced state. The panel is rendered far off-screen (&lt;code&gt;left: -9999px&lt;/code&gt;) until it has been measured, then moved into place. An off-screen element is still focusable, so there is no moment at which &lt;code&gt;focus()&lt;/code&gt; can be refused, whatever the user's motion setting does to transitions.&lt;/p&gt;
&lt;p&gt;While I was in there I fixed a second problem with the same component: a menu taller than the viewport had rows that could not be reached at all. Placement now gives the panel a maximum height and lets it scroll.&lt;/p&gt;
&lt;p&gt;Other ways to solve it, if moving the element off-screen doesn't suit your component:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Take visibility out of the transition.&lt;/strong&gt; Give the panel an explicit &lt;code&gt;transition-property&lt;/code&gt; that lists only what you animate (for example &lt;code&gt;opacity, transform&lt;/code&gt;), with enough specificity to hold under the reset.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Focus after the reveal has been committed.&lt;/strong&gt; Wait one animation frame, or for &lt;code&gt;transitionend&lt;/code&gt;, before calling &lt;code&gt;focus()&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Scope the reset.&lt;/strong&gt; Apply the reduced-motion rule to the properties that actually move things, not to every transition on the page.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;general&quot;&gt;The general lesson: check that focus landed&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;focus()&lt;/code&gt; is one of the few DOM calls that fails without a signal. It can be refused because the element is hidden, &lt;code&gt;inert&lt;/code&gt;, disabled, not yet in the document, or inside a closed &lt;code&gt;&amp;lt;details&amp;gt;&lt;/code&gt;. Any code that moves focus as part of opening something should be able to confirm it:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;function focusOrReport(el) {
  el.focus();
  if (document.activeElement !== el) {
    console.warn(&amp;quot;focus was refused&amp;quot;, el, getComputedStyle(el).visibility);
    return false;
  }
  return true;
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;In a test suite this is a one-line assertion (&lt;code&gt;expect(document.activeElement).toBe(firstItem)&lt;/code&gt;), and it would have caught this bug on the day it was written, provided the test ran with reduced motion emulated.&lt;/p&gt;

&lt;h2 id=&quot;testing&quot;&gt;Test with reduced motion on&lt;/h2&gt;
&lt;p&gt;That last condition is the real gap. My tests and my manual checks all ran with default settings. Reduced motion is easy to emulate, and it changes more behaviour than its name suggests:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;In Chrome DevTools: open the Rendering panel and set &lt;em&gt;Emulate CSS media feature prefers-reduced-motion&lt;/em&gt; to &lt;em&gt;reduce&lt;/em&gt;.&lt;/li&gt;
&lt;li&gt;In Playwright: &lt;code&gt;page.emulateMedia({ reducedMotion: &amp;quot;reduce&amp;quot; })&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;On your own machine: turn the system setting on for a week. I found a second issue that way. A loading overlay that fades out when the app is ready stayed fully opaque over the finished page until its (collapsed) animation ended, then cut away abruptly. With motion reduced it was a longer wait that ended in a harder flash, the opposite of what the setting asks for. That one animation is now exempt from the reset, because it only changes opacity and nothing moves.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;summary&quot;&gt;Summary&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;The common reduced-motion reset turns &lt;em&gt;every&lt;/em&gt; property change into a very short transition, because &lt;code&gt;transition-property&lt;/code&gt; defaults to &lt;code&gt;all&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code&gt;visibility&lt;/code&gt; takes part in transitions, so an element revealed that way is still hidden for an instant.&lt;/li&gt;
&lt;li&gt;&lt;code&gt;focus()&lt;/code&gt; on a hidden element fails silently. Verify with &lt;code&gt;document.activeElement&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Don't hide a to-be-focused element with &lt;code&gt;visibility&lt;/code&gt;, or else focus it a frame later.&lt;/li&gt;
&lt;li&gt;Run your keyboard tests with reduced motion emulated.&lt;/li&gt;
&lt;/ul&gt;</content>
    <category term="Accessibility" />
    <category term="CSS" />
    <category term="Web" />
  </entry>
  <entry>
    <title>Cutting 30 KB from a boot bundle by moving module boundaries</title>
    <link href="https://faizo.net/writing/code-splitting-boot-bundle-module-boundaries/" />
    <id>https://faizo.net/writing/code-splitting-boot-bundle-module-boundaries/</id>
    <published>2026-11-13T00:00:00Z</published>
    <updated>2026-11-13T00:00:00Z</updated>
    <summary>Lazy loading didn't shrink my first-load JavaScript until I learned that a bundler places each module in one chunk, whole. How to find and split those modules.</summary>
    <content type="html">&lt;p&gt;DWEEB is a single-page editor. Its build has a budget for the &quot;critical&quot; bundle, meaning the JavaScript and CSS a first visit must download before the editor works, and the build fails when the budget is exceeded. For a while that budget was 182 KB gzipped and the bundle sat at 181.0 KB. Every new feature turned into a negotiation over a few hundred bytes.&lt;/p&gt;
&lt;p&gt;The app already lazy-loaded every dialog. The remaining weight was not in the obviously optional screens. It was in code that &lt;em&gt;looked&lt;/em&gt; like it was part of the first screen and wasn't, and in modules that were dragged into the boot chunk by a single import. Fixing both took the critical bundle from &lt;strong&gt;588,815 to 477,114 bytes raw, and from 181,014 to 150,427 bytes gzipped&lt;/strong&gt;, about 17% less to download. The budget is now 160 KB.&lt;/p&gt;

&lt;h2 id=&quot;first-screen&quot;&gt;Rule one: the boot path carries only what the first screen renders&lt;/h2&gt;
&lt;p&gt;The editor shows a tree of message components on the left. Selecting a row unfolds an inspector under it with that component's settings: text fields, a markdown toolbar, colour and emoji pickers, plugin options. There is one inspector for each kind of component, and together they were a large share of the main chunk.&lt;/p&gt;
&lt;p&gt;On load, no row is selected. Not one line of inspector code can run until the user clicks something. It was in the boot bundle only because the tree component imported it at the top of the file.&lt;/p&gt;
&lt;p&gt;All the inspectors are now one lazy chunk behind a single entry module:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-jsx&quot;&gt;const LazyInspector = lazy(() =&amp;gt; import(&amp;quot;./inspectorPanels&amp;quot;));

function TreeRow({ node, selected }) {
  return (
    &amp;lt;li&amp;gt;
      &amp;lt;RowHeader node={node} /&amp;gt;
      {selected &amp;amp;&amp;amp; (
        &amp;lt;ChunkErrorBoundary onDismiss={deselect}&amp;gt;
          &amp;lt;Suspense fallback={&amp;lt;InspectorSkeleton /&amp;gt;}&amp;gt;
            &amp;lt;LazyInspector node={node} /&amp;gt;
          &amp;lt;/Suspense&amp;gt;
        &amp;lt;/ChunkErrorBoundary&amp;gt;
      )}
    &amp;lt;/li&amp;gt;
  );
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Two things make this invisible to the user:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Warm it when idle.&lt;/strong&gt; Once the tree has mounted, an idle callback starts the &lt;code&gt;import()&lt;/code&gt;. By the time a person has read the screen and clicked a row, the chunk is almost always already in memory. The lazy boundary delays the download past first paint. It doesn't delay the click.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Handle the load failing.&lt;/strong&gt; A lazily loaded chunk can fail to arrive, for example when a deploy has replaced the files an open tab still refers to. The boundary around it offers a refresh, dismissing that notice deselects the row, and the rest of the editor keeps working throughout. I wrote about that failure in &lt;a href=&quot;/writing/spa-deploy-skew-chunk-errors/&quot;&gt;When a deploy deletes the chunk an open tab still needs&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;One chunk for all inspectors is deliberate. A chunk per inspector type would save a little download for someone who only ever edits text, and cost a visible delay the first time each new type is opened.&lt;/p&gt;

&lt;h2 id=&quot;whole-modules&quot;&gt;Rule two: a module lands in one chunk, whole&lt;/h2&gt;
&lt;p&gt;The second saving came from something I had misunderstood about bundlers. I assumed that if a lazy dialog was the only user of a function, the function would end up in the dialog's chunk. It doesn't work that way.&lt;/p&gt;
&lt;p&gt;Rollup (which Vite uses for production builds) removes exports that &lt;em&gt;nothing&lt;/em&gt; uses. But an export that &lt;em&gt;something&lt;/em&gt; uses has to live somewhere, and the unit of placement is the module, not the function. If a module is imported by the boot path at all, the whole module goes into a boot chunk, including every export that only lazy code calls.&lt;/p&gt;
&lt;p&gt;My webhook module was a typical example. It exported a small URL parser, which the boot path used to recognise a pasted webhook address, and next to it all the code that sends, edits and fetches messages, which only the Send dialog used. One import of the parser put the entire sender in the boot bundle.&lt;/p&gt;
&lt;p&gt;The fix is not clever. Split the file along the line between &quot;needed at boot&quot; and &quot;needed later&quot;:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;// before: one module, imported by boot code for parseWebhookUrl only
webhook/index.ts        parseWebhookUrl, sendMessage, editMessage, fetchMessage …

// after
webhook/webhookUrl.ts   parseWebhookUrl              ← boot imports this
webhook/send.ts         sendMessage, editMessage …   ← only the dialog imports this&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;I made the same cut in half a dozen places: the open/closed flag of the assistant panel apart from the assistant's logic, the toolbar's icons apart from the full icon set, the API calls a dialog makes apart from the types the rest of the app shares.&lt;/p&gt;

&lt;h2 id=&quot;barrels&quot;&gt;Barrel files undo all of it&lt;/h2&gt;
&lt;p&gt;A barrel is an &lt;code&gt;index.ts&lt;/code&gt; that re-exports everything in a folder so callers can write one tidy import. Splitting the webhook module achieves nothing if boot code still imports the parser through the folder's barrel, because importing the barrel imports every module it re-exports, the sender included.&lt;/p&gt;
&lt;p&gt;In theory a bundler can skip re-exported modules that have no side effects. In practice that depends on package flags and on what each module does at its top level, and I didn't want my first-load size to rest on it. The rule in this codebase is plain: &lt;strong&gt;code on the boot path imports from the specific file, never from a barrel.&lt;/strong&gt;&lt;/p&gt;

&lt;h2 id=&quot;finding&quot;&gt;Finding the modules worth splitting&lt;/h2&gt;
&lt;p&gt;Bundle visualisers show which modules are big. They don't show which ones are in the wrong chunk. For that I print, for each output chunk, the modules inside it and their size after tree-shaking. A tiny plugin does it:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;// vite.config.ts
function chunkReport() {
  return {
    name: &amp;quot;chunk-report&amp;quot;,
    generateBundle(_options, bundle) {
      for (const chunk of Object.values(bundle)) {
        if (chunk.type !== &amp;quot;chunk&amp;quot;) continue;
        const kind = chunk.isEntry ? &amp;quot;entry&amp;quot; : chunk.isDynamicEntry ? &amp;quot;lazy&amp;quot; : &amp;quot;shared&amp;quot;;
        console.log(chunk.fileName, kind);
        const modules = Object.entries(chunk.modules)
          .sort((a, b) =&amp;gt; b[1].renderedLength - a[1].renderedLength);
        for (const [id, info] of modules) {
          console.log(&amp;quot;   &amp;quot;, String(info.renderedLength).padStart(7), id);
        }
      }
    },
  };
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Then I read the list for the chunks a first visit loads and ask one question of each large module: &lt;em&gt;does the first screen call this?&lt;/em&gt; Modules where the honest answer is &quot;one small function of it&quot; are the candidates. The list was shorter than I expected, and each split was a few minutes of moving code between files.&lt;/p&gt;

&lt;h2 id=&quot;cautions&quot;&gt;Three cautions&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Splitting can add requests.&lt;/strong&gt; I once imported a few state modules directly from the app's top-level error screen, which lives in the entry chunk. The bundler responded by pulling those modules out of the main app chunk into chunks of their own, so both could share them. The build came out at 19 critical requests against a cap of 16, and 12 KB heavier. If code in the entry chunk needs something from the app, it should reach it through a dynamic import of the app chunk, not around it.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Imports can have side effects.&lt;/strong&gt; The default entry point of Stripe's JavaScript package injects Stripe's script tag into the page as a side effect of being imported. Because it sat in a shared vendor chunk, every visitor on every page view loaded a payment script, with its cookies, though almost none of them would ever open the checkout. The package ships a second entry point, &lt;code&gt;@stripe/stripe-js/pure&lt;/code&gt;, that does nothing until you call it. Check what your dependencies do at import time.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Enforce the result.&lt;/strong&gt; The build measures the critical bundle from its own manifest and fails over budget, and it also caps the number of critical requests. Without that check, the next convenient top-level import quietly puts everything back.&lt;/p&gt;

&lt;h2 id=&quot;summary&quot;&gt;Summary&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Ask what the first screen actually renders. Anything that needs a click to appear can load after first paint, warmed during idle time.&lt;/li&gt;
&lt;li&gt;A module is placed in one chunk as a whole. One boot-side import carries all of its exports along.&lt;/li&gt;
&lt;li&gt;Split modules along the boot/later line, and import boot code from specific files, not barrels.&lt;/li&gt;
&lt;li&gt;Print each chunk's modules to find the ones in the wrong place.&lt;/li&gt;
&lt;li&gt;Watch the request count as well as the bytes, and fail the build on both.&lt;/li&gt;
&lt;/ul&gt;</content>
    <category term="Performance" />
    <category term="Web" />
    <category term="Front end" />
  </entry>
  <entry>
    <title>How a trailing space in an env file turns a security check off</title>
    <link href="https://faizo.net/writing/environment-config-fail-loudly/" />
    <id>https://faizo.net/writing/environment-config-fail-loudly/</id>
    <published>2026-11-13T00:00:00Z</published>
    <updated>2026-11-13T00:00:00Z</updated>
    <summary>REQUIRE_MANAGE_GUILD=true with a trailing space parsed as false. How lenient env parsing fails silently, and the rules that make a server refuse to boot instead.</summary>
    <content type="html">&lt;p&gt;My API server reads its settings from environment variables, like most services that run in containers. One of them, &lt;code&gt;REQUIRE_MANAGE_GUILD&lt;/code&gt;, decides whether a signed-in user may only work with the Discord servers they have permission to manage. The env file says &lt;code&gt;true&lt;/code&gt;. Reading the parser one day, I realised how little it would take for the running process to say false.&lt;/p&gt;
&lt;p&gt;All it needed was a space at the end of the line. The parser compared the value with &lt;code&gt;&amp;quot;true&amp;quot;&lt;/code&gt;, would find &lt;code&gt;&amp;quot;true &amp;quot;&lt;/code&gt;, and would do what a great deal of configuration code does with a value it doesn't recognise: use the default. Nothing would be logged. The server would start normally with the restriction simply off.&lt;/p&gt;
&lt;p&gt;The same parser read &lt;code&gt;COOKIE_SECURE&lt;/code&gt;, where the same mistake would drop the &lt;code&gt;Secure&lt;/code&gt; flag from the session cookie. This article is about the rules I changed afterwards, and two related ways configuration can be wrong without anything telling you.&lt;/p&gt;

&lt;h2 id=&quot;lenient&quot;&gt;Lenient parsing is a silent failure&lt;/h2&gt;
&lt;p&gt;The parser had a shape most projects contain somewhere:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-rust&quot;&gt;fn env_bool(key: &amp;amp;str, default: bool) -&amp;gt; bool {
    match std::env::var(key).as_deref() {
        Ok(&amp;quot;true&amp;quot;) | Ok(&amp;quot;1&amp;quot;) =&amp;gt; true,
        Ok(&amp;quot;false&amp;quot;) | Ok(&amp;quot;0&amp;quot;) =&amp;gt; false,
        _ =&amp;gt; default,
    }
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The last arm handles two very different situations as if they were one. &quot;The variable isn't set&quot; is a legitimate reason to use the default. &quot;The variable is set to something I can't read&quot; is an operator error, and treating it as &quot;unset&quot; converts a typo into a behaviour change. For a boolean that guards access, the default is the dangerous direction as often as not.&lt;/p&gt;
&lt;p&gt;Trailing whitespace is the most common way to hit it, because it is invisible in an editor and survives copy and paste. A capitalised &lt;code&gt;True&lt;/code&gt;, a value someone wrapped in quotes, or a file saved with Windows line endings can do the same thing.&lt;/p&gt;

&lt;h2 id=&quot;rules&quot;&gt;The rules now&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;1. Trim every value on the way in.&lt;/strong&gt; No setting in my server has meaningful leading or trailing whitespace, so every variable is trimmed in one place before anything parses it.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. Absent means default. Present but unparseable means the server doesn't start.&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-rust&quot;&gt;fn parse_bool(key: &amp;amp;str, raw: &amp;amp;str) -&amp;gt; Result&amp;lt;bool, ConfigError&amp;gt; {
    match raw.trim().to_ascii_lowercase().as_str() {
        &amp;quot;1&amp;quot; | &amp;quot;true&amp;quot; | &amp;quot;yes&amp;quot; | &amp;quot;on&amp;quot; =&amp;gt; Ok(true),
        &amp;quot;0&amp;quot; | &amp;quot;false&amp;quot; | &amp;quot;no&amp;quot; | &amp;quot;off&amp;quot; =&amp;gt; Ok(false),
        other =&amp;gt; Err(ConfigError::invalid(key, other, &amp;quot;expected true or false&amp;quot;)),
    }
}

fn env_bool(key: &amp;amp;str, default: bool) -&amp;gt; Result&amp;lt;bool, ConfigError&amp;gt; {
    match std::env::var(key) {
        Err(_) =&amp;gt; Ok(default),
        Ok(raw) =&amp;gt; parse_bool(key, &amp;amp;raw),
    }
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The accepted spellings are a short, closed list. Anything else is an error that names the variable and shows the value it found. The same rule applies to numbers, durations and lists: a price table that doesn't parse stops the boot, it doesn't become an empty table.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. Fail at startup, not at first use.&lt;/strong&gt; All configuration is parsed into one struct before the server opens a port. A deploy with a bad value fails within a second, while the previous version is still running, instead of failing for a user an hour later on the one code path that reads the setting.&lt;/p&gt;
&lt;p&gt;A crash at boot feels harsh. It is the cheapest failure available: it happens while I am watching the deploy, and the error message says exactly which line to fix.&lt;/p&gt;

&lt;h2 id=&quot;paths&quot;&gt;The second silent failure: relative paths in a container&lt;/h2&gt;
&lt;p&gt;The server keeps several small SQLite databases: short links, scheduled posts, a message library. Each has a path setting, and each originally defaulted to a bare file name such as &lt;code&gt;schedules.db&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;A bare file name is resolved against the process's working directory. In a container that is a directory inside the container's own writable layer, not the mounted volume. Everything works. Data is written and read back. Then the next deploy replaces the container, and the database is gone, with no error at any point, because from the program's point of view nothing went wrong.&lt;/p&gt;
&lt;p&gt;Three changes closed that:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The compose file passes every path explicitly with a default on the volume, for example &lt;code&gt;SCHEDULE_DB_PATH=${SCHEDULE_DB_PATH:-/data/schedules.db}&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;At boot, the server checks every enabled store and logs a loud warning naming each one whose path is relative.&lt;/li&gt;
&lt;li&gt;A strict flag, meant for production, turns that warning into a refusal to start. A new store has to be added to the list that this check covers, so it can't be forgotten.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;This matters most for features that are off by default. Switching one on later is a configuration change, made by hand on the server, long after the code review. If the feature brings its own database, its path has to be set in the same change, and the strict check is what catches it when it isn't.&lt;/p&gt;

&lt;h2 id=&quot;stale&quot;&gt;The third: configuration that was valid when you wrote it&lt;/h2&gt;
&lt;p&gt;Some settings name things that exist outside your system. My server's built-in AI assistant calls a hosted model, and the model's name is a setting. The provider retires models on a published schedule. One day a name that had been working started returning &lt;code&gt;404 model_not_found&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;Boot-time validation can't catch this, because the value was correct at boot. What matters is how the running code treats it. Mine originally handled it like any other rejected request: the whole call failed with a 502, which pages me, even when a configured fallback model could have answered. Now a retired model is recognised specifically. It is skipped, the next model in the chain is tried, and a warning is logged. Only when no configured model is left does the server log an error that lists every retired name, which is precisely the thing a person needs to go and fix.&lt;/p&gt;
&lt;p&gt;The general idea: when a setting points at something external, decide in advance what &quot;it no longer exists&quot; should do, and make that message name the setting.&lt;/p&gt;

&lt;h2 id=&quot;visible&quot;&gt;Make the effective configuration visible&lt;/h2&gt;
&lt;p&gt;Two smaller habits follow from all this:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Log the decisions, not the secrets.&lt;/strong&gt; A startup line that states which optional features are on, and where each store lives, turns a silent misconfiguration into something you read on every deploy. An access restriction listed as &quot;off&quot; in that summary is hard to miss.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Health checks should exercise the stores.&lt;/strong&gt; The readiness endpoint runs a trivial query against each database that is configured, with a short deadline, and reports which one failed. A store that is misconfigured or stuck shows up in monitoring instead of in a user's error message.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;summary&quot;&gt;Summary&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Trim values. Whitespace in an env file is invisible and common.&lt;/li&gt;
&lt;li&gt;Unset means &quot;use the default&quot;. Set but unreadable means &quot;refuse to start&quot;, with the variable's name in the message.&lt;/li&gt;
&lt;li&gt;Parse everything before opening a port.&lt;/li&gt;
&lt;li&gt;In containers, give every data file an absolute path on a volume, and check for it at boot.&lt;/li&gt;
&lt;li&gt;For settings that name external things, handle &quot;it's gone&quot; explicitly and say which setting to change.&lt;/li&gt;
&lt;li&gt;Log the effective feature switches at startup.&lt;/li&gt;
&lt;/ul&gt;</content>
    <category term="Operations" />
    <category term="Rust" />
    <category term="Configuration" />
  </entry>
  <entry>
    <title>Preact's useId gave my dialogs the same ids as the page behind them</title>
    <link href="https://faizo.net/writing/preact-useid-duplicate-ids-portals/" />
    <id>https://faizo.net/writing/preact-useid-duplicate-ids-portals/</id>
    <published>2026-11-13T00:00:00Z</published>
    <updated>2026-11-13T00:00:00Z</updated>
    <summary>useId in Preact counts per render root, so a dialog rendered in its own root repeats ids already used on the page. How to detect duplicate ids and replace the hook.</summary>
    <content type="html">&lt;p&gt;Form fields need ids. A &lt;code&gt;&amp;lt;label for&amp;gt;&lt;/code&gt; needs one to point at its input, and &lt;code&gt;aria-describedby&lt;/code&gt; needs one to connect a field to its hint or error text. In a component you can't hard-code them, because the component may appear twice on a page. That is the job of the &lt;code&gt;useId&lt;/code&gt; hook: it hands each component instance an id that is unique in the document.&lt;/p&gt;
&lt;p&gt;In my app it didn't. With one particular dialog open, two inputs in the dialog had the same ids as two inputs in the editor behind it. This is the story of how that happens with Preact, what it breaks, and the few lines that replaced the hook.&lt;/p&gt;

&lt;h2 id=&quot;symptom&quot;&gt;What it broke&lt;/h2&gt;
&lt;p&gt;The dialog had a &quot;Message ID&quot; field and a &quot;Thread ID&quot; field. The editor behind it had &quot;Username&quot; and &quot;Avatar URL&quot; fields. Each pair shared an id. Browsers resolve an id reference to the &lt;em&gt;first&lt;/em&gt; matching element in document order, and the editor comes first. So:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Clicking the &quot;Message ID&quot; label in the dialog focused nothing useful. Its &lt;code&gt;for&lt;/code&gt; pointed at the Username field, which sat under the dialog's backdrop.&lt;/li&gt;
&lt;li&gt;A screen reader announced the dialog's inputs without their labels, and announced the editor's hint text as the description of a dialog field.&lt;/li&gt;
&lt;li&gt;A validation error in the dialog was attached, as far as assistive technology could tell, to a field on the page behind.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;For a sighted mouse user almost nothing looked wrong, which is why it survived for a long time. I found it while checking the dialog's accessibility by hand, by asking the browser which labels each input had:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;// In the console, with the dialog open:
document.querySelector('[role=&amp;quot;dialog&amp;quot;] input').labels
// → NodeList [] (the label belongs to another element)&lt;/code&gt;&lt;/pre&gt;

&lt;h2 id=&quot;why&quot;&gt;Why useId repeats itself&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;useId&lt;/code&gt; can't use a random number. It was designed for server rendering, where the id generated on the server must equal the id generated in the browser during hydration. So the implementation is deterministic: it derives the id from the component's position in the tree and a counter.&lt;/p&gt;
&lt;p&gt;In Preact, that counter is stored on the root of the tree being rendered. The ids come out as &lt;code&gt;P0-0&lt;/code&gt;, &lt;code&gt;P0-1&lt;/code&gt;, &lt;code&gt;P0-2&lt;/code&gt; and so on, in the order components first ask for one. Within a single tree that is unique. The catch is the phrase &quot;a single tree&quot;. Every call to &lt;code&gt;render()&lt;/code&gt; into a different container starts a new root with a new counter, beginning again at &lt;code&gt;P0-0&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;My dialogs are rendered with &lt;code&gt;createPortal&lt;/code&gt; into containers attached to &lt;code&gt;&amp;lt;body&amp;gt;&lt;/code&gt;, so that they sit above everything and aren't clipped by any ancestor's overflow or stacking context. In React a portal stays part of the tree that created it. In Preact, &lt;code&gt;createPortal&lt;/code&gt; lives in the compatibility package and is built on a separate &lt;code&gt;render()&lt;/code&gt; into the target container, so for id purposes each portal is its own root. The editor had already handed out &lt;code&gt;P0-0&lt;/code&gt; and &lt;code&gt;P0-1&lt;/code&gt; to its first two fields. The dialog's first two fields asked their own root and received &lt;code&gt;P0-0&lt;/code&gt; and &lt;code&gt;P0-1&lt;/code&gt; too.&lt;/p&gt;
&lt;p&gt;Which fields collided depended on render order, so most dialogs were lucky: their early ids matched elements that didn't use labels. This one wasn't.&lt;/p&gt;

&lt;h2 id=&quot;detect&quot;&gt;Detecting duplicate ids&lt;/h2&gt;
&lt;p&gt;Duplicate ids don't raise an error anywhere. You have to look for them. This snippet lists every id that appears more than once in the current document. Open each dialog and menu in your app and run it:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;const counts = new Map();
for (const el of document.querySelectorAll(&amp;quot;[id]&amp;quot;)) {
  counts.set(el.id, (counts.get(el.id) ?? 0) + 1);
}
console.table([...counts].filter(([, n]) =&amp;gt; n &amp;gt; 1));&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The same check works as a test helper. I call it at the end of the tests that open a dialog over a rendered page:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;export function duplicateIds(root = document) {
  const seen = new Set();
  const dupes = new Set();
  for (const el of root.querySelectorAll(&amp;quot;[id]&amp;quot;)) {
    if (seen.has(el.id)) dupes.add(el.id);
    seen.add(el.id);
  }
  return [...dupes];
}

expect(duplicateIds()).toEqual([]);&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Automated accessibility checkers also flag duplicate ids that are referenced by a label or an ARIA attribute. They only see the state of the page at the moment they run, though, so a scan of the page with every dialog closed reports nothing.&lt;/p&gt;

&lt;h2 id=&quot;fix&quot;&gt;The replacement hook&lt;/h2&gt;
&lt;p&gt;My app is never server-rendered. There is no hydration, so I don't need ids to be reproducible across two environments. I only need them to be unique within one page load. A counter at module level does that, because a module is evaluated once no matter how many render roots exist:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;import { useRef } from &amp;quot;preact/hooks&amp;quot;;

let next = 0;

/** An id unique in this document, across every render root. */
export function useUniqueId(prefix = &amp;quot;id&amp;quot;) {
  const ref = useRef(null);
  if (ref.current === null) {
    ref.current = prefix + &amp;quot;-&amp;quot; + (next++).toString(36);
  }
  return ref.current;
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The ref keeps the id stable for the life of the component instance, across re-renders. Every component in the app now uses this hook, and the project's conventions say never to import &lt;code&gt;useId&lt;/code&gt;, so the old one doesn't come back through a new component or a copied snippet.&lt;/p&gt;

&lt;h2 id=&quot;when-not&quot;&gt;When you can't do this&lt;/h2&gt;
&lt;p&gt;If your app &lt;em&gt;is&lt;/em&gt; server-rendered and hydrated, a module counter is wrong: the server and the browser would count in different orders, and hydration would report mismatches. In that case the options are:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Render overlays inside the main tree&lt;/strong&gt;, positioned with CSS (or the browser's top layer through &lt;code&gt;&amp;lt;dialog&amp;gt;&lt;/code&gt; and the Popover API) instead of being moved to another container. They then share the main root and its counter.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Prefix per root.&lt;/strong&gt; Give each separately rendered root a distinct prefix through context and build ids as &lt;code&gt;prefix + useId()&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Avoid ids where possible.&lt;/strong&gt; Wrapping an input inside its &lt;code&gt;&amp;lt;label&amp;gt;&lt;/code&gt; needs no &lt;code&gt;for&lt;/code&gt; attribute at all. ARIA relationships still need ids, so this only removes part of the problem.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;React has the same design, with an explicit answer for multiple roots: &lt;code&gt;createRoot&lt;/code&gt; takes an &lt;code&gt;identifierPrefix&lt;/code&gt; option for exactly this case. If you run more than one React root on a page and use &lt;code&gt;useId&lt;/code&gt;, set it.&lt;/p&gt;

&lt;h2 id=&quot;summary&quot;&gt;Summary&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;useId&lt;/code&gt; is unique per render root, not per document. Two roots on one page produce the same ids.&lt;/li&gt;
&lt;li&gt;In Preact a portal counts as its own root, and dialogs are exactly where labelled form fields live.&lt;/li&gt;
&lt;li&gt;Duplicate ids fail silently: labels and ARIA references resolve to the first match in the document.&lt;/li&gt;
&lt;li&gt;Check with &lt;code&gt;input.labels&lt;/code&gt; and a duplicate-id scan while overlays are open.&lt;/li&gt;
&lt;li&gt;Without server rendering, a module-level counter is simpler and correct. With it, give each root a prefix.&lt;/li&gt;
&lt;/ul&gt;</content>
    <category term="Preact" />
    <category term="Accessibility" />
    <category term="Front end" />
  </entry>
  <entry>
    <title>Keeping a TypeScript validator and its Rust port in agreement</title>
    <link href="https://faizo.net/writing/two-implementations-one-corpus/" />
    <id>https://faizo.net/writing/two-implementations-one-corpus/</id>
    <published>2026-11-13T00:00:00Z</published>
    <updated>2026-11-13T00:00:00Z</updated>
    <summary>The same validation rules live in a TypeScript web app and a Rust server. A generated test corpus keeps them identical, and UTF-16 length is the first trap.</summary>
    <content type="html">&lt;p&gt;DWEEB, my Discord message builder, validates a message before it is sent: character limits, how many components a message may hold, which component is allowed inside which, required fields. Those rules were written once, in TypeScript, for the browser editor.&lt;/p&gt;
&lt;p&gt;Then I added a server feature that needed the same rules. The server is written in Rust. It exposes the builder to AI clients through the Model Context Protocol, and a model that submits a message needs the same list of problems a person would see in the editor, before anything reaches Discord. Running the TypeScript on the server would have meant adding a JavaScript runtime as a second service. I chose to port the rules to Rust and accept the cost that comes with that choice: &lt;strong&gt;two implementations of one set of rules will drift apart unless something forces them not to.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;This is what does the forcing, and the bugs it caught on the first day.&lt;/p&gt;

&lt;h2 id=&quot;split&quot;&gt;Split the problem: data is generated, rules are pinned&lt;/h2&gt;
&lt;p&gt;A validator is partly data and partly logic. I treat the two differently.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Data is never written twice.&lt;/strong&gt; Limits (how long a button label may be, how many options a select menu holds), the template catalogue and the list of placeholder tokens all live in TypeScript source files. A script reads them and writes a JSON file into the Rust project, which the server embeds at compile time with &lt;code&gt;include_str!&lt;/code&gt;. The Rust code contains no limit as a number. If I change a cap in one place, the other side picks it up on the next build.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Logic is pinned by a shared corpus.&lt;/strong&gt; The rules themselves can't be generated, so they are tested against the same expectations on both sides. The script builds 119 small messages, most of them broken in one specific way, runs the TypeScript validator over them, and records what it reports:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-json&quot;&gt;{
  &amp;quot;name&amp;quot;: &amp;quot;button-at-top-level&amp;quot;,
  &amp;quot;message&amp;quot;: {
    &amp;quot;flags&amp;quot;: 32768,
    &amp;quot;components&amp;quot;: [
      { &amp;quot;type&amp;quot;: 10, &amp;quot;content&amp;quot;: &amp;quot;hi&amp;quot; },
      { &amp;quot;type&amp;quot;: 2, &amp;quot;style&amp;quot;: 1, &amp;quot;label&amp;quot;: &amp;quot;Go&amp;quot;, &amp;quot;custom_id&amp;quot;: &amp;quot;go&amp;quot; }
    ]
  },
  &amp;quot;errors&amp;quot;: [{ &amp;quot;code&amp;quot;: &amp;quot;BUTTON_OUTSIDE_ROW&amp;quot;, &amp;quot;path&amp;quot;: &amp;quot;components[1]&amp;quot; }],
  &amp;quot;warnings&amp;quot;: []
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;That file is committed. The TypeScript test suite checks that the validator still produces exactly these results. The Rust test suite loads the same file and checks that the port produces exactly these results. Neither side can change behaviour without the other side's tests failing.&lt;/p&gt;

&lt;h2 id=&quot;rules&quot;&gt;Four rules that make the corpus trustworthy&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;1. Pin codes and paths, not wording.&lt;/strong&gt; Each expected issue is a &lt;code&gt;(code, path)&lt;/code&gt; pair. The human-readable sentence is left out on purpose. I rewrite error copy often, and a corpus that included it would fail on every wording change and teach me to regenerate it without reading the diff.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. The generator refuses an incomplete corpus.&lt;/strong&gt; The script knows every issue code the validator can produce. If any code is not triggered by at least one case, it exits with an error and writes nothing. So adding a new rule without adding a case for it fails the build, and the Rust port can't silently lack a rule.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. The committed file must match a fresh run.&lt;/strong&gt; CI regenerates the files and fails if &lt;code&gt;git diff&lt;/code&gt; shows any change. Nobody can commit a corpus that is out of date, or edit it by hand to make a test pass.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;4. The output is deterministic everywhere.&lt;/strong&gt; Anything sorted in the file is sorted by plain code-point comparison, never with JavaScript's &lt;code&gt;localeCompare&lt;/code&gt;. That function's ordering depends on the machine's locale and on the ICU data the runtime ships, so the file could differ between my laptop and CI, and Rust could not reproduce it. Code-point order is the same on every machine and is what Rust's string comparison does by default.&lt;/p&gt;

&lt;h2 id=&quot;utf16&quot;&gt;Trap one: what &quot;length&quot; means&lt;/h2&gt;
&lt;p&gt;The first trap is string length. The editor counts characters with JavaScript's &lt;code&gt;.length&lt;/code&gt;, the same unit an HTML input's &lt;code&gt;maxLength&lt;/code&gt; uses. That unit is the UTF-16 code unit. Most characters are one unit. Characters outside the Basic Multilingual Plane, which includes most emoji, are two.&lt;/p&gt;
&lt;p&gt;Rust strings are UTF-8, and Rust offers two obvious ways to measure one. Both are wrong here:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-rust&quot;&gt;let s = &amp;quot;🎉🎉🎉&amp;quot;;

s.len();                    // 12  bytes of UTF-8
s.chars().count();          // 3   Unicode scalar values
s.encode_utf16().count();   // 6   UTF-16 code units, what .length returns&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;With &lt;code&gt;chars().count()&lt;/code&gt;, a message made of emoji passes the server's check at twice the length the editor allows. With &lt;code&gt;len()&lt;/code&gt;, the same message is rejected at half the allowed length, and any text with accents or non-Latin script is cut short too. Only &lt;code&gt;encode_utf16().count()&lt;/code&gt; agrees with the browser. The corpus has cases built from emoji that sit exactly on a limit and one unit over it, so a port that counts in the wrong unit fails immediately in both directions.&lt;/p&gt;

&lt;h2 id=&quot;lz&quot;&gt;Trap two: an algorithm defined over UTF-16&lt;/h2&gt;
&lt;p&gt;The editor can turn a message into a share link by compressing its JSON with LZ-String and putting the result in the URL. The server needed to produce the same links. LZ-String is a JavaScript library, and its algorithm is specified in terms of JavaScript string indices: it walks the input one UTF-16 code unit at a time and builds its dictionary from those units.&lt;/p&gt;
&lt;p&gt;A Rust port that iterates over &lt;code&gt;chars()&lt;/code&gt; looks correct and works for every ASCII message. Give it one emoji and it produces a link the browser can't decode, because the two sides disagree about how many symbols the input has. The fix is to convert the input to a &lt;code&gt;Vec&amp;lt;u16&amp;gt;&lt;/code&gt; first and run the algorithm over that. This is pinned the same way as the validator: a generated file of input strings and the exact output the JavaScript library gives for each, including strings with emoji and surrogate pairs.&lt;/p&gt;

&lt;h2 id=&quot;divergence&quot;&gt;One deliberate difference&lt;/h2&gt;
&lt;p&gt;The two sides differ in one place, and the corpus records it instead of hiding it. In the editor, a certain kind of malformed input (a section missing a required part) is refused at the import boundary with an exception, because there is no sensible way to repair it and the editor must never hold a tree it can't render. On the server the caller is a model that can fix its payload if told what is wrong, so the Rust side reports it as an ordinary issue. The corpus stores the Rust behaviour for that case and the TypeScript test knows about the exception. A written-down difference is fine. An accidental one is what the whole setup exists to prevent.&lt;/p&gt;

&lt;h2 id=&quot;worth&quot;&gt;Was porting worth it?&lt;/h2&gt;
&lt;p&gt;For this project, yes. The server stays a single binary with no second runtime beside it, and a rule changed on one side only now fails the other side's tests at build time. The work also improved the original. Feeding model-written payloads through the new server turned up two inputs that made the TypeScript validator throw instead of report: a text block with no content field, and a link button with no URL. Both are things a person could paste into the editor's JSON import, and both now produce an ordinary validation message.&lt;/p&gt;
&lt;p&gt;The cost is real, though. Every new rule is written twice, and the generator is one more thing to keep working. If the second implementation could have called the first one cheaply, I would have done that instead.&lt;/p&gt;

&lt;h2 id=&quot;summary&quot;&gt;Summary&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Generate shared &lt;em&gt;data&lt;/em&gt; from one source. Never copy a limit by hand.&lt;/li&gt;
&lt;li&gt;Pin shared &lt;em&gt;logic&lt;/em&gt; with a corpus produced by the reference implementation and checked by both.&lt;/li&gt;
&lt;li&gt;Make the generator fail when a rule has no case, and make CI fail when the committed corpus is stale.&lt;/li&gt;
&lt;li&gt;Sort by code point, never by locale.&lt;/li&gt;
&lt;li&gt;JavaScript's &lt;code&gt;.length&lt;/code&gt; is UTF-16 code units. In Rust that is &lt;code&gt;encode_utf16().count()&lt;/code&gt;, not &lt;code&gt;len()&lt;/code&gt; or &lt;code&gt;chars().count()&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Algorithms written for JavaScript strings must run over UTF-16 units when ported.&lt;/li&gt;
&lt;/ul&gt;</content>
    <category term="Rust" />
    <category term="TypeScript" />
    <category term="Testing" />
  </entry>
  <entry>
    <title>Nested deadlines: answering Discord interactions inside three seconds</title>
    <link href="https://faizo.net/writing/discord-interaction-deadlines/" />
    <id>https://faizo.net/writing/discord-interaction-deadlines/</id>
    <published>2026-11-09T00:00:00Z</published>
    <updated>2026-11-09T00:00:00Z</updated>
    <summary>Routing Discord button clicks through a dispatcher to plugin services inside the 3-second window: failure classes, safe retries and nested timeouts.</summary>
    <content type="html">&lt;p&gt;Every button click, select menu pick and modal submit in a Discord app arrives as an &lt;em&gt;interaction&lt;/em&gt;, and Discord gives your app three seconds to send the first response. Miss it and the person who clicked sees &lt;q&gt;This interaction failed&lt;/q&gt; (or &lt;q&gt;&amp;lt;app&amp;gt; didn't respond in time&lt;/q&gt;), whatever your server did afterwards. Three seconds sounds generous until you put a few network hops between Discord and the code that actually does the work.&lt;/p&gt;

&lt;p&gt;This is how the interaction path in &lt;a href=&quot;/projects/dweeb/&quot;&gt;DWEEB&lt;/a&gt; is built, the three mistakes I made in it, and the rules I ended up with. The code is Rust, but nothing here depends on the language.&lt;/p&gt;

&lt;h2 id=&quot;the-shape&quot;&gt;The shape of the problem&lt;/h2&gt;
&lt;p&gt;DWEEB lets people put working buttons and menus into webhook messages: a ticket panel, a giveaway, a poll, a self-assignable role menu. Each of those features is its own small service (I call them plugins), and Discord only knows one URL for the whole application: the &lt;strong&gt;interactions endpoint&lt;/strong&gt;. So a single public service, the dispatcher, receives every interaction, verifies Discord's signature, looks at the component's &lt;code&gt;custom_id&lt;/code&gt; prefix (&lt;code&gt;giveaway:&lt;/code&gt;, &lt;code&gt;poll:&lt;/code&gt;, &lt;code&gt;tickets:&lt;/code&gt; and so on) and forwards the request to the plugin that owns it over a private network.&lt;/p&gt;
&lt;p&gt;That gives every click this path:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Discord POSTs the interaction to the dispatcher.&lt;/li&gt;
&lt;li&gt;The dispatcher forwards it to a plugin.&lt;/li&gt;
&lt;li&gt;The plugin may call Discord's REST API (read a role, post a message, edit a channel) before it can decide what to answer.&lt;/li&gt;
&lt;li&gt;The plugin's answer travels back through the dispatcher to Discord.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Each arrow is a place time can go. The design question is who is allowed to spend how much of it, and what happens when they overrun.&lt;/p&gt;

&lt;h2 id=&quot;unreadable-errors&quot;&gt;Mistake one: an error message that says nothing&lt;/h2&gt;
&lt;p&gt;The first alert this path ever sent me read, in full, &lt;q&gt;forward failed prefix=&quot;selfrole:&quot; upstream=http://self-role:8092 err=error sending request for url (…)&lt;/q&gt;. That sentence is what the Rust HTTP client &lt;a href=&quot;https://docs.rs/reqwest&quot;&gt;reqwest&lt;/a&gt; prints for &lt;em&gt;every&lt;/em&gt; transport failure. A refused connection, a DNS failure, our own deadline expiring and a connection dying half-way through all render identically. The real reason sits in the error's &lt;code&gt;source()&lt;/code&gt; chain, which nothing was printing.&lt;/p&gt;
&lt;p&gt;Those four cases want opposite handling, so the first fix was to stop treating them as one thing. Every failed forward is now classified:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-rust&quot;&gt;enum ForwardFailure {
    /// We never got a connection. Nothing reached the plugin.
    Dial,
    /// Connected, sent the request, no answer before the deadline.
    Timeout,
    /// The connection died after the request was written.
    Broken,
}

fn classify(err: &amp;amp;reqwest::Error) -&amp;gt; ForwardFailure {
    // Order matters: a *connect* timeout answers true to both
    // is_connect() and is_timeout(), and it is a dial failure.
    if err.is_connect() {
        ForwardFailure::Dial
    } else if err.is_timeout() {
        ForwardFailure::Timeout
    } else {
        ForwardFailure::Broken
    }
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The log line then carries the flattened cause chain instead of the top-level message, so the same failure now reads &lt;q&gt;client error (Connect): tcp connect error: Connection refused (os error 111)&lt;/q&gt;. One detail worth copying: print the chain &lt;em&gt;or&lt;/em&gt; the client's own message, not both. The top-level message only repeats the URL, and my alert forwarder truncates long lines from the end, which is exactly where the useful part sits.&lt;/p&gt;

&lt;h2 id=&quot;what-to-retry&quot;&gt;What is safe to retry, and what never is&lt;/h2&gt;
&lt;p&gt;The dispatcher reaches plugins directly over the container network, so when a plugin container is being recreated during a deploy there is a short window where its address refuses connections. That used to fail the click. The obvious fix is a retry, and the obvious retry is wrong.&lt;/p&gt;
&lt;p&gt;A retry is only safe when you can prove the first attempt had no effect. For a &lt;strong&gt;dial failure&lt;/strong&gt; you can: no connection was made, so the plugin never saw the request. For a connection that broke &lt;em&gt;after&lt;/em&gt; the request was written you can't. The plugin may have toggled the role, entered the member into the giveaway or recorded the vote, and sending the interaction again would do it twice. A self-assignable role that gets toggled twice is a role that silently didn't change.&lt;/p&gt;
&lt;p&gt;So the rule is narrow: &lt;strong&gt;retry dial failures, never anything else&lt;/strong&gt;. The HTTP library already retries the one other safe case on its own (a pooled keep-alive connection that turns out to be closed before anything was sent), so what reaches the &lt;code&gt;Broken&lt;/code&gt; branch is precisely the set of failures that must not be repeated.&lt;/p&gt;
&lt;p&gt;The retry also has to respect the overall budget. Each attempt gets only what is left of the time the hop started with, and the client has a short connect timeout so that one attempt against an address that silently drops packets can't eat the whole window:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-rust&quot;&gt;let started = Instant::now();
let mut attempt_err = None;
loop {
    let left = FORWARD_BUDGET.saturating_sub(started.elapsed());
    if left.is_zero() {
        break Err(attempt_err.expect(&amp;quot;at least one attempt ran&amp;quot;));
    }
    match client.post(&amp;amp;upstream).timeout(left).body(body.clone()).send().await {
        Ok(response) =&amp;gt; break Ok(response),
        Err(err) if matches!(classify(&amp;amp;err), ForwardFailure::Dial) =&amp;gt; {
            attempt_err = Some(err);
            tokio::time::sleep(DIAL_RETRY_GAP.min(left)).await;
        }
        Err(err) =&amp;gt; break Err(err), // Timeout or Broken: never resend
    }
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;A dial that recovers inside the window logs at info level. A dial that never recovers means the plugin is genuinely unreachable, which is my infrastructure's fault, and that one pages me.&lt;/p&gt;

&lt;h2 id=&quot;equal-deadlines&quot;&gt;Mistake two: two deadlines with the same number&lt;/h2&gt;
&lt;p&gt;This is the one I'd most like other people to avoid, because it looks fine in review. The dispatcher gave each forward &lt;strong&gt;2,500 ms&lt;/strong&gt;. Every plugin gave its own Discord REST calls &lt;strong&gt;2,500 ms&lt;/strong&gt; too. Both numbers are reasonable on their own, and both sit comfortably inside Discord's three seconds.&lt;/p&gt;
&lt;p&gt;The problem is that the inner clock starts later. The plugin's REST call begins some milliseconds after the dispatcher's timer started, so whenever Discord's API was slow enough to bring the inner call close to its limit, the outer timer fired first, every time. The dispatcher gave up and told the member &lt;q&gt;the plugin didn't respond&lt;/q&gt;, then the plugin's call succeeded a moment later. The member saw a failure for a click that had worked, and my alerting saw a plugin timeout, which pointed me at the wrong component.&lt;/p&gt;
&lt;p&gt;The rule I took from it: &lt;strong&gt;an inner deadline must always be strictly smaller than the outer deadline waiting on it&lt;/strong&gt;, with enough margin for the work around it. Then the failure is reported by the component that actually knows what went wrong. The plugins' Discord clients now use 2,200 ms, and the ordering is checked by the compiler rather than by a comment that will drift:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-rust&quot;&gt;const FORWARD_BUDGET_MS: u64 = 2_500;
const PLUGIN_DISCORD_TIMEOUT_MS: u64 = 2_200;
const DISCORD_INTERACTION_WINDOW_MS: u64 = 3_000;

const _: () = assert!(PLUGIN_DISCORD_TIMEOUT_MS &amp;lt; FORWARD_BUDGET_MS);
const _: () = assert!(FORWARD_BUDGET_MS &amp;lt; DISCORD_INTERACTION_WINDOW_MS);&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;In my setup the plugins live in separate crates, so the assertion pins the plugin value as a constant in the dispatcher. That's still better than nothing: changing one number without the other now needs a conscious edit in two places.&lt;/p&gt;

&lt;h2 id=&quot;log-by-fault&quot;&gt;Mistake three: one log level for every failure&lt;/h2&gt;
&lt;p&gt;With the failures classified, the next step was making the alerting follow fault rather than symptom:&lt;/p&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Failure&lt;/th&gt;&lt;th&gt;Whose fault&lt;/th&gt;&lt;th&gt;Level&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;Dial failed for the whole window&lt;/td&gt;&lt;td&gt;Mine: the plugin is down&lt;/td&gt;&lt;td&gt;Error, pages&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;Connection broke after the request was sent&lt;/td&gt;&lt;td&gt;Unknown and unexpected&lt;/td&gt;&lt;td&gt;Error, pages&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;Plugin accepted the request but ran out of time&lt;/td&gt;&lt;td&gt;Usually a slow Discord API behind it&lt;/td&gt;&lt;td&gt;Warning, does not page&lt;/td&gt;&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;The timeout row deserves a note. A plugin that is merely slow because Discord was slow is not something I can act on at 4 a.m., and it heals itself. A plugin that is genuinely wedged is a different story, and that is caught by a separate health check that probes each plugin directly every two minutes. Health checks can tell slow from stuck. The forward path can't.&lt;/p&gt;
&lt;p&gt;The member-facing copy follows the same split. For a timeout the message says to check whether the action went through before clicking again, because the plugin may well have completed it after the dispatcher stopped listening. &lt;q&gt;Try again&lt;/q&gt; would be exactly wrong for a toggle.&lt;/p&gt;

&lt;h2 id=&quot;defer-or-answer&quot;&gt;When to defer instead&lt;/h2&gt;
&lt;p&gt;Discord also lets you buy time: answer with a deferred response within three seconds, then follow up within fifteen minutes. It is tempting to defer everything. I don't, because a deferral changes what the person sees (a &quot;thinking&quot; state or a loading message) and adds a second request that can fail on its own.&lt;/p&gt;
&lt;p&gt;The rule I use is simple. If the work is one or two fast reads that can run concurrently, answer directly: the Directory plugin, which renders a live list of a server's roles and channels, makes three concurrent read requests and never defers. If the work is a multi-step flow that writes to Discord several times (creating a ticket channel, setting its permissions, posting a welcome message, logging it), defer immediately and do the work in the background, rolling back cleanly if a step fails. A test asserts that every response the Directory plugin can produce is a final one, because a stray deferral there would show up as a spinner that never resolves, and nobody would notice it in code review.&lt;/p&gt;

&lt;h2 id=&quot;checklist&quot;&gt;The checklist I use now&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Classify transport failures before deciding anything. Check &quot;couldn't connect&quot; before &quot;timed out&quot;, since a connect timeout is both.&lt;/li&gt;
&lt;li&gt;Log the error's cause chain, not the client's top-level message.&lt;/li&gt;
&lt;li&gt;Retry only failures that provably had no effect. For a forwarded interaction that means dial failures, nothing else.&lt;/li&gt;
&lt;li&gt;Give each retry the remaining budget, not a fresh one.&lt;/li&gt;
&lt;li&gt;Make every inner deadline strictly smaller than the outer one, and have the compiler check it.&lt;/li&gt;
&lt;li&gt;Page on faults that are yours. Watch the rest with health checks that can tell slow from dead.&lt;/li&gt;
&lt;li&gt;Word failure messages for the case where the action may have happened anyway.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;None of this is specific to Discord. Any system where a caller gives up on a fixed clock and a callee keeps working has the same traps. Discord just makes the clock short enough that you hit them in the first month.&lt;/p&gt;</content>
    <category term="Discord API" />
    <category term="Rust" />
    <category term="Reliability" />
  </entry>
  <entry>
    <title>Measuring how Discord renders a message instead of guessing</title>
    <link href="https://faizo.net/writing/measuring-discord-message-rendering/" />
    <id>https://faizo.net/writing/measuring-discord-message-rendering/</id>
    <published>2026-11-09T00:00:00Z</published>
    <updated>2026-11-09T00:00:00Z</updated>
    <summary>Keeping a Discord message preview faithful by measuring Discord's own client: the workflow, media gallery layout rules, failure states and markdown quirks.</summary>
    <content type="html">&lt;p&gt;&lt;a href=&quot;/projects/dweeb/&quot;&gt;DWEEB&lt;/a&gt; shows a live preview of the message you're building, and the whole product depends on that preview being right. If it shows a two-image gallery at one height and Discord shows it at another, people stop trusting it, and a builder you can't trust is just a JSON editor with extra steps.&lt;/p&gt;
&lt;p&gt;Early on I styled the preview by eye from screenshots. It was always slightly off, and I couldn't say by how much. So I switched to measuring: send the same message to Discord, then read the numbers out of Discord's own web client. This article describes that workflow and the rules it produced, which may save you some time if you build anything that renders Discord messages.&lt;/p&gt;

&lt;h2 id=&quot;workflow&quot;&gt;The workflow&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Build the message in the editor&lt;/strong&gt; and export its exact JSON payload.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Post it to a test webhook&lt;/strong&gt; in a private server. For Components V2 messages, webhook execution needs &lt;code&gt;?with_components=true&lt;/code&gt; and the message flag &lt;code&gt;IS_COMPONENTS_V2&lt;/code&gt; (&lt;code&gt;1 &amp;lt;&amp;lt; 15&lt;/code&gt;), or the components are refused.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Open the message in Discord's web client&lt;/strong&gt; and read the rendered DOM with the developer tools: element sizes, &lt;code&gt;getComputedStyle&lt;/code&gt; values, the CSS custom properties the theme defines.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Write the measured values into the preview&lt;/strong&gt; as named tokens, with a note saying where they came from, so nobody &quot;fixes&quot; them by eye later.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;One practical snag: Discord's current client expresses many colors in &lt;code&gt;oklab()&lt;/code&gt;, which is hard to compare with hex values. The simplest reliable conversion is to let the browser do it, by painting the color into a one-pixel canvas and reading the pixel back:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;function measuredColor(cssColor) {
  const ctx = document.createElement(&amp;quot;canvas&amp;quot;).getContext(&amp;quot;2d&amp;quot;, { willReadFrequently: true });
  ctx.clearRect(0, 0, 1, 1);
  ctx.fillStyle = cssColor;          // e.g. &amp;quot;oklab(0.27 0.002 -0.008)&amp;quot;
  ctx.fillRect(0, 0, 1, 1);
  const [r, g, b, a] = ctx.getImageData(0, 0, 1, 1).data;
  const hex = [r, g, b].map((v) =&amp;gt; v.toString(16).padStart(2, &amp;quot;0&amp;quot;)).join(&amp;quot;&amp;quot;);
  return { hex: &amp;quot;#&amp;quot; + hex, alpha: +(a / 255).toFixed(3) };
}&lt;/code&gt;&lt;/pre&gt;

&lt;h2 id=&quot;right-surface&quot;&gt;Measure the right surface&lt;/h2&gt;
&lt;p&gt;My first audit got the background wrong in a way that's easy to repeat. In Discord's 2026 dark theme the app frame behind the chat is a near-black (&lt;code&gt;#121214&lt;/code&gt;), but messages render on the chat panel, which is &lt;code&gt;#1a1a1e&lt;/code&gt;. I sampled the frame, and the preview read far too dark beside the editor. Always find the element the message is actually inside before sampling.&lt;/p&gt;
&lt;p&gt;A related rule: &lt;strong&gt;keep colors that are meant to work together within one theme&lt;/strong&gt;. My preview canvas deliberately uses classic dark mode's chat background (&lt;code&gt;#313338&lt;/code&gt;), because the newer, darker surfaces looked too heavy next to the editor. Containers then have to use classic dark's container color too (&lt;code&gt;#2b2d31&lt;/code&gt;). Mixing the newer theme's container color onto the classic background produced a container that looked like a hole in the page. In the newer theme, containers are lighter than the chat. In the classic theme, they're darker. A pair from one theme always looks right. A mixed pair doesn't.&lt;/p&gt;

&lt;h2 id=&quot;gallery&quot;&gt;Media gallery layout, measured&lt;/h2&gt;
&lt;p&gt;The Components V2 media gallery holds up to ten images, and Discord lays them out differently depending on the count. These are the rules I measured. They're the same at the top level and inside a container. A container just narrows the column, to 566 px in my measurements.&lt;/p&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Images&lt;/th&gt;&lt;th&gt;Layout&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;1&lt;/td&gt;&lt;td&gt;The image at its natural aspect ratio, capped at 600 px wide and 350 px tall.&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;2&lt;/td&gt;&lt;td&gt;Two columns at a fixed 280 px height. The source aspect ratio is ignored.&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;3&lt;/td&gt;&lt;td&gt;A hero on the left and two stacked on the right, in a 2fr / 1fr split, with the whole block at 12:7.&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;4&lt;/td&gt;&lt;td&gt;A 2×2 grid whose cells take the source image's aspect ratio (3:2 if it can't be read).&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;5&lt;/td&gt;&lt;td&gt;A 280 px-high pair, as for two, above a row of three squares.&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;6 and 9&lt;/td&gt;&lt;td&gt;All squares, three per row.&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;7 and 10&lt;/td&gt;&lt;td&gt;A full-width hero at the source aspect ratio (no height cap) above rows of squares.&lt;/td&gt;&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;The two-image case surprised me most. I had assumed Discord would respect the images' shapes. It doesn't: two portrait photos and two panoramas get the same 280 px-high strip, cropped.&lt;/p&gt;
&lt;p&gt;A spoilered container also behaves as a unit: the whole card is blurred heavily (I measured &lt;code&gt;blur(44px)&lt;/code&gt;), its accent stripe is hidden, and a &quot;SPOILER&quot; pill sits on top.&lt;/p&gt;

&lt;h2 id=&quot;failures&quot;&gt;Failure states are part of the design&lt;/h2&gt;
&lt;p&gt;A preview also has to show what happens when things go wrong, because that's what the recipient will see. Measured:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;An image that fails to load&lt;/strong&gt; keeps its cell's geometry and shows a centered 32 px broken-image glyph on an almost transparent fill. A lone image becomes a 350×350 box and a section thumbnail an 85×85 one.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A custom emoji Discord can't resolve&lt;/strong&gt; renders as plain &lt;code&gt;:name:&lt;/code&gt; text, not as a broken image.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A long button label&lt;/strong&gt; grows the button, and the row wraps. &lt;strong&gt;A long select-menu placeholder&lt;/strong&gt; is truncated with an ellipsis.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;markdown&quot;&gt;Markdown quirks worth knowing&lt;/h2&gt;
&lt;p&gt;Discord's markdown isn't CommonMark, and several of its rules differ in ways you only find by testing. Every one of these is checked against real messages and pinned in a test file:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;*italic*&lt;/code&gt; needs a non-space character right after the opening &lt;code&gt;*&lt;/code&gt;, while &lt;code&gt;_italic_&lt;/code&gt; needs word boundaries on both sides.&lt;/li&gt;
&lt;li&gt;An auto-detected link drops trailing punctuation: &lt;code&gt;. , : ; &amp;quot; ' ) ]&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Inline styles can continue across line breaks.&lt;/li&gt;
&lt;li&gt;Consecutive ordered-list items directly after a bullet list are merged into that list.&lt;/li&gt;
&lt;li&gt;Components V2 text displays never render &quot;jumbo&quot; emoji, even when a line contains only emoji.&lt;/li&gt;
&lt;li&gt;Timestamps have &lt;strong&gt;nine&lt;/strong&gt; styles, not seven: &lt;code&gt;&amp;lt;t:1700000000:s&amp;gt;&lt;/code&gt; and &lt;code&gt;&amp;lt;t:1700000000:S&amp;gt;&lt;/code&gt; (short date with short or medium time) joined the older &lt;code&gt;t T d D f F R&lt;/code&gt;. A preview that only knows seven shows the newer two as raw text.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;accepted-gaps&quot;&gt;What I chose not to match&lt;/h2&gt;
&lt;p&gt;Some differences are deliberate and written down as such: no syntax highlighting inside code blocks, the device's native emoji instead of Discord's Twemoji artwork (the Discord Activity version of the app can't load third-party CDNs), and a fallback font when Discord's own isn't available. Writing the accepted gaps down matters as much as the measurements. Otherwise the next audit &quot;fixes&quot; them and breaks something else.&lt;/p&gt;

&lt;h2 id=&quot;takeaway&quot;&gt;Takeaway&lt;/h2&gt;
&lt;p&gt;If a UI has to match another product, measure the other product. A real webhook, a test server and &lt;code&gt;getComputedStyle&lt;/code&gt; give you numbers you can defend, and a short note next to each value (&quot;measured off the live client, dark theme, this surface&quot;) stops it drifting back towards someone's guess.&lt;/p&gt;</content>
    <category term="Discord" />
    <category term="Components V2" />
    <category term="Front end" />
  </entry>
  <entry>
    <title>Your crash reporter is paging you for someone else's code</title>
    <link href="https://faizo.net/writing/browser-extension-crash-reports/" />
    <id>https://faizo.net/writing/browser-extension-crash-reports/</id>
    <published>2026-11-09T00:00:00Z</published>
    <updated>2026-11-09T00:00:00Z</updated>
    <summary>Extensions and third-party scripts throw into your page's error handlers. How to attribute a JavaScript stack trace to its real owner, and why the server decides.</summary>
    <content type="html">&lt;p&gt;A web app's global error handlers, &lt;code&gt;window.onerror&lt;/code&gt; and the &lt;code&gt;unhandledrejection&lt;/code&gt; event, hear everything that throws in the page's JavaScript world. That world isn't only yours. Wallet extensions inject scripts into it on purpose (they have to, to define &lt;code&gt;window.ethereum&lt;/code&gt;). Popup blockers wrap &lt;code&gt;fetch&lt;/code&gt;. Analytics tags you load yourself run there. So do userscripts, bookmarklets and whatever someone pastes into the console.&lt;/p&gt;
&lt;p&gt;My crash reporter for &lt;a href=&quot;/projects/dweeb/&quot;&gt;DWEEB&lt;/a&gt; sends a small, content-free beacon to my server for every uncaught error, and the server turns a real crash into a page to my phone. Over a few months, four of those pages were for code I never shipped. This is how I learned to tell the difference, and the rules I ended up trusting.&lt;/p&gt;

&lt;h2 id=&quot;incidents&quot;&gt;Four pages that weren't mine&lt;/h2&gt;
&lt;h3&gt;A stack overflow with no source URL&lt;/h3&gt;
&lt;p&gt;Safari reported &lt;q&gt;Maximum call stack size exceeded.&lt;/q&gt; with frames named &lt;code&gt;@&lt;/code&gt;, &lt;code&gt;Pk@&lt;/code&gt; and &lt;code&gt;Nk@&lt;/code&gt;, and &lt;strong&gt;no URL on any of them&lt;/strong&gt;. JavaScriptCore renders code that has no script URL that way. The short names looked like minified code, which made me assume they were mine. To check, I rebuilt every bundle that had been deployed that week and compared the minified identifier frequencies against production. They matched (so local rebuilds name things the same way production does, a useful trick in itself), and no build contained those symbols. It was someone else's script overflowing its own stack.&lt;/p&gt;
&lt;h3&gt;MetaMask failing to connect to itself&lt;/h3&gt;
&lt;p&gt;The second was an &lt;code&gt;unhandledrejection&lt;/code&gt;: &lt;q&gt;Failed to connect to MetaMask&lt;/q&gt;, with one frame at &lt;code&gt;chrome-extension://nkbihfbeogaeaoehlefnkodbefgpgknn/…&lt;/code&gt;. That is MetaMask's page-world script. It starts a connection on load and drops the promise, which rejects after an extension-detection timeout. My app never touches &lt;code&gt;window.ethereum&lt;/code&gt;. The interesting part was the build that reported it: a bundle about 25 days old, still running from a visitor's service-worker cache. Whatever I fixed in the client, that visitor's copy would keep reporting with the old rules for weeks. Only the server could stop it.&lt;/p&gt;
&lt;h3&gt;&quot;Failed to fetch&quot; from Google's own tag&lt;/h3&gt;
&lt;p&gt;The third read &lt;code&gt;Failed to fetch&lt;/code&gt;, and some of its frames were &quot;page&quot; frames, which is why it paged. Those frames turned out to be Google's &lt;code&gt;gtag.js&lt;/code&gt;, sending an analytics hit, underneath two frames from a popup blocker. The blocker wraps &lt;code&gt;window.fetch&lt;/code&gt; and passes each request to an asynchronous inspector whose promise it never handles. When an analytics hit failed (blocked, or the visitor went offline), the dropped promise rejected too. &lt;code&gt;gtag.js&lt;/code&gt; handles its own failures. I reproduced it exactly in headless Chrome with a replica of the hook, and without the hook the same failed requests produced nothing.&lt;/p&gt;
&lt;h3&gt;Safari's extension API wording&lt;/h3&gt;
&lt;p&gt;The fourth had no stack at all: &lt;q&gt;Invalid call to runtime.sendMessage(). Tab not found.&lt;/q&gt; That is WebKit's wording when an extension's content script calls a WebExtension API for a tab that's gone. Safari rejects those calls without a stack, so only the message attributes it. My app calls no extension APIs.&lt;/p&gt;

&lt;h2 id=&quot;the-rule&quot;&gt;The rule: every location is someone else's&lt;/h2&gt;
&lt;p&gt;The tempting rule is the one several error-tracking tools use: look at the top frame, and if it belongs to an extension, drop the error. I rejected it, because it silences real bugs. Extensions that wrap browser APIs insert their frames &lt;em&gt;above&lt;/em&gt; yours. If my code calls &lt;code&gt;history.pushState&lt;/code&gt; with something invalid while an extension wraps &lt;code&gt;pushState&lt;/code&gt;, the top frame is the extension's, and the bug is mine.&lt;/p&gt;
&lt;p&gt;What I use instead:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Extract every &lt;strong&gt;location&lt;/strong&gt; in the stack: each &lt;code&gt;://&lt;/code&gt; together with the whole scheme before it, compared case-insensitively. A stack line without a location (&lt;code&gt;&amp;lt;anonymous&amp;gt;&lt;/code&gt;, &lt;code&gt;[native code]&lt;/code&gt;, &lt;code&gt;async Promise.all (index 0)&lt;/code&gt;) is ignored.&lt;/li&gt;
&lt;li&gt;The error is foreign only if there is &lt;strong&gt;at least one location and all of them belong to someone else&lt;/strong&gt;. A single frame of mine anywhere in the stack keeps it mine.&lt;/li&gt;
&lt;li&gt;&quot;Someone else&quot; means an extension scheme (&lt;code&gt;chrome-extension&lt;/code&gt;, &lt;code&gt;moz-extension&lt;/code&gt;, &lt;code&gt;safari-web-extension&lt;/code&gt;, &lt;code&gt;safari-extension&lt;/code&gt;, and &lt;code&gt;webkit-masked-url&lt;/code&gt;, which is how Safari masks every extension URL), Firefox's &lt;code&gt;&amp;lt;anonymous code&amp;gt;&lt;/code&gt; (its name for page-world extension scripts), or a short list of third-party script hosts I load but don't ship.&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;const EXTENSION_SCHEMES = new Set([
  &amp;quot;chrome-extension&amp;quot;, &amp;quot;moz-extension&amp;quot;, &amp;quot;safari-web-extension&amp;quot;,
  &amp;quot;safari-extension&amp;quot;, &amp;quot;webkit-masked-url&amp;quot;,
]);
const THIRD_PARTY_HOSTS = new Set([&amp;quot;www.googletagmanager.com&amp;quot;]);

function locations(stack) {
  const found = [];
  for (const m of stack.matchAll(/([A-Za-z0-9+.-]*):\/\/([^\s/)]*)(\/?)/g)) {
    found.push({ scheme: m[1].toLowerCase(), host: m[2].toLowerCase(), slash: m[3] === &amp;quot;/&amp;quot; });
  }
  if (stack.includes(&amp;quot;&amp;lt;anonymous code&amp;gt;&amp;quot;)) found.push({ scheme: &amp;quot;firefox-extension&amp;quot; });
  return found;
}

function isForeign(stack) {
  const locs = locations(stack);
  return locs.length &amp;gt; 0 &amp;amp;&amp;amp; locs.every((l) =&amp;gt;
    EXTENSION_SCHEMES.has(l.scheme) || l.scheme === &amp;quot;firefox-extension&amp;quot; ||
    (l.scheme === &amp;quot;https&amp;quot; &amp;amp;&amp;amp; l.slash &amp;amp;&amp;amp; THIRD_PARTY_HOSTS.has(l.host)));
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Some details in that sketch are deliberate. A scheme like &lt;code&gt;blob:https&lt;/code&gt; or &lt;code&gt;webpack-internal&lt;/code&gt; reads as mine, because the comparison takes the whole scheme run, not its tail. A third-party host only counts when the host is followed directly by a slash, so a longer host that merely starts with the same name, a URL with a port or credentials, plain &lt;code&gt;http&lt;/code&gt;, or the host appearing inside a path all read as mine. When in doubt, the rule falls on the side that pages.&lt;/p&gt;

&lt;h3&gt;What still pages, on purpose&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;A rejection with no locations at all.&lt;/strong&gt; When my own &lt;code&gt;fetch&lt;/code&gt; fails and nothing catches it, Chrome rejects with a bare &lt;code&gt;TypeError&lt;/code&gt; that names no frame. Treating &quot;no location&quot; as foreign would hide that.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Anything caught by my error boundary or the boot path.&lt;/strong&gt; The foreign rule only applies to the two window-level traps. If an extension manages to take down rendering, that is an outage, whoever's fault it is.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Message lists.&lt;/strong&gt; I never drop an error by its wording alone, with one exception (the stackless WebKit extension-API wording above, which my app cannot produce). &lt;q&gt;Cannot read properties of null (reading 'type')&lt;/q&gt; is a common extension error and also, word for word, a bug I could write tomorrow.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;truncation&quot;&gt;The truncation trap&lt;/h2&gt;
&lt;p&gt;Beacons are small on purpose: the stack travels as at most six lines and 800 characters. V8 spends the first line on the &lt;code&gt;Name: message&lt;/code&gt; header, and some messages are long or span several lines (validation libraries pretty-print, &lt;code&gt;DataCloneError&lt;/code&gt; quotes source code). Those pushed every frame out of the window. Since a stack that names no location used to count as unattributed, my own crash in Chrome could be silenced simply by having a verbose message.&lt;/p&gt;
&lt;p&gt;The fix was to have the client judge the &lt;strong&gt;full&lt;/strong&gt; stack before trimming it, and then, when the trimmed window would contain no frame of mine, to promote the first frame of mine into it with a marker for the skipped lines:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;TypeError: Failed to execute 'structuredClone' on 'Window': …
    at chrome-extension://abc/inject.js:1:2041
    ... 14 lines skipped ...
    at https://example.com/assets/editor-3f9a1c.js:2:18803&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The promoted line is budgeted first, so no later clamp can cut its location in half. And clamps never split a UTF-16 surrogate pair: an orphaned half serializes as an escape that strict JSON parsers refuse, and the whole beacon is lost.&lt;/p&gt;

&lt;h2 id=&quot;evidence&quot;&gt;Send evidence, not a verdict&lt;/h2&gt;
&lt;p&gt;The easiest implementation would have been a boolean in the beacon: &lt;code&gt;foreign: true&lt;/code&gt;. I didn't do it, and this is the lesson I'd pass on to anyone with a service worker. Clients run old bundles for a long time. Every rule you put in the client is frozen into each deployed version for as long as some visitor keeps that version cached, and you can't fix it. The MetaMask page came from a bundle more than three weeks old.&lt;/p&gt;
&lt;p&gt;So the client sends &lt;em&gt;evidence&lt;/em&gt; (the kind of error and a stack window that includes a frame of mine if one exists), and the server decides. The rules exist in both places, but the server is the authority, and both implementations are tested against one shared file of hand-written vectors so they can't drift apart. When I add an extension scheme, I add it to the client, the server and the vector file in one change, and only after a real beacon shows it.&lt;/p&gt;
&lt;p&gt;Foreign errors aren't thrown away. They're logged at info level with a &lt;code&gt;frames=&lt;/code&gt; field (&lt;code&gt;extension&lt;/code&gt;, &lt;code&gt;third-party&lt;/code&gt;, &lt;code&gt;page&lt;/code&gt; or &lt;code&gt;mixed&lt;/code&gt;), so I can still count them. And real crashes carry the same field, so a page that says &lt;code&gt;frames=mixed&lt;/code&gt; tells me up front that someone else's code was in the stack beside mine.&lt;/p&gt;

&lt;h2 id=&quot;takeaways&quot;&gt;What I'd tell someone setting up error reporting&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Your global error handlers report code you don't own. Plan for it on day one.&lt;/li&gt;
&lt;li&gt;Attribute by &lt;em&gt;every&lt;/em&gt; location in the stack, not the top frame.&lt;/li&gt;
&lt;li&gt;Keep a stack with no locations on the paging side.&lt;/li&gt;
&lt;li&gt;Judge the full stack before truncating it.&lt;/li&gt;
&lt;li&gt;Put the decision on the server, because old clients never fully go away.&lt;/li&gt;
&lt;li&gt;Add a rule only when a real report shows you need it, and keep a test vector for it.&lt;/li&gt;
&lt;/ul&gt;</content>
    <category term="JavaScript" />
    <category term="Observability" />
    <category term="Web" />
  </entry>
  <entry>
    <title>When a deploy deletes the chunk an open tab still needs</title>
    <link href="https://faizo.net/writing/spa-deploy-skew-chunk-errors/" />
    <id>https://faizo.net/writing/spa-deploy-skew-chunk-errors/</id>
    <published>2026-11-09T00:00:00Z</published>
    <updated>2026-11-09T00:00:00Z</updated>
    <summary>&quot;Failed to fetch dynamically imported module&quot; after a deploy: why code-split apps hit it, how to recover safely, and how to tell a stale tab from a bad release.</summary>
    <content type="html">&lt;p&gt;If you ship a code-split single-page app, you will eventually see this in your error reports:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;TypeError: Failed to fetch dynamically imported module: https://example.com/assets/Gallery-4b1f0c2e.js&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;It usually means nothing is broken. A tab loaded version A of your app, you deployed version B, the host removed A's files, and then the tab tried to lazy-load a piece of A that no longer exists. In &lt;a href=&quot;/projects/dweeb/&quot;&gt;DWEEB&lt;/a&gt; this paged me repeatedly in its first months: first during boot, then after boot when a tab that had been open for hours opened the template gallery.&lt;/p&gt;
&lt;p&gt;The fix is not one trick. It is a handful of layers, each covering a case the others can't, and a way of reporting that can tell &quot;this visitor's tab is old&quot; from &quot;the release I just shipped is broken&quot;. This article walks through all of them.&lt;/p&gt;

&lt;h2 id=&quot;why&quot;&gt;Why it happens&lt;/h2&gt;
&lt;p&gt;Bundlers like Vite emit content-hashed chunk names, so every release has a different set of file names. Two facts about the host then do the damage. GitHub Pages, where DWEEB's front end lives, replaces the whole site on each deploy, so the previous release's chunks are gone the moment the new one is live. And the HTML page that points at those chunks is cached briefly (around ten minutes on Pages). So there are two ways to end up asking for a file that doesn't exist:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;A long-lived tab&lt;/strong&gt; keeps running the old code and lazy-loads an old chunk after the deploy.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A fresh load during the cache window&lt;/strong&gt; gets the old HTML from an edge cache, which names chunks that were just deleted.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;layers&quot;&gt;The layers&lt;/h2&gt;
&lt;h3&gt;1. Let a service worker keep the old release&lt;/h3&gt;
&lt;p&gt;A precaching service worker stores every chunk of the release it installed, so a tab it controls can lazy-load old chunks long after the host deleted them. One gap is easy to miss: by default, the page that &lt;em&gt;installs&lt;/em&gt; the worker isn't controlled by it, so a first visit stays unprotected until it is closed. Setting &lt;code&gt;clientsClaim: true&lt;/code&gt; fixes that. It's safe even when you prompt users before updating, because an &lt;em&gt;updated&lt;/em&gt; worker still waits, so it never takes over a tab running an older release.&lt;/p&gt;

&lt;h3&gt;2. Recover a failed boot automatically, but carefully&lt;/h3&gt;
&lt;p&gt;If the failure happens while the app is booting, there is nothing on screen to lose yet, so an automatic recovery is fine. Mine is a short ladder run from the boot promise's &lt;code&gt;catch&lt;/code&gt;:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Reload the page.&lt;/li&gt;
&lt;li&gt;If that boots the same broken shell (under a service worker a reload is answered from its cache, so it can), unregister the service workers and navigate to the same URL with a one-off query parameter that bypasses every cache, then strip the parameter again on the next boot.&lt;/li&gt;
&lt;li&gt;If that fails too, show a plain notice with a button, instead of a page stuck on &quot;Loading…&quot;.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Each rung has guards, and every one of them came from a bug. Progress is recorded in &lt;code&gt;sessionStorage&lt;/code&gt; and read back before a navigation happens, so the ladder can never loop (no storage means no automatic step at all). The record is keyed on the &lt;strong&gt;build id&lt;/strong&gt;, not the version number: DWEEB's &lt;code&gt;package.json&lt;/code&gt; had said &lt;code&gt;1.0.0&lt;/code&gt; for every release since launch, so &quot;once per version&quot; quietly meant &quot;once per tab, ever&quot;. There's also an absolute cap of four automatic navigations per tab in ten minutes, independent of the build, for the case where two builds alternate behind a CDN. And no automatic navigation happens after the app reports itself ready, because that would throw away someone's unsaved work.&lt;/p&gt;

&lt;h3&gt;3. After boot, ask, never reload&lt;/h3&gt;
&lt;p&gt;Once the editor is up, a person may be halfway through a message. Every lazily loaded surface is wrapped in a small error boundary that recognises exactly this failure and shows a &quot;refresh to update&quot; dialog while the rest of the app keeps running. Drafts autosave and the URL is preserved, so the refresh loses nothing, but the person chooses when. Two details matter. The dialog's dismiss action must fully unmount the failed surface, or the cached rejected import is re-thrown on every render. And anything that isn't a stale-chunk failure is re-thrown to the top-level boundary rather than being dressed up as an update.&lt;/p&gt;

&lt;h3&gt;4. Background imports handle their own failures&lt;/h3&gt;
&lt;p&gt;The service-worker registration itself was lazy-loaded a few seconds after first paint. In a background tab, browser timer throttling can delay that by hours, until after a deploy has removed the chunk. Nothing on screen was waiting for it, but the unhandled rejection paged me anyway. Fire-and-forget imports now get their own &lt;code&gt;catch&lt;/code&gt; that reports a handled, non-paging event.&lt;/p&gt;

&lt;h2 id=&quot;diagnosis&quot;&gt;The message is a symptom, not a diagnosis&lt;/h2&gt;
&lt;p&gt;Here is the part that took longest to get right. Every browser produces the same error text for &lt;em&gt;any&lt;/em&gt; failed module fetch. A visitor whose connection dropped during boot looks byte-for-byte identical to deploy skew, and both look identical to a broken release. I was paged for &quot;fatal&quot; chunk failures that named files the server was serving perfectly well: the requests had simply failed in transit, and the one recovery reload failed the same way.&lt;/p&gt;
&lt;p&gt;So before the client reports the serious case, it asks two questions, concurrently, with a four-second limit:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;async function diagnoseChunkFailure(chunkUrl) {
  const [chunk, shell] = await Promise.all([
    // Is the file really gone? Same-origin HEAD, no caches.
    probe(chunkUrl, { method: &amp;quot;HEAD&amp;quot;, cache: &amp;quot;no-store&amp;quot; }),
    // What does the host serve as the app shell right now?
    // An unknown query misses the service worker's cache.
    probe(&amp;quot;/?probe=&amp;quot; + crypto.randomUUID(), { cache: &amp;quot;no-store&amp;quot; }),
  ]);
  if (!chunk || chunk.status &amp;lt; 400 || chunk.status &amp;gt;= 500) return &amp;quot;chunk-unreachable&amp;quot;;
  if (!shell) return &amp;quot;shell-unverified&amp;quot;;
  return liveEntry(shell) === currentEntry() ? &amp;quot;broken-release&amp;quot; : &amp;quot;stale-tab&amp;quot;;
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Only a 4xx on the chunk &lt;em&gt;and&lt;/em&gt; a live shell that is this very build means the release I'm serving references a file it doesn't have. That is the only case that pages. Everything else is logged at info level and counted. Two implementation notes: probe the full URL from the original error, not a truncated copy (a clipped URL 404s and manufactures a false alarm), and make sure the probe itself can never reject, or its failure lands back in your own error handler.&lt;/p&gt;

&lt;h2 id=&quot;stale-clients&quot;&gt;Old clients never drain&lt;/h2&gt;
&lt;p&gt;A month after all of that shipped, the same tab paged me again. It was running a bundle 24 days old, from before the live-shell probe existed, so its reporter still sent the old &quot;fatal&quot; shape. With a service worker and a polite update prompt, some tabs simply never update. Waiting for them to drain is not a plan.&lt;/p&gt;
&lt;p&gt;The fix had to live where an old client can't overrule it: the server. Each build now stamps its id into the HTML:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-html&quot;&gt;&amp;lt;meta name=&amp;quot;app-build&amp;quot; content=&amp;quot;e699a38eec&amp;quot; /&amp;gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Crash beacons already carry the build id of the bundle that sent them. When a &quot;fatal&quot; chunk report arrives, the server reads the build id off its own front end (cached for five minutes) and, if the report came from a build that isn't live, logs it as a stale client instead of paging. A few rules keep that safe:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Nothing is learned from the beacon.&lt;/strong&gt; The server fetches its own configured origin. A forged beacon can at most claim to be the live build, which pages, which is the old behaviour.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Every failure fails open.&lt;/strong&gt; If the shell can't be fetched or has no marker, the answer is &quot;don't know&quot;, and the report pages as before.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The reader follows no redirects&lt;/strong&gt; and refuses a marker that isn't shaped like a build id, since the value ends up in a log line.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A fresher answer wins.&lt;/strong&gt; A current client that checked the live shell itself at the moment of the crash knows more than a five-minute-old server cache, so its verdict is never overruled.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;hollow&quot;&gt;The strangest one: a chunk that arrives empty&lt;/h2&gt;
&lt;p&gt;Much later, Firefox reported a crash that read like an ordinary bug: &lt;q&gt;can't access property &quot;parse&quot;, t is undefined&lt;/q&gt;. The module namespace the boot code read from was empty. Serving an empty body for that one chunk reproduced the report byte for byte, and so did writing an empty entry into the service worker's cache. That second reproduction explained why it kept happening: the precache library skips any URL it already has during install, so unregistering and re-registering the worker puts the damaged copy straight back, and unchanged chunks keep their hash across releases.&lt;/p&gt;
&lt;p&gt;A static import of an empty chunk fails at link time with a clear engine message. A dynamic &lt;code&gt;import()&lt;/code&gt; just hands back an empty namespace. So every boot-time namespace is now checked for the exports it should have, and the recovery ladder, before each step, deletes that URL from every Cache Storage cache and refetches it with &lt;code&gt;cache: &amp;quot;reload&amp;quot;&lt;/code&gt;. Tested in Firefox and Chromium, a damaged tab now heals in one reload without anyone noticing.&lt;/p&gt;

&lt;h2 id=&quot;summary&quot;&gt;Summary&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Expect old chunks to disappear. Let a service worker keep them, and claim the first visit too.&lt;/li&gt;
&lt;li&gt;Recover boot failures automatically with a bounded, per-build ladder. Never navigate away from work in progress.&lt;/li&gt;
&lt;li&gt;Key everything on a unique build id, never on a semver string someone forgets to bump.&lt;/li&gt;
&lt;li&gt;Treat &quot;failed to fetch module&quot; as a symptom. Probe the chunk and the live shell before calling it a broken release.&lt;/li&gt;
&lt;li&gt;Let the server, which knows what is live, decide whether old clients' reports matter.&lt;/li&gt;
&lt;/ul&gt;</content>
    <category term="Web" />
    <category term="Deployment" />
    <category term="Service workers" />
  </entry>
  <entry>
    <title>A dropped DNS packet that looked like a Discord outage</title>
    <link href="https://faizo.net/writing/dns-serve-stale-docker/" />
    <id>https://faizo.net/writing/dns-serve-stale-docker/</id>
    <published>2026-11-09T00:00:00Z</published>
    <updated>2026-11-09T00:00:00Z</updated>
    <summary>A 5-second &quot;connect timed out&quot; to discord.com was a DNS stall inside Docker. How one lost UDP packet stalls lookups, and how serving stale answers fixes it.</summary>
    <content type="html">&lt;p&gt;One evening my phone showed an error from DWEEB's API server:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;GET /api/guilds/…/webhooks  error=could not reach Discord: client error (Connect): operation timed out  latency=5001 ms&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Discord was fine. Its status page was green, other requests a second earlier and later had succeeded, and nothing in the request was unusual. The number that gave it away was &lt;code&gt;5001 ms&lt;/code&gt;: almost exactly my HTTP client's five-second connect timeout. Something had eaten the entire connect budget before a TCP connection was even attempted. That something was DNS.&lt;/p&gt;

&lt;h2 id=&quot;chain&quot;&gt;How one lost packet becomes a five-second stall&lt;/h2&gt;
&lt;p&gt;The server runs in Docker on a small VPS. A lookup for &lt;code&gt;discord.com&lt;/code&gt; from inside a container passes through four resolvers before anything leaves the machine, and none of the first three does what you'd hope:&lt;/p&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Layer&lt;/th&gt;&lt;th&gt;Caches?&lt;/th&gt;&lt;th&gt;What it does on a lost packet&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;glibc in the container&lt;/td&gt;&lt;td&gt;No&lt;/td&gt;&lt;td&gt;Waits, then retries (default timeout 5 s)&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;Docker's embedded DNS&lt;/td&gt;&lt;td&gt;No&lt;/td&gt;&lt;td&gt;Forwards to the host; abandons the forwarded query after 4 s&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;systemd-resolved on the host&lt;/td&gt;&lt;td&gt;Only within the record's TTL&lt;/td&gt;&lt;td&gt;On the version I run, re-sends an unanswered UDP query only after a fixed 5 s&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;The provider's two resolvers&lt;/td&gt;&lt;td&gt;Yes&lt;/td&gt;&lt;td&gt;Answer in milliseconds, when the packet arrives&lt;/td&gt;&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;So when one UDP datagram is dropped somewhere between the host and the provider's resolver, systemd-resolved won't ask again for five seconds, but Docker gives up at four. The lookup fails or stalls past four seconds, and the application's five-second connect timeout, which covers DNS &lt;em&gt;and&lt;/em&gt; TCP &lt;em&gt;and&lt;/em&gt; TLS, is spent by the lookup alone. The error says &quot;connect timed out&quot;, which points you at the network or at Discord, when the real fault is a resolver on your own host.&lt;/p&gt;
&lt;p&gt;Once I knew what to look for, the evidence was in the Docker daemon's journal a second before the alert:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[resolver] failed to query external DNS server … 127.0.0.53:53: i/o timeout question=discord.com&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Counting those lines showed 61 stalls in eight days, seven of them for &lt;code&gt;discord.com&lt;/code&gt;. Healthy lookups took 4 to 29 ms. Stalls were all four seconds or more. Nothing in between.&lt;/p&gt;

&lt;h2 id=&quot;host-fix&quot;&gt;Fix one: make the host resolver less fragile&lt;/h2&gt;
&lt;p&gt;The first fix belongs to the host: give systemd-resolved additional upstream servers so a single lost packet to one of them isn't a five-second wait. That reduced the rate. It can't make it zero, and it does nothing for the next machine I deploy to. The application needed to survive this on its own.&lt;/p&gt;
&lt;p&gt;I also considered the two quick application fixes and rejected both. Raising the connect timeout past the stall turns every stall into a slow request instead of a failed one, and in this incident the stall outlasted glibc's own retry too. Reclassifying connect failures as &quot;Discord's fault&quot; would silence a real problem: if my host genuinely can't resolve or reach Discord, I want to know.&lt;/p&gt;

&lt;h2 id=&quot;serve-stale&quot;&gt;Fix two: serve stale&lt;/h2&gt;
&lt;p&gt;DNS already has an answer for this situation. &lt;a href=&quot;https://www.rfc-editor.org/rfc/rfc8767&quot;&gt;RFC 8767&lt;/a&gt;, &quot;Serving Stale Data to Improve DNS Resiliency&quot;, describes resolvers answering from expired cache entries when the authoritative servers can't be reached. I applied the same idea inside the application, as the HTTP client's custom resolver:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Every connection still starts a fresh lookup, and a fresh answer always wins.&lt;/li&gt;
&lt;li&gt;If no answer arrives within &lt;strong&gt;1 second&lt;/strong&gt;, or the lookup fails outright, connect to the address from the &lt;strong&gt;last successful lookup&lt;/strong&gt; for that host, provided it is at most 24 hours old. Log that at info level.&lt;/li&gt;
&lt;li&gt;Let the slow lookup keep running in the background, so a late answer still refreshes the remembered address.&lt;/li&gt;
&lt;li&gt;If nothing is remembered (the process just started), keep waiting, but give up at &lt;strong&gt;4 seconds&lt;/strong&gt; with an error that says what happened.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;A simplified version of the resolver, using reqwest's &lt;code&gt;Resolve&lt;/code&gt; trait and Tokio:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-rust&quot;&gt;const FRESH_WAIT: Duration = Duration::from_secs(1);
const DEADLINE: Duration = Duration::from_secs(4);
const MAX_STALE: Duration = Duration::from_secs(24 * 60 * 60);
const CONNECT_TIMEOUT: Duration = Duration::from_secs(5);

// The ordering is the design. Check it at compile time.
const _: () = assert!(FRESH_WAIT.as_millis() &amp;lt; DEADLINE.as_millis());
const _: () = assert!(DEADLINE.as_millis() &amp;lt; CONNECT_TIMEOUT.as_millis());

async fn resolve(&amp;amp;self, host: String) -&amp;gt; Result&amp;lt;Vec&amp;lt;SocketAddr&amp;gt;, BoxError&amp;gt; {
    // Spawned, so a slow lookup outlives this call and still updates memory.
    let lookup = tokio::spawn(self.clone().lookup_and_remember(host.clone()));
    let mut lookup = std::pin::pin!(lookup);

    if let Ok(done) = tokio::time::timeout(FRESH_WAIT, &amp;amp;mut lookup).await {
        match done? {
            Ok(addrs) =&amp;gt; return Ok(addrs),
            Err(err) =&amp;gt; return self.remembered(&amp;amp;host).ok_or(err),
        }
    }
    if let Some(addrs) = self.remembered(&amp;amp;host) {
        tracing::info!(target: &amp;quot;dns&amp;quot;, %host, &amp;quot;no answer in 1s; dialing last good address&amp;quot;);
        return Ok(addrs);
    }
    match tokio::time::timeout(DEADLINE - FRESH_WAIT, lookup).await {
        Ok(done) =&amp;gt; done?,
        Err(_) =&amp;gt; Err(format!(
            &amp;quot;no answer for {host} within 4s, and no earlier answer to fall back on&amp;quot;
        ).into()),
    }
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;(&lt;code&gt;remembered&lt;/code&gt; returns the stored addresses only when they are younger than &lt;code&gt;MAX_STALE&lt;/code&gt;.)&lt;/p&gt;

&lt;h2 id=&quot;why-safe&quot;&gt;Why connecting to an old address is safe&lt;/h2&gt;
&lt;p&gt;The obvious worry with a stale address is connecting to the wrong machine. HTTPS takes care of that: &lt;strong&gt;TLS verifies the server's certificate against the hostname on every connection&lt;/strong&gt;, whatever IP address the socket happens to reach. If Discord had moved &lt;code&gt;discord.com&lt;/code&gt; to a new address and the old one now belonged to someone else, the handshake would fail, and the request would fail with a certificate error, which is the same outcome as the stall but faster. A stale address can fail to connect. It can't connect you to an impostor.&lt;/p&gt;
&lt;p&gt;The 24-hour cap is a sanity limit rather than a security one. Big API providers keep their front-end addresses stable for much longer than a day, but if a host has been unreachable through DNS for a whole day, a fresh failure is more useful than a stale success.&lt;/p&gt;

&lt;h2 id=&quot;results&quot;&gt;What changed&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;A DNS stall for a host the process has talked to before now costs about one second instead of failing the request, and leaves an info line I can grep for.&lt;/li&gt;
&lt;li&gt;A stall on a cold process still fails, still pages (it really is my host's problem), but at four seconds and with a message that names DNS, instead of a generic timeout that sent me looking at Discord.&lt;/li&gt;
&lt;li&gt;The timeouts are documented by an assertion, not a comment: wait for fresh answer, then fall back, then give up, all inside the connect timeout.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;I only put this resolver on the client that talks to Discord. Other clients in the system either have long enough budgets to ride out a stall late, or are short-lived plugin clients where the right fix is the host resolver. If you run anything latency-sensitive in Docker on a single host, it's worth grepping your daemon journal for &lt;q&gt;failed to query external DNS&lt;/q&gt; before you blame the API on the other end.&lt;/p&gt;</content>
    <category term="Operations" />
    <category term="DNS" />
    <category term="Rust" />
  </entry>
  <entry>
    <title>Three ways a reverse proxy invents a 502</title>
    <link href="https://faizo.net/writing/reverse-proxy-false-502s/" />
    <id>https://faizo.net/writing/reverse-proxy-false-502s/</id>
    <published>2026-11-09T00:00:00Z</published>
    <updated>2026-11-09T00:00:00Z</updated>
    <summary>Caddy logged 502s for requests my backend had answered. Unread request bodies, container restarts and HTTP/3 clients hanging up, and how to fix each.</summary>
    <content type="html">&lt;p&gt;My production stack is simple: &lt;a href=&quot;https://caddyserver.com/&quot;&gt;Caddy&lt;/a&gt; terminates TLS and reverse-proxies to a handful of Rust services in containers. Any error-level log line is forwarded to a Discord channel on my phone, so a 502 is an alert. Over a few months I was paged for 502s that were not failures of my backend at all. Caddy had produced each one itself, for three different reasons. Each is easy to fix once you can recognise it.&lt;/p&gt;

&lt;h2 id=&quot;unread-bodies&quot;&gt;1. The backend answered without reading the request body&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Symptom:&lt;/strong&gt; an occasional 502 on a path you don't even serve, usually a POST from a vulnerability scanner (&lt;code&gt;POST /lib/vendor/phpunit/…&lt;/code&gt; was mine). Caddy's error log mentions &lt;code&gt;write: broken pipe&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;What happens:&lt;/strong&gt; the Rust web framework I use, axum, answers an unknown route with 404 straight away, without reading the request body. The HTTP server can't reuse a connection whose body wasn't consumed, so it closes it. Caddy is still busy streaming the body upstream, gets a broken pipe, throws away the perfectly good 404 and reports a 502 of its own, at error level.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Fix:&lt;/strong&gt; make the fallback handler read (and discard) the body before answering. The connection stays healthy, the client gets the honest 404, and nothing is logged anywhere:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-rust&quot;&gt;async fn not_found(body: axum::body::Bytes) -&amp;gt; StatusCode {
    // Reading the body (bounded by the router's body-size limit) keeps the
    // connection reusable, so the proxy delivers this 404 instead of a 502.
    drop(body);
    StatusCode::NOT_FOUND
}

let app = Router::new()
    .route(&amp;quot;/api/…&amp;quot;, post(handler))
    .fallback(not_found)          // register before the layers that should wrap it
    .layer(DefaultBodyLimit::max(256 * 1024))
    .layer(TraceLayer::new_for_http());&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Two details. Buffering into &lt;code&gt;Bytes&lt;/code&gt; is bounded by the body-size limit, so a huge body is rejected rather than read forever. And in axum, &lt;code&gt;Router::layer&lt;/code&gt; only wraps what was added above it, so the fallback must be registered before the layers you want it to pass through.&lt;/p&gt;

&lt;h2 id=&quot;restarts&quot;&gt;2. The upstream was restarting&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Symptom:&lt;/strong&gt; a burst of 502s at deploy time, with &lt;code&gt;dial tcp …: connect: connection refused&lt;/code&gt; in Caddy's log.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;What happens:&lt;/strong&gt; recreating a container leaves a gap of a second or so where its address refuses connections. Caddy dials it, gets refused, and answers 502. I measured it: during one forced recreate of a service, &lt;strong&gt;6 of 200&lt;/strong&gt; probe requests failed. For a Discord app that's worse than an alert. An interaction that lands in that gap shows the member &quot;This interaction failed&quot;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Fix:&lt;/strong&gt; let Caddy retry dials for a short window. A snippet keeps it consistent across every upstream:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-caddyfile&quot;&gt;(upstream_retry) {
	lb_try_duration 2s
	lb_try_interval 200ms
}

api.example.com {
	reverse_proxy app:8080 {
		import upstream_retry
	}
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;After the change, the same test gave &lt;strong&gt;0 of 200&lt;/strong&gt; failures and no error lines at all, since a retry that succeeds logs nothing. This is safe because of what is being retried: a &lt;em&gt;dial&lt;/em&gt; failure means no connection was made, so the upstream never saw the request and can't have processed it. An upstream that answers 500 still passes straight through. And a service that is really down still produces a 502, just about two seconds later, so a real outage still pages. I keep the window well under three seconds because Discord interactions must be answered within three.&lt;/p&gt;
&lt;p&gt;One caveat: this only covers hops Caddy makes. My API server also calls an internal dispatcher service directly over the container network, so that client has its own short re-dial loop for refused connections, with the same &quot;dial failures only&quot; rule.&lt;/p&gt;

&lt;h2 id=&quot;http3&quot;&gt;3. An HTTP/3 client hung up&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Symptom:&lt;/strong&gt; 502s on ordinary GET requests (&lt;code&gt;/api/capabilities&lt;/code&gt;, &lt;code&gt;/auth/me&lt;/code&gt;) over &lt;code&gt;HTTP/3.0&lt;/code&gt;, mostly from Firefox and iOS Safari, each taking almost exactly &lt;strong&gt;two seconds&lt;/strong&gt;, with an error like:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;reading: Application error 0x100 (remote)&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;What happens:&lt;/strong&gt; &lt;code&gt;0x100&lt;/code&gt; is &lt;code&gt;H3_NO_ERROR&lt;/code&gt;: the browser closed the stream because it no longer needed the response, typically a navigation or a closed tab. Caddy only recognises a client going away when Go reports a plain context cancellation. The QUIC library it uses cancels the request context with the QUIC close as the cause, which is neither, so Caddy treats it as an upstream failure. Since it's a GET, Caddy's default retry policy kicks in: it retries every 200 ms against a client that is gone until the two-second try window runs out, then logs a 502 at error level. The two-second duration in the log is the retry window, not backend latency.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Fix:&lt;/strong&gt; this one I handle in the alerting, not the proxy. Disabling GET retries would undo fix number two. The alert forwarder drops these lines when all of the following hold:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;the error is an HTTP/3 application close marked &lt;code&gt;(remote)&lt;/code&gt;, meaning the client closed it. A &lt;code&gt;(local)&lt;/code&gt; close is my side aborting, which still pages;&lt;/li&gt;
&lt;li&gt;the request's duration is short (I use 15 seconds as the cut-off). A client that gave up after waiting a long time for an answer my backend never sent is a real problem, and it still pages.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Chromium can hang up with a different spelling. When its network stack drops all its connections at once, the log reads &lt;code&gt;INTERNAL_ERROR (remote): 16:net error&lt;/code&gt;. I mute that exact string under the same duration rule. Any other transport-level error code from a browser could mean my QUIC stack actually broke the protocol, so it still pages.&lt;/p&gt;

&lt;h2 id=&quot;alerting&quot;&gt;A note on the alert forwarder itself&lt;/h2&gt;
&lt;p&gt;Muting by text is dangerous if you do it in the wrong order. My forwarder originally checked for the word &quot;panicked&quot; before it had parsed the log level. My crash-report endpoint is public and logs some fields verbatim at info level, so anyone could have triggered a &quot;PANIC&quot; page by sending an error message that contained the word. Now every content match runs &lt;em&gt;after&lt;/em&gt; the level is parsed, and info, debug and trace lines can never page. A genuine Rust panic is printed to stderr without any log prefix, so it still matches.&lt;/p&gt;
&lt;p&gt;The forwarder also has an offline test mode that runs the classifier over a file of real production lines, and I run it on the server before restarting the service. Log formats drift. In one case a change to the span prefix meant crash reports silently stopped paging for four weeks, and nobody noticed because silence looks like health.&lt;/p&gt;

&lt;h2 id=&quot;checklist&quot;&gt;Checklist&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Drain request bodies in your fallback handler.&lt;/li&gt;
&lt;li&gt;Retry upstream &lt;em&gt;dials&lt;/em&gt;, briefly, at the proxy. Nothing else.&lt;/li&gt;
&lt;li&gt;Learn your proxy's spelling of &quot;the client went away&quot; for each protocol you serve, and filter it with a duration bound.&lt;/li&gt;
&lt;li&gt;Parse the log level before matching any content.&lt;/li&gt;
&lt;li&gt;Test the alert classifier against real lines whenever you change it.&lt;/li&gt;
&lt;/ul&gt;</content>
    <category term="Operations" />
    <category term="Caddy" />
    <category term="HTTP" />
  </entry>
  <entry>
    <title>Discord keeps your webhook's avatar_url, not the image, so host it forever</title>
    <link href="https://faizo.net/writing/discord-webhook-avatar-url-hosting/" />
    <id>https://faizo.net/writing/discord-webhook-avatar-url-hosting/</id>
    <published>2026-11-09T00:00:00Z</published>
    <updated>2026-11-09T00:00:00Z</updated>
    <summary>Discord stores your webhook's avatar_url, not the image. Why uploaded avatars break later, the silent size limits, and how to host them permanently.</summary>
    <content type="html">&lt;p&gt;When you execute a Discord webhook you can override how the message looks: &lt;code&gt;username&lt;/code&gt; sets the display name and &lt;code&gt;avatar_url&lt;/code&gt; sets the picture. It feels like an upload. It isn't. Discord stores the &lt;strong&gt;URL string&lt;/strong&gt; with the message and loads the image through its media proxy when the message is displayed. If the URL stops serving an image, every message that used it loses its avatar, and there is no way to point an existing message at a new picture: editing a webhook message can change its content, but not its username or avatar.&lt;/p&gt;
&lt;p&gt;In &lt;a href=&quot;/projects/dweeb/&quot;&gt;DWEEB&lt;/a&gt; people kept asking to upload an avatar from their computer rather than paste a link. This is what I learned building that, including two &quot;cheap&quot; designs that don't work.&lt;/p&gt;

&lt;h2 id=&quot;tried&quot;&gt;Two ideas that don't work&lt;/h2&gt;
&lt;h3&gt;A short-lived image store&lt;/h3&gt;
&lt;p&gt;The first idea was to accept the upload, keep it for a day or so, and let Discord fetch it once. That works for exactly as long as Discord's media cache holds the image. After that, a message that is supposed to be permanent (a server's rules, a role menu, an announcement) shows a broken avatar. Since the URL is what's stored, the lifetime of the hosting &lt;em&gt;is&lt;/em&gt; the lifetime of the avatar.&lt;/p&gt;
&lt;h3&gt;Discord's own attachment CDN&lt;/h3&gt;
&lt;p&gt;The clever idea was to post the image as an attachment in a throwaway webhook message, keep the &lt;code&gt;cdn.discordapp.com/attachments/…&lt;/code&gt; link Discord returns, and delete the message. Discord would host the image for free. Unfortunately Discord &lt;strong&gt;rejects its own attachment URLs&lt;/strong&gt; in &lt;code&gt;avatar_url&lt;/code&gt;, both with and without the signed &lt;code&gt;?ex=&amp;amp;is=&amp;amp;hm=&lt;/code&gt; query parameters attachment links now carry. This is a known limitation (discussed in the discord-api-docs issue tracker, #6657), not a bug in your request. Don't spend an afternoon on it.&lt;/p&gt;

&lt;h2 id=&quot;silent-limits&quot;&gt;The limits Discord doesn't tell you about&lt;/h2&gt;
&lt;p&gt;Two more things fail silently, with no error from the API:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Large images.&lt;/strong&gt; Above roughly 1024 pixels on a side, Discord quietly shows the default webhook avatar instead of yours. The request succeeds and the message posts normally.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Animated GIFs.&lt;/strong&gt; A webhook avatar doesn't animate. You get a still frame at best.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Silent failures are the worst kind for a tool whose whole job is &quot;what you see is what gets posted&quot;, so the fix had to make sure no oversized or animated image ever reached Discord.&lt;/p&gt;

&lt;h2 id=&quot;design&quot;&gt;The design: the browser does the pixels, the server just keeps them&lt;/h2&gt;
&lt;h3&gt;In the browser&lt;/h3&gt;
&lt;p&gt;Image processing is cheap in the browser and expensive on a small server, so all of it happens client-side. The uploaded image is center-cropped to a square (Discord shows avatars in a circle, so a square source loses the least), scaled down to 256×256, and re-encoded:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;async function prepareAvatar(file) {
  const bitmap = await createImageBitmap(file); // first frame only for GIFs
  const side = Math.min(bitmap.width, bitmap.height);
  const size = Math.min(256, side);
  const canvas = new OffscreenCanvas(size, size);
  const ctx = canvas.getContext(&amp;quot;2d&amp;quot;);
  ctx.drawImage(
    bitmap,
    (bitmap.width - side) / 2, (bitmap.height - side) / 2, side, side,
    0, 0, size, size,
  );
  const png = await canvas.convertToBlob({ type: &amp;quot;image/png&amp;quot; });
  if (hasTransparency(ctx, size) || png.size &amp;lt;= PNG_SIZE_BUDGET) return png;
  return canvas.convertToBlob({ type: &amp;quot;image/jpeg&amp;quot;, quality: 0.9 });
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The format choice matters more than it looks. If the image has &lt;em&gt;any&lt;/em&gt; transparent pixels it stays PNG, because JPEG has no alpha channel and transparent areas turn black, which looks awful inside Discord's circular crop. Opaque images stay PNG while they're small and switch to JPEG beyond a size budget.&lt;/p&gt;

&lt;h3&gt;On the server&lt;/h3&gt;
&lt;p&gt;The server never decodes an image. It reads the header bytes of the format it was given to check the type and dimensions, and refuses anything else. For PNG that is a fixed position in the file:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-rust&quot;&gt;fn png_dimensions(bytes: &amp;amp;[u8]) -&amp;gt; Option&amp;lt;(u32, u32)&amp;gt; {
    const SIGNATURE: &amp;amp;[u8] = b&amp;quot;\x89PNG\r\n\x1a\n&amp;quot;;
    // 8-byte signature, then the IHDR chunk: length(4) &amp;quot;IHDR&amp;quot;(4) width(4) height(4)
    if bytes.len() &amp;lt; 24 || &amp;amp;bytes[..8] != SIGNATURE || &amp;amp;bytes[12..16] != b&amp;quot;IHDR&amp;quot; {
        return None;
    }
    let width = u32::from_be_bytes(bytes[16..20].try_into().ok()?);
    let height = u32::from_be_bytes(bytes[20..24].try_into().ok()?);
    Some((width, height))
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;JPEG takes a little more work (walk the segments to the first start-of-frame marker), but it's still a few dozen lines with no image library. That keeps the server's dependency list and attack surface small, and the browser has already done the actual resizing.&lt;/p&gt;

&lt;h3&gt;Storage that never forgets&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Content-addressed.&lt;/strong&gt; The file is stored and served under its SHA-256 hash, as &lt;code&gt;/api/avatar/&amp;lt;sha256&amp;gt;.png&lt;/code&gt;. The same image uploaded twice is stored once.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Immutable.&lt;/strong&gt; Since the URL names the exact bytes, it is served with a one-year &lt;code&gt;immutable&lt;/code&gt; cache header. Discord's media proxy, browsers and CDNs can all cache it forever.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Anonymous reads.&lt;/strong&gt; Discord's fetcher carries no credentials, so serving is public. Uploading is not: only signed-in users can upload, so the endpoint can't become a free image host.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Never swept.&lt;/strong&gt; There is no garbage collector. Deleting a row would silently break a live message somewhere, and I can't know which messages still exist. Growth is bounded by deduplication, a per-file size cap and a total row cap. When the cap is reached, uploads get a &quot;try again later&quot; error. Old images are never evicted to make room.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;input&quot;&gt;Keep the field a URL&lt;/h2&gt;
&lt;p&gt;One last decision: the upload doesn't replace the avatar URL field, it fills it in. People still paste existing CDN links, and DWEEB supports placeholders like &lt;code&gt;{server_icon}&lt;/code&gt; that resolve to the server's icon at send time. An upload is just a convenient way to get a URL that will last.&lt;/p&gt;

&lt;h2 id=&quot;summary&quot;&gt;Summary&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;avatar_url&lt;/code&gt; stores a link. Whatever hosts it must outlive every message that uses it.&lt;/li&gt;
&lt;li&gt;Discord's own attachment links aren't accepted as avatars.&lt;/li&gt;
&lt;li&gt;Stay at or below 1024×1024 and don't count on animation. 256×256 is plenty.&lt;/li&gt;
&lt;li&gt;Preserve transparency with PNG. Discord crops avatars to a circle.&lt;/li&gt;
&lt;li&gt;Content-address, cache immutably, and never delete.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The same rule applies to any image URL you put into a Discord message that is meant to last, including embed thumbnails and Components V2 media. If you're linking to it rather than uploading it as an attachment, you are now its host.&lt;/p&gt;</content>
    <category term="Discord API" />
    <category term="Webhooks" />
    <category term="Rust" />
  </entry>
  <entry>
    <title>Chrome's page translation versus your virtual DOM</title>
    <link href="https://faizo.net/writing/browser-translation-virtual-dom-crash/" />
    <id>https://faizo.net/writing/browser-translation-virtual-dom-crash/</id>
    <published>2026-11-09T00:00:00Z</published>
    <updated>2026-11-09T00:00:00Z</updated>
    <summary>Why Chrome's page translation makes Preact and React throw &quot;Failed to execute 'insertBefore' on 'Node'&quot;, and a narrow DOM patch that fixes it safely.</summary>
    <content type="html">&lt;p&gt;One morning a crash report from &lt;a href=&quot;/projects/dweeb/&quot;&gt;DWEEB&lt;/a&gt; said the whole editor had fallen over to its error screen with this:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;NotFoundError: Failed to execute 'insertBefore' on 'Node': The node before which the new node is to be inserted is not a child of this node.&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The top frames were &lt;code&gt;insert&lt;/code&gt; and &lt;code&gt;diffChildren&lt;/code&gt;, inside the vendor bundle, meaning inside Preact itself. Preact doesn't have bugs like that on ordinary pages. The page wasn't ordinary: the visitor had asked Chrome to translate it.&lt;/p&gt;

&lt;h2 id=&quot;what-translation-does&quot;&gt;What browser translation does to your DOM&lt;/h2&gt;
&lt;p&gt;Chrome's built-in translation (the same machinery as the Google Translate website widget) works on text nodes. For each text node it translates, it inserts a wrapper and &lt;strong&gt;moves the original text node inside it&lt;/strong&gt;:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-html&quot;&gt;&amp;lt;!-- Before --&amp;gt;
&amp;lt;button&amp;gt;&amp;lt;svg …&amp;gt;&amp;lt;/svg&amp;gt;Send&amp;lt;/button&amp;gt;

&amp;lt;!-- After translation --&amp;gt;
&amp;lt;button&amp;gt;&amp;lt;svg …&amp;gt;&amp;lt;/svg&amp;gt;&amp;lt;font&amp;gt;&amp;lt;font&amp;gt;Enviar&amp;lt;/font&amp;gt;&amp;lt;/font&amp;gt;&amp;lt;/button&amp;gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;That's harmless until your framework touches that part of the tree again. A virtual DOM library keeps references to the real DOM nodes it created. When it needs to insert a new element, it calls &lt;code&gt;parent.insertBefore(newNode, referenceNode)&lt;/code&gt; with the sibling it remembers as the reference. But the remembered text node now lives inside a &lt;code&gt;&amp;lt;font&amp;gt;&lt;/code&gt;, not inside &lt;code&gt;parent&lt;/code&gt;, so the browser throws. Preact guards against a reference that has been &lt;em&gt;detached&lt;/em&gt; from the document (&lt;code&gt;!oldDom.parentNode&lt;/code&gt;), but not against one that has been &lt;em&gt;moved&lt;/em&gt; somewhere else. React has had a long-standing issue about the same class of problem with Google Translate.&lt;/p&gt;
&lt;p&gt;In practice it takes a render that inserts an element next to a bare text child. A conditional icon appearing beside a label, or an emoji element appearing mid-paragraph, is enough. A single click and the app is gone.&lt;/p&gt;

&lt;h2 id=&quot;reproduce&quot;&gt;Reproducing it without a translator&lt;/h2&gt;
&lt;p&gt;You don't need to drive the translation feature to test this. Wrapping one rendered text node the way the translator does is enough:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;function simulateTranslation(element) {
  const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT);
  const text = walker.nextNode();
  const outer = document.createElement(&amp;quot;font&amp;quot;);
  const inner = document.createElement(&amp;quot;font&amp;quot;);
  text.parentNode.insertBefore(outer, text);
  outer.appendChild(inner);
  inner.appendChild(text); // the original node moves; the framework still holds it
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Then trigger a render that inserts a sibling before or after that text, and you get the exact error from the report.&lt;/p&gt;

&lt;h2 id=&quot;options&quot;&gt;The options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Turn translation off&lt;/strong&gt; with &lt;code&gt;translate=&amp;quot;no&amp;quot;&lt;/code&gt; on the root. That trades a crash for an app the visitor explicitly asked to read in their own language and now can't. They didn't do anything wrong.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Wrap every text node in a span&lt;/strong&gt; so the framework's references are elements the translator leaves alone. That works, but you have to apply it to every piece of text in the app forever, including text you don't control.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Make the two DOM methods that throw tolerate a moved node.&lt;/strong&gt; Preact has no hook around DOM insertion, so this means patching &lt;code&gt;Node.prototype&lt;/code&gt;. It sounds alarming, which is why the rule I set for the patch matters more than the patch itself.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;patch&quot;&gt;A patch that only acts where the browser would throw&lt;/h2&gt;
&lt;p&gt;The patch changes behaviour &lt;strong&gt;only in the exact situation where the native call would otherwise throw&lt;/strong&gt;. Every working code path in the app runs exactly as before.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;const nativeInsertBefore = Node.prototype.insertBefore;
const nativeRemoveChild = Node.prototype.removeChild;

Node.prototype.insertBefore = function (node, ref) {
  if (ref instanceof Node &amp;amp;&amp;amp; ref.parentNode !== this) {
    // Walk up from the stale reference to the ancestor that IS our child.
    // The translator's wrapper stands exactly where the text used to be,
    // so inserting before it preserves the intended order.
    let anchor = ref;
    while (anchor &amp;amp;&amp;amp; anchor.parentNode !== this) anchor = anchor.parentNode;
    if (anchor) {
      reportDesyncOnce(this, ref);
      return nativeInsertBefore.call(this, node, anchor);
    }
  }
  return nativeInsertBefore.call(this, node, ref); // throws natively if still invalid
};

Node.prototype.removeChild = function (child) {
  if (child instanceof Node &amp;amp;&amp;amp; child.parentNode !== this) {
    // Not our child any more: someone else moved it. Leave it alone.
    reportDesyncOnce(this, child);
    return child;
  }
  return nativeRemoveChild.call(this, child);
};&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Some choices are deliberate:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Insert before the ancestor, not at the end.&lt;/strong&gt; Appending would be simpler, but it would put the new icon &lt;em&gt;after&lt;/em&gt; its label. Walking up to the wrapper keeps the order the app intended.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code&gt;removeChild&lt;/code&gt; does nothing for a foreign child.&lt;/strong&gt; It doesn't go looking for the node and remove it from wherever it lives now. That node belongs to the translator.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Bad arguments still throw.&lt;/strong&gt; If my code passes something that isn't a node, it still gets the native &lt;code&gt;TypeError&lt;/code&gt;. A real bug of mine must stay loud.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Install it before the first render&lt;/strong&gt;, and after the crash reporter, because it reports through it.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The cost is measurable but irrelevant: about 100 nanoseconds per &lt;code&gt;insertBefore&lt;/code&gt; in a microbenchmark that does nothing else, which disappears next to layout.&lt;/p&gt;

&lt;h2 id=&quot;reporting&quot;&gt;Reporting it so a real bug can't hide behind it&lt;/h2&gt;
&lt;p&gt;A patch that swallows DOM errors could also hide my own mistakes, for example code that moves nodes behind the framework's back. So the guard reports once per page, as a distinct, non-paging event, and the report carries the two facts that tell the cases apart:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;the tag the stale node was found under (&lt;code&gt;FONT&lt;/code&gt; for Chrome's translator);&lt;/li&gt;
&lt;li&gt;any translator markers on the document: Chrome adds the &lt;code&gt;translated-ltr&lt;/code&gt; or &lt;code&gt;translated-rtl&lt;/code&gt; class to &lt;code&gt;&amp;lt;html&amp;gt;&lt;/code&gt;, and Microsoft's translator adds &lt;code&gt;_msttexthash&lt;/code&gt; attributes.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;A report reading &lt;code&gt;parent=FONT translator=google&lt;/code&gt; is a browser rewriting the page, and nothing needs doing. A report with &lt;code&gt;translator=none&lt;/code&gt; under an ordinary tag means the guard is covering for a bug of mine, and I go and look.&lt;/p&gt;
&lt;p&gt;One deployment detail: the server that receives crash reports had to learn the new event type &lt;em&gt;before&lt;/em&gt; the client started sending it. An older server would have treated the unknown type as a crash and paged me for every translated page view.&lt;/p&gt;

&lt;h2 id=&quot;takeaway&quot;&gt;Takeaway&lt;/h2&gt;
&lt;p&gt;If your app has visitors who don't read your language, some of them translate it, and your framework's assumptions about owning the DOM will eventually meet a rewritten tree. You can stop them translating, or you can make the two methods that throw tolerate the one situation translation creates, and measure how often it happens. I chose the second. The people who translate the page are trying to use the product.&lt;/p&gt;</content>
    <category term="JavaScript" />
    <category term="Preact" />
    <category term="Web" />
  </entry>
  <entry>
    <title>A stale browser tab deleted four hours of saved drafts</title>
    <link href="https://faizo.net/writing/localstorage-multiple-tabs/" />
    <id>https://faizo.net/writing/localstorage-multiple-tabs/</id>
    <published>2026-11-09T00:00:00Z</published>
    <updated>2026-11-09T00:00:00Z</updated>
    <summary>Two tabs, one localStorage key, and a save that wrote an old list over newer data. Making browser storage safe across tabs, plus two IndexedDB traps.</summary>
    <content type="html">&lt;p&gt;A user wrote in: they had saved four drafts in &lt;a href=&quot;/projects/dweeb/&quot;&gt;DWEEB&lt;/a&gt; over an afternoon, and now the list showed only two old ones plus the one they had just saved. Four hours of work, gone. Nothing had been deleted, nothing had errored, and the save had &quot;worked&quot;.&lt;/p&gt;
&lt;p&gt;It took a few minutes to guess and a headless browser to prove: they had two tabs open.&lt;/p&gt;

&lt;h2 id=&quot;bug&quot;&gt;The bug&lt;/h2&gt;
&lt;p&gt;Browser-saved drafts lived in one &lt;code&gt;localStorage&lt;/code&gt; key holding a JSON array. The app kept that array in a state store, loaded once at startup, and saving did the obvious thing:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;// The bug: write this tab's in-memory view back as the whole list.
save(record) {
  const entries = [record, ...this.entries];
  localStorage.setItem(KEY, JSON.stringify(entries));
  this.entries = entries;
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Every tab of the same origin shares one &lt;code&gt;localStorage&lt;/code&gt;, but each tab has its own copy of &lt;code&gt;this.entries&lt;/code&gt;. So:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Tab A is opened in the morning. It loads two drafts into memory.&lt;/li&gt;
&lt;li&gt;The user works in tab B all afternoon and saves four more. Storage now holds six.&lt;/li&gt;
&lt;li&gt;They go back to tab A and save. Tab A writes its record plus &lt;em&gt;its&lt;/em&gt; two, and replaces six drafts with three.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The in-memory copy is not the data. It is one tab's &lt;em&gt;view&lt;/em&gt; of the data, and it goes stale the moment another tab writes.&lt;/p&gt;

&lt;h2 id=&quot;fix&quot;&gt;The fix: read, modify, write&lt;/h2&gt;
&lt;p&gt;Every mutation now re-reads the stored list, applies its one change and writes that back. The in-memory copy is only ever updated from what was written:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;function mutate(change) {
  let current;
  try {
    const raw = localStorage.getItem(KEY);
    current = raw ? JSON.parse(raw) : [];
  } catch {
    // Unreadable (blocked storage, corrupt JSON): refuse the write rather
    // than overwrite a list we couldn't see.
    return false;
  }
  const next = change(current);
  localStorage.setItem(KEY, JSON.stringify(next));
  store.setEntries(next);
  return true;
}

const save = (record) =&amp;gt; mutate((list) =&amp;gt; [record, ...list.filter((r) =&amp;gt; r.id !== record.id)]);
const remove = (id) =&amp;gt; mutate((list) =&amp;gt; list.filter((r) =&amp;gt; r.id !== id));&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;localStorage&lt;/code&gt; operations are synchronous, and in practice a read-then-write inside one task doesn't interleave with another tab's write, so this closes the window that matters. (If you need real transactions across tabs, use IndexedDB or the Web Locks API.)&lt;/p&gt;
&lt;p&gt;Two more pieces keep the &lt;em&gt;view&lt;/em&gt; honest:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Listen for the &lt;code&gt;storage&lt;/code&gt; event.&lt;/strong&gt; It fires in every other same-origin tab when one tab writes, so each tab can re-read and update its list. Keep unchanged records as the same objects, so the UI doesn't re-render everything for one change.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Re-read on &lt;code&gt;pageshow&lt;/code&gt; with &lt;code&gt;persisted&lt;/code&gt; set.&lt;/strong&gt; A page restored from the back/forward cache missed every storage event fired while it was frozen.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;There's also a subtle case. If another tab deletes a draft that &lt;em&gt;this&lt;/em&gt; tab has open in its editor, the record disappears from the list, but this tab may still be using it. Images in that draft live in IndexedDB, which is also shared between tabs. Those entries stay in a &quot;deleted elsewhere&quot; set for the lifetime of the page, so the image cleanup won't remove files the open editor still shows.&lt;/p&gt;
&lt;p&gt;A test now replays the incident exactly (two stores sharing one storage, an old tab saving last) and fails on the old code.&lt;/p&gt;

&lt;h2 id=&quot;getitem-throws&quot;&gt;Trap: &lt;code&gt;getItem&lt;/code&gt; can throw&lt;/h2&gt;
&lt;p&gt;A related bug took the whole app down for a different visitor. &lt;code&gt;localStorage.getItem&lt;/code&gt; doesn't just return &lt;code&gt;null&lt;/code&gt; when storage is unavailable. When a user has &lt;em&gt;blocked&lt;/em&gt; site data, merely accessing &lt;code&gt;window.localStorage&lt;/code&gt; or calling &lt;code&gt;getItem&lt;/code&gt; throws a &lt;code&gt;SecurityError&lt;/code&gt;. DWEEB read a &quot;have we shown the welcome gallery?&quot; flag inside a component's state initializer, so the throw escaped rendering and landed on the error screen, over a browser privacy setting. Now every storage access is wrapped, and an unreadable flag reads as &quot;never&quot;, which is the safe first-visit answer.&lt;/p&gt;

&lt;h2 id=&quot;indexeddb&quot;&gt;Two IndexedDB traps from the same feature&lt;/h2&gt;
&lt;p&gt;Images people add to a draft are stored as blobs in IndexedDB, and a cleanup pass deletes blobs that no draft references any more. Both of these bit me there.&lt;/p&gt;
&lt;h3&gt;&lt;code&gt;IDBCursor.delete()&lt;/code&gt; throws on a key cursor&lt;/h3&gt;
&lt;p&gt;To find orphans without loading every image into memory, the cleanup iterated with &lt;code&gt;openKeyCursor()&lt;/code&gt;, which yields keys only. Calling &lt;code&gt;cursor.delete()&lt;/code&gt; on a key cursor throws &lt;code&gt;InvalidStateError&lt;/code&gt;. The spec only allows it on a value cursor. Worse, an exception thrown inside a transaction's event handler &lt;strong&gt;aborts the whole transaction&lt;/strong&gt;. The same transaction was also loading the user's live images, so one orphan both produced a crash report and silently dropped every image in the open draft. The fix is to issue a separate &lt;code&gt;store.delete(key)&lt;/code&gt; request per orphan, and to call &lt;code&gt;preventDefault()&lt;/code&gt; on each request's error event so a single failed delete can't abort the rest.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;const request = store.openKeyCursor();
request.onsuccess = () =&amp;gt; {
  const cursor = request.result;
  if (!cursor) return;
  if (!referenced.has(cursor.key)) {
    const del = store.delete(cursor.key);       // not cursor.delete()
    del.onerror = (event) =&amp;gt; event.preventDefault(); // don't abort the transaction
  }
  cursor.continue();
};&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;For tests, the &lt;a href=&quot;https://github.com/dumbmatter/fakeIndexedDB&quot;&gt;fake-indexeddb&lt;/a&gt; package enforces this spec restriction, so the bug reproduces in a unit test without a browser.&lt;/p&gt;
&lt;h3&gt;Cleanup judged by one tab is wrong for all of them&lt;/h3&gt;
&lt;p&gt;Each tab decided what counted as an orphan from &lt;em&gt;its own&lt;/em&gt; editor and its own view of the saved drafts. Delete a draft in one tab, and that tab's cleanup would remove the images another tab had just loaded from it. They'd come back as &quot;missing&quot; after a reload. Now loading and pruning are separate steps. Loading always happens. Pruning stored bytes only happens when a quick &lt;code&gt;BroadcastChannel&lt;/code&gt; ping finds no other open tab of the app. Memory is still freed immediately in each tab. Disk is only cleaned by a tab that knows it's alone.&lt;/p&gt;

&lt;h2 id=&quot;rules&quot;&gt;Rules I now follow for browser storage&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Shared storage plus per-tab memory means memory is a cache. Never write it back as the source of truth.&lt;/li&gt;
&lt;li&gt;Mutate by reading, changing one thing and writing. Refuse to write over data you couldn't read.&lt;/li&gt;
&lt;li&gt;Follow other tabs with the &lt;code&gt;storage&lt;/code&gt; event and &lt;code&gt;pageshow&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Treat every storage access as something that can throw.&lt;/li&gt;
&lt;li&gt;Before deleting shared data, ask whether another tab could still be using it.&lt;/li&gt;
&lt;/ul&gt;</content>
    <category term="JavaScript" />
    <category term="Web" />
    <category term="State management" />
  </entry>
  <entry>
    <title>A short page is not the last page: counting a Discord bot's servers</title>
    <link href="https://faizo.net/writing/discord-current-user-guilds-pagination/" />
    <id>https://faizo.net/writing/discord-current-user-guilds-pagination/</id>
    <published>2026-11-09T00:00:00Z</published>
    <updated>2026-11-09T00:00:00Z</updated>
    <summary>My bot's server count sat at 199 for weeks, then jumped to 344. Paginating GET /users/@me/guilds correctly, and a per-token rate limit I raced myself.</summary>
    <content type="html">&lt;p&gt;DWEEB's backend asks Discord which servers its bot is in. It needs that to show whether the bot is present in a server before offering features that require it, and it publishes the total to the app's listing page on Top.gg. For weeks the number sat at 198 or 199. Then, on a day with no deploy, it jumped from 199 to 344 in a single refresh.&lt;/p&gt;
&lt;p&gt;The number had never been 199. My pagination had been wrong the whole time.&lt;/p&gt;

&lt;h2 id=&quot;endpoint&quot;&gt;The endpoint&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;GET /users/@me/guilds&lt;/code&gt; returns the servers the current user (or bot) is in, at most 200 per request, ordered by ID. You page forward with &lt;code&gt;after&lt;/code&gt; set to the last ID you received. The documentation notes that 200 is the most servers a regular user can join, so for &lt;em&gt;user&lt;/em&gt; tokens one request is enough. Bots have no such limit, so for a bot you have to page.&lt;/p&gt;

&lt;h2 id=&quot;bug&quot;&gt;The bug: stopping on a short page&lt;/h2&gt;
&lt;p&gt;My loop stopped when a page came back with fewer than 200 entries, which is the usual way to detect the end of a list:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-rust&quot;&gt;// Wrong: a page shorter than the limit was taken to mean &amp;quot;no more pages&amp;quot;.
loop {
    let page = get_guilds(after, 200).await?;
    ids.extend(page.iter().map(|g| g.id));
    if page.len() &amp;lt; 200 { break; }
    after = page.last().map(|g| g.id);
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The endpoint doesn't guarantee that. It can return fewer than the limit while there are more results after the page. That would explain both the plateau and the sudden jump: the first page kept coming back one or two short of 200, and the loop never asked for the second page until one day a full page came back. During those weeks, about 145 servers that had the bot showed &quot;bot not present&quot; in DWEEB, and the public listing showed a number short by more than 40%.&lt;/p&gt;
&lt;p&gt;The fix costs one extra request per walk: &lt;strong&gt;only an empty page ends the list&lt;/strong&gt;.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-rust&quot;&gt;loop {
    let page = get_guilds(after, 200).await?;
    let Some(last) = page.last() else { break };  // empty page: done
    after = Some(last.id);
    ids.extend(page.iter().map(|g| g.id));
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;I've found other Discord endpoints that are tempting to paginate the same way. Unless the documentation explicitly promises that a short page is the last one, I page until empty.&lt;/p&gt;

&lt;h2 id=&quot;dont-publish-zero&quot;&gt;If the read fails, publish nothing&lt;/h2&gt;
&lt;p&gt;The server count is pushed to Top.gg every 30 minutes, because Top.gg shows whatever number a bot last posted. Two rules keep that honest:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;A failed read is skipped, never posted as zero.&lt;/strong&gt; An earlier helper folded errors into an empty set, which is fine for &quot;is the bot in this one server?&quot; but would publish &quot;0 servers&quot; to a public page if used for the count. A stale count lags. A zero is visibly wrong and drops the listing to the bottom of every sort.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The reporter never logs at error level.&lt;/strong&gt; A Top.gg outage isn't worth waking anyone. Failures are logged at info and retried on the next tick. Only a rejected token earns a warning.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;rate-limit&quot;&gt;The same endpoint, the user side: a rate-limit race&lt;/h2&gt;
&lt;p&gt;The web app also calls this endpoint with each &lt;em&gt;user's&lt;/em&gt; OAuth token, to list the servers they can manage. My logs showed about 1,100 &quot;Discord rate-limited&quot; warnings in 29 days, each followed by a wait of about one second, always on routes that load when a page opens.&lt;/p&gt;
&lt;p&gt;The cause was in my own code. Two different authorization checks each needed the user's server list: one for &quot;servers you can manage&quot; and one for &quot;servers you're a member of&quot;. They are two views of the same response from Discord, but each fetched and cached it separately. Opening the server library triggered both at once, both called Discord with the same token, and the second one got a 429 and slept for the &lt;code&gt;Retry-After&lt;/code&gt; time. Discord holds this route to roughly one call per second per token, so a page load was racing itself.&lt;/p&gt;
&lt;p&gt;The fix was to make the server list &lt;strong&gt;one fetch, one cache entry&lt;/strong&gt;, shared by every view that derives from it, with concurrent callers waiting for the same in-flight request. The login callback also warms that cache, so the first page load after signing in doesn't fetch at all. One caveat about my own evidence: I worked this out from the code and the shape of the logs, not from Discord's rate-limit headers, because I wasn't logging those yet. That's the next section.&lt;/p&gt;

&lt;h2 id=&quot;logging&quot;&gt;Logging rate limits without leaking secrets&lt;/h2&gt;
&lt;p&gt;Discord's responses include rate-limit headers that tell you what you hit: &lt;code&gt;X-RateLimit-Bucket&lt;/code&gt;, &lt;code&gt;X-RateLimit-Scope&lt;/code&gt; (user, global or shared) and, on a 429, how long to wait. Logging them makes the next investigation take minutes instead of a day. The catch is that the obvious companion field, the request path, can contain a secret: a webhook's execute URL is &lt;code&gt;/webhooks/{id}/{token}&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;So the warning logs a &lt;strong&gt;route shape&lt;/strong&gt; built from an allow-list of path patterns, never the raw path:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-rust&quot;&gt;fn route_shape(path: &amp;amp;str) -&amp;gt; &amp;amp;'static str {
    // Only known shapes are named. Anything else is logged as &amp;quot;other&amp;quot;,
    // so a token-bearing path can never reach the logs.
    match path.split('/').filter(|s| !s.is_empty()).collect::&amp;lt;Vec&amp;lt;_&amp;gt;&amp;gt;().as_slice() {
        [&amp;quot;users&amp;quot;, &amp;quot;@me&amp;quot;, &amp;quot;guilds&amp;quot;] =&amp;gt; &amp;quot;/users/@me/guilds&amp;quot;,
        [&amp;quot;guilds&amp;quot;, _, &amp;quot;channels&amp;quot;] =&amp;gt; &amp;quot;/guilds/{id}/channels&amp;quot;,
        [&amp;quot;guilds&amp;quot;, _, &amp;quot;roles&amp;quot;] =&amp;gt; &amp;quot;/guilds/{id}/roles&amp;quot;,
        [&amp;quot;webhooks&amp;quot;, ..] =&amp;gt; &amp;quot;/webhooks/{id}/{token}&amp;quot;,
        _ =&amp;gt; &amp;quot;other&amp;quot;,
    }
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The same caution applies to error messages. Some HTTP clients append the request URL to their error text (reqwest's &lt;code&gt;Display&lt;/code&gt; adds &lt;code&gt;for url (…)&lt;/code&gt;). One of my scheduled-post workers stored that text as the failure reason shown in the UI, which put a webhook token in plain text into a field the rest of the server could read. Error messages that leave the process are now built from the error's cause chain with the URL removed, and stored reasons are scrubbed on startup.&lt;/p&gt;

&lt;h2 id=&quot;summary&quot;&gt;Summary&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Page &lt;code&gt;GET /users/@me/guilds&lt;/code&gt; with &lt;code&gt;after&lt;/code&gt; until a page is empty, not until a page is short.&lt;/li&gt;
&lt;li&gt;Never publish a count from a failed read.&lt;/li&gt;
&lt;li&gt;Fetch a user's server list once and derive every view from it. Don't let two checks race for the same per-token budget.&lt;/li&gt;
&lt;li&gt;Log Discord's rate-limit bucket and scope, with the route reduced to an allow-listed shape.&lt;/li&gt;
&lt;li&gt;Strip URLs from error text before it is logged or stored.&lt;/li&gt;
&lt;/ul&gt;</content>
    <category term="Discord API" />
    <category term="Rust" />
    <category term="Rate limits" />
  </entry>
  <entry>
    <title>Opening the Discord app from a web page without opening the website too</title>
    <link href="https://faizo.net/writing/open-discord-app-from-web-link/" />
    <id>https://faizo.net/writing/open-discord-app-from-web-link/</id>
    <published>2026-11-09T00:00:00Z</published>
    <updated>2026-11-09T00:00:00Z</updated>
    <summary>An &quot;Open in Discord&quot; button should launch the app or the website, not both. The discord:// race, cold starts on Windows, and each browser's popup limits.</summary>
    <content type="html">&lt;p&gt;After you post a message with &lt;a href=&quot;/projects/dweeb/&quot;&gt;DWEEB&lt;/a&gt;, the confirmation has an &lt;strong&gt;Open in Discord&lt;/strong&gt; button. The ideal behaviour is simple to state: if the Discord desktop app is installed, open the message there; if not, open it on discord.com in a new tab. Browsers give you no direct way to ask whether an app is installed, so every implementation of this is a race. Mine shipped with a bug that opened &lt;em&gt;both&lt;/em&gt;, and fixing it meant learning how long each browser lets a click stay &quot;a click&quot;.&lt;/p&gt;

&lt;h2 id=&quot;race&quot;&gt;The race&lt;/h2&gt;
&lt;p&gt;The approach most sites use:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;On click, navigate to the app's URL scheme, here &lt;code&gt;discord://-/channels/{guild}/{channel}/{message}&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;If the app is installed, the operating system hands the link to it, and the browser window loses focus as the app comes to the front.&lt;/li&gt;
&lt;li&gt;If the page still has focus after a grace period, assume nothing handled the link and open the web URL.&lt;/li&gt;
&lt;/ol&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;let cancelPending = null;

export function openInDiscord(appUrl, webUrl) {
  cancelPending?.();                       // a repeat click replaces the previous race

  let appTookOver = false;
  const onHide = () =&amp;gt; { appTookOver = true; };
  const onVisibility = () =&amp;gt; { if (document.hidden) appTookOver = true; };
  window.addEventListener(&amp;quot;blur&amp;quot;, onHide);
  document.addEventListener(&amp;quot;visibilitychange&amp;quot;, onVisibility);

  const timer = setTimeout(() =&amp;gt; {
    cleanup();
    if (!appTookOver &amp;amp;&amp;amp; document.hasFocus()) window.open(webUrl, &amp;quot;_blank&amp;quot;, &amp;quot;noopener&amp;quot;);
  }, graceMs());

  function cleanup() {
    clearTimeout(timer);
    window.removeEventListener(&amp;quot;blur&amp;quot;, onHide);
    document.removeEventListener(&amp;quot;visibilitychange&amp;quot;, onVisibility);
    cancelPending = null;
  }
  cancelPending = cleanup;

  window.location.href = appUrl;
}&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Note that the test is &quot;the page kept focus &lt;em&gt;for the whole window&lt;/em&gt;&quot;, not &quot;the page has focus when the timer fires&quot;. A blur at any point, even if focus comes back before the timer, means the app took over. The visibility check covers platforms where the page is hidden rather than blurred.&lt;/p&gt;

&lt;h2 id=&quot;bug&quot;&gt;The bug: 800 milliseconds&lt;/h2&gt;
&lt;p&gt;The first version used an 800 ms grace period. It felt responsive in testing, on a machine where Discord was already running. On Windows, with the browser set to always allow &lt;code&gt;discord://&lt;/code&gt; links without asking, a Discord client that is starting cold regularly takes &lt;em&gt;more&lt;/em&gt; than 800 ms to come to the front. The timer fired first, the web tab opened, and a moment later the app appeared as well. People got two copies of their message on screen and reasonably assumed the button was broken.&lt;/p&gt;
&lt;p&gt;A longer window fixes it, but there's a hard limit on how long the window can be, and it's different in every browser.&lt;/p&gt;

&lt;h2 id=&quot;activation&quot;&gt;The constraint: user activation&lt;/h2&gt;
&lt;p&gt;Browsers only allow &lt;code&gt;window.open&lt;/code&gt; as a direct result of a user action. The HTML standard calls this &lt;strong&gt;transient user activation&lt;/strong&gt;: a click grants it, and it expires after a browser-defined interval. Open a window after it expires and the popup blocker stops you. The fallback runs from a timer, so the grace period has to end while the click's activation is still valid.&lt;/p&gt;
&lt;div class=&quot;table-wrap&quot;&gt;&lt;table&gt;
&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Engine&lt;/th&gt;&lt;th&gt;What allows the delayed open&lt;/th&gt;&lt;th&gt;Grace period I use&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;Chromium (Chrome, Edge…)&lt;/td&gt;&lt;td&gt;Transient activation lasts about 5 seconds&lt;/td&gt;&lt;td&gt;2,500 ms&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;Firefox&lt;/td&gt;&lt;td&gt;Transient activation lasts about 5 seconds by default&lt;/td&gt;&lt;td&gt;2,500 ms&lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td&gt;Safari (WebKit)&lt;/td&gt;&lt;td&gt;Passes a click's activation through &lt;code&gt;setTimeout&lt;/code&gt; only for delays up to 1 second&lt;/td&gt;&lt;td&gt;at most 1,000 ms&lt;/td&gt;&lt;/tr&gt;
&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;p&gt;On Chromium and Firefox, 2.5 seconds comfortably covers a cold app start and stays well inside the activation window. On Safari, a longer delay doesn't just fail quietly: a blocked popup there can turn into navigating the current tab to the web URL, which would take the person away from the page they were on. So Safari keeps a window of one second or less, and accepts that a very slow app start may occasionally open both.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;function graceMs() {
  // WebKit only forwards user activation through timers of &amp;lt;= 1s.
  return isWebKit() ? 1000 : 2500;
}&lt;/code&gt;&lt;/pre&gt;

&lt;h2 id=&quot;repeat-clicks&quot;&gt;Repeat clicks&lt;/h2&gt;
&lt;p&gt;Someone who clicks, sees nothing for a second and clicks again would, with a naïve implementation, start a second race and possibly get two fallback tabs. A module-level cancel function (&lt;code&gt;cancelPending&lt;/code&gt; above) makes each click supersede the previous one instead of stacking.&lt;/p&gt;

&lt;h2 id=&quot;testing&quot;&gt;Testing it&lt;/h2&gt;
&lt;p&gt;The behaviour depends on timing and focus, which unit tests handle well with fake timers. My test file covers the cases that matter: app takes over (blur before the deadline, so no web tab), app absent (focus held, so a web tab opens), blur then refocus inside the window (still counts as the app), a repeat click (one race, not two), and the per-engine grace periods. The file's comments explain why the numbers are what they are. It's the kind of constant someone will want to &quot;tighten for snappiness&quot; in a year, and the test is there to stop them.&lt;/p&gt;

&lt;h2 id=&quot;summary&quot;&gt;Summary&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;A custom-scheme deep link with a web fallback is always a race. Detect the app by focus loss during the whole window.&lt;/li&gt;
&lt;li&gt;Size the window for a cold app start, not a warm one. 800 ms was too short on Windows.&lt;/li&gt;
&lt;li&gt;Stay inside each engine's user-activation window: about 5 s for Chromium and Firefox, 1 s for timers in Safari.&lt;/li&gt;
&lt;li&gt;Let repeat clicks cancel the previous race.&lt;/li&gt;
&lt;/ul&gt;</content>
    <category term="JavaScript" />
    <category term="Discord" />
    <category term="Browsers" />
  </entry>
  <entry>
    <title>Stripe Checkout: a 100%-off promo code that doesn't ask for a card</title>
    <link href="https://faizo.net/writing/stripe-checkout-free-promo-code-no-card/" />
    <id>https://faizo.net/writing/stripe-checkout-free-promo-code-no-card/</id>
    <published>2026-11-09T00:00:00Z</published>
    <updated>2026-11-09T00:00:00Z</updated>
    <summary>A 100%-off-forever promo code still showed a card form in Stripe Checkout. Why, and the API details that let your own promo field skip the card.</summary>
    <content type="html">&lt;p&gt;I wanted to hand out a few free plans for &lt;a href=&quot;/projects/dweeb/&quot;&gt;DWEEB&lt;/a&gt;: a promotion code for 100% off, forever. Someone with the code should be able to subscribe without entering a card, since they will never be charged. I created the coupon and the code in Stripe, opened Checkout, typed the code into Checkout's promo field, and watched the total drop to $0.00, right above a card form that still had to be filled in.&lt;/p&gt;
&lt;p&gt;Here's why, and the setup that works.&lt;/p&gt;

&lt;h2 id=&quot;why&quot;&gt;Why Checkout still asks for a card&lt;/h2&gt;
&lt;p&gt;Stripe Checkout can skip card collection for a subscription, but only when two things are true:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;the session is created with &lt;code&gt;payment_method_collection=if_required&lt;/code&gt;, and&lt;/li&gt;
&lt;li&gt;the amount due is already zero &lt;strong&gt;when the session is created&lt;/strong&gt;.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;A code typed into Checkout's own promotion-code box is applied &lt;em&gt;after&lt;/em&gt; the session exists. The session was built expecting payment, and the card form doesn't go away when the total changes. So a free code entered there discounts the total to zero and still demands a card. There's no way to warn the customer from your side, because the session was already created with card collection on.&lt;/p&gt;
&lt;p&gt;The conclusion is that the discount has to arrive &lt;em&gt;with&lt;/em&gt; the session-creation request. That means your own promo-code field, sent to your server, applied server-side.&lt;/p&gt;

&lt;h2 id=&quot;setup&quot;&gt;The setup that works&lt;/h2&gt;
&lt;p&gt;The pricing dialog has its own &quot;Have a promo code?&quot; field. The server looks the code up, checks it, and creates the Checkout Session with the discount attached:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;POST /v1/checkout/sessions
  mode=subscription
  line_items[0][price]=price_…
  line_items[0][quantity]=1
  discounts[0][promotion_code]=promo_…          # resolved from the customer's code
  payment_method_collection=if_required          # only when the code covers everything
  success_url=…
  cancel_url=…&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Some rules matter here.&lt;/p&gt;
&lt;h3&gt;Never send &lt;code&gt;allow_promotion_codes&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;allow_promotion_codes=true&lt;/code&gt; shows Checkout's own promo box, and it's mutually exclusive with &lt;code&gt;discounts&lt;/code&gt;: Stripe rejects a session that carries both. Leaving it off also removes the trap above. Checkout's box sits right next to the price and looks official, so that's where people type codes. When it doesn't exist, your field is the only way in, and it's always the one that works. Nothing is lost: partial-discount codes work through your field too, and still collect a card as they should. Because it's now the only entrance, I show the field openly rather than hiding it behind a link.&lt;/p&gt;
&lt;h3&gt;Skip the card only when the code really covers everything&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;if_required&lt;/code&gt; is set only when the coupon is &lt;code&gt;percent_off &amp;gt;= 100&lt;/code&gt; &lt;em&gt;and&lt;/em&gt; &lt;code&gt;duration = forever&lt;/code&gt;. A 100%-off coupon that lasts three months still needs the card its first real renewal will charge. A fixed &lt;code&gt;amount_off&lt;/code&gt; that happens to equal today's price is excluded too: if the price ever goes up, that customer has no card on file and the renewal fails.&lt;/p&gt;
&lt;h3&gt;Accept only the customer-facing code&lt;/h3&gt;
&lt;p&gt;The client sends the text the customer typed, never a coupon ID or a &lt;code&gt;promo_…&lt;/code&gt; ID. Promotion codes are the objects Stripe designed to be handed out, with their own redemption limits. The server resolves the code and re-checks it rather than trusting a filter alone:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;GET /v1/promotion_codes?code=FREEFOREVER&amp;amp;active=true&amp;amp;limit=1&amp;amp;expand[]=data.promotion.coupon

checks: active, expires_at (if set) in the future,
        times_redeemed &amp;lt; max_redemptions (if set), coupon.valid&lt;/code&gt;&lt;/pre&gt;

&lt;h2 id=&quot;api-version&quot;&gt;The API-version trap: where the coupon lives&lt;/h2&gt;
&lt;p&gt;This one cost me a confusing hour. Older Stripe API versions return the coupon inline at the top level of a promotion code (&lt;code&gt;promotion_code.coupon&lt;/code&gt;). On the API version my account uses, the coupon is referenced under &lt;code&gt;promotion.coupon&lt;/code&gt;, and only as an ID unless you expand it (&lt;code&gt;expand[]=data.promotion.coupon&lt;/code&gt; in a list request). My first parser only read the top-level field, found nothing, and concluded that a live, valid, 100%-off-forever code was &lt;em&gt;expired&lt;/em&gt;. I only found out by querying Stripe by hand.&lt;/p&gt;
&lt;p&gt;Two lessons came out of that:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Read both shapes&lt;/strong&gt; when a field moved between API versions, especially in a codebase that might be pinned to a different version than your dashboard.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Not being able to read the coupon is not a rejection.&lt;/strong&gt; If the coupon can't be parsed, the code is still applied (Stripe validates it at session creation anyway). It just doesn't qualify for card-free checkout. Refusing a valid code because your parser failed is the worse failure.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;applies-to&quot;&gt;Product restrictions are expandable too&lt;/h2&gt;
&lt;p&gt;A coupon can be limited to specific products with &lt;code&gt;applies_to&lt;/code&gt;. That field is &lt;strong&gt;expandable&lt;/strong&gt;, so a plain &lt;code&gt;GET /v1/coupons/{id}&lt;/code&gt; omits it, and a restricted coupon looks unrestricted. Ask with &lt;code&gt;?expand[]=applies_to&lt;/code&gt;, and never conclude &quot;no restriction&quot; from the field's absence. If a session is created with a code whose restrictions don't fit the price, Stripe rejects it, and your customer sees an error from a pricing card that promised them a discount.&lt;/p&gt;

&lt;h2 id=&quot;errors&quot;&gt;Errors are the customer's, not yours&lt;/h2&gt;
&lt;p&gt;In my setup, any 5xx from my API server pages me. A mistyped code and a code that doesn't apply to the chosen plan are both ordinary customer situations, so they return 4xx with a clear message (&quot;That promo code isn't valid&quot;, &quot;That promo code can't be used on this plan&quot;). To do that, the Stripe client has to keep Stripe's status code rather than flattening every failure into a string: a 4xx from Stripe about the discount is a customer problem, a 5xx or a network failure is not.&lt;/p&gt;
&lt;p&gt;The checkout route also has its own rate limit, since every call creates a Stripe session and may look up a code. Expiry dates and redemption limits stay in Stripe, which already enforces them. I don't rebuild them.&lt;/p&gt;

&lt;h2 id=&quot;summary&quot;&gt;Summary&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;To skip the card, the session must be created with the discount already applied and &lt;code&gt;payment_method_collection=if_required&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Use your own promo field and &lt;code&gt;discounts[0][promotion_code]&lt;/code&gt;. Don't send &lt;code&gt;allow_promotion_codes&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Only skip the card for coupons that are 100% off and last forever.&lt;/li&gt;
&lt;li&gt;Expect &lt;code&gt;promotion.coupon&lt;/code&gt; versus top-level &lt;code&gt;coupon&lt;/code&gt; depending on API version, and expand what you need.&lt;/li&gt;
&lt;li&gt;Return customer mistakes as 4xx.&lt;/li&gt;
&lt;/ul&gt;</content>
    <category term="Stripe" />
    <category term="Payments" />
    <category term="Rust" />
  </entry>
  <entry>
    <title>An event parameter named &quot;source&quot; rewrote my GA4 traffic attribution</title>
    <link href="https://faizo.net/writing/ga4-source-parameter-attribution/" />
    <id>https://faizo.net/writing/ga4-source-parameter-attribution/</id>
    <published>2026-11-09T00:00:00Z</published>
    <updated>2026-11-09T00:00:00Z</updated>
    <summary>17% of my GA4 sessions were credited to traffic sources called &quot;gallery&quot; and &quot;seo&quot;. The cause was an event parameter name. Which names to avoid.</summary>
    <content type="html">&lt;p&gt;I use Google Analytics 4 on &lt;a href=&quot;/projects/dweeb/&quot;&gt;DWEEB&lt;/a&gt; to answer a few product questions: where visitors come from, which templates they pick, whether the code export gets used. In September 2026 I was reading the traffic acquisition report and found two traffic sources I had never heard of: &lt;strong&gt;gallery&lt;/strong&gt; and &lt;strong&gt;seo&lt;/strong&gt;. Together they made up the entire &quot;Unassigned&quot; channel, 565 of 3,279 sessions in the period, about 17%.&lt;/p&gt;
&lt;p&gt;Nobody was sending traffic from a site called &quot;gallery&quot;. Those were values of a custom event parameter.&lt;/p&gt;

&lt;h2 id=&quot;cause&quot;&gt;The cause&lt;/h2&gt;
&lt;p&gt;When someone applied a template, the app sent an event like this:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;gtag(&amp;quot;event&amp;quot;, &amp;quot;template_applied&amp;quot;, { template: &amp;quot;server-rules&amp;quot;, source: &amp;quot;gallery&amp;quot; });&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;source&lt;/code&gt; meant &quot;which part of the UI the template was applied from&quot;: the gallery, or a link from one of the site's guide pages (&lt;code&gt;seo&lt;/code&gt;). To GA4, though, &lt;code&gt;source&lt;/code&gt; is not just any name. Together with &lt;code&gt;medium&lt;/code&gt;, &lt;code&gt;campaign&lt;/code&gt;, &lt;code&gt;term&lt;/code&gt; and &lt;code&gt;content&lt;/code&gt;, it is one of the names GA reads as &lt;strong&gt;manual campaign information&lt;/strong&gt;. In my property, an event carrying &lt;code&gt;source: &amp;quot;gallery&amp;quot;&lt;/code&gt; re-attributed the session to a traffic source named &quot;gallery&quot;, overwriting the search engine or AI assistant that had actually sent the visitor. Since those sessions had no matching medium, they landed in &quot;Unassigned&quot;.&lt;/p&gt;
&lt;p&gt;The fix was a rename, plus a guard so it can't happen again:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;// Names GA4 can treat as campaign information. Never use them as event parameters.
const RESERVED = new Set([&amp;quot;source&amp;quot;, &amp;quot;medium&amp;quot;, &amp;quot;campaign&amp;quot;, &amp;quot;term&amp;quot;, &amp;quot;content&amp;quot;]);

export function track(name, params = {}) {
  for (const key of Object.keys(params)) {
    if (RESERVED.has(key)) {
      throw new Error(`analytics: &amp;quot;${key}&amp;quot; is reserved by GA4 attribution; rename it`);
    }
  }
  window.gtag?.(&amp;quot;event&amp;quot;, name, params);
}

track(&amp;quot;template_applied&amp;quot;, { template: &amp;quot;server-rules&amp;quot;, applied_from: &amp;quot;gallery&amp;quot; });&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;A unit test also checks every allowed parameter list against the five names, so the mistake fails CI rather than quietly corrupting a month of reports. The data from before the fix still undercounts Organic Search and AI-assistant referrals by that 17%, and I note that whenever I compare across that date.&lt;/p&gt;
&lt;p&gt;The general lesson: &lt;strong&gt;analytics parameter names are a shared namespace&lt;/strong&gt;. Check a vendor's reserved and automatically collected names before inventing your own. Generic words like &lt;code&gt;source&lt;/code&gt;, &lt;code&gt;type&lt;/code&gt; or &lt;code&gt;value&lt;/code&gt; are exactly the ones vendors reserve.&lt;/p&gt;

&lt;h2 id=&quot;consent&quot;&gt;Lesson two: stopping gtag's advertising request&lt;/h2&gt;
&lt;p&gt;DWEEB's privacy policy promises analytics cookies and no advertising or cross-site tracking. While tightening the Content Security Policy on the site's static pages, I saw a console error on every page that loaded analytics: a request to &lt;code&gt;stats.g.doubleclick.net&lt;/code&gt; blocked by the CSP. That's gtag's Google-signals ping, an advertising-related request.&lt;/p&gt;
&lt;p&gt;I tried the documented switches first. Google signals was already turned off for the property. Setting &lt;code&gt;allow_google_signals: false&lt;/code&gt; and &lt;code&gt;allow_ad_personalization_signals: false&lt;/code&gt;, through &lt;code&gt;gtag(&amp;quot;set&amp;quot;)&lt;/code&gt; or the &lt;code&gt;config&lt;/code&gt; call, did not stop the request. What did stop it was setting consent defaults &lt;em&gt;before&lt;/em&gt; the &lt;code&gt;js&lt;/code&gt; and &lt;code&gt;config&lt;/code&gt; calls:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;window.dataLayer = window.dataLayer || [];
function gtag() { dataLayer.push(arguments); }

gtag(&amp;quot;consent&amp;quot;, &amp;quot;default&amp;quot;, {
  ad_storage: &amp;quot;denied&amp;quot;,
  ad_user_data: &amp;quot;denied&amp;quot;,
  ad_personalization: &amp;quot;denied&amp;quot;,
  analytics_storage: &amp;quot;granted&amp;quot;,
});
gtag(&amp;quot;js&amp;quot;, new Date());
gtag(&amp;quot;config&amp;quot;, &amp;quot;G-XXXXXXXXXX&amp;quot;, {
  allow_google_signals: false,
  allow_ad_personalization_signals: false,
});&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Page views were still collected afterwards. The collection requests carry consent state that reflects denied ad storage, and the DoubleClick request was gone. I kept the two flags anyway, because they are the documented per-tag opt-outs. The wrong fix would have been to widen the CSP to let the request through. The error was the CSP doing its job.&lt;/p&gt;

&lt;h2 id=&quot;privacy&quot;&gt;Lesson three: what never goes into analytics&lt;/h2&gt;
&lt;p&gt;A message builder handles things people would rather not have in an analytics product: message text, webhook URLs (which contain a secret token), server and channel IDs. The rules I follow:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Allow-lists, not deny-lists.&lt;/strong&gt; Each event has an explicit list of permitted parameters with fixed values. Anything else is dropped before it leaves the page.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Turn off Enhanced Measurement.&lt;/strong&gt; GA4's automatic outbound-click, site-search and history-change events collect URLs and query strings your own filters never see. A page URL with a shared message in its fragment, or a query containing an ID, would go straight into the property.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Send a controlled page location.&lt;/strong&gt; The page location sent is a canonical path, and the referrer is reduced to its origin. Hash fragments and arbitrary query strings are never sent.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No free-form text, ever.&lt;/strong&gt; Not message content, not search terms, not error messages.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;This costs a little analytical detail. In exchange, I can describe in the privacy policy exactly what is collected, and it stays true when someone adds an event in a hurry.&lt;/p&gt;

&lt;h2 id=&quot;summary&quot;&gt;Summary&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Don't name event parameters &lt;code&gt;source&lt;/code&gt;, &lt;code&gt;medium&lt;/code&gt;, &lt;code&gt;campaign&lt;/code&gt;, &lt;code&gt;term&lt;/code&gt; or &lt;code&gt;content&lt;/code&gt; in GA4. Enforce it in code.&lt;/li&gt;
&lt;li&gt;If you deny advertising, set consent defaults first. The individual flags didn't stop the DoubleClick request for me.&lt;/li&gt;
&lt;li&gt;Allow-list parameters and disable automatic collection you can't filter.&lt;/li&gt;
&lt;/ul&gt;</content>
    <category term="Analytics" />
    <category term="Google Analytics" />
    <category term="Privacy" />
  </entry>
</feed>
