actual-mcp-server 0.16.1 → 0.16.5

package/README.md

@@ -774,7 +774,7 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.16.1 | **Tool Count:** 74 (verified LibreChat-compatible)
+**Version:** 0.16.5 | **Tool Count:** 74 (verified LibreChat-compatible)
 
 ## Sponsor
 

package/dist/src/actualConnection.js

@@ -2,6 +2,9 @@ import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import api from '@actual-app/api';
+import { loadBudgetTracked } from './lib/budgetLoader.js';
+import { withApiLock } from './lib/apiLock.js';
+import { withOpTimeout } from './lib/opTimeout.js';
 import logger from './logger.js';
 import config from './config.js';
 import { connectionPool } from './lib/ActualConnectionPool.js';
@@ -24,6 +27,11 @@ export async function connectToActual() {
         return;
     }
     initializing = true;
+    // #396: reset before each attempt. It was set on failure and NEVER cleared, so once the
+    // silent-success bug is fixed and a bad load throws routinely, a single failure would poison
+    // every later session open for the process lifetime: a concurrent caller arriving while
+    // `initializing` is true rethrows whatever was left here.
+    initializationError = null;
     try {
         const SERVER_URL = config.ACTUAL_SERVER_URL;
         const PASSWORD = config.ACTUAL_PASSWORD;
@@ -36,20 +44,35 @@ export async function connectToActual() {
         if (!fs.existsSync(DATA_DIR))
             fs.mkdirSync(DATA_DIR, { recursive: true });
         log.info(`Initializing Actual API with dataDir=${DATA_DIR}`);
-        await api.init({
-            dataDir: DATA_DIR,
-            serverURL: SERVER_URL,
-            password: PASSWORD,
+        // #396: this is the SIXTH budget load site, and it is production reachable. Revision 0 of
+        // that ticket claimed it was `--test-actual-connection` only; it is not.
+        // `connectToActualForSession` below falls through to this function whenever
+        // USE_CONNECTION_POOL=false (a documented, supported variable), and httpServer calls it on
+        // every HTTP session open. It used to hand-write the download and record the loaded syncId
+        // UNCONDITIONALLY, so it had none of the guarantees the other five sites have.
+        //
+        // The lock is acquired HERE, around init plus load only, mirroring
+        // ActualConnectionPool.getConnection. Never around the `while (initializing)` spin-wait
+        // above: that would hold the mutex while waiting for its holder and deadlock. No caller of
+        // this function holds the api lock, so this acquisition is safe.
+        //
+        // This is NOT behaviour neutral, and that is intended: the download becomes bounded by
+        // ACTUAL_OP_TIMEOUT_MS with abandon-not-cancel semantics, and becomes a registered load that
+        // later lock acquisitions wait for. Both match what the pool sites already do.
+        await withApiLock(async () => {
+            // #396 review: BOUND the init. It was unbounded here before, which was survivable only
+            // because this call held no lock. Now that it does, an unbounded stalled login would never
+            // settle, `.finally(release)` would never run, and the process-global api mutex would be
+            // wedged permanently for every session: the exact #270 class. Both pool sites already bound
+            // their `api.init` this way, and this was the only `api.init` in the repo that did not.
+            await withOpTimeout(() => api.init({
+                dataDir: DATA_DIR,
+                serverURL: SERVER_URL,
+                password: PASSWORD,
+            }), 'connectToActual init');
+            log.info(`Downloading budget with sync ID: ${BUDGET_SYNC_ID}`);
+            await loadBudgetTracked(BUDGET_SYNC_ID, BUDGET_PASSWORD);
         });
-        log.info(`Downloading budget with sync ID: ${BUDGET_SYNC_ID}`);
-        // According to official docs, downloadBudget accepts optional second parameter for E2E encryption
-        if (BUDGET_PASSWORD) {
-            const apiWithOptions = api;
-            await apiWithOptions.downloadBudget(BUDGET_SYNC_ID, { password: BUDGET_PASSWORD });
-        }
-        else {
-            await api.downloadBudget(BUDGET_SYNC_ID);
-        }
         if (TEST_ACTUAL_CONNECTION) {
             logger.info('Test flag detected (--test-actual-connection) — closing Actual session.');
             // Prefer the documented shutdown method only

package/dist/src/lib/ActualConnectionPool.js

@@ -17,6 +17,8 @@ import path from 'path';
 import os from 'os';
 import fs from 'fs';
 import { isApiInitialized, setApiInitialized } from './apiState.js';
+import { withApiLock } from './apiLock.js';
+import { loadBudgetTracked } from './budgetLoader.js';
 import { withOpTimeout } from './opTimeout.js';
 const DEFAULT_DATA_DIR = path.resolve(os.homedir() || '.', '.actual');
 class ActualConnectionPool {
@@ -237,27 +239,40 @@ class ActualConnectionPool {
             fs.mkdirSync(DATA_DIR, { recursive: true });
         }
         try {
-            // Bound the session-open init/download (#270): this is the HTTP exposure.
-            // A stalled upstream here would otherwise hang session open unbounded and,
-            // because the api singleton is process-global, wedge other sessions too.
-            await withOpTimeout(() => api.init({
-                dataDir: DATA_DIR,
-                serverURL: SERVER_URL,
-                password: PASSWORD,
-            }), 'pool init');
-            logger.info(`[ConnectionPool] Downloading budget for session: ${sessionId}`);
-            if (BUDGET_PASSWORD) {
-                const apiWithOptions = api;
-                await withOpTimeout(() => apiWithOptions.downloadBudget(BUDGET_SYNC_ID, { password: BUDGET_PASSWORD }), 'pool downloadBudget');
-            }
-            else {
-                await withOpTimeout(() => api.downloadBudget(BUDGET_SYNC_ID), 'pool downloadBudget');
-            }
-            // Mark the singleton as live only AFTER the budget is downloaded (#270):
-            // setting it before downloadBudget left a poisoning window where the
-            // adapter's pool-cooperation branch could reuse a connection whose budget
-            // never loaded (a stalled/failed download would leak isApiInitialized=true).
-            setApiInitialized(true);
+            // #390 round 2: hold the api mutex across init + download.
+            //
+            // Recording the loaded budget and checking it inside the lock only NARROWED the race
+            // while this mutator stayed outside it. Reproduced: a pooled read passed the
+            // precondition, parked at an await still holding the lock, a new session opened here on
+            // a different budget, and the first session's raw call then executed against it. The
+            // window is not small: it is the whole duration of an operation, and since #378 made the
+            // drain sequential, the whole duration of a batch, with one check at the start.
+            //
+            // Safe against the non-reentrant mutex: the two callers of getConnection
+            // (actualConnection's session-open helper and switchBudget's slow path) are both OUTSIDE
+            // any withApiLock block. switchBudget's own downloadBudget takes the lock separately and
+            // has already released it before it reaches here.
+            await withApiLock(async () => {
+                // Bound the session-open init/download (#270): this is the HTTP exposure.
+                // A stalled upstream here would otherwise hang session open unbounded and,
+                // because the api singleton is process-global, wedge other sessions too.
+                await withOpTimeout(() => api.init({
+                    dataDir: DATA_DIR,
+                    serverURL: SERVER_URL,
+                    password: PASSWORD,
+                }), 'pool init');
+                logger.info(`[ConnectionPool] Downloading budget for session: ${sessionId}`);
+                // #390: the shared tracked loader, not a hand-written download. It clears the record
+                // BEFORE starting and keeps an abandoned load registered, so a session-open download that
+                // outruns ACTUAL_OP_TIMEOUT_MS cannot silently re-point the singleton later.
+                await loadBudgetTracked(BUDGET_SYNC_ID, BUDGET_PASSWORD, 'pool downloadBudget');
+                // Mark the singleton as live only AFTER the budget is downloaded (#270):
+                // setting it before downloadBudget left a poisoning window where the
+                // adapter's pool-cooperation branch could reuse a connection whose budget
+                // never loaded (a stalled/failed download would leak isApiInitialized=true).
+                setApiInitialized(true);
+            }); // #390: end of the api-mutex block. Everything after this is pool bookkeeping and
+            // touches no singleton state, so it does not need the lock.
             conn = {
                 sessionId,
                 initialized: true,
@@ -276,17 +291,29 @@ class ActualConnectionPool {
         catch (err) {
             logger.error(`[ConnectionPool] Failed to initialize connection for session ${sessionId}:`, err);
             // Clean up the failed connection attempt
-            // Try to shutdown the API to leave it in a clean state for the next attempt
-            try {
+            // Try to shutdown the API to leave it in a clean state for the next attempt.
+            //
+            // #390 round 3: UNDER THE MUTEX, like the init above it. Locking the mutator and leaving
+            // its compensating mutator unlocked closes nothing: reproduced as this cleanup's
+            // api.shutdown() firing while ANOTHER session's operation was in flight inside the lock,
+            // so that operation observed a torn-down api. The lock is re-acquired rather than held
+            // across the whole try, because the init block released it on the way out and this
+            // function is never called from inside a lock (both callers are outside one).
+            // #393 review: the lock ITSELF can reject now (it settles an abandoned budget load on
+            // acquisition), and this is a CLEANUP path. If that rejection escaped, `setApiInitialized(false)`
+            // and the connections.delete below would be skipped and the caller would receive
+            // "abandoned budget load timed out" instead of the real session-open failure. Cleanup
+            // must not be able to fail louder than the thing it is cleaning up after, so the whole
+            // acquisition is swallowed here, not just the shutdown call.
+            await withApiLock(async () => {
                 const maybeApi = api;
                 if (typeof maybeApi.shutdown === 'function') {
                     await maybeApi.shutdown();
                     logger.debug(`[ConnectionPool] Cleaned up failed connection for session: ${sessionId}`);
                 }
-            }
-            catch (cleanupErr) {
+            }).catch((cleanupErr) => {
                 logger.debug(`[ConnectionPool] Error during cleanup (ignoring): ${cleanupErr}`);
-            }
+            });
             // Singleton is back to torn-down state regardless of cleanup outcome.
             setApiInitialized(false);
             // Ensure this session is not in the connections map
@@ -312,22 +339,23 @@ class ActualConnectionPool {
             fs.mkdirSync(DATA_DIR, { recursive: true });
         }
         try {
-            // Bound the session-open init/download (#270), same as getConnection.
-            await withOpTimeout(() => api.init({
-                dataDir: DATA_DIR,
-                serverURL: SERVER_URL,
-                password: PASSWORD,
-            }), 'pool init');
-            if (BUDGET_PASSWORD) {
-                const apiWithOptions = api;
-                await withOpTimeout(() => apiWithOptions.downloadBudget(BUDGET_SYNC_ID, { password: BUDGET_PASSWORD }), 'pool downloadBudget');
-            }
-            else {
-                await withOpTimeout(() => api.downloadBudget(BUDGET_SYNC_ID), 'pool downloadBudget');
-            }
-            // Mark live only after a successful download (#270): avoids the poisoning
-            // window where a stalled/failed download would leak isApiInitialized=true.
-            setApiInitialized(true);
+            // #390 round 2: same reasoning as getConnection above; this mutates the same
+            // process-global singleton, so it takes the same mutex.
+            await withApiLock(async () => {
+                // Bound the session-open init/download (#270), same as getConnection.
+                await withOpTimeout(() => api.init({
+                    dataDir: DATA_DIR,
+                    serverURL: SERVER_URL,
+                    password: PASSWORD,
+                }), 'pool init');
+                // #390: the shared tracked loader, not a hand-written download. It clears the record
+                // BEFORE starting and keeps an abandoned load registered, so a session-open download that
+                // outruns ACTUAL_OP_TIMEOUT_MS cannot silently re-point the singleton later.
+                await loadBudgetTracked(BUDGET_SYNC_ID, BUDGET_PASSWORD, 'pool downloadBudget');
+                // Mark live only after a successful download (#270): avoids the poisoning
+                // window where a stalled/failed download would leak isApiInitialized=true.
+                setApiInitialized(true);
+            }); // #390: end of the api-mutex block.
             this.sharedConnection = {
                 sessionId: 'shared',
                 initialized: true,