DEV Community: Vadym Arnaut

I sent HTTP QUERY through the real internet. The smarter the layer, the harder it broke.

Vadym Arnaut — Tue, 07 Jul 2026 14:49:11 +0000

TL;DR. HTTP got a new method in June: QUERY (RFC 10008), a GET that carries a body. Everyone wrote explainers and threat models. Nobody actually fired it at real infrastructure. So I did, for a few nights: ten production edges from CloudFront to raw nginx, three browser engines, real client libraries. One law fell out of all of it. The more a layer "understands" HTTP methods, the more likely it is to break the newest one. And when I forced a real cache to store a QUERY, it served one query's answer to a different query.

RFC 10008 shipped in June. If you missed it: QUERY is a request method with GET's semantics (safe, idempotent, cacheable) that carries its query in the body like POST. It's the thing we've faked with POST /search for twenty years, finally given a name.

Twenty years of POST /search was a small lie we told every cache and WAF. QUERY is the honest version.

Within days of the RFC there was already a wave of posts. Explainers mostly, plus a couple of good security write-ups mapping the "attack surface." Every one of them was theory. Not one ran a request. The Hive Security piece even calls its own smuggling section "the most speculative entry on this list, there's no confirmed public case yet." So the interesting question was wide open: what does QUERY actually DO when it hits the real internet?

I built a little lab and spent a few nights finding out. Repo at the bottom. Here's what happened.

The edge decides, and it's a coin toss

First stop, the CDN. I sent one QUERY request through ten production edges and watched who forwarded it to the origin and who killed it on the doorstep.

One QUERY request, ten edges. Every status is the edge's own, not the origin's.

The split was clean, and it was backwards from what you'd want. CloudFront answers 403 Invalid method, and there is NO config that fixes it: its allowed-methods list is a closed set of seven verbs and QUERY will never be one of them. Akamai (which, and I love this, co-authored the RFC) returns 400, treating QUERY as an unparseable token. Google, Netlify, Bunny all say 405. Vercel does something stranger, it challenges the verb as bot traffic, which I wrote up on its own.

And the edges that let QUERY through? nginx. HAProxy. Fastly. Cloudflare. Fly. Plain, configurable proxies with no opinion about your verbs.

That's when it clicked. The blockers all shared one trait: they're the smart, managed, "we handle HTTP methods for you" platforms. The forwarders are the dumb pipes. The more a layer understands about HTTP methods, the more likely it is to reject the newest one.

I want to be careful here, because the docs lie about this and I almost repeated it. The research I read said Varnish "breaks" QUERY. So I installed real Varnish and sent it one. It forwarded it fine (uncached, but it reached the origin). Not blocked. The real blockers are the proprietary edges with closed method vocabularies, not the open-source proxies you can actually configure. Measure, don't trust the write-up. Even this one.

The same list, written before QUERY existed, is everywhere

Once you see the pattern at the edge you can't unsee it up and down the stack. It's always the same shape: a hardcoded allow-list of "known" methods, frozen before June 2026, and QUERY isn't on it.

Change nothing but the verb, and every layer flips.

