feat(api-graphql): add WebSocket connection health monitoring

[anivar]

Description of changes

Add read-only WebSocket connection health diagnostics to AWSWebSocketProvider:

• getConnectionHealth() — returns WebSocketHealthState with:

  • isHealthy: true when connection state is Connected AND last keep-alive was received within 65 seconds
  • connectionState: current ConnectionState enum value
  • lastKeepAliveTime: timestamp of most recent keep-alive
  • timeSinceLastKeepAlive: milliseconds since last keep-alive

• isConnected() — checks raw WebSocket readyState === OPEN

These methods let consumers detect stale connections and build health indicators without modifying any internal state.

Removed from original implementation:

• Broken reconnect() method (called close() which destroys subscription state and reconnection monitor, making recovery impossible)
• Over-engineered persistent storage (module-level require() side effect for AsyncStorage, localStorage I/O on every keep-alive, useless after app restart)
• Unused WebSocketControl interface (never implemented)
• getPersistentConnectionHealth() (depended on removed persistence)

Issue #, if available

N/A

Description of how you validated changes

• 10 unit tests covering all connection states, keep-alive staleness, and WebSocket readyState values
• Verified 42 existing AWSAppSyncRealTimeProvider tests still pass
• TypeScript compilation clean (no new errors)

Checklist

• PR description included
• yarn test passes
• Unit Tests are changed or added
• Relevant documentation is changed or added (and PR referenced)

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[bobbor]

Thanks for opening the PR.
Please take a look at the comments

[anivar]

Hi @bobbor - I've addressed all the review feedback and made additional improvements to code quality.

Review feedback addressed:

• Fixed Promise handling with proper .catch()
• Using KeyValueStorageInterface instead of any
• Proper import statements at the top
• Simplified code where possible
• Using Date.now() instead of JSON.stringify(new Date())

Additional refactoring:

• Extracted helper methods (calculateHealthState, getPersistedKeepAliveTimestamp, persistKeepAliveTimestamp)
• Refactored platform storage initialization into testable function
• Added concurrency guards and proper error handling to reconnect()
• Fixed type consistency in WebSocketHealthState (non-optional fields with defaults)

Test coverage:

• Added 21 unit tests covering all new functionality
• All 170 tests passing

No breaking changes. Ready for re-review.

[changeset-bot]

🦋 Changeset detected

Latest commit: f8c906a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@aws-amplify/api-graphql	Patch
@aws-amplify/api	Patch
@aws-amplify/datastore	Patch
aws-amplify	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[anivar]

Hi @bobbor — thanks for the thorough review. I've refactored significantly based on your feedback. Most points were addressed by simplifying the scope:

Your review points → resolution:

1. Unhandled Promise on AsyncStorage.setItem → Persistent storage removed (unnecessary complexity for this use case)
2. Use KeyValueStorageInterface type → No longer needed without storage
3. Use import statement instead of inline require() → Removed along with storage
4. Unnecessary _ prefix on variables → Removed with persistent health methods
5. reconnect(): just await this.close() → Removed reconnect() — on closer review, close() tears down subscription state and the reconnection monitor, so reconnect-after-close can't work with the current architecture
6. Use Date.now() directly → No more persistence code
7. Unnecessary ternary on keepAliveTimestamp → Fixed, it's always initialized to Date.now()
8. Simplify isHealthy calculation → Done, inlined directly
9. lastKeepAliveTime should be 0 not undefined → Simplified

What remains (139 lines, down from 571):

• getConnectionHealth() — read-only diagnostics
• isConnected() — readyState === OPEN check
• WebSocketHealthState type
• 10 unit tests