ImportHandler: Pass `ImportError` to `import` hook

CHANGELOG.md

@@ -19,6 +19,7 @@
 * New APIs for processing attributes: `ep_etherpad-lite/static/js/attributes`
   (low-level API) and `ep_etherpad-lite/static/js/AttributeMap` (high-level
   API).
+* The `import` server-side hook has a new `ImportError` context property.
 
 ### Compatibility changes
 

doc/api/hooks_server-side.md

@@ -821,6 +821,19 @@ Context properties:
   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](https://github.com/ether/etherpad-lite/blob/1.8.16/src/static/js/pad_impexp.js#L80-L86).
+
+Example:
+
+```javascript
+exports.import = async (hookName, {fileEnding, ImportError}) => {
+  // Reject all *.etherpad imports with a permission denied message.
+  if (fileEnding === '.etherpad') throw new ImportError('permission');
+};
+```
 
 ## `userJoin`
 

src/node/handler/ImportHandler.js

@@ -142,8 +142,8 @@ const doImport = async (req, res, padId) => {
   }
 
   const destFile = path.join(tmpDirectory, `etherpad_import_${randNum}.${exportExtension}`);
-  const importHandledByPlugin =
-      (await hooks.aCallAll('import', {srcFile, destFile, fileEnding, padId})).some((x) => x);
+  const context = {srcFile, destFile, fileEnding, padId, ImportError};
+  const importHandledByPlugin = (await hooks.aCallAll('import', context)).some((x) => x);
   const fileIsEtherpad = (fileEnding === '.etherpad');
   const fileIsHTML = (fileEnding === '.html' || fileEnding === '.htm');
   const fileIsTXT = (fileEnding === '.txt');