Merge branch 'master' into #1059-specify-dns-resolver-port

server/model/group.js

@@ -3,6 +3,12 @@ const { R } = require("redbean-node");
 
 class Group extends BeanModel {
 
+    /**
+     * Return an object that ready to parse to JSON for public
+     * Only show necessary data to public
+     * @param {boolean} [showTags=false] Should the JSON include monitor tags
+     * @returns {Object}
+     */
     async toPublicJSON(showTags = false) {
         let monitorBeanList = await this.getMonitorList();
         let monitorList = [];
@@ -19,6 +25,10 @@ class Group extends BeanModel {
         };
     }
 
+    /**
+     * Get all monitors
+     * @returns {Bean[]}
+     */
     async getMonitorList() {
         return R.convertToBeans("monitor", await R.getAll(`
             SELECT monitor.* FROM monitor, monitor_group

server/model/heartbeat.js

@@ -13,6 +13,11 @@ const { BeanModel } = require("redbean-node/dist/bean-model");
  */
 class Heartbeat extends BeanModel {
 
+    /**
+     * Return an object that ready to parse to JSON for public
+     * Only show necessary data to public
+     * @returns {Object}
+     */
     toPublicJSON() {
         return {
             status: this.status,
@@ -22,6 +27,10 @@ class Heartbeat extends BeanModel {
         };
     }
 
+    /**
+     * Return an object that ready to parse to JSON
+     * @returns {Object}
+     */
     toJSON() {
         return {
             monitorID: this.monitor_id,

server/model/incident.js

@@ -2,6 +2,11 @@ const { BeanModel } = require("redbean-node/dist/bean-model");
 
 class Incident extends BeanModel {
 
+    /**
+     * Return an object that ready to parse to JSON for public
+     * Only show necessary data to public
+     * @returns {Object}
+     */
     toPublicJSON() {
         return {
             id: this.id,

server/model/monitor.js

@@ -27,6 +27,7 @@ class Monitor extends BeanModel {
     /**
      * Return an object that ready to parse to JSON for public
      * Only show necessary data to public
+     * @returns {Object}
      */
     async toPublicJSON(showTags = false) {
         let obj = {
@@ -41,6 +42,7 @@ class Monitor extends BeanModel {
 
     /**
      * Return an object that ready to parse to JSON
+     * @returns {Object}
      */
     async toJSON(includeSensitiveData = true) {
 
@@ -101,6 +103,10 @@ class Monitor extends BeanModel {
         return data;
     }
 
+    /**
+     * Get all tags applied to this monitor
+     * @returns {Promise<LooseObject<any>[]>}
+     */
     async getTags() {
         return await R.getAll("SELECT mt.*, tag.name, tag.color FROM monitor_tag mt JOIN tag ON mt.tag_id = tag.id WHERE mt.monitor_id = ?", [ this.id ]);
     }
@@ -114,6 +120,10 @@ class Monitor extends BeanModel {
         return Buffer.from(user + ":" + pass).toString("base64");
     }
 
+    /**
+     * Is the TLS expiry notification enabled?
+     * @returns {boolean}
+     */
     isEnabledExpiryNotification() {
         return Boolean(this.expiryNotification);
     }
@@ -134,10 +144,18 @@ class Monitor extends BeanModel {
         return Boolean(this.upsideDown);
     }
 
+    /**
+     * Get accepted status codes
+     * @returns {Object}
+     */
     getAcceptedStatuscodes() {
         return JSON.parse(this.accepted_statuscodes_json);
     }
 
+    /**
+     * Start monitor
+     * @param {Server} io Socket server instance
+     */
     start(io) {
         let previousBeat = null;
         let retries = 0;
@@ -497,6 +515,7 @@ class Monitor extends BeanModel {
 
         };
 
+        /** Get a heartbeat and handle errors */
         const safeBeat = async () => {
             try {
                 await beat();
@@ -522,6 +541,7 @@ class Monitor extends BeanModel {
         }
     }
 
+    /** Stop monitor */
     stop() {
         clearTimeout(this.heartbeatInterval);
         this.isStop = true;
@@ -529,6 +549,10 @@ class Monitor extends BeanModel {
         this.prometheus().remove();
     }
 
+    /**
+     * Get a new prometheus instance
+     * @returns {Prometheus}
+     */
     prometheus() {
         return new Prometheus(this);
     }
@@ -537,7 +561,7 @@ class Monitor extends BeanModel {
      * Helper Method:
      * returns URL object for further usage
      * returns null if url is invalid
-     * @returns {null|URL}
+     * @returns {(null|URL)}
      */
     getUrl() {
         try {
@@ -550,7 +574,7 @@ class Monitor extends BeanModel {
     /**
      * Store TLS info to database
      * @param checkCertificateResult
-     * @returns {Promise<object>}
+     * @returns {Promise<Object>}
      */
     async updateTlsInfo(checkCertificateResult) {
         let tlsInfoBean = await R.findOne("monitor_tls_info", "monitor_id = ?", [
@@ -592,6 +616,12 @@ class Monitor extends BeanModel {
         return checkCertificateResult;
     }
 
+    /**
+     * Send statistics to clients
+     * @param {Server} io Socket server instance
+     * @param {number} monitorID ID of monitor to send
+     * @param {number} userID ID of user to send to
+     */
     static async sendStats(io, monitorID, userID) {
         const hasClients = getTotalClientInRoom(io, userID) > 0;
 
@@ -606,8 +636,8 @@ class Monitor extends BeanModel {
     }
 
     /**
-     *
-     * @param duration : int Hours
+     * Send the average ping to user
+     * @param {number} duration Hours
      */
     static async sendAvgPing(duration, io, monitorID, userID) {
         const timeLogger = new TimeLogger();
@@ -627,6 +657,12 @@ class Monitor extends BeanModel {
         io.to(userID).emit("avgPing", monitorID, avgPing);
     }
 
+    /**
+     * Send certificate information to client
+     * @param {Server} io Socket server instance
+     * @param {number} monitorID ID of monitor to send
+     * @param {number} userID ID of user to send to
+     */
     static async sendCertInfo(io, monitorID, userID) {
         let tlsInfo = await R.findOne("monitor_tls_info", "monitor_id = ?", [
             monitorID,
@@ -640,7 +676,8 @@ class Monitor extends BeanModel {
      * Uptime with calculation
      * Calculation based on:
      * https://www.uptrends.com/support/kb/reporting/calculation-of-uptime-and-downtime
-     * @param duration : int Hours
+     * @param {number} duration Hours
+     * @param {number} monitorID ID of monitor to calculate
      */
     static async calcUptime(duration, monitorID) {
         const timeLogger = new TimeLogger();
@@ -694,7 +731,7 @@ class Monitor extends BeanModel {
 
         } else {
             // Handle new monitor with only one beat, because the beat's duration = 0
-            let status = parseInt(await R.getCell("SELECT `status` FROM heartbeat WHERE monitor_id = ?", [monitorID]));
+            let status = parseInt(await R.getCell("SELECT `status` FROM heartbeat WHERE monitor_id = ?", [ monitorID ]));
 
             if (status === UP) {
                 uptime = 1;
@@ -706,13 +743,23 @@ class Monitor extends BeanModel {
 
     /**
      * Send Uptime
-     * @param duration : int Hours
+     * @param {number} duration Hours
+     * @param {Server} io Socket server instance
+     * @param {number} monitorID ID of monitor to send
+     * @param {number} userID ID of user to send to
      */
     static async sendUptime(duration, io, monitorID, userID) {
         const uptime = await this.calcUptime(duration, monitorID);
         io.to(userID).emit("uptime", monitorID, duration, uptime);
     }
 
+    /**
+     * Has status of monitor changed since last beat?
+     * @param {boolean} isFirstBeat Is this the first beat of this monitor?
+     * @param {const} previousBeatStatus Status of the previous beat
+     * @param {const} currentBeatStatus Status of the current beat
+     * @returns {boolean} True if is an important beat else false
+     */
     static isImportantBeat(isFirstBeat, previousBeatStatus, currentBeatStatus) {
         // * ? -> ANY STATUS = important [isFirstBeat]
         // UP -> PENDING = not important
@@ -731,6 +778,12 @@ class Monitor extends BeanModel {
         return isImportant;
     }
 
+    /**
+     * Send a notification about a monitor
+     * @param {boolean} isFirstBeat Is this beat the first of this monitor?
+     * @param {Monitor} monitor The monitor to send a notificaton about
+     * @param {Bean} bean Status information about monitor
+     */
     static async sendNotification(isFirstBeat, monitor, bean) {
         if (!isFirstBeat || bean.status === DOWN) {
             const notificationList = await Monitor.getNotificationList(monitor);
@@ -755,6 +808,11 @@ class Monitor extends BeanModel {
         }
     }
 
+    /**
+     * Get list of notification providers for a given monitor
+     * @param {Monitor} monitor Monitor to get notification providers for
+     * @returns {Promise<LooseObject<any>[]>}
+     */
     static async getNotificationList(monitor) {
         let notificationList = await R.getAll("SELECT notification.* FROM notification, monitor_notification WHERE monitor_id = ? AND monitor_notification.notification_id = notification.id ", [
             monitor.id,
@@ -762,6 +820,10 @@ class Monitor extends BeanModel {
         return notificationList;
     }
 
+    /**
+     * Send notification about a certificate
+     * @param {Object} tlsInfoObject Information about certificate
+     */
     async sendCertNotification(tlsInfoObject) {
         if (tlsInfoObject && tlsInfoObject.certInfo && tlsInfoObject.certInfo.daysRemaining) {
             const notificationList = await Monitor.getNotificationList(this);
@@ -773,6 +835,14 @@ class Monitor extends BeanModel {
         }
     }
 
+    /**
+     * Send a certificate notification when certificate expires in less
+     * than target days
+     * @param {number} daysRemaining Number of days remaining on certifcate
+     * @param {number} targetDays Number of days to alert after
+     * @param {LooseObject<any>[]} notificationList List of notification providers
+     * @returns {Promise<void>}
+     */
     async sendCertNotificationByTargetDays(daysRemaining, targetDays, notificationList) {
 
         if (daysRemaining > targetDays) {
@@ -820,6 +890,11 @@ class Monitor extends BeanModel {
         }
     }
 
+    /**
+     * Get the status of the previous heartbeat
+     * @param {number} monitorID ID of monitor to check
+     * @returns {Promise<LooseObject<any>>}
+     */
     static async getPreviousHeartbeat(monitorID) {
         return await R.getRow(`
             SELECT status, time FROM heartbeat

server/model/proxy.js

@@ -1,6 +1,10 @@
 const { BeanModel } = require("redbean-node/dist/bean-model");
 
 class Proxy extends BeanModel {
+    /**
+     * Return an object that ready to parse to JSON
+     * @returns {Object}
+     */
     toJSON() {
         return {
             id: this._id,

server/model/status_page.js

@@ -6,6 +6,7 @@ class StatusPage extends BeanModel {
     static domainMappingList = { };
 
     /**
+     * Loads domain mapping from DB
      * Return object like this: { "test-uptime.kuma.pet": "default" }
      * @returns {Promise<void>}
      */
@@ -17,6 +18,12 @@ class StatusPage extends BeanModel {
         `);
     }
 
+    /**
+     * Send status page list to client
+     * @param {Server} io io Socket server instance
+     * @param {Socket} socket Socket.io instance
+     * @returns {Promise<Bean[]>}
+     */
     static async sendStatusPageList(io, socket) {
         let result = {};
 
@@ -30,6 +37,11 @@ class StatusPage extends BeanModel {
         return list;
     }
 
+    /**
+     * Update list of domain names
+     * @param {string[]} domainNameList
+     * @returns {Promise<void>}
+     */
     async updateDomainNameList(domainNameList) {
 
         if (!Array.isArray(domainNameList)) {
@@ -69,6 +81,10 @@ class StatusPage extends BeanModel {
         }
     }
 
+    /**
+     * Get list of domain names
+     * @returns {Object[]}
+     */
     getDomainNameList() {
         let domainList = [];
         for (let domain in StatusPage.domainMappingList) {
@@ -81,6 +97,10 @@ class StatusPage extends BeanModel {
         return domainList;
     }
 
+    /**
+     * Return an object that ready to parse to JSON
+     * @returns {Object}
+     */
     async toJSON() {
         return {
             id: this.id,
@@ -98,6 +118,11 @@ class StatusPage extends BeanModel {
         };
     }
 
+    /**
+     * Return an object that ready to parse to JSON for public
+     * Only show necessary data to public
+     * @returns {Object}
+     */
     async toPublicJSON() {
         return {
             slug: this.slug,
@@ -113,12 +138,20 @@ class StatusPage extends BeanModel {
         };
     }
 
+    /**
+     * Convert slug to status page ID
+     * @param {string} slug
+     */
     static async slugToID(slug) {
         return await R.getCell("SELECT id FROM status_page WHERE slug = ? ", [
             slug
         ]);
     }
 
+    /**
+     * Get path to the icon for the page
+     * @returns {string}
+     */
     getIcon() {
         if (!this.icon) {
             return "/icon.svg";

server/model/tag.js

@@ -1,6 +1,11 @@
 const { BeanModel } = require("redbean-node/dist/bean-model");
 
 class Tag extends BeanModel {
+
+    /**
+     * Return an object that ready to parse to JSON
+     * @returns {Object}
+     */
     toJSON() {
         return {
             id: this._id,

server/model/user.js

@@ -3,12 +3,11 @@ const passwordHash = require("../password-hash");
 const { R } = require("redbean-node");
 
 class User extends BeanModel {
-
     /**
-     *
+     * Reset user password
      * Fix #1510, as in the context reset-password.js, there is no auto model mapping. Call this static function instead.
-     * @param userID
-     * @param newPassword
+     * @param {number} userID ID of user to update
+     * @param {string} newPassword
      * @returns {Promise<void>}
      */
     static async resetPassword(userID, newPassword) {
@@ -19,8 +18,8 @@ class User extends BeanModel {
     }
 
     /**
-     *
-     * @param newPassword
+     * Reset this users password
+     * @param {string} newPassword
      * @returns {Promise<void>}
      */
     async resetPassword(newPassword) {