fix: improve etcd API prefix detection for all versions

Author: datlechin

CHANGELOG.md

@@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-- etcd connection failing with 404 on etcd 3.4.x due to hardcoded `/v3/` API prefix
+- etcd connection failing with 404 when gRPC gateway uses a different API prefix (auto-detects `/v3/`, `/v3beta/`, `/v3alpha/`)
 
 ## [0.21.0] - 2026-03-19
 

Plugins/EtcdDriverPlugin/EtcdHttpClient.swift

@@ -415,8 +415,14 @@ internal final class EtcdHttpClient: @unchecked Sendable {
         let _: EtcdStatusResponse = try await post(path: apiPath("maintenance/status"), body: EmptyBody())
     }
 
+    /// Probes etcd gateway prefixes in order and selects the first that responds
+    /// with a non-404 status. Covers all etcd versions:
+    ///   3.5+  → /v3/  only
+    ///   3.4   → /v3/  + /v3beta/
+    ///   3.3   → /v3beta/ + /v3alpha/
+    ///   3.2-  → /v3alpha/ only
     private func detectApiPrefix() async throws {
-        let candidates = ["v3", "v3beta"]
+        let candidates = ["v3", "v3beta", "v3alpha"]
 
         lock.lock()
         guard let session else {
@@ -439,7 +445,8 @@ internal final class EtcdHttpClient: @unchecked Sendable {
             do {
                 (_, response) = try await session.data(for: request)
             } catch {
-                throw EtcdError.connectionFailed(error.localizedDescription)
+                // Network-level failure — server is unreachable regardless of prefix
+                throw error
             }
 
             guard let httpResponse = response as? HTTPURLResponse else {
@@ -450,16 +457,17 @@ internal final class EtcdHttpClient: @unchecked Sendable {
                 continue
             }
 
+            // Any non-404 (200, 401, etc.) means this prefix exists on the server
             lock.lock()
             apiPrefix = candidate
             lock.unlock()
             Self.logger.debug("Detected etcd API prefix: \(candidate)")
             return
         }
 
-        lock.lock()
-        apiPrefix = "v3"
-        lock.unlock()
+        throw EtcdError.connectionFailed(
+            "No supported etcd API found (tried: \(candidates.joined(separator: ", ")))"
+        )
     }
 
     // MARK: - KV Operations