Session Builder#

The ngrok Agent SDK for Python

class ngrok.SessionBuilder#

The builder for an ngrok session.

authtoken(authtoken)#

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.

authtoken_from_env()#: Shortcut for calling SessionBuilder::authtoken with the value of the NGROK_AUTHTOKEN environment variable.

ca_cert(cert_bytes)#

Configures the TLS certificate 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. Pass in the bytes of the certificate to be used to validate the connection, then override the address to connect to via the server_addr call.

Roughly corresponds to the root_cas parameter in the ngrok docs.

client_info(client_type, version, comments=Ellipsis)#

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.

connect()#: Attempt to establish an ngrok session using the current configuration.

handle_disconnection(handler)#: Configures a function which is called to after a disconnection to the ngrok service. In the event of network disruptions, it will be called each time the session reconnects. The handler is given the address that will be used to connect the session to, e.g. “example.com:443”, and the message from the error that occurred. Raising an exception in the handler will cause the Session to throw an uncaught error instead of reconnecting.

handle_heartbeat(handler)#

Call the provided handler whenever a heartbeat response is received, with the latency in milliseconds.

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

handle_restart_command(handler)#

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.

handle_stop_command(handler)#

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.

handle_update_command(handler)#

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.

heartbeat_interval(heartbeat_interval)#

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.

heartbeat_tolerance(heartbeat_tolerance)#

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.

metadata(metadata)#

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.

root_cas(root_cas)#

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

server_addr(addr)#

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.