ngrok / ngrok-rust

Embed ngrok secure ingress into your Rust apps with a single line of code.

ngrok Community Discussions

In this repository, you will find discussions for all things ngrok. Feel free to share feedback, discuss topics with other community members, or ask questions.

Product Bug Reports

If you think you've found an bug in one of our products, the best place to report them is as a new issue. The issues page is regularly monitored by the ngrok Product team who will triage and respond. If the issue is with an open source ngrok product, we encourage you to open public issues directly in those repositories.

Product Feedback / New Feature Ideas

We encourage you to open a discussion if you have suggestions for how we can improve our products. You don't need to have a solution to the problem you are facing to kick off a discussion.

Prior to creating a new discussion, please take a look at previous discussions to see if someone else has already shared your suggestion(s). If you find a similar discussion, reply with additional details or upvote the discussion to signal your support rather than creating a new one.

Once you kick off a new feature discussion, the ngrok Product team will evaluate the feedback but may not be able to respond to every submission. From there, we will work with you, and the entire community, to ensure we understand the current capabilities ngrok doesn’t have and explore the space for potential solutions to your problem statement. If the product team determines that we will not be working to solve the problem you have identified, we may comment on the discussion describing our reasoning so our decisions can remain transparent.

Disclaimer

Any statement in this repository that is not purely historical is considered a forward-looking statement. Forward-looking statements included in this repository are based on information available to ngrok as of the date they are made, and ngrok assumes no obligation to update any forward-looking statements. The forward-looking comments in the public feedback discussions do not represent a commitment, guarantee, obligation or promise to deliver any product or feature, or to deliver any product and feature by any particular date, and are intended to outline the general development plans. Customers should not rely on these public feedback discussions to make any purchasing decision.

This repo was inspired by the Github Community Discussions Repo.

ngrok-rust's Issues

[Questions] There are plans to add support for `async-std`.?

Hi, I wanted to use the rust ngrok sdk but when I went to the documentation and then to the source code I noticed that it is linked to the Tokio ecosystem, I guess it makes sense because it is the largest within the rust ecosystem.

But my stack is completely based on async-std and that's why my question, I would love to be able to use this package without having to change my stack.

Builder ergonomics

Hi! 👋

First, let me thank you for the great crate. It was a breeze to add initial support for ngrok in our product, Devolutions Gateway.

However, I noticed all the builders are "consuming". This means, we can’t write straightforward code such as:

let mut builder = Session::builder()
    .authtoken(…)
    .tcp_endpoint()
    .remote_addr(…)
    .forwards_to(…);

if let Some(metadata) = metadata {
    builder.metadata(metadata);
}

for deny_cidr in deny_cidrs {
    builder.deny_cidr(deny_cidr);
}

let tunnel = builder.listen().await?;

This is really important when the configuration must be dynamic. See how I had to resort to macro tricks to get something somewhat "clean": Devolutions/devolutions-gateway#442

Here is an excerpt:

macro_rules! builder_call_opt {
    ($builder:ident . $method:ident ( $ngrok_option:expr ) ) => {{
        if let Some(option) = $ngrok_option {
            $builder.$method(option)
        } else {
            $builder
        }
    }};
}

macro_rules! builder_call_vec {
    ($builder:ident . $method:ident ( $ngrok_option:expr ) ) => {{
        let mut builder = $builder;
        let mut iter = $ngrok_option;
        loop {
            builder = match iter.next() {
                Some(item) => builder.$method(item),
                None => break builder,
            };
        }
    }};
    ($ngrok_option:expr, $builder:ident . $method:ident ( $( $( & )? $field:ident ),+ ) ) => {{
        let mut builder = $builder;
        let mut iter = $ngrok_option.iter();
        loop {
            builder = match iter.next() {
                Some(item) => builder.$method($( & item . $field ),+),
                None => break builder,
            };
        }
    }};
}

macro_rules! builder_call_flag {
    ($builder:ident . $method:ident ( $ngrok_option:expr ) ) => {{
        match $ngrok_option {
            Some(option) if option => $builder.$method(),
            _ => $builder,
        }
    }};
}

let builder = Session::builder().authtoken(&conf.authtoken);
let builder = builder_call_opt!(builder.heartbeat_interval(conf.heartbeat_interval));
let builder = builder_call_opt!(builder.heartbeat_tolerance(conf.heartbeat_tolerance));
let builder = builder_call_opt!(builder.metadata(&conf.metadata));
let builder = builder_call_opt!(builder.server_addr(&conf.server_addr));

let session = builder.connect().await?;

let builder = session.http_endpoint().domain(&http_conf.domain).forwards_to(hostname);
let builder = builder_call_opt!(builder.metadata(&http_conf.metadata));
let builder = builder_call_vec!(http_conf.basic_auth, builder.basic_auth(username, password));
let builder = builder_call_opt!(builder.circuit_breaker(http_conf.circuit_breaker));
let builder = builder_call_flag!(builder.compression(http_conf.compression));
let builder = builder_call_vec!(builder.allow_cidr(http_conf.allow_cidrs.iter()));
let builder = builder_call_vec!(builder.deny_cidr(http_conf.deny_cidrs.iter()));
let builder = builder_call_opt!(builder.proxy_proto(http_conf.proxy_proto.map(ProxyProto::from)));
let builder = builder_call_vec!(builder.scheme(
    http_conf
        .schemes
        .iter()
        .map(|s| Scheme::from_str(s).unwrap_or(Scheme::HTTPS))
));

