Crate ngrok

ngrok-rust

API Docs (main)

ngrok 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 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, and connections implement tokio’s AsyncRead and AsyncWrite traits. This makes it easy to add ngrok-rust into any application that’s built on hyper, such as the popular axum HTTP framework.

See /ngrok/examples/ for example usage, or the tests in /ngrok/src/online_tests.rs.

For working with the ngrok API, check out the ngrok Rust API Client Library.

Installation

Add ngrok to the [dependencies] section of your Cargo.toml with cargo add:

$ cargo add ngrok

Quickstart

Create a simple HTTP server using ngrok and axum:

Cargo.toml:

[package]
name = "ngrok-rust-demo"
version = "0.1.0"
edition = "2021"

[dependencies]
ngrok = {version = "0.14.0"}
tokio = { version = "1", features = [
    "full"
] }
axum = { version = "0.7.4", features = ["tokio"] }
async-trait = "0.1.59"
hyper = {version = "1", features = ["full"]}
hyper-util = { version = "0.1", features = [
	"full"
] }
url = "2.5.4"

src/main.rs:

#![deny(warnings)]
use axum::{routing::get, Router};
use ngrok::config::ForwarderBuilder;
use std::net::SocketAddr;
use url::Url;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // Create Axum app
    let app = Router::new().route("/", get(|| async { "Hello from Axum!" }));

    // Spawn Axum server
    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
    tokio::spawn(async move {
        axum::serve(tokio::net::TcpListener::bind(addr).await.unwrap(), app)
            .await
            .unwrap();
    });

    // Set up ngrok tunnel
    let sess1 = ngrok::Session::builder()
        .authtoken_from_env()
        .connect()
        .await?;
    let sess2 = ngrok::Session::builder()
        .authtoken_from_env()
        .connect()
        .await?;

    let _listener = sess1
        .http_endpoint()
        .domain("/* your domain*/")
        .pooling_enabled(true)
        .listen_and_forward(Url::parse("http://localhost:3000").unwrap())
        .await?;
    let _listener2 = sess2
        .http_endpoint()
        .domain("/* your domain */")
        .pooling_enabled(true)
        .listen_and_forward(Url::parse("http://localhost:8000").unwrap())
        .await?;

    // Wait indefinitely
    tokio::signal::ctrl_c().await?;
    Ok(())
}

Changelog

Changes to ngrok-rust are tracked under CHANGELOG.md.

Join the ngrok Community

• Check out our official docs
• Read about updates on our blog
• Open an issue or pull request
• Join our Slack community
• Follow us on X / Twitter (@ngrokHQ)
• Subscribe to our Youtube channel (@ngrokHQ)

License

This project is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in ngrok by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Modules

• config
  Tunnel and endpoint configuration types.
• conn
  Types for working with ngrok connections.
• forwarder
  Types for working with connection forwarders.
• prelude
  A prelude of traits for working with ngrok types.
• session
  Types for working with the ngrok session.
• tunnel
  Types for working with ngrok tunnels.

Structs

• EdgeConn
  A connection via an ngrok Edge.
• EndpointConn
  A connection via an ngrok Endpoint.
• Session
  An ngrok session.

Traits

• Conn
  An incoming connection over an ngrok tunnel. Effectively a trait alias for async read+write, plus connection info.
• Error
  An error that may have an ngrok error code. All ngrok error codes are documented at https://ngrok.com/docs/errors
• Tunnel
  An ngrok tunnel.