diff --git a/docs/guide/database/d1.md b/docs/guide/database/d1.md index cb3836df1..4e2f1c4e8 100644 --- a/docs/guide/database/d1.md +++ b/docs/guide/database/d1.md @@ -43,7 +43,15 @@ await db.batch([ Void enables [D1 read replication](https://developers.cloudflare.com/d1/best-practices/read-replication/) when it provisions a database. To enable it on an existing database, run `void deploy --platform cloudflare --provision`. Queries through `db` from `void/db` use a D1 session for each Void request, so reads can run near the request and later queries in that request see at least the same data. Framework handlers without Void's request scope start each database operation on the primary. `createDb` starts a replica-capable session for the binding you pass it. -Replicas can lag between requests. Authentication checks use the primary so a lagging replica can't accept a revoked session. For other reads that need the latest primary data, create a client inside the request: +::: warning +Replicas can lag between requests. [Carry a bookmark](#cross-request-bookmarks) to preserve previously observed database state, or use a [primary-first session](#reading-from-the-primary) when you need the latest primary data. +::: + +For raw D1 calls or another query library, use `withSession()` to read from replicas. A bare D1 binding reads from the primary. + +### Avoid stale reads with a primary-first session {#reading-from-the-primary} + +Authentication checks use the primary so a lagging replica can't accept a revoked session. For other reads that need the latest primary data, create a client inside the request: ```ts import { users } from '@schema'; @@ -59,7 +67,221 @@ export const GET = defineHandler(async () => { With `session: 'first-primary'`, the first query reads from the primary and later queries see at least the same data. The default, `'first-unconstrained'`, allows the first query to use a replica. -For raw D1 calls or another query library, use `withSession()` to read from replicas. A bare D1 binding reads from the primary. +### See your writes in subsequent requests {#cross-request-bookmarks} + +To make a read after a save see that save in a later request, carry a [D1 bookmark](https://developers.cloudflare.com/d1/best-practices/read-replication/#start-a-session-from-previous-context-bookmark) between requests. A bookmark allows D1 to use a replica that has caught up to at least the previously observed database state. + +::: warning +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: + +Local server-side requests through `void/client` share that session. If middleware runs again, repeating an already satisfied session requirement preserves the session and its database progress. For an independent primary-first read or a newer bookmark after using `db`, use `createDb` instead. + +::: warning +Concurrent responses can overwrite this cookie with an older bookmark. The [header-based recipe](#api-requests-with-concurrent-clients) retains the newest bookmark across concurrent API responses. Clearing or expiring bookmark storage starts a new bookmark chain. +::: + +::: note +To use cookies and API headers together, see [Supporting both transports](#supporting-both-transports). +::: + +```ts +// middleware/01.database.ts +import { getCookie, setCookie } from 'hono/cookie'; +import { defineMiddleware } from 'void'; +import { getBookmark, setSession } from 'void/db'; + +export default defineMiddleware(async (c, next) => { + setSession(getCookie(c, 'db-bookmark') ?? 'first-unconstrained'); + await next(); + + const bookmark = getBookmark(); + if (bookmark) { + setCookie(c, 'db-bookmark', bookmark, { + httpOnly: true, + secure: new URL(c.req.url).protocol === 'https:', + sameSite: 'Lax', + path: '/', + }); + } + c.header('Cache-Control', 'private, no-store'); +}); +``` + +#### API requests with concurrent clients + +For browser API requests, exchange an `X-DB-Bookmark` header and retain the newest bookmark. [D1 bookmarks are lexicographically sortable](https://developers.cloudflare.com/d1/reference/time-travel/#bookmarks), so an older response must not replace a newer bookmark from the same database. + +For requests made through the browser fetch wrapper below, exchange bookmarks using this middleware: + +::: warning +This recipe carries bookmarks only through the fetch wrapper below, not ordinary navigation, form submissions, or Pages requests. It does not share bookmarks with the cookie-based recipe. +::: + +::: note +To use cookies and API headers together, see [Supporting both transports](#supporting-both-transports). +::: + +```ts +// middleware/01.database.ts +import { defineMiddleware } from 'void'; +import { getBookmark, setSession } from 'void/db'; + +export default defineMiddleware(async (c, next) => { + if (!c.req.path.startsWith('/api/')) { + await next(); + return; + } + + setSession(c.req.header('X-DB-Bookmark') ?? 'first-unconstrained'); + await next(); + const bookmark = getBookmark(); + if (bookmark) { + c.header('X-DB-Bookmark', bookmark); + } + c.header('Cache-Control', 'private, no-store'); +}); +``` + +On the browser, send the saved bookmark and atomically retain the newest returned value using [Web Locks](https://developer.mozilla.org/en-US/docs/Web/API/Web_Locks_API). This requires HTTPS (or localhost), browser storage, and Web Locks support. Use a scope unique to the database and signed-in account; same-origin tabs with the same scope share progress. + +```ts +// src/bookmark-fetch.ts +export function createBookmarkFetch(scope: string) { + const key = `d1-bookmark:${scope}`; + + return async function bookmarkFetch(path: string, init: RequestInit = {}): Promise { + const url = new URL(path, location.origin); + if (url.origin !== location.origin || !url.pathname.startsWith('/api/')) { + throw new Error('bookmarkFetch requires a same-origin /api/ URL.'); + } + + const bookmark = localStorage.getItem(key); + const headers = new Headers(init.headers); + headers.delete('X-DB-Bookmark'); + if (bookmark) headers.set('X-DB-Bookmark', bookmark); + + const response = await fetch(url, { + ...init, + headers, + credentials: 'same-origin', + cache: 'no-store', + redirect: 'error', + }); + + const returned = response.headers.get('X-DB-Bookmark'); + if (returned) { + await navigator.locks.request(key, () => { + const current = localStorage.getItem(key); + if (current === null || returned > current) { + localStorage.setItem(key, returned); + } + }); + } + + return response; + }; +} +``` + +Use the wrapper for each participating API request. For example, with an existing profile API: + +```ts +import { createBookmarkFetch } from './bookmark-fetch'; + +export async function saveAndReadProfile(accountId: string, name: string) { + const api = createBookmarkFetch(`app-db:${accountId}`); + const saved = await api('/api/profile', { + method: 'POST', + headers: { 'Content-Type': 'text/plain' }, + body: name, + }); + if (!saved.ok) throw new Error(`Save failed: ${saved.status}`); + + // Sends at least the completed save's bookmark. + const response = await api('/api/profile'); + if (!response.ok) throw new Error(`Read failed: ${response.status}`); + return response.json(); +} +``` + +The wrapper saves the newest bookmark before resolving, so subsequent requests inherit its progress even if concurrent responses arrive out of order. + +Use API endpoints that return data, not redirects. + +#### Supporting both transports + +Use this single middleware with the fetch wrapper above to support API requests alongside browser navigation and forms. It selects the newest incoming bookmark for the same database and returns it through both transports. + +::: warning +The fetch wrapper retains the newest bookmark across concurrent responses, but cookies can still be overwritten out of order. For a guaranteed fresh read on a redirect's destination page, use a primary-first session. +::: + +```ts +// middleware/01.database.ts +import { getCookie, setCookie } from 'hono/cookie'; +import { defineMiddleware } from 'void'; +import { getBookmark, setSession } from 'void/db'; + +export default defineMiddleware(async (c, next) => { + const incoming: string[] = []; + + // Cookie input: navigation, forms, and same-origin fetch requests. + // Remove for header-only use. + const cookieBookmark = getCookie(c, 'db-bookmark'); + if (cookieBookmark) incoming.push(cookieBookmark); + + // Header input: the fetch wrapper's saved progress. + // Remove for cookie-only use. + const headerBookmark = c.req.header('X-DB-Bookmark'); + if (headerBookmark) incoming.push(headerBookmark); + + // Bookmarks from the same database sort oldest to newest. + setSession(incoming.sort().at(-1) ?? 'first-unconstrained'); + await next(); + + const bookmark = getBookmark(); + if (bookmark) { + // Cookie output: progress for subsequent navigation and forms. + // Remove for header-only use. + setCookie(c, 'db-bookmark', bookmark, { + httpOnly: true, + secure: new URL(c.req.url).protocol === 'https:', + sameSite: 'Lax', + path: '/', + }); + + // Header output: progress for the fetch wrapper. + // Remove for cookie-only use. + c.header('X-DB-Bookmark', bookmark); + } + + c.header('Cache-Control', 'private, no-store'); +}); +``` + +#### Using `createDb` + +For another D1 binding or a framework-owned endpoint, such as an Astro API route, create a client with the incoming bookmark. After querying, return `getBookmark(client)` in the response header: + +```ts +import { users } from '@schema'; +import { createDb, getBookmark } from 'void/db'; + +export async function readUsers(request: Request, binding: D1Database) { + const client = createDb(binding, { + session: request.headers.get('X-DB-Bookmark') ?? 'first-unconstrained', + }); + const result = await client.select().from(users).all(); + + const headers = new Headers({ 'Cache-Control': 'private, no-store' }); + const bookmark = getBookmark(client); + if (bookmark) headers.set('X-DB-Bookmark', bookmark); + return Response.json(result, { headers }); +} +``` ## Alternative Query Layers diff --git a/docs/reference/api.md b/docs/reference/api.md index b6a6a8010..05a09b43d 100644 --- a/docs/reference/api.md +++ b/docs/reference/api.md @@ -58,7 +58,7 @@ Import Void's app-facing APIs from these paths: | `void/schema-pg` | Re-exports [`drizzle-orm/pg-core`](https://orm.drizzle.team/docs/column-types/pg) for PostgreSQL table and column builders | | `void/schema-mysql` | Re-exports `drizzle-orm/mysql-core` for MySQL table and column builders | | `void/database-provider` | `defineDatabaseProvider` and adapter types for `void db connect --provider` | -| `void/db` | `db` (Drizzle D1, PostgreSQL, or MySQL instance for the active dialect), `createDb`, query operators (`eq`, `and`, `or`, `desc`, `like`, `inArray`, etc.) | +| `void/db` | `db` (Drizzle D1, PostgreSQL, or MySQL instance for the active dialect), `createDb`, D1 session helpers (`setSession`, `getBookmark`), query operators (`eq`, `and`, `or`, `desc`, `like`, `inArray`, etc.) | | `void/seed` | `defineSeed`, `SeedContext`, `SeedFn` for programmatic `void db seed` modules | | `void/kv` | `kv`, `createKV`, typed KV client/map types | | `void/storage` | `storage`, `createStorage` for the inferred R2 binding or a specific `R2Bucket` | diff --git a/docs/reference/api/database.md b/docs/reference/api/database.md index 5ad4c163b..779521bfa 100644 --- a/docs/reference/api/database.md +++ b/docs/reference/api/database.md @@ -37,7 +37,9 @@ import { createDb } from 'void/db'; const db = createDb(env.MY_OTHER_DB); ``` -For a fresh D1 read, pass `{ session: 'first-primary' }` and create the client inside the request. The default, `'first-unconstrained'`, allows the first query to use a replica. Both keep your schema and query types. See [Read replication](../../guide/database/d1.md#read-replication). +For a fresh D1 read, pass `{ session: 'first-primary' }` and create the client inside the request. The default, `'first-unconstrained'`, allows the first query to use a replica. Both keep your schema and query types. See [Avoid stale reads with a primary-first session](../../guide/database/d1.md#reading-from-the-primary). + +The `session` option also accepts a D1 bookmark from a previous request. Use `getBookmark(client)` after queries to obtain the bookmark to return to your client. See [Using `createDb`](../../guide/database/d1.md#using-createdb) for an example. For PostgreSQL and MySQL projects, pass a connection string. @@ -53,7 +55,7 @@ const db = createDb('postgres://user:password@host:5432/app'); // D1 function createDb( d1: D1Database, - options?: { session?: D1SessionConstraint }, + options?: { session?: D1SessionConstraint | D1SessionBookmark }, ): DrizzleD1Database; // PostgreSQL @@ -63,6 +65,32 @@ function createDb(connectionString: string): NodePgDatabase; function createDb(connectionString: string): MySql2Database; ``` +## `setSession(start)` {#setsession} + +D1 only. Set the starting bookmark or constraint for the default request's `db`. Call it in middleware before the first use of `db`. It does not change explicitly created clients or later requests. + +Passing `'first-unconstrained'` preserves any bookmark or primary-first requirement already configured, even before the first use of `db`. Other starting values replace the configuration until the session opens. + +After the session opens, repeated calls preserve it when the requirement is already satisfied: the original starting value, `'first-unconstrained'`, or a bookmark no newer than the session's current bookmark. This lets middleware run again during a local server-side fetch without resetting database progress. Repeating `'first-primary'` does not force another primary read. + +A newer bookmark or changing an opened session to `'first-primary'` throws. Configure these before using `db`, or use `createDb(binding, { session })` for an independent session. + +```ts +function setSession(start: D1SessionConstraint | D1SessionBookmark): void; +``` + +## `getBookmark(client?)` {#getbookmark} + +D1 only. Return the default request session's bookmark, or pass a client returned by `createDb()` to read that client's bookmark. Returns `null` when no bookmark is available. Reading the default bookmark does not open a database session. + +```ts +function getBookmark(client?: DrizzleD1Database): D1SessionBookmark | null; +``` + +`setSession()` and the no-argument `getBookmark()` require Void's request scope. For a framework-owned endpoint, such as an Astro API route, use an [explicit client](../../guide/database/d1.md#using-createdb) instead. + +For cookie and header middleware, a browser fetch wrapper, and guidance on combining both transports, see [See your writes in subsequent requests](../../guide/database/d1.md#cross-request-bookmarks). + ## Query Operators {#query-operators} `void/db` re-exports commonly used [Drizzle operators](https://orm.drizzle.team/docs/operators) so you never need to depend on `drizzle-orm` directly: diff --git a/packages/void/package.json b/packages/void/package.json index f3106e33e..040acf123 100644 --- a/packages/void/package.json +++ b/packages/void/package.json @@ -28,6 +28,7 @@ "type": "module", "imports": { "#self/_env": "./dist/runtime/env/runtime.mjs", + "#self/runtime/db-session": "./dist/runtime/db/session.mjs", "#self/email": "./dist/runtime/email/index.mjs", "#self/env": "./dist/runtime/env/public.mjs", "#self/client": "./dist/runtime/client/index.mjs", diff --git a/packages/void/skills/void/SKILL.md b/packages/void/skills/void/SKILL.md index 24550f2c0..f36ee0b6e 100644 --- a/packages/void/skills/void/SKILL.md +++ b/packages/void/skills/void/SKILL.md @@ -44,6 +44,7 @@ Use `void deploy --skip-migrations` when database migrations run separately; it | Server/API routing and middleware | `docs/guide/server-routing.md`, `docs/integrations/hono.md` | | Pages mode, loader/action, forms, layouts | `docs/guide/pages-routing/*.md`, `docs/guide/type-safety.md` | | Database and migrations | `docs/guide/database.md`, `docs/guide/type-safety.md` | +| D1 replicas, bookmarks, read-after-write | `docs/guide/database/d1.md`, `docs/reference/api/database.md` | | Typed fetch and end-to-end typing | `docs/guide/typed-fetch.md`, `docs/guide/type-safety.md` | | Authentication | `docs/guide/auth.md`, `docs/reference/api/auth.md`, `docs/guide/env-vars.md` | | Cloudflare runtime bindings and config | `docs/integrations/cloudflare.md`, `docs/reference/config.md`, `docs/guide/env-vars.md` | diff --git a/packages/void/src/codegen/db-types.ts b/packages/void/src/codegen/db-types.ts index acc99f7dc..206b21d00 100644 --- a/packages/void/src/codegen/db-types.ts +++ b/packages/void/src/codegen/db-types.ts @@ -11,7 +11,7 @@ const DIALECT_DB_TYPES = { sqlite: { type: 'DrizzleD1Database', from: 'void/_db', - arg: 'd1: D1Database, options?: { session?: D1SessionConstraint }', + arg: 'd1: D1Database, options?: { session?: D1SessionConstraint | D1SessionBookmark }', }, postgresql: { type: 'NodePgDatabase', from: 'void/_db-pg', arg: 'connectionString: string' }, mysql: { type: 'MySql2Database', from: 'void/_db-mysql', arg: 'connectionString: string' }, @@ -42,6 +42,12 @@ export function generateDbDts( ...(schema ? ['import type * as schema from "@schema";', 'type Schema = typeof schema;'] : []), `export declare const db: ${type}<${schemaType}>;`, `export declare function createDb(${arg}): ${type}<${schemaType}>;`, + ...(dialect === 'sqlite' + ? [ + 'export declare function setSession(start: D1SessionConstraint | (D1SessionBookmark & {})): void;', + `export declare function getBookmark(client?: ${type}<${schemaType}>): D1SessionBookmark | null;`, + ] + : []), `export { ${DRIZZLE_OPERATORS} } from "void/_db";`, `export type { ${DRIZZLE_TYPES} } from "void/_db";`, `export type { ${type} } from "${from}";`, diff --git a/packages/void/src/plugin-drizzle.ts b/packages/void/src/plugin-drizzle.ts index 86b364044..2ebf8e14e 100644 --- a/packages/void/src/plugin-drizzle.ts +++ b/packages/void/src/plugin-drizzle.ts @@ -22,6 +22,7 @@ import { readProjectPaths, resolveProjectPaths, type ProjectPaths } from './proj const drizzleD1Resolved = fileURLToPath(import.meta.resolve('drizzle-orm/d1')); const drizzleOrmResolved = fileURLToPath(import.meta.resolve('drizzle-orm')); const envModuleResolved = fileURLToPath(import.meta.resolve('#self/_env')); +const dbSessionResolved = fileURLToPath(import.meta.resolve('#self/runtime/db-session')); const drizzleNodePgResolved = fileURLToPath(import.meta.resolve('drizzle-orm/node-postgres')); const drizzleMysql2Resolved = fileURLToPath(import.meta.resolve('drizzle-orm/mysql2')); @@ -300,17 +301,27 @@ export function createDb(connectionString) { return ` export { ${DRIZZLE_OPERATORS} } from ${JSON.stringify(drizzleOrmResolved)}; import { drizzle } from ${JSON.stringify(drizzleD1Resolved)}; -import { getRuntimeRequestResource, requireRuntimeBinding } from ${JSON.stringify(envModuleResolved)}; +import { getRuntimeRequestResource } from ${JSON.stringify(envModuleResolved)}; +import { createD1SessionAccess } from ${JSON.stringify(dbSessionResolved)}; ${schemaImport} const _requestResourceKey = {}; +const sessions = createD1SessionAccess(${JSON.stringify(d1BindingName)}); + +export function setSession(start) { + sessions.setSession(start); +} + +export function getBookmark(client) { + return sessions.getBookmark(client === db ? undefined : client); +} export const db = new Proxy({}, { get(_, prop) { const instance = getRuntimeRequestResource( _requestResourceKey, - () => createDb(requireRuntimeBinding(${JSON.stringify(d1BindingName)})), - () => createPrimaryDb(requireRuntimeBinding(${JSON.stringify(d1BindingName)})) + () => drizzle(sessions.getSession()${drizzleConfig}), + () => drizzle(sessions.getSession()${drizzleConfig}) ); return Reflect.get(instance, prop); }, @@ -320,9 +331,6 @@ export function createDb(d1, options) { return drizzle(d1.withSession(options?.session ?? "first-unconstrained")${drizzleConfig}); } -function createPrimaryDb(d1) { - return drizzle(d1.withSession("first-primary")${drizzleConfig}); -} `; }, }, diff --git a/packages/void/src/runtime/db/index.ts b/packages/void/src/runtime/db/index.ts index 94e3396f5..6ad6f7ae3 100644 --- a/packages/void/src/runtime/db/index.ts +++ b/packages/void/src/runtime/db/index.ts @@ -11,6 +11,7 @@ import { getRuntimeRequestResource, requireRuntimeBinding, } from '../env/runtime.ts'; +import { createD1SessionAccess, type DbSessionStart } from './session.ts'; // Re-export commonly used Drizzle utilities so consumers never need // to depend on drizzle-orm directly. @@ -48,21 +49,35 @@ export type { AnyColumn, SQL, SQLWrapper } from 'drizzle-orm'; export type { BatchItem } from 'drizzle-orm/batch'; export type { DrizzleD1Database } from 'drizzle-orm/d1'; +export type { DbSessionStart }; + +const DEFAULT_BINDING = 'DB'; + /** * Create a Drizzle D1 instance from a custom D1 binding. * Use this when you have multiple D1 databases or need a non-default binding. */ export function createDb( d1: D1Database, - options?: { session?: D1SessionConstraint }, + options?: { session?: DbSessionStart }, ): DrizzleD1Database { return _drizzle( d1.withSession(options?.session ?? 'first-unconstrained') as unknown as D1Database, ); } -function createPrimaryDb(d1: D1Database): DrizzleD1Database { - return _drizzle(d1.withSession('first-primary') as unknown as D1Database); +const sessions = createD1SessionAccess(DEFAULT_BINDING); + +/** Set the default D1 session's starting bookmark or constraint before using db. */ +export function setSession(start: DbSessionStart): void { + sessions.setSession(start); +} + +/** Read the default request session's bookmark, or that of an explicit D1 client. */ +export function getBookmark>( + client?: DrizzleD1Database, +): D1SessionBookmark | null { + return sessions.getBookmark((client as object | undefined) === db ? undefined : client); } const requestDbKey = {}; @@ -73,14 +88,19 @@ function requireD1(): D1Database { // an installed package only when the package is an ES module that depends on void and the // app lists it or reaches it through such packages. if ( - getRuntimeBinding('DB') == null && + getRuntimeBinding(DEFAULT_BINDING) == null && (getRuntimeBinding('HYPERDRIVE') != null || getRuntimeBinding('DATABASE_URL') != null) ) { throw new Error( - "db: Missing Cloudflare binding 'DB'. This app connects through HYPERDRIVE or DATABASE_URL, but its server bundle loaded the D1 client. In Nuxt or Analog, add 'void/nitro' to the Nitro modules. An installed package that imports void/db must be an ES module that lists void in its dependencies or peerDependencies, and the app must list it or reach it through such packages.", + `db: Missing Cloudflare binding '${DEFAULT_BINDING}'. This app connects through HYPERDRIVE or DATABASE_URL, but its server bundle loaded the D1 client. In Nuxt or Analog, add 'void/nitro' to the Nitro modules. An installed package that imports void/db must be an ES module that lists void in its dependencies or peerDependencies, and the app must list it or reach it through such packages.`, ); } - return requireRuntimeBinding('DB'); + return requireRuntimeBinding(DEFAULT_BINDING); +} + +function d1Init() { + requireD1(); + return _drizzle(sessions.getSession()); } /** @@ -92,10 +112,9 @@ export const db: DrizzleD1Database = new Proxy({} as DrizzleD1Database, { get(_, prop) { const instance = getRuntimeRequestResource( requestDbKey, - () => createDb(requireD1()), - // 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, + // Outside Void's request scope, create an uncached client. + d1Init, ); return Reflect.get(instance, prop); }, diff --git a/packages/void/src/runtime/db/session.ts b/packages/void/src/runtime/db/session.ts new file mode 100644 index 000000000..c5b041153 --- /dev/null +++ b/packages/void/src/runtime/db/session.ts @@ -0,0 +1,80 @@ +import type { DrizzleD1Database } from 'drizzle-orm/d1'; +import { getRuntimeRequestResource, requireRuntimeBinding } from '../env/runtime.ts'; + +export type DbSessionStart = D1SessionConstraint | (D1SessionBookmark & {}); + +export interface DbRequestSession { + start: DbSessionStart; + session?: D1DatabaseSession; +} + +export interface DbSessionAccess { + getSession(): D1Database; + setSession(start: DbSessionStart): void; + getBookmark>( + client?: DrizzleD1Database | undefined, + ): D1SessionBookmark | null; +} + +/** @internal Shared by the published D1 client and schema-aware generated clients. */ +export function createD1SessionAccess(bindingName: string): DbSessionAccess { + const key = {}; + + function state(): DbRequestSession { + return getRuntimeRequestResource(key, () => ({ start: 'first-unconstrained' })); + } + + return { + getSession() { + const current = getRuntimeRequestResource( + key, + () => ({ start: 'first-unconstrained' }), + // Outside Void's request scope, sessions are not shared between operations. + // Start each session on primary to preserve fresh reads. + () => ({ start: 'first-primary' }), + ); + return (current.session ??= requireRuntimeBinding(bindingName).withSession( + current.start, + )) as unknown as D1Database; + }, + + setSession(start) { + const current = state(); + // Nested middleware may have no bookmark of its own. Its fallback must + // not discard the outer requirement, even before the first DB access. + if (start === 'first-unconstrained') { + return; + } + if (current.session) { + // Middleware runs again on local server-side fetches. Repeated inputs + // must preserve the existing session and any progress made by queries. + if (start === current.start) { + return; + } + const bookmark = current.session.getBookmark(); + if (start !== 'first-primary' && bookmark !== null && start <= bookmark) { + return; + } + throw new Error( + 'db: setSession() cannot strengthen an opened session. Call it before the first use of db, or use createDb(binding, { session }) with getBookmark(client) for an independent session.', + ); + } + current.start = start; + }, + + getBookmark>( + client?: DrizzleD1Database | undefined, + ) { + if (client) { + const session = Reflect.get(client, '$client'); + if (!session?.getBookmark) { + throw new Error('db: getBookmark(client) requires a D1 session-backed client.'); + } + + return session.getBookmark(); + } + // Inspect only: middleware on a route without database queries must not open a session. + return state().session?.getBookmark() ?? null; + }, + }; +} diff --git a/packages/void/test/integration/d1-sessions-api-playground.test.ts b/packages/void/test/integration/d1-sessions-api-playground.test.ts new file mode 100644 index 000000000..3d9c1e551 --- /dev/null +++ b/packages/void/test/integration/d1-sessions-api-playground.test.ts @@ -0,0 +1,313 @@ +import { execSync } from 'node:child_process'; +import { writeFileSync } from 'node:fs'; +import { join } from 'node:path'; +import spawn from 'cross-spawn'; +import { chromium } from 'playwright'; +import { describe, expect, it } from 'vite-plus/test'; +import { + createIsolatedPlayground, + killChild, + startServer, +} from '../../../../test/integration-helpers.ts'; + +const ROOT = join(import.meta.dirname, '../../../..'); + +describe('playground/d1-sessions-api', () => { + for (const mode of ['dev', 'preview'] as const) { + it(`propagates bookmarks only in the fixed variant (${mode})`, async () => { + const fixture = createIsolatedPlayground(ROOT, 'playground/d1-sessions-api'); + const browser = await chromium.launch(); + let server: Awaited> | undefined; + try { + // Exercise actual server serialization; fault injection stays in the disposable fixture. + writeFileSync( + join(fixture.root, 'routes/api/[variant].ts'), + ` +import { defineHandler } from 'void'; +import { loader, action } from '../../src/database.ts'; +function fail() { + throw new Error('D1_ERROR: test failure
', { cause: new Error('test RPC disconnect') }); +} +export const GET = defineHandler((c) => { + if (c.req.header('x-demo-test-error') === 'read') fail(); + return loader(c); +}); +export const POST = defineHandler(async (c) => { + if (c.req.header('x-demo-test-error') === 'save') fail(); + const starts = []; + if (c.req.query('experiment') === 'immediate') { + c.env = { ...c.env, DB: new Proxy(c.env.DB, { + get(binding, key) { + if (key === 'withSession') return (start) => { + starts.push(start); + if (starts.length === 2 && c.req.header('x-demo-test-error') === 'immediate-read') fail(); + return binding.withSession(start); + }; + return Reflect.get(binding, key, binding); + }, + }) }; + } + const response = await action(c); + response.headers.set('x-test-session-starts', JSON.stringify(starts)); + return response; +}); +`, + ); + execSync('vp exec void db migrate', { + cwd: fixture.root, + stdio: 'pipe', + }); + if (mode === 'preview') { + execSync('vp build', { cwd: fixture.root, stdio: 'pipe' }); + } + server = await startServer( + (port) => + spawn('vp', [mode, '--host', '127.0.0.1', '--port', String(port), '--strictPort'], { + cwd: fixture.root, + stdio: ['ignore', 'pipe', 'pipe'], + env: { ...process.env, VOID_INSPECTOR_PORT: 'false' }, + }), + 60_000, + { expectBody: 'D1 Sessions API' }, + ); + const context = await browser.newContext(); + const page = await context.newPage(); + await page.goto(server.base); + const heading = page.getByRole('heading', { name: 'D1 Sessions API', exact: true }); + expect(await heading.count()).toBe(1); + const homeLink = page.getByRole('link', { name: 'D1 Sessions API', exact: true }); + expect(await homeLink.count()).toBe(1); + for (const variant of ['with-bookmark', 'without-bookmark']) { + const fixed = variant === 'with-bookmark'; + const initial = await context.request.get(`${server.base}/api/${variant}`); + expect(initial.status()).toBe(200); + expect(await initial.json()).toMatchObject({ outcome: 'idle', observed: null }); + + const write = await context.request.post(`${server.base}/api/${variant}`, { + maxRedirects: 0, + }); + expect(write.status()).toBe(303); + expect(write.headers()['cache-control']).toContain('no-store'); + expect(Boolean(write.headers()['set-cookie']?.includes('d1-demo-bookmark='))).toBe(fixed); + const read = await context.request.get(`${server.base}${write.headers().location}`); + const observation = await read.json(); + expect(observation).toMatchObject({ variant, outcome: 'fresh' }); + expect(observation.observed).toBe(observation.expected); + expect(Boolean(observation.incomingBookmark)).toBe(fixed); + expect(read.headers()['x-d1-bookmark']).toBe(observation.outgoingBookmark); + + await page.goto( + `${server.base}/${variant}?experiment=redirect&pressure=0.25&trials=20&probes=50`, + ); + await page.locator('#app[data-hydrated="true"]').waitFor(); + expect( + await page.getByRole('checkbox', { name: 'Add replication pressure' }).isChecked(), + ).toBe(true); + expect( + await page.getByRole('combobox', { name: 'Pressure per trial' }).inputValue(), + ).toBe('0.25'); + expect( + await page + .getByRole('combobox', { name: 'Pressure per trial' }) + .locator('option') + .allTextContents(), + ).toEqual(['256 KiB', '512 KiB', '1 MiB', '2 MiB']); + expect(await page.getByRole('combobox', { name: 'Reads per write' }).count()).toBe(0); + expect( + await page.getByRole('combobox', { name: 'Pressure writes per save' }).count(), + ).toBe(0); + expect(await page.getByRole('button', { name: /^Save and/ }).count()).toBe(0); + await page.getByRole('combobox', { name: 'Pressure per trial' }).selectOption('0.5'); + expect( + await page.getByRole('combobox', { name: 'Probes', exact: true }).inputValue(), + ).toBe('50'); + expect( + await page.getByRole('combobox', { name: 'Trials', exact: true }).inputValue(), + ).toBe('20'); + await expect.poll(() => new URL(page.url()).searchParams.get('pressure')).toBe('0.5'); + await page.reload(); + await page.locator('#app[data-hydrated="true"]').waitFor(); + await expect + .poll(() => page.getByRole('combobox', { name: 'Pressure per trial' }).inputValue()) + .toBe('0.5'); + expect( + await page.getByRole('combobox', { name: 'Probes', exact: true }).inputValue(), + ).toBe('50'); + await page.getByRole('button', { name: 'Run trials', exact: true }).click(); + await expect.poll(() => page.locator('.trial-row').count(), { timeout: 30_000 }).toBe(20); + await expect.poll(() => page.locator('.result h2').textContent()).toBe('Fresh read'); + await page.locator('#app[data-hydrated="true"]').waitFor(); + expect(await page.locator('.result').textContent()).toContain('512 KiB per trial'); + expect(await page.getByRole('link', { name: 'Read again', exact: true }).count()).toBe(0); + await page.getByRole('checkbox', { name: 'Add replication pressure' }).uncheck(); + await page.getByRole('button', { name: 'Run trials', exact: true }).click(); + await expect.poll(() => page.locator('.trial-row').count(), { timeout: 30_000 }).toBe(20); + expect(await page.locator('tbody tr.stale').count()).toBe(0); + expect( + await page.getByText('20 completed · 20 fresh · 0 stale · 0 errored').count(), + ).toBe(1); + expect(await page.locator('.result').textContent()).toContain('Off'); + + const immediate = await context.request.post( + `${server.base}/api/${variant}?experiment=immediate&pressure=1`, + { maxRedirects: 0 }, + ); + expect(immediate.status()).toBe(200); + expect(immediate.headers().location).toBeUndefined(); + expect(immediate.headers()['set-cookie']?.includes('d1-demo-bookmark=')).not.toBe(true); + const immediateObservation = await immediate.json(); + expect(immediateObservation).toMatchObject({ + experiment: 'immediate', + variant, + pressureMiB: 1, + outcome: 'fresh', + writeBookmark: expect.any(String), + outgoingBookmark: expect.any(String), + }); + expect(immediateObservation.observed).toBe(immediateObservation.expected); + expect(immediateObservation.incomingBookmark).toBe( + fixed ? immediateObservation.writeBookmark : null, + ); + expect(immediate.headers()['x-d1-bookmark']).toBe(immediateObservation.outgoingBookmark); + expect(immediateObservation.reads).toBeUndefined(); + expect(JSON.parse(immediate.headers()['x-test-session-starts'])).toEqual([ + 'first-unconstrained', + fixed ? immediateObservation.writeBookmark : 'first-unconstrained', + ]); + for (const count of [1, 16, 999]) { + const sampled = await context.request.post( + `${server.base}/api/${variant}?experiment=immediate&reads=${count}&writes=${count}&pressure=0.25`, + ); + const sampledObservation = await sampled.json(); + expect(sampled.status()).toBe(200); + expect(sampledObservation.pressureMiB).toBe(0.25); + expect(sampledObservation.reads).toBeUndefined(); + expect(sampledObservation.pressureWrites).toBeUndefined(); + expect(JSON.parse(sampled.headers()['x-test-session-starts'])).toHaveLength(2); + } + + await page.getByRole('combobox', { name: 'Read timing' }).selectOption('immediate'); + await page.getByRole('button', { name: 'Run trials', exact: true }).click(); + await expect.poll(() => page.locator('.trial-row').count(), { timeout: 30_000 }).toBe(20); + expect(await page.locator('.result h2').textContent()).toBe('Fresh read'); + expect(await page.locator('.result').textContent()).toContain('Immediate server read'); + expect(await page.locator('.result').textContent()).toContain('Read session bookmark'); + } + for (const size of [0.25, 0.5, 1, 2]) { + const response = await context.request.post( + `${server.base}/api/with-bookmark?pressure=${size}`, + ); + expect(response.status()).toBe(200); + expect(await response.json()).toMatchObject({ pressureMiB: size, outcome: 'fresh' }); + } + for (const size of [4, 16, 32, 64, 999999]) { + const invalid = await context.request.post( + `${server.base}/api/with-bookmark?pressure=${size}`, + ); + expect(await invalid.json()).toMatchObject({ pressureMiB: 0, outcome: 'fresh' }); + } + const probe = await context.request.get(`${server.base}/api/routing`); + expect(probe.status()).toBe(200); + expect(await probe.json()).toMatchObject({ + path: 'void-run', + metadata: { rows_written: 0 }, + }); + const bookmark = (await context.cookies()).find( + (cookie) => cookie.name === 'd1-demo-bookmark', + ); + expect(bookmark).toMatchObject({ httpOnly: true, sameSite: 'Lax' }); + expect((await context.request.get(`${server.base}/api/unknown`)).status()).toBe(404); + expect( + ( + await context.request.post(`${server.base}/api/with-bookmark`, { + headers: { origin: 'https://other.example' }, + }) + ).status(), + ).toBe(403); + + const readFailure = await context.request.get( + `${server.base}/api/with-bookmark?expected=acknowledged-revision`, + { headers: { 'x-demo-test-error': 'read' } }, + ); + expect(readFailure.status()).toBe(500); + expect(readFailure.headers()['cache-control']).toContain('no-store'); + expect(await readFailure.json()).toMatchObject({ + outcome: 'errored', + expected: 'acknowledged-revision', + observed: null, + error: { + phase: 'read', + status: 500, + causes: [ + { + name: 'Error', + message: 'D1_ERROR: test failure
', + stack: expect.any(String), + }, + { name: 'Error', message: 'test RPC disconnect', stack: expect.any(String) }, + ], + }, + }); + + const immediateReadFailure = await context.request.post( + `${server.base}/api/with-bookmark?experiment=immediate`, + { headers: { 'x-demo-test-error': 'immediate-read' }, maxRedirects: 0 }, + ); + expect(immediateReadFailure.status()).toBe(500); + const failedSamples = await immediateReadFailure.json(); + expect(failedSamples).toMatchObject({ + experiment: 'immediate', + outcome: 'errored', + expected: expect.any(String), + observed: null, + writeBookmark: expect.any(String), + error: { phase: 'read', status: 500 }, + }); + expect(failedSamples.reads).toBeUndefined(); + + await page.goto(`${server.base}/without-bookmark`); + await page.locator('#app[data-hydrated="true"]').waitFor(); + await page.getByRole('checkbox', { name: 'Add replication pressure' }).uncheck(); + let writes = 0; + await page.route('**/api/without-bookmark*', async (route) => { + const request = route.request(); + const headers = { ...request.headers() }; + if (request.method() === 'POST' && ++writes >= 2) { + headers['x-demo-test-error'] = 'save'; + } + await route.continue({ headers }); + }); + await page.getByRole('button', { name: 'Run trials', exact: true }).click(); + await expect + .poll(() => page.locator('.result h2').textContent()) + .toBe('Errored — trial did not complete'); + expect(await page.getByText('1 completed · 1 fresh · 0 stale · 1 errored').count()).toBe(1); + expect(await page.locator('tbody tr.fresh').count()).toBe(1); + expect(await page.locator('tbody tr.errored').count()).toBe(1); + expect(await page.locator('[role="alert"]').textContent()).toContain( + 'write may have committed', + ); + await page.locator('.error-details details summary').click(); + expect(await page.locator('.error-details details').textContent()).toContain( + 'test RPC disconnect', + ); + expect(await page.locator('.error-details details').textContent()).toContain( + 'D1_ERROR: test failure
', + ); + expect(writes).toBe(2); + await page.getByRole('button', { name: 'Run trials', exact: true }).click(); + await expect + .poll(() => page.getByText('0 completed · 0 fresh · 0 stale · 1 errored').count()) + .toBe(1); + expect(writes).toBe(3); + await context.close(); + } finally { + await browser.close(); + if (server) { + await killChild(server.child); + } + fixture.cleanup(); + } + }, 120_000); + } +}); diff --git a/packages/void/test/integration/db-session.test.ts b/packages/void/test/integration/db-session.test.ts new file mode 100644 index 000000000..c1b0350e0 --- /dev/null +++ b/packages/void/test/integration/db-session.test.ts @@ -0,0 +1,292 @@ +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { convertV4MiniflareOptions, Miniflare } from 'miniflare'; +import { build } from 'vite'; +import { afterEach, describe, expect, it } from 'vite-plus/test'; +import { analyzeApplication } from '../../src/application-routing.ts'; +import { readConfig } from '../../src/config.ts'; +import { drizzlePlugin } from '../../src/plugin-drizzle.ts'; +import { + compileRouteTable, + compileWorkerClient, + compileWorkerEntry, +} from '../../src/router/compile.ts'; + +const source = (file: string) => + fileURLToPath(new URL(`../../src/runtime/${file}`, import.meta.url)); +let directory: string; +let runtime: Miniflare | undefined; +afterEach(async () => { + await runtime?.dispose(); + runtime = undefined; + if (directory) { + rmSync(directory, { recursive: true, force: true }); + } +}); + +describe('D1 bookmarks in generated Workers', () => { + // Local D1 has no replica lag. The unit reproduction controls lag; this verifies + // real D1 bookmarks, middleware, redirects, bundling and request scope in workerd. + it.each( + [ + { module: 'runtime', bindingName: 'DB' }, + { module: 'generated', bindingName: 'DB' }, + { module: 'generated', bindingName: 'APP_DB' }, + ].flatMap((client) => + ['header', 'cookie'].flatMap((transport) => + ['direct', 'server-fetch', 'before-use', 'nested-write', 'concurrent'].map((dispatch) => ({ + ...client, + transport, + dispatch, + })), + ), + ), + )( + '$module / $bindingName carries a bookmark through $transport middleware ($dispatch)', + async ({ module, bindingName, transport, dispatch }) => { + directory = mkdtempSync(join(tmpdir(), 'void-db-bookmark-worker-')); + const routes = join(directory, 'routes'); + const middleware = join(directory, 'middleware'); + const output = join(directory, 'output'); + mkdirSync(routes); + mkdirSync(middleware); + writeFileSync( + join(middleware, '01.database.ts'), + ` +import { setSession, getBookmark } from 'void/db'; +import { getCookie, setCookie } from 'hono/cookie'; +export default async (c, next) => { + const incoming = ${transport === 'cookie' ? "getCookie(c, 'db-bookmark')" : "c.req.header('X-DB-Bookmark')"}; + setSession(incoming ?? 'first-unconstrained'); + await next(); + const bookmark = getBookmark(); + if (bookmark) { + c.header('X-DB-Bookmark', bookmark); + ${transport === 'cookie' ? "setCookie(c, 'db-bookmark', bookmark, { httpOnly: true, sameSite: 'Lax', path: '/' });" : ''} + } +}; +`, + ); + writeFileSync( + join(routes, 'profile.ts'), + ` +import { db, createDb, getBookmark, sql } from 'void/db'; +export async function POST(c) { + await db.run(sql\`UPDATE profile SET name = 'Alice' WHERE id = 1\`); + return c.redirect('/profile', 303); +} +export async function GET(c) { + const name = await db.get(sql\`SELECT name FROM profile WHERE id = 1\`); + const client = createDb(c.env[${JSON.stringify(bindingName)}], { session: getBookmark() ?? 'first-unconstrained' }); + const explicit = await client.get(sql\`SELECT name FROM profile WHERE id = 1\`); + return c.json({ name, explicit, bookmark: getBookmark(client) }); +} +export async function PATCH(c) { + await db.run(sql\`UPDATE profile SET name = 'Nested name' WHERE id = 1\`); + return c.json({ bookmark: getBookmark() }); +} +`, + ); + writeFileSync(join(routes, 'unused.ts'), 'export function GET() { return "unused"; }'); + if (dispatch !== 'direct') { + writeFileSync( + join(routes, 'nested.ts'), + ` +import { fetch } from 'void/client'; +import { db, sql } from 'void/db'; +export async function GET(c) { + ${dispatch === 'before-use' ? '' : 'await db.get(sql`SELECT name FROM profile WHERE id = 1`);'} + ${ + dispatch === 'nested-write' + ? `await fetch('/profile', { method: 'PATCH', retry: 0 }); + const outerName = await db.get(sql\`SELECT name FROM profile WHERE id = 1\`); + return c.json({ ...await fetch('/profile', { retry: 0 }), outerName });` + : dispatch === 'concurrent' + ? `const results = await Promise.all([ + fetch('/profile', { retry: 0 }), + fetch('/profile', { retry: 0 }), + ]); + return c.json({ ...results[0], concurrent: results });` + : "return c.json(await fetch('/profile', { retry: 0 }));" + } +} +`, + ); + } + const { scan } = await analyzeApplication(directory, { config: readConfig(directory) }); + const routeTable = join(directory, 'generated-routes.ts'); + const entry = join(directory, 'generated-worker.ts'); + writeFileSync( + routeTable, + compileRouteTable( + scan, + routes, + middleware, + join(directory, 'crons'), + join(directory, 'queues'), + null, + { + honoPath: fileURLToPath(import.meta.resolve('hono')), + honoRoutePath: fileURLToPath(import.meta.resolve('hono/route')), + runtimeEnvPath: source('env/runtime.ts'), + projectRoot: directory, + homeDir: tmpdir(), + auth: null, + dev: false, + reactRefresh: false, + }, + ), + ); + writeFileSync(entry, compileWorkerEntry({ runtimeEnvPath: source('env/runtime.ts') })); + const instrumentedEntry = join(directory, 'instrumented-worker.ts'); + writeFileSync( + instrumentedEntry, + ` +import worker from './generated-worker.ts'; +export default { + async fetch(request, env, ctx) { + const starts = []; + const bindingName = ${JSON.stringify(bindingName)}; + const binding = env[bindingName]; + const tracked = new Proxy(binding, { + get(target, prop) { + if (prop === 'withSession') return (start) => { + starts.push(start); + return target.withSession(start); + }; + const value = Reflect.get(target, prop, target); + return typeof value === 'function' ? value.bind(target) : value; + }, + }); + const response = await new worker(ctx, { ...env, [bindingName]: tracked }).fetch(request); + const result = new Response(response.body, response); + result.headers.set('X-Test-Session-Starts', JSON.stringify(starts)); + return result; + }, +}; +`, + ); + await build({ + configFile: false, + logLevel: 'silent', + plugins: [ + { + name: 'bookmark-worker-fixture', + enforce: 'pre', + resolveId(id) { + if (id === 'virtual:void-routes') { + return routeTable; + } + if (id === 'hono/cookie') { + return fileURLToPath(import.meta.resolve('hono/cookie')); + } + if (id.endsWith('/dist/runtime/db/session.mjs')) { + return source('db/session.ts'); + } + if (id.endsWith('/dist/runtime/routing/index.mjs')) { + return source('routing/index.ts'); + } + if (id === 'void/db' && module === 'runtime') { + return source('db/index.ts'); + } + if (id === 'void/client') { + return '\0bookmark-worker-client'; + } + if (id.endsWith('/dist/runtime/client/fetch-server.mjs')) { + return source('client/fetch-server.ts'); + } + }, + load(id) { + if (id === '\0bookmark-worker-client') { + return compileWorkerClient(source('auth/client.ts')); + } + }, + }, + ...(module === 'generated' + ? [ + drizzlePlugin(directory, false, 'sqlite', { + d1BindingName: bindingName, + forceVirtualDb: true, + }), + ] + : []), + ], + ssr: { noExternal: true }, + build: { + outDir: output, + ssr: instrumentedEntry, + target: 'esnext', + rollupOptions: { + external: [/^cloudflare:/, /^node:/], + output: { entryFileNames: 'worker.mjs', codeSplitting: false }, + }, + }, + }); + runtime = new Miniflare( + convertV4MiniflareOptions({ + compatibilityDate: '2026-07-01', + compatibilityFlags: ['nodejs_compat'], + modules: true, + modulesRoot: output, + scriptPath: join(output, 'worker.mjs'), + d1Databases: [bindingName], + }), + ); + const binding = await runtime.getD1Database(bindingName); + await binding.prepare('CREATE TABLE profile (id INTEGER PRIMARY KEY, name TEXT)').run(); + await binding.prepare("INSERT INTO profile VALUES (1, 'Old name')").run(); + const saved = await runtime.dispatchFetch('https://app.test/profile', { + method: 'POST', + redirect: 'manual', + }); + expect(saved.status, await saved.clone().text()).toBe(303); + expect(saved.headers.get('Location')).toBe('/profile'); + const bookmark = saved.headers.get('X-DB-Bookmark'); + expect(bookmark).toBeTruthy(); + const loaded = await runtime.dispatchFetch( + `https://app.test/${dispatch === 'direct' ? 'profile' : 'nested'}`, + { + headers: + transport === 'cookie' + ? { Cookie: `db-bookmark=${encodeURIComponent(bookmark!)}` } + : { 'X-DB-Bookmark': bookmark! }, + }, + ); + expect(loaded.status, await loaded.clone().text()).toBe(200); + // Local D1 has no replica lag, so explicitly assert that middleware + // preserved the outer bookmark even when nested dispatch happens first. + const starts = JSON.parse(loaded.headers.get('X-Test-Session-Starts')!) as string[]; + expect(starts[0]).toBe(bookmark); + // Direct GET also creates an explicit client from its wrapped env. + // Local fetch receives cloudflare:workers env for explicit clients, + // while its default db still shares the outer runtime session. + expect(starts).toHaveLength(dispatch === 'direct' ? 2 : 1); + const name = dispatch === 'nested-write' ? 'Nested name' : 'Alice'; + const profile = { + name: { name }, + explicit: { name }, + bookmark: expect.any(String), + }; + expect(await loaded.json()).toEqual({ + ...profile, + ...(dispatch === 'nested-write' ? { outerName: { name } } : {}), + ...(dispatch === 'concurrent' ? { concurrent: [profile, profile] } : {}), + }); + expect(loaded.headers.get('X-DB-Bookmark')).toBeTruthy(); + if (transport === 'cookie') { + expect(loaded.headers.get('Set-Cookie')).toContain('db-bookmark='); + } + const unused = await runtime.dispatchFetch('https://app.test/unused', { + headers: + transport === 'cookie' + ? { Cookie: `db-bookmark=${encodeURIComponent(bookmark!)}` } + : { 'X-DB-Bookmark': bookmark! }, + }); + expect(await unused.text()).toBe('unused'); + expect(unused.headers.has('X-DB-Bookmark')).toBe(false); + }, + 30_000, + ); +}); diff --git a/packages/void/test/unit/db-session.test.ts b/packages/void/test/unit/db-session.test.ts new file mode 100644 index 000000000..00d357ae4 --- /dev/null +++ b/packages/void/test/unit/db-session.test.ts @@ -0,0 +1,383 @@ +import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { fileURLToPath, pathToFileURL } from 'node:url'; +import { drizzle } from 'drizzle-orm/d1'; +import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'; +import { Hono } from 'hono'; +import { convertV4MiniflareOptions, Miniflare } from 'miniflare'; +import { afterEach, describe, expect, it, vi } from 'vite-plus/test'; +import { drizzlePlugin } from '../../src/plugin-drizzle.ts'; +import * as runtimeDb from '../../src/runtime/db/index.ts'; +import { envContext } from '../../src/runtime/env/raw.ts'; +import { withRuntimeEnv } from '../../src/runtime/env/runtime.ts'; +import { getHookHandler } from '../helpers/vite-hooks.ts'; + +const roots: Array = []; +const profile = sqliteTable('profile', { + id: integer('id').primaryKey(), + name: text('name').notNull(), +}); + +afterEach(() => { + for (const root of roots.splice(0)) { + rmSync(root, { recursive: true, force: true }); + } +}); + +async function loadGeneratedDb(bindingName: string): Promise { + const root = mkdtempSync(join(tmpdir(), 'void-db-session-')); + roots.push(root); + const plugin = drizzlePlugin(root, false, 'sqlite', { + d1BindingName: bindingName, + forceVirtualDb: true, + }); + const load = getHookHandler(plugin.load) as (id: string) => string; + const path = join(root, 'db.mjs'); + writeFileSync( + path, + load('\0virtual:void-db') + .replace( + JSON.stringify(fileURLToPath(import.meta.resolve('#self/_env'))), + JSON.stringify(new URL('../../src/runtime/env/runtime.ts', import.meta.url).href), + ) + .replace( + JSON.stringify(fileURLToPath(import.meta.resolve('#self/runtime/db-session'))), + JSON.stringify(new URL('../../src/runtime/db/session.ts', import.meta.url).href), + ), + ); + return import(pathToFileURL(path).href); +} + +// Miniflare executes real D1 SQL but does not provide controllable replica lag. +// Model only the session boundary here, as in auth-d1-database.test.ts: +// PRIMARY advances after a write, REPLICA stays at the original profile. +// These opaque tokens belong to this fixture, not to Miniflare's Sessions API. +const BEFORE_SAVE = 'test-bookmark-001-before-save'; +const AFTER_SAVE = 'test-bookmark-002-after-save'; + +function laggingBinding(primary: D1Database, replica: D1Database) { + const withSession = vi.fn((start: string = 'first-unconstrained') => { + if (!['first-unconstrained', 'first-primary', BEFORE_SAVE, AFTER_SAVE].includes(start)) { + throw new Error(`Unexpected test session start: ${start}`); + } + let fresh = start === 'first-primary' || start === AFTER_SAVE; + let bookmark: string | null = start === BEFORE_SAVE || start === AFTER_SAVE ? start : null; + const session = { + getBookmark: () => bookmark, + prepare(sql: string) { + const write = /^update\b/i.test(sql); + if (!write && !/^select\b/i.test(sql)) { + throw new Error(`Unexpected test query: ${sql}`); + } + function statement(params: Array) { + // Choose at execution time, so a session's reads observe its previous writes. + async function execute(method: 'run' | 'raw') { + const database = write || fresh ? primary : replica; + const prepared = database.prepare(sql).bind(...params); + const result = await prepared[method](); + if (write) { + fresh = true; + } + bookmark = fresh ? AFTER_SAVE : BEFORE_SAVE; + return result; + } + return { + bind: (...values: Array) => statement(values), + run: () => execute('run'), + raw: () => execute('raw'), + }; + } + return statement([]); + }, + } as unknown as D1DatabaseSession; + return session; + }); + // Only the D1 operations used by this reproduction are implemented. + return { binding: { withSession } as unknown as D1Database, withSession }; +} + +const clients = [ + { module: 'runtime', bindingName: 'DB' }, + { module: 'generated', bindingName: 'DB' }, + { module: 'generated', bindingName: 'APP_DB' }, +]; + +describe('D1 cross-request bookmark reproduction (#783)', () => { + it.each(clients)( + '$module / $bindingName: preserves read-your-writes at the next request', + async (testCase) => { + const miniflare = new Miniflare( + convertV4MiniflareOptions({ + modules: true, + script: 'export default { fetch() { return new Response("ok") } }', + d1Databases: ['PRIMARY', 'REPLICA'], + }), + ); + try { + const primary = await miniflare.getD1Database('PRIMARY'); + const replica = await miniflare.getD1Database('REPLICA'); + for (const database of [primary, replica]) { + await database + .prepare('CREATE TABLE profile (id INTEGER PRIMARY KEY, name TEXT NOT NULL)') + .run(); + await database.prepare("INSERT INTO profile VALUES (1, 'Old name')").run(); + } + const { binding, withSession } = laggingBinding( + primary as unknown as D1Database, + replica as unknown as D1Database, + ); + const { db, createDb, setSession, getBookmark } = + testCase.module === 'runtime' ? runtimeDb : await loadGeneratedDb(testCase.bindingName); + const env = { [testCase.bindingName]: binding }; + const readProfile = () => db.select().from(profile); + + const app = new Hono(); + app.use(async (c, next) => { + setSession(c.req.header('X-DB-Bookmark') ?? 'first-unconstrained'); + await next(); + const bookmark = getBookmark(); + if (bookmark) { + c.header('X-DB-Bookmark', bookmark); + } + }); + // Request A: POST /profile. The write and subsequent read share a session. + app.post('/profile', async (c) => { + expect(await readProfile()).toEqual([{ id: 1, name: 'Old name' }]); + await db.update(profile).set({ name: 'Alice' }).run(); + expect(await readProfile()).toEqual([{ id: 1, name: 'Alice' }]); + return c.redirect('/profile', 303); + }); + app.get('/profile', async (c) => c.json(await readProfile())); + const saved = await withRuntimeEnv(env, () => app.request('/profile', { method: 'POST' })); + expect(saved.status).toBe(303); + expect(saved.headers.get('Location')).toBe('/profile'); + expect(withSession).toHaveBeenCalledExactlyOnceWith('first-unconstrained'); + const bookmark = saved.headers.get('X-DB-Bookmark'); + expect(bookmark).toBe(AFTER_SAVE); + + // Request B: GET /profile after the redirect should observe the saved profile. + const loaded = await withRuntimeEnv(env, () => + app.request('/profile', { + headers: { 'X-DB-Bookmark': bookmark! }, + }), + ); + expect(await loaded.json()).toEqual([{ id: 1, name: 'Alice' }]); + expect(withSession.mock.calls.map(([start]) => start)).toEqual([ + 'first-unconstrained', + AFTER_SAVE, + ]); + + // Control: starting on primary avoids the stale read. + expect( + await createDb(binding, { session: 'first-primary' }).select().from(profile), + ).toEqual([{ id: 1, name: 'Alice' }]); + + // Explicit clients accept the same carried bookmark without casts. + const explicit = createDb(binding, { session: bookmark! }); + expect(getBookmark(explicit)).toBe(AFTER_SAVE); + expect(await explicit.select().from(profile)).toEqual([{ id: 1, name: 'Alice' }]); + expect(withSession).toHaveBeenLastCalledWith(AFTER_SAVE); + + // Neither control secretly caught up the stale replica. + expect(await withRuntimeEnv(env, readProfile)).toEqual([{ id: 1, name: 'Old name' }]); + } finally { + await miniflare.dispose(); + } + }, + 30_000, + ); +}); + +describe.each(clients)('$module / $bindingName session lifecycle', (testCase) => { + async function loadClient() { + return testCase.module === 'runtime' ? runtimeDb : loadGeneratedDb(testCase.bindingName); + } + + function mockBinding() { + const withSession = vi.fn((start: string) => ({ + getBookmark: vi.fn((): string | null => + start === 'first-unconstrained' || start === 'first-primary' ? null : start, + ), + })); + return { withSession, env: { [testCase.bindingName]: { withSession } } }; + } + + it('does not open a D1 session when middleware configures or inspects an unused db', async () => { + const { db, getBookmark, setSession } = await loadClient(); + const { withSession, env } = mockBinding(); + withRuntimeEnv(env, () => { + expect(getBookmark()).toBeNull(); + expect(getBookmark(db)).toBeNull(); + setSession(AFTER_SAVE); + expect(getBookmark()).toBeNull(); + }); + expect(withSession).not.toHaveBeenCalled(); + expect(withRuntimeEnv(env, getBookmark)).toBeNull(); + }); + + it.each([AFTER_SAVE, 'first-primary'])( + 'preserves configured %s when nested middleware supplies no bookmark before db use', + async (start) => { + const { db, setSession } = await loadClient(); + const { withSession, env } = mockBinding(); + withRuntimeEnv(env, () => { + setSession(start); + setSession('first-unconstrained'); + void db.select(); + }); + expect(withSession).toHaveBeenCalledExactlyOnceWith(start); + }, + ); + + it.each([ + [AFTER_SAVE, BEFORE_SAVE], + [BEFORE_SAVE, AFTER_SAVE], + [AFTER_SAVE, 'first-primary'], + ['first-primary', AFTER_SAVE], + ] as const)('still replaces unopened %s with %s', async (start, replacement) => { + const { db, setSession } = await loadClient(); + const { withSession, env } = mockBinding(); + withRuntimeEnv(env, () => { + setSession(start); + setSession(replacement); + void db.select(); + }); + expect(withSession).toHaveBeenCalledExactlyOnceWith(replacement); + }); + + it('rejects stronger requirements after db is used and keeps the original session', async () => { + const { db, getBookmark, setSession } = await loadClient(); + const { withSession, env } = mockBinding(); + withRuntimeEnv(env, () => { + setSession(BEFORE_SAVE); + void db.select(); + expect(() => setSession(AFTER_SAVE)).toThrow('createDb'); + expect(() => setSession('first-primary')).toThrow('createDb'); + expect(getBookmark()).toBe(BEFORE_SAVE); + expect(getBookmark(db)).toBe(BEFORE_SAVE); + withSession.mock.results[0]!.value.getBookmark.mockReturnValue(AFTER_SAVE); + expect(() => setSession('test-bookmark-003-newer')).toThrow('createDb'); + expect(() => setSession('first-primary')).toThrow('createDb'); + expect(getBookmark()).toBe(AFTER_SAVE); + }); + expect(withSession).toHaveBeenCalledExactlyOnceWith(BEFORE_SAVE); + }); + + it.each(['first-unconstrained', 'first-primary', BEFORE_SAVE])( + 'preserves an opened %s session when repeated middleware requirements are satisfied', + async (start) => { + const { db, getBookmark, setSession } = await loadClient(); + const { withSession, env } = mockBinding(); + withRuntimeEnv(env, () => { + setSession(start); + void db.select(); + setSession(start); + setSession('first-unconstrained'); + const session = withSession.mock.results[0]!.value; + // D1 advances the bookmark as queries complete. Compare against that + // progress, not just the session's original starting value. + session.getBookmark.mockReturnValue(AFTER_SAVE); + setSession(BEFORE_SAVE); + setSession(AFTER_SAVE); + setSession('first-unconstrained'); + setSession(start); + expect(getBookmark()).toBe(AFTER_SAVE); + expect(getBookmark(db)).toBe(AFTER_SAVE); + void db.select(); + }); + expect(withSession).toHaveBeenCalledExactlyOnceWith(start); + }, + ); + + it('rejects a bookmark requirement on an opened session with no observed bookmark', async () => { + const { db, setSession, getBookmark } = await loadClient(); + const { withSession, env } = mockBinding(); + withRuntimeEnv(env, () => { + void db.select(); + setSession('first-unconstrained'); + expect(() => setSession(BEFORE_SAVE)).toThrow('createDb'); + expect(() => setSession('first-primary')).toThrow('createDb'); + expect(getBookmark()).toBeNull(); + }); + expect(withSession).toHaveBeenCalledExactlyOnceWith('first-unconstrained'); + }); + + it('keeps overlapping requests and explicit clients independent', async () => { + const { db, createDb, getBookmark, setSession } = await loadClient(); + const { withSession, env } = mockBinding(); + let resume!: () => void; + const resumed = new Promise((resolve) => { + resume = resolve; + }); + const first = withRuntimeEnv(env, async () => { + setSession(AFTER_SAVE); + void db.select(); + await resumed; + expect(getBookmark()).toBe(AFTER_SAVE); + setSession(BEFORE_SAVE); + expect(getBookmark()).toBe(AFTER_SAVE); + }); + try { + await withRuntimeEnv(env, async () => { + setSession(BEFORE_SAVE); + const explicit = createDb(env[testCase.bindingName] as unknown as D1Database, { + session: AFTER_SAVE, + }); + await Promise.resolve(); + expect(getBookmark(explicit)).toBe(AFTER_SAVE); + expect(getBookmark()).toBeNull(); + void db.select(); + expect(getBookmark()).toBe(BEFORE_SAVE); + }); + } finally { + resume(); + await first; + } + withRuntimeEnv(env, () => { + expect(getBookmark()).toBeNull(); + void db.select(); + expect(getBookmark()).toBeNull(); + }); + expect(withSession.mock.calls.map(([start]) => start)).toEqual([ + AFTER_SAVE, + AFTER_SAVE, + BEFORE_SAVE, + 'first-unconstrained', + ]); + }); + + it('requires a Void request scope for the default-session middleware helpers', async () => { + const { getBookmark, setSession } = await loadClient(); + expect(() => setSession(AFTER_SAVE)).toThrow('outside a runtime handler'); + expect(() => getBookmark()).toThrow('outside a runtime handler'); + }); + + it('reads an explicit client bookmark without a Void request scope', async () => { + const { createDb, getBookmark } = await loadClient(); + const { withSession, env } = mockBinding(); + const client = createDb(env[testCase.bindingName] as unknown as D1Database, { + session: AFTER_SAVE, + }); + expect(getBookmark(client)).toBe(AFTER_SAVE); + expect(withSession).toHaveBeenCalledExactlyOnceWith(AFTER_SAVE); + }); + + it('rejects bookmark inspection of a client backed by a bare D1 binding', async () => { + const { getBookmark } = await loadClient(); + const { env } = mockBinding(); + const client = drizzle(env[testCase.bindingName] as unknown as D1Database); + expect(() => getBookmark(client)).toThrow('requires a D1 session-backed client'); + }); +}); + +it('starts each published db access on primary outside a Void request scope', () => { + const withSession = vi.fn(() => ({ getBookmark: () => null })); + envContext.run({ DB: { withSession } }, () => { + void runtimeDb.db.select; + void runtimeDb.db.select; + void runtimeDb.db.select; + }); + expect(withSession.mock.calls).toEqual([['first-primary'], ['first-primary'], ['first-primary']]); + expect(new Set(withSession.mock.results.map((result) => result.value)).size).toBe(3); +}); diff --git a/packages/void/test/unit/db-session.typecheck.ts b/packages/void/test/unit/db-session.typecheck.ts index 6a02f6c92..66270035e 100644 --- a/packages/void/test/unit/db-session.typecheck.ts +++ b/packages/void/test/unit/db-session.typecheck.ts @@ -1,5 +1,11 @@ +import { integer, sqliteTable } from 'drizzle-orm/sqlite-core'; import { expectTypeOf } from 'vite-plus/test'; -import { createDb, type DrizzleD1Database } from '../../src/runtime/db/index.ts'; +import { + createDb, + getBookmark, + setSession, + type DrizzleD1Database, +} from '../../src/runtime/db/index.ts'; declare const binding: D1Database; @@ -7,7 +13,21 @@ expectTypeOf(createDb(binding, { session: 'first-primary' })).toEqualTypeOf(); +expectTypeOf(getBookmark(createDb(binding))).toEqualTypeOf(); + +const schema = { profile: sqliteTable('profile', { id: integer('id').primaryKey() }) }; +declare const schemaClient: DrizzleD1Database; +expectTypeOf(getBookmark(schemaClient)).toEqualTypeOf(); + +// @ts-expect-error Session starts must be strings. +createDb(binding, { session: 123 }); // @ts-expect-error Session options do not accept arbitrary settings. createDb(binding, { primary: true }); diff --git a/packages/void/test/unit/plugin-drizzle.test.ts b/packages/void/test/unit/plugin-drizzle.test.ts index 05bc5b0b5..1c8e3408b 100644 --- a/packages/void/test/unit/plugin-drizzle.test.ts +++ b/packages/void/test/unit/plugin-drizzle.test.ts @@ -183,6 +183,10 @@ export function drizzle(config) { /^import \{ ((?:getRuntimeBinding|getRuntimeRequestResource|requireRuntimeBinding)[^}]*) \} from .*;$/m, (_match, imports: string) => `import { ${imports} } from ${JSON.stringify(envUrl)};`, ); + code = code.replace( + /^import \{ createD1SessionAccess \} from .*;$/m, + `import { createD1SessionAccess } from ${JSON.stringify(new URL('../../src/runtime/db/session.ts', import.meta.url).href)};`, + ); writeFileSync(join(root, 'virtual-db.mjs'), code); writeFileSync( join(root, 'harness.mjs'), @@ -425,7 +429,9 @@ describe('drizzlePlugin db typing generation', () => { const dts = readFileSync(join(root, '.void', 'db.d.ts'), 'utf8'); expect(dts).toContain('import type { DrizzleD1Database } from "void/_db";'); - expect(dts).toContain('options?: { session?: D1SessionConstraint }'); + expect(dts).toContain('options?: { session?: D1SessionConstraint | D1SessionBookmark }'); + expect(dts).toContain('export declare function setSession('); + expect(dts).toContain('export declare function getBookmark('); expect(dts).toContain('): DrizzleD1Database;'); expect(dts).not.toContain('void/_db-pg'); }); @@ -915,8 +921,8 @@ export const requestPoolOptions = (env) => expect(resolved).toBe('\0virtual:void-db'); const code = load.call({}, '\0virtual:void-db'); - expect(code).toContain('requireRuntimeBinding("myapp_db")'); - expect(code).not.toContain('requireRuntimeBinding("DB")'); + expect(code).toContain('createD1SessionAccess("myapp_db")'); + expect(code).not.toContain('createD1SessionAccess("DB")'); }); it('can keep void/db off tsconfig paths for metaframeworks that materialize aliases', () => { diff --git a/packages/void/vite.config.ts b/packages/void/vite.config.ts index faab5bdce..a1773edb5 100644 --- a/packages/void/vite.config.ts +++ b/packages/void/vite.config.ts @@ -26,6 +26,7 @@ function injectWorkersTypesReferencePlugin() { // Patch declaration entrypoints whose source uses Cloudflare globals. const targets = new Set([ 'runtime/handler/index.d.mts', + 'runtime/db/index.d.mts', 'runtime/env/public.d.mts', 'runtime/sandbox/index.d.mts', 'runtime/sandbox/container.d.mts', @@ -99,6 +100,7 @@ export default defineConfig({ 'src/runtime/env/public.ts', 'src/runtime/env/public-client.ts', 'src/runtime/db/index.ts', + 'src/runtime/db/session.ts', 'src/runtime/db/postgres.ts', 'src/runtime/db/mysql.ts', 'src/runtime/durable/index.ts', diff --git a/playground/d1-sessions-api/.gitignore b/playground/d1-sessions-api/.gitignore new file mode 100644 index 000000000..54406eb2b --- /dev/null +++ b/playground/d1-sessions-api/.gitignore @@ -0,0 +1 @@ +cloudflare.config.ts diff --git a/playground/d1-sessions-api/README.md b/playground/d1-sessions-api/README.md new file mode 100644 index 000000000..5c06eec0f --- /dev/null +++ b/playground/d1-sessions-api/README.md @@ -0,0 +1,73 @@ +# D1 Sessions API + +React Pages demo comparing real D1 read-after-write behavior with and without bookmark propagation. Choose browser-cookie transport or an immediate server-side read through an independent session. The home page includes code snippets and VS Code source links, like `playground/http-errors`. + +## Local development + +From the repository root: + +```sh +vp install +cd playground/d1-sessions-api +vp exec void db migrate +cd ../.. +vp run --filter ./playground/d1-sessions-api dev +``` + +Open `/without-bookmark` and `/with-bookmark`. Choose the same **Read timing** and pressure settings in both variants: + +Selections persist across reloads and deployments in browser storage and the page URL, and are shared between variants. Explicit URL parameters take precedence. The selected write/read experiment is labeled at the top; trial results themselves remain in page memory. + +### Read-only routing baseline + +Start with **Probe once** or choose a **Probes** count and click **Run probes** above the write experiments. The probe count is independent of the trial count; both are saved in browser storage and the URL. Each `GET /api/routing` performs one indexed SELECT through a fresh `first-unconstrained` session using `void/db .run()`, without saves, pressure, or bookmark propagation. Probes run sequentially and stop on an error. + +Counters show primary, replica, unknown, and error totals. Each sample shows Worker colo, D1 region/colo, attempts, rows returned, wall time, and expandable complete D1 metadata, rows, bookmark, and errors. Missing `total_attempts` is shown as **not reported**, not assumed to mean one. The same complete metadata and timing are available for trial reads. Structured server logs use `d1-routing-probe` and `d1-routing-probe-error` events. + +The probe reads the first profile by indexed ID; an empty database still measures routing. It does not measure read-after-write consistency or force replica selection. Avoid running write experiments in another tab while collecting a no-write baseline. + +### Write/read experiments + +- **Browser redirect (cookie)** (default): each trial performs an API POST followed by a 303 GET and displays the result in place. Only the fixed variant transports its bookmark in an HttpOnly cookie. +- **Immediate server read**: each trial performs one POST. Both variants write through a new unconstrained session, then read once through a separate new session without a browser round trip. The control starts the reader unconstrained; the fixed variant passes the completed write's bookmark directly to the reader's `createDb()`. Neither variant reads or updates the bookmark cookie in this mode. Use `?experiment=immediate` to open this mode directly. + +Each trial shows its read target, revision, bookmarks, and D1 metadata. Counters separate primary reads, replica reads, stale replica reads, unknown targets (including local D1), and read errors. There is one read per trial, with no concurrent readers or writers. + +Choose **20** (default), **50**, **100**, **200**, or **500** trials before clicking “Run trials”. It repeats the selected experiment sequentially, displaying expected/observed revisions, stale counts, D1 primary/replica metadata, and bookmarks. Immediate mode narrows the time available for replication to catch up; D1 can still route reads to the primary, and neither mode guarantees a stale read. + +Failed requests appear as **errored**, separately from fresh/stale reads. A failed trial stops the run and stays in the history with an expandable error row. Error details include the failing phase, HTTP status, request ID when available, server error messages, stack traces, and nested causes. This diagnostic playground returns those details from its API. A failed save may have committed before its connection was interrupted; it is not automatically retried. + +Local Miniflare does not reproduce distributed replica lag: both variants normally pass. No artificial delay, fake bookmark, or simulated stale data is used. + +**Add replication pressure** is checked by default at **256 KiB per trial**. Choose **256 KiB**, **512 KiB**, **1 MiB**, or **2 MiB**. Each trial saves its revision and rewrites unrelated 256 KiB BLOB rows in one transaction, then reads the revision once through an independent session. No database operations are issued in parallel. The fixed variant's read bookmark comes from that completed write transaction. + +Payload slots are shared across visitors and reused, using at most eight slots (2 MiB). Previously written data is not deleted when choosing smaller settings. At the defaults, 20 trials write 5 MiB of pressure data. The UI shows the selected total. API `pressure=0.25`, `pressure=0.5`, `pressure=1`, and `pressure=2` select these sizes; other values disable pressure. Uncheck the option for revision-only writes. Use a disposable database; pressure does not guarantee stale reads. + +Click **Run trials** to write and read automatically using the selected timing. Every trial finishes before the next starts; there is no one-off Save button. + +## Deploy your own demo + +Copy `cloudflare.config.example.ts` to `cloudflare.config.ts`, replace the `YOUR_*` placeholders with your account, Worker name, database name, and database ID, and update the import in `void.config.ts` to use that file. Use a valid lowercase Worker name for `YOUR_WORKER_ID`. Credentials come from the `cf` wrapper through `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID`. + +The example uses the Singapore placement hint `aws:ap-southeast-1`. Provision a D1 primary in Western Europe (`WEUR`) with read replication enabled (`auto`) to test across regions. **Worker placement / colo** displays `cf-placement` when available (for example, `remote-SIN`), falling back to the request's Cloudflare colo. Placement influences where the Worker executes; it does not force D1 reads onto a replica. Check each read's primary/replica metadata separately. + +Workers Observability is enabled with persisted invocation logs and 100% log sampling. Server errors also emit a structured `d1-demo-error` log. + +To deploy, run these commands from this directory. Build with Vite+ first, then pass the generated output to `cf`: + +```sh +vp build +cf deploy --prebuilt --mode production --dry-run +cf d1 migrations apply YOUR_DATABASE_ID --dir db/migrations +cf deploy --prebuilt --mode production --no-provision +``` + +The migration command applies only pending files and uses the `d1_migrations` tracking table. Local development uses an independent SQLite database; run `vp exec void db migrate` after changing the database configuration to initialize it. + +Try the control repeatedly from a region far from the Western Europe primary, then compare the manual-bookmark variant. A stale read is timing-dependent and is not guaranteed: a replica may already be caught up, or the read may hit the primary. D1 metadata identifies where each read actually ran. [D1 automatically places replicas in every supported region](https://developers.cloudflare.com/d1/best-practices/read-replication/#read-replica-locations); individual replica locations cannot be selected. + +Provision a database with `cf d1 create --name YOUR_DATABASE_NAME --primary-location-hint weur --read-replication-mode auto`. Check its current region and replication settings with `cf d1 get YOUR_DATABASE_ID`. When switching databases, clear the `d1-demo-bookmark` cookie before testing the bookmark variant so it starts a session on the new database. + +The two variants and timing modes share implementation but have independent profile rows per browser. In redirect mode, only `/with-bookmark` and `/api/with-bookmark` read and update the HttpOnly bookmark cookie using `setSession()` and `getBookmark()`. The control ignores that cookie even after visiting the fixed page. `X-D1-Bookmark` exposes the outgoing read bookmark for inspection in DevTools in both experiments, but the control never sends it back. + +ISR is disabled and responses use `private, no-store`. Run in a single tab without concurrent writes: concurrent cookies can overwrite newer bookmarks, and a later save can replace the exact revision being compared. This public demo writes one profile row per visitor per variant and timing mode; use a disposable D1 database and remove it when finished. It is not an authentication or production data-management example. diff --git a/playground/d1-sessions-api/cloudflare.config.example.ts b/playground/d1-sessions-api/cloudflare.config.example.ts new file mode 100644 index 000000000..ac9bd3638 --- /dev/null +++ b/playground/d1-sessions-api/cloudflare.config.example.ts @@ -0,0 +1,28 @@ +import { bindings, defineConfig } from 'cf/config'; + +export default defineConfig({ + accountId: 'YOUR_ACCOUNT_ID', + worker: { + name: 'YOUR_WORKER_ID', + compatibilityDate: '2026-02-24', + compatibilityFlags: ['nodejs_als'], + entrypoint: './.void/entry.ts', + workersDev: true, + placement: { region: 'aws:ap-southeast-1' }, + observability: { + enabled: true, + headSamplingRate: 1, + logs: { + enabled: true, + invocationLogs: true, + persist: true, + }, + }, + env: { + DB: bindings.d1({ + name: 'YOUR_DATABASE_NAME', + id: 'YOUR_DATABASE_ID', + }), + }, + }, +}); diff --git a/playground/d1-sessions-api/db/migrations/20261111235451_long_silver_surfer.sql b/playground/d1-sessions-api/db/migrations/20261111235451_long_silver_surfer.sql new file mode 100644 index 000000000..16eda4527 --- /dev/null +++ b/playground/d1-sessions-api/db/migrations/20261111235451_long_silver_surfer.sql @@ -0,0 +1,5 @@ +CREATE TABLE `bookmark_profiles` ( + `id` text PRIMARY KEY NOT NULL, + `revision` text NOT NULL, + `saved_at` text NOT NULL +); diff --git a/playground/d1-sessions-api/db/migrations/20261112024822_robust_frog_thor.sql b/playground/d1-sessions-api/db/migrations/20261112024822_robust_frog_thor.sql new file mode 100644 index 000000000..9d461d785 --- /dev/null +++ b/playground/d1-sessions-api/db/migrations/20261112024822_robust_frog_thor.sql @@ -0,0 +1,4 @@ +CREATE TABLE `bookmark_pressure_chunks` ( + `id` integer PRIMARY KEY NOT NULL, + `payload` blob NOT NULL +); diff --git a/playground/d1-sessions-api/db/migrations/meta/20261111235451_snapshot.json b/playground/d1-sessions-api/db/migrations/meta/20261111235451_snapshot.json new file mode 100644 index 000000000..1554530c8 --- /dev/null +++ b/playground/d1-sessions-api/db/migrations/meta/20261111235451_snapshot.json @@ -0,0 +1,49 @@ +{ + "version": "6", + "dialect": "sqlite", + "id": "d3ab64ca-4c40-441b-9fab-61fbdc8cb89c", + "prevId": "00000000-0000-0000-0000-000000000000", + "tables": { + "bookmark_profiles": { + "name": "bookmark_profiles", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true, + "autoincrement": false + }, + "revision": { + "name": "revision", + "type": "text", + "primaryKey": false, + "notNull": true, + "autoincrement": false + }, + "saved_at": { + "name": "saved_at", + "type": "text", + "primaryKey": false, + "notNull": true, + "autoincrement": false + } + }, + "indexes": {}, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "checkConstraints": {} + } + }, + "views": {}, + "enums": {}, + "_meta": { + "schemas": {}, + "tables": {}, + "columns": {} + }, + "internal": { + "indexes": {} + } +} diff --git a/playground/d1-sessions-api/db/migrations/meta/20261112024822_snapshot.json b/playground/d1-sessions-api/db/migrations/meta/20261112024822_snapshot.json new file mode 100644 index 000000000..0c00bacf4 --- /dev/null +++ b/playground/d1-sessions-api/db/migrations/meta/20261112024822_snapshot.json @@ -0,0 +1,73 @@ +{ + "version": "6", + "dialect": "sqlite", + "id": "57fdfcdf-e304-4236-aab1-27b848708481", + "prevId": "d3ab64ca-4c40-441b-9fab-61fbdc8cb89c", + "tables": { + "bookmark_pressure_chunks": { + "name": "bookmark_pressure_chunks", + "columns": { + "id": { + "name": "id", + "type": "integer", + "primaryKey": true, + "notNull": true, + "autoincrement": false + }, + "payload": { + "name": "payload", + "type": "blob", + "primaryKey": false, + "notNull": true, + "autoincrement": false + } + }, + "indexes": {}, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "checkConstraints": {} + }, + "bookmark_profiles": { + "name": "bookmark_profiles", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true, + "autoincrement": false + }, + "revision": { + "name": "revision", + "type": "text", + "primaryKey": false, + "notNull": true, + "autoincrement": false + }, + "saved_at": { + "name": "saved_at", + "type": "text", + "primaryKey": false, + "notNull": true, + "autoincrement": false + } + }, + "indexes": {}, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "checkConstraints": {} + } + }, + "views": {}, + "enums": {}, + "_meta": { + "schemas": {}, + "tables": {}, + "columns": {} + }, + "internal": { + "indexes": {} + } +} diff --git a/playground/d1-sessions-api/db/migrations/meta/_journal.json b/playground/d1-sessions-api/db/migrations/meta/_journal.json new file mode 100644 index 000000000..58cba499a --- /dev/null +++ b/playground/d1-sessions-api/db/migrations/meta/_journal.json @@ -0,0 +1,20 @@ +{ + "version": "7", + "dialect": "sqlite", + "entries": [ + { + "idx": 0, + "version": "6", + "when": 1794441291547, + "tag": "20261111235451_long_silver_surfer", + "breakpoints": true + }, + { + "idx": 1, + "version": "6", + "when": 1794451702064, + "tag": "20261112024822_robust_frog_thor", + "breakpoints": true + } + ] +} diff --git a/playground/d1-sessions-api/db/schema.ts b/playground/d1-sessions-api/db/schema.ts new file mode 100644 index 000000000..7325f7c84 --- /dev/null +++ b/playground/d1-sessions-api/db/schema.ts @@ -0,0 +1,12 @@ +import { blob, integer, sqliteTable, text } from 'void/schema-d1'; + +export const profiles = sqliteTable('bookmark_profiles', { + id: text('id').primaryKey(), + revision: text('revision').notNull(), + savedAt: text('saved_at').notNull(), +}); + +export const pressureChunks = sqliteTable('bookmark_pressure_chunks', { + id: integer('id').primaryKey(), + payload: blob('payload', { mode: 'buffer' }).notNull(), +}); diff --git a/playground/d1-sessions-api/middleware/database.ts b/playground/d1-sessions-api/middleware/database.ts new file mode 100644 index 000000000..e2dd14a50 --- /dev/null +++ b/playground/d1-sessions-api/middleware/database.ts @@ -0,0 +1,96 @@ +import { getCookie, setCookie } from 'hono/cookie'; +import { defineMiddleware } from 'void'; +import { getBookmark, setSession } from 'void/db'; +import { + BOOKMARK_COOKIE, + errorObservation, + experimentForQuery, + pressureMiBForQuery, + serializeError, + variantForPath, + VISITOR_COOKIE, +} from '../src/demo.ts'; + +export default defineMiddleware(async (c, next) => { + const variant = variantForPath(c.req.path); + if (!variant) { + await next(); + return; + } + + c.header('Cache-Control', 'private, no-store'); + const cookieOptions = { + httpOnly: true, + secure: new URL(c.req.url).protocol === 'https:', + sameSite: 'Lax' as const, + path: '/', + }; + let visitor = getCookie(c, VISITOR_COOKIE); + if (!visitor || !/^[0-9a-f-]{36}$/.test(visitor)) { + visitor = crypto.randomUUID(); + setCookie(c, VISITOR_COOKIE, visitor, cookieOptions); + } + c.set('demoVisitor', visitor); + const experiment = experimentForQuery(c.req.query('experiment')); + + // The control ignores the bookmark cookie, even after visiting the fixed variant. + if (experiment === 'redirect' && variant === 'with-bookmark') { + setSession(getCookie(c, BOOKMARK_COOKIE) ?? 'first-unconstrained'); + } + + await next(); + + if (c.error) { + // Log messages explicitly: workerd's Error rendering may contain only the stack. + const errors = serializeError(c.error); + console.error( + JSON.stringify({ + event: 'd1-demo-error', + method: c.req.method, + path: c.req.path, + pressure: c.req.query('pressure') ?? '0', + experiment, + errors, + }), + ); + if (c.req.path.startsWith('/api/')) { + // This diagnostic playground deliberately returns server errors for inspection. + c.header('Cache-Control', 'private, no-store'); + const observation = errorObservation( + variant, + pressureMiBForQuery(c.req.query('pressure')), + { + phase: c.req.method === 'POST' && !c.get('demoWriteRevision') ? 'save' : 'read', + status: c.res.status, + requestId: c.req.header('cf-ray') ?? null, + causes: errors, + }, + (c.get('demoWriteRevision') as string | undefined) ?? + (c.req.method === 'GET' ? (c.req.query('expected') ?? null) : null), + experiment, + ); + observation.incomingBookmark = + experiment === 'immediate' + ? ((c.get('demoReadBookmark') as string | undefined) ?? null) + : variant === 'with-bookmark' + ? (getCookie(c, BOOKMARK_COOKIE) ?? null) + : null; + observation.writeBookmark = (c.get('demoWriteBookmark') as string | undefined) ?? null; + const response = c.json(observation); + c.res = new Response(response.body, { status: c.res.status, headers: response.headers }); + } + return; + } + + if (experiment === 'immediate') { + return; + } + + const bookmark = getBookmark(); + if (bookmark) { + c.header('X-D1-Bookmark', bookmark); + if (variant === 'with-bookmark') { + setCookie(c, BOOKMARK_COOKIE, bookmark, cookieOptions); + } + } +}); diff --git a/playground/d1-sessions-api/package.json b/playground/d1-sessions-api/package.json new file mode 100644 index 000000000..e1f8d28d0 --- /dev/null +++ b/playground/d1-sessions-api/package.json @@ -0,0 +1,26 @@ +{ + "name": "playground-d1-sessions-api", + "private": true, + "type": "module", + "scripts": { + "build": "vp build", + "dev": "vp dev", + "preview": "vp preview", + "typecheck": "tsc --noEmit" + }, + "dependencies": { + "hono": "catalog:", + "react": "catalog:", + "react-dom": "catalog:" + }, + "devDependencies": { + "@types/react": "^19.3.0", + "@types/react-dom": "^19.3.0", + "@void/react": "workspace:*", + "cf": "catalog:", + "typescript": "catalog:", + "vite": "catalog:", + "vite-plus": "catalog:", + "void": "workspace:*" + } +} diff --git a/playground/d1-sessions-api/pages/index.tsx b/playground/d1-sessions-api/pages/index.tsx new file mode 100644 index 000000000..9782a9833 --- /dev/null +++ b/playground/d1-sessions-api/pages/index.tsx @@ -0,0 +1,85 @@ +import { Link } from '@void/react'; +import { SourceLink } from '../src/source-link.tsx'; + +export default function Home() { + return ( + <> +

D1 Sessions API

+

+ A write succeeds on the primary. A read in the next request can reach a replica that has not + caught up yet. Compare the same write/read flow with and without a bookmark, using a browser + redirect or an immediate server-side read through a separate session. +

+

+ Related:{' '} + Issue #783 | PR #XXX: TBD +

+
+ How to see the difference +
    +
  1. Deploy to Cloudflare with D1 read replication enabled.
  2. +
  3. + Open the control and choose “Browser redirect (cookie)” or “Immediate server read”. + Choose a count and “Run trials”. +
  4. +
  5. Look for a stale read: the observed revision differs from the acknowledged write.
  6. +
  7. + Repeat with the same timing and pressure in the manual-bookmark variant, which passes + the write’s bookmark to the read session. +
  8. +
+

+ Immediate mode removes the browser round trip between the write and read. Both variants + create one independent read session per trial; only the fixed variant initializes it with + the write bookmark. Each trial finishes before the next starts. Browser redirect mode + demonstrates transport through an HttpOnly cookie instead. +

+

+ This demo does not fake replica lag. Local D1 usually reads fresh in both variants, and + even a live replica may already be caught up. A fresh control read is not proof of + consistency. Try from a region far from the primary. The demo disables ISR and response + caching. +

+

+ Each browser has its own profile per variant. Run trials sequentially in one tab: + concurrent saves and cookie responses can race. Bookmarks do not promise to include + unrelated later writes from another client. +

+

+ + Cloudflare: resume a D1 session from a bookmark + +

+
+
+
+
+

Without bookmark

+

+ +

+
{'// No bookmark transport.'}
+

+ Every request starts unconstrained. A successful save can be followed by a stale read. +

+ Playground +
+
+

Manual bookmark

+

+ +

+
{`setSession(getCookie(c, 'd1-demo-bookmark') ?? 'first-unconstrained');
+await next();
+const bookmark = getBookmark();
+if (bookmark) setCookie(c, 'd1-demo-bookmark', bookmark, options);`}
+

+ Middleware resumes the previous session using an HttpOnly cookie. The redirected read + sees data at least as up-to-date as the acknowledged save. +

+ Playground +
+
+ + ); +} diff --git a/playground/d1-sessions-api/pages/layout.tsx b/playground/d1-sessions-api/pages/layout.tsx new file mode 100644 index 000000000..fd5ff903c --- /dev/null +++ b/playground/d1-sessions-api/pages/layout.tsx @@ -0,0 +1,21 @@ +import { Link } from '@void/react'; +import type { ReactNode } from 'react'; +import './styles.css'; + +export default function Layout({ children }: { children: ReactNode }) { + return ( +
+
+ +
+
+
{children}
+
+ ); +} diff --git a/playground/d1-sessions-api/pages/styles.css b/playground/d1-sessions-api/pages/styles.css new file mode 100644 index 000000000..422d0999d --- /dev/null +++ b/playground/d1-sessions-api/pages/styles.css @@ -0,0 +1,50 @@ +.container { + box-sizing: border-box; + max-width: 100rem; + margin-inline: auto; + padding: 1rem; +} +.container p { + max-width: 75ch; +} +.controls { + display: flex; + flex-wrap: wrap; + align-items: center; + gap: 1rem; +} +.variants { + display: flex; + flex-wrap: wrap; + align-items: flex-start; + gap: 1rem 2rem; +} +.variants > section { + flex: 1 1 22rem; + min-width: 0; +} +pre { + white-space: pre-wrap; +} +pre, +code { + overflow-wrap: anywhere; +} +.table-scroll { + overflow-x: auto; +} + +.result.fresh h2, +tr.fresh td:nth-child(2), +.fresh-count { + color: green; +} + +.result.stale h2, +.result.errored h2, +tr.errored td:nth-child(2), +.error-count, +tr.stale td:nth-child(2), +.stale-count { + color: #b00020; +} diff --git a/playground/d1-sessions-api/pages/with-bookmark.server.ts b/playground/d1-sessions-api/pages/with-bookmark.server.ts new file mode 100644 index 000000000..da8fa1066 --- /dev/null +++ b/playground/d1-sessions-api/pages/with-bookmark.server.ts @@ -0,0 +1,4 @@ +export { loader, action } from '../src/database.ts'; + +export const revalidate = 0; +export const prerender = false; diff --git a/playground/d1-sessions-api/pages/with-bookmark.tsx b/playground/d1-sessions-api/pages/with-bookmark.tsx new file mode 100644 index 000000000..9f446e134 --- /dev/null +++ b/playground/d1-sessions-api/pages/with-bookmark.tsx @@ -0,0 +1 @@ +export { default } from '../src/demo-page.tsx'; diff --git a/playground/d1-sessions-api/pages/without-bookmark.server.ts b/playground/d1-sessions-api/pages/without-bookmark.server.ts new file mode 100644 index 000000000..da8fa1066 --- /dev/null +++ b/playground/d1-sessions-api/pages/without-bookmark.server.ts @@ -0,0 +1,4 @@ +export { loader, action } from '../src/database.ts'; + +export const revalidate = 0; +export const prerender = false; diff --git a/playground/d1-sessions-api/pages/without-bookmark.tsx b/playground/d1-sessions-api/pages/without-bookmark.tsx new file mode 100644 index 000000000..9f446e134 --- /dev/null +++ b/playground/d1-sessions-api/pages/without-bookmark.tsx @@ -0,0 +1 @@ +export { default } from '../src/demo-page.tsx'; diff --git a/playground/d1-sessions-api/routes/api/[variant].ts b/playground/d1-sessions-api/routes/api/[variant].ts new file mode 100644 index 000000000..09bc6b973 --- /dev/null +++ b/playground/d1-sessions-api/routes/api/[variant].ts @@ -0,0 +1 @@ +export { loader as GET, action as POST } from '../../src/database.ts'; diff --git a/playground/d1-sessions-api/routes/api/routing.ts b/playground/d1-sessions-api/routes/api/routing.ts new file mode 100644 index 000000000..1b71bf17e --- /dev/null +++ b/playground/d1-sessions-api/routes/api/routing.ts @@ -0,0 +1,46 @@ +import { defineHandler } from 'void'; +import { createDb, getBookmark, sql } from 'void/db'; +import { serializeError, type RoutingProbe } from '../../src/demo.ts'; + +export const GET = defineHandler(async (c) => { + c.header('Cache-Control', 'private, no-store'); + // No writes, pressure, request-scoped db, or incoming bookmark cookies here. + // Each probe reads one indexed row through one fresh session. + const query = 'SELECT revision, saved_at FROM bookmark_profiles ORDER BY id LIMIT 1'; + const workerColo = + c.req.header('cf-placement') ?? + (typeof c.req.raw.cf?.colo === 'string' ? c.req.raw.cf.colo : null); + const path = 'void-run'; + const started = performance.now(); + try { + const client = createDb(c.env.DB, { session: 'first-unconstrained' }); + const result = await client.run(sql.raw(query)); + const probe: RoutingProbe = { + path, + workerColo, + elapsedMs: performance.now() - started, + metadata: { ...result.meta }, + rows: result.results, + bookmark: getBookmark(client), + }; + console.log(JSON.stringify({ event: 'd1-routing-probe', ...probe })); + return c.json(probe); + } catch (cause) { + const probe: RoutingProbe = { + path, + workerColo, + elapsedMs: performance.now() - started, + metadata: null, + rows: [], + bookmark: null, + error: { + phase: 'probe', + status: 500, + requestId: c.req.header('cf-ray') ?? null, + causes: serializeError(cause), + }, + }; + console.error(JSON.stringify({ event: 'd1-routing-probe-error', ...probe })); + return c.json(probe, 500); + } +}); diff --git a/playground/d1-sessions-api/src/database.ts b/playground/d1-sessions-api/src/database.ts new file mode 100644 index 000000000..3d06a723f --- /dev/null +++ b/playground/d1-sessions-api/src/database.ts @@ -0,0 +1,133 @@ +import { pressureChunks, profiles } from '@schema'; +import { getCookie } from 'hono/cookie'; +import { HTTPException } from 'hono/http-exception'; +import { defineHandler, type CloudContext } from 'void'; +import { createDb, db, getBookmark, sql } from 'void/db'; +import { + BOOKMARK_COOKIE, + experimentForQuery, + pressureMiBForQuery, + variantForPath, + type Observation, + type Variant, +} from './demo.ts'; + +function variant(c: CloudContext): Variant { + const value = variantForPath(c.req.path); + if (!value) { + throw new HTTPException(404); + } + return value; +} + +function profileId(c: CloudContext): string { + const suffix = experimentForQuery(c.req.query('experiment')) === 'immediate' ? ':immediate' : ''; + return `${String(c.get('demoVisitor'))}:${variant(c)}${suffix}`; +} + +async function readObservation( + c: CloudContext, + client: typeof db, + expected: string | null, + incomingBookmark: string | null, + writeBookmark: string | null = null, +): Promise { + const mode = variant(c); + const started = performance.now(); + // Keep the raw D1 metadata from the very read being compared with the write receipt. + const result = await client.run(sql` + SELECT revision, saved_at FROM ${profiles} WHERE ${profiles.id} = ${profileId(c)} + `); + const row = result.results[0] as { revision: string; saved_at: string } | undefined; + const observed = row?.revision ?? null; + return { + experiment: experimentForQuery(c.req.query('experiment')), + pressureMiB: pressureMiBForQuery(c.req.query('pressure')), + variant: mode, + expected, + observed, + savedAt: row?.saved_at ?? null, + outcome: expected === null ? 'idle' : observed === expected ? 'fresh' : 'stale', + incomingBookmark, + writeBookmark, + outgoingBookmark: getBookmark(client), + servedByPrimary: result.meta.served_by_primary ?? null, + servedByRegion: result.meta.served_by_region ?? null, + metadata: { ...result.meta }, + elapsedMs: performance.now() - started, + workerColo: + c.req.header('cf-placement') ?? + (typeof c.req.raw.cf?.colo === 'string' ? c.req.raw.cf.colo : null), + }; +} + +export const loader = defineHandler(async (c): Promise => { + const immediate = experimentForQuery(c.req.query('experiment')) === 'immediate'; + return readObservation( + c, + immediate ? createDb(c.env.DB) : db, + c.req.query('expected') ?? null, + !immediate && variant(c) === 'with-bookmark' ? (getCookie(c, BOOKMARK_COOKIE) ?? null) : null, + ); +}); + +export const action = defineHandler(async (c) => { + const origin = c.req.header('origin'); + if (origin && origin !== new URL(c.req.url).origin) { + throw new HTTPException(403, { message: 'Use the demo from the same origin.' }); + } + const mode = variant(c); + const revision = crypto.randomUUID(); + const savedAt = new Date().toISOString(); + const pressureMiB = pressureMiBForQuery(c.req.query('pressure')); + const immediate = experimentForQuery(c.req.query('experiment')) === 'immediate'; + // Both immediate variants start an independent, unconstrained write session. + const writer = immediate ? createDb(c.env.DB) : db; + const save = writer + .insert(profiles) + .values({ id: profileId(c), revision, savedAt }) + .onConflictDoUpdate({ target: profiles.id, set: { revision, savedAt } }); + // One transaction per trial, including optional BLOB pressure. No parallel writers. + // Reuse up to eight 256 KiB slots; existing larger experiments are left untouched. + if (pressureMiB) { + await writer.batch([ + save, + ...Array.from({ length: pressureMiB * 4 }, (_, id) => + writer + .insert(pressureChunks) + .values({ id, payload: sql`randomblob(262144)` }) + .onConflictDoUpdate({ + target: pressureChunks.id, + set: { payload: sql`randomblob(262144)` }, + }), + ), + ]); + } else { + await save; + } + // Mark the acknowledged write before reading so failures keep the write receipt. + c.set('demoWriteRevision', revision); + if (immediate) { + const writeBookmark = getBookmark(writer); + c.set('demoWriteBookmark', writeBookmark); + if (mode === 'with-bookmark' && writeBookmark === null) { + throw new Error('D1 did not return a bookmark for the acknowledged write.'); + } + const incomingBookmark = mode === 'with-bookmark' ? writeBookmark : null; + c.set('demoReadBookmark', incomingBookmark); + const reader = createDb(c.env.DB, { session: incomingBookmark ?? 'first-unconstrained' }); + const observation = await readObservation(c, reader, revision, incomingBookmark, writeBookmark); + if (observation.outgoingBookmark) { + c.header('X-D1-Bookmark', observation.outgoingBookmark); + } + return c.json(observation); + } + + // Carry only the expected revision in the URL, not the observed value or a D1 bookmark. + // Following this redirect issues a genuinely separate read request. + const path = c.req.path.startsWith('/api/') ? `/api/${mode}` : `/${mode}`; + return c.redirect( + `${path}?expected=${revision}${pressureMiB ? `&pressure=${pressureMiB}` : ''}`, + 303, + ); +}); diff --git a/playground/d1-sessions-api/src/demo-page.tsx b/playground/d1-sessions-api/src/demo-page.tsx new file mode 100644 index 000000000..c7a4259ea --- /dev/null +++ b/playground/d1-sessions-api/src/demo-page.tsx @@ -0,0 +1,491 @@ +import { Fragment, useEffect, useState } from 'react'; +import { + DEFAULT_PRESSURE_MIB, + errorObservation, + experimentForQuery, + experimentLabel, + PRESSURE_OPTIONS, + pressureLabel, + RUN_COUNTS, + type Observation, + type TrialError, +} from './demo.ts'; +import { MetadataDetails } from './metadata.tsx'; +import { RoutingProbePanel } from './routing-probe.tsx'; +import { SourceLink } from './source-link.tsx'; + +export default function DemoPage(props: Observation) { + // Keyed by the variant so client navigation never mixes the two trial histories. + return ; +} + +function Trials({ initial }: { initial: Observation }) { + const [results, setResults] = useState>([]); + const [running, setRunning] = useState(false); + const [trialsRunning, setTrialsRunning] = useState(false); + const [trialCount, setTrialCount] = useState(20); + const [runSize, setRunSize] = useState(20); + const [pressure, setPressure] = useState(true); + const [pressureMiB, setPressureMiB] = useState(initial.pressureMiB || DEFAULT_PRESSURE_MIB); + const [experiment, setExperiment] = useState(initial.experiment); + const [probeCount, setProbeCount] = useState(20); + const [settingsReady, setSettingsReady] = useState(false); + useEffect(() => { + let saved: Record = {}; + try { + saved = JSON.parse(localStorage.getItem('d1-demo-settings-v1') ?? '{}') ?? {}; + } catch { + // Browser storage may be unavailable. The URL still persists selections. + } + const params = new URLSearchParams(location.search); + const value = (key: string) => params.get(key) ?? saved[key]; + const timing = value('experiment'); + if (timing === 'redirect' || timing === 'immediate') { + setExperiment(timing); + } + const trials = Number(value('trials')); + if (RUN_COUNTS.some((count) => count === trials)) { + setTrialCount(trials); + } + const probes = Number(value('probes')); + if (RUN_COUNTS.some((count) => count === probes)) { + setProbeCount(probes); + } + const size = Number( + params.get('size') ?? params.get('pressure') ?? saved.size ?? saved.pressure, + ); + if (PRESSURE_OPTIONS.some((option) => option === size)) { + setPressureMiB(size); + } + if (value('pressure') !== undefined) { + setPressure(Number(value('pressure')) > 0); + } + setSettingsReady(true); + }, []); + useEffect(() => { + if (!settingsReady) { + return; + } + const settings = { + experiment, + trials: String(trialCount), + probes: String(probeCount), + pressure: String(pressure ? pressureMiB : 0), + size: String(pressureMiB), + }; + try { + localStorage.setItem('d1-demo-settings-v1', JSON.stringify(settings)); + } catch { + /* URL fallback. */ + } + const url = new URL(location.href); + url.searchParams.delete('reads'); + url.searchParams.delete('writes'); + for (const [key, value] of Object.entries(settings)) { + url.searchParams.set(key, value); + } + history.replaceState(history.state, '', url); + }, [settingsReady, experiment, trialCount, probeCount, pressure, pressureMiB]); + const controlsDisabled = running || !settingsReady; + const immediate = experiment === 'immediate'; + const fixed = initial.variant === 'with-bookmark'; + const latest = results.at(-1) ?? initial; + const fresh = results.filter((result) => result.outcome === 'fresh').length; + const stale = results.filter((result) => result.outcome === 'stale').length; + const errored = results.filter((result) => result.outcome === 'errored').length; + + async function runTrials(count: number) { + setRunSize(count); + setRunning(true); + setTrialsRunning(true); + setResults([]); + try { + for (let index = 0; index < count; index++) { + // Redirect mode follows the 303; immediate mode writes and reads in this POST. + const response = await fetch( + `/api/${initial.variant}?experiment=${experiment}${pressure ? `&pressure=${pressureMiB}` : ''}`, + { + method: 'POST', + credentials: 'same-origin', + cache: 'no-store', + }, + ); + if (!response.ok) { + const text = await response.text(); + let failure = errorObservation( + initial.variant, + pressure ? pressureMiB : 0, + { + phase: immediate ? 'request' : response.redirected ? 'read' : 'save', + status: response.status, + requestId: response.headers.get('cf-ray'), + causes: [{ name: 'HTTP error', message: text || response.statusText, stack: null }], + }, + null, + experiment, + ); + try { + const body: Observation = JSON.parse(text); + if (body.outcome === 'errored' && body.error) { + failure = body; + } + } catch { + // Infrastructure failures can return plain text or HTML instead of app JSON. + } + setResults((previous) => [...previous, failure]); + break; + } + const observation: Observation = await response.json(); + setResults((previous) => [...previous, observation]); + } + } catch (cause) { + const failure = errorObservation( + initial.variant, + pressure ? pressureMiB : 0, + { + phase: 'request', + status: null, + requestId: null, + causes: [ + { + name: cause instanceof Error ? cause.name : 'Error', + message: cause instanceof Error ? cause.message : String(cause), + stack: cause instanceof Error ? (cause.stack ?? null) : null, + }, + ], + }, + null, + experiment, + ); + setResults((previous) => [...previous, failure]); + } finally { + setRunning(false); + setTrialsRunning(false); + } + } + + return ( + <> +

{fixed ? 'Manual bookmark propagation' : 'Without bookmark propagation'}

+

+ Selected write/read experiment: {experimentLabel(experiment)}. Settings are + shared between variants and saved in this browser and URL. Explicit URL settings take + precedence. +

+ +
+

Write/read experiment

+

+ +

+

+ {immediate + ? fixed + ? 'Each trial writes, then reads once through a new session initialized with that write’s bookmark, passed directly in server code.' + : 'Each trial writes, then reads once through a new unconstrained session. The write’s bookmark is not passed to the read.' + : fixed + ? 'The POST returns its bookmark in a cookie. The redirected GET resumes from that bookmark.' + : 'The POST and redirected GET have independent, unconstrained sessions. No bookmark is sent back.'} +

+
+        {immediate
+          ? fixed
+            ? `// After the write completes on writer:
+const bookmark = getBookmark(writer);
+if (!bookmark) throw new Error('Missing write bookmark');
+const reader = createDb(c.env.DB, { session: bookmark });
+// Read once through reader, not writer.`
+            : `// After the write completes on writer:
+const reader = createDb(c.env.DB, { session: 'first-unconstrained' });
+// Read once through reader, not writer.`
+          : fixed
+            ? `setSession(getCookie(c, 'd1-demo-bookmark') ?? 'first-unconstrained');
+await next();
+const bookmark = getBookmark();
+if (bookmark) setCookie(c, 'd1-demo-bookmark', bookmark, options);`
+            : '// No setSession() call; no bookmark cookie is read or written.'}
+      
+ {immediate && ( +

+ Both variants use the same write and read query with separate sessions. There is no + browser round trip between them. Each trial finishes before the next starts. D1 still + chooses each read's destination. +

+ )} +

+ · +

+
+

+ {' '} + {' '} + — {pressure ? pressureMiB * trialCount : 0} MiB per {trialCount} trials. This does not + guarantee lag. Use a disposable database. +

+ {pressure && ( +

+ The revision and unrelated BLOB rows are saved in one transaction, followed by one read. + No database operations run in parallel. +

+ )} +
+ + +
+
+

+ {latest.outcome === 'errored' + ? 'Errored — trial did not complete' + : latest.outcome === 'idle' + ? 'Ready to run trials' + : latest.outcome === 'fresh' + ? 'Fresh read' + : 'Stale read — save acknowledged, but not visible'} +

+ {latest.error &&

{failureMessage(latest.error)}

} +
+
Read timing
+
{experimentLabel(latest.experiment)}
+
Expected revision (write receipt)
+
+ + {latest.expected ?? + (latest.error ? 'Save not acknowledged' : 'No save in this URL yet')} + +
+
Observed revision (database read)
+
+ + {latest.observed ?? (latest.error ? 'Read did not complete' : 'No row visible')} + +
+
Observed saved time
+
{latest.savedAt ?? '—'}
+
Replication pressure
+
{latest.pressureMiB ? `${pressureLabel(latest.pressureMiB)} per trial` : 'Off'}
+
Read served by
+
+ {latest.error + ? 'No completed read' + : latest.servedByPrimary === null + ? 'Unknown (local D1 does not report this)' + : latest.servedByPrimary + ? 'Primary' + : 'Replica'}{' '} + · {latest.servedByRegion ?? 'unknown region'} +
+
Worker placement / colo
+
{latest.workerColo ?? 'Unknown / local'}
+ {latest.experiment === 'immediate' && ( + <> +
Write bookmark
+
+ {latest.writeBookmark ?? 'None'} +
+ + )} +
+ {latest.experiment === 'immediate' ? 'Read session bookmark' : 'Incoming bookmark'} +
+
+ {latest.incomingBookmark ?? (fixed ? 'None yet' : 'Not carried (control)')} +
+
Outgoing bookmark
+
+ {latest.outgoingBookmark ?? 'None'} +
+ {latest.error && ( + <> +
Error
+
+ +
+ + )} +
+ +
+
+

Trial history

+

+ {fresh + stale} completed · {fresh} fresh ·{' '} + {stale} stale ·{' '} + {errored} errored +

+ +
+ + + + + + + + + + + + {results.map((result, index) => ( + + + + + + + + + {result.metadata && ( + + + + )} + {result.error && ( + + + + )} + + ))} + +
TrialResultRead targetExpectedObserved
{index + 1}{result.outcome} + {result.error + ? '—' + : result.servedByPrimary === null + ? 'unknown' + : result.servedByPrimary + ? 'primary' + : 'replica'}{' '} + / {result.servedByRegion ?? 'local'} + + {result.expected} + + {result.observed ?? (result.error ? '—' : 'missing')} +
+ +
+ +
+
+

+ Replica lag is not guaranteed. Both variants will usually look fresh locally. Run in one tab + without concurrent writes; the expected revision is a comparison value, not a bookmark. + Trials stay in this page’s memory and reset when you leave it. +

+ + ); +} + +function ReadCounts({ reads }: { reads: Array }) { + const completed = reads.filter((read) => read.outcome === 'fresh' || read.outcome === 'stale'); + return ( +

+ Reads: {completed.filter((read) => read.servedByPrimary === true).length} primary ·{' '} + {completed.filter((read) => read.servedByPrimary === false).length} replica ·{' '} + + { + completed.filter((read) => read.servedByPrimary === false && read.outcome === 'stale') + .length + }{' '} + stale replica + {' '} + · {completed.filter((read) => read.servedByPrimary === null).length} unknown target ·{' '} + + {reads.filter((read) => read.outcome === 'errored').length} read errors + +

+ ); +} + +function failureMessage(error: TrialError): string { + const status = error.status === null ? 'Request failed' : `HTTP ${error.status}`; + const outcome = + error.phase === 'probe' + ? 'The read-only probe failed; no write was attempted.' + : error.phase === 'save' + ? 'Save was not acknowledged; the write may have committed.' + : error.phase === 'read' + ? 'Save was acknowledged, but the follow-up read failed.' + : 'The request did not complete; the write outcome may be unknown.'; + return `${status}. ${outcome}`; +} + +function ErrorDetails({ error }: { error: TrialError }) { + return ( +
+ {error.causes[0]?.message || 'Error details'} +

{failureMessage(error)}

+

+ Phase: {error.phase} · Request ID: {error.requestId ?? 'Unavailable'} +

+ {error.causes.map((cause, index) => ( +
+

+ + {index === 0 ? 'Error' : `Cause ${index}`}: {cause.name} + +

+
{cause.message}
+
{cause.stack ?? 'No stack trace available.'}
+
+ ))} +
+ ); +} diff --git a/playground/d1-sessions-api/src/demo.ts b/playground/d1-sessions-api/src/demo.ts new file mode 100644 index 000000000..2b150785b --- /dev/null +++ b/playground/d1-sessions-api/src/demo.ts @@ -0,0 +1,110 @@ +export type Variant = 'without-bookmark' | 'with-bookmark'; +export type Experiment = 'redirect' | 'immediate'; + +export function experimentForQuery(value: string | undefined): Experiment { + return value === 'immediate' ? 'immediate' : 'redirect'; +} + +export function experimentLabel(experiment: Experiment): string { + return experiment === 'immediate' ? 'Immediate server read' : 'Browser redirect (cookie)'; +} + +export const PRESSURE_OPTIONS = [0.25, 0.5, 1, 2] as const; +export const DEFAULT_PRESSURE_MIB = 0.25; +export const RUN_COUNTS = [20, 50, 100, 200, 500] as const; + +export function pressureLabel(size: number): string { + return size < 1 ? `${size * 1024} KiB` : `${size} MiB`; +} + +export function pressureMiBForQuery(value: string | undefined): number { + const size = Number(value); + return PRESSURE_OPTIONS.some((option) => option === size) ? size : 0; +} + +export type Observation = { + experiment: Experiment; + pressureMiB: number; + variant: Variant; + expected: string | null; + observed: string | null; + savedAt: string | null; + outcome: 'idle' | 'fresh' | 'stale' | 'errored'; + incomingBookmark: string | null; + writeBookmark: string | null; + outgoingBookmark: string | null; + servedByPrimary: boolean | null; + servedByRegion: string | null; + workerColo: string | null; + metadata?: Record; + elapsedMs?: number; + error?: TrialError; +}; + +export type TrialError = { + phase: 'save' | 'read' | 'request' | 'probe'; + status: number | null; + requestId: string | null; + causes: Array<{ name: string; message: string; stack: string | null }>; +}; + +export type RoutingProbe = { + path: 'void-run'; + workerColo: string | null; + elapsedMs: number; + metadata: Record | null; + rows: Array; + bookmark: string | null; + error?: TrialError; +}; + +export function serializeError(cause: unknown): TrialError['causes'] { + const errors: TrialError['causes'] = []; + for (let depth = 0; cause !== undefined && depth < 5; depth++) { + errors.push( + cause instanceof Error + ? { name: cause.name, message: cause.message, stack: cause.stack ?? null } + : { name: 'Cause', message: String(cause), stack: null }, + ); + cause = cause instanceof Error ? cause.cause : undefined; + } + return errors; +} + +export function errorObservation( + variant: Variant, + pressureMiB: number, + error: TrialError, + expected: string | null = null, + experiment: Experiment = 'redirect', +): Observation { + return { + experiment, + variant, + pressureMiB, + outcome: 'errored', + expected, + observed: null, + savedAt: null, + incomingBookmark: null, + writeBookmark: null, + outgoingBookmark: null, + servedByPrimary: null, + servedByRegion: null, + workerColo: null, + error, + }; +} + +export const BOOKMARK_COOKIE = 'd1-demo-bookmark'; +export const VISITOR_COOKIE = 'd1-demo-visitor'; + +export function variantForPath(path: string): Variant | null { + if (path === '/with-bookmark' || path === '/api/with-bookmark') { + return 'with-bookmark'; + } + if (path === '/without-bookmark' || path === '/api/without-bookmark') { + return 'without-bookmark'; + } + return null; +} diff --git a/playground/d1-sessions-api/src/metadata.tsx b/playground/d1-sessions-api/src/metadata.tsx new file mode 100644 index 000000000..90c2a0d6b --- /dev/null +++ b/playground/d1-sessions-api/src/metadata.tsx @@ -0,0 +1,20 @@ +export function MetadataDetails({ + metadata, + elapsedMs, +}: { + metadata?: Record; + elapsedMs?: number; +}) { + if (!metadata) { + return null; + } + return ( +
+ + D1 metadata · attempts: {String(metadata.total_attempts ?? 'not reported')} ·{' '} + {elapsedMs?.toFixed(1) ?? '—'} ms wall time + +
{JSON.stringify(metadata, null, 2)}
+
+ ); +} diff --git a/playground/d1-sessions-api/src/routing-probe.tsx b/playground/d1-sessions-api/src/routing-probe.tsx new file mode 100644 index 000000000..79ed9c385 --- /dev/null +++ b/playground/d1-sessions-api/src/routing-probe.tsx @@ -0,0 +1,172 @@ +import { useState } from 'react'; +import { RUN_COUNTS, serializeError, type RoutingProbe } from './demo.ts'; +import { MetadataDetails } from './metadata.tsx'; +import { SourceLink } from './source-link.tsx'; + +export function RoutingProbePanel({ + running, + setRunning, + count, + setCount, +}: { + running: boolean; + setRunning: (value: boolean) => void; + count: number; + setCount: (value: number) => void; +}) { + const [results, setResults] = useState>([]); + const [progress, setProgress] = useState(0); + const [error, setError] = useState(null); + + async function run(rounds: number) { + setRunning(true); + setResults([]); + setProgress(0); + setError(null); + try { + for (let round = 0; round < rounds; round++) { + const response = await fetch('/api/routing', { + cache: 'no-store', + credentials: 'same-origin', + }); + const text = await response.text(); + let body: RoutingProbe; + try { + body = JSON.parse(text); + } catch { + throw new Error( + `HTTP ${response.status}; request ID: ${response.headers.get('cf-ray') ?? 'unavailable'}\n${text}`, + ); + } + if (body.path !== 'void-run') { + throw new Error(`HTTP ${response.status}\n${text}`); + } + setResults((previous) => [...previous, body]); + setProgress(round + 1); + if (!response.ok || body.error) { + break; + } + } + } catch (cause) { + setError(JSON.stringify(serializeError(cause), null, 2)); + } finally { + setRunning(false); + } + } + + return ( +
+

Read-only routing baseline

+

+ No saves, no pressure, no bookmark propagation. Each probe issues one SELECT through a fresh{' '} + first-unconstrained session using void/db .run(). Probes are + sequential. An empty result still measures routing, not staleness. +

+
{'SELECT revision, saved_at FROM bookmark_profiles ORDER BY id LIMIT 1'}
+

+ +

+

+ {' '} + {' '} + {' '} + {progress} probes completed +

+ {error && ( +
+ Probe request failed +
{error}
+
+ )} +

+ void-run:{' '} + { + results.filter((result) => !result.error && result.metadata?.served_by_primary === true) + .length + }{' '} + primary ·{' '} + { + results.filter((result) => !result.error && result.metadata?.served_by_primary === false) + .length + }{' '} + replica ·{' '} + { + results.filter( + (result) => !result.error && typeof result.metadata?.served_by_primary !== 'boolean', + ).length + }{' '} + unknown · {results.filter((result) => result.error).length} errors +

+
+ + + + + + + + + + + + + + {results.map((result, index) => ( + + + + + + + + + + ))} + +
ProbeWorkerD1 target / region / coloAttemptsRows returnedWall timeDetails
{index + 1}{result.workerColo ?? 'unknown'} + {result.error + ? 'failed' + : result.metadata?.served_by_primary === true + ? 'primary' + : result.metadata?.served_by_primary === false + ? 'replica' + : 'unknown'}{' '} + / {String(result.metadata?.served_by_region ?? 'unknown')} /{' '} + {String(result.metadata?.served_by_colo ?? 'unknown')} + {String(result.metadata?.total_attempts ?? 'not reported')}{result.error ? '—' : result.rows.length}{result.elapsedMs.toFixed(1)} ms + +
+ Rows / bookmark / error +
+                      {JSON.stringify(
+                        { rows: result.rows, bookmark: result.bookmark, error: result.error },
+                        null,
+                        2,
+                      )}
+                    
+
+
+
+
+ ); +} diff --git a/playground/d1-sessions-api/src/source-link.tsx b/playground/d1-sessions-api/src/source-link.tsx new file mode 100644 index 000000000..d98dc6603 --- /dev/null +++ b/playground/d1-sessions-api/src/source-link.tsx @@ -0,0 +1,14 @@ +declare const __D1_SESSIONS_API_SOURCE_ROOT__: string; + +export function SourceLink({ file }: { file: string }) { + const source = new URL( + file.split('/').map(encodeURIComponent).join('/'), + __D1_SESSIONS_API_SOURCE_ROOT__, + ); + const host = source.host ? `//${source.host}` : ''; + return ( + + {file} + + ); +} diff --git a/playground/d1-sessions-api/src/vite-env.d.ts b/playground/d1-sessions-api/src/vite-env.d.ts new file mode 100644 index 000000000..11f02fe2a --- /dev/null +++ b/playground/d1-sessions-api/src/vite-env.d.ts @@ -0,0 +1 @@ +/// diff --git a/playground/d1-sessions-api/tsconfig.json b/playground/d1-sessions-api/tsconfig.json new file mode 100644 index 000000000..1f640d2a3 --- /dev/null +++ b/playground/d1-sessions-api/tsconfig.json @@ -0,0 +1,16 @@ +{ + "extends": "./.void/tsconfig.json", + "compilerOptions": { + "target": "ES2022", + "module": "NodeNext", + "moduleResolution": "NodeNext", + "strict": true, + "noUnusedLocals": true, + "esModuleInterop": true, + "skipLibCheck": true, + "jsx": "react-jsx", + "types": ["void/env"], + "allowImportingTsExtensions": true + }, + "include": ["pages", "routes", "middleware", "src", "db", "*.config.ts"] +} diff --git a/playground/d1-sessions-api/vite.config.ts b/playground/d1-sessions-api/vite.config.ts new file mode 100644 index 000000000..f0477a68a --- /dev/null +++ b/playground/d1-sessions-api/vite.config.ts @@ -0,0 +1,10 @@ +import { voidReact } from '@void/react/plugin'; +import { defineConfig } from 'vite-plus'; +import { voidPlugin } from 'void'; + +export default defineConfig({ + define: { + __D1_SESSIONS_API_SOURCE_ROOT__: JSON.stringify(new URL('./', import.meta.url).href), + }, + plugins: [voidPlugin(), voidReact()], +}); diff --git a/playground/d1-sessions-api/void.config.ts b/playground/d1-sessions-api/void.config.ts new file mode 100644 index 000000000..14f6e82bf --- /dev/null +++ b/playground/d1-sessions-api/void.config.ts @@ -0,0 +1,31 @@ +import { defineConfig } from 'void/config'; +import cloudflare from './cloudflare.config.example.ts'; + +export default defineConfig({ + routing: { isr: false }, + cloudflare: { + account_id: cloudflare.accountId, + name: cloudflare.worker.name, + compatibility_date: cloudflare.worker.compatibilityDate, + compatibility_flags: cloudflare.worker.compatibilityFlags, + workers_dev: cloudflare.worker.workersDev, + placement: cloudflare.worker.placement, + observability: { + enabled: cloudflare.worker.observability.enabled, + head_sampling_rate: cloudflare.worker.observability.headSamplingRate, + logs: { + enabled: cloudflare.worker.observability.logs.enabled, + invocation_logs: cloudflare.worker.observability.logs.invocationLogs, + persist: cloudflare.worker.observability.logs.persist, + }, + }, + d1_databases: [ + { + binding: 'DB', + database_name: cloudflare.worker.env.DB.name, + database_id: cloudflare.worker.env.DB.id, + migrations_dir: 'db/migrations', + }, + ], + }, +}); diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 8719f66cd..3f711aed0 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1393,6 +1393,43 @@ importers: specifier: workspace:* version: link:../../packages/void + playground/d1-sessions-api: + dependencies: + hono: + specifier: 'catalog:' + version: 4.13.19 + react: + specifier: 'catalog:' + version: 19.3.1 + react-dom: + specifier: 'catalog:' + version: 19.3.1(react@19.3.1) + devDependencies: + '@types/react': + specifier: ^19.3.0 + version: 19.3.0 + '@types/react-dom': + specifier: ^19.3.0 + version: 19.3.0(@types/react@19.3.0) + '@void/react': + specifier: workspace:* + version: link:../../packages/react + cf: + specifier: 'catalog:' + version: 1.0.0-rc.0(@types/node@26.6.6) + typescript: + specifier: 'catalog:' + version: 7.0.2 + vite: + specifier: 'catalog:' + version: '@voidzero-dev/vite-plus-core@8.3.8000(@types/node@26.6.6)(esbuild@0.28.2)(jiti@2.7.0)(sass-embedded@1.104.1)(sass@1.104.1)(terser@5.51.2)(tsx@4.23.15)(typescript@7.0.2)(yaml@2.9.1)' + vite-plus: + specifier: 'catalog:' + version: 1.7.0(@astrojs/compiler-rs@0.5.3)(@types/node@26.6.6)(@vitest/browser-preview@5.1.0)(@vitest/ui@5.1.0)(@voidzero-dev/vite-plus-core@8.3.8000(@types/node@26.6.6)(esbuild@0.28.2)(jiti@2.7.0)(sass-embedded@1.104.1)(sass@1.104.1)(terser@5.51.2)(tsx@4.23.15)(typescript@7.0.2)(yaml@2.9.1))(esbuild@0.28.2)(happy-dom@21.0.4)(jiti@2.7.0)(playwright@1.65.1)(sass-embedded@1.104.1)(sass@1.104.1)(svelte@5.57.3)(terser@5.51.2)(tsx@4.23.15)(typescript@7.0.2)(vitest@5.1.0)(yaml@2.9.1) + void: + specifier: workspace:* + version: link:../../packages/void + playground/http-errors: dependencies: '@hono/node-server':