feat(connections): show a full-window connecting surface with named stages (#2053)

Author: datlechin

CHANGELOG.md

@@ -23,8 +23,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Redshift external schemas now list their tables. Spectrum, federated query, cross-database, and datashare schemas showed up empty because their tables are not in the standard catalog.
 - External schemas are marked in the sidebar, and their tables show an external icon. External tables open read-only, because Redshift rejects `UPDATE` and `DELETE` on them.
 
+### Changed
+
+- Connecting to a database now fills the window instead of framing a spinner with an empty sidebar and inspector, and it names the step it is on: opening the tunnel, negotiating encryption, authenticating, preparing the session. PostgreSQL, CockroachDB, Redshift, ClickHouse, and Redis report their own handshake steps; the rest report the steps around the driver. A step that stalls says so rather than spinning silently.
+- A connection that fails now shows the database's own error wherever the connect started, including from a link or a database file, and offers Copy Details. Those routes used to drop the real message and report only that the connection had closed.
+- Opening a table or query from a link now opens its window straight away, so a slow connect has somewhere to report progress and a failed one has somewhere to explain itself.
+- A saved pre-connect script no longer runs when the app reopens a session on its own. The window waits with a Connect button, which asks before running it.
+
 ### Fixed
 
+- A dropped SSH tunnel that ran out of reconnect attempts left the window spinning forever with no way back. It now reports what happened and offers to try again.
+- A brief tunnel reconnect no longer closes your tabs. The window used to tear down the whole session on the blip, taking unsaved query edits with it.
+- The sidebar's filter field no longer sits over an empty sidebar while a connection is still being established.
 - The JSON view of a result now follows the grid: rows come in the order you sorted them, a column filter leaves its rows out, and hidden columns stay hidden. It used to show every row in fetch order, including rows the filter had removed, and columns you had hidden.
 - Copy JSON in the JSON view and Copy as JSON in the grid now produce the same output for the same rows.
 - The JSON view now updates when you change a column filter without running a new query.

Plugins/ClickHouseDriverPlugin/ClickHousePlugin.swift

@@ -195,6 +195,10 @@ final class ClickHousePluginDriver: PluginDatabaseDriver, @unchecked Sendable {
     // MARK: - Connection
 
     func connect() async throws {
+        try await connect(reportingStage: { _ in })
+    }
+
+    func connect(reportingStage report: @escaping ConnectionStageReporter) async throws {
         let urlConfig = URLSessionConfiguration.default
         urlConfig.timeoutIntervalForRequest = HttpQueryTimeout.sessionBootstrapRequestTimeout
         urlConfig.timeoutIntervalForResource = HttpQueryTimeout.sessionResourceTimeout
@@ -221,6 +225,7 @@ final class ClickHousePluginDriver: PluginDatabaseDriver, @unchecked Sendable {
             throw ClickHouseError.connectionFailed
         }
 
+        report(.preparingSession)
         if let result = try? await executeRaw("SELECT version()"),
            let versionStr = result.rows.first?.first?.asText {
             _serverVersion = versionStr

Plugins/PostgreSQLDriverPlugin/LibPQDriverCore.swift

@@ -20,6 +20,11 @@ final class LibPQDriverCore: @unchecked Sendable {
 
     var onPostConnect: (@Sendable () async -> Void)?
 
+    /// Set by `LibPQBackedDriver` for the span of one connect, so every driver built on this
+    /// core reports its handshake steps without having to thread a parameter through its own
+    /// `connect()` and duplicate the setup each one does around it.
+    var stageReporter: ConnectionStageReporter?
+
     var serverVersion: String? { libpqConnection?.serverVersion() }
     var serverVersionNumber: Int32 { libpqConnection?.serverVersionNumber() ?? 0 }
 
@@ -47,7 +52,7 @@ final class LibPQDriverCore: @unchecked Sendable {
             suppressServerSideCancel: singleConnectionMode
         )
 
-        try await pqConn.connect()
+        try await pqConn.connect(reportingStage: stageReporter ?? { _ in })
         libpqConnection = pqConn
 
         switch await probeSchema(pqConn, query: PostgreSQLSchemaQueries.currentSchema) {
@@ -193,6 +198,14 @@ extension LibPQBackedDriver {
         try await core.connect()
     }
 
+    /// Routes back through `connect()` rather than calling the core directly, so a driver that
+    /// overrides `connect()` to probe catalogs or remap errors still runs its own version.
+    func connect(reportingStage report: @escaping ConnectionStageReporter) async throws {
+        core.stageReporter = report
+        defer { core.stageReporter = nil }
+        try await connect()
+    }
+
     func disconnect() {
         core.disconnect()
     }

Plugins/PostgreSQLDriverPlugin/LibPQPluginConnection.swift

@@ -162,7 +162,7 @@ final class LibPQPluginConnection: @unchecked Sendable {
 
     // MARK: - Connection Management
 
-    func connect() async throws {
+    func connect(reportingStage report: @escaping ConnectionStageReporter = { _ in }) async throws {
         stateLock.lock()
         _isConnectCancelled = false
         stateLock.unlock()
@@ -172,7 +172,7 @@ final class LibPQPluginConnection: @unchecked Sendable {
                 on: queue,
                 cancellationCheck: { [weak self] in self?.isConnectCancelled ?? true }
             ) { [self] in
-                try performConnect()
+                try performConnect(reportingStage: report)
             }
         } onCancel: {
             cancelConnect()
@@ -191,7 +191,7 @@ final class LibPQPluginConnection: @unchecked Sendable {
         return _isConnectCancelled
     }
 
-    private func performConnect() throws {
+    private func performConnect(reportingStage report: @escaping ConnectionStageReporter) throws {
         guard let connection = buildConnectionString().withCString({ PQconnectStart($0) }) else {
             throw LibPQPluginError.connectionFailed
         }
@@ -205,7 +205,7 @@ final class LibPQPluginConnection: @unchecked Sendable {
             throw connectionError(from: connection)
         }
 
-        try pollUntilConnected(connection)
+        try pollUntilConnected(connection, reportingStage: report)
         configureEstablishedConnection(connection)
 
         stateLock.lock()
@@ -215,12 +215,17 @@ final class LibPQPluginConnection: @unchecked Sendable {
         adopted = true
     }
 
-    private func pollUntilConnected(_ connection: OpaquePointer) throws {
+    private func pollUntilConnected(
+        _ connection: OpaquePointer,
+        reportingStage report: @escaping ConnectionStageReporter
+    ) throws {
         let deadline = PQgetCurrentTimeUSec() + Self.connectTimeoutMicroseconds
         var status = PGRES_POLLING_WRITING
+        var lastHandshakeStatus: ConnStatusType?
 
         while true {
             try checkConnectCancellation()
+            reportHandshakeStage(of: connection, last: &lastHandshakeStatus, report: report)
 
             switch status {
             case PGRES_POLLING_OK:
@@ -250,6 +255,28 @@ final class LibPQPluginConnection: @unchecked Sendable {
         }
     }
 
+    /// `PGRES_POLLING_*` only says whether the socket wants a read or a write, so it cannot tell
+    /// a TLS handshake from an authentication exchange. `PQstatus` can, and reading it costs one
+    /// pointer dereference per poll slice.
+    private func reportHandshakeStage(
+        of connection: OpaquePointer,
+        last: inout ConnStatusType?,
+        report: ConnectionStageReporter
+    ) {
+        let current = PQstatus(connection)
+        guard current != last else { return }
+        last = current
+
+        switch current {
+        case CONNECTION_SSL_STARTUP:
+            report(.negotiatingEncryption)
+        case CONNECTION_AWAITING_RESPONSE, CONNECTION_AUTH_OK:
+            report(.authenticating)
+        default:
+            break
+        }
+    }
+
     private func checkConnectCancellation() throws {
         guard isConnectCancelled else { return }
         throw CancellationError()

Plugins/RedisDriverPlugin/RedisPluginConnection.swift

@@ -165,14 +165,15 @@ final class RedisPluginConnection: @unchecked Sendable {
 
     // MARK: - Connection Management
 
-    func connect() async throws {
+    func connect(reportingStage report: @escaping ConnectionStageReporter = { _ in }) async throws {
         #if canImport(CRedis)
         _ = Self.initOnce
         try await pluginDispatchAsync(on: queue) { [self] in
             logger.debug("Connecting to Redis at \(self.host):\(self.port)")
 
-            try openContextSync(selectDatabase: database)
+            try openContextSync(selectDatabase: database, reportingStage: report)
 
+            report(.preparingSession)
             do {
                 let pingReply = try executeCommandSync(["PING"])
                 if case .error(let msg) = pingReply {
@@ -398,7 +399,10 @@ private extension RedisPluginConnection {
         }
     }
 
-    func openContextSync(selectDatabase dbIndex: Int) throws {
+    func openContextSync(
+        selectDatabase dbIndex: Int,
+        reportingStage report: ConnectionStageReporter = { _ in }
+    ) throws {
         let connectTimeout = timeval(tv_sec: 10, tv_usec: 0)
         guard let ctx = redisConnectWithTimeout(host, Int32(port), connectTimeout) else {
             logger.error("Failed to create Redis context")
@@ -423,8 +427,12 @@ private extension RedisPluginConnection {
 
         do {
             if sslConfig.isEnabled {
+                report(.negotiatingEncryption)
                 try connectSSL(ctx)
             }
+            if let password, !password.isEmpty {
+                report(.authenticating)
+            }
             try authenticateSync()
             if dbIndex != 0 {
                 let reply = try executeCommandSync(["SELECT", String(dbIndex)])

Plugins/RedisDriverPlugin/RedisPluginDriver.swift

@@ -60,6 +60,10 @@ final class RedisPluginDriver: PluginDatabaseDriver, @unchecked Sendable {
     // MARK: - Connection Management
 
     func connect() async throws {
+        try await connect(reportingStage: { _ in })
+    }
+
+    func connect(reportingStage report: @escaping ConnectionStageReporter) async throws {
         let sslConfig = config.ssl
         let redisDb = Int(config.additionalFields["redisDatabase"] ?? "") ?? Int(config.database) ?? 0
 
@@ -72,7 +76,7 @@ final class RedisPluginDriver: PluginDatabaseDriver, @unchecked Sendable {
             sslConfig: sslConfig
         )
 
-        try await conn.connect()
+        try await conn.connect(reportingStage: report)
         redisConnection = conn
     }
 

Plugins/TableProPluginKit/ConnectionStage.swift

@@ -0,0 +1,22 @@
+import Foundation
+
+/// A step a connection attempt passes through, reported as it starts so a window can say what
+/// it is waiting on instead of showing an unexplained spinner.
+///
+/// Left non-frozen so it can gain steps without an ABI bump, and `custom` carries an
+/// engine-specific step that does not earn a shared case.
+public enum ConnectionStage: Sendable, Equatable {
+    case resolvingTunnel
+    case runningPreConnectScript
+    case awaitingCredentials
+    case openingConnection
+    case negotiatingEncryption
+    case authenticating
+    case preparingSession
+    case custom(String)
+}
+
+/// Called on whatever thread the stage is observed from, so it must be cheap and must not
+/// assume the main actor. It is deliberately synchronous: the deepest call sites are C poll
+/// loops where a suspension point would change the timing of the connect itself.
+public typealias ConnectionStageReporter = @Sendable (ConnectionStage) -> Void

Plugins/TableProPluginKit/PluginDatabaseDriver.swift

@@ -75,6 +75,7 @@ public protocol PluginDatabaseDriver: AnyObject, Sendable {
     var capabilities: PluginCapabilities { get }
 
     func connect() async throws
+    func connect(reportingStage report: @escaping ConnectionStageReporter) async throws
     func disconnect()
     func ping() async throws
 
@@ -208,6 +209,12 @@ public protocol PluginDatabaseDriver: AnyObject, Sendable {
 public extension PluginDatabaseDriver {
     var capabilities: PluginCapabilities { [] }
 
+    /// A driver that cannot see inside its own connect keeps the plain path. The app still
+    /// reports the stages either side of this call, so the window is never blank.
+    func connect(reportingStage report: @escaping ConnectionStageReporter) async throws {
+        try await connect()
+    }
+
     func fetchTriggers(table: String, schema: String?) async throws -> [PluginTriggerInfo] { [] }
 
     /// Engines whose partitions are metadata on one table object, rather than

TablePro/Core/Database/DatabaseDriver.swift

@@ -28,6 +28,9 @@ protocol DatabaseDriver: AnyObject, Sendable {
     /// Connect to the database
     func connect() async throws
 
+    /// Connect while reporting the steps this driver can see from inside its own handshake.
+    func connectReporting(stage report: @escaping ConnectionStageReporter) async throws
+
     /// Disconnect from the database
     func disconnect()
 
@@ -240,6 +243,10 @@ extension DatabaseDriver {
     /// Override in drivers that support version querying
     var serverVersion: String? { nil }
 
+    func connectReporting(stage report: @escaping ConnectionStageReporter) async throws {
+        try await connect()
+    }
+
     var queryBuildingPluginDriver: (any PluginDatabaseDriver)? { nil }
 
     func beginTransaction(mode: PluginTransactionAccessMode) async throws {