underpost 2.8.885 → 2.8.886

package/src/server/dns.js

@@ -1,3 +1,9 @@
+/**
+ * Provides a comprehensive set of DNS and IP management utilities,
+ * primarily focused on dynamic DNS (DDNS) updates and network checks.
+ * @module src/server/dns.js
+ * @namespace DnsManager
+ */
 import axios from 'axios';
 import dotenv from 'dotenv';
 import fs from 'fs';
@@ -13,52 +19,109 @@ dotenv.config();
 
 const logger = loggerFactory(import.meta);
 
-const ip = {
-  public: {
-    get: async () => await publicIp(), // => 'fe80::200:f8ff:fe21:67cf'
-    ipv4: async () => await publicIpv4(), // => '46.5.21.123'
-    ipv6: async () => await publicIpv6(), // => 'fe80::200:f8ff:fe21:67cf'
-  },
-};
+/**
+ * Main class for handling DNS and IP related operations.
+ * All utility methods are implemented as static to serve as a namespace container.
+ * @class Dns
+ * @augments Dns
+ * @memberof DnsManager
+ */
+class Dns {
+  /**
+   * Retrieves the current public IP address (IPv4 or IPv6).
+   * @async
+   * @static
+   * @memberof DnsManager
+   * @returns {Promise<string>} The public IP address.
+   */
+  static async getPublicIp() {
+    return await publicIp();
+  }
 
-const isInternetConnection = (domain = 'google.com') =>
-  new Promise((resolve) => dns.lookup(domain, {}, (err) => resolve(err ? false : true)));
+  /**
+   * Retrieves the current public IPv4 address.
+   * @async
+   * @static
+   * @memberof DnsManager
+   * @returns {Promise<string>} The public IPv4 address.
+   */
+  static async getPublicIpv4() {
+    return await publicIpv4();
+  }
 
-// export INTERFACE=$(ip route | grep default | cut -d ' ' -f 5)
-// export IP_ADDRESS=$(ip -4 addr show dev $INTERFACE | grep -oP '(?<=inet\s)\d+(\.\d+){3}')
-const getLocalIPv4Address = () =>
-  os.networkInterfaces()[
-    shellExec(`ip route | grep default | cut -d ' ' -f 5`, {
+  /**
+   * Retrieves the current public IPv6 address.
+   * @async
+   * @static
+   * @memberof DnsManager
+   * @returns {Promise<string>} The public IPv6 address.
+   */
+  static async getPublicIpv6() {
+    return await publicIpv6();
+  }
+
+  /**
+   * Checks for active internet connection by performing a DNS lookup on a specified domain.
+   * @static
+   * @memberof DnsManager
+   * @param {string} [domain='google.com'] The domain to check the connection against.
+   * @returns {Promise<boolean>} True if connected, false otherwise.
+   */
+  static isInternetConnection(domain = 'google.com') {
+    return new Promise((resolve) => dns.lookup(domain, {}, (err) => resolve(err ? false : true)));
+  }
+
+  /**
+   * Gets the local device's IPv4 address by determining the active network interface.
+   * This relies on shell execution (`ip route`) and is primarily intended for Linux environments.
+   * @static
+   * @memberof DnsManager
+   * @returns {string} The local IPv4 address.
+   */
+  static getLocalIPv4Address() {
+    // Determine the default network interface name using shell command
+    const interfaceName = shellExec(`ip route | grep default | cut -d ' ' -f 5`, {
       stdout: true,
       silent: true,
       disableLog: true,
-    }).trim()
-  ].find((i) => i.family === 'IPv4').address;
+    }).trim();
 
-class Dns {
-  static callback = async function (deployList) {
-    // Network topology configuration:
-    // LAN -> [NAT-VPS](modem/router device) -> WAN
-    // enabled DMZ Host to proxy IP 80-443 (79-444) sometimes router block first port
-
-    // Enabling DHCP
-    // Navigate to Subnets > VLAN > Configure DHCP.
-    // Select the appropriate DHCP options (Managed or Relay).
-    // Save and apply changes.
-
-    // verify inet ip proxy server address
-    // DHCP (Dynamic Host Configuration Protocol) LAN reserver IP -> MAC ID
-    // LAN server or device's local servers port ->  3000-3100 (2999-3101)
-    // DNS Records: [ANAME](Address Dynamic) -> [A](ipv4) host | [AAAA](ipv6) host -> [public-ip]
-    // Forward the router's TCP/UDP ports to the LAN device's IP address
-    const isOnline = await isInternetConnection();
+    // Find the IPv4 address associated with the determined interface
+    const networkInfo = os.networkInterfaces()[interfaceName];
+
+    if (!networkInfo) {
+      logger.error(`Could not find network interface: ${interfaceName}`);
+      return null;
+    }
+
+    const ipv4 = networkInfo.find((i) => i.family === 'IPv4');
+
+    if (!ipv4) {
+      logger.error(`Could not find IPv4 address for interface: ${interfaceName}`);
+      return null;
+    }
+
+    return ipv4.address;
+  }
+
+  /**
+   * Performs the dynamic DNS update logic.
+   * It checks if the public IP has changed and, if so, updates the configured DNS records.
+   * @async
+   * @static
+   * @memberof DnsManager
+   * @param {string} deployList Comma-separated string of deployment IDs to process.
+   * @returns {Promise<void>}
+   */
+  static async callback(deployList) {
+    const isOnline = await Dns.isInternetConnection();
 
     if (!isOnline) return;
 
     let testIp;
 
     try {
-      testIp = await ip.public.ipv4();
+      testIp = await Dns.getPublicIpv4();
     } catch (error) {
       logger.error(error, { testIp, stack: error.stack });
     }
@@ -66,52 +129,97 @@ class Dns {
     const currentIp = UnderpostRootEnv.API.get('ip');
 
     if (validator.isIP(testIp) && currentIp !== testIp) {
-      logger.info(`new ip`, testIp);
+      logger.info(`New IP detected`, testIp);
       UnderpostRootEnv.API.set('monitor-input', 'pause');
 
       for (const _deployId of deployList.split(',')) {
         const deployId = _deployId.trim();
         const privateCronConfPath = `./engine-private/conf/${deployId}/conf.cron.json`;
         const confCronPath = fs.existsSync(privateCronConfPath) ? privateCronConfPath : './conf/conf.cron.json';
+
+        if (!fs.existsSync(confCronPath)) {
+          logger.warn(`Cron config file not found for deployId: ${deployId} at ${confCronPath}`);
+          continue;
+        }
+
         const confCronData = JSON.parse(fs.readFileSync(confCronPath, 'utf8'));
+
+        if (!confCronData.records) {
+          logger.warn(`'records' field missing in cron config for deployId: ${deployId}`);
+          continue;
+        }
+
+        // Iterate through DNS record types (A, AAAA, etc.)
         for (const recordType of Object.keys(confCronData.records)) {
           switch (recordType) {
             case 'A':
+              // Process A records for IPv4 update
               for (const dnsProvider of confCronData.records[recordType]) {
                 if (typeof Dns.services.updateIp[dnsProvider.dns] === 'function')
                   await Dns.services.updateIp[dnsProvider.dns]({ ...dnsProvider, ip: testIp });
               }
               break;
 
+            // Add other record types (e.g., AAAA) here if needed
             default:
               break;
           }
         }
+
+        // Verify the IP update externally
         try {
           const ipUrlTest = `https://${process.env.DEFAULT_DEPLOY_HOST}`;
           const response = await axios.get(ipUrlTest);
           const verifyIp = response.request.socket.remoteAddress;
           logger.info(ipUrlTest + ' verify ip', verifyIp);
           if (verifyIp === testIp) {
-            logger.info('ip updated successfully', testIp);
+            logger.info('IP updated successfully and verified', testIp);
             UnderpostRootEnv.API.set('ip', testIp);
             UnderpostRootEnv.API.delete('monitor-input');
-          } else logger.error('ip not updated', testIp);
+          } else {
+            logger.error('IP not updated or verification failed', { expected: testIp, received: verifyIp });
+          }
         } catch (error) {
-          logger.error(error, error.stack);
-          logger.error('ip not updated', testIp);
+          logger.error('Error during IP update verification step', {
+            error: error.message,
+            stack: error.stack,
+            testIp,
+          });
         }
       }
     }
-  };
+  }
 
+  /**
+   * Internal collection of external DNS service update functions.
+   * @static
+   * @memberof DnsManager
+   * @property {object} updateIp - Functions keyed by DNS provider name to update A/AAAA records.
+   */
   static services = {
     updateIp: {
+      /**
+       * Updates the IP address for a dondominio.com DNS record.
+       * @memberof DnsManager
+       * @param {object} options
+       * @param {string} options.user - The dondominio DDNS username.
+       * @param {string} options.api_key - The dondominio DDNS password/API key.
+       * @param {string} options.host - The hostname to update.
+       * @param {string} options.dns - The name of the DNS provider ('dondominio').
+       * @param {string} options.ip - The new IPv4 address to set.
+       * @returns {Promise<boolean>} True on success, false on failure.
+       */
       dondominio: (options) => {
         const { user, api_key, host, dns, ip } = options;
         const url = `https://dondns.dondominio.com/json/?user=${user}&password=${api_key}&host=${host}&ip=${ip}`;
         logger.info(`${dns} update ip url`, url);
-        if (process.env.NODE_ENV !== 'production') return false;
+
+        // Prevent live IP update in non-production environments
+        if (process.env.NODE_ENV !== 'production') {
+          logger.warn('Skipping dondominio update in non-production environment.');
+          return Promise.resolve(false);
+        }
+
         return new Promise((resolve) => {
           axios
             .get(url)
@@ -120,15 +228,49 @@ class Dns {
               return resolve(true);
             })
             .catch((error) => {
-              logger.error(error, `${dns} update ip error`);
+              logger.error(error, `${dns} update ip error: ${error.message}`);
               return resolve(false);
             });
         });
       },
+      // Add other DNS provider update functions here
     },
   };
 }
 
