Skip to content

fix(core-backend): reconnection logic #6861

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Oct 22, 2025
Merged

fix(core-backend): reconnection logic #6861

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c165f71
fix(core-backend): reconnection logic
Kriys94 Oct 16, 2025
d602e67
fix(core-backend): clean code
Kriys94 Oct 22, 2025
373a4f6
Merge branch 'main' into fix/WebsocketReconnection
Kriys94 Oct 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions packages/core-backend/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

### Added

- Add `forceReconnection()` method to `BackendWebSocketService` for controlled subscription state cleanup ([#6861](https://github.com/MetaMask/core/pull/6861))
- Performs a controlled disconnect-then-reconnect sequence with exponential backoff
- Useful for recovering from subscription/unsubscription issues and cleaning up orphaned subscriptions
- Add `BackendWebSocketService:forceReconnection` messenger action
- Add stable connection timer to prevent rapid reconnection loops ([#6861](https://github.com/MetaMask/core/pull/6861))
- Connection must stay stable for 10 seconds before resetting reconnect attempts
- Prevents issues when server accepts connection then immediately closes it

### Changed

- Bump `@metamask/base-controller` from `^8.4.1` to `^8.4.2` ([#6917](https://github.com/MetaMask/core/pull/6917))
- Update `AccountActivityService` to use new `forceReconnection()` method instead of manually calling disconnect/connect ([#6861](https://github.com/MetaMask/core/pull/6861))
- **BREAKING:** Update allowed actions for `AccountActivityService` messenger: remove `BackendWebSocketService:disconnect`, add `BackendWebSocketService:forceConnect` ([#6861](https://github.com/MetaMask/core/pull/6861))
- Improve reconnection scheduling in `BackendWebSocketService` to be idempotent ([#6861](https://github.com/MetaMask/core/pull/6861))
- Prevents duplicate reconnection timers and inflated attempt counters
- Scheduler checks if reconnect is already scheduled before creating new timer
- Improve error handling in `BackendWebSocketService.connect()` ([#6861](https://github.com/MetaMask/core/pull/6861))
- Always schedule reconnect on connection failure (exponential backoff prevents aggressive retries)
- Remove redundant schedule calls from error paths
- Update `BackendWebSocketService.disconnect()` to reset reconnect attempts counter ([#6861](https://github.com/MetaMask/core/pull/6861))
- Update `BackendWebSocketService.disconnect()` return type from `Promise<void>` to `void` ([#6861](https://github.com/MetaMask/core/pull/6861))
- Improve logging throughout `BackendWebSocketService` for better debugging ([#6861](https://github.com/MetaMask/core/pull/6861))

### Fixed

- Fix potential race condition in `BackendWebSocketService.connect()` that could bypass exponential backoff when reconnect is already scheduled ([#6861](https://github.com/MetaMask/core/pull/6861))
- Fix memory leak from orphaned timers when multiple reconnects are scheduled ([#6861](https://github.com/MetaMask/core/pull/6861))
- Fix issue where reconnect attempts counter could grow unnecessarily with duplicate scheduled reconnects ([#6861](https://github.com/MetaMask/core/pull/6861))

## [2.1.0]

Expand Down
38 changes: 13 additions & 25 deletions packages/core-backend/src/AccountActivityService.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ const getMessenger = () => {
// Create mock action handlers
const mockGetSelectedAccount = jest.fn();
const mockConnect = jest.fn();
const mockDisconnect = jest.fn();
const mockForceReconnection = jest.fn();
const mockSubscribe = jest.fn();
const mockChannelHasSubscription = jest.fn();
const mockGetSubscriptionsByChannel = jest.fn();
Expand All @@ -89,8 +89,8 @@ const getMessenger = () => {
mockConnect,
);
rootMessenger.registerActionHandler(
'BackendWebSocketService:disconnect',
mockDisconnect,
'BackendWebSocketService:forceReconnection',
mockForceReconnection,
);
rootMessenger.registerActionHandler(
'BackendWebSocketService:subscribe',
Expand Down Expand Up @@ -123,7 +123,7 @@ const getMessenger = () => {
mocks: {
getSelectedAccount: mockGetSelectedAccount,
connect: mockConnect,
disconnect: mockDisconnect,
forceReconnection: mockForceReconnection,
subscribe: mockSubscribe,
channelHasSubscription: mockChannelHasSubscription,
getSubscriptionsByChannel: mockGetSubscriptionsByChannel,
Expand Down Expand Up @@ -222,7 +222,7 @@ type WithServiceCallback<ReturnValue> = (payload: {
mocks: {
getSelectedAccount: jest.Mock;
connect: jest.Mock;
disconnect: jest.Mock;
forceReconnection: jest.Mock;
subscribe: jest.Mock;
channelHasSubscription: jest.Mock;
getSubscriptionsByChannel: jest.Mock;
Expand Down Expand Up @@ -464,28 +464,22 @@ describe('AccountActivityService', () => {
);
});

it('should handle disconnect failures during force reconnection by logging error and continuing gracefully', async () => {
it('should handle subscription failure by calling forceReconnection', async () => {
await withService(async ({ service, mocks }) => {
// Mock disconnect to fail - this prevents the reconnect step from executing
mocks.disconnect.mockRejectedValue(
new Error('Disconnect failed during force reconnection'),
);

// Trigger scenario that causes force reconnection by making subscribe fail
// Mock subscribe to fail
mocks.subscribe.mockRejectedValue(new Error('Subscription failed'));

// Should handle both subscription failure and disconnect failure gracefully - should not throw
// Should handle subscription failure gracefully - should not throw
const result = await service.subscribe({ address: '0x123abc' });
expect(result).toBeUndefined();

// Verify the subscription was attempted
expect(mocks.subscribe).toHaveBeenCalledTimes(1);

// Verify disconnect was attempted (but failed, preventing reconnection)
expect(mocks.disconnect).toHaveBeenCalledTimes(1);
// Verify forceReconnection was called (lines 289-290)
expect(mocks.forceReconnection).toHaveBeenCalledTimes(1);

// Connect is only called once at the start because disconnect failed,
// so the reconnect step never executes (it's in the same try-catch block)
// Connect is only called once at the start
expect(mocks.connect).toHaveBeenCalledTimes(1);
});
});
Expand Down Expand Up @@ -536,14 +530,8 @@ describe('AccountActivityService', () => {
// unsubscribe catches errors and forces reconnection instead of throwing
await service.unsubscribe(mockSubscription);

// Should have attempted to force reconnection with exact sequence
expect(mocks.disconnect).toHaveBeenCalledTimes(1);
expect(mocks.connect).toHaveBeenCalledTimes(1);

// Verify disconnect was called before connect
const disconnectOrder = mocks.disconnect.mock.invocationCallOrder[0];
const connectOrder = mocks.connect.mock.invocationCallOrder[0];
expect(disconnectOrder).toBeLessThan(connectOrder);
// Should have attempted to force reconnection
expect(mocks.forceReconnection).toHaveBeenCalledTimes(1);
},
);
});
Expand Down
15 changes: 5 additions & 10 deletions packages/core-backend/src/AccountActivityService.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ export type AccountActivityServiceActions = AccountActivityServiceMethodActions;
export const ACCOUNT_ACTIVITY_SERVICE_ALLOWED_ACTIONS = [
'AccountsController:getSelectedAccount',
'BackendWebSocketService:connect',
'BackendWebSocketService:disconnect',
'BackendWebSocketService:forceReconnection',
'BackendWebSocketService:subscribe',
'BackendWebSocketService:getConnectionInfo',
'BackendWebSocketService:channelHasSubscription',
Expand Down Expand Up @@ -559,16 +559,11 @@ export class AccountActivityService {
* Force WebSocket reconnection to clean up subscription state
*/
async #forceReconnection(): Promise<void> {
try {
log('Forcing WebSocket reconnection to clean up subscription state');

// All subscriptions will be cleaned up automatically on WebSocket disconnect
log('Forcing WebSocket reconnection to clean up subscription state');

await this.#messenger.call('BackendWebSocketService:disconnect');
await this.#messenger.call('BackendWebSocketService:connect');
} catch (error) {
log('Failed to force WebSocket reconnection', { error });
}
// Use the dedicated forceReconnection method which performs a controlled
// disconnect-then-connect sequence to clean up subscription state
await this.#messenger.call('BackendWebSocketService:forceReconnection');
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did this because I want to fully control the reconnection via scheduleConnect

}

// =============================================================================
Expand Down
22 changes: 22 additions & 0 deletions packages/core-backend/src/BackendWebSocketService-method-action-types.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,27 @@ export type BackendWebSocketServiceDisconnectAction = {
handler: BackendWebSocketService['disconnect'];
};

/**
* Forces a WebSocket reconnection to clean up subscription state
*
* This method is useful when subscription state may be out of sync and needs to be reset.
* It performs a controlled disconnect-then-reconnect sequence:
* - Disconnects cleanly to trigger subscription cleanup
* - Schedules reconnection with exponential backoff to prevent rapid loops
* - All subscriptions will be cleaned up automatically on disconnect
*
* Use cases:
* - Recovering from subscription/unsubscription issues
* - Cleaning up orphaned subscriptions
* - Forcing a fresh subscription state
*
* @returns Promise that resolves when disconnection is complete (reconnection is scheduled)
*/
export type BackendWebSocketServiceForceReconnectionAction = {
type: `BackendWebSocketService:forceReconnection`;
handler: BackendWebSocketService['forceReconnection'];
};
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did this because I want to fully control the reconnection via scheduleConnect


/**
* Sends a message through the WebSocket
*
Expand Down Expand Up @@ -159,6 +180,7 @@ export type BackendWebSocketServiceSubscribeAction = {
export type BackendWebSocketServiceMethodActions =
| BackendWebSocketServiceConnectAction
| BackendWebSocketServiceDisconnectAction
| BackendWebSocketServiceForceReconnectionAction
| BackendWebSocketServiceSendMessageAction
| BackendWebSocketServiceSendRequestAction
| BackendWebSocketServiceGetConnectionInfoAction
Expand Down
Loading
Loading