HTTP Listener Builder#

The ngrok Agent SDK for Python

class ngrok.HttpListenerBuilder#

An ngrok listener backing an HTTP endpoint.

allow_cidr(cidr)#

Restriction placed on the origin of incoming connections to the edge to only allow these CIDR ranges. Call multiple times to add additional CIDR ranges. See IP restrictions in the ngrok docs for additional details.

allow_user_agent(regex)#

A set of regular expressions used to match User-Agents that will be allowed. On request, the User Agent Filter module will check the incoming User-Agent header value against the list of defined allow and deny regular expression rules. See User Agent Filter in the ngrok docs for additional details.

app_protocol(app_protocol)#

The L7 protocol to use for this edge: “http1” or “http2”.

basic_auth(username, password)#

Credentials for basic authentication. If not called, basic authentication is disabled.

circuit_breaker(circuit_breaker)#

Reject requests when 5XX responses exceed this ratio. Disabled when 0. See Circuit Breaker in the ngrok docs for additional details.

compression()#

Enable gzip compression for HTTP responses. See Compression in the ngrok docs for additional details.

deny_cidr(cidr)#

Restriction placed on the origin of incoming connections to the edge to deny these CIDR ranges. Call multiple times to add additional CIDR ranges. See IP restrictions in the ngrok docs for additional details.

deny_user_agent(regex)#

A set of regular expressions used to match User-Agents that will be denied. On request, the User Agent Filter module will check the incoming User-Agent header value against the list of defined allow and deny regular expression rules. See User Agent Filter in the ngrok docs for additional details.

domain(domain)#

The domain to request for this edge, any valid domain or hostname that you have previously registered with ngrok. If using a custom domain, this requires registering in the ngrok dashboard and setting a DNS CNAME value.

forwards_to(forwards_to)#

Listener backend metadata. Viewable via the dashboard and API, but has no bearing on listener behavior.

To automatically forward connections, you can use listen_and_forward, or listen_and_serve on the Listener Builder.

listen()#

Begin listening for new connections on this listener.

listen_and_forward(to_url)#

Begin listening for new connections on this listener and forwarding them to the given url. This url can be either a TCP/HTTP address or a file socket path, for example: “http://localhost:8080”, “https://192.168.1.100:8443”, or for file socket paths on Linux/Darwin “unix:///path/to/unix.sock”.

Parameters:

to_url – The URL to forward traffic on to

Returns:

A task to await for the Listener linked with the server.

Return type:

Task

listen_and_serve(server)#

Begin listening for new connections on this listener and forwarding them to the given http server.

Parameters:

server (http.server.HTTPServer or None) – The server to link with a Listener.

Returns:

A task to await for the Listener linked with the server.

Return type:

Task

metadata(metadata)#

Listener-specific opaque metadata. Viewable via the API.

mutual_tlsca(mutual_tlsca)#

Certificates to use for client authentication at the ngrok edge. See Mutual TLS in the ngrok docs for additional details.

oauth(allow_emails=None, allow_domains=None, scopes=None, client_id=None, client_secret=None)#

OAuth configuration. If not called, OAuth is disabled. See OAuth in the ngrok docs for additional details.

Parameters:

  • provider (str) – The name of the OAuth provider to use.

  • allow_emails (list or None) – A list of email addresses to allow.

  • allow_domains (list or None) – A list of domain names to allow.

  • scopes (list or None) – A list of scopes.

  • client_id (str or None) – The optional OAuth client ID, required for scopes.

  • client_secret (str or None) – The optional OAuth client secret, required for scopes.

oidc(client_id, client_secret, allow_emails=None, allow_domains=None, scopes=None)#

OIDC configuration. If not called, OIDC is disabled. See OpenID Connect in the ngrok docs for additional details.

Parameters:

  • issuer_url (str) – The name of the OIDC issuer URL to use.

  • client_id (str) – The OIDC client ID.

  • client_secret (str) – The OIDC client secret.

  • allow_emails (list or None) – A list of email addresses to allow.

  • allow_domains (list or None) – A list of domain names to allow.

  • scopes (list or None) – A list of scopes.

policy(policy_config)#

Traffic Policy configuration. :param str policy_config: Traffic policy configuration to be attached to the listener.

proxy_proto(proxy_proto)#

The version of PROXY protocol to use with this listener “1”, “2”, or “” if not using.

remove_request_header(name)#

Removes a header from requests to this edge. See Request Headers in the ngrok docs for additional details.

remove_response_header(name)#

Removes a header from responses from this edge. See Response Headers in the ngrok docs for additional details.

request_header(name, value)#

Adds a header to all requests to this edge. See Request Headers in the ngrok docs for additional details.

response_header(name, value)#

Adds a header to all responses coming from this edge. See Response Headers in the ngrok docs for additional details.

scheme(scheme)#

The scheme that this edge should use. “HTTPS” or “HTTP”, defaults to “HTTPS”.

verify_upstream_tls(verify_upstream_tls)#

Whether to disable certificate verification for this listener.

webhook_verification(provider, secret)#

WebhookVerification configuration. If not called, WebhookVerification is disabled. See Webhook Verification in the ngrok docs for additional details.

websocket_tcp_conversion()#

Convert incoming websocket connections to TCP-like streams.