├── docs
    ├── .nojekyll
    ├── _static
    │   ├── empty
    │   ├── scripts
    │   │   ├── furo-extensions.js
    │   │   ├── furo.js.LICENSE.txt
    │   │   └── furo.js
    │   ├── file.png
    │   ├── minus.png
    │   ├── plus.png
    │   ├── documentation_options.js
    │   ├── debug.css
    │   ├── doctools.js
    │   ├── styles
    │   │   ├── furo-extensions.css
    │   │   └── furo-extensions.css.map
    │   ├── sphinx_highlight.js
    │   ├── language_data.js
    │   └── skeleton.css
    ├── objects.inv
    ├── .doctrees
    │   ├── index.doctree
    │   ├── module.doctree
    │   ├── listener.doctree
    │   ├── session.doctree
    │   ├── environment.pickle
    │   ├── ngrok_session.doctree
    │   ├── ngrok_tunnel.doctree
    │   ├── session_builder.doctree
    │   ├── http_listener_builder.doctree
    │   ├── ngrok_session_builder.doctree
    │   ├── tcp_listener_builder.doctree
    │   ├── tls_listener_builder.doctree
    │   ├── labeled_listener_builder.doctree
    │   ├── ngrok_tcp_tunnel_builder.doctree
    │   ├── ngrok_tls_tunnel_builder.doctree
    │   ├── ngrok_http_tunnel_builder.doctree
    │   └── ngrok_labeled_tunnel_builder.doctree
    ├── _sources
    │   ├── listener.rst.txt
    │   ├── session.rst.txt
    │   ├── session_builder.rst.txt
    │   ├── tls_listener_builder.rst.txt
    │   ├── tcp_listener_builder.rst.txt
    │   ├── http_listener_builder.rst.txt
    │   ├── labeled_listener_builder.rst.txt
    │   ├── module.rst.txt
    │   └── index.rst.txt
    ├── .buildinfo
    └── search.html
├── .envrc
├── python
    └── ngrok
    │   ├── py.typed
    │   ├── mypy.ini
    │   ├── __init__.py
    │   ├── ngrok_parser.py
    │   ├── __main__.py
    │   └── ngrok.pyi
├── .python-version
├── doc_source
    ├── _static
    │   └── empty
    ├── session.rst
    ├── listener.rst
    ├── session_builder.rst
    ├── tls_listener_builder.rst
    ├── http_listener_builder.rst
    ├── tcp_listener_builder.rst
    ├── labeled_listener_builder.rst
    ├── module.rst
    ├── index.rst
    └── conf.py
├── examples
    ├── djangosite
    │   ├── db.sqlite3
    │   ├── djangosite
    │   │   ├── __init__.py
    │   │   ├── asgi.py
    │   │   ├── wsgi.py
    │   │   ├── urls.py
    │   │   ├── ngrok-asgi.py
    │   │   └── settings.py
    │   └── manage.py
    ├── gradio
    │   ├── requirements.txt
    │   ├── gradio-asgi.py
    │   └── gradio-ngrok.py
    ├── openplayground
    │   ├── requirements.txt
    │   └── run.py
    ├── gpt4all
    │   ├── requirements.txt
    │   └── run.py
    ├── streamlit
    │   ├── streamlit-demo.py
    │   └── streamlit-ngrok.py
    ├── requirements.txt
    ├── flask-ngrok.py
    ├── aiohttp-ngrok.py
    ├── ngrok-http-minimal.py
    ├── ngrok-forward-minimal.py
    ├── hypercorn-http2-ngrok.py
    ├── uvicorn-ngrok.py
    ├── tornado-ngrok.py
    ├── domain.crt
    ├── django-single-file.py
    ├── domain.key
    ├── ngrok-tcp.py
    ├── ngrok-tls.py
    ├── ngrok-forward-full.py
    ├── ngrok-labeled.py
    └── ngrok-http-full.py
├── .gitattributes
├── rustfmt.toml
├── src
    ├── build.rs
    ├── tcp.rs
    ├── logging.rs
    ├── tls.rs
    ├── lib.rs
    ├── wrapper.rs
    └── listener_builder.rs
├── .cargo
    └── config.toml
├── uv.lock
├── pytest.ini
├── requirements.txt
├── CONTRIBUTING.md
├── RELEASE.md
├── LICENSE-MIT
├── .github
    └── workflows
    │   ├── rust-cache
    │       └── action.yml
    │   ├── publish.yml
    │   ├── ci.yml
    │   └── build.yml
├── Cargo.toml
├── pyproject.toml
├── test
    └── test_main.py
├── flake.lock
├── CODE_OF_CONDUCT.md
├── CHANGELOG.md
├── .gitignore
├── flake.nix
└── Makefile


/docs/.nojekyll:
--------------------------------------------------------------------------------
1 | 


--------------------------------------------------------------------------------
/docs/_static/empty:
--------------------------------------------------------------------------------
1 | 


--------------------------------------------------------------------------------
/.envrc:
--------------------------------------------------------------------------------
1 | use flake
2 | 


--------------------------------------------------------------------------------
/python/ngrok/py.typed:
--------------------------------------------------------------------------------
1 | 


--------------------------------------------------------------------------------
/.python-version:
--------------------------------------------------------------------------------
1 | 3.10.13
2 | 


--------------------------------------------------------------------------------
/doc_source/_static/empty:
--------------------------------------------------------------------------------
1 | 


--------------------------------------------------------------------------------
/examples/djangosite/db.sqlite3:
--------------------------------------------------------------------------------
1 | 


--------------------------------------------------------------------------------
/docs/_static/scripts/furo-extensions.js:
--------------------------------------------------------------------------------
1 | 


--------------------------------------------------------------------------------
/examples/djangosite/djangosite/__init__.py:
--------------------------------------------------------------------------------
1 | 


--------------------------------------------------------------------------------
/.gitattributes:
--------------------------------------------------------------------------------
1 | docs/**    linguist-generated=true
2 | 


--------------------------------------------------------------------------------
/examples/gradio/requirements.txt:
--------------------------------------------------------------------------------
1 | gradio==3.28.0
2 | 


--------------------------------------------------------------------------------
/python/ngrok/mypy.ini:
--------------------------------------------------------------------------------
1 | [mypy]
2 | implicit_optional = True
3 | 


--------------------------------------------------------------------------------
/examples/openplayground/requirements.txt:
--------------------------------------------------------------------------------
1 | openplayground==0.1.5
2 | 


--------------------------------------------------------------------------------
/docs/objects.inv:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ngrok/ngrok-python/HEAD/docs/objects.inv


--------------------------------------------------------------------------------
/docs/_static/file.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ngrok/ngrok-python/HEAD/docs/_static/file.png


--------------------------------------------------------------------------------
/docs/_static/minus.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ngrok/ngrok-python/HEAD/docs/_static/minus.png


--------------------------------------------------------------------------------
/docs/_static/plus.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ngrok/ngrok-python/HEAD/docs/_static/plus.png


--------------------------------------------------------------------------------
/examples/gpt4all/requirements.txt:
--------------------------------------------------------------------------------
1 | pygpt4all==1.1.0
2 | gradio==3.28.3
3 | pyllamacpp==2.1.3
4 | 


--------------------------------------------------------------------------------
/docs/.doctrees/index.doctree:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ngrok/ngrok-python/HEAD/docs/.doctrees/index.doctree


--------------------------------------------------------------------------------
/docs/.doctrees/module.doctree:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ngrok/ngrok-python/HEAD/docs/.doctrees/module.doctree


--------------------------------------------------------------------------------
/docs/.doctrees/listener.doctree:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ngrok/ngrok-python/HEAD/docs/.doctrees/listener.doctree


--------------------------------------------------------------------------------
/docs/.doctrees/session.doctree:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ngrok/ngrok-python/HEAD/docs/.doctrees/session.doctree


--------------------------------------------------------------------------------
/docs/.doctrees/environment.pickle:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ngrok/ngrok-python/HEAD/docs/.doctrees/environment.pickle


--------------------------------------------------------------------------------
/docs/.doctrees/ngrok_session.doctree:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ngrok/ngrok-python/HEAD/docs/.doctrees/ngrok_session.doctree


--------------------------------------------------------------------------------
/docs/.doctrees/ngrok_tunnel.doctree:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ngrok/ngrok-python/HEAD/docs/.doctrees/ngrok_tunnel.doctree


--------------------------------------------------------------------------------
/docs/.doctrees/session_builder.doctree:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ngrok/ngrok-python/HEAD/docs/.doctrees/session_builder.doctree


--------------------------------------------------------------------------------
/rustfmt.toml:
--------------------------------------------------------------------------------
1 | imports_layout = "Vertical"
2 | imports_granularity = "Crate"
3 | group_imports = "StdExternalCrate"
4 | edition = "2021"


--------------------------------------------------------------------------------
/doc_source/session.rst:
--------------------------------------------------------------------------------
1 | Session
2 | =====================================
3 | 
4 | .. automodule:: ngrok
5 |    :members: Session
6 | 
7 | 


--------------------------------------------------------------------------------
/src/build.rs:
--------------------------------------------------------------------------------
1 | fn main() -> Result<(), &'static str> {
2 |     pyo3_build_config::add_extension_module_link_args();
3 |     Ok(())
4 | }
5 | 


--------------------------------------------------------------------------------
/doc_source/listener.rst:
--------------------------------------------------------------------------------
1 | Listener
2 | =====================================
3 | 
4 | .. automodule:: ngrok
5 |    :members: Listener
6 | 
7 | 


--------------------------------------------------------------------------------
/docs/.doctrees/http_listener_builder.doctree:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ngrok/ngrok-python/HEAD/docs/.doctrees/http_listener_builder.doctree


--------------------------------------------------------------------------------
/docs/.doctrees/ngrok_session_builder.doctree:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ngrok/ngrok-python/HEAD/docs/.doctrees/ngrok_session_builder.doctree


--------------------------------------------------------------------------------
/docs/.doctrees/tcp_listener_builder.doctree:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ngrok/ngrok-python/HEAD/docs/.doctrees/tcp_listener_builder.doctree


--------------------------------------------------------------------------------
/docs/.doctrees/tls_listener_builder.doctree:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ngrok/ngrok-python/HEAD/docs/.doctrees/tls_listener_builder.doctree


--------------------------------------------------------------------------------
/examples/streamlit/streamlit-demo.py:
--------------------------------------------------------------------------------
1 | import streamlit as st
2 | 
3 | x = st.slider("Select a value")
4 | st.write(x, "squared is", x * x)
5 | 


--------------------------------------------------------------------------------
/docs/.doctrees/labeled_listener_builder.doctree:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ngrok/ngrok-python/HEAD/docs/.doctrees/labeled_listener_builder.doctree


--------------------------------------------------------------------------------
/docs/.doctrees/ngrok_tcp_tunnel_builder.doctree:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ngrok/ngrok-python/HEAD/docs/.doctrees/ngrok_tcp_tunnel_builder.doctree


--------------------------------------------------------------------------------
/docs/.doctrees/ngrok_tls_tunnel_builder.doctree:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ngrok/ngrok-python/HEAD/docs/.doctrees/ngrok_tls_tunnel_builder.doctree


--------------------------------------------------------------------------------
/docs/_sources/listener.rst.txt:
--------------------------------------------------------------------------------
1 | Listener
2 | =====================================
3 | 
4 | .. automodule:: ngrok
5 |    :members: Listener
6 | 
7 | 


--------------------------------------------------------------------------------
/docs/_sources/session.rst.txt:
--------------------------------------------------------------------------------
1 | Session
2 | =====================================
3 | 
4 | .. automodule:: ngrok
5 |    :members: Session
6 | 
7 | 


--------------------------------------------------------------------------------
/python/ngrok/__init__.py:
--------------------------------------------------------------------------------
1 | from .ngrok import *
2 | 
3 | __doc__ = ngrok.__doc__
4 | if hasattr(ngrok, "__all__"):
5 |     __all__ = ngrok.__all__
6 | 


--------------------------------------------------------------------------------
/.cargo/config.toml:
--------------------------------------------------------------------------------
1 | [target.aarch64-apple-darwin]
2 | rustflags = [
3 |   "-C", "link-arg=-undefined",
4 |   "-C", "link-arg=dynamic_lookup",
5 | ]
6 | 


--------------------------------------------------------------------------------
/docs/.doctrees/ngrok_http_tunnel_builder.doctree:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ngrok/ngrok-python/HEAD/docs/.doctrees/ngrok_http_tunnel_builder.doctree


--------------------------------------------------------------------------------
/docs/.doctrees/ngrok_labeled_tunnel_builder.doctree:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ngrok/ngrok-python/HEAD/docs/.doctrees/ngrok_labeled_tunnel_builder.doctree


--------------------------------------------------------------------------------
/doc_source/session_builder.rst:
--------------------------------------------------------------------------------
1 | Session Builder
2 | =====================================
3 | 
4 | .. automodule:: ngrok
5 |    :members: SessionBuilder
6 | 
7 | 


--------------------------------------------------------------------------------
/doc_source/tls_listener_builder.rst:
--------------------------------------------------------------------------------
1 | TLS Listener Builder
2 | =====================================
3 | 
4 | .. automodule:: ngrok
5 |    :members: TlsListenerBuilder


--------------------------------------------------------------------------------
/docs/_sources/session_builder.rst.txt:
--------------------------------------------------------------------------------
1 | Session Builder
2 | =====================================
3 | 
4 | .. automodule:: ngrok
5 |    :members: SessionBuilder
6 | 
7 | 


--------------------------------------------------------------------------------
/uv.lock:
--------------------------------------------------------------------------------
1 | version = 1
2 | revision = 2
3 | requires-python = ">=3.12"
4 | 
5 | [[package]]
6 | name = "ngrok"
7 | version = "1.5.0"
8 | source = { editable = "." }
9 | 


--------------------------------------------------------------------------------
/docs/_sources/tls_listener_builder.rst.txt:
--------------------------------------------------------------------------------
1 | TLS Listener Builder
2 | =====================================
3 | 
4 | .. automodule:: ngrok
5 |    :members: TlsListenerBuilder


--------------------------------------------------------------------------------
/doc_source/http_listener_builder.rst:
--------------------------------------------------------------------------------
1 | HTTP Listener Builder
2 | =====================================
3 | 
4 | .. automodule:: ngrok
5 |    :members: HttpListenerBuilder
6 | 
7 | 


--------------------------------------------------------------------------------
/doc_source/tcp_listener_builder.rst:
--------------------------------------------------------------------------------
1 | TCP Listener Builder
2 | =====================================
3 | 
4 | .. automodule:: ngrok
5 |    :members: TcpListenerBuilder
6 | 
7 | 


--------------------------------------------------------------------------------
/docs/_sources/tcp_listener_builder.rst.txt:
--------------------------------------------------------------------------------
1 | TCP Listener Builder
2 | =====================================
3 | 
4 | .. automodule:: ngrok
5 |    :members: TcpListenerBuilder
6 | 
7 | 


--------------------------------------------------------------------------------
/doc_source/labeled_listener_builder.rst:
--------------------------------------------------------------------------------
1 | Labeled Listener Builder
2 | =====================================
3 | 
4 | .. automodule:: ngrok
5 |    :members: LabeledListenerBuilder
6 | 
7 | 


--------------------------------------------------------------------------------
/docs/_sources/http_listener_builder.rst.txt:
--------------------------------------------------------------------------------
1 | HTTP Listener Builder
2 | =====================================
3 | 
4 | .. automodule:: ngrok
5 |    :members: HttpListenerBuilder
6 | 
7 | 


--------------------------------------------------------------------------------
/docs/_sources/labeled_listener_builder.rst.txt:
--------------------------------------------------------------------------------
1 | Labeled Listener Builder
2 | =====================================
3 | 
4 | .. automodule:: ngrok
5 |    :members: LabeledListenerBuilder
6 | 
7 | 


--------------------------------------------------------------------------------
/examples/requirements.txt:
--------------------------------------------------------------------------------
1 | aiohttp==3.8.4
2 | Django==4.1.7
3 | Flask==2.2.3
4 | gunicorn==20.1.0
5 | Hypercorn==0.16.0
6 | streamlit==1.22.0
7 | tornado==6.3.1
8 | uvicorn==0.21.0
9 | Werkzeug==2.2.2


--------------------------------------------------------------------------------
/pytest.ini:
--------------------------------------------------------------------------------
1 | [pytest]
2 | timeout = 60
3 | log_cli = true
4 | log_cli_level = DEBUG
5 | log_cli_format = %(asctime)s [%(levelname)8s] %(message)s (%(filename)s:%(lineno)s)
6 | log_cli_date_format = %Y-%m-%d %H:%M:%S
7 | 
8 | 


--------------------------------------------------------------------------------
/doc_source/module.rst:
--------------------------------------------------------------------------------
1 | Ngrok Module
2 | =====================================
3 | 
4 | .. automodule:: ngrok
5 |    :members: connect, default, disconnect, fd, forward, getsockname, kill, listen, log_level, pipe_name, werkzeug_develop
6 | 
7 | 


--------------------------------------------------------------------------------
/docs/_sources/module.rst.txt:
--------------------------------------------------------------------------------
1 | Ngrok Module
2 | =====================================
3 | 
4 | .. automodule:: ngrok
5 |    :members: connect, default, disconnect, fd, forward, getsockname, kill, listen, log_level, pipe_name, werkzeug_develop
6 | 
7 | 


--------------------------------------------------------------------------------
/docs/_static/scripts/furo.js.LICENSE.txt:
--------------------------------------------------------------------------------
1 | /*!
2 |  * gumshoejs v5.1.2 (patched by @pradyunsg)
3 |  * A simple, framework-agnostic scrollspy script.
4 |  * (c) 2019 Chris Ferdinandi
5 |  * MIT License
6 |  * http://github.com/cferdinandi/gumshoe
7 |  */
8 | 


--------------------------------------------------------------------------------
/docs/.buildinfo:
--------------------------------------------------------------------------------
1 | # Sphinx build info version 1
2 | # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
3 | config: 72ac09c0c03a2f7ae3823be5ece6cc7e
4 | tags: 645f666f9bcd5a90fca523b33c5a78b7
5 | 


--------------------------------------------------------------------------------
/examples/flask-ngrok.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python
 2 | 
 3 | import flask, logging, ngrok
 4 | 
 5 | logging.basicConfig(level=logging.INFO)
 6 | listener = ngrok.werkzeug_develop()
 7 | 
 8 | app = flask.Flask(__name__)
 9 | 
10 | 
11 | @app.route("/")
12 | def hello():
13 |     return "Hello, World!"
14 | 
15 | 
16 | app.run()
17 | 


--------------------------------------------------------------------------------
/examples/aiohttp-ngrok.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python
 2 | 
 3 | from aiohttp import web
 4 | import logging, ngrok
 5 | 
 6 | 
 7 | async def hello(request):
 8 |     return web.Response(text="Online in One Line")
 9 | 
10 | 
11 | logging.basicConfig(level=logging.INFO)
12 | app = web.Application()
13 | app.add_routes([web.get("/", hello)])
14 | web.run_app(app, sock=ngrok.listen())
15 | 


--------------------------------------------------------------------------------
/requirements.txt:
--------------------------------------------------------------------------------
 1 | aiohttp==3.9.5 # async HTTP client/server framework
 2 | black==23.3.0 # code formatter
 3 | furo==2024.8.6 # customisable Sphinx theme
 4 | maturin==1.9.1 # build and publish Python packages
 5 | mypy==1.15.0 # static type checker
 6 | myst-parser==4.0.1 # Sphinx extension for Markdown
 7 | pytest-xdist==3.6.1 # run tests in parallel
 8 | pytest-timeout==2.3.1 # timeout tests
 9 | requests==2.32.3 # HTTP library
10 | Sphinx==8.1.3 # documentation tool
11 | 


--------------------------------------------------------------------------------
/docs/_static/documentation_options.js:
--------------------------------------------------------------------------------
 1 | var DOCUMENTATION_OPTIONS = {
 2 |     URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
 3 |     VERSION: '',
 4 |     LANGUAGE: 'en',
 5 |     COLLAPSE_INDEX: false,
 6 |     BUILDER: 'html',
 7 |     FILE_SUFFIX: '.html',
 8 |     LINK_SUFFIX: '.html',
 9 |     HAS_SOURCE: true,
10 |     SOURCELINK_SUFFIX: '.txt',
11 |     NAVIGATION_WITH_KEYS: false,
12 |     SHOW_SEARCH_SUMMARY: true,
13 |     ENABLE_SEARCH_SHORTCUTS: true,
14 | };


--------------------------------------------------------------------------------
/examples/djangosite/djangosite/asgi.py:
--------------------------------------------------------------------------------
 1 | """
 2 | ASGI config for djangosite project.
 3 | 
 4 | It exposes the ASGI callable as a module-level variable named ``application``.
 5 | 
 6 | For more information on this file, see
 7 | https://docs.djangoproject.com/en/4.1/howto/deployment/asgi/
 8 | """
 9 | 
10 | import os
11 | 
12 | from django.core.asgi import get_asgi_application
13 | 
14 | os.environ.setdefault("DJANGO_SETTINGS_MODULE", "djangosite.settings")
15 | 
16 | application = get_asgi_application()
17 | 


--------------------------------------------------------------------------------
/examples/djangosite/djangosite/wsgi.py:
--------------------------------------------------------------------------------
 1 | """
 2 | WSGI config for djangosite project.
 3 | 
 4 | It exposes the WSGI callable as a module-level variable named ``application``.
 5 | 
 6 | For more information on this file, see
 7 | https://docs.djangoproject.com/en/4.1/howto/deployment/wsgi/
 8 | """
 9 | 
10 | import os
11 | 
12 | from django.core.wsgi import get_wsgi_application
13 | 
14 | os.environ.setdefault("DJANGO_SETTINGS_MODULE", "djangosite.settings")
15 | 
16 | application = get_wsgi_application()
17 | 


--------------------------------------------------------------------------------
/examples/openplayground/run.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python
 2 | 
 3 | import argparse, logging, ngrok
 4 | from server import app
 5 | 
 6 | # setup ngrok
 7 | parser = argparse.ArgumentParser()
 8 | parser.add_argument("--host", help="Hostname or IP address", default="localhost")
 9 | parser.add_argument("--port", help="Port number", type=int, default=5432)
10 | args, unknown = parser.parse_known_args()
11 | logging.basicConfig(level=logging.INFO)
12 | listener = ngrok.forward(f"{args.host}:{args.port}", authtoken_from_env=True)
13 | 
14 | # call the runner
15 | app.run()
16 | 


--------------------------------------------------------------------------------
/examples/gradio/gradio-asgi.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python
 2 | #
 3 | # Run this with:
 4 | # ngrok-asgi uvicorn gradio-asgi:demo.app --port 7860 --reload
 5 | 
 6 | import asyncio, ngrok, os, sys
 7 | import gradio as gr
 8 | 
 9 | 
10 | def greet(name):
11 |     return "Hello " + name + "!"
12 | 
13 | 
14 | demo = gr.Interface(fn=greet, inputs="text", outputs="text")
15 | 
16 | try:
17 |     # 'gradio' command line already has a loop running via uvicorn
18 |     running_loop = asyncio.get_running_loop()
19 | except RuntimeError:
20 |     # only call launch if not in uvicorn already
21 |     demo.launch()
22 | 


--------------------------------------------------------------------------------
/examples/ngrok-http-minimal.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python
 2 | 
 3 | from http.server import HTTPServer, BaseHTTPRequestHandler
 4 | import logging, ngrok
 5 | 
 6 | 
 7 | class HelloHandler(BaseHTTPRequestHandler):
 8 |     def do_GET(self):
 9 |         body = bytes("Hello", "utf-8")
10 |         self.protocol_version = "HTTP/1.1"
11 |         self.send_response(200)
12 |         self.send_header("Content-Length", len(body))
13 |         self.end_headers()
14 |         self.wfile.write(body)
15 | 
16 | 
17 | logging.basicConfig(level=logging.INFO)
18 | server = HTTPServer(("localhost", 0), HelloHandler)
19 | ngrok.listen(server)
20 | server.serve_forever()
21 | 


