Skip to content

Commit 6ac0c64

Browse files
anandgupta42claude
andcommitted
fix(ci): actually run the drivers unit suite, and stop misreporting a caller's own deadline
Second review wave on #1198. The two findings that matter are gaps in what runs and what gets blamed. **`packages/drivers` has never been tested in CI.** The package declares no scripts, no job sets it as a working directory, and the TypeScript job runs `bun test` from `packages/opencode` only. All 142 driver unit tests — the lock, timeout and read-only regressions this PR turns on — could fail without any job noticing. Added a `Run drivers unit suite` step to the `driver-e2e` job, and `packages/drivers/test/**` to the `drivers` path filter. **The DuckDB E2E step ran with a 5s per-test deadline.** Invoking `bun test` directly does not use the package's `test` script, so it took the CLI default of 5000ms — shorter than the driver's own 30s default open budget and the lock helper's 30s readiness budget. A step meant to prove a too-short deadline was removed was imposing one of its own. Now `--timeout 90000`, explicitly. **A deadline the caller set was reported as a broken client.** With `open_timeout_ms: 1` on the connection, `warehouse_test` said "the client on this machine is broken, nothing about your configuration is wrong, stop and report" — for a failure the connection's own setting caused and its own setting fixes. That is the same category error this PR exists to remove, pointing the other way. `resolveOpenTimeoutMs` now returns the source; a connection-scoped budget names itself in the message and classifies as `config_error`, while the default or the env var stays `driver_open_timeout` and infrastructure. **Also** - The raw-lock fallback in `categorizeConnectionError` matched `could not set lock` alone, which is generic enough to appear in an unrelated remote error — it would have told the user to close a local process over a warehouse fault. Now requires DuckDB's full shape (`could not set lock` *and* `conflicting lock`). - The `drivers` filter ignored `package.json`, `bun.lock` and `packages/drivers/package.json`, which govern whether the native binding is fetched at all. A change to those could break every real-DuckDB path with no real-DuckDB job running. - The lock helper's 30s readiness timer was never cleared, holding the event loop open for up to 30s per call after the last assertion. - The lock helper's child imported the driver outside its `try`, so a load failure surfaced as a bare unhandled rejection instead of the normalised `HOLD_FAILED` message. **Tests.** A retry-path case in `driver-security.test.ts` that fails the first open with DuckDB's *real* `Conflicting lock is held` text and asserts the READ_ONLY retry fires — the existing retry test used a fabricated `DUCKDB_LOCKED` string that the driver's original `.includes("locked")` already matched, so it could not have caught a regression in real-message detection. Ungated cases for the connection-scoped deadline classification and for not claiming another driver's lock-shaped error. E2E cases asserting the deadline message names its source, and that a connection-set deadline is `config_error` / not infrastructure while an env-set one stays infrastructure. Gates: typecheck 13/13; markers ok against `origin/main`; drivers 142 pass 0 fail; `test/altimate` 4224 pass 0 fail; gated E2E 21 pass 0 fail on six consecutive runs. Lint 5864 warnings / 1 error — the error is the pre-existing `consistent-return` in `packages/http-recorder/test/record-replay.test.ts`; the warnings are +2 against the branch baseline, both un-awaited `mock.module` calls in new tests, matching how every other `mock.module` in that file is written. Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01VqnuBDGkh1ZT65Ti7e6DHZ
1 parent 4c6d20e commit 6ac0c64

8 files changed

Lines changed: 190 additions & 30 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,13 @@ jobs:
6868
- 'packages/opencode/test/altimate/warehouse-test-duckdb-e2e.test.ts'
6969
- 'packages/opencode/test/altimate/duckdb-lock-helper.ts'
7070
- 'packages/opencode/src/altimate/tools/warehouse-test.ts'
71+
- 'packages/drivers/test/**'
72+
# These govern whether the native DuckDB binding is fetched at all
73+
# (`trustedDependencies`, and the pinned version). A change to them
74+
# can break every real-DuckDB test while touching no test file.
75+
- 'package.json'
76+
- 'bun.lock'
77+
- 'packages/drivers/package.json'
7178
dbt-tools:
7279
- 'packages/dbt-tools/**'
7380
installer:
@@ -294,6 +301,14 @@ jobs:
294301
- name: Install dependencies
295302
run: bun install
296303

