diff --git a/CHANGELOG.md b/CHANGELOG.md index 488d0e947..39ff70f3c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,7 @@ #### For plugin authors +* New `expressPreSession` server-side hook. * New APIs for processing attributes: `ep_etherpad-lite/static/js/attributes` (low-level API) and `ep_etherpad-lite/static/js/AttributeMap` (high-level API). diff --git a/doc/api/hooks_server-side.md b/doc/api/hooks_server-side.md index ddae10d14..47477216c 100644 --- a/doc/api/hooks_server-side.md +++ b/doc/api/hooks_server-side.md @@ -58,6 +58,35 @@ Run during startup after the named plugin is initialized. Context properties: None +## `expressPreSession` + +Called from: `src/node/hooks/express.js` + +Called during server startup just before the +[`express-session`](https://www.npmjs.com/package/express-session) middleware is +added to the Express Application object. Use this hook to add route handlers or +middleware that executes before `express-session` state is created and +authentication is performed. This is useful for creating public endpoints that +don't spam the database with new `express-session` records or trigger +authentication. + +**WARNING:** All handlers registered during this hook run before the built-in +authentication checks, so any handled endpoints will be public unless the +handler itself authenticates the user. + +Context properties: + +* `app`: The Express [Application](https://expressjs.com/en/4x/api.html#app) + object. + +Example: + +```javascript +exports.expressPreSession = async (hookName, {app}) => { + app.get('/hello-world', (req, res) => res.send('hello world')); +}; +``` + ## `expressConfigure` Called from: `src/node/hooks/express.js` diff --git a/src/node/hooks/express.js b/src/node/hooks/express.js index 1e2fc4481..2441b827e 100644 --- a/src/node/hooks/express.js +++ b/src/node/hooks/express.js @@ -204,6 +204,10 @@ exports.restartServer = async () => { // If webaccess.preAuthorize explicitly grants access, webaccess.checkAccess will skip all checks. app.use(webaccess.preAuthorize); + // Give plugins an opportunity to install handlers/middleware after the preAuthorize middleware + // but before the express-session middleware. This allows plugins to avoid creating an + // express-session record in the database when it is not needed (e.g., public static content). + await hooks.aCallAll('expressPreSession', {app}); app.use(exports.sessionMiddleware); app.use(cookieParser(settings.sessionKey, {})); app.use(webaccess.checkAccess);