Handle ngrok version 3 (#272)

* git commit -m "Handles ngrok v2 and v3 ways of setting the auth token.

This commit refactors a couple of things too. Mostly it extracts things from the src/process.js file. Neither the version or authtoken commands need the process (they both spawn their own processes briefly), so they had no business colocating.

This allowed the setAuthToken function to break out into a few utility functions and make the function more understandable overall. The new src/version.js didn't change much from when it was in src/process.js, but relocating it did allow for removing some requires at the top of src/process.js

* feat: adds function to upgrade ngrok config for use with ngrok version 3

* Updates to use ngrok client v3.

* Run tests against node 16 and 18

* Updates README. Tries to not run tests twice on a push to a branch with an open PR.

* Just run workflow on push

* Exposes old default config path, tests that an old style config file throws

* Adds test for config upgrade function

* It throws an error, that's what is important

* Drops support for Node less than 14.2

* Removes package-lock.json from the repo

.github/workflows/tests.yml

@@ -1,26 +1,26 @@
 name: Tests
 
-on: [push, pull_request]
+on: push
 
 jobs:
   test:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        node-version: [10.x, 12.x, 14.x]
+        node-version: [14.x, 16.x, 18.x]
       max-parallel: 1
 
     steps:
-    - uses: actions/checkout@v2
-    - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v1
-      with:
-        node-version: ${{ matrix.node-version }}
-    - run: npm install
-    - run: npm test
-      env:
-        CI: true
-        NGROK_AUTHTOKEN_FREE: ${{secrets.NGROK_AUTHTOKEN_FREE}}
-        NGROK_AUTHTOKEN_PAID: ${{secrets.NGROK_AUTHTOKEN_PAID}}
-        NGROK_FORCE_TOKENS: ${{secrets.NGROK_FORCE_TOKENS}}
+      - uses: actions/checkout@v2
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v1
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm install
+      - run: npm test
+        env:
+          CI: true
+          NGROK_AUTHTOKEN_FREE: ${{secrets.NGROK_AUTHTOKEN_FREE}}
+          NGROK_AUTHTOKEN_PAID: ${{secrets.NGROK_AUTHTOKEN_PAID}}
+          NGROK_FORCE_TOKENS: ${{secrets.NGROK_FORCE_TOKENS}}

.gitignore

@@ -2,4 +2,5 @@ node_modules/
 bin/
 bin/**
 bin/ngrok
-*.log
+*.log
+package-lock.json

.mocharc.json

@@ -1,9 +1,9 @@
 {
-  "require": "./test/setup.js",
+  "require": ["./test/setup.js", "./test/configSetup.js"],
   "reporter": "spec",
   "ui": "bdd",
   "recursive": true,
   "colors": true,
   "timeout": 10000,
   "slow": 100
-}
+}

CHANGELOG.md

@@ -6,7 +6,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-...
+### Changed
+
+Updates to ngrok binary version 3. This is a breaking change.
+
+- **[breaking]** Drops support for Node less than version 14.2
+- **[breaking]** download.js now uses URLs that download ngrok version 3
+- **[breaking]** To set basic auth on a tunnel, use the option `basic_auth` instead of `auth` or `httpauth`
+- **[breaking]** The ngrok client API now fails if you send arguments that aren't part of the [available configuration](https://ngrok.com/docs/ngrok-agent/config#config-ngrok-tunnel-definitions). Changed the `defaults` function to return `tunnelOpts` and `globalOpts` from the available options
+- Updates the underlying ngrok client command to set the authtoken
+- Passing an authtoken as a connect option doesn't update the ngrok config file, it just passes it to the command
+- Updates the test setup to use mocha hooks to store/restore config
+- Basic auth password must be at least 8 characters now, updated tests that used a 4 character password
+- The ngrok client tries to guess the closest region, updated the tests to use a consistent region of "us" (the old default)
+- The v3 ngrok client looks for config in its new [default location](https://ngrok.com/docs/ngrok-agent/config#config-ngrok-location), but will fallback to the old location. Updated tests to remove both, to reset the state.
+- Adds a function to [upgrade the config file](https://ngrok.com/docs/guides/upgrade-v2-v3).
 
 ## [4.3.3] - 2022-08-18
 

README.md

@@ -1,5 +1,7 @@
 # ngrok [![Tests](https://github.com/bubenshchykov/ngrok/workflows/Tests/badge.svg)](https://github.com/bubenshchykov/ngrok/actions) ![TypeScript compatible](https://img.shields.io/badge/typescript-compatible-brightgreen.svg) [![npm](https://img.shields.io/npm/v/ngrok.svg)](https://www.npmjs.com/package/ngrok) [![npm](https://img.shields.io/npm/dm/ngrok.svg)](https://www.npmjs.com/package/ngrok)
 
+This project is the Node.js wrapper for the [ngrok client](https://ngrok.com/download). Version 5 of this project uses ngrok client version 3. For ngrok client version 2, check out version 4.
+
 ![alt ngrok.com](https://ngrok.com/static/img/overview.png)
 
 * [Usage](#usage)
@@ -10,6 +12,7 @@
     * [Options](#options)
   * [Disconnect](#disconnect)
   * [Config](#config)
+    * [Updating config for ngrok version 3](#updating-config-for-ngrok-version-3)
   * [Inspector](#inspector)
   * [API](#api)
     * [List tunnels](#list-tunnels)
@@ -25,6 +28,9 @@
 * [ngrok binary update](#ngrok-binary-update)
 * [Using with nodemon](#using-with-nodemon)
 * [Contributors](#contributors)
+* [Upgrading to version 5](#upgrading-to-version-5)
+  * [Config](#config-1)
+  * [Connect options](#connect-options)
 * [Upgrading to version 4](#upgrading-to-version-4)
   * [TypeScript](#typescript)
 
@@ -102,7 +108,7 @@ There are many options that you can pass to `connect`, here are some examples:
 const url = await ngrok.connect({
   proto: 'http', // http|tcp|tls, defaults to http
   addr: 8080, // port or network address, defaults to 80
-  auth: 'user:pwd', // http basic authentication for tunnel
+  basic_auth: 'user:pwd', // http basic authentication for tunnel
   subdomain: 'alex', // reserved tunnel name https://alex.ngrok.io
   authtoken: '12345', // your authtoken from ngrok.com
   region: 'us', // one of ngrok regions (us, eu, au, ap, sa, jp, in), defaults to us
@@ -113,9 +119,12 @@ const url = await ngrok.connect({
 });
 ```
 
-See [the ngrok documentation for all of the tunnel definition options](https://ngrok.com/docs#tunnel-definitions) including: `name, inspect, host_header, bind_tls, hostname, crt, key, client_cas, remote_addr`.
+See [the ngrok documentation for all of the tunnel definition options](https://ngrok.com/docs/ngrok-agent/config#config-ngrok-tunnel-definitions) including: `name, inspect, host_header, scheme, hostname, crt, key, remote_addr`.
+
+Note on regions:
 
-Note on regions: the region used in the first tunnel will be used for all the following tunnels.
+* The region used in the first tunnel will be used for all the following tunnels
+* If you do not provide a region, ngrok will try to pick the closest one to your location. This will include the region in the URL. To get a URL without a region, set the region to "us".
 
 ### Disconnect
 
@@ -127,19 +136,40 @@ await ngrok.disconnect(); // stops all
 await ngrok.kill(); // kills ngrok process
 ```
 
-Note on HTTP tunnels: by default bind_tls is true, so whenever you use HTTP proto two tunnels are created - HTTP and HTTPS. If you disconnect the HTTPS tunnel, the HTTP tunnel remains open. You might want to close them both by passing the HTTP-version url, or simply by disconnecting all in one go `ngrok.disconnect()`.
-
 ### Config
 
 You can use ngrok's [configurations files](https://ngrok.com/docs#config), and pass `name` option when making a tunnel. Configuration files allow to store tunnel options. Ngrok looks for them here:
 
+| System         | Path                                              |
+| -------------- | ------------------------------------------------- |
+| MacOS (Darwin) | `"~/Library/Application Support/ngrok/ngrok.yml"` |
+| Linux          | `"~/.config/ngrok/ngrok.yml"`                     |
+| Windows        | `"%HOMEPATH%\AppData\Local\ngrok\ngrok.yml"`      |
+
+You can specify a custom `configPath` when making a tunnel.
+
+#### Updating config for ngrok version 3
+
+With the upgrade to ngrok version 3, an older config file will no longer be compatible without a few changes. The ngrok agent provides a [command to upgrade your config](https://ngrok.com/docs/ngrok-agent/ngrok#command-ngrok-config-upgrade). On the command line you can run:
+
 ```
-OS X	/Users/example/.ngrok2/ngrok.yml
-Linux	/home/example/.ngrok2/ngrok.yml
-Windows	C:\Users\example\.ngrok2\ngrok.yml
+ngrok config upgrade
 ```
 
-You can specify a custom `configPath` when making a tunnel.
+The default locations of the config file have changed too, you can upgrade and move your config file with the command:
+
+```
+ngrok config upgrade --relocate
+```
+
+The library makes this command available as well. To get the same effect you can run:
+
+```js
+await ngrok.upgradeConfig();
+
+// relocate the config file too:
+await ngrok.upgradeConfig({ relocate: true });
+```
 
 ### Inspector
 
@@ -219,12 +249,12 @@ const request = await api.requestDetail(requestId);
 
 ### Proxy
 
-- If you are behind a corporate proxy and have issues installing ngrok, you can set ```HTTPS_PROXY``` env var to fix it. ngrok's postinstall scripts uses the [`got`](https://www.npmjs.com/package/got) module to fetch the binary and the [`hpagent`](https://github.com/delvedor/hpagent) module to support HTTPS proxies. You will need to install the `hpagent` module as a dependency
+- If you are behind a corporate proxy and have issues installing ngrok, you can set `HTTPS_PROXY` env var to fix it. ngrok's postinstall scripts uses the [`got`](https://www.npmjs.com/package/got) module to fetch the binary and the [`hpagent`](https://github.com/delvedor/hpagent) module to support HTTPS proxies. You will need to install the `hpagent` module as a dependency
 - If you are using a CA file, set the path in the environment variable `NGROK_ROOT_CA_PATH`. The path is needed for downloading the ngrok binary in the postinstall script
 
 ## How it works
 
-```npm install``` downloads the ngrok binary for your platform from the official ngrok hosting. To host binaries yourself set the `NGROK_CDN_URL` environment variable before installing ngrok. To force specific platform set `NGROK_ARCH`, eg `NGROK_ARCH=freebsdia32`.
+`npm install` downloads the ngrok binary for your platform from the official ngrok hosting. To host binaries yourself set the `NGROK_CDN_URL` environment variable before installing ngrok. To force specific platform set `NGROK_ARCH`, eg `NGROK_ARCH=freebsdia32`.
 
 The first time you create a tunnel the ngrok process is spawned and runs until you disconnect or when the parent process is killed. All further tunnels are connected or disconnected through the internal ngrok API which usually runs on http://127.0.0.1:4040.
 
@@ -243,10 +273,24 @@ If you want your application to restart as you make changes to it, you may use [
 
 ## Contributors
 
-Please run ```git update-index --assume-unchanged bin/ngrok``` to not override [ngrok stub](https://github.com/bubenshchykov/ngrok/blob/master/bin/ngrok) in your PR. Unfortunately it can't be gitignored.
+Please run `git update-index --assume-unchanged bin/ngrok` to not override [ngrok stub](https://github.com/bubenshchykov/ngrok/blob/master/bin/ngrok) in your PR. Unfortunately it can't be gitignored.
 
 The test suite covers the basic usage without an authtoken, as well as features available for free and paid authtokens. You can supply your own tokens as environment variables, otherwise a warning is given and some specs are ignored (locally and in PR builds). GitHub Actions supplies real tokens to master branch and runs all specs always.
 
+## Upgrading to version 5
+
+Please read the [upgrade notes for the ngrok agent](https://ngrok.com/docs/guides/upgrade-v2-v3). Library specific changes are described below and there is more in the [CHANGELOG](./CHANGELOG.md):
+
+### Config 
+
+The format and default location of the config file has changed. Please see the section on [upgrading your config file](#updating-config-for-ngrok-version-3) for more detail.
+
+### Connect options
+
+The `bind_tls` option is now `scheme`. When `bind_tls` was true (the default), ngrok agent version 2 would start two tunnels, one on `http` and one on `https`. Now, when `scheme` is set to `https` (the default), only an `https` tunnel will be created. To create both tunnels, you will need to pass `["http", "https"]` as the `scheme` option.
+
+The `auth` option, also available as `httpauth`, is now just `basic_auth`. Note also that the password for `basic_auth` must be between 8 and 128 characters long.
+
 ## Upgrading to version 4
 
 The main impetus to update the package was to remove the dependency on the deprecated `request` module. `request` was replaced with `got`. Calls to the main `ngrok` functions, `connect`, `authtoken`, `disconnect`, `kill`, `getVersion` and `getUrl` respond the same as in version 3.

download.js

@@ -11,8 +11,8 @@ function downloadNgrok(callback, options) {
   const fs = require("fs");
   const path = require("path");
   const readline = require("readline");
-  const extract_zip = require('extract-zip');
-  const got = require("got");
+  const extract_zip = require("extract-zip");
+  const got = require("got").default;
 
   const cafilePath = options.cafilePath || process.env.NGROK_ROOT_CA_PATH;
   const cdnUrl = getCdnUrl();
@@ -35,7 +35,7 @@ function downloadNgrok(callback, options) {
     const cdnPath =
       options.cdnPath ||
       process.env.NGROK_CDN_PATH ||
-      "/c/4VmDzA7iaHb/ngrok-stable-";
+      "/c/bNyj1mQVY4c/ngrok-v3-stable-";
     const cdnFiles = {
       darwinia32: cdn + cdnPath + "darwin-386.zip",
       darwinx64: cdn + cdnPath + "darwin-amd64.zip",
@@ -117,7 +117,7 @@ function downloadNgrok(callback, options) {
       })
       .on("downloadProgress", ({ percent, transferred, total }) => {
         readline.clearLine(process.stderr, 0, () => {
-          readline.cursorTo(process.stderr, 0, () => {
+          readline.cursorTo(process.stderr, 0, null, () => {
             process.stderr.write(
               `ngrok - downloading progress: ${transferred}/${total} (${(
                 percent * 100
@@ -148,16 +148,16 @@ function downloadNgrok(callback, options) {
   function extract(cb) {
     console.error("ngrok - unpacking binary");
     const moduleBinPath = path.join(__dirname, "bin");
-    extract_zip(cacheUrl, { dir: moduleBinPath})
+    extract_zip(cacheUrl, { dir: moduleBinPath })
       .then(() => {
         const suffix = os.platform() === "win32" ? ".exe" : "";
         if (suffix === ".exe") {
           fs.writeFileSync(path.join(moduleBinPath, "ngrok.cmd"), "ngrok.exe");
         }
         const target = path.join(moduleBinPath, "ngrok" + suffix);
-        fs.chmodSync(target, 0755);
+        fs.chmodSync(target, 0o755);
         if (!fs.existsSync(target) || fs.statSync(target).size <= 0) {
-          return error(new Error("corrupted file " + target));
+          return cb(new Error("corrupted file " + target));
         }
         console.log("ngrok - binary unpacked to " + target);
         cb(null);

index.d.ts

@@ -55,16 +55,37 @@ declare module "ngrok" {
    */
   export function authtoken(token: string | Ngrok.Options): Promise<void>;
 
+  /**
+   * Returns the default location of the config file, ngrok.yml
+   * Based on the docs here: https://ngrok.com/docs/ngrok-agent/config#config-ngrok-location
+   */
+  export function defaultConfigPath(): string;
+
+  /**
+   * Returns the old default location of the config file from ngrok v2, which is
+   * still a fallback location that ngrok checks.
+   */
+  export function oldDefaultConfigPath(): string;
+
   /**
    *
    * Gets the version of the ngrok binary.
    */
   export function getVersion(options?: Ngrok.Options): Promise<string>;
 
-  namespace Ngrok {
+  /**
+   *
+   */
+  export function upgradeConfig(options?: {
+    relocate?: boolean;
+    configPath?: string;
+    binPath?: (defaultPath: string) => string;
+  }): Promise<void>;
+
+  export namespace Ngrok {
     // This is a protocol that you can select when starting a tunnel.
     type Protocol = "http" | "tcp" | "tls";
-    // Choosing http will start a tunnel on both http and https. So when the 
+    // Choosing http will start a tunnel on both http and https. So when the
     // tunnels are returned from the API, "https" is a possibility too.
     type TunnelProtocol = "https" | "http" | "tcp" | "tls";
     type Region = "us" | "eu" | "au" | "ap" | "sa" | "jp" | "in";
@@ -137,7 +158,7 @@ declare module "ngrok" {
        */
       onStatusChange?: (status: "connected" | "closed") => any;
 
-       /**
+      /**
        * Callback called when ngrok host process is terminated.
        */
       onTerminated?: () => any;
@@ -236,8 +257,8 @@ declare module "ngrok" {
     error_code: number;
     status_code: number;
     msg: string;
-    details: { [key: string]: string }
-  }
+    details: { [key: string]: string };
+  };
 
   class NgrokClientError extends Error {
     constructor(message: string, response: Response, body: ErrorBody | string);