I measured the ones I could reach. Cross-origin QUERY in the browser preflights (it isn't CORS-safelisted), and if your server answers Access-Control-Allow-Methods: GET, POST, which is what a huge share of the internet hardcodes, the browser blocks it before your code runs. Identical in Chromium, Firefox, and WebKit.

Client retries are my favorite one. QUERY is idempotent, the ONE property that makes a retry safe. So I pointed urllib3's default retry policy at a server that fails once and fired a GET and a QUERY. The GET retried and succeeded. The QUERY failed on the first try and gave up, because urllib3's retry allow-list is {GET, HEAD, PUT, DELETE, OPTIONS, TRACE} and nobody has added QUERY. Your CDN breaks QUERY because it's too smart. Your HTTP client breaks it because it's too careful. The exact safety mechanism built to stop clients double-firing POSTs now refuses to retry the one new method that is genuinely safe to retry.

It just keeps going. OpenTelemetry drops QUERY into _OTHER on its Java and Go agents, so it vanishes from your per-method dashboards. OpenAPI 3.1 literally cannot name a QUERY operation. OWASP CRS blocks it with a four-token string older than the RFC. Nobody sat down and wrote "block QUERY." They wrote "here are the methods" years ago, and the list is now the bug.

I made a real cache store QUERY. It served the wrong answer.

Here's the part that made me sit back.

QUERY's whole reason to exist over POST is that it's cacheable. But the cache key has to include the body, because the body IS the query. The RFC says exactly that, then adds one nervous sentence in the Security Considerations:

Caches that normalize QUERY content incorrectly or in ways that are significantly different from how the resource processes the content can return an incorrect response if normalization results in a false positive.

That "false positive" is a polite way to spell cache poisoning. The authors saw it, wrote it down, and shipped anyway. I wanted to watch it happen.

So I told real Varnish to cache QUERY and sent it three requests.

Three different queries, one URL. Varnish served the first one's answer to all of them.

Varnish keys its cache on the URL and host. Not the body. So the moment you force it to cache a QUERY, every request to /search collapses into one entry. I sent {"a":1}, then {"a":1} again (fine, a real cache hit), then {"a":999}, a completely different query. It got {"a":1}'s cached response. The origin was never even asked. And it's worse than key collision: Varnish drops the request body on the cacheable fetch, so the origin couldn't have computed the right answer even if it had been asked.

I checked this the honest way, hitting the origin directly to confirm it echoes each body correctly. It does. This is Varnish, not my test. It's that Security Considerations sentence sitting live in production-grade software: cache QUERY naively and you hand one user's search results to another. The write-ups modeled this risk on paper. Here it is running, in a tiny VCL snippet.

For balance: I also wrote a ~40-line cache that does it RIGHT, keying on a hash of the body. The fix is genuinely easy. The point is that the caches you already run don't do it, and turning caching on is the dangerous part.

The good news: your code is already fine

Here's the twist that keeps this from being all doom. Every layer that breaks QUERY is infrastructure you didn't write. The layer you DID write is ready.

I checked the receive side: Express, Fastify, and FastAPI all route a QUERY request and read its body without a fuss. Browsers send it, all three engines, via both fetch and XMLHttpRequest. The runtimes rolled out the carpet. It's the bouncers at the edge who never got the memo.

So you can ship QUERY today, as long as you're willing to duck when the edge swings.

Try the real method first. Fall back to POST plus a header the moment an intermediary says no.

The trick is the oldest one in the book: X-HTTP-Method-Override. The client tries native QUERY. If it eats a 403 or 405 from some middlebox, it retries as a plain POST carrying X-HTTP-Method-Override: QUERY, and a tiny server middleware unwraps it back into a QUERY. The edge only ever sees a POST, which every CDN on earth forwards. You do lose edge cacheability on that fallback path, which, after the Varnish section, you may not want anyway.

What's actually new here

Quick honesty, because it matters. The RISKS in this post are not secret. There's a real blog wave, including solid security write-ups, that describe cache poisoning, the CORS gotcha, unknown-method blocking, all of it. What none of them did was run it. Every piece I found is threat-modeling, and says so. What's new here is the measurement: which edge does what and why, the live Varnish poisoning, the retry gap, the cross-engine CORS behavior, the working fix. Theory is cheap for a three-week-old RFC. I wanted receipts.

What I'd want to hear back

If you run QUERY behind Cloudflare or Fastly with real caching switched on, does the body-blind poisoning reproduce there too? That's the one experiment I couldn't run without your origin.
Anyone shipping QUERY in prod, not a demo? Which layer bit you first?
Is there a single CDN that keys a cache on the request body today, or does "cacheable QUERY" stay theoretical until someone builds it?

The lab, every script, the raw numbers, and the ~40-line safe cache:

ArVaViT / http-query-lab

Empirical tests of the new HTTP QUERY method (RFC 10008) against real clients, frameworks, and production infra

http-query-lab

Empirical tests of the new HTTP QUERY method (RFC 10008, June 2026) against real clients, servers, frameworks, and production infrastructure. Not what the spec says, but what actually happens on the wire in July 2026.

QUERY is a request method with GET semantics (safe, idempotent, cacheable per RFC 10008 §2 and §2.7) that carries its query in the body instead of the URI This repo answers: who on a real request path already speaks it, and who breaks?

Headline: Vercel's default bot mitigation treats QUERY as a bot signal

Twenty requests, one client, 400ms apart, one method at a time:

GET   x20  from node/undici : all 200            (clean)
POST  x20  from node/undici : all 200            (clean, and POST carries a body)
QUERY x20  from node/undici : 200,200,200,403... (challenge at request #4)
QUERY x20  from curl        : 200,...,403...      (challenge at request #5)

The 403 is X-Vercel-Mitigated: challenge from…

View on GitHub

HTTP finally shipped QUERY. I fired it at production and the edge called it a bot.

Vadym Arnaut — Sat, 04 Jul 2026 02:58:12 +0000

TL;DR. QUERY (RFC 10008) is a real HTTP method now, a GET that carries a body. I deployed echo endpoints on Vercel (Python and Node), Supabase Edge, and local FastAPI, then fired GET, POST and QUERY at each. Every runtime handled QUERY fine. Then Vercel's default bot mitigation started 403-challenging my QUERY traffic specifically. Same client, same body: 20 GETs clean, 20 POSTs clean, QUERY tripped the challenge on request #4. Reproduced from a second client. The functions are ready for QUERY. The edge in front of them is not.

RFC 10008 landed in June. If you missed the wave of explainers: QUERY is a request method with GET semantics (safe, idempotent, cacheable) that carries its query in the body instead of the URL. It closes the old gap where a search filter is too big for a query string but you don't want to lie and call it a POST.

Every post I read explained the spec. Nobody actually fired it at a live production edge. So I did, late one night, with a throwaway lab. Most of it was boring. One result made me sit up and say "wait, what?" out loud. Repo at the bottom.

The setup

Four echo endpoints, each returns the method and body it saw:

Vercel serverless, Python runtime
Vercel serverless, Node runtime
Supabase Edge Function (Kong gateway in front of Deno)
local FastAPI on uvicorn, for the parser tests

The whole Python function is basically this:

# api/echo.py on Vercel
class handler(BaseHTTPRequestHandler):
    def do_QUERY(self):   # yes, you just define do_QUERY
        self._echo()
    def do_GET(self):
        self._echo()

Python's BaseHTTPRequestHandler dispatches on do_<METHOD>, so do_QUERY is all it takes. Miss the handler and you get a clean 501, which is exactly what the RFC wants.

The runtimes are ready

This part was boring in the best way. QUERY went end to end everywhere.

curl -X QUERY https://http-query-lab.vercel.app/api/echo -d '{"q":"hi"}'
# {"runtime":"python","method":"QUERY","body":"{\"q\":\"hi\"}"}

Node's parser (llhttp) has known QUERY since v21.7.2, it sits in http.METHODS on 22 and 26. Supabase's Deno gateway forwarded it on both HTTP/1.1 and HTTP/2. The only 405 I got was on a static asset, which is correct.

Frameworks are where it gets uneven. What actually happens today:

Layer	QUERY today
Node `http` / llhttp	in `http.METHODS` since 21.7.2
Express 5	routes it, `app.query()` exists (auto-generated from `http.METHODS`)
Fastify 5	refuses it until `addHttpMethod('QUERY', {hasBody:true})`
Python `http.server`	define `do_QUERY`, missing handler gives 501
FastAPI	`@app.api_route(methods=["QUERY"])`
.NET 10	`HttpMethod.Query` on client and server

Fastify was the one that bit me. A QUERY route throws at registration with "QUERY method is not supported", and an incoming QUERY 404s until you opt in. Not a bug, it validates against a fixed method list. Just a footgun if you assume parity with Express.

Every runtime I tried returns QUERY. The only thing that drops it sits at one edge.

Then the edge called it a bot

Here is the part nobody wrote about.

I ran a burst test against the Vercel endpoint. Twenty requests, same client, 400ms apart, one method at a time from the same connection pool. GET first, then POST, then QUERY:

GET   x20:  all 200
POST  x20:  all 200        (POST carries a body too, remember)
QUERY x20:  200,200,200,403,403,403,403...

Same client and same body across the top three rows. GET and POST finish clean, QUERY does not.

Request #4 came back 403. X-Vercel-Mitigated: challenge. That 403 was not from my function. It was the edge, and my request NEVER reached the runtime. Once it flagged me, every method got challenged, GET included, for more than ten minutes.

My first thought was the boring one: "it's the client, curl and undici look like bots, of course the scorer hates me." So I controlled for it. The GET and POST bursts above are from the exact same client, the same fingerprint, and POST even carries a body. They ran clean to twenty. Only the method changed.

Then I ran the QUERY burst from a second client, curl instead of undici. Challenged on request #5. Same story!

So it is not the fingerprint, not the body, not the request rate. Twenty GETs and twenty POSTs at the same cadence sail right through. Swap the method to QUERY, change nothing else, and a bot challenge fires in four requests. That is when it clicked: the edge is treating the QUERY verb ITSELF as a bot signal. No custom firewall rules, no attack mode. This is the default behavior on a fresh project.

And honestly? It makes a grim kind of sense. Real browser traffic doesn't send QUERY yet, so to a heuristic "QUERY from a non-browser" looks exactly like a scanner poking your API with a weird verb. The spec shipped faster than the security tooling learned the verb exists. The runtime rolled out the carpet, and the bouncer at the door never got the memo.

You can turn Vercel's bot management off or bypass it with a token, so this isn't fatal. But flip QUERY on for a public endpoint today, sit behind a CDN with default bot rules, and some slice of your legitimate non-browser callers get challenged into a wall. You won't even see it in your app logs, because it never reaches your app.

Two more footguns before you ship QUERY

Lowercase kills it. fetch only uppercases the six classic methods, so fetch(url, {method:'query'}) goes on the wire literally as lowercase query. That is not cosmetic. The default uvicorn parser (httptools, which wraps llhttp) rejects it with a 400 before your app runs:

uvicorn --http httptools:   QUERY -> 200,  query -> 400,  get -> 400
uvicorn --http h11:         QUERY -> 200,  query -> 200,  get -> 200

llhttp matches its method table case-sensitively, so any lowercase verb is an invalid token to it, not just QUERY. Switch to the pure-Python h11 parser and the same lowercase request passes through to a 405. So "my QUERY works locally but 400s in prod" can just be two different parsers. The normalization gap itself is tracked in whatwg/fetch#1938, worth a read.

Nothing caches it yet. The whole selling point of QUERY over POST is that it is cacheable. In practice no browser cache stores it today. I put Cache-Control: public, max-age=300 on a QUERY response against a local origin, no CDN in the path, and fired two identical requests. Both hit the origin. The GET control on the same setup served the second from cache. That matches what jeswr measured for Chrome and Firefox in that same fetch issue. The RFC allows caching QUERY with a cache key that includes the body, but existing caches key on method plus URL, so they structurally can't, and they don't. The "cacheable" promise is real on paper and ZERO in your browser right now.

What I'd want to hear back

This was one edge, one night, one very confused engineer staring at a wall of 403s. I really want to know how far it generalizes.

If you're on Cloudflare or AWS WAF, does default bot protection challenge QUERY the way Vercel's does? I only tested one edge, curious whether this is industry-wide or a Vercel default.
Anyone running QUERY on a real public endpoint, not a demo? What broke?
Is body-aware cache keying ever landing in a shipping cache, or does "cacheable QUERY" stay theoretical?

Lab, all the scripts, and the raw numbers:

ArVaViT / http-query-lab

Empirical tests of the new HTTP QUERY method (RFC 10008) against real clients, frameworks, and production infra

http-query-lab

Headline: Vercel's default bot mitigation treats QUERY as a bot signal

Twenty requests, one client, 400ms apart, one method at a time:

GET   x20  from node/undici : all 200            (clean)
POST  x20  from node/undici : all 200            (clean, and POST carries a body)
QUERY x20  from node/undici : 200,200,200,403... (challenge at request #4)
QUERY x20  from curl        : 200,...,403...      (challenge at request #5)

The 403 is X-Vercel-Mitigated: challenge from…

View on GitHub

Three dumb ways our prod got slow (and not one was a slow algorithm)

Vadym Arnaut — Thu, 25 Jun 2026 17:13:29 +0000

TL;DR. Three prod slowdowns in one week. A 30-second timeout that was secretly TWO MINUTES. A math library we shipped twice to students who don't even have math. And a dashboard that built tens of thousands of objects just to draw a few hundred rows. Not one of them was a slow algorithm. The cause was never where I looked first.

We run Equip (open-source LMS: FastAPI + React + Supabase Postgres). I spent a week chasing latency, and the slow-query log lied to me every single time. Every fix lived UPSTREAM of the code that looked slow. Here's the wall of shame.

1. The 30-second timeout that was actually two minutes

I was sure we had a 30s statement_timeout. I set it the obvious way:

# looks right. does absolutely nothing in prod.
connect_args = {"options": "-c statement_timeout=30000"}

Then I ran SHOW statement_timeout on prod. It said 2min.

Two. Minutes. Not 30 seconds. The raw cluster default.

Here's why. We sit behind Supabase's Supavisor in transaction-pooling mode, and a transaction pooler SILENTLY drops libpq startup options. The server connection you borrow for a transaction is not the one you "connected" with, so everything you set at startup just... evaporates. Our 30-second safety net was a comment. One ugly query could pin a pooled connection for the full two minutes.

The fix is a SET LOCAL on every transaction, wired through a SQLAlchemy engine event:

@event.listens_for(_engine, "begin")
def _set_statement_timeout(conn):
    # SET LOCAL is scoped to THIS transaction, so it can't leak
    # onto the next client that borrows this pooled connection
    conn.exec_driver_sql("SET LOCAL statement_timeout = '30s'")

SET LOCAL is the ONLY form that survives a transaction pooler. A plain session SET leaks the value onto whoever grabs that connection next. The startup options get dropped. SET LOCAL resets on commit, so every transaction gets exactly the ceiling you asked for and nobody inherits it.

Lesson: behind a transaction pooler, "I configured the connection" is a sentence you should not trust. That connection isn't yours.

2. We shipped KaTeX TWICE, to people who have no math

The student chapter page kept getting heavier and nobody could tell me why. The content is mostly text. There's basically no math in prod.

So I opened the bundle. We were shipping KaTeX twice. TWICE! One copy (v0.17.0) imported straight into ChapterView. A second copy (v0.16.47) dragged in transitively by the rich-text editor's math extension. Two full copies of a typesetting library, and the student-facing one loaded eagerly on every single chapter render, formula or not.

And there was a nastier landmine under it. katex.min.css only lived in the teacher-editor chunk. So the very first time a teacher typed a formula, it looked perfect for THEM and rendered unstyled and broken for every student, because students never load that chunk. Ouch.

Two fixes. Dedupe to one copy with an npm override so the editor extension uses the app's katex. Then make the whole thing lazy, loading the library AND its CSS only when there's actually math on the page:

// only runs if the page has unrendered math markers
const [{ default: katex }] = await Promise.all([
  import("katex"),
  import("katex/dist/katex.min.css"), // ship the CSS WITH the lib, not in some other chunk
]);

ChapterView fires it and forgets. The student chapter chunk dropped from 84.2 KB to 9.9 KB gzip. For the page loads with no math (almost all of them) katex now never downloads at all.

Lesson: a dependency that your dependency drags in is STILL your bytes. "Import it where it's used" beats "import it at the top" exactly when most people never hit that path.

3. We built tens of thousands of objects to draw a few hundred rows

This one wore three masks, all the same sin: doing O(N×M) work to render O(N) of UI.

/users/me/courses (the dashboard) eager-loaded the WHOLE module-and-chapter tree for every course. Hundreds of entities on a big course. Then the dashboard schema threw all of it in the bin, because the dashboard shows course cards, not chapters.
/progress/course/{id}/students shipped the full per-chapter breakdown for every student. That's students times chapters. On our fat-seed test course it was tens of thousands of objects in ONE response, just to draw a table of names and averages.
The localized course detail validated the same tree up to THREE times per request and cloned a couple hundred chapter objects with model_copy on the way.

The fixes are boring, and that's the point. A slim dashboard schema with no modules field, so the tree never loads. A progress list that returns server-computed averages and lazy-loads one student's detail only when you expand their row. And a single bottom-up validation pass with Pydantic v2's revalidate_instances="never", so each entity is validated once instead of three times.

Then the database side of the exact same story: we were missing indexes. Three of them, one migration. The two that mattered are partial composite indexes:

-- we only ever aggregate COMPLETED attempts, so don't index the rest
CREATE INDEX ix_quiz_attempts_quiz_user_completed
  ON quiz_attempts (quiz_id, user_id)
  WHERE completed_at IS NOT NULL;

CREATE INDEX ix_chapter_progress_chapter_user_completed
  ON chapter_progress (chapter_id, user_id)
  WHERE completed;

That WHERE predicate is the whole trick. These queries only ever touch completed work, so indexing the unfinished rows is dead weight. The third index, on certificates(status), was already declared in our ORM model and had just never been migrated to prod. A model-vs-schema drift the audit caught on the way past.

Lesson: the slow-query log shows you the query that's slow. It does NOT tell you the query should never have been fetching that shape to begin with.

The thread tying it together

None of this was algorithmic. A startup option a pooler ignores. A duplicated dependency. Over-fetching a tree just to throw it away. A missing WHERE on an index. Every one of them lived upstream of the code that profiled slow: in the connection layer, the bundler, the serializer, the migration history.

The profiler points at the symptom. Now I try to ask, every single time: "what BUILT this input?" before I optimize whatever's chewing through it.

A few things I'd honestly love to hear back on:

If you're behind a transaction pooler (Supavisor, PgBouncer): do you SET LOCAL per transaction, or push timeouts up to the gateway and keep the app dumb? We went app-side and I'm genuinely not sure it's right long-term.
Has a transitive dependency ever shipped a second copy of something already in your bundle? How did you catch it before prod? We're eyeing a gzip size budget in CI.
Where do you draw the lazy-loading line? Math was easy. I'm much less sure about, say, a charting lib used on a third of pages.

ArVaViT / equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

A free, open-source learning management system built for Bible schools church ministries, and nonprofit educational programs

Live demo · Roadmap · Contributing · Support · Changelog

Screenshots

Sign in (light)	Sign in (dark)
Account creation — student / teacher role picker	Mobile (390px)

Live at equipbible.com. Teacher and admin views (gradebook, course editor, analytics) are behind sign-in — create a free account to explore.

Why this project?

Hundreds of small Bible schools, home churches, and missionary training programs around the world still manage courses on paper, WhatsApp, or spreadsheets. Commercial LMS platforms are expensive, overkill, or require technical expertise that volunteer-run organizations simply don't have.

Equip is designed to change that:

Free forever — MIT-licensed, no paywalls, no "premium" tiers.
Simple to deploy — one-click Vercel deploy with a free Supabase database. No Docker, no servers to manage.
Built for small scale — optimized for 20-100 students, not…

View on GitHub

I had real backend auth. The browser just walked around it.

Vadym Arnaut — Wed, 17 Jun 2026 18:33:50 +0000

Here's the thing nobody warns you about when you put Supabase behind a "real" backend.

My stack is React + FastAPI + Supabase Postgres. Every write goes through FastAPI. Every endpoint checks the user, the role, the ownership. I audited that backend HARD — rate limits, JWT validation, RLS, the whole thing. I was proud of it.

And none of it mattered for the two holes I actually shipped.

Because the Supabase anon key lives in the browser. It HAS to — that's how supabase-js talks to your project. Which means every logged-in user is holding a key that talks to Postgres directly. Not through my FastAPI. Around it.

That anon key is a SECOND API. And I'd spent months hardening the first one while the second one sat there, wide open, the whole time.

Hole #1 — the answers were just... readable

Quiz questions live in quiz_options, one is_correct boolean per option. My backend never sends is_correct to a student before they submit. Obviously.

But the browser doesn't have to ask my backend.

// any logged-in student, straight from the console:
const { data } = await supabase
  .from('quiz_options')
  .select('question_id, label, is_correct')   // <- the answer key. all of it.

The RLS policy said "authenticated users can read quiz_options." Totally true for the rows. It just also handed back the column that decides the grade. The answer key. To anyone with a login and ten seconds of curiosity.

Fix: column-level REVOKE SELECT from the client role, and let the backend be the only thing that ever reads is_correct. (PR #775.)

Hole #2 — they could WRITE things they shouldn't

Same class of bug, bigger blast radius. The default Postgres grants let the client role insert/update far more than I'd realized — including a path toward forging a certificate. Nobody did it. But "nobody did it yet" is not a security model!

So I stopped patching table by table and flipped the whole thing:

-- kill the client's entire write surface, then grant back the ONE thing it needs
ALTER DEFAULT PRIVILEGES IN SCHEMA public
  REVOKE INSERT, UPDATE, DELETE ON TABLES FROM authenticated;
GRANT UPDATE (/* your own profile fields */) ON public.profiles TO authenticated;

After that migration the browser can write exactly one thing: your own profile. EVERYTHING else goes through FastAPI, where the real checks live. (PR #794.)

The lesson I wish I'd had on day one

If your anon key ships to the browser — and with supabase-js, it does — then your RLS grants ARE your API. Not "a backend detail." The actual, public, internet-facing contract.

So audit them like it. Read every GRANT. For every table, ask one question: if a logged-in user typed this select (or insert) in their console, what comes back, and what changes? Default the client to read-almost-nothing, write-nothing — and earn each grant back on purpose.

Your backend auth can be flawless and still be theater, if the front door right next to it is unlocked.

Equip is open source under MIT: github.com/ArVaViT/equip. Both fixes are in main — PR #775 (the answer-key leak) and PR #794 (the write-surface lockdown).

What's the worst RLS grant you've ever found in your own project? I genuinely want to hear it.

ArVaViT / equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

A free, open-source learning management system built for Bible schools church ministries, and nonprofit educational programs

Live demo · Roadmap · Contributing · Support · Changelog

Screenshots

Sign in (light)	Sign in (dark)
Account creation — student / teacher role picker	Mobile (390px)

Live at equipbible.com. Teacher and admin views (gradebook, course editor, analytics) are behind sign-in — create a free account to explore.

Why this project?

Equip is designed to change that:

Free forever — MIT-licensed, no paywalls, no "premium" tiers.
Simple to deploy — one-click Vercel deploy with a free Supabase database. No Docker, no servers to manage.
Built for small scale — optimized for 20-100 students, not…

View on GitHub

I ran 4 AI agents on yesterday's PRs. Two real security bugs surfaced.

Vadym Arnaut — Tue, 09 Jun 2026 03:01:20 +0000

After every coding session I run a 4-agent parallel audit on the diff I just shipped. A recent session of mine was seven PRs landing a new daily-challenge feature on my open-source LMS. Two of the audit findings were real security or integrity bugs that my human review missed. This is the playbook.

The four agents

I split the audit into four narrow roles. Narrow because a generalist agent tells you everything is fine; a specialist with a clear mandate tells you what is broken.

Cleanup agent. Looks for leftover patterns from the work just done: dead references to removed roles, unused i18n keys, orphan test fixtures, dual-named scripts where one should have died.
Security agent. Auth, tokens, rotation, CSP, RLS, secrets in code, error messages that leak structure. Treats every new endpoint as hostile until proven otherwise.
Test integrity agent. Reads each test that was added or changed and asks the harder question: would this test fail if the code under test was wrong? Hunts for tautologies, tests that pass by insertion order, assertions that match the implementation instead of the requirement.
Live prod verification agent. Pulls actual production data, hits the new endpoints with real auth, confirms the change reached prod and behaves like the diff implies.

Each agent runs in parallel with a 15-20 minute budget, not a 6-minute skim. The output is a findings list, severity-tagged, with file:line references and proposed fixes.

The audit's haul: two real bugs

Critical: PyJWT `decode` does not validate `iat`

The diff included an iCal subscription feature with a 365-day token TTL and a "rotate token" button. Rotation generated a new JWT with a fresh iat and updated nothing else. The implicit promise was that the old token would stop working.

It did not. The security agent flagged this in one line: "pyjwt.decode does not validate iat by default. Old tokens with the original iat remain valid for the full 365-day TTL after rotation."

# Before — rotation does nothing useful
payload = jwt.decode(token, SECRET, algorithms=["HS256"])
# iat is in the payload but never compared to anything

# After — refuse any token issued before the user's rotation floor
floor = current_user.calendar_ical_min_iat
payload = jwt.decode(token, SECRET, algorithms=["HS256"])
if floor is not None and payload["iat"] < floor:
    raise InvalidToken()

Schema change: one new column on profiles, calendar_ical_min_iat BIGINT NULL. Rotation writes the new token's iat to that floor. Verification refuses any token whose iat is below it. Three tests pin the contract: rotation invalidates the old token, a token signed with a different secret fails, the floor read works on first rotation.

PyJWT validates exp and nbf by default. It does not validate iat. Even passing options={"verify_iat": True} only checks that iat is a valid timestamp, not that it is recent enough. If your auth design assumes "rotation invalidates everything older," you have to enforce it yourself.

High: a test that was passing by insertion order

The test integrity agent caught a test named test_prefers_live_over_archive_attempt. The function under test ordered results by is_archive ASC. The test inserted the live attempt first, then the archive attempt, then asserted the live one came back.

That assertion passed for the wrong reason. SQLite returned rows in insertion order absent an effective ORDER BY. If the ORDER BY had been deleted from the production code, the test would have stayed green. The agent flagged this as "tautological under the current backend; rewrite so only the ORDER BY can make the test pass." I reversed the insertion order. The test passes for the right reason now.

This is the finding that scared me most. The other one was a security bug, but at least it was a bug I would have learned from when it bit. A test that passes for the wrong reason is a bug you never learn from, because it tells you everything is fine while the implementation rots underneath.

Why specialist agents beat one generalist

The first version of this workflow used one agent with a long prompt that said "find security issues, cleanup issues, test issues, and verify against prod." The output was a list of fifteen "potential concerns" that read like a checklist someone copied from a blog post. Half were false positives, none were severity-ranked, and the actually-critical PyJWT thing was buried at item nine.

Splitting the same audit into four specialists with narrow mandates and clear severity rubrics changed the output. The cleanup agent comes back with "zero items" when there is nothing, instead of inventing four items to look thorough. The security agent comes back with two findings, both real, both severity-tagged, both with file:line refs. The test integrity agent finds the tautology that nobody who wrote the test would ever see, because the human author is exactly the wrong person to ask whether the test would catch the bug.

What this is not

This is not a code-review bot replacing human review. It runs after the human review and merge, on the change as it exists in main. It is not a substitute for thinking about the diff while you write it. It is the second pass that catches what familiarity blinds you to, on the surface area the diff actually touches.

If a human review took 30 minutes and missed the PyJWT thing, a four-agent audit that catches it is the cheapest security investment in the workflow. The cost is the agent budget. The value is the bug that would have been a year-long production leak.

I will not be writing production code without the four-agent post-session audit again.

Equip is open source under MIT at github.com/ArVaViT/equip. PR #626 closes the bugs above and adds the defensive tests.

ArVaViT / equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

A free, open-source learning management system built for Bible schools church ministries, and nonprofit educational programs

Live demo · Roadmap · Contributing · Support · Changelog

Screenshots

Sign in (light)	Sign in (dark)
Account creation — student / teacher role picker	Mobile (390px)

Live at equipbible.com. Teacher and admin views (gradebook, course editor, analytics) are behind sign-in — create a free account to explore.

Why this project?

Equip is designed to change that:

Free forever — MIT-licensed, no paywalls, no "premium" tiers.
Simple to deploy — one-click Vercel deploy with a free Supabase database. No Docker, no servers to manage.
Built for small scale — optimized for 20-100 students, not…

View on GitHub

There is no source language: a manifesto for symmetric multilingual content

Vadym Arnaut — Thu, 28 May 2026 14:50:42 +0000

Three weeks ago I shipped a bilingual LMS. The architecture modeled one language as source and the rest as overlay: a source_locale column on every translatable entity, an MT pipeline reading source rows and writing overlay rows. It worked. Students used it. Certificates issued. Three published courses, fourteen real users, end-to-end.

Last week it broke in a way that did not fit a bug fix.

A teacher whose interface was set to English wrote a course entirely in Russian. The system saw teacher.preferred_locale = 'en', stamped source_locale = 'en' on every course field, and then served Russian students a course labelled "Russian translation of an English source" — when no English source existed, ever. The fallback path showed [translation missing] placeholders on a course that was, in fact, perfectly written in the language being requested.

The first fix attempt was a heuristic: detect the actual character set of the content and derive source_locale from that, not from the teacher's UI. Better. Still wrong, because per-entity source locale assumes the entity is monolingual — and there is no rule that says it has to be. A course with an English title and a Russian description is one entity with no single answer to "which locale is source?"

The second attempt moved detection per-field. Better still. Still wrong, because per-field source locale assumes the field is monolingual — and there is no rule that says it has to be. A bilingual paragraph (a sentence in English, a Russian phrase set off in italics, a quoted scripture reference) has no single answer either.

At that point the model is the bug, not the heuristic.

Locale is just a column

The new schema, shipped to main last night across eight stacked PRs:

CREATE TABLE content_versions (
    id                 uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    entity_type        text NOT NULL CHECK (entity_type IN (
                           'course','chapter_block','assignment','cohort',
                           'course_event','announcement', ...
                       )),
    entity_id          uuid NOT NULL,
    field              text NOT NULL,
    locale             text NOT NULL CHECK (locale IN ('en','ru')),
    body               text NOT NULL,
    origin             text NOT NULL CHECK (origin IN ('human','mt')),
    source_version_id  uuid REFERENCES content_versions(id),
    superseded_by      uuid REFERENCES content_versions(id),
    created_at         timestamptz NOT NULL DEFAULT now(),
    created_by         uuid REFERENCES auth.users(id)
);

CREATE UNIQUE INDEX content_versions_active_unique
ON content_versions (entity_type, entity_id, field, locale)
WHERE superseded_by IS NULL;

Every (entity, field, locale) is its own row. There is no source locale and no overlay. There are rows that exist because a human wrote them, rows that exist because the MT pipeline produced them, and the lineage between them. The thing that says "this Russian title was machine-translated from that English title" is source_version_id. The thing that says "an editor revised it" is superseded_by. The thing that says "what language is this row" is locale. No row outranks another by default.

The model is symmetric. The data is the data. Adding a third language is INSERT INTO content_versions ... plus appending a string to a Pydantic Literal. Zero DDL. No schema deltas. No "let's refactor source_locale to be nullable for the Spanish migration."

What this fixes that you can name

The "Тайтл" bug class disappears entirely. There is no source_locale column to be wrong, so it cannot be wrong. A teacher's UI preference no longer leaks into the content model.

Mixed-language entities are first-class. A course with an English title and a Russian description is two content_versions rows. Each one is correct in isolation. No "what's the source locale of this course" question to argue about, because no field on the entity claims to know.

Translation history is preserved by construction. Editing a row creates a new row with superseded_by pointing at the old one. The previous translation is not overwritten or archived in some side table; it is still in content_versions, just with a non-null superseded_by. The active row is the one with superseded_by IS NULL, enforced by the partial unique index above.

Cascade invalidation gets precise. When the English title is edited, the MT rows that were generated from it — and only those — get invalidated, via source_version_id. The old code had to purge_course_translations(course_id) and re-translate everything, because the lineage was not recorded anywhere readable. The new code knows exactly which rows depend on which.

What stays true from before

The registry pattern still holds. The fact that an entity has translatable fields is declared once, in backend/app/services/translation/registry.py, and read by the orchestrator, the schemas, and the CI guard. The schema change did not move this; it sharpened it. The registry now declares "this entity has these fields in content_versions" instead of "this entity has these _ru/_en overlay columns."

The Bible substitution layer still holds. Canonical text — KJV, Synodal, anything where the wording is a contract with the reader — never goes through the LLM. The MT pipeline substitutes placeholders, translates the prose around them, restores canonical target-locale text. The new model did not touch this. It could not; canonical text is not translated content. It is content that happens to exist in multiple locales because the canon exists in multiple locales. The substitution layer just makes sure the canonical version is the one that ships.

The three-layer split still holds. UI strings, user-generated content, canonical artifacts — three problems, three mechanisms, one product. The new model only touches the middle layer. The other two were already right.

The principle, generalized

The "source language" idea is a residue of monolingual-first design. Pick almost any i18n library, almost any LMS, almost any CMS, and you will find the same implicit assumption: one language is canonical, the rest are derived. Defaults, fallbacks, base locales, primary languages, source-of-truth columns. They all encode the same idea — somebody's language is real, everybody else's is a copy.

For documentation, that may be honest. The MDN reference is in English; the French version is a translation of the English version; calling English the source is correct because it is. For a product that serves bilingual or multilingual users as equally first-class — a faith community, an immigrant network, a multilingual school — the assumption is wrong, and it leaks. Every dropdown that says "EN (Original)", every fallback_locale: 'en' in a config file, every test that asserts the English string and ignores the Russian one, is a cultural primacy choice masquerading as engineering simplicity.

The cost of refusing the assumption is real but bounded. The backfill script is ~550 lines of dual-write reconciliation. The schema is symmetric, so there is no per-language DDL. Read paths read one table, not "canonical column union overlay table." The whole migration is in flight as a six-phase stacked PR — half shipped, the rest sequenced with DO NOT auto-merge until previous live + 7 days, take pg_dump, confirm PITR window, schedule Tue/Wed UTC. Boring, careful, recoverable. The principle is sharp; the rollout is not.

How to verify you have the same bug

Two checks. If your data model has a source_locale (or original_locale, or default_locale) column on a translatable entity, you have a primary language. If your application config has a fallback_locale and your read paths use it when a translation is missing, you have a primary language. Either is the residue. Both is the full version.

The honest move is to model what is actually true: a course has content. Some of that content is in English. Some is in Russian. Some was written by a human. Some was generated by an MT pipeline from a specific human-written version. None of those facts make any language more real than any other.

Bigger than i18n

The deeper read is that the "source plus overlay" pattern is a default reach for any time you have versions of the same thing in different shapes: translations, variants, A/B copy, accessibility re-writes, plain-language summaries, audio scripts. The same model — every variant is a row, lineage is explicit, supersession is preserved, no variant is privileged by schema — generalizes cleanly past locale.

If you are building anything where multiple variants of the same content need to coexist as equals, the question is not which one is the source. The question is what is the lineage, and who or what wrote each row.

If your bilingual app has a fallback locale, you have already chosen which language is real.

Equip is open source under MIT at github.com/ArVaViT/equip. Live at equipbible.com. The content_versions foundation migration is supabase/migrations/20260527230000_content_versions_foundation.sql. The six-phase rollout spans PRs #531 through #553 — Phase 1 (dual-write) is fully merged across all eleven translatable entity types; Phases 2 through 5 (dual-read with comparator, backfill, cv-primary read behind a flag, delete legacy + drop content_translations + drop the source text columns) are sequenced as an open stack.

ArVaViT / equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

A free, open-source learning management system built for Bible schools church ministries, and nonprofit educational programs

Live demo · Roadmap · Contributing · Support · Changelog

Screenshots

Sign in (light)	Sign in (dark)
Account creation — student / teacher role picker	Mobile (390px)

Live at equipbible.com. Teacher and admin views (gradebook, course editor, analytics) are behind sign-in — create a free account to explore.

Why this project?

Equip is designed to change that:

Free forever — MIT-licensed, no paywalls, no "premium" tiers.
Simple to deploy — one-click Vercel deploy with a free Supabase database. No Docker, no servers to manage.
Built for small scale — optimized for 20-100 students, not…

View on GitHub

The auth_rls_initplan linter has a blind spot: SECURITY DEFINER bodies

Vadym Arnaut — Wed, 27 May 2026 21:46:29 +0000

If you've ever migrated a Supabase project to the wrapped (SELECT auth.uid()) pattern, you know the linter that flags the bare call. auth_rls_initplan reads every RLS policy expression and warns whenever auth.uid() is used directly instead of inside a scalar subselect. The wrap turns the call from a per-row evaluation into a single InitPlan. On a million-row table that is the difference between a 30ms read and a 30-second read.

The linter is good. It is also incomplete.

What it doesn't see

The linter introspects the policy expression itself. It does not walk into the body of any function the policy calls. So this passes the linter cleanly:

CREATE OR REPLACE FUNCTION public.is_owner(target_user uuid)
    RETURNS boolean
    LANGUAGE sql
    SECURITY DEFINER
    STABLE
AS $$
    SELECT auth.uid() = target_user;
$$;

CREATE POLICY rows_owner ON public.things
    FOR SELECT
    USING ((SELECT public.is_owner(user_id)));

Green linter. Slow query. The (SELECT ...) at the policy level caches the return value of is_owner(user_id), which itself depends on the row's user_id and runs every row. The auth call inside the function is back to per-row evaluation, and the InitPlan optimization the wrap was supposed to enable never kicks in.

The fix is the same wrap, one level deeper

Move the scalar subselect inside the function body:

CREATE OR REPLACE FUNCTION public.is_owner(target_user uuid)
    RETURNS boolean
    LANGUAGE sql
    SECURITY DEFINER
    STABLE
AS $$
    SELECT (SELECT auth.uid()) = target_user;
$$;

The function still runs per row, but the auth lookup inside it is the single InitPlan call the optimization was designed for.

How to find them

Grep the schema for auth.uid() inside function bodies, not just policies:

pg_dump --schema-only your_db \
    | rg -B 5 'auth\.(uid|jwt)\(\)' \
    | rg -A 2 'SECURITY DEFINER'

Or EXPLAIN ANALYZE the slow query and look for a subplan that fires once per row instead of once per query. If it scales with rows scanned, you have one of these.

The linter is a good first pass. This is the second pass to run before you call your migration done.

Equip: an open-source LMS for Bible schools — bilingual, scripture-aware, 4 weeks of real users

Vadym Arnaut — Thu, 21 May 2026 00:30:31 +0000

TL;DR. Equip is a free, open-source LMS built for Bible schools and small ministries. MIT-licensed. Bilingual Russian↔English out of the box — the same course renders in either language depending on who's reading. Self-hostable end-to-end on free tiers. 4 weeks in production: 14 real users, 3 published courses, 3 issued certificates. This post is what's in it, what's wired in, and how it's built.

Why this exists

Small Bible schools, home-church training programs, and missionary-prep tracks around the world run their coursework on paper, WhatsApp groups, or shared Google Sheets. The commercial LMSes either price out small ministries (Canvas, Blackboard), require an IT department to run (Moodle, Open edX), or fight the use case at every step. Most are built for K–12 or universities, not 30 students reading through Romans together.

I wanted an LMS that:

Costs zero to run for a 20–100 student school
Has no vendor lock-in (your data, your hosting)
Handles scripture correctly — more on this below, it turned out to be the most interesting constraint
Works in Russian and English without manual per-string translation
Is small enough that one nontechnical ministry admin can run it end-to-end

That's Equip. Live at equipbible.com.

Bilingual content, end-to-end

This is the feature that does the most work, so it goes first.

Russian and English UI ship together, but the more interesting decision is content. A teacher writes a course in their own language. When a student of the other language enrolls, every text field on every entity (course name, module title, chapter content, quiz question, quiz option, quiz explanation, assignment prompt) is auto-translated via Gemini Flash Lite and cached per (entity_type, entity_id, field, locale). The translation runs once per field and reads from cache thereafter. Cost per course is measured in cents.

The author always sees their own source-language content. The student always sees their target-language content. No "switch language to see English" toggle. No leaking source-locale strings. No [translation missing] placeholders.

Same /register page, two locales, rendered live by Equip:

The Cyrillic side isn't a different file or a different route. It's the same React tree with useTranslation(), plus the scripture passage in the left rail swapped from KJV (1769) to Synodal (1876) by a server-side substitution layer — see next section.

The scripture-preservation constraint

Most translation APIs (Gemini, GPT-4, DeepL) will happily paraphrase a Bible verse if you feed it into them as part of a longer paragraph. For a course where the exact wording of John 3:16 matters, that's a non-starter. "For God so loved the world" and "Because God loved the world this much" are not interchangeable in a Bible-study context, no matter how close the meaning.

Equip solves this outside the LLM:

Pre-process incoming HTML, detect <blockquote> + scripture-reference pairs.
Swap the verse text for an opaque ASCII placeholder (VERSE_<hex>).
Send the prose-with-placeholders to Gemini Flash Lite with a system prompt that lists "preserve placeholders verbatim" as a hard rule.
After the model returns, restore each placeholder with the canonical text from bundled translations: KJV 1769 for English, Synodal 1876 for Russian.

The model never sees the verse text. The translation never paraphrases scripture. Implementation lives in app/services/bible/substitution.py and is about 200 lines.

There's a fallback in the system prompt for paraphrased quotes that the substitution layer can't confidently match (similarity < 0.80 to canonical) — "leave the original verse text untouched." That covers content where the substitution layer can't reliably do its job.

What's wired in

Equip is small in scope but talks to a few external services where it makes sense to. Each one is a deliberate choice, not a default:

Service	What it does in Equip
YouVersion Platform API	Verse-of-the-Day card on the home dashboard. Reads the YV verse-of-the-day endpoint, caches the result per (locale, date). YV registration is on the non-commercial track, which is what shipped with our values from day one.
Gemini Flash Lite (Google AI)	Bilingual content translation pipeline (above). Flash Lite is overkill on quality and underkill on cost for surface translation; this is the sweet spot.
KJV 1769 + Synodal 1876	Bundled in the backend as JSON, served as the canonical scripture for the substitution layer. Public-domain, no API call.
Supabase Auth	Google OAuth + email/password. JWT verification server-side. The `auth.uid()` value flows through every RLS policy.
Datadog	Browser-RUM on the SPA, log intake from the FastAPI backend, four synthetics on the public surfaces. Free tier.
Resend	Transactional email (verify, password reset, certificate-ready notifications) from a verified `equipbible.com` domain. Free tier.
Sentry-class error attribution	Not Sentry itself — Datadog's RUM + log correlation does the same job for our scale, single vendor.

The pattern across all of these: pick a single best-fit service per layer, stay on free tiers as long as possible, never hide the integration behind a paywall.

What it does (the standard LMS surface)

Courses → modules → chapters, rich content via TipTap (callouts, audio, embedded YouTube, images), quizzes (multiple choice, true/false, short-answer, essay), assignments with a teacher grading queue, certificates with teacher approval, gradebook, cohorts, calendar, announcements.

The architecture, briefly

Layer	Stack
Frontend	React 18, TypeScript, Vite, Tailwind, shadcn/ui, TipTap, motion
Backend	FastAPI, Python 3.12, SQLAlchemy 2, Pydantic 2
Database	PostgreSQL on Supabase, RLS on every public table
Storage	Supabase Storage (avatars, course materials)
Deploy	Vercel — static SPA at equipbible.com, Python serverless at api.equipbible.com
CI/CD	GitHub Actions: lint, typecheck, 700+ backend tests, 220+ frontend tests, npm audit, pip-audit, Postgres schema smoke, CodeQL, OpenSSF Scorecard, Dependabot auto-merge for patch/minor
Monitoring	Datadog (RUM, logs, synthetics)

Total infra cost at current usage: $0. Vercel, Supabase, Datadog, and Resend free tiers carry the whole thing.

Mobile, too

No native app; responsive web from 360px wide. A native app is months of work that buys little at this scale.

State of production, 4 weeks in

Real numbers from the database as of this morning, not aspirations:

14 users (11 students, 2 teachers, 1 admin)
3 published courses, 1 in draft
10 modules, 28 chapters of actual content
21 enrollments across the 3 courses
6 chapters completed by active students
3 certificates issued (teacher-approved, full course completion)
9 quiz attempts submitted and graded

Each user signed up with a real email, enrolled in a real course, and in three cases finished one and received a teacher-signed certificate. End-to-end flow runs.

What's intentionally NOT there

No "Discover" feed or social layer. Students enroll because a teacher invited them, not because an algorithm recommended a course.
No live video conferencing. Use Zoom or Jitsi separately. Equip stores course-event entries with a meeting-URL field. That's the integration surface.
No mobile app. Responsive web works.
No monetization features. No paywalls, no premium tier, no "powered by" splash. MIT-licensed. Use it, fork it, deploy it.
No "AI assistant" widget. AI is in the translation pipeline as infrastructure, not in the UI as a feature. Bible-study students aren't asking for a chatbot.

How to actually use it

Two paths, depending on what you want:

Hosted at equipbible.com. Free. Sign up, you're in. Anyone can enroll in any published course. Teaching on the hosted instance is approval-based — the self-host path below has no such gate. No credit card.

Self-host your own instance. Clone the repo, point at your own Supabase project, deploy to Vercel. Bible schools that want their own URL, full data sovereignty, and isolation from other tenants get this. Total cost still $0 on the free tiers.

If you're a Bible school or ministry running coursework on Google Sheets and WhatsApp groups, this is for you. Either path works. Pick the one that matches how much technical setup you want to do.

What's next

Near-term on the published roadmap: teacher onboarding flow (the first-login /teacher page is too quiet right now), a completion-celebration moment (students don't know clearly when they finish a course), and a 15-minute self-host walkthrough for schools without a dev on staff.

Longer-term: more language pairs (Spanish + Portuguese for missionary contexts) via api.bible, in-platform certificate verification via signed JSON-LD, and a contribution path for translators to refine AI-translated content where wording matters most.

What I want to hear back

Especially from three groups:

Anyone running a small Bible school or ministry training program: what's blocking you from moving off your current setup? Particularly curious about Russian-speaking schools in CIS countries where the Synodal canonical-text handling matters.
Anyone who has built or contributed to a niche-domain LMS: what's the one constraint you wish you'd designed for from day one? I'd rather steal your lessons than learn them again.
Anyone considering forking Equip for a different niche (Sunday-school curriculum, a different religious tradition, secular adult-ed): tell me what'd need to change. Easier to plan the abstractions now than retrofit them later.

ArVaViT / equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

A free, open-source learning management system built for Bible schools church ministries, and nonprofit educational programs

Live demo · Roadmap · Contributing · Support · Changelog

Screenshots

Sign in (light)	Sign in (dark)
Account creation — student / teacher role picker	Mobile (390px)

Live at equipbible.com. Teacher and admin views (gradebook, course editor, analytics) are behind sign-in — create a free account to explore.

Why this project?

Equip is designed to change that:

Free forever — MIT-licensed, no paywalls, no "premium" tiers.
Simple to deploy — one-click Vercel deploy with a free Supabase database. No Docker, no servers to manage.
Built for small scale — optimized for 20-100 students, not…

View on GitHub

76 RLS policies rewritten in one migration: the auth.uid() init-plan trap in Supabase

Vadym Arnaut — Wed, 20 May 2026 23:48:33 +0000

TL;DR. If your Supabase RLS policies call auth.uid() directly inside USING(...) or WITH CHECK(...), Postgres re-evaluates the function once per row. Wrap it as (SELECT auth.uid()) and the planner hoists the call to a single init plan that runs once per query. Same logical query, different plan, different cost at scale. We had 76 policies doing this wrong on Equip. Supabase's own auth_rls_initplan advisor lint found every one of them.

Equip is an open-source LMS we run on equipbible.com — FastAPI backend, React frontend, Supabase Postgres with RLS on every public table. Migrations live in the repo as plain .sql files. Standard setup, nothing exotic.

A while back we ran Supabase's database advisor as part of a pre-deploy sweep and one warning stopped us:

auth_rls_initplan: Detects RLS policies that re-evaluate
auth functions for each row.

It listed 76 of our policies. Same warning every time, same root cause.

What `auth.uid()` actually does per row

A typical Equip policy at the time:

-- BEFORE: auth.uid() called for every row scanned
CREATE POLICY "assignments_update_teacher" ON public.assignments
FOR UPDATE TO authenticated
USING (
  EXISTS (
    SELECT 1 FROM public.profiles p
    WHERE p.id = auth.uid()
      AND p.role IN ('teacher', 'admin')
  )
);

That auth.uid() looks like a constant. It isn't. It's a Postgres function marked STABLE, which means within one query it returns the same value, but the planner has to be told it can hoist the call out of the per-row loop. By default it doesn't. Every row scanned during the policy check fires the function again, allocates the JWT context, reads the claim, returns it.

For a 50-row dev table you'd never notice. For a chapter_progress table with one row per (student × chapter), or a quiz_answers table that grows every time a student submits anything, it adds up fast.

The fix that takes ten characters

-- AFTER: auth.uid() runs once, planner caches the result
CREATE POLICY "assignments_update_teacher" ON public.assignments
FOR UPDATE TO authenticated
USING (
  EXISTS (
    SELECT 1 FROM public.profiles p
    WHERE p.id = (SELECT auth.uid())
      AND p.role IN ('teacher', 'admin')
  )
);

Wrapping the call in a subquery isn't stylistic. The planner treats (SELECT auth.uid()) as a subquery returning one row of one value, and pulls it out into an InitPlan that runs exactly once at the start of the query. Every row check then sees a literal, not a function call.

You can confirm this on your own database. EXPLAIN ANALYZE on the bare version shows a function call inside the filter. On the wrapped version it shows InitPlan 1 at the top and the filter references $0. Same query, different plan.

Supabase covers this under RLS performance recommendations, but it's easy to miss when you're writing policies by hand at the same pace you're shipping features.

Why we missed it for months

Honest moment: we shipped most of Equip's policies with the raw auth.uid() pattern. They worked. Every test passed. Production users (students, teachers, admins) couldn't tell the difference. We were nowhere near the row count where the per-row overhead would have shown up as user-visible latency.

That's the actual trap. The warning sign isn't "your app is slow." By the time it's slow you've already shipped a pile more policies in the same shape, because everything you wrote between then and now had no reason to fail. The trap is that this pattern works fine in dev and on a small prod, then quietly compounds when one table grows.

Two patterns reliably hit the cliff first in our experience:

Per-user write tables like chapter_progress or quiz_attempts. One row per (student × content), grows linearly with engagement.
Many-to-many junctions like enrollments. Scanned during nearly every authenticated read.

Anything else (small lookup tables, course catalogs, taxonomy) stays fast for a long time even with the bad pattern. So the early "we don't see it yet" reading is correct, but it's not informative. The pattern is structurally wrong, you just haven't hit the row count that exposes it.

How we caught it: the database advisor

The Supabase project dashboard has an Advisors tab. Open it on any Postgres project and one of the performance lints is auth_rls_initplan. It scans pg_policies, parses the qual and with_check expressions, and flags any direct auth.<function>() call that isn't wrapped.

Two ways to run it:

# Supabase CLI (v2.81.3+)
supabase db advisors

# Or via the dashboard:
# https://supabase.com/dashboard/project/<ref>/advisors/performance

If you've wired the Supabase MCP server into your dev environment, get_advisors returns the same list as a tool call you can run from an agent. Either way the output is a flat list of policy names. The migration itself is mechanical:

-- For each flagged policy: DROP + recreate with the wrapped call
DROP POLICY "<name>" ON public.<table>;
CREATE POLICY "<name>" ON public.<table>
FOR <command> TO <roles>
USING (<original expression with (SELECT auth.uid())>);

Our 20260421015755_rls_perf_cleanup_016_policies.sql did this 76 times in a single migration. Mostly find-replace with care to keep the original semantics intact.

The PL/pgSQL footgun nobody mentions

While you're already in there, one more thing: if you've abstracted any of this into a helper function (e.g. is_admin() to keep policies DRY), check the language declaration.

-- BAD: planner can't inline a plpgsql function, every call is opaque
CREATE FUNCTION public.is_admin() RETURNS boolean
LANGUAGE plpgsql STABLE AS $$
BEGIN
  RETURN EXISTS (
    SELECT 1 FROM public.profiles p
    WHERE p.id = (SELECT auth.uid()) AND p.role = 'admin'
  );
END $$;

-- GOOD: SQL functions get inlined into the policy at plan time
CREATE FUNCTION public.is_admin() RETURNS boolean
LANGUAGE sql STABLE AS $$
  SELECT EXISTS (
    SELECT 1 FROM public.profiles p
    WHERE p.id = (SELECT auth.uid()) AND p.role = 'admin'
  );
$$;

LANGUAGE sql + STABLE + a single SELECT lets Postgres inline the function body into the policy at plan time. EXPLAIN looks identical to inline EXISTS. Switch to LANGUAGE plpgsql and the planner treats it as an opaque call. Can't push predicates in, can't reorder joins, every row hits the function.

We don't use helpers in Equip yet, but multiple people in the Supabase community have hit this when extracting is_member_of(school_id) for multi-tenant setups. The helper looks right, the policy looks DRY, the EXPLAIN looks wrong.

What to do today, in order

Open your project's Advisors → Performance tab. Look for auth_rls_initplan. If the list is non-empty, you have the trap.
Write a single migration that DROPs and recreates the flagged policies with (SELECT auth.uid()) everywhere auth.uid() appears bare. Don't try to refactor the policies' logic at the same time. Pure mechanical change.
While you're in the advisor, glance at multiple_permissive_policies and policy_exists_rls_disabled. Both compound the same per-row cost. Multiple permissive policies on the same role + action each run separately, so two bad policies double the trap.
If you have helper functions in policies, verify each is LANGUAGE sql STABLE with a single SELECT body. Convert any plpgsql ones if you can keep the logic in pure SQL.

The advisor keeps flagging this on every new policy you write, so once you wire it into pre-merge checks (CI step, pre-deploy hook, or a habit on PR review) the trap doesn't come back.

What I want to hear back, especially from people running Supabase in production:

Has this lint caught anything for you besides auth.uid()? auth.jwt() ->> 'role' should hit the same code path but I haven't traced it directly.
If you've written is_member_of(...) helpers for multi-tenant RLS, did you keep them in SQL or move to plpgsql? Curious about the tradeoff at scale.
For anyone who left these unwrapped on purpose — what does that constraint look like? I can imagine a few cases where you'd want the per-row eval, but I can't think of any in policy code specifically.

ArVaViT / equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

A free, open-source learning management system built for Bible schools church ministries, and nonprofit educational programs

Live demo · Roadmap · Contributing · Support · Changelog

Screenshots

Sign in (light)	Sign in (dark)
Account creation — student / teacher role picker	Mobile (390px)

Live at equipbible.com. Teacher and admin views (gradebook, course editor, analytics) are behind sign-in — create a free account to explore.

Why this project?

Equip is designed to change that:

Free forever — MIT-licensed, no paywalls, no "premium" tiers.
Simple to deploy — one-click Vercel deploy with a free Supabase database. No Docker, no servers to manage.
Built for small scale — optimized for 20-100 students, not…

View on GitHub

4 footguns integrating YouVersion's new platform API — and a clean Verse of the Day

Vadym Arnaut — Fri, 15 May 2026 18:39:44 +0000

TL;DR. YouVersion opened its API in April 2026. We wired it into our open-source Bible LMS as a Verse of the Day card on the dashboard. Four small things in their API surface cost us time. Writing them up so you don't repeat them.

Equip is an open-source LMS for Bible schools (FastAPI + React + Supabase, MIT). A dashboard verse-of-the-day card is one of those quietly load-bearing features for a faith-shaped product — it gives the page a pastoral anchor on the right while keeping the actionable column primary, and creates a daily-return habit without screaming for engagement.

YouVersion just opened YouVersion Platform: 1,474 Bibles, 1,283 languages, REST API plus SDKs (Swift, Kotlin, React, React Native). Free for non-commercial use. So we plugged it in.

The endpoints are simple. The friction is in the small print.

Footgun #1: `/v1/bibles` returns 422 without `language_ranges[]`

First instinct after pip install httpx:

# Wrong. Will not work.
httpx.get("https://api.youversion.com/v1/bibles",
          headers={"X-YVP-App-Key": KEY})

Response:

HTTP 422 Unprocessable Entity
{"detail": [{"type": "missing",
             "loc": ["query", "language_ranges[]"],
             "msg": "Field required"}]}

The listing endpoint requires at least one ISO 639-3 language filter. We found that out the way everyone does — by reading the 422 body. Correct form:

httpx.get(
    "https://api.youversion.com/v1/bibles",
    params={"language_ranges[]": "eng"},   # eng, rus, ukr, etc.
    headers={"X-YVP-App-Key": KEY},
)

If you're calling from a JS client and reach for URLSearchParams, the brackets matter — language_ranges[] with the literal brackets works, language_ranges without them does not.

Side note while you're here: the auth header is X-YVP-App-Key, not Authorization: Bearer. The 401 you get from forgetting is generic enough that you'll sit there comparing your key character-by-character before going back to the docs. Pin the header name in the integration's docstring on day one.

Footgun #2: `all_available=true` reveals the real catalog

With language_ranges[]=eng,rus,ukr we got 11 Bibles back — all English (ASV, BSB, Geneva, CPDV, etc.). Zero Russian. Zero Ukrainian.

The marketing number is 1,474 translations. Where are they?

httpx.get(
    "https://api.youversion.com/v1/bibles",
    params={"language_ranges[]": "rus", "all_available": "true"},
    headers={"X-YVP-App-Key": KEY},
)

That returns 5 Russian Bibles: NRT (Новый Русский Перевод — the modern Russian we needed), three CARS variants, and CSLAV (church Slavonic). For Ukrainian: just UKRK 1905 — pre-revolutionary, hard for modern students. No modern Огієнко or UBIO in the platform yet.

The mental model: the listing endpoint without all_available shows what is enabled for your app key, not what exists in the platform. Fetching a passage via /bibles/{id}/passages/{ref} works for the broader catalog regardless of listing visibility — at least for non-commercial use as of this writing.

Worth two minutes verifying for your own keys before you build a UI that says "no Russian translations available." We almost did.

Footgun #3: `content` is HTML, even when you didn't ask

The passage endpoint is the cleanest part of the API. You hand it a Bible ID and a USFM ref:

GET /v1/bibles/143/passages/JHN.3.16
→ {
    "id": "JHN.3.16",
    "content": "<p>Ведь Бог так полюбил этот мир...</p>",
    "reference": "От Иоанна 3:16"
  }

Two things to notice. First, reference is localized to the Bible's language — "От Иоанна 3:16" for NRT, "John 3:16" for BSB, automatically. That is free i18n you would otherwise build yourself.

Second, content is HTML. Usually a thin  wrapper, sometimes with  markers, occasionally a chunk of whitespace bleeding from the source USFM. If you're rendering scripture in a plain-prose sidebar card, you have to strip:

def _strip_html(html: str) -> str:
    text = re.sub(r"<[^>]+>", "", html)
    # Some responses pack newlines inside <p> from the source markup —
    # collapse whitespace so the card renders as a single tidy line.
    text = re.sub(r"\s+", " ", text).strip()
    return text

YouVersion never injects user-supplied markup into content (it is their licensed text — they control the source), so a regex strip is safe here. Do not copy this pattern verbatim to places where the content origin is untrusted.

Footgun #4: their VOTD endpoint exists, but you cannot pick the verses

YouVersion ships /v1/verse_of_the_days/{day} that returns their curated verse for that day of year:

GET /v1/verse_of_the_days/135
→ { "day": 135, "passage_id": "ISA.12.2" }

Useful if you want to mirror the YouVersion app behavior exactly. But it is their selection — you cannot pass a tag, theme, or audience filter. For an LMS aimed at Bible-school students we wanted curated passages that bias toward doctrinally-neutral, evergreen, ecumenical scripture: no denomination-specific proof texts, nothing that translates badly into Russian or Ukrainian.

So we rolled our own list — 250 references covering salvation, hope, comfort, love, faith, wisdom, prayer, and perseverance. Grouped by canon section: Gospels, Acts, Pauline epistles, Hebrews and General epistles, Revelation, Psalms, Proverbs, Wisdom and Prophets, Torah and Historical books, Job and Minor prophets.

The shape that worked: deterministic by day, cached by day

Selection is a one-liner:

def _pick_reference(date: dt.date) -> str:
    """Everyone, everywhere, sees the same verse on a given UTC date."""
    return _VERSES[date.toordinal() % len(_VERSES)]

toordinal() gives a globally monotonic integer. Modulo the catalog size, you get a cycle that takes about eight months to repeat — long enough that no student sees the same verse twice in a school term. No randomness, no per-user state, no cache invalidation drama. The verse on a given date is the same in every browser on every device.

Cache is a process-local dict keyed on (date_iso, locale). Evict any entry whose date is not today on every write — the cache never holds more than len(supported_locales) entries. We support en and ru, so at most two entries deep:

with _CACHE_LOCK:
    for k in list(_CACHE):
        if k[0] != date_iso:
            _CACHE.pop(k, None)
    _CACHE[cache_key] = verse

Two YouVersion calls per Python process per day. If the API key is unset (CI, fresh local dev), the service raises a typed exception and the route returns 404. The frontend treats 404 as "hide the card silently."

Never block the dashboard on a third party. Same playbook as every other optional widget — but worth restating, because Bible-school students will not forgive a broken homepage on a Sunday.

A few things to weigh before you adopt this

Non-commercial lock-in is real. You agree at app registration. Future paywalls, ads, or paid tiers revoke API access. For an open-source LMS this is fine. For a commercial product, model around it on day one — your BibleProvider should be an adapter, not a hard import.
Russian coverage is solid, Ukrainian is sparse. Modern Russian is there (NRT). Ukrainian audiences still need a fallback layer for modern translations.
The SDKs ship UI components, not just data clients. If you're using their React SDK you may not need most of the integration code above. We chose the REST API because Verse of the Day in our app is server-cached and renders in a slot we already control.

What I'd ask the room

If you have integrated YouVersion Platform yourself — how are you handling the locale → bible_id mapping when there are multiple translations in the same language? We pick one per locale (en → BSB, ru → NRT) because Verse of the Day is a one-card, one-rendering surface. For a reading-plan flow where users want to switch translations on the fly the design space is wider — curious what others have done.

For anyone building Christian software in 2026 — does the non-commercial lock-in change how you architect, or do you accept it and never plan to monetize? Genuinely curious whether anyone has built around the constraint.

And for the YouVersion Platform team if you read this: an Accept: text/plain toggle on /passages would let consumers skip the strip-HTML dance. Probably trivial on your side, ergonomic win on ours.

ArVaViT / equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

A free, open-source learning management system built for Bible schools church ministries, and nonprofit educational programs

Live demo · Roadmap · Contributing · Changelog

Why this project?

Equip is designed to change that:

Free forever — MIT-licensed, no paywalls, no "premium" tiers.
Simple to deploy — one-click Vercel deploy with a free Supabase database. No Docker, no servers to manage.
Built for small scale — optimized for 20-100 students, not enterprise pricing models.
Contributor-friendly — clear docs, conventional commits, issue templates, and a welcoming community.

Features

Area	What you get
Course authoring	Courses, modules, chapters, rich content blocks (TipTap editor with images, YouTube, callouts, audio)
Assessments	Multiple-choice, true/false, short-answer, and essay

…

View on GitHub

Two days lost to PGRST116: when Supabase RLS hides a successful write

Vadym Arnaut — Wed, 13 May 2026 19:36:01 +0000

TL;DR. Our Supabase upsert wrote the row. The chained .select().single() returned PGRST116. The wrapper read that as a failed write. The frontend retried. The retry was wrong. Two days to find why.

We've been running an LMS on Supabase for the past several months — auth, RLS on every table, FastAPI talking to Postgres. The bug below cost us two days last quarter, and the fix changed how we read PGRST116 in our wrapper.

The setting

We have a quiz_attempts table. Each attempt gets created on quiz start, updated as the student progresses. The update is an upsert because a retry of the same attempt_id should patch the existing row, not insert a duplicate.

const { data, error } = await supabase
  .from('quiz_attempts')
  .upsert({ id, student_id, quiz_id, attempt_count })
  .select()
  .single();

The .select().single() chain returns the upserted row so we can show the student their new state.

RLS policies, simplified:

create policy "students write their own attempts"
on quiz_attempts for all to authenticated
using (student_id = auth.uid())
with check (student_id = auth.uid());

create policy "students read their own attempts"
on quiz_attempts for select to authenticated
using (student_id = auth.uid() and is_visible = true);

The SELECT policy carries an extra is_visible check that the write policy doesn't. That asymmetry is the seam the bug walks through.

The bug

A trigger on quiz_attempts flips is_visible to false under a corner case (timing relative to a parallel write from an admin tool — the specifics aren't the point). The student's upsert committed: their fields were written, the row is theirs.

Then .select().single() runs. The SELECT policy applies. is_visible = false. PostgREST returns:

{
  "code": "PGRST116",
  "details": "Results contain 0 rows",
  "message": "JSON object requested, multiple (or no) rows returned"
}

Our runtime wrapper auto-threw on any .error. To the upstream code, this looked identical to a failed upsert. The frontend retried with the same payload. The retry hit the same trigger. The user state diverged from the DB state. Etc.

Why this was hard

PGRST116 has two completely different meanings when it comes after a mutation:

The upsert truly failed — constraint violation, missing required field, RLS denied the write.
The upsert succeeded — RLS just hid the returned row from the caller.

The wrapper conflated them. The PostgrestError code is identical. The HTTP status is identical (406). The only difference lives in the database, which the client can't see.

Two days of logs because we kept treating "no row returned" as "no row written."

The fix

Three changes.

1. Don't auto-throw on PGRST116 from a .select().single() chained off a mutation. Treat it as ambiguous and route to a separate branch:

async function safeUpsertReturning(query) {
  const { data, error } = await query;
  if (!error) return { data, error: null };
  if (error.code === 'PGRST116') {
    // The mutation may have succeeded; we just can't read the row.
    return { data: null, error: null, hidden: true };
  }
  throw error;
}

2. Service-role verification. When the wrapper returns hidden: true, the backend does a service-role read by id to confirm whether the row actually exists. Yes → success-without-readback (treat as written). No → real failure, propagate. The client never branches on this directly.

3. Observability tying client errors to DB state. Every PGRST116 from the wrapper emits a structured event with the query shape and request id. Server-side, we log the same id with the actual row state visible to service role. Correlating the two would have surfaced the mismatch on day one.

What I'd tell past-us

PGRST116 is not a write error. It's a visibility error.

Your wrapper, your error handler, your retry logic — each should know which one it's seeing. If your stack can't tell the difference, you're going to retry successful writes. The kind of bug that produces is the kind where the symptom and the cause are twelve layers apart.

What I want to hear back

Do you separate "write failed" from "write succeeded but I can't read it" in your Supabase code? What does the wrapper look like?
Has anyone built a Postgres-side audit trigger that captures "row was written but RLS hid it from the writer"? Curious about the shape.
For service-role verification — anything safer than select(*).eq('id', id) you've used?

The project that runs this stack is open source:

ArVaViT / equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

A free, open-source learning management system built for Bible schools church ministries, and nonprofit educational programs

Live demo · Roadmap · Contributing · Changelog

Why this project?

Equip is designed to change that:

Free forever — MIT-licensed, no paywalls, no "premium" tiers.
Simple to deploy — one-click Vercel deploy with a free Supabase database. No Docker, no servers to manage.
Built for small scale — optimized for 20-100 students, not enterprise pricing models.
Contributor-friendly — clear docs, conventional commits, issue templates, and a welcoming community.

Features

Area	What you get
Course authoring	Courses, modules, chapters, rich content blocks (TipTap editor with images, YouTube, callouts, audio)
Assessments	Multiple-choice, true/false, short-answer, and essay

…

View on GitHub

The 3 i18n mistakes every open-source LMS makes

Vadym Arnaut — Wed, 13 May 2026 03:21:32 +0000

TL;DR. Every open-source LMS treats internationalization as one problem. It's three. UI strings, user-generated content, and canonical artifacts each need a different mechanism. Most codebases collapse them into one — that's the bug.

We've been building an open-source Bible school LMS for about 5 months. It runs in Russian and English (Ukrainian coming), with auto-translated user content and canonical-text preservation for scripture quotes. Building this forced me to look at how Moodle, Open edX, Canvas LMS, and Chamilo handle the same problem.

The pattern is the same in all of them — and was the same in ours when we started.

Mistake #1: User-generated content treated like UI strings

Every LMS has solid gettext-style infrastructure for UI strings. "Sign in", "Course catalog", "Submit assignment" — these live in .po files (Moodle), Transifex (Open edX), i18n-js (Canvas), YAML (Rails-based). A translator translates the file once. Done.

User-generated content is a different problem entirely. When a teacher authors a course in Russian, the title — "Введение в Послание к Римлянам" — is a row in courses.title. An English-speaking student opens the catalog and sees Cyrillic. The UI is translated. The content isn't.

	UI strings	User-generated content
Examples	"Sign in", "Submit"	Course title, lesson body, quiz question
Source	Fixed catalog of values	Unbounded user input
Tool	gettext / Transifex / YAML	Runtime translation (Google, DeepL, Gemini)
When	Build / release time	Runtime (lazy or eager)
Storage	Locale file	Separate cache table
Common bug	None major	Treated like UI strings → only one language ever shown

Moodle's workaround is the multilang filter — you wrap content in …… and a filter shows the matching one. This is a 2008 solution. It puts the entire burden on the teacher: they must author every piece of content twice, in every language. Most don't, and the platform falls back to "show whatever the teacher wrote first."

The shape of the right answer is a separate translation cache:

CREATE TABLE content_translations (
  entity_type  TEXT NOT NULL,    -- 'course', 'lesson', 'quiz_question'
  entity_id    UUID NOT NULL,
  field        TEXT NOT NULL,    -- 'title', 'description', 'body'
  locale       TEXT NOT NULL,    -- 'ru', 'en', 'uk', 'es'
  content      TEXT NOT NULL,
  source       TEXT NOT NULL,    -- 'human' | 'machine' | 'canonical'
  cached_at    TIMESTAMPTZ NOT NULL,
  PRIMARY KEY (entity_type, entity_id, field, locale)
);

Teacher authors in one language. A translation worker fills in the others lazily (first request) or eagerly (on publish). The course-detail endpoint joins on (entity_type, entity_id, field, viewer_locale).

The architectural decision: content is not a UI string and cannot live in the same system. If your LMS uses gettext for "Submit assignment" and the same mechanism for course titles, that's the bug.

Mistake #2: No accommodation for length variance

English is dense. Russian runs ~25–30% longer for the same meaning. German is comparable. Finnish is worse. Arabic is shorter — and right-to-left, its own category.

Most LMS UIs are designed in English. Buttons that fit "Save" don't fit "Сохранить". Nav tabs that fit "Courses" wrap to two lines for "Курсы и обучение". Mobile breaks first.

Part of the fix is CSS:

/* Reserve space against the longer-language baseline */
.action-button {
  min-width: 8rem;
  white-space: nowrap;
  overflow: hidden;
  text-overflow: ellipsis;
}

/* Tabular content: don't let translation reflow the grid */
.lesson-list-cell {
  min-height: 4.5rem;  /* fits 2-line Russian titles without shift */
}

But the real fix is testing every screen in your longest-content language, not just English. Most teams hire designers who only see the English mock and don't realize their "Continue" button is broken in Russian until a user reports it.

What helped us: a Storybook locale switcher defaulting to Russian (not English), and a Playwright snapshot suite that screenshots both locales. The first commit that breaks Russian layout is caught in CI, not by a user.

Mistake #3: Canonical content forced through translation

This is the bug that motivated our entire content-translation rewrite.

A teacher in Russian writes: "Послание к Римлянам 8:28 говорит, что все содействует ко благу". The course gets auto-translated to English. Naively you send the whole string to Google Translate or DeepL, and you get back: "Romans 8:28 says that everything works together for good." That's almost a real Bible verse — but it isn't quoting any actual translation. It's a translation of a translation.

You don't want that. You want the actual KJV (or NIV, or ESV) text of Romans 8:28 spliced in.

Same problem exists everywhere there's canonical content:

Programming courses with code samples (don't translate the variables!)
Math curricula with formulas
Legal courses citing statutes
Medical courses citing clinical-trial registries
Literature courses with original-language quotes

Most LMSes don't separate "translatable prose" from "canonical artifact" — so when they auto-translate, the canonical content gets mangled or invented.

Our pattern: parse the source for canonical references, replace each with a placeholder token, translate the surrounding prose, then substitute the canonical text back from a separate lookup.

def translate_with_canonical_preservation(
    text: str, source_lang: str, target_lang: str
) -> str:
    # 1. Find canonical references in either language
    refs = extract_bible_refs(text, lang=source_lang)
    # [{"raw": "Послание к Римлянам 8:28", "book": "ROM", "chapter": 8, "verses": [28]}]

    # 2. Replace each with a unique placeholder
    placeholders = {}
    for i, ref in enumerate(refs):
        token = f"⟦CANON_{i}⟧"
        placeholders[token] = ref
        text = text.replace(ref["raw"], token, 1)

    # 3. Translate the token-bearing string
    translated = translate(text, source_lang, target_lang)

    # 4. Substitute the canonical text back, looked up in the target translation
    for token, ref in placeholders.items():
        canonical_text = lookup_canonical(ref, target_lang)  # KJV for en, Synodal for ru
        translated = translated.replace(token, canonical_text)

    return translated

How `extract_bible_refs` handles the cross-language book-name matrix

Detection is a regex over a normalized book-name dictionary. Each canonical book has an entry like:

BOOKS = {
    "ROM": {
        "en": ["Romans", "Rom", "Rom."],
        "ru": ["Послание к Римлянам", "Римлянам", "Рим", "Рим."],
        "uk": ["Послання до Римлян", "Римлян", "Рим"],
    },
    # ... 65 more books
}

The regex is built per request as (book_alias_1|book_alias_2|...)\s+(\d+):(\d+)(?:[-–](\d+))? so it accepts: Romans 8:28, Послание к Римлянам 8:28, Рим 8:28, Рим. 8:28, Romans 8:28-29, Romans 8:28a.

Sundry edge cases: chapter-only refs (Romans 8 — whole-chapter), letter suffixes (8:28a — first half of verse), em-dash vs hyphen, non-breaking spaces. Each lives in unit tests.

lookup_canonical pulls from a canonical text table keyed by (book, chapter, verse_start, verse_end, translation). Cache the final translated string keyed by (entity_id, field, locale) per Mistake #1.

This is ~400 lines we wouldn't have written if any of the LMSes we looked at had solved this for us.

What I want to hear back

These are the three patterns I keep seeing. They're not the only ones (cache invalidation on edits, RTL layout, Slavic plural forms — separate posts), but they're the ones every general-purpose LMS skips.

If you've shipped i18n in an LMS, education platform, or any content product:

Do you separate UI strings from content? What's your storage shape?
How do you handle length variance? Do you test the long-language layout in CI?
Do you have canonical content that mustn't be translated? Code samples, equations, citations? How are you handling it?

Curious where teams have landed. The patterns above are our current best, not our last word.

The project that drove all of this is open source:

ArVaViT / equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

A free, open-source learning management system built for Bible schools church ministries, and nonprofit educational programs

Live demo · Roadmap · Contributing · Support · Changelog

Screenshots

Sign in (light)	Sign in (dark)
Account creation — student / teacher role picker	Mobile (390px)

Live at equipbible.com. Teacher and admin views (gradebook, course editor, analytics) are behind sign-in — create a free account to explore.

Why this project?

Equip is designed to change that:

Free forever — MIT-licensed, no paywalls, no "premium" tiers.
Simple to deploy — one-click Vercel deploy with a free Supabase database. No Docker, no servers to manage.
Built for small scale — optimized for 20-100 students, not…

View on GitHub

DEV Community: Vadym Arnaut

I sent HTTP QUERY through the real internet. The smarter the layer, the harder it broke.

The edge decides, and it's a coin toss

The same list, written before QUERY existed, is everywhere

I made a real cache store QUERY. It served the wrong answer.

The good news: your code is already fine

What's actually new here

What I'd want to hear back

ArVaViT / http-query-lab

Empirical tests of the new HTTP QUERY method (RFC 10008) against real clients, frameworks, and production infra

http-query-lab

Headline: Vercel's default bot mitigation treats QUERY as a bot signal

HTTP finally shipped QUERY. I fired it at production and the edge called it a bot.

The setup

The runtimes are ready

Then the edge called it a bot

Two more footguns before you ship QUERY

What I'd want to hear back

ArVaViT / http-query-lab

Empirical tests of the new HTTP QUERY method (RFC 10008) against real clients, frameworks, and production infra

http-query-lab

Headline: Vercel's default bot mitigation treats QUERY as a bot signal

Three dumb ways our prod got slow (and not one was a slow algorithm)

1. The 30-second timeout that was actually two minutes

2. We shipped KaTeX TWICE, to people who have no math

3. We built tens of thousands of objects to draw a few hundred rows

The thread tying it together

ArVaViT / equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

Screenshots

Why this project?

I had real backend auth. The browser just walked around it.

Hole #1 — the answers were just... readable

Hole #2 — they could WRITE things they shouldn't

The lesson I wish I'd had on day one

ArVaViT / equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

Screenshots

Why this project?

I ran 4 AI agents on yesterday's PRs. Two real security bugs surfaced.

The four agents

The audit's haul: two real bugs

Critical: PyJWT decode does not validate iat

High: a test that was passing by insertion order

Why specialist agents beat one generalist

What this is not

ArVaViT / equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

Screenshots

Why this project?

There is no source language: a manifesto for symmetric multilingual content

Locale is just a column

What this fixes that you can name

What stays true from before

The principle, generalized

How to verify you have the same bug

Bigger than i18n

ArVaViT / equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

Screenshots

Why this project?

The auth_rls_initplan linter has a blind spot: SECURITY DEFINER bodies

What it doesn't see

The fix is the same wrap, one level deeper

How to find them

Equip: an open-source LMS for Bible schools — bilingual, scripture-aware, 4 weeks of real users

Why this exists

Bilingual content, end-to-end

The scripture-preservation constraint

What's wired in

What it does (the standard LMS surface)

The architecture, briefly

Mobile, too

State of production, 4 weeks in

What's intentionally NOT there

How to actually use it

Critical: PyJWT `decode` does not validate `iat`

What `auth.uid()` actually does per row

Footgun #1: `/v1/bibles` returns 422 without `language_ranges[]`

Footgun #2: `all_available=true` reveals the real catalog

Footgun #3: `content` is HTML, even when you didn't ask

How `extract_bible_refs` handles the cross-language book-name matrix