--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
 1 | # Contributing to ngrok-python
 2 | 
 3 | Thank you for deciding to contribute to ngrok-python!
 4 | 
 5 | ## Reporting a bug
 6 | 
 7 | To report a bug, please [open a new issue](https://github.com/ngrok/ngrok-python/issues/new) with clear reproduction steps. We will triage and investigate these issues at a regular interval.
 8 | 
 9 | ## Contributing code
10 | 
11 | Bugfixes and small improvements are always appreciated!
12 | 
13 | For any larger changes or features, please [open a new issue](https://github.com/ngrok/ngrok-python/issues/new) first to discuss whether the change makes sense. When in doubt, it's always okay to open an issue first.
14 | 


--------------------------------------------------------------------------------
/examples/ngrok-forward-minimal.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python
 2 | 
 3 | from http.server import HTTPServer, BaseHTTPRequestHandler
 4 | import logging, ngrok, os
 5 | import asyncio
 6 | 
 7 | 
 8 | class HelloHandler(BaseHTTPRequestHandler):
 9 |     def do_GET(self):
10 |         body = bytes("Hello", "utf-8")
11 |         self.protocol_version = "HTTP/1.1"
12 |         self.send_response(200)
13 |         self.send_header("Content-Length", len(body))
14 |         self.end_headers()
15 |         self.wfile.write(body)
16 | 
17 | 
18 | logging.basicConfig(level=logging.INFO)
19 | server = HTTPServer(("localhost", 8080), HelloHandler)
20 | listener = ngrok.forward("localhost:8080", authtoken_from_env=True)
21 | server.serve_forever()
22 | 


--------------------------------------------------------------------------------
/examples/hypercorn-http2-ngrok.py:
--------------------------------------------------------------------------------
 1 | import asyncio
 2 | import ngrok
 3 | import logging
 4 | from hypercorn.config import Config
 5 | from hypercorn.asyncio import serve
 6 | 
 7 | config = Config()
 8 | 
 9 | 
10 | async def app(scope, receive, send):
11 |     await send(
12 |         {
13 |             "type": "http.response.start",
14 |             "status": 200,
15 |             "headers": [
16 |                 (b"content-type", b"text/plain"),
17 |             ],
18 |         }
19 |     )
20 |     await send(
21 |         {
22 |             "type": "http.response.body",
23 |             "body": b"hello",
24 |         }
25 |     )
26 | 
27 | 
28 | logging.basicConfig(level=logging.INFO)
29 | ngrok.forward(addr="localhost:8080", authtoken_from_env=True, app_protocol="http2")
30 | config.bind = ["localhost:8080"]
31 | asyncio.run(serve(app, config))
32 | 


--------------------------------------------------------------------------------
/examples/djangosite/djangosite/urls.py:
--------------------------------------------------------------------------------
 1 | """djangosite URL Configuration
 2 | 
 3 | The `urlpatterns` list routes URLs to views. For more information please see:
 4 |     https://docs.djangoproject.com/en/4.1/topics/http/urls/
 5 | Examples:
 6 | Function views
 7 |     1. Add an import:  from my_app import views
 8 |     2. Add a URL to urlpatterns:  path('', views.home, name='home')
 9 | Class-based views
10 |     1. Add an import:  from other_app.views import Home
11 |     2. Add a URL to urlpatterns:  path('', Home.as_view(), name='home')
12 | Including another URLconf
13 |     1. Import the include() function: from django.urls import include, path
14 |     2. Add a URL to urlpatterns:  path('blog/', include('blog.urls'))
15 | """
16 | from django.contrib import admin
17 | from django.urls import path
18 | 
19 | urlpatterns = [
20 |     path("admin/", admin.site.urls),
21 | ]
22 | 


--------------------------------------------------------------------------------
/examples/uvicorn-ngrok.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python
 2 | 
 3 | import asyncio, logging, ngrok, os, uvicorn
 4 | 
 5 | logging.basicConfig(level=logging.INFO)
 6 | 
 7 | 
 8 | async def app(scope, receive, send):
 9 |     assert scope["type"] == "http"
10 | 
11 |     await send(
12 |         {
13 |             "type": "http.response.start",
14 |             "status": 200,
15 |             "headers": [[b"content-type", b"text/plain"]],
16 |         }
17 |     )
18 |     await send(
19 |         {
20 |             "type": "http.response.body",
21 |             "body": b"Hello, world!",
22 |         }
23 |     )
24 | 
25 | 
26 | if os.name == "nt":  # windows
27 | 
28 |     async def setup():
29 |         listener = await ngrok.default()
30 |         listener.forward("localhost:8000")
31 | 
32 |     asyncio.run(setup())
33 |     uvicorn.run(app=app)
34 |     exit()
35 | 
36 | uvicorn.run(app=app, fd=ngrok.fd())
37 | 


--------------------------------------------------------------------------------
/doc_source/index.rst:
--------------------------------------------------------------------------------
 1 | .. ngrok documentation master file, created by
 2 |    sphinx-quickstart on Fri Mar 10 17:11:45 2023.
 3 |    You can adapt this file completely to your liking, but it should at least
 4 |    contain the root `toctree` directive.
 5 | 
 6 | .. include:: ../README.md
 7 |    :parser: myst_parser.sphinx_
 8 | 
 9 | API Reference
10 | =============
11 | 
12 | .. toctree::
13 |    :caption: Listener and Sessions:
14 |    :maxdepth: 1
15 | 
16 |    session_builder
17 |    session
18 |    listener
19 | 
20 | .. toctree::
21 |    :caption: Listener Builders:
22 |    :maxdepth: 1
23 | 
24 |    http_listener_builder
25 |    tcp_listener_builder
26 |    tls_listener_builder
27 |    labeled_listener_builder
28 | 
29 | .. toctree::
30 |    :caption: Module:
31 |    :maxdepth: 1
32 | 
33 |    module
34 | 
35 | Indices and tables
36 | ==================
37 | 
38 | * :ref:`genindex`
39 | * :ref:`modindex`
40 | * :ref:`search`
41 | 


--------------------------------------------------------------------------------
/RELEASE.md:
--------------------------------------------------------------------------------
 1 | Release Instructions
 2 | --------------------
 3 | 
 4 | Pre-Commit
 5 | ----------
 6 | 1. fix-n-fmt
 7 | 1. make test
 8 | 
 9 | Release
10 | -------
11 | 1. `git checkout main; git pull origin main`
12 | 1. `git checkout -b <username>/<version>`
13 | 1. Bump version number in `version` in `Cargo.toml`
14 | 1. Update CHANGELOG.md
15 | 1. make docs
16 | 1. `git add .`
17 | 1. `git commit -m '<version>'`
18 | 1. `git push origin <username>/<version>`
19 |     - Or with graphite: `gt branch track` and `gt stack submit`
20 | 1. Create a pull request off this branch
21 |     - Make sure the name of the pull request is also just the `<version>` so the workflow will know to do a release
22 |     - Do not prepend the `<version>` with `v`. For instance, if releasing `1.1.0`, the PR should be named `1.1.0`, NOT `v1.1.0`
23 | 1. Merge the pull request
24 | 1. Verify release appears on [PyPI](https://pypi.org/project/ngrok/#history)
25 | 


--------------------------------------------------------------------------------
/docs/_sources/index.rst.txt:
--------------------------------------------------------------------------------
 1 | .. ngrok documentation master file, created by
 2 |    sphinx-quickstart on Fri Mar 10 17:11:45 2023.
 3 |    You can adapt this file completely to your liking, but it should at least
 4 |    contain the root `toctree` directive.
 5 | 
 6 | .. include:: ../README.md
 7 |    :parser: myst_parser.sphinx_
 8 | 
 9 | API Reference
10 | =============
11 | 
12 | .. toctree::
13 |    :caption: Listener and Sessions:
14 |    :maxdepth: 1
15 | 
16 |    session_builder
17 |    session
18 |    listener
19 | 
20 | .. toctree::
21 |    :caption: Listener Builders:
22 |    :maxdepth: 1
23 | 
24 |    http_listener_builder
25 |    tcp_listener_builder
26 |    tls_listener_builder
27 |    labeled_listener_builder
28 | 
29 | .. toctree::
30 |    :caption: Module:
31 |    :maxdepth: 1
32 | 
33 |    module
34 | 
35 | Indices and tables
36 | ==================
37 | 
38 | * :ref:`genindex`
39 | * :ref:`modindex`
40 | * :ref:`search`
41 | 


--------------------------------------------------------------------------------
/src/tcp.rs:
--------------------------------------------------------------------------------
 1 | use pyo3::{
 2 |     pymethods,
 3 |     PyRefMut,
 4 | };
 5 | 
 6 | use crate::listener_builder::TcpListenerBuilder;
 7 | 
 8 | #[pymethods]
 9 | #[allow(dead_code)]
10 | impl TcpListenerBuilder {
11 |     /// The TCP address to request for this edge.
12 |     /// These addresses can be reserved in the `ngrok dashboard`_ to use across sessions. For example: remote_addr("2.tcp.ngrok.io:21746")
13 |     ///
14 |     /// .. _ngrok dashboard: https://dashboard.ngrok.com/cloud-edge/tcp-addresses
15 |     pub fn remote_addr(self_: PyRefMut<Self>, remote_addr: String) -> PyRefMut<Self> {
16 |         self_.set(|b| {
17 |             b.remote_addr(remote_addr);
18 |         });
19 |         self_
20 |     }
21 | 
22 |     /// Enable endpoint pooling for this listener.
23 |     pub fn pooling_enabled(self_: PyRefMut<Self>, pooling_enabled: bool) -> PyRefMut<Self> {
24 |         self_.set(|b| {
25 |             b.pooling_enabled(pooling_enabled);
26 |         });
27 |         self_
28 |     }
29 | }
30 | 


--------------------------------------------------------------------------------
/LICENSE-MIT:
--------------------------------------------------------------------------------
1 | Copyright 2022 ngrok, Inc.
2 | 
3 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
4 | 
5 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
6 | 
7 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


--------------------------------------------------------------------------------
/examples/tornado-ngrok.py:
--------------------------------------------------------------------------------
 1 | import asyncio
 2 | import tornado
 3 | 
 4 | import ngrok
 5 | 
 6 | app_port = 8889
 7 | 
 8 | 
 9 | class MainHandler(tornado.web.RequestHandler):
10 |     def get(self):
11 |         self.write("Hello, world")
12 | 
13 | 
14 | def make_app():
15 |     return tornado.web.Application(
16 |         [
17 |             (r"/", MainHandler),
18 |         ]
19 |     )
20 | 
21 | 
22 | async def setup_listener():
23 |     listen = f"localhost:{app_port}"
24 |     session = await ngrok.SessionBuilder().authtoken_from_env().connect()
25 |     listener = await (
26 |         session.http_endpoint()
27 |         # .domain('<name>.ngrok.app') # if on a paid plan, set a custom static domain
28 |         .listen()
29 |     )
30 |     print(f"Forwarding to {listen} from ingress url: {listener.url()}")
31 |     listener.forward(listen)
32 | 
33 | 
34 | async def main():
35 |     app = make_app()
36 |     app.listen(app_port)
37 |     await asyncio.Event().wait()
38 | 
39 | 
40 | if __name__ == "__main__":
41 |     asyncio.run(setup_listener())
42 |     asyncio.run(main())
43 | 


--------------------------------------------------------------------------------
/.github/workflows/rust-cache/action.yml:
--------------------------------------------------------------------------------
 1 | name: 'rust cache setup'
 2 | description: 'Set up cargo and sccache caches'
 3 | inputs: {}
 4 | outputs: {}
 5 | runs:
 6 |   using: "composite"
 7 |   steps:
 8 |     - name: configure sccache
 9 |       uses: actions/github-script@v6
10 |       with:
11 |         script: |
12 |           core.exportVariable('ACTIONS_CACHE_URL', process.env.ACTIONS_CACHE_URL || '');
13 |           core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');
14 |           core.exportVariable('SCCACHE_GHA_CACHE_TO', 'sccache-${{runner.os}}-${{github.ref_name}}');
15 |           core.exportVariable('SCCACHE_GHA_CACHE_FROM', 'sccache-${{runner.os}}-main,sccache-${{runner.os}}-');
16 |     - name: cargo registry cache
17 |       uses: actions/cache@v3
18 |       with:
19 |         key: cargo-${{ runner.os }}-${{ hashFiles('**/Cargo.toml') }}-${{ github.sha }}
20 |         restore-keys: |
21 |           cargo-${{ runner.os }}-${{ hashFiles('**/Cargo.toml') }}-
22 |           cargo-${{ runner.os }}-
23 |         path: |
24 |           ~/.cargo/registry
25 |           ~/.cargo/git


--------------------------------------------------------------------------------
/examples/domain.crt:
--------------------------------------------------------------------------------
 1 | -----BEGIN CERTIFICATE-----
 2 | MIIC+jCCAeICCQDobWtly6PonjANBgkqhkiG9w0BAQsFADA/MQswCQYDVQQGEwJV
 3 | UzERMA8GA1UECgwITm90IFJlYWwxHTAbBgNVBAMMFHJ1c3Qtc2RrLmV4YW1wbGUu
 4 | Y29tMB4XDTIyMTIwMjE4MzMxM1oXDTMyMTEyOTE4MzMxM1owPzELMAkGA1UEBhMC
 5 | VVMxETAPBgNVBAoMCE5vdCBSZWFsMR0wGwYDVQQDDBRydXN0LXNkay5leGFtcGxl
 6 | LmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKhsx8tZWzaqaz9i
 7 | gnyU9O/dCEX8qgCvU2yoeJBfGhwCnlFNQBUdBGlV+Cjf19ozagYlY6Cunu214AUR
 8 | CDHTZsgTmMhtHkJ3kWD0wgDu+uyUuW6akP1+o39lebDc6CbDV7j1ySBoPMROp5dB
 9 | pX+ltpH42CmJM6ciwfTD1uuW5LXJvb9d4HISZp2RWyHqb3a6pI7E+XLqXg/Yy9MY
10 | eqQESZMrYCjC+Sn4blGhcQhjTVU2rM5ChoDtZuL8OJQ0UYmchlch8CNc5Lvj9hAT
11 | BiafEAscGrdIAZkK50kjpcIOWPPSfjCRqz8elSQqoKFq/uQnHBF5NwmsEqE0sXhw
12 | 4UdngRMCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAKieeE6gzuxHGjVT2NKL5BFjL
13 | XKxdQhI/Tt7ClKu39Ay62fXDRznTBpGRfyWsJ5r3wmsHFogw46a2HYZHyuTMfyPY
14 | lKhE/9EPMf/faqhIa33nMBASNzuGB5yfcPaod4KJX6DBKZtIpgkm2+S6BivpuSEo
15 | DJ0lNtlR80mcVPma9KR57A0oh/UIsHXxL0qIKdaxyZYOZ1Zhtm+hzZcZA4wHkqzN
16 | olNk3SOfhC5vVFudg+5KtxPBZ/efS9sqDUstH8hmE1JnxCF9OBlHdKI4yUMnsEf7
17 | aOy11K5g7Oc3m7EB1twEQkufBAJeYzMOCji17GyJHDojNuOLkrmoLgcgDym5LQ==
18 | -----END CERTIFICATE-----
19 | 


--------------------------------------------------------------------------------
/examples/gradio/gradio-ngrok.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python
 2 | #
 3 | # For basic launch, run:
 4 | # python gradio-ngrok.py
 5 | #
 6 | # For uvicorn with reloading, run:
 7 | # gradio gradio-ngrok.py
 8 | 
 9 | import asyncio, ngrok, os, sys
10 | import gradio as gr
11 | 
12 | 
13 | def greet(name):
14 |     return "Hello " + name + "!"
15 | 
16 | 
17 | demo = gr.Interface(fn=greet, inputs="text", outputs="text")
18 | 
19 | 
20 | async def setup_listener():
21 |     listen = "localhost:7860"
22 |     session = await ngrok.SessionBuilder().authtoken_from_env().connect()
23 |     listener = await (
24 |         session.http_endpoint()
25 |         # .domain('<name>.ngrok.app') # if on a paid plan, set a custom static domain
26 |         .listen()
27 |     )
28 |     print(f"Forwarding to {listen} from ingress url: {listener.url()}")
29 |     listener.forward(listen)
30 | 
31 | 
32 | try:
33 |     # 'gradio' command line already has a loop running via uvicorn
34 |     running_loop = asyncio.get_running_loop()
35 |     running_loop.create_task(setup_listener())
36 | except RuntimeError:
37 |     asyncio.run(setup_listener())
38 |     # only call launch if not in uvicorn already
39 |     demo.launch()
40 | 


--------------------------------------------------------------------------------
/examples/streamlit/streamlit-ngrok.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python
 2 | #
 3 | # For basic launch, run:
 4 | # python streamlit-ngrok.py
 5 | 
 6 | import asyncio, ngrok
 7 | import click
 8 | 
 9 | from streamlit.web.bootstrap import run
10 | 
11 | app_port = 8501
12 | 
13 | 
14 | async def setup_listener():
15 |     listen = f"localhost:{app_port}"
16 |     session = await ngrok.SessionBuilder().authtoken_from_env().connect()
17 |     listener = await (
18 |         session.http_endpoint()
19 |         # .domain('<name>.ngrok.app') # if on a paid plan, set a custom static domain
20 |         .listen()
21 |     )
22 |     click.secho(
23 |         f"Forwarding to {listen} from ingress url: {listener.url()}",
24 |         fg="green",
25 |         bold=True,
26 |     )
27 |     listener.forward(listen)
28 | 
29 | 
30 | try:
31 |     # Check if asyncio loop is already running. If so, piggyback on it to run the ngrok listener.
32 |     running_loop = asyncio.get_running_loop()
33 |     running_loop.create_task(setup_listener())
34 | except RuntimeError:
35 |     # No existing loop is running, so we can run the ngrok listener on a new loop.
36 |     asyncio.run(setup_listener())
37 | 
38 | run("streamlit-demo.py", command_line=None, args=[], flag_options={})
39 | 


--------------------------------------------------------------------------------
/examples/django-single-file.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python
 2 | # Adapted from: https://arunrocks.com/django-application-in-one-file/
 3 | 
 4 | from django.conf import settings
 5 | from django.core.management import execute_from_command_line
 6 | from django.http import HttpResponse
 7 | from django.urls import path
 8 | import asyncio, logging, ngrok, os, sys
 9 | 
10 | # Set env variable to protect against the autoreloader.
11 | if os.getenv("NGROK_LISTENER_RUNNING") is None:
12 |     os.environ["NGROK_LISTENER_RUNNING"] = "true"
13 |     logging.basicConfig(level=logging.INFO)
14 | 
15 |     async def setup():
16 |         listener = await ngrok.default()
17 |         listener.forward("localhost:8080")
18 | 
19 |     asyncio.run(setup())
20 | 
21 | 
22 | async def home(request):
23 |     response = HttpResponse("Hello")
24 |     return response
25 | 
26 | 
27 | settings.configure(
28 |     ALLOWED_HOSTS=["*"],  # Disable host header validation
29 |     DEBUG=True,
30 |     MIDDLEWARE=[
31 |         "django.middleware.common.CommonMiddleware"
32 |     ],  # CommonMiddleware adds Content-Length header
33 |     ROOT_URLCONF=__name__,
34 |     SECRET_KEY="a-bad-secret",  # Insecure! Change this
35 | )
36 | urlpatterns = [path("", home)]
37 | 
38 | execute_from_command_line([__name__, "runserver", "8080"])
39 | 


--------------------------------------------------------------------------------
/Cargo.toml:
--------------------------------------------------------------------------------
 1 | [package]
 2 | edition = "2021"
 3 | name = "ngrok-python"
 4 | version = "1.6.0"
 5 | description = "The ngrok Agent SDK for Python"
 6 | 
 7 | [lib]
 8 | name = "ngrok"
 9 | crate-type = ["cdylib"]
10 | 
11 | [dependencies]
12 | async-trait = "0.1.59"
13 | bytes = "1.3.0"
14 | futures = "0.3.26"
15 | lazy_static = "1.4.0"
16 | log = "0.4"
17 | mio = { version = "1.0.3" }
18 | ngrok = { version = "0.17.0", features = ["hyper"] }
19 | once_cell = {version = "1.21"}
20 | pyo3 = { version = "0.22", features = ["abi3", "abi3-py310", "extension-module", "multiple-pymethods", "experimental-async", "gil-refs", "generate-import-lib"]}
21 | pyo3-async-runtimes = { version = "0.22", features = ["attributes", "tokio-runtime"] }
22 | pyo3-log = { version = "0.11" }
23 | parking_lot = "0.12.1"
24 | regex = "1.9.5"
25 | rustls = "0.23.25"
26 | rustls-pemfile = "2.0.0"
27 | tokio = { version = "1.40", features = ["sync"] }
28 | tracing = { version = "0.1.37", features = ["log", "log-always"] }
29 | url = "2.4.0"
30 | aws-lc-sys = { version = "=0.28.0", features = ["bindgen"] }
31 | aws-lc-rs = "=1.13.0"
32 | 
33 | [build-dependencies]
34 | prost-build = "0.13.5"
35 | pyo3-build-config = "0.24"
36 | 
37 | [profile.release]
38 | lto = true
39 | 
40 | [package.metadata.cargo-udeps.ignore]
41 | normal = ["mio"]
42 | 


--------------------------------------------------------------------------------
/doc_source/conf.py:
--------------------------------------------------------------------------------
 1 | # Configuration file for the Sphinx documentation builder.
 2 | #
 3 | # For the full list of built-in configuration values, see the documentation:
 4 | # https://www.sphinx-doc.org/en/master/usage/configuration.html
 5 | 
 6 | import http
 7 | from http.server import HTTPServer
 8 | 
 9 | # -- Project information -----------------------------------------------------
10 | # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
11 | 
12 | project = 'ngrok'
13 | # note the space prefix is required, or sphinx will convert 2023 to 1980
14 | copyright = ' 2023, ngrok'
15 | author = 'ngrok'
16 | 
17 | # -- General configuration ---------------------------------------------------
18 | # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
19 | 
20 | extensions = ['sphinx.ext.autodoc', 'myst_parser']
21 | 
22 | templates_path = ['doc_source']
23 | exclude_patterns = ['Thumbs.db', '.DS_Store']
24 | source_suffix = {
25 |     '.rst': 'restructuredtext',
26 |     '.txt': 'markdown',
27 |     '.md': 'markdown',
28 | }
29 | 
30 | # -- Options for HTML output -------------------------------------------------
31 | # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
32 | 
33 | html_theme = 'furo'
34 | html_static_path = ['_static']
35 | 


--------------------------------------------------------------------------------
/.github/workflows/publish.yml:
--------------------------------------------------------------------------------
 1 | name: Publish All
 2 | on:
 3 |   workflow_dispatch:
 4 | 
 5 | jobs:
 6 |   ci:
 7 |     name: Run CI
 8 |     uses: ./.github/workflows/ci.yml
 9 |     secrets:
10 |       NGROK_AUTHTOKEN: ${{ secrets.NGROK_AUTHTOKEN }}
11 |       MATURIN_PASSWORD: ${{ secrets.MATURIN_PASSWORD }}
12 |     permissions:
13 |       contents: write
14 |     with:
15 |       publish: true
16 |   tag-release:
17 |     name: Tag Release
18 |     needs: ci
19 |     runs-on: ubuntu-latest
20 |     steps:
21 |       - uses: actions/checkout@v4
22 |       - uses: jrobsonchase/direnv-action@v0.7
23 |       - name: Tag Release
24 |         run: |
25 |           version="$(grep '^version =' Cargo.toml | head -n1 | awk -F\" '{print $2}')"
26 |           tag="v${version}"
27 |           git config user.name "GitHub Action"
28 |           git config user.email noreply@ngrok.com
29 |           echo "Version: ${version} tag: $tag"
30 |           echo "Fetching all tags in the repository"
31 |           git fetch --tags
32 |           if git rev-parse "refs/tags/$tag" >/dev/null 2>&1; then
33 |             echo "Tag $tag already exists, skipping tag creation."
34 |           else
35 |             echo "Tag $tag does not exist, pushing tag."
36 |             git tag -a -m "Version ${version}" $tag
37 |             git push --tags
38 |           fi
39 | 


--------------------------------------------------------------------------------
/examples/gpt4all/run.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python
 2 | 
 3 | import argparse
 4 | import logging
 5 | import os
 6 | 
 7 | import gradio as gr
 8 | import ngrok
 9 | from pygpt4all.models.gpt4all import GPT4All
10 | 
11 | logging.basicConfig(level=logging.INFO)
12 | 
13 | default_port = 7860
14 | 
15 | 
16 | def create_ngrok_listener():
17 |     parser = argparse.ArgumentParser()
18 |     parser.add_argument("--host", help="Hostname or IP address", default="localhost")
19 |     parser.add_argument("--port", help="Port number", type=int, default=default_port)
20 | 
21 |     args, _ = parser.parse_known_args()
22 | 
23 |     return ngrok.forward(f"{args.host}:{args.port}", authtoken_from_env=True)
24 | 
25 | 
26 | # setup ngrok
27 | listener = create_ngrok_listener()
28 | 
29 | # Load model path from environment.
30 | if "MODEL_PATH" not in os.environ:
31 |     raise Exception(
32 |         "MODEL_PATH environment variable not found. Please set it to the path of your model."
33 |     )
34 | 
35 | model_path = os.environ["MODEL_PATH"]
36 | model = GPT4All(model_path)
37 | 
38 | 
39 | # Create model function
40 | def gpt4all(prompt):
41 |     resp = [token for token in model.generate(prompt)]
42 |     return "".join(resp).strip()
43 | 
44 | 
45 | # Create a Gradio interface
46 | demo = gr.Interface(fn=gpt4all, inputs="text", outputs="text")
47 | demo.launch()
48 | 


--------------------------------------------------------------------------------
/examples/djangosite/djangosite/ngrok-asgi.py:
--------------------------------------------------------------------------------
 1 | """
 2 | ASGI config for djangosite project.
 3 | 
 4 | It exposes the ASGI callable as a module-level variable named ``application``.
 5 | 
 6 | For more information on this file, see
 7 | https://docs.djangoproject.com/en/4.1/howto/deployment/asgi/
 8 | """
 9 | 
10 | import os
11 | 
12 | from django.core.asgi import get_asgi_application
13 | 
14 | os.environ.setdefault("DJANGO_SETTINGS_MODULE", "djangosite.settings")
15 | 
16 | application = get_asgi_application()
17 | 
18 | """Added by ngrok"""
19 | # This block handles 'make run-django-uvicorn' and 'make run-django-gunicorn' which uses this asgi.py as the entry point.
20 | # Set env variable to protect against the gunicorn autoreloader.
21 | if os.getenv("NGROK_LISTENER_RUNNING") is None:
22 |     os.environ["NGROK_LISTENER_RUNNING"] = "true"
23 |     import asyncio, multiprocessing, ngrok, sys
24 | 
25 |     async def setup():
26 |         listen = "localhost:8000"
27 |         listener = await ngrok.default()
28 |         print(f"Forwarding to {listen} from ingress url: {listener.url()}")
29 |         listener.forward(listen)
30 | 
31 |     try:
32 |         running_loop = asyncio.get_running_loop()
33 |         running_loop.create_task(setup())
34 |     except RuntimeError:
35 |         # no running loop, run on its own
36 |         asyncio.run(setup())
37 | """End added by ngrok"""
38 | 


--------------------------------------------------------------------------------
/pyproject.toml:
--------------------------------------------------------------------------------
 1 | [project]
 2 | name = "ngrok"
 3 | version = "1.6.0"
 4 | readme = "README.md"
 5 | requires-python = ">=3.12"
 6 | # https://pypi.org/classifiers/
 7 | classifiers = ["Development Status :: 5 - Production/Stable",
 8 |   "Intended Audience :: Developers",
 9 |   "License :: OSI Approved :: MIT License",
10 |   "Operating System :: POSIX",
11 |   "Operating System :: Microsoft :: Windows",
12 |   "Operating System :: MacOS :: MacOS X",
13 |   "Topic :: Utilities",
14 |   "Programming Language :: Python",
15 |   "Programming Language :: Python :: 3",
16 |   "Programming Language :: Python :: 3 :: Only",
17 |   "Programming Language :: Python :: 3.12",
18 |   "Programming Language :: Python :: 3.13",
19 |   "Topic :: System :: Networking",
20 |   "Topic :: System :: Networking :: Firewalls"]
21 | keywords = ["ngrok", "python", "pypi", "pyo3", "ingress", "networking"]
22 | license = {text = "MIT OR Apache-2.0"}
23 | 
24 | [project.urls]
25 | homepage = "https://ngrok.com"
26 | # documentation = "readthedocs.org"
27 | repository = "https://github.com/ngrok/ngrok-python"
28 | changelog = "https://github.com/ngrok/ngrok-python/blob/main/CHANGELOG.md"
29 | 
30 | [project.scripts]
31 | ngrok-asgi = "ngrok:__main__.asgi_cli"
32 | 
33 | [build-system]
34 | requires = ["maturin>=1.5,<=1.9.1"]
35 | build-backend = "maturin"
36 | 
37 | [tool.maturin]
38 | python-source = "python"
39 | 


--------------------------------------------------------------------------------
/examples/djangosite/manage.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python
 2 | """Django's command-line utility for administrative tasks."""
 3 | import os
 4 | import sys
 5 | 
 6 | 
 7 | def main():
 8 |     """Added by ngrok"""
 9 |     # This block handles 'make rundjangosite' which uses this manage.py as the entry point.
10 |     # Set env variable to protect against the autoreloader.
11 |     if os.getenv("NGROK_LISTENER_RUNNING") is None:
12 |         os.environ["NGROK_LISTENER_RUNNING"] = "true"
13 |         import asyncio, multiprocessing, ngrok
14 | 
15 |         async def setup():
16 |             listen = sys.argv[2] if len(sys.argv) > 2 else "localhost:8000"
17 |             listener = await ngrok.default()
18 |             print(f"Forwarding to {listen} from ingress url: {listener.url()}")
19 |             listener.forward(listen)
20 | 
21 |         asyncio.run(setup())
22 |     """End added by ngrok"""
23 | 
24 |     """Run administrative tasks."""
25 |     os.environ.setdefault("DJANGO_SETTINGS_MODULE", "djangosite.settings")
26 |     try:
27 |         from django.core.management import execute_from_command_line
28 |     except ImportError as exc:
29 |         raise ImportError(
30 |             "Couldn't import Django. Are you sure it's installed and "
31 |             "available on your PYTHONPATH environment variable? Did you "
32 |             "forget to activate a virtual environment?"
33 |         ) from exc
34 |     execute_from_command_line(sys.argv)
35 | 
36 | 
37 | if __name__ == "__main__":
38 |     main()
39 | 


--------------------------------------------------------------------------------
/src/logging.rs:
--------------------------------------------------------------------------------
 1 | use log::LevelFilter;
 2 | use pyo3::{
 3 |     pyfunction,
 4 |     PyResult,
 5 |     Python,
 6 | };
 7 | use pyo3_log::{
 8 |     Caching,
 9 |     Logger,
10 | };
11 | 
12 | use crate::py_err;
13 | 
14 | /// Set the log level for the bridge to Python logging.
15 | /// The log level defaults to INFO, it can be set to one of ERROR, WARN, INFO, DEBUG, or TRACE.
16 | ///
17 | /// :param level: The logging level to use (ERROR, WARN, INFO, DEBUG, or TRACE).
18 | /// :type level: str
19 | #[pyfunction]
20 | #[pyo3(text_signature = "(level=\"INFO\")")]
21 | pub fn log_level(py: Python, level: Option<String>) -> PyResult<()> {
22 |     let tracing_level = if let Some(level) = level {
23 |         match level.to_uppercase().as_str() {
24 |             "ERROR" => LevelFilter::Error,
25 |             "WARN" => LevelFilter::Warn,
26 |             "INFO" => LevelFilter::Info,
27 |             "DEBUG" => LevelFilter::Debug,
28 |             "TRACE" => LevelFilter::Trace,
29 |             _ => return Err(py_err("Unknown log level: {level:?}")),
30 |         }
31 |     } else {
32 |         LevelFilter::Info
33 |     };
34 | 
35 |     if let Err(err) = Logger::new(py, Caching::LoggersAndLevels)?
36 |         .filter(LevelFilter::Trace)
37 |         .install()
38 |     {
39 |         if !err.to_string().contains("already initialized") {
40 |             return Err(py_err(format!("Failed to subscribe logger, {err}")));
41 |         }
42 |     }
43 |     log::set_max_level(tracing_level);
44 |     Ok(())
45 | }
46 | 


--------------------------------------------------------------------------------
/docs/_static/debug.css:
--------------------------------------------------------------------------------
 1 | /*
 2 |   This CSS file should be overridden by the theme authors. It's
 3 |   meant for debugging and developing the skeleton that this theme provides.
 4 | */
 5 | body {
 6 |   font-family: -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif,
 7 |     "Apple Color Emoji", "Segoe UI Emoji";
 8 |   background: lavender;
 9 | }
10 | .sb-announcement {
11 |   background: rgb(131, 131, 131);
12 | }
13 | .sb-announcement__inner {
14 |   background: black;
15 |   color: white;
16 | }
17 | .sb-header {
18 |   background: lightskyblue;
19 | }
20 | .sb-header__inner {
21 |   background: royalblue;
22 |   color: white;
23 | }
24 | .sb-header-secondary {
25 |   background: lightcyan;
26 | }
27 | .sb-header-secondary__inner {
28 |   background: cornflowerblue;
29 |   color: white;
30 | }
31 | .sb-sidebar-primary {
32 |   background: lightgreen;
33 | }
34 | .sb-main {
35 |   background: blanchedalmond;
36 | }
37 | .sb-main__inner {
38 |   background: antiquewhite;
39 | }
40 | .sb-header-article {
41 |   background: lightsteelblue;
42 | }
43 | .sb-article-container {
44 |   background: snow;
45 | }
46 | .sb-article-main {
47 |   background: white;
48 | }
49 | .sb-footer-article {
50 |   background: lightpink;
51 | }
52 | .sb-sidebar-secondary {
53 |   background: lightgoldenrodyellow;
54 | }
55 | .sb-footer-content {
56 |   background: plum;
57 | }
58 | .sb-footer-content__inner {
59 |   background: palevioletred;
60 | }
61 | .sb-footer {
62 |   background: pink;
63 | }
64 | .sb-footer__inner {
65 |   background: salmon;
66 | }
67 | .sb-article {
68 |   background: white;
69 | }
70 | 


--------------------------------------------------------------------------------
/examples/domain.key:
--------------------------------------------------------------------------------
 1 | -----BEGIN RSA PRIVATE KEY-----
 2 | MIIEpAIBAAKCAQEAqGzHy1lbNqprP2KCfJT0790IRfyqAK9TbKh4kF8aHAKeUU1A
 3 | FR0EaVX4KN/X2jNqBiVjoK6e7bXgBREIMdNmyBOYyG0eQneRYPTCAO767JS5bpqQ
 4 | /X6jf2V5sNzoJsNXuPXJIGg8xE6nl0Glf6W2kfjYKYkzpyLB9MPW65bktcm9v13g
 5 | chJmnZFbIepvdrqkjsT5cupeD9jL0xh6pARJkytgKML5KfhuUaFxCGNNVTaszkKG
 6 | gO1m4vw4lDRRiZyGVyHwI1zku+P2EBMGJp8QCxwat0gBmQrnSSOlwg5Y89J+MJGr
 7 | Px6VJCqgoWr+5CccEXk3CawSoTSxeHDhR2eBEwIDAQABAoIBADKQLc8brWmU8gue
 8 | bGQwZ/RW3DP+rZ71A8ucLE3Tb0g3dQYddf6groFdINpMkUXdp5few7Eqm2Xr8ywy
 9 | N86Vk8a/M2AAelQkB04fTNrw4/4AjEbrOloQGc+WTFlPiJaSkJRjnZUQFiYtIt0j
10 | BSd0PYJHPcYCfbJQmf/8h1pE+7ajNJlvEWrJ8UjDCjUuPPxq1aCOIA48aN8awDaO
11 | 2R0AeSBws6+6UgyBgy2juat0t8PvS+AiLv4rK3RGMD+x96KoPEoVVgOQLr5YTqRP
12 | Q+HYrs5cSXx9Jb2cmuJzvPUJmE3HKhoshWrK7fz5Z8wVAqTGhX6dbuHoqMJnAdla
13 | FFSBEokCgYEA0BAsrDrnSkls1uC54iqzrxPMvITj4UnBR+PK504NrtP2brlcVIDP
14 | e0dTKPTqjIC0vpDIg2fhPPvKkeoyuL6huiUWL/DdYVphUlwTf2Mu6PUm3o4M1MWN
15 | S7q09cqUp4HWCUbzN3MIJ8sOPY17Lq+fxi1Wf4mNh+8IIXcJQ4HgUiUCgYEAzzqx
16 | L7ck6pBUTtpUFYFTCUQDOYdzPE72zOzHK/LpoWJEssQ479srKlmSnRPRZbPZGMGE
17 | EXvhWROonux96rRrZjiBI4B5G4rzeY0Rs24kClEh+7s5Zw4xmfSJu5oSdLqiy+O+
18 | IKMVhOm9qq+8+y9LwKyajwR27srLdHSijJoXNNcCgYEAgtc5EJH2MwwbisFFg8mw
19 | t0+vN3omR91203uXdH/sMN4Qoa6lNmrOj0raK+5gtTyW7SPlRGWGCjCZQctSXEVd
20 | NM7vtfQ1c2w/uWg3xqsbq9nGuLwBq6gT4+SkudDMTM5kR+87Mcp//W4/JUwcg85j
21 | nl+Sfp+Exk/1//14cOByrZUCgYEAjrr7HUVEfPbJysHf1iwL2D7rBa3AdhJhNIYF
22 | LMUTm59Gd+Zk3PeUxIeLTvs+Z5E2/zESWMR9UtASfNugYo6/xlk2wRAU2h6bUeYT
23 | AgXjduOox2yNvehty389emRFP/boeAw1gN8yzCf+BdkjDdLmlx+LGORXUmOFPIG1
24 | D6h2QWMCgYA0WysR3XMcRH/8GDAgNVry5JvKoxlVXTPqVScTjMRj3VAzPYPCV+ql
25 | lNN6yh/TuJwdvNs+uhKd1Wu4cDIb9GqxkBbUTKoKBrVL1YB93IC7QIR5wVjhJF/i
26 | lrFW1ogr3535UzHzyDD1oXvcnWV/JnTdadHf2oA3Em8n2oTQvXQAog==
27 | -----END RSA PRIVATE KEY-----
28 | 


--------------------------------------------------------------------------------
/examples/ngrok-tcp.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python
 2 | 
 3 | import asyncio, logging, ngrok, os, socketserver, threading
 4 | from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 5 | from typing import Union
 6 | from socketserver import TCPServer, UnixStreamServer
 7 | 
 8 | 
 9 | async def create_listener() -> ngrok.Listener:
10 |     # create session
11 |     session: ngrok.Session = (
12 |         await ngrok.SessionBuilder()
13 |         .authtoken_from_env()
14 |         .metadata("Online in One Line")
15 |         .connect()
16 |     )
17 |     # create listener
18 |     return (
19 |         await session.tcp_endpoint()
20 |         # .allow_cidr("0.0.0.0/0")
21 |         # .deny_cidr("10.1.1.1/32")
22 |         # .forwards_to("example python")
23 |         # .proxy_proto("") # One of: "", "1", "2"
24 |         # .remote_addr("<n>.tcp.ngrok.io:<p>")
25 |         .metadata("example listener metadata from python").listen()
26 |     )
27 | 
28 | 
29 | class HelloHandler(BaseHTTPRequestHandler):
30 |     def do_GET(self):
31 |         body = bytes("<html><body>Hello</body></html>", "utf-8")
32 |         self.protocol_version = "HTTP/1.1"
33 |         self.send_response(200)
34 |         self.send_header("Content-type", "text/html")
35 |         self.send_header("Content-Length", len(body))
36 |         self.end_headers()
37 |         self.wfile.write(body)
38 | 
39 | 
40 | httpd: Union[TCPServer, UnixStreamServer] = ThreadingHTTPServer(
41 |     ("localhost", 0), HelloHandler
42 | )
43 | if os.name != "nt":
44 |     # Set up a unix socket wrapper around standard http server
45 |     class UnixSocketHttpServer(UnixStreamServer):
46 |         def get_request(self):
47 |             request, client_address = super(UnixSocketHttpServer, self).get_request()
48 |             return (request, ["local", 0])
49 | 
50 |     httpd = UnixSocketHttpServer((ngrok.pipe_name()), HelloHandler)
51 | 
52 | logging.basicConfig(level=logging.INFO)
53 | listener = asyncio.run(create_listener())
54 | ngrok.listen(httpd, listener)
55 | httpd.serve_forever()
56 | 


--------------------------------------------------------------------------------
/src/tls.rs:
--------------------------------------------------------------------------------
 1 | use bytes::Bytes;
 2 | use pyo3::{
 3 |     pymethods,
 4 |     types::PyByteArray,
 5 |     PyRefMut,
 6 | };
 7 | 
 8 | use crate::listener_builder::TlsListenerBuilder;
 9 | 
10 | #[pymethods]
11 | #[allow(dead_code)]
12 | impl TlsListenerBuilder {
13 |     /// The domain to request for this edge, any valid domain or hostname that you have
14 |     /// previously registered with ngrok. If using a custom domain, this requires
15 |     /// registering in the `ngrok dashboard`_ and setting a DNS CNAME value.
16 |     ///
17 |     /// .. _ngrok dashboard: https://dashboard.ngrok.com/cloud-edge/domains    
18 |     pub fn domain(self_: PyRefMut<Self>, domain: String) -> PyRefMut<Self> {
19 |         self_.set(|b| {
20 |             b.domain(domain);
21 |         });
22 |         self_
23 |     }
24 |     /// Certificates to use for client authentication at the ngrok edge.
25 |     /// See `Mutual TLS`_ in the ngrok docs for additional details.
26 |     ///
27 |     /// .. _Mutual TLS: https://ngrok.com/docs/cloud-edge/modules/mutual-tls/
28 |     pub fn mutual_tlsca<'a>(
29 |         self_: PyRefMut<'a, Self>,
30 |         mutual_tlsca: &PyByteArray,
31 |     ) -> PyRefMut<'a, Self> {
32 |         self_.set(|b| {
33 |             b.mutual_tlsca(Bytes::from(mutual_tlsca.to_vec()));
34 |         });
35 |         self_
36 |     }
37 | 
38 |     /// Enable endpoint pooling for this listener.
39 |     pub fn pooling_enabled(self_: PyRefMut<Self>, endpoint_pooling: bool) -> PyRefMut<Self> {
40 |         self_.set(|b| {
41 |             b.pooling_enabled(endpoint_pooling);
42 |         });
43 |         self_
44 |     }
45 | 
46 |     /// The key to use for TLS termination at the ngrok edge in PEM format.
47 |     /// See `TLS Termination`_ in the ngrok docs for additional details.
48 |     ///
49 |     /// .. _TLS Termination: https://ngrok.com/docs/cloud-edge/modules/tls-termination/
50 |     pub fn termination<'a>(
51 |         self_: PyRefMut<'a, Self>,
52 |         cert_pem: &PyByteArray,
53 |         key_pem: &PyByteArray,
54 |     ) -> PyRefMut<'a, Self> {
55 |         self_.set(|b| {
56 |             b.termination(
57 |                 Bytes::from(cert_pem.to_vec()),
58 |                 Bytes::from(key_pem.to_vec()),
59 |             );
60 |         });
61 |         self_
62 |     }
63 | }
64 | 


