Skip to content

fix: auto-detect etcd API prefix for v3.4.x compatibility#382

Merged
datlechin merged 3 commits intomainfrom
fix/etcd-api-prefix-compat
Mar 20, 2026
Merged

fix: auto-detect etcd API prefix for v3.4.x compatibility#382
datlechin merged 3 commits intomainfrom
fix/etcd-api-prefix-compat

Conversation

@datlechin
Copy link
Copy Markdown
Collaborator

@datlechin datlechin commented Mar 20, 2026

Summary

Closes #380

  • Auto-detect the correct etcd gRPC-gateway API prefix (/v3/ vs /v3beta/) during connection, fixing 404 errors on etcd 3.4.x
  • etcd 3.3-3.4 serves the HTTP gateway at /v3beta/, while 3.5+ uses /v3/ — the plugin previously hardcoded /v3/
  • Detection probes /v3/maintenance/status first, falls back to /v3beta/ on HTTP 404; network errors propagate immediately

Test plan

  • Connect to an etcd 3.4.x instance (via SSH tunnel or direct) — should succeed instead of returning 404
  • Connect to an etcd 3.5+ instance — should continue working as before
  • Verify all operations (get, put, del, watch, lease, auth, cluster) work after connection
  • Disconnect and reconnect — prefix should be re-detected correctly

Summary by CodeRabbit

  • Bug Fixes
    • Resolved connections failing with HTTP 404 when the etcd gRPC gateway uses a nonstandard API prefix.
    • Added automatic detection of supported etcd API prefixes (/v3, /v3beta, /v3alpha) so the client aligns with gateway routing.
    • Improved connection probing and authentication handling to restore compatibility and reduce connection errors.

@coderabbitai
Copy link
Copy Markdown

coderabbitai bot commented Mar 20, 2026

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 37467597-2cf7-4fbf-9e4e-44f18cd9dfb3

📥 Commits

Reviewing files that changed from the base of the PR and between d2a16af and 03f86e6.

📒 Files selected for processing (1)
  • Plugins/EtcdDriverPlugin/EtcdHttpClient.swift

📝 Walkthrough

Walkthrough

Automatically detect etcd API prefixes by probing candidates (v3, v3beta, v3alpha) and use the detected prefix for all HTTP paths. Replaced hardcoded "v3/..." paths with a dynamic apiPath(...). Added changelog entry documenting the fix for 404s when gateway API prefixes differ.

Changes

Cohort / File(s) Summary
Changelog
CHANGELOG.md
Added Unreleased → Fixed entry documenting automatic detection of etcd API prefixes to prevent HTTP 404 when gRPC gateway uses a nonstandard API prefix.
Etcd HTTP client & API paths
Plugins/EtcdDriverPlugin/EtcdHttpClient.swift
Added apiPrefix state and apiPath(_:) helper; replaced hardcoded v3/... paths with apiPath(...); implemented detectApiPrefix() probing ["v3","v3beta","v3alpha"] (treating 404 as absent, accepting 200 or 401); updated connect()/disconnect() and error handling accordingly.
Usage sites (internal request paths)
.../kv/*, .../lease/*, .../cluster/*, .../maintenance/*, .../watch/*, .../auth/*, .../compaction/*
All request path constructions updated to use apiPath(...) instead of hardcoded "v3/...", affecting KV, lease, cluster, maintenance/endpoint status, watch, auth, and compaction flows.

Sequence Diagram(s)

sequenceDiagram
    actor Client as Client (TablePro)
    participant HTTP as EtcdHttpClient
    participant Etcd as etcd Server

    rect rgba(200, 100, 100, 0.5)
    Note over Client,Etcd: Old Flow (Hardcoded /v3 → possible 404)
    Client->>HTTP: connect()
    HTTP->>Etcd: POST /v3/maintenance/status
    Etcd-->>HTTP: 404 Not Found
    HTTP-->>Client: Connection error (404)
    end

    rect rgba(100, 200, 100, 0.5)
    Note over Client,Etcd: New Flow (Prefix auto-detection)
    Client->>HTTP: connect()
    HTTP->>HTTP: detectApiPrefix()
    HTTP->>Etcd: POST /v3/maintenance/status
    Etcd-->>HTTP: 404 Not Found
    HTTP->>Etcd: POST /v3beta/maintenance/status
    Etcd-->>HTTP: 200 OK
    HTTP->>HTTP: set apiPrefix = "v3beta"
    HTTP-->>Client: Connection established
    end
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

Poem

🐰 I peeked through tunnels, sniffed each API door,

v3 or beta, alpha—I'll try them all, of course.
No more lost 404s along the trail,
I hop in, detect, and cheer when connections prevail. 🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The PR title accurately summarizes the main change—automatic detection of etcd API prefix for v3.4.x compatibility—and is directly relevant to the changeset.
Linked Issues check ✅ Passed The PR implements automatic detection of etcd API prefixes (/v3/, /v3beta/, /v3alpha/) to fix connection failures, directly addressing issue #380's requirement for compatible detection with etcd 3.4.x servers.
Out of Scope Changes check ✅ Passed All changes are within scope: CHANGELOG.md documents the fix, and EtcdHttpClient.swift implements the API prefix detection logic to resolve the linked issue without unrelated modifications.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch fix/etcd-api-prefix-compat
📝 Coding Plan
  • Generate coding plan for human review comments

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

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

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@Plugins/EtcdDriverPlugin/EtcdHttpClient.swift`:
- Around line 468-470: The detector currently throws
EtcdError.connectionFailed("No supported etcd API..."), which causes connect()
to double-wrap probe failures; change the detector to throw a distinct error
(e.g., EtcdError.unsupportedAPI or a plain ProbeError) instead of
EtcdError.connectionFailed, or rethrow the underlying probe error unwrapped so
connect() can wrap it once; update the EtcdError enum to include unsupportedAPI
if needed and replace the throw at the detector site (the existing throw
EtcdError.connectionFailed(...) line) accordingly so connect() remains the
single place that classifies probe failures as connectionFailed.
- Around line 456-465: The probe currently treats any non-404 status as a valid
prefix, causing false positives for auth-required (401/403) or server errors;
update the probe inside the loop to only accept successful responses (e.g.
status codes in 200...299 or specifically 200) before setting apiPrefix and
returning. Keep the lock/apiPrefix assignment around the accepted case (use
lock.lock()/lock.unlock() or a defer) and for non-404/non-2xx responses log the
unexpected status via Self.logger.debug or warn and continue probing instead of
binding the prefix. Ensure the change references httpResponse.statusCode,
apiPrefix, lock, and Self.logger.debug in the modified logic.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a454156d-c4bf-4a86-85fb-82addde4c82f

📥 Commits

Reviewing files that changed from the base of the PR and between 6846b61 and d2a16af.

📒 Files selected for processing (2)
  • CHANGELOG.md
  • Plugins/EtcdDriverPlugin/EtcdHttpClient.swift

@datlechin datlechin merged commit 6095728 into main Mar 20, 2026
2 of 3 checks passed
@datlechin datlechin deleted the fix/etcd-api-prefix-compat branch March 20, 2026 02:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

bug: etcd connection test fails over SSH tunnel

1 participant