offline-transactions: a mutation function that never settles stalls the outbox, and a reconnect cannot recover it
メンテナーはふだん 1 日以内に返信
まだ誰も着手していません。
評価
- 難易度
- 4/5
- 見積もり時間
- 3〜5日
- 初心者へのやさしさ
- 30/100
- issue の種類
- 機能追加
- 明瞭さ
- おおむね明確
- 活発さ
- 活発
- 技術スタック
- node.js, typescript
- 領域
- backend
調査の方向性
The executor's runMutationFn in the offline-transactions package awaits the mutation function with no bound, and the strict FIFO only arms the next retry once the head settles. Start by reading that method and the online handler that calls executeAll(), then run the attached repro.mjs in hang mode to see the stall. Done would be an opt-in per-attempt timeout (or an AbortSignal in OfflineMutationFnParams) that turns a hung attempt into a retriable failure, with a test covering reconnect recovery.
索引モデルが issue の本文から書いたものです。
説明
- I've validated the bug against the latest version of DB packages (
@tanstack/offline-transactions1.2.1 with@tanstack/db1.0.0-rc.1.5; also 1.1.4 with 0.15.2)
Describe the bug
TransactionExecutor.runMutationFn awaits the mutation function with no bound, and passes it no signal. The strict FIFO only arms its next retry timer once the head settles. So when one attempt never settles, nothing after it runs, for as long as the page lives:
- every queued transaction behind the head stays queued, and its
commit()stays pending; - a reconnect cannot help: the online handler calls
executeAll(), which returns the in-flightexecutionPromisewhileisExecutingis true; - the reconnect also arms
deferDataRefreshon every collection with that same promise, so collection refreshes stay deferred too.
A mutation function that never settles is ordinary in the browser. fetch has no default timeout, and a connection the network accepts and never answers (a captive portal, a proxy, a server that dies mid-request, a laptop resuming from sleep) leaves its promise pending. The app sees no error, so neither the retry policy nor onlineDetector gets a chance to act.
To Reproduce
Plain Node, no browser needed (script below):
- Start an executor with an in-memory
StorageAdapter, a leader that always wins, and anonlineDetectorthe script can trigger. Register one mutation function whose first call returnsnew Promise(() => {})and whose later calls resolve. - Commit transaction A, then transaction B.
- After 2.5 s: the mutation function has been called once (A). A and B are both pending, and
getPendingCount()is 2. - Call
onlineDetector.notifyOnline(). After another 2.5 s nothing has changed: still one call, both commits pending, and thedeferDataRefreshpromise it armed has not settled.
Output on 1.2.1:
[ 14ms] mutationFn called for A
[ 2567ms] after 2.5s: {"calls":["A"],"settle":{"A":"pending","B":"pending"},"pending":2}
[ 5070ms] 2.5s after notifyOnline(): {"calls":["A"],"settle":{"A":"pending","B":"pending"},"pending":2}
[ 5070ms] refresh barrier armed: true, settled: false
repro.mjs
// Repro: a mutation function that never settles stalls the offline outbox.
// Usage: node repro.mjs <env dir with node_modules> <mode>
// mode "hang" – the head's first attempt never settles
// mode "deadline" – same, wrapped in a 500 ms race that rejects retriably
// mode "abort" – same, but the race rejects with an AbortError DOMException
import { pathToFileURL } from "node:url";
import path from "node:path";
const [envDir, mode = "hang"] = process.argv.slice(2);
const load = (p) =>
import(pathToFileURL(path.join(envDir, "node_modules", p)).href);
const { createCollection } = await load("@tanstack/db/dist/esm/index.js");
const { startOfflineExecutor } = await load(
"@tanstack/offline-transactions/dist/esm/index.js",
);
const t0 = Date.now();
const log = (...a) => console.log(`[${String(Date.now() - t0).padStart(5)}ms]`, ...a);
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
class MemoryStorage {
store = new Map();
async get(k) { return this.store.get(k) ?? null; }
async set(k, v) { this.store.set(k, v); }
async delete(k) { this.store.delete(k); }
async keys() { return [...this.store.keys()]; }
async clear() { this.store.clear(); }
}
class Leader {
listeners = new Set();
async requestLeadership() { return true; }
releaseLeadership() {}
isLeader() { return true; }
onLeadershipChange(cb) { this.listeners.add(cb); return () => this.listeners.delete(cb); }
}
class Online {
listeners = new Set();
subscribe(cb) { this.listeners.add(cb); return () => this.listeners.delete(cb); }
notifyOnline() { for (const cb of this.listeners) cb(); }
isOnline() { return true; }
dispose() {}
}
const collection = createCollection({
id: "items",
getKey: (item) => item.id,
startSync: true,
sync: { sync: ({ markReady }) => { markReady(); } },
});
const calls = [];
let first = true;
const persist = async ({ transaction }) => {
const key = transaction.mutations[0].key;
calls.push(key);
log(`mutationFn called for ${key}`);
if (first) {
first = false;
return new Promise(() => {}); // a request the network accepted and never answered
}
};
const withDeadline = (fn, ms, makeError) => async (params) => {
let timer;
try {
return await Promise.race([
fn(params),
new Promise((_, reject) => {
timer = setTimeout(() => reject(makeError()), ms);
}),
]);
} finally {
clearTimeout(timer);
}
};
const mutationFn =
mode === "deadline"
? withDeadline(persist, 500, () => new Error("persist attempt timed out"))
: mode === "abort"
? withDeadline(persist, 500, () => new DOMException("timed out", "AbortError"))
: persist;
const online = new Online();
const executor = startOfflineExecutor({
collections: { items: collection },
mutationFns: { persist: mutationFn },
storage: new MemoryStorage(),
leaderElection: new Leader(),
onlineDetector: online,
jitter: false,
});
await executor.waitForInit();
log(`offline enabled: ${executor.isOfflineEnabled}`);
const settle = {};
const write = (id) => {
const tx = executor.createOfflineTransaction({ mutationFnName: "persist", autoCommit: false });
tx.mutate(() => collection.insert({ id }));
settle[id] = "pending";
tx.commit().then(
() => { settle[id] = "persisted"; log(`${id} persisted`); },
(e) => { settle[id] = `rejected: ${e?.name}: ${e?.message}`; log(`${id} rejected`, e?.name, e?.message); },
);
};
write("A");
await sleep(50);
write("B");
let refreshSettled = false;
const report = (label) =>
log(label, JSON.stringify({ calls, settle, pending: executor.getPendingCount(), rows: [...collection.keys()] }));
await sleep(2500);
report("after 2.5s:");
// A reconnect resets retry delays and drains; it also arms the refresh barrier.
online.notifyOnline();
const barrier = collection.deferDataRefresh;
if (barrier) barrier.then(() => { refreshSettled = true; }, () => { refreshSettled = true; });
await sleep(2500);
report("2.5s after notifyOnline():");
log(`refresh barrier armed: ${barrier != null}, settled: ${refreshSettled}`);
process.exit(0);
Expected behavior
An opt-in bound on one attempt, so an app can choose to recover without wrapping every mutation function itself. Either shape would do:
- A per-attempt timeout on
OfflineConfig(for examplemutationFnTimeoutMs), after which the executor treats the attempt as a retriable failure and moves on to its backoff. - An
AbortSignalinOfflineMutationFnParams, which the executor aborts on its own timeout (if one is configured) and ondispose(), so afetchcan be cancelled.
I don't think we need/want a default. #1625 explains why a long mutation function is intended when it waits for a sync echo, and an opt-in keeps that contract.
Screenshots
N/A
Desktop (please complete the following information):
Additional context
My workaround (see below) wraps each mutation function in a race against a timer, and hands the attempt an AbortSignal the request carries into fetch. On expiry it aborts the signal and rejects with a retriable error, and the executor's backoff then re-sends the write under its idempotency key. Upstream support would let me drop it.
const persistWithinDeadline = async (deadlineMs, persist) => {
const controller = new AbortController()
// Not an AbortError: DefaultRetryPolicy would treat that as permanent.
const expiry = new Error(`persist attempt did not settle within ${deadlineMs}ms`)
const expired = new Promise((_, reject) => {
controller.signal.addEventListener('abort', () => reject(expiry), { once: true })
})
const timer = setTimeout(() => controller.abort(expiry), deadlineMs)
try {
await Promise.race([persist(controller.signal), expired])
} finally {
clearTimeout(timer)
}
}
Related, not duplicates: #1602 (confirm writes off the serial drain), #1625 (mutation log RFC), #2184 (a preload waiting on a persisting transaction).
- 主要言語
- TypeScript
- スター
- 4k
- フォーク
- 286
- 平均マージ
- 1日 1時間
- マージ済み PR(30日)
- 104
環境構築
- Dockerfile・Docker Compose ファイルなし
- プルリクエストのテンプレートあり
- コントリビューションガイドを読む
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
TanStack/db のほかの issue
-
extractSimpleComparisons returns value: null when the right side of a comparison isn't a literalオープン
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100
メンテナーはふだん 1 日以内に返信
-
`avg`, `min`, `max` and `sum` treat `null` values as `0`対応中かも @oyobbeb が 8 日前に担当しました。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 76/100
メンテナーはふだん 1 日以内に返信
-
難易度 1/5 1〜3時間 初心者へのやさしさ 88/100
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
メンテナーはふだん 1 日以内に返信
-
Two @tanstack/db tests time out under CPU load because a cold module import counts against the 5 s default timeout対応中かも @jp-knj が 20 日前に担当しました。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100
メンテナーはふだん 1 日以内に返信
似ている issue
-
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100
vercel-labs/ui#809 ·
メンテナーはふだん 1 日以内に返信
-
bot:ai-assisted component:platform-js status:untriaged
難易度 1/5 1時間未満 初心者へのやさしさ 74/100
midnightntwrk/platform-js#38 ·
-
[bug] Second false positive on high-cost plugin alert: detection only compares patch entry id, community plugin dsh-auto | [bug] 高成本插件告警第二次误报:检测只比对 patch 条目 id,社区插件 dsh-auto-review 被认成 @deepseek-ai/dsh-experimental-auto-review対応中かも このイシューにリンクされたプルリクエストがオープン中、またはマージ済みです。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 68/100
ranxianglei/billion-context#7068 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
mybigday/whisper.rn#348 ·
-
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
six-group/six-webcomponents#600 ·