refactor: replace string-matched errors with typed control-plane errors

[rawkode]

Summary

Two places decided what to do by matching error message text. Both break silently the moment the wording changes.

Missing tunnel key: Option, not a sentinel

Repo::listen_key_for_tunnel bailed with the literal "KEY_NOT_FOUND" and resolve_listen_key in the binary recovered by e.to_string().contains(...). A missing key is an expected state, so the method now returns Result<Option<SecretKey>> and the caller matches on None.

Breaking change to the connect-lib public API. Repo is re-exported and the signature changes. The crate is 0.1.0 and unpublished, and the only caller is the binary in this repo. A parallel optional-returning method was rejected because it would leave the sentinel in place.

Behaviour change: the interactive picker path previously called listen_key_for_tunnel directly and would print the raw KEY_NOT_FOUND sentinel if the key was missing. It now goes through resolve_listen_key and gets the same regenerate-and-rewire handling as --id.

Control-plane failures: ControlPlaneError enum

project_lookup_error in the binary searched for "not found", "NotFound" and "404" in an error that had already been wrapped twice, so any 404 matched, not only a missing control plane. At the same time find_connector had the typed kube::Error in hand, matched on e.code, and then baked datumctl ctx switch guidance into a string inside the library.

New in kube_error.rs:

• ControlPlaneError { ProjectNotFound, PermissionDenied, Unauthorized } with thiserror. Each variant keeps the original kube::Error as #[source], so the API status, reason and message still reach the binary's "Underlying error" line.
• classify_list_error(project_id, context, kube::Error) maps 404/403/401 from a list call to the enum and wraps everything else with the given context. A 404 on a list is precise: an empty namespace returns 200, so it can only mean the control-plane path is missing.
• ControlPlaneError::find_in(&AnyError) walks the source chain. AnyError::downcast_ref only inspects the outermost error and every .context(..) adds a layer, so a plain downcast at the top level misses it. There is a test for this.

The error travels inside the existing n0_error::AnyError, so the TunnelService API is unchanged. Every list that propagates out of TunnelService goes through the classifier, so a project-level failure on any call in a sequence, not only the first, gets guidance.

The binary recovers the variant in main() and attaches the guidance there. Behaviour changes:

• Guidance now applies to every control-plane failure that reaches main, not only the --endpoint lookup. Previously a 404 from find_connector fell through to a bare "Failed to list connectors".
• The datumctl command text no longer lives in the embeddable library.
• The underlying error is printed on its own line after the guidance instead of inlined.

Not in scope

is_dns_error in progress.rs also matches on message text, but reqwest::Error exposes no DNS classification and the source chain bottoms out in an uncategorised io::Error. Fixing it properly means resolving with hickory first and handing reqwest the IPs, which changes behaviour. Left for a separate PR.

Verification

Check	Result
cargo clippy --workspace --all-targets	same nine pre-existing errors as develop, no new findings (PR #27 fixes those)
cargo test --workspace	77 passed, 0 failed, including 6 new tests
rustfmt --check on touched lib files	clean (main.rs kept to my hunks since develop is not fmt-clean)
grep KEY_NOT_FOUND|datumctl ctx switch connect-lib/lib	no matches
grep 'std_context("Failed to list' connect-lib/lib	no matches

[Copilot]

Copilot review overview

🟡 Changes recommended

Three moderate findings remain unresolved.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 3

Open (3)

• Preserve original kube error details in control-plane error chain · New
• Avoid unannounced breaking change to public listen_key_for_tunnel API · New
• Classify Connector and ConnectorAdvertisement list errors · New

What changed in this PR

This PR replaces string-matched errors with typed control-plane errors and explicit missing-key handling.

Changes:

• Uses Option<SecretKey> for missing tunnel keys.
• Adds typed error classification and source-chain lookup.
• Moves control-plane guidance into the binary.

File	Summary
connect-lib/​lib/​src/​tunnels.rs	Applies typed classification to tunnel list failures. Moderate (2 votes): classify subsequent list operations as well.
connect-lib/​lib/​src/​repo.rs	Implements optional listen-key lookup. Moderate (2 votes): address the public API compatibility decision.
connect-lib/​lib/​src/​lib.rs	Re-exports ControlPlaneError.
connect-lib/​lib/​src/​kube_error.rs	Defines error classification and chain lookup. Moderate (3 votes): preserve original API errors for diagnostics.
connect-lib/​bin/​src/​main.rs	Handles key recovery and user-facing guidance.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[rawkode]

@copilot resolve the merge conflicts on this branch.

[Copilot]

@copilot resolve the merge conflicts on this branch.

Resolved and pushed. I merged origin/develop into this branch, resolved the conflicts, and finalized it in f87716a (with a small follow-up synchronization fix in 151cb50).

[cla-assistant]

All committers have signed the CLA.

[cla-assistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ rawkode
❌ Copilot
_{You have signed the CLA already but the status is still pending? Let us recheck it.}