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.