304+
# `packages/drivers` declares no scripts and no job had it as a working
305+
# directory, so its 141 unit tests — including the driver's lock, timeout
306+
# and read-only regressions — never ran in CI at all. The main TypeScript
307+
# job runs `bun test` from `packages/opencode` only.
308+
- name: Run drivers unit suite
309+
run: bun test --timeout 60000
310+
working-directory: packages/drivers
311+
297312
- name: Run local driver E2E (DuckDB, SQLite, PostgreSQL)
298313
run: bun test test/altimate/drivers-e2e.test.ts
299314
working-directory: packages/opencode
@@ -308,8 +323,14 @@ jobs:
308323
# whole-directory run these would silently exercise a fake. With
309324
# ALTIMATE_DUCKDB_E2E=1 a missing or mocked driver fails the step rather
310325
# than skipping it.
326+
#
327+
# `--timeout` is explicit because invoking `bun test` directly does not use
328+
# the package's `test` script, so it would otherwise take the CLI default
329+
# of 5000ms — shorter than both the driver's 30s default open budget and
330+
# the lock helper's 30s readiness budget, which would reimpose exactly the
331+
# kind of too-short outer deadline this PR removes.
311332
- name: Run DuckDB store-open E2E (real store, no mocks)
312-
run: bun test test/altimate/duckdb-open-e2e.test.ts test/altimate/warehouse-test-duckdb-e2e.test.ts
333+
run: bun test --timeout 90000 test/altimate/duckdb-open-e2e.test.ts test/altimate/warehouse-test-duckdb-e2e.test.ts
313334
working-directory: packages/opencode
314335
env:
315336
ALTIMATE_DUCKDB_E2E: "1"

‎packages/drivers/src/duckdb.ts‎

Lines changed: 24 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -32,12 +32,20 @@ function positiveMs(value: unknown): number | undefined {
3232
return Number.isFinite(n) && n > 0 ? Math.min(n, MAX_TIMER_MS) : undefined
3333
}
3434

35-
function resolveOpenTimeoutMs(config: ConnectionConfig): number {
36-
return (
37-
positiveMs(config.open_timeout_ms) ??
38-
positiveMs(globalThis.process?.env?.["ALTIMATE_DUCKDB_OPEN_TIMEOUT_MS"]) ??
39-
DEFAULT_OPEN_TIMEOUT_MS
40-
)
35+
/**
36+
* Where the budget came from, which decides how a caller should read a
37+
* deadline failure: one the connection set is that connection's own doing and
38+
* is fixed by changing it, while the default or a machine-wide env var firing
39+
* says something about the machine instead.
40+
*/
41+
type TimeoutSource = "connection" | "env" | "default"
42+
43+
function resolveOpenTimeoutMs(config: ConnectionConfig): { ms: number; source: TimeoutSource } {
44+
const fromConfig = positiveMs(config.open_timeout_ms)
45+
if (fromConfig !== undefined) return { ms: fromConfig, source: "connection" }
46+
const fromEnv = positiveMs(globalThis.process?.env?.["ALTIMATE_DUCKDB_OPEN_TIMEOUT_MS"])
47+
if (fromEnv !== undefined) return { ms: fromEnv, source: "env" }
48+
return { ms: DEFAULT_OPEN_TIMEOUT_MS, source: "default" }
4149
}
4250
// altimate_change end
4351

@@ -52,7 +60,7 @@ export async function connect(config: ConnectionConfig): Promise<Connector> {
5260

5361
const dbPath = (config.path as string) ?? ":memory:"
5462
// altimate_change start — configurable open budget
55-
const openTimeoutMs = resolveOpenTimeoutMs(config)
63+
const { ms: openTimeoutMs, source: openTimeoutSource } = resolveOpenTimeoutMs(config)
5664
// altimate_change end
5765
let db: any
5866
let connection: any
@@ -176,8 +184,15 @@ export async function connect(config: ConnectionConfig): Promise<Connector> {
176184
`DuckDB store "${dbPath}" did not finish opening within ${openTimeoutMs}ms. ` +
177185
`This is a client-side deadline in the DuckDB driver, not a fault in the store ` +
178186
`— the open may simply be queued behind other work in this process. ` +
179-
`Raise the budget with this connection's open_timeout_ms (which takes ` +
180-
`priority) or ALTIMATE_DUCKDB_OPEN_TIMEOUT_MS if the machine is loaded.`,
187+
(openTimeoutSource === "connection"
188+
? // Named so callers can tell a self-inflicted deadline from one
189+
// they did not choose. Registry.categorizeConnectionError keys
190+
// off this phrase to report it as configuration rather than as
191+
// a broken client.
192+
`This deadline was set on this connection as open_timeout_ms=${openTimeoutMs}; ` +
193+
`raise or remove it.`
194+
: `Raise the budget with this connection's open_timeout_ms (which takes ` +
195+
`priority) or ALTIMATE_DUCKDB_OPEN_TIMEOUT_MS if the machine is loaded.`),
181196
),
182197
)
183198
}

