From 8a92054c2b564b4119f92031ec4ee8c3b181eabb Mon Sep 17 00:00:00 2001 From: Matthew Nickson Date: Fri, 11 Aug 2023 09:46:41 +0200 Subject: [PATCH] Added JSDoc to ESLint (#3529) * Added JSDoc to eslint rules Signed-off-by: Matthew Nickson * Fixed JSDoc eslint errors Signed-off-by: Matthew Nickson * Update the check-linters workflow to Node.js 20 --------- Signed-off-by: Matthew Nickson Co-authored-by: Louis Lam --- .eslintrc.js | 41 ++++- .github/workflows/auto-test.yml | 4 +- extra/beta/update-version.js | 4 + extra/download-dist.js | 1 + extra/fs-rmSync.js | 4 +- extra/simple-dns-server.js | 2 +- extra/simple-mqtt-server.js | 8 +- extra/update-language-files/index.js | 4 +- extra/update-version.js | 4 + extra/update-wiki-version.js | 2 + package-lock.json | 104 ++++++++++++ package.json | 1 + server/auth.js | 27 ++-- server/cacheable-dns-http-agent.js | 10 +- server/client.js | 16 +- server/database.js | 26 +-- server/docker.js | 17 +- server/google-analytics.js | 4 +- server/image-data-uri.js | 6 +- server/jobs.js | 5 +- server/jobs/clear-old-data.js | 2 +- server/jobs/incremental-vacuum.js | 2 +- server/model/api_key.js | 8 +- server/model/docker_host.js | 2 +- server/model/group.js | 12 +- server/model/heartbeat.js | 4 +- server/model/incident.js | 2 +- server/model/maintenance.js | 34 +++- server/model/monitor.js | 109 ++++++++----- server/model/proxy.js | 2 +- server/model/status_page.js | 34 ++-- server/model/tag.js | 2 +- server/model/user.js | 4 +- server/monitor-types/monitor-type.js | 8 +- .../real-browser-monitor-type.js | 32 +++- server/monitor-types/tailscale-ping.js | 18 +-- server/notification-providers/alerta.js | 3 + server/notification-providers/alertnow.js | 3 + server/notification-providers/aliyun-sms.js | 9 +- server/notification-providers/apprise.js | 3 + server/notification-providers/bark.js | 12 +- server/notification-providers/clicksendsms.js | 3 + server/notification-providers/dingding.js | 11 +- server/notification-providers/discord.js | 3 + server/notification-providers/feishu.js | 3 + server/notification-providers/flashduty.js | 13 +- server/notification-providers/freemobile.js | 3 + server/notification-providers/goalert.js | 3 + server/notification-providers/google-chat.js | 3 + server/notification-providers/gorush.js | 3 + server/notification-providers/gotify.js | 3 + .../notification-providers/home-assistant.js | 3 + server/notification-providers/kook.js | 3 + server/notification-providers/line.js | 3 + server/notification-providers/linenotify.js | 3 + server/notification-providers/lunasea.js | 3 + server/notification-providers/matrix.js | 3 + server/notification-providers/mattermost.js | 3 + server/notification-providers/nostr.js | 13 ++ .../notification-provider.js | 9 +- server/notification-providers/ntfy.js | 3 + server/notification-providers/octopush.js | 3 + server/notification-providers/onebot.js | 3 + server/notification-providers/opsgenie.js | 8 +- server/notification-providers/pagerduty.js | 7 +- server/notification-providers/pagertree.js | 8 +- server/notification-providers/promosms.js | 3 + server/notification-providers/pushbullet.js | 3 + server/notification-providers/pushdeer.js | 3 + server/notification-providers/pushover.js | 3 + server/notification-providers/pushy.js | 3 + server/notification-providers/rocket-chat.js | 3 + server/notification-providers/serverchan.js | 7 +- server/notification-providers/serwersms.js | 3 + server/notification-providers/signal.js | 3 + server/notification-providers/slack.js | 5 + server/notification-providers/smsc.js | 3 + server/notification-providers/smseagle.js | 3 + server/notification-providers/smsmanager.js | 3 + server/notification-providers/smtp.js | 3 + server/notification-providers/splunk.js | 7 +- server/notification-providers/squadcast.js | 3 + server/notification-providers/stackfield.js | 3 + server/notification-providers/teams.js | 19 ++- .../notification-providers/techulus-push.js | 3 + server/notification-providers/telegram.js | 3 + server/notification-providers/twilio.js | 3 + server/notification-providers/webhook.js | 3 + server/notification-providers/wecom.js | 7 +- server/notification-providers/zoho-cliq.js | 17 +- server/notification.js | 17 +- server/password-hash.js | 15 +- server/prometheus.js | 12 +- server/proxy.js | 31 ++-- server/rate-limiter.js | 14 +- server/server.js | 18 ++- server/settings.js | 13 +- .../socket-handlers/api-key-socket-handler.js | 3 +- .../cloudflared-socket-handler.js | 11 +- .../database-socket-handler.js | 1 + .../socket-handlers/docker-socket-handler.js | 1 + .../socket-handlers/general-socket-handler.js | 2 +- .../maintenance-socket-handler.js | 1 + .../socket-handlers/proxy-socket-handler.js | 1 + .../status-page-socket-handler.js | 3 + server/uptime-cache-list.js | 14 +- server/uptime-kuma-server.js | 56 +++++-- server/util-server.js | 150 ++++++++++-------- src/components/APIKeyDialog.vue | 11 +- src/components/BadgeGeneratorDialog.vue | 5 +- src/components/CertificateInfoRow.vue | 4 +- src/components/Confirm.vue | 11 +- src/components/CopyableInput.vue | 12 +- src/components/CreateGroupDialog.vue | 9 +- src/components/DockerHostDialog.vue | 23 ++- src/components/HeartbeatBar.vue | 10 +- src/components/HiddenInput.vue | 10 +- src/components/Login.vue | 5 +- src/components/MonitorList.vue | 36 ++++- src/components/MonitorListItem.vue | 5 +- src/components/MonitorSettingDialog.vue | 12 +- src/components/NotificationDialog.vue | 24 ++- src/components/ProxyDialog.vue | 16 +- src/components/PublicGroupList.vue | 18 ++- src/components/Tag.vue | 7 +- src/components/TagEditDialog.vue | 10 +- src/components/TagsManager.vue | 52 ++++-- src/components/TwoFADialog.vue | 40 ++++- src/components/notifications/Telegram.vue | 8 +- src/components/notifications/index.js | 1 - src/components/settings/APIKeys.vue | 11 +- src/components/settings/Backup.vue | 8 +- src/components/settings/General.vue | 15 +- src/components/settings/MonitorHistory.vue | 20 ++- src/components/settings/Notifications.vue | 2 + src/components/settings/ReverseProxy.vue | 15 +- src/components/settings/Security.vue | 20 ++- src/components/settings/Tags.vue | 2 +- src/mixins/datetime.js | 23 +-- src/mixins/lang.js | 6 +- src/mixins/mobile.js | 10 +- src/mixins/socket.js | 129 +++++++++------ src/mixins/theme.js | 5 +- src/pages/AddStatusPage.vue | 5 +- src/pages/Details.vue | 60 +++++-- src/pages/EditMaintenance.vue | 20 ++- src/pages/EditMonitor.vue | 22 ++- src/pages/MaintenanceDetails.vue | 15 +- src/pages/ManageMaintenance.vue | 17 +- src/pages/NotFound.vue | 5 +- src/pages/Settings.vue | 16 +- src/pages/StatusPage.vue | 93 ++++++++--- src/util-frontend.js | 34 ++-- 153 files changed, 1505 insertions(+), 574 deletions(-) diff --git a/.eslintrc.js b/.eslintrc.js index 4713799d..d9d3e4c2 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -14,6 +14,7 @@ module.exports = { extends: [ "eslint:recommended", "plugin:vue/vue3-recommended", + "plugin:jsdoc/recommended-error", ], parser: "vue-eslint-parser", parserOptions: { @@ -21,6 +22,9 @@ module.exports = { sourceType: "module", requireConfigFile: false, }, + plugins: [ + "jsdoc" + ], rules: { "yoda": "error", eqeqeq: [ "warn", "smart" ], @@ -97,7 +101,42 @@ module.exports = { }], "no-control-regex": "off", "one-var": [ "error", "never" ], - "max-statements-per-line": [ "error", { "max": 1 }] + "max-statements-per-line": [ "error", { "max": 1 }], + "jsdoc/check-tag-names": [ + "error", + { + "definedTags": [ "link" ] + } + ], + "jsdoc/no-undefined-types": "off", + "jsdoc/no-defaults": [ + "error", + { "noOptionalParamNames": true } + ], + "jsdoc/require-throws": "error", + "jsdoc/require-jsdoc": [ + "error", + { + "require": { + "FunctionDeclaration": true, + "MethodDefinition": true, + } + } + ], + "jsdoc/no-blank-block-descriptions": "error", + "jsdoc/require-returns-check": [ + "error", + { "reportMissingReturnForUndefinedTypes": false } + ], + "jsdoc/require-returns": [ + "error", + { + "forceRequireReturn": true, + "forceReturnsWithAsync": true + } + ], + "jsdoc/require-param-type": "error", + "jsdoc/require-param-description": "error" }, "overrides": [ { diff --git a/.github/workflows/auto-test.yml b/.github/workflows/auto-test.yml index 161c5bc5..ee01a3ad 100644 --- a/.github/workflows/auto-test.yml +++ b/.github/workflows/auto-test.yml @@ -71,10 +71,10 @@ jobs: - run: git config --global core.autocrlf false # Mainly for Windows - uses: actions/checkout@v3 - - name: Use Node.js 14 + - name: Use Node.js 20 uses: actions/setup-node@v3 with: - node-version: 14 + node-version: 20 - run: npm install - run: npm run lint diff --git a/extra/beta/update-version.js b/extra/beta/update-version.js index 3dafbe8d..d8e626d0 100644 --- a/extra/beta/update-version.js +++ b/extra/beta/update-version.js @@ -36,6 +36,8 @@ if (! exists) { /** * Commit updated files * @param {string} version Version to update to + * @returns {void} + * @throws Error committing files */ function commit(version) { let msg = "Update to " + version; @@ -55,6 +57,7 @@ function commit(version) { /** * Create a tag with the specified version * @param {string} version Tag to create + * @returns {void} */ function tag(version) { let res = childProcess.spawnSync("git", [ "tag", version ]); @@ -68,6 +71,7 @@ function tag(version) { * Check if a tag exists for the specified version * @param {string} version Version to check * @returns {boolean} Does the tag already exist + * @throws Version is not valid */ function tagExists(version) { if (! version) { diff --git a/extra/download-dist.js b/extra/download-dist.js index a854ca8b..b8be5eb8 100644 --- a/extra/download-dist.js +++ b/extra/download-dist.js @@ -15,6 +15,7 @@ download(url); /** * Downloads the latest version of the dist from a GitHub release. * @param {string} url The URL to download from. + * @returns {void} * * Generated by Trelent */ diff --git a/extra/fs-rmSync.js b/extra/fs-rmSync.js index aa45b6dc..0fdbab93 100644 --- a/extra/fs-rmSync.js +++ b/extra/fs-rmSync.js @@ -4,12 +4,12 @@ const fs = require("fs"); * to avoid the runtime deprecation warning triggered for using `fs.rmdirSync` with `{ recursive: true }` in Node.js v16, * or the `recursive` property removing completely in the future Node.js version. * See the link below. - * * @todo Once we drop the support for Node.js v14 (or at least versions before v14.14.0), we can safely replace this function with `fs.rmSync`, since `fs.rmSync` was add in Node.js v14.14.0 and currently we supports all the Node.js v14 versions that include the versions before the v14.14.0, and this function have almost the same signature with `fs.rmSync`. * @link https://nodejs.org/docs/latest-v16.x/api/deprecations.html#dep0147-fsrmdirpath--recursive-true- the deprecation infomation of `fs.rmdirSync` * @link https://nodejs.org/docs/latest-v16.x/api/fs.html#fsrmsyncpath-options the document of `fs.rmSync` * @param {fs.PathLike} path Valid types for path values in "fs". - * @param {fs.RmDirOptions} [options] options for `fs.rmdirSync`, if `fs.rmSync` is available and property `recursive` is true, it will automatically have property `force` with value `true`. + * @param {fs.RmDirOptions} options options for `fs.rmdirSync`, if `fs.rmSync` is available and property `recursive` is true, it will automatically have property `force` with value `true`. + * @returns {void} */ const rmSync = (path, options) => { if (typeof fs.rmSync === "function") { diff --git a/extra/simple-dns-server.js b/extra/simple-dns-server.js index a6946dcb..38bf74f6 100644 --- a/extra/simple-dns-server.js +++ b/extra/simple-dns-server.js @@ -138,7 +138,7 @@ server.listen({ /** * Get human readable request type from request code * @param {number} code Request code to translate - * @returns {string} Human readable request type + * @returns {string|void} Human readable request type */ function type(code) { for (let name in Packet.TYPE) { diff --git a/extra/simple-mqtt-server.js b/extra/simple-mqtt-server.js index b970a380..66ebfe4d 100644 --- a/extra/simple-mqtt-server.js +++ b/extra/simple-mqtt-server.js @@ -7,11 +7,17 @@ class SimpleMqttServer { aedes = require("aedes")(); server = require("net").createServer(this.aedes.handle); + /** + * @param {number} port Port to listen on + */ constructor(port) { this.port = port; } - /** Start the MQTT server */ + /** + * Start the MQTT server + * @returns {void} + */ start() { this.server.listen(this.port, () => { console.log("server started and listening on port ", this.port); diff --git a/extra/update-language-files/index.js b/extra/update-language-files/index.js index 078c4e6f..5b748a98 100644 --- a/extra/update-language-files/index.js +++ b/extra/update-language-files/index.js @@ -12,6 +12,7 @@ import rmSync from "../fs-rmSync.js"; * created with this code if one does not already exist * @param {string} baseLang The second base language file to copy. This * will be ignored if set to "en" as en.js is copied by default + * @returns {void} */ function copyFiles(langCode, baseLang) { if (fs.existsSync("./languages")) { @@ -33,7 +34,8 @@ function copyFiles(langCode, baseLang) { /** * Update the specified language file * @param {string} langCode Language code to update - * @param {string} baseLang Second language to copy keys from + * @param {string} baseLangCode Second language to copy keys from + * @returns {void} */ async function updateLanguage(langCode, baseLangCode) { const en = (await import("./languages/en.js")).default; diff --git a/extra/update-version.js b/extra/update-version.js index 8d78f17d..2bc13a78 100644 --- a/extra/update-version.js +++ b/extra/update-version.js @@ -39,6 +39,8 @@ if (! exists) { /** * Commit updated files * @param {string} version Version to update to + * @returns {void} + * @throws Error when committing files */ function commit(version) { let msg = "Update to " + version; @@ -55,6 +57,7 @@ function commit(version) { /** * Create a tag with the specified version * @param {string} version Tag to create + * @returns {void} */ function tag(version) { let res = childProcess.spawnSync("git", [ "tag", version ]); @@ -65,6 +68,7 @@ function tag(version) { * Check if a tag exists for the specified version * @param {string} version Version to check * @returns {boolean} Does the tag already exist + * @throws Version is not valid */ function tagExists(version) { if (! version) { diff --git a/extra/update-wiki-version.js b/extra/update-wiki-version.js index f551db41..003deec0 100644 --- a/extra/update-wiki-version.js +++ b/extra/update-wiki-version.js @@ -13,6 +13,7 @@ updateWiki(newVersion); /** * Update the wiki with new version number * @param {string} newVersion Version to update to + * @returns {void} */ function updateWiki(newVersion) { const wikiDir = "./tmp/wiki"; @@ -46,6 +47,7 @@ function updateWiki(newVersion) { /** * Check if a directory exists and then delete it * @param {string} dir Directory to delete + * @returns {void} */ function safeDelete(dir) { if (fs.existsSync(dir)) { diff --git a/package-lock.json b/package-lock.json index 0d6fc83b..7db707f4 100644 --- a/package-lock.json +++ b/package-lock.json @@ -103,6 +103,7 @@ "dns2": "~2.0.1", "dompurify": "~2.4.3", "eslint": "~8.14.0", + "eslint-plugin-jsdoc": "^46.4.6", "eslint-plugin-vue": "~8.7.1", "favico.js": "~0.3.10", "jest": "~29.6.1", @@ -3456,6 +3457,20 @@ "ms": "^2.1.1" } }, + "node_modules/@es-joy/jsdoccomment": { + "version": "0.40.1", + "resolved": "https://registry.npmjs.org/@es-joy/jsdoccomment/-/jsdoccomment-0.40.1.tgz", + "integrity": "sha512-YORCdZSusAlBrFpZ77pJjc5r1bQs5caPWtAu+WWmiSo+8XaUzseapVrfAtiRFbQWnrBxxLLEwF6f6ZG/UgCQCg==", + "dev": true, + "dependencies": { + "comment-parser": "1.4.0", + "esquery": "^1.5.0", + "jsdoc-type-pratt-parser": "~4.0.0" + }, + "engines": { + "node": ">=16" + } + }, "node_modules/@esbuild/android-arm": { "version": "0.18.20", "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.18.20.tgz", @@ -6227,6 +6242,15 @@ } ] }, + "node_modules/are-docs-informative": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/are-docs-informative/-/are-docs-informative-0.0.2.tgz", + "integrity": "sha512-ixiS0nLNNG5jNQzgZJNoUpBKdo9yTYZMGJ+QgT2jmjR7G7+QHRCc4v6LQ3NgE7EBJq+o0ams3waJwkrlBom8Ig==", + "dev": true, + "engines": { + "node": ">=14" + } + }, "node_modules/are-we-there-yet": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/are-we-there-yet/-/are-we-there-yet-2.0.0.tgz", @@ -6992,6 +7016,18 @@ "node": ">=10.0.0" } }, + "node_modules/builtin-modules": { + "version": "3.3.0", + "resolved": "https://registry.npmjs.org/builtin-modules/-/builtin-modules-3.3.0.tgz", + "integrity": "sha512-zhaCDicdLuWN5UbN5IMnFqNMhNfo919sH85y2/ea+5Yg9TsTkeZxpL+JLbp6cgYFS4sRLp3YV4S6yDuqVWHYOw==", + "dev": true, + "engines": { + "node": ">=6" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/bulk-write-stream": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/bulk-write-stream/-/bulk-write-stream-2.0.1.tgz", @@ -7533,6 +7569,15 @@ "node": ">= 6" } }, + "node_modules/comment-parser": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/comment-parser/-/comment-parser-1.4.0.tgz", + "integrity": "sha512-QLyTNiZ2KDOibvFPlZ6ZngVsZ/0gYnE6uTXi5aoDg8ed3AkJAz4sEje3Y8a29hQ1s6A99MZXe47fLAXQ1rTqaw==", + "dev": true, + "engines": { + "node": ">= 12.0.0" + } + }, "node_modules/commist": { "version": "1.1.0", "resolved": "https://registry.npmjs.org/commist/-/commist-1.1.0.tgz", @@ -8967,6 +9012,41 @@ "url": "https://opencollective.com/eslint" } }, + "node_modules/eslint-plugin-jsdoc": { + "version": "46.4.6", + "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-46.4.6.tgz", + "integrity": "sha512-z4SWYnJfOqftZI+b3RM9AtWL1vF/sLWE/LlO9yOKDof9yN2+n3zOdOJTGX/pRE/xnPsooOLG2Rq6e4d+XW3lNw==", + "dev": true, + "dependencies": { + "@es-joy/jsdoccomment": "~0.40.1", + "are-docs-informative": "^0.0.2", + "comment-parser": "1.4.0", + "debug": "^4.3.4", + "escape-string-regexp": "^4.0.0", + "esquery": "^1.5.0", + "is-builtin-module": "^3.2.1", + "semver": "^7.5.4", + "spdx-expression-parse": "^3.0.1" + }, + "engines": { + "node": ">=16" + }, + "peerDependencies": { + "eslint": "^7.0.0 || ^8.0.0" + } + }, + "node_modules/eslint-plugin-jsdoc/node_modules/escape-string-regexp": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz", + "integrity": "sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==", + "dev": true, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/eslint-plugin-vue": { "version": "8.7.1", "resolved": "https://registry.npmjs.org/eslint-plugin-vue/-/eslint-plugin-vue-8.7.1.tgz", @@ -10845,6 +10925,21 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/is-builtin-module": { + "version": "3.2.1", + "resolved": "https://registry.npmjs.org/is-builtin-module/-/is-builtin-module-3.2.1.tgz", + "integrity": "sha512-BSLE3HnV2syZ0FK0iMA/yUGplUeMmNz4AW5fnTunbCIqZi4vG3WjJT9FHMy5D69xmAYBHXQhJdALdpwVxV501A==", + "dev": true, + "dependencies": { + "builtin-modules": "^3.3.0" + }, + "engines": { + "node": ">=6" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/is-callable": { "version": "1.2.7", "resolved": "https://registry.npmjs.org/is-callable/-/is-callable-1.2.7.tgz", @@ -13025,6 +13120,15 @@ "integrity": "sha512-UVU9dibq2JcFWxQPA6KCqj5O42VOmAY3zQUfEKxU0KpTGXwNoCjkX1e13eHNvw/xPynt6pU0rZ1htjWTNTSXsg==", "dev": true }, + "node_modules/jsdoc-type-pratt-parser": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-4.0.0.tgz", + "integrity": "sha512-YtOli5Cmzy3q4dP26GraSOeAhqecewG04hoO8DY56CH4KJ9Fvv5qKWUCCo3HZob7esJQHCv6/+bnTy72xZZaVQ==", + "dev": true, + "engines": { + "node": ">=12.0.0" + } + }, "node_modules/jsesc": { "version": "3.0.2", "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-3.0.2.tgz", diff --git a/package.json b/package.json index 400f0782..38ea7249 100644 --- a/package.json +++ b/package.json @@ -165,6 +165,7 @@ "dns2": "~2.0.1", "dompurify": "~2.4.3", "eslint": "~8.14.0", + "eslint-plugin-jsdoc": "^46.4.6", "eslint-plugin-vue": "~8.7.1", "favico.js": "~0.3.10", "jest": "~29.6.1", diff --git a/server/auth.js b/server/auth.js index 1ea8b45f..5cf96b6f 100644 --- a/server/auth.js +++ b/server/auth.js @@ -9,9 +9,9 @@ const dayjs = require("dayjs"); /** * Login to web app - * @param {string} username - * @param {string} password - * @returns {Promise<(Bean|null)>} + * @param {string} username Username to login with + * @param {string} password Password to login with + * @returns {Promise<(Bean|null)>} User or null if login failed */ exports.login = async function (username, password) { if (typeof username !== "string" || typeof password !== "string") { @@ -39,6 +39,7 @@ exports.login = async function (username, password) { /** * Validate a provided API key * @param {string} key API key to verify + * @returns {boolean} API is ok? */ async function verifyAPIKey(key) { if (typeof key !== "string") { @@ -73,9 +74,10 @@ async function verifyAPIKey(key) { /** * Custom authorizer for express-basic-auth - * @param {string} username - * @param {string} password - * @param {authCallback} callback + * @param {string} username Username to login with + * @param {string} password Password to login with + * @param {authCallback} callback Callback to handle login result + * @returns {void} */ function apiAuthorizer(username, password, callback) { // API Rate Limit @@ -99,9 +101,10 @@ function apiAuthorizer(username, password, callback) { /** * Custom authorizer for express-basic-auth - * @param {string} username - * @param {string} password - * @param {authCallback} callback + * @param {string} username Username to login with + * @param {string} password Password to login with + * @param {authCallback} callback Callback to handle login result + * @returns {void} */ function userAuthorizer(username, password, callback) { // Login Rate Limit @@ -126,7 +129,8 @@ function userAuthorizer(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 + * @param {express.NextFunction} next Next handler in chain + * @returns {void} */ exports.basicAuth = async function (req, res, next) { const middleware = basicAuth({ @@ -148,7 +152,8 @@ exports.basicAuth = async function (req, res, next) { * Use use API Key if API keys enabled, else use basic auth * @param {express.Request} req Express request object * @param {express.Response} res Express response object - * @param {express.NextFunction} next + * @param {express.NextFunction} next Next handler in chain + * @returns {void} */ exports.apiAuth = async function (req, res, next) { if (!await Settings.get("disableAuth")) { diff --git a/server/cacheable-dns-http-agent.js b/server/cacheable-dns-http-agent.js index cc067f72..bcc95568 100644 --- a/server/cacheable-dns-http-agent.js +++ b/server/cacheable-dns-http-agent.js @@ -15,6 +15,7 @@ class CacheableDnsHttpAgent { /** * Register/Disable cacheable to global agents + * @returns {void} */ static async update() { log.debug("CacheableDnsHttpAgent", "update"); @@ -40,14 +41,15 @@ class CacheableDnsHttpAgent { /** * Attach cacheable to HTTP agent * @param {http.Agent} agent Agent to install + * @returns {void} */ static install(agent) { this.cacheable.install(agent); } /** - * @var {https.AgentOptions} agentOptions - * @return {https.Agent} + * @param {https.AgentOptions} agentOptions Options to pass to HTTPS agent + * @returns {https.Agent} The new HTTPS agent */ static getHttpsAgent(agentOptions) { if (!this.enable) { @@ -63,8 +65,8 @@ class CacheableDnsHttpAgent { } /** - * @var {http.AgentOptions} agentOptions - * @return {https.Agents} + * @param {http.AgentOptions} agentOptions Options to pass to the HTTP agent + * @returns {https.Agents} The new HTTP agent */ static getHttpAgent(agentOptions) { if (!this.enable) { diff --git a/server/client.js b/server/client.js index 2e3bd43b..e00fdb1e 100644 --- a/server/client.js +++ b/server/client.js @@ -12,7 +12,7 @@ const checkVersion = require("./check-version"); /** * Send list of notification providers to client * @param {Socket} socket Socket.io socket instance - * @returns {Promise} + * @returns {Promise} List of notifications */ async function sendNotificationList(socket) { const timeLogger = new TimeLogger(); @@ -40,8 +40,8 @@ async function sendNotificationList(socket) { * Send Heartbeat History list to socket * @param {Socket} socket Socket.io instance * @param {number} monitorID ID of monitor to send heartbeat history - * @param {boolean} [toUser=false] True = send to all browsers with the same user id, False = send to the current browser only - * @param {boolean} [overwrite=false] Overwrite client-side's heartbeat list + * @param {boolean} toUser True = send to all browsers with the same user id, False = send to the current browser only + * @param {boolean} overwrite Overwrite client-side's heartbeat list * @returns {Promise} */ async function sendHeartbeatList(socket, monitorID, toUser = false, overwrite = false) { @@ -71,8 +71,8 @@ async function sendHeartbeatList(socket, monitorID, toUser = false, overwrite = * Important Heart beat list (aka event list) * @param {Socket} socket Socket.io instance * @param {number} monitorID ID of monitor to send heartbeat history - * @param {boolean} [toUser=false] True = send to all browsers with the same user id, False = send to the current browser only - * @param {boolean} [overwrite=false] Overwrite client-side's heartbeat list + * @param {boolean} toUser True = send to all browsers with the same user id, False = send to the current browser only + * @param {boolean} overwrite Overwrite client-side's heartbeat list * @returns {Promise} */ async function sendImportantHeartbeatList(socket, monitorID, toUser = false, overwrite = false) { @@ -100,7 +100,7 @@ async function sendImportantHeartbeatList(socket, monitorID, toUser = false, ove /** * Emit proxy list to client * @param {Socket} socket Socket.io socket instance - * @return {Promise} + * @returns {Promise} List of proxies */ async function sendProxyList(socket) { const timeLogger = new TimeLogger(); @@ -141,7 +141,7 @@ async function sendAPIKeyList(socket) { /** * Emits the version information to the client. * @param {Socket} socket Socket.io socket instance - * @param {boolean} hideVersion + * @param {boolean} hideVersion Should we hide the version information in the response? * @returns {Promise} */ async function sendInfo(socket, hideVersion = false) { @@ -165,7 +165,7 @@ async function sendInfo(socket, hideVersion = false) { /** * Send list of docker hosts to client * @param {Socket} socket Socket.io socket instance - * @returns {Promise} + * @returns {Promise} List of docker hosts */ async function sendDockerHostList(socket) { const timeLogger = new TimeLogger(); diff --git a/server/database.js b/server/database.js index 30d7879d..e9df008e 100644 --- a/server/database.js +++ b/server/database.js @@ -101,7 +101,8 @@ class Database { /** * Initialize the data directory - * @param {Object} args Arguments to initialize DB with + * @param {object} args Arguments to initialize DB with + * @returns {void} */ static initDataDir(args) { // Data Directory (must be end with "/") @@ -154,11 +155,11 @@ class Database { /** * Connect to the database - * @param {boolean} [testMode=false] Should the connection be + * @param {boolean} testMode Should the connection be * started in test mode? - * @param {boolean} [autoloadModels=true] Should models be + * @param {boolean} autoloadModels Should models be * automatically loaded? - * @param {boolean} [noLog=false] Should logs not be output? + * @param {boolean} noLog Should logs not be output? * @returns {Promise} */ static async connect(testMode = false, autoloadModels = true, noLog = false) { @@ -312,6 +313,10 @@ class Database { } } + /** + * Patch the database + * @returns {void} + */ static async patch() { // Still need to keep this for old versions of Uptime Kuma if (Database.dbConfig.type === "sqlite") { @@ -497,8 +502,8 @@ class Database { * Patch database using new patching process * Used it patch2() only * @private - * @param sqlFilename - * @param databasePatchedFiles + * @param {string} sqlFilename Name of SQL file to load + * @param {object} databasePatchedFiles Patch status of database files * @returns {Promise} */ static async patch2Recursion(sqlFilename, databasePatchedFiles) { @@ -533,7 +538,7 @@ class Database { /** * Load an SQL file and execute it - * @param filename Filename of SQL file to import + * @param {string} filename Filename of SQL file to import * @returns {Promise} */ static async importSQLFile(filename) { @@ -567,7 +572,7 @@ class Database { /** * Aquire a direct connection to database - * @returns {any} + * @returns {any} Database connection */ static getBetterSQLite3Database() { return R.knex.client.acquireConnection(); @@ -604,7 +609,10 @@ class Database { process.removeListener("unhandledRejection", listener); } - /** Get the size of the database */ + /** + * Get the size of the database + * @returns {number} Size of database + */ static getSize() { log.debug("db", "Database.getSize()"); let stats = fs.statSync(Database.sqlitePath); diff --git a/server/docker.js b/server/docker.js index 1a8c0a5d..18346e08 100644 --- a/server/docker.js +++ b/server/docker.js @@ -14,10 +14,10 @@ class DockerHost { /** * Save a docker host - * @param {Object} dockerHost Docker host to save + * @param {object} dockerHost Docker host to save * @param {?number} dockerHostID ID of the docker host to update * @param {number} userID ID of the user who adds the docker host - * @returns {Promise} + * @returns {Promise} Updated docker host */ static async save(dockerHost, dockerHostID, userID) { let bean; @@ -64,7 +64,7 @@ class DockerHost { /** * Fetches the amount of containers on the Docker host - * @param {Object} dockerHost Docker host to check for + * @param {object} dockerHost Docker host to check for * @returns {number} Total amount of containers on the host */ static async testDockerHost(dockerHost) { @@ -108,6 +108,8 @@ class DockerHost { /** * Since axios 0.27.X, it does not accept `tcp://` protocol. * Change it to `http://` on the fly in order to fix it. (https://github.com/louislam/uptime-kuma/issues/2165) + * @param {any} url URL to fix + * @returns {any} URL with tcp:// replaced by http:// */ static patchDockerURL(url) { if (typeof url === "string") { @@ -129,11 +131,10 @@ class DockerHost { * 'data/docker-tls/example.com/' would be searched for certificate files), * then 'ca.pem', 'key.pem' and 'cert.pem' files are included in the agent options. * File names can also be overridden via 'DOCKER_TLS_FILE_NAME_(CA|KEY|CERT)'. - * - * @param {String} dockerType i.e. "tcp" or "socket" - * @param {String} url The docker host URL rewritten to https:// - * @return {Object} - * */ + * @param {string} dockerType i.e. "tcp" or "socket" + * @param {string} url The docker host URL rewritten to https:// + * @returns {object} HTTP agent options + */ static getHttpsAgentOptions(dockerType, url) { let baseOptions = { maxCachedSessions: 0, diff --git a/server/google-analytics.js b/server/google-analytics.js index fc9fbec8..ceae7d2e 100644 --- a/server/google-analytics.js +++ b/server/google-analytics.js @@ -3,8 +3,8 @@ const jsesc = require("jsesc"); /** * Returns a string that represents the javascript that is required to insert the Google Analytics scripts * into a webpage. - * @param tagId Google UA/G/AW/DC Property ID to use with the Google Analytics script. - * @returns {string} + * @param {string} tagId Google UA/G/AW/DC Property ID to use with the Google Analytics script. + * @returns {string} HTML script tags to inject into page */ function getGoogleAnalyticsScript(tagId) { let escapedTagId = jsesc(tagId, { isScriptContext: true }); diff --git a/server/image-data-uri.js b/server/image-data-uri.js index eaf651f0..77dd2330 100644 --- a/server/image-data-uri.js +++ b/server/image-data-uri.js @@ -10,7 +10,7 @@ let ImageDataURI = (() => { /** * Decode the data:image/ URI * @param {string} dataURI data:image/ URI to decode - * @returns {?Object} An object with properties "imageType" and "dataBase64". + * @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. @@ -52,8 +52,8 @@ let ImageDataURI = (() => { /** * Write data URI to file * @param {string} dataURI data:image/ URI - * @param {string} [filePath] Path to write file to - * @returns {Promise} + * @param {string} filePath Path to write file to + * @returns {Promise} Write file error */ function outputFile(dataURI, filePath) { filePath = filePath || "./"; diff --git a/server/jobs.js b/server/jobs.js index a17bd8c9..0838731d 100644 --- a/server/jobs.js +++ b/server/jobs.js @@ -39,7 +39,10 @@ const initBackgroundJobs = async function () { }; -/** Stop all background jobs if running */ +/** + * Stop all background jobs if running + * @returns {void} + */ const stopBackgroundJobs = function () { for (const job of jobs) { if (job.croner) { diff --git a/server/jobs/clear-old-data.js b/server/jobs/clear-old-data.js index fddda82f..91677f07 100644 --- a/server/jobs/clear-old-data.js +++ b/server/jobs/clear-old-data.js @@ -7,7 +7,7 @@ const DEFAULT_KEEP_PERIOD = 180; /** * Clears old data from the heartbeat table of the database. - * @return {Promise} A promise that resolves when the data has been cleared. + * @returns {Promise} A promise that resolves when the data has been cleared. */ const clearOldData = async () => { diff --git a/server/jobs/incremental-vacuum.js b/server/jobs/incremental-vacuum.js index 3a04b12c..f0fa78a1 100644 --- a/server/jobs/incremental-vacuum.js +++ b/server/jobs/incremental-vacuum.js @@ -4,7 +4,7 @@ const Database = require("../database"); /** * Run incremental_vacuum and checkpoint the WAL. - * @return {Promise} A promise that resolves when the process is finished. + * @returns {Promise} A promise that resolves when the process is finished. */ const incrementalVacuum = async () => { diff --git a/server/model/api_key.js b/server/model/api_key.js index 1b27a60f..96de9845 100644 --- a/server/model/api_key.js +++ b/server/model/api_key.js @@ -19,7 +19,7 @@ class APIKey extends BeanModel { /** * Returns an object that ready to parse to JSON - * @returns {Object} + * @returns {object} Object ready to parse */ toJSON() { return { @@ -37,7 +37,7 @@ class APIKey extends BeanModel { /** * Returns an object that ready to parse to JSON with sensitive fields * removed - * @returns {Object} + * @returns {object} Object ready to parse */ toPublicJSON() { return { @@ -53,9 +53,9 @@ class APIKey extends BeanModel { /** * Create a new API Key and store it in the database - * @param {Object} key Object sent by client + * @param {object} key Object sent by client * @param {int} userID ID of socket user - * @returns {Promise} + * @returns {Promise} API key */ static async save(key, userID) { let bean; diff --git a/server/model/docker_host.js b/server/model/docker_host.js index 20598292..ceb8f4a3 100644 --- a/server/model/docker_host.js +++ b/server/model/docker_host.js @@ -3,7 +3,7 @@ const { BeanModel } = require("redbean-node/dist/bean-model"); class DockerHost extends BeanModel { /** * Returns an object that ready to parse to JSON - * @returns {Object} + * @returns {object} Object ready to parse */ toJSON() { return { diff --git a/server/model/group.js b/server/model/group.js index 5b712ace..98ac2a47 100644 --- a/server/model/group.js +++ b/server/model/group.js @@ -4,10 +4,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} + * Return an object that ready to parse to JSON for public Only show + * necessary data to public + * @param {boolean} showTags Should the JSON include monitor tags + * @param {boolean} certExpiry Should JSON include info about + * certificate expiry? + * @returns {object} Object ready to parse */ async toPublicJSON(showTags = false, certExpiry = false) { let monitorBeanList = await this.getMonitorList(); @@ -27,7 +29,7 @@ class Group extends BeanModel { /** * Get all monitors - * @returns {Bean[]} + * @returns {Bean[]} List of monitors */ async getMonitorList() { return R.convertToBeans("monitor", await R.getAll(` diff --git a/server/model/heartbeat.js b/server/model/heartbeat.js index b7847f87..cc86ef63 100644 --- a/server/model/heartbeat.js +++ b/server/model/heartbeat.js @@ -12,7 +12,7 @@ class Heartbeat extends BeanModel { /** * Return an object that ready to parse to JSON for public * Only show necessary data to public - * @returns {Object} + * @returns {object} Object ready to parse */ toPublicJSON() { return { @@ -25,7 +25,7 @@ class Heartbeat extends BeanModel { /** * Return an object that ready to parse to JSON - * @returns {Object} + * @returns {object} Object ready to parse */ toJSON() { return { diff --git a/server/model/incident.js b/server/model/incident.js index f954cc74..c47dabb4 100644 --- a/server/model/incident.js +++ b/server/model/incident.js @@ -5,7 +5,7 @@ class Incident extends BeanModel { /** * Return an object that ready to parse to JSON for public * Only show necessary data to public - * @returns {Object} + * @returns {object} Object ready to parse */ toPublicJSON() { return { diff --git a/server/model/maintenance.js b/server/model/maintenance.js index f18eb026..fb51060e 100644 --- a/server/model/maintenance.js +++ b/server/model/maintenance.js @@ -11,7 +11,7 @@ class Maintenance extends BeanModel { /** * Return an object that ready to parse to JSON for public * Only show necessary data to public - * @returns {Object} + * @returns {object} Object ready to parse */ async toPublicJSON() { @@ -98,7 +98,7 @@ class Maintenance extends BeanModel { /** * Return an object that ready to parse to JSON * @param {string} timezone If not specified, the timeRange will be in UTC - * @returns {Object} + * @returns {object} Object ready to parse */ async toJSON(timezone = null) { return this.toPublicJSON(timezone); @@ -142,7 +142,7 @@ class Maintenance extends BeanModel { /** * Convert data from socket to bean * @param {Bean} bean Bean to fill in - * @param {Object} obj Data to fill bean with + * @param {object} obj Data to fill bean with * @returns {Bean} Filled bean */ static async jsonToBean(bean, obj) { @@ -188,7 +188,7 @@ class Maintenance extends BeanModel { /** * Throw error if cron is invalid - * @param cron + * @param {string|Date} cron Pattern or date * @returns {Promise} */ static async validateCron(cron) { @@ -198,6 +198,8 @@ class Maintenance extends BeanModel { /** * Run the cron + * @param {boolean} throwError Should an error be thrown on failure + * @returns {Promise} */ async run(throwError = false) { if (this.beanMeta.job) { @@ -290,6 +292,10 @@ class Maintenance extends BeanModel { } } + /** + * Get timeslots where maintenance is running + * @returns {object|null} Maintenance time slot + */ getRunningTimeslot() { let start = dayjs(this.beanMeta.job.nextRun(dayjs().add(-this.duration, "second").toDate())); let end = start.add(this.duration, "second"); @@ -305,6 +311,10 @@ class Maintenance extends BeanModel { } } + /** + * Stop the maintenance + * @returns {void} + */ stop() { if (this.beanMeta.job) { this.beanMeta.job.stop(); @@ -312,10 +322,18 @@ class Maintenance extends BeanModel { } } + /** + * Is this maintenance currently active + * @returns {boolean} The maintenance is active? + */ async isUnderMaintenance() { return (await this.getStatus()) === "under-maintenance"; } + /** + * Get the timezone of the maintenance + * @returns {string} timezone + */ async getTimezone() { if (!this.timezone || this.timezone === "SAME_AS_SERVER") { return await UptimeKumaServer.getInstance().getTimezone(); @@ -323,10 +341,18 @@ class Maintenance extends BeanModel { return this.timezone; } + /** + * Get offset for timezone + * @returns {string} offset + */ async getTimezoneOffset() { return dayjs.tz(dayjs(), await this.getTimezone()).format("Z"); } + /** + * Get the current status of the maintenance + * @returns {string} Current status + */ async getStatus() { if (!this.active) { return "inactive"; diff --git a/server/model/monitor.js b/server/model/monitor.js index 237eb79e..fccc4fcb 100644 --- a/server/model/monitor.js +++ b/server/model/monitor.js @@ -34,9 +34,12 @@ const Database = require("../database"); class Monitor extends BeanModel { /** - * Return an object that ready to parse to JSON for public - * Only show necessary data to public - * @returns {Object} + * Return an object that ready to parse to JSON for public Only show + * necessary data to public + * @param {boolean} showTags Include tags in JSON + * @param {boolean} certExpiry Include certificate expiry info in + * JSON + * @returns {object} Object ready to parse */ async toPublicJSON(showTags = false, certExpiry = false) { let obj = { @@ -65,7 +68,9 @@ class Monitor extends BeanModel { /** * Return an object that ready to parse to JSON - * @returns {Object} + * @param {boolean} includeSensitiveData Include sensitive data in + * JSON + * @returns {object} Object ready to parse */ async toJSON(includeSensitiveData = true) { @@ -183,9 +188,9 @@ class Monitor extends BeanModel { } /** - * Checks if the monitor is active based on itself and its parents - * @returns {Promise} - */ + * Checks if the monitor is active based on itself and its parents + * @returns {Promise} Is the monitor active? + */ async isActive() { const parentActive = await Monitor.isParentActive(this.id); @@ -194,7 +199,8 @@ class Monitor extends BeanModel { /** * Get all tags applied to this monitor - * @returns {Promise[]>} + * @returns {Promise[]>} List of tags on the + * monitor */ 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 = ? ORDER BY tag.name", [ this.id ]); @@ -203,7 +209,8 @@ class Monitor extends BeanModel { /** * Gets certificate expiry for this monitor * @param {number} monitorID ID of monitor to send - * @returns {Promise>} + * @returns {Promise>} Certificate expiry info for + * monitor */ async getCertExpiry(monitorID) { let tlsInfoBean = await R.findOne("monitor_tls_info", "monitor_id = ?", [ @@ -228,7 +235,9 @@ class Monitor extends BeanModel { /** * Encode user and password to Base64 encoding * for HTTP "basic" auth, as per RFC-7617 - * @returns {string} + * @param {string} user Username to encode + * @param {string} pass Password to encode + * @returns {string} Encoded username:password */ encodeBase64(user, pass) { return Buffer.from(user + ":" + pass).toString("base64"); @@ -236,7 +245,7 @@ class Monitor extends BeanModel { /** * Is the TLS expiry notification enabled? - * @returns {boolean} + * @returns {boolean} Enabled? */ isEnabledExpiryNotification() { return Boolean(this.expiryNotification); @@ -244,7 +253,7 @@ class Monitor extends BeanModel { /** * Parse to boolean - * @returns {boolean} + * @returns {boolean} Should TLS errors be ignored? */ getIgnoreTls() { return Boolean(this.ignoreTls); @@ -252,7 +261,7 @@ class Monitor extends BeanModel { /** * Parse to boolean - * @returns {boolean} + * @returns {boolean} Is the monitor in upside down mode? */ isUpsideDown() { return Boolean(this.upsideDown); @@ -260,7 +269,7 @@ class Monitor extends BeanModel { /** * Parse to boolean - * @returns {boolean} + * @returns {boolean} Invert keyword match? */ isInvertKeyword() { return Boolean(this.invertKeyword); @@ -268,7 +277,7 @@ class Monitor extends BeanModel { /** * Parse to boolean - * @returns {boolean} + * @returns {boolean} Enable TLS for gRPC? */ getGrpcEnableTls() { return Boolean(this.grpcEnableTls); @@ -276,7 +285,7 @@ class Monitor extends BeanModel { /** * Get accepted status codes - * @returns {Object} + * @returns {object} Accepted status codes */ getAcceptedStatuscodes() { return JSON.parse(this.accepted_statuscodes_json); @@ -289,6 +298,7 @@ class Monitor extends BeanModel { /** * Start monitor * @param {Server} io Socket server instance + * @returns {void} */ start(io) { let previousBeat = null; @@ -980,7 +990,10 @@ class Monitor extends BeanModel { }; - /** Get a heartbeat and handle errors */ + /** + * Get a heartbeat and handle errors7 + * @returns {void} + */ const safeBeat = async () => { try { await beat(); @@ -1008,10 +1021,10 @@ class Monitor extends BeanModel { /** * Make a request using axios - * @param {Object} options Options for 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 + * don't retry on failure + * @returns {object} Axios response */ async makeAxiosRequest(options, finalCall = false) { try { @@ -1046,7 +1059,10 @@ class Monitor extends BeanModel { } } - /** Stop monitor */ + /** + * Stop monitor + * @returns {void} + */ stop() { clearTimeout(this.heartbeatInterval); this.isStop = true; @@ -1056,7 +1072,7 @@ class Monitor extends BeanModel { /** * Get prometheus instance - * @returns {Prometheus|undefined} + * @returns {Prometheus|undefined} Current prometheus instance */ getPrometheus() { return this.prometheus; @@ -1066,7 +1082,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)} Monitor URL */ getUrl() { try { @@ -1078,8 +1094,8 @@ class Monitor extends BeanModel { /** * Store TLS info to database - * @param checkCertificateResult - * @returns {Promise} + * @param {object} checkCertificateResult Certificate to update + * @returns {Promise} Updated certificate */ async updateTlsInfo(checkCertificateResult) { let tlsInfoBean = await R.findOne("monitor_tls_info", "monitor_id = ?", [ @@ -1126,6 +1142,7 @@ class Monitor extends BeanModel { * @param {Server} io Socket server instance * @param {number} monitorID ID of monitor to send * @param {number} userID ID of user to send to + * @returns {void} */ static async sendStats(io, monitorID, userID) { const hasClients = getTotalClientInRoom(io, userID) > 0; @@ -1143,6 +1160,10 @@ class Monitor extends BeanModel { /** * Send the average ping to user * @param {number} duration Hours + * @param {Server} io Socket instance to send data to + * @param {number} monitorID ID of monitor to read + * @param {number} userID ID of user to send data to + * @returns {void} */ static async sendAvgPing(duration, io, monitorID, userID) { const timeLogger = new TimeLogger(); @@ -1168,6 +1189,7 @@ class Monitor extends BeanModel { * @param {Server} io Socket server instance * @param {number} monitorID ID of monitor to send * @param {number} userID ID of user to send to + * @returns {void} */ static async sendCertInfo(io, monitorID, userID) { let tlsInfo = await R.findOne("monitor_tls_info", "monitor_id = ?", [ @@ -1184,6 +1206,8 @@ class Monitor extends BeanModel { * https://www.uptrends.com/support/kb/reporting/calculation-of-uptime-and-downtime * @param {number} duration Hours * @param {number} monitorID ID of monitor to calculate + * @param {boolean} forceNoCache Should the uptime be recalculated? + * @returns {number} Uptime of monitor */ static async calcUptime(duration, monitorID, forceNoCache = false) { @@ -1264,6 +1288,7 @@ class Monitor extends BeanModel { * @param {Server} io Socket server instance * @param {number} monitorID ID of monitor to send * @param {number} userID ID of user to send to + * @returns {void} */ static async sendUptime(duration, io, monitorID, userID) { const uptime = await this.calcUptime(duration, monitorID); @@ -1338,6 +1363,7 @@ class Monitor extends BeanModel { * @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 + * @returns {void} */ static async sendNotification(isFirstBeat, monitor, bean) { if (!isFirstBeat || bean.status === DOWN) { @@ -1378,7 +1404,7 @@ class Monitor extends BeanModel { /** * Get list of notification providers for a given monitor * @param {Monitor} monitor Monitor to get notification providers for - * @returns {Promise[]>} + * @returns {Promise[]>} List of notifications */ 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 ", [ @@ -1389,7 +1415,8 @@ class Monitor extends BeanModel { /** * checks certificate chain for expiring certificates - * @param {Object} tlsInfoObject Information about certificate + * @param {object} tlsInfoObject Information about certificate + * @returns {void} */ async checkCertExpiryNotifications(tlsInfoObject) { if (tlsInfoObject && tlsInfoObject.certInfo && tlsInfoObject.certInfo.daysRemaining) { @@ -1476,7 +1503,7 @@ class Monitor extends BeanModel { /** * Get the status of the previous heartbeat * @param {number} monitorID ID of monitor to check - * @returns {Promise>} + * @returns {Promise>} Previous heartbeat */ static async getPreviousHeartbeat(monitorID) { return await R.getRow(` @@ -1490,7 +1517,7 @@ class Monitor extends BeanModel { /** * Check if monitor is under maintenance * @param {number} monitorID ID of monitor to check - * @returns {Promise} + * @returns {Promise} Is the monitor under maintenance */ static async isUnderMaintenance(monitorID) { const maintenanceIDList = await R.getCol(` @@ -1513,7 +1540,11 @@ class Monitor extends BeanModel { return false; } - /** Make sure monitor interval is between bounds */ + /** + * Make sure monitor interval is between bounds + * @returns {void} + * @throws Interval is outside of range + */ validate() { if (this.interval > MAX_INTERVAL_SECOND) { throw new Error(`Interval cannot be more than ${MAX_INTERVAL_SECOND} seconds`); @@ -1526,7 +1557,7 @@ class Monitor extends BeanModel { /** * Gets Parent of the monitor * @param {number} monitorID ID of monitor to get - * @returns {Promise>} + * @returns {Promise>} Parent */ static async getParent(monitorID) { return await R.getRow(` @@ -1542,7 +1573,7 @@ class Monitor extends BeanModel { /** * Gets all Children of the monitor * @param {number} monitorID ID of monitor to get - * @returns {Promise>} + * @returns {Promise>} Children */ static async getChildren(monitorID) { return await R.getAll(` @@ -1555,7 +1586,7 @@ class Monitor extends BeanModel { /** * Gets Full Path-Name (Groups and Name) - * @returns {Promise} + * @returns {Promise} Full path name of this monitor */ async getPathName() { let path = this.name; @@ -1575,8 +1606,8 @@ class Monitor extends BeanModel { /** * Gets recursive all child ids - * @param {number} monitorID ID of the monitor to get - * @returns {Promise} + * @param {number} monitorID ID of the monitor to get + * @returns {Promise} IDs of all children */ static async getAllChildrenIDs(monitorID) { const childs = await Monitor.getChildren(monitorID); @@ -1607,10 +1638,10 @@ class Monitor extends BeanModel { } /** - * Checks recursive if parent (ancestors) are active - * @param {number} monitorID ID of the monitor to get - * @returns {Promise} - */ + * Checks recursive if parent (ancestors) are active + * @param {number} monitorID ID of the monitor to get + * @returns {Promise} Is the parent monitor active? + */ static async isParentActive(monitorID) { const parent = await Monitor.getParent(monitorID); diff --git a/server/model/proxy.js b/server/model/proxy.js index 4517b11b..ec78403d 100644 --- a/server/model/proxy.js +++ b/server/model/proxy.js @@ -3,7 +3,7 @@ const { BeanModel } = require("redbean-node/dist/bean-model"); class Proxy extends BeanModel { /** * Return an object that ready to parse to JSON - * @returns {Object} + * @returns {object} Object ready to parse */ toJSON() { return { diff --git a/server/model/status_page.js b/server/model/status_page.js index e168acf2..e6095a63 100644 --- a/server/model/status_page.js +++ b/server/model/status_page.js @@ -14,10 +14,11 @@ class StatusPage extends BeanModel { static domainMappingList = { }; /** - * - * @param {Response} response - * @param {string} indexHTML - * @param {string} slug + * Handle responses to status page + * @param {Response} response Response object + * @param {string} indexHTML HTML to render + * @param {string} slug Status page slug + * @returns {void} */ static async handleStatusPageResponse(response, indexHTML, slug) { let statusPage = await R.findOne("status_page", " slug = ? ", [ @@ -33,8 +34,9 @@ class StatusPage extends BeanModel { /** * SSR for status pages - * @param {string} indexHTML - * @param {StatusPage} statusPage + * @param {string} indexHTML HTML page to render + * @param {StatusPage} statusPage Status page populate HTML with + * @returns {void} */ static async renderHTML(indexHTML, statusPage) { const $ = cheerio.load(indexHTML); @@ -87,7 +89,8 @@ class StatusPage extends BeanModel { /** * Get all status page data in one call - * @param {StatusPage} statusPage + * @param {StatusPage} statusPage Status page to get data for + * @returns {object} Status page data */ static async getStatusPageData(statusPage) { const config = await statusPage.toPublicJSON(); @@ -142,7 +145,7 @@ 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} + * @returns {Promise} Status page list */ static async sendStatusPageList(io, socket) { let result = {}; @@ -159,7 +162,7 @@ class StatusPage extends BeanModel { /** * Update list of domain names - * @param {string[]} domainNameList + * @param {string[]} domainNameList List of status page domains * @returns {Promise} */ async updateDomainNameList(domainNameList) { @@ -203,7 +206,7 @@ class StatusPage extends BeanModel { /** * Get list of domain names - * @returns {Object[]} + * @returns {object[]} List of status page domains */ getDomainNameList() { let domainList = []; @@ -219,7 +222,7 @@ class StatusPage extends BeanModel { /** * Return an object that ready to parse to JSON - * @returns {Object} + * @returns {object} Object ready to parse */ async toJSON() { return { @@ -243,7 +246,7 @@ class StatusPage extends BeanModel { /** * Return an object that ready to parse to JSON for public * Only show necessary data to public - * @returns {Object} + * @returns {object} Object ready to parse */ async toPublicJSON() { return { @@ -264,7 +267,8 @@ class StatusPage extends BeanModel { /** * Convert slug to status page ID - * @param {string} slug + * @param {string} slug Status page slug + * @returns {Promise} ID of status page */ static async slugToID(slug) { return await R.getCell("SELECT id FROM status_page WHERE slug = ? ", [ @@ -274,7 +278,7 @@ class StatusPage extends BeanModel { /** * Get path to the icon for the page - * @returns {string} + * @returns {string} Path */ getIcon() { if (!this.icon) { @@ -287,7 +291,7 @@ class StatusPage extends BeanModel { /** * Get list of maintenances * @param {number} statusPageId ID of status page to get maintenance for - * @returns {Object} Object representing maintenances sanitized for public + * @returns {object} Object representing maintenances sanitized for public */ static async getMaintenanceList(statusPageId) { try { diff --git a/server/model/tag.js b/server/model/tag.js index b31eb868..bc8a4db1 100644 --- a/server/model/tag.js +++ b/server/model/tag.js @@ -4,7 +4,7 @@ class Tag extends BeanModel { /** * Return an object that ready to parse to JSON - * @returns {Object} + * @returns {object} Object ready to parse */ toJSON() { return { diff --git a/server/model/user.js b/server/model/user.js index fc619c74..cba53a3f 100644 --- a/server/model/user.js +++ b/server/model/user.js @@ -7,7 +7,7 @@ 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 {number} userID ID of user to update - * @param {string} newPassword + * @param {string} newPassword Users new password * @returns {Promise} */ static async resetPassword(userID, newPassword) { @@ -19,7 +19,7 @@ class User extends BeanModel { /** * Reset this users password - * @param {string} newPassword + * @param {string} newPassword Users new password * @returns {Promise} */ async resetPassword(newPassword) { diff --git a/server/monitor-types/monitor-type.js b/server/monitor-types/monitor-type.js index 80a0a7d9..782bedd5 100644 --- a/server/monitor-types/monitor-type.js +++ b/server/monitor-types/monitor-type.js @@ -3,10 +3,10 @@ class MonitorType { name = undefined; /** - * - * @param {Monitor} monitor - * @param {Heartbeat} heartbeat - * @param {UptimeKumaServer} server + * Run the monitoring check on the given monitor + * @param {Monitor} monitor Monitor to check + * @param {Heartbeat} heartbeat Monitor heartbeat to update + * @param {UptimeKumaServer} server Uptime Kuma server * @returns {Promise} */ async check(monitor, heartbeat, server) { diff --git a/server/monitor-types/real-browser-monitor-type.js b/server/monitor-types/real-browser-monitor-type.js index f3e5695f..34ee1848 100644 --- a/server/monitor-types/real-browser-monitor-type.js +++ b/server/monitor-types/real-browser-monitor-type.js @@ -51,6 +51,11 @@ if (process.platform === "win32") { log.debug("chrome", allowedList); +/** + * Is the executable path allowed? + * @param {string} executablePath Path to executable + * @returns {Promise} The executable is allowed? + */ async function isAllowedChromeExecutable(executablePath) { console.log(config.args); if (config.args["allow-all-chrome-exec"] || process.env.UPTIME_KUMA_ALLOW_ALL_CHROME_EXEC === "1") { @@ -61,6 +66,11 @@ async function isAllowedChromeExecutable(executablePath) { return allowedList.includes(executablePath); } +/** + * Get the current instance of the browser. If there isn't one, create + * it. + * @returns {Promise} The browser + */ async function getBrowser() { if (!browser) { let executablePath = await Settings.get("chromeExecutable"); @@ -75,6 +85,11 @@ async function getBrowser() { return browser; } +/** + * Prepare the chrome executable path + * @param {string} executablePath Path to chrome executable + * @returns {Promise} Executable path + */ async function prepareChromeExecutable(executablePath) { // Special code for using the playwright_chromium if (typeof executablePath === "string" && executablePath.toLocaleLowerCase() === "#playwright_chromium") { @@ -121,6 +136,12 @@ async function prepareChromeExecutable(executablePath) { return executablePath; } +/** + * Find the chrome executable + * @param {any[]} executables Executables to search through + * @returns {any} Executable + * @throws Could not find executable + */ function findChrome(executables) { // Use the last working executable, so we don't have to search for it again if (lastAutoDetectChromeExecutable) { @@ -138,6 +159,10 @@ function findChrome(executables) { throw new Error("Chromium not found, please specify Chromium executable path in the settings page."); } +/** + * Reset chrome + * @returns {Promise} + */ async function resetChrome() { if (browser) { await browser.close(); @@ -147,8 +172,8 @@ async function resetChrome() { /** * Test if the chrome executable is valid and return the version - * @param executablePath - * @returns {Promise} + * @param {string} executablePath Path to executable + * @returns {Promise} Chrome version */ async function testChrome(executablePath) { try { @@ -175,6 +200,9 @@ class RealBrowserMonitorType extends MonitorType { name = "real-browser"; + /** + * @inheritdoc + */ async check(monitor, heartbeat, server) { const browser = await getBrowser(); const context = await browser.newContext(); diff --git a/server/monitor-types/tailscale-ping.js b/server/monitor-types/tailscale-ping.js index eeec9e3f..e5275391 100644 --- a/server/monitor-types/tailscale-ping.js +++ b/server/monitor-types/tailscale-ping.js @@ -13,9 +13,9 @@ class TailscalePing extends MonitorType { /** * Checks the ping status of the URL associated with the monitor. * It then parses the Tailscale ping command output to update the heatrbeat. - * - * @param {Object} monitor - The monitor object associated with the check. - * @param {Object} heartbeat - The heartbeat object to update. + * @param {object} monitor The monitor object associated with the check. + * @param {object} heartbeat The heartbeat object to update. + * @returns {Promise} * @throws Will throw an error if checking Tailscale ping encounters any error */ async check(monitor, heartbeat) { @@ -31,9 +31,9 @@ class TailscalePing extends MonitorType { /** * Runs the Tailscale ping command to the given URL. - * - * @param {string} hostname - The hostname to ping. - * @returns {Promise} - A Promise that resolves to the output of the Tailscale ping command + * @param {string} hostname The hostname to ping. + * @param {number} interval Interval to send ping + * @returns {Promise} A Promise that resolves to the output of the Tailscale ping command * @throws Will throw an error if the command execution encounters any error. */ async runTailscalePing(hostname, interval) { @@ -61,9 +61,9 @@ class TailscalePing extends MonitorType { /** * Parses the output of the Tailscale ping command to update the heartbeat. - * - * @param {string} tailscaleOutput - The output of the Tailscale ping command. - * @param {Object} heartbeat - The heartbeat object to update. + * @param {string} tailscaleOutput The output of the Tailscale ping command. + * @param {object} heartbeat The heartbeat object to update. + * @returns {void} * @throws Will throw an eror if the output contains any unexpected string. */ parseTailscaleOutput(tailscaleOutput, heartbeat) { diff --git a/server/notification-providers/alerta.js b/server/notification-providers/alerta.js index 2b85d67a..62092178 100644 --- a/server/notification-providers/alerta.js +++ b/server/notification-providers/alerta.js @@ -6,6 +6,9 @@ class Alerta extends NotificationProvider { name = "alerta"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; diff --git a/server/notification-providers/alertnow.js b/server/notification-providers/alertnow.js index d778b01d..1206b72e 100644 --- a/server/notification-providers/alertnow.js +++ b/server/notification-providers/alertnow.js @@ -7,6 +7,9 @@ class AlertNow extends NotificationProvider { name = "AlertNow"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; try { diff --git a/server/notification-providers/aliyun-sms.js b/server/notification-providers/aliyun-sms.js index fa73ffb1..8f83ac5b 100644 --- a/server/notification-providers/aliyun-sms.js +++ b/server/notification-providers/aliyun-sms.js @@ -7,6 +7,9 @@ const qs = require("qs"); class AliyunSMS extends NotificationProvider { name = "AliyunSMS"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; @@ -78,9 +81,9 @@ class AliyunSMS extends NotificationProvider { /** * Aliyun request sign - * @param {Object} param Parameters object to sign + * @param {object} param Parameters object to sign * @param {string} AccessKeySecret Secret key to sign parameters with - * @returns {string} + * @returns {string} Base64 encoded request */ sign(param, AccessKeySecret) { let param2 = {}; @@ -122,7 +125,7 @@ class AliyunSMS extends NotificationProvider { /** * Convert status constant to string * @param {const} status The status constant - * @returns {string} + * @returns {string} Status */ statusToString(status) { switch (status) { diff --git a/server/notification-providers/apprise.js b/server/notification-providers/apprise.js index 887afbf5..b624b910 100644 --- a/server/notification-providers/apprise.js +++ b/server/notification-providers/apprise.js @@ -5,6 +5,9 @@ class Apprise extends NotificationProvider { name = "apprise"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { const args = [ "-vv", "-b", msg, notification.appriseURL ]; if (notification.title) { diff --git a/server/notification-providers/bark.js b/server/notification-providers/bark.js index bcd3c682..8746761e 100644 --- a/server/notification-providers/bark.js +++ b/server/notification-providers/bark.js @@ -18,6 +18,9 @@ const successMessage = "Successes!"; class Bark extends NotificationProvider { name = "Bark"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let barkEndpoint = notification.barkEndpoint; @@ -45,8 +48,9 @@ class Bark extends NotificationProvider { /** * Add additional parameter for better on device styles (iOS 15 * optimized) + * @param {BeanModel} notification Notification to send * @param {string} postUrl URL to append parameters to - * @returns {string} + * @returns {string} Additional URL parameters */ appendAdditionalParameters(notification, postUrl) { // set icon to uptime kuma icon, 11kb should be fine @@ -70,7 +74,8 @@ class Bark extends NotificationProvider { /** * Check if result is successful - * @param {Object} result Axios response object + * @param {object} result Axios response object + * @returns {void} * @throws {Error} The status code is not in range 2xx */ checkResult(result) { @@ -84,10 +89,11 @@ class Bark extends NotificationProvider { /** * Send the message + * @param {BeanModel} notification Notification to send * @param {string} title Message title * @param {string} subtitle Message * @param {string} endpoint Endpoint to send request to - * @returns {string} + * @returns {string} Success message */ async postNotification(notification, title, subtitle, endpoint) { // url encode title and subtitle diff --git a/server/notification-providers/clicksendsms.js b/server/notification-providers/clicksendsms.js index 1df05309..5539a6a4 100644 --- a/server/notification-providers/clicksendsms.js +++ b/server/notification-providers/clicksendsms.js @@ -5,6 +5,9 @@ class ClickSendSMS extends NotificationProvider { name = "clicksendsms"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; try { diff --git a/server/notification-providers/dingding.js b/server/notification-providers/dingding.js index cea0b0a1..be3a2fbc 100644 --- a/server/notification-providers/dingding.js +++ b/server/notification-providers/dingding.js @@ -6,6 +6,9 @@ const Crypto = require("crypto"); class DingDing extends NotificationProvider { name = "DingDing"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; @@ -39,8 +42,8 @@ class DingDing extends NotificationProvider { /** * Send message to DingDing - * @param {BeanModel} notification - * @param {Object} params Parameters of message + * @param {BeanModel} notification Notification to send + * @param {object} params Parameters of message * @returns {boolean} True if successful else false */ async sendToDingDing(notification, params) { @@ -66,7 +69,7 @@ class DingDing extends NotificationProvider { * DingDing sign * @param {Date} timestamp Timestamp of message * @param {string} secretKey Secret key to sign data with - * @returns {string} + * @returns {string} Base64 encoded signature */ sign(timestamp, secretKey) { return Crypto @@ -78,7 +81,7 @@ class DingDing extends NotificationProvider { /** * Convert status constant to string * @param {const} status The status constant - * @returns {string} + * @returns {string} Status */ statusToString(status) { // TODO: Move to notification-provider.js to avoid repetition in classes diff --git a/server/notification-providers/discord.js b/server/notification-providers/discord.js index 37de0d36..94cca3a8 100644 --- a/server/notification-providers/discord.js +++ b/server/notification-providers/discord.js @@ -6,6 +6,9 @@ class Discord extends NotificationProvider { name = "discord"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; diff --git a/server/notification-providers/feishu.js b/server/notification-providers/feishu.js index 683a3653..dd5ce295 100644 --- a/server/notification-providers/feishu.js +++ b/server/notification-providers/feishu.js @@ -5,6 +5,9 @@ const { DOWN, UP } = require("../../src/util"); class Feishu extends NotificationProvider { name = "Feishu"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; let feishuWebHookUrl = notification.feishuWebHookUrl; diff --git a/server/notification-providers/flashduty.js b/server/notification-providers/flashduty.js index 0d6f69e5..83ef27b5 100644 --- a/server/notification-providers/flashduty.js +++ b/server/notification-providers/flashduty.js @@ -7,6 +7,9 @@ const successMessage = "Sent Successfully."; class FlashDuty extends NotificationProvider { name = "FlashDuty"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { try { if (heartbeatJSON == null) { @@ -33,12 +36,12 @@ class FlashDuty extends NotificationProvider { this.throwGeneralAxiosError(error); } } + /** * Generate a monitor url from the monitors infomation - * @param {Object} monitorInfo Monitor details - * @returns {string|undefined} + * @param {object} monitorInfo Monitor details + * @returns {string|undefined} Monitor URL */ - genMonitorUrl(monitorInfo) { if (monitorInfo.type === "port" && monitorInfo.port) { return monitorInfo.hostname + ":" + monitorInfo.port; @@ -54,9 +57,9 @@ class FlashDuty extends NotificationProvider { * @param {BeanModel} notification Message title * @param {string} title Message * @param {string} body Message - * @param {Object} monitorInfo Monitor details + * @param {object} monitorInfo Monitor details * @param {string} eventStatus Monitor status (Info, Warning, Critical, Ok) - * @returns {string} + * @returns {string} Success message */ async postNotification(notification, title, body, monitorInfo, eventStatus) { const options = { diff --git a/server/notification-providers/freemobile.js b/server/notification-providers/freemobile.js index 919150fa..44c55bfd 100644 --- a/server/notification-providers/freemobile.js +++ b/server/notification-providers/freemobile.js @@ -5,6 +5,9 @@ class FreeMobile extends NotificationProvider { name = "FreeMobile"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; try { diff --git a/server/notification-providers/goalert.js b/server/notification-providers/goalert.js index 73e0375a..abf77924 100644 --- a/server/notification-providers/goalert.js +++ b/server/notification-providers/goalert.js @@ -6,6 +6,9 @@ class GoAlert extends NotificationProvider { name = "GoAlert"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; try { diff --git a/server/notification-providers/google-chat.js b/server/notification-providers/google-chat.js index 02cb4823..413fde26 100644 --- a/server/notification-providers/google-chat.js +++ b/server/notification-providers/google-chat.js @@ -8,6 +8,9 @@ class GoogleChat extends NotificationProvider { name = "GoogleChat"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; try { diff --git a/server/notification-providers/gorush.js b/server/notification-providers/gorush.js index 6d756e46..28f03ab9 100644 --- a/server/notification-providers/gorush.js +++ b/server/notification-providers/gorush.js @@ -5,6 +5,9 @@ class Gorush extends NotificationProvider { name = "gorush"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; diff --git a/server/notification-providers/gotify.js b/server/notification-providers/gotify.js index 0c524493..3e99b3d1 100644 --- a/server/notification-providers/gotify.js +++ b/server/notification-providers/gotify.js @@ -5,6 +5,9 @@ class Gotify extends NotificationProvider { name = "gotify"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; try { diff --git a/server/notification-providers/home-assistant.js b/server/notification-providers/home-assistant.js index 6b950476..292fc3e6 100644 --- a/server/notification-providers/home-assistant.js +++ b/server/notification-providers/home-assistant.js @@ -6,6 +6,9 @@ const defaultNotificationService = "notify"; class HomeAssistant extends NotificationProvider { name = "HomeAssistant"; + /** + * @inheritdoc + */ async send(notification, message, monitor = null, heartbeat = null) { const notificationService = notification?.notificationService || defaultNotificationService; diff --git a/server/notification-providers/kook.js b/server/notification-providers/kook.js index b37b75ab..b9b68f43 100644 --- a/server/notification-providers/kook.js +++ b/server/notification-providers/kook.js @@ -5,6 +5,9 @@ class Kook extends NotificationProvider { name = "Kook"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; let url = "https://www.kookapp.cn/api/v3/message/create"; diff --git a/server/notification-providers/line.js b/server/notification-providers/line.js index 10b7f2c9..73dc962f 100644 --- a/server/notification-providers/line.js +++ b/server/notification-providers/line.js @@ -6,6 +6,9 @@ class Line extends NotificationProvider { name = "line"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; try { diff --git a/server/notification-providers/linenotify.js b/server/notification-providers/linenotify.js index 279acb7d..dfe7e598 100644 --- a/server/notification-providers/linenotify.js +++ b/server/notification-providers/linenotify.js @@ -7,6 +7,9 @@ class LineNotify extends NotificationProvider { name = "LineNotify"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; try { diff --git a/server/notification-providers/lunasea.js b/server/notification-providers/lunasea.js index 0a5fea7b..3729b0fe 100644 --- a/server/notification-providers/lunasea.js +++ b/server/notification-providers/lunasea.js @@ -6,6 +6,9 @@ class LunaSea extends NotificationProvider { name = "lunasea"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; let lunaseaurl = ""; diff --git a/server/notification-providers/matrix.js b/server/notification-providers/matrix.js index 915c772d..c9baf48b 100644 --- a/server/notification-providers/matrix.js +++ b/server/notification-providers/matrix.js @@ -6,6 +6,9 @@ const { log } = require("../../src/util"); class Matrix extends NotificationProvider { name = "matrix"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; diff --git a/server/notification-providers/mattermost.js b/server/notification-providers/mattermost.js index d4997392..9cbb51bb 100644 --- a/server/notification-providers/mattermost.js +++ b/server/notification-providers/mattermost.js @@ -6,6 +6,9 @@ class Mattermost extends NotificationProvider { name = "mattermost"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; try { diff --git a/server/notification-providers/nostr.js b/server/notification-providers/nostr.js index 2c17840d..9d93678f 100644 --- a/server/notification-providers/nostr.js +++ b/server/notification-providers/nostr.js @@ -33,6 +33,9 @@ if (semver.lt(nodeVersion, "16.0.0")) { class Nostr extends NotificationProvider { name = "nostr"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { // All DMs should have same timestamp const createdAt = Math.floor(Date.now() / 1000); @@ -86,6 +89,11 @@ class Nostr extends NotificationProvider { return `${successfulRelays}/${relays.length} relays connected.`; } + /** + * Get the private key for the sender + * @param {string} sender Sender to retrieve key for + * @returns {nip19.DecodeResult} Private key + */ async getPrivateKey(sender) { try { const senderDecodeResult = await nip19.decode(sender); @@ -96,6 +104,11 @@ class Nostr extends NotificationProvider { } } + /** + * Get public keys for recipients + * @param {string} recipients Newline delimited list of recipients + * @returns {nip19.DecodeResult[]} Public keys + */ async getPublicKeys(recipients) { const recipientsList = recipients.split("\n"); const publicKeys = []; diff --git a/server/notification-providers/notification-provider.js b/server/notification-providers/notification-provider.js index 2a182d42..9b4f0bb0 100644 --- a/server/notification-providers/notification-provider.js +++ b/server/notification-providers/notification-provider.js @@ -2,16 +2,16 @@ class NotificationProvider { /** * Notification Provider Name - * @type string + * @type {string} */ name = undefined; /** * Send a notification - * @param {BeanModel} notification + * @param {BeanModel} notification Notification to send * @param {string} msg General Message - * @param {?Object} monitorJSON Monitor details (For Up/Down only) - * @param {?Object} heartbeatJSON Heartbeat details (For Up/Down only) + * @param {?object} monitorJSON Monitor details (For Up/Down only) + * @param {?object} heartbeatJSON Heartbeat details (For Up/Down only) * @returns {Promise} Return Successful Message * @throws Error with fail msg */ @@ -22,6 +22,7 @@ class NotificationProvider { /** * Throws an error * @param {any} error The error to throw + * @returns {void} * @throws {any} The error specified */ throwGeneralAxiosError(error) { diff --git a/server/notification-providers/ntfy.js b/server/notification-providers/ntfy.js index 2d8378e5..86fc0e08 100644 --- a/server/notification-providers/ntfy.js +++ b/server/notification-providers/ntfy.js @@ -6,6 +6,9 @@ class Ntfy extends NotificationProvider { name = "ntfy"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; try { diff --git a/server/notification-providers/octopush.js b/server/notification-providers/octopush.js index d5c475d3..ec62cd3a 100644 --- a/server/notification-providers/octopush.js +++ b/server/notification-providers/octopush.js @@ -5,6 +5,9 @@ class Octopush extends NotificationProvider { name = "octopush"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; diff --git a/server/notification-providers/onebot.js b/server/notification-providers/onebot.js index 6c62eccb..ec7fc46d 100644 --- a/server/notification-providers/onebot.js +++ b/server/notification-providers/onebot.js @@ -5,6 +5,9 @@ class OneBot extends NotificationProvider { name = "OneBot"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; try { diff --git a/server/notification-providers/opsgenie.js b/server/notification-providers/opsgenie.js index 5fa7f3e4..05c855d7 100644 --- a/server/notification-providers/opsgenie.js +++ b/server/notification-providers/opsgenie.js @@ -68,11 +68,11 @@ class Opsgenie extends NotificationProvider { } /** - * - * @param {BeanModel} notification + * Make POST request to Opsgenie + * @param {BeanModel} notification Notification to send * @param {string} url Request url - * @param {Object} data Request body - * @returns {Promise} + * @param {object} data Request body + * @returns {Promise} Success message */ async post(notification, url, data) { let config = { diff --git a/server/notification-providers/pagerduty.js b/server/notification-providers/pagerduty.js index 86e9a099..c60d782e 100644 --- a/server/notification-providers/pagerduty.js +++ b/server/notification-providers/pagerduty.js @@ -39,7 +39,8 @@ class PagerDuty extends NotificationProvider { /** * Check if result is successful, result code should be in range 2xx - * @param {Object} result Axios response object + * @param {object} result Axios response object + * @returns {void} * @throws {Error} The status code is not in range 2xx */ checkResult(result) { @@ -56,9 +57,9 @@ class PagerDuty extends NotificationProvider { * @param {BeanModel} notification Message title * @param {string} title Message title * @param {string} body Message - * @param {Object} monitorInfo Monitor details (For Up/Down only) + * @param {object} monitorInfo Monitor details (For Up/Down only) * @param {?string} eventAction Action event for PagerDuty (trigger, acknowledge, resolve) - * @returns {string} + * @returns {Promise} Success message */ async postNotification(notification, title, body, monitorInfo, eventAction = "trigger") { diff --git a/server/notification-providers/pagertree.js b/server/notification-providers/pagertree.js index 8a0c4e36..c7a5338d 100644 --- a/server/notification-providers/pagertree.js +++ b/server/notification-providers/pagertree.js @@ -32,7 +32,8 @@ class PagerTree extends NotificationProvider { /** * Check if result is successful, result code should be in range 2xx - * @param {Object} result Axios response object + * @param {object} result Axios response object + * @returns {void} * @throws {Error} The status code is not in range 2xx */ checkResult(result) { @@ -48,9 +49,10 @@ class PagerTree extends NotificationProvider { * Send the message * @param {BeanModel} notification Message title * @param {string} title Message title - * @param {Object} monitorJSON Monitor details (For Up/Down only) + * @param {object} monitorJSON Monitor details (For Up/Down only) + * @param {object} heartbeatJSON Heartbeat details (For Up/Down only) * @param {?string} eventAction Action event for PagerTree (create, resolve) - * @returns {string} + * @returns {Promise} Success state */ async postNotification(notification, title, monitorJSON, heartbeatJSON, eventAction = "create") { diff --git a/server/notification-providers/promosms.js b/server/notification-providers/promosms.js index 572a2132..7ec91971 100644 --- a/server/notification-providers/promosms.js +++ b/server/notification-providers/promosms.js @@ -5,6 +5,9 @@ class PromoSMS extends NotificationProvider { name = "promosms"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; diff --git a/server/notification-providers/pushbullet.js b/server/notification-providers/pushbullet.js index f3d95a85..9fbd4d4c 100644 --- a/server/notification-providers/pushbullet.js +++ b/server/notification-providers/pushbullet.js @@ -7,6 +7,9 @@ class Pushbullet extends NotificationProvider { name = "pushbullet"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; diff --git a/server/notification-providers/pushdeer.js b/server/notification-providers/pushdeer.js index 288137d1..78525a54 100644 --- a/server/notification-providers/pushdeer.js +++ b/server/notification-providers/pushdeer.js @@ -6,6 +6,9 @@ class PushDeer extends NotificationProvider { name = "PushDeer"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; let endpoint = "/message/push"; diff --git a/server/notification-providers/pushover.js b/server/notification-providers/pushover.js index b333b476..31f8d885 100644 --- a/server/notification-providers/pushover.js +++ b/server/notification-providers/pushover.js @@ -5,6 +5,9 @@ class Pushover extends NotificationProvider { name = "pushover"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; let pushoverlink = "https://api.pushover.net/1/messages.json"; diff --git a/server/notification-providers/pushy.js b/server/notification-providers/pushy.js index 1d6e7f32..afb9e617 100644 --- a/server/notification-providers/pushy.js +++ b/server/notification-providers/pushy.js @@ -5,6 +5,9 @@ class Pushy extends NotificationProvider { name = "pushy"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; diff --git a/server/notification-providers/rocket-chat.js b/server/notification-providers/rocket-chat.js index 76b964a3..13b39cde 100644 --- a/server/notification-providers/rocket-chat.js +++ b/server/notification-providers/rocket-chat.js @@ -8,6 +8,9 @@ class RocketChat extends NotificationProvider { name = "rocket.chat"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; try { diff --git a/server/notification-providers/serverchan.js b/server/notification-providers/serverchan.js index d631c8e6..2315e1c3 100644 --- a/server/notification-providers/serverchan.js +++ b/server/notification-providers/serverchan.js @@ -6,6 +6,9 @@ class ServerChan extends NotificationProvider { name = "ServerChan"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; try { @@ -23,8 +26,8 @@ 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) + * @param {?object} heartbeatJSON Heartbeat details (For Up/Down only) + * @param {?object} monitorJSON Monitor details (For Up/Down only) * @returns {string} Formatted title */ checkStatus(heartbeatJSON, monitorJSON) { diff --git a/server/notification-providers/serwersms.js b/server/notification-providers/serwersms.js index 14fe691a..76e1ef2c 100644 --- a/server/notification-providers/serwersms.js +++ b/server/notification-providers/serwersms.js @@ -5,6 +5,9 @@ class SerwerSMS extends NotificationProvider { name = "serwersms"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; diff --git a/server/notification-providers/signal.js b/server/notification-providers/signal.js index 677208ee..c445ee82 100644 --- a/server/notification-providers/signal.js +++ b/server/notification-providers/signal.js @@ -5,6 +5,9 @@ class Signal extends NotificationProvider { name = "signal"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; diff --git a/server/notification-providers/slack.js b/server/notification-providers/slack.js index 41c2bd02..d512a7cd 100644 --- a/server/notification-providers/slack.js +++ b/server/notification-providers/slack.js @@ -10,7 +10,9 @@ class Slack extends NotificationProvider { /** * Deprecated property notification.slackbutton * Set it as primary base url if this is not yet set. + * @deprecated * @param {string} url The primary base URL to use + * @returns {Promise} */ static async deprecateURL(url) { let currentPrimaryBaseURL = await setting("primaryBaseURL"); @@ -25,6 +27,9 @@ class Slack extends NotificationProvider { } } + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; diff --git a/server/notification-providers/smsc.js b/server/notification-providers/smsc.js index 251bc455..34d9c8fa 100644 --- a/server/notification-providers/smsc.js +++ b/server/notification-providers/smsc.js @@ -4,6 +4,9 @@ const axios = require("axios"); class SMSC extends NotificationProvider { name = "smsc"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; try { diff --git a/server/notification-providers/smseagle.js b/server/notification-providers/smseagle.js index c431297e..988f17fd 100644 --- a/server/notification-providers/smseagle.js +++ b/server/notification-providers/smseagle.js @@ -5,6 +5,9 @@ class SMSEagle extends NotificationProvider { name = "SMSEagle"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; diff --git a/server/notification-providers/smsmanager.js b/server/notification-providers/smsmanager.js index 833bff60..7d55d410 100644 --- a/server/notification-providers/smsmanager.js +++ b/server/notification-providers/smsmanager.js @@ -5,6 +5,9 @@ class SMSManager extends NotificationProvider { name = "SMSManager"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { try { let data = { diff --git a/server/notification-providers/smtp.js b/server/notification-providers/smtp.js index 9b59ec09..17072625 100644 --- a/server/notification-providers/smtp.js +++ b/server/notification-providers/smtp.js @@ -6,6 +6,9 @@ class SMTP extends NotificationProvider { name = "smtp"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { const config = { diff --git a/server/notification-providers/splunk.js b/server/notification-providers/splunk.js index 2d82dd39..e07c5103 100644 --- a/server/notification-providers/splunk.js +++ b/server/notification-providers/splunk.js @@ -37,7 +37,8 @@ class Splunk extends NotificationProvider { /** * Check if result is successful, result code should be in range 2xx - * @param {Object} result Axios response object + * @param {object} result Axios response object + * @returns {void} * @throws {Error} The status code is not in range 2xx */ checkResult(result) { @@ -54,9 +55,9 @@ class Splunk extends NotificationProvider { * @param {BeanModel} notification Message title * @param {string} title Message title * @param {string} body Message - * @param {Object} monitorInfo Monitor details (For Up/Down only) + * @param {object} monitorInfo Monitor details (For Up/Down only) * @param {?string} eventAction Action event for PagerDuty (trigger, acknowledge, resolve) - * @returns {string} + * @returns {Promise} Success state */ async postNotification(notification, title, body, monitorInfo, eventAction = "trigger") { diff --git a/server/notification-providers/squadcast.js b/server/notification-providers/squadcast.js index 15553ff7..0b60503d 100644 --- a/server/notification-providers/squadcast.js +++ b/server/notification-providers/squadcast.js @@ -6,6 +6,9 @@ class Squadcast extends NotificationProvider { name = "squadcast"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; diff --git a/server/notification-providers/stackfield.js b/server/notification-providers/stackfield.js index 7f22634e..26c038ea 100644 --- a/server/notification-providers/stackfield.js +++ b/server/notification-providers/stackfield.js @@ -7,6 +7,9 @@ class Stackfield extends NotificationProvider { name = "stackfield"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null) { let okMsg = "Sent Successfully."; try { diff --git a/server/notification-providers/teams.js b/server/notification-providers/teams.js index bcfc82c2..30976cf5 100644 --- a/server/notification-providers/teams.js +++ b/server/notification-providers/teams.js @@ -9,7 +9,7 @@ class Teams extends NotificationProvider { * Generate the message to send * @param {const} status The status constant * @param {string} monitorName Name of monitor - * @returns {string} + * @returns {string} Status message */ _statusMessageFactory = (status, monitorName) => { if (status === DOWN) { @@ -37,11 +37,12 @@ class Teams extends NotificationProvider { /** * Generate payload for notification - * @param {const} status The status of the monitor - * @param {string} monitorMessage Message to send - * @param {string} monitorName Name of monitor affected - * @param {string} monitorUrl URL of monitor affected - * @returns {Object} + * @param {object} args Method arguments + * @param {const} args.status The status of the monitor + * @param {string} args.monitorMessage Message to send + * @param {string} args.monitorName Name of monitor affected + * @param {string} args.monitorUrl URL of monitor affected + * @returns {object} Notification payload */ _notificationPayloadFactory = ({ status, @@ -96,7 +97,8 @@ class Teams extends NotificationProvider { /** * Send the notification * @param {string} webhookUrl URL to send the request to - * @param {Object} payload Payload generated by _notificationPayloadFactory + * @param {object} payload Payload generated by _notificationPayloadFactory + * @returns {Promise} */ _sendNotification = async (webhookUrl, payload) => { await axios.post(webhookUrl, payload); @@ -116,6 +118,9 @@ class Teams extends NotificationProvider { return this._sendNotification(webhookUrl, payload); }; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; diff --git a/server/notification-providers/techulus-push.js b/server/notification-providers/techulus-push.js index 751ff4c3..bfd9503b 100644 --- a/server/notification-providers/techulus-push.js +++ b/server/notification-providers/techulus-push.js @@ -5,6 +5,9 @@ class TechulusPush extends NotificationProvider { name = "PushByTechulus"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; diff --git a/server/notification-providers/telegram.js b/server/notification-providers/telegram.js index 561cabd8..210e3512 100644 --- a/server/notification-providers/telegram.js +++ b/server/notification-providers/telegram.js @@ -5,6 +5,9 @@ class Telegram extends NotificationProvider { name = "telegram"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; diff --git a/server/notification-providers/twilio.js b/server/notification-providers/twilio.js index a908fb21..2abb38b9 100644 --- a/server/notification-providers/twilio.js +++ b/server/notification-providers/twilio.js @@ -5,6 +5,9 @@ class Twilio extends NotificationProvider { name = "twilio"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; diff --git a/server/notification-providers/webhook.js b/server/notification-providers/webhook.js index 9f5643b4..597ef846 100644 --- a/server/notification-providers/webhook.js +++ b/server/notification-providers/webhook.js @@ -7,6 +7,9 @@ class Webhook extends NotificationProvider { name = "webhook"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; diff --git a/server/notification-providers/wecom.js b/server/notification-providers/wecom.js index 1825419a..ea30b26d 100644 --- a/server/notification-providers/wecom.js +++ b/server/notification-providers/wecom.js @@ -6,6 +6,9 @@ class WeCom extends NotificationProvider { name = "WeCom"; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; @@ -26,9 +29,9 @@ class WeCom extends NotificationProvider { /** * Generate the message to send - * @param {Object} heartbeatJSON Heartbeat details (For Up/Down only) + * @param {object} heartbeatJSON Heartbeat details (For Up/Down only) * @param {string} msg General message - * @returns {Object} + * @returns {object} Message */ composeMessage(heartbeatJSON, msg) { let title; diff --git a/server/notification-providers/zoho-cliq.js b/server/notification-providers/zoho-cliq.js index 749647d0..08653e3d 100644 --- a/server/notification-providers/zoho-cliq.js +++ b/server/notification-providers/zoho-cliq.js @@ -10,7 +10,7 @@ class ZohoCliq extends NotificationProvider { * Generate the message to send * @param {const} status The status constant * @param {string} monitorName Name of monitor - * @returns {string} + * @returns {string} Status message */ _statusMessageFactory = (status, monitorName) => { if (status === DOWN) { @@ -25,6 +25,7 @@ class ZohoCliq extends NotificationProvider { * Send the notification * @param {string} webhookUrl URL to send the request to * @param {Array} payload Payload generated by _notificationPayloadFactory + * @returns {Promise} */ _sendNotification = async (webhookUrl, payload) => { await axios.post(webhookUrl, { text: payload.join("\n") }); @@ -32,11 +33,12 @@ class ZohoCliq extends NotificationProvider { /** * Generate payload for notification - * @param {const} status The status of the monitor - * @param {string} monitorMessage Message to send - * @param {string} monitorName Name of monitor affected - * @param {string} monitorUrl URL of monitor affected - * @returns {Array} + * @param {object} args Method arguments + * @param {const} args.status The status of the monitor + * @param {string} args.monitorMessage Message to send + * @param {string} args.monitorName Name of monitor affected + * @param {string} args.monitorUrl URL of monitor affected + * @returns {Array} Notification payload */ _notificationPayloadFactory = ({ status, @@ -74,6 +76,9 @@ class ZohoCliq extends NotificationProvider { return this._sendNotification(webhookUrl, payload); }; + /** + * @inheritdoc + */ async send(notification, msg, monitorJSON = null, heartbeatJSON = null) { let okMsg = "Sent Successfully."; diff --git a/server/notification.js b/server/notification.js index 570c440d..1e717022 100644 --- a/server/notification.js +++ b/server/notification.js @@ -58,7 +58,12 @@ class Notification { providerList = {}; - /** Initialize the notification providers */ + /** + * Initialize the notification providers + * @returns {void} + * @throws Notification provider does not have a name + * @throws Duplicate notification providers in list + */ static init() { log.info("notification", "Prepare Notification Providers"); @@ -133,10 +138,10 @@ class Notification { /** * Send a notification - * @param {BeanModel} notification + * @param {BeanModel} notification Notification to send * @param {string} msg General Message - * @param {Object} monitorJSON Monitor details (For Up/Down only) - * @param {Object} heartbeatJSON Heartbeat details (For Up/Down only) + * @param {object} monitorJSON Monitor details (For Up/Down only) + * @param {object} heartbeatJSON Heartbeat details (For Up/Down only) * @returns {Promise} Successful msg * @throws Error with fail msg */ @@ -150,10 +155,10 @@ class Notification { /** * Save a notification - * @param {Object} notification Notification to save + * @param {object} notification Notification to save * @param {?number} notificationID ID of notification to update * @param {number} userID ID of user who adds notification - * @returns {Promise} + * @returns {Promise} Notification that was saved */ static async save(notification, notificationID, userID) { let bean; diff --git a/server/password-hash.js b/server/password-hash.js index ba228f6b..83a23d9e 100644 --- a/server/password-hash.js +++ b/server/password-hash.js @@ -4,8 +4,8 @@ const saltRounds = 10; /** * Hash a password - * @param {string} password - * @returns {string} + * @param {string} password Password to hash + * @returns {string} Hash */ exports.generate = function (password) { return bcrypt.hashSync(password, saltRounds); @@ -13,8 +13,8 @@ exports.generate = function (password) { /** * Verify a password against a hash - * @param {string} password - * @param {string} hash + * @param {string} password Password to verify + * @param {string} hash Hash to verify against * @returns {boolean} Does the password match the hash? */ exports.verify = function (password, hash) { @@ -27,8 +27,8 @@ exports.verify = function (password, hash) { /** * Is the hash a SHA1 hash - * @param {string} hash - * @returns {boolean} + * @param {string} hash Hash to check + * @returns {boolean} Is SHA1 hash? */ function isSHA1(hash) { return (typeof hash === "string" && hash.startsWith("sha1")); @@ -36,7 +36,8 @@ function isSHA1(hash) { /** * Does the hash need to be rehashed? - * @returns {boolean} + * @param {string} hash Hash to check + * @returns {boolean} Needs to be rehashed? */ exports.needRehash = function (hash) { return isSHA1(hash); diff --git a/server/prometheus.js b/server/prometheus.js index dd04394a..f44af6c1 100644 --- a/server/prometheus.js +++ b/server/prometheus.js @@ -36,7 +36,7 @@ class Prometheus { monitorLabelValues = {}; /** - * @param {Object} monitor Monitor object to monitor + * @param {object} monitor Monitor object to monitor */ constructor(monitor) { this.monitorLabelValues = { @@ -50,8 +50,9 @@ class Prometheus { /** * Update the metrics page - * @param {Object} heartbeat Heartbeat details - * @param {Object} tlsInfo TLS details + * @param {object} heartbeat Heartbeat details + * @param {object} tlsInfo TLS details + * @returns {void} */ update(heartbeat, tlsInfo) { @@ -99,7 +100,10 @@ class Prometheus { } } - /** Remove monitor from prometheus */ + /** + * Remove monitor from prometheus + * @returns {void} + */ remove() { try { monitorCertDaysRemaining.remove(this.monitorLabelValues); diff --git a/server/proxy.js b/server/proxy.js index 660b9b41..a0b4378d 100644 --- a/server/proxy.js +++ b/server/proxy.js @@ -11,11 +11,10 @@ class Proxy { /** * Saves and updates given proxy entity - * - * @param proxy - * @param proxyID - * @param userID - * @return {Promise} + * @param {object} proxy Proxy to store + * @param {number} proxyID ID of proxy to update + * @param {number} userID ID of user the proxy belongs to + * @returns {Promise} Updated proxy */ static async save(proxy, proxyID, userID) { let bean; @@ -65,10 +64,9 @@ class Proxy { /** * Deletes proxy with given id and removes it from monitors - * - * @param proxyID - * @param userID - * @return {Promise} + * @param {number} proxyID ID of proxy to delete + * @param {number} userID ID of proxy owner + * @returns {Promise} */ static async delete(proxyID, userID) { const bean = await R.findOne("proxy", " id = ? AND user_id = ? ", [ proxyID, userID ]); @@ -86,10 +84,10 @@ class Proxy { /** * Create HTTP and HTTPS agents related with given proxy bean object - * - * @param proxy proxy bean object - * @param options http and https agent options - * @return {{httpAgent: Agent, httpsAgent: Agent}} + * @param {object} proxy proxy bean object + * @param {object} options http and https agent options + * @returns {{httpAgent: Agent, httpsAgent: Agent}} New HTTP and HTTPS agents + * @throws Proxy protocol is unsupported */ static createAgents(proxy, options) { const { httpAgentOptions, httpsAgentOptions } = options || {}; @@ -171,10 +169,9 @@ class Proxy { /** * Applies given proxy id to monitors - * - * @param proxyID - * @param userID - * @return {Promise} + * @param {number} proxyID ID of proxy to apply + * @param {number} userID ID of proxy owner + * @returns {Promise} */ async function applyProxyEveryMonitor(proxyID, userID) { // Find all monitors with id and proxy id diff --git a/server/rate-limiter.js b/server/rate-limiter.js index ec77f1a4..3c269b6f 100644 --- a/server/rate-limiter.js +++ b/server/rate-limiter.js @@ -3,7 +3,7 @@ const { log } = require("../src/util"); class KumaRateLimiter { /** - * @param {Object} config Rate limiter configuration object + * @param {object} config Rate limiter configuration object */ constructor(config) { this.errorMessage = config.errorMessage; @@ -13,14 +13,14 @@ class KumaRateLimiter { /** * Callback for pass * @callback passCB - * @param {Object} err Too many requests + * @param {object} err Too many requests */ /** * Should the request be passed through - * @param {passCB} callback - * @param {number} [num=1] Number of tokens to remove - * @returns {Promise} + * @param {passCB} callback Callback function to call with decision + * @param {number} num Number of tokens to remove + * @returns {Promise} Should the request be allowed? */ async pass(callback, num = 1) { const remainingRequests = await this.removeTokens(num); @@ -39,8 +39,8 @@ class KumaRateLimiter { /** * Remove a given number of tokens - * @param {number} [num=1] Number of tokens to remove - * @returns {Promise} + * @param {number} num Number of tokens to remove + * @returns {Promise} Number of remaining tokens */ async removeTokens(num = 1) { return await this.rateLimiter.removeTokens(num); diff --git a/server/server.js b/server/server.js index 7363955b..cedef1d5 100644 --- a/server/server.js +++ b/server/server.js @@ -1699,8 +1699,8 @@ async function updateMonitorNotification(monitorID, notificationIDList) { /** * Check if a given user owns a specific monitor - * @param {number} userID - * @param {number} monitorID + * @param {number} userID ID of user to check + * @param {number} monitorID ID of monitor to check * @returns {Promise} * @throws {Error} The specified user does not own the monitor */ @@ -1719,7 +1719,7 @@ async function checkOwner(userID, monitorID) { * Function called after user login * This function is used to send the heartbeat list of a monitor. * @param {Socket} socket Socket.io instance - * @param {Object} user User object + * @param {object} user User object * @returns {Promise} */ async function afterLogin(socket, user) { @@ -1760,7 +1760,7 @@ async function afterLogin(socket, user) { /** * Initialize the database - * @param {boolean} [testMode=false] Should the connection be + * @param {boolean} testMode Should the connection be * started in test mode? * @returns {Promise} */ @@ -1852,7 +1852,10 @@ async function pauseMonitor(userID, monitorID) { } } -/** Resume active monitors */ +/** + * Resume active monitors + * @returns {Promise} + */ async function startMonitors() { let list = await R.find("monitor", " active = 1 "); @@ -1896,7 +1899,10 @@ async function shutdownFunction(signal) { Settings.stopCacheCleaner(); } -/** Final function called before application exits */ +/** + * Final function called before application exits + * @returns {void} + */ function finalFunction() { log.info("server", "Graceful shutdown successful!"); } diff --git a/server/settings.js b/server/settings.js index 285b626b..4776c554 100644 --- a/server/settings.js +++ b/server/settings.js @@ -96,7 +96,7 @@ class Settings { /** * Get settings based on type * @param {string} type The type of setting - * @returns {Promise} + * @returns {Promise} Settings */ static async getSettings(type) { let list = await R.getAll("SELECT `key`, `value` FROM setting WHERE `type` = ? ", [ @@ -119,7 +119,7 @@ class Settings { /** * Set settings based on type * @param {string} type Type of settings to set - * @param {Object} data Values of settings + * @param {object} data Values of settings * @returns {Promise} */ static async setSettings(type, data) { @@ -150,8 +150,9 @@ class Settings { } /** - * - * @param {string[]} keyList + * Delete selected keys from settings cache + * @param {string[]} keyList Keys to remove + * @returns {void} */ static deleteCache(keyList) { for (let key of keyList) { @@ -159,6 +160,10 @@ class Settings { } } + /** + * Stop the cache cleaner if running + * @returns {void} + */ static stopCacheCleaner() { if (Settings.cacheCleaner) { clearInterval(Settings.cacheCleaner); diff --git a/server/socket-handlers/api-key-socket-handler.js b/server/socket-handlers/api-key-socket-handler.js index 69b0b60d..8a4f5d44 100644 --- a/server/socket-handlers/api-key-socket-handler.js +++ b/server/socket-handlers/api-key-socket-handler.js @@ -9,8 +9,9 @@ const { Settings } = require("../settings"); const { sendAPIKeyList } = require("../client"); /** - * Handlers for Maintenance + * Handlers for API keys * @param {Socket} socket Socket.io instance + * @returns {void} */ module.exports.apiKeySocketHandler = (socket) => { // Add a new api key diff --git a/server/socket-handlers/cloudflared-socket-handler.js b/server/socket-handlers/cloudflared-socket-handler.js index ee58e1ad..809191fe 100644 --- a/server/socket-handlers/cloudflared-socket-handler.js +++ b/server/socket-handlers/cloudflared-socket-handler.js @@ -11,6 +11,7 @@ const cloudflared = new CloudflaredTunnel(); * Change running state * @param {string} running Is it running? * @param {string} message Message to pass + * @returns {void} */ cloudflared.change = (running, message) => { io.to("cloudflared").emit(prefix + "running", running); @@ -19,7 +20,8 @@ cloudflared.change = (running, message) => { /** * Emit an error message - * @param {string} errorMessage + * @param {string} errorMessage Error message to send + * @returns {void} */ cloudflared.error = (errorMessage) => { io.to("cloudflared").emit(prefix + "errorMessage", errorMessage); @@ -28,6 +30,7 @@ cloudflared.error = (errorMessage) => { /** * Handler for cloudflared * @param {Socket} socket Socket.io instance + * @returns {void} */ module.exports.cloudflaredSocketHandler = (socket) => { @@ -89,6 +92,7 @@ module.exports.cloudflaredSocketHandler = (socket) => { /** * Automatically start cloudflared * @param {string} token Cloudflared tunnel token + * @returns {Promise} */ module.exports.autoStart = async (token) => { if (!token) { @@ -106,7 +110,10 @@ module.exports.autoStart = async (token) => { } }; -/** Stop cloudflared */ +/** + * Stop cloudflared + * @returns {Promise} + */ module.exports.stop = async () => { log.info("cloudflared", "Stop cloudflared"); if (cloudflared) { diff --git a/server/socket-handlers/database-socket-handler.js b/server/socket-handlers/database-socket-handler.js index 041cbba0..8441520a 100644 --- a/server/socket-handlers/database-socket-handler.js +++ b/server/socket-handlers/database-socket-handler.js @@ -4,6 +4,7 @@ const Database = require("../database"); /** * Handlers for database * @param {Socket} socket Socket.io instance + * @returns {void} */ module.exports = (socket) => { diff --git a/server/socket-handlers/docker-socket-handler.js b/server/socket-handlers/docker-socket-handler.js index 542f18ce..d7d768f0 100644 --- a/server/socket-handlers/docker-socket-handler.js +++ b/server/socket-handlers/docker-socket-handler.js @@ -6,6 +6,7 @@ const { log } = require("../../src/util"); /** * Handlers for docker hosts * @param {Socket} socket Socket.io instance + * @returns {void} */ module.exports.dockerSocketHandler = (socket) => { socket.on("addDockerHost", async (dockerHost, dockerHostID, callback) => { diff --git a/server/socket-handlers/general-socket-handler.js b/server/socket-handlers/general-socket-handler.js index 2f0c63b4..64ace402 100644 --- a/server/socket-handlers/general-socket-handler.js +++ b/server/socket-handlers/general-socket-handler.js @@ -10,7 +10,7 @@ let gameList = null; /** * Get a game list via GameDig - * @returns {Object[]} list of games supported by GameDig + * @returns {object[]} list of games supported by GameDig */ function getGameList() { if (gameList == null) { diff --git a/server/socket-handlers/maintenance-socket-handler.js b/server/socket-handlers/maintenance-socket-handler.js index ff5bb0fc..348c0a3c 100644 --- a/server/socket-handlers/maintenance-socket-handler.js +++ b/server/socket-handlers/maintenance-socket-handler.js @@ -9,6 +9,7 @@ const server = UptimeKumaServer.getInstance(); /** * Handlers for Maintenance * @param {Socket} socket Socket.io instance + * @returns {void} */ module.exports.maintenanceSocketHandler = (socket) => { // Add a new maintenance diff --git a/server/socket-handlers/proxy-socket-handler.js b/server/socket-handlers/proxy-socket-handler.js index e67a829f..a5f2f478 100644 --- a/server/socket-handlers/proxy-socket-handler.js +++ b/server/socket-handlers/proxy-socket-handler.js @@ -7,6 +7,7 @@ const server = UptimeKumaServer.getInstance(); /** * Handlers for proxy * @param {Socket} socket Socket.io instance + * @returns {void} */ module.exports.proxySocketHandler = (socket) => { socket.on("addProxy", async (proxy, proxyID, callback) => { diff --git a/server/socket-handlers/status-page-socket-handler.js b/server/socket-handlers/status-page-socket-handler.js index eba40dae..427f52d0 100644 --- a/server/socket-handlers/status-page-socket-handler.js +++ b/server/socket-handlers/status-page-socket-handler.js @@ -11,6 +11,7 @@ const { UptimeKumaServer } = require("../uptime-kuma-server"); /** * Socket handlers for status page * @param {Socket} socket Socket.io instance to add listeners on + * @returns {void} */ module.exports.statusPageSocketHandler = (socket) => { @@ -350,6 +351,8 @@ module.exports.statusPageSocketHandler = (socket) => { * Check slug a-z, 0-9, - only * Regex from: https://stackoverflow.com/questions/22454258/js-regex-string-validation-for-slug * @param {string} slug Slug to test + * @returns {void} + * @throws Slug is not valid */ function checkSlug(slug) { if (typeof slug !== "string") { diff --git a/server/uptime-cache-list.js b/server/uptime-cache-list.js index d88a9cbf..3d2a684c 100644 --- a/server/uptime-cache-list.js +++ b/server/uptime-cache-list.js @@ -7,9 +7,9 @@ class UptimeCacheList { /** * Get the uptime for a specific period - * @param {number} monitorID - * @param {number} duration - * @return {number} + * @param {number} monitorID ID of monitor to query + * @param {number} duration Duration to query + * @returns {(number|null)} Uptime for provided duration, if it exists */ static getUptime(monitorID, duration) { if (UptimeCacheList.list[monitorID] && UptimeCacheList.list[monitorID][duration]) { @@ -22,9 +22,10 @@ class UptimeCacheList { /** * Add uptime for specified monitor - * @param {number} monitorID - * @param {number} duration + * @param {number} monitorID ID of monitor to insert for + * @param {number} duration Duration to insert for * @param {number} uptime Uptime to add + * @returns {void} */ static addUptime(monitorID, duration, uptime) { log.debug("UptimeCacheList", "addUptime: " + monitorID + " " + duration); @@ -36,7 +37,8 @@ class UptimeCacheList { /** * Clear cache for specified monitor - * @param {number} monitorID + * @param {number} monitorID ID of monitor to clear + * @returns {void} */ static clearCache(monitorID) { log.debug("UptimeCacheList", "clearCache: " + monitorID); diff --git a/server/uptime-kuma-server.js b/server/uptime-kuma-server.js index 7817c9e1..ce3d0ad0 100644 --- a/server/uptime-kuma-server.js +++ b/server/uptime-kuma-server.js @@ -20,7 +20,7 @@ const path = require("path"); */ class UptimeKumaServer { /** - * + * Current server instance * @type {UptimeKumaServer} */ static instance = null; @@ -49,7 +49,6 @@ class UptimeKumaServer { indexHTML = ""; /** - * * @type {{}} */ static monitorTypeList = { @@ -62,6 +61,12 @@ class UptimeKumaServer { */ jwtSecret = null; + /** + * Get the current instance of the server if it exists, otherwise + * create a new instance. + * @param {object} args Arguments to pass to instance constructor + * @returns {UptimeKumaServer} Server instance + */ static getInstance(args) { if (UptimeKumaServer.instance == null) { UptimeKumaServer.instance = new UptimeKumaServer(args); @@ -69,6 +74,9 @@ class UptimeKumaServer { return UptimeKumaServer.instance; } + /** + * @param {object} args Arguments to initialise server with + */ constructor(args) { // SSL const sslKey = args["ssl-key"] || process.env.UPTIME_KUMA_SSL_KEY || process.env.SSL_KEY || undefined; @@ -106,7 +114,10 @@ class UptimeKumaServer { this.io = new Server(this.httpServer); } - /** Initialise app after the database has been set up */ + /** + * Initialise app after the database has been set up + * @returns {Promise} + */ async initAfterDatabaseReady() { // Static this.app.use("/screenshots", express.static(Database.screenshotDir)); @@ -123,8 +134,8 @@ class UptimeKumaServer { /** * Send list of monitors to client - * @param {Socket} socket - * @returns {Object} List of monitors + * @param {Socket} socket Socket to send list on + * @returns {object} List of monitors */ async sendMonitorList(socket) { let list = await this.getMonitorJSONList(socket.userID); @@ -135,7 +146,7 @@ class UptimeKumaServer { /** * Get a list of monitors for the given user. * @param {string} userID - The ID of the user to get monitors for. - * @returns {Promise} A promise that resolves to an object with monitor IDs as keys and monitor objects as values. + * @returns {Promise} A promise that resolves to an object with monitor IDs as keys and monitor objects as values. * * Generated by Trelent */ @@ -156,7 +167,7 @@ class UptimeKumaServer { /** * Send maintenance list to client * @param {Socket} socket Socket.io instance to send to - * @returns {Object} + * @returns {object} Maintenance list */ async sendMaintenanceList(socket) { return await this.sendMaintenanceListByUserID(socket.userID); @@ -164,8 +175,8 @@ class UptimeKumaServer { /** * Send list of maintenances to user - * @param {number} userID - * @returns {Object} + * @param {number} userID User to send list to + * @returns {object} Maintenance list */ async sendMaintenanceListByUserID(userID) { let list = await this.getMaintenanceJSONList(userID); @@ -176,7 +187,7 @@ class UptimeKumaServer { /** * Get a list of maintenances for the given user. * @param {string} userID - The ID of the user to get maintenances for. - * @returns {Promise} A promise that resolves to an object with maintenance IDs as keys and maintenances objects as values. + * @returns {Promise} A promise that resolves to an object with maintenance IDs as keys and maintenances objects as values. */ async getMaintenanceJSONList(userID) { let result = {}; @@ -188,7 +199,7 @@ class UptimeKumaServer { /** * Load maintenance list and run - * @param userID + * @param {any} userID Unused * @returns {Promise} */ async loadMaintenanceList(userID) { @@ -202,6 +213,11 @@ class UptimeKumaServer { } } + /** + * Retrieve a specific maintenance + * @param {number} maintenanceID ID of maintenance to retrieve + * @returns {(object|null)} Maintenance if it exists + */ getMaintenance(maintenanceID) { if (this.maintenanceList[maintenanceID]) { return this.maintenanceList[maintenanceID]; @@ -213,6 +229,7 @@ class UptimeKumaServer { * Write error to log file * @param {any} error The error to write * @param {boolean} outputToConsole Should the error also be output to console? + * @returns {void} */ static errorLog(error, outputToConsole = true) { const errorLogStream = fs.createWriteStream(path.join(Database.dataDir, "/error.log"), { @@ -237,8 +254,8 @@ class UptimeKumaServer { /** * Get the IP of the client connected to the socket - * @param {Socket} socket - * @returns {string} + * @param {Socket} socket Socket to query + * @returns {string} IP of client */ async getClientIP(socket) { let clientIP = socket.client.conn.remoteAddress; @@ -262,7 +279,7 @@ class UptimeKumaServer { * Attempt to get the current server timezone * If this fails, fall back to environment variables and then make a * guess. - * @returns {Promise} + * @returns {Promise} Current timezone */ async getTimezone() { // From process.env.TZ @@ -307,7 +324,7 @@ class UptimeKumaServer { /** * Get the current offset - * @returns {string} + * @returns {string} Time offset */ getTimezoneOffset() { return dayjs().format("Z"); @@ -315,7 +332,9 @@ class UptimeKumaServer { /** * Throw an error if the timezone is invalid - * @param timezone + * @param {string} timezone Timezone to test + * @returns {void} + * @throws The timezone is invalid */ checkTimezone(timezone) { try { @@ -327,7 +346,8 @@ class UptimeKumaServer { /** * Set the current server timezone and environment variables - * @param {string} timezone + * @param {string} timezone Timezone to set + * @returns {Promise} */ async setTimezone(timezone) { this.checkTimezone(timezone); @@ -355,6 +375,7 @@ class UptimeKumaServer { /** * Start all system services (e.g. nscd) * For now, only used in Docker + * @returns {void} */ startServices() { if (process.env.UPTIME_KUMA_IS_CONTAINER) { @@ -369,6 +390,7 @@ class UptimeKumaServer { /** * Stop all system services + * @returns {void} */ stopServices() { if (process.env.UPTIME_KUMA_IS_CONTAINER) { diff --git a/server/util-server.js b/server/util-server.js index 778e7c6f..44500865 100644 --- a/server/util-server.js +++ b/server/util-server.js @@ -40,7 +40,7 @@ const { Kafka, SASLOptions } = require("kafkajs"); const isWindows = process.platform === /^win/.test(process.platform); /** * Init or reset JWT secret - * @returns {Promise} + * @returns {Promise} JWT secret */ exports.initJWTSecret = async () => { let jwtSecretBean = await R.findOne("setting", " `key` = ? ", [ @@ -60,7 +60,7 @@ exports.initJWTSecret = async () => { /** * Decodes a jwt and returns the payload portion without verifying the jqt. * @param {string} jwt The input jwt as a string - * @returns {Object} Decoded jwt payload object + * @returns {object} Decoded jwt payload object */ exports.decodeJwt = (jwt) => { return JSON.parse(Buffer.from(jwt.split(".")[1], "base64").toString()); @@ -124,7 +124,7 @@ exports.tcping = function (hostname, port) { /** * Ping the specified machine * @param {string} hostname Hostname / address of machine - * @param {number} [size=56] Size of packet to send + * @param {number} size Size of packet to send * @returns {Promise} Time for ping in ms rounded to nearest integer */ exports.ping = async (hostname, size = 56) => { @@ -147,7 +147,7 @@ exports.ping = async (hostname, size = 56) => { * Ping the specified machine * @param {string} hostname Hostname / address of machine to ping * @param {boolean} ipv6 Should IPv6 be used? - * @param {number} [size = 56] Size of ping packet to send + * @param {number} size Size of ping packet to send * @returns {Promise} Time for ping in ms rounded to nearest integer */ exports.pingAsync = function (hostname, ipv6 = false, size = 56) { @@ -179,9 +179,9 @@ exports.pingAsync = function (hostname, ipv6 = false, size = 56) { * @param {string} hostname Hostname / address of machine to test * @param {string} topic MQTT topic * @param {string} okMessage Expected result - * @param {Object} [options={}] MQTT options. Contains port, username, + * @param {object} options MQTT options. Contains port, username, * password and interval (interval defaults to 20) - * @returns {Promise} + * @returns {Promise} Received MQTT message */ exports.mqttAsync = function (hostname, topic, okMessage, options = {}) { return new Promise((resolve, reject) => { @@ -243,16 +243,17 @@ exports.mqttAsync = function (hostname, topic, okMessage, options = {}) { /** * Monitor Kafka using Producer + * @param {string[]} brokers List of kafka brokers to connect, host and + * port joined by ':' * @param {string} topic Topic name to produce into * @param {string} message Message to produce - * @param {Object} [options={interval = 20, allowAutoTopicCreation = false, ssl = false, clientId = "Uptime-Kuma"}] - * Kafka client options. Contains ssl, clientId, allowAutoTopicCreation and - * interval (interval defaults to 20, allowAutoTopicCreation defaults to false, clientId defaults to "Uptime-Kuma" - * and ssl defaults to false) - * @param {string[]} brokers List of kafka brokers to connect, host and port joined by ':' - * @param {SASLOptions} [saslOptions={}] Options for kafka client Authentication (SASL) (defaults to - * {}) - * @returns {Promise} + * @param {object} options Kafka client options. Contains ssl, clientId, + * allowAutoTopicCreation and interval (interval defaults to 20, + * allowAutoTopicCreation defaults to false, clientId defaults to + * "Uptime-Kuma" and ssl defaults to false) + * @param {SASLOptions} saslOptions Options for kafka client + * Authentication (SASL) (defaults to {}) + * @returns {Promise} Status message */ exports.kafkaProducerAsync = function (brokers, topic, message, options = {}, saslOptions = {}) { return new Promise((resolve, reject) => { @@ -331,9 +332,9 @@ exports.kafkaProducerAsync = function (brokers, topic, message, options = {}, sa /** * Use NTLM Auth for a http request. - * @param {Object} options The http request options - * @param {Object} ntlmOptions The auth options - * @returns {Promise<(string[]|Object[]|Object)>} + * @param {object} options The http request options + * @param {object} ntlmOptions The auth options + * @returns {Promise<(string[] | object[] | object)>} NTLM response */ exports.httpNtlm = function (options, ntlmOptions) { return new Promise((resolve, reject) => { @@ -355,7 +356,7 @@ exports.httpNtlm = function (options, ntlmOptions) { * @param {string} resolverServer The DNS server to use * @param {string} resolverPort Port the DNS server is listening on * @param {string} rrtype The type of record to request - * @returns {Promise<(string[]|Object[]|Object)>} + * @returns {Promise<(string[] | object[] | object)>} DNS response */ exports.dnsResolve = function (hostname, resolverServer, resolverPort, rrtype) { const resolver = new Resolver(); @@ -388,7 +389,8 @@ exports.dnsResolve = function (hostname, resolverServer, resolverPort, rrtype) { * Run a query on SQL Server * @param {string} connectionString The database connection string * @param {string} query The query to validate the database with - * @returns {Promise<(string[]|Object[]|Object)>} + * @returns {Promise<(string[] | object[] | object)>} Response from + * server */ exports.mssqlQuery = async function (connectionString, query) { let pool; @@ -409,7 +411,8 @@ exports.mssqlQuery = async function (connectionString, query) { * Run a query on Postgres * @param {string} connectionString The database connection string * @param {string} query The query to validate the database with - * @returns {Promise<(string[]|Object[]|Object)>} + * @returns {Promise<(string[] | object[] | object)>} Response from + * server */ exports.postgresQuery = function (connectionString, query) { return new Promise((resolve, reject) => { @@ -455,7 +458,7 @@ exports.postgresQuery = function (connectionString, query) { * Run a query on MySQL/MariaDB * @param {string} connectionString The database connection string * @param {string} query The query to validate the database with - * @returns {Promise<(string)>} + * @returns {Promise<(string)>} Response from server */ exports.mysqlQuery = function (connectionString, query) { return new Promise((resolve, reject) => { @@ -486,9 +489,10 @@ exports.mysqlQuery = function (connectionString, query) { }; /** - * Connect to and Ping a MongoDB database + * Connect to and ping a MongoDB database * @param {string} connectionString The database connection string - * @returns {Promise<(string[]|Object[]|Object)>} + * @returns {Promise<(string[] | object[] | object)>} Response from + * server */ exports.mongodbPing = async function (connectionString) { let client = await MongoClient.connect(connectionString); @@ -510,9 +514,9 @@ exports.mongodbPing = async function (connectionString) { * @param {string} calledStationId ID of called station * @param {string} callingStationId ID of calling station * @param {string} secret Secret to use - * @param {number} [port=1812] Port to contact radius server on - * @param {number} [timeout=2500] Timeout for connection to use - * @returns {Promise} + * @param {number} port Port to contact radius server on + * @param {number} timeout Timeout for connection to use + * @returns {Promise} Response from server */ exports.radius = function ( hostname, @@ -552,6 +556,7 @@ exports.radius = function ( /** * Redis server ping * @param {string} dsn The redis connection string + * @returns {Promise} Response from redis server */ exports.redisPingAsync = function (dsn) { return new Promise((resolve, reject) => { @@ -593,7 +598,7 @@ exports.setting = async function (key) { }; /** - * Sets the specified setting to specifed value + * Sets the specified setting to specified value * @param {string} key Key of setting to set * @param {any} value Value to set to * @param {?string} type Type of setting @@ -606,7 +611,7 @@ exports.setSetting = async function (key, value, type = null) { /** * Get settings based on type * @param {string} type The type of setting - * @returns {Promise} + * @returns {Promise} Settings of requested type */ exports.getSettings = async function (type) { return await Settings.getSettings(type); @@ -615,7 +620,7 @@ exports.getSettings = async function (type) { /** * Set settings based on type * @param {string} type Type of settings to set - * @param {Object} data Values of settings + * @param {object} data Values of settings * @returns {Promise} */ exports.setSettings = async function (type, data) { @@ -629,7 +634,7 @@ exports.setSettings = async function (type, data) { * Get number of days between two dates * @param {Date} validFrom Start date * @param {Date} validTo End date - * @returns {number} + * @returns {number} Number of days */ const getDaysBetween = (validFrom, validTo) => Math.round(Math.abs(+validFrom - +validTo) / 8.64e7); @@ -638,7 +643,7 @@ const getDaysBetween = (validFrom, validTo) => * Get days remaining from a time range * @param {Date} validFrom Start date * @param {Date} validTo End date - * @returns {number} + * @returns {number} Number of days remaining */ const getDaysRemaining = (validFrom, validTo) => { const daysRemaining = getDaysBetween(validFrom, validTo); @@ -650,8 +655,9 @@ const getDaysRemaining = (validFrom, validTo) => { /** * Fix certificate info for display - * @param {Object} info The chain obtained from getPeerCertificate() - * @returns {Object} An object representing certificate information + * @param {object} info The chain obtained from getPeerCertificate() + * @returns {object} An object representing certificate information + * @throws The certificate chain length exceeded 500. */ const parseCertificateInfo = function (info) { let link = info; @@ -698,8 +704,9 @@ const parseCertificateInfo = function (info) { /** * Check if certificate is valid - * @param {Object} res Response object from axios - * @returns {Object} Object containing certificate information + * @param {object} res Response object from axios + * @returns {object} Object containing certificate information + * @throws No socket was found to check certificate for */ exports.checkCertificate = function (res) { if (!res.request.res.socket) { @@ -757,7 +764,7 @@ exports.checkStatusCode = function (status, acceptedCodes) { * Get total number of clients in room * @param {Server} io Socket server instance * @param {string} roomName Name of room to check - * @returns {number} + * @returns {number} Total clients in room */ exports.getTotalClientInRoom = (io, roomName) => { @@ -784,7 +791,8 @@ exports.getTotalClientInRoom = (io, roomName) => { /** * Allow CORS all origins if development - * @param {Object} res Response object from axios + * @param {object} res Response object from axios + * @returns {void} */ exports.allowDevAllOrigin = (res) => { if (process.env.NODE_ENV === "development") { @@ -794,7 +802,8 @@ exports.allowDevAllOrigin = (res) => { /** * Allow CORS all origins - * @param {Object} res Response object from axios + * @param {object} res Response object from axios + * @returns {void} */ exports.allowAllOrigin = (res) => { res.header("Access-Control-Allow-Origin", "*"); @@ -805,6 +814,8 @@ exports.allowAllOrigin = (res) => { /** * Check if a user is logged in * @param {Socket} socket Socket instance + * @returns {void} + * @throws The user is not logged in */ exports.checkLogin = (socket) => { if (!socket.userID) { @@ -815,8 +826,10 @@ exports.checkLogin = (socket) => { /** * For logged-in users, double-check the password * @param {Socket} socket Socket.io instance - * @param {string} currentPassword - * @returns {Promise} + * @param {string} currentPassword Password to validate + * @returns {Promise} User + * @throws The current password is not a string + * @throws The provided password is not correct */ exports.doubleCheckPassword = async (socket, currentPassword) => { if (typeof currentPassword !== "string") { @@ -834,7 +847,10 @@ exports.doubleCheckPassword = async (socket, currentPassword) => { return user; }; -/** Start Unit tests */ +/** + * Start Unit tests + * @returns {void} + */ exports.startUnitTest = async () => { console.log("Starting unit test..."); const npm = /^win/.test(process.platform) ? "npm.cmd" : "npm"; @@ -854,7 +870,10 @@ exports.startUnitTest = async () => { }); }; -/** Start end-to-end tests */ +/** + * Start end-to-end tests + * @returns {void} + */ exports.startE2eTests = async () => { console.log("Starting unit test..."); const npm = /^win/.test(process.platform) ? "npm.cmd" : "npm"; @@ -877,7 +896,7 @@ exports.startE2eTests = async () => { /** * Convert unknown string to UTF8 * @param {Uint8Array} body Buffer - * @returns {string} + * @returns {string} UTF8 string */ exports.convertToUTF8 = (body) => { const guessEncoding = chardet.detect(body); @@ -889,11 +908,10 @@ exports.convertToUTF8 = (body) => { * Returns a color code in hex format based on a given percentage: * 0% => hue = 10 => red * 100% => hue = 90 => green - * * @param {number} percentage float, 0 to 1 - * @param {number} maxHue - * @param {number} minHue, int - * @returns {string}, hex value + * @param {number} maxHue Maximum hue - int + * @param {number} minHue Minimum hue - int + * @returns {string} Color in hex */ exports.percentageToColor = (percentage, maxHue = 90, minHue = 10) => { const hue = percentage * (maxHue - minHue) + minHue; @@ -906,10 +924,9 @@ exports.percentageToColor = (percentage, maxHue = 90, minHue = 10) => { /** * Joins and array of string to one string after filtering out empty values - * - * @param {string[]} parts - * @param {string} connector - * @returns {string} + * @param {string[]} parts Strings to join + * @param {string} connector Separator for joined strings + * @returns {string} Joined strings */ exports.filterAndJoin = (parts, connector = "") => { return parts.filter((part) => !!part && part !== "").join(connector); @@ -917,8 +934,9 @@ exports.filterAndJoin = (parts, connector = "") => { /** * Send an Error response - * @param {Object} res Express response object - * @param {string} [msg=""] Message to send + * @param {object} res Express response object + * @param {string} msg Message to send + * @returns {void} */ module.exports.sendHttpError = (res, msg = "") => { if (msg.includes("SQLITE_BUSY") || msg.includes("SQLITE_LOCKED")) { @@ -939,6 +957,13 @@ module.exports.sendHttpError = (res, msg = "") => { } }; +/** + * Convert timezone of time object + * @param {object} obj Time object to update + * @param {string} timezone New timezone to set + * @param {boolean} timeObjectToUTC Convert time object to UTC + * @returns {object} Time object with updated timezone + */ function timeObjectConvertTimezone(obj, timezone, timeObjectToUTC = true) { let offsetString; @@ -981,20 +1006,20 @@ function timeObjectConvertTimezone(obj, timezone, timeObjectToUTC = true) { } /** - * - * @param {object} obj - * @param {string} timezone - * @returns {object} + * Convert time object to UTC + * @param {object} obj Object to convert + * @param {string} timezone Timezone of time object + * @returns {object} Updated time object */ module.exports.timeObjectToUTC = (obj, timezone = undefined) => { return timeObjectConvertTimezone(obj, timezone, true); }; /** - * - * @param {object} obj - * @param {string} timezone - * @returns {object} + * Convert time object to local time + * @param {object} obj Object to convert + * @param {string} timezone Timezone to convert to + * @returns {object} Updated object */ module.exports.timeObjectToLocal = (obj, timezone = undefined) => { return timeObjectConvertTimezone(obj, timezone, false); @@ -1002,7 +1027,8 @@ module.exports.timeObjectToLocal = (obj, timezone = undefined) => { /** * Create gRPC client stib - * @param {Object} options from gRPC client + * @param {object} options from gRPC client + * @returns {Promise} Result of gRPC query */ module.exports.grpcQuery = async (options) => { const { grpcUrl, grpcProtobufData, grpcServiceName, grpcEnableTls, grpcMethod, grpcBody } = options; diff --git a/src/components/APIKeyDialog.vue b/src/components/APIKeyDialog.vue index 4bba69fe..ac9cffe3 100644 --- a/src/components/APIKeyDialog.vue +++ b/src/components/APIKeyDialog.vue @@ -126,6 +126,7 @@ export default { methods: { /** * Show modal + * @returns {void} */ show() { this.id = null; @@ -138,7 +139,10 @@ export default { this.keyaddmodal.show(); }, - /** Submit data to server */ + /** + * Submit data to server + * @returns {Promise} + */ async submit() { this.processing = true; @@ -159,7 +163,10 @@ export default { }); }, - /** Clear Form inputs */ + /** + * Clear Form inputs + * @returns {void} + */ clearForm() { this.key = { name: "", diff --git a/src/components/BadgeGeneratorDialog.vue b/src/components/BadgeGeneratorDialog.vue index aa6fa6e8..5ae0a877 100644 --- a/src/components/BadgeGeneratorDialog.vue +++ b/src/components/BadgeGeneratorDialog.vue @@ -279,8 +279,9 @@ export default { methods: { /** * Setting monitor - * @param {number} monitorId ID of monitor - * @param {string} monitorName Name of monitor + * @param {number} monitorId ID of monitor + * @param {string} monitorName Name of monitor + * @returns {void} */ show(monitorId, monitorName) { this.monitor = { diff --git a/src/components/CertificateInfoRow.vue b/src/components/CertificateInfoRow.vue index f02d1d7b..8a4a875c 100644 --- a/src/components/CertificateInfoRow.vue +++ b/src/components/CertificateInfoRow.vue @@ -65,9 +65,9 @@ export default { methods: { /** * Format the subject of the certificate - * @param {Object} subject Object representing the certificates + * @param {object} subject Object representing the certificates * subject - * @returns {string} + * @returns {string} Certificate subject */ formatSubject(subject) { if (subject.O && subject.CN && subject.C) { diff --git a/src/components/Confirm.vue b/src/components/Confirm.vue index 4bc2217c..e855b676 100644 --- a/src/components/Confirm.vue +++ b/src/components/Confirm.vue @@ -58,18 +58,23 @@ export default { this.modal = new Modal(this.$refs.modal); }, methods: { - /** Show the confirm dialog */ + /** + * Show the confirm dialog + * @returns {void} + */ show() { this.modal.show(); }, /** - * @emits string "yes" Notify the parent when Yes is pressed + * @fires string "yes" Notify the parent when Yes is pressed + * @returns {void} */ yes() { this.$emit("yes"); }, /** - * @emits string "no" Notify the parent when No is pressed + * @fires string "no" Notify the parent when No is pressed + * @returns {void} */ no() { this.$emit("no"); diff --git a/src/components/CopyableInput.vue b/src/components/CopyableInput.vue index 943193f4..951fded9 100644 --- a/src/components/CopyableInput.vue +++ b/src/components/CopyableInput.vue @@ -90,19 +90,25 @@ export default { }, methods: { - /** Show the input */ + /** + * Show the input + * @returns {void} + */ showInput() { this.visibility = "text"; }, - /** Hide the input */ + /** + * Hide the input + * @returns {void} + */ hideInput() { this.visibility = "password"; }, /** * Copy the provided text to the users clipboard - * @param {string} textToCopy + * @param {string} textToCopy Text to copy to clipboard * @returns {Promise} */ copyToClipboard(textToCopy) { diff --git a/src/components/CreateGroupDialog.vue b/src/components/CreateGroupDialog.vue index ed20610c..ba7fe6eb 100644 --- a/src/components/CreateGroupDialog.vue +++ b/src/components/CreateGroupDialog.vue @@ -43,10 +43,17 @@ export default { this.modal = new Modal(this.$refs.modal); }, methods: { - /** Show the confirm dialog */ + /** + * Show the confirm dialog + * @returns {void} + */ show() { this.modal.show(); }, + /** + * Dialog confirmed + * @returns {void} + */ confirm() { this.$emit("added", this.groupName); this.modal.hide(); diff --git a/src/components/DockerHostDialog.vue b/src/components/DockerHostDialog.vue index 335e8f2b..2744264a 100644 --- a/src/components/DockerHostDialog.vue +++ b/src/components/DockerHostDialog.vue @@ -91,7 +91,10 @@ export default { }, methods: { - /** Confirm deletion of docker host */ + /** + * Confirm deletion of docker host + * @returns {void} + */ deleteConfirm() { this.modal.hide(); this.$refs.confirmDelete.show(); @@ -99,7 +102,8 @@ export default { /** * Show specified docker host - * @param {number} dockerHostID + * @param {number} dockerHostID ID of host to show + * @returns {void} */ show(dockerHostID) { if (dockerHostID) { @@ -131,7 +135,10 @@ export default { this.modal.show(); }, - /** Add docker host */ + /** + * Add docker host + * @returns {void} + */ submit() { this.processing = true; this.$root.getSocket().emit("addDockerHost", this.dockerHost, this.id, (res) => { @@ -150,7 +157,10 @@ export default { }); }, - /** Test the docker host */ + /** + * Test the docker host + * @returns {void} + */ test() { this.processing = true; this.$root.getSocket().emit("testDockerHost", this.dockerHost, (res) => { @@ -159,7 +169,10 @@ export default { }); }, - /** Delete this docker host */ + /** + * Delete this docker host + * @returns {void} + */ deleteDockerHost() { this.processing = true; this.$root.getSocket().emit("deleteDockerHost", this.id, (res) => { diff --git a/src/components/HeartbeatBar.vue b/src/components/HeartbeatBar.vue index 8323f7cf..376d88ab 100644 --- a/src/components/HeartbeatBar.vue +++ b/src/components/HeartbeatBar.vue @@ -56,6 +56,7 @@ export default { /** * If heartbeatList is null, get it from $root.heartbeatList + * @returns {object} Heartbeat list */ beatList() { if (this.heartbeatList === null) { @@ -241,7 +242,10 @@ export default { this.resize(); }, methods: { - /** Resize the heartbeat bar */ + /** + * Resize the heartbeat bar + * @returns {void} + */ resize() { if (this.$refs.wrap) { this.maxBeat = Math.floor(this.$refs.wrap.clientWidth / (this.beatWidth + this.beatMargin * 2)); @@ -251,8 +255,8 @@ export default { /** * Get the title of the beat. * Used as the hover tooltip on the heartbeat bar. - * @param {Object} beat Beat to get title from - * @returns {string} + * @param {object} beat Beat to get title from + * @returns {string} Beat title */ getBeatTitle(beat) { return `${this.$root.datetime(beat.time)}` + ((beat.msg) ? ` - ${beat.msg}` : ""); diff --git a/src/components/HiddenInput.vue b/src/components/HiddenInput.vue index fb86a398..85ff8837 100644 --- a/src/components/HiddenInput.vue +++ b/src/components/HiddenInput.vue @@ -74,11 +74,17 @@ export default { }, methods: { - /** Show users input in plain text */ + /** + * Show users input in plain text + * @returns {void} + */ showInput() { this.visibility = "text"; }, - /** Censor users input */ + /** + * Censor users input + * @returns {void} + */ hideInput() { this.visibility = "password"; }, diff --git a/src/components/Login.vue b/src/components/Login.vue index 0a0266e7..f9ec9798 100644 --- a/src/components/Login.vue +++ b/src/components/Login.vue @@ -64,7 +64,10 @@ export default { }, methods: { - /** Submit the user details and attempt to log in */ + /** + * Submit the user details and attempt to log in + * @returns {void} + */ submit() { this.processing = true; diff --git a/src/components/MonitorList.vue b/src/components/MonitorList.vue index fd6fd1a4..e5cac1a3 100644 --- a/src/components/MonitorList.vue +++ b/src/components/MonitorList.vue @@ -103,6 +103,7 @@ export default { * Improve the sticky appearance of the list by increasing its * height as user scrolls down. * Not used on mobile. + * @returns {object} Style for monitor list */ boxStyle() { if (window.innerWidth > 550) { @@ -267,7 +268,10 @@ export default { window.removeEventListener("scroll", this.onScroll); }, methods: { - /** Handle user scroll */ + /** + * Handle user scroll + * @returns {void} + */ onScroll() { if (window.top.scrollY <= 133) { this.windowTop = window.top.scrollY; @@ -283,13 +287,17 @@ export default { monitorURL(id) { return getMonitorRelativeURL(id); }, - /** Clear the search bar */ + /** + * Clear the search bar + * @returns {void} + */ clearSearchText() { this.searchText = ""; }, /** * Update the MonitorList Filter * @param {object} newFilter Object with new filter + * @returns {void} */ updateFilter(newFilter) { this.filterState = newFilter; @@ -297,6 +305,7 @@ export default { /** * Deselect a monitor * @param {number} id ID of monitor + * @returns {void} */ deselect(id) { delete this.selectedMonitors[id]; @@ -304,6 +313,7 @@ export default { /** * Select a monitor * @param {number} id ID of monitor + * @returns {void} */ select(id) { this.selectedMonitors[id] = true; @@ -311,21 +321,30 @@ export default { /** * Determine if monitor is selected * @param {number} id ID of monitor - * @returns {bool} + * @returns {bool} Is the monitor selected? */ isSelected(id) { return id in this.selectedMonitors; }, - /** Disable select mode and reset selection */ + /** + * Disable select mode and reset selection + * @returns {void} + */ cancelSelectMode() { this.selectMode = false; this.selectedMonitors = {}; }, - /** Show dialog to confirm pause */ + /** + * Show dialog to confirm pause + * @returns {void} + */ pauseDialog() { this.$refs.confirmPause.show(); }, - /** Pause each selected monitor */ + /** + * Pause each selected monitor + * @returns {void} + */ pauseSelected() { Object.keys(this.selectedMonitors) .filter(id => this.$root.monitorList[id].active) @@ -333,7 +352,10 @@ export default { this.cancelSelectMode(); }, - /** Resume each selected monitor */ + /** + * Resume each selected monitor + * @returns {void} + */ resumeSelected() { Object.keys(this.selectedMonitors) .filter(id => !this.$root.monitorList[id].active) diff --git a/src/components/MonitorListItem.vue b/src/components/MonitorListItem.vue index 4013b1e3..5b844968 100644 --- a/src/components/MonitorListItem.vue +++ b/src/components/MonitorListItem.vue @@ -189,7 +189,9 @@ export default { }, methods: { /** - * Changes the collapsed value of the current monitor and saves it to local storage + * Changes the collapsed value of the current monitor and saves + * it to local storage + * @returns {void} */ changeCollapsed() { this.isCollapsed = !this.isCollapsed; @@ -214,6 +216,7 @@ export default { }, /** * Toggle selection of monitor + * @returns {void} */ toggleSelection() { if (this.isSelected(this.monitor.id)) { diff --git a/src/components/MonitorSettingDialog.vue b/src/components/MonitorSettingDialog.vue index d8e9da1a..e6b2cd1e 100644 --- a/src/components/MonitorSettingDialog.vue +++ b/src/components/MonitorSettingDialog.vue @@ -67,8 +67,9 @@ export default { methods: { /** * Setting monitor - * @param {Object} group Data of monitor - * @param {Object} monitor Data of monitor + * @param {object} group Data of monitor + * @param {object} monitor Data of monitor + * @returns {void} */ show(group, monitor) { this.monitor = { @@ -86,6 +87,7 @@ export default { * Toggle the value of sendUrl * @param {number} groupIndex Index of group monitor is member of * @param {number} index Index of monitor within group + * @returns {void} */ toggleLink(groupIndex, index) { this.$root.publicGroupList[groupIndex].monitorList[index].sendUrl = !this.$root.publicGroupList[groupIndex].monitorList[index].sendUrl; @@ -95,10 +97,10 @@ export default { * Should a link to the monitor be shown? * Attempts to guess if a link should be shown based upon if * sendUrl is set and if the URL is default or not. - * @param {Object} monitor Monitor to check - * @param {boolean} [ignoreSendUrl=false] Should the presence of the sendUrl + * @param {object} monitor Monitor to check + * @param {boolean} ignoreSendUrl Should the presence of the sendUrl * property be ignored. This will only work in edit mode. - * @returns {boolean} + * @returns {boolean} Should the link be shown? */ showLink(monitor, ignoreSendUrl = false) { // We must check if there are any elements in monitorList to diff --git a/src/components/NotificationDialog.vue b/src/components/NotificationDialog.vue index f7fce0d3..170a1d4c 100644 --- a/src/components/NotificationDialog.vue +++ b/src/components/NotificationDialog.vue @@ -218,7 +218,10 @@ export default { }, methods: { - /** Show dialog to confirm deletion */ + /** + * Show dialog to confirm deletion + * @returns {void} + */ deleteConfirm() { this.modal.hide(); this.$refs.confirmDelete.show(); @@ -227,6 +230,7 @@ export default { /** * Show settings for specified notification * @param {number} notificationID ID of notification to show + * @returns {void} */ show(notificationID) { if (notificationID) { @@ -250,7 +254,10 @@ export default { this.modal.show(); }, - /** Submit the form to the server */ + /** + * Submit the form to the server + * @returns {void} + */ submit() { this.processing = true; this.$root.getSocket().emit("addNotification", this.notification, this.id, (res) => { @@ -269,7 +276,10 @@ export default { }); }, - /** Test the notification endpoint */ + /** + * Test the notification endpoint + * @returns {void} + */ test() { this.processing = true; this.$root.getSocket().emit("testNotification", this.notification, (res) => { @@ -278,7 +288,10 @@ export default { }); }, - /** Delete the notification endpoint */ + /** + * Delete the notification endpoint + * @returns {void} + */ deleteNotification() { this.processing = true; this.$root.getSocket().emit("deleteNotification", this.id, (res) => { @@ -293,7 +306,8 @@ export default { /** * Get a unique default name for the notification * @param {keyof NotificationFormList} notificationKey - * @return {string} + * Notification to retrieve + * @returns {string} Default name */ getUniqueDefaultName(notificationKey) { diff --git a/src/components/ProxyDialog.vue b/src/components/ProxyDialog.vue index 74e5878b..fc92359b 100644 --- a/src/components/ProxyDialog.vue +++ b/src/components/ProxyDialog.vue @@ -131,7 +131,10 @@ export default { }, methods: { - /** Show dialog to confirm deletion */ + /** + * Show dialog to confirm deletion + * @returns {void} + */ deleteConfirm() { this.modal.hide(); this.$refs.confirmDelete.show(); @@ -140,6 +143,7 @@ export default { /** * Show settings for specified proxy * @param {number} proxyID ID of proxy to show + * @returns {void} */ show(proxyID) { if (proxyID) { @@ -169,7 +173,10 @@ export default { this.modal.show(); }, - /** Submit form data for saving */ + /** + * Submit form data for saving + * @returns {void} + */ submit() { this.processing = true; this.$root.getSocket().emit("addProxy", this.proxy, this.id, (res) => { @@ -187,7 +194,10 @@ export default { }); }, - /** Delete this proxy */ + /** + * Delete this proxy + * @returns {void} + */ deleteProxy() { this.processing = true; this.$root.getSocket().emit("deleteProxy", this.id, (res) => { diff --git a/src/components/PublicGroupList.vue b/src/components/PublicGroupList.vue index ba2230f0..ce0a645b 100644 --- a/src/components/PublicGroupList.vue +++ b/src/components/PublicGroupList.vue @@ -131,6 +131,7 @@ export default { /** * Remove the specified group * @param {number} index Index of group to remove + * @returns {void} */ removeGroup(index) { this.$root.publicGroupList.splice(index, 1); @@ -141,6 +142,7 @@ export default { * @param {number} groupIndex Index of group to remove monitor * from * @param {number} index Index of monitor to remove + * @returns {void} */ removeMonitor(groupIndex, index) { this.$root.publicGroupList[groupIndex].monitorList.splice(index, 1); @@ -150,10 +152,10 @@ export default { * Should a link to the monitor be shown? * Attempts to guess if a link should be shown based upon if * sendUrl is set and if the URL is default or not. - * @param {Object} monitor Monitor to check - * @param {boolean} [ignoreSendUrl=false] Should the presence of the sendUrl + * @param {object} monitor Monitor to check + * @param {boolean} ignoreSendUrl Should the presence of the sendUrl * property be ignored. This will only work in edit mode. - * @returns {boolean} + * @returns {boolean} Should the link be shown */ showLink(monitor, ignoreSendUrl = false) { // We must check if there are any elements in monitorList to @@ -166,8 +168,8 @@ export default { /** * Returns formatted certificate expiry or Bad cert message - * @param {Object} monitor Monitor to show expiry for - * @returns {string} + * @param {object} monitor Monitor to show expiry for + * @returns {string} Certificate expiry message */ formattedCertExpiryMessage(monitor) { if (monitor?.element?.validCert && monitor?.element?.certExpiryDaysRemaining) { @@ -180,9 +182,9 @@ export default { }, /** - * Returns certificate expiry based on days remaining - * @param {Object} monitor Monitor to show expiry for - * @returns {string} + * Returns certificate expiry color based on days remaining + * @param {object} monitor Monitor to show expiry for + * @returns {string} Color for certificate expiry */ certExpiryColor(monitor) { if (monitor?.element?.validCert && monitor.element.certExpiryDaysRemaining > 7) { diff --git a/src/components/Tag.vue b/src/components/Tag.vue index 956eea3e..6c2ff8c9 100644 --- a/src/components/Tag.vue +++ b/src/components/Tag.vue @@ -19,12 +19,13 @@