actual-mcp-server 0.16.2 → 0.16.6

package/README.md

@@ -774,7 +774,7 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.16.2 | **Tool Count:** 74 (verified LibreChat-compatible)
+**Version:** 0.16.6 | **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,
@@ -358,7 +386,65 @@ class ActualConnectionPool {
      * the connection: in those cases the transport must survive.
      */
     async shutdownConnection(sessionId, opts = {}) {
+        // #392: acquire the api mutex, because this calls api.shutdown() on the PROCESS-GLOBAL
+        // singleton. Without it, the idle sweep or an explicit session close can tear the api down
+        // while ANOTHER session's operation is in flight inside the lock, and that operation then
+        // observes a torn-down api. Reproduced during #390's security review for the sibling cleanup
+        // site, which #390 fixed; these were the paths it left behind.
+        //
+        // NOT reentrant, so this variant is for callers that do NOT hold the lock. Callers that DO
+        // must call shutdownConnectionLocked directly; wrapping there would deadlock, and the symptom
+        // is a ~30s stall ended by #270's timeout rather than an obvious hang. The audit of which is
+        // which is recorded on shutdownConnectionLocked.
+        // #392 review (BLOCKING): the acquisition itself can REJECT. Since #393, taking the api lock
+        // settles any abandoned budget load and THROWS on timeout, so this wrapper gained a rejection
+        // path the old body never had (it was try/catch/finally end to end). Its callers are cleanup
+        // paths that do not expect one: `cleanupIdleConnections` is invoked from `setInterval`
+        // unawaited, and "abandoned budget load timed out" is not in `rejection-allowlist.ts`, so the
+        // escape reached `src/index.ts`'s unhandledRejection handler and called process.exit(1). That
+        // is the exact defect #393 fixed one level up in the write drain, reintroduced at a new
+        // acquisition site.
+        //
+        // So the acquisition is swallowed, matching the established pattern in the session-open
+        // cleanup above: cleanup must not fail louder than the thing it is cleaning up after.
+        // The entry is still torn down on that path, unless the caller asked for expiry to be
+        // re-checked and the session came back, which is the sweep's own contract. Tearing down
+        // matters because a stuck load must not make idle sessions un-evictable: the pool would fill
+        // to MAX_CONCURRENT_SESSIONS and start refusing new sessions with nothing in the log saying
+        // why. The unlocked shutdown in this handler is acceptable for a specific reason worth
+        // stating: while a registration is stuck, EVERY lock acquisition throws, so no operation can
+        // be running inside the lock at the moment this path fires.
+        await withApiLock(() => this.shutdownConnectionLocked(sessionId, opts)).catch(async (err) => {
+            logger.error(`[ConnectionPool] Could not acquire the api lock to shut down ${sessionId}; ` +
+                `tearing the entry down without it: ${err instanceof Error ? err.message : String(err)}`);
+            await this.shutdownConnectionLocked(sessionId, opts).catch(() => { });
+        });
+    }
+    /**
+     * The body of shutdownConnection, for callers that ALREADY hold the api mutex.
+     *
+     * #392 call-site audit, done explicitly rather than by inspection because the mutex is not
+     * reentrant and getting it wrong produces a stall that reads as a slow upstream server:
+     *
+     *   HOLDS the lock, so calls this variant:
+     *     - actual-adapter withActualApi pooled branch, infra-error drop
+     *     - actual-adapter withActualApiWrite, sync failure and infra-error drop
+     *     - actual-adapter processWriteQueue drain, sync failure and batch error
+     *   Does NOT hold it, so calls the wrapping shutdownConnection:
+     *     - actual-adapter switchBudget slow path (its own withApiLock block has closed by then)
+     *     - actualConnection.shutdownActualForSession (session close)
+     *     - this.cleanupIdleConnections (the idle sweep)
+     *     - this.shutdownAll
+     */
+    async shutdownConnectionLocked(sessionId, opts = {}) {
         const conn = this.connections.get(sessionId);
+        // #392 review: the idle sweep decides who is expired BEFORE waiting for the mutex, and that
+        // wait is no longer negligible. Re-checking here means a session that was touched while we
+        // queued keeps its connection instead of being closed mid-conversation.
+        if (opts.onlyIfExpired && conn && !this.isExpired(conn)) {
+            logger.debug(`[ConnectionPool] ${sessionId} was touched while waiting for the api lock; not evicting`);
+            return;
+        }
         if (!conn || !conn.initialized) {
             return;
         }
@@ -396,6 +482,16 @@ class ActualConnectionPool {
      * Shutdown the shared connection
      */
     async shutdownSharedConnection() {
+        // #392: same reasoning as shutdownConnection. Its only caller is shutdownAll, which does not
+        // hold the mutex.
+        await withApiLock(() => this.shutdownSharedConnectionLocked()).catch(async (err) => {
+            logger.error(`[ConnectionPool] Could not acquire the api lock to shut down the shared connection; ` +
+                `tearing it down without it: ${err instanceof Error ? err.message : String(err)}`);
+            await this.shutdownSharedConnectionLocked().catch(() => { });
+        });
+    }
+    /** The body of shutdownSharedConnection, for callers that already hold the api mutex. */
+    async shutdownSharedConnectionLocked() {
         if (!this.sharedConnection?.initialized) {
             return;
         }
@@ -472,7 +568,15 @@ class ActualConnectionPool {
                 // in the same window (#167). This is the path that previously drifted:
                 // the pool's autonomous timer removed an entry httpServer's separate
                 // timer knew nothing about.
-                await this.shutdownConnection(sessionId, { evict: true });
+                //
+                // #392 review: RE-CHECK expiry, because the decision above was taken before the lock and
+                // the eviction now waits for it. Before #392 that wait was effectively zero; since #378
+                // made drains sequential, one lock hold is the SUM of a batch's operations, so it is
+                // bounded only by batch length times ACTUAL_OP_TIMEOUT_MS. A session that was idle when
+                // marked can be active again by the time the lock arrives, and evicting it then closes
+                // its transport mid-conversation. Deciding and acting on the same side of the mutex is
+                // what makes the decision mean anything.
+                await this.shutdownConnection(sessionId, { evict: true, onlyIfExpired: true });
             }
         }
     }