fix(errors): unify backend error protocol and preserve db detail

This commit is contained in:
miracle authored and GitHub committed 2026-08-05 17:25:21 +08:00
1 parent f1617bbd87
commit c8c40ba839
24 files changed
+1197 -182

No files matched your search

+108 -1
View File
@@ -240,6 +240,23 @@ describe("backend error translation", () => {
expect(translateBackendError(t, error)).toBe(`${t(error.messageKey)}\n\n${error.detail}`);
});
test("shows a native adapter code with the DuckDB detail", () => {
const t = translatorFor("en");
const error = {
version: 1,
code: "DBX-JDBC-4001",
messageKey: "backendErrors.jdbc.sqlFailed",
messageParams: { stage: "execute" },
source: "jdbcAgent",
operationOutcome: "unknown",
origin: { subsystem: "database", adapter: "native", driver: "duckdb" },
diagnostics: { category: "sql", stage: "execute", adapterCode: "duckdb_execute_failed" },
detail: "Catalog Error: Table missing_table does not exist",
} as const;
expect(translateBackendError(t, error)).toBe(`${t(error.messageKey, error.messageParams)}\n\n[duckdb_execute_failed] ${error.detail}`);
});
test("hides internal Agent error data from structured error details", () => {
const t = translatorFor("zh-CN");
const detail = 'driver: bad connection\nDBX_AGENT_ERROR_DATA:{"category":null,"agentSessionId":"session-1"}';
@@ -262,7 +279,7 @@ describe("backend error translation", () => {
["non-finite params", { messageParams: { retryAfter: Number.POSITIVE_INFINITY } }],
["non-string detail", { detail: 42 }],
["object detail", { detail: { message: "database failure" } }],
["unknown source", { source: "http" }],
["non-string source", { source: 42 }],
["unknown outcome", { operationOutcome: "completed" }],
])("rejects malformed structured envelopes with %s", (_name, override) => {
expect(
@@ -278,12 +295,102 @@ describe("backend error translation", () => {
).toBeNull();
});
test("accepts unknown compatibility sources and extensible origins", () => {
const error = normalizeBackendError({
version: 1,
code: "DBX-DB-4001",
messageKey: "backendErrors.jdbc.sqlFailed",
messageParams: { stage: "execute" },
source: "nativeDatabase",
operationOutcome: "unknown",
origin: { subsystem: "database", adapter: "native", driver: "postgresql" },
detail: "relation missing_table does not exist",
});
expect(error?.source).toBe("nativeDatabase");
expect(error?.origin?.driver).toBe("postgresql");
});
test("falls back to legacy text for plain HTTP and Tauri failures", () => {
const t = translatorFor("zh-CN");
const error = new BackendErrorException("legacy backend failure");
expect(error.backendError.code).toBe("DBX-LEGACY-0001");
expect(translateBackendError(t, error)).toBe(`${t("backendErrors.legacy")}\n\nlegacy backend failure`);
});
test("preserves JSON envelopes carried by strings and Error messages", () => {
const envelope = {
version: 1,
code: "DBX-JDBC-4001",
messageKey: "backendErrors.jdbc.sqlFailed",
messageParams: { stage: "execute" },
source: "jdbcAgent",
operationOutcome: "unknown",
detail: "relation missing_table does not exist",
} as const;
expect(normalizeBackendError(JSON.stringify(envelope))).toEqual(envelope);
expect(normalizeBackendError(new Error(JSON.stringify(envelope)))).toEqual(envelope);
});
test("retains bounded diagnostics from unknown rejection objects", () => {
const error = new BackendErrorException({ reason: "database worker returned a vendor diagnostic" });
expect(error.backendError.code).toBe("DBX-LEGACY-0001");
expect(error.backendError.detail).toBe("database worker returned a vendor diagnostic");
expect(new BackendErrorException({ reason: "x".repeat(70_000) }).backendError.detail).toHaveLength(64 * 1024);
});
test("normalizes structured errors across Error realms and module copies", () => {
const envelope = {
version: 1,
code: "DBX-JDBC-5001",
messageKey: "backendErrors.jdbc.protocolFailed",
messageParams: {},
source: "jdbcAgent" as const,
operationOutcome: "unknown" as const,
detail: "connection reset by peer",
};
const copiedError = Object.assign(new Error("Backend request failed"), {
name: "BackendErrorException",
backendError: envelope,
});
const workerError = { name: "BackendErrorException", message: JSON.stringify(envelope) };
expect(normalizeBackendError(copiedError)).toEqual(envelope);
expect(normalizeBackendError(workerError)).toEqual(envelope);
});
test("does not recurse forever through cyclic error wrappers", () => {
const self: Record<string, unknown> = {};
self.error = self;
expect(normalizeBackendError(self)).toBeNull();
expect(() => new BackendErrorException(self)).not.toThrow();
const first: Record<string, unknown> = {};
const second: Record<string, unknown> = {};
first.backendError = second;
second.error = first;
expect(normalizeBackendError(first)).toBeNull();
expect(() => new BackendErrorException(first)).not.toThrow();
});
test("stops at a finite wrapper depth", () => {
let wrapper: Record<string, unknown> = { error: { message: "deep legacy error" } };
for (let index = 0; index < 32; index += 1) wrapper = { backendError: wrapper };
expect(normalizeBackendError(wrapper)).toBeNull();
});
test("does not stringify a structured envelope as [object Object]", () => {
expect(
formatError({
version: 1,
code: "DBX-JDBC-5001",
messageKey: "backendErrors.jdbc.protocolFailed",
messageParams: {},
source: "jdbcAgent",
operationOutcome: "unknown",
}),
).toBe("DBX-JDBC-5001");
});
});
// Matching on message text only works while both sides agree on the wording, so
+4 -1
View File
@@ -128,7 +128,10 @@ function translateStructuredBackendError(t: BackendErrorTranslate, error: Backen
const translated = t(error.messageKey, error.messageParams);
const summary = translated !== error.messageKey ? translated : t("backendErrors.unknown");
const detail = error.detail ? sanitizeBackendErrorMessage(error.detail).trim() : undefined;
return detail && detail !== summary ? `${summary}\n\n${detail}` : summary;
const rawAdapterCode = error.diagnostics?.adapterCode;
const adapterCode = typeof rawAdapterCode === "string" && /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(rawAdapterCode) ? rawAdapterCode : undefined;
const diagnosticDetail = detail && adapterCode ? `[${adapterCode}] ${detail}` : (detail ?? adapterCode);
return diagnosticDetail && diagnosticDetail !== summary ? `${summary}\n\n${diagnosticDetail}` : summary;
}
export function translateBackendError(t: BackendErrorTranslate, error: unknown): string {