Merge remote-tracking branch 'origin/main' into carl/blog-link

cargo-doc-ngrok/Cargo.toml

@@ -15,6 +15,6 @@ futures = "0.3.25"
 http = "0.2.8"
 hyper = { version = "0.14.23", features = ["server"] }
 hyper-staticfile = "0.9.2"
-ngrok = { path = "../ngrok", version = "0.12", features = ["hyper"] }
+ngrok = { path = "../ngrok", version = "0.13", features = ["hyper"] }
 tokio = { version = "1.23.0", features = ["full"] }
 watchexec = "2.3.0"

ngrok/CHANGELOG.md

@@ -1,83 +1,94 @@
+## 0.13.1
+
+- Preserve the `ERR_NGROK` prefix for error codes.
+
+## 0.13.0
+
+- Add the `NgrokError` trait
+- Add the `ErrResp` type
+- Change the `RpcError::Response` variant to the `ErrResp` type (from `String`)
+- Implement `NgrokError` for `ErrResp`, `RpcError`, and `ConnectError`
+
 ## 0.12.4
 
-* Add `Win32_Foundation` feature
-* Update nix for rust `1.72`
+- Add `Win32_Foundation` feature
+- Update nix for rust `1.72`
 
 ## 0.12.3
 
-* Add `session.id()`
+- Add `session.id()`
 
 ## 0.12.2
 
-* Updated readme and changelog
+- Updated readme and changelog
 
 ## 0.12.1
 
-* Add source error on reconnect
-* Rename repository to ngrok-rust
+- Add source error on reconnect
+- Rename repository to ngrok-rust
 
 ## 0.12.0
 
-* Add `client_info` to SessionBuilder
-* Update UserAgent generation
-* Make `circuit_breaker` test more reliable
+- Add `client_info` to SessionBuilder
+- Update UserAgent generation
+- Make `circuit_breaker` test more reliable
 
 ## 0.11.3
 
-* Update stream forwarding logic
-* Add `ca_cert` option to SessionBuilder
-* Unpin `bstr`
+- Update stream forwarding logic
+- Add `ca_cert` option to SessionBuilder
+- Unpin `bstr`
 
 ## 0.11.2
 
-* Send UserAgent when authenticating
-* Update readme documentation
+- Send UserAgent when authenticating
+- Update readme documentation
 
 ## 0.11.0
 
-* Include a session close method
-* Mark errors as non-exhaustive
+- Include a session close method
+- Mark errors as non-exhaustive
 
 ## 0.10.2
 
-* Update default forwards-to
-* Expose OAuth Client ID/Secret setters
-* Muxado: close method on the opener
+- Update default forwards-to
+- Expose OAuth Client ID/Secret setters
+- Muxado: close method on the opener
 
 ## 0.10.1
 
-* Add windows pipe support
-* Require tokio rt
+- Add windows pipe support
+- Require tokio rt
 
 ## 0.10.0
 
-* Some api-breaking consistency fixes for the session builder.
-* Update the connector to be more in-line with the other handlers and to support
+- Some api-breaking consistency fixes for the session builder.
+- Update the connector to be more in-line with the other handlers and to support
   disconnect/reconnect error reporting.
-* Add support for custom heartbeat handlers.
+- Add support for custom heartbeat handlers.
 
 ## 0.9.0
 
-* Update docs to match ngrok-go
-* Update the tls termination configuration methods to match those in ngrok-go
-* Remove the `_string` suffix from the cidr restriction methods
+- Update docs to match ngrok-go
+- Update the tls termination configuration methods to match those in ngrok-go
+- Remove the `_string` suffix from the cidr restriction methods
 
 ## 0.8.1
 
-* Fix cancellation bugs causing leaked muxado/ngrok sessions.
+- Fix cancellation bugs causing leaked muxado/ngrok sessions.
 
 ## 0.8.0
 
-* Some breaking changes to builder method naming for consistency.
-* Add dashboard command handlers
+- Some breaking changes to builder method naming for consistency.
+- Add dashboard command handlers
 
 ## 0.7.0
 
-* Initial crates.io release.
+- Initial crates.io release.
 
 ## Pre-0.7.0
 
