From c6812b6481ac38602f063e877ed644d72f9482ca Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 4 Feb 2026 03:56:04 +0000 Subject: [PATCH] docs(auth-utils): document intentional inconsistent state in destroy() Addresses Copilot AI comment on PR #79 about unclear behavior when destroy() returns early due to locked mutexes. Problem: When destroy() is called but mutexes are locked (active transactions), the function sets destroyed=true but returns early without destroying resources. This creates temporary inconsistent state that wasn't documented, making it unclear if this was intentional or a bug. Behavior: 1. destroy() ALWAYS sets destroyed=true (prevents new transactions) 2. If mutexes locked: early return, resources NOT destroyed 3. Active transactions continue safely with existing resources 4. After transactions complete: resources cleaned up by GC 5. If no locked mutexes: resources destroyed immediately State during early return: - destroyed = true (new transactions throw error) - preKeyManager exists (active transactions can use it) - keyQueues exist (active transactions can use them) This is INTENTIONAL and SAFE: - New transactions are rejected (destroyed flag check) - Active transactions complete successfully (resources exist) - No crash, no corruption, just deferred cleanup Changes: - Added comprehensive JSDoc explaining the two-path behavior - Documented the intentional temporary inconsistent state - Added inline comment reminding that flag is set even on early return - Clarified that GC handles cleanup for early return case This addresses the Copilot concern that the behavior was misleading. The state is intentional, not a bug - just needed documentation. https://claude.ai/code/session_VMxqX --- src/Utils/auth-utils.ts | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/Utils/auth-utils.ts b/src/Utils/auth-utils.ts index 28dc56a1..155ced79 100644 --- a/src/Utils/auth-utils.ts +++ b/src/Utils/auth-utils.ts @@ -353,9 +353,19 @@ export const addTransactionCapability = ( /** * Cleanup all resources (queues, managers, mutexes) * Should be called during connection cleanup + * + * IMPORTANT BEHAVIOR: + * - Always sets destroyed=true to prevent NEW transactions + * - If mutexes are locked (active transactions), returns early WITHOUT destroying resources + * - This creates intentional temporary inconsistent state: + * * destroyed=true (new transactions rejected) + * * resources exist (active transactions complete safely) + * * resources cleaned up by GC after active transactions finish + * - If no locked mutexes, destroys resources immediately */ destroy: () => { // CRITICAL: Set destroyed flag FIRST to prevent new transactions + // Note: Flag is set even if early return occurs (see doc above) destroyed = true logger.debug('🗑️ Cleaning up transaction capability resources')