Skip to content

Commit b6562f2

Browse files
bobzilladevbobzilladev
authored
Merge pull request #92 from ngrok/bob/connect-return-listener
Return Listener object from ngrok.connect
2 parents 1cc0034 + 531fff4 commit b6562f2

File tree

5 files changed

+46
-37
lines changed

5 files changed

+46
-37
lines changed

‎README.md

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -45,8 +45,8 @@ npm install @ngrok/ngrok
4545
```jsx
4646
const ngrok = require("@ngrok/ngrok");
4747
(async function() {
48-
const url = await ngrok.connect({ addr: 8080, authtoken_from_env: true });
49-
console.log(`Ingress established at: ${url}`);
48+
const listener = await ngrok.connect({ addr: 8080, authtoken_from_env: true });
49+
console.log(`Ingress established at: ${listener.url()}`);
5050
})();
5151
```
5252

@@ -83,56 +83,56 @@ With no arguments the [connect](https://ngrok.github.io/ngrok-nodejs/functions/c
8383
```jsx
8484
const ngrok = require("@ngrok/ngrok");
8585
(async function() {
86-
console.log( await ngrok.connect() );
86+
console.log( (await ngrok.connect()).url() );
8787
})();
8888
```
8989

9090
You can pass the port number to forward on `localhost`:
9191

9292
```jsx
93-
const url = await ngrok.connect(4242);
93+
const listener = await ngrok.connect(4242);
9494
```
9595

9696
Or you can specify the host and port via a string:
9797

9898
```jsx
99-
const url = await ngrok.connect("localhost:4242");
99+
const listener = await ngrok.connect("localhost:4242");
100100
```
101101

102102
More options can be passed to the `connect` method to customize the connection:
103103

104104
```jsx
105-
const url = await ngrok.connect({addr: 8080, basic_auth: "ngrok:online1line"});
106-
const url = await ngrok.connect({addr: 8080, oauth_provider: "google", oauth_allow_domains: "example.com"});
105+
const listener = await ngrok.connect({addr: 8080, basic_auth: "ngrok:online1line"});
106+
const listener = await ngrok.connect({addr: 8080, oauth_provider: "google", oauth_allow_domains: "example.com"});
107107
```
108108

109109
The (optional) `proto` parameter is the listener type, which defaults to `http`. To create a TCP listener:
110110

111111
```jsx
112-
const url = await ngrok.connect({proto: 'tcp', addr: 25565});
112+
const listener = await ngrok.connect({proto: 'tcp', addr: 25565});
113113
```
114114

115115
See [Full Configuration](#full-configuration) for the list of possible configuration options.
116116

117117
## Disconnection
118118

119-
To close a listener use the [disconnect](https://ngrok.github.io/ngrok-nodejs/functions/disconnect.html) method with the `url` of the listener to close:
119+
The [close](https://ngrok.github.io/ngrok-nodejs/classes/Listener.html#close) method on a listener will shut it down, and also stop the ngrok session if it is no longer needed. This method returns a promise that resolves when the listener is closed.
120120

121121
```jsx
122-
await ngrok.disconnect(url);
122+
const listener = await ngrok.getListenerByUrl(url);
123+
await listener.close();
123124
```
124125

125-
Or omit the `url` to close all listeners:
126+
Or use the [disconnect](https://ngrok.github.io/ngrok-nodejs/functions/disconnect.html) method with the `url()` of the listener to close (or id() for a Labeled Listener):
126127

127128
```jsx
128-
await ngrok.disconnect();
129+
await ngrok.disconnect(listener.url());
129130
```
130131

131-
The [close](https://ngrok.github.io/ngrok-nodejs/classes/Listener.html#close) method on a listener will shut it down, and also stop the ngrok session if it is no longer needed. This method returns a promise that resolves when the listener is closed.
132+
Or omit the `url()` to close all listeners:
132133

133134
```jsx
134-
const listener = await ngrok.getListenerByUrl(url);
135-
await listener.close();
135+
await ngrok.disconnect();
136136
```
137137

138138
## Listing Listeners
@@ -148,7 +148,7 @@ const listeners = await ngrok.listeners();
148148
This example shows [all the possible configuration items of ngrok.connect](https://github.com/ngrok/ngrok-nodejs/blob/main/examples/ngrok-connect-full.js):
149149

150150
```jsx
151-
const url = await ngrok.connect({
151+
const listener = await ngrok.connect({
152152
// session configuration
153153
addr: `localhost:8080`, // or `8080` or `unix:${UNIX_SOCKET}`
154154
authtoken: "<authtoken>",

‎__test__/connect.spec.mjs

Lines changed: 17 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -48,10 +48,11 @@ async function validateShutdown(t, httpServer, url, axiosConfig) {
4848

4949
test("connect https", async (t) => {
5050
const httpServer = await makeHttp();
51-
const url = await ngrok.connect({
51+
const listener = await ngrok.connect({
5252
addr: httpServer.listenTo,
5353
authtoken: process.env["NGROK_AUTHTOKEN"],
5454
});
55+
const url = listener.url();
5556

5657
t.truthy(url);
5758
t.truthy(url.startsWith("https://"), url);
@@ -61,7 +62,8 @@ test("connect https", async (t) => {
6162
test("connect number", async (t) => {
6263
const httpServer = await makeHttp();
6364
ngrok.authtoken(process.env["NGROK_AUTHTOKEN"]);
64-
const url = await ngrok.connect(parseInt(httpServer.listenTo.split(":")[1], 10));
65+
const listener = await ngrok.connect(parseInt(httpServer.listenTo.split(":")[1], 10));
66+
const url = listener.url();
6567

6668
t.truthy(url);
6769
t.truthy(url.startsWith("https://"), url);
@@ -72,7 +74,8 @@ test("connect port string", async (t) => {
7274
ngrok.consoleLog();
7375
const httpServer = await makeHttp();
7476
ngrok.authtoken(process.env["NGROK_AUTHTOKEN"]);
75-
const url = await ngrok.connect(httpServer.listenTo.split(":")[1]);
77+
const listener = await ngrok.connect(httpServer.listenTo.split(":")[1]);
78+
const url = listener.url();
7679

7780
t.truthy(url);
7881
t.truthy(url.startsWith("https://"), url);
@@ -83,7 +86,8 @@ test("connect addr port string", async (t) => {
8386
ngrok.consoleLog();
8487
const httpServer = await makeHttp();
8588
ngrok.authtoken(process.env["NGROK_AUTHTOKEN"]);
86-
const url = await ngrok.connect({ addr: httpServer.listenTo.split(":")[1] });
89+
const listener = await ngrok.connect({ addr: httpServer.listenTo.split(":")[1] });
90+
const url = listener.url();
8791

8892
t.truthy(url);
8993
t.truthy(url.startsWith("https://"), url);
@@ -93,7 +97,8 @@ test("connect addr port string", async (t) => {
9397
test("connect string", async (t) => {
9498
const httpServer = await makeHttp();
9599
ngrok.authtoken(process.env["NGROK_AUTHTOKEN"]);
96-
const url = await ngrok.connect(httpServer.listenTo);
100+
const listener = await ngrok.connect(httpServer.listenTo);
101+
const url = listener.url();
97102

98103
t.truthy(url);
99104
t.truthy(url.startsWith("https://"), url);
@@ -102,7 +107,7 @@ test("connect string", async (t) => {
102107

103108
test("connect vectorize", async (t) => {
104109
const httpServer = await makeHttp();
105-
const url = await ngrok.connect({
110+
const listener = await ngrok.connect({
106111
// numeric port
107112
addr: parseInt(httpServer.listenTo.split(":")[1], 10),
108113
authtoken: process.env["NGROK_AUTHTOKEN"],
@@ -129,6 +134,7 @@ test("connect vectorize", async (t) => {
129134
response_header_add: "X-Res-Yup2:true2",
130135
schemes: "HTTPS",
131136
});
137+
const url = listener.url();
132138

133139
t.truthy(url);
134140
t.truthy(url.startsWith("https://"), url);
@@ -141,22 +147,22 @@ test("connect vectorize", async (t) => {
141147

142148
test("connect tcp listener", async (t) => {
143149
const httpServer = await makeHttp();
144-
const url = await ngrok.connect({
150+
const listener = await ngrok.connect({
145151
addr: httpServer.listenTo,
146152
authtoken_from_env: true,
147153
proto: "tcp",
148154
forwards_to: "tcp forwards to",
149155
metadata: "tcp metadata",
150156
});
151157

152-
t.truthy(url);
158+
t.truthy(listener);
153159

154-
await validateShutdown(t, httpServer, url.replace("tcp:", "http:"));
160+
await validateShutdown(t, httpServer, listener.url().replace("tcp:", "http:"));
155161
});
156162

157163
test("connect tls listener", async (t) => {
158164
const httpServer = await makeHttp();
159-
const url = await ngrok.connect({
165+
const listener = await ngrok.connect({
160166
addr: httpServer.listenTo,
161167
authtoken_from_env: true,
162168
proto: "tls",
@@ -165,6 +171,7 @@ test("connect tls listener", async (t) => {
165171
crt: fs.readFileSync("examples/domain.crt", "utf8"),
166172
key: fs.readFileSync("examples/domain.key", "utf8"),
167173
});
174+
const url = listener.url();
168175

169176
t.truthy(url);
170177

‎examples/ngrok-connect-full.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ const ngrok = require("@ngrok/ngrok");
2020
ngrok.consoleLog("INFO"); // turn on info logging
2121

2222
(async function () {
23-
const url = await ngrok.connect({
23+
const listener = await ngrok.connect({
2424
// session configuration
2525
addr: `unix:${UNIX_SOCKET}`,
2626
// addr: `localhost:8080`,
@@ -63,5 +63,5 @@ ngrok.consoleLog("INFO"); // turn on info logging
6363
// verify_webhook_secret: "asdf",
6464
// websocket_tcp_converter: true,
6565
});
66-
console.log(`Ingress established at: ${url}`);
66+
console.log(`Ingress established at: ${listener.url()}`);
6767
})();

‎examples/ngrok-connect-minimal.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,6 @@ console.log(`Node.js web server at 8080 is running..`);
1212
// setup ngrok
1313
const ngrok = require("@ngrok/ngrok");
1414
(async function () {
15-
const url = await ngrok.connect({ addr: 8080, authtoken_from_env: true });
16-
console.log(`Ingress established at: ${url}`);
15+
const listener = await ngrok.connect({ addr: 8080, authtoken_from_env: true });
16+
console.log(`Ingress established at: ${listener.url()}`);
1717
})();

‎src/connect.rs

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,11 @@ use tracing::warn;
99

1010
use crate::{
1111
config::Config,
12-
listener,
13-
listener::TCP_PREFIX,
12+
listener::{
13+
self,
14+
Listener,
15+
TCP_PREFIX,
16+
},
1417
logging::logging_callback,
1518
napi_err,
1619
session::{
@@ -129,7 +132,7 @@ pub fn connect(
129132
}
130133

131134
/// Connect the session, configure and start the listener
132-
async fn async_connect(s_builder: SessionBuilder, config: Config) -> Result<String> {
135+
async fn async_connect(s_builder: SessionBuilder, config: Config) -> Result<Listener> {
133136
// Using a singleton session for connect use cases
134137
let mut opt = SESSION.lock().await;
135138
if opt.is_none() {
@@ -147,17 +150,16 @@ async fn async_connect(s_builder: SessionBuilder, config: Config) -> Result<Stri
147150
_ => return Err(napi_err(format!("unhandled protocol {proto}"))),
148151
};
149152

150-
let url = listener::get_listener(id.clone())
153+
let listener = listener::get_listener(id.clone())
151154
.await
152-
.and_then(|t| t.url())
153-
.unwrap_or(id.clone());
155+
.ok_or(napi_err("failed to start listener".to_string()))?;
154156

155157
// move forwarding to another task
156158
if let Some(addr) = config.addr {
157159
tokio::spawn(async move { listener::forward(&id, addr).await });
158160
}
159161

160-
Ok(url)
162+
Ok(listener)
161163
}
162164

163165
/// HTTP Listener configuration

0 commit comments

Comments
 (0)