-* There was originally a crate on crates.io named 'ngrok' that wrapped the agent
+- There was originally a crate on crates.io named 'ngrok' that wrapped the agent
   binary. It can be found [here](https://github.com/nkconnor/ngrok).
 
   Thanks @nkconnor!

ngrok/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ngrok"
-version = "0.12.4"
+version = "0.13.1"
 edition = "2021"
 license = "MIT OR Apache-2.0"
 description = "The ngrok agent SDK"

ngrok/README.md

@@ -22,17 +22,17 @@
 [ngrok](https://ngrok.com) is a simplified API-first ingress-as-a-service that adds connectivity, 
 security, and observability to your apps.
 
-ngrok-rust, our native and idiomatic crate for adding a public internet address 
-with secure ingress traffic directly into your Rust apps 🦀. If you’ve used ngrok in 
+ngrok-rust, our native and idiomatic crate for adding a public internet address
+with secure ingress traffic directly into your Rust apps 🦀. If you’ve used ngrok in
 the past, you can think of ngrok-rust as the ngrok agent packaged as a Rust crate.
 
-ngrok-rust lets developers serve Rust services on the internet in a single statement 
-without setting up low-level network primitives like IPs, NAT, certificates, 
-load balancers, and even ports! Applications using ngrok-rust listen on ngrok’s global 
-ingress network for TCP and HTTP traffic. ngrok-rust listeners are usable with 
-[hyper Servers](https://docs.rs/hyper/latest/hyper/server/index.html), and connections 
-implement [tokio’s AsyncRead and AsyncWrite traits](https://docs.rs/tokio/latest/tokio/io/index.html). 
-This makes it easy to add ngrok-rust into any application that’s built on hyper, such 
+ngrok-rust lets developers serve Rust services on the internet in a single statement
+without setting up low-level network primitives like IPs, NAT, certificates,
+load balancers, and even ports! Applications using ngrok-rust listen on ngrok’s global
+ingress network for TCP and HTTP traffic. ngrok-rust listeners are usable with
+[hyper Servers](https://docs.rs/hyper/latest/hyper/server/index.html), and connections
+implement [tokio’s AsyncRead and AsyncWrite traits](https://docs.rs/tokio/latest/tokio/io/index.html).
+This makes it easy to add ngrok-rust into any application that’s built on hyper, such
 as the popular [axum](https://docs.rs/axum/latest/axum/) HTTP framework.
 
 See [`/ngrok/examples/`][examples] for example usage, or the tests in
@@ -60,7 +60,7 @@ Add `ngrok` to the `[dependencies]` section of your `Cargo.toml`:
 ...
 
 [dependencies]
-ngrok = "0.12"
+ngrok = "0.13"
 
 ...
 ```
@@ -76,20 +76,22 @@ $ cargo add ngrok
 Create a simple HTTP server using `ngrok` and `axum`:
 
 `Cargo.toml`:
+
 ```toml
 [package]
 name = "ngrok-axum-example"
 version = "0.1.0"
 edition = "2021"
 
 [dependencies]
-ngrok = { version="0.12", features=["axum"] }
+ngrok = { version="0.13", features=["axum"] }
 tokio = { version = "1.26", features = ["full"] }
 axum = "0.6"
 anyhow = "1.0"
 ```
 
 `src/main.rs`:
+
 ```rust
 use std::net::SocketAddr;
 
@@ -141,10 +143,10 @@ async fn main() -> anyhow::Result<()> {
 
 This project is licensed under either of
 
- * Apache License, Version 2.0, ([LICENSE-APACHE][apache-url] or
-   <http://www.apache.org/licenses/LICENSE-2.0>)
- * MIT license ([LICENSE-MIT][mit-url] or
-   <http://opensource.org/licenses/MIT>)
+- Apache License, Version 2.0, ([LICENSE-APACHE][apache-url] or
+  <http://www.apache.org/licenses/LICENSE-2.0>)
+- MIT license ([LICENSE-MIT][mit-url] or
+  <http://opensource.org/licenses/MIT>)
 
 at your option.
 

ngrok/src/internals/proto.rs

@@ -1,5 +1,6 @@
 use std::{
     collections::HashMap,
+    error,
     fmt,
     io,
     ops::{
@@ -38,6 +39,66 @@ pub const SRV_INFO_REQ: StreamType = StreamType::clamp(8);
 
 pub const VERSION: &str = "2";
 
+/// An error that may have an ngrok error code.
+/// All ngrok error codes are documented at https://ngrok.com/docs/errors
+pub trait NgrokError: error::Error {
+    /// Return the ngrok error code, if one exists for this error.
+    fn error_code(&self) -> Option<&str> {
+        None
+    }
+    /// Return the error message minus the ngrok error code.
+    /// If this error has no error code, this is equivalent to
+    /// `format!("{error}")`.
+    fn msg(&self) -> String {
+        format!("{self}")
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Default)]
+pub struct ErrResp {
+    pub msg: String,
+    pub error_code: Option<String>,
+}
+
+impl<'a> From<&'a str> for ErrResp {
+    fn from(value: &'a str) -> Self {
+        let mut error_code = None;
+        let mut msg_lines = vec![];
+        for line in value.lines().filter(|l| !l.is_empty()) {
+            if line.starts_with("ERR_NGROK_") {
+                error_code = Some(line.trim().into());
+            } else {
+                msg_lines.push(line);
+            }
+        }
+        ErrResp {
+            error_code,
+            msg: msg_lines.join("\n"),
+        }
+    }
+}
+
+impl error::Error for ErrResp {}
+
+impl fmt::Display for ErrResp {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        self.msg.fmt(f)?;
+        if let Some(code) = &self.error_code {
+            write!(f, "\n\nERR_NGROK_{code}")?;
+        }
+        Ok(())
+    }
+}
+
+impl NgrokError for ErrResp {
+    fn error_code(&self) -> Option<&str> {
+        self.error_code.as_deref()
+    }
+    fn msg(&self) -> String {
+        self.msg.clone()
+    }
+}
+
 #[derive(Serialize, Deserialize, Debug, Clone, Default)]
 #[serde(rename_all = "PascalCase")]
 pub struct Auth {

ngrok/src/internals/raw_session.rs

@@ -57,6 +57,8 @@ use super::{
         BindOpts,
         BindResp,
         CommandResp,
+        ErrResp,
+        NgrokError,
         ProxyHeader,
         ReadHeaderError,
         Restart,
@@ -95,8 +97,24 @@ pub enum RpcError {
     #[error("failed to deserialize rpc response")]
     InvalidResponse(#[from] serde_json::Error),
     /// There was an error in the RPC response.
-    #[error("rpc error response: {0}")]
-    Response(String),
+    #[error("rpc error response:\n{0}")]
+    Response(ErrResp),
+}
+
+impl NgrokError for RpcError {
+    fn error_code(&self) -> Option<&str> {
+        match self {
+            RpcError::Response(resp) => resp.error_code(),
+            _ => None,
+        }
+    }
+
+    fn msg(&self) -> String {
+        match self {
+            RpcError::Response(resp) => resp.msg(),
+            _ => format!("{self}"),
+        }
+    }
 }
 
 #[derive(Error, Debug)]
@@ -258,7 +276,7 @@ impl RpcClient {
         if let Ok(err) = err_resp {
             if !err.error.is_empty() {
                 debug!(?err, "decoded rpc error response");
-                return Err(RpcError::Response(err.error));
+                return Err(RpcError::Response(err.error.as_str().into()));
             }
         }
 

ngrok/src/lib.rs

@@ -55,6 +55,7 @@ pub mod prelude {
     #[doc(inline)]
     pub use crate::{
         config::TunnelBuilder,
+        internals::proto::NgrokError,
         tunnel::{
             LabelsTunnel,
             ProtoTunnel,

ngrok/src/online_tests.rs

@@ -319,7 +319,7 @@ async fn oauth() -> Result<(), Error> {
     assert_eq!(resp.status(), StatusCode::OK);
     let body = resp.text().await?;
     assert_ne!(body, "Hello, world!");
-    assert!(body.contains("google-site-verification"));
+    assert!(body.contains("accounts.google.com"));
 
     Ok(())
 }