diff --git a/ghost/api-framework/lib/http.js b/ghost/api-framework/lib/http.js index 369ce13aa4..65188185f8 100644 --- a/ghost/api-framework/lib/http.js +++ b/ghost/api-framework/lib/http.js @@ -11,9 +11,14 @@ const headers = require('./headers'); * The wrapper receives the express request, prepares the frame and forwards the request to the pipeline. * * @param {Function} apiImpl - Pipeline wrapper, which executes the target ctrl function. - * @return {Function} + * @return {import('express').RequestHandler} */ const http = (apiImpl) => { + /** + * @param {import('express').Request} req - Express request object. + * @param {import('express').Response} res - Express response object. + * @param {import('express').NextFunction} next - Express next function. + */ return async function Http(req, res, next) { debug(`External API request to ${req.url}`); let apiKey = null; diff --git a/ghost/core/core/server/GhostServer.js b/ghost/core/core/server/GhostServer.js index ebcbe0fab5..dd6c1eeddc 100644 --- a/ghost/core/core/server/GhostServer.js +++ b/ghost/core/core/server/GhostServer.js @@ -67,7 +67,7 @@ class GhostServer { * Starts the ghost server listening on the configured port. * Requires an express app to be passed in * - * @param {Object} rootApp - Required express app instance. + * @param {import('express').Application} rootApp - Required express app instance. * @return {Promise} Resolves once Ghost has started */ start(rootApp) { diff --git a/ghost/core/core/server/web/admin/app.js b/ghost/core/core/server/web/admin/app.js index d67dc2b7b5..02280dbb9d 100644 --- a/ghost/core/core/server/web/admin/app.js +++ b/ghost/core/core/server/web/admin/app.js @@ -10,6 +10,10 @@ const errorHandler = require('@tryghost/mw-error-handler'); const sentry = require('../../../shared/sentry'); const redirectAdminUrls = require('./middleware/redirect-admin-urls'); +/** + * + * @returns {import('express').Application} + */ module.exports = function setupAdminApp() { debug('Admin setup start'); const adminApp = express('admin'); diff --git a/ghost/core/core/server/web/admin/controller.js b/ghost/core/core/server/web/admin/controller.js index 20277694b7..eee566cd4b 100644 --- a/ghost/core/core/server/web/admin/controller.js +++ b/ghost/core/core/server/web/admin/controller.js @@ -20,8 +20,8 @@ const messages = { * * Every request to the admin panel will re-trigger the update check service. * - * @param req - * @param res + * @param {import('express').Request} req + * @param {import('express').Response} res */ module.exports = function adminController(req, res) { debug('index called'); diff --git a/ghost/core/core/server/web/admin/middleware/redirect-admin-urls.js b/ghost/core/core/server/web/admin/middleware/redirect-admin-urls.js index 097c0d784a..09d08d1047 100644 --- a/ghost/core/core/server/web/admin/middleware/redirect-admin-urls.js +++ b/ghost/core/core/server/web/admin/middleware/redirect-admin-urls.js @@ -1,5 +1,11 @@ const urlUtils = require('../../../../shared/url-utils'); +/** + * + * @param {import('express').Request} req + * @param {import('express').Response} res + * @param {import('express').NextFunction} next + */ function redirectAdminUrls(req, res, next) { const subdir = urlUtils.getSubdir(); const ghostPathRegex = new RegExp(`^${subdir}/ghost/(.+)`); diff --git a/ghost/core/core/server/web/announcement/routes.js b/ghost/core/core/server/web/announcement/routes.js index 9b97b2358a..054069e75c 100644 --- a/ghost/core/core/server/web/announcement/routes.js +++ b/ghost/core/core/server/web/announcement/routes.js @@ -3,6 +3,9 @@ const api = require('../../api').endpoints; const {http} = require('@tryghost/api-framework'); const shared = require('../shared'); +/** + * @returns {import('express').Router} + */ module.exports = function apiRoutes() { const router = express.Router('announcements'); diff --git a/ghost/core/core/server/web/api/app.js b/ghost/core/core/server/web/api/app.js index cb26e1e18b..a99445d54d 100644 --- a/ghost/core/core/server/web/api/app.js +++ b/ghost/core/core/server/web/api/app.js @@ -5,6 +5,9 @@ const sentry = require('../../../shared/sentry'); const errorHandler = require('@tryghost/mw-error-handler'); const APIVersionCompatibilityService = require('../../services/api-version-compatibility'); +/** + * @returns {import('express').Application} + */ module.exports = function setupApiApp() { debug('Parent API setup start'); const apiApp = express('api'); diff --git a/ghost/core/core/server/web/api/endpoints/admin/app.js b/ghost/core/core/server/web/api/endpoints/admin/app.js index f315febc38..f8e340528a 100644 --- a/ghost/core/core/server/web/api/endpoints/admin/app.js +++ b/ghost/core/core/server/web/api/endpoints/admin/app.js @@ -12,6 +12,9 @@ const routes = require('./routes'); const APIVersionCompatibilityService = require('../../../../services/api-version-compatibility'); const GhostNestApp = require('@tryghost/ghost'); +/** + * @returns {import('express').Application} + */ module.exports = function setupApiApp() { debug('Admin API setup start'); const apiApp = express('admin api'); diff --git a/ghost/core/core/server/web/api/endpoints/admin/middleware.js b/ghost/core/core/server/web/api/endpoints/admin/middleware.js index a3595c061c..ab4dde91fc 100644 --- a/ghost/core/core/server/web/api/endpoints/admin/middleware.js +++ b/ghost/core/core/server/web/api/endpoints/admin/middleware.js @@ -8,6 +8,11 @@ const messages = { notImplemented: 'The server does not support the functionality required to fulfill the request.' }; +/** + * @param {import('express').Request} req + * @param {import('express').Response} res + * @param {import('express').NextFunction} next + */ const notImplemented = function notImplemented(req, res, next) { // CASE: user is logged in, allow if (!req.api_key) { @@ -63,8 +68,12 @@ const notImplemented = function notImplemented(req, res, next) { })); }; +/** @typedef {import('express').RequestHandler} RequestHandler */ + /** * Authentication for private endpoints + * + * @type {RequestHandler[]} */ module.exports.authAdminApi = [ auth.authenticate.authenticateAdminApi, @@ -79,6 +88,8 @@ module.exports.authAdminApi = [ /** * Authentication for private endpoints with token in URL * Ex.: For scheduler publish endpoint + * + * @type {RequestHandler[]} */ module.exports.authAdminApiWithUrl = [ auth.authenticate.authenticateAdminApiWithUrl, @@ -92,6 +103,8 @@ module.exports.authAdminApiWithUrl = [ /** * Middleware for public admin endpoints + * + * @type {RequestHandler[]} */ module.exports.publicAdminApi = [ apiMw.cors, diff --git a/ghost/core/core/server/web/api/endpoints/admin/routes.js b/ghost/core/core/server/web/api/endpoints/admin/routes.js index 52791c3bc3..3ea39dbb7f 100644 --- a/ghost/core/core/server/web/api/endpoints/admin/routes.js +++ b/ghost/core/core/server/web/api/endpoints/admin/routes.js @@ -7,6 +7,9 @@ const mw = require('./middleware'); const shared = require('../../../shared'); const labs = require('../../../../../shared/labs'); +/** + * @returns {import('express').Router} + */ module.exports = function apiRoutes() { const router = express.Router('admin api'); diff --git a/ghost/core/core/server/web/api/endpoints/content/app.js b/ghost/core/core/server/web/api/endpoints/content/app.js index 7d8aa98b89..0d6c371143 100644 --- a/ghost/core/core/server/web/api/endpoints/content/app.js +++ b/ghost/core/core/server/web/api/endpoints/content/app.js @@ -9,6 +9,9 @@ const routes = require('./routes'); const errorHandler = require('@tryghost/mw-error-handler'); const apiVersionCompatibility = require('../../../../services/api-version-compatibility'); +/** + * @returns {import('express').Application} + */ module.exports = function setupApiApp() { debug('Content API setup start'); const apiApp = express('content api'); diff --git a/ghost/core/core/server/web/api/endpoints/content/middleware.js b/ghost/core/core/server/web/api/endpoints/content/middleware.js index b16cfd947d..c5c484c95b 100644 --- a/ghost/core/core/server/web/api/endpoints/content/middleware.js +++ b/ghost/core/core/server/web/api/endpoints/content/middleware.js @@ -12,6 +12,8 @@ const shared = require('../../../shared'); /** * Authentication for public endpoints + * + * @type {import('express').RequestHandler[]} */ module.exports.authenticatePublic = [ shared.middleware.brute.contentApiKey, diff --git a/ghost/core/core/server/web/api/endpoints/content/routes.js b/ghost/core/core/server/web/api/endpoints/content/routes.js index 8d23e81b28..1db03d362a 100644 --- a/ghost/core/core/server/web/api/endpoints/content/routes.js +++ b/ghost/core/core/server/web/api/endpoints/content/routes.js @@ -5,6 +5,9 @@ const {http} = require('@tryghost/api-framework'); const mw = require('./middleware'); const config = require('../../../../../shared/config'); +/** + * @returns {import('express').Router} + */ module.exports = function apiRoutes() { const router = express.Router('content api'); diff --git a/ghost/core/core/server/web/api/middleware/upload.js b/ghost/core/core/server/web/api/middleware/upload.js index 165ec209cf..30549356a6 100644 --- a/ghost/core/core/server/web/api/middleware/upload.js +++ b/ghost/core/core/server/web/api/middleware/upload.js @@ -156,10 +156,16 @@ const checkFileIsValid = (fileData, types, extensions) => { * * @param {Object} options * @param {String} options.type - type of the file - * @returns {Function} + * @returns {import('express').RequestHandler} */ const validation = function ({type}) { // if we finish the data/importer logic, we forward the request to the specified importer + + /** + * @param {import('express').Request} req + * @param {import('express').Response} res + * @param {import('express').NextFunction} next + */ return function uploadValidation(req, res, next) { const extensions = (config.get('uploads')[type] && config.get('uploads')[type].extensions) || []; const contentTypes = (config.get('uploads')[type] && config.get('uploads')[type].contentTypes) || []; @@ -192,7 +198,7 @@ const validation = function ({type}) { * * @param {Object} options * @param {String} options.type - type of the file - * @returns {Function} + * @returns {import('express').RequestHandler} */ const mediaValidation = function ({type}) { return function mediaUploadValidation(req, res, next) { diff --git a/ghost/core/core/server/web/comments/routes.js b/ghost/core/core/server/web/comments/routes.js index b2c731c34c..82a350674d 100644 --- a/ghost/core/core/server/web/comments/routes.js +++ b/ghost/core/core/server/web/comments/routes.js @@ -7,6 +7,9 @@ const shared = require('../shared'); const bodyParser = require('body-parser'); const membersService = require('../../../server/services/members'); +/** + * @returns {import('express').Router} + */ module.exports = function apiRoutes() { const router = express.Router('comment api'); router.use(bodyParser.json({limit: '50mb'})); diff --git a/ghost/core/core/server/web/members/app.js b/ghost/core/core/server/web/members/app.js index df8daaa79d..89311ea8ea 100644 --- a/ghost/core/core/server/web/members/app.js +++ b/ghost/core/core/server/web/members/app.js @@ -16,6 +16,9 @@ const api = require('../../api').endpoints; const commentRouter = require('../comments'); const announcementRouter = require('../announcement'); +/** + * @returns {import('express').Application} + */ module.exports = function setupMembersApp() { debug('Members App setup start'); const membersApp = express('members'); diff --git a/ghost/core/core/server/web/parent/app.js b/ghost/core/core/server/web/parent/app.js index 2a1c8d9a4b..bbc698966a 100644 --- a/ghost/core/core/server/web/parent/app.js +++ b/ghost/core/core/server/web/parent/app.js @@ -4,6 +4,9 @@ const express = require('../../../shared/express'); const compress = require('compression'); const mw = require('./middleware'); +/** + * @returns {import('express').Application} + */ module.exports = function setupParentApp() { debug('ParentApp setup start'); const parentApp = express('parent'); diff --git a/ghost/core/core/server/web/parent/backend.js b/ghost/core/core/server/web/parent/backend.js index 792ef3686a..66c1019340 100644 --- a/ghost/core/core/server/web/parent/backend.js +++ b/ghost/core/core/server/web/parent/backend.js @@ -4,7 +4,7 @@ const {BASE_API_PATH} = require('../../../shared/url-utils'); /** * - * @returns {import('express').RequestHandler} + * @returns {import('express').Application} */ module.exports = () => { debug('BackendApp setup start'); diff --git a/ghost/core/core/server/web/parent/frontend.js b/ghost/core/core/server/web/parent/frontend.js index 4b0a8fc991..69d27c7372 100644 --- a/ghost/core/core/server/web/parent/frontend.js +++ b/ghost/core/core/server/web/parent/frontend.js @@ -5,7 +5,7 @@ const shared = require('../shared'); /** * * @param {import('../../../frontend/services/routing/RouterManager').RouterConfig} routerConfig - * @returns {import('express').RequestHandler} + * @returns {import('express').Application} */ module.exports = (routerConfig) => { debug('FrontendApp setup start', routerConfig); diff --git a/ghost/core/core/server/web/parent/middleware/emit-events.js b/ghost/core/core/server/web/parent/middleware/emit-events.js index 318bd32612..5d58d3b386 100644 --- a/ghost/core/core/server/web/parent/middleware/emit-events.js +++ b/ghost/core/core/server/web/parent/middleware/emit-events.js @@ -3,6 +3,11 @@ const INVALIDATE_ALL = '/*'; // Emit the site.changed event, a special model event used for webhooks const events = require('../../../lib/common/events'); +/** + * @param {import('express').Request} req + * @param {import('express').Response} res + * @param {import('express').NextFunction} next + */ module.exports = function emitEvents(req, res, next) { res.on('finish', function triggerEvents() { if (res.get('X-Cache-Invalidate') === INVALIDATE_ALL) { diff --git a/ghost/core/core/server/web/parent/middleware/ghost-locals.js b/ghost/core/core/server/web/parent/middleware/ghost-locals.js index 213abedba7..146a6d20fa 100644 --- a/ghost/core/core/server/web/parent/middleware/ghost-locals.js +++ b/ghost/core/core/server/web/parent/middleware/ghost-locals.js @@ -1,7 +1,12 @@ const ghostVersion = require('@tryghost/version'); -// ### GhostLocals Middleware -// Expose the standard locals that every request will need to have available +/** + * Expose the standard locals that every request will need to have available + * + * @param {import('express').Request} req + * @param {import('express').Response} res + * @param {import('express').NextFunction} next + */ module.exports = function ghostLocals(req, res, next) { // Make sure we have a locals value. res.locals = res.locals || {}; diff --git a/ghost/core/core/server/web/parent/middleware/log-request.js b/ghost/core/core/server/web/parent/middleware/log-request.js index 121b63d385..bc1391eaf6 100644 --- a/ghost/core/core/server/web/parent/middleware/log-request.js +++ b/ghost/core/core/server/web/parent/middleware/log-request.js @@ -2,6 +2,10 @@ const logging = require('@tryghost/logging'); /** * @TODO: move this middleware to Framework monorepo? + * + * @param {import('express').Request} req + * @param {import('express').Response} res + * @param {import('express').NextFunction} next */ module.exports = function logRequest(req, res, next) { const startTime = Date.now(); diff --git a/ghost/core/core/server/web/parent/middleware/queue-request.js b/ghost/core/core/server/web/parent/middleware/queue-request.js index c1cd4a5fe0..debdf8fb2e 100644 --- a/ghost/core/core/server/web/parent/middleware/queue-request.js +++ b/ghost/core/core/server/web/parent/middleware/queue-request.js @@ -44,6 +44,11 @@ module.exports = function queueRequest( debug(`Request completed: ${job.data.req.path}`); }); + /** + * @param {import('express').Request} req + * @param {import('express').Response} res + * @param {import('express').NextFunction} next + */ return function queueRequestMw(req, res, next) { req.queueDepth = queue.queue.getLength(); diff --git a/ghost/core/core/server/web/parent/middleware/request-id.js b/ghost/core/core/server/web/parent/middleware/request-id.js index 14ea5cf123..1e537cb191 100644 --- a/ghost/core/core/server/web/parent/middleware/request-id.js +++ b/ghost/core/core/server/web/parent/middleware/request-id.js @@ -2,6 +2,10 @@ const uuid = require('uuid'); /** * @TODO: move this middleware to Framework monorepo? + * + * @param {import('express').Request} req + * @param {import('express').Response} res + * @param {import('express').NextFunction} next */ module.exports = function requestIdMw(req, res, next) { const requestId = req.get('X-Request-ID') || uuid.v4(); diff --git a/ghost/core/core/server/web/webmentions/routes.js b/ghost/core/core/server/web/webmentions/routes.js index f4bdf0723f..d41978461f 100644 --- a/ghost/core/core/server/web/webmentions/routes.js +++ b/ghost/core/core/server/web/webmentions/routes.js @@ -5,6 +5,9 @@ const shared = require('../shared'); const bodyParser = require('body-parser'); +/** + * @returns {import('express').Router} + */ module.exports = function apiRoutes() { const router = express.Router('webmentions'); diff --git a/ghost/core/core/shared/express.js b/ghost/core/core/shared/express.js index bf207f7b46..338babcac3 100644 --- a/ghost/core/core/shared/express.js +++ b/ghost/core/core/shared/express.js @@ -5,6 +5,11 @@ const sentry = require('./sentry'); const lazyLoad = createLazyRouter(); +/** + * + * @param {String} name + * @returns {import('express').Application} + */ module.exports = (name) => { debug('new app start', name); const app = express();