+/**
+ * @namespace Dns
+ * @description Exported IP object for backward compatibility, mapping to Dns static methods.
+ */
+const ip = {
+  public: {
+    /** @type {function(): Promise<string>} */
+    get: Dns.getPublicIp,
+    /** @type {function(): Promise<string>} */
+    ipv4: Dns.getPublicIpv4,
+    /** @type {function(): Promise<string>} */
+    ipv6: Dns.getPublicIpv6,
+  },
+};
+
+/**
+ * @function isInternetConnection
+ * @memberof DnsManager
+ * @description Exported function for backward compatibility.
+ * @param {string} [domain='google.com']
+ * @returns {Promise<boolean>}
+ */
+const isInternetConnection = Dns.isInternetConnection;
+
+/**
+ * @function getLocalIPv4Address
+ * @memberof DnsManager
+ * @description Exported function for backward compatibility.
+ * @returns {string}
+ */
+const getLocalIPv4Address = Dns.getLocalIPv4Address;
+
+// Export the class as default and all original identifiers for backward compatibility.
 export default Dns;
 
 export { Dns, ip, isInternetConnection, getLocalIPv4Address };

package/src/server/downloader.js

@@ -1,3 +1,9 @@
+/**
+ * Provides a utility class for downloading files from a URL and saving them to the local filesystem.
+ * @module src/server/downloader.js
+ * @namespace Downloader
+ */
+
 import axios from 'axios';
 import fs from 'fs';
 import { loggerFactory } from './logger.js';
