Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

Seanaye/feat/turso backed cache (#5686)

Sean Ayea581dfb26a7a
diff --git a/.github/workflows/deploy_on_push.yml b/.github/workflows/deploy_on_push.yml
index ea7bd50d12..543172ff84 100644
--- a/.github/workflows/deploy_on_push.yml
+++ b/.github/workflows/deploy_on_push.yml
@@ -23,7 +23,7 @@ jobs:
diff: |-
cloud-storage: ./Cargo.toml ./Cargo.lock ./Cross.toml ./clippy.toml ./deny.toml ./rust-toolchain.toml ./.cargo/** ./.config/** ./.sqlx/** ./crates/** ./services/** ./tooling/xtask/** ./tooling/just/** ./tooling/scripts/** ./static_assets/** ./docker/** ./nix/** ./nix-support/** ./infra/** ./.github/workflows/deploy_on_push.yml ./.github/workflows/deploy_all_services.yml ./.github/actions/deploy-cloud-storage-pulumi/** ./.github/actions/setup-nix/** ./.github/actions/teardown-nix/** ./.github/actions/migrate-cloud-storage-db/** ./.github/scripts/build-cloud-storage-lambdas-nix.sh ./.github/services-config.json ./.github/workspace-dep-closures.json ./flake.nix ./flake.lock
sync-service: ./services/sync-service/** ./crates/macro_sync_service_jwt/** ./Cargo.toml ./Cargo.lock ./rust-toolchain.toml ./.github/workflows/deploy_on_push.yml ./.github/workflows/deploy_sync_service.yml
- web-app: ./infra/stacks/web-app/** ./.github/workflows/deploy_on_push.yml ./.github/workflows/deploy_web_app.yml ./package.json ./bun.lock ./apps/web/** ./packages/** ./crates/client/cache-core/** ./crates/client/cache-idb/** ./crates/client/cache-wasm/** ./static_assets/schema.graphql ./Cargo.toml ./Cargo.lock ./rust-toolchain.toml
+ web-app: ./infra/stacks/web-app/** ./.github/workflows/deploy_on_push.yml ./.github/workflows/deploy_web_app.yml ./package.json ./bun.lock ./apps/web/** ./packages/** ./crates/client/cache-core/** ./crates/client/cache-turso/** ./crates/client/cache-wasm/** ./crates/client/turso-opfs/** ./static_assets/schema.graphql ./Cargo.toml ./Cargo.lock ./rust-toolchain.toml
deploy-cloud-storage:
needs:
- check-to-deploy
diff --git a/.github/workflows/deploy_preview.yml b/.github/workflows/deploy_preview.yml
index bb4975a2a6..9cb651a2d2 100644
--- a/.github/workflows/deploy_preview.yml
+++ b/.github/workflows/deploy_preview.yml
@@ -14,8 +14,9 @@ env:
- apps/web/**
- packages/**
- crates/client/cache-core/**
- - crates/client/cache-idb/**
+ - crates/client/cache-turso/**
- crates/client/cache-wasm/**
+ - crates/client/turso-opfs/**
- static_assets/schema.graphql
- Cargo.toml
- Cargo.lock
diff --git a/.github/workflows/web-app-check-main.yml b/.github/workflows/web-app-check-main.yml
index 71c4475d10..83122ff172 100644
--- a/.github/workflows/web-app-check-main.yml
+++ b/.github/workflows/web-app-check-main.yml
@@ -30,8 +30,9 @@ jobs:
- 'apps/web/**'
- 'packages/**'
- 'crates/client/cache-core/**'
- - 'crates/client/cache-idb/**'
+ - 'crates/client/cache-turso/**'
- 'crates/client/cache-wasm/**'
+ - 'crates/client/turso-opfs/**'
- 'static_assets/schema.graphql'
- 'Cargo.toml'
- 'Cargo.lock'
diff --git a/.github/workspace-dep-closures.json b/.github/workspace-dep-closures.json
index 3381836510..6ba1324ea3 100644
--- a/.github/workspace-dep-closures.json
+++ b/.github/workspace-dep-closures.json
@@ -593,20 +593,22 @@
"crates/client/cache-core",
"crates/maybe_send"
],
- "cache-idb": [
+ "cache-sqlite": [
"crates/client/cache-core",
- "crates/client/cache-idb",
+ "crates/client/cache-sqlite",
"crates/maybe_send"
],
- "cache-sqlite": [
+ "cache-turso": [
"crates/client/cache-core",
- "crates/client/cache-sqlite",
+ "crates/client/cache-turso",
+ "crates/client/turso-opfs",
"crates/maybe_send"
],
"cache-wasm": [
"crates/client/cache-core",
- "crates/client/cache-idb",
+ "crates/client/cache-turso",
"crates/client/cache-wasm",
+ "crates/client/turso-opfs",
"crates/maybe_send"
],
"cal": [
@@ -6329,6 +6331,9 @@
"crates/unfurl",
"crates/workspace-hack"
],
+ "turso-opfs": [
+ "crates/client/turso-opfs"
+ ],
"unfurl": [
"crates/unfurl",
"crates/workspace-hack"
diff --git a/Cargo.lock b/Cargo.lock
index 371a5d6554..7ec14480c9 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -48,6 +48,16 @@ dependencies = [
"generic-array",
]
+[[package]]
+name = "aegis"
+version = "0.9.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "78412fa53e6da95324e8902c3641b3ff32ab45258582ea997eb9169c68ffa219"
+dependencies = [
+ "cc",
+ "softaes",
+]
+
[[package]]
name = "aes"
version = "0.8.4"
@@ -410,6 +420,12 @@ version = "0.2.21"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "683d7910e743518b0e34f1186f92494becacb047c7b6bf616c96772180fef923"
+[[package]]
+name = "allocator-api2"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c880a97d28a3681c0267bd29cff89621202715b065127cd445fa0f0fe0aa2880"
+
[[package]]
name = "ammonia"
version = "4.1.4"
@@ -522,6 +538,22 @@ dependencies = [
"workspace-hack",
]
+[[package]]
+name = "antithesis_sdk"
+version = "0.2.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08410fcac93669a476c006cd6c4512ac1e2b30fd117231a5d55d8a2c76599b82"
+dependencies = [
+ "libc",
+ "libloading",
+ "linkme",
+ "once_cell",
+ "rand 0.8.6",
+ "rustc_version_runtime",
+ "serde",
+ "serde_json",
+]
+
[[package]]
name = "anyhow"
version = "1.0.103"
@@ -587,6 +619,15 @@ dependencies = [
"derive_arbitrary",
]
+[[package]]
+name = "arc-swap"
+version = "1.9.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c049c0be4daef0b145cb3555416b3b8ef5b7888a38aea1a3a155801fe7b0810b"
+dependencies = [
+ "rustversion",
+]
+
[[package]]
name = "arcstr"
version = "1.2.0"
@@ -615,6 +656,26 @@ dependencies = [
"yansi",
]
+[[package]]
+name = "aristo"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fcdeefa800110050103e2459a2f8dbdbd560ad046e30f1f87e24ce19c2cb8bde"
+dependencies = [
+ "aristo-macros",
+]
+
+[[package]]
+name = "aristo-macros"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d64a66d21a80182b35b1741997a6d2456911f54b7eb1918aa4e2382fc205268d"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
[[package]]
name = "arrayvec"
version = "0.5.2"
@@ -706,6 +767,12 @@ dependencies = [
"serde_json",
]
+[[package]]
+name = "assoc"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bfdc70193dadb9d7287fa4b633f15f90c876915b31f6af17da307fc59c9859a8"
+
[[package]]
name = "async-channel"
version = "1.9.0"
@@ -2127,6 +2194,19 @@ dependencies = [
"bitflags 1.3.2",
]
+[[package]]
+name = "bigdecimal"
+version = "0.4.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4d6867f1565b3aad85681f1015055b087fcfd840d6aeee6eee7f2da317603695"
+dependencies = [
+ "autocfg",
+ "libm",
+ "num-bigint",
+ "num-integer",
+ "num-traits",
+]
+
[[package]]
name = "bindgen"
version = "0.71.1"
@@ -2201,6 +2281,18 @@ dependencies = [
"no_std_io2",
]
+[[package]]
+name = "bitvec"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ddcec3d12c579d40898fe0a9a358a803c23e9c52ca3c425707f81c9436211837"
+dependencies = [
+ "funty",
+ "radium",
+ "tap",
+ "wyz",
+]
+
[[package]]
name = "block-buffer"
version = "0.10.4"
@@ -2340,6 +2432,15 @@ dependencies = [
"workspace-hack",
]
+[[package]]
+name = "branches"
+version = "0.4.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8fba76cd916045514e3064707df9ed5282b94419444c2753a6c62ecaf458e56"
+dependencies = [
+ "rustc_version",
+]
+
[[package]]
name = "broadcast"
version = "0.1.0"
@@ -2388,6 +2489,20 @@ name = "bytemuck"
version = "1.25.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c8efb64bd706a16a1bdde310ae86b351e4d21550d98d056f22f8a7f7a2183fec"
+dependencies = [
+ "bytemuck_derive",
+]
+
+[[package]]
+name = "bytemuck_derive"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc0e56a716f1e132ff6bf4bdac1c944a3fcdc1cae65f70a4a2a1ac3b401d2d1f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
[[package]]
name = "byteorder"
@@ -2457,42 +2572,44 @@ dependencies = [
]
[[package]]
-name = "cache-idb"
+name = "cache-sqlite"
version = "0.1.0"
dependencies = [
"cache-core",
- "idb",
- "js-sys",
+ "pollster",
+ "rusqlite",
"serde_json",
+ "tempfile",
"thiserror 2.0.18",
- "wasm-bindgen",
- "wasm-bindgen-test",
- "web-sys",
]
[[package]]
-name = "cache-sqlite"
+name = "cache-turso"
version = "0.1.0"
dependencies = [
"cache-core",
+ "cache-sqlite",
+ "maybe_send",
"pollster",
- "rusqlite",
"serde_json",
- "tempfile",
"thiserror 2.0.18",
+ "turso-opfs",
+ "turso_core",
+ "wasm-bindgen-test",
]
[[package]]
name = "cache-wasm"
-version = "0.3.2"
+version = "0.4.0"
dependencies = [
"async-lock",
"cache-core",
- "cache-idb",
+ "cache-turso",
"js-sys",
"serde",
"serde-wasm-bindgen",
"serde_json",
+ "turso-opfs",
"wasm-bindgen",
"wasm-bindgen-futures",
"wasm-bindgen-test",
@@ -2755,6 +2872,12 @@ version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "613afe47fcd5fac7ccf1db93babcb082c5994d996f20b8b159f2ad1658eb5724"
+[[package]]
+name = "cfg_block"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "18758054972164c3264f7c8386f5fc6da6114cb46b619fd365d4e3b2dc3ae487"
+
[[package]]
name = "chacha20"
version = "0.10.0"
@@ -3593,6 +3716,15 @@ version = "0.4.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "338089f42c427b86394a5ee60ff321da23a5c89c9d89514c829687b26359fcff"
+[[package]]
+name = "crc32c"
+version = "0.6.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a47af21622d091a8f0fb295b88bc886ac74efcc613efc19f5d0b21de5c89e47"
+dependencies = [
+ "rustc_version",
+]
+
[[package]]
name = "crc32fast"
version = "1.5.0"
@@ -5640,6 +5772,17 @@ dependencies = [
"ascii_utils",
]
+[[package]]
+name = "fastbloom"
+version = "0.14.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4e7f34442dbe69c60fe8eaf58a8cafff81a1f278816d8ab4db255b3bef4ac3c4"
+dependencies = [
+ "getrandom 0.3.4",
+ "libm",
+ "siphasher 1.0.3",
+]
+
[[package]]
name = "fastrand"
version = "1.9.0"
@@ -5863,6 +6006,12 @@ version = "1.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "42703706b716c37f96a77aea830392ad231f44c9e9a67872fa5548707e11b11c"
+[[package]]
+name = "funty"
+version = "2.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6d5a32815ae3f33302d95fdcb2ce17862f8c65363dcfd29360480ba1001fc9c"
+
[[package]]
name = "fusionauth"
version = "0.1.0"
@@ -6171,11 +6320,13 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0de51e6874e94e7bf76d726fc5d13ba782deca734ff60d5bb2fb2607c7406555"
dependencies = [
"cfg-if",
+ "js-sys",
"libc",
"r-efi 6.0.0",
"rand_core 0.10.1",
"wasip2",
"wasip3",
+ "wasm-bindgen",
]
[[package]]
@@ -6700,7 +6851,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e5274423e17b7c9fc20b6e7e208532f9b19825d82dfd615708b70edd83df41f1"
dependencies = [
"ahash",
- "allocator-api2",
+ "allocator-api2 0.2.21",
]
[[package]]
@@ -6709,7 +6860,7 @@ version = "0.15.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
dependencies = [
- "allocator-api2",
+ "allocator-api2 0.2.21",
"equivalent",
"foldhash 0.1.5",
]
@@ -6720,7 +6871,7 @@ version = "0.16.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "841d1cc9bed7f9236f321df977030373f4a4163ae1a7dbfe1a51a2c1a51d9100"
dependencies = [
- "allocator-api2",
+ "allocator-api2 0.2.21",
"equivalent",
"foldhash 0.2.0",
]
@@ -6731,7 +6882,7 @@ version = "0.17.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
dependencies = [
- "allocator-api2",
+ "allocator-api2 0.2.21",
"equivalent",
"foldhash 0.2.0",
]
@@ -7281,6 +7432,31 @@ dependencies = [
"cc",
]
+[[package]]
+name = "icu_collator"
+version = "2.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8bbdf98e5e0aa827770acee171ebb568aaab975a36b56afdb5fd0e2f525750bb"
+dependencies = [
+ "icu_collator_data",
+ "icu_collections",
+ "icu_locale",
+ "icu_locale_core",
+ "icu_normalizer",
+ "icu_properties",
+ "icu_provider",
+ "smallvec",
+ "utf16_iter",
+ "utf8_iter",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_collator_data"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "038ed8e5817f2059c2f3efb0945ba78d060d3d25e8f1a1bea5139f821a21a2f0"
+
[[package]]
name = "icu_collections"
version = "2.2.0"
@@ -7295,6 +7471,21 @@ dependencies = [
"zerovec",
]
+[[package]]
+name = "icu_locale"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d5a396343c7208121dc86e35623d3dfe19814a7613cfd14964994cdc9c9a2e26"
+dependencies = [
+ "icu_collections",
+ "icu_locale_core",
+ "icu_locale_data",
+ "icu_provider",
+ "potential_utf",
+ "tinystr",
+ "zerovec",
+]
+
[[package]]
name = "icu_locale_core"
version = "2.2.0"
@@ -7303,11 +7494,18 @@ checksum = "92219b62b3e2b4d88ac5119f8904c10f8f61bf7e95b640d25ba3075e6cac2c29"
dependencies = [
"displaydoc",
"litemap",
+ "serde",
"tinystr",
"writeable",
"zerovec",
]
+[[package]]
+name = "icu_locale_data"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d5fdcc9ac77c6d74ff5cf6e65ef3181d6af32003b16fce3a77fb451d2f695993"
+
[[package]]
name = "icu_normalizer"
version = "2.2.0"
@@ -7319,6 +7517,9 @@ dependencies = [
"icu_properties",
"icu_provider",
"smallvec",
+ "utf16_iter",
+ "utf8_iter",
+ "write16",
"zerovec",
]
@@ -7356,6 +7557,8 @@ checksum = "139c4cf31c8b5f33d7e199446eff9c1e02decfc2f0eec2c8d71f65befa45b421"
dependencies = [
"displaydoc",
"icu_locale_core",
+ "serde",
+ "stable_deref_trait",
"writeable",
"yoke",
"zerofrom",
@@ -7369,28 +7572,13 @@ version = "2.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3d3067d79b975e8844ca9eb072e16b31c3c1c36928edf9c6789548c524d0d954"
-[[package]]
-name = "idb"
-version = "0.6.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6554f394e990a1af530a528a7fdcad6e01b29cb1b990f89df3ffd62cf15f7828"
-dependencies = [
- "indexmap 2.14.0",
- "js-sys",
- "num-traits",
- "thiserror 2.0.18",
- "tokio",
- "wasm-bindgen",
- "web-sys",
-]
-
[[package]]
name = "iddqd"
version = "0.3.18"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "616230c7d641ef971a3a5bfcc654c6b7524ab9c9fb665693c6a397dba9a14aca"
dependencies = [
- "allocator-api2",
+ "allocator-api2 0.2.21",
"equivalent",
"foldhash 0.2.0",
"hashbrown 0.16.1",
@@ -7708,6 +7896,15 @@ dependencies = [
"syn 2.0.117",
]
+[[package]]
+name = "intrusive-collections"
+version = "0.9.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "189d0897e4cbe8c75efedf3502c18c887b05046e59d28404d4d8e46cbc4d1e86"
+dependencies = [
+ "memoffset",
+]
+
[[package]]
name = "invite_email"
version = "0.1.0"
@@ -8265,6 +8462,26 @@ dependencies = [
"vcpkg",
]
+[[package]]
+name = "linkme"
+version = "0.3.37"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3045e122bd98aef8ec3ad58ce84f0791f64e70163d1a02710af4aa11a4d54cc5"
+dependencies = [
+ "linkme-impl",
+]
+
+[[package]]
+name = "linkme-impl"
+version = "0.3.37"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "77060ebe535362c3da75682cd17b0431017b6e7c5661e714fc69a7ad017d1301"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
[[package]]
name = "linux-raw-sys"
version = "0.4.15"
@@ -9279,6 +9496,15 @@ version = "2.8.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
+[[package]]
+name = "memoffset"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
+dependencies = [
+ "autocfg",
+]
+
[[package]]
name = "memory"
version = "0.1.0"
@@ -9366,6 +9592,28 @@ dependencies = [
"syn 2.0.117",
]
+[[package]]
+name = "miette"
+version = "7.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5f98efec8807c63c752b5bd61f862c165c115b0a35685bdcfd9238c7aeb592b7"
+dependencies = [
+ "cfg-if",
+ "miette-derive",
+ "unicode-width 0.1.14",
+]
+
+[[package]]
+name = "miette-derive"
+version = "7.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "db5b29714e950dbb20d5e6f74f9dcec4edbcc1067bb7f8ed198c097b8c1a818b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
[[package]]
name = "mime"
version = "0.3.17"
@@ -10845,6 +11093,15 @@ dependencies = [
"sha2 0.10.9",
]
+[[package]]
+name = "pack1"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3b7bb0ecf2e447b1f20ee94ee79ef6eed1e9d4b3c36ce1903b9dea3bf205523"
+dependencies = [
+ "bytemuck",
+]
+
[[package]]
name = "parking"
version = "2.2.1"
@@ -11429,6 +11686,8 @@ version = "0.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0103b1cef7ec0cf76490e969665504990193874ea05c85ff9bab8b911d0a0564"
dependencies = [
+ "serde_core",
+ "writeable",
"zerovec",
]
@@ -11923,6 +12182,12 @@ version = "6.0.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
+[[package]]
+name = "radium"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc33ff2d4973d518d823d61aa239014831e521c75da58e3df4840d3f47749d09"
+
[[package]]
name = "rand"
version = "0.7.3"
@@ -12040,6 +12305,15 @@ dependencies = [
"rand_core 0.5.1",
]
+[[package]]
+name = "rand_pcg"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "59cad018caf63deb318e5a4586d99a24424a364f40f1e5778c29aca23f4fc73e"
+dependencies = [
+ "rand_core 0.6.4",
+]
+
[[package]]
name = "rand_xorshift"
version = "0.4.0"
@@ -12058,6 +12332,15 @@ dependencies = [
"rand_core 0.6.4",
]
+[[package]]
+name = "rapidhash"
+version = "4.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5da7e78a036ce858e8d55b7e7dc8ba3a88b78350fd2155d3591bbd966b58589e"
+dependencies = [
+ "rustversion",
+]
+
[[package]]
name = "rate_limit"
version = "0.1.0"
@@ -12628,6 +12911,16 @@ dependencies = [
"syn 2.0.117",
]
+[[package]]
+name = "roaring"
+version = "0.11.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1dedc5658c6ecb3bdb5ef5f3295bb9253f42dcf3fd1402c03f6b1f7659c3c4a9"
+dependencies = [
+ "bytemuck",
+ "byteorder",
+]
+
[[package]]
name = "roles_and_permissions"
version = "0.1.0"
@@ -12787,6 +13080,16 @@ dependencies = [
"semver",
]
+[[package]]
+name = "rustc_version_runtime"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2dd18cd2bae1820af0b6ad5e54f4a51d0f3fcc53b05f845675074efcc7af071d"
+dependencies = [
+ "rustc_version",
+ "semver",
+]
+
[[package]]
name = "rustix"
version = "0.38.44"
@@ -13858,6 +14161,26 @@ version = "1.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
+[[package]]
+name = "shuttle"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2ab17edba38d63047f46780cf7360acf7467fec2c048928689a5c1dd1c2b4e31"
+dependencies = [
+ "assoc",
+ "bitvec",
+ "cfg-if",
+ "generator",
+ "hex",
+ "owo-colors",
+ "rand 0.8.6",
+ "rand_core 0.6.4",
+ "rand_pcg",
+ "scoped-tls",
+ "smallvec",
+ "tracing",
+]
+
[[package]]
name = "signal-hook"
version = "0.3.18"
@@ -13942,6 +14265,15 @@ dependencies = [
"time",
]
+[[package]]
+name = "simsimd"
+version = "6.5.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f4fb3bc3cdce07a7d7d4caa4c54f8aa967f6be41690482b54b24100a2253fa70"
+dependencies = [
+ "cc",
+]
+
[[package]]
name = "siphasher"
version = "0.3.11"
@@ -14070,6 +14402,12 @@ dependencies = [
"windows-sys 0.61.2",
]
+[[package]]
+name = "softaes"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "45e14297decde697ddf377c25752aead0927d5cfc89c2684d2af96901a4ceeea"
+
[[package]]
name = "soup"
version = "0.1.0"
@@ -14616,6 +14954,15 @@ version = "0.11.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
+[[package]]
+name = "strum"
+version = "0.26.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fec0f0aef304996cf250b31b5a10dee7980c85da9d759361292b8bca5a18f06"
+dependencies = [
+ "strum_macros 0.26.4",
+]
+
[[package]]
name = "strum"
version = "0.27.2"
@@ -14634,6 +14981,19 @@ dependencies = [
"strum_macros 0.28.0",
]
+[[package]]
+name = "strum_macros"
+version = "0.26.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4c6bee85a5a24955dc440386795aa378cd9cf82acd5f764469152d2270e581be"
+dependencies = [
+ "heck 0.5.0",
+ "proc-macro2",
+ "quote",
+ "rustversion",
+ "syn 2.0.117",
+]
+
[[package]]
name = "strum_macros"
version = "0.27.2"
@@ -14836,6 +15196,12 @@ version = "0.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7b2093cf4c8eb1e67749a6762251bc9cd836b6fc171623bd0a9d324d37af2417"
+[[package]]
+name = "tap"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "55937e1799185b12863d447f42597ed69d9928686b8d88a1df17376a097d8369"
+
[[package]]
name = "target-lexicon"
version = "0.13.5"
@@ -15099,6 +15465,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c8323304221c2a851516f22236c5722a72eaa19749016521d6dff0824447d96d"
dependencies = [
"displaydoc",
+ "serde_core",
"zerovec",
]
@@ -15631,6 +15998,123 @@ dependencies = [
"url",
]
+[[package]]
+name = "turso-opfs"
+version = "0.1.0"
+dependencies = [
+ "js-sys",
+ "turso_core",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "wasm-bindgen-test",
+ "web-sys",
+]
+
+[[package]]
+name = "turso_core"
+version = "0.8.0-pre.3"
+source = "git+https://github.com/seanaye/turso?rev=be9acfe9e5e6efb17911af84047e4855cace53a3#be9acfe9e5e6efb17911af84047e4855cace53a3"
+dependencies = [
+ "aegis",
+ "aes",
+ "aes-gcm",
+ "allocator-api2 0.4.0",
+ "antithesis_sdk",
+ "arc-swap",
+ "aristo",
+ "bigdecimal",
+ "bitflags 2.11.1",
+ "branches",
+ "bumpalo",
+ "bytemuck",
+ "cfg_aliases",
+ "cfg_block",
+ "chrono",
+ "crc32c",
+ "crossbeam-epoch",
+ "crossbeam-utils",
+ "either",
+ "fallible-iterator 0.3.0",
+ "fastbloom",
+ "getrandom 0.2.17",
+ "getrandom 0.3.4",
+ "hex",
+ "icu_collator",
+ "icu_locale",
+ "intrusive-collections",
+ "libc",
+ "libloading",
+ "libm",
+ "loom",
+ "miette",
+ "num-bigint",
+ "num-traits",
+ "pack1",
+ "parking_lot",
+ "pastey 0.2.3",
+ "polling",
+ "rand 0.9.4",
+ "rapidhash",
+ "regex",
+ "regex-syntax",
+ "roaring",
+ "rustc-hash 2.1.2",
+ "rustix 1.1.4",
+ "ryu",
+ "serde_json",
+ "shuttle",
+ "simdutf8",
+ "simsimd",
+ "smallvec",
+ "strum 0.26.3",
+ "strum_macros 0.26.4",
+ "tempfile",
+ "thiserror 2.0.18",
+ "tracing",
+ "tracing-subscriber",
+ "turso_ext",
+ "turso_macros",
+ "turso_parser",
+ "twox-hash",
+ "uncased",
+ "uuid",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "turso_ext"
+version = "0.8.0-pre.3"
+source = "git+https://github.com/seanaye/turso?rev=be9acfe9e5e6efb17911af84047e4855cace53a3#be9acfe9e5e6efb17911af84047e4855cace53a3"
+dependencies = [
+ "chrono",
+ "getrandom 0.4.2",
+ "turso_macros",
+]
+
+[[package]]
+name = "turso_macros"
+version = "0.8.0-pre.3"
+source = "git+https://github.com/seanaye/turso?rev=be9acfe9e5e6efb17911af84047e4855cace53a3#be9acfe9e5e6efb17911af84047e4855cace53a3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
+[[package]]
+name = "turso_parser"
+version = "0.8.0-pre.3"
+source = "git+https://github.com/seanaye/turso?rev=be9acfe9e5e6efb17911af84047e4855cace53a3#be9acfe9e5e6efb17911af84047e4855cace53a3"
+dependencies = [
+ "bitflags 2.11.1",
+ "memchr",
+ "miette",
+ "strum 0.26.3",
+ "strum_macros 0.26.4",
+ "thiserror 2.0.18",
+ "turso_macros",
+]
+
[[package]]
name = "twox-hash"
version = "2.1.2"
@@ -15664,6 +16148,15 @@ version = "0.1.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "eaea85b334db583fe3274d12b4cd1880032beab409c0d774be044d4480ab9a94"
+[[package]]
+name = "uncased"
+version = "0.9.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e1b88fcfe09e89d3866a5c11019378088af2d24c3fbd4f0543f96b479ec90697"
+dependencies = [
+ "version_check",
+]
+
[[package]]
name = "unfurl"
version = "0.1.0"
@@ -15923,6 +16416,12 @@ version = "0.7.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "09cc8ee72d2a9becf2f2febe0205bbed8fc6615b7cb429ad062dc7b7ddd036a9"
+[[package]]
+name = "utf16_iter"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8232dd3cdaed5356e0f716d285e4b40b932ac434100fe9b7e0e8e935b9e6246"
+
[[package]]
name = "utf16string"
version = "0.2.0"
@@ -17131,12 +17630,27 @@ dependencies = [
"zeroize",
]
+[[package]]
+name = "write16"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d1890f4022759daae28ed4fe62859b1236caebfc61ede2f63ed4e695f3f6d936"
+
[[package]]
name = "writeable"
version = "0.6.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1ffae5123b2d3fc086436f8834ae3ab053a283cfac8fe0a0b8eaae044768a4c4"
+[[package]]
+name = "wyz"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05f360fc0b24296329c78fda852a1e9ae82de9cf7b27dae4b7f62f118f77b9ed"
+dependencies = [
+ "tap",
+]
+
[[package]]
name = "xmlparser"
version = "0.13.6"
@@ -17383,6 +17897,7 @@ dependencies = [
"displaydoc",
"yoke",
"zerofrom",
+ "zerovec",
]
[[package]]
@@ -17391,6 +17906,7 @@ version = "0.11.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "90f911cbc359ab6af17377d242225f4d75119aec87ea711a880987b18cd7b239"
dependencies = [
+ "serde",
"yoke",
"zerofrom",
"zerovec-derive",
diff --git a/Cargo.toml b/Cargo.toml
index 5fdb8927a8..47f8738e38 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -13,9 +13,10 @@ members = [
"crates/calendar_events",
"crates/channel_bots",
"crates/client/cache-core",
- "crates/client/cache-idb",
"crates/client/cache-sqlite",
+ "crates/client/cache-turso",
"crates/client/cache-wasm",
+ "crates/client/turso-opfs",
"crates/complete_graph",
"crates/cowlike",
"crates/crm",
@@ -207,6 +208,7 @@ pdfium-render = { version = "0.8.37", default-features = false, features = [
] }
pgvector = { version = "0.4", features = ["postgres", "sqlx"] }
postcard = { version = "1", features = ["use-std"] }
+pollster = "0.4"
quote = "1"
rand = "0.9.0"
# uses vendored to fix lambda builds failing.
@@ -267,6 +269,9 @@ tracing = "0.1.44"
tracing-opentelemetry = "0.32.1"
tracing-subscriber = { version = "0.3.22", features = ["env-filter", "json"] }
tracing-tree = "0.4.0"
+# Exact remotely available Turso fork revision approved by the browser cache G0.
+# Its source tree is identical to the locally verified cf7de761 revision.
+turso_core = { git = "https://github.com/seanaye/turso", rev = "be9acfe9e5e6efb17911af84047e4855cace53a3", default-features = false }
tungstenite = { version = "0.28", features = ["url"] }
unsynn = "0.3"
urlencoding = "2.1.3"
@@ -283,6 +288,8 @@ wiremock = "0.6.5"
# anything older than 0.2.123, so keep this floor above that.
wasm-bindgen = "0.2.123"
wasm-bindgen-futures = "0.4"
+wasm-bindgen-test = "0.3"
+web-sys = "0.3"
web-time = "1.1.0"
worker = "0.8.1"
# this is pinned to match axum 0.7.9 dependency requirements
diff --git a/apps/web/.gitignore b/apps/web/.gitignore
index 2210b6754a..34629f871d 100644
--- a/apps/web/.gitignore
+++ b/apps/web/.gitignore
@@ -47,6 +47,7 @@ CodeSignTool/
**/build
**/.build
**/dist
+**/.dist-production
**/*.tsbuildinfo
diff --git a/apps/web/justfile b/apps/web/justfile
index e19ce3ead7..85ce579b8c 100644
--- a/apps/web/justfile
+++ b/apps/web/justfile
@@ -65,18 +65,23 @@ node_heap := "--max-old-space-size=6144"
build-dev: build-cache-wasm
MODE=development NODE_ENV=production NODE_OPTIONS="{{node_heap}}" bun run --bun build
+ bun scripts/cache-wasm/cli.ts package-dist --dist dist
build-staging: build-cache-wasm
MODE=staging NODE_ENV=production NODE_OPTIONS="{{node_heap}}" bun run --bun build
+ bun scripts/cache-wasm/cli.ts package-dist --dist dist
build-prod: build-cache-wasm
MODE=production NODE_ENV=production NODE_OPTIONS="{{node_heap}}" bun run --bun build
+ bun scripts/cache-wasm/cli.ts package-dist --dist dist
# Tauri build hook (run automatically via beforeBuildCommand) — not meant to be run directly
[private]
build-tauri: build-cache-wasm
printf production > tauri/src-tauri/.macro-tauri-env
MODE=production NODE_ENV=production NODE_OPTIONS="{{node_heap}}" bun run --bun build
+ bun scripts/cache-wasm/cli.ts package-dist --dist dist
+ bun scripts/cache-wasm/cli.ts remove-sidecar --dist dist
# Build the bundle, zip it, and install it at
# tooling/native_app_server/app-archive.zip for the bundle
@@ -87,7 +92,7 @@ dist-archive: build-prod
set -euo pipefail
TARGET="$(cd {{ justfile_directory() }}/../../tooling/native_app_server && pwd)/app-archive.zip"
rm -f "$TARGET"
- (cd dist && zip -qr "$TARGET" .)
+ (cd dist && zip -qr "$TARGET" . -x '*cache_wasm_bg*.wasm.br')
echo "Archive: $TARGET"
bundle-smoke-server *ARGS:
@@ -163,6 +168,27 @@ cycles-ci:
build-cache-wasm:
wasm-pack build {{justfile_directory()}}/../../crates/client/cache-wasm --target web --release --out-dir {{justfile_directory()}}/src/lib/graphql-cache/wasm
+# Build the production browser harness served by Vite preview.
+build-cache-wasm-browser-production: build-cache-wasm build-cache-wasm-browser-test-hooks
+ bunx --bun vite build --config src/lib/graphql-cache/worker/browser-test/vite.config.ts
+ bun scripts/cache-wasm/cli.ts package-dist --dist src/lib/graphql-cache/worker/browser-test/.dist-production
+
+# Build the separate destructive-hook WASM used only by cache recovery tests.
+# Its distinct name keeps it outside the one-production-cache-WASM deploy gate.
+[private]
+build-cache-wasm-browser-test-hooks:
+ wasm-pack build {{justfile_directory()}}/../../crates/client/cache-wasm \
+ --target web --release \
+ --out-name cache_wasm_browser_test_hooks \
+ --out-dir {{justfile_directory()}}/src/lib/graphql-cache/wasm-browser-test \
+ --features browser-test-hooks
+
+# Exercise development and production asset URLs, lazy election, MIME,
+# fresh-scope startup, DB-ready, first-ready, and linear-memory budgets.
+test-cache-wasm-browser:
+ bunx --bun playwright test --config src/lib/graphql-cache/worker/browser-test/playwright.config.ts --project chromium --project firefox
+ bunx --bun playwright test --config src/lib/graphql-cache/worker/browser-test/playwright.production.config.ts --project chromium-production --project firefox-production
+
# Local profiling build: retain Rust symbols and DWARF source locations so an
# exported Firefox profile can be symbolicated back to Rust files and lines.
# This overwrites the gitignored release wasm package and is intentionally not
diff --git a/apps/web/scripts/cache-wasm/budgets.ts b/apps/web/scripts/cache-wasm/budgets.ts
new file mode 100644
index 0000000000..9082c9a93a
--- /dev/null
+++ b/apps/web/scripts/cache-wasm/budgets.ts
@@ -0,0 +1,5 @@
+export const CACHE_WASM_BUDGETS = {
+ browserReadyP95Ms: 3_000,
+ hostFirstReadyP95Ms: 5_000,
+ linearMemoryBytes: 32 * 1024 * 1024,
+} as const;
diff --git a/apps/web/scripts/cache-wasm/cli.ts b/apps/web/scripts/cache-wasm/cli.ts
new file mode 100755
index 0000000000..17639f8970
--- /dev/null
+++ b/apps/web/scripts/cache-wasm/cli.ts
@@ -0,0 +1,79 @@
+#!/usr/bin/env bun
+
+import { readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import {
+ brotliCompressSync,
+ brotliDecompressSync,
+ constants as zlibConstants,
+} from 'node:zlib';
+
+function argument(name: string, fallback?: string): string {
+ const index = process.argv.indexOf(name);
+ const value = index >= 0 ? process.argv[index + 1] : fallback;
+ if (!value) throw new Error(`missing ${name}`);
+ return value;
+}
+
+function walkFiles(directory: string): string[] {
+ return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+ const path = join(directory, entry.name);
+ return entry.isDirectory() ? walkFiles(path) : [path];
+ });
+}
+
+function oneMatchingFile(distPath: string, pattern: RegExp): string {
+ const matches = walkFiles(distPath).filter((path) =>
+ pattern.test(basename(path))
+ );
+ if (matches.length !== 1) {
+ throw new Error(
+ `expected one cache WASM artifact in ${distPath}, found ${matches.length}`
+ );
+ }
+ return matches[0];
+}
+
+const distPath = resolve(
+ argument('--dist', resolve(import.meta.dirname, '../../dist'))
+);
+const command = process.argv[2];
+
+switch (command) {
+ case 'package-dist': {
+ const wasmPath = oneMatchingFile(
+ distPath,
+ /^cache_wasm_bg(?:-[\w-]+)?\.wasm$/
+ );
+ const raw = readFileSync(wasmPath);
+ const compressed = brotliCompressSync(raw, {
+ params: {
+ [zlibConstants.BROTLI_PARAM_MODE]: zlibConstants.BROTLI_MODE_GENERIC,
+ [zlibConstants.BROTLI_PARAM_QUALITY]: 11,
+ [zlibConstants.BROTLI_PARAM_SIZE_HINT]: raw.byteLength,
+ },
+ });
+ if (!brotliDecompressSync(compressed).equals(raw)) {
+ throw new Error(
+ 'Brotli sidecar does not decompress to the raw cache WASM'
+ );
+ }
+ const sidecarPath = `${wasmPath}.br`;
+ writeFileSync(sidecarPath, compressed);
+ process.stdout.write(`${sidecarPath}\n`);
+ break;
+ }
+ case 'remove-sidecar': {
+ const sidecarPath = oneMatchingFile(
+ distPath,
+ /^cache_wasm_bg(?:-[\w-]+)?\.wasm\.br$/
+ );
+ rmSync(sidecarPath);
+ process.stdout.write(`${sidecarPath}\n`);
+ break;
+ }
+ default:
+ throw new Error(
+ 'usage: cli.ts <package-dist|remove-sidecar> --dist <directory>'
+ );
+}
diff --git a/apps/web/scripts/cache-wasm/precompressed-preview-server.mjs b/apps/web/scripts/cache-wasm/precompressed-preview-server.mjs
new file mode 100644
index 0000000000..1f6323c76a
--- /dev/null
+++ b/apps/web/scripts/cache-wasm/precompressed-preview-server.mjs
@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+import { createServer } from 'node:http';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { basename, extname, resolve, sep } from 'node:path';
+
+const dist = resolve(process.argv[2] ?? 'dist');
+const port = Number(process.env.PORT ?? 4189);
+if (!Number.isSafeInteger(port) || port <= 0) {
+ throw new Error(`invalid PORT: ${process.env.PORT}`);
+}
+if (!existsSync(dist) || !statSync(dist).isDirectory()) {
+ throw new Error(`production browser dist is missing: ${dist}`);
+}
+
+const contentTypes = new Map([
+ ['.html', 'text/html; charset=utf-8'],
+ ['.css', 'text/css; charset=utf-8'],
+ ['.js', 'text/javascript; charset=utf-8'],
+ ['.map', 'application/json; charset=utf-8'],
+ ['.json', 'application/json; charset=utf-8'],
+ ['.svg', 'image/svg+xml; charset=utf-8'],
+ ['.png', 'image/png'],
+ ['.ico', 'image/x-icon'],
+ ['.woff2', 'font/woff2'],
+ ['.wasm', 'application/wasm'],
+]);
+
+createServer((request, response) => {
+ const url = new URL(request.url ?? '/', `http://${request.headers.host}`);
+ if (url.pathname === '/app') {
+ response.writeHead(302, { location: '/app/' });
+ response.end();
+ return;
+ }
+ if (!url.pathname.startsWith('/app/')) {
+ response.writeHead(404).end('not found');
+ return;
+ }
+ let relativePath;
+ try {
+ relativePath = decodeURIComponent(url.pathname.slice('/app/'.length));
+ } catch {
+ response.writeHead(400).end('invalid path encoding');
+ return;
+ }
+ const requestedPath = resolve(dist, relativePath || 'index.html');
+ if (
+ requestedPath !== dist &&
+ !requestedPath.startsWith(`${dist}${sep}`)
+ ) {
+ response.writeHead(400).end('invalid path');
+ return;
+ }
+ const isWasm = extname(requestedPath) === '.wasm';
+ const isCacheWasm =
+ isWasm && /^cache_wasm_bg(?:-[\w-]+)?\.wasm$/.test(basename(requestedPath));
+ const bodyPath = isCacheWasm ? `${requestedPath}.br` : requestedPath;
+ if (!existsSync(bodyPath) || !statSync(bodyPath).isFile()) {
+ response.writeHead(404).end('not found');
+ return;
+ }
+ const body = readFileSync(bodyPath);
+ const headers = {
+ 'content-type': contentTypes.get(extname(requestedPath)) ?? 'application/octet-stream',
+ 'content-length': String(body.byteLength),
+ 'cache-control': 'public, max-age=31536000, immutable',
+ ...(isCacheWasm ? { 'content-encoding': 'br' } : {}),
+ };
+ response.writeHead(200, headers);
+ response.end(request.method === 'HEAD' ? undefined : body);
+}).listen(port, '127.0.0.1', () => {
+ process.stdout.write(
+ `precompressed cache WASM preview listening at http://127.0.0.1:${port}/app/\n`
+ );
+});
diff --git a/apps/web/scripts/cache-wasm/prune-old-brotli-from-s3.sh b/apps/web/scripts/cache-wasm/prune-old-brotli-from-s3.sh
new file mode 100755
index 0000000000..3a753ccbdb
--- /dev/null
+++ b/apps/web/scripts/cache-wasm/prune-old-brotli-from-s3.sh
@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# Prune prior cache WASM objects only after every publication step succeeds.
+set -euo pipefail
+
+if [ "$#" -lt 2 ] || [ "$#" -gt 3 ]; then
+ echo "usage: prune-old-brotli-from-s3.sh <dist-root> <s3-prefix> [retention-days]" >&2
+ exit 2
+fi
+
+dist_root=$1
+s3_prefix=${2%/}
+retention_days=${3:-7}
+if ! [[ "$retention_days" =~ ^[1-9][0-9]*$ ]]; then
+ echo "retention days must be a positive integer" >&2
+ exit 2
+fi
+
+raw_files=()
+while IFS= read -r -d '' path; do
+ raw_files+=("$path")
+done < <(find "$dist_root" -type f -name 'cache_wasm_bg*.wasm' -print0)
+if [ "${#raw_files[@]}" -ne 1 ]; then
+ echo "expected one raw cache WASM; found ${#raw_files[@]}" >&2
+ exit 1
+fi
+raw=${raw_files[0]}
+relative_key=${raw#"${dist_root%/}"/}
+if [ "$relative_key" = "$raw" ]; then
+ echo "cache WASM is not contained by dist root" >&2
+ exit 1
+fi
+
+s3_location=${s3_prefix#s3://}
+if [ "$s3_location" = "$s3_prefix" ]; then
+ echo "S3 prefix must start with s3://" >&2
+ exit 2
+fi
+bucket=${s3_location%%/*}
+if [ -z "$bucket" ]; then
+ echo "S3 prefix must include a bucket" >&2
+ exit 2
+fi
+if [[ "$s3_location" == */* ]]; then
+ prefix=${s3_location#*/}
+else
+ prefix=''
+fi
+current_key=${prefix:+$prefix/}$relative_key
+cutoff=$(date -u -d "$retention_days days ago" '+%Y-%m-%dT%H:%M:%SZ')
+list_args=(s3api list-objects-v2 --bucket "$bucket")
+if [ -n "$prefix" ]; then
+ list_args+=(--prefix "$prefix/")
+fi
+list_args+=(
+ --query "Contents[?LastModified<=\`$cutoff\`].Key"
+ --output text
+)
+
+# Immutable hashed URLs can remain in recently served pages after a deploy.
+# Preserve the current object and every generation inside the retention window;
+# remove only matching cache WASM keys whose S3 LastModified is older.
+while IFS= read -r key; do
+ [ -n "$key" ] || continue
+ [ "$key" != "None" ] || continue
+ [ "$key" != "$current_key" ] || continue
+ case "$key" in
+ *cache_wasm_bg*.wasm) aws s3 rm "s3://$bucket/$key" ;;
+ esac
+done < <(aws "${list_args[@]}" | tr '\t' '\n')
diff --git a/apps/web/scripts/cache-wasm/upload-brotli-to-s3.sh b/apps/web/scripts/cache-wasm/upload-brotli-to-s3.sh
new file mode 100755
index 0000000000..08eb6bd0ed
--- /dev/null
+++ b/apps/web/scripts/cache-wasm/upload-brotli-to-s3.sh
@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Upload the precompressed cache WASM bytes at the original .wasm key. The
+# caller's generic sync must exclude both cache_wasm_bg*.wasm and *.wasm.br.
+set -euo pipefail
+
+if [ "$#" -lt 2 ] || [ "$#" -gt 3 ]; then
+ echo "usage: upload-brotli-to-s3.sh <dist-root> <s3-prefix> [acl]" >&2
+ exit 2
+fi
+
+dist_root=$1
+s3_prefix=${2%/}
+acl=${3:-}
+raw_files=()
+while IFS= read -r -d '' path; do
+ raw_files+=("$path")
+done < <(find "$dist_root" -type f -name 'cache_wasm_bg*.wasm' -print0)
+sidecars=()
+while IFS= read -r -d '' path; do
+ sidecars+=("$path")
+done < <(find "$dist_root" -type f -name 'cache_wasm_bg*.wasm.br' -print0)
+if [ "${#raw_files[@]}" -ne 1 ] || [ "${#sidecars[@]}" -ne 1 ]; then
+ echo "expected one raw cache WASM and one Brotli sidecar; found ${#raw_files[@]} raw / ${#sidecars[@]} sidecar" >&2
+ exit 1
+fi
+raw=${raw_files[0]}
+sidecar=${sidecars[0]}
+if [ "$sidecar" != "$raw.br" ]; then
+ echo "cache WASM sidecar is not adjacent to its raw artifact" >&2
+ exit 1
+fi
+if ! brotli --decompress --stdout "$sidecar" | cmp --silent - "$raw"; then
+ echo "cache WASM sidecar does not decompress to the raw artifact" >&2
+ exit 1
+fi
+relative_key=${raw#"${dist_root%/}"/}
+if [ "$relative_key" = "$raw" ]; then
+ echo "cache WASM is not contained by dist root" >&2
+ exit 1
+fi
+args=(
+ s3 cp "$sidecar" "$s3_prefix/$relative_key"
+ --content-type application/wasm
+ --content-encoding br
+ --cache-control 'public, max-age=31536000, immutable'
+)
+if [ -n "$acl" ]; then
+ args+=(--acl "$acl")
+fi
+# Pruning is intentionally a separate post-publication operation. A failure in
+# this upload or any later generic/index publish step must retain prior keys.
+aws "${args[@]}"
diff --git a/apps/web/scripts/cache-wasm/upload-brotli-to-s3.test.ts b/apps/web/scripts/cache-wasm/upload-brotli-to-s3.test.ts
new file mode 100644
index 0000000000..815d029484
--- /dev/null
+++ b/apps/web/scripts/cache-wasm/upload-brotli-to-s3.test.ts
@@ -0,0 +1,211 @@
+import { spawnSync } from 'node:child_process';
+import {
+ chmodSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ rmSync,
+ writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { brotliCompressSync } from 'node:zlib';
+import { afterEach, describe, expect, it } from 'vitest';
+
+const temporaryDirectories: string[] = [];
+afterEach(() => {
+ for (const directory of temporaryDirectories.splice(0)) {
+ rmSync(directory, { recursive: true, force: true });
+ }
+});
+
+describe('cache WASM S3 upload', () => {
+ it('production generic sync excludes cache raw/sidecar but not unrelated WASM', () => {
+ const infrastructure = readFileSync(
+ resolve(import.meta.dirname, '../../../../infra/stacks/web-app/index.ts'),
+ 'utf8'
+ );
+ expect(infrastructure).toContain(
+ '--exclude "*cache_wasm_bg*.wasm" --exclude "*cache_wasm_bg*.wasm.br"'
+ );
+ expect(infrastructure).not.toContain('--exclude "*.wasm"');
+ const uploadIndex = infrastructure.indexOf('upload-brotli-to-s3.sh');
+ const syncIndex = infrastructure.indexOf('aws s3 sync ./output');
+ const indexPublishIndex = infrastructure.indexOf(
+ 'index-html-object-metadata-command'
+ );
+ const pruneIndex = infrastructure.indexOf(
+ 'prune-old-brotli-from-s3.sh'
+ );
+ expect(uploadIndex).toBeLessThan(syncIndex);
+ expect(syncIndex).toBeLessThan(indexPublishIndex);
+ expect(indexPublishIndex).toBeLessThan(pruneIndex);
+ expect(infrastructure.slice(uploadIndex, syncIndex)).toContain('&&');
+ expect(infrastructure).toContain(
+ 'dependsOn: [webAppAssets, syncAssetsCommand]'
+ );
+ expect(infrastructure).toContain(
+ 'dependsOn: [indexHtmlObjectMetadataCommand]'
+ );
+ });
+
+ it('keeps sidecars in web delivery but excludes them from native/OTA packaging', () => {
+ const webJustfile = readFileSync(
+ resolve(import.meta.dirname, '../../justfile'),
+ 'utf8'
+ );
+ expect(webJustfile).toMatch(
+ /build-tauri:[\s\S]*package-dist --dist dist\n\s+bun scripts\/cache-wasm\/cli\.ts remove-sidecar --dist dist/
+ );
+ expect(webJustfile).toContain(
+ `zip -qr "$TARGET" . -x '*cache_wasm_bg*.wasm.br'`
+ );
+
+ const infrastructure = readFileSync(
+ resolve(import.meta.dirname, '../../../../infra/stacks/web-app/index.ts'),
+ 'utf8'
+ );
+ expect(infrastructure).toContain(
+ `find ${'${shellQuote(appArchiveOutputPath)}'} -type f -name 'cache_wasm_bg*.wasm.br' -delete`
+ );
+ expect(infrastructure).toContain('--exclude "app-archive/*"');
+ });
+
+ it('uploads only sidecar bytes at the original WASM key with exact metadata', () => {
+ const directory = mkdtempSync(join(tmpdir(), 'cache-wasm-upload-'));
+ temporaryDirectories.push(directory);
+ const dist = join(directory, 'dist');
+ const assets = join(dist, 'assets');
+ const bin = join(directory, 'bin');
+ mkdirSync(assets, { recursive: true });
+ mkdirSync(bin);
+ const raw = Buffer.from('cache wasm'.repeat(1_000));
+ const unrelated = Buffer.from('leave me alone');
+ const rawPath = join(assets, 'cache_wasm_bg-hash.wasm');
+ const sidecarPath = `${rawPath}.br`;
+ const unrelatedPath = join(assets, 'other.wasm');
+ writeFileSync(rawPath, raw);
+ writeFileSync(sidecarPath, brotliCompressSync(raw));
+ writeFileSync(unrelatedPath, unrelated);
+ const argumentsPath = join(directory, 'aws-arguments.txt');
+ const fakeAws = join(bin, 'aws');
+ writeFileSync(
+ fakeAws,
+ `#!/usr/bin/env bash\nprintf '%s\\n' CALL "$@" >> ${JSON.stringify(argumentsPath)}\nif [ "\${FAIL_CP:-}" = true ] && [ "\${2:-}" = cp ]; then exit 42; fi\n`
+ );
+ chmodSync(fakeAws, 0o755);
+
+ const script = resolve(import.meta.dirname, 'upload-brotli-to-s3.sh');
+ const result = spawnSync(
+ 'bash',
+ [script, dist, 's3://example/app', 'public-read'],
+ {
+ encoding: 'utf8',
+ env: { ...process.env, PATH: `${bin}:${process.env.PATH}` },
+ }
+ );
+
+ expect(result.stderr).toBe('');
+ expect(result.status).toBe(0);
+ expect(readFileSync(argumentsPath, 'utf8').trim().split('\n')).toEqual([
+ 'CALL',
+ 's3',
+ 'cp',
+ sidecarPath,
+ 's3://example/app/assets/cache_wasm_bg-hash.wasm',
+ '--content-type',
+ 'application/wasm',
+ '--content-encoding',
+ 'br',
+ '--cache-control',
+ 'public, max-age=31536000, immutable',
+ '--acl',
+ 'public-read',
+ ]);
+ expect(readFileSync(rawPath)).toEqual(raw);
+ expect(readFileSync(unrelatedPath)).toEqual(unrelated);
+ });
+
+ it('prunes only old cache objects in its separate post-publication step', () => {
+ const directory = mkdtempSync(join(tmpdir(), 'cache-wasm-prune-'));
+ temporaryDirectories.push(directory);
+ const dist = join(directory, 'dist');
+ const assets = join(dist, 'assets');
+ const bin = join(directory, 'bin');
+ mkdirSync(assets, { recursive: true });
+ mkdirSync(bin);
+ writeFileSync(join(assets, 'cache_wasm_bg-current.wasm'), 'current');
+ const argumentsPath = join(directory, 'aws-arguments.txt');
+ const fakeAws = join(bin, 'aws');
+ writeFileSync(
+ fakeAws,
+ `#!/usr/bin/env bash\nprintf '%s\\n' CALL "$@" >> ${JSON.stringify(argumentsPath)}\nif [ "\${1:-}" = s3api ]; then printf '%s\\n' app/assets/cache_wasm_bg-old.wasm app/assets/cache_wasm_bg-current.wasm; fi\n`
+ );
+ chmodSync(fakeAws, 0o755);
+
+ const result = spawnSync(
+ 'bash',
+ [
+ resolve(import.meta.dirname, 'prune-old-brotli-from-s3.sh'),
+ dist,
+ 's3://example/app',
+ ],
+ {
+ encoding: 'utf8',
+ env: { ...process.env, PATH: `${bin}:${process.env.PATH}` },
+ }
+ );
+ expect(result.status).toBe(0);
+ const calls = readFileSync(argumentsPath, 'utf8');
+ expect(calls).toContain(
+ 'CALL\ns3api\nlist-objects-v2\n--bucket\nexample\n--prefix\napp/\n'
+ );
+ expect(calls).toContain(
+ 'CALL\ns3\nrm\ns3://example/app/assets/cache_wasm_bg-old.wasm\n'
+ );
+ expect(calls).not.toContain(
+ 'rm\ns3://example/app/assets/cache_wasm_bg-current.wasm'
+ );
+ });
+
+ it('does not invoke pruning when the current upload fails', () => {
+ const directory = mkdtempSync(join(tmpdir(), 'cache-wasm-upload-fail-'));
+ temporaryDirectories.push(directory);
+ const dist = join(directory, 'dist');
+ const assets = join(dist, 'assets');
+ const bin = join(directory, 'bin');
+ mkdirSync(assets, { recursive: true });
+ mkdirSync(bin);
+ const rawPath = join(assets, 'cache_wasm_bg-current.wasm');
+ writeFileSync(rawPath, Buffer.from('current cache wasm'.repeat(100)));
+ writeFileSync(
+ `${rawPath}.br`,
+ brotliCompressSync(readFileSync(rawPath))
+ );
+ const argumentsPath = join(directory, 'aws-arguments.txt');
+ const fakeAws = join(bin, 'aws');
+ writeFileSync(
+ fakeAws,
+ `#!/usr/bin/env bash\nprintf '%s\\n' CALL "$@" >> ${JSON.stringify(argumentsPath)}\nif [ "\${2:-}" = cp ]; then exit 42; fi\n`
+ );
+ chmodSync(fakeAws, 0o755);
+
+ const result = spawnSync(
+ 'bash',
+ [
+ resolve(import.meta.dirname, 'upload-brotli-to-s3.sh'),
+ dist,
+ 's3://example/app',
+ ],
+ {
+ encoding: 'utf8',
+ env: { ...process.env, PATH: `${bin}:${process.env.PATH}` },
+ }
+ );
+
+ expect(result.status).toBe(42);
+ const calls = readFileSync(argumentsPath, 'utf8');
+ expect(calls).toContain('\ns3\ncp\n');
+ expect(calls).not.toContain('\nrm\n');
+ });
+});
diff --git a/apps/web/scripts/preview/deploy.ts b/apps/web/scripts/preview/deploy.ts
index 884ce62590..71fc27bd29 100644
--- a/apps/web/scripts/preview/deploy.ts
+++ b/apps/web/scripts/preview/deploy.ts
@@ -10,12 +10,43 @@
* AWS credentials must be configured (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, or AWS profile)
*/
-import { execSync } from 'node:child_process';
+import { execFileSync, execSync } from 'node:child_process';
import { existsSync } from 'node:fs';
import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const SCRIPT_DIRECTORY = fileURLToPath(new URL('.', import.meta.url));
const PREVIEW_BUCKET = 'macro-preview-assets-dev';
-const DIST_PATH = resolve(import.meta.dir, '../../dist');
+const DIST_PATH = resolve(SCRIPT_DIRECTORY, '../../dist');
+const CACHE_WASM_UPLOAD_SCRIPT = resolve(
+ SCRIPT_DIRECTORY,
+ '../cache-wasm/upload-brotli-to-s3.sh'
+);
+const CACHE_WASM_PRUNE_SCRIPT = resolve(
+ SCRIPT_DIRECTORY,
+ '../cache-wasm/prune-old-brotli-from-s3.sh'
+);
+
+export function previewSyncArguments(
+ previewId: string,
+ distPath = DIST_PATH
+): string[] {
+ return [
+ 's3',
+ 'sync',
+ `${distPath}/`,
+ `s3://${PREVIEW_BUCKET}/${previewId}/app/`,
+ '--delete',
+ '--cache-control',
+ 'public, max-age=31536000, immutable',
+ '--exclude',
+ 'index.html',
+ '--exclude',
+ '*cache_wasm_bg*.wasm',
+ '--exclude',
+ '*cache_wasm_bg*.wasm.br',
+ ];
+}
function parseArgs(): { previewId: string; skipBuild: boolean } {
const args = process.argv.slice(2);
@@ -65,32 +96,47 @@ function build(): void {
});
}
+type PreviewCommandRunner = (
+ executable: string,
+ argumentsList: readonly string[]
+) => void;
+
+export function publishPreviewAssets(
+ previewId: string,
+ distPath = DIST_PATH,
+ run: PreviewCommandRunner = (executable, argumentsList) => {
+ execFileSync(executable, [...argumentsList], { stdio: 'inherit' });
+ }
+): void {
+ const s3Prefix = `s3://${PREVIEW_BUCKET}/${previewId}/app`;
+ run('bash', [CACHE_WASM_UPLOAD_SCRIPT, distPath, s3Prefix]);
+ run('aws', previewSyncArguments(previewId, distPath));
+ run('aws', [
+ 's3',
+ 'cp',
+ `${distPath}/index.html`,
+ `${s3Prefix}/index.html`,
+ '--cache-control',
+ 'no-cache, no-store, must-revalidate',
+ ]);
+ run('bash', [CACHE_WASM_PRUNE_SCRIPT, distPath, s3Prefix]);
+}
+
function deploy(previewId: string): void {
validateBucket(PREVIEW_BUCKET);
if (!existsSync(DIST_PATH)) {
console.error(`ERROR: Build output not found at ${DIST_PATH}`);
- console.error('Run with --skip-build=false or build first with: bun run build:dev');
+ console.error(
+ 'Run with --skip-build=false or build first with: bun run build:dev'
+ );
process.exit(1);
}
console.log(`\nDeploying to s3://${PREVIEW_BUCKET}/${previewId}/app/\n`);
- // Sync all files except index.html with immutable cache
- execSync(
- `aws s3 sync ${DIST_PATH}/ s3://${PREVIEW_BUCKET}/${previewId}/app/ ` +
- `--delete ` +
- `--cache-control "public, max-age=31536000, immutable" ` +
- `--exclude "index.html"`,
- { stdio: 'inherit' }
- );
-
- // Upload index.html with no-cache
- execSync(
- `aws s3 cp ${DIST_PATH}/index.html s3://${PREVIEW_BUCKET}/${previewId}/app/index.html ` +
- `--cache-control "no-cache, no-store, must-revalidate"`,
- { stdio: 'inherit' }
- );
+ // Upload current bytes, publish assets/index, and only then prune old keys.
+ publishPreviewAssets(previewId);
const previewUrl = `https://${previewId}.preview.macro.com`;
console.log(`\nPreview deployed: ${previewUrl}\n`);
@@ -108,14 +154,13 @@ function cleanup(previewId: string): void {
console.log('\nCleanup complete\n');
}
-// Main
-const { previewId, skipBuild } = parseArgs();
+if (import.meta.main) {
+ const { previewId, skipBuild } = parseArgs();
-if (process.argv.includes('--cleanup')) {
- cleanup(previewId);
-} else {
- if (!skipBuild) {
- build();
+ if (process.argv.includes('--cleanup')) {
+ cleanup(previewId);
+ } else {
+ if (!skipBuild) build();
+ deploy(previewId);
}
- deploy(previewId);
}
diff --git a/apps/web/scripts/preview/preview.test.ts b/apps/web/scripts/preview/preview.test.ts
index e54bbd881c..c2870bff3d 100644
--- a/apps/web/scripts/preview/preview.test.ts
+++ b/apps/web/scripts/preview/preview.test.ts
@@ -1,4 +1,5 @@
import { describe, expect, it } from 'vitest';
+import { previewSyncArguments, publishPreviewAssets } from './deploy';
import {
extractPreviewIdFromBody,
generatePreviewId,
@@ -34,7 +35,8 @@ describe('buildCommentBody', () => {
describe('extractPreviewIdFromBody', () => {
it('extracts preview id from url without path', () => {
- const body = '**Preview:** [https://my-feature-abc123.preview.macro.com](...)';
+ const body =
+ '**Preview:** [https://my-feature-abc123.preview.macro.com](...)';
expect(extractPreviewIdFromBody(body)).toBe('my-feature-abc123');
});
@@ -73,7 +75,8 @@ describe('generatePreviewId', () => {
});
it('truncates long branch names to 30 chars', () => {
- const longBranch = 'this-is-a-very-long-branch-name-that-exceeds-thirty-chars';
+ const longBranch =
+ 'this-is-a-very-long-branch-name-that-exceeds-thirty-chars';
const id = generatePreviewId(longBranch);
const prefixWithoutNanoid = id.slice(0, -7);
expect(prefixWithoutNanoid.length).toBeLessThanOrEqual(30);
@@ -91,6 +94,51 @@ describe('generatePreviewId', () => {
});
});
+describe('preview cache WASM deployment', () => {
+ it('excludes only cache WASM raw/sidecar from generic sync', () => {
+ const argumentsList = previewSyncArguments('preview-id', '/tmp/dist');
+ expect(argumentsList).toContain('*cache_wasm_bg*.wasm');
+ expect(argumentsList).toContain('*cache_wasm_bg*.wasm.br');
+ expect(argumentsList).not.toContain('*.wasm');
+ expect(argumentsList).not.toContain('*.wasm.br');
+ });
+
+ it('publishes current WASM, assets, and index before pruning', () => {
+ const calls: string[][] = [];
+ publishPreviewAssets('preview-id', '/tmp/dist', (executable, args) => {
+ calls.push([executable, ...args]);
+ });
+ expect(calls.map((call) => call[0])).toEqual([
+ 'bash',
+ 'aws',
+ 'aws',
+ 'bash',
+ ]);
+ expect(calls[0].join(' ')).toContain('upload-brotli-to-s3.sh');
+ expect(calls[1].slice(0, 3)).toEqual(['aws', 's3', 'sync']);
+ expect(calls[2].slice(0, 3)).toEqual(['aws', 's3', 'cp']);
+ expect(calls[3].join(' ')).toContain('prune-old-brotli-from-s3.sh');
+ });
+
+ it.each([1, 2])(
+ 'does not prune when publication step %i fails',
+ (failedCall) => {
+ const calls: string[][] = [];
+ expect(() =>
+ publishPreviewAssets('preview-id', '/tmp/dist', (executable, args) => {
+ calls.push([executable, ...args]);
+ if (calls.length - 1 === failedCall) throw new Error('publish failed');
+ })
+ ).toThrow('publish failed');
+ expect(
+ calls.some((call) =>
+ call.join(' ').includes('prune-old-brotli-from-s3.sh')
+ )
+ ).toBe(false);
+ }
+ );
+});
+
describe('roundtrip: build url then extract id', () => {
it('extracts same id from generated comment', () => {
const originalId = 'my-feature-abc123';
diff --git a/apps/web/src/lib/core/constant/featureFlags.ts b/apps/web/src/lib/core/constant/featureFlags.ts
index 64b2d01a6a..6acb7f6d1c 100644
--- a/apps/web/src/lib/core/constant/featureFlags.ts
+++ b/apps/web/src/lib/core/constant/featureFlags.ts
@@ -484,6 +484,24 @@ export const ENABLE_GRAPHQL_SOUP_OVERRIDE = getFeatureFlagOverride(
'ENABLE_GRAPHQL_SOUP'
);
+const parseBooleanOverride = (value: unknown): boolean | undefined =>
+ value === 'true' ? true : value === 'false' ? false : undefined;
+
+/** Browser-only Turso/OPFS cache rollout. Production defaults off. */
+export const ENABLE_BROWSER_TURSO_CACHE_FLAG = 'enable-browser-turso-cache';
+const BROWSER_TURSO_CACHE_ENV = import.meta.env.VITE_ENABLE_BROWSER_TURSO_CACHE;
+export const ENABLE_BROWSER_TURSO_CACHE_OVERRIDE = parseBooleanOverride(
+ BROWSER_TURSO_CACHE_ENV
+);
+
+/** Independent emergency stop. Any true env/PostHog source wins. */
+export const DISABLE_BROWSER_TURSO_CACHE_FLAG = 'disable-browser-turso-cache';
+const DISABLE_BROWSER_TURSO_CACHE_ENV = import.meta.env
+ .VITE_DISABLE_BROWSER_TURSO_CACHE;
+export const DISABLE_BROWSER_TURSO_CACHE_OVERRIDE = parseBooleanOverride(
+ DISABLE_BROWSER_TURSO_CACHE_ENV
+);
+
/**
* Non-reactive check for imperative call sites (e.g. the soup GraphQL
* client's normalized-cache gate). Env override first (dev), else the same
diff --git a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts
index 163067b531..c9330f4169 100644
--- a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts
+++ b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts
@@ -18,12 +18,13 @@ import {
subscribe,
} from 'wonka';
import type { CacheHost } from '../host/types';
-import type {
- ClaimedMutation,
- EnqueueOptimisticMutationResult,
- MutationClaim,
- ReadResult,
- WriteResult,
+import {
+ ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE,
+ type ClaimedMutation,
+ type EnqueueOptimisticMutationResult,
+ type MutationClaim,
+ type ReadResult,
+ type WriteResult,
} from '../protocol';
import { entityFromArgument } from './entity-resolvers';
import {
@@ -479,6 +480,38 @@ function harness(
return { ops, results, forwarded, client };
}
+function controlledQueryHarness(
+ host: CacheHost,
+ options: NormalizedCacheExchangeOptions = {}
+) {
+ const ops = makeSubject<Operation>();
+ const network = makeSubject<OperationResult>();
+ const forwarded: Operation[] = [];
+ const results: OperationResult[] = [];
+ const client = {
+ reexecuteOperation: vi.fn((operation: Operation) => ops.next(operation)),
+ } as unknown as Client;
+ const forward = (ops$: Source<Operation>): Source<OperationResult> => {
+ pipe(
+ ops$,
+ subscribe((operation) => forwarded.push(operation))
+ );
+ return network.source;
+ };
+ pipe(
+ normalizedCacheExchange(
+ host,
+ options
+ )({
+ forward,
+ client,
+ dispatchDebug: () => undefined,
+ })(ops.source),
+ subscribe((result) => results.push(result))
+ );
+ return { ops, network, forwarded, results, client };
+}
+
const tick = () => new Promise((resolve) => setTimeout(resolve, 10));
describe('normalizedCacheExchange', () => {
@@ -957,6 +990,347 @@ describe('normalizedCacheExchange', () => {
]);
});
+ it('defers replacement reread behind a slow successful fallback network request', async () => {
+ let readCount = 0;
+ host.readQuery = async (args) => {
+ host.reads.push({ opKey: args.opKey, query: args.query });
+ readCount += 1;
+ if (readCount === 1) {
+ throw Object.assign(new Error('old owner lost'), {
+ errorCode: 'owner-epoch-lost',
+ });
+ }
+ return { kind: 'miss' };
+ };
+ const { ops, network, forwarded, client } = controlledQueryHarness(host);
+ ops.next(makeOp(41));
+ await tick();
+ expect(forwarded).toHaveLength(1);
+
+ host.pushAffected([41]);
+ expect(client.reexecuteOperation).not.toHaveBeenCalled();
+ network.next({
+ operation: forwarded[0]!,
+ data: { from: 'slow-network' },
+ error: undefined,
+ extensions: undefined,
+ stale: false,
+ hasNext: false,
+ });
+ await tick();
+
+ expect(forwarded).toHaveLength(1);
+ expect(client.reexecuteOperation).not.toHaveBeenCalled();
+ expect(host.writes).toHaveLength(1);
+ expect(host.reads).toHaveLength(2);
+ });
+
+ it('restores a fast successful fallback after replacement without another API request', async () => {
+ let readCount = 0;
+ let cached: unknown;
+ host.readQuery = async (args) => {
+ host.reads.push({
+ opKey: args.opKey,
+ query: args.query,
+ variables: args.variables,
+ priority: args.priority,
+ entityResolvers: args.entityResolvers,
+ });
+ readCount += 1;
+ if (readCount === 1) {
+ throw Object.assign(new Error('old owner lost'), {
+ errorCode: 'owner-epoch-lost',
+ });
+ }
+ return cached === undefined
+ ? { kind: 'miss' }
+ : { kind: 'hit', data: cached };
+ };
+ host.writeQuery = vi
+ .fn()
+ .mockRejectedValueOnce(new Error('replacement init not ready'))
+ .mockImplementationOnce(async (args) => {
+ cached = args.data;
+ return { changed: [], affectedOps: [], reset: false };
+ });
+ const { ops, network, forwarded, results, client } = controlledQueryHarness(
+ host,
+ ENTITY_RESOLVER_OPTIONS
+ );
+ ops.next(makeOp(42));
+ await tick();
+ network.next({
+ operation: forwarded[0]!,
+ data: { from: 'fast-network' },
+ error: undefined,
+ extensions: undefined,
+ stale: false,
+ hasNext: false,
+ });
+ await tick();
+ expect(host.writeQuery).toHaveBeenCalledOnce();
+
+ host.pushAffected([42]);
+ await tick();
+
+ expect(host.writeQuery).toHaveBeenCalledTimes(2);
+ expect(host.writeQuery).toHaveBeenLastCalledWith(
+ expect.objectContaining({
+ opKey: 42,
+ data: { from: 'fast-network' },
+ entityResolvers: EXPECTED_ENTITY_RESOLVERS,
+ })
+ );
+ expect(cached).toEqual({ from: 'fast-network' });
+ expect(host.reads).toHaveLength(2);
+ expect(host.reads[1]).toEqual(
+ expect.objectContaining({
+ opKey: 42,
+ variables: { input: { limit: 2 } },
+ entityResolvers: EXPECTED_ENTITY_RESOLVERS,
+ })
+ );
+ expect(client.reexecuteOperation).not.toHaveBeenCalled();
+ expect(forwarded).toHaveLength(1);
+ expect(results).toHaveLength(1);
+ });
+
+ it('serializes a replacement notification during write and preserves payload after retry failure', async () => {
+ let readCount = 0;
+ host.readQuery = async (args) => {
+ host.reads.push({ opKey: args.opKey, query: args.query });
+ readCount += 1;
+ if (readCount === 1) {
+ throw Object.assign(new Error('old owner lost'), {
+ errorCode: 'owner-epoch-lost',
+ });
+ }
+ return { kind: 'hit', data: { from: 'network' } };
+ };
+ let rejectInitialWrite!: (error: Error) => void;
+ const initialWrite = new Promise<never>((_resolve, reject) => {
+ rejectInitialWrite = reject;
+ });
+ host.writeQuery = vi
+ .fn()
+ .mockImplementationOnce(async () => await initialWrite)
+ .mockRejectedValueOnce(new Error('replacement failed while writing'))
+ .mockResolvedValueOnce({ changed: [], affectedOps: [], reset: false });
+ const { ops, network, forwarded, client } = controlledQueryHarness(host);
+ ops.next(makeOp(43));
+ await tick();
+ network.next({
+ operation: forwarded[0]!,
+ data: { from: 'network' },
+ error: undefined,
+ extensions: undefined,
+ stale: false,
+ hasNext: false,
+ });
+ await vi.waitFor(() => expect(host.writeQuery).toHaveBeenCalledOnce());
+
+ host.pushAffected([43]);
+ rejectInitialWrite(new Error('old write failed'));
+ await vi.waitFor(() => expect(host.writeQuery).toHaveBeenCalledTimes(2));
+ await tick();
+ expect(host.reads).toHaveLength(1);
+
+ host.pushAffected([43]);
+ await vi.waitFor(() => expect(host.writeQuery).toHaveBeenCalledTimes(3));
+ await vi.waitFor(() => expect(host.reads).toHaveLength(2));
+
+ expect(client.reexecuteOperation).not.toHaveBeenCalled();
+ expect(forwarded).toHaveLength(1);
+ });
+
+ it('invalidates retained fallback A before newer network result B writes', async () => {
+ let readCount = 0;
+ let writeCount = 0;
+ let cached: unknown;
+ host.readQuery = async (args) => {
+ host.reads.push({
+ opKey: args.opKey,
+ query: args.query,
+ variables: args.variables,
+ entityResolvers: args.entityResolvers,
+ });
+ readCount += 1;
+ if (readCount === 1) {
+ throw Object.assign(new Error('old owner lost'), {
+ errorCode: 'owner-epoch-lost',
+ });
+ }
+ return { kind: 'hit', data: cached };
+ };
+ host.writeQuery = vi.fn(async (args) => {
+ writeCount += 1;
+ if (writeCount === 1) throw new Error('initial A write failed');
+ if (writeCount === 2) throw new Error('replacement A write failed');
+ cached = args.data;
+ return { changed: [], affectedOps: [], reset: false };
+ });
+ const { ops, network, forwarded, client } = controlledQueryHarness(
+ host,
+ ENTITY_RESOLVER_OPTIONS
+ );
+ const fallbackA = makeOp(46);
+ ops.next(fallbackA);
+ await tick();
+ network.next({
+ operation: forwarded[0]!,
+ data: { version: 'A' },
+ error: undefined,
+ extensions: undefined,
+ stale: false,
+ hasNext: false,
+ });
+ await tick();
+ host.pushAffected([46]);
+ await vi.waitFor(() => expect(host.writeQuery).toHaveBeenCalledTimes(2));
+ await tick();
+
+ const newerB = makeOp(46, 'network-only');
+ ops.next(newerB);
+ await vi.waitFor(() =>
+ expect(forwarded.filter(({ kind }) => kind === 'query')).toHaveLength(2)
+ );
+ network.next({
+ operation: forwarded.findLast(({ kind }) => kind === 'query')!,
+ data: { version: 'B' },
+ error: undefined,
+ extensions: undefined,
+ stale: false,
+ hasNext: false,
+ });
+ await vi.waitFor(() => expect(host.writeQuery).toHaveBeenCalledTimes(3));
+ await vi.waitFor(() => expect(host.reads).toHaveLength(2));
+ expect(cached).toEqual({ version: 'B' });
+ expect(host.reads[1]?.entityResolvers).toEqual(EXPECTED_ENTITY_RESOLVERS);
+
+ host.pushAffected([46]);
+ await tick();
+ expect(client.reexecuteOperation).toHaveBeenCalledOnce();
+ expect(host.reads).toHaveLength(3);
+ expect(host.writeQuery).toHaveBeenCalledTimes(3);
+ expect(cached).toEqual({ version: 'B' });
+ expect(forwarded.filter(({ kind }) => kind === 'query')).toHaveLength(2);
+
+ ops.next(teardownOf(newerB));
+ await tick();
+ host.pushAffected([46]);
+ await tick();
+ expect(host.writeQuery).toHaveBeenCalledTimes(3);
+ expect(cached).toEqual({ version: 'B' });
+ });
+
+ it('clears registration-only context before a later ordinary cache miss', async () => {
+ let readCount = 0;
+ host.readQuery = async (args) => {
+ host.reads.push({ opKey: args.opKey, query: args.query });
+ readCount += 1;
+ if (readCount === 1) {
+ throw Object.assign(new Error('old owner lost'), {
+ errorCode: 'owner-epoch-lost',
+ });
+ }
+ return { kind: 'miss' };
+ };
+ const { ops, network, forwarded, client } = controlledQueryHarness(host);
+ ops.next(makeOp(44));
+ await tick();
+ network.next({
+ operation: forwarded[0]!,
+ data: undefined,
+ error: undefined,
+ extensions: undefined,
+ stale: false,
+ hasNext: false,
+ });
+ await tick();
+
+ host.pushAffected([44]);
+ await tick();
+ expect(client.reexecuteOperation).toHaveBeenCalledOnce();
+ expect(
+ vi.mocked(client.reexecuteOperation).mock.calls[0]?.[0]?.context
+ .normalizedCacheReplacementRegistrationOnly
+ ).toBe(true);
+ expect(host.reads).toHaveLength(2);
+ expect(forwarded).toHaveLength(1);
+
+ host.pushAffected([44]);
+ await tick();
+ expect(client.reexecuteOperation).toHaveBeenCalledTimes(2);
+ expect(
+ vi.mocked(client.reexecuteOperation).mock.calls[1]?.[0]?.context
+ .normalizedCacheReplacementRegistrationOnly
+ ).toBe(false);
+ expect(host.reads).toHaveLength(3);
+ expect(forwarded).toHaveLength(2);
+ });
+
+ it('drops retained replacement payload on teardown', async () => {
+ host.readQuery = async (args) => {
+ host.reads.push({ opKey: args.opKey, query: args.query });
+ throw Object.assign(new Error('old owner lost'), {
+ errorCode: 'owner-epoch-lost',
+ });
+ };
+ host.writeQuery = vi
+ .fn()
+ .mockRejectedValue(new Error('replacement init not ready'));
+ const { ops, network, forwarded, client } = controlledQueryHarness(host);
+ const op = makeOp(45);
+ ops.next(op);
+ await tick();
+ network.next({
+ operation: forwarded[0]!,
+ data: { from: 'network' },
+ error: undefined,
+ extensions: undefined,
+ stale: false,
+ hasNext: false,
+ });
+ await tick();
+
+ ops.next(teardownOf(op));
+ await tick();
+ host.pushAffected([45]);
+ await tick();
+
+ expect(host.writeQuery).toHaveBeenCalledOnce();
+ expect(host.reads).toHaveLength(1);
+ expect(client.reexecuteOperation).not.toHaveBeenCalled();
+ expect(forwarded).toHaveLength(2);
+ expect(forwarded[1]?.kind).toBe('teardown');
+ });
+
+ it('reexecutes an old rejected cache-only read without forwarding the API', async () => {
+ let readCount = 0;
+ host.readQuery = async (args) => {
+ host.reads.push({ opKey: args.opKey, query: args.query });
+ readCount += 1;
+ if (readCount === 1) {
+ throw Object.assign(new Error('old owner lost'), {
+ errorCode: 'owner-epoch-lost',
+ });
+ }
+ return { kind: 'miss' };
+ };
+ const { ops, forwarded, client } = controlledQueryHarness(host);
+ ops.next(makeOp(44, 'cache-only'));
+ await tick();
+
+ host.pushAffected([44]);
+ await tick();
+
+ expect(client.reexecuteOperation).toHaveBeenCalledOnce();
+ const reissued = vi.mocked(client.reexecuteOperation).mock.calls[0]?.[0];
+ expect(reissued?.context.requestPolicy).toBe('cache-only');
+ expect(forwarded).toHaveLength(0);
+ expect(host.reads).toHaveLength(2);
+ });
+
it('teardown unregisters the op with the host and stops re-execution', async () => {
const { ops, client } = harness(host);
const op = makeOp(7);
@@ -1041,6 +1415,133 @@ describe('normalizedCacheExchange', () => {
expect(results[0]?.data).toEqual({ from: 'network' });
});
+ it('does not forward an admitted enqueue rejected by pagehide uncertainty', async () => {
+ host.enqueueOptimisticMutation = vi.fn().mockRejectedValue(
+ Object.assign(new Error('pagehide abruptly disposed the host'), {
+ errorCode: ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE,
+ })
+ );
+ const { ops, results, forwarded } = harness(host);
+
+ ops.next(makeMutationOp(1, optimistic));
+ await tick();
+
+ expect(forwarded).toHaveLength(0);
+ expect(results).toHaveLength(1);
+ expect(results[0]?.error?.networkError).toMatchObject({
+ errorCode: 'admitted-enqueue-uncertain',
+ });
+ });
+
+ it('keeps a standby enqueue off the API while graceful disposal waits for its response', async () => {
+ const enqueue = host.enqueueOptimisticMutation.bind(host);
+ let releaseResponse!: () => void;
+ const responseGate = new Promise<void>((resolve) => {
+ releaseResponse = resolve;
+ });
+ host.enqueueOptimisticMutation = async (args, claim) => {
+ await responseGate;
+ return {
+ ...(await enqueue(args, claim)),
+ initialClaim: { kind: 'not-runnable' },
+ };
+ };
+ const { ops, results, forwarded } = harness(host);
+
+ ops.next(makeMutationOp(1, optimistic));
+ await tick();
+ host.dispose();
+ expect(forwarded).toHaveLength(0);
+ expect(results).toHaveLength(0);
+ releaseResponse();
+ await tick();
+
+ expect(forwarded).toHaveLength(0);
+ expect(optimisticMutationDispositionOf(results[0])).toEqual({
+ kind: 'queued',
+ transactionId: 'txn-1',
+ });
+ });
+
+ it('does not forward when graceful disposal sees transport failure while waiting', async () => {
+ let rejectResponse!: (error: Error) => void;
+ host.enqueueOptimisticMutation = vi.fn(
+ async () =>
+ await new Promise<EnqueueOptimisticMutationResult>(
+ (_resolve, reject) => {
+ rejectResponse = reject;
+ }
+ )
+ );
+ const { ops, results, forwarded } = harness(host);
+ ops.next(makeMutationOp(1, optimistic));
+ await tick();
+ host.dispose();
+ expect(forwarded).toHaveLength(0);
+
+ rejectResponse(
+ Object.assign(new Error('transport failed during graceful wait'), {
+ errorCode: ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE,
+ })
+ );
+ await tick();
+
+ expect(forwarded).toHaveLength(0);
+ expect(results[0]?.error?.networkError).toMatchObject({
+ errorCode: 'admitted-enqueue-uncertain',
+ });
+ });
+
+ it('does not forward or retry an admitted enqueue after multi-tab transport uncertainty', async () => {
+ const oldScopeQueue: unknown[] = [];
+ const enqueueAttempts = vi.fn(
+ async (args: Parameters<CacheHost['enqueueOptimisticMutation']>[0]) => {
+ // A second tab could observe this durable side effect even though this
+ // tab lost the SharedWorker response immediately afterward.
+ oldScopeQueue.push(args.data);
+ throw Object.assign(new Error('old-scope transport failed'), {
+ errorCode: ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE,
+ });
+ }
+ );
+ host.enqueueOptimisticMutation = enqueueAttempts;
+ const secondTabObservedQueue = (): unknown[] => [...oldScopeQueue];
+ const onCacheError = vi.fn();
+ const { ops, results, forwarded } = harness(host, undefined, {
+ onCacheError,
+ });
+ const base = makeMutationOp(1, optimistic);
+ const operation = makeOperation(base.kind, base, {
+ ...base.context,
+ normalizedCacheOptimistic: {
+ optimisticResponse: optimistic,
+ linkPatches: [
+ {
+ query: 'query CachedList { cachedList { id } }',
+ variablesJson: '{}',
+ path: [{ field: 'cachedList' }],
+ operation: { kind: 'remove', entityKey: 'Item:1' },
+ },
+ ],
+ revalidations: [],
+ },
+ });
+
+ ops.next(operation);
+ await tick();
+
+ expect(secondTabObservedQueue()).toEqual([optimistic]);
+ expect(enqueueAttempts).toHaveBeenCalledOnce();
+ expect(forwarded).toHaveLength(0);
+ expect(results).toHaveLength(1);
+ expect(results[0]?.data).toBeUndefined();
+ expect(results[0]?.error?.networkError).toMatchObject({
+ message: 'old-scope transport failed',
+ errorCode: 'admitted-enqueue-uncertain',
+ });
+ expect(onCacheError).toHaveBeenCalledOnce();
+ });
+
it('replays an older returned claim and reports the new caller as queued', async () => {
host.seedQueued({
query: stringifyDocument(MUTATION),
diff --git a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.ts b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.ts
index a18dab2440..4f48e612a7 100644
--- a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.ts
+++ b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.ts
@@ -26,11 +26,13 @@
* - Without one: forwarded normally; successful responses are normalized
* through the standard write path so dependent cached queries update.
*
- * Cache failures are never fatal: any host error degrades to the network.
+ * Cache failures normally degrade to the network. An admitted optimistic
+ * enqueue with an unfenced transport outcome emits an error instead, because
+ * forwarding could duplicate a side effect already durable in the old scope.
*/
import {
- type CombinedError,
+ CombinedError,
type Exchange,
makeOperation,
type Operation,
@@ -58,10 +60,12 @@ import {
tap,
} from 'wonka';
import type { CacheHost } from '../host/types';
-import type {
- ClaimedMutation,
- EnqueueOptimisticMutationResult,
- QueryRevalidationWire,
+import {
+ type ClaimedMutation,
+ type EnqueueOptimisticMutationResult,
+ isAdmittedEnqueueUncertainError,
+ isOwnerEpochLostError,
+ type QueryRevalidationWire,
} from '../protocol';
import {
compileEntityResolvers,
@@ -82,6 +86,9 @@ import {
const QUEUE_ATTEMPT_CONTEXT_KEY = 'normalizedCacheQueueAttempt';
/** Marks dependency-pushed reads as latency-sensitive worker work. */
const AFFECTED_READ_CONTEXT_KEY = 'normalizedCacheAffectedRead';
+/** Prevents a post-network dependency refresh from forwarding the API again. */
+const REPLACEMENT_REGISTRATION_ONLY_CONTEXT_KEY =
+ 'normalizedCacheReplacementRegistrationOnly';
const QUEUE_REQUEST_TIMEOUT_MS = 60_000;
const QUEUE_LEASE_MS = 5 * 60_000;
const EMPTY_QUEUE_POLL_MS = 30_000;
@@ -269,6 +276,17 @@ function operationCacheEffects(data: unknown): CacheEffect[] {
);
}
+function uncertainEnqueueResult(op: Operation, error: Error): OperationResult {
+ return {
+ operation: op,
+ data: undefined,
+ error: new CombinedError({ networkError: error }),
+ extensions: undefined,
+ stale: false,
+ hasNext: false,
+ };
+}
+
function queuedMutationResult(
op: Operation,
transactionId: string
@@ -289,7 +307,7 @@ function queuedMutationResult(
export interface NormalizedCacheExchangeOptions {
/** Schema-typed singular entity relations derived from field arguments. */
entityResolvers?: EntityResolverConfig;
- /** Called when a cache read/write fails (diagnostics; flow already degraded to network). */
+ /** Called when cache work fails; the operation may degrade or emit uncertainty. */
onCacheError?: (error: unknown, op: Operation) => void;
/**
* Extracts the session identity (e.g. viewer id, `data.user.id`) from a
@@ -322,20 +340,200 @@ export function normalizedCacheExchange(
* later optimistic entity writes can affect the active operation.
*/
const dependencyRefreshOps = new Set<number>();
+ type RetainedReplacementFallback = {
+ version: number;
+ writeArgs: Parameters<CacheHost['writeQuery']>[0];
+ readyPending: boolean;
+ recovering: boolean;
+ invalidated: boolean;
+ recoveryPromise?: Promise<void>;
+ };
+ type QueryState = {
+ networkBoundQueries: number;
+ replacementFallback: boolean;
+ deferredAffected: boolean;
+ completedReplacementFallback: boolean;
+ networkRegistrationSatisfied: boolean;
+ retainedReplacementFallback?: RetainedReplacementFallback;
+ networkResultVersion: number;
+ queryResultTurn?: Promise<void>;
+ };
+ const queryStates = new Map<number, QueryState>();
+ const queryState = (key: number): QueryState => {
+ let state = queryStates.get(key);
+ if (!state) {
+ state = {
+ networkBoundQueries: 0,
+ replacementFallback: false,
+ deferredAffected: false,
+ completedReplacementFallback: false,
+ networkRegistrationSatisfied: false,
+ networkResultVersion: 0,
+ };
+ queryStates.set(key, state);
+ }
+ return state;
+ };
+
+ const acquireQueryResultTurn = async (key: number): Promise<() => void> => {
+ const state = queryState(key);
+ const previous = state.queryResultTurn ?? Promise.resolve();
+ let release!: () => void;
+ const current = new Promise<void>((resolve) => {
+ release = resolve;
+ });
+ state.queryResultTurn = current;
+ await previous;
+ return () => {
+ release();
+ if (
+ queryStates.get(key) === state &&
+ state.queryResultTurn === current
+ ) {
+ state.queryResultTurn = undefined;
+ }
+ };
+ };
+
+ const invalidateOlderRetainedFallback = async (
+ key: number,
+ version: number
+ ): Promise<void> => {
+ while (true) {
+ const state = queryStates.get(key);
+ const retained = state?.retainedReplacementFallback;
+ if (!state || !retained || retained.version >= version) return;
+ retained.invalidated = true;
+ retained.readyPending = false;
+ if (retained.recoveryPromise) {
+ // Keep the exact in-flight candidate addressable until its cache
+ // attempt settles; the newer result must write strictly after it.
+ await retained.recoveryPromise;
+ }
+ if (state.retainedReplacementFallback === retained) {
+ state.retainedReplacementFallback = undefined;
+ }
+ }
+ };
+
+ const reexecuteAffected = (key: number, registrationOnly = false): void => {
+ const op = activeOps.get(key);
+ if (!op) return;
+ client.reexecuteOperation(
+ makeOperation(op.kind, op, {
+ ...op.context,
+ requestPolicy:
+ op.context.requestPolicy === 'cache-only'
+ ? 'cache-only'
+ : 'cache-first',
+ [AFFECTED_READ_CONTEXT_KEY]: true,
+ // activeOps observes every reissued operation. Explicitly clear the
+ // one-shot marker so a later ordinary invalidation can reach the API.
+ [REPLACEMENT_REGISTRATION_ONLY_CONTEXT_KEY]: registrationOnly,
+ })
+ );
+ };
+
+ const recoverRetainedReplacementFallback = (key: number): void => {
+ const state = queryStates.get(key);
+ const retained = state?.retainedReplacementFallback;
+ if (!state || !retained || retained.invalidated || !activeOps.has(key))
+ return;
+ retained.readyPending = true;
+ if (retained.recovering || state.networkBoundQueries > 0) return;
+ retained.recovering = true;
+ const recovery = (async () => {
+ while (
+ queryStates.get(key) === state &&
+ state.retainedReplacementFallback === retained &&
+ !retained.invalidated &&
+ retained.readyPending
+ ) {
+ retained.readyPending = false;
+ try {
+ await host.writeQuery(retained.writeArgs);
+ if (
+ queryStates.get(key) !== state ||
+ state.retainedReplacementFallback !== retained ||
+ retained.invalidated ||
+ !activeOps.has(key)
+ ) {
+ return;
+ }
+ // Register the complete normalized dependency set directly. This
+ // cannot enqueue another API request or replay the old cache RPC.
+ await host.readQuery({
+ opKey: retained.writeArgs.opKey,
+ query: retained.writeArgs.query,
+ operationName: retained.writeArgs.operationName,
+ variables: retained.writeArgs.variables,
+ entityResolvers: retained.writeArgs.entityResolvers,
+ });
+ if (
+ queryStates.get(key) !== state ||
+ state.retainedReplacementFallback !== retained ||
+ retained.invalidated
+ ) {
+ return;
+ }
+ state.retainedReplacementFallback = undefined;
+ dependencyRefreshOps.delete(key);
+ state.replacementFallback = false;
+ state.deferredAffected = false;
+ state.completedReplacementFallback = false;
+ state.networkRegistrationSatisfied = false;
+ return;
+ } catch (error) {
+ if (
+ queryStates.get(key) !== state ||
+ state.retainedReplacementFallback !== retained ||
+ retained.invalidated
+ ) {
+ return;
+ }
+ const active = activeOps.get(key);
+ if (active) options.onCacheError?.(error, active);
+ // Preserve the successful payload for a later replacement-ready
+ // notification. A notification received during this attempt sets
+ // readyPending and safely drives exactly one subsequent attempt.
+ }
+ }
+ })().catch(() => undefined);
+ retained.recoveryPromise = recovery;
+ void recovery.then(() => {
+ if (retained.recoveryPromise === recovery) {
+ retained.recoveryPromise = undefined;
+ }
+ if (
+ queryStates.get(key) !== state ||
+ state.retainedReplacementFallback !== retained
+ )
+ return;
+ retained.recovering = false;
+ if (retained.invalidated) {
+ state.retainedReplacementFallback = undefined;
+ } else if (retained.readyPending) {
+ recoverRetainedReplacementFallback(key);
+ }
+ });
+ };
const unsubscribePush = host.onOpsAffected((opKeys) => {
for (const key of opKeys) {
- const op = activeOps.get(key);
- if (!op) continue;
- // Re-read from cache; do not stampede the network (graphcache does
- // the same downgrade on dependency-driven re-execution).
- client.reexecuteOperation(
- makeOperation(op.kind, op, {
- ...op.context,
- requestPolicy: 'cache-first',
- [AFFECTED_READ_CONTEXT_KEY]: true,
- })
- );
+ if (!activeOps.has(key)) continue;
+ const state = queryState(key);
+ if (state.networkBoundQueries > 0) {
+ state.deferredAffected = true;
+ continue;
+ }
+ const registrationOnly = state.completedReplacementFallback;
+ state.completedReplacementFallback = false;
+ state.replacementFallback = false;
+ if (state.retainedReplacementFallback) {
+ recoverRetainedReplacementFallback(key);
+ continue;
+ }
+ reexecuteAffected(key, registrationOnly);
}
});
@@ -345,6 +543,44 @@ export function normalizedCacheExchange(
// Async cache reads re-inject network-bound operations here.
const { source: forwardQueue$, next: enqueueForward } =
makeSubject<Operation>();
+
+ const enqueueQueryForward = (op: Operation): void => {
+ queryState(op.key).networkBoundQueries += 1;
+ enqueueForward(op);
+ };
+
+ const finishNetworkQuery = (
+ key: number,
+ replacementRegistrationSatisfied: boolean
+ ): void => {
+ const state = queryState(key);
+ const remaining = state.networkBoundQueries - 1;
+ if (remaining > 0) {
+ state.networkBoundQueries = remaining;
+ return;
+ }
+ state.networkBoundQueries = 0;
+ const deferred = state.deferredAffected;
+ state.deferredAffected = false;
+ const replacementFallback = state.replacementFallback;
+ state.replacementFallback = false;
+ if (deferred) {
+ state.completedReplacementFallback = false;
+ if (!replacementRegistrationSatisfied) {
+ if (state.retainedReplacementFallback) {
+ recoverRetainedReplacementFallback(key);
+ } else {
+ reexecuteAffected(key, true);
+ }
+ }
+ } else if (replacementFallback) {
+ // A fast fallback completed before replacement initialization. The
+ // later affected notification must register cache dependencies but
+ // must not issue the API request a second time.
+ state.completedReplacementFallback = true;
+ }
+ };
+
const queueOwner = `exchange:${host.clientId}`;
const liveQueuedOps = new Map<
string,
@@ -511,7 +747,7 @@ export function normalizedCacheExchange(
const policy = op.context.requestPolicy;
if (policy === 'network-only') {
dependencyRefreshOps.add(op.key);
- enqueueForward(op);
+ enqueueQueryForward(op);
return undefined;
}
try {
@@ -528,7 +764,7 @@ export function normalizedCacheExchange(
});
if (read.kind === 'hit') {
const stale = policy === 'cache-and-network';
- if (stale) enqueueForward(op);
+ if (stale) enqueueQueryForward(op);
return cacheResult(op, read.data, stale);
}
if (policy === 'cache-only') {
@@ -537,13 +773,19 @@ export function normalizedCacheExchange(
dependencyRefreshOps.add(op.key);
} catch (error) {
options.onCacheError?.(error, op);
+ if (isOwnerEpochLostError(error)) {
+ queryState(op.key).replacementFallback = true;
+ }
// `cache-only` must never touch the network, even when the cache
// itself fails — degrade to an empty result instead.
if (policy === 'cache-only') {
return cacheResult(op, undefined, false);
}
}
- enqueueForward(op);
+ if (op.context[REPLACEMENT_REGISTRATION_ONLY_CONTEXT_KEY] === true) {
+ return undefined;
+ }
+ enqueueQueryForward(op);
return undefined;
}
@@ -583,15 +825,19 @@ export function normalizedCacheExchange(
try {
enqueue = await host.enqueueOptimisticMutation(args, claim);
} catch (error) {
+ options.onCacheError?.(error, op);
+ if (isAdmittedEnqueueUncertainError(error)) {
+ // The old-scope queue may already contain the side effect. It is
+ // unsafe to forward or retry without a coordinator fence.
+ return uncertainEnqueueResult(op, error);
+ }
// A cached bin/page may disappear between inspect and enqueue. Do
// not expose a partial relation move: retain entity optimism and
// the post-success revalidation descriptors instead.
if (args.linkPatches.length === 0) {
- options.onCacheError?.(error, op);
enqueueForward(op);
return undefined;
}
- options.onCacheError?.(error, op);
try {
enqueue = await host.enqueueOptimisticMutation(
{
@@ -610,6 +856,9 @@ export function normalizedCacheExchange(
);
} catch (fallbackError) {
options.onCacheError?.(fallbackError, op);
+ if (isAdmittedEnqueueUncertainError(fallbackError)) {
+ return uncertainEnqueueResult(op, fallbackError);
+ }
enqueueForward(op);
return undefined;
}
@@ -692,28 +941,74 @@ export function normalizedCacheExchange(
subscriptionEffectChains.delete(op.key);
}
}
- } else if (op.kind === 'query' && result.data != null) {
+ } else if (op.kind === 'query') {
+ const releaseTurn = await acquireQueryResultTurn(op.key);
try {
- const args = {
- opKey: op.key,
- query: queryText(op),
- operationName: operationName(op),
- variables: op.variables as Record<string, unknown> | undefined,
- entityResolvers,
- };
- await host.writeQuery({
- ...args,
- data: result.data,
- identity: options.extractIdentity?.(result.data),
- });
- if (dependencyRefreshOps.delete(op.key) && activeOps.has(op.key)) {
- // A miss only records dependencies reached before the missing
- // record. Re-read the now-populated query to register its full
- // entity graph for push-driven optimistic updates.
- await host.readQuery(args);
+ const state = queryState(op.key);
+ const resultVersion = state.networkResultVersion + 1;
+ state.networkResultVersion = resultVersion;
+ // Every newer result supersedes an older retained payload, even an
+ // error or intermediate streamed result with no cache write.
+ await invalidateOlderRetainedFallback(op.key, resultVersion);
+ if (result.data != null) {
+ const readArgs = {
+ opKey: op.key,
+ query: queryText(op),
+ operationName: operationName(op),
+ variables: op.variables as Record<string, unknown> | undefined,
+ entityResolvers,
+ };
+ const writeArgs = {
+ ...readArgs,
+ data: result.data,
+ identity: options.extractIdentity?.(result.data),
+ };
+ const retained: RetainedReplacementFallback | undefined =
+ result.error === undefined &&
+ result.hasNext !== true &&
+ activeOps.has(op.key) &&
+ state.replacementFallback
+ ? {
+ version: resultVersion,
+ writeArgs,
+ readyPending: false,
+ recovering: false,
+ invalidated: false,
+ }
+ : undefined;
+ if (retained) {
+ // Install before the first write: replacement-ready pushes can
+ // arrive synchronously while the cache attempt is settling.
+ state.retainedReplacementFallback = retained;
+ }
+ try {
+ await host.writeQuery(writeArgs);
+ if (
+ activeOps.has(op.key) &&
+ (dependencyRefreshOps.has(op.key) || state.deferredAffected)
+ ) {
+ // A miss or replacement fallback needs one successful read
+ // on the current generation after network write-through.
+ await host.readQuery(readArgs);
+ dependencyRefreshOps.delete(op.key);
+ state.networkRegistrationSatisfied = true;
+ }
+ if (state.retainedReplacementFallback === retained) {
+ state.retainedReplacementFallback = undefined;
+ }
+ } catch (error) {
+ options.onCacheError?.(error, op);
+ }
}
- } catch (error) {
- options.onCacheError?.(error, op);
+ if (result.hasNext !== true) {
+ dependencyRefreshOps.delete(op.key);
+ const registrationSatisfied = state.networkRegistrationSatisfied;
+ state.networkRegistrationSatisfied = false;
+ finishNetworkQuery(op.key, registrationSatisfied);
+ }
+ } finally {
+ if (!activeOps.has(op.key)) queryStates.delete(op.key);
+ releaseTurn();
}
} else if (op.kind === 'mutation') {
const attempt = queueAttemptOf(op);
@@ -852,6 +1147,7 @@ export function normalizedCacheExchange(
if (op.kind === 'teardown') {
activeOps.delete(op.key);
dependencyRefreshOps.delete(op.key);
+ queryStates.delete(op.key);
host.teardown(op.key).catch(() => undefined);
}
})
diff --git a/apps/web/src/lib/graphql-cache/host/types.ts b/apps/web/src/lib/graphql-cache/host/types.ts
index 8e2f2ac8b4..e9125f5ad1 100644
--- a/apps/web/src/lib/graphql-cache/host/types.ts
+++ b/apps/web/src/lib/graphql-cache/host/types.ts
@@ -1,7 +1,8 @@
/**
* Transport-agnostic cache host interface consumed by the urql exchange and
* imperative writers (websocket handlers). Implementations:
- * - worker-host.ts: browser (SharedWorker + wasm engine, or no-op fallback)
+ * - worker-host.ts: browser (SharedWorker coordinator + elected WASM engine,
+ * or no-op fallback)
* - tauri-host.ts (Phase 3b): Tauri IPC to the native engine
*/
@@ -72,7 +73,7 @@ export interface InitialMutationClaimArgs {
export interface CacheHost {
/** Stable id of this context; used to namespace operation ids. */
readonly clientId: string;
- /** True for the storage-free fallback used without SharedWorker support. */
+ /** True for the storage-free fallback when browser cache APIs are unsupported. */
readonly disabled?: boolean;
readQuery(args: CacheReadArgs): Promise<ReadResult>;
diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.integration.test.ts b/apps/web/src/lib/graphql-cache/host/worker-host.integration.test.ts
new file mode 100644
index 0000000000..ce2a6a4e4a
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/host/worker-host.integration.test.ts
@@ -0,0 +1,617 @@
+import {
+ type Client,
+ gql,
+ makeOperation,
+ type Operation,
+ type OperationResult,
+} from '@urql/core';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { makeSubject, pipe, type Source, subscribe } from 'wonka';
+import { normalizedCacheExchange } from '../exchange/normalized-cache-exchange';
+import type { CacheRequest, CacheResponse } from '../protocol';
+import { installCacheEngineWorker } from '../worker/cache-engine-runtime';
+import {
+ type CoordinatorMessagePort,
+ CoordinatorRouter,
+} from '../worker/coordinator-router';
+import type { CacheHost } from './types';
+import { createWorkerCacheHost } from './worker-host';
+
+const PAGEHIDE_MUTATION = gql`
+ mutation HoldPagehide {
+ holdPagehide
+ }
+`;
+const STANDBY_MUTATION = gql`
+ mutation HoldStandby {
+ holdStandby
+ }
+`;
+const RETIREMENT_FAILURE_MUTATION = gql`
+ mutation HoldRetirementFailure {
+ holdRetirementFailure
+ }
+`;
+
+function exchangeHarness(host: CacheHost, operation: Operation) {
+ const operations = makeSubject<Operation>();
+ const network = makeSubject<OperationResult>();
+ const forwarded: Operation[] = [];
+ const results: OperationResult[] = [];
+ const client = { reexecuteOperation: vi.fn() } as unknown as Client;
+ const forward = (source: Source<Operation>): Source<OperationResult> => {
+ pipe(
+ source,
+ subscribe((forwardedOperation) => forwarded.push(forwardedOperation))
+ );
+ return network.source;
+ };
+ pipe(
+ normalizedCacheExchange(host)({
+ forward,
+ client,
+ dispatchDebug: () => undefined,
+ })(operations.source),
+ subscribe((result) => results.push(result))
+ );
+ operations.next(operation);
+ return { forwarded, results };
+}
+
+function optimisticMutation(key: number, query: Operation['query']): Operation {
+ return makeOperation('mutation', { key, query, variables: {} }, {
+ requestPolicy: 'cache-first',
+ url: 'http://integration.test',
+ suspense: false,
+ normalizedCacheOptimistic: {
+ optimisticResponse: { held: true },
+ },
+ } as never);
+}
+
+class LinkedMessagePort {
+ peer: LinkedMessagePort | undefined;
+ onmessage: ((event: MessageEvent<unknown>) => void) | null = null;
+ onmessageerror: (() => void) | null = null;
+ closed = false;
+
+ postMessage(message: unknown, transfer: Transferable[] = []): void {
+ const peer = this.peer;
+ if (this.closed || !peer || peer.closed) return;
+ queueMicrotask(() => {
+ if (peer.closed) return;
+ peer.onmessage?.({
+ data: message,
+ ports: transfer,
+ } as unknown as MessageEvent);
+ });
+ }
+
+ start(): void {}
+
+ close(): void {
+ this.closed = true;
+ }
+}
+
+class LinkedMessageChannel {
+ readonly port1 = new LinkedMessagePort();
+ readonly port2 = new LinkedMessagePort();
+
+ constructor() {
+ this.port1.peer = this.port2;
+ this.port2.peer = this.port1;
+ }
+}
+
+type RuntimeLog = {
+ epoch: number;
+ kind: CacheRequest['kind'] | 'drain';
+ id?: number;
+ query?: string;
+};
+
+type Deferred = { promise: Promise<void>; resolve: () => void };
+const deferred = (): Deferred => {
+ let resolve!: () => void;
+ const promise = new Promise<void>((settle) => {
+ resolve = settle;
+ });
+ return { promise, resolve };
+};
+
+class IntegrationCore {
+ constructor(
+ private readonly epoch: number,
+ private readonly logs: RuntimeLog[],
+ private readonly activationGates: Map<number, Promise<void>>,
+ private readonly hostInitGates: Map<number, Promise<void>>,
+ private readonly enqueueGates: Map<string, Promise<void>>
+ ) {}
+
+ addPort(): void {}
+
+ async handleRequest(
+ port: { postMessage(message: unknown): void },
+ request: CacheRequest
+ ): Promise<void> {
+ this.logs.push({
+ epoch: this.epoch,
+ kind: request.kind,
+ id: request.id,
+ query: 'query' in request ? request.query : undefined,
+ });
+ if (request.kind === 'init') {
+ const gate =
+ request.id === 0
+ ? this.activationGates.get(this.epoch)
+ : this.hostInitGates.get(this.epoch);
+ if (gate) await gate;
+ }
+ if (request.kind === 'read' && request.query.includes('Slow')) {
+ await new Promise<void>(() => undefined);
+ return;
+ }
+ if (request.kind === 'enqueue-optimistic-mutation') {
+ const gate = this.enqueueGates.get(request.operationName ?? '');
+ if (gate) await gate;
+ }
+ let result: unknown = null;
+ if (request.kind === 'read') result = { kind: 'miss' };
+ if (request.kind === 'enqueue-optimistic-mutation') {
+ result = {
+ transactionId: `integration-${request.id}`,
+ changed: [],
+ affectedOps: [],
+ reset: false,
+ initialClaim: { kind: 'not-runnable' },
+ };
+ }
+ const response: CacheResponse = { id: request.id, ok: true, result };
+ port.postMessage(response);
+ }
+
+ async drain(): Promise<void> {
+ this.logs.push({ epoch: this.epoch, kind: 'drain' });
+ }
+}
+
+class IntegrationWorkerScope {
+ onmessage: ((event: MessageEvent<unknown>) => void) | null = null;
+ closed = false;
+
+ close(): void {
+ this.closed = true;
+ }
+}
+
+class IntegrationDedicatedWorker {
+ onerror: ((this: AbstractWorker, event: ErrorEvent) => unknown) | null = null;
+ onmessageerror: ((this: Worker, event: MessageEvent) => unknown) | null =
+ null;
+ readonly scope = new IntegrationWorkerScope();
+ terminated = false;
+
+ constructor(
+ readonly epoch: number,
+ logs: RuntimeLog[],
+ activationGates: Map<number, Promise<void>>,
+ hostInitGates: Map<number, Promise<void>>,
+ enqueueGates: Map<string, Promise<void>>
+ ) {
+ installCacheEngineWorker({
+ scope: this.scope,
+ createCore: () =>
+ new IntegrationCore(
+ epoch,
+ logs,
+ activationGates,
+ hostInitGates,
+ enqueueGates
+ ),
+ ownerLockIsHeld: async () => true,
+ });
+ }
+
+ postMessage(message: unknown, transfer: Transferable[]): void {
+ this.scope.onmessage?.({
+ data: message,
+ ports: transfer,
+ } as unknown as MessageEvent);
+ }
+
+ terminate(): void {
+ this.terminated = true;
+ }
+
+ fail(message: string): void {
+ this.onerror?.call(
+ {} as AbstractWorker,
+ { message, preventDefault: vi.fn() } as unknown as ErrorEvent
+ );
+ }
+}
+
+class IntegrationSharedWorker {
+ onerror: ((this: AbstractWorker, event: ErrorEvent) => unknown) | null = null;
+ readonly port: LinkedMessagePort;
+
+ constructor(router: CoordinatorRouter) {
+ const channel = new LinkedMessageChannel();
+ this.port = channel.port1;
+ router.connect(channel.port2 as unknown as CoordinatorMessagePort);
+ }
+
+ fail(message: string): void {
+ this.onerror?.call(
+ {} as AbstractWorker,
+ { message, preventDefault: vi.fn() } as unknown as ErrorEvent
+ );
+ }
+}
+
+describe('worker CacheHost coordinator integration', () => {
+ const logs: RuntimeLog[] = [];
+ const dedicatedWorkers: IntegrationDedicatedWorker[] = [];
+ const sharedWorkers: IntegrationSharedWorker[] = [];
+ const activationGates = new Map<number, Promise<void>>();
+ const hostInitGates = new Map<number, Promise<void>>();
+ const enqueueGates = new Map<string, Promise<void>>();
+
+ beforeEach(() => {
+ localStorage.clear();
+ logs.length = 0;
+ dedicatedWorkers.length = 0;
+ sharedWorkers.length = 0;
+ activationGates.clear();
+ hostInitGates.clear();
+ enqueueGates.clear();
+ const router = new CoordinatorRouter({
+ verifyTabLockHeld: async () => true,
+ watchTabLock: () => () => undefined,
+ });
+ vi.stubGlobal('MessageChannel', LinkedMessageChannel);
+ vi.stubGlobal(
+ 'SharedWorker',
+ class {
+ onerror: IntegrationSharedWorker['onerror'] = null;
+ readonly port: LinkedMessagePort;
+
+ constructor() {
+ const worker = new IntegrationSharedWorker(router);
+ sharedWorkers.push(worker);
+ this.port = worker.port;
+ Object.defineProperty(this, 'onerror', {
+ get: () => worker.onerror,
+ set: (value) => {
+ worker.onerror = value;
+ },
+ });
+ }
+ }
+ );
+ vi.stubGlobal(
+ 'Worker',
+ class {
+ readonly delegate: IntegrationDedicatedWorker;
+
+ constructor(_url: URL, options?: WorkerOptions) {
+ const epoch = Number(options?.name?.split(':').at(-1));
+ this.delegate = new IntegrationDedicatedWorker(
+ epoch,
+ logs,
+ activationGates,
+ hostInitGates,
+ enqueueGates
+ );
+ dedicatedWorkers.push(this.delegate);
+ }
+
+ get onerror(): IntegrationDedicatedWorker['onerror'] {
+ return this.delegate.onerror;
+ }
+
+ set onerror(value: IntegrationDedicatedWorker['onerror']) {
+ this.delegate.onerror = value;
+ }
+
+ get onmessageerror(): IntegrationDedicatedWorker['onmessageerror'] {
+ return this.delegate.onmessageerror;
+ }
+
+ set onmessageerror(value: IntegrationDedicatedWorker['onmessageerror'],) {
+ this.delegate.onmessageerror = value;
+ }
+
+ postMessage(message: unknown, transfer: Transferable[]): void {
+ this.delegate.postMessage(message, transfer);
+ }
+
+ terminate(): void {
+ this.delegate.terminate();
+ }
+ }
+ );
+ vi.stubGlobal('navigator', {
+ locks: {
+ request: async (
+ name: string,
+ _options: LockOptions,
+ callback: (lock: Lock | null) => unknown
+ ) => await callback({ name, mode: 'exclusive' } as Lock),
+ },
+ storage: { getDirectory: vi.fn() },
+ });
+ });
+
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ vi.restoreAllMocks();
+ });
+
+ it('registers, replaces without replay or duplicate reread, and retires gracefully', async () => {
+ const host = createWorkerCacheHost({
+ scope: 'integration-scope',
+ requestTimeoutMs: 1_000,
+ });
+ const order: string[] = [];
+ let replacementRead: Promise<unknown> | undefined;
+ host.onOpsAffected((keys) => {
+ order.push(`affected:${keys.join(',')}`);
+ replacementRead = host.readQuery({
+ opKey: keys[0],
+ query: 'query Replacement { replacement }',
+ });
+ });
+
+ expect(sharedWorkers).toHaveLength(0);
+ expect(dedicatedWorkers).toHaveLength(0);
+
+ await expect(
+ host.readQuery({ query: 'query Warm { warm }' })
+ ).resolves.toEqual({ kind: 'miss' });
+ await Promise.all([
+ host.readQuery({ opKey: 7, query: 'query RegisteredSeven { seven }' }),
+ host.readQuery({ opKey: 9, query: 'query RegisteredNine { nine }' }),
+ ]);
+ expect(sharedWorkers).toHaveLength(1);
+ expect(dedicatedWorkers.map((worker) => worker.epoch)).toEqual([1]);
+
+ const slowRead = host.readQuery({
+ opKey: 7,
+ query: 'query Slow { slow }',
+ });
+ const slowRejected = expect(slowRead).rejects.toMatchObject({
+ errorCode: 'owner-epoch-lost',
+ });
+ void slowRead.catch(() => order.push('old-request-rejected'));
+ await vi.waitFor(() =>
+ expect(
+ logs.filter(
+ ({ epoch, query }) => epoch === 1 && query?.includes('Slow')
+ )
+ ).toHaveLength(1)
+ );
+
+ dedicatedWorkers[0]?.fail('integration engine loss');
+ await slowRejected;
+ await vi.waitFor(() => expect(order).toContain('affected:7,9'));
+ await vi.waitFor(() => expect(replacementRead).toBeDefined());
+ await expect(replacementRead).resolves.toEqual({ kind: 'miss' });
+
+ expect(order).toEqual(['old-request-rejected', 'affected:7,9']);
+ expect(dedicatedWorkers.map((worker) => worker.epoch)).toEqual([1, 2]);
+ expect(dedicatedWorkers[0]?.terminated).toBe(true);
+ expect(logs.filter(({ query }) => query?.includes('Slow'))).toHaveLength(1);
+ expect(
+ logs.filter(
+ ({ epoch, kind, id }) => epoch === 2 && kind === 'init' && id !== 0
+ )
+ ).toHaveLength(1);
+ expect(
+ logs.filter(
+ ({ epoch, query }) =>
+ epoch === 2 && query === 'query Replacement { replacement }'
+ )
+ ).toHaveLength(1);
+
+ host.dispose();
+ await vi.waitFor(() => expect(dedicatedWorkers[1]?.terminated).toBe(true));
+ expect(logs).toContainEqual({ epoch: 2, kind: 'drain' });
+ expect(sharedWorkers[0]?.port.closed).toBe(true);
+ });
+
+ it('does not duplicate reads queued before or joined during replacement init', async () => {
+ const activationGate = deferred();
+ const hostInitGate = deferred();
+ activationGates.set(2, activationGate.promise);
+ hostInitGates.set(2, hostInitGate.promise);
+ const host = createWorkerCacheHost({
+ scope: 'integration-scope',
+ requestTimeoutMs: 1_000,
+ });
+ const affected: number[][] = [];
+ let replacementRead: Promise<unknown> | undefined;
+ host.onOpsAffected((keys) => {
+ affected.push(keys);
+ replacementRead = host.readQuery({
+ opKey: keys[0],
+ query: 'query UntouchedReplacement { ten }',
+ });
+ });
+ await Promise.all(
+ [8, 9, 10].map((opKey) =>
+ host.readQuery({
+ opKey,
+ query: `query Registered${opKey} { value${opKey} }`,
+ })
+ )
+ );
+
+ // No request from this host is in flight when the owner is lost, so the
+ // host remains ready while the coordinator enters resetting/activating.
+ dedicatedWorkers[0]?.fail('integration engine loss');
+ await vi.waitFor(() =>
+ expect(dedicatedWorkers.map(({ epoch }) => epoch)).toEqual([1, 2])
+ );
+ const queuedBefore = host.readQuery({
+ opKey: 8,
+ query: 'query QueuedBefore { eight }',
+ });
+ expect(
+ logs.filter(
+ ({ epoch, query }) => epoch === 2 && query?.includes('QueuedBefore')
+ )
+ ).toHaveLength(0);
+ activationGate.resolve();
+ await vi.waitFor(() =>
+ expect(
+ logs.filter(
+ ({ epoch, kind, id }) => epoch === 2 && kind === 'init' && id !== 0
+ )
+ ).toHaveLength(1)
+ );
+
+ const joinedDuring = host.readQuery({
+ opKey: 9,
+ query: 'query JoinedDuring { nine }',
+ });
+ hostInitGate.resolve();
+ await expect(queuedBefore).resolves.toEqual({ kind: 'miss' });
+ await expect(joinedDuring).resolves.toEqual({ kind: 'miss' });
+ await vi.waitFor(() => expect(affected).toEqual([[10]]));
+ await vi.waitFor(() => expect(replacementRead).toBeDefined());
+ await expect(replacementRead).resolves.toEqual({ kind: 'miss' });
+
+ expect(
+ logs.filter(
+ ({ epoch, query }) => epoch === 2 && query?.includes('QueuedBefore')
+ )
+ ).toHaveLength(1);
+ expect(
+ logs.filter(
+ ({ epoch, query }) => epoch === 2 && query?.includes('JoinedDuring')
+ )
+ ).toHaveLength(1);
+ expect(
+ logs.filter(
+ ({ epoch, query }) =>
+ epoch === 2 && query?.includes('UntouchedReplacement')
+ )
+ ).toHaveLength(1);
+ host.dispose();
+ });
+
+ it('keeps API forwarding at zero when pagehide abandons an admitted enqueue', async () => {
+ const gate = deferred();
+ enqueueGates.set('HoldPagehide', gate.promise);
+ localStorage.setItem('graphql-cache:scope', 'integration-scope');
+ const host = createWorkerCacheHost({ scope: 'integration-scope' });
+ const { forwarded, results } = exchangeHarness(
+ host,
+ optimisticMutation(101, PAGEHIDE_MUTATION)
+ );
+ await vi.waitFor(() =>
+ expect(
+ logs.filter(
+ ({ kind, query }) =>
+ kind === 'enqueue-optimistic-mutation' &&
+ query?.includes('HoldPagehide')
+ )
+ ).toHaveLength(1)
+ );
+
+ dispatchEvent(new Event('pagehide'));
+ await vi.waitFor(() => expect(results).toHaveLength(1));
+
+ expect(forwarded).toHaveLength(0);
+ expect(results[0]?.error?.networkError).toMatchObject({
+ errorCode: 'admitted-enqueue-uncertain',
+ });
+ await vi.waitFor(() =>
+ expect(localStorage.getItem('graphql-cache:scope')).toBe(
+ 'quarantine:integration-scope'
+ )
+ );
+ });
+
+ it('keeps a standby connected until its admitted enqueue response settles', async () => {
+ const owner = createWorkerCacheHost({ scope: 'integration-scope' });
+ await owner.readQuery({ query: 'query OwnerWarm { ownerWarm }' });
+ const gate = deferred();
+ enqueueGates.set('HoldStandby', gate.promise);
+ const standby = createWorkerCacheHost({ scope: 'integration-scope' });
+ const { forwarded, results } = exchangeHarness(
+ standby,
+ optimisticMutation(102, STANDBY_MUTATION)
+ );
+ await vi.waitFor(() =>
+ expect(
+ logs.filter(
+ ({ kind, query }) =>
+ kind === 'enqueue-optimistic-mutation' &&
+ query?.includes('HoldStandby')
+ )
+ ).toHaveLength(1)
+ );
+
+ standby.dispose();
+ expect(sharedWorkers[1]?.port.closed).toBe(false);
+ gate.resolve();
+ await vi.waitFor(() => expect(results).toHaveLength(1));
+ await vi.waitFor(() => expect(sharedWorkers[1]?.port.closed).toBe(true));
+
+ expect(forwarded).toHaveLength(0);
+ expect(results[0]?.error).toBeUndefined();
+ owner.dispose();
+ await vi.waitFor(() => expect(dedicatedWorkers[0]?.terminated).toBe(true));
+ });
+
+ it('keeps API forwarding at zero when standby retirement transport fails', async () => {
+ const owner = createWorkerCacheHost({ scope: 'integration-scope' });
+ await owner.readQuery({ query: 'query OwnerWarm { ownerWarm }' });
+ const gate = deferred();
+ enqueueGates.set('HoldRetirementFailure', gate.promise);
+ localStorage.setItem('graphql-cache:scope', 'integration-scope');
+ const initializationErrors: string[] = [];
+ const standby = createWorkerCacheHost({
+ scope: 'integration-scope',
+ onInitializationError: (error) =>
+ initializationErrors.push(error.message),
+ });
+ const { forwarded, results } = exchangeHarness(
+ standby,
+ optimisticMutation(103, RETIREMENT_FAILURE_MUTATION)
+ );
+ await vi.waitFor(() =>
+ expect(
+ logs.filter(
+ ({ kind, query }) =>
+ kind === 'enqueue-optimistic-mutation' &&
+ query?.includes('HoldRetirementFailure')
+ )
+ ).toHaveLength(1)
+ );
+
+ standby.dispose();
+ expect(sharedWorkers[1]?.port.closed).toBe(false);
+ sharedWorkers[1]?.fail('standby SharedWorker failed during retirement');
+ await vi.waitFor(() => expect(results).toHaveLength(1));
+
+ expect(forwarded).toHaveLength(0);
+ expect(results[0]?.error?.networkError).toMatchObject({
+ errorCode: 'admitted-enqueue-uncertain',
+ });
+ await vi.waitFor(() => {
+ expect(localStorage.getItem('graphql-cache:scope')).toBe(
+ 'quarantine:integration-scope'
+ );
+ expect(initializationErrors).toEqual([
+ 'standby SharedWorker failed during retirement',
+ ]);
+ });
+ gate.resolve();
+ owner.dispose();
+ await vi.waitFor(() => expect(dedicatedWorkers[0]?.terminated).toBe(true));
+ });
+});
diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.test.ts b/apps/web/src/lib/graphql-cache/host/worker-host.test.ts
index 7f23711400..637fd8e14b 100644
--- a/apps/web/src/lib/graphql-cache/host/worker-host.test.ts
+++ b/apps/web/src/lib/graphql-cache/host/worker-host.test.ts
@@ -1,17 +1,181 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type {
+ CacheRequest,
+ CacheResponseErrorCode,
+ WorkerMessage,
+ WriteResult,
+} from '../protocol';
+import type {
+ CacheCoordinatorPageAdapter,
+ CacheCoordinatorPageAdapterOptions,
+ PageAdapterDisposeOptions,
+} from '../worker/coordinator-page-adapter';
+
+const adapterFactory = vi.hoisted(() => vi.fn());
+
+vi.mock('../worker/coordinator-page-adapter', () => ({
+ createCacheCoordinatorPageAdapter: adapterFactory,
+}));
+
import { createWorkerCacheHost } from './worker-host';
+const CLIENT_ID = '00000000-0000-4000-8000-000000000007';
+const EMPTY_WRITE: WriteResult = {
+ changed: [],
+ affectedOps: [],
+ reset: false,
+};
+
+function responseFor(request: CacheRequest): unknown {
+ switch (request.kind) {
+ case 'read':
+ return { kind: 'miss' };
+ case 'read-records':
+ return { records: [], nextCursor: null };
+ case 'write':
+ case 'commit-optimistic-write':
+ case 'rollback-optimistic-write':
+ return EMPTY_WRITE;
+ case 'enqueue-optimistic-mutation':
+ return {
+ ...EMPTY_WRITE,
+ transactionId: '1',
+ initialClaim: { kind: 'not-runnable' },
+ };
+ case 'inspect-query':
+ case 'inspect-query-variants':
+ return [];
+ case 'claim-next-mutation':
+ return undefined;
+ case 'invalidate':
+ case 'delete-records':
+ return request.keys;
+ case 'init':
+ case 'defer-optimistic-write':
+ case 'teardown':
+ case 'clear':
+ return null;
+ }
+}
+
+class FakePageAdapter {
+ onmessage: ((event: MessageEvent<WorkerMessage>) => void) | null = null;
+ readonly requests: CacheRequest[] = [];
+ readonly ignoredKinds = new Set<CacheRequest['kind']>();
+ readonly errors = new Map<CacheRequest['kind'], string>();
+ readonly dispose = vi.fn(
+ async (_options: PageAdapterDisposeOptions = {}): Promise<void> => {}
+ );
+
+ constructor(readonly options: CacheCoordinatorPageAdapterOptions) {}
+
+ postMessage(request: CacheRequest): void {
+ this.requests.push(request);
+ if (this.ignoredKinds.has(request.kind)) return;
+ const error = this.errors.get(request.kind);
+ queueMicrotask(() => {
+ if (error === undefined) this.respond(request.id, responseFor(request));
+ else this.reject(request.id, error);
+ });
+ }
+
+ respond(id: number, result: unknown): void {
+ this.emit({ id, ok: true, result });
+ }
+
+ reject(id: number, error: string, errorCode?: CacheResponseErrorCode): void {
+ this.emit({
+ id,
+ ok: false,
+ error,
+ ...(errorCode === undefined ? {} : { errorCode }),
+ });
+ }
+
+ push(message: WorkerMessage | unknown): void {
+ this.emit(message as WorkerMessage);
+ }
+
+ replace(ownerEpoch: number): void {
+ this.options.onEngineReplaced?.(ownerEpoch);
+ }
+
+ protocolError(error: Error): void {
+ this.options.onProtocolError?.(error);
+ }
+
+ terminalError(error: Error): void {
+ this.options.onTerminalError?.(error);
+ }
+
+ private emit(message: WorkerMessage): void {
+ this.onmessage?.({ data: message } as MessageEvent<WorkerMessage>);
+ }
+}
+
+let lastAdapter: FakePageAdapter | undefined;
+let configureAdapter: (adapter: FakePageAdapter) => void;
+let sharedWorkerConstructor: ReturnType<typeof vi.fn>;
+let dedicatedWorkerConstructor: ReturnType<typeof vi.fn>;
+let indexedDbDelete: ReturnType<typeof vi.fn>;
+
+function stubSupportedBrowser(): void {
+ sharedWorkerConstructor = vi.fn();
+ dedicatedWorkerConstructor = vi.fn();
+ vi.stubGlobal('SharedWorker', sharedWorkerConstructor);
+ vi.stubGlobal('Worker', dedicatedWorkerConstructor);
+ vi.stubGlobal('MessageChannel', vi.fn());
+ indexedDbDelete = vi.fn(() => ({
+ onblocked: null,
+ onerror: null,
+ onsuccess: null,
+ }));
+ vi.stubGlobal('indexedDB', { deleteDatabase: indexedDbDelete });
+ vi.stubGlobal('navigator', {
+ locks: {
+ request: vi.fn(
+ async (
+ name: string,
+ _options: LockOptions,
+ callback: (lock: Lock | null) => unknown
+ ) => await callback({ name, mode: 'exclusive' } as Lock)
+ ),
+ },
+ storage: { getDirectory: vi.fn() },
+ });
+}
+
+function requireAdapter(): FakePageAdapter {
+ if (!lastAdapter) throw new Error('page adapter was not constructed');
+ return lastAdapter;
+}
+
describe('createWorkerCacheHost', () => {
+ beforeEach(() => {
+ localStorage.clear();
+ stubSupportedBrowser();
+ vi.spyOn(crypto, 'randomUUID').mockReturnValue(CLIENT_ID);
+ lastAdapter = undefined;
+ configureAdapter = () => undefined;
+ adapterFactory.mockReset();
+ adapterFactory.mockImplementation(
+ (options: CacheCoordinatorPageAdapterOptions) => {
+ const fake = new FakePageAdapter(options);
+ configureAdapter(fake);
+ lastAdapter = fake;
+ return fake as unknown as CacheCoordinatorPageAdapter;
+ }
+ );
+ });
+
afterEach(() => {
vi.useRealTimers();
vi.unstubAllGlobals();
vi.restoreAllMocks();
});
- it('uses a storage-free no-op host when SharedWorker is unavailable', async () => {
- const worker = vi.fn();
+ it('uses a storage-free no-op host when a required capability is unavailable', async () => {
vi.stubGlobal('SharedWorker', undefined);
- vi.stubGlobal('Worker', worker);
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
const host = createWorkerCacheHost({ scope: 'scope-1' });
@@ -19,243 +183,378 @@ describe('createWorkerCacheHost', () => {
expect(warn).toHaveBeenCalledWith(
'[graphql-cache] disabled: SharedWorker is not supported by this browser'
);
- expect(worker).not.toHaveBeenCalled();
+ expect(adapterFactory).not.toHaveBeenCalled();
+ expect(dedicatedWorkerConstructor).not.toHaveBeenCalled();
+ expect(indexedDbDelete).not.toHaveBeenCalled();
expect(host.disabled).toBe(true);
await expect(host.readQuery({ query: '{ x }' })).resolves.toEqual({
kind: 'miss',
});
await expect(
host.writeQuery({ query: '{ x }', data: { x: 1 } })
- ).resolves.toEqual({ changed: [], affectedOps: [], reset: false });
- await expect(
- host.readRecords({
- document: 'fragment Item on GraphqlSoupItem { id }',
- fragmentName: 'Item',
- limit: 20,
- })
- ).resolves.toEqual({ records: [], nextCursor: null });
+ ).resolves.toEqual(EMPTY_WRITE);
});
- it('round-trips generated query inspection through the worker protocol', async () => {
- const requests: unknown[] = [];
- const variants = [{ variables: { input: { initial: { limit: 20 } } } }];
- const instances = variants.map((variant) => ({
- ...variant,
- value: { bins: [] },
- }));
- class FakeSharedWorker {
- port = {
- onmessage: null as ((event: MessageEvent) => void) | null,
- start() {},
- close() {},
- postMessage: (request: { id?: number; kind: string }) => {
- requests.push(request);
- if (request.id === undefined) return;
- queueMicrotask(() => {
- this.port.onmessage?.({
- data: {
- id: request.id,
- ok: true,
- result:
- request.kind === 'inspect-query'
- ? instances
- : request.kind === 'inspect-query-variants'
- ? variants
- : null,
- },
- } as MessageEvent);
- });
- },
- };
- }
- vi.stubGlobal('SharedWorker', FakeSharedWorker);
+ it('uses the no-op host when OPFS is unavailable', () => {
+ vi.stubGlobal('navigator', {
+ locks: { request: vi.fn() },
+ storage: {},
+ });
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
const host = createWorkerCacheHost({ scope: 'scope-1' });
- const variantRequest = {
- query:
- 'query Views($input: GroupedSoupInput!) { user { groupSoup(input: $input) { bins { key } } } }',
- operationName: 'Views',
- path: [{ field: 'user' }, { field: 'groupSoup' }],
- };
- const request = {
- ...variantRequest,
- variableFilters: [
- { input: { initial: { groupBy: { field: 'PROPERTY' } } } },
- ],
- };
- await expect(host.inspectQueryVariants(variantRequest)).resolves.toEqual(
- variants
+ expect(host.disabled).toBe(true);
+ expect(warn).toHaveBeenCalledWith(
+ '[graphql-cache] disabled: OPFS is not supported by this browser'
);
- expect(requests).toContainEqual(
- expect.objectContaining({
- kind: 'inspect-query-variants',
- ...variantRequest,
- })
+ expect(adapterFactory).not.toHaveBeenCalled();
+ });
+
+ it('does not false-gate worker-only sync access handle capability', async () => {
+ vi.stubGlobal('FileSystemFileHandle', undefined);
+ vi.stubGlobal('FileSystemSyncAccessHandle', undefined);
+ configureAdapter = (fake) => {
+ fake.errors.set('init', 'sync access handles unavailable in engine');
+ };
+ const onInitializationError = vi.fn();
+ const host = createWorkerCacheHost({
+ scope: 'scope-1',
+ onInitializationError,
+ });
+
+ expect(host.disabled).not.toBe(true);
+ await expect(host.clear()).rejects.toThrow(
+ 'sync access handles unavailable in engine'
);
+ expect(adapterFactory).toHaveBeenCalledOnce();
+ expect(onInitializationError).toHaveBeenCalledOnce();
+ });
+
+ it('samples origin storage pressure periodically and clears the timer on dispose', async () => {
+ vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
+ const estimate = vi.fn(async () => ({ usage: 25, quota: 100 }));
+ vi.stubGlobal('navigator', {
+ ...(navigator as unknown as Record<string, unknown>),
+ storage: {
+ getDirectory: vi.fn(),
+ estimate,
+ persisted: vi.fn(async () => true),
+ },
+ });
+ const observations: Array<Record<string, unknown>> = [];
+ const host = createWorkerCacheHost({
+ scope: 'scope-1',
+ storageHealthIntervalMs: 1_000,
+ telemetry: {
+ record: (observation) => observations.push(observation),
+ flush: vi.fn(),
+ },
+ });
+
+ await host.readQuery({ query: 'query Ready { value }' });
+ await Promise.resolve();
+ expect(estimate).toHaveBeenCalledOnce();
+ await vi.advanceTimersByTimeAsync(2_000);
+ expect(estimate).toHaveBeenCalledTimes(3);
+
+ host.dispose();
+ await vi.advanceTimersByTimeAsync(2_000);
+ expect(estimate).toHaveBeenCalledTimes(3);
expect(
- requests.find(
- (candidate) =>
- (candidate as { kind?: string }).kind === 'inspect-query-variants'
+ observations.filter(
+ (observation) =>
+ observation.name === 'graphql_cache.origin_storage_pressure'
)
- ).not.toHaveProperty('variableFilters');
- await expect(host.inspectQuery(request)).resolves.toEqual(instances);
- expect(requests).toContainEqual(
- expect.objectContaining({ kind: 'inspect-query', ...request })
+ ).toHaveLength(3);
+ });
+
+ it('constructs the coordinator adapter and starts cutover cleanup lazily on first RPC', async () => {
+ const host = createWorkerCacheHost({ scope: 'lazy-scope' });
+ host.onOpsAffected(() => undefined);
+
+ expect(adapterFactory).not.toHaveBeenCalled();
+ expect(sharedWorkerConstructor).not.toHaveBeenCalled();
+ expect(dedicatedWorkerConstructor).not.toHaveBeenCalled();
+ expect(indexedDbDelete).not.toHaveBeenCalled();
+
+ const read = host.readQuery({ query: '{ x }' });
+ expect(adapterFactory).toHaveBeenCalledOnce();
+ expect(indexedDbDelete).toHaveBeenCalledOnce();
+ expect(indexedDbDelete).toHaveBeenCalledWith('graphql-cache:lazy-scope');
+ expect(adapterFactory).toHaveBeenCalledWith(
+ expect.objectContaining({ scope: 'lazy-scope' })
);
+ await expect(read).resolves.toEqual({ kind: 'miss' });
+ await host.clear();
+ expect(requireAdapter().requests.map((request) => request.kind)).toEqual([
+ 'init',
+ 'read',
+ 'clear',
+ ]);
+ expect(indexedDbDelete).toHaveBeenCalledOnce();
host.dispose();
});
- it('forwards user-visible read priority to the worker', async () => {
- const requests: Array<{ id?: number; kind: string; priority?: string }> =
- [];
- class FakeSharedWorker {
- port = {
- onmessage: null as ((event: MessageEvent) => void) | null,
- start() {},
- close() {},
- postMessage: (request: {
- id?: number;
- kind: string;
- priority?: string;
- }) => {
- requests.push(request);
- if (request.id === undefined) return;
- queueMicrotask(() => {
- this.port.onmessage?.({
- data: {
- id: request.id,
- ok: true,
- result:
- request.kind === 'read'
- ? { kind: 'hit', data: { soup: true } }
- : null,
- },
- } as MessageEvent);
- });
- },
- };
- }
- vi.stubGlobal('SharedWorker', FakeSharedWorker);
- const host = createWorkerCacheHost({ scope: 'scope-1' });
- const entityResolvers = [
- {
- parentType: 'GraphqlUser',
- fieldName: 'emailThread',
- targetType: 'GraphqlSoupEmailThread',
- argumentPath: ['input', 'threadId'],
- },
- ];
+ it('preserves the complete CacheHost RPC surface, request ids, and call order', async () => {
+ const host = createWorkerCacheHost({ scope: 'scope-1', hotCapacity: 42 });
+ const claim = { owner: 'runner', generation: 'generation-1' };
- await expect(
+ const results = await Promise.all([
host.readQuery({
opKey: 7,
- query: 'query GroupSoup { groupSoup }',
+ query: 'query Read { user { id } }',
priority: 'user-visible',
- entityResolvers,
- })
- ).resolves.toEqual({ kind: 'hit', data: { soup: true } });
- expect(requests).toContainEqual(
+ entityResolvers: [
+ {
+ parentType: 'GraphqlUser',
+ fieldName: 'emailThread',
+ targetType: 'GraphqlSoupEmailThread',
+ argumentPath: ['input', 'threadId'],
+ },
+ ],
+ }),
+ host.readRecords({
+ document: 'fragment Item on GraphqlSoupItem { id }',
+ fragmentName: 'Item',
+ cursor: 'cursor-1',
+ limit: 20,
+ }),
+ host.writeQuery({
+ opKey: 8,
+ query: 'query Read { user { id } }',
+ data: { user: { id: 'user-1' } },
+ identity: 'user-1',
+ }),
+ host.enqueueOptimisticMutation(
+ {
+ opKey: 9,
+ query: 'mutation Rename { rename { id } }',
+ data: { rename: { id: 'doc-1' } },
+ },
+ { owner: 'runner', nowMs: 100, leaseExpiresAtMs: 1_100 }
+ ),
+ host.inspectQueryVariants({
+ query: 'query Views { views }',
+ path: [{ field: 'views' }],
+ }),
+ host.inspectQuery({
+ query: 'query Views { views }',
+ path: [{ field: 'views' }],
+ variableFilters: [{ input: { limit: 20 } }],
+ }),
+ host.claimNextMutation('runner', 200, 1_200),
+ host.deferOptimisticWrite('1', claim, 2_000, 'offline'),
+ host.commitOptimisticWrite('1', claim, {
+ query: 'mutation Rename { rename { id } }',
+ data: { rename: { id: 'doc-1' } },
+ }),
+ host.rollbackOptimisticWrite('2', claim, 'denied'),
+ host.invalidate(['User:1']),
+ host.deleteRecords(['Document:1']),
+ host.teardown(7),
+ host.clear(),
+ ]);
+
+ const requests = requireAdapter().requests;
+ expect(requests.map(({ id, kind }) => [id, kind])).toEqual([
+ [1, 'init'],
+ [2, 'read'],
+ [3, 'read-records'],
+ [4, 'write'],
+ [5, 'enqueue-optimistic-mutation'],
+ [6, 'inspect-query-variants'],
+ [7, 'inspect-query'],
+ [8, 'claim-next-mutation'],
+ [9, 'defer-optimistic-write'],
+ [10, 'commit-optimistic-write'],
+ [11, 'rollback-optimistic-write'],
+ [12, 'invalidate'],
+ [13, 'delete-records'],
+ [14, 'teardown'],
+ [15, 'clear'],
+ ]);
+ expect(requests[0]).toEqual({
+ id: 1,
+ kind: 'init',
+ scope: 'scope-1',
+ hotCapacity: 42,
+ });
+ expect(requests[1]).toEqual(
expect.objectContaining({
- kind: 'read',
+ opId: `${CLIENT_ID}:7`,
priority: 'user-visible',
- entityResolvers,
+ entityResolvers: [
+ expect.objectContaining({
+ parentType: 'GraphqlUser',
+ fieldName: 'emailThread',
+ }),
+ ],
})
);
+ expect(requests[3]).toEqual(
+ expect.objectContaining({ originOpId: `${CLIENT_ID}:8` })
+ );
+ expect(requests[4]).toEqual(
+ expect.objectContaining({
+ originOpId: `${CLIENT_ID}:9`,
+ owner: 'runner',
+ createdAtMs: 100,
+ nowMs: 100,
+ leaseExpiresAtMs: 1_100,
+ })
+ );
+ expect(requests[13]).toEqual({
+ id: 14,
+ kind: 'teardown',
+ opId: `${CLIENT_ID}:7`,
+ });
+ expect(results[0]).toEqual({ kind: 'miss' });
+ expect(results[3]).toEqual(expect.objectContaining({ transactionId: '1' }));
host.dispose();
});
- it('delivers queued mutation settlements pushed by the worker', async () => {
- let push: (message: unknown) => void = () => {
- throw new Error('worker not initialized');
- };
- class FakeSharedWorker {
- port = {
- onmessage: null as ((event: MessageEvent) => void) | null,
- start() {},
- close() {},
- postMessage: (request: { id?: number }) => {
- if (request.id === undefined) return;
- queueMicrotask(() => {
- this.port.onmessage?.({
- data: { id: request.id, ok: true, result: null },
- } as MessageEvent);
- });
- },
- };
+ it('bounds hung registration/init before admitting reads or mutations', async () => {
+ vi.useFakeTimers();
+ configureAdapter = (fake) => fake.ignoredKinds.add('init');
+ const onInitializationError = vi.fn();
+ const host = createWorkerCacheHost({
+ scope: 'scope-1',
+ requestTimeoutMs: 100,
+ initializationTimeoutMs: 10,
+ onInitializationError,
+ });
- constructor() {
- push = (message) =>
- this.port.onmessage?.({ data: message } as MessageEvent);
- }
- }
- vi.stubGlobal('SharedWorker', FakeSharedWorker);
+ const read = host.readQuery({ opKey: 4, query: 'query Read { user }' });
+ const mutation = host.enqueueOptimisticMutation(
+ { query: 'mutation Update { update }', data: { update: true } },
+ { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
+ );
+ const readRejected = expect(read).rejects.toThrow(
+ 'cache worker timeout: init'
+ );
+ const mutationRejected = expect(mutation).rejects.toThrow(
+ 'cache worker timeout: init'
+ );
+
+ await vi.advanceTimersByTimeAsync(11);
+ await Promise.all([readRejected, mutationRejected]);
+
+ const adapter = requireAdapter();
+ expect(adapter.requests.map(({ id, kind }) => [id, kind])).toEqual([
+ [1, 'init'],
+ ]);
+ expect(adapter.dispose).toHaveBeenCalledWith({ graceful: false });
+ expect(onInitializationError).toHaveBeenCalledOnce();
+ expect(vi.getTimerCount()).toBe(0);
+ });
+
+ it('recovers typed initial epoch loss with fresh init handshakes only', async () => {
+ configureAdapter = (fake) => fake.ignoredKinds.add('init');
+ const onInitializationError = vi.fn();
+ const host = createWorkerCacheHost({
+ scope: 'scope-1',
+ onInitializationError,
+ });
+ const affected: number[][] = [];
+ host.onOpsAffected((keys) => affected.push(keys));
+
+ const read = host.readQuery({ opKey: 44, query: 'query Read { user }' });
+ const mutation = host.enqueueOptimisticMutation(
+ { query: 'mutation Update { update }', data: { update: true } },
+ { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
+ );
+ const readRejected = expect(read).rejects.toMatchObject({
+ message: 'owner epoch 1 was lost',
+ errorCode: 'owner-epoch-lost',
+ });
+ const mutationRejected = expect(mutation).rejects.toMatchObject({
+ message: 'owner epoch 1 was lost',
+ errorCode: 'owner-epoch-lost',
+ });
+ const adapter = requireAdapter();
+ adapter.reject(1, 'owner epoch 1 was lost', 'owner-epoch-lost');
+ await Promise.all([readRejected, mutationRejected]);
+
+ adapter.replace(2);
+ expect(adapter.requests.map(({ id, kind }) => [id, kind])).toEqual([
+ [1, 'init'],
+ [2, 'init'],
+ ]);
+ expect(affected).toEqual([]);
+ adapter.reject(2, 'owner epoch 2 was lost', 'owner-epoch-lost');
+ await Promise.resolve();
+
+ adapter.replace(3);
+ expect(adapter.requests.map(({ id, kind }) => [id, kind])).toEqual([
+ [1, 'init'],
+ [2, 'init'],
+ [3, 'init'],
+ ]);
+ expect(affected).toEqual([]);
+ adapter.respond(3, null);
+ await vi.waitFor(() =>
+ expect(
+ adapter.requests.filter(({ kind }) => kind === 'init')
+ ).toHaveLength(3)
+ );
+ expect(affected).toEqual([]);
+
+ expect(
+ adapter.requests.filter(
+ (request) =>
+ request.kind === 'read' ||
+ request.kind === 'enqueue-optimistic-mutation'
+ )
+ ).toEqual([]);
+ expect(onInitializationError).not.toHaveBeenCalled();
+ host.dispose();
+ });
+
+ it('suppresses replacement notification while an original init is queued', async () => {
+ configureAdapter = (fake) => fake.ignoredKinds.add('init');
const host = createWorkerCacheHost({ scope: 'scope-1' });
- const seen: unknown[] = [];
- host.onMutationSettled((settlement) => seen.push(settlement));
- const settlement = {
- transactionId: '12',
- status: 'committed' as const,
- };
+ const affected: number[][] = [];
+ host.onOpsAffected((keys) => affected.push(keys));
- push({ kind: 'mutation-settled', settlement });
+ const read = host.readQuery({ opKey: 5, query: 'query Read { user }' });
+ const adapter = requireAdapter();
+ adapter.replace(2);
+ adapter.respond(1, null);
+ await expect(read).resolves.toEqual({ kind: 'miss' });
- expect(seen).toEqual([settlement]);
+ expect(affected).toEqual([]);
+ expect(adapter.requests.map(({ id, kind }) => [id, kind])).toEqual([
+ [1, 'init'],
+ [2, 'read'],
+ ]);
host.dispose();
});
- it('times out reads without timing out durable mutations', async () => {
+ it('times out read-only RPC without timing out or replaying mutations', async () => {
vi.useFakeTimers();
- const requests: Array<{ id?: number; kind: string }> = [];
- let respond: (id: number, result: unknown) => void = () => {
- throw new Error('worker not initialized');
+ configureAdapter = (fake) => {
+ fake.ignoredKinds.add('read');
+ fake.ignoredKinds.add('enqueue-optimistic-mutation');
};
- class FakeSharedWorker {
- port = {
- onmessage: null as ((event: MessageEvent) => void) | null,
- start() {},
- close() {},
- postMessage: (request: { id?: number; kind: string }) => {
- requests.push(request);
- if (request.id === undefined) return;
- if (request.kind === 'init') {
- queueMicrotask(() =>
- this.port.onmessage?.({
- data: { id: request.id, ok: true, result: null },
- } as MessageEvent)
- );
- }
- },
- };
-
- constructor() {
- respond = (id, result) =>
- this.port.onmessage?.({
- data: { id, ok: true, result },
- } as MessageEvent);
- }
- }
- vi.stubGlobal('SharedWorker', FakeSharedWorker);
const host = createWorkerCacheHost({
scope: 'scope-1',
requestTimeoutMs: 10,
});
- const readResult = expect(
- host.readQuery({ query: 'query Read { user { id } }' })
- ).rejects.toThrow('cache worker timeout: read');
- const mutationResult = host.enqueueOptimisticMutation(
+ const read = host.readQuery({ query: 'query Read { user { id } }' });
+ const mutation = host.enqueueOptimisticMutation(
{
query: 'mutation Rename { rename { id } }',
data: { rename: { id: 'doc-1' } },
},
- {
- owner: 'runner-1',
- nowMs: 123,
- leaseExpiresAtMs: 1_123,
- }
+ { owner: 'runner', nowMs: 123, leaseExpiresAtMs: 1_123 }
+ );
+ const readResult = expect(read).rejects.toThrow(
+ 'cache worker timeout: read'
);
let mutationSettled = false;
- void mutationResult.then(
+ void mutation.then(
() => {
mutationSettled = true;
},
@@ -267,50 +566,647 @@ describe('createWorkerCacheHost', () => {
await vi.advanceTimersByTimeAsync(11);
await readResult;
expect(mutationSettled).toBe(false);
+ const adapter = requireAdapter();
expect(
- requests.filter(
+ adapter.requests.filter(
(request) => request.kind === 'enqueue-optimistic-mutation'
)
).toHaveLength(1);
- const mutationRequest = requests.find(
+ const mutationRequest = adapter.requests.find(
(request) => request.kind === 'enqueue-optimistic-mutation'
);
- expect(mutationRequest).toEqual(
- expect.objectContaining({
- owner: 'runner-1',
- nowMs: 123,
- createdAtMs: 123,
- leaseExpiresAtMs: 1_123,
- })
- );
- expect(mutationRequest?.id).toBeTypeOf('number');
- const result = {
+ adapter.respond(mutationRequest?.id as number, {
+ ...EMPTY_WRITE,
transactionId: '1',
- changed: [],
- affectedOps: [],
- reset: false,
- initialClaim: { kind: 'not-runnable' as const },
+ initialClaim: { kind: 'not-runnable' },
+ });
+ await expect(mutation).resolves.toEqual(
+ expect.objectContaining({ transactionId: '1' })
+ );
+ expect(
+ adapter.requests.filter(
+ (request) => request.kind === 'enqueue-optimistic-mutation'
+ )
+ ).toHaveLength(1);
+ host.dispose();
+ });
+
+ it('rejects old-epoch requests and never replays reads or durable mutations', async () => {
+ configureAdapter = (fake) => {
+ fake.ignoredKinds.add('read');
+ fake.ignoredKinds.add('enqueue-optimistic-mutation');
};
- respond(mutationRequest?.id as number, result);
- await expect(mutationResult).resolves.toEqual(result);
+ const host = createWorkerCacheHost({ scope: 'scope-1' });
+ const affected: number[][] = [];
+ host.onOpsAffected((keys) => affected.push(keys));
+ await host.clear();
+
+ const read = host.readQuery({ opKey: 44, query: 'query Read { user }' });
+ const mutation = host.enqueueOptimisticMutation(
+ { query: 'mutation Update { update }', data: { update: true } },
+ { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
+ );
+ const readRejected = expect(read).rejects.toThrow('owner epoch 1 was lost');
+ const mutationRejected = expect(mutation).rejects.toThrow(
+ 'owner epoch 1 was lost'
+ );
+ const adapter = requireAdapter();
+ await vi.waitFor(() =>
+ expect(
+ adapter.requests.filter(
+ (request) =>
+ request.kind === 'read' ||
+ request.kind === 'enqueue-optimistic-mutation'
+ )
+ ).toHaveLength(2)
+ );
+ const oldEpochRequests = adapter.requests.filter(
+ (request) =>
+ request.kind === 'read' ||
+ request.kind === 'enqueue-optimistic-mutation'
+ );
+ for (const request of oldEpochRequests) {
+ adapter.reject(request.id, 'owner epoch 1 was lost', 'owner-epoch-lost');
+ }
+ await Promise.all([readRejected, mutationRejected]);
+
+ adapter.replace(2);
+ await vi.waitFor(() =>
+ expect(
+ adapter.requests.filter(({ kind }) => kind === 'init')
+ ).toHaveLength(2)
+ );
+ expect(affected).toEqual([]);
+
+ expect(
+ adapter.requests.filter((request) => request.kind === 'init')
+ ).toHaveLength(2);
+ expect(
+ adapter.requests.filter(
+ (request) =>
+ request.kind === 'read' ||
+ request.kind === 'enqueue-optimistic-mutation'
+ )
+ ).toEqual(oldEpochRequests);
host.dispose();
});
- it('falls back to no-op when SharedWorker initialization throws', () => {
- vi.stubGlobal(
- 'SharedWorker',
- vi.fn(function () {
- throw new Error('blocked');
- })
+ it('notifies a successfully registered key whose old-epoch reread was rejected', async () => {
+ const host = createWorkerCacheHost({ scope: 'scope-1' });
+ const affected: number[][] = [];
+ host.onOpsAffected((keys) => affected.push(keys));
+ await host.clear();
+ await Promise.all([
+ host.readQuery({ opKey: 7, query: 'query Seven { seven }' }),
+ host.readQuery({ opKey: 9, query: 'query Nine { nine }' }),
+ ]);
+ const adapter = requireAdapter();
+ adapter.ignoredKinds.add('read');
+
+ const reread = host.readQuery({
+ opKey: 7,
+ query: 'query SlowSeven { seven }',
+ });
+ await vi.waitFor(() =>
+ expect(
+ adapter.requests.filter(
+ (request) =>
+ request.kind === 'read' && request.query.includes('SlowSeven')
+ )
+ ).toHaveLength(1)
);
- const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const request = adapter.requests.find(
+ (candidate) =>
+ candidate.kind === 'read' && candidate.query.includes('SlowSeven')
+ );
+ adapter.reject(
+ request?.id as number,
+ 'owner epoch 1 was lost',
+ 'owner-epoch-lost'
+ );
+ await expect(reread).rejects.toMatchObject({
+ errorCode: 'owner-epoch-lost',
+ });
+ adapter.replace(2);
+ await vi.waitFor(() => expect(affected).toEqual([[7, 9]]));
+ expect(
+ adapter.requests.filter(
+ (candidate) =>
+ candidate.kind === 'read' && candidate.query.includes('SlowSeven')
+ )
+ ).toHaveLength(1);
+ host.dispose();
+ });
+
+ it('notifies only registered active operations and deduplicates replacement epochs', async () => {
const host = createWorkerCacheHost({ scope: 'scope-1' });
+ const affected: number[][] = [];
+ const unsubscribe = host.onOpsAffected((keys) => affected.push(keys));
+ await host.clear();
- expect(host.disabled).toBe(true);
- expect(warn).toHaveBeenCalledWith(
- '[graphql-cache] disabled: SharedWorker could not be initialized'
+ await Promise.all([
+ host.readQuery({ opKey: 7, query: 'query Seven { seven }' }),
+ host.readQuery({ opKey: 9, query: 'query Nine { nine }' }),
+ host.readQuery({ query: 'query Untracked { untracked }' }),
+ ]);
+ const adapter = requireAdapter();
+ adapter.replace(2);
+ await vi.waitFor(() => expect(affected).toEqual([[7, 9]]));
+
+ await host.teardown(7);
+ await host.readQuery({ opKey: 9, query: 'query NineAgain { nine }' });
+ adapter.replace(2);
+ adapter.replace(1);
+ adapter.replace(3);
+ adapter.replace(3);
+ await vi.waitFor(() => expect(affected).toEqual([[7, 9], [9]]));
+
+ await Promise.all([
+ host.readQuery({ opKey: 9, query: 'query NineThird { nine }' }),
+ host.readQuery({ opKey: 7, query: 'query SevenAgain { seven }' }),
+ ]);
+ adapter.replace(4);
+ await vi.waitFor(() => expect(affected).toEqual([[7, 9], [9], [9, 7]]));
+ unsubscribe();
+
+ expect(affected).toEqual([[7, 9], [9], [9, 7]]);
+ host.dispose();
+ });
+
+ it('strictly filters pushes to the exact client operation prefix', async () => {
+ const host = createWorkerCacheHost({ scope: 'scope-1' });
+ const affected: number[][] = [];
+ const cacheChanges = vi.fn();
+ const settlements: unknown[] = [];
+ host.onOpsAffected((keys) => affected.push(keys));
+ host.onCacheChanged(cacheChanges);
+ host.onMutationSettled((settlement) => settlements.push(settlement));
+ await host.clear();
+
+ const adapter = requireAdapter();
+ adapter.push({
+ kind: 'ops-affected',
+ opIds: [
+ `${CLIENT_ID}:7`,
+ `${CLIENT_ID}:7`,
+ `foreign:${CLIENT_ID}:8`,
+ `${CLIENT_ID}0:9`,
+ `${CLIENT_ID}:1e3`,
+ `${CLIENT_ID}:0x10`,
+ `${CLIENT_ID}:NaN`,
+ `${CLIENT_ID}:9007199254740992`,
+ `${CLIENT_ID}:007`,
+ `${CLIENT_ID}:-0`,
+ `${CLIENT_ID}:not-a-number`,
+ `${CLIENT_ID}:`,
+ `${CLIENT_ID}:12`,
+ ],
+ keys: ['User:1'],
+ });
+ adapter.push({ kind: 'ops-affected', opIds: [7], keys: [] });
+ adapter.push({ kind: 'cache-changed' });
+ adapter.push({
+ kind: 'mutation-settled',
+ settlement: { transactionId: '3', status: 'committed' },
+ });
+
+ expect(affected).toEqual([[7, 12]]);
+ expect(cacheChanges).toHaveBeenCalledOnce();
+ expect(settlements).toEqual([{ transactionId: '3', status: 'committed' }]);
+ host.dispose();
+ });
+
+ it('reports initialization failure once, settles callers, and closes transport', async () => {
+ vi.useFakeTimers();
+ configureAdapter = (fake) => {
+ fake.errors.set('init', 'OPFS initialization failed');
+ };
+ const onInitializationError = vi.fn();
+ const host = createWorkerCacheHost({
+ scope: 'scope-1',
+ requestTimeoutMs: 10,
+ onInitializationError,
+ });
+
+ const read = host.readQuery({ query: 'query Read { user }' });
+ const write = host.writeQuery({
+ query: 'query Read { user }',
+ data: { user: null },
+ });
+ const readRejected = expect(read).rejects.toThrow(
+ 'OPFS initialization failed'
+ );
+ const writeRejected = expect(write).rejects.toThrow(
+ 'OPFS initialization failed'
+ );
+ await vi.runAllTimersAsync();
+ await Promise.all([readRejected, writeRejected]);
+
+ const adapter = requireAdapter();
+ adapter.protocolError(new Error('late coordinator error'));
+ adapter.reject(1, 'late initialization response');
+
+ expect(onInitializationError).toHaveBeenCalledOnce();
+ expect(onInitializationError).toHaveBeenCalledWith(
+ expect.objectContaining({ message: 'OPFS initialization failed' })
+ );
+ expect(adapter.dispose).toHaveBeenCalledOnce();
+ expect(adapter.dispose).toHaveBeenCalledWith({ graceful: false });
+ expect(vi.getTimerCount()).toBe(0);
+ host.dispose();
+ expect(adapter.dispose).toHaveBeenCalledOnce();
+ });
+
+ it('terminal transport failure quarantines scope and rejects admitted mutations once', async () => {
+ configureAdapter = (fake) => {
+ fake.ignoredKinds.add('enqueue-optimistic-mutation');
+ };
+ localStorage.setItem('graphql-cache:scope', 'scope-1');
+ const onInitializationError = vi.fn();
+ const host = createWorkerCacheHost({
+ scope: 'scope-1',
+ onInitializationError,
+ });
+ const affected = vi.fn();
+ host.onOpsAffected(affected);
+ await host.clear();
+ const adapter = requireAdapter();
+ const mutation = host.enqueueOptimisticMutation(
+ { query: 'mutation Update { update }', data: { update: true } },
+ { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
+ );
+ const mutationRejected = expect(mutation).rejects.toMatchObject({
+ message: expect.stringContaining('coordinator MessagePort messageerror'),
+ errorCode: 'admitted-enqueue-uncertain',
+ });
+ await vi.waitFor(() =>
+ expect(
+ adapter.requests.filter(
+ (request) => request.kind === 'enqueue-optimistic-mutation'
+ )
+ ).toHaveLength(1)
+ );
+
+ adapter.terminalError(new Error('coordinator MessagePort messageerror'));
+ await mutationRejected;
+ adapter.terminalError(new Error('duplicate terminal callback'));
+ adapter.replace(2);
+
+ expect(onInitializationError).toHaveBeenCalledOnce();
+ expect(adapter.dispose).toHaveBeenCalledOnce();
+ expect(adapter.dispose).toHaveBeenCalledWith({ graceful: false });
+ expect(localStorage.getItem('graphql-cache:scope')).toBe(
+ 'quarantine:scope-1'
+ );
+ expect(affected).not.toHaveBeenCalled();
+ expect(
+ adapter.requests.filter(
+ (request) => request.kind === 'enqueue-optimistic-mutation'
+ )
+ ).toHaveLength(1);
+ await expect(host.clear()).rejects.toThrow(
+ 'coordinator MessagePort messageerror'
+ );
+ });
+
+ it('quarantines transport scope before invoking the product failure callback', async () => {
+ let runLock!: () => Promise<void>;
+ vi.stubGlobal('navigator', {
+ locks: {
+ request: vi.fn(
+ <T>(
+ _name: string,
+ _options: LockOptions,
+ callback: (lock: Lock | null) => T | PromiseLike<T>
+ ) =>
+ new Promise<T>((resolve, reject) => {
+ runLock = async () => {
+ try {
+ resolve(
+ await callback({
+ name: 'graphql-cache:scope-storage',
+ mode: 'exclusive',
+ } as Lock)
+ );
+ } catch (error) {
+ reject(error);
+ }
+ };
+ })
+ ),
+ },
+ storage: { getDirectory: vi.fn() },
+ });
+ localStorage.setItem('graphql-cache:scope', 'scope-1');
+ const callbackScopes: Array<string | null> = [];
+ const host = createWorkerCacheHost({
+ scope: 'scope-1',
+ onInitializationError: () => {
+ callbackScopes.push(localStorage.getItem('graphql-cache:scope'));
+ },
+ });
+ await host.clear();
+
+ requireAdapter().terminalError(new Error('transport failed'));
+ expect(callbackScopes).toEqual([]);
+ expect(localStorage.getItem('graphql-cache:scope')).toBe('scope-1');
+ await runLock();
+ await vi.waitFor(() =>
+ expect(callbackScopes).toEqual(['quarantine:scope-1'])
+ );
+ });
+
+ it('converges same-scope failures and ignores stale or disposed host quarantine', async () => {
+ const adapters: FakePageAdapter[] = [];
+ adapterFactory.mockImplementation(
+ (adapterOptions: CacheCoordinatorPageAdapterOptions) => {
+ const fake = new FakePageAdapter(adapterOptions);
+ adapters.push(fake);
+ return fake as unknown as CacheCoordinatorPageAdapter;
+ }
+ );
+ localStorage.setItem('graphql-cache:scope', 'shared-old');
+ const firstError = vi.fn();
+ const secondError = vi.fn();
+ const first = createWorkerCacheHost({
+ scope: 'shared-old',
+ onInitializationError: firstError,
+ });
+ const second = createWorkerCacheHost({
+ scope: 'shared-old',
+ onInitializationError: secondError,
+ });
+ await Promise.all([first.clear(), second.clear()]);
+
+ adapters[0]?.terminalError(new Error('first tab transport failed'));
+ expect(localStorage.getItem('graphql-cache:scope')).toBe(
+ 'quarantine:shared-old'
+ );
+ adapters[1]?.terminalError(new Error('second tab transport failed'));
+ expect(localStorage.getItem('graphql-cache:scope')).toBe(
+ 'quarantine:shared-old'
+ );
+ await vi.waitFor(() => {
+ expect(firstError).toHaveBeenCalledOnce();
+ expect(secondError).toHaveBeenCalledOnce();
+ });
+
+ const staleError = vi.fn();
+ const stale = createWorkerCacheHost({
+ scope: 'shared-old',
+ onInitializationError: staleError,
+ });
+ await stale.clear();
+ localStorage.setItem('graphql-cache:scope', 'new-healthy-scope');
+ adapters[2]?.terminalError(new Error('late stale transport failed'));
+ expect(localStorage.getItem('graphql-cache:scope')).toBe(
+ 'new-healthy-scope'
+ );
+
+ const disposedError = vi.fn();
+ const disposed = createWorkerCacheHost({
+ scope: 'shared-old',
+ onInitializationError: disposedError,
+ });
+ await disposed.clear();
+ disposed.dispose();
+ adapters[3]?.terminalError(new Error('late disposed callback'));
+ expect(localStorage.getItem('graphql-cache:scope')).toBe(
+ 'new-healthy-scope'
+ );
+ expect(disposedError).not.toHaveBeenCalled();
+ });
+
+ it('reports a lazy adapter-construction failure without leaking a transport', async () => {
+ adapterFactory.mockImplementationOnce(() => {
+ throw new Error('SharedWorker construction failed');
+ });
+ const onInitializationError = vi.fn();
+ const host = createWorkerCacheHost({
+ scope: 'scope-1',
+ onInitializationError,
+ });
+
+ expect(adapterFactory).not.toHaveBeenCalled();
+ await expect(host.clear()).rejects.toThrow(
+ 'SharedWorker construction failed'
+ );
+
+ expect(adapterFactory).toHaveBeenCalledOnce();
+ expect(onInitializationError).toHaveBeenCalledOnce();
+ expect(lastAdapter).toBeUndefined();
+ host.dispose();
+ });
+
+ it('disposes explicitly with graceful idempotence and drains pending mutation responses', async () => {
+ configureAdapter = (fake) => {
+ fake.ignoredKinds.add('enqueue-optimistic-mutation');
+ };
+ const host = createWorkerCacheHost({ scope: 'scope-1' });
+ await host.clear();
+ const adapter = requireAdapter();
+ let finishDrain: (() => void) | undefined;
+ const draining = new Promise<void>((resolve) => {
+ finishDrain = resolve;
+ });
+ adapter.dispose.mockImplementationOnce(async () => await draining);
+ const mutation = host.enqueueOptimisticMutation(
+ { query: 'mutation Update { update }', data: { update: true } },
+ { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
+ );
+ await vi.waitFor(() =>
+ expect(
+ adapter.requests.filter(
+ (request) => request.kind === 'enqueue-optimistic-mutation'
+ )
+ ).toHaveLength(1)
+ );
+ const mutationRequest = adapter.requests.find(
+ (request) => request.kind === 'enqueue-optimistic-mutation'
+ );
+
+ host.dispose();
+ host.dispose();
+ expect(adapter.dispose).not.toHaveBeenCalled();
+ adapter.respond(mutationRequest?.id as number, {
+ ...EMPTY_WRITE,
+ transactionId: '4',
+ initialClaim: { kind: 'not-runnable' },
+ });
+
+ await expect(mutation).resolves.toEqual(
+ expect.objectContaining({ transactionId: '4' })
+ );
+ finishDrain?.();
+ await draining;
+ expect(adapter.dispose).toHaveBeenCalledOnce();
+ expect(adapter.dispose).toHaveBeenCalledWith({ graceful: true });
+ await expect(host.clear()).rejects.toThrow(
+ 'cache worker host was disposed'
+ );
+ });
+
+ it('keeps pagehide armed until graceful adapter retirement resolves', async () => {
+ const host = createWorkerCacheHost({ scope: 'scope-1' });
+ await host.clear();
+ const adapter = requireAdapter();
+ let finishRetirement!: () => void;
+ const retirement = new Promise<void>((resolve) => {
+ finishRetirement = resolve;
+ });
+ adapter.dispose.mockImplementationOnce(async () => await retirement);
+
+ host.dispose();
+ expect(adapter.dispose).toHaveBeenCalledWith({ graceful: true });
+ dispatchEvent(new Event('pagehide'));
+
+ expect(adapter.dispose).toHaveBeenNthCalledWith(2, { graceful: false });
+ finishRetirement();
+ await retirement;
+ await expect(host.clear()).rejects.toThrow(
+ 'cache worker host was disposed'
+ );
+ });
+
+ it('quarantines and reports transport failure during adapter retirement', async () => {
+ localStorage.setItem('graphql-cache:scope', 'scope-1');
+ const onInitializationError = vi.fn();
+ const host = createWorkerCacheHost({
+ scope: 'scope-1',
+ onInitializationError,
+ });
+ await host.clear();
+ const adapter = requireAdapter();
+ let finishRetirement!: () => void;
+ const retirement = new Promise<void>((resolve) => {
+ finishRetirement = resolve;
+ });
+ adapter.dispose.mockImplementationOnce(async () => await retirement);
+
+ host.dispose();
+ adapter.terminalError(new Error('SharedWorker failed during retirement'));
+
+ expect(adapter.dispose).toHaveBeenNthCalledWith(2, { graceful: false });
+ await vi.waitFor(() => {
+ expect(localStorage.getItem('graphql-cache:scope')).toBe(
+ 'quarantine:scope-1'
+ );
+ expect(onInitializationError).toHaveBeenCalledOnce();
+ });
+ finishRetirement();
+ await retirement;
+ });
+
+ it('waits for existing read timeout before gracefully disconnecting a requester', async () => {
+ vi.useFakeTimers();
+ configureAdapter = (fake) => fake.ignoredKinds.add('read');
+ const host = createWorkerCacheHost({
+ scope: 'scope-1',
+ requestTimeoutMs: 10,
+ });
+ await host.clear();
+ const adapter = requireAdapter();
+ const read = host.readQuery({ query: 'query Slow { slow }' });
+ const readOutcome = read.then(
+ () => undefined,
+ (error: unknown) => error
+ );
+ await Promise.resolve();
+ expect(adapter.requests.filter(({ kind }) => kind === 'read')).toHaveLength(
+ 1
+ );
+
+ host.dispose();
+ expect(adapter.dispose).not.toHaveBeenCalled();
+ await vi.advanceTimersByTimeAsync(11);
+ await expect(readOutcome).resolves.toMatchObject({
+ message: 'cache worker timeout: read',
+ });
+
+ expect(adapter.dispose).toHaveBeenCalledOnce();
+ expect(adapter.dispose).toHaveBeenCalledWith({ graceful: true });
+ });
+
+ it('preserves transport uncertainty when graceful disposal is already draining admitted work', async () => {
+ configureAdapter = (fake) => {
+ fake.ignoredKinds.add('enqueue-optimistic-mutation');
+ };
+ localStorage.setItem('graphql-cache:scope', 'scope-1');
+ const onInitializationError = vi.fn();
+ const host = createWorkerCacheHost({
+ scope: 'scope-1',
+ onInitializationError,
+ });
+ await host.clear();
+ const adapter = requireAdapter();
+ let finishDrain!: () => void;
+ const draining = new Promise<void>((resolve) => {
+ finishDrain = resolve;
+ });
+ adapter.dispose.mockImplementationOnce(async () => await draining);
+ const mutation = host.enqueueOptimisticMutation(
+ { query: 'mutation Update { update }', data: { update: true } },
+ { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
+ );
+ await vi.waitFor(() =>
+ expect(
+ adapter.requests.filter(
+ ({ kind }) => kind === 'enqueue-optimistic-mutation'
+ )
+ ).toHaveLength(1)
+ );
+
+ host.dispose();
+ adapter.terminalError(new Error('transport failed during drain'));
+ await expect(mutation).rejects.toMatchObject({
+ errorCode: 'admitted-enqueue-uncertain',
+ });
+
+ expect(localStorage.getItem('graphql-cache:scope')).toBe(
+ 'quarantine:scope-1'
+ );
+ expect(onInitializationError).toHaveBeenCalledOnce();
+ finishDrain();
+ await draining;
+ });
+
+ it('treats pagehide as uncertain for an admitted enqueue and quarantines its scope', async () => {
+ configureAdapter = (fake) => {
+ fake.ignoredKinds.add('enqueue-optimistic-mutation');
+ };
+ localStorage.setItem('graphql-cache:scope', 'scope-1');
+ const host = createWorkerCacheHost({ scope: 'scope-1' });
+ await host.clear();
+ const adapter = requireAdapter();
+ const mutation = host.enqueueOptimisticMutation(
+ { query: 'mutation Update { update }', data: { update: true } },
+ { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
+ );
+ const rejected = expect(mutation).rejects.toMatchObject({
+ message: expect.stringContaining('abruptly disposed'),
+ errorCode: 'admitted-enqueue-uncertain',
+ });
+ await vi.waitFor(() =>
+ expect(
+ adapter.requests.filter(
+ ({ kind }) => kind === 'enqueue-optimistic-mutation'
+ )
+ ).toHaveLength(1)
+ );
+
+ host.dispose();
+ expect(adapter.dispose).not.toHaveBeenCalled();
+ dispatchEvent(new Event('pagehide'));
+ await rejected;
+
+ expect(adapter.dispose).toHaveBeenCalledOnce();
+ expect(adapter.dispose).toHaveBeenCalledWith({ graceful: false });
+ await vi.waitFor(() =>
+ expect(localStorage.getItem('graphql-cache:scope')).toBe(
+ 'quarantine:scope-1'
+ )
);
});
});
diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.ts b/apps/web/src/lib/graphql-cache/host/worker-host.ts
index 70c23bead6..e7de02b2fe 100644
--- a/apps/web/src/lib/graphql-cache/host/worker-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/worker-host.ts
@@ -1,18 +1,23 @@
/**
- * Browser CacheHost: talks to the single cache engine in a SharedWorker.
- * Platforms without SharedWorker support receive a storage-free no-op host.
+ * Browser CacheHost: routes cache RPC through the SharedWorker coordinator to
+ * the currently elected dedicated cache engine. Unsupported browsers receive
+ * a storage-free no-op host.
*/
+import { deleteLegacyNormalizedCacheIdb } from '../legacy-idb-cleanup';
import {
+ ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE,
type CachedQueryInstanceWire,
type CachedQueryVariantWire,
- type CacheNotice,
type CacheRequest,
+ type CacheResponseErrorCode,
type ClaimedMutation,
type EnqueueOptimisticMutationResult,
isCachePush,
+ isCacheResponse,
type MutationClaim,
type MutationSettlement,
+ OWNER_EPOCH_LOST_ERROR_CODE,
type ReadRecordsArgs,
type ReadResult,
type SelectedRecordPageWire,
@@ -20,6 +25,20 @@ import {
type WorkerMessage,
type WriteResult,
} from '../protocol';
+import { quarantineCacheScope } from '../scope';
+import {
+ type CacheRolloutCohort,
+ type CacheTelemetryRecorderLike,
+ type CacheTelemetrySink,
+ classifyCacheError,
+ isolateCacheTelemetry,
+ operationCategoryForRequest,
+} from '../telemetry';
+import { createPageCacheTelemetry } from '../telemetry-relay';
+import {
+ type CacheCoordinatorPageAdapter,
+ createCacheCoordinatorPageAdapter,
+} from '../worker/coordinator-page-adapter';
import { createNoopCacheHost } from './noop-host';
import type {
CacheHost,
@@ -34,9 +53,22 @@ import type {
type Pending = {
resolve: (value: unknown) => void;
reject: (error: Error) => void;
+ kind: CacheRequest['kind'];
+ opKey?: number;
+ admitted: boolean;
+ startedAt: number;
timer?: ReturnType<typeof setTimeout>;
};
+type HostState =
+ | 'idle'
+ | 'initializing'
+ | 'awaiting-replacement'
+ | 'ready'
+ | 'disposing'
+ | 'failed'
+ | 'disposed';
+
/** `Omit` that distributes over union members. */
type DistributiveOmit<T, K extends PropertyKey> = T extends unknown
? Omit<T, K>
@@ -51,19 +83,105 @@ export interface WorkerHostOptions {
* operation that may already have completed durably.
*/
requestTimeoutMs?: number;
- /** Reports an asynchronous durable-storage initialization failure. */
+ /**
+ * Registration/initialization timeout in ms. Defaults to requestTimeoutMs,
+ * so callers cannot hang before a read-only request timer can start.
+ */
+ initializationTimeoutMs?: number;
+ /** Reports terminal initialization or coordinator-transport failure. */
onInitializationError?: (error: Error) => void;
+ /** Allowlisted rollout cohort attached to browser-cache telemetry. */
+ rolloutCohort?: CacheRolloutCohort;
+ /** Injectable recorder for deterministic tests or alternate exporters. */
+ telemetry?: CacheTelemetryRecorderLike;
+ /** Injectable final sink; defaults to anonymous OpenTelemetry spans. */
+ telemetrySink?: CacheTelemetrySink;
+ /** Test seams for bounded origin-storage-pressure sampling. */
+ storageHealthIntervalMs?: number;
+ setInterval?: typeof globalThis.setInterval;
+ clearInterval?: typeof globalThis.clearInterval;
}
const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
+const DEFAULT_STORAGE_HEALTH_INTERVAL_MS = 5 * 60_000;
+const MIN_STORAGE_HEALTH_INTERVAL_MS = 1_000;
+const MAX_STORAGE_HEALTH_INTERVAL_MS = 15 * 60_000;
-export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
+function unsupportedBrowserReason(): string | undefined {
if (typeof SharedWorker !== 'function') {
- return createNoopCacheHost('SharedWorker is not supported by this browser');
+ return 'SharedWorker is not supported by this browser';
+ }
+ if (typeof Worker !== 'function') {
+ return 'DedicatedWorker is not supported by this browser';
+ }
+ if (typeof MessageChannel !== 'function') {
+ return 'MessageChannel is not supported by this browser';
+ }
+ if (
+ typeof navigator === 'undefined' ||
+ !navigator.locks ||
+ typeof navigator.locks.request !== 'function'
+ ) {
+ return 'Web Locks are not supported by this browser';
+ }
+ if (
+ !navigator.storage ||
+ typeof navigator.storage.getDirectory !== 'function'
+ ) {
+ return 'OPFS is not supported by this browser';
+ }
+ // Do not probe createSyncAccessHandle here: Chromium and Firefox expose it
+ // only inside DedicatedWorker. Engine initialization reports that async
+ // capability failure through the normal terminal-init path.
+ return undefined;
+}
+
+const asError = (error: unknown): Error =>
+ error instanceof Error ? error : new Error(String(error));
+
+class CacheResponseError extends Error {
+ constructor(
+ message: string,
+ readonly errorCode?: CacheResponseErrorCode
+ ) {
+ super(message);
+ this.name = 'CacheResponseError';
+ }
+}
+
+const isOwnerEpochLoss = (error: unknown): error is CacheResponseError =>
+ error instanceof CacheResponseError &&
+ error.errorCode === OWNER_EPOCH_LOST_ERROR_CODE;
+
+export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
+ const pageTelemetry = options.telemetry
+ ? undefined
+ : createPageCacheTelemetry({
+ rolloutCohort: options.rolloutCohort ?? 'unknown',
+ sink: options.telemetrySink,
+ });
+ const telemetry = isolateCacheTelemetry(
+ options.telemetry ?? pageTelemetry?.recorder
+ );
+ const now = (): number => globalThis.performance?.now() ?? Date.now();
+ const unsupportedReason = unsupportedBrowserReason();
+ if (unsupportedReason) {
+ telemetry?.record({
+ name: 'graphql_cache.host_ready',
+ operationCategory: 'initialization',
+ outcome: 'error',
+ errorCode: 'unsupported',
+ });
+ telemetry?.flush();
+ return createNoopCacheHost(unsupportedReason);
}
const clientId = crypto.randomUUID();
const pending = new Map<number, Pending>();
+ const activeOpKeys = new Set<number>();
+ const registeredOpKeys = new Set<number>();
+ const lostRegisteredOpKeys = new Set<number>();
+ const replacementReadOpKeys = new Set<number>();
const affectedSubscribers = new Set<(opKeys: number[]) => void>();
const cacheChangeSubscribers = new Set<() => void>();
const settlementSubscribers = new Set<
@@ -71,10 +189,53 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
>();
const requestTimeoutMs =
options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+ const initializationTimeoutMs =
+ options.initializationTimeoutMs ?? requestTimeoutMs;
let nextRequestId = 1;
-
- let post: (msg: CacheRequest) => void;
- let dispose: () => void;
+ let state: HostState = 'idle';
+ let initialization: Promise<void> | undefined;
+ let initializationError: Error | undefined;
+ let replacementError: CacheResponseError | undefined;
+ let recoveryInProgress = false;
+ let latestReplacementEpoch = 0;
+ let failureReported = false;
+ let terminalFailureHandled = false;
+ let adapter: CacheCoordinatorPageAdapter | undefined;
+ let adapterDisposePromise: Promise<void> | undefined;
+ let adapterDisposeWasGraceful = false;
+ let adapterDisposalStarted = false;
+ let disposalMode: 'graceful' | 'abrupt' | undefined;
+ let pagehideRegistered = false;
+ let legacyIdbDeletionStarted = false;
+ let telemetryRelayStarted = false;
+ let telemetryFinished = false;
+ let initializationStartedAt = 0;
+ let storageHealthTimer: ReturnType<typeof setInterval> | undefined;
+ const setIntervalFn =
+ options.setInterval ?? globalThis.setInterval.bind(globalThis);
+ const clearIntervalFn =
+ options.clearInterval ?? globalThis.clearInterval.bind(globalThis);
+ const storageHealthIntervalMs = Math.min(
+ Math.max(
+ options.storageHealthIntervalMs ?? DEFAULT_STORAGE_HEALTH_INTERVAL_MS,
+ MIN_STORAGE_HEALTH_INTERVAL_MS
+ ),
+ MAX_STORAGE_HEALTH_INTERVAL_MS
+ );
+
+ const recordRequestOutcome = (
+ entry: Pending,
+ outcome: 'success' | 'error',
+ error?: unknown
+ ): void => {
+ telemetry?.record({
+ name: 'graphql_cache.host_request',
+ operationCategory: operationCategoryForRequest({ kind: entry.kind }),
+ outcome,
+ errorCode: outcome === 'error' ? classifyCacheError(error) : 'none',
+ durationMs: now() - entry.startedAt,
+ });
+ };
const onMessage = (event: MessageEvent<WorkerMessage>) => {
const msg = event.data;
@@ -88,89 +249,506 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
return;
}
const prefix = `${clientId}:`;
- const opKeys = msg.opIds
- .filter((id) => id.startsWith(prefix))
- .map((id) => Number(id.slice(prefix.length)))
- .filter((n) => Number.isFinite(n));
+ const opKeys = [
+ ...new Set(
+ msg.opIds.flatMap((id) => {
+ if (!id.startsWith(prefix)) return [];
+ const suffix = id.slice(prefix.length);
+ const opKey = Number(suffix);
+ return Number.isSafeInteger(opKey) && String(opKey) === suffix
+ ? [opKey]
+ : [];
+ })
+ ),
+ ];
if (opKeys.length > 0) {
for (const cb of affectedSubscribers) cb(opKeys);
}
return;
}
+ if (!isCacheResponse(msg)) return;
const entry = pending.get(msg.id);
if (!entry) return;
+ if (!msg.ok) {
+ const error = new CacheResponseError(msg.error, msg.errorCode);
+ if (isOwnerEpochLoss(error)) observeOwnerEpochLoss(error);
+ pending.delete(msg.id);
+ if (entry.timer !== undefined) clearTimeout(entry.timer);
+ recordRequestOutcome(entry, 'error', error);
+ entry.reject(error);
+ finishGracefulDisposeIfDrained();
+ return;
+ }
pending.delete(msg.id);
if (entry.timer !== undefined) clearTimeout(entry.timer);
- if (msg.ok) {
- entry.resolve(msg.result);
- } else {
- entry.reject(new Error(msg.error));
+ if (
+ entry.kind === 'read' &&
+ entry.opKey !== undefined &&
+ activeOpKeys.has(entry.opKey)
+ ) {
+ registeredOpKeys.add(entry.opKey);
}
+ recordRequestOutcome(entry, 'success');
+ entry.resolve(msg.result);
+ finishGracefulDisposeIfDrained();
};
- let worker: SharedWorker;
- try {
- worker = new SharedWorker(
- new URL('../worker/cache.shared-worker.ts', import.meta.url),
- { type: 'module', name: `graphql-cache:${options.scope}` }
+ function beginRecoveryGeneration(): void {
+ if (recoveryInProgress) return;
+ recoveryInProgress = true;
+ lostRegisteredOpKeys.clear();
+ for (const opKey of registeredOpKeys) lostRegisteredOpKeys.add(opKey);
+ registeredOpKeys.clear();
+ }
+
+ function markPendingReads(target: Set<number>): void {
+ for (const entry of pending.values()) {
+ if (entry.kind === 'read' && entry.opKey !== undefined) {
+ target.add(entry.opKey);
+ }
+ }
+ }
+
+ function emitAffectedKeys(opKeys: number[]): void {
+ if (opKeys.length === 0) return;
+ for (const cb of affectedSubscribers) cb(opKeys);
+ }
+
+ function onEngineReplaced(ownerEpoch: number): void {
+ if (state === 'failed' || state === 'disposing' || state === 'disposed') {
+ return;
+ }
+ if (ownerEpoch <= latestReplacementEpoch) return;
+ latestReplacementEpoch = ownerEpoch;
+ // Initial readiness completes the already-running first handshake.
+ if (state === 'initializing' && !recoveryInProgress) return;
+ if (state === 'ready') {
+ beginRecoveryGeneration();
+ // No old response put this host into recovery. Requests still pending at
+ // replacement broadcast were queued by the coordinator while resetting
+ // and will be routed exactly once to this replacement generation.
+ markPendingReads(replacementReadOpKeys);
+ }
+ if (state !== 'ready' && state !== 'awaiting-replacement') return;
+ void startInitialization().catch(() => undefined);
+ }
+
+ function observeOwnerEpochLoss(error: CacheResponseError): void {
+ if (state === 'failed' || state === 'disposing' || state === 'disposed') {
+ return;
+ }
+ beginRecoveryGeneration();
+ // A rejected old-epoch read may have registered dependencies before its
+ // response was lost. It belongs to the lost generation, not replacement.
+ markPendingReads(lostRegisteredOpKeys);
+ replacementError = error;
+ initialization = undefined;
+ state = 'awaiting-replacement';
+ }
+
+ function unregisterPagehide(): void {
+ if (!pagehideRegistered || typeof removeEventListener !== 'function') {
+ return;
+ }
+ removeEventListener('pagehide', onPagehide);
+ pagehideRegistered = false;
+ }
+
+ function registerPagehide(): void {
+ if (pagehideRegistered || typeof addEventListener !== 'function') return;
+ pagehideRegistered = true;
+ addEventListener('pagehide', onPagehide, { once: true });
+ }
+
+ function getAdapter(): CacheCoordinatorPageAdapter {
+ if (adapter) return adapter;
+ if (!telemetryRelayStarted) {
+ telemetryRelayStarted = true;
+ pageTelemetry?.relay.start();
+ }
+ const created = createCacheCoordinatorPageAdapter({
+ scope: options.scope,
+ hotCapacity: options.hotCapacity,
+ onEngineReplaced,
+ onTerminalError: failTransport,
+ telemetry,
+ });
+ created.onmessage = onMessage;
+ adapter = created;
+ registerPagehide();
+ return created;
+ }
+
+ function startLegacyIdbDeletion(): void {
+ if (legacyIdbDeletionStarted) return;
+ legacyIdbDeletionStarted = true;
+ // Cutover cleanup must never delay cache startup or any cache RPC.
+ void deleteLegacyNormalizedCacheIdb(options.scope);
+ }
+
+ function rejectPending(error: Error, transportUncertain = false): void {
+ const entries = [...pending.values()];
+ pending.clear();
+ for (const entry of entries) {
+ if (entry.timer !== undefined) clearTimeout(entry.timer);
+ recordRequestOutcome(entry, 'error', error);
+ if (
+ transportUncertain &&
+ entry.admitted &&
+ entry.kind === 'enqueue-optimistic-mutation'
+ ) {
+ entry.reject(
+ new CacheResponseError(
+ `${error.message}: admitted optimistic enqueue outcome is uncertain`,
+ ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE
+ )
+ );
+ } else {
+ entry.reject(error);
+ }
+ }
+ }
+
+ function disposeAdapter(graceful: boolean): Promise<void> {
+ if (adapterDisposePromise) {
+ if (!graceful && adapterDisposeWasGraceful && adapter) {
+ adapterDisposeWasGraceful = false;
+ try {
+ // A pagehide during graceful retirement must reach the adapter so it
+ // can terminate and close instead of memoizing the old mode.
+ void adapter.dispose({ graceful: false });
+ } catch {
+ // The original disposal promise still owns final settlement.
+ }
+ }
+ return adapterDisposePromise;
+ }
+ if (!adapter) return Promise.resolve();
+ adapterDisposeWasGraceful = graceful;
+ try {
+ adapterDisposePromise = adapter
+ .dispose({ graceful })
+ .catch(() => undefined);
+ } catch {
+ // The host is already closed and cannot safely retry disposal.
+ adapterDisposePromise = Promise.resolve();
+ }
+ return adapterDisposePromise;
+ }
+
+ function clearSubscribers(): void {
+ affectedSubscribers.clear();
+ cacheChangeSubscribers.clear();
+ settlementSubscribers.clear();
+ }
+
+ function reportFailure(error: Error): void {
+ if (failureReported) return;
+ failureReported = true;
+ options.onInitializationError?.(error);
+ }
+
+ function failInitialization(error: Error): void {
+ if (state === 'failed' || state === 'disposed' || state === 'ready') return;
+ telemetry?.record({
+ name: 'graphql_cache.host_ready',
+ operationCategory: 'initialization',
+ outcome: 'error',
+ errorCode: classifyCacheError(error),
+ durationMs:
+ initializationStartedAt > 0 ? now() - initializationStartedAt : 0,
+ });
+ state = 'failed';
+ initialization = undefined;
+ initializationError = error;
+ rejectPending(error);
+ clearSubscribers();
+ unregisterPagehide();
+ void disposeAdapter(false).then(finishTelemetry);
+ reportFailure(error);
+ }
+
+ function hasAdmittedEnqueue(): boolean {
+ return [...pending.values()].some(
+ (entry) => entry.admitted && entry.kind === 'enqueue-optimistic-mutation'
);
- worker.port.onmessage = onMessage;
- worker.port.start();
- } catch {
- return createNoopCacheHost('SharedWorker could not be initialized');
- }
- post = (msg) => worker.port.postMessage(msg);
- dispose = () => {
- // Tell the SharedWorker to drop our port — there is no platform
- // disconnect event, and stale ports would otherwise accumulate.
- const notice: CacheNotice = { kind: 'disconnect' };
- worker.port.postMessage(notice);
- worker.port.close();
- };
+ }
+
+ function failTransport(error: Error): void {
+ if (terminalFailureHandled) return;
+ stopStorageHealthSampling();
+ const admittedWorkIsUncertain = [...pending.values()].some(
+ (entry) => entry.admitted
+ );
+ if (state === 'disposed' && !admittedWorkIsUncertain) return;
+ terminalFailureHandled = true;
+ state = 'failed';
+ initialization = undefined;
+ initializationError = error;
+ rejectPending(error, true);
+ clearSubscribers();
+ unregisterPagehide();
+ void disposeAdapter(false).then(finishTelemetry);
+ // Product failure handling may immediately construct another host. Make
+ // the matching old scope unreachable before invoking that callback.
+ void quarantineCacheScope(options.scope).then(() => {
+ try {
+ reportFailure(error);
+ } catch {
+ // Failure reporting cannot reopen or invalidate completed quarantine.
+ }
+ });
+ }
+
+ function stopStorageHealthSampling(): void {
+ if (storageHealthTimer === undefined) return;
+ clearIntervalFn(storageHealthTimer);
+ storageHealthTimer = undefined;
+ }
+
+ function finishTelemetry(): void {
+ if (telemetryFinished) return;
+ stopStorageHealthSampling();
+ telemetryFinished = true;
+ telemetry?.flush();
+ pageTelemetry?.relay.dispose();
+ }
+
+ function startAdapterDisposal(graceful: boolean): void {
+ if (adapterDisposalStarted) {
+ if (!graceful) void disposeAdapter(false);
+ return;
+ }
+ adapterDisposalStarted = true;
+ void disposeAdapter(graceful).then(() => {
+ if (state !== 'disposing') return;
+ state = 'disposed';
+ unregisterPagehide();
+ finishTelemetry();
+ });
+ }
+
+ function finishGracefulDisposeIfDrained(): void {
+ if (
+ state !== 'disposing' ||
+ disposalMode !== 'graceful' ||
+ pending.size > 0
+ ) {
+ return;
+ }
+ startAdapterDisposal(true);
+ }
+
+ function disposeHost(graceful: boolean): void {
+ stopStorageHealthSampling();
+ if (state === 'disposed') return;
+ if (state === 'disposing') {
+ if (graceful || disposalMode === 'abrupt') return;
+ disposalMode = 'abrupt';
+ const quarantine = hasAdmittedEnqueue();
+ clearSubscribers();
+ if (quarantine) void quarantineCacheScope(options.scope);
+ rejectPending(new Error('cache worker host was abruptly disposed'), true);
+ startAdapterDisposal(false);
+ return;
+ }
+ if (graceful && state === 'ready') {
+ // Stop admission first, but keep the requester/standby connected until
+ // every already-admitted RPC has a response or its existing read timer.
+ // Mutations deliberately have no arbitrary disposal timeout.
+ state = 'disposing';
+ disposalMode = 'graceful';
+ clearSubscribers();
+ // Keep pagehide armed through coordinator retirement so an abrupt close
+ // can still terminate the adapter's in-progress graceful drain.
+ finishGracefulDisposeIfDrained();
+ return;
+ }
+
+ const quarantine = hasAdmittedEnqueue();
+ state = 'disposing';
+ disposalMode = 'abrupt';
+ clearSubscribers();
+ if (quarantine) void quarantineCacheScope(options.scope);
+ rejectPending(new Error('cache worker host was abruptly disposed'), true);
+ startAdapterDisposal(false);
+ }
- // Best-effort cleanup when the page goes away (bfcache-safe: a restored
- // page gets a fresh host on next use anyway).
- if (typeof addEventListener === 'function') {
- addEventListener('pagehide', dispose, { once: true });
+ function onPagehide(): void {
+ disposeHost(false);
}
function request(
- msg: DistributiveOmit<CacheRequest, 'id'>
+ msg: DistributiveOmit<CacheRequest, 'id'>,
+ opKey?: number
): Promise<unknown> {
+ if (state === 'failed') {
+ return Promise.reject(
+ initializationError ?? new Error('cache worker initialization failed')
+ );
+ }
+ if (state === 'disposing' || state === 'disposed') {
+ return Promise.reject(new Error('cache worker host was disposed'));
+ }
+
const id = nextRequestId++;
return new Promise((resolve, reject) => {
- const entry: Pending = { resolve, reject };
- if (
- msg.kind === 'read' ||
- msg.kind === 'read-records' ||
- msg.kind === 'inspect-query' ||
- msg.kind === 'inspect-query-variants'
- ) {
+ const entry: Pending = {
+ resolve,
+ reject,
+ kind: msg.kind,
+ opKey,
+ admitted: false,
+ startedAt: now(),
+ };
+ const timeoutMs =
+ msg.kind === 'init'
+ ? initializationTimeoutMs
+ : msg.kind === 'read' ||
+ msg.kind === 'read-records' ||
+ msg.kind === 'inspect-query' ||
+ msg.kind === 'inspect-query-variants'
+ ? requestTimeoutMs
+ : undefined;
+ if (timeoutMs !== undefined) {
entry.timer = setTimeout(() => {
if (pending.delete(id)) {
- reject(new Error(`cache worker timeout: ${msg.kind}`));
+ const error = new Error(`cache worker timeout: ${msg.kind}`);
+ recordRequestOutcome(entry, 'error', error);
+ reject(error);
+ finishGracefulDisposeIfDrained();
}
- }, requestTimeoutMs);
+ }, timeoutMs);
}
pending.set(id, entry);
- post({ ...msg, id } as CacheRequest);
+ try {
+ getAdapter().postMessage({ ...msg, id } as CacheRequest);
+ // The first accepted coordinator send is the browser Turso host's
+ // actual lazy start. Only then begin fire-and-forget legacy cleanup.
+ startLegacyIdbDeletion();
+ if (pending.has(id)) entry.admitted = true;
+ } catch (error) {
+ if (pending.delete(id) && entry.timer !== undefined) {
+ clearTimeout(entry.timer);
+ }
+ const requestError = asError(error);
+ recordRequestOutcome(entry, 'error', requestError);
+ reject(requestError);
+ }
});
}
- const ready = request({
- kind: 'init',
- scope: options.scope,
- hotCapacity: options.hotCapacity,
- });
- void (async () => {
+ async function observeStorageHealth(): Promise<void> {
try {
- await ready;
+ const storage = navigator.storage;
+ const [estimate, persisted] = await Promise.all([
+ storage.estimate(),
+ typeof storage.persisted === 'function'
+ ? storage.persisted()
+ : Promise.resolve(undefined),
+ ]);
+ const usageBytes = estimate.usage;
+ const quotaBytes = estimate.quota;
+ telemetry?.record({
+ name: 'graphql_cache.origin_storage_pressure',
+ operationCategory: 'storage',
+ outcome: 'success',
+ persistence:
+ persisted === true
+ ? 'granted'
+ : persisted === false
+ ? 'denied'
+ : 'unknown',
+ usageBytes,
+ quotaBytes,
+ ratio:
+ usageBytes !== undefined && quotaBytes !== undefined && quotaBytes > 0
+ ? usageBytes / quotaBytes
+ : undefined,
+ });
} catch (error) {
- options.onInitializationError?.(
- error instanceof Error ? error : new Error(String(error))
+ telemetry?.record({
+ name: 'graphql_cache.origin_storage_pressure',
+ operationCategory: 'storage',
+ outcome: 'error',
+ errorCode: classifyCacheError(error),
+ persistence: 'unknown',
+ });
+ }
+ }
+
+ function startStorageHealthSampling(): void {
+ void observeStorageHealth();
+ storageHealthTimer ??= setIntervalFn(() => {
+ void observeStorageHealth();
+ }, storageHealthIntervalMs);
+ }
+
+ function startInitialization(): Promise<void> {
+ state = 'initializing';
+ replacementError = undefined;
+ initializationStartedAt = now();
+ const handshake = request({
+ kind: 'init',
+ scope: options.scope,
+ hotCapacity: options.hotCapacity,
+ }).then(
+ () => {
+ if (state !== 'initializing') return;
+ state = 'ready';
+ initialization = undefined;
+ telemetry?.record({
+ name: 'graphql_cache.host_ready',
+ operationCategory: 'initialization',
+ outcome: 'success',
+ errorCode: 'none',
+ durationMs: now() - initializationStartedAt,
+ });
+ startStorageHealthSampling();
+ if (recoveryInProgress) {
+ const opKeys = [...lostRegisteredOpKeys].filter(
+ (opKey) =>
+ activeOpKeys.has(opKey) && !replacementReadOpKeys.has(opKey)
+ );
+ recoveryInProgress = false;
+ lostRegisteredOpKeys.clear();
+ replacementReadOpKeys.clear();
+ emitAffectedKeys(opKeys);
+ }
+ },
+ (error: unknown) => {
+ const initializationFailure = asError(error);
+ initialization = undefined;
+ if (isOwnerEpochLoss(initializationFailure)) {
+ observeOwnerEpochLoss(initializationFailure);
+ } else {
+ failInitialization(initializationFailure);
+ }
+ throw initializationFailure;
+ }
+ );
+ initialization = handshake;
+ return handshake;
+ }
+
+ function ensureInitialized(): Promise<void> {
+ if (state === 'ready') return Promise.resolve();
+ if (state === 'initializing' && initialization) return initialization;
+ if (state === 'awaiting-replacement') {
+ return Promise.reject(
+ replacementError ?? new Error('cache worker is awaiting replacement')
+ );
+ }
+ if (state === 'failed') {
+ return Promise.reject(
+ initializationError ?? new Error('cache worker initialization failed')
);
}
- })();
+ if (state === 'disposing' || state === 'disposed') {
+ return Promise.reject(new Error('cache worker host was disposed'));
+ }
+ return startInitialization();
+ }
const opId = (opKey: number) => `${clientId}:${opKey}`;
@@ -178,21 +756,28 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
clientId,
async readQuery(args: CacheReadArgs): Promise<ReadResult> {
- await ready;
- return (await request({
- kind: 'read',
- opId: args.opKey === undefined ? undefined : opId(args.opKey),
- query: args.query,
- operationName: args.operationName,
- variables: args.variables,
- priority: args.priority,
- entityResolvers: args.entityResolvers,
- })) as ReadResult;
+ if (args.opKey !== undefined) {
+ activeOpKeys.add(args.opKey);
+ if (recoveryInProgress) replacementReadOpKeys.add(args.opKey);
+ }
+ await ensureInitialized();
+ return (await request(
+ {
+ kind: 'read',
+ opId: args.opKey === undefined ? undefined : opId(args.opKey),
+ query: args.query,
+ operationName: args.operationName,
+ variables: args.variables,
+ priority: args.priority,
+ entityResolvers: args.entityResolvers,
+ },
+ args.opKey
+ )) as ReadResult;
},
async readRecords(args: ReadRecordsArgs): Promise<SelectedRecordPageWire> {
const limit = validateRecordSelectionLimit(args.limit);
- await ready;
+ await ensureInitialized();
return (await request({
kind: 'read-records',
document: args.document,
@@ -203,7 +788,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
},
async writeQuery(args: CacheWriteArgs): Promise<WriteResult> {
- await ready;
+ await ensureInitialized();
return (await request({
kind: 'write',
originOpId: args.opKey === undefined ? undefined : opId(args.opKey),
@@ -219,7 +804,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
args: EnqueueOptimisticMutationArgs,
claim: InitialMutationClaimArgs
): Promise<EnqueueOptimisticMutationResult> {
- await ready;
+ await ensureInitialized();
return (await request({
kind: 'enqueue-optimistic-mutation',
originOpId: args.opKey === undefined ? undefined : opId(args.opKey),
@@ -239,7 +824,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
async inspectQueryVariants(
args: InspectQueryVariantsArgs
): Promise<CachedQueryVariantWire[]> {
- await ready;
+ await ensureInitialized();
return (await request({
kind: 'inspect-query-variants',
query: args.query,
@@ -251,7 +836,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
async inspectQuery(
args: InspectQueryArgs
): Promise<CachedQueryInstanceWire[]> {
- await ready;
+ await ensureInitialized();
return (await request({
kind: 'inspect-query',
query: args.query,
@@ -266,7 +851,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
nowMs: number,
leaseExpiresAtMs: number
): Promise<ClaimedMutation | undefined> {
- await ready;
+ await ensureInitialized();
return (await request({
kind: 'claim-next-mutation',
owner,
@@ -281,7 +866,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
nextAttemptAtMs: number,
error: string
): Promise<void> {
- await ready;
+ await ensureInitialized();
await request({
kind: 'defer-optimistic-write',
transactionId,
@@ -297,7 +882,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
claim: MutationClaim,
args: CacheWriteArgs
): Promise<WriteResult> {
- await ready;
+ await ensureInitialized();
return (await request({
kind: 'commit-optimistic-write',
transactionId,
@@ -315,7 +900,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
claim: MutationClaim,
error: string
): Promise<WriteResult> {
- await ready;
+ await ensureInitialized();
return (await request({
kind: 'rollback-optimistic-write',
transactionId,
@@ -326,23 +911,34 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
},
async invalidate(keys: string[]): Promise<string[]> {
- await ready;
+ await ensureInitialized();
return (await request({ kind: 'invalidate', keys })) as string[];
},
async deleteRecords(keys: string[]): Promise<string[]> {
- await ready;
+ await ensureInitialized();
return (await request({ kind: 'delete-records', keys })) as string[];
},
async teardown(opKey: number): Promise<void> {
- await ready;
+ activeOpKeys.delete(opKey);
+ registeredOpKeys.delete(opKey);
+ lostRegisteredOpKeys.delete(opKey);
+ replacementReadOpKeys.delete(opKey);
+ await ensureInitialized();
await request({ kind: 'teardown', opId: opId(opKey) });
},
async clear(): Promise<void> {
- await ready;
+ await ensureInitialized();
await request({ kind: 'clear' });
+ telemetry?.record({
+ name: 'graphql_cache.logical_reset',
+ operationCategory: 'lifecycle',
+ outcome: 'success',
+ errorCode: 'none',
+ resetReason: 'explicit-clear',
+ });
},
onOpsAffected(cb: (opKeys: number[]) => void): () => void {
@@ -363,10 +959,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
},
dispose() {
- affectedSubscribers.clear();
- cacheChangeSubscribers.clear();
- settlementSubscribers.clear();
- dispose();
+ disposeHost(true);
},
};
}
diff --git a/apps/web/src/lib/graphql-cache/legacy-idb-cleanup.test.ts b/apps/web/src/lib/graphql-cache/legacy-idb-cleanup.test.ts
new file mode 100644
index 0000000000..f8d3cc1ffa
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/legacy-idb-cleanup.test.ts
@@ -0,0 +1,132 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { deleteLegacyNormalizedCacheIdb } from './legacy-idb-cleanup';
+
+type MutableDeleteRequest = Pick<
+ IDBOpenDBRequest,
+ 'onblocked' | 'onerror' | 'onsuccess'
+>;
+
+function deleteRequest(): MutableDeleteRequest {
+ return {
+ onblocked: null,
+ onerror: null,
+ onsuccess: null,
+ };
+}
+
+function dispatch(
+ request: MutableDeleteRequest,
+ kind: 'blocked' | 'error' | 'success'
+): ReturnType<typeof vi.fn> {
+ const preventDefault = vi.fn();
+ const event = { type: kind, preventDefault } as unknown as Event;
+ const handler =
+ kind === 'blocked'
+ ? request.onblocked
+ : kind === 'error'
+ ? request.onerror
+ : request.onsuccess;
+ handler?.call(request as IDBOpenDBRequest, event);
+ return preventDefault;
+}
+
+describe('deleteLegacyNormalizedCacheIdb', () => {
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ vi.restoreAllMocks();
+ });
+
+ it('deletes only the exact former database name without opening or enumerating IDB', async () => {
+ const request = deleteRequest();
+ const deleteDatabase = vi.fn(() => request);
+ const open = vi.fn();
+ const databases = vi.fn();
+ vi.stubGlobal('indexedDB', { deleteDatabase, open, databases });
+
+ const attempt = deleteLegacyNormalizedCacheIdb('scope:s1:v2');
+
+ expect(deleteDatabase).toHaveBeenCalledOnce();
+ expect(deleteDatabase).toHaveBeenCalledWith('graphql-cache:scope:s1:v2');
+ expect(open).not.toHaveBeenCalled();
+ expect(databases).not.toHaveBeenCalled();
+ expect(deleteDatabase).not.toHaveBeenCalledWith(
+ 'unrelated-idb:scope:s1:v2'
+ );
+ dispatch(request, 'success');
+ await expect(attempt).resolves.toBeUndefined();
+ });
+
+ it('settles on blocked while allowing the same request to complete later', async () => {
+ const request = deleteRequest();
+ vi.stubGlobal('indexedDB', {
+ deleteDatabase: vi.fn(() => request),
+ });
+ const attempt = deleteLegacyNormalizedCacheIdb('blocked-scope');
+
+ expect(dispatch(request, 'blocked')).not.toHaveBeenCalled();
+ await expect(attempt).resolves.toBeUndefined();
+
+ expect(() => dispatch(request, 'success')).not.toThrow();
+ const preventDefault = dispatch(request, 'error');
+ expect(preventDefault).toHaveBeenCalledOnce();
+ });
+
+ it('settles and suppresses an IndexedDB request error', async () => {
+ const request = deleteRequest();
+ vi.stubGlobal('indexedDB', {
+ deleteDatabase: vi.fn(() => request),
+ });
+ const attempt = deleteLegacyNormalizedCacheIdb('error-scope');
+
+ const preventDefault = dispatch(request, 'error');
+
+ expect(preventDefault).toHaveBeenCalledOnce();
+ await expect(attempt).resolves.toBeUndefined();
+ });
+
+ it.each([
+ ['missing API', undefined],
+ [
+ 'synchronous deletion failure',
+ {
+ deleteDatabase: vi.fn(() => {
+ throw new DOMException('denied', 'SecurityError');
+ }),
+ },
+ ],
+ ])('settles when IndexedDB is unavailable: %s', async (label, factory) => {
+ vi.stubGlobal('indexedDB', factory);
+
+ await expect(
+ deleteLegacyNormalizedCacheIdb(`unavailable-${label}`)
+ ).resolves.toBeUndefined();
+ });
+
+ it('attempts deletion once per scope for the module session', async () => {
+ const firstRequest = deleteRequest();
+ const secondRequest = deleteRequest();
+ const deleteDatabase = vi
+ .fn()
+ .mockReturnValueOnce(firstRequest)
+ .mockReturnValueOnce(secondRequest);
+ vi.stubGlobal('indexedDB', { deleteDatabase });
+
+ const first = deleteLegacyNormalizedCacheIdb('same-scope');
+ const duplicate = deleteLegacyNormalizedCacheIdb('same-scope');
+ expect(duplicate).toBe(first);
+ expect(deleteDatabase).toHaveBeenCalledOnce();
+ dispatch(firstRequest, 'success');
+ await first;
+
+ await deleteLegacyNormalizedCacheIdb('same-scope');
+ expect(deleteDatabase).toHaveBeenCalledOnce();
+
+ const other = deleteLegacyNormalizedCacheIdb('other-scope');
+ expect(deleteDatabase).toHaveBeenNthCalledWith(
+ 2,
+ 'graphql-cache:other-scope'
+ );
+ dispatch(secondRequest, 'success');
+ await other;
+ });
+});
diff --git a/apps/web/src/lib/graphql-cache/legacy-idb-cleanup.ts b/apps/web/src/lib/graphql-cache/legacy-idb-cleanup.ts
new file mode 100644
index 0000000000..89e9a8d61b
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/legacy-idb-cleanup.ts
@@ -0,0 +1,43 @@
+/**
+ * Best-effort removal of the normalized cache's former IndexedDB database.
+ *
+ * Cutover never opens, enumerates, or migrates the old database. A blocked
+ * deletion settles immediately for callers while the browser remains free to
+ * complete the same request after an old tab releases its connection.
+ */
+
+const deletionAttempts = new Map<string, Promise<void>>();
+
+/** Deletes exactly the former `graphql-cache:<scope>` database once per page session. */
+export function deleteLegacyNormalizedCacheIdb(scope: string): Promise<void> {
+ const existing = deletionAttempts.get(scope);
+ if (existing) return existing;
+
+ const attempt = new Promise<void>((resolve) => {
+ try {
+ const factory = globalThis.indexedDB;
+ if (!factory || typeof factory.deleteDatabase !== 'function') {
+ resolve();
+ return;
+ }
+
+ const request = factory.deleteDatabase(`graphql-cache:${scope}`);
+ let settled = false;
+ const settle = (event: Event): void => {
+ // Keep this handler installed after `blocked`: the same request can
+ // later fail, and preventing its error avoids an uncaught global event.
+ if (event.type === 'error') event.preventDefault();
+ if (settled) return;
+ settled = true;
+ resolve();
+ };
+ request.onsuccess = settle;
+ request.onerror = settle;
+ request.onblocked = settle;
+ } catch {
+ resolve();
+ }
+ });
+ deletionAttempts.set(scope, attempt);
+ return attempt;
+}
diff --git a/apps/web/src/lib/graphql-cache/lifecycle.test.ts b/apps/web/src/lib/graphql-cache/lifecycle.test.ts
index f25180ddf5..0f2664e866 100644
--- a/apps/web/src/lib/graphql-cache/lifecycle.test.ts
+++ b/apps/web/src/lib/graphql-cache/lifecycle.test.ts
@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import type { CacheHost } from './host/types';
function hostWithClear(clear: () => Promise<void>): CacheHost {
@@ -12,6 +12,10 @@ describe('clearRegisteredCaches', () => {
vi.resetModules();
});
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ });
+
it('preserves the scope when every cache clears', async () => {
localStorage.setItem('graphql-cache:scope', 'current-scope');
const clear = vi.fn().mockResolvedValue(undefined);
@@ -26,6 +30,51 @@ describe('clearRegisteredCaches', () => {
expect(localStorage.getItem('graphql-cache:scope')).toBe('current-scope');
});
+ it('awaits the serialized scope rotation before logout clearing resolves', async () => {
+ localStorage.setItem('graphql-cache:scope', 'current-scope');
+ vi.spyOn(crypto, 'randomUUID').mockReturnValue(
+ '00000000-0000-4000-8000-000000000002'
+ );
+ let enterLock!: () => void;
+ const lockGate = new Promise<void>((resolve) => {
+ enterLock = resolve;
+ });
+ vi.stubGlobal('navigator', {
+ locks: {
+ request: vi.fn(
+ async (
+ name: string,
+ _options: LockOptions,
+ callback: (lock: Lock | null) => unknown
+ ) => {
+ await lockGate;
+ return await callback({ name, mode: 'exclusive' } as Lock);
+ }
+ ),
+ },
+ });
+ const { clearRegisteredCaches, registerCacheHost } = await import(
+ './lifecycle'
+ );
+ registerCacheHost(
+ hostWithClear(async () => await Promise.reject(new Error('wipe failed')))
+ );
+ let settled = false;
+
+ const clearing = clearRegisteredCaches().then(() => {
+ settled = true;
+ });
+ await Promise.resolve();
+ expect(settled).toBe(false);
+ expect(localStorage.getItem('graphql-cache:scope')).toBe('current-scope');
+ enterLock();
+ await clearing;
+
+ expect(localStorage.getItem('graphql-cache:scope')).toBe(
+ '00000000-0000-4000-8000-000000000002'
+ );
+ });
+
it('rotates the scope after attempting every clear when one fails', async () => {
localStorage.setItem('graphql-cache:scope', 'current-scope');
vi.spyOn(crypto, 'randomUUID').mockReturnValue(
diff --git a/apps/web/src/lib/graphql-cache/lifecycle.ts b/apps/web/src/lib/graphql-cache/lifecycle.ts
index 30cbe78196..c4c6ee31e1 100644
--- a/apps/web/src/lib/graphql-cache/lifecycle.ts
+++ b/apps/web/src/lib/graphql-cache/lifecycle.ts
@@ -9,12 +9,12 @@ export function registerCacheHost(host: CacheHost): () => void {
return () => hosts.delete(host);
}
-/** Best-effort wipe of records and queued user intent during logout. */
+/** Best-effort reset of each active cache database during logout. */
export async function clearRegisteredCaches(): Promise<void> {
const results = await Promise.allSettled(
[...hosts].map((host) => host.clear())
);
if (results.some((result) => result.status === 'rejected')) {
- rotateCacheScope();
+ await rotateCacheScope();
}
}
diff --git a/apps/web/src/lib/graphql-cache/protocol.test.ts b/apps/web/src/lib/graphql-cache/protocol.test.ts
index e974760404..de01eafe18 100644
--- a/apps/web/src/lib/graphql-cache/protocol.test.ts
+++ b/apps/web/src/lib/graphql-cache/protocol.test.ts
@@ -1,5 +1,8 @@
import { describe, expect, it } from 'vitest';
import {
+ isCachePush,
+ isCacheResponse,
+ isWorkerMessage,
MAX_RECORD_SELECTION_PAGE_SIZE,
validateRecordSelectionLimit,
} from './protocol';
@@ -25,3 +28,66 @@ describe('validateRecordSelectionLimit', () => {
);
});
});
+
+describe('cache worker message validators', () => {
+ it('accepts exact responses and every typed push', () => {
+ const values = [
+ { id: 1, ok: true, result: { kind: 'miss' } },
+ { id: 2, ok: false, error: 'failed' },
+ {
+ id: 3,
+ ok: false,
+ error: 'old owner failed',
+ errorCode: 'owner-epoch-lost',
+ },
+ {
+ id: 4,
+ ok: false,
+ error: 'enqueue response uncertain',
+ errorCode: 'admitted-enqueue-uncertain',
+ },
+ { kind: 'ops-affected', opIds: ['client:7'], keys: ['User:1'] },
+ { kind: 'cache-changed' },
+ {
+ kind: 'mutation-settled',
+ settlement: { transactionId: '3', status: 'committed' },
+ },
+ {
+ kind: 'mutation-settled',
+ settlement: {
+ transactionId: '4',
+ status: 'permanently-failed',
+ error: 'denied',
+ },
+ },
+ ];
+
+ expect(values.map(isWorkerMessage)).toEqual(values.map(() => true));
+ expect(isCacheResponse(values[0])).toBe(true);
+ expect(isCachePush(values[4])).toBe(true);
+ });
+
+ it.each([
+ null,
+ [],
+ 'push',
+ 7,
+ { id: -1, ok: true, result: null },
+ { id: 1, ok: true },
+ { id: 1, ok: false, error: 'failed', extra: true },
+ { id: 1, ok: false, error: 'failed', errorCode: 'future-code' },
+ { kind: 'ops-affected', opIds: [7], keys: [] },
+ { kind: 'ops-affected', opIds: [], keys: [], extra: true },
+ { kind: 'cache-changed', keys: [] },
+ {
+ kind: 'mutation-settled',
+ settlement: { transactionId: '3', status: 'committed', error: 'extra' },
+ },
+ {
+ kind: 'mutation-settled',
+ settlement: { transactionId: '4', status: 'permanently-failed' },
+ },
+ ])('rejects malformed or extended worker message %#', (value) => {
+ expect(isWorkerMessage(value)).toBe(false);
+ });
+});
diff --git a/apps/web/src/lib/graphql-cache/protocol.ts b/apps/web/src/lib/graphql-cache/protocol.ts
index dd0ada45ec..f6b079a9ff 100644
--- a/apps/web/src/lib/graphql-cache/protocol.ts
+++ b/apps/web/src/lib/graphql-cache/protocol.ts
@@ -4,8 +4,9 @@ import type { EntityResolverWire } from './exchange/entity-resolvers';
* Wire protocol between page contexts and the cache worker (the `CacheHost`
* RPC from the design doc, apps/web/docs/graphql-normalized-cache-plan.md §4).
*
- * The browser topology is one SharedWorker engine serving many page ports.
- * Platforms without SharedWorker support use a storage-free no-op host.
+ * The browser topology routes page ports through a SharedWorker coordinator
+ * to one elected DedicatedWorker engine. Platforms missing the required
+ * coordinator capabilities use a storage-free no-op host.
*
* Operation ids are strings of the form `"{clientId}:{urqlOperationKey}"` so
* one shared engine can track operations from many tabs without collisions.
@@ -282,23 +283,27 @@ export type CacheRequest = { id: number } & (
| { kind: 'clear' }
);
-export type CacheResponse =
- | { id: number; ok: true; result: unknown }
- | { id: number; ok: false; error: string };
+/** Stable machine-readable cache RPC rejection codes. */
+export type CacheResponseErrorCode =
+ | 'owner-epoch-lost'
+ | 'admitted-enqueue-uncertain';
-/**
- * Fire-and-forget notice from a client to the worker (no id/response).
- * `disconnect` lets a SharedWorker drop the sender's port — there is no
- * platform event for client disconnection, so hosts send this on dispose
- * and pagehide.
- */
-export type CacheNotice = { kind: 'disconnect' };
+/** Old-owner work was rejected after fenced engine loss and was not replayed. */
+export const OWNER_EPOCH_LOST_ERROR_CODE: CacheResponseErrorCode =
+ 'owner-epoch-lost';
-export function isCacheNotice(
- msg: CacheRequest | CacheNotice
-): msg is CacheNotice {
- return msg.kind === 'disconnect';
-}
+/** An enqueue send was admitted before its unfenced transport became uncertain. */
+export const ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE: CacheResponseErrorCode =
+ 'admitted-enqueue-uncertain';
+
+export type CacheResponse =
+ | { id: number; ok: true; result: unknown }
+ | {
+ id: number;
+ ok: false;
+ error: string;
+ errorCode?: CacheResponseErrorCode;
+ };
/**
* Pushed (not request/response) messages from worker to its client(s):
@@ -317,6 +322,100 @@ export type CachePush =
export type WorkerMessage = CacheResponse | CachePush;
-export function isCachePush(msg: WorkerMessage): msg is CachePush {
- return 'kind' in msg;
+type UnknownWireRecord = Record<string, unknown>;
+
+const isWireRecord = (value: unknown): value is UnknownWireRecord =>
+ typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const hasOnlyWireKeys = (
+ value: UnknownWireRecord,
+ keys: readonly string[]
+): boolean => Object.keys(value).every((key) => keys.includes(key));
+
+const isWireStringArray = (value: unknown): value is string[] =>
+ Array.isArray(value) && value.every((item) => typeof item === 'string');
+
+/** Strictly validates a machine-readable cache response error code. */
+export const isCacheResponseErrorCode = (
+ value: unknown
+): value is CacheResponseErrorCode =>
+ value === OWNER_EPOCH_LOST_ERROR_CODE ||
+ value === ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE;
+
+/** Identifies a coordinator-fenced rejection from a lost owner epoch. */
+export const isOwnerEpochLostError = (
+ value: unknown
+): value is Error & { errorCode: 'owner-epoch-lost' } =>
+ value instanceof Error &&
+ 'errorCode' in value &&
+ value.errorCode === OWNER_EPOCH_LOST_ERROR_CODE;
+
+/** Identifies the host-only uncertainty result for an admitted enqueue send. */
+export const isAdmittedEnqueueUncertainError = (
+ value: unknown
+): value is Error & { errorCode: 'admitted-enqueue-uncertain' } =>
+ value instanceof Error &&
+ 'errorCode' in value &&
+ value.errorCode === ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE;
+
+/** Strictly validates a cache response received across a host boundary. */
+export function isCacheResponse(value: unknown): value is CacheResponse {
+ if (
+ !isWireRecord(value) ||
+ !Number.isSafeInteger(value.id) ||
+ (value.id as number) < 0
+ ) {
+ return false;
+ }
+ if (value.ok === true) {
+ return (
+ hasOnlyWireKeys(value, ['id', 'ok', 'result']) &&
+ Object.hasOwn(value, 'result')
+ );
+ }
+ return (
+ value.ok === false &&
+ hasOnlyWireKeys(value, ['id', 'ok', 'error', 'errorCode']) &&
+ typeof value.error === 'string' &&
+ (value.errorCode === undefined || isCacheResponseErrorCode(value.errorCode))
+ );
}
+
+/** Strictly validates a pushed cache notification. */
+export function isCachePush(value: unknown): value is CachePush {
+ if (!isWireRecord(value)) return false;
+ switch (value.kind) {
+ case 'ops-affected':
+ return (
+ hasOnlyWireKeys(value, ['kind', 'opIds', 'keys']) &&
+ isWireStringArray(value.opIds) &&
+ isWireStringArray(value.keys)
+ );
+ case 'cache-changed':
+ return hasOnlyWireKeys(value, ['kind']);
+ case 'mutation-settled': {
+ const settlement = value.settlement;
+ if (
+ !hasOnlyWireKeys(value, ['kind', 'settlement']) ||
+ !isWireRecord(settlement) ||
+ typeof settlement.transactionId !== 'string'
+ ) {
+ return false;
+ }
+ if (settlement.status === 'committed') {
+ return hasOnlyWireKeys(settlement, ['transactionId', 'status']);
+ }
+ return (
+ settlement.status === 'permanently-failed' &&
+ hasOnlyWireKeys(settlement, ['transactionId', 'status', 'error']) &&
+ typeof settlement.error === 'string'
+ );
+ }
+ default:
+ return false;
+ }
+}
+
+/** Strictly validates any response or push delivered to a cache host. */
+export const isWorkerMessage = (value: unknown): value is WorkerMessage =>
+ isCacheResponse(value) || isCachePush(value);
diff --git a/apps/web/src/lib/graphql-cache/rollout-observability.ts b/apps/web/src/lib/graphql-cache/rollout-observability.ts
new file mode 100644
index 0000000000..b8133b291e
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/rollout-observability.ts
@@ -0,0 +1,28 @@
+import { isTauri } from '@core/util/platform';
+import { getBrowserTursoCacheRolloutDecision } from './rollout';
+import { createPageCacheTelemetry } from './telemetry-relay';
+
+/** Records the navigation control/treatment point without starting cache I/O. */
+export function recordBrowserTursoCacheNavigation(): void {
+ if (isTauri()) return;
+ try {
+ const decision = getBrowserTursoCacheRolloutDecision();
+ const navigation = performance.getEntriesByType('navigation')[0] as
+ | PerformanceNavigationTiming
+ | undefined;
+ const pageTelemetry = createPageCacheTelemetry({
+ rolloutCohort: decision.cohort,
+ });
+ pageTelemetry.recorder.record({
+ name: 'graphql_cache.navigation',
+ operationCategory: 'navigation',
+ outcome: 'success',
+ errorCode: 'none',
+ durationMs: navigation?.duration ?? 0,
+ });
+ pageTelemetry.recorder.flush();
+ pageTelemetry.relay.dispose();
+ } catch {
+ // Navigation telemetry is observational and must never delay rendering.
+ }
+}
diff --git a/apps/web/src/lib/graphql-cache/rollout-policy.test.ts b/apps/web/src/lib/graphql-cache/rollout-policy.test.ts
new file mode 100644
index 0000000000..4683377ba2
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/rollout-policy.test.ts
@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest';
+import {
+ type BooleanFlag,
+ resolveBrowserTursoCacheRollout,
+} from './rollout-policy';
+
+const values: BooleanFlag[] = [undefined, false, true];
+
+describe('browser Turso cache rollout policy', () => {
+ it('is exhaustive: kill wins, explicit enable override is next, undefined fails closed', () => {
+ for (const enableEnvOverride of values) {
+ for (const disableEnvOverride of values) {
+ for (const posthogEnable of values) {
+ for (const posthogDisable of values) {
+ const decision = resolveBrowserTursoCacheRollout({
+ isTauri: false,
+ graphqlTransportEnabled: true,
+ enableEnvOverride,
+ disableEnvOverride,
+ posthogEnable,
+ posthogDisable,
+ });
+ const killed =
+ disableEnvOverride === true || posthogDisable === true;
+ const expected = killed
+ ? false
+ : enableEnvOverride !== undefined
+ ? enableEnvOverride
+ : posthogEnable === true;
+ expect(
+ decision.enabled,
+ JSON.stringify({
+ enableEnvOverride,
+ disableEnvOverride,
+ posthogEnable,
+ posthogDisable,
+ })
+ ).toBe(expected);
+ if (killed) expect(decision.reason).toBe('emergency-disabled');
+ }
+ }
+ }
+ }
+ });
+
+ it('keeps production-style undefined flags off', () => {
+ expect(
+ resolveBrowserTursoCacheRollout({
+ isTauri: false,
+ graphqlTransportEnabled: true,
+ enableEnvOverride: undefined,
+ disableEnvOverride: undefined,
+ posthogEnable: undefined,
+ posthogDisable: undefined,
+ })
+ ).toEqual({
+ enabled: false,
+ cohort: 'control',
+ reason: 'not-enabled',
+ nativeCacheUnchanged: false,
+ });
+ });
+
+ it('does not enable a cache when the existing GraphQL transport is disabled', () => {
+ expect(
+ resolveBrowserTursoCacheRollout({
+ isTauri: false,
+ graphqlTransportEnabled: false,
+ enableEnvOverride: true,
+ disableEnvOverride: false,
+ posthogEnable: true,
+ posthogDisable: false,
+ })
+ ).toMatchObject({
+ enabled: false,
+ reason: 'graphql-transport-disabled',
+ });
+ });
+
+ it.each([false, true])(
+ 'leaves Tauri native cache behavior equal to GraphQL transport=%s',
+ (graphqlTransportEnabled) => {
+ expect(
+ resolveBrowserTursoCacheRollout({
+ isTauri: true,
+ graphqlTransportEnabled,
+ // Even contradictory browser values are irrelevant on native.
+ enableEnvOverride: !graphqlTransportEnabled,
+ disableEnvOverride: true,
+ posthogEnable: !graphqlTransportEnabled,
+ posthogDisable: true,
+ })
+ ).toEqual({
+ enabled: graphqlTransportEnabled,
+ cohort: 'unknown',
+ reason: 'tauri-native-unchanged',
+ nativeCacheUnchanged: true,
+ });
+ }
+ );
+});
diff --git a/apps/web/src/lib/graphql-cache/rollout-policy.ts b/apps/web/src/lib/graphql-cache/rollout-policy.ts
new file mode 100644
index 0000000000..4311335164
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/rollout-policy.ts
@@ -0,0 +1,82 @@
+import type { CacheRolloutCohort } from './telemetry';
+
+export type BooleanFlag = boolean | undefined;
+
+export type BrowserTursoCacheRolloutInput = {
+ isTauri: boolean;
+ graphqlTransportEnabled: boolean;
+ enableEnvOverride: BooleanFlag;
+ disableEnvOverride: BooleanFlag;
+ posthogEnable: BooleanFlag;
+ posthogDisable: BooleanFlag;
+};
+
+export type BrowserTursoCacheRolloutDecision = {
+ enabled: boolean;
+ cohort: CacheRolloutCohort;
+ reason:
+ | 'tauri-native-unchanged'
+ | 'graphql-transport-disabled'
+ | 'emergency-disabled'
+ | 'env-enabled'
+ | 'posthog-enabled'
+ | 'not-enabled';
+ /** Whether the caller must retain the existing native cache path. */
+ nativeCacheUnchanged: boolean;
+};
+
+/**
+ * Pure cache rollout policy. The emergency flag is intentionally independent from the
+ * rollout flag and any true kill source wins. Undefined PostHog values fail
+ * closed. Tauri returns before browser policy is considered.
+ */
+export function resolveBrowserTursoCacheRollout(
+ input: BrowserTursoCacheRolloutInput
+): BrowserTursoCacheRolloutDecision {
+ if (input.isTauri) {
+ return {
+ enabled: input.graphqlTransportEnabled,
+ cohort: 'unknown',
+ reason: 'tauri-native-unchanged',
+ nativeCacheUnchanged: true,
+ };
+ }
+ if (!input.graphqlTransportEnabled) {
+ return {
+ enabled: false,
+ cohort: 'control',
+ reason: 'graphql-transport-disabled',
+ nativeCacheUnchanged: false,
+ };
+ }
+ if (input.disableEnvOverride === true || input.posthogDisable === true) {
+ return {
+ enabled: false,
+ cohort: 'control',
+ reason: 'emergency-disabled',
+ nativeCacheUnchanged: false,
+ };
+ }
+ if (input.enableEnvOverride !== undefined) {
+ return {
+ enabled: input.enableEnvOverride,
+ cohort: input.enableEnvOverride ? 'override' : 'control',
+ reason: input.enableEnvOverride ? 'env-enabled' : 'not-enabled',
+ nativeCacheUnchanged: false,
+ };
+ }
+ if (input.posthogEnable === true) {
+ return {
+ enabled: true,
+ cohort: 'treatment',
+ reason: 'posthog-enabled',
+ nativeCacheUnchanged: false,
+ };
+ }
+ return {
+ enabled: false,
+ cohort: 'control',
+ reason: 'not-enabled',
+ nativeCacheUnchanged: false,
+ };
+}
diff --git a/apps/web/src/lib/graphql-cache/rollout.test.ts b/apps/web/src/lib/graphql-cache/rollout.test.ts
new file mode 100644
index 0000000000..d9d6540770
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/rollout.test.ts
@@ -0,0 +1,82 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+ isTauri: vi.fn(() => false),
+ graphqlEnabled: vi.fn(() => true),
+ isFeatureEnabled: vi.fn<(flag: string) => boolean | undefined>(),
+}));
+
+vi.mock('@core/util/platform', () => ({ isTauri: mocks.isTauri }));
+vi.mock('@core/constant/featureFlags', () => ({
+ ENABLE_GRAPHQL_SOUP: mocks.graphqlEnabled,
+ ENABLE_BROWSER_TURSO_CACHE_FLAG: 'enable-browser-turso-cache',
+ DISABLE_BROWSER_TURSO_CACHE_FLAG: 'disable-browser-turso-cache',
+ ENABLE_BROWSER_TURSO_CACHE_OVERRIDE: undefined,
+ DISABLE_BROWSER_TURSO_CACHE_OVERRIDE: undefined,
+}));
+vi.mock('@app/lib/analytics', () => ({
+ analytics: {
+ posthog: {
+ isFeatureEnabled: mocks.isFeatureEnabled,
+ },
+ },
+}));
+
+import { getBrowserTursoCacheRolloutDecision } from './rollout';
+
+describe('browser Turso cache production gate', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ mocks.isTauri.mockReturnValue(false);
+ mocks.graphqlEnabled.mockReturnValue(true);
+ mocks.isFeatureEnabled.mockReturnValue(undefined);
+ });
+
+ it('fails closed while PostHog flags are undefined', () => {
+ expect(getBrowserTursoCacheRolloutDecision()).toMatchObject({
+ enabled: false,
+ cohort: 'control',
+ reason: 'not-enabled',
+ });
+ });
+
+ it('uses a Boolean PostHog rollout and lets the independent kill win', () => {
+ mocks.isFeatureEnabled.mockImplementation(
+ (flag) => flag === 'enable-browser-turso-cache'
+ );
+ expect(getBrowserTursoCacheRolloutDecision().enabled).toBe(true);
+
+ mocks.isFeatureEnabled.mockReturnValue(true);
+ expect(getBrowserTursoCacheRolloutDecision()).toMatchObject({
+ enabled: false,
+ reason: 'emergency-disabled',
+ });
+ });
+
+ it('does not read browser PostHog flags or subscribe on Tauri', () => {
+ mocks.isTauri.mockReturnValue(true);
+ mocks.graphqlEnabled.mockReturnValue(true);
+ mocks.isFeatureEnabled.mockImplementation(() => {
+ throw new Error('browser flag touched on Tauri');
+ });
+
+ expect(getBrowserTursoCacheRolloutDecision()).toMatchObject({
+ enabled: true,
+ nativeCacheUnchanged: true,
+ });
+ expect(mocks.isFeatureEnabled).not.toHaveBeenCalled();
+ });
+
+ it('imports without constructing browser workers', async () => {
+ const WorkerConstructor = vi.fn(() => {
+ throw new Error('worker must stay lazy');
+ });
+ vi.stubGlobal('Worker', WorkerConstructor);
+ vi.stubGlobal('SharedWorker', WorkerConstructor);
+
+ await import('./worker/coordinator-page-adapter');
+
+ expect(WorkerConstructor).not.toHaveBeenCalled();
+ vi.unstubAllGlobals();
+ });
+});
diff --git a/apps/web/src/lib/graphql-cache/rollout.ts b/apps/web/src/lib/graphql-cache/rollout.ts
new file mode 100644
index 0000000000..de649a4b77
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/rollout.ts
@@ -0,0 +1,44 @@
+import { analytics } from '@app/lib/analytics';
+import {
+ DISABLE_BROWSER_TURSO_CACHE_FLAG,
+ DISABLE_BROWSER_TURSO_CACHE_OVERRIDE,
+ ENABLE_BROWSER_TURSO_CACHE_FLAG,
+ ENABLE_BROWSER_TURSO_CACHE_OVERRIDE,
+ ENABLE_GRAPHQL_SOUP,
+} from '@core/constant/featureFlags';
+import { isTauri } from '@core/util/platform';
+import {
+ type BrowserTursoCacheRolloutDecision,
+ resolveBrowserTursoCacheRollout,
+} from './rollout-policy';
+
+/** Resolves the current gate without constructing a browser cache resource. */
+export function getBrowserTursoCacheRolloutDecision(): BrowserTursoCacheRolloutDecision {
+ const native = isTauri();
+ const graphqlTransportEnabled = ENABLE_GRAPHQL_SOUP();
+ if (native) {
+ // Do not touch browser rollout flags on Tauri. Besides preserving behavior,
+ // this keeps native startup independent from PostHog browser-cache state.
+ return resolveBrowserTursoCacheRollout({
+ isTauri: true,
+ graphqlTransportEnabled,
+ enableEnvOverride: undefined,
+ disableEnvOverride: undefined,
+ posthogEnable: undefined,
+ posthogDisable: undefined,
+ });
+ }
+
+ return resolveBrowserTursoCacheRollout({
+ isTauri: false,
+ graphqlTransportEnabled,
+ enableEnvOverride: ENABLE_BROWSER_TURSO_CACHE_OVERRIDE,
+ disableEnvOverride: DISABLE_BROWSER_TURSO_CACHE_OVERRIDE,
+ posthogEnable: analytics.posthog.isFeatureEnabled(
+ ENABLE_BROWSER_TURSO_CACHE_FLAG
+ ),
+ posthogDisable: analytics.posthog.isFeatureEnabled(
+ DISABLE_BROWSER_TURSO_CACHE_FLAG
+ ),
+ });
+}
diff --git a/apps/web/src/lib/graphql-cache/scope.test.ts b/apps/web/src/lib/graphql-cache/scope.test.ts
new file mode 100644
index 0000000000..222d0487d2
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/scope.test.ts
@@ -0,0 +1,110 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { quarantineCacheScope, rotateCacheScope } from './scope';
+
+const STORAGE_KEY = 'graphql-cache:scope';
+
+type LockRequest = {
+ run: () => Promise<void>;
+};
+
+function controlledLockManager(): {
+ lockManager: Pick<LockManager, 'request'>;
+ requests: LockRequest[];
+} {
+ const requests: LockRequest[] = [];
+ const lockManager = {
+ request: vi.fn(
+ <T>(
+ _name: string,
+ _options: LockOptions,
+ callback: (lock: Lock | null) => T | PromiseLike<T>
+ ): Promise<T> =>
+ new Promise<T>((resolve, reject) => {
+ requests.push({
+ run: async () => {
+ try {
+ resolve(
+ await callback({
+ name: 'graphql-cache:scope-storage',
+ mode: 'exclusive',
+ } as Lock)
+ );
+ } catch (error) {
+ reject(error);
+ }
+ },
+ });
+ })
+ ),
+ } as unknown as Pick<LockManager, 'request'>;
+ return { lockManager, requests };
+}
+
+describe('serialized cache scope replacement', () => {
+ beforeEach(() => {
+ localStorage.clear();
+ });
+
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ vi.restoreAllMocks();
+ });
+
+ it('falls back synchronously only when Web Locks are unavailable', async () => {
+ vi.stubGlobal('navigator', {});
+ localStorage.setItem(STORAGE_KEY, 'old-scope');
+
+ await expect(quarantineCacheScope('old-scope')).resolves.toBe(
+ 'quarantine:old-scope'
+ );
+ expect(localStorage.getItem(STORAGE_KEY)).toBe('quarantine:old-scope');
+ });
+
+ it('does not use an unsafe fallback when an advertised lock fails', async () => {
+ vi.stubGlobal('navigator', {
+ locks: { request: vi.fn().mockRejectedValue(new Error('lock failed')) },
+ });
+ localStorage.setItem(STORAGE_KEY, 'old-scope');
+
+ await expect(quarantineCacheScope('old-scope')).resolves.toBeUndefined();
+ expect(localStorage.getItem(STORAGE_KEY)).toBe('old-scope');
+ });
+
+ it('serializes a stale S1 quarantine behind an S2 rotation', async () => {
+ const { lockManager, requests } = controlledLockManager();
+ vi.stubGlobal('navigator', { locks: lockManager });
+ vi.spyOn(crypto, 'randomUUID').mockReturnValue(
+ '22222222-2222-4222-8222-222222222222'
+ );
+ localStorage.setItem(STORAGE_KEY, 'scope-1');
+
+ const staleQuarantine = quarantineCacheScope('scope-1');
+ const rotateToScope2 = rotateCacheScope();
+ expect(requests).toHaveLength(2);
+ await requests[1]?.run();
+ await expect(rotateToScope2).resolves.toBe(
+ '22222222-2222-4222-8222-222222222222'
+ );
+ await requests[0]?.run();
+ await expect(staleQuarantine).resolves.toBeUndefined();
+
+ expect(localStorage.getItem(STORAGE_KEY)).toBe(
+ '22222222-2222-4222-8222-222222222222'
+ );
+ });
+
+ it('converges serialized failures that observed the same S1 scope', async () => {
+ const { lockManager, requests } = controlledLockManager();
+ vi.stubGlobal('navigator', { locks: lockManager });
+ localStorage.setItem(STORAGE_KEY, 'scope-1');
+
+ const first = quarantineCacheScope('scope-1');
+ const second = quarantineCacheScope('scope-1');
+ await requests[0]?.run();
+ await requests[1]?.run();
+
+ await expect(first).resolves.toBe('quarantine:scope-1');
+ await expect(second).resolves.toBe('quarantine:scope-1');
+ expect(localStorage.getItem(STORAGE_KEY)).toBe('quarantine:scope-1');
+ });
+});
diff --git a/apps/web/src/lib/graphql-cache/scope.ts b/apps/web/src/lib/graphql-cache/scope.ts
index 8a901cd7a8..8290b8d53f 100644
--- a/apps/web/src/lib/graphql-cache/scope.ts
+++ b/apps/web/src/lib/graphql-cache/scope.ts
@@ -1,32 +1,95 @@
/**
- * Cache scope: an anonymous, client-generated uuid naming the local cache
- * storage (IndexedDB database). Deliberately NOT derived from user identity:
+ * Cache scope: an anonymous, client-generated token naming the local Turso
+ * cache in OPFS. Deliberately NOT derived from user identity:
*
* - construction is synchronous and works offline (no identity waterfall);
- * - no PII leaks into enumerable storage metadata (database names);
+ * - no PII leaks into enumerable storage metadata (OPFS filenames);
* - user↔cache consistency is enforced *inside* the cache by the identity
* witness (`QueryRoot.user.id` observed on every write): a response for a
* different user than the one bound to the cache wipes and rebinds it
* (silent restart). See the design doc and cache-core `identity_witness`.
*
- * The uuid is stable for the browser profile; identity changes normally rotate
- * the cache *contents*. A failed logout wipe rotates the scope as a quarantine.
+ * The scope is stable for the browser profile and maps to one Turso/OPFS
+ * database identity. Identity changes reset that database's contents. Scope
+ * replacement is serialized across tabs so a stale transport failure cannot
+ * overwrite a newer logout rotation.
*/
const SCOPE_STORAGE_KEY = 'graphql-cache:scope';
+const SCOPE_STORAGE_LOCK = 'graphql-cache:scope-storage';
+const quarantineScopeFor = (scope: string): string => `quarantine:${scope}`;
-/** Quarantines a cache whose durable logout wipe could not be confirmed. */
-export function rotateCacheScope(): void {
- const scope = crypto.randomUUID();
+type ScopeStorageAction = () => string | undefined;
+
+/** Serializes scope compare/set whenever Web Locks are supported. */
+async function withScopeStorageLock(
+ action: ScopeStorageAction
+): Promise<string | undefined> {
+ let locks: LockManager | undefined;
try {
- localStorage.setItem(SCOPE_STORAGE_KEY, scope);
+ locks = typeof navigator === 'undefined' ? undefined : navigator.locks;
} catch {
+ return undefined;
+ }
+ if (!locks || typeof locks.request !== 'function') {
try {
- localStorage.removeItem(SCOPE_STORAGE_KEY);
+ return action();
} catch {
- // Inaccessible storage already makes the current scope session-only.
+ return undefined;
}
}
+ try {
+ return await locks.request(SCOPE_STORAGE_LOCK, { mode: 'exclusive' }, () =>
+ action()
+ );
+ } catch {
+ // Never perform an unserialized fallback on a platform advertising locks.
+ return undefined;
+ }
+}
+
+/**
+ * Conditionally quarantines one uncertain transport scope.
+ *
+ * Simultaneous failures for the same scope converge on one deterministic
+ * replacement. The compare and set run under the same cross-tab lock as
+ * logout rotation, so a stale host cannot overwrite a newer unrelated scope.
+ */
+export async function quarantineCacheScope(
+ expectedScope: string
+): Promise<string | undefined> {
+ const replacement = quarantineScopeFor(expectedScope);
+ return await withScopeStorageLock(() => {
+ try {
+ const current = localStorage.getItem(SCOPE_STORAGE_KEY);
+ if (current === expectedScope) {
+ localStorage.setItem(SCOPE_STORAGE_KEY, replacement);
+ return replacement;
+ }
+ return current === replacement ? replacement : undefined;
+ } catch {
+ // Without a trustworthy compare, retaining the persisted value is safer.
+ return undefined;
+ }
+ });
+}
+
+/** Quarantines a cache whose durable logout wipe could not be confirmed. */
+export async function rotateCacheScope(): Promise<string | undefined> {
+ return await withScopeStorageLock(() => {
+ try {
+ const scope = crypto.randomUUID();
+ localStorage.setItem(SCOPE_STORAGE_KEY, scope);
+ return scope;
+ } catch {
+ try {
+ localStorage.removeItem(SCOPE_STORAGE_KEY);
+ } catch {
+ // Inaccessible storage already makes the current scope session-only.
+ }
+ return undefined;
+ }
+ });
}
export function getOrCreateCacheScope(): string {
diff --git a/apps/web/src/lib/graphql-cache/telemetry-otel.test.ts b/apps/web/src/lib/graphql-cache/telemetry-otel.test.ts
new file mode 100644
index 0000000000..4420345ba6
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/telemetry-otel.test.ts
@@ -0,0 +1,72 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const span = vi.hoisted(() => ({ setAttr: vi.fn(), end: vi.fn() }));
+const anonymousSpan = vi.hoisted(() => vi.fn(() => span));
+
+vi.mock('@macro-inc/observability', () => ({
+ Telemetry: { anonymousSpan },
+}));
+
+import { createOtelCacheTelemetrySink } from './telemetry-otel';
+
+describe('cache OpenTelemetry sink', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('uses anonymous fixed-name spans and only schema attributes', () => {
+ createOtelCacheTelemetrySink().emit({
+ browserFamily: 'firefox',
+ browserVersion: '151',
+ appVersion: '0.1',
+ backend: 'turso-wasm-opfs',
+ rolloutCohort: 'treatment',
+ name: 'graphql_cache.transaction',
+ operationCategory: 'transaction',
+ outcome: 'error',
+ errorCode: 'opfs-quota',
+ openOutcome: 'reset-corrupt',
+ queueDiagnosticsAvailability: 'available',
+ resetAttempt: 'wipe-before-open',
+ queueDepth: 4,
+ oldestAgeMs: 25,
+ durationMs: 12,
+ });
+
+ expect(anonymousSpan).toHaveBeenCalledWith('graphql_cache.transaction');
+ expect(Object.fromEntries(span.setAttr.mock.calls)).toEqual({
+ 'cache.browser_family': 'firefox',
+ 'cache.browser_version': '151',
+ 'cache.app_version': '0.1',
+ 'cache.backend': 'turso-wasm-opfs',
+ 'cache.rollout_cohort': 'treatment',
+ 'cache.operation_category': 'transaction',
+ 'cache.outcome': 'error',
+ 'cache.error_code': 'opfs-quota',
+ 'cache.open_outcome': 'reset-corrupt',
+ 'cache.queue_diagnostics_availability': 'available',
+ 'cache.reset_attempt': 'wipe-before-open',
+ 'cache.duration_ms': 12,
+ 'cache.queue_depth': 4,
+ 'cache.oldest_age_ms': 25,
+ });
+ expect(span.end).toHaveBeenCalledOnce();
+ });
+
+ it('isolates Telemetry failures', () => {
+ anonymousSpan.mockImplementationOnce(() => {
+ throw new Error('provider unavailable');
+ });
+ expect(() =>
+ createOtelCacheTelemetrySink().emit({
+ browserFamily: 'other',
+ browserVersion: 'unknown',
+ appVersion: 'unknown',
+ backend: 'turso-wasm-opfs',
+ rolloutCohort: 'unknown',
+ name: 'graphql_cache.db_ready',
+ operationCategory: 'initialization',
+ })
+ ).not.toThrow();
+ });
+});
diff --git a/apps/web/src/lib/graphql-cache/telemetry-otel.ts b/apps/web/src/lib/graphql-cache/telemetry-otel.ts
new file mode 100644
index 0000000000..2c5ec32d01
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/telemetry-otel.ts
@@ -0,0 +1,82 @@
+import { Telemetry } from '@macro-inc/observability';
+import type { CacheTelemetryEnvelope, CacheTelemetrySink } from './telemetry';
+
+/**
+ * Privacy-safe OpenTelemetry adapter. It uses the anonymous span API so the
+ * browser provider cannot enrich cache metrics with `usr.id`.
+ */
+export function createOtelCacheTelemetrySink(): CacheTelemetrySink {
+ return {
+ emit(event: CacheTelemetryEnvelope): void {
+ try {
+ const span = Telemetry.anonymousSpan(event.name);
+ span.setAttr('cache.browser_family', event.browserFamily);
+ span.setAttr('cache.browser_version', event.browserVersion);
+ span.setAttr('cache.app_version', event.appVersion);
+ span.setAttr('cache.backend', event.backend);
+ span.setAttr('cache.rollout_cohort', event.rolloutCohort);
+ span.setAttr('cache.operation_category', event.operationCategory);
+ if (event.aggregatedEventName !== undefined) {
+ span.setAttr(
+ 'cache.aggregated_event_name',
+ event.aggregatedEventName
+ );
+ }
+ if (event.outcome !== undefined) {
+ span.setAttr('cache.outcome', event.outcome);
+ }
+ if (event.errorCode !== undefined) {
+ span.setAttr('cache.error_code', event.errorCode);
+ }
+ if (event.resetReason !== undefined) {
+ span.setAttr('cache.reset_reason', event.resetReason);
+ }
+ if (event.ownerEvent !== undefined) {
+ span.setAttr('cache.owner_event', event.ownerEvent);
+ }
+ if (event.persistence !== undefined) {
+ span.setAttr('cache.persistence', event.persistence);
+ }
+ if (event.openOutcome !== undefined) {
+ span.setAttr('cache.open_outcome', event.openOutcome);
+ }
+ if (event.queueDiagnosticsAvailability !== undefined) {
+ span.setAttr(
+ 'cache.queue_diagnostics_availability',
+ event.queueDiagnosticsAvailability
+ );
+ }
+ if (event.resetAttempt !== undefined) {
+ span.setAttr('cache.reset_attempt', event.resetAttempt);
+ }
+ if (event.durationMs !== undefined) {
+ span.setAttr('cache.duration_ms', event.durationMs);
+ }
+ if (event.bytes !== undefined) span.setAttr('cache.bytes', event.bytes);
+ if (event.highWaterBytes !== undefined) {
+ span.setAttr('cache.high_water_bytes', event.highWaterBytes);
+ }
+ if (event.usageBytes !== undefined) {
+ span.setAttr('cache.usage_bytes', event.usageBytes);
+ }
+ if (event.quotaBytes !== undefined) {
+ span.setAttr('cache.quota_bytes', event.quotaBytes);
+ }
+ if (event.ratio !== undefined) span.setAttr('cache.ratio', event.ratio);
+ if (event.count !== undefined) span.setAttr('cache.count', event.count);
+ if (event.sampleRate !== undefined) {
+ span.setAttr('cache.sample_rate', event.sampleRate);
+ }
+ if (event.queueDepth !== undefined) {
+ span.setAttr('cache.queue_depth', event.queueDepth);
+ }
+ if (event.oldestAgeMs !== undefined) {
+ span.setAttr('cache.oldest_age_ms', event.oldestAgeMs);
+ }
+ span.end();
+ } catch {
+ // OTel availability and exporter failures never affect cache behavior.
+ }
+ },
+ };
+}
diff --git a/apps/web/src/lib/graphql-cache/telemetry-relay.test.ts b/apps/web/src/lib/graphql-cache/telemetry-relay.test.ts
new file mode 100644
index 0000000000..b6f00962e7
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/telemetry-relay.test.ts
@@ -0,0 +1,119 @@
+import { describe, expect, it, vi } from 'vitest';
+import {
+ browserCacheTelemetryContext,
+ type CacheTelemetryEnvelope,
+ CacheTelemetryReporter,
+} from './telemetry';
+import {
+ CacheTelemetryRelay,
+ createPageCacheTelemetry,
+} from './telemetry-relay';
+
+class FakeChannel {
+ onmessage: ((event: MessageEvent<unknown>) => void) | null = null;
+ onmessageerror: (() => void) | null = null;
+ closed = false;
+ postMessage(): void {}
+ close(): void {
+ this.closed = true;
+ }
+ receive(data: unknown): void {
+ this.onmessage?.({ data } as MessageEvent<unknown>);
+ }
+}
+
+describe('cache telemetry worker relay', () => {
+ it('uses one scope-free reporter lock and forwards only validated observations', async () => {
+ const channel = new FakeChannel();
+ const events: CacheTelemetryEnvelope[] = [];
+ let lockName = '';
+ let lockCallback: ((lock: Lock | null) => Promise<void> | void) | undefined;
+ const lockManager = {
+ request: vi.fn(
+ async (
+ name: string,
+ _options: LockOptions,
+ callback: (lock: Lock | null) => Promise<void> | void
+ ) => {
+ lockName = name;
+ lockCallback = callback;
+ }
+ ),
+ } as unknown as Pick<LockManager, 'request'>;
+ const { relay } = createPageCacheTelemetry({
+ rolloutCohort: 'treatment',
+ sink: { emit: (event) => events.push(event) },
+ relay: {
+ createChannel: () => channel as unknown as BroadcastChannel,
+ lockManager,
+ },
+ });
+
+ relay.start();
+ await Promise.resolve();
+ expect(lockName).toBe('macro:graphql-cache-telemetry-reporter:v1');
+ const leadership = lockCallback?.({
+ name: lockName,
+ mode: 'exclusive',
+ } as Lock);
+ await Promise.resolve();
+ channel.receive({
+ name: 'graphql_cache.owner',
+ operationCategory: 'lifecycle',
+ ownerEvent: 'elected',
+ scope: 'must-not-pass',
+ });
+ channel.receive({
+ name: 'graphql_cache.owner',
+ operationCategory: 'lifecycle',
+ ownerEvent: 'elected',
+ });
+
+ expect(events).toHaveLength(1);
+ expect(events[0]).toMatchObject({
+ rolloutCohort: 'unknown',
+ appVersion: 'unknown',
+ });
+ expect(JSON.stringify(events)).not.toContain('must-not-pass');
+ relay.dispose();
+ await leadership;
+ expect(channel.closed).toBe(true);
+ });
+
+ it('isolates channel failures', () => {
+ const relay = new CacheTelemetryRelay(
+ new CacheTelemetryReporter(browserCacheTelemetryContext('unknown'), {
+ emit: () => undefined,
+ }),
+ {
+ createChannel: () => {
+ throw new Error('channel unavailable');
+ },
+ }
+ );
+
+ expect(() => relay.start()).not.toThrow();
+ expect(() => relay.dispose()).not.toThrow();
+ });
+
+ it('isolates lock failures after creating the channel', () => {
+ const channel = new FakeChannel();
+ const relay = new CacheTelemetryRelay(
+ new CacheTelemetryReporter(browserCacheTelemetryContext('unknown'), {
+ emit: () => undefined,
+ }),
+ {
+ createChannel: () => channel as unknown as BroadcastChannel,
+ lockManager: {
+ request: () => {
+ throw new Error('lock unavailable');
+ },
+ } as unknown as Pick<LockManager, 'request'>,
+ }
+ );
+
+ expect(() => relay.start()).not.toThrow();
+ expect(() => relay.dispose()).not.toThrow();
+ expect(channel.closed).toBe(true);
+ });
+});
diff --git a/apps/web/src/lib/graphql-cache/telemetry-relay.ts b/apps/web/src/lib/graphql-cache/telemetry-relay.ts
new file mode 100644
index 0000000000..b5d7517c62
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/telemetry-relay.ts
@@ -0,0 +1,157 @@
+import {
+ browserCacheTelemetryContext,
+ type CacheRolloutCohort,
+ CacheTelemetryRecorder,
+ type CacheTelemetryRecorderLike,
+ CacheTelemetryReporter,
+ type CacheTelemetrySink,
+ isCacheTelemetryObservation,
+} from './telemetry';
+import { createOtelCacheTelemetrySink } from './telemetry-otel';
+
+const CACHE_TELEMETRY_CHANNEL = 'macro:graphql-cache-telemetry:v1';
+const CACHE_TELEMETRY_REPORTER_LOCK =
+ 'macro:graphql-cache-telemetry-reporter:v1';
+
+type BroadcastChannelLike = Pick<
+ BroadcastChannel,
+ 'postMessage' | 'close' | 'onmessage' | 'onmessageerror'
+>;
+
+export interface CacheTelemetryRelayOptions {
+ createChannel?: (name: string) => BroadcastChannelLike;
+ lockManager?: Pick<LockManager, 'request'>;
+}
+
+/**
+ * Relays typed worker observations through exactly one live browser page.
+ * Leadership is a fixed, scope-free Web Lock; no cache or identity key crosses
+ * the telemetry channel.
+ */
+export class CacheTelemetryRelay {
+ private channel: BroadcastChannelLike | undefined;
+ private abortController: AbortController | undefined;
+ private releaseLeadership: (() => void) | undefined;
+ private leader = false;
+ private started = false;
+ private disposed = false;
+
+ constructor(
+ private readonly reporter: CacheTelemetryReporter,
+ private readonly options: CacheTelemetryRelayOptions = {}
+ ) {}
+
+ start(): void {
+ if (this.started || this.disposed) return;
+ this.started = true;
+ try {
+ const createChannel =
+ this.options.createChannel ??
+ ((name: string) => new BroadcastChannel(name));
+ this.channel = createChannel(CACHE_TELEMETRY_CHANNEL);
+ this.channel.onmessage = (event: MessageEvent<unknown>) => {
+ if (this.leader && isCacheTelemetryObservation(event.data)) {
+ this.reporter.emit(event.data);
+ }
+ };
+ this.channel.onmessageerror = () => undefined;
+ } catch {
+ this.channel = undefined;
+ return;
+ }
+
+ const locks =
+ this.options.lockManager ??
+ (typeof navigator === 'undefined' ? undefined : navigator.locks);
+ if (!locks) return;
+ const abortController = new AbortController();
+ this.abortController = abortController;
+ const held = new Promise<void>((resolve) => {
+ this.releaseLeadership = resolve;
+ });
+ try {
+ void locks
+ .request(
+ CACHE_TELEMETRY_REPORTER_LOCK,
+ { mode: 'exclusive', signal: abortController.signal },
+ async (lock) => {
+ if (!lock || this.disposed) return;
+ this.leader = true;
+ try {
+ await held;
+ } finally {
+ this.leader = false;
+ }
+ }
+ )
+ .catch(() => undefined);
+ } catch {
+ // A relay failure only drops worker-originated telemetry.
+ }
+ }
+
+ dispose(): void {
+ if (this.disposed) return;
+ this.disposed = true;
+ this.leader = false;
+ try {
+ this.releaseLeadership?.();
+ this.abortController?.abort();
+ if (this.channel) {
+ this.channel.onmessage = null;
+ this.channel.onmessageerror = null;
+ this.channel.close();
+ }
+ } catch {
+ // Lifecycle cleanup remains best-effort and exception-isolated.
+ }
+ this.channel = undefined;
+ }
+}
+
+/** Page recorder + worker relay, backed by anonymous OpenTelemetry spans. */
+export function createPageCacheTelemetry(options: {
+ rolloutCohort: CacheRolloutCohort;
+ sink?: CacheTelemetrySink;
+ relay?: CacheTelemetryRelayOptions;
+}): {
+ recorder: CacheTelemetryRecorderLike;
+ relay: CacheTelemetryRelay;
+} {
+ const sink = options.sink ?? createOtelCacheTelemetrySink();
+ const pageReporter = new CacheTelemetryReporter(
+ browserCacheTelemetryContext(options.rolloutCohort),
+ sink
+ );
+ // Worker observations carry no activation context over the scope-free
+ // channel, so they must never inherit whichever page won relay leadership.
+ const workerReporter = new CacheTelemetryReporter(
+ {
+ ...browserCacheTelemetryContext('unknown'),
+ appVersion: 'unknown',
+ },
+ sink
+ );
+ return {
+ recorder: new CacheTelemetryRecorder(pageReporter),
+ relay: new CacheTelemetryRelay(workerReporter, options.relay),
+ };
+}
+
+let workerRecorder: CacheTelemetryRecorderLike | undefined;
+let workerChannel: BroadcastChannelLike | undefined;
+
+/** Lazy worker recorder. Constructing/importing it creates no worker/channel. */
+export function workerCacheTelemetry(): CacheTelemetryRecorderLike {
+ workerRecorder ??= new CacheTelemetryRecorder({
+ emit(observation): void {
+ try {
+ workerChannel ??= new BroadcastChannel(CACHE_TELEMETRY_CHANNEL);
+ workerChannel.postMessage(observation);
+ } catch {
+ // Missing/failed BroadcastChannel only drops this observation.
+ }
+ },
+ });
+ return workerRecorder;
+}
diff --git a/apps/web/src/lib/graphql-cache/telemetry.test.ts b/apps/web/src/lib/graphql-cache/telemetry.test.ts
new file mode 100644
index 0000000000..192a9bb8fa
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/telemetry.test.ts
@@ -0,0 +1,380 @@
+import { describe, expect, it } from 'vitest';
+import {
+ browserCacheTelemetryContext,
+ type CacheTelemetryEnvelope,
+ type CacheTelemetryObservation,
+ CacheTelemetryRecorder,
+ CacheTelemetryReporter,
+ classifyCacheError,
+ isCacheTelemetryObservation,
+ isolateCacheTelemetry,
+ operationCategoryForRequest,
+ resetReasonForError,
+} from './telemetry';
+
+describe('cache telemetry privacy contract', () => {
+ it('exports only fixed names, classifications, measurements, and allowlisted dimensions', () => {
+ const events: CacheTelemetryEnvelope[] = [];
+ const reporter = new CacheTelemetryReporter(
+ browserCacheTelemetryContext(
+ 'treatment',
+ 'Mozilla/5.0 Firefox/151.0 secret-user-fragment',
+ '0.1.0+abc123'
+ ),
+ { emit: (event) => events.push(event) }
+ );
+ const hostile = {
+ name: 'graphql_cache.host_request',
+ operationCategory: 'read',
+ outcome: 'hit',
+ durationMs: 4,
+ scope: 'scope-secret',
+ entityId: 'doc-secret',
+ userId: 'user-secret',
+ query: 'query Secret { document(id: "doc-secret") { id } }',
+ variables: { token: 'secret-token' },
+ result: { private: true },
+ } as unknown as CacheTelemetryObservation;
+
+ reporter.emit(hostile);
+
+ expect(events).toEqual([
+ {
+ browserFamily: 'firefox',
+ browserVersion: '151',
+ appVersion: '0.1',
+ backend: 'turso-wasm-opfs',
+ rolloutCohort: 'treatment',
+ name: 'graphql_cache.host_request',
+ operationCategory: 'read',
+ outcome: 'hit',
+ durationMs: 4,
+ },
+ ]);
+ const serialized = JSON.stringify(events);
+ for (const forbidden of [
+ 'scope-secret',
+ 'doc-secret',
+ 'user-secret',
+ 'query Secret',
+ 'secret-token',
+ 'private',
+ ]) {
+ expect(serialized).not.toContain(forbidden);
+ }
+ });
+
+ it('exports queue diagnostics and open outcomes without IDs or payloads', () => {
+ const events: CacheTelemetryEnvelope[] = [];
+ const reporter = new CacheTelemetryReporter(
+ browserCacheTelemetryContext('treatment'),
+ { emit: (event) => events.push(event) }
+ );
+ reporter.emit({
+ name: 'graphql_cache.queue_diagnostics',
+ operationCategory: 'queue',
+ outcome: 'success',
+ errorCode: 'none',
+ openOutcome: 'reset-corrupt',
+ queueDiagnosticsAvailability: 'available',
+ resetAttempt: 'wipe-before-open',
+ queueDepth: 3,
+ oldestAgeMs: 42,
+ scope: 'private-scope',
+ mutationId: 'private-mutation',
+ query: 'mutation Private { private }',
+ } as unknown as CacheTelemetryObservation);
+
+ expect(events).toEqual([
+ expect.objectContaining({
+ name: 'graphql_cache.queue_diagnostics',
+ openOutcome: 'reset-corrupt',
+ queueDiagnosticsAvailability: 'available',
+ resetAttempt: 'wipe-before-open',
+ queueDepth: 3,
+ oldestAgeMs: 42,
+ }),
+ ]);
+ expect(JSON.stringify(events)).not.toMatch(
+ /private-scope|private-mutation|mutation Private/
+ );
+ });
+
+ it('rejects relay payloads with unknown fields or ad-hoc names', () => {
+ expect(
+ isCacheTelemetryObservation({
+ name: 'graphql_cache.read',
+ operationCategory: 'read',
+ outcome: 'miss',
+ })
+ ).toBe(true);
+ expect(
+ isCacheTelemetryObservation({
+ name: 'graphql_cache.read',
+ operationCategory: 'read',
+ query: '{ secret }',
+ })
+ ).toBe(false);
+ expect(
+ isCacheTelemetryObservation({
+ name: 'graphql_cache.dynamic.secret',
+ operationCategory: 'read',
+ })
+ ).toBe(false);
+ });
+
+ it('uses a payload-free exhaustive error taxonomy', () => {
+ expect(classifyCacheError(new Error('OPFS quota full: doc-123'))).toBe(
+ 'opfs-quota'
+ );
+ expect(classifyCacheError(new Error('owner epoch 3 was lost'))).toBe(
+ 'owner-lost'
+ );
+ expect(classifyCacheError(new Error('corrupt postcard for User:1'))).toBe(
+ 'integrity'
+ );
+ expect(resetReasonForError(new Error('namespace mismatch: private'))).toBe(
+ 'namespace-mismatch'
+ );
+ expect(classifyCacheError({ private: 'not stringified' })).toBe('unknown');
+ });
+
+ it('maps every request kind to an allowlisted operation category', () => {
+ const cases = {
+ init: 'initialization',
+ read: 'read',
+ 'read-records': 'read',
+ write: 'write',
+ 'enqueue-optimistic-mutation': 'transaction',
+ 'inspect-query-variants': 'inspection',
+ 'inspect-query': 'inspection',
+ 'claim-next-mutation': 'transaction',
+ 'defer-optimistic-write': 'transaction',
+ 'commit-optimistic-write': 'transaction',
+ 'rollback-optimistic-write': 'transaction',
+ invalidate: 'invalidation',
+ 'delete-records': 'invalidation',
+ teardown: 'lifecycle',
+ clear: 'lifecycle',
+ } as const;
+
+ for (const [kind, expected] of Object.entries(cases)) {
+ expect(operationCategoryForRequest({ kind } as never)).toBe(expected);
+ }
+ });
+});
+
+describe('cache telemetry sampling and failure isolation', () => {
+ it('uses weighted aggregates, independent event sampling, and unsampled errors', () => {
+ const observations: CacheTelemetryObservation[] = [];
+ const recorder = new CacheTelemetryRecorder(
+ { emit: (event) => observations.push(event) },
+ 10,
+ 100
+ );
+ recorder.record({
+ name: 'graphql_cache.read',
+ operationCategory: 'read',
+ outcome: 'hit',
+ durationMs: 10,
+ count: 2,
+ });
+ recorder.record({
+ name: 'graphql_cache.read',
+ operationCategory: 'read',
+ outcome: 'hit',
+ durationMs: 20,
+ count: 3,
+ });
+ for (let index = 0; index < 10; index++) {
+ for (const outcome of ['hit', 'miss'] as const) {
+ recorder.record({
+ name: 'graphql_cache.read',
+ operationCategory: 'read',
+ outcome,
+ durationMs: index,
+ });
+ }
+ }
+ recorder.record({
+ name: 'graphql_cache.transaction',
+ operationCategory: 'transaction',
+ outcome: 'error',
+ errorCode: 'opfs-io',
+ });
+ recorder.flush();
+
+ const hitAggregate = observations.find(
+ (event) =>
+ event.name === 'graphql_cache.aggregate' && event.outcome === 'hit'
+ );
+ expect(hitAggregate).toMatchObject({
+ aggregatedEventName: 'graphql_cache.read',
+ count: 15,
+ durationMs: 8.333333333333334,
+ sampleRate: 1,
+ });
+ expect(
+ observations.filter(
+ (event) =>
+ event.name === 'graphql_cache.read' && event.sampleRate === 10
+ )
+ ).toHaveLength(2);
+ expect(
+ observations.find((event) => event.name === 'graphql_cache.transaction')
+ ).toMatchObject({ outcome: 'error', sampleRate: 1 });
+ expect(
+ observations.filter(
+ (event) =>
+ event.name === 'graphql_cache.aggregate' &&
+ event.aggregatedEventName === 'graphql_cache.transaction'
+ )
+ ).toEqual([]);
+ });
+
+ it('flushes matching pending successes before each raw error', () => {
+ const observations: CacheTelemetryObservation[] = [];
+ const recorder = new CacheTelemetryRecorder({
+ emit: (event) => observations.push(event),
+ });
+ for (let index = 0; index < 149; index++) {
+ recorder.record({
+ name: 'graphql_cache.transaction',
+ operationCategory: 'transaction',
+ outcome: 'success',
+ });
+ }
+ for (let index = 0; index < 2; index++) {
+ recorder.record({
+ name: 'graphql_cache.transaction',
+ operationCategory: 'transaction',
+ outcome: 'error',
+ errorCode: 'opfs-io',
+ });
+ }
+
+ const aggregates = observations.filter(
+ (event) =>
+ event.name === 'graphql_cache.aggregate' &&
+ event.aggregatedEventName === 'graphql_cache.transaction'
+ );
+ expect(
+ aggregates.reduce((total, event) => total + (event.count ?? 0), 0)
+ ).toBe(149);
+ const firstErrorIndex = observations.findIndex(
+ (event) =>
+ event.name === 'graphql_cache.transaction' && event.outcome === 'error'
+ );
+ expect(observations[firstErrorIndex - 1]).toMatchObject({
+ name: 'graphql_cache.aggregate',
+ count: 49,
+ });
+ expect(
+ observations.filter(
+ (event) =>
+ event.name === 'graphql_cache.transaction' &&
+ event.outcome === 'error' &&
+ event.sampleRate === 1
+ )
+ ).toHaveLength(2);
+ });
+
+ it('never lets a throwing sink or injected recorder change the caller outcome', () => {
+ const recorder = new CacheTelemetryRecorder({
+ emit: () => {
+ throw new Error('exporter secret failure');
+ },
+ });
+ const reporter = new CacheTelemetryReporter(
+ browserCacheTelemetryContext('unknown'),
+ {
+ emit: () => {
+ throw new Error('otel down');
+ },
+ }
+ );
+
+ expect(() =>
+ recorder.record({
+ name: 'graphql_cache.db_ready',
+ operationCategory: 'initialization',
+ outcome: 'success',
+ })
+ ).not.toThrow();
+ expect(() =>
+ reporter.emit({
+ name: 'graphql_cache.reset_wipe',
+ operationCategory: 'storage',
+ outcome: 'error',
+ })
+ ).not.toThrow();
+ expect(() => recorder.flush()).not.toThrow();
+
+ const injected = isolateCacheTelemetry({
+ record: () => {
+ throw new Error('injected record failed');
+ },
+ flush: () => {
+ throw new Error('injected flush failed');
+ },
+ });
+ expect(() =>
+ injected.record({
+ name: 'graphql_cache.owner',
+ operationCategory: 'lifecycle',
+ })
+ ).not.toThrow();
+ expect(() => injected.flush()).not.toThrow();
+ });
+
+ it('bounds invalid numbers and unsafe runtime dimensions', () => {
+ const events: CacheTelemetryEnvelope[] = [];
+ const reporter = new CacheTelemetryReporter(
+ browserCacheTelemetryContext(
+ 'override',
+ 'Mozilla/5.0 Chrome/145.0.7632.6',
+ '[email protected]/private'
+ ),
+ { emit: (event) => events.push(event) }
+ );
+ reporter.emit({
+ name: 'graphql_cache.origin_storage_pressure',
+ operationCategory: 'storage',
+ usageBytes: -1,
+ quotaBytes: Number.POSITIVE_INFINITY,
+ ratio: 7,
+ });
+
+ expect(events[0]).toMatchObject({
+ browserFamily: 'chromium',
+ browserVersion: '145',
+ appVersion: 'unknown',
+ ratio: 1,
+ });
+ expect(events[0]).not.toHaveProperty('usageBytes');
+ expect(events[0]).not.toHaveProperty('quotaBytes');
+
+ const hostileContextEvents: CacheTelemetryEnvelope[] = [];
+ new CacheTelemetryReporter(
+ {
+ browserFamily: 'private-user' as never,
+ browserVersion: '151.0 user-secret',
+ appVersion: '[email protected]',
+ backend: 'private-backend' as never,
+ rolloutCohort: 'private-cohort' as never,
+ },
+ { emit: (event) => hostileContextEvents.push(event) }
+ ).emit({
+ name: 'graphql_cache.owner',
+ operationCategory: 'lifecycle',
+ });
+ expect(hostileContextEvents[0]).toMatchObject({
+ browserFamily: 'other',
+ browserVersion: 'unknown',
+ appVersion: 'unknown',
+ backend: 'turso-wasm-opfs',
+ rolloutCohort: 'unknown',
+ });
+ expect(JSON.stringify(hostileContextEvents)).not.toContain('private');
+ });
+});
diff --git a/apps/web/src/lib/graphql-cache/telemetry.ts b/apps/web/src/lib/graphql-cache/telemetry.ts
new file mode 100644
index 0000000000..b0d94111d3
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/telemetry.ts
@@ -0,0 +1,620 @@
+import { match } from 'ts-pattern';
+import type { CacheRequest } from './protocol';
+
+/** Fixed cache telemetry names. Dashboards must not accept ad-hoc names. */
+export const CACHE_TELEMETRY_EVENT_NAMES = [
+ 'graphql_cache.wasm_download',
+ 'graphql_cache.wasm_compile',
+ 'graphql_cache.wasm_instantiate',
+ 'graphql_cache.schema_init',
+ 'graphql_cache.db_ready',
+ 'graphql_cache.host_ready',
+ 'graphql_cache.host_request',
+ 'graphql_cache.coordinator_request',
+ 'graphql_cache.engine_request',
+ 'graphql_cache.transaction',
+ 'graphql_cache.read',
+ 'graphql_cache.owner',
+ 'graphql_cache.stale_drop',
+ 'graphql_cache.lock_wait',
+ 'graphql_cache.storage_reset_required',
+ 'graphql_cache.logical_reset',
+ 'graphql_cache.reset_wipe',
+ 'graphql_cache.origin_storage_pressure',
+ 'graphql_cache.linear_memory',
+ 'graphql_cache.queue_diagnostics',
+ 'graphql_cache.navigation',
+ 'graphql_cache.aggregate',
+] as const;
+
+export type CacheTelemetryEventName =
+ (typeof CACHE_TELEMETRY_EVENT_NAMES)[number];
+
+export const CACHE_OPERATION_CATEGORIES = [
+ 'initialization',
+ 'read',
+ 'write',
+ 'transaction',
+ 'queue',
+ 'inspection',
+ 'invalidation',
+ 'lifecycle',
+ 'storage',
+ 'navigation',
+ 'unknown',
+] as const;
+export type CacheOperationCategory =
+ (typeof CACHE_OPERATION_CATEGORIES)[number];
+
+export const CACHE_TELEMETRY_OUTCOMES = [
+ 'success',
+ 'error',
+ 'hit',
+ 'miss',
+ 'graceful',
+ 'abrupt',
+ 'granted',
+ 'denied',
+ 'unknown',
+] as const;
+export type CacheTelemetryOutcome = (typeof CACHE_TELEMETRY_OUTCOMES)[number];
+
+export const CACHE_OPEN_OUTCOMES = [
+ 'opened-existing',
+ 'opened-new',
+ 'reset-incompatible',
+ 'reset-corrupt',
+ 'reset-storage-uncertain',
+] as const;
+export type CacheOpenOutcome = (typeof CACHE_OPEN_OUTCOMES)[number];
+
+export const CACHE_QUEUE_DIAGNOSTICS_AVAILABILITY = [
+ 'available',
+ 'unavailable',
+] as const;
+export type CacheQueueDiagnosticsAvailability =
+ (typeof CACHE_QUEUE_DIAGNOSTICS_AVAILABILITY)[number];
+
+/** Payload-free, bounded error classes shared by all cache layers. */
+export const CACHE_ERROR_CODES = [
+ 'none',
+ 'unsupported',
+ 'timeout',
+ 'wasm-download',
+ 'wasm-compile',
+ 'wasm-instantiate',
+ 'schema',
+ 'integrity',
+ 'opfs-unavailable',
+ 'opfs-quota',
+ 'opfs-io',
+ 'lock',
+ 'owner-lost',
+ 'protocol',
+ 'transport',
+ 'storage-reset',
+ 'initialization',
+ 'unknown',
+] as const;
+export type CacheErrorCode = (typeof CACHE_ERROR_CODES)[number];
+
+export const CACHE_RESET_REASONS = [
+ 'explicit-clear',
+ 'identity-change',
+ 'namespace-mismatch',
+ 'integrity-failure',
+ 'storage-reset-required',
+ 'abrupt-owner-loss',
+ 'storage-eviction',
+ 'quota-failure',
+ 'unknown',
+] as const;
+export type CacheResetReason = (typeof CACHE_RESET_REASONS)[number];
+
+export const CACHE_OWNER_EVENTS = [
+ 'elected',
+ 'activated',
+ 'graceful-drain-started',
+ 'graceful-drain-completed',
+ 'abrupt-loss',
+ 'replacement',
+ 'multiple-owner-detected',
+] as const;
+export type CacheOwnerEvent = (typeof CACHE_OWNER_EVENTS)[number];
+
+export const CACHE_ROLLOUT_COHORTS = [
+ 'control',
+ 'treatment',
+ 'override',
+ 'unknown',
+] as const;
+export type CacheRolloutCohort = (typeof CACHE_ROLLOUT_COHORTS)[number];
+
+export type CacheTelemetryObservation = {
+ name: CacheTelemetryEventName;
+ /** Original fixed event name represented by an aggregate envelope. */
+ aggregatedEventName?: CacheTelemetryEventName;
+ operationCategory: CacheOperationCategory;
+ outcome?: CacheTelemetryOutcome;
+ errorCode?: CacheErrorCode;
+ resetReason?: CacheResetReason;
+ ownerEvent?: CacheOwnerEvent;
+ persistence?: 'granted' | 'denied' | 'unknown';
+ openOutcome?: CacheOpenOutcome;
+ queueDiagnosticsAvailability?: CacheQueueDiagnosticsAvailability;
+ resetAttempt?: 'wipe-before-open';
+ durationMs?: number;
+ bytes?: number;
+ highWaterBytes?: number;
+ usageBytes?: number;
+ quotaBytes?: number;
+ ratio?: number;
+ count?: number;
+ sampleRate?: number;
+ queueDepth?: number;
+ oldestAgeMs?: number;
+};
+
+/** The only cohort/browser/backend dimensions permitted on exported events. */
+export type CacheTelemetryContext = {
+ browserFamily: 'chromium' | 'firefox' | 'safari' | 'other';
+ browserVersion: string;
+ appVersion: string;
+ backend: 'turso-wasm-opfs';
+ rolloutCohort: CacheRolloutCohort;
+};
+
+export type CacheTelemetryEnvelope = Readonly<
+ CacheTelemetryContext & CacheTelemetryObservation
+>;
+
+export interface CacheTelemetryObservationSink {
+ emit(observation: CacheTelemetryObservation): void;
+}
+
+export interface CacheTelemetrySink {
+ emit(event: CacheTelemetryEnvelope): void;
+}
+
+export interface CacheTelemetryRecorderLike {
+ record(observation: CacheTelemetryObservation): void;
+ flush(): void;
+}
+
+const HIGH_VOLUME_NAMES = new Set<CacheTelemetryEventName>([
+ 'graphql_cache.host_request',
+ 'graphql_cache.coordinator_request',
+ 'graphql_cache.engine_request',
+ 'graphql_cache.transaction',
+ 'graphql_cache.read',
+]);
+
+const boundedNumber = (
+ value: number | undefined,
+ maximum = Number.MAX_SAFE_INTEGER
+): number | undefined =>
+ value !== undefined && Number.isFinite(value) && value >= 0
+ ? Math.min(value, maximum)
+ : undefined;
+
+function sanitizeObservation(
+ input: CacheTelemetryObservation
+): CacheTelemetryObservation | undefined {
+ if (!CACHE_TELEMETRY_EVENT_NAMES.includes(input.name)) return;
+ if (!CACHE_OPERATION_CATEGORIES.includes(input.operationCategory)) return;
+
+ return {
+ name: input.name,
+ ...(input.name === 'graphql_cache.aggregate' &&
+ input.aggregatedEventName !== undefined &&
+ HIGH_VOLUME_NAMES.has(input.aggregatedEventName)
+ ? { aggregatedEventName: input.aggregatedEventName }
+ : {}),
+ operationCategory: input.operationCategory,
+ ...(input.outcome !== undefined &&
+ CACHE_TELEMETRY_OUTCOMES.includes(input.outcome)
+ ? { outcome: input.outcome }
+ : {}),
+ ...(input.errorCode !== undefined &&
+ CACHE_ERROR_CODES.includes(input.errorCode)
+ ? { errorCode: input.errorCode }
+ : {}),
+ ...(input.resetReason !== undefined &&
+ CACHE_RESET_REASONS.includes(input.resetReason)
+ ? { resetReason: input.resetReason }
+ : {}),
+ ...(input.ownerEvent !== undefined &&
+ CACHE_OWNER_EVENTS.includes(input.ownerEvent)
+ ? { ownerEvent: input.ownerEvent }
+ : {}),
+ ...(input.persistence === 'granted' ||
+ input.persistence === 'denied' ||
+ input.persistence === 'unknown'
+ ? { persistence: input.persistence }
+ : {}),
+ ...(input.openOutcome !== undefined &&
+ CACHE_OPEN_OUTCOMES.includes(input.openOutcome)
+ ? { openOutcome: input.openOutcome }
+ : {}),
+ ...(input.queueDiagnosticsAvailability !== undefined &&
+ CACHE_QUEUE_DIAGNOSTICS_AVAILABILITY.includes(
+ input.queueDiagnosticsAvailability
+ )
+ ? {
+ queueDiagnosticsAvailability: input.queueDiagnosticsAvailability,
+ }
+ : {}),
+ ...(input.resetAttempt === 'wipe-before-open'
+ ? { resetAttempt: input.resetAttempt }
+ : {}),
+ ...(boundedNumber(input.durationMs, 3_600_000) !== undefined
+ ? { durationMs: boundedNumber(input.durationMs, 3_600_000) }
+ : {}),
+ ...(boundedNumber(input.bytes) !== undefined
+ ? { bytes: boundedNumber(input.bytes) }
+ : {}),
+ ...(boundedNumber(input.highWaterBytes) !== undefined
+ ? { highWaterBytes: boundedNumber(input.highWaterBytes) }
+ : {}),
+ ...(boundedNumber(input.usageBytes) !== undefined
+ ? { usageBytes: boundedNumber(input.usageBytes) }
+ : {}),
+ ...(boundedNumber(input.quotaBytes) !== undefined
+ ? { quotaBytes: boundedNumber(input.quotaBytes) }
+ : {}),
+ ...(boundedNumber(input.ratio, 1) !== undefined
+ ? { ratio: boundedNumber(input.ratio, 1) }
+ : {}),
+ ...(boundedNumber(input.count) !== undefined
+ ? { count: boundedNumber(input.count) }
+ : {}),
+ ...(boundedNumber(input.sampleRate) !== undefined
+ ? { sampleRate: boundedNumber(input.sampleRate) }
+ : {}),
+ ...(boundedNumber(input.queueDepth) !== undefined
+ ? { queueDepth: boundedNumber(input.queueDepth) }
+ : {}),
+ ...(boundedNumber(input.oldestAgeMs, 31_536_000_000) !== undefined
+ ? { oldestAgeMs: boundedNumber(input.oldestAgeMs, 31_536_000_000) }
+ : {}),
+ };
+}
+
+type Aggregate = {
+ template: CacheTelemetryObservation;
+ count: number;
+ totalDurationMs: number;
+};
+
+/**
+ * Exception-isolated recorder. High-volume successes are counted in bounded
+ * aggregates and sampled; every error remains individually visible.
+ */
+export class CacheTelemetryRecorder implements CacheTelemetryRecorderLike {
+ private readonly sampleSequences = new Map<string, number>();
+ private readonly aggregates = new Map<string, Aggregate>();
+
+ constructor(
+ private readonly sink: CacheTelemetryObservationSink,
+ private readonly sampleRate = 100,
+ private readonly aggregateEvery = 50
+ ) {}
+
+ record(input: CacheTelemetryObservation): void {
+ try {
+ const observation = sanitizeObservation(input);
+ if (!observation) return;
+ if (!HIGH_VOLUME_NAMES.has(observation.name)) {
+ this.safeEmit(observation);
+ return;
+ }
+ const isError =
+ observation.outcome === 'error' ||
+ observation.errorCode === 'owner-lost';
+ if (isError) {
+ // Make the denominator current before the raw error is observable.
+ // Matching successes remain counted exactly once in aggregates.
+ this.flushMatchingSuccesses(observation);
+ this.safeEmit({ ...observation, sampleRate: 1 });
+ return;
+ }
+
+ const key = JSON.stringify([
+ observation.name,
+ observation.operationCategory,
+ observation.outcome ?? 'unknown',
+ observation.errorCode ?? 'none',
+ ]);
+ const aggregate = this.aggregates.get(key) ?? {
+ template: observation,
+ count: 0,
+ totalDurationMs: 0,
+ };
+ const weight = observation.count ?? 1;
+ aggregate.count += weight;
+ aggregate.totalDurationMs += (observation.durationMs ?? 0) * weight;
+ this.aggregates.set(key, aggregate);
+ if (aggregate.count >= this.aggregateEvery) this.flushOne(key, aggregate);
+
+ const sampleSequence = (this.sampleSequences.get(key) ?? 0) + 1;
+ this.sampleSequences.set(key, sampleSequence);
+ const mustEmit =
+ this.sampleRate <= 1 || sampleSequence % this.sampleRate === 0;
+ if (mustEmit) {
+ this.safeEmit({
+ ...observation,
+ sampleRate: this.sampleRate,
+ });
+ }
+ } catch {
+ // Telemetry is deliberately unable to affect cache correctness.
+ }
+ }
+
+ flush(): void {
+ try {
+ for (const [key, aggregate] of this.aggregates) {
+ this.flushOne(key, aggregate);
+ }
+ } catch {
+ // A broken sink must not escape lifecycle cleanup.
+ }
+ }
+
+ private flushMatchingSuccesses(error: CacheTelemetryObservation): void {
+ for (const [key, aggregate] of this.aggregates) {
+ if (aggregate.template.name === error.name) {
+ this.flushOne(key, aggregate);
+ }
+ }
+ }
+
+ private flushOne(key: string, aggregate: Aggregate): void {
+ this.aggregates.delete(key);
+ const durationMs =
+ aggregate.count > 0
+ ? aggregate.totalDurationMs / aggregate.count
+ : undefined;
+ this.safeEmit({
+ name: 'graphql_cache.aggregate',
+ aggregatedEventName: aggregate.template.name,
+ operationCategory: aggregate.template.operationCategory,
+ outcome: aggregate.template.outcome,
+ errorCode: aggregate.template.errorCode,
+ count: aggregate.count,
+ durationMs,
+ sampleRate: 1,
+ });
+ }
+
+ private safeEmit(observation: CacheTelemetryObservation): void {
+ try {
+ this.sink.emit(observation);
+ } catch {
+ // Failure isolation is part of the telemetry contract.
+ }
+ }
+}
+
+/** Adds allowlisted runtime dimensions and strips every unknown property. */
+export class CacheTelemetryReporter implements CacheTelemetryObservationSink {
+ private readonly context: CacheTelemetryContext;
+
+ constructor(
+ context: CacheTelemetryContext,
+ private readonly sink: CacheTelemetrySink
+ ) {
+ this.context = {
+ browserFamily: ['chromium', 'firefox', 'safari', 'other'].includes(
+ context.browserFamily
+ )
+ ? context.browserFamily
+ : 'other',
+ browserVersion: /^\d{1,3}$/.test(context.browserVersion)
+ ? context.browserVersion
+ : 'unknown',
+ appVersion: /^\d+\.\d+$/.test(context.appVersion)
+ ? context.appVersion.slice(0, 16)
+ : 'unknown',
+ backend: 'turso-wasm-opfs',
+ rolloutCohort: CACHE_ROLLOUT_COHORTS.includes(context.rolloutCohort)
+ ? context.rolloutCohort
+ : 'unknown',
+ };
+ }
+
+ emit(input: CacheTelemetryObservation): void {
+ try {
+ const observation = sanitizeObservation(input);
+ if (!observation) return;
+ this.sink.emit(Object.freeze({ ...this.context, ...observation }));
+ } catch {
+ // Export failure cannot change request, transaction, or lifecycle state.
+ }
+ }
+}
+
+export const NOOP_CACHE_TELEMETRY: CacheTelemetryRecorderLike = Object.freeze({
+ record: () => undefined,
+ flush: () => undefined,
+});
+
+/** Wraps even an untrusted injected recorder in the correctness firewall. */
+export function isolateCacheTelemetry(
+ recorder: CacheTelemetryRecorderLike | undefined
+): CacheTelemetryRecorderLike {
+ if (!recorder) return NOOP_CACHE_TELEMETRY;
+ return {
+ record(observation): void {
+ try {
+ recorder.record(observation);
+ } catch {
+ // Injected sinks have the same failure-isolation contract as OTel.
+ }
+ },
+ flush(): void {
+ try {
+ recorder.flush();
+ } catch {
+ // Cleanup remains independent from exporter behavior.
+ }
+ },
+ };
+}
+
+export function operationCategoryForRequest(
+ request: Pick<CacheRequest, 'kind'>
+): CacheOperationCategory {
+ return match(request.kind)
+ .with('init', () => 'initialization' as const)
+ .with('read', 'read-records', () => 'read' as const)
+ .with('write', () => 'write' as const)
+ .with(
+ 'enqueue-optimistic-mutation',
+ 'claim-next-mutation',
+ 'defer-optimistic-write',
+ 'commit-optimistic-write',
+ 'rollback-optimistic-write',
+ () => 'transaction' as const
+ )
+ .with(
+ 'inspect-query',
+ 'inspect-query-variants',
+ () => 'inspection' as const
+ )
+ .with('invalidate', 'delete-records', () => 'invalidation' as const)
+ .with('teardown', 'clear', () => 'lifecycle' as const)
+ .exhaustive();
+}
+
+export function isStorageTransactionRequest(
+ request: Pick<CacheRequest, 'kind'>
+): boolean {
+ return [
+ 'write',
+ 'enqueue-optimistic-mutation',
+ 'claim-next-mutation',
+ 'defer-optimistic-write',
+ 'commit-optimistic-write',
+ 'rollback-optimistic-write',
+ 'invalidate',
+ 'delete-records',
+ 'clear',
+ ].includes(request.kind);
+}
+
+/** Classifies an error without retaining or exporting its message. */
+export function classifyCacheError(error: unknown): CacheErrorCode {
+ const message =
+ error instanceof Error
+ ? error.message.toLowerCase()
+ : typeof error === 'string'
+ ? error.toLowerCase()
+ : '';
+ if (message.includes('timeout')) return 'timeout';
+ if (message.includes('quota') || /\bfull\b/.test(message))
+ return 'opfs-quota';
+ if (message.includes('opfs') && message.includes('unavailable')) {
+ return 'opfs-unavailable';
+ }
+ if (message.includes('opfs') || message.includes('wal')) return 'opfs-io';
+ if (message.includes('lock')) return 'lock';
+ if (message.includes('owner epoch') || message.includes('owner-lost')) {
+ return 'owner-lost';
+ }
+ if (message.includes('protocol') || message.includes('envelope')) {
+ return 'protocol';
+ }
+ if (message.includes('transport') || message.includes('messageport')) {
+ return 'transport';
+ }
+ if (message.includes('schema') || message.includes('namespace')) {
+ return 'schema';
+ }
+ if (message.includes('integrity') || message.includes('corrupt')) {
+ return 'integrity';
+ }
+ if (message.includes('reset required')) return 'storage-reset';
+ if (message.includes('wasm')) return 'wasm-instantiate';
+ if (message.includes('initializ') || message.includes('open')) {
+ return 'initialization';
+ }
+ return 'unknown';
+}
+
+export function resetReasonForError(error: unknown): CacheResetReason {
+ const code = classifyCacheError(error);
+ if (code === 'opfs-quota') return 'quota-failure';
+ if (code === 'integrity') return 'integrity-failure';
+ if (code === 'schema') return 'namespace-mismatch';
+ if (code === 'owner-lost') return 'abrupt-owner-loss';
+ return 'storage-reset-required';
+}
+
+export function browserCacheTelemetryContext(
+ rolloutCohort: CacheRolloutCohort,
+ userAgent = typeof navigator === 'undefined' ? '' : navigator.userAgent,
+ appVersion = import.meta.env.__APP_VERSION__ ?? 'unknown'
+): CacheTelemetryContext {
+ const firefox = /Firefox\/(\d+(?:\.\d+)*)/i.exec(userAgent);
+ const chromium = /(?:Chrome|Chromium)\/(\d+(?:\.\d+)*)/i.exec(userAgent);
+ const safari =
+ /Safari\//i.test(userAgent) && !chromium
+ ? /Version\/(\d+(?:\.\d+)*)/i.exec(userAgent)
+ : null;
+ const match = firefox ?? chromium ?? safari;
+ const browserFamily = firefox
+ ? 'firefox'
+ : chromium
+ ? 'chromium'
+ : safari
+ ? 'safari'
+ : 'other';
+ const safeVersion = match?.[1]?.split('.')[0] ?? 'unknown';
+ const appRelease = /^(\d+)\.(\d+)/.exec(appVersion);
+ const safeAppVersion = appRelease
+ ? `${appRelease[1]}.${appRelease[2]}`.slice(0, 16)
+ : 'unknown';
+ return {
+ browserFamily,
+ browserVersion: safeVersion,
+ appVersion: safeAppVersion,
+ backend: 'turso-wasm-opfs',
+ rolloutCohort: CACHE_ROLLOUT_COHORTS.includes(rolloutCohort)
+ ? rolloutCohort
+ : 'unknown',
+ };
+}
+
+export function isCacheTelemetryObservation(
+ value: unknown
+): value is CacheTelemetryObservation {
+ if (typeof value !== 'object' || value === null) return false;
+ const candidate = sanitizeObservation(value as CacheTelemetryObservation);
+ if (!candidate) return false;
+ return Object.keys(value).every((key) =>
+ [
+ 'name',
+ 'aggregatedEventName',
+ 'operationCategory',
+ 'outcome',
+ 'errorCode',
+ 'resetReason',
+ 'ownerEvent',
+ 'persistence',
+ 'openOutcome',
+ 'queueDiagnosticsAvailability',
+ 'resetAttempt',
+ 'durationMs',
+ 'bytes',
+ 'highWaterBytes',
+ 'usageBytes',
+ 'quotaBytes',
+ 'ratio',
+ 'count',
+ 'sampleRate',
+ 'queueDepth',
+ 'oldestAgeMs',
+ ].includes(key)
+ );
+}
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/browser-test-wasm-module.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/browser-test-wasm-module.ts
new file mode 100644
index 0000000000..56c112c02f
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/browser-test-wasm-module.ts
@@ -0,0 +1,42 @@
+type BrowserTestCacheWasmModule = {
+ default(input?: { module_or_path?: unknown }): Promise<unknown>;
+ browserTestMakeNamespaceIncompatible(scope: string): Promise<void>;
+ browserTestCorruptQueuePayload(scope: string): Promise<void>;
+};
+
+let modulePromise:
+ | Promise<{ module: BrowserTestCacheWasmModule; wasmUrl: string }>
+ | undefined;
+
+/** Loads the separate feature-gated destructive-hook artifact for tests only. */
+export function loadBrowserTestCacheWasm(): Promise<{
+ module: BrowserTestCacheWasmModule;
+ wasmUrl: string;
+}> {
+ if (modulePromise) return modulePromise;
+ const initialization = (async () => {
+ const glueUrl = new URL(
+ '../../wasm-browser-test/cache_wasm_browser_test_hooks.js',
+ import.meta.url
+ ).href;
+ const wasmUrl = new URL(
+ '../../wasm-browser-test/cache_wasm_browser_test_hooks_bg.wasm',
+ import.meta.url
+ ).href;
+ const module = (await import(
+ /* @vite-ignore */ glueUrl
+ )) as BrowserTestCacheWasmModule;
+ const response = await fetch(wasmUrl);
+ if (!response.ok) {
+ throw new Error(`browser-test WASM returned HTTP ${response.status}`);
+ }
+ const compiled = await WebAssembly.compile(await response.arrayBuffer());
+ await module.default({ module_or_path: compiled });
+ return { module, wasmUrl };
+ })();
+ modulePromise = initialization;
+ void initialization.catch(() => {
+ if (modulePromise === initialization) modulePromise = undefined;
+ });
+ return initialization;
+}
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/browser-wire.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/browser-wire.ts
new file mode 100644
index 0000000000..06f7101e87
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/browser-wire.ts
@@ -0,0 +1,44 @@
+export type BrowserHarnessCommand =
+ | { kind: 'write'; commandId: string; value: string }
+ | { kind: 'read'; commandId: string }
+ | { kind: 'slow-read'; commandId: string }
+ | { kind: 'graceful-close'; commandId: string }
+ | { kind: 'crash-worker'; commandId: string }
+ | { kind: 'release-liveness-lock'; commandId: string }
+ | {
+ kind: 'stale-response';
+ commandId: string;
+ ownerEpoch: number;
+ routeId: number;
+ };
+
+export type BrowserHarnessEnvelope =
+ | {
+ source: 'harness';
+ targetTabId: string;
+ command: BrowserHarnessCommand;
+ }
+ | {
+ source: 'tab';
+ tabId: string;
+ event:
+ | { kind: 'adapter-created' }
+ | { kind: 'registered' }
+ | { kind: 'worker-created'; ownerEpoch: number }
+ | { kind: 'worker-terminated'; ownerEpoch: number; reason: string }
+ | { kind: 'engine-replaced'; ownerEpoch: number }
+ | { kind: 'cache-push'; pushKind: string }
+ | {
+ kind: 'command-result';
+ commandId: string;
+ ok: true;
+ result?: unknown;
+ }
+ | {
+ kind: 'command-result';
+ commandId: string;
+ ok: false;
+ error: string;
+ }
+ | { kind: 'protocol-error'; error: string };
+ };
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle-harness.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle-harness.ts
new file mode 100644
index 0000000000..70d3118fd2
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle-harness.ts
@@ -0,0 +1,253 @@
+import type { CacheHost } from '../../host/types';
+import { createWorkerCacheHost } from '../../host/worker-host';
+import { clearRegisteredCaches, registerCacheHost } from '../../lifecycle';
+
+const result = document.querySelector<HTMLElement>('#result');
+if (!result) throw new Error('missing Cache result node');
+
+const parameters = new URLSearchParams(location.search);
+const treatment = parameters.get('treatment') === 'true';
+const scope =
+ parameters.get('scope') ?? `cache-lifecycle-${crypto.randomUUID()}`;
+const NativeWorker = globalThis.Worker;
+const NativeSharedWorker = globalThis.SharedWorker;
+const engineWorkers: Worker[] = [];
+const constructedWorkerUrls: string[] = [];
+globalThis.Worker = new Proxy(NativeWorker, {
+ construct(target, args: ConstructorParameters<typeof Worker>) {
+ const worker = Reflect.construct(target, args) as Worker;
+ if (args[1]?.name?.startsWith('graphql-cache-engine:')) {
+ engineWorkers.push(worker);
+ constructedWorkerUrls.push(String(args[0]));
+ }
+ return worker;
+ },
+});
+globalThis.SharedWorker = new Proxy(NativeSharedWorker, {
+ construct(target, args: ConstructorParameters<typeof SharedWorker>) {
+ constructedWorkerUrls.push(String(args[0]));
+ return Reflect.construct(target, args) as SharedWorker;
+ },
+});
+let owner: CacheHost | undefined;
+let standby: CacheHost | undefined;
+let unregisterOwner: (() => void) | undefined;
+let hostConstructionCount = 0;
+
+const query = (
+ operationName: string
+) => `query ${operationName}($input: SoupInput!) {
+ user {
+ id
+ soup(input: $input) {
+ nextCursor
+ items { __typename id }
+ }
+ }
+}`;
+const variables = (limit: number) => ({ input: { limit } });
+const data = (identity: string, value: string) => ({
+ user: {
+ id: identity,
+ soup: {
+ nextCursor: null,
+ items: [{ __typename: 'GraphqlSoupDocument', id: value }],
+ },
+ },
+});
+
+function requireOwner(): CacheHost {
+ if (!owner) throw new Error('Cache cache host is not started');
+ return owner;
+}
+
+async function read(host: CacheHost, limit: number, name: string) {
+ return await host.readQuery({
+ query: query(name),
+ operationName: name,
+ variables: variables(limit),
+ });
+}
+
+async function startOwner(registerForLogout = false): Promise<void> {
+ if (!treatment) {
+ throw new Error('Cache control/default-off cannot activate cache');
+ }
+ if (owner) return;
+ hostConstructionCount += 1;
+ owner = createWorkerCacheHost({
+ scope,
+ requestTimeoutMs: 20_000,
+ initializationTimeoutMs: 20_000,
+ rolloutCohort: 'treatment',
+ });
+ if (registerForLogout) unregisterOwner = registerCacheHost(owner);
+ await read(owner, 1, 'CacheLifecycleQuery');
+}
+
+const api = {
+ scope,
+ rolloutMode(): 'control' | 'treatment' {
+ return treatment ? 'treatment' : 'control';
+ },
+ hostConstructionCount(): number {
+ return hostConstructionCount;
+ },
+ constructedWorkerUrls(): string[] {
+ return [...constructedWorkerUrls];
+ },
+ engineWorkerCount(): number {
+ return engineWorkers.length;
+ },
+ navigationDurationMs(): number {
+ return (
+ (
+ performance.getEntriesByType('navigation')[0] as
+ | PerformanceNavigationTiming
+ | undefined
+ )?.duration ?? 0
+ );
+ },
+ async start(): Promise<void> {
+ await startOwner();
+ if (standby) return;
+ hostConstructionCount += 1;
+ standby = createWorkerCacheHost({
+ scope,
+ requestTimeoutMs: 20_000,
+ initializationTimeoutMs: 20_000,
+ rolloutCohort: 'treatment',
+ });
+ await read(standby, 1, 'CacheLifecycleQuery');
+ },
+ async startSingle(): Promise<void> {
+ await startOwner();
+ },
+ async startLogoutHost(): Promise<void> {
+ await startOwner(true);
+ },
+ async write(
+ value: string,
+ identity = 'cache-lifecycle-user',
+ limit = 1
+ ): Promise<void> {
+ const host = requireOwner();
+ await host.writeQuery({
+ query: query('CacheLifecycleQuery'),
+ operationName: 'CacheLifecycleQuery',
+ variables: variables(limit),
+ data: data(identity, value),
+ identity,
+ });
+ },
+ async read(limit = 1): Promise<unknown> {
+ return await read(requireOwner(), limit, 'CacheLifecycleQuery');
+ },
+ async logoutReset(limit = 1): Promise<unknown> {
+ if (!unregisterOwner) {
+ throw new Error('Cache logout host is not registered');
+ }
+ await clearRegisteredCaches();
+ return await read(requireOwner(), limit, 'CacheLifecycleQuery');
+ },
+ async closeSamePageStandbyHost(): Promise<{
+ ownerRead: unknown;
+ engineWorkerCount: number;
+ }> {
+ if (!standby) throw new Error('Cache standby is not started');
+ standby.dispose();
+ standby = undefined;
+ return {
+ ownerRead: await read(requireOwner(), 1, 'CacheLifecycleQuery'),
+ engineWorkerCount: engineWorkers.length,
+ };
+ },
+ async startStandby(): Promise<void> {
+ if (!treatment) throw new Error('Cache control cannot start standby');
+ if (standby) return;
+ hostConstructionCount += 1;
+ standby = createWorkerCacheHost({
+ scope,
+ requestTimeoutMs: 20_000,
+ initializationTimeoutMs: 20_000,
+ rolloutCohort: 'treatment',
+ });
+ await read(standby, 1, 'CacheLifecycleQuery');
+ },
+ async cleanOwnerHandoff(): Promise<unknown> {
+ if (!standby) throw new Error('Cache standby is not started');
+ const retiring = requireOwner();
+ const replacement = standby;
+ standby = undefined;
+ retiring.dispose();
+ owner = replacement;
+ return await read(replacement, 1, 'CacheLifecycleQuery');
+ },
+ async identityReset(): Promise<{ old: unknown; current: unknown }> {
+ const host = requireOwner();
+ await host.writeQuery({
+ query: query('CacheLifecycleQuery'),
+ operationName: 'CacheLifecycleQuery',
+ variables: variables(1),
+ data: data('cache-lifecycle-user-a', 'identity-a'),
+ identity: 'cache-lifecycle-user-a',
+ });
+ await host.writeQuery({
+ query: query('CacheLifecycleQuery'),
+ operationName: 'CacheLifecycleQuery',
+ variables: variables(2),
+ data: data('cache-lifecycle-user-b', 'identity-b'),
+ identity: 'cache-lifecycle-user-b',
+ });
+ return {
+ old: await read(host, 1, 'CacheLifecycleQuery'),
+ current: await read(host, 2, 'CacheLifecycleQuery'),
+ };
+ },
+ async abruptOwnerLoss(): Promise<{
+ oldRequestRejected: boolean;
+ replacement: unknown;
+ }> {
+ const host = requireOwner();
+ await api.write('abrupt-must-wipe', 'cache-lifecycle-user-b', 3);
+ const currentWorker = engineWorkers.at(-1);
+ if (!currentWorker) throw new Error('missing elected Cache engine worker');
+ currentWorker.terminate();
+ const oldRequestRejected = await read(host, 3, 'CacheLifecycleQuery').then(
+ () => false,
+ () => true
+ );
+ const deadline = performance.now() + 20_000;
+ for (;;) {
+ try {
+ const replacement = await read(host, 3, 'CacheLifecycleQuery');
+ return { oldRequestRejected, replacement };
+ } catch (error) {
+ if (performance.now() >= deadline) throw error;
+ await new Promise<void>((resolve) => setTimeout(resolve, 50));
+ }
+ }
+ },
+ dispose(): void {
+ unregisterOwner?.();
+ unregisterOwner = undefined;
+ owner?.dispose();
+ standby?.dispose();
+ owner = undefined;
+ standby = undefined;
+ },
+};
+
+declare global {
+ interface Window {
+ cacheLifecycleHarness: typeof api;
+ }
+}
+
+window.cacheLifecycleHarness = api;
+result.dataset.status = 'ready';
+result.dataset.rollout = treatment ? 'treatment' : 'control';
+result.textContent = JSON.stringify({
+ scopeFreeTelemetry: true,
+ rollout: result.dataset.rollout,
+});
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle.browser.e2e.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle.browser.e2e.ts
new file mode 100644
index 0000000000..9e123d941b
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle.browser.e2e.ts
@@ -0,0 +1,537 @@
+import { basename } from 'node:path';
+import { expect, test } from '@playwright/test';
+
+const harnessPath = (projectName: string): string =>
+ projectName.includes('production')
+ ? '/app/cache-lifecycle.html'
+ : '/cache-lifecycle.html';
+
+const isHit = (value: unknown): boolean =>
+ typeof value === 'object' &&
+ value !== null &&
+ (value as { kind?: unknown }).kind === 'hit';
+
+const isMiss = (value: unknown): boolean =>
+ typeof value === 'object' &&
+ value !== null &&
+ (value as { kind?: unknown }).kind === 'miss';
+
+test.describe.configure({ mode: 'serial' });
+
+const cacheResources = (urls: string[]) => ({
+ wasm: [
+ ...new Set(
+ urls.filter((url) => /cache_wasm_bg(?:-[\w-]+)?\.wasm(?:\?|$)/.test(url))
+ ),
+ ],
+ engine: [
+ ...new Set(urls.filter((url) => /cache\.engine-worker[^/]*\.js/.test(url))),
+ ],
+ coordinator: [
+ ...new Set(
+ urls.filter((url) =>
+ /cache\.coordinator\.shared-worker[^/]*\.js/.test(url)
+ )
+ ),
+ ],
+});
+
+test('Cache exact host stays navigation-lazy, preserves offline handoff, resets identity, and wipes abrupt loss', async ({
+ context,
+ page,
+}, testInfo) => {
+ const requestedUrls: string[] = [];
+ const browserErrors: string[] = [];
+ const failedResponses: string[] = [];
+ const failedRequests: string[] = [];
+ context.on('request', (request) => requestedUrls.push(request.url()));
+ context.on('requestfailed', (request) => {
+ failedRequests.push(
+ `${request.failure()?.errorText ?? 'failed'} ${request.url()}`
+ );
+ });
+ context.on('response', (response) => {
+ if (response.status() >= 400) {
+ failedResponses.push(`${response.status()} ${response.url()}`);
+ }
+ });
+ page.on('console', (message) => {
+ if (message.type() === 'error') {
+ browserErrors.push(
+ `${message.text()} @ ${message.location().url || 'unknown'}`
+ );
+ }
+ });
+ page.on('pageerror', (error) => browserErrors.push(error.message));
+
+ const path = harnessPath(testInfo.project.name);
+ await page.goto(path);
+ await expect(page.locator('#result')).toHaveAttribute('data-status', 'ready');
+ await expect(page.locator('#result')).toHaveAttribute(
+ 'data-rollout',
+ 'control'
+ );
+ expect(
+ await page.evaluate(() => ({
+ mode: window.cacheLifecycleHarness.rolloutMode(),
+ hostCount: window.cacheLifecycleHarness.hostConstructionCount(),
+ workerCount: window.cacheLifecycleHarness.constructedWorkerUrls().length,
+ }))
+ ).toEqual({ mode: 'control', hostCount: 0, workerCount: 0 });
+ expect(cacheResources(requestedUrls)).toEqual({
+ wasm: [],
+ engine: [],
+ coordinator: [],
+ });
+
+ const scope = `cache-lifecycle-playwright-${crypto.randomUUID()}`;
+ await page.goto(`${path}?treatment=true&scope=${encodeURIComponent(scope)}`);
+ await expect(page.locator('#result')).toHaveAttribute('data-status', 'ready');
+ await expect(page.locator('#result')).toHaveAttribute(
+ 'data-rollout',
+ 'treatment'
+ );
+ expect(
+ await page.evaluate(() =>
+ window.cacheLifecycleHarness.hostConstructionCount()
+ )
+ ).toBe(0);
+ const beforeFirstUse = cacheResources([
+ ...requestedUrls,
+ ...(await page.evaluate(() =>
+ window.cacheLifecycleHarness.constructedWorkerUrls()
+ )),
+ ]);
+ expect(beforeFirstUse.wasm).toEqual([]);
+ expect(beforeFirstUse.engine).toEqual([]);
+ expect(beforeFirstUse.coordinator).toEqual([]);
+
+ await page.evaluate(() => window.cacheLifecycleHarness.start());
+ await expect
+ .poll(() => cacheResources(requestedUrls).wasm.length, { timeout: 30_000 })
+ .toBe(1);
+ const afterFirstUse = cacheResources([
+ ...requestedUrls,
+ ...(await page.evaluate(() =>
+ window.cacheLifecycleHarness.constructedWorkerUrls()
+ )),
+ ]);
+ expect(afterFirstUse.engine).toHaveLength(1);
+ expect(afterFirstUse.coordinator).toHaveLength(1);
+
+ await page.evaluate(() =>
+ window.cacheLifecycleHarness.write(
+ 'offline-preserved',
+ 'cache-lifecycle-offline-user'
+ )
+ );
+ const standbyClose = await page.evaluate(() =>
+ window.cacheLifecycleHarness.closeSamePageStandbyHost()
+ );
+ expect(isHit(standbyClose.ownerRead)).toBe(true);
+ expect(standbyClose.engineWorkerCount).toBe(1);
+ await page.evaluate(() => window.cacheLifecycleHarness.startStandby());
+ await context.setOffline(true);
+ const offlineHandoff = await page.evaluate(() =>
+ window.cacheLifecycleHarness.cleanOwnerHandoff()
+ );
+ expect(isHit(offlineHandoff)).toBe(true);
+ await context.setOffline(false);
+
+ const identity = await page.evaluate(() =>
+ window.cacheLifecycleHarness.identityReset()
+ );
+ expect(isMiss(identity.old)).toBe(true);
+ expect(isHit(identity.current)).toBe(true);
+
+ const abrupt = await page.evaluate(() =>
+ window.cacheLifecycleHarness.abruptOwnerLoss()
+ );
+ expect(abrupt.oldRequestRejected).toBe(true);
+ expect(isMiss(abrupt.replacement)).toBe(true);
+
+ const isolation = await page.evaluate(() => ({
+ crossOriginIsolated: globalThis.crossOriginIsolated,
+ sharedArrayBufferCreated:
+ typeof globalThis.SharedArrayBuffer === 'function' &&
+ globalThis.crossOriginIsolated,
+ }));
+ expect(isolation).toEqual({
+ crossOriginIsolated: false,
+ sharedArrayBufferCreated: false,
+ });
+ expect({ browserErrors, failedResponses, failedRequests }).toEqual({
+ browserErrors: [],
+ failedResponses: [],
+ failedRequests: [],
+ });
+
+ const resources = cacheResources([
+ ...requestedUrls,
+ ...(await page.evaluate(() =>
+ window.cacheLifecycleHarness.constructedWorkerUrls()
+ )),
+ ]);
+ const mode = testInfo.project.name.includes('production')
+ ? 'production'
+ : 'development';
+ if (mode === 'production') {
+ expect(resources.wasm).toHaveLength(1);
+ expect(basename(new URL(resources.wasm[0]!).pathname)).toMatch(
+ /^cache_wasm_bg-[\w-]+\.wasm$/
+ );
+ expect(resources.engine.every((url) => url.includes('/app/'))).toBe(true);
+ expect(resources.coordinator.every((url) => url.includes('/app/'))).toBe(
+ true
+ );
+ }
+
+ await page.evaluate(() => window.cacheLifecycleHarness.dispose());
+});
+
+test('Cache real standby tab close preserves the same active engine', async ({
+ context,
+ page,
+}, testInfo) => {
+ test.skip(
+ !testInfo.project.name.includes('production'),
+ 'Cache rollout evidence requires the production bundle'
+ );
+ const scope = `cache-lifecycle-standby-tab-${crypto.randomUUID()}`;
+ const path = `${harnessPath(testInfo.project.name)}?treatment=true&scope=${encodeURIComponent(scope)}`;
+ await page.goto(path);
+ await expect(page.locator('#result')).toHaveAttribute('data-status', 'ready');
+ await page.evaluate(() => window.cacheLifecycleHarness.startSingle());
+ expect(
+ await page.evaluate(() => window.cacheLifecycleHarness.engineWorkerCount())
+ ).toBe(1);
+ const ownerWorkerUrls = await page.evaluate(() =>
+ window.cacheLifecycleHarness.constructedWorkerUrls()
+ );
+ await page.evaluate(() =>
+ window.cacheLifecycleHarness.write('real-standby-preserved')
+ );
+
+ const standbyPage = await context.newPage();
+ await standbyPage.goto(path);
+ await expect(standbyPage.locator('#result')).toHaveAttribute(
+ 'data-status',
+ 'ready'
+ );
+ await standbyPage.evaluate(() => window.cacheLifecycleHarness.startSingle());
+ expect(
+ await standbyPage.evaluate(() =>
+ window.cacheLifecycleHarness.engineWorkerCount()
+ )
+ ).toBe(0);
+ expect(
+ await standbyPage.evaluate(() => window.cacheLifecycleHarness.read())
+ ).toMatchObject({
+ kind: 'hit',
+ data: {
+ user: {
+ soup: { items: [{ id: 'real-standby-preserved' }] },
+ },
+ },
+ });
+
+ await standbyPage.close();
+ await page.evaluate(() =>
+ window.cacheLifecycleHarness.write('owner-after-real-standby-close')
+ );
+ expect(
+ await page.evaluate(() => window.cacheLifecycleHarness.read())
+ ).toMatchObject({
+ kind: 'hit',
+ data: {
+ user: {
+ soup: { items: [{ id: 'owner-after-real-standby-close' }] },
+ },
+ },
+ });
+ expect(
+ await page.evaluate(() => window.cacheLifecycleHarness.engineWorkerCount())
+ ).toBe(1);
+ expect(
+ await page.evaluate(() =>
+ window.cacheLifecycleHarness.constructedWorkerUrls()
+ )
+ ).toEqual(ownerWorkerUrls);
+ await page.evaluate(() => window.cacheLifecycleHarness.dispose());
+});
+
+test('Cache actual logout cache lifecycle wipes the registered production host', async ({
+ page,
+}, testInfo) => {
+ test.skip(
+ !testInfo.project.name.includes('production'),
+ 'Cache rollout evidence requires the production bundle'
+ );
+ const scope = `cache-lifecycle-logout-${crypto.randomUUID()}`;
+ const path = `${harnessPath(testInfo.project.name)}?treatment=true&scope=${encodeURIComponent(scope)}`;
+ await page.goto(path);
+ await expect(page.locator('#result')).toHaveAttribute('data-status', 'ready');
+ await page.evaluate(() => window.cacheLifecycleHarness.startLogoutHost());
+ await page.evaluate(() =>
+ window.cacheLifecycleHarness.write('logout-must-wipe')
+ );
+ expect(
+ isHit(await page.evaluate(() => window.cacheLifecycleHarness.read()))
+ ).toBe(true);
+ expect(
+ isMiss(
+ await page.evaluate(() => window.cacheLifecycleHarness.logoutReset())
+ )
+ ).toBe(true);
+ await page.evaluate(() => window.cacheLifecycleHarness.write('post-logout'));
+ expect(
+ isHit(await page.evaluate(() => window.cacheLifecycleHarness.read()))
+ ).toBe(true);
+ await page.evaluate(() => window.cacheLifecycleHarness.dispose());
+});
+
+test('Cache actual GraphQL Soup selector stays default-off without browser cache resources', async ({
+ page,
+}, testInfo) => {
+ test.skip(
+ !testInfo.project.name.includes('production'),
+ 'Cache rollout evidence requires the production bundle'
+ );
+ const requestedUrls: string[] = [];
+ page.on('request', (request) => requestedUrls.push(request.url()));
+ await page.goto(
+ testInfo.project.name.includes('production')
+ ? '/app/graphql-soup-rollout.html'
+ : '/graphql-soup-rollout.html'
+ );
+ await expect(page.locator('#result')).toHaveAttribute('data-status', 'ready');
+ const result = await page.evaluate(() =>
+ window.graphqlSoupRolloutHarness.resolveDefaultOff()
+ );
+ expect(result).toEqual({
+ cacheEnabled: false,
+ cacheHostPresent: false,
+ resources: { workerUrls: [], sharedWorkerUrls: [] },
+ });
+ expect(cacheResources(requestedUrls)).toEqual({
+ wasm: [],
+ engine: [],
+ coordinator: [],
+ });
+});
+
+test('Cache actual PostHog treatment override is lazy and kill applies on navigation', async ({
+ page,
+}, testInfo) => {
+ test.skip(
+ !testInfo.project.name.includes('production'),
+ 'Cache rollout evidence requires the production bundle'
+ );
+ const requestedUrls: string[] = [];
+ page.on('request', (request) => requestedUrls.push(request.url()));
+ const posthogRequests = () =>
+ requestedUrls.filter((url) => {
+ const parsed = new URL(url);
+ return (
+ parsed.hostname.includes('posthog') ||
+ parsed.pathname.includes('/__cache-rollout-posthog-disabled') ||
+ parsed.pathname.includes('/i/ph/')
+ );
+ });
+ const path = '/app/graphql-soup-rollout.html';
+ await page.goto(path);
+ await expect(page.locator('#result')).toHaveAttribute('data-status', 'ready');
+ const treatment = await page.evaluate(() =>
+ window.graphqlSoupRolloutHarness.tryTreatment()
+ );
+ expect(
+ treatment.overrideApplied,
+ 'the required supported PostHog override must be available'
+ ).toBe(true);
+ if (!treatment.overrideApplied) {
+ throw new Error('required PostHog treatment override was unavailable');
+ }
+
+ expect(treatment.lazyBeforeRead).toBe(true);
+ expect(treatment.readKind).toBe('miss');
+ expect(treatment.samePageKillLatched).toBe(true);
+ expect(treatment.posthogBeforeSendCalls).toBe(0);
+ expect(treatment.resources.workerUrls).toHaveLength(1);
+ expect(treatment.resources.workerUrls[0]).toMatch(
+ /cache\.engine-worker-[A-Za-z0-9_-]+\.js$/
+ );
+ expect(treatment.resources.sharedWorkerUrls).toHaveLength(1);
+ expect(treatment.resources.sharedWorkerUrls[0]).toMatch(
+ /cache\.coordinator\.shared-worker-[A-Za-z0-9_-]+\.js$/
+ );
+ expect(cacheResources(requestedUrls).wasm).toHaveLength(1);
+ expect(posthogRequests()).toEqual([]);
+
+ const requestCountBeforeNavigation = requestedUrls.length;
+ await page.goto(path);
+ await expect(page.locator('#result')).toHaveAttribute('data-status', 'ready');
+ const afterNavigation = await page.evaluate(() =>
+ window.graphqlSoupRolloutHarness.resolveAfterNavigationKill()
+ );
+ expect(afterNavigation).toEqual({
+ cacheEnabled: false,
+ cacheHostPresent: false,
+ posthogBeforeSendCalls: 0,
+ resources: { workerUrls: [], sharedWorkerUrls: [] },
+ });
+ expect(
+ cacheResources(requestedUrls.slice(requestCountBeforeNavigation))
+ ).toEqual({ wasm: [], engine: [], coordinator: [] });
+ expect(posthogRequests()).toEqual([]);
+});
+
+test('Cache terminates each admitted mutating RPC before core without replay', async ({
+ context,
+ page,
+}, testInfo) => {
+ test.skip(
+ !testInfo.project.name.includes('production'),
+ 'Cache fault evidence requires the production bundle'
+ );
+ testInfo.setTimeout(360_000);
+ const requestedUrls: string[] = [];
+ context.on('request', (request) => requestedUrls.push(request.url()));
+ await page.goto('/app/cache-recovery.html');
+ await expect(page.locator('#result')).toHaveAttribute('data-status', 'ready');
+ const kinds = await page.evaluate(
+ () => window.cacheRecoveryHarness.mutatingRequestKinds
+ );
+ expect(kinds).toEqual([
+ 'write',
+ 'enqueue-optimistic-mutation',
+ 'claim-next-mutation',
+ 'defer-optimistic-write',
+ 'commit-optimistic-write',
+ 'rollback-optimistic-write',
+ 'invalidate',
+ 'delete-records',
+ 'clear',
+ ]);
+ const results = [];
+ for (const kind of kinds) {
+ results.push(
+ await page.evaluate(
+ async (requestKind) =>
+ await window.cacheRecoveryHarness.runFaultKind(requestKind),
+ kind
+ )
+ );
+ }
+ for (const result of results) {
+ expect(result).toMatchObject({
+ actualDedicatedWorkerTerminated: true,
+ requestAdmittedBeforeCore: true,
+ midSqlExecutionClaimed: false,
+ oldRequestRejected: true,
+ replacementRecordsEmpty: true,
+ replacementQueueEmpty: true,
+ mutationAdmissionCount: 1,
+ unexpectedReplacementMutatingAdmissionCount: 0,
+ replacementAdmissionBarrierObserved: true,
+ resetPhaseSequence: [
+ 'graphql_cache.storage_reset_required',
+ 'graphql_cache.logical_reset',
+ 'graphql_cache.reset_wipe',
+ ],
+ exactProductionTursoWasm: true,
+ queueTelemetryObserved: true,
+ performanceMemoryAvailable: false,
+ userAgentSpecificMemoryAvailable: false,
+ });
+ }
+ expect(cacheResources(requestedUrls).wasm).toHaveLength(1);
+ expect(cacheResources(requestedUrls).engine).toHaveLength(1);
+});
+
+test('Cache lock-safe incompatible namespace and corrupt queue payload recover exactly once', async ({
+ context,
+ page,
+}, testInfo) => {
+ test.skip(
+ !testInfo.project.name.includes('production'),
+ 'Cache recovery evidence requires the production bundle'
+ );
+ testInfo.setTimeout(180_000);
+ const requestedUrls: string[] = [];
+ context.on('request', (request) => requestedUrls.push(request.url()));
+ await page.goto('/app/cache-recovery.html');
+ await expect(page.locator('#result')).toHaveAttribute('data-status', 'ready');
+ const recoveryHookUrls = new Set<string>();
+ for (const [kind, openOutcome] of [
+ ['incompatible-namespace', 'reset-incompatible'],
+ ['corrupt-queue-payload', 'reset-corrupt'],
+ ] as const) {
+ const result = await page.evaluate(
+ async (recoveryKind) =>
+ await window.cacheRecoveryHarness.runRecoveryKind(recoveryKind),
+ kind
+ );
+ expect(result).toMatchObject({
+ kind,
+ gracefulCloseBeforeMutation: true,
+ separateFeatureGatedBrowserTestArtifact: true,
+ productionArtifactDebugExportsAbsent: true,
+ browserTestWasmUrl: expect.stringMatching(
+ /cache_wasm_browser_test_hooks_bg-[A-Za-z0-9_-]+\.wasm$/
+ ),
+ browserTestWorkerOnlyControl: true,
+ productionCoordinatorProtocolUnchanged: true,
+ openOutcome,
+ recordsWiped: true,
+ durableQueueWiped: true,
+ usableAfterReset: true,
+ storageResetRequiredCount: 1,
+ logicalResetCount: 1,
+ resetWipeCount: 1,
+ queueTelemetryObserved: true,
+ });
+ recoveryHookUrls.add(result.browserTestWasmUrl);
+ }
+ expect(recoveryHookUrls.size).toBe(1);
+ const [recoveryHookUrl] = [...recoveryHookUrls];
+ if (!recoveryHookUrl) throw new Error('missing recovery-hook WASM URL');
+ const hookResponse = await context.request.get(recoveryHookUrl);
+ expect(hookResponse.ok()).toBe(true);
+ expect(cacheResources(requestedUrls).wasm).toHaveLength(1);
+ expect(cacheResources(requestedUrls).engine).toHaveLength(1);
+});
+
+test('Cache Chromium storage eviction reopens empty without fabricated Firefox coverage', async ({
+ context,
+ page,
+}, testInfo) => {
+ test.skip(
+ !testInfo.project.name.startsWith('chromium'),
+ 'Chromium CDP is the only local storage-eviction control available'
+ );
+ const path = harnessPath(testInfo.project.name);
+ const scope = `cache-lifecycle-eviction-${crypto.randomUUID()}`;
+ await page.goto(`${path}?treatment=true&scope=${encodeURIComponent(scope)}`);
+ await expect(page.locator('#result')).toHaveAttribute('data-status', 'ready');
+ await page.evaluate(async () => {
+ await window.cacheLifecycleHarness.start();
+ await window.cacheLifecycleHarness.write(
+ 'evict-me',
+ 'cache-lifecycle-eviction-user'
+ );
+ window.cacheLifecycleHarness.dispose();
+ });
+ await page.waitForTimeout(1_000);
+
+ const cdp = await context.newCDPSession(page);
+ await cdp.send('Storage.clearDataForOrigin', {
+ origin: new URL(page.url()).origin,
+ storageTypes: 'file_systems',
+ });
+ const reopened = await page.evaluate(async () => {
+ await window.cacheLifecycleHarness.start();
+ return await window.cacheLifecycleHarness.read();
+ });
+ expect(isMiss(reopened)).toBe(true);
+ await page.evaluate(() => window.cacheLifecycleHarness.dispose());
+});
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle.html b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle.html
new file mode 100644
index 0000000000..988046255f
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <link rel="icon" href="data:," />
+ <title>Cache exact cache lifecycle harness</title>
+ </head>
+ <body>
+ <main id="result" data-status="loading">loading</main>
+ <script type="module" src="./cache-lifecycle-harness.ts"></script>
+ </body>
+</html>
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/cache-recovery-harness.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-recovery-harness.ts
new file mode 100644
index 0000000000..a954dc7a78
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-recovery-harness.ts
@@ -0,0 +1,709 @@
+import type { CacheRequest } from '../../protocol';
+import type {
+ ProductionCacheRequestWithoutId,
+ ProductionHarnessCommand,
+ ProductionHarnessEnvelope,
+} from './production-browser-wire';
+
+const resultElement = document.querySelector<HTMLElement>('#result');
+if (!resultElement) throw new Error('missing Cache internal result element');
+
+export const CACHE_MUTATING_REQUEST_KINDS = [
+ 'write',
+ 'enqueue-optimistic-mutation',
+ 'claim-next-mutation',
+ 'defer-optimistic-write',
+ 'commit-optimistic-write',
+ 'rollback-optimistic-write',
+ 'invalidate',
+ 'delete-records',
+ 'clear',
+] as const satisfies readonly CacheRequest['kind'][];
+
+type MutatingRequestKind = (typeof CACHE_MUTATING_REQUEST_KINDS)[number];
+type RecoveryKind = 'incompatible-namespace' | 'corrupt-queue-payload';
+type CommandWithoutId = ProductionHarnessCommand extends infer Command
+ ? Command extends ProductionHarnessCommand
+ ? Omit<Command, 'commandId'>
+ : never
+ : never;
+
+type RuntimeTelemetry = {
+ kind: string;
+ tabId?: string;
+ ownerEpoch?: number;
+ requestId?: number;
+ requestKind?: string;
+ databaseAction?: string;
+ performanceMemoryAvailable?: boolean;
+ userAgentSpecificMemoryAvailable?: boolean;
+ admissionBarrier?: boolean;
+ fatalCode?: string;
+};
+
+type QueueTelemetry = {
+ name?: string;
+ openOutcome?: string;
+ queueDepth?: number;
+ oldestAgeMs?: number;
+};
+
+const QUERY = `query Soup($input: SoupInput!) {
+ user {
+ id
+ soup(input: $input) {
+ nextCursor
+ items { __typename id }
+ }
+ }
+}`;
+const MUTATION = `mutation SetEntityProperty($input: SetEntityPropertyInput!) {
+ setEntityProperty(input: $input) { id displayName }
+}`;
+const VARIABLES = { input: { limit: 1 } };
+const MUTATION_VARIABLES = {
+ input: {
+ entityType: 'DOCUMENT',
+ entityId: 'doc-1',
+ propertyDefinitionId: 'def-1',
+ value: { string: 'x' },
+ },
+};
+
+const assert: (condition: unknown, message: string) => asserts condition = (
+ condition,
+ message
+) => {
+ if (!condition) throw new Error(message);
+};
+
+const waitUntil = async (
+ description: string,
+ predicate: () => boolean,
+ timeoutMs = 30_000
+): Promise<void> => {
+ const started = performance.now();
+ while (!predicate()) {
+ if (performance.now() - started > timeoutMs) {
+ throw new Error(`timed out waiting for ${description}`);
+ }
+ await new Promise<void>((resolve) => setTimeout(resolve, 20));
+ }
+};
+
+class ProductionSession {
+ readonly runtimeTelemetry: RuntimeTelemetry[] = [];
+ readonly cacheTelemetry: QueueTelemetry[] = [];
+ private readonly tabs = new Map<string, HTMLIFrameElement>();
+ private readonly registered = new Set<string>();
+ private readonly pending = new Map<
+ string,
+ {
+ resolve: (value: unknown) => void;
+ reject: (error: Error) => void;
+ timer: ReturnType<typeof setTimeout>;
+ }
+ >();
+ private readonly tabChannel: BroadcastChannel;
+ private readonly runtimeChannel: BroadcastChannel;
+ private readonly cacheTelemetryChannel = new BroadcastChannel(
+ 'macro:graphql-cache-telemetry:v1'
+ );
+
+ constructor(readonly scope: string) {
+ this.tabChannel = new BroadcastChannel(
+ `graphql-cache-wp08-production-tabs:${scope}`
+ );
+ this.runtimeChannel = new BroadcastChannel(
+ `graphql-cache-wp08-production:${scope}`
+ );
+ this.tabChannel.onmessage = (
+ event: MessageEvent<ProductionHarnessEnvelope>
+ ) => {
+ const envelope = event.data;
+ if (envelope.source !== 'tab') return;
+ switch (envelope.event.kind) {
+ case 'registered':
+ this.registered.add(envelope.tabId);
+ break;
+ case 'command-result': {
+ const pending = this.pending.get(envelope.event.commandId);
+ if (!pending) return;
+ this.pending.delete(envelope.event.commandId);
+ clearTimeout(pending.timer);
+ if (envelope.event.ok) pending.resolve(envelope.event.result);
+ else pending.reject(new Error(envelope.event.error));
+ break;
+ }
+ case 'protocol-error':
+ throw new Error(envelope.event.error);
+ }
+ };
+ this.runtimeChannel.onmessage = (event: MessageEvent<RuntimeTelemetry>) => {
+ this.runtimeTelemetry.push(event.data);
+ };
+ this.cacheTelemetryChannel.onmessage = (
+ event: MessageEvent<QueueTelemetry>
+ ) => {
+ this.cacheTelemetry.push(event.data);
+ };
+ }
+
+ async openTab(tabId: string): Promise<void> {
+ const readyBefore = this.runtimeTelemetry.filter(
+ (event) => event.kind === 'ready'
+ ).length;
+ const url = new URL('./production-tab.html', location.href);
+ url.searchParams.set('scope', this.scope);
+ url.searchParams.set('tabId', tabId);
+ const frame = document.createElement('iframe');
+ frame.name = `${this.scope}:${tabId}`;
+ frame.src = url.href;
+ frame.hidden = true;
+ document.body.append(frame);
+ this.tabs.set(tabId, frame);
+ await waitUntil(`${tabId} registration`, () => this.registered.has(tabId));
+ await waitUntil(
+ `${tabId} engine ready`,
+ () =>
+ this.runtimeTelemetry.filter((event) => event.kind === 'ready').length >
+ readyBefore
+ );
+ }
+
+ command(tabId: string, command: CommandWithoutId): Promise<unknown> {
+ const commandId = crypto.randomUUID();
+ const result = new Promise<unknown>((resolve, reject) => {
+ const timer = setTimeout(() => {
+ this.pending.delete(commandId);
+ reject(new Error(`production command timed out: ${command.kind}`));
+ }, 30_000);
+ this.pending.set(commandId, { resolve, reject, timer });
+ });
+ this.tabChannel.postMessage({
+ source: 'harness',
+ targetTabId: tabId,
+ command: { ...command, commandId } as ProductionHarnessCommand,
+ } satisfies ProductionHarnessEnvelope);
+ return result;
+ }
+
+ async gracefulClose(tabId: string): Promise<void> {
+ const drainedBefore = this.runtimeTelemetry.filter(
+ (event) => event.kind === 'drained'
+ ).length;
+ await this.command(tabId, { kind: 'graceful-close' });
+ await waitUntil(
+ `${tabId} graceful drain`,
+ () =>
+ this.runtimeTelemetry.filter((event) => event.kind === 'drained')
+ .length > drainedBefore
+ );
+ this.tabs.get(tabId)?.remove();
+ this.tabs.delete(tabId);
+ }
+
+ close(): void {
+ for (const frame of this.tabs.values()) frame.remove();
+ for (const pending of this.pending.values()) {
+ clearTimeout(pending.timer);
+ pending.reject(new Error('production session closed'));
+ }
+ this.pending.clear();
+ this.tabChannel.close();
+ this.runtimeChannel.close();
+ this.cacheTelemetryChannel.close();
+ }
+}
+
+const writeRequest = (value: string): ProductionCacheRequestWithoutId => ({
+ kind: 'write',
+ query: QUERY,
+ operationName: 'Soup',
+ variables: VARIABLES,
+ data: {
+ user: {
+ id: 'cache-recovery-user',
+ soup: {
+ nextCursor: null,
+ items: [{ __typename: 'GraphqlSoupDocument', id: value }],
+ },
+ },
+ },
+ identity: 'cache-recovery-identity',
+});
+
+const enqueueRequest = (
+ owner: string,
+ createdAtMs: number
+): ProductionCacheRequestWithoutId => ({
+ kind: 'enqueue-optimistic-mutation',
+ query: MUTATION,
+ operationName: 'SetEntityProperty',
+ variables: MUTATION_VARIABLES,
+ data: {
+ setEntityProperty: { id: 'prop-1', displayName: 'Optimistic' },
+ },
+ createdAtMs,
+ owner,
+ nowMs: createdAtMs,
+ leaseExpiresAtMs: createdAtMs + 1_000,
+});
+
+type SeededMutation = {
+ transactionId: string;
+ leaseOwner: string;
+ leaseGeneration: string;
+};
+
+function seededMutation(value: unknown, owner: string): SeededMutation {
+ assert(typeof value === 'object' && value !== null, 'missing enqueue result');
+ const result = value as {
+ transactionId?: unknown;
+ initialClaim?: {
+ kind?: unknown;
+ mutation?: { leaseGeneration?: unknown };
+ };
+ };
+ assert(typeof result.transactionId === 'string', 'missing transaction id');
+ assert(
+ result.initialClaim?.kind === 'claimed',
+ 'seed mutation was not claimed'
+ );
+ assert(
+ typeof result.initialClaim.mutation?.leaseGeneration === 'string',
+ 'missing lease generation'
+ );
+ return {
+ transactionId: result.transactionId,
+ leaseOwner: owner,
+ leaseGeneration: result.initialClaim.mutation.leaseGeneration,
+ };
+}
+
+const blockedRequest = (
+ kind: MutatingRequestKind,
+ seed: SeededMutation
+): ProductionCacheRequestWithoutId => {
+ switch (kind) {
+ case 'write':
+ return writeRequest('blocked-write');
+ case 'enqueue-optimistic-mutation':
+ return enqueueRequest('blocked-enqueue-owner', 20);
+ case 'claim-next-mutation':
+ return {
+ kind,
+ owner: 'blocked-claim-owner',
+ nowMs: 2_000,
+ leaseExpiresAtMs: 3_000,
+ };
+ case 'defer-optimistic-write':
+ return {
+ kind,
+ ...seed,
+ nextAttemptAtMs: 5_000,
+ error: 'browser-test-retry',
+ };
+ case 'commit-optimistic-write':
+ return {
+ kind,
+ ...seed,
+ query: MUTATION,
+ operationName: 'SetEntityProperty',
+ variables: MUTATION_VARIABLES,
+ data: {
+ setEntityProperty: { id: 'prop-1', displayName: 'Committed' },
+ },
+ };
+ case 'rollback-optimistic-write':
+ return { kind, ...seed, error: 'browser-test-permanent' };
+ case 'invalidate':
+ case 'delete-records':
+ return { kind, keys: ['GraphqlSoupDocument:seed-record'] };
+ case 'clear':
+ return { kind };
+ }
+};
+
+const isMiss = (value: unknown): boolean =>
+ typeof value === 'object' &&
+ value !== null &&
+ (value as { kind?: unknown }).kind === 'miss';
+
+const isHit = (value: unknown): boolean =>
+ typeof value === 'object' &&
+ value !== null &&
+ (value as { kind?: unknown }).kind === 'hit';
+
+const admissionBarrierRequest = (): ProductionCacheRequestWithoutId => ({
+ kind: 'read',
+ query: QUERY.replace('query Soup', 'query CacheAdmissionBarrier'),
+ operationName: 'CacheAdmissionBarrier',
+ variables: VARIABLES,
+});
+
+async function runFaultKind(kind: MutatingRequestKind) {
+ assert(
+ CACHE_MUTATING_REQUEST_KINDS.includes(kind),
+ `unsupported mutating request kind ${kind}`
+ );
+ const session = new ProductionSession(
+ `cache-recovery-fault-${kind}-${crypto.randomUUID()}`
+ );
+ try {
+ await session.openTab('fault-tab');
+ await session.command('fault-tab', {
+ kind: 'request',
+ request: writeRequest('seed-record'),
+ });
+ const owner = `seed-owner-${kind}`;
+ const seed = seededMutation(
+ await session.command('fault-tab', {
+ kind: 'request',
+ request: enqueueRequest(owner, 10),
+ }),
+ owner
+ );
+ await session.command('fault-tab', {
+ kind: 'arm-mutation-block',
+ requestKind: kind,
+ });
+ await waitUntil('mutation block arm proof', () =>
+ session.runtimeTelemetry.some(
+ (event) =>
+ event.kind === 'mutation-block-armed' && event.requestKind === kind
+ )
+ );
+ const armIndex = session.runtimeTelemetry.findIndex(
+ (event) =>
+ event.kind === 'mutation-block-armed' && event.requestKind === kind
+ );
+ const oldRequest = session
+ .command('fault-tab', {
+ kind: 'request',
+ request: blockedRequest(kind, seed),
+ })
+ .then(
+ () => ({ rejected: false, error: '' }),
+ (error: unknown) => ({
+ rejected: true,
+ error: error instanceof Error ? error.message : String(error),
+ })
+ );
+ await waitUntil('request admitted and blocked before core', () =>
+ session.runtimeTelemetry.some(
+ (event) =>
+ event.kind === 'request-blocked-before-core' &&
+ event.requestKind === kind
+ )
+ );
+ const blocked = session.runtimeTelemetry.find(
+ (event) =>
+ event.kind === 'request-blocked-before-core' &&
+ event.requestKind === kind
+ );
+ assert(blocked?.requestId !== undefined, 'missing blocked request id');
+ const readyBefore = session.runtimeTelemetry.filter(
+ (event) => event.kind === 'ready'
+ ).length;
+ const telemetryBeforeLoss = session.cacheTelemetry.length;
+ await session.command('fault-tab', { kind: 'terminate-worker' });
+ const old = await oldRequest;
+ assert(old.rejected, 'old admitted request did not reject');
+ await waitUntil(
+ 'replacement ready after actual worker termination',
+ () =>
+ session.runtimeTelemetry.filter((event) => event.kind === 'ready')
+ .length > readyBefore
+ );
+ const replacementReadyIndex = session.runtimeTelemetry.findLastIndex(
+ (event) => event.kind === 'ready'
+ );
+ assert(replacementReadyIndex > armIndex, 'missing replacement ready index');
+ await session.command('fault-tab', {
+ kind: 'request',
+ request: admissionBarrierRequest(),
+ });
+ await waitUntil('replacement request-admission barrier', () =>
+ session.runtimeTelemetry
+ .slice(replacementReadyIndex + 1)
+ .some((event) => event.admissionBarrier === true)
+ );
+ const barrierIndex = session.runtimeTelemetry.findIndex(
+ (event, index) =>
+ index > replacementReadyIndex && event.admissionBarrier === true
+ );
+ assert(barrierIndex > replacementReadyIndex, 'missing admission barrier');
+ const mutationAdmissions = session.runtimeTelemetry
+ .slice(armIndex, replacementReadyIndex + 1)
+ .filter(
+ (event) =>
+ event.kind === 'request-admitted' && event.requestKind === kind
+ );
+ assert(mutationAdmissions.length === 1, 'mutating request was replayed');
+ assert(
+ mutationAdmissions[0]?.requestId === blocked.requestId,
+ 'blocked admission proof did not identify the routed request'
+ );
+ const mutatingKinds = new Set<string>(CACHE_MUTATING_REQUEST_KINDS);
+ const unexpectedReplacementMutatingAdmissions = session.runtimeTelemetry
+ .slice(replacementReadyIndex + 1, barrierIndex + 1)
+ .filter(
+ (event) =>
+ event.kind === 'request-admitted' &&
+ mutatingKinds.has(String(event.requestKind))
+ );
+ assert(
+ unexpectedReplacementMutatingAdmissions.length === 0,
+ 'replacement admitted unexpected replayed mutation work'
+ );
+
+ const replacementRead = await session.command('fault-tab', {
+ kind: 'request',
+ request: {
+ kind: 'read',
+ query: QUERY,
+ operationName: 'Soup',
+ variables: VARIABLES,
+ },
+ });
+ const replacementClaim = await session.command('fault-tab', {
+ kind: 'request',
+ request: {
+ kind: 'claim-next-mutation',
+ owner: 'replacement-probe',
+ nowMs: 10_000,
+ leaseExpiresAtMs: 11_000,
+ },
+ });
+ assert(isMiss(replacementRead), 'replacement retained a durable record');
+ assert(
+ replacementClaim === undefined || replacementClaim === null,
+ 'replacement retained the durable queue'
+ );
+ const ready = session.runtimeTelemetry
+ .filter((event) => event.kind === 'ready')
+ .at(-1);
+ await waitUntil('authoritative reset phase sequence', () =>
+ session.cacheTelemetry
+ .slice(telemetryBeforeLoss)
+ .some((event) => event.name === 'graphql_cache.reset_wipe')
+ );
+ const resetTelemetry = session.cacheTelemetry.slice(telemetryBeforeLoss);
+ const resetPhaseSequence = resetTelemetry
+ .filter((event) =>
+ [
+ 'graphql_cache.storage_reset_required',
+ 'graphql_cache.logical_reset',
+ 'graphql_cache.reset_wipe',
+ ].includes(String(event.name))
+ )
+ .map((event) => event.name);
+ assert(
+ JSON.stringify(resetPhaseSequence) ===
+ JSON.stringify([
+ 'graphql_cache.storage_reset_required',
+ 'graphql_cache.logical_reset',
+ 'graphql_cache.reset_wipe',
+ ]),
+ `unexpected reset phase sequence ${JSON.stringify(resetPhaseSequence)}`
+ );
+ await session.gracefulClose('fault-tab');
+ return {
+ kind,
+ actualDedicatedWorkerTerminated: true,
+ requestAdmittedBeforeCore: true,
+ midSqlExecutionClaimed: false,
+ oldRequestRejected: old.rejected,
+ replacementRecordsEmpty: true,
+ replacementQueueEmpty: true,
+ mutationAdmissionCount: mutationAdmissions.length,
+ unexpectedReplacementMutatingAdmissionCount:
+ unexpectedReplacementMutatingAdmissions.length,
+ replacementAdmissionBarrierObserved: true,
+ resetPhaseSequence,
+ exactProductionTursoWasm: true,
+ performanceMemoryAvailable: ready?.performanceMemoryAvailable ?? false,
+ userAgentSpecificMemoryAvailable:
+ ready?.userAgentSpecificMemoryAvailable ?? false,
+ queueTelemetryObserved: session.cacheTelemetry.some(
+ (event) =>
+ event.name === 'graphql_cache.queue_diagnostics' &&
+ event.queueDepth === 0
+ ),
+ };
+ } finally {
+ session.close();
+ }
+}
+
+async function applyStorageMutation(
+ scope: string,
+ kind: RecoveryKind
+): Promise<string> {
+ const worker = new Worker(
+ new URL('./production-cache.storage-control-worker.ts', import.meta.url),
+ { type: 'module', name: `cache-recovery-storage-control:${kind}` }
+ );
+ try {
+ return await new Promise<string>((resolve, reject) => {
+ const timeout = setTimeout(
+ () => reject(new Error('storage-control worker timed out')),
+ 30_000
+ );
+ worker.onmessage = (
+ event: MessageEvent<{
+ id: number;
+ ok: boolean;
+ wasmUrl?: string;
+ error?: string;
+ }>
+ ) => {
+ if (event.data.id !== 1) return;
+ clearTimeout(timeout);
+ if (event.data.ok && event.data.wasmUrl) resolve(event.data.wasmUrl);
+ else reject(new Error(event.data.error ?? 'storage-control failed'));
+ };
+ worker.onerror = (event) => {
+ clearTimeout(timeout);
+ reject(new Error(event.message));
+ };
+ worker.postMessage({ id: 1, scope, kind });
+ });
+ } finally {
+ worker.terminate();
+ }
+}
+
+async function runRecoveryKind(kind: RecoveryKind) {
+ const scope = `cache-recovery-${kind}-${crypto.randomUUID()}`;
+ const session = new ProductionSession(scope);
+ try {
+ await session.openTab('before-corruption');
+ await session.command('before-corruption', {
+ kind: 'request',
+ request: writeRequest('must-reset'),
+ });
+ await session.command('before-corruption', {
+ kind: 'request',
+ request: enqueueRequest('recovery-seed-owner', 10),
+ });
+ await session.gracefulClose('before-corruption');
+ const browserTestWasmUrl = await applyStorageMutation(scope, kind);
+ const telemetryBeforeReopen = session.cacheTelemetry.length;
+ await session.openTab('after-corruption');
+ await waitUntil('recovery outcome and authoritative wipe telemetry', () => {
+ const events = session.cacheTelemetry.slice(telemetryBeforeReopen);
+ return (
+ events.some((event) =>
+ String(event.openOutcome).startsWith('reset-')
+ ) && events.some((event) => event.name === 'graphql_cache.reset_wipe')
+ );
+ });
+ const replacementTelemetry = session.cacheTelemetry.slice(
+ telemetryBeforeReopen
+ );
+ const expectedOutcome =
+ kind === 'incompatible-namespace'
+ ? 'reset-incompatible'
+ : 'reset-corrupt';
+ const replacementRead = await session.command('after-corruption', {
+ kind: 'request',
+ request: {
+ kind: 'read',
+ query: QUERY,
+ operationName: 'Soup',
+ variables: VARIABLES,
+ },
+ });
+ const replacementClaim = await session.command('after-corruption', {
+ kind: 'request',
+ request: {
+ kind: 'claim-next-mutation',
+ owner: 'recovery-probe',
+ nowMs: 10_000,
+ leaseExpiresAtMs: 11_000,
+ },
+ });
+ assert(isMiss(replacementRead), 'recovery retained a durable record');
+ assert(
+ replacementClaim === undefined || replacementClaim === null,
+ 'recovery retained the durable queue'
+ );
+ await session.command('after-corruption', {
+ kind: 'request',
+ request: writeRequest('usable-after-reset'),
+ });
+ const usableRead = await session.command('after-corruption', {
+ kind: 'request',
+ request: {
+ kind: 'read',
+ query: QUERY,
+ operationName: 'Soup',
+ variables: VARIABLES,
+ },
+ });
+ assert(isHit(usableRead), 'recovered cache was not usable');
+ const phaseCount = (name: string): number =>
+ replacementTelemetry.filter((event) => event.name === name).length;
+ assert(
+ replacementTelemetry.some(
+ (event) => event.openOutcome === expectedOutcome
+ ),
+ `missing ${expectedOutcome} telemetry`
+ );
+ for (const phase of [
+ 'graphql_cache.storage_reset_required',
+ 'graphql_cache.logical_reset',
+ 'graphql_cache.reset_wipe',
+ ]) {
+ assert(phaseCount(phase) === 1, `${phase} was not emitted exactly once`);
+ }
+ await session.gracefulClose('after-corruption');
+ return {
+ kind,
+ gracefulCloseBeforeMutation: true,
+ separateFeatureGatedBrowserTestArtifact: true,
+ productionArtifactDebugExportsAbsent: true,
+ browserTestWasmUrl,
+ browserTestWorkerOnlyControl: true,
+ productionCoordinatorProtocolUnchanged: true,
+ openOutcome: expectedOutcome,
+ recordsWiped: true,
+ durableQueueWiped: true,
+ usableAfterReset: true,
+ storageResetRequiredCount: phaseCount(
+ 'graphql_cache.storage_reset_required'
+ ),
+ logicalResetCount: phaseCount('graphql_cache.logical_reset'),
+ resetWipeCount: phaseCount('graphql_cache.reset_wipe'),
+ queueTelemetryObserved: replacementTelemetry.some(
+ (event) =>
+ event.name === 'graphql_cache.queue_diagnostics' &&
+ event.queueDepth === 0
+ ),
+ };
+ } finally {
+ session.close();
+ }
+}
+
+const api = {
+ mutatingRequestKinds: CACHE_MUTATING_REQUEST_KINDS,
+ runFaultKind,
+ runRecoveryKind,
+};
+
+declare global {
+ interface Window {
+ cacheRecoveryHarness: typeof api;
+ }
+}
+
+window.cacheRecoveryHarness = api;
+resultElement.dataset.status = 'ready';
+resultElement.textContent = JSON.stringify({
+ productionInertHooks: true,
+ publicCoordinatorProtocolUnchanged: true,
+ mutatingRequestKinds: CACHE_MUTATING_REQUEST_KINDS,
+});
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/cache-recovery.html b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-recovery.html
new file mode 100644
index 0000000000..e4d2d7abdf
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-recovery.html
@@ -0,0 +1,8 @@
+<!doctype html>
+<html lang="en">
+ <head><meta charset="UTF-8" /><title>Cache internal browser harness</title></head>
+ <body>
+ <pre id="result" data-status="loading"></pre>
+ <script type="module" src="./cache-recovery-harness.ts"></script>
+ </body>
+</html>
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/cache-wasm-packaging.browser.e2e.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-wasm-packaging.browser.e2e.ts
new file mode 100644
index 0000000000..60118316e5
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-wasm-packaging.browser.e2e.ts
@@ -0,0 +1,262 @@
+import { expect, type Page, test } from '@playwright/test';
+import { CACHE_WASM_BUDGETS } from '../../../../../scripts/cache-wasm/budgets';
+import type { CacheWasmPerformanceSample } from './performance-harness';
+
+type CacheWasmBrowserSample = CacheWasmPerformanceSample & {
+ browser: 'chromium' | 'firefox';
+ wasmUrl: string;
+};
+
+const percentile95 = (values: number[]): number =>
+ [...values].sort((left, right) => left - right)[
+ Math.ceil(values.length * 0.95) - 1
+ ]!;
+
+const SAMPLE_COUNT = 5;
+const isProductionProject = (projectName: string): boolean =>
+ projectName.includes('production');
+const harnessPath = (projectName: string, page: string): string =>
+ isProductionProject(projectName) ? `/app/${page}` : `/${page}`;
+
+async function fetchedWasmEvidence(
+ page: Page,
+ wasmUrl: string
+): Promise<{
+ contentType: string | null;
+ contentEncoding: string | null;
+ validModule: boolean;
+ sha256: string;
+}> {
+ return await page.evaluate(async (url) => {
+ const response = await fetch(url);
+ const bytes = await response.arrayBuffer();
+ const [module, digest] = await Promise.all([
+ WebAssembly.compile(bytes),
+ crypto.subtle.digest('SHA-256', bytes),
+ ]);
+ return {
+ contentType: response.headers.get('content-type'),
+ contentEncoding: response.headers.get('content-encoding'),
+ validModule: module instanceof WebAssembly.Module,
+ sha256: [...new Uint8Array(digest)]
+ .map((byte) => byte.toString(16).padStart(2, '0'))
+ .join(''),
+ };
+ }, wasmUrl);
+}
+
+test('exact production CacheHost reaches the exact engine URL without a wrapper', async ({
+ context,
+ page,
+}, testInfo) => {
+ const requests: string[] = [];
+ const wasmResponses: string[] = [];
+ context.on('request', (request) => requests.push(request.url()));
+ context.on('response', (response) => {
+ if (new URL(response.url()).pathname.endsWith('.wasm')) {
+ wasmResponses.push(response.url());
+ }
+ });
+
+ await page.goto(
+ harnessPath(testInfo.project.name, 'exact-production-host.html')
+ );
+ const result = page.locator('#result');
+ await expect(result).toHaveAttribute('data-status', 'passed', {
+ timeout: 30_000,
+ });
+ const report = JSON.parse((await result.textContent()) ?? '') as {
+ sharedWorkerConstructions: number;
+ dedicatedWorkerConstructions: number;
+ engineWorkerUrl: string;
+ crossOriginIsolated: boolean;
+ sharedArrayBufferAvailable: boolean;
+ };
+ expect(report).toMatchObject({
+ sharedWorkerConstructions: 1,
+ dedicatedWorkerConstructions: 1,
+ crossOriginIsolated: false,
+ sharedArrayBufferAvailable: false,
+ });
+ expect(report.engineWorkerUrl).toContain('cache.engine-worker');
+ expect(report.engineWorkerUrl).not.toContain('instrumented-cache');
+ expect(
+ requests.filter((url) => url.includes('instrumented-cache.engine-worker'))
+ ).toEqual([]);
+ expect(
+ requests.filter((url) => url.includes('cache.engine-worker'))
+ ).toHaveLength(1);
+ expect(wasmResponses).toHaveLength(1);
+ const served = await fetchedWasmEvidence(page, wasmResponses[0]);
+ expect(served).toEqual({
+ contentType: expect.stringContaining('application/wasm'),
+ contentEncoding: isProductionProject(testInfo.project.name) ? 'br' : null,
+ validModule: true,
+ sha256: expect.stringMatching(/^[a-f0-9]{64}$/),
+ });
+});
+
+test('combined cache WASM stays lazy and meets fresh-scope startup budgets', async ({
+ context,
+ page,
+}, testInfo) => {
+ const requests: string[] = [];
+ const wasmResponses: string[] = [];
+ const browserName = testInfo.project.name.includes('firefox')
+ ? 'firefox'
+ : 'chromium';
+ context.on('request', (request) => requests.push(request.url()));
+ context.on('response', (response) => {
+ if (new URL(response.url()).pathname.endsWith('.wasm')) {
+ wasmResponses.push(response.url());
+ }
+ });
+
+ await page.goto(harnessPath(testInfo.project.name, 'performance.html'));
+ await expect(page.locator('#result')).toHaveAttribute('data-status', 'idle');
+ await page.waitForTimeout(250);
+ expect(
+ requests.filter((url) => {
+ const parsed = new URL(url);
+ if (parsed.pathname.includes('cache_wasm')) return true;
+ const enginePath =
+ /(?:cache[.-]engine-worker|instrumented-cache\.engine-worker)/.test(
+ parsed.pathname
+ );
+ // Vite dev loads a tiny `?worker&url` URL-export module eagerly; it does
+ // not fetch or execute the worker script (`?worker_file`) or WASM.
+ return (
+ enginePath &&
+ (!parsed.searchParams.has('worker') ||
+ parsed.searchParams.has('worker_file'))
+ );
+ })
+ ).toEqual([]);
+
+ const samples: CacheWasmBrowserSample[] = [];
+ for (let index = 0; index < SAMPLE_COUNT; index++) {
+ const responseCountBefore = wasmResponses.length;
+ let measurement: CacheWasmPerformanceSample;
+ try {
+ measurement = await page.evaluate(async () => {
+ const run = (
+ window as typeof window & {
+ runCacheWasmPerformanceSample(): Promise<CacheWasmPerformanceSample>;
+ }
+ ).runCacheWasmPerformanceSample;
+ return await run();
+ });
+ } catch (error) {
+ throw new Error(
+ `${error instanceof Error ? error.message : String(error)}\nrequests:\n${requests.join('\n')}`
+ );
+ }
+ const sampleWasmResponses = wasmResponses.slice(responseCountBefore);
+ expect(sampleWasmResponses).toHaveLength(1);
+ expect(measurement.wasmFetchCount).toBe(sampleWasmResponses.length);
+ expect(measurement.wasmSha256).toMatch(/^[a-f0-9]{64}$/);
+ samples.push({
+ ...measurement,
+ browser: browserName,
+ wasmUrl: sampleWasmResponses[0],
+ });
+ }
+
+ const mode = samples[0].mode;
+ const production = mode === 'production';
+ expect(production).toBe(isProductionProject(testInfo.project.name));
+ expect(samples).toHaveLength(SAMPLE_COUNT);
+ for (const sample of samples) {
+ expect(sample).toMatchObject({
+ mode,
+ sharedWorkerConstructions: 1,
+ dedicatedWorkerConstructions: 1,
+ nestedWorkerConstructions: 0,
+ ownerEpochs: [1],
+ crossOriginIsolated: false,
+ sharedArrayBufferAvailable: false,
+ });
+ expect(sample.linearMemoryBytes).toBeLessThanOrEqual(
+ CACHE_WASM_BUDGETS.linearMemoryBytes
+ );
+ expect(sample.productionEngineUrl).not.toBe(sample.instrumentedEngineUrl);
+ }
+
+ const sharedWorkerUrls = [
+ ...new Set(samples.map((sample) => sample.sharedWorkerUrl)),
+ ];
+ const productionEngineUrls = [
+ ...new Set(samples.map((sample) => sample.productionEngineUrl)),
+ ];
+ const instrumentedEngineUrls = [
+ ...new Set(samples.map((sample) => sample.instrumentedEngineUrl)),
+ ];
+ const wasmUrls = [...new Set(samples.map((sample) => sample.wasmUrl))];
+ expect(sharedWorkerUrls).toHaveLength(1);
+ expect(productionEngineUrls).toHaveLength(1);
+ expect(instrumentedEngineUrls).toHaveLength(1);
+ expect(wasmUrls).toHaveLength(1);
+ if (mode === 'development') {
+ expect(sharedWorkerUrls[0]).toContain(
+ '/src/lib/graphql-cache/worker/cache.coordinator.shared-worker.ts'
+ );
+ expect(productionEngineUrls[0]).toContain(
+ '/src/lib/graphql-cache/worker/cache.engine-worker.ts'
+ );
+ expect(instrumentedEngineUrls[0]).toContain(
+ '/instrumented-cache.engine-worker.ts'
+ );
+ } else {
+ expect(sharedWorkerUrls[0]).toMatch(
+ /\/app\/assets\/cache\.coordinator\.shared-worker-[\w-]+\.js$/
+ );
+ expect(productionEngineUrls[0]).toMatch(
+ /\/app\/assets\/cache\.engine-worker-[\w-]+\.js$/
+ );
+ expect(instrumentedEngineUrls[0]).toMatch(
+ /\/app\/assets\/instrumented-cache\.engine-worker-[\w-]+\.js$/
+ );
+ expect(wasmUrls[0]).toMatch(/\/app\/assets\/cache_wasm_bg-[\w-]+\.wasm$/);
+ }
+
+ const browserReadyP95Ms = percentile95(
+ samples.map((sample) => sample.browserReadyMs)
+ );
+ const hostFirstReadyP95Ms = percentile95(
+ samples.map((sample) => sample.hostFirstReadyMs)
+ );
+ expect(browserReadyP95Ms).toBeLessThanOrEqual(
+ CACHE_WASM_BUDGETS.browserReadyP95Ms
+ );
+ expect(hostFirstReadyP95Ms).toBeLessThanOrEqual(
+ CACHE_WASM_BUDGETS.hostFirstReadyP95Ms
+ );
+ // The instrumented engine clones and hashes each actual decoded runtime
+ // response, so artifact binding adds no second WASM request.
+ expect(wasmResponses).toHaveLength(SAMPLE_COUNT);
+ const wasmHashes = [...new Set(samples.map((sample) => sample.wasmSha256))];
+ expect(wasmHashes).toHaveLength(1);
+
+ if (production) {
+ for (const workerUrl of [
+ sharedWorkerUrls[0],
+ productionEngineUrls[0],
+ instrumentedEngineUrls[0],
+ ]) {
+ const evidence = await page.evaluate(async (mapUrl) => {
+ const response = await fetch(mapUrl);
+ const value = (await response.json()) as { sources?: unknown };
+ return {
+ ok: response.ok,
+ contentType: response.headers.get('content-type'),
+ hasSources: Array.isArray(value.sources) && value.sources.length > 0,
+ };
+ }, `${workerUrl}.map`);
+ expect(evidence).toEqual({
+ ok: true,
+ contentType: expect.stringContaining('application/json'),
+ hasSources: true,
+ });
+ }
+ }
+});
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/coordinator.browser.e2e.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/coordinator.browser.e2e.ts
new file mode 100644
index 0000000000..b1aa8898e8
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/coordinator.browser.e2e.ts
@@ -0,0 +1,216 @@
+import { expect, test } from '@playwright/test';
+
+const harnessPath = (projectName: string, path = ''): string =>
+ projectName.includes('production') ? `/app/${path}` : `/${path}`;
+
+test('three pages fence graceful, abrupt, stale, and worker-only ownership', async ({
+ context,
+ page,
+}, testInfo) => {
+ const browserErrors: string[] = [];
+ const watch = (candidate: typeof page): void => {
+ candidate.on('console', (message) => {
+ if (message.type() === 'error') browserErrors.push(message.text());
+ });
+ candidate.on('pageerror', (error) => browserErrors.push(error.message));
+ };
+ watch(page);
+ context.on('page', watch);
+
+ await page.goto(harnessPath(testInfo.project.name));
+ const result = page.locator('#result');
+ await expect(result).toHaveAttribute('data-status', 'passed', {
+ timeout: 40_000,
+ });
+ const report = JSON.parse((await result.textContent()) ?? '') as {
+ passed: boolean;
+ openedTabs: number;
+ ownerEpochs: number[];
+ maxWorkersPerEpoch: number;
+ noEagerWorker: boolean;
+ collidingRequestIdsRewritten: boolean;
+ gracefulPreserved: boolean;
+ abruptRejectedInflight: boolean;
+ abruptWiped: boolean;
+ workerOnlyPageStayedAlive: boolean;
+ workerOnlyWiped: boolean;
+ livenessPageStayedAlive: boolean;
+ livenessTerminationReason: string;
+ livenessWiped: boolean;
+ staleMessageDrops: number;
+ staleMessagePortResponseDropped: boolean;
+ pushReachedAllTabs: boolean;
+ ownerLockContentionEpochs: number[];
+ engineReplacedEpochs: number[];
+ protocolErrors: string[];
+ };
+
+ expect(report).toMatchObject({
+ passed: true,
+ openedTabs: 3,
+ ownerEpochs: [1, 2, 3, 4],
+ maxWorkersPerEpoch: 1,
+ noEagerWorker: true,
+ collidingRequestIdsRewritten: true,
+ gracefulPreserved: true,
+ abruptRejectedInflight: true,
+ abruptWiped: true,
+ workerOnlyPageStayedAlive: true,
+ workerOnlyWiped: true,
+ livenessPageStayedAlive: true,
+ livenessTerminationReason: 'tab liveness lock was released',
+ livenessWiped: true,
+ staleMessageDrops: 1,
+ staleMessagePortResponseDropped: true,
+ pushReachedAllTabs: true,
+ ownerLockContentionEpochs: [1, 2, 3, 4],
+ engineReplacedEpochs: [2, 3, 4],
+ protocolErrors: [],
+ });
+ expect(browserErrors).toEqual([]);
+});
+
+test('production CacheHost performs fresh init and active reread after owner loss', async ({
+ context,
+ page,
+}, testInfo) => {
+ const browserErrors: string[] = [];
+ const watch = (candidate: typeof page): void => {
+ candidate.on('console', (message) => {
+ if (message.type() === 'error') browserErrors.push(message.text());
+ });
+ candidate.on('pageerror', (error) => browserErrors.push(error.message));
+ };
+ watch(page);
+ context.on('page', watch);
+
+ await page.goto(harnessPath(testInfo.project.name, 'host.html'));
+ const result = page.locator('#result');
+ await expect(result).toHaveAttribute('data-status', 'passed', {
+ timeout: 60_000,
+ });
+ const report = JSON.parse((await result.textContent()) ?? '') as {
+ passed: boolean;
+ noEagerConstructor: boolean;
+ requestOrder: Array<[number, number, string]>;
+ oldEpochRejectedBeforeReplacement: boolean;
+ oldRequestReplayCount: number;
+ replacementActiveKeys: number[][];
+ replacementReadCompleted: boolean;
+ gracefulDrained: boolean;
+ terminatedEpochs: number[];
+ sharedPortClosed: boolean;
+ initializationErrors: string[];
+ };
+
+ expect(report).toEqual({
+ passed: true,
+ noEagerConstructor: true,
+ requestOrder: [
+ [1, 1, 'init'],
+ [1, 2, 'read'],
+ [1, 3, 'read'],
+ [1, 4, 'read'],
+ [2, 5, 'init'],
+ [2, 6, 'read'],
+ ],
+ oldEpochRejectedBeforeReplacement: true,
+ oldRequestReplayCount: 1,
+ replacementActiveKeys: [[7, 9]],
+ replacementReadCompleted: true,
+ gracefulDrained: true,
+ terminatedEpochs: [1, 2],
+ sharedPortClosed: true,
+ initializationErrors: [],
+ });
+ expect(browserErrors).toEqual([]);
+});
+
+test('direct cutover lazily deletes only the former normalized-cache IDB', async ({
+ page,
+}, testInfo) => {
+ const browserErrors: string[] = [];
+ page.on('console', (message) => {
+ if (message.type() === 'error') browserErrors.push(message.text());
+ });
+ page.on('pageerror', (error) => browserErrors.push(error.message));
+
+ await page.goto(harnessPath(testInfo.project.name, 'cutover.html'));
+ const result = page.locator('#result');
+ await expect(result).toHaveAttribute('data-status', 'passed', {
+ timeout: 60_000,
+ });
+ const report = JSON.parse((await result.textContent()) ?? '') as {
+ passed: boolean;
+ noEagerDeletion: boolean;
+ deletionRequestedOnFirstUse: boolean;
+ blockedDeletionDidNotBlockHost: boolean;
+ legacyDeletionCompletedLater: boolean;
+ unrelatedIdbPreserved: boolean;
+ };
+
+ expect(report).toEqual({
+ passed: true,
+ noEagerDeletion: true,
+ deletionRequestedOnFirstUse: true,
+ blockedDeletionDidNotBlockHost: true,
+ legacyDeletionCompletedLater: true,
+ unrelatedIdbPreserved: true,
+ });
+ expect(browserErrors).toEqual([]);
+});
+
+test('production cache-wasm Turso engine preserves graceful data and atomically recovers abrupt loss', async ({
+ context,
+ page,
+}, testInfo) => {
+ const browserErrors: string[] = [];
+ const watch = (candidate: typeof page): void => {
+ candidate.on('console', (message) => {
+ if (message.type() === 'error') browserErrors.push(message.text());
+ });
+ candidate.on('pageerror', (error) => browserErrors.push(error.message));
+ };
+ watch(page);
+ context.on('page', watch);
+
+ await page.goto(harnessPath(testInfo.project.name, 'production.html'));
+ const result = page.locator('#result');
+ await expect(result).toHaveAttribute('data-status', 'passed', {
+ timeout: 60_000,
+ });
+ const report = JSON.parse((await result.textContent()) ?? '') as {
+ passed: boolean;
+ realTursoDataPreservedGracefully: boolean;
+ gracefulCloseReleasedOwnerLock: boolean;
+ gracefulReplacementWaitedForPhysicalLock: boolean;
+ gracefulPendingOwnerLockRequests: number;
+ abruptInflightRejected: boolean;
+ abruptRequestReplayCount: number;
+ abruptOwnerPageStayedAlive: boolean;
+ recoveryReplacementWaitedForPhysicalLock: boolean;
+ recoveryPendingOwnerLockRequests: number;
+ atomicRecoveryOpenWipedToMiss: boolean;
+ recoveryDatabaseAction: string;
+ ownerEpochs: number[];
+ protocolErrors: string[];
+ };
+
+ expect(report).toEqual({
+ passed: true,
+ realTursoDataPreservedGracefully: true,
+ gracefulCloseReleasedOwnerLock: true,
+ gracefulReplacementWaitedForPhysicalLock: true,
+ gracefulPendingOwnerLockRequests: 1,
+ abruptInflightRejected: true,
+ abruptRequestReplayCount: 1,
+ abruptOwnerPageStayedAlive: true,
+ recoveryReplacementWaitedForPhysicalLock: true,
+ recoveryPendingOwnerLockRequests: 1,
+ atomicRecoveryOpenWipedToMiss: true,
+ recoveryDatabaseAction: 'wipe-before-open',
+ ownerEpochs: [1, 2, 3],
+ protocolErrors: [],
+ });
+ expect(browserErrors).toEqual([]);
+});
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/cutover-harness.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/cutover-harness.ts
new file mode 100644
index 0000000000..909f444f27
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/cutover-harness.ts
@@ -0,0 +1,129 @@
+import { createWorkerCacheHost } from '../../host/worker-host';
+
+const resultNode = document.querySelector('#result');
+if (!(resultNode instanceof HTMLElement))
+ throw new Error('missing result node');
+
+const scope = `wp10-cutover-${crypto.randomUUID()}`;
+const legacyName = `graphql-cache:${scope}`;
+const unrelatedName = `unrelated-idb:${scope}`;
+const STORE = 'records';
+const MARKER_KEY = 'keep';
+const MARKER_VALUE = 'unrelated-data';
+
+const openDatabase = (
+ name: string,
+ initialize?: (database: IDBDatabase) => void
+): Promise<IDBDatabase> =>
+ new Promise((resolve, reject) => {
+ const request = indexedDB.open(name, 1);
+ request.onupgradeneeded = () => initialize?.(request.result);
+ request.onsuccess = () => resolve(request.result);
+ request.onerror = () =>
+ reject(request.error ?? new Error('IDB open failed'));
+ });
+
+const writeMarker = (database: IDBDatabase): Promise<void> =>
+ new Promise((resolve, reject) => {
+ const transaction = database.transaction(STORE, 'readwrite');
+ transaction.objectStore(STORE).put(MARKER_VALUE, MARKER_KEY);
+ transaction.oncomplete = () => resolve();
+ transaction.onerror = () =>
+ reject(transaction.error ?? new Error('IDB marker write failed'));
+ transaction.onabort = transaction.onerror;
+ });
+
+const readMarker = (database: IDBDatabase): Promise<unknown> =>
+ new Promise((resolve, reject) => {
+ const request = database
+ .transaction(STORE, 'readonly')
+ .objectStore(STORE)
+ .get(MARKER_KEY);
+ request.onsuccess = () => resolve(request.result);
+ request.onerror = () =>
+ reject(request.error ?? new Error('IDB marker read failed'));
+ });
+
+const databaseExists = async (name: string): Promise<boolean> =>
+ (await indexedDB.databases()).some((database) => database.name === name);
+
+const waitUntil = async (
+ label: string,
+ predicate: () => boolean | Promise<boolean>,
+ timeoutMs = 20_000
+): Promise<void> => {
+ const deadline = performance.now() + timeoutMs;
+ while (!(await predicate())) {
+ if (performance.now() >= deadline) throw new Error(`${label} timed out`);
+ await new Promise((resolve) => setTimeout(resolve, 10));
+ }
+};
+
+const deleteDatabase = (name: string): Promise<void> =>
+ new Promise((resolve) => {
+ const request = indexedDB.deleteDatabase(name);
+ request.onsuccess = () => resolve();
+ request.onerror = () => resolve();
+ request.onblocked = () => resolve();
+ });
+
+const report: Record<string, unknown> = {
+ passed: false,
+ noEagerDeletion: false,
+ deletionRequestedOnFirstUse: false,
+ blockedDeletionDidNotBlockHost: false,
+ legacyDeletionCompletedLater: false,
+ unrelatedIdbPreserved: false,
+};
+
+let legacy: IDBDatabase | undefined;
+let unrelated: IDBDatabase | undefined;
+try {
+ legacy = await openDatabase(legacyName, (database) => {
+ database.createObjectStore(STORE);
+ });
+ unrelated = await openDatabase(unrelatedName, (database) => {
+ database.createObjectStore(STORE);
+ });
+ await writeMarker(unrelated);
+
+ let legacyVersionChange = false;
+ legacy.onversionchange = () => {
+ legacyVersionChange = true;
+ // Deliberately remain open so the cutover request reaches `blocked`.
+ };
+
+ const host = createWorkerCacheHost({ scope, requestTimeoutMs: 20_000 });
+ await new Promise((resolve) => setTimeout(resolve, 0));
+ report.noEagerDeletion = !legacyVersionChange;
+
+ await host.clear();
+ report.deletionRequestedOnFirstUse = legacyVersionChange;
+ report.blockedDeletionDidNotBlockHost = await databaseExists(legacyName);
+
+ legacy.close();
+ legacy = undefined;
+ await waitUntil(
+ 'legacy normalized cache deletion',
+ async () => !(await databaseExists(legacyName))
+ );
+ report.legacyDeletionCompletedLater = true;
+ report.unrelatedIdbPreserved =
+ (await databaseExists(unrelatedName)) &&
+ (await readMarker(unrelated)) === MARKER_VALUE;
+
+ host.dispose();
+ report.passed = Object.entries(report)
+ .filter(([key]) => key !== 'passed')
+ .every(([, value]) => value === true);
+} catch (error) {
+ report.error = error instanceof Error ? error.message : String(error);
+} finally {
+ legacy?.close();
+ unrelated?.close();
+ await deleteDatabase(legacyName);
+ await deleteDatabase(unrelatedName);
+}
+
+resultNode.dataset.status = report.passed ? 'passed' : 'failed';
+resultNode.textContent = JSON.stringify(report);
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/cutover.html b/apps/web/src/lib/graphql-cache/worker/browser-test/cutover.html
new file mode 100644
index 0000000000..da5270ab02
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/cutover.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <link rel="icon" href="data:," />
+ <title>WP-10 normalized cache IDB cutover harness</title>
+ </head>
+ <body>
+ <pre id="result" data-status="running">running</pre>
+ <script type="module" src="./cutover-harness.ts"></script>
+ </body>
+</html>
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/exact-production-host-harness.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/exact-production-host-harness.ts
new file mode 100644
index 0000000000..012f1a7ff3
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/exact-production-host-harness.ts
@@ -0,0 +1,67 @@
+import { createWorkerCacheHost } from '../../host/worker-host';
+
+const resultElement = document.querySelector<HTMLElement>('#result');
+if (!resultElement) throw new Error('missing result element');
+
+const NativeWorker = globalThis.Worker;
+const NativeSharedWorker = globalThis.SharedWorker;
+let sharedWorkerConstructions = 0;
+let dedicatedWorkerConstructions = 0;
+let engineWorkerUrl = '';
+globalThis.SharedWorker = new Proxy(NativeSharedWorker, {
+ construct(target, argumentsList) {
+ sharedWorkerConstructions++;
+ return Reflect.construct(target, argumentsList);
+ },
+});
+globalThis.Worker = new Proxy(NativeWorker, {
+ construct(target, argumentsList) {
+ const [url, options] = argumentsList as ConstructorParameters<
+ typeof Worker
+ >;
+ if (options?.name?.startsWith('graphql-cache-engine:')) {
+ dedicatedWorkerConstructions++;
+ engineWorkerUrl = String(url);
+ }
+ return Reflect.construct(target, argumentsList);
+ },
+});
+
+const scope = `cache-exact-production-${crypto.randomUUID()}`;
+const host = createWorkerCacheHost({
+ scope,
+ requestTimeoutMs: 15_000,
+ initializationTimeoutMs: 15_000,
+});
+
+try {
+ await host.readQuery({
+ opKey: 1,
+ query: `query CacheExactProduction($input: SoupInput!) {
+ user {
+ id
+ soup(input: $input) {
+ nextCursor
+ items { __typename id }
+ }
+ }
+ }`,
+ operationName: 'CacheExactProduction',
+ variables: { input: { limit: 1 } },
+ });
+ resultElement.textContent = JSON.stringify({
+ sharedWorkerConstructions,
+ dedicatedWorkerConstructions,
+ engineWorkerUrl,
+ crossOriginIsolated: globalThis.crossOriginIsolated,
+ sharedArrayBufferAvailable:
+ typeof globalThis.SharedArrayBuffer === 'function',
+ });
+ resultElement.dataset.status = 'passed';
+} catch (error) {
+ resultElement.textContent =
+ error instanceof Error ? (error.stack ?? error.message) : String(error);
+ resultElement.dataset.status = 'failed';
+} finally {
+ host.dispose();
+}
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/exact-production-host.html b/apps/web/src/lib/graphql-cache/worker/browser-test/exact-production-host.html
new file mode 100644
index 0000000000..92d6d1137e
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/exact-production-host.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Exact production cache host smoke</title>
+ </head>
+ <body>
+ <pre id="result" data-status="running"></pre>
+ <script type="module" src="./exact-production-host-harness.ts"></script>
+ </body>
+</html>
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/fake-cache.engine-worker.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/fake-cache.engine-worker.ts
new file mode 100644
index 0000000000..be7852b2b4
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/fake-cache.engine-worker.ts
@@ -0,0 +1,323 @@
+/// <reference lib="webworker" />
+
+import type { CacheRequest, CacheResponse } from '../../protocol';
+import {
+ CACHE_COORDINATOR_PROTOCOL_VERSION,
+ type CoordinatorToEngineEnvelope,
+ type EngineToCoordinatorEnvelope,
+ type PageToEngineEnvelope,
+ validateCoordinatorToEngineEnvelope,
+ validatePageToEngineEnvelope,
+} from '../coordinator-protocol';
+
+declare const self: DedicatedWorkerGlobalScope;
+
+const withVersion = <T extends { coordinatorVersion: 1 }>(
+ value: T extends unknown ? Omit<T, 'coordinatorVersion'> : never
+): T =>
+ ({
+ coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION,
+ ...value,
+ }) as unknown as T;
+
+const databaseName = (scope: string): string =>
+ `graphql-cache-wp08-browser:${scope}`;
+
+const openDatabase = async (scope: string): Promise<IDBDatabase> =>
+ await new Promise((resolve, reject) => {
+ const request = indexedDB.open(databaseName(scope), 1);
+ request.onupgradeneeded = () => {
+ if (!request.result.objectStoreNames.contains('records')) {
+ request.result.createObjectStore('records');
+ }
+ };
+ request.onsuccess = () => resolve(request.result);
+ request.onerror = () => reject(request.error ?? new Error('open failed'));
+ });
+
+const deleteDatabase = async (scope: string): Promise<void> =>
+ await new Promise((resolve, reject) => {
+ const request = indexedDB.deleteDatabase(databaseName(scope));
+ request.onsuccess = () => resolve();
+ request.onerror = () => reject(request.error ?? new Error('delete failed'));
+ request.onblocked = () => reject(new Error('delete blocked'));
+ });
+
+const put = async (database: IDBDatabase, value: unknown): Promise<void> =>
+ await new Promise((resolve, reject) => {
+ const transaction = database.transaction('records', 'readwrite');
+ transaction.objectStore('records').put(value, 'root');
+ transaction.oncomplete = () => resolve();
+ transaction.onerror = () =>
+ reject(transaction.error ?? new Error('put failed'));
+ });
+
+const get = async (database: IDBDatabase): Promise<unknown | undefined> =>
+ await new Promise((resolve, reject) => {
+ const transaction = database.transaction('records', 'readonly');
+ const request = transaction.objectStore('records').get('root');
+ request.onsuccess = () => resolve(request.result);
+ request.onerror = () => reject(request.error ?? new Error('get failed'));
+ });
+
+const clear = async (database: IDBDatabase): Promise<void> =>
+ await new Promise((resolve, reject) => {
+ const transaction = database.transaction('records', 'readwrite');
+ transaction.objectStore('records').clear();
+ transaction.oncomplete = () => resolve();
+ transaction.onerror = () =>
+ reject(transaction.error ?? new Error('clear failed'));
+ });
+
+const delay = async (milliseconds: number): Promise<void> =>
+ await new Promise((resolve) => setTimeout(resolve, milliseconds));
+
+let controlPort: MessagePort | undefined;
+let activationValue: PageToEngineEnvelope | undefined;
+let telemetry: BroadcastChannel | undefined;
+let ignoreHeartbeats = false;
+
+const sendStaleResponse = (ownerEpoch: number, routeId: number): void => {
+ controlPort?.postMessage(
+ withVersion<EngineToCoordinatorEnvelope>({
+ kind: 'engine-response',
+ ownerEpoch,
+ routeId,
+ response: { id: routeId, ok: true, result: 'stale-must-not-escape' },
+ })
+ );
+};
+
+const execute = async (
+ database: IDBDatabase,
+ request: CacheRequest
+): Promise<CacheResponse> => {
+ if (request.kind === 'read' && request.query.includes('Slow')) {
+ await delay(10_000);
+ }
+ switch (request.kind) {
+ case 'init':
+ return { id: request.id, ok: true, result: null };
+ case 'write':
+ await put(database, request.data);
+ return {
+ id: request.id,
+ ok: true,
+ result: { changed: ['ROOT_QUERY'], affectedOps: [], reset: false },
+ };
+ case 'read': {
+ const value = await get(database);
+ return {
+ id: request.id,
+ ok: true,
+ result:
+ value === undefined ? { kind: 'miss' } : { kind: 'hit', data: value },
+ };
+ }
+ case 'clear':
+ await clear(database);
+ return { id: request.id, ok: true, result: null };
+ default:
+ return {
+ id: request.id,
+ ok: false,
+ error: `fake engine does not implement ${request.kind}`,
+ };
+ }
+};
+
+async function activate(
+ activation: PageToEngineEnvelope,
+ port: MessagePort
+): Promise<void> {
+ activationValue = activation;
+ controlPort = port;
+ telemetry = new BroadcastChannel(`graphql-cache-wp08:${activation.scope}`);
+ await navigator.locks.request(
+ activation.ownerLockName,
+ { mode: 'exclusive' },
+ async (lock) => {
+ if (!lock) throw new Error('owner lock was not acquired');
+ telemetry?.postMessage({
+ kind: 'lock-acquired',
+ tabId: activation.tabId,
+ ownerEpoch: activation.ownerEpoch,
+ });
+ let database: IDBDatabase | undefined;
+ let queue = Promise.resolve();
+ let draining = false;
+ let requestShutdown: (() => void) | undefined;
+ const shutdown = new Promise<void>((resolve) => {
+ requestShutdown = resolve;
+ });
+ try {
+ if (activation.databaseAction === 'wipe-before-open') {
+ telemetry?.postMessage({
+ kind: 'wipe-started',
+ ownerEpoch: activation.ownerEpoch,
+ });
+ await deleteDatabase(activation.scope);
+ telemetry?.postMessage({
+ kind: 'wipe-completed',
+ ownerEpoch: activation.ownerEpoch,
+ });
+ }
+ database = await openDatabase(activation.scope);
+ const activeDatabase = database;
+ port.onmessage = (event: MessageEvent<unknown>) => {
+ const parsed = validateCoordinatorToEngineEnvelope(event.data);
+ if (!parsed.ok) return;
+ const message: CoordinatorToEngineEnvelope = parsed.value;
+ if (message.ownerEpoch !== activation.ownerEpoch) return;
+ switch (message.kind) {
+ case 'heartbeat':
+ if (!ignoreHeartbeats) {
+ port.postMessage(
+ withVersion<EngineToCoordinatorEnvelope>({
+ kind: 'heartbeat-ack',
+ ownerEpoch: activation.ownerEpoch,
+ heartbeatId: message.heartbeatId,
+ })
+ );
+ }
+ break;
+ case 'drain-engine':
+ if (draining) return;
+ draining = true;
+ void queue.finally(() => requestShutdown?.());
+ break;
+ case 'engine-request':
+ if (draining) return;
+ telemetry?.postMessage({
+ kind: 'request-started',
+ tabId: activation.tabId,
+ ownerEpoch: activation.ownerEpoch,
+ routeId: message.routeId,
+ requestKind: message.request.kind,
+ requestId: message.request.id,
+ slow:
+ message.request.kind === 'read' &&
+ message.request.query.includes('Slow'),
+ });
+ queue = queue.then(async () => {
+ let response: CacheResponse;
+ try {
+ response = await execute(activeDatabase, message.request);
+ } catch (error) {
+ response = {
+ id: message.request.id,
+ ok: false,
+ error:
+ error instanceof Error ? error.message : String(error),
+ };
+ }
+ port.postMessage(
+ withVersion<EngineToCoordinatorEnvelope>({
+ kind: 'engine-response',
+ ownerEpoch: activation.ownerEpoch,
+ routeId: message.routeId,
+ response,
+ })
+ );
+ if (
+ response.ok &&
+ (message.request.kind === 'write' ||
+ message.request.kind === 'clear')
+ ) {
+ port.postMessage(
+ withVersion<EngineToCoordinatorEnvelope>({
+ kind: 'engine-push',
+ ownerEpoch: activation.ownerEpoch,
+ push: { kind: 'cache-changed' },
+ })
+ );
+ }
+ });
+ break;
+ }
+ };
+ port.start();
+ port.postMessage(
+ withVersion<EngineToCoordinatorEnvelope>({
+ kind: 'engine-ready',
+ tabId: activation.tabId,
+ ownerEpoch: activation.ownerEpoch,
+ ownerLockName: activation.ownerLockName,
+ ownerLockHeld: true,
+ databaseActionProof:
+ activation.databaseAction === 'wipe-before-open'
+ ? 'wiped-before-open'
+ : 'opened-existing',
+ openOutcome:
+ activation.databaseAction === 'wipe-before-open'
+ ? 'reset-storage-uncertain'
+ : 'opened-existing',
+ })
+ );
+ telemetry?.postMessage({
+ kind: 'ready',
+ tabId: activation.tabId,
+ ownerEpoch: activation.ownerEpoch,
+ });
+
+ await shutdown;
+ await queue;
+ database.close();
+ database = undefined;
+ port.postMessage(
+ withVersion<EngineToCoordinatorEnvelope>({
+ kind: 'engine-drained',
+ tabId: activation.tabId,
+ ownerEpoch: activation.ownerEpoch,
+ })
+ );
+ } finally {
+ database?.close();
+ telemetry?.postMessage({
+ kind: 'lock-releasing',
+ tabId: activation.tabId,
+ ownerEpoch: activation.ownerEpoch,
+ });
+ }
+ }
+ );
+ port.close();
+ telemetry?.close();
+ self.close();
+}
+
+self.onmessage = (event: MessageEvent<unknown>) => {
+ if (
+ typeof event.data === 'object' &&
+ event.data !== null &&
+ 'testKind' in event.data
+ ) {
+ const control = event.data as {
+ testKind: string;
+ ownerEpoch?: number;
+ routeId?: number;
+ };
+ if (control.testKind === 'crash') {
+ setTimeout(() => {
+ throw new Error('harness-induced worker-only failure');
+ });
+ } else if (
+ control.testKind === 'stale-response' &&
+ control.ownerEpoch !== undefined &&
+ control.routeId !== undefined
+ ) {
+ sendStaleResponse(control.ownerEpoch, control.routeId);
+ } else if (control.testKind === 'hang-heartbeats') {
+ ignoreHeartbeats = true;
+ }
+ return;
+ }
+
+ const parsed = validatePageToEngineEnvelope(event.data);
+ const port = event.ports[0];
+ if (!parsed.ok || !port || activationValue) {
+ port?.close();
+ return;
+ }
+ void activate(parsed.value, port);
+};
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/fake-coordinator.shared-worker.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/fake-coordinator.shared-worker.ts
new file mode 100644
index 0000000000..1c54c1c56d
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/fake-coordinator.shared-worker.ts
@@ -0,0 +1,24 @@
+/// <reference lib="webworker" />
+
+import { CoordinatorRouter } from '../coordinator-router';
+
+declare const self: SharedWorkerGlobalScope;
+
+const router = new CoordinatorRouter();
+let telemetry: BroadcastChannel | undefined;
+
+self.onconnect = (event: MessageEvent) => {
+ const port = event.ports[0];
+ if (port) router.connect(port);
+};
+
+setInterval(() => {
+ const snapshot = router.snapshot();
+ if (!snapshot) return;
+ telemetry ??= new BroadcastChannel(`graphql-cache-wp08:${snapshot.scope}`);
+ telemetry.postMessage({
+ kind: 'coordinator-snapshot',
+ ownerEpoch: snapshot.ownerEpoch,
+ snapshot,
+ });
+}, 100);
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/graphql-soup-rollout-harness.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/graphql-soup-rollout-harness.ts
new file mode 100644
index 0000000000..04f0dd74e6
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/graphql-soup-rollout-harness.ts
@@ -0,0 +1,191 @@
+export {};
+
+const result = document.querySelector<HTMLElement>('#result');
+if (!result) throw new Error('missing Cache GraphQL Soup result node');
+
+const NativeWorker = globalThis.Worker;
+const NativeSharedWorker = globalThis.SharedWorker;
+const workerUrls: string[] = [];
+const sharedWorkerUrls: string[] = [];
+
+globalThis.Worker = new Proxy(NativeWorker, {
+ construct(target, args: ConstructorParameters<typeof Worker>) {
+ workerUrls.push(String(args[0]));
+ return Reflect.construct(target, args) as Worker;
+ },
+});
+globalThis.SharedWorker = new Proxy(NativeSharedWorker, {
+ construct(target, args: ConstructorParameters<typeof SharedWorker>) {
+ sharedWorkerUrls.push(String(args[0]));
+ return Reflect.construct(target, args) as SharedWorker;
+ },
+});
+
+const resources = () => ({
+ workerUrls: [...workerUrls],
+ sharedWorkerUrls: [...sharedWorkerUrls],
+});
+
+const loadSoup = async () =>
+ await import('../../../service-clients/service-storage/graphql-soup');
+
+let posthogBeforeSendCalls = 0;
+
+async function initializeLocalPosthog() {
+ const { analytics } = await import('@app/lib/analytics');
+ if (!analytics.posthog.config.token) {
+ const disabledApiHost = `${location.origin}/__cache-rollout-posthog-disabled`;
+ analytics.posthog.init('phc_cache_rollout_local_test', {
+ api_host: disabledApiHost,
+ flags_api_host: disabledApiHost,
+ autocapture: false,
+ rageclick: false,
+ capture_pageview: false,
+ capture_pageleave: false,
+ capture_performance: false,
+ capture_dead_clicks: false,
+ capture_exceptions: false,
+ capture_heatmaps: false,
+ disable_session_recording: true,
+ enable_recording_console_log: false,
+ disable_persistence: true,
+ persistence: 'memory',
+ disable_external_dependency_loading: true,
+ disable_surveys: true,
+ disable_surveys_automatic_display: true,
+ disable_product_tours: true,
+ disable_conversations: true,
+ disable_web_experiments: true,
+ advanced_disable_flags: true,
+ advanced_disable_feature_flags_on_first_load: true,
+ advanced_disable_toolbar_metrics: true,
+ request_batching: false,
+ opt_out_capturing_by_default: true,
+ opt_out_persistence_by_default: true,
+ person_profiles: 'never',
+ save_campaign_params: false,
+ save_referrer: false,
+ before_send: () => {
+ posthogBeforeSendCalls += 1;
+ return null;
+ },
+ loaded: (posthog) => posthog.opt_out_capturing(),
+ });
+ }
+ return analytics;
+}
+
+function overrideRolloutFlags(
+ analytics: Awaited<ReturnType<typeof initializeLocalPosthog>>,
+ disabled: boolean
+): void {
+ analytics.posthog.featureFlags.overrideFeatureFlags({
+ flags: {
+ 'enable-graphql-soup': true,
+ 'enable-browser-turso-cache': true,
+ 'disable-browser-turso-cache': disabled,
+ },
+ suppressWarning: true,
+ });
+}
+
+const api = {
+ resources,
+ async resolveDefaultOff(): Promise<{
+ cacheEnabled: boolean;
+ cacheHostPresent: boolean;
+ resources: ReturnType<typeof resources>;
+ }> {
+ const soup = await loadSoup();
+ soup.getGraphqlSoupClient();
+ return {
+ cacheEnabled: soup.graphqlCacheEnabled(),
+ cacheHostPresent: soup.getGraphqlCacheHost() !== undefined,
+ resources: resources(),
+ };
+ },
+ async tryTreatment(): Promise<
+ | {
+ overrideApplied: false;
+ blocker: 'posthog-override-unavailable';
+ posthogBeforeSendCalls: number;
+ resources: ReturnType<typeof resources>;
+ }
+ | {
+ overrideApplied: true;
+ lazyBeforeRead: boolean;
+ readKind: string;
+ samePageKillLatched: boolean;
+ posthogBeforeSendCalls: number;
+ resources: ReturnType<typeof resources>;
+ }
+ > {
+ const analytics = await initializeLocalPosthog();
+ overrideRolloutFlags(analytics, false);
+ const overrideApplied =
+ analytics.posthog.isFeatureEnabled('enable-graphql-soup') === true &&
+ analytics.posthog.isFeatureEnabled('enable-browser-turso-cache') ===
+ true &&
+ analytics.posthog.isFeatureEnabled('disable-browser-turso-cache') ===
+ false;
+ if (!overrideApplied) {
+ return {
+ overrideApplied: false,
+ blocker: 'posthog-override-unavailable',
+ posthogBeforeSendCalls,
+ resources: resources(),
+ };
+ }
+
+ const soup = await loadSoup();
+ const client = soup.getGraphqlSoupClient();
+ const host = soup.getGraphqlCacheHost();
+ if (!host) throw new Error('PostHog treatment did not create cache host');
+ const lazyBeforeRead =
+ workerUrls.length === 0 && sharedWorkerUrls.length === 0;
+ const read = await host.readQuery({
+ query: 'query CacheRolloutSelector { __typename }',
+ operationName: 'CacheRolloutSelector',
+ });
+
+ overrideRolloutFlags(analytics, true);
+ const samePageKillLatched =
+ soup.getGraphqlSoupClient() === client &&
+ soup.getGraphqlCacheHost() === host;
+ return {
+ overrideApplied: true,
+ lazyBeforeRead,
+ readKind: read.kind,
+ samePageKillLatched,
+ posthogBeforeSendCalls,
+ resources: resources(),
+ };
+ },
+ async resolveAfterNavigationKill(): Promise<{
+ cacheEnabled: boolean;
+ cacheHostPresent: boolean;
+ posthogBeforeSendCalls: number;
+ resources: ReturnType<typeof resources>;
+ }> {
+ const analytics = await initializeLocalPosthog();
+ overrideRolloutFlags(analytics, true);
+ const soup = await loadSoup();
+ soup.getGraphqlSoupClient();
+ return {
+ cacheEnabled: soup.graphqlCacheEnabled(),
+ cacheHostPresent: soup.getGraphqlCacheHost() !== undefined,
+ posthogBeforeSendCalls,
+ resources: resources(),
+ };
+ },
+};
+
+declare global {
+ interface Window {
+ graphqlSoupRolloutHarness: typeof api;
+ }
+}
+
+window.graphqlSoupRolloutHarness = api;
+result.dataset.status = 'ready';
+result.textContent = JSON.stringify({ actualGraphqlSoupPath: true });
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/graphql-soup-rollout.html b/apps/web/src/lib/graphql-cache/worker/browser-test/graphql-soup-rollout.html
new file mode 100644
index 0000000000..0ab5fb8e08
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/graphql-soup-rollout.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <link rel="icon" href="data:," />
+ <title>Cache production GraphQL Soup selector harness</title>
+ </head>
+ <body>
+ <main id="result" data-status="loading">loading</main>
+ <script type="module" src="./graphql-soup-rollout-harness.ts"></script>
+ </body>
+</html>
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/harness.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/harness.ts
new file mode 100644
index 0000000000..691d1f4ed3
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/harness.ts
@@ -0,0 +1,408 @@
+import { databaseOwnerLockName } from '../coordinator-protocol';
+import type {
+ BrowserHarnessCommand,
+ BrowserHarnessEnvelope,
+} from './browser-wire';
+
+const resultElement = document.querySelector<HTMLElement>('#result');
+if (!resultElement) throw new Error('missing result element');
+
+type CommandWithoutId = BrowserHarnessCommand extends infer Command
+ ? Command extends BrowserHarnessCommand
+ ? Omit<Command, 'commandId'>
+ : never
+ : never;
+
+type EngineTelemetry = {
+ kind: string;
+ tabId?: string;
+ ownerEpoch: number;
+ routeId?: number;
+ requestKind?: string;
+ requestId?: number;
+ slow?: boolean;
+ snapshot?: { staleMessageDrops?: number };
+};
+
+const waitUntil = async (
+ description: string,
+ predicate: () => boolean,
+ timeoutMs = 20_000
+): Promise<void> => {
+ const started = performance.now();
+ while (!predicate()) {
+ if (performance.now() - started > timeoutMs) {
+ throw new Error(`timed out waiting for ${description}`);
+ }
+ await new Promise<void>((resolve) => setTimeout(resolve, 20));
+ }
+};
+
+const assert: (condition: unknown, message: string) => asserts condition = (
+ condition,
+ message
+) => {
+ if (!condition) throw new Error(message);
+};
+
+const run = async (): Promise<Record<string, unknown>> => {
+ const scope = `wp08-${crypto.randomUUID()}`;
+ const tabChannel = new BroadcastChannel(`graphql-cache-wp08-tabs:${scope}`);
+ const telemetryChannel = new BroadcastChannel(`graphql-cache-wp08:${scope}`);
+ const tabIds = ['tab-a', 'tab-b', 'tab-c'] as const;
+ const popups = new Map<string, Window>();
+ const registered = new Set<string>();
+ const adapterCreated = new Set<string>();
+ const eventOrder = new Map<string, string[]>();
+ const workers: Array<{ tabId: string; ownerEpoch: number }> = [];
+ const terminated: Array<{
+ tabId: string;
+ ownerEpoch: number;
+ reason: string;
+ }> = [];
+ const replacements = new Set<number>();
+ const pushes = new Map<string, number>();
+ const telemetry: EngineTelemetry[] = [];
+ const pendingCommands = new Map<
+ string,
+ {
+ resolve: (value: unknown) => void;
+ reject: (error: Error) => void;
+ timer: ReturnType<typeof setTimeout>;
+ }
+ >();
+ const protocolErrors: string[] = [];
+
+ const remember = (tabId: string, kind: string): void => {
+ const events = eventOrder.get(tabId) ?? [];
+ events.push(kind);
+ eventOrder.set(tabId, events);
+ };
+
+ tabChannel.onmessage = (event: MessageEvent<BrowserHarnessEnvelope>) => {
+ const envelope = event.data;
+ if (envelope.source !== 'tab') return;
+ const tabEvent = envelope.event;
+ remember(envelope.tabId, tabEvent.kind);
+ switch (tabEvent.kind) {
+ case 'adapter-created':
+ adapterCreated.add(envelope.tabId);
+ break;
+ case 'registered':
+ registered.add(envelope.tabId);
+ break;
+ case 'worker-created':
+ workers.push({
+ tabId: envelope.tabId,
+ ownerEpoch: tabEvent.ownerEpoch,
+ });
+ break;
+ case 'worker-terminated':
+ terminated.push({
+ tabId: envelope.tabId,
+ ownerEpoch: tabEvent.ownerEpoch,
+ reason: tabEvent.reason,
+ });
+ break;
+ case 'engine-replaced':
+ replacements.add(tabEvent.ownerEpoch);
+ break;
+ case 'cache-push':
+ pushes.set(envelope.tabId, (pushes.get(envelope.tabId) ?? 0) + 1);
+ break;
+ case 'protocol-error':
+ protocolErrors.push(tabEvent.error);
+ break;
+ case 'command-result': {
+ const pending = pendingCommands.get(tabEvent.commandId);
+ if (!pending) return;
+ pendingCommands.delete(tabEvent.commandId);
+ clearTimeout(pending.timer);
+ if (tabEvent.ok) pending.resolve(tabEvent.result);
+ else pending.reject(new Error(tabEvent.error));
+ break;
+ }
+ }
+ };
+ telemetryChannel.onmessage = (event: MessageEvent<EngineTelemetry>) => {
+ telemetry.push(event.data);
+ };
+
+ const command = async (
+ targetTabId: string,
+ value: CommandWithoutId
+ ): Promise<unknown> => {
+ const commandId = crypto.randomUUID();
+ const result = new Promise<unknown>((resolve, reject) => {
+ const timer = setTimeout(() => {
+ pendingCommands.delete(commandId);
+ reject(new Error(`command timed out: ${value.kind}`));
+ }, 20_000);
+ pendingCommands.set(commandId, { resolve, reject, timer });
+ });
+ tabChannel.postMessage({
+ source: 'harness',
+ targetTabId,
+ command: { ...value, commandId } as BrowserHarnessCommand,
+ } satisfies BrowserHarnessEnvelope);
+ return await result;
+ };
+
+ const latestOwner = (minimumEpoch = 0) =>
+ workers.toReversed().find((worker) => worker.ownerEpoch >= minimumEpoch);
+
+ const ownerLockName = (): string | undefined => {
+ if (!latestOwner()) return;
+ return databaseOwnerLockName(scope);
+ };
+
+ const verifyOwnerLock = async (ownerEpoch: number): Promise<void> => {
+ const lockName = ownerLockName();
+ assert(lockName, 'missing owner lock name');
+ const locks = await navigator.locks.query();
+ const held = locks.held?.filter((lock) => lock.name === lockName) ?? [];
+ assert(
+ held.length === 1,
+ `epoch ${ownerEpoch} did not hold one owner lock`
+ );
+ const unavailable = await navigator.locks.request(
+ lockName,
+ { mode: 'exclusive', ifAvailable: true },
+ (lock) => lock === null
+ );
+ assert(unavailable, `epoch ${ownerEpoch} owner lock was not exclusive`);
+ };
+
+ for (const tabId of tabIds) {
+ const url = new URL('./tab.html', location.href);
+ url.searchParams.set('scope', scope);
+ url.searchParams.set('tabId', tabId);
+ const popup = window.open(url, `${scope}:${tabId}`);
+ if (!popup) throw new Error(`popup blocked for ${tabId}`);
+ popups.set(tabId, popup);
+ }
+
+ await waitUntil('three adapters', () => adapterCreated.size === 3);
+ await waitUntil('three registrations', () => registered.size === 3);
+ await waitUntil('epoch 1 ready', () =>
+ telemetry.some((event) => event.kind === 'ready' && event.ownerEpoch === 1)
+ );
+ assert(workers.length === 1, 'standby page eagerly created a worker');
+ for (const tabId of tabIds) {
+ assert(
+ eventOrder.get(tabId)?.[0] === 'adapter-created',
+ `${tabId} created a worker before its lazy adapter`
+ );
+ }
+ await waitUntil(
+ 'three colliding init requests',
+ () =>
+ telemetry.filter(
+ (event) =>
+ event.kind === 'request-started' && event.requestKind === 'init'
+ ).length >= 3
+ );
+ const routedInitIds = new Set(
+ telemetry
+ .filter(
+ (event) =>
+ event.kind === 'request-started' && event.requestKind === 'init'
+ )
+ .map((event) => event.requestId)
+ );
+ assert(
+ routedInitIds.size === 3,
+ 'colliding tab request ids were not rewritten'
+ );
+ await verifyOwnerLock(1);
+
+ const first = latestOwner(1);
+ assert(first, 'missing epoch 1 owner');
+ const firstStandbys = tabIds.filter((tabId) => tabId !== first.tabId);
+ await command(firstStandbys[0]!, { kind: 'write', value: 'preserved' });
+ await waitUntil('cache push fanout', () =>
+ tabIds.every((tabId) => (pushes.get(tabId) ?? 0) > 0)
+ );
+ expectHit(await command(firstStandbys[1]!, { kind: 'read' }), 'preserved');
+
+ await command(first.tabId, { kind: 'graceful-close' });
+ await waitUntil('epoch 2 ready', () =>
+ telemetry.some((event) => event.kind === 'ready' && event.ownerEpoch === 2)
+ );
+ const second = latestOwner(2);
+ assert(second, 'missing epoch 2 owner');
+ assert(second.tabId !== first.tabId, 'graceful handoff reused retiring tab');
+ await verifyOwnerLock(2);
+ expectHit(await command(second.tabId, { kind: 'read' }), 'preserved');
+
+ await command(second.tabId, { kind: 'write', value: 'must-wipe' });
+ const requester = tabIds.find(
+ (tabId) => tabId !== first.tabId && tabId !== second.tabId
+ );
+ assert(requester, 'missing abrupt-loss requester');
+ const slow = command(requester, { kind: 'slow-read' }).then(
+ () => '',
+ (error: unknown) => (error instanceof Error ? error.message : String(error))
+ );
+ await waitUntil('slow route start', () =>
+ telemetry.some(
+ (event) =>
+ event.kind === 'request-started' &&
+ event.ownerEpoch === 2 &&
+ event.slow === true
+ )
+ );
+ const oldRoute = telemetry.find(
+ (event) =>
+ event.kind === 'request-started' &&
+ event.ownerEpoch === 2 &&
+ event.slow === true
+ );
+ assert(oldRoute?.routeId, 'missing old route id');
+ const secondPage = popups.get(second.tabId);
+ assert(secondPage && !secondPage.closed, 'abrupt owner page closed early');
+ await command(second.tabId, { kind: 'crash-worker' });
+ await waitUntil('epoch 2 worker termination', () =>
+ terminated.some((event) => event.ownerEpoch === 2)
+ );
+ const abruptError = await slow;
+ assert(
+ abruptError.includes('owner epoch 2 was lost'),
+ 'old route was not rejected'
+ );
+ assert(!secondPage.closed, 'worker-only failure closed its page');
+ try {
+ await waitUntil(
+ 'epoch 3 wipe and ready',
+ () =>
+ telemetry.some(
+ (event) => event.kind === 'wipe-completed' && event.ownerEpoch === 3
+ ) &&
+ telemetry.some(
+ (event) => event.kind === 'ready' && event.ownerEpoch === 3
+ )
+ );
+ } catch (error) {
+ const locks = await navigator.locks.query();
+ throw new Error(
+ `${error instanceof Error ? error.message : String(error)}; workers=${JSON.stringify(workers)}; telemetry=${JSON.stringify(telemetry.slice(-20))}; events=${JSON.stringify(Object.fromEntries(eventOrder))}; locks=${JSON.stringify(locks)}; protocol=${JSON.stringify(protocolErrors)}`
+ );
+ }
+ const third = latestOwner(3);
+ assert(third, 'missing epoch 3 owner');
+ await verifyOwnerLock(3);
+ expectMiss(await command(third.tabId, { kind: 'read' }));
+
+ await command(third.tabId, {
+ kind: 'stale-response',
+ ownerEpoch: 3,
+ routeId: oldRoute.routeId,
+ });
+ await waitUntil('coordinator stale-message telemetry', () =>
+ telemetry.some(
+ (event) =>
+ event.kind === 'coordinator-snapshot' &&
+ (event.snapshot?.staleMessageDrops ?? 0) > 0
+ )
+ );
+ expectMiss(await command(third.tabId, { kind: 'read' }));
+
+ await command(third.tabId, { kind: 'write', value: 'liveness-wipe' });
+ const thirdPage = popups.get(third.tabId);
+ assert(thirdPage && !thirdPage.closed, 'liveness owner page closed early');
+ await command(third.tabId, { kind: 'release-liveness-lock' });
+ await waitUntil('epoch 3 liveness termination', () =>
+ terminated.some(
+ (event) =>
+ event.ownerEpoch === 3 &&
+ event.reason === 'tab liveness lock was released'
+ )
+ );
+ assert(!thirdPage.closed, 'liveness lock release closed its page');
+ await waitUntil(
+ 'epoch 4 wipe and ready',
+ () =>
+ telemetry.some(
+ (event) => event.kind === 'wipe-completed' && event.ownerEpoch === 4
+ ) &&
+ telemetry.some(
+ (event) => event.kind === 'ready' && event.ownerEpoch === 4
+ )
+ );
+ const fourth = latestOwner(4);
+ assert(fourth, 'missing epoch 4 owner');
+ await verifyOwnerLock(4);
+ expectMiss(await command(fourth.tabId, { kind: 'read' }));
+
+ const result = {
+ passed: true,
+ openedTabs: 3,
+ ownerEpochs: workers.map((worker) => worker.ownerEpoch),
+ ownerTabs: workers.map((worker) => worker.tabId),
+ maxWorkersPerEpoch: Math.max(
+ ...workers.map(
+ ({ ownerEpoch }) =>
+ workers.filter((worker) => worker.ownerEpoch === ownerEpoch).length
+ )
+ ),
+ noEagerWorker: true,
+ collidingRequestIdsRewritten: true,
+ gracefulPreserved: true,
+ abruptRejectedInflight: abruptError.includes('owner epoch 2 was lost'),
+ abruptWiped: true,
+ workerOnlyPageStayedAlive: !secondPage.closed,
+ workerOnlyWiped: true,
+ livenessPageStayedAlive: !thirdPage.closed,
+ livenessTerminationReason: terminated.find(
+ (event) => event.ownerEpoch === 3
+ )?.reason,
+ livenessWiped: true,
+ staleMessageDrops: Math.max(
+ 0,
+ ...telemetry.map((event) => event.snapshot?.staleMessageDrops ?? 0)
+ ),
+ staleMessagePortResponseDropped: telemetry.some(
+ (event) => (event.snapshot?.staleMessageDrops ?? 0) > 0
+ ),
+ pushReachedAllTabs: tabIds.every((tabId) => (pushes.get(tabId) ?? 0) > 0),
+ ownerLockContentionEpochs: [1, 2, 3, 4],
+ engineReplacedEpochs: [...replacements].toSorted(),
+ protocolErrors,
+ };
+
+ for (const popup of popups.values()) popup.close();
+ tabChannel.close();
+ telemetryChannel.close();
+ return result;
+};
+
+function expectHit(value: unknown, expected: string): void {
+ assert(
+ typeof value === 'object' &&
+ value !== null &&
+ (value as { kind?: unknown }).kind === 'hit' &&
+ (value as { data?: { value?: unknown } }).data?.value === expected,
+ `expected cache hit ${expected}`
+ );
+}
+
+function expectMiss(value: unknown): void {
+ assert(
+ typeof value === 'object' &&
+ value !== null &&
+ (value as { kind?: unknown }).kind === 'miss',
+ 'expected cache miss'
+ );
+}
+
+void run().then(
+ (result) => {
+ resultElement.dataset.status = 'passed';
+ resultElement.textContent = JSON.stringify(result, null, 2);
+ },
+ (error: unknown) => {
+ resultElement.dataset.status = 'failed';
+ resultElement.textContent =
+ error instanceof Error ? (error.stack ?? error.message) : String(error);
+ }
+);
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/host-harness.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/host-harness.ts
new file mode 100644
index 0000000000..658e44597e
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/host-harness.ts
@@ -0,0 +1,223 @@
+import { createWorkerCacheHost } from '../../host/worker-host';
+import productionCacheWorkerUrl from './production-cache.engine-worker.ts?worker&url';
+
+const resultNode = document.querySelector('#result');
+if (!(resultNode instanceof HTMLElement))
+ throw new Error('missing result node');
+
+const scope = `wp09-host-${crypto.randomUUID()}`;
+const telemetry = new BroadcastChannel(
+ `graphql-cache-wp08-production:${scope}`
+);
+type TelemetryEvent = {
+ kind: string;
+ ownerEpoch: number;
+ requestId?: number;
+ requestKind?: string;
+ slow?: boolean;
+};
+const telemetryEvents: TelemetryEvent[] = [];
+telemetry.onmessage = (event: MessageEvent<TelemetryEvent>) => {
+ telemetryEvents.push(event.data);
+};
+
+const waitUntil = async (
+ label: string,
+ predicate: () => boolean,
+ timeoutMs = 20_000
+): Promise<void> => {
+ const deadline = performance.now() + timeoutMs;
+ while (!predicate()) {
+ if (performance.now() >= deadline) throw new Error(`${label} timed out`);
+ await new Promise((resolve) => setTimeout(resolve, 10));
+ }
+};
+
+const nativeWorker = globalThis.Worker;
+const nativeSharedWorker = globalThis.SharedWorker;
+const engineWorkers: Worker[] = [];
+const terminatedEpochs: number[] = [];
+let sharedWorkerConstructions = 0;
+let sharedPortClosed = false;
+
+const workerProxy = new Proxy(nativeWorker, {
+ construct(_target, args: ConstructorParameters<typeof Worker>) {
+ const [url, options] = args;
+ const epoch = Number(options?.name?.split(':').at(-1));
+ const worker = options?.name?.startsWith('graphql-cache-engine:')
+ ? new nativeWorker(productionCacheWorkerUrl, options)
+ : new nativeWorker(url, options);
+ if (options?.name?.startsWith('graphql-cache-engine:')) {
+ engineWorkers.push(worker);
+ const terminate = worker.terminate.bind(worker);
+ worker.terminate = () => {
+ terminatedEpochs.push(epoch);
+ terminate();
+ };
+ }
+ return worker;
+ },
+});
+globalThis.Worker = workerProxy;
+
+const sharedWorkerProxy = new Proxy(nativeSharedWorker, {
+ construct(_target, args: ConstructorParameters<typeof SharedWorker>) {
+ sharedWorkerConstructions += 1;
+ const worker = new nativeSharedWorker(...args);
+ const close = worker.port.close.bind(worker.port);
+ worker.port.close = () => {
+ sharedPortClosed = true;
+ close();
+ };
+ return worker;
+ },
+});
+globalThis.SharedWorker = sharedWorkerProxy;
+
+const QUERY = `query Soup($input: SoupInput!) {
+ user {
+ id
+ soup(input: $input) {
+ nextCursor
+ items {
+ __typename
+ id
+ }
+ }
+ }
+}`;
+const SLOW_QUERY = QUERY.replace('query Soup', 'query Slow');
+const VARIABLES = { input: { limit: 1 } };
+
+const report: Record<string, unknown> = {
+ passed: false,
+ noEagerConstructor: false,
+ requestOrder: [],
+ oldEpochRejectedBeforeReplacement: false,
+ oldRequestReplayCount: 0,
+ replacementActiveKeys: [],
+ replacementReadCompleted: false,
+ gracefulDrained: false,
+ terminatedEpochs,
+ sharedPortClosed: false,
+ initializationErrors: [],
+};
+
+try {
+ const initializationErrors: string[] = [];
+ const host = createWorkerCacheHost({
+ scope,
+ requestTimeoutMs: 10_000,
+ onInitializationError: (error) => initializationErrors.push(error.message),
+ });
+ report.noEagerConstructor =
+ sharedWorkerConstructions === 0 && engineWorkers.length === 0;
+
+ const order: string[] = [];
+ const replacementActiveKeys: number[][] = [];
+ let replacementRead: Promise<unknown> | undefined;
+ host.onOpsAffected((keys) => {
+ order.push('active-notified');
+ replacementActiveKeys.push(keys);
+ replacementRead ??= host.readQuery({
+ opKey: keys[0],
+ query: QUERY,
+ operationName: 'Soup',
+ variables: VARIABLES,
+ });
+ });
+
+ await Promise.all([
+ host.readQuery({
+ opKey: 7,
+ query: QUERY,
+ operationName: 'Soup',
+ variables: VARIABLES,
+ }),
+ host.readQuery({
+ opKey: 9,
+ query: QUERY,
+ operationName: 'Soup',
+ variables: VARIABLES,
+ }),
+ ]);
+ const slowRead = host.readQuery({
+ opKey: 7,
+ query: SLOW_QUERY,
+ operationName: 'Slow',
+ variables: VARIABLES,
+ });
+ const slowOutcome = slowRead.then(
+ () => undefined,
+ (error: unknown) => {
+ order.push('old-request-rejected');
+ return error;
+ }
+ );
+ await waitUntil('slow request admission', () =>
+ telemetryEvents.some((event) => event.slow === true)
+ );
+
+ engineWorkers[0]?.postMessage({ testKind: 'crash' });
+ const oldError = (await slowOutcome) as
+ | (Error & { errorCode?: string })
+ | undefined;
+ await waitUntil('replacement active notification', () =>
+ order.includes('active-notified')
+ );
+ await waitUntil('replacement read creation', () => replacementRead != null);
+ await replacementRead;
+
+ const routedRequests = telemetryEvents.filter(
+ (event) => event.kind === 'request-admitted'
+ );
+ report.requestOrder = routedRequests.map((event) => [
+ event.ownerEpoch,
+ event.requestId,
+ event.requestKind,
+ ]);
+ report.oldEpochRejectedBeforeReplacement =
+ oldError?.errorCode === 'owner-epoch-lost' &&
+ order.join(',') === 'old-request-rejected,active-notified';
+ report.oldRequestReplayCount = routedRequests.filter(
+ (event) => event.slow === true
+ ).length;
+ report.replacementActiveKeys = replacementActiveKeys;
+ report.replacementReadCompleted = routedRequests.some(
+ (event) =>
+ event.ownerEpoch === 2 &&
+ event.requestKind === 'read' &&
+ event.slow === false
+ );
+
+ host.dispose();
+ await waitUntil('graceful engine drain', () =>
+ telemetryEvents.some(
+ (event) => event.kind === 'drained' && event.ownerEpoch === 2
+ )
+ );
+ await waitUntil('graceful worker termination', () =>
+ terminatedEpochs.includes(2)
+ );
+ await waitUntil('coordinator port close', () => sharedPortClosed);
+
+ report.gracefulDrained = true;
+ report.sharedPortClosed = sharedPortClosed;
+ report.initializationErrors = initializationErrors;
+ report.passed =
+ report.noEagerConstructor === true &&
+ report.oldEpochRejectedBeforeReplacement === true &&
+ report.oldRequestReplayCount === 1 &&
+ JSON.stringify(replacementActiveKeys) === JSON.stringify([[7, 9]]) &&
+ report.replacementReadCompleted === true &&
+ report.gracefulDrained === true &&
+ sharedPortClosed &&
+ JSON.stringify(terminatedEpochs) === JSON.stringify([1, 2]) &&
+ initializationErrors.length === 0;
+} catch (error) {
+ report.error = error instanceof Error ? error.message : String(error);
+}
+
+resultNode.dataset.status = report.passed ? 'passed' : 'failed';
+resultNode.textContent = JSON.stringify(report);
+telemetry.close();
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/host.html b/apps/web/src/lib/graphql-cache/worker/browser-test/host.html
new file mode 100644
index 0000000000..9814da04d4
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/host.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <link rel="icon" href="data:," />
+ <title>WP-09 CacheHost coordinator browser test</title>
+ </head>
+ <body>
+ <pre id="result" data-status="running"></pre>
+ <script type="module" src="./host-harness.ts"></script>
+ </body>
+</html>
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/index.html b/apps/web/src/lib/graphql-cache/worker/browser-test/index.html
new file mode 100644
index 0000000000..e9a7f7cd1a
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/index.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <link rel="icon" href="data:," />
+ <title>WP-08 production coordinator browser harness</title>
+ </head>
+ <body>
+ <pre id="result" data-status="running">running</pre>
+ <script type="module" src="./harness.ts"></script>
+ </body>
+</html>
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/instrumented-cache.engine-worker.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/instrumented-cache.engine-worker.ts
new file mode 100644
index 0000000000..7d3de96f36
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/instrumented-cache.engine-worker.ts
@@ -0,0 +1,95 @@
+/// <reference lib="webworker" />
+
+import type { CacheEngineRuntimeEvent } from '../cache-engine-runtime';
+
+let channel: BroadcastChannel | undefined;
+let activationStartedAt = 0;
+let nestedWorkerConstructions = 0;
+let wasmFetchCount = 0;
+let wasmSha256: Promise<string> | undefined;
+const nativeFetch: typeof fetch = globalThis.fetch.bind(globalThis);
+globalThis.fetch = async (...argumentsList: Parameters<typeof fetch>) => {
+ const response = await nativeFetch(...argumentsList);
+ const input = argumentsList[0];
+ const requestUrl =
+ typeof input === 'string'
+ ? input
+ : input instanceof URL
+ ? input.href
+ : input.url;
+ if (/\/cache_wasm_bg(?:-[\w-]+)?\.wasm(?:[?#]|$)/.test(requestUrl)) {
+ wasmFetchCount++;
+ wasmSha256 = response
+ .clone()
+ .arrayBuffer()
+ .then(async (bytes) => {
+ const digest = await crypto.subtle.digest('SHA-256', bytes);
+ return [...new Uint8Array(digest)]
+ .map((byte) => byte.toString(16).padStart(2, '0'))
+ .join('');
+ });
+ }
+ return response;
+};
+
+const WorkerConstructor = globalThis.Worker;
+if (typeof WorkerConstructor === 'function') {
+ globalThis.Worker = new Proxy(WorkerConstructor, {
+ construct() {
+ nestedWorkerConstructions++;
+ throw new Error('nested cache worker construction is forbidden');
+ },
+ });
+}
+
+const report = async (event: CacheEngineRuntimeEvent): Promise<void> => {
+ channel ??= new BroadcastChannel(
+ `graphql-cache-performance:${event.activation.scope}`
+ );
+ if (event.kind === 'activation-started') {
+ activationStartedAt = performance.now();
+ channel.postMessage({
+ kind: 'activation-started',
+ ownerEpoch: event.activation.ownerEpoch,
+ });
+ }
+ if (event.kind === 'ready') {
+ const { cacheWasmLinearMemoryBytes } = await import('../wasm-module');
+ if (!wasmSha256) {
+ throw new Error('cache WASM fetch was not observed before DB readiness');
+ }
+ channel.postMessage({
+ kind: 'database-ready',
+ ownerEpoch: event.activation.ownerEpoch,
+ workerActivationMs: performance.now() - activationStartedAt,
+ linearMemoryBytes: cacheWasmLinearMemoryBytes(),
+ wasmFetchCount,
+ wasmSha256: await wasmSha256,
+ nestedWorkerConstructions,
+ crossOriginIsolated: globalThis.crossOriginIsolated,
+ sharedArrayBufferAvailable:
+ typeof globalThis.SharedArrayBuffer === 'function',
+ });
+ }
+};
+
+// Install interception before evaluating any production runtime module so a
+// future static-import constructor cannot run outside this measurement guard.
+// Top-level-await permits activation delivery during the dynamic import, so
+// buffer those envelopes until the production runtime owns `onmessage`.
+const bufferedActivationEvents: MessageEvent<unknown>[] = [];
+globalThis.onmessage = (event: MessageEvent<unknown>) => {
+ bufferedActivationEvents.push(event);
+};
+const { installCacheEngineWorker } = await import('../cache-engine-runtime');
+installCacheEngineWorker({
+ hooks: {
+ onEvent: (event) => {
+ void report(event);
+ },
+ },
+});
+const runtimeOnMessage = globalThis.onmessage;
+for (const event of bufferedActivationEvents) {
+ runtimeOnMessage?.call(globalThis, event);
+}
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/performance-harness.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/performance-harness.ts
new file mode 100644
index 0000000000..f2219b0176
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/performance-harness.ts
@@ -0,0 +1,209 @@
+import { createWorkerCacheHost } from '../../host/worker-host';
+import instrumentedEngineWorkerUrl from './instrumented-cache.engine-worker.ts?worker&url';
+
+const resultElement = document.querySelector<HTMLElement>('#result');
+if (!resultElement) throw new Error('missing result element');
+
+declare const __CACHE_WASM_BUILD_MODE__: 'development' | 'production';
+
+type WorkerObservation = {
+ kind: 'shared' | 'dedicated';
+ requestedUrl: string;
+ actualUrl: string;
+};
+let workerObserver: ((observation: WorkerObservation) => void) | undefined;
+let workerErrorObserver: ((error: Error) => void) | undefined;
+const NativeWorker = globalThis.Worker;
+const NativeSharedWorker = globalThis.SharedWorker;
+globalThis.Worker = new Proxy(NativeWorker, {
+ construct(target, argumentsList) {
+ const [requestedUrl, options] = argumentsList as ConstructorParameters<
+ typeof Worker
+ >;
+ const isCacheEngine = options?.name?.startsWith('graphql-cache-engine:');
+ const actualUrl = isCacheEngine
+ ? instrumentedEngineWorkerUrl
+ : requestedUrl;
+ workerObserver?.({
+ kind: 'dedicated',
+ requestedUrl: String(requestedUrl),
+ actualUrl: new URL(String(actualUrl), location.href).href,
+ });
+ const worker = Reflect.construct(target, [actualUrl, options]);
+ worker.addEventListener('error', (event: ErrorEvent) => {
+ workerErrorObserver?.(
+ new Error(event.message || 'instrumented engine worker failed')
+ );
+ });
+ worker.addEventListener('messageerror', () => {
+ workerErrorObserver?.(
+ new Error('instrumented engine worker emitted messageerror')
+ );
+ });
+ return worker;
+ },
+});
+globalThis.SharedWorker = new Proxy(NativeSharedWorker, {
+ construct(target, argumentsList) {
+ workerObserver?.({
+ kind: 'shared',
+ requestedUrl: String(argumentsList[0]),
+ actualUrl: String(argumentsList[0]),
+ });
+ return Reflect.construct(target, argumentsList);
+ },
+});
+
+type WorkerTelemetry =
+ | { kind: 'activation-started'; ownerEpoch: number }
+ | {
+ kind: 'database-ready';
+ ownerEpoch: number;
+ workerActivationMs: number;
+ linearMemoryBytes: number;
+ wasmFetchCount: number;
+ wasmSha256: string;
+ nestedWorkerConstructions: number;
+ crossOriginIsolated: boolean;
+ sharedArrayBufferAvailable: boolean;
+ };
+
+export interface CacheWasmPerformanceSample {
+ mode: 'development' | 'production';
+ activationMs: number;
+ browserReadyMs: number;
+ hostFirstReadyMs: number;
+ workerActivationMs: number;
+ linearMemoryBytes: number;
+ sharedWorkerConstructions: number;
+ dedicatedWorkerConstructions: number;
+ nestedWorkerConstructions: number;
+ wasmFetchCount: number;
+ wasmSha256: string;
+ ownerEpochs: number[];
+ crossOriginIsolated: boolean;
+ sharedArrayBufferAvailable: boolean;
+ sharedWorkerUrl: string;
+ productionEngineUrl: string;
+ instrumentedEngineUrl: string;
+}
+
+const waitFor = <T>(
+ description: string,
+ install: (resolve: (value: T) => void, reject: (error: Error) => void) => void
+): Promise<T> =>
+ new Promise<T>((resolve, reject) => {
+ const timer = setTimeout(
+ () => reject(new Error(`${description} timed out`)),
+ 15_000
+ );
+ install(
+ (value) => {
+ clearTimeout(timer);
+ resolve(value);
+ },
+ (error) => {
+ clearTimeout(timer);
+ reject(error);
+ }
+ );
+ });
+
+const QUERY = `query CachePerformance($input: SoupInput!) {
+ user {
+ id
+ soup(input: $input) {
+ nextCursor
+ items {
+ __typename
+ id
+ }
+ }
+ }
+}`;
+
+async function runMeasurement(): Promise<CacheWasmPerformanceSample> {
+ const scope = `cache-performance-${crypto.randomUUID()}`;
+ const started = performance.now();
+ let activationMs = 0;
+ let sharedWorkerConstructions = 0;
+ let dedicatedWorkerConstructions = 0;
+ let sharedWorkerUrl = '';
+ let productionEngineUrl = '';
+ let actualInstrumentedEngineUrl = '';
+ const ownerEpochs = new Set<number>();
+ workerObserver = ({ kind, requestedUrl, actualUrl }) => {
+ if (kind === 'shared') {
+ sharedWorkerConstructions++;
+ sharedWorkerUrl = requestedUrl;
+ } else {
+ dedicatedWorkerConstructions++;
+ productionEngineUrl = requestedUrl;
+ actualInstrumentedEngineUrl = actualUrl;
+ }
+ };
+ const telemetryChannel = new BroadcastChannel(
+ `graphql-cache-performance:${scope}`
+ );
+ let rejectDatabaseReady: ((error: Error) => void) | undefined;
+ const databaseReady = waitFor<
+ Extract<WorkerTelemetry, { kind: 'database-ready' }> & {
+ browserReadyMs: number;
+ }
+ >('cache database ready', (resolve, reject) => {
+ rejectDatabaseReady = reject;
+ telemetryChannel.onmessage = (event: MessageEvent<WorkerTelemetry>) => {
+ ownerEpochs.add(event.data.ownerEpoch);
+ if (event.data.kind === 'activation-started') {
+ activationMs = performance.now() - started;
+ return;
+ }
+ resolve({
+ ...event.data,
+ browserReadyMs: performance.now() - started,
+ });
+ };
+ });
+ workerErrorObserver = (error) => rejectDatabaseReady?.(error);
+ const host = createWorkerCacheHost({
+ scope,
+ requestTimeoutMs: 15_000,
+ initializationTimeoutMs: 15_000,
+ onInitializationError: (error) => rejectDatabaseReady?.(error),
+ });
+ const firstReady = host.readQuery({
+ opKey: 1,
+ query: QUERY,
+ operationName: 'CachePerformance',
+ variables: { input: { limit: 1 } },
+ });
+ const [ready] = await Promise.all([databaseReady, firstReady]);
+ const hostFirstReadyMs = performance.now() - started;
+ host.dispose();
+ telemetryChannel.close();
+ workerObserver = undefined;
+ workerErrorObserver = undefined;
+ return {
+ mode: __CACHE_WASM_BUILD_MODE__,
+ activationMs,
+ browserReadyMs: ready.browserReadyMs,
+ hostFirstReadyMs,
+ workerActivationMs: ready.workerActivationMs,
+ linearMemoryBytes: ready.linearMemoryBytes,
+ sharedWorkerConstructions,
+ dedicatedWorkerConstructions,
+ nestedWorkerConstructions: ready.nestedWorkerConstructions,
+ wasmFetchCount: ready.wasmFetchCount,
+ wasmSha256: ready.wasmSha256,
+ ownerEpochs: [...ownerEpochs].sort((left, right) => left - right),
+ crossOriginIsolated: ready.crossOriginIsolated,
+ sharedArrayBufferAvailable: ready.sharedArrayBufferAvailable,
+ sharedWorkerUrl,
+ productionEngineUrl,
+ instrumentedEngineUrl: actualInstrumentedEngineUrl,
+ };
+}
+
+Object.assign(window, { runCacheWasmPerformanceSample: runMeasurement });
+resultElement.dataset.status = 'idle';
+resultElement.textContent = JSON.stringify({ mode: __CACHE_WASM_BUILD_MODE__ });
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/performance.html b/apps/web/src/lib/graphql-cache/worker/browser-test/performance.html
new file mode 100644
index 0000000000..04f05d4995
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/performance.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <link rel="icon" href="data:," />
+ <title>Cache performance cache WASM packaging measurement</title>
+ </head>
+ <body>
+ <pre id="result" data-status="loading">loading</pre>
+ <script type="module" src="./performance-harness.ts"></script>
+ </body>
+</html>
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.config.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.config.ts
new file mode 100644
index 0000000000..9b4051eaaa
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.config.ts
@@ -0,0 +1,48 @@
+import { fileURLToPath } from 'node:url';
+import { defineConfig, devices } from '@playwright/test';
+
+const directory = fileURLToPath(new URL('.', import.meta.url));
+const webDirectory = fileURLToPath(new URL('../../../../../', import.meta.url));
+
+export default defineConfig({
+ testDir: directory,
+ testMatch: [
+ 'coordinator.browser.e2e.ts',
+ 'cache-wasm-packaging.browser.e2e.ts',
+ ],
+ timeout: 90_000,
+ fullyParallel: false,
+ workers: 1,
+ reporter: 'line',
+ use: {
+ baseURL: 'http://127.0.0.1:4188',
+ headless: true,
+ },
+ webServer: {
+ command: `just build-cache-wasm && bunx --bun vite --config ${JSON.stringify(`${directory}/vite.config.ts`)}`,
+ cwd: webDirectory,
+ url: 'http://127.0.0.1:4188',
+ reuseExistingServer: false,
+ timeout: 180_000,
+ },
+ projects: [
+ {
+ name: 'chromium',
+ use: {
+ ...devices['Desktop Chrome'],
+ launchOptions: {
+ executablePath: process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH,
+ },
+ },
+ },
+ {
+ name: 'firefox',
+ use: {
+ ...devices['Desktop Firefox'],
+ launchOptions: {
+ executablePath: process.env.PLAYWRIGHT_FIREFOX_EXECUTABLE_PATH,
+ },
+ },
+ },
+ ],
+});
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.production.config.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.production.config.ts
new file mode 100644
index 0000000000..d072dc6beb
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.production.config.ts
@@ -0,0 +1,50 @@
+import { fileURLToPath } from 'node:url';
+import { defineConfig } from '@playwright/test';
+
+const directory = fileURLToPath(new URL('.', import.meta.url));
+const webDirectory = fileURLToPath(new URL('../../../../../', import.meta.url));
+
+export default defineConfig({
+ testDir: directory,
+ testMatch: [
+ 'coordinator.browser.e2e.ts',
+ 'cache-wasm-packaging.browser.e2e.ts',
+ 'cache-lifecycle.browser.e2e.ts',
+ ],
+ timeout: 90_000,
+ fullyParallel: false,
+ workers: 1,
+ reporter: 'line',
+ use: {
+ baseURL: 'http://127.0.0.1:4189/app/',
+ headless: true,
+ },
+ webServer: {
+ command:
+ 'just build-cache-wasm-browser-production && node scripts/cache-wasm/precompressed-preview-server.mjs src/lib/graphql-cache/worker/browser-test/.dist-production',
+ cwd: webDirectory,
+ url: 'http://127.0.0.1:4189/app/',
+ reuseExistingServer: false,
+ timeout: 180_000,
+ },
+ projects: [
+ {
+ name: 'chromium-production',
+ use: {
+ browserName: 'chromium',
+ launchOptions: {
+ executablePath: process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH,
+ },
+ },
+ },
+ {
+ name: 'firefox-production',
+ use: {
+ browserName: 'firefox',
+ launchOptions: {
+ executablePath: process.env.PLAYWRIGHT_FIREFOX_EXECUTABLE_PATH,
+ },
+ },
+ },
+ ],
+});
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/production-browser-wire.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/production-browser-wire.ts
new file mode 100644
index 0000000000..bce3d68b6a
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/production-browser-wire.ts
@@ -0,0 +1,53 @@
+import type { CacheRequest } from '../../protocol';
+
+export type ProductionCacheRequestWithoutId = CacheRequest extends infer Request
+ ? Request extends CacheRequest
+ ? Omit<Request, 'id'>
+ : never
+ : never;
+
+export type ProductionHarnessCommand =
+ | { kind: 'write'; commandId: string; value: string }
+ | { kind: 'read'; commandId: string }
+ | { kind: 'slow-read'; commandId: string }
+ | { kind: 'graceful-close'; commandId: string }
+ | { kind: 'crash-worker'; commandId: string }
+ | {
+ kind: 'arm-mutation-block';
+ commandId: string;
+ requestKind: CacheRequest['kind'];
+ }
+ | {
+ kind: 'request';
+ commandId: string;
+ request: ProductionCacheRequestWithoutId;
+ }
+ | { kind: 'terminate-worker'; commandId: string };
+
+export type ProductionHarnessEnvelope =
+ | {
+ source: 'harness';
+ targetTabId: string;
+ command: ProductionHarnessCommand;
+ }
+ | {
+ source: 'tab';
+ tabId: string;
+ event:
+ | { kind: 'registered' }
+ | { kind: 'worker-created'; ownerEpoch: number }
+ | { kind: 'worker-terminated'; ownerEpoch: number; reason: string }
+ | {
+ kind: 'command-result';
+ commandId: string;
+ ok: true;
+ result?: unknown;
+ }
+ | {
+ kind: 'command-result';
+ commandId: string;
+ ok: false;
+ error: string;
+ }
+ | { kind: 'protocol-error'; error: string };
+ };
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/production-cache.engine-worker.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/production-cache.engine-worker.ts
new file mode 100644
index 0000000000..65298ffbf3
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/production-cache.engine-worker.ts
@@ -0,0 +1,119 @@
+/// <reference lib="webworker" />
+
+import type { CacheRequest } from '../../protocol';
+import {
+ type CacheEngineRuntimeEvent,
+ installCacheEngineWorker,
+} from '../cache-engine-runtime';
+
+const BLOCKABLE_MUTATION_KINDS = [
+ 'write',
+ 'enqueue-optimistic-mutation',
+ 'claim-next-mutation',
+ 'defer-optimistic-write',
+ 'commit-optimistic-write',
+ 'rollback-optimistic-write',
+ 'invalidate',
+ 'delete-records',
+ 'clear',
+] as const satisfies readonly CacheRequest['kind'][];
+
+type BlockableMutationKind = (typeof BLOCKABLE_MUTATION_KINDS)[number];
+
+let telemetry: BroadcastChannel | undefined;
+let activeScope: string | undefined;
+let armedMutationKind: BlockableMutationKind | undefined;
+const testChannel = (scope: string): BroadcastChannel => {
+ telemetry ??= new BroadcastChannel(`graphql-cache-wp08-production:${scope}`);
+ return telemetry;
+};
+const report = (event: CacheEngineRuntimeEvent): void => {
+ activeScope = event.activation.scope;
+ const workerPerformance = globalThis.performance as Performance & {
+ memory?: unknown;
+ measureUserAgentSpecificMemory?: unknown;
+ };
+ testChannel(event.activation.scope).postMessage({
+ kind: event.kind,
+ tabId: event.activation.tabId,
+ ownerEpoch: event.activation.ownerEpoch,
+ databaseAction: event.activation.databaseAction,
+ requestId: event.kind === 'request-admitted' ? event.request.id : undefined,
+ requestKind:
+ event.kind === 'request-admitted' ? event.request.kind : undefined,
+ slow:
+ event.kind === 'request-admitted' &&
+ event.request.kind === 'read' &&
+ event.request.query.includes('Slow'),
+ admissionBarrier:
+ event.kind === 'request-admitted' &&
+ event.request.kind === 'read' &&
+ event.request.query.includes('CacheAdmissionBarrier'),
+ reason: event.kind === 'fatal' ? event.reason : undefined,
+ fatalCode: event.kind === 'fatal' ? event.fatalCode : undefined,
+ performanceMemoryAvailable:
+ event.kind === 'ready' && workerPerformance.memory !== undefined,
+ userAgentSpecificMemoryAvailable:
+ event.kind === 'ready' &&
+ typeof workerPerformance.measureUserAgentSpecificMemory === 'function',
+ });
+};
+
+const blockInjectedRequest = async (request: CacheRequest): Promise<void> => {
+ if (request.kind === 'read' && request.query.includes('Slow')) {
+ await new Promise<void>(() => {});
+ }
+ if (request.kind === armedMutationKind) {
+ armedMutationKind = undefined;
+ if (!activeScope) throw new Error('test hook has no active scope');
+ testChannel(activeScope).postMessage({
+ kind: 'request-blocked-before-core',
+ requestId: request.id,
+ requestKind: request.kind,
+ });
+ await new Promise<void>(() => {});
+ }
+};
+
+installCacheEngineWorker({
+ hooks: {
+ beforeRequest: blockInjectedRequest,
+ onEvent: report,
+ },
+});
+
+const runtimeOnMessage = self.onmessage;
+self.onmessage = (event: MessageEvent<unknown>) => {
+ if (
+ typeof event.data === 'object' &&
+ event.data !== null &&
+ 'testKind' in event.data &&
+ event.data.testKind === 'crash'
+ ) {
+ setTimeout(() => {
+ throw new Error('production harness induced worker crash');
+ });
+ return;
+ }
+ if (
+ typeof event.data === 'object' &&
+ event.data !== null &&
+ 'testKind' in event.data &&
+ event.data.testKind === 'arm-mutation-block' &&
+ 'requestKind' in event.data &&
+ typeof event.data.requestKind === 'string' &&
+ (BLOCKABLE_MUTATION_KINDS as readonly string[]).includes(
+ event.data.requestKind
+ )
+ ) {
+ armedMutationKind = event.data.requestKind as BlockableMutationKind;
+ if (activeScope) {
+ testChannel(activeScope).postMessage({
+ kind: 'mutation-block-armed',
+ requestKind: armedMutationKind,
+ });
+ }
+ return;
+ }
+ runtimeOnMessage?.call(self, event);
+};
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/production-cache.storage-control-worker.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/production-cache.storage-control-worker.ts
new file mode 100644
index 0000000000..dd6fb414a1
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/production-cache.storage-control-worker.ts
@@ -0,0 +1,42 @@
+/// <reference lib="webworker" />
+
+import { match } from 'ts-pattern';
+import { loadBrowserTestCacheWasm } from './browser-test-wasm-module';
+
+type StorageControlRequest = {
+ id: number;
+ scope: string;
+ kind: 'incompatible-namespace' | 'corrupt-queue-payload';
+};
+
+type StorageControlResponse =
+ | { id: number; ok: true; wasmUrl: string }
+ | { id: number; ok: false; error: string };
+
+const worker = self as unknown as DedicatedWorkerGlobalScope;
+
+worker.onmessage = (event: MessageEvent<StorageControlRequest>) => {
+ const request = event.data;
+ void (async () => {
+ const { module, wasmUrl } = await loadBrowserTestCacheWasm();
+ await match(request)
+ .with({ kind: 'incompatible-namespace' }, ({ scope }) =>
+ module.browserTestMakeNamespaceIncompatible(scope)
+ )
+ .with({ kind: 'corrupt-queue-payload' }, ({ scope }) =>
+ module.browserTestCorruptQueuePayload(scope)
+ )
+ .exhaustive();
+ worker.postMessage({
+ id: request.id,
+ ok: true,
+ wasmUrl,
+ } satisfies StorageControlResponse);
+ })().catch((error: unknown) => {
+ worker.postMessage({
+ id: request.id,
+ ok: false,
+ error: error instanceof Error ? error.message : String(error),
+ } satisfies StorageControlResponse);
+ });
+};
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/production-harness.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/production-harness.ts
new file mode 100644
index 0000000000..bd9af4ece7
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/production-harness.ts
@@ -0,0 +1,374 @@
+import { databaseOwnerLockName } from '../coordinator-protocol';
+import type {
+ ProductionHarnessCommand,
+ ProductionHarnessEnvelope,
+} from './production-browser-wire';
+
+const resultElement = document.querySelector<HTMLElement>('#result');
+if (!resultElement) throw new Error('missing result element');
+
+type CommandWithoutId = ProductionHarnessCommand extends infer Command
+ ? Command extends ProductionHarnessCommand
+ ? Omit<Command, 'commandId'>
+ : never
+ : never;
+
+type RuntimeTelemetry = {
+ kind: string;
+ tabId: string;
+ ownerEpoch: number;
+ databaseAction: 'open-existing' | 'wipe-before-open';
+ requestId?: number;
+ requestKind?: string;
+ slow?: boolean;
+ reason?: string;
+};
+
+const assert: (condition: unknown, message: string) => asserts condition = (
+ condition,
+ message
+) => {
+ if (!condition) throw new Error(message);
+};
+
+const waitUntil = async (
+ description: string,
+ predicate: () => boolean | Promise<boolean>,
+ timeoutMs = 30_000
+): Promise<void> => {
+ const started = performance.now();
+ while (!(await predicate())) {
+ if (performance.now() - started > timeoutMs) {
+ throw new Error(`timed out waiting for ${description}`);
+ }
+ await new Promise<void>((resolve) => setTimeout(resolve, 20));
+ }
+};
+
+const run = async (): Promise<Record<string, unknown>> => {
+ const scope = `wp08-production-${crypto.randomUUID()}`;
+ const tabIds = ['production-a', 'production-b', 'production-c'] as const;
+ const tabChannel = new BroadcastChannel(
+ `graphql-cache-wp08-production-tabs:${scope}`
+ );
+ const telemetryChannel = new BroadcastChannel(
+ `graphql-cache-wp08-production:${scope}`
+ );
+ const popups = new Map<string, Window>();
+ const registered = new Set<string>();
+ const workers: Array<{ tabId: string; ownerEpoch: number }> = [];
+ const terminated: Array<{
+ tabId: string;
+ ownerEpoch: number;
+ reason: string;
+ }> = [];
+ const telemetry: RuntimeTelemetry[] = [];
+ const protocolErrors: string[] = [];
+ const pendingCommands = new Map<
+ string,
+ {
+ resolve: (value: unknown) => void;
+ reject: (error: Error) => void;
+ timer: ReturnType<typeof setTimeout>;
+ }
+ >();
+
+ tabChannel.onmessage = (event: MessageEvent<ProductionHarnessEnvelope>) => {
+ const message = event.data;
+ if (message.source !== 'tab') return;
+ switch (message.event.kind) {
+ case 'registered':
+ registered.add(message.tabId);
+ break;
+ case 'worker-created':
+ workers.push({
+ tabId: message.tabId,
+ ownerEpoch: message.event.ownerEpoch,
+ });
+ break;
+ case 'worker-terminated':
+ terminated.push({
+ tabId: message.tabId,
+ ownerEpoch: message.event.ownerEpoch,
+ reason: message.event.reason,
+ });
+ break;
+ case 'protocol-error':
+ protocolErrors.push(message.event.error);
+ break;
+ case 'command-result': {
+ const pending = pendingCommands.get(message.event.commandId);
+ if (!pending) return;
+ pendingCommands.delete(message.event.commandId);
+ clearTimeout(pending.timer);
+ if (message.event.ok) pending.resolve(message.event.result);
+ else pending.reject(new Error(message.event.error));
+ break;
+ }
+ }
+ };
+ telemetryChannel.onmessage = (event: MessageEvent<RuntimeTelemetry>) => {
+ telemetry.push(event.data);
+ };
+
+ const command = async (
+ targetTabId: string,
+ value: CommandWithoutId
+ ): Promise<unknown> => {
+ const commandId = crypto.randomUUID();
+ const result = new Promise<unknown>((resolve, reject) => {
+ const timer = setTimeout(() => {
+ pendingCommands.delete(commandId);
+ reject(new Error(`production command timed out: ${value.kind}`));
+ }, 30_000);
+ pendingCommands.set(commandId, { resolve, reject, timer });
+ });
+ tabChannel.postMessage({
+ source: 'harness',
+ targetTabId,
+ command: { ...value, commandId } as ProductionHarnessCommand,
+ } satisfies ProductionHarnessEnvelope);
+ return await result;
+ };
+
+ const latestOwner = (minimumEpoch = 0) =>
+ workers.toReversed().find((worker) => worker.ownerEpoch >= minimumEpoch);
+
+ const ownerLockName = databaseOwnerLockName(scope);
+ const queueOwnerLockContender = () => {
+ let release!: () => void;
+ let markAcquired!: () => void;
+ const acquired = new Promise<void>((resolve) => {
+ markAcquired = resolve;
+ });
+ const heldUntilReleased = new Promise<void>((resolve) => {
+ release = resolve;
+ });
+ const completed = navigator.locks.request(
+ ownerLockName,
+ { mode: 'exclusive' },
+ async (lock) => {
+ assert(lock, 'production lock contender did not acquire the lock');
+ markAcquired();
+ await heldUntilReleased;
+ }
+ );
+ return { acquired, release, completed };
+ };
+ const waitForPendingReplacementLock = async (
+ description: string
+ ): Promise<{ held: number; pending: number }> => {
+ let evidence = { held: 0, pending: 0 };
+ await waitUntil(description, async () => {
+ const snapshot = await navigator.locks.query();
+ evidence = {
+ held:
+ snapshot.held?.filter((lock) => lock.name === ownerLockName).length ??
+ 0,
+ pending:
+ snapshot.pending?.filter((lock) => lock.name === ownerLockName)
+ .length ?? 0,
+ };
+ return evidence.held === 1 && evidence.pending === 1;
+ });
+ return evidence;
+ };
+
+ for (const tabId of tabIds) {
+ const url = new URL('./production-tab.html', location.href);
+ url.searchParams.set('scope', scope);
+ url.searchParams.set('tabId', tabId);
+ const popup = window.open(url, `${scope}:${tabId}`);
+ if (!popup) throw new Error(`popup blocked for ${tabId}`);
+ popups.set(tabId, popup);
+ }
+
+ await waitUntil(
+ 'three production registrations',
+ () => registered.size === 3
+ );
+ await waitUntil('production epoch 1 ready', () =>
+ telemetry.some((event) => event.kind === 'ready' && event.ownerEpoch === 1)
+ );
+ const first = latestOwner(1);
+ assert(first, 'missing production epoch 1 owner');
+ const firstStandby = tabIds.find((tabId) => tabId !== first.tabId);
+ assert(firstStandby, 'missing production standby');
+
+ await command(firstStandby, { kind: 'write', value: 'real-preserved' });
+ expectProductionHit(
+ await command(firstStandby, { kind: 'read' }),
+ 'real-preserved'
+ );
+
+ const gracefulLock = queueOwnerLockContender();
+ const graceful = command(first.tabId, { kind: 'graceful-close' });
+ await gracefulLock.acquired;
+ await graceful;
+ await waitUntil('production epoch 1 drained', () =>
+ telemetry.some(
+ (event) => event.kind === 'drained' && event.ownerEpoch === 1
+ )
+ );
+ await waitUntil('production epoch 2 activation', () =>
+ telemetry.some(
+ (event) => event.kind === 'activation-started' && event.ownerEpoch === 2
+ )
+ );
+ const gracefulLockEvidence = await waitForPendingReplacementLock(
+ 'epoch 2 exact owner lock request to become pending'
+ );
+ const gracefulWaitedForPhysicalLock = !telemetry.some(
+ (event) => event.kind === 'ready' && event.ownerEpoch === 2
+ );
+ assert(
+ gracefulWaitedForPhysicalLock,
+ 'graceful replacement bypassed the held physical owner lock'
+ );
+ gracefulLock.release();
+ await gracefulLock.completed;
+ await waitUntil('production epoch 2 ready', () =>
+ telemetry.some((event) => event.kind === 'ready' && event.ownerEpoch === 2)
+ );
+ const second = latestOwner(2);
+ assert(second, 'missing production epoch 2 owner');
+ expectProductionHit(
+ await command(second.tabId, { kind: 'read' }),
+ 'real-preserved'
+ );
+
+ await command(second.tabId, { kind: 'write', value: 'real-must-wipe' });
+ expectProductionHit(
+ await command(second.tabId, { kind: 'read' }),
+ 'real-must-wipe'
+ );
+ const requester = tabIds.find(
+ (tabId) => tabId !== first.tabId && tabId !== second.tabId
+ );
+ assert(requester, 'missing production abrupt requester');
+ const slow = command(requester, { kind: 'slow-read' }).then(
+ () => '',
+ (error: unknown) => (error instanceof Error ? error.message : String(error))
+ );
+ await waitUntil('production slow request admission', () =>
+ telemetry.some(
+ (event) =>
+ event.kind === 'request-admitted' &&
+ event.ownerEpoch === 2 &&
+ event.slow === true
+ )
+ );
+
+ const abruptLock = queueOwnerLockContender();
+ const secondPage = popups.get(second.tabId);
+ assert(
+ secondPage && !secondPage.closed,
+ 'production owner page closed early'
+ );
+ await command(second.tabId, { kind: 'crash-worker' });
+ const abruptError = await slow;
+ assert(
+ abruptError.includes('owner epoch 2 was lost'),
+ 'production in-flight request was not rejected on abrupt loss'
+ );
+ await abruptLock.acquired;
+ await waitUntil('production epoch 3 recovery activation', () =>
+ telemetry.some(
+ (event) => event.kind === 'activation-started' && event.ownerEpoch === 3
+ )
+ );
+ const recoveryLockEvidence = await waitForPendingReplacementLock(
+ 'epoch 3 exact owner lock request to become pending'
+ );
+ const recoveryWaitedForPhysicalLock = !telemetry.some(
+ (event) => event.kind === 'ready' && event.ownerEpoch === 3
+ );
+ assert(
+ recoveryWaitedForPhysicalLock,
+ 'recovery replacement bypassed the held physical owner lock'
+ );
+ abruptLock.release();
+ await abruptLock.completed;
+ await waitUntil('production epoch 3 recovery ready', () =>
+ telemetry.some((event) => event.kind === 'ready' && event.ownerEpoch === 3)
+ );
+ const third = latestOwner(3);
+ assert(third, 'missing production epoch 3 owner');
+ expectProductionMiss(await command(third.tabId, { kind: 'read' }));
+
+ const slowAdmissions = telemetry.filter(
+ (event) => event.kind === 'request-admitted' && event.slow === true
+ );
+ assert(slowAdmissions.length === 1, 'abrupt in-flight request was replayed');
+ assert(!secondPage.closed, 'production worker crash closed its owner page');
+ assert(
+ terminated.some(
+ (event) =>
+ event.ownerEpoch === 2 &&
+ event.reason.includes('production harness induced worker crash')
+ ),
+ 'production worker crash reason was not attributed'
+ );
+ assert(protocolErrors.length === 0, 'production coordinator protocol error');
+
+ const result = {
+ passed: true,
+ realTursoDataPreservedGracefully: true,
+ gracefulCloseReleasedOwnerLock: telemetry.some(
+ (event) => event.kind === 'drained' && event.ownerEpoch === 1
+ ),
+ gracefulReplacementWaitedForPhysicalLock: gracefulWaitedForPhysicalLock,
+ gracefulPendingOwnerLockRequests: gracefulLockEvidence.pending,
+ abruptInflightRejected: abruptError.includes('owner epoch 2 was lost'),
+ abruptRequestReplayCount: slowAdmissions.length,
+ abruptOwnerPageStayedAlive: !secondPage.closed,
+ recoveryReplacementWaitedForPhysicalLock: recoveryWaitedForPhysicalLock,
+ recoveryPendingOwnerLockRequests: recoveryLockEvidence.pending,
+ atomicRecoveryOpenWipedToMiss: true,
+ recoveryDatabaseAction: telemetry.find(
+ (event) => event.kind === 'ready' && event.ownerEpoch === 3
+ )?.databaseAction,
+ ownerEpochs: workers.map((worker) => worker.ownerEpoch),
+ protocolErrors,
+ };
+
+ for (const popup of popups.values()) popup.close();
+ tabChannel.close();
+ telemetryChannel.close();
+ return result;
+};
+
+function expectProductionHit(value: unknown, expected: string): void {
+ assert(
+ typeof value === 'object' &&
+ value !== null &&
+ (value as { kind?: unknown }).kind === 'hit' &&
+ (
+ value as {
+ data?: { user?: { soup?: { items?: Array<{ id?: unknown }> } } };
+ }
+ ).data?.user?.soup?.items?.[0]?.id === expected,
+ `expected production cache hit ${expected}`
+ );
+}
+
+function expectProductionMiss(value: unknown): void {
+ assert(
+ typeof value === 'object' &&
+ value !== null &&
+ (value as { kind?: unknown }).kind === 'miss',
+ 'expected production cache miss'
+ );
+}
+
+void run().then(
+ (result) => {
+ resultElement.dataset.status = 'passed';
+ resultElement.textContent = JSON.stringify(result, null, 2);
+ },
+ (error: unknown) => {
+ resultElement.dataset.status = 'failed';
+ resultElement.textContent =
+ error instanceof Error ? (error.stack ?? error.message) : String(error);
+ }
+);
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/production-tab.html b/apps/web/src/lib/graphql-cache/worker/browser-test/production-tab.html
new file mode 100644
index 0000000000..38297ff4e2
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/production-tab.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <link rel="icon" href="data:," />
+ <title>WP-08 production Turso coordinator tab</title>
+ </head>
+ <body>
+ <p>WP-08 production Turso coordinator tab</p>
+ <script type="module" src="./production-tab.ts"></script>
+ </body>
+</html>
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/production-tab.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/production-tab.ts
new file mode 100644
index 0000000000..1b90e367d5
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/production-tab.ts
@@ -0,0 +1,217 @@
+import { match } from 'ts-pattern';
+import type { CacheRequest, CacheResponse } from '../../protocol';
+import {
+ createCacheCoordinatorPageAdapter,
+ type DedicatedWorkerLike,
+} from '../coordinator-page-adapter';
+import type {
+ ProductionHarnessCommand,
+ ProductionHarnessEnvelope,
+} from './production-browser-wire';
+
+const parameters = new URLSearchParams(location.search);
+const tabId = parameters.get('tabId') ?? '';
+const scope = parameters.get('scope') ?? '';
+if (!tabId || !scope) throw new Error('missing production harness parameters');
+
+const QUERY = `query Soup($input: SoupInput!) {
+ user {
+ id
+ soup(input: $input) {
+ nextCursor
+ items {
+ __typename
+ id
+ }
+ }
+ }
+}`;
+const SLOW_QUERY = QUERY.replace('query Soup', 'query Slow');
+const VARIABLES = { input: { limit: 1 } };
+
+const channel = new BroadcastChannel(
+ `graphql-cache-wp08-production-tabs:${scope}`
+);
+const report = (
+ event: Extract<ProductionHarnessEnvelope, { source: 'tab' }>['event']
+): void => {
+ channel.postMessage({
+ source: 'tab',
+ tabId,
+ event,
+ } satisfies ProductionHarnessEnvelope);
+};
+
+let nextRequestId = 1;
+let currentWorker: DedicatedWorkerLike | undefined;
+const pending = new Map<number, (response: CacheResponse) => void>();
+
+const adapter = createCacheCoordinatorPageAdapter({
+ scope,
+ tabId,
+ createDedicatedWorker: (_workerScope, ownerEpoch) =>
+ new Worker(
+ new URL('./production-cache.engine-worker.ts', import.meta.url),
+ {
+ type: 'module',
+ name: `graphql-cache-wp08-production:${scope}:${ownerEpoch}`,
+ }
+ ),
+ onWorkerCreated: (worker, ownerEpoch) => {
+ currentWorker = worker;
+ report({ kind: 'worker-created', ownerEpoch });
+ },
+ onWorkerTerminated: (ownerEpoch, reason) => {
+ currentWorker = undefined;
+ report({ kind: 'worker-terminated', ownerEpoch, reason });
+ },
+ onProtocolError: (error) => {
+ report({ kind: 'protocol-error', error: error.message });
+ },
+});
+
+adapter.onmessage = (event) => {
+ const message = event.data;
+ if ('kind' in message) return;
+ const resolve = pending.get(message.id);
+ if (!resolve) return;
+ pending.delete(message.id);
+ resolve(message);
+};
+
+type CacheRequestWithoutId = CacheRequest extends infer Request
+ ? Request extends CacheRequest
+ ? Omit<Request, 'id'>
+ : never
+ : never;
+
+const sendRequest = async (
+ commandId: string,
+ request: CacheRequestWithoutId
+): Promise<void> => {
+ const id = nextRequestId++;
+ const response = new Promise<CacheResponse>((resolve) => {
+ pending.set(id, resolve);
+ });
+ adapter.postMessage({ ...request, id } as CacheRequest);
+ const result = await response;
+ if (result.ok) {
+ report({
+ kind: 'command-result',
+ commandId,
+ ok: true,
+ result: result.result,
+ });
+ } else {
+ report({
+ kind: 'command-result',
+ commandId,
+ ok: false,
+ error: result.error,
+ });
+ }
+};
+
+const handleCommand = (command: ProductionHarnessCommand): void => {
+ match(command)
+ .with({ kind: 'write' }, (value) => {
+ void sendRequest(value.commandId, {
+ kind: 'write',
+ query: QUERY,
+ operationName: 'Soup',
+ variables: VARIABLES,
+ data: {
+ user: {
+ id: 'production-user',
+ soup: {
+ nextCursor: null,
+ items: [{ __typename: 'GraphqlSoupDocument', id: value.value }],
+ },
+ },
+ },
+ identity: 'production-test-user',
+ });
+ })
+ .with({ kind: 'read' }, (value) => {
+ void sendRequest(value.commandId, {
+ kind: 'read',
+ query: QUERY,
+ operationName: 'Soup',
+ variables: VARIABLES,
+ });
+ })
+ .with({ kind: 'slow-read' }, (value) => {
+ void sendRequest(value.commandId, {
+ kind: 'read',
+ query: SLOW_QUERY,
+ operationName: 'Slow',
+ variables: VARIABLES,
+ });
+ })
+ .with({ kind: 'graceful-close' }, (value) => {
+ void adapter.dispose({ graceful: true }).then(() => {
+ report({
+ kind: 'command-result',
+ commandId: value.commandId,
+ ok: true,
+ });
+ setTimeout(() => window.close());
+ });
+ })
+ .with({ kind: 'crash-worker' }, (value) => {
+ if (!currentWorker) {
+ report({
+ kind: 'command-result',
+ commandId: value.commandId,
+ ok: false,
+ error: 'tab has no production worker',
+ });
+ return;
+ }
+ currentWorker.postMessage({ testKind: 'crash' }, []);
+ report({ kind: 'command-result', commandId: value.commandId, ok: true });
+ })
+ .with({ kind: 'arm-mutation-block' }, (value) => {
+ if (!currentWorker) {
+ report({
+ kind: 'command-result',
+ commandId: value.commandId,
+ ok: false,
+ error: 'tab has no production worker',
+ });
+ return;
+ }
+ currentWorker.postMessage(
+ { testKind: 'arm-mutation-block', requestKind: value.requestKind },
+ []
+ );
+ report({ kind: 'command-result', commandId: value.commandId, ok: true });
+ })
+ .with({ kind: 'request' }, (value) => {
+ void sendRequest(value.commandId, value.request);
+ })
+ .with({ kind: 'terminate-worker' }, (value) => {
+ if (!currentWorker) {
+ report({
+ kind: 'command-result',
+ commandId: value.commandId,
+ ok: false,
+ error: 'tab has no production worker',
+ });
+ return;
+ }
+ currentWorker.terminate();
+ report({ kind: 'command-result', commandId: value.commandId, ok: true });
+ })
+ .exhaustive();
+};
+
+channel.onmessage = (event: MessageEvent<ProductionHarnessEnvelope>) => {
+ const message = event.data;
+ if (message.source === 'harness' && message.targetTabId === tabId) {
+ handleCommand(message.command);
+ }
+};
+
+adapter.postMessage({ id: nextRequestId++, kind: 'init', scope });
+void adapter.start().then(() => report({ kind: 'registered' }));
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/production.html b/apps/web/src/lib/graphql-cache/worker/browser-test/production.html
new file mode 100644
index 0000000000..b8d1ee8a85
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/production.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <link rel="icon" href="data:," />
+ <title>WP-08 production Turso coordinator harness</title>
+ </head>
+ <body>
+ <pre id="result" data-status="running">running</pre>
+ <script type="module" src="./production-harness.ts"></script>
+ </body>
+</html>
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/tab.html b/apps/web/src/lib/graphql-cache/worker/browser-test/tab.html
new file mode 100644
index 0000000000..26200ebe37
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/tab.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <link rel="icon" href="data:," />
+ <title>WP-08 coordinator tab</title>
+ </head>
+ <body>
+ <p>WP-08 coordinator tab</p>
+ <script type="module" src="./tab.ts"></script>
+ </body>
+</html>
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/tab.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/tab.ts
new file mode 100644
index 0000000000..3cc93fbde2
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/tab.ts
@@ -0,0 +1,215 @@
+import { match } from 'ts-pattern';
+import type { CacheRequest, CacheResponse } from '../../protocol';
+import {
+ createCacheCoordinatorPageAdapter,
+ type DedicatedWorkerLike,
+} from '../coordinator-page-adapter';
+import type {
+ BrowserHarnessCommand,
+ BrowserHarnessEnvelope,
+} from './browser-wire';
+
+const parameters = new URLSearchParams(location.search);
+const tabId = parameters.get('tabId') ?? '';
+const scope = parameters.get('scope') ?? '';
+if (!tabId || !scope) throw new Error('missing browser harness parameters');
+
+const channel = new BroadcastChannel(`graphql-cache-wp08-tabs:${scope}`);
+const report = (
+ event: Extract<BrowserHarnessEnvelope, { source: 'tab' }>['event']
+): void => {
+ channel.postMessage({
+ source: 'tab',
+ tabId,
+ event,
+ } satisfies BrowserHarnessEnvelope);
+};
+
+let releaseLivenessLock!: () => void;
+const releaseLivenessSignal = new Promise<void>((resolve) => {
+ releaseLivenessLock = resolve;
+});
+const lockManager = {
+ request: ((
+ lockName: string,
+ options: LockOptions,
+ callback: (lock: Lock | null) => unknown
+ ) =>
+ navigator.locks.request(lockName, options, async (lock) => {
+ // The harness intentionally releases liveness early and discards a
+ // callback result that no caller consumes.
+ await Promise.race([
+ Promise.resolve(callback(lock)),
+ releaseLivenessSignal,
+ ]);
+ })) as LockManager['request'],
+};
+
+let nextRequestId = 1;
+let currentWorker: DedicatedWorkerLike | undefined;
+const pending = new Map<
+ number,
+ { commandId: string; resolve: (response: CacheResponse) => void }
+>();
+
+const adapter = createCacheCoordinatorPageAdapter({
+ scope,
+ tabId,
+ createSharedWorker: (workerScope) =>
+ new SharedWorker(
+ new URL('./fake-coordinator.shared-worker.ts', import.meta.url),
+ {
+ type: 'module',
+ name: `graphql-cache-wp08-coordinator:${workerScope}`,
+ }
+ ),
+ lockManager,
+ createDedicatedWorker: (_scope, ownerEpoch) =>
+ new Worker(new URL('./fake-cache.engine-worker.ts', import.meta.url), {
+ type: 'module',
+ name: `graphql-cache-wp08-fake:${scope}:${ownerEpoch}`,
+ }),
+ onWorkerCreated: (worker, ownerEpoch) => {
+ currentWorker = worker;
+ report({ kind: 'worker-created', ownerEpoch });
+ },
+ onWorkerTerminated: (ownerEpoch, reason) => {
+ currentWorker = undefined;
+ report({ kind: 'worker-terminated', ownerEpoch, reason });
+ },
+ onEngineReplaced: (ownerEpoch) => {
+ report({ kind: 'engine-replaced', ownerEpoch });
+ },
+ onProtocolError: (error) => {
+ report({ kind: 'protocol-error', error: error.message });
+ },
+});
+report({ kind: 'adapter-created' });
+
+adapter.onmessage = (event) => {
+ const message = event.data;
+ if ('kind' in message) {
+ report({ kind: 'cache-push', pushKind: message.kind });
+ return;
+ }
+ const waiter = pending.get(message.id);
+ if (!waiter) return;
+ pending.delete(message.id);
+ waiter.resolve(message);
+};
+
+type CacheRequestWithoutId = CacheRequest extends infer Request
+ ? Request extends CacheRequest
+ ? Omit<Request, 'id'>
+ : never
+ : never;
+
+const sendRequest = async (
+ commandId: string,
+ request: CacheRequestWithoutId
+): Promise<void> => {
+ const id = nextRequestId++;
+ const response = new Promise<CacheResponse>((resolve) => {
+ pending.set(id, { commandId, resolve });
+ });
+ adapter.postMessage({ ...request, id } as CacheRequest);
+ const result = await response;
+ if (result.ok) {
+ report({
+ kind: 'command-result',
+ commandId,
+ ok: true,
+ result: result.result,
+ });
+ } else {
+ report({
+ kind: 'command-result',
+ commandId,
+ ok: false,
+ error: result.error,
+ });
+ }
+};
+
+const handleCommand = (command: BrowserHarnessCommand): void => {
+ match(command)
+ .with({ kind: 'write' }, (value) => {
+ void sendRequest(value.commandId, {
+ kind: 'write',
+ query: 'query Value { value }',
+ data: { value: value.value },
+ });
+ })
+ .with({ kind: 'read' }, (value) => {
+ void sendRequest(value.commandId, {
+ kind: 'read',
+ query: 'query Value { value }',
+ });
+ })
+ .with({ kind: 'slow-read' }, (value) => {
+ void sendRequest(value.commandId, {
+ kind: 'read',
+ query: 'query Slow { value }',
+ });
+ })
+ .with({ kind: 'graceful-close' }, (value) => {
+ void adapter.dispose({ graceful: true }).then(() => {
+ report({
+ kind: 'command-result',
+ commandId: value.commandId,
+ ok: true,
+ });
+ setTimeout(() => window.close());
+ });
+ })
+ .with({ kind: 'crash-worker' }, (value) => {
+ if (!currentWorker) {
+ report({
+ kind: 'command-result',
+ commandId: value.commandId,
+ ok: false,
+ error: 'tab has no worker',
+ });
+ return;
+ }
+ currentWorker.postMessage({ testKind: 'crash' }, []);
+ report({ kind: 'command-result', commandId: value.commandId, ok: true });
+ })
+ .with({ kind: 'release-liveness-lock' }, (value) => {
+ releaseLivenessLock();
+ report({ kind: 'command-result', commandId: value.commandId, ok: true });
+ })
+ .with({ kind: 'stale-response' }, (value) => {
+ if (!currentWorker) {
+ report({
+ kind: 'command-result',
+ commandId: value.commandId,
+ ok: false,
+ error: 'tab has no worker',
+ });
+ return;
+ }
+ currentWorker.postMessage(
+ {
+ testKind: 'stale-response',
+ ownerEpoch: value.ownerEpoch,
+ routeId: value.routeId,
+ },
+ []
+ );
+ report({ kind: 'command-result', commandId: value.commandId, ok: true });
+ })
+ .exhaustive();
+};
+
+channel.onmessage = (event: MessageEvent<BrowserHarnessEnvelope>) => {
+ const message = event.data;
+ if (message.source === 'harness' && message.targetTabId === tabId) {
+ handleCommand(message.command);
+ }
+};
+
+// First cache use starts liveness registration. Every page deliberately uses
+// request id 1, proving the coordinator must rewrite ids before engine routing.
+adapter.postMessage({ id: nextRequestId++, kind: 'init', scope });
+void adapter.start().then(() => report({ kind: 'registered' }));
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/vite.config.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/vite.config.ts
new file mode 100644
index 0000000000..221807ddf0
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/vite.config.ts
@@ -0,0 +1,56 @@
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defineConfig } from 'vite';
+import tsconfigPaths from 'vite-tsconfig-paths';
+
+const directory = fileURLToPath(new URL('.', import.meta.url));
+
+export default defineConfig(({ command }) => ({
+ root: directory,
+ base: command === 'build' ? '/app/' : '/',
+ plugins: [
+ tsconfigPaths({
+ projects: [resolve(directory, '../../../../../tsconfig.json')],
+ }),
+ ],
+ define: {
+ __CACHE_WASM_BUILD_MODE__: JSON.stringify(
+ command === 'build' ? 'production' : 'development'
+ ),
+ },
+ server: {
+ host: '127.0.0.1',
+ port: 4188,
+ strictPort: true,
+ },
+ preview: {
+ host: '127.0.0.1',
+ port: 4189,
+ strictPort: true,
+ },
+ worker: { format: 'es' },
+ build: {
+ target: 'esnext',
+ outDir: resolve(directory, '.dist-production'),
+ emptyOutDir: true,
+ sourcemap: true,
+ assetsInlineLimit: 0,
+ rollupOptions: {
+ input: Object.fromEntries(
+ [
+ 'index.html',
+ 'host.html',
+ 'cutover.html',
+ 'production.html',
+ 'production-tab.html',
+ 'tab.html',
+ 'performance.html',
+ 'exact-production-host.html',
+ 'cache-lifecycle.html',
+ 'graphql-soup-rollout.html',
+ 'cache-recovery.html',
+ ].map((name) => [name.replace('.html', ''), resolve(directory, name)])
+ ),
+ },
+ },
+}));
diff --git a/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.test.ts b/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.test.ts
new file mode 100644
index 0000000000..90ad4b5b4b
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.test.ts
@@ -0,0 +1,742 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { CacheRequest } from '../protocol';
+import {
+ type CacheEngineRuntimeOptions,
+ installCacheEngineWorker,
+} from './cache-engine-runtime';
+import {
+ CACHE_COORDINATOR_PROTOCOL_VERSION,
+ databaseOwnerLockName,
+ type PageToEngineEnvelope,
+} from './coordinator-protocol';
+import {
+ type CoordinatorMessagePort,
+ CoordinatorRouter,
+} from './coordinator-router';
+import type { CacheWorkerCoreOptions } from './worker-core';
+
+class FakePort {
+ readonly messages: unknown[] = [];
+ closed = false;
+ started = false;
+ onmessage: ((event: MessageEvent<unknown>) => void) | null = null;
+ onmessageerror: (() => void) | null = null;
+
+ postMessage(message: unknown): void {
+ this.messages.push(message);
+ }
+
+ close(): void {
+ this.closed = true;
+ }
+
+ start(): void {
+ this.started = true;
+ }
+
+ receive(message: unknown): void {
+ this.onmessage?.({ data: message, ports: [] } as unknown as MessageEvent);
+ }
+}
+
+class FakeWorkerScope {
+ closed = false;
+ onmessage: ((event: MessageEvent<unknown>) => void) | null = null;
+
+ close(): void {
+ this.closed = true;
+ }
+
+ activate(
+ activation: PageToEngineEnvelope,
+ port: FakePort | MessagePort
+ ): void {
+ this.onmessage?.({
+ data: activation,
+ ports: [port as MessagePort],
+ } as unknown as MessageEvent);
+ }
+}
+
+const version = {
+ coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION,
+} as const;
+
+const activation = (
+ databaseAction: 'open-existing' | 'wipe-before-open' = 'open-existing'
+): PageToEngineEnvelope => ({
+ ...version,
+ kind: 'activate-engine',
+ scope: 'scope',
+ tabId: 'tab-a',
+ ownerEpoch: 7,
+ databaseAction,
+ ownerLockName: 'owner-lock',
+ hotCapacity: 11,
+});
+
+const messagesOfKind = <T extends string>(port: FakePort, kind: T) =>
+ port.messages.filter(
+ (message): message is Record<string, unknown> & { kind: T } =>
+ typeof message === 'object' &&
+ message !== null &&
+ (message as { kind?: unknown }).kind === kind
+ );
+
+const registerTab = async (
+ router: CoordinatorRouter,
+ port: FakePort,
+ tabId: string
+): Promise<void> => {
+ await router.handleTabMessage(port as CoordinatorMessagePort, {
+ ...version,
+ kind: 'register-tab',
+ scope: 'scope',
+ tabId,
+ livenessLockName: `graphql-cache-tab:scope:${tabId}`,
+ });
+};
+
+const attachRuntime = async (
+ router: CoordinatorRouter,
+ tabPort: FakePort,
+ tabId: string,
+ ownerEpoch: number,
+ databaseAction: 'open-existing' | 'wipe-before-open',
+ createCore: NonNullable<CacheEngineRuntimeOptions['createCore']>,
+ outbound?: unknown[]
+): Promise<{ channel: MessageChannel; scope: FakeWorkerScope }> => {
+ const channel = new MessageChannel();
+ if (outbound) {
+ const postMessage = channel.port2.postMessage.bind(channel.port2);
+ channel.port2.postMessage = ((message: unknown) => {
+ outbound.push(message);
+ postMessage(message);
+ }) as MessagePort['postMessage'];
+ }
+ await router.handleTabMessage(
+ tabPort as CoordinatorMessagePort,
+ {
+ ...version,
+ kind: 'attach-engine-port',
+ tabId,
+ ownerEpoch,
+ },
+ [channel.port1]
+ );
+ const scope = new FakeWorkerScope();
+ installCacheEngineWorker({
+ scope,
+ ownerLockIsHeld: async () => true,
+ createCore,
+ });
+ scope.activate(
+ {
+ ...version,
+ kind: 'activate-engine',
+ scope: 'scope',
+ tabId,
+ ownerEpoch,
+ databaseAction,
+ ownerLockName: databaseOwnerLockName('scope'),
+ },
+ channel.port2
+ );
+ await vi.waitFor(() =>
+ expect(router.snapshot()?.state).toMatchObject({
+ kind: 'active',
+ tabId,
+ ownerEpoch,
+ })
+ );
+ return { channel, scope };
+};
+
+const cacheResponses = (port: FakePort) =>
+ messagesOfKind(port, 'cache-message').map(
+ (message) => message.message as Record<string, unknown>
+ );
+
+describe('cache engine worker runtime', () => {
+ it('selects atomic recovery-open and only proves wipe after initialization', async () => {
+ const scope = new FakeWorkerScope();
+ const direct = new FakePort();
+ let coreOptions: CacheWorkerCoreOptions | undefined;
+ const handleRequest = vi.fn(
+ async (
+ port: { postMessage(message: unknown): void },
+ request: CacheRequest
+ ) => {
+ expect(request).toMatchObject({
+ kind: 'init',
+ scope: 'scope',
+ hotCapacity: 11,
+ });
+ port.postMessage({ id: request.id, ok: true, result: null });
+ }
+ );
+ installCacheEngineWorker({
+ scope,
+ ownerLockIsHeld: async () => true,
+ createCore: (options) => {
+ coreOptions = options;
+ return {
+ addPort: vi.fn(),
+ handleRequest,
+ drain: vi.fn(),
+ };
+ },
+ });
+
+ scope.activate(activation('wipe-before-open'), direct);
+ await vi.waitFor(() =>
+ expect(messagesOfKind(direct, 'engine-ready')).toHaveLength(1)
+ );
+
+ expect(coreOptions?.recoveryOpen).toBe(true);
+ expect(messagesOfKind(direct, 'engine-ready')[0]).toMatchObject({
+ tabId: 'tab-a',
+ ownerEpoch: 7,
+ databaseActionProof: 'wiped-before-open',
+ });
+ });
+
+ it('throttles runtime linear memory, emits cached queue state, and drains high-water values', async () => {
+ const scope = new FakeWorkerScope();
+ const direct = new FakePort();
+ const observations: Array<Record<string, unknown>> = [];
+ const recordCachedQueueDiagnostics = vi.fn();
+ let now = 0;
+ let memoryBytes = 10;
+ installCacheEngineWorker({
+ scope,
+ now: () => now,
+ readLinearMemoryBytes: () => memoryBytes,
+ memoryTelemetryIntervalMs: 60_000,
+ ownerLockIsHeld: async () => true,
+ telemetry: {
+ record: (observation) => observations.push(observation),
+ flush: vi.fn(),
+ },
+ createCore: () => ({
+ addPort: vi.fn(),
+ drain: vi.fn(),
+ recordCachedQueueDiagnostics,
+ handleRequest: async (port, request) => {
+ port.postMessage({ id: request.id, ok: true, result: null });
+ },
+ }),
+ });
+ scope.activate(activation(), direct);
+ await vi.waitFor(() =>
+ expect(messagesOfKind(direct, 'engine-ready')).toHaveLength(1)
+ );
+
+ direct.receive({
+ ...version,
+ kind: 'heartbeat',
+ ownerEpoch: 7,
+ heartbeatId: 1,
+ });
+ now = 60_000;
+ memoryBytes = 20;
+ direct.receive({
+ ...version,
+ kind: 'heartbeat',
+ ownerEpoch: 7,
+ heartbeatId: 2,
+ });
+ memoryBytes = 15;
+ direct.receive({
+ ...version,
+ kind: 'drain-engine',
+ ownerEpoch: 7,
+ });
+ await vi.waitFor(() =>
+ expect(messagesOfKind(direct, 'engine-drained')).toHaveLength(1)
+ );
+
+ expect(recordCachedQueueDiagnostics).toHaveBeenCalledTimes(2);
+ expect(
+ observations.filter(
+ (observation) => observation.name === 'graphql_cache.linear_memory'
+ )
+ ).toEqual([
+ expect.objectContaining({ bytes: 10, highWaterBytes: 10 }),
+ expect.objectContaining({ bytes: 20, highWaterBytes: 20 }),
+ expect.objectContaining({ bytes: 15, highWaterBytes: 20 }),
+ ]);
+ });
+
+ it('fatals instead of forwarding a core-emitted coordinator-only error code', async () => {
+ const scope = new FakeWorkerScope();
+ const direct = new FakePort();
+ installCacheEngineWorker({
+ scope,
+ ownerLockIsHeld: async () => true,
+ createCore: () => ({
+ addPort: vi.fn(),
+ drain: vi.fn(),
+ handleRequest: async (port, request) => {
+ if (request.kind === 'init') {
+ port.postMessage({ id: request.id, ok: true, result: null });
+ return;
+ }
+ port.postMessage({
+ id: request.id,
+ ok: false,
+ error: 'forged topology loss',
+ errorCode: 'owner-epoch-lost',
+ });
+ },
+ }),
+ });
+ scope.activate(activation(), direct);
+ await vi.waitFor(() =>
+ expect(messagesOfKind(direct, 'engine-ready')).toHaveLength(1)
+ );
+
+ direct.receive({
+ ...version,
+ kind: 'engine-request',
+ ownerEpoch: 7,
+ routeId: 1,
+ request: { id: 1, kind: 'clear' },
+ });
+ await vi.waitFor(() =>
+ expect(messagesOfKind(direct, 'engine-fatal')).toHaveLength(1)
+ );
+
+ expect(messagesOfKind(direct, 'engine-response')).toHaveLength(0);
+ expect(messagesOfKind(direct, 'engine-fatal')[0]).toMatchObject({
+ reason: 'CacheWorkerCore emitted a coordinator-only cache error code',
+ fatalCode: 'runtime-failure',
+ });
+ });
+
+ it('keeps an earlier injected admission ahead of drain and response ordering', async () => {
+ const scope = new FakeWorkerScope();
+ const direct = new FakePort();
+ const order: string[] = [];
+ let releaseHook!: () => void;
+ const hookBlocker = new Promise<void>((resolve) => {
+ releaseHook = resolve;
+ });
+ const handleRequest = vi.fn(
+ async (
+ port: { postMessage(message: unknown): void },
+ request: CacheRequest
+ ) => {
+ if (request.kind === 'init') {
+ port.postMessage({ id: request.id, ok: true, result: null });
+ return;
+ }
+ order.push('request');
+ port.postMessage({
+ id: request.id,
+ ok: true,
+ result: { kind: 'miss' },
+ });
+ }
+ );
+ const drain = vi.fn(async () => {
+ order.push('drain');
+ });
+ installCacheEngineWorker({
+ scope,
+ ownerLockIsHeld: async () => true,
+ hooks: {
+ beforeRequest: async (request) => {
+ if (request.kind === 'read') await hookBlocker;
+ },
+ },
+ createCore: () => ({ addPort: vi.fn(), handleRequest, drain }),
+ });
+ scope.activate(activation(), direct);
+ await vi.waitFor(() =>
+ expect(messagesOfKind(direct, 'engine-ready')).toHaveLength(1)
+ );
+
+ direct.receive({
+ ...version,
+ kind: 'engine-request',
+ ownerEpoch: 7,
+ routeId: 23,
+ request: { id: 23, kind: 'read', query: 'query Slow { value }' },
+ });
+ direct.receive({
+ ...version,
+ kind: 'drain-engine',
+ ownerEpoch: 7,
+ });
+ await Promise.resolve();
+ expect(drain).not.toHaveBeenCalled();
+
+ releaseHook();
+ await vi.waitFor(() =>
+ expect(messagesOfKind(direct, 'engine-drained')).toHaveLength(1)
+ );
+
+ expect(order).toEqual(['request', 'drain']);
+ expect(
+ direct.messages
+ .filter(
+ (message) =>
+ typeof message === 'object' &&
+ message !== null &&
+ ['engine-response', 'engine-drained'].includes(
+ String((message as { kind?: unknown }).kind)
+ )
+ )
+ .map((message) => (message as { kind: string }).kind)
+ ).toEqual(['engine-response', 'engine-drained']);
+ expect(direct.closed).toBe(true);
+ expect(scope.closed).toBe(true);
+ });
+
+ it('does not replay a completed mutation or leak its stale response and push after owner loss', async () => {
+ const router = new CoordinatorRouter({
+ verifyTabLockHeld: async () => true,
+ watchTabLock: () => () => {},
+ });
+ const tabA = new FakePort();
+ const tabB = new FakePort();
+ await registerTab(router, tabA, 'tab-a');
+ await registerTab(router, tabB, 'tab-b');
+
+ let effectCount = 0;
+ let markEffectStarted!: () => void;
+ const effectStarted = new Promise<void>((resolve) => {
+ markEffectStarted = resolve;
+ });
+ let releaseOldOutput!: () => void;
+ const oldOutputBlocked = new Promise<void>((resolve) => {
+ releaseOldOutput = resolve;
+ });
+ let markOldOutputPosted!: () => void;
+ const oldOutputPosted = new Promise<void>((resolve) => {
+ markOldOutputPosted = resolve;
+ });
+ const oldRuntime = await attachRuntime(
+ router,
+ tabA,
+ 'tab-a',
+ 1,
+ 'open-existing',
+ () => ({
+ addPort: vi.fn(),
+ drain: vi.fn(),
+ handleRequest: async (port, request) => {
+ if (request.kind === 'init') {
+ port.postMessage({ id: request.id, ok: true, result: null });
+ return;
+ }
+ if (request.kind !== 'clear') return;
+ effectCount += 1;
+ markEffectStarted();
+ await oldOutputBlocked;
+ port.postMessage({ id: request.id, ok: true, result: null });
+ port.postMessage({ kind: 'cache-changed' });
+ markOldOutputPosted();
+ },
+ })
+ );
+
+ await router.handleTabMessage(tabB as CoordinatorMessagePort, {
+ ...version,
+ kind: 'cache-request',
+ tabId: 'tab-b',
+ request: { id: 41, kind: 'clear' },
+ });
+ await effectStarted;
+ expect(effectCount).toBe(1);
+ expect(router.snapshot()?.inFlightRequestCount).toBe(1);
+
+ await router.handleTabMessage(tabA as CoordinatorMessagePort, {
+ ...version,
+ kind: 'engine-lost',
+ tabId: 'tab-a',
+ ownerEpoch: 1,
+ reason: 'injected owner failure after durable mutation',
+ });
+ await vi.waitFor(() =>
+ expect(router.snapshot()?.state).toMatchObject({
+ kind: 'activating',
+ tabId: 'tab-b',
+ ownerEpoch: 2,
+ databaseAction: 'wipe-before-open',
+ })
+ );
+ expect(cacheResponses(tabB)).toContainEqual({
+ id: 41,
+ ok: false,
+ error: expect.stringContaining('owner epoch 1 was lost'),
+ errorCode: 'owner-epoch-lost',
+ });
+
+ const replacementRequests: string[] = [];
+ const replacementRuntime = await attachRuntime(
+ router,
+ tabB,
+ 'tab-b',
+ 2,
+ 'wipe-before-open',
+ () => ({
+ addPort: vi.fn(),
+ drain: vi.fn(),
+ handleRequest: async (port, request) => {
+ if (request.kind === 'init') {
+ port.postMessage({ id: request.id, ok: true, result: null });
+ return;
+ }
+ replacementRequests.push(request.kind);
+ },
+ })
+ );
+
+ releaseOldOutput();
+ await oldOutputPosted;
+
+ expect(effectCount).toBe(1);
+ expect(replacementRequests).toEqual([]);
+ expect(
+ [...cacheResponses(tabA), ...cacheResponses(tabB)].filter(
+ (message) => message.kind === 'cache-changed'
+ )
+ ).toEqual([]);
+ expect(router.snapshot()?.state).toMatchObject({
+ kind: 'active',
+ ownerEpoch: 2,
+ });
+
+ oldRuntime.channel.port1.close();
+ oldRuntime.channel.port2.close();
+ replacementRuntime.channel.port1.close();
+ replacementRuntime.channel.port2.close();
+ });
+
+ it('emits one authoritative reset sequence across live fatal and recovery replacement', async () => {
+ const observations: Array<Record<string, unknown>> = [];
+ const router = new CoordinatorRouter({
+ verifyTabLockHeld: async () => true,
+ watchTabLock: () => () => {},
+ telemetry: {
+ record: (observation) => observations.push(observation),
+ flush: vi.fn(),
+ },
+ });
+ const tabA = new FakePort();
+ const tabB = new FakePort();
+ await registerTab(router, tabA, 'tab-a');
+ await registerTab(router, tabB, 'tab-b');
+
+ const outbound: unknown[] = [];
+ let markResetRequestStarted!: () => void;
+ const resetRequestStarted = new Promise<void>((resolve) => {
+ markResetRequestStarted = resolve;
+ });
+ let triggerReset!: () => void;
+ const resetBlocked = new Promise<void>((resolve) => {
+ triggerReset = resolve;
+ });
+ const runtime = await attachRuntime(
+ router,
+ tabA,
+ 'tab-a',
+ 1,
+ 'open-existing',
+ (options) => ({
+ addPort: vi.fn(),
+ drain: vi.fn(),
+ handleRequest: async (port, request) => {
+ if (request.kind === 'init') {
+ port.postMessage({ id: request.id, ok: true, result: null });
+ return;
+ }
+ if (request.kind === 'read') return;
+ if (request.kind !== 'clear') return;
+ markResetRequestStarted();
+ await resetBlocked;
+ options.onStorageResetRequired?.(
+ Object.assign(new Error('storage reset'), {
+ cacheStorageResetRequired: true as const,
+ })
+ );
+ port.postMessage({
+ id: request.id,
+ ok: false,
+ error: 'ordinary request error after reset marker',
+ });
+ },
+ }),
+ outbound
+ );
+
+ await router.handleTabMessage(tabB as CoordinatorMessagePort, {
+ ...version,
+ kind: 'cache-request',
+ tabId: 'tab-b',
+ request: { id: 51, kind: 'read', query: 'query Pending { value }' },
+ });
+ await vi.waitFor(() =>
+ expect(router.snapshot()?.inFlightRequestCount).toBe(1)
+ );
+ await router.handleTabMessage(tabB as CoordinatorMessagePort, {
+ ...version,
+ kind: 'cache-request',
+ tabId: 'tab-b',
+ request: { id: 52, kind: 'clear' },
+ });
+ await resetRequestStarted;
+ expect(router.snapshot()?.inFlightRequestCount).toBe(2);
+
+ triggerReset();
+ await vi.waitFor(() =>
+ expect(router.snapshot()?.state).toMatchObject({
+ kind: 'activating',
+ ownerEpoch: 2,
+ databaseAction: 'wipe-before-open',
+ })
+ );
+ await vi.waitFor(() =>
+ expect(
+ outbound.filter(
+ (message) =>
+ typeof message === 'object' &&
+ message !== null &&
+ ['engine-fatal', 'engine-response'].includes(
+ String((message as { kind?: unknown }).kind)
+ )
+ )
+ ).toHaveLength(2)
+ );
+
+ const fatalAndResponse = outbound
+ .filter(
+ (message) =>
+ typeof message === 'object' &&
+ message !== null &&
+ ['engine-fatal', 'engine-response'].includes(
+ String((message as { kind?: unknown }).kind)
+ )
+ )
+ .map((message) => (message as { kind: string }).kind);
+ expect(fatalAndResponse).toEqual(['engine-fatal', 'engine-response']);
+ expect(outbound).toContainEqual(
+ expect.objectContaining({
+ kind: 'engine-fatal',
+ fatalCode: 'storage-reset-required',
+ })
+ );
+ expect(router.snapshot()?.inFlightRequestCount).toBe(0);
+ expect(cacheResponses(tabB)).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ id: 51,
+ ok: false,
+ error: expect.stringContaining(
+ 'cache storage requested physical reset'
+ ),
+ }),
+ expect.objectContaining({
+ id: 52,
+ ok: false,
+ error: expect.stringContaining(
+ 'cache storage requested physical reset'
+ ),
+ }),
+ ])
+ );
+ expect(cacheResponses(tabB)).not.toContainEqual(
+ expect.objectContaining({
+ error: 'ordinary request error after reset marker',
+ })
+ );
+
+ const replacementRuntime = await attachRuntime(
+ router,
+ tabB,
+ 'tab-b',
+ 2,
+ 'wipe-before-open',
+ (options) => ({
+ addPort: vi.fn(),
+ drain: vi.fn(),
+ handleRequest: async (port, request) => {
+ if (request.kind === 'init') {
+ options.onInitializationOutcome?.('reset-storage-uncertain');
+ port.postMessage({ id: request.id, ok: true, result: null });
+ }
+ },
+ })
+ );
+ expect(
+ observations
+ .filter((observation) =>
+ [
+ 'graphql_cache.storage_reset_required',
+ 'graphql_cache.logical_reset',
+ 'graphql_cache.reset_wipe',
+ ].includes(String(observation.name))
+ )
+ .map((observation) => observation.name)
+ ).toEqual([
+ 'graphql_cache.storage_reset_required',
+ 'graphql_cache.logical_reset',
+ 'graphql_cache.reset_wipe',
+ ]);
+ expect(
+ observations.filter(
+ (observation) =>
+ observation.name === 'graphql_cache.storage_reset_required'
+ )
+ ).toHaveLength(1);
+
+ runtime.channel.port1.close();
+ runtime.channel.port2.close();
+ replacementRuntime.channel.port1.close();
+ replacementRuntime.channel.port2.close();
+ });
+
+ it('reports a fatal error for a valid envelope with the wrong owner epoch', async () => {
+ const scope = new FakeWorkerScope();
+ const direct = new FakePort();
+ const handleRequest = vi.fn(
+ async (
+ port: { postMessage(message: unknown): void },
+ request: CacheRequest
+ ) => {
+ port.postMessage({ id: request.id, ok: true, result: null });
+ }
+ );
+ installCacheEngineWorker({
+ scope,
+ ownerLockIsHeld: async () => true,
+ createCore: () => ({
+ addPort: vi.fn(),
+ handleRequest,
+ drain: vi.fn(),
+ }),
+ });
+ scope.activate(activation(), direct);
+ await vi.waitFor(() =>
+ expect(messagesOfKind(direct, 'engine-ready')).toHaveLength(1)
+ );
+
+ direct.receive({
+ ...version,
+ kind: 'heartbeat',
+ ownerEpoch: 8,
+ heartbeatId: 1,
+ });
+
+ expect(messagesOfKind(direct, 'engine-fatal')).toContainEqual(
+ expect.objectContaining({
+ tabId: 'tab-a',
+ ownerEpoch: 7,
+ reason: 'coordinator envelope owner epoch does not match activation',
+ })
+ );
+ expect(messagesOfKind(direct, 'heartbeat-ack')).toHaveLength(0);
+ });
+});
diff --git a/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.ts b/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.ts
new file mode 100644
index 0000000000..c91d57954c
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.ts
@@ -0,0 +1,392 @@
+/// <reference lib="webworker" />
+
+import type { CacheRequest, CacheResponse } from '../protocol';
+import {
+ type CacheTelemetryRecorderLike,
+ classifyCacheError,
+ isolateCacheTelemetry,
+} from '../telemetry';
+import { workerCacheTelemetry } from '../telemetry-relay';
+import {
+ CACHE_COORDINATOR_PROTOCOL_VERSION,
+ type CoordinatorToEngineEnvelope,
+ type EngineFatalCode,
+ type EngineOpenOutcome,
+ type EngineToCoordinatorEnvelope,
+ isCachePush,
+ isCacheResponse,
+ type PageToEngineEnvelope,
+ validateCoordinatorToEngineEnvelope,
+ validatePageToEngineEnvelope,
+} from './coordinator-protocol';
+import { cacheWasmLinearMemoryBytes } from './wasm-module';
+import { CacheWorkerCore, type CacheWorkerCoreOptions } from './worker-core';
+
+export type CacheEngineRuntimeEvent =
+ | { kind: 'activation-started'; activation: PageToEngineEnvelope }
+ | {
+ kind: 'request-admitted';
+ activation: PageToEngineEnvelope;
+ request: CacheRequest;
+ }
+ | { kind: 'ready'; activation: PageToEngineEnvelope }
+ | { kind: 'drained'; activation: PageToEngineEnvelope }
+ | {
+ kind: 'fatal';
+ activation: PageToEngineEnvelope;
+ reason: string;
+ fatalCode: EngineFatalCode;
+ };
+
+export interface CacheEngineRuntimeHooks {
+ beforeRequest?: (
+ request: CacheRequest,
+ activation: PageToEngineEnvelope
+ ) => void | Promise<void>;
+ onEvent?: (event: CacheEngineRuntimeEvent) => void;
+}
+
+interface CacheWorkerCoreLike {
+ addPort(port: { postMessage(message: unknown): void }): void;
+ handleRequest(
+ port: { postMessage(message: unknown): void },
+ request: CacheRequest
+ ): Promise<void>;
+ drain(): Promise<void>;
+ recordCachedQueueDiagnostics?(): void;
+}
+
+interface DedicatedWorkerScopeLike {
+ onmessage: ((event: MessageEvent<unknown>) => void) | null;
+ close(): void;
+}
+
+export interface CacheEngineRuntimeOptions {
+ scope?: DedicatedWorkerScopeLike;
+ hooks?: CacheEngineRuntimeHooks;
+ createCore?: (options: CacheWorkerCoreOptions) => CacheWorkerCoreLike;
+ ownerLockIsHeld?: (ownerLockName: string) => Promise<boolean>;
+ telemetry?: CacheTelemetryRecorderLike;
+ /** Injectable clock/memory source for throttling tests. */
+ now?: () => number;
+ readLinearMemoryBytes?: () => number;
+ memoryTelemetryIntervalMs?: number;
+}
+
+const withVersion = <T extends { coordinatorVersion: 1 }>(
+ value: T extends unknown ? Omit<T, 'coordinatorVersion'> : never
+): T =>
+ ({
+ coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION,
+ ...value,
+ }) as unknown as T;
+
+const errorMessage = (error: unknown): string =>
+ error instanceof Error ? error.message : String(error);
+
+async function initializeCore(
+ core: CacheWorkerCoreLike,
+ activation: PageToEngineEnvelope
+): Promise<void> {
+ let response: CacheResponse | undefined;
+ await core.handleRequest(
+ {
+ postMessage(message: unknown) {
+ if (isCacheResponse(message)) response = message;
+ },
+ },
+ {
+ id: 0,
+ kind: 'init',
+ scope: activation.scope,
+ hotCapacity: activation.hotCapacity,
+ }
+ );
+ if (!response || !response.ok) {
+ throw new Error(
+ response && !response.ok
+ ? response.error
+ : 'cache engine initialization returned no response'
+ );
+ }
+}
+
+async function defaultOwnerLockIsHeld(ownerLockName: string): Promise<boolean> {
+ const snapshot = await navigator.locks.query();
+ return Boolean(
+ snapshot.held?.some(
+ (lock) => lock.name === ownerLockName && lock.mode === 'exclusive'
+ )
+ );
+}
+
+async function activate(
+ activation: PageToEngineEnvelope,
+ directPort: MessagePort,
+ workerScope: DedicatedWorkerScopeLike,
+ options: CacheEngineRuntimeOptions
+): Promise<void> {
+ const hooks = options.hooks;
+ const telemetry = isolateCacheTelemetry(
+ options.telemetry ?? workerCacheTelemetry()
+ );
+ const now =
+ options.now ?? (() => globalThis.performance?.now() ?? Date.now());
+ const activationStartedAt = now();
+ const readLinearMemoryBytes =
+ options.readLinearMemoryBytes ?? cacheWasmLinearMemoryBytes;
+ const memoryTelemetryIntervalMs = options.memoryTelemetryIntervalMs ?? 60_000;
+ let lastMemoryTelemetryAt = Number.NEGATIVE_INFINITY;
+ let linearMemoryHighWaterBytes = 0;
+ const recordLinearMemory = (force: boolean): void => {
+ const observedAt = now();
+ if (
+ !force &&
+ observedAt - lastMemoryTelemetryAt < memoryTelemetryIntervalMs
+ ) {
+ return;
+ }
+ try {
+ const bytes = readLinearMemoryBytes();
+ linearMemoryHighWaterBytes = Math.max(linearMemoryHighWaterBytes, bytes);
+ lastMemoryTelemetryAt = observedAt;
+ telemetry.record({
+ name: 'graphql_cache.linear_memory',
+ operationCategory: 'storage',
+ outcome: 'success',
+ bytes,
+ highWaterBytes: linearMemoryHighWaterBytes,
+ });
+ } catch {
+ // A missing memory export only drops this observation.
+ }
+ };
+ const emitEvent = (event: CacheEngineRuntimeEvent): void => {
+ try {
+ hooks?.onEvent?.(event);
+ } catch {
+ // Observation hooks are never part of the ownership protocol.
+ }
+ };
+ emitEvent({ kind: 'activation-started', activation });
+ let failed = false;
+ let initializationOpenOutcome: EngineOpenOutcome =
+ activation.databaseAction === 'wipe-before-open'
+ ? 'reset-storage-uncertain'
+ : 'opened-existing';
+ let draining = false;
+ const pendingAdmissions = new Set<Promise<void>>();
+ const post = (message: EngineToCoordinatorEnvelope): void => {
+ directPort.postMessage(message);
+ };
+ const fatal = (
+ reason: string,
+ fatalCode: EngineFatalCode = 'runtime-failure'
+ ): void => {
+ if (failed) return;
+ failed = true;
+ emitEvent({ kind: 'fatal', activation, reason, fatalCode });
+ post(
+ withVersion<EngineToCoordinatorEnvelope>({
+ kind: 'engine-fatal',
+ tabId: activation.tabId,
+ ownerEpoch: activation.ownerEpoch,
+ reason,
+ fatalCode,
+ })
+ );
+ };
+
+ const createCore =
+ options.createCore ??
+ ((coreOptions: CacheWorkerCoreOptions) => new CacheWorkerCore(coreOptions));
+ const core = createCore({
+ recoveryOpen: activation.databaseAction === 'wipe-before-open',
+ onStorageResetRequired: () => {
+ fatal('cache storage requested physical reset', 'storage-reset-required');
+ },
+ onInitializationOutcome: (outcome) => {
+ initializationOpenOutcome = outcome;
+ },
+ telemetry,
+ });
+ const enginePort = {
+ postMessage(message: unknown): void {
+ if (isCacheResponse(message)) {
+ if (!message.ok && message.errorCode !== undefined) {
+ fatal('CacheWorkerCore emitted a coordinator-only cache error code');
+ return;
+ }
+ post(
+ withVersion<EngineToCoordinatorEnvelope>({
+ kind: 'engine-response',
+ ownerEpoch: activation.ownerEpoch,
+ routeId: message.id,
+ response: message,
+ })
+ );
+ return;
+ }
+ if (isCachePush(message)) {
+ post(
+ withVersion<EngineToCoordinatorEnvelope>({
+ kind: 'engine-push',
+ ownerEpoch: activation.ownerEpoch,
+ push: message,
+ })
+ );
+ return;
+ }
+ fatal('CacheWorkerCore emitted an invalid cache message');
+ },
+ };
+
+ const admitRequest = (request: CacheRequest): void => {
+ emitEvent({ kind: 'request-admitted', activation, request });
+ if (!hooks?.beforeRequest) {
+ void core.handleRequest(enginePort, request);
+ return;
+ }
+ const admission = Promise.resolve(hooks.beforeRequest(request, activation))
+ .then(async () => {
+ if (!failed) await core.handleRequest(enginePort, request);
+ })
+ .catch((error: unknown) => {
+ fatal(`engine request hook failed: ${errorMessage(error)}`);
+ });
+ pendingAdmissions.add(admission);
+ void admission.finally(() => pendingAdmissions.delete(admission));
+ };
+
+ directPort.onmessage = (event: MessageEvent<unknown>) => {
+ const parsed = validateCoordinatorToEngineEnvelope(event.data);
+ if (!parsed.ok) {
+ fatal(`invalid coordinator envelope: ${parsed.error}`);
+ return;
+ }
+ const message: CoordinatorToEngineEnvelope = parsed.value;
+ if (failed) return;
+ if (message.ownerEpoch !== activation.ownerEpoch) {
+ fatal('coordinator envelope owner epoch does not match activation');
+ return;
+ }
+ switch (message.kind) {
+ case 'engine-request':
+ if (draining) {
+ fatal('coordinator routed a request after drain began');
+ return;
+ }
+ admitRequest(message.request);
+ break;
+ case 'drain-engine':
+ if (draining) return;
+ draining = true;
+ void (async () => {
+ await Promise.all(pendingAdmissions);
+ await core.drain();
+ recordLinearMemory(true);
+ emitEvent({ kind: 'drained', activation });
+ telemetry.flush();
+ post(
+ withVersion<EngineToCoordinatorEnvelope>({
+ kind: 'engine-drained',
+ tabId: activation.tabId,
+ ownerEpoch: activation.ownerEpoch,
+ })
+ );
+ directPort.close();
+ workerScope.close();
+ })().catch((error: unknown) =>
+ fatal(`engine drain failed: ${errorMessage(error)}`)
+ );
+ break;
+ case 'heartbeat':
+ recordLinearMemory(false);
+ core.recordCachedQueueDiagnostics?.();
+ post(
+ withVersion<EngineToCoordinatorEnvelope>({
+ kind: 'heartbeat-ack',
+ ownerEpoch: activation.ownerEpoch,
+ heartbeatId: message.heartbeatId,
+ })
+ );
+ break;
+ }
+ };
+ directPort.onmessageerror = () => {
+ fatal('coordinator direct MessagePort messageerror');
+ };
+ directPort.start();
+
+ try {
+ await initializeCore(core, activation);
+ if (failed) return;
+ const ownerLockIsHeld = options.ownerLockIsHeld ?? defaultOwnerLockIsHeld;
+ if (!(await ownerLockIsHeld(activation.ownerLockName))) {
+ throw new Error('cache engine does not hold its physical owner Web Lock');
+ }
+ core.addPort(enginePort);
+ recordLinearMemory(true);
+ post(
+ withVersion<EngineToCoordinatorEnvelope>({
+ kind: 'engine-ready',
+ tabId: activation.tabId,
+ ownerEpoch: activation.ownerEpoch,
+ ownerLockName: activation.ownerLockName,
+ ownerLockHeld: true,
+ databaseActionProof: initializationOpenOutcome.startsWith('reset-')
+ ? 'wiped-before-open'
+ : 'opened-existing',
+ openOutcome: initializationOpenOutcome,
+ })
+ );
+ emitEvent({ kind: 'ready', activation });
+ telemetry.record({
+ name: 'graphql_cache.db_ready',
+ operationCategory: 'initialization',
+ outcome: 'success',
+ errorCode: 'none',
+ durationMs: now() - activationStartedAt,
+ });
+ } catch (error) {
+ telemetry.record({
+ name: 'graphql_cache.db_ready',
+ operationCategory: 'initialization',
+ outcome: 'error',
+ errorCode: classifyCacheError(error),
+ durationMs: now() - activationStartedAt,
+ });
+ telemetry.flush();
+ post(
+ withVersion<EngineToCoordinatorEnvelope>({
+ kind: 'activation-failed',
+ tabId: activation.tabId,
+ ownerEpoch: activation.ownerEpoch,
+ reason: errorMessage(error),
+ failureCode:
+ activation.databaseAction === 'wipe-before-open'
+ ? 'recovery-open-failed'
+ : 'initialization-failed',
+ })
+ );
+ }
+}
+
+/** Installs the production dedicated-worker transport around CacheWorkerCore. */
+export function installCacheEngineWorker(
+ options: CacheEngineRuntimeOptions = {}
+): void {
+ const workerScope =
+ options.scope ?? (self as unknown as DedicatedWorkerScopeLike);
+ let activated = false;
+ workerScope.onmessage = (event: MessageEvent<unknown>) => {
+ const parsed = validatePageToEngineEnvelope(event.data);
+ const directPort = event.ports[0];
+ if (!parsed.ok || event.ports.length !== 1 || !directPort || activated) {
+ for (const port of event.ports) port.close();
+ return;
+ }
+ activated = true;
+ void activate(parsed.value, directPort, workerScope, options);
+ };
+}
diff --git a/apps/web/src/lib/graphql-cache/worker/cache.coordinator.shared-worker.ts b/apps/web/src/lib/graphql-cache/worker/cache.coordinator.shared-worker.ts
new file mode 100644
index 0000000000..05dbcb7816
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/cache.coordinator.shared-worker.ts
@@ -0,0 +1,12 @@
+/// <reference lib="webworker" />
+
+import { CoordinatorRouter } from './coordinator-router';
+
+declare const self: SharedWorkerGlobalScope;
+
+const router = new CoordinatorRouter();
+
+self.onconnect = (event: MessageEvent) => {
+ const port = event.ports[0];
+ if (port) router.connect(port);
+};
diff --git a/apps/web/src/lib/graphql-cache/worker/cache.engine-worker.ts b/apps/web/src/lib/graphql-cache/worker/cache.engine-worker.ts
new file mode 100644
index 0000000000..02ae2afba8
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/cache.engine-worker.ts
@@ -0,0 +1,5 @@
+/// <reference lib="webworker" />
+
+import { installCacheEngineWorker } from './cache-engine-runtime';
+
+installCacheEngineWorker();
diff --git a/apps/web/src/lib/graphql-cache/worker/cache.shared-worker.ts b/apps/web/src/lib/graphql-cache/worker/cache.shared-worker.ts
deleted file mode 100644
index 214c08f031..0000000000
--- a/apps/web/src/lib/graphql-cache/worker/cache.shared-worker.ts
+++ /dev/null
@@ -1,31 +0,0 @@
-/**
- * SharedWorker entry: one engine shared by every tab (preferred topology).
- */
-
-import {
- type CacheNotice,
- type CacheRequest,
- isCacheNotice,
-} from '../protocol';
-import { CacheWorkerCore } from './worker-core';
-
-declare const self: SharedWorkerGlobalScope;
-
-const core = new CacheWorkerCore();
-
-self.onconnect = (event: MessageEvent) => {
- const port = event.ports[0];
- if (!port) return;
- core.addPort(port);
- port.onmessage = (msg: MessageEvent<CacheRequest | CacheNotice>) => {
- // Clients announce disconnection (dispose/pagehide) — there is no
- // platform event for it, and unpruned ports would accumulate.
- if (isCacheNotice(msg.data)) {
- core.removePort(port);
- port.close();
- return;
- }
- void core.handleRequest(port, msg.data);
- };
- port.start();
-};
diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-core.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-core.test.ts
new file mode 100644
index 0000000000..6124feb29d
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-core.test.ts
@@ -0,0 +1,342 @@
+import { describe, expect, it } from 'vitest';
+import { type CoordinatorAction, CoordinatorCore } from './coordinator-core';
+import type { DatabaseActionProof } from './coordinator-protocol';
+
+const OWNER_LOCK = 'physical-owner-lock';
+
+const action = <K extends CoordinatorAction['kind']>(
+ actions: CoordinatorAction[],
+ kind: K
+): Extract<CoordinatorAction, { kind: K }> => {
+ const found = actions.find((candidate) => candidate.kind === kind);
+ if (!found) throw new Error(`missing ${kind}`);
+ return found as Extract<CoordinatorAction, { kind: K }>;
+};
+
+const ready = (
+ core: CoordinatorCore,
+ tabId: string,
+ ownerEpoch: number,
+ databaseActionProof: DatabaseActionProof
+): CoordinatorAction[] =>
+ core.engineReady({
+ tabId,
+ ownerEpoch,
+ ownerLockName: OWNER_LOCK,
+ expectedOwnerLockName: OWNER_LOCK,
+ ownerLockHeld: true,
+ databaseActionProof,
+ openOutcome:
+ databaseActionProof === 'wiped-before-open'
+ ? 'reset-storage-uncertain'
+ : 'opened-existing',
+ });
+
+const init = (id: number) => ({ id, kind: 'init', scope: 'scope' }) as const;
+
+const clear = (id: number) => ({ id, kind: 'clear' }) as const;
+
+describe('CoordinatorCore', () => {
+ it('covers waiting, activating, active, draining, and graceful reactivation', () => {
+ const core = new CoordinatorCore('scope');
+ expect(core.state).toEqual({
+ kind: 'waiting-for-tab',
+ nextDatabaseAction: 'open-existing',
+ });
+
+ expect(core.registerTab('tab-a')).toEqual([
+ {
+ kind: 'elect-owner',
+ tabId: 'tab-a',
+ ownerEpoch: 1,
+ databaseAction: 'open-existing',
+ },
+ ]);
+ core.registerTab('tab-b');
+ core.registerTab('tab-c');
+ expect(core.snapshot()).toMatchObject({
+ state: { kind: 'activating', tabId: 'tab-a', ownerEpoch: 1 },
+ activeOwnerCount: 0,
+ tabIds: ['tab-a', 'tab-b', 'tab-c'],
+ });
+
+ core.request('tab-c', init(1));
+ expect(core.snapshot().queuedRequestCount).toBe(1);
+ const activation = ready(core, 'tab-a', 1, 'opened-existing');
+ expect(action(activation, 'route-request')).toMatchObject({
+ requesterTabId: 'tab-c',
+ ownerTabId: 'tab-a',
+ ownerEpoch: 1,
+ request: { id: 1, kind: 'init' },
+ });
+ expect(core.snapshot().activeOwnerCount).toBe(1);
+
+ expect(core.beginGracefulDeparture('tab-a', 1)).toEqual([
+ { kind: 'drain-owner', tabId: 'tab-a', ownerEpoch: 1 },
+ ]);
+ expect(core.state.kind).toBe('draining');
+ const handoff = core.engineDrained('tab-a', 1);
+ expect(action(handoff, 'retire-tab')).toEqual({
+ kind: 'retire-tab',
+ tabId: 'tab-a',
+ ownerEpoch: 1,
+ });
+ expect(action(handoff, 'elect-owner')).toEqual({
+ kind: 'elect-owner',
+ tabId: 'tab-b',
+ ownerEpoch: 2,
+ databaseAction: 'open-existing',
+ });
+ expect(ready(core, 'tab-b', 2, 'opened-existing')).toContainEqual({
+ kind: 'broadcast-engine-replaced',
+ ownerEpoch: 2,
+ });
+ });
+
+ it('rejects unregistered and retiring-tab requests', () => {
+ const core = new CoordinatorCore('scope');
+ expect(core.request('missing', clear(1))).toEqual([
+ expect.objectContaining({
+ kind: 'reject-request',
+ tabId: 'missing',
+ requestId: 1,
+ error: 'requester tab is not registered',
+ }),
+ ]);
+
+ core.registerTab('tab-a');
+ ready(core, 'tab-a', 1, 'opened-existing');
+ core.beginGracefulDeparture('tab-a', 1);
+ expect(core.request('tab-a', clear(2))).toEqual([
+ expect.objectContaining({
+ kind: 'reject-request',
+ tabId: 'tab-a',
+ requestId: 2,
+ error: 'requester tab is retiring',
+ }),
+ ]);
+ });
+
+ it('rewrites colliding per-tab request ids into unique routes and restores them', () => {
+ const core = new CoordinatorCore('scope');
+ core.registerTab('tab-a');
+ core.registerTab('tab-b');
+ core.registerTab('tab-c');
+ ready(core, 'tab-a', 1, 'opened-existing');
+
+ const first = action(core.request('tab-b', clear(7)), 'route-request');
+ const second = action(core.request('tab-c', clear(7)), 'route-request');
+ expect(first.routeId).not.toBe(second.routeId);
+ expect(first.request.id).toBe(first.routeId);
+ expect(second.request.id).toBe(second.routeId);
+
+ expect(
+ core.engineResponse(1, second.routeId, {
+ id: second.routeId,
+ ok: true,
+ result: 'second',
+ })
+ ).toEqual([
+ {
+ kind: 'deliver-response',
+ tabId: 'tab-c',
+ response: { id: 7, ok: true, result: 'second' },
+ },
+ ]);
+ expect(
+ core.engineResponse(1, first.routeId, {
+ id: first.routeId,
+ ok: true,
+ result: 'first',
+ })
+ ).toEqual([
+ {
+ kind: 'deliver-response',
+ tabId: 'tab-b',
+ response: { id: 7, ok: true, result: 'first' },
+ },
+ ]);
+ });
+
+ it('continues routing earlier responses and pushes while draining, then queues later work', () => {
+ const core = new CoordinatorCore('scope');
+ core.registerTab('tab-a');
+ core.registerTab('tab-b');
+ ready(core, 'tab-a', 1, 'opened-existing');
+ const routed = action(core.request('tab-b', clear(4)), 'route-request');
+
+ core.beginGracefulDeparture('tab-a', 1);
+ expect(core.request('tab-b', clear(5))).toEqual([]);
+ expect(core.snapshot().queuedRequestCount).toBe(1);
+ expect(core.enginePush(1, { kind: 'cache-changed' })).toEqual([
+ { kind: 'broadcast-push', push: { kind: 'cache-changed' } },
+ ]);
+ expect(
+ core.engineResponse(1, routed.routeId, {
+ id: routed.routeId,
+ ok: true,
+ result: null,
+ })
+ ).toContainEqual({
+ kind: 'deliver-response',
+ tabId: 'tab-b',
+ response: { id: 4, ok: true, result: null },
+ });
+
+ core.engineDrained('tab-a', 1);
+ const activation = ready(core, 'tab-b', 2, 'opened-existing');
+ expect(action(activation, 'route-request')).toMatchObject({
+ requesterTabId: 'tab-b',
+ ownerEpoch: 2,
+ request: { kind: 'clear' },
+ });
+ });
+
+ it('rejects old-epoch inflight work without replay and requires wipe proof', () => {
+ const core = new CoordinatorCore('scope');
+ core.registerTab('tab-a');
+ core.registerTab('tab-b');
+ ready(core, 'tab-a', 1, 'opened-existing');
+ const old = action(core.request('tab-b', clear(9)), 'route-request');
+
+ const loss = core.ownerLost('tab-a', 1, 'worker failed');
+ expect(loss).toContainEqual({
+ kind: 'reject-request',
+ tabId: 'tab-b',
+ requestId: 9,
+ error: 'owner epoch 1 was lost: worker failed',
+ errorCode: 'owner-epoch-lost',
+ });
+ expect(core.state).toEqual({
+ kind: 'resetting-after-loss',
+ previousTabId: 'tab-a',
+ previousEpoch: 1,
+ nextEpoch: 2,
+ reason: 'worker failed',
+ });
+ expect(action(core.resumeAfterLoss(), 'elect-owner')).toMatchObject({
+ tabId: 'tab-b',
+ ownerEpoch: 2,
+ databaseAction: 'wipe-before-open',
+ });
+ expect(ready(core, 'tab-b', 2, 'wiped-before-open')).toContainEqual({
+ kind: 'broadcast-engine-replaced',
+ ownerEpoch: 2,
+ });
+
+ expect(
+ core.engineResponse(1, old.routeId, {
+ id: old.routeId,
+ ok: true,
+ result: 'stale',
+ })
+ ).toEqual([
+ {
+ kind: 'drop-stale-engine-message',
+ ownerEpoch: 1,
+ routeId: old.routeId,
+ reason: 'stale-epoch',
+ },
+ ]);
+ expect(core.snapshot().staleMessageDrops).toBe(1);
+ });
+
+ it('drops unknown current routes and old-epoch pushes', () => {
+ const core = new CoordinatorCore('scope');
+ core.registerTab('tab-a');
+ ready(core, 'tab-a', 1, 'opened-existing');
+
+ expect(
+ core.engineResponse(1, 77, { id: 77, ok: true, result: null })
+ ).toContainEqual(
+ expect.objectContaining({
+ kind: 'drop-stale-engine-message',
+ reason: 'unknown-route',
+ })
+ );
+ expect(core.enginePush(0, { kind: 'cache-changed' })).toContainEqual(
+ expect.objectContaining({
+ kind: 'drop-stale-engine-message',
+ reason: 'stale-epoch',
+ })
+ );
+ });
+
+ it('uses standby liveness loss without failover and owner liveness loss with wipe', () => {
+ const core = new CoordinatorCore('scope');
+ core.registerTab('tab-a');
+ core.registerTab('tab-b');
+ core.registerTab('tab-c');
+ ready(core, 'tab-a', 1, 'opened-existing');
+
+ expect(core.tabLost('tab-c')).toEqual([
+ { kind: 'drop-tab', tabId: 'tab-c' },
+ ]);
+ expect(core.state).toEqual({
+ kind: 'active',
+ tabId: 'tab-a',
+ ownerEpoch: 1,
+ });
+ expect(core.tabLost('tab-a')).toContainEqual({
+ kind: 'schedule-reset-activation',
+ });
+ expect(action(core.resumeAfterLoss(), 'elect-owner')).toMatchObject({
+ tabId: 'tab-b',
+ ownerEpoch: 2,
+ databaseAction: 'wipe-before-open',
+ });
+ });
+
+ it('rejects wrong physical-lock and reset proofs without activating', () => {
+ const core = new CoordinatorCore('scope');
+ core.registerTab('tab-a');
+ core.registerTab('tab-b');
+
+ const wrongLock = core.engineReady({
+ tabId: 'tab-a',
+ ownerEpoch: 1,
+ ownerLockName: 'wrong',
+ expectedOwnerLockName: OWNER_LOCK,
+ ownerLockHeld: true,
+ databaseActionProof: 'opened-existing',
+ openOutcome: 'opened-existing',
+ });
+ expect(action(wrongLock, 'protocol-violation').error).toContain(
+ 'wrong physical owner lock'
+ );
+ core.resumeAfterLoss();
+ const wrongProof = core.engineReady({
+ tabId: 'tab-b',
+ ownerEpoch: 2,
+ ownerLockName: OWNER_LOCK,
+ expectedOwnerLockName: OWNER_LOCK,
+ ownerLockHeld: true,
+ databaseActionProof: 'opened-existing',
+ openOutcome: 'reset-storage-uncertain',
+ });
+ expect(action(wrongProof, 'protocol-violation').error).toContain(
+ 'does not match open outcome'
+ );
+ expect(core.snapshot().activeOwnerCount).toBe(0);
+ });
+
+ it('retains wipe-before-open while no replacement tab is available', () => {
+ const core = new CoordinatorCore('scope');
+ core.registerTab('tab-a');
+ ready(core, 'tab-a', 1, 'opened-existing');
+ core.tabLost('tab-a');
+ expect(core.resumeAfterLoss()).toEqual([]);
+ expect(core.state).toEqual({
+ kind: 'waiting-for-tab',
+ nextDatabaseAction: 'wipe-before-open',
+ });
+ expect(core.registerTab('tab-b')).toEqual([
+ {
+ kind: 'elect-owner',
+ tabId: 'tab-b',
+ ownerEpoch: 2,
+ databaseAction: 'wipe-before-open',
+ },
+ ]);
+ });
+});
diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-core.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-core.ts
new file mode 100644
index 0000000000..317d97064b
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-core.ts
@@ -0,0 +1,546 @@
+import {
+ type CachePush,
+ type CacheRequest,
+ type CacheResponse,
+ type CacheResponseErrorCode,
+ OWNER_EPOCH_LOST_ERROR_CODE,
+} from '../protocol';
+import type {
+ DatabaseAction,
+ DatabaseActionProof,
+ EngineOpenOutcome,
+ OwnerEpoch,
+ RouteId,
+} from './coordinator-protocol';
+
+export type CoordinatorState =
+ | { kind: 'waiting-for-tab'; nextDatabaseAction: DatabaseAction }
+ | {
+ kind: 'activating';
+ tabId: string;
+ ownerEpoch: OwnerEpoch;
+ databaseAction: DatabaseAction;
+ }
+ | { kind: 'active'; tabId: string; ownerEpoch: OwnerEpoch }
+ | { kind: 'draining'; tabId: string; ownerEpoch: OwnerEpoch }
+ | {
+ kind: 'resetting-after-loss';
+ previousTabId: string;
+ previousEpoch: OwnerEpoch;
+ nextEpoch: OwnerEpoch;
+ reason: string;
+ };
+
+export type CoordinatorSnapshot = {
+ scope: string;
+ state: CoordinatorState;
+ tabIds: string[];
+ ownerEpoch: OwnerEpoch;
+ queuedRequestCount: number;
+ inFlightRequestCount: number;
+ staleMessageDrops: number;
+ protocolViolations: number;
+ activeOwnerCount: 0 | 1;
+};
+
+type QueuedRequest = {
+ tabId: string;
+ request: CacheRequest;
+};
+
+type InFlightRequest = QueuedRequest & {
+ routeId: RouteId;
+ ownerEpoch: OwnerEpoch;
+};
+
+export type CoordinatorAction =
+ | {
+ kind: 'elect-owner';
+ tabId: string;
+ ownerEpoch: OwnerEpoch;
+ databaseAction: DatabaseAction;
+ }
+ | {
+ kind: 'route-request';
+ ownerTabId: string;
+ requesterTabId: string;
+ ownerEpoch: OwnerEpoch;
+ routeId: RouteId;
+ request: CacheRequest;
+ }
+ | { kind: 'deliver-response'; tabId: string; response: CacheResponse }
+ | { kind: 'broadcast-push'; push: CachePush }
+ | {
+ kind: 'reject-request';
+ tabId: string;
+ requestId: number;
+ error: string;
+ errorCode?: CacheResponseErrorCode;
+ }
+ | { kind: 'drain-owner'; tabId: string; ownerEpoch: OwnerEpoch }
+ | { kind: 'close-engine-route'; tabId: string; ownerEpoch: OwnerEpoch }
+ | { kind: 'drop-tab'; tabId: string }
+ | { kind: 'retire-tab'; tabId: string; ownerEpoch: OwnerEpoch }
+ | { kind: 'schedule-reset-activation' }
+ | { kind: 'broadcast-engine-replaced'; ownerEpoch: OwnerEpoch }
+ | {
+ kind: 'drop-stale-engine-message';
+ ownerEpoch: OwnerEpoch;
+ routeId?: RouteId;
+ reason: 'stale-epoch' | 'unknown-route' | 'inactive-engine';
+ }
+ | { kind: 'protocol-violation'; error: string };
+
+export type EngineReady = {
+ tabId: string;
+ ownerEpoch: OwnerEpoch;
+ ownerLockName: string;
+ expectedOwnerLockName: string;
+ ownerLockHeld: true;
+ databaseActionProof: DatabaseActionProof;
+ openOutcome: EngineOpenOutcome;
+};
+
+const proofFor = (outcome: EngineOpenOutcome): DatabaseActionProof =>
+ outcome.startsWith('reset-') ? 'wiped-before-open' : 'opened-existing';
+
+/** Pure election, epoch, routing, drain, and abrupt-loss state machine. */
+export class CoordinatorCore {
+ private stateValue: CoordinatorState = {
+ kind: 'waiting-for-tab',
+ nextDatabaseAction: 'open-existing',
+ };
+ private readonly tabs: string[] = [];
+ private readonly retiringTabs = new Set<string>();
+ private readonly queuedRequests: QueuedRequest[] = [];
+ private readonly inFlight = new Map<RouteId, InFlightRequest>();
+ private currentEpoch = 0;
+ private nextRouteId = 1;
+ private staleMessageDrops = 0;
+ private protocolViolations = 0;
+
+ constructor(readonly scope: string) {
+ if (scope.length === 0) throw new Error('scope must not be empty');
+ }
+
+ get state(): CoordinatorState {
+ return { ...this.stateValue };
+ }
+
+ snapshot(): CoordinatorSnapshot {
+ return {
+ scope: this.scope,
+ state: this.state,
+ tabIds: [...this.tabs],
+ ownerEpoch: this.currentEpoch,
+ queuedRequestCount: this.queuedRequests.length,
+ inFlightRequestCount: this.inFlight.size,
+ staleMessageDrops: this.staleMessageDrops,
+ protocolViolations: this.protocolViolations,
+ activeOwnerCount: this.stateValue.kind === 'active' ? 1 : 0,
+ };
+ }
+
+ registerTab(tabId: string): CoordinatorAction[] {
+ if (this.tabs.includes(tabId)) return [];
+ this.tabs.push(tabId);
+ if (this.stateValue.kind !== 'waiting-for-tab') return [];
+ return this.activateNext(this.stateValue.nextDatabaseAction);
+ }
+
+ request(tabId: string, request: CacheRequest): CoordinatorAction[] {
+ if (!this.tabs.includes(tabId)) {
+ return [
+ this.reject(tabId, request.id, 'requester tab is not registered'),
+ ];
+ }
+ if (this.retiringTabs.has(tabId)) {
+ return [this.reject(tabId, request.id, 'requester tab is retiring')];
+ }
+
+ const queued = { tabId, request };
+ if (this.stateValue.kind !== 'active') {
+ this.queuedRequests.push(queued);
+ return [];
+ }
+ return [this.route(queued, this.stateValue)];
+ }
+
+ engineReady(ready: EngineReady): CoordinatorAction[] {
+ const state = this.stateValue;
+ if (
+ state.kind !== 'activating' ||
+ state.tabId !== ready.tabId ||
+ state.ownerEpoch !== ready.ownerEpoch
+ ) {
+ return this.recordProtocolViolation(
+ `unexpected engine-ready from ${ready.tabId} at epoch ${ready.ownerEpoch}`
+ );
+ }
+
+ let error: string | undefined;
+ if (!ready.ownerLockHeld) {
+ error = 'engine became ready without the exclusive owner lock';
+ } else if (ready.ownerLockName !== ready.expectedOwnerLockName) {
+ error = 'engine reported the wrong physical owner lock';
+ } else if (ready.databaseActionProof !== proofFor(ready.openOutcome)) {
+ error = `engine proof does not match open outcome ${ready.openOutcome}`;
+ }
+ if (error) {
+ return [
+ ...this.recordProtocolViolation(error),
+ ...this.transitionToAbruptLoss(state.tabId, state.ownerEpoch, error),
+ ];
+ }
+
+ this.stateValue = {
+ kind: 'active',
+ tabId: state.tabId,
+ ownerEpoch: state.ownerEpoch,
+ };
+ const actions: CoordinatorAction[] = [];
+ if (state.ownerEpoch > 1) {
+ actions.push({
+ kind: 'broadcast-engine-replaced',
+ ownerEpoch: state.ownerEpoch,
+ });
+ }
+ while (this.queuedRequests.length > 0) {
+ const queued = this.queuedRequests.shift();
+ if (queued && this.tabs.includes(queued.tabId)) {
+ actions.push(this.route(queued, this.stateValue));
+ }
+ }
+ this.assertInvariants();
+ return actions;
+ }
+
+ engineResponse(
+ ownerEpoch: OwnerEpoch,
+ routeId: RouteId,
+ response: CacheResponse
+ ): CoordinatorAction[] {
+ if (!this.acceptsEngineMessages(ownerEpoch)) {
+ return [this.dropStale(ownerEpoch, routeId, 'stale-epoch')];
+ }
+ const request = this.inFlight.get(routeId);
+ if (!request || request.ownerEpoch !== ownerEpoch) {
+ return [this.dropStale(ownerEpoch, routeId, 'unknown-route')];
+ }
+
+ this.inFlight.delete(routeId);
+ return [
+ {
+ kind: 'deliver-response',
+ tabId: request.tabId,
+ response: { ...response, id: request.request.id },
+ },
+ ];
+ }
+
+ enginePush(ownerEpoch: OwnerEpoch, push: CachePush): CoordinatorAction[] {
+ if (!this.acceptsEngineMessages(ownerEpoch)) {
+ return [this.dropStale(ownerEpoch, undefined, 'stale-epoch')];
+ }
+ return [{ kind: 'broadcast-push', push }];
+ }
+
+ beginGracefulDeparture(
+ tabId: string,
+ ownerEpoch: OwnerEpoch
+ ): CoordinatorAction[] {
+ const state = this.stateValue;
+ if (
+ state.kind !== 'active' ||
+ state.tabId !== tabId ||
+ state.ownerEpoch !== ownerEpoch
+ ) {
+ return this.recordProtocolViolation(
+ `unexpected graceful departure from ${tabId} at epoch ${ownerEpoch}`
+ );
+ }
+ this.retiringTabs.add(tabId);
+ this.stateValue = { kind: 'draining', tabId, ownerEpoch };
+ return [{ kind: 'drain-owner', tabId, ownerEpoch }];
+ }
+
+ engineDrained(tabId: string, ownerEpoch: OwnerEpoch): CoordinatorAction[] {
+ const state = this.stateValue;
+ if (
+ state.kind !== 'draining' ||
+ state.tabId !== tabId ||
+ state.ownerEpoch !== ownerEpoch
+ ) {
+ return this.recordProtocolViolation(
+ `unexpected engine-drained from ${tabId} at epoch ${ownerEpoch}`
+ );
+ }
+
+ const actions = this.rejectEpochRequests(
+ ownerEpoch,
+ 'engine drained before delivering its response'
+ );
+ this.removeTabRecord(tabId);
+ this.retiringTabs.delete(tabId);
+ actions.push(
+ { kind: 'close-engine-route', tabId, ownerEpoch },
+ { kind: 'retire-tab', tabId, ownerEpoch }
+ );
+ this.stateValue = {
+ kind: 'waiting-for-tab',
+ nextDatabaseAction: 'open-existing',
+ };
+ actions.push(...this.activateNext('open-existing'));
+ this.assertInvariants();
+ return actions;
+ }
+
+ ownerLost(
+ tabId: string,
+ ownerEpoch: OwnerEpoch,
+ reason: string
+ ): CoordinatorAction[] {
+ return this.transitionToAbruptLoss(tabId, ownerEpoch, reason);
+ }
+
+ tabLost(
+ tabId: string,
+ reason = 'tab liveness lock was released'
+ ): CoordinatorAction[] {
+ if (!this.tabs.includes(tabId)) return [];
+ const state = this.stateValue;
+ const wasOwner =
+ (state.kind === 'active' ||
+ state.kind === 'activating' ||
+ state.kind === 'draining') &&
+ state.tabId === tabId;
+
+ const actions: CoordinatorAction[] = [{ kind: 'drop-tab', tabId }];
+ if (wasOwner) {
+ actions.push(
+ ...this.transitionToAbruptLoss(tabId, state.ownerEpoch, reason)
+ );
+ }
+ this.removeTabRecord(tabId);
+ this.retiringTabs.delete(tabId);
+ this.assertInvariants();
+ return actions;
+ }
+
+ resumeAfterLoss(): CoordinatorAction[] {
+ const state = this.stateValue;
+ if (state.kind !== 'resetting-after-loss') return [];
+ const candidate = this.chooseCandidate(state.previousTabId);
+ if (!candidate) {
+ this.stateValue = {
+ kind: 'waiting-for-tab',
+ nextDatabaseAction: 'wipe-before-open',
+ };
+ return [];
+ }
+ this.currentEpoch = state.nextEpoch;
+ this.stateValue = {
+ kind: 'activating',
+ tabId: candidate,
+ ownerEpoch: state.nextEpoch,
+ databaseAction: 'wipe-before-open',
+ };
+ return [
+ {
+ kind: 'elect-owner',
+ tabId: candidate,
+ ownerEpoch: state.nextEpoch,
+ databaseAction: 'wipe-before-open',
+ },
+ ];
+ }
+
+ expectsEngine(tabId: string, ownerEpoch: OwnerEpoch): boolean {
+ return (
+ this.stateValue.kind === 'activating' &&
+ this.stateValue.tabId === tabId &&
+ this.stateValue.ownerEpoch === ownerEpoch
+ );
+ }
+
+ private transitionToAbruptLoss(
+ tabId: string,
+ ownerEpoch: OwnerEpoch,
+ reason: string
+ ): CoordinatorAction[] {
+ const state = this.stateValue;
+ if (
+ (state.kind !== 'active' &&
+ state.kind !== 'activating' &&
+ state.kind !== 'draining') ||
+ state.tabId !== tabId ||
+ state.ownerEpoch !== ownerEpoch
+ ) {
+ return [];
+ }
+
+ const actions = this.rejectEpochRequests(
+ ownerEpoch,
+ `owner epoch ${ownerEpoch} was lost: ${reason}`,
+ OWNER_EPOCH_LOST_ERROR_CODE
+ );
+ actions.push(
+ { kind: 'close-engine-route', tabId, ownerEpoch },
+ { kind: 'schedule-reset-activation' }
+ );
+ this.stateValue = {
+ kind: 'resetting-after-loss',
+ previousTabId: tabId,
+ previousEpoch: ownerEpoch,
+ nextEpoch: this.currentEpoch + 1,
+ reason,
+ };
+ this.assertInvariants();
+ return actions;
+ }
+
+ private rejectEpochRequests(
+ ownerEpoch: OwnerEpoch,
+ error: string,
+ errorCode?: CacheResponseErrorCode
+ ): CoordinatorAction[] {
+ const actions: CoordinatorAction[] = [];
+ for (const [routeId, request] of this.inFlight) {
+ if (request.ownerEpoch !== ownerEpoch) continue;
+ this.inFlight.delete(routeId);
+ actions.push(
+ this.reject(request.tabId, request.request.id, error, errorCode)
+ );
+ }
+ return actions;
+ }
+
+ private activateNext(databaseAction: DatabaseAction): CoordinatorAction[] {
+ const candidate = this.chooseCandidate();
+ if (!candidate) {
+ this.stateValue = {
+ kind: 'waiting-for-tab',
+ nextDatabaseAction: databaseAction,
+ };
+ return [];
+ }
+ this.currentEpoch += 1;
+ this.stateValue = {
+ kind: 'activating',
+ tabId: candidate,
+ ownerEpoch: this.currentEpoch,
+ databaseAction,
+ };
+ return [
+ {
+ kind: 'elect-owner',
+ tabId: candidate,
+ ownerEpoch: this.currentEpoch,
+ databaseAction,
+ },
+ ];
+ }
+
+ private chooseCandidate(avoid?: string): string | undefined {
+ const eligible = this.tabs.filter((tabId) => !this.retiringTabs.has(tabId));
+ return eligible.find((tabId) => tabId !== avoid) ?? eligible[0];
+ }
+
+ private route(
+ queued: QueuedRequest,
+ state: Extract<CoordinatorState, { kind: 'active' }>
+ ): Extract<CoordinatorAction, { kind: 'route-request' }> {
+ if (!Number.isSafeInteger(this.nextRouteId)) {
+ throw new Error('coordinator route id space exhausted');
+ }
+ const routeId = this.nextRouteId++;
+ this.inFlight.set(routeId, {
+ ...queued,
+ routeId,
+ ownerEpoch: state.ownerEpoch,
+ });
+ return {
+ kind: 'route-request',
+ ownerTabId: state.tabId,
+ requesterTabId: queued.tabId,
+ ownerEpoch: state.ownerEpoch,
+ routeId,
+ request: { ...queued.request, id: routeId },
+ };
+ }
+
+ private removeTabRecord(tabId: string): void {
+ const index = this.tabs.indexOf(tabId);
+ if (index >= 0) this.tabs.splice(index, 1);
+ for (let index = this.queuedRequests.length - 1; index >= 0; index -= 1) {
+ if (this.queuedRequests[index]?.tabId === tabId) {
+ this.queuedRequests.splice(index, 1);
+ }
+ }
+ for (const [routeId, request] of this.inFlight) {
+ if (request.tabId === tabId) this.inFlight.delete(routeId);
+ }
+ }
+
+ private acceptsEngineMessages(ownerEpoch: OwnerEpoch): boolean {
+ return (
+ (this.stateValue.kind === 'active' ||
+ this.stateValue.kind === 'draining') &&
+ this.stateValue.ownerEpoch === ownerEpoch
+ );
+ }
+
+ private reject(
+ tabId: string,
+ requestId: number,
+ error: string,
+ errorCode?: CacheResponseErrorCode
+ ): Extract<CoordinatorAction, { kind: 'reject-request' }> {
+ return {
+ kind: 'reject-request',
+ tabId,
+ requestId,
+ error,
+ ...(errorCode === undefined ? {} : { errorCode }),
+ };
+ }
+
+ private dropStale(
+ ownerEpoch: OwnerEpoch,
+ routeId: RouteId | undefined,
+ reason: Extract<
+ CoordinatorAction,
+ { kind: 'drop-stale-engine-message' }
+ >['reason']
+ ): Extract<CoordinatorAction, { kind: 'drop-stale-engine-message' }> {
+ this.staleMessageDrops += 1;
+ return {
+ kind: 'drop-stale-engine-message',
+ ownerEpoch,
+ routeId,
+ reason,
+ };
+ }
+
+ private recordProtocolViolation(error: string): CoordinatorAction[] {
+ this.protocolViolations += 1;
+ return [{ kind: 'protocol-violation', error }];
+ }
+
+ private assertInvariants(): void {
+ if (
+ this.stateValue.kind !== 'active' &&
+ this.stateValue.kind !== 'draining'
+ ) {
+ if (this.inFlight.size > 0) {
+ throw new Error('invariant: requests are in flight without an owner');
+ }
+ return;
+ }
+ for (const request of this.inFlight.values()) {
+ if (request.ownerEpoch !== this.stateValue.ownerEpoch) {
+ throw new Error('invariant: in-flight request has a stale owner epoch');
+ }
+ }
+ }
+}
diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.test.ts
new file mode 100644
index 0000000000..e2ab0ca6c4
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.test.ts
@@ -0,0 +1,838 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+ createCacheCoordinatorPageAdapter,
+ type DedicatedWorkerLike,
+ type SharedWorkerLike,
+} from './coordinator-page-adapter';
+import { CACHE_COORDINATOR_PROTOCOL_VERSION } from './coordinator-protocol';
+
+class FakeCoordinatorPort {
+ readonly messages: Array<{ message: unknown; transfer: Transferable[] }> = [];
+ onmessage: ((event: MessageEvent<unknown>) => void) | null = null;
+ onmessageerror: (() => void) | null = null;
+ closed = false;
+ readonly events: string[] = [];
+ readonly throwKinds = new Set<string>();
+
+ postMessage(message: unknown, transfer: Transferable[] = []): void {
+ const kind = String((message as { kind?: unknown }).kind);
+ this.events.push(`post:${kind}`);
+ if (this.throwKinds.has(kind)) throw new Error(`${kind} send failed`);
+ this.messages.push({ message, transfer });
+ }
+
+ start(): void {}
+
+ close(): void {
+ this.closed = true;
+ this.events.push('close');
+ }
+
+ receive(message: unknown): void {
+ this.onmessage?.({ data: message } as MessageEvent);
+ }
+}
+
+class FakeTransferPort {
+ onmessage = null;
+ onmessageerror = null;
+ closed = false;
+ postMessage(): void {}
+ start(): void {}
+ close(): void {
+ this.closed = true;
+ }
+}
+
+class FakeMessageChannel {
+ static readonly instances: FakeMessageChannel[] = [];
+ port1 = new FakeTransferPort();
+ port2 = new FakeTransferPort();
+
+ constructor() {
+ FakeMessageChannel.instances.push(this);
+ }
+}
+
+class FakeWorker implements DedicatedWorkerLike {
+ onerror: DedicatedWorkerLike['onerror'] = null;
+ onmessageerror: DedicatedWorkerLike['onmessageerror'] = null;
+ readonly messages: Array<{ message: unknown; transfer: Transferable[] }> = [];
+ terminated = false;
+ throwOnPost = false;
+
+ postMessage(message: unknown, transfer: Transferable[]): void {
+ if (this.throwOnPost) throw new Error('activate-engine send failed');
+ this.messages.push({ message, transfer });
+ }
+
+ terminate(): void {
+ this.terminated = true;
+ }
+}
+
+const version = {
+ coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION,
+} as const;
+
+const heldLockManager = (events: string[] = []) =>
+ ({
+ request: vi.fn(
+ async (
+ name: string,
+ _options: LockOptions,
+ callback: (lock: Lock | null) => unknown
+ ) => {
+ events.push(`lock:${name}`);
+ return await callback({ name, mode: 'exclusive' } as Lock);
+ }
+ ),
+ }) as unknown as Pick<LockManager, 'request'>;
+
+const election = (ownerEpoch: number) => ({
+ ...version,
+ kind: 'become-owner',
+ scope: 'scope',
+ tabId: 'tab-a',
+ ownerEpoch,
+ databaseAction:
+ ownerEpoch === 1
+ ? ('open-existing' as const)
+ : ('wipe-before-open' as const),
+ ownerLockName: 'physical-lock',
+});
+
+describe('CacheCoordinatorPageAdapter', () => {
+ beforeEach(() => {
+ FakeMessageChannel.instances.length = 0;
+ vi.stubGlobal('MessageChannel', FakeMessageChannel);
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ vi.unstubAllGlobals();
+ vi.restoreAllMocks();
+ });
+
+ it('is construction-safe, creates SharedWorker on first use, and DedicatedWorker only on election', async () => {
+ const events: string[] = [];
+ const coordinatorPort = new FakeCoordinatorPort();
+ const sharedFactory = vi.fn(() => {
+ events.push('shared-worker');
+ return { port: coordinatorPort as unknown as MessagePort };
+ });
+ const dedicatedFactory = vi.fn(() => new FakeWorker());
+ const adapter = createCacheCoordinatorPageAdapter({
+ scope: 'scope',
+ tabId: 'tab-a',
+ lockManager: heldLockManager(events),
+ createSharedWorker: sharedFactory,
+ createDedicatedWorker: dedicatedFactory,
+ });
+
+ expect(events).toEqual([]);
+ expect(sharedFactory).not.toHaveBeenCalled();
+ expect(dedicatedFactory).not.toHaveBeenCalled();
+
+ adapter.postMessage({ id: 1, kind: 'clear' });
+ await vi.waitFor(() => expect(sharedFactory).toHaveBeenCalledOnce());
+ expect(events).toEqual([
+ 'lock:graphql-cache-tab:scope:tab-a',
+ 'shared-worker',
+ ]);
+ expect(dedicatedFactory).not.toHaveBeenCalled();
+ expect(
+ (coordinatorPort.messages[0]!.message as { kind?: string }).kind
+ ).toBe('register-tab');
+
+ coordinatorPort.receive({ ...version, kind: 'registered', tabId: 'tab-a' });
+ expect(
+ coordinatorPort.messages.some(
+ ({ message }) => (message as { kind?: string }).kind === 'cache-request'
+ )
+ ).toBe(true);
+ expect(dedicatedFactory).not.toHaveBeenCalled();
+
+ coordinatorPort.receive(election(1));
+ expect(dedicatedFactory).toHaveBeenCalledOnce();
+ const attach = coordinatorPort.messages.find(
+ ({ message }) =>
+ (message as { kind?: string }).kind === 'attach-engine-port'
+ );
+ expect(attach?.transfer).toHaveLength(1);
+ });
+
+ it('terminates and clears a failed worker before reporting owner loss', async () => {
+ const order: string[] = [];
+ const coordinatorPort = new FakeCoordinatorPort();
+ const worker = new FakeWorker();
+ worker.terminate = () => {
+ worker.terminated = true;
+ order.push('terminated');
+ };
+ coordinatorPort.postMessage = (message, transfer = []) => {
+ coordinatorPort.messages.push({ message, transfer });
+ if ((message as { kind?: string }).kind === 'engine-lost') {
+ order.push('loss-reported');
+ }
+ };
+ const adapter = createCacheCoordinatorPageAdapter({
+ scope: 'scope',
+ tabId: 'tab-a',
+ lockManager: heldLockManager(),
+ createSharedWorker: () => ({
+ port: coordinatorPort as unknown as MessagePort,
+ }),
+ createDedicatedWorker: () => worker,
+ });
+ const started = adapter.start();
+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));
+ coordinatorPort.receive({ ...version, kind: 'registered', tabId: 'tab-a' });
+ await started;
+ coordinatorPort.receive(election(1));
+
+ worker.onerror?.call(
+ {} as AbstractWorker,
+ {
+ message: 'worker crashed',
+ preventDefault: vi.fn(),
+ } as unknown as ErrorEvent
+ );
+
+ expect(order).toEqual(['terminated', 'loss-reported']);
+ expect(worker.terminated).toBe(true);
+ expect(coordinatorPort.messages).toContainEqual(
+ expect.objectContaining({
+ message: expect.objectContaining({
+ kind: 'engine-lost',
+ ownerEpoch: 1,
+ reason: 'worker crashed',
+ }),
+ })
+ );
+ });
+
+ it('accepts same-page replacement only after the failed worker was cleared', async () => {
+ const coordinatorPort = new FakeCoordinatorPort();
+ const workers = [new FakeWorker(), new FakeWorker()];
+ const dedicatedFactory = vi.fn(() => workers.shift() as FakeWorker);
+ const adapter = createCacheCoordinatorPageAdapter({
+ scope: 'scope',
+ tabId: 'tab-a',
+ lockManager: heldLockManager(),
+ createSharedWorker: () => ({
+ port: coordinatorPort as unknown as MessagePort,
+ }),
+ createDedicatedWorker: dedicatedFactory,
+ });
+ const started = adapter.start();
+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));
+ coordinatorPort.receive({ ...version, kind: 'registered', tabId: 'tab-a' });
+ await started;
+ coordinatorPort.receive(election(1));
+ coordinatorPort.receive({
+ ...version,
+ kind: 'terminate-engine',
+ tabId: 'tab-a',
+ ownerEpoch: 1,
+ reason: 'heartbeat timeout',
+ });
+ coordinatorPort.receive(election(2));
+
+ expect(dedicatedFactory).toHaveBeenCalledTimes(2);
+ });
+
+ it('forwards validated cache messages and closes on malformed envelopes', async () => {
+ const coordinatorPort = new FakeCoordinatorPort();
+ const terminalErrors: string[] = [];
+ const adapter = createCacheCoordinatorPageAdapter({
+ scope: 'scope',
+ tabId: 'tab-a',
+ lockManager: heldLockManager(),
+ createSharedWorker: () => ({
+ port: coordinatorPort as unknown as MessagePort,
+ }),
+ createDedicatedWorker: () => new FakeWorker(),
+ onTerminalError: (error) => terminalErrors.push(error.message),
+ });
+ const messages: unknown[] = [];
+ adapter.onmessage = (event) => messages.push(event.data);
+ const started = adapter.start();
+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));
+ coordinatorPort.receive({ ...version, kind: 'registered', tabId: 'tab-a' });
+ await started;
+
+ coordinatorPort.receive({
+ ...version,
+ kind: 'cache-message',
+ message: { id: 8, ok: true, result: 'ok' },
+ });
+ coordinatorPort.receive({
+ ...version,
+ kind: 'cache-message',
+ message: { id: 'bad', ok: true, result: 'ignored' },
+ });
+
+ expect(messages).toEqual([{ id: 8, ok: true, result: 'ok' }]);
+ expect(terminalErrors).toEqual([
+ 'invalid cache-message coordinator envelope',
+ ]);
+ expect(coordinatorPort.closed).toBe(true);
+ });
+
+ it('settles queued RPC and does not retry construction after startup fails', async () => {
+ const sharedFactory = vi.fn(() => {
+ throw new Error('coordinator construction failed');
+ });
+ const terminalErrors: string[] = [];
+ const messages: unknown[] = [];
+ const adapter = createCacheCoordinatorPageAdapter({
+ scope: 'scope',
+ tabId: 'tab-a',
+ lockManager: heldLockManager(),
+ createSharedWorker: sharedFactory,
+ createDedicatedWorker: () => new FakeWorker(),
+ onTerminalError: (error) => terminalErrors.push(error.message),
+ });
+ adapter.onmessage = (event) => messages.push(event.data);
+
+ adapter.postMessage({ id: 1, kind: 'clear' });
+ await vi.waitFor(() => expect(messages).toHaveLength(1));
+ adapter.postMessage({ id: 2, kind: 'clear' });
+
+ expect(sharedFactory).toHaveBeenCalledOnce();
+ expect(messages).toEqual([
+ { id: 1, ok: false, error: 'coordinator construction failed' },
+ { id: 2, ok: false, error: 'page adapter is closed' },
+ ]);
+ expect(terminalErrors).toEqual(['coordinator construction failed']);
+ });
+
+ it('keeps registered coordinator protocol diagnostics advisory', async () => {
+ const coordinatorPort = new FakeCoordinatorPort();
+ const protocolErrors: string[] = [];
+ const terminalErrors: string[] = [];
+ const adapter = createCacheCoordinatorPageAdapter({
+ scope: 'scope',
+ tabId: 'tab-a',
+ lockManager: heldLockManager(),
+ createSharedWorker: () => ({
+ port: coordinatorPort as unknown as MessagePort,
+ }),
+ createDedicatedWorker: () => new FakeWorker(),
+ onProtocolError: (error) => protocolErrors.push(error.message),
+ onTerminalError: (error) => terminalErrors.push(error.message),
+ });
+ const started = adapter.start();
+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));
+ coordinatorPort.receive({ ...version, kind: 'registered', tabId: 'tab-a' });
+ await started;
+
+ coordinatorPort.receive({
+ ...version,
+ kind: 'protocol-error',
+ error: 'another tab sent a stale envelope',
+ });
+
+ expect(protocolErrors).toEqual(['another tab sent a stale envelope']);
+ expect(terminalErrors).toEqual([]);
+ expect(coordinatorPort.closed).toBe(false);
+ await adapter.dispose();
+ });
+
+ it('terminates an owned engine before closing a failed SharedWorker transport', async () => {
+ const order: string[] = [];
+ const coordinatorPort = new FakeCoordinatorPort();
+ coordinatorPort.close = () => {
+ coordinatorPort.closed = true;
+ order.push('coordinator-closed');
+ };
+ const sharedWorker: SharedWorkerLike = {
+ port: coordinatorPort as unknown as MessagePort,
+ onerror: null,
+ };
+ const worker = new FakeWorker();
+ worker.terminate = () => {
+ worker.terminated = true;
+ order.push('engine-terminated');
+ };
+ const terminalErrors: string[] = [];
+ const livenessReleased = vi.fn();
+ const lockManager = {
+ request: vi.fn(
+ async (
+ name: string,
+ _options: LockOptions,
+ callback: (lock: Lock | null) => unknown
+ ) => {
+ await callback({ name, mode: 'exclusive' } as Lock);
+ livenessReleased();
+ }
+ ),
+ } as unknown as Pick<LockManager, 'request'>;
+ const adapter = createCacheCoordinatorPageAdapter({
+ scope: 'scope',
+ tabId: 'tab-a',
+ lockManager,
+ createSharedWorker: () => sharedWorker,
+ createDedicatedWorker: () => worker,
+ onTerminalError: (error) => {
+ terminalErrors.push(error.message);
+ order.push('terminal-reported');
+ },
+ });
+ const started = adapter.start();
+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));
+ coordinatorPort.receive({ ...version, kind: 'registered', tabId: 'tab-a' });
+ await started;
+ coordinatorPort.receive(election(1));
+
+ sharedWorker.onerror?.call(
+ {} as AbstractWorker,
+ {
+ message: 'SharedWorker crashed',
+ preventDefault: vi.fn(),
+ } as unknown as ErrorEvent
+ );
+
+ expect(order).toEqual([
+ 'engine-terminated',
+ 'coordinator-closed',
+ 'terminal-reported',
+ ]);
+ expect(terminalErrors).toEqual(['SharedWorker crashed']);
+ await vi.waitFor(() => expect(livenessReleased).toHaveBeenCalledOnce());
+ });
+
+ it('closes a standby transport on MessagePort messageerror exactly once', async () => {
+ const coordinatorPort = new FakeCoordinatorPort();
+ const terminalErrors: string[] = [];
+ const dedicatedFactory = vi.fn(() => new FakeWorker());
+ const adapter = createCacheCoordinatorPageAdapter({
+ scope: 'scope',
+ tabId: 'tab-a',
+ lockManager: heldLockManager(),
+ createSharedWorker: () => ({
+ port: coordinatorPort as unknown as MessagePort,
+ }),
+ createDedicatedWorker: dedicatedFactory,
+ onTerminalError: (error) => terminalErrors.push(error.message),
+ });
+ const started = adapter.start();
+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));
+ coordinatorPort.receive({ ...version, kind: 'registered', tabId: 'tab-a' });
+ await started;
+
+ coordinatorPort.onmessageerror?.();
+ coordinatorPort.onmessageerror?.();
+
+ expect(dedicatedFactory).not.toHaveBeenCalled();
+ expect(coordinatorPort.closed).toBe(true);
+ expect(terminalErrors).toEqual(['coordinator MessagePort messageerror']);
+ });
+
+ it.each(['register-tab', 'cache-request'] as const)(
+ 'terminal-fails exactly once when %s send throws',
+ async (throwKind) => {
+ const coordinatorPort = new FakeCoordinatorPort();
+ coordinatorPort.throwKinds.add(throwKind);
+ const terminalErrors: string[] = [];
+ const adapter = createCacheCoordinatorPageAdapter({
+ scope: 'scope',
+ tabId: 'tab-a',
+ lockManager: heldLockManager(),
+ createSharedWorker: () => ({
+ port: coordinatorPort as unknown as MessagePort,
+ }),
+ createDedicatedWorker: () => new FakeWorker(),
+ onTerminalError: (error) => terminalErrors.push(error.message),
+ });
+ const messages: unknown[] = [];
+ adapter.onmessage = (event) => messages.push(event.data);
+
+ if (throwKind === 'cache-request') {
+ const started = adapter.start();
+ await vi.waitFor(() =>
+ expect(coordinatorPort.messages).toHaveLength(1)
+ );
+ coordinatorPort.receive({
+ ...version,
+ kind: 'registered',
+ tabId: 'tab-a',
+ });
+ await started;
+ adapter.postMessage({ id: 1, kind: 'clear' });
+ } else {
+ adapter.postMessage({ id: 1, kind: 'clear' });
+ await expect(adapter.start()).rejects.toThrow(
+ 'register-tab send failed'
+ );
+ expect(messages).toEqual([
+ { id: 1, ok: false, error: 'register-tab send failed' },
+ ]);
+ }
+
+ await vi.waitFor(() => expect(terminalErrors).toHaveLength(1));
+ coordinatorPort.onmessageerror?.();
+ expect(terminalErrors).toEqual([`${throwKind} send failed`]);
+ expect(coordinatorPort.closed).toBe(true);
+ await adapter.dispose();
+ }
+ );
+
+ it.each(['attach-engine-port', 'activate-engine'] as const)(
+ 'closes untransferred channels and the worker when %s send throws',
+ async (throwKind) => {
+ const coordinatorPort = new FakeCoordinatorPort();
+ const worker = new FakeWorker();
+ if (throwKind === 'attach-engine-port') {
+ coordinatorPort.throwKinds.add(throwKind);
+ } else {
+ worker.throwOnPost = true;
+ }
+ const terminalErrors: string[] = [];
+ const adapter = createCacheCoordinatorPageAdapter({
+ scope: 'scope',
+ tabId: 'tab-a',
+ lockManager: heldLockManager(),
+ createSharedWorker: () => ({
+ port: coordinatorPort as unknown as MessagePort,
+ }),
+ createDedicatedWorker: () => worker,
+ onTerminalError: (error) => terminalErrors.push(error.message),
+ });
+ const started = adapter.start();
+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));
+ coordinatorPort.receive({
+ ...version,
+ kind: 'registered',
+ tabId: 'tab-a',
+ });
+ await started;
+ coordinatorPort.receive(election(1));
+
+ await vi.waitFor(() => expect(terminalErrors).toHaveLength(1));
+ const channel = FakeMessageChannel.instances[0];
+ expect(worker.terminated).toBe(true);
+ expect(channel?.port2.closed).toBe(true);
+ expect(channel?.port1.closed).toBe(throwKind === 'attach-engine-port');
+ expect(coordinatorPort.closed).toBe(true);
+ expect(terminalErrors[0]).toContain(`${throwKind} send failed`);
+ }
+ );
+
+ it('terminal-fails after terminating an engine when owner-loss reporting throws', async () => {
+ const coordinatorPort = new FakeCoordinatorPort();
+ coordinatorPort.throwKinds.add('engine-lost');
+ const worker = new FakeWorker();
+ const terminalErrors: string[] = [];
+ const adapter = createCacheCoordinatorPageAdapter({
+ scope: 'scope',
+ tabId: 'tab-a',
+ lockManager: heldLockManager(),
+ createSharedWorker: () => ({
+ port: coordinatorPort as unknown as MessagePort,
+ }),
+ createDedicatedWorker: () => worker,
+ onTerminalError: (error) => terminalErrors.push(error.message),
+ });
+ const started = adapter.start();
+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));
+ coordinatorPort.receive({ ...version, kind: 'registered', tabId: 'tab-a' });
+ await started;
+ coordinatorPort.receive(election(1));
+
+ worker.onerror?.call(
+ {} as AbstractWorker,
+ {
+ message: 'engine crashed',
+ preventDefault: vi.fn(),
+ } as unknown as ErrorEvent
+ );
+
+ expect(worker.terminated).toBe(true);
+ expect(coordinatorPort.closed).toBe(true);
+ expect(terminalErrors).toEqual(['engine-lost send failed']);
+ });
+
+ it.each([
+ { graceful: true, throwKind: 'graceful-departure' },
+ { graceful: false, throwKind: 'disconnect-tab' },
+ ])(
+ 'settles $graceful disposal when $throwKind send throws',
+ async ({ graceful, throwKind }) => {
+ const coordinatorPort = new FakeCoordinatorPort();
+ const worker = new FakeWorker();
+ const terminalErrors: string[] = [];
+ const adapter = createCacheCoordinatorPageAdapter({
+ scope: 'scope',
+ tabId: 'tab-a',
+ lockManager: heldLockManager(),
+ createSharedWorker: () => ({
+ port: coordinatorPort as unknown as MessagePort,
+ }),
+ createDedicatedWorker: () => worker,
+ onTerminalError: (error) => terminalErrors.push(error.message),
+ });
+ const started = adapter.start();
+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));
+ coordinatorPort.receive({
+ ...version,
+ kind: 'registered',
+ tabId: 'tab-a',
+ });
+ await started;
+ coordinatorPort.receive(election(1));
+ coordinatorPort.throwKinds.add(throwKind);
+
+ await adapter.dispose({ graceful });
+
+ expect(worker.terminated).toBe(true);
+ expect(coordinatorPort.closed).toBe(true);
+ expect(terminalErrors).toEqual([`${throwKind} send failed`]);
+ }
+ );
+
+ it('settles graceful timeout when disconnect reporting throws', async () => {
+ vi.useFakeTimers();
+ const coordinatorPort = new FakeCoordinatorPort();
+ const worker = new FakeWorker();
+ const terminalErrors: string[] = [];
+ const adapter = createCacheCoordinatorPageAdapter({
+ scope: 'scope',
+ tabId: 'tab-a',
+ lockManager: heldLockManager(),
+ createSharedWorker: () => ({
+ port: coordinatorPort as unknown as MessagePort,
+ }),
+ createDedicatedWorker: () => worker,
+ gracefulTimeoutMs: 10,
+ onTerminalError: (error) => terminalErrors.push(error.message),
+ });
+ const started = adapter.start();
+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));
+ coordinatorPort.receive({ ...version, kind: 'registered', tabId: 'tab-a' });
+ await started;
+ coordinatorPort.receive(election(1));
+ coordinatorPort.throwKinds.add('disconnect-tab');
+
+ const disposed = adapter.dispose({ graceful: true });
+ await vi.advanceTimersByTimeAsync(11);
+ await disposed;
+
+ expect(worker.terminated).toBe(true);
+ expect(coordinatorPort.closed).toBe(true);
+ expect(terminalErrors).toEqual(['disconnect-tab send failed']);
+ });
+
+ it('rejects startup and queued RPC when disposed during lock acquisition', async () => {
+ let allowLock!: () => void;
+ const lockGate = new Promise<void>((resolve) => {
+ allowLock = resolve;
+ });
+ const terminalErrors: string[] = [];
+ const messages: unknown[] = [];
+ const lockManager = {
+ request: vi.fn(
+ async (
+ name: string,
+ _options: LockOptions,
+ callback: (lock: Lock | null) => unknown
+ ) => {
+ await lockGate;
+ await callback({ name, mode: 'exclusive' } as Lock);
+ throw new Error('late lock-manager rejection');
+ }
+ ),
+ } as unknown as Pick<LockManager, 'request'>;
+ const adapter = createCacheCoordinatorPageAdapter({
+ scope: 'scope',
+ tabId: 'tab-a',
+ lockManager,
+ createSharedWorker: vi.fn(),
+ createDedicatedWorker: () => new FakeWorker(),
+ onTerminalError: (error) => terminalErrors.push(error.message),
+ });
+ adapter.onmessage = (event) => messages.push(event.data);
+ adapter.postMessage({ id: 1, kind: 'clear' });
+ const started = adapter.start();
+
+ await adapter.dispose();
+ await expect(started).rejects.toThrow(
+ 'page adapter was disposed during startup'
+ );
+ expect(messages).toEqual([
+ {
+ id: 1,
+ ok: false,
+ error: 'page adapter was disposed during startup',
+ },
+ ]);
+ allowLock();
+ await Promise.resolve();
+ await Promise.resolve();
+
+ expect(terminalErrors).toEqual([]);
+ await expect(adapter.start()).rejects.toThrow('page adapter is closed');
+ });
+
+ it('rejects stale elections and deduplicates replacement epochs monotonically', async () => {
+ const coordinatorPort = new FakeCoordinatorPort();
+ const firstWorker = new FakeWorker();
+ const workers = [firstWorker, new FakeWorker()];
+ const dedicatedFactory = vi.fn(() => workers.shift() as FakeWorker);
+ const replacements: number[] = [];
+ const terminalErrors: string[] = [];
+ const adapter = createCacheCoordinatorPageAdapter({
+ scope: 'scope',
+ tabId: 'tab-a',
+ lockManager: heldLockManager(),
+ createSharedWorker: () => ({
+ port: coordinatorPort as unknown as MessagePort,
+ }),
+ createDedicatedWorker: dedicatedFactory,
+ onEngineReplaced: (epoch) => replacements.push(epoch),
+ onTerminalError: (error) => terminalErrors.push(error.message),
+ });
+ const started = adapter.start();
+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));
+ coordinatorPort.receive({ ...version, kind: 'registered', tabId: 'tab-a' });
+ await started;
+ coordinatorPort.receive(election(1));
+ coordinatorPort.receive({
+ ...version,
+ kind: 'engine-replaced',
+ ownerEpoch: 1,
+ });
+ coordinatorPort.receive({
+ ...version,
+ kind: 'engine-replaced',
+ ownerEpoch: 1,
+ });
+ coordinatorPort.receive({
+ ...version,
+ kind: 'terminate-engine',
+ tabId: 'tab-a',
+ ownerEpoch: 1,
+ reason: 'lost',
+ });
+ coordinatorPort.receive(election(1));
+
+ expect(replacements).toEqual([1]);
+ expect(dedicatedFactory).toHaveBeenCalledOnce();
+ expect(firstWorker.messages).toHaveLength(1);
+ expect(firstWorker.messages[0]?.message).toMatchObject({
+ kind: 'activate-engine',
+ ownerEpoch: 1,
+ });
+ expect(workers).toHaveLength(1);
+ expect(coordinatorPort.closed).toBe(true);
+ expect(terminalErrors).toEqual([
+ 'coordinator elected stale or duplicate owner epoch 1',
+ ]);
+ });
+
+ it('escalates an owner graceful drain to abrupt disposal on pagehide', async () => {
+ const coordinatorPort = new FakeCoordinatorPort();
+ const worker = new FakeWorker();
+ const adapter = createCacheCoordinatorPageAdapter({
+ scope: 'scope',
+ tabId: 'tab-a',
+ lockManager: heldLockManager(),
+ createSharedWorker: () => ({
+ port: coordinatorPort as unknown as MessagePort,
+ }),
+ createDedicatedWorker: () => worker,
+ });
+ const started = adapter.start();
+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));
+ coordinatorPort.receive({ ...version, kind: 'registered', tabId: 'tab-a' });
+ await started;
+ coordinatorPort.receive(election(1));
+
+ const graceful = adapter.dispose({ graceful: true });
+ expect(worker.terminated).toBe(false);
+ const abrupt = adapter.dispose({ graceful: false });
+ expect(abrupt).toBe(graceful);
+ await abrupt;
+
+ expect(worker.terminated).toBe(true);
+ expect(coordinatorPort.closed).toBe(true);
+ expect(
+ coordinatorPort.events.filter((event) => event === 'post:disconnect-tab')
+ ).toHaveLength(1);
+ });
+
+ it('terminal-fails when the owned engine crashes during graceful drain', async () => {
+ const coordinatorPort = new FakeCoordinatorPort();
+ const worker = new FakeWorker();
+ const terminalErrors: string[] = [];
+ const adapter = createCacheCoordinatorPageAdapter({
+ scope: 'scope',
+ tabId: 'tab-a',
+ lockManager: heldLockManager(),
+ createSharedWorker: () => ({
+ port: coordinatorPort as unknown as MessagePort,
+ }),
+ createDedicatedWorker: () => worker,
+ onTerminalError: (error) => terminalErrors.push(error.message),
+ });
+ const started = adapter.start();
+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));
+ coordinatorPort.receive({ ...version, kind: 'registered', tabId: 'tab-a' });
+ await started;
+ coordinatorPort.receive(election(1));
+
+ const disposed = adapter.dispose({ graceful: true });
+ worker.onerror?.call(
+ {} as AbstractWorker,
+ {
+ message: 'engine failed while draining',
+ preventDefault: vi.fn(),
+ } as unknown as ErrorEvent
+ );
+ await disposed;
+
+ expect(worker.terminated).toBe(true);
+ expect(coordinatorPort.closed).toBe(true);
+ expect(terminalErrors).toEqual(['engine failed while draining']);
+ });
+
+ it('keeps the worker alive through graceful drain and terminates after retire-complete', async () => {
+ vi.useFakeTimers();
+ const coordinatorPort = new FakeCoordinatorPort();
+ const worker = new FakeWorker();
+ const adapter = createCacheCoordinatorPageAdapter({
+ scope: 'scope',
+ tabId: 'tab-a',
+ lockManager: heldLockManager(),
+ createSharedWorker: () => ({
+ port: coordinatorPort as unknown as MessagePort,
+ }),
+ createDedicatedWorker: () => worker,
+ });
+ const started = adapter.start();
+ await vi.waitFor(() => expect(coordinatorPort.messages).toHaveLength(1));
+ coordinatorPort.receive({ ...version, kind: 'registered', tabId: 'tab-a' });
+ await started;
+ coordinatorPort.receive(election(1));
+
+ const disposed = adapter.dispose({ graceful: true });
+ expect(worker.terminated).toBe(false);
+ expect(coordinatorPort.messages).toContainEqual(
+ expect.objectContaining({
+ message: expect.objectContaining({ kind: 'graceful-departure' }),
+ })
+ );
+ coordinatorPort.receive({
+ ...version,
+ kind: 'retire-complete',
+ tabId: 'tab-a',
+ ownerEpoch: 1,
+ });
+ await disposed;
+
+ expect(worker.terminated).toBe(true);
+ expect(coordinatorPort.closed).toBe(true);
+ });
+});
diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.ts
new file mode 100644
index 0000000000..7e5b36de67
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.ts
@@ -0,0 +1,747 @@
+import type { CacheRequest, WorkerMessage } from '../protocol';
+import {
+ type CacheTelemetryRecorderLike,
+ classifyCacheError,
+ isolateCacheTelemetry,
+} from '../telemetry';
+import {
+ CACHE_COORDINATOR_PROTOCOL_VERSION,
+ type CoordinatorToTabEnvelope,
+ isCacheRequest,
+ type PageToEngineEnvelope,
+ type TabToCoordinatorEnvelope,
+ tabLivenessLockName,
+ validateCoordinatorToTabEnvelope,
+} from './coordinator-protocol';
+
+export interface SharedWorkerLike {
+ readonly port: MessagePort;
+ onerror?: ((this: AbstractWorker, event: ErrorEvent) => unknown) | null;
+}
+
+export interface DedicatedWorkerLike {
+ onerror: ((this: AbstractWorker, event: ErrorEvent) => unknown) | null;
+ onmessageerror: ((this: Worker, event: MessageEvent) => unknown) | null;
+ postMessage(message: unknown, transfer: Transferable[]): void;
+ terminate(): void;
+}
+
+export interface CacheCoordinatorPageAdapterOptions {
+ scope: string;
+ hotCapacity?: number;
+ tabId?: string;
+ createSharedWorker?: (scope: string) => SharedWorkerLike;
+ createDedicatedWorker?: (
+ scope: string,
+ ownerEpoch: number
+ ) => DedicatedWorkerLike;
+ lockManager?: Pick<LockManager, 'request'>;
+ onEngineReplaced?: (ownerEpoch: number) => void;
+ onOwnerChanged?: (ownerEpoch: number | undefined) => void;
+ onWorkerCreated?: (worker: DedicatedWorkerLike, ownerEpoch: number) => void;
+ onWorkerTerminated?: (ownerEpoch: number, reason: string) => void;
+ /** Advisory coordinator diagnostic after successful registration. */
+ onProtocolError?: (error: Error) => void;
+ /** Fatal SharedWorker/MessagePort/envelope failure after resources close. */
+ onTerminalError?: (error: Error) => void;
+ gracefulTimeoutMs?: number;
+ /** Privacy-safe lifecycle recorder supplied by the browser host. */
+ telemetry?: CacheTelemetryRecorderLike;
+}
+
+export interface PageAdapterDisposeOptions {
+ graceful?: boolean;
+}
+
+const DEFAULT_GRACEFUL_TIMEOUT_MS = 10_000;
+
+const withVersion = <T extends { coordinatorVersion: 1 }>(
+ value: T extends unknown ? Omit<T, 'coordinatorVersion'> : never
+): T =>
+ ({
+ coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION,
+ ...value,
+ }) as unknown as T;
+
+const defaultSharedWorkerFactory = (scope: string): SharedWorkerLike =>
+ new SharedWorker(
+ new URL('./cache.coordinator.shared-worker.ts', import.meta.url),
+ { type: 'module', name: `graphql-cache-coordinator:${scope}` }
+ );
+
+const defaultDedicatedWorkerFactory = (
+ scope: string,
+ ownerEpoch: number
+): DedicatedWorkerLike =>
+ new Worker(new URL('./cache.engine-worker.ts', import.meta.url), {
+ type: 'module',
+ name: `graphql-cache-engine:${scope}:${ownerEpoch}`,
+ });
+
+/**
+ * Import-safe page endpoint for the browser coordinator topology.
+ * SharedWorker creation starts on first use; DedicatedWorker creation starts
+ * only after a current-epoch election.
+ */
+export class CacheCoordinatorPageAdapter {
+ readonly tabId: string;
+ onmessage: ((event: MessageEvent<WorkerMessage>) => void) | null = null;
+
+ private readonly createSharedWorker: (scope: string) => SharedWorkerLike;
+ private readonly createDedicatedWorker: (
+ scope: string,
+ ownerEpoch: number
+ ) => DedicatedWorkerLike;
+ private readonly lockManager: Pick<LockManager, 'request'> | undefined;
+ private readonly gracefulTimeoutMs: number;
+ private sharedWorker: SharedWorkerLike | undefined;
+ private engineWorker: DedicatedWorkerLike | undefined;
+ private ownerEpoch: number | undefined;
+ private registered = false;
+ private startPromise: Promise<void> | undefined;
+ private resolveRegistration: (() => void) | undefined;
+ private rejectRegistration: ((error: Error) => void) | undefined;
+ private readonly queuedRequests: CacheRequest[] = [];
+ private releaseLivenessLock: (() => void) | undefined;
+ private disposePromise: Promise<void> | undefined;
+ private resolveDispose: (() => void) | undefined;
+ private gracefulTimeout: ReturnType<typeof setTimeout> | undefined;
+ private disposeMode: 'graceful' | 'abrupt' | undefined;
+ private pagehideRegistered = false;
+ private terminalErrorReported = false;
+ private readonly terminatedOwnerEpochs = new Set<number>();
+ private highestOwnerEpochSeen = 0;
+ private latestEngineReplacedEpoch = 0;
+ private closed = false;
+ private readonly telemetry: CacheTelemetryRecorderLike;
+ private readonly now = (): number =>
+ globalThis.performance?.now() ?? Date.now();
+
+ constructor(private readonly options: CacheCoordinatorPageAdapterOptions) {
+ if (!options.scope) throw new Error('cache coordinator scope is required');
+ if (
+ options.hotCapacity !== undefined &&
+ (!Number.isSafeInteger(options.hotCapacity) || options.hotCapacity <= 0)
+ ) {
+ throw new Error('hot capacity must be a positive integer');
+ }
+ this.tabId = options.tabId ?? crypto.randomUUID();
+ this.createSharedWorker =
+ options.createSharedWorker ?? defaultSharedWorkerFactory;
+ this.createDedicatedWorker =
+ options.createDedicatedWorker ?? defaultDedicatedWorkerFactory;
+ this.lockManager = options.lockManager;
+ this.gracefulTimeoutMs =
+ options.gracefulTimeoutMs ?? DEFAULT_GRACEFUL_TIMEOUT_MS;
+ this.telemetry = isolateCacheTelemetry(options.telemetry);
+ }
+
+ /** Acquires tab liveness and registers without constructing an engine. */
+ start(): Promise<void> {
+ if (this.closed) return Promise.reject(new Error('page adapter is closed'));
+ if (this.startPromise) return this.startPromise;
+ this.startPromise = new Promise<void>((resolve, reject) => {
+ this.resolveRegistration = resolve;
+ this.rejectRegistration = reject;
+ });
+ void this.connect().catch((error: unknown) => {
+ // Explicit disposal can settle start while lock acquisition is pending.
+ // A later lock-manager rejection belongs to that closed attempt.
+ if (this.closed) return;
+ this.failTerminal(
+ error instanceof Error ? error : new Error(String(error))
+ );
+ });
+ return this.startPromise;
+ }
+
+ /** Queues unchanged cache RPC until registration and engine readiness. */
+ postMessage(request: CacheRequest): void {
+ if (!isCacheRequest(request)) {
+ const error = new Error('invalid cache request');
+ this.options.onProtocolError?.(error);
+ if (
+ typeof (request as { id?: unknown })?.id === 'number' &&
+ Number.isSafeInteger((request as { id: number }).id)
+ ) {
+ this.emit({
+ id: (request as { id: number }).id,
+ ok: false,
+ error: error.message,
+ });
+ }
+ return;
+ }
+ if (this.closed) {
+ this.emit({ id: request.id, ok: false, error: 'page adapter is closed' });
+ return;
+ }
+ if (!this.registered) {
+ this.queuedRequests.push(request);
+ void this.start().catch(() => undefined);
+ return;
+ }
+ this.postCoordinator(
+ withVersion<TabToCoordinatorEnvelope>({
+ kind: 'cache-request',
+ tabId: this.tabId,
+ request,
+ })
+ );
+ }
+
+ /** Gracefully drains an owned engine, or immediately drops a standby tab. */
+ dispose(options: PageAdapterDisposeOptions = {}): Promise<void> {
+ const graceful = options.graceful === true;
+ if (this.disposePromise) {
+ if (!graceful && this.disposeMode === 'graceful' && !this.closed) {
+ this.disposeMode = 'abrupt';
+ this.abortDispose('pagehide interrupted graceful page disposal');
+ }
+ return this.disposePromise;
+ }
+ this.disposePromise = new Promise<void>((resolve) => {
+ this.resolveDispose = resolve;
+ });
+ if (this.closed) {
+ this.settleDispose();
+ return this.disposePromise;
+ }
+ if (!this.sharedWorker) {
+ this.disposeMode = 'abrupt';
+ this.closed = true;
+ this.registered = false;
+ const error = new Error('page adapter was disposed during startup');
+ this.rejectStartAndQueued(error);
+ this.releaseLiveness();
+ this.settleDispose();
+ return this.disposePromise;
+ }
+
+ if (graceful && this.ownerEpoch !== undefined) {
+ this.disposeMode = 'graceful';
+ const ownerEpoch = this.ownerEpoch;
+ if (
+ !this.postCoordinator(
+ withVersion<TabToCoordinatorEnvelope>({
+ kind: 'graceful-departure',
+ tabId: this.tabId,
+ ownerEpoch,
+ })
+ )
+ ) {
+ return this.disposePromise;
+ }
+ this.gracefulTimeout = setTimeout(() => {
+ this.gracefulTimeout = undefined;
+ if (this.closed) return;
+ this.terminateEngine(ownerEpoch, 'graceful drain timed out', false);
+ if (this.closed) return;
+ this.postCoordinator(
+ withVersion<TabToCoordinatorEnvelope>({
+ kind: 'disconnect-tab',
+ tabId: this.tabId,
+ reason: 'graceful page disposal timed out',
+ })
+ );
+ if (!this.closed) {
+ this.failTerminal(new Error('graceful engine drain timed out'));
+ }
+ }, this.gracefulTimeoutMs);
+ } else {
+ this.disposeMode = 'abrupt';
+ this.abortDispose('page disposed without graceful drain');
+ }
+ return this.disposePromise;
+ }
+
+ private abortDispose(reason: string): void {
+ this.clearGracefulTimeout();
+ if (this.ownerEpoch !== undefined) {
+ this.terminateEngine(this.ownerEpoch, reason, false);
+ }
+ if (!this.closed) {
+ this.postCoordinator(
+ withVersion<TabToCoordinatorEnvelope>({
+ kind: 'disconnect-tab',
+ tabId: this.tabId,
+ reason,
+ })
+ );
+ }
+ this.finishDispose();
+ }
+
+ private async connect(): Promise<void> {
+ const lockManager = this.lockManager ?? navigator.locks;
+ if (
+ typeof SharedWorker !== 'function' &&
+ this.options.createSharedWorker === undefined
+ ) {
+ throw new Error('SharedWorker is unavailable');
+ }
+ if (
+ typeof Worker !== 'function' &&
+ this.options.createDedicatedWorker === undefined
+ ) {
+ throw new Error('DedicatedWorker is unavailable');
+ }
+ if (typeof MessageChannel !== 'function') {
+ throw new Error('MessageChannel is unavailable');
+ }
+ if (!lockManager) throw new Error('Web Locks are unavailable');
+
+ const livenessLockName = tabLivenessLockName(
+ this.options.scope,
+ this.tabId
+ );
+ const lockStartedAt = this.now();
+ let acquired: (() => void) | undefined;
+ let acquisitionFailed: ((error: Error) => void) | undefined;
+ const acquiredPromise = new Promise<void>((resolve, reject) => {
+ acquired = resolve;
+ acquisitionFailed = reject;
+ });
+ const heldUntilReleased = new Promise<void>((resolve) => {
+ this.releaseLivenessLock = resolve;
+ });
+ void lockManager
+ .request(livenessLockName, { mode: 'exclusive' }, async (lock) => {
+ if (!lock) {
+ acquisitionFailed?.(new Error('tab liveness lock was not acquired'));
+ return;
+ }
+ acquired?.();
+ await heldUntilReleased;
+ })
+ .catch((error: unknown) => {
+ acquisitionFailed?.(
+ error instanceof Error ? error : new Error(String(error))
+ );
+ });
+ try {
+ await acquiredPromise;
+ } catch (error) {
+ this.telemetry.record({
+ name: 'graphql_cache.lock_wait',
+ operationCategory: 'lifecycle',
+ outcome: 'error',
+ errorCode: classifyCacheError(error),
+ durationMs: this.now() - lockStartedAt,
+ });
+ throw error;
+ }
+ this.telemetry.record({
+ name: 'graphql_cache.lock_wait',
+ operationCategory: 'lifecycle',
+ outcome: 'success',
+ errorCode: 'none',
+ durationMs: this.now() - lockStartedAt,
+ });
+ if (this.closed) return;
+
+ const worker = this.createSharedWorker(this.options.scope);
+ this.sharedWorker = worker;
+ worker.onerror = (event) => {
+ event.preventDefault();
+ this.failTerminal(
+ new Error(event.message || 'SharedWorker transport error')
+ );
+ };
+ worker.port.onmessage = (event: MessageEvent<unknown>) => {
+ const transferredPorts = event.ports ?? [];
+ if (transferredPorts.length > 0) {
+ for (const port of transferredPorts) this.closePort(port);
+ this.failTerminal(
+ new Error('coordinator envelope transferred an unexpected port')
+ );
+ return;
+ }
+ try {
+ this.handleCoordinatorMessage(event.data);
+ } catch (error) {
+ this.failTerminal(
+ error instanceof Error ? error : new Error(String(error))
+ );
+ }
+ };
+ worker.port.onmessageerror = () => {
+ this.failTerminal(new Error('coordinator MessagePort messageerror'));
+ };
+ worker.port.start();
+ this.postCoordinator(
+ withVersion<TabToCoordinatorEnvelope>({
+ kind: 'register-tab',
+ scope: this.options.scope,
+ tabId: this.tabId,
+ livenessLockName,
+ hotCapacity: this.options.hotCapacity,
+ })
+ );
+ }
+
+ private handleCoordinatorMessage(rawMessage: unknown): void {
+ const parsed = validateCoordinatorToTabEnvelope(rawMessage);
+ if (!parsed.ok) {
+ this.failTerminal(new Error(parsed.error));
+ return;
+ }
+ const message = parsed.value;
+ switch (message.kind) {
+ case 'registered':
+ if (message.tabId !== this.tabId || this.registered) {
+ this.failTerminal(
+ new Error('invalid coordinator registration acknowledgement')
+ );
+ return;
+ }
+ this.registered = true;
+ this.resolveRegistration?.();
+ this.resolveRegistration = undefined;
+ this.rejectRegistration = undefined;
+ this.registerPagehide();
+ for (const request of this.queuedRequests.splice(0)) {
+ this.postMessage(request);
+ }
+ break;
+ case 'become-owner':
+ if (
+ message.tabId !== this.tabId ||
+ message.scope !== this.options.scope
+ ) {
+ this.failTerminal(
+ new Error('coordinator elected the wrong page or scope')
+ );
+ return;
+ }
+ if (
+ message.ownerEpoch <= this.highestOwnerEpochSeen ||
+ this.terminatedOwnerEpochs.has(message.ownerEpoch)
+ ) {
+ this.failTerminal(
+ new Error(
+ `coordinator elected stale or duplicate owner epoch ${message.ownerEpoch}`
+ )
+ );
+ return;
+ }
+ this.highestOwnerEpochSeen = message.ownerEpoch;
+ this.spawnEngine(message);
+ break;
+ case 'cache-message':
+ this.emit(message.message);
+ break;
+ case 'terminate-engine':
+ if (message.tabId !== this.tabId) {
+ this.failTerminal(new Error('coordinator terminated the wrong page'));
+ return;
+ }
+ if (
+ !this.terminateEngine(message.ownerEpoch, message.reason, false) &&
+ !this.terminatedOwnerEpochs.has(message.ownerEpoch)
+ ) {
+ this.failTerminal(
+ new Error('coordinator terminated an unknown owner epoch')
+ );
+ }
+ break;
+ case 'retire-complete':
+ if (
+ message.tabId !== this.tabId ||
+ !this.terminateEngine(
+ message.ownerEpoch,
+ 'graceful engine retirement completed',
+ false
+ )
+ ) {
+ this.failTerminal(
+ new Error('coordinator retired the wrong page or owner epoch')
+ );
+ return;
+ }
+ this.finishDispose();
+ break;
+ case 'engine-replaced':
+ if (message.ownerEpoch <= this.latestEngineReplacedEpoch) return;
+ this.latestEngineReplacedEpoch = message.ownerEpoch;
+ this.highestOwnerEpochSeen = Math.max(
+ this.highestOwnerEpochSeen,
+ message.ownerEpoch
+ );
+ this.options.onEngineReplaced?.(message.ownerEpoch);
+ break;
+ case 'protocol-error': {
+ const error = new Error(message.error);
+ if (!this.registered) this.failTerminal(error);
+ else this.options.onProtocolError?.(error);
+ break;
+ }
+ }
+ }
+
+ private spawnEngine(
+ election: Extract<CoordinatorToTabEnvelope, { kind: 'become-owner' }>
+ ): void {
+ if (this.engineWorker || this.ownerEpoch !== undefined) {
+ this.failTerminal(
+ new Error('coordinator elected a page that already owns an engine')
+ );
+ return;
+ }
+ const worker = this.createDedicatedWorker(
+ this.options.scope,
+ election.ownerEpoch
+ );
+ this.engineWorker = worker;
+ this.ownerEpoch = election.ownerEpoch;
+ this.options.onOwnerChanged?.(election.ownerEpoch);
+ this.options.onWorkerCreated?.(worker, election.ownerEpoch);
+
+ worker.onerror = (event) => {
+ event.preventDefault();
+ const reason = event.message || 'dedicated engine worker error';
+ const failedDuringDrain = this.disposeMode === 'graceful';
+ this.terminateEngine(election.ownerEpoch, reason, !failedDuringDrain);
+ if (failedDuringDrain && !this.closed) {
+ this.failTerminal(new Error(reason));
+ }
+ };
+ worker.onmessageerror = () => {
+ const reason = 'dedicated engine worker messageerror';
+ const failedDuringDrain = this.disposeMode === 'graceful';
+ this.terminateEngine(election.ownerEpoch, reason, !failedDuringDrain);
+ if (failedDuringDrain && !this.closed) {
+ this.failTerminal(new Error(reason));
+ }
+ };
+
+ const directChannel = new MessageChannel();
+ if (
+ !this.postCoordinator(
+ withVersion<TabToCoordinatorEnvelope>({
+ kind: 'attach-engine-port',
+ tabId: this.tabId,
+ ownerEpoch: election.ownerEpoch,
+ }),
+ [directChannel.port1],
+ [directChannel.port1]
+ )
+ ) {
+ this.closePort(directChannel.port2);
+ return;
+ }
+ try {
+ worker.postMessage(
+ withVersion<PageToEngineEnvelope>({
+ kind: 'activate-engine',
+ scope: election.scope,
+ tabId: this.tabId,
+ ownerEpoch: election.ownerEpoch,
+ databaseAction: election.databaseAction,
+ ownerLockName: election.ownerLockName,
+ hotCapacity: election.hotCapacity,
+ }),
+ [directChannel.port2]
+ );
+ } catch (error) {
+ this.closePort(directChannel.port2);
+ this.failTerminal(
+ error instanceof Error ? error : new Error(String(error))
+ );
+ }
+ }
+
+ private terminateEngine(
+ ownerEpoch: number,
+ reason: string,
+ reportLoss: boolean
+ ): boolean {
+ if (!this.engineWorker || this.ownerEpoch !== ownerEpoch) return false;
+ const worker = this.engineWorker;
+ let cleanupError: Error | undefined;
+ try {
+ worker.onerror = null;
+ } catch (error) {
+ cleanupError = error instanceof Error ? error : new Error(String(error));
+ }
+ try {
+ worker.onmessageerror = null;
+ } catch (error) {
+ cleanupError ??=
+ error instanceof Error ? error : new Error(String(error));
+ }
+ try {
+ worker.terminate();
+ } catch (error) {
+ cleanupError ??=
+ error instanceof Error ? error : new Error(String(error));
+ }
+ this.terminatedOwnerEpochs.add(ownerEpoch);
+ this.engineWorker = undefined;
+ this.ownerEpoch = undefined;
+ try {
+ this.options.onOwnerChanged?.(undefined);
+ this.options.onWorkerTerminated?.(ownerEpoch, reason);
+ } catch (error) {
+ cleanupError ??=
+ error instanceof Error ? error : new Error(String(error));
+ }
+ if (cleanupError) {
+ this.failTerminal(cleanupError);
+ } else if (reportLoss && this.sharedWorker && !this.closed) {
+ this.postCoordinator(
+ withVersion<TabToCoordinatorEnvelope>({
+ kind: 'engine-lost',
+ tabId: this.tabId,
+ ownerEpoch,
+ reason,
+ })
+ );
+ }
+ return true;
+ }
+
+ private emit(message: WorkerMessage): void {
+ this.onmessage?.({ data: message } as MessageEvent<WorkerMessage>);
+ }
+
+ private postCoordinator(
+ message: TabToCoordinatorEnvelope,
+ transfer: Transferable[] = [],
+ untransferredPorts: MessagePort[] = []
+ ): boolean {
+ const port = this.sharedWorker?.port;
+ if (!port) {
+ for (const untransferredPort of untransferredPorts) {
+ this.closePort(untransferredPort);
+ }
+ if (!this.closed) {
+ this.failTerminal(new Error('coordinator MessagePort is unavailable'));
+ }
+ return false;
+ }
+ try {
+ port.postMessage(message, transfer);
+ return true;
+ } catch (error) {
+ for (const untransferredPort of untransferredPorts) {
+ this.closePort(untransferredPort);
+ }
+ this.failTerminal(
+ error instanceof Error ? error : new Error(String(error))
+ );
+ return false;
+ }
+ }
+
+ private registerPagehide(): void {
+ if (this.pagehideRegistered || typeof addEventListener !== 'function') {
+ return;
+ }
+ this.pagehideRegistered = true;
+ addEventListener(
+ 'pagehide',
+ () => {
+ void this.dispose({ graceful: false });
+ },
+ { once: true }
+ );
+ }
+
+ private failTerminal(error: Error): void {
+ if (this.terminalErrorReported) return;
+ this.terminalErrorReported = true;
+ this.closed = true;
+ this.registered = false;
+ this.clearGracefulTimeout();
+ if (this.ownerEpoch !== undefined) {
+ this.terminateEngine(this.ownerEpoch, error.message, false);
+ }
+ this.closeCoordinatorPort();
+ this.releaseLiveness();
+ this.rejectStartAndQueued(error);
+ this.settleDispose();
+ try {
+ this.options.onTerminalError?.(error);
+ } catch {
+ // Terminal cleanup is complete; observers cannot reopen the transport.
+ }
+ }
+
+ private finishDispose(): void {
+ this.closed = true;
+ this.registered = false;
+ this.clearGracefulTimeout();
+ this.closeCoordinatorPort();
+ this.releaseLiveness();
+ this.rejectStartAndQueued(new Error('page adapter was disposed'));
+ this.settleDispose();
+ }
+
+ private rejectStartAndQueued(error: Error): void {
+ this.rejectRegistration?.(error);
+ this.rejectRegistration = undefined;
+ this.resolveRegistration = undefined;
+ for (const request of this.queuedRequests.splice(0)) {
+ try {
+ this.emit({ id: request.id, ok: false, error: error.message });
+ } catch {
+ // One consumer callback cannot prevent settlement of later requests.
+ }
+ }
+ }
+
+ private closeCoordinatorPort(): void {
+ const worker = this.sharedWorker;
+ this.sharedWorker = undefined;
+ if (!worker) return;
+ try {
+ worker.onerror = null;
+ } catch {
+ // Continue closing the port even if a test double rejects detachment.
+ }
+ try {
+ worker.port.onmessage = null;
+ worker.port.onmessageerror = null;
+ } catch {
+ // Continue closing even if a test double rejects handler detachment.
+ }
+ this.closePort(worker.port);
+ }
+
+ private closePort(port: Pick<MessagePort, 'close'>): void {
+ try {
+ port.close();
+ } catch {
+ // Closing is best-effort after ownership has already been abandoned.
+ }
+ }
+
+ private clearGracefulTimeout(): void {
+ if (this.gracefulTimeout === undefined) return;
+ clearTimeout(this.gracefulTimeout);
+ this.gracefulTimeout = undefined;
+ }
+
+ private settleDispose(): void {
+ this.resolveDispose?.();
+ this.resolveDispose = undefined;
+ }
+
+ private releaseLiveness(): void {
+ const release = this.releaseLivenessLock;
+ this.releaseLivenessLock = undefined;
+ try {
+ release?.();
+ } catch {
+ // Promise resolvers do not throw, but cleanup must remain exception-safe.
+ }
+ }
+}
+
+/** Creates a lazy, import-safe page coordinator endpoint. */
+export function createCacheCoordinatorPageAdapter(
+ options: CacheCoordinatorPageAdapterOptions
+): CacheCoordinatorPageAdapter {
+ return new CacheCoordinatorPageAdapter(options);
+}
diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts
new file mode 100644
index 0000000000..4996822461
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts
@@ -0,0 +1,277 @@
+import { describe, expect, it } from 'vitest';
+import {
+ CACHE_COORDINATOR_PROTOCOL_VERSION,
+ databaseOwnerLockName,
+ isCachePush,
+ isCacheRequest,
+ isCacheResponse,
+ validateCoordinatorToEngineEnvelope,
+ validateCoordinatorToTabEnvelope,
+ validateEngineToCoordinatorEnvelope,
+ validatePageToEngineEnvelope,
+ validateTabToCoordinatorEnvelope,
+} from './coordinator-protocol';
+
+const version = {
+ coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION,
+} as const;
+
+describe('coordinator runtime protocol', () => {
+ it('validates unchanged cache RPC and rejects unknown fields or kinds', () => {
+ expect(isCacheRequest({ id: 0, kind: 'clear' })).toBe(true);
+ expect(isCacheRequest({ id: 1, kind: 'read', query: '{ x }' })).toBe(true);
+ expect(isCacheRequest({ id: 1, kind: 'clear', surprise: true })).toBe(
+ false
+ );
+ expect(isCacheRequest({ id: 1, kind: 'future-kind' })).toBe(false);
+ expect(isCacheResponse({ id: 3, ok: true, result: undefined })).toBe(true);
+ expect(isCacheResponse({ id: 3, ok: false, error: 'failed' })).toBe(true);
+ expect(
+ isCacheResponse({
+ id: 3,
+ ok: false,
+ error: 'failed',
+ errorCode: 'owner-epoch-lost',
+ })
+ ).toBe(true);
+ expect(
+ isCacheResponse({
+ id: 3,
+ ok: false,
+ error: 'failed',
+ errorCode: 'future-code',
+ })
+ ).toBe(false);
+ expect(isCacheResponse({ id: 3, ok: false, error: 4 })).toBe(false);
+ expect(isCachePush({ kind: 'cache-changed' })).toBe(true);
+ expect(
+ isCachePush({
+ kind: 'mutation-settled',
+ settlement: { transactionId: '1', status: 'committed' },
+ })
+ ).toBe(true);
+ });
+
+ it.each([
+ {
+ ...version,
+ kind: 'register-tab',
+ scope: 'scope',
+ tabId: 'tab',
+ livenessLockName: 'graphql-cache-tab:scope:tab',
+ },
+ {
+ ...version,
+ kind: 'cache-request',
+ tabId: 'tab',
+ request: { id: 1, kind: 'clear' },
+ },
+ {
+ ...version,
+ kind: 'attach-engine-port',
+ tabId: 'tab',
+ ownerEpoch: 1,
+ },
+ {
+ ...version,
+ kind: 'graceful-departure',
+ tabId: 'tab',
+ ownerEpoch: 1,
+ },
+ {
+ ...version,
+ kind: 'engine-lost',
+ tabId: 'tab',
+ ownerEpoch: 1,
+ reason: 'failed',
+ },
+ {
+ ...version,
+ kind: 'disconnect-tab',
+ tabId: 'tab',
+ reason: 'closed',
+ },
+ ])('accepts tab envelope $kind', (message) => {
+ expect(validateTabToCoordinatorEnvelope(message)).toEqual({
+ ok: true,
+ value: message,
+ });
+ });
+
+ it.each([
+ { ...version, kind: 'registered', tabId: 'tab' },
+ {
+ ...version,
+ kind: 'become-owner',
+ scope: 'scope',
+ tabId: 'tab',
+ ownerEpoch: 1,
+ databaseAction: 'open-existing',
+ ownerLockName: 'owner-lock',
+ },
+ {
+ ...version,
+ kind: 'cache-message',
+ message: { id: 1, ok: true, result: null },
+ },
+ {
+ ...version,
+ kind: 'terminate-engine',
+ tabId: 'tab',
+ ownerEpoch: 1,
+ reason: 'failed',
+ },
+ {
+ ...version,
+ kind: 'retire-complete',
+ tabId: 'tab',
+ ownerEpoch: 1,
+ },
+ { ...version, kind: 'engine-replaced', ownerEpoch: 2 },
+ { ...version, kind: 'protocol-error', error: 'bad envelope' },
+ ])('accepts coordinator-to-tab envelope $kind', (message) => {
+ expect(validateCoordinatorToTabEnvelope(message).ok).toBe(true);
+ });
+
+ it('validates activation and both direct-port directions', () => {
+ expect(
+ validatePageToEngineEnvelope({
+ ...version,
+ kind: 'activate-engine',
+ scope: 'scope',
+ tabId: 'tab',
+ ownerEpoch: 1,
+ databaseAction: 'wipe-before-open',
+ ownerLockName: 'owner-lock',
+ }).ok
+ ).toBe(true);
+ expect(
+ validateCoordinatorToEngineEnvelope({
+ ...version,
+ kind: 'engine-request',
+ ownerEpoch: 1,
+ routeId: 7,
+ request: { id: 7, kind: 'clear' },
+ }).ok
+ ).toBe(true);
+ expect(
+ validateCoordinatorToEngineEnvelope({
+ ...version,
+ kind: 'engine-request',
+ ownerEpoch: 1,
+ routeId: 7,
+ request: { id: 6, kind: 'clear' },
+ }).ok
+ ).toBe(false);
+ expect(
+ validateEngineToCoordinatorEnvelope({
+ ...version,
+ kind: 'engine-ready',
+ tabId: 'tab',
+ ownerEpoch: 1,
+ ownerLockName: 'owner-lock',
+ ownerLockHeld: true,
+ databaseActionProof: 'wiped-before-open',
+ openOutcome: 'reset-storage-uncertain',
+ }).ok
+ ).toBe(true);
+ expect(
+ validateEngineToCoordinatorEnvelope({
+ ...version,
+ kind: 'engine-ready',
+ tabId: 'tab',
+ ownerEpoch: 1,
+ ownerLockName: 'owner-lock',
+ ownerLockHeld: false,
+ databaseActionProof: 'wiped-before-open',
+ openOutcome: 'reset-storage-uncertain',
+ }).ok
+ ).toBe(false);
+ expect(
+ validateEngineToCoordinatorEnvelope({
+ ...version,
+ kind: 'engine-fatal',
+ tabId: 'tab',
+ ownerEpoch: 1,
+ reason: 'reset',
+ fatalCode: 'storage-reset-required',
+ }).ok
+ ).toBe(true);
+ expect(
+ validateEngineToCoordinatorEnvelope({
+ ...version,
+ kind: 'activation-failed',
+ tabId: 'tab',
+ ownerEpoch: 1,
+ reason: 'open failed',
+ failureCode: 'recovery-open-failed',
+ }).ok
+ ).toBe(true);
+ expect(
+ validateEngineToCoordinatorEnvelope({
+ ...version,
+ kind: 'engine-response',
+ ownerEpoch: 1,
+ routeId: 7,
+ response: {
+ id: 7,
+ ok: false,
+ error: 'forged topology loss',
+ errorCode: 'owner-epoch-lost',
+ },
+ }).ok
+ ).toBe(false);
+ });
+
+ it('rejects missing versions, non-positive epochs, extra fields, and malformed nested payloads', () => {
+ expect(
+ validateTabToCoordinatorEnvelope({
+ kind: 'register-tab',
+ scope: 'scope',
+ tabId: 'tab',
+ livenessLockName: 'lock',
+ }).ok
+ ).toBe(false);
+ expect(
+ validateCoordinatorToTabEnvelope({
+ ...version,
+ kind: 'engine-replaced',
+ ownerEpoch: 0,
+ }).ok
+ ).toBe(false);
+ expect(
+ validateCoordinatorToTabEnvelope({
+ coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION + 1,
+ kind: 'engine-replaced',
+ ownerEpoch: 1,
+ }).ok
+ ).toBe(false);
+ expect(
+ validateEngineToCoordinatorEnvelope({
+ ...version,
+ kind: 'heartbeat-ack',
+ ownerEpoch: 1,
+ heartbeatId: 1,
+ extra: true,
+ }).ok
+ ).toBe(false);
+ expect(
+ validateCoordinatorToEngineEnvelope({
+ ...version,
+ kind: 'engine-request',
+ ownerEpoch: 1,
+ routeId: 1,
+ request: { id: 1, kind: 'unknown' },
+ }).ok
+ ).toBe(false);
+ });
+
+ it('derives the exact UTF-8 canonical turso-opfs lock name', () => {
+ expect(databaseOwnerLockName('scope')).toBe(
+ 'macro:turso-opfs:v1:19:graphql-cache:scope'
+ );
+ expect(databaseOwnerLockName('é')).toBe(
+ 'macro:turso-opfs:v1:16:graphql-cache:é'
+ );
+ });
+});
diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts
new file mode 100644
index 0000000000..d1114fc7ea
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts
@@ -0,0 +1,897 @@
+import {
+ type CachePush,
+ type CacheRequest,
+ type CacheResponse,
+ isCachePush,
+ isCacheResponse,
+ isWorkerMessage,
+ type WorkerMessage,
+} from '../protocol';
+
+export { isCachePush, isCacheResponse, isWorkerMessage };
+
+/** Version of the topology envelope around the unchanged cache RPC. */
+export const CACHE_COORDINATOR_PROTOCOL_VERSION = 1 as const;
+
+export type OwnerEpoch = number;
+export type RouteId = number;
+export type DatabaseAction = 'open-existing' | 'wipe-before-open';
+export type DatabaseActionProof = 'opened-existing' | 'wiped-before-open';
+export type EngineOpenOutcome =
+ | 'opened-existing'
+ | 'opened-new'
+ | 'reset-incompatible'
+ | 'reset-corrupt'
+ | 'reset-storage-uncertain';
+export type EngineFatalCode = 'storage-reset-required' | 'runtime-failure';
+export type ActivationFailureCode =
+ | 'initialization-failed'
+ | 'recovery-open-failed';
+
+export type TabToCoordinatorEnvelope =
+ | {
+ coordinatorVersion: 1;
+ kind: 'register-tab';
+ scope: string;
+ tabId: string;
+ livenessLockName: string;
+ hotCapacity?: number;
+ }
+ | {
+ coordinatorVersion: 1;
+ kind: 'cache-request';
+ tabId: string;
+ request: CacheRequest;
+ }
+ | {
+ coordinatorVersion: 1;
+ kind: 'attach-engine-port';
+ tabId: string;
+ ownerEpoch: OwnerEpoch;
+ }
+ | {
+ coordinatorVersion: 1;
+ kind: 'graceful-departure';
+ tabId: string;
+ ownerEpoch: OwnerEpoch;
+ }
+ | {
+ coordinatorVersion: 1;
+ kind: 'engine-lost';
+ tabId: string;
+ ownerEpoch: OwnerEpoch;
+ reason: string;
+ }
+ | {
+ coordinatorVersion: 1;
+ kind: 'disconnect-tab';
+ tabId: string;
+ reason: string;
+ };
+
+export type CoordinatorToTabEnvelope =
+ | {
+ coordinatorVersion: 1;
+ kind: 'registered';
+ tabId: string;
+ }
+ | {
+ coordinatorVersion: 1;
+ kind: 'become-owner';
+ scope: string;
+ tabId: string;
+ ownerEpoch: OwnerEpoch;
+ databaseAction: DatabaseAction;
+ ownerLockName: string;
+ hotCapacity?: number;
+ }
+ | {
+ coordinatorVersion: 1;
+ kind: 'cache-message';
+ message: WorkerMessage;
+ }
+ | {
+ coordinatorVersion: 1;
+ kind: 'terminate-engine';
+ tabId: string;
+ ownerEpoch: OwnerEpoch;
+ reason: string;
+ }
+ | {
+ coordinatorVersion: 1;
+ kind: 'retire-complete';
+ tabId: string;
+ ownerEpoch: OwnerEpoch;
+ }
+ | {
+ coordinatorVersion: 1;
+ kind: 'engine-replaced';
+ ownerEpoch: OwnerEpoch;
+ }
+ | {
+ coordinatorVersion: 1;
+ kind: 'protocol-error';
+ error: string;
+ };
+
+export type PageToEngineEnvelope = {
+ coordinatorVersion: 1;
+ kind: 'activate-engine';
+ scope: string;
+ tabId: string;
+ ownerEpoch: OwnerEpoch;
+ databaseAction: DatabaseAction;
+ ownerLockName: string;
+ hotCapacity?: number;
+};
+
+export type CoordinatorToEngineEnvelope =
+ | {
+ coordinatorVersion: 1;
+ kind: 'engine-request';
+ ownerEpoch: OwnerEpoch;
+ routeId: RouteId;
+ request: CacheRequest;
+ }
+ | {
+ coordinatorVersion: 1;
+ kind: 'drain-engine';
+ ownerEpoch: OwnerEpoch;
+ }
+ | {
+ coordinatorVersion: 1;
+ kind: 'heartbeat';
+ ownerEpoch: OwnerEpoch;
+ heartbeatId: number;
+ };
+
+export type EngineToCoordinatorEnvelope =
+ | {
+ coordinatorVersion: 1;
+ kind: 'engine-ready';
+ tabId: string;
+ ownerEpoch: OwnerEpoch;
+ ownerLockName: string;
+ ownerLockHeld: true;
+ databaseActionProof: DatabaseActionProof;
+ openOutcome: EngineOpenOutcome;
+ }
+ | {
+ coordinatorVersion: 1;
+ kind: 'engine-response';
+ ownerEpoch: OwnerEpoch;
+ routeId: RouteId;
+ response: CacheResponse;
+ }
+ | {
+ coordinatorVersion: 1;
+ kind: 'engine-push';
+ ownerEpoch: OwnerEpoch;
+ push: CachePush;
+ }
+ | {
+ coordinatorVersion: 1;
+ kind: 'engine-drained';
+ tabId: string;
+ ownerEpoch: OwnerEpoch;
+ }
+ | {
+ coordinatorVersion: 1;
+ kind: 'engine-fatal';
+ tabId: string;
+ ownerEpoch: OwnerEpoch;
+ reason: string;
+ fatalCode: EngineFatalCode;
+ }
+ | {
+ coordinatorVersion: 1;
+ kind: 'activation-failed';
+ tabId: string;
+ ownerEpoch: OwnerEpoch;
+ reason: string;
+ failureCode: ActivationFailureCode;
+ }
+ | {
+ coordinatorVersion: 1;
+ kind: 'heartbeat-ack';
+ ownerEpoch: OwnerEpoch;
+ heartbeatId: number;
+ };
+
+export type EnvelopeValidation<T> =
+ | { ok: true; value: T }
+ | { ok: false; error: string };
+
+type UnknownRecord = Record<string, unknown>;
+
+const fail = <T>(error: string): EnvelopeValidation<T> => ({
+ ok: false,
+ error,
+});
+
+const pass = <T>(value: T): EnvelopeValidation<T> => ({ ok: true, value });
+
+const isRecord = (value: unknown): value is UnknownRecord =>
+ typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const isString = (value: unknown): value is string => typeof value === 'string';
+
+const isNonEmptyString = (value: unknown): value is string =>
+ isString(value) && value.length > 0;
+
+const isOptionalString = (value: unknown): value is string | undefined =>
+ value === undefined || isString(value);
+
+const isSafeNonNegativeInteger = (value: unknown): value is number =>
+ Number.isSafeInteger(value) && (value as number) >= 0;
+
+const isPositiveInteger = (value: unknown): value is number =>
+ Number.isSafeInteger(value) && (value as number) > 0;
+
+const isOptionalPositiveInteger = (
+ value: unknown
+): value is number | undefined =>
+ value === undefined || isPositiveInteger(value);
+
+const isStringArray = (value: unknown): value is string[] =>
+ Array.isArray(value) && value.every(isString);
+
+const hasOwn = (record: UnknownRecord, key: string): boolean =>
+ Object.hasOwn(record, key);
+
+const hasOnlyKeys = (record: UnknownRecord, keys: readonly string[]): boolean =>
+ Object.keys(record).every((key) => keys.includes(key));
+
+const hasVersion = (record: UnknownRecord): boolean =>
+ record.coordinatorVersion === CACHE_COORDINATOR_PROTOCOL_VERSION;
+
+const isDatabaseAction = (value: unknown): value is DatabaseAction =>
+ value === 'open-existing' || value === 'wipe-before-open';
+
+const isDatabaseActionProof = (value: unknown): value is DatabaseActionProof =>
+ value === 'opened-existing' || value === 'wiped-before-open';
+
+const isEngineOpenOutcome = (value: unknown): value is EngineOpenOutcome =>
+ typeof value === 'string' &&
+ [
+ 'opened-existing',
+ 'opened-new',
+ 'reset-incompatible',
+ 'reset-corrupt',
+ 'reset-storage-uncertain',
+ ].includes(value);
+
+const isEngineFatalCode = (value: unknown): value is EngineFatalCode =>
+ value === 'storage-reset-required' || value === 'runtime-failure';
+
+const isActivationFailureCode = (
+ value: unknown
+): value is ActivationFailureCode =>
+ value === 'initialization-failed' || value === 'recovery-open-failed';
+
+const isOptionalRecord = (
+ value: unknown
+): value is Record<string, unknown> | undefined =>
+ value === undefined || isRecord(value);
+
+const isPath = (value: unknown): boolean =>
+ Array.isArray(value) &&
+ value.every(
+ (segment) =>
+ isRecord(segment) &&
+ hasOnlyKeys(segment, ['field']) &&
+ isString(segment.field)
+ );
+
+const isEntityResolvers = (value: unknown): boolean =>
+ value === undefined ||
+ (Array.isArray(value) &&
+ value.every(
+ (resolver) =>
+ isRecord(resolver) &&
+ isString(resolver.parentType) &&
+ isString(resolver.fieldName) &&
+ isString(resolver.targetType) &&
+ isStringArray(resolver.argumentPath)
+ ));
+
+const commonRequest = (record: UnknownRecord): boolean =>
+ isSafeNonNegativeInteger(record.id) && isNonEmptyString(record.kind);
+
+/** Strictly validates a cache RPC request nested in a coordinator envelope. */
+export function isCacheRequest(value: unknown): value is CacheRequest {
+ if (!isRecord(value) || !commonRequest(value)) return false;
+ switch (value.kind) {
+ case 'init':
+ return (
+ hasOnlyKeys(value, ['id', 'kind', 'scope', 'hotCapacity']) &&
+ isNonEmptyString(value.scope) &&
+ isOptionalPositiveInteger(value.hotCapacity)
+ );
+ case 'read':
+ return (
+ hasOnlyKeys(value, [
+ 'id',
+ 'kind',
+ 'opId',
+ 'query',
+ 'operationName',
+ 'variables',
+ 'priority',
+ 'entityResolvers',
+ ]) &&
+ isOptionalString(value.opId) &&
+ isString(value.query) &&
+ isOptionalString(value.operationName) &&
+ isOptionalRecord(value.variables) &&
+ (value.priority === undefined || value.priority === 'user-visible') &&
+ isEntityResolvers(value.entityResolvers)
+ );
+ case 'write':
+ return (
+ hasOnlyKeys(value, [
+ 'id',
+ 'kind',
+ 'originOpId',
+ 'query',
+ 'operationName',
+ 'variables',
+ 'data',
+ 'identity',
+ ]) &&
+ isOptionalString(value.originOpId) &&
+ isString(value.query) &&
+ isOptionalString(value.operationName) &&
+ isOptionalRecord(value.variables) &&
+ hasOwn(value, 'data') &&
+ isOptionalString(value.identity)
+ );
+ case 'enqueue-optimistic-mutation':
+ return (
+ hasOnlyKeys(value, [
+ 'id',
+ 'kind',
+ 'originOpId',
+ 'query',
+ 'operationName',
+ 'variables',
+ 'data',
+ 'linkPatches',
+ 'revalidations',
+ 'createdAtMs',
+ 'owner',
+ 'nowMs',
+ 'leaseExpiresAtMs',
+ ]) &&
+ isOptionalString(value.originOpId) &&
+ isString(value.query) &&
+ isOptionalString(value.operationName) &&
+ isOptionalRecord(value.variables) &&
+ hasOwn(value, 'data') &&
+ (value.linkPatches === undefined || Array.isArray(value.linkPatches)) &&
+ (value.revalidations === undefined ||
+ Array.isArray(value.revalidations)) &&
+ isSafeNonNegativeInteger(value.createdAtMs) &&
+ isString(value.owner) &&
+ isSafeNonNegativeInteger(value.nowMs) &&
+ isSafeNonNegativeInteger(value.leaseExpiresAtMs)
+ );
+ case 'claim-next-mutation':
+ return (
+ hasOnlyKeys(value, [
+ 'id',
+ 'kind',
+ 'owner',
+ 'nowMs',
+ 'leaseExpiresAtMs',
+ ]) &&
+ isString(value.owner) &&
+ isSafeNonNegativeInteger(value.nowMs) &&
+ isSafeNonNegativeInteger(value.leaseExpiresAtMs)
+ );
+ case 'defer-optimistic-write':
+ return (
+ hasOnlyKeys(value, [
+ 'id',
+ 'kind',
+ 'transactionId',
+ 'leaseOwner',
+ 'leaseGeneration',
+ 'nextAttemptAtMs',
+ 'error',
+ ]) &&
+ isString(value.transactionId) &&
+ isString(value.leaseOwner) &&
+ isString(value.leaseGeneration) &&
+ isSafeNonNegativeInteger(value.nextAttemptAtMs) &&
+ isString(value.error)
+ );
+ case 'commit-optimistic-write':
+ return (
+ hasOnlyKeys(value, [
+ 'id',
+ 'kind',
+ 'transactionId',
+ 'leaseOwner',
+ 'leaseGeneration',
+ 'query',
+ 'operationName',
+ 'variables',
+ 'data',
+ ]) &&
+ isString(value.transactionId) &&
+ isString(value.leaseOwner) &&
+ isString(value.leaseGeneration) &&
+ isString(value.query) &&
+ isOptionalString(value.operationName) &&
+ isOptionalRecord(value.variables) &&
+ hasOwn(value, 'data')
+ );
+ case 'rollback-optimistic-write':
+ return (
+ hasOnlyKeys(value, [
+ 'id',
+ 'kind',
+ 'transactionId',
+ 'leaseOwner',
+ 'leaseGeneration',
+ 'error',
+ ]) &&
+ isString(value.transactionId) &&
+ isString(value.leaseOwner) &&
+ isString(value.leaseGeneration) &&
+ isString(value.error)
+ );
+ case 'read-records':
+ return (
+ hasOnlyKeys(value, [
+ 'id',
+ 'kind',
+ 'document',
+ 'fragmentName',
+ 'cursor',
+ 'limit',
+ ]) &&
+ isString(value.document) &&
+ isString(value.fragmentName) &&
+ isOptionalString(value.cursor) &&
+ isPositiveInteger(value.limit)
+ );
+ case 'inspect-query':
+ return (
+ hasOnlyKeys(value, [
+ 'id',
+ 'kind',
+ 'query',
+ 'operationName',
+ 'path',
+ 'variableFilters',
+ ]) &&
+ isString(value.query) &&
+ isOptionalString(value.operationName) &&
+ isPath(value.path) &&
+ (value.variableFilters === undefined ||
+ (Array.isArray(value.variableFilters) &&
+ value.variableFilters.every(isRecord)))
+ );
+ case 'inspect-query-variants':
+ return (
+ hasOnlyKeys(value, ['id', 'kind', 'query', 'operationName', 'path']) &&
+ isString(value.query) &&
+ isOptionalString(value.operationName) &&
+ isPath(value.path)
+ );
+ case 'teardown':
+ return hasOnlyKeys(value, ['id', 'kind', 'opId']) && isString(value.opId);
+ case 'invalidate':
+ case 'delete-records':
+ return (
+ hasOnlyKeys(value, ['id', 'kind', 'keys']) && isStringArray(value.keys)
+ );
+ case 'clear':
+ return hasOnlyKeys(value, ['id', 'kind']);
+ default:
+ return false;
+ }
+}
+
+/** Validates an untrusted page-to-coordinator message. */
+export function validateTabToCoordinatorEnvelope(
+ value: unknown
+): EnvelopeValidation<TabToCoordinatorEnvelope> {
+ if (!isRecord(value) || !hasVersion(value) || !isString(value.kind)) {
+ return fail('invalid coordinator envelope header');
+ }
+ const base =
+ value.coordinatorVersion === CACHE_COORDINATOR_PROTOCOL_VERSION &&
+ isNonEmptyString(value.tabId);
+ if (!base) return fail('invalid coordinator tab identity');
+
+ switch (value.kind) {
+ case 'register-tab':
+ if (
+ hasOnlyKeys(value, [
+ 'coordinatorVersion',
+ 'kind',
+ 'scope',
+ 'tabId',
+ 'livenessLockName',
+ 'hotCapacity',
+ ]) &&
+ isNonEmptyString(value.scope) &&
+ isNonEmptyString(value.livenessLockName) &&
+ isOptionalPositiveInteger(value.hotCapacity)
+ ) {
+ return pass(value as TabToCoordinatorEnvelope);
+ }
+ break;
+ case 'cache-request':
+ if (
+ hasOnlyKeys(value, [
+ 'coordinatorVersion',
+ 'kind',
+ 'tabId',
+ 'request',
+ ]) &&
+ isCacheRequest(value.request)
+ ) {
+ return pass(value as TabToCoordinatorEnvelope);
+ }
+ break;
+ case 'attach-engine-port':
+ case 'graceful-departure':
+ if (
+ hasOnlyKeys(value, [
+ 'coordinatorVersion',
+ 'kind',
+ 'tabId',
+ 'ownerEpoch',
+ ]) &&
+ isPositiveInteger(value.ownerEpoch)
+ ) {
+ return pass(value as TabToCoordinatorEnvelope);
+ }
+ break;
+ case 'engine-lost':
+ if (
+ hasOnlyKeys(value, [
+ 'coordinatorVersion',
+ 'kind',
+ 'tabId',
+ 'ownerEpoch',
+ 'reason',
+ ]) &&
+ isPositiveInteger(value.ownerEpoch) &&
+ isNonEmptyString(value.reason)
+ ) {
+ return pass(value as TabToCoordinatorEnvelope);
+ }
+ break;
+ case 'disconnect-tab':
+ if (
+ hasOnlyKeys(value, ['coordinatorVersion', 'kind', 'tabId', 'reason']) &&
+ isNonEmptyString(value.reason)
+ ) {
+ return pass(value as TabToCoordinatorEnvelope);
+ }
+ break;
+ }
+ return fail(`invalid ${value.kind} coordinator envelope`);
+}
+
+/** Validates an untrusted coordinator-to-page message. */
+export function validateCoordinatorToTabEnvelope(
+ value: unknown
+): EnvelopeValidation<CoordinatorToTabEnvelope> {
+ if (!isRecord(value) || !hasVersion(value) || !isString(value.kind)) {
+ return fail('invalid coordinator envelope header');
+ }
+ switch (value.kind) {
+ case 'registered':
+ if (
+ hasOnlyKeys(value, ['coordinatorVersion', 'kind', 'tabId']) &&
+ isNonEmptyString(value.tabId)
+ ) {
+ return pass(value as CoordinatorToTabEnvelope);
+ }
+ break;
+ case 'become-owner':
+ if (
+ hasOnlyKeys(value, [
+ 'coordinatorVersion',
+ 'kind',
+ 'scope',
+ 'tabId',
+ 'ownerEpoch',
+ 'databaseAction',
+ 'ownerLockName',
+ 'hotCapacity',
+ ]) &&
+ isNonEmptyString(value.scope) &&
+ isNonEmptyString(value.tabId) &&
+ isPositiveInteger(value.ownerEpoch) &&
+ isDatabaseAction(value.databaseAction) &&
+ isNonEmptyString(value.ownerLockName) &&
+ isOptionalPositiveInteger(value.hotCapacity)
+ ) {
+ return pass(value as CoordinatorToTabEnvelope);
+ }
+ break;
+ case 'cache-message':
+ if (
+ hasOnlyKeys(value, ['coordinatorVersion', 'kind', 'message']) &&
+ isWorkerMessage(value.message)
+ ) {
+ return pass(value as CoordinatorToTabEnvelope);
+ }
+ break;
+ case 'terminate-engine':
+ if (
+ hasOnlyKeys(value, [
+ 'coordinatorVersion',
+ 'kind',
+ 'tabId',
+ 'ownerEpoch',
+ 'reason',
+ ]) &&
+ isNonEmptyString(value.tabId) &&
+ isPositiveInteger(value.ownerEpoch) &&
+ isNonEmptyString(value.reason)
+ ) {
+ return pass(value as CoordinatorToTabEnvelope);
+ }
+ break;
+ case 'retire-complete':
+ if (
+ hasOnlyKeys(value, [
+ 'coordinatorVersion',
+ 'kind',
+ 'tabId',
+ 'ownerEpoch',
+ ]) &&
+ isNonEmptyString(value.tabId) &&
+ isPositiveInteger(value.ownerEpoch)
+ ) {
+ return pass(value as CoordinatorToTabEnvelope);
+ }
+ break;
+ case 'engine-replaced':
+ if (
+ hasOnlyKeys(value, ['coordinatorVersion', 'kind', 'ownerEpoch']) &&
+ isPositiveInteger(value.ownerEpoch)
+ ) {
+ return pass(value as CoordinatorToTabEnvelope);
+ }
+ break;
+ case 'protocol-error':
+ if (
+ hasOnlyKeys(value, ['coordinatorVersion', 'kind', 'error']) &&
+ isNonEmptyString(value.error)
+ ) {
+ return pass(value as CoordinatorToTabEnvelope);
+ }
+ break;
+ }
+ return fail(`invalid ${value.kind} coordinator envelope`);
+}
+
+/** Validates the page's one-time DedicatedWorker activation message. */
+export function validatePageToEngineEnvelope(
+ value: unknown
+): EnvelopeValidation<PageToEngineEnvelope> {
+ if (
+ isRecord(value) &&
+ hasVersion(value) &&
+ value.kind === 'activate-engine' &&
+ hasOnlyKeys(value, [
+ 'coordinatorVersion',
+ 'kind',
+ 'scope',
+ 'tabId',
+ 'ownerEpoch',
+ 'databaseAction',
+ 'ownerLockName',
+ 'hotCapacity',
+ ]) &&
+ isNonEmptyString(value.scope) &&
+ isNonEmptyString(value.tabId) &&
+ isPositiveInteger(value.ownerEpoch) &&
+ isDatabaseAction(value.databaseAction) &&
+ isNonEmptyString(value.ownerLockName) &&
+ isOptionalPositiveInteger(value.hotCapacity)
+ ) {
+ return pass(value as PageToEngineEnvelope);
+ }
+ return fail('invalid activate-engine envelope');
+}
+
+/** Validates an untrusted coordinator-to-engine direct-port message. */
+export function validateCoordinatorToEngineEnvelope(
+ value: unknown
+): EnvelopeValidation<CoordinatorToEngineEnvelope> {
+ if (!isRecord(value) || !hasVersion(value) || !isString(value.kind)) {
+ return fail('invalid coordinator envelope header');
+ }
+ switch (value.kind) {
+ case 'engine-request':
+ if (
+ hasOnlyKeys(value, [
+ 'coordinatorVersion',
+ 'kind',
+ 'ownerEpoch',
+ 'routeId',
+ 'request',
+ ]) &&
+ isPositiveInteger(value.ownerEpoch) &&
+ isPositiveInteger(value.routeId) &&
+ isCacheRequest(value.request) &&
+ value.request.id === value.routeId
+ ) {
+ return pass(value as CoordinatorToEngineEnvelope);
+ }
+ break;
+ case 'drain-engine':
+ if (
+ hasOnlyKeys(value, ['coordinatorVersion', 'kind', 'ownerEpoch']) &&
+ isPositiveInteger(value.ownerEpoch)
+ ) {
+ return pass(value as CoordinatorToEngineEnvelope);
+ }
+ break;
+ case 'heartbeat':
+ if (
+ hasOnlyKeys(value, [
+ 'coordinatorVersion',
+ 'kind',
+ 'ownerEpoch',
+ 'heartbeatId',
+ ]) &&
+ isPositiveInteger(value.ownerEpoch) &&
+ isPositiveInteger(value.heartbeatId)
+ ) {
+ return pass(value as CoordinatorToEngineEnvelope);
+ }
+ break;
+ }
+ return fail(`invalid ${value.kind} coordinator envelope`);
+}
+
+/** Validates an untrusted engine-to-coordinator direct-port message. */
+export function validateEngineToCoordinatorEnvelope(
+ value: unknown
+): EnvelopeValidation<EngineToCoordinatorEnvelope> {
+ if (!isRecord(value) || !hasVersion(value) || !isString(value.kind)) {
+ return fail('invalid coordinator envelope header');
+ }
+ switch (value.kind) {
+ case 'engine-ready':
+ if (
+ hasOnlyKeys(value, [
+ 'coordinatorVersion',
+ 'kind',
+ 'tabId',
+ 'ownerEpoch',
+ 'ownerLockName',
+ 'ownerLockHeld',
+ 'databaseActionProof',
+ 'openOutcome',
+ ]) &&
+ isNonEmptyString(value.tabId) &&
+ isPositiveInteger(value.ownerEpoch) &&
+ isNonEmptyString(value.ownerLockName) &&
+ value.ownerLockHeld === true &&
+ isDatabaseActionProof(value.databaseActionProof) &&
+ isEngineOpenOutcome(value.openOutcome)
+ ) {
+ return pass(value as EngineToCoordinatorEnvelope);
+ }
+ break;
+ case 'engine-response':
+ if (
+ hasOnlyKeys(value, [
+ 'coordinatorVersion',
+ 'kind',
+ 'ownerEpoch',
+ 'routeId',
+ 'response',
+ ]) &&
+ isPositiveInteger(value.ownerEpoch) &&
+ isPositiveInteger(value.routeId) &&
+ isCacheResponse(value.response) &&
+ (value.response.ok || value.response.errorCode === undefined) &&
+ value.response.id === value.routeId
+ ) {
+ return pass(value as EngineToCoordinatorEnvelope);
+ }
+ break;
+ case 'engine-push':
+ if (
+ hasOnlyKeys(value, [
+ 'coordinatorVersion',
+ 'kind',
+ 'ownerEpoch',
+ 'push',
+ ]) &&
+ isPositiveInteger(value.ownerEpoch) &&
+ isCachePush(value.push)
+ ) {
+ return pass(value as EngineToCoordinatorEnvelope);
+ }
+ break;
+ case 'engine-drained':
+ if (
+ hasOnlyKeys(value, [
+ 'coordinatorVersion',
+ 'kind',
+ 'tabId',
+ 'ownerEpoch',
+ ]) &&
+ isNonEmptyString(value.tabId) &&
+ isPositiveInteger(value.ownerEpoch)
+ ) {
+ return pass(value as EngineToCoordinatorEnvelope);
+ }
+ break;
+ case 'engine-fatal':
+ if (
+ hasOnlyKeys(value, [
+ 'coordinatorVersion',
+ 'kind',
+ 'tabId',
+ 'ownerEpoch',
+ 'reason',
+ 'fatalCode',
+ ]) &&
+ isNonEmptyString(value.tabId) &&
+ isPositiveInteger(value.ownerEpoch) &&
+ isNonEmptyString(value.reason) &&
+ isEngineFatalCode(value.fatalCode)
+ ) {
+ return pass(value as EngineToCoordinatorEnvelope);
+ }
+ break;
+ case 'activation-failed':
+ if (
+ hasOnlyKeys(value, [
+ 'coordinatorVersion',
+ 'kind',
+ 'tabId',
+ 'ownerEpoch',
+ 'reason',
+ 'failureCode',
+ ]) &&
+ isNonEmptyString(value.tabId) &&
+ isPositiveInteger(value.ownerEpoch) &&
+ isNonEmptyString(value.reason) &&
+ isActivationFailureCode(value.failureCode)
+ ) {
+ return pass(value as EngineToCoordinatorEnvelope);
+ }
+ break;
+ case 'heartbeat-ack':
+ if (
+ hasOnlyKeys(value, [
+ 'coordinatorVersion',
+ 'kind',
+ 'ownerEpoch',
+ 'heartbeatId',
+ ]) &&
+ isPositiveInteger(value.ownerEpoch) &&
+ isPositiveInteger(value.heartbeatId)
+ ) {
+ return pass(value as EngineToCoordinatorEnvelope);
+ }
+ break;
+ }
+ return fail(`invalid ${value.kind} coordinator envelope`);
+}
+
+export const tabLivenessLockName = (scope: string, tabId: string): string =>
+ `graphql-cache-tab:${scope}:${tabId}`;
+
+/** Mirrors turso-opfs's canonical lock derivation without exposing a new lock. */
+export function databaseOwnerLockName(scope: string): string {
+ const databaseIdentity = `graphql-cache:${scope}`;
+ const byteLength = new TextEncoder().encode(databaseIdentity).byteLength;
+ return `macro:turso-opfs:v1:${byteLength}:${databaseIdentity}`;
+}
diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-router.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-router.test.ts
new file mode 100644
index 0000000000..bb7bd6cf54
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-router.test.ts
@@ -0,0 +1,779 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+ CACHE_COORDINATOR_PROTOCOL_VERSION,
+ databaseOwnerLockName,
+} from './coordinator-protocol';
+import {
+ type CoordinatorMessagePort,
+ CoordinatorRouter,
+} from './coordinator-router';
+
+class FakePort {
+ readonly messages: unknown[] = [];
+ readonly events: string[] = [];
+ closed = false;
+ started = false;
+ onmessage: ((event: MessageEvent<unknown>) => void) | null = null;
+ onmessageerror: (() => void) | null = null;
+
+ postMessage(message: unknown): void {
+ this.messages.push(message);
+ this.events.push(
+ `post:${String((message as { kind?: unknown })?.kind ?? 'unknown')}`
+ );
+ }
+
+ close(): void {
+ this.closed = true;
+ this.events.push('close');
+ }
+
+ start(): void {
+ this.started = true;
+ }
+
+ receive(message: unknown): void {
+ this.onmessage?.({ data: message, ports: [] } as unknown as MessageEvent);
+ }
+}
+
+const version = {
+ coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION,
+} as const;
+
+const register = async (
+ router: CoordinatorRouter,
+ port: FakePort,
+ tabId: string
+): Promise<void> => {
+ await router.handleTabMessage(port as CoordinatorMessagePort, {
+ ...version,
+ kind: 'register-tab',
+ scope: 'scope',
+ tabId,
+ livenessLockName: `graphql-cache-tab:scope:${tabId}`,
+ });
+};
+
+const attach = async (
+ router: CoordinatorRouter,
+ tabPort: FakePort,
+ tabId: string,
+ ownerEpoch: number,
+ enginePort: FakePort
+): Promise<void> => {
+ await router.handleTabMessage(
+ tabPort as CoordinatorMessagePort,
+ {
+ ...version,
+ kind: 'attach-engine-port',
+ tabId,
+ ownerEpoch,
+ },
+ [enginePort as unknown as MessagePort]
+ );
+};
+
+const ready = (
+ enginePort: FakePort,
+ tabId: string,
+ ownerEpoch: number,
+ proof: 'opened-existing' | 'wiped-before-open'
+): void => {
+ enginePort.receive({
+ ...version,
+ kind: 'engine-ready',
+ tabId,
+ ownerEpoch,
+ ownerLockName: databaseOwnerLockName('scope'),
+ ownerLockHeld: true,
+ databaseActionProof: proof,
+ openOutcome:
+ proof === 'wiped-before-open'
+ ? 'reset-storage-uncertain'
+ : 'opened-existing',
+ });
+};
+
+const messagesOfKind = <T extends string>(port: FakePort, kind: T) =>
+ port.messages.filter(
+ (message): message is Record<string, unknown> & { kind: T } =>
+ typeof message === 'object' &&
+ message !== null &&
+ (message as { kind?: unknown }).kind === kind
+ );
+
+describe('CoordinatorRouter', () => {
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it('reports recovery reset success only after ready proof and failure on activation failure', async () => {
+ const observations: Array<Record<string, unknown>> = [];
+ const setupRecovery = async () => {
+ const router = new CoordinatorRouter({
+ verifyTabLockHeld: async () => true,
+ watchTabLock: () => () => {},
+ telemetry: {
+ record: (observation) => observations.push(observation),
+ flush: vi.fn(),
+ },
+ });
+ const tabA = new FakePort();
+ const tabB = new FakePort();
+ const engineA = new FakePort();
+ await register(router, tabA, 'tab-a');
+ await register(router, tabB, 'tab-b');
+ await attach(router, tabA, 'tab-a', 1, engineA);
+ ready(engineA, 'tab-a', 1, 'opened-existing');
+ await router.handleTabMessage(tabA as CoordinatorMessagePort, {
+ ...version,
+ kind: 'engine-lost',
+ tabId: 'tab-a',
+ ownerEpoch: 1,
+ reason: 'injected abrupt loss',
+ });
+ expect(router.snapshot()?.state).toMatchObject({
+ kind: 'activating',
+ ownerEpoch: 2,
+ databaseAction: 'wipe-before-open',
+ });
+ expect(
+ observations.filter(
+ (observation) => observation.name === 'graphql_cache.reset_wipe'
+ )
+ ).toEqual([]);
+ return { router, tabB };
+ };
+
+ const successful = await setupRecovery();
+ const successfulEngine = new FakePort();
+ await attach(
+ successful.router,
+ successful.tabB,
+ 'tab-b',
+ 2,
+ successfulEngine
+ );
+ ready(successfulEngine, 'tab-b', 2, 'wiped-before-open');
+ expect(
+ observations.filter(
+ (observation) => observation.name === 'graphql_cache.reset_wipe'
+ )
+ ).toEqual([
+ expect.objectContaining({
+ outcome: 'success',
+ resetReason: 'abrupt-owner-loss',
+ }),
+ ]);
+
+ observations.length = 0;
+ const failed = await setupRecovery();
+ const failedEngine = new FakePort();
+ await attach(failed.router, failed.tabB, 'tab-b', 2, failedEngine);
+ failedEngine.receive({
+ ...version,
+ kind: 'activation-failed',
+ tabId: 'tab-b',
+ ownerEpoch: 2,
+ reason: 'OPFS recovery open failed',
+ failureCode: 'recovery-open-failed',
+ });
+ expect(
+ observations.filter(
+ (observation) => observation.name === 'graphql_cache.reset_wipe'
+ )
+ ).toEqual([
+ expect.objectContaining({
+ outcome: 'error',
+ resetReason: 'abrupt-owner-loss',
+ }),
+ ]);
+ });
+
+ it('registers only after independent liveness-lock contention succeeds', async () => {
+ let releaseVerification: ((held: boolean) => void) | undefined;
+ const verification = new Promise<boolean>((resolve) => {
+ releaseVerification = resolve;
+ });
+ const router = new CoordinatorRouter({
+ verifyTabLockHeld: () => verification,
+ watchTabLock: () => () => {},
+ });
+ const port = new FakePort();
+
+ const registration = register(router, port, 'tab-a');
+ expect(port.messages).toEqual([]);
+ expect(router.snapshot()).toBeUndefined();
+ releaseVerification?.(true);
+ await registration;
+
+ expect(messagesOfKind(port, 'registered')).toHaveLength(1);
+ expect(messagesOfKind(port, 'become-owner')).toContainEqual(
+ expect.objectContaining({
+ tabId: 'tab-a',
+ ownerEpoch: 1,
+ databaseAction: 'open-existing',
+ })
+ );
+ });
+
+ it('cancels an exact pending registration on MessagePort messageerror', async () => {
+ let finishVerification!: (held: boolean) => void;
+ const verification = new Promise<boolean>((resolve) => {
+ finishVerification = resolve;
+ });
+ const router = new CoordinatorRouter({
+ verifyTabLockHeld: () => verification,
+ watchTabLock: () => () => {},
+ });
+ const stalePort = new FakePort();
+ router.connect(stalePort as CoordinatorMessagePort);
+ stalePort.receive({
+ ...version,
+ kind: 'register-tab',
+ scope: 'scope',
+ tabId: 'stale-tab',
+ livenessLockName: 'graphql-cache-tab:scope:stale-tab',
+ });
+
+ stalePort.onmessageerror?.();
+ finishVerification(true);
+ await vi.waitFor(() => expect(stalePort.closed).toBe(true));
+ await Promise.resolve();
+
+ expect(messagesOfKind(stalePort, 'registered')).toHaveLength(0);
+ expect(messagesOfKind(stalePort, 'become-owner')).toHaveLength(0);
+ expect(router.snapshot()).toBeUndefined();
+
+ const livePort = new FakePort();
+ await register(router, livePort, 'live-tab');
+ expect(messagesOfKind(livePort, 'become-owner')).toContainEqual(
+ expect.objectContaining({ tabId: 'live-tab', ownerEpoch: 1 })
+ );
+ expect(router.snapshot()?.tabIds).toEqual(['live-tab']);
+ });
+
+ it('rejects registration when the page does not already hold its lock', async () => {
+ const router = new CoordinatorRouter({
+ verifyTabLockHeld: async () => false,
+ watchTabLock: () => () => {},
+ });
+ const port = new FakePort();
+
+ await register(router, port, 'tab-a');
+
+ expect(port.closed).toBe(true);
+ expect(messagesOfKind(port, 'protocol-error')).toContainEqual(
+ expect.objectContaining({
+ error: 'tab registration requires an already-held liveness lock',
+ })
+ );
+ expect(router.snapshot()).toBeUndefined();
+ });
+
+ it('routes colliding tab ids through unique engine ids, restores responses, and fans pushes', async () => {
+ const router = new CoordinatorRouter({
+ verifyTabLockHeld: async () => true,
+ watchTabLock: () => () => {},
+ });
+ const tabA = new FakePort();
+ const tabB = new FakePort();
+ const tabC = new FakePort();
+ await register(router, tabA, 'tab-a');
+ await register(router, tabB, 'tab-b');
+ await register(router, tabC, 'tab-c');
+ const engine = new FakePort();
+ await attach(router, tabA, 'tab-a', 1, engine);
+ ready(engine, 'tab-a', 1, 'opened-existing');
+
+ await router.handleTabMessage(tabB as CoordinatorMessagePort, {
+ ...version,
+ kind: 'cache-request',
+ tabId: 'tab-b',
+ request: { id: 4, kind: 'clear' },
+ });
+ await router.handleTabMessage(tabC as CoordinatorMessagePort, {
+ ...version,
+ kind: 'cache-request',
+ tabId: 'tab-c',
+ request: { id: 4, kind: 'clear' },
+ });
+ const routes = messagesOfKind(engine, 'engine-request');
+ expect(routes).toHaveLength(2);
+ const first = routes[0]!;
+ expect(first.routeId).not.toBe(routes[1]?.routeId);
+ expect((first.request as { id: number }).id).toBe(first.routeId);
+
+ const second = routes[1] as unknown as { routeId: number };
+ engine.receive({
+ ...version,
+ kind: 'engine-response',
+ ownerEpoch: 1,
+ routeId: second.routeId,
+ response: { id: second.routeId, ok: true, result: 'tab-c' },
+ });
+ expect(messagesOfKind(tabC, 'cache-message')).toContainEqual(
+ expect.objectContaining({
+ message: { id: 4, ok: true, result: 'tab-c' },
+ })
+ );
+
+ engine.receive({
+ ...version,
+ kind: 'engine-push',
+ ownerEpoch: 1,
+ push: { kind: 'cache-changed' },
+ });
+ for (const tab of [tabA, tabB, tabC]) {
+ expect(messagesOfKind(tab, 'cache-message')).toContainEqual(
+ expect.objectContaining({ message: { kind: 'cache-changed' } })
+ );
+ }
+ });
+
+ it('orders drain after earlier routes and elects open-existing only after drained', async () => {
+ const router = new CoordinatorRouter({
+ verifyTabLockHeld: async () => true,
+ watchTabLock: () => () => {},
+ });
+ const tabA = new FakePort();
+ const tabB = new FakePort();
+ await register(router, tabA, 'tab-a');
+ await register(router, tabB, 'tab-b');
+ const engine = new FakePort();
+ await attach(router, tabA, 'tab-a', 1, engine);
+ ready(engine, 'tab-a', 1, 'opened-existing');
+ await router.handleTabMessage(tabB as CoordinatorMessagePort, {
+ ...version,
+ kind: 'cache-request',
+ tabId: 'tab-b',
+ request: { id: 1, kind: 'clear' },
+ });
+ await router.handleTabMessage(tabA as CoordinatorMessagePort, {
+ ...version,
+ kind: 'graceful-departure',
+ tabId: 'tab-a',
+ ownerEpoch: 1,
+ });
+
+ expect(
+ engine.messages
+ .slice(-2)
+ .map((message) => (message as { kind: string }).kind)
+ ).toEqual(['engine-request', 'drain-engine']);
+ expect(messagesOfKind(tabB, 'become-owner')).toHaveLength(0);
+ const route = messagesOfKind(engine, 'engine-request')[0] as unknown as {
+ routeId: number;
+ };
+ engine.receive({
+ ...version,
+ kind: 'engine-response',
+ ownerEpoch: 1,
+ routeId: route.routeId,
+ response: { id: route.routeId, ok: true, result: null },
+ });
+ engine.receive({
+ ...version,
+ kind: 'engine-drained',
+ tabId: 'tab-a',
+ ownerEpoch: 1,
+ });
+
+ expect(messagesOfKind(tabB, 'become-owner')).toContainEqual(
+ expect.objectContaining({
+ ownerEpoch: 2,
+ databaseAction: 'open-existing',
+ })
+ );
+ expect(tabA.closed).toBe(true);
+ });
+
+ it('counts an unknown response with the current direct-route tuple as stale', async () => {
+ const router = new CoordinatorRouter({
+ verifyTabLockHeld: async () => true,
+ watchTabLock: () => () => {},
+ });
+ const tabA = new FakePort();
+ await register(router, tabA, 'tab-a');
+ const engine = new FakePort();
+ await attach(router, tabA, 'tab-a', 1, engine);
+ ready(engine, 'tab-a', 1, 'opened-existing');
+
+ engine.receive({
+ ...version,
+ kind: 'engine-response',
+ ownerEpoch: 1,
+ routeId: 999,
+ response: { id: 999, ok: true, result: 'stale' },
+ });
+
+ expect(router.snapshot()?.staleMessageDrops).toBe(1);
+ expect(router.snapshot()?.state).toMatchObject({
+ kind: 'active',
+ ownerEpoch: 1,
+ });
+ expect(messagesOfKind(tabA, 'terminate-engine')).toHaveLength(0);
+ });
+
+ it('uses activation and heartbeat watchdogs to terminate and wipe', async () => {
+ vi.useFakeTimers();
+ const router = new CoordinatorRouter({
+ activationTimeoutMs: 10,
+ heartbeatIntervalMs: 5,
+ heartbeatTimeoutMs: 7,
+ verifyTabLockHeld: async () => true,
+ watchTabLock: () => () => {},
+ });
+ const tabA = new FakePort();
+ const tabB = new FakePort();
+ await register(router, tabA, 'tab-a');
+ await register(router, tabB, 'tab-b');
+
+ await vi.advanceTimersByTimeAsync(11);
+ expect(messagesOfKind(tabA, 'terminate-engine')).toContainEqual(
+ expect.objectContaining({
+ ownerEpoch: 1,
+ reason: 'engine activation watchdog timed out',
+ })
+ );
+ expect(messagesOfKind(tabB, 'become-owner')).toContainEqual(
+ expect.objectContaining({
+ ownerEpoch: 2,
+ databaseAction: 'wipe-before-open',
+ })
+ );
+
+ const engine = new FakePort();
+ await attach(router, tabB, 'tab-b', 2, engine);
+ ready(engine, 'tab-b', 2, 'wiped-before-open');
+ await vi.advanceTimersByTimeAsync(6);
+ expect(messagesOfKind(engine, 'heartbeat')).toHaveLength(1);
+ await vi.advanceTimersByTimeAsync(8);
+ expect(messagesOfKind(tabB, 'terminate-engine')).toContainEqual(
+ expect.objectContaining({
+ ownerEpoch: 2,
+ reason: 'engine heartbeat watchdog timed out',
+ })
+ );
+ expect(router.snapshot()?.state.kind).toBe('activating');
+ expect(router.snapshot()?.ownerEpoch).toBe(3);
+ });
+
+ it('accepts heartbeat acknowledgements and rearms the watchdog', async () => {
+ vi.useFakeTimers();
+ const router = new CoordinatorRouter({
+ heartbeatIntervalMs: 5,
+ heartbeatTimeoutMs: 7,
+ verifyTabLockHeld: async () => true,
+ watchTabLock: () => () => {},
+ });
+ const tab = new FakePort();
+ await register(router, tab, 'tab-a');
+ const engine = new FakePort();
+ await attach(router, tab, 'tab-a', 1, engine);
+ ready(engine, 'tab-a', 1, 'opened-existing');
+
+ await vi.advanceTimersByTimeAsync(5);
+ const ping = messagesOfKind(engine, 'heartbeat')[0] as unknown as {
+ heartbeatId: number;
+ };
+ engine.receive({
+ ...version,
+ kind: 'heartbeat-ack',
+ ownerEpoch: 1,
+ heartbeatId: ping.heartbeatId,
+ });
+ await vi.advanceTimersByTimeAsync(6);
+
+ expect(messagesOfKind(tab, 'terminate-engine')).toHaveLength(0);
+ expect(messagesOfKind(engine, 'heartbeat')).toHaveLength(2);
+ });
+
+ it('uses liveness watcher release as the correctness path', async () => {
+ const releases = new Map<string, () => void>();
+ const cancels: string[] = [];
+ const router = new CoordinatorRouter({
+ verifyTabLockHeld: async () => true,
+ watchTabLock: (lockName, onReleased) => {
+ releases.set(lockName, onReleased);
+ return () => cancels.push(lockName);
+ },
+ });
+ const tabA = new FakePort();
+ const tabB = new FakePort();
+ const tabC = new FakePort();
+ await register(router, tabA, 'tab-a');
+ await register(router, tabB, 'tab-b');
+ await register(router, tabC, 'tab-c');
+ const engine = new FakePort();
+ await attach(router, tabA, 'tab-a', 1, engine);
+ ready(engine, 'tab-a', 1, 'opened-existing');
+
+ releases.get('graphql-cache-tab:scope:tab-b')?.();
+ expect(router.snapshot()?.state).toMatchObject({
+ kind: 'active',
+ tabId: 'tab-a',
+ });
+ releases.get('graphql-cache-tab:scope:tab-a')?.();
+ await Promise.resolve();
+
+ expect(messagesOfKind(tabA, 'terminate-engine')).toContainEqual(
+ expect.objectContaining({
+ ownerEpoch: 1,
+ reason: 'tab liveness lock was released',
+ })
+ );
+ expect(tabA.events.indexOf('post:terminate-engine')).toBeLessThan(
+ tabA.events.indexOf('close')
+ );
+ expect(router.snapshot()?.state).toMatchObject({
+ kind: 'activating',
+ ownerEpoch: 2,
+ databaseAction: 'wipe-before-open',
+ });
+ expect(cancels).toEqual(
+ expect.arrayContaining([
+ 'graphql-cache-tab:scope:tab-a',
+ 'graphql-cache-tab:scope:tab-b',
+ ])
+ );
+ });
+
+ it('removes a gracefully retiring owner before liveness-loss re-election', async () => {
+ const releases = new Map<string, () => void>();
+ const router = new CoordinatorRouter({
+ verifyTabLockHeld: async () => true,
+ watchTabLock: (lockName, onReleased) => {
+ releases.set(lockName, onReleased);
+ return () => undefined;
+ },
+ });
+ const tabA = new FakePort();
+ const tabB = new FakePort();
+ await register(router, tabA, 'tab-a');
+ await register(router, tabB, 'tab-b');
+ const engine = new FakePort();
+ await attach(router, tabA, 'tab-a', 1, engine);
+ ready(engine, 'tab-a', 1, 'opened-existing');
+
+ await router.handleTabMessage(tabA as CoordinatorMessagePort, {
+ ...version,
+ kind: 'graceful-departure',
+ tabId: 'tab-a',
+ ownerEpoch: 1,
+ });
+ releases.get('graphql-cache-tab:scope:tab-a')?.();
+ await Promise.resolve();
+
+ expect(router.snapshot()?.tabIds).toEqual(['tab-b']);
+ expect(router.snapshot()?.state).toMatchObject({
+ kind: 'activating',
+ tabId: 'tab-b',
+ ownerEpoch: 2,
+ databaseAction: 'wipe-before-open',
+ });
+ });
+
+ it('terminates a live owner before dropping a MessagePort on messageerror', async () => {
+ const router = new CoordinatorRouter({
+ verifyTabLockHeld: async () => true,
+ watchTabLock: () => () => {},
+ });
+ const tabA = new FakePort();
+ const tabB = new FakePort();
+ router.connect(tabA as CoordinatorMessagePort);
+ tabA.receive({
+ ...version,
+ kind: 'register-tab',
+ scope: 'scope',
+ tabId: 'tab-a',
+ livenessLockName: 'graphql-cache-tab:scope:tab-a',
+ });
+ await vi.waitFor(() =>
+ expect(messagesOfKind(tabA, 'registered')).toHaveLength(1)
+ );
+ await register(router, tabB, 'tab-b');
+ const engine = new FakePort();
+ await attach(router, tabA, 'tab-a', 1, engine);
+ ready(engine, 'tab-a', 1, 'opened-existing');
+
+ tabA.onmessageerror?.();
+ await Promise.resolve();
+
+ expect(messagesOfKind(tabA, 'terminate-engine')).toContainEqual(
+ expect.objectContaining({
+ ownerEpoch: 1,
+ reason: 'tab MessagePort messageerror',
+ })
+ );
+ expect(tabA.events.indexOf('post:terminate-engine')).toBeLessThan(
+ tabA.events.indexOf('close')
+ );
+ expect(router.snapshot()?.state).toMatchObject({
+ kind: 'activating',
+ ownerEpoch: 2,
+ databaseAction: 'wipe-before-open',
+ });
+ });
+
+ it('fails the current owner on an engine envelope route-tuple mismatch', async () => {
+ const router = new CoordinatorRouter({
+ verifyTabLockHeld: async () => true,
+ watchTabLock: () => () => {},
+ });
+ const tabA = new FakePort();
+ const tabB = new FakePort();
+ await register(router, tabA, 'tab-a');
+ await register(router, tabB, 'tab-b');
+ const engine = new FakePort();
+ await attach(router, tabA, 'tab-a', 1, engine);
+ ready(engine, 'tab-a', 1, 'opened-existing');
+
+ engine.receive({
+ ...version,
+ kind: 'engine-drained',
+ tabId: 'different-tab',
+ ownerEpoch: 1,
+ });
+ await Promise.resolve();
+
+ expect(messagesOfKind(tabA, 'terminate-engine')).toContainEqual(
+ expect.objectContaining({
+ ownerEpoch: 1,
+ reason: 'engine envelope owner tuple does not match its direct route',
+ })
+ );
+ expect(router.snapshot()?.state).toMatchObject({
+ kind: 'activating',
+ ownerEpoch: 2,
+ databaseAction: 'wipe-before-open',
+ });
+ });
+
+ it('fences an engine-originated topology error code instead of forwarding it', async () => {
+ const router = new CoordinatorRouter({
+ verifyTabLockHeld: async () => true,
+ watchTabLock: () => () => {},
+ });
+ const tabA = new FakePort();
+ const tabB = new FakePort();
+ await register(router, tabA, 'tab-a');
+ await register(router, tabB, 'tab-b');
+ const engine = new FakePort();
+ await attach(router, tabA, 'tab-a', 1, engine);
+ ready(engine, 'tab-a', 1, 'opened-existing');
+ await router.handleTabMessage(tabB as CoordinatorMessagePort, {
+ ...version,
+ kind: 'cache-request',
+ tabId: 'tab-b',
+ request: { id: 8, kind: 'clear' },
+ });
+ const route = messagesOfKind(engine, 'engine-request')[0] as unknown as {
+ routeId: number;
+ };
+
+ // Enter through the router's direct engine port. Its strict envelope
+ // validation must fence the owner; this is not merely a runtime unit path.
+ engine.receive({
+ ...version,
+ kind: 'engine-response',
+ ownerEpoch: 1,
+ routeId: route.routeId,
+ response: {
+ id: route.routeId,
+ ok: false,
+ error: 'forged topology loss',
+ errorCode: 'owner-epoch-lost',
+ },
+ });
+ await Promise.resolve();
+
+ expect(messagesOfKind(tabB, 'cache-message')).toContainEqual(
+ expect.objectContaining({
+ message: expect.objectContaining({
+ id: 8,
+ ok: false,
+ error: expect.stringContaining('invalid engine envelope'),
+ errorCode: 'owner-epoch-lost',
+ }),
+ })
+ );
+ expect(messagesOfKind(tabB, 'cache-message')).not.toContainEqual(
+ expect.objectContaining({
+ message: expect.objectContaining({ error: 'forged topology loss' }),
+ })
+ );
+ expect(messagesOfKind(tabA, 'terminate-engine')).toContainEqual(
+ expect.objectContaining({
+ ownerEpoch: 1,
+ reason: expect.stringContaining('invalid engine envelope'),
+ })
+ );
+ expect(router.snapshot()?.state).toMatchObject({
+ kind: 'activating',
+ ownerEpoch: 2,
+ databaseAction: 'wipe-before-open',
+ });
+ });
+
+ it('fails instead of clearing watchdogs for unexpected current engine-drained', async () => {
+ const router = new CoordinatorRouter({
+ verifyTabLockHeld: async () => true,
+ watchTabLock: () => () => {},
+ });
+ const tabA = new FakePort();
+ const tabB = new FakePort();
+ await register(router, tabA, 'tab-a');
+ await register(router, tabB, 'tab-b');
+ const engine = new FakePort();
+ await attach(router, tabA, 'tab-a', 1, engine);
+ ready(engine, 'tab-a', 1, 'opened-existing');
+
+ engine.receive({
+ ...version,
+ kind: 'engine-drained',
+ tabId: 'tab-a',
+ ownerEpoch: 1,
+ });
+ await Promise.resolve();
+
+ expect(messagesOfKind(tabA, 'terminate-engine')).toContainEqual(
+ expect.objectContaining({
+ reason: 'unexpected engine-drained from current direct route',
+ })
+ );
+ expect(router.snapshot()?.state).toMatchObject({
+ kind: 'activating',
+ ownerEpoch: 2,
+ databaseAction: 'wipe-before-open',
+ });
+ });
+
+ it('treats malformed current-engine messages as uncertain owner loss', async () => {
+ const router = new CoordinatorRouter({
+ verifyTabLockHeld: async () => true,
+ watchTabLock: () => () => {},
+ });
+ const tabA = new FakePort();
+ const tabB = new FakePort();
+ await register(router, tabA, 'tab-a');
+ await register(router, tabB, 'tab-b');
+ const engine = new FakePort();
+ await attach(router, tabA, 'tab-a', 1, engine);
+
+ engine.receive({ kind: 'engine-ready', ownerEpoch: 1 });
+ await Promise.resolve();
+
+ expect(messagesOfKind(tabA, 'terminate-engine')).toContainEqual(
+ expect.objectContaining({
+ reason: expect.stringContaining('invalid engine envelope'),
+ })
+ );
+ expect(router.snapshot()?.state).toMatchObject({
+ kind: 'activating',
+ ownerEpoch: 2,
+ databaseAction: 'wipe-before-open',
+ });
+ });
+});
diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-router.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-router.ts
new file mode 100644
index 0000000000..f0c6e83c65
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-router.ts
@@ -0,0 +1,1130 @@
+import type { CacheResponse } from '../protocol';
+import {
+ type CacheResetReason,
+ type CacheTelemetryRecorderLike,
+ classifyCacheError,
+ isolateCacheTelemetry,
+ NOOP_CACHE_TELEMETRY,
+ operationCategoryForRequest,
+} from '../telemetry';
+import { workerCacheTelemetry } from '../telemetry-relay';
+import {
+ type CoordinatorAction,
+ CoordinatorCore,
+ type CoordinatorSnapshot,
+} from './coordinator-core';
+import {
+ type ActivationFailureCode,
+ CACHE_COORDINATOR_PROTOCOL_VERSION,
+ type CoordinatorToEngineEnvelope,
+ type CoordinatorToTabEnvelope,
+ databaseOwnerLockName,
+ type EngineFatalCode,
+ type EngineOpenOutcome,
+ type TabToCoordinatorEnvelope,
+ tabLivenessLockName,
+ validateEngineToCoordinatorEnvelope,
+ validateTabToCoordinatorEnvelope,
+} from './coordinator-protocol';
+
+export type CoordinatorMessagePort = Pick<
+ MessagePort,
+ 'postMessage' | 'close' | 'start' | 'onmessage' | 'onmessageerror'
+>;
+
+export type CancelLivenessWatch = () => void;
+
+export interface CoordinatorRouterOptions {
+ activationTimeoutMs?: number;
+ heartbeatIntervalMs?: number;
+ heartbeatTimeoutMs?: number;
+ verifyTabLockHeld?: (lockName: string) => Promise<boolean>;
+ watchTabLock?: (
+ lockName: string,
+ onReleased: () => void
+ ) => CancelLivenessWatch;
+ setTimeout?: typeof globalThis.setTimeout;
+ clearTimeout?: typeof globalThis.clearTimeout;
+ queueMicrotask?: typeof globalThis.queueMicrotask;
+ telemetry?: CacheTelemetryRecorderLike;
+}
+
+type TabConnection = {
+ port: CoordinatorMessagePort;
+ cancelLivenessWatch: CancelLivenessWatch;
+};
+
+type PendingRegistration = { cancelled: boolean };
+
+type EngineRoute = {
+ tabId: string;
+ ownerEpoch: number;
+ port: CoordinatorMessagePort;
+};
+
+const DEFAULT_ACTIVATION_TIMEOUT_MS = 20_000;
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 2_000;
+const DEFAULT_HEARTBEAT_TIMEOUT_MS = 5_000;
+
+const resetReasonForOpenOutcome = (
+ outcome: EngineOpenOutcome
+): CacheResetReason => {
+ switch (outcome) {
+ case 'reset-incompatible':
+ return 'namespace-mismatch';
+ case 'reset-corrupt':
+ return 'integrity-failure';
+ case 'reset-storage-uncertain':
+ return 'storage-reset-required';
+ case 'opened-existing':
+ case 'opened-new':
+ return 'unknown';
+ }
+};
+
+type WithoutVersion<T> = T extends unknown
+ ? Omit<T, 'coordinatorVersion'>
+ : never;
+
+const envelope = <T extends { coordinatorVersion: 1 }>(
+ value: WithoutVersion<T>
+): T =>
+ ({
+ coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION,
+ ...value,
+ }) as unknown as T;
+
+/** Independently checks that registration cannot acquire the page-held lock. */
+export async function verifyTabLivenessLockHeld(
+ lockName: string
+): Promise<boolean> {
+ return await navigator.locks.request(
+ lockName,
+ { mode: 'exclusive', ifAvailable: true },
+ (lock) => lock === null
+ );
+}
+
+/** Waits for the page's liveness lock to be released or abandoned. */
+export function watchTabLivenessLock(
+ lockName: string,
+ onReleased: () => void
+): CancelLivenessWatch {
+ const abortController = new AbortController();
+ void navigator.locks
+ .request(
+ lockName,
+ { mode: 'exclusive', signal: abortController.signal },
+ (lock) => {
+ if (lock) onReleased();
+ }
+ )
+ .catch((error: unknown) => {
+ if (
+ !abortController.signal.aborted &&
+ (!(error instanceof DOMException) || error.name !== 'AbortError')
+ ) {
+ console.error('[graphql-cache] tab liveness watch failed');
+ }
+ });
+ return () => abortController.abort();
+}
+
+/** SharedWorker adapter around the deterministic coordinator state machine. */
+export class CoordinatorRouter {
+ private coreValue: CoordinatorCore | undefined;
+ private hotCapacity: number | undefined;
+ private readonly tabs = new Map<string, TabConnection>();
+ private readonly portTabs = new Map<CoordinatorMessagePort, string>();
+ private readonly pendingRegistrations = new Map<
+ CoordinatorMessagePort,
+ PendingRegistration
+ >();
+ private engineRoute: EngineRoute | undefined;
+ private activationTimer: ReturnType<typeof setTimeout> | undefined;
+ private heartbeatIntervalTimer: ReturnType<typeof setTimeout> | undefined;
+ private heartbeatTimeoutTimer: ReturnType<typeof setTimeout> | undefined;
+ private nextHeartbeatId = 1;
+ private pendingHeartbeat:
+ | { ownerEpoch: number; heartbeatId: number }
+ | undefined;
+
+ private readonly activationTimeoutMs: number;
+ private readonly heartbeatIntervalMs: number;
+ private readonly heartbeatTimeoutMs: number;
+ private readonly verifyTabLockHeld: (lockName: string) => Promise<boolean>;
+ private readonly watchTabLock: (
+ lockName: string,
+ onReleased: () => void
+ ) => CancelLivenessWatch;
+ private readonly setTimeoutFn: typeof globalThis.setTimeout;
+ private readonly clearTimeoutFn: typeof globalThis.clearTimeout;
+ private readonly queueMicrotaskFn: typeof globalThis.queueMicrotask;
+ private readonly telemetry: CacheTelemetryRecorderLike;
+ private readonly routeStarted = new Map<
+ number,
+ {
+ startedAt: number;
+ ownerEpoch: number;
+ category: ReturnType<typeof operationCategoryForRequest>;
+ }
+ >();
+ private readonly activationStarted = new Map<number, number>();
+ private readonly pendingRecoveryResetEpochs = new Map<
+ number,
+ CacheResetReason
+ >();
+ private nextRecoveryResetReason: CacheResetReason | undefined;
+ private readonly resetRequiredEpochs = new Set<number>();
+ private readonly now = (): number =>
+ globalThis.performance?.now() ?? Date.now();
+
+ constructor(options: CoordinatorRouterOptions = {}) {
+ this.activationTimeoutMs =
+ options.activationTimeoutMs ?? DEFAULT_ACTIVATION_TIMEOUT_MS;
+ this.heartbeatIntervalMs =
+ options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+ this.heartbeatTimeoutMs =
+ options.heartbeatTimeoutMs ?? DEFAULT_HEARTBEAT_TIMEOUT_MS;
+ this.verifyTabLockHeld =
+ options.verifyTabLockHeld ?? verifyTabLivenessLockHeld;
+ this.watchTabLock = options.watchTabLock ?? watchTabLivenessLock;
+ this.setTimeoutFn =
+ options.setTimeout ?? globalThis.setTimeout.bind(globalThis);
+ this.clearTimeoutFn =
+ options.clearTimeout ?? globalThis.clearTimeout.bind(globalThis);
+ this.queueMicrotaskFn =
+ options.queueMicrotask ?? globalThis.queueMicrotask.bind(globalThis);
+ this.telemetry = isolateCacheTelemetry(
+ options.telemetry ??
+ (typeof window === 'undefined'
+ ? workerCacheTelemetry()
+ : NOOP_CACHE_TELEMETRY)
+ );
+ }
+
+ get core(): CoordinatorCore | undefined {
+ return this.coreValue;
+ }
+
+ snapshot(): CoordinatorSnapshot | undefined {
+ return this.coreValue?.snapshot();
+ }
+
+ connect(port: CoordinatorMessagePort): void {
+ port.onmessage = (event: MessageEvent<unknown>) => {
+ void this.handleTabMessage(port, event.data, event.ports);
+ };
+ port.onmessageerror = () => {
+ const tabId = this.portTabs.get(port);
+ if (tabId) {
+ this.loseTab(tabId, 'tab MessagePort messageerror');
+ return;
+ }
+ const registration = this.pendingRegistrations.get(port);
+ if (registration) {
+ registration.cancelled = true;
+ if (this.pendingRegistrations.get(port) === registration) {
+ this.pendingRegistrations.delete(port);
+ }
+ }
+ port.close();
+ };
+ port.start();
+ }
+
+ async handleTabMessage(
+ port: CoordinatorMessagePort,
+ rawMessage: unknown,
+ transferredPorts: readonly MessagePort[] = []
+ ): Promise<void> {
+ const parsed = validateTabToCoordinatorEnvelope(rawMessage);
+ if (!parsed.ok) {
+ this.postProtocolError(port, parsed.error);
+ return;
+ }
+ const message = parsed.value;
+ const expectedPortCount = message.kind === 'attach-engine-port' ? 1 : 0;
+ if (transferredPorts.length !== expectedPortCount) {
+ for (const transferredPort of transferredPorts) transferredPort.close();
+ const tabId = this.portTabs.get(port);
+ if (message.kind === 'attach-engine-port' && tabId) {
+ this.failOwner(
+ tabId,
+ message.ownerEpoch,
+ 'engine attachment transferred the wrong number of ports'
+ );
+ } else {
+ this.postProtocolError(
+ port,
+ 'coordinator envelope transferred unexpected ports'
+ );
+ }
+ return;
+ }
+ if (message.kind === 'register-tab') {
+ await this.register(port, message);
+ return;
+ }
+
+ const tabId = this.portTabs.get(port);
+ if (!tabId) {
+ this.postProtocolError(port, 'message arrived before tab registration');
+ return;
+ }
+ if (message.tabId !== tabId) {
+ this.postProtocolError(
+ port,
+ 'message tab id does not match the registered port'
+ );
+ return;
+ }
+ const core = this.coreValue;
+ if (!core) {
+ this.postProtocolError(port, 'coordinator is not initialized');
+ return;
+ }
+
+ switch (message.kind) {
+ case 'cache-request':
+ this.applyActions(core.request(tabId, message.request));
+ break;
+ case 'attach-engine-port':
+ this.attachEnginePort(tabId, message.ownerEpoch, transferredPorts[0]);
+ break;
+ case 'graceful-departure':
+ this.applyActions(
+ core.beginGracefulDeparture(tabId, message.ownerEpoch)
+ );
+ break;
+ case 'engine-lost':
+ this.failOwner(tabId, message.ownerEpoch, message.reason);
+ break;
+ case 'disconnect-tab':
+ this.loseTab(tabId, message.reason);
+ break;
+ }
+ }
+
+ private async register(
+ port: CoordinatorMessagePort,
+ message: Extract<TabToCoordinatorEnvelope, { kind: 'register-tab' }>
+ ): Promise<void> {
+ if (this.portTabs.has(port) || this.pendingRegistrations.has(port)) {
+ this.postProtocolError(port, 'MessagePort already registered');
+ return;
+ }
+ if (this.tabs.has(message.tabId)) {
+ this.postProtocolError(port, 'tab id is already registered');
+ port.close();
+ return;
+ }
+ const expectedLockName = tabLivenessLockName(message.scope, message.tabId);
+ if (message.livenessLockName !== expectedLockName) {
+ this.postProtocolError(
+ port,
+ 'tab registered without the expected liveness-lock name'
+ );
+ port.close();
+ return;
+ }
+ if (this.coreValue && this.coreValue.scope !== message.scope) {
+ this.postProtocolError(port, 'coordinator scope mismatch');
+ port.close();
+ return;
+ }
+ if (this.coreValue && this.hotCapacity !== message.hotCapacity) {
+ this.postProtocolError(port, 'coordinator hot-capacity mismatch');
+ port.close();
+ return;
+ }
+
+ const registration: PendingRegistration = { cancelled: false };
+ this.pendingRegistrations.set(port, registration);
+ let lockHeld = false;
+ try {
+ lockHeld = await this.verifyTabLockHeld(message.livenessLockName);
+ } catch {
+ if (
+ registration.cancelled ||
+ this.pendingRegistrations.get(port) !== registration
+ ) {
+ return;
+ }
+ this.pendingRegistrations.delete(port);
+ this.postProtocolError(port, 'tab liveness-lock verification failed');
+ port.close();
+ return;
+ }
+ if (
+ registration.cancelled ||
+ this.pendingRegistrations.get(port) !== registration
+ ) {
+ return;
+ }
+ this.pendingRegistrations.delete(port);
+ if (!lockHeld) {
+ this.postProtocolError(
+ port,
+ 'tab registration requires an already-held liveness lock'
+ );
+ port.close();
+ return;
+ }
+ // Recheck after the asynchronous lock probe so concurrent registrations
+ // cannot race a duplicate tab or mismatched first scope into the router.
+ if (this.portTabs.has(port) || this.tabs.has(message.tabId)) {
+ this.postProtocolError(port, 'tab registration raced another port');
+ port.close();
+ return;
+ }
+ if (
+ this.coreValue &&
+ (this.coreValue.scope !== message.scope ||
+ this.hotCapacity !== message.hotCapacity)
+ ) {
+ this.postProtocolError(port, 'coordinator registration raced a mismatch');
+ port.close();
+ return;
+ }
+
+ if (!this.coreValue) {
+ this.coreValue = new CoordinatorCore(message.scope);
+ this.hotCapacity = message.hotCapacity;
+ }
+ let connection: TabConnection;
+ const cancelLivenessWatch = this.watchTabLock(
+ message.livenessLockName,
+ () => {
+ const current = this.tabs.get(message.tabId);
+ if (current && current === connection) {
+ this.loseTab(message.tabId, 'tab liveness lock was released');
+ }
+ }
+ );
+ connection = { port, cancelLivenessWatch };
+ this.tabs.set(message.tabId, connection);
+ this.portTabs.set(port, message.tabId);
+ this.postToTab(
+ message.tabId,
+ envelope<CoordinatorToTabEnvelope>({
+ kind: 'registered',
+ tabId: message.tabId,
+ })
+ );
+ this.applyActions(this.coreValue.registerTab(message.tabId));
+ }
+
+ private attachEnginePort(
+ tabId: string,
+ ownerEpoch: number,
+ transferredPort: MessagePort | undefined
+ ): void {
+ const core = this.coreValue;
+ if (
+ !core?.expectsEngine(tabId, ownerEpoch) ||
+ !transferredPort ||
+ this.engineRoute
+ ) {
+ transferredPort?.close();
+ if (core?.expectsEngine(tabId, ownerEpoch)) {
+ this.failOwner(tabId, ownerEpoch, 'invalid direct engine attachment');
+ } else {
+ this.postProtocolError(
+ this.tabs.get(tabId)?.port,
+ `stale engine port for epoch ${ownerEpoch}`
+ );
+ }
+ return;
+ }
+
+ const route: EngineRoute = {
+ tabId,
+ ownerEpoch,
+ port: transferredPort,
+ };
+ this.engineRoute = route;
+ transferredPort.onmessage = (event: MessageEvent<unknown>) => {
+ if (this.engineRoute !== route) return;
+ if (event.ports.length > 0) {
+ for (const port of event.ports) port.close();
+ this.failOwner(
+ tabId,
+ ownerEpoch,
+ 'engine envelope transferred an unexpected port'
+ );
+ return;
+ }
+ this.handleEngineMessage(route, event.data);
+ };
+ transferredPort.onmessageerror = () => {
+ if (this.engineRoute === route) {
+ this.failOwner(tabId, ownerEpoch, 'engine MessagePort messageerror');
+ }
+ };
+ transferredPort.start();
+ }
+
+ private handleEngineMessage(route: EngineRoute, rawMessage: unknown): void {
+ const parsed = validateEngineToCoordinatorEnvelope(rawMessage);
+ if (!parsed.ok) {
+ this.failOwner(
+ route.tabId,
+ route.ownerEpoch,
+ `invalid engine envelope: ${parsed.error}`
+ );
+ return;
+ }
+ const message = parsed.value;
+ const core = this.coreValue;
+ if (!core) return;
+ if (
+ message.ownerEpoch !== route.ownerEpoch ||
+ ('tabId' in message && message.tabId !== route.tabId)
+ ) {
+ this.failOwner(
+ route.tabId,
+ route.ownerEpoch,
+ 'engine envelope owner tuple does not match its direct route'
+ );
+ return;
+ }
+
+ switch (message.kind) {
+ case 'engine-ready': {
+ const actions = core.engineReady({
+ ...message,
+ expectedOwnerLockName: databaseOwnerLockName(core.scope),
+ });
+ const violated = actions.some(
+ (action) => action.kind === 'protocol-violation'
+ );
+ this.applyActions(actions);
+ if (violated) {
+ if (this.isCurrentOwner(route.tabId, route.ownerEpoch)) {
+ this.failOwner(
+ route.tabId,
+ route.ownerEpoch,
+ 'engine readiness proof was rejected'
+ );
+ } else {
+ this.postTerminateEngine(
+ route.tabId,
+ route.ownerEpoch,
+ 'engine readiness proof was rejected'
+ );
+ }
+ break;
+ }
+ if (
+ core.state.kind === 'active' &&
+ core.state.ownerEpoch === message.ownerEpoch
+ ) {
+ const recoveryResetReason = this.pendingRecoveryResetEpochs.get(
+ message.ownerEpoch
+ );
+ if (recoveryResetReason !== undefined) {
+ this.pendingRecoveryResetEpochs.delete(message.ownerEpoch);
+ this.recordLogicalResetAndWipe(
+ recoveryResetReason,
+ message.openOutcome
+ );
+ } else if (message.openOutcome.startsWith('reset-')) {
+ const resetReason = resetReasonForOpenOutcome(message.openOutcome);
+ this.recordStorageResetRequired(
+ message.ownerEpoch,
+ resetReason,
+ message.openOutcome
+ );
+ this.recordLogicalResetAndWipe(
+ resetReason,
+ message.openOutcome,
+ false
+ );
+ }
+ const startedAt = this.activationStarted.get(message.ownerEpoch);
+ this.activationStarted.delete(message.ownerEpoch);
+ this.telemetry.record({
+ name: 'graphql_cache.owner',
+ operationCategory: 'lifecycle',
+ outcome: 'success',
+ ownerEvent: 'activated',
+ durationMs:
+ startedAt === undefined ? undefined : this.now() - startedAt,
+ });
+ this.clearActivationTimer();
+ this.scheduleHeartbeat(message.ownerEpoch);
+ }
+ break;
+ }
+ case 'engine-response': {
+ const timing = this.routeStarted.get(message.routeId);
+ this.routeStarted.delete(message.routeId);
+ if (timing) {
+ this.telemetry.record({
+ name: 'graphql_cache.coordinator_request',
+ operationCategory: timing.category,
+ outcome: message.response.ok ? 'success' : 'error',
+ errorCode: message.response.ok
+ ? 'none'
+ : classifyCacheError(message.response.error),
+ durationMs: this.now() - timing.startedAt,
+ });
+ }
+ this.applyActions(
+ core.engineResponse(
+ message.ownerEpoch,
+ message.routeId,
+ message.response
+ )
+ );
+ break;
+ }
+ case 'engine-push':
+ this.applyActions(core.enginePush(message.ownerEpoch, message.push));
+ break;
+ case 'engine-drained': {
+ const actions = core.engineDrained(message.tabId, message.ownerEpoch);
+ if (actions.some((action) => action.kind === 'protocol-violation')) {
+ this.applyActions(actions);
+ this.failOwner(
+ route.tabId,
+ route.ownerEpoch,
+ 'unexpected engine-drained from current direct route'
+ );
+ break;
+ }
+ this.telemetry.record({
+ name: 'graphql_cache.owner',
+ operationCategory: 'lifecycle',
+ outcome: 'graceful',
+ ownerEvent: 'graceful-drain-completed',
+ });
+ this.applyActions(actions);
+ break;
+ }
+ case 'engine-fatal':
+ this.failOwner(
+ message.tabId,
+ message.ownerEpoch,
+ message.reason,
+ message.fatalCode
+ );
+ break;
+ case 'activation-failed':
+ this.failOwner(
+ message.tabId,
+ message.ownerEpoch,
+ message.reason,
+ undefined,
+ message.failureCode
+ );
+ break;
+ case 'heartbeat-ack':
+ this.acceptHeartbeat(message.ownerEpoch, message.heartbeatId);
+ break;
+ }
+ }
+
+ private applyActions(actions: CoordinatorAction[]): void {
+ const core = this.coreValue;
+ if (!core) return;
+ for (const action of actions) {
+ switch (action.kind) {
+ case 'elect-owner':
+ this.clearEngineWatchdogs();
+ this.activationStarted.set(action.ownerEpoch, this.now());
+ this.telemetry.record({
+ name: 'graphql_cache.owner',
+ operationCategory: 'lifecycle',
+ outcome: 'success',
+ ownerEvent: 'elected',
+ });
+ if (action.databaseAction === 'wipe-before-open') {
+ this.pendingRecoveryResetEpochs.set(
+ action.ownerEpoch,
+ this.nextRecoveryResetReason ?? 'abrupt-owner-loss'
+ );
+ this.nextRecoveryResetReason = undefined;
+ }
+ this.postToTab(
+ action.tabId,
+ envelope<CoordinatorToTabEnvelope>({
+ kind: 'become-owner',
+ scope: core.scope,
+ tabId: action.tabId,
+ ownerEpoch: action.ownerEpoch,
+ databaseAction: action.databaseAction,
+ ownerLockName: databaseOwnerLockName(core.scope),
+ hotCapacity: this.hotCapacity,
+ })
+ );
+ this.activationTimer = this.setTimeoutFn(() => {
+ this.failOwner(
+ action.tabId,
+ action.ownerEpoch,
+ 'engine activation watchdog timed out'
+ );
+ }, this.activationTimeoutMs);
+ break;
+ case 'route-request': {
+ this.routeStarted.set(action.routeId, {
+ startedAt: this.now(),
+ ownerEpoch: action.ownerEpoch,
+ category: operationCategoryForRequest(action.request),
+ });
+ const route = this.engineRoute;
+ if (
+ !route ||
+ route.tabId !== action.ownerTabId ||
+ route.ownerEpoch !== action.ownerEpoch
+ ) {
+ this.failOwner(
+ action.ownerTabId,
+ action.ownerEpoch,
+ 'direct engine MessagePort is missing'
+ );
+ break;
+ }
+ route.port.postMessage(
+ envelope<CoordinatorToEngineEnvelope>({
+ kind: 'engine-request',
+ ownerEpoch: action.ownerEpoch,
+ routeId: action.routeId,
+ request: action.request,
+ })
+ );
+ break;
+ }
+ case 'deliver-response':
+ this.postCacheResponse(action.tabId, action.response);
+ break;
+ case 'broadcast-push':
+ this.broadcast(
+ envelope<CoordinatorToTabEnvelope>({
+ kind: 'cache-message',
+ message: action.push,
+ })
+ );
+ break;
+ case 'reject-request':
+ this.postCacheResponse(action.tabId, {
+ id: action.requestId,
+ ok: false,
+ error: action.error,
+ ...(action.errorCode === undefined
+ ? {}
+ : { errorCode: action.errorCode }),
+ });
+ break;
+ case 'drain-owner': {
+ this.telemetry.record({
+ name: 'graphql_cache.owner',
+ operationCategory: 'lifecycle',
+ outcome: 'graceful',
+ ownerEvent: 'graceful-drain-started',
+ });
+ this.clearHeartbeatTimers();
+ const route = this.engineRoute;
+ if (
+ !route ||
+ route.tabId !== action.tabId ||
+ route.ownerEpoch !== action.ownerEpoch
+ ) {
+ this.failOwner(
+ action.tabId,
+ action.ownerEpoch,
+ 'direct engine MessagePort disappeared before drain'
+ );
+ break;
+ }
+ route.port.postMessage(
+ envelope<CoordinatorToEngineEnvelope>({
+ kind: 'drain-engine',
+ ownerEpoch: action.ownerEpoch,
+ })
+ );
+ break;
+ }
+ case 'close-engine-route':
+ this.clearEngineWatchdogs();
+ if (
+ this.engineRoute?.tabId === action.tabId &&
+ this.engineRoute.ownerEpoch === action.ownerEpoch
+ ) {
+ this.engineRoute.port.close();
+ this.engineRoute = undefined;
+ }
+ break;
+ case 'drop-tab':
+ this.removeTabConnection(action.tabId);
+ break;
+ case 'retire-tab':
+ this.postToTab(
+ action.tabId,
+ envelope<CoordinatorToTabEnvelope>({
+ kind: 'retire-complete',
+ tabId: action.tabId,
+ ownerEpoch: action.ownerEpoch,
+ })
+ );
+ this.removeTabConnection(action.tabId);
+ break;
+ case 'schedule-reset-activation':
+ this.queueMicrotaskFn(() => {
+ if (this.coreValue) {
+ this.applyActions(this.coreValue.resumeAfterLoss());
+ }
+ });
+ break;
+ case 'broadcast-engine-replaced':
+ this.telemetry.record({
+ name: 'graphql_cache.owner',
+ operationCategory: 'lifecycle',
+ outcome: 'success',
+ ownerEvent: 'replacement',
+ });
+ this.broadcast(
+ envelope<CoordinatorToTabEnvelope>({
+ kind: 'engine-replaced',
+ ownerEpoch: action.ownerEpoch,
+ })
+ );
+ break;
+ case 'drop-stale-engine-message':
+ this.telemetry.record({
+ name: 'graphql_cache.stale_drop',
+ operationCategory: 'lifecycle',
+ outcome: 'success',
+ errorCode: 'owner-lost',
+ count: 1,
+ });
+ break;
+ case 'protocol-violation':
+ this.telemetry.record({
+ name: 'graphql_cache.owner',
+ operationCategory: 'lifecycle',
+ outcome: 'error',
+ ownerEvent:
+ action.error.includes('already owns') ||
+ action.error.includes('multiple owner')
+ ? 'multiple-owner-detected'
+ : undefined,
+ errorCode: 'protocol',
+ });
+ this.broadcast(
+ envelope<CoordinatorToTabEnvelope>({
+ kind: 'protocol-error',
+ error: action.error,
+ })
+ );
+ break;
+ }
+ }
+ }
+
+ private failOwner(
+ tabId: string,
+ ownerEpoch: number,
+ reason: string,
+ fatalCode?: EngineFatalCode,
+ failureCode?: ActivationFailureCode
+ ): void {
+ const core = this.coreValue;
+ if (!core) return;
+ const actions = core.ownerLost(tabId, ownerEpoch, reason);
+ if (actions.length === 0) return;
+ this.activationStarted.delete(ownerEpoch);
+ const pendingReason = this.recordPendingResetFailure(
+ ownerEpoch,
+ reason,
+ failureCode
+ );
+ const resetReason =
+ pendingReason ??
+ (fatalCode === 'storage-reset-required'
+ ? 'storage-reset-required'
+ : 'abrupt-owner-loss');
+ this.nextRecoveryResetReason = resetReason;
+ if (pendingReason === undefined) {
+ this.recordStorageResetRequired(ownerEpoch, resetReason);
+ }
+ this.telemetry.record({
+ name: 'graphql_cache.owner',
+ operationCategory: 'lifecycle',
+ outcome: 'abrupt',
+ ownerEvent: 'abrupt-loss',
+ errorCode:
+ fatalCode === 'storage-reset-required'
+ ? 'storage-reset'
+ : classifyCacheError(reason),
+ });
+ for (const [routeId, timing] of this.routeStarted) {
+ if (timing.ownerEpoch !== ownerEpoch) continue;
+ this.routeStarted.delete(routeId);
+ this.telemetry.record({
+ name: 'graphql_cache.coordinator_request',
+ operationCategory: timing.category,
+ outcome: 'error',
+ errorCode: 'owner-lost',
+ durationMs: this.now() - timing.startedAt,
+ });
+ }
+ this.postTerminateEngine(tabId, ownerEpoch, reason);
+ this.clearEngineWatchdogs();
+ this.applyActions(actions);
+ }
+
+ private loseTab(tabId: string, reason: string): void {
+ const core = this.coreValue;
+ if (!core) return;
+ const state = core.state;
+ if (
+ state.kind !== 'waiting-for-tab' &&
+ state.kind !== 'resetting-after-loss' &&
+ state.tabId === tabId
+ ) {
+ this.activationStarted.delete(state.ownerEpoch);
+ const pendingReason = this.recordPendingResetFailure(
+ state.ownerEpoch,
+ reason
+ );
+ const resetReason = pendingReason ?? 'abrupt-owner-loss';
+ this.nextRecoveryResetReason = resetReason;
+ if (pendingReason === undefined) {
+ this.recordStorageResetRequired(state.ownerEpoch, resetReason);
+ }
+ this.telemetry.record({
+ name: 'graphql_cache.owner',
+ operationCategory: 'lifecycle',
+ outcome: 'abrupt',
+ ownerEvent: 'abrupt-loss',
+ errorCode: classifyCacheError(reason),
+ });
+ for (const [routeId, timing] of this.routeStarted) {
+ if (timing.ownerEpoch !== state.ownerEpoch) continue;
+ this.routeStarted.delete(routeId);
+ this.telemetry.record({
+ name: 'graphql_cache.coordinator_request',
+ operationCategory: timing.category,
+ outcome: 'error',
+ errorCode: 'owner-lost',
+ durationMs: this.now() - timing.startedAt,
+ });
+ }
+ // The page may still be alive after a liveness or MessagePort failure.
+ // Tell it to kill the orphanable DedicatedWorker before dropping its port.
+ this.postTerminateEngine(tabId, state.ownerEpoch, reason);
+ this.clearEngineWatchdogs();
+ }
+ this.applyActions(core.tabLost(tabId, reason));
+ }
+
+ private recordStorageResetRequired(
+ ownerEpoch: number,
+ resetReason: CacheResetReason,
+ openOutcome?: EngineOpenOutcome
+ ): void {
+ if (this.resetRequiredEpochs.has(ownerEpoch)) return;
+ this.resetRequiredEpochs.add(ownerEpoch);
+ this.telemetry.record({
+ name: 'graphql_cache.storage_reset_required',
+ operationCategory: 'storage',
+ outcome: 'error',
+ errorCode:
+ resetReason === 'namespace-mismatch'
+ ? 'schema'
+ : resetReason === 'integrity-failure'
+ ? 'integrity'
+ : 'storage-reset',
+ resetReason,
+ openOutcome,
+ });
+ }
+
+ private recordLogicalResetAndWipe(
+ resetReason: CacheResetReason,
+ openOutcome: EngineOpenOutcome,
+ coordinatorWipe = true
+ ): void {
+ this.telemetry.record({
+ name: 'graphql_cache.logical_reset',
+ operationCategory: 'storage',
+ outcome: 'success',
+ errorCode: 'none',
+ resetReason,
+ openOutcome,
+ });
+ this.telemetry.record({
+ name: 'graphql_cache.reset_wipe',
+ operationCategory: 'storage',
+ outcome: 'success',
+ errorCode: 'none',
+ resetReason,
+ openOutcome,
+ ...(coordinatorWipe ? { resetAttempt: 'wipe-before-open' as const } : {}),
+ });
+ }
+
+ private recordPendingResetFailure(
+ ownerEpoch: number,
+ reason: string,
+ failureCode?: ActivationFailureCode
+ ): CacheResetReason | undefined {
+ const resetReason = this.pendingRecoveryResetEpochs.get(ownerEpoch);
+ if (resetReason === undefined) return;
+ this.pendingRecoveryResetEpochs.delete(ownerEpoch);
+ this.telemetry.record({
+ name: 'graphql_cache.reset_wipe',
+ operationCategory: 'storage',
+ outcome: 'error',
+ errorCode:
+ failureCode === 'recovery-open-failed'
+ ? 'storage-reset'
+ : classifyCacheError(reason),
+ resetReason,
+ resetAttempt: 'wipe-before-open',
+ });
+ return resetReason;
+ }
+
+ private isCurrentOwner(tabId: string, ownerEpoch: number): boolean {
+ const state = this.coreValue?.state;
+ return Boolean(
+ state &&
+ state.kind !== 'waiting-for-tab' &&
+ state.kind !== 'resetting-after-loss' &&
+ state.tabId === tabId &&
+ state.ownerEpoch === ownerEpoch
+ );
+ }
+
+ private postTerminateEngine(
+ tabId: string,
+ ownerEpoch: number,
+ reason: string
+ ): void {
+ this.postToTab(
+ tabId,
+ envelope<CoordinatorToTabEnvelope>({
+ kind: 'terminate-engine',
+ tabId,
+ ownerEpoch,
+ reason,
+ })
+ );
+ }
+
+ private postCacheResponse(tabId: string, response: CacheResponse): void {
+ this.postToTab(
+ tabId,
+ envelope<CoordinatorToTabEnvelope>({
+ kind: 'cache-message',
+ message: response,
+ })
+ );
+ }
+
+ private postToTab(tabId: string, message: CoordinatorToTabEnvelope): void {
+ this.tabs.get(tabId)?.port.postMessage(message);
+ }
+
+ private broadcast(message: CoordinatorToTabEnvelope): void {
+ for (const connection of this.tabs.values()) {
+ connection.port.postMessage(message);
+ }
+ }
+
+ private postProtocolError(
+ port: CoordinatorMessagePort | undefined,
+ error: string
+ ): void {
+ port?.postMessage(
+ envelope<CoordinatorToTabEnvelope>({ kind: 'protocol-error', error })
+ );
+ }
+
+ private removeTabConnection(tabId: string): void {
+ const connection = this.tabs.get(tabId);
+ if (!connection) return;
+ this.tabs.delete(tabId);
+ this.portTabs.delete(connection.port);
+ connection.cancelLivenessWatch();
+ connection.port.close();
+ }
+
+ private scheduleHeartbeat(ownerEpoch: number): void {
+ this.clearHeartbeatTimers();
+ this.heartbeatIntervalTimer = this.setTimeoutFn(() => {
+ const route = this.engineRoute;
+ const state = this.coreValue?.state;
+ if (
+ !route ||
+ state?.kind !== 'active' ||
+ state.ownerEpoch !== ownerEpoch
+ ) {
+ return;
+ }
+ const heartbeatId = this.nextHeartbeatId++;
+ this.pendingHeartbeat = { ownerEpoch, heartbeatId };
+ route.port.postMessage(
+ envelope<CoordinatorToEngineEnvelope>({
+ kind: 'heartbeat',
+ ownerEpoch,
+ heartbeatId,
+ })
+ );
+ this.heartbeatTimeoutTimer = this.setTimeoutFn(() => {
+ if (
+ this.pendingHeartbeat?.ownerEpoch === ownerEpoch &&
+ this.pendingHeartbeat.heartbeatId === heartbeatId
+ ) {
+ this.failOwner(
+ route.tabId,
+ ownerEpoch,
+ 'engine heartbeat watchdog timed out'
+ );
+ }
+ }, this.heartbeatTimeoutMs);
+ }, this.heartbeatIntervalMs);
+ }
+
+ private acceptHeartbeat(ownerEpoch: number, heartbeatId: number): void {
+ if (
+ this.pendingHeartbeat?.ownerEpoch !== ownerEpoch ||
+ this.pendingHeartbeat.heartbeatId !== heartbeatId
+ ) {
+ return;
+ }
+ if (this.heartbeatTimeoutTimer !== undefined) {
+ this.clearTimeoutFn(this.heartbeatTimeoutTimer);
+ this.heartbeatTimeoutTimer = undefined;
+ }
+ this.pendingHeartbeat = undefined;
+ this.scheduleHeartbeat(ownerEpoch);
+ }
+
+ private clearActivationTimer(): void {
+ if (this.activationTimer !== undefined) {
+ this.clearTimeoutFn(this.activationTimer);
+ this.activationTimer = undefined;
+ }
+ }
+
+ private clearHeartbeatTimers(): void {
+ if (this.heartbeatIntervalTimer !== undefined) {
+ this.clearTimeoutFn(this.heartbeatIntervalTimer);
+ this.heartbeatIntervalTimer = undefined;
+ }
+ if (this.heartbeatTimeoutTimer !== undefined) {
+ this.clearTimeoutFn(this.heartbeatTimeoutTimer);
+ this.heartbeatTimeoutTimer = undefined;
+ }
+ this.pendingHeartbeat = undefined;
+ }
+
+ private clearEngineWatchdogs(): void {
+ this.clearActivationTimer();
+ this.clearHeartbeatTimers();
+ }
+}
diff --git a/apps/web/src/lib/graphql-cache/worker/wasm-module.ts b/apps/web/src/lib/graphql-cache/worker/wasm-module.ts
index 8c92128444..ce5f14f701 100644
--- a/apps/web/src/lib/graphql-cache/worker/wasm-module.ts
+++ b/apps/web/src/lib/graphql-cache/worker/wasm-module.ts
@@ -21,9 +21,43 @@ import type {
SelectedRecordPageWire,
WriteResult,
} from '../protocol';
+import { workerCacheTelemetry } from '../telemetry-relay';
+
+/** Stable, payload-free marker latched on reset-required WASM errors. */
+export interface CacheStorageResetRequiredError extends Error {
+ readonly cacheStorageResetRequired: true;
+}
+
+export type CacheOpenOutcome =
+ | 'opened-existing'
+ | 'opened-new'
+ | 'reset-incompatible'
+ | 'reset-corrupt'
+ | 'reset-storage-uncertain';
+
+export type CacheQueueDiagnostics =
+ | {
+ availability: 'available';
+ /** Decimal strings preserve Rust integer precision across wasm-bindgen. */
+ depth: string;
+ oldestCreatedAtMs: string | null;
+ }
+ | {
+ /** Compatibility engines must never masquerade as an empty queue. */
+ availability: 'unavailable';
+ depth: null;
+ oldestCreatedAtMs: null;
+ };
+
+export interface CacheOpenResult {
+ engine: CacheEngine;
+ outcome: CacheOpenOutcome;
+}
export interface CacheEngine {
boundIdentity(): Promise<string | null>;
+ /** Optional for compatibility engines; absence means unavailable. */
+ queueDiagnostics?(): Promise<CacheQueueDiagnostics>;
readQuery(
opId: string | undefined,
query: string,
@@ -99,33 +133,140 @@ export interface CacheEngine {
deleteKeys(keys: string[]): Promise<string[]>;
teardownOperation(opId: string): Promise<void>;
clear(): Promise<void>;
- /** Close the IndexedDB connection; call before destroyCache. */
+ /** Reset/recreate OPFS; concurrent calls wait for the fresh engine. */
+ physicalReset(): Promise<void>;
+ /** Gracefully close Turso/OPFS and release the owner lock. */
close(): Promise<void>;
}
export interface CacheWasmModule {
default: (input?: { module_or_path?: unknown }) => Promise<unknown>;
openCache(scope: string, hotCapacity?: number): Promise<CacheEngine>;
+ /** Additive open API with a coarse, payload-free recovery outcome. */
+ openCacheWithOutcome?(
+ scope: string,
+ hotCapacity?: number
+ ): Promise<CacheOpenResult>;
+ /** Atomically wipes before Turso open while retaining one OPFS owner lock. */
+ openCacheForRecovery(
+ scope: string,
+ hotCapacity?: number
+ ): Promise<CacheEngine>;
+ /** Additive recovery-open API with its coarse wipe outcome. */
+ openCacheForRecoveryWithOutcome?(
+ scope: string,
+ hotCapacity?: number
+ ): Promise<CacheOpenResult>;
destroyCache(scope: string): Promise<void>;
schemaHash(): string;
}
let modulePromise: Promise<CacheWasmModule> | undefined;
+let wasmMemory: WebAssembly.Memory | undefined;
+
+/** Returns the combined module's current unshared linear-memory allocation. */
+export function cacheWasmLinearMemoryBytes(): number {
+ if (!wasmMemory) throw new Error('cache WASM memory is not initialized');
+ return wasmMemory.buffer.byteLength;
+}
/** Loads and initializes the wasm module exactly once per worker context. */
export function loadCacheWasm(): Promise<CacheWasmModule> {
if (!modulePromise) {
- modulePromise = (async () => {
+ const initialization = (async () => {
+ const telemetry = workerCacheTelemetry();
+ const now = (): number => globalThis.performance?.now() ?? Date.now();
const url = new URL('../wasm/cache_wasm.js', import.meta.url).href;
const mod = (await import(/* @vite-ignore */ url)) as CacheWasmModule;
// Resolve the wasm binary explicitly: vite copies the generated JS as
// an opaque asset, so its internal relative `cache_wasm_bg.wasm` URL
// would 404 in production. This `new URL` pattern is statically
- // analyzable, so vite emits the binary as an asset and rewrites it.
+ // analyzable, so vite emits exactly one lazy hashed binary. Explicit
+ // fetch/compile keeps download, compile, and instantiate separately observable.
const wasmUrl = new URL('../wasm/cache_wasm_bg.wasm', import.meta.url);
- await mod.default({ module_or_path: wasmUrl });
- return mod;
+ const downloadStartedAt = now();
+ let bytes: ArrayBuffer;
+ try {
+ const response = await fetch(wasmUrl);
+ if (!response.ok) {
+ throw new Error(
+ `cache WASM download returned HTTP ${response.status}`
+ );
+ }
+ bytes = await response.arrayBuffer();
+ telemetry.record({
+ name: 'graphql_cache.wasm_download',
+ operationCategory: 'initialization',
+ outcome: 'success',
+ errorCode: 'none',
+ durationMs: now() - downloadStartedAt,
+ bytes: bytes.byteLength,
+ });
+ } catch (error) {
+ telemetry.record({
+ name: 'graphql_cache.wasm_download',
+ operationCategory: 'initialization',
+ outcome: 'error',
+ errorCode: 'wasm-download',
+ durationMs: now() - downloadStartedAt,
+ });
+ throw error;
+ }
+
+ const compileStartedAt = now();
+ let compiled: WebAssembly.Module;
+ try {
+ compiled = await WebAssembly.compile(bytes);
+ telemetry.record({
+ name: 'graphql_cache.wasm_compile',
+ operationCategory: 'initialization',
+ outcome: 'success',
+ errorCode: 'none',
+ durationMs: now() - compileStartedAt,
+ });
+ } catch (error) {
+ telemetry.record({
+ name: 'graphql_cache.wasm_compile',
+ operationCategory: 'initialization',
+ outcome: 'error',
+ errorCode: 'wasm-compile',
+ durationMs: now() - compileStartedAt,
+ });
+ throw error;
+ }
+
+ const instantiateStartedAt = now();
+ try {
+ const exports = (await mod.default({ module_or_path: compiled })) as {
+ memory?: WebAssembly.Memory;
+ };
+ if (!(exports.memory instanceof WebAssembly.Memory)) {
+ throw new Error('cache WASM did not export its linear memory');
+ }
+ wasmMemory = exports.memory;
+ telemetry.record({
+ name: 'graphql_cache.wasm_instantiate',
+ operationCategory: 'initialization',
+ outcome: 'success',
+ errorCode: 'none',
+ durationMs: now() - instantiateStartedAt,
+ });
+ return mod;
+ } catch (error) {
+ telemetry.record({
+ name: 'graphql_cache.wasm_instantiate',
+ operationCategory: 'initialization',
+ outcome: 'error',
+ errorCode: 'wasm-instantiate',
+ durationMs: now() - instantiateStartedAt,
+ });
+ throw error;
+ }
})();
+ modulePromise = initialization;
+ void initialization.catch(() => {
+ if (modulePromise === initialization) modulePromise = undefined;
+ });
}
return modulePromise;
}
diff --git a/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts b/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts
index 3a2b429151..3138363657 100644
--- a/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts
+++ b/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts
@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
const loadCacheWasmMock = vi.hoisted(() => vi.fn());
@@ -12,6 +12,10 @@ describe('CacheWorkerCore', () => {
vi.clearAllMocks();
});
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
it('dispatches read-records to the wasm engine', async () => {
const page: SelectedRecordPageWire = {
records: [{ id: 'item-1' }],
@@ -315,8 +319,8 @@ describe('CacheWorkerCore', () => {
'read:client:group-soup',
'read:client:child',
]);
- // Two read RPCs for the same active operation require one wasm call, so
- // the full denormalization and its IndexedDB get_batch work run once.
+ // Two read RPCs for the same active operation require one WASM call, so
+ // the full denormalization and its storage batch read run once.
expect(
readQuery.mock.calls.filter(([opId]) => opId === 'client:group-soup')
).toHaveLength(1);
@@ -586,4 +590,571 @@ describe('CacheWorkerCore', () => {
expect(messages).toContainEqual({ kind: 'cache-changed' });
});
+
+ it('drains earlier request responses before consuming close and rejects later admission', async () => {
+ const order: string[] = [];
+ let releaseRead!: () => void;
+ let markReadStarted!: () => void;
+ const readStarted = new Promise<void>((resolve) => {
+ markReadStarted = resolve;
+ });
+ const blocker = new Promise<void>((resolve) => {
+ releaseRead = resolve;
+ });
+ const readQuery = vi.fn(async () => {
+ order.push('read:start');
+ markReadStarted();
+ await blocker;
+ order.push('read:done');
+ return { kind: 'miss' as const };
+ });
+ const close = vi.fn(async () => {
+ order.push('close');
+ });
+ loadCacheWasmMock.mockResolvedValue({
+ openCache: vi.fn().mockResolvedValue({ readQuery, close }),
+ });
+ const messages: unknown[] = [];
+ const port = {
+ postMessage: (message: unknown) => {
+ messages.push(message);
+ if ((message as { id?: number }).id === 2) order.push('response');
+ },
+ };
+ const core = new CacheWorkerCore();
+ await core.handleRequest(port, {
+ id: 1,
+ kind: 'init',
+ scope: 'scope-1',
+ });
+
+ const read = core.handleRequest(port, {
+ id: 2,
+ kind: 'read',
+ query: 'query Read { value }',
+ });
+ await readStarted;
+ const drain = core.drain();
+ await core.handleRequest(port, {
+ id: 3,
+ kind: 'clear',
+ });
+ expect(messages).toContainEqual({
+ id: 3,
+ ok: false,
+ error: 'cache engine is draining',
+ });
+ expect(close).not.toHaveBeenCalled();
+
+ releaseRead();
+ await Promise.all([read, drain]);
+ expect(order).toEqual(['read:start', 'read:done', 'response', 'close']);
+ });
+
+ it('uses atomic recovery-open instead of opening before a reset', async () => {
+ const openCache = vi.fn();
+ const openCacheForRecovery = vi.fn().mockResolvedValue({});
+ loadCacheWasmMock.mockResolvedValue({
+ openCache,
+ openCacheForRecovery,
+ });
+ const messages: unknown[] = [];
+ const core = new CacheWorkerCore({ recoveryOpen: true });
+
+ await core.handleRequest(
+ { postMessage: (message: unknown) => messages.push(message) },
+ { id: 1, kind: 'init', scope: 'scope-1', hotCapacity: 17 }
+ );
+
+ expect(openCache).not.toHaveBeenCalled();
+ expect(openCacheForRecovery).toHaveBeenCalledWith('scope-1', 17);
+ expect(messages).toEqual([{ id: 1, ok: true, result: null }]);
+ });
+
+ it('rejects repeated init scope and exact optional capacity mismatches', async () => {
+ const openCache = vi.fn().mockResolvedValue({});
+ loadCacheWasmMock.mockResolvedValue({ openCache });
+ const messages: unknown[] = [];
+ const port = { postMessage: (message: unknown) => messages.push(message) };
+ const core = new CacheWorkerCore();
+
+ await core.handleRequest(port, {
+ id: 1,
+ kind: 'init',
+ scope: 'scope-1',
+ });
+ await core.handleRequest(port, {
+ id: 2,
+ kind: 'init',
+ scope: 'scope-1',
+ });
+ await core.handleRequest(port, {
+ id: 3,
+ kind: 'init',
+ scope: 'scope-2',
+ });
+ await core.handleRequest(port, {
+ id: 4,
+ kind: 'init',
+ scope: 'scope-1',
+ hotCapacity: 1,
+ });
+
+ expect(openCache).toHaveBeenCalledOnce();
+ expect(messages).toEqual([
+ { id: 1, ok: true, result: null },
+ { id: 2, ok: true, result: null },
+ {
+ id: 3,
+ ok: false,
+ error:
+ 'cache worker already initialized for scope scope-1, got scope-2',
+ },
+ {
+ id: 4,
+ ok: false,
+ error:
+ 'cache worker already initialized with hot capacity undefined, got 1',
+ },
+ ]);
+
+ const capacityMessages: unknown[] = [];
+ const capacityCore = new CacheWorkerCore();
+ await capacityCore.handleRequest(
+ { postMessage: (message: unknown) => capacityMessages.push(message) },
+ { id: 5, kind: 'init', scope: 'scope-1', hotCapacity: 2 }
+ );
+ await capacityCore.handleRequest(
+ { postMessage: (message: unknown) => capacityMessages.push(message) },
+ { id: 6, kind: 'init', scope: 'scope-1' }
+ );
+ expect(capacityMessages.at(-1)).toEqual({
+ id: 6,
+ ok: false,
+ error:
+ 'cache worker already initialized with hot capacity 2, got undefined',
+ });
+ });
+
+ it('refreshes queue diagnostics only at bounded checkpoints and recalculates cached age on heartbeat/drain', async () => {
+ let monotonicNow = 0;
+ let wallClockNow = 1_000;
+ const queueDiagnostics = vi.fn().mockResolvedValue({
+ availability: 'available',
+ depth: '2',
+ oldestCreatedAtMs: '900',
+ });
+ const close = vi.fn().mockResolvedValue(undefined);
+ const writeQuery = vi.fn().mockResolvedValue({
+ changed: [],
+ affectedOps: [],
+ reset: false,
+ });
+ loadCacheWasmMock.mockResolvedValue({
+ openCacheWithOutcome: vi.fn().mockResolvedValue({
+ engine: { queueDiagnostics, close, writeQuery },
+ outcome: 'opened-new',
+ }),
+ });
+ const observations: Array<Record<string, unknown>> = [];
+ const core = new CacheWorkerCore({
+ monotonicNow: () => monotonicNow,
+ wallClockNow: () => wallClockNow,
+ queueDiagnosticsIntervalMs: 60_000,
+ telemetry: {
+ record: (observation) => observations.push(observation),
+ flush: vi.fn(),
+ },
+ });
+ const port = { postMessage: vi.fn() };
+ await core.handleRequest(port, { id: 1, kind: 'init', scope: 'scope-1' });
+ monotonicNow = 1;
+ await core.handleRequest(port, {
+ id: 2,
+ kind: 'write',
+ query: 'query Read { value }',
+ data: { value: true },
+ });
+ await Promise.resolve();
+ expect(queueDiagnostics).toHaveBeenCalledTimes(1);
+
+ wallClockNow = 1_500;
+ core.recordCachedQueueDiagnostics();
+ expect(queueDiagnostics).toHaveBeenCalledTimes(1);
+ monotonicNow = 60_001;
+ await core.handleRequest(port, {
+ id: 3,
+ kind: 'write',
+ query: 'query Read { value }',
+ data: { value: false },
+ });
+ await vi.waitFor(() =>
+ expect(
+ observations.filter(
+ (observation) =>
+ observation.name === 'graphql_cache.queue_diagnostics' &&
+ observation.outcome === 'success'
+ )
+ ).toHaveLength(3)
+ );
+ wallClockNow = 2_000;
+ await core.drain();
+ expect(queueDiagnostics).toHaveBeenCalledTimes(2);
+ expect(
+ observations
+ .filter(
+ (observation) =>
+ observation.name === 'graphql_cache.queue_diagnostics' &&
+ observation.outcome === 'success'
+ )
+ .map(({ queueDepth, oldestAgeMs, queueDiagnosticsAvailability }) => ({
+ queueDepth,
+ oldestAgeMs,
+ queueDiagnosticsAvailability,
+ }))
+ ).toEqual([
+ {
+ queueDepth: 2,
+ oldestAgeMs: 100,
+ queueDiagnosticsAvailability: 'available',
+ },
+ {
+ queueDepth: 2,
+ oldestAgeMs: 600,
+ queueDiagnosticsAvailability: 'available',
+ },
+ {
+ queueDepth: 2,
+ oldestAgeMs: 600,
+ queueDiagnosticsAvailability: 'available',
+ },
+ {
+ queueDepth: 2,
+ oldestAgeMs: 1_100,
+ queueDiagnosticsAvailability: 'available',
+ },
+ ]);
+ });
+
+ it('marks compatibility diagnostics unavailable instead of authoritative empty', async () => {
+ loadCacheWasmMock.mockResolvedValue({
+ openCache: vi.fn().mockResolvedValue({ close: vi.fn() }),
+ });
+ const observations: Array<Record<string, unknown>> = [];
+ const core = new CacheWorkerCore({
+ telemetry: {
+ record: (observation) => observations.push(observation),
+ flush: vi.fn(),
+ },
+ });
+ await core.handleRequest(
+ { postMessage: vi.fn() },
+ { id: 1, kind: 'init', scope: 'compatibility' }
+ );
+ expect(observations).toContainEqual(
+ expect.objectContaining({
+ name: 'graphql_cache.queue_diagnostics',
+ outcome: 'success',
+ queueDiagnosticsAvailability: 'unavailable',
+ })
+ );
+ expect(observations).not.toContainEqual(
+ expect.objectContaining({
+ name: 'graphql_cache.queue_diagnostics',
+ queueDepth: 0,
+ })
+ );
+ });
+
+ it('serializes a hanging refresh away from correctness and bounds it without changing results', async () => {
+ vi.useFakeTimers();
+ let monotonicNow = 0;
+ const queueDiagnostics = vi
+ .fn()
+ .mockResolvedValueOnce({
+ availability: 'available',
+ depth: '1',
+ oldestCreatedAtMs: '10',
+ })
+ .mockImplementation(() => new Promise(() => {}));
+ const readQuery = vi.fn().mockResolvedValue({ kind: 'miss' });
+ const writeQuery = vi.fn().mockResolvedValue({
+ changed: [],
+ affectedOps: [],
+ reset: false,
+ });
+ loadCacheWasmMock.mockResolvedValue({
+ openCache: vi.fn().mockResolvedValue({
+ queueDiagnostics,
+ readQuery,
+ writeQuery,
+ close: vi.fn(),
+ }),
+ });
+ const observations: Array<Record<string, unknown>> = [];
+ const port = { postMessage: vi.fn() };
+ const core = new CacheWorkerCore({
+ monotonicNow: () => monotonicNow,
+ queueDiagnosticsIntervalMs: 0,
+ queueDiagnosticsTimeoutMs: 20,
+ telemetry: {
+ record: (observation) => observations.push(observation),
+ flush: vi.fn(),
+ },
+ });
+ await core.handleRequest(port, { id: 1, kind: 'init', scope: 'scope' });
+ monotonicNow = 1;
+ await core.handleRequest(port, {
+ id: 2,
+ kind: 'write',
+ query: 'query Read { value }',
+ data: { value: true },
+ });
+ await vi.waitFor(() => expect(queueDiagnostics).toHaveBeenCalledTimes(2));
+ const read = core.handleRequest(port, {
+ id: 3,
+ kind: 'read',
+ query: 'query Read { value }',
+ });
+ expect(readQuery).not.toHaveBeenCalled();
+ await vi.advanceTimersByTimeAsync(20);
+ await read;
+ expect(readQuery).toHaveBeenCalledOnce();
+ expect(port.postMessage).toHaveBeenCalledWith({
+ id: 3,
+ ok: true,
+ result: { kind: 'miss' },
+ });
+ expect(observations).toContainEqual(
+ expect.objectContaining({
+ name: 'graphql_cache.queue_diagnostics',
+ outcome: 'error',
+ errorCode: 'timeout',
+ })
+ );
+ });
+
+ it('keeps the latest snapshot after diagnostic errors and cancels hangs before drain', async () => {
+ const resetError = Object.assign(new Error('diagnostic reset marker'), {
+ cacheStorageResetRequired: true as const,
+ });
+ const queueDiagnostics = vi
+ .fn()
+ .mockResolvedValueOnce({
+ availability: 'available',
+ depth: '3',
+ oldestCreatedAtMs: '100',
+ })
+ .mockRejectedValueOnce(resetError)
+ .mockImplementation(() => new Promise(() => {}));
+ const writeQuery = vi.fn().mockResolvedValue({
+ changed: [],
+ affectedOps: [],
+ reset: false,
+ });
+ const close = vi.fn().mockResolvedValue(undefined);
+ loadCacheWasmMock.mockResolvedValue({
+ openCache: vi.fn().mockResolvedValue({
+ queueDiagnostics,
+ writeQuery,
+ close,
+ }),
+ });
+ const onStorageResetRequired = vi.fn();
+ const observations: Array<Record<string, unknown>> = [];
+ const core = new CacheWorkerCore({
+ queueDiagnosticsIntervalMs: 0,
+ queueDiagnosticsTimeoutMs: 30_000,
+ wallClockNow: () => 200,
+ onStorageResetRequired,
+ telemetry: {
+ record: (observation) => observations.push(observation),
+ flush: vi.fn(),
+ },
+ });
+ const port = { postMessage: vi.fn() };
+ await core.handleRequest(port, { id: 1, kind: 'init', scope: 'scope' });
+ await core.handleRequest(port, {
+ id: 2,
+ kind: 'write',
+ query: 'query Read { value }',
+ data: { value: true },
+ });
+ await vi.waitFor(() =>
+ expect(observations).toContainEqual(
+ expect.objectContaining({
+ name: 'graphql_cache.queue_diagnostics',
+ outcome: 'error',
+ })
+ )
+ );
+ core.recordCachedQueueDiagnostics();
+ expect(onStorageResetRequired).not.toHaveBeenCalled();
+ expect(observations).toContainEqual(
+ expect.objectContaining({
+ name: 'graphql_cache.queue_diagnostics',
+ outcome: 'error',
+ })
+ );
+ expect(observations.at(-1)).toMatchObject({
+ name: 'graphql_cache.queue_diagnostics',
+ outcome: 'success',
+ queueDiagnosticsAvailability: 'available',
+ queueDepth: 3,
+ oldestAgeMs: 100,
+ });
+
+ await core.handleRequest(port, {
+ id: 3,
+ kind: 'write',
+ query: 'query Read { value }',
+ data: { value: false },
+ });
+ await vi.waitFor(() => expect(queueDiagnostics).toHaveBeenCalledTimes(3));
+ await expect(core.drain()).resolves.toBeUndefined();
+ expect(close).toHaveBeenCalledOnce();
+ expect(onStorageResetRequired).not.toHaveBeenCalled();
+ });
+
+ it('reports the initialization outcome but leaves every reset phase to the coordinator', async () => {
+ const observations: Array<Record<string, unknown>> = [];
+ loadCacheWasmMock.mockResolvedValue({
+ openCacheWithOutcome: vi.fn().mockResolvedValue({
+ engine: {
+ queueDiagnostics: vi.fn().mockResolvedValue({
+ availability: 'available',
+ depth: '0',
+ oldestCreatedAtMs: null,
+ }),
+ },
+ outcome: 'reset-corrupt',
+ }),
+ });
+ const onInitializationOutcome = vi.fn();
+ const core = new CacheWorkerCore({
+ onInitializationOutcome,
+ telemetry: {
+ record: (observation) => observations.push(observation),
+ flush: vi.fn(),
+ },
+ });
+ await core.handleRequest(
+ { postMessage: vi.fn() },
+ { id: 1, kind: 'init', scope: 'scope-1' }
+ );
+
+ expect(onInitializationOutcome).toHaveBeenCalledOnce();
+ expect(onInitializationOutcome).toHaveBeenCalledWith('reset-corrupt');
+ expect(
+ observations.filter((observation) =>
+ [
+ 'graphql_cache.storage_reset_required',
+ 'graphql_cache.logical_reset',
+ 'graphql_cache.reset_wipe',
+ ].includes(String(observation.name))
+ )
+ ).toEqual([]);
+ expect(observations).toContainEqual(
+ expect.objectContaining({
+ name: 'graphql_cache.schema_init',
+ openOutcome: 'reset-corrupt',
+ })
+ );
+ });
+
+ it('leaves recovery-open wipe authority with the coordinator', async () => {
+ const observations: Array<Record<string, unknown>> = [];
+ loadCacheWasmMock.mockResolvedValue({
+ openCacheForRecoveryWithOutcome: vi.fn().mockResolvedValue({
+ engine: {
+ queueDiagnostics: vi.fn().mockResolvedValue({
+ availability: 'available',
+ depth: '0',
+ oldestCreatedAtMs: null,
+ }),
+ },
+ outcome: 'reset-storage-uncertain',
+ }),
+ });
+ const onInitializationOutcome = vi.fn();
+ const core = new CacheWorkerCore({
+ recoveryOpen: true,
+ onInitializationOutcome,
+ telemetry: {
+ record: (observation) => observations.push(observation),
+ flush: vi.fn(),
+ },
+ });
+ await core.handleRequest(
+ { postMessage: vi.fn() },
+ { id: 1, kind: 'init', scope: 'scope-1' }
+ );
+ expect(onInitializationOutcome).toHaveBeenCalledWith(
+ 'reset-storage-uncertain'
+ );
+ expect(
+ observations.filter((observation) =>
+ [
+ 'graphql_cache.storage_reset_required',
+ 'graphql_cache.logical_reset',
+ 'graphql_cache.reset_wipe',
+ ].includes(String(observation.name))
+ )
+ ).toEqual([]);
+ });
+
+ it('reports a latched storage-reset marker once before returning failures', async () => {
+ const resetError = Object.assign(
+ new Error('cache storage reset required'),
+ {
+ cacheStorageResetRequired: true as const,
+ }
+ );
+ const readQuery = vi.fn().mockRejectedValue(resetError);
+ loadCacheWasmMock.mockResolvedValue({
+ openCache: vi.fn().mockResolvedValue({ readQuery }),
+ });
+ const onStorageResetRequired = vi.fn();
+ const observations: Array<Record<string, unknown>> = [];
+ const messages: unknown[] = [];
+ const port = { postMessage: (message: unknown) => messages.push(message) };
+ const core = new CacheWorkerCore({
+ onStorageResetRequired,
+ telemetry: {
+ record: (observation) => observations.push(observation),
+ flush: vi.fn(),
+ },
+ });
+ await core.handleRequest(port, {
+ id: 1,
+ kind: 'init',
+ scope: 'scope-1',
+ });
+
+ await core.handleRequest(port, {
+ id: 2,
+ kind: 'read',
+ query: 'query Read { value }',
+ });
+ await core.handleRequest(port, {
+ id: 3,
+ kind: 'read',
+ query: 'query ReadAgain { value }',
+ });
+
+ expect(onStorageResetRequired).toHaveBeenCalledTimes(1);
+ expect(onStorageResetRequired).toHaveBeenCalledWith(resetError);
+ expect(
+ observations.filter((observation) =>
+ [
+ 'graphql_cache.storage_reset_required',
+ 'graphql_cache.reset_wipe',
+ ].includes(String(observation.name))
+ )
+ ).toEqual([]);
+ expect(messages.slice(-2)).toEqual([
+ { id: 2, ok: false, error: 'cache storage reset required' },
+ { id: 3, ok: false, error: 'cache storage reset required' },
+ ]);
+ });
});
diff --git a/apps/web/src/lib/graphql-cache/worker/worker-core.ts b/apps/web/src/lib/graphql-cache/worker/worker-core.ts
index 5b0160b5ee..502a72d888 100644
--- a/apps/web/src/lib/graphql-cache/worker/worker-core.ts
+++ b/apps/web/src/lib/graphql-cache/worker/worker-core.ts
@@ -1,6 +1,6 @@
/**
- * SharedWorker core: owns the browser's single wasm engine, serves the RPC
- * protocol to page ports, and fans out invalidations.
+ * Dedicated engine-worker core: owns the elected browser WASM engine, serves
+ * coordinator-routed RPCs, and fans out invalidations.
*/
import { match } from 'ts-pattern';
@@ -13,7 +13,18 @@ import type {
SelectedRecordPageWire,
WriteResult,
} from '../protocol';
-import { type CacheEngine, loadCacheWasm } from './wasm-module';
+import {
+ type CacheTelemetryRecorderLike,
+ classifyCacheError,
+ isolateCacheTelemetry,
+ isStorageTransactionRequest,
+ operationCategoryForRequest,
+} from '../telemetry';
+import {
+ type CacheEngine,
+ type CacheOpenOutcome,
+ loadCacheWasm,
+} from './wasm-module';
type PortLike = {
postMessage(msg: unknown): void;
@@ -31,6 +42,21 @@ type QueuedEngineRequest = {
waiters: RequestWaiter[];
};
+export interface CacheWorkerCoreOptions {
+ /** Atomically recovery-wipes before any Turso open during initialization. */
+ recoveryOpen?: boolean;
+ /** Called once when WASM latches a reset-required storage failure. */
+ onStorageResetRequired?: (error: Error) => void;
+ /** Reports the bounded open outcome to the coordinator transport. */
+ onInitializationOutcome?: (outcome: CacheOpenOutcome) => void;
+ telemetry?: CacheTelemetryRecorderLike;
+ /** Injectable clocks and cadence for payload-free diagnostics tests. */
+ monotonicNow?: () => number;
+ wallClockNow?: () => number;
+ queueDiagnosticsIntervalMs?: number;
+ queueDiagnosticsTimeoutMs?: number;
+}
+
const NORMAL_READ_PRIORITY = 0;
const USER_VISIBLE_READ_PRIORITY = 1;
const CACHE_WRITE_PRIORITY = 2;
@@ -83,7 +109,33 @@ export class CacheWorkerCore {
/** Serializes engine calls while allowing safe read prioritization. */
private readonly queue: QueuedEngineRequest[] = [];
private running = false;
+ private acceptingRequests = true;
+ private activeRequestHandlers = 0;
+ private readonly drainWaiters = new Set<() => void>();
+ private resetRequiredReported = false;
+ private hotCapacity: number | undefined;
private readonly ports = new Set<PortLike>();
+ private readonly telemetry: CacheTelemetryRecorderLike;
+ private readonly now: () => number;
+ private readonly wallClockNow: () => number;
+ private readonly queueDiagnosticsIntervalMs: number;
+ private readonly queueDiagnosticsTimeoutMs: number;
+ private lastQueueDiagnosticsAt = Number.NEGATIVE_INFINITY;
+ private latestQueueDiagnostics:
+ | { depth: number; oldestCreatedAtMs?: number }
+ | undefined;
+ private cancelQueueDiagnostics: (() => void) | undefined;
+
+ constructor(private readonly options: CacheWorkerCoreOptions = {}) {
+ this.telemetry = isolateCacheTelemetry(options.telemetry);
+ this.now =
+ options.monotonicNow ??
+ (() => globalThis.performance?.now() ?? Date.now());
+ this.wallClockNow = options.wallClockNow ?? (() => Date.now());
+ this.queueDiagnosticsIntervalMs =
+ options.queueDiagnosticsIntervalMs ?? 60_000;
+ this.queueDiagnosticsTimeoutMs = options.queueDiagnosticsTimeoutMs ?? 250;
+ }
addPort(port: PortLike): void {
this.ports.add(port);
@@ -95,15 +147,127 @@ export class CacheWorkerCore {
async handleRequest(port: PortLike, request: CacheRequest): Promise<void> {
const respond = (response: CacheResponse) => port.postMessage(response);
+ const startedAt = this.now();
+ const category = operationCategoryForRequest(request);
+ if (!this.acceptingRequests) {
+ this.telemetry.record({
+ name: 'graphql_cache.engine_request',
+ operationCategory: category,
+ outcome: 'error',
+ errorCode: 'owner-lost',
+ durationMs: this.now() - startedAt,
+ });
+ respond({
+ id: request.id,
+ ok: false,
+ error: 'cache engine is draining',
+ });
+ return;
+ }
+
+ this.activeRequestHandlers += 1;
try {
const result = await this.enqueue(request);
+ const durationMs = this.now() - startedAt;
+ this.telemetry.record({
+ name: 'graphql_cache.engine_request',
+ operationCategory: category,
+ outcome: 'success',
+ errorCode: 'none',
+ durationMs,
+ });
+ if (isStorageTransactionRequest(request)) {
+ this.telemetry.record({
+ name: 'graphql_cache.transaction',
+ operationCategory: category,
+ outcome: 'success',
+ errorCode: 'none',
+ durationMs,
+ });
+ }
+ if (
+ request.kind === 'write' &&
+ typeof result === 'object' &&
+ result !== null &&
+ 'reset' in result &&
+ result.reset === true
+ ) {
+ this.telemetry.record({
+ name: 'graphql_cache.logical_reset',
+ operationCategory: 'storage',
+ outcome: 'success',
+ errorCode: 'none',
+ resetReason: 'identity-change',
+ });
+ }
+ if (request.kind === 'read') {
+ this.telemetry.record({
+ name: 'graphql_cache.read',
+ operationCategory: 'read',
+ outcome:
+ typeof result === 'object' &&
+ result !== null &&
+ 'kind' in result &&
+ result.kind === 'hit'
+ ? 'hit'
+ : 'miss',
+ durationMs,
+ });
+ }
respond({ id: request.id, ok: true, result });
} catch (error) {
+ const durationMs = this.now() - startedAt;
+ const errorCode = classifyCacheError(error);
+ this.telemetry.record({
+ name: 'graphql_cache.engine_request',
+ operationCategory: category,
+ outcome: 'error',
+ errorCode,
+ durationMs,
+ });
+ if (isStorageTransactionRequest(request)) {
+ this.telemetry.record({
+ name: 'graphql_cache.transaction',
+ operationCategory: category,
+ outcome: 'error',
+ errorCode,
+ durationMs,
+ });
+ }
+ this.reportResetRequired(error);
respond({
id: request.id,
ok: false,
error: error instanceof Error ? error.message : String(error),
});
+ } finally {
+ this.activeRequestHandlers -= 1;
+ this.resolveDrainWaitersIfIdle();
+ }
+ }
+
+ /** Stops admission, drains every earlier request/response, then closes OPFS. */
+ async drain(): Promise<void> {
+ this.acceptingRequests = false;
+ // A best-effort observation may never delay correctness teardown.
+ this.cancelQueueDiagnostics?.();
+ if (
+ this.activeRequestHandlers > 0 ||
+ this.running ||
+ this.queue.length > 0
+ ) {
+ await new Promise<void>((resolve) => this.drainWaiters.add(resolve));
+ }
+ if (this.initPromise) await this.initPromise.catch(() => undefined);
+ const engine = this.engine;
+ if (!engine) return;
+ this.recordCachedQueueDiagnostics();
+ this.engine = undefined;
+ try {
+ await engine.close();
+ } catch (error) {
+ this.reportResetRequired(error);
+ throw error;
}
}
@@ -129,7 +293,7 @@ export class CacheWorkerCore {
if (duplicate) {
duplicate.priority = Math.max(duplicate.priority, priority);
duplicate.waiters.push({ resolve, reject });
- this.drain();
+ this.drainQueue();
return;
}
}
@@ -140,7 +304,7 @@ export class CacheWorkerCore {
readSignature: signature,
waiters: [{ resolve, reject }],
});
- this.drain();
+ this.drainQueue();
});
}
@@ -149,7 +313,7 @@ export class CacheWorkerCore {
* Cache-view writes retain FIFO order with each other; overlapping reads
* may observe the newer state, which is linearizable and avoids stale work.
*/
- private drain(): void {
+ private drainQueue(): void {
if (this.running || this.queue.length === 0) return;
let segmentEnd = this.queue.findIndex((queued) =>
@@ -173,8 +337,12 @@ export class CacheWorkerCore {
this.running = true;
void this.dispatch(queued.request)
.then(
- (result) => {
+ async (result) => {
+ // Resolve the cache result before the bounded observation checkpoint.
for (const waiter of queued.waiters) waiter.resolve(result);
+ if (isStorageTransactionRequest(queued.request)) {
+ await this.refreshQueueDiagnostics(false);
+ }
},
(error) => {
for (const waiter of queued.waiters) waiter.reject(error);
@@ -182,7 +350,8 @@ export class CacheWorkerCore {
)
.finally(() => {
this.running = false;
- this.drain();
+ this.drainQueue();
+ this.resolveDrainWaitersIfIdle();
});
}
@@ -359,26 +528,237 @@ export class CacheWorkerCore {
.exhaustive();
}
+ /** Emits the latest successful snapshot without touching storage. */
+ recordCachedQueueDiagnostics(): void {
+ const snapshot = this.latestQueueDiagnostics;
+ this.telemetry.record({
+ name: 'graphql_cache.queue_diagnostics',
+ operationCategory: 'queue',
+ outcome: 'success',
+ errorCode: 'none',
+ queueDiagnosticsAvailability: snapshot ? 'available' : 'unavailable',
+ ...(snapshot
+ ? {
+ queueDepth: snapshot.depth,
+ oldestAgeMs:
+ snapshot.oldestCreatedAtMs === undefined
+ ? 0
+ : Math.max(0, this.wallClockNow() - snapshot.oldestCreatedAtMs),
+ }
+ : {}),
+ });
+ }
+
+ /** Refreshes diagnostics only at serialized initialization/mutation checkpoints. */
+ private async refreshQueueDiagnostics(force: boolean): Promise<void> {
+ const observedAt = this.now();
+ if (
+ !force &&
+ observedAt - this.lastQueueDiagnosticsAt < this.queueDiagnosticsIntervalMs
+ ) {
+ return;
+ }
+ this.lastQueueDiagnosticsAt = observedAt;
+ const engine = this.engine;
+ if (!engine || typeof engine.queueDiagnostics !== 'function') {
+ this.recordCachedQueueDiagnostics();
+ return;
+ }
+
+ const queueDiagnostics = engine.queueDiagnostics.bind(engine);
+ let cancel!: () => void;
+ const cancelled = new Promise<{ kind: 'cancelled' }>((resolve) => {
+ cancel = () => resolve({ kind: 'cancelled' });
+ });
+ this.cancelQueueDiagnostics = cancel;
+ const attempt = Promise.resolve()
+ .then(() => queueDiagnostics())
+ .then(
+ (value) => ({ kind: 'result' as const, value }),
+ (error: unknown) => ({ kind: 'error' as const, error })
+ );
+ let timeout: ReturnType<typeof setTimeout> | undefined;
+ const timedOut = new Promise<{ kind: 'timeout' }>((resolve) => {
+ timeout = setTimeout(
+ () => resolve({ kind: 'timeout' }),
+ this.queueDiagnosticsTimeoutMs
+ );
+ });
+
+ try {
+ const outcome = await Promise.race([attempt, timedOut, cancelled]);
+ if (outcome.kind === 'cancelled') return;
+ if (outcome.kind === 'timeout') {
+ this.telemetry.record({
+ name: 'graphql_cache.queue_diagnostics',
+ operationCategory: 'queue',
+ outcome: 'error',
+ errorCode: 'timeout',
+ queueDiagnosticsAvailability: this.latestQueueDiagnostics
+ ? 'available'
+ : 'unavailable',
+ });
+ return;
+ }
+ if (outcome.kind === 'error') {
+ this.telemetry.record({
+ name: 'graphql_cache.queue_diagnostics',
+ operationCategory: 'queue',
+ outcome: 'error',
+ errorCode: classifyCacheError(outcome.error),
+ queueDiagnosticsAvailability: this.latestQueueDiagnostics
+ ? 'available'
+ : 'unavailable',
+ });
+ return;
+ }
+ if (outcome.value.availability === 'unavailable') {
+ this.recordCachedQueueDiagnostics();
+ return;
+ }
+
+ const maxSafe = BigInt(Number.MAX_SAFE_INTEGER);
+ const depthInteger = BigInt(outcome.value.depth);
+ const oldestInteger =
+ outcome.value.oldestCreatedAtMs === null
+ ? undefined
+ : BigInt(outcome.value.oldestCreatedAtMs);
+ this.latestQueueDiagnostics = {
+ depth: Number(
+ depthInteger < 0n
+ ? 0n
+ : depthInteger > maxSafe
+ ? maxSafe
+ : depthInteger
+ ),
+ ...(oldestInteger === undefined
+ ? {}
+ : {
+ oldestCreatedAtMs: Number(
+ oldestInteger > maxSafe
+ ? maxSafe
+ : oldestInteger < -maxSafe
+ ? -maxSafe
+ : oldestInteger
+ ),
+ }),
+ };
+ this.recordCachedQueueDiagnostics();
+ } catch (error) {
+ // Parsing a malformed diagnostic is an observation failure only.
+ this.telemetry.record({
+ name: 'graphql_cache.queue_diagnostics',
+ operationCategory: 'queue',
+ outcome: 'error',
+ errorCode: classifyCacheError(error),
+ queueDiagnosticsAvailability: this.latestQueueDiagnostics
+ ? 'available'
+ : 'unavailable',
+ });
+ } finally {
+ if (timeout !== undefined) clearTimeout(timeout);
+ if (this.cancelQueueDiagnostics === cancel) {
+ this.cancelQueueDiagnostics = undefined;
+ }
+ }
+ }
+
private async init(scope: string, hotCapacity?: number): Promise<void> {
if (this.initPromise) {
- // Subsequent tabs connecting to the SharedWorker re-init idempotently.
+ // Subsequent page clients routed to this elected engine re-init idempotently.
await this.initPromise;
if (this.scope !== scope) {
throw new Error(
`cache worker already initialized for scope ${this.scope}, got ${scope}`
);
}
+ if (this.hotCapacity !== hotCapacity) {
+ throw new Error(
+ `cache worker already initialized with hot capacity ${String(this.hotCapacity)}, got ${String(hotCapacity)}`
+ );
+ }
return;
}
this.scope = scope;
+ this.hotCapacity = hotCapacity;
this.initPromise = (async () => {
const wasm = await loadCacheWasm();
- this.engine = await wasm.openCache(scope, hotCapacity);
+ const schemaStartedAt = this.now();
+ try {
+ let openOutcome: CacheOpenOutcome;
+ if (this.options.recoveryOpen) {
+ if (wasm.openCacheForRecoveryWithOutcome) {
+ const opened = await wasm.openCacheForRecoveryWithOutcome(
+ scope,
+ hotCapacity
+ );
+ this.engine = opened.engine;
+ openOutcome = opened.outcome;
+ } else {
+ this.engine = await wasm.openCacheForRecovery(scope, hotCapacity);
+ openOutcome = 'reset-storage-uncertain';
+ }
+ } else if (wasm.openCacheWithOutcome) {
+ const opened = await wasm.openCacheWithOutcome(scope, hotCapacity);
+ this.engine = opened.engine;
+ openOutcome = opened.outcome;
+ } else {
+ this.engine = await wasm.openCache(scope, hotCapacity);
+ openOutcome = 'opened-existing';
+ }
+ this.options.onInitializationOutcome?.(openOutcome);
+ this.telemetry.record({
+ name: 'graphql_cache.schema_init',
+ operationCategory: 'initialization',
+ outcome: 'success',
+ errorCode: 'none',
+ openOutcome,
+ durationMs: this.now() - schemaStartedAt,
+ });
+ await this.refreshQueueDiagnostics(true);
+ } catch (error) {
+ this.telemetry.record({
+ name: 'graphql_cache.schema_init',
+ operationCategory: 'initialization',
+ outcome: 'error',
+ errorCode: classifyCacheError(error),
+ durationMs: this.now() - schemaStartedAt,
+ });
+ throw error;
+ }
})();
await this.initPromise;
}
- /** Notifies every page connected to this shared engine. */
+ private reportResetRequired(error: unknown): void {
+ if (
+ this.resetRequiredReported ||
+ (typeof error !== 'object' && typeof error !== 'function') ||
+ error === null ||
+ !('cacheStorageResetRequired' in error) ||
+ error.cacheStorageResetRequired !== true
+ ) {
+ return;
+ }
+ this.resetRequiredReported = true;
+ this.options.onStorageResetRequired?.(
+ error instanceof Error ? error : new Error('cache storage reset required')
+ );
+ }
+
+ private resolveDrainWaitersIfIdle(): void {
+ if (
+ this.activeRequestHandlers > 0 ||
+ this.running ||
+ this.queue.length > 0
+ ) {
+ return;
+ }
+ for (const resolve of this.drainWaiters) resolve();
+ this.drainWaiters.clear();
+ }
+
+ /** Notifies every page routed to this elected engine. */
private fanOut(result: WriteResult, cacheChanged: boolean): void {
if (result.affectedOps.length > 0) {
this.push({
diff --git a/apps/web/src/lib/service-clients/service-storage/graphql-soup.test.ts b/apps/web/src/lib/service-clients/service-storage/graphql-soup.test.ts
new file mode 100644
index 0000000000..be28946d24
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-storage/graphql-soup.test.ts
@@ -0,0 +1,207 @@
+import type { BrowserTursoCacheRolloutDecision } from '@graphql-cache/rollout-policy';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => {
+ let enabled = true;
+ let graphqlEnabled = true;
+ let tauri = false;
+ let releaseApi: (() => void) | undefined;
+ let markApiStarted: (() => void) | undefined;
+ const apiStarted = () =>
+ new Promise<void>((resolve) => {
+ markApiStarted = resolve;
+ });
+ let queuedMutationCount = 0;
+ const host = {
+ disabled: false,
+ dispose: vi.fn(),
+ enqueueOptimisticMutation: vi.fn(async () => {
+ queuedMutationCount += 1;
+ return { transactionId: 'tx-1' };
+ }),
+ commitOptimisticWrite: vi.fn(async () => {
+ queuedMutationCount -= 1;
+ return {
+ changed: [],
+ affectedOps: [],
+ reset: false,
+ revalidations: [],
+ };
+ }),
+ };
+ const apiCall = vi.fn(async () => {
+ markApiStarted?.();
+ await new Promise<void>((resolve) => {
+ releaseApi = resolve;
+ });
+ return { data: { committed: true } };
+ });
+ const plainClient = { kind: 'plain' };
+ return {
+ get enabled() {
+ return enabled;
+ },
+ set enabled(value: boolean) {
+ enabled = value;
+ },
+ get graphqlEnabled() {
+ return graphqlEnabled;
+ },
+ set graphqlEnabled(value: boolean) {
+ graphqlEnabled = value;
+ },
+ get tauri() {
+ return tauri;
+ },
+ set tauri(value: boolean) {
+ tauri = value;
+ },
+ host,
+ apiCall,
+ apiStarted,
+ releaseApi: () => releaseApi?.(),
+ resetQueue: () => {
+ queuedMutationCount = 0;
+ },
+ queueDepth: () => queuedMutationCount,
+ plainClient,
+ createWorkerCacheHost: vi.fn(() => host),
+ createTauriCacheHost: vi.fn(() => host),
+ };
+});
+
+vi.mock('@core/constant/featureFlags', () => ({
+ ENABLE_BEARER_TOKEN_AUTH: false,
+}));
+vi.mock('@core/constant/servers', () => ({
+ SERVER_HOSTS: { 'document-storage-service': 'http://dss.test' },
+}));
+vi.mock('@core/util/fetchWithToken', () => ({ fetchToken: vi.fn() }));
+vi.mock('@core/util/platform', () => ({ isTauri: () => mocks.tauri }));
+vi.mock('@core/util/platformFetch', () => ({ platformFetch: vi.fn() }));
+vi.mock('@graphql-cache/rollout', () => ({
+ getBrowserTursoCacheRolloutDecision:
+ (): BrowserTursoCacheRolloutDecision => ({
+ enabled: mocks.tauri ? mocks.graphqlEnabled : mocks.enabled,
+ cohort: mocks.tauri ? 'unknown' : 'treatment',
+ reason: mocks.tauri ? 'tauri-native-unchanged' : 'posthog-enabled',
+ nativeCacheUnchanged: mocks.tauri,
+ }),
+}));
+vi.mock('@graphql-cache/index', () => ({
+ createWorkerCacheHost: mocks.createWorkerCacheHost,
+ createTauriCacheHost: mocks.createTauriCacheHost,
+ entityFromArgument: () => () => undefined,
+}));
+vi.mock('@graphql-cache/lifecycle', () => ({
+ registerCacheHost: () => () => undefined,
+}));
+vi.mock('@graphql-cache/scope', () => ({
+ getOrCreateCacheScope: () => 'anonymous-scope',
+}));
+vi.mock('@graphql-cache/exchange/normalized-cache-exchange', () => ({
+ normalizedCacheExchange: (host: unknown) => ({ kind: 'cache', host }),
+}));
+vi.mock('@service-auth/fetch', () => ({ getMacroApiToken: vi.fn() }));
+vi.mock('graphql', () => ({ print: () => 'mutation Test' }));
+vi.mock('graphql-ws', () => ({
+ createClient: () => ({ subscribe: vi.fn(), dispose: vi.fn() }),
+}));
+vi.mock('./graphql/generated/graphql', () => ({
+ GroupSoupDocument: {},
+ SoupDocument: {},
+}));
+vi.mock('./graphql-soup-websocket', () => ({
+ SOUP_GRAPHQL_WEBSOCKET_RETRY_ATTEMPTS: 0,
+ shouldRetryGraphqlSoupWebSocket: () => false,
+ createGraphqlSoupWebSocketUrlResolver: () => () => 'ws://dss.test',
+ createGraphqlSoupSubscriptionsLifecycle: () => ({
+ replace: vi.fn(),
+ dispose: vi.fn(),
+ }),
+}));
+vi.mock('@urql/core', () => ({
+ fetchExchange: { kind: 'fetch' },
+ subscriptionExchange: () => ({ kind: 'subscription' }),
+ createClient: (options: {
+ exchanges: Array<{ kind?: string; host?: typeof mocks.host }>;
+ }) => {
+ const cacheExchange = options.exchanges.find(
+ ({ kind }) => kind === 'cache'
+ );
+ if (!cacheExchange?.host) return mocks.plainClient;
+ const host = cacheExchange.host;
+ return {
+ kind: 'cached',
+ mutation: () => ({
+ toPromise: async () => {
+ await host.enqueueOptimisticMutation();
+ const response = await mocks.apiCall();
+ await host.commitOptimisticWrite();
+ return response;
+ },
+ }),
+ };
+ },
+}));
+
+describe('GraphQL Soup browser cache session gate', () => {
+ beforeEach(() => {
+ vi.resetModules();
+ vi.clearAllMocks();
+ mocks.enabled = true;
+ mocks.graphqlEnabled = true;
+ mocks.tauri = false;
+ mocks.resetQueue();
+ });
+
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ });
+
+ it('latches an activated client through a flag change until navigation', async () => {
+ const apiStarted = mocks.apiStarted();
+ const soup = await import('./graphql-soup');
+ const client = soup.getGraphqlSoupClient() as unknown as {
+ mutation(): { toPromise(): Promise<unknown> };
+ };
+ const mutation = client.mutation().toPromise();
+ await apiStarted;
+
+ mocks.enabled = false;
+ expect(soup.getGraphqlSoupClient()).toBe(client);
+ expect(soup.graphqlCacheEnabled()).toBe(true);
+ expect(mocks.queueDepth()).toBe(1);
+ expect(mocks.host.dispose).not.toHaveBeenCalled();
+
+ mocks.releaseApi();
+ await expect(mutation).resolves.toEqual({ data: { committed: true } });
+ expect(mocks.apiCall).toHaveBeenCalledOnce();
+ expect(mocks.host.enqueueOptimisticMutation).toHaveBeenCalledOnce();
+ expect(mocks.host.commitOptimisticWrite).toHaveBeenCalledOnce();
+ expect(mocks.queueDepth()).toBe(0);
+ expect(mocks.host.dispose).not.toHaveBeenCalled();
+ });
+
+ it('imports and uses the native path without constructing browser workers', async () => {
+ const WorkerConstructor = vi.fn(() => {
+ throw new Error('browser worker must not be constructed on Tauri');
+ });
+ vi.stubGlobal('Worker', WorkerConstructor);
+ vi.stubGlobal('SharedWorker', WorkerConstructor);
+ mocks.tauri = true;
+ mocks.enabled = false;
+
+ const soup = await import('./graphql-soup');
+ const nativeClient = soup.getGraphqlSoupClient();
+ mocks.graphqlEnabled = false;
+
+ expect(soup.graphqlCacheEnabled()).toBe(false);
+ expect(soup.getGraphqlSoupClient()).toBe(mocks.plainClient);
+ expect(nativeClient).not.toBe(mocks.plainClient);
+ expect(mocks.host.dispose).not.toHaveBeenCalled();
+ expect(mocks.createTauriCacheHost).toHaveBeenCalledOnce();
+ expect(mocks.createWorkerCacheHost).not.toHaveBeenCalled();
+ expect(WorkerConstructor).not.toHaveBeenCalled();
+ });
+});
diff --git a/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts b/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts
index a2abe57751..8d28646a7e 100644
--- a/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts
+++ b/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts
@@ -1,7 +1,4 @@
-import {
- ENABLE_BEARER_TOKEN_AUTH,
- ENABLE_GRAPHQL_SOUP,
-} from '@core/constant/featureFlags';
+import { ENABLE_BEARER_TOKEN_AUTH } from '@core/constant/featureFlags';
import { SERVER_HOSTS } from '@core/constant/servers';
import { fetchToken } from '@core/util/fetchWithToken';
import { isTauri } from '@core/util/platform';
@@ -14,6 +11,7 @@ import {
entityFromArgument,
} from '@graphql-cache/index';
import { registerCacheHost } from '@graphql-cache/lifecycle';
+import { getBrowserTursoCacheRolloutDecision } from '@graphql-cache/rollout';
import { getOrCreateCacheScope } from '@graphql-cache/scope';
import { getMacroApiToken } from '@service-auth/fetch';
import type { ApiUserNotification } from '@service-notification/generated/schemas/apiUserNotification';
@@ -121,11 +119,27 @@ const graphqlSoupClient = createClient({
* process (graphql_cache_plugin).
*/
export function graphqlCacheEnabled(): boolean {
- return ENABLE_GRAPHQL_SOUP();
+ if (!isTauri() && browserCacheClientActivated) return true;
+ return getBrowserTursoCacheRolloutDecision().enabled;
}
let cachedClient: Client | undefined;
let cachedCacheHost: CacheHost | undefined;
+let cachedCacheCleanup: (() => void) | undefined;
+let browserCacheClientActivated = false;
+
+function fallbackAfterInitializationFailure(): void {
+ const cleanup = cachedCacheCleanup;
+ cachedCacheCleanup = undefined;
+ cachedCacheHost = undefined;
+ cachedClient = graphqlSoupClient;
+ browserCacheClientActivated = false;
+ try {
+ cleanup?.();
+ } catch {
+ // Initialization-failure cleanup cannot alter GraphQL transport fallback.
+ }
+}
/** Returns the persistent normalized-cache host after client initialization. */
export function getGraphqlCacheHost(): CacheHost | undefined {
@@ -141,20 +155,29 @@ export function getGraphqlCacheHost(): CacheHost | undefined {
* Any failure falls back to the plain fetch client for the session.
*/
export function getGraphqlSoupClient(): Client {
- if (!graphqlCacheEnabled()) return graphqlSoupClient;
- cachedClient ??= (() => {
+ const native = isTauri();
+ // Only the browser Turso client is session-latched. Tauri keeps the prior
+ // dynamic GraphQL transport behavior and can return to the plain client when
+ // ENABLE_GRAPHQL_SOUP changes without constructing a browser resource.
+ if (!native && browserCacheClientActivated && cachedClient)
+ return cachedClient;
+ const rollout = getBrowserTursoCacheRolloutDecision();
+ if (!rollout.enabled) return graphqlSoupClient;
+ if (cachedClient) return cachedClient;
+ cachedClient = (() => {
let host: CacheHost | undefined;
let websocketClient: GraphqlWsClient | undefined;
let unregisterHost: () => void = () => undefined;
const subscriptionsLifecycle = createGraphqlSoupSubscriptionsLifecycle();
- const onInitializationError = (error: Error) => {
- if (!host || cachedCacheHost !== host) return;
+ const cleanup = () => {
unregisterHost();
- host.dispose();
+ host?.dispose();
subscriptionsLifecycle.dispose();
if (websocketClient) void websocketClient.dispose();
- cachedCacheHost = undefined;
- cachedClient = graphqlSoupClient;
+ };
+ const onInitializationError = (error: Error) => {
+ if (!host || cachedCacheHost !== host) return;
+ fallbackAfterInitializationFailure();
console.warn(
'graphql cache async init failed; using uncached client',
error
@@ -162,9 +185,13 @@ export function getGraphqlSoupClient(): Client {
};
try {
const scope = getOrCreateCacheScope();
- host = isTauri()
+ host = native
? createTauriCacheHost({ scope, onInitializationError })
- : createWorkerCacheHost({ scope, onInitializationError });
+ : createWorkerCacheHost({
+ scope,
+ onInitializationError,
+ rolloutCohort: rollout.cohort,
+ });
const resolveWebSocketUrl = createGraphqlSoupWebSocketUrlResolver({
dssHost,
bearerTokenAuth: ENABLE_BEARER_TOKEN_AUTH,
@@ -232,13 +259,13 @@ export function getGraphqlSoupClient(): Client {
cachedCacheHost = host;
unregisterHost = registerCacheHost(host);
subscriptionsLifecycle.replace(client, host);
+ cachedCacheCleanup = cleanup;
+ browserCacheClientActivated = !native;
return client;
} catch (error) {
- unregisterHost();
- host?.dispose();
- subscriptionsLifecycle.dispose();
- if (websocketClient) void websocketClient.dispose();
+ cleanup();
cachedCacheHost = undefined;
+ cachedCacheCleanup = undefined;
console.warn('graphql cache init failed; using uncached client', error);
return graphqlSoupClient;
}
diff --git a/apps/web/src/observability/browser.ts b/apps/web/src/observability/browser.ts
index c48bd531e4..6eb7e53be9 100644
--- a/apps/web/src/observability/browser.ts
+++ b/apps/web/src/observability/browser.ts
@@ -1,3 +1,4 @@
+import { recordBrowserTursoCacheNavigation } from '@graphql-cache/rollout-observability';
import { Telemetry } from '@macro-inc/observability';
import { createWebTracingProvider } from '@macro-inc/observability/web';
// This static import loads the zone.js Promise patch before application modules run.
@@ -62,6 +63,7 @@ export async function initializeBrowserObservability(): Promise<void> {
tracingProvider: (resource, getUserId) =>
createWebTracingProvider(telemetryConfig, resource, getUserId),
});
+ recordBrowserTursoCacheNavigation();
window.addEventListener('pagehide', () => void Telemetry.flush());
window.addEventListener('error', (event) => {
diff --git a/apps/web/src/vite-env.d.ts b/apps/web/src/vite-env.d.ts
index ec21d7d642..2205896d6a 100644
--- a/apps/web/src/vite-env.d.ts
+++ b/apps/web/src/vite-env.d.ts
@@ -10,6 +10,8 @@ interface ImportMetaEnv {
readonly VITE_OTEL_ENV?: string;
readonly VITE_ENABLE_BROWSER_OTEL?: string;
readonly VITE_ENABLE_REMINDERS?: string;
+ readonly VITE_ENABLE_BROWSER_TURSO_CACHE?: string;
+ readonly VITE_DISABLE_BROWSER_TURSO_CACHE?: string;
}
interface ImportMeta {
diff --git a/apps/web/tauri/graphql_cache_plugin/Cargo.toml b/apps/web/tauri/graphql_cache_plugin/Cargo.toml
index 7cb76958ad..7df20cfd00 100644
--- a/apps/web/tauri/graphql_cache_plugin/Cargo.toml
+++ b/apps/web/tauri/graphql_cache_plugin/Cargo.toml
@@ -13,5 +13,5 @@ tokio = { workspace = true, features = ["sync"] }
tracing = { workspace = true }
[dev-dependencies]
-pollster = "0.4"
+pollster = { workspace = true }
tempfile = "3"
diff --git a/crates/client/README.md b/crates/client/README.md
index 7d473c604b..8c43b7afcf 100644
--- a/crates/client/README.md
+++ b/crates/client/README.md
@@ -9,8 +9,9 @@ Normalized GraphQL cache with disk-backed persistence for urql. Design doc:
|---|---|
| `cache-core` | Pure engine: normalize/denormalize, LRU hot tier, dependency index, durable ordered optimistic-mutation queue, async `Storage` trait |
| `cache-sqlite` | `Storage` over SQLite — Tauri native host |
-| `cache-idb` | `Storage` over IndexedDB via the `idb` crate — browser wasm host (wasm32-only; empty shell elsewhere) |
-| `cache-wasm` | wasm-bindgen shell exposing the engine to the browser worker glue (`apps/web/src/lib/graphql-cache/`) |
+| `cache-turso` | `Storage` over Turso core — browser WASM host |
+| `turso-opfs` | Browser OPFS `IO`/`File` adapter for the dedicated Turso engine worker |
+| `cache-wasm` | wasm-bindgen shell combining the engine, Turso storage, and OPFS adapter for browser worker glue (`apps/web/src/lib/graphql-cache/`) |
The Tauri host lives in the tauri workspace (it needs the patched tauri fork
pinned there): `apps/web/tauri/graphql_cache_plugin`, path-depending on
@@ -20,23 +21,59 @@ Tauri's Linux desktop stack needs its WebKitGTK/DBus system libraries).
## Tests
-From the repository root (these crates are workspace members; use
-`SQLX_OFFLINE=true` as usual):
+Run from the repository root:
```sh
-SQLX_OFFLINE=true cargo test -p cache-core -p cache-sqlite # native
-cargo check --target wasm32-unknown-unknown -p cache-idb -p cache-wasm --all-targets
-wasm-pack test --headless --chrome crates/client/cache-idb # browser tests (IDB backend)
+cargo test -p cache-core -p cache-sqlite -p cache-turso -p turso-opfs
+cargo check --target wasm32-unknown-unknown -p cache-turso -p turso-opfs -p cache-wasm --all-targets
+wasm-pack test --headless --chrome crates/client/cache-turso
+wasm-pack test --headless --chrome crates/client/turso-opfs
```
NixOS note: wasm-pack downloads a dynamically-linked chromedriver that won't
-run. Work around by invoking the runner directly with a nix chromedriver:
+run. Work around by resolving the cached runner whose reported version matches
+the workspace's `wasm-bindgen`, then invoke it with a Nix chromedriver:
```sh
-cd crates/client/cache-idb
-CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER=~/.cache/.wasm-pack/wasm-bindgen-*/wasm-bindgen-test-runner \
-CHROMEDRIVER=$(command -v chromedriver || echo /nix/store/*undetected-chromedriver*/bin/undetected-chromedriver) \
-WASM_BINDGEN_TEST_ONLY_WEB=1 cargo test --target wasm32-unknown-unknown
+wasm_bindgen_version=$(
+ cargo tree -p cache-turso --target wasm32-unknown-unknown -i wasm-bindgen --prefix none |
+ sed -n 's/^wasm-bindgen v//p' |
+ head -n 1
+)
+runner=
+for candidate in "$(command -v wasm-bindgen-test-runner || true)" \
+ "$HOME"/.cache/.wasm-pack/wasm-bindgen-*/wasm-bindgen-test-runner; do
+ [ -x "$candidate" ] || continue
+ [ "$("$candidate" --version)" = "wasm-bindgen-test-runner $wasm_bindgen_version" ] || continue
+ runner=$candidate
+ break
+done
+test -x "$runner" || {
+ echo "no wasm-bindgen-test-runner matching $wasm_bindgen_version" >&2
+ exit 1
+}
+
+chromedriver=$(command -v chromedriver || true)
+if [ -z "$chromedriver" ]; then
+ for candidate in /nix/store/*chromedriver*/bin/chromedriver \
+ /nix/store/*chromedriver*/bin/undetected-chromedriver; do
+ [ -x "$candidate" ] || continue
+ chromedriver=$candidate
+ break
+ done
+fi
+test -x "$chromedriver" || {
+ echo 'no Nix chromedriver found' >&2
+ exit 1
+}
+
+CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER="$runner" \
+CHROMEDRIVER="$chromedriver" \
+WASM_BINDGEN_TEST_ONLY_WEB=1 cargo test --target wasm32-unknown-unknown -p cache-turso
+
+CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER="$runner" \
+CHROMEDRIVER="$chromedriver" \
+WASM_BINDGEN_TEST_ONLY_WEB=1 cargo test --target wasm32-unknown-unknown -p turso-opfs --lib
```
## Key policy
diff --git a/crates/client/cache-core/Cargo.toml b/crates/client/cache-core/Cargo.toml
index e4449f1cc7..1b39980c57 100644
--- a/crates/client/cache-core/Cargo.toml
+++ b/crates/client/cache-core/Cargo.toml
@@ -19,4 +19,4 @@ apollo-compiler = { workspace = true }
sha2 = { workspace = true }
[dev-dependencies]
-pollster = "0.4"
+pollster = { workspace = true }
diff --git a/crates/client/cache-core/src/codec.rs b/crates/client/cache-core/src/codec.rs
index 38e75261d8..71d9757fa4 100644
--- a/crates/client/cache-core/src/codec.rs
+++ b/crates/client/cache-core/src/codec.rs
@@ -1,8 +1,10 @@
-//! Binary record codec shared by all persistent backends (IndexedDB,
-//! SQLite). Records are stored as postcard bytes; the cache namespace embeds
-//! [`CACHE_FORMAT_VERSION`] and [`CACHE_SCHEMA_COMPATIBILITY_EPOCH`]. Additive
-//! GraphQL schema changes keep existing records, while incompatible schema or
-//! record-format changes start a fresh cache.
+//! Binary record codec shared by all persistent backends (browser Turso and
+//! native SQLite). Records are stored as postcard bytes; the logical namespace
+//! embeds [`CACHE_FORMAT_VERSION`] and [`CACHE_SCHEMA_COMPATIBILITY_EPOCH`].
+//! A healthy, graceful browser reopen with matching versions preserves records,
+//! queued mutations, and optimistic layers. A compatibility/format mismatch or
+//! abrupt/uncertain browser owner loss physically resets the database and
+//! discards all three.
use crate::normalize::RecordUpdates;
use crate::queue::{PersistedOptimisticLayer, StoredMutation};
@@ -75,8 +77,10 @@ pub fn decode_record_updates(bytes: &[u8]) -> Result<RecordUpdates, CodecError>
decode(bytes)
}
-/// Canonical database/namespace name for a cache instance.
-/// `scope` identifies the user/workspace (host-provided).
+/// Canonical logical namespace for a cache instance.
+///
+/// `scope` is an anonymous, client-generated token supplied by the host. It is
+/// neither user nor workspace identity.
pub fn cache_namespace(scope: &str) -> String {
format!("graphql-cache:{scope}:s{CACHE_SCHEMA_COMPATIBILITY_EPOCH}:v{CACHE_FORMAT_VERSION}")
}
@@ -84,9 +88,11 @@ pub fn cache_namespace(scope: &str) -> String {
/// Stable physical database name for a cache scope.
///
/// Unlike [`cache_namespace`], this deliberately excludes the schema
-/// compatibility epoch and cache format version. Normalized records are
-/// disposable on version changes, while queued mutations represent user intent
-/// and must remain discoverable.
+/// compatibility epoch and cache format version so the browser can acquire the
+/// same main/WAL paths and validate their metadata. Only a healthy, graceful
+/// close and compatible reopen preserves those files. A compatibility/format
+/// mismatch or abrupt/uncertain owner loss physically resets both files,
+/// discarding every row, including queued mutations and optimistic layers.
pub fn cache_database_name(scope: &str) -> String {
format!("graphql-cache:{scope}")
}
@@ -133,6 +139,9 @@ mod tests {
#[test]
fn namespace_uses_schema_compatibility_epoch_not_schema_hash() {
- assert_eq!(cache_namespace("user-1"), "graphql-cache:user-1:s1:v2");
+ assert_eq!(
+ cache_namespace("client-token-1"),
+ "graphql-cache:client-token-1:s1:v2"
+ );
}
}
diff --git a/crates/client/cache-core/src/engine.rs b/crates/client/cache-core/src/engine.rs
index 6bed2745d4..8046a817a6 100644
--- a/crates/client/cache-core/src/engine.rs
+++ b/crates/client/cache-core/src/engine.rs
@@ -27,7 +27,7 @@ use crate::queue::{
use crate::record_selection::{
RecordCursor, RecordSelection, RecordSelectionError, SelectedRecordPage, validate_limit,
};
-use crate::store::Storage;
+use crate::store::{QueueDiagnostics, Storage};
use crate::value::{EntityKey, Record, canonical_json};
use lru::LruCache;
use serde_json::Value as Json;
@@ -1309,12 +1309,28 @@ impl<S: Storage> Engine<S> {
self.deps.active_ops()
}
- /// Access to the underlying storage (hosts need it for lifecycle
- /// operations like closing connections before database deletion).
+ /// Returns payload-free durable mutation queue diagnostics.
+ pub async fn queue_diagnostics(&self) -> Result<QueueDiagnostics, EngineError<S::Error>> {
+ self.storage
+ .queue_diagnostics()
+ .await
+ .map_err(EngineError::Storage)
+ }
+
+ /// Access to the underlying storage for non-consuming diagnostics.
pub fn storage(&self) -> &S {
&self.storage
}
+ /// Consumes the engine and returns its owned storage.
+ ///
+ /// Hosts must use this transition for storage lifecycles that require
+ /// exclusive ownership, such as proving that a browser database connection
+ /// is closed before preserving or physically resetting its OPFS files.
+ pub fn into_storage(self) -> S {
+ self.storage
+ }
+
/// Memoized document parse. Takes the map (not `&mut self`) so callers
/// can keep the returned borrow while using other engine fields.
fn document<'d>(
diff --git a/crates/client/cache-core/src/store.rs b/crates/client/cache-core/src/store.rs
index 8cc65b46f3..546dfc064a 100644
--- a/crates/client/cache-core/src/store.rs
+++ b/crates/client/cache-core/src/store.rs
@@ -1,9 +1,9 @@
//! Storage abstraction: the cold tier behind the in-memory hot tier.
//!
-//! Implementations: in-memory (tests, Phase 1), IndexedDB via the `idb`
-//! crate (browser, Phase 2), SQLite (Tauri native, Phase 2). Futures are
-//! [`MaybeSend`]: `Send` on native targets (so hosts can drive the engine
-//! from a multi-threaded runtime), unbounded on wasm — wasm futures aren't
+//! Implementations: in-memory (tests), Turso over OPFS (browser), and SQLite
+//! (Tauri native). Futures are [`MaybeSend`]: `Send` on native targets (so
+//! hosts can drive the engine from a multi-threaded runtime), unbounded on
+//! wasm — wasm futures aren't
//! `Send`.
use crate::queue::{
@@ -15,6 +15,27 @@ use maybe_send::MaybeSend;
use std::collections::{BTreeMap, HashMap};
use std::convert::Infallible;
+/// Whether a storage implementation can provide queue diagnostics.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub enum QueueDiagnosticsAvailability {
+ /// This compatibility implementation has no authoritative diagnostics.
+ #[default]
+ Unavailable,
+ /// The depth and oldest timestamp were read from authoritative storage.
+ Available,
+}
+
+/// Payload-free durable mutation queue diagnostics.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub struct QueueDiagnostics {
+ /// Whether the numeric snapshot is authoritative.
+ pub availability: QueueDiagnosticsAvailability,
+ /// Number of durable mutations waiting for settlement.
+ pub depth: u64,
+ /// Oldest durable enqueue timestamp, or `None` when the queue is empty.
+ pub oldest_created_at_ms: Option<i64>,
+}
+
/// Async KV over normalized records. Batch-oriented by design: the engine
/// issues one `get_batch` per denormalization round, never per record.
pub trait Storage: MaybeSend {
@@ -58,6 +79,17 @@ pub trait Storage: MaybeSend {
&self,
) -> impl Future<Output = Result<Vec<QueuedMutation>, Self::Error>> + MaybeSend;
+ /// Returns only queue depth and the oldest enqueue timestamp.
+ ///
+ /// The default preserves source compatibility for external storage
+ /// implementations and explicitly reports diagnostics as unavailable.
+ /// Production backends override it with an authoritative aggregate query.
+ fn queue_diagnostics(
+ &self,
+ ) -> impl Future<Output = Result<QueueDiagnostics, Self::Error>> + MaybeSend {
+ async { Ok(QueueDiagnostics::default()) }
+ }
+
/// Claims the oldest mutation when it is runnable and not actively leased.
/// Later mutations are never skipped.
fn claim_next_mutation(
@@ -200,6 +232,18 @@ impl Storage for InMemoryStorage {
.collect())
}
+ async fn queue_diagnostics(&self) -> Result<QueueDiagnostics, Self::Error> {
+ Ok(QueueDiagnostics {
+ availability: QueueDiagnosticsAvailability::Available,
+ depth: self.mutations.len() as u64,
+ oldest_created_at_ms: self
+ .mutations
+ .values()
+ .map(|(mutation, _)| mutation.created_at_ms)
+ .min(),
+ })
+ }
+
async fn claim_next_mutation(
&mut self,
request: MutationClaimRequest,
diff --git a/crates/client/cache-core/tests/engine.rs b/crates/client/cache-core/tests/engine.rs
index f36c58fb79..2ce86e0c99 100644
--- a/crates/client/cache-core/tests/engine.rs
+++ b/crates/client/cache-core/tests/engine.rs
@@ -95,6 +95,13 @@ fn page_for_user(user: &str, names: &[(&str, &str)]) -> Json {
})
}
+#[test]
+fn consuming_engine_returns_exclusively_owned_storage() {
+ let engine = Engine::new(InMemoryStorage::new());
+ let storage: InMemoryStorage = engine.into_storage();
+ assert!(storage.is_empty());
+}
+
#[test]
fn miss_then_write_then_hit() {
block_on(async {
diff --git a/crates/client/cache-core/tests/mutation_queue.rs b/crates/client/cache-core/tests/mutation_queue.rs
index ba9e696108..82d3ee4757 100644
--- a/crates/client/cache-core/tests/mutation_queue.rs
+++ b/crates/client/cache-core/tests/mutation_queue.rs
@@ -54,6 +54,64 @@ fn queued(value: &str, created_at_ms: i64) -> NewQueuedMutation {
}
}
+#[test]
+fn queue_diagnostics_are_payload_free_and_track_oldest() {
+ block_on(async {
+ let mut storage = InMemoryStorage::new();
+ assert_eq!(
+ storage.queue_diagnostics().await.unwrap(),
+ cache_core::store::QueueDiagnostics {
+ availability: cache_core::store::QueueDiagnosticsAvailability::Available,
+ depth: 0,
+ oldest_created_at_ms: None,
+ }
+ );
+ let first = storage
+ .enqueue_mutation(queued("secret-a", 42))
+ .await
+ .unwrap();
+ storage
+ .enqueue_mutation(queued("secret-b", 21))
+ .await
+ .unwrap();
+ assert_eq!(
+ storage.queue_diagnostics().await.unwrap(),
+ cache_core::store::QueueDiagnostics {
+ availability: cache_core::store::QueueDiagnosticsAvailability::Available,
+ depth: 2,
+ oldest_created_at_ms: Some(21),
+ }
+ );
+ let claimed = storage
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner".into(),
+ now_ms: 100,
+ lease_expires_at_ms: 200,
+ })
+ .await
+ .unwrap()
+ .unwrap();
+ storage
+ .discard_mutation(
+ first,
+ MutationClaimToken {
+ owner: "runner".into(),
+ generation: claimed.lease_generation,
+ },
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ storage.queue_diagnostics().await.unwrap(),
+ cache_core::store::QueueDiagnostics {
+ availability: cache_core::store::QueueDiagnosticsAvailability::Available,
+ depth: 1,
+ oldest_created_at_ms: Some(21),
+ }
+ );
+ });
+}
+
#[test]
fn queue_claim_retry_and_settlement_are_ordered() {
block_on(async {
diff --git a/crates/client/cache-core/tests/optimistic.rs b/crates/client/cache-core/tests/optimistic.rs
index 0d9f335c18..f836816d83 100644
--- a/crates/client/cache-core/tests/optimistic.rs
+++ b/crates/client/cache-core/tests/optimistic.rs
@@ -475,7 +475,13 @@ fn enqueue_does_not_skip_a_leased_or_deferred_head() {
#[test]
fn claim_failure_after_enqueue_preserves_one_durable_visible_mutation() {
block_on(async {
- let mut engine = Engine::new(ClaimFailingStorage::new());
+ let compatibility_storage = ClaimFailingStorage::new();
+ assert_eq!(
+ compatibility_storage.queue_diagnostics().await.unwrap(),
+ cache_core::store::QueueDiagnostics::default(),
+ "the compatibility default must be explicitly unavailable"
+ );
+ let mut engine = Engine::new(compatibility_storage);
engine
.write_query(
None,
diff --git a/crates/client/cache-idb/Cargo.toml b/crates/client/cache-idb/Cargo.toml
deleted file mode 100644
index fc7fb90ba6..0000000000
--- a/crates/client/cache-idb/Cargo.toml
+++ /dev/null
@@ -1,27 +0,0 @@
-[package]
-edition = "2024"
-name = "cache-idb"
-publish = false
-version = "0.1.0"
-
-# wasm32-only implementation; the crate compiles to an empty shell on other
-# targets so plain `cargo test` at the workspace root stays green.
-
-[dependencies]
-cache-core = { path = "../cache-core" }
-thiserror = { workspace = true }
-
-[target.'cfg(target_arch = "wasm32")'.dependencies]
-idb = "0.6"
-js-sys = "0.3"
-wasm-bindgen = "0.2"
-web-sys = { version = "0.3", features = [
- "Event",
- "EventTarget",
- "IdbDatabase",
- "console",
-] }
-
-[target.'cfg(target_arch = "wasm32")'.dev-dependencies]
-serde_json = { workspace = true }
-wasm-bindgen-test = "0.3"
diff --git a/crates/client/cache-idb/src/idb_storage.rs b/crates/client/cache-idb/src/idb_storage.rs
deleted file mode 100644
index b631f50d32..0000000000
--- a/crates/client/cache-idb/src/idb_storage.rs
+++ /dev/null
@@ -1,545 +0,0 @@
-use cache_core::codec::{
- CodecError, cache_database_name, cache_namespace, decode_optimistic_layer, decode_record,
- decode_stored_mutation, encode_optimistic_layer, encode_record, encode_stored_mutation,
-};
-use cache_core::queue::{
- ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, NewQueuedMutation,
- QueuedMutation,
-};
-use cache_core::store::Storage;
-use cache_core::value::{EntityKey, Record};
-use idb::{
- CursorDirection, Database, DatabaseEvent, Factory, KeyRange, ObjectStoreParams, Query,
- TransactionMode,
-};
-use thiserror::Error;
-use wasm_bindgen::{JsCast, JsValue};
-
-const META_STORE: &str = "meta";
-const RECORDS_STORE: &str = "records";
-const MUTATION_QUEUE_STORE: &str = "mutation_queue";
-const OPTIMISTIC_LAYERS_STORE: &str = "optimistic_layers";
-const DB_VERSION: u32 = 1;
-const SCOPE_META_KEY: &str = "scope";
-const NAMESPACE_META_KEY: &str = "namespace";
-
-#[derive(Debug, Error)]
-pub enum IdbStorageError {
- #[error("indexeddb: {0}")]
- Idb(#[from] idb::Error),
- #[error(transparent)]
- Codec(#[from] CodecError),
- #[error("stored value is not a Uint8Array")]
- NotBytes,
- #[error("stored metadata is not a string")]
- NotString,
- #[error("mutation queue key is not a safe positive integer")]
- InvalidMutationId,
- #[error("mutation queue and optimistic layer stores are inconsistent")]
- InconsistentQueue,
-}
-
-pub struct IdbStorage {
- db: Database,
-}
-
-fn bytes_to_js(bytes: &[u8]) -> JsValue {
- js_sys::Uint8Array::from(bytes).into()
-}
-
-fn bytes_from_js(value: JsValue) -> Result<Vec<u8>, IdbStorageError> {
- let bytes: js_sys::Uint8Array = value.dyn_into().map_err(|_| IdbStorageError::NotBytes)?;
- Ok(bytes.to_vec())
-}
-
-fn mutation_id_from_js(value: &JsValue) -> Result<MutationId, IdbStorageError> {
- const MAX_SAFE_INTEGER: f64 = 9_007_199_254_740_991.0;
- let Some(number) = value.as_f64() else {
- return Err(IdbStorageError::InvalidMutationId);
- };
- if !(1.0..=MAX_SAFE_INTEGER).contains(&number) || number.fract() != 0.0 {
- return Err(IdbStorageError::InvalidMutationId);
- }
- Ok(number as MutationId)
-}
-
-fn mutation_id_to_js(id: MutationId) -> Result<JsValue, IdbStorageError> {
- const MAX_SAFE_INTEGER: MutationId = 9_007_199_254_740_991;
- if id == 0 || id > MAX_SAFE_INTEGER {
- return Err(IdbStorageError::InvalidMutationId);
- }
- Ok(JsValue::from_f64(id as f64))
-}
-
-fn claim_matches(mutation: &cache_core::queue::StoredMutation, claim: &MutationClaimToken) -> bool {
- mutation.lease_owner.as_deref() == Some(&claim.owner)
- && mutation.lease_generation == claim.generation
-}
-
-impl IdbStorage {
- /// Opens the cache database for `scope` and initializes all stores.
- /// Compatibility-epoch or cache-format changes clear only disposable
- /// records; a scope change also clears queued user intent.
- pub async fn open(scope: &str) -> Result<Self, IdbStorageError> {
- let name = cache_database_name(scope);
- let factory = Factory::new()?;
- let mut request = factory.open(&name, Some(DB_VERSION))?;
- request.on_upgrade_needed(|event| {
- let database = event.database().expect("upgrade event has database");
- let existing = database.store_names();
- for (name, params) in [
- (META_STORE, ObjectStoreParams::new()),
- (RECORDS_STORE, ObjectStoreParams::new()),
- (MUTATION_QUEUE_STORE, {
- let mut params = ObjectStoreParams::new();
- params.auto_increment(true);
- params
- }),
- (OPTIMISTIC_LAYERS_STORE, ObjectStoreParams::new()),
- ] {
- if !existing.iter().any(|store| store == name) {
- database
- .create_object_store(name, params)
- .unwrap_or_else(|_| panic!("create {name} object store"));
- }
- }
- });
- let mut db = request.await?;
- // Close immediately when another context needs this database gone or
- // upgraded (delete/upgrade requests block while connections are
- // open); without this, `destroy` from another tab can hang forever.
- db.on_version_change(|event: web_sys::Event| {
- if let Some(target) = event.target()
- && let Ok(db) = wasm_bindgen::JsCast::dyn_into::<web_sys::IdbDatabase>(target)
- {
- db.close();
- }
- });
- let mut storage = IdbStorage { db };
- storage.initialize_namespace(scope).await?;
- Ok(storage)
- }
-
- async fn initialize_namespace(&mut self, scope: &str) -> Result<(), IdbStorageError> {
- let tx = self.db.transaction(
- &[
- META_STORE,
- RECORDS_STORE,
- MUTATION_QUEUE_STORE,
- OPTIMISTIC_LAYERS_STORE,
- ],
- TransactionMode::ReadWrite,
- )?;
- let meta = tx.object_store(META_STORE)?;
- let scope_request = meta.get(JsValue::from_str(SCOPE_META_KEY))?;
- let namespace_request = meta.get(JsValue::from_str(NAMESPACE_META_KEY))?;
- let stored_scope = scope_request
- .await?
- .map(|value| value.as_string().ok_or(IdbStorageError::NotString))
- .transpose()?;
- let stored_namespace = namespace_request
- .await?
- .map(|value| value.as_string().ok_or(IdbStorageError::NotString))
- .transpose()?;
- let expected_namespace = cache_namespace(scope);
-
- if stored_scope.as_deref() != Some(scope) {
- tx.object_store(OPTIMISTIC_LAYERS_STORE)?.clear()?;
- tx.object_store(MUTATION_QUEUE_STORE)?.clear()?;
- tx.object_store(RECORDS_STORE)?.clear()?;
- } else if stored_namespace.as_deref() != Some(expected_namespace.as_str()) {
- tx.object_store(RECORDS_STORE)?.clear()?;
- }
- meta.put(
- &JsValue::from_str(scope),
- Some(&JsValue::from_str(SCOPE_META_KEY)),
- )?;
- meta.put(
- &JsValue::from_str(&expected_namespace),
- Some(&JsValue::from_str(NAMESPACE_META_KEY)),
- )?;
- tx.commit()?.await?;
- Ok(())
- }
-
- /// Deletes the database for `scope` (logout / stale-namespace cleanup).
- ///
- /// Connections opened by [`Self::open`] auto-close on `versionchange`,
- /// so this does not block on our own live handles. A `blocked` event
- /// (foreign connection without that handler) is logged for diagnosis
- /// instead of hanging silently.
- pub async fn destroy(scope: &str) -> Result<(), IdbStorageError> {
- let factory = Factory::new()?;
- let mut request = factory.delete(&cache_database_name(scope))?;
- request.on_blocked(|_| {
- web_sys::console::warn_1(
- &"graphql-cache: database deletion blocked by an open connection".into(),
- );
- });
- request.await?;
- Ok(())
- }
-
- /// Closes the underlying connection. Subsequent operations on this
- /// storage will fail; call right before dropping/destroying.
- pub fn close(&self) {
- self.db.close();
- }
-}
-
-impl Storage for IdbStorage {
- type Error = IdbStorageError;
-
- async fn get_batch(&self, keys: &[EntityKey<'_>]) -> Result<Vec<Option<Record>>, Self::Error> {
- let tx = self
- .db
- .transaction(&[RECORDS_STORE], TransactionMode::ReadOnly)?;
- let store = tx.object_store(RECORDS_STORE)?;
-
- // Dispatch all gets first (they execute concurrently within the
- // transaction), then await in order.
- let mut requests = Vec::with_capacity(keys.len());
- for key in keys {
- requests.push(store.get(JsValue::from_str(key.0.as_ref()))?);
- }
- let mut out = Vec::with_capacity(keys.len());
- for request in requests {
- let value = request.await?;
- out.push(match value {
- None => None,
- Some(js) => Some(decode_record(&bytes_from_js(js)?)?),
- });
- }
- Ok(out)
- }
-
- async fn put_batch(
- &mut self,
- entries: Vec<(EntityKey<'static>, Record)>,
- ) -> Result<(), Self::Error> {
- let tx = self
- .db
- .transaction(&[RECORDS_STORE], TransactionMode::ReadWrite)?;
- let store = tx.object_store(RECORDS_STORE)?;
- for (key, record) in &entries {
- let bytes = encode_record(record);
- store.put(
- &bytes_to_js(&bytes),
- Some(&JsValue::from_str(key.0.as_ref())),
- )?;
- }
- // Committing the transaction is what makes the batch atomic.
- tx.commit()?.await?;
- Ok(())
- }
-
- async fn delete_batch(&mut self, keys: &[EntityKey<'static>]) -> Result<(), Self::Error> {
- let tx = self
- .db
- .transaction(&[RECORDS_STORE], TransactionMode::ReadWrite)?;
- let store = tx.object_store(RECORDS_STORE)?;
- for key in keys {
- store.delete(JsValue::from_str(key.0.as_ref()))?;
- }
- tx.commit()?.await?;
- Ok(())
- }
-
- async fn scan_records(
- &self,
- type_names: &[String],
- after: Option<&EntityKey<'static>>,
- limit: usize,
- ) -> Result<Vec<(EntityKey<'static>, Record)>, Self::Error> {
- if type_names.is_empty() || limit == 0 {
- return Ok(Vec::new());
- }
-
- let mut type_names = type_names.to_vec();
- type_names.sort();
- type_names.dedup();
- let mut records = Vec::with_capacity(limit);
- for type_name in type_names {
- if records.len() == limit {
- break;
- }
- let prefix = format!("{type_name}:");
- let upper = format!("{type_name};");
- if after.is_some_and(|after| after.0.as_ref() >= upper.as_str()) {
- continue;
- }
- let (lower, lower_open) = match after {
- Some(after) if after.0.as_ref() >= prefix.as_str() => (after.0.as_ref(), true),
- _ => (prefix.as_str(), false),
- };
- let range = KeyRange::bound(
- &JsValue::from_str(lower),
- &JsValue::from_str(&upper),
- Some(lower_open),
- Some(true),
- )?;
- let tx = self
- .db
- .transaction(&[RECORDS_STORE], TransactionMode::ReadOnly)?;
- let store = tx.object_store(RECORDS_STORE)?;
- let Some(cursor) = store
- .open_cursor(Some(Query::from(range)), Some(CursorDirection::Next))?
- .await?
- else {
- continue;
- };
- let mut cursor = cursor.into_managed();
- while records.len() < limit {
- let Some(key) = cursor.key()? else {
- break;
- };
- let Some(value) = cursor.value()? else {
- break;
- };
- let key = key.as_string().ok_or(IdbStorageError::NotString)?;
- records.push((
- EntityKey(key.into()),
- decode_record(&bytes_from_js(value)?)?,
- ));
- cursor.next(None).await?;
- }
- }
- Ok(records)
- }
-
- async fn enqueue_mutation(
- &mut self,
- entry: NewQueuedMutation,
- ) -> Result<MutationId, Self::Error> {
- let tx = self.db.transaction(
- &[MUTATION_QUEUE_STORE, OPTIMISTIC_LAYERS_STORE],
- TransactionMode::ReadWrite,
- )?;
- let queue = tx.object_store(MUTATION_QUEUE_STORE)?;
- let mutation_bytes = encode_stored_mutation(&entry.mutation);
- let generated_key = queue.add(&bytes_to_js(&mutation_bytes), None)?.await?;
- let id = mutation_id_from_js(&generated_key)?;
- let optimistic_bytes = encode_optimistic_layer(&entry.optimistic);
- tx.object_store(OPTIMISTIC_LAYERS_STORE)?
- .put(&bytes_to_js(&optimistic_bytes), Some(&generated_key))?;
- tx.commit()?.await?;
- Ok(id)
- }
-
- async fn load_mutation_queue(&self) -> Result<Vec<QueuedMutation>, Self::Error> {
- let tx = self.db.transaction(
- &[MUTATION_QUEUE_STORE, OPTIMISTIC_LAYERS_STORE],
- TransactionMode::ReadOnly,
- )?;
- let queue = tx.object_store(MUTATION_QUEUE_STORE)?;
- let optimistic = tx.object_store(OPTIMISTIC_LAYERS_STORE)?;
- let queue_keys_request = queue.get_all_keys(None, None)?;
- let queue_values_request = queue.get_all(None, None)?;
- let optimistic_keys_request = optimistic.get_all_keys(None, None)?;
- let optimistic_values_request = optimistic.get_all(None, None)?;
-
- let queue_keys = queue_keys_request.await?;
- let queue_values = queue_values_request.await?;
- let optimistic_keys = optimistic_keys_request.await?;
- let optimistic_values = optimistic_values_request.await?;
- if queue_keys.len() != queue_values.len()
- || queue_keys.len() != optimistic_keys.len()
- || queue_keys.len() != optimistic_values.len()
- {
- return Err(IdbStorageError::InconsistentQueue);
- }
-
- let mut out = Vec::with_capacity(queue_keys.len());
- for (((queue_key, mutation), optimistic_key), layer) in queue_keys
- .into_iter()
- .zip(queue_values)
- .zip(optimistic_keys)
- .zip(optimistic_values)
- {
- let id = mutation_id_from_js(&queue_key)?;
- if mutation_id_from_js(&optimistic_key)? != id {
- return Err(IdbStorageError::InconsistentQueue);
- }
- out.push(QueuedMutation {
- id,
- mutation: decode_stored_mutation(&bytes_from_js(mutation)?)?,
- optimistic: decode_optimistic_layer(&bytes_from_js(layer)?)?,
- });
- }
- Ok(out)
- }
-
- async fn claim_next_mutation(
- &mut self,
- request: MutationClaimRequest,
- ) -> Result<Option<ClaimedMutation>, Self::Error> {
- let tx = self.db.transaction(
- &[MUTATION_QUEUE_STORE, OPTIMISTIC_LAYERS_STORE],
- TransactionMode::ReadWrite,
- )?;
- let queue = tx.object_store(MUTATION_QUEUE_STORE)?;
- let optimistic = tx.object_store(OPTIMISTIC_LAYERS_STORE)?;
- let queue_keys_request = queue.get_all_keys(None, Some(1))?;
- let queue_values_request = queue.get_all(None, Some(1))?;
- let optimistic_keys_request = optimistic.get_all_keys(None, Some(1))?;
- let optimistic_values_request = optimistic.get_all(None, Some(1))?;
- let queue_keys = queue_keys_request.await?;
- let queue_values = queue_values_request.await?;
- let optimistic_keys = optimistic_keys_request.await?;
- let optimistic_values = optimistic_values_request.await?;
-
- if queue_keys.is_empty() {
- if !queue_values.is_empty()
- || !optimistic_keys.is_empty()
- || !optimistic_values.is_empty()
- {
- return Err(IdbStorageError::InconsistentQueue);
- }
- tx.commit()?.await?;
- return Ok(None);
- }
- if queue_keys.len() != 1
- || queue_values.len() != 1
- || optimistic_keys.len() != 1
- || optimistic_values.len() != 1
- {
- return Err(IdbStorageError::InconsistentQueue);
- }
- let key = &queue_keys[0];
- let id = mutation_id_from_js(key)?;
- if mutation_id_from_js(&optimistic_keys[0])? != id {
- return Err(IdbStorageError::InconsistentQueue);
- }
- let mut mutation = decode_stored_mutation(&bytes_from_js(queue_values[0].clone())?)?;
- if mutation
- .next_attempt_at_ms
- .is_some_and(|next| next > request.now_ms)
- || mutation
- .lease_expires_at_ms
- .is_some_and(|expiry| expiry > request.now_ms)
- {
- tx.commit()?.await?;
- return Ok(None);
- }
-
- mutation.attempt_count = mutation.attempt_count.saturating_add(1);
- mutation.lease_generation = mutation.lease_generation.saturating_add(1);
- mutation.lease_owner = Some(request.owner);
- mutation.lease_expires_at_ms = Some(request.lease_expires_at_ms);
- mutation.next_attempt_at_ms = None;
- let generation = mutation.lease_generation;
- queue.put(&bytes_to_js(&encode_stored_mutation(&mutation)), Some(key))?;
- let layer = decode_optimistic_layer(&bytes_from_js(optimistic_values[0].clone())?)?;
- tx.commit()?.await?;
- Ok(Some(ClaimedMutation {
- queued: QueuedMutation {
- id,
- mutation,
- optimistic: layer,
- },
- lease_generation: generation,
- }))
- }
-
- async fn defer_mutation(
- &mut self,
- id: MutationId,
- claim: MutationClaimToken,
- next_attempt_at_ms: i64,
- error: String,
- ) -> Result<bool, Self::Error> {
- let key = mutation_id_to_js(id)?;
- let tx = self
- .db
- .transaction(&[MUTATION_QUEUE_STORE], TransactionMode::ReadWrite)?;
- let queue = tx.object_store(MUTATION_QUEUE_STORE)?;
- let Some(value) = queue.get(key.clone())?.await? else {
- tx.commit()?.await?;
- return Ok(false);
- };
- let mut mutation = decode_stored_mutation(&bytes_from_js(value)?)?;
- if !claim_matches(&mutation, &claim) {
- tx.commit()?.await?;
- return Ok(false);
- }
- mutation.next_attempt_at_ms = Some(next_attempt_at_ms);
- mutation.last_error = Some(error);
- mutation.lease_owner = None;
- mutation.lease_expires_at_ms = None;
- queue.put(&bytes_to_js(&encode_stored_mutation(&mutation)), Some(&key))?;
- tx.commit()?.await?;
- Ok(true)
- }
-
- async fn complete_mutation(
- &mut self,
- id: MutationId,
- claim: MutationClaimToken,
- entries: Vec<(EntityKey<'static>, Record)>,
- ) -> Result<bool, Self::Error> {
- let key = mutation_id_to_js(id)?;
- let tx = self.db.transaction(
- &[RECORDS_STORE, MUTATION_QUEUE_STORE, OPTIMISTIC_LAYERS_STORE],
- TransactionMode::ReadWrite,
- )?;
- let queue = tx.object_store(MUTATION_QUEUE_STORE)?;
- let Some(value) = queue.get(key.clone())?.await? else {
- tx.commit()?.await?;
- return Ok(false);
- };
- let mutation = decode_stored_mutation(&bytes_from_js(value)?)?;
- if !claim_matches(&mutation, &claim) {
- tx.commit()?.await?;
- return Ok(false);
- }
- let records = tx.object_store(RECORDS_STORE)?;
- for (record_key, record) in &entries {
- records.put(
- &bytes_to_js(&encode_record(record)),
- Some(&JsValue::from_str(record_key.0.as_ref())),
- )?;
- }
- queue.delete(key.clone())?;
- tx.object_store(OPTIMISTIC_LAYERS_STORE)?.delete(key)?;
- tx.commit()?.await?;
- Ok(true)
- }
-
- async fn discard_mutation(
- &mut self,
- id: MutationId,
- claim: MutationClaimToken,
- ) -> Result<bool, Self::Error> {
- let key = mutation_id_to_js(id)?;
- let tx = self.db.transaction(
- &[MUTATION_QUEUE_STORE, OPTIMISTIC_LAYERS_STORE],
- TransactionMode::ReadWrite,
- )?;
- let queue = tx.object_store(MUTATION_QUEUE_STORE)?;
- let Some(value) = queue.get(key.clone())?.await? else {
- tx.commit()?.await?;
- return Ok(false);
- };
- let mutation = decode_stored_mutation(&bytes_from_js(value)?)?;
- if !claim_matches(&mutation, &claim) {
- tx.commit()?.await?;
- return Ok(false);
- }
- queue.delete(key.clone())?;
- tx.object_store(OPTIMISTIC_LAYERS_STORE)?.delete(key)?;
- tx.commit()?.await?;
- Ok(true)
- }
-
- async fn clear(&mut self) -> Result<(), Self::Error> {
- let tx = self.db.transaction(
- &[RECORDS_STORE, MUTATION_QUEUE_STORE, OPTIMISTIC_LAYERS_STORE],
- TransactionMode::ReadWrite,
- )?;
- tx.object_store(OPTIMISTIC_LAYERS_STORE)?.clear()?;
- tx.object_store(MUTATION_QUEUE_STORE)?.clear()?;
- tx.object_store(RECORDS_STORE)?.clear()?;
- tx.commit()?.await?;
- Ok(())
- }
-}
diff --git a/crates/client/cache-idb/src/lib.rs b/crates/client/cache-idb/src/lib.rs
deleted file mode 100644
index f652989e74..0000000000
--- a/crates/client/cache-idb/src/lib.rs
+++ /dev/null
@@ -1,18 +0,0 @@
-//! IndexedDB [`Storage`](cache_core::store::Storage) backend for the browser
-//! host (wasm module in a SharedWorker / dedicated worker).
-//!
-//! One stable IndexedDB database per cache scope. Disposable normalized
-//! records are versioned by schema compatibility epoch and cache format,
-//! while queued mutations and their optimistic layers remain discoverable
-//! across incompatible record-schema changes.
-//! Postcard payloads are stored in indexable record envelopes whose `value`
-//! property is a `Uint8Array`.
-//!
-//! wasm32-only; on other targets this crate is an empty shell so workspace
-//! `cargo test` stays green.
-
-#[cfg(target_arch = "wasm32")]
-mod idb_storage;
-
-#[cfg(target_arch = "wasm32")]
-pub use idb_storage::{IdbStorage, IdbStorageError};
diff --git a/crates/client/cache-idb/tests/web.rs b/crates/client/cache-idb/tests/web.rs
deleted file mode 100644
index e728fedc54..0000000000
--- a/crates/client/cache-idb/tests/web.rs
+++ /dev/null
@@ -1,205 +0,0 @@
-//! Browser tests for the IndexedDB backend. Run with:
-//! `wasm-pack test --headless --chrome cache-idb`
-//! (or `--firefox`). Not part of native `cargo test`.
-
-#![cfg(target_arch = "wasm32")]
-
-use cache_core::engine::{Engine, ReadResult};
-use cache_core::queue::{
- MutationClaimRequest, MutationClaimToken, MutationRequest, NewQueuedMutation,
- PersistedOptimisticLayer, StoredMutation,
-};
-use cache_core::record_selection::RecordSelection;
-use cache_core::store::Storage;
-use cache_core::value::{CacheValue, EntityKey, Record};
-use cache_idb::IdbStorage;
-use wasm_bindgen_test::*;
-
-wasm_bindgen_test_configure!(run_in_browser);
-
-fn record(name: &str) -> Record {
- let mut r = Record::default();
- r.fields
- .insert("name".into(), CacheValue::String(name.into()));
- r
-}
-
-fn key(s: &str) -> EntityKey<'static> {
- EntityKey(s.to_string().into())
-}
-
-fn queued(name: &str) -> NewQueuedMutation {
- NewQueuedMutation {
- mutation: StoredMutation::new(
- MutationRequest {
- query: "mutation Rename { rename { id } }".into(),
- operation_name: Some("Rename".into()),
- variables_json: format!(r#"{{"name":"{name}"}}"#),
- identity: Some("user-1".into()),
- },
- 10,
- ),
- optimistic: PersistedOptimisticLayer {
- optimistic_data_json: format!(r#"{{"rename":{{"name":"{name}"}}}}"#),
- normalized_updates: [(key("A:1"), record(name))].into(),
- },
- }
-}
-
-#[wasm_bindgen_test]
-async fn put_get_delete_roundtrip() {
- IdbStorage::destroy("test-rt").await.unwrap();
- let mut s = IdbStorage::open("test-rt").await.unwrap();
-
- s.put_batch(vec![(key("A:1"), record("a")), (key("B:2"), record("b"))])
- .await
- .unwrap();
-
- let got = s
- .get_batch(&[key("A:1"), key("C:3"), key("B:2")])
- .await
- .unwrap();
- assert_eq!(got[0].as_ref().unwrap(), &record("a"));
- assert!(got[1].is_none());
- assert_eq!(got[2].as_ref().unwrap(), &record("b"));
-
- s.put_batch(vec![(key("A:1"), record("a2"))]).await.unwrap();
- let got = s.get_batch(&[key("A:1")]).await.unwrap();
- assert_eq!(got[0].as_ref().unwrap(), &record("a2"));
-
- s.delete_batch(&[key("A:1")]).await.unwrap();
- assert!(s.get_batch(&[key("A:1")]).await.unwrap()[0].is_none());
-
- s.clear().await.unwrap();
- assert!(s.get_batch(&[key("B:2")]).await.unwrap()[0].is_none());
-}
-
-#[wasm_bindgen_test]
-async fn scans_selected_record_types_in_key_order() {
- let scope = "test-record-scan";
- IdbStorage::destroy(scope).await.unwrap();
- let mut storage = IdbStorage::open(scope).await.unwrap();
- storage
- .put_batch(vec![
- (key("TypeB:2"), record("b2")),
- (key("Other:1"), record("other")),
- (key("TypeA:2"), record("a2")),
- (key("TypeA:1"), record("a1")),
- ])
- .await
- .unwrap();
-
- let first = storage
- .scan_records(&["TypeB".into(), "TypeA".into()], None, 2)
- .await
- .unwrap();
- assert_eq!(
- first
- .iter()
- .map(|(key, _)| key.0.as_ref())
- .collect::<Vec<_>>(),
- vec!["TypeA:1", "TypeA:2"]
- );
- let second = storage
- .scan_records(&["TypeA".into(), "TypeB".into()], Some(&first[1].0), 2)
- .await
- .unwrap();
- assert_eq!(
- second
- .iter()
- .map(|(key, _)| key.0.as_ref())
- .collect::<Vec<_>>(),
- vec!["TypeB:2"]
- );
-}
-
-#[wasm_bindgen_test]
-async fn persists_across_reopen() {
- IdbStorage::destroy("test-persist").await.unwrap();
- let mut s = IdbStorage::open("test-persist").await.unwrap();
- s.put_batch(vec![(key("A:1"), record("a"))]).await.unwrap();
- s.close();
-
- let s = IdbStorage::open("test-persist").await.unwrap();
- let got = s.get_batch(&[key("A:1")]).await.unwrap();
- assert_eq!(got[0].as_ref().unwrap(), &record("a"));
-}
-
-#[wasm_bindgen_test]
-async fn mutation_queue_persists_and_settles_atomically() {
- IdbStorage::destroy("test-queue").await.unwrap();
- let mut storage = IdbStorage::open("test-queue").await.unwrap();
- let id = storage
- .enqueue_mutation(queued("optimistic"))
- .await
- .unwrap();
- storage.close();
-
- let mut storage = IdbStorage::open("test-queue").await.unwrap();
- let loaded = storage.load_mutation_queue().await.unwrap();
- assert_eq!(loaded.len(), 1);
- assert_eq!(loaded[0].id, id);
- let claimed = storage
- .claim_next_mutation(MutationClaimRequest {
- owner: "runner".into(),
- now_ms: 20,
- lease_expires_at_ms: 100,
- })
- .await
- .unwrap()
- .unwrap();
- assert!(
- storage
- .complete_mutation(
- id,
- MutationClaimToken {
- owner: "runner".into(),
- generation: claimed.lease_generation,
- },
- vec![(key("A:1"), record("server"))],
- )
- .await
- .unwrap()
- );
- assert!(storage.load_mutation_queue().await.unwrap().is_empty());
- assert_eq!(
- storage.get_batch(&[key("A:1")]).await.unwrap()[0],
- Some(record("server"))
- );
-}
-
-#[wasm_bindgen_test]
-async fn engine_over_idb() {
- IdbStorage::destroy("test-engine").await.unwrap();
- let storage = IdbStorage::open("test-engine").await.unwrap();
- let mut engine = Engine::new(storage);
-
- let query = r#"query Soup($input: SoupInput!) {
- user { id soup(input: $input) { nextCursor items { __typename id } } }
- }"#;
- let serde_json::Value::Object(vars) = serde_json::json!({"input": {"limit": 1}}) else {
- unreachable!()
- };
- let data = serde_json::json!({
- "user": { "id": "user-1", "soup": { "nextCursor": null, "items": [{"__typename": "GraphqlSoupDocument", "id": "doc-1"}] } }
- });
-
- engine
- .write_query(None, query, Some("Soup"), &vars, &data, None)
- .await
- .unwrap();
- let ReadResult::Hit { data: cached } = engine
- .read_query(None, query, Some("Soup"), &vars)
- .await
- .unwrap()
- else {
- panic!("expected hit");
- };
- assert_eq!(cached, data);
-
- let selection =
- RecordSelection::parse("fragment Item on GraphqlSoupDocument { id }", "Item").unwrap();
- let page = engine.read_records(&selection, None, 10).await.unwrap();
- assert_eq!(page.records, vec![serde_json::json!({"id": "doc-1"})]);
- assert!(page.next_cursor.is_none());
-}
diff --git a/crates/client/cache-sqlite/Cargo.toml b/crates/client/cache-sqlite/Cargo.toml
index eb622ac86f..5f3ed89f1d 100644
--- a/crates/client/cache-sqlite/Cargo.toml
+++ b/crates/client/cache-sqlite/Cargo.toml
@@ -12,6 +12,6 @@ rusqlite = { version = "0.32", features = ["bundled"] }
thiserror = { workspace = true }
[dev-dependencies]
-pollster = "0.4"
+pollster = { workspace = true }
serde_json = { workspace = true }
tempfile = "3"
diff --git a/crates/client/cache-sqlite/src/lib.rs b/crates/client/cache-sqlite/src/lib.rs
index eca2898c30..bfc49d5e90 100644
--- a/crates/client/cache-sqlite/src/lib.rs
+++ b/crates/client/cache-sqlite/src/lib.rs
@@ -20,7 +20,7 @@ use cache_core::queue::{
ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, MutationRequest,
NewQueuedMutation, PersistedOptimisticLayer, QueuedMutation, StoredMutation,
};
-use cache_core::store::Storage;
+use cache_core::store::{QueueDiagnostics, QueueDiagnosticsAvailability, Storage};
use cache_core::value::{EntityKey, Record};
use rusqlite::{Connection, OptionalExtension, Transaction, params, params_from_iter};
use std::path::Path;
@@ -89,6 +89,8 @@ impl SqliteStorage {
last_error TEXT,
created_at_ms INTEGER NOT NULL
);
+ CREATE INDEX IF NOT EXISTS mutation_queue_created_at_ms_idx
+ ON mutation_queue(created_at_ms);
CREATE TABLE IF NOT EXISTS optimistic_layers (
mutation_id INTEGER PRIMARY KEY,
optimistic_data_json TEXT NOT NULL,
@@ -388,6 +390,27 @@ impl Storage for SqliteStorage {
Ok(out)
}
+ async fn queue_diagnostics(&self) -> Result<QueueDiagnostics, Self::Error> {
+ let (depth, oldest_created_at_ms): (i64, Option<i64>) = self.conn().query_row(
+ "SELECT COUNT(*), MIN(created_at_ms) FROM mutation_queue",
+ [],
+ |row| Ok((row.get(0)?, row.get(1)?)),
+ )?;
+ let depth = u64::try_from(depth).map_err(|_| {
+ SqliteStorageError::QueueInvariant("negative mutation queue depth".to_string())
+ })?;
+ if (depth == 0) != oldest_created_at_ms.is_none() {
+ return Err(SqliteStorageError::QueueInvariant(
+ "queue depth and oldest timestamp disagree".to_string(),
+ ));
+ }
+ Ok(QueueDiagnostics {
+ availability: QueueDiagnosticsAvailability::Available,
+ depth,
+ oldest_created_at_ms,
+ })
+ }
+
async fn claim_next_mutation(
&mut self,
request: MutationClaimRequest,
@@ -598,6 +621,75 @@ mod tests {
});
}
+ #[test]
+ fn queue_diagnostics_return_only_depth_and_oldest_timestamp() {
+ block_on(async {
+ let storage = SqliteStorage::open_in_memory("user-1").unwrap();
+ assert_eq!(
+ storage.queue_diagnostics().await.unwrap(),
+ QueueDiagnostics {
+ availability: QueueDiagnosticsAvailability::Available,
+ depth: 0,
+ oldest_created_at_ms: None,
+ }
+ );
+ storage
+ .conn()
+ .execute(
+ "INSERT INTO mutation_queue (query, variables_json, created_at_ms) VALUES ('mutation A { a }', '{}', 9), ('mutation B { b }', '{}', 4)",
+ [],
+ )
+ .unwrap();
+ assert_eq!(
+ storage.queue_diagnostics().await.unwrap(),
+ QueueDiagnostics {
+ availability: QueueDiagnosticsAvailability::Available,
+ depth: 2,
+ oldest_created_at_ms: Some(4),
+ }
+ );
+ });
+ }
+
+ #[test]
+ fn queue_diagnostics_query_uses_covering_index_at_scale() {
+ block_on(async {
+ let storage = SqliteStorage::open_in_memory("queue-plan").unwrap();
+ storage
+ .conn()
+ .execute(
+ "WITH RECURSIVE values_to_insert(value) AS (VALUES(1) UNION ALL SELECT value + 1 FROM values_to_insert WHERE value < 10000) INSERT INTO mutation_queue (query, variables_json, created_at_ms) SELECT 'mutation Scale { scale }', '{}', 10001 - value FROM values_to_insert",
+ [],
+ )
+ .unwrap();
+ let details = {
+ let conn = storage.conn();
+ let mut plan = conn
+ .prepare(
+ "EXPLAIN QUERY PLAN SELECT COUNT(*), MIN(created_at_ms) FROM mutation_queue",
+ )
+ .unwrap();
+ plan.query_map([], |row| row.get::<_, String>(3))
+ .unwrap()
+ .collect::<Result<Vec<_>, _>>()
+ .unwrap()
+ .join(" ")
+ };
+ assert!(
+ details.contains("mutation_queue_created_at_ms_idx"),
+ "diagnostics query did not use the timestamp index: {details}"
+ );
+ assert_eq!(
+ storage.queue_diagnostics().await.unwrap(),
+ QueueDiagnostics {
+ availability: QueueDiagnosticsAvailability::Available,
+ depth: 10_000,
+ oldest_created_at_ms: Some(1),
+ }
+ );
+ });
+ }
+
#[test]
fn scans_selected_record_types_in_key_order() {
block_on(async {
diff --git a/crates/client/cache-turso/Cargo.toml b/crates/client/cache-turso/Cargo.toml
new file mode 100644
index 0000000000..9d6888af4a
--- /dev/null
+++ b/crates/client/cache-turso/Cargo.toml
@@ -0,0 +1,31 @@
+[package]
+edition = "2024"
+name = "cache-turso"
+publish = false
+version = "0.1.0"
+
+[features]
+default = []
+browser-test-hooks = []
+
+[dependencies]
+cache-core = { path = "../cache-core" }
+maybe_send = { path = "../../maybe_send" }
+thiserror = { workspace = true }
+
+[target.'cfg(target_arch = "wasm32")'.dependencies]
+turso-opfs = { path = "../turso-opfs" }
+turso_core = { workspace = true, features = ["fs", "pure-rust-crypto", "uuid"] }
+
+[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
+turso_core = { workspace = true, features = ["fs", "pure-rust-crypto", "uuid"] }
+
+[dev-dependencies]
+pollster = { workspace = true }
+serde_json = { workspace = true }
+
+[target.'cfg(not(target_arch = "wasm32"))'.dev-dependencies]
+cache-sqlite = { path = "../cache-sqlite" }
+
+[target.'cfg(target_arch = "wasm32")'.dev-dependencies]
+wasm-bindgen-test = { workspace = true }
diff --git a/crates/client/cache-turso/src/driver.rs b/crates/client/cache-turso/src/driver.rs
new file mode 100644
index 0000000000..3c621b9efa
--- /dev/null
+++ b/crates/client/cache-turso/src/driver.rs
@@ -0,0 +1,324 @@
+use crate::{PhysicalResetReason, TursoStorageError};
+use std::num::NonZeroUsize;
+use std::sync::Arc;
+use turso_core::{Connection, LimboError, Statement, StepResult, Value};
+
+pub(crate) type Values = Vec<Value>;
+pub(crate) type Rows = Vec<Values>;
+
+struct RunFailure {
+ error: TursoStorageError,
+ execution_completed: bool,
+ cleanup_failed: bool,
+}
+
+impl RunFailure {
+ fn execution(error: TursoStorageError) -> Self {
+ Self {
+ error,
+ execution_completed: false,
+ cleanup_failed: false,
+ }
+ }
+
+ fn cleanup(execution_completed: bool) -> Self {
+ Self {
+ error: TursoStorageError::reset(PhysicalResetReason::TransactionOutcomeUncertain),
+ execution_completed,
+ cleanup_failed: true,
+ }
+ }
+}
+
+pub(crate) fn prepare(
+ connection: &Arc<Connection>,
+ sql: &str,
+) -> Result<Statement, TursoStorageError> {
+ connection.prepare(sql).map_err(TursoStorageError::turso)
+}
+
+pub(crate) fn validate(connection: &Arc<Connection>, sql: &str) -> Result<(), TursoStorageError> {
+ let mut statement = prepare(connection, sql)?;
+ checked_reset(&mut statement)?;
+ statement.clear_bindings();
+ Ok(())
+}
+
+pub(crate) fn execute(
+ connection: &Arc<Connection>,
+ sql: &str,
+ values: Values,
+) -> Result<i64, TursoStorageError> {
+ let mut statement = prepare(connection, sql)?;
+ execute_prepared(&mut statement, values)
+}
+
+pub(crate) fn query(
+ connection: &Arc<Connection>,
+ sql: &str,
+ values: Values,
+) -> Result<Rows, TursoStorageError> {
+ let mut statement = prepare(connection, sql)?;
+ query_prepared(&mut statement, values)
+}
+
+pub(crate) fn execute_prepared(
+ statement: &mut Statement,
+ values: Values,
+) -> Result<i64, TursoStorageError> {
+ execute_prepared_detailed(statement, values).map_err(|failure| failure.error)
+}
+
+fn execute_prepared_detailed(statement: &mut Statement, values: Values) -> Result<i64, RunFailure> {
+ let (rows, changed) = run_prepared(statement, values)?;
+ if rows.is_empty() {
+ Ok(changed)
+ } else {
+ Err(RunFailure::execution(TursoStorageError::Database))
+ }
+}
+
+pub(crate) fn query_prepared(
+ statement: &mut Statement,
+ values: Values,
+) -> Result<Rows, TursoStorageError> {
+ run_prepared(statement, values)
+ .map(|(rows, _)| rows)
+ .map_err(|failure| failure.error)
+}
+
+fn run_prepared(statement: &mut Statement, values: Values) -> Result<(Rows, i64), RunFailure> {
+ let execution = (|| {
+ if statement.parameters_count() != values.len() {
+ return Err(TursoStorageError::Database);
+ }
+ for (offset, value) in values.into_iter().enumerate() {
+ let index = NonZeroUsize::new(offset + 1).ok_or(TursoStorageError::Database)?;
+ statement
+ .bind_at(index, value)
+ .map_err(TursoStorageError::turso)?;
+ }
+
+ let mut rows = Vec::new();
+ loop {
+ // The pinned Turso revision completes this rollback without
+ // producing rollback-owned File work. Native fault tests use this
+ // private scheduler hook to exercise a failure from the rollback's
+ // StepResult::IO/IO::step polling boundary without manufacturing a
+ // completion or describing a post-success error as completion-delivered.
+ #[cfg(all(test, not(target_arch = "wasm32")))]
+ let forced_control_io = take_forced_control_io();
+ #[cfg(any(not(test), target_arch = "wasm32"))]
+ let forced_control_io = false;
+ let step = if forced_control_io {
+ StepResult::IO
+ } else {
+ statement.step().map_err(TursoStorageError::turso)?
+ };
+ match step {
+ StepResult::Done => break,
+ StepResult::Row => {
+ let row = statement
+ .row()
+ .ok_or_else(|| TursoStorageError::reset(PhysicalResetReason::Corruption))?;
+ rows.push(row.get_values().cloned().collect());
+ }
+ StepResult::IO => {
+ #[cfg(all(test, not(target_arch = "wasm32")))]
+ record_control_io();
+ statement._io().step().map_err(TursoStorageError::turso)?
+ }
+ StepResult::Yield => statement._io().step().map_err(TursoStorageError::turso)?,
+ StepResult::Busy => return Err(TursoStorageError::turso(LimboError::Busy)),
+ StepResult::Interrupt => {
+ return Err(TursoStorageError::turso(LimboError::Interrupt));
+ }
+ }
+ }
+ Ok((rows, statement.n_change()))
+ })();
+
+ // Turso has no separate public finalize call. A checked reset releases the
+ // active VM state and I/O before reuse or drop; dropping then releases the
+ // prepared statement itself. Any reset failure makes that cleanup and any
+ // surrounding transaction unusable, regardless of the underlying class.
+ let reset = checked_reset(statement);
+ statement.clear_bindings();
+ match (execution, reset) {
+ (Ok(value), Ok(())) => Ok(value),
+ (Err(error), Ok(())) => Err(RunFailure::execution(error)),
+ (execution, Err(_)) => Err(RunFailure::cleanup(execution.is_ok())),
+ }
+}
+
+fn checked_reset(statement: &mut Statement) -> Result<(), TursoStorageError> {
+ let reset = statement
+ .reset()
+ .map_err(|_| TursoStorageError::reset(PhysicalResetReason::TransactionOutcomeUncertain));
+ #[cfg(all(test, not(target_arch = "wasm32")))]
+ if take_reset_failure(statement.get_sql()) {
+ return Err(TursoStorageError::reset(
+ PhysicalResetReason::TransactionOutcomeUncertain,
+ ));
+ }
+ reset
+}
+
+pub(crate) fn read_transaction<T>(
+ connection: &Arc<Connection>,
+ operation: impl FnOnce() -> Result<T, TursoStorageError>,
+) -> Result<T, TursoStorageError> {
+ transaction(connection, "BEGIN", operation)
+}
+
+pub(crate) fn write_transaction<T>(
+ connection: &Arc<Connection>,
+ operation: impl FnOnce() -> Result<T, TursoStorageError>,
+) -> Result<T, TursoStorageError> {
+ transaction(connection, "BEGIN IMMEDIATE", operation)
+}
+
+fn transaction<T>(
+ connection: &Arc<Connection>,
+ begin_sql: &str,
+ operation: impl FnOnce() -> Result<T, TursoStorageError>,
+) -> Result<T, TursoStorageError> {
+ let begin = execute_control(connection, begin_sql, TestControlPhase::Begin);
+ if let Err(failure) = begin {
+ if failure.execution_completed && failure.cleanup_failed {
+ let _ = execute_control(connection, "ROLLBACK", TestControlPhase::Rollback);
+ }
+ return Err(failure.error);
+ }
+
+ match operation() {
+ Ok(value) => match execute_control(connection, "COMMIT", TestControlPhase::Commit) {
+ Ok(_) => Ok(value),
+ Err(_) => {
+ let _ = execute_control(connection, "ROLLBACK", TestControlPhase::Rollback);
+ Err(TursoStorageError::reset(
+ PhysicalResetReason::TransactionOutcomeUncertain,
+ ))
+ }
+ },
+ Err(error) => match execute_control(connection, "ROLLBACK", TestControlPhase::Rollback) {
+ Ok(_) => Err(error),
+ Err(_) => Err(TursoStorageError::reset(
+ PhysicalResetReason::TransactionOutcomeUncertain,
+ )),
+ },
+ }
+}
+
+fn execute_control(
+ connection: &Arc<Connection>,
+ sql: &str,
+ phase: TestControlPhase,
+) -> Result<i64, RunFailure> {
+ #[cfg(all(test, not(target_arch = "wasm32")))]
+ record_control_phase(phase);
+ #[cfg(all(test, not(target_arch = "wasm32")))]
+ let _phase_guard = TestControlPhaseGuard::enter(phase);
+ #[cfg(any(not(test), target_arch = "wasm32"))]
+ let _ = phase;
+ let mut statement = prepare(connection, sql).map_err(RunFailure::execution)?;
+ execute_prepared_detailed(&mut statement, Vec::new())
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum TestControlPhase {
+ Begin,
+ Commit,
+ Rollback,
+}
+
+#[cfg(all(test, not(target_arch = "wasm32")))]
+thread_local! {
+ static RESET_FAILURE_SQL: std::cell::RefCell<Option<String>> = const { std::cell::RefCell::new(None) };
+ static CURRENT_CONTROL_PHASE: std::cell::Cell<Option<TestControlPhase>> = const { std::cell::Cell::new(None) };
+ static CONTROL_TRACE: std::cell::RefCell<Vec<TestControlPhase>> = const { std::cell::RefCell::new(Vec::new()) };
+ static CONTROL_IO_TRACE: std::cell::RefCell<Vec<TestControlPhase>> = const { std::cell::RefCell::new(Vec::new()) };
+ static FORCE_CONTROL_IO: std::cell::Cell<bool> = const { std::cell::Cell::new(false) };
+}
+
+#[cfg(all(test, not(target_arch = "wasm32")))]
+struct TestControlPhaseGuard {
+ previous: Option<TestControlPhase>,
+}
+
+#[cfg(all(test, not(target_arch = "wasm32")))]
+impl TestControlPhaseGuard {
+ fn enter(phase: TestControlPhase) -> Self {
+ let previous = CURRENT_CONTROL_PHASE.with(|current| current.replace(Some(phase)));
+ Self { previous }
+ }
+}
+
+#[cfg(all(test, not(target_arch = "wasm32")))]
+impl Drop for TestControlPhaseGuard {
+ fn drop(&mut self) {
+ CURRENT_CONTROL_PHASE.with(|current| current.set(self.previous));
+ }
+}
+
+#[cfg(all(test, not(target_arch = "wasm32")))]
+fn take_reset_failure(sql: &str) -> bool {
+ RESET_FAILURE_SQL.with(|fault| {
+ if fault.borrow().as_deref() == Some(sql) {
+ fault.borrow_mut().take();
+ true
+ } else {
+ false
+ }
+ })
+}
+
+#[cfg(all(test, not(target_arch = "wasm32")))]
+fn record_control_phase(phase: TestControlPhase) {
+ CONTROL_TRACE.with(|trace| trace.borrow_mut().push(phase));
+}
+
+#[cfg(all(test, not(target_arch = "wasm32")))]
+fn take_forced_control_io() -> bool {
+ current_test_control_phase() == Some(TestControlPhase::Rollback)
+ && FORCE_CONTROL_IO.with(|forced| forced.replace(false))
+}
+
+#[cfg(all(test, not(target_arch = "wasm32")))]
+fn record_control_io() {
+ if let Some(phase) = current_test_control_phase() {
+ CONTROL_IO_TRACE.with(|trace| trace.borrow_mut().push(phase));
+ }
+}
+
+#[cfg(all(test, not(target_arch = "wasm32")))]
+pub(crate) fn current_test_control_phase() -> Option<TestControlPhase> {
+ CURRENT_CONTROL_PHASE.with(std::cell::Cell::get)
+}
+
+#[cfg(all(test, not(target_arch = "wasm32")))]
+pub(crate) fn arm_reset_failure(sql: &str) {
+ RESET_FAILURE_SQL.with(|fault| *fault.borrow_mut() = Some(sql.to_owned()));
+}
+
+#[cfg(all(test, not(target_arch = "wasm32")))]
+pub(crate) fn arm_rollback_control_io() {
+ FORCE_CONTROL_IO.with(|forced| forced.set(true));
+}
+
+#[cfg(all(test, not(target_arch = "wasm32")))]
+pub(crate) fn clear_control_trace() {
+ CONTROL_TRACE.with(|trace| trace.borrow_mut().clear());
+ CONTROL_IO_TRACE.with(|trace| trace.borrow_mut().clear());
+ FORCE_CONTROL_IO.with(|forced| forced.set(false));
+}
+
+#[cfg(all(test, not(target_arch = "wasm32")))]
+pub(crate) fn take_control_trace() -> Vec<TestControlPhase> {
+ CONTROL_TRACE.with(|trace| std::mem::take(&mut *trace.borrow_mut()))
+}
+
+#[cfg(all(test, not(target_arch = "wasm32")))]
+pub(crate) fn take_control_io_trace() -> Vec<TestControlPhase> {
+ CONTROL_IO_TRACE.with(|trace| std::mem::take(&mut *trace.borrow_mut()))
+}
diff --git a/crates/client/cache-turso/src/error.rs b/crates/client/cache-turso/src/error.rs
new file mode 100644
index 0000000000..ea0733e840
--- /dev/null
+++ b/crates/client/cache-turso/src/error.rs
@@ -0,0 +1,129 @@
+use std::io::ErrorKind;
+use thiserror::Error;
+use turso_core::{CompletionError, LimboError};
+
+/// The reason an open browser cache must be physically replaced.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Error)]
+pub enum PhysicalResetReason {
+ /// The database or one of its checked rows is structurally corrupt.
+ #[error("corrupt local database")]
+ Corruption,
+ /// A postcard payload failed the shared cache codec.
+ #[error("corrupt cache payload")]
+ Codec,
+ /// Queue, key, numeric, or relational state violated the frozen schema contract.
+ #[error("invalid durable cache state")]
+ Invariant,
+ /// The browser storage quota is full.
+ #[error("browser storage is full")]
+ StorageFull,
+ /// A commit, rollback, or statement cleanup left transaction durability uncertain.
+ #[error("transaction outcome is uncertain")]
+ TransactionOutcomeUncertain,
+ /// A storage I/O operation failed or returned an unexpected completion state.
+ #[error("storage I/O is uncertain")]
+ Io,
+ /// Required schema or metadata is missing or incompatible.
+ #[error("storage compatibility mismatch")]
+ Compatibility,
+ /// The approved integrity check did not return its sole success row.
+ #[error("storage integrity check failed")]
+ Integrity,
+}
+
+impl PhysicalResetReason {
+ pub(crate) const fn latch_code(self) -> u8 {
+ match self {
+ Self::Corruption => 1,
+ Self::Codec => 2,
+ Self::Invariant => 3,
+ Self::StorageFull => 4,
+ Self::TransactionOutcomeUncertain => 5,
+ Self::Io => 6,
+ Self::Compatibility => 7,
+ Self::Integrity => 8,
+ }
+ }
+
+ pub(crate) const fn from_latch_code(code: u8) -> Option<Self> {
+ match code {
+ 1 => Some(Self::Corruption),
+ 2 => Some(Self::Codec),
+ 3 => Some(Self::Invariant),
+ 4 => Some(Self::StorageFull),
+ 5 => Some(Self::TransactionOutcomeUncertain),
+ 6 => Some(Self::Io),
+ 7 => Some(Self::Compatibility),
+ 8 => Some(Self::Integrity),
+ _ => None,
+ }
+ }
+}
+
+/// Errors produced by the Turso storage backend.
+///
+/// Errors deliberately contain no entity keys, cache scope, GraphQL text,
+/// variables, record bytes, or mutation payloads.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Error)]
+pub enum TursoStorageError {
+ /// A caller supplied a value outside the checked storage contract.
+ #[error("invalid storage input")]
+ InvalidInput,
+ /// A deterministic database operation failed without an uncertain commit outcome.
+ #[error("Turso database operation failed")]
+ Database,
+ /// The disposable physical database must be closed and replaced.
+ #[error("physical cache reset required: {0}")]
+ PhysicalResetRequired(PhysicalResetReason),
+}
+
+impl TursoStorageError {
+ /// Returns whether the current physical database must not be reused.
+ pub const fn requires_physical_reset(&self) -> bool {
+ matches!(self, Self::PhysicalResetRequired(_))
+ }
+
+ /// Returns the physical-reset reason, when replacement is required.
+ pub const fn physical_reset_reason(&self) -> Option<PhysicalResetReason> {
+ match self {
+ Self::PhysicalResetRequired(reason) => Some(*reason),
+ Self::InvalidInput | Self::Database => None,
+ }
+ }
+
+ pub(crate) const fn reset(reason: PhysicalResetReason) -> Self {
+ Self::PhysicalResetRequired(reason)
+ }
+
+ pub(crate) fn turso(error: LimboError) -> Self {
+ match error {
+ LimboError::Corrupt(_)
+ | LimboError::NotADB
+ | LimboError::InvalidColumnType
+ | LimboError::InvalidBlobSize(_)
+ | LimboError::Page1NotAlloc => Self::reset(PhysicalResetReason::Corruption),
+ LimboError::DatabaseFull(_)
+ | LimboError::CompletionError(CompletionError::IOError(ErrorKind::StorageFull, _)) => {
+ Self::reset(PhysicalResetReason::StorageFull)
+ }
+ LimboError::CompletionError(
+ CompletionError::DecryptionError { .. }
+ | CompletionError::PageCodecError { .. }
+ | CompletionError::ShortRead { .. }
+ | CompletionError::ShortReadWalFrame { .. }
+ | CompletionError::WalFramePageMismatch { .. }
+ | CompletionError::ChecksumMismatch { .. }
+ | CompletionError::ChecksumNotEnabled,
+ ) => Self::reset(PhysicalResetReason::Corruption),
+ LimboError::CompletionError(_) => Self::reset(PhysicalResetReason::Io),
+ _ => Self::Database,
+ }
+ }
+
+ pub(crate) const fn initialization(self) -> Self {
+ match self {
+ Self::PhysicalResetRequired(_) => self,
+ Self::InvalidInput | Self::Database => Self::reset(PhysicalResetReason::Compatibility),
+ }
+ }
+}
diff --git a/crates/client/cache-turso/src/key.rs b/crates/client/cache-turso/src/key.rs
new file mode 100644
index 0000000000..17362c375d
--- /dev/null
+++ b/crates/client/cache-turso/src/key.rs
@@ -0,0 +1,65 @@
+use crate::{PhysicalResetReason, TursoStorageError};
+use cache_core::value::{EntityKey, ROOT_QUERY};
+use std::borrow::Cow;
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct RecordKey {
+ pub(crate) typename: String,
+ pub(crate) id: String,
+}
+
+impl RecordKey {
+ pub(crate) fn from_entity(key: &EntityKey<'_>) -> Result<Self, TursoStorageError> {
+ let value = key.as_ref();
+ let parsed = if value == ROOT_QUERY {
+ Self {
+ typename: ROOT_QUERY.to_owned(),
+ id: String::new(),
+ }
+ } else {
+ let (typename, id) = value
+ .split_once(':')
+ .ok_or(TursoStorageError::InvalidInput)?;
+ if typename.is_empty() {
+ return Err(TursoStorageError::InvalidInput);
+ }
+ Self {
+ typename: typename.to_owned(),
+ id: id.to_owned(),
+ }
+ };
+ if parsed.canonical_string()? != value {
+ return Err(TursoStorageError::InvalidInput);
+ }
+ Ok(parsed)
+ }
+
+ pub(crate) fn into_entity(self) -> Result<EntityKey<'static>, TursoStorageError> {
+ let canonical = self.canonical_string_from_row()?;
+ let reparsed = Self::from_entity(&EntityKey(Cow::Borrowed(&canonical)))
+ .map_err(|_| TursoStorageError::reset(PhysicalResetReason::Corruption))?;
+ if reparsed != self {
+ return Err(TursoStorageError::reset(PhysicalResetReason::Corruption));
+ }
+ Ok(EntityKey(Cow::Owned(canonical)))
+ }
+
+ fn canonical_string(&self) -> Result<String, TursoStorageError> {
+ if self.typename.is_empty() {
+ return Err(TursoStorageError::InvalidInput);
+ }
+ if self.typename == ROOT_QUERY && self.id.is_empty() {
+ Ok(ROOT_QUERY.to_owned())
+ } else {
+ Ok(format!("{}:{}", self.typename, self.id))
+ }
+ }
+
+ fn canonical_string_from_row(&self) -> Result<String, TursoStorageError> {
+ self.canonical_string()
+ .map_err(|_| TursoStorageError::reset(PhysicalResetReason::Corruption))
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/client/cache-turso/src/key/test.rs b/crates/client/cache-turso/src/key/test.rs
new file mode 100644
index 0000000000..bfc2278225
--- /dev/null
+++ b/crates/client/cache-turso/src/key/test.rs
@@ -0,0 +1,41 @@
+use super::*;
+
+#[test]
+fn checked_entity_key_round_trips() {
+ for value in [
+ // ROOT_QUERY is the only key accepted without a typename/id separator;
+ // ROOT_QUERY: remains invalid, while ordinary typenames may have empty IDs.
+ "ROOT_QUERY",
+ "GraphqlSoupDocument:doc-1",
+ "GraphqlSoupDocument:tenant:doc-1",
+ "__meta:identity",
+ "Thing:",
+ ] {
+ let entity = EntityKey(Cow::Borrowed(value));
+ let pair = RecordKey::from_entity(&entity).unwrap();
+ assert_eq!(pair.into_entity().unwrap().as_ref(), value);
+ }
+}
+
+#[test]
+fn invalid_entity_keys_and_sql_pairs_are_rejected() {
+ for value in ["", "Thing", ":id", "ROOT_QUERY:"] {
+ assert!(RecordKey::from_entity(&EntityKey(Cow::Borrowed(value))).is_err());
+ }
+ let empty_typename = RecordKey {
+ typename: String::new(),
+ id: "id".into(),
+ };
+ assert!(
+ empty_typename
+ .into_entity()
+ .unwrap_err()
+ .requires_physical_reset()
+ );
+
+ let root_query = RecordKey {
+ typename: "ROOT_QUERY".into(),
+ id: String::new(),
+ };
+ assert_eq!(root_query.into_entity().unwrap().as_ref(), "ROOT_QUERY");
+}
diff --git a/crates/client/cache-turso/src/lib.rs b/crates/client/cache-turso/src/lib.rs
new file mode 100644
index 0000000000..0784814675
--- /dev/null
+++ b/crates/client/cache-turso/src/lib.rs
@@ -0,0 +1,28 @@
+//! Production Turso storage adapter for the normalized GraphQL cache.
+//!
+//! The adapter implements every [`cache_core::store::Storage`] operation with
+//! the frozen compound-key schema, checked postcard payloads, strict-head
+//! mutation leasing, and immediate write transactions. Incompatible or
+//! uncertain disposable state is classified for physical reset; it is never
+//! migrated, copied, logged, or redirected to a fallback backend.
+
+#![deny(missing_docs)]
+#![forbid(unsafe_code)]
+
+mod driver;
+mod error;
+mod key;
+mod storage;
+
+pub use error::{PhysicalResetReason, TursoStorageError};
+pub use storage::{
+ BROWSER_STORAGE_SCHEMA_VERSION, TursoStorage, TursoStorageCloseOutcome, TursoStorageOpenOutcome,
+};
+
+#[cfg(not(target_arch = "wasm32"))]
+pub use storage::TursoMemoryDatabase;
+#[cfg(target_arch = "wasm32")]
+pub use storage::{
+ HealthyTursoStorageClosed, ResetRequiredTursoStorageClosed, TursoStorageCloseFailure,
+ TursoStorageOpenFailure, TursoStorageResetFailure,
+};
diff --git a/crates/client/cache-turso/src/storage.rs b/crates/client/cache-turso/src/storage.rs
new file mode 100644
index 0000000000..b0a1091e29
--- /dev/null
+++ b/crates/client/cache-turso/src/storage.rs
@@ -0,0 +1,2141 @@
+use crate::driver;
+use crate::key::RecordKey;
+use crate::{PhysicalResetReason, TursoStorageError};
+use cache_core::codec::{
+ cache_namespace, decode_record, decode_record_updates, encode_record, encode_record_updates,
+};
+use cache_core::queue::{
+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, MutationRequest,
+ NewQueuedMutation, PersistedOptimisticLayer, QueuedMutation, StoredMutation,
+};
+use cache_core::store::{QueueDiagnostics, QueueDiagnosticsAvailability, Storage};
+use cache_core::value::{EntityKey, Record};
+use std::sync::Arc;
+use std::sync::atomic::{AtomicU8, Ordering};
+use turso_core::{Connection, Numeric, Value};
+
+#[cfg(not(target_arch = "wasm32"))]
+use std::sync::Mutex;
+#[cfg(not(target_arch = "wasm32"))]
+use std::sync::atomic::AtomicU64;
+#[cfg(not(target_arch = "wasm32"))]
+use turso_core::{Database, IO, MemoryIO, OpenOptions, SqliteDialect};
+#[cfg(target_arch = "wasm32")]
+use turso_opfs::{
+ CloseFailure, ClosedSession, ConnectedOpfsSession, OpenDisposition, OpfsError, OpfsOwner,
+ ResetFailure,
+};
+
+/// Frozen browser-storage schema version, independent of cache postcard versions.
+pub const BROWSER_STORAGE_SCHEMA_VERSION: u32 = 2;
+
+/// Coarse outcome of validating an OPFS Turso session.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum TursoStorageOpenOutcome {
+ /// Existing compatible storage was validated and preserved.
+ OpenedExisting,
+ /// A fresh physical database was initialized.
+ OpenedNew,
+}
+
+const CREATE_SCHEMA: [&str; 5] = [
+ "CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)",
+ "CREATE TABLE records (__typename TEXT NOT NULL, id TEXT NOT NULL, value BLOB NOT NULL, PRIMARY KEY (__typename, id))",
+ "CREATE TABLE mutation_queue (id INTEGER PRIMARY KEY AUTOINCREMENT, query TEXT NOT NULL, operation_name TEXT, variables_json TEXT NOT NULL, identity TEXT, attempt_count INTEGER NOT NULL DEFAULT 0, next_attempt_at_ms INTEGER, lease_owner TEXT, lease_generation INTEGER NOT NULL DEFAULT 0, lease_expires_at_ms INTEGER, last_error TEXT, created_at_ms INTEGER NOT NULL)",
+ "CREATE INDEX mutation_queue_created_at_ms_idx ON mutation_queue(created_at_ms)",
+ "CREATE TABLE optimistic_layers (mutation_id INTEGER PRIMARY KEY, optimistic_data_json TEXT NOT NULL, normalized_updates BLOB NOT NULL, FOREIGN KEY (mutation_id) REFERENCES mutation_queue(id) ON DELETE CASCADE)",
+];
+const RECORD_GET: &str = "SELECT value FROM records WHERE __typename = ?1 AND id = ?2";
+const RECORD_UPSERT: &str = "INSERT INTO records (__typename, id, value) VALUES (?1, ?2, ?3) ON CONFLICT (__typename, id) DO UPDATE SET value = excluded.value";
+const RECORD_DELETE: &str = "DELETE FROM records WHERE __typename = ?1 AND id = ?2";
+const QUEUE_INSERT: &str = "INSERT INTO mutation_queue (query, operation_name, variables_json, identity, attempt_count, next_attempt_at_ms, lease_owner, lease_generation, lease_expires_at_ms, last_error, created_at_ms) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11)";
+const LAYER_INSERT: &str = "INSERT INTO optimistic_layers (mutation_id, optimistic_data_json, normalized_updates) VALUES (?1, ?2, ?3)";
+const QUEUE_SELECT: &str = "SELECT m.id, m.query, m.operation_name, m.variables_json, m.identity, m.attempt_count, m.next_attempt_at_ms, m.lease_owner, m.lease_generation, m.lease_expires_at_ms, m.last_error, m.created_at_ms, o.optimistic_data_json, o.normalized_updates FROM mutation_queue AS m LEFT JOIN optimistic_layers AS o ON o.mutation_id = m.id ORDER BY m.id ASC";
+const QUEUE_HEAD_SELECT: &str = "SELECT m.id, m.query, m.operation_name, m.variables_json, m.identity, m.attempt_count, m.next_attempt_at_ms, m.lease_owner, m.lease_generation, m.lease_expires_at_ms, m.last_error, m.created_at_ms, o.optimistic_data_json, o.normalized_updates FROM mutation_queue AS m LEFT JOIN optimistic_layers AS o ON o.mutation_id = m.id ORDER BY m.id ASC LIMIT 1";
+const ORPHAN_LAYER_SELECT: &str = "SELECT o.mutation_id FROM optimistic_layers AS o LEFT JOIN mutation_queue AS m ON m.id = o.mutation_id WHERE m.id IS NULL LIMIT 1";
+const ANY_LAYER_SELECT: &str = "SELECT mutation_id FROM optimistic_layers LIMIT 1";
+const CLAIM_SELECT: &str = "SELECT lease_owner, lease_generation FROM mutation_queue WHERE id = ?1";
+const REQUIRE_LAYER_SELECT: &str = "SELECT 1 FROM optimistic_layers WHERE mutation_id = ?1";
+const QUEUE_DIAGNOSTICS_SELECT: &str = "SELECT COUNT(*), MIN(created_at_ms) FROM mutation_queue";
+
+/// Turso-backed implementation of [`Storage`].
+///
+/// On `wasm32` this value owns the consuming
+/// `turso_opfs::ConnectedOpfsSession` capability. It must be consumed with
+/// [`Self::try_close`] before OPFS preservation or reset.
+/// Native builds own a Turso `MemoryIO` database solely for conformance tests.
+pub struct TursoStorage {
+ health: AtomicU8,
+ #[cfg(target_arch = "wasm32")]
+ session: ConnectedOpfsSession,
+ #[cfg(not(target_arch = "wasm32"))]
+ database: Arc<Database>,
+ #[cfg(not(target_arch = "wasm32"))]
+ connection: Arc<Connection>,
+ #[cfg(all(test, not(target_arch = "wasm32")))]
+ fault: Mutex<Option<TestFault>>,
+}
+
+impl std::fmt::Debug for TursoStorage {
+ fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ formatter
+ .debug_struct("TursoStorage")
+ .finish_non_exhaustive()
+ }
+}
+
+#[cfg(target_arch = "wasm32")]
+impl TursoStorage {
+ /// Validates or initializes an already connected, OPFS-owned Turso session.
+ ///
+ /// Initialization failure exposes only a consuming physical-reset
+ /// transition. It never exposes the connected or closed OPFS capability,
+ /// so incompatible files cannot be preserved accidentally.
+ pub fn from_opfs_session(
+ session: ConnectedOpfsSession,
+ scope: &str,
+ ) -> Result<Self, TursoStorageOpenFailure> {
+ Self::from_opfs_session_with_outcome(session, scope).map(|(storage, _)| storage)
+ }
+
+ /// Validates or initializes an OPFS session and returns its coarse outcome.
+ pub fn from_opfs_session_with_outcome(
+ session: ConnectedOpfsSession,
+ scope: &str,
+ ) -> Result<(Self, TursoStorageOpenOutcome), TursoStorageOpenFailure> {
+ let fresh = session.disposition() == OpenDisposition::Fresh;
+ let connection = session.connection();
+ let result = initialize(&connection, scope, fresh);
+ drop(connection);
+ match result {
+ Ok(()) => Ok((
+ Self {
+ health: AtomicU8::new(0),
+ session,
+ },
+ if fresh {
+ TursoStorageOpenOutcome::OpenedNew
+ } else {
+ TursoStorageOpenOutcome::OpenedExisting
+ },
+ )),
+ Err(error) => Err(TursoStorageOpenFailure { error, session }),
+ }
+ }
+
+ /// Browser-test-artifact-only helper used by the storage-control worker.
+ #[cfg(feature = "browser-test-hooks")]
+ #[doc(hidden)]
+ pub fn browser_test_make_namespace_incompatible(&mut self) -> Result<(), TursoStorageError> {
+ self.require_healthy()?;
+ let connection = self.connection();
+ self.latch_result(driver::write_transaction(&connection, || {
+ require_changed(
+ driver::execute(
+ &connection,
+ "UPDATE meta SET value = 'browser-test-incompatible' WHERE key = 'namespace'",
+ Vec::new(),
+ )?,
+ 1,
+ )
+ }))
+ }
+
+ /// Browser-test-artifact-only helper that writes an invalid queue payload.
+ #[cfg(feature = "browser-test-hooks")]
+ #[doc(hidden)]
+ pub fn browser_test_corrupt_queue_payload(&mut self) -> Result<(), TursoStorageError> {
+ self.require_healthy()?;
+ let connection = self.connection();
+ self.latch_result(driver::write_transaction(&connection, || {
+ require_changed(
+ driver::execute(
+ &connection,
+ QUEUE_INSERT,
+ vec![
+ text("mutation BrowserTestCorrupt { __typename }"),
+ Value::Null,
+ text("{}"),
+ Value::Null,
+ Value::from_i64(0),
+ Value::Null,
+ Value::Null,
+ Value::from_i64(0),
+ Value::Null,
+ Value::Null,
+ Value::from_i64(1),
+ ],
+ )?,
+ 1,
+ )?;
+ let id = mutation_id_from_row(connection.last_insert_rowid())?;
+ require_changed(
+ driver::execute(
+ &connection,
+ LAYER_INSERT,
+ vec![
+ Value::from_i64(mutation_id_to_sql(id)?),
+ text("{}"),
+ Value::from_blob(vec![0xff]),
+ ],
+ )?,
+ 1,
+ )
+ }))
+ }
+
+ /// Consumes storage and closes Turso into a health-typed OPFS capability.
+ ///
+ /// Healthy storage may subsequently be preserved or reset. A latched
+ /// reset-required storage returns a capability that exposes reset only.
+ /// Close failure exposes no recoverable session and requires replacing the
+ /// worker before a recovery wipe.
+ pub fn try_close(self) -> Result<TursoStorageCloseOutcome, TursoStorageCloseFailure> {
+ let reason = self.latched_reason();
+ let closed = self
+ .session
+ .try_close()
+ .map_err(TursoStorageCloseFailure::new)?;
+ Ok(match reason {
+ Some(reason) => {
+ TursoStorageCloseOutcome::ResetRequired(ResetRequiredTursoStorageClosed {
+ reason,
+ closed,
+ })
+ }
+ None => TursoStorageCloseOutcome::Healthy(HealthyTursoStorageClosed { closed }),
+ })
+ }
+
+ fn connection(&self) -> Arc<Connection> {
+ self.session.connection()
+ }
+}
+
+/// Result of consuming and gracefully closing a browser Turso storage.
+#[cfg(target_arch = "wasm32")]
+#[derive(Debug)]
+pub enum TursoStorageCloseOutcome {
+ /// The database remained healthy and may be preserved or reset.
+ Healthy(HealthyTursoStorageClosed),
+ /// A reset-required reason was latched, so preservation is unavailable.
+ ResetRequired(ResetRequiredTursoStorageClosed),
+}
+
+/// Closed healthy browser storage that may be preserved or reset.
+#[cfg(target_arch = "wasm32")]
+#[derive(Debug)]
+pub struct HealthyTursoStorageClosed {
+ closed: ClosedSession,
+}
+
+#[cfg(target_arch = "wasm32")]
+impl HealthyTursoStorageClosed {
+ /// Preserves the healthy main/WAL pair and returns its still-locked owner.
+ pub fn preserve(self) -> Result<OpfsOwner, OpfsError> {
+ self.closed.preserve()
+ }
+
+ /// Physically resets the healthy main/WAL pair.
+ pub async fn reset(self) -> Result<OpfsOwner, TursoStorageResetFailure> {
+ self.closed
+ .reset()
+ .await
+ .map_err(TursoStorageResetFailure::from_reset)
+ }
+}
+
+/// Closed reset-required browser storage that cannot be preserved.
+#[cfg(target_arch = "wasm32")]
+#[derive(Debug)]
+pub struct ResetRequiredTursoStorageClosed {
+ reason: PhysicalResetReason,
+ closed: ClosedSession,
+}
+
+#[cfg(target_arch = "wasm32")]
+impl ResetRequiredTursoStorageClosed {
+ /// Returns the first reset-required reason latched by this storage.
+ pub fn reason(&self) -> PhysicalResetReason {
+ self.reason
+ }
+
+ /// Physically resets the unhealthy main/WAL pair.
+ pub async fn reset(self) -> Result<OpfsOwner, TursoStorageResetFailure> {
+ self.closed
+ .reset()
+ .await
+ .map_err(TursoStorageResetFailure::from_reset)
+ }
+}
+
+/// A browser close failure that exposes no reusable session capability.
+///
+/// The worker-local OPFS owner is either already poisoned or becomes poisoned
+/// when the retained internal session is dropped. Recovery requires worker
+/// replacement followed by the owner's recovery wipe.
+#[cfg(target_arch = "wasm32")]
+#[derive(Debug)]
+pub struct TursoStorageCloseFailure {
+ failure: CloseFailure,
+}
+
+#[cfg(target_arch = "wasm32")]
+impl TursoStorageCloseFailure {
+ fn new(failure: CloseFailure) -> Self {
+ Self { failure }
+ }
+
+ /// Returns the payload-free OPFS error classification.
+ pub fn error(&self) -> &OpfsError {
+ self.failure.error()
+ }
+
+ /// Returns that recovery requires replacing the poisoned worker.
+ pub const fn requires_worker_replacement(&self) -> bool {
+ true
+ }
+}
+
+#[cfg(target_arch = "wasm32")]
+impl std::fmt::Display for TursoStorageCloseFailure {
+ fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ self.failure.fmt(formatter)
+ }
+}
+
+#[cfg(target_arch = "wasm32")]
+impl std::error::Error for TursoStorageCloseFailure {
+ fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+ Some(&self.failure)
+ }
+}
+
+/// A browser reset transition failure that requires worker replacement.
+#[cfg(target_arch = "wasm32")]
+#[derive(Debug)]
+pub struct TursoStorageResetFailure {
+ failure: TursoStorageResetFailureInner,
+}
+
+#[cfg(target_arch = "wasm32")]
+#[derive(Debug)]
+enum TursoStorageResetFailureInner {
+ Close(CloseFailure),
+ Reset(ResetFailure),
+}
+
+#[cfg(target_arch = "wasm32")]
+impl TursoStorageResetFailure {
+ fn from_close(failure: CloseFailure) -> Self {
+ Self {
+ failure: TursoStorageResetFailureInner::Close(failure),
+ }
+ }
+
+ fn from_reset(failure: ResetFailure) -> Self {
+ Self {
+ failure: TursoStorageResetFailureInner::Reset(failure),
+ }
+ }
+
+ /// Returns the payload-free OPFS error classification.
+ pub fn error(&self) -> &OpfsError {
+ match &self.failure {
+ TursoStorageResetFailureInner::Close(failure) => failure.error(),
+ TursoStorageResetFailureInner::Reset(failure) => failure.error(),
+ }
+ }
+
+ /// Returns that recovery requires replacing the poisoned worker.
+ pub const fn requires_worker_replacement(&self) -> bool {
+ true
+ }
+}
+
+#[cfg(target_arch = "wasm32")]
+impl std::fmt::Display for TursoStorageResetFailure {
+ fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ match &self.failure {
+ TursoStorageResetFailureInner::Close(failure) => failure.fmt(formatter),
+ TursoStorageResetFailureInner::Reset(failure) => failure.fmt(formatter),
+ }
+ }
+}
+
+#[cfg(target_arch = "wasm32")]
+impl std::error::Error for TursoStorageResetFailure {
+ fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+ match &self.failure {
+ TursoStorageResetFailureInner::Close(failure) => Some(failure),
+ TursoStorageResetFailureInner::Reset(failure) => Some(failure),
+ }
+ }
+}
+
+/// A WASM initialization failure that permits only physical reset.
+#[cfg(target_arch = "wasm32")]
+pub struct TursoStorageOpenFailure {
+ error: TursoStorageError,
+ session: ConnectedOpfsSession,
+}
+
+#[cfg(target_arch = "wasm32")]
+impl TursoStorageOpenFailure {
+ /// Returns the payload-free storage classification.
+ pub fn error(&self) -> TursoStorageError {
+ self.error
+ }
+
+ /// Consumes a non-reset failure, closes Turso, and preserves main and WAL.
+ ///
+ /// This accessor must only be used when [`Self::error`] does not require a
+ /// physical reset. A close failure poisons the worker-local owner.
+ pub fn preserve(self) -> Result<OpfsOwner, OpfsError> {
+ let closed = self
+ .session
+ .try_close()
+ .map_err(|failure| failure.error().clone())?;
+ closed.preserve()
+ }
+
+ /// Consumes the failure, closes Turso, and physically resets main and WAL.
+ ///
+ /// Neither the connected nor closed session is exposed. Close/reset failure
+ /// requires worker replacement before recovery.
+ pub async fn reset(self) -> Result<OpfsOwner, TursoStorageResetFailure> {
+ let closed = self
+ .session
+ .try_close()
+ .map_err(TursoStorageResetFailure::from_close)?;
+ closed
+ .reset()
+ .await
+ .map_err(TursoStorageResetFailure::from_reset)
+ }
+}
+
+#[cfg(target_arch = "wasm32")]
+impl std::fmt::Debug for TursoStorageOpenFailure {
+ fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ formatter
+ .debug_struct("TursoStorageOpenFailure")
+ .field("error", &self.error)
+ .finish_non_exhaustive()
+ }
+}
+
+#[cfg(target_arch = "wasm32")]
+impl std::fmt::Display for TursoStorageOpenFailure {
+ fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ self.error.fmt(formatter)
+ }
+}
+
+#[cfg(target_arch = "wasm32")]
+impl std::error::Error for TursoStorageOpenFailure {}
+
+/// Reopenable Turso `MemoryIO` database used by native conformance tests.
+#[cfg(not(target_arch = "wasm32"))]
+pub struct TursoMemoryDatabase {
+ path: String,
+ state: Mutex<MemoryDatabaseState>,
+}
+
+#[cfg(not(target_arch = "wasm32"))]
+struct MemoryDatabaseState {
+ io: Arc<MemoryIO>,
+ initialized: bool,
+}
+
+#[cfg(not(target_arch = "wasm32"))]
+impl TursoMemoryDatabase {
+ /// Creates an isolated, initially fresh in-memory physical database.
+ pub fn new(database_path: impl Into<String>) -> Self {
+ Self {
+ path: database_path.into(),
+ state: Mutex::new(MemoryDatabaseState {
+ io: Arc::new(MemoryIO::new()),
+ initialized: false,
+ }),
+ }
+ }
+
+ /// Opens and initializes or validates this in-memory database for `scope`.
+ pub fn open(&self, scope: &str) -> Result<TursoStorage, TursoStorageError> {
+ let (io, fresh) = {
+ let state = self.state.lock().unwrap_or_else(|error| error.into_inner());
+ (state.io.clone(), !state.initialized)
+ };
+ let io_trait: Arc<dyn IO> = io;
+ let database = Database::open(
+ io_trait,
+ &self.path,
+ OpenOptions::new(Arc::new(SqliteDialect)),
+ )
+ .map_err(TursoStorageError::turso)
+ .map_err(|error| if fresh { error } else { error.initialization() })?;
+ let connection = database
+ .connect()
+ .map_err(TursoStorageError::turso)
+ .map_err(|error| if fresh { error } else { error.initialization() })?;
+ if let Err(error) = initialize(&connection, scope, fresh) {
+ if connection.close().is_err() {
+ return Err(TursoStorageError::reset(
+ PhysicalResetReason::TransactionOutcomeUncertain,
+ ));
+ }
+ return Err(error);
+ }
+ if fresh {
+ self.state
+ .lock()
+ .unwrap_or_else(|error| error.into_inner())
+ .initialized = true;
+ }
+ Ok(TursoStorage {
+ health: AtomicU8::new(0),
+ database,
+ connection,
+ #[cfg(all(test, not(target_arch = "wasm32")))]
+ fault: Mutex::new(None),
+ })
+ }
+
+ /// Replaces the complete in-memory main/WAL store with a fresh one.
+ ///
+ /// Callers must first consume and close every storage opened from this
+ /// database. This models the owner-level physical reset used by OPFS.
+ pub fn physical_reset(&self) {
+ let mut state = self.state.lock().unwrap_or_else(|error| error.into_inner());
+ state.io = Arc::new(MemoryIO::new());
+ state.initialized = false;
+ }
+}
+
+/// Health-typed result of consuming a native conformance-test storage.
+#[cfg(not(target_arch = "wasm32"))]
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum TursoStorageCloseOutcome {
+ /// The native test database remained healthy.
+ Healthy,
+ /// The native test database must be physically replaced before reopening.
+ ResetRequired(PhysicalResetReason),
+}
+
+#[cfg(not(target_arch = "wasm32"))]
+impl TursoStorage {
+ /// Opens a one-use isolated Turso `MemoryIO` database.
+ pub fn open_in_memory(scope: &str) -> Result<Self, TursoStorageError> {
+ static NEXT_MEMORY_DATABASE: AtomicU64 = AtomicU64::new(1);
+ let id = NEXT_MEMORY_DATABASE.fetch_add(1, Ordering::Relaxed);
+ TursoMemoryDatabase::new(format!("cache-turso-memory-{id}.db")).open(scope)
+ }
+
+ /// Consumes and explicitly closes the native Turso connection.
+ pub fn try_close(self) -> Result<TursoStorageCloseOutcome, TursoStorageError> {
+ let reason = self.latched_reason();
+ self.connection.close().map_err(|_| {
+ TursoStorageError::reset(PhysicalResetReason::TransactionOutcomeUncertain)
+ })?;
+ drop(self.connection);
+ drop(self.database);
+ Ok(match reason {
+ Some(reason) => TursoStorageCloseOutcome::ResetRequired(reason),
+ None => TursoStorageCloseOutcome::Healthy,
+ })
+ }
+
+ fn connection(&self) -> Arc<Connection> {
+ self.connection.clone()
+ }
+}
+
+impl TursoStorage {
+ fn latched_reason(&self) -> Option<PhysicalResetReason> {
+ let code = self.health.load(Ordering::Acquire);
+ PhysicalResetReason::from_latch_code(code)
+ .or_else(|| (code != 0).then_some(PhysicalResetReason::TransactionOutcomeUncertain))
+ }
+
+ fn require_healthy(&self) -> Result<(), TursoStorageError> {
+ self.latched_reason()
+ .map_or(Ok(()), |reason| Err(TursoStorageError::reset(reason)))
+ }
+
+ fn latch_result<T>(
+ &self,
+ result: Result<T, TursoStorageError>,
+ ) -> Result<T, TursoStorageError> {
+ match result {
+ Err(TursoStorageError::PhysicalResetRequired(reason)) => {
+ let _ = self.health.compare_exchange(
+ 0,
+ reason.latch_code(),
+ Ordering::AcqRel,
+ Ordering::Acquire,
+ );
+ Err(TursoStorageError::reset(reason))
+ }
+ result => result,
+ }
+ }
+}
+
+impl Storage for TursoStorage {
+ type Error = TursoStorageError;
+
+ async fn get_batch(&self, keys: &[EntityKey<'_>]) -> Result<Vec<Option<Record>>, Self::Error> {
+ self.require_healthy()?;
+ let result = (|| {
+ let keys = keys
+ .iter()
+ .map(RecordKey::from_entity)
+ .collect::<Result<Vec<_>, _>>()?;
+ if keys.is_empty() {
+ return Ok(Vec::new());
+ }
+ let connection = self.connection();
+ driver::read_transaction(&connection, || {
+ let mut statement = driver::prepare(&connection, RECORD_GET)?;
+ let mut records = Vec::with_capacity(keys.len());
+ for key in &keys {
+ let rows = driver::query_prepared(
+ &mut statement,
+ vec![text(&key.typename), text(&key.id)],
+ )?;
+ match rows.as_slice() {
+ [] => records.push(None),
+ [row] => {
+ records.push(Some(decode_record(&required_blob(row, 0)?).map_err(
+ |_| TursoStorageError::reset(PhysicalResetReason::Codec),
+ )?))
+ }
+ _ => return Err(invariant()),
+ }
+ }
+ Ok(records)
+ })
+ })();
+ self.latch_result(result)
+ }
+
+ async fn put_batch(
+ &mut self,
+ entries: Vec<(EntityKey<'static>, Record)>,
+ ) -> Result<(), Self::Error> {
+ self.require_healthy()?;
+ let result = (|| {
+ let entries = prepare_records(entries)?;
+ if entries.is_empty() {
+ return Ok(());
+ }
+ let connection = self.connection();
+ driver::write_transaction(&connection, || {
+ let mut statement = driver::prepare(&connection, RECORD_UPSERT)?;
+ for (index, entry) in entries.iter().enumerate() {
+ let changed = driver::execute_prepared(
+ &mut statement,
+ vec![
+ text(&entry.key.typename),
+ text(&entry.key.id),
+ Value::from_blob(entry.value.clone()),
+ ],
+ )?;
+ require_changed(changed, 1)?;
+ self.fault_after(TestFaultSite::Put, index)?;
+ }
+ Ok(())
+ })
+ })();
+ self.latch_result(result)
+ }
+
+ async fn delete_batch(&mut self, keys: &[EntityKey<'static>]) -> Result<(), Self::Error> {
+ self.require_healthy()?;
+ let result = (|| {
+ let keys = keys
+ .iter()
+ .map(RecordKey::from_entity)
+ .collect::<Result<Vec<_>, _>>()?;
+ if keys.is_empty() {
+ return Ok(());
+ }
+ let connection = self.connection();
+ driver::write_transaction(&connection, || {
+ let mut statement = driver::prepare(&connection, RECORD_DELETE)?;
+ for (index, key) in keys.iter().enumerate() {
+ let changed = driver::execute_prepared(
+ &mut statement,
+ vec![text(&key.typename), text(&key.id)],
+ )?;
+ if !(0..=1).contains(&changed) {
+ return Err(invariant());
+ }
+ self.fault_after(TestFaultSite::Delete, index)?;
+ }
+ Ok(())
+ })
+ })();
+ self.latch_result(result)
+ }
+
+ async fn scan_records(
+ &self,
+ type_names: &[String],
+ after: Option<&EntityKey<'static>>,
+ limit: usize,
+ ) -> Result<Vec<(EntityKey<'static>, Record)>, Self::Error> {
+ self.require_healthy()?;
+ let result = (|| {
+ if type_names.is_empty() || limit == 0 {
+ return Ok(Vec::new());
+ }
+ let mut type_names = type_names.to_vec();
+ type_names.sort();
+ type_names.dedup();
+ let after = after
+ .map(|key| RecordKey::from_entity(key).map(|_| key.as_ref().to_owned()))
+ .transpose()?;
+ let limit = i64::try_from(limit).map_err(|_| TursoStorageError::InvalidInput)?;
+
+ let mut sql =
+ String::from("SELECT __typename, id, value FROM records WHERE __typename IN (");
+ for index in 0..type_names.len() {
+ if index != 0 {
+ sql.push_str(", ");
+ }
+ sql.push('?');
+ sql.push_str(&(index + 1).to_string());
+ }
+ sql.push_str(") AND NOT (__typename = 'ROOT_QUERY' AND id = '')");
+ let mut values = type_names
+ .iter()
+ .map(|value| text(value))
+ .collect::<Vec<_>>();
+ if let Some(after) = after {
+ let cursor_index = values.len() + 1;
+ sql.push_str(" AND ((__typename || ':' || id) COLLATE BINARY) > ?");
+ sql.push_str(&cursor_index.to_string());
+ values.push(text(&after));
+ }
+ let limit_index = values.len() + 1;
+ sql.push_str(" ORDER BY (__typename || ':' || id) COLLATE BINARY ASC LIMIT ?");
+ sql.push_str(&limit_index.to_string());
+ values.push(Value::from_i64(limit));
+
+ let connection = self.connection();
+ let rows = driver::query(&connection, &sql, values)?;
+ rows.into_iter()
+ .map(|row| {
+ let key = RecordKey {
+ typename: required_text(&row, 0)?,
+ id: required_text(&row, 1)?,
+ }
+ .into_entity()?;
+ let record = decode_record(&required_blob(&row, 2)?)
+ .map_err(|_| TursoStorageError::reset(PhysicalResetReason::Codec))?;
+ Ok((key, record))
+ })
+ .collect()
+ })();
+ self.latch_result(result)
+ }
+
+ async fn enqueue_mutation(
+ &mut self,
+ entry: NewQueuedMutation,
+ ) -> Result<MutationId, Self::Error> {
+ self.require_healthy()?;
+ let result = (|| {
+ let mutation_values = mutation_values(&entry.mutation)?;
+ let updates = encode_record_updates(&entry.optimistic.normalized_updates);
+ let connection = self.connection();
+ driver::write_transaction(&connection, || {
+ require_changed(
+ driver::execute(&connection, QUEUE_INSERT, mutation_values)?,
+ 1,
+ )?;
+ self.fault_after(TestFaultSite::Enqueue, 0)?;
+ let id = mutation_id_from_row(connection.last_insert_rowid())?;
+ require_changed(
+ driver::execute(
+ &connection,
+ LAYER_INSERT,
+ vec![
+ Value::from_i64(mutation_id_to_sql(id)?),
+ text(&entry.optimistic.optimistic_data_json),
+ Value::from_blob(updates),
+ ],
+ )?,
+ 1,
+ )?;
+ Ok(id)
+ })
+ })();
+ self.latch_result(result)
+ }
+
+ async fn load_mutation_queue(&self) -> Result<Vec<QueuedMutation>, Self::Error> {
+ self.require_healthy()?;
+ let result = {
+ let connection = self.connection();
+ driver::read_transaction(&connection, || {
+ let rows = driver::query(&connection, QUEUE_SELECT, Vec::new())?;
+ let mut queue = Vec::with_capacity(rows.len());
+ for row in rows {
+ let parsed = parse_queue_row(&row)?;
+ let optimistic = parsed.optimistic.ok_or_else(invariant)?;
+ queue.push(QueuedMutation {
+ id: parsed.id,
+ mutation: parsed.mutation,
+ optimistic,
+ });
+ }
+ if !driver::query(&connection, ORPHAN_LAYER_SELECT, Vec::new())?.is_empty() {
+ return Err(invariant());
+ }
+ Ok(queue)
+ })
+ };
+ self.latch_result(result)
+ }
+
+ async fn queue_diagnostics(&self) -> Result<QueueDiagnostics, Self::Error> {
+ self.require_healthy()?;
+ // Diagnostics are deliberately outside a transaction and outside the
+ // health latch. A failed observation must never alter cache recovery.
+ self.fault_after(TestFaultSite::Diagnostics, 0)?;
+ let connection = self.connection();
+ let rows = driver::query(&connection, QUEUE_DIAGNOSTICS_SELECT, Vec::new())?;
+ let [row] = rows.as_slice() else {
+ return Err(invariant());
+ };
+ if row.len() != 2 {
+ return Err(invariant());
+ }
+ let depth = u64::try_from(required_i64(row, 0)?).map_err(|_| invariant())?;
+ let oldest_created_at_ms = nullable_i64(row, 1)?;
+ if (depth == 0) != oldest_created_at_ms.is_none() {
+ return Err(invariant());
+ }
+ Ok(QueueDiagnostics {
+ availability: QueueDiagnosticsAvailability::Available,
+ depth,
+ oldest_created_at_ms,
+ })
+ }
+
+ async fn claim_next_mutation(
+ &mut self,
+ request: MutationClaimRequest,
+ ) -> Result<Option<ClaimedMutation>, Self::Error> {
+ self.require_healthy()?;
+ let result = {
+ let connection = self.connection();
+ driver::write_transaction(&connection, || {
+ let rows = driver::query(&connection, QUEUE_HEAD_SELECT, Vec::new())?;
+ let Some(row) = rows.first() else {
+ if !driver::query(&connection, ANY_LAYER_SELECT, Vec::new())?.is_empty() {
+ return Err(invariant());
+ }
+ return Ok(None);
+ };
+ if rows.len() != 1 {
+ return Err(invariant());
+ }
+ let mut parsed = parse_queue_row(row)?;
+ let optimistic = parsed.optimistic.take().ok_or_else(invariant)?;
+ if parsed
+ .mutation
+ .next_attempt_at_ms
+ .is_some_and(|next| next > request.now_ms)
+ || parsed
+ .mutation
+ .lease_expires_at_ms
+ .is_some_and(|expiry| expiry > request.now_ms)
+ {
+ return Ok(None);
+ }
+
+ parsed.mutation.attempt_count = parsed.mutation.attempt_count.saturating_add(1);
+ parsed.mutation.lease_generation =
+ parsed.mutation.lease_generation.saturating_add(1);
+ let generation =
+ generation_to_sql(parsed.mutation.lease_generation).map_err(|_| invariant())?;
+ parsed.mutation.next_attempt_at_ms = None;
+ parsed.mutation.lease_owner = Some(request.owner.clone());
+ parsed.mutation.lease_expires_at_ms = Some(request.lease_expires_at_ms);
+ require_changed(
+ driver::execute(
+ &connection,
+ "UPDATE mutation_queue SET attempt_count = ?2, next_attempt_at_ms = NULL, lease_owner = ?3, lease_generation = ?4, lease_expires_at_ms = ?5 WHERE id = ?1",
+ vec![
+ Value::from_i64(mutation_id_to_sql(parsed.id)?),
+ Value::from_i64(i64::from(parsed.mutation.attempt_count)),
+ text(&request.owner),
+ Value::from_i64(generation),
+ Value::from_i64(request.lease_expires_at_ms),
+ ],
+ )?,
+ 1,
+ )?;
+ Ok(Some(ClaimedMutation {
+ queued: QueuedMutation {
+ id: parsed.id,
+ mutation: parsed.mutation,
+ optimistic,
+ },
+ lease_generation: u64::try_from(generation).map_err(|_| invariant())?,
+ }))
+ })
+ };
+ self.latch_result(result)
+ }
+
+ async fn defer_mutation(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ next_attempt_at_ms: i64,
+ error: String,
+ ) -> Result<bool, Self::Error> {
+ self.require_healthy()?;
+ let result = (|| {
+ let id = mutation_id_to_sql(id)?;
+ let generation = generation_to_sql(claim.generation)?;
+ let connection = self.connection();
+ driver::write_transaction(&connection, || {
+ let changed = driver::execute(
+ &connection,
+ "UPDATE mutation_queue SET next_attempt_at_ms = ?4, lease_owner = NULL, lease_expires_at_ms = NULL, last_error = ?5 WHERE id = ?1 AND lease_owner = ?2 AND lease_generation = ?3",
+ vec![
+ Value::from_i64(id),
+ text(&claim.owner),
+ Value::from_i64(generation),
+ Value::from_i64(next_attempt_at_ms),
+ text(&error),
+ ],
+ )?;
+ changed_to_bool(changed)
+ })
+ })();
+ self.latch_result(result)
+ }
+
+ async fn complete_mutation(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ entries: Vec<(EntityKey<'static>, Record)>,
+ ) -> Result<bool, Self::Error> {
+ self.require_healthy()?;
+ let result = (|| {
+ let sql_id = mutation_id_to_sql(id)?;
+ generation_to_sql(claim.generation)?;
+ let entries = prepare_records(entries)?;
+ let connection = self.connection();
+ driver::write_transaction(&connection, || {
+ if !claim_is_current(&connection, sql_id, &claim)? {
+ return Ok(false);
+ }
+ require_layer(&connection, sql_id)?;
+ {
+ let mut statement = driver::prepare(&connection, RECORD_UPSERT)?;
+ for (index, entry) in entries.iter().enumerate() {
+ require_changed(
+ driver::execute_prepared(
+ &mut statement,
+ vec![
+ text(&entry.key.typename),
+ text(&entry.key.id),
+ Value::from_blob(entry.value.clone()),
+ ],
+ )?,
+ 1,
+ )?;
+ self.fault_after(TestFaultSite::Complete, index)?;
+ }
+ }
+ require_changed(
+ driver::execute(
+ &connection,
+ "DELETE FROM mutation_queue WHERE id = ?1",
+ vec![Value::from_i64(sql_id)],
+ )?,
+ 1,
+ )?;
+ Ok(true)
+ })
+ })();
+ self.latch_result(result)
+ }
+
+ async fn discard_mutation(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ ) -> Result<bool, Self::Error> {
+ self.require_healthy()?;
+ let result = (|| {
+ let sql_id = mutation_id_to_sql(id)?;
+ generation_to_sql(claim.generation)?;
+ let connection = self.connection();
+ driver::write_transaction(&connection, || {
+ if !claim_is_current(&connection, sql_id, &claim)? {
+ return Ok(false);
+ }
+ require_layer(&connection, sql_id)?;
+ require_changed(
+ driver::execute(
+ &connection,
+ "DELETE FROM mutation_queue WHERE id = ?1",
+ vec![Value::from_i64(sql_id)],
+ )?,
+ 1,
+ )?;
+ self.fault_after(TestFaultSite::Discard, 0)?;
+ Ok(true)
+ })
+ })();
+ self.latch_result(result)
+ }
+
+ async fn clear(&mut self) -> Result<(), Self::Error> {
+ self.require_healthy()?;
+ let result = {
+ let connection = self.connection();
+ driver::write_transaction(&connection, || {
+ driver::execute(&connection, "DELETE FROM optimistic_layers", Vec::new())?;
+ self.fault_after(TestFaultSite::Clear, 0)?;
+ driver::execute(&connection, "DELETE FROM mutation_queue", Vec::new())?;
+ self.fault_after(TestFaultSite::Clear, 1)?;
+ driver::execute(&connection, "DELETE FROM records", Vec::new())?;
+ self.fault_after(TestFaultSite::Clear, 2)?;
+ Ok(())
+ })
+ };
+ self.latch_result(result)
+ }
+}
+
+fn initialize(
+ connection: &Arc<Connection>,
+ scope: &str,
+ fresh: bool,
+) -> Result<(), TursoStorageError> {
+ enable_foreign_keys(connection).map_err(TursoStorageError::initialization)?;
+ if fresh {
+ driver::write_transaction(connection, || {
+ for sql in CREATE_SCHEMA {
+ driver::execute(connection, sql, Vec::new())?;
+ }
+ driver::execute(
+ connection,
+ "INSERT INTO meta (key, value) VALUES ('scope', ?1)",
+ vec![text(scope)],
+ )?;
+ driver::execute(
+ connection,
+ "INSERT INTO meta (key, value) VALUES ('namespace', ?1)",
+ vec![text(&cache_namespace(scope))],
+ )?;
+ driver::execute(
+ connection,
+ "INSERT INTO meta (key, value) VALUES ('storage_schema_version', ?1)",
+ vec![text(&BROWSER_STORAGE_SCHEMA_VERSION.to_string())],
+ )?;
+ Ok(())
+ })
+ .map_err(TursoStorageError::initialization)?;
+ enable_foreign_keys(connection).map_err(TursoStorageError::initialization)?;
+ validate_frozen_schema(connection)?;
+ return Ok(());
+ }
+
+ validate_quick_check(connection)?;
+ validate_frozen_schema(connection)?;
+ let metadata = driver::query(
+ connection,
+ "SELECT key, value FROM meta WHERE key IN ('scope', 'namespace', 'storage_schema_version') ORDER BY key ASC",
+ Vec::new(),
+ )
+ .map_err(TursoStorageError::initialization)?;
+ let expected = [
+ ("namespace", cache_namespace(scope)),
+ ("scope", scope.to_owned()),
+ (
+ "storage_schema_version",
+ BROWSER_STORAGE_SCHEMA_VERSION.to_string(),
+ ),
+ ];
+ if metadata.len() != expected.len() {
+ return Err(TursoStorageError::reset(PhysicalResetReason::Compatibility));
+ }
+ for (row, (expected_key, expected_value)) in metadata.iter().zip(expected) {
+ let key = required_text(row, 0)
+ .map_err(|_| TursoStorageError::reset(PhysicalResetReason::Compatibility))?;
+ let value = required_text(row, 1)
+ .map_err(|_| TursoStorageError::reset(PhysicalResetReason::Compatibility))?;
+ if key != expected_key || value != expected_value {
+ return Err(TursoStorageError::reset(PhysicalResetReason::Compatibility));
+ }
+ }
+ for sql in [
+ RECORD_GET,
+ RECORD_UPSERT,
+ RECORD_DELETE,
+ QUEUE_INSERT,
+ LAYER_INSERT,
+ QUEUE_SELECT,
+ QUEUE_HEAD_SELECT,
+ ORPHAN_LAYER_SELECT,
+ CLAIM_SELECT,
+ REQUIRE_LAYER_SELECT,
+ QUEUE_DIAGNOSTICS_SELECT,
+ ] {
+ driver::validate(connection, sql).map_err(TursoStorageError::initialization)?;
+ }
+ validate_queue_consistency(connection)
+}
+
+fn enable_foreign_keys(connection: &Arc<Connection>) -> Result<(), TursoStorageError> {
+ driver::execute(connection, "PRAGMA foreign_keys = ON", Vec::new())?;
+ let rows = driver::query(connection, "PRAGMA foreign_keys", Vec::new())?;
+ if rows.len() == 1 && required_i64(&rows[0], 0)? == 1 {
+ Ok(())
+ } else {
+ Err(TursoStorageError::reset(PhysicalResetReason::Invariant))
+ }
+}
+
+#[derive(Clone, Copy)]
+struct ColumnSpec {
+ name: &'static str,
+ declared_type: &'static str,
+ not_null: bool,
+ default_zero: bool,
+ primary_key_position: i64,
+}
+
+const META_COLUMNS: &[ColumnSpec] = &[
+ ColumnSpec {
+ name: "key",
+ declared_type: "TEXT",
+ not_null: false,
+ default_zero: false,
+ primary_key_position: 1,
+ },
+ ColumnSpec {
+ name: "value",
+ declared_type: "TEXT",
+ not_null: true,
+ default_zero: false,
+ primary_key_position: 0,
+ },
+];
+
+const RECORD_COLUMNS: &[ColumnSpec] = &[
+ ColumnSpec {
+ name: "__typename",
+ declared_type: "TEXT",
+ not_null: true,
+ default_zero: false,
+ primary_key_position: 1,
+ },
+ ColumnSpec {
+ name: "id",
+ declared_type: "TEXT",
+ not_null: true,
+ default_zero: false,
+ primary_key_position: 2,
+ },
+ ColumnSpec {
+ name: "value",
+ declared_type: "BLOB",
+ not_null: true,
+ default_zero: false,
+ primary_key_position: 0,
+ },
+];
+
+const MUTATION_COLUMNS: &[ColumnSpec] = &[
+ ColumnSpec {
+ name: "id",
+ declared_type: "INTEGER",
+ not_null: false,
+ default_zero: false,
+ primary_key_position: 1,
+ },
+ ColumnSpec {
+ name: "query",
+ declared_type: "TEXT",
+ not_null: true,
+ default_zero: false,
+ primary_key_position: 0,
+ },
+ ColumnSpec {
+ name: "operation_name",
+ declared_type: "TEXT",
+ not_null: false,
+ default_zero: false,
+ primary_key_position: 0,
+ },
+ ColumnSpec {
+ name: "variables_json",
+ declared_type: "TEXT",
+ not_null: true,
+ default_zero: false,
+ primary_key_position: 0,
+ },
+ ColumnSpec {
+ name: "identity",
+ declared_type: "TEXT",
+ not_null: false,
+ default_zero: false,
+ primary_key_position: 0,
+ },
+ ColumnSpec {
+ name: "attempt_count",
+ declared_type: "INTEGER",
+ not_null: true,
+ default_zero: true,
+ primary_key_position: 0,
+ },
+ ColumnSpec {
+ name: "next_attempt_at_ms",
+ declared_type: "INTEGER",
+ not_null: false,
+ default_zero: false,
+ primary_key_position: 0,
+ },
+ ColumnSpec {
+ name: "lease_owner",
+ declared_type: "TEXT",
+ not_null: false,
+ default_zero: false,
+ primary_key_position: 0,
+ },
+ ColumnSpec {
+ name: "lease_generation",
+ declared_type: "INTEGER",
+ not_null: true,
+ default_zero: true,
+ primary_key_position: 0,
+ },
+ ColumnSpec {
+ name: "lease_expires_at_ms",
+ declared_type: "INTEGER",
+ not_null: false,
+ default_zero: false,
+ primary_key_position: 0,
+ },
+ ColumnSpec {
+ name: "last_error",
+ declared_type: "TEXT",
+ not_null: false,
+ default_zero: false,
+ primary_key_position: 0,
+ },
+ ColumnSpec {
+ name: "created_at_ms",
+ declared_type: "INTEGER",
+ not_null: true,
+ default_zero: false,
+ primary_key_position: 0,
+ },
+];
+
+const OPTIMISTIC_COLUMNS: &[ColumnSpec] = &[
+ ColumnSpec {
+ name: "mutation_id",
+ declared_type: "INTEGER",
+ not_null: false,
+ default_zero: false,
+ primary_key_position: 1,
+ },
+ ColumnSpec {
+ name: "optimistic_data_json",
+ declared_type: "TEXT",
+ not_null: true,
+ default_zero: false,
+ primary_key_position: 0,
+ },
+ ColumnSpec {
+ name: "normalized_updates",
+ declared_type: "BLOB",
+ not_null: true,
+ default_zero: false,
+ primary_key_position: 0,
+ },
+];
+
+fn validate_frozen_schema(connection: &Arc<Connection>) -> Result<(), TursoStorageError> {
+ validate_allowed_schema_objects(connection)?;
+ validate_table_columns(connection, "meta", META_COLUMNS)?;
+ validate_table_columns(connection, "records", RECORD_COLUMNS)?;
+ validate_table_columns(connection, "mutation_queue", MUTATION_COLUMNS)?;
+ validate_table_columns(connection, "optimistic_layers", OPTIMISTIC_COLUMNS)?;
+ validate_table_indexes(connection, "meta", &[(0, "key")])?;
+ validate_table_indexes(connection, "records", &[(0, "__typename"), (1, "id")])?;
+ validate_mutation_queue_indexes(connection)?;
+ validate_table_indexes(connection, "optimistic_layers", &[])?;
+ validate_table_constraints(connection, "meta", false)?;
+ validate_table_constraints(connection, "records", false)?;
+ validate_table_constraints(connection, "mutation_queue", true)?;
+ validate_table_constraints(connection, "optimistic_layers", false)?;
+ validate_no_foreign_keys(connection, "meta")?;
+ validate_no_foreign_keys(connection, "records")?;
+ validate_no_foreign_keys(connection, "mutation_queue")?;
+ validate_optimistic_foreign_key(connection)
+}
+
+const SQLITE_SEQUENCE_TABLE: &str = "sqlite_sequence";
+const TURSO_AUTOINCREMENT_TABLE: &str =
+ "__turso_internal_seq___turso_internal_autoincrement_mutation_queue";
+
+fn validate_allowed_schema_objects(connection: &Arc<Connection>) -> Result<(), TursoStorageError> {
+ let rows = driver::query(
+ connection,
+ "SELECT type, name, sql FROM sqlite_schema ORDER BY type ASC, name ASC",
+ Vec::new(),
+ )
+ .map_err(TursoStorageError::initialization)?;
+ let expected = ["meta", "mutation_queue", "optimistic_layers", "records"];
+ let support = [SQLITE_SEQUENCE_TABLE, TURSO_AUTOINCREMENT_TABLE];
+ let mut seen = [false; 4];
+ let mut diagnostics_index_seen = false;
+ let mut support_seen = [false; 2];
+ for row in rows {
+ if row.len() != 3 {
+ return Err(compatibility());
+ }
+ let object_type = required_text(&row, 0).map_err(|_| compatibility())?;
+ let name = required_text(&row, 1).map_err(|_| compatibility())?;
+ if let Some(position) = expected.iter().position(|expected| *expected == name) {
+ if object_type != "table"
+ || !matches!(row.get(2), Some(Value::Text(_)))
+ || seen[position]
+ {
+ return Err(compatibility());
+ }
+ seen[position] = true;
+ continue;
+ }
+ if object_type == "index" && matches!(row.get(2), Some(Value::Null)) {
+ continue;
+ }
+ if name == "mutation_queue_created_at_ms_idx" {
+ if object_type != "index"
+ || required_text(&row, 2).ok().as_deref()
+ != Some(
+ "CREATE INDEX mutation_queue_created_at_ms_idx ON mutation_queue (created_at_ms)",
+ )
+ || diagnostics_index_seen
+ {
+ return Err(compatibility());
+ }
+ diagnostics_index_seen = true;
+ continue;
+ }
+ if let Some(position) = support.iter().position(|expected| *expected == name) {
+ if object_type != "table"
+ || !matches!(row.get(2), Some(Value::Text(_)))
+ || support_seen[position]
+ {
+ return Err(compatibility());
+ }
+ validate_support_table(connection, &name, position)?;
+ support_seen[position] = true;
+ continue;
+ }
+ return Err(compatibility());
+ }
+ if seen.into_iter().all(|present| present)
+ && diagnostics_index_seen
+ && support_seen.into_iter().all(|present| present)
+ {
+ Ok(())
+ } else {
+ Err(compatibility())
+ }
+}
+
+fn validate_support_table(
+ connection: &Arc<Connection>,
+ table: &str,
+ support_position: usize,
+) -> Result<(), TursoStorageError> {
+ let escaped = table.replace('\'', "''");
+ let rows = driver::query(
+ connection,
+ &format!("PRAGMA table_xinfo('{escaped}')"),
+ Vec::new(),
+ )
+ .map_err(TursoStorageError::initialization)?;
+ let sqlite_sequence = [("name", "", 0, 0), ("seq", "", 0, 0)];
+ let turso_autoincrement = [
+ ("value", "INTEGER", 0, 1),
+ ("is_called", "INTEGER", 0, 0),
+ ("start", "INTEGER", 0, 0),
+ ("inc", "INTEGER", 0, 0),
+ ("min", "INTEGER", 0, 0),
+ ("max", "INTEGER", 0, 0),
+ ("cycle", "INTEGER", 0, 0),
+ ];
+ let expected: &[_] = match support_position {
+ 0 => &sqlite_sequence,
+ 1 => &turso_autoincrement,
+ _ => return Err(compatibility()),
+ };
+ if rows.len() != expected.len() {
+ return Err(compatibility());
+ }
+ for (position, (row, (expected_name, expected_type, expected_not_null, expected_pk))) in
+ rows.iter().zip(expected).enumerate()
+ {
+ if row.len() != 7
+ || required_i64(row, 0).ok() != i64::try_from(position).ok()
+ || required_text(row, 1).ok().as_deref() != Some(*expected_name)
+ || required_text(row, 2).ok().as_deref() != Some(*expected_type)
+ || required_i64(row, 3).ok() != Some(*expected_not_null)
+ || !matches!(row.get(4), Some(Value::Null))
+ || required_i64(row, 5).ok() != Some(*expected_pk)
+ || required_i64(row, 6).ok() != Some(0)
+ {
+ return Err(compatibility());
+ }
+ }
+ if !driver::query(
+ connection,
+ &format!("PRAGMA index_list('{escaped}')"),
+ Vec::new(),
+ )
+ .map_err(TursoStorageError::initialization)?
+ .is_empty()
+ || !driver::query(
+ connection,
+ &format!("PRAGMA foreign_key_list('{escaped}')"),
+ Vec::new(),
+ )
+ .map_err(TursoStorageError::initialization)?
+ .is_empty()
+ {
+ return Err(compatibility());
+ }
+ Ok(())
+}
+
+fn validate_table_columns(
+ connection: &Arc<Connection>,
+ table: &str,
+ expected: &[ColumnSpec],
+) -> Result<(), TursoStorageError> {
+ let sql = format!("PRAGMA table_xinfo('{table}')");
+ let rows =
+ driver::query(connection, &sql, Vec::new()).map_err(TursoStorageError::initialization)?;
+ if rows.len() != expected.len() {
+ return Err(compatibility());
+ }
+ for (position, (row, expected)) in rows.iter().zip(expected).enumerate() {
+ if row.len() != 7
+ || required_i64(row, 0).ok() != i64::try_from(position).ok()
+ || required_text(row, 1).ok().as_deref() != Some(expected.name)
+ || required_text(row, 2)
+ .ok()
+ .is_none_or(|value| value.trim().to_ascii_uppercase() != expected.declared_type)
+ || required_i64(row, 3).ok() != Some(i64::from(expected.not_null))
+ || !default_matches(row.get(4), expected.default_zero)
+ || required_i64(row, 5).ok() != Some(expected.primary_key_position)
+ || required_i64(row, 6).ok() != Some(0)
+ {
+ return Err(compatibility());
+ }
+ }
+ Ok(())
+}
+
+fn default_matches(value: Option<&Value>, expected_zero: bool) -> bool {
+ match (value, expected_zero) {
+ (Some(Value::Null), false) => true,
+ (Some(Value::Text(value)), true) => {
+ value.as_str().chars().all(|character| {
+ character == '0'
+ || character == '('
+ || character == ')'
+ || character.is_whitespace()
+ }) && value.as_str().contains('0')
+ }
+ (Some(Value::Numeric(Numeric::Integer(0))), true) => true,
+ _ => false,
+ }
+}
+
+fn validate_mutation_queue_indexes(connection: &Arc<Connection>) -> Result<(), TursoStorageError> {
+ let rows = driver::query(
+ connection,
+ "PRAGMA index_list('mutation_queue')",
+ Vec::new(),
+ )
+ .map_err(TursoStorageError::initialization)?;
+ let [row] = rows.as_slice() else {
+ return Err(compatibility());
+ };
+ if row.len() != 5
+ || required_i64(row, 0).ok() != Some(0)
+ || required_text(row, 1).ok().as_deref() != Some("mutation_queue_created_at_ms_idx")
+ || required_i64(row, 2).ok() != Some(0)
+ || required_text(row, 3).ok().as_deref() != Some("c")
+ || required_i64(row, 4).ok() != Some(0)
+ {
+ return Err(compatibility());
+ }
+ let index_rows = driver::query(
+ connection,
+ "PRAGMA index_xinfo('mutation_queue_created_at_ms_idx')",
+ Vec::new(),
+ )
+ .map_err(TursoStorageError::initialization)?;
+ let [created_at, rowid] = index_rows.as_slice() else {
+ return Err(compatibility());
+ };
+ if created_at.len() != 6
+ || required_i64(created_at, 0).ok() != Some(0)
+ || required_i64(created_at, 1).ok() != Some(11)
+ || required_text(created_at, 2).ok().as_deref() != Some("created_at_ms")
+ || required_i64(created_at, 3).ok() != Some(0)
+ || required_text(created_at, 4).ok().as_deref() != Some("BINARY")
+ || required_i64(created_at, 5).ok() != Some(1)
+ || rowid.len() != 6
+ || required_i64(rowid, 0).ok() != Some(1)
+ || required_i64(rowid, 1).ok() != Some(-1)
+ || !rowid.get(2).is_some_and(|value| {
+ matches!(value, Value::Null)
+ || matches!(value, Value::Text(text) if text.as_str().is_empty())
+ })
+ || required_i64(rowid, 3).ok() != Some(0)
+ || required_text(rowid, 4).ok().as_deref() != Some("BINARY")
+ || required_i64(rowid, 5).ok() != Some(0)
+ {
+ return Err(compatibility());
+ }
+ Ok(())
+}
+
+fn validate_table_indexes(
+ connection: &Arc<Connection>,
+ table: &str,
+ expected_key_columns: &[(i64, &str)],
+) -> Result<(), TursoStorageError> {
+ let rows = driver::query(
+ connection,
+ &format!("PRAGMA index_list('{}')", table.replace('\'', "''")),
+ Vec::new(),
+ )
+ .map_err(TursoStorageError::initialization)?;
+ let expected_index_count = usize::from(!expected_key_columns.is_empty());
+ if rows.len() != expected_index_count {
+ return Err(compatibility());
+ }
+ let Some(row) = rows.first() else {
+ return Ok(());
+ };
+ if row.len() != 5
+ || required_i64(row, 0).ok() != Some(0)
+ || required_i64(row, 2).ok() != Some(1)
+ || required_text(row, 3).ok().as_deref() != Some("pk")
+ || required_i64(row, 4).ok() != Some(0)
+ {
+ return Err(compatibility());
+ }
+ let index_name = required_text(row, 1).map_err(|_| compatibility())?;
+ let index_rows = driver::query(
+ connection,
+ &format!("PRAGMA index_xinfo('{}')", index_name.replace('\'', "''")),
+ Vec::new(),
+ )
+ .map_err(TursoStorageError::initialization)?;
+ if index_rows.len() != expected_key_columns.len() + 1 {
+ return Err(compatibility());
+ }
+ for (sequence, (row, (expected_column_id, expected_name))) in
+ index_rows.iter().zip(expected_key_columns).enumerate()
+ {
+ if row.len() != 6
+ || required_i64(row, 0).ok() != i64::try_from(sequence).ok()
+ || required_i64(row, 1).ok() != Some(*expected_column_id)
+ || required_text(row, 2).ok().as_deref() != Some(*expected_name)
+ || required_i64(row, 3).ok() != Some(0)
+ || required_text(row, 4).ok().as_deref() != Some("BINARY")
+ || required_i64(row, 5).ok() != Some(1)
+ {
+ return Err(compatibility());
+ }
+ }
+ let Some(rowid) = index_rows.last() else {
+ return Err(compatibility());
+ };
+ if rowid.len() != 6
+ || required_i64(rowid, 0).ok() != i64::try_from(expected_key_columns.len()).ok()
+ || required_i64(rowid, 1).ok() != Some(-1)
+ || !rowid.get(2).is_some_and(|value| {
+ matches!(value, Value::Null)
+ || matches!(value, Value::Text(text) if text.as_str().is_empty())
+ })
+ || required_i64(rowid, 3).ok() != Some(0)
+ || required_text(rowid, 4).ok().as_deref() != Some("BINARY")
+ || required_i64(rowid, 5).ok() != Some(0)
+ {
+ return Err(compatibility());
+ }
+ Ok(())
+}
+
+#[derive(Debug, PartialEq, Eq)]
+enum SchemaToken {
+ Word(String),
+ QuotedIdentifier,
+ StringLiteral,
+ Symbol,
+}
+
+impl SchemaToken {
+ fn is_keyword(&self, expected: &str) -> bool {
+ matches!(self, Self::Word(word) if word == expected)
+ }
+}
+
+fn validate_table_constraints(
+ connection: &Arc<Connection>,
+ table: &str,
+ expects_autoincrement: bool,
+) -> Result<(), TursoStorageError> {
+ let rows = driver::query(
+ connection,
+ "SELECT sql FROM sqlite_schema WHERE type = 'table' AND name = ?1",
+ vec![text(table)],
+ )
+ .map_err(TursoStorageError::initialization)?;
+ let [row] = rows.as_slice() else {
+ return Err(compatibility());
+ };
+ if row.len() != 1 {
+ return Err(compatibility());
+ }
+ let sql = required_text(row, 0).map_err(|_| compatibility())?;
+ let tokens = lex_schema(&sql)?;
+ if has_forbidden_table_syntax(&tokens) {
+ return Err(compatibility());
+ }
+ let autoincrement_count = tokens
+ .iter()
+ .filter(|token| token.is_keyword("autoincrement"))
+ .count();
+ if !expects_autoincrement {
+ return (autoincrement_count == 0)
+ .then_some(())
+ .ok_or_else(compatibility);
+ }
+ let declaration_count = tokens
+ .windows(4)
+ .filter(|window| {
+ window[0].is_keyword("integer")
+ && window[1].is_keyword("primary")
+ && window[2].is_keyword("key")
+ && window[3].is_keyword("autoincrement")
+ })
+ .count();
+ if autoincrement_count == 1 && declaration_count == 1 {
+ Ok(())
+ } else {
+ Err(compatibility())
+ }
+}
+
+fn has_forbidden_table_syntax(tokens: &[SchemaToken]) -> bool {
+ ["as", "check", "collate", "generated", "unique"]
+ .into_iter()
+ .any(|keyword| tokens.iter().any(|token| token.is_keyword(keyword)))
+}
+
+fn lex_schema(sql: &str) -> Result<Vec<SchemaToken>, TursoStorageError> {
+ let characters = sql.chars().collect::<Vec<_>>();
+ let mut tokens = Vec::new();
+ let mut index = 0;
+ while index < characters.len() {
+ let character = characters[index];
+ if character.is_whitespace() {
+ index += 1;
+ continue;
+ }
+ if character == '-' && characters.get(index + 1) == Some(&'-') {
+ index += 2;
+ while index < characters.len() && !matches!(characters[index], '\n' | '\r') {
+ index += 1;
+ }
+ continue;
+ }
+ if character == '/' && characters.get(index + 1) == Some(&'*') {
+ index += 2;
+ let mut closed = false;
+ while index + 1 < characters.len() {
+ if characters[index] == '*' && characters[index + 1] == '/' {
+ index += 2;
+ closed = true;
+ break;
+ }
+ index += 1;
+ }
+ if !closed {
+ return Err(compatibility());
+ }
+ continue;
+ }
+ if character == '\'' {
+ index = scan_quoted(&characters, index + 1, '\'')?;
+ tokens.push(SchemaToken::StringLiteral);
+ continue;
+ }
+ if matches!(character, '"' | '`') {
+ index = scan_quoted(&characters, index + 1, character)?;
+ tokens.push(SchemaToken::QuotedIdentifier);
+ continue;
+ }
+ if character == '[' {
+ index += 1;
+ while index < characters.len() && characters[index] != ']' {
+ index += 1;
+ }
+ if index == characters.len() {
+ return Err(compatibility());
+ }
+ index += 1;
+ tokens.push(SchemaToken::QuotedIdentifier);
+ continue;
+ }
+ if character.is_alphabetic() || character == '_' {
+ let start = index;
+ index += 1;
+ while index < characters.len()
+ && (characters[index].is_alphanumeric() || matches!(characters[index], '_' | '$'))
+ {
+ index += 1;
+ }
+ tokens.push(SchemaToken::Word(
+ characters[start..index]
+ .iter()
+ .collect::<String>()
+ .to_lowercase(),
+ ));
+ continue;
+ }
+ tokens.push(SchemaToken::Symbol);
+ index += 1;
+ }
+ Ok(tokens)
+}
+
+fn scan_quoted(
+ characters: &[char],
+ mut index: usize,
+ delimiter: char,
+) -> Result<usize, TursoStorageError> {
+ while index < characters.len() {
+ if characters[index] == delimiter {
+ if characters.get(index + 1) == Some(&delimiter) {
+ index += 2;
+ continue;
+ }
+ return Ok(index + 1);
+ }
+ index += 1;
+ }
+ Err(compatibility())
+}
+
+fn validate_no_foreign_keys(
+ connection: &Arc<Connection>,
+ table: &str,
+) -> Result<(), TursoStorageError> {
+ let escaped = table.replace('\'', "''");
+ if driver::query(
+ connection,
+ &format!("PRAGMA foreign_key_list('{escaped}')"),
+ Vec::new(),
+ )
+ .map_err(TursoStorageError::initialization)?
+ .is_empty()
+ {
+ Ok(())
+ } else {
+ Err(compatibility())
+ }
+}
+
+fn validate_optimistic_foreign_key(connection: &Arc<Connection>) -> Result<(), TursoStorageError> {
+ let rows = driver::query(
+ connection,
+ "PRAGMA foreign_key_list('optimistic_layers')",
+ Vec::new(),
+ )
+ .map_err(TursoStorageError::initialization)?;
+ let [row] = rows.as_slice() else {
+ return Err(compatibility());
+ };
+ if row.len() != 8
+ || required_i64(row, 0).ok() != Some(0)
+ || required_i64(row, 1).ok() != Some(0)
+ || required_text(row, 2).ok().as_deref() != Some("mutation_queue")
+ || required_text(row, 3).ok().as_deref() != Some("mutation_id")
+ || required_text(row, 4).ok().as_deref() != Some("id")
+ || required_text(row, 5).ok().as_deref() != Some("NO ACTION")
+ || required_text(row, 6).ok().as_deref() != Some("CASCADE")
+ || required_text(row, 7).ok().as_deref() != Some("NONE")
+ {
+ return Err(compatibility());
+ }
+ Ok(())
+}
+
+fn compatibility() -> TursoStorageError {
+ TursoStorageError::reset(PhysicalResetReason::Compatibility)
+}
+
+fn validate_quick_check(connection: &Arc<Connection>) -> Result<(), TursoStorageError> {
+ let rows = driver::query(connection, "PRAGMA quick_check", Vec::new())
+ .map_err(TursoStorageError::initialization)?;
+ validate_quick_check_rows(&rows)
+}
+
+fn validate_quick_check_rows(rows: &[Vec<Value>]) -> Result<(), TursoStorageError> {
+ if rows.len() == 1
+ && rows[0].len() == 1
+ && required_text(&rows[0], 0).ok().as_deref() == Some("ok")
+ {
+ Ok(())
+ } else {
+ Err(TursoStorageError::reset(PhysicalResetReason::Integrity))
+ }
+}
+
+fn validate_queue_consistency(connection: &Arc<Connection>) -> Result<(), TursoStorageError> {
+ let queue = driver::query(connection, QUEUE_SELECT, Vec::new())
+ .map_err(TursoStorageError::initialization)?;
+ for row in queue {
+ if parse_queue_row(&row)?.optimistic.is_none() {
+ return Err(invariant());
+ }
+ }
+ if driver::query(connection, ORPHAN_LAYER_SELECT, Vec::new())
+ .map_err(TursoStorageError::initialization)?
+ .is_empty()
+ {
+ Ok(())
+ } else {
+ Err(invariant())
+ }
+}
+
+struct EncodedRecord {
+ key: RecordKey,
+ value: Vec<u8>,
+}
+
+fn prepare_records(
+ entries: Vec<(EntityKey<'static>, Record)>,
+) -> Result<Vec<EncodedRecord>, TursoStorageError> {
+ entries
+ .into_iter()
+ .map(|(key, record)| {
+ Ok(EncodedRecord {
+ key: RecordKey::from_entity(&key)?,
+ value: encode_record(&record),
+ })
+ })
+ .collect()
+}
+
+fn mutation_values(mutation: &StoredMutation) -> Result<Vec<Value>, TursoStorageError> {
+ Ok(vec![
+ text(&mutation.request.query),
+ optional_text(mutation.request.operation_name.as_deref()),
+ text(&mutation.request.variables_json),
+ optional_text(mutation.request.identity.as_deref()),
+ Value::from_i64(i64::from(mutation.attempt_count)),
+ optional_i64(mutation.next_attempt_at_ms),
+ optional_text(mutation.lease_owner.as_deref()),
+ Value::from_i64(generation_to_sql(mutation.lease_generation)?),
+ optional_i64(mutation.lease_expires_at_ms),
+ optional_text(mutation.last_error.as_deref()),
+ Value::from_i64(mutation.created_at_ms),
+ ])
+}
+
+struct ParsedQueueRow {
+ id: MutationId,
+ mutation: StoredMutation,
+ optimistic: Option<PersistedOptimisticLayer>,
+}
+
+fn parse_queue_row(row: &[Value]) -> Result<ParsedQueueRow, TursoStorageError> {
+ if row.len() != 14 {
+ return Err(invariant());
+ }
+ let optimistic = match (&row[12], &row[13]) {
+ (Value::Null, Value::Null) => None,
+ (Value::Null, _) | (_, Value::Null) => return Err(invariant()),
+ _ => Some(PersistedOptimisticLayer {
+ optimistic_data_json: required_text(row, 12)?,
+ normalized_updates: decode_record_updates(&required_blob(row, 13)?)
+ .map_err(|_| TursoStorageError::reset(PhysicalResetReason::Codec))?,
+ }),
+ };
+ Ok(ParsedQueueRow {
+ id: mutation_id_from_row(required_i64(row, 0)?)?,
+ mutation: StoredMutation {
+ request: MutationRequest {
+ query: required_text(row, 1)?,
+ operation_name: nullable_text(row, 2)?,
+ variables_json: required_text(row, 3)?,
+ identity: nullable_text(row, 4)?,
+ },
+ attempt_count: u32::try_from(required_i64(row, 5)?).map_err(|_| invariant())?,
+ next_attempt_at_ms: nullable_i64(row, 6)?,
+ lease_owner: nullable_text(row, 7)?,
+ lease_generation: u64::try_from(required_i64(row, 8)?).map_err(|_| invariant())?,
+ lease_expires_at_ms: nullable_i64(row, 9)?,
+ last_error: nullable_text(row, 10)?,
+ created_at_ms: required_i64(row, 11)?,
+ },
+ optimistic,
+ })
+}
+
+fn claim_is_current(
+ connection: &Arc<Connection>,
+ id: i64,
+ claim: &MutationClaimToken,
+) -> Result<bool, TursoStorageError> {
+ let rows = driver::query(connection, CLAIM_SELECT, vec![Value::from_i64(id)])?;
+ match rows.as_slice() {
+ [] => Ok(false),
+ [row] => Ok(
+ nullable_text(row, 0)?.as_deref() == Some(claim.owner.as_str())
+ && u64::try_from(required_i64(row, 1)?).map_err(|_| invariant())?
+ == claim.generation,
+ ),
+ _ => Err(invariant()),
+ }
+}
+
+fn require_layer(connection: &Arc<Connection>, id: i64) -> Result<(), TursoStorageError> {
+ let rows = driver::query(connection, REQUIRE_LAYER_SELECT, vec![Value::from_i64(id)])?;
+ if rows.len() == 1 && required_i64(&rows[0], 0)? == 1 {
+ Ok(())
+ } else {
+ Err(invariant())
+ }
+}
+
+fn mutation_id_from_row(value: i64) -> Result<MutationId, TursoStorageError> {
+ if value <= 0 {
+ Err(invariant())
+ } else {
+ u64::try_from(value).map_err(|_| invariant())
+ }
+}
+
+fn mutation_id_to_sql(value: MutationId) -> Result<i64, TursoStorageError> {
+ let value = i64::try_from(value).map_err(|_| TursoStorageError::InvalidInput)?;
+ if value > 0 {
+ Ok(value)
+ } else {
+ Err(TursoStorageError::InvalidInput)
+ }
+}
+
+fn generation_to_sql(value: u64) -> Result<i64, TursoStorageError> {
+ i64::try_from(value).map_err(|_| TursoStorageError::InvalidInput)
+}
+
+fn text(value: &str) -> Value {
+ Value::from_text(value.to_owned())
+}
+
+fn optional_text(value: Option<&str>) -> Value {
+ value.map_or(Value::Null, text)
+}
+
+fn optional_i64(value: Option<i64>) -> Value {
+ value.map_or(Value::Null, Value::from_i64)
+}
+
+fn required_value(row: &[Value], index: usize) -> Result<&Value, TursoStorageError> {
+ row.get(index)
+ .ok_or_else(|| TursoStorageError::reset(PhysicalResetReason::Corruption))
+}
+
+fn required_text(row: &[Value], index: usize) -> Result<String, TursoStorageError> {
+ match required_value(row, index)? {
+ Value::Text(value) => Ok(value.as_str().to_owned()),
+ _ => Err(TursoStorageError::reset(PhysicalResetReason::Corruption)),
+ }
+}
+
+fn nullable_text(row: &[Value], index: usize) -> Result<Option<String>, TursoStorageError> {
+ match required_value(row, index)? {
+ Value::Null => Ok(None),
+ Value::Text(value) => Ok(Some(value.as_str().to_owned())),
+ _ => Err(TursoStorageError::reset(PhysicalResetReason::Corruption)),
+ }
+}
+
+fn required_blob(row: &[Value], index: usize) -> Result<Vec<u8>, TursoStorageError> {
+ match required_value(row, index)? {
+ Value::Blob(value) => Ok(value.to_vec()),
+ _ => Err(TursoStorageError::reset(PhysicalResetReason::Corruption)),
+ }
+}
+
+fn required_i64(row: &[Value], index: usize) -> Result<i64, TursoStorageError> {
+ match required_value(row, index)? {
+ Value::Numeric(Numeric::Integer(value)) => Ok(*value),
+ _ => Err(TursoStorageError::reset(PhysicalResetReason::Corruption)),
+ }
+}
+
+fn nullable_i64(row: &[Value], index: usize) -> Result<Option<i64>, TursoStorageError> {
+ match required_value(row, index)? {
+ Value::Null => Ok(None),
+ Value::Numeric(Numeric::Integer(value)) => Ok(Some(*value)),
+ _ => Err(TursoStorageError::reset(PhysicalResetReason::Corruption)),
+ }
+}
+
+fn require_changed(changed: i64, expected: i64) -> Result<(), TursoStorageError> {
+ if changed == expected {
+ Ok(())
+ } else {
+ Err(invariant())
+ }
+}
+
+fn changed_to_bool(changed: i64) -> Result<bool, TursoStorageError> {
+ match changed {
+ 0 => Ok(false),
+ 1 => Ok(true),
+ _ => Err(invariant()),
+ }
+}
+
+fn invariant() -> TursoStorageError {
+ TursoStorageError::reset(PhysicalResetReason::Invariant)
+}
+
+#[derive(Clone, Copy)]
+enum TestFaultSite {
+ Diagnostics,
+ Put,
+ Delete,
+ Enqueue,
+ Complete,
+ Discard,
+ Clear,
+}
+
+impl TursoStorage {
+ fn fault_after(&self, site: TestFaultSite, index: usize) -> Result<(), TursoStorageError> {
+ #[cfg(all(test, not(target_arch = "wasm32")))]
+ {
+ let mut fault = self.fault.lock().unwrap_or_else(|error| error.into_inner());
+ if let Some((fault_state, fault_code)) = fault
+ .as_ref()
+ .and_then(|fault| fault.rollback_io_step_at(site, index))
+ {
+ fault_state.store(fault_code, Ordering::SeqCst);
+ *fault = None;
+ // This pinned Turso rollback emits no File completion after
+ // this operation failure. Force its IO::step polling boundary
+ // instead; no successful or unrelated completion is repurposed.
+ driver::arm_rollback_control_io();
+ return Err(TursoStorageError::Database);
+ }
+ if let Some(error) = fault.as_ref().and_then(|fault| fault.error_at(site, index)) {
+ *fault = None;
+ return Err(error);
+ }
+ }
+ #[cfg(any(not(test), target_arch = "wasm32"))]
+ let _ = (site, index);
+ Ok(())
+ }
+}
+
+#[cfg(all(test, not(target_arch = "wasm32")))]
+#[derive(Clone)]
+enum TestFault {
+ After {
+ site: TestFaultSite,
+ index: usize,
+ },
+ ResetAfter {
+ site: TestFaultSite,
+ index: usize,
+ reason: PhysicalResetReason,
+ },
+ RollbackIoStepAfter {
+ site: TestFaultSite,
+ index: usize,
+ fault_state: Arc<AtomicU8>,
+ fault_code: u8,
+ },
+}
+
+#[cfg(all(test, not(target_arch = "wasm32")))]
+impl TestFault {
+ fn error_at(&self, site: TestFaultSite, index: usize) -> Option<TursoStorageError> {
+ let (expected_site, expected_index, error) = match self {
+ Self::After { site, index } => (site, index, TursoStorageError::Database),
+ Self::ResetAfter {
+ site,
+ index,
+ reason,
+ } => (site, index, TursoStorageError::reset(*reason)),
+ Self::RollbackIoStepAfter { .. } => return None,
+ };
+ (std::mem::discriminant(expected_site) == std::mem::discriminant(&site)
+ && *expected_index == index)
+ .then_some(error)
+ }
+
+ fn rollback_io_step_at(
+ &self,
+ site: TestFaultSite,
+ index: usize,
+ ) -> Option<(Arc<AtomicU8>, u8)> {
+ let Self::RollbackIoStepAfter {
+ site: expected_site,
+ index: expected_index,
+ fault_state,
+ fault_code,
+ } = self
+ else {
+ return None;
+ };
+ (std::mem::discriminant(expected_site) == std::mem::discriminant(&site)
+ && *expected_index == index)
+ .then(|| (fault_state.clone(), *fault_code))
+ }
+}
+
+#[cfg(all(test, not(target_arch = "wasm32")))]
+impl TursoStorage {
+ fn arm_fault(&self, fault: TestFault) {
+ *self.fault.lock().unwrap_or_else(|error| error.into_inner()) = Some(fault);
+ }
+}
+
+#[cfg(all(test, target_arch = "wasm32"))]
+mod browser_test;
+#[cfg(all(test, not(target_arch = "wasm32")))]
+mod test;
diff --git a/crates/client/cache-turso/src/storage/browser_test.rs b/crates/client/cache-turso/src/storage/browser_test.rs
new file mode 100644
index 0000000000..cf236c3486
--- /dev/null
+++ b/crates/client/cache-turso/src/storage/browser_test.rs
@@ -0,0 +1,67 @@
+use super::*;
+use cache_core::store::Storage;
+use cache_core::value::EntityKey;
+use turso_opfs::{OpenResult, OpfsOwner};
+use wasm_bindgen_test::*;
+
+wasm_bindgen_test_configure!(run_in_dedicated_worker);
+
+fn key(value: &str) -> EntityKey<'static> {
+ EntityKey(value.to_owned().into())
+}
+
+#[wasm_bindgen_test(async)]
+async fn runtime_corruption_closes_reset_only_and_replacement_is_empty() {
+ let owner = OpfsOwner::acquire("cache-turso-wp06-runtime-reset.db")
+ .await
+ .unwrap()
+ .recovery_wipe()
+ .await
+ .unwrap();
+ let OpenResult::Ready(session) = owner.open().await.unwrap() else {
+ panic!("recovery wipe must produce a complete fresh pair")
+ };
+ let storage =
+ TursoStorage::from_opfs_session(session.connect().unwrap(), "runtime-reset").unwrap();
+ driver::execute(
+ &storage.connection(),
+ RECORD_UPSERT,
+ vec![text("Thing"), text("1"), Value::from_blob(vec![0xff])],
+ )
+ .unwrap();
+ assert_eq!(
+ storage
+ .get_batch(&[key("Thing:1")])
+ .await
+ .unwrap_err()
+ .physical_reset_reason(),
+ Some(PhysicalResetReason::Codec)
+ );
+ assert_eq!(
+ storage
+ .load_mutation_queue()
+ .await
+ .unwrap_err()
+ .physical_reset_reason(),
+ Some(PhysicalResetReason::Codec)
+ );
+
+ let TursoStorageCloseOutcome::ResetRequired(closed) = storage.try_close().unwrap() else {
+ panic!("runtime corruption must make preservation unavailable")
+ };
+ assert_eq!(closed.reason(), PhysicalResetReason::Codec);
+ let owner = closed.reset().await.unwrap();
+ let OpenResult::Ready(session) = owner.open().await.unwrap() else {
+ panic!("physical reset must recreate a complete pair")
+ };
+ let replacement =
+ TursoStorage::from_opfs_session(session.connect().unwrap(), "runtime-reset").unwrap();
+ assert_eq!(
+ replacement.get_batch(&[key("Thing:1")]).await.unwrap(),
+ vec![None]
+ );
+ let TursoStorageCloseOutcome::Healthy(closed) = replacement.try_close().unwrap() else {
+ panic!("fresh replacement must be healthy")
+ };
+ closed.preserve().unwrap().release().await.unwrap();
+}
diff --git a/crates/client/cache-turso/src/storage/test.rs b/crates/client/cache-turso/src/storage/test.rs
new file mode 100644
index 0000000000..bfa2449309
--- /dev/null
+++ b/crates/client/cache-turso/src/storage/test.rs
@@ -0,0 +1,1409 @@
+use super::*;
+use cache_core::normalize::RecordUpdates;
+use pollster::block_on;
+use std::sync::atomic::{AtomicU8, Ordering};
+use turso_core::io::{FileId, FileSyncType};
+use turso_core::{
+ Buffer, Clock, Completion, CompletionError, File, IO, LimboError, MemoryIO, MonotonicInstant,
+ OpenFlags, WallClockInstant,
+};
+
+fn key(value: &str) -> EntityKey<'static> {
+ EntityKey(value.to_owned().into())
+}
+
+fn record(value: &str) -> Record {
+ let mut record = Record::default();
+ record.fields.insert(
+ "value".into(),
+ cache_core::value::CacheValue::String(value.into()),
+ );
+ record
+}
+
+fn queued(label: &str) -> NewQueuedMutation {
+ NewQueuedMutation {
+ mutation: StoredMutation::new(
+ MutationRequest {
+ query: format!("mutation {label} {{ update {{ id }} }}"),
+ operation_name: Some(label.into()),
+ variables_json: "{}".into(),
+ identity: Some("identity".into()),
+ },
+ 1,
+ ),
+ optimistic: PersistedOptimisticLayer {
+ optimistic_data_json: "{}".into(),
+ normalized_updates: RecordUpdates::default(),
+ },
+ }
+}
+
+fn token(owner: &str, generation: u64) -> MutationClaimToken {
+ MutationClaimToken {
+ owner: owner.into(),
+ generation,
+ }
+}
+
+fn raw_execute(storage: &TursoStorage, sql: &str, values: Vec<Value>) -> i64 {
+ driver::execute(&storage.connection(), sql, values).unwrap()
+}
+
+fn raw_scalar(storage: &TursoStorage, sql: &str) -> i64 {
+ let rows = driver::query(&storage.connection(), sql, Vec::new()).unwrap();
+ required_i64(&rows[0], 0).unwrap()
+}
+
+fn expect_reset_reason<T>(result: Result<T, TursoStorageError>, expected: PhysicalResetReason) {
+ let Err(error) = result else {
+ panic!("reset-required operation unexpectedly succeeded")
+ };
+ assert_eq!(error.physical_reset_reason(), Some(expected));
+}
+
+async fn expect_every_storage_method_latched(
+ storage: &mut TursoStorage,
+ expected: PhysicalResetReason,
+) {
+ expect_reset_reason(storage.get_batch(&[key("Thing:1")]).await, expected);
+ expect_reset_reason(
+ storage
+ .put_batch(vec![(key("Thing:2"), record("blocked"))])
+ .await,
+ expected,
+ );
+ expect_reset_reason(storage.delete_batch(&[key("Thing:1")]).await, expected);
+ expect_reset_reason(
+ storage.scan_records(&["Thing".into()], None, 1).await,
+ expected,
+ );
+ expect_reset_reason(storage.enqueue_mutation(queued("Blocked")).await, expected);
+ expect_reset_reason(storage.load_mutation_queue().await, expected);
+ expect_reset_reason(storage.queue_diagnostics().await, expected);
+ expect_reset_reason(
+ storage
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "blocked".into(),
+ now_ms: 1,
+ lease_expires_at_ms: 2,
+ })
+ .await,
+ expected,
+ );
+ expect_reset_reason(
+ storage
+ .defer_mutation(1, token("blocked", 1), 2, "blocked".into())
+ .await,
+ expected,
+ );
+ expect_reset_reason(
+ storage
+ .complete_mutation(1, token("blocked", 1), Vec::new())
+ .await,
+ expected,
+ );
+ expect_reset_reason(
+ storage.discard_mutation(1, token("blocked", 1)).await,
+ expected,
+ );
+ expect_reset_reason(storage.clear().await, expected);
+}
+
+#[test]
+fn queue_diagnostics_use_one_payload_free_aggregate_query() {
+ block_on(async {
+ let mut storage = TursoStorage::open_in_memory("queue-diagnostics").unwrap();
+ assert_eq!(
+ storage.queue_diagnostics().await.unwrap(),
+ QueueDiagnostics {
+ availability: QueueDiagnosticsAvailability::Available,
+ depth: 0,
+ oldest_created_at_ms: None,
+ }
+ );
+ let first = storage.enqueue_mutation(queued("First")).await.unwrap();
+ let second = storage.enqueue_mutation(queued("Second")).await.unwrap();
+ raw_execute(
+ &storage,
+ "UPDATE mutation_queue SET created_at_ms = ?2 WHERE id = ?1",
+ vec![
+ Value::from_i64(mutation_id_to_sql(first).unwrap()),
+ Value::from_i64(10),
+ ],
+ );
+ raw_execute(
+ &storage,
+ "UPDATE mutation_queue SET created_at_ms = ?2 WHERE id = ?1",
+ vec![
+ Value::from_i64(mutation_id_to_sql(second).unwrap()),
+ Value::from_i64(20),
+ ],
+ );
+ assert_eq!(
+ storage.queue_diagnostics().await.unwrap(),
+ QueueDiagnostics {
+ availability: QueueDiagnosticsAvailability::Available,
+ depth: 2,
+ oldest_created_at_ms: Some(10),
+ }
+ );
+ });
+}
+
+#[test]
+fn queue_diagnostics_use_the_created_at_covering_index_at_scale() {
+ block_on(async {
+ let storage = TursoStorage::open_in_memory("queue-diagnostics-plan").unwrap();
+ raw_execute(
+ &storage,
+ "WITH RECURSIVE values_to_insert(value) AS (VALUES(1) UNION ALL SELECT value + 1 FROM values_to_insert WHERE value < 10000) INSERT INTO mutation_queue (query, variables_json, created_at_ms) SELECT 'mutation Scale { scale }', '{}', 10001 - value FROM values_to_insert",
+ Vec::new(),
+ );
+ let plan = driver::query(
+ &storage.connection(),
+ &format!("EXPLAIN QUERY PLAN {QUEUE_DIAGNOSTICS_SELECT}"),
+ Vec::new(),
+ )
+ .unwrap();
+ let details = plan
+ .iter()
+ .filter_map(|row| required_text(row, 3).ok())
+ .collect::<Vec<_>>()
+ .join(" ");
+ assert!(
+ details.contains("mutation_queue_created_at_ms_idx"),
+ "diagnostics query did not use the covering timestamp index: {details}"
+ );
+ assert_eq!(
+ storage.queue_diagnostics().await.unwrap(),
+ QueueDiagnostics {
+ availability: QueueDiagnosticsAvailability::Available,
+ depth: 10_000,
+ oldest_created_at_ms: Some(1),
+ }
+ );
+ });
+}
+
+#[test]
+fn queue_diagnostics_failure_never_latches_storage_health() {
+ block_on(async {
+ let mut storage = TursoStorage::open_in_memory("queue-diagnostics-health").unwrap();
+ storage.arm_fault(TestFault::ResetAfter {
+ site: TestFaultSite::Diagnostics,
+ index: 0,
+ reason: PhysicalResetReason::Io,
+ });
+ assert_eq!(
+ storage
+ .queue_diagnostics()
+ .await
+ .unwrap_err()
+ .physical_reset_reason(),
+ Some(PhysicalResetReason::Io)
+ );
+ storage
+ .enqueue_mutation(queued("StillHealthy"))
+ .await
+ .unwrap();
+ assert_eq!(storage.queue_diagnostics().await.unwrap().depth, 1);
+ assert_eq!(
+ storage.try_close().unwrap(),
+ TursoStorageCloseOutcome::Healthy
+ );
+ });
+}
+
+#[test]
+fn fresh_schema_metadata_foreign_keys_quick_check_and_cascade_are_real() {
+ block_on(async {
+ let mut storage = TursoStorage::open_in_memory("schema-scope").unwrap();
+ assert_eq!(raw_scalar(&storage, "PRAGMA foreign_keys"), 1);
+ let quick = driver::query(&storage.connection(), "PRAGMA quick_check", Vec::new()).unwrap();
+ assert_eq!(quick.len(), 1);
+ assert_eq!(required_text(&quick[0], 0).unwrap(), "ok");
+ assert_eq!(raw_scalar(&storage, "SELECT COUNT(*) FROM meta"), 3);
+
+ let violation = driver::execute(
+ &storage.connection(),
+ LAYER_INSERT,
+ vec![Value::from_i64(999), text("{}"), Value::from_blob(vec![0])],
+ )
+ .unwrap_err();
+ assert!(!violation.requires_physical_reset());
+ assert_eq!(raw_scalar(&storage, "PRAGMA foreign_keys"), 1);
+
+ let id = storage.enqueue_mutation(queued("Cascade")).await.unwrap();
+ let claimed = storage
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner".into(),
+ now_ms: 1,
+ lease_expires_at_ms: 10,
+ })
+ .await
+ .unwrap()
+ .unwrap();
+ assert!(
+ storage
+ .discard_mutation(id, token("runner", claimed.lease_generation))
+ .await
+ .unwrap()
+ );
+ assert_eq!(
+ raw_scalar(&storage, "SELECT COUNT(*) FROM optimistic_layers"),
+ 0
+ );
+ });
+}
+
+#[test]
+fn quick_check_requires_exactly_one_ok_text_row() {
+ assert!(validate_quick_check_rows(&[vec![text("ok")]]).is_ok());
+ for rows in [
+ Vec::new(),
+ vec![vec![text("corrupt")]],
+ vec![vec![text("ok")], vec![text("ok")]],
+ vec![vec![text("ok"), text("extra")]],
+ vec![vec![Value::from_i64(1)]],
+ ] {
+ assert_eq!(
+ validate_quick_check_rows(&rows)
+ .unwrap_err()
+ .physical_reset_reason(),
+ Some(PhysicalResetReason::Integrity)
+ );
+ }
+}
+
+#[test]
+fn every_metadata_mismatch_and_missing_schema_requests_physical_reset() {
+ block_on(async {
+ for (name, sql) in [
+ (
+ "namespace",
+ "UPDATE meta SET value = 'wrong' WHERE key = 'namespace'",
+ ),
+ (
+ "scope",
+ "UPDATE meta SET value = 'wrong' WHERE key = 'scope'",
+ ),
+ (
+ "version",
+ "UPDATE meta SET value = '999' WHERE key = 'storage_schema_version'",
+ ),
+ ("missing", "DELETE FROM meta WHERE key = 'namespace'"),
+ ("schema", "DROP TABLE records"),
+ (
+ "queue-diagnostics-index",
+ "DROP INDEX mutation_queue_created_at_ms_idx",
+ ),
+ ] {
+ let database = TursoMemoryDatabase::new(format!("mismatch-{name}.db"));
+ let storage = database.open("scope").unwrap();
+ raw_execute(&storage, sql, Vec::new());
+ storage.try_close().unwrap();
+ let error = database.open("scope").unwrap_err();
+ assert!(error.requires_physical_reset(), "case {name}: {error}");
+ assert_eq!(
+ error.physical_reset_reason(),
+ Some(PhysicalResetReason::Compatibility)
+ );
+ }
+
+ let database = TursoMemoryDatabase::new("scope-mismatch-reset.db");
+ let mut storage = database.open("scope-a").unwrap();
+ storage
+ .put_batch(vec![(key("Thing:1"), record("value"))])
+ .await
+ .unwrap();
+ storage.enqueue_mutation(queued("Queued")).await.unwrap();
+ storage.try_close().unwrap();
+ assert!(
+ database
+ .open("scope-b")
+ .unwrap_err()
+ .requires_physical_reset()
+ );
+ database.physical_reset();
+ let storage = database.open("scope-b").unwrap();
+ assert_eq!(
+ storage.get_batch(&[key("Thing:1")]).await.unwrap(),
+ vec![None]
+ );
+ assert!(storage.load_mutation_queue().await.unwrap().is_empty());
+ });
+}
+
+#[test]
+fn semantically_equivalent_schema_formatting_is_accepted_on_reopen() {
+ let database = TursoMemoryDatabase::new("semantic-schema-formatting.db");
+ let storage = database.open("scope").unwrap();
+ for sql in [
+ "DROP TABLE optimistic_layers",
+ "DROP TABLE mutation_queue",
+ "DROP TABLE records",
+ r#"create table [records] (
+ [__typename] text not null,
+ `id` text not null,
+ 'value' blob not null,
+ -- UNIQUE(value), CHECK(id), and COLLATE NOCASE are only comment text.
+ primary key ([__typename], `id`)
+ )"#,
+ r#"create table 'mutation_queue' (
+ 'id' integer /* AUTOINCREMENT UNIQUE CHECK COLLATE */ primary key autoincrement,
+ "query" text not null,
+ [operation_name] text,
+ `variables_json` text not null,
+ "identity" text,
+ "attempt_count" integer default ( ( 0 ) ) not null,
+ "next_attempt_at_ms" integer,
+ "lease_owner" text,
+ "lease_generation" integer default ((0)) not null,
+ "lease_expires_at_ms" integer,
+ "last_error" text,
+ "created_at_ms" integer not null
+ )"#,
+ "CREATE INDEX mutation_queue_created_at_ms_idx ON mutation_queue(created_at_ms)",
+ r#"create table `optimistic_layers` (
+ `mutation_id` integer primary key,
+ [optimistic_data_json] text not null,
+ 'normalized_updates' blob not null,
+ /* A string-like quoted identifier containing 'UNIQUE CHECK COLLATE'. */
+ foreign key (`mutation_id`) references 'mutation_queue' ('id') on delete cascade
+ )"#,
+ ] {
+ raw_execute(&storage, sql, Vec::new());
+ }
+ assert_eq!(
+ storage.try_close().unwrap(),
+ TursoStorageCloseOutcome::Healthy
+ );
+ let mut reopened = database.open("scope").unwrap();
+ block_on(async {
+ let first = reopened.enqueue_mutation(queued("First")).await.unwrap();
+ let claimed = reopened
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner".into(),
+ now_ms: 1,
+ lease_expires_at_ms: 2,
+ })
+ .await
+ .unwrap()
+ .unwrap();
+ assert!(
+ reopened
+ .discard_mutation(first, token("runner", claimed.lease_generation))
+ .await
+ .unwrap()
+ );
+ assert!(reopened.enqueue_mutation(queued("Second")).await.unwrap() > first);
+ });
+ assert_eq!(
+ reopened.try_close().unwrap(),
+ TursoStorageCloseOutcome::Healthy
+ );
+}
+
+#[test]
+fn generated_column_forms_are_rejected_by_the_schema_lexer() {
+ for sql in [
+ "CREATE TABLE records (value TEXT GENERATED ALWAYS AS (id))",
+ "CREATE TABLE records (value TEXT AS (id))",
+ ] {
+ let tokens = lex_schema(sql).unwrap();
+ assert!(has_forbidden_table_syntax(&tokens), "SQL: {sql}");
+ }
+}
+
+#[test]
+fn every_malformed_frozen_schema_constraint_requests_reset_on_reopen() {
+ let cases = vec![
+ (
+ "meta-primary-key",
+ vec![
+ "DROP TABLE meta",
+ "CREATE TABLE meta (key TEXT, value TEXT NOT NULL)",
+ ],
+ ),
+ (
+ "meta-extra-foreign-key",
+ vec![
+ "DROP TABLE meta",
+ "CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT NOT NULL, FOREIGN KEY (value) REFERENCES records(id))",
+ ],
+ ),
+ (
+ "records-column-type",
+ vec![
+ "DROP TABLE records",
+ "CREATE TABLE records (__typename TEXT NOT NULL, id INTEGER NOT NULL, value BLOB NOT NULL, PRIMARY KEY (__typename, id))",
+ ],
+ ),
+ (
+ "records-primary-key",
+ vec![
+ "DROP TABLE records",
+ "CREATE TABLE records (__typename TEXT NOT NULL, id TEXT NOT NULL, value BLOB NOT NULL)",
+ ],
+ ),
+ (
+ "records-primary-key-order",
+ vec![
+ "DROP TABLE records",
+ "CREATE TABLE records (__typename TEXT NOT NULL, id TEXT NOT NULL, value BLOB NOT NULL, PRIMARY KEY (id, __typename))",
+ ],
+ ),
+ (
+ "records-not-null",
+ vec![
+ "DROP TABLE records",
+ "CREATE TABLE records (__typename TEXT NOT NULL, id TEXT NOT NULL, value BLOB, PRIMARY KEY (__typename, id))",
+ ],
+ ),
+ (
+ "records-extra-column",
+ vec![
+ "DROP TABLE records",
+ "CREATE TABLE records (__typename TEXT NOT NULL, id TEXT NOT NULL, value BLOB NOT NULL, extra TEXT, PRIMARY KEY (__typename, id))",
+ ],
+ ),
+ (
+ "records-extra-foreign-key",
+ vec![
+ "DROP TABLE records",
+ "CREATE TABLE records (__typename TEXT NOT NULL, id TEXT NOT NULL, value BLOB NOT NULL, PRIMARY KEY (__typename, id), FOREIGN KEY (value) REFERENCES meta(key))",
+ ],
+ ),
+ (
+ "records-unique-constraint",
+ vec![
+ "DROP TABLE records",
+ "CREATE TABLE records (__typename TEXT NOT NULL, id TEXT NOT NULL, value BLOB NOT NULL, PRIMARY KEY (__typename, id), UNIQUE (value))",
+ ],
+ ),
+ (
+ "records-check-constraint",
+ vec![
+ "DROP TABLE records",
+ "CREATE TABLE records (__typename TEXT NOT NULL, id TEXT NOT NULL CHECK (id <> ''), value BLOB NOT NULL, PRIMARY KEY (__typename, id))",
+ ],
+ ),
+ (
+ "records-collation",
+ vec![
+ "DROP TABLE records",
+ "CREATE TABLE records (__typename TEXT NOT NULL, id TEXT COLLATE NOCASE NOT NULL, value BLOB NOT NULL, PRIMARY KEY (__typename, id))",
+ ],
+ ),
+ (
+ "queue-autoincrement",
+ vec![
+ "DROP TABLE optimistic_layers",
+ "DROP TABLE mutation_queue",
+ "CREATE TABLE mutation_queue (id INTEGER PRIMARY KEY, query TEXT NOT NULL, operation_name TEXT, variables_json TEXT NOT NULL, identity TEXT, attempt_count INTEGER NOT NULL DEFAULT 0, next_attempt_at_ms INTEGER, lease_owner TEXT, lease_generation INTEGER NOT NULL DEFAULT 0, lease_expires_at_ms INTEGER, last_error TEXT, created_at_ms INTEGER NOT NULL)",
+ CREATE_SCHEMA[3],
+ ],
+ ),
+ (
+ "queue-extra-foreign-key",
+ vec![
+ "DROP TABLE optimistic_layers",
+ "DROP TABLE mutation_queue",
+ "CREATE TABLE mutation_queue (id INTEGER PRIMARY KEY AUTOINCREMENT, query TEXT NOT NULL, operation_name TEXT, variables_json TEXT NOT NULL, identity TEXT, attempt_count INTEGER NOT NULL DEFAULT 0, next_attempt_at_ms INTEGER, lease_owner TEXT, lease_generation INTEGER NOT NULL DEFAULT 0, lease_expires_at_ms INTEGER, last_error TEXT, created_at_ms INTEGER NOT NULL, FOREIGN KEY (identity) REFERENCES meta(key))",
+ CREATE_SCHEMA[3],
+ ],
+ ),
+ (
+ "queue-not-null",
+ vec![
+ "DROP TABLE optimistic_layers",
+ "DROP TABLE mutation_queue",
+ "CREATE TABLE mutation_queue (id INTEGER PRIMARY KEY AUTOINCREMENT, query TEXT, operation_name TEXT, variables_json TEXT NOT NULL, identity TEXT, attempt_count INTEGER NOT NULL DEFAULT 0, next_attempt_at_ms INTEGER, lease_owner TEXT, lease_generation INTEGER NOT NULL DEFAULT 0, lease_expires_at_ms INTEGER, last_error TEXT, created_at_ms INTEGER NOT NULL)",
+ CREATE_SCHEMA[3],
+ ],
+ ),
+ (
+ "queue-default",
+ vec![
+ "DROP TABLE optimistic_layers",
+ "DROP TABLE mutation_queue",
+ "CREATE TABLE mutation_queue (id INTEGER PRIMARY KEY AUTOINCREMENT, query TEXT NOT NULL, operation_name TEXT, variables_json TEXT NOT NULL, identity TEXT, attempt_count INTEGER NOT NULL DEFAULT 1, next_attempt_at_ms INTEGER, lease_owner TEXT, lease_generation INTEGER NOT NULL DEFAULT 0, lease_expires_at_ms INTEGER, last_error TEXT, created_at_ms INTEGER NOT NULL)",
+ CREATE_SCHEMA[3],
+ ],
+ ),
+ (
+ "optimistic-primary-key",
+ vec![
+ "DROP TABLE optimistic_layers",
+ "CREATE TABLE optimistic_layers (mutation_id INTEGER, optimistic_data_json TEXT NOT NULL, normalized_updates BLOB NOT NULL, FOREIGN KEY (mutation_id) REFERENCES mutation_queue(id) ON DELETE CASCADE)",
+ ],
+ ),
+ (
+ "optimistic-foreign-key",
+ vec![
+ "DROP TABLE optimistic_layers",
+ "CREATE TABLE optimistic_layers (mutation_id INTEGER PRIMARY KEY, optimistic_data_json TEXT NOT NULL, normalized_updates BLOB NOT NULL)",
+ ],
+ ),
+ (
+ "optimistic-foreign-key-parent",
+ vec![
+ "DROP TABLE optimistic_layers",
+ "CREATE TABLE optimistic_layers (mutation_id INTEGER PRIMARY KEY, optimistic_data_json TEXT NOT NULL, normalized_updates BLOB NOT NULL, FOREIGN KEY (mutation_id) REFERENCES records(id) ON DELETE CASCADE)",
+ ],
+ ),
+ (
+ "optimistic-foreign-key-from",
+ vec![
+ "DROP TABLE optimistic_layers",
+ "CREATE TABLE optimistic_layers (mutation_id INTEGER PRIMARY KEY, optimistic_data_json TEXT NOT NULL, normalized_updates BLOB NOT NULL, FOREIGN KEY (optimistic_data_json) REFERENCES mutation_queue(id) ON DELETE CASCADE)",
+ ],
+ ),
+ (
+ "optimistic-foreign-key-to",
+ vec![
+ "DROP TABLE optimistic_layers",
+ "CREATE TABLE optimistic_layers (mutation_id INTEGER PRIMARY KEY, optimistic_data_json TEXT NOT NULL, normalized_updates BLOB NOT NULL, FOREIGN KEY (mutation_id) REFERENCES mutation_queue(query) ON DELETE CASCADE)",
+ ],
+ ),
+ (
+ "optimistic-cascade",
+ vec![
+ "DROP TABLE optimistic_layers",
+ "CREATE TABLE optimistic_layers (mutation_id INTEGER PRIMARY KEY, optimistic_data_json TEXT NOT NULL, normalized_updates BLOB NOT NULL, FOREIGN KEY (mutation_id) REFERENCES mutation_queue(id))",
+ ],
+ ),
+ (
+ "unexpected-table",
+ vec!["CREATE TABLE unexpected_object (id INTEGER)"],
+ ),
+ (
+ "unexpected-sequence-shaped-table",
+ vec![
+ "CREATE TABLE unexpected_sequence (value INTEGER PRIMARY KEY, is_called INTEGER, start INTEGER, inc INTEGER, min INTEGER, max INTEGER, cycle INTEGER)",
+ ],
+ ),
+ (
+ "unexpected-sqlite-sequence-shaped-table",
+ vec!["CREATE TABLE unexpected_sqlite_sequence (name, seq)"],
+ ),
+ (
+ "unexpected-index",
+ vec!["CREATE INDEX records_value_index ON records(value)"],
+ ),
+ (
+ "unexpected-unique-index",
+ vec!["CREATE UNIQUE INDEX records_value_unique ON records(value)"],
+ ),
+ (
+ "unexpected-partial-index",
+ vec!["CREATE INDEX records_value_partial ON records(value) WHERE id <> ''"],
+ ),
+ ];
+
+ for (name, statements) in cases {
+ let database = TursoMemoryDatabase::new(format!("malformed-{name}.db"));
+ let storage = database.open("scope").unwrap();
+ for sql in statements {
+ raw_execute(&storage, sql, Vec::new());
+ }
+ assert_eq!(
+ storage.try_close().unwrap(),
+ TursoStorageCloseOutcome::Healthy
+ );
+ let error = database.open("scope").unwrap_err();
+ assert_eq!(
+ error.physical_reset_reason(),
+ Some(PhysicalResetReason::Compatibility),
+ "case {name}: {error}"
+ );
+ database.physical_reset();
+ }
+}
+
+#[test]
+fn corrupt_keys_blobs_queue_relationships_and_numerics_request_reset() {
+ block_on(async {
+ let storage = TursoStorage::open_in_memory("corrupt-record").unwrap();
+ raw_execute(
+ &storage,
+ RECORD_UPSERT,
+ vec![text("Thing"), text("1"), Value::from_blob(vec![0xff, 0x00])],
+ );
+ let error = storage.get_batch(&[key("Thing:1")]).await.unwrap_err();
+ assert_eq!(
+ error.physical_reset_reason(),
+ Some(PhysicalResetReason::Codec)
+ );
+
+ let storage = TursoStorage::open_in_memory("corrupt-key").unwrap();
+ raw_execute(
+ &storage,
+ RECORD_UPSERT,
+ vec![
+ text(""),
+ text("id"),
+ Value::from_blob(encode_record(&record("valid"))),
+ ],
+ );
+ let error = storage
+ .scan_records(&[String::new()], None, 10)
+ .await
+ .unwrap_err();
+ assert_eq!(
+ error.physical_reset_reason(),
+ Some(PhysicalResetReason::Corruption)
+ );
+
+ let storage = TursoStorage::open_in_memory("missing-layer").unwrap();
+ raw_execute(
+ &storage,
+ "INSERT INTO mutation_queue (query, variables_json, created_at_ms) VALUES (?1, ?2, ?3)",
+ vec![
+ text("mutation Missing { x }"),
+ text("{}"),
+ Value::from_i64(0),
+ ],
+ );
+ assert_eq!(
+ storage
+ .load_mutation_queue()
+ .await
+ .unwrap_err()
+ .physical_reset_reason(),
+ Some(PhysicalResetReason::Invariant)
+ );
+
+ let storage = TursoStorage::open_in_memory("orphan-layer").unwrap();
+ raw_execute(&storage, "PRAGMA foreign_keys = OFF", Vec::new());
+ raw_execute(
+ &storage,
+ LAYER_INSERT,
+ vec![
+ Value::from_i64(999),
+ text("{}"),
+ Value::from_blob(encode_record_updates(&RecordUpdates::default())),
+ ],
+ );
+ raw_execute(&storage, "PRAGMA foreign_keys = ON", Vec::new());
+ assert_eq!(raw_scalar(&storage, "PRAGMA foreign_keys"), 1);
+ assert_eq!(
+ storage
+ .load_mutation_queue()
+ .await
+ .unwrap_err()
+ .physical_reset_reason(),
+ Some(PhysicalResetReason::Invariant)
+ );
+
+ let mut storage = TursoStorage::open_in_memory("corrupt-updates").unwrap();
+ let id = storage.enqueue_mutation(queued("Corrupt")).await.unwrap();
+ raw_execute(
+ &storage,
+ "UPDATE optimistic_layers SET normalized_updates = ?2 WHERE mutation_id = ?1",
+ vec![
+ Value::from_i64(mutation_id_to_sql(id).unwrap()),
+ Value::from_blob(vec![0xff]),
+ ],
+ );
+ assert_eq!(
+ storage
+ .load_mutation_queue()
+ .await
+ .unwrap_err()
+ .physical_reset_reason(),
+ Some(PhysicalResetReason::Codec)
+ );
+
+ for (name, column, value) in [
+ ("negative-attempt", "attempt_count", -1),
+ ("large-attempt", "attempt_count", i64::from(u32::MAX) + 1),
+ ("negative-generation", "lease_generation", -1),
+ ] {
+ let mut storage = TursoStorage::open_in_memory(name).unwrap();
+ let id = storage.enqueue_mutation(queued(name)).await.unwrap();
+ raw_execute(
+ &storage,
+ &format!("UPDATE mutation_queue SET {column} = ?2 WHERE id = ?1"),
+ vec![
+ Value::from_i64(mutation_id_to_sql(id).unwrap()),
+ Value::from_i64(value),
+ ],
+ );
+ assert_eq!(
+ storage
+ .load_mutation_queue()
+ .await
+ .unwrap_err()
+ .physical_reset_reason(),
+ Some(PhysicalResetReason::Invariant)
+ );
+ }
+
+ for invalid_id in [0, -1] {
+ let storage =
+ TursoStorage::open_in_memory(&format!("invalid-id-{invalid_id}")).unwrap();
+ raw_execute(
+ &storage,
+ "INSERT INTO mutation_queue (id, query, variables_json, created_at_ms) VALUES (?1, ?2, ?3, ?4)",
+ vec![
+ Value::from_i64(invalid_id),
+ text("mutation Invalid { x }"),
+ text("{}"),
+ Value::from_i64(0),
+ ],
+ );
+ raw_execute(
+ &storage,
+ LAYER_INSERT,
+ vec![
+ Value::from_i64(invalid_id),
+ text("{}"),
+ Value::from_blob(encode_record_updates(&RecordUpdates::default())),
+ ],
+ );
+ assert_eq!(
+ storage
+ .load_mutation_queue()
+ .await
+ .unwrap_err()
+ .physical_reset_reason(),
+ Some(PhysicalResetReason::Invariant)
+ );
+ }
+
+ let mut storage = TursoStorage::open_in_memory("generation-overflow").unwrap();
+ let id = storage
+ .enqueue_mutation(queued("GenerationOverflow"))
+ .await
+ .unwrap();
+ raw_execute(
+ &storage,
+ "UPDATE mutation_queue SET lease_generation = ?2 WHERE id = ?1",
+ vec![
+ Value::from_i64(mutation_id_to_sql(id).unwrap()),
+ Value::from_i64(i64::MAX),
+ ],
+ );
+ assert_eq!(
+ storage
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner".into(),
+ now_ms: 1,
+ lease_expires_at_ms: 2,
+ })
+ .await
+ .unwrap_err()
+ .physical_reset_reason(),
+ Some(PhysicalResetReason::Invariant)
+ );
+ });
+}
+
+#[test]
+fn reset_health_latch_blocks_every_method_without_touching_turso() {
+ block_on(async {
+ let mut storage = TursoStorage::open_in_memory("health-latch").unwrap();
+ raw_execute(
+ &storage,
+ RECORD_UPSERT,
+ vec![text("Thing"), text("1"), Value::from_blob(vec![0xff])],
+ );
+ expect_reset_reason(
+ storage.get_batch(&[key("Thing:1")]).await,
+ PhysicalResetReason::Codec,
+ );
+
+ driver::clear_control_trace();
+ driver::arm_reset_failure(RECORD_GET);
+ expect_every_storage_method_latched(&mut storage, PhysicalResetReason::Codec).await;
+ assert!(driver::take_control_trace().is_empty());
+ assert_eq!(
+ storage.try_close().unwrap(),
+ TursoStorageCloseOutcome::ResetRequired(PhysicalResetReason::Codec)
+ );
+
+ // The reset fault remains armed, proving the latched get did not even
+ // prepare/reset its Turso statement.
+ let probe = TursoStorage::open_in_memory("health-latch-probe").unwrap();
+ expect_reset_reason(
+ probe.get_batch(&[key("Thing:1")]).await,
+ PhysicalResetReason::TransactionOutcomeUncertain,
+ );
+ assert_eq!(
+ probe.try_close().unwrap(),
+ TursoStorageCloseOutcome::ResetRequired(
+ PhysicalResetReason::TransactionOutcomeUncertain
+ )
+ );
+ });
+}
+
+#[test]
+fn statement_cleanup_failures_are_uncertain_and_begin_cleanup_attempts_rollback() {
+ block_on(async {
+ for (name, sql) in [
+ ("begin-reset", "BEGIN IMMEDIATE"),
+ ("write-reset", RECORD_UPSERT),
+ ] {
+ let database = TursoMemoryDatabase::new(format!("{name}.db"));
+ let mut storage = database.open("scope").unwrap();
+ driver::clear_control_trace();
+ driver::arm_reset_failure(sql);
+ expect_reset_reason(
+ storage
+ .put_batch(vec![(key("Thing:1"), record("value"))])
+ .await,
+ PhysicalResetReason::TransactionOutcomeUncertain,
+ );
+ assert_eq!(
+ driver::take_control_trace(),
+ vec![
+ driver::TestControlPhase::Begin,
+ driver::TestControlPhase::Rollback,
+ ],
+ "case {name}"
+ );
+
+ driver::clear_control_trace();
+ expect_reset_reason(
+ storage.get_batch(&[key("Thing:1")]).await,
+ PhysicalResetReason::TransactionOutcomeUncertain,
+ );
+ assert!(driver::take_control_trace().is_empty(), "case {name}");
+ assert_eq!(
+ storage.try_close().unwrap(),
+ TursoStorageCloseOutcome::ResetRequired(
+ PhysicalResetReason::TransactionOutcomeUncertain
+ )
+ );
+ database.physical_reset();
+ let replacement = database.open("scope").unwrap();
+ assert_eq!(
+ replacement.get_batch(&[key("Thing:1")]).await.unwrap(),
+ vec![None]
+ );
+ assert_eq!(
+ replacement.try_close().unwrap(),
+ TursoStorageCloseOutcome::Healthy
+ );
+ }
+ });
+}
+
+#[test]
+fn completion_delivered_commit_failure_is_exact_and_not_reusable() {
+ block_on(async {
+ let io = FaultIo::new();
+ let mut storage = fault_storage(io.clone());
+ io.arm(IoFault::CommitCompletion);
+ driver::clear_control_trace();
+ expect_reset_reason(
+ storage
+ .put_batch(vec![(key("Thing:1"), record("value"))])
+ .await,
+ PhysicalResetReason::TransactionOutcomeUncertain,
+ );
+ assert!(io.is_clear(), "COMMIT did not observe its File completion");
+ assert_eq!(
+ driver::take_control_trace(),
+ vec![
+ driver::TestControlPhase::Begin,
+ driver::TestControlPhase::Commit,
+ driver::TestControlPhase::Rollback,
+ ]
+ );
+ assert!(
+ driver::take_control_io_trace().is_empty(),
+ "the COMMIT Statement must observe the delivered completion directly"
+ );
+
+ driver::clear_control_trace();
+ expect_reset_reason(
+ storage.get_batch(&[key("Thing:1")]).await,
+ PhysicalResetReason::TransactionOutcomeUncertain,
+ );
+ assert!(driver::take_control_trace().is_empty());
+ assert!(driver::take_control_io_trace().is_empty());
+ assert_eq!(
+ storage.try_close().unwrap(),
+ TursoStorageCloseOutcome::ResetRequired(
+ PhysicalResetReason::TransactionOutcomeUncertain
+ )
+ );
+ });
+}
+
+#[test]
+fn rollback_io_step_polling_failure_is_exact_and_not_reusable() {
+ block_on(async {
+ let io = FaultIo::new();
+ let mut storage = fault_storage(io.clone());
+ storage.arm_fault(TestFault::RollbackIoStepAfter {
+ site: TestFaultSite::Put,
+ index: 0,
+ fault_state: io.fault.clone(),
+ fault_code: IoFault::RollbackIoStep as u8,
+ });
+ driver::clear_control_trace();
+ expect_reset_reason(
+ storage
+ .put_batch(vec![(key("Thing:1"), record("value"))])
+ .await,
+ PhysicalResetReason::TransactionOutcomeUncertain,
+ );
+ assert!(io.is_clear(), "ROLLBACK did not poll the injected IO error");
+ assert_eq!(
+ driver::take_control_trace(),
+ vec![
+ driver::TestControlPhase::Begin,
+ driver::TestControlPhase::Rollback,
+ ]
+ );
+ assert_eq!(
+ driver::take_control_io_trace(),
+ vec![driver::TestControlPhase::Rollback]
+ );
+
+ driver::clear_control_trace();
+ expect_reset_reason(
+ storage.get_batch(&[key("Thing:1")]).await,
+ PhysicalResetReason::TransactionOutcomeUncertain,
+ );
+ assert!(driver::take_control_trace().is_empty());
+ assert!(driver::take_control_io_trace().is_empty());
+ assert_eq!(
+ storage.try_close().unwrap(),
+ TursoStorageCloseOutcome::ResetRequired(
+ PhysicalResetReason::TransactionOutcomeUncertain
+ )
+ );
+
+ let replacement = fault_storage(FaultIo::new());
+ assert_eq!(
+ replacement.get_batch(&[key("Thing:1")]).await.unwrap(),
+ vec![None]
+ );
+ assert!(replacement.load_mutation_queue().await.unwrap().is_empty());
+ assert_eq!(
+ replacement.try_close().unwrap(),
+ TursoStorageCloseOutcome::Healthy
+ );
+ });
+}
+
+#[test]
+fn operation_reset_classes_survive_successful_rollback_and_latching() {
+ block_on(async {
+ for reason in [PhysicalResetReason::StorageFull, PhysicalResetReason::Io] {
+ let mut storage = TursoStorage::open_in_memory("preserved-reset-class").unwrap();
+ storage.arm_fault(TestFault::ResetAfter {
+ site: TestFaultSite::Put,
+ index: 0,
+ reason,
+ });
+ expect_reset_reason(
+ storage
+ .put_batch(vec![(key("Thing:1"), record("value"))])
+ .await,
+ reason,
+ );
+ expect_reset_reason(storage.get_batch(&[key("Thing:1")]).await, reason);
+ assert_eq!(
+ storage.try_close().unwrap(),
+ TursoStorageCloseOutcome::ResetRequired(reason)
+ );
+ }
+ });
+}
+
+#[test]
+fn injected_statement_failures_roll_back_every_storage_boundary() {
+ block_on(async {
+ let mut storage = TursoStorage::open_in_memory("atomic-put").unwrap();
+ storage.arm_fault(TestFault::After {
+ site: TestFaultSite::Put,
+ index: 0,
+ });
+ storage
+ .put_batch(vec![
+ (key("Thing:1"), record("one")),
+ (key("Thing:2"), record("two")),
+ ])
+ .await
+ .unwrap_err();
+ assert_eq!(
+ storage
+ .get_batch(&[key("Thing:1"), key("Thing:2")])
+ .await
+ .unwrap(),
+ vec![None, None]
+ );
+
+ storage
+ .put_batch(vec![
+ (key("Thing:1"), record("one")),
+ (key("Thing:2"), record("two")),
+ ])
+ .await
+ .unwrap();
+ storage.arm_fault(TestFault::After {
+ site: TestFaultSite::Delete,
+ index: 0,
+ });
+ storage
+ .delete_batch(&[key("Thing:1"), key("Thing:2")])
+ .await
+ .unwrap_err();
+ assert_eq!(
+ storage
+ .get_batch(&[key("Thing:1"), key("Thing:2")])
+ .await
+ .unwrap(),
+ vec![Some(record("one")), Some(record("two"))]
+ );
+
+ storage.arm_fault(TestFault::After {
+ site: TestFaultSite::Enqueue,
+ index: 0,
+ });
+ storage
+ .enqueue_mutation(queued("Atomic"))
+ .await
+ .unwrap_err();
+ assert!(storage.load_mutation_queue().await.unwrap().is_empty());
+
+ let id = storage.enqueue_mutation(queued("Complete")).await.unwrap();
+ let claimed = storage
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner".into(),
+ now_ms: 1,
+ lease_expires_at_ms: 10,
+ })
+ .await
+ .unwrap()
+ .unwrap();
+ storage.arm_fault(TestFault::After {
+ site: TestFaultSite::Complete,
+ index: 0,
+ });
+ storage
+ .complete_mutation(
+ id,
+ token("runner", claimed.lease_generation),
+ vec![
+ (key("Result:1"), record("one")),
+ (key("Result:2"), record("two")),
+ ],
+ )
+ .await
+ .unwrap_err();
+ assert_eq!(
+ storage
+ .get_batch(&[key("Result:1"), key("Result:2")])
+ .await
+ .unwrap(),
+ vec![None, None]
+ );
+ assert_eq!(storage.load_mutation_queue().await.unwrap().len(), 1);
+
+ storage.arm_fault(TestFault::After {
+ site: TestFaultSite::Discard,
+ index: 0,
+ });
+ storage
+ .discard_mutation(id, token("runner", claimed.lease_generation))
+ .await
+ .unwrap_err();
+ assert_eq!(storage.load_mutation_queue().await.unwrap().len(), 1);
+
+ storage.arm_fault(TestFault::After {
+ site: TestFaultSite::Clear,
+ index: 0,
+ });
+ storage.clear().await.unwrap_err();
+ assert_eq!(storage.load_mutation_queue().await.unwrap().len(), 1);
+ assert_eq!(
+ storage.get_batch(&[key("Thing:1")]).await.unwrap(),
+ vec![Some(record("one"))]
+ );
+ });
+}
+
+#[test]
+fn corruption_quota_io_and_uncertain_transactions_have_payload_free_classes() {
+ assert_eq!(
+ TursoStorageError::turso(LimboError::Corrupt("secret payload".into()))
+ .physical_reset_reason(),
+ Some(PhysicalResetReason::Corruption)
+ );
+ assert_eq!(
+ TursoStorageError::turso(LimboError::DatabaseFull("secret payload".into()))
+ .physical_reset_reason(),
+ Some(PhysicalResetReason::StorageFull)
+ );
+ assert_eq!(
+ TursoStorageError::turso(LimboError::CompletionError(CompletionError::IOError(
+ std::io::ErrorKind::StorageFull,
+ "write",
+ )))
+ .physical_reset_reason(),
+ Some(PhysicalResetReason::StorageFull)
+ );
+ assert_eq!(
+ TursoStorageError::turso(LimboError::CompletionError(CompletionError::IOError(
+ std::io::ErrorKind::Other,
+ "sync",
+ )))
+ .physical_reset_reason(),
+ Some(PhysicalResetReason::Io)
+ );
+ let error = TursoStorageError::reset(PhysicalResetReason::TransactionOutcomeUncertain);
+ assert!(!error.to_string().contains("secret"));
+}
+
+#[derive(Clone, Copy)]
+#[repr(u8)]
+enum IoFault {
+ None = 0,
+ StorageFull = 1,
+ Sync = 2,
+ CommitCompletion = 3,
+ RollbackIoStep = 4,
+}
+
+struct FaultIo {
+ inner: MemoryIO,
+ fault: Arc<AtomicU8>,
+}
+
+impl FaultIo {
+ fn new() -> Arc<Self> {
+ Arc::new(Self {
+ inner: MemoryIO::new(),
+ fault: Arc::new(AtomicU8::new(IoFault::None as u8)),
+ })
+ }
+
+ fn arm(&self, fault: IoFault) {
+ self.fault.store(fault as u8, Ordering::SeqCst);
+ }
+
+ fn take(&self, fault: IoFault) -> bool {
+ self.fault
+ .compare_exchange(
+ fault as u8,
+ IoFault::None as u8,
+ Ordering::SeqCst,
+ Ordering::SeqCst,
+ )
+ .is_ok()
+ }
+
+ fn is_clear(&self) -> bool {
+ self.fault.load(Ordering::SeqCst) == IoFault::None as u8
+ }
+}
+
+impl Clock for FaultIo {
+ fn current_time_monotonic(&self) -> MonotonicInstant {
+ self.inner.current_time_monotonic()
+ }
+
+ fn current_time_wall_clock(&self) -> WallClockInstant {
+ self.inner.current_time_wall_clock()
+ }
+}
+
+impl IO for FaultIo {
+ fn open_file(
+ &self,
+ path: &str,
+ flags: OpenFlags,
+ direct: bool,
+ ) -> turso_core::Result<Arc<dyn File>> {
+ Ok(Arc::new(FaultFile {
+ fault: self.fault.clone(),
+ inner: self.inner.open_file(path, flags, direct)?,
+ }))
+ }
+
+ fn remove_file(&self, path: &str) -> turso_core::Result<()> {
+ self.inner.remove_file(path)
+ }
+
+ fn file_id(&self, path: &str) -> turso_core::Result<FileId> {
+ self.inner.file_id(path)
+ }
+
+ fn supports_shared_wal_coordination(&self) -> bool {
+ false
+ }
+
+ fn step(&self) -> turso_core::Result<()> {
+ if driver::current_test_control_phase() == Some(driver::TestControlPhase::Rollback)
+ && self.take(IoFault::RollbackIoStep)
+ {
+ return Err(CompletionError::IOError(
+ std::io::ErrorKind::Other,
+ "rollback IO::step polling",
+ )
+ .into());
+ }
+ self.inner.step()
+ }
+}
+
+struct FaultFile {
+ fault: Arc<AtomicU8>,
+ inner: Arc<dyn File>,
+}
+
+impl FaultFile {
+ fn take(&self, fault: IoFault) -> bool {
+ self.fault
+ .compare_exchange(
+ fault as u8,
+ IoFault::None as u8,
+ Ordering::SeqCst,
+ Ordering::SeqCst,
+ )
+ .is_ok()
+ }
+
+ fn deliver_commit_completion_error(&self, completion: &Completion) -> bool {
+ if driver::current_test_control_phase() != Some(driver::TestControlPhase::Commit)
+ || !self.take(IoFault::CommitCompletion)
+ {
+ return false;
+ }
+ // Deliver the failure through the File completion before returning;
+ // the COMMIT Statement observes that completion directly. This is not
+ // an IO::step error and no successful operation is later reclassified.
+ completion.error(CompletionError::IOError(
+ std::io::ErrorKind::Other,
+ "commit completion delivery",
+ ));
+ true
+ }
+}
+
+impl File for FaultFile {
+ fn lock_file(&self, exclusive: bool) -> turso_core::Result<()> {
+ self.inner.lock_file(exclusive)
+ }
+
+ fn unlock_file(&self) -> turso_core::Result<()> {
+ self.inner.unlock_file()
+ }
+
+ fn pread(&self, pos: u64, completion: Completion) -> turso_core::Result<Completion> {
+ self.inner.pread(pos, completion)
+ }
+
+ fn pwrite(
+ &self,
+ pos: u64,
+ buffer: Arc<Buffer>,
+ completion: Completion,
+ ) -> turso_core::Result<Completion> {
+ if self.deliver_commit_completion_error(&completion) {
+ return Ok(completion);
+ }
+ if self.take(IoFault::StorageFull) {
+ return Err(CompletionError::IOError(std::io::ErrorKind::StorageFull, "write").into());
+ }
+ self.inner.pwrite(pos, buffer, completion)
+ }
+
+ fn pwritev(
+ &self,
+ pos: u64,
+ buffers: Vec<Arc<Buffer>>,
+ completion: Completion,
+ ) -> turso_core::Result<Completion> {
+ if self.deliver_commit_completion_error(&completion) {
+ return Ok(completion);
+ }
+ if self.take(IoFault::StorageFull) {
+ return Err(CompletionError::IOError(std::io::ErrorKind::StorageFull, "writev").into());
+ }
+ self.inner.pwritev(pos, buffers, completion)
+ }
+
+ fn sync(
+ &self,
+ completion: Completion,
+ sync_type: FileSyncType,
+ ) -> turso_core::Result<Completion> {
+ if self.deliver_commit_completion_error(&completion) {
+ return Ok(completion);
+ }
+ if self.take(IoFault::Sync) {
+ return Err(CompletionError::IOError(std::io::ErrorKind::Other, "sync").into());
+ }
+ self.inner.sync(completion, sync_type)
+ }
+
+ fn size(&self) -> turso_core::Result<u64> {
+ self.inner.size()
+ }
+
+ fn truncate(&self, len: u64, completion: Completion) -> turso_core::Result<Completion> {
+ if self.deliver_commit_completion_error(&completion) {
+ return Ok(completion);
+ }
+ self.inner.truncate(len, completion)
+ }
+
+ fn has_hole(&self, pos: usize, len: usize) -> turso_core::Result<bool> {
+ self.inner.has_hole(pos, len)
+ }
+
+ fn punch_hole(&self, pos: usize, len: usize) -> turso_core::Result<()> {
+ self.inner.punch_hole(pos, len)
+ }
+}
+
+fn fault_storage(io: Arc<FaultIo>) -> TursoStorage {
+ static NEXT_FAULT_DATABASE: AtomicU64 = AtomicU64::new(1);
+ let id = NEXT_FAULT_DATABASE.fetch_add(1, Ordering::Relaxed);
+ let path = format!("fault-{id}.db");
+ let io_trait: Arc<dyn IO> = io;
+ let database =
+ Database::open(io_trait, &path, OpenOptions::new(Arc::new(SqliteDialect))).unwrap();
+ let connection = database.connect().unwrap();
+ initialize(&connection, "fault-scope", true).unwrap();
+ TursoStorage {
+ health: AtomicU8::new(0),
+ database,
+ connection,
+ fault: Mutex::new(None),
+ }
+}
+
+#[test]
+fn injected_memory_io_quota_and_sync_failures_require_reset() {
+ block_on(async {
+ for fault in [IoFault::StorageFull, IoFault::Sync] {
+ // Both injected file failures are reached while COMMIT is in
+ // flight, so the transaction outcome class takes precedence.
+ let expected = PhysicalResetReason::TransactionOutcomeUncertain;
+ let io = FaultIo::new();
+ let mut storage = fault_storage(io.clone());
+ io.arm(fault);
+ expect_reset_reason(
+ storage
+ .put_batch(vec![(key("Thing:1"), record("value"))])
+ .await,
+ expected,
+ );
+ expect_reset_reason(storage.get_batch(&[key("Thing:1")]).await, expected);
+ assert_eq!(
+ storage.try_close().unwrap(),
+ TursoStorageCloseOutcome::ResetRequired(expected)
+ );
+ }
+ });
+}
diff --git a/crates/client/cache-turso/tests/engine_turso.rs b/crates/client/cache-turso/tests/engine_turso.rs
new file mode 100644
index 0000000000..1147712a1d
--- /dev/null
+++ b/crates/client/cache-turso/tests/engine_turso.rs
@@ -0,0 +1,356 @@
+#![cfg(not(target_arch = "wasm32"))]
+
+use cache_core::engine::{BeginOptimisticWrite, Engine, ReadResult};
+use cache_core::queue::{MutationClaimRequest, MutationClaimToken};
+use cache_core::record_selection::RecordSelection;
+use cache_core::store::Storage;
+use cache_core::value::{CacheValue, EntityKey, Record};
+use cache_turso::{TursoMemoryDatabase, TursoStorage, TursoStorageCloseOutcome};
+use pollster::block_on;
+use serde_json::{Value as Json, json};
+
+const QUERY: &str = r#"
+query Soup($input: SoupInput!) {
+ user {
+ id
+ soup(input: $input) {
+ items {
+ __typename
+ id
+ ... on GraphqlSoupDocument {
+ properties {
+ id
+ displayName
+ value {
+ __typename
+ ... on GraphqlStringPropertyValue { stringValue: value }
+ }
+ }
+ }
+ }
+ nextCursor
+ }
+ }
+}
+"#;
+
+const MUTATION: &str = r#"
+mutation SetEntityProperty($input: SetEntityPropertyInput!) {
+ setEntityProperty(input: $input) {
+ id
+ displayName
+ value {
+ __typename
+ ... on GraphqlStringPropertyValue { stringValue: value }
+ }
+ }
+}
+"#;
+
+fn query_vars() -> serde_json::Map<String, Json> {
+ let Json::Object(values) = json!({"input": {"limit": 10}}) else {
+ unreachable!()
+ };
+ values
+}
+
+fn mutation_vars(value: &str) -> serde_json::Map<String, Json> {
+ let Json::Object(values) = json!({"input": {
+ "entityType": "DOCUMENT",
+ "entityId": "doc-1",
+ "propertyDefinitionId": "definition-1",
+ "value": {"string": value}
+ }}) else {
+ unreachable!()
+ };
+ values
+}
+
+fn page(display_name: &str, value: &str, user: &str) -> Json {
+ json!({"user": {"id": user, "soup": {
+ "items": [{
+ "__typename": "GraphqlSoupDocument",
+ "id": "doc-1",
+ "properties": [{
+ "id": "property-1",
+ "displayName": display_name,
+ "value": {
+ "__typename": "GraphqlStringPropertyValue",
+ "stringValue": value
+ }
+ }]
+ }],
+ "nextCursor": null
+ }}})
+}
+
+fn mutation_response(display_name: &str, value: &str) -> Json {
+ json!({"setEntityProperty": {
+ "id": "property-1",
+ "displayName": display_name,
+ "value": {
+ "__typename": "GraphqlStringPropertyValue",
+ "stringValue": value
+ }
+ }})
+}
+
+async fn read_value(engine: &mut Engine<TursoStorage>) -> (String, String) {
+ let ReadResult::Hit { data } = engine
+ .read_query(None, QUERY, Some("Soup"), &query_vars())
+ .await
+ .unwrap()
+ else {
+ panic!("expected Turso-backed hit")
+ };
+ let property = &data["user"]["soup"]["items"][0]["properties"][0];
+ (
+ property["displayName"].as_str().unwrap().to_owned(),
+ property["value"]["stringValue"]
+ .as_str()
+ .unwrap()
+ .to_owned(),
+ )
+}
+
+#[test]
+fn query_identity_cold_tier_selection_and_clear_run_over_turso() {
+ block_on(async {
+ let storage = TursoStorage::open_in_memory("engine-query").unwrap();
+ let mut engine = Engine::with_capacity(storage, 1);
+ let original = page("Status", "todo", "user-1");
+ engine
+ .write_query(
+ Some(1),
+ QUERY,
+ Some("Soup"),
+ &query_vars(),
+ &original,
+ Some("user-1"),
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ engine.current_identity().await.unwrap().as_deref(),
+ Some("user-1")
+ );
+ assert_eq!(
+ read_value(&mut engine).await,
+ ("Status".into(), "todo".into())
+ );
+
+ let selection = RecordSelection::parse(
+ "fragment Property on GraphqlProperty { id displayName }",
+ "Property",
+ )
+ .unwrap();
+ let selected = engine.read_records(&selection, None, 10).await.unwrap();
+ assert_eq!(
+ selected.records,
+ vec![json!({"id": "property-1", "displayName": "Status"})]
+ );
+
+ let reset = engine
+ .write_query(
+ Some(2),
+ QUERY,
+ Some("Soup"),
+ &query_vars(),
+ &page("Other", "done", "user-2"),
+ Some("user-2"),
+ )
+ .await
+ .unwrap();
+ assert!(reset.reset);
+ assert_eq!(
+ engine.current_identity().await.unwrap().as_deref(),
+ Some("user-2")
+ );
+ engine.clear().await.unwrap();
+ assert!(matches!(
+ engine
+ .read_query(None, QUERY, Some("Soup"), &query_vars())
+ .await
+ .unwrap(),
+ ReadResult::Miss
+ ));
+ });
+}
+
+#[test]
+fn optimistic_hydration_retry_complete_and_reopen_run_over_turso() {
+ block_on(async {
+ let database = TursoMemoryDatabase::new("engine-optimistic-reopen.db");
+ let mut engine = Engine::new(database.open("engine-optimistic").unwrap());
+ engine
+ .write_query(
+ None,
+ QUERY,
+ Some("Soup"),
+ &query_vars(),
+ &page("Status", "todo", "user-1"),
+ Some("user-1"),
+ )
+ .await
+ .unwrap();
+ let (mutation_id, _) = engine
+ .begin_optimistic_write(
+ None,
+ BeginOptimisticWrite {
+ query: MUTATION,
+ operation_name: Some("SetEntityProperty"),
+ variables: &mutation_vars("doing"),
+ data: &mutation_response("Status", "doing"),
+ link_patches: &[],
+ revalidations: &[],
+ created_at_ms: 10,
+ },
+ )
+ .await
+ .unwrap();
+ assert_eq!(read_value(&mut engine).await.1, "doing");
+ assert_eq!(
+ engine.into_storage().try_close().unwrap(),
+ TursoStorageCloseOutcome::Healthy
+ );
+
+ let mut reopened = Engine::new(database.open("engine-optimistic").unwrap());
+ assert_eq!(read_value(&mut reopened).await.1, "doing");
+ let first_claim = reopened
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner-a".into(),
+ now_ms: 20,
+ lease_expires_at_ms: 100,
+ })
+ .await
+ .unwrap()
+ .unwrap();
+ reopened
+ .defer_optimistic_write(
+ mutation_id,
+ MutationClaimToken {
+ owner: "runner-a".into(),
+ generation: first_claim.lease_generation,
+ },
+ 200,
+ "offline".into(),
+ )
+ .await
+ .unwrap();
+ assert!(
+ reopened
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner-b".into(),
+ now_ms: 199,
+ lease_expires_at_ms: 300,
+ })
+ .await
+ .unwrap()
+ .is_none()
+ );
+ let second_claim = reopened
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner-b".into(),
+ now_ms: 200,
+ lease_expires_at_ms: 300,
+ })
+ .await
+ .unwrap()
+ .unwrap();
+ reopened
+ .commit_optimistic_write(
+ mutation_id,
+ MutationClaimToken {
+ owner: "runner-b".into(),
+ generation: second_claim.lease_generation,
+ },
+ MUTATION,
+ Some("SetEntityProperty"),
+ &mutation_vars("done"),
+ &mutation_response("Status (server)", "done"),
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ read_value(&mut reopened).await,
+ ("Status (server)".into(), "done".into())
+ );
+ assert!(
+ reopened
+ .storage()
+ .load_mutation_queue()
+ .await
+ .unwrap()
+ .is_empty()
+ );
+ assert_eq!(
+ reopened.into_storage().try_close().unwrap(),
+ TursoStorageCloseOutcome::Healthy
+ );
+ });
+}
+
+#[test]
+fn optimistic_discard_restores_durable_base_over_turso() {
+ block_on(async {
+ let storage = TursoStorage::open_in_memory("engine-discard").unwrap();
+ let mut engine = Engine::new(storage);
+ engine
+ .write_query(
+ None,
+ QUERY,
+ Some("Soup"),
+ &query_vars(),
+ &page("Status", "todo", "user-1"),
+ None,
+ )
+ .await
+ .unwrap();
+ let (mutation_id, _) = engine
+ .begin_optimistic_write(
+ None,
+ BeginOptimisticWrite {
+ query: MUTATION,
+ operation_name: Some("SetEntityProperty"),
+ variables: &mutation_vars("bad"),
+ data: &mutation_response("Status", "bad"),
+ link_patches: &[],
+ revalidations: &[],
+ created_at_ms: 1,
+ },
+ )
+ .await
+ .unwrap();
+ let claimed = engine
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner".into(),
+ now_ms: 2,
+ lease_expires_at_ms: 100,
+ })
+ .await
+ .unwrap()
+ .unwrap();
+ engine
+ .rollback_optimistic_write(
+ mutation_id,
+ MutationClaimToken {
+ owner: "runner".into(),
+ generation: claimed.lease_generation,
+ },
+ )
+ .await
+ .unwrap();
+ assert_eq!(read_value(&mut engine).await.1, "todo");
+
+ let records = engine
+ .storage()
+ .get_batch(&[EntityKey("GraphqlProperty:property-1".into())])
+ .await
+ .unwrap();
+ let record: &Record = records[0].as_ref().unwrap();
+ let CacheValue::Object(value) = record.fields.get("value").unwrap() else {
+ panic!("property value object")
+ };
+ assert_eq!(value.get("value"), Some(&CacheValue::String("todo".into())));
+ });
+}
diff --git a/crates/client/cache-turso/tests/shared_conformance.rs b/crates/client/cache-turso/tests/shared_conformance.rs
new file mode 100644
index 0000000000..c3eb8c233e
--- /dev/null
+++ b/crates/client/cache-turso/tests/shared_conformance.rs
@@ -0,0 +1,697 @@
+#![cfg(not(target_arch = "wasm32"))]
+
+use cache_core::normalize::RecordUpdates;
+use cache_core::queue::{
+ MutationClaimRequest, MutationClaimToken, MutationRequest, NewQueuedMutation,
+ PersistedOptimisticLayer, StoredMutation,
+};
+use cache_core::store::{InMemoryStorage, Storage};
+use cache_core::value::{CacheValue, EntityKey, Record};
+use cache_sqlite::SqliteStorage;
+use cache_turso::{TursoMemoryDatabase, TursoStorage, TursoStorageCloseOutcome};
+use pollster::block_on;
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicU64, Ordering};
+
+trait BackendFactory: Sized {
+ type Backend: Storage;
+
+ fn create() -> (Self, Self::Backend);
+ fn reopen(&mut self, storage: Self::Backend) -> Self::Backend;
+ fn finish(self, storage: Self::Backend);
+}
+
+struct InMemoryFactory;
+
+impl BackendFactory for InMemoryFactory {
+ type Backend = InMemoryStorage;
+
+ fn create() -> (Self, Self::Backend) {
+ (Self, InMemoryStorage::new())
+ }
+
+ fn reopen(&mut self, storage: Self::Backend) -> Self::Backend {
+ storage
+ }
+
+ fn finish(self, _: Self::Backend) {}
+}
+
+struct SqliteFactory {
+ path: PathBuf,
+}
+
+impl BackendFactory for SqliteFactory {
+ type Backend = SqliteStorage;
+
+ fn create() -> (Self, Self::Backend) {
+ static NEXT_DATABASE: AtomicU64 = AtomicU64::new(1);
+ let id = NEXT_DATABASE.fetch_add(1, Ordering::Relaxed);
+ let path = std::env::temp_dir().join(format!(
+ "cache-turso-shared-conformance-{}-{id}.db",
+ std::process::id()
+ ));
+ let _ = std::fs::remove_file(&path);
+ let storage = SqliteStorage::open(&path, "shared-conformance").unwrap();
+ (Self { path }, storage)
+ }
+
+ fn reopen(&mut self, storage: Self::Backend) -> Self::Backend {
+ drop(storage);
+ SqliteStorage::open(&self.path, "shared-conformance").unwrap()
+ }
+
+ fn finish(self, storage: Self::Backend) {
+ drop(storage);
+ std::fs::remove_file(self.path).unwrap();
+ }
+}
+
+struct TursoFactory {
+ database: TursoMemoryDatabase,
+}
+
+impl BackendFactory for TursoFactory {
+ type Backend = TursoStorage;
+
+ fn create() -> (Self, Self::Backend) {
+ let database = TursoMemoryDatabase::new("shared-conformance.db");
+ let storage = database.open("shared-conformance").unwrap();
+ (Self { database }, storage)
+ }
+
+ fn reopen(&mut self, storage: Self::Backend) -> Self::Backend {
+ assert_eq!(
+ storage.try_close().unwrap(),
+ TursoStorageCloseOutcome::Healthy
+ );
+ self.database.open("shared-conformance").unwrap()
+ }
+
+ fn finish(self, storage: Self::Backend) {
+ assert_eq!(
+ storage.try_close().unwrap(),
+ TursoStorageCloseOutcome::Healthy
+ );
+ }
+}
+
+fn key(value: &str) -> EntityKey<'static> {
+ EntityKey(value.to_owned().into())
+}
+
+fn record(value: &str) -> Record {
+ let mut record = Record::default();
+ record
+ .fields
+ .insert("value".into(), CacheValue::String(value.into()));
+ record
+}
+
+fn queued(label: &str) -> NewQueuedMutation {
+ NewQueuedMutation {
+ mutation: StoredMutation::new(
+ MutationRequest {
+ query: format!("mutation {label} {{ update {{ id }} }}"),
+ operation_name: Some(label.into()),
+ variables_json: "{}".into(),
+ identity: None,
+ },
+ 1,
+ ),
+ optimistic: PersistedOptimisticLayer {
+ optimistic_data_json: "{}".into(),
+ normalized_updates: RecordUpdates::default(),
+ },
+ }
+}
+
+fn fully_populated_queued() -> NewQueuedMutation {
+ NewQueuedMutation {
+ mutation: StoredMutation {
+ request: MutationRequest {
+ query: "mutation Full($id: ID!) { update(id: $id) { id } }".into(),
+ operation_name: Some("Full".into()),
+ variables_json: r#"{"id":"full"}"#.into(),
+ identity: Some("identity-witness".into()),
+ },
+ attempt_count: 7,
+ next_attempt_at_ms: Some(-2),
+ lease_owner: Some("expired-owner".into()),
+ lease_generation: 11,
+ lease_expires_at_ms: Some(-1),
+ last_error: Some("previous retry".into()),
+ created_at_ms: -3,
+ },
+ optimistic: PersistedOptimisticLayer {
+ optimistic_data_json: r#"{"update":{"id":"full"}}"#.into(),
+ normalized_updates: RecordUpdates::from([(
+ key("Optimistic:full"),
+ record("optimistic-full"),
+ )]),
+ },
+ }
+}
+
+fn token(owner: &str, generation: u64) -> MutationClaimToken {
+ MutationClaimToken {
+ owner: owner.into(),
+ generation,
+ }
+}
+
+fn claim_request(owner: &str, now_ms: i64, lease_expires_at_ms: i64) -> MutationClaimRequest {
+ MutationClaimRequest {
+ owner: owner.into(),
+ now_ms,
+ lease_expires_at_ms,
+ }
+}
+
+async fn scan_keys<S: Storage>(
+ storage: &S,
+ type_names: &[String],
+ after: Option<&EntityKey<'static>>,
+ limit: usize,
+) -> Vec<String> {
+ storage
+ .scan_records(type_names, after, limit)
+ .await
+ .unwrap()
+ .into_iter()
+ .map(|(key, _)| key.as_ref().to_owned())
+ .collect()
+}
+
+async fn record_contract<S: Storage>(storage: &mut S) {
+ storage
+ .put_batch(vec![
+ (key("ROOT_QUERY"), record("root")),
+ (key("__meta:identity"), record("meta")),
+ (key("Thing:"), record("empty-id")),
+ (key("Type:9"), record("type-9")),
+ (key("Type0:1"), record("type0-1")),
+ (key("Other:1"), record("other")),
+ (key("Type:0"), record("type-0")),
+ (key("Type0:0"), record("type0-first")),
+ (key("Type:a"), record("type-a")),
+ (key("Type:a:colon"), record("colon-id")),
+ (key("Type:a:colon:again"), record("multiple-colon-id")),
+ (key("Type0:0"), record("type0-last")),
+ ])
+ .await
+ .unwrap();
+
+ let aligned = storage
+ .get_batch(&[
+ key("Missing:leading"),
+ key("ROOT_QUERY"),
+ key("__meta:identity"),
+ key("Thing:"),
+ key("Type:a:colon:again"),
+ key("Missing:middle"),
+ key("Type0:0"),
+ key("Type0:0"),
+ key("Missing:trailing"),
+ ])
+ .await
+ .unwrap();
+ assert_eq!(
+ aligned,
+ vec![
+ None,
+ Some(record("root")),
+ Some(record("meta")),
+ Some(record("empty-id")),
+ Some(record("multiple-colon-id")),
+ None,
+ Some(record("type0-last")),
+ Some(record("type0-last")),
+ None,
+ ]
+ );
+
+ let names = ["Type".to_owned(), "Type0".to_owned(), "Type".to_owned()];
+ let mut rust_sorted = [
+ key("Type:9"),
+ key("Type0:1"),
+ key("Type:0"),
+ key("Type0:0"),
+ key("Type:a"),
+ key("Type:a:colon"),
+ key("Type:a:colon:again"),
+ ];
+ rust_sorted.sort();
+ let expected = rust_sorted
+ .iter()
+ .map(|key| key.as_ref().to_owned())
+ .collect::<Vec<_>>();
+ assert!(scan_keys(storage, &[], None, 10).await.is_empty());
+ assert!(scan_keys(storage, &names, None, 0).await.is_empty());
+ assert_eq!(scan_keys(storage, &names, None, 10).await, expected);
+ assert_eq!(
+ scan_keys(storage, &names, Some(&key("A:0")), 10).await,
+ expected
+ );
+ assert_eq!(
+ scan_keys(storage, &names, Some(&key("Type0:0")), 10).await,
+ [
+ "Type0:1",
+ "Type:0",
+ "Type:9",
+ "Type:a",
+ "Type:a:colon",
+ "Type:a:colon:again",
+ ]
+ );
+ assert_eq!(
+ scan_keys(storage, &names, Some(&key("Type0:0z")), 10).await,
+ [
+ "Type0:1",
+ "Type:0",
+ "Type:9",
+ "Type:a",
+ "Type:a:colon",
+ "Type:a:colon:again",
+ ]
+ );
+ assert_eq!(
+ scan_keys(storage, &names, Some(&key("Type0:1")), 10).await,
+ [
+ "Type:0",
+ "Type:9",
+ "Type:a",
+ "Type:a:colon",
+ "Type:a:colon:again",
+ ]
+ );
+ assert_eq!(
+ scan_keys(storage, &names, Some(&key("Type0:zz")), 10).await,
+ [
+ "Type:0",
+ "Type:9",
+ "Type:a",
+ "Type:a:colon",
+ "Type:a:colon:again",
+ ]
+ );
+ assert_eq!(
+ scan_keys(storage, &names, Some(&key("Type:0")), 1).await,
+ ["Type:9"]
+ );
+ assert_eq!(
+ scan_keys(storage, &names, Some(&key("Type:9")), 10).await,
+ ["Type:a", "Type:a:colon", "Type:a:colon:again"]
+ );
+ assert_eq!(
+ scan_keys(storage, &names, Some(&key("Type:a")), 10).await,
+ ["Type:a:colon", "Type:a:colon:again"]
+ );
+ assert_eq!(
+ scan_keys(storage, &names, Some(&key("Type:a:colon")), 10).await,
+ ["Type:a:colon:again"]
+ );
+ assert!(
+ scan_keys(storage, &names, Some(&key("Type:a:colon:again")), 10,)
+ .await
+ .is_empty()
+ );
+ assert!(
+ scan_keys(storage, &names, Some(&key("Z:9")), 10)
+ .await
+ .is_empty()
+ );
+
+ for limit in [1, 2] {
+ let mut cursor = None;
+ let mut paged = Vec::new();
+ loop {
+ let page = storage
+ .scan_records(&names, cursor.as_ref(), limit)
+ .await
+ .unwrap();
+ assert!(page.len() <= limit);
+ let Some((last, _)) = page.last() else {
+ break;
+ };
+ cursor = Some(last.clone());
+ paged.extend(page.into_iter().map(|(key, _)| key.as_ref().to_owned()));
+ }
+ assert_eq!(paged, expected);
+ }
+
+ storage
+ .delete_batch(&[key("Missing:delete"), key("Type:a"), key("Type:a")])
+ .await
+ .unwrap();
+ assert_eq!(storage.get_batch(&[key("Type:a")]).await.unwrap(), [None]);
+ storage.delete_batch(&[]).await.unwrap();
+ storage
+ .put_batch(vec![(key("Type:a"), record("restored"))])
+ .await
+ .unwrap();
+}
+
+async fn reopen_contract<F: BackendFactory>(
+ factory: &mut F,
+ mut storage: F::Backend,
+) -> F::Backend {
+ let first_entry = fully_populated_queued();
+ let second_entry = queued("ReopenSecond");
+ let first = storage.enqueue_mutation(first_entry.clone()).await.unwrap();
+ let second = storage
+ .enqueue_mutation(second_entry.clone())
+ .await
+ .unwrap();
+ assert!(second > first);
+
+ let mut storage = factory.reopen(storage);
+ assert_eq!(
+ storage
+ .get_batch(&[key("ROOT_QUERY"), key("Type:9"), key("Type:a:colon:again"),])
+ .await
+ .unwrap(),
+ [
+ Some(record("root")),
+ Some(record("type-9")),
+ Some(record("multiple-colon-id")),
+ ]
+ );
+ let loaded = storage.load_mutation_queue().await.unwrap();
+ assert_eq!(
+ loaded.iter().map(|entry| entry.id).collect::<Vec<_>>(),
+ [first, second]
+ );
+ assert_eq!(loaded[0].mutation, first_entry.mutation);
+ assert_eq!(loaded[0].optimistic, first_entry.optimistic);
+ assert_eq!(loaded[1].mutation, second_entry.mutation);
+ assert_eq!(loaded[1].optimistic, second_entry.optimistic);
+
+ let first_claim = storage
+ .claim_next_mutation(claim_request("reopen-first", 0, 1))
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(first_claim.queued.mutation.attempt_count, 8);
+ assert_eq!(first_claim.lease_generation, 12);
+ assert!(
+ storage
+ .discard_mutation(first, token("reopen-first", 12))
+ .await
+ .unwrap()
+ );
+ let second_claim = storage
+ .claim_next_mutation(claim_request("reopen-second", 0, 1))
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(second_claim.queued.id, second);
+ assert!(
+ storage
+ .discard_mutation(
+ second,
+ token("reopen-second", second_claim.lease_generation),
+ )
+ .await
+ .unwrap()
+ );
+ assert!(storage.load_mutation_queue().await.unwrap().is_empty());
+ assert_eq!(
+ storage.get_batch(&[key("Type:9")]).await.unwrap(),
+ [Some(record("type-9"))],
+ "discard must not change existing records"
+ );
+ storage
+}
+
+async fn queue_contract<S: Storage>(storage: &mut S) {
+ assert!(storage.load_mutation_queue().await.unwrap().is_empty());
+ assert_eq!(
+ storage.queue_diagnostics().await.unwrap(),
+ cache_core::store::QueueDiagnostics {
+ availability: cache_core::store::QueueDiagnosticsAvailability::Available,
+ depth: 0,
+ oldest_created_at_ms: None,
+ }
+ );
+ assert!(
+ storage
+ .claim_next_mutation(claim_request("empty", 0, 1))
+ .await
+ .unwrap()
+ .is_none()
+ );
+
+ let absent = token("absent", 1);
+ assert!(
+ !storage
+ .defer_mutation(999, absent.clone(), 2, "absent".into())
+ .await
+ .unwrap()
+ );
+ assert!(
+ !storage
+ .complete_mutation(999, absent.clone(), Vec::new())
+ .await
+ .unwrap()
+ );
+ assert!(!storage.discard_mutation(999, absent).await.unwrap());
+
+ let first = storage.enqueue_mutation(queued("First")).await.unwrap();
+ let second = storage.enqueue_mutation(queued("Second")).await.unwrap();
+ assert!(second > first);
+ assert_eq!(
+ storage.queue_diagnostics().await.unwrap(),
+ cache_core::store::QueueDiagnostics {
+ availability: cache_core::store::QueueDiagnosticsAvailability::Available,
+ depth: 2,
+ oldest_created_at_ms: Some(1),
+ }
+ );
+ let first_claim = storage
+ .claim_next_mutation(claim_request("runner-a", 1, 10))
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(first_claim.queued.id, first);
+ assert_eq!(first_claim.queued.mutation.attempt_count, 1);
+ assert_eq!(first_claim.lease_generation, 1);
+ assert!(
+ storage
+ .claim_next_mutation(claim_request("runner-b", 9, 20))
+ .await
+ .unwrap()
+ .is_none(),
+ "a leased strict head must block the second row"
+ );
+ let expired_reclaim = storage
+ .claim_next_mutation(claim_request("runner-b", 10, 15))
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(expired_reclaim.queued.id, first);
+ assert_eq!(expired_reclaim.queued.mutation.attempt_count, 2);
+ assert_eq!(expired_reclaim.lease_generation, 2);
+ assert!(
+ !storage
+ .defer_mutation(
+ first,
+ token("runner-a", first_claim.lease_generation),
+ 20,
+ "stale".into(),
+ )
+ .await
+ .unwrap()
+ );
+ assert!(
+ !storage
+ .discard_mutation(first, token("runner-a", first_claim.lease_generation))
+ .await
+ .unwrap()
+ );
+ assert!(
+ storage
+ .defer_mutation(
+ first,
+ token("runner-b", expired_reclaim.lease_generation),
+ 20,
+ "retry".into(),
+ )
+ .await
+ .unwrap()
+ );
+ let deferred = storage.load_mutation_queue().await.unwrap();
+ assert_eq!(deferred.len(), 2);
+ assert_eq!(deferred[0].id, first);
+ assert_eq!(deferred[0].mutation.attempt_count, 2);
+ assert_eq!(deferred[0].mutation.next_attempt_at_ms, Some(20));
+ assert_eq!(deferred[0].mutation.lease_owner, None);
+ assert_eq!(deferred[0].mutation.lease_expires_at_ms, None);
+ assert_eq!(deferred[0].mutation.lease_generation, 2);
+ assert_eq!(deferred[0].mutation.last_error.as_deref(), Some("retry"));
+ assert!(
+ storage
+ .claim_next_mutation(claim_request("runner-c", 19, 30))
+ .await
+ .unwrap()
+ .is_none(),
+ "a deferred strict head must block the second row"
+ );
+
+ let retry_claim = storage
+ .claim_next_mutation(claim_request("runner-c", 20, 30))
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(retry_claim.queued.id, first);
+ assert_eq!(retry_claim.queued.mutation.attempt_count, 3);
+ assert_eq!(retry_claim.lease_generation, 3);
+ assert!(
+ !storage
+ .discard_mutation(first, token("runner-b", expired_reclaim.lease_generation))
+ .await
+ .unwrap()
+ );
+ assert!(
+ storage
+ .discard_mutation(first, token("runner-c", retry_claim.lease_generation))
+ .await
+ .unwrap()
+ );
+
+ let second_claim = storage
+ .claim_next_mutation(claim_request("runner-d", 20, 25))
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(second_claim.queued.id, second);
+ assert_eq!(second_claim.queued.mutation.attempt_count, 1);
+ assert!(
+ storage
+ .defer_mutation(
+ second,
+ token("runner-d", second_claim.lease_generation),
+ 30,
+ "second retry".into(),
+ )
+ .await
+ .unwrap()
+ );
+ assert!(
+ storage
+ .claim_next_mutation(claim_request("runner-e", 29, 40))
+ .await
+ .unwrap()
+ .is_none()
+ );
+ let second_retry = storage
+ .claim_next_mutation(claim_request("runner-e", 30, 40))
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(second_retry.queued.id, second);
+ assert_eq!(second_retry.queued.mutation.attempt_count, 2);
+ assert!(
+ !storage
+ .complete_mutation(
+ second,
+ token("runner-d", second_claim.lease_generation),
+ vec![(key("Result:stale"), record("must-not-write"))],
+ )
+ .await
+ .unwrap()
+ );
+ assert_eq!(
+ storage.get_batch(&[key("Result:stale")]).await.unwrap(),
+ [None]
+ );
+ assert!(
+ storage
+ .complete_mutation(
+ second,
+ token("runner-e", second_retry.lease_generation),
+ vec![(key("Result:complete"), record("committed"))],
+ )
+ .await
+ .unwrap()
+ );
+ assert_eq!(
+ storage.get_batch(&[key("Result:complete")]).await.unwrap(),
+ [Some(record("committed"))]
+ );
+ assert!(storage.load_mutation_queue().await.unwrap().is_empty());
+ assert!(
+ storage
+ .claim_next_mutation(claim_request("empty-again", 40, 50))
+ .await
+ .unwrap()
+ .is_none()
+ );
+}
+
+async fn clear_contract<S: Storage>(storage: &mut S) {
+ let before_clear = storage.enqueue_mutation(queued("Clear")).await.unwrap();
+ storage.clear().await.unwrap();
+ assert!(storage.load_mutation_queue().await.unwrap().is_empty());
+ assert_eq!(
+ storage
+ .get_batch(&[
+ key("ROOT_QUERY"),
+ key("__meta:identity"),
+ key("Thing:"),
+ key("Type0:0"),
+ key("Type:9"),
+ key("Other:1"),
+ key("Result:complete"),
+ ])
+ .await
+ .unwrap(),
+ [None, None, None, None, None, None, None]
+ );
+ assert!(
+ storage
+ .claim_next_mutation(claim_request("after-clear", 50, 60))
+ .await
+ .unwrap()
+ .is_none()
+ );
+ let after_clear = storage
+ .enqueue_mutation(queued("AfterClear"))
+ .await
+ .unwrap();
+ assert!(after_clear > before_clear);
+ storage.clear().await.unwrap();
+ assert!(storage.load_mutation_queue().await.unwrap().is_empty());
+}
+
+async fn common_contract<F: BackendFactory>(
+ factory: &mut F,
+ mut storage: F::Backend,
+) -> F::Backend {
+ record_contract(&mut storage).await;
+ let mut storage = reopen_contract(factory, storage).await;
+ queue_contract(&mut storage).await;
+ clear_contract(&mut storage).await;
+ storage
+}
+
+fn run<F: BackendFactory>() {
+ let (mut factory, storage) = F::create();
+ let storage = block_on(common_contract(&mut factory, storage));
+ factory.finish(storage);
+}
+
+#[test]
+fn in_memory_storage_satisfies_shared_contract() {
+ run::<InMemoryFactory>();
+}
+
+#[test]
+fn sqlite_storage_satisfies_shared_contract() {
+ run::<SqliteFactory>();
+}
+
+#[test]
+fn turso_storage_satisfies_shared_contract() {
+ run::<TursoFactory>();
+}
diff --git a/crates/client/cache-turso/tests/storage_conformance.rs b/crates/client/cache-turso/tests/storage_conformance.rs
new file mode 100644
index 0000000000..8d0fc73afe
--- /dev/null
+++ b/crates/client/cache-turso/tests/storage_conformance.rs
@@ -0,0 +1,515 @@
+#![cfg(not(target_arch = "wasm32"))]
+
+use cache_core::meta::TYPES;
+use cache_core::normalize::RecordUpdates;
+use cache_core::queue::{
+ MutationClaimRequest, MutationClaimToken, MutationRequest, NewQueuedMutation,
+ PersistedOptimisticLayer, StoredMutation,
+};
+use cache_core::store::Storage;
+use cache_core::value::{CacheValue, EntityKey, Record};
+use cache_turso::{TursoMemoryDatabase, TursoStorage};
+use pollster::block_on;
+
+fn key(value: &str) -> EntityKey<'static> {
+ EntityKey(value.to_owned().into())
+}
+
+fn record(value: &str) -> Record {
+ let mut record = Record::default();
+ record
+ .fields
+ .insert("value".into(), CacheValue::String(value.into()));
+ record
+}
+
+fn queued(label: &str, created_at_ms: i64) -> NewQueuedMutation {
+ let mut update = Record::default();
+ update
+ .fields
+ .insert("value".into(), CacheValue::String(label.into()));
+ NewQueuedMutation {
+ mutation: StoredMutation {
+ request: MutationRequest {
+ query: format!("mutation {label} {{ update {{ id }} }}"),
+ operation_name: Some(label.into()),
+ variables_json: format!(r#"{{"label":"{label}"}}"#),
+ identity: Some("identity-witness".into()),
+ },
+ attempt_count: 7,
+ next_attempt_at_ms: None,
+ lease_owner: None,
+ lease_generation: 11,
+ lease_expires_at_ms: None,
+ last_error: Some("previous retry".into()),
+ created_at_ms,
+ },
+ optimistic: PersistedOptimisticLayer {
+ optimistic_data_json: format!(r#"{{"update":{{"label":"{label}"}}}}"#),
+ normalized_updates: RecordUpdates::from([(key("Thing:1"), update)]),
+ },
+ }
+}
+
+fn claim(owner: &str, generation: u64) -> MutationClaimToken {
+ MutationClaimToken {
+ owner: owner.into(),
+ generation,
+ }
+}
+
+#[test]
+fn compound_keys_batches_duplicates_and_checked_inputs_conform() {
+ block_on(async {
+ let mut storage = TursoStorage::open_in_memory("scope-batches").unwrap();
+ let valid = [
+ "ROOT_QUERY",
+ "GraphqlSoupDocument:doc-1",
+ "GraphqlSoupDocument:tenant:doc-1",
+ "__meta:identity",
+ "Thing:",
+ ];
+ storage
+ .put_batch(
+ valid
+ .iter()
+ .enumerate()
+ .map(|(index, value)| (key(value), record(&index.to_string())))
+ .collect(),
+ )
+ .await
+ .unwrap();
+
+ let requested = [
+ key("Missing:leading"),
+ key(valid[1]),
+ key("Missing:middle"),
+ key(valid[1]),
+ key(valid[4]),
+ key("Missing:trailing"),
+ ];
+ let values = storage.get_batch(&requested).await.unwrap();
+ assert_eq!(values.len(), requested.len());
+ assert!(values[0].is_none());
+ assert_eq!(values[1], Some(record("1")));
+ assert!(values[2].is_none());
+ assert_eq!(values[3], values[1]);
+ assert_eq!(values[4], Some(record("4")));
+ assert!(values[5].is_none());
+
+ storage
+ .put_batch(vec![
+ (key("Duplicate:1"), record("first")),
+ (key("Duplicate:1"), record("last")),
+ ])
+ .await
+ .unwrap();
+ assert_eq!(
+ storage.get_batch(&[key("Duplicate:1")]).await.unwrap(),
+ vec![Some(record("last"))]
+ );
+ storage
+ .delete_batch(&[
+ key("Missing:delete"),
+ key("Duplicate:1"),
+ key("Duplicate:1"),
+ ])
+ .await
+ .unwrap();
+ assert_eq!(
+ storage.get_batch(&[key("Duplicate:1")]).await.unwrap(),
+ vec![None]
+ );
+
+ for invalid in ["", "Colonless", ":id", "ROOT_QUERY:"] {
+ let error = storage
+ .put_batch(vec![(key(invalid), record("invalid"))])
+ .await
+ .unwrap_err();
+ assert!(!error.requires_physical_reset());
+ }
+ storage.try_close().unwrap();
+ });
+}
+
+#[test]
+fn canonical_binary_scan_has_global_exclusive_cursor_and_dynamic_in() {
+ block_on(async {
+ let mut storage = TursoStorage::open_in_memory("scope-scan").unwrap();
+ let values = [
+ "ROOT_QUERY",
+ "Type:9",
+ "Type0:1",
+ "Type:a:colon",
+ "Type:tenant:item",
+ "Other:1",
+ "__meta:identity",
+ ];
+ storage
+ .put_batch(
+ values
+ .iter()
+ .map(|value| (key(value), record(value)))
+ .collect(),
+ )
+ .await
+ .unwrap();
+
+ assert!(
+ storage
+ .scan_records(&[], None, 10)
+ .await
+ .unwrap()
+ .is_empty()
+ );
+ assert!(
+ storage
+ .scan_records(&["Type".into()], None, 0)
+ .await
+ .unwrap()
+ .is_empty()
+ );
+ let names = ["Type0".into(), "Type".into(), "Type".into()];
+ let expected = ["Type0:1", "Type:9", "Type:a:colon", "Type:tenant:item"];
+ let all = storage.scan_records(&names, None, 20).await.unwrap();
+ assert_eq!(
+ all.iter().map(|(key, _)| key.as_ref()).collect::<Vec<_>>(),
+ expected
+ );
+
+ let mut cursor = None;
+ let mut paged = Vec::new();
+ loop {
+ let page = storage
+ .scan_records(&names, cursor.as_ref(), 1)
+ .await
+ .unwrap();
+ let Some((last, _)) = page.last() else {
+ break;
+ };
+ cursor = Some(last.clone());
+ paged.extend(page.into_iter().map(|(key, _)| key));
+ }
+ assert_eq!(
+ paged.iter().map(EntityKey::as_ref).collect::<Vec<_>>(),
+ expected
+ );
+ assert!(
+ storage
+ .scan_records(&names, Some(&key("Unselected:zz")), 2)
+ .await
+ .unwrap()
+ .is_empty()
+ );
+
+ let maximum_types = TYPES
+ .iter()
+ .map(|metadata| metadata.name.to_owned())
+ .collect::<Vec<_>>();
+ storage
+ .scan_records(&maximum_types, None, usize::MAX.min(i64::MAX as usize))
+ .await
+ .unwrap();
+ storage.try_close().unwrap();
+ });
+}
+
+#[test]
+fn queue_preserves_every_field_order_and_reopen_state() {
+ block_on(async {
+ let database = TursoMemoryDatabase::new("queue-reopen.db");
+ let mut storage = database.open("scope-queue-reopen").unwrap();
+ let mut first_entry = queued("First", 100);
+ first_entry.mutation.next_attempt_at_ms = Some(150);
+ first_entry.mutation.lease_owner = Some("reopen-owner".into());
+ first_entry.mutation.lease_expires_at_ms = Some(175);
+ let second_entry = NewQueuedMutation {
+ mutation: StoredMutation::new(
+ MutationRequest {
+ query: "mutation Second { update { id } }".into(),
+ operation_name: None,
+ variables_json: "{}".into(),
+ identity: None,
+ },
+ -20,
+ ),
+ optimistic: PersistedOptimisticLayer {
+ optimistic_data_json: "null".into(),
+ normalized_updates: RecordUpdates::default(),
+ },
+ };
+ let first = storage.enqueue_mutation(first_entry.clone()).await.unwrap();
+ let second = storage
+ .enqueue_mutation(second_entry.clone())
+ .await
+ .unwrap();
+ assert!(first > 0 && second > first);
+ storage.try_close().unwrap();
+
+ let storage = database.open("scope-queue-reopen").unwrap();
+ let loaded = storage.load_mutation_queue().await.unwrap();
+ assert_eq!(
+ loaded.iter().map(|entry| entry.id).collect::<Vec<_>>(),
+ vec![first, second]
+ );
+ assert_eq!(loaded[0].mutation, first_entry.mutation);
+ assert_eq!(loaded[0].optimistic, first_entry.optimistic);
+ assert_eq!(loaded[1].mutation, second_entry.mutation);
+ assert_eq!(loaded[1].optimistic, second_entry.optimistic);
+ storage.try_close().unwrap();
+ });
+}
+
+#[test]
+fn strict_head_retries_leases_and_fences_conform() {
+ block_on(async {
+ let mut storage = TursoStorage::open_in_memory("scope-leases").unwrap();
+ let mut first_entry = queued("First", 1);
+ first_entry.mutation.attempt_count = 0;
+ first_entry.mutation.lease_generation = 0;
+ first_entry.mutation.last_error = None;
+ first_entry.mutation.next_attempt_at_ms = Some(100);
+ let mut second_entry = queued("Second", 2);
+ second_entry.mutation.attempt_count = 0;
+ second_entry.mutation.lease_generation = 0;
+ second_entry.mutation.last_error = None;
+ let first = storage.enqueue_mutation(first_entry).await.unwrap();
+ let second = storage.enqueue_mutation(second_entry).await.unwrap();
+
+ assert!(
+ storage
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner-a".into(),
+ now_ms: 99,
+ lease_expires_at_ms: 150,
+ })
+ .await
+ .unwrap()
+ .is_none()
+ );
+ let first_claim = storage
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner-a".into(),
+ now_ms: 100,
+ lease_expires_at_ms: 150,
+ })
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(first_claim.queued.id, first);
+ assert_eq!(first_claim.queued.mutation.attempt_count, 1);
+ assert_eq!(first_claim.lease_generation, 1);
+ assert!(
+ storage
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner-b".into(),
+ now_ms: 149,
+ lease_expires_at_ms: 200,
+ })
+ .await
+ .unwrap()
+ .is_none()
+ );
+
+ let reclaimed = storage
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner-b".into(),
+ now_ms: 150,
+ lease_expires_at_ms: 250,
+ })
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(reclaimed.queued.id, first);
+ assert_eq!(reclaimed.queued.mutation.attempt_count, 2);
+ assert_eq!(reclaimed.lease_generation, 2);
+ assert!(
+ !storage
+ .defer_mutation(first, claim("runner-a", 1), 300, "stale".into())
+ .await
+ .unwrap()
+ );
+ assert!(
+ storage
+ .defer_mutation(first, claim("runner-b", 2), 300, "offline".into())
+ .await
+ .unwrap()
+ );
+ let deferred = storage.load_mutation_queue().await.unwrap();
+ assert_eq!(deferred[0].mutation.next_attempt_at_ms, Some(300));
+ assert_eq!(deferred[0].mutation.lease_owner, None);
+ assert_eq!(deferred[0].mutation.lease_expires_at_ms, None);
+ assert_eq!(deferred[0].mutation.lease_generation, 2);
+ assert_eq!(deferred[0].mutation.last_error.as_deref(), Some("offline"));
+ assert!(
+ storage
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner-c".into(),
+ now_ms: 299,
+ lease_expires_at_ms: 400,
+ })
+ .await
+ .unwrap()
+ .is_none()
+ );
+ let third_claim = storage
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner-c".into(),
+ now_ms: 300,
+ lease_expires_at_ms: 400,
+ })
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(third_claim.lease_generation, 3);
+ assert!(
+ !storage
+ .discard_mutation(first, claim("runner-b", 2))
+ .await
+ .unwrap()
+ );
+ assert!(
+ storage
+ .discard_mutation(first, claim("runner-c", 3))
+ .await
+ .unwrap()
+ );
+ let next = storage
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner-d".into(),
+ now_ms: 300,
+ lease_expires_at_ms: 500,
+ })
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(next.queued.id, second);
+ storage.try_close().unwrap();
+ });
+}
+
+#[test]
+fn complete_discard_clear_and_non_reused_ids_are_atomic_semantics() {
+ block_on(async {
+ let mut storage = TursoStorage::open_in_memory("scope-settlement").unwrap();
+ let first = storage
+ .enqueue_mutation(queued("Complete", 1))
+ .await
+ .unwrap();
+ let first_claim = storage
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner".into(),
+ now_ms: 1,
+ lease_expires_at_ms: 100,
+ })
+ .await
+ .unwrap()
+ .unwrap();
+ assert!(
+ !storage
+ .complete_mutation(
+ first,
+ claim("stale", first_claim.lease_generation),
+ vec![(key("Result:stale"), record("must-not-write"))],
+ )
+ .await
+ .unwrap()
+ );
+ assert_eq!(
+ storage.get_batch(&[key("Result:stale")]).await.unwrap(),
+ vec![None]
+ );
+ assert!(
+ storage
+ .complete_mutation(
+ first,
+ claim("runner", first_claim.lease_generation),
+ vec![
+ (key("Result:1"), record("first")),
+ (key("Result:1"), record("last")),
+ ],
+ )
+ .await
+ .unwrap()
+ );
+ assert_eq!(
+ storage.get_batch(&[key("Result:1")]).await.unwrap(),
+ vec![Some(record("last"))]
+ );
+ assert!(storage.load_mutation_queue().await.unwrap().is_empty());
+
+ let discarded = storage
+ .enqueue_mutation(queued("Discard", 2))
+ .await
+ .unwrap();
+ let discard_claim = storage
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "discarder".into(),
+ now_ms: 2,
+ lease_expires_at_ms: 100,
+ })
+ .await
+ .unwrap()
+ .unwrap();
+ assert!(
+ storage
+ .discard_mutation(
+ discarded,
+ claim("discarder", discard_claim.lease_generation),
+ )
+ .await
+ .unwrap()
+ );
+ assert_eq!(
+ storage.get_batch(&[key("Result:1")]).await.unwrap(),
+ vec![Some(record("last"))]
+ );
+
+ let before_clear = storage
+ .enqueue_mutation(queued("BeforeClear", 3))
+ .await
+ .unwrap();
+ storage.clear().await.unwrap();
+ assert!(storage.load_mutation_queue().await.unwrap().is_empty());
+ assert_eq!(
+ storage.get_batch(&[key("Result:1")]).await.unwrap(),
+ vec![None]
+ );
+ let after_clear = storage
+ .enqueue_mutation(queued("AfterClear", 4))
+ .await
+ .unwrap();
+ assert!(after_clear > before_clear);
+ storage.try_close().unwrap();
+ });
+}
+
+#[test]
+fn checked_rust_queue_values_are_rejected_before_transactions() {
+ block_on(async {
+ let mut storage = TursoStorage::open_in_memory("scope-numerics").unwrap();
+ let mut oversized = queued("Oversized", 1);
+ oversized.mutation.lease_generation = u64::MAX;
+ assert!(
+ !storage
+ .enqueue_mutation(oversized)
+ .await
+ .unwrap_err()
+ .requires_physical_reset()
+ );
+ assert!(
+ !storage
+ .discard_mutation(
+ u64::MAX,
+ MutationClaimToken {
+ owner: "runner".into(),
+ generation: 0,
+ },
+ )
+ .await
+ .unwrap_err()
+ .requires_physical_reset()
+ );
+ storage.try_close().unwrap();
+ });
+}
diff --git a/crates/client/cache-turso/tests/web.rs b/crates/client/cache-turso/tests/web.rs
new file mode 100644
index 0000000000..fa825a500f
--- /dev/null
+++ b/crates/client/cache-turso/tests/web.rs
@@ -0,0 +1,217 @@
+#![cfg(target_arch = "wasm32")]
+
+use cache_core::engine::{Engine, ReadResult};
+use cache_core::normalize::RecordUpdates;
+use cache_core::queue::{
+ MutationRequest, NewQueuedMutation, PersistedOptimisticLayer, StoredMutation,
+};
+use cache_core::store::Storage;
+use cache_core::value::{CacheValue, EntityKey, Record};
+use cache_turso::{HealthyTursoStorageClosed, TursoStorage, TursoStorageCloseOutcome};
+use turso_opfs::{OpenResult, OpfsOwner};
+use wasm_bindgen_test::*;
+
+wasm_bindgen_test_configure!(run_in_dedicated_worker);
+
+fn key(value: &str) -> EntityKey<'static> {
+ EntityKey(value.to_owned().into())
+}
+
+fn record(value: &str) -> Record {
+ let mut record = Record::default();
+ record
+ .fields
+ .insert("value".into(), CacheValue::String(value.into()));
+ record
+}
+
+fn healthy_close(outcome: TursoStorageCloseOutcome) -> HealthyTursoStorageClosed {
+ let TursoStorageCloseOutcome::Healthy(closed) = outcome else {
+ panic!("healthy browser storage unexpectedly required reset")
+ };
+ closed
+}
+
+fn queued() -> NewQueuedMutation {
+ NewQueuedMutation {
+ mutation: StoredMutation::new(
+ MutationRequest {
+ query: "mutation Browser { update { id } }".into(),
+ operation_name: Some("Browser".into()),
+ variables_json: "{}".into(),
+ identity: None,
+ },
+ 1,
+ ),
+ optimistic: PersistedOptimisticLayer {
+ optimistic_data_json: "{}".into(),
+ normalized_updates: RecordUpdates::default(),
+ },
+ }
+}
+
+const ENGINE_QUERY: &str = r#"
+query BrowserEngine {
+ user {
+ id
+ }
+}
+"#;
+
+fn engine_data() -> serde_json::Value {
+ serde_json::json!({"user": {"id": "browser-user"}})
+}
+
+#[wasm_bindgen_test(async)]
+async fn real_engine_over_opfs_consumes_storage_for_preserve_and_reset() {
+ let owner = OpfsOwner::acquire("cache-turso-wp06-engine.db")
+ .await
+ .unwrap()
+ .recovery_wipe()
+ .await
+ .unwrap();
+ let OpenResult::Ready(session) = owner.open().await.unwrap() else {
+ panic!("recovery wipe must produce a complete fresh pair")
+ };
+ let storage =
+ TursoStorage::from_opfs_session(session.connect().unwrap(), "engine-scope").unwrap();
+ let mut engine = Engine::new(storage);
+ engine
+ .write_query(
+ None,
+ ENGINE_QUERY,
+ Some("BrowserEngine"),
+ &serde_json::Map::new(),
+ &engine_data(),
+ None,
+ )
+ .await
+ .unwrap();
+ let owner = healthy_close(engine.into_storage().try_close().unwrap())
+ .preserve()
+ .unwrap();
+
+ let OpenResult::Ready(session) = owner.open().await.unwrap() else {
+ panic!("preserved engine database must reopen")
+ };
+ let storage =
+ TursoStorage::from_opfs_session(session.connect().unwrap(), "engine-scope").unwrap();
+ let mut engine = Engine::new(storage);
+ let ReadResult::Hit { data } = engine
+ .read_query(
+ None,
+ ENGINE_QUERY,
+ Some("BrowserEngine"),
+ &serde_json::Map::new(),
+ )
+ .await
+ .unwrap()
+ else {
+ panic!("reopened OPFS engine must read its durable record")
+ };
+ assert_eq!(data, engine_data());
+ let owner = healthy_close(engine.into_storage().try_close().unwrap())
+ .reset()
+ .await
+ .unwrap();
+
+ let OpenResult::Ready(session) = owner.open().await.unwrap() else {
+ panic!("reset engine database must reopen fresh")
+ };
+ let storage =
+ TursoStorage::from_opfs_session(session.connect().unwrap(), "engine-scope").unwrap();
+ let mut replacement = Engine::new(storage);
+ assert!(matches!(
+ replacement
+ .read_query(
+ None,
+ ENGINE_QUERY,
+ Some("BrowserEngine"),
+ &serde_json::Map::new(),
+ )
+ .await
+ .unwrap(),
+ ReadResult::Miss
+ ));
+ healthy_close(replacement.into_storage().try_close().unwrap())
+ .preserve()
+ .unwrap()
+ .release()
+ .await
+ .unwrap();
+}
+
+#[wasm_bindgen_test(async)]
+async fn incompatible_opfs_initialization_exposes_reset_only_and_cannot_preserve() {
+ let owner = OpfsOwner::acquire("cache-turso-wp06-browser.db")
+ .await
+ .unwrap()
+ .recovery_wipe()
+ .await
+ .unwrap();
+ let OpenResult::Ready(session) = owner.open().await.unwrap() else {
+ panic!("recovery wipe must produce a complete fresh pair")
+ };
+ let mut storage =
+ TursoStorage::from_opfs_session(session.connect().unwrap(), "browser-scope").unwrap();
+ storage
+ .put_batch(vec![
+ (key("ROOT_QUERY"), record("root")),
+ (key("Type0:1"), record("prefix")),
+ (key("Type:9"), record("ordinary")),
+ ])
+ .await
+ .unwrap();
+ let mutation_id = storage.enqueue_mutation(queued()).await.unwrap();
+ let owner = healthy_close(storage.try_close().unwrap())
+ .preserve()
+ .unwrap();
+
+ let OpenResult::Ready(session) = owner.open().await.unwrap() else {
+ panic!("preserved complete pair must reopen")
+ };
+ let storage =
+ TursoStorage::from_opfs_session(session.connect().unwrap(), "browser-scope").unwrap();
+ assert_eq!(
+ storage
+ .scan_records(&["Type".into(), "Type0".into()], None, 10)
+ .await
+ .unwrap()
+ .into_iter()
+ .map(|(key, _)| key.as_ref().to_owned())
+ .collect::<Vec<_>>(),
+ vec!["Type0:1", "Type:9"]
+ );
+ assert_eq!(
+ storage.load_mutation_queue().await.unwrap()[0].id,
+ mutation_id
+ );
+
+ let owner = healthy_close(storage.try_close().unwrap())
+ .preserve()
+ .unwrap();
+ let OpenResult::Ready(session) = owner.open().await.unwrap() else {
+ panic!("preserved complete pair must reopen for compatibility validation")
+ };
+ let failure =
+ TursoStorage::from_opfs_session(session.connect().unwrap(), "wrong-browser-scope")
+ .unwrap_err();
+ assert!(failure.error().requires_physical_reset());
+ let owner = failure.reset().await.unwrap();
+ let OpenResult::Ready(session) = owner.open().await.unwrap() else {
+ panic!("physical reset must recreate a complete fresh pair")
+ };
+ let storage =
+ TursoStorage::from_opfs_session(session.connect().unwrap(), "browser-scope").unwrap();
+ assert!(storage.load_mutation_queue().await.unwrap().is_empty());
+ assert_eq!(
+ storage.get_batch(&[key("Type:9")]).await.unwrap(),
+ vec![None]
+ );
+ healthy_close(storage.try_close().unwrap())
+ .preserve()
+ .unwrap()
+ .release()
+ .await
+ .unwrap();
+}
diff --git a/crates/client/cache-wasm/Cargo.toml b/crates/client/cache-wasm/Cargo.toml
index 8405d0bb76..799c1722d9 100644
--- a/crates/client/cache-wasm/Cargo.toml
+++ b/crates/client/cache-wasm/Cargo.toml
@@ -2,7 +2,11 @@
edition = "2024"
name = "cache-wasm"
publish = false
-version = "0.3.2"
+version = "0.4.0"
+
+[features]
+default = []
+browser-test-hooks = ["cache-turso/browser-test-hooks"]
[lib]
crate-type = ["cdylib", "rlib"]
@@ -17,22 +21,22 @@ wasm-opt = false
demangle-name-section = true
dwarf-debug-info = true
-# Browser-only wasm-bindgen shell around the engine + IDB storage. Like
-# cache-idb, it compiles to an empty shell off-wasm so workspace `cargo test`
-# stays green.
+# Browser-only wasm-bindgen shell around the engine + Turso OPFS storage. It
+# compiles to an empty shell off-wasm so workspace `cargo test` stays green.
[dependencies]
cache-core = { path = "../cache-core" }
[target.'cfg(target_arch = "wasm32")'.dependencies]
async-lock = { workspace = true }
-cache-idb = { path = "../cache-idb" }
+cache-turso = { path = "../cache-turso" }
js-sys = { workspace = true }
serde = { workspace = true }
serde-wasm-bindgen = { workspace = true }
serde_json = { workspace = true }
+turso-opfs = { path = "../turso-opfs" }
wasm-bindgen = { workspace = true }
wasm-bindgen-futures = { workspace = true }
[target.'cfg(target_arch = "wasm32")'.dev-dependencies]
-wasm-bindgen-test = "0.3"
+wasm-bindgen-test = { workspace = true }
diff --git a/crates/client/cache-wasm/src/lib.rs b/crates/client/cache-wasm/src/lib.rs
index db23b1f3d5..f753347600 100644
--- a/crates/client/cache-wasm/src/lib.rs
+++ b/crates/client/cache-wasm/src/lib.rs
@@ -1,4 +1,4 @@
-//! wasm-bindgen shell around the cache engine + IndexedDB storage.
+//! wasm-bindgen shell around the cache engine + Turso OPFS storage.
//!
//! Exposes a `CacheEngine` class to the JS worker glue
//! (`apps/web/src/lib/graphql-cache/`). All methods return Promises; the
diff --git a/crates/client/cache-wasm/src/shell.rs b/crates/client/cache-wasm/src/shell.rs
index 01083e203b..eb7bcfc3b6 100644
--- a/crates/client/cache-wasm/src/shell.rs
+++ b/crates/client/cache-wasm/src/shell.rs
@@ -1,20 +1,36 @@
use async_lock::Mutex;
+use cache_core::codec::cache_database_name;
use cache_core::deps::OpId;
-use cache_core::engine::{BeginOptimisticWrite, Engine, InitialClaimOutcome, ReadResult};
+use cache_core::engine::{
+ BeginOptimisticWrite, Engine, EngineError, InitialClaimOutcome, ReadResult,
+};
use cache_core::entity_resolver::EntityResolver;
use cache_core::link_patch::{OptimisticLinkPatch, QueryRevalidation};
use cache_core::query_inspection::QueryInspection;
use cache_core::queue::{ClaimedMutation, MutationClaimRequest, MutationClaimToken};
use cache_core::record_selection::{RecordCursor, RecordSelection};
+use cache_core::store::QueueDiagnosticsAvailability;
use cache_core::value::EntityKey;
-use cache_idb::IdbStorage;
+use cache_turso::{
+ PhysicalResetReason, TursoStorage, TursoStorageCloseOutcome, TursoStorageError,
+ TursoStorageOpenOutcome,
+};
use serde::{Deserialize, Serialize};
use std::cell::RefCell;
use std::collections::HashMap;
use std::rc::Rc;
+use turso_opfs::{OpenResult, OpfsOwner};
use wasm_bindgen::prelude::*;
use wasm_bindgen_futures::future_to_promise;
+#[cfg(test)]
+mod test;
+#[cfg(test)]
+mod test_storage;
+
+#[cfg(test)]
+use test_storage::{BrowserStorage, TestStorageFault};
+
/// Interns host-side string operation ids to engine `u64` ids.
#[derive(Default)]
struct OpInterner {
@@ -55,6 +71,49 @@ enum JsReadResult {
Miss,
}
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum CacheOpenOutcome {
+ OpenedExisting,
+ OpenedNew,
+ ResetIncompatible,
+ ResetCorrupt,
+ ResetStorageUncertain,
+}
+
+impl CacheOpenOutcome {
+ const fn as_str(self) -> &'static str {
+ match self {
+ Self::OpenedExisting => "opened-existing",
+ Self::OpenedNew => "opened-new",
+ Self::ResetIncompatible => "reset-incompatible",
+ Self::ResetCorrupt => "reset-corrupt",
+ Self::ResetStorageUncertain => "reset-storage-uncertain",
+ }
+ }
+}
+
+impl From<TursoStorageOpenOutcome> for CacheOpenOutcome {
+ fn from(outcome: TursoStorageOpenOutcome) -> Self {
+ match outcome {
+ TursoStorageOpenOutcome::OpenedExisting => Self::OpenedExisting,
+ TursoStorageOpenOutcome::OpenedNew => Self::OpenedNew,
+ }
+ }
+}
+
+fn recovery_outcome(reason: PhysicalResetReason) -> CacheOpenOutcome {
+ match reason {
+ PhysicalResetReason::Compatibility => CacheOpenOutcome::ResetIncompatible,
+ PhysicalResetReason::Corruption
+ | PhysicalResetReason::Codec
+ | PhysicalResetReason::Invariant
+ | PhysicalResetReason::Integrity => CacheOpenOutcome::ResetCorrupt,
+ PhysicalResetReason::StorageFull
+ | PhysicalResetReason::TransactionOutcomeUncertain
+ | PhysicalResetReason::Io => CacheOpenOutcome::ResetStorageUncertain,
+ }
+}
+
#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct JsWriteResult {
@@ -140,36 +199,355 @@ fn parse_timestamp(value: f64, label: &str) -> Result<i64, JsValue> {
Ok(value as i64)
}
+#[cfg(not(test))]
+type BrowserStorage = TursoStorage;
+type BrowserEngine = Engine<BrowserStorage>;
+
+#[cfg(not(test))]
+fn wrap_storage(storage: TursoStorage) -> BrowserStorage {
+ storage
+}
+
+#[cfg(test)]
+fn wrap_storage(storage: TursoStorage) -> BrowserStorage {
+ BrowserStorage::new(storage)
+}
+
+#[cfg(not(test))]
+fn unwrap_storage(storage: BrowserStorage) -> TursoStorage {
+ storage
+}
+
+#[cfg(test)]
+fn unwrap_storage(storage: BrowserStorage) -> TursoStorage {
+ storage.into_inner()
+}
+
+struct CacheState {
+ engine: Option<BrowserEngine>,
+ scope: String,
+ hot_capacity: Option<u32>,
+ reset_required: bool,
+}
+
+impl CacheState {
+ fn ensure_callable(&self) -> Result<(), JsValue> {
+ if self.reset_required {
+ Err(reset_required_js_error())
+ } else if self.engine.is_none() {
+ Err(closed_js_error())
+ } else {
+ Ok(())
+ }
+ }
+
+ fn engine_mut(&mut self) -> Result<&mut BrowserEngine, JsValue> {
+ self.ensure_callable()?;
+ Ok(self
+ .engine
+ .as_mut()
+ .expect("callable cache state contains an engine"))
+ }
+
+ fn engine_result<T>(
+ &mut self,
+ result: Result<T, EngineError<TursoStorageError>>,
+ ) -> Result<T, JsValue> {
+ result.map_err(|error| self.engine_error(error))
+ }
+
+ fn engine_error(&mut self, error: EngineError<TursoStorageError>) -> JsValue {
+ if engine_error_requires_reset(&error) {
+ self.reset_required = true;
+ reset_required_js_error()
+ } else {
+ err_js(error)
+ }
+ }
+}
+
#[wasm_bindgen]
pub struct CacheEngine {
- engine: Rc<Mutex<Engine<IdbStorage>>>,
+ state: Rc<Mutex<CacheState>>,
ops: Rc<RefCell<OpInterner>>,
}
-/// Opens (or creates) the cache for `scope`. The physical database is selected
-/// by [`cache_core::codec::cache_database_name`] from `scope` alone; the schema
-/// compatibility epoch and format version are record-compatibility inputs.
-#[wasm_bindgen(js_name = openCache)]
-pub async fn open_cache(scope: String, hot_capacity: Option<u32>) -> Result<CacheEngine, JsError> {
- let storage = IdbStorage::open(&scope)
- .await
- .map_err(|e| JsError::new(&e.to_string()))?;
- let engine = match hot_capacity {
- Some(cap) => Engine::with_capacity(storage, cap as usize),
+fn database_identity(scope: &str) -> String {
+ cache_database_name(scope)
+}
+
+fn build_engine(storage: TursoStorage, hot_capacity: Option<u32>) -> BrowserEngine {
+ let storage = wrap_storage(storage);
+ match hot_capacity {
+ Some(capacity) => Engine::with_capacity(storage, capacity as usize),
None => Engine::new(storage),
+ }
+}
+
+fn validate_hot_capacity(hot_capacity: Option<u32>) -> Result<(), JsValue> {
+ if hot_capacity == Some(0) {
+ Err(err_js("hot capacity must be greater than zero"))
+ } else {
+ Ok(())
+ }
+}
+
+async fn open_owner(owner: OpfsOwner) -> Result<OpenResult, JsValue> {
+ match owner.open().await {
+ Ok(opened) => Ok(opened),
+ Err(failure) => {
+ let error = err_js(&failure);
+ if let Some(owner) = failure.into_owner() {
+ owner.release().await.map_err(err_js)?;
+ }
+ Err(error)
+ }
+ }
+}
+
+struct OpenedStorage {
+ storage: TursoStorage,
+ outcome: CacheOpenOutcome,
+}
+
+async fn open_storage(scope: &str, owner: OpfsOwner) -> Result<OpenedStorage, JsValue> {
+ let (owner, reset_outcome) = match open_owner(owner).await? {
+ OpenResult::Ready(session) => {
+ let connected = session.connect().map_err(err_js)?;
+ match TursoStorage::from_opfs_session_with_outcome(connected, scope) {
+ Ok((storage, outcome)) => {
+ return Ok(OpenedStorage {
+ storage,
+ outcome: outcome.into(),
+ });
+ }
+ Err(failure) => {
+ let error = failure.error();
+ if !error.requires_physical_reset() {
+ let owner = failure.preserve().map_err(err_js)?;
+ owner.release().await.map_err(err_js)?;
+ return Err(err_js(error));
+ }
+ let outcome = recovery_outcome(
+ error
+ .physical_reset_reason()
+ .expect("reset-required error has a reset reason"),
+ );
+ (failure.reset().await.map_err(err_js)?, outcome)
+ }
+ }
+ }
+ OpenResult::ResetRequired(session) => (
+ session.reset().await.map_err(err_js)?,
+ CacheOpenOutcome::ResetStorageUncertain,
+ ),
};
- Ok(CacheEngine {
- engine: Rc::new(Mutex::new(engine)),
- ops: Rc::new(RefCell::new(OpInterner::default())),
- })
+
+ match open_owner(owner).await? {
+ OpenResult::Ready(session) => {
+ let connected = session.connect().map_err(err_js)?;
+ match TursoStorage::from_opfs_session(connected, scope) {
+ Ok(storage) => Ok(OpenedStorage {
+ storage,
+ outcome: reset_outcome,
+ }),
+ Err(failure) => {
+ let reset_required = failure.error().requires_physical_reset();
+ let owner = failure.reset().await.map_err(err_js)?;
+ owner.release().await.map_err(err_js)?;
+ Err(if reset_required {
+ reset_required_js_error()
+ } else {
+ err_js("cache storage initialization failed")
+ })
+ }
+ }
+ }
+ OpenResult::ResetRequired(session) => {
+ let owner = session.reset().await.map_err(err_js)?;
+ owner.release().await.map_err(err_js)?;
+ Err(reset_required_js_error())
+ }
+ }
+}
+
+async fn acquire_storage(scope: &str, recovery_wipe: bool) -> Result<OpenedStorage, JsValue> {
+ let owner = OpfsOwner::acquire(&database_identity(scope))
+ .await
+ .map_err(err_js)?;
+ let owner = if recovery_wipe {
+ owner.recovery_wipe().await.map_err(err_js)?
+ } else {
+ owner
+ };
+ let mut opened = open_storage(scope, owner).await?;
+ if recovery_wipe {
+ opened.outcome = CacheOpenOutcome::ResetStorageUncertain;
+ }
+ Ok(opened)
+}
+
+async fn open_cache_inner(
+ scope: String,
+ hot_capacity: Option<u32>,
+ recovery_wipe: bool,
+) -> Result<(CacheEngine, CacheOpenOutcome), JsValue> {
+ validate_hot_capacity(hot_capacity)?;
+ let OpenedStorage { storage, outcome } = acquire_storage(&scope, recovery_wipe).await?;
+ Ok((
+ CacheEngine {
+ state: Rc::new(Mutex::new(CacheState {
+ engine: Some(build_engine(storage, hot_capacity)),
+ scope,
+ hot_capacity,
+ reset_required: false,
+ })),
+ ops: Rc::new(RefCell::new(OpInterner::default())),
+ },
+ outcome,
+ ))
+}
+
+fn cache_open_result(engine: CacheEngine, outcome: CacheOpenOutcome) -> Result<JsValue, JsValue> {
+ let result = js_sys::Object::new();
+ js_sys::Reflect::set(
+ &result,
+ &JsValue::from_str("engine"),
+ &JsValue::from(engine),
+ )?;
+ js_sys::Reflect::set(
+ &result,
+ &JsValue::from_str("outcome"),
+ &JsValue::from_str(outcome.as_str()),
+ )?;
+ Ok(result.into())
+}
+
+/// Opens (or creates) the cache for `scope` after acquiring its exclusive OPFS
+/// owner lock. The physical identity is derived from `scope` alone; disposable
+/// incomplete or incompatible files are reset and reopened before returning.
+#[wasm_bindgen(js_name = openCache)]
+pub async fn open_cache(scope: String, hot_capacity: Option<u32>) -> Result<CacheEngine, JsValue> {
+ open_cache_inner(scope, hot_capacity, false)
+ .await
+ .map(|(engine, _)| engine)
}
-/// Deletes the cache database for `scope` (logout).
+/// Additive open API returning the engine and payload-free recovery outcome.
+#[wasm_bindgen(js_name = openCacheWithOutcome)]
+pub async fn open_cache_with_outcome(
+ scope: String,
+ hot_capacity: Option<u32>,
+) -> Result<JsValue, JsValue> {
+ let (engine, outcome) = open_cache_inner(scope, hot_capacity, false).await?;
+ cache_open_result(engine, outcome)
+}
+
+/// Acquires the canonical owner once, recovery-wipes before any Turso open,
+/// then opens a fresh cache while continuously retaining that same owner lock.
+#[wasm_bindgen(js_name = openCacheForRecovery)]
+pub async fn open_cache_for_recovery(
+ scope: String,
+ hot_capacity: Option<u32>,
+) -> Result<CacheEngine, JsValue> {
+ open_cache_inner(scope, hot_capacity, true)
+ .await
+ .map(|(engine, _)| engine)
+}
+
+/// Additive recovery-open API returning the engine and coarse wipe outcome.
+#[wasm_bindgen(js_name = openCacheForRecoveryWithOutcome)]
+pub async fn open_cache_for_recovery_with_outcome(
+ scope: String,
+ hot_capacity: Option<u32>,
+) -> Result<JsValue, JsValue> {
+ let (engine, outcome) = open_cache_inner(scope, hot_capacity, true).await?;
+ cache_open_result(engine, outcome)
+}
+
+/// Recovery-wipes and recreates the cache database for `scope` while holding
+/// the same exclusive OPFS owner lock used by [`openCache`](open_cache).
#[wasm_bindgen(js_name = destroyCache)]
-pub async fn destroy_cache(scope: String) -> Result<(), JsError> {
- IdbStorage::destroy(&scope)
+pub async fn destroy_cache(scope: String) -> Result<(), JsValue> {
+ OpfsOwner::acquire(&database_identity(&scope))
+ .await
+ .map_err(err_js)?
+ .recovery_wipe()
+ .await
+ .map_err(err_js)?
+ .release()
.await
- .map_err(|e| JsError::new(&e.to_string()))
+ .map_err(err_js)
+}
+
+#[cfg(feature = "browser-test-hooks")]
+enum BrowserTestStorageMutation {
+ IncompatibleNamespace,
+ CorruptQueuePayload,
+}
+
+#[cfg(feature = "browser-test-hooks")]
+async fn browser_test_mutate_closed_storage(
+ scope: String,
+ mutation: BrowserTestStorageMutation,
+) -> Result<(), JsValue> {
+ let owner = OpfsOwner::acquire(&database_identity(&scope))
+ .await
+ .map_err(err_js)?;
+ let session = match open_owner(owner).await? {
+ OpenResult::Ready(session) => session,
+ OpenResult::ResetRequired(session) => {
+ let owner = session.reset().await.map_err(err_js)?;
+ owner.release().await.map_err(err_js)?;
+ return Err(err_js("browser-test storage was already reset-required"));
+ }
+ };
+ let connected = session.connect().map_err(err_js)?;
+ let mut storage = match TursoStorage::from_opfs_session(connected, &scope) {
+ Ok(storage) => storage,
+ Err(failure) => {
+ let owner = failure.reset().await.map_err(err_js)?;
+ owner.release().await.map_err(err_js)?;
+ return Err(err_js("browser-test storage validation failed"));
+ }
+ };
+ match mutation {
+ BrowserTestStorageMutation::IncompatibleNamespace => {
+ storage.browser_test_make_namespace_incompatible()
+ }
+ BrowserTestStorageMutation::CorruptQueuePayload => {
+ storage.browser_test_corrupt_queue_payload()
+ }
+ }
+ .map_err(err_js)?;
+ match storage.try_close().map_err(err_js)? {
+ TursoStorageCloseOutcome::Healthy(closed) => closed
+ .preserve()
+ .map_err(err_js)?
+ .release()
+ .await
+ .map_err(err_js),
+ TursoStorageCloseOutcome::ResetRequired(closed) => {
+ let owner = closed.reset().await.map_err(err_js)?;
+ owner.release().await.map_err(err_js)?;
+ Err(err_js("browser-test mutation unexpectedly required reset"))
+ }
+ }
+}
+
+/// Test-artifact-only incompatible-namespace hook.
+#[cfg(feature = "browser-test-hooks")]
+#[wasm_bindgen(js_name = browserTestMakeNamespaceIncompatible)]
+pub async fn browser_test_make_namespace_incompatible(scope: String) -> Result<(), JsValue> {
+ browser_test_mutate_closed_storage(scope, BrowserTestStorageMutation::IncompatibleNamespace)
+ .await
+}
+
+/// Test-artifact-only corrupt-queue hook.
+#[cfg(feature = "browser-test-hooks")]
+#[wasm_bindgen(js_name = browserTestCorruptQueuePayload)]
+pub async fn browser_test_corrupt_queue_payload(scope: String) -> Result<(), JsValue> {
+ browser_test_mutate_closed_storage(scope, BrowserTestStorageMutation::CorruptQueuePayload).await
}
/// Schema hash baked into this build (build diagnostics).
@@ -184,11 +562,35 @@ fn to_js<T: Serialize>(value: &T) -> Result<JsValue, JsValue> {
.map_err(|e| JsValue::from_str(&e.to_string()))
}
-/// All rejections surface as real `Error` objects (consistent
-/// `instanceof Error` / `.message` behavior with the `JsError`-returning
-/// functions like `openCache`).
-fn err_js(e: impl std::fmt::Display) -> JsValue {
- js_sys::Error::new(&e.to_string()).into()
+const RESET_REQUIRED_MARKER: &str = "cacheStorageResetRequired";
+const RESET_REQUIRED_MESSAGE: &str = "cache storage reset required";
+
+/// All rejections surface as real `Error` objects with consistent
+/// `instanceof Error` and `.message` behavior.
+fn err_js(error: impl std::fmt::Display) -> JsValue {
+ js_sys::Error::new(&error.to_string()).into()
+}
+
+fn closed_js_error() -> JsValue {
+ err_js("cache engine is closed")
+}
+
+fn reset_required_js_error() -> JsValue {
+ let error = js_sys::Error::new(RESET_REQUIRED_MESSAGE);
+ js_sys::Reflect::set(
+ error.as_ref(),
+ &JsValue::from_str(RESET_REQUIRED_MARKER),
+ &JsValue::TRUE,
+ )
+ .expect("new JavaScript Error accepts the reset marker");
+ error.into()
+}
+
+fn engine_error_requires_reset(error: &EngineError<TursoStorageError>) -> bool {
+ matches!(
+ error,
+ EngineError::Storage(storage_error) if storage_error.requires_physical_reset()
+ )
}
fn parse_variables(
@@ -233,20 +635,77 @@ fn parse_query_inspection(
})
}
+async fn close_storage(storage: BrowserStorage, force_reset: bool) -> Result<OpfsOwner, JsValue> {
+ match unwrap_storage(storage).try_close().map_err(err_js)? {
+ TursoStorageCloseOutcome::Healthy(closed) if force_reset => {
+ closed.reset().await.map_err(err_js)
+ }
+ TursoStorageCloseOutcome::Healthy(closed) => closed.preserve().map_err(err_js),
+ TursoStorageCloseOutcome::ResetRequired(closed) => closed.reset().await.map_err(err_js),
+ }
+}
+
#[wasm_bindgen]
impl CacheEngine {
+ /// Returns payload-free durable mutation queue diagnostics.
+ #[wasm_bindgen(js_name = queueDiagnostics)]
+ pub fn queue_diagnostics(&self) -> js_sys::Promise {
+ let state = self.state.clone();
+ future_to_promise(async move {
+ let mut state = state.lock().await;
+ // Observation failures bypass `engine_result`: diagnostics never
+ // latch reset-required state or alter the engine lifecycle.
+ let diagnostics = state
+ .engine_mut()?
+ .queue_diagnostics()
+ .await
+ .map_err(err_js)?;
+ let value = js_sys::Object::new();
+ let available = diagnostics.availability == QueueDiagnosticsAvailability::Available;
+ js_sys::Reflect::set(
+ &value,
+ &JsValue::from_str("availability"),
+ &JsValue::from_str(if available {
+ "available"
+ } else {
+ "unavailable"
+ }),
+ )?;
+ js_sys::Reflect::set(
+ &value,
+ &JsValue::from_str("depth"),
+ &if available {
+ JsValue::from_str(&diagnostics.depth.to_string())
+ } else {
+ JsValue::NULL
+ },
+ )?;
+ js_sys::Reflect::set(
+ &value,
+ &JsValue::from_str("oldestCreatedAtMs"),
+ &if available {
+ diagnostics
+ .oldest_created_at_ms
+ .map_or(JsValue::NULL, |timestamp| {
+ JsValue::from_str(&timestamp.to_string())
+ })
+ } else {
+ JsValue::NULL
+ },
+ )?;
+ Ok(value.into())
+ })
+ }
+
/// Returns the opaque identity bound to this cache, or `null` when no
/// identity-bearing response has been stored yet.
#[wasm_bindgen(js_name = boundIdentity)]
pub fn bound_identity(&self) -> js_sys::Promise {
- let engine = self.engine.clone();
+ let state = self.state.clone();
future_to_promise(async move {
- let identity = engine
- .lock()
- .await
- .current_identity()
- .await
- .map_err(err_js)?;
+ let mut state = state.lock().await;
+ let result = state.engine_mut()?.current_identity().await;
+ let identity = state.engine_result(result)?;
to_js(&identity)
})
}
@@ -263,14 +722,16 @@ impl CacheEngine {
variables: JsValue,
entity_resolvers: JsValue,
) -> js_sys::Promise {
- let engine = self.engine.clone();
+ let state = self.state.clone();
let ops = self.ops.clone();
future_to_promise(async move {
+ let mut state = state.lock().await;
+ state.ensure_callable()?;
let vars = parse_variables(variables)?;
let entity_resolvers: Vec<EntityResolver> = parse_vec(entity_resolvers)?;
let op = op_id.map(|name| ops.borrow_mut().intern(&name));
- let mut engine = engine.lock().await;
- let result = engine
+ let result = state
+ .engine_mut()?
.read_query_with_entity_resolvers(
op,
&query,
@@ -278,8 +739,8 @@ impl CacheEngine {
&vars,
&entity_resolvers,
)
- .await
- .map_err(err_js)?;
+ .await;
+ let result = state.engine_result(result)?;
to_js(&match result {
ReadResult::Hit { data } => JsReadResult::Hit { data },
ReadResult::Miss => JsReadResult::Miss,
@@ -296,16 +757,17 @@ impl CacheEngine {
cursor: JsValue,
limit: u32,
) -> js_sys::Promise {
- let engine = self.engine.clone();
+ let state = self.state.clone();
future_to_promise(async move {
+ let mut state = state.lock().await;
+ state.ensure_callable()?;
let selection = RecordSelection::parse(&document, &fragment_name).map_err(err_js)?;
let cursor = parse_record_cursor(cursor)?;
- let page = engine
- .lock()
- .await
+ let result = state
+ .engine_mut()?
.read_records(&selection, cursor.as_ref(), limit as usize)
- .await
- .map_err(err_js)?;
+ .await;
+ let page = state.engine_result(result)?;
to_js(&page)
})
}
@@ -326,14 +788,16 @@ impl CacheEngine {
data: JsValue,
identity: Option<String>,
) -> js_sys::Promise {
- let engine = self.engine.clone();
+ let state = self.state.clone();
let ops = self.ops.clone();
future_to_promise(async move {
+ let mut state = state.lock().await;
+ state.ensure_callable()?;
let vars = parse_variables(variables)?;
let data: serde_json::Value = serde_wasm_bindgen::from_value(data).map_err(err_js)?;
let origin = origin_op_id.map(|name| ops.borrow_mut().intern(&name));
- let mut engine = engine.lock().await;
- let result = engine
+ let result = state
+ .engine_mut()?
.write_query(
origin,
&query,
@@ -342,8 +806,8 @@ impl CacheEngine {
&data,
identity.as_deref(),
)
- .await
- .map_err(err_js)?;
+ .await;
+ let result = state.engine_result(result)?;
to_js(&JsWriteResult {
changed: result
.changed
@@ -376,9 +840,11 @@ impl CacheEngine {
now_ms: f64,
lease_expires_at_ms: f64,
) -> js_sys::Promise {
- let engine = self.engine.clone();
+ let state = self.state.clone();
let ops = self.ops.clone();
future_to_promise(async move {
+ let mut state = state.lock().await;
+ state.ensure_callable()?;
let vars = parse_variables(variables)?;
let data: serde_json::Value = serde_wasm_bindgen::from_value(data).map_err(err_js)?;
let link_patches: Vec<OptimisticLinkPatch> = parse_vec(link_patches)?;
@@ -393,8 +859,8 @@ impl CacheEngine {
)?,
};
let origin = origin_op_id.map(|name| ops.borrow_mut().intern(&name));
- let mut engine = engine.lock().await;
- let result = engine
+ let result = state
+ .engine_mut()?
.enqueue_optimistic_mutation(
origin,
BeginOptimisticWrite {
@@ -408,13 +874,16 @@ impl CacheEngine {
},
claim,
)
- .await
- .map_err(err_js)?;
+ .await;
+ let result = state.engine_result(result)?;
let initial_claim = match result.initial_claim {
InitialClaimOutcome::Claimed(claimed) => JsInitialMutationClaim::Claimed {
mutation: JsClaimedMutation::try_from(*claimed)?,
},
InitialClaimOutcome::NotRunnable => JsInitialMutationClaim::NotRunnable,
+ InitialClaimOutcome::Failed(error) if engine_error_requires_reset(&error) => {
+ return Err(state.engine_error(error));
+ }
InitialClaimOutcome::Failed(error) => JsInitialMutationClaim::Failed {
error: error.to_string(),
},
@@ -443,15 +912,16 @@ impl CacheEngine {
operation_name: Option<String>,
path: JsValue,
) -> js_sys::Promise {
- let engine = self.engine.clone();
+ let state = self.state.clone();
future_to_promise(async move {
+ let mut state = state.lock().await;
+ state.ensure_callable()?;
let inspection = parse_query_inspection(query, operation_name, path, Vec::new())?;
- let variants = engine
- .lock()
- .await
+ let result = state
+ .engine_mut()?
.inspect_query_variants(&inspection)
- .await
- .map_err(err_js)?;
+ .await;
+ let variants = state.engine_result(result)?;
to_js(&variants)
})
}
@@ -465,16 +935,14 @@ impl CacheEngine {
path: JsValue,
variable_filters: JsValue,
) -> js_sys::Promise {
- let engine = self.engine.clone();
+ let state = self.state.clone();
future_to_promise(async move {
+ let mut state = state.lock().await;
+ state.ensure_callable()?;
let variable_filters = parse_vec(variable_filters)?;
let inspection = parse_query_inspection(query, operation_name, path, variable_filters)?;
- let instances = engine
- .lock()
- .await
- .inspect_query(&inspection)
- .await
- .map_err(err_js)?;
+ let result = state.engine_mut()?.inspect_query(&inspection).await;
+ let instances = state.engine_result(result)?;
to_js(&instances)
})
}
@@ -487,8 +955,10 @@ impl CacheEngine {
now_ms: f64,
lease_expires_at_ms: f64,
) -> js_sys::Promise {
- let engine = self.engine.clone();
+ let state = self.state.clone();
future_to_promise(async move {
+ let mut state = state.lock().await;
+ state.ensure_callable()?;
let request = MutationClaimRequest {
owner,
now_ms: parse_timestamp(now_ms, "claim timestamp")?,
@@ -497,12 +967,8 @@ impl CacheEngine {
"lease expiration timestamp",
)?,
};
- let claimed = engine
- .lock()
- .await
- .claim_next_mutation(request)
- .await
- .map_err(err_js)?;
+ let result = state.engine_mut()?.claim_next_mutation(request).await;
+ let claimed = state.engine_result(result)?;
to_js(&claimed.map(JsClaimedMutation::try_from).transpose()?)
})
}
@@ -517,24 +983,21 @@ impl CacheEngine {
next_attempt_at_ms: f64,
error: String,
) -> js_sys::Promise {
- let engine = self.engine.clone();
+ let state = self.state.clone();
future_to_promise(async move {
+ let mut state = state.lock().await;
+ state.ensure_callable()?;
let transaction = parse_transaction_id(&transaction_id)?;
let claim = MutationClaimToken {
owner: lease_owner,
generation: parse_u64(&lease_generation, "lease generation")?,
};
- engine
- .lock()
- .await
- .defer_optimistic_write(
- transaction,
- claim,
- parse_timestamp(next_attempt_at_ms, "next attempt timestamp")?,
- error,
- )
- .await
- .map_err(err_js)?;
+ let next_attempt_at_ms = parse_timestamp(next_attempt_at_ms, "next attempt timestamp")?;
+ let result = state
+ .engine_mut()?
+ .defer_optimistic_write(transaction, claim, next_attempt_at_ms, error)
+ .await;
+ state.engine_result(result)?;
Ok(JsValue::UNDEFINED)
})
}
@@ -542,6 +1005,7 @@ impl CacheEngine {
/// Atomically replaces a claimed optimistic layer with the real network
/// response and removes it from the durable queue.
#[wasm_bindgen(js_name = commitOptimisticWrite)]
+ #[allow(clippy::too_many_arguments)]
pub fn commit_optimistic_write(
&self,
transaction_id: String,
@@ -552,9 +1016,11 @@ impl CacheEngine {
variables: JsValue,
data: JsValue,
) -> js_sys::Promise {
- let engine = self.engine.clone();
+ let state = self.state.clone();
let ops = self.ops.clone();
future_to_promise(async move {
+ let mut state = state.lock().await;
+ state.ensure_callable()?;
let transaction = parse_transaction_id(&transaction_id)?;
let claim = MutationClaimToken {
owner: lease_owner,
@@ -562,8 +1028,8 @@ impl CacheEngine {
};
let vars = parse_variables(variables)?;
let data: serde_json::Value = serde_wasm_bindgen::from_value(data).map_err(err_js)?;
- let mut engine = engine.lock().await;
- let result = engine
+ let result = state
+ .engine_mut()?
.commit_optimistic_write(
transaction,
claim,
@@ -572,8 +1038,8 @@ impl CacheEngine {
&vars,
&data,
)
- .await
- .map_err(err_js)?;
+ .await;
+ let result = state.engine_result(result)?;
to_js(&JsWriteResult {
changed: result
.changed
@@ -596,19 +1062,21 @@ impl CacheEngine {
lease_owner: String,
lease_generation: String,
) -> js_sys::Promise {
- let engine = self.engine.clone();
+ let state = self.state.clone();
let ops = self.ops.clone();
future_to_promise(async move {
+ let mut state = state.lock().await;
+ state.ensure_callable()?;
let transaction = parse_transaction_id(&transaction_id)?;
let claim = MutationClaimToken {
owner: lease_owner,
generation: parse_u64(&lease_generation, "lease generation")?,
};
- let mut engine = engine.lock().await;
- let result = engine
+ let result = state
+ .engine_mut()?
.rollback_optimistic_write(transaction, claim)
- .await
- .map_err(err_js)?;
+ .await;
+ let result = state.engine_result(result)?;
to_js(&JsWriteResult {
changed: result
.changed
@@ -627,32 +1095,31 @@ impl CacheEngine {
/// operation ids.
#[wasm_bindgen(js_name = invalidateKeys)]
pub fn invalidate_keys(&self, keys: Vec<String>) -> js_sys::Promise {
- let engine = self.engine.clone();
+ let state = self.state.clone();
let ops = self.ops.clone();
future_to_promise(async move {
+ let mut state = state.lock().await;
+ state.ensure_callable()?;
let keys: Vec<EntityKey<'static>> =
keys.into_iter().map(|key| EntityKey(key.into())).collect();
- let mut engine = engine.lock().await;
- let affected = engine.invalidate_keys(keys.iter());
+ let affected = state.engine_mut()?.invalidate_keys(keys.iter());
to_js(&ops.borrow().names(affected))
})
}
- /// Deletes stale records from memory and IndexedDB after a server-side
+ /// Deletes stale records from memory and Turso after a server-side
/// mutation and resolves to affected local operation ids.
#[wasm_bindgen(js_name = deleteKeys)]
pub fn delete_keys(&self, keys: Vec<String>) -> js_sys::Promise {
- let engine = self.engine.clone();
+ let state = self.state.clone();
let ops = self.ops.clone();
future_to_promise(async move {
+ let mut state = state.lock().await;
+ state.ensure_callable()?;
let keys: Vec<EntityKey<'static>> =
keys.into_iter().map(|key| EntityKey(key.into())).collect();
- let affected = engine
- .lock()
- .await
- .delete_keys(&keys)
- .await
- .map_err(err_js)?;
+ let result = state.engine_mut()?.delete_keys(&keys).await;
+ let affected = state.engine_result(result)?;
to_js(&ops.borrow().names(affected))
})
}
@@ -661,15 +1128,12 @@ impl CacheEngine {
/// queue and returns locally affected operations.
#[wasm_bindgen(js_name = refreshOptimisticQueue)]
pub fn refresh_optimistic_queue(&self) -> js_sys::Promise {
- let engine = self.engine.clone();
+ let state = self.state.clone();
let ops = self.ops.clone();
future_to_promise(async move {
- let result = engine
- .lock()
- .await
- .refresh_optimistic_queue()
- .await
- .map_err(err_js)?;
+ let mut state = state.lock().await;
+ let result = state.engine_mut()?.refresh_optimistic_queue().await;
+ let result = state.engine_result(result)?;
to_js(&JsWriteResult {
changed: result
.changed
@@ -688,10 +1152,11 @@ impl CacheEngine {
/// and resolves to every local operation id (all must re-execute).
#[wasm_bindgen(js_name = externalReset)]
pub fn external_reset(&self) -> js_sys::Promise {
- let engine = self.engine.clone();
+ let state = self.state.clone();
let ops = self.ops.clone();
future_to_promise(async move {
- let affected = engine.lock().await.external_reset();
+ let mut state = state.lock().await;
+ let affected = state.engine_mut()?.external_reset();
to_js(&ops.borrow().names(affected))
})
}
@@ -699,34 +1164,106 @@ impl CacheEngine {
/// Unregisters an operation (urql teardown).
#[wasm_bindgen(js_name = teardownOperation)]
pub fn teardown_operation(&self, op_id: String) -> js_sys::Promise {
- let engine = self.engine.clone();
+ let state = self.state.clone();
let ops = self.ops.clone();
future_to_promise(async move {
- let removed = ops.borrow_mut().remove(&op_id);
- if let Some(id) = removed {
- engine.lock().await.teardown_operation(id);
+ let mut state = state.lock().await;
+ let engine = state.engine_mut()?;
+ if let Some(id) = ops.borrow_mut().remove(&op_id) {
+ engine.teardown_operation(id);
}
Ok(JsValue::UNDEFINED)
})
}
- /// Drops all cached state (logout, corruption rebuild).
+ /// Drops all cached state, including the durable mutation queue.
pub fn clear(&self) -> js_sys::Promise {
- let engine = self.engine.clone();
+ let state = self.state.clone();
future_to_promise(async move {
- engine.lock().await.clear().await.map_err(err_js)?;
+ let mut state = state.lock().await;
+ let result = state.engine_mut()?.clear().await;
+ state.engine_result(result)?;
Ok(JsValue::UNDEFINED)
})
}
- /// Closes the underlying IndexedDB connection. Call before
- /// [`destroyCache`](destroy_cache) — database deletion blocks while
- /// connections are open. The engine is unusable afterwards.
+ /// Physically resets and recreates this instance's OPFS database while
+ /// retaining the exclusive owner lock. The instance remains usable after
+ /// the fresh engine has been installed.
+ #[wasm_bindgen(js_name = physicalReset)]
+ pub fn physical_reset(&self) -> js_sys::Promise {
+ let state = self.state.clone();
+ future_to_promise(async move {
+ let mut state = state.lock().await;
+ let engine = state.engine.take().ok_or_else(|| {
+ if state.reset_required {
+ err_js("cache engine requires worker replacement")
+ } else {
+ closed_js_error()
+ }
+ })?;
+ let scope = state.scope.clone();
+ let hot_capacity = state.hot_capacity;
+ let owner = match close_storage(engine.into_storage(), true).await {
+ Ok(owner) => owner,
+ Err(error) => {
+ state.reset_required = true;
+ return Err(error);
+ }
+ };
+ let storage = match open_storage(&scope, owner).await {
+ Ok(opened) => opened.storage,
+ Err(error) => {
+ state.reset_required = true;
+ return Err(error);
+ }
+ };
+ state.engine = Some(build_engine(storage, hot_capacity));
+ state.reset_required = false;
+ Ok(JsValue::UNDEFINED)
+ })
+ }
+
+ /// Consumes the engine, closes Turso and all OPFS handles, then preserves a
+ /// healthy database or resets a latched-unhealthy database before releasing
+ /// the exclusive owner lock. Every later instance method rejects.
pub fn close(&self) -> js_sys::Promise {
- let engine = self.engine.clone();
+ let state = self.state.clone();
future_to_promise(async move {
- engine.lock().await.storage().close();
+ let mut state = state.lock().await;
+ let engine = state.engine.take().ok_or_else(|| {
+ if state.reset_required {
+ err_js("cache engine requires worker replacement")
+ } else {
+ closed_js_error()
+ }
+ })?;
+ let owner = match close_storage(engine.into_storage(), state.reset_required).await {
+ Ok(owner) => owner,
+ Err(error) => {
+ state.reset_required = true;
+ return Err(error);
+ }
+ };
+ if let Err(error) = owner.release().await {
+ state.reset_required = true;
+ return Err(err_js(error));
+ }
+ state.reset_required = false;
Ok(JsValue::UNDEFINED)
})
}
}
+
+#[cfg(test)]
+impl CacheEngine {
+ async fn arm_storage_fault(&self, fault: TestStorageFault) {
+ let state = self.state.lock().await;
+ state
+ .engine
+ .as_ref()
+ .expect("test cache contains an engine")
+ .storage()
+ .arm(fault);
+ }
+}
diff --git a/crates/client/cache-wasm/src/shell/test.rs b/crates/client/cache-wasm/src/shell/test.rs
new file mode 100644
index 0000000000..c190b0c1ac
--- /dev/null
+++ b/crates/client/cache-wasm/src/shell/test.rs
@@ -0,0 +1,1014 @@
+use super::*;
+use serde::de::DeserializeOwned;
+use wasm_bindgen_futures::JsFuture;
+use wasm_bindgen_test::*;
+
+wasm_bindgen_test_configure!(run_in_dedicated_worker);
+
+const QUERY: &str = r#"query Soup($input: SoupInput!) {
+ user {
+ id
+ soup(input: $input) {
+ nextCursor
+ items {
+ __typename
+ id
+ }
+ }
+ }
+}"#;
+
+const PROPERTY_QUERY: &str = r#"query Soup($input: SoupInput!) {
+ user { id soup(input: $input) { nextCursor items {
+ __typename
+ id
+ ... on GraphqlSoupDocument { properties { id displayName } }
+ } } }
+}"#;
+
+const PROPERTY_MUTATION: &str = r#"mutation SetEntityProperty($input: SetEntityPropertyInput!) {
+ setEntityProperty(input: $input) { id displayName }
+}"#;
+
+const RECORD_FRAGMENT: &str = r#"fragment CachedDocument on GraphqlSoupDocument {
+ id
+}"#;
+
+fn js(json: serde_json::Value) -> JsValue {
+ use serde::Serialize;
+ json.serialize(&serde_wasm_bindgen::Serializer::json_compatible())
+ .expect("serialize test value")
+}
+
+fn from_js<T: DeserializeOwned>(value: JsValue) -> T {
+ serde_wasm_bindgen::from_value(value).expect("deserialize wasm result")
+}
+
+async fn resolved(promise: js_sys::Promise) -> JsValue {
+ JsFuture::from(promise).await.expect("promise resolves")
+}
+
+async fn assert_closed(promise: js_sys::Promise) {
+ let error = JsFuture::from(promise)
+ .await
+ .expect_err("closed method rejects");
+ let message = js_sys::Reflect::get(&error, &JsValue::from_str("message"))
+ .expect("Error.message")
+ .as_string()
+ .expect("message is a string");
+ assert_eq!(message, "cache engine is closed");
+}
+
+async fn assert_reset_required(promise: js_sys::Promise) {
+ let error = JsFuture::from(promise)
+ .await
+ .expect_err("reset-required method rejects");
+ assert!(error.is_instance_of::<js_sys::Error>());
+ assert_eq!(
+ js_sys::Reflect::get(&error, &JsValue::from_str(RESET_REQUIRED_MARKER))
+ .expect("reset marker")
+ .as_bool(),
+ Some(true)
+ );
+ let message = js_sys::Reflect::get(&error, &JsValue::from_str("message"))
+ .expect("Error.message")
+ .as_string()
+ .expect("message is a string");
+ assert_eq!(message, RESET_REQUIRED_MESSAGE);
+}
+
+fn variables() -> serde_json::Value {
+ serde_json::json!({"input": {"limit": 1}})
+}
+
+fn soup_data(document_id: &str) -> serde_json::Value {
+ serde_json::json!({
+ "user": {
+ "id": "user-1",
+ "soup": {
+ "nextCursor": null,
+ "items": [{
+ "__typename": "GraphqlSoupDocument",
+ "id": document_id
+ }]
+ }
+ }
+ })
+}
+
+fn property_base() -> serde_json::Value {
+ property_data("Status")
+}
+
+fn property_data(display_name: &str) -> serde_json::Value {
+ serde_json::json!({
+ "user": { "id": "user-1", "soup": { "nextCursor": null, "items": [{
+ "__typename": "GraphqlSoupDocument",
+ "id": "doc-1",
+ "properties": [{ "id": "prop-1", "displayName": display_name }]
+ }] } }
+ })
+}
+
+fn mutation_variables() -> serde_json::Value {
+ serde_json::json!({"input": {
+ "entityType": "DOCUMENT",
+ "entityId": "doc-1",
+ "propertyDefinitionId": "def-1",
+ "value": { "string": "x" }
+ }})
+}
+
+async fn fresh_engine(scope: &str) -> CacheEngine {
+ destroy_cache(scope.into())
+ .await
+ .expect("wipe test database");
+ open_cache(scope.into(), None).await.expect("open cache")
+}
+
+async fn close_and_destroy(engine: &CacheEngine, scope: &str) {
+ resolved(engine.close()).await;
+ destroy_cache(scope.into()).await.expect("destroy cache");
+}
+
+#[wasm_bindgen_test(async)]
+async fn operations_preserve_js_boundary_interner_and_ordering() {
+ const SCOPE: &str = "cache-wasm-wp07-operations";
+ let engine = fresh_engine(SCOPE).await;
+ let vars = variables();
+
+ for operation in ["tab:z", "tab:a"] {
+ let read: serde_json::Value = from_js(
+ resolved(engine.read_query(
+ Some(operation.into()),
+ QUERY.into(),
+ Some("Soup".into()),
+ js(vars.clone()),
+ JsValue::UNDEFINED,
+ ))
+ .await,
+ );
+ assert_eq!(read["kind"], "miss");
+ }
+
+ let write: serde_json::Value = from_js(
+ resolved(engine.write_query(
+ Some("tab:writer".into()),
+ QUERY.into(),
+ Some("Soup".into()),
+ js(vars.clone()),
+ js(soup_data("doc-1")),
+ Some("user-1".into()),
+ ))
+ .await,
+ );
+ assert_eq!(write["affectedOps"], serde_json::json!(["tab:z", "tab:a"]));
+ assert_eq!(write["reset"], false);
+
+ let identity: Option<String> = from_js(resolved(engine.bound_identity()).await);
+ assert_eq!(identity.as_deref(), Some("user-1"));
+
+ let variants: serde_json::Value = from_js(
+ resolved(engine.inspect_query_variants(
+ QUERY.into(),
+ Some("Soup".into()),
+ js(serde_json::json!([{"field": "user"}, {"field": "soup"}])),
+ ))
+ .await,
+ );
+ assert_eq!(variants[0]["variables"], vars);
+ assert!(variants[0].get("value").is_none());
+
+ let inspected: serde_json::Value = from_js(
+ resolved(engine.inspect_query(
+ QUERY.into(),
+ Some("Soup".into()),
+ js(serde_json::json!([{"field": "user"}, {"field": "soup"}])),
+ js(serde_json::json!([])),
+ ))
+ .await,
+ );
+ assert_eq!(inspected[0]["variables"], vars);
+ assert_eq!(inspected[0]["value"], soup_data("doc-1")["user"]["soup"]);
+
+ let read: serde_json::Value = from_js(
+ resolved(engine.read_query(
+ Some("tab:z".into()),
+ QUERY.into(),
+ Some("Soup".into()),
+ js(vars.clone()),
+ JsValue::UNDEFINED,
+ ))
+ .await,
+ );
+ assert_eq!(read["kind"], "hit");
+ assert_eq!(read["data"], soup_data("doc-1"));
+ let read: serde_json::Value = from_js(
+ resolved(engine.read_query(
+ Some("tab:a".into()),
+ QUERY.into(),
+ Some("Soup".into()),
+ js(vars.clone()),
+ JsValue::UNDEFINED,
+ ))
+ .await,
+ );
+ assert_eq!(read["kind"], "hit");
+
+ let affected: Vec<String> =
+ from_js(resolved(engine.invalidate_keys(vec!["GraphqlSoupDocument:doc-1".into()])).await);
+ assert_eq!(affected, ["tab:z", "tab:a"]);
+
+ resolved(engine.delete_keys(vec!["GraphqlSoupDocument:doc-1".into()])).await;
+ let read: serde_json::Value = from_js(
+ resolved(engine.read_query(
+ Some("tab:z".into()),
+ QUERY.into(),
+ Some("Soup".into()),
+ js(vars),
+ JsValue::UNDEFINED,
+ ))
+ .await,
+ );
+ assert_eq!(read["kind"], "miss");
+
+ close_and_destroy(&engine, SCOPE).await;
+}
+
+#[wasm_bindgen_test(async)]
+async fn entity_resolvers_cross_the_js_boundary() {
+ const SCOPE: &str = "cache-wasm-wp07-entity-resolver";
+ let engine = fresh_engine(SCOPE).await;
+ resolved(engine.write_query(
+ None,
+ QUERY.into(),
+ Some("Soup".into()),
+ js(variables()),
+ js(serde_json::json!({
+ "user": {
+ "id": "user-1",
+ "soup": {
+ "nextCursor": null,
+ "items": [{
+ "__typename": "GraphqlSoupEmailThread",
+ "id": "thread-1"
+ }]
+ }
+ }
+ })),
+ None,
+ ))
+ .await;
+
+ let direct_query = r#"query Email($input: EmailThreadInput!) {
+ user { id emailThread(input: $input) { __typename id } }
+ }"#;
+ let result: serde_json::Value = from_js(
+ resolved(engine.read_query(
+ Some("tab:entity".into()),
+ direct_query.into(),
+ Some("Email".into()),
+ js(serde_json::json!({"input": {"threadId": "thread-1"}})),
+ js(serde_json::json!([{
+ "parentType": "GraphqlUser",
+ "fieldName": "emailThread",
+ "targetType": "GraphqlSoupEmailThread",
+ "argumentPath": ["input", "threadId"]
+ }])),
+ ))
+ .await,
+ );
+ assert_eq!(result["kind"], "hit");
+ assert_eq!(result["data"]["user"]["emailThread"]["id"], "thread-1");
+
+ close_and_destroy(&engine, SCOPE).await;
+}
+
+#[wasm_bindgen_test(async)]
+async fn queue_and_optimistic_layers_survive_preserve_reopen_in_id_order() {
+ const SCOPE: &str = "cache-wasm-wp07-queue-reopen";
+ let engine = fresh_engine(SCOPE).await;
+ let vars = variables();
+ resolved(engine.write_query(
+ None,
+ PROPERTY_QUERY.into(),
+ Some("Soup".into()),
+ js(vars.clone()),
+ js(property_base()),
+ None,
+ ))
+ .await;
+
+ let first: serde_json::Value = from_js(
+ resolved(engine.enqueue_optimistic_mutation(
+ None,
+ PROPERTY_MUTATION.into(),
+ Some("SetEntityProperty".into()),
+ js(mutation_variables()),
+ js(serde_json::json!({
+ "setEntityProperty": { "id": "prop-1", "displayName": "First" }
+ })),
+ JsValue::UNDEFINED,
+ JsValue::UNDEFINED,
+ 1.0,
+ "first-owner".into(),
+ 0.0,
+ 50.0,
+ ))
+ .await,
+ );
+ assert_eq!(first["initialClaim"]["kind"], "claimed");
+
+ let second: serde_json::Value = from_js(
+ resolved(engine.enqueue_optimistic_mutation(
+ None,
+ PROPERTY_MUTATION.into(),
+ Some("SetEntityProperty".into()),
+ js(mutation_variables()),
+ js(serde_json::json!({
+ "setEntityProperty": { "id": "prop-1", "displayName": "Second" }
+ })),
+ JsValue::UNDEFINED,
+ JsValue::UNDEFINED,
+ 2.0,
+ "second-owner".into(),
+ 0.0,
+ 50.0,
+ ))
+ .await,
+ );
+ assert_eq!(second["initialClaim"]["kind"], "not-runnable");
+ let first_id = first["transactionId"].as_str().unwrap().to_owned();
+ let second_id = second["transactionId"].as_str().unwrap().to_owned();
+
+ resolved(engine.close()).await;
+ let reopened = open_cache(SCOPE.into(), None)
+ .await
+ .expect("reopen preserved cache");
+ let optimistic: serde_json::Value = from_js(
+ resolved(reopened.read_query(
+ Some("tab:queue".into()),
+ PROPERTY_QUERY.into(),
+ Some("Soup".into()),
+ js(vars.clone()),
+ JsValue::UNDEFINED,
+ ))
+ .await,
+ );
+ assert_eq!(
+ optimistic["data"]["user"]["soup"]["items"][0]["properties"][0]["displayName"],
+ "Second"
+ );
+
+ let first_claim: serde_json::Value =
+ from_js(resolved(reopened.claim_next_mutation("reopener".into(), 50.0, 100.0)).await);
+ assert_eq!(first_claim["transactionId"], first_id);
+ resolved(reopened.rollback_optimistic_write(
+ first_id,
+ "reopener".into(),
+ first_claim["leaseGeneration"].as_str().unwrap().into(),
+ ))
+ .await;
+
+ let second_claim: serde_json::Value =
+ from_js(resolved(reopened.claim_next_mutation("reopener".into(), 50.0, 100.0)).await);
+ assert_eq!(second_claim["transactionId"], second_id);
+ resolved(reopened.rollback_optimistic_write(
+ second_id,
+ "reopener".into(),
+ second_claim["leaseGeneration"].as_str().unwrap().into(),
+ ))
+ .await;
+
+ let base: serde_json::Value = from_js(
+ resolved(reopened.read_query(
+ Some("tab:queue".into()),
+ PROPERTY_QUERY.into(),
+ Some("Soup".into()),
+ js(vars),
+ JsValue::UNDEFINED,
+ ))
+ .await,
+ );
+ assert_eq!(
+ base["data"]["user"]["soup"]["items"][0]["properties"][0]["displayName"],
+ "Status"
+ );
+
+ close_and_destroy(&reopened, SCOPE).await;
+}
+
+#[wasm_bindgen_test(async)]
+async fn optimistic_commit_reports_affected_ops_and_rejects_settled_or_malformed_ids() {
+ const SCOPE: &str = "cache-wasm-wp07-optimistic-commit";
+ let engine = fresh_engine(SCOPE).await;
+ let vars = variables();
+ resolved(engine.write_query(
+ None,
+ PROPERTY_QUERY.into(),
+ Some("Soup".into()),
+ js(vars.clone()),
+ js(property_base()),
+ None,
+ ))
+ .await;
+ resolved(engine.read_query(
+ Some("tab:optimistic".into()),
+ PROPERTY_QUERY.into(),
+ Some("Soup".into()),
+ js(vars.clone()),
+ JsValue::UNDEFINED,
+ ))
+ .await;
+
+ let enqueue: serde_json::Value = from_js(
+ resolved(engine.enqueue_optimistic_mutation(
+ None,
+ PROPERTY_MUTATION.into(),
+ Some("SetEntityProperty".into()),
+ js(mutation_variables()),
+ js(serde_json::json!({
+ "setEntityProperty": { "id": "prop-1", "displayName": "Stage" }
+ })),
+ JsValue::UNDEFINED,
+ JsValue::UNDEFINED,
+ 123.0,
+ "runner".into(),
+ 10.0,
+ 1_000.0,
+ ))
+ .await,
+ );
+ let transaction_id = enqueue["transactionId"].as_str().unwrap().to_owned();
+ let generation = enqueue["initialClaim"]["mutation"]["leaseGeneration"]
+ .as_str()
+ .unwrap()
+ .to_owned();
+ assert_eq!(
+ enqueue["affectedOps"],
+ serde_json::json!(["tab:optimistic"])
+ );
+
+ let commit: serde_json::Value = from_js(
+ resolved(engine.commit_optimistic_write(
+ transaction_id.clone(),
+ "runner".into(),
+ generation.clone(),
+ PROPERTY_MUTATION.into(),
+ Some("SetEntityProperty".into()),
+ js(mutation_variables()),
+ js(serde_json::json!({
+ "setEntityProperty": { "id": "prop-1", "displayName": "Stage!" }
+ })),
+ ))
+ .await,
+ );
+ assert_eq!(
+ commit["changed"],
+ serde_json::json!(["GraphqlProperty:prop-1"])
+ );
+ assert_eq!(commit["affectedOps"], serde_json::json!(["tab:optimistic"]));
+
+ let read: serde_json::Value = from_js(
+ resolved(engine.read_query(
+ Some("tab:optimistic".into()),
+ PROPERTY_QUERY.into(),
+ Some("Soup".into()),
+ js(vars),
+ JsValue::UNDEFINED,
+ ))
+ .await,
+ );
+ assert_eq!(
+ read["data"]["user"]["soup"]["items"][0]["properties"][0]["displayName"],
+ "Stage!"
+ );
+
+ assert!(
+ JsFuture::from(engine.rollback_optimistic_write(
+ transaction_id,
+ "runner".into(),
+ generation,
+ ))
+ .await
+ .is_err()
+ );
+ assert!(
+ JsFuture::from(engine.rollback_optimistic_write(
+ "not-a-number".into(),
+ "runner".into(),
+ "1".into(),
+ ))
+ .await
+ .is_err()
+ );
+
+ close_and_destroy(&engine, SCOPE).await;
+}
+
+#[wasm_bindgen_test(async)]
+async fn destroy_recovery_wipes_records_and_queue() {
+ const SCOPE: &str = "cache-wasm-wp07-destroy";
+ let engine = fresh_engine(SCOPE).await;
+ resolved(engine.write_query(
+ None,
+ PROPERTY_QUERY.into(),
+ Some("Soup".into()),
+ js(variables()),
+ js(property_base()),
+ Some("user-1".into()),
+ ))
+ .await;
+ resolved(engine.enqueue_optimistic_mutation(
+ None,
+ PROPERTY_MUTATION.into(),
+ Some("SetEntityProperty".into()),
+ js(mutation_variables()),
+ js(serde_json::json!({
+ "setEntityProperty": { "id": "prop-1", "displayName": "Queued" }
+ })),
+ JsValue::UNDEFINED,
+ JsValue::UNDEFINED,
+ 1.0,
+ "destroy-owner".into(),
+ 0.0,
+ 100.0,
+ ))
+ .await;
+ resolved(engine.close()).await;
+
+ destroy_cache(SCOPE.into()).await.expect("recovery wipe");
+ let replacement = open_cache(SCOPE.into(), None)
+ .await
+ .expect("open replacement");
+ let read: serde_json::Value = from_js(
+ resolved(replacement.read_query(
+ None,
+ QUERY.into(),
+ Some("Soup".into()),
+ js(variables()),
+ JsValue::UNDEFINED,
+ ))
+ .await,
+ );
+ assert_eq!(read["kind"], "miss");
+ let identity: Option<String> = from_js(resolved(replacement.bound_identity()).await);
+ assert_eq!(identity, None);
+ let claimed =
+ resolved(replacement.claim_next_mutation("replacement".into(), 100.0, 200.0)).await;
+ assert!(claimed.is_undefined() || claimed.is_null());
+
+ close_and_destroy(&replacement, SCOPE).await;
+}
+
+#[wasm_bindgen_test(async)]
+async fn recovery_open_wipes_existing_data_before_opening_fresh_turso() {
+ const SCOPE: &str = "cache-wasm-wp08-recovery-open";
+ let engine = fresh_engine(SCOPE).await;
+ resolved(engine.write_query(
+ None,
+ QUERY.into(),
+ Some("Soup".into()),
+ js(variables()),
+ js(soup_data("must-be-wiped")),
+ Some("user-1".into()),
+ ))
+ .await;
+ resolved(engine.close()).await;
+
+ let replacement = open_cache_for_recovery(SCOPE.into(), None)
+ .await
+ .expect("atomic recovery open");
+ let read: serde_json::Value = from_js(
+ resolved(replacement.read_query(
+ None,
+ QUERY.into(),
+ Some("Soup".into()),
+ js(variables()),
+ JsValue::UNDEFINED,
+ ))
+ .await,
+ );
+ assert_eq!(read["kind"], "miss");
+ let identity: Option<String> = from_js(resolved(replacement.bound_identity()).await);
+ assert_eq!(identity, None);
+
+ close_and_destroy(&replacement, SCOPE).await;
+}
+
+#[wasm_bindgen_test(async)]
+async fn incompatible_initialization_resets_and_identity_reset_does_not_latch() {
+ const SCOPE: &str = "cache-wasm-wp07-resets";
+ let owner = OpfsOwner::acquire(&database_identity(SCOPE))
+ .await
+ .expect("acquire incompatible database")
+ .recovery_wipe()
+ .await
+ .expect("start incompatible database fresh");
+ let OpenResult::Ready(session) = owner.open().await.expect("open incompatible database") else {
+ panic!("recovery wipe creates a complete pair")
+ };
+ let incompatible = TursoStorage::from_opfs_session(
+ session.connect().expect("connect incompatible database"),
+ "different-scope",
+ )
+ .expect("initialize incompatible metadata");
+ let TursoStorageCloseOutcome::Healthy(closed) = incompatible
+ .try_close()
+ .expect("close incompatible database")
+ else {
+ panic!("new incompatible database is otherwise healthy")
+ };
+ closed
+ .preserve()
+ .expect("preserve incompatible metadata")
+ .release()
+ .await
+ .expect("release incompatible owner");
+
+ let engine = open_cache(SCOPE.into(), None)
+ .await
+ .expect("incompatible initialization is reset and reopened");
+ let read: serde_json::Value = from_js(
+ resolved(engine.read_query(
+ None,
+ QUERY.into(),
+ Some("Soup".into()),
+ js(variables()),
+ JsValue::UNDEFINED,
+ ))
+ .await,
+ );
+ assert_eq!(read["kind"], "miss");
+
+ let first_identity: serde_json::Value = from_js(
+ resolved(engine.write_query(
+ None,
+ QUERY.into(),
+ Some("Soup".into()),
+ js(variables()),
+ js(soup_data("identity-a")),
+ Some("identity-a".into()),
+ ))
+ .await,
+ );
+ assert_eq!(first_identity["reset"], false);
+ let normal_identity_reset: serde_json::Value = from_js(
+ resolved(engine.write_query(
+ None,
+ QUERY.into(),
+ Some("Soup".into()),
+ js(variables()),
+ js(soup_data("identity-b")),
+ Some("identity-b".into()),
+ ))
+ .await,
+ );
+ assert_eq!(normal_identity_reset["reset"], true);
+ let identity: Option<String> = from_js(resolved(engine.bound_identity()).await);
+ assert_eq!(identity.as_deref(), Some("identity-b"));
+
+ close_and_destroy(&engine, SCOPE).await;
+}
+
+#[wasm_bindgen_test(async)]
+async fn storage_reset_errors_latch_and_block_hot_read_write_and_control_methods() {
+ const SCOPE: &str = "cache-wasm-wp07-reset-latch";
+ let engine = fresh_engine(SCOPE).await;
+ resolved(engine.write_query(
+ None,
+ QUERY.into(),
+ Some("Soup".into()),
+ js(variables()),
+ js(soup_data("reset-latch")),
+ Some("identity".into()),
+ ))
+ .await;
+ resolved(engine.invalidate_keys(vec!["GraphqlSoupDocument:reset-latch".into()])).await;
+ engine.arm_storage_fault(TestStorageFault::GetBatch).await;
+
+ assert_reset_required(engine.read_query(
+ Some("tab:latched".into()),
+ QUERY.into(),
+ Some("Soup".into()),
+ js(variables()),
+ JsValue::UNDEFINED,
+ ))
+ .await;
+ assert_reset_required(engine.bound_identity()).await;
+ assert_reset_required(engine.invalidate_keys(vec!["GraphqlSoupDocument:any".into()])).await;
+ assert_reset_required(engine.external_reset()).await;
+ assert_reset_required(engine.teardown_operation("tab:latched".into())).await;
+ assert_reset_required(engine.read_query(
+ None,
+ QUERY.into(),
+ Some("Soup".into()),
+ JsValue::from_str("malformed variables must not mask the latch"),
+ JsValue::UNDEFINED,
+ ))
+ .await;
+ assert_reset_required(engine.write_query(
+ None,
+ QUERY.into(),
+ Some("Soup".into()),
+ js(variables()),
+ js(soup_data("blocked")),
+ None,
+ ))
+ .await;
+ assert_reset_required(engine.clear()).await;
+
+ resolved(engine.physical_reset()).await;
+ let identity: Option<String> = from_js(resolved(engine.bound_identity()).await);
+ assert_eq!(identity, None);
+
+ resolved(engine.write_query(
+ None,
+ PROPERTY_QUERY.into(),
+ Some("Soup".into()),
+ js(variables()),
+ js(property_base()),
+ None,
+ ))
+ .await;
+ engine
+ .arm_storage_fault(TestStorageFault::ClaimNextMutation)
+ .await;
+ assert_reset_required(engine.enqueue_optimistic_mutation(
+ None,
+ PROPERTY_MUTATION.into(),
+ Some("SetEntityProperty".into()),
+ js(mutation_variables()),
+ js(serde_json::json!({
+ "setEntityProperty": { "id": "prop-1", "displayName": "Nested" }
+ })),
+ JsValue::UNDEFINED,
+ JsValue::UNDEFINED,
+ 1.0,
+ "nested-owner".into(),
+ 0.0,
+ 100.0,
+ ))
+ .await;
+ assert_reset_required(engine.bound_identity()).await;
+
+ resolved(engine.physical_reset()).await;
+ close_and_destroy(&engine, SCOPE).await;
+}
+
+#[wasm_bindgen_test(async)]
+async fn physical_reset_serializes_recreates_and_preserves_interner_registration() {
+ const SCOPE: &str = "cache-wasm-wp07-physical-reset";
+ let engine = fresh_engine(SCOPE).await;
+ resolved(engine.write_query(
+ None,
+ PROPERTY_QUERY.into(),
+ Some("Soup".into()),
+ js(variables()),
+ js(property_base()),
+ None,
+ ))
+ .await;
+ resolved(engine.read_query(
+ Some("tab:retained".into()),
+ PROPERTY_QUERY.into(),
+ Some("Soup".into()),
+ js(variables()),
+ JsValue::UNDEFINED,
+ ))
+ .await;
+ let retained_id = *engine
+ .ops
+ .borrow()
+ .by_name
+ .get("tab:retained")
+ .expect("operation is interned before reset");
+ resolved(engine.enqueue_optimistic_mutation(
+ None,
+ PROPERTY_MUTATION.into(),
+ Some("SetEntityProperty".into()),
+ js(mutation_variables()),
+ js(serde_json::json!({
+ "setEntityProperty": { "id": "prop-1", "displayName": "Queued" }
+ })),
+ JsValue::UNDEFINED,
+ JsValue::UNDEFINED,
+ 1.0,
+ "reset-owner".into(),
+ 0.0,
+ 100.0,
+ ))
+ .await;
+
+ let concurrent = js_sys::Array::new();
+ concurrent.push(&engine.physical_reset());
+ concurrent.push(&engine.write_query(
+ None,
+ PROPERTY_QUERY.into(),
+ Some("Soup".into()),
+ js(variables()),
+ js(property_base()),
+ None,
+ ));
+ JsFuture::from(js_sys::Promise::all(&concurrent))
+ .await
+ .expect("concurrent call waits for physical reset and uses the replacement");
+
+ assert_eq!(
+ engine.ops.borrow().by_name.get("tab:retained"),
+ Some(&retained_id)
+ );
+ let claimed = resolved(engine.claim_next_mutation("replacement".into(), 100.0, 200.0)).await;
+ assert!(claimed.is_undefined() || claimed.is_null());
+
+ let read: serde_json::Value = from_js(
+ resolved(engine.read_query(
+ Some("tab:retained".into()),
+ PROPERTY_QUERY.into(),
+ Some("Soup".into()),
+ js(variables()),
+ JsValue::UNDEFINED,
+ ))
+ .await,
+ );
+ assert_eq!(read["kind"], "hit");
+ let write: serde_json::Value = from_js(
+ resolved(engine.write_query(
+ Some("tab:writer".into()),
+ PROPERTY_QUERY.into(),
+ Some("Soup".into()),
+ js(variables()),
+ js(property_data("Updated")),
+ None,
+ ))
+ .await,
+ );
+ assert_eq!(write["affectedOps"], serde_json::json!(["tab:retained"]));
+
+ close_and_destroy(&engine, SCOPE).await;
+}
+
+#[wasm_bindgen_test(async)]
+async fn zero_hot_capacity_rejects_before_opfs_and_does_not_leak_the_lock() {
+ const SCOPE: &str = "cache-wasm-wp07-zero-capacity";
+ destroy_cache(SCOPE.into())
+ .await
+ .expect("clean capacity test");
+ let error = match open_cache(SCOPE.into(), Some(0)).await {
+ Ok(_) => panic!("zero capacity must reject"),
+ Err(error) => error,
+ };
+ assert!(error.is_instance_of::<js_sys::Error>());
+ let message = js_sys::Reflect::get(&error, &JsValue::from_str("message"))
+ .unwrap()
+ .as_string()
+ .unwrap();
+ assert_eq!(message, "hot capacity must be greater than zero");
+
+ let engine = open_cache(SCOPE.into(), Some(1))
+ .await
+ .expect("valid open succeeds after rejected capacity");
+ close_and_destroy(&engine, SCOPE).await;
+}
+
+#[wasm_bindgen_test(async)]
+async fn every_method_rejects_after_consuming_close() {
+ const SCOPE: &str = "cache-wasm-wp07-closed";
+ let engine = fresh_engine(SCOPE).await;
+ resolved(engine.close()).await;
+
+ assert_closed(engine.bound_identity()).await;
+ assert_closed(engine.read_query(
+ None,
+ QUERY.into(),
+ Some("Soup".into()),
+ js(variables()),
+ JsValue::UNDEFINED,
+ ))
+ .await;
+ assert_closed(engine.read_records(
+ RECORD_FRAGMENT.into(),
+ "CachedDocument".into(),
+ JsValue::UNDEFINED,
+ 1,
+ ))
+ .await;
+ assert_closed(engine.write_query(
+ None,
+ QUERY.into(),
+ Some("Soup".into()),
+ js(variables()),
+ js(soup_data("closed")),
+ None,
+ ))
+ .await;
+ assert_closed(engine.enqueue_optimistic_mutation(
+ None,
+ PROPERTY_MUTATION.into(),
+ Some("SetEntityProperty".into()),
+ js(mutation_variables()),
+ js(serde_json::json!({
+ "setEntityProperty": { "id": "prop-1", "displayName": "Closed" }
+ })),
+ JsValue::UNDEFINED,
+ JsValue::UNDEFINED,
+ 1.0,
+ "closed".into(),
+ 1.0,
+ 2.0,
+ ))
+ .await;
+ assert_closed(engine.inspect_query_variants(
+ QUERY.into(),
+ Some("Soup".into()),
+ js(serde_json::json!([{"field": "user"}, {"field": "soup"}])),
+ ))
+ .await;
+ assert_closed(engine.inspect_query(
+ QUERY.into(),
+ Some("Soup".into()),
+ js(serde_json::json!([{"field": "user"}, {"field": "soup"}])),
+ js(serde_json::json!([])),
+ ))
+ .await;
+ assert_closed(engine.claim_next_mutation("closed".into(), 1.0, 2.0)).await;
+ assert_closed(engine.defer_optimistic_write(
+ "1".into(),
+ "closed".into(),
+ "1".into(),
+ 2.0,
+ "closed".into(),
+ ))
+ .await;
+ assert_closed(engine.commit_optimistic_write(
+ "1".into(),
+ "closed".into(),
+ "1".into(),
+ PROPERTY_MUTATION.into(),
+ Some("SetEntityProperty".into()),
+ js(mutation_variables()),
+ js(serde_json::json!({
+ "setEntityProperty": { "id": "prop-1", "displayName": "Closed" }
+ })),
+ ))
+ .await;
+ assert_closed(engine.rollback_optimistic_write("1".into(), "closed".into(), "1".into())).await;
+ assert_closed(engine.invalidate_keys(vec!["GraphqlSoupDocument:1".into()])).await;
+ assert_closed(engine.delete_keys(vec!["GraphqlSoupDocument:1".into()])).await;
+ assert_closed(engine.refresh_optimistic_queue()).await;
+ assert_closed(engine.external_reset()).await;
+ assert_closed(engine.teardown_operation("closed:1".into())).await;
+ assert_closed(engine.clear()).await;
+ assert_closed(engine.physical_reset()).await;
+ assert_closed(engine.close()).await;
+
+ destroy_cache(SCOPE.into())
+ .await
+ .expect("destroy closed cache");
+}
+
+#[wasm_bindgen_test(async)]
+async fn calls_serialize_and_owner_lock_excludes_a_second_open() {
+ const SCOPE: &str = "cache-wasm-wp07-serialization-lock";
+ let engine = fresh_engine(SCOPE).await;
+ assert!(open_cache(SCOPE.into(), None).await.is_err());
+
+ let writes = js_sys::Array::new();
+ writes.push(&engine.write_query(
+ None,
+ QUERY.into(),
+ Some("Soup".into()),
+ js(variables()),
+ js(soup_data("first")),
+ None,
+ ));
+ writes.push(&engine.write_query(
+ None,
+ QUERY.into(),
+ Some("Soup".into()),
+ js(variables()),
+ js(soup_data("second")),
+ None,
+ ));
+ JsFuture::from(js_sys::Promise::all(&writes))
+ .await
+ .expect("overlapping calls serialize without reentrancy");
+
+ let read: serde_json::Value = from_js(
+ resolved(engine.read_query(
+ None,
+ QUERY.into(),
+ Some("Soup".into()),
+ js(variables()),
+ JsValue::UNDEFINED,
+ ))
+ .await,
+ );
+ assert_eq!(read["data"], soup_data("second"));
+
+ resolved(engine.close()).await;
+ let reopened = open_cache(SCOPE.into(), None)
+ .await
+ .expect("close releases owner lock");
+ close_and_destroy(&reopened, SCOPE).await;
+}
diff --git a/crates/client/cache-wasm/src/shell/test_storage.rs b/crates/client/cache-wasm/src/shell/test_storage.rs
new file mode 100644
index 0000000000..dc4428b7a9
--- /dev/null
+++ b/crates/client/cache-wasm/src/shell/test_storage.rs
@@ -0,0 +1,135 @@
+use cache_core::queue::{
+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, NewQueuedMutation,
+ QueuedMutation,
+};
+use cache_core::store::{QueueDiagnostics, Storage};
+use cache_core::value::{EntityKey, Record};
+use cache_turso::{PhysicalResetReason, TursoStorage, TursoStorageError};
+use std::sync::atomic::{AtomicU8, Ordering};
+
+#[derive(Clone, Copy)]
+pub(super) enum TestStorageFault {
+ GetBatch = 1,
+ ClaimNextMutation = 2,
+}
+
+pub(super) struct BrowserStorage {
+ inner: TursoStorage,
+ fault: AtomicU8,
+}
+
+impl BrowserStorage {
+ pub(super) fn new(inner: TursoStorage) -> Self {
+ Self {
+ inner,
+ fault: AtomicU8::new(0),
+ }
+ }
+
+ pub(super) fn into_inner(self) -> TursoStorage {
+ self.inner
+ }
+
+ pub(super) fn arm(&self, fault: TestStorageFault) {
+ self.fault.store(fault as u8, Ordering::Release);
+ }
+
+ fn take(&self, fault: TestStorageFault) -> Result<(), TursoStorageError> {
+ if self
+ .fault
+ .compare_exchange(fault as u8, 0, Ordering::AcqRel, Ordering::Acquire)
+ .is_ok()
+ {
+ Err(TursoStorageError::PhysicalResetRequired(
+ PhysicalResetReason::Codec,
+ ))
+ } else {
+ Ok(())
+ }
+ }
+}
+
+impl Storage for BrowserStorage {
+ type Error = TursoStorageError;
+
+ async fn get_batch(&self, keys: &[EntityKey<'_>]) -> Result<Vec<Option<Record>>, Self::Error> {
+ self.take(TestStorageFault::GetBatch)?;
+ self.inner.get_batch(keys).await
+ }
+
+ async fn put_batch(
+ &mut self,
+ entries: Vec<(EntityKey<'static>, Record)>,
+ ) -> Result<(), Self::Error> {
+ self.inner.put_batch(entries).await
+ }
+
+ async fn delete_batch(&mut self, keys: &[EntityKey<'static>]) -> Result<(), Self::Error> {
+ self.inner.delete_batch(keys).await
+ }
+
+ async fn scan_records(
+ &self,
+ type_names: &[String],
+ after: Option<&EntityKey<'static>>,
+ limit: usize,
+ ) -> Result<Vec<(EntityKey<'static>, Record)>, Self::Error> {
+ self.inner.scan_records(type_names, after, limit).await
+ }
+
+ async fn enqueue_mutation(
+ &mut self,
+ entry: NewQueuedMutation,
+ ) -> Result<MutationId, Self::Error> {
+ self.inner.enqueue_mutation(entry).await
+ }
+
+ async fn load_mutation_queue(&self) -> Result<Vec<QueuedMutation>, Self::Error> {
+ self.inner.load_mutation_queue().await
+ }
+
+ async fn queue_diagnostics(&self) -> Result<QueueDiagnostics, Self::Error> {
+ self.inner.queue_diagnostics().await
+ }
+
+ async fn claim_next_mutation(
+ &mut self,
+ request: MutationClaimRequest,
+ ) -> Result<Option<ClaimedMutation>, Self::Error> {
+ self.take(TestStorageFault::ClaimNextMutation)?;
+ self.inner.claim_next_mutation(request).await
+ }
+
+ async fn defer_mutation(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ next_attempt_at_ms: i64,
+ error: String,
+ ) -> Result<bool, Self::Error> {
+ self.inner
+ .defer_mutation(id, claim, next_attempt_at_ms, error)
+ .await
+ }
+
+ async fn complete_mutation(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ entries: Vec<(EntityKey<'static>, Record)>,
+ ) -> Result<bool, Self::Error> {
+ self.inner.complete_mutation(id, claim, entries).await
+ }
+
+ async fn discard_mutation(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ ) -> Result<bool, Self::Error> {
+ self.inner.discard_mutation(id, claim).await
+ }
+
+ async fn clear(&mut self) -> Result<(), Self::Error> {
+ self.inner.clear().await
+ }
+}
diff --git a/crates/client/cache-wasm/tests/web.rs b/crates/client/cache-wasm/tests/web.rs
deleted file mode 100644
index efd6a5f867..0000000000
--- a/crates/client/cache-wasm/tests/web.rs
+++ /dev/null
@@ -1,361 +0,0 @@
-//! Browser tests for the wasm shell (JsValue boundary + async mutex).
-//! Run like cache-idb's tests (see workspace README).
-
-#![cfg(target_arch = "wasm32")]
-
-use cache_wasm::{destroy_cache, open_cache};
-use wasm_bindgen::JsValue;
-use wasm_bindgen_futures::JsFuture;
-use wasm_bindgen_test::*;
-
-wasm_bindgen_test_configure!(run_in_browser);
-
-const QUERY: &str = r#"query Soup($input: SoupInput!) {
- user {
- id
- soup(input: $input) {
- nextCursor
- items {
- __typename
- id
- }
- }
- }
-}"#;
-
-fn js(json: serde_json::Value) -> JsValue {
- use serde::Serialize;
- json.serialize(&serde_wasm_bindgen::Serializer::json_compatible())
- .unwrap()
-}
-
-#[wasm_bindgen_test]
-async fn write_then_read_through_js_boundary() {
- destroy_cache("wasm-shell-test".into()).await.unwrap();
- let engine = open_cache("wasm-shell-test".into(), None).await.unwrap();
-
- let vars = serde_json::json!({"input": {"limit": 1}});
- let data = serde_json::json!({
- "user": {
- "id": "user-1",
- "soup": {
- "nextCursor": null,
- "items": [{ "__typename": "GraphqlSoupDocument", "id": "doc-1" }]
- }
- }
- });
-
- // Miss first.
- let read = JsFuture::from(engine.read_query(
- Some("tab1:1".into()),
- QUERY.into(),
- Some("Soup".into()),
- js(vars.clone()),
- JsValue::UNDEFINED,
- ))
- .await
- .unwrap();
- let read: serde_json::Value = serde_wasm_bindgen::from_value(read).unwrap();
- assert_eq!(read["kind"], "miss");
-
- // Write via op 2 (tagged with the viewer identity), expect op 1
- // affected (registered on the miss).
- let write = JsFuture::from(engine.write_query(
- Some("tab1:2".into()),
- QUERY.into(),
- Some("Soup".into()),
- js(vars.clone()),
- js(data.clone()),
- Some("user-1".into()),
- ))
- .await
- .unwrap();
- let write: serde_json::Value = serde_wasm_bindgen::from_value(write).unwrap();
- assert!(!write["changed"].as_array().unwrap().is_empty());
- assert_eq!(write["affectedOps"], serde_json::json!(["tab1:1"]));
- assert_eq!(write["reset"], serde_json::json!(false));
-
- let identity = JsFuture::from(engine.bound_identity()).await.unwrap();
- let identity: Option<String> = serde_wasm_bindgen::from_value(identity).unwrap();
- assert_eq!(identity.as_deref(), Some("user-1"));
-
- // Hit now; data is a plain JS object round-tripped exactly.
- let read = JsFuture::from(engine.read_query(
- Some("tab1:1".into()),
- QUERY.into(),
- Some("Soup".into()),
- js(vars.clone()),
- JsValue::UNDEFINED,
- ))
- .await
- .unwrap();
- let read: serde_json::Value = serde_wasm_bindgen::from_value(read).unwrap();
- assert_eq!(read["kind"], "hit");
- assert_eq!(read["data"], data);
-
- // Variables-only inspection crosses the wasm boundary without
- // materializing the selected value.
- let variants = JsFuture::from(engine.inspect_query_variants(
- QUERY.into(),
- Some("Soup".into()),
- js(serde_json::json!([{"field": "user"}, {"field": "soup"}])),
- ))
- .await
- .unwrap();
- let variants: serde_json::Value = serde_wasm_bindgen::from_value(variants).unwrap();
- assert_eq!(variants[0]["variables"], vars);
- assert!(variants[0].get("value").is_none());
-
- // Full generated-query inspection also materializes the selected value.
- let inspected = JsFuture::from(engine.inspect_query(
- QUERY.into(),
- Some("Soup".into()),
- js(serde_json::json!([{"field": "user"}, {"field": "soup"}])),
- js(serde_json::json!([])),
- ))
- .await
- .unwrap();
- let inspected: serde_json::Value = serde_wasm_bindgen::from_value(inspected).unwrap();
- assert_eq!(inspected[0]["variables"], vars);
- assert_eq!(inspected[0]["value"], data["user"]["soup"]);
-
- // Cross-instance invalidation path: evict + report local dependents.
- let affected =
- JsFuture::from(engine.invalidate_keys(vec!["GraphqlSoupDocument:doc-1".to_string()]))
- .await
- .unwrap();
- let affected: Vec<String> = serde_wasm_bindgen::from_value(affected).unwrap();
- assert_eq!(affected, vec!["tab1:1".to_string()]);
-
- // External invalidation keeps the shared cold-tier record, while local
- // mutation invalidation removes it from both tiers.
- let read = JsFuture::from(engine.read_query(
- Some("tab1:1".into()),
- QUERY.into(),
- Some("Soup".into()),
- js(vars.clone()),
- JsValue::UNDEFINED,
- ))
- .await
- .unwrap();
- let read: serde_json::Value = serde_wasm_bindgen::from_value(read).unwrap();
- assert_eq!(read["kind"], "hit");
-
- JsFuture::from(engine.delete_keys(vec!["GraphqlSoupDocument:doc-1".to_string()]))
- .await
- .unwrap();
- let read = JsFuture::from(engine.read_query(
- Some("tab1:1".into()),
- QUERY.into(),
- Some("Soup".into()),
- js(vars),
- JsValue::UNDEFINED,
- ))
- .await
- .unwrap();
- let read: serde_json::Value = serde_wasm_bindgen::from_value(read).unwrap();
- assert_eq!(read["kind"], "miss");
-
- // Lifecycle: close the connection, then deletion completes (would hang
- // on a live connection without versionchange auto-close).
- JsFuture::from(engine.close()).await.unwrap();
- destroy_cache("wasm-shell-test".into()).await.unwrap();
-}
-
-#[wasm_bindgen_test]
-async fn entity_resolvers_cross_the_js_boundary() {
- destroy_cache("wasm-shell-entity-resolver".into())
- .await
- .unwrap();
- let engine = open_cache("wasm-shell-entity-resolver".into(), None)
- .await
- .unwrap();
- let soup_variables = serde_json::json!({"input": {"limit": 1}});
- JsFuture::from(engine.write_query(
- None,
- QUERY.into(),
- Some("Soup".into()),
- js(soup_variables),
- js(serde_json::json!({
- "user": {
- "id": "user-1",
- "soup": {
- "nextCursor": null,
- "items": [{
- "__typename": "GraphqlSoupEmailThread",
- "id": "thread-1"
- }]
- }
- }
- })),
- None,
- ))
- .await
- .unwrap();
-
- let direct_query = r#"query Email($input: EmailThreadInput!) {
- user { id emailThread(input: $input) { __typename id } }
- }"#;
- let result = JsFuture::from(engine.read_query(
- Some("tab1:entity".into()),
- direct_query.into(),
- Some("Email".into()),
- js(serde_json::json!({"input": {"threadId": "thread-1"}})),
- js(serde_json::json!([{
- "parentType": "GraphqlUser",
- "fieldName": "emailThread",
- "targetType": "GraphqlSoupEmailThread",
- "argumentPath": ["input", "threadId"]
- }])),
- ))
- .await
- .unwrap();
- let result: serde_json::Value = serde_wasm_bindgen::from_value(result).unwrap();
- assert_eq!(result["kind"], "hit");
- assert_eq!(result["data"]["user"]["emailThread"]["id"], "thread-1");
-
- JsFuture::from(engine.close()).await.unwrap();
- destroy_cache("wasm-shell-entity-resolver".into())
- .await
- .unwrap();
-}
-
-const PROPERTY_QUERY: &str = r#"query Soup($input: SoupInput!) {
- user { id soup(input: $input) { nextCursor items {
- __typename
- id
- ... on GraphqlSoupDocument { properties { id displayName } }
- } } }
-}"#;
-
-const PROPERTY_MUTATION: &str = r#"mutation SetEntityProperty($input: SetEntityPropertyInput!) {
- setEntityProperty(input: $input) { id displayName }
-}"#;
-
-#[wasm_bindgen_test]
-async fn optimistic_write_round_trip() {
- destroy_cache("wasm-shell-optimistic".into()).await.unwrap();
- let engine = open_cache("wasm-shell-optimistic".into(), None)
- .await
- .unwrap();
-
- let vars = serde_json::json!({"input": {"limit": 1}});
- let base = serde_json::json!({
- "user": { "id": "user-1", "soup": { "nextCursor": null, "items": [{
- "__typename": "GraphqlSoupDocument",
- "id": "doc-1",
- "properties": [{ "id": "prop-1", "displayName": "Status" }]
- }] } }
- });
- JsFuture::from(engine.write_query(
- None,
- PROPERTY_QUERY.into(),
- Some("Soup".into()),
- js(vars.clone()),
- js(base),
- None,
- ))
- .await
- .unwrap();
- // Register op 1 against the property record.
- let read = JsFuture::from(engine.read_query(
- Some("tab1:1".into()),
- PROPERTY_QUERY.into(),
- Some("Soup".into()),
- js(vars.clone()),
- JsValue::UNDEFINED,
- ))
- .await
- .unwrap();
- let read: serde_json::Value = serde_wasm_bindgen::from_value(read).unwrap();
- assert_eq!(read["kind"], "hit");
-
- let mutation_vars = serde_json::json!({"input": {
- "entityType": "DOCUMENT",
- "entityId": "doc-1",
- "propertyDefinitionId": "def-1",
- "value": { "string": "x" }
- }});
-
- // Enqueue: op 1 is affected and the strict head is already claimed.
- let enqueue = JsFuture::from(engine.enqueue_optimistic_mutation(
- None,
- PROPERTY_MUTATION.into(),
- Some("SetEntityProperty".into()),
- js(mutation_vars.clone()),
- js(serde_json::json!({ "setEntityProperty": { "id": "prop-1", "displayName": "Stage" } })),
- JsValue::UNDEFINED,
- JsValue::UNDEFINED,
- 123.0,
- "runner".into(),
- 10.0,
- 1_000.0,
- ))
- .await
- .unwrap();
- let enqueue: serde_json::Value = serde_wasm_bindgen::from_value(enqueue).unwrap();
- let txn = enqueue["transactionId"].as_str().unwrap().to_string();
- assert_eq!(enqueue["affectedOps"], serde_json::json!(["tab1:1"]));
- assert_eq!(
- enqueue["changed"],
- serde_json::json!(["GraphqlProperty:prop-1"])
- );
- assert_eq!(enqueue["initialClaim"]["kind"], "claimed");
- assert_eq!(enqueue["initialClaim"]["mutation"]["transactionId"], txn);
-
- // The optimistic layer is visible through reads.
- let read = JsFuture::from(engine.read_query(
- Some("tab1:1".into()),
- PROPERTY_QUERY.into(),
- Some("Soup".into()),
- js(vars.clone()),
- JsValue::UNDEFINED,
- ))
- .await
- .unwrap();
- let read: serde_json::Value = serde_wasm_bindgen::from_value(read).unwrap();
- assert_eq!(
- read["data"]["user"]["soup"]["items"][0]["properties"][0]["displayName"],
- serde_json::json!("Stage")
- );
-
- let generation = enqueue["initialClaim"]["mutation"]["leaseGeneration"]
- .as_str()
- .unwrap()
- .to_string();
-
- // Commit with the real response; the layer flushes durably.
- let commit = JsFuture::from(engine.commit_optimistic_write(
- txn.clone(),
- "runner".into(),
- generation.clone(),
- PROPERTY_MUTATION.into(),
- Some("SetEntityProperty".into()),
- js(mutation_vars.clone()),
- js(serde_json::json!({ "setEntityProperty": { "id": "prop-1", "displayName": "Stage!" } })),
- ))
- .await
- .unwrap();
- let commit: serde_json::Value = serde_wasm_bindgen::from_value(commit).unwrap();
- assert_eq!(
- commit["changed"],
- serde_json::json!(["GraphqlProperty:prop-1"])
- );
- assert_eq!(commit["affectedOps"], serde_json::json!(["tab1:1"]));
-
- // Settled transactions reject further commits/rollbacks.
- let err =
- JsFuture::from(engine.rollback_optimistic_write(txn, "runner".into(), generation)).await;
- assert!(err.is_err());
- // Malformed ids reject too.
- let err = JsFuture::from(engine.rollback_optimistic_write(
- "not-a-number".into(),
- "runner".into(),
- "1".into(),
- ))
- .await;
- assert!(err.is_err());
-
- JsFuture::from(engine.close()).await.unwrap();
- destroy_cache("wasm-shell-optimistic".into()).await.unwrap();
-}
diff --git a/crates/client/turso-opfs/Cargo.toml b/crates/client/turso-opfs/Cargo.toml
new file mode 100644
index 0000000000..545129891d
--- /dev/null
+++ b/crates/client/turso-opfs/Cargo.toml
@@ -0,0 +1,33 @@
+[package]
+edition = "2024"
+name = "turso-opfs"
+publish = false
+version = "0.1.0"
+
+# Production code is wasm32-only. The target-independent lifecycle machine is
+# compiled natively only for its unit tests.
+
+[target.'cfg(target_arch = "wasm32")'.dependencies]
+js-sys = { workspace = true }
+turso_core = { workspace = true, features = ["fs", "uuid"] }
+wasm-bindgen = { workspace = true }
+wasm-bindgen-futures = { workspace = true }
+web-sys = { workspace = true, features = [
+ "AbortController",
+ "AbortSignal",
+ "DedicatedWorkerGlobalScope",
+ "DomException",
+ "FileSystemDirectoryHandle",
+ "FileSystemFileHandle",
+ "FileSystemGetDirectoryOptions",
+ "FileSystemGetFileOptions",
+ "FileSystemReadWriteOptions",
+ "FileSystemRemoveOptions",
+ "FileSystemSyncAccessHandle",
+ "StorageManager",
+ "WorkerGlobalScope",
+ "WorkerNavigator",
+] }
+
+[target.'cfg(target_arch = "wasm32")'.dev-dependencies]
+wasm-bindgen-test = { workspace = true }
diff --git a/crates/client/turso-opfs/README.md b/crates/client/turso-opfs/README.md
new file mode 100644
index 0000000000..187874d610
--- /dev/null
+++ b/crates/client/turso-opfs/README.md
@@ -0,0 +1,60 @@
+# turso-opfs
+
+Browser-only Turso `Clock`/`IO`/`File` adapter for DedicatedWorker-owned OPFS.
+
+## Ownership and recovery boundary
+
+`OpfsOwner::acquire(database_identity)` validates one direct-child canonical
+identity (reserving the `-wal` suffix) and derives both the exclusive Web Lock
+name and main/WAL paths from it. There are no independent scope/path inputs or
+main-as-WAL aliases that could map the same files to different locks. `open()`
+accepts no path argument. The lock remains held
+through Turso use, consuming close, preserve/reset, and idle ownership, and is
+released only by `OpfsOwner::release()`.
+
+`OpfsSession::connect()` constructs the approved Turso dialect/options and
+private OPFS storage internally. Callers must never invoke `Connection::close`
+directly; `ConnectedOpfsSession::try_close()` exclusively owns and proves that
+transition. Turso open/connect failures poison and require worker replacement
+followed by a fresh lock acquisition and `recovery_wipe()`.
+
+The crate tests physical lock contention in its real DedicatedWorker. Actual
+cross-worker termination/restart orchestration remains a WP-08 coordinator
+harness responsibility: terminating a worker causes the browser to release its
+Web Lock and worker-local JavaScript handles, after which the replacement worker
+must acquire the same canonical database lock and call `recovery_wipe()` when the
+coordinator selected wipe-before-open. Local tests do not claim cross-worker
+termination proof.
+
+## Repeatable verification
+
+Run from the repository root:
+
+```bash
+cargo fmt -p turso-opfs -- --check
+cargo test -p turso-opfs
+cargo clippy -p turso-opfs --all-targets -- -D warnings
+cargo check --target wasm32-unknown-unknown -p turso-opfs --all-targets
+cargo clippy --target wasm32-unknown-unknown -p turso-opfs --all-targets -- -D warnings
+
+# Each command compiles and runs the same #[wasm_bindgen_test] in a real
+# DedicatedWorker with that browser's OPFS and Web Locks implementations.
+wasm-pack test --headless --chrome crates/client/turso-opfs
+wasm-pack test --headless --firefox crates/client/turso-opfs
+```
+
+On NixOS, `wasm-pack`'s downloaded WebDrivers may not have a runnable ELF
+interpreter. Use the wasm-bindgen test runner with Nix-provided drivers instead:
+
+```bash
+CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER=wasm-bindgen-test-runner \
+CHROMEDRIVER=/path/to/nix/chromedriver \
+WASM_BINDGEN_TEST_ONLY_WEB=1 \
+cargo test --target wasm32-unknown-unknown -p turso-opfs --lib -- --nocapture
+
+PATH=/path/to/nix/firefox:$PATH \
+CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER=wasm-bindgen-test-runner \
+GECKODRIVER=/path/to/nix/geckodriver \
+WASM_BINDGEN_TEST_ONLY_WEB=1 \
+cargo test --target wasm32-unknown-unknown -p turso-opfs --lib -- --nocapture
+```
diff --git a/crates/client/turso-opfs/src/browser.rs b/crates/client/turso-opfs/src/browser.rs
new file mode 100644
index 0000000000..2aa8d74461
--- /dev/null
+++ b/crates/client/turso-opfs/src/browser.rs
@@ -0,0 +1,2265 @@
+//! `wasm32` DedicatedWorker OPFS implementation.
+
+use crate::state::{
+ CloseToken, FileRole, HandleId, Machine, OwnerId, Paths, SessionId, StateError, StateErrorKind,
+};
+use js_sys::{Function, Object, Promise, Reflect};
+use std::{
+ cell::RefCell,
+ collections::HashMap,
+ fmt,
+ io::ErrorKind,
+ sync::{
+ Arc,
+ atomic::{AtomicU64, Ordering},
+ },
+};
+use turso_core::{
+ Buffer, Clock, Completion, CompletionError, Connection, Database, File, IO, LimboError,
+ MonotonicInstant, OpenFlags, OpenOptions, SqliteDialect, WallClockInstant,
+ io::{FileId, FileSyncType},
+};
+use wasm_bindgen::{JsCast, JsValue, closure::Closure, prelude::wasm_bindgen};
+use wasm_bindgen_futures::JsFuture;
+use web_sys::{
+ AbortController, DedicatedWorkerGlobalScope, DomException, FileSystemDirectoryHandle,
+ FileSystemFileHandle, FileSystemGetFileOptions, FileSystemReadWriteOptions,
+ FileSystemRemoveOptions, FileSystemSyncAccessHandle,
+};
+
+#[cfg(test)]
+mod test;
+
+const MAX_SAFE_INTEGER: u64 = 9_007_199_254_740_991;
+
+#[wasm_bindgen]
+extern "C" {
+ #[wasm_bindgen(js_namespace = performance, js_name = now)]
+ fn performance_now() -> f64;
+}
+
+/// Stable, payload-free error categories produced by the OPFS adapter.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum OpfsErrorKind {
+ /// The database filename is not an approved direct OPFS child name.
+ InvalidName,
+ /// Acquiring, validating, or releasing the canonical database Web Lock failed.
+ Lock,
+ /// The caller does not own the worker-local adapter.
+ Ownership,
+ /// A stale session, handle, or one-use close token was used.
+ Lifecycle,
+ /// A callback attempted to enter OPFS while another operation was active.
+ Reentrant,
+ /// Turso, I/O, or file references still exist at close time.
+ ActiveReferences,
+ /// Opening, connecting, or gracefully closing Turso failed.
+ Turso,
+ /// Opening or registering a sync access handle failed.
+ Open,
+ /// Reading an OPFS file failed.
+ Read,
+ /// Writing an OPFS file failed.
+ Write,
+ /// Flushing an OPFS file failed.
+ Flush,
+ /// Truncating an OPFS file failed.
+ Truncate,
+ /// Reading an OPFS file size failed.
+ Size,
+ /// Closing a sync access handle was uncertain.
+ Close,
+ /// Asynchronously removing a closed OPFS path failed.
+ Remove,
+ /// Asynchronously recreating a removed OPFS path failed.
+ Recreate,
+ /// Browser storage reported that its quota was full.
+ StorageFull,
+ /// The worker-local session is poisoned and cannot be reused.
+ Poisoned,
+ /// Turso requested a synchronous operation that this adapter forbids.
+ Unsupported,
+}
+
+/// A payload-free OPFS adapter error.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct OpfsError {
+ kind: OpfsErrorKind,
+ message: String,
+}
+
+impl OpfsError {
+ fn new(kind: OpfsErrorKind, message: impl Into<String>) -> Self {
+ Self {
+ kind,
+ message: message.into(),
+ }
+ }
+
+ /// Returns the stable error category.
+ pub fn kind(&self) -> OpfsErrorKind {
+ self.kind
+ }
+}
+
+impl fmt::Display for OpfsError {
+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+ formatter.write_str(&self.message)
+ }
+}
+
+impl std::error::Error for OpfsError {}
+
+/// Whether a complete pre-opened main/WAL pair was fresh or existing.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum OpenDisposition {
+ /// Neither path existed, or this pair was freshly recreated by reset/wipe.
+ Fresh,
+ /// Both approved paths already existed.
+ Existing,
+}
+
+/// Result of physically pre-opening the identity-bound main/WAL pair.
+#[derive(Debug)]
+pub enum OpenResult {
+ /// Both paths form a complete pair and may be connected to Turso.
+ Ready(OpfsSession),
+ /// Exactly one path pre-existed; only physical reset is permitted.
+ ResetRequired(ResetRequiredSession),
+}
+
+/// Exclusive canonical-database ownership backed by a held Web Lock.
+#[derive(Debug)]
+pub struct OpfsOwner {
+ id: OwnerId,
+ paths: Paths,
+ lock_name: String,
+ fresh: bool,
+ armed: bool,
+}
+
+impl OpfsOwner {
+ /// Acquires and holds this canonical database identity's exclusive Web Lock.
+ ///
+ /// The single validated identity derives both the physical main/WAL names
+ /// and the Web Lock name, so the same files cannot be opened under a
+ /// different lock. [`Self::open`] accepts no alternate path. The lock is
+ /// held across open, Turso use, close, preserve/reset, and idle ownership.
+ pub async fn acquire(database_identity: &str) -> Result<Self, OpfsError> {
+ let paths = approved_paths(database_identity)?;
+ let lock_name = owner_lock_name(database_identity);
+ let id = acquire_database_lock(database_identity, &lock_name).await?;
+ Ok(Self {
+ id,
+ paths,
+ lock_name,
+ fresh: false,
+ armed: true,
+ })
+ }
+
+ /// Returns the canonical database identity bound into this owner.
+ pub fn database_path(&self) -> &str {
+ self.paths.get(FileRole::Main)
+ }
+
+ /// Returns the exact exclusive Web Lock name held by this owner.
+ pub fn lock_name(&self) -> &str {
+ &self.lock_name
+ }
+
+ /// Physically wipes and recreates both approved paths before any open.
+ ///
+ /// This is the recovery path after abrupt worker loss or a pre-open entry
+ /// conflict. It recursively removes only the two direct, validated child
+ /// names. Cancellation or any partial remove/recreate failure poisons the
+ /// owner; a poisoned worker must be replaced.
+ pub async fn recovery_wipe(mut self) -> Result<Self, WipeFailure> {
+ REGISTRY
+ .with(|registry| {
+ registry
+ .borrow_mut()
+ .machine
+ .start_wipe(self.id, self.paths.clone())
+ })
+ .map_err(state_error)
+ .map_err(WipeFailure::new)?;
+ self.armed = false;
+ let mut guard = AsyncPoisonGuard::new(
+ self.id,
+ "recovery wipe cancelled or failed after entering Wiping",
+ );
+ reset_paths(&self.paths, true)
+ .await
+ .map_err(WipeFailure::new)?;
+ REGISTRY
+ .with(|registry| registry.borrow_mut().machine.finish_wipe(self.id))
+ .map_err(state_error)
+ .map_err(WipeFailure::new)?;
+ guard.disarm();
+ self.fresh = true;
+ self.armed = true;
+ Ok(self)
+ }
+
+ /// Pre-opens exactly this owner's bound main and WAL paths.
+ ///
+ /// A one-sided pre-existing pair returns [`OpenResult::ResetRequired`], a
+ /// type that exposes no Turso I/O and can only be physically reset.
+ pub async fn open(mut self) -> Result<OpenResult, OpenFailure> {
+ let paths = self.paths.clone();
+ let session = match REGISTRY.with(|registry| {
+ registry
+ .borrow_mut()
+ .machine
+ .start_open(self.id, paths.clone())
+ }) {
+ Ok(session) => session,
+ Err(error) => return Err(open_failure_after_cleanup(state_error(error), self)),
+ };
+
+ let root = match worker_root().await {
+ Ok(root) => root,
+ Err(error) => {
+ let adapter_error = js_error(OpfsErrorKind::Open, "OPFS root open", &error);
+ cleanup_failed_open(self.id, session, &adapter_error);
+ return Err(open_failure_after_cleanup(adapter_error, self));
+ }
+ };
+
+ let mut created = [false; 2];
+ for role in FileRole::ALL {
+ #[cfg(test)]
+ if take_open_failure(role) {
+ let error = OpfsError::new(OpfsErrorKind::Open, "injected OPFS pre-open failure");
+ cleanup_failed_open(self.id, session, &error);
+ return Err(open_failure_after_cleanup(error, self));
+ }
+
+ let (handle, was_created) = match open_sync_handle(&root, paths.get(role)).await {
+ Ok(value) => value,
+ Err(error) => {
+ let adapter_error =
+ js_error(OpfsErrorKind::Open, "OPFS sync handle open", &error);
+ cleanup_failed_open(self.id, session, &adapter_error);
+ return Err(open_failure_after_cleanup(adapter_error, self));
+ }
+ };
+ created[role.index()] = was_created;
+
+ let handle_id = match REGISTRY.with(|registry| {
+ registry
+ .borrow_mut()
+ .machine
+ .register(self.id, session, role)
+ }) {
+ Ok(handle_id) => handle_id,
+ Err(error) => {
+ let adapter_error = state_error(error);
+ let current_closed = close_sync_handle(&handle).is_ok();
+ cleanup_failed_open(self.id, session, &adapter_error);
+ if !current_closed {
+ poison(self.id, "unregistered sync handle close was uncertain");
+ }
+ return Err(open_failure_after_cleanup(adapter_error, self));
+ }
+ };
+ REGISTRY.with(|registry| {
+ registry
+ .borrow_mut()
+ .handles
+ .insert(handle_id, RegisteredHandle { role, handle });
+ });
+ }
+
+ let reset_only = created[0] != created[1];
+ if let Err(error) = REGISTRY.with(|registry| {
+ registry
+ .borrow_mut()
+ .machine
+ .activate(self.id, session, reset_only)
+ }) {
+ let adapter_error = state_error(error);
+ cleanup_failed_open(self.id, session, &adapter_error);
+ return Err(open_failure_after_cleanup(adapter_error, self));
+ }
+
+ let disposition = if self.fresh || created == [true, true] {
+ OpenDisposition::Fresh
+ } else {
+ OpenDisposition::Existing
+ };
+ self.armed = false;
+ if reset_only {
+ return Ok(OpenResult::ResetRequired(ResetRequiredSession {
+ owner: self.id,
+ session,
+ paths,
+ armed: true,
+ }));
+ }
+
+ let references = Arc::new(SessionReferences);
+ let io = Arc::new(OpfsIo {
+ owner: self.id,
+ session,
+ references: references.clone(),
+ last_monotonic_nanos: AtomicU64::new(0),
+ });
+ Ok(OpenResult::Ready(OpfsSession {
+ owner: self.id,
+ session,
+ paths,
+ disposition,
+ io,
+ references,
+ armed: true,
+ }))
+ }
+
+ /// Releases the idle owner and then proves its physical Web Lock request
+ /// completed. Cancellation after release begins poisons the registry.
+ pub async fn release(mut self) -> Result<(), OpfsError> {
+ self.armed = false;
+ let mut guard = AsyncPoisonGuard::new(
+ self.id,
+ "owner lock release cancelled before completion proof",
+ );
+ release_database_lock(self.id).await?;
+ REGISTRY
+ .with(|registry| registry.borrow_mut().machine.release_owner(self.id))
+ .map_err(state_error)?;
+ guard.disarm();
+ Ok(())
+ }
+}
+
+impl Drop for OpfsOwner {
+ fn drop(&mut self) {
+ if self.armed {
+ poison(self.id, "armed OPFS owner dropped without explicit release");
+ begin_database_lock_release(self.id);
+ }
+ }
+}
+
+/// A failure while asynchronously pre-opening main and WAL.
+#[derive(Debug)]
+pub struct OpenFailure {
+ error: OpfsError,
+ owner: Option<OpfsOwner>,
+}
+
+impl OpenFailure {
+ fn recoverable(error: OpfsError, owner: OpfsOwner) -> Self {
+ Self {
+ error,
+ owner: Some(owner),
+ }
+ }
+
+ fn poisoned(error: OpfsError) -> Self {
+ Self { error, owner: None }
+ }
+
+ /// Returns the classified adapter error.
+ pub fn error(&self) -> &OpfsError {
+ &self.error
+ }
+
+ /// Returns the idle owner only when partial-open cleanup was certain.
+ pub fn into_owner(mut self) -> Option<OpfsOwner> {
+ self.owner.take()
+ }
+}
+
+impl fmt::Display for OpenFailure {
+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+ self.error.fmt(formatter)
+ }
+}
+
+impl std::error::Error for OpenFailure {}
+
+/// A complete, identity-bound main/WAL session not yet connected to Turso.
+#[derive(Debug)]
+pub struct OpfsSession {
+ owner: OwnerId,
+ session: SessionId,
+ paths: Paths,
+ disposition: OpenDisposition,
+ io: Arc<OpfsIo>,
+ references: Arc<SessionReferences>,
+ armed: bool,
+}
+
+impl OpfsSession {
+ /// Returns the approved main database filename.
+ pub fn database_path(&self) -> &str {
+ self.paths.get(FileRole::Main)
+ }
+
+ /// Returns the approved WAL filename.
+ pub fn wal_path(&self) -> &str {
+ self.paths.get(FileRole::Wal)
+ }
+
+ /// Reports whether this complete pair was fresh or existing.
+ pub fn disposition(&self) -> OpenDisposition {
+ self.disposition
+ }
+
+ /// Opens exactly one production Turso database and connection bound to
+ /// this session's private I/O object.
+ ///
+ /// The adapter constructs the approved `SqliteDialect` and default Turso
+ /// options internally. Neither raw options, the database, nor raw I/O is
+ /// exposed. Any Turso open/storage/connect failure poisons the session;
+ /// recovery requires worker replacement and a new owner recovery wipe.
+ pub fn connect(mut self) -> Result<ConnectedOpfsSession, ConnectFailure> {
+ let options = OpenOptions::new(Arc::new(SqliteDialect));
+ let database =
+ match open_turso_database(self.io.clone(), self.paths.get(FileRole::Main), options) {
+ Ok(database) => database,
+ Err(error) => {
+ self.armed = false;
+ poison(
+ self.owner,
+ "Turso open/storage failure made session health uncertain",
+ );
+ return Err(ConnectFailure::poisoned(turso_error("open", error)));
+ }
+ };
+ let connection = match connect_turso_database(&database) {
+ Ok(connection) => connection,
+ Err(error) => {
+ drop(database);
+ self.armed = false;
+ poison(
+ self.owner,
+ "Turso connection failure made session health uncertain",
+ );
+ return Err(ConnectFailure::poisoned(turso_error("connect", error)));
+ }
+ };
+ if let Err(error) = REGISTRY.with(|registry| {
+ registry
+ .borrow_mut()
+ .machine
+ .bind_connection(self.owner, self.session)
+ }) {
+ let _ = connection.close();
+ drop(connection);
+ drop(database);
+ self.armed = false;
+ poison(
+ self.owner,
+ "connection binding did not match the OPFS session",
+ );
+ return Err(ConnectFailure::poisoned(state_error(error)));
+ }
+ self.armed = false;
+ Ok(ConnectedOpfsSession {
+ owner: self.owner,
+ session: self.session,
+ paths: self.paths.clone(),
+ disposition: self.disposition,
+ io: self.io.clone(),
+ references: self.references.clone(),
+ database: Some(database),
+ connection: Some(connection),
+ armed: true,
+ })
+ }
+}
+
+impl Drop for OpfsSession {
+ fn drop(&mut self) {
+ if self.armed {
+ poison(
+ self.owner,
+ "ready OPFS session dropped without creating and closing its Turso connection",
+ );
+ }
+ }
+}
+
+/// Failure while creating the session's sole production Turso connection.
+#[derive(Debug)]
+pub struct ConnectFailure {
+ error: OpfsError,
+}
+
+impl ConnectFailure {
+ fn poisoned(error: OpfsError) -> Self {
+ Self { error }
+ }
+
+ /// Returns the classified adapter error.
+ pub fn error(&self) -> &OpfsError {
+ &self.error
+ }
+}
+
+impl fmt::Display for ConnectFailure {
+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+ self.error.fmt(formatter)
+ }
+}
+
+impl std::error::Error for ConnectFailure {}
+
+/// Session owning the sole production Turso database and connection.
+pub struct ConnectedOpfsSession {
+ owner: OwnerId,
+ session: SessionId,
+ paths: Paths,
+ disposition: OpenDisposition,
+ io: Arc<OpfsIo>,
+ references: Arc<SessionReferences>,
+ database: Option<Arc<Database>>,
+ connection: Option<Arc<Connection>>,
+ armed: bool,
+}
+
+impl fmt::Debug for ConnectedOpfsSession {
+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+ formatter
+ .debug_struct("ConnectedOpfsSession")
+ .field("owner", &self.owner)
+ .field("session", &self.session)
+ .field("paths", &self.paths)
+ .field("disposition", &self.disposition)
+ .field("armed", &self.armed)
+ .finish_non_exhaustive()
+ }
+}
+
+impl ConnectedOpfsSession {
+ /// Returns the approved main database filename.
+ pub fn database_path(&self) -> &str {
+ self.paths.get(FileRole::Main)
+ }
+
+ /// Returns whether this complete pair was fresh or existing.
+ pub fn disposition(&self) -> OpenDisposition {
+ self.disposition
+ }
+
+ /// Clones the sole production connection for application use.
+ ///
+ /// Callers must never invoke `Connection::close` directly. All clones and
+ /// statements must be dropped before [`Self::try_close`], which exclusively
+ /// owns the close transition and its success proof.
+ pub fn connection(&self) -> Arc<Connection> {
+ self.connection
+ .as_ref()
+ .expect("armed connected session always owns its connection")
+ .clone()
+ }
+
+ /// Consumes the session, calls its bound `Connection::close`, verifies the
+ /// close succeeded, drops Turso ownership, proves no Database/IO/File
+ /// references remain, and only then closes the JavaScript handles.
+ pub fn try_close(mut self) -> Result<ClosedSession, CloseFailure> {
+ let connection = self
+ .connection
+ .as_ref()
+ .expect("armed connected session always owns its connection");
+ if connection.is_closed() {
+ self.armed = false;
+ poison(
+ self.owner,
+ "bound Turso connection was closed outside the adapter transition",
+ );
+ return Err(CloseFailure::poisoned(OpfsError::new(
+ OpfsErrorKind::Turso,
+ "bound Turso connection was already closed; session poisoned",
+ )));
+ }
+ if Arc::strong_count(connection) != 1 {
+ return Err(CloseFailure::recoverable(
+ OpfsError::new(
+ OpfsErrorKind::ActiveReferences,
+ "connection clones or statements remain before graceful close",
+ ),
+ self,
+ ));
+ }
+
+ if let Err(error) = close_turso_connection(connection) {
+ self.armed = false;
+ poison(self.owner, "session-bound Turso Connection::close failed");
+ return Err(CloseFailure::poisoned(turso_error("close", error)));
+ }
+ if let Err(error) = REGISTRY.with(|registry| {
+ registry
+ .borrow_mut()
+ .machine
+ .record_connection_close(self.owner, self.session)
+ }) {
+ self.armed = false;
+ poison(
+ self.owner,
+ "Turso close proof did not match the OPFS session",
+ );
+ return Err(CloseFailure::poisoned(state_error(error)));
+ }
+
+ drop(self.connection.take());
+ drop(self.database.take());
+ if Arc::strong_count(&self.io) != 1 || Arc::strong_count(&self.references) != 2 {
+ self.armed = false;
+ poison(
+ self.owner,
+ "Turso close succeeded but Database/IO/File references remained",
+ );
+ return Err(CloseFailure::poisoned(OpfsError::new(
+ OpfsErrorKind::ActiveReferences,
+ "references remained after the session-bound Turso close",
+ )));
+ }
+
+ self.armed = false;
+ close_session_handles(self.owner, self.session, false).map_err(CloseFailure::poisoned)
+ }
+}
+
+impl Drop for ConnectedOpfsSession {
+ fn drop(&mut self) {
+ if self.armed {
+ poison(
+ self.owner,
+ "connected OPFS session dropped without adapter-driven Turso close",
+ );
+ }
+ }
+}
+
+/// A one-sided main/WAL pair that can only be physically reset.
+#[derive(Debug)]
+pub struct ResetRequiredSession {
+ owner: OwnerId,
+ session: SessionId,
+ paths: Paths,
+ armed: bool,
+}
+
+impl ResetRequiredSession {
+ /// Returns the approved main database filename requiring reset.
+ pub fn database_path(&self) -> &str {
+ self.paths.get(FileRole::Main)
+ }
+
+ /// Closes the unexposed handles, deletes/recreates both paths, and returns
+ /// the still-locked idle owner. No raw I/O or Turso connection is exposed.
+ pub async fn reset(mut self) -> Result<OpfsOwner, ResetFailure> {
+ self.armed = false;
+ let closed =
+ close_session_handles(self.owner, self.session, true).map_err(ResetFailure::new)?;
+ closed.reset().await
+ }
+}
+
+impl Drop for ResetRequiredSession {
+ fn drop(&mut self) {
+ if self.armed {
+ poison(
+ self.owner,
+ "reset-only incomplete pair dropped without physical reset",
+ );
+ }
+ }
+}
+
+/// Failure while proving connection ownership or closing Turso/OPFS.
+#[derive(Debug)]
+pub struct CloseFailure {
+ error: OpfsError,
+ session: Option<ConnectedOpfsSession>,
+}
+
+impl CloseFailure {
+ fn recoverable(error: OpfsError, session: ConnectedOpfsSession) -> Self {
+ Self {
+ error,
+ session: Some(session),
+ }
+ }
+
+ fn poisoned(error: OpfsError) -> Self {
+ Self {
+ error,
+ session: None,
+ }
+ }
+
+ /// Returns the classified adapter error.
+ pub fn error(&self) -> &OpfsError {
+ &self.error
+ }
+
+ /// Returns the connected session only before `Connection::close` ran.
+ pub fn into_session(mut self) -> Option<ConnectedOpfsSession> {
+ self.session.take()
+ }
+}
+
+impl fmt::Display for CloseFailure {
+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+ self.error.fmt(formatter)
+ }
+}
+
+impl std::error::Error for CloseFailure {}
+
+/// A one-use token proving Turso resources and JavaScript handles are closed.
+#[derive(Debug)]
+pub struct ClosedSession {
+ owner: OwnerId,
+ token: CloseToken,
+ armed: bool,
+}
+
+impl ClosedSession {
+ /// Consumes this token without deleting files and returns an idle owner.
+ pub fn preserve(mut self) -> Result<OpfsOwner, OpfsError> {
+ let binding = owner_binding(self.owner)?;
+ let result = REGISTRY.with(|registry| {
+ registry
+ .borrow_mut()
+ .machine
+ .preserve(self.owner, self.token)
+ });
+ // An invalid token is consumed without a Drop-side state mutation; the
+ // checked transition itself is the sole operation and is mutation-free.
+ self.armed = false;
+ result.map_err(state_error)?;
+ Ok(binding.into_owner(self.owner, false))
+ }
+
+ /// Consumes this token, asynchronously deletes and recreates main and WAL,
+ /// and returns an idle owner that marks the next matching open as fresh.
+ ///
+ /// Synchronous [`IO::remove_file`] is never used. Any removal, recreation,
+ /// or unexpected-state failure poisons the worker-local session.
+ pub async fn reset(mut self) -> Result<OpfsOwner, ResetFailure> {
+ let binding = owner_binding(self.owner).map_err(ResetFailure::new)?;
+ let start = REGISTRY.with(|registry| {
+ registry
+ .borrow_mut()
+ .machine
+ .start_reset(self.owner, self.token)
+ });
+ // As with preserve, invalid/consumed tokens are rejected without a
+ // Drop-side transition or mutation of the checked state.
+ self.armed = false;
+ let paths = start.map_err(state_error).map_err(ResetFailure::new)?;
+ let mut guard = AsyncPoisonGuard::new(
+ self.owner,
+ "reset cancelled or failed after entering Resetting",
+ );
+
+ reset_paths(&paths, false)
+ .await
+ .map_err(ResetFailure::new)?;
+ REGISTRY
+ .with(|registry| {
+ registry
+ .borrow_mut()
+ .machine
+ .finish_reset(self.owner, self.token)
+ })
+ .map_err(state_error)
+ .map_err(ResetFailure::new)?;
+ guard.disarm();
+ Ok(binding.into_owner(self.owner, true))
+ }
+}
+
+impl Drop for ClosedSession {
+ fn drop(&mut self) {
+ if self.armed {
+ poison(
+ self.owner,
+ "closed-session token dropped without preserve or reset",
+ );
+ }
+ }
+}
+
+/// A reset failure; the worker-local session is poisoned and not reusable.
+#[derive(Clone, Debug)]
+pub struct ResetFailure {
+ error: OpfsError,
+}
+
+impl ResetFailure {
+ fn new(error: OpfsError) -> Self {
+ Self { error }
+ }
+
+ /// Returns the classified adapter error.
+ pub fn error(&self) -> &OpfsError {
+ &self.error
+ }
+}
+
+impl fmt::Display for ResetFailure {
+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+ self.error.fmt(formatter)
+ }
+}
+
+impl std::error::Error for ResetFailure {}
+
+/// A recovery-wipe failure; the worker-local owner is poisoned.
+#[derive(Clone, Debug)]
+pub struct WipeFailure {
+ error: OpfsError,
+}
+
+impl WipeFailure {
+ fn new(error: OpfsError) -> Self {
+ Self { error }
+ }
+
+ /// Returns the classified adapter error.
+ pub fn error(&self) -> &OpfsError {
+ &self.error
+ }
+}
+
+impl fmt::Display for WipeFailure {
+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+ self.error.fmt(formatter)
+ }
+}
+
+impl std::error::Error for WipeFailure {}
+
+#[derive(Debug)]
+struct AsyncPoisonGuard {
+ owner: OwnerId,
+ reason: &'static str,
+ armed: bool,
+}
+
+impl AsyncPoisonGuard {
+ fn new(owner: OwnerId, reason: &'static str) -> Self {
+ Self {
+ owner,
+ reason,
+ armed: true,
+ }
+ }
+
+ fn disarm(&mut self) {
+ self.armed = false;
+ }
+}
+
+impl Drop for AsyncPoisonGuard {
+ fn drop(&mut self) {
+ if self.armed {
+ poison(self.owner, self.reason);
+ }
+ }
+}
+
+#[derive(Debug)]
+struct SessionReferences;
+
+struct RegisteredHandle {
+ role: FileRole,
+ handle: FileSystemSyncAccessHandle,
+}
+
+#[derive(Clone, Debug)]
+struct OwnerBinding {
+ paths: Paths,
+ lock_name: String,
+}
+
+impl OwnerBinding {
+ fn into_owner(self, id: OwnerId, fresh: bool) -> OpfsOwner {
+ OpfsOwner {
+ id,
+ paths: self.paths,
+ lock_name: self.lock_name,
+ fresh,
+ armed: true,
+ }
+ }
+}
+
+// Each Function comes from Closure::into_js_value: JavaScript owns the Rust
+// closure allocation. Registry clones intentionally keep grant/settlement
+// callbacks reachable until the outer Web Lock request has actually settled.
+struct LockCallbacks {
+ _grant: Function,
+ _fulfilled: Function,
+ _rejected: Function,
+}
+
+struct RegisteredOwnerLock {
+ owner: OwnerId,
+ binding: OwnerBinding,
+ release: Function,
+ request: Option<Promise>,
+ callbacks: Option<LockCallbacks>,
+}
+
+struct PendingOwnerLock {
+ lock_name: String,
+ controller: AbortController,
+ request: Option<Promise>,
+ callbacks: LockCallbacks,
+ cancelled: bool,
+}
+
+#[derive(Default)]
+struct Registry {
+ machine: Machine,
+ handles: HashMap<HandleId, RegisteredHandle>,
+ owner_lock: Option<RegisteredOwnerLock>,
+ pending_lock: Option<PendingOwnerLock>,
+ #[cfg(test)]
+ faults: TestFaults,
+}
+
+#[cfg(test)]
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum ResetFault {
+ AfterMainRemoval,
+ AfterMainRecreate,
+}
+
+#[cfg(test)]
+#[derive(Default)]
+struct TestFaults {
+ fail_open: Option<FileRole>,
+ fail_close: Option<FileRole>,
+ database_open_error: Option<CompletionError>,
+ database_connect_error: Option<CompletionError>,
+ fail_connection_close: bool,
+ connection_close_calls: usize,
+ reset_fault: Option<ResetFault>,
+ max_write_chunk: Option<usize>,
+ next_write_error: Option<CompletionError>,
+ write_error_after_chunks: Option<(usize, CompletionError)>,
+}
+
+thread_local! {
+ // The sole long-lived owner of JavaScript OPFS objects. It is never placed
+ // in Arc/Mutex and never enters a Turso Send + Sync trait object.
+ static REGISTRY: RefCell<Registry> = RefCell::new(Registry::default());
+}
+
+#[derive(Debug)]
+struct OpfsIo {
+ owner: OwnerId,
+ session: SessionId,
+ references: Arc<SessionReferences>,
+ last_monotonic_nanos: AtomicU64,
+}
+
+#[derive(Debug)]
+struct OpfsFile {
+ owner: OwnerId,
+ session: SessionId,
+ handle: HandleId,
+ _references: Arc<SessionReferences>,
+}
+
+impl Clock for OpfsIo {
+ fn current_time_monotonic(&self) -> MonotonicInstant {
+ let observed = (performance_now().max(0.0) * 1_000_000.0) as u64;
+ let mut previous = self.last_monotonic_nanos.load(Ordering::Relaxed);
+ loop {
+ let next = observed.max(previous.saturating_add(1));
+ match self.last_monotonic_nanos.compare_exchange_weak(
+ previous,
+ next,
+ Ordering::Relaxed,
+ Ordering::Relaxed,
+ ) {
+ Ok(_) => return MonotonicInstant::from_nanos(next as u128),
+ Err(current) => previous = current,
+ }
+ }
+ }
+
+ fn current_time_wall_clock(&self) -> WallClockInstant {
+ let millis = js_sys::Date::now();
+ let seconds = (millis / 1_000.0).floor() as i64;
+ let micros = ((millis - seconds as f64 * 1_000.0) * 1_000.0) as u32;
+ WallClockInstant {
+ secs: seconds,
+ micros,
+ }
+ }
+}
+
+impl IO for OpfsIo {
+ fn open_file(
+ &self,
+ path: &str,
+ flags: OpenFlags,
+ direct: bool,
+ ) -> turso_core::Result<Arc<dyn File>> {
+ let _operation = OperationGuard::enter(self.owner, self.session)?;
+ let handle = REGISTRY.with(|registry| {
+ registry.borrow().machine.validate_open(
+ self.owner,
+ self.session,
+ path,
+ flags.contains(OpenFlags::ReadOnly),
+ flags.contains(OpenFlags::NoLock),
+ direct,
+ )
+ })?;
+ Ok(Arc::new(OpfsFile {
+ owner: self.owner,
+ session: self.session,
+ handle,
+ _references: self.references.clone(),
+ }))
+ }
+
+ fn remove_file(&self, _path: &str) -> turso_core::Result<()> {
+ let _operation = OperationGuard::enter(self.owner, self.session)?;
+ Err(completion_io_error(
+ ErrorKind::Unsupported,
+ "synchronous OPFS remove_file is forbidden",
+ ))
+ }
+
+ fn file_id(&self, path: &str) -> turso_core::Result<FileId> {
+ let _operation = OperationGuard::enter(self.owner, self.session)?;
+ REGISTRY.with(|registry| {
+ registry
+ .borrow()
+ .machine
+ .validate_path(self.owner, self.session, path)
+ })?;
+ Ok(FileId::from_path_hash(path))
+ }
+
+ fn supports_shared_wal_coordination(&self) -> bool {
+ false
+ }
+}
+
+impl File for OpfsFile {
+ fn lock_file(&self, _exclusive: bool) -> turso_core::Result<()> {
+ let _operation = OperationGuard::enter(self.owner, self.session)?;
+ registered_handle(self.owner, self.session, self.handle).map(|_| ())
+ }
+
+ fn unlock_file(&self) -> turso_core::Result<()> {
+ let _operation = OperationGuard::enter(self.owner, self.session)?;
+ registered_handle(self.owner, self.session, self.handle).map(|_| ())
+ }
+
+ fn pread(&self, pos: u64, completion: Completion) -> turso_core::Result<Completion> {
+ let _operation = OperationGuard::enter(self.owner, self.session)?;
+ let result = read_once(
+ self.owner,
+ self.session,
+ self.handle,
+ pos,
+ completion.as_read().buf(),
+ );
+ finish_completion(&completion, result);
+ Ok(completion)
+ }
+
+ fn pwrite(
+ &self,
+ pos: u64,
+ buffer: Arc<Buffer>,
+ completion: Completion,
+ ) -> turso_core::Result<Completion> {
+ let _operation = OperationGuard::enter(self.owner, self.session)?;
+ completion.keep_write_buffer_alive(buffer.clone());
+ let result = preflight_write_range(pos, [buffer.as_slice().len()])
+ .and_then(|expected| {
+ write_all(
+ pos,
+ buffer.as_slice(),
+ self.owner,
+ self.session,
+ self.handle,
+ )
+ .and_then(|written| {
+ if written == expected {
+ completion_count(written)
+ } else {
+ Err(CompletionError::ShortWrite)
+ }
+ })
+ })
+ .map_err(LimboError::CompletionError);
+ finish_completion(&completion, result);
+ Ok(completion)
+ }
+
+ fn pwritev(
+ &self,
+ mut pos: u64,
+ buffers: Vec<Arc<Buffer>>,
+ completion: Completion,
+ ) -> turso_core::Result<Completion> {
+ let _operation = OperationGuard::enter(self.owner, self.session)?;
+ // All browser writes are synchronous, so the argument vector keeps
+ // every buffer alive until all writes finish and completion fires.
+ // Aggregate count and end offset are checked before the first write.
+ let result = (|| {
+ let expected =
+ preflight_write_range(pos, buffers.iter().map(|buffer| buffer.as_slice().len()))?;
+ let mut total = 0_usize;
+ for buffer in &buffers {
+ let written = write_all(
+ pos,
+ buffer.as_slice(),
+ self.owner,
+ self.session,
+ self.handle,
+ )?;
+ total = total
+ .checked_add(written)
+ .ok_or(CompletionError::ShortWrite)?;
+ pos = pos
+ .checked_add(written as u64)
+ .ok_or(CompletionError::ShortWrite)?;
+ }
+ if total == expected {
+ completion_count(total)
+ } else {
+ Err(CompletionError::ShortWrite)
+ }
+ })()
+ .map_err(LimboError::CompletionError);
+ finish_completion(&completion, result);
+ Ok(completion)
+ }
+
+ fn sync(
+ &self,
+ completion: Completion,
+ _sync_type: FileSyncType,
+ ) -> turso_core::Result<Completion> {
+ let _operation = OperationGuard::enter(self.owner, self.session)?;
+ let result = registered_handle(self.owner, self.session, self.handle).and_then(|handle| {
+ handle.flush().map_err(|error| {
+ js_handle_completion_error(self.owner, "OPFS flush", &error, ErrorKind::Other)
+ })?;
+ Ok(0)
+ });
+ finish_completion(&completion, result);
+ Ok(completion)
+ }
+
+ fn size(&self) -> turso_core::Result<u64> {
+ let _operation = OperationGuard::enter(self.owner, self.session)?;
+ registered_handle(self.owner, self.session, self.handle).and_then(|handle| {
+ handle
+ .get_size()
+ .map_err(|error| {
+ js_handle_limbo_error(self.owner, "OPFS getSize", &error, ErrorKind::Other)
+ })
+ .and_then(number_to_u64)
+ })
+ }
+
+ fn truncate(&self, len: u64, completion: Completion) -> turso_core::Result<Completion> {
+ let _operation = OperationGuard::enter(self.owner, self.session)?;
+ let result = validate_position(len).and_then(|()| {
+ let handle = registered_handle(self.owner, self.session, self.handle)?;
+ handle.truncate_with_f64(len as f64).map_err(|error| {
+ js_handle_limbo_error(self.owner, "OPFS truncate", &error, ErrorKind::Other)
+ })?;
+ Ok(0)
+ });
+ finish_completion(&completion, result);
+ Ok(completion)
+ }
+}
+
+#[derive(Debug)]
+struct OperationGuard {
+ owner: OwnerId,
+ session: SessionId,
+}
+
+impl OperationGuard {
+ fn enter(owner: OwnerId, session: SessionId) -> turso_core::Result<Self> {
+ REGISTRY.with(|registry| {
+ registry
+ .borrow_mut()
+ .machine
+ .begin_operation(owner, session)
+ })?;
+ Ok(Self { owner, session })
+ }
+}
+
+impl Drop for OperationGuard {
+ fn drop(&mut self) {
+ REGISTRY.with(|registry| {
+ registry
+ .borrow_mut()
+ .machine
+ .end_operation(self.owner, self.session);
+ });
+ }
+}
+
+fn approved_paths(database_name: &str) -> Result<Paths, OpfsError> {
+ if database_name.is_empty()
+ || database_name == "."
+ || database_name == ".."
+ || database_name.ends_with("-wal")
+ || database_name.contains(['/', '\\', '\0'])
+ {
+ return Err(OpfsError::new(
+ OpfsErrorKind::InvalidName,
+ "database identity must be a direct child and must not use the reserved -wal suffix",
+ ));
+ }
+ let wal = format!("{database_name}-wal");
+ Ok(Paths::new(database_name.to_owned(), wal))
+}
+
+fn owner_lock_name(database_identity: &str) -> String {
+ format!(
+ "macro:turso-opfs:v1:{}:{database_identity}",
+ database_identity.len()
+ )
+}
+
+#[derive(Debug)]
+struct PendingAcquireGuard {
+ lock_name: String,
+ armed: bool,
+}
+
+impl PendingAcquireGuard {
+ fn disarm(&mut self) {
+ self.armed = false;
+ }
+}
+
+impl Drop for PendingAcquireGuard {
+ fn drop(&mut self) {
+ if self.armed {
+ cancel_database_lock_acquire(&self.lock_name);
+ }
+ }
+}
+
+async fn acquire_database_lock(
+ database_identity: &str,
+ lock_name: &str,
+) -> Result<OwnerId, OpfsError> {
+ let worker = js_sys::global()
+ .dyn_into::<DedicatedWorkerGlobalScope>()
+ .map_err(|error| js_error(OpfsErrorKind::Lock, "DedicatedWorker lock scope", &error))?;
+ let manager = Reflect::get(worker.navigator().as_ref(), &JsValue::from_str("locks"))
+ .map_err(|error| js_error(OpfsErrorKind::Lock, "Web Lock manager", &error))?;
+ if manager.is_null() || manager.is_undefined() {
+ return Err(OpfsError::new(
+ OpfsErrorKind::Lock,
+ "Web Locks API is unavailable in this DedicatedWorker",
+ ));
+ }
+ let request_function = Reflect::get(&manager, &JsValue::from_str("request"))
+ .and_then(|value| value.dyn_into::<Function>())
+ .map_err(|error| js_error(OpfsErrorKind::Lock, "Web Lock request function", &error))?;
+ let occupied = REGISTRY.with(|registry| {
+ let registry = registry.borrow();
+ registry.pending_lock.is_some() || registry.owner_lock.is_some()
+ });
+ if occupied {
+ return Err(OpfsError::new(
+ OpfsErrorKind::Ownership,
+ "worker-local OPFS registry already owns or is acquiring a Web Lock",
+ ));
+ }
+
+ let controller = AbortController::new()
+ .map_err(|error| js_error(OpfsErrorKind::Lock, "Web Lock abort controller", &error))?;
+ let options = Object::new();
+ Reflect::set(
+ options.as_ref(),
+ &JsValue::from_str("mode"),
+ &JsValue::from_str("exclusive"),
+ )
+ .map_err(|error| js_error(OpfsErrorKind::Lock, "Web Lock mode", &error))?;
+ Reflect::set(
+ options.as_ref(),
+ &JsValue::from_str("signal"),
+ controller.signal().as_ref(),
+ )
+ .map_err(|error| js_error(OpfsErrorKind::Lock, "Web Lock abort signal", &error))?;
+
+ let mut acquired_resolve = None;
+ let mut acquired_reject = None;
+ let acquired = Promise::new(&mut |resolve, reject| {
+ acquired_resolve = Some(resolve.clone());
+ acquired_reject = Some(reject.clone());
+ });
+ let resolve = acquired_resolve.expect("Promise constructor supplies resolve");
+ let reject = acquired_reject.expect("Promise constructor supplies reject");
+ let callback_reject = reject.clone();
+ let callback_resolve = resolve.clone();
+ let callback_lock_name = lock_name.to_owned();
+ let binding = OwnerBinding {
+ paths: approved_paths(database_identity)?,
+ lock_name: lock_name.to_owned(),
+ };
+ let grant = Closure::wrap(Box::new(move |lock: JsValue| -> Promise {
+ if lock.is_null() || lock.is_undefined() {
+ let _ = callback_reject.call1(
+ &JsValue::UNDEFINED,
+ &JsValue::from_str("exclusive Web Lock was not granted"),
+ );
+ return Promise::resolve(&JsValue::UNDEFINED);
+ }
+ let actual_name = Reflect::get(&lock, &JsValue::from_str("name"))
+ .ok()
+ .and_then(|value| value.as_string());
+ let actual_mode = Reflect::get(&lock, &JsValue::from_str("mode"))
+ .ok()
+ .and_then(|value| value.as_string());
+ if actual_name.as_deref() != Some(callback_lock_name.as_str())
+ || actual_mode.as_deref() != Some("exclusive")
+ {
+ let _ = callback_reject.call1(
+ &JsValue::UNDEFINED,
+ &JsValue::from_str("granted Web Lock did not match canonical identity"),
+ );
+ return Promise::resolve(&JsValue::UNDEFINED);
+ }
+
+ let mut release_resolve = None;
+ let held = Promise::new(&mut |resolve, _reject| {
+ release_resolve = Some(resolve.clone());
+ });
+ let release = release_resolve.expect("Promise constructor supplies resolve");
+ let claimed = REGISTRY.with(|registry| {
+ let mut registry = registry.borrow_mut();
+ if registry
+ .pending_lock
+ .as_ref()
+ .is_none_or(|pending| pending.lock_name != callback_lock_name)
+ || registry.owner_lock.is_some()
+ {
+ return Err(OpfsError::new(
+ OpfsErrorKind::Ownership,
+ "Web Lock callback did not match the pending acquisition",
+ ));
+ }
+ let owner = registry.machine.claim_owner().map_err(state_error)?;
+ registry.owner_lock = Some(RegisteredOwnerLock {
+ owner,
+ binding: binding.clone(),
+ release,
+ request: None,
+ callbacks: None,
+ });
+ Ok(owner)
+ });
+ match claimed {
+ Ok(_) => {
+ let _ = callback_resolve.call1(&JsValue::UNDEFINED, &JsValue::TRUE);
+ held
+ }
+ Err(error) => {
+ let _ = callback_reject
+ .call1(&JsValue::UNDEFINED, &JsValue::from_str(&error.to_string()));
+ Promise::resolve(&JsValue::UNDEFINED)
+ }
+ }
+ }) as Box<dyn FnMut(JsValue) -> Promise>)
+ .into_js_value()
+ .unchecked_into::<Function>();
+
+ let fulfilled_lock_name = lock_name.to_owned();
+ let fulfilled = Closure::wrap(Box::new(move |_value: JsValue| -> JsValue {
+ REGISTRY.with(|registry| {
+ let mut registry = registry.borrow_mut();
+ let cancelled = registry.pending_lock.as_ref().is_some_and(|pending| {
+ pending.lock_name == fulfilled_lock_name && pending.cancelled
+ });
+ if cancelled {
+ registry.pending_lock = None;
+ if registry.owner_lock.as_ref().is_some_and(|lock| {
+ lock.binding.lock_name == fulfilled_lock_name && lock.callbacks.is_none()
+ }) {
+ registry.owner_lock = None;
+ }
+ }
+ });
+ JsValue::UNDEFINED
+ }) as Box<dyn FnMut(JsValue) -> JsValue>)
+ .into_js_value()
+ .unchecked_into::<Function>();
+
+ let rejected_lock_name = lock_name.to_owned();
+ let request_reject = reject.clone();
+ let rejected = Closure::wrap(Box::new(move |error: JsValue| -> JsValue {
+ let _ = request_reject.call1(&JsValue::UNDEFINED, &error);
+ let owner = REGISTRY.with(|registry| {
+ let mut registry = registry.borrow_mut();
+ if registry
+ .pending_lock
+ .as_ref()
+ .is_some_and(|pending| pending.lock_name == rejected_lock_name)
+ {
+ registry.pending_lock = None;
+ }
+ if registry
+ .owner_lock
+ .as_ref()
+ .is_some_and(|lock| lock.binding.lock_name == rejected_lock_name)
+ {
+ registry.owner_lock.take().map(|lock| lock.owner)
+ } else {
+ None
+ }
+ });
+ if let Some(owner) = owner {
+ poison(owner, "held Web Lock request rejected before clean release");
+ }
+ JsValue::UNDEFINED
+ }) as Box<dyn FnMut(JsValue) -> JsValue>)
+ .into_js_value()
+ .unchecked_into::<Function>();
+
+ let callbacks = LockCallbacks {
+ _grant: grant.clone(),
+ _fulfilled: fulfilled.clone(),
+ _rejected: rejected.clone(),
+ };
+ REGISTRY.with(|registry| {
+ registry.borrow_mut().pending_lock = Some(PendingOwnerLock {
+ lock_name: lock_name.to_owned(),
+ controller,
+ request: None,
+ callbacks,
+ cancelled: false,
+ });
+ });
+ let mut guard = PendingAcquireGuard {
+ lock_name: lock_name.to_owned(),
+ armed: true,
+ };
+
+ let request = match request_function
+ .call3(
+ &manager,
+ &JsValue::from_str(lock_name),
+ options.as_ref(),
+ grant.as_ref(),
+ )
+ .and_then(|value| value.dyn_into::<Promise>())
+ {
+ Ok(request) => request,
+ Err(error) => {
+ REGISTRY.with(|registry| registry.borrow_mut().pending_lock = None);
+ guard.disarm();
+ return Err(js_error(OpfsErrorKind::Lock, "Web Lock request", &error));
+ }
+ };
+ REGISTRY.with(|registry| {
+ if let Some(pending) = registry.borrow_mut().pending_lock.as_mut() {
+ pending.request = Some(request.clone());
+ }
+ });
+ let then = Reflect::get(request.as_ref(), &JsValue::from_str("then"))
+ .and_then(|value| value.dyn_into::<Function>())
+ .and_then(|then| then.call2(request.as_ref(), fulfilled.as_ref(), rejected.as_ref()));
+ if let Err(error) = then {
+ cancel_database_lock_acquire(lock_name);
+ let _ = JsFuture::from(request).await;
+ REGISTRY.with(|registry| registry.borrow_mut().pending_lock = None);
+ guard.disarm();
+ return Err(js_error(
+ OpfsErrorKind::Lock,
+ "Web Lock settlement handlers",
+ &error,
+ ));
+ }
+
+ JsFuture::from(acquired)
+ .await
+ .map_err(|error| js_error(OpfsErrorKind::Lock, "Web Lock acquisition", &error))?;
+
+ let owner = REGISTRY.with(|registry| {
+ let mut registry = registry.borrow_mut();
+ let pending = registry.pending_lock.take().ok_or_else(|| {
+ OpfsError::new(
+ OpfsErrorKind::Lock,
+ "Web Lock acquisition lost its pending capability",
+ )
+ })?;
+ if pending.lock_name != lock_name || pending.cancelled {
+ return Err(OpfsError::new(
+ OpfsErrorKind::Lock,
+ "Web Lock acquisition completed for a cancelled identity",
+ ));
+ }
+ let registered = registry.owner_lock.as_mut().ok_or_else(|| {
+ OpfsError::new(
+ OpfsErrorKind::Lock,
+ "Web Lock callback completed without an owner capability",
+ )
+ })?;
+ if registered.binding.lock_name != lock_name {
+ return Err(OpfsError::new(
+ OpfsErrorKind::Lock,
+ "registered owner lock does not match canonical identity",
+ ));
+ }
+ registered.request = pending.request;
+ registered.callbacks = Some(pending.callbacks);
+ Ok(registered.owner)
+ })?;
+ guard.disarm();
+ Ok(owner)
+}
+
+fn cancel_database_lock_acquire(lock_name: &str) {
+ let (controller, release, owner) = REGISTRY.with(|registry| {
+ let mut registry = registry.borrow_mut();
+ let controller = registry
+ .pending_lock
+ .as_mut()
+ .filter(|pending| pending.lock_name == lock_name)
+ .map(|pending| {
+ pending.cancelled = true;
+ pending.controller.clone()
+ });
+ let lock = registry
+ .owner_lock
+ .as_ref()
+ .filter(|lock| lock.binding.lock_name == lock_name && lock.callbacks.is_none());
+ (
+ controller,
+ lock.map(|lock| lock.release.clone()),
+ lock.map(|lock| lock.owner),
+ )
+ });
+ if let Some(controller) = controller {
+ controller.abort();
+ }
+ if let Some(owner) = owner {
+ poison(owner, "Web Lock acquisition future cancelled after grant");
+ }
+ if let Some(release) = release {
+ let _ = release.call0(&JsValue::UNDEFINED);
+ }
+}
+
+fn owner_binding(owner: OwnerId) -> Result<OwnerBinding, OpfsError> {
+ REGISTRY.with(|registry| {
+ registry
+ .borrow()
+ .owner_lock
+ .as_ref()
+ .filter(|lock| lock.owner == owner && lock.request.is_some())
+ .map(|lock| lock.binding.clone())
+ .ok_or_else(|| {
+ OpfsError::new(
+ OpfsErrorKind::Lock,
+ "owner is not backed by the matching held Web Lock",
+ )
+ })
+ })
+}
+
+fn begin_database_lock_release(owner: OwnerId) {
+ let release = REGISTRY.with(|registry| {
+ registry
+ .borrow()
+ .owner_lock
+ .as_ref()
+ .filter(|lock| lock.owner == owner)
+ .map(|lock| lock.release.clone())
+ });
+ if let Some(release) = release {
+ let _ = release.call0(&JsValue::UNDEFINED);
+ }
+}
+
+async fn release_database_lock(owner: OwnerId) -> Result<(), OpfsError> {
+ let (release, request) = REGISTRY.with(|registry| {
+ let registry = registry.borrow();
+ let lock = registry
+ .owner_lock
+ .as_ref()
+ .filter(|lock| lock.owner == owner)
+ .ok_or_else(|| {
+ OpfsError::new(
+ OpfsErrorKind::Lock,
+ "owner release lacks its matching held Web Lock",
+ )
+ })?;
+ let request = lock.request.clone().ok_or_else(|| {
+ OpfsError::new(
+ OpfsErrorKind::Lock,
+ "owner Web Lock request has no completion proof",
+ )
+ })?;
+ Ok::<_, OpfsError>((lock.release.clone(), request))
+ })?;
+ release
+ .call0(&JsValue::UNDEFINED)
+ .map_err(|error| js_error(OpfsErrorKind::Lock, "Web Lock release signal", &error))?;
+ JsFuture::from(request)
+ .await
+ .map_err(|error| js_error(OpfsErrorKind::Lock, "Web Lock release completion", &error))?;
+ REGISTRY.with(|registry| {
+ let mut registry = registry.borrow_mut();
+ if registry
+ .owner_lock
+ .as_ref()
+ .is_some_and(|lock| lock.owner == owner)
+ {
+ registry.owner_lock = None;
+ Ok(())
+ } else {
+ Err(OpfsError::new(
+ OpfsErrorKind::Lock,
+ "released Web Lock did not match the current owner",
+ ))
+ }
+ })
+}
+
+async fn worker_root() -> Result<FileSystemDirectoryHandle, JsValue> {
+ let worker = js_sys::global().dyn_into::<DedicatedWorkerGlobalScope>()?;
+ JsFuture::from(worker.navigator().storage().get_directory())
+ .await?
+ .dyn_into::<FileSystemDirectoryHandle>()
+}
+
+async fn open_sync_handle(
+ root: &FileSystemDirectoryHandle,
+ path: &str,
+) -> Result<(FileSystemSyncAccessHandle, bool), JsValue> {
+ let (file, created) = match JsFuture::from(root.get_file_handle(path)).await {
+ Ok(file) => (file.dyn_into::<FileSystemFileHandle>()?, false),
+ Err(error) if is_not_found(&error) => {
+ let options = FileSystemGetFileOptions::new();
+ options.set_create(true);
+ (
+ JsFuture::from(root.get_file_handle_with_options(path, &options))
+ .await?
+ .dyn_into::<FileSystemFileHandle>()?,
+ true,
+ )
+ }
+ Err(error) => return Err(error),
+ };
+ let handle = JsFuture::from(file.create_sync_access_handle())
+ .await?
+ .dyn_into::<FileSystemSyncAccessHandle>()?;
+ Ok((handle, created))
+}
+
+fn open_turso_database(
+ io: Arc<dyn IO>,
+ path: &str,
+ options: OpenOptions,
+) -> turso_core::Result<Arc<Database>> {
+ #[cfg(test)]
+ if let Some(error) =
+ REGISTRY.with(|registry| registry.borrow_mut().faults.database_open_error.take())
+ {
+ return Err(LimboError::CompletionError(error));
+ }
+ Database::open(io, path, options)
+}
+
+fn connect_turso_database(database: &Arc<Database>) -> turso_core::Result<Arc<Connection>> {
+ #[cfg(test)]
+ if let Some(error) =
+ REGISTRY.with(|registry| registry.borrow_mut().faults.database_connect_error.take())
+ {
+ return Err(LimboError::CompletionError(error));
+ }
+ database.connect()
+}
+
+#[cfg(test)]
+fn inject_out_of_band_marked_close_failure(connection: &Connection) -> turso_core::Result<()> {
+ // Faithfully model pinned Turso's ordering: Connection::close marks the
+ // connection closed before shutdown checkpoint can return an error.
+ connection.close()?;
+ debug_assert!(connection.is_closed());
+ Err(LimboError::InternalError(
+ "injected failure after out-of-band close marked the connection".into(),
+ ))
+}
+
+fn close_turso_connection(connection: &Connection) -> turso_core::Result<()> {
+ #[cfg(test)]
+ if REGISTRY.with(|registry| {
+ let mut registry = registry.borrow_mut();
+ registry.faults.connection_close_calls += 1;
+ std::mem::take(&mut registry.faults.fail_connection_close)
+ }) {
+ return Err(LimboError::InternalError(
+ "injected session-bound Turso close failure".into(),
+ ));
+ }
+ connection.close()
+}
+
+fn close_session_handles(
+ owner: OwnerId,
+ session: SessionId,
+ reset_only: bool,
+) -> Result<ClosedSession, OpfsError> {
+ let handle_ids = REGISTRY
+ .with(|registry| {
+ let mut registry = registry.borrow_mut();
+ if reset_only {
+ registry.machine.start_reset_only_close(owner, session)
+ } else {
+ registry.machine.start_close(owner, session)
+ }
+ })
+ .map_err(state_error)
+ .inspect_err(|_| poison(owner, "handle close proof did not match active session"))?;
+
+ let mut failures = Vec::new();
+ let mut unexpected = false;
+ for (role, handle_id) in [
+ (FileRole::Wal, handle_ids[FileRole::Wal.index()]),
+ (FileRole::Main, handle_ids[FileRole::Main.index()]),
+ ] {
+ let entry = REGISTRY.with(|registry| registry.borrow_mut().handles.remove(&handle_id));
+ let Some(entry) = entry else {
+ unexpected = true;
+ continue;
+ };
+ if entry.role != role || close_registered_handle(&entry).is_err() {
+ failures.push((handle_id, entry));
+ }
+ }
+
+ if unexpected || !failures.is_empty() {
+ REGISTRY.with(|registry| {
+ let mut registry = registry.borrow_mut();
+ registry.handles.extend(failures);
+ let _ = registry.machine.poison(
+ owner,
+ "sync handle close was uncertain or registry state was unexpected".into(),
+ );
+ });
+ return Err(OpfsError::new(
+ OpfsErrorKind::Close,
+ "OPFS sync handle close was uncertain; session poisoned",
+ ));
+ }
+
+ let token = REGISTRY
+ .with(|registry| registry.borrow_mut().machine.finish_close(owner, session))
+ .map_err(state_error)
+ .inspect_err(|_| poison(owner, "close completion did not match worker registry"))?;
+ Ok(ClosedSession {
+ owner,
+ token,
+ armed: true,
+ })
+}
+
+fn cleanup_failed_open(owner: OwnerId, session: SessionId, cause: &OpfsError) {
+ let entries =
+ REGISTRY.with(|registry| registry.borrow_mut().handles.drain().collect::<Vec<_>>());
+ let mut uncertain = Vec::new();
+ for (id, entry) in entries {
+ if close_registered_handle(&entry).is_err() {
+ uncertain.push((id, entry));
+ }
+ }
+ REGISTRY.with(|registry| {
+ let mut registry = registry.borrow_mut();
+ registry.handles.extend(uncertain);
+ let cleanup_certain = registry.handles.is_empty();
+ let _ = registry.machine.abort_open(
+ owner,
+ session,
+ cleanup_certain,
+ format!(
+ "partial open cleanup uncertain after {}",
+ cause.kind() as u8
+ ),
+ );
+ });
+}
+
+fn open_failure_after_cleanup(error: OpfsError, mut owner: OpfsOwner) -> OpenFailure {
+ let reusable = REGISTRY.with(|registry| {
+ let registry = registry.borrow();
+ registry.machine.is_idle_owner(owner.id)
+ && registry.handles.is_empty()
+ && registry.pending_lock.is_none()
+ && registry.owner_lock.as_ref().is_some_and(|lock| {
+ lock.owner == owner.id
+ && lock.request.is_some()
+ && lock.binding.paths == owner.paths
+ && lock.binding.lock_name == owner.lock_name
+ })
+ });
+ if reusable {
+ OpenFailure::recoverable(error, owner)
+ } else {
+ owner.armed = false;
+ OpenFailure::poisoned(OpfsError::new(
+ OpfsErrorKind::Poisoned,
+ "partial OPFS open cleanup was uncertain; session poisoned",
+ ))
+ }
+}
+
+fn close_registered_handle(entry: &RegisteredHandle) -> Result<(), JsValue> {
+ #[cfg(test)]
+ if take_close_failure(entry.role) {
+ return Err(JsValue::from_str("injected sync handle close failure"));
+ }
+ close_sync_handle(&entry.handle)
+}
+
+fn close_sync_handle(handle: &FileSystemSyncAccessHandle) -> Result<(), JsValue> {
+ let close =
+ Reflect::get(handle.as_ref(), &JsValue::from_str("close"))?.dyn_into::<Function>()?;
+ close.call0(handle.as_ref()).map(|_| ())
+}
+
+async fn reset_paths(paths: &Paths, recursive: bool) -> Result<(), OpfsError> {
+ let root = worker_root()
+ .await
+ .map_err(|error| js_error(OpfsErrorKind::Remove, "OPFS reset root open", &error))?;
+ for role in FileRole::ALL {
+ remove_if_present(&root, paths.get(role), recursive).await?;
+ #[cfg(test)]
+ if role == FileRole::Main && take_reset_failure(ResetFault::AfterMainRemoval) {
+ return Err(OpfsError::new(
+ OpfsErrorKind::Remove,
+ "injected failure after removing the main path",
+ ));
+ }
+ }
+ for role in FileRole::ALL {
+ let options = FileSystemGetFileOptions::new();
+ options.set_create(true);
+ JsFuture::from(root.get_file_handle_with_options(paths.get(role), &options))
+ .await
+ .map_err(|error| js_error(OpfsErrorKind::Recreate, "OPFS path recreate", &error))?
+ .dyn_into::<FileSystemFileHandle>()
+ .map_err(|error| {
+ js_error(OpfsErrorKind::Recreate, "OPFS recreated entry type", &error)
+ })?;
+ #[cfg(test)]
+ if role == FileRole::Main && take_reset_failure(ResetFault::AfterMainRecreate) {
+ return Err(OpfsError::new(
+ OpfsErrorKind::Recreate,
+ "injected failure after recreating the main path",
+ ));
+ }
+ }
+ Ok(())
+}
+
+async fn remove_if_present(
+ root: &FileSystemDirectoryHandle,
+ path: &str,
+ recursive: bool,
+) -> Result<(), OpfsError> {
+ let remove = if recursive {
+ let options = FileSystemRemoveOptions::new();
+ options.set_recursive(true);
+ root.remove_entry_with_options(path, &options)
+ } else {
+ root.remove_entry(path)
+ };
+ match JsFuture::from(remove).await {
+ Ok(_) => Ok(()),
+ Err(error) if is_not_found(&error) => Ok(()),
+ Err(error) => Err(js_error(OpfsErrorKind::Remove, "OPFS path remove", &error)),
+ }
+}
+
+fn is_not_found(value: &JsValue) -> bool {
+ dom_exception_name(value).as_deref() == Some("NotFoundError")
+}
+
+fn registered_handle(
+ owner: OwnerId,
+ session: SessionId,
+ id: HandleId,
+) -> turso_core::Result<FileSystemSyncAccessHandle> {
+ let handle = REGISTRY.with(|registry| {
+ let registry = registry.borrow();
+ registry.machine.validate_session(owner, session)?;
+ Ok::<_, LimboError>(registry.handles.get(&id).map(|entry| entry.handle.clone()))
+ })?;
+ handle.ok_or_else(|| {
+ poison(
+ owner,
+ "active session referenced a missing registered OPFS handle",
+ );
+ completion_io_error(ErrorKind::Other, "active OPFS handle registry is invalid")
+ })
+}
+
+fn read_once(
+ owner: OwnerId,
+ session: SessionId,
+ id: HandleId,
+ pos: u64,
+ buffer: &Buffer,
+) -> turso_core::Result<i32> {
+ validate_position(pos)?;
+ let handle = registered_handle(owner, session, id)?;
+ let options = FileSystemReadWriteOptions::new();
+ options.set_at(pos as f64);
+ handle
+ .read_with_u8_array_and_options(buffer.as_mut_slice(), &options)
+ .map_err(|error| js_handle_limbo_error(owner, "OPFS read", &error, ErrorKind::Other))
+ .and_then(number_to_i32)
+}
+
+fn preflight_write_range(
+ pos: u64,
+ lengths: impl IntoIterator<Item = usize>,
+) -> Result<usize, CompletionError> {
+ let total = lengths.into_iter().try_fold(0_usize, |total, length| {
+ total.checked_add(length).ok_or(CompletionError::ShortWrite)
+ })?;
+ completion_count(total)?;
+ if total == 0 {
+ return Ok(0);
+ }
+ validate_position(pos).map_err(limbo_to_completion)?;
+ let total_u64 = u64::try_from(total).map_err(|_| CompletionError::ShortWrite)?;
+ let end = pos
+ .checked_add(total_u64)
+ .ok_or(CompletionError::ShortWrite)?;
+ if end > MAX_SAFE_INTEGER {
+ return Err(CompletionError::IOError(
+ ErrorKind::InvalidInput,
+ "OPFS write end exceeds JavaScript safe integer",
+ ));
+ }
+ Ok(total)
+}
+
+fn write_all(
+ mut pos: u64,
+ mut bytes: &[u8],
+ owner: OwnerId,
+ session: SessionId,
+ id: HandleId,
+) -> Result<usize, CompletionError> {
+ let expected = bytes.len();
+ let mut total = 0_usize;
+ while !bytes.is_empty() {
+ let written = write_once(owner, session, id, pos, bytes)?;
+ if written == 0 || written > bytes.len() {
+ return Err(CompletionError::ShortWrite);
+ }
+ total = total
+ .checked_add(written)
+ .ok_or(CompletionError::ShortWrite)?;
+ pos = pos
+ .checked_add(written as u64)
+ .ok_or(CompletionError::ShortWrite)?;
+ bytes = &bytes[written..];
+ }
+ if total == expected {
+ Ok(total)
+ } else {
+ Err(CompletionError::ShortWrite)
+ }
+}
+
+fn write_once(
+ owner: OwnerId,
+ session: SessionId,
+ id: HandleId,
+ pos: u64,
+ bytes: &[u8],
+) -> Result<usize, CompletionError> {
+ validate_position(pos).map_err(limbo_to_completion)?;
+ let handle = registered_handle(owner, session, id).map_err(limbo_to_completion)?;
+ #[cfg(test)]
+ let (chunk_limit, injected_error) = REGISTRY.with(|registry| {
+ let mut registry = registry.borrow_mut();
+ let injected = registry.faults.next_write_error.take().or_else(|| {
+ let fault = registry.faults.write_error_after_chunks.as_mut()?;
+ if fault.0 == 0 {
+ let error = fault.1;
+ registry.faults.write_error_after_chunks = None;
+ Some(error)
+ } else {
+ fault.0 -= 1;
+ None
+ }
+ });
+ (registry.faults.max_write_chunk, injected)
+ });
+ #[cfg(not(test))]
+ let (chunk_limit, injected_error): (Option<usize>, Option<CompletionError>) = (None, None);
+ if let Some(error) = injected_error {
+ return Err(error);
+ }
+ let chunk_len = chunk_limit.unwrap_or(bytes.len()).min(bytes.len());
+ if chunk_len == 0 {
+ return Ok(0);
+ }
+ let options = FileSystemReadWriteOptions::new();
+ options.set_at(pos as f64);
+ let written = handle
+ .write_with_u8_array_and_options(&bytes[..chunk_len], &options)
+ .map_err(|error| {
+ js_handle_completion_error(owner, "OPFS write", &error, ErrorKind::Other)
+ })?;
+ let written = number_to_i32(written)
+ .map(|written| written as usize)
+ .map_err(limbo_to_completion)?;
+ if written <= chunk_len {
+ Ok(written)
+ } else {
+ Err(CompletionError::ShortWrite)
+ }
+}
+
+fn completion_count(count: usize) -> Result<i32, CompletionError> {
+ i32::try_from(count).map_err(|_| CompletionError::ShortWrite)
+}
+
+fn finish_completion(completion: &Completion, result: turso_core::Result<i32>) {
+ match result {
+ Ok(value) => completion.complete(value),
+ Err(error) => completion.error(limbo_to_completion(error)),
+ }
+}
+
+fn validate_position(value: u64) -> turso_core::Result<()> {
+ if value <= MAX_SAFE_INTEGER {
+ Ok(())
+ } else {
+ Err(completion_io_error(
+ ErrorKind::InvalidInput,
+ "OPFS offset exceeds JavaScript safe integer",
+ ))
+ }
+}
+
+fn number_to_i32(value: f64) -> turso_core::Result<i32> {
+ if value.is_finite() && value >= 0.0 && value.fract() == 0.0 && value <= i32::MAX as f64 {
+ Ok(value as i32)
+ } else {
+ Err(completion_io_error(
+ ErrorKind::InvalidData,
+ "invalid OPFS byte count",
+ ))
+ }
+}
+
+fn number_to_u64(value: f64) -> turso_core::Result<u64> {
+ if value.is_finite() && value >= 0.0 && value.fract() == 0.0 && value <= MAX_SAFE_INTEGER as f64
+ {
+ Ok(value as u64)
+ } else {
+ Err(completion_io_error(
+ ErrorKind::InvalidData,
+ "invalid OPFS file size",
+ ))
+ }
+}
+
+fn state_error(error: StateError) -> OpfsError {
+ let kind = match error.kind {
+ StateErrorKind::Ownership => OpfsErrorKind::Ownership,
+ StateErrorKind::Reentrant => OpfsErrorKind::Reentrant,
+ StateErrorKind::ActiveReferences => OpfsErrorKind::ActiveReferences,
+ StateErrorKind::Poisoned => OpfsErrorKind::Poisoned,
+ StateErrorKind::Path | StateErrorKind::Flags => OpfsErrorKind::InvalidName,
+ StateErrorKind::Session
+ | StateErrorKind::Registration
+ | StateErrorKind::Token
+ | StateErrorKind::Exhausted => OpfsErrorKind::Lifecycle,
+ };
+ OpfsError::new(kind, error.message)
+}
+
+impl From<StateError> for LimboError {
+ fn from(error: StateError) -> Self {
+ let kind = match error.kind {
+ StateErrorKind::Reentrant | StateErrorKind::ActiveReferences => ErrorKind::WouldBlock,
+ StateErrorKind::Path => ErrorKind::NotFound,
+ StateErrorKind::Flags => ErrorKind::PermissionDenied,
+ StateErrorKind::Ownership
+ | StateErrorKind::Session
+ | StateErrorKind::Registration
+ | StateErrorKind::Token
+ | StateErrorKind::Exhausted
+ | StateErrorKind::Poisoned => ErrorKind::Other,
+ };
+ completion_io_error(kind, error.message)
+ }
+}
+
+fn completion_io_error(kind: ErrorKind, operation: &'static str) -> LimboError {
+ CompletionError::IOError(kind, operation).into()
+}
+
+fn limbo_to_completion(error: LimboError) -> CompletionError {
+ match error {
+ LimboError::CompletionError(error) => error,
+ _ => CompletionError::IOError(ErrorKind::Other, "OPFS adapter"),
+ }
+}
+
+fn js_handle_limbo_error(
+ owner: OwnerId,
+ operation: &'static str,
+ value: &JsValue,
+ fallback: ErrorKind,
+) -> LimboError {
+ LimboError::CompletionError(js_handle_completion_error(
+ owner, operation, value, fallback,
+ ))
+}
+
+fn js_handle_completion_error(
+ owner: OwnerId,
+ operation: &'static str,
+ value: &JsValue,
+ fallback: ErrorKind,
+) -> CompletionError {
+ if is_invalid_active_handle_error(value) {
+ poison(
+ owner,
+ "browser reported invalid ownership/state for an active OPFS handle",
+ );
+ }
+ js_completion_error(operation, value, fallback)
+}
+
+fn is_invalid_active_handle_error(value: &JsValue) -> bool {
+ matches!(
+ dom_exception_name(value).as_deref(),
+ Some("InvalidStateError") | Some("NoModificationAllowedError")
+ )
+}
+
+fn js_completion_error(
+ operation: &'static str,
+ value: &JsValue,
+ fallback: ErrorKind,
+) -> CompletionError {
+ let kind = match dom_exception_name(value).as_deref() {
+ Some("QuotaExceededError") => ErrorKind::StorageFull,
+ Some("NotFoundError") => ErrorKind::NotFound,
+ Some("InvalidStateError") | Some("NoModificationAllowedError") => ErrorKind::Other,
+ Some("TypeMismatchError") | Some("InvalidModificationError") => ErrorKind::InvalidInput,
+ _ => fallback,
+ };
+ CompletionError::IOError(kind, operation)
+}
+
+fn turso_error(operation: &'static str, error: LimboError) -> OpfsError {
+ let kind = match &error {
+ LimboError::CompletionError(CompletionError::IOError(ErrorKind::StorageFull, _)) => {
+ OpfsErrorKind::StorageFull
+ }
+ _ => OpfsErrorKind::Turso,
+ };
+ OpfsError::new(kind, format!("Turso {operation} failed: {error}"))
+}
+
+fn js_error(kind: OpfsErrorKind, operation: &'static str, value: &JsValue) -> OpfsError {
+ let actual_kind = if dom_exception_name(value).as_deref() == Some("QuotaExceededError") {
+ OpfsErrorKind::StorageFull
+ } else {
+ kind
+ };
+ let name = dom_exception_name(value).unwrap_or_else(|| "JavaScriptError".into());
+ OpfsError::new(actual_kind, format!("{operation} failed ({name})"))
+}
+
+fn dom_exception_name(value: &JsValue) -> Option<String> {
+ value
+ .dyn_ref::<DomException>()
+ .map(DomException::name)
+ .or_else(|| {
+ Reflect::get(value, &JsValue::from_str("name"))
+ .ok()
+ .and_then(|name| name.as_string())
+ })
+}
+
+fn poison(owner: OwnerId, reason: &str) {
+ let _ = REGISTRY.try_with(|registry| {
+ if let Ok(mut registry) = registry.try_borrow_mut() {
+ let _ = registry.machine.poison(owner, reason.to_owned());
+ }
+ });
+}
+
+#[cfg(test)]
+fn take_open_failure(role: FileRole) -> bool {
+ REGISTRY.with(|registry| {
+ let mut registry = registry.borrow_mut();
+ if registry.faults.fail_open == Some(role) {
+ registry.faults.fail_open = None;
+ true
+ } else {
+ false
+ }
+ })
+}
+
+#[cfg(test)]
+fn take_reset_failure(fault: ResetFault) -> bool {
+ REGISTRY.with(|registry| {
+ let mut registry = registry.borrow_mut();
+ if registry.faults.reset_fault == Some(fault) {
+ registry.faults.reset_fault = None;
+ true
+ } else {
+ false
+ }
+ })
+}
+
+#[cfg(test)]
+fn take_close_failure(role: FileRole) -> bool {
+ REGISTRY.with(|registry| {
+ let mut registry = registry.borrow_mut();
+ if registry.faults.fail_close == Some(role) {
+ registry.faults.fail_close = None;
+ true
+ } else {
+ false
+ }
+ })
+}
+
+#[allow(dead_code)]
+fn assert_send_sync_contract() {
+ fn assert_send_sync<T: Send + Sync>() {}
+ assert_send_sync::<OwnerId>();
+ assert_send_sync::<SessionId>();
+ assert_send_sync::<HandleId>();
+ assert_send_sync::<OpfsIo>();
+ assert_send_sync::<OpfsFile>();
+}
diff --git a/crates/client/turso-opfs/src/browser/test.rs b/crates/client/turso-opfs/src/browser/test.rs
new file mode 100644
index 0000000000..f855fada40
--- /dev/null
+++ b/crates/client/turso-opfs/src/browser/test.rs
@@ -0,0 +1,1048 @@
+use super::*;
+use std::{
+ cell::{Cell, RefCell},
+ future::Future,
+ rc::Rc,
+ sync::{
+ Mutex,
+ atomic::{AtomicBool, AtomicUsize},
+ },
+ task::{Context, Poll, Waker},
+};
+use turso_core::{Row, StepResult};
+use wasm_bindgen_test::*;
+use web_sys::{FileSystemGetDirectoryOptions, FileSystemGetFileOptions, FileSystemRemoveOptions};
+
+wasm_bindgen_test_configure!(run_in_dedicated_worker);
+
+#[derive(Debug)]
+struct TrackedCompletion {
+ completion: Completion,
+ count: Arc<AtomicUsize>,
+ result: Arc<Mutex<Option<Result<i32, CompletionError>>>>,
+}
+
+fn write_completion() -> TrackedCompletion {
+ tracked_completion(Completion::new_write)
+}
+
+fn sync_completion() -> TrackedCompletion {
+ tracked_completion(Completion::new_sync)
+}
+
+fn truncate_completion() -> TrackedCompletion {
+ tracked_completion(Completion::new_trunc)
+}
+
+fn tracked_completion(
+ build: impl FnOnce(Box<dyn Fn(Result<i32, CompletionError>) + Send + Sync>) -> Completion,
+) -> TrackedCompletion {
+ let count = Arc::new(AtomicUsize::new(0));
+ let result = Arc::new(Mutex::new(None));
+ let callback_count = count.clone();
+ let callback_result = result.clone();
+ let callback: Box<dyn Fn(Result<i32, CompletionError>) + Send + Sync> =
+ Box::new(move |value| {
+ callback_count.fetch_add(1, Ordering::SeqCst);
+ *callback_result.lock().expect("tracked callback result") = Some(value);
+ });
+ TrackedCompletion {
+ completion: build(callback),
+ count,
+ result,
+ }
+}
+
+fn read_completion(buffer: Arc<Buffer>) -> TrackedCompletion {
+ let count = Arc::new(AtomicUsize::new(0));
+ let result = Arc::new(Mutex::new(None));
+ let callback_count = count.clone();
+ let callback_result = result.clone();
+ let completion = Completion::new_read(buffer, move |value| {
+ callback_count.fetch_add(1, Ordering::SeqCst);
+ *callback_result.lock().expect("tracked read result") = Some(
+ value
+ .as_ref()
+ .map(|(_, bytes)| *bytes)
+ .map_err(|error| *error),
+ );
+ None
+ });
+ TrackedCompletion {
+ completion,
+ count,
+ result,
+ }
+}
+
+fn assert_completion(tracked: &TrackedCompletion, expected: Result<i32, CompletionError>) {
+ assert_eq!(tracked.count.load(Ordering::SeqCst), 1);
+ assert_eq!(
+ tracked.result.lock().expect("tracked result").as_ref(),
+ Some(&expected)
+ );
+ assert!(tracked.completion.finished());
+ assert_eq!(tracked.completion.get_error(), expected.err());
+}
+
+fn query_one_i64(connection: &Arc<Connection>, sql: &str) -> turso_core::Result<i64> {
+ let mut statement = connection.prepare(sql)?;
+ let mut result = None;
+ drive_statement(&mut statement, |row| {
+ result = Some(row.get::<i64>(0)?);
+ Ok(())
+ })?;
+ result.ok_or_else(|| LimboError::InternalError("query returned no row".into()))
+}
+
+fn drive_statement(
+ statement: &mut turso_core::Statement,
+ mut on_row: impl FnMut(&Row) -> turso_core::Result<()>,
+) -> turso_core::Result<()> {
+ loop {
+ match statement.step()? {
+ StepResult::Done => return Ok(()),
+ StepResult::Row => on_row(
+ statement
+ .row()
+ .ok_or_else(|| LimboError::InternalError("row step had no row".into()))?,
+ )?,
+ StepResult::IO | StepResult::Yield => statement._io().step()?,
+ StepResult::Busy => return Err(LimboError::Busy),
+ StepResult::Interrupt => return Err(LimboError::Interrupt),
+ }
+ }
+}
+
+async fn recursive_remove(root: &FileSystemDirectoryHandle, path: &str) {
+ let options = FileSystemRemoveOptions::new();
+ options.set_recursive(true);
+ match JsFuture::from(root.remove_entry_with_options(path, &options)).await {
+ Ok(_) => {}
+ Err(error) if is_not_found(&error) => {}
+ Err(error) => panic!("failed to clean browser test artifact: {error:?}"),
+ }
+}
+
+async fn clean_pair(database_name: &str) {
+ let root = worker_root().await.expect("worker OPFS root");
+ recursive_remove(&root, database_name).await;
+ recursive_remove(&root, &format!("{database_name}-wal")).await;
+}
+
+async fn replace_poisoned_registry_for_test() {
+ let (handles, pending, lock) = REGISTRY.with(|registry| {
+ let mut registry = registry.borrow_mut();
+ (
+ std::mem::take(&mut registry.handles),
+ registry.pending_lock.take(),
+ registry.owner_lock.take(),
+ )
+ });
+ for entry in handles.into_values() {
+ let _ = close_sync_handle(&entry.handle);
+ }
+ if let Some(pending) = pending {
+ pending.controller.abort();
+ }
+ if let Some(lock) = lock {
+ let _ = lock.release.call0(&JsValue::UNDEFINED);
+ if let Some(request) = lock.request {
+ let _ = JsFuture::from(request).await;
+ }
+ }
+ REGISTRY.with(|registry| *registry.borrow_mut() = Registry::default());
+}
+
+async fn open_ready(owner: OpfsOwner) -> OpfsSession {
+ match owner.open().await.expect("pre-open OPFS pair") {
+ OpenResult::Ready(session) => session,
+ OpenResult::ResetRequired(_) => panic!("expected a complete OPFS pair"),
+ }
+}
+
+fn connect_ready(session: OpfsSession) -> ConnectedOpfsSession {
+ session
+ .connect()
+ .expect("open sole production Turso connection")
+}
+
+async fn fresh_closed(database_name: &str) -> ClosedSession {
+ let owner = OpfsOwner::acquire(database_name)
+ .await
+ .expect("identity-bound owner");
+ let owner = owner.recovery_wipe().await.expect("fresh recovery wipe");
+ connect_ready(open_ready(owner).await)
+ .try_close()
+ .expect("adapter-driven close")
+}
+
+struct RawHeldLock {
+ release: Function,
+ request: Promise,
+ _grant: Function,
+}
+
+impl RawHeldLock {
+ async fn release(self) {
+ self.release
+ .call0(&JsValue::UNDEFINED)
+ .expect("release raw test Web Lock");
+ JsFuture::from(self.request)
+ .await
+ .expect("raw test Web Lock settles");
+ }
+}
+
+async fn acquire_raw_web_lock(lock_name: &str) -> RawHeldLock {
+ let worker = js_sys::global()
+ .dyn_into::<DedicatedWorkerGlobalScope>()
+ .expect("DedicatedWorker raw lock");
+ let manager = Reflect::get(worker.navigator().as_ref(), &JsValue::from_str("locks"))
+ .expect("raw Web Lock manager");
+ let mut granted_resolve = None;
+ let granted = Promise::new(&mut |resolve, _reject| granted_resolve = Some(resolve.clone()));
+ let granted_resolve = granted_resolve.expect("granted resolver");
+ let release_slot = Rc::new(RefCell::new(None));
+ let callback_release = release_slot.clone();
+ let grant = Closure::wrap(Box::new(move |lock: JsValue| -> Promise {
+ assert!(!lock.is_null() && !lock.is_undefined());
+ let mut release_resolve = None;
+ let held = Promise::new(&mut |resolve, _reject| release_resolve = Some(resolve.clone()));
+ *callback_release.borrow_mut() = release_resolve;
+ let _ = granted_resolve.call1(&JsValue::UNDEFINED, &JsValue::TRUE);
+ held
+ }) as Box<dyn FnMut(JsValue) -> Promise>)
+ .into_js_value()
+ .unchecked_into::<Function>();
+ let options = Object::new();
+ Reflect::set(
+ options.as_ref(),
+ &JsValue::from_str("mode"),
+ &JsValue::from_str("exclusive"),
+ )
+ .expect("raw lock mode");
+ let request = Reflect::get(&manager, &JsValue::from_str("request"))
+ .expect("raw request property")
+ .dyn_into::<Function>()
+ .expect("raw request function")
+ .call3(
+ &manager,
+ &JsValue::from_str(lock_name),
+ options.as_ref(),
+ grant.as_ref(),
+ )
+ .expect("raw lock request")
+ .dyn_into::<Promise>()
+ .expect("raw request promise");
+ JsFuture::from(granted).await.expect("raw Web Lock granted");
+ let release = release_slot
+ .borrow_mut()
+ .take()
+ .expect("raw lock release resolver");
+ RawHeldLock {
+ release,
+ request,
+ _grant: grant,
+ }
+}
+
+async fn yield_tasks_until(mut condition: impl FnMut() -> bool) {
+ for _ in 0..32 {
+ if condition() {
+ return;
+ }
+ let task = Promise::new(&mut |resolve, reject| {
+ let result = Reflect::get(&js_sys::global(), &JsValue::from_str("setTimeout"))
+ .and_then(|value| value.dyn_into::<Function>())
+ .and_then(|set_timeout| {
+ set_timeout.call2(&js_sys::global(), resolve.as_ref(), &JsValue::from_f64(0.0))
+ });
+ if let Err(error) = result {
+ let _ = reject.call1(&JsValue::UNDEFINED, &error);
+ }
+ });
+ JsFuture::from(task).await.expect("browser task yield");
+ }
+ assert!(
+ condition(),
+ "condition did not settle after browser task yields"
+ );
+}
+
+async fn web_lock_available(lock_name: &str) -> bool {
+ let worker = js_sys::global()
+ .dyn_into::<DedicatedWorkerGlobalScope>()
+ .expect("DedicatedWorker lock probe");
+ let manager = Reflect::get(worker.navigator().as_ref(), &JsValue::from_str("locks"))
+ .expect("Web Lock manager");
+ let options = Object::new();
+ Reflect::set(
+ options.as_ref(),
+ &JsValue::from_str("mode"),
+ &JsValue::from_str("exclusive"),
+ )
+ .expect("lock mode");
+ Reflect::set(
+ options.as_ref(),
+ &JsValue::from_str("ifAvailable"),
+ &JsValue::TRUE,
+ )
+ .expect("ifAvailable");
+ let observed = Rc::new(Cell::new(None));
+ let callback_observed = observed.clone();
+ let callback = Closure::wrap(Box::new(move |lock: JsValue| -> Promise {
+ callback_observed.set(Some(!lock.is_null() && !lock.is_undefined()));
+ Promise::resolve(&JsValue::UNDEFINED)
+ }) as Box<dyn FnMut(JsValue) -> Promise>);
+ let request = Reflect::get(&manager, &JsValue::from_str("request"))
+ .expect("request property")
+ .dyn_into::<Function>()
+ .expect("request function")
+ .call3(
+ &manager,
+ &JsValue::from_str(lock_name),
+ options.as_ref(),
+ callback.as_ref().unchecked_ref::<Function>().as_ref(),
+ )
+ .expect("request lock probe")
+ .dyn_into::<Promise>()
+ .expect("request promise");
+ JsFuture::from(request).await.expect("lock probe completes");
+ observed.get().expect("lock callback observed")
+}
+
+fn poll_once<F: Future>(mut future: std::pin::Pin<&mut F>) -> Poll<F::Output> {
+ let waker = Waker::noop();
+ let mut context = Context::from_waker(waker);
+ future.as_mut().poll(&mut context)
+}
+
+fn assert_poisoned() {
+ assert!(REGISTRY.with(|registry| registry.borrow().machine.is_poisoned()));
+}
+
+#[wasm_bindgen_test]
+async fn real_worker_opfs_contract_and_consuming_lifecycle() {
+ let nonce = js_sys::Date::now() as u64;
+ let database_name = format!("wp05-{nonce}.db");
+ let wal_name = format!("{database_name}-wal");
+ clean_pair(&database_name).await;
+
+ assert_eq!(
+ OpfsOwner::acquire("")
+ .await
+ .expect_err("empty database identity")
+ .kind(),
+ OpfsErrorKind::InvalidName
+ );
+ assert_eq!(
+ OpfsOwner::acquire("nested/cache.db")
+ .await
+ .expect_err("database identity must be a direct child")
+ .kind(),
+ OpfsErrorKind::InvalidName
+ );
+ assert_eq!(
+ OpfsOwner::acquire(&format!("{database_name}-wal"))
+ .await
+ .expect_err("a WAL path cannot become a second canonical identity")
+ .kind(),
+ OpfsErrorKind::InvalidName
+ );
+
+ // Cancellation before grant keeps JS-owned callbacks alive until the
+ // aborted request rejects, then clears the pending capability without a
+ // trap or leaked lock.
+ let queued_db = format!("wp05-lock-queued-{nonce}.db");
+ let queued_lock_name = owner_lock_name(&queued_db);
+ let blocker = acquire_raw_web_lock(&queued_lock_name).await;
+ let mut queued_acquire = Box::pin(OpfsOwner::acquire(&queued_db));
+ assert!(matches!(poll_once(queued_acquire.as_mut()), Poll::Pending));
+ assert!(REGISTRY.with(|registry| registry.borrow().pending_lock.is_some()));
+ drop(queued_acquire);
+ yield_tasks_until(|| REGISTRY.with(|registry| registry.borrow().pending_lock.is_none())).await;
+ assert!(REGISTRY.with(|registry| registry.borrow().owner_lock.is_none()));
+ assert_eq!(
+ REGISTRY.with(|registry| registry.borrow().machine.phase_label()),
+ "unowned"
+ );
+ blocker.release().await;
+ assert!(web_lock_available(&queued_lock_name).await);
+
+ // If the browser grants before Rust polls the acquisition future again,
+ // dropping that future poisons, releases, and retains all JS callbacks
+ // until the held request fulfills.
+ let granted_db = format!("wp05-lock-granted-{nonce}.db");
+ let granted_lock_name = owner_lock_name(&granted_db);
+ let mut granted_acquire = Box::pin(OpfsOwner::acquire(&granted_db));
+ assert!(matches!(poll_once(granted_acquire.as_mut()), Poll::Pending));
+ yield_tasks_until(|| REGISTRY.with(|registry| registry.borrow().owner_lock.is_some())).await;
+ assert!(REGISTRY.with(|registry| registry.borrow().pending_lock.is_some()));
+ drop(granted_acquire);
+ yield_tasks_until(|| {
+ REGISTRY.with(|registry| {
+ let registry = registry.borrow();
+ registry.pending_lock.is_none() && registry.owner_lock.is_none()
+ })
+ })
+ .await;
+ assert_poisoned();
+ assert!(web_lock_available(&granted_lock_name).await);
+ replace_poisoned_registry_for_test().await;
+
+ let mut owner = OpfsOwner::acquire(&database_name)
+ .await
+ .expect("physical owner Web Lock");
+ assert_eq!(owner.database_path(), database_name);
+ assert_eq!(owner.lock_name(), owner_lock_name(&database_name));
+ assert!(!web_lock_available(owner.lock_name()).await);
+ assert_eq!(
+ OpfsOwner::acquire("other.db")
+ .await
+ .expect_err("one worker cannot own a second capability")
+ .kind(),
+ OpfsErrorKind::Ownership
+ );
+
+ REGISTRY.with(|registry| registry.borrow_mut().faults.fail_open = Some(FileRole::Wal));
+ let failure = owner
+ .open()
+ .await
+ .expect_err("injected WAL pre-open failure");
+ assert_eq!(failure.error().kind(), OpfsErrorKind::Open);
+ owner = failure
+ .into_owner()
+ .expect("certain partial-open cleanup returns locked owner");
+ assert_eq!(
+ REGISTRY.with(|registry| registry.borrow().machine.phase_label()),
+ "idle"
+ );
+ assert!(REGISTRY.with(|registry| registry.borrow().handles.is_empty()));
+
+ let incomplete = match owner.open().await.expect("detect one-sided pair") {
+ OpenResult::ResetRequired(incomplete) => incomplete,
+ OpenResult::Ready(_) => panic!("one-sided pair must never expose Turso I/O"),
+ };
+ assert_eq!(incomplete.database_path(), database_name);
+ owner = incomplete
+ .reset()
+ .await
+ .expect("reset-only type removes and recreates both paths");
+
+ let session = open_ready(owner).await;
+ assert_eq!(session.disposition(), OpenDisposition::Fresh);
+ assert_eq!(session.database_path(), database_name);
+ assert_eq!(session.wal_path(), wal_name);
+
+ // Internal-only direct adapter checks. Production callers cannot obtain
+ // this I/O; they can only consume OpfsSession::connect.
+ {
+ let io = session.io.clone();
+ let main = io
+ .open_file(&database_name, OpenFlags::Create, true)
+ .expect("approved main flags");
+ let wal = io
+ .open_file(&wal_name, OpenFlags::Create, false)
+ .expect("approved WAL flags");
+ assert!(
+ io.open_file("unregistered.db", OpenFlags::Create, true)
+ .is_err()
+ );
+ assert!(
+ io.open_file(&database_name, OpenFlags::ReadOnly, true)
+ .is_err()
+ );
+ assert!(
+ io.open_file(&database_name, OpenFlags::Create | OpenFlags::NoLock, true,)
+ .is_err()
+ );
+ assert!(io.open_file(&wal_name, OpenFlags::Create, true).is_err());
+ assert!(io.remove_file(&database_name).is_err());
+ assert_eq!(
+ io.file_id(&database_name).expect("registered file ID"),
+ FileId::from_path_hash(&database_name)
+ );
+ main.lock_file(true)
+ .expect("owner lock makes file lock a no-op");
+ main.unlock_file().expect("owner unlock no-op");
+ // Monotonic clock samples are strictly increasing.
+ assert!(io.current_time_monotonic() < io.current_time_monotonic());
+ // Wall-clock micros is the sub-second microsecond component.
+ assert!(io.current_time_wall_clock().micros < 1_000_000);
+
+ let empty = write_completion();
+ drop(
+ main.pwrite(
+ u64::MAX,
+ Arc::new(Buffer::new(Vec::new())),
+ empty.completion.clone(),
+ )
+ .expect("empty write submission"),
+ );
+ assert_completion(&empty, Ok(0));
+
+ REGISTRY.with(|registry| registry.borrow_mut().faults.max_write_chunk = Some(2));
+ let partial = write_completion();
+ drop(
+ main.pwrite(
+ 0,
+ Arc::new(Buffer::new(b"abcdef".to_vec())),
+ partial.completion.clone(),
+ )
+ .expect("partial write retry submission"),
+ );
+ assert_completion(&partial, Ok(6));
+ REGISTRY.with(|registry| registry.borrow_mut().faults.max_write_chunk = None);
+
+ let vectored = write_completion();
+ drop(
+ main.pwritev(
+ 6,
+ vec![
+ Arc::new(Buffer::new(b"12".to_vec())),
+ Arc::new(Buffer::new(b"34".to_vec())),
+ ],
+ vectored.completion.clone(),
+ )
+ .expect("vectored write submission"),
+ );
+ assert_completion(&vectored, Ok(4));
+ assert_eq!(main.size().expect("size after writes"), 10);
+
+ let before_overflow = main.size().expect("size before overflow probes");
+ let overflow = write_completion();
+ drop(
+ main.pwrite(
+ MAX_SAFE_INTEGER,
+ Arc::new(Buffer::new(vec![1])),
+ overflow.completion.clone(),
+ )
+ .expect("overflow submission completes through callback"),
+ );
+ assert_completion(
+ &overflow,
+ Err(CompletionError::IOError(
+ ErrorKind::InvalidInput,
+ "OPFS write end exceeds JavaScript safe integer",
+ )),
+ );
+ assert_eq!(
+ main.size().expect("pwrite overflow is mutation-free"),
+ before_overflow
+ );
+
+ let vectored_overflow = write_completion();
+ drop(
+ main.pwritev(
+ MAX_SAFE_INTEGER - 1,
+ vec![
+ Arc::new(Buffer::new(vec![1])),
+ Arc::new(Buffer::new(vec![2])),
+ ],
+ vectored_overflow.completion.clone(),
+ )
+ .expect("vectored overflow submission"),
+ );
+ assert_completion(
+ &vectored_overflow,
+ Err(CompletionError::IOError(
+ ErrorKind::InvalidInput,
+ "OPFS write end exceeds JavaScript safe integer",
+ )),
+ );
+ assert_eq!(
+ main.size().expect("pwritev overflow is mutation-free"),
+ before_overflow
+ );
+ assert_eq!(
+ preflight_write_range(0, [i32::MAX as usize, 1]),
+ Err(CompletionError::ShortWrite)
+ );
+
+ let truncate = truncate_completion();
+ drop(
+ main.truncate(0, truncate.completion.clone())
+ .expect("clear direct test bytes"),
+ );
+ assert_completion(&truncate, Ok(0));
+ let injected = CompletionError::IOError(ErrorKind::StorageFull, "injected partial error");
+ REGISTRY.with(|registry| {
+ let mut registry = registry.borrow_mut();
+ registry.faults.max_write_chunk = Some(2);
+ registry.faults.write_error_after_chunks = Some((1, injected));
+ });
+ let partial_error = write_completion();
+ drop(
+ main.pwrite(
+ 0,
+ Arc::new(Buffer::new(b"abcdef".to_vec())),
+ partial_error.completion.clone(),
+ )
+ .expect("partial-then-error submission"),
+ );
+ assert_completion(&partial_error, Err(injected));
+ assert_eq!(main.size().expect("first chunk was physically written"), 2);
+ let partial_bytes = Arc::new(Buffer::new(vec![0; 2]));
+ let partial_read = read_completion(partial_bytes.clone());
+ drop(
+ main.pread(0, partial_read.completion.clone())
+ .expect("read partial runtime write"),
+ );
+ assert_completion(&partial_read, Ok(2));
+ assert_eq!(partial_bytes.as_slice(), b"ab");
+ REGISTRY.with(|registry| registry.borrow_mut().faults.max_write_chunk = None);
+
+ let clear = truncate_completion();
+ drop(
+ main.truncate(0, clear.completion.clone())
+ .expect("restore blank Turso main file"),
+ );
+ assert_completion(&clear, Ok(0));
+ let sync = sync_completion();
+ drop(
+ main.sync(sync.completion.clone(), FileSyncType::Fsync)
+ .expect("sync blank file"),
+ );
+ assert_completion(&sync, Ok(0));
+
+ let reentrant_rejected = Arc::new(AtomicBool::new(false));
+ let callback_file = main.clone();
+ let callback_observation = reentrant_rejected.clone();
+ let reentrant = Completion::new_write(move |_| {
+ callback_observation.store(callback_file.size().is_err(), Ordering::SeqCst);
+ });
+ drop(
+ main.pwrite(0, Arc::new(Buffer::new(Vec::new())), reentrant.clone())
+ .expect("reentrancy callback probe"),
+ );
+ assert!(reentrant.finished());
+ assert!(reentrant_rejected.load(Ordering::SeqCst));
+ drop((main, wal, io));
+ }
+
+ let stale_owner = session.owner;
+ let stale_session = session.session;
+ let connected = connect_ready(session);
+ let connection = connected.connection();
+ connection
+ .execute("CREATE TABLE persistence (id INTEGER PRIMARY KEY, value TEXT NOT NULL)")
+ .expect("create persistence table");
+ connection
+ .execute("INSERT INTO persistence (id, value) VALUES (1, 'preserved')")
+ .expect("insert persistence marker");
+ assert_eq!(
+ query_one_i64(&connection, "SELECT COUNT(*) FROM persistence")
+ .expect("query persistence count"),
+ 1
+ );
+
+ let close_failure = connected
+ .try_close()
+ .expect_err("connection clone proves graceful close was omitted");
+ assert_eq!(
+ close_failure.error().kind(),
+ OpfsErrorKind::ActiveReferences
+ );
+ let connected = close_failure
+ .into_session()
+ .expect("pre-close rejection returns connected session");
+ assert!(!connection.is_closed());
+ let connection_weak = Arc::downgrade(&connection);
+ drop(connection);
+ let close_calls = REGISTRY.with(|registry| registry.borrow().faults.connection_close_calls);
+ let closed = connected
+ .try_close()
+ .expect("adapter calls and proves Connection::close success");
+ assert_eq!(
+ REGISTRY.with(|registry| registry.borrow().faults.connection_close_calls),
+ close_calls + 1
+ );
+ assert!(connection_weak.upgrade().is_none());
+
+ let valid_token = closed.token;
+ let invalid = ClosedSession {
+ owner: closed.owner,
+ token: CloseToken::from_raw(valid_token.get() + 1),
+ armed: true,
+ };
+ assert_eq!(
+ invalid.preserve().expect_err("invalid close token").kind(),
+ OpfsErrorKind::Lifecycle
+ );
+ assert_eq!(
+ REGISTRY.with(|registry| registry.borrow().machine.phase_label()),
+ "closed"
+ );
+ let closed = ClosedSession {
+ owner: stale_owner,
+ token: valid_token,
+ armed: true,
+ };
+ owner = closed.preserve().expect("valid one-use preserve");
+
+ let session = open_ready(owner).await;
+ assert_eq!(session.disposition(), OpenDisposition::Existing);
+ let connected = connect_ready(session);
+ let connection = connected.connection();
+ assert_eq!(
+ query_one_i64(&connection, "SELECT COUNT(*) FROM persistence")
+ .expect("preserved row count"),
+ 1
+ );
+ drop(connection);
+ owner = connected
+ .try_close()
+ .expect("close preserved Turso session")
+ .reset()
+ .await
+ .expect("delete and recreate complete pair");
+ assert!(REGISTRY.with(|registry| {
+ registry
+ .borrow_mut()
+ .machine
+ .preserve(stale_owner, valid_token)
+ .is_err()
+ }));
+ assert_eq!(
+ REGISTRY.with(|registry| registry.borrow().machine.phase_label()),
+ "idle"
+ );
+
+ let stale_io = OpfsIo {
+ owner: stale_owner,
+ session: stale_session,
+ references: Arc::new(SessionReferences),
+ last_monotonic_nanos: AtomicU64::new(0),
+ };
+ assert!(
+ stale_io
+ .open_file(&database_name, OpenFlags::Create, true)
+ .is_err()
+ );
+ assert_eq!(
+ REGISTRY.with(|registry| registry.borrow().machine.phase_label()),
+ "idle"
+ );
+
+ let session = open_ready(owner).await;
+ assert_eq!(session.disposition(), OpenDisposition::Fresh);
+ {
+ let io = session.io.clone();
+ let main = io
+ .open_file(&database_name, OpenFlags::Create, true)
+ .expect("recreated main");
+ let wal = io
+ .open_file(&wal_name, OpenFlags::Create, false)
+ .expect("recreated WAL");
+ assert_eq!(main.size().expect("recreated main is empty"), 0);
+ assert_eq!(wal.size().expect("recreated WAL is empty"), 0);
+ }
+ let connected = connect_ready(session);
+ let closed = connected.try_close().expect("close recreated pair");
+ owner = closed.preserve().expect("preserve recreated pair");
+ let lock_name = owner.lock_name().to_owned();
+ owner
+ .release()
+ .await
+ .expect("prove physical Web Lock release");
+ assert!(web_lock_available(&lock_name).await);
+ clean_pair(&database_name).await;
+
+ // Recovery wipe recursively resolves a pre-open directory conflict while
+ // the bound owner lock is physically held.
+ let recovery_db = format!("wp05-recovery-{nonce}.db");
+ let root = worker_root().await.expect("recovery root");
+ let directory_options = FileSystemGetDirectoryOptions::new();
+ directory_options.set_create(true);
+ let conflict =
+ JsFuture::from(root.get_directory_handle_with_options(&recovery_db, &directory_options))
+ .await
+ .expect("conflicting main directory")
+ .dyn_into::<FileSystemDirectoryHandle>()
+ .expect("directory conflict type");
+ let child_options = FileSystemGetFileOptions::new();
+ child_options.set_create(true);
+ JsFuture::from(conflict.get_file_handle_with_options("child", &child_options))
+ .await
+ .expect("non-empty conflict");
+ owner = OpfsOwner::acquire(&recovery_db)
+ .await
+ .expect("recovery owner");
+ owner = owner
+ .recovery_wipe()
+ .await
+ .expect("owner-bound pre-open recovery wipe");
+ let connected = connect_ready(open_ready(owner).await);
+ owner = connected
+ .try_close()
+ .expect("close recovery pair")
+ .preserve()
+ .expect("preserve recovery pair");
+ owner.release().await.expect("release recovery lock");
+ clean_pair(&recovery_db).await;
+
+ // Cancellation after start_reset enters Resetting and the armed future
+ // guard poisons on drop.
+ let cancel_db = format!("wp05-cancel-{nonce}.db");
+ let closed = fresh_closed(&cancel_db).await;
+ let mut reset = Box::pin(closed.reset());
+ assert!(matches!(poll_once(reset.as_mut()), Poll::Pending));
+ assert_eq!(
+ REGISTRY.with(|registry| registry.borrow().machine.phase_label()),
+ "resetting"
+ );
+ drop(reset);
+ assert_poisoned();
+ replace_poisoned_registry_for_test().await;
+ clean_pair(&cancel_db).await;
+
+ for (suffix, fault, expected_kind) in [
+ (
+ "remove",
+ ResetFault::AfterMainRemoval,
+ OpfsErrorKind::Remove,
+ ),
+ (
+ "recreate",
+ ResetFault::AfterMainRecreate,
+ OpfsErrorKind::Recreate,
+ ),
+ ] {
+ let db = format!("wp05-{suffix}-{nonce}.db");
+ let closed = fresh_closed(&db).await;
+ REGISTRY.with(|registry| registry.borrow_mut().faults.reset_fault = Some(fault));
+ let failure = closed
+ .reset()
+ .await
+ .expect_err("partial reset failure must poison");
+ assert_eq!(failure.error().kind(), expected_kind);
+ assert_poisoned();
+ replace_poisoned_registry_for_test().await;
+ clean_pair(&db).await;
+ }
+
+ // Adapter-driven Connection::close failure is consuming and poison-only.
+ let close_fail_db = format!("wp05-close-fail-{nonce}.db");
+ let owner = OpfsOwner::acquire(&close_fail_db)
+ .await
+ .expect("close-failure owner")
+ .recovery_wipe()
+ .await
+ .expect("close-failure wipe");
+ let connected = connect_ready(open_ready(owner).await);
+ REGISTRY.with(|registry| registry.borrow_mut().faults.fail_connection_close = true);
+ let failure = connected
+ .try_close()
+ .expect_err("injected Turso close failure");
+ assert_eq!(failure.error().kind(), OpfsErrorKind::Turso);
+ assert!(failure.into_session().is_none());
+ assert_poisoned();
+ replace_poisoned_registry_for_test().await;
+ clean_pair(&close_fail_db).await;
+
+ // Pinned Turso marks a connection closed before shutdown checkpoint can
+ // fail. A faithful out-of-band marked-then-error sequence must therefore
+ // never be accepted later as a healthy adapter-driven close.
+ let out_of_band_db = format!("wp05-out-of-band-close-{nonce}.db");
+ let owner = OpfsOwner::acquire(&out_of_band_db)
+ .await
+ .expect("out-of-band owner")
+ .recovery_wipe()
+ .await
+ .expect("out-of-band wipe");
+ let connected = connect_ready(open_ready(owner).await);
+ let connection = connected.connection();
+ assert!(inject_out_of_band_marked_close_failure(&connection).is_err());
+ assert!(connection.is_closed());
+ drop(connection);
+ let failure = connected
+ .try_close()
+ .expect_err("already-closed connection must poison");
+ assert_eq!(failure.error().kind(), OpfsErrorKind::Turso);
+ assert!(failure.into_session().is_none());
+ assert_poisoned();
+ replace_poisoned_registry_for_test().await;
+ clean_pair(&out_of_band_db).await;
+
+ // Open/storage failures preserve storage-full classification but never
+ // return a reusable ready session. Recovery is replacement + canonical
+ // lock reacquisition + wipe-before-open.
+ let storage_fail_db = format!("wp05-storage-fail-{nonce}.db");
+ let owner = OpfsOwner::acquire(&storage_fail_db)
+ .await
+ .expect("storage-failure owner")
+ .recovery_wipe()
+ .await
+ .expect("storage-failure wipe");
+ let session = open_ready(owner).await;
+ REGISTRY.with(|registry| {
+ registry.borrow_mut().faults.database_open_error = Some(CompletionError::IOError(
+ ErrorKind::StorageFull,
+ "injected database storage recovery",
+ ));
+ });
+ let failure = session
+ .connect()
+ .expect_err("database open/storage failure must poison");
+ assert_eq!(failure.error().kind(), OpfsErrorKind::StorageFull);
+ assert_poisoned();
+ replace_poisoned_registry_for_test().await;
+ let owner = OpfsOwner::acquire(&storage_fail_db)
+ .await
+ .expect("replacement storage owner")
+ .recovery_wipe()
+ .await
+ .expect("replacement recovery wipe");
+ let connected = connect_ready(open_ready(owner).await);
+ let owner = connected
+ .try_close()
+ .expect("replacement closes cleanly")
+ .preserve()
+ .expect("replacement preserve");
+ owner.release().await.expect("release replacement lock");
+ clean_pair(&storage_fail_db).await;
+
+ let connect_fail_db = format!("wp05-connect-fail-{nonce}.db");
+ let owner = OpfsOwner::acquire(&connect_fail_db)
+ .await
+ .expect("connect-failure owner")
+ .recovery_wipe()
+ .await
+ .expect("connect-failure wipe");
+ let session = open_ready(owner).await;
+ REGISTRY.with(|registry| {
+ registry.borrow_mut().faults.database_connect_error = Some(CompletionError::IOError(
+ ErrorKind::Other,
+ "injected database connect failure",
+ ));
+ });
+ let failure = session
+ .connect()
+ .expect_err("database connect failure must poison");
+ assert_eq!(failure.error().kind(), OpfsErrorKind::Turso);
+ assert_poisoned();
+ replace_poisoned_registry_for_test().await;
+ clean_pair(&connect_fail_db).await;
+
+ // Omitting the consuming close transition poisons on drop.
+ let omit_db = format!("wp05-omit-close-{nonce}.db");
+ let owner = OpfsOwner::acquire(&omit_db)
+ .await
+ .expect("omitted-close owner")
+ .recovery_wipe()
+ .await
+ .expect("omitted-close wipe");
+ drop(connect_ready(open_ready(owner).await));
+ assert_poisoned();
+ replace_poisoned_registry_for_test().await;
+ clean_pair(&omit_db).await;
+
+ let incomplete_drop_db = format!("wp05-incomplete-drop-{nonce}.db");
+ let root = worker_root().await.expect("incomplete-drop root");
+ let create = FileSystemGetFileOptions::new();
+ create.set_create(true);
+ JsFuture::from(root.get_file_handle_with_options(&incomplete_drop_db, &create))
+ .await
+ .expect("create one-sided main path");
+ let owner = OpfsOwner::acquire(&incomplete_drop_db)
+ .await
+ .expect("incomplete-drop owner");
+ let incomplete = match owner.open().await.expect("one-sided open") {
+ OpenResult::ResetRequired(incomplete) => incomplete,
+ OpenResult::Ready(_) => panic!("one-sided drop probe must be reset-only"),
+ };
+ drop(incomplete);
+ assert_poisoned();
+ replace_poisoned_registry_for_test().await;
+ clean_pair(&incomplete_drop_db).await;
+
+ // Browser-invalid state for a registered active handle is an ownership
+ // invariant failure: ErrorKind::Other plus poison, never WouldBlock.
+ let invalid_db = format!("wp05-invalid-handle-{nonce}.db");
+ let owner = OpfsOwner::acquire(&invalid_db)
+ .await
+ .expect("invalid-handle owner")
+ .recovery_wipe()
+ .await
+ .expect("invalid-handle wipe");
+ let session = open_ready(owner).await;
+ let io = session.io.clone();
+ let main = io
+ .open_file(&invalid_db, OpenFlags::Create, true)
+ .expect("registered main before invalidation");
+ let registered_main = REGISTRY.with(|registry| {
+ registry
+ .borrow()
+ .handles
+ .values()
+ .find(|entry| entry.role == FileRole::Main)
+ .expect("registered main handle")
+ .handle
+ .clone()
+ });
+ close_sync_handle(&registered_main).expect("externally invalidate active handle in test");
+ let error = main.size().expect_err("invalid active handle must fail");
+ assert!(matches!(
+ error,
+ LimboError::CompletionError(CompletionError::IOError(ErrorKind::Other, _))
+ ));
+ assert_poisoned();
+ drop((main, io, session));
+ replace_poisoned_registry_for_test().await;
+ clean_pair(&invalid_db).await;
+
+ // Armed owner and close-token drops also poison and begin lock release.
+ let owner_drop_db = format!("wp05-owner-drop-{nonce}.db");
+ drop(
+ OpfsOwner::acquire(&owner_drop_db)
+ .await
+ .expect("owner drop capability"),
+ );
+ assert_poisoned();
+ replace_poisoned_registry_for_test().await;
+
+ let token_drop_db = format!("wp05-token-drop-{nonce}.db");
+ drop(fresh_closed(&token_drop_db).await);
+ assert_poisoned();
+ replace_poisoned_registry_for_test().await;
+ clean_pair(&token_drop_db).await;
+
+ // Uncertain partial-open and handle-close cleanup retain no reusable type.
+ let uncertain_open_db = format!("wp05-open-poison-{nonce}.db");
+ let owner = OpfsOwner::acquire(&uncertain_open_db)
+ .await
+ .expect("uncertain-open owner");
+ REGISTRY.with(|registry| {
+ let mut registry = registry.borrow_mut();
+ registry.faults.fail_open = Some(FileRole::Wal);
+ registry.faults.fail_close = Some(FileRole::Main);
+ });
+ let failure = owner
+ .open()
+ .await
+ .expect_err("uncertain partial-open cleanup");
+ assert_eq!(failure.error().kind(), OpfsErrorKind::Poisoned);
+ assert!(failure.into_owner().is_none());
+ assert_poisoned();
+ replace_poisoned_registry_for_test().await;
+ clean_pair(&uncertain_open_db).await;
+
+ let uncertain_close_db = format!("wp05-handle-close-{nonce}.db");
+ let owner = OpfsOwner::acquire(&uncertain_close_db)
+ .await
+ .expect("uncertain-handle-close owner")
+ .recovery_wipe()
+ .await
+ .expect("uncertain-handle-close wipe");
+ let connected = connect_ready(open_ready(owner).await);
+ REGISTRY.with(|registry| registry.borrow_mut().faults.fail_close = Some(FileRole::Wal));
+ let failure = connected
+ .try_close()
+ .expect_err("uncertain sync handle close");
+ assert_eq!(failure.error().kind(), OpfsErrorKind::Close);
+ assert!(failure.into_session().is_none());
+ assert_poisoned();
+ replace_poisoned_registry_for_test().await;
+ clean_pair(&uncertain_close_db).await;
+}
diff --git a/crates/client/turso-opfs/src/lib.rs b/crates/client/turso-opfs/src/lib.rs
new file mode 100644
index 0000000000..dc67c7cb8c
--- /dev/null
+++ b/crates/client/turso-opfs/src/lib.rs
@@ -0,0 +1,30 @@
+//! Browser-only Turso I/O over worker-owned Origin Private File System files.
+//!
+//! The production implementation exists only on `wasm32` DedicatedWorkers.
+//! [`OpfsOwner::acquire`] derives and physically holds an exclusive Web Lock
+//! and main/WAL paths from one canonical database identity. JavaScript lock and OPFS handles remain in
+//! worker-local storage; Turso sees only checked numeric IDs.
+//!
+//! Opening is typed: a one-sided main/WAL pair becomes
+//! [`ResetRequiredSession`] and cannot expose I/O. A complete [`OpfsSession`]
+//! creates exactly one production Turso connection. Closing is consuming and
+//! adapter-driven: [`ConnectedOpfsSession::try_close`] requires sole connection
+//! ownership, calls `Connection::close`, proves success, drops Turso resources,
+//! checks all references, and only then closes OPFS handles. [`ClosedSession`]
+//! is a one-use choice between preservation and asynchronous physical reset.
+
+#![deny(missing_docs)]
+#![forbid(unsafe_code)]
+
+#[cfg(any(test, target_arch = "wasm32"))]
+mod state;
+
+#[cfg(target_arch = "wasm32")]
+mod browser;
+
+#[cfg(target_arch = "wasm32")]
+pub use browser::{
+ CloseFailure, ClosedSession, ConnectFailure, ConnectedOpfsSession, OpenDisposition,
+ OpenFailure, OpenResult, OpfsError, OpfsErrorKind, OpfsOwner, OpfsSession, ResetFailure,
+ ResetRequiredSession, WipeFailure,
+};
diff --git a/crates/client/turso-opfs/src/state.rs b/crates/client/turso-opfs/src/state.rs
new file mode 100644
index 0000000000..451f24fd55
--- /dev/null
+++ b/crates/client/turso-opfs/src/state.rs
@@ -0,0 +1,834 @@
+//! Target-independent consuming lifecycle for the worker-local adapter.
+
+use std::fmt;
+
+#[cfg(test)]
+mod test;
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub(crate) struct OwnerId(u64);
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub(crate) struct SessionId(u64);
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub(crate) struct HandleId(u64);
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub(crate) struct CloseToken(u64);
+
+impl OwnerId {
+ #[cfg(test)]
+ pub(crate) fn get(self) -> u64 {
+ self.0
+ }
+}
+
+impl SessionId {
+ #[cfg(test)]
+ pub(crate) fn get(self) -> u64 {
+ self.0
+ }
+}
+
+impl HandleId {
+ #[cfg(test)]
+ pub(crate) fn get(self) -> u64 {
+ self.0
+ }
+}
+
+impl CloseToken {
+ #[cfg(test)]
+ pub(crate) fn get(self) -> u64 {
+ self.0
+ }
+
+ #[cfg(test)]
+ pub(crate) fn from_raw(value: u64) -> Self {
+ Self(value)
+ }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub(crate) enum FileRole {
+ Main,
+ Wal,
+}
+
+impl FileRole {
+ pub(crate) const ALL: [Self; 2] = [Self::Main, Self::Wal];
+
+ pub(crate) const fn index(self) -> usize {
+ match self {
+ Self::Main => 0,
+ Self::Wal => 1,
+ }
+ }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct Paths {
+ main: String,
+ wal: String,
+}
+
+impl Paths {
+ pub(crate) fn new(main: String, wal: String) -> Self {
+ Self { main, wal }
+ }
+
+ pub(crate) fn get(&self, role: FileRole) -> &str {
+ match role {
+ FileRole::Main => &self.main,
+ FileRole::Wal => &self.wal,
+ }
+ }
+
+ pub(crate) fn role_for(&self, path: &str) -> Option<FileRole> {
+ FileRole::ALL
+ .into_iter()
+ .find(|role| self.get(*role) == path)
+ }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum StateErrorKind {
+ Ownership,
+ Session,
+ Reentrant,
+ ActiveReferences,
+ Path,
+ Flags,
+ Registration,
+ Token,
+ Exhausted,
+ Poisoned,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) struct StateError {
+ pub(crate) kind: StateErrorKind,
+ pub(crate) message: &'static str,
+}
+
+impl StateError {
+ const fn new(kind: StateErrorKind, message: &'static str) -> Self {
+ Self { kind, message }
+ }
+}
+
+impl fmt::Display for StateError {
+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+ formatter.write_str(self.message)
+ }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum ActiveKind {
+ Ready,
+ Connected,
+ ConnectionClosed,
+ ResetOnly,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+enum Phase {
+ Unowned,
+ Idle {
+ owner: OwnerId,
+ },
+ Opening {
+ owner: OwnerId,
+ session: SessionId,
+ paths: Paths,
+ handles: [Option<HandleId>; 2],
+ },
+ Active {
+ owner: OwnerId,
+ session: SessionId,
+ paths: Paths,
+ handles: [HandleId; 2],
+ kind: ActiveKind,
+ operation_active: bool,
+ },
+ Closing {
+ owner: OwnerId,
+ session: SessionId,
+ paths: Paths,
+ },
+ Closed {
+ owner: OwnerId,
+ token: CloseToken,
+ paths: Paths,
+ },
+ Resetting {
+ owner: OwnerId,
+ token: CloseToken,
+ paths: Paths,
+ },
+ Wiping {
+ owner: OwnerId,
+ paths: Paths,
+ },
+ Poisoned {
+ owner: OwnerId,
+ reason: String,
+ },
+}
+
+#[derive(Debug)]
+pub(crate) struct Machine {
+ next_owner: u64,
+ next_session: u64,
+ next_handle: u64,
+ next_close_token: u64,
+ phase: Phase,
+}
+
+impl Default for Machine {
+ fn default() -> Self {
+ Self {
+ next_owner: 0,
+ next_session: 0,
+ next_handle: 0,
+ next_close_token: 0,
+ phase: Phase::Unowned,
+ }
+ }
+}
+
+impl Machine {
+ pub(crate) fn claim_owner(&mut self) -> Result<OwnerId, StateError> {
+ if matches!(self.phase, Phase::Poisoned { .. }) {
+ return Err(poisoned());
+ }
+ if self.phase != Phase::Unowned {
+ return Err(StateError::new(
+ StateErrorKind::Ownership,
+ "worker-local OPFS registry already has an owner",
+ ));
+ }
+ self.next_owner = next_id(self.next_owner, "owner ID space exhausted")?;
+ let owner = OwnerId(self.next_owner);
+ self.phase = Phase::Idle { owner };
+ Ok(owner)
+ }
+
+ pub(crate) fn release_owner(&mut self, owner: OwnerId) -> Result<(), StateError> {
+ match self.phase {
+ Phase::Idle { owner: current } if current == owner => {
+ self.phase = Phase::Unowned;
+ Ok(())
+ }
+ Phase::Poisoned { .. } => Err(poisoned()),
+ _ => Err(StateError::new(
+ StateErrorKind::Ownership,
+ "owner release requires the matching idle owner",
+ )),
+ }
+ }
+
+ pub(crate) fn start_open(
+ &mut self,
+ owner: OwnerId,
+ paths: Paths,
+ ) -> Result<SessionId, StateError> {
+ match self.phase {
+ Phase::Idle { owner: current } if current == owner => {}
+ Phase::Poisoned { .. } => return Err(poisoned()),
+ _ => {
+ return Err(StateError::new(
+ StateErrorKind::Ownership,
+ "session open requires the matching idle owner",
+ ));
+ }
+ }
+ self.next_session = next_id(self.next_session, "session ID space exhausted")?;
+ let session = SessionId(self.next_session);
+ self.phase = Phase::Opening {
+ owner,
+ session,
+ paths,
+ handles: [None, None],
+ };
+ Ok(session)
+ }
+
+ pub(crate) fn register(
+ &mut self,
+ owner: OwnerId,
+ session: SessionId,
+ role: FileRole,
+ ) -> Result<HandleId, StateError> {
+ let handles = match &mut self.phase {
+ Phase::Opening {
+ owner: current_owner,
+ session: current_session,
+ handles,
+ ..
+ } if *current_owner == owner && *current_session == session => handles,
+ Phase::Poisoned { .. } => return Err(poisoned()),
+ _ => {
+ return Err(StateError::new(
+ StateErrorKind::Session,
+ "handle registration does not match the opening session",
+ ));
+ }
+ };
+ if handles[role.index()].is_some() {
+ return Err(StateError::new(
+ StateErrorKind::Registration,
+ "an approved path was registered twice",
+ ));
+ }
+ self.next_handle = next_id(self.next_handle, "handle ID space exhausted")?;
+ let handle = HandleId(self.next_handle);
+ handles[role.index()] = Some(handle);
+ Ok(handle)
+ }
+
+ pub(crate) fn activate(
+ &mut self,
+ owner: OwnerId,
+ session: SessionId,
+ reset_only: bool,
+ ) -> Result<Paths, StateError> {
+ let (paths, handles) = match &self.phase {
+ Phase::Opening {
+ owner: current_owner,
+ session: current_session,
+ paths,
+ handles: [Some(main), Some(wal)],
+ } if *current_owner == owner && *current_session == session => {
+ (paths.clone(), [*main, *wal])
+ }
+ Phase::Opening { .. } => {
+ return Err(StateError::new(
+ StateErrorKind::Registration,
+ "activation requires both approved paths",
+ ));
+ }
+ Phase::Poisoned { .. } => return Err(poisoned()),
+ _ => {
+ return Err(StateError::new(
+ StateErrorKind::Session,
+ "activation does not match the opening session",
+ ));
+ }
+ };
+ self.phase = Phase::Active {
+ owner,
+ session,
+ paths: paths.clone(),
+ handles,
+ kind: if reset_only {
+ ActiveKind::ResetOnly
+ } else {
+ ActiveKind::Ready
+ },
+ operation_active: false,
+ };
+ Ok(paths)
+ }
+
+ pub(crate) fn bind_connection(
+ &mut self,
+ owner: OwnerId,
+ session: SessionId,
+ ) -> Result<(), StateError> {
+ match &mut self.phase {
+ Phase::Active {
+ owner: current_owner,
+ session: current_session,
+ kind,
+ operation_active: false,
+ ..
+ } if *current_owner == owner
+ && *current_session == session
+ && *kind == ActiveKind::Ready =>
+ {
+ *kind = ActiveKind::Connected;
+ Ok(())
+ }
+ Phase::Poisoned { .. } => Err(poisoned()),
+ _ => Err(StateError::new(
+ StateErrorKind::Session,
+ "connection binding requires the matching ready session",
+ )),
+ }
+ }
+
+ pub(crate) fn record_connection_close(
+ &mut self,
+ owner: OwnerId,
+ session: SessionId,
+ ) -> Result<(), StateError> {
+ match &mut self.phase {
+ Phase::Active {
+ owner: current_owner,
+ session: current_session,
+ kind,
+ operation_active: false,
+ ..
+ } if *current_owner == owner
+ && *current_session == session
+ && *kind == ActiveKind::Connected =>
+ {
+ *kind = ActiveKind::ConnectionClosed;
+ Ok(())
+ }
+ Phase::Poisoned { .. } => Err(poisoned()),
+ _ => Err(StateError::new(
+ StateErrorKind::ActiveReferences,
+ "connection close proof requires the matching connected session",
+ )),
+ }
+ }
+
+ pub(crate) fn abort_open(
+ &mut self,
+ owner: OwnerId,
+ session: SessionId,
+ cleanup_certain: bool,
+ reason: String,
+ ) -> Result<(), StateError> {
+ match self.phase {
+ Phase::Opening {
+ owner: current_owner,
+ session: current_session,
+ ..
+ } if current_owner == owner && current_session == session => {}
+ Phase::Poisoned { .. } => return Err(poisoned()),
+ _ => {
+ return Err(StateError::new(
+ StateErrorKind::Session,
+ "opening cleanup does not match the opening session",
+ ));
+ }
+ }
+ self.phase = if cleanup_certain {
+ Phase::Idle { owner }
+ } else {
+ Phase::Poisoned { owner, reason }
+ };
+ Ok(())
+ }
+
+ pub(crate) fn validate_session(
+ &self,
+ owner: OwnerId,
+ session: SessionId,
+ ) -> Result<(), StateError> {
+ match self.phase {
+ Phase::Active {
+ owner: current_owner,
+ session: current_session,
+ kind: ActiveKind::Ready | ActiveKind::Connected,
+ ..
+ } if current_owner == owner && current_session == session => Ok(()),
+ Phase::Poisoned { .. } => Err(poisoned()),
+ _ => Err(StateError::new(
+ StateErrorKind::Session,
+ "stale or mismatched owner/session ID",
+ )),
+ }
+ }
+
+ pub(crate) fn validate_open(
+ &self,
+ owner: OwnerId,
+ session: SessionId,
+ path: &str,
+ read_only: bool,
+ no_lock: bool,
+ direct: bool,
+ ) -> Result<HandleId, StateError> {
+ let (paths, handles) = match &self.phase {
+ Phase::Active {
+ owner: current_owner,
+ session: current_session,
+ paths,
+ handles,
+ kind: ActiveKind::Ready | ActiveKind::Connected,
+ ..
+ } if *current_owner == owner && *current_session == session => (paths, handles),
+ Phase::Poisoned { .. } => return Err(poisoned()),
+ _ => {
+ return Err(StateError::new(
+ StateErrorKind::Session,
+ "open_file used a stale or mismatched session",
+ ));
+ }
+ };
+ let role = paths.role_for(path).ok_or_else(|| {
+ StateError::new(
+ StateErrorKind::Path,
+ "open_file path was not pre-registered",
+ )
+ })?;
+ if read_only {
+ return Err(StateError::new(
+ StateErrorKind::Flags,
+ "read-only open is not approved for the writable cache session",
+ ));
+ }
+ let expected_direct = role == FileRole::Main;
+ if direct != expected_direct {
+ return Err(StateError::new(
+ StateErrorKind::Flags,
+ "open_file direct mode does not match the approved main/WAL mode",
+ ));
+ }
+ if no_lock && role != FileRole::Wal {
+ return Err(StateError::new(
+ StateErrorKind::Flags,
+ "NoLock is approved only for the WAL path",
+ ));
+ }
+ Ok(handles[role.index()])
+ }
+
+ pub(crate) fn validate_path(
+ &self,
+ owner: OwnerId,
+ session: SessionId,
+ path: &str,
+ ) -> Result<(), StateError> {
+ let paths = match &self.phase {
+ Phase::Active {
+ owner: current_owner,
+ session: current_session,
+ paths,
+ kind: ActiveKind::Ready | ActiveKind::Connected,
+ ..
+ } if *current_owner == owner && *current_session == session => paths,
+ Phase::Poisoned { .. } => return Err(poisoned()),
+ _ => {
+ return Err(StateError::new(
+ StateErrorKind::Session,
+ "path lookup used a stale or mismatched session",
+ ));
+ }
+ };
+ if paths.role_for(path).is_some() {
+ Ok(())
+ } else {
+ Err(StateError::new(
+ StateErrorKind::Path,
+ "path was not pre-registered",
+ ))
+ }
+ }
+
+ pub(crate) fn begin_operation(
+ &mut self,
+ owner: OwnerId,
+ session: SessionId,
+ ) -> Result<(), StateError> {
+ match &mut self.phase {
+ Phase::Active {
+ owner: current_owner,
+ session: current_session,
+ kind: ActiveKind::Ready | ActiveKind::Connected,
+ operation_active,
+ ..
+ } if *current_owner == owner && *current_session == session => {
+ if *operation_active {
+ return Err(StateError::new(
+ StateErrorKind::Reentrant,
+ "reentrant OPFS operation rejected",
+ ));
+ }
+ *operation_active = true;
+ Ok(())
+ }
+ Phase::Poisoned { .. } => Err(poisoned()),
+ _ => Err(StateError::new(
+ StateErrorKind::Session,
+ "operation used a stale or mismatched session",
+ )),
+ }
+ }
+
+ pub(crate) fn end_operation(&mut self, owner: OwnerId, session: SessionId) {
+ if let Phase::Active {
+ owner: current_owner,
+ session: current_session,
+ operation_active,
+ ..
+ } = &mut self.phase
+ && *current_owner == owner
+ && *current_session == session
+ {
+ *operation_active = false;
+ }
+ }
+
+ pub(crate) fn start_close(
+ &mut self,
+ owner: OwnerId,
+ session: SessionId,
+ ) -> Result<[HandleId; 2], StateError> {
+ self.start_close_with_kind(owner, session, ActiveKind::ConnectionClosed)
+ }
+
+ pub(crate) fn start_reset_only_close(
+ &mut self,
+ owner: OwnerId,
+ session: SessionId,
+ ) -> Result<[HandleId; 2], StateError> {
+ self.start_close_with_kind(owner, session, ActiveKind::ResetOnly)
+ }
+
+ fn start_close_with_kind(
+ &mut self,
+ owner: OwnerId,
+ session: SessionId,
+ required_kind: ActiveKind,
+ ) -> Result<[HandleId; 2], StateError> {
+ let (paths, handles) = match &self.phase {
+ Phase::Active {
+ owner: current_owner,
+ session: current_session,
+ paths,
+ handles,
+ kind,
+ operation_active: false,
+ } if *current_owner == owner
+ && *current_session == session
+ && *kind == required_kind =>
+ {
+ (paths.clone(), *handles)
+ }
+ Phase::Active {
+ owner: current_owner,
+ session: current_session,
+ operation_active: true,
+ ..
+ } if *current_owner == owner && *current_session == session => {
+ return Err(StateError::new(
+ StateErrorKind::ActiveReferences,
+ "cannot close while an OPFS operation is active",
+ ));
+ }
+ Phase::Active {
+ owner: current_owner,
+ session: current_session,
+ ..
+ } if *current_owner == owner && *current_session == session => {
+ return Err(StateError::new(
+ StateErrorKind::ActiveReferences,
+ "close requires the matching connection-close or reset-only proof",
+ ));
+ }
+ Phase::Poisoned { .. } => return Err(poisoned()),
+ _ => {
+ return Err(StateError::new(
+ StateErrorKind::Session,
+ "close used a stale or mismatched session",
+ ));
+ }
+ };
+ self.phase = Phase::Closing {
+ owner,
+ session,
+ paths: paths.clone(),
+ };
+ Ok(handles)
+ }
+
+ pub(crate) fn finish_close(
+ &mut self,
+ owner: OwnerId,
+ session: SessionId,
+ ) -> Result<CloseToken, StateError> {
+ let paths = match &self.phase {
+ Phase::Closing {
+ owner: current_owner,
+ session: current_session,
+ paths,
+ } if *current_owner == owner && *current_session == session => paths.clone(),
+ Phase::Poisoned { .. } => return Err(poisoned()),
+ _ => {
+ return Err(StateError::new(
+ StateErrorKind::Session,
+ "close completion did not match the closing session",
+ ));
+ }
+ };
+ self.next_close_token = next_id(self.next_close_token, "close token space exhausted")?;
+ let token = CloseToken(self.next_close_token);
+ self.phase = Phase::Closed {
+ owner,
+ token,
+ paths,
+ };
+ Ok(token)
+ }
+
+ pub(crate) fn preserve(&mut self, owner: OwnerId, token: CloseToken) -> Result<(), StateError> {
+ match self.phase {
+ Phase::Closed {
+ owner: current_owner,
+ token: current_token,
+ ..
+ } if current_owner == owner && current_token == token => {
+ self.phase = Phase::Idle { owner };
+ Ok(())
+ }
+ Phase::Poisoned { .. } => Err(poisoned()),
+ _ => Err(StateError::new(
+ StateErrorKind::Token,
+ "preserve requires the matching one-use close token",
+ )),
+ }
+ }
+
+ pub(crate) fn start_reset(
+ &mut self,
+ owner: OwnerId,
+ token: CloseToken,
+ ) -> Result<Paths, StateError> {
+ let paths = match &self.phase {
+ Phase::Closed {
+ owner: current_owner,
+ token: current_token,
+ paths,
+ } if *current_owner == owner && *current_token == token => paths.clone(),
+ Phase::Poisoned { .. } => return Err(poisoned()),
+ _ => {
+ return Err(StateError::new(
+ StateErrorKind::Token,
+ "reset requires the matching one-use close token",
+ ));
+ }
+ };
+ self.phase = Phase::Resetting {
+ owner,
+ token,
+ paths: paths.clone(),
+ };
+ Ok(paths)
+ }
+
+ pub(crate) fn finish_reset(
+ &mut self,
+ owner: OwnerId,
+ token: CloseToken,
+ ) -> Result<(), StateError> {
+ match self.phase {
+ Phase::Resetting {
+ owner: current_owner,
+ token: current_token,
+ ..
+ } if current_owner == owner && current_token == token => {
+ self.phase = Phase::Idle { owner };
+ Ok(())
+ }
+ Phase::Poisoned { .. } => Err(poisoned()),
+ _ => Err(StateError::new(
+ StateErrorKind::Token,
+ "reset completion did not match the consumed close token",
+ )),
+ }
+ }
+
+ pub(crate) fn start_wipe(&mut self, owner: OwnerId, paths: Paths) -> Result<(), StateError> {
+ match self.phase {
+ Phase::Idle { owner: current } if current == owner => {
+ self.phase = Phase::Wiping { owner, paths };
+ Ok(())
+ }
+ Phase::Poisoned { .. } => Err(poisoned()),
+ _ => Err(StateError::new(
+ StateErrorKind::Ownership,
+ "recovery wipe requires the matching idle owner",
+ )),
+ }
+ }
+
+ pub(crate) fn finish_wipe(&mut self, owner: OwnerId) -> Result<(), StateError> {
+ match self.phase {
+ Phase::Wiping { owner: current, .. } if current == owner => {
+ self.phase = Phase::Idle { owner };
+ Ok(())
+ }
+ Phase::Poisoned { .. } => Err(poisoned()),
+ _ => Err(StateError::new(
+ StateErrorKind::Ownership,
+ "recovery wipe completion requires the matching wiping owner",
+ )),
+ }
+ }
+
+ pub(crate) fn poison(&mut self, owner: OwnerId, reason: String) -> Result<(), StateError> {
+ if matches!(self.phase, Phase::Poisoned { owner: current, .. } if current == owner) {
+ return Ok(());
+ }
+ let current_owner = match self.phase {
+ Phase::Unowned => None,
+ Phase::Idle { owner }
+ | Phase::Opening { owner, .. }
+ | Phase::Active { owner, .. }
+ | Phase::Closing { owner, .. }
+ | Phase::Closed { owner, .. }
+ | Phase::Resetting { owner, .. }
+ | Phase::Wiping { owner, .. }
+ | Phase::Poisoned { owner, .. } => Some(owner),
+ };
+ if current_owner != Some(owner) {
+ return Err(StateError::new(
+ StateErrorKind::Ownership,
+ "stale owner cannot poison the current OPFS lifecycle",
+ ));
+ }
+ self.phase = Phase::Poisoned { owner, reason };
+ Ok(())
+ }
+
+ pub(crate) fn is_idle_owner(&self, owner: OwnerId) -> bool {
+ matches!(self.phase, Phase::Idle { owner: current } if current == owner)
+ }
+
+ #[cfg(test)]
+ pub(crate) fn phase_label(&self) -> &'static str {
+ match self.phase {
+ Phase::Unowned => "unowned",
+ Phase::Idle { .. } => "idle",
+ Phase::Opening { .. } => "opening",
+ Phase::Active { .. } => "active",
+ Phase::Closing { .. } => "closing",
+ Phase::Closed { .. } => "closed",
+ Phase::Resetting { .. } => "resetting",
+ Phase::Wiping { .. } => "wiping",
+ Phase::Poisoned { .. } => "poisoned",
+ }
+ }
+
+ #[cfg(all(test, target_arch = "wasm32"))]
+ pub(crate) fn is_poisoned(&self) -> bool {
+ matches!(self.phase, Phase::Poisoned { .. })
+ }
+
+ #[cfg(test)]
+ pub(crate) fn poison_reason(&self) -> Option<&str> {
+ match &self.phase {
+ Phase::Poisoned { reason, .. } => Some(reason),
+ _ => None,
+ }
+ }
+}
+
+fn next_id(value: u64, message: &'static str) -> Result<u64, StateError> {
+ value
+ .checked_add(1)
+ .ok_or_else(|| StateError::new(StateErrorKind::Exhausted, message))
+}
+
+fn poisoned() -> StateError {
+ StateError::new(
+ StateErrorKind::Poisoned,
+ "worker-local OPFS session is poisoned",
+ )
+}
diff --git a/crates/client/turso-opfs/src/state/test.rs b/crates/client/turso-opfs/src/state/test.rs
new file mode 100644
index 0000000000..2a8a8bd001
--- /dev/null
+++ b/crates/client/turso-opfs/src/state/test.rs
@@ -0,0 +1,323 @@
+use super::*;
+
+fn paths() -> Paths {
+ Paths::new("cache.db".into(), "cache.db-wal".into())
+}
+
+fn active_machine() -> (Machine, OwnerId, SessionId, [HandleId; 2]) {
+ let mut machine = Machine::default();
+ let owner = machine.claim_owner().unwrap();
+ let session = machine.start_open(owner, paths()).unwrap();
+ let main = machine.register(owner, session, FileRole::Main).unwrap();
+ let wal = machine.register(owner, session, FileRole::Wal).unwrap();
+ machine.activate(owner, session, false).unwrap();
+ (machine, owner, session, [main, wal])
+}
+
+fn closed_machine() -> (Machine, OwnerId, CloseToken) {
+ let (mut machine, owner, session, _) = active_machine();
+ machine.bind_connection(owner, session).unwrap();
+ machine.record_connection_close(owner, session).unwrap();
+ machine.start_close(owner, session).unwrap();
+ let token = machine.finish_close(owner, session).unwrap();
+ (machine, owner, token)
+}
+
+#[test]
+fn numeric_trait_tokens_are_send_sync_and_pointer_free() {
+ fn assert_send_sync<T: Send + Sync>() {}
+ assert_send_sync::<OwnerId>();
+ assert_send_sync::<SessionId>();
+ assert_send_sync::<HandleId>();
+ assert_send_sync::<CloseToken>();
+ assert_eq!(std::mem::size_of::<OwnerId>(), std::mem::size_of::<u64>());
+ assert_eq!(std::mem::size_of::<SessionId>(), std::mem::size_of::<u64>());
+ assert_eq!(std::mem::size_of::<HandleId>(), std::mem::size_of::<u64>());
+ assert_eq!(
+ std::mem::size_of::<CloseToken>(),
+ std::mem::size_of::<u64>()
+ );
+}
+
+#[test]
+fn one_owner_and_matching_idle_release_are_required() {
+ let mut machine = Machine::default();
+ let owner = machine.claim_owner().unwrap();
+ assert_eq!(owner.get(), 1);
+ assert!(machine.is_idle_owner(owner));
+ assert_eq!(
+ machine.claim_owner().unwrap_err().kind,
+ StateErrorKind::Ownership
+ );
+ assert_eq!(
+ machine
+ .release_owner(OwnerId(owner.get() + 1))
+ .unwrap_err()
+ .kind,
+ StateErrorKind::Ownership
+ );
+ assert_eq!(machine.phase_label(), "idle");
+ machine.release_owner(owner).unwrap();
+ assert_eq!(machine.phase_label(), "unowned");
+ assert_eq!(machine.claim_owner().unwrap().get(), 2);
+}
+
+#[test]
+fn opening_requires_exactly_main_and_wal_once() {
+ let mut machine = Machine::default();
+ let owner = machine.claim_owner().unwrap();
+ let session = machine.start_open(owner, paths()).unwrap();
+ let main = machine.register(owner, session, FileRole::Main).unwrap();
+ assert_eq!(main.get(), 1);
+ assert_eq!(
+ machine
+ .register(owner, session, FileRole::Main)
+ .unwrap_err()
+ .kind,
+ StateErrorKind::Registration
+ );
+ assert_eq!(
+ machine.activate(owner, session, false).unwrap_err().kind,
+ StateErrorKind::Registration
+ );
+ let wal = machine.register(owner, session, FileRole::Wal).unwrap();
+ assert_eq!(wal.get(), 2);
+ machine.activate(owner, session, false).unwrap();
+ assert_eq!(machine.phase_label(), "active");
+}
+
+#[test]
+fn partial_open_cleanup_returns_idle_only_when_certain() {
+ let mut clean = Machine::default();
+ let owner = clean.claim_owner().unwrap();
+ let session = clean.start_open(owner, paths()).unwrap();
+ clean.register(owner, session, FileRole::Main).unwrap();
+ clean
+ .abort_open(owner, session, true, "WAL open failed".into())
+ .unwrap();
+ assert_eq!(clean.phase_label(), "idle");
+ assert!(clean.start_open(owner, paths()).is_ok());
+
+ let mut uncertain = Machine::default();
+ let owner = uncertain.claim_owner().unwrap();
+ let session = uncertain.start_open(owner, paths()).unwrap();
+ uncertain.register(owner, session, FileRole::Main).unwrap();
+ uncertain
+ .abort_open(
+ owner,
+ session,
+ false,
+ "WAL open and main close failed".into(),
+ )
+ .unwrap();
+ assert_eq!(uncertain.phase_label(), "poisoned");
+ assert_eq!(
+ uncertain.start_open(owner, paths()).unwrap_err().kind,
+ StateErrorKind::Poisoned
+ );
+ assert_eq!(
+ uncertain.release_owner(owner).unwrap_err().kind,
+ StateErrorKind::Poisoned
+ );
+}
+
+#[test]
+fn approved_main_and_wal_flags_are_enforced() {
+ let (machine, owner, session, handles) = active_machine();
+ machine.validate_session(owner, session).unwrap();
+ machine
+ .validate_path(owner, session, "cache.db-wal")
+ .unwrap();
+ assert_eq!(
+ machine
+ .validate_open(owner, session, "cache.db", false, false, true)
+ .unwrap(),
+ handles[0]
+ );
+ assert_eq!(
+ machine
+ .validate_open(owner, session, "cache.db-wal", false, false, false)
+ .unwrap(),
+ handles[1]
+ );
+ assert_eq!(
+ machine
+ .validate_open(owner, session, "cache.db-wal", false, true, false)
+ .unwrap(),
+ handles[1]
+ );
+ for error in [
+ machine.validate_open(owner, session, "other.db", false, false, true),
+ machine.validate_open(owner, session, "cache.db", true, false, true),
+ machine.validate_open(owner, session, "cache.db", false, true, true),
+ machine.validate_open(owner, session, "cache.db", false, false, false),
+ machine.validate_open(owner, session, "cache.db-wal", false, false, true),
+ ] {
+ assert!(error.is_err());
+ }
+}
+
+#[test]
+fn stale_sessions_and_reentrant_operations_do_not_mutate_health() {
+ let (mut machine, owner, session, _) = active_machine();
+ assert_eq!(
+ machine
+ .poison(OwnerId(owner.get() + 1), "stale cleanup".into())
+ .unwrap_err()
+ .kind,
+ StateErrorKind::Ownership
+ );
+ assert_eq!(machine.phase_label(), "active");
+ assert_eq!(
+ machine
+ .begin_operation(owner, SessionId(session.get() + 1))
+ .unwrap_err()
+ .kind,
+ StateErrorKind::Session
+ );
+ assert_eq!(machine.phase_label(), "active");
+ machine.begin_operation(owner, session).unwrap();
+ assert_eq!(
+ machine.begin_operation(owner, session).unwrap_err().kind,
+ StateErrorKind::Reentrant
+ );
+ assert_eq!(
+ machine.start_close(owner, session).unwrap_err().kind,
+ StateErrorKind::ActiveReferences
+ );
+ machine.end_operation(owner, session);
+ assert_eq!(
+ machine.start_close(owner, session).unwrap_err().kind,
+ StateErrorKind::ActiveReferences
+ );
+ machine.bind_connection(owner, session).unwrap();
+ assert_eq!(
+ machine.start_close(owner, session).unwrap_err().kind,
+ StateErrorKind::ActiveReferences
+ );
+ machine.record_connection_close(owner, session).unwrap();
+ machine.start_close(owner, session).unwrap();
+ assert_eq!(machine.phase_label(), "closing");
+}
+
+#[test]
+fn invalid_close_tokens_never_mutate_closed_state() {
+ let (mut machine, owner, token) = closed_machine();
+ assert_eq!(token.get(), 1);
+ assert_eq!(
+ machine
+ .preserve(OwnerId(owner.get() + 1), token)
+ .unwrap_err()
+ .kind,
+ StateErrorKind::Token
+ );
+ assert_eq!(machine.phase_label(), "closed");
+ assert_eq!(
+ machine
+ .start_reset(owner, CloseToken::from_raw(token.get() + 1))
+ .unwrap_err()
+ .kind,
+ StateErrorKind::Token
+ );
+ assert_eq!(machine.phase_label(), "closed");
+ machine.preserve(owner, token).unwrap();
+ assert_eq!(machine.phase_label(), "idle");
+ assert_eq!(
+ machine.preserve(owner, token).unwrap_err().kind,
+ StateErrorKind::Token
+ );
+ assert_eq!(machine.phase_label(), "idle");
+}
+
+#[test]
+fn reset_consumes_token_and_returns_matching_owner_to_idle() {
+ let (mut machine, owner, token) = closed_machine();
+ let selected = machine.start_reset(owner, token).unwrap();
+ assert_eq!(selected, paths());
+ assert_eq!(machine.phase_label(), "resetting");
+ assert_eq!(
+ machine.start_reset(owner, token).unwrap_err().kind,
+ StateErrorKind::Token
+ );
+ assert_eq!(machine.phase_label(), "resetting");
+ machine.finish_reset(owner, token).unwrap();
+ assert_eq!(machine.phase_label(), "idle");
+ assert_eq!(
+ machine.start_reset(owner, token).unwrap_err().kind,
+ StateErrorKind::Token
+ );
+ assert_eq!(machine.phase_label(), "idle");
+}
+
+#[test]
+fn reset_failure_poison_rejects_reopen_release_and_token_reuse() {
+ let (mut machine, owner, token) = closed_machine();
+ machine.start_reset(owner, token).unwrap();
+ machine.poison(owner, "partial deletion".into()).unwrap();
+ machine.poison(owner, "later failure".into()).unwrap();
+ assert_eq!(machine.phase_label(), "poisoned");
+ assert_eq!(machine.poison_reason(), Some("partial deletion"));
+ assert_eq!(
+ machine.finish_reset(owner, token).unwrap_err().kind,
+ StateErrorKind::Poisoned
+ );
+ assert_eq!(
+ machine.start_reset(owner, token).unwrap_err().kind,
+ StateErrorKind::Poisoned
+ );
+ assert_eq!(
+ machine.start_open(owner, paths()).unwrap_err().kind,
+ StateErrorKind::Poisoned
+ );
+ assert_eq!(
+ machine.release_owner(owner).unwrap_err().kind,
+ StateErrorKind::Poisoned
+ );
+}
+
+#[test]
+fn incomplete_pair_is_reset_only_and_never_operational() {
+ let mut machine = Machine::default();
+ let owner = machine.claim_owner().unwrap();
+ let session = machine.start_open(owner, paths()).unwrap();
+ machine.register(owner, session, FileRole::Main).unwrap();
+ machine.register(owner, session, FileRole::Wal).unwrap();
+ machine.activate(owner, session, true).unwrap();
+ assert_eq!(
+ machine.begin_operation(owner, session).unwrap_err().kind,
+ StateErrorKind::Session
+ );
+ assert_eq!(
+ machine.bind_connection(owner, session).unwrap_err().kind,
+ StateErrorKind::Session
+ );
+ assert_eq!(
+ machine.start_close(owner, session).unwrap_err().kind,
+ StateErrorKind::ActiveReferences
+ );
+ machine.start_reset_only_close(owner, session).unwrap();
+ let token = machine.finish_close(owner, session).unwrap();
+ machine.start_reset(owner, token).unwrap();
+ machine.finish_reset(owner, token).unwrap();
+ assert_eq!(machine.phase_label(), "idle");
+}
+
+#[test]
+fn recovery_wipe_is_consuming_and_poisoned_cancellation_cannot_finish() {
+ let mut machine = Machine::default();
+ let owner = machine.claim_owner().unwrap();
+ machine.start_wipe(owner, paths()).unwrap();
+ assert_eq!(machine.phase_label(), "wiping");
+ assert_eq!(
+ machine.start_open(owner, paths()).unwrap_err().kind,
+ StateErrorKind::Ownership
+ );
+ machine
+ .poison(owner, "recovery future cancelled".into())
+ .unwrap();
+ assert_eq!(machine.phase_label(), "poisoned");
+ assert_eq!(
+ machine.finish_wipe(owner).unwrap_err().kind,
+ StateErrorKind::Poisoned
+ );
+}
diff --git a/deny.toml b/deny.toml
index 2713b1325e..a802868bd6 100644
--- a/deny.toml
+++ b/deny.toml
@@ -216,6 +216,7 @@ deny = [
"tracing-panic", # External crate allowed to use tracing-subscriber
"tracing-tree",
"tracing-web", # External WASM tracing layer
+ "turso_core", # External Turso crate requires tracing-subscriber directly
"worker-rs-otel", # Cloudflare/WASM OpenTelemetry integration
"workspace-hack", # cargo-hakari generated crate
], reason = "Use macro_entrypoint for tracing setup in workspace crates" },
diff --git a/infra/stacks/web-app/index.ts b/infra/stacks/web-app/index.ts
index 5b32884f64..ee97c59d47 100644
--- a/infra/stacks/web-app/index.ts
+++ b/infra/stacks/web-app/index.ts
@@ -63,9 +63,32 @@ const publicAccessBlock = new aws.s3.BucketPublicAccessBlock(
}
);
-const appArchive = new pulumi.asset.FileArchive(localPath);
+// Stage web delivery and a native/OTA archive separately. Web delivery keeps
+// the Brotli sidecar for targeted S3 upload; native clients need the raw WASM
+// only, so their archive copy removes the sidecar before FileArchive snapshots it.
+const buildOutputPath = './output/app';
+const appArchiveOutputPath = './output/app-archive';
+const cacheWasmRetentionDays = 7;
+const shellQuote = (value: string): string =>
+ "'" + value.replaceAll("'", "'\\''") + "'";
+execSync('rm -rf ./output', { stdio: 'inherit' });
+execSync(
+ `mkdir -p ${shellQuote(buildOutputPath)} ${shellQuote(appArchiveOutputPath)}`,
+ { stdio: 'inherit' }
+);
+execSync(`cp -r ${shellQuote(localPath)}/* ${shellQuote(buildOutputPath)}`, {
+ stdio: 'inherit',
+});
+execSync(
+ `cp -r ${shellQuote(localPath)}/* ${shellQuote(appArchiveOutputPath)}`,
+ { stdio: 'inherit' }
+);
+execSync(
+ `find ${shellQuote(appArchiveOutputPath)} -type f -name 'cache_wasm_bg*.wasm.br' -delete`,
+ { stdio: 'inherit' }
+);
-// Upload the app archive to the S3 bucket
+const appArchive = new pulumi.asset.FileArchive(appArchiveOutputPath);
new aws.s3.BucketObjectv2(
'app-archive',
{
@@ -78,25 +101,21 @@ new aws.s3.BucketObjectv2(
dependsOn: [ownershipControls, publicAccessBlock],
}
);
-
-// Create web-app output folder
-// Remove the existing app folder
-let buildOutputPath = './output/app';
-execSync(`rm -rf ./output`, { stdio: 'inherit' });
-// Create the app folder
-execSync(`mkdir -p ${buildOutputPath}`, { stdio: 'inherit' });
-// Move the files to the app folder
-execSync(`cp -r ${localPath}/* ${buildOutputPath}`, { stdio: 'inherit' });
// Copy the index.html to the routing lambda
-execSync(`cp ${buildOutputPath}/index.html ./appRouteLambda/index.html`, {
- stdio: 'inherit',
-});
+execSync(
+ `cp ${shellQuote(`${buildOutputPath}/index.html`)} ./appRouteLambda/index.html`,
+ { stdio: 'inherit' }
+);
const syncAssetsCommand = new command.local.Command(
'sync-assets-command',
{
// Source maps are intentionally public in production; the web client is open source.
- create: pulumi.interpolate`aws s3 sync ./output s3://${webAppAssets.bucket} --acl public-read --delete --exclude "app/app-archive.zip"`,
+ // Cache WASM is over CloudFront's automatic-compression size limit. Keep
+ // raw bytes in dist/archive for Tauri and local preview, but exclude both
+ // raw and sidecar from generic sync. The targeted uploader stores Brotli
+ // bytes at the original .wasm key with application/wasm + Content-Encoding br.
+ create: pulumi.interpolate`bash ../../../apps/web/scripts/cache-wasm/upload-brotli-to-s3.sh ./output/app s3://${webAppAssets.bucket}/app public-read && aws s3 sync ./output s3://${webAppAssets.bucket} --acl public-read --delete --exclude "app/app-archive.zip" --exclude "app-archive/*" --exclude "*cache_wasm_bg*.wasm" --exclude "*cache_wasm_bg*.wasm.br"`,
triggers: [Date.now()],
},
{
@@ -115,7 +134,7 @@ const updateIndexHtmlObjectMetadataCommand = webAppAssets.id.apply(
);
// Run the command to update the index.html object metadata
-new command.local.Command(
+const indexHtmlObjectMetadataCommand = new command.local.Command(
'index-html-object-metadata-command',
{
create: updateIndexHtmlObjectMetadataCommand,
@@ -123,6 +142,20 @@ new command.local.Command(
{ dependsOn: [webAppAssets, syncAssetsCommand], replaceOnChanges: ['*'] }
);
+// Prune only after the current WASM, generic assets, index content, and index
+// metadata have all published. Any earlier failure preserves all prior keys.
+new command.local.Command(
+ 'prune-old-cache-wasm-command',
+ {
+ create: pulumi.interpolate`bash ../../../apps/web/scripts/cache-wasm/prune-old-brotli-from-s3.sh ./output/app s3://${webAppAssets.bucket}/app ${cacheWasmRetentionDays}`,
+ triggers: [Date.now()],
+ },
+ {
+ dependsOn: [indexHtmlObjectMetadataCommand],
+ replaceOnChanges: ['*'],
+ }
+);
+
// First, create an IAM role and attach the AWSLambdaBasicExecutionRole policy
const lambdaRole = new aws.iam.Role('content-encoding-header-lambda-role', {
assumeRolePolicy: aws.iam.assumeRolePolicyForPrincipal({
diff --git a/nix/cloud-storage.nix b/nix/cloud-storage.nix
index 34cc488d4e..8abae62c8e 100644
--- a/nix/cloud-storage.nix
+++ b/nix/cloud-storage.nix
@@ -709,6 +709,7 @@
just-lsp
taplo
bun
+ brotli
pnpm
sqlx-cli
typescript-language-server
diff --git a/packages/observability/src/privacy.ts b/packages/observability/src/privacy.ts
new file mode 100644
index 0000000000..384e7b8a2f
--- /dev/null
+++ b/packages/observability/src/privacy.ts
@@ -0,0 +1,15 @@
+import { type Context, createContextKey } from "@opentelemetry/api";
+
+const SUPPRESS_USER_ID_KEY = createContextKey(
+ "@macro-inc/observability/suppress-user-id",
+);
+
+/** Marks telemetry whose contract forbids user identity enrichment. */
+export function suppressUserId(context: Context): Context {
+ return context.setValue(SUPPRESS_USER_ID_KEY, true);
+}
+
+/** Returns whether a span/log context forbids user identity enrichment. */
+export function userIdSuppressed(context: Context): boolean {
+ return context.getValue(SUPPRESS_USER_ID_KEY) === true;
+}
diff --git a/packages/observability/src/telemetry.test.ts b/packages/observability/src/telemetry.test.ts
index 65820b54f3..1015583530 100644
--- a/packages/observability/src/telemetry.test.ts
+++ b/packages/observability/src/telemetry.test.ts
@@ -13,6 +13,7 @@ import {
} from "@opentelemetry/sdk-trace-base";
import { beforeEach, describe, expect, test } from "vitest";
import { Telemetry } from "./index";
+import { userIdSuppressed } from "./privacy";
import { ZoneContextManager } from "./zone";
context.setGlobalContextManager(new ZoneContextManager().enable());
@@ -20,7 +21,19 @@ context.setGlobalContextManager(new ZoneContextManager().enable());
const spanExporter = new InMemorySpanExporter();
trace.setGlobalTracerProvider(
new BasicTracerProvider({
- spanProcessors: [new SimpleSpanProcessor(spanExporter)],
+ spanProcessors: [
+ {
+ onStart: (span, parentContext) => {
+ if (!userIdSuppressed(parentContext)) {
+ span.setAttribute("usr.id", "test-user");
+ }
+ },
+ onEnd: () => {},
+ forceFlush: () => Promise.resolve(),
+ shutdown: () => Promise.resolve(),
+ },
+ new SimpleSpanProcessor(spanExporter),
+ ],
}),
);
@@ -78,6 +91,25 @@ describe("Telemetry", () => {
});
});
+ test("anonymous span trees are detached roots and suppress identity", () => {
+ const regular = Telemetry.span("regular");
+ const anonymous = regular.run(() =>
+ Telemetry.anonymousSpan("cache.request"),
+ );
+ const child = anonymous.span("cache.storage");
+ child.end();
+ anonymous.end();
+ regular.end();
+
+ const spans = new Map(
+ spanExporter.getFinishedSpans().map((span) => [span.name, span]),
+ );
+ expect(spans.get("regular")?.attributes["usr.id"]).toBe("test-user");
+ expect(spans.get("cache.request")?.attributes).not.toHaveProperty("usr.id");
+ expect(spans.get("cache.request")?.parentSpanContext).toBeUndefined();
+ expect(spans.get("cache.storage")?.attributes).not.toHaveProperty("usr.id");
+ });
+
test("ends a callback span after the async operation", async () => {
let complete: () => void = () => {};
const operation = Telemetry.span("doc.save", async (span) => {
diff --git a/packages/observability/src/telemetry.ts b/packages/observability/src/telemetry.ts
index c872a5472d..a37bfba41d 100644
--- a/packages/observability/src/telemetry.ts
+++ b/packages/observability/src/telemetry.ts
@@ -33,16 +33,27 @@ export class Telemetry {
name: string,
operation?: SpanOperation<T>,
): Span | Promise<T> {
- const span = Telemetry.#tracing.span(name);
- if (!operation) return span;
+ return Telemetry.#runSpan(Telemetry.#tracing.span(name), operation);
+ }
- return span.run(async () => {
- try {
- return await operation(span);
- } finally {
- span.end();
- }
- });
+ /**
+ * Start telemetry whose complete span tree is forbidden from receiving the
+ * runtime user-id enrichment. Use this for privacy-aggregated subsystem
+ * metrics whose schema does not permit identity.
+ */
+ static anonymousSpan<T>(
+ name: string,
+ operation: SpanOperation<T>,
+ ): Promise<T>;
+ static anonymousSpan(name: string): Span;
+ static anonymousSpan<T>(
+ name: string,
+ operation?: SpanOperation<T>,
+ ): Span | Promise<T> {
+ return Telemetry.#runSpan(
+ Telemetry.#tracing.anonymousSpan(name),
+ operation,
+ );
}
/** Start an HTTP client span. Callers must end the returned span. */
@@ -77,6 +88,21 @@ export class Telemetry {
]);
}
+ static #runSpan<T>(
+ span: Span,
+ operation?: SpanOperation<T>,
+ ): Span | Promise<T> {
+ if (!operation) return span;
+
+ return span.run(async () => {
+ try {
+ return await operation(span);
+ } finally {
+ span.end();
+ }
+ });
+ }
+
static async #initialize(config: TelemetryInitConfig): Promise<void> {
try {
if (!(await config.enabled())) return;
diff --git a/packages/observability/src/tracing.ts b/packages/observability/src/tracing.ts
index 37ad20ffb4..47b3108658 100644
--- a/packages/observability/src/tracing.ts
+++ b/packages/observability/src/tracing.ts
@@ -1,7 +1,14 @@
-import { type Context, context, SpanKind, trace } from "@opentelemetry/api";
+import {
+ type Context,
+ context,
+ ROOT_CONTEXT,
+ SpanKind,
+ trace,
+} from "@opentelemetry/api";
import type { Resource } from "@opentelemetry/resources";
import type { TelemetryInitConfig } from "./config";
import { INSTRUMENTATION_SCOPE_NAME } from "./constants";
+import { suppressUserId } from "./privacy";
import type { TelemetryTracingProvider } from "./provider";
import { type Span, SpanImpl } from "./span";
@@ -20,6 +27,11 @@ export class Tracing {
return this.#startSpan(name, context.active());
}
+ /** Starts a detached root span tree with user enrichment suppressed. */
+ anonymousSpan(name: string): Span {
+ return this.#startSpan(name, suppressUserId(ROOT_CONTEXT));
+ }
+
clientSpan(name: string): Span {
return this.#startSpan(name, context.active(), SpanKind.CLIENT);
}
diff --git a/packages/observability/src/web.ts b/packages/observability/src/web.ts
index 3bff964281..e85a8a79cf 100644
--- a/packages/observability/src/web.ts
+++ b/packages/observability/src/web.ts
@@ -5,6 +5,7 @@ import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
import { WebTracerProvider } from "@opentelemetry/sdk-trace-web";
import type { TelemetryInitConfig } from "./config";
import { ATTR_USER_ID } from "./constants";
+import { userIdSuppressed } from "./privacy";
import type { TelemetryTracingProvider } from "./provider";
/** Creates the browser OpenTelemetry provider used by the web application. */
@@ -17,7 +18,8 @@ export function createWebTracingProvider(
resource,
spanProcessors: [
{
- onStart: (span) => {
+ onStart: (span, parentContext) => {
+ if (userIdSuppressed(parentContext)) return;
const userId = getUserId();
if (userId !== undefined) span.setAttribute(ATTR_USER_ID, userId);
},
diff --git a/packages/observability/src/worker.ts b/packages/observability/src/worker.ts
index 8398603e5e..808dbb8da8 100644
--- a/packages/observability/src/worker.ts
+++ b/packages/observability/src/worker.ts
@@ -8,8 +8,9 @@ import {
OTLPExporter,
type TraceConfig,
} from "@microlabs/otel-cf-workers";
-import type { Span } from "@opentelemetry/api";
+import type { Context, Span } from "@opentelemetry/api";
import { ATTR_DEPLOYMENT_ENVIRONMENT, ATTR_USER_ID } from "./constants";
+import { userIdSuppressed } from "./privacy";
export type { TraceConfig };
export { instrument, instrumentDO };
@@ -46,8 +47,9 @@ export function createWorkerTraceConfig(
service: { name: options.serviceName },
spanProcessors: [
{
- onStart: (span: Span) => {
+ onStart: (span: Span, parentContext: Context) => {
span.setAttribute(ATTR_DEPLOYMENT_ENVIRONMENT, options.environment);
+ if (userIdSuppressed(parentContext)) return;
const userId = options.getUserId?.();
if (userId !== undefined) span.setAttribute(ATTR_USER_ID, userId);
},
diff --git a/tooling/xtask/crates/xtask_workflows/src/workflows/web_artifact_paths.rs b/tooling/xtask/crates/xtask_workflows/src/workflows/web_artifact_paths.rs
index c5a9607e84..a37329546d 100644
--- a/tooling/xtask/crates/xtask_workflows/src/workflows/web_artifact_paths.rs
+++ b/tooling/xtask/crates/xtask_workflows/src/workflows/web_artifact_paths.rs
@@ -11,8 +11,9 @@ pub const WEB_ARTIFACT_PATHS: &[RepoGlob<'static>] = &[
RepoGlob::new("apps/web/**"),
RepoGlob::new("packages/**"),
RepoGlob::new("crates/client/cache-core/**"),
- RepoGlob::new("crates/client/cache-idb/**"),
+ RepoGlob::new("crates/client/cache-turso/**"),
RepoGlob::new("crates/client/cache-wasm/**"),
+ RepoGlob::new("crates/client/turso-opfs/**"),
RepoGlob::new("static_assets/schema.graphql"),
RepoGlob::new("Cargo.toml"),
RepoGlob::new("Cargo.lock"),