31 KiB
Server-side hooks
These hooks are called on server-side.
loadSettings
Called from: src/node/server.js
Things in context:
- settings - the settings object
Use this hook to receive the global settings in your plugin.
shutdown
Called from: src/node/server.js
Things in context: None
This hook runs before shutdown. Use it to stop timers, close sockets and files, flush buffers, etc. The database is not available while this hook is running. The shutdown function must not block for long because there is a short timeout before the process is forcibly terminated.
The shutdown function must return a Promise, which must resolve to undefined
.
Returning callback(value)
will return a Promise that is resolved to value
.
Example:
// using an async function
exports.shutdown = async (hookName, context) => {
await flushBuffers();
};
pluginUninstall
Called from: src/static/js/pluginfw/installer.js
Things in context:
- plugin_name - self-explanatory
If this hook returns an error, the callback to the uninstall function gets an error as well. This mostly seems useful for handling additional features added in based on the installation of other plugins, which is pretty cool!
pluginInstall
Called from: src/static/js/pluginfw/installer.js
Things in context:
- plugin_name - self-explanatory
If this hook returns an error, the callback to the install function gets an error, too. This seems useful for adding in features when a particular plugin is installed.
init_<plugin name>
Called from: src/static/js/pluginfw/plugins.js
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
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 object.
Example:
exports.expressPreSession = async (hookName, {app}) => {
app.get('/hello-world', (req, res) => res.send('hello world'));
};
expressConfigure
Called from: src/node/hooks/express.js
Called during server startup just after the
express-session
middleware is
added to the Express Application object. Use this hook to add route handlers or
middleware that executes after express-session
state is created and
authentication is performed.
Context properties:
app
: The Express Application object.
expressCreateServer
Called from: src/node/hooks/express.js
Identical to the expressConfigure
hook (the two run in parallel with each
other) except this hook's context includes the HTTP Server object.
Context properties:
app
: The Express Application object.server
: The http.Server or https.Server object.
expressCloseServer
Called from: src/node/hooks/express.js
Things in context: Nothing
This hook is called when the HTTP server is closing, which happens during
shutdown (see the shutdown hook) and when the server restarts (e.g., when a
plugin is installed via the /admin/plugins
page). The HTTP server may or may
not already be closed when this hook executes.
Example:
exports.expressCloseServer = async () => {
await doSomeCleanup();
};
eejsBlock_<name>
Called from: src/node/eejs/index.js
Things in context:
- content - the content of the block
This hook gets called upon the rendering of an ejs template block. For any specific kind of block, you can change how that block gets rendered by modifying the content object passed in.
Available blocks in pad.html
are:
htmlHead
- after<html>
and immediately before the title tagstyles
- the style<link>
sbody
- the contents of the body tageditbarMenuLeft
- the left tool bar (consider using the toolbar controller instead of manually adding html here)editbarMenuRight
- right tool barafterEditbar
- allows you to add stuff immediately after the toolbaruserlist
- the contents of the userlist dropdownloading
- the initial loading messagemySettings
- the left column of the settings dropdown ("My view"); intended for adding checkboxes onlymySettings.dropdowns
- add your dropdown settings hereglobalSettings
- the right column of the settings dropdown ("Global view")importColumn
- import formexportColumn
- export formmodals
- Contains all connectivity messagesembedPopup
- the embed dropdownscripts
- Add your script tags here, if you really have to (consider use client-side hooks instead)
timeslider.html
blocks:
timesliderStyles
timesliderScripts
timesliderBody
timesliderTop
timesliderEditbarRight
modals
index.html
blocks:
indexCustomStyles
- contains theindex.css
<link>
tag, allows you to add your own or to customize the one provided by the active skinindexWrapper
- contains the form for creating new padsindexCustomScripts
- contains theindex.js
<script>
tag, allows you to add your own or to customize the one provided by the active skin
padInitToolbar
Called from: src/node/hooks/express/specialpages.js
Things in context:
- toolbar - the toolbar controller that will render the toolbar eventually
Here you can add custom toolbar items that will be available in the toolbar config in settings.json
. For more about the toolbar controller see the API section.
Usage examples:
onAccessCheck
Called from: src/node/db/SecurityManager.js
Things in context:
- padID - the real ID (never the read-only ID) of the pad the user wants to access
- token - the token of the author
- sessionCookie - the session the use has
This hook gets called when the access to the concrete pad is being checked.
Return false
to deny access.
padCreate
Called from: src/node/db/Pad.js
Called when a new pad is created.
Context properties:
pad
: The Pad object.authorId
: The ID of the author who created the pad.author
(deprecated): Synonym ofauthorId
.
padLoad
Called from: src/node/db/PadManager.js
Called when a pad is loaded, including after new pad creation.
Context properties:
pad
: The Pad object.
padUpdate
Called from: src/node/db/Pad.js
Called when an existing pad is updated.
Context properties:
pad
: The Pad object.authorId
: The ID of the author who updated the pad.author
(deprecated): Synonym ofauthorId
.revs
: The index of the new revision.changeset
: The changeset of this revision (see Changeset Library).
padCopy
Called from: src/node/db/Pad.js
Things in context:
- originalPad - the source pad instance
- destinationID - the id of the pad copied from originalPad
This hook gets called when an existing pad was copied.
Usage examples:
padRemove
Called from: src/node/db/Pad.js
Things in context:
- padID
This hook gets called when an existing pad was removed/deleted.
Usage examples:
socketio
Called from: src/node/hooks/express/socketio.js
Things in context:
- app - the application object
- io - the socketio object
- server - the http server object
I have no idea what this is useful for, someone else will have to add this description.
preAuthorize
Called from: src/node/hooks/express/webaccess.js
Called for each HTTP request before any authentication checks are performed. The
registered preAuthorize
hook functions are called one at a time until one
explicitly grants or denies the request by returning true
or false
,
respectively. If none of the hook functions return anything, the access decision
is deferred to the normal authentication and authorization checks.
Example uses:
- Always grant access to static content.
- Process an OAuth callback.
- Drop requests from IP addresses that have failed N authentication checks within the past X minutes.
Return values:
undefined
(or[]
) defers the access decision to the next registeredpreAuthorize
hook function, or to the normal authentication and authorization checks if no morepreAuthorize
hook functions remain.true
(or[true]
) immediately grants access to the requested resource, unless the request is for an/admin
page in which case it is treated the same as returningundefined
. (This prevents buggy plugins from accidentally granting admin access to the general public.)false
(or[false]
) immediately denies the request. ThepreAuthnFailure
hook will be called to handle the failure.
Context properties:
req
: The Express Request object.res
: The Express Response object.next
: Callback to immediately hand off handling to the next Express middleware/handler, or to the next matching route if'route'
is passed as the first argument. Do not call this unless you understand the consequences.
Example:
exports.preAuthorize = async (hookName, {req}) => {
if (await ipAddressIsFirewalled(req)) return false;
if (requestIsForStaticContent(req)) return true;
if (requestIsForOAuthCallback(req)) return true;
// Defer the decision to the next step by returning undefined.
};
authorize
Called from: src/node/hooks/express/webaccess.js
Things in context:
- req - the request object
- res - the response object
- next - ?
- resource - the path being accessed
This hook is called to handle authorization. It is especially useful for controlling access to specific paths.
A plugin's authorize function is only called if all of the following are true:
- The request is not for static content or an API endpoint. (Requests for static content and API endpoints are always authorized, even if unauthenticated.)
- The
requireAuthentication
andrequireAuthorization
settings are both true. - The user has already successfully authenticated.
- The user is not an admin (admin users are always authorized).
- The path being accessed is not an
/admin
path (/admin
paths can only be accessed by admin users, and admin users are always authorized). - An authorize function from a different plugin has not already caused authorization to pass or fail.
Note that the authorize hook cannot grant access to /admin
pages. If admin
access is desired, the is_admin
user setting must be set to true. This can be
set in the settings file or by the authenticate hook.
You can pass the following values to the provided callback:
[true]
or['create']
will grant access to modify or create the pad if the request is for a pad, otherwise access is simply granted. Access to a pad will be downgraded to modify-only ifsettings.editOnly
is true or the user'scanCreate
setting is set tofalse
, and downgraded to read-only if the user'sreadOnly
setting istrue
.['modify']
will grant access to modify but not create the pad if the request is for a pad, otherwise access is simply granted. Access to a pad will be downgraded to read-only if the user'sreadOnly
setting istrue
.['readOnly']
will grant read-only access.[false]
will deny access.[]
orundefined
will defer the authorization decision to the next authorization plugin (if any, otherwise deny).
Example:
exports.authorize = (hookName, context, cb) => {
const user = context.req.session.user;
const path = context.req.path; // or context.resource
if (isExplicitlyProhibited(user, path)) return cb([false]);
if (isExplicitlyAllowed(user, path)) return cb([true]);
return cb([]); // Let the next authorization plugin decide
};
authenticate
Called from: src/node/hooks/express/webaccess.js
Things in context:
- req - the request object
- res - the response object
- users - the users object from settings.json (possibly modified by plugins)
- next - ?
- username - the username used (optional)
- password - the password used (optional)
This hook is called to handle authentication.
Plugins that supply an authenticate function should probably also supply an authnFailure function unless falling back to HTTP basic authentication is appropriate upon authentication failure.
This hook is only called if either the requireAuthentication
setting is true
or the request is for an /admin
page.
Calling the provided callback with [true]
or [false]
will cause
authentication to succeed or fail, respectively. Calling the callback with []
or undefined
will defer the authentication decision to the next authentication
plugin (if any, otherwise fall back to HTTP basic authentication).
If you wish to provide a mix of restricted and anonymous access (e.g., some pads are private, others are public), you can "authenticate" (as a guest account) users that have not yet logged in, and rely on other hooks (e.g., authorize, onAccessCheck, handleMessageSecurity) to authorize specific privileged actions.
If authentication is successful, the authenticate function MUST set
context.req.session.user
to the user's settings object. The username
property of this object should be set to the user's username. The settings
object should come from global settings (context.users[username]
).
Example:
exports.authenticate = (hook_name, context, cb) => {
if (notApplicableToThisPlugin(context)) {
return cb([]); // Let the next authentication plugin decide
}
const username = authenticate(context);
if (!username) {
console.warn(`ep_myplugin.authenticate: Failed authentication from IP ${context.req.ip}`);
return cb([false]);
}
console.info(`ep_myplugin.authenticate: Successful authentication from IP ${context.req.ip} for user ${username}`);
const users = context.users;
if (!(username in users)) users[username] = {};
users[username].username = username;
context.req.session.user = users[username];
return cb([true]);
};
authFailure
Called from: src/node/hooks/express/webaccess.js
Things in context:
- req - the request object
- res - the response object
- next - ?
DEPRECATED: Use authnFailure or authzFailure instead.
This hook is called to handle an authentication or authorization failure.
Plugins that supply an authenticate function should probably also supply an authnFailure function unless falling back to HTTP basic authentication is appropriate upon authentication failure.
A plugin's authFailure function is only called if all of the following are true:
- There was an authentication or authorization failure.
- The failure was not already handled by an authFailure function from another plugin.
- For authentication failures: The failure was not already handled by the authnFailure hook.
- For authorization failures: The failure was not already handled by the authzFailure hook.
Calling the provided callback with [true]
tells Etherpad that the failure was
handled and no further error handling is required. Calling the callback with
[]
or undefined
defers error handling to the next authFailure plugin (if
any, otherwise fall back to HTTP basic authentication for an authentication
failure or a generic 403 page for an authorization failure).
Example:
exports.authFailure = (hookName, context, cb) => {
if (notApplicableToThisPlugin(context)) {
return cb([]); // Let the next plugin handle the error
}
context.res.redirect(makeLoginURL(context.req));
return cb([true]);
};
preAuthzFailure
Called from: src/node/hooks/express/webaccess.js
Things in context:
- req - the request object
- res - the response object
This hook is called to handle a pre-authentication authorization failure.
A plugin's preAuthzFailure function is only called if the pre-authentication authorization failure was not already handled by a preAuthzFailure function from another plugin.
Calling the provided callback with [true]
tells Etherpad that the failure was
handled and no further error handling is required. Calling the callback with
[]
or undefined
defers error handling to a preAuthzFailure function from
another plugin (if any, otherwise fall back to a generic 403 error page).
Example:
exports.preAuthzFailure = (hookName, context, cb) => {
if (notApplicableToThisPlugin(context)) return cb([]);
context.res.status(403).send(renderFancy403Page(context.req));
return cb([true]);
};
authnFailure
Called from: src/node/hooks/express/webaccess.js
Things in context:
- req - the request object
- res - the response object
This hook is called to handle an authentication failure.
Plugins that supply an authenticate function should probably also supply an authnFailure function unless falling back to HTTP basic authentication is appropriate upon authentication failure.
A plugin's authnFailure function is only called if the authentication failure was not already handled by an authnFailure function from another plugin.
Calling the provided callback with [true]
tells Etherpad that the failure was
handled and no further error handling is required. Calling the callback with
[]
or undefined
defers error handling to an authnFailure function from
another plugin (if any, otherwise fall back to the deprecated authFailure hook).
Example:
exports.authnFailure = (hookName, context, cb) => {
if (notApplicableToThisPlugin(context)) return cb([]);
context.res.redirect(makeLoginURL(context.req));
return cb([true]);
};
authzFailure
Called from: src/node/hooks/express/webaccess.js
Things in context:
- req - the request object
- res - the response object
This hook is called to handle a post-authentication authorization failure.
A plugin's authzFailure function is only called if the authorization failure was not already handled by an authzFailure function from another plugin.
Calling the provided callback with [true]
tells Etherpad that the failure was
handled and no further error handling is required. Calling the callback with
[]
or undefined
defers error handling to an authzFailure function from
another plugin (if any, otherwise fall back to the deprecated authFailure hook).
Example:
exports.authzFailure = (hookName, context, cb) => {
if (notApplicableToThisPlugin(context)) return cb([]);
if (needsPremiumAccount(context.req) && !context.req.session.user.premium) {
context.res.status(200).send(makeUpgradeToPremiumAccountPage(context.req));
return cb([true]);
}
// Use the generic 403 forbidden response.
return cb([]);
};
handleMessage
Called from: src/node/handler/PadMessageHandler.js
This hook allows plugins to drop or modify incoming socket.io messages from
clients, before Etherpad processes them. If any hook function returns null
then the message will not be subject to further processing.
Context properties:
message
: The message being handled.sessionInfo
: Object describing the socket.io session with the following properties:authorId
: The user's author ID.padId
: The real (not read-only) ID of the pad.readOnly
: Whether the client has read-only access (true) or read/write access (false).
socket
: The socket.io Socket object.client
: (Deprecated; usesocket
instead.) Synonym ofsocket
.
Example:
exports.handleMessage = async (hookName, {message, socket}) => {
if (message.type === 'USERINFO_UPDATE') {
// Force the display name to the name associated with the account.
const user = socket.client.request.session.user || {};
if (user.name) message.data.userInfo.name = user.name;
}
};
handleMessageSecurity
Called from: src/node/handler/PadMessageHandler.js
Called for each incoming message from a client. Allows plugins to grant temporary write access to a pad.
Supported return values:
undefined
: No change in access status.'permitOnce'
: Override the user's read-only access for the currentCOLLABROOM
message only. Has no effect if the current message is not aCOLLABROOM
message, or if the user already has write access to the pad.true
: (Deprecated; return'permitOnce'
instead.) Override the user's read-only access for allCOLLABROOM
messages from the same socket.io connection (including the current message, if applicable) until the client's nextCLIENT_READY
message. Has no effect if the user already has write access to the pad. Read-only access is reset after eachCLIENT_READY
message, so returningtrue
has no effect forCLIENT_READY
messages.
Context properties:
message
: The message being handled.sessionInfo
: Object describing the socket.io connection with the following properties:authorId
: The user's author ID.padId
: The real (not read-only) ID of the pad.readOnly
: Whether the client has read-only access (true) or read/write access (false).
socket
: The socket.io Socket object.client
: (Deprecated; usesocket
instead.) Synonym ofsocket
.
Example:
exports.handleMessageSecurity = async (hookName, context) => {
const {message, sessionInfo: {readOnly}} = context;
if (!readOnly || message.type !== 'COLLABROOM') return;
if (await messageIsBenign(message)) return 'permitOnce';
};
clientVars
Called from: src/node/handler/PadMessageHandler.js
Things in context:
- clientVars - the basic
clientVars
built by the core - pad - the pad this session is about
- socket - the socket.io Socket object
This hook is called after a client connects but before the initial configuration is sent to the client. Plugins can use this hook to manipulate the configuration. (Example: Add a tracking ID for an external analytics tool that is used client-side.)
You can manipulate clientVars
in two different ways:
- Return an object. The object will be merged into
clientVars
viaObject.assign()
, so any keys that already exist inclientVars
will be overwritten by the values in the returned object. - Modify
context.clientVars
. Beware: Other plugins might also be reading or manipulating the samecontext.clientVars
object. To avoid race conditions, you are encouraged to return an object rather than modifycontext.clientVars
.
If needed, you can access the user's account information (if authenticated) via
context.socket.client.request.session.user
.
Examples:
// Using an async function
exports.clientVars = async (hookName, context) => {
const user = context.socket.client.request.session.user || {};
return {'accountUsername': user.username || '<unknown>'}
};
// Using a regular function
exports.clientVars = (hookName, context, callback) => {
const user = context.socket.client.request.session.user || {};
return callback({'accountUsername': user.username || '<unknown>'});
};
getLineHTMLForExport
Called from: src/node/utils/ExportHtml.js
This hook will allow a plug-in developer to re-write each line when exporting to HTML.
Context properties:
apool
: Pool object.attribLine
: Line attributes.line
:lineContent
:text
: Line text.padId
: Writable (not read-only) pad identifier.
Example:
const AttributeMap = require('ep_etherpad-lite/static/js/AttributeMap');
const Changeset = require('ep_etherpad-lite/static/js/Changeset');
exports.getLineHTMLForExport = async (hookName, context) => {
if (!context.attribLine) return;
const [op] = Changeset.deserializeOps(context.attribLine);
if (op == null) return;
const heading = AttributeMap.fromString(op.attribs, context.apool).get('heading');
if (!heading) return;
context.lineContent = `<${heading}>${context.lineContent}</${heading}>`;
};
exportHTMLAdditionalContent
Called from: src/node/utils/ExportHtml.js
Things in context:
- padId
This hook will allow a plug-in developer to include additional HTML content in the body of the exported HTML.
Example:
exports.exportHTMLAdditionalContent = async (hookName, {padId}) => {
return 'I am groot in ' + padId;
};
stylesForExport
Called from: src/node/utils/ExportHtml.js
Things in context:
- padId - The Pad Id
This hook will allow a plug-in developer to append Styles to the Exported HTML.
Example:
exports.stylesForExport = function(hook, padId, cb){
cb("body{font-size:13.37em !important}");
}
aceAttribClasses
Called from: src/static/js/linestylefilter.js
This hook is called when attributes are investigated on a line. It is useful if you want to add another attribute type or property type to a pad.
An attributes object is passed to the aceAttribClasses hook functions instead of the usual context object. A hook function can either modify this object directly or provide an object whose properties will be assigned to the attributes object.
Example:
exports.aceAttribClasses = (hookName, attrs, cb) => {
return cb([{
sub: 'tag:sub',
}]);
};
exportFileName
Called from src/node/handler/ExportHandler.js
Things in context:
- padId
This hook will allow a plug-in developer to modify the file name of an exported pad. This is useful if you want to export a pad under another name and/or hide the padId under export. Note that the doctype or file extension cannot be modified for security reasons.
Example:
exports.exportFileName = function(hook, padId, callback){
callback("newFileName"+padId);
}
exportHtmlAdditionalTags
Called from src/node/utils/ExportHtml.js
Things in context:
- Pad object
This hook will allow a plug-in developer to include more properties and attributes to support during HTML Export. If tags are stored as ['color', 'red']
on the attribute pool, use exportHtmlAdditionalTagsWithData
instead. An Array should be returned.
Example:
// Add the props to be supported in export
exports.exportHtmlAdditionalTags = function(hook, pad, cb){
var padId = pad.id;
cb(["massive","jugs"]);
};
exportHtmlAdditionalTagsWithData
Called from src/node/utils/ExportHtml.js
Things in context:
- Pad object
Identical to exportHtmlAdditionalTags
, but for tags that are stored with a specific value (not simply true
) on the attribute pool. For example ['color', 'red']
, instead of ['bold', true]
. This hook will allow a plug-in developer to include more properties and attributes to support during HTML Export. An Array of arrays should be returned. The exported HTML will contain tags like <span data-color="red">
for the content where attributes are ['color', 'red']
.
Example:
// Add the props to be supported in export
exports.exportHtmlAdditionalTagsWithData = function(hook, pad, cb){
var padId = pad.id;
cb([["color", "red"], ["color", "blue"]]);
};
exportEtherpadAdditionalContent
Called from src/node/utils/ExportEtherpad.js and src/node/utils/ImportEtherpad.js
Things in context: Nothing
Useful for exporting and importing pad metadata that is stored in the database
but not in the pad's content or attributes. For example, in ep_comments_page the
comments are stored as comments:padId:uniqueIdOfComment
so a complete export
of all pad data to an .etherpad
file must include the comments:padId:*
records.
Example:
// Add support for exporting comments metadata
exports.exportEtherpadAdditionalContent = () => ['comments'];
import
Called from: src/node/handler/ImportHandler.js
Called when a user submits a document for import, before the document is converted to HTML. The hook function should return a truthy value if the hook function elected to convert the document to HTML.
Context properties:
destFile
: The destination HTML filename.fileEnding
: The lower-cased filename extension fromsrcFile
with leading period (examples:'.docx'
,'.html'
,'.etherpad'
).padId
: The identifier of the destination pad.srcFile
: The document to convert.ImportError
: Subclass of Error that can be thrown to provide a specific error message to the user. The constructor's first argument must be a string matching one of the known error identifiers.
Example:
exports.import = async (hookName, {fileEnding, ImportError}) => {
// Reject all *.etherpad imports with a permission denied message.
if (fileEnding === '.etherpad') throw new ImportError('permission');
};
userJoin
Called from: src/node/handler/PadMessageHandler.js
Called after users have been notified that a new user has joined the pad.
Context properties:
authorId
: The user's author identifier.displayName
: The user's display name.padId
: The real (not read-only) identifier of the pad the user joined. This MUST NOT be shared with any users that are connected with read-only access.readOnly
: Whether the user only has read-only access.readOnlyPadId
: The read-only identifier of the pad the user joined.socket
: The socket.io Socket object.
Example:
exports.userJoin = async (hookName, {authorId, displayName, padId}) => {
console.log(`${authorId} (${displayName}) joined pad ${padId});
};
userLeave
Called from: src/node/handler/PadMessageHandler.js
Called when a user disconnects from a pad. This is useful if you want to perform certain actions after a pad has been edited.
Context properties:
authorId
: The user's author ID.padId
: The pad's real (not read-only) identifier.readOnly
: If truthy, the user only has read-only access.readOnlyPadId
: The pad's read-only identifier.socket
: The socket.io Socket object.
Example:
exports.userLeave = async (hookName, {author, padId}) => {
console.log(`${author} left pad ${padId}`);
};
chatNewMessage
Called from: src/node/handler/PadMessageHandler.js
Called when a user (or plugin) generates a new chat message, just before it is saved to the pad and relayed to all connected users.
Context properties:
message
: The chat message object. Plugins can mutate this object to change the message text or add custom metadata to control how the message will be rendered by thechatNewMessage
client-side hook. The message'sauthorId
property can be trusted (the server overwrites any client-provided author ID value with the user's actual author ID before this hook runs).padId
: The pad's real (not read-only) identifier.pad
: The pad's Pad object.