--------------------------------------------------------------------------------
/examples/ngrok-tls.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python
 2 | 
 3 | import asyncio, logging, ngrok, os, socketserver, threading
 4 | from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 5 | from typing import Union
 6 | from socketserver import TCPServer, UnixStreamServer
 7 | 
 8 | logging.basicConfig(level=logging.INFO)
 9 | pipe = ngrok.pipe_name()
10 | 
11 | 
12 | async def create_listener() -> ngrok.Listener:
13 |     # create session
14 |     session: ngrok.Session = (
15 |         await ngrok.SessionBuilder()
16 |         .authtoken_from_env()
17 |         # .authtoken("<authtoken>")
18 |         .metadata("Online in One Line")
19 |         .connect()
20 |     )
21 |     # create listener
22 |     return (
23 |         await session.tls_endpoint()
24 |         # .allow_cidr("0.0.0.0/0")
25 |         # .deny_cidr("10.1.1.1/32")
26 |         # .domain("<somedomain>.ngrok.io")
27 |         # .forwards_to("example python")
28 |         # .mutual_tlsca(load_file("ca.crt"))
29 |         # .proxy_proto("") # One of: "", "1", "2"
30 |         .termination(load_file("domain.crt"), load_file("domain.key"))
31 |         .metadata("example listener metadata from python")
32 |         .listen()
33 |     )
34 | 
35 | 
36 | def load_file(name):
37 |     with open("examples/{}".format(name), "r") as crt:
38 |         return bytearray(crt.read().encode())
39 | 
40 | 
41 | class HelloHandler(BaseHTTPRequestHandler):
42 |     def do_GET(self):
43 |         body = bytes("<html><body>Hello</body></html>", "utf-8")
44 |         self.protocol_version = "HTTP/1.1"
45 |         self.send_response(200)
46 |         self.send_header("Content-type", "text/html")
47 |         self.send_header("Content-Length", len(body))
48 |         self.end_headers()
49 |         self.wfile.write(body)
50 | 
51 | 
52 | httpd: Union[TCPServer, UnixStreamServer] = ThreadingHTTPServer(
53 |     ("localhost", 0), HelloHandler
54 | )
55 | if os.name != "nt":
56 |     # Set up a unix socket wrapper around standard http server
57 |     class UnixSocketHttpServer(UnixStreamServer):
58 |         def get_request(self):
59 |             request, client_address = super(UnixSocketHttpServer, self).get_request()
60 |             return (request, ["local", 0])
61 | 
62 |     httpd = UnixSocketHttpServer((ngrok.pipe_name()), HelloHandler)
63 | 
64 | logging.basicConfig(level=logging.INFO)
65 | listener = asyncio.run(create_listener())
66 | ngrok.listen(httpd, listener)
67 | httpd.serve_forever()
68 | 


--------------------------------------------------------------------------------
/examples/ngrok-forward-full.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python
 2 | 
 3 | from http.server import HTTPServer, BaseHTTPRequestHandler
 4 | import logging, ngrok, os
 5 | import asyncio
 6 | 
 7 | 
 8 | class HelloHandler(BaseHTTPRequestHandler):
 9 |     def do_GET(self):
10 |         body = bytes("Hello!", "utf-8")
11 |         self.protocol_version = "HTTP/1.1"
12 |         self.send_response(200)
13 |         self.send_header("Content-Length", len(body))
14 |         self.end_headers()
15 |         self.wfile.write(body)
16 | 
17 | 
18 | def load_file(name):
19 |     with open("examples/{}".format(name), "r") as crt:
20 |         return bytearray(crt.read().encode())
21 | 
22 | 
23 | logging.basicConfig(level=logging.INFO)
24 | server = HTTPServer(("localhost", 8080), HelloHandler)
25 | listener = ngrok.forward(
26 |     # session configuration
27 |     addr="localhost:8080",
28 |     # allow_user_agent="^mozilla.*",
29 |     # authtoken="<authtoken>",
30 |     authtoken_from_env=True,
31 |     session_metadata="Online in One Line",
32 |     # listener configuration
33 |     basic_auth=["ngrok:online1line"],
34 |     circuit_breaker=0.1,
35 |     compression=True,
36 |     # deny_user_agent="^curl.*",
37 |     # domain="<domain>",
38 |     allow_cidr="0.0.0.0/0",
39 |     deny_cidr="10.1.1.1/32",
40 |     metadata="example listener metadata from python",
41 |     # mutual_tls_cas=load_file("ca.crt"),
42 |     # oauth_provider="google",
43 |     # oauth_allow_domains=["<domain>"],
44 |     # oauth_allow_emails=["<email>"],
45 |     # oauth_scopes=["<scope>"],
46 |     # oauth_client_id="<id>",
47 |     # oauth_client_secret="<secret>",
48 |     # oidc_issuer_url="<url>",
49 |     # oidc_client_id="<id>",
50 |     # oidc_client_secret="<secret>",
51 |     # oidc_allow_domains=["<domain>"],
52 |     # oidc_allow_emails=["<email>"],
53 |     # oidc_scopes=["<scope>"],
54 |     proxy_proto="",  # One of: "", "1", "2"
55 |     request_header_remove="X-Req-Nope",
56 |     response_header_remove="X-Res-Nope",
57 |     request_header_add="X-Req-Yup:true",
58 |     response_header_add="X-Res-Yup:true",
59 |     schemes=["HTTPS"],
60 |     # verify_upstream_tls=True,
61 |     # verify_webhook_provider="twilio",
62 |     # verify_webhook_secret="asdf",
63 |     # websocket_tcp_converter=True,
64 |     # traffic_policy='{"on_http_request": [{"actions": [{"type": "custom-response","config": {"status_code": 200, "body": "Hello, World!"}}]}]}',
65 | )
66 | server.serve_forever()
67 | 


--------------------------------------------------------------------------------
/test/test_main.py:
--------------------------------------------------------------------------------
 1 | from ngrok import __main__, ngrok_parser
 2 | import os
 3 | import unittest
 4 | 
 5 | 
 6 | class TestNgrokMain(unittest.IsolatedAsyncioTestCase):
 7 |     def parser_test(self, args_str, pipe_expect, tcp_expect):
 8 |         parser = ngrok_parser.get_parser()
 9 |         args, unknown = parser.parse_known_args(args_str.split())
10 |         self.assertEqual(pipe_expect, __main__.get_pipe_string(args))
11 |         self.assertEqual(tcp_expect, __main__.get_tcp_string(args))
12 | 
13 |     def test_uvicorn(self):
14 |         self.parser_test("uvicorn", None, None)
15 |         self.parser_test("uvicorn --host 0.0.0.0", None, "0.0.0.0:8000")
16 |         self.parser_test("uvicorn --host 127.0.0.1", None, "127.0.0.1:8000")
17 |         self.parser_test("uvicorn --host 192.168.2.1", None, "192.168.2.1:8000")
18 |         self.parser_test("uvicorn --host localhost", None, "localhost:8000")
19 |         self.parser_test("uvicorn --port 1234", None, "localhost:1234")
20 |         self.parser_test("uvicorn --host localhost --port 1234", None, "localhost:1234")
21 |         # ipv6
22 |         self.parser_test("uvicorn --host ::", None, ":::8000")
23 |         self.parser_test("uvicorn --host :: --port 1234", None, ":::1234")
24 |         # pipe
25 |         self.parser_test("uvicorn --uds /uvicorn.sock", "/uvicorn.sock", None)
26 |         self.parser_test("uvicorn --fd 42", None, None)
27 | 
28 |     def test_gunicorn(self):
29 |         self.parser_test("gunicorn", None, None)
30 |         self.parser_test("gunicorn --bind 0.0.0.0", None, "0.0.0.0:8000")
31 |         self.parser_test("gunicorn --bind 127.0.0.1", None, "127.0.0.1:8000")
32 |         self.parser_test("gunicorn --bind 192.168.2.1", None, "192.168.2.1:8000")
33 |         self.parser_test("gunicorn --bind localhost", None, "localhost:8000")
34 |         self.parser_test("gunicorn --bind :1234", None, "localhost:1234")
35 |         self.parser_test("gunicorn --bind localhost:1234", None, "localhost:1234")
36 |         os.environ["PORT"] = "1234"
37 |         self.parser_test("gunicorn --bind localhost", None, "localhost:1234")
38 |         del os.environ["PORT"]
39 |         # ipv6
40 |         self.parser_test("gunicorn --bind [::]", None, "[::]:8000")
41 |         self.parser_test("gunicorn --bind [::]:1234", None, "[::]:1234")
42 |         # pipe
43 |         self.parser_test("gunicorn --bind unix:/uvicorn.sock", "/uvicorn.sock", None)
44 |         self.parser_test("gunicorn --bind fd://42", None, None)
45 | 


--------------------------------------------------------------------------------
/examples/ngrok-labeled.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python
 2 | 
 3 | import asyncio, logging, ngrok, os, socketserver, threading
 4 | from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 5 | from typing import Union
 6 | from socketserver import TCPServer, UnixStreamServer
 7 | 
 8 | 
 9 | async def create_listener() -> ngrok.Listener:
10 |     # create session
11 |     session = (
12 |         await ngrok.SessionBuilder()
13 |         .authtoken_from_env()
14 |         .metadata("Online in One Line")
15 |         .connect()
16 |     )
17 |     # create listener
18 |     return (
19 |         await session.labeled_listener()
20 |         .label("edge", "edghts_<edge_id>")
21 |         .metadata("example listener metadata from python")
22 |         # Set the application protocol to "http1" or "http2"
23 |         # .app_protocol("http2")
24 |         .listen()
25 |     )
26 | 
27 | 
28 | # Example of using the ngrok.forward convenience function for labeled ingress
29 | def create_listener_connect(addr):
30 |     if addr.startswith("/"):
31 |         addr = f"unix:{addr}"
32 |     ngrok.forward(
33 |         addr,
34 |         authtoken_from_env=True,
35 |         labels="edge:edghts_<edge_id>",
36 |         proto="labeled",
37 |         # Set the application protocol to "http1" or "http2"
38 |         # app_protocol="http2",
39 |     )
40 | 
41 | 
42 | class HelloHandler(BaseHTTPRequestHandler):
43 |     def do_GET(self):
44 |         body = bytes("<html><body>Hello</body></html>", "utf-8")
45 |         self.protocol_version = "HTTP/1.1"
46 |         self.send_response(200)
47 |         self.send_header("Content-type", "text/html")
48 |         self.send_header("Content-Length", len(body))
49 |         self.end_headers()
50 |         self.wfile.write(body)
51 | 
52 | 
53 | httpd: Union[TCPServer, UnixStreamServer] = ThreadingHTTPServer(
54 |     ("localhost", 0), HelloHandler
55 | )
56 | if os.name != "nt":
57 |     # Set up a unix socket wrapper around standard http server
58 |     class UnixSocketHttpServer(socketserver.UnixStreamServer):
59 |         def get_request(self):
60 |             request, client_address = super(UnixSocketHttpServer, self).get_request()
61 |             return (request, ["local", 0])
62 | 
63 |     httpd = UnixSocketHttpServer((ngrok.pipe_name()), HelloHandler)
64 | 
65 | logging.basicConfig(level=logging.INFO)
66 | # create_listener_connect(httpd.server_address)
67 | listener = asyncio.run(create_listener())
68 | ngrok.listen(httpd, listener)
69 | httpd.serve_forever()
70 | 


--------------------------------------------------------------------------------
/flake.lock:
--------------------------------------------------------------------------------
  1 | {
  2 |   "nodes": {
  3 |     "fenix-flake": {
  4 |       "inputs": {
  5 |         "nixpkgs": [
  6 |           "nixpkgs"
  7 |         ],
  8 |         "rust-analyzer-src": "rust-analyzer-src"
  9 |       },
 10 |       "locked": {
 11 |         "lastModified": 1721716180,
 12 |         "narHash": "sha256-9s6WJOHUo/ChtV+1Kysf/BA0SIqmfl9SjJtkpiyRUWg=",
 13 |         "owner": "nix-community",
 14 |         "repo": "fenix",
 15 |         "rev": "8df0c074eac46e1f90e9e25c65ddbc2241717bb1",
 16 |         "type": "github"
 17 |       },
 18 |       "original": {
 19 |         "owner": "nix-community",
 20 |         "repo": "fenix",
 21 |         "type": "github"
 22 |       }
 23 |     },
 24 |     "flake-utils": {
 25 |       "inputs": {
 26 |         "systems": "systems"
 27 |       },
 28 |       "locked": {
 29 |         "lastModified": 1710146030,
 30 |         "narHash": "sha256-SZ5L6eA7HJ/nmkzGG7/ISclqe6oZdOZTNoesiInkXPQ=",
 31 |         "owner": "numtide",
 32 |         "repo": "flake-utils",
 33 |         "rev": "b1d9ab70662946ef0850d488da1c9019f3a9752a",
 34 |         "type": "github"
 35 |       },
 36 |       "original": {
 37 |         "owner": "numtide",
 38 |         "repo": "flake-utils",
 39 |         "type": "github"
 40 |       }
 41 |     },
 42 |     "nixpkgs": {
 43 |       "locked": {
 44 |         "lastModified": 1721622093,
 45 |         "narHash": "sha256-iQ+quy3A1EKeFyLyAtjhgSvZHH7r+xybXZkxMhasN4I=",
 46 |         "owner": "nixos",
 47 |         "repo": "nixpkgs",
 48 |         "rev": "453402b94f39f968a7c27df28e060f69e4a50c3b",
 49 |         "type": "github"
 50 |       },
 51 |       "original": {
 52 |         "owner": "nixos",
 53 |         "ref": "nixpkgs-unstable",
 54 |         "repo": "nixpkgs",
 55 |         "type": "github"
 56 |       }
 57 |     },
 58 |     "root": {
 59 |       "inputs": {
 60 |         "fenix-flake": "fenix-flake",
 61 |         "flake-utils": "flake-utils",
 62 |         "nixpkgs": "nixpkgs"
 63 |       }
 64 |     },
 65 |     "rust-analyzer-src": {
 66 |       "flake": false,
 67 |       "locked": {
 68 |         "lastModified": 1721661365,
 69 |         "narHash": "sha256-dHCsQcxaa3luWEXD+ehItZtWU2B10DXb7GWBF1Fy+I4=",
 70 |         "owner": "rust-lang",
 71 |         "repo": "rust-analyzer",
 72 |         "rev": "329adb5ab18bbb6f9f4ff47c6426412fefc50618",
 73 |         "type": "github"
 74 |       },
 75 |       "original": {
 76 |         "owner": "rust-lang",
 77 |         "ref": "nightly",
 78 |         "repo": "rust-analyzer",
 79 |         "type": "github"
 80 |       }
 81 |     },
 82 |     "systems": {
 83 |       "locked": {
 84 |         "lastModified": 1681028828,
 85 |         "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
 86 |         "owner": "nix-systems",
 87 |         "repo": "default",
 88 |         "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
 89 |         "type": "github"
 90 |       },
 91 |       "original": {
 92 |         "owner": "nix-systems",
 93 |         "repo": "default",
 94 |         "type": "github"
 95 |       }
 96 |     }
 97 |   },
 98 |   "root": "root",
 99 |   "version": 7
100 | }
101 | 


--------------------------------------------------------------------------------
/CODE_OF_CONDUCT.md:
--------------------------------------------------------------------------------
 1 | # ngrok Code of Conduct
 2 | 
 3 | ## Our Pledge
 4 | 
 5 | In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
 6 | 
 7 | ## Our Standards
 8 | 
 9 | Examples of behavior that contributes to creating a positive environment include:
10 | 
11 | - Using welcoming and inclusive language
12 | - Being respectful of differing viewpoints and experiences
13 | - Gracefully accepting constructive criticism
14 | - Focusing on what is best for the community
15 | - Showing empathy towards other community members
16 | 
17 | Examples of unacceptable behavior by participants include:
18 | 
19 | - The use of sexualized language or imagery and unwelcome sexual attention or advances
20 | - Trolling, insulting/derogatory comments, and personal or political attacks
21 | - Public or private harassment
22 | - Publishing others' private information, such as a physical or electronic address, without explicit permission
23 | - Other conduct which could reasonably be considered inappropriate in a professional setting
24 | 
25 | ## Our Responsibilities
26 | 
27 | The ngrok documentation team is responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
28 | 
29 | The ngrok documentation team has the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
30 | 
31 | ## Scope
32 | 
33 | This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the ngrok docs project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
34 | 
35 | ## Enforcement
36 | 
37 | Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [support@ngrok.com](mailto:support@ngrok.com). All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
38 | 
39 | Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
40 | 
41 | ## Attribution
42 | 
43 | This Code of Conduct is adapted from the Contributor Covenant, version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
44 | 
45 | For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq
46 | 


--------------------------------------------------------------------------------
/src/lib.rs:
--------------------------------------------------------------------------------
  1 | use ::ngrok::prelude::Error;
  2 | use listener::Listener;
  3 | use listener_builder::{
  4 |     HttpListenerBuilder,
  5 |     LabeledListenerBuilder,
  6 |     TcpListenerBuilder,
  7 |     TlsListenerBuilder,
  8 | };
  9 | use pyo3::{
 10 |     exceptions::PyValueError,
 11 |     pymodule,
 12 |     types::PyModule,
 13 |     wrap_pyfunction,
 14 |     PyErr,
 15 |     PyResult,
 16 |     Python,
 17 | };
 18 | use session::{
 19 |     Session,
 20 |     SessionBuilder,
 21 | };
 22 | use tracing::debug;
 23 | 
 24 | use crate::{
 25 |     connect::{
 26 |         async_connect,
 27 |         async_disconnect,
 28 |         connect as connect_fn,
 29 |         disconnect,
 30 |         forward,
 31 |         kill,
 32 |     },
 33 |     listener::{
 34 |         async_listeners,
 35 |         get_listeners,
 36 |     },
 37 |     logging::log_level,
 38 |     session::set_auth_token,
 39 |     wrapper::{
 40 |         default,
 41 |         fd,
 42 |         getsockname,
 43 |         listen,
 44 |         pipe_name,
 45 |         werkzeug_develop,
 46 |     },
 47 | };
 48 | 
 49 | pub mod connect;
 50 | pub mod http;
 51 | pub mod listener;
 52 | pub mod listener_builder;
 53 | pub mod logging;
 54 | pub mod session;
 55 | pub mod tcp;
 56 | pub mod tls;
 57 | pub mod wrapper;
 58 | 
 59 | // A Python module implemented in Rust. The name of this function must match
 60 | // the `lib.name` setting in the `Cargo.toml`, else Python will not be able to
 61 | // import the module.
 62 | 
 63 | /// The ngrok Agent SDK for Python
 64 | #[pymodule]
 65 | fn ngrok(py: Python<'_>, m: &PyModule) -> PyResult<()> {
 66 |     m.add_function(wrap_pyfunction!(async_connect, m)?)?;
 67 |     m.add_function(wrap_pyfunction!(async_disconnect, m)?)?;
 68 |     m.add_function(wrap_pyfunction!(async_listeners, m)?)?;
 69 |     m.add_function(wrap_pyfunction!(connect_fn, m)?)?;
 70 |     m.add_function(wrap_pyfunction!(default, m)?)?;
 71 |     m.add_function(wrap_pyfunction!(disconnect, m)?)?;
 72 |     m.add_function(wrap_pyfunction!(fd, m)?)?;
 73 |     m.add_function(wrap_pyfunction!(forward, m)?)?;
 74 |     m.add_function(wrap_pyfunction!(getsockname, m)?)?;
 75 |     m.add_function(wrap_pyfunction!(kill, m)?)?;
 76 |     m.add_function(wrap_pyfunction!(listen, m)?)?;
 77 |     m.add_function(wrap_pyfunction!(log_level, m)?)?;
 78 |     m.add_function(wrap_pyfunction!(pipe_name, m)?)?;
 79 |     m.add_function(wrap_pyfunction!(set_auth_token, m)?)?;
 80 |     m.add_function(wrap_pyfunction!(get_listeners, m)?)?;
 81 |     m.add_function(wrap_pyfunction!(werkzeug_develop, m)?)?;
 82 | 
 83 |     m.add_class::<SessionBuilder>()?;
 84 |     m.add_class::<Session>()?;
 85 | 
 86 |     m.add_class::<Listener>()?;
 87 |     m.add_class::<HttpListenerBuilder>()?;
 88 |     m.add_class::<LabeledListenerBuilder>()?;
 89 |     m.add_class::<TcpListenerBuilder>()?;
 90 |     m.add_class::<TlsListenerBuilder>()?;
 91 | 
 92 |     // turn on logging bridge by default, since user won't see unless they activate Python logging
 93 |     if let Err(e) = log_level(py, None) {
 94 |         debug!("Error enabling logging: {e:?}")
 95 |     }
 96 |     Ok(())
 97 | }
 98 | 
 99 | // Shorthand for PyValueError creation
100 | pub(crate) fn py_err(message: impl Into<String>) -> PyErr {
101 |     PyValueError::new_err(message.into())
102 | }
103 | 
104 | // Shorthand for Error creation from NgrokError
105 | pub(crate) fn py_ngrok_err(message: impl Into<String>, err: &impl Error) -> PyErr {
106 |     let py_err = if let Some(error_code) = err.error_code() {
107 |         PyValueError::new_err((message.into(), err.msg(), error_code.to_string()))
108 |     } else {
109 |         PyValueError::new_err((message.into(), err.msg()))
110 |     };
111 |     py_err
112 | }
113 | 


