Struct ngrok::session::SessionBuilder

pub struct SessionBuilder { /* private fields */ }

The builder for an ngrok Session.

Implementations

impl SessionBuilder

pub fn authtoken(&mut self, authtoken: impl Into<String>) -> &mut Self

Configures the session to authenticate with the provided authtoken. You can find your existing authtoken or create a new one in the ngrok dashboard.

See the authtoken parameter in the ngrok docs for additional details.

pub fn authtoken_from_env(&mut self) -> &mut Self

Shortcut for calling SessionBuilder::authtoken with the value of the NGROK_AUTHTOKEN environment variable.

pub fn heartbeat_interval( &mut self, heartbeat_interval: Duration ) -> Result<&mut Self, InvalidHeartbeatInterval>

Configures how often the session will send heartbeat messages to the ngrok service to check session liveness.

See the heartbeat_interval parameter in the ngrok docs for additional details.

pub fn heartbeat_tolerance( &mut self, heartbeat_tolerance: Duration ) -> Result<&mut Self, InvalidHeartbeatTolerance>

Configures the duration to wait for a response to a heartbeat before assuming the session connection is dead and attempting to reconnect.

See the heartbeat_tolerance parameter in the ngrok docs for additional details.

pub fn metadata(&mut self, metadata: impl Into<String>) -> &mut Self

Configures the opaque, machine-readable metadata string for this session. Metadata is made available to you in the ngrok dashboard and the Agents API resource. It is a useful way to allow you to uniquely identify sessions. We suggest encoding the value in a structured format like JSON.

See the metdata parameter in the ngrok docs for additional details.

pub fn server_addr( &mut self, addr: impl Into<String> ) -> Result<&mut Self, InvalidServerAddr>

Configures the network address to dial to connect to the ngrok service. Use this option only if you are connecting to a custom agent ingress.

See the server_addr parameter in the ngrok docs for additional details.

pub fn root_cas( &mut self, root_cas: impl Into<String> ) -> Result<&mut Self, Error>

Sets the file path to a default certificate in PEM format to validate ngrok Session TLS connections. Setting to “trusted” is the default, using the ngrok CA certificate. Setting to “host” will verify using the certificates on the host operating system. A client config set via tls_config after calling root_cas will override this value.

Corresponds to the root_cas parameter in the ngrok docs

pub fn ca_cert(&mut self, ca_cert: Bytes) -> &mut Self

Sets the default certificate in PEM format to validate ngrok Session TLS connections. A client config set via tls_config will override this value.

Roughly corresponds to the “path to a certificate PEM file” option in the root_cas parameter in the ngrok docs

pub fn tls_config(&mut self, config: ClientConfig) -> &mut Self

Configures the TLS client used to connect to the ngrok service while establishing the session. Use this option only if you are connecting through a man-in-the-middle or deep packet inspection proxy. Passed to the connect callback set with SessionBuilder::connect.

Roughly corresponds to the root_cas parameter in the ngrok docs, but allows for deeper TLS configuration.

pub fn connector(&mut self, connect: impl Connector) -> &mut Self

Configures a function which is called to establish the connection to the ngrok service. Use this option if you need to connect through an outbound proxy. In the event of network disruptions, it will be called each time the session reconnects.

pub fn proxy_url( &mut self, url: Url ) -> Result<&mut Self, ProxyUnsupportedError>

Configures the session to connect to ngrok through an outbound HTTP or SOCKS5 proxy. This parameter is ignored if you override the connector with SessionBuilder::connector.

See the proxy url parameter in the ngrok docs for additional details.

pub fn handle_stop_command( &mut self, handler: impl CommandHandler<Stop> ) -> &mut Self

Configures a function which is called when the ngrok service requests that this Session stops. Your application may choose to interpret this callback as a request to terminate the Session or the entire process.

Errors returned by this function will be visible to the ngrok dashboard or API as the response to the Stop operation.

Do not block inside this callback. It will cause the Dashboard or API stop operation to time out. Do not call std::process::exit inside this callback, it will also cause the operation to time out.

pub fn handle_restart_command( &mut self, handler: impl CommandHandler<Restart> ) -> &mut Self

Configures a function which is called when the ngrok service requests that this Session updates. Your application may choose to interpret this callback as a request to restart the Session or the entire process.

Errors returned by this function will be visible to the ngrok dashboard or API as the response to the Restart operation.

Do not block inside this callback. It will cause the Dashboard or API stop operation to time out. Do not call std::process::exit inside this callback, it will also cause the operation to time out.

pub fn handle_update_command( &mut self, handler: impl CommandHandler<Update> ) -> &mut Self

Configures a function which is called when the ngrok service requests that this Session updates. Your application may choose to interpret this callback as a request to update its configuration, itself, or to invoke some other application-specific behavior.

Errors returned by this function will be visible to the ngrok dashboard or API as the response to the Restart operation.

Do not block inside this callback. It will cause the Dashboard or API stop operation to time out. Do not call std::process::exit inside this callback, it will also cause the operation to time out.

pub fn handle_heartbeat(&mut self, callback: impl HeartbeatHandler) -> &mut Self

Call the provided handler whenever a heartbeat response is received.

If the handler returns an error, the heartbeat task will exit, resulting in the session eventually dying as well.

pub fn client_info( &mut self, client_type: impl Into<String>, version: impl Into<String>, comments: Option<impl Into<String>> ) -> &mut Self

Add client type and version information for a client application.

This is a way for applications and library consumers of this crate identify themselves.

This will add a new entry to the User-Agent field in the “most significant” (first) position. Comments must follow RFC 7230 or a connection error may occur.

pub async fn connect(&self) -> Result<Session, ConnectError>

Begins a new ngrok Session by connecting to the ngrok service. connect blocks until the session is successfully established or fails with an error.

Trait Implementations

impl Clone for SessionBuilder

fn clone(&self) -> SessionBuilder

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for SessionBuilder

fn default() -> Self

Returns the “default value” for a type.