let tunnel = builder.listen().await?;

This is especially bad for collections (basic_auth, allow_cidr, deny_cidr, …).

For reference, I had a similar situation in our IronRDP WASM module: SessionBuilder. In order to interface with JavaScript in a clean way, the builder methods must not take ownership of self. Using a RefCell internally is often the best solution. (An additional requirement, that ngrok-rs can ignore, was for the builder to be cheap to clone, hence the Rc.)

Rust official Style Guidelines book is also a good read: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html

Mirror ngrok-go's approach to setting the UserAgent in the AuthReq

The weird comma-separated ClientType field and matching updates to the ClientVersion was a misstep on my part - we should do the better thing and use the UserAgent field.

Expose OAuth ClientID/ClientSecret configuration

Same as ngrok/ngrok-go#70

Any chance of breaking muxado out into a separate repo?

Seems useful on its own. A la muxado-go.

Update needed due to breaking changes of axum version "0.7.4" release

Can you please update to allow the use of the new axum "0.7.4" release.
There were breaking changes of the axum Server sintax.

error[E0433]: failed to resolve: could not find Server in axum
--> src/main.rs:21:11
|
21 | axum::Server::builder(listener)
| ^^^^^^ could not find Server in axum

Thank you

[Question] What is the use of ProxyProto option when using ngrok as a library via this crate?

Hi!

As per the ngrok documentation:

Add a PROXY protocol header on connection to your upstream service. This sends connection information like the original client IP address to your upstream service.

But when using this library, we have access to the original client IP address using Conn::remote_addr from inside the "upstream service".

Hence my question: what’s the difference when this option is set, and how is it useful?

Thank you!

Support the `app_protocol` option for HTTP and Labeled listeners

This is to support http/2, and potentially other change-of-protocols that may occur.

See ngrok-private/ngrok#23863

Since we're Rusty here, let's maybe make it an enum rather than a string as it is in Go?

• setup the app protocol to forward http2/http1/"" #130
• tls config alpn forwarding work

Build on windows fails

Edit: The problem seems to be, that the import of windows_sys depending on the target config being windows, does not seem to work properly.

Building the package on windows fails with the following error:

   Compiling axum v0.6.18
   Compiling reqwest v0.11.18
   Compiling teloxide-core v0.9.1
   Compiling ngrok v0.12.3
error[E0433]: failed to resolve: could not find `Win32` in `windows_sys`
  --> C:\Users\User\.cargo\registry\src\index.crates.io-6f17d22bba15001f\ngrok-0.12.3\src\tunnel_ext.rs:24:18
   |
24 | use windows_sys::Win32::Foundation::ERROR_PIPE_BUSY;
   |                  ^^^^^ could not find `Win32` in `windows_sys`

For more information about this error, try `rustc --explain E0433`.
error: could not compile `ngrok` (lib) due to previous error
warning: build failed, waiting for other jobs to finish...

Support Host header rewriting

Word on the street is that we can do this at the ngrok edge via some middleware and won't need to do it directly in "agent" code anymore. Should simplify things for us significantly!

investigate wndinc underflows in muxado

I've observed some panics when the stream manager attempts to decrement a window below zero. I'm removing the panic, but there could still be another bug somewhere that was causing the sub-zero decrement in the first place that we should still look for.

Session/tunnel leaks

Consumers should reasonably expect dropping a tunnel to cause it to get closed, and dropping the session and all tunnels tied to it to close the session. This doesn't seem to be happening.

Investigation should start at the muxado layer and work its way up until the culprit is found. Entirely possible that I messed it up at the very bottom level 😛

Try to exclude `unwrap` and use implemented error handling to prevent potential problems.

Using unwrap in code can cause problems because if the value is actually None or Err, it will result in a panic and your program will crash. Instead of using unwrap, it is generally a better practice to use error handling techniques and the ? operator to handle potential errors in a safer way.

The function which uses unwrap is located here.

Support equivalent of root_cas: host in SDKs

When using the ngrok CLI agent to connect to a custom server_addr that uses a cert signed by letsencrypt we need to set root_cas: host to allow the agent to trust the LE CA.

Can we add the equivalent to each of the SDKs as well?

Run cargo-udeps in CI

Need more exemple

Hello,

Sorry, but have you an example to work with Rocket framework ?
It's built over hyper with http2 but all my test don't work...
Thx

Update to hyper v1

It's finally stable! 🎉

I imagine everyone will be eager to move to the new version, so we should bump our dependency that we track for Server integration.

Should hopefully be a pretty easy transition since we aren't using a very large API surface area.