diff --git a/crates/openshell-cli/src/main.rs b/crates/openshell-cli/src/main.rs index bb55bd7fcc..9e1af68744 100644 --- a/crates/openshell-cli/src/main.rs +++ b/crates/openshell-cli/src/main.rs @@ -8,7 +8,7 @@ use clap::{CommandFactory, Parser, Subcommand, ValueEnum, ValueHint}; use clap_complete::engine::ArgValueCompleter; use clap_complete::env::CompleteEnv; -use miette::Result; +use miette::{Result, WrapErr}; use openshell_cli::color::{self, ColorChoice, Colorize}; use std::io::Write; use std::path::PathBuf; @@ -4134,7 +4134,16 @@ async fn run_async() -> Result<()> { let ctx = resolve_gateway(&cli.gateway, &cli.gateway_endpoint)?; let mut tls = tls.with_gateway_name(&ctx.name); apply_auth(&mut tls, &ctx.name)?; - let channel = openshell_cli::tls::build_channel(&ctx.endpoint, &tls).await?; + let channel = openshell_cli::tls::build_channel(&ctx.endpoint, &tls) + .await + .wrap_err_with(|| { + format!( + "Could not connect to gateway '{}' at {}.\n\ + Check that the gateway service or tunnel is running and the endpoint is correct.\n\ + Inspect saved endpoints with: openshell gateway list", + ctx.name, ctx.endpoint + ) + })?; let interceptor = openshell_core::auth::EdgeAuthInterceptor::new( tls.oidc_token.as_deref(), tls.edge_token.as_deref(), diff --git a/crates/openshell-cli/tests/gateway_registration_integration.rs b/crates/openshell-cli/tests/gateway_registration_integration.rs index 706ec1dee9..b144c714ee 100644 --- a/crates/openshell-cli/tests/gateway_registration_integration.rs +++ b/crates/openshell-cli/tests/gateway_registration_integration.rs @@ -104,6 +104,62 @@ fn status_with_unregistered_named_gateway_fails() { ); } +#[test] +fn term_connection_error_reports_gateway_and_endpoint_override() { + let config_dir = tempfile::tempdir().expect("create user config dir"); + let system_dir = tempfile::tempdir().expect("create system config dir"); + let listener = std::net::TcpListener::bind("127.0.0.1:0").expect("bind test endpoint"); + let port = listener.local_addr().expect("local address").port(); + let endpoint = format!("http://127.0.0.1:{port}"); + drop(listener); + write_user_gateway_metadata( + config_dir.path(), + "offline", + "http://stored.example.com:17670", + 17670, + false, + "plaintext", + ); + + let output = run( + config_dir.path(), + system_dir.path(), + &[ + "--gateway", + "offline", + "--gateway-endpoint", + &endpoint, + "term", + ], + ); + + assert_ne!(output.code, 0, "{}", output.combined); + assert!( + output.combined.contains("gateway 'offline'"), + "{}", + output.combined + ); + assert!(output.combined.contains(&endpoint), "{}", output.combined); + assert!( + output.combined.contains("openshell gateway list"), + "{}", + output.combined + ); + assert!( + output + .combined + .to_ascii_lowercase() + .contains("connection refused"), + "{}", + output.combined + ); + assert!( + !output.combined.contains("stored.example.com"), + "{}", + output.combined + ); +} + #[test] fn status_with_unregistered_environment_gateway_fails() { let config_dir = tempfile::tempdir().expect("create user config dir"); diff --git a/crates/openshell-sdk/src/error.rs b/crates/openshell-sdk/src/error.rs index 0422f9bf8e..170ace4a04 100644 --- a/crates/openshell-sdk/src/error.rs +++ b/crates/openshell-sdk/src/error.rs @@ -44,6 +44,9 @@ pub enum SdkError { Connect { /// Error message. message: String, + /// Original channel error, including TCP and TLS failure causes. + #[source] + source: Option>, }, /// Auth-related failure: OIDC discovery / refresh, token format invalid @@ -139,6 +142,7 @@ impl SdkError { pub fn connect(message: impl Into) -> Self { Self::Connect { message: message.into(), + source: None, } } @@ -248,6 +252,15 @@ impl SdkError { } } +impl From for SdkError { + fn from(source: tonic::transport::Error) -> Self { + Self::Connect { + message: source.to_string(), + source: Some(Box::new(source)), + } + } +} + #[cfg(test)] mod tests { use super::*; diff --git a/crates/openshell-sdk/src/transport.rs b/crates/openshell-sdk/src/transport.rs index eb2dd87b06..a4e7ca7ed4 100644 --- a/crates/openshell-sdk/src/transport.rs +++ b/crates/openshell-sdk/src/transport.rs @@ -88,7 +88,7 @@ pub async fn build_channel(config: &ClientConfig) -> Result { return standard_endpoint(gateway.clone())? .connect() .await - .map_err(|e| SdkError::connect(format!("{e}"))); + .map_err(SdkError::from); } if !gateway.starts_with("https://") { @@ -103,7 +103,7 @@ pub async fn build_channel(config: &ClientConfig) -> Result { return standard_endpoint(format!("http://{local_addr}"))? .connect() .await - .map_err(|e| SdkError::connect(format!("{e}"))); + .map_err(SdkError::from); } // Branch 3 — insecure TLS (skip cert verification): swap the scheme to @@ -118,7 +118,7 @@ pub async fn build_channel(config: &ClientConfig) -> Result { return standard_endpoint(http_uri)? .connect_with_connector(connector) .await - .map_err(|e| SdkError::connect(format!("{e}"))); + .map_err(SdkError::from); } // Branch 4 — anonymous TLS or OIDC bearer over HTTPS: pin `ca_cert` when @@ -141,7 +141,7 @@ pub async fn build_channel(config: &ClientConfig) -> Result { .map_err(|e| SdkError::tls(format!("{e}")))? .connect() .await - .map_err(|e| SdkError::connect(format!("{e}"))) + .map_err(SdkError::from) } /// rustls verifier that accepts any server certificate. diff --git a/docs/how-it-works/gateways/overview.mdx b/docs/how-it-works/gateways/overview.mdx index 093f73517a..568300892a 100644 --- a/docs/how-it-works/gateways/overview.mdx +++ b/docs/how-it-works/gateways/overview.mdx @@ -164,6 +164,12 @@ openshell gateway remove production ## Troubleshoot +If `openshell term` cannot connect, its error names the selected gateway and the +endpoint it tried, including a `--gateway-endpoint` override. Inspect saved +endpoints with `openshell gateway list`, which works without a live connection. +Check the underlying error to distinguish a connection refusal from a TLS or +authentication failure, then inspect the gateway service or tunnel. + Check gateway health: ```shell