Connectivity Troubleshooter 🕵️

Connectivity Troubleshooter for Failed DocumentDB and MongoDB Connections

Description:

When a connection attempt fails in the DocumentDB for VS Code extension, users are currently left with a brief error message, often with limited insight into what went wrong. This feature introduces a Connectivity Troubleshooter that helps users quickly identify common issues when trying to connect to MongoDB or DocumentDB endpoints.

Instead of guessing or manually testing, users will be able to activate a built-in tool that runs a sequence of automatic checks based on the provided connection string and reports clear diagnostics.

Proposed Functionality:

Upon a failed connection attempt, the user will be prompted to "Run Troubleshooter", which performs the following diagnostic steps:

1. Validate Connection String Format

   • Checks if the connection string is syntactically valid and contains expected components (scheme, host, port, credentials, options).

2. Check System Online Status (Optional, warning only)

   • Pings a known, reliable public host (e.g., 8.8.8.8, etc.).
   • If unreachable, displays a warning such as: "Your system may be offline or unable to reach external hosts."
   • This check does not block further diagnostics but provides helpful context in offline scenarios.

3. Parse and Resolve Hostname

   • Extracts the hostname from the URI and attempts DNS resolution.
   • For SRV-style URIs (mongodb+srv://), performs SRV and TXT record lookups.
   • Fails early if resolution doesn't return valid addresses.

4. Ping Target Port

   • Verifies whether the specified host and port are reachable via TCP.
   • Distinguishes between connection timeout and immediate rejections.

5. Inspect Network Access

   • Detects if firewall, antivirus, VPN, or proxy settings might be blocking outbound traffic to the target host.
   • Uses heuristics from previous steps to determine if network conditions are interfering.

6. Credential Completeness Check

   • Ensures that the connection string includes necessary authentication details, if required.

7. Connection and Permissions Verification

   • Attempts to establish a real connection using the full connection string.
   • Diagnoses errors including authentication failures, TLS certificate issues, and handshake problems.
   • If authentication succeeds, attempts to list databases using the authenticated user.
   • If permissions are insufficient, a clear message will be shown explaining the failure.

8. Suggest External Investigation

   • If all internal checks pass but the connection still fails, the user is advised to:
     • Verify server-side access controls (IP allowlists, firewall rules).
     • Check for misconfigured authentication, TLS certificates, or network routing.
     • Contact their cloud provider (e.g., Azure Cosmos DB, MongoDB Atlas) for further troubleshooting assistance.
   • A message like the following could be shown:
     "Everything looks correct on your local system. The issue may lie in the server-side configuration. Please review your cluster’s access controls or consult your provider’s support documentation."

Expected Behavior:

• If a connection fails, the user will be able to launch the troubleshooter via a prompt or command palette entry.
• A step-by-step diagnostic output will be shown, with clear pass/fail indicators and helpful messages.
• For failed checks, actionable suggestions will be provided.
• If all checks pass but the connection still fails, the user is guided to investigate external configuration issues.

Additional Considerations:

• Results should be presented in a readable format, potentially using a React-based WebView or a structured terminal-like output.
• Troubleshooter could be built to work even outside of failed connection flows, e.g., as a command available from the Command Palette for any saved connection.
• Diagnostic checks should not send or store any credentials, only the structural and network-relevant parts of the connection string are parsed.
• This could be the basis for future telemetry-based pattern detection, helping us identify common root causes users encounter.
• The implementation should be portable so that the core logic can be released as a standalone command-line tool.

No files, tests, or entry points are named, so start by locating the failed-connection flow and the extension's command or WebView entry points. Compare the existing connection error handling with the proposed checks, then define completion as a launchable troubleshooter that reports each diagnostic step and actionable results without sending or storing credentials.