@automattic/vip 4.1.5 → 4.1.6

package/node_modules/lando/plugins/lando-core/lib/utils.js

@@ -6,13 +6,20 @@ const chalk = require('chalk');
 const path = require('path');
 const url = require('url');
 
-/*
- * Helper method to get the host part of a volume
+/**
+ * Extracts the host-side path from a compose volume declaration.
+ * @param {string} mount Compose volume declaration.
+ * @returns {string} Host-side path.
  */
 exports.getHostPath = mount => _.dropRight(mount.split(':')).join(':');
 
-/*
- * Takes inspect data and extracts all the exposed ports
+/**
+ * Builds localhost URLs from docker inspect port metadata.
+ * @param {object} data Docker inspect payload.
+ * @param {string[]} [scan] Ports that should be exposed in app info.
+ * @param {string[]} [secured] Ports that should use https.
+ * @param {string} [bindAddress] Expected host bind address.
+ * @returns {object} Service name with its resolved URLs.
  */
 exports.getUrls = (data, scan = ['80, 443'], secured = ['443'], bindAddress = '127.0.0.1') => {
   return _(_.merge(_.get(data, 'Config.ExposedPorts', []), {'443/tcp': {}}))
@@ -32,9 +39,12 @@ exports.getUrls = (data, scan = ['80, 443'], secured = ['443'], bindAddress = '1
       .value();
 };
 
-/*
- * Helper method to normalize a path so that Lando overrides can be used as though
- * the docker-compose files were in the app root.
+/**
+ * Normalizes override paths as if docker compose files lived at the app root.
+ * @param {string} local Relative or absolute path.
+ * @param {string} [base] Base directory for relative paths.
+ * @param {string[]} [excludes] Paths that should be left untouched.
+ * @returns {string} Normalized path.
  */
 exports.normalizePath = (local, base = '.', excludes = []) => {
   // Return local if it starts with $ or ~
@@ -47,8 +57,12 @@ exports.normalizePath = (local, base = '.', excludes = []) => {
   return path.resolve(path.join(base, local));
 };
 
-/*
- * Helper to normalize overrides
+/**
+ * Normalizes build and volume paths inside a compose override block.
+ * @param {object} overrides Compose overrides.
+ * @param {string} [base] Base directory for relative paths.
+ * @param {object} [volumes] Named volumes that should not be rewritten.
+ * @returns {object} Mutated override object.
  */
 exports.normalizeOverrides = (overrides, base = '.', volumes = {}) => {
   // Normalize any build paths
@@ -77,8 +91,10 @@ exports.normalizeOverrides = (overrides, base = '.', volumes = {}) => {
   return overrides;
 };
 
-/*
- * Returns a CLI table with app start metadata info
+/**
+ * Builds CLI table data for app start output.
+ * @param {import('../../../lib/app')} app App metadata.
+ * @returns {object} CLI table rows.
  */
 exports.startTable = app => {
   const data = {
@@ -110,13 +126,17 @@ exports.startTable = app => {
   return data;
 };
 
-/*
- * Helper to strip the patch version
+/**
+ * Drops the patch segment from a semantic version string.
+ * @param {string} version Semantic version string.
+ * @returns {string} Major and minor version.
  */
 exports.stripPatch = version => _.slice(version.split('.'), 0, 2).join('.');
 
-/*
- * Helper to help us allow wildcard patch versions eg when there is no minor version tag available
+/**
+ * Converts wildcard patch versions into major-minor versions.
+ * @param {string[]} versions Version strings to normalize.
+ * @returns {string[]} Normalized version strings.
  */
 exports.stripWild = versions => _(versions)
     .map(version => (version.split('.')[2] === 'x') ? _.slice(version.split('.'), 0, 2).join('.') : version)

package/node_modules/lando/plugins/lando-core/lib/warnings.js

@@ -3,6 +3,10 @@
 // Modules
 const _ = require('lodash');
 
+/**
+ * Builds the warning shown when too many SSH keys are detected.
+ * @returns {object} Warning payload.
+ */
 exports.maxKeyWarning = () => ({
   title: 'You have a lot of keys!',
   detail: [
@@ -13,6 +17,10 @@ exports.maxKeyWarning = () => ({
   url: 'https://docs.lando.dev/config/ssh.html#customizing',
 });
 
+/**
+ * Builds the warning shown when an app was built with a different Lando version.
+ * @returns {object} Warning payload.
+ */
 exports.rebuildWarning = () => ({
   title: 'This app was built on a different version of Lando.',
   detail: [
@@ -23,18 +31,37 @@ exports.rebuildWarning = () => ({
   command: 'lando rebuild',
 });
 
+/**
+ * Builds the warning shown when a service is not running.
+ * @param {string} service Service name.
+ * @returns {object} Warning payload.
+ */
 exports.serviceNotRunningWarning = service => ({
   title: `The service "${service}" is not running!`,
   detail: ['This is likely a critical problem and we recommend you run the command below to investigate'],
   command: `lando logs -s ${service}`,
 });
 
+/**
+ * Builds the warning shown when a service healthcheck fails.
+ * @param {string} service Service name.
+ * @returns {object} Warning payload.
+ */
 exports.serviceUnhealthyWarning = service => ({
   title: `The service "${service}" failed its healthcheck`,
   detail: ['This may be ok but we recommend you run the command below to investigate:'],
   command: `lando logs -s ${service}`,
 });
 
+/**
+ * Builds the warning shown when Docker is outside the supported version range.
+ * @param {object} warning Warning context.
+ * @param {string} warning.name Docker dependency name.
+ * @param {string} warning.version Detected version.
+ * @param {string} warning.wants Supported semver range.
+ * @param {string} warning.link Help URL.
+ * @returns {object} Warning payload.
+ */
 exports.unsupportedVersionWarning = ({name, version, wants, link}) => ({
   title: `Using an unsupported version of DOCKER ${_.upperCase(name)}`,
   detail: [

package/node_modules/lando/plugins/lando-core/tasks/destroy.js

@@ -5,7 +5,7 @@ module.exports = lando => {
     command: 'destroy',
     describe: 'Destroys your app',
     options: {
-      yes: lando.cli.confirm('Are you sure you want to DESTROY?'),
+      yes: lando.cli.confirm(),
     },
     run: options => {
       // Stop rebuild if user decides its a nogo

package/node_modules/lando/plugins/lando-core/tasks/rebuild.js

@@ -13,7 +13,7 @@ module.exports = lando => {
         alias: ['s'],
         array: true,
       },
-      yes: lando.cli.confirm('Are you sure you want to rebuild?'),
+      yes: lando.cli.confirm(),
     },
     run: options => {
       if (!options.yes) {

package/node_modules/lando/plugins/lando-events/index.js

@@ -1,3 +1,7 @@
 'use strict';
 
+/**
+ * Placeholder initializer for the events plugin.
+ * @param {object} lando Lando runtime instance.
+ */
 module.exports = lando => {};

package/node_modules/lando/plugins/lando-events/lib/utils.js

@@ -4,7 +4,11 @@
 const _ = require('lodash');
 const getUser = require('./../../../lib/utils').getUser;
 
-// Helper to find the default service
+/**
+ * Resolves the default service name for an event command.
+ * @param {object} data Event command metadata.
+ * @returns {string} Service name.
+ */
 const getDefaultService = data => {
   if (_.has(data, 'service')) {
     if (_.startsWith(data.service, ':')) {
@@ -18,19 +22,36 @@ const getDefaultService = data => {
   }
 };
 
-// Helper to find a command
+/**
+ * Extracts the command string or argv from an event command definition.
+ * @param {string|object} cmd Event command definition.
+ * @returns {string|string[]} Command payload.
+ */
 const getCommand = cmd => typeof cmd === 'object' ? cmd[getFirstKey(cmd)] : cmd;
 
-// Key find helper
+/**
+ * Returns the first key from an object.
+ * @param {object} obj Object to inspect.
+ * @returns {string|undefined} First key.
+ */
 const getFirstKey = obj => _.first(_.keys(obj));
 
-// Helper to find a service
+/**
+ * Resolves the target service for an event command.
+ * @param {string|object} cmd Event command definition.
+ * @param {object} [data] Event command metadata.
+ * @returns {string} Service name.
+ */
 const getService = (cmd, data = {}) => {
   return typeof cmd === 'object' ? getFirstKey(cmd) : getDefaultService(data);
 };
 
-/*
- * Translate events into run objects
+/**
+ * Translates event command definitions into engine run tasks.
+ * @param {Array<string|object>} cmds Event command definitions.
+ * @param {import('../../../lib/app')} app App instance.
+ * @param {object} [data] Event command metadata.
+ * @returns {object[]} Engine run tasks.
  */
 exports.events2Runz = (cmds, app, data = {}) => _.map(cmds, cmd => {
   // Discover the service

package/node_modules/lando/plugins/lando-networking/app.js

@@ -25,8 +25,8 @@ module.exports = (app, lando) => {
                 if (!_.includes(error.message, 'is not connected to network lando')) throw error;
               })
           // Connect
+              .then(() => landonet.connect({Container: container.id, EndpointConfig: {Aliases: [internalAlias]}}))
               .then(() => {
-                landonet.connect({Container: container.id, EndpointConfig: {Aliases: [internalAlias]}});
                 app.log.debug('connected %s to the landonet', container.name);
               });
         });
@@ -70,8 +70,8 @@ module.exports = (app, lando) => {
               if (!_.includes(error.message, 'is not connected to network lando')) throw error;
             })
         // Connect
+            .then(() => bridgeNet.connect({Container: proxyContainer, EndpointConfig: {Aliases: aliases}}))
             .then(() => {
-              bridgeNet.connect({Container: proxyContainer, EndpointConfig: {Aliases: aliases}});
               app.log.debug('aliased %j to the proxynet', aliases);
             });
       });

package/node_modules/lando/plugins/lando-networking/index.js

@@ -3,8 +3,10 @@
 // Modules
 const _ = require('lodash');
 
-/*
- * Helper to clean out any old networks when we hit the limit
+/**
+ * Prunes unused Docker networks when the daemon reaches Docker's network limit.
+ * @param {object} lando Lando runtime instance.
+ * @returns {Promise|undefined} Promise for cleanup work when pruning is needed.
  */
 const cleanNetworks = lando => lando.engine.getNetworks()
     .then(networks => {
@@ -42,6 +44,11 @@ const cleanNetworks = lando => lando.engine.getNetworks()
       }
     });
 
+/**
+ * Registers networking lifecycle hooks and default config.
+ * @param {object} lando Lando runtime instance.
+ * @returns {object} Plugin config contribution.
+ */
 module.exports = lando => {
   // Preemptively make sure we have enough networks and if we don't smartly prune some of them
   lando.events.on('pre-engine-start', 1, () => cleanNetworks(lando));

package/node_modules/lando/plugins/lando-networking/test/app.spec.js

@@ -0,0 +1,87 @@
+/**
+ * Tests for network attachment during startup.
+ * @file app.spec.js
+ */
+
+'use strict';
+
+const {expect} = require('chai');
+const sinon = require('sinon');
+const Bluebird = require('../../../lib/promise');
+const networking = require('../app');
+
+describe('networking startup', () => {
+  ['app containers', 'proxy aliases'].forEach((target, index) => {
+    describe(target, () => {
+      let hook;
+      let resolveConnection;
+      let rejectConnection;
+      let connectionStarted;
+      let debug;
+
+      beforeEach(() => {
+        const hooks = [];
+        const connection = new Bluebird((resolve, reject) => {
+          resolveConnection = resolve;
+          rejectConnection = reject;
+        });
+        let markStarted;
+        connectionStarted = new Bluebird(resolve => {
+          markStarted = resolve;
+        });
+        const network = {
+          disconnect: sinon.stub().returns(Bluebird.resolve()),
+          connect: () => {
+            markStarted();
+            return connection;
+          },
+        };
+        debug = sinon.spy();
+        networking({
+          events: {on: (name, priority, handler) => {
+            if (name === 'post-start') hooks.push(handler);
+          }},
+          project: 'example',
+          config: {proxy: {appserver: ['example.lndo.site']}},
+          log: {debug},
+        }, {
+          Promise: Bluebird,
+          config: {networkBridge: 'lando', proxy: 'ON', proxyContainer: 'proxy'},
+          engine: {
+            getNetwork: () => network,
+            list: () => Bluebird.resolve([{id: 'appserver', service: 'appserver', app: 'example'}]),
+            exists: () => Bluebird.resolve(true),
+            scan: () => Bluebird.resolve({}),
+          },
+        });
+        hook = hooks[index];
+      });
+
+      it('should wait for attachment before completing startup and logging success', async () => {
+        let completed = false;
+        const startup = hook().then(() => {
+          completed = true;
+        });
+        await connectionStarted;
+        await Bluebird.delay(20);
+        expect(completed).to.equal(false);
+        expect(debug.called).to.equal(false);
+        resolveConnection();
+        await startup;
+        expect(completed).to.equal(true);
+        expect(debug.calledOnce).to.equal(true);
+      });
+
+      it('should propagate attachment failures instead of reporting success', async () => {
+        const failure = new Error('network attachment failed');
+        const startup = hook().reflect();
+        await connectionStarted;
+        rejectConnection(failure);
+        const result = await startup;
+        expect(result.isRejected()).to.equal(true);
+        expect(result.reason()).to.equal(failure);
+        expect(debug.called).to.equal(false);
+      });
+    });
+  });
+});

package/node_modules/lando/plugins/lando-proxy/index.js

@@ -6,6 +6,7 @@ const path = require('path');
 const utils = require('./lib/utils');
 
 // Default config values
+/** @type {object} */
 const defaultConfig = {
   proxy: 'ON',
   proxyName: 'landoproxyhyperion5000gandalfedition',
@@ -32,7 +33,11 @@ const defaultConfig = {
   proxyPassThru: true,
 };
 
-
+/**
+ * Registers proxy bootstrap hooks and default config.
+ * @param {object} lando Lando runtime instance.
+ * @returns {object} Plugin config contribution.
+ */
 module.exports = lando => {
   // Add in some computed config eg things after our config has been settled
   lando.events.on('post-bootstrap-config', ({config}) => {

package/node_modules/lando/plugins/lando-proxy/lib/utils.js

@@ -8,8 +8,12 @@ const url = require('url');
 // eslint-disable-next-line no-redeclare
 const Promise = require('../../../lib/promise');
 
-/*
- * Helper to get URLs for app info and scanning purposes
+/**
+ * Expands a proxy URL into the HTTP and optional HTTPS app-info URLs.
+ * @param {object} url Parsed URL data.
+ * @param {object} ports HTTP and HTTPS port mapping.
+ * @param {boolean} [hasCerts] Whether HTTPS URLs should be emitted.
+ * @returns {string[]} URLs for app info and scanning.
  */
 const getInfoUrls = (url, ports, hasCerts = false) => {
   // Start with the default
@@ -28,9 +32,8 @@ const getInfoUrls = (url, ports, hasCerts = false) => {
  * It will use the first port with `status === false` for the proxy. However, if looking for an available port,
  * the status of `false` will mean that we failed to connect to it, but that does not mean we can listen on it (e.g., because of ETIMEDOUT).
  * That is why we have to invert the meaning of the status.
- *
  * @param {string[]} urls An array of URLs to scan for unavailable ports.
- * @return {Promise<Array>} An array of objects of the form {url: url, status: boolean}. If `status === true`, the port is available.
+ * @returns {Promise<object[]>} Objects of the form {url, status}; `status === true` means the port is available.
  */
 exports.findUnavailablePorts = urls => {
   return Promise.map(urls, (url => {
@@ -71,16 +74,23 @@ exports.findUnavailablePorts = urls => {
   }));
 };
 
-/*
- * Reduces urls to first open port
+/**
+ * Resolves the first unavailable port reported by the scanner.
+ * @param {function(string[], object): Promise} scanner Port scanner.
+ * @param {string[]} [urls] URLs to inspect.
+ * @returns {Promise} Promise resolving to the first matching port.
  */
 exports.getFirstOpenPort = (scanner, urls = []) => scanner(urls, {max: 1, waitCodes: []})
     .filter(url => url.status === false)
     .map(port => _.last(port.url.split(':')))
     .then(ports => ports[0]);
 
-/*
- * Helper to determine what ports have changed
+/**
+ * Computes which proxy protocols still need rescanning.
+ * @param {object} current Current port mapping.
+ * @param {object} last Previous port mapping.
+ * @param {{http: boolean, https: boolean}} [status] Existing scan status.
+ * @returns {{http: boolean, https: boolean}} Updated scan status.
  */
 exports.needsProtocolScan = (current, last, status = {http: true, https: true}) => {
   if (!last) return status;
@@ -89,8 +99,11 @@ exports.needsProtocolScan = (current, last, status = {http: true, https: true})
   return status;
 };
 
-/*
- * Helper to get proxy runner
+/**
+ * Builds compose runner data for the proxy service.
+ * @param {string} project Compose project name.
+ * @param {string[]} files Compose files.
+ * @returns {object} Engine run descriptor.
  */
 exports.getProxyRunner = (project, files) => ({
   compose: files,
@@ -101,8 +114,10 @@ exports.getProxyRunner = (project, files) => ({
   },
 });
 
-/*
- * Helper to get the trafix rule
+/**
+ * Builds a Traefik routing rule from parsed URL data.
+ * @param {object} rule Parsed proxy rule.
+ * @returns {string} Traefik rule expression.
  */
 exports.getRule = rule => {
   // Start with the rule we can assume
@@ -113,8 +128,10 @@ exports.getRule = rule => {
   return rules.join(' && ');
 };
 
-/*
- * Get a list of URLs and their counts
+/**
+ * Counts duplicate host, path, and port combinations across proxy config.
+ * @param {object} config Proxy config keyed by service.
+ * @returns {object} Counts keyed by host, path, and port.
  */
 exports.getUrlsCounts = config => _(config)
     .flatMap(service => service)
@@ -123,16 +140,22 @@ exports.getUrlsCounts = config => _(config)
     .countBy()
     .value();
 
-/*
- * Parse config into urls we can merge to app.info
+/**
+ * Expands proxied URLs into app-info URLs.
+ * @param {string[]} urls Proxy URLs.
+ * @param {object} ports HTTP and HTTPS port mapping.
+ * @param {boolean} [hasCerts] Whether HTTPS URLs should be emitted.
+ * @returns {string[]} App-info URLs.
  */
 exports.parse2Info = (urls, ports, hasCerts = false) => _(urls)
     .map(url => exports.parseUrl(url))
     .flatMap(url => getInfoUrls(url, ports, hasCerts))
     .value();
 
-/*
- * Parse urls into SANS
+/**
+ * Builds SAN entries for all proxied hosts.
+ * @param {string[]} urls Proxy URLs.
+ * @returns {string} SAN entries separated by newlines.
  */
 exports.parse2Sans = urls => _(urls)
     .map(url => exports.parseUrl(url).host)
@@ -140,8 +163,11 @@ exports.parse2Sans = urls => _(urls)
     .value()
     .join('\n');
 
-/*
- * Parse hosts for traefik
+/**
+ * Builds per-service proxy config for Traefik.
+ * @param {object} config Proxy config keyed by service.
+ * @param {string[]} [sslReady] Services that can terminate TLS.
+ * @returns {object[]} Proxy config fragments.
  */
 exports.parseConfig = (config, sslReady = []) => _(config)
     .map((urls, service) => ({
@@ -152,8 +178,13 @@ exports.parseConfig = (config, sslReady = []) => _(config)
       labels: exports.parseRoutes(service, urls, sslReady)}))
     .value();
 
-/*
- * Helper to parse the routes
+/**
+ * Converts service URLs into Traefik labels.
+ * @param {string} service Service name.
+ * @param {string[]} [urls] Service URLs.
+ * @param {string[]} sslReady Services that can terminate TLS.
+ * @param {object} [labels] Existing labels.
+ * @returns {object} Traefik labels.
  */
 exports.parseRoutes = (service, urls = [], sslReady, labels = {}) => {
   // Prepare our URLs for traefik
@@ -207,10 +238,10 @@ exports.parseRoutes = (service, urls = [], sslReady, labels = {}) => {
   });
   return labels;
 };
-
-
-/*
- * Helper to parse a url
+/**
+ * Parses proxy URL input and applies Lando defaults.
+ * @param {string|object} data Proxy URL input.
+ * @returns {object} Parsed URL config with defaults applied.
  */
 exports.parseUrl = data => {
   // We add the protocol ourselves, so it can be parsed. We also change all *
@@ -228,8 +259,12 @@ exports.parseUrl = data => {
   return _.merge(defaults, parsedUrl, {host: parsedUrl.hostname.replace(/__wildcard__/g, '*')});
 };
 
-/*
- * Maps ports to urls
+/**
+ * Maps local ports to HTTP or HTTPS URLs.
+ * @param {Array<string|number>} ports Ports to map.
+ * @param {boolean} [secure] Whether to emit https URLs.
+ * @param {string} [hostname] Hostname to use in generated URLs.
+ * @returns {string[]} Generated URLs.
  */
 exports.ports2Urls = (ports, secure = false, hostname = '127.0.0.1') => _(ports)
     .map(port => url.format({protocol: (secure) ? 'https' : 'http', hostname, port}))

package/node_modules/lando/plugins/lando-proxy/lib/warnings.js

@@ -1,5 +1,10 @@
 'use strict';
 
+/**
+ * Builds the warning shown when the proxy cannot start.
+ * @param {string} message Failure detail.
+ * @returns {object} Warning payload.
+ */
 exports.cannotStartProxyWarning = message => ({
   title: 'Lando was not able to start the proxy',
   detail: [
@@ -10,6 +15,11 @@ exports.cannotStartProxyWarning = message => ({
   url: 'https://docs.lando.dev/config/proxy.html',
 });
 
+/**
+ * Builds the warning shown when a proxy route targets an unknown service.
+ * @param {string} service Service name.
+ * @returns {object} Warning payload.
+ */
 exports.unknownServiceWarning = service => ({
   title: `Proxying to unknown service "${service}"!`,
   detail: [

package/node_modules/lando/plugins/lando-recipes/index.js

@@ -1,3 +1,7 @@
 'use strict';
 
+/**
+ * Placeholder initializer for the recipes plugin.
+ * @param {object} lando Lando runtime instance.
+ */
 module.exports = lando => {};

package/node_modules/lando/plugins/lando-recipes/lib/build.js

@@ -5,7 +5,11 @@ const _ = require('lodash');
 const path = require('path');
 const utils = require('./../../../lib/utils');
 
-// Helper to kill a run
+/**
+ * Builds a purge run descriptor used to clean up failed init containers.
+ * @param {object} config Engine run descriptor.
+ * @returns {object} Purge run descriptor.
+ */
 const killRun = config => ({
   id: config.id,
   compose: config.compose,
@@ -16,7 +20,11 @@ const killRun = config => ({
   },
 });
 
-// Helper to get a build array of run thingz
+/**
+ * Builds the engine run descriptor for recipe initialization.
+ * @param {object} config Run defaults and command metadata.
+ * @returns {object} Engine run descriptor.
+ */
 exports.buildRun = config => ({
   id: config.id,
   compose: config.compose,
@@ -30,14 +38,24 @@ exports.buildRun = config => ({
   },
 });
 
-// Helper to run
+/**
+ * Runs recipe initialization and cleans up failed init containers.
+ * @param {import('../../../lib/lando')} lando Lando runtime instance.
+ * @param {object} run Engine run descriptor.
+ * @returns {Promise} Promise for the recipe init workflow.
+ */
 exports.run = (lando, run) => lando.engine.run(run).catch(err => {
   return lando.engine.stop(killRun(run))
       .then(() => lando.engine.destroy(killRun(run)))
       .then(() => lando.Promise.reject(err));
 });
 
-// Helper to get run defaults
+/**
+ * Builds default run settings for recipe initialization.
+ * @param {import('../../../lib/lando')} lando Lando runtime instance.
+ * @param {object} options Init command options.
+ * @returns {object} Default run descriptor.
+ */
 exports.runDefaults = (lando, options) => {
   // Handle all the compose stuff
   const LandoInit = lando.factory.get('_init');