feat(twilio-run:start): options for ngrok config and named tunnel

Author: philnash

packages/twilio-run/README.md

@@ -152,8 +152,8 @@ twilio-run --inspect
 # Exposes the Twilio functions via ngrok to share them
 twilio-run --ngrok
 
-# Exposes the Twilio functions via ngrok using a custom subdomain (requires a paid-for ngrok account)
-twilio-run --ngrok=subdomain
+# Uses a custom project ngrok config and named tunnel to expose the functions via ngrok
+twilio-run --ngrok --ngrok-config=./ngrok.yml --ngrok-name=example
 ```
 
 ### `twilio-run deploy`

packages/twilio-run/package.json

@@ -73,6 +73,7 @@
     "type-fest": "^0.15.1",
     "window-size": "^1.1.1",
     "wrap-ansi": "^5.1.0",
+    "yaml": "^1.10.0",
     "yargs": "^13.2.2"
   },
   "optionalDependencies": {

packages/twilio-run/src/commands/start.ts

@@ -159,6 +159,14 @@ export const cliInfo: CliInfo = {
       describe:
         'Uses ngrok to create a public url. Pass a string to set the subdomain (requires a paid-for ngrok account).',
     },
+    'ngrok-config': {
+      type: 'string',
+      describe: 'Path to custom ngrok config for project specific config.',
+    },
+    'ngrok-name': {
+      type: 'string',
+      describe: 'Name of ngrok tunnel config.',
+    },
     logs: {
       type: 'boolean',
       default: true,

packages/twilio-run/src/config/start.ts

@@ -1,23 +1,21 @@
 import { EnvironmentVariables } from '@twilio-labs/serverless-api';
 import dotenv from 'dotenv';
 import { readFileSync } from 'fs';
-import path, { resolve } from 'path';
-import { Arguments } from 'yargs';
+import path, { resolve, join } from 'path';
+import { homedir } from 'os';
+import { Arguments, config } from 'yargs';
 import { ExternalCliOptions, SharedFlags } from '../commands/shared';
 import { CliInfo } from '../commands/types';
 import { EnvironmentVariablesWithAuth } from '../types/generic';
 import { fileExists } from '../utils/fs';
 import { getDebugFunction, logger } from '../utils/logger';
 import { readSpecializedConfig } from './global';
 import { mergeFlagsAndConfig } from './utils/mergeFlagsAndConfig';
+import { INgrokOptions } from 'ngrok';
+import { parse } from 'yaml';
 
 const debug = getDebugFunction('twilio-run:cli:config');
 
-type NgrokConfig = {
-  addr: string | number;
-  subdomain?: string;
-};
-
 type InspectInfo = {
   hostPort: string;
   break: boolean;
@@ -47,6 +45,8 @@ export type StartCliFlags = Arguments<
     env?: string;
     port: string;
     ngrok?: string | boolean;
+    ngrokConfig?: string;
+    ngrokName?: string;
     logs: boolean;
     detailedLogs: boolean;
     live: boolean;
@@ -67,12 +67,73 @@ export async function getUrl(cli: StartCliFlags, port: string | number) {
   let url = `http://localhost:${port}`;
   if (typeof cli.ngrok !== 'undefined') {
     debug('Starting ngrok tunnel');
-    const ngrokConfig: NgrokConfig = { addr: port };
+    // Setup default ngrok config, setting the protocol and the port number to
+    // forward to.
+    const defaultConfig: INgrokOptions = { addr: port, proto: 'http' };
+    let tunnelConfig = defaultConfig;
+    let ngrokConfig;
+    if (typeof cli.ngrokConfig === 'string') {
+      // If we set a config path then try to load that config. If the config
+      // fails to load then we'll try to load the default config instead.
+      const configPath = join(process.cwd(), cli.ngrokConfig);
+      try {
+        ngrokConfig = parse(readFileSync(configPath, 'utf-8'));
+      } catch (err) {
+        logger.warn(`Could not find ngrok config file at ${configPath}`);
+      }
+    }
+    if (!ngrokConfig) {
+      // Try to load default config. If there is no default config file, set
+      // `ngrokConfig` to be an empty object.
+      const configPath = join(homedir(), '.ngrok2', 'ngrok.yml');
+      try {
+        ngrokConfig = parse(readFileSync(configPath, 'utf-8'));
+      } catch (err) {
+        ngrokConfig = {};
+      }
+    }
+    if (
+      typeof cli.ngrokName === 'string' &&
+      typeof ngrokConfig.tunnels === 'object'
+    ) {
+      // If we've asked for a named ngrok tunnel and there are available tunnels
+      // in the config, then set the `tunnelConfig` to the options from the
+      // config, overriding the addr and proto to the defaults.
+      tunnelConfig = { ...ngrokConfig.tunnels[cli.ngrokName], ...tunnelConfig };
+      if (!tunnelConfig) {
+        // If the config does not include the named tunnel, then set it back to
+        // the default options.
+        logger.warn(
+          `Could not find config for named tunnel "${cli.ngrokName}". Falling back to other options.`
+        );
+        tunnelConfig = defaultConfig;
+      }
+    }
+    if (typeof ngrokConfig.authtoken === 'string') {
+      // If there is an authtoken in the config, add it to the tunnel config.
+      tunnelConfig.authToken = ngrokConfig.authtoken;
+    }
     if (typeof cli.ngrok === 'string' && cli.ngrok.length > 0) {
-      ngrokConfig.subdomain = cli.ngrok;
+      // If we've asked for a custom subdomain, override the tunnel config with
+      // it.
+      tunnelConfig.subdomain = cli.ngrok;
+    }
+    const ngrok = require('ngrok');
+    try {
+      // Try to open the ngrok tunnel.
+      url = await ngrok.connect(tunnelConfig);
+    } catch (error) {
+      // If it fails, it is likely to be because the tunnel config we pass is
+      // not allowed (e.g. using a custom subdomain without an authtoken). The
+      // error message from ngrok itself should describe the issue.
+      logger.warn(error.message);
+      if (
+        typeof error.details !== 'undefined' &&
+        typeof error.details.err !== 'undefined'
+      ) {
+        logger.warn(error.details.err);
+      }
     }
-
-    url = await require('ngrok').connect(ngrokConfig);
     debug('ngrok tunnel URL: %s', url);
   }