A local-first personal finance app
[AI] api: attach stable error codes that survive the worker boundary (#8437)
Matiss Janis Aboltinsa862d463d769
diff --git a/packages/desktop-client/src/components/filters/SavedFilterMenuButton.tsx b/packages/desktop-client/src/components/filters/SavedFilterMenuButton.tsxindex fda77c3c82..765d74c8a4 100644--- a/packages/desktop-client/src/components/filters/SavedFilterMenuButton.tsx+++ b/packages/desktop-client/src/components/filters/SavedFilterMenuButton.tsx@@ -80,7 +80,7 @@ export function SavedFilterMenuButton({});if (response.error) {- setErr(response.error.message);+ setErr(response.error.message ?? null);setNameOpen(true);return;}@@ -126,7 +126,7 @@ export function SavedFilterMenuButton({});if (response.error) {- setErr(response.error.message);+ setErr(response.error.message ?? null);setNameOpen(true);return;}@@ -152,7 +152,7 @@ export function SavedFilterMenuButton({});if (response.error) {- setErr(response.error.message);+ setErr(response.error.message ?? null);setNameOpen(true);return;}diff --git a/packages/docs/docs/api/index.md b/packages/docs/docs/api/index.mdindex cbaa577452..4fa021a956 100644--- a/packages/docs/docs/api/index.md+++ b/packages/docs/docs/api/index.md@@ -114,6 +114,56 @@ The browser build is fully self-contained: the Web Worker and its WebAssembly anThe engine uses `SharedArrayBuffer`, so the page that runs the API must be served **cross-origin isolated**: over HTTPS, with `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp`. This is a hosting/server requirement (it cannot be bundled away). See [Enabling SharedArrayBuffer Access](../troubleshooting/shared-array-buffer.md). In local development, set the same headers on your dev server (for example via a small Vite middleware plugin).:::+## Handling Errors++When an API method fails, the rejected error usually carries a human-readable `message` in English. For the most common connection and download failures, the error also carries a stable, machine-readable `code`. Use `code` when your app needs to react to a specific kind of failure (for example, to show its own translated message) — matching on the text of `message` is fragile because the wording can change between releases.++```js+try {+ await api.init({+ dataDir: '/some/path',+ serverURL: 'http://localhost:5006',+ password: 'hunter2',+ });+ await api.downloadBudget('1cfdbb80-6274-49bf-b0c2-737235a4c81f');+} catch (error) {+ switch (error.code) {+ case 'network-failure':+ case 'network':+ // The server could not be reached. Check the serverURL.+ break;+ case 'invalid-password':+ // The server password is wrong.+ break;+ case 'budget-not-found':+ // No budget file matches the given sync ID.+ break;+ default:+ // Fall back to the message text.+ console.error(error.message);+ }+}+```++These are the codes for the common failures:++| Code | Meaning |+| ------------------------ | ---------------------------------------------------------------------------------------------------- |+| `network-failure` | The server could not be reached — the `serverURL` is wrong, or the server is offline or unreachable. |+| `network` | Same as `network-failure`, reported by the download and encryption-key checks. |+| `invalid-password` | The server password given to `init` is wrong. |+| `token-expired` | The session token given to `init` is invalid or has expired. |+| `unauthorized` | The client is not logged in to the server. |+| `budget-not-found` | No budget file matches the given sync ID. |+| `missing-key` | The budget file is end-to-end encrypted, and no encryption password was given. |+| `decrypt-failure` | The budget file could not be decrypted — the encryption password is wrong. |+| `old-key-style` | The budget file uses an old, unsupported encryption key style. |+| `out-of-sync-migrations` | The budget file needs a newer version of Actual — update the API package. |++:::note+`code` is present for the common connection and download failures listed above. Other errors may only carry a `message`, so always keep a fallback.+:::+## Writing Data ImportersIf you are using another app, like YNAB or Mint, you might want to migrate your data into Actual. Right now, Actual officially supports [importing YNAB4 data](../migration/ynab4.md) and [importing nYNAB data](../migration/nynab.md) (and it works very well). But if you want to import all of your data into Actual, you can write a custom importer.diff --git a/packages/loot-core/src/platform/client/connection/index-types.ts b/packages/loot-core/src/platform/client/connection/index-types.tsindex 80160f9263..811ee6d441 100644--- a/packages/loot-core/src/platform/client/connection/index-types.ts+++ b/packages/loot-core/src/platform/client/connection/index-types.ts@@ -8,6 +8,18 @@ import type { ServerEvents } from '#types/server-events';export declare function init(socket?: Worker | MessagePort): Promise<unknown>;export type Init = typeof init;+/** Error shape posted by the backend when a handler rejects. */+export type ConnectionError = {+ /** Stable, machine-readable failure code (e.g. 'network-failure') */+ code?: string;+ name?: string;+ cause?: unknown;+} & (+ | { type: 'APIError'; message: string }+ // A ServerError can be built from a rejection without a message+ | { type: 'ServerError'; message?: string }+);+/*** Send a command to the browser server.*@@ -25,14 +37,7 @@ export declare function send<K extends keyof Handlers>(options: { catchErrors: true },): Promise<| { data: Awaited<ReturnType<Handlers[K]>>; error: undefined }- | {- data: undefined;- error: {- type: 'APIError' | 'ServerError';- message: string;- cause?: unknown;- };- }+ | { data: undefined; error: ConnectionError }>;export declare function send<K extends keyof Handlers>(name: K,@@ -54,14 +59,7 @@ export declare function sendCatch<K extends keyof Handlers>(args?: Parameters<Handlers[K]>[0],): Promise<| { data: Awaited<ReturnType<Handlers[K]>>; error: undefined }- | {- data: undefined;- error: {- type: 'APIError' | 'ServerError';- message: string;- cause?: unknown;- };- }+ | { data: undefined; error: ConnectionError }>;export type SendCatch = typeof sendCatch;diff --git a/packages/loot-core/src/platform/server/connection/errors.ts b/packages/loot-core/src/platform/server/connection/errors.tsnew file mode 100644index 0000000000..43816920e6--- /dev/null+++ b/packages/loot-core/src/platform/server/connection/errors.ts@@ -0,0 +1,99 @@+export type TransferableError = {+ type: string;+ message?: string;+ // Stable, machine-readable failure code (e.g. 'network-failure',+ // 'invalid-password', 'budget-not-found'). Sourced from the error's+ // `reason`/`code` and guaranteed to survive the boundary.+ code?: string;+ name?: string;+ stack?: string;+ cause?: unknown;+};++function getField(error: unknown, field: string): unknown {+ return typeof error === 'object' && error !== null+ ? (error as Record<string, unknown>)[field]+ : undefined;+}++function getStringField(error: unknown, field: string): string | undefined {+ const value = getField(error, field);+ return typeof value === 'string' ? value : undefined;+}++// Internal errors carry their machine-readable slug on `reason` (PostError,+// SyncError, …) or `code` (BankSyncError, Node system errors); `errno` covers+// Emscripten filesystem errors.+function getErrorCode(error: unknown): string | undefined {+ const code =+ getField(error, 'reason') ??+ getField(error, 'code') ??+ getField(error, 'errno');++ if (typeof code === 'string') {+ return code;+ }+ if (typeof code === 'number') {+ return String(code);+ }+ return undefined;+}++function coerceError(error: unknown): TransferableError {+ if (getField(error, 'type') === 'APIError') {+ return error as TransferableError;+ }++ return {+ type: 'ServerError',+ message: getStringField(error, 'message'),+ code: getErrorCode(error),+ name: getStringField(error, 'name'),+ cause: error,+ };+}++// A reduced shape that is always structured-cloneable: `cause` (the original+// error) is dropped, everything kept is a plain string.+function toCloneableError(error: TransferableError): TransferableError {+ return {+ type: error.type,+ message: error.message,+ code: error.code,+ name: error.name,+ stack: getStringField(error.cause, 'stack'),+ };+}++// Post a rejected handler result in the envelope the request expects, and+// return the serialized error for the caller's reporting. If the structured+// clone inside `post` fails — the error held a non-cloneable value, e.g. an+// Emscripten ErrnoError carrying methods — retry with a plain, always+// cloneable shape so the real failure isn't replaced by a DataCloneError.+export function postErrorReply(+ post: (message: unknown) => void,+ request: { id: unknown; name: string; catchErrors?: boolean },+ rejection: unknown,+): TransferableError {+ const { id, name, catchErrors } = request;+ const error = coerceError(rejection);++ function buildMessage(err: TransferableError) {+ if (name.startsWith('api/')) {+ // The API is newer and does automatically forward errors+ return { type: 'reply', id, error: err };+ }+ if (catchErrors) {+ return { type: 'reply', id, result: { error: err, data: null } };+ }+ return { type: 'error', id, error: err };+ }++ try {+ post(buildMessage(error));+ } catch {+ post(buildMessage(toCloneableError(error)));+ }++ return error;+}diff --git a/packages/loot-core/src/platform/server/connection/index.electron.ts b/packages/loot-core/src/platform/server/connection/index.electron.tsindex 04d5b20749..74de4dad09 100644--- a/packages/loot-core/src/platform/server/connection/index.electron.ts+++ b/packages/loot-core/src/platform/server/connection/index.electron.ts@@ -4,16 +4,9 @@ import { logger } from '#platform/server/log';import { APIError } from '#server/errors';import { isMutating, runHandler } from '#server/mutators';+import { postErrorReply } from './errors';import type * as T from './index-types';-function coerceError(error) {- if (error.type && error.type === 'APIError') {- return error;- }-- return { type: 'ServerError', message: error.message, cause: error };-}-export const init: T.Init = function (_socketName, handlers) {process.parentPort.on('message', ({ data }) => {const { id, name, args, undoTag, catchErrors } = data;@@ -35,25 +28,11 @@ export const init: T.Init = function (_socketName, handlers) {});},nativeError => {- const error = coerceError(nativeError);-- if (name.startsWith('api/')) {- // The API is newer and does automatically forward- // errors- process.parentPort.postMessage({- type: 'reply',- id,- error,- });- } else if (catchErrors) {- process.parentPort.postMessage({- type: 'reply',- id,- result: { error, data: null },- });- } else {- process.parentPort.postMessage({ type: 'error', id, error });- }+ const error = postErrorReply(+ message => process.parentPort.postMessage(message),+ { id, name, catchErrors },+ nativeError,+ );if (error.type === 'ServerError' && name !== 'api/load-budget') {captureException(nativeError);diff --git a/packages/loot-core/src/platform/server/connection/index.ts b/packages/loot-core/src/platform/server/connection/index.tsindex 39c57750c8..57f9e6151e 100644--- a/packages/loot-core/src/platform/server/connection/index.ts+++ b/packages/loot-core/src/platform/server/connection/index.ts@@ -4,6 +4,7 @@ import { logger } from '#platform/server/log';import { APIError } from '#server/errors';import { isMutating, runHandler } from '#server/mutators';+import { postErrorReply } from './errors';import type * as T from './index-types';function getGlobalObject() {@@ -23,14 +24,6 @@ function getGlobalObject() {getGlobalObject().__globalServerChannel = null;-function coerceError(error) {- if (error.type && error.type === 'APIError') {- return error;- }-- return { type: 'ServerError', message: error.message, cause: error };-}-export const init: T.Init = function (serverChn, handlers) {const serverChannel = serverChn as Window;getGlobalObject().__globalServerChannel = serverChannel;@@ -66,21 +59,11 @@ export const init: T.Init = function (serverChn, handlers) {});},nativeError => {- const error = coerceError(nativeError);-- if (name.startsWith('api/')) {- // The API is newer and does automatically forward- // errors- serverChannel.postMessage({ type: 'reply', id, error });- } else if (catchErrors) {- serverChannel.postMessage({- type: 'reply',- id,- result: { error, data: null },- });- } else {- serverChannel.postMessage({ type: 'error', id, error });- }+ const error = postErrorReply(+ message => serverChannel.postMessage(message),+ { id, name, catchErrors },+ nativeError,+ );// Only report internal errorsif (error.type === 'ServerError') {diff --git a/packages/loot-core/src/server/api.ts b/packages/loot-core/src/server/api.tsindex 1b0bc0069d..0701df1c84 100644--- a/packages/loot-core/src/server/api.ts+++ b/packages/loot-core/src/server/api.ts@@ -42,7 +42,7 @@ import { isTrackingBudget } from './budget/actions';import * as cloudStorage from './cloud-storage';import type { RemoteFile } from './cloud-storage';import * as db from './db';-import { APIError } from './errors';+import { APIError, withErrorCode } from './errors';import { runMutator } from './mutators';import * as prefs from './prefs';import * as sheet from './sheet';@@ -170,7 +170,7 @@ handlers['api/load-budget'] = async function ({ id }) {} else {connection.send('show-budgets');- throw new Error(getSyncError(error, id));+ throw withErrorCode(new Error(getSyncError(error, id)), error);}}};@@ -189,12 +189,18 @@ handlers['api/download-budget'] = async function ({ syncId, password }) {if (!localBudget) {const files = await handlers['get-remote-files']();if (!files) {- throw new Error('Could not get remote files');+ throw withErrorCode(+ new Error('Could not get remote files'),+ 'network-failure',+ );}const file = files.find(f => f.groupId === syncId);if (!file) {- throw new Error(- `Budget "${syncId}" not found. Check the sync id of your budget in the Advanced section of the settings page.`,+ throw withErrorCode(+ new Error(+ `Budget "${syncId}" not found. Check the sync id of your budget in the Advanced section of the settings page.`,+ ),+ 'budget-not-found',);}@@ -206,8 +212,11 @@ handlers['api/download-budget'] = async function ({ syncId, password }) {// Set the e2e encryption keysif (activeFile.encryptKeyId) {if (!password) {- throw new Error(- `File ${activeFile.name} is encrypted. Please provide a password.`,+ throw withErrorCode(+ new Error(+ `File ${activeFile.name} is encrypted. Please provide a password.`,+ ),+ 'missing-key',);}@@ -216,7 +225,10 @@ handlers['api/download-budget'] = async function ({ syncId, password }) {password,});if (result.error) {- throw new Error(getTestKeyError(result.error));+ throw withErrorCode(+ new Error(getTestKeyError(result.error)),+ result.error.reason,+ );}}@@ -225,8 +237,11 @@ handlers['api/download-budget'] = async function ({ syncId, password }) {await handlers['load-budget']({ id: localBudget.id });const result = await handlers['sync-budget']();if (result.error) {- throw new Error(- getSyncError(result.error.reason, localBudget.id, result.error.meta),+ throw withErrorCode(+ new Error(+ getSyncError(result.error.reason, localBudget.id, result.error.meta),+ ),+ result.error.reason,);}return;@@ -238,7 +253,10 @@ handlers['api/download-budget'] = async function ({ syncId, password }) {});if (result.error) {logger.log('Full error details', result.error);- throw new Error(getDownloadError(result.error));+ throw withErrorCode(+ new Error(getDownloadError(result.error)),+ result.error.reason,+ );}await handlers['load-budget']({ id: result.id });};@@ -256,7 +274,10 @@ handlers['api/sync'] = async function () {const { id } = prefs.getPrefs();const result = await handlers['sync-budget']();if (result.error) {- throw new Error(getSyncError(result.error.reason, id, result.error.meta));+ throw withErrorCode(+ new Error(getSyncError(result.error.reason, id, result.error.meta)),+ result.error.reason,+ );}};@@ -295,7 +316,7 @@ handlers['api/bank-sync'] = async function (args) {const errors = allErrors.filter(e => e != null);if (errors.length > 0) {- throw new Error(getBankSyncError(errors[0]));+ throw withErrorCode(new Error(getBankSyncError(errors[0])), errors[0].code);}};diff --git a/packages/loot-core/src/server/errors.ts b/packages/loot-core/src/server/errors.tsindex 0cba4b7f3d..e304f401e5 100644--- a/packages/loot-core/src/server/errors.ts+++ b/packages/loot-core/src/server/errors.ts@@ -90,6 +90,20 @@ export function APIError(return { type: 'APIError', message: msg, meta };}+/**+ * Tag an error with a stable, machine-readable failure code (e.g.+ * 'network-failure', 'invalid-password', 'budget-not-found'). The code is+ * kept when the error crosses the worker boundary (see+ * `#platform/server/connection`), so API consumers can branch on `err.code`+ * instead of parsing the English message.+ */+export function withErrorCode<E extends Error>(+ error: E,+ code: string | undefined,+): E & { code?: string } {+ return code == null ? error : Object.assign(error, { code });+}+export function FileDownloadError(reason: string,meta?: {diff --git a/packages/loot-core/src/server/main.ts b/packages/loot-core/src/server/main.tsindex 58373eb95c..b27be83cac 100644--- a/packages/loot-core/src/server/main.ts+++ b/packages/loot-core/src/server/main.ts@@ -19,6 +19,7 @@ import { app as dashboardApp } from './dashboard/app';import * as db from './db';import * as encryption from './encryption';import { app as encryptionApp } from './encryption/app';+import { withErrorCode } from './errors';import { app as filtersApp } from './filters/app';import { app as forecastApp } from './forecast/app';import { app as formulasApp } from './formulas/app';@@ -291,21 +292,30 @@ export async function init(config: InitConfig) {if (!user || user.tokenExpired === true) {// Clear invalid tokenawait runHandler(handlers['subscribe-set-token'], { token: '' });- throw new Error(- 'Authentication failed: invalid or expired session token',+ throw withErrorCode(+ new Error('Authentication failed: invalid or expired session token'),+ 'token-expired',);}if (user.offline === true) {// Clear token since we can't validateawait runHandler(handlers['subscribe-set-token'], { token: '' });- throw new Error('Authentication failed: server offline or unreachable');+ throw withErrorCode(+ new Error('Authentication failed: server offline or unreachable'),+ 'network-failure',+ );}} else if ('password' in config && config.password) {const result = await runHandler(handlers['subscribe-sign-in'], {password: config.password,});if (result?.error) {- throw new Error(`Authentication failed: ${result.error}`);+ // `result.error` is already a machine-readable slug (e.g.+ // 'invalid-password', 'network-failure')+ throw withErrorCode(+ new Error(`Authentication failed: ${result.error}`),+ result.error,+ );}}} else {diff --git a/upcoming-release-notes/stable-api-error-codes.md b/upcoming-release-notes/stable-api-error-codes.mdnew file mode 100644index 0000000000..26f16afc3c--- /dev/null+++ b/upcoming-release-notes/stable-api-error-codes.md@@ -0,0 +1,6 @@+---+category: Enhancements+authors: [MatissJanis]+---++Common API failures now include a stable code so apps built on the API can show their own clear message for each kind of failure.