@@ -6,29 +12,64 @@ dotenv.config();
 
 const logger = loggerFactory(import.meta);
 
-const Downloader = (url, fullPath, options = { method: 'get', responseType: 'stream' }) =>
-  new Promise((resolve, reject) =>
-    axios({
-      url,
-      ...options,
-    })
-      .then((response) => {
-        // Create a write stream to save the file to the specified path
-        const writer = fs.createWriteStream(fullPath);
-        response.data.pipe(writer);
-        writer.on('finish', () => {
-          logger.info('Download complete. File saved at', fullPath);
-          return resolve(fullPath);
-        });
-        writer.on('error', (error) => {
-          logger.error(error, 'Error downloading the file');
-          return reject(error);
-        });
+/**
+ * Main class for handling file downloading operations.
+ * All utility methods are implemented as static to serve as a namespace container.
+ * @class Downloader
+ * @augments Downloader
+ * @memberof Downloader
+ */
+class Downloader {
+  /**
+   * Downloads a file from a given URL and pipes the stream to a local file path.
+   * @static
+   * @memberof Downloader
+   * @param {string} url The URL of the file to download.
+   * @param {string} fullPath The full local path where the file should be saved.
+   * @param {object} [options] Axios request configuration options.
+   * @param {string} [options.method='get'] HTTP method.
+   * @param {string} [options.responseType='stream'] Expected response type.
+   * @returns {Promise<string>} Resolves with the full path of the saved file on success.
+   * @memberof Downloader
+   */
+  static downloadFile(url, fullPath, options = { method: 'get', responseType: 'stream' }) {
+    return new Promise((resolve, reject) =>
+      axios({
+        url,
+        ...options,
       })
-      .catch((error) => {
-        logger.error(error, 'Error in the request');
-        return reject(error);
-      }),
-  );
+        .then((response) => {
+          // Create a write stream to save the file to the specified path
+          const writer = fs.createWriteStream(fullPath);
+          response.data.pipe(writer);
+          writer.on('finish', () => {
+            logger.info('Download complete. File saved at', fullPath);
+            return resolve(fullPath);
+          });
+          writer.on('error', (error) => {
+            logger.error(error, 'Error downloading the file');
+            // Cleanup incomplete file if possible
+            if (fs.existsSync(fullPath)) fs.unlinkSync(fullPath);
+            return reject(error);
+          });
+        })
+        .catch((error) => {
+          logger.error(error, 'Error in the request');
+          return reject(error);
+        }),
+    );
+  }
+}
+
+export default Downloader;
 
-export { Downloader };
+/**
+ * @function downloadFile
+ * @description Backward compatibility export for `Downloader.downloadFile`.
+ * @param {string} url The URL of the file to download.
+ * @param {string} fullPath The full local path where the file should be saved.
+ * @param {object} [options] Axios request configuration options.
+ * @returns {Promise<string>} Resolves with the full path of the saved file on success.
+ * @memberof Downloader
+ */
+export const downloadFile = Downloader.downloadFile;