release v3.24.1 generated by @lando/prepare-release-action

Author: rtfm-47

CHANGELOG.md

@@ -1,5 +1,7 @@
 ## {{ UNRELEASED_VERSION }} - [{{ UNRELEASED_DATE }}]({{ UNRELEASED_LINK }})
 
+## v3.24.1 - [March 3, 2025](https://github.com/lando/core/releases/tag/v3.24.1)
+
 ### Bug Fixes
 
 * Fixed bug causing legacy excluding to fail with `utils.getNamedVolumes is not a function` [#346](https://github.com/lando/core/issues/346)

builders/_lando.js

@@ -1,3 +1,10 @@
+/**
+ * @module builders/_lando
+ * @description Lando service builder for Lando services. This module provides the base
+ * implementation for all Lando services, handling configuration, environment setup,
+ * and container orchestration.
+ */
+
 'use strict';
 
 // Modules
@@ -10,13 +17,68 @@ const write = require('../utils/write-file');
 const {color} = require('listr2');
 const {nanoid} = require('nanoid');
 
-/*
- * The lowest level lando service, this is where a lot of the deep magic lives
+/**
+ * Configuration options for a Lando service.
+ * @typedef {Object} LandoServiceConfig
+ * @property {string} name - Service name
+ * @property {Object} [healthcheck] - Health check configuration
+ * @property {string} type - Service type (e.g., 'apache', 'nginx', 'php')
+ * @property {string} userConfRoot - User config root directory
+ * @property {string} version - Service version
+ * @property {string} [confDest] - Config destination path in container
+ * @property {string} [confSrc] - Config source path on host
+ * @property {Object} [config] - Configuration files mapping (remote path -> local path)
+ * @property {string} [data] - Data directory name for persistent storage
+ * @property {string} [dataHome] - Data home directory name for user data
+ * @property {string} [entrypoint] - Container entrypoint script
+ * @property {string} [home] - Home directory path in container
+ * @property {string[]} [moreHttpPorts] - Additional HTTP ports to expose
+ * @property {Object} [info] - Service information for display
+ * @property {string[]} [legacy] - Legacy versions to warn about
+ * @property {string} [meUser] - Service user inside container
+ * @property {boolean} [patchesSupported] - Whether patch versions are supported
+ * @property {Object} [pinPairs] - Version pinning configuration
+ * @property {string[]} [ports] - Ports to expose
+ * @property {string} [project] - Project name for namespacing
+ * @property {Object} [overrides] - Docker compose overrides
+ * @property {boolean} [refreshCerts] - Whether to refresh SSL certificates
+ * @property {Object} [remoteFiles] - Remote files mapping
+ * @property {string[]} [scripts] - Additional scripts to mount
+ * @property {boolean|string} [scriptsDir] - Scripts directory to mount
+ * @property {string} [sport] - SSL port number
+ * @property {boolean} [ssl] - Whether SSL is enabled
+ * @property {boolean} [sslExpose] - Whether to expose SSL ports
+ * @property {string[]} [supported] - List of supported versions
+ * @property {boolean} [supportedIgnore] - Whether to ignore version support check
+ * @property {string} [root] - Root directory for relative paths
+ */
+
+/**
+ * The lowest level lando service definition.
+ * @typedef {Object} ServiceTypeLando
+ * @property {string} parent - The parent service type to extend from.
+ * @property {(parent: any) => any} builder - Builder function that returns a service class.
+ */
+
+/**
+ * Base Lando service implementation.
+ * @type {ServiceTypeLando}
  */
 module.exports = {
   name: '_lando',
   parent: '_compose',
+  /**
+   * Creates a new LandoLando service class.
+   * @param {any} parent - The parent class to extend from.
+   * @return {any} The LandoLando service class.
+   */
   builder: parent => class LandoLando extends parent {
+    /**
+     * Creates a new LandoLando service instance.
+     * @param {string} id - The unique identifier for the service.
+     * @param {Partial<LandoServiceConfig>} options - Service configuration options.
+     * @param {...Object} sources - Additional configuration sources to merge.
+     */
     constructor(
       id,
       {
@@ -25,7 +87,6 @@ module.exports = {
         type,
         userConfRoot,
         version,
-        // app = '',
         confDest = '',
         confSrc = '',
         config = {},
@@ -52,7 +113,6 @@ module.exports = {
         supported = ['custom'],
         supportedIgnore = false,
         root = '',
-        // webroot = '/app',
       } = {},
       ...sources
     ) {

builders/_service.js

@@ -3,44 +3,113 @@
 // Modules
 const _ = require('lodash');
 
-/*
- * The lowest level lando service
+/**
+ * @typedef {import('../lib/factory').ComposeService} ComposeService
+ * @typedef {import('./_lando').LandoServiceConfig} LandoServiceConfig
+ */
+
+/**
+ * Configuration options for a Lando service.
+ * @typedef {Object} ServiceConfig
+ * @extends {LandoServiceConfig}
+ * @property {string} [webroot] - The webroot path relative to /app
+ * @property {number} [port] - The port to expose
+ * @property {boolean|number} [portforward] - Whether to forward ports (true) or a specific port number
+ * @property {Object} [_app] - Internal app configuration
+ * @property {Object} [_app._config] - App configuration settings
+ * @property {string} [_app._config.bindAddress] - The address to bind services to
+ * @property {Object} [healthcheck] - Health check configuration
+ * @property {Object} [creds] - Service credentials
+ */
+
+/**
+ * Base service implementation that extends the Lando base service.
+ * @type {Object}
  */
 module.exports = {
+  /**
+   * The name of the service.
+   * @type {string}
+   */
   name: '_service',
+
+  /**
+   * The parent service type to extend from.
+   * @type {string}
+   */
   parent: '_lando',
+
+  /**
+   * Creates a new LandoService class extending the parent class.
+   * @param {any} parent - The parent class to extend from.
+   * @return {any} The LandoService class.
+   */
   builder: parent => class LandoService extends parent {
+    /**
+     * Creates a new LandoService instance.
+     * @param {string} id - The unique identifier for the service.
+     * @param {Partial<ServiceConfig>} options - Service configuration options.
+     * @param {...Object} sources - Additional configuration sources to merge.
+     */
     constructor(id, options = {}, ...sources) {
+      // Add the service environment settings
       sources.push({services: _.set({}, options.name, {
         environment: {
+          /**
+           * The webroot path for the service.
+           * @type {string}
+           */
           LANDO_WEBROOT: `/app/${options.webroot}`,
+          /**
+           * The type of the service.
+           * @type {string}
+           */
           LANDO_SERVICE_TYPE: 'service',
         },
       })});
-      // @TODO: add in any envvars for this?
-      // Add in relevant portforward data
+
+      // Add port forwarding settings if specified
       if (options.portforward) {
         if (options.portforward === true) {
+          // Add port forwarding for the service using the default port
           sources.push({services: _.set({}, options.name, {ports: [options.port]})});
         } else {
+          // Add port forwarding with a custom port mapping
           sources.push({services: _.set({}, options.name, {ports: [`${options.portforward}:${options.port}`]})});
         }
       }
-      // Add in relevant info
+
+      // Merge the info object with default connection settings
       options.info = _.merge({}, options.info, {
+        /**
+         * Internal connection details for service-to-service communication.
+         * @type {Object}
+         * @property {string} host - The service hostname
+         * @property {number} port - The service port
+         */
         internal_connection: {
           host: options.name,
           port: options.port,
         },
+        /**
+         * External connection details for host machine access.
+         * @type {Object}
+         * @property {string} host - The bind address
+         * @property {number|string} port - The forwarded port or 'not forwarded'
+         */
         external_connection: {
           host: options._app._config.bindAddress,
           port: _.get(options, 'portforward', 'not forwarded'),
         },
       });
-      // Add in a our healthcheck if we have one
+
+      // Add healthcheck settings if specified
       if (options.healthcheck) options.info.healthcheck = options.healthcheck;
-      // Add in creds if we have them
+
+      // Add credentials if specified
       if (options.creds) options.info.creds = options.creds;
+
+      // Call the parent constructor with the merged configuration
       super(id, options, ...sources);
     }
   },

builders/_webserver.js

@@ -3,25 +3,75 @@
 // Modules
 const _ = require('lodash');
 
-/*
- * The lowest level lando service
+/**
+ * @typedef {import('../lib/factory').ComposeService} ComposeService
+ * @typedef {import('./_lando').LandoServiceConfig} LandoServiceConfig
+ */
+
+/**
+ * Configuration options for a Lando webserver service.
+ * @typedef {Object} WebServerConfig
+ * @extends {LandoServiceConfig}
+ * @property {string} webroot - The webroot path relative to /app
+ */
+
+/**
+ * Base webserver service implementation.
+ * @type {Object}
  */
 module.exports = {
+  /**
+   * The name of the service.
+   * @type {string}
+   */
   name: '_webserver',
+
+  /**
+   * The parent service type to extend from.
+   * @type {string}
+   */
   parent: '_lando',
+
+  /**
+   * Creates a new LandoWebServer class extending the parent class.
+   * @param {any} parent - The parent class to extend from.
+   * @return {any} The LandoWebServer class.
+   */
   builder: parent => class LandoWebServer extends parent {
+    /**
+     * Creates a new LandoWebServer instance.
+     * @param {string} id - The unique identifier for the service.
+     * @param {Partial<WebServerConfig>} options - Service configuration options.
+     * @param {...Object} sources - Additional configuration sources to merge.
+     */
     constructor(id, options = {}, ...sources) {
+      // Add webserver-specific environment settings
       sources.push({services: _.set({}, options.name, {
         environment: {
+          /**
+           * The webroot path for the service.
+           * @type {string}
+           */
           LANDO_WEBROOT: `/app/${options.webroot}`,
+          /**
+           * The type of the service.
+           * @type {string}
+           */
           LANDO_SERVICE_TYPE: 'webserver',
         },
         working_dir: '/app',
       })});
-      // Add in relevant info
+
+      // Add webserver-specific info
       options.info = _.merge({}, options.info, {
+        /**
+         * The webroot path for the service.
+         * @type {string}
+         */
         webroot: options.webroot,
       });
+
+      // Call parent constructor with merged configuration
       super(id, options, ...sources);
     }
   },

builders/lando.js

@@ -1,29 +1,76 @@
 'use strict';
 
+/**
+ * @typedef {import('../lib/factory').ComposeService} ComposeService
+ * @typedef {import('./_lando').LandoServiceConfig} LandoServiceConfig
+ */
+
 const _ = require('lodash');
 
-/*
- * this should be the same as the v3 "compose" service but we are stealth loading it in core so that we can
- * use it for testing when the cli is decoupled from its plugins. you shouldnt really use it directly but theoretically
- * it should have the same docs as https://docs.lando.dev/compose/ except with "type: lando"
- *
- * we've named it "type: lando" as it most closely resembles the new lowest level typed v4 service which is also named
- * lando
- *
+/**
+ * Configuration options for a Lando v3 service.
+ * @typedef {Object} LandoV3Config
+ * @extends {LandoServiceConfig}
+ * @property {string} version - The version of the service
+ * @property {Object} services - Docker compose services configuration
+ * @property {Object} networks - Docker compose networks configuration
+ * @property {Object} volumes - Docker compose volumes configuration
+ */
+
+/**
+ * This module exports a configuration object for the Lando service in Lando.
+ * It is designed to mimic the v3 "compose" service for testing purposes when the CLI is decoupled from its plugins.
+ * Direct use is discouraged, but it should theoretically have the same documentation as https://docs.lando.dev/compose/, except with "type: lando".
+ * The name "type: lando" is chosen because it closely resembles the new lowest level typed v4 service, also named lando.
+ * @type {Object}
  */
 module.exports = {
+  /**
+   * The name of the service.
+   * @type {string}
+   */
   name: 'lando',
+
+  /**
+   * The API version of the service.
+   * @type {number}
+   */
   api: 3,
+
+  /**
+   * The default configuration for the service.
+   * @type {LandoV3Config}
+   */
   config: {
     version: 'custom',
     services: {},
     networks: {},
     volumes: {},
   },
+
+  /**
+   * The parent service type to extend from.
+   * @type {string}
+   */
   parent: '_lando',
+
+  /**
+   * Creates a new LandoServiceV3 class extending the parent class.
+   * @param {any} parent - The parent class to extend from.
+   * @param {LandoV3Config} config - The configuration for the service.
+   * @return {any} The LandoServiceV3 class.
+   */
   builder: (parent, config) => class LandoServiceV3 extends parent {
+    /**
+     * Creates a new LandoServiceV3 instance.
+     * @param {string} id - The unique identifier for the service.
+     * @param {Partial<LandoV3Config>} options - Service configuration options.
+     */
     constructor(id, options = {}) {
+      // Merge default config with provided options
       options = _.merge({}, config, options);
+
+      // Call parent constructor with merged configuration and compose settings
       super(id, options, {
         services: _.set(
           {},