Generated documentation :)

This commit is contained in:
Calum Bird 2021-11-09 21:24:31 -08:00
parent 5df34cd137
commit f55350bebc
11 changed files with 234 additions and 1 deletions

View File

@ -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);

View File

@ -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";

View File

@ -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) {

View File

@ -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,

View File

@ -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) => {

View File

@ -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;

View File

@ -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

View File

@ -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;

View File

@ -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);

View File

@ -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) {

View File

@ -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";