From caff9ca736228e833fcab0ecfef8ebb551f9d0ef Mon Sep 17 00:00:00 2001 From: Matthew Nickson Date: Thu, 5 Jan 2023 22:19:05 +0000 Subject: [PATCH] Added JSDoc for server/ Signed-off-by: Matthew Nickson --- server/auth.js | 6 ++++ server/cacheable-dns-http-agent.js | 4 +++ server/jobs.js | 1 + server/model/maintenance.js | 23 +++++++++++++++ server/model/maintenance_timeslot.js | 9 ++++++ server/model/monitor.js | 8 ++++++ server/notification-providers/serverchan.js | 6 ++++ server/prometheus.js | 1 + server/uptime-cache-list.js | 18 +++++++++--- server/uptime-kuma-server.js | 32 +++++++++++++++++++++ 10 files changed, 104 insertions(+), 4 deletions(-) diff --git a/server/auth.js b/server/auth.js index 3ce1a604..fd19b0e4 100644 --- a/server/auth.js +++ b/server/auth.js @@ -63,6 +63,12 @@ function myAuthorizer(username, password, callback) { }); } +/** + * Use basic auth if auth is not disabled + * @param {express.Request} req Express request object + * @param {express.Response} res Express response object + * @param {express.NextFunction} next + */ exports.basicAuth = async function (req, res, next) { const middleware = basicAuth({ authorizer: myAuthorizer, diff --git a/server/cacheable-dns-http-agent.js b/server/cacheable-dns-http-agent.js index 30136791..cc067f72 100644 --- a/server/cacheable-dns-http-agent.js +++ b/server/cacheable-dns-http-agent.js @@ -37,6 +37,10 @@ class CacheableDnsHttpAgent { this.enable = isEnable; } + /** + * Attach cacheable to HTTP agent + * @param {http.Agent} agent Agent to install + */ static install(agent) { this.cacheable.install(agent); } diff --git a/server/jobs.js b/server/jobs.js index f9c7f86e..66a27606 100644 --- a/server/jobs.js +++ b/server/jobs.js @@ -32,6 +32,7 @@ const initBackgroundJobs = function (args) { return bree; }; +/** Stop all background jobs if running */ const stopBackgroundJobs = function () { if (bree) { bree.stop(); diff --git a/server/model/maintenance.js b/server/model/maintenance.js index d9be3427..45db63d1 100644 --- a/server/model/maintenance.js +++ b/server/model/maintenance.js @@ -112,6 +112,11 @@ class Maintenance extends BeanModel { return this.toPublicJSON(timezone); } + /** + * Get a list of weekdays that the maintenance is active for + * Monday=1, Tuesday=2 etc. + * @returns {number[]} Array of active weekdays + */ getDayOfWeekList() { log.debug("timeslot", "List: " + this.weekdays); return JSON.parse(this.weekdays).sort(function (a, b) { @@ -119,12 +124,20 @@ class Maintenance extends BeanModel { }); } + /** + * Get a list of days in month that maintenance is active for + * @returns {number[]} Array of active days in month + */ getDayOfMonthList() { return JSON.parse(this.days_of_month).sort(function (a, b) { return a - b; }); } + /** + * Get the start date and time for maintenance + * @returns {dayjs.Dayjs} Start date and time + */ getStartDateTime() { let startOfTheDay = dayjs.utc(this.start_date).format("HH:mm"); log.debug("timeslot", "startOfTheDay: " + startOfTheDay); @@ -137,6 +150,10 @@ class Maintenance extends BeanModel { return dayjs.utc(this.start_date).add(startTimeSecond, "second"); } + /** + * Get the duraction of maintenance in seconds + * @returns {number} Duration of maintenance + */ getDuration() { let duration = dayjs.utc(this.end_time, "HH:mm").diff(dayjs.utc(this.start_time, "HH:mm"), "second"); // Add 24hours if it is across day @@ -146,6 +163,12 @@ class Maintenance extends BeanModel { return duration; } + /** + * Convert data from socket to bean + * @param {Bean} bean Bean to fill in + * @param {Object} obj Data to fill bean with + * @returns {Bean} Filled bean + */ static jsonToBean(bean, obj) { if (obj.id) { bean.id = obj.id; diff --git a/server/model/maintenance_timeslot.js b/server/model/maintenance_timeslot.js index 2babe6bc..77643c2c 100644 --- a/server/model/maintenance_timeslot.js +++ b/server/model/maintenance_timeslot.js @@ -6,6 +6,11 @@ const { UptimeKumaServer } = require("../uptime-kuma-server"); class MaintenanceTimeslot extends BeanModel { + /** + * Return an object that ready to parse to JSON for public + * Only show necessary data to public + * @returns {Object} + */ async toPublicJSON() { const serverTimezoneOffset = UptimeKumaServer.getInstance().getTimezoneOffset(); @@ -21,6 +26,10 @@ class MaintenanceTimeslot extends BeanModel { return obj; } + /** + * Return an object that ready to parse to JSON + * @returns {Object} + */ async toJSON() { return await this.toPublicJSON(); } diff --git a/server/model/monitor.js b/server/model/monitor.js index 9f8c8300..e6332b8f 100644 --- a/server/model/monitor.js +++ b/server/model/monitor.js @@ -748,6 +748,13 @@ class Monitor extends BeanModel { } } + /** + * Make a request using axios + * @param {Object} options Options for Axios + * @param {boolean} finalCall Should this be the final call i.e + * don't retry on faliure + * @returns {Object} Axios response + */ async makeAxiosRequest(options, finalCall = false) { try { let res; @@ -1229,6 +1236,7 @@ class Monitor extends BeanModel { return maintenance.count !== 0; } + /** Make sure monitor interval is between bounds */ validate() { if (this.interval > MAX_INTERVAL_SECOND) { throw new Error(`Interval cannot be more than ${MAX_INTERVAL_SECOND} seconds`); diff --git a/server/notification-providers/serverchan.js b/server/notification-providers/serverchan.js index fbf99f80..d631c8e6 100644 --- a/server/notification-providers/serverchan.js +++ b/server/notification-providers/serverchan.js @@ -21,6 +21,12 @@ class ServerChan extends NotificationProvider { } } + /** + * Get the formatted title for message + * @param {?Object} monitorJSON Monitor details (For Up/Down only) + * @param {?Object} heartbeatJSON Heartbeat details (For Up/Down only) + * @returns {string} Formatted title + */ checkStatus(heartbeatJSON, monitorJSON) { let title = "UptimeKuma Message"; if (heartbeatJSON != null && heartbeatJSON["status"] === UP) { diff --git a/server/prometheus.js b/server/prometheus.js index 1473ab7a..aeba95f8 100644 --- a/server/prometheus.js +++ b/server/prometheus.js @@ -99,6 +99,7 @@ class Prometheus { } } + /** Remove monitor from prometheus */ remove() { try { monitorCertDaysRemaining.remove(this.monitorLabelValues); diff --git a/server/uptime-cache-list.js b/server/uptime-cache-list.js index 1347968f..d88a9cbf 100644 --- a/server/uptime-cache-list.js +++ b/server/uptime-cache-list.js @@ -6,10 +6,10 @@ class UptimeCacheList { static list = {}; /** - * - * @param monitorID - * @param duration - * @return number + * Get the uptime for a specific period + * @param {number} monitorID + * @param {number} duration + * @return {number} */ static getUptime(monitorID, duration) { if (UptimeCacheList.list[monitorID] && UptimeCacheList.list[monitorID][duration]) { @@ -20,6 +20,12 @@ class UptimeCacheList { } } + /** + * Add uptime for specified monitor + * @param {number} monitorID + * @param {number} duration + * @param {number} uptime Uptime to add + */ static addUptime(monitorID, duration, uptime) { log.debug("UptimeCacheList", "addUptime: " + monitorID + " " + duration); if (!UptimeCacheList.list[monitorID]) { @@ -28,6 +34,10 @@ class UptimeCacheList { UptimeCacheList.list[monitorID][duration] = uptime; } + /** + * Clear cache for specified monitor + * @param {number} monitorID + */ static clearCache(monitorID) { log.debug("UptimeCacheList", "clearCache: " + monitorID); delete UptimeCacheList.list[monitorID]; diff --git a/server/uptime-kuma-server.js b/server/uptime-kuma-server.js index 06237562..14712176 100644 --- a/server/uptime-kuma-server.js +++ b/server/uptime-kuma-server.js @@ -86,6 +86,7 @@ class UptimeKumaServer { this.io = new Server(this.httpServer); } + /** Initialise app after the dabase has been set up */ async initAfterDatabaseReady() { await CacheableDnsHttpAgent.update(); @@ -98,6 +99,11 @@ class UptimeKumaServer { this.generateMaintenanceTimeslotsInterval = setInterval(this.generateMaintenanceTimeslots, 60 * 1000); } + /** + * Send list of monitors to client + * @param {Socket} socket + * @returns {Object} List of monitors + */ async sendMonitorList(socket) { let list = await this.getMonitorJSONList(socket.userID); this.io.to(socket.userID).emit("monitorList", list); @@ -134,6 +140,11 @@ class UptimeKumaServer { return await this.sendMaintenanceListByUserID(socket.userID); } + /** + * Send list of maintenances to user + * @param {number} userID + * @returns {Object} + */ async sendMaintenanceListByUserID(userID) { let list = await this.getMaintenanceJSONList(userID); this.io.to(userID).emit("maintenanceList", list); @@ -185,6 +196,11 @@ class UptimeKumaServer { errorLogStream.end(); } + /** + * Get the IP of the client connected to the socket + * @param {Socket} socket + * @returns {string} + */ async getClientIP(socket) { let clientIP = socket.client.conn.remoteAddress; @@ -203,6 +219,12 @@ class UptimeKumaServer { } } + /** + * Attempt to get the current server timezone + * If this fails, fall back to environment variables and then make a + * guess. + * @returns {string} + */ async getTimezone() { let timezone = await Settings.get("serverTimezone"); if (timezone) { @@ -214,16 +236,25 @@ class UptimeKumaServer { } } + /** + * Get the current offset + * @returns {string} + */ getTimezoneOffset() { return dayjs().format("Z"); } + /** + * Set the current server timezone and environment variables + * @param {string} timezone + */ async setTimezone(timezone) { await Settings.set("serverTimezone", timezone, "general"); process.env.TZ = timezone; dayjs.tz.setDefault(timezone); } + /** Load the timeslots for maintenance */ async generateMaintenanceTimeslots() { let list = await R.find("maintenance_timeslot", " generated_next = 0 AND start_date <= DATETIME('now') "); @@ -237,6 +268,7 @@ class UptimeKumaServer { } + /** Stop the server */ async stop() { clearTimeout(this.generateMaintenanceTimeslotsInterval); }