diff --git a/extra/download-dist.js b/extra/download-dist.js
index dc64166c4..a9c630239 100644
--- a/extra/download-dist.js
+++ b/extra/download-dist.js
@@ -11,6 +11,12 @@ const filename = "dist.tar.gz";
const url = `https://github.com/louislam/uptime-kuma/releases/download/${version}/${filename}`;
download(url);
+/**
+ * Downloads the latest version of the dist from a GitHub release.
+ * @param {string} url The URL to download from.
+ *
+ * Generated by Trelent
+ */
function download(url) {
console.log(url);
diff --git a/extra/update-version.js b/extra/update-version.js
index 2e3b42da8..34b46281f 100644
--- a/extra/update-version.js
+++ b/extra/update-version.js
@@ -37,6 +37,12 @@ if (! exists) {
console.log("version exists");
}
+/**
+ * Updates the version number in package.json and commits it to git
+ * @param {string} version - The new version number
+ *
+ * Generated by Trelent
+ */
function commit(version) {
let msg = "update to " + version;
@@ -54,6 +60,12 @@ function tag(version) {
console.log(res.stdout.toString().trim());
}
+/**
+ * Checks if a given version is already tagged in the git repository.
+ * @param {string} version - The version to check for.
+ *
+ * Generated by Trelent
+ */
function tagExists(version) {
if (! version) {
throw new Error("invalid version");
@@ -64,6 +76,13 @@ function tagExists(version) {
return res.stdout.toString().trim() === version;
}
+/**
+ * Update the How-to-Update.md file in the wiki to reflect a new version of Kuma.
+ * @param {string} oldVersion The previous version of Kuma that was released.
+ * @param {string} newVersion The current version of Kuma that is being released.
+ *
+ * Generated by Trelent
+ */
function updateWiki(oldVersion, newVersion) {
const wikiDir = "./tmp/wiki";
const howToUpdateFilename = "./tmp/wiki/🆙-How-to-Update.md";
diff --git a/server/auth.js b/server/auth.js
index c476ea1e3..2cb71e93c 100644
--- a/server/auth.js
+++ b/server/auth.js
@@ -30,6 +30,13 @@ exports.login = async function (username, password) {
return null;
};
+/**
+ * A function that checks if a user is logged in.
+ * @param {string} username The username of the user to check for.
+ * @param {function} callback The callback to call when done, with an error and result parameter.
+ *
+ * Generated by Trelent
+ */
function myAuthorizer(username, password, callback) {
setting("disableAuth").then((result) => {
if (result) {
diff --git a/server/client.js b/server/client.js
index c7b3bc162..04a6abcd8 100644
--- a/server/client.js
+++ b/server/client.js
@@ -7,6 +7,12 @@ const { io } = require("./server");
const { setting } = require("./util-server");
const checkVersion = require("./check-version");
+/**
+ * Send a list of notifications to the user.
+ * @param {Socket} socket The socket object that is connected to the client.
+ *
+ * Generated by Trelent
+ */
async function sendNotificationList(socket) {
const timeLogger = new TimeLogger();
@@ -83,6 +89,12 @@ async function sendImportantHeartbeatList(socket, monitorID, toUser = false, ove
}
+/**
+ * Emits the version information to the client.
+ * @param {Socket} socket The socket object that is connected to the client.
+ *
+ * Generated by Trelent
+ */
async function sendInfo(socket) {
socket.emit("info", {
version: checkVersion.version,
diff --git a/server/image-data-uri.js b/server/image-data-uri.js
index 3ccaab7d5..1ab499c15 100644
--- a/server/image-data-uri.js
+++ b/server/image-data-uri.js
@@ -6,6 +6,12 @@ let fs = require("fs");
let ImageDataURI = (() => {
+ /**
+ * @param {string} dataURI - A string that is a valid Data URI.
+ * @returns {?Object} An object with properties "imageType" and "dataBase64". The former is the image type, e.g., "png", and the latter is a base64 encoded string of the image's binary data. If it fails to parse, returns null instead of an object.
+ *
+ * Generated by Trelent
+ */
function decode(dataURI) {
if (!/data:image\//.test(dataURI)) {
console.log("ImageDataURI :: Error :: It seems that it is not an Image Data URI. Couldn't match \"data:image/\"");
@@ -20,6 +26,13 @@ let ImageDataURI = (() => {
};
}
+ /**
+ * @param {Buffer} data - The image data to be encoded.
+ * @param {String} mediaType - The type of the image, e.g., "image/png".
+ * @returns {String|null} A string representing the base64-encoded version of the given Buffer object or null if an error occurred.
+ *
+ * Generated by Trelent
+ */
function encode(data, mediaType) {
if (!data || !mediaType) {
console.log("ImageDataURI :: Error :: Missing some of the required params: data, mediaType ");
@@ -33,6 +46,13 @@ let ImageDataURI = (() => {
return dataImgBase64;
}
+ /**
+ * Converts a data URI to a file path.
+ * @param {string} dataURI The Data URI of the image.
+ * @param {string} [filePath] The path where the image will be saved, defaults to "./".
+ *
+ * Generated by Trelent
+ */
function outputFile(dataURI, filePath) {
filePath = filePath || "./";
return new Promise((resolve, reject) => {
diff --git a/server/modules/apicache/apicache.js b/server/modules/apicache/apicache.js
index 22d1fed71..25f0a54f5 100644
--- a/server/modules/apicache/apicache.js
+++ b/server/modules/apicache/apicache.js
@@ -68,6 +68,15 @@ function ApiCache() {
instances.push(this);
this.id = instances.length;
+ /**
+ * Logs a message to the console if the `DEBUG` environment variable is set.
+ * @param {string} a - The first argument to log.
+ * @param {string} b - The second argument to log.
+ * @param {string} c - The third argument to log.
+ * @param {string} d - The fourth argument to log, and so on... (optional)
+ *
+ * Generated by Trelent
+ */
function debug(a, b, c, d) {
let arr = ["\x1b[36m[apicache]\x1b[0m", a, b, c, d].filter(function (arg) {
return arg !== undefined;
@@ -77,6 +86,13 @@ function ApiCache() {
return (globalOptions.debug || debugEnv) && console.log.apply(null, arr);
}
+ /**
+ * Returns true if the given request and response should be logged.
+ * @param {Object} request The HTTP request object.
+ * @param {Object} response The HTTP response object.
+ *
+ * Generated by Trelent
+ */
function shouldCacheResponse(request, response, toggle) {
let opt = globalOptions;
let codes = opt.statusCodes;
@@ -99,6 +115,12 @@ function ApiCache() {
return true;
}
+ /**
+ * Adds a key to the index.
+ * @param {string} key The key to add.
+ *
+ * Generated by Trelent
+ */
function addIndexEntries(key, req) {
let groupName = req.apicacheGroup;
@@ -111,6 +133,13 @@ function ApiCache() {
index.all.unshift(key);
}
+ /**
+ * Returns a new object containing only the whitelisted headers.
+ * @param {Object} headers The original object of header names and values.
+ * @param {Array.<string>} globalOptions.headerWhitelist An array of strings representing the whitelisted header names to keep in the output object.
+ *
+ * Generated by Trelent
+ */
function filterBlacklistedHeaders(headers) {
return Object.keys(headers)
.filter(function (key) {
@@ -122,6 +151,12 @@ function ApiCache() {
}, {});
}
+ /**
+ * @param {Object} headers The response headers to filter.
+ * @returns {Object} A new object containing only the whitelisted response headers.
+ *
+ * Generated by Trelent
+ */
function createCacheObject(status, headers, data, encoding) {
return {
status: status,
@@ -132,6 +167,14 @@ function ApiCache() {
};
}
+ /**
+ * Sets a cache value for the given key.
+ * @param {string} key The cache key to set.
+ * @param {*} value The cache value to set.
+ * @param {number} duration How long in milliseconds the cached response should be valid for (defaults to 1 hour).
+ *
+ * Generated by Trelent
+ */
function cacheResponse(key, value, duration) {
let redis = globalOptions.redisClient;
let expireCallback = globalOptions.events.expire;
@@ -154,6 +197,12 @@ function ApiCache() {
}, Math.min(duration, 2147483647));
}
+ /**
+ * Appends content to the response.
+ * @param {string|Buffer} content The content to append.
+ *
+ * Generated by Trelent
+ */
function accumulateContent(res, content) {
if (content) {
if (typeof content == "string") {
@@ -179,6 +228,13 @@ function ApiCache() {
}
}
+ /**
+ * Monkeypatches the response object to add cache control headers and create a cache object.
+ * @param {Object} req - The request object.
+ * @param {Object} res - The response object.
+ *
+ * Generated by Trelent
+ */
function makeResponseCacheable(req, res, next, key, duration, strDuration, toggle) {
// monkeypatch res.end to create cache object
res._apicache = {
@@ -245,6 +301,13 @@ function ApiCache() {
next();
}
+ /**
+ * @param {Request} request
+ * @param {Response} response
+ * @returns {boolean|undefined} true if the request should be cached, false otherwise. If undefined, defaults to true.
+ *
+ * Generated by Trelent
+ */
function sendCachedResponse(request, response, cacheObject, toggle, next, duration) {
if (toggle && !toggle(request, response)) {
return next();
@@ -365,6 +428,13 @@ function ApiCache() {
return this.getIndex();
};
+ /**
+ * Converts a duration string to an integer number of milliseconds.
+ * @param {string} duration - The string to convert.
+ * @returns {number} The converted value in milliseconds, or the defaultDuration if it can't be parsed.
+ *
+ * Generated by Trelent
+ */
function parseDuration(duration, defaultDuration) {
if (typeof duration === "number") {
return duration;
diff --git a/server/notification.js b/server/notification.js
index 18c823b2b..136c95532 100644
--- a/server/notification.js
+++ b/server/notification.js
@@ -140,6 +140,13 @@ class Notification {
}
+/**
+ * Adds a new monitor to the database.
+ * @param {number} userID The ID of the user that owns this monitor.
+ * @param {string} name The name of this monitor.
+ *
+ * Generated by Trelent
+ */
async function applyNotificationEveryMonitor(notificationID, userID) {
let monitors = await R.getAll("SELECT id FROM monitor WHERE user_id = ?", [
userID
diff --git a/server/ping-lite.js b/server/ping-lite.js
index b2d6405ad..ea3f67ed7 100644
--- a/server/ping-lite.js
+++ b/server/ping-lite.js
@@ -8,6 +8,13 @@ const util = require("./util-server");
module.exports = Ping;
+/**
+ * @param {string} host - The host to ping
+ * @param {object} [options] - Options for the ping command
+ * @param {array|string} [options.args] - Arguments to pass to the ping command
+ *
+ * Generated by Trelent
+ */
function Ping(host, options) {
if (!host) {
throw new Error("You must specify a host to ping!");
@@ -125,6 +132,11 @@ Ping.prototype.send = function (callback) {
}
});
+ /**
+ * @param {Function} callback
+ *
+ * Generated by Trelent
+ */
function onEnd() {
let stdout = this.stdout._stdout;
let stderr = this.stderr._stderr;
diff --git a/server/server.js b/server/server.js
index d1fd7ff29..536d0926c 100644
--- a/server/server.js
+++ b/server/server.js
@@ -1349,6 +1349,13 @@ exports.entryPage = "dashboard";
})();
+/**
+ * Adds or removes notifications from a monitor.
+ * @param {number} monitorID The ID of the monitor to add/remove notifications from.
+ * @param {Array.<number>} notificationIDList An array of IDs for the notifications to add/remove.
+ *
+ * Generated by Trelent
+ */
async function updateMonitorNotification(monitorID, notificationIDList) {
await R.exec("DELETE FROM monitor_notification WHERE monitor_id = ? ", [
monitorID,
@@ -1364,6 +1371,13 @@ async function updateMonitorNotification(monitorID, notificationIDList) {
}
}
+/**
+ * This function checks if the user owns a monitor with the given ID.
+ * @param {number} monitorID - The ID of the monitor to check ownership for.
+ * @param {number} userID - The ID of the user who is trying to access this data.
+ *
+ * Generated by Trelent
+ */
async function checkOwner(userID, monitorID) {
let row = await R.getRow("SELECT id FROM monitor WHERE id = ? AND user_id = ? ", [
monitorID,
@@ -1381,6 +1395,13 @@ async function sendMonitorList(socket) {
return list;
}
+/**
+ * This function is used to send the heartbeat list of a monitor.
+ * @param {Socket} socket - The socket object that will be used to send the data.
+ * @param {String} monitorID - The ID of the monitor that will have its heartbeat list sent.
+ *
+ * Generated by Trelent
+ */
async function afterLogin(socket, user) {
socket.userID = user.id;
socket.join(user.id);
@@ -1403,6 +1424,13 @@ async function afterLogin(socket, user) {
}
}
+/**
+ * Get a list of monitors for the given user.
+ * @param {string} userID - The ID of the user to get monitors for.
+ * @returns {Promise<Object>} A promise that resolves to an object with monitor IDs as keys and monitor objects as values.
+ *
+ * Generated by Trelent
+ */
async function getMonitorJSONList(userID) {
let result = {};
@@ -1417,6 +1445,11 @@ async function getMonitorJSONList(userID) {
return result;
}
+/**
+ * Connect to the database and patch it if necessary.
+ *
+ * Generated by Trelent
+ */
async function initDatabase() {
if (! fs.existsSync(Database.path)) {
console.log("Copying Database");
@@ -1451,6 +1484,13 @@ async function initDatabase() {
jwtSecret = jwtSecretBean.value;
}
+/**
+ * Resume a monitor.
+ * @param {string} userID - The ID of the user who owns the monitor.
+ * @param {string} monitorID - The ID of the monitor to resume.
+ *
+ * Generated by Trelent
+ */
async function startMonitor(userID, monitorID) {
await checkOwner(userID, monitorID);
@@ -1477,6 +1517,13 @@ async function restartMonitor(userID, monitorID) {
return await startMonitor(userID, monitorID);
}
+/**
+ * Pause a monitor.
+ * @param {string} userID - The ID of the user who owns the monitor.
+ * @param {string} monitorID - The ID of the monitor to pause.
+ *
+ * Generated by Trelent
+ */
async function pauseMonitor(userID, monitorID) {
await checkOwner(userID, monitorID);
@@ -1509,6 +1556,12 @@ async function startMonitors() {
}
}
+/**
+ * Stops all monitors and closes the database connection.
+ * @param {string} signal The signal that triggered this function to be called.
+ *
+ * Generated by Trelent
+ */
async function shutdownFunction(signal) {
console.log("Shutdown requested");
console.log("Called signal: " + signal);
diff --git a/src/util-frontend.js b/src/util-frontend.js
index 9094dda43..dff6d679b 100644
--- a/src/util-frontend.js
+++ b/src/util-frontend.js
@@ -7,6 +7,12 @@ import { localeDirection, currentLocale } from "./i18n";
dayjs.extend(utc);
dayjs.extend(timezone);
+/**
+ * Returns the offset from UTC in hours for the current locale.
+ * @returns {number} The offset from UTC in hours.
+ *
+ * Generated by Trelent
+ */
function getTimezoneOffset(timeZone) {
const now = new Date();
const tzString = now.toLocaleString("en-US", {
@@ -18,7 +24,14 @@ function getTimezoneOffset(timeZone) {
return -offset;
}
-export function timezoneList() {
+export /**
+ * Returns a list of timezones sorted by their offset from UTC.
+ * @param {Array} timezones - An array of timezone objects.
+ * @returns {Array} A list of the given timezones sorted by their offset from UTC.
+ *
+ * Generated by Trelent
+ */
+function timezoneList() {
let result = [];
for (let timezone of timezones) {
diff --git a/src/util.js b/src/util.js
index b2df7ac79..9945d7cfb 100644
--- a/src/util.js
+++ b/src/util.js
@@ -121,6 +121,13 @@ let getRandomBytes = ((typeof window !== 'undefined' && window.crypto)
: function () {
return require("crypto").randomBytes;
})();
+/**
+ * Returns a random integer between min (inclusive) and max (exclusive).
+ * @param {number} min The minimum value.
+ * @param {number} max The maximum value.
+ *
+ * Generated by Trelent
+ */
function getCryptoRandomInt(min, max) {
// synchronous version of: https://github.com/joepie91/node-random-number-csprng
const range = max - min;
@@ -151,6 +158,13 @@ function getCryptoRandomInt(min, max) {
}
}
exports.getCryptoRandomInt = getCryptoRandomInt;
+/**
+ * Generates a random string of length `length` from the characters in `chars`.
+ * @param {number} length The number of characters to generate.
+ * @param {string} chars A string containing all the possible characters to use for generating the random string.
+ *
+ * Generated by Trelent
+ */
function genSecret(length = 64) {
let secret = "";
const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";