Repository navigation
feat: add support for D1 Sessions API to mitigate stale data returned from replicas - #813
kossnocorp wants to merge 12 commits into
Conversation
b8f635e to
ff403b4
Compare
|
0f6dfa8 to
ca8896e
Compare
|
@yangshun thank you for the heads-up! |
552cda1 to
6bd4980
Compare
Brooooooklyn
left a comment
There was a problem hiding this comment.
Thanks for this, and for the careful write-up on replicas. The core runtime change is small and mostly right: outside a request, db still starts on primary for each access, auth keeps its own primary client, the new module adds no heavy imports, and the unit tests pass.
Requesting changes for:
| Level | Issue |
|---|---|
| medium | The docs middleware's setSession() throws when a loader that used db makes a server-side fetch from void/client (same request scope) |
| medium | The cookie and both-transports recipes turn off ISR and shared caching for every route |
| low | The generated .void/db.d.ts doesn't match the published void/db types (getBookmark generic, DbSessionStart) |
| low | Any property read or await on db locks setSession(); unclear error outside the request scope; constraint typos compile |
| low | defer() note, bookmark input note, test timeouts, placeholder |
Missing tests: the published module's out-of-scope path (each access uses first-primary) and the getBookmark(client) error for a client not backed by a session.
Also: the branch is behind main and needs the rebase requested earlier. The playground is a scope call for maintainers; trimming it and its browser suite would make it easier to maintain.
| // Framework adapters do not always enter Void's request scope. Without a | ||
| // shared session, each operation starts on primary to preserve fresh reads. | ||
| () => createPrimaryDb(requireD1()), | ||
| d1Init, |
There was a problem hiding this comment.
Low — any property read on db counts as "first use".
The proxy get trap builds the client (and so calls withSession()) for every property, including then and symbols. So const f = db.select, logging db, await Promise.resolve(db), or return db from an async function all open the session, and a later setSession() throws. Users will read "before the first use of db" as "before the first query".
Suggestion: open the D1 session lazily (hand drizzle a small D1-shaped wrapper whose prepare/batch/exec call getSession() when they run), or at least don't build the client for then and symbol keys. The generated module in plugin-drizzle.ts has the same behaviour.
| export function createD1SessionAccess(bindingName: string): DbSessionAccess { | ||
| const key = {}; | ||
|
|
||
| function state(): DbRequestSession { |
There was a problem hiding this comment.
Low — unclear error outside Void's request scope.
state() passes no out-of-scope callback, so setSession() and getBookmark() throw env: Request-scoped resource is unavailable outside a runtime handler.. D1 apps on Nuxt/Analog do run outside that scope (nitro.ts adds the scope plugin only for non-sqlite dialects).
Suggestion: throw a db:-specific error that points to createDb(env.DB, { session }) plus getBookmark(client), or return null from getBookmark() there.
| import type { DrizzleD1Database } from 'drizzle-orm/d1'; | ||
| import { getRuntimeRequestResource, requireRuntimeBinding } from '../env/runtime.ts'; | ||
|
|
||
| export type DbSessionStart = D1SessionConstraint | (D1SessionBookmark & {}); |
There was a problem hiding this comment.
Low — constraint typos now compile.
D1SessionConstraint | (D1SessionBookmark & {}) is just string, and createDb's session option changed from D1SessionConstraint to this type. So 'first-primay' or 'primary' type-check and are sent to D1 as a bookmark. This PR also removes the old @ts-expect-error case in db-session.typecheck.ts that caught this.
Suggestion: keep & {} for editor completion, but in setSession/createDb reject strings that start with first- and are not one of the two constraints, and add a test for it.
| ...(dialect === 'sqlite' | ||
| ? [ | ||
| 'export declare function setSession(start: D1SessionConstraint | (D1SessionBookmark & {})): void;', | ||
| `export declare function getBookmark(client?: ${type}<${schemaType}>): D1SessionBookmark | null;`, |
There was a problem hiding this comment.
Low — the generated getBookmark is narrower than the published one.
Here client is typed DrizzleD1Database<Schema> (the app's schema only), while runtime/db/index.ts is generic over TSchema. With the generated .void/db.d.ts, getBookmark(createDb(env.OTHER_DB)) fails with TS2345.
Suggestion: emit getBookmark<TSchema extends Record<string, unknown>>(client?: DrizzleD1Database<TSchema>). Please also add a check that type-checks the generated d.ts, not only the source module.
On your thread just above: in Void the sqlite dialect always means D1 (the virtual module is built on drizzle-orm/d1, and the node target blocks void/db), so I don't think a separate void/d1 is needed.
| path: '/', | ||
| }); | ||
| } | ||
| c.header('Cache-Control', 'private, no-store'); |
There was a problem hiding this comment.
Medium — this recipe turns off ISR and shared caching for the whole app.
This is global middleware with no path filter. After next() it always sets Cache-Control: private, no-store (this replaces whatever the route set) and a Set-Cookie whenever there is a bookmark. In @void/isr, hasSharedCacheOptOut treats either one as an opt-out, so every ISR or cached route stops caching. The "Supporting both transports" recipe has the same problem.
Suggestion: limit it to the paths that need read-your-writes (as the header recipe does with /api/), don't replace a Cache-Control the handler already set, and say clearly that the routes it covers are not cached.
| Bookmarks do not affect cached responses. Disable ISR for pages that require fresh reads (`export const revalidate = 0` in the page's `.server.ts` file), and do not serve these requests from shared response caches. | ||
| ::: | ||
|
|
||
| Use middleware to set the default `db` session before your handlers or Pages loaders run, and return its bookmark after their queries. For a browser app, a cookie carries it through redirects and navigation: |
There was a problem hiding this comment.
Low — defer() queries miss the bookmark.
Pages defer() data streams after the response is returned, so the middleware reads getBookmark() before those queries finish. One sentence would cover it: queries inside defer() callbacks don't update the returned bookmark, so do writes that need read-your-writes before the loader returns.
| import { getBookmark, setSession } from 'void/db'; | ||
|
|
||
| export default defineMiddleware(async (c, next) => { | ||
| setSession(getCookie(c, 'db-bookmark') ?? 'first-unconstrained'); |
There was a problem hiding this comment.
Low (not proven) — the bookmark comes from the client.
The cookie or header value goes straight to setSession(). Cloudflare's own examples do the same, so this isn't a blocker. But workerd keeps the bookmark that sorts highest, so a bad value that sorts above real ones never gets replaced and stays in the cookie. A short note (check the shape, fall back to 'first-unconstrained' on a bookmark error, or name the cookie per database) would help.
| </p> | ||
| <p> | ||
| <strong>Related:</strong>{' '} | ||
| <a href="https://github.com/voidzero-dev/void/issues/783">Issue #783</a> | PR #XXX: TBD |
There was a problem hiding this comment.
Nit: leftover PR #XXX: TBD placeholder. Link #813 or remove it.
| await route.continue({ headers }); | ||
| }); | ||
| await page.getByRole('button', { name: 'Run trials', exact: true }).click(); | ||
| await expect |
There was a problem hiding this comment.
Low — likely to fail randomly. This expect.poll (and the one at line 299) uses Vitest's default 1s timeout, but it waits on a POST with a D1 write, a 303 GET, and a second intercepted POST in dev mode. Please pass { timeout: 30_000 } like the other polls in this file.
More broadly, this suite builds and runs the playground twice and mostly checks the demo UI. The README says local Miniflare can't show the replica lag, so both variants pass here. Cutting it to one mode with a few API-level checks (POST → 303, cookie/header set) would keep the void/db coverage and keep the test run fast.
|
@Brooooooklyn thank you for the review. I'm looking into it. What do you think about making replicas opt-in? I can make the change disabling it in the same PR. |
|
Thanks! Yes, let's make replicas opt-in here. Please add a config option, have provisioning skip Both provisioning paths set it today:
The review comments above still apply, since the session helpers are still useful once replicas are turned on. |
a364521 to
ae21985
Compare
This PR closes #783.
It adds two new primitives into D1
void/dbthat utilize D1 Session API:getBookmark- returns the current session bookmarksetSession- starts a new session from a previous bookmark.Using these allow to solve the D1 Replicas problem in the scenario
read OLD -> write NEW -> read OLDand ensure sequential consistency.Warning
Using Sessions API requires understanding of the problem, introduction of a middleware and in case with client requests, using a custom fetch wrapper.
There's no plug-in-play solution that would make it work automatigally, and to completely remove the possibility of users seeing stale data requires either explicit reading from primary or complex session coordinator code.
I suggest to consider disabling replicas by default and designing a thoughtful API on top of these primitives that would provide great DX for users that opt-into using replicas.
See guides for more information and usage examples:
TL;DR;
To utilize Sessions API the user has to create a middleware:
To make it work with client requests, instead of the cookie (or along with the cookie transport), the devs should use a header, e.g.,
X-DB-Bookmarkand make requests through a wrapper that sets the bookmark.Why disabling replicas?
TL;DR; replicas are not safe and might result in support tickets, bugs and security issues when enable unknowingly.
Enabling them by default creates two problems not present in a default D1 setup and not common in other environments:
User might see a stale data right after they perform a write request.
User might see old data after seeing a new one.
An action triggering an account suspension might not propagate the account state and allow already suspended account to perform an action they should not be able. See Avoid stale reads with a primary-first session.
While the first two are annoyances and just a source of support requests, the last one is a security issue.
The fact that we enable replicas by default is hidden in the documentation and the user, even experienced with D1, could get caught by surprise and deploy unsafe code unknowingly.
Making it opt-in would allow devs that want/need replicas to understand cons and decide if they want it. Those who decide to opt-in will keep in mind these nuances and work around them. If they need the advantage that replicas provide, they will be happy to use said APIs regardless how awkward they are and how many docs they have to read.
For some apps it would be completely normal, but not for all.
Why not incorporate a bulletproof solution into Void?
The problem is that every query could produce fresh bookmark, even a read. So we have to track all request bookmarks and resolve the newest one.
The single cookie approach described in the guide breaks with multiple requests where a newer request could overwrite a fresh bookmark with an older one (i.e. dashboard).
So we'll have to track every query bookmark and store each in a separate cookie, so a middleware could resolve the freshest one. It might lead to hitting server/browser limits on the cookies number and break. Not to mention overhead of carrying these cookies with every request.
A built-in multi-cookie solution could work out and be a good default middleware for users that opt-in and ok with a possibility that the describe problems might appear.
But adding this overhead and still not giving 100% guarantee doesn't sound like a good default.
Reproduction
In cases where primary D1 is deployed to say
WEURbut the nearest edge isSINright after write, theSINreplica might not get the update fast enough and the user will see data before edits.Unless you're in Europe, where the primary D1 is deployed, you can see the problem in the playground (you might not have the access, ping me): https://voidzero-void-d1-bookmarks.skoss-individual-account.workers.dev/without-bookmark?experiment=immediate&trials=20&pressure=0.5&size=0.5&probes=20
To reproduce:
In "Read-only routing baseline" section click "Run probes" button. Repeat until you see the replica region closest to you (
replica / APAC / SINin my case:Then go a section below "Write/read experiment" and set:
Press "Run Trials" button. Unless you're unlucky or D1 got significant replication pressure and switched from replica to the primary D1, you'll see some of the requests getting stale data (stale data is only possible on a replica,
SINin my case):Depending on your region and current state of D1 instance you might not see stale data at all. If you see that read target is
primary / WEURwait for a 1-2 minutes and start from 1. You can also increase replication pressure a bit. A high pressure makes D1 switch to primary and only hit replicas occasionally. Most likely you will encounter a network error caused by D1 being overwhelmed.The working solution is on the "Manual bookmark" page where data is always fresh: https://voidzero-void-d1-bookmarks.skoss-individual-account.workers.dev/with-bookmark?experiment=immediate&trials=20&probes=20&pressure=0.5&size=0.5