‎packages/drivers/test/driver-security.test.ts‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -189,6 +189,50 @@ describe("DuckDB driver", () => {
189189
await connector.close()
190190
})
191191

192+
test("retries with READ_ONLY when the first open fails with DuckDB's real lock text", async () => {
193+
// The other retry test drives a fabricated "DUCKDB_LOCKED: file is locked"
194+
// string, which the driver's original `.includes("locked")` check already
195+
// matched. Only this one uses the message DuckDB actually emits, so only
196+
// this one would catch a regression that broke detection of a real lock
197+
// collision on the retry path.
198+
let attempts = 0
199+
const accessModes: Array<string | undefined> = []
200+
mock.module("duckdb", () => ({
201+
default: {
202+
Database: class {
203+
constructor(_path: string, optsOrCb: any, cb?: (err: Error | null) => void) {
204+
const opts = typeof optsOrCb === "function" ? undefined : optsOrCb
205+
const done = openCallback(optsOrCb, cb)
206+
accessModes.push(opts?.access_mode)
207+
attempts++
208+
if (attempts === 1) setTimeout(() => done(new Error(REAL_DUCKDB_LOCK_ERROR)), 0)
209+
else setTimeout(() => done(null), 0)
210+
}
211+
connect() {
212+
return {
213+
all: (_sql: string, cb: (err: Error | null, rows: any[]) => void) => {
214+
cb(null, [{ result: 1 }])
215+
},
216+
}
217+
}
218+
close(cb: any) {
219+
if (cb) cb(null)
220+
}
221+
},
222+
},
223+
}))
224+
225+
const { connect } = await import("../src/duckdb")
226+
const connector = await connect({ type: "duckdb", path: "/tmp/test.duckdb" })
227+
await connector.connect()
228+
229+
expect(attempts).toBe(2)
230+
expect(accessModes[0]).toBeUndefined()
231+
expect(accessModes[1]).toBe("READ_ONLY")
232+
233+
await connector.close()
234+
})
235+
192236
test("wraps a lock error on an explicitly read-only open, and does not retry it", async () => {
193237
// A caller that set `readonly` already gets READ_ONLY on the first open,
194238
// so there is nothing for the retry to try differently — DuckDB's file

‎packages/opencode/src/altimate/native/connections/registry.ts‎

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -285,15 +285,24 @@ export function categorizeConnectionError(e: unknown): string {
285285
// altimate_change start — categories for local-client faults
286286
// Checked before the generic "timeout"/"not found" rules below, which are
287287
// about the remote warehouse and would otherwise swallow these.
288-
if (msg.includes("did not finish opening")) return "driver_open_timeout"
289-
// "locked by another process" is the DuckDB driver's own wrapper. The other
290-
// two are DuckDB's raw text ("Could not set lock on file …: Conflicting lock
291-
// is held"), matched here as well so a lock that reaches this function
292-
// unwrapped is still classified rather than falling through to "other".
288+
if (msg.includes("did not finish opening")) {
289+
// A deadline the connection itself set is the connection's fault, and the
290+
// remedy is to raise or drop that setting. Reporting it as a broken client
291+
// — "stop and report, nothing about your config is wrong" — is the exact
292+
// mirror of the confusion this categorisation exists to remove. Only a
293+
// deadline the caller did not choose per-connection is infrastructure.
294+
return msg.includes("deadline was set on this connection") ? "config_error" : "driver_open_timeout"
295+
}
296+
// "locked by another process" is the DuckDB driver's own wrapper. The second
297+
// clause is DuckDB's raw text ("Could not set lock on file …: Conflicting
298+
// lock is held"), matched here as well so a lock that reaches this function
299+
// unwrapped is still classified rather than falling through to "other". Both
300+
// halves of that clause are required: "could not set lock" on its own is
301+
// generic enough to appear in an unrelated remote error, and claiming it
302+
// would tell the user to close a local process over a remote fault.
293303
if (
294304
msg.includes("locked by another process") ||
295-
msg.includes("conflicting lock") ||
296-
msg.includes("could not set lock")
305+
(msg.includes("could not set lock") && msg.includes("conflicting lock"))
297306
)
298307
return "store_locked"
299308
// altimate_change end

‎packages/opencode/test/altimate/connections.test.ts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,22 @@ describe("categorizeConnectionError: local-client faults", () => {
5151
expect(categorizeConnectionError(err)).toBe("driver_open_timeout")
5252
})
5353

54+
test("a deadline the connection set is a config fault, not a broken client", () => {
55+
const err = new Error(
56+
'DuckDB store "/tmp/w.duckdb" did not finish opening within 1ms. ' +
57+
"This deadline was set on this connection as open_timeout_ms=1; raise or remove it.",
58+
)
59+
expect(categorizeConnectionError(err)).toBe("config_error")
60+
expect(isInfrastructureFailure(categorizeConnectionError(err))).toBe(false)
61+
})
62+
63+
test("does not claim another driver's error just because it mentions a lock", () => {
64+
// "could not set lock" alone is generic enough to appear in an unrelated
65+
// remote failure; claiming it would tell the user to close a local process
66+
// over a warehouse-side fault.
67+
expect(categorizeConnectionError(new Error("ERROR: could not set lock timeout"))).not.toBe("store_locked")
68+
})
69+
5470
test("still classifies a real credentials failure as auth_failed", () => {
5571
expect(categorizeConnectionError(new Error("password authentication failed for user"))).toBe("auth_failed")
5672
})

‎packages/opencode/test/altimate/duckdb-lock-helper.ts‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -34,8 +34,11 @@ export async function holdWriteLock(storePath: string, scratchDir: string): Prom
3434
fs.writeFileSync(
3535
scriptPath,
3636
[
37-
`const { connect } = await import(${JSON.stringify(DRIVER_PATH)})`,
3837
`try {`,
38+
// Inside the try, so a driver that fails to load is reported through the
39+
// same HOLD_FAILED channel as any other failure rather than surfacing as
40+
// a bare unhandled rejection the parent has to guess at.
41+
` const { connect } = await import(${JSON.stringify(DRIVER_PATH)})`,
3942
` const c = await connect({ type: "duckdb", path: process.argv[2] })`,
4043
` await c.connect()`,
4144
// A real write, so the lock is unambiguously a writer's.
@@ -73,15 +76,21 @@ export async function holdWriteLock(storePath: string, scratchDir: string): Prom
7376
throw new Error(`lock holder exited without taking the lock: ${err || "(no output)"}`)
7477
})()
7578

76-
const timeout = new Promise<never>((_, reject) =>
77-
setTimeout(() => reject(new Error("lock holder did not report READY within 30s")), 30_000),
78-
)
79+
// The handle is kept so it can be cleared: an un-cleared timer holds the
80+
// event loop open, which would make the whole test process sit for the full
81+
// 30s after its last assertion, once per call.
82+
let timer: ReturnType<typeof setTimeout> | undefined
83+
const timeout = new Promise<never>((_, reject) => {
84+
timer = setTimeout(() => reject(new Error("lock holder did not report READY within 30s")), 30_000)
85+
})
7986

8087
try {
8188
await Promise.race([ready, timeout])
8289
} catch (e) {
8390
child.kill()
8491
throw e
92+
} finally {
93+
if (timer) clearTimeout(timer)
8594
}
8695

8796
return {

‎packages/opencode/test/altimate/duckdb-open-e2e.test.ts‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -129,15 +129,31 @@ describe("DuckDB driver: opening a real store", () => {
129129
// The old message was `Timed out opening DuckDB database "<path>"`, which
130130
// reads as "the store is broken" and sent investigators after the file.
131131
expect(message).toContain("not a fault in the store")
132-
expect(message).toContain("ALTIMATE_DUCKDB_OPEN_TIMEOUT_MS")
132+
})
133+
134+
ddbTest("a deadline the connection set says so, so it is not read as a broken client", async () => {
135+
// The remedy differs by source, so the message has to name it. A budget the
136+
// connection chose is fixed by changing that connection; the default firing
137+
// says something about the machine instead.
138+
const c = await connect({ type: "duckdb", path: storePath, open_timeout_ms: 1 })
139+
const message = await messageFrom(() => c.connect())
140+
expect(message).toContain("deadline was set on this connection as open_timeout_ms=1")
141+
// It must NOT point at the env var, which does not override a per-connection
142+
// setting and so would not fix anything here.
143+
expect(message).not.toContain("ALTIMATE_DUCKDB_OPEN_TIMEOUT_MS")
133144
})
134145

135146
ddbTest("the open deadline is tunable by environment variable", async () => {
136147
const prev = process.env["ALTIMATE_DUCKDB_OPEN_TIMEOUT_MS"]
137148
process.env["ALTIMATE_DUCKDB_OPEN_TIMEOUT_MS"] = "1"
138149
try {
139150
const c = await connect({ type: "duckdb", path: storePath })
140-
expect(await messageFrom(() => c.connect())).toContain("did not finish opening within 1ms")
151+
const message = await messageFrom(() => c.connect())
152+
expect(message).toContain("did not finish opening within 1ms")
153+
// Sourced from the environment, not the connection, so the message points
154+
// at the knobs that would actually change it.
155+
expect(message).toContain("ALTIMATE_DUCKDB_OPEN_TIMEOUT_MS")
156+
expect(message).not.toContain("deadline was set on this connection")
141157
} finally {
142158
if (prev === undefined) delete process.env["ALTIMATE_DUCKDB_OPEN_TIMEOUT_MS"]
143159
else process.env["ALTIMATE_DUCKDB_OPEN_TIMEOUT_MS"] = prev

‎packages/opencode/test/altimate/warehouse-test-duckdb-e2e.test.ts‎

Lines changed: 37 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -93,14 +93,36 @@ describe("warehouse.test against a real DuckDB store", () => {
9393
ddbTest("reports a broken client as an infrastructure failure, not a failed connection", async () => {
9494
Registry.reset()
9595
// An unreachably small open budget stands in for any local fault that
96-
// stops the store opening. The point of the assertion is the *shape* of
97-
// the report: a caller must be able to tell this apart from a bad
98-
// password without parsing prose.
96+
// stops the store opening. It is set through the environment, NOT on the
97+
// connection: a deadline the connection itself chose is that connection's
98+
// own doing and is covered by the next test. The point of the assertion is
99+
// the *shape* of the report — a caller must be able to tell this apart from
100+
// a bad password without parsing prose.
101+
const prev = process.env["ALTIMATE_DUCKDB_OPEN_TIMEOUT_MS"]
102+
process.env["ALTIMATE_DUCKDB_OPEN_TIMEOUT_MS"] = "1"
103+
try {
104+
Registry.setConfigs({ local: { type: "duckdb", path: storePath } })
105+
const result = await warehouseTest("local")
106+
expect(result.connected).toBe(false)
107+
expect(result.infrastructure).toBe(true)
108+
expect(result.error_category).toBe("driver_open_timeout")
109+
} finally {
110+
if (prev === undefined) delete process.env["ALTIMATE_DUCKDB_OPEN_TIMEOUT_MS"]
111+
else process.env["ALTIMATE_DUCKDB_OPEN_TIMEOUT_MS"] = prev
112+
}
113+
})
114+
115+
ddbTest("a deadline the connection itself set is a configuration fault, not infrastructure", async () => {
116+
// The mirror of the bug this PR fixes. Telling a caller "your client is
117+
// broken, stop and report it" when they set `open_timeout_ms: 1` themselves
118+
// is the same category error as reporting a broken install as a bad
119+
// password — it just points the wrong way.
120+
Registry.reset()
99121
Registry.setConfigs({ local: { type: "duckdb", path: storePath, open_timeout_ms: 1 } })
100122
const result = await warehouseTest("local")
101123
expect(result.connected).toBe(false)
102-
expect(result.infrastructure).toBe(true)
103-
expect(result.error_category).toBe("driver_open_timeout")
124+
expect(result.error_category).toBe("config_error")
125+
expect(result.infrastructure).toBe(false)
104126
})
105127

106128
ddbTest("does not mark a genuine configuration mistake as infrastructure", async () => {
@@ -169,8 +191,16 @@ describe("warehouse.test against a real DuckDB store", () => {
169191
expect(ok.title).toContain("OK")
170192

171193
Registry.reset()
172-
Registry.setConfigs({ local: { type: "duckdb", path: storePath, open_timeout_ms: 1 } })
173-
const broken = await tool.execute({ name: "local" }, ctx)
194+
const prev = process.env["ALTIMATE_DUCKDB_OPEN_TIMEOUT_MS"]
195+
process.env["ALTIMATE_DUCKDB_OPEN_TIMEOUT_MS"] = "1"
196+
let broken: Awaited<ReturnType<typeof tool.execute>>
197+
try {
198+
Registry.setConfigs({ local: { type: "duckdb", path: storePath } })
199+
broken = await tool.execute({ name: "local" }, ctx)
200+
} finally {
201+
if (prev === undefined) delete process.env["ALTIMATE_DUCKDB_OPEN_TIMEOUT_MS"]
202+
else process.env["ALTIMATE_DUCKDB_OPEN_TIMEOUT_MS"] = prev
203+
}
174204
// The whole point: a reader of this transcript — human or model — must not
175205
// be able to mistake a broken client for the model getting something
176206
// wrong, or for a connection that needs its credentials fixed.

0 commit comments

Comments
 (0)