qiyu-cli 0.2.2 → 0.2.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +156 -84
- package/dist/commands/api-notes.js +16 -0
- package/dist/commands/api.js +60 -14
- package/dist/commands/auth.js +1 -1
- package/dist/commands/db.js +58 -19
- package/dist/commands/query.js +25 -8
- package/dist/commands/stats.js +22 -4
- package/dist/commands/store-precheck.js +72 -5
- package/dist/commands/store.js +46 -11
- package/dist/commands/sync-notes.js +13 -6
- package/dist/commands/sync-run.js +28 -6
- package/dist/commands/sync.js +56 -12
- package/dist/core/config.js +6 -0
- package/dist/core/edition.js +1 -1
- package/dist/core/http.js +24 -2
- package/dist/core/registry/index.js +10 -0
- package/dist/core/registry/specs.json +2 -2
- package/dist/output.js +11 -1
- package/dist/query/sandbox.js +19 -1
- package/dist/store/duckdb.js +1500 -59
- package/dist/store/object-kinds.js +32 -0
- package/dist/store/retry.js +98 -3
- package/dist/store/schema.js +6 -1
- package/dist/sync/engine.js +209 -39
- package/dist/sync/registry.js +3 -1
- package/dist/sync/tasks/pace.js +27 -0
- package/dist/sync/write-contract.js +32 -0
- package/package.json +2 -2
package/dist/store/duckdb.js
CHANGED
|
@@ -11,23 +11,80 @@
|
|
|
11
11
|
// D-T3 追加:src/sync/state.ts 常量 SELECT 3 处(水位/缺口读取),不在上述 9 处内。
|
|
12
12
|
// D-T11 追加:src/sync/tasks/knowledge.ts 常量 SELECT 1 处
|
|
13
13
|
//(knowledge.categories 的驱动序 SELECT DISTINCT robot_id),不在上述 9 处内。
|
|
14
|
+
import { AsyncLocalStorage } from 'node:async_hooks';
|
|
14
15
|
import { MIGRATIONS, tableByName } from './schema.js';
|
|
16
|
+
import { objectKinds, isBaseTable, sameObjectName } from './object-kinds.js';
|
|
15
17
|
import { retryWithBackoff, isLockError, isModuleNotFound } from './retry.js';
|
|
16
18
|
// `isModuleNotFound` 的定义已下沉到 retry.ts(架构审查 M-4):spec §5.1 白名单允许
|
|
17
19
|
// query/ import `store/retry` 但不允许 `store/duckdb`。这里保留 re-export,既有
|
|
18
20
|
// 导入点(tests/store/errors.test.ts)不破。
|
|
19
21
|
export { isModuleNotFound };
|
|
20
22
|
const defaultImporter = () => import('@duckdb/node-api');
|
|
23
|
+
/**
|
|
24
|
+
* `e instanceof Error` 的安全形态(CR 第五十六轮 major):**已撤销的 Proxy** 上 `instanceof`
|
|
25
|
+
* 会抛 TypeError(HasInstance 走 [[GetPrototypeOf]])—— 错误路径上的类型判据不得自己成为新的
|
|
26
|
+
* 主失败。撤销后的 Proxy 一律当「非 Error」,原值仍挂在 `cause`。
|
|
27
|
+
*/
|
|
28
|
+
function isErrorValue(e) {
|
|
29
|
+
try {
|
|
30
|
+
return e instanceof Error;
|
|
31
|
+
}
|
|
32
|
+
catch {
|
|
33
|
+
return false;
|
|
34
|
+
}
|
|
35
|
+
}
|
|
21
36
|
/** 依赖缺失 → store_not_initialized(按缺失 specifier 前缀二分 hint,spec §5.1)。 */
|
|
22
37
|
function depError(e) {
|
|
23
38
|
const mn = isModuleNotFound(e);
|
|
24
|
-
const err = new Error(`无法加载 DuckDB 依赖:${e
|
|
39
|
+
const err = new Error(`无法加载 DuckDB 依赖:${isErrorValue(e) ? e.message : safeValueText(e, 400)}`);
|
|
25
40
|
err.kind = 'store_not_initialized';
|
|
26
41
|
err.hint = mn && mn.missing.startsWith('@duckdb/node-bindings')
|
|
27
42
|
? '当前平台无 DuckDB 预编译包(无 node-gyp 回退)。请在受支持的平台上安装 @duckdb/node-api@1.5.6-r.1'
|
|
28
43
|
: '未安装 DuckDB 依赖。请在 qiyu-cli 的安装环境中运行:npm install @duckdb/node-api@1.5.6-r.1';
|
|
29
44
|
return err;
|
|
30
45
|
}
|
|
46
|
+
/** 把任意拒绝值转成**截断的**文本;转换本身抛(无原型对象等)时交回占位说明。
|
|
47
|
+
* 错误路径上的所有「值转文本」都走它 —— 补话/诊断不得自己成为新的主失败。 */
|
|
48
|
+
function safeValueText(v, max) {
|
|
49
|
+
try {
|
|
50
|
+
return String(v).slice(0, max);
|
|
51
|
+
}
|
|
52
|
+
catch {
|
|
53
|
+
return `(无法转成文本的拒绝值,typeof=${typeof v})`;
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* 安全读取拒绝值上的 `kind`(CR 第六十六轮 major 的反向判据):拒绝值可能是 `null` /
|
|
58
|
+
* 无原型对象 / 访问器抛异常的对象 —— 判据自己抛错就会把原始失败换掉。读不出来一律 undefined。
|
|
59
|
+
*/
|
|
60
|
+
function safeKindOf(v) {
|
|
61
|
+
if (v === null || (typeof v !== 'object' && typeof v !== 'function'))
|
|
62
|
+
return undefined;
|
|
63
|
+
try {
|
|
64
|
+
const k = v.kind;
|
|
65
|
+
return typeof k === 'string' ? k : undefined;
|
|
66
|
+
}
|
|
67
|
+
catch {
|
|
68
|
+
return undefined;
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* 拒绝值 → 截断文本,**先安全地取 message**:`message` 是抛异常的访问器时,`String(e)` 之前
|
|
73
|
+
* 的求值不能发生在 try 外面(CR 第五十五轮 major:求值一抛,状态标记就落不下去)。
|
|
74
|
+
*/
|
|
75
|
+
function safeMessageText(v, max) {
|
|
76
|
+
try {
|
|
77
|
+
return String(isErrorValue(v) ? v.message : v).slice(0, max);
|
|
78
|
+
}
|
|
79
|
+
catch {
|
|
80
|
+
return `(无法转成文本的拒绝值,typeof=${typeof v})`;
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* 派发前被**本地关闭判据**拒绝的 usage 错误(身份集合)。COMMIT 的归因据此区分「根本没下发」
|
|
85
|
+
* 与「驱动拒绝」—— 不读拒绝值的 `kind`(访问器可抛,驱动对象也可能伪造该字段,CR 第五十五轮 major)。
|
|
86
|
+
*/
|
|
87
|
+
const closedBeforeDispatch = new WeakSet();
|
|
31
88
|
/** usage 错误(退出码 2):带 kind 供命令层经 thrownToExit 归 usageFail 双通道。 */
|
|
32
89
|
function usage(msg) {
|
|
33
90
|
const e = new Error(msg);
|
|
@@ -49,13 +106,30 @@ export async function createDuckDbStore(cfg, mode, deps = {}) {
|
|
|
49
106
|
const inst = mode === 'ro'
|
|
50
107
|
? await mod.DuckDBInstance.create(cfg.path, { access_mode: 'READ_ONLY' })
|
|
51
108
|
: await mod.DuckDBInstance.create(cfg.path);
|
|
109
|
+
let conn;
|
|
52
110
|
try {
|
|
53
|
-
|
|
111
|
+
conn = await inst.connect();
|
|
112
|
+
// ⚠️ 会话级封锁外部访问(2026-11-14,历史审查 PR#4 复核):此前只有查询沙箱
|
|
113
|
+
// (`src/query/sandbox.ts` 的 `HARDENING_SQL`)设过 `enable_external_access=false`,
|
|
114
|
+
// store 连接什么都没设 —— 而实测 DuckDB 默认值是 **true**。于是 `store status/init`
|
|
115
|
+
// 打开一个来源不明的 `.duckdb` 时,库里声明的 `tags` 等 view 会作为 COUNT(*) 的
|
|
116
|
+
// 本体以用户权限执行(实测:含 `secret` 表的库里造 `tags` view,status 退出 0 并
|
|
117
|
+
// 计数成功)。只设值、**不** lock_configuration —— 那是查询沙箱的加固项;
|
|
118
|
+
// store 的写路径不需要改这个配置,锁住只会让将来正当的会话设置无从下手。
|
|
119
|
+
await conn
|
|
120
|
+
.runAndReadAll('SET enable_external_access=false');
|
|
54
121
|
return { conn, inst };
|
|
55
122
|
}
|
|
56
123
|
catch (e) {
|
|
57
124
|
// ⚠️ R 组 R9:create 成功但 connect 失败 → instance 泄漏(锁可能随进程滞留),
|
|
58
125
|
// ro 退避路径会累积 —— 失败路径自清理。
|
|
126
|
+
// ⚠️ **连接也要关**(Codex PR#74 第三轮 P2):加固 `SET` 是在 connect **成功之后**才跑的,
|
|
127
|
+
// 它失败时只关 instance 会漏掉已建立的连接 —— DuckDB 的锁要两者都关才释放,ro 退避路径
|
|
128
|
+
// 每失败一次就多一个未关连接,后续打开更容易撞锁。先关连接,再关实例。
|
|
129
|
+
try {
|
|
130
|
+
conn?.closeSync?.();
|
|
131
|
+
}
|
|
132
|
+
catch { /* 同上 */ }
|
|
59
133
|
try {
|
|
60
134
|
inst.closeSync?.();
|
|
61
135
|
}
|
|
@@ -71,13 +145,29 @@ export async function createDuckDbStore(cfg, mode, deps = {}) {
|
|
|
71
145
|
try {
|
|
72
146
|
const r = await retryWithBackoff({
|
|
73
147
|
tryOpen: open, isRetryable: isLockError, maxMs: cfg.readOnlyRetryMs,
|
|
148
|
+
// 单次尝试也必须有界(2026-11-14,历史审查 PR#4 复核):`DuckDBInstance.create` /
|
|
149
|
+
// `connect` 在网络盘或卡住的锁等待上可以永不返回,而截止时间原先只在**抛错后**才比 ——
|
|
150
|
+
// 只读命令会无限挂着。超时被放弃的尝试若后来成功,经 `onAbandoned` 关掉(否则多一个
|
|
151
|
+
// 锁持有者)。
|
|
152
|
+
attemptMs: cfg.readOnlyRetryMs,
|
|
153
|
+
onAbandoned: (r) => {
|
|
154
|
+
try {
|
|
155
|
+
r.conn.closeSync?.();
|
|
156
|
+
}
|
|
157
|
+
catch { /* 清理失败不掩盖原错误 */ }
|
|
158
|
+
try {
|
|
159
|
+
r.inst.closeSync?.();
|
|
160
|
+
}
|
|
161
|
+
catch { /* 同上 */ }
|
|
162
|
+
},
|
|
74
163
|
sleep: deps.sleep, now: deps.now,
|
|
75
164
|
});
|
|
76
165
|
conn = r.conn;
|
|
77
166
|
inst = r.inst;
|
|
78
167
|
}
|
|
79
168
|
catch (e) {
|
|
80
|
-
|
|
169
|
+
// 打开超时(`timedOut` 标记)与撞锁是同一类后果 —— 等不到库;归 store_locked。
|
|
170
|
+
if (isLockError(e) || e.timedOut === true) {
|
|
81
171
|
const err = new Error(`数据库被写进程占用(等待 ${cfg.readOnlyRetryMs}ms 后超时):${cfg.path}`);
|
|
82
172
|
err.kind = 'store_locked';
|
|
83
173
|
err.retryable = true;
|
|
@@ -112,9 +202,31 @@ export async function createDuckDbStore(cfg, mode, deps = {}) {
|
|
|
112
202
|
}
|
|
113
203
|
// ⚠️ 真实 API(第四轮实测):runAndReadAll(sql, params) 返回带 getRowObjectsJson()
|
|
114
204
|
// 与 columnNames() 的读取器;run() 返回的 Result 没有取行方法。
|
|
205
|
+
// `extractStatements` 在**原型**上(不在自有属性里):测试里包一层的导入缝若要让它可见,
|
|
206
|
+
// 必须显式转发(`...(conn as object)` 展开拿不到原型方法,见 `rejectMultiStatements` 的报错)。
|
|
115
207
|
const c = conn;
|
|
116
208
|
let closed = false;
|
|
117
209
|
let inTx = false;
|
|
210
|
+
/**
|
|
211
|
+
* 当前事务的**所有者令牌**(历史审查 PR#4 复核)。
|
|
212
|
+
*
|
|
213
|
+
* ⚠️ 事故事实:`inTx` 是**整个 Store 实例共享的布尔**,所以「事务外另一条异步链」调用
|
|
214
|
+
* `upsert`/`delete` 时会被当成「事务内」,直接被写进别人那条未提交的事务 —— 对方回滚,
|
|
215
|
+
* 这一行就**静默消失**,而 `upsert` 还返回了成功行数(实测:outside 分支 resolves,
|
|
216
|
+
* 回滚后 `count === 0`)。报错是可修的,"成功却丢数据"不可发现。
|
|
217
|
+
* 归属判据用 `AsyncLocalStorage`:只有从 `transaction()` 回调**内部**发起的写才算事务内。
|
|
218
|
+
* 单连接、`await` 串行的既有用法(store init/status、sync 引擎)行为完全不变。
|
|
219
|
+
*/
|
|
220
|
+
let txToken;
|
|
221
|
+
/**
|
|
222
|
+
* 事务「代号」:只用于**防御性**断言(CR 第二十八轮引入,第三十八轮后按设计不可达)。
|
|
223
|
+
* ⚠️ 当前设计的不变量(CR 第三十八轮收口):**BEGIN 只在连接上没有任何在途语句时发出**
|
|
224
|
+
* (`admitBegin` 检查 `foreignInFlight`),事务期间任何外部语句在下发前就被 `assertTxOwnership`
|
|
225
|
+
* 拒绝 —— 因此「外部语句在事务执行期落进来」在支持路径上不可能发生。代号检查保留为
|
|
226
|
+
* 内部不变量的兜底:若未来某条路径绕开了准入,它会以 `internal` 响亮失败而不是静默丢写。
|
|
227
|
+
*/
|
|
228
|
+
let txEpoch = 0;
|
|
229
|
+
const alsTx = deps.makeAls?.() ?? new AsyncLocalStorage();
|
|
118
230
|
// ⚠️ 所有语句执行收敛到这一个方法 —— 测试 spy 的落点(spec §5.3)。
|
|
119
231
|
// ⚠️ **挂载与调用契约(v3.1 定死,消除二选一)**:
|
|
120
232
|
// ① store 的方法体**双轨调用**:数据语句(SELECT/INSERT 等)必须经 `store.execSql(...)`
|
|
@@ -125,11 +237,815 @@ export async function createDuckDbStore(cfg, mode, deps = {}) {
|
|
|
125
237
|
// ② `Object.defineProperty` 必须 `writable: true, configurable: true` —— 默认
|
|
126
238
|
// configurable:false 会让 vi.spyOn 重定义属性时直接抛 TypeError;
|
|
127
239
|
// ③ 挂为**不可枚举**(不污染 JSON 输出与接口形状)。
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
240
|
+
/** 语句下发期间事务代号变化 → `internal`,`cause` 可带驱动原文(与 `assertTxOwnership` 同一分类)。 */
|
|
241
|
+
const epochChangedError = (cause) => {
|
|
242
|
+
const err = new Error('语句等待期间另一条异步链开启了事务 —— 本条语句可能落进那条事务,'
|
|
243
|
+
+ '它一旦执行期报错就会把对方的事务标成 aborted(对方随后 COMMIT / 写入会响亮失败、'
|
|
244
|
+
+ '事务内写入不落库;对方若因此拿到成功,请报告)', cause === undefined ? {} : { cause });
|
|
245
|
+
err.kind = 'internal';
|
|
246
|
+
err.hint = '让同一个 Store 实例上的操作串行执行:不要用 Promise.all 并行调用 upsert/delete/transaction/query/count';
|
|
247
|
+
return err;
|
|
248
|
+
};
|
|
249
|
+
/**
|
|
250
|
+
* 在**别的异步链**里下发、还没有交回结果的语句(数量)。
|
|
251
|
+
* ⚠️ 为什么需要它(CodeRabbit/Codex PR#81 第三十二、三十三轮 major,隔离内存 DuckDB 探针复现):
|
|
252
|
+
* 外部语句在事务内执行期报错后,DuckDB 把事务标成 aborted —— 此后 `COMMIT` 返回成功却丢弃
|
|
253
|
+
* 全部写入(2026-11-18 直连驱动实测:`bad-err → commit-ok → COUNT 0`)。外部语句的错误只
|
|
254
|
+
* reject 给发起它的那条链,所有者看不到;驱动在「执行完、结果交回」之间还有异步点,按
|
|
255
|
+
* 「错误已交回」打记号会漏掉「提交早于交回」的时序。
|
|
256
|
+
* 所以:任一**不是当前事务上下文**下发的语句仍在途时,所有者不提交、直接拿**拒绝**
|
|
257
|
+
* (而不是等「在途语句全清」,那会把普通并发读拖成死等)。
|
|
258
|
+
*/
|
|
259
|
+
let foreignInFlight = 0;
|
|
260
|
+
/**
|
|
261
|
+
* 进行中的**多语句写操作**:事务外的 `delete`(count → DELETE → count)与事务外的 `upsert`
|
|
262
|
+
* 自动事务。⚠️ 为什么 BEGIN 必须等它们(CR 第三十七轮 major):单连接上的语句会按**实际执行**
|
|
263
|
+
* 顺序进入当时开着的事务。写操作的两步之间若插进一条 BEGIN,DELETE 的实际执行可能早于 BEGIN
|
|
264
|
+
* (autocommit 已提交)而结果晚于 BEGIN 才交回 —— 调用方拿到「跨代」的失败,行却真的删了;
|
|
265
|
+
* 重试还会报「删了 0 行」。所以 BEGIN 前要求写操作全部落定(本操作自己除外)。
|
|
266
|
+
* 代价如实记录:写操作与事务并发发起会被拒(internal)—— Store 本契约就是同一实例串行 await。
|
|
267
|
+
*/
|
|
268
|
+
const writeOpsInFlight = new Set();
|
|
269
|
+
const enterWriteOp = () => {
|
|
270
|
+
const t = Symbol('write-op');
|
|
271
|
+
writeOpsInFlight.add(t);
|
|
272
|
+
return t;
|
|
273
|
+
};
|
|
274
|
+
const leaveWriteOp = (t) => { writeOpsInFlight.delete(t); };
|
|
275
|
+
const admitBegin = (self) => {
|
|
276
|
+
// ⚠️ **任何在途语句都会让 BEGIN 不安全**(CR 第三十八轮 major):驱动里已接收、尚未执行的
|
|
277
|
+
// 原始 SQL(`query`)无法静态判定是读还是写;它可能在 BEGIN 之后才执行(落进新事务)或在
|
|
278
|
+
// ROLLBACK / COMMIT 之后才执行(在 autocommit 里落库)。能确定的是:**只要它还没交回结果,
|
|
279
|
+
// 开启事务就不安全**。所以 BEGIN 要求连接上没有任何在途语句(本操作自身的语句除外,
|
|
280
|
+
// 自动事务登记写操作时它的语句还没有下发)。
|
|
281
|
+
if (foreignInFlight > 0) {
|
|
282
|
+
const err = new Error(`另一条异步链上的 ${foreignInFlight} 条语句还没有交回结果(可能仍在驱动里):`
|
|
283
|
+
+ '此时开启事务会与它交错 —— 它若在 BEGIN 之后执行会落进本事务,在回滚/提交之后执行则会在 '
|
|
284
|
+
+ 'autocommit 里落库,而调用方拿到的是失败');
|
|
285
|
+
err.kind = 'internal';
|
|
286
|
+
err.hint = '让同一个 Store 实例上的操作串行 await:不要用 Promise.all 并行调用 upsert/delete/transaction/query/count';
|
|
287
|
+
throw err;
|
|
288
|
+
}
|
|
289
|
+
for (const op of writeOpsInFlight) {
|
|
290
|
+
if (op === self)
|
|
291
|
+
continue;
|
|
292
|
+
const err = new Error('另一条异步链上的写操作还没有完成(它的语句可能仍在驱动里):'
|
|
293
|
+
+ '此时开启事务会与它交错 —— 它拿到的「删改了几行」将不可信');
|
|
294
|
+
err.kind = 'internal';
|
|
295
|
+
err.hint = '让同一个 Store 实例上的操作串行 await:不要用 Promise.all 并行调用 upsert/delete/transaction/query/count';
|
|
296
|
+
throw err;
|
|
297
|
+
}
|
|
298
|
+
};
|
|
299
|
+
/**
|
|
300
|
+
* 受影响的事务(令牌)与成因:外部语句**执行期报错**(跨代)或**交回时报错且期间跨代**。
|
|
301
|
+
* 与在途计数互补(CR 第三十四轮 major):计数在结果交回时归零,若错误交回早于所有者提交,
|
|
302
|
+
* 提交那一刻计数已为 0 —— 只靠计数会放行(用例「外部语句的错误先交回、所有者随后才提交」钉住)。
|
|
303
|
+
*/
|
|
304
|
+
const brokenTx = new Map();
|
|
305
|
+
/**
|
|
306
|
+
* **所有者自己**下发、还没交回结果的语句(按令牌计数)。外部语句有 `foreignInFlight`,
|
|
307
|
+
* 但所有者那条不计数(它归自己看得到)—— 若调用方**没有 await** 事务回调里的写就返回,
|
|
308
|
+
* 提交时这条语句仍在驱动里,可能落进随后开启的事务并被别人提交(CR 第三十六轮 major)。
|
|
309
|
+
*/
|
|
310
|
+
const txInFlight = new Map();
|
|
311
|
+
/**
|
|
312
|
+
* 本令牌下**还没完成**的写操作(多批次 upsert / 多语句 delete)。⚠️ 为什么不能只数语句
|
|
313
|
+
* (CR 第三十九轮 major #2):多批次写两条语句之间 `txInFlight` 会瞬间归零 —— 回调没 await 它
|
|
314
|
+
* 时,`commitOrRefuse` 可能恰好在「上一批已交回、下一批还没下发」的窗口里看到零并 COMMIT,
|
|
315
|
+
* 事务报成功、第二批随后被拒(只有部分行落库)。写操作在整个生命周期内登记。
|
|
316
|
+
*/
|
|
317
|
+
const txWrites = new Map();
|
|
318
|
+
const trackWrite = (token) => {
|
|
319
|
+
txWrites.set(token, (txWrites.get(token) ?? 0) + 1);
|
|
320
|
+
let done = false;
|
|
321
|
+
return () => {
|
|
322
|
+
if (done)
|
|
323
|
+
return;
|
|
324
|
+
done = true;
|
|
325
|
+
const rest = (txWrites.get(token) ?? 1) - 1;
|
|
326
|
+
if (rest <= 0)
|
|
327
|
+
txWrites.delete(token);
|
|
328
|
+
else
|
|
329
|
+
txWrites.set(token, rest);
|
|
330
|
+
};
|
|
331
|
+
};
|
|
332
|
+
/** 等在途的本事务语句落定(计数归零)时唤醒 `drainOwned`。 */
|
|
333
|
+
const drainWaiters = new Map();
|
|
334
|
+
/** 在途的外部语句登记:返回「这一次」的解除函数(只减一次)。 */
|
|
335
|
+
const trackForeign = () => {
|
|
336
|
+
foreignInFlight += 1;
|
|
337
|
+
let done = false;
|
|
338
|
+
return () => {
|
|
339
|
+
if (done)
|
|
340
|
+
return;
|
|
341
|
+
done = true;
|
|
342
|
+
foreignInFlight -= 1;
|
|
343
|
+
};
|
|
344
|
+
};
|
|
345
|
+
/** 事务内语句的在途登记(与 `trackForeign` 同款「只减一次」语义)。 */
|
|
346
|
+
const trackOwn = (token) => {
|
|
347
|
+
txInFlight.set(token, (txInFlight.get(token) ?? 0) + 1);
|
|
348
|
+
let done = false;
|
|
349
|
+
return () => {
|
|
350
|
+
if (done)
|
|
351
|
+
return;
|
|
352
|
+
done = true;
|
|
353
|
+
const rest = (txInFlight.get(token) ?? 1) - 1;
|
|
354
|
+
if (rest <= 0) {
|
|
355
|
+
txInFlight.delete(token);
|
|
356
|
+
const waiters = drainWaiters.get(token);
|
|
357
|
+
if (waiters !== undefined) {
|
|
358
|
+
drainWaiters.delete(token);
|
|
359
|
+
for (const w of waiters)
|
|
360
|
+
w();
|
|
361
|
+
}
|
|
362
|
+
}
|
|
363
|
+
else {
|
|
364
|
+
txInFlight.set(token, rest);
|
|
365
|
+
}
|
|
366
|
+
};
|
|
367
|
+
};
|
|
368
|
+
/**
|
|
369
|
+
* 事务收尾前把**本事务自己**已下发的语句等回来(CR 第三十七轮 major #1)。
|
|
370
|
+
* ⚠️ 顺序不能反过来:先发 ROLLBACK 的话,驱动里那条还没执行完的语句会在事务结束后(autocommit)
|
|
371
|
+
* 执行 —— 本该被回滚的写入真的落库,而调用方看到的是「已整体回滚」。
|
|
372
|
+
* 返回 false = 超时仍无法确认(调用方必须退役连接,且**不得**再发 ROLLBACK,见 `closeTx`)。
|
|
373
|
+
* 上限 5s:正常语句是毫秒级;真的有语句卡死时不值得把调用方一直挂住。
|
|
374
|
+
*
|
|
375
|
+
* ⚠️ **超时先 `interrupt()` 再放弃**(CR 第三十九轮 major #3,直连驱动实测 2026-11-19):
|
|
376
|
+
* 5s 内没交回通常是语句**真的还在原生执行**(实测 `INSERT … range(30000000000)` 超过 5s)。
|
|
377
|
+
* 此时直接放弃、靠用户 close 重建是**不安全的**:`closeSync()` 不取消原生任务 —— 实测关连接
|
|
378
|
+
* 与关实例各 0ms 返回,但进程**再也不会自行退出**(CPU 0%、内存不涨,不是繁忙而是原生线程
|
|
379
|
+
* 被自身的查询卡住),只能被 kill。`interrupt()` 后语句以 `INTERRUPT Error: Interrupted!`
|
|
380
|
+
* 交回、回滚照常确认、未提交写入不落库、同一路径重建成功、进程正常退出(同一探针实测)。
|
|
381
|
+
* 所以:到点先 `interrupt()`,再给有界窗口(`DRAIN_INTERRUPT_GRACE_MS`)等它交回;
|
|
382
|
+
* 等不到时清单里**一句都不剩**才返回 false —— 调用方照旧退役连接。
|
|
383
|
+
*/
|
|
384
|
+
const DRAIN_CAP_MS = deps.drainCapMs ?? 5_000;
|
|
385
|
+
const DRAIN_INTERRUPT_GRACE_MS = deps.drainInterruptGraceMs ?? 5_000;
|
|
386
|
+
/**
|
|
387
|
+
* 事务收尾的**独立**等待预算(默认 5s):drain 的两个截止时刻只覆盖「等在途语句交回」,
|
|
388
|
+
* 不覆盖 ROLLBACK 自身 —— 驱动卡在那条 ROLLBACK 上时,sync run / store init 会永久挂住,
|
|
389
|
+
* 连「回滚未能确认」都说不出口(CR 第四十一轮 major)。
|
|
390
|
+
*/
|
|
391
|
+
const ROLLBACK_CAP_MS = deps.rollbackCapMs ?? 5_000;
|
|
392
|
+
/** 等待计数归零;超过 deadline 返回 false。 */
|
|
393
|
+
const waitDrained = async (token, deadline) => {
|
|
394
|
+
while ((txInFlight.get(token) ?? 0) > 0) {
|
|
395
|
+
// ⚠️ **用单调时钟**(CR 第五十四轮 major):`Date.now()` 会被系统时钟调整(NTP 步进)
|
|
396
|
+
// 往回/往前跳,让 5s 的收尾预算提前或延后;`performance.now()` 单调,只随真实流逝走。
|
|
397
|
+
const left = deadline - performance.now();
|
|
398
|
+
if (left <= 0)
|
|
399
|
+
return false;
|
|
400
|
+
await new Promise((resolve) => {
|
|
401
|
+
const waiters = drainWaiters.get(token) ?? [];
|
|
402
|
+
waiters.push(resolve);
|
|
403
|
+
drainWaiters.set(token, waiters);
|
|
404
|
+
// 兜底唤醒:计数异常时也不能无限等(上面的 while 会再判一次)。超时前把自己从名单里
|
|
405
|
+
// 摘掉 —— 退役连接上的名单不该攒着已经没人等的闭包。
|
|
406
|
+
setTimeout(() => {
|
|
407
|
+
const list = drainWaiters.get(token);
|
|
408
|
+
if (list !== undefined) {
|
|
409
|
+
const i = list.indexOf(resolve);
|
|
410
|
+
if (i >= 0)
|
|
411
|
+
list.splice(i, 1);
|
|
412
|
+
if (list.length === 0)
|
|
413
|
+
drainWaiters.delete(token);
|
|
414
|
+
}
|
|
415
|
+
resolve();
|
|
416
|
+
}, Math.min(left, 250));
|
|
417
|
+
});
|
|
418
|
+
}
|
|
419
|
+
return true;
|
|
420
|
+
};
|
|
421
|
+
const drainOwned = async (token) => {
|
|
422
|
+
if (await waitDrained(token, performance.now() + DRAIN_CAP_MS))
|
|
423
|
+
return true;
|
|
424
|
+
// 语句在原生执行里卡着:中断是唯一不靠 kill 的出路(见上方实测)。
|
|
425
|
+
// ⚠️ 这里只可能中断到**本事务的**语句:事务开着期间,别的异步链的语句在
|
|
426
|
+
// `assertTxOwnership` 就被拒、根本进不了驱动(`foreignInFlight` 必为 0)。
|
|
427
|
+
try {
|
|
428
|
+
c.interrupt?.();
|
|
429
|
+
}
|
|
430
|
+
catch { /* 中断失败照旧走退役路径 */ }
|
|
431
|
+
if (await waitDrained(token, performance.now() + DRAIN_INTERRUPT_GRACE_MS))
|
|
432
|
+
return true;
|
|
433
|
+
// ⚠️ **放弃前再中断一次**(CR 第四十三轮 major 的追问):驱动在准备/初始化阶段会清掉
|
|
434
|
+
// 中断标志,一次 interrupt 可能落在「这条语句还没进入原生执行」的时刻 —— 之后它照样
|
|
435
|
+
// 开始跑,而我们这一侧已经给不出结论。此时已经退役令牌,剩余在途全是**本事务的**语句,
|
|
436
|
+
// 补一发中断没有归属风险,且子进程实测(2026-11-20):interrupt 让卡住的语句以
|
|
437
|
+
// `INTERRUPT Error` 交回后,进程不再被原生线程占住、可正常退出(仅 close 则 15s 不退)。
|
|
438
|
+
// 不在这里再等:调用方已按「回滚未能确认」退役,结论不再依赖它是否真的停下。
|
|
439
|
+
try {
|
|
440
|
+
c.interrupt?.();
|
|
441
|
+
}
|
|
442
|
+
catch { /* 同上 */ }
|
|
443
|
+
return false;
|
|
444
|
+
};
|
|
445
|
+
/**
|
|
446
|
+
* 事务结束(提交 / 回滚 / 拒绝)时把令牌的 `ended` 置位。令牌是对象、由异步上下文持有,
|
|
447
|
+
* 因此**判定永远有效**、不依赖全局集合的保留策略(CR 第三十八轮 major:全局集合 FIFO 淘汰
|
|
448
|
+
* 之后,极老上下文里的语句又能通过检查)。
|
|
449
|
+
*/
|
|
450
|
+
const retire = (token) => { token.ended = true; };
|
|
451
|
+
const newTxToken = () => ({ ended: false });
|
|
452
|
+
const txEndedError = () => {
|
|
453
|
+
const err = new Error('该语句所属的事务已经结束(提交 / 回滚 / 拒绝):它的结果与副作用都不可信,已拒绝。'
|
|
454
|
+
+ '不要在事务回调里下发不 await 的语句,也不要把事务里的 Promise 存到事务外再 await');
|
|
455
|
+
err.kind = 'internal';
|
|
456
|
+
err.hint = 'await 事务回调里的每一次调用,并让同一个 Store 实例上的操作串行执行';
|
|
457
|
+
return err;
|
|
458
|
+
};
|
|
459
|
+
/** BEGIN 已**成功返回**的令牌:据此区分「ROLLBACK 失败时有事务可能仍开着」与「BEGIN 本来就没成」。 */
|
|
460
|
+
const beganTx = new Set();
|
|
461
|
+
/**
|
|
462
|
+
* 连接退役(CR 第三十七轮 major #4):ROLLBACK 无法确认时,DuckDB 的事务状态未知 ——
|
|
463
|
+
* 继续下发语句有可能落进一条还开着的事务。此时**不发 ROLLBACK**(在途语句可能随后在
|
|
464
|
+
* autocommit 里执行)、拒绝一切后续语句;事务由 `close()` 关闭连接时隐式结束。
|
|
465
|
+
*/
|
|
466
|
+
let poisoned;
|
|
467
|
+
// 事务失效性探针超时、中断后仍未交回 —— closeTx 据此跳过 ROLLBACK(Codex 第十二轮 P2)。
|
|
468
|
+
let nativeProbeStuck = false;
|
|
469
|
+
// ⚠️ **「超时那一刻在途」≠「收尾时仍占用连接」**(CR 第六十六轮 major):探针可能在我们
|
|
470
|
+
// 放弃等待之后、回调返回之前自己交回 —— 只看 stuck 会为了一个已经结束的探针跳过 ROLLBACK
|
|
471
|
+
// 并错误退役。记账以**收尾时刻**为准:原始 promise 一落定就把这里翻成 true。
|
|
472
|
+
let nativeProbeSettled = true;
|
|
473
|
+
// ⚠️ **每个探针各记各的账**(CR第六十七轮 major):同一事务里两条在途语句先后失败,会各自
|
|
474
|
+
//起一次 `SELECT1`。若「已交回」只用一个共享布尔,旧探针 A交回会把**仍挂住的新探针 B**
|
|
475
|
+
//记成已结束 →收尾发出 ROLLBACK、排在 B后面超时,把「探针挂住」误报成「回滚未确认」。
|
|
476
|
+
//收尾只认**最近一次**探针的状态:锁存代次,过期探针的交回/超时都不再改状态。
|
|
477
|
+
let nativeProbeGen = 0;
|
|
478
|
+
/**
|
|
479
|
+
* `hint` 只在成因的恢复动作与通用说法**不同**时才给(CR 第四十一轮 major):COMMIT
|
|
480
|
+
* 结果未知时写入可能已落库,「关掉重建后直接重试」就是重复写,通用的
|
|
481
|
+
* 「未提交的写入不会落库」在这里是假话 —— 恢复动作用该成因自己的。
|
|
482
|
+
*/
|
|
483
|
+
const poison = (reason, hint) => {
|
|
484
|
+
if (poisoned === undefined)
|
|
485
|
+
poisoned = { reason, hint };
|
|
486
|
+
};
|
|
487
|
+
const poisonedError = (p) => {
|
|
488
|
+
const reason = p.reason;
|
|
489
|
+
const err = new Error(`Store 已退役:${reason} —— 单连接的事务状态无法确认,`
|
|
490
|
+
+ '任何后续语句都可能落进一条未结束的事务。请关闭该 Store 实例并重新创建后再试'
|
|
491
|
+
+ '(本实例上的写入结果不可信)');
|
|
492
|
+
err.kind = 'internal';
|
|
493
|
+
err.code = 'store_retired';
|
|
494
|
+
err.hint = p.hint
|
|
495
|
+
?? 'close 该 Store 并重建实例,先核对数据(本事务的写入是否落库)再决定是否重放;'
|
|
496
|
+
+ '若进程随后仍不退出,说明那条语句卡在不可中断的原生点上,只能结束进程';
|
|
497
|
+
return err;
|
|
498
|
+
};
|
|
499
|
+
/**
|
|
500
|
+
* `commitOrRefuse` 抛出的拒绝错误(回滚已由它负责)。
|
|
501
|
+
* ⚠️ 用**身份集合**而不是往错误对象上挂字段(CR 第三十七轮 major #2):回调可以拒绝
|
|
502
|
+
* `undefined` / `null`(读属性直接 TypeError,原错误被吞掉),别人也能在自己的错误对象上
|
|
503
|
+
* 伪造同名标记让回滚被跳过。集合只收我们亲手抛出的那个对象。
|
|
504
|
+
*/
|
|
505
|
+
const refusals = new WeakMap();
|
|
506
|
+
// ⚠️ 按**令牌**归属(CR 第三十八轮 major):A 的拒绝对象被调用方接住、在 B 的回调里原样
|
|
507
|
+
// 抛出时,只按身份匹配会让 B 跳过回滚 —— 而回滚已由 A 负责,B 的事务还开着。
|
|
508
|
+
/**
|
|
509
|
+
* 令牌生命周期的**唯一收口点**:事务结束(提交 / 拒绝 / 回调抛错 / 收尾失败)时把该令牌
|
|
510
|
+
* 从全部按令牌键控的集合里删掉。⚠️ 曾只在 `commitOrRefuse` 的成功/拒绝路径里删 —— 回调抛错
|
|
511
|
+
* 走 `rollbackInTx` 时 `brokenTx` / `beganTx` / 计数全都不删,令牌与错误原因被永久强引用
|
|
512
|
+
* (Codex PR#81 第四十三轮 P2;`txStateProbe` 的用例钉住「结束后一律为 0」)。
|
|
513
|
+
*/
|
|
514
|
+
const releaseTokenState = (token) => {
|
|
515
|
+
brokenTx.delete(token);
|
|
516
|
+
beganTx.delete(token);
|
|
517
|
+
txInFlight.delete(token);
|
|
518
|
+
txWrites.delete(token);
|
|
519
|
+
drainWaiters.delete(token);
|
|
520
|
+
deps.txStateProbe?.({
|
|
521
|
+
brokenTx: brokenTx.size, beganTx: beganTx.size, txInFlight: txInFlight.size,
|
|
522
|
+
txWrites: txWrites.size, drainWaiters: drainWaiters.size,
|
|
523
|
+
});
|
|
524
|
+
};
|
|
525
|
+
const isRefusal = (e, token) => ((typeof e === 'object' && e !== null) || typeof e === 'function') && refusals.get(e) === token;
|
|
526
|
+
/**
|
|
527
|
+
* 提交,或者**拒绝冒充成功**:还有**别的异步链**的语句在途时(`foreignInFlight`),它的结果
|
|
528
|
+
* (可能正是让本事务 aborted 的那次拒绝)还没交回,此刻 COMMIT 无法证明自己不是「先成功、
|
|
529
|
+
* 后丢写」—— 改成 ROLLBACK 并抛 `internal`,点明成因与「已整体回滚」。
|
|
530
|
+
* ⚠️ 为什么不按「错误已交回」打记号:那样必须等驱动把拒绝交回,而所有者提交恰恰可能发生在
|
|
531
|
+
* 交回之前(CR/Codex 第三十三轮 major 的实测形态)。在途计数在**下发时**就登记,提交时同步可读。
|
|
532
|
+
* 代价如实记录:并发的普通读(`count` 等)也会让同一时刻提交的事务被拒 —— 保守侧,且与
|
|
533
|
+
* Store「同一实例操作串行 await」的契约一致。
|
|
534
|
+
*/
|
|
535
|
+
const commitOrRefuse = async (token) => {
|
|
536
|
+
const marked = brokenTx.get(token);
|
|
537
|
+
brokenTx.delete(token); // 令牌唯一,读过即清,不会串到别的事务
|
|
538
|
+
const ownPending = txInFlight.get(token) ?? 0;
|
|
539
|
+
const ownWrites = txWrites.get(token) ?? 0;
|
|
540
|
+
if (marked === undefined && foreignInFlight === 0 && ownPending === 0 && ownWrites === 0) {
|
|
541
|
+
txInFlight.delete(token);
|
|
542
|
+
// ⚠️ **先退役令牌、再发 COMMIT**(CR 第三十八轮 major #9):COMMIT 在驱动里执行期间,
|
|
543
|
+
// 残留上下文里恢复的语句若仍被放行,会排在 COMMIT 之后在 autocommit 里执行,而本事务
|
|
544
|
+
// 报的是提交成功。事务控制语句自身走 `txControl` 豁免。
|
|
545
|
+
retire(token);
|
|
546
|
+
try {
|
|
547
|
+
await execSql('COMMIT', [], { txControl: true });
|
|
548
|
+
}
|
|
549
|
+
catch (e) {
|
|
550
|
+
// 连接已关闭(execSql 派发前的本地守卫)→ COMMIT 根本没下发,不存在「结果未知」;
|
|
551
|
+
// 原错误照常交回。⚠️ 判据用**身份集合**而不是读 `.kind`(CR 第五十五轮 major):
|
|
552
|
+
// 拒绝值的 `kind` 可能是抛异常的访问器(读一下就换成 TypeError),也可能是驱动对象
|
|
553
|
+
// 伪造的同名字段(会把「可能已落库」的提交当成没下发)。
|
|
554
|
+
if (e !== null && typeof e === 'object' && closedBeforeDispatch.has(e))
|
|
555
|
+
throw e;
|
|
556
|
+
// ⚠️ **COMMIT 结果未知**(CR 第三十九轮 major #5):COMMIT 已下发、结果没能确认 ——
|
|
557
|
+
// 写入可能已经落库,也可能没有。不能只说「失败」:按失败重试可能重复写。
|
|
558
|
+
// ⚠️ **本实例当场永久退役**(CR 第四十一轮 major):不能把「还能不能用」寄望于随后
|
|
559
|
+
// 那次 ROLLBACK 恰好失败 —— 若它成功(例如 COMMIT 根本没执行、事务还开着),归属
|
|
560
|
+
// 被清掉后连接会继续可用,而错误里刚说过「请用新的 Store 实例核对」。
|
|
561
|
+
poison('事务提交结果未知:COMMIT 已下发但结果未能确认(写入可能已落库)', '关闭并重建 Store 实例,**先核对数据是否已落库**再决定是否重放 —— '
|
|
562
|
+
+ 'COMMIT 已下发,不要按失败直接重试(可能重复写)');
|
|
563
|
+
const err = new Error('事务提交结果未知:COMMIT 已下发但未能确认结果 —— 本事务的写入**可能已经落库**,也可能没有。'
|
|
564
|
+
+ '不要按失败直接重试(可能重复写);请用新的 Store 实例核对后再决定', { cause: e });
|
|
565
|
+
err.kind = 'internal';
|
|
566
|
+
err.code = 'store_retired';
|
|
567
|
+
err.hint = '关闭并重建 Store 实例,核对数据后决定是否重放';
|
|
568
|
+
// 这条错误已按成因给过恢复动作:外层 catch 的回滚收尾不得再补通用文案(两套指令打架)。
|
|
569
|
+
selfDiagnosed.add(err);
|
|
570
|
+
throw err;
|
|
571
|
+
}
|
|
572
|
+
beganTx.delete(token);
|
|
573
|
+
return;
|
|
574
|
+
}
|
|
575
|
+
const why = marked
|
|
576
|
+
?? (ownWrites > 0
|
|
577
|
+
? `事务回调返回时仍有 ${ownWrites} 个本事务的写操作没有完成(是不是没有 await 它们?)`
|
|
578
|
+
: ownPending > 0
|
|
579
|
+
? `事务回调返回时仍有 ${ownPending} 条本事务的语句没有交回结果(是不是没有 await 它们?)`
|
|
580
|
+
: `事务提交时仍有 ${foreignInFlight} 条其他异步链下发的语句没有交回结果,它执行期报错会把本事务标成 aborted`);
|
|
581
|
+
// ⚠️ 顺序:先退役令牌(停掉后续下发),再等在途语句交回,最后才 ROLLBACK(`closeTx`)。
|
|
582
|
+
// ⚠️ `none`与 `unconfirmed`必须分开说(Codex第十四轮 P2):`none` =连接已关闭(未提交
|
|
583
|
+
//写入随连接丢弃)或 ROLLBACK被拒但活动事务探针确认连接上**已无事务** ——实例没有退役,
|
|
584
|
+
//后续语句照常可用;旧实现把两者都写成「该连接已退役」并打 `store_retired`,而同一实例
|
|
585
|
+
//随后还能成功查询,恢复动作被指向了不存在的故障。只有 `unconfirmed`(回滚可能没执行、
|
|
586
|
+
//事务也许还开着)才退役。
|
|
587
|
+
const closeState = await closeTx(token);
|
|
588
|
+
const rolledBack = closeState === 'confirmed';
|
|
589
|
+
const retired = closeState === 'unconfirmed';
|
|
590
|
+
txInFlight.delete(token);
|
|
591
|
+
txWrites.delete(token);
|
|
592
|
+
const rollbackNote = rolledBack
|
|
593
|
+
? '因此已整体回滚'
|
|
594
|
+
: retired
|
|
595
|
+
? '**回滚也未能确认**(连接可能已关闭、或还有语句未交回):该连接已退役,'
|
|
596
|
+
+ '不要把该事务的任何写入当成已保存'
|
|
597
|
+
: closed
|
|
598
|
+
? '连接已关闭,未提交的写入随连接丢弃,本实例不可再用 —— 但不要把该事务的任何写入当成已保存'
|
|
599
|
+
: '回滚没有确认回执,但连接上已无活动事务(该事务已经结束):实例仍可用,'
|
|
600
|
+
+ '但该事务的写入是否落库无法从本连接确认,不要把它的任何写入当成已保存';
|
|
601
|
+
const err = new Error(`事务未提交:${why} ——该事务可能已被 DuckDB 标成 aborted,`
|
|
602
|
+
+ 'COMMIT 可能返回成功却丢弃全部写入,'
|
|
603
|
+
+ rollbackNote);
|
|
604
|
+
err.kind = 'internal';
|
|
605
|
+
// ⚠️恢复动作按**收尾状态**给(CR第四十三轮 major):这条拒绝不经过外层 catch的
|
|
606
|
+
// `annotateUnconfirmedRollback`(身份集合让它跳过回滚),所以退役状态的恢复动作必须在这里
|
|
607
|
+
//自己给 ——否则 hint只说「让操作串行」,而实例已经退役、照做也没用。
|
|
608
|
+
const serializeHint = '让同一个 Store 实例上的操作串行执行,并 await 事务回调里的每一次写:不要用 Promise.all 并行调用 upsert/delete/transaction/query/count';
|
|
609
|
+
err.hint = rolledBack
|
|
610
|
+
? serializeHint
|
|
611
|
+
: retired
|
|
612
|
+
? serializeHint
|
|
613
|
+
+ ';本次回滚也未能确认、该连接已退役 —— 请关闭并重建 Store 实例,先核对数据(本事务的写入是否落库)再决定是否重放'
|
|
614
|
+
: serializeHint
|
|
615
|
+
+ ';本次事务的写入是否落库无法确认 —— 先核对数据再决定是否重放(不必重建 Store 实例)';
|
|
616
|
+
// ⚠️稳定标记(CR第四十七轮 major):这条拒绝不经过顶层 catch的标注,编排层按 code判
|
|
617
|
+
// 「实例已退役」——已确认回滚或「连接上已无事务」时实例仍可用,不带标记。
|
|
618
|
+
if (retired)
|
|
619
|
+
err.code = 'store_retired';
|
|
620
|
+
// 回滚**已由这里负责**(唯一处理点,CR 第三十六轮 major):外层 catch 见到这个拒绝就不再
|
|
621
|
+
// 回滚第二次 —— 两次回滚里只要一次成功、另一次失败,上一行对「回滚是否确认」的说法就不可信。
|
|
622
|
+
refusals.set(err, token);
|
|
623
|
+
throw err;
|
|
624
|
+
};
|
|
625
|
+
/**
|
|
626
|
+
* 语句执行期报错后,问连接「事务是否已被标成 aborted」(直连驱动实测见 catch 里的注释)。
|
|
627
|
+
* 直接走原生连接、不经 `execSql`:不登记在途、不做归属判定,也绝不递归。
|
|
628
|
+
*/
|
|
629
|
+
const txInvalidated = async () => {
|
|
630
|
+
// ⚠️ **必须有界**(CR 第六十四轮 major):这条探针直接走原生连接,若原生线程被上一条
|
|
631
|
+
// 失败语句占住,`SELECT 1` 永不交回 —— 而它是在 `execSql` 的 catch 里 await 的,拒绝也
|
|
632
|
+
// 就永远到不了调用方,回滚收尾(连同 ROLLBACK 自己的有界预算)根本没机会开始。
|
|
633
|
+
// 超时与探针报错同一保守侧:无法证明事务未失效 → 按「已失效」处理(只影响是否拒绝提交,
|
|
634
|
+
// 不换掉交回的错误)。超时后补发 interrupt,别把原生线程留在里面。
|
|
635
|
+
let timer;
|
|
636
|
+
const timeout = new Promise((_, reject) => {
|
|
637
|
+
timer = setTimeout(() => reject(new Error('事务失效性探针超时')), 50);
|
|
638
|
+
});
|
|
639
|
+
let raw;
|
|
640
|
+
let gen = -1;
|
|
641
|
+
try {
|
|
642
|
+
// 同一次派发前的复核(关闭 / 退役后这条探针不回交任何有意义的答案,直接按保守侧处理)。
|
|
643
|
+
if (closed || poisoned !== undefined)
|
|
644
|
+
return true;
|
|
645
|
+
gen = ++nativeProbeGen;
|
|
646
|
+
raw = c.runAndReadAll('SELECT 1', []);
|
|
647
|
+
nativeProbeSettled = false;
|
|
648
|
+
const settle = () => { if (gen === nativeProbeGen)
|
|
649
|
+
nativeProbeSettled = true; };
|
|
650
|
+
raw.then(settle, settle);
|
|
651
|
+
void raw.catch(() => { });
|
|
652
|
+
await Promise.race([raw, timeout]);
|
|
653
|
+
if (gen === nativeProbeGen)
|
|
654
|
+
nativeProbeStuck = false;
|
|
655
|
+
return false;
|
|
656
|
+
}
|
|
657
|
+
catch {
|
|
658
|
+
try {
|
|
659
|
+
c.interrupt?.();
|
|
660
|
+
}
|
|
661
|
+
catch { /* 中断失败照旧按已失效处理 */ }
|
|
662
|
+
// ⚠️ **超时后还要知道探针有没有真的交回**(Codex 第十二轮 P2):`Promise.race` 只结束
|
|
663
|
+
// 等待、不取消底层查询。若它仍在占用单连接,随后 closeTx 发出的 ROLLBACK 只会排在它
|
|
664
|
+
// 后面超时 —— 被误判成「回滚未确认」并退役实例,而归因是错的(ROLLBACK 根本没轮到)。
|
|
665
|
+
// 有界等它交回;仍未交回 → 记账,让 closeTx 跳过 ROLLBACK、按「收尾无法确认」处理。
|
|
666
|
+
const settled = raw === undefined ? true : await Promise.race([
|
|
667
|
+
raw.then(() => true, () => true),
|
|
668
|
+
new Promise((resolve) => { setTimeout(() => resolve(false), 100); }),
|
|
669
|
+
]);
|
|
670
|
+
if (gen === nativeProbeGen)
|
|
671
|
+
nativeProbeStuck = !settled;
|
|
672
|
+
return true;
|
|
673
|
+
}
|
|
674
|
+
finally {
|
|
675
|
+
if (timer !== undefined)
|
|
676
|
+
clearTimeout(timer);
|
|
677
|
+
}
|
|
678
|
+
};
|
|
679
|
+
/**
|
|
680
|
+
*多语句的**文本初筛**:只决定「要不要交给 DuckDB 解析」,判据是解析结果的语句数。
|
|
681
|
+
*对象是剥掉字面量 /注释 /引号标识符 / dollar 引用后的**代码**:引用与注释里的 `;`
|
|
682
|
+
*不执行,不算多语句;真正分隔语句的分号必然留在代码里,所以没有假阴性。末尾分号去掉
|
|
683
|
+
*后仍含 `;`才解析(`SELECT 1;`实测 `count === 1`,不再多花一次解析)。
|
|
684
|
+
*/
|
|
685
|
+
const mightBeMulti = (sql) => stripSqlLiterals(sql).replace(/[\s;]+$/, '').includes(';');
|
|
686
|
+
/**
|
|
687
|
+
* 把 SQL 里**不执行**的文本剥掉(字符串字面量 / 引号标识符 / 行注释 / 块注释 / dollar 引用),
|
|
688
|
+
* 只给「事务控制 / 多语句」两条**词法判据**用(`isRawTxControl`与 `mightBeMulti`)。
|
|
689
|
+
* ⚠️ 它不是 SQL 解析器,边界如实记录:块注释按 DuckDB 的**嵌套**规则消费到配平的
|
|
690
|
+
* 「星号加斜杠」;真驱动探针 2026-11-21:内层注释里含 COMMIT 的嵌套注释查询照常合法。
|
|
691
|
+
*/
|
|
692
|
+
const stripSqlLiterals = (sql) => {
|
|
693
|
+
let out = '';
|
|
694
|
+
for (let i = 0; i < sql.length; i++) {
|
|
695
|
+
const ch = sql[i];
|
|
696
|
+
if (ch === '-' && sql[i + 1] === '-') {
|
|
697
|
+
while (i < sql.length && sql[i] !== '\n')
|
|
698
|
+
i++;
|
|
699
|
+
out += '\n';
|
|
700
|
+
continue;
|
|
701
|
+
}
|
|
702
|
+
if (ch === '/' && sql[i + 1] === '*') {
|
|
703
|
+
// DuckDB 的块注释可以**嵌套**(真驱动探针 2026-11-21:
|
|
704
|
+
// `/* outer /* inner */ COMMIT */ SELECT 1` 返回 {v:1})。按深度消费到配平的 `*/`;
|
|
705
|
+
// 只认第一个 `*/` 会把内层之后的 `COMMIT */ SELECT` 当成代码,合法查询被误拒成 usage。
|
|
706
|
+
let depth = 1;
|
|
707
|
+
i += 2;
|
|
708
|
+
while (i < sql.length && depth > 0) {
|
|
709
|
+
if (sql[i] === '/' && sql[i + 1] === '*') {
|
|
710
|
+
depth++;
|
|
711
|
+
i += 2;
|
|
712
|
+
continue;
|
|
713
|
+
}
|
|
714
|
+
if (sql[i] === '*' && sql[i + 1] === '/') {
|
|
715
|
+
depth--;
|
|
716
|
+
i += 2;
|
|
717
|
+
continue;
|
|
718
|
+
}
|
|
719
|
+
i++;
|
|
720
|
+
}
|
|
721
|
+
i--;
|
|
722
|
+
out += ' ';
|
|
723
|
+
continue;
|
|
724
|
+
}
|
|
725
|
+
if (ch === "'" || ch === '"') {
|
|
726
|
+
const q = ch;
|
|
727
|
+
i++;
|
|
728
|
+
while (i < sql.length) {
|
|
729
|
+
if (sql[i] === q) {
|
|
730
|
+
if (sql[i + 1] === q) {
|
|
731
|
+
i += 2;
|
|
732
|
+
continue;
|
|
733
|
+
}
|
|
734
|
+
break;
|
|
735
|
+
}
|
|
736
|
+
i++;
|
|
737
|
+
}
|
|
738
|
+
out += ' ';
|
|
739
|
+
continue;
|
|
740
|
+
}
|
|
741
|
+
if (ch === '$') {
|
|
742
|
+
const m = /^\$(?:[A-Za-z_][A-Za-z_0-9]*)?\$/.exec(sql.slice(i));
|
|
743
|
+
if (m !== null) {
|
|
744
|
+
const end = sql.indexOf(m[0], i + m[0].length);
|
|
745
|
+
if (end !== -1) {
|
|
746
|
+
i = end + m[0].length - 1;
|
|
747
|
+
out += ' ';
|
|
748
|
+
continue;
|
|
749
|
+
}
|
|
750
|
+
}
|
|
751
|
+
}
|
|
752
|
+
out += ch;
|
|
753
|
+
}
|
|
754
|
+
return out;
|
|
755
|
+
};
|
|
756
|
+
/**
|
|
757
|
+
*事务控制的**词法判据**(唯一判据,2026-11-21 由「解析后看 statementType」改回文本)。
|
|
758
|
+
*
|
|
759
|
+
*判据为什么是文本、且必须是文本:
|
|
760
|
+
*① **语法闭包**已用真驱动枚举过(`@duckdb/node-api` 1.5.6-r.1):全部事务控制写法 ——
|
|
761
|
+
* `BEGIN [TRANSACTION]` / `COMMIT [WORK|TRANSACTION]` / `ROLLBACK [WORK]` /
|
|
762
|
+
* `END [TRANSACTION]` / `ABORT` / `START TRANSACTION [READ ONLY]`,含注释前缀与尾分号 ——
|
|
763
|
+
* `prepare(0).statementType` 都是 `TRANSACTION`,且**都以这六个词开头**;DuckDB 没有
|
|
764
|
+
* `PREPARE TRANSACTION`(直接语法错误)。所以句首锚定的词法判据没有假阴性。
|
|
765
|
+
*② 用 `prepare(0)` 当判据有**副作用**(真驱动探针 2026-11-21):prepare 会求值 table
|
|
766
|
+
* function 参数 —— `SELECT * FROM range(nextval('s'))` 在 prepare 时序列前进一格、执行时
|
|
767
|
+
* 再前进一格(结果从 1 行变 2 行);自动提交下 prepare 这条查询还会以 DuckDB 内部断言
|
|
768
|
+
* 「read-only but has made changes」失败,把一条合法查询变成 internal 错误。分类判据
|
|
769
|
+
* 不得改变被分类语句的结果。
|
|
770
|
+
*③ 判据对象是 `stripSqlLiterals` 之后的**代码**,锚定在(剥掉 `EXPLAIN` 包装后的)语句
|
|
771
|
+
* 开头:字符串里的 `COMMIT`、`CASE … END`、别名 `AS start` 都不会命中(真驱动接受
|
|
772
|
+
* `EXPLAIN ANALYZE SELECT 1 AS start`)。
|
|
773
|
+
*边界:多语句由语句数判据先拒(`SELECT 1; COMMIT` 的归因是多语句);`EXPLAIN` 包装
|
|
774
|
+
*由 `stripExplainWrapper` 剥掉后判里层(`EXPLAIN ANALYZE COMMIT` / `EXPLAIN (ANALYZE)
|
|
775
|
+
*COMMIT` 实测都会执行里层)。
|
|
776
|
+
*/
|
|
777
|
+
const TX_CONTROL_AT_START = /^\s*(?:(?:BEGIN|COMMIT|ROLLBACK|END|ABORT)\b|START\s+TRANSACTION\b)/i;
|
|
778
|
+
/**
|
|
779
|
+
*剥掉 `EXPLAIN [ANALYZE] [(选项…)]` 包装(有界,最多四层):`EXPLAIN ANALYZE COMMIT` 的外层
|
|
780
|
+
*语句类型是 EXPLAIN,但 DuckDB 照常执行里层计划(真驱动探针 2026-11-20:事务里写入 →
|
|
781
|
+
*`EXPLAIN ANALYZE COMMIT` → ROLLBACK 报 `no transaction is active`、写入已在库里)。
|
|
782
|
+
*入参是 `stripSqlLiterals` 的产物:括号只可能来自代码(选项里的字符串已被空格替换),
|
|
783
|
+
*平衡括号不会被字面量里的括号破坏。
|
|
784
|
+
*/
|
|
785
|
+
const stripExplainWrapper = (s) => {
|
|
786
|
+
let t = s;
|
|
787
|
+
for (let i = 0; i < 4; i++) {
|
|
788
|
+
const m = /^\s*EXPLAIN\b/i.exec(t);
|
|
789
|
+
if (m === null)
|
|
790
|
+
return t;
|
|
791
|
+
t = t.slice(m[0].length);
|
|
792
|
+
const a = /^\s+ANALYZE\b/i.exec(t);
|
|
793
|
+
if (a !== null)
|
|
794
|
+
t = t.slice(a[0].length);
|
|
795
|
+
const opt = /^\s*\(/.exec(t);
|
|
796
|
+
if (opt !== null) {
|
|
797
|
+
let depth = 0;
|
|
798
|
+
let j = opt[0].length - 1;
|
|
799
|
+
for (; j < t.length; j++) {
|
|
800
|
+
if (t[j] === '(')
|
|
801
|
+
depth++;
|
|
802
|
+
else if (t[j] === ')') {
|
|
803
|
+
depth--;
|
|
804
|
+
if (depth === 0) {
|
|
805
|
+
j++;
|
|
806
|
+
break;
|
|
807
|
+
}
|
|
808
|
+
}
|
|
809
|
+
}
|
|
810
|
+
t = t.slice(j);
|
|
811
|
+
}
|
|
812
|
+
}
|
|
813
|
+
return t;
|
|
814
|
+
};
|
|
815
|
+
/** 原始事务控制(含 `EXPLAIN` 里层)的唯一判据。 */
|
|
816
|
+
const isRawTxControl = (sql) => TX_CONTROL_AT_START.test(stripExplainWrapper(stripSqlLiterals(sql)));
|
|
817
|
+
/**原始事务控制的拒绝错误(`execSql`的唯一出口)。 */
|
|
818
|
+
const rawTxError = () => {
|
|
819
|
+
const err = new Error('事务控制语句不得经 `query` / 原始 SQL 下发 —— 它绕过事务归属与收尾判据'
|
|
820
|
+
+ '(回调里发 COMMIT 会让「回调随后抛错」无法回滚)');
|
|
821
|
+
err.kind = 'usage';
|
|
822
|
+
err.hint = '把写入放进 store.transaction() 的回调里,由 Store 负责 BEGIN / COMMIT / ROLLBACK';
|
|
823
|
+
return err;
|
|
824
|
+
};
|
|
825
|
+
/**
|
|
826
|
+
*多语句的**唯一判据**(CR 第四十一轮 major):解析一次、按语句数判。
|
|
827
|
+
*`SELECT 1; COMMIT` 实测会被驱动逐条执行 —— 第一条 SELECT、第二条 COMMIT,回调里的写入
|
|
828
|
+
*被提前提交,随后抛错也回滚不了。初筛(`mightBeMulti`)只看剥掉字面量 / 注释后的代码,
|
|
829
|
+
*真正分隔语句的分号必然留在代码里,所以没有假阴性。
|
|
830
|
+
* ⚠️ **解析失败不得放行**(CR 第五十九轮 major,真驱动探针 2026-11-20):驱动在派发时
|
|
831
|
+
*会**再次解析**并依次执行各语句 —— 实测「首次 extractStatements 异步拒绝、随后放行」
|
|
832
|
+
*时,`CREATE TABLE probeA(…); CREATE TABLE probeB(…)` 两条都真的执行了。拿不到语句数
|
|
833
|
+
*就无法证明只有一条,只能拒绝;原生解析错误挂在 `cause`(措辞用 safeValueText,
|
|
834
|
+
*访问器/无原型对象不得把诊断换掉)。
|
|
835
|
+
* ⚠️ 判据**不再经过 `prepare(0)`**(Codex 第十四轮 P2):旧实现为了语句类型做预编译,
|
|
836
|
+
*真驱动探针证明它会求值 table function 参数、改变查询结果(见 `TX_CONTROL_AT_START`)。
|
|
837
|
+
*/
|
|
838
|
+
const rejectMultiStatements = async (sql) => {
|
|
839
|
+
if (typeof c.extractStatements !== 'function') {
|
|
840
|
+
// 真实连接的方法在**原型**上(`...(conn as object)` 展开拿不到它),手写假对象可能
|
|
841
|
+
// 只包了 runAndReadAll。这里必须响亮失败而不是放行:跳过判据等于把多语句守卫关掉。
|
|
842
|
+
const err = new Error('连接缺少 extractStatements —— 无法判定 SQL 的语句数');
|
|
843
|
+
err.kind = 'internal';
|
|
844
|
+
err.hint = 'Store 连接必须提供 extractStatements(@duckdb/node-api 的 DuckDBConnection 原生具备);手写的测试假连接需显式转发该方法';
|
|
845
|
+
throw err;
|
|
846
|
+
}
|
|
847
|
+
let parseFailure;
|
|
848
|
+
const ex = await c.extractStatements(sql).catch((e) => { parseFailure = e; return undefined; });
|
|
849
|
+
if (ex === undefined) {
|
|
850
|
+
const err = new Error(`无法解析 SQL 的语句数(${safeValueText(parseFailure, 160)})——`
|
|
851
|
+
+ '为安全起见拒绝派发:多语句会被驱动逐条执行,事务控制或写入可能夹在其中');
|
|
852
|
+
err.kind = 'internal';
|
|
853
|
+
err.hint = '把多条语句拆成多次 query 调用;写入请放进 store.transaction() 的回调里';
|
|
854
|
+
err.cause = parseFailure;
|
|
855
|
+
throw err;
|
|
856
|
+
}
|
|
857
|
+
if (ex.count > 1) {
|
|
858
|
+
const err = new Error(`一次只接受一条语句(检测到 ${ex.count} 条)—— 多语句会被逐条执行,`
|
|
859
|
+
+ '事务控制或写入可能夹在其中,绕过归属与收尾判据');
|
|
860
|
+
err.kind = 'usage';
|
|
861
|
+
err.hint = '把多条语句拆成多次 query 调用;写入请放进 store.transaction() 的回调里';
|
|
862
|
+
throw err;
|
|
863
|
+
}
|
|
864
|
+
};
|
|
865
|
+
/**
|
|
866
|
+
* 已结束事务的残留上下文不得再**开启**新事务(CR 第三十八轮 major #2):`upsert` 的自动事务
|
|
867
|
+
* 与 `transaction()` 会在 `alsTx.run` 里把旧令牌替换成新令牌,替换之后 execSql 的退役检查
|
|
868
|
+
* 读到的就是新令牌了 —— 必须在**换令牌之前**就拒。
|
|
869
|
+
*/
|
|
870
|
+
const rejectEndedContext = () => {
|
|
871
|
+
const ctx = alsTx.getStore();
|
|
872
|
+
if (ctx !== undefined && ctx.ended)
|
|
873
|
+
throw txEndedError();
|
|
874
|
+
};
|
|
875
|
+
const execSql = async (sql, params = [], opts) => {
|
|
876
|
+
const txControl = opts?.txControl === true;
|
|
877
|
+
if (closed) {
|
|
878
|
+
// 身份登记:COMMIT 的 catch 靠它识别「本地没下发」(不读拒绝值的 kind)。
|
|
879
|
+
const e = usage('数据库连接已关闭');
|
|
880
|
+
closedBeforeDispatch.add(e);
|
|
881
|
+
throw e;
|
|
882
|
+
}
|
|
883
|
+
// 连接已退役:事务状态无法确认,一条语句都不许再发(CR 第三十七轮 major #4)。
|
|
884
|
+
if (poisoned !== undefined)
|
|
885
|
+
throw poisonedError(poisoned);
|
|
886
|
+
// ⚠️ **未决的失效探针占着单连接**(Codex第十四轮 P2):探针超时且中断后仍未交回时,
|
|
887
|
+
//连接上任何新语句都只会排在它后面、永不交回 ——回调若 catch掉原错误再 await
|
|
888
|
+
// count()/query(),回调就永远不返回,回滚收尾(连同 ROLLBACK自己的有界预算)根本没机会
|
|
889
|
+
//开始。此时拒绝一切新语句(txControl除外:收尾的 ROLLBACK由 closeTx自己先按「无法
|
|
890
|
+
//确认」处理),让回调尽快返回、由收尾退役实例。
|
|
891
|
+
if (!txControl && nativeProbeStuck && !nativeProbeSettled) {
|
|
892
|
+
const err = new Error('事务失效性探针超时后仍未交回:连接可能仍被它占用,已拒绝下发新语句'
|
|
893
|
+
+ '(继续下发只会排在它后面永不交回,事务收尾也就没有机会开始)');
|
|
894
|
+
err.kind = 'internal';
|
|
895
|
+
err.hint = '不要在事务回调里继续执行语句:让回调返回或抛错,由 Store 收尾(回滚);若收尾也未能确认,关闭并重建 Store 实例';
|
|
896
|
+
throw err;
|
|
897
|
+
}
|
|
898
|
+
// ⚠️ **原始事务控制一律拒绝**(CR 第三十九轮 major #4,第四十一轮改为按**解析出的语句
|
|
899
|
+
// 类型**判):托管回调里 `s.query('COMMIT')` 会通过归属检查、把回调里的写入提前提交 ——
|
|
900
|
+
// 随后回调抛错也无法回滚(「报失败、数据却落库」)。事务控制只能由 Store 自己
|
|
901
|
+
// (`txControl` 豁免)经 `transaction()` / 自动事务发出。
|
|
902
|
+
//事务控制由**词法判据**(`isRawTxControl`,见 `TX_CONTROL_AT_START`的注释)在下方
|
|
903
|
+
//同步判:不需要解析,也就不再为拿 statementType去 `prepare`(真驱动探针证明那会
|
|
904
|
+
//求值 table function参数、改变查询结果)。
|
|
905
|
+
// ⚠️ **已结束事务的残留上下文**里不得再下发语句(CR 第三十七轮 major #3):令牌过期只可能来自
|
|
906
|
+
// 「回调里没 await 的语句」或「事务里的 Promise 存到事务外再 await」—— 它的副作用与结果
|
|
907
|
+
// 都不可信。事务控制语句(ROLLBACK)走 `txControl` 豁免:收尾时必须能发出去。
|
|
908
|
+
const ctxToken = alsTx.getStore();
|
|
909
|
+
if (!txControl && ctxToken !== undefined && ctxToken.ended)
|
|
910
|
+
throw txEndedError();
|
|
911
|
+
// ⚠️ **语句等待期间有人开了事务**同样不安全(CodeRabbit PR#81 第二十八轮 major,实测复现:
|
|
912
|
+
// 外部 `SELECT` 与另一条链的事务交错,那条 SELECT 执行期报错 → 事务 COMMIT 返回成功而写入
|
|
913
|
+
// 被丢弃,`count` 从 1 变成 0)。归属检查只覆盖「下发前」;驱动内部 `runUntilLast` /
|
|
914
|
+
// `prepared.run()` 之间的 await 是第二个窗口,用事务代号把它封住。
|
|
915
|
+
// ⚠️ 解析判据的 await 也是同一个窗口(CR 第四十一轮):所以在它之前取代号,解析之后再判。
|
|
916
|
+
const epochBefore = txEpoch;
|
|
917
|
+
// ⚠️ **多语句必须独立于关键字初筛判**(CR 第四十五轮 major,真驱动探针 2026-11-20):
|
|
918
|
+
// `INSERT INTO scratch VALUES (1); SELECT * FROM missing_table` 里没有事务关键字,旧实现
|
|
919
|
+
//直接派发 ——驱动先执行 INSERT、再准备第二条时报错,**行已经写进去了**。只要剥掉
|
|
920
|
+
//字面量 /注释后的**代码**里还有分号,就解析一次、按语句数判。
|
|
921
|
+
const needsParse = !txControl && mightBeMulti(sql);
|
|
922
|
+
if (needsParse) {
|
|
923
|
+
// 解析同样占用连接(extract/prepare 走原生上下文):按在途登记,BEGIN 准入才看得见它。
|
|
924
|
+
// ⚠️ **归属先于登记**(CR 第四十二轮 major,实测复现):判据必须是「当前链就是这条事务的
|
|
925
|
+
// 所有者」,而不是实例级的「有活动事务」—— 事务开着时另一条链发来的解析若记在所有者账上,
|
|
926
|
+
// 所有者回调此刻返回,`commitOrRefuse` 会看到 ownPending>0、拒绝提交并把连接退役。
|
|
927
|
+
// `assertTxOwnership()` 在这里同步判(同 `foreignInFlight` 的输入),外部链在解析前就被拒。
|
|
928
|
+
assertTxOwnership();
|
|
929
|
+
const untrackParse = inTx && txToken !== undefined ? trackOwn(txToken) : trackForeign();
|
|
930
|
+
try {
|
|
931
|
+
await rejectMultiStatements(sql);
|
|
932
|
+
}
|
|
933
|
+
catch (e) {
|
|
934
|
+
// ⚠️ **解析失败也可能让事务失效**(CR第六十六轮 major的同一形态):DuckDB的解析会
|
|
935
|
+
//做绑定与 constant folding,解析期的报错同样可能把事务标成 aborted ——旧实现直接
|
|
936
|
+
//把它当普通拒绝交回,回调吞掉后 `commitOrRefuse`只看到在途归零,COMMIT被 DuckDB
|
|
937
|
+
//静默改成 ROLLBACK,写入丢失。(执行期的同名形态由派发路径的同一探针兜住。)
|
|
938
|
+
// 拒绝照旧是**原始解析错误**(不换掉);只在事务所有者的计数登记内问一次连接,
|
|
939
|
+
// 探针说已失效才打 brokenTx 记号。local usage(事务控制语句)与派发前被拒的形态
|
|
940
|
+
// 没动过连接状态,不问。
|
|
941
|
+
if (!txControl && !closed && poisoned === undefined
|
|
942
|
+
&& inTx && txToken !== undefined && ctxToken === txToken
|
|
943
|
+
&& safeKindOf(e) !== 'usage' && await txInvalidated()) {
|
|
944
|
+
brokenTx.set(txToken, '事务内的 SQL 在解析/预编译期就让 DuckDB 把整条事务标成 aborted'
|
|
945
|
+
+ `(驱动原文:${safeMessageText(e, 160)})`);
|
|
946
|
+
}
|
|
947
|
+
throw e;
|
|
948
|
+
}
|
|
949
|
+
finally {
|
|
950
|
+
untrackParse();
|
|
951
|
+
}
|
|
952
|
+
// 解析等待期间连接可能被关闭 / 退役,事务也可能被别人开启或结束 —— 逐项重判后才派发。
|
|
953
|
+
if (closed)
|
|
954
|
+
throw usage('数据库连接已关闭');
|
|
955
|
+
if (poisoned !== undefined)
|
|
956
|
+
throw poisonedError(poisoned);
|
|
957
|
+
if (!txControl && ctxToken !== undefined && ctxToken.ended)
|
|
958
|
+
throw txEndedError();
|
|
959
|
+
if (txEpoch !== epochBefore) {
|
|
960
|
+
assertTxOwnership();
|
|
961
|
+
throw epochChangedError();
|
|
962
|
+
}
|
|
963
|
+
}
|
|
964
|
+
// ⚠️ **原始事务控制一律拒绝**(CR第三十九轮 major #4):托管回调里 `s.query('COMMIT')`
|
|
965
|
+
//会通过归属检查、把回调里的写入提前提交 ——随后回调抛错也无法回滚(「报失败、数据却
|
|
966
|
+
//落库」)。事务控制只能由 Store自己(`txControl`豁免)经 `transaction()` /自动事务发出;
|
|
967
|
+
//判据是词法 + `EXPLAIN`里层(见 `TX_CONTROL_AT_START`),不碰连接、不求值参数。
|
|
968
|
+
if (!txControl) {
|
|
969
|
+
assertTxOwnership();
|
|
970
|
+
if (isRawTxControl(sql))
|
|
971
|
+
throw rawTxError();
|
|
972
|
+
}
|
|
973
|
+
// ⚠️ **一切语句派发都过归属闸门**(CodeRabbit PR#81 第十六轮 major,实测复现):单连接
|
|
974
|
+
// 上的语句会加入当前活动事务 —— 包括读语句。别人的事务开着时,另一条链发出的 SELECT
|
|
975
|
+
// 也落在那条事务里;它一旦执行期报错(实测:目标表是 CAST 失败的 view),DuckDB 就把
|
|
976
|
+
// 那条事务标成 aborted:所有者的 COMMIT 返回成功、写入却被静默丢弃。
|
|
977
|
+
// 只守方法入口不够:入口与该语句之间隔着 await(`del` 的 count),窗口仍在。
|
|
978
|
+
assertTxOwnership();
|
|
131
979
|
// 统一走 runAndReadAll:其结果带 getRowObjectsJson/columnNames(run() 的结果没有)
|
|
132
|
-
|
|
980
|
+
// 在**别的异步链**的上下文里下发、且此刻不在本事务里 → 登记为在途(见 `foreignInFlight`)。
|
|
981
|
+
// ⚠️ 判据是「**此刻有本实例的活动事务、且当前链就是它的所有者**」,不是「ALS 里有没有令牌」
|
|
982
|
+
// (CR 第三十五轮 major):已完成事务 A 里排下的定时器 / 续体仍带着 A 的令牌(AsyncLocalStorage
|
|
983
|
+
// 按异步资源传播),它在 `inTx === false` 时下发的语句同样可能落进随后开启的事务 B —— 旧判据
|
|
984
|
+
// 把「有令牌」当成「在本事务里」,这条语句不登记、B 提交时计数为 0,缺口因此打开。
|
|
985
|
+
// 归属由上一行的 `assertTxOwnership()` 担保(无 await 间隔):能走到这里且 `inTx` 为真,
|
|
986
|
+
// 当前链就一定是 `txToken` 的所有者。
|
|
987
|
+
const untrack = inTx && txToken !== undefined ? trackOwn(txToken) : trackForeign();
|
|
988
|
+
let result;
|
|
989
|
+
try {
|
|
990
|
+
// ⚠️ **无参语句不得传空数组**(Codex第十四轮 P2,真驱动探针2026-11-21):驱动把
|
|
991
|
+
//「传了 values」当成走 `runUntilLast`(extract + **prepare** + bind + run)的信号 ——
|
|
992
|
+
//空数组也是 truthy,于是每条无参查询都被预编译:prepare会求值 table function参数
|
|
993
|
+
//(`range(nextval(…))`因此多前进一格;自动提交下还以内部断言「read-only but has
|
|
994
|
+
// made changes」失败)。不传参数时驱动走原生一次性查询,语义相同、不预编译。
|
|
995
|
+
result = params.length === 0 ? await c.runAndReadAll(sql) : await c.runAndReadAll(sql, params);
|
|
996
|
+
}
|
|
997
|
+
catch (e) {
|
|
998
|
+
// ⚠️ **失败路径同样要检查代号**(CodeRabbit PR#81 第二十八轮 major):驱动报错时
|
|
999
|
+
// `runAndReadAll` 抛出,若只成功路径检查,最危险的情形(外部语句执行期报错 → 把别人的
|
|
1000
|
+
// 事务标成 aborted → COMMIT 返回成功而写入被丢弃,实测 count 1→0)恰好漏网。
|
|
1001
|
+
// 此时原错误被替换成归因正确的 internal,`cause` 保留驱动原文。
|
|
1002
|
+
// ⚠️ **本事务自己的语句执行期报错**:只有它**真的把事务标成 aborted** 时才打记号
|
|
1003
|
+
// (CR 第三十七轮 major #5 + 第三十八轮 major #6)。直连驱动实测(2026-11-18):
|
|
1004
|
+
// Catalog Error / Binder Error **不**废事务(后续 INSERT 正常、COMMIT 后写入落库),
|
|
1005
|
+
// Conversion Error 等执行期错误才废(后续语句报 `Current transaction is aborted`,
|
|
1006
|
+
// COMMIT 返回成功却丢写)。所以判据不是「任何错误都拒提交」——那会把可恢复错误吞成
|
|
1007
|
+
// 必然失败 —— 而是**问连接**:发一条 `SELECT 1`,报错即已失效。
|
|
1008
|
+
// ⚠️ **探针只在「活跃事务的所有者自己下发的数据语句」执行期报错后才发**
|
|
1009
|
+
// (CR 第四十一轮 major):`txInvalidated` 直接走原生连接、绕过授位与退役判据 ——
|
|
1010
|
+
// 事务控制语句(COMMIT/ROLLBACK)自身的失败另有处理(结果未知 / 退役),此刻在
|
|
1011
|
+
// 未知的事务状态上再多下发一条语句毫无意义;采集、解析期的失败发生在派发之前,
|
|
1012
|
+
// 连接状态没有被这条语句动过,也不需要问。
|
|
1013
|
+
// 连接已关 / 已退役时同样不问:两条检查与 `execSql` 派发前的同源,不能因为进入了
|
|
1014
|
+
// catch 分支就绕过它们(那条语句可能恰恰是「连接在等待期间被关掉」才失败的)。
|
|
1015
|
+
if (!txControl && !closed && poisoned === undefined
|
|
1016
|
+
&& inTx && txToken !== undefined && ctxToken === txToken && await txInvalidated()) {
|
|
1017
|
+
brokenTx.set(txToken, `本事务内的一条语句执行期报错,DuckDB 已把整条事务标成 aborted`
|
|
1018
|
+
+ `(驱动原文:${safeMessageText(e, 160)})`);
|
|
1019
|
+
}
|
|
1020
|
+
if (txEpoch !== epochBefore && txToken !== undefined) {
|
|
1021
|
+
brokenTx.set(txToken, '外部语句执行期报错,且期间另一条链开启了事务'
|
|
1022
|
+
+ `(驱动原文:${safeMessageText(e, 160)})`);
|
|
1023
|
+
}
|
|
1024
|
+
if (txEpoch !== epochBefore) {
|
|
1025
|
+
throw epochChangedError(e);
|
|
1026
|
+
}
|
|
1027
|
+
throw e;
|
|
1028
|
+
}
|
|
1029
|
+
finally {
|
|
1030
|
+
// 结果(成功或拒绝)都已交回 —— 这条外部语句不再「在途」。
|
|
1031
|
+
untrack();
|
|
1032
|
+
}
|
|
1033
|
+
// ⚠️ 事务已结束后才交回的结果同样不可信(CR 第三十七轮 major #3):语句可能已在回滚/提交
|
|
1034
|
+
// 之后才执行(回滚后的那次执行落在 autocommit 里),调用方据此继续下一步就是错的。
|
|
1035
|
+
if (!txControl && ctxToken !== undefined && ctxToken.ended)
|
|
1036
|
+
throw txEndedError();
|
|
1037
|
+
// 下发期间事务代号变了 → 这条语句可能落进了别人的事务(或它自己在事务里开过又提交过)
|
|
1038
|
+
if (txEpoch !== epochBefore) {
|
|
1039
|
+
// ⚠️ **执行成功**同样要给当前事务打记号(CR 第三十六轮 major):外部的 DELETE 在别的事务
|
|
1040
|
+
// 里**成功**执行时,行已经真的删了;调用方拿到的是拒绝 —— 若那条事务照常 COMMIT,
|
|
1041
|
+
// 「报了失败、数据却落库」同时成立。记号让那条事务拒绝提交并回滚,两边结论一致。
|
|
1042
|
+
if (txToken !== undefined) {
|
|
1043
|
+
brokenTx.set(txToken, `另一条异步链下发的语句在跨代期间**执行成功**,它可能已并入本事务:${sql.slice(0, 80)}`);
|
|
1044
|
+
}
|
|
1045
|
+
assertTxOwnership();
|
|
1046
|
+
throw epochChangedError();
|
|
1047
|
+
}
|
|
1048
|
+
return result;
|
|
133
1049
|
};
|
|
134
1050
|
const assertTable = (name) => {
|
|
135
1051
|
const t = tableByName(name);
|
|
@@ -137,6 +1053,30 @@ export async function createDuckDbStore(cfg, mode, deps = {}) {
|
|
|
137
1053
|
throw usage(`未知表:${name}`);
|
|
138
1054
|
return t;
|
|
139
1055
|
};
|
|
1056
|
+
/**
|
|
1057
|
+
* 事务归属守卫:有事务开着、但**当前异步链不是它的所有者** → 拒绝。
|
|
1058
|
+
*
|
|
1059
|
+
* ⚠️ 判据覆盖**所有语句**而不只是写:单连接上的读(`query`/`count`/`tables`)同样落进
|
|
1060
|
+
* 当前活动事务,它一旦执行期报错就会把那条事务标成 aborted(见 `execSql` 的注释)。
|
|
1061
|
+
* 所以文案必须对读也成立 —— 只说"写操作"会把只读调用方引到错误的成因上
|
|
1062
|
+
* (CodeRabbit PR#81 第十七轮 minor,实测:`count`/`query` 报出的是"写操作")。
|
|
1063
|
+
* 为什么是 `internal` 而不是 `usage`:这不是调用方参数写错,是本进程内两条异步链
|
|
1064
|
+
* 同时用一个 Store 实例 —— 唯一正确的修法是调用方串行化(Store 契约见文件头)。
|
|
1065
|
+
*/
|
|
1066
|
+
const assertTxOwnership = () => {
|
|
1067
|
+
if (!inTx)
|
|
1068
|
+
return;
|
|
1069
|
+
if (alsTx.getStore() === txToken)
|
|
1070
|
+
return;
|
|
1071
|
+
const err = new Error('同一个 Store 实例上有事务未提交时,另一条异步链又发起了语句 —— 已拒绝。'
|
|
1072
|
+
+ '写会被并入那条事务并随它一起回滚(表现为"写入成功但数据消失");'
|
|
1073
|
+
+ '读同样落在那条事务里,一旦执行期报错就会把它标成 aborted,'
|
|
1074
|
+
+ '所有者随后的 COMMIT 返回成功而写入被丢弃。'
|
|
1075
|
+
+ 'Store 的并发契约是"同一实例上的操作必须串行 await"(见 src/store/duckdb.ts 文件头)');
|
|
1076
|
+
err.kind = 'internal';
|
|
1077
|
+
err.hint = '让同一个 Store 实例上的操作串行执行:不要用 Promise.all 并行调用 upsert/delete/transaction/query/count';
|
|
1078
|
+
throw err;
|
|
1079
|
+
};
|
|
140
1080
|
const assertRows = (t, rows) => {
|
|
141
1081
|
if (rows.length === 0)
|
|
142
1082
|
return;
|
|
@@ -160,7 +1100,13 @@ export async function createDuckDbStore(cfg, mode, deps = {}) {
|
|
|
160
1100
|
const cols = t.columns.map((x) => x.name);
|
|
161
1101
|
const quoted = cols.map((x) => `"${x}"`).join(', ');
|
|
162
1102
|
const nonKey = cols.filter((x) => !t.primaryKey.includes(x));
|
|
163
|
-
|
|
1103
|
+
// ⚠️ 只有主键列的表要写 `DO NOTHING`(2026-11-14,历史审查 PR#4 复核):`schema_version`
|
|
1104
|
+
// 的唯一列 `version` 就是主键,`nonKey` 为空时拼出的 `DO UPDATE SET ` 语法错误
|
|
1105
|
+
// (实测 `Parser Error: syntax error at end of input`),而 `assertTable` 放行该表
|
|
1106
|
+
// —— upsert 契约对这张表不成立。语义上「只有主键」的行没有可更新的列,冲突即已存在。
|
|
1107
|
+
const conflictAction = nonKey.length > 0
|
|
1108
|
+
? `DO UPDATE SET ${nonKey.map((x) => `"${x}" = excluded."${x}"`).join(', ')}`
|
|
1109
|
+
: 'DO NOTHING';
|
|
164
1110
|
const pk = t.primaryKey.map((x) => `"${x}"`).join(', ');
|
|
165
1111
|
// ⚠️ 同批重复主键必须先收敛(2026-11-04 修):DuckDB 的多行 `INSERT ... ON CONFLICT
|
|
166
1112
|
// DO UPDATE` 在同一语句里遇到重复键时**保留第一条**(实测:两条 id=1 的行写入后是
|
|
@@ -212,30 +1158,358 @@ export async function createDuckDbStore(cfg, mode, deps = {}) {
|
|
|
212
1158
|
// 65000 是保守值:实测该版本上限 ≥70000,勿据此放大(Q 组 Q-低-1)。
|
|
213
1159
|
const hardCap = Math.max(1, Math.floor(65000 / cols.length));
|
|
214
1160
|
const rowsPerStmt = Math.max(1, Math.min(cfg.batchSize, hardCap));
|
|
1161
|
+
// `DO NOTHING` 时不能按 `batch.length` 记账(Codex PR#74 第二轮 P2):冲突行一行都没写,
|
|
1162
|
+
// 契约(types.ts `Store.upsert`「返回实际写入行数」)要求如实计数。这张表所有列都是主键,
|
|
1163
|
+
// 唯一会改变行数的就是「新键插入」—— 用前后计数,与 `del` 的算法同源。
|
|
1164
|
+
// `DO UPDATE` 之路不计数:新键插入、旧键更新,两者都算一次写入。
|
|
1165
|
+
const countDelta = nonKey.length === 0;
|
|
1166
|
+
// ⚠️ 同 `del`:前导 count 与 INSERT 前面各判一次归属。`doUpsert` 只在事务内路径被调用
|
|
1167
|
+
// (外部 upsert 已在入口被拒),但事务可能在这条计数期间被别的链抢走 —— 派发点那次
|
|
1168
|
+
// 才是真正的闸门;计数前这次防的是「计数语句本身落进别人的事务并把它污掉」。
|
|
1169
|
+
assertTxOwnership();
|
|
1170
|
+
const beforeCount = countDelta ? await store.count(t.name) : 0;
|
|
215
1171
|
for (let i = 0; i < uniq.length; i += rowsPerStmt) {
|
|
216
1172
|
const batch = uniq.slice(i, i + rowsPerStmt);
|
|
217
1173
|
const placeholders = batch.map(() => `(${cols.map(() => '?').join(', ')})`).join(', ');
|
|
218
1174
|
const params = batch.flatMap((r) => cols.map((k) => r[k] ?? null));
|
|
219
|
-
|
|
1175
|
+
// ⚠️ 归属检查必须**贴着语句派发**,不能只在 `upsert` 入口判一次(CodeRabbit PR#81):
|
|
1176
|
+
// 入口到这条 INSERT 之间隔着 `beforeCount` 等 await,别的调用方可能正好在这段窗口里
|
|
1177
|
+
// 开事务 —— 那时这次 INSERT 会被并入它、随它回滚,又变回"成功却丢数据"。
|
|
1178
|
+
assertTxOwnership();
|
|
1179
|
+
await store.execSql(`INSERT INTO "${t.name}" (${quoted}) VALUES ${placeholders} ON CONFLICT (${pk}) ${conflictAction}`, params);
|
|
220
1180
|
written += batch.length;
|
|
221
1181
|
}
|
|
1182
|
+
if (countDelta)
|
|
1183
|
+
return Math.max(0, (await store.count(t.name)) - beforeCount);
|
|
222
1184
|
return written;
|
|
223
1185
|
};
|
|
224
1186
|
const del = async (tname, where, params = []) => {
|
|
225
1187
|
const t = assertTable(tname);
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
1188
|
+
// ⚠️ **关闭必须先于归属**(Codex PR#81 第二十五轮 P3):事务回调里 `close()` 之后再删,
|
|
1189
|
+
// 先判归属会把"连接已关"误诊成"并发竞争"(见 `upsert` 处的同款注释)。
|
|
1190
|
+
if (closed)
|
|
1191
|
+
throw usage('数据库连接已关闭');
|
|
1192
|
+
rejectEndedContext();
|
|
1193
|
+
// ⚠️ 归属检查必须**先于第一条语句**(CodeRabbit PR#81 第十轮 major,实测复现):
|
|
1194
|
+
// 若只在 `count` 之后判,这条 count 自己就会在别人的事务里执行 —— 而**任何**执行期
|
|
1195
|
+
// 错误(实测:目标表被换成 CAST 失败的 view 时的 Conversion Error)都会把那条事务
|
|
1196
|
+
// 标成 aborted:对方的 COMMIT 返回成功,写入却被静默丢弃(实测行数归零、无报错)。
|
|
1197
|
+
// 所以外部写在这里就被拒,一条语句都不发。
|
|
1198
|
+
assertTxOwnership();
|
|
1199
|
+
// ⚠️ 事务外的 `del` 是**多语句写操作**:整个序列(count → DELETE → count)登记在册,
|
|
1200
|
+
// 期间不许开事务(`admitBegin`)—— 否则 DELETE 的实际执行可能早于 BEGIN 提交、结果晚于
|
|
1201
|
+
// BEGIN 交回,删改行数以「跨代失败」报出去,行却已经删了(CR 第三十七轮 major #6)。
|
|
1202
|
+
const op = inTx ? undefined : enterWriteOp();
|
|
1203
|
+
const own = inTx && txToken !== undefined ? trackWrite(txToken) : undefined;
|
|
235
1204
|
try {
|
|
236
|
-
await
|
|
1205
|
+
const before = await store.count(tname);
|
|
1206
|
+
// 派发点再判一次(CodeRabbit PR#81 major):`count` 是 await,期间别的调用方可能开事务,
|
|
1207
|
+
// 随后这条 DELETE 就被并进去。
|
|
1208
|
+
assertTxOwnership();
|
|
1209
|
+
await store.execSql(`DELETE FROM "${t.name}" WHERE ${where}`, params);
|
|
1210
|
+
const after = await store.count(tname);
|
|
1211
|
+
return Math.max(0, before - after);
|
|
1212
|
+
}
|
|
1213
|
+
finally {
|
|
1214
|
+
if (own !== undefined)
|
|
1215
|
+
own();
|
|
1216
|
+
if (op !== undefined)
|
|
1217
|
+
leaveWriteOp(op);
|
|
237
1218
|
}
|
|
238
|
-
|
|
1219
|
+
};
|
|
1220
|
+
/**
|
|
1221
|
+
* 把「回滚未能确认」补进**交回给调用方的诊断**(两个事务处理器的唯一落点)。
|
|
1222
|
+
* 否则调用方的诊断与已确认回滚一字不差(CR 第四十二轮 major)。
|
|
1223
|
+
* ⚠️ **不再就地改写调用方的错误对象**(CR 第六十轮 major):回滚状态是**这次事务尝试**的属性,
|
|
1224
|
+
* 不是错误对象的属性 —— 同一个 Error 可能被回调跨 Store / 跨事务复用,在 A(回滚未确认、实例
|
|
1225
|
+
* 退役)上补的 `code: 'store_retired'` 与「本实例已退役」文案会跟着对象出现在 B(回滚已确认、
|
|
1226
|
+
* 实例仍可用)的诊断里,全是假话。现在**一律包一层**:原错误挂 `cause`(身份契约由 cause 承接),
|
|
1227
|
+
* 状态字段只写在我们自己新建的普通 Error 上 —— 也顺带绕开了冻结 / getter+空 setter / revoked
|
|
1228
|
+
* Proxy 这些「写外部对象会炸或静默丢」的陷阱(round 46–59 的加固因此变成结构性保证)。
|
|
1229
|
+
*/
|
|
1230
|
+
/** 自带成因级恢复动作的错误(COMMIT 结果未知,本地新建)—— 不再追加通用回滚文案,免得两套指令打架。 */
|
|
1231
|
+
const selfDiagnosed = new WeakSet();
|
|
1232
|
+
const annotateUnconfirmedRollback = (e, state) => {
|
|
1233
|
+
if (state !== 'unconfirmed')
|
|
1234
|
+
return e;
|
|
1235
|
+
// COMMIT 结果未知的错误是本地新建的对象,不存在跨实例复用;它已按成因给过恢复动作。
|
|
1236
|
+
if (isErrorValue(e) && selfDiagnosed.has(e))
|
|
1237
|
+
return e;
|
|
1238
|
+
const note = ' ——(事务收尾)回滚未能确认:ROLLBACK 可能根本没有执行,该事务也许仍然开着;'
|
|
1239
|
+
+ '该连接已退役,本实例上的写入结果不可信';
|
|
1240
|
+
const hint = '关闭并重建 Store 实例,先核对数据(本事务的写入是否落库)'
|
|
1241
|
+
+ '再决定是否重放;本实例上的后续语句都会被拒';
|
|
1242
|
+
// 原 message / kind / hint 的读取都可能抛(访问器 / revoked Proxy):一律读不到就退化。
|
|
1243
|
+
const isErr = isErrorValue(e);
|
|
1244
|
+
const readable = (() => {
|
|
1245
|
+
try {
|
|
1246
|
+
if (isErr)
|
|
1247
|
+
return String(e.message);
|
|
1248
|
+
// 非 Error 的拒绝值(字符串 / 对象)也要带上状态(CR 第四十八轮 major):调用方拿到的
|
|
1249
|
+
// 不能与「已确认回滚」一字不差;原值挂在 cause 上。
|
|
1250
|
+
return `事务失败(回调拒绝了一个非 Error 值:${safeValueText(e, 120)})`;
|
|
1251
|
+
}
|
|
1252
|
+
catch {
|
|
1253
|
+
return '(无法读取的错误消息)';
|
|
1254
|
+
}
|
|
1255
|
+
})();
|
|
1256
|
+
const prevKind = isErr
|
|
1257
|
+
? (() => {
|
|
1258
|
+
// ⚠️ 非字符串按缺失处理(CR 第六十一轮 major):Symbol 等值落进模板拼接会抛
|
|
1259
|
+
// TypeError,整段标注会被换成 TypeError;直接落进 kind 分流又会污染命令出口。
|
|
1260
|
+
try {
|
|
1261
|
+
const v = e.kind;
|
|
1262
|
+
return typeof v === 'string' ? v : undefined;
|
|
1263
|
+
}
|
|
1264
|
+
catch {
|
|
1265
|
+
return undefined;
|
|
1266
|
+
}
|
|
1267
|
+
})()
|
|
1268
|
+
: undefined;
|
|
1269
|
+
const prevHint = isErr
|
|
1270
|
+
? (() => {
|
|
1271
|
+
try {
|
|
1272
|
+
const v = e.hint;
|
|
1273
|
+
return typeof v === 'string' ? v : undefined;
|
|
1274
|
+
}
|
|
1275
|
+
catch {
|
|
1276
|
+
return undefined;
|
|
1277
|
+
}
|
|
1278
|
+
})()
|
|
1279
|
+
: undefined;
|
|
1280
|
+
const wrapped = new Error(`${readable}${note}`, { cause: e });
|
|
1281
|
+
wrapped.kind = prevKind ?? 'internal';
|
|
1282
|
+
wrapped.retryable = false;
|
|
1283
|
+
wrapped.code = 'store_retired';
|
|
1284
|
+
wrapped.hint = prevHint === undefined
|
|
1285
|
+
? hint
|
|
1286
|
+
: `${hint};原错误的建议(核对之后才可执行):${prevHint}`;
|
|
1287
|
+
return wrapped;
|
|
1288
|
+
};
|
|
1289
|
+
/**
|
|
1290
|
+
* 在令牌上下文里收尾:退役令牌 → 等在途语句落定 → ROLLBACK。返回收尾状态(三态,见
|
|
1291
|
+
* `TxClose`):`confirmed` 才会被 `commitOrRefuse` 说成「已整体回滚」;`unconfirmed` 由两个
|
|
1292
|
+
* 事务处理器补进交回的错误(CR 第四十二轮 major:否则调用方拿到的诊断与已确认回滚一字不差)。
|
|
1293
|
+
* ⚠️ **关闭后不得进入上下文**(CodeRabbit PR#81 第十九轮 minor):`close()` 已把 ALS
|
|
1294
|
+
* `disable()` 掉,而 `alsTx.run()` 会把它**重新启用**、失败路径又不再 disable ——
|
|
1295
|
+
* 「事务进行中被 close」每次都在攒一个启用态上下文。`execSql` 在这种情况下本来也必然抛
|
|
1296
|
+
* 「连接已关闭」,回滚必然失败,所以直接跳过。
|
|
1297
|
+
*/
|
|
1298
|
+
const rollbackInTx = async (token) => {
|
|
1299
|
+
retire(token);
|
|
1300
|
+
// 连接已关:未提交的写入随连接丢弃(真驱动探针 2026-11-20:关连接后重开,未提交行数 0),
|
|
1301
|
+
// 事务状态不是「未知」,不需要向调用方补「回滚未确认」。
|
|
1302
|
+
if (closed)
|
|
1303
|
+
return 'none';
|
|
1304
|
+
return alsTx.run(token, () => closeTx(token));
|
|
1305
|
+
};
|
|
1306
|
+
/**
|
|
1307
|
+
* `rollbackInTx` / `commitOrRefuse` 共用的事务收尾(只在令牌上下文里调用)。
|
|
1308
|
+
* 返回收尾状态;无法确认时**退役连接**并**不发 ROLLBACK**(CR 第三十七轮 major #1/#4):
|
|
1309
|
+
* 先 ROLLBACK 的话,驱动里还没执行完的语句会在事务结束后于 autocommit 里执行。
|
|
1310
|
+
*/
|
|
1311
|
+
/**
|
|
1312
|
+
* 连接上**此刻有没有活动事务**(BEGIN 收尾归因用,Codex PR#81 第五十四轮 P2)。
|
|
1313
|
+
* 真驱动探针(2026-11-20):autocommit 下每条语句各开一个隐式事务、`txid_current()`
|
|
1314
|
+
* 逐次**递增**;显式事务内连续查询返回**同一值**。所以「两次查询同值 = 有活动事务」。
|
|
1315
|
+
* 任何失败 / 超时 → `undefined`(调用方按「无法确认」处理,保守侧不变)。
|
|
1316
|
+
* ⚠️ 只在 ROLLBACK 已被拒、需要判断「事务到底开没开」时调用 —— 正常路径一次都不发。
|
|
1317
|
+
*/
|
|
1318
|
+
const probeActiveTransaction = async () => {
|
|
1319
|
+
// ⚠️ **退役连接上一条语句都不许发**(CR 第六十三轮 major):`closeTx` 在这里绕过了
|
|
1320
|
+
// execSql 的退役守卫,若连接已退役(poison),探针就是「退役后仍做原生操作」。
|
|
1321
|
+
// 退役状态下的答案已由 poison 决定,保守侧 = 按「未能确认」处理。
|
|
1322
|
+
if (poisoned !== undefined)
|
|
1323
|
+
return undefined;
|
|
1324
|
+
const one = async () => {
|
|
1325
|
+
// ⚠️ **每次原生调用前复核连接状态**(CR 第六十五轮 major):close() 可能落在两次探针
|
|
1326
|
+
// 之间(第一次 txid_current 在途时关连接),随后第二次仍在已关闭的连接上发语句;
|
|
1327
|
+
// 反过来 close 也可能落在 ROLLBACK 在途期间,让第一次探针在关闭之后才发。关闭 / 退役
|
|
1328
|
+
// 时静态求值不可信 → 抛给下面的保守侧(返回 undefined)。
|
|
1329
|
+
if (closed)
|
|
1330
|
+
throw new Error('连接已关闭,事务状态探针不派发');
|
|
1331
|
+
if (poisoned !== undefined)
|
|
1332
|
+
throw new Error('Store 已退役,事务状态探针不派发');
|
|
1333
|
+
let timer;
|
|
1334
|
+
const timeout = new Promise((_, reject) => {
|
|
1335
|
+
timer = setTimeout(() => reject(new Error('事务状态探针超时')), 50);
|
|
1336
|
+
});
|
|
1337
|
+
try {
|
|
1338
|
+
const raw = c.runAndReadAll('SELECT txid_current() AS t');
|
|
1339
|
+
// 超时后探针仍可能迟到拒绝(中断 / 连接收尾)—— 先挂一个空的 catch,避免它冒成
|
|
1340
|
+
// 未处理的 rejection 带走进程。
|
|
1341
|
+
void raw.catch(() => { });
|
|
1342
|
+
const r = await Promise.race([raw, timeout]);
|
|
1343
|
+
return String(r.getRowObjectsJson?.()[0]?.t);
|
|
1344
|
+
}
|
|
1345
|
+
finally {
|
|
1346
|
+
if (timer !== undefined)
|
|
1347
|
+
clearTimeout(timer);
|
|
1348
|
+
}
|
|
1349
|
+
};
|
|
1350
|
+
try {
|
|
1351
|
+
const a = await one();
|
|
1352
|
+
const b = await one();
|
|
1353
|
+
return a === b;
|
|
1354
|
+
}
|
|
1355
|
+
catch {
|
|
1356
|
+
// ⚠️ 超时 / 失败时把执行中的原生查询中断掉(CR 第六十三轮 major):close 不会取消
|
|
1357
|
+
// 原生任务,挂住的 SELECT 会把进程留在后台。目的只是解卡,不改变归因。
|
|
1358
|
+
try {
|
|
1359
|
+
c.interrupt?.();
|
|
1360
|
+
}
|
|
1361
|
+
catch { /* 中断失败照旧走保守侧 */ }
|
|
1362
|
+
return undefined;
|
|
1363
|
+
}
|
|
1364
|
+
};
|
|
1365
|
+
const closeTx = async (token) => {
|
|
1366
|
+
retire(token);
|
|
1367
|
+
if (closed)
|
|
1368
|
+
return 'none';
|
|
1369
|
+
if (!(await drainOwned(token))) {
|
|
1370
|
+
// 中断之后仍不交回:语句卡在不可中断的原生点上。此时连 close 都不能让进程退出
|
|
1371
|
+
//(实测:连接/实例都秒关,但原生线程仍被自身查询占住),所以退役文案要与这一事实一致。
|
|
1372
|
+
poison('事务内仍有语句没有交回结果(中断后仍未返回),无法确认它们不会在回滚之后落库');
|
|
1373
|
+
return 'unconfirmed';
|
|
1374
|
+
}
|
|
1375
|
+
// ⚠️ **探针可能仍占着连接**(Codex 第十二轮 P2):事务失效性探针超时后已无法确认它是否
|
|
1376
|
+
// 停止;此时发 ROLLBACK 只会排在它后面、超时后被误判成「回滚未确认」,而真实成因是连接
|
|
1377
|
+
// 仍被探针占用。直接按「收尾无法确认」退役,把成因写进文案,不发 ROLLBACK。
|
|
1378
|
+
// ⚠️ 判据是「**收尾此刻**探针仍没交回」(CR 第六十六轮 major):超时那一刻在途、但随后
|
|
1379
|
+
// 自己交回的探针已经不占连接,为它跳过 ROLLBACK 会把可正常收尾的事务错误退役。
|
|
1380
|
+
if (nativeProbeStuck && !nativeProbeSettled) {
|
|
1381
|
+
poison('事务状态探针中断后仍未交回:连接可能仍被它占用,ROLLBACK 无法安全发出');
|
|
1382
|
+
beganTx.delete(token);
|
|
1383
|
+
return 'unconfirmed';
|
|
1384
|
+
}
|
|
1385
|
+
// 事务控制语句豁免「令牌已退役」检查,否则收尾自己的 ROLLBACK 也会被挡。
|
|
1386
|
+
// ⚠️ **ROLLBACK 自身必须有界,且超时后必须 interrupt**(CR 第四十一轮 major 定有界、
|
|
1387
|
+
// 第四十二轮补中断)。子进程实测(DuckDB 1.5.6-r.1,2026-11-20):巨型语句占住原生线程、
|
|
1388
|
+
// ROLLBACK 排在它后面时,到点只 close 掉连接与实例,**进程 15s 内不退出**(只能 SIGKILL,
|
|
1389
|
+
// closeSync 不取消原生任务);同一探针先 `interrupt()`,卡住的语句以 `INTERRUPT Error`
|
|
1390
|
+
// 交回、排队的 ROLLBACK 随即执行成功、1.9s 内正常退出。所以:到点先 interrupt,
|
|
1391
|
+
// 再给 `DRAIN_INTERRUPT_GRACE_MS` 等 ROLLBACK 落定;等不到才按「未能确认」退役。
|
|
1392
|
+
let failed;
|
|
1393
|
+
// ⚠️ **不能用「failed !== undefined」判是否被拒**(CR 第五十二轮 major):拒绝值恰好是
|
|
1394
|
+
// `undefined` 时会把「ROLLBACK 被拒」当成「成功」,于是回滚未确认的事务被说成「已整体回滚」。
|
|
1395
|
+
let rejected = false;
|
|
1396
|
+
const settled = execSql('ROLLBACK', [], { txControl: true })
|
|
1397
|
+
.then(() => { }, (e) => { failed = e; rejected = true; });
|
|
1398
|
+
/** 等到 `settled` 或超时;返回是否已落定。 */
|
|
1399
|
+
const awaitSettled = async (ms) => {
|
|
1400
|
+
let timer;
|
|
1401
|
+
const done = await Promise.race([
|
|
1402
|
+
settled.then(() => true),
|
|
1403
|
+
new Promise((resolve) => { timer = setTimeout(() => resolve(false), ms); }),
|
|
1404
|
+
]);
|
|
1405
|
+
if (timer !== undefined)
|
|
1406
|
+
clearTimeout(timer);
|
|
1407
|
+
return done;
|
|
1408
|
+
};
|
|
1409
|
+
try {
|
|
1410
|
+
if (!(await awaitSettled(ROLLBACK_CAP_MS))) {
|
|
1411
|
+
try {
|
|
1412
|
+
c.interrupt?.();
|
|
1413
|
+
}
|
|
1414
|
+
catch { /* 中断失败照旧走退役路径 */ }
|
|
1415
|
+
if (!(await awaitSettled(DRAIN_INTERRUPT_GRACE_MS))) {
|
|
1416
|
+
// ⚠️ **放弃前再补一发中断**(CR 第六十轮 major):驱动把 ROLLBACK 拆成「准备」与
|
|
1417
|
+
// 「执行」两段,第一次 interrupt 若落在准备阶段之前,会被随后的准备清掉 —— 之后它
|
|
1418
|
+
// 照样进入原生执行,而我们这边已经放弃并退役(连 close 都解不了卡)。此时已经不再
|
|
1419
|
+
// 等它交回(结论已经是「未能确认」),补发的目的只是别把原生线程留在里面。
|
|
1420
|
+
try {
|
|
1421
|
+
c.interrupt?.();
|
|
1422
|
+
}
|
|
1423
|
+
catch { /* 同上 */ }
|
|
1424
|
+
// 中断之后仍不交回:卡在不可中断的原生点上(连 close 都不能让进程退出)。
|
|
1425
|
+
poison(`ROLLBACK 在 ${ROLLBACK_CAP_MS}ms 内未返回,中断后 ${DRAIN_INTERRUPT_GRACE_MS}ms 内仍未交回:事务也许仍然开着`);
|
|
1426
|
+
beganTx.delete(token);
|
|
1427
|
+
return 'unconfirmed';
|
|
1428
|
+
}
|
|
1429
|
+
}
|
|
1430
|
+
if (rejected)
|
|
1431
|
+
throw failed;
|
|
1432
|
+
beganTx.delete(token);
|
|
1433
|
+
return 'confirmed';
|
|
1434
|
+
}
|
|
1435
|
+
catch (e) {
|
|
1436
|
+
// BEGIN 都没成功 → 本来就没有事务可回滚(可以是 BEGIN 被快照拒这类响亮失败),不是「状态未知」。
|
|
1437
|
+
// 挂住的那次 ROLLBACK 若**迟到成功**,事务其实已经收尾 —— 但本实例状态已经不可信
|
|
1438
|
+
//(退役由 poison 负责、连接即将关闭),不因迟到结果恢复可用性,保持「未能确认」。
|
|
1439
|
+
// ⚠️ **「登记过」不等于「事务真的开过」**(Codex PR#81 第五十四轮 P2):`beganTx` 在发出
|
|
1440
|
+
// BEGIN 之前登记(为了兜住「原生已成功、结果交回才拒」),若驱动的拒绝发生在原生执行
|
|
1441
|
+
// **之前**,事务根本没开过 —— 直接按「回滚未确认」毒化会把原错误换成退役文案,后续所有
|
|
1442
|
+
// 操作都被拒。这里问一次连接(两次 `txid_current()` 同值才是有活动事务):
|
|
1443
|
+
// 确认没有 → 按「无可回滚」交回原错误;探针失败 / 有事务 → 保守毒化(与旧行为一致)。
|
|
1444
|
+
let unconfirmed = beganTx.has(token);
|
|
1445
|
+
if (unconfirmed) {
|
|
1446
|
+
const active = await probeActiveTransaction();
|
|
1447
|
+
if (active === false) {
|
|
1448
|
+
unconfirmed = false;
|
|
1449
|
+
}
|
|
1450
|
+
else {
|
|
1451
|
+
poison('ROLLBACK 未能确认:它可能根本没有执行,事务也许仍然开着');
|
|
1452
|
+
}
|
|
1453
|
+
}
|
|
1454
|
+
beganTx.delete(token);
|
|
1455
|
+
return unconfirmed ? 'unconfirmed' : 'none';
|
|
1456
|
+
}
|
|
1457
|
+
};
|
|
1458
|
+
/**
|
|
1459
|
+
* 他人库指纹(`init` 专用):命中返回成因文案,否则 null。
|
|
1460
|
+
*
|
|
1461
|
+
* ⚠️ **只认「我们绝不可能产出」的形态**(2026-11-14,历史审查 PR#4 复核实测):
|
|
1462
|
+
* ① `schema_version` 没有 `version` 列 —— 我们的迁移第一版就建了它;
|
|
1463
|
+
* ② 有表但 `schema_version` **一行都没有** —— 我们的每次迁移都插一行,留下的库至少有一条;
|
|
1464
|
+
* ③ 记录的最大版本**超过本 CLI 已知的最新迁移** —— 我们从未写过这个号;
|
|
1465
|
+
* ④ `schema_version` **不是一个基表**(view 等)—— 我们只会建表,且求值外来 view 有副作用。
|
|
1466
|
+
* ⚠️ **不要**改回「声明表出现声明外的列就拒绝」(首版这么写,全量回归当场抓到):
|
|
1467
|
+
* 多列/少列是**既有契约里的 schema 漂移**(`db tables` 只警告不失败、README 明写),
|
|
1468
|
+
* 一条手工 `ALTER TABLE … ADD COLUMN` 会被误判成他人库,`store init` 直接不可用。
|
|
1469
|
+
* 代价如实记录:一条**版本号恰好落在我们范围内**的外来库仍可能被当成「旧版 CLI 建的库」,
|
|
1470
|
+
* 那时 init 不建表、只按 `storeTablesWarnings` 点名缺表 —— 不会往里写业务数据。
|
|
1471
|
+
*/
|
|
1472
|
+
const detectForeignStore = async () => {
|
|
1473
|
+
// ⚠️ 先看**对象类型**再谈内容(CodeRabbit PR#74 第五轮):`information_schema.tables` 把
|
|
1474
|
+
// view 也算作表,下面那条 `MAX(version)` 会把 view 本体当查询执行 —— 一条
|
|
1475
|
+
// `CREATE VIEW schema_version AS SELECT CAST('x' AS INTEGER)` 就能让 init 报
|
|
1476
|
+
// Conversion Error(internal),既绕开「他人库」归类,也违背「是 view 就不求值」的说法。
|
|
1477
|
+
// 本 CLI 从不把 schema_version 建成 view,所以「不是基表」本身就是他人库指纹。
|
|
1478
|
+
// ⚠️ 同上按大小写不敏感取(`"SCHEMA_VERSION"` view 同样会被下面那条按小写名的查询执行)。
|
|
1479
|
+
const kindRes = await store.execSql("SELECT table_name, table_type FROM information_schema.tables WHERE table_schema = 'main'");
|
|
1480
|
+
const svKind = objectKinds(kindRes
|
|
1481
|
+
.getRowObjectsJson()).find((o) => sameObjectName(o.name, 'schema_version'));
|
|
1482
|
+
if (svKind !== undefined && !isBaseTable(svKind)) {
|
|
1483
|
+
return `目标数据库不是本 CLI 创建的(schema_version 不是基表,实际是 ${svKind.type || '未知对象'}):${cfg.path}`;
|
|
1484
|
+
}
|
|
1485
|
+
const r = await store.execSql("SELECT table_name, column_name FROM information_schema.columns WHERE table_schema = 'main'");
|
|
1486
|
+
const cols = new Map();
|
|
1487
|
+
for (const row of r.getRowObjectsJson()) {
|
|
1488
|
+
// ⚠️ 表名键按大小写不敏感取的规则(Codex PR#76 第三轮):库里的 `"SCHEMA_VERSION"`
|
|
1489
|
+
// 表也要取到它自己的列,否则被误判成「缺少 version 列」。列名折叠同一规则。
|
|
1490
|
+
const t = String(row.table_name).replace(/[A-Z]/g, (c) => c.toLowerCase());
|
|
1491
|
+
const list = cols.get(t) ?? [];
|
|
1492
|
+
list.push(String(row.column_name));
|
|
1493
|
+
cols.set(t, list);
|
|
1494
|
+
}
|
|
1495
|
+
const svCols = cols.get('schema_version') ?? [];
|
|
1496
|
+
if (!svCols.some((c) => sameObjectName(c, 'version'))) {
|
|
1497
|
+
return `目标数据库不是本 CLI 创建的(schema_version 缺少 version 列,`
|
|
1498
|
+
+ `实际列:${svCols.join('、') || '无'}):${cfg.path}`;
|
|
1499
|
+
}
|
|
1500
|
+
const svRes = await store.execSql('SELECT COUNT(*) AS n, COALESCE(MAX(version), 0) AS v FROM schema_version');
|
|
1501
|
+
const rows = svRes.getRowObjectsJson();
|
|
1502
|
+
const n = Number(rows[0]?.n ?? 0);
|
|
1503
|
+
const v = Number(rows[0]?.v ?? 0);
|
|
1504
|
+
const latest = MIGRATIONS.reduce((m, x) => Math.max(m, x.version), 0);
|
|
1505
|
+
if (n === 0) {
|
|
1506
|
+
return `目标数据库不是本 CLI 创建的(库中有表,但 schema_version 没有任何记录):${cfg.path}`;
|
|
1507
|
+
}
|
|
1508
|
+
if (v > latest) {
|
|
1509
|
+
return `目标数据库不是本 CLI 创建的(schema_version 记录版本 ${v},`
|
|
1510
|
+
+ `高于本 CLI 已知的最新迁移 ${latest}):${cfg.path}`;
|
|
1511
|
+
}
|
|
1512
|
+
return null;
|
|
239
1513
|
};
|
|
240
1514
|
// ⚠️ store 自引用:方法体经 store.execSql 调用(见下方契约)。断言目标**必须含
|
|
241
1515
|
// execSql**(第四轮 H 组实测:`as unknown as Store` 下方法体内所有 store.execSql
|
|
@@ -246,38 +1520,57 @@ export async function createDuckDbStore(cfg, mode, deps = {}) {
|
|
|
246
1520
|
if (mode === 'ro')
|
|
247
1521
|
throw usage('只读模式下不能初始化(需 rw 模式)');
|
|
248
1522
|
// 他人库防线(spec §6.1):已有表但无 schema_version → 拒绝。
|
|
249
|
-
const existing = await store.execSql(`SELECT table_name FROM information_schema.tables WHERE table_schema = 'main'`);
|
|
250
|
-
const
|
|
251
|
-
.
|
|
252
|
-
|
|
1523
|
+
const existing = await store.execSql(`SELECT table_name, table_type FROM information_schema.tables WHERE table_schema = 'main'`);
|
|
1524
|
+
const kinds = objectKinds(existing
|
|
1525
|
+
.getRowObjectsJson());
|
|
1526
|
+
const names = kinds.map((k) => k.name);
|
|
1527
|
+
// ⚠️ 存在性与类型都按大小写不敏感判(Codex PR#76):DuckDB 标识符大小写不敏感,
|
|
1528
|
+
// 一条 `"SCHEMA_VERSION"` view 会被下面的 `MAX(version)` 按小写名执行。
|
|
1529
|
+
const svKind = kinds.find((k) => sameObjectName(k.name, 'schema_version'));
|
|
1530
|
+
if (names.length > 0 && svKind === undefined) {
|
|
253
1531
|
// ⚠️ 他人库 → store_not_initialized、退出码 1(spec §8.2 成因 6)——不是 usage。
|
|
254
1532
|
const err = new Error(`目标数据库不是本 CLI 创建的(含表 ${names.join(', ')}):${cfg.path}`);
|
|
255
1533
|
err.kind = 'store_not_initialized';
|
|
256
1534
|
err.hint = '目标数据库不是本 CLI 创建的,请换 --db 路径';
|
|
257
1535
|
throw err;
|
|
258
1536
|
}
|
|
259
|
-
|
|
1537
|
+
// ⚠️ 「有 schema_version」不是身份证明(2026-11-14,历史审查 PR#4 复核):实测造一个
|
|
1538
|
+
// `{secret 表, schema_version(version INTEGER) 空表}` 的外来库,init 直接报 ok 并往里
|
|
1539
|
+
// 建表。指纹判据见 `detectForeignStore` 的注释(三条「我们不可能产出」的形态)。
|
|
1540
|
+
if (svKind !== undefined) {
|
|
1541
|
+
const foreign = await detectForeignStore();
|
|
1542
|
+
if (foreign !== null) {
|
|
1543
|
+
const err = new Error(foreign);
|
|
1544
|
+
err.kind = 'store_not_initialized';
|
|
1545
|
+
err.hint = '目标数据库不是本 CLI 创建的,请换 --db 路径';
|
|
1546
|
+
throw err;
|
|
1547
|
+
}
|
|
1548
|
+
}
|
|
1549
|
+
const cur = svKind !== undefined
|
|
260
1550
|
? await store.execSql('SELECT COALESCE(MAX(version), 0) AS v FROM schema_version')
|
|
261
1551
|
: null;
|
|
262
1552
|
const v = cur === null ? 0 : Number(cur.getRowObjectsJson()[0].v);
|
|
263
1553
|
for (const m of MIGRATIONS.filter((x) => x.version > v).sort((a, b) => a.version - b.version)) {
|
|
264
|
-
|
|
265
|
-
|
|
1554
|
+
// ⚠️ 迁移走**托管事务**(CR 第三十八轮 major #1):裸 `execSql('BEGIN')` 不登记归属 ——
|
|
1555
|
+
// 迁移暂停时另一条链的 `transaction()` 会再发一条 BEGIN(DuckDB 拒绝它并把迁移的事务
|
|
1556
|
+
// 标成 aborted),随后它的失败处理回滚掉迁移事务,`init` 恢复后就在事务外执行语句。
|
|
1557
|
+
// 托管事务把准入、归属登记、回滚与退役全部收敛到同一处。
|
|
1558
|
+
// 迁移失败 → 事务回滚且**不推进**版本 → 下次 init 重放该迁移(验收 19/20)。
|
|
1559
|
+
await store.transaction(async () => {
|
|
266
1560
|
await m.up((sql) => store.execSql(sql).then(() => undefined));
|
|
267
1561
|
await store.execSql('INSERT INTO schema_version (version) VALUES (?)', [m.version]);
|
|
268
|
-
|
|
269
|
-
}
|
|
270
|
-
catch (e) {
|
|
271
|
-
// 迁移失败:回滚且**不推进**版本 —— 下次 init 重放该迁移(验收 19/20)。
|
|
272
|
-
await safeRollback();
|
|
273
|
-
throw e;
|
|
274
|
-
}
|
|
1562
|
+
});
|
|
275
1563
|
}
|
|
276
1564
|
},
|
|
277
1565
|
async tables() {
|
|
1566
|
+
// ⚠️ 返回**声明的名字**(Codex PR#76 第四轮实测):DuckDB 标识符大小写不敏感,
|
|
1567
|
+
// `"SCHEMA_VERSION"` 与 `schema_version` 是同一个对象;调用方(store status/init、
|
|
1568
|
+
// sync)拿这些名字去 `assertTable`(按声明名查)并比对声明集 —— 原样返回大写名会让
|
|
1569
|
+
// `store status` 在 `count('SCHEMA_VERSION')` 上抛 usage(实测退出码 2),
|
|
1570
|
+
// 并把它同时报成「声明有而库中无」与「库中有而声明无」。未声明的对象原样返回。
|
|
278
1571
|
const r = await store.execSql(`SELECT table_name FROM information_schema.tables WHERE table_schema = 'main'`);
|
|
279
1572
|
return r.getRowObjectsJson()
|
|
280
|
-
.map((x) => String(x.table_name)).sort();
|
|
1573
|
+
.map((x) => tableByName(String(x.table_name))?.name ?? String(x.table_name)).sort();
|
|
281
1574
|
},
|
|
282
1575
|
async count(table) {
|
|
283
1576
|
assertTable(table);
|
|
@@ -288,47 +1581,186 @@ export async function createDuckDbStore(cfg, mode, deps = {}) {
|
|
|
288
1581
|
async upsert(table, rows) {
|
|
289
1582
|
const t = assertTable(table);
|
|
290
1583
|
assertRows(t, rows);
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
//
|
|
294
|
-
//
|
|
295
|
-
|
|
1584
|
+
// ⚠️ **关闭必须先于归属**:事务回调里 `close()` 之后再写,`inTx` 尚未复位 —— 先判归属
|
|
1585
|
+
// 会把它误诊成"并发竞争"(internal + 串行化提示),而真实原因是连接已经关了,正确
|
|
1586
|
+
// 分类是 `usage`(Codex PR#81 第二十五轮 P3,实测:`count` 走 `execSql` 报 usage,
|
|
1587
|
+
// `upsert`/`delete` 报 internal —— 同一个 Store 上两种说法)。
|
|
1588
|
+
if (closed)
|
|
1589
|
+
throw usage('数据库连接已关闭');
|
|
1590
|
+
// ⚠️ 退役连接不接受新工作(CR 第六十三轮 major):自动事务的 BEGIN 同样不发。
|
|
1591
|
+
if (poisoned !== undefined)
|
|
1592
|
+
throw poisonedError(poisoned);
|
|
1593
|
+
rejectEndedContext();
|
|
1594
|
+
// ⚠️ `inTx` 的语义是「本实例上有事务开着」,不等于「调用者在那个事务里」——
|
|
1595
|
+
// 归属必须由 `assertTxOwnership` 判(历史审查 PR#4 复核)。
|
|
1596
|
+
// 入口这一处只做**快速失败**(省掉开自己那条事务的功夫);真正的判定在
|
|
1597
|
+
// `doUpsert` 贴着 INSERT 的那次 —— 见那里的注释。
|
|
1598
|
+
if (inTx) {
|
|
1599
|
+
assertTxOwnership();
|
|
1600
|
+
if (txToken === undefined)
|
|
1601
|
+
return doUpsert(t, rows);
|
|
1602
|
+
const done = trackWrite(txToken);
|
|
1603
|
+
try {
|
|
1604
|
+
return await doUpsert(t, rows);
|
|
1605
|
+
}
|
|
1606
|
+
finally {
|
|
1607
|
+
done();
|
|
1608
|
+
}
|
|
1609
|
+
}
|
|
1610
|
+
// ⚠️ 自动事务也**登记归属**(CodeRabbit PR#81 第八轮 major):只打 BEGIN 不置 `inTx`
|
|
1611
|
+
// 时,另有调用方在此期间 `transaction()`,它的 BEGIN 会撞上「事务已开」而失败 ——
|
|
1612
|
+
// 那条失败路径若再 ROLLBACK,就会把**这里的**活动事务回滚掉,之后的批次落在事务外、
|
|
1613
|
+
// 最终 COMMIT 失败留下部分写入。登记后用单一令牌管住:同一实例上事实并存两种事务
|
|
1614
|
+
// 从根上不存在(并发的第二次写会在 `assertTxOwnership` 被拒,且它自己的 BEGIN 不会
|
|
1615
|
+
// 发出、也就没有任何人会回滚别人的事务)。
|
|
1616
|
+
// 登记与整个(同步段 + 后续批次)放在同一个异步上下文里:`doUpsert` 内部贴着 INSERT
|
|
1617
|
+
// 的 `assertTxOwnership` 要有令牌才认得出「这是自己那条自动事务」。
|
|
1618
|
+
const token = newTxToken();
|
|
1619
|
+
// 自动事务也是「写操作」:BEGIN 之前登记,且要求**别的**写操作都已落定(CR 第三十七轮
|
|
1620
|
+
// major #6)。⚠️ 准入必须排在 `txEpoch += 1` / `inTx = true` **之前** —— 否则被拒的
|
|
1621
|
+
// 自动事务也会推进代号,把正在执行的外部写误判成「跨代」。
|
|
1622
|
+
const op = enterWriteOp();
|
|
1623
|
+
let n;
|
|
1624
|
+
let beginAttempted = false;
|
|
296
1625
|
try {
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
1626
|
+
admitBegin(op);
|
|
1627
|
+
inTx = true;
|
|
1628
|
+
txToken = token;
|
|
1629
|
+
txEpoch += 1;
|
|
1630
|
+
// ⚠️ BEGIN / 数据语句 / COMMIT 全在**带令牌的上下文**里(闸门下移到 `execSql` 之后,
|
|
1631
|
+
// 事务控制语句也要过它,见那里的注释);`doUpsert` 内部贴着 INSERT 的归属检查同样
|
|
1632
|
+
// 靠这个上下文认出「这是自己那条自动事务」。
|
|
1633
|
+
n = await alsTx.run(token, async () => {
|
|
1634
|
+
beginAttempted = true;
|
|
1635
|
+
beganTx.add(token); // 理由同 `transaction()`:驱动可能在原生 BEGIN 成功后拒绝交回结果
|
|
1636
|
+
await execSql('BEGIN', [], { txControl: true });
|
|
1637
|
+
const written = await doUpsert(t, rows);
|
|
1638
|
+
await commitOrRefuse(token);
|
|
1639
|
+
return written;
|
|
1640
|
+
});
|
|
300
1641
|
}
|
|
301
1642
|
catch (e) {
|
|
302
|
-
|
|
1643
|
+
// ⚠️ 准入失败(还没碰过 BEGIN)不得回滚(CR 第三十九轮 major #1):那条 ROLLBACK 会发到
|
|
1644
|
+
// 一条**别人的**事务上(手开事务)并拖慢拒绝。只有 BEGIN 已尝试过才进入回滚处理 ——
|
|
1645
|
+
// 「原生 BEGIN 成功了但结果交回被拒」的情形由 `beginAttempted` + `beganTx` 一起兜住。
|
|
1646
|
+
if (!isRefusal(e, token) && beginAttempted) {
|
|
1647
|
+
// 回滚未能确认时必须带回状态(CR 第四十二轮 major):rethrow 原错误,但让它自己说出
|
|
1648
|
+
// 「写入状态不可信」。已确认回滚 / 无可回滚的路径一字不改。
|
|
1649
|
+
throw annotateUnconfirmedRollback(e, await rollbackInTx(token));
|
|
1650
|
+
}
|
|
303
1651
|
throw e;
|
|
304
1652
|
}
|
|
1653
|
+
finally {
|
|
1654
|
+
inTx = false;
|
|
1655
|
+
txToken = undefined;
|
|
1656
|
+
leaveWriteOp(op);
|
|
1657
|
+
releaseTokenState(token);
|
|
1658
|
+
}
|
|
1659
|
+
return n;
|
|
305
1660
|
},
|
|
306
1661
|
delete: del,
|
|
307
1662
|
async transaction(fn) {
|
|
308
|
-
|
|
1663
|
+
// ⚠️ `closed` 必须先于**任何** ALS 使用(Codex PR#81 第十八轮 P2,实测确认):
|
|
1664
|
+
// `alsTx.run()` 会把 `close()` 里 disable 过的实例**重新启用**(Node 的全局 storageList
|
|
1665
|
+
// 强引用它),而这条失败路径不会再 disable —— 迟到的 `transaction()` 每次都在攒一个
|
|
1666
|
+
// 启用态上下文。`upsert()` 本来就是这么防的,这里对齐。
|
|
1667
|
+
if (closed)
|
|
1668
|
+
throw usage('数据库连接已关闭');
|
|
1669
|
+
// ⚠️ **退役连接不接受新事务**(CR 第六十三轮 major):连 BEGIN 都不发 —— 否则失败
|
|
1670
|
+
// 路径的回滚收尾会把原错误换成「回滚未确认」,并在退役连接上再做原生探测。
|
|
1671
|
+
if (poisoned !== undefined)
|
|
1672
|
+
throw poisonedError(poisoned);
|
|
1673
|
+
rejectEndedContext();
|
|
1674
|
+
// ⚠️ 用异步上下文区分两种「事务已开」(CodeRabbit PR#81 第十七轮 minor,实测复现):
|
|
1675
|
+
// · 调用方**就在所有者上下文里**(`fn` 里的 `tx.transaction`,令牌一致)→ 真嵌套,usage;
|
|
1676
|
+
// · 调用方是**另一条异步链**(令牌不一致)→ 并发竞争,internal。
|
|
1677
|
+
// 原先只对「自动事务被撞」分开报,显式事务被撞时一律落到
|
|
1678
|
+
// `usage('不得嵌套事务')` —— 实测竞争方拿到退出码 2 的「参数写错」信号,且没有串行化提示。
|
|
1679
|
+
// 令牌现在一律是对象:区分依据是**异步上下文里的令牌是否相等**,不是令牌类型。
|
|
1680
|
+
const owns = inTx && alsTx.getStore() === txToken;
|
|
1681
|
+
if (inTx && !owns) {
|
|
1682
|
+
throw Object.assign(new Error('本实例上有一条事务尚未提交,此时另一条异步链不能开始新事务 —— '
|
|
1683
|
+
+ '请让同一 Store 实例上的操作串行 await'), {
|
|
1684
|
+
kind: 'internal',
|
|
1685
|
+
hint: '让同一个 Store 实例上的操作串行执行:不要用 Promise.all 并行调用 upsert/delete/transaction/query/count',
|
|
1686
|
+
});
|
|
1687
|
+
}
|
|
1688
|
+
if (owns)
|
|
309
1689
|
throw usage('不得嵌套事务');
|
|
310
|
-
|
|
1690
|
+
// ⚠️ **BEGIN 的准入**(CR 第三十七轮 major #6):写操作(`delete` / 自动事务)还在进行时
|
|
1691
|
+
// 不许开事务 —— 单连接上的语句按实际执行顺序进入事务,写操作的 DELETE/INSERT 可能已经
|
|
1692
|
+
// 提交而其结果还没交回;此时开事务会让它报「跨代失败」、行却真的改过了。
|
|
1693
|
+
admitBegin();
|
|
1694
|
+
// ⚠️ 归属登记必须**先于** `BEGIN` 的 await(CodeRabbit PR#81 第七轮 major):原先
|
|
1695
|
+
// `inTx` 在 BEGIN 落定之后才置位,BEGIN 这条 await 期间它的外部写会被放行,随后的
|
|
1696
|
+
// 语句排进本事务、回滚时静默消失(实测:BEGIN 挂住时外部 delete 返回成功、行没了)。
|
|
1697
|
+
const token = newTxToken();
|
|
311
1698
|
inTx = true;
|
|
1699
|
+
txToken = token;
|
|
1700
|
+
txEpoch += 1;
|
|
312
1701
|
try {
|
|
313
|
-
// ⚠️
|
|
314
|
-
//
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
1702
|
+
// ⚠️ BEGIN **失败也要发 ROLLBACK**(2026-11-16 实测裁定,拒绝 CodeRabbit 第八轮的建议):
|
|
1703
|
+
// 手开事务存在时嵌套 BEGIN 会被 DuckDB 拒绝,**而它同时已把那条事务标记为 aborted**
|
|
1704
|
+
// —— 数据在任何后续动作之前就已经废了。此时两种收尾的差别只在「失败是否可见」:
|
|
1705
|
+
// · 发 ROLLBACK:连接恢复干净,之后调用方的 COMMIT 报 `no transaction is active`
|
|
1706
|
+
// (**响亮**地告诉它事务没了)—— 实测正是如此;
|
|
1707
|
+
// · 不发 ROLLBACK:调用方的 COMMIT 返回成功,但 DuckDB 静默丢弃该事务的全部写入
|
|
1708
|
+
// (实测:行数归零、无任何报错)—— 这才是"部分写入 + 静默丢数据"。
|
|
1709
|
+
// 所以这里保留 ROLLBACK;`safeRollback` 吞掉「根本没有事务」的次生错误。
|
|
1710
|
+
// aborted 的事务同样可被 ROLLBACK 收尾(DuckDB),外部语句污掉它的情形效果一致。
|
|
1711
|
+
// 真正要堵的是「BEGIN 根本不该发出」:自动事务已登记归属(见 `upsert`)、显式事务
|
|
1712
|
+
// 在 BEGIN 前登记 —— 支持路径上不会再出现第二条 BEGIN(用例见 duckdb.test 的两条)。
|
|
1713
|
+
// ⚠️ BEGIN / 回调 / COMMIT 全部在**带令牌的上下文**里:闸门在 `execSql`(事务控制
|
|
1714
|
+
// 语句也要过它),回调里的 `tx.upsert`/`tx.delete` 也靠这个上下文认得出
|
|
1715
|
+
// "这是事务内的写"(CodeRabbit PR#81 第十六轮)。
|
|
1716
|
+
return await alsTx.run(token, async () => {
|
|
1717
|
+
// 先登记「可能已开启」(CR 第三十八轮 major #7):驱动可能在原生 BEGIN **成功之后**
|
|
1718
|
+
// 才拒绝结果交回,此时 `beganTx` 若为空,后续 ROLLBACK 失败就不会触发退役 ——
|
|
1719
|
+
// 事务可能真的开着。登记后由成功的 COMMIT / ROLLBACK 负责清除。
|
|
1720
|
+
beganTx.add(token);
|
|
1721
|
+
await execSql('BEGIN', [], { txControl: true });
|
|
1722
|
+
// ⚠️ 真实投影而非 cast:WriteTx 类型上不含 query/init/close(spec §4.2.6 防线分层),
|
|
1723
|
+
// 运行时对象也不得携带 —— 直接传 store 的话 `Object.keys(tx)` 可枚举出 query。
|
|
1724
|
+
// ⚠️ `WriteTx` 是**回调作用域**的(CR 第三十八轮 major #4;契约写进 types.ts):
|
|
1725
|
+
// `const tx = await transaction(async (t) => t)` 把投影带出回调后,直接调用会变成
|
|
1726
|
+
// 一个 Store 别名(在 autocommit 里写),调用方却以为它还在事务里。每个方法入口
|
|
1727
|
+
// 都核对「当前异步上下文仍是本事务」。
|
|
1728
|
+
// ⚠️ **关闭必须先于归属**(Codex PR#81 第四十三轮 P2,探针 2026-11-20):`close()`
|
|
1729
|
+
// 会 `alsTx.disable()`,`getStore()` 随即变成 undefined —— 只看令牌会把「连接已关」
|
|
1730
|
+
// 误诊成「事务已结束」(internal),而 Store 自己的方法是 `usage`「数据库连接已关闭」。
|
|
1731
|
+
// 同一个坏状态两种分类 = Agent 拿到两种退出码(1 vs 2)。
|
|
1732
|
+
const assertProjection = () => {
|
|
1733
|
+
if (closed)
|
|
1734
|
+
throw usage('数据库连接已关闭');
|
|
1735
|
+
if (!inTx || alsTx.getStore() !== token)
|
|
1736
|
+
throw txEndedError();
|
|
1737
|
+
};
|
|
1738
|
+
// 方法一律 `async`:守卫的拒绝必须以 **rejected promise** 呈现(与类型契约一致),
|
|
1739
|
+
// 同步 throw 会让调用方在 `await` 之前就炸。
|
|
1740
|
+
const tx = {
|
|
1741
|
+
tables: async () => { assertProjection(); return store.tables(); },
|
|
1742
|
+
count: async (t) => { assertProjection(); return store.count(t); },
|
|
1743
|
+
upsert: async (t, rows) => { assertProjection(); return store.upsert(t, rows); },
|
|
1744
|
+
delete: async (t, w, p) => { assertProjection(); return store.delete(t, w, p); },
|
|
1745
|
+
transaction: async (f) => { assertProjection(); return store.transaction(f); },
|
|
1746
|
+
};
|
|
1747
|
+
const r = await fn(tx);
|
|
1748
|
+
await commitOrRefuse(token);
|
|
1749
|
+
return r;
|
|
1750
|
+
});
|
|
325
1751
|
}
|
|
326
1752
|
catch (e) {
|
|
327
|
-
|
|
1753
|
+
// ROLLBACK 也走 `execSql`:在令牌上下文里发,闸门才认得它属于本事务(若 BEGIN 都没
|
|
1754
|
+
// 成功,`safeRollback` 吞掉「没有事务」的次生错误)。⚠️ `commitOrRefuse` 抛出的拒绝
|
|
1755
|
+
// 已在身份集合里:回滚已由它负责,这里不再回滚第二次(CR 第三十六轮 major)。
|
|
1756
|
+
if (!isRefusal(e, token))
|
|
1757
|
+
throw annotateUnconfirmedRollback(e, await rollbackInTx(token));
|
|
328
1758
|
throw e;
|
|
329
1759
|
}
|
|
330
1760
|
finally {
|
|
331
1761
|
inTx = false;
|
|
1762
|
+
txToken = undefined;
|
|
1763
|
+
releaseTokenState(token);
|
|
332
1764
|
}
|
|
333
1765
|
},
|
|
334
1766
|
async query(sql, params) {
|
|
@@ -357,6 +1789,15 @@ export async function createDuckDbStore(cfg, mode, deps = {}) {
|
|
|
357
1789
|
inst.closeSync?.();
|
|
358
1790
|
}
|
|
359
1791
|
catch { /* 清理期错误不掩盖 */ }
|
|
1792
|
+
// ⚠️ 事务归属的 ALS 必须显式 `disable()`(Codex PR#81 P2,实测确认):执行过
|
|
1793
|
+
// `run()` 的实例会被 Node 的全局 `storageList` **强引用**,只关 DuckDB 不关它,
|
|
1794
|
+
// 反复「建 Store → 跑事务 → 关」的进程/测试会把实例一直攒着(本地 async_hooks
|
|
1795
|
+
// 后端实测:关掉 40 个 Store 后仍有 40 个 ALS 处于启用态),并拖慢之后每个异步资源
|
|
1796
|
+
// 的传播。`disable()` 幂等,包 try 防老运行时不支持。
|
|
1797
|
+
try {
|
|
1798
|
+
alsTx.disable();
|
|
1799
|
+
}
|
|
1800
|
+
catch { /* 不支持 disable 的运行时:忽略 */ }
|
|
360
1801
|
},
|
|
361
1802
|
};
|
|
362
1803
|
// ⚠️ 挂载契约见上方 execSql 注释:不可枚举 + writable + configurable(缺 configurable
|