--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
  1 | ## Unreleased
  2 | 
  3 | - Add support for internal endpoints
  4 | 
  5 | ## 1.5.0:
  6 | - Adds `pooling_enabled` to listener builders, allowing the endpoint to pool with other endpoints with the same host/port/binding
  7 | - Adds support for Windows-aarch64
  8 | 
  9 | ## 1.4.0:
 10 | 
 11 | - Rename `policy` to `traffic_policy` in Listener builders and `ngrok.forward`
 12 | - Fix quickstart example in README
 13 | 
 14 | ## 1.3.0:
 15 | 
 16 | - Add `root_cas` to session builder and `ngrok.forward`. Setting this to `host` will use the host's trusted certificates to connect for the ngrok session.
 17 | - Add `session_ca_cert` and `server_addr` to `ngrok.forward`, which correspond to the same functions in the session builder.
 18 | 
 19 | ## 1.2.0:
 20 | 
 21 | - Add `verify_upstream_tls` to listener builders and `ngrok.forward`. Setting this to false will skip verification of the upstream application's TLS certificate.
 22 | 
 23 | ## 1.1.0:
 24 | 
 25 | - Add `app_protocol(string)` to http and labeled listener builders, and `app_protocol: string` as a `ngrok.forward()` argument. Setting this to "http2" will enable HTTP/2 support to the backend application.
 26 | 
 27 | ## 1.0.0
 28 | 
 29 | - Add policy support to Listener builders and `ngrok.forward`
 30 | 
 31 | ## 0.12.1
 32 | 
 33 | - Move to `ngrok.forward` from `ngrok.connect`, keeping an alias
 34 | 
 35 | ## 0.12.0
 36 | 
 37 | - Add `allow_user_agent` and `deny_user_agent` options to HTTP listeners
 38 | - Add `client_id` and `client_secret` options to OAuth
 39 | 
 40 | ## 0.11.0
 41 | 
 42 | - Rename all assets to listener
 43 | - Add links to ngrok documentation
 44 | - Log if an auth token was used for session creation
 45 | 
 46 | ## 0.10.1
 47 | 
 48 | - Fix publishing for aarch64
 49 | 
 50 | ## 0.10.0
 51 | 
 52 | - Add `listen_and_forward` and `listen_and_serve` to listener builders.
 53 | - Update to latest version of underlying rust library, allowing TLS backends.
 54 | - Fix aarch64 build for docker-ubuntu-on-macos and raspberry pi.
 55 | 
 56 | ## 0.9.0
 57 | 
 58 | - Flattened `listener.forward_pipe()` and `listener.forward_tcp()` into `listener.forward()`. Determination will be made based on `addr` input.
 59 | - Added [Mypy](https://mypy.readthedocs.io/en/stable/) static typing information.
 60 | - Added `session.get_listeners()` to get a list of current non-closed listeners for the session.
 61 | - Added `ngrok.set_auth_token(<token>)` to set a default auth token to use for sessions.
 62 | - Added [ngrok error codes](https://ngrok.com/docs/errors/reference/) as 3rd argument to thrown Errors, when available.
 63 | 
 64 | ## 0.8.1:
 65 | 
 66 | - Cleanly return from a listener forward call after a `session.close()`
 67 | 
 68 | ## 0.8.0:
 69 | 
 70 | - Add `Session.client_info()`
 71 | - Rename to `ngrok-python`
 72 | 
 73 | ## 0.7.0:
 74 | 
 75 | - Add `ngrok.disconnect(url)` and `ngrok.kill()` convenience functions.
 76 | - Add examples for [Tornado](https://www.tornadoweb.org), [OpenPlayground](https://github.com/nat/openplayground), [Streamlit](https://streamlit.io/), [GPT4All](https://github.com/nomic-ai/gpt4all).
 77 | - Handle protocols in `addr`, and dots in `connect` option keys, for ease-of-use.
 78 | - [Docs](https://ngrok.github.io/ngrok-python/) improvements
 79 | 
 80 | ## 0.6.0:
 81 | 
 82 | - Add `ngrok.connect(options)` convenience function.
 83 | - Add [Gradio](https://gradio.app/) example.
 84 | - Consolidate multiple listener classes into one.
 85 | 
 86 | ## 0.5.0:
 87 | 
 88 | - Add ngrok-asgi ASGI runner.
 89 | - Migrate `ca_cert` to the upstream call in `ngrok-rust`.
 90 | 
 91 | ## 0.4.0:
 92 | 
 93 | - Django, auto-format, and windows support in examples.
 94 | 
 95 | ## 0.3.0:
 96 | 
 97 | - Add wrapper convenience functions.
 98 | - Add `close`, `ca_cert`, `handle_disconnection`, `handle_heartbeat` to Session.
 99 | 
100 | ## 0.2.3:
101 | 
102 | - Initial public release.
103 | 


--------------------------------------------------------------------------------
/examples/djangosite/djangosite/settings.py:
--------------------------------------------------------------------------------
  1 | """
  2 | Django settings for djangosite project.
  3 | 
  4 | Generated by 'django-admin startproject' using Django 4.1.7.
  5 | 
  6 | For more information on this file, see
  7 | https://docs.djangoproject.com/en/4.1/topics/settings/
  8 | 
  9 | For the full list of settings and their values, see
 10 | https://docs.djangoproject.com/en/4.1/ref/settings/
 11 | """
 12 | 
 13 | from pathlib import Path
 14 | 
 15 | # Build paths inside the project like this: BASE_DIR / 'subdir'.
 16 | BASE_DIR = Path(__file__).resolve().parent.parent
 17 | 
 18 | 
 19 | # Quick-start development settings - unsuitable for production
 20 | # See https://docs.djangoproject.com/en/4.1/howto/deployment/checklist/
 21 | 
 22 | # SECURITY WARNING: keep the secret key used in production secret!
 23 | SECRET_KEY = "django-insecure-4w0)_hr2ji*e(fnzlz8k9y^gxl^u$wr9cf-fu^ly!ewouwx^so"
 24 | 
 25 | # SECURITY WARNING: don't run with debug turned on in production!
 26 | DEBUG = True
 27 | 
 28 | ALLOWED_HOSTS = []
 29 | """Added by ngrok"""
 30 | # Allowing all is less secure, could specify a ngrok static domain if you have one.
 31 | ALLOWED_HOSTS.append("*")
 32 | """End added by ngrok"""
 33 | 
 34 | 
 35 | # Application definition
 36 | 
 37 | INSTALLED_APPS = [
 38 |     "django.contrib.admin",
 39 |     "django.contrib.auth",
 40 |     "django.contrib.contenttypes",
 41 |     "django.contrib.sessions",
 42 |     "django.contrib.messages",
 43 |     "django.contrib.staticfiles",
 44 | ]
 45 | 
 46 | MIDDLEWARE = [
 47 |     "django.middleware.security.SecurityMiddleware",
 48 |     "django.contrib.sessions.middleware.SessionMiddleware",
 49 |     "django.middleware.common.CommonMiddleware",
 50 |     "django.middleware.csrf.CsrfViewMiddleware",
 51 |     "django.contrib.auth.middleware.AuthenticationMiddleware",
 52 |     "django.contrib.messages.middleware.MessageMiddleware",
 53 |     "django.middleware.clickjacking.XFrameOptionsMiddleware",
 54 | ]
 55 | 
 56 | ROOT_URLCONF = "djangosite.urls"
 57 | 
 58 | TEMPLATES = [
 59 |     {
 60 |         "BACKEND": "django.template.backends.django.DjangoTemplates",
 61 |         "DIRS": [],
 62 |         "APP_DIRS": True,
 63 |         "OPTIONS": {
 64 |             "context_processors": [
 65 |                 "django.template.context_processors.debug",
 66 |                 "django.template.context_processors.request",
 67 |                 "django.contrib.auth.context_processors.auth",
 68 |                 "django.contrib.messages.context_processors.messages",
 69 |             ],
 70 |         },
 71 |     },
 72 | ]
 73 | 
 74 | WSGI_APPLICATION = "djangosite.wsgi.application"
 75 | 
 76 | 
 77 | # Database
 78 | # https://docs.djangoproject.com/en/4.1/ref/settings/#databases
 79 | 
 80 | DATABASES = {
 81 |     "default": {
 82 |         "ENGINE": "django.db.backends.sqlite3",
 83 |         "NAME": BASE_DIR / "db.sqlite3",
 84 |     }
 85 | }
 86 | 
 87 | 
 88 | # Password validation
 89 | # https://docs.djangoproject.com/en/4.1/ref/settings/#auth-password-validators
 90 | 
 91 | AUTH_PASSWORD_VALIDATORS = [
 92 |     {
 93 |         "NAME": "django.contrib.auth.password_validation.UserAttributeSimilarityValidator",
 94 |     },
 95 |     {
 96 |         "NAME": "django.contrib.auth.password_validation.MinimumLengthValidator",
 97 |     },
 98 |     {
 99 |         "NAME": "django.contrib.auth.password_validation.CommonPasswordValidator",
100 |     },
101 |     {
102 |         "NAME": "django.contrib.auth.password_validation.NumericPasswordValidator",
103 |     },
104 | ]
105 | 
106 | 
107 | # Internationalization
108 | # https://docs.djangoproject.com/en/4.1/topics/i18n/
109 | 
110 | LANGUAGE_CODE = "en-us"
111 | 
112 | TIME_ZONE = "UTC"
113 | 
114 | USE_I18N = True
115 | 
116 | USE_TZ = True
117 | 
118 | 
119 | # Static files (CSS, JavaScript, Images)
120 | # https://docs.djangoproject.com/en/4.1/howto/static-files/
121 | 
122 | STATIC_URL = "static/"
123 | 
124 | # Default primary key field type
125 | # https://docs.djangoproject.com/en/4.1/ref/settings/#default-auto-field
126 | 
127 | DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"
128 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
  1 | # Created by https://www.toptal.com/developers/gitignore/api/node
  2 | # Edit at https://www.toptal.com/developers/gitignore?templates=node
  3 | 
  4 | ### Node ###
  5 | # Logs
  6 | logs
  7 | *.log
  8 | npm-debug.log*
  9 | yarn-debug.log*
 10 | yarn-error.log*
 11 | lerna-debug.log*
 12 | 
 13 | # Diagnostic reports (https://nodejs.org/api/report.html)
 14 | report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
 15 | 
 16 | # Runtime data
 17 | pids
 18 | *.pid
 19 | *.seed
 20 | *.pid.lock
 21 | 
 22 | # Directory for instrumented libs generated by jscoverage/JSCover
 23 | lib-cov
 24 | 
 25 | # Coverage directory used by tools like istanbul
 26 | coverage
 27 | *.lcov
 28 | 
 29 | # nyc test coverage
 30 | .nyc_output
 31 | 
 32 | # Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
 33 | .grunt
 34 | 
 35 | # Bower dependency directory (https://bower.io/)
 36 | bower_components
 37 | 
 38 | # node-waf configuration
 39 | .lock-wscript
 40 | 
 41 | # Compiled binary addons (https://nodejs.org/api/addons.html)
 42 | build/Release
 43 | 
 44 | # Dependency directories
 45 | node_modules/
 46 | jspm_packages/
 47 | venv/
 48 | 
 49 | # TypeScript v1 declaration files
 50 | typings/
 51 | 
 52 | # TypeScript cache
 53 | *.tsbuildinfo
 54 | 
 55 | # Optional npm cache directory
 56 | .npm
 57 | 
 58 | # Optional eslint cache
 59 | .eslintcache
 60 | 
 61 | # Microbundle cache
 62 | .rpt2_cache/
 63 | .rts2_cache_cjs/
 64 | .rts2_cache_es/
 65 | .rts2_cache_umd/
 66 | 
 67 | # Optional REPL history
 68 | .node_repl_history
 69 | 
 70 | # Output of 'npm pack'
 71 | *.tgz
 72 | 
 73 | # Yarn Integrity file
 74 | .yarn-integrity
 75 | 
 76 | # dotenv environment variables file
 77 | .env
 78 | .env.test
 79 | 
 80 | # parcel-bundler cache (https://parceljs.org/)
 81 | .cache
 82 | 
 83 | # Next.js build output
 84 | .next
 85 | 
 86 | # Nuxt.js build / generate output
 87 | .nuxt
 88 | dist
 89 | 
 90 | # Gatsby files
 91 | .cache/
 92 | # Comment in the public line in if your project uses Gatsby and not Next.js
 93 | # https://nextjs.org/blog/next-9-1#public-directory-support
 94 | # public
 95 | 
 96 | # vuepress build output
 97 | .vuepress/dist
 98 | 
 99 | # Serverless directories
100 | .serverless/
101 | 
102 | # FuseBox cache
103 | .fusebox/
104 | 
105 | # DynamoDB Local files
106 | .dynamodb/
107 | 
108 | # TernJS port file
109 | .tern-port
110 | 
111 | # Stores VSCode versions used for testing VSCode extensions
112 | .vscode-test
113 | 
114 | # End of https://www.toptal.com/developers/gitignore/api/node
115 | 
116 | # Created by https://www.toptal.com/developers/gitignore/api/macos
117 | # Edit at https://www.toptal.com/developers/gitignore?templates=macos
118 | 
119 | ### macOS ###
120 | # General
121 | .DS_Store
122 | .AppleDouble
123 | .LSOverride
124 | 
125 | # Icon must end with two 
126 | Icon
127 | 
128 | 
129 | # Thumbnails
130 | ._*
131 | 
132 | # Files that might appear in the root of a volume
133 | .DocumentRevisions-V100
134 | .fseventsd
135 | .Spotlight-V100
136 | .TemporaryItems
137 | .Trashes
138 | .VolumeIcon.icns
139 | .com.apple.timemachine.donotpresent
140 | 
141 | # Directories potentially created on remote AFP share
142 | .AppleDB
143 | .AppleDesktop
144 | Network Trash Folder
145 | Temporary Items
146 | .apdisk
147 | 
148 | ### macOS Patch ###
149 | # iCloud generated files
150 | *.icloud
151 | 
152 | # End of https://www.toptal.com/developers/gitignore/api/macos
153 | 
154 | # Created by https://www.toptal.com/developers/gitignore/api/windows
155 | # Edit at https://www.toptal.com/developers/gitignore?templates=windows
156 | 
157 | ### Windows ###
158 | # Windows thumbnail cache files
159 | Thumbs.db
160 | Thumbs.db:encryptable
161 | ehthumbs.db
162 | ehthumbs_vista.db
163 | 
164 | # Dump file
165 | *.stackdump
166 | 
167 | # Folder config file
168 | [Dd]esktop.ini
169 | 
170 | # Recycle Bin used on file shares
171 | $RECYCLE.BIN/
172 | 
173 | # Windows Installer files
174 | *.cab
175 | *.msi
176 | *.msix
177 | *.msm
178 | *.msp
179 | 
180 | # Windows shortcuts
181 | *.lnk
182 | 
183 | # End of https://www.toptal.com/developers/gitignore/api/windows
184 | 
185 | #Added by cargo
186 | /target
187 | 
188 | # Miscellaneous
189 | .pnp.*
190 | .yarn/*
191 | !.yarn/patches
192 | !.yarn/plugins
193 | !.yarn/releases
194 | !.yarn/sdks
195 | !.yarn/versions
196 | 
197 | *.node
198 | .direnv
199 | *.swp
200 | __pycache__/
201 | ngrok.abi3.so
202 | .vscode/
203 | 


--------------------------------------------------------------------------------
/examples/ngrok-http-full.py:
--------------------------------------------------------------------------------
  1 | #!/usr/bin/env python
  2 | 
  3 | import asyncio, logging, ngrok, os, socketserver, threading
  4 | from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
  5 | from typing import Union, cast
  6 | from socketserver import TCPServer, UnixStreamServer
  7 | 
  8 | logging.basicConfig(
  9 |     level=logging.INFO,
 10 |     format="%(asctime)-15s %(levelname)s %(name)s %(filename)s:%(lineno)d %(message)s",
 11 | )
 12 | 
 13 | 
 14 | def on_stop():
 15 |     print("stop command")
 16 | 
 17 | 
 18 | def on_restart():
 19 |     print("restart command")
 20 | 
 21 | 
 22 | def on_update(version, permit_major_version):
 23 |     print(
 24 |         f"update command, version: {version}, permit_major_version: {permit_major_version}"
 25 |     )
 26 | 
 27 | 
 28 | def on_heartbeat(latency):
 29 |     print(f"heartbeat, latency: {latency} milliseconds")
 30 | 
 31 | 
 32 | def on_disconnection(addr, error):
 33 |     print(f"connecting, addr: {addr} error: {error}")
 34 | 
 35 | 
 36 | async def create_listener(httpd: Union[TCPServer, UnixStreamServer]) -> None:
 37 |     # create session
 38 |     session: ngrok.Session = (
 39 |         await ngrok.SessionBuilder()
 40 |         .authtoken_from_env()
 41 |         # .authtoken("<authtoken>")
 42 |         .metadata("Online in One Line")
 43 |         .client_info("ngrok-http-full", "1.2.3")
 44 |         .handle_stop_command(on_stop)
 45 |         .handle_restart_command(on_restart)
 46 |         .handle_update_command(on_update)
 47 |         .handle_heartbeat(on_heartbeat)
 48 |         .handle_disconnection(on_disconnection)
 49 |         # .ca_cert(load_file("ca.crt"))
 50 |         # .server_addr("example.com:443")
 51 |         .connect()
 52 |     )
 53 |     # create listener
 54 |     listener: ngrok.Listener = (
 55 |         await session.http_endpoint()
 56 |         # .allow_cidr("0.0.0.0/0")
 57 |         # .allow_user_agent("^mozilla.*")
 58 |         # .app_protocol("http2")
 59 |         # .basic_auth("ngrok", "online1line")
 60 |         # .circuit_breaker(0.5)
 61 |         # .compression()
 62 |         # .deny_cidr("10.1.1.1/32")
 63 |         # .deny_user_agent("^curl.*")
 64 |         # .domain("<somedomain>.ngrok.io")
 65 |         # .mutual_tlsca(load_file("ca.crt"))
 66 |         # .oauth("google", ["<user>@<domain>"], ["<domain>"])
 67 |         # .oauth("google", ["<user>@<domain>"], ["<domain>"], ["<scope>"], "<id>", "<secret>")
 68 |         # .oidc("<url>", "<id>", "<secret>", ["<user>@<domain>"], ["<domain>"], ["<scope>"])
 69 |         # .proxy_proto("") # One of: "", "1", "2"
 70 |         # .remove_request_header("X-Req-Nope")
 71 |         # .remove_response_header("X-Res-Nope")
 72 |         # .request_header("X-Req-Yup", "true")
 73 |         # .response_header("X-Res-Yup", "true")
 74 |         # .scheme("HTTPS")
 75 |         # .verify_upstream_tls(False)
 76 |         # .websocket_tcp_conversion()
 77 |         # .webhook_verification("twilio", "asdf")
 78 |         .metadata("example listener metadata from python").listen()
 79 |     )
 80 |     sock = cast(tuple[str, int], httpd.server_address)
 81 |     if os.name != "nt":
 82 |         listener.forward(cast(str, httpd.server_address))
 83 |     else:
 84 |         listener.forward(f"localhost:{sock[1]}")
 85 | 
 86 | 
 87 | def load_file(name):
 88 |     with open("examples/{}".format(name), "r") as crt:
 89 |         return bytearray(crt.read().encode())
 90 | 
 91 | 
 92 | class HelloHandler(BaseHTTPRequestHandler):
 93 |     def do_GET(self):
 94 |         body = bytes("<html><body>Hello</body></html>", "utf-8")
 95 |         self.protocol_version = "HTTP/1.1"
 96 |         self.send_response(200)
 97 |         self.send_header("Content-type", "text/html")
 98 |         self.send_header("Content-Length", len(body))
 99 |         self.end_headers()
100 |         self.wfile.write(body)
101 | 
102 | 
103 | httpd: Union[TCPServer, UnixStreamServer] = ThreadingHTTPServer(
104 |     ("localhost", 0), HelloHandler
105 | )
106 | if os.name != "nt":
107 |     # Set up a unix socket wrapper around standard http server
108 |     class UnixSocketHttpServer(UnixStreamServer):
109 |         def get_request(self):
110 |             request, client_address = super(UnixSocketHttpServer, self).get_request()
111 |             return (request, ["local", 0])
112 | 
113 |     pipe_name = ngrok.pipe_name()
114 |     httpd = UnixSocketHttpServer((pipe_name), HelloHandler)
115 | 
116 | # To enable more verbose logging:
117 | # logging.getLogger().setLevel(5)
118 | # ngrok.log_level("TRACE")
119 | 
120 | logging.basicConfig(level=logging.INFO)
121 | asyncio.run(create_listener(httpd))
122 | httpd.serve_forever()
123 | 


--------------------------------------------------------------------------------
/flake.nix:
--------------------------------------------------------------------------------
  1 | {
  2 |   description = "ngrok agent library in Rust";
  3 | 
  4 |   inputs = {
  5 |     nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
  6 | 
  7 |     # Note: fenix packages are cached via cachix:
  8 |     #       cachix use nix-community
  9 |     fenix-flake = {
 10 |       url = "github:nix-community/fenix";
 11 |       inputs.nixpkgs.follows = "nixpkgs";
 12 |     };
 13 | 
 14 |     flake-utils = {
 15 |       url = "github:numtide/flake-utils";
 16 |       inputs.nixpkgs.follows = "nixpkgs";
 17 |     };
 18 |   };
 19 | 
 20 |   outputs = { self, nixpkgs, fenix-flake, flake-utils }:
 21 |     flake-utils.lib.eachDefaultSystem (system:
 22 |       let
 23 |         pkgs = import nixpkgs {
 24 |           inherit system;
 25 |           overlays = [
 26 |             fenix-flake.overlays.default
 27 |           ];
 28 |         };
 29 |         toolchain = pkgs.fenix.complete.withComponents [
 30 |           "cargo"
 31 |           "clippy"
 32 |           "rust-src"
 33 |           "rustc"
 34 |           "rustfmt"
 35 |           "rust-analyzer"
 36 |         ];
 37 |         llvm-toolchain = with pkgs; [
 38 |           cmake
 39 | 
 40 |           clang
 41 |           libclang
 42 |           llvm
 43 |         ];
 44 |         python-toolchain = with pkgs; [
 45 |           python3
 46 |           python3Packages.pandas
 47 |           python3Packages.pyarrow
 48 | 
 49 |           python3Packages.python-lsp-server
 50 |         ];
 51 |         fix-n-fmt = pkgs.writeShellScriptBin "fix-n-fmt" ''
 52 |           set -euf -o pipefail
 53 |           ${toolchain}/bin/cargo clippy --fix --allow-staged --allow-dirty --all-targets --all-features
 54 |           ${toolchain}/bin/cargo fmt
 55 |         '';
 56 |         pre-commit = pkgs.writeShellScript "pre-commit" ''
 57 |           cargo clippy --workspace --all-targets --all-features -- -D warnings
 58 |           result=$?
 59 | 
 60 |           if [[ ''${result} -ne 0 ]] ; then
 61 |               cat <<\EOF
 62 |           There are some linting issues, try `fix-n-fmt` to fix.
 63 |           EOF
 64 |               exit 1
 65 |           fi
 66 | 
 67 |           # Use a dedicated sub-target-dir for udeps. For some reason, it fights with clippy over the cache.
 68 |           CARGO_TARGET_DIR=$(git rev-parse --show-toplevel)/target/udeps cargo udeps --workspace --all-targets --all-features
 69 |           result=$?
 70 | 
 71 |           if [[ ''${result} -ne 0 ]] ; then
 72 |               cat <<\EOF
 73 |           There are some unused dependencies.
 74 |           EOF
 75 |               exit 1
 76 |           fi
 77 | 
 78 |           diff=$(cargo fmt -- --check)
 79 |           result=$?
 80 | 
 81 |           if [[ ''${result} -ne 0 ]] ; then
 82 |               cat <<\EOF
 83 |           There are some code style issues, run `fix-n-fmt` first.
 84 |           EOF
 85 |               exit 1
 86 |           fi
 87 | 
 88 |           exit 0
 89 |         '';
 90 |         setup-hooks = pkgs.writeShellScriptBin "setup-hooks" ''
 91 |           repo_root=$(git rev-parse --git-dir)
 92 | 
 93 |           ${toString (map (h: ''
 94 |             ln -sf ${h} ''${repo_root}/hooks/${h.name}
 95 |           '') [
 96 |             pre-commit
 97 |           ])}
 98 |         '';
 99 |         # Make sure that cargo semver-checks uses the stable toolchain rather
100 |         # than the nightly one that we normally develop with.
101 |         semver-checks = with pkgs; symlinkJoin {
102 |           name = "cargo-semver-checks";
103 |           paths = [ cargo-semver-checks ];
104 |           buildInputs = [ makeWrapper ];
105 |           postBuild = ''
106 |             wrapProgram $out/bin/cargo-semver-checks \
107 |               --prefix PATH : ${rustc}/bin \
108 |               --prefix PATH : ${cargo}/bin
109 |           '';
110 |         };
111 |         extract-version = with pkgs; writeShellScriptBin "extract-crate-version" ''
112 |           ${cargo}/bin/cargo metadata --format-version 1 --no-deps | \
113 |             ${jq}/bin/jq -r ".packages[] | select(.name == \"$1\") | .version"
114 |         '';
115 |       in
116 |       {
117 |         devShell = pkgs.mkShell {
118 |           CHALK_OVERFLOW_DEPTH = 3000;
119 |           CHALK_SOLVER_MAX_SIZE = 1500;
120 |           OPENSSL_LIB_DIR = "${pkgs.openssl.out}/lib";
121 |           OPENSSL_INCLUDE_DIR = "${pkgs.openssl.dev}/include";
122 |           RUSTC_WRAPPER="${pkgs.sccache}/bin/sccache";
123 |           LIBCLANG_PATH="${pkgs.llvmPackages.libclang.lib}/lib";
124 |           buildInputs = with pkgs; [
125 |             toolchain
126 |             python-toolchain
127 |             llvm-toolchain
128 |             fix-n-fmt
129 |             setup-hooks
130 |             cargo-udeps
131 |             semver-checks
132 |             extract-version
133 |           ] ++ lib.optionals stdenv.isDarwin [
134 |             # nix darwin stdenv has broken libiconv: https://github.com/NixOS/nixpkgs/issues/158331
135 |             libiconv
136 |             pkgs.darwin.apple_sdk.frameworks.Security
137 |           ];
138 |         };
139 |       });
140 | }
141 | 


--------------------------------------------------------------------------------
/docs/_static/scripts/furo.js:
--------------------------------------------------------------------------------
1 | /*! For license information please see furo.js.LICENSE.txt */
2 | (()=>{var t={212:function(t,e,n){var o,r;r=void 0!==n.g?n.g:"undefined"!=typeof window?window:this,o=function(){return function(t){"use strict";var e={navClass:"active",contentClass:"active",nested:!1,nestedClass:"active",offset:0,reflow:!1,events:!0},n=function(t,e,n){if(n.settings.events){var o=new CustomEvent(t,{bubbles:!0,cancelable:!0,detail:n});e.dispatchEvent(o)}},o=function(t){var e=0;if(t.offsetParent)for(;t;)e+=t.offsetTop,t=t.offsetParent;return e>=0?e:0},r=function(t){t&&t.sort((function(t,e){return o(t.content)<o(e.content)?-1:1}))},c=function(e,n,o){var r=e.getBoundingClientRect(),c=function(t){return"function"==typeof t.offset?parseFloat(t.offset()):parseFloat(t.offset)}(n);return o?parseInt(r.bottom,10)<(t.innerHeight||document.documentElement.clientHeight):parseInt(r.top,10)<=c},s=function(){return Math.ceil(t.innerHeight+t.pageYOffset)>=Math.max(document.body.scrollHeight,document.documentElement.scrollHeight,document.body.offsetHeight,document.documentElement.offsetHeight,document.body.clientHeight,document.documentElement.clientHeight)},l=function(t,e){var n=t[t.length-1];if(function(t,e){return!(!s()||!c(t.content,e,!0))}(n,e))return n;for(var o=t.length-1;o>=0;o--)if(c(t[o].content,e))return t[o]},a=function(t,e){if(e.nested&&t.parentNode){var n=t.parentNode.closest("li");n&&(n.classList.remove(e.nestedClass),a(n,e))}},i=function(t,e){if(t){var o=t.nav.closest("li");o&&(o.classList.remove(e.navClass),t.content.classList.remove(e.contentClass),a(o,e),n("gumshoeDeactivate",o,{link:t.nav,content:t.content,settings:e}))}},u=function(t,e){if(e.nested){var n=t.parentNode.closest("li");n&&(n.classList.add(e.nestedClass),u(n,e))}};return function(o,c){var s,a,d,f,m,v={setup:function(){s=document.querySelectorAll(o),a=[],Array.prototype.forEach.call(s,(function(t){var e=document.getElementById(decodeURIComponent(t.hash.substr(1)));e&&a.push({nav:t,content:e})})),r(a)},detect:function(){var t=l(a,m);t?d&&t.content===d.content||(i(d,m),function(t,e){if(t){var o=t.nav.closest("li");o&&(o.classList.add(e.navClass),t.content.classList.add(e.contentClass),u(o,e),n("gumshoeActivate",o,{link:t.nav,content:t.content,settings:e}))}}(t,m),d=t):d&&(i(d,m),d=null)}},h=function(e){f&&t.cancelAnimationFrame(f),f=t.requestAnimationFrame(v.detect)},g=function(e){f&&t.cancelAnimationFrame(f),f=t.requestAnimationFrame((function(){r(a),v.detect()}))};return v.destroy=function(){d&&i(d,m),t.removeEventListener("scroll",h,!1),m.reflow&&t.removeEventListener("resize",g,!1),a=null,s=null,d=null,f=null,m=null},m=function(){var t={};return Array.prototype.forEach.call(arguments,(function(e){for(var n in e){if(!e.hasOwnProperty(n))return;t[n]=e[n]}})),t}(e,c||{}),v.setup(),v.detect(),t.addEventListener("scroll",h,!1),m.reflow&&t.addEventListener("resize",g,!1),v}}(r)}.apply(e,[]),void 0===o||(t.exports=o)}},e={};function n(o){var r=e[o];if(void 0!==r)return r.exports;var c=e[o]={exports:{}};return t[o].call(c.exports,c,c.exports,n),c.exports}n.n=t=>{var e=t&&t.__esModule?()=>t.default:()=>t;return n.d(e,{a:e}),e},n.d=(t,e)=>{for(var o in e)n.o(e,o)&&!n.o(t,o)&&Object.defineProperty(t,o,{enumerable:!0,get:e[o]})},n.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(t){if("object"==typeof window)return window}}(),n.o=(t,e)=>Object.prototype.hasOwnProperty.call(t,e),(()=>{"use strict";var t=n(212),e=n.n(t),o=null,r=null,c=window.pageYOffset||document.documentElement.scrollTop;function s(){const t=localStorage.getItem("theme")||"auto";var e;"light"!==(e=window.matchMedia("(prefers-color-scheme: dark)").matches?"auto"===t?"light":"light"==t?"dark":"auto":"auto"===t?"dark":"dark"==t?"light":"auto")&&"dark"!==e&&"auto"!==e&&(console.error(`Got invalid theme mode: ${e}. Resetting to auto.`),e="auto"),document.body.dataset.theme=e,localStorage.setItem("theme",e),console.log(`Changed to ${e} mode.`)}function l(){!function(){const t=document.getElementsByClassName("theme-toggle");Array.from(t).forEach((t=>{t.addEventListener("click",s)}))}(),function(){let t=0,e=!1;window.addEventListener("scroll",(function(n){t=window.scrollY,e||(window.requestAnimationFrame((function(){var n;n=t,0==Math.floor(r.getBoundingClientRect().top)?r.classList.add("scrolled"):r.classList.remove("scrolled"),function(t){t<64?document.documentElement.classList.remove("show-back-to-top"):t<c?document.documentElement.classList.add("show-back-to-top"):t>c&&document.documentElement.classList.remove("show-back-to-top"),c=t}(n),function(t){null!==o&&(0==t?o.scrollTo(0,0):Math.ceil(t)>=Math.floor(document.documentElement.scrollHeight-window.innerHeight)?o.scrollTo(0,o.scrollHeight):document.querySelector(".scroll-current"))}(n),e=!1})),e=!0)})),window.scroll()}(),null!==o&&new(e())(".toc-tree a",{reflow:!0,recursive:!0,navClass:"scroll-current",offset:()=>{let t=parseFloat(getComputedStyle(document.documentElement).fontSize);return r.getBoundingClientRect().height+.5*t+1}})}document.addEventListener("DOMContentLoaded",(function(){document.body.parentNode.classList.remove("no-js"),r=document.querySelector("header"),o=document.querySelector(".toc-scroll"),l()}))})()})();
3 | //# sourceMappingURL=furo.js.map


--------------------------------------------------------------------------------
/docs/_static/doctools.js:
--------------------------------------------------------------------------------
  1 | /*
  2 |  * doctools.js
  3 |  * ~~~~~~~~~~~
  4 |  *
  5 |  * Base JavaScript utilities for all Sphinx HTML documentation.
  6 |  *
  7 |  * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
  8 |  * :license: BSD, see LICENSE for details.
  9 |  *
 10 |  */
 11 | "use strict";
 12 | 
 13 | const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([
 14 |   "TEXTAREA",
 15 |   "INPUT",
 16 |   "SELECT",
 17 |   "BUTTON",
 18 | ]);
 19 | 
 20 | const _ready = (callback) => {
 21 |   if (document.readyState !== "loading") {
 22 |     callback();
 23 |   } else {
 24 |     document.addEventListener("DOMContentLoaded", callback);
 25 |   }
 26 | };
 27 | 
 28 | /**
 29 |  * Small JavaScript module for the documentation.
 30 |  */
 31 | const Documentation = {
 32 |   init: () => {
 33 |     Documentation.initDomainIndexTable();
 34 |     Documentation.initOnKeyListeners();
 35 |   },
 36 | 
 37 |   /**
 38 |    * i18n support
 39 |    */
 40 |   TRANSLATIONS: {},
 41 |   PLURAL_EXPR: (n) => (n === 1 ? 0 : 1),
 42 |   LOCALE: "unknown",
 43 | 
 44 |   // gettext and ngettext don't access this so that the functions
 45 |   // can safely bound to a different name (_ = Documentation.gettext)
 46 |   gettext: (string) => {
 47 |     const translated = Documentation.TRANSLATIONS[string];
 48 |     switch (typeof translated) {
 49 |       case "undefined":
 50 |         return string; // no translation
 51 |       case "string":
 52 |         return translated; // translation exists
 53 |       default:
 54 |         return translated[0]; // (singular, plural) translation tuple exists
 55 |     }
 56 |   },
 57 | 
 58 |   ngettext: (singular, plural, n) => {
 59 |     const translated = Documentation.TRANSLATIONS[singular];
 60 |     if (typeof translated !== "undefined")
 61 |       return translated[Documentation.PLURAL_EXPR(n)];
 62 |     return n === 1 ? singular : plural;
 63 |   },
 64 | 
 65 |   addTranslations: (catalog) => {
 66 |     Object.assign(Documentation.TRANSLATIONS, catalog.messages);
 67 |     Documentation.PLURAL_EXPR = new Function(
 68 |       "n",
 69 |       `return (${catalog.plural_expr})`
 70 |     );
 71 |     Documentation.LOCALE = catalog.locale;
 72 |   },
 73 | 
 74 |   /**
 75 |    * helper function to focus on search bar
 76 |    */
 77 |   focusSearchBar: () => {
 78 |     document.querySelectorAll("input[name=q]")[0]?.focus();
 79 |   },
 80 | 
 81 |   /**
 82 |    * Initialise the domain index toggle buttons
 83 |    */
 84 |   initDomainIndexTable: () => {
 85 |     const toggler = (el) => {
 86 |       const idNumber = el.id.substr(7);
 87 |       const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`);
 88 |       if (el.src.substr(-9) === "minus.png") {
 89 |         el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`;
 90 |         toggledRows.forEach((el) => (el.style.display = "none"));
 91 |       } else {
 92 |         el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`;
 93 |         toggledRows.forEach((el) => (el.style.display = ""));
 94 |       }
 95 |     };
 96 | 
 97 |     const togglerElements = document.querySelectorAll("img.toggler");
 98 |     togglerElements.forEach((el) =>
 99 |       el.addEventListener("click", (event) => toggler(event.currentTarget))
100 |     );
101 |     togglerElements.forEach((el) => (el.style.display = ""));
102 |     if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler);
103 |   },
104 | 
105 |   initOnKeyListeners: () => {
106 |     // only install a listener if it is really needed
107 |     if (
108 |       !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS &&
109 |       !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS
110 |     )
111 |       return;
112 | 
113 |     document.addEventListener("keydown", (event) => {
114 |       // bail for input elements
115 |       if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return;
116 |       // bail with special keys
117 |       if (event.altKey || event.ctrlKey || event.metaKey) return;
118 | 
119 |       if (!event.shiftKey) {
120 |         switch (event.key) {
121 |           case "ArrowLeft":
122 |             if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break;
123 | 
124 |             const prevLink = document.querySelector('link[rel="prev"]');
125 |             if (prevLink && prevLink.href) {
126 |               window.location.href = prevLink.href;
127 |               event.preventDefault();
128 |             }
129 |             break;
130 |           case "ArrowRight":
131 |             if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break;
132 | 
133 |             const nextLink = document.querySelector('link[rel="next"]');
134 |             if (nextLink && nextLink.href) {
135 |               window.location.href = nextLink.href;
136 |               event.preventDefault();
137 |             }
138 |             break;
139 |         }
140 |       }
141 | 
142 |       // some keyboard layouts may need Shift to get /
143 |       switch (event.key) {
144 |         case "/":
145 |           if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break;
146 |           Documentation.focusSearchBar();
147 |           event.preventDefault();
148 |       }
149 |     });
150 |   },
151 | };
152 | 
153 | // quick alias for translations
154 | const _ = Documentation.gettext;
155 | 
156 | _ready(Documentation.init);
157 | 


--------------------------------------------------------------------------------
/docs/_static/styles/furo-extensions.css:
--------------------------------------------------------------------------------
1 | #furo-sidebar-ad-placement{padding:var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal)}#furo-sidebar-ad-placement .ethical-sidebar{background:var(--color-background-secondary);border:none;box-shadow:none}#furo-sidebar-ad-placement .ethical-sidebar:hover{background:var(--color-background-hover)}#furo-sidebar-ad-placement .ethical-sidebar a{color:var(--color-foreground-primary)}#furo-sidebar-ad-placement .ethical-callout a{color:var(--color-foreground-secondary)!important}#furo-readthedocs-versions{background:transparent;display:block;position:static;width:100%}#furo-readthedocs-versions .rst-versions{background:#1a1c1e}#furo-readthedocs-versions .rst-current-version{background:var(--color-sidebar-item-background);cursor:unset}#furo-readthedocs-versions .rst-current-version:hover{background:var(--color-sidebar-item-background)}#furo-readthedocs-versions .rst-current-version .fa-book{color:var(--color-foreground-primary)}#furo-readthedocs-versions>.rst-other-versions{padding:0}#furo-readthedocs-versions>.rst-other-versions small{opacity:1}#furo-readthedocs-versions .injected .rst-versions{position:unset}#furo-readthedocs-versions:focus-within,#furo-readthedocs-versions:hover{box-shadow:0 0 0 1px var(--color-sidebar-background-border)}#furo-readthedocs-versions:focus-within .rst-current-version,#furo-readthedocs-versions:hover .rst-current-version{background:#1a1c1e;font-size:inherit;height:auto;line-height:inherit;padding:12px;text-align:right}#furo-readthedocs-versions:focus-within .rst-current-version .fa-book,#furo-readthedocs-versions:hover .rst-current-version .fa-book{color:#fff;float:left}#furo-readthedocs-versions:focus-within .fa-caret-down,#furo-readthedocs-versions:hover .fa-caret-down{display:none}#furo-readthedocs-versions:focus-within .injected,#furo-readthedocs-versions:focus-within .rst-current-version,#furo-readthedocs-versions:focus-within .rst-other-versions,#furo-readthedocs-versions:hover .injected,#furo-readthedocs-versions:hover .rst-current-version,#furo-readthedocs-versions:hover .rst-other-versions{display:block}#furo-readthedocs-versions:focus-within>.rst-current-version,#furo-readthedocs-versions:hover>.rst-current-version{display:none}.highlight:hover button.copybtn{color:var(--color-code-foreground)}.highlight button.copybtn{align-items:center;background-color:var(--color-code-background);border:none;color:var(--color-background-item);cursor:pointer;height:1.25em;opacity:1;right:.5rem;top:.625rem;transition:color .3s,opacity .3s;width:1.25em}.highlight button.copybtn:hover{background-color:var(--color-code-background);color:var(--color-brand-content)}.highlight button.copybtn:after{background-color:transparent;color:var(--color-code-foreground);display:none}.highlight button.copybtn.success{color:#22863a;transition:color 0ms}.highlight button.copybtn.success:after{display:block}.highlight button.copybtn svg{padding:0}body{--sd-color-primary:var(--color-brand-primary);--sd-color-primary-highlight:var(--color-brand-content);--sd-color-primary-text:var(--color-background-primary);--sd-color-shadow:rgba(0,0,0,.05);--sd-color-card-border:var(--color-card-border);--sd-color-card-border-hover:var(--color-brand-content);--sd-color-card-background:var(--color-card-background);--sd-color-card-text:var(--color-foreground-primary);--sd-color-card-header:var(--color-card-marginals-background);--sd-color-card-footer:var(--color-card-marginals-background);--sd-color-tabs-label-active:var(--color-brand-content);--sd-color-tabs-label-hover:var(--color-foreground-muted);--sd-color-tabs-label-inactive:var(--color-foreground-muted);--sd-color-tabs-underline-active:var(--color-brand-content);--sd-color-tabs-underline-hover:var(--color-foreground-border);--sd-color-tabs-underline-inactive:var(--color-background-border);--sd-color-tabs-overline:var(--color-background-border);--sd-color-tabs-underline:var(--color-background-border)}.sd-tab-content{box-shadow:0 -2px var(--sd-color-tabs-overline),0 1px var(--sd-color-tabs-underline)}.sd-card{box-shadow:0 .1rem .25rem var(--sd-color-shadow),0 0 .0625rem rgba(0,0,0,.1)}.sd-shadow-sm{box-shadow:0 .1rem .25rem var(--sd-color-shadow),0 0 .0625rem rgba(0,0,0,.1)!important}.sd-shadow-md{box-shadow:0 .3rem .75rem var(--sd-color-shadow),0 0 .0625rem rgba(0,0,0,.1)!important}.sd-shadow-lg{box-shadow:0 .6rem 1.5rem var(--sd-color-shadow),0 0 .0625rem rgba(0,0,0,.1)!important}.sd-card-hover:hover{transform:none}.sd-cards-carousel{gap:.25rem;padding:.25rem}body{--tabs--label-text:var(--color-foreground-muted);--tabs--label-text--hover:var(--color-foreground-muted);--tabs--label-text--active:var(--color-brand-content);--tabs--label-text--active--hover:var(--color-brand-content);--tabs--label-background:transparent;--tabs--label-background--hover:transparent;--tabs--label-background--active:transparent;--tabs--label-background--active--hover:transparent;--tabs--padding-x:0.25em;--tabs--margin-x:1em;--tabs--border:var(--color-background-border);--tabs--label-border:transparent;--tabs--label-border--hover:var(--color-foreground-muted);--tabs--label-border--active:var(--color-brand-content);--tabs--label-border--active--hover:var(--color-brand-content)}[role=main] .container{max-width:none;padding-left:0;padding-right:0}.shadow.docutils{border:none;box-shadow:0 .2rem .5rem rgba(0,0,0,.05),0 0 .0625rem rgba(0,0,0,.1)!important}.sphinx-bs .card{background-color:var(--color-background-secondary);color:var(--color-foreground)}
2 | /*# sourceMappingURL=furo-extensions.css.map*/


--------------------------------------------------------------------------------
/docs/_static/sphinx_highlight.js:
--------------------------------------------------------------------------------
  1 | /* Highlighting utilities for Sphinx HTML documentation. */
  2 | "use strict";
  3 | 
  4 | const SPHINX_HIGHLIGHT_ENABLED = true
  5 | 
  6 | /**
  7 |  * highlight a given string on a node by wrapping it in
  8 |  * span elements with the given class name.
  9 |  */
 10 | const _highlight = (node, addItems, text, className) => {
 11 |   if (node.nodeType === Node.TEXT_NODE) {
 12 |     const val = node.nodeValue;
 13 |     const parent = node.parentNode;
 14 |     const pos = val.toLowerCase().indexOf(text);
 15 |     if (
 16 |       pos >= 0 &&
 17 |       !parent.classList.contains(className) &&
 18 |       !parent.classList.contains("nohighlight")
 19 |     ) {
 20 |       let span;
 21 | 
 22 |       const closestNode = parent.closest("body, svg, foreignObject");
 23 |       const isInSVG = closestNode && closestNode.matches("svg");
 24 |       if (isInSVG) {
 25 |         span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
 26 |       } else {
 27 |         span = document.createElement("span");
 28 |         span.classList.add(className);
 29 |       }
 30 | 
 31 |       span.appendChild(document.createTextNode(val.substr(pos, text.length)));
 32 |       parent.insertBefore(
 33 |         span,
 34 |         parent.insertBefore(
 35 |           document.createTextNode(val.substr(pos + text.length)),
 36 |           node.nextSibling
 37 |         )
 38 |       );
 39 |       node.nodeValue = val.substr(0, pos);
 40 | 
 41 |       if (isInSVG) {
 42 |         const rect = document.createElementNS(
 43 |           "http://www.w3.org/2000/svg",
 44 |           "rect"
 45 |         );
 46 |         const bbox = parent.getBBox();
 47 |         rect.x.baseVal.value = bbox.x;
 48 |         rect.y.baseVal.value = bbox.y;
 49 |         rect.width.baseVal.value = bbox.width;
 50 |         rect.height.baseVal.value = bbox.height;
 51 |         rect.setAttribute("class", className);
 52 |         addItems.push({ parent: parent, target: rect });
 53 |       }
 54 |     }
 55 |   } else if (node.matches && !node.matches("button, select, textarea")) {
 56 |     node.childNodes.forEach((el) => _highlight(el, addItems, text, className));
 57 |   }
 58 | };
 59 | const _highlightText = (thisNode, text, className) => {
 60 |   let addItems = [];
 61 |   _highlight(thisNode, addItems, text, className);
 62 |   addItems.forEach((obj) =>
 63 |     obj.parent.insertAdjacentElement("beforebegin", obj.target)
 64 |   );
 65 | };
 66 | 
 67 | /**
 68 |  * Small JavaScript module for the documentation.
 69 |  */
 70 | const SphinxHighlight = {
 71 | 
 72 |   /**
 73 |    * highlight the search words provided in localstorage in the text
 74 |    */
 75 |   highlightSearchWords: () => {
 76 |     if (!SPHINX_HIGHLIGHT_ENABLED) return;  // bail if no highlight
 77 | 
 78 |     // get and clear terms from localstorage
 79 |     const url = new URL(window.location);
 80 |     const highlight =
 81 |         localStorage.getItem("sphinx_highlight_terms")
 82 |         || url.searchParams.get("highlight")
 83 |         || "";
 84 |     localStorage.removeItem("sphinx_highlight_terms")
 85 |     url.searchParams.delete("highlight");
 86 |     window.history.replaceState({}, "", url);
 87 | 
 88 |     // get individual terms from highlight string
 89 |     const terms = highlight.toLowerCase().split(/\s+/).filter(x => x);
 90 |     if (terms.length === 0) return; // nothing to do
 91 | 
 92 |     // There should never be more than one element matching "div.body"
 93 |     const divBody = document.querySelectorAll("div.body");
 94 |     const body = divBody.length ? divBody[0] : document.querySelector("body");
 95 |     window.setTimeout(() => {
 96 |       terms.forEach((term) => _highlightText(body, term, "highlighted"));
 97 |     }, 10);
 98 | 
 99 |     const searchBox = document.getElementById("searchbox");
100 |     if (searchBox === null) return;
101 |     searchBox.appendChild(
102 |       document
103 |         .createRange()
104 |         .createContextualFragment(
105 |           '<p class="highlight-link">' +
106 |             '<a href="javascript:SphinxHighlight.hideSearchWords()">' +
107 |             _("Hide Search Matches") +
108 |             "</a></p>"
109 |         )
110 |     );
111 |   },
112 | 
113 |   /**
114 |    * helper function to hide the search marks again
115 |    */
116 |   hideSearchWords: () => {
117 |     document
118 |       .querySelectorAll("#searchbox .highlight-link")
119 |       .forEach((el) => el.remove());
120 |     document
121 |       .querySelectorAll("span.highlighted")
122 |       .forEach((el) => el.classList.remove("highlighted"));
123 |     localStorage.removeItem("sphinx_highlight_terms")
124 |   },
125 | 
126 |   initEscapeListener: () => {
127 |     // only install a listener if it is really needed
128 |     if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return;
129 | 
130 |     document.addEventListener("keydown", (event) => {
131 |       // bail for input elements
132 |       if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return;
133 |       // bail with special keys
134 |       if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return;
135 |       if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) {
136 |         SphinxHighlight.hideSearchWords();
137 |         event.preventDefault();
138 |       }
139 |     });
140 |   },
141 | };
142 | 
143 | _ready(SphinxHighlight.highlightSearchWords);
144 | _ready(SphinxHighlight.initEscapeListener);
145 | 


--------------------------------------------------------------------------------
/.github/workflows/ci.yml:
--------------------------------------------------------------------------------
  1 | name: CI
  2 | env:
  3 |   DEBUG: napi:*
  4 |   APP_NAME: ngrok
  5 |   MACOSX_DEPLOYMENT_TARGET: '10.13'
  6 | on:
  7 |   workflow_call:
  8 |     inputs:
  9 |       publish:
 10 |         required: false
 11 |         default: false
 12 |         type: boolean
 13 |     secrets:
 14 |       NGROK_AUTHTOKEN:
 15 |         required: true
 16 |       MATURIN_PASSWORD:
 17 |         required: true
 18 |   push:
 19 |     inputs:
 20 |       publish:
 21 |         required: false
 22 |         default: false
 23 |         type: boolean
 24 |     branches:
 25 |       - '**'
 26 |     tags-ignore:
 27 |       - '**'
 28 |     paths-ignore:
 29 |       - '**/*.md'
 30 |       - LICENSE
 31 |       - '**/*.gitignore'
 32 |       - .editorconfig
 33 |       - docs/**
 34 | 
 35 | jobs:
 36 |   udeps:
 37 |     name: Udeps
 38 |     runs-on: ubuntu-latest
 39 |     steps:
 40 |       - uses: actions/checkout@v4
 41 |       - uses: jrobsonchase/direnv-action@v0.7
 42 |       - uses: ./.github/workflows/rust-cache
 43 |       - name: Run Udeps
 44 |         run: |
 45 |           cargo udeps --workspace --all-targets --all-features
 46 |   fmt:
 47 |     name: Rustfmt
 48 |     runs-on: ubuntu-latest
 49 |     steps:
 50 |       - uses: actions/checkout@v4
 51 |       - uses: jrobsonchase/direnv-action@v0.7
 52 |       - name: Run Rustfmt
 53 |         run: |
 54 |           cargo fmt --all -- --check
 55 |   clippy:
 56 |     name: Clippy
 57 |     runs-on: ubuntu-latest
 58 |     steps:
 59 |       - uses: actions/checkout@v4
 60 |       - uses: jrobsonchase/direnv-action@v0.7
 61 |       - uses: ./.github/workflows/rust-cache
 62 |       - name: Run Clippy
 63 |         run: |
 64 |           cargo clippy --all-targets --all-features --workspace
 65 |   test:
 66 |     name: Test
 67 |     runs-on: ubuntu-latest
 68 |     steps:
 69 |       - uses: actions/checkout@v4
 70 |       - uses: jrobsonchase/direnv-action@v0.7
 71 |       - uses: ./.github/workflows/rust-cache
 72 |       - name: Run Tests
 73 |         run: |
 74 |           NGROK_AUTHTOKEN=${{ secrets.NGROK_AUTHTOKEN }} make mypy
 75 |           NGROK_AUTHTOKEN=${{ secrets.NGROK_AUTHTOKEN }} make testfast
 76 | 
 77 |   build:
 78 |     needs:
 79 |       - clippy
 80 |       - fmt
 81 |       - test
 82 |       - udeps
 83 |     uses: ./.github/workflows/build.yml
 84 |     secrets: inherit
 85 |     with:
 86 |       publish: ${{ inputs.publish || false }}
 87 |       docker: ${{ matrix.settings.docker }}
 88 |       host: ${{ matrix.settings.host }}
 89 |       setup: ${{ matrix.settings.setup }}
 90 |       target: ${{ matrix.settings.target }}
 91 |     strategy:
 92 |       fail-fast: false
 93 |       matrix:
 94 |         settings:
 95 |           # MACOS
 96 |           - host: macos-latest
 97 |             target: aarch64-apple-darwin
 98 |           - host: macos-latest
 99 |             target: universal2-apple-darwin
100 |           - host: macos-latest
101 |             target: x86_64-apple-darwin
102 | 
103 |           # LINUX
104 |           - host: ubuntu-latest
105 |             target: aarch64-unknown-linux-gnu
106 |             docker: ghcr.io/rust-cross/manylinux2014-cross:aarch64
107 |           - host: ubuntu-24.04-arm
108 |             target: aarch64-unknown-linux-musl
109 |             docker: alpine:3.21
110 |           - host: ubuntu-latest
111 |             target: armv7-unknown-linux-gnueabihf
112 |             docker: ghcr.io/rust-cross/manylinux2014-cross:armv7
113 |           - host: ubuntu-latest
114 |             target: x86_64-unknown-linux-gnu
115 |             docker: ghcr.io/rust-cross/manylinux2014-cross:x86_64
116 |           - host: ubuntu-latest
117 |             target: x86_64-unknown-linux-musl
118 |             docker: alpine:3.21
119 | 
120 |           # WINDOWS
121 |           - host: windows-latest
122 |             target: aarch64-pc-windows-msvc
123 |           - host: windows-latest
124 |             target: i686-pc-windows-msvc
125 |           - host: windows-latest
126 |             target: x86_64-pc-windows-msvc 
127 |   
128 |   build-freebsd:
129 |     runs-on: ubuntu-22.04
130 |     name: Build FreeBSD
131 |     timeout-minutes: 20
132 |     continue-on-error: true
133 |     steps:
134 |       - name: Run lscpu
135 |         run: lscpu
136 |       - uses: actions/checkout@v4
137 |       - name: Build
138 |         id: build
139 |         uses: vmactions/freebsd-vm@v1
140 |         env:
141 |           RUSTUP_HOME: /usr/local/rustup
142 |           CARGO_HOME: /usr/local/cargo
143 |           RUSTUP_IO_THREADS: 1
144 |         with:
145 |           envs: RUSTUP_HOME CARGO_HOME RUSTUP_IO_THREADS
146 |           usesh: true
147 |           mem: 3000
148 |           prepare: |
149 |             pkg install -y -f curl libnghttp2 python3 cmake llvm
150 |             alias curl="curl --retry 5 --retry-all-errors"
151 |             curl https://sh.rustup.rs -sSf --output rustup.sh
152 |             sh rustup.sh -y --profile minimal --default-toolchain beta
153 |             export PATH="/usr/local/cargo/bin:$PATH"
154 |           run: |
155 |             export PATH="/usr/local/cargo/bin:$PATH"
156 |             python3 -m venv .env
157 |             . .env/bin/activate && pip install -r requirements.txt
158 |             echo "~~~~ maturin building"
159 |             . .env/bin/activate && maturin build
160 |             rm -rf .env/ target/debug/ target/release/
161 |       - name: Upload artifact
162 |         uses: actions/upload-artifact@v4
163 |         with:
164 |           name: bindings-freebsd
165 |           path: target/wheels/*.whl
166 |           if-no-files-found: error


--------------------------------------------------------------------------------
/python/ngrok/ngrok_parser.py:
--------------------------------------------------------------------------------
  1 | import argparse
  2 | 
  3 | 
  4 | def get_pass_through_args():
  5 |     return {"host", "port", "uds", "fd", "config", "bind"}
  6 | 
  7 | 
  8 | def get_parser():
  9 |     # argument parsing
 10 |     parser = argparse.ArgumentParser(
 11 |         prog="ngrok-asgi",
 12 |         description="ASGI wrapper for ngrok",
 13 |         epilog="Online in One Line",
 14 |     )
 15 |     parser.add_argument(
 16 |         "command", choices=["gunicorn", "uvicorn"], help="gunicorn or uvicorn"
 17 |     )
 18 |     # ngrok session options
 19 |     parser.add_argument(
 20 |         "--authtoken",
 21 |         help="Ngrok authtoken, otherwise uses NGROK_AUTH_TOKEN environment variable",
 22 |     )
 23 |     parser.add_argument(
 24 |         "--session-metadata",
 25 |         help="Configures the opaque, machine-readable metadata string for this session.",
 26 |     )
 27 | 
 28 |     # ngrok listener options
 29 |     parser.add_argument(
 30 |         "--allow-cidr",
 31 |         action="append",
 32 |         help="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.",
 33 |     )
 34 |     parser.add_argument(
 35 |         "--basic-auth",
 36 |         nargs=2,
 37 |         metavar=("username", "password"),
 38 |         help="Credentials for basic authentication.",
 39 |     )
 40 |     parser.add_argument(
 41 |         "--circuit-breaker",
 42 |         help="Reject requests when 5XX responses exceed this ratio. Disabled when 0.",
 43 |     )
 44 |     parser.add_argument(
 45 |         "--compression",
 46 |         action="store_true",
 47 |         help="Enable gzip compression for HTTP responses.",
 48 |     )
 49 |     parser.add_argument(
 50 |         "--deny-cidr",
 51 |         action="append",
 52 |         help="Restriction placed on the origin of incoming connections to the edge to deny these CIDR ranges. Call multiple times to add additional CIDR ranges.",
 53 |     )
 54 |     parser.add_argument("--domain", help="The domain to request for this edge.")
 55 |     parser.add_argument(
 56 |         "--forwards-to",
 57 |         help="Listener backend metadata. Viewable via the dashboard and API, but has no bearing on listener behavior.",
 58 |     )
 59 |     parser.add_argument(
 60 |         "--metadata", help="Listener-specific opaque metadata. Viewable via the API."
 61 |     )
 62 |     parser.add_argument(
 63 |         "--mutual-tlsca",
 64 |         help="Filename of certificates to use for client authentication at the ngrok edge.",
 65 |     )
 66 |     parser.add_argument("--oauth-provider", help="OAuth provider configuration.")
 67 |     parser.add_argument(
 68 |         "--oidc",
 69 |         nargs=3,
 70 |         metavar=("issuer-url", "client-id", "client-secret"),
 71 |         help="OIDC configuration.",
 72 |     )
 73 |     parser.add_argument(
 74 |         "--allow-emails", action="append", help="OAuth/OIDC configuration."
 75 |     )
 76 |     parser.add_argument(
 77 |         "--allow-domains", action="append", help="OAuth/OIDC configuration."
 78 |     )
 79 |     parser.add_argument("--scopes", action="append", help="OAuth/OIDC configuration.")
 80 |     parser.add_argument(
 81 |         "--proxy-proto",
 82 |         choices=["", "1", "2"],
 83 |         help="The version of PROXY protocol to use with this listener “1”, “2”, or “” if not using.",
 84 |     )
 85 |     parser.add_argument(
 86 |         "--remove-request-header",
 87 |         action="append",
 88 |         help="Removes a header from requests to this edge. Call multiple times to add additional values.",
 89 |     )
 90 |     parser.add_argument(
 91 |         "--remove-response-header",
 92 |         action="append",
 93 |         help="Removes a header from responses from this edge Call multiple times to add additional values..",
 94 |     )
 95 |     parser.add_argument(
 96 |         "--request-header",
 97 |         action="append",
 98 |         nargs=2,
 99 |         metavar=("header", "value"),
100 |         help="Adds a header to all requests to this edge. Call multiple times to add additional values.",
101 |     )
102 |     parser.add_argument(
103 |         "--response-header",
104 |         action="append",
105 |         nargs=2,
106 |         metavar=("header", "value"),
107 |         help="Adds a header to all responses coming from this edge. Call multiple times to add additional values.",
108 |     )
109 |     parser.add_argument(
110 |         "--scheme",
111 |         choices=["HTTPS", "HTTP"],
112 |         help="The scheme that this edge should use. Defaults to HTTPS.",
113 |     )
114 |     parser.add_argument(
115 |         "--webhook-verification",
116 |         nargs=2,
117 |         metavar=("provider", "secret"),
118 |         help="WebhookVerification configuration.",
119 |     )
120 |     parser.add_argument(
121 |         "--websocket-tcp-conversion",
122 |         action="store_true",
123 |         help="Convert incoming websocket connections to TCP-like streams.",
124 |     )
125 |     # uvicorn options
126 |     parser.add_argument("--host", help="Hostname or IP address")
127 |     parser.add_argument("--port", help="Port number", type=int)
128 |     parser.add_argument("--uds", help="Unix domain socket")
129 |     parser.add_argument("--fd", help="File descriptor")
130 |     # gunicorn options
131 |     parser.add_argument("--config", "-c", help="Config file not supported")
132 |     parser.add_argument(
133 |         "--bind",
134 |         "-b",
135 |         help="Specify a server socket to bind. Server sockets can be any of $(HOST), $(HOST):$(PORT), "
136 |         + "fd://$(FD), or unix:$(PATH). An IP is a valid $(HOST).",
137 |     )
138 |     return parser
139 | 


--------------------------------------------------------------------------------
/Makefile:
--------------------------------------------------------------------------------
  1 | # system python interpreter. used only to create virtual environment
  2 | PY = python3
  3 | VENV = venv
  4 | BIN=$(VENV)/bin
  5 | SHELL=/bin/bash
  6 | 
  7 | # make it work on windows too
  8 | ifeq ($(OS), Windows_NT)
  9 | 	BIN=$(VENV)/Scripts
 10 | 	PY=python
 11 | endif
 12 | 
 13 | all: venv run
 14 | 
 15 | venv:
 16 | 	: # Create venv if it doesn't exist
 17 | 	test -d $(VENV) || ($(PY) -m venv $(VENV) && $(BIN)/pip install -r requirements.txt)
 18 | 
 19 | install: venv
 20 | 	. $(BIN)/activate && pip install -r requirements.txt
 21 | 
 22 | examples-install: venv
 23 | 	. $(BIN)/activate && pip install -r examples/requirements.txt --quiet
 24 | 
 25 | develop: venv
 26 | 	. $(BIN)/activate && maturin develop
 27 | 
 28 | build: venv
 29 | 	. $(BIN)/activate && maturin build
 30 | 
 31 | run: develop
 32 | 	. $(BIN)/activate && ./examples/ngrok-http-minimal.py
 33 | 
 34 | run-aio: develop examples-install
 35 | 	. $(BIN)/activate && python ./examples/aiohttp-ngrok.py
 36 | 
 37 | run-http2: develop examples-install
 38 | 	. $(BIN)/activate && python ./examples/hypercorn-http2-ngrok.py
 39 | 
 40 | run-forward-full: develop
 41 | 	. $(BIN)/activate && python ./examples/ngrok-forward-full.py
 42 | 
 43 | run-forward-minimal: develop
 44 | 	. $(BIN)/activate && python ./examples/ngrok-forward-minimal.py
 45 | 
 46 | run-django: develop examples-install
 47 | 	. $(BIN)/activate && python ./examples/django-single-file.py
 48 | 
 49 | # Run django using the manage.py which is auto-generated by "django-admin startproject"
 50 | # The manage.py file has the ngrok listener setup code.
 51 | run-djangosite: develop examples-install
 52 | 	. $(BIN)/activate && python ./examples/djangosite/manage.py runserver localhost:1234
 53 | 
 54 | # Run django ASGI via uvicorn. The ngrok-asgi.py file has the ngrok listener setup code.
 55 | run-django-uvicorn: develop examples-install
 56 | 	. $(BIN)/activate && pushd ./examples/djangosite && python -m uvicorn djangosite.ngrok-asgi:application
 57 | 
 58 | # Run django ASGI via gunicorn. The ngrok-asgi.py file has the ngrok listener setup code.
 59 | run-django-gunicorn: develop examples-install
 60 | 	. $(BIN)/activate && pushd ./examples/djangosite && python -m gunicorn djangosite.ngrok-asgi:application -k uvicorn.workers.UvicornWorker
 61 | 
 62 | # Run ngrok ASGI via uvicorn. The python/ngrok/__main__.py file has the ngrok listener setup code.
 63 | run-ngrok-uvicorn: develop examples-install
 64 | 	. $(BIN)/activate && pushd ./examples/djangosite && python -m ngrok uvicorn djangosite.asgi:application $(args)
 65 | 
 66 | # Run ngrok ASGI via gunicorn. The python/ngrok/__main__.py file has the ngrok listener setup code.
 67 | run-ngrok-gunicorn: develop examples-install
 68 | 	. $(BIN)/activate && pushd ./examples/djangosite && python -m ngrok gunicorn djangosite.asgi:application -k uvicorn.workers.UvicornWorker $(args)
 69 | 
 70 | # Run ngrok-asgi script via uvicorn. The python/ngrok/__main__.py file has the ngrok listener setup code.
 71 | run-ngrok-asgi: develop examples-install
 72 | 	. $(BIN)/activate && pushd ./examples/djangosite && ngrok-asgi uvicorn djangosite.asgi:application $(args)
 73 | 
 74 | run-flask: develop examples-install
 75 | 	. $(BIN)/activate && python ./examples/flask-ngrok.py
 76 | 
 77 | run-gradio: develop
 78 | 	. $(BIN)/activate && pip install -r examples/gradio/requirements.txt
 79 | 	. $(BIN)/activate && gradio ./examples/gradio/gradio-ngrok.py
 80 | 
 81 | run-gradio-asgi: develop
 82 | 	. $(BIN)/activate && pip install -r examples/gradio/requirements.txt
 83 | 	. $(BIN)/activate && ngrok-asgi uvicorn examples.gradio.gradio-asgi:demo.app --port 7860 --reload
 84 | 
 85 | run-tornado: develop examples-install
 86 | 	. $(BIN)/activate && python ./examples/tornado-ngrok.py
 87 | 
 88 | run-streamlit: develop examples-install
 89 | 	. $(BIN)/activate && pushd ./examples/streamlit && python streamlit-ngrok.py
 90 | 
 91 | run-full: develop
 92 | 	. $(BIN)/activate && ./examples/ngrok-http-full.py
 93 | 
 94 | run-labeled: develop
 95 | 	. $(BIN)/activate && ./examples/ngrok-labeled.py
 96 | 
 97 | run-openplayground: develop
 98 | 	. $(BIN)/activate && pip install -r examples/openplayground/requirements.txt
 99 | 	. $(BIN)/activate && python examples/openplayground/run.py
100 | 
101 | run-gpt4all: develop
102 | 	. $(BIN)/activate && pip install -r examples/gpt4all/requirements.txt --quiet
103 | 	. $(BIN)/activate && python examples/gpt4all/run.py
104 | 
105 | run-tcp: develop
106 | 	. $(BIN)/activate && ./examples/ngrok-tcp.py
107 | 
108 | run-tls: develop
109 | 	. $(BIN)/activate && ./examples/ngrok-tls.py
110 | 
111 | run-uvicorn: develop examples-install
112 | 	. $(BIN)/activate && python ./examples/uvicorn-ngrok.py
113 | 
114 | mypy: develop
115 | 	. $(BIN)/activate && mypy ./examples/ngrok-forward-minimal.py
116 | 	. $(BIN)/activate && mypy ./examples/ngrok-forward-full.py
117 | 	. $(BIN)/activate && mypy ./examples/ngrok-http-minimal.py
118 | 	. $(BIN)/activate && mypy ./examples/ngrok-http-full.py
119 | 	. $(BIN)/activate && mypy ./examples/ngrok-labeled.py
120 | 	. $(BIN)/activate && mypy ./examples/ngrok-tcp.py
121 | 	. $(BIN)/activate && mypy ./examples/ngrok-tls.py
122 | 
123 | # e.g.: make test='-k TestNgrok.test_gzip_listener' test
124 | test: develop
125 | 	. $(BIN)/activate && python -m unittest discover test $(test)
126 | 
127 | # testfast is called by github workflow in ci.yml
128 | testfast: develop
129 | 	. $(BIN)/activate && py.test -n 4 ./test/test*.py
130 | 
131 | testpublish:
132 | 	. $(BIN)/activate && maturin publish --repository testpypi
133 | 
134 | docs: clean develop black docsfast
135 | 
136 | docsfast : develop
137 | 	. $(BIN)/activate && sphinx-build -a -E -b html doc_source/ docs/
138 | 
139 | black: develop
140 | 	. $(BIN)/activate && black examples/ test/ python/
141 | 
142 | clean:
143 | 	rm -rf $(VENV) target/
144 | 


--------------------------------------------------------------------------------
/docs/_static/language_data.js:
--------------------------------------------------------------------------------
  1 | /*
  2 |  * language_data.js
  3 |  * ~~~~~~~~~~~~~~~~
  4 |  *
  5 |  * This script contains the language-specific data used by searchtools.js,
  6 |  * namely the list of stopwords, stemmer, scorer and splitter.
  7 |  *
  8 |  * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
  9 |  * :license: BSD, see LICENSE for details.
 10 |  *
 11 |  */
 12 | 
 13 | var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"];
 14 | 
 15 | 
 16 | /* Non-minified version is copied as a separate JS file, is available */
 17 | 
 18 | /**
 19 |  * Porter Stemmer
 20 |  */
 21 | var Stemmer = function() {
 22 | 
 23 |   var step2list = {
 24 |     ational: 'ate',
 25 |     tional: 'tion',
 26 |     enci: 'ence',
 27 |     anci: 'ance',
 28 |     izer: 'ize',
 29 |     bli: 'ble',
 30 |     alli: 'al',
 31 |     entli: 'ent',
 32 |     eli: 'e',
 33 |     ousli: 'ous',
 34 |     ization: 'ize',
 35 |     ation: 'ate',
 36 |     ator: 'ate',
 37 |     alism: 'al',
 38 |     iveness: 'ive',
 39 |     fulness: 'ful',
 40 |     ousness: 'ous',
 41 |     aliti: 'al',
 42 |     iviti: 'ive',
 43 |     biliti: 'ble',
 44 |     logi: 'log'
 45 |   };
 46 | 
 47 |   var step3list = {
 48 |     icate: 'ic',
 49 |     ative: '',
 50 |     alize: 'al',
 51 |     iciti: 'ic',
 52 |     ical: 'ic',
 53 |     ful: '',
 54 |     ness: ''
 55 |   };
 56 | 
 57 |   var c = "[^aeiou]";          // consonant
 58 |   var v = "[aeiouy]";          // vowel
 59 |   var C = c + "[^aeiouy]*";    // consonant sequence
 60 |   var V = v + "[aeiou]*";      // vowel sequence
 61 | 
 62 |   var mgr0 = "^(" + C + ")?" + V + C;                      // [C]VC... is m>0
 63 |   var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$";    // [C]VC[V] is m=1
 64 |   var mgr1 = "^(" + C + ")?" + V + C + V + C;              // [C]VCVC... is m>1
 65 |   var s_v   = "^(" + C + ")?" + v;                         // vowel in stem
 66 | 
 67 |   this.stemWord = function (w) {
 68 |     var stem;
 69 |     var suffix;
 70 |     var firstch;
 71 |     var origword = w;
 72 | 
 73 |     if (w.length < 3)
 74 |       return w;
 75 | 
 76 |     var re;
 77 |     var re2;
 78 |     var re3;
 79 |     var re4;
 80 | 
 81 |     firstch = w.substr(0,1);
 82 |     if (firstch == "y")
 83 |       w = firstch.toUpperCase() + w.substr(1);
 84 | 
 85 |     // Step 1a
 86 |     re = /^(.+?)(ss|i)es$/;
 87 |     re2 = /^(.+?)([^s])s$/;
 88 | 
 89 |     if (re.test(w))
 90 |       w = w.replace(re,"$1$2");
 91 |     else if (re2.test(w))
 92 |       w = w.replace(re2,"$1$2");
 93 | 
 94 |     // Step 1b
 95 |     re = /^(.+?)eed$/;
 96 |     re2 = /^(.+?)(ed|ing)$/;
 97 |     if (re.test(w)) {
 98 |       var fp = re.exec(w);
 99 |       re = new RegExp(mgr0);
100 |       if (re.test(fp[1])) {
101 |         re = /.$/;
102 |         w = w.replace(re,"");
103 |       }
104 |     }
105 |     else if (re2.test(w)) {
106 |       var fp = re2.exec(w);
107 |       stem = fp[1];
108 |       re2 = new RegExp(s_v);
109 |       if (re2.test(stem)) {
110 |         w = stem;
111 |         re2 = /(at|bl|iz)$/;
112 |         re3 = new RegExp("([^aeiouylsz])\\1$");
113 |         re4 = new RegExp("^" + C + v + "[^aeiouwxy]$");
114 |         if (re2.test(w))
115 |           w = w + "e";
116 |         else if (re3.test(w)) {
117 |           re = /.$/;
118 |           w = w.replace(re,"");
119 |         }
120 |         else if (re4.test(w))
121 |           w = w + "e";
122 |       }
123 |     }
124 | 
125 |     // Step 1c
126 |     re = /^(.+?)y$/;
127 |     if (re.test(w)) {
128 |       var fp = re.exec(w);
129 |       stem = fp[1];
130 |       re = new RegExp(s_v);
131 |       if (re.test(stem))
132 |         w = stem + "i";
133 |     }
134 | 
135 |     // Step 2
136 |     re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/;
137 |     if (re.test(w)) {
138 |       var fp = re.exec(w);
139 |       stem = fp[1];
140 |       suffix = fp[2];
141 |       re = new RegExp(mgr0);
142 |       if (re.test(stem))
143 |         w = stem + step2list[suffix];
144 |     }
145 | 
146 |     // Step 3
147 |     re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/;
148 |     if (re.test(w)) {
149 |       var fp = re.exec(w);
150 |       stem = fp[1];
151 |       suffix = fp[2];
152 |       re = new RegExp(mgr0);
153 |       if (re.test(stem))
154 |         w = stem + step3list[suffix];
155 |     }
156 | 
157 |     // Step 4
158 |     re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/;
159 |     re2 = /^(.+?)(s|t)(ion)$/;
160 |     if (re.test(w)) {
161 |       var fp = re.exec(w);
162 |       stem = fp[1];
163 |       re = new RegExp(mgr1);
164 |       if (re.test(stem))
165 |         w = stem;
166 |     }
167 |     else if (re2.test(w)) {
168 |       var fp = re2.exec(w);
169 |       stem = fp[1] + fp[2];
170 |       re2 = new RegExp(mgr1);
171 |       if (re2.test(stem))
172 |         w = stem;
173 |     }
174 | 
175 |     // Step 5
176 |     re = /^(.+?)e$/;
177 |     if (re.test(w)) {
178 |       var fp = re.exec(w);
179 |       stem = fp[1];
180 |       re = new RegExp(mgr1);
181 |       re2 = new RegExp(meq1);
182 |       re3 = new RegExp("^" + C + v + "[^aeiouwxy]$");
183 |       if (re.test(stem) || (re2.test(stem) && !(re3.test(stem))))
184 |         w = stem;
185 |     }
186 |     re = /ll$/;
187 |     re2 = new RegExp(mgr1);
188 |     if (re.test(w) && re2.test(w)) {
189 |       re = /.$/;
190 |       w = w.replace(re,"");
191 |     }
192 | 
193 |     // and turn initial Y back to y
194 |     if (firstch == "y")
195 |       w = firstch.toLowerCase() + w.substr(1);
196 |     return w;
197 |   }
198 | }
199 | 
200 | 


--------------------------------------------------------------------------------
/python/ngrok/__main__.py:
--------------------------------------------------------------------------------
  1 | import asyncio
  2 | import logging
  3 | import ngrok
  4 | from ngrok import ngrok_parser
  5 | import os
  6 | import re
  7 | import shlex
  8 | import sys
  9 | 
 10 | DEFAULT_HOST = "localhost"
 11 | DEFAULT_PORT = "8000"
 12 | 
 13 | 
 14 | def configure_session(args):
 15 |     builder = ngrok.SessionBuilder()
 16 |     if args.authtoken:
 17 |         builder.authtoken(args.authtoken)
 18 |     else:
 19 |         builder.authtoken_from_env()
 20 | 
 21 |     if args.session_metadata:
 22 |         builder.metadata(args.session_metadata)
 23 |     return builder
 24 | 
 25 | 
 26 | def configure_listener(session, args):
 27 |     builder = session.http_endpoint()
 28 |     if args.allow_cidr:
 29 |         for cidr in args.allow_cidr:
 30 |             builder.allow_cidr(cidr)
 31 |     if args.basic_auth:
 32 |         builder.basic_auth(args.basic_auth[0], args.basic_auth[1])
 33 |     if args.circuit_breaker:
 34 |         builder.circuit_breaker(float(args.circuit_breaker))
 35 |     if args.compression:
 36 |         builder.compression()
 37 |     if args.deny_cidr:
 38 |         for cidr in args.deny_cidr:
 39 |             builder.deny_cidr(cidr)
 40 |     if args.domain:
 41 |         builder.domain(args.domain)
 42 |     if args.forwards_to:
 43 |         builder.forwards_to(args.forwards_to)
 44 |     if args.metadata:
 45 |         builder.metadata(args.metadata)
 46 |     if args.mutual_tlsca:
 47 |         with open(args.mutual_tlsca, "r") as crt:
 48 |             builder.mutual_tlsca(bytearray(crt.read().encode()))
 49 |     if args.oauth_provider:
 50 |         builder.oauth(
 51 |             args.oauth_provider, args.allow_emails, args.allow_domains, args.scopes
 52 |         )
 53 |     if args.oidc:
 54 |         builder.oidc(
 55 |             args.oidc[0],
 56 |             args.oidc[1],
 57 |             args.oidc[2],
 58 |             args.allow_emails,
 59 |             args.allow_domains,
 60 |             args.scopes,
 61 |         )
 62 |     if args.proxy_proto:
 63 |         builder.proxy_proto(args.proxy_proto)
 64 |     if args.remove_request_header:
 65 |         for header in args.remove_request_header:
 66 |             builder.remove_request_header(header)
 67 |     if args.remove_response_header:
 68 |         for header in args.remove_response_header:
 69 |             builder.remove_response_header(header)
 70 |     if args.request_header:
 71 |         for header in args.request_header:
 72 |             builder.request_header(header[0], header[1])
 73 |     if args.response_header:
 74 |         for header in args.response_header:
 75 |             builder.response_header(header[0], header[1])
 76 |     if args.scheme:
 77 |         builder.scheme(args.scheme)
 78 |     if args.webhook_verification:
 79 |         builder.webhook_verification(
 80 |             args.webhook_verification[0], args.webhook_verification[1]
 81 |         )
 82 |     if args.websocket_tcp_conversion:
 83 |         builder.websocket_tcp_conversion(args.websocket_tcp_conversion)
 84 |     return builder
 85 | 
 86 | 
 87 | def gunicorn():
 88 |     from gunicorn.app.wsgiapp import run
 89 | 
 90 |     run()
 91 | 
 92 | 
 93 | def uvicorn():
 94 |     import uvicorn
 95 | 
 96 |     uvicorn.main()
 97 | 
 98 | 
 99 | def get_pipe_string(args):
100 |     pipe_string = None
101 |     if args.uds:
102 |         pipe_string = args.uds
103 |     if args.bind and args.bind.startswith("unix:"):
104 |         pipe_string = args.bind[5:]
105 |     return pipe_string
106 | 
107 | 
108 | def fallback_port(args):
109 |     fallback_port = DEFAULT_PORT
110 |     if args.command == "gunicorn" and "PORT" in os.environ:
111 |         fallback_port = os.getenv("PORT")
112 |     return fallback_port
113 | 
114 | 
115 | def get_tcp_string(args):
116 |     tcp_string = None
117 |     if args.host and args.port:
118 |         tcp_string = args.host + ":" + str(args.port)
119 |     elif args.host:
120 |         tcp_string = args.host + ":" + fallback_port(args)
121 |     elif args.port:
122 |         tcp_string = DEFAULT_HOST + ":" + str(args.port)
123 |     elif (
124 |         args.bind
125 |         and not args.bind.startswith("fd://")
126 |         and not args.bind.startswith("unix:")
127 |     ):
128 |         tcp_string = args.bind
129 |         # check if missing host
130 |         if re.search("^:\d+$", tcp_string):
131 |             tcp_string = DEFAULT_HOST + tcp_string
132 |         # check if missing port
133 |         if not re.search(":\d+$", tcp_string):
134 |             tcp_string += ":" + fallback_port(args)
135 |     return tcp_string
136 | 
137 | 
138 | def setup_forwarding(listener, args, tcp_string=None):
139 |     if tcp_string:
140 |         listener.forward(tcp_string)
141 |         return True
142 | 
143 |     # prefer pipe over tcp
144 |     pipe_string = get_pipe_string(args)
145 |     if pipe_string:
146 |         listener.forward(pipe_string)
147 |     else:
148 |         tcp_string = get_tcp_string(args)
149 |         if not tcp_string:
150 |             return False
151 |         listener.forward(tcp_string)
152 | 
153 |     return True
154 | 
155 | 
156 | async def bind(parser, args):
157 |     session = await configure_session(args).connect()
158 |     listener = await configure_listener(session, args).listen()
159 |     listener_success = setup_forwarding(listener, args)
160 | 
161 |     # if we don't have what we need, check gunicorn environment variable
162 |     if (
163 |         not listener_success
164 |         and args.command == "gunicorn"
165 |         and "GUNICORN_CMD_ARGS" in os.environ
166 |     ):
167 |         env_cmd_args = shlex.split(os.getenv("GUNICORN_CMD_ARGS"))
168 |         env_args, unknown = parser.parse_known_args(env_cmd_args)
169 |         listener_success = setup_forwarding(listener, env_args)
170 | 
171 |     # fallback to the default host and port for these runners
172 |     if not listener_success:
173 |         listener_success = setup_forwarding(
174 |             listener, args, tcp_string=f"{DEFAULT_HOST}:{fallback_port(args)}"
175 |         )
176 | 
177 |     # give up
178 |     if not listener_success:
179 |         logging.fatal("No listener created. Exiting.")
180 |         sys.exit(1)
181 | 
182 |     return listener
183 | 
184 | 
185 | def main(args):
186 |     logging.basicConfig(level=logging.INFO)
187 | 
188 |     # argument parsing
189 |     parser = ngrok_parser.get_parser()
190 |     args, unknown = parser.parse_known_args()
191 | 
192 |     # validation
193 |     if args.config:
194 |         logging.fatal("Config file not supported. Exiting.")
195 |         sys.exit(2)
196 |     if args.fd or (args.bind and args.bind.startswith("fd://")):
197 |         logging.fatal("File Descriptor not supported. Exiting.")
198 |         sys.exit(3)
199 | 
200 |     # bind to ngrok
201 |     listener = asyncio.run(bind(parser, args))
202 | 
203 |     # now pretend we don't exist
204 |     pass_args = [args.command]
205 |     # pass through some args
206 |     pass_through_args = ngrok_parser.get_pass_through_args()
207 |     for key, val in vars(args).items():
208 |         if key in pass_through_args and val:
209 |             pass_args.append(f"--{key}")
210 |             pass_args.append(str(val))
211 |     # pass through all unknown args
212 |     sys.argv = pass_args + unknown
213 |     if args.command == "gunicorn":
214 |         gunicorn()
215 |     elif args.command == "uvicorn":
216 |         uvicorn()
217 | 
218 | 
219 | def asgi_cli():
220 |     main(sys.argv)
221 | 
222 | 
223 | if __name__ == "__main__":
224 |     main(sys.argv)
225 | 


--------------------------------------------------------------------------------
/docs/_static/skeleton.css:
--------------------------------------------------------------------------------
  1 | /* Some sane resets. */
  2 | html {
  3 |   height: 100%;
  4 | }
  5 | 
  6 | body {
  7 |   margin: 0;
  8 |   min-height: 100%;
  9 | }
 10 | 
 11 | /* All the flexbox magic! */
 12 | body,
 13 | .sb-announcement,
 14 | .sb-content,
 15 | .sb-main,
 16 | .sb-container,
 17 | .sb-container__inner,
 18 | .sb-article-container,
 19 | .sb-footer-content,
 20 | .sb-header,
 21 | .sb-header-secondary,
 22 | .sb-footer {
 23 |   display: flex;
 24 | }
 25 | 
 26 | /* These order things vertically */
 27 | body,
 28 | .sb-main,
 29 | .sb-article-container {
 30 |   flex-direction: column;
 31 | }
 32 | 
 33 | /* Put elements in the center */
 34 | .sb-header,
 35 | .sb-header-secondary,
 36 | .sb-container,
 37 | .sb-content,
 38 | .sb-footer,
 39 | .sb-footer-content {
 40 |   justify-content: center;
 41 | }
 42 | /* Put elements at the ends */
 43 | .sb-article-container {
 44 |   justify-content: space-between;
 45 | }
 46 | 
 47 | /* These elements grow. */
 48 | .sb-main,
 49 | .sb-content,
 50 | .sb-container,
 51 | article {
 52 |   flex-grow: 1;
 53 | }
 54 | 
 55 | /* Because padding making this wider is not fun */
 56 | article {
 57 |   box-sizing: border-box;
 58 | }
 59 | 
 60 | /* The announcements element should never be wider than the page. */
 61 | .sb-announcement {
 62 |   max-width: 100%;
 63 | }
 64 | 
 65 | .sb-sidebar-primary,
 66 | .sb-sidebar-secondary {
 67 |   flex-shrink: 0;
 68 |   width: 17rem;
 69 | }
 70 | 
 71 | .sb-announcement__inner {
 72 |   justify-content: center;
 73 | 
 74 |   box-sizing: border-box;
 75 |   height: 3rem;
 76 | 
 77 |   overflow-x: auto;
 78 |   white-space: nowrap;
 79 | }
 80 | 
 81 | /* Sidebars, with checkbox-based toggle */
 82 | .sb-sidebar-primary,
 83 | .sb-sidebar-secondary {
 84 |   position: fixed;
 85 |   height: 100%;
 86 |   top: 0;
 87 | }
 88 | 
 89 | .sb-sidebar-primary {
 90 |   left: -17rem;
 91 |   transition: left 250ms ease-in-out;
 92 | }
 93 | .sb-sidebar-secondary {
 94 |   right: -17rem;
 95 |   transition: right 250ms ease-in-out;
 96 | }
 97 | 
 98 | .sb-sidebar-toggle {
 99 |   display: none;
100 | }
101 | .sb-sidebar-overlay {
102 |   position: fixed;
103 |   top: 0;
104 |   width: 0;
105 |   height: 0;
106 | 
107 |   transition: width 0ms ease 250ms, height 0ms ease 250ms, opacity 250ms ease;
108 | 
109 |   opacity: 0;
110 |   background-color: rgba(0, 0, 0, 0.54);
111 | }
112 | 
113 | #sb-sidebar-toggle--primary:checked
114 |   ~ .sb-sidebar-overlay[for="sb-sidebar-toggle--primary"],
115 | #sb-sidebar-toggle--secondary:checked
116 |   ~ .sb-sidebar-overlay[for="sb-sidebar-toggle--secondary"] {
117 |   width: 100%;
118 |   height: 100%;
119 |   opacity: 1;
120 |   transition: width 0ms ease, height 0ms ease, opacity 250ms ease;
121 | }
122 | 
123 | #sb-sidebar-toggle--primary:checked ~ .sb-container .sb-sidebar-primary {
124 |   left: 0;
125 | }
126 | #sb-sidebar-toggle--secondary:checked ~ .sb-container .sb-sidebar-secondary {
127 |   right: 0;
128 | }
129 | 
130 | /* Full-width mode */
131 | .drop-secondary-sidebar-for-full-width-content
132 |   .hide-when-secondary-sidebar-shown {
133 |   display: none !important;
134 | }
135 | .drop-secondary-sidebar-for-full-width-content .sb-sidebar-secondary {
136 |   display: none !important;
137 | }
138 | 
139 | /* Mobile views */
140 | .sb-page-width {
141 |   width: 100%;
142 | }
143 | 
144 | .sb-article-container,
145 | .sb-footer-content__inner,
146 | .drop-secondary-sidebar-for-full-width-content .sb-article,
147 | .drop-secondary-sidebar-for-full-width-content .match-content-width {
148 |   width: 100vw;
149 | }
150 | 
151 | .sb-article,
152 | .match-content-width {
153 |   padding: 0 1rem;
154 |   box-sizing: border-box;
155 | }
156 | 
157 | @media (min-width: 32rem) {
158 |   .sb-article,
159 |   .match-content-width {
160 |     padding: 0 2rem;
161 |   }
162 | }
163 | 
164 | /* Tablet views */
165 | @media (min-width: 42rem) {
166 |   .sb-article-container {
167 |     width: auto;
168 |   }
169 |   .sb-footer-content__inner,
170 |   .drop-secondary-sidebar-for-full-width-content .sb-article,
171 |   .drop-secondary-sidebar-for-full-width-content .match-content-width {
172 |     width: 42rem;
173 |   }
174 |   .sb-article,
175 |   .match-content-width {
176 |     width: 42rem;
177 |   }
178 | }
179 | @media (min-width: 46rem) {
180 |   .sb-footer-content__inner,
181 |   .drop-secondary-sidebar-for-full-width-content .sb-article,
182 |   .drop-secondary-sidebar-for-full-width-content .match-content-width {
183 |     width: 46rem;
184 |   }
185 |   .sb-article,
186 |   .match-content-width {
187 |     width: 46rem;
188 |   }
189 | }
190 | @media (min-width: 50rem) {
191 |   .sb-footer-content__inner,
192 |   .drop-secondary-sidebar-for-full-width-content .sb-article,
193 |   .drop-secondary-sidebar-for-full-width-content .match-content-width {
194 |     width: 50rem;
195 |   }
196 |   .sb-article,
197 |   .match-content-width {
198 |     width: 50rem;
199 |   }
200 | }
201 | 
202 | /* Tablet views */
203 | @media (min-width: 59rem) {
204 |   .sb-sidebar-secondary {
205 |     position: static;
206 |   }
207 |   .hide-when-secondary-sidebar-shown {
208 |     display: none !important;
209 |   }
210 |   .sb-footer-content__inner,
211 |   .drop-secondary-sidebar-for-full-width-content .sb-article,
212 |   .drop-secondary-sidebar-for-full-width-content .match-content-width {
213 |     width: 59rem;
214 |   }
215 |   .sb-article,
216 |   .match-content-width {
217 |     width: 42rem;
218 |   }
219 | }
220 | @media (min-width: 63rem) {
221 |   .sb-footer-content__inner,
222 |   .drop-secondary-sidebar-for-full-width-content .sb-article,
223 |   .drop-secondary-sidebar-for-full-width-content .match-content-width {
224 |     width: 63rem;
225 |   }
226 |   .sb-article,
227 |   .match-content-width {
228 |     width: 46rem;
229 |   }
230 | }
231 | @media (min-width: 67rem) {
232 |   .sb-footer-content__inner,
233 |   .drop-secondary-sidebar-for-full-width-content .sb-article,
234 |   .drop-secondary-sidebar-for-full-width-content .match-content-width {
235 |     width: 67rem;
236 |   }
237 |   .sb-article,
238 |   .match-content-width {
239 |     width: 50rem;
240 |   }
241 | }
242 | 
243 | /* Desktop views */
244 | @media (min-width: 76rem) {
245 |   .sb-sidebar-primary {
246 |     position: static;
247 |   }
248 |   .hide-when-primary-sidebar-shown {
249 |     display: none !important;
250 |   }
251 |   .sb-footer-content__inner,
252 |   .drop-secondary-sidebar-for-full-width-content .sb-article,
253 |   .drop-secondary-sidebar-for-full-width-content .match-content-width {
254 |     width: 59rem;
255 |   }
256 |   .sb-article,
257 |   .match-content-width {
258 |     width: 42rem;
259 |   }
260 | }
261 | 
262 | /* Full desktop views */
263 | @media (min-width: 80rem) {
264 |   .sb-article,
265 |   .match-content-width {
266 |     width: 46rem;
267 |   }
268 |   .sb-footer-content__inner,
269 |   .drop-secondary-sidebar-for-full-width-content .sb-article,
270 |   .drop-secondary-sidebar-for-full-width-content .match-content-width {
271 |     width: 63rem;
272 |   }
273 | }
274 | 
275 | @media (min-width: 84rem) {
276 |   .sb-article,
277 |   .match-content-width {
278 |     width: 50rem;
279 |   }
280 |   .sb-footer-content__inner,
281 |   .drop-secondary-sidebar-for-full-width-content .sb-article,
282 |   .drop-secondary-sidebar-for-full-width-content .match-content-width {
283 |     width: 67rem;
284 |   }
285 | }
286 | 
287 | @media (min-width: 88rem) {
288 |   .sb-footer-content__inner,
289 |   .drop-secondary-sidebar-for-full-width-content .sb-article,
290 |   .drop-secondary-sidebar-for-full-width-content .match-content-width {
291 |     width: 67rem;
292 |   }
293 |   .sb-page-width {
294 |     width: 88rem;
295 |   }
296 | }
297 | 


--------------------------------------------------------------------------------
/docs/_static/styles/furo-extensions.css.map:
--------------------------------------------------------------------------------
1 | {"version":3,"file":"styles/furo-extensions.css","mappings":"AAGA,2BACE,oFACA,4CAKE,6CAHA,YACA,eAEA,CACA,kDACE,yCAEF,8CACE,sCAEJ,8CACE,kDAEJ,2BAGE,uBACA,cAHA,gBACA,UAEA,CAGA,yCACE,mBAEF,gDAEE,gDADA,YACA,CACA,sDACE,gDACF,yDACE,sCAEJ,+CACE,UACA,qDACE,UAGF,mDACE,eAEJ,yEAEE,4DAEA,mHASE,mBAPA,kBAEA,YADA,oBAGA,aADA,gBAIA,CAEA,qIAEE,WADA,UACA,CAEJ,uGACE,aAEF,iUAGE,cAEF,mHACE,aC1EJ,gCACE,mCAEF,0BAKE,mBAUA,8CACA,YAFA,mCAKA,eAZA,cALA,UASA,YADA,YAYA,iCAdA,YAcA,CAEA,gCAEE,8CADA,gCACA,CAEF,gCAGE,6BADA,mCADA,YAEA,CAEF,kCAEE,cADA,oBACA,CACA,wCACE,cAEJ,8BACE,UC5CN,KAEE,6CAA8C,CAC9C,uDAAwD,CACxD,uDAAwD,CAGxD,iCAAsC,CAGtC,+CAAgD,CAChD,uDAAwD,CACxD,uDAAwD,CACxD,oDAAqD,CACrD,6DAA8D,CAC9D,6DAA8D,CAG9D,uDAAwD,CACxD,yDAA0D,CAC1D,4DAA6D,CAC7D,2DAA4D,CAC5D,8DAA+D,CAC/D,iEAAkE,CAClE,uDAAwD,CACxD,wDAAyD,CAG3D,gBACE,qFAGF,SACE,6EAEF,cACE,uFAEF,cACE,uFAEF,cACE,uFAGF,qBACE,eAEF,mBACE,WACA,eChDF,KACE,gDAAiD,CACjD,uDAAwD,CACxD,qDAAsD,CACtD,4DAA6D,CAC7D,oCAAqC,CACrC,2CAA4C,CAC5C,4CAA6C,CAC7C,mDAAoD,CACpD,wBAAyB,CACzB,oBAAqB,CACrB,6CAA8C,CAC9C,gCAAiC,CACjC,yDAA0D,CAC1D,uDAAwD,CACxD,8DAA+D,CCbjE,uBACE,eACA,eACA,gBAGF,iBACE,YACA,+EAGF,iBACE,mDACA","sources":["webpack:///./src/furo/assets/styles/extensions/_readthedocs.sass","webpack:///./src/furo/assets/styles/extensions/_copybutton.sass","webpack:///./src/furo/assets/styles/extensions/_sphinx-design.sass","webpack:///./src/furo/assets/styles/extensions/_sphinx-inline-tabs.sass","webpack:///./src/furo/assets/styles/extensions/_sphinx-panels.sass"],"sourcesContent":["// This file contains the styles used for tweaking how ReadTheDoc's embedded\n// contents would show up inside the theme.\n\n#furo-sidebar-ad-placement\n  padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal)\n  .ethical-sidebar\n    // Remove the border and box-shadow.\n    border: none\n    box-shadow: none\n    // Manage the background colors.\n    background: var(--color-background-secondary)\n    &:hover\n      background: var(--color-background-hover)\n    // Ensure the text is legible.\n    a\n      color: var(--color-foreground-primary)\n\n  .ethical-callout a\n    color: var(--color-foreground-secondary) !important\n\n#furo-readthedocs-versions\n  position: static\n  width: 100%\n  background: transparent\n  display: block\n\n  // Make the background color fit with the theme's aesthetic.\n  .rst-versions\n    background: rgb(26, 28, 30)\n\n  .rst-current-version\n    cursor: unset\n    background: var(--color-sidebar-item-background)\n    &:hover\n      background: var(--color-sidebar-item-background)\n    .fa-book\n      color: var(--color-foreground-primary)\n\n  > .rst-other-versions\n    padding: 0\n    small\n      opacity: 1\n\n  .injected\n    .rst-versions\n      position: unset\n\n  &:hover,\n  &:focus-within\n    box-shadow: 0 0 0 1px var(--color-sidebar-background-border)\n\n    .rst-current-version\n      // Undo the tweaks done in RTD's CSS\n      font-size: inherit\n      line-height: inherit\n      height: auto\n      text-align: right\n      padding: 12px\n\n      // Match the rest of the body\n      background: #1a1c1e\n\n      .fa-book\n        float: left\n        color: white\n\n    .fa-caret-down\n      display: none\n\n    .rst-current-version,\n    .rst-other-versions,\n    .injected\n      display: block\n\n    > .rst-current-version\n      display: none\n",".highlight\n  &:hover button.copybtn\n    color: var(--color-code-foreground)\n\n  button.copybtn\n    // Make it visible\n    opacity: 1\n\n    // Align things correctly\n    align-items: center\n\n    height: 1.25em\n    width: 1.25em\n\n    top: 0.625rem // $code-spacing-vertical\n    right: 0.5rem\n\n    // Make it look better\n    color: var(--color-background-item)\n    background-color: var(--color-code-background)\n    border: none\n\n    // Change to cursor to make it obvious that you can click on it\n    cursor: pointer\n\n    // Transition smoothly, for aesthetics\n    transition: color 300ms, opacity 300ms\n\n    &:hover\n      color: var(--color-brand-content)\n      background-color: var(--color-code-background)\n\n    &::after\n      display: none\n      color: var(--color-code-foreground)\n      background-color: transparent\n\n    &.success\n      transition: color 0ms\n      color: #22863a\n      &::after\n        display: block\n\n    svg\n      padding: 0\n","body\n  // Colors\n  --sd-color-primary: var(--color-brand-primary)\n  --sd-color-primary-highlight: var(--color-brand-content)\n  --sd-color-primary-text: var(--color-background-primary)\n\n  // Shadows\n  --sd-color-shadow: rgba(0, 0, 0, 0.05)\n\n  // Cards\n  --sd-color-card-border: var(--color-card-border)\n  --sd-color-card-border-hover: var(--color-brand-content)\n  --sd-color-card-background: var(--color-card-background)\n  --sd-color-card-text: var(--color-foreground-primary)\n  --sd-color-card-header: var(--color-card-marginals-background)\n  --sd-color-card-footer: var(--color-card-marginals-background)\n\n  // Tabs\n  --sd-color-tabs-label-active: var(--color-brand-content)\n  --sd-color-tabs-label-hover: var(--color-foreground-muted)\n  --sd-color-tabs-label-inactive: var(--color-foreground-muted)\n  --sd-color-tabs-underline-active: var(--color-brand-content)\n  --sd-color-tabs-underline-hover: var(--color-foreground-border)\n  --sd-color-tabs-underline-inactive: var(--color-background-border)\n  --sd-color-tabs-overline: var(--color-background-border)\n  --sd-color-tabs-underline: var(--color-background-border)\n\n// Tabs\n.sd-tab-content\n  box-shadow: 0 -2px var(--sd-color-tabs-overline), 0 1px var(--sd-color-tabs-underline)\n\n// Shadows\n.sd-card  // Have a shadow by default\n  box-shadow: 0 0.1rem 0.25rem var(--sd-color-shadow), 0 0 0.0625rem rgba(0, 0, 0, 0.1)\n\n.sd-shadow-sm\n  box-shadow: 0 0.1rem 0.25rem var(--sd-color-shadow), 0 0 0.0625rem rgba(0, 0, 0, 0.1) !important\n\n.sd-shadow-md\n  box-shadow: 0 0.3rem 0.75rem var(--sd-color-shadow), 0 0 0.0625rem rgba(0, 0, 0, 0.1) !important\n\n.sd-shadow-lg\n  box-shadow: 0 0.6rem 1.5rem var(--sd-color-shadow), 0 0 0.0625rem rgba(0, 0, 0, 0.1) !important\n\n// Cards\n.sd-card-hover:hover  // Don't change scale on hover\n  transform: none\n\n.sd-cards-carousel  // Have a bit of gap in the carousel by default\n  gap: 0.25rem\n  padding: 0.25rem\n","// This file contains styles to tweak sphinx-inline-tabs to work well with Furo.\n\nbody\n  --tabs--label-text: var(--color-foreground-muted)\n  --tabs--label-text--hover: var(--color-foreground-muted)\n  --tabs--label-text--active: var(--color-brand-content)\n  --tabs--label-text--active--hover: var(--color-brand-content)\n  --tabs--label-background: transparent\n  --tabs--label-background--hover: transparent\n  --tabs--label-background--active: transparent\n  --tabs--label-background--active--hover: transparent\n  --tabs--padding-x: 0.25em\n  --tabs--margin-x: 1em\n  --tabs--border: var(--color-background-border)\n  --tabs--label-border: transparent\n  --tabs--label-border--hover: var(--color-foreground-muted)\n  --tabs--label-border--active: var(--color-brand-content)\n  --tabs--label-border--active--hover: var(--color-brand-content)\n","// This file contains styles to tweak sphinx-panels to work well with Furo.\n\n// sphinx-panels includes Bootstrap 4, which uses .container which can conflict\n// with docutils' `.. container::` directive.\n[role=\"main\"] .container\n  max-width: initial\n  padding-left: initial\n  padding-right: initial\n\n// Make the panels look nicer!\n.shadow.docutils\n  border: none\n  box-shadow: 0 0.2rem 0.5rem rgba(0, 0, 0, 0.05), 0 0 0.0625rem rgba(0, 0, 0, 0.1) !important\n\n// Make panel colors respond to dark mode\n.sphinx-bs .card\n  background-color: var(--color-background-secondary)\n  color: var(--color-foreground)\n"],"names":[],"sourceRoot":""}


--------------------------------------------------------------------------------
/python/ngrok/ngrok.pyi:
--------------------------------------------------------------------------------
  1 | from typing import Union, Optional, Any, Awaitable, List, Mapping, Callable
  2 | 
  3 | # See API documentation for full information on the available functions:
  4 | # https://ngrok.github.io/ngrok-python/
  5 | 
  6 | def connect(
  7 |     addr: Union[None, str, int] = None,
  8 |     listener: Optional[Listener] = None,
  9 |     **options: object,
 10 | ) -> Listener: ...
 11 | def default(session: Optional[Session] = None) -> Listener: ...
 12 | def disconnect(url: Optional[str] = None) -> None: ...
 13 | def fd(session: Optional[Session] = None) -> int: ...
 14 | def forward(
 15 |     addr: Union[None, str, int] = None,
 16 |     listener: Optional[Listener] = None,
 17 |     **options: object,
 18 | ) -> Listener: ...
 19 | def getsockname(session: Optional[Session] = None) -> str: ...
 20 | def kill() -> None: ...
 21 | def listen(
 22 |     server: Optional[Any] = None, listener: Optional[Listener] = None
 23 | ) -> Listener: ...
 24 | def log_level(level: str = "INFO") -> None: ...
 25 | def pipe_name() -> str: ...
 26 | def werkzeug_develop(
 27 |     listener: Optional[Listener] = None,
 28 | ) -> Union[Awaitable[Listener], Listener]: ...
 29 | 
 30 | class Listener:
 31 |     def close(self) -> Awaitable[None]: ...
 32 |     def forward(self, addr: str) -> Awaitable[None]: ...
 33 |     def forwards_to(self) -> str: ...
 34 |     def id(self) -> str: ...
 35 |     def labels(self) -> Mapping[str, str]: ...
 36 |     def metadata(self) -> str: ...
 37 |     def proto(self) -> str: ...
 38 |     def url(self) -> str: ...
 39 | 
 40 | class Session:
 41 |     def close(self) -> Awaitable[None]: ...
 42 |     def close_listener(self, id: str) -> Awaitable[None]: ...
 43 |     def get_listeners(self) -> List[Listener]: ...
 44 |     def http_endpoint(self) -> HttpListenerBuilder: ...
 45 |     def labeled_listener(self) -> LabeledListenerBuilder: ...
 46 |     def tcp_endpoint(self) -> TcpListenerBuilder: ...
 47 |     def tls_endpoint(self) -> TlsListenerBuilder: ...
 48 | 
 49 | class SessionBuilder:
 50 |     def authtoken(self, authtoken: str) -> SessionBuilder: ...
 51 |     def authtoken_from_env(self) -> SessionBuilder: ...
 52 |     def ca_cert(self, cert_bytes: bytearray) -> SessionBuilder: ...
 53 |     def client_info(
 54 |         self, client_type: str, version: str, comments: Optional[str] = None
 55 |     ) -> SessionBuilder: ...
 56 |     def connect(self) -> Awaitable[Session]: ...
 57 |     def handle_disconnection(self, handler: Callable[[str, str]]) -> SessionBuilder: ...
 58 |     def handle_heartbeat(self, handler: Callable[[int]]) -> SessionBuilder: ...
 59 |     def handle_restart_command(self, handler: Callable[[]]) -> SessionBuilder: ...
 60 |     def handle_stop_command(self, handler: Callable[[]]) -> SessionBuilder: ...
 61 |     def handle_update_command(
 62 |         self, handler: Callable[[str, str]]
 63 |     ) -> SessionBuilder: ...
 64 |     def heartbeat_interval(self, heartbeat_interval: int) -> SessionBuilder: ...
 65 |     def heartbeat_tolerance(self, heartbeat_tolerance: int) -> SessionBuilder: ...
 66 |     def metadata(self, metadata: str) -> SessionBuilder: ...
 67 |     def root_cas(self, root_cas: str) -> SessionBuilder: ...
 68 |     def server_addr(self, server_addr: str) -> SessionBuilder: ...
 69 | 
 70 | class HttpListenerBuilder:
 71 |     def allow_cidr(self, cidr: str) -> HttpListenerBuilder: ...
 72 |     def allow_user_agent(self, regex: str) -> HttpListenerBuilder: ...
 73 |     def app_protocol(self, app_protocol: str) -> HttpListenerBuilder: ...
 74 |     def basic_auth(self, username: str, password: str) -> HttpListenerBuilder: ...
 75 |     def circuit_breaker(self, circuit_breaker: float) -> HttpListenerBuilder: ...
 76 |     def compression(self) -> HttpListenerBuilder: ...
 77 |     def deny_cidr(self, cidr: str) -> HttpListenerBuilder: ...
 78 |     def deny_user_agent(self, regex: str) -> HttpListenerBuilder: ...
 79 |     def domain(self, domain: str) -> HttpListenerBuilder: ...
 80 |     def forwards_to(self, forwards_to: str) -> HttpListenerBuilder: ...
 81 |     def listen(self) -> Awaitable[Listener]: ...
 82 |     def listen_and_forward(self, url: str) -> Awaitable[Listener]: ...
 83 |     def listen_and_serve(self, server: Any) -> Awaitable[Listener]: ...
 84 |     def metadata(self, metadata: str) -> HttpListenerBuilder: ...
 85 |     def mutual_tlsca(self, mutual_tlsca: bytearray) -> HttpListenerBuilder: ...
 86 |     def oauth(
 87 |         self,
 88 |         provider: str,
 89 |         allow_emails: Optional[list[str]] = None,
 90 |         allow_domains: Optional[list[str]] = None,
 91 |         scopes: Optional[list[str]] = None,
 92 |         client_id: Optional[str] = None,
 93 |         client_secret: Optional[str] = None,
 94 |     ) -> HttpListenerBuilder: ...
 95 |     def oidc(
 96 |         self,
 97 |         issuer_url: str,
 98 |         client_id: str,
 99 |         client_secret: str,
100 |         allow_emails: Optional[list[str]] = None,
101 |         allow_domains: Optional[list[str]] = None,
102 |         scopes: Optional[list[str]] = None,
103 |     ) -> HttpListenerBuilder: ...
104 |     def policy(self, policy: str) -> HttpListenerBuilder: ...
105 |     def pooling_enabled(self, pooling_enabled: bool) -> HttpListenerBuilder: ...
106 |     def proxy_proto(self, proxy_proto: str) -> HttpListenerBuilder: ...
107 |     def remove_request_header(self, name: str) -> HttpListenerBuilder: ...
108 |     def remove_response_header(self, name: str) -> HttpListenerBuilder: ...
109 |     def request_header(self, name: str, value: str) -> HttpListenerBuilder: ...
110 |     def response_header(self, name: str, value: str) -> HttpListenerBuilder: ...
111 |     def scheme(self, scheme: str) -> HttpListenerBuilder: ...
112 |     def traffic_policy(self, policy: str) -> HttpListenerBuilder: ...
113 |     def verify_upstream_tls(self, verify_upstream_tls: bool) -> HttpListenerBuilder: ...
114 |     def webhook_verification(
115 |         self, provider: str, secret: str
116 |     ) -> HttpListenerBuilder: ...
117 |     def websocket_tcp_conversion(self) -> HttpListenerBuilder: ...
118 | 
119 | class LabeledListenerBuilder:
120 |     def app_protocol(self, app_protocol: str) -> LabeledListenerBuilder: ...
121 |     def label(self, label: str, value: str) -> LabeledListenerBuilder: ...
122 |     def listen(self) -> Awaitable[Listener]: ...
123 |     def listen_and_forward(self, url: str) -> Awaitable[Listener]: ...
124 |     def listen_and_serve(self, server: Any) -> Awaitable[Listener]: ...
125 |     def metadata(self, metadata: str) -> LabeledListenerBuilder: ...
126 |     def verify_upstream_tls(
127 |         self, verify_upstream_tls: bool
128 |     ) -> LabeledListenerBuilder: ...
129 | 
130 | class TcpListenerBuilder:
131 |     def allow_cidr(self, cidr: str) -> TcpListenerBuilder: ...
132 |     def deny_cidr(self, cidr: str) -> TcpListenerBuilder: ...
133 |     def forwards_to(self, forwards_to: str) -> TcpListenerBuilder: ...
134 |     def listen(self) -> Awaitable[Listener]: ...
135 |     def listen_and_forward(self, url: str) -> Awaitable[Listener]: ...
136 |     def listen_and_serve(self, server: Any) -> Awaitable[Listener]: ...
137 |     def metadata(self, metadata: str) -> TcpListenerBuilder: ...
138 |     def policy(self, policy: str) -> TcpListenerBuilder: ...
139 |     def pooling_enabled(self, pooling_enabled: bool) -> TcpListenerBuilder: ...
140 |     def proxy_proto(self, proxy_proto: str) -> TcpListenerBuilder: ...
141 |     def remote_addr(self, remote_addr: str) -> TcpListenerBuilder: ...
142 |     def traffic_policy(self, policy: str) -> TcpListenerBuilder: ...
143 |     def verify_upstream_tls(self, verify_upstream_tls: bool) -> TcpListenerBuilder: ...
144 | 
145 | class TlsListenerBuilder:
146 |     def allow_cidr(self, cidr: str) -> TlsListenerBuilder: ...
147 |     def deny_cidr(self, cidr: str) -> TlsListenerBuilder: ...
148 |     def domain(self, domain: str) -> TlsListenerBuilder: ...
149 |     def forwards_to(self, forwards_to: str) -> TlsListenerBuilder: ...
150 |     def listen(self) -> Awaitable[Listener]: ...
151 |     def listen_and_forward(self, url: str) -> Awaitable[Listener]: ...
152 |     def listen_and_serve(self, server: Any) -> Awaitable[Listener]: ...
153 |     def metadata(self, metadata: str) -> TlsListenerBuilder: ...
154 |     def mutual_tlsca(self, mutual_tlsca: bytearray) -> TlsListenerBuilder: ...
155 |     def policy(self, policy: str) -> TlsListenerBuilder: ...
156 |     def pooling_enabled(self, pooling_enabled: bool) -> TlsListenerBuilder: ...
157 |     def proxy_proto(self, proxy_proto: str) -> TlsListenerBuilder: ...
158 |     def termination(
159 |         self, cert_pem: bytearray, key_pem: bytearray
160 |     ) -> TlsListenerBuilder: ...
161 |     def traffic_policy(self, policy: str) -> TlsListenerBuilder: ...
162 |     def verify_upstream_tls(self, verify_upstream_tls: bool) -> TlsListenerBuilder: ...
163 | 


--------------------------------------------------------------------------------
/src/wrapper.rs:
--------------------------------------------------------------------------------
  1 | use pyo3::{
  2 |     intern,
  3 |     pyfunction,
  4 |     types::{
  5 |         PyModule,
  6 |         PyString,
  7 |         PyTuple,
  8 |     },
  9 |     IntoPy,
 10 |     Py,
 11 |     PyAny,
 12 |     PyErr,
 13 |     PyResult,
 14 |     Python,
 15 | };
 16 | 
 17 | use crate::{
 18 |     listener::{
 19 |         TCP_PREFIX,
 20 |         UNIX_PREFIX,
 21 |     },
 22 |     py_err,
 23 | };
 24 | 
 25 | /// Create a path name to use for pipe forwarding.
 26 | /// This will be a file path in the temp directory on unix-like systems,
 27 | /// or a named pipe on Windows. Files will be removed at program exit.
 28 | #[pyfunction]
 29 | pub fn pipe_name(py: Python) -> PyResult<Py<PyAny>> {
 30 |     call_code(
 31 |         py,
 32 |         None,
 33 |         r#"
 34 | import atexit
 35 | import logging
 36 | import os
 37 | import random
 38 | import tempfile
 39 | 
 40 | path = '\\\\.\\pipe\\ngrok_pipe' if os.name == 'nt' else \
 41 |     "{}/tun-{}.sock".format(tempfile.gettempdir(), random.randrange(0,1000000))
 42 | 
 43 | def delete_socket():
 44 |     if os.path.exists(path):
 45 |         logging.info('deleting {}'.format(path))
 46 |         os.remove(path)
 47 | 
 48 | def run(input=None):
 49 |     atexit.register(delete_socket)
 50 |     return path
 51 |     "#,
 52 |     )
 53 | }
 54 | 
 55 | /// Create a default HTTP listener. Optionally pass in a connected Session to use.
 56 | ///
 57 | /// Returns the listener if no async loop is running, otherwise returns a Task to await with a listener result.
 58 | ///
 59 | /// :param session: The Session to use to create the listener.
 60 | /// :type session: Session or None
 61 | /// :return: The created listener.
 62 | /// :rtype: Listener
 63 | #[pyfunction]
 64 | #[pyo3(text_signature = "(session=None)")]
 65 | pub fn default(py: Python, session: Option<Py<PyAny>>) -> PyResult<Py<PyAny>> {
 66 |     default_listener_with_return(py, session, "listener")
 67 | }
 68 | 
 69 | /// Create a default HTTP listener and get its file descriptor. Optionally pass in a connected Session to use.
 70 | ///
 71 | /// Returns the file descriptor if no async loop is running, otherwise returns a Task to await with a file descriptor result.
 72 | ///
 73 | /// :param session: The Session to use to create the listener.
 74 | /// :type session: Session or None
 75 | /// :return: The file descriptor of the created listener's forwarding socket.
 76 | /// :rtype: int
 77 | #[pyfunction]
 78 | #[pyo3(text_signature = "(session=None)")]
 79 | pub fn fd(py: Python, session: Option<Py<PyAny>>) -> PyResult<Py<PyAny>> {
 80 |     default_listener_with_return(py, session, "listener.fd")
 81 | }
 82 | 
 83 | /// Create a default HTTP listener and get its socket name. Optionally pass in a connected Session to use.
 84 | ///
 85 | /// Returns the socket name if no async loop is running, otherwise returns a Task to await with a socket name result.
 86 | ///
 87 | /// :param session: The Session to use to create the listener.
 88 | /// :type session: Session or None
 89 | /// :return: The name of the created listener's forwarding socket.
 90 | /// :rtype: str
 91 | #[pyfunction]
 92 | #[pyo3(text_signature = "(session=None)")]
 93 | pub fn getsockname(py: Python, session: Option<Py<PyAny>>) -> PyResult<Py<PyAny>> {
 94 |     default_listener_with_return(py, session, "listener.getsockname()")
 95 | }
 96 | 
 97 | fn default_listener_with_return(
 98 |     py: Python,
 99 |     session: Option<Py<PyAny>>,
100 |     return_str: &str,
101 | ) -> PyResult<Py<PyAny>> {
102 |     loop_wrap(
103 |         py,
104 |         session,
105 |         &format!(
106 |             r###"
107 |     if input is None:
108 |         input = await SessionBuilder().authtoken_from_env().connect()
109 |     listener = await input.http_endpoint().listen()
110 |     return {return_str}
111 |     "###
112 |         ),
113 |     )
114 | }
115 | 
116 | /// Create and return a listening default HTTP listener.
117 | /// Optionally pass in an object with a "server_address" attribute,
118 | /// such as a http.server.HTTPServer, and the listener will
119 | /// forward TCP to that server_address. Optionally also pass in a previously created listener.
120 | ///
121 | /// Returns the created listener if no async loop is running, otherwise returns a Task to await with a listener result.
122 | ///
123 | /// :param server: The server to link with a listener.
124 | /// :type server: http.server.HTTPServer or None
125 | /// :param listener: The Listener to use to link with the server.
126 | /// :type listener: Listener or None
127 | /// :return: The listener linked with the server, or a Task to await for said listener.
128 | /// :rtype: Listener or Task
129 | #[pyfunction]
130 | #[pyo3(text_signature = "(server=None, listener=None)")]
131 | pub fn listen(
132 |     py: Python,
133 |     server: Option<Py<PyAny>>,
134 |     listener: Option<Py<PyAny>>,
135 | ) -> PyResult<Py<PyAny>> {
136 |     let mut forward = "".to_string();
137 |     if let Some(server) = server {
138 |         let address = address_from_server(py, server)?;
139 |         forward = format!("input.forward('{address}')");
140 |     }
141 | 
142 |     loop_wrap(
143 |         py,
144 |         listener,
145 |         &format!(
146 |             r###"
147 |     if input is None:
148 |         session = await SessionBuilder().authtoken_from_env().connect()
149 |         input = await session.http_endpoint().listen()
150 |     {forward}
151 |     return input
152 |     "###
153 |         ),
154 |     )
155 | }
156 | 
157 | pub(crate) fn address_from_server(py: Python, server: Py<PyAny>) -> Result<String, PyErr> {
158 |     let server_address_attr = server.getattr(py, "server_address")?;
159 |     let address_type = server_address_attr.as_ref(py).get_type();
160 |     if server_address_attr
161 |         .as_ref(py)
162 |         .is_instance(py.get_type::<PyTuple>())?
163 |     {
164 |         let address: &PyTuple = server_address_attr.downcast(py)?;
165 |         Ok(format!(
166 |             "{TCP_PREFIX}{}:{}",
167 |             address.get_item(0)?,
168 |             address.get_item(1)?
169 |         ))
170 |     } else if server_address_attr
171 |         .as_ref(py)
172 |         .is_instance(py.get_type::<PyString>())?
173 |     {
174 |         let address: &PyString = server_address_attr.downcast(py)?;
175 |         Ok(format!("{UNIX_PREFIX}{address}"))
176 |     } else {
177 |         return Err(py_err(format!(
178 |             "Unhandled server_address type: {address_type}"
179 |         )));
180 |     }
181 | }
182 | 
183 | /// Set the WERKZEUG_SERVER_FD environment variable with a file descriptor from a default HTTP listener.
184 | /// Also sets WERKZEUG_RUN_MAIN to "true" to engage the use of WERKZEUG_SERVER_FD.
185 | ///
186 | /// Returns the created listener if no async loop is running, otherwise returns a Task to await with a listener result.
187 | ///
188 | /// :param listener: The Listener to use to link with the werkzeug server.
189 | /// :type listener: Listener or None
190 | /// :return: The listener linked with the server, or a Task to await for said listener.
191 | /// :rtype: Listener or Task
192 | #[pyfunction]
193 | #[pyo3(text_signature = "(listener=None)")]
194 | pub fn werkzeug_develop(py: Python, listener: Option<Py<PyAny>>) -> PyResult<Py<PyAny>> {
195 |     loop_wrap(
196 |         py,
197 |         listener,
198 |         r#"
199 |     if input is None:
200 |         session = await SessionBuilder().authtoken_from_env().connect()
201 |         input = await session.http_endpoint().listen()
202 | 
203 |     import os
204 |     os.environ["WERKZEUG_SERVER_FD"] = str(input.fd)
205 |     os.environ["WERKZEUG_RUN_MAIN"] = "true"
206 |     return input
207 |     "#,
208 |     )
209 | }
210 | 
211 | /// Python wrapper to call the passed in work in an async context whether or not an async loop is running.
212 | pub(crate) fn loop_wrap(py: Python, input: Option<Py<PyAny>>, work: &str) -> PyResult<Py<PyAny>> {
213 |     let code = format!(
214 |         r###"
215 | import asyncio
216 | import ngrok
217 | from ngrok import SessionBuilder
218 | 
219 | async def wrap(input=None):
220 | {work}
221 | 
222 | def run(input=None):
223 |     try:
224 |         running_loop = asyncio.get_running_loop()
225 |         return running_loop.create_task(wrap(input))
226 |     except RuntimeError:
227 |         pass
228 | 
229 |     return asyncio.run(wrap(input))
230 |     "###
231 |     );
232 | 
233 |     call_code(py, input, code.as_str())
234 | }
235 | 
236 | /// Call the given code, returning the required 'retval' attribute from it.
237 | fn call_code(py: Python, input: Option<Py<PyAny>>, code: &str) -> PyResult<Py<PyAny>> {
238 |     // give fake filename and module name to not interfere with other projects' empty-string module
239 |     let run = PyModule::from_code(py, code, "ngrok_wrapper", "ngrok_wrapper")?.getattr("run")?;
240 | 
241 |     let res = match input {
242 |         Some(input) => {
243 |             let args = PyTuple::new(py, &[input]);
244 |             run.call1(args)?
245 |         }
246 |         None => run.call0()?,
247 |     };
248 | 
249 |     Ok(res.into())
250 | }
251 | 
252 | /// Create and bind a python localhost TCP socket.
253 | pub(crate) fn bound_default_tcp_socket(py: Python) -> PyResult<Py<PyAny>> {
254 |     let socket = PyModule::import(py, intern!(py, "socket"))?;
255 |     let sock_func = socket.getattr(intern!(py, "socket"))?;
256 |     let obj = sock_func.call0()?;
257 |     let bind = obj.getattr(intern!(py, "bind"))?;
258 |     let host: &PyAny = PyString::new(py, "localhost");
259 |     let port: &PyAny = 0u8.into_py(py).into_ref(py);
260 |     let address = PyTuple::new(py, [host, port]);
261 |     let args = PyTuple::new(py, [address]);
262 |     bind.call1(args)?;
263 |     let res = obj.into_py(py);
264 |     Ok(res)
265 | }
266 | 
267 | /// Create and bind a python unix socket.
268 | pub(crate) fn bound_default_unix_socket(py: Python) -> PyResult<Py<PyAny>> {
269 |     let socket = PyModule::import(py, intern!(py, "socket"))?;
270 |     let sock_func = socket.getattr(intern!(py, "socket"))?;
271 |     let af_unix = socket.getattr(intern!(py, "AF_UNIX"))?;
272 |     let sock_args = PyTuple::new(py, [af_unix]);
273 |     let obj = sock_func.call1(sock_args)?;
274 |     let bind = obj.getattr(intern!(py, "bind"))?;
275 |     let address = pipe_name(py)?;
276 |     let args = PyTuple::new(py, &[address]);
277 |     bind.call1(args)?;
278 |     let res = obj.into_py(py);
279 |     Ok(res)
280 | }
281 | 
282 | pub fn wrap_object(py: Python, input: Py<PyAny>) -> PyResult<Py<PyAny>> {
283 |     call_code(
284 |         py,
285 |         Some(input),
286 |         r###"
287 | class Proxy:
288 |     def __init__(self, proxied):
289 |         object.__setattr__(self, '_proxied', proxied)
290 | 
291 |     def __getattribute__(self, name):
292 |         p = object.__getattribute__(self, '_proxied')
293 |         return getattr(p, name)
294 | 
295 |     def __setattr__(self, name, value):
296 |         p = object.__getattribute__(self, '_proxied')
297 |         setattr(p, name, value)
298 | 
299 |     def __getitem__(self, key):
300 |         p = object.__getattribute__(self, '_proxied')
301 |         return p[key]
302 | 
303 |     def __setitem__(self, key, value):
304 |         p = object.__getattribute__(self, '_proxied')
305 |         p[key] = value
306 | 
307 |     def __delitem__(self, key):
308 |         p = object.__getattribute__(self, '_proxied')
309 |         del p[key]
310 | 
311 | def run(input):
312 |     return Proxy(input)
313 | "###,
314 |     )
315 | }
316 | 


--------------------------------------------------------------------------------
/.github/workflows/build.yml:
--------------------------------------------------------------------------------
  1 | on:
  2 |   workflow_call:
  3 |     inputs:
  4 |       docker:
  5 |         required: false
  6 |         type: string
  7 |       host:
  8 |         required: true
  9 |         type: string
 10 |       if:
 11 |         description: 'Whether to run this job'
 12 |         required: false
 13 |         default: true
 14 |         type: boolean
 15 |       publish:
 16 |         required: false
 17 |         type: boolean
 18 |         default: false
 19 |       setup:
 20 |         required: false
 21 |         type: string
 22 |       target:
 23 |         required: true
 24 |         type: string
 25 | jobs:
 26 |   reusable-build:
 27 |     if: ${{ inputs.if }}
 28 |     name: stable - ${{ inputs.target }} - python@3.12
 29 |     runs-on: ${{ inputs.host }}
 30 |     env:
 31 |       PYTHON_VERSION: "3.12"
 32 |       MATURIN_VERSION: "v1.9.1"
 33 |       XWIN_VERSION: "16"
 34 |     steps:
 35 |       - name: Checkout
 36 |         uses: actions/checkout@v4
 37 |       - name: Cache cargo
 38 |         uses: actions/cache@v4
 39 |         with:
 40 |           path: |
 41 |             ~/.cargo/registry/index/
 42 |             ~/.cargo/registry/cache/
 43 |             ~/.cargo/git/db/
 44 |             .cargo-cache
 45 |             target/
 46 |           key: ${{ inputs.target }}-cargo-${{ inputs.host }}
 47 |       - name: Setup toolchain
 48 |         run: ${{ inputs.setup }}
 49 |         if: ${{ inputs.setup }}
 50 |         shell: bash
 51 |       - name: Install nasm for i686-pc-windows-msvc
 52 |         uses: ilammy/setup-nasm@v1
 53 |         if: inputs.target == 'i686-pc-windows-msvc'
 54 |       - name: Setup x86 Python for i686-pc-windows-msvc
 55 |         if: ${{ inputs.target == 'i686-pc-windows-msvc' }}
 56 |         uses: actions/setup-python@v5
 57 |         with:
 58 |           python-version: ${{ env.PYTHON_VERSION }}
 59 |           architecture: "x86"
 60 |       - name: Download ARM64 Python SDK
 61 |         if: ${{ inputs.target == 'aarch64-pc-windows-msvc' }}
 62 |         run: |
 63 |           curl -LO https://www.python.org/ftp/python/${{ env.PYTHON_VERSION }}.0/python-${{ env.PYTHON_VERSION }}.0-embed-arm64.zip
 64 |           mkdir python-arm64
 65 |           tar -xf python-${{ env.PYTHON_VERSION }}.0-embed-arm64.zip -C python-arm64
 66 |       - name: Set ARM64 Python environment variables 
 67 |         if: ${{ inputs.target == 'aarch64-pc-windows-msvc' }}
 68 |         shell: pwsh
 69 |         run: |
 70 |           echo "PYTHONHOME=${{ github.workspace }}\python-arm64" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
 71 |           echo "PYTHONPATH=${{ github.workspace }}\python-arm64" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
 72 |           echo "PATH=${{ github.workspace }}\python-arm64;${env:PATH}" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
 73 | 
 74 |       - name: Build and (Publish) musl for ${{ inputs.target }}
 75 |         uses: addnab/docker-run-action@v3
 76 |         if: ${{ inputs.target == 'x86_64-unknown-linux-musl' || inputs.target == 'aarch64-unknown-linux-musl' }}
 77 |         with:
 78 |           image: ${{ inputs.docker }}
 79 |           options: '-e SHOULD_PUBLISH=${{ inputs.publish }} --user 0:0 -v ${{ github.workspace }}/.cargo-cache/git/db:/usr/local/cargo/git/db -v ${{ github.workspace }}/.cargo/registry/cache:/usr/local/cargo/registry/cache -v ${{ github.workspace }}/.cargo/registry/index:/usr/local/cargo/registry/index -v ${{ github.workspace }}:/build -w /build'
 80 |           run: |
 81 |             echo "apk add:"
 82 |             apk upgrade
 83 |             apk add musl-dev gcc make cmake clang-libclang rustup python3-dev bash
 84 |             rustup-init -y
 85 |             . $HOME/.cargo/env
 86 | 
 87 |             echo "create venv:"
 88 |             make venv
 89 |             ./venv/bin/pip install patchelf
 90 |             make build
 91 | 
 92 |             if [ "${SHOULD_PUBLISH}" == 'true' ]; then
 93 |               echo "~~~~ maturin publishing"
 94 |               . ./venv/bin/activate && maturin publish --no-sdist --skip-existing -u __token__ -p ${{ secrets.MATURIN_PASSWORD }}
 95 |             fi
 96 | 
 97 |       - name: Build and (Publish) aarch64-unknown-linux-gnu
 98 |         uses: addnab/docker-run-action@v3
 99 |         if: ${{ inputs.target == 'aarch64-unknown-linux-gnu' }}
100 |         with:
101 |           image: ${{ inputs.docker }}
102 |           options: '-e SHOULD_PUBLISH=${{ inputs.publish }} --user 0:0 -v ${{ github.workspace }}/.cargo-cache/git/db:/usr/local/cargo/git/db -v ${{ github.workspace }}/.cargo/registry/cache:/usr/local/cargo/registry/cache -v ${{ github.workspace }}/.cargo/registry/index:/usr/local/cargo/registry/index -v ${{ github.workspace }}:/build -w /build'
103 |           run: |
104 |             # Ensure multilib support is available
105 |             sudo apt -y update
106 |             sudo apt -y full-upgrade
107 |             sudo apt -y install gcc-multilib
108 | 
109 |             # Install Rust
110 |             curl --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal
111 |             export PATH="$HOME/.cargo/bin:$PATH"
112 | 
113 |             # ring 0.17 assembly build needs __ARM_ARCH set
114 |             export CFLAGS_aarch64_unknown_linux_gnu="-D__ARM_ARCH=8"
115 |             rustup component add llvm-tools-preview || true
116 |             rustup target add aarch64-unknown-linux-gnu
117 |             python3 -m venv .env
118 |             . .env/bin/activate && pip install -r requirements.txt
119 |             . .env/bin/activate && pip install patchelf
120 |             # this is in raw 'sh', use single '='
121 |             if [ "${SHOULD_PUBLISH}" = 'true' ]; then
122 |               echo "~~~~ maturin publishing"
123 |               # pass '--debug' to avoid optimization, which breaks tls signature validation on this platform
124 |               . .env/bin/activate && maturin publish --target ${{ inputs.target }} --no-sdist --skip-existing --debug -u __token__ -p ${{ secrets.MATURIN_PASSWORD }}
125 |             else
126 |               echo "~~~~ maturin building"
127 |               . .env/bin/activate && maturin build --target ${{ inputs.target }}
128 |             fi
129 |       - name: Build and (Publish) armv7-unknown-linux-gnueabihf
130 |         uses: addnab/docker-run-action@v3
131 |         if: ${{ inputs.target == 'armv7-unknown-linux-gnueabihf' }}
132 |         with:
133 |           image: ${{ inputs.docker }}
134 |           options: '-e SHOULD_PUBLISH=${{ inputs.publish }} --user 0:0 -v ${{ github.workspace }}/.cargo-cache/git/db:/usr/local/cargo/git/db -v ${{ github.workspace }}/.cargo/registry/cache:/usr/local/cargo/registry/cache -v ${{ github.workspace }}/.cargo/registry/index:/usr/local/cargo/registry/index -v ${{ github.workspace }}:/build -w /build'
135 |           run: |
136 |             # Ensure multilib support is available
137 |             sudo apt -y update
138 |             sudo apt -y full-upgrade
139 |             sudo apt -y install gcc-multilib
140 | 
141 |             # Set up bindgen environment
142 |             export BINDGEN_EXTRA_CLANG_ARGS="--target=armv7-unknown-linux-gnueabihf"
143 |             export BINDGEN_SYSROOT="/usr/arm-linux-gnueabihf"
144 |             export RUST_BACKTRACE=1
145 |             
146 |             # Install Rust and configure ARM target
147 |             curl --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal
148 |             export PATH="$HOME/.cargo/bin:$PATH"
149 |             rustup target add armv7-unknown-linux-gnueabihf
150 |             cargo install --force --locked bindgen-cli
151 | 
152 |             python3 -m venv .env
153 |             . .env/bin/activate && pip install -r requirements.txt
154 |             . .env/bin/activate && pip install patchelf
155 |             # this is in raw 'sh', use single '='
156 |             if [ "${SHOULD_PUBLISH}" = 'true' ]; then
157 |               echo "~~~~ maturin publishing"
158 |               # pass '--debug' to avoid optimization, which breaks tls signature validation on this platform
159 |               . .env/bin/activate && maturin publish --target ${{ inputs.target }} --no-sdist --skip-existing --debug -u __token__ -p ${{ secrets.MATURIN_PASSWORD }}
160 |             else
161 |               echo "~~~~ maturin building"
162 |               RUST_BACKTRACE=1 . .env/bin/activate && maturin build --target ${{ inputs.target }} --verbose
163 |             fi
164 |       - name: Build and (Publish) x86_64-unknown-linux-gnu
165 |         uses: addnab/docker-run-action@v3
166 |         if: ${{ inputs.target == 'x86_64-unknown-linux-gnu' }}
167 |         with:
168 |           image: ${{ inputs.docker }}
169 |           options: '-e SHOULD_PUBLISH=${{ inputs.publish }} --user 0:0 -v ${{ github.workspace }}/.cargo-cache/git/db:/usr/local/cargo/git/db -v ${{ github.workspace }}/.cargo/registry/cache:/usr/local/cargo/registry/cache -v ${{ github.workspace }}/.cargo/registry/index:/usr/local/cargo/registry/index -v ${{ github.workspace }}:/build -w /build'
170 |           run: |
171 |             # Update and install required packages
172 |             sudo apt-get update
173 |             sudo apt-get install -y llvm-dev clang libclang-dev gcc-multilib
174 | 
175 |             # Install Rust minimal toolchain
176 |             curl --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal
177 |             export PATH="$HOME/.cargo/bin:$PATH"
178 | 
179 |             # Add necessary Rust targets and components
180 |             rustup component add llvm-tools-preview || true
181 |             rustup target add x86_64-unknown-linux-gnu
182 | 
183 |             # Create and activate Python virtual environment
184 |             python3 -m venv .env
185 |             . .env/bin/activate && pip install -r requirements.txt
186 |             . .env/bin/activate && pip install patchelf
187 | 
188 |             if [ "${SHOULD_PUBLISH}" = 'true' ]; then
189 |               echo "~~~~ maturin publishing"
190 |               . .env/bin/activate && maturin publish --target ${{ inputs.target }} --no-sdist --skip-existing -i python3.12 -u __token__ -p ${{ secrets.MATURIN_PASSWORD }}
191 |             else
192 |               echo "~~~~ maturin building"
193 |               . .env/bin/activate && maturin build --target ${{ inputs.target }}
194 |             fi
195 |       - name: Build Python Extension Module (non-docker)
196 |         if: ${{ inputs.publish != true && !inputs.docker && !contains(inputs.target,'android') }}
197 |         uses: PyO3/maturin-action@v1
198 |         with:
199 |           maturin-version: ${{ env.MATURIN_VERSION }}
200 |           target: ${{ inputs.target }}
201 |           args: --release -i python${{ env.PYTHON_VERSION }} --target ${{ inputs.target }} -m Cargo.toml
202 |         env:
203 |           XWIN_VERSION: ${{ env.XWIN_VERSION }}
204 |       - name: Publish to PyPI (non-docker)
205 |         if: ${{ inputs.publish == true && !inputs.docker && !contains(inputs.target,'android') }}
206 |         uses: PyO3/maturin-action@v1
207 |         with:
208 |           command: publish
209 |           maturin-version: ${{ env.MATURIN_VERSION }}
210 |           target: ${{ inputs.target }}
211 |           args: --no-sdist --skip-existing -i python${{ env.PYTHON_VERSION }} -m Cargo.toml -u __token__ -p ${{ secrets.MATURIN_PASSWORD }}
212 |       - name: Upload artifact
213 |         uses: actions/upload-artifact@v4
214 |         with:
215 |           name: bindings-${{ inputs.target }}
216 |           path: target/wheels/*.whl # path to the python wheel package
217 |           if-no-files-found: error
218 | 


--------------------------------------------------------------------------------
/src/listener_builder.rs:
--------------------------------------------------------------------------------
  1 | use std::{
  2 |     str::FromStr,
  3 |     sync::Arc,
  4 | };
  5 | 
  6 | use ngrok::{
  7 |     prelude::*,
  8 |     Session,
  9 | };
 10 | use parking_lot::Mutex;
 11 | use pyo3::{
 12 |     pyclass,
 13 |     pymethods,
 14 |     Bound,
 15 |     Py,
 16 |     PyAny,
 17 |     PyRefMut,
 18 |     PyResult,
 19 |     Python,
 20 | };
 21 | use tracing::debug;
 22 | use url::Url;
 23 | 
 24 | use crate::{
 25 |     listener::{
 26 |         HttpListener,
 27 |         LabeledListener,
 28 |         Listener,
 29 |         TcpListener,
 30 |         TlsListener,
 31 |     },
 32 |     py_err,
 33 |     py_ngrok_err,
 34 |     wrapper::address_from_server,
 35 | };
 36 | 
 37 | macro_rules! make_listener_builder {
 38 |     ($(#[$outer:meta])* $wrapper:ident, $builder:tt, $listener:tt, $mode:tt) => {
 39 |         $(#[$outer])*
 40 |         #[pyclass]
 41 |         #[allow(dead_code)]
 42 |         pub(crate) struct $wrapper {
 43 |             session: Arc<Mutex<Session>>,
 44 |             pub(crate) listener_builder: Arc<Mutex<$builder>>,
 45 |         }
 46 | 
 47 |         #[pymethods]
 48 |         #[allow(dead_code)]
 49 |         impl $wrapper {
 50 |             /// Listener-specific opaque metadata. Viewable via the API.
 51 |             pub fn metadata(self_: PyRefMut<Self>, metadata: String) -> PyRefMut<Self> {
 52 |                 self_.set(|b| {b.metadata(metadata);});
 53 |                 self_
 54 |             }
 55 | 
 56 |             /// Whether to disable certificate verification for this listener.
 57 |             pub fn verify_upstream_tls(self_: PyRefMut<Self>, verify_upstream_tls: bool) -> PyRefMut<Self> {
 58 |                 self_.set(|b| {b.verify_upstream_tls(verify_upstream_tls);});
 59 |                 self_
 60 |             }
 61 | 
 62 |             /// Begin listening for new connections on this listener.
 63 |             pub fn listen<'a>(&self, py: Python<'a>) -> PyResult<Bound<'a, PyAny>> {
 64 |                 let session = self.session.lock().clone();
 65 |                 let tun = self.listener_builder.lock().clone();
 66 |                 pyo3_async_runtimes::tokio::future_into_py(
 67 |                     py,
 68 |                     async move {
 69 |                         $wrapper::do_listen(session, tun).await
 70 |                     },
 71 |                 )
 72 |             }
 73 | 
 74 |             /// Begin listening for new connections on this listener and forwarding them to the given url.
 75 |             /// This url can be either a TCP/HTTP address or a file socket path, for example:
 76 |             /// "http://localhost:8080", "https://192.168.1.100:8443", or for file socket paths on
 77 |             /// Linux/Darwin "unix:///path/to/unix.sock".
 78 |             ///
 79 |             /// :param to_url: The URL to forward traffic on to
 80 |             /// :return: A task to await for the :class:`Listener` linked with the server.
 81 |             /// :rtype: Task
 82 |             pub fn listen_and_forward<'a>(&self, to_url: String, py: Python<'a>) -> PyResult<Bound<'a, PyAny>> {
 83 |                 let url = Url::parse(&to_url).map_err(|e| py_err(format!("Url forward argument parse failure, {e}")))?;
 84 |                 let session = self.session.lock().clone();
 85 |                 let builder = self.listener_builder.lock().clone();
 86 | 
 87 |                 pyo3_async_runtimes::tokio::future_into_py(
 88 |                     py,
 89 |                     async move {
 90 |                         let result = builder
 91 |                         .listen_and_forward(url)
 92 |                         .await
 93 |                         .map_err(|e| py_ngrok_err("failed to start listener", &e));
 94 | 
 95 |                         // create the wrapping listener object via its async new()
 96 |                         match result {
 97 |                             Ok(raw_fwd) => Ok($listener::new_forwarder(session, raw_fwd).await),
 98 |                             Err(val) => Err(val),
 99 |                         }
100 |                     },
101 |                 )
102 |             }
103 | 
104 |             /// Begin listening for new connections on this listener and forwarding them to the given http server.
105 |             ///
106 |             /// :param server: The server to link with a :class:`Listener`.
107 |             /// :type server: http.server.HTTPServer or None
108 |             /// :return: A task to await for the :class:`Listener` linked with the server.
109 |             /// :rtype: Task
110 |             pub fn listen_and_serve<'a>(
111 |                 &self,
112 |                 py: Python<'a>,
113 |                 server: Py<PyAny>,
114 |             ) -> PyResult<Bound<'a, PyAny>> {
115 |                 let address = address_from_server(py, server)?;
116 |                 return self.listen_and_forward(address, py)
117 |             }
118 |         }
119 | 
120 |         #[allow(dead_code)]
121 |         impl $wrapper {
122 |             pub(crate) fn new(session: Session, raw_listener_builder: $builder) -> Self {
123 |                 $wrapper {
124 |                     session: Arc::new(Mutex::new(session)),
125 |                     listener_builder: Arc::new(Mutex::new(raw_listener_builder)),
126 |                 }
127 |             }
128 | 
129 |             /// Handle the locking and Option management
130 |             pub(crate) fn set<F>(&self, f: F)
131 |             where
132 |                 F: FnOnce(&mut parking_lot::lock_api::MutexGuard<'_, parking_lot::RawMutex, $builder>),
133 |             {
134 |                 let mut builder = self.listener_builder.lock();
135 |                 f(&mut builder);
136 |             }
137 | 
138 |             pub(crate) async fn async_listen(&self) -> PyResult<Listener> {
139 |                 let session = self.session.lock().clone();
140 |                 let tun = self.listener_builder.lock().clone();
141 |                 $wrapper::do_listen(session, tun).await
142 |             }
143 | 
144 |             async fn do_listen(session: Session, builder: $builder) -> PyResult<Listener> {
145 |                 let result = builder
146 |                             .listen()
147 |                             .await
148 |                             .map_err(|e| py_ngrok_err("failed to start listener", &e));
149 | 
150 |                 // create the wrapping listener object via its async new()
151 |                 match result {
152 |                     Ok(raw_tun) => Ok($listener::new_listener(session, raw_tun).await),
153 |                     Err(val) => Err(val),
154 |                 }
155 |             }
156 |         }
157 | 
158 |         impl Drop for $wrapper {
159 |             fn drop(&mut self) {
160 |                 debug!("{} drop", stringify!($wrapper));
161 |             }
162 |         }
163 | 
164 | 
165 |         // mode specific methods
166 |         make_listener_builder!($mode, $wrapper);
167 |     };
168 | 
169 |     (common, $wrapper:ty) => {
170 |         #[pymethods]
171 |         #[allow(dead_code)]
172 |         impl $wrapper {
173 |             /// Restriction placed on the origin of incoming connections to the edge to only allow these CIDR ranges.
174 |             /// Call multiple times to add additional CIDR ranges.
175 |             /// See `IP restrictions`_ in the ngrok docs for additional details.
176 |             ///
177 |             /// .. _IP restrictions: https://ngrok.com/docs/cloud-edge/modules/ip-restrictions/
178 |             pub fn allow_cidr(self_: PyRefMut<Self>, cidr: String) -> PyRefMut<Self> {
179 |                 self_.set(|b| {b.allow_cidr(cidr);});
180 |                 self_
181 |             }
182 |             /// Restriction placed on the origin of incoming connections to the edge to deny these CIDR ranges.
183 |             /// Call multiple times to add additional CIDR ranges.
184 |             /// See `IP restrictions`_ in the ngrok docs for additional details.
185 |             ///
186 |             /// .. _IP restrictions: https://ngrok.com/docs/cloud-edge/modules/ip-restrictions/
187 |             pub fn deny_cidr(self_: PyRefMut<Self>, cidr: String) -> PyRefMut<Self> {
188 |                 self_.set(|b| {b.deny_cidr(cidr);});
189 |                 self_
190 |             }
191 |             /// The version of PROXY protocol to use with this listener "1", "2", or "" if not using.
192 |             pub fn proxy_proto(self_: PyRefMut<Self>, proxy_proto: String) -> PyRefMut<Self> {
193 |                 self_.set(|b| {b.proxy_proto(
194 |                     ProxyProto::from_str(proxy_proto.as_str())
195 |                         .unwrap_or_else(|_| panic!("Unknown proxy protocol: {:?}", proxy_proto)),
196 |                 );});
197 |                 self_
198 |             }
199 |             /// Listener backend metadata. Viewable via the dashboard and API, but has no
200 |             /// bearing on listener behavior.
201 |             ///
202 |             /// To automatically forward connections, you can use :any:`listen_and_forward`,
203 |             /// or :any:`listen_and_serve` on the Listener Builder.
204 |             pub fn forwards_to(self_: PyRefMut<Self>, forwards_to: String) -> PyRefMut<Self> {
205 |                 self_.set(|b| {b.forwards_to(forwards_to);});
206 |                 self_
207 |             }
208 | 
209 |             /// DEPRECATED: use traffic_policy instead.
210 |             /// :param str policy_config: Traffic policy configuration to be attached to the listener.
211 |             pub fn policy(self_: PyRefMut<Self>, policy_config: String) -> PyRefMut<Self> {
212 |                 self_.set(|b| {b.traffic_policy(policy_config);});
213 |                 self_
214 |             }
215 | 
216 |             /// Traffic Policy configuration.
217 |             /// :param str policy_config: Traffic policy configuration to be attached to the listener.
218 |             pub fn traffic_policy(self_: PyRefMut<Self>, policy_config: String) -> PyRefMut<Self> {
219 |                 self_.set(|b| {b.traffic_policy(policy_config);});
220 |                 self_
221 |             }
222 |         }
223 |     };
224 | 
225 |     (label, $wrapper:ty) => {
226 |         #[pymethods]
227 |         #[allow(dead_code)]
228 |         impl $wrapper {
229 |             /// Add a label, value pair for this listener.
230 |             /// See `Using Labels`_ in the ngrok docs for additional details.
231 |             ///
232 |             /// .. _Using Labels: https://ngrok.com/docs/guides/using-labels-within-ngrok/
233 |             pub fn label(self_: PyRefMut<Self>, label: String, value: String) -> PyRefMut<Self> {
234 |                 self_.set(|b| {b.label(label, value);});
235 |                 self_
236 |             }
237 | 
238 |             /// Set the L7 application protocol used for this listener, i.e. "http1" or "http2" (default "http1")
239 |             pub fn app_protocol(self_: PyRefMut<Self>, app_protocol: String) -> PyRefMut<Self> {
240 |                 self_.set(|b| {b.app_protocol(app_protocol);});
241 |                 self_
242 |             }
243 |         }
244 |     };
245 | }
246 | 
247 | make_listener_builder! {
248 |     /// An ngrok listener backing an HTTP endpoint.
249 |     HttpListenerBuilder, HttpTunnelBuilder, HttpListener, common
250 | }
251 | make_listener_builder! {
252 |     /// An ngrok listener backing a TCP endpoint.
253 |     TcpListenerBuilder, TcpTunnelBuilder, TcpListener, common
254 | }
255 | make_listener_builder! {
256 |     /// An ngrok listener backing a TLS endpoint.
257 |     TlsListenerBuilder, TlsTunnelBuilder, TlsListener, common
258 | }
259 | make_listener_builder! {
260 |     /// A labeled ngrok listener.
261 |     LabeledListenerBuilder, LabeledTunnelBuilder, LabeledListener, label
262 | }
263 | 


--------------------------------------------------------------------------------
/docs/search.html:
--------------------------------------------------------------------------------
  1 | <!doctype html>
  2 | <html class="no-js" lang="en">
  3 |   <head><meta charset="utf-8"/>
  4 |     <meta name="viewport" content="width=device-width,initial-scale=1"/>
  5 |     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="#" />
  6 | 
  7 |     <!-- Generated with Sphinx 6.1.3 and Furo 2022.12.07 --><title>Search - ngrok  documentation</title><link rel="stylesheet" type="text/css" href="_static/pygments.css" />
  8 |     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=91d0f0d1c444bdcb17a68e833c7a53903343c195" />
  9 |     <link rel="stylesheet" type="text/css" href="_static/styles/furo-extensions.css?digest=30d1aed668e5c3a91c3e3bf6a60b675221979f0e" />
 10 |     
 11 |     
 12 | 
 13 | 
 14 | <style>
 15 |   body {
 16 |     --color-code-background: #f8f8f8;
 17 |   --color-code-foreground: black;
 18 |   
 19 |   }
 20 |   @media not print {
 21 |     body[data-theme="dark"] {
 22 |       --color-code-background: #202020;
 23 |   --color-code-foreground: #d0d0d0;
 24 |   
 25 |     }
 26 |     @media (prefers-color-scheme: dark) {
 27 |       body:not([data-theme="light"]) {
 28 |         --color-code-background: #202020;
 29 |   --color-code-foreground: #d0d0d0;
 30 |   
 31 |       }
 32 |     }
 33 |   }
 34 | </style></head>
 35 |   <body>
 36 |     
 37 |     <script>
 38 |       document.body.dataset.theme = localStorage.getItem("theme") || "auto";
 39 |     </script>
 40 |     
 41 | 
 42 | <svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
 43 |   <symbol id="svg-toc" viewBox="0 0 24 24">
 44 |     <title>Contents</title>
 45 |     <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024">
 46 |       <path d="M408 442h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8zm-8 204c0 4.4 3.6 8 8 8h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56zm504-486H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zm0 632H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zM115.4 518.9L271.7 642c5.8 4.6 14.4.5 14.4-6.9V388.9c0-7.4-8.5-11.5-14.4-6.9L115.4 505.1a8.74 8.74 0 0 0 0 13.8z"/>
 47 |     </svg>
 48 |   </symbol>
 49 |   <symbol id="svg-menu" viewBox="0 0 24 24">
 50 |     <title>Menu</title>
 51 |     <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
 52 |       stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu">
 53 |       <line x1="3" y1="12" x2="21" y2="12"></line>
 54 |       <line x1="3" y1="6" x2="21" y2="6"></line>
 55 |       <line x1="3" y1="18" x2="21" y2="18"></line>
 56 |     </svg>
 57 |   </symbol>
 58 |   <symbol id="svg-arrow-right" viewBox="0 0 24 24">
 59 |     <title>Expand</title>
 60 |     <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
 61 |       stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right">
 62 |       <polyline points="9 18 15 12 9 6"></polyline>
 63 |     </svg>
 64 |   </symbol>
 65 |   <symbol id="svg-sun" viewBox="0 0 24 24">
 66 |     <title>Light mode</title>
 67 |     <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
 68 |       stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="feather-sun">
 69 |       <circle cx="12" cy="12" r="5"></circle>
 70 |       <line x1="12" y1="1" x2="12" y2="3"></line>
 71 |       <line x1="12" y1="21" x2="12" y2="23"></line>
 72 |       <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
 73 |       <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
 74 |       <line x1="1" y1="12" x2="3" y2="12"></line>
 75 |       <line x1="21" y1="12" x2="23" y2="12"></line>
 76 |       <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
 77 |       <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
 78 |     </svg>
 79 |   </symbol>
 80 |   <symbol id="svg-moon" viewBox="0 0 24 24">
 81 |     <title>Dark mode</title>
 82 |     <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
 83 |       stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon">
 84 |       <path stroke="none" d="M0 0h24v24H0z" fill="none" />
 85 |       <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" />
 86 |     </svg>
 87 |   </symbol>
 88 |   <symbol id="svg-sun-half" viewBox="0 0 24 24">
 89 |     <title>Auto light/dark mode</title>
 90 |     <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
 91 |       stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-shadow">
 92 |       <path stroke="none" d="M0 0h24v24H0z" fill="none"/>
 93 |       <circle cx="12" cy="12" r="9" />
 94 |       <path d="M13 12h5" />
 95 |       <path d="M13 15h4" />
 96 |       <path d="M13 18h1" />
 97 |       <path d="M13 9h4" />
 98 |       <path d="M13 6h1" />
 99 |     </svg>
100 |   </symbol>
101 | </svg>
102 | 
103 | <input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation">
104 | <input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc">
105 | <label class="overlay sidebar-overlay" for="__navigation">
106 |   <div class="visually-hidden">Hide navigation sidebar</div>
107 | </label>
108 | <label class="overlay toc-overlay" for="__toc">
109 |   <div class="visually-hidden">Hide table of contents sidebar</div>
110 | </label>
111 | 
112 | 
113 | 
114 | <div class="page">
115 |   <header class="mobile-header">
116 |     <div class="header-left">
117 |       <label class="nav-overlay-icon" for="__navigation">
118 |         <div class="visually-hidden">Toggle site navigation sidebar</div>
119 |         <i class="icon"><svg><use href="#svg-menu"></use></svg></i>
120 |       </label>
121 |     </div>
122 |     <div class="header-center">
123 |       <a href="index.html"><div class="brand">ngrok  documentation</div></a>
124 |     </div>
125 |     <div class="header-right">
126 |       <div class="theme-toggle-container theme-toggle-header">
127 |         <button class="theme-toggle">
128 |           <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
129 |           <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
130 |           <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
131 |           <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
132 |         </button>
133 |       </div>
134 |       <label class="toc-overlay-icon toc-header-icon no-toc" for="__toc">
135 |         <div class="visually-hidden">Toggle table of contents sidebar</div>
136 |         <i class="icon"><svg><use href="#svg-toc"></use></svg></i>
137 |       </label>
138 |     </div>
139 |   </header>
140 |   <aside class="sidebar-drawer">
141 |     <div class="sidebar-container">
142 |       
143 |       <div class="sidebar-sticky"><a class="sidebar-brand" href="index.html">
144 |   
145 |   
146 |   <span class="sidebar-brand-text">ngrok  documentation</span>
147 |   
148 | </a><form class="sidebar-search-container" method="get" action="#" role="search">
149 |   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
150 |   <input type="hidden" name="check_keywords" value="yes">
151 |   <input type="hidden" name="area" value="default">
152 | </form>
153 | <div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
154 |   <p class="caption" role="heading"><span class="caption-text">Listener and Sessions:</span></p>
155 | <ul>
156 | <li class="toctree-l1"><a class="reference internal" href="session_builder.html">Session Builder</a></li>
157 | <li class="toctree-l1"><a class="reference internal" href="session.html">Session</a></li>
158 | <li class="toctree-l1"><a class="reference internal" href="listener.html">Listener</a></li>
159 | </ul>
160 | <p class="caption" role="heading"><span class="caption-text">Listener Builders:</span></p>
161 | <ul>
162 | <li class="toctree-l1"><a class="reference internal" href="http_listener_builder.html">HTTP Listener Builder</a></li>
163 | <li class="toctree-l1"><a class="reference internal" href="tcp_listener_builder.html">TCP Listener Builder</a></li>
164 | <li class="toctree-l1"><a class="reference internal" href="tls_listener_builder.html">TLS Listener Builder</a></li>
165 | <li class="toctree-l1"><a class="reference internal" href="labeled_listener_builder.html">Labeled Listener Builder</a></li>
166 | </ul>
167 | <p class="caption" role="heading"><span class="caption-text">Module:</span></p>
168 | <ul>
169 | <li class="toctree-l1"><a class="reference internal" href="module.html">Ngrok Module</a></li>
170 | </ul>
171 | 
172 | </div>
173 | </div>
174 | 
175 |       </div>
176 |       
177 |     </div>
178 |   </aside>
179 |   <div class="main">
180 |     <div class="content">
181 |       <div class="article-container">
182 |         <a href="#" class="back-to-top muted-link">
183 |           <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
184 |             <path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path>
185 |           </svg>
186 |           <span>Back to top</span>
187 |         </a>
188 |         <div class="content-icon-container">
189 |           <div class="theme-toggle-container theme-toggle-content">
190 |             <button class="theme-toggle">
191 |               <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
192 |               <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
193 |               <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
194 |               <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
195 |             </button>
196 |           </div>
197 |           <label class="toc-overlay-icon toc-content-icon no-toc" for="__toc">
198 |             <div class="visually-hidden">Toggle table of contents sidebar</div>
199 |             <i class="icon"><svg><use href="#svg-toc"></use></svg></i>
200 |           </label>
201 |         </div>
202 |         <article role="main">
203 |           
204 | <noscript>
205 | <div class="admonition error">
206 |   <p class="admonition-title">Error</p>
207 |   <p>
208 |     Please activate JavaScript to enable the search functionality.
209 |   </p>
210 | </div>
211 | </noscript>
212 | 
213 | <div id="search-results"></div>
214 | 
215 |         </article>
216 |       </div>
217 |       <footer>
218 |         
219 |         <div class="related-pages">
220 |           
221 |           
222 |         </div>
223 |         <div class="bottom-of-page">
224 |           <div class="left-details">
225 |             <div class="copyright">
226 |                 Copyright &#169;  2023, ngrok
227 |             </div>
228 |             Made with <a href="https://www.sphinx-doc.org/">Sphinx</a> and <a class="muted-link" href="https://pradyunsg.me">@pradyunsg</a>'s
229 |             
230 |             <a href="https://github.com/pradyunsg/furo">Furo</a>
231 |             
232 |           </div>
233 |           <div class="right-details">
234 |             
235 |           </div>
236 |         </div>
237 |         
238 |       </footer>
239 |     </div>
240 |     <aside class="toc-drawer no-toc">
241 |       
242 |       
243 |       
244 |     </aside>
245 |   </div>
246 | </div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
247 |     <script src="_static/doctools.js"></script>
248 |     <script src="_static/sphinx_highlight.js"></script>
249 |     <script src="_static/scripts/furo.js"></script>
250 |     
251 | <script src="_static/searchtools.js"></script>
252 | <script src="_static/language_data.js"></script>
253 | <script src="searchindex.js"></script></body>
254 | </html>


--------------------------------------------------------------------------------