PadMessageHandler: Replace clientReady hook with new userJoin hook

CHANGELOG.md

@@ -31,6 +31,8 @@
       different. See
       [citizenos/ep_image_upload#49](https://github.com/citizenos/ep_image_upload/pull/49)
       for an example fix.
+  * The `clientReady` server-side hook is deprecated; use the new `userJoin`
+    hook instead.
 
 ### Notable enhancements
 
@@ -38,6 +40,7 @@
 * For plugin authors:
   * `clientVars` was added to the context for the `postAceInit` client-side
     hook. Plugins should use this instead of the `clientVars` global variable.
+  * New `userJoin` server-side hook.
 
 # 1.8.14
 

doc/api/hooks_server-side.md

@@ -807,6 +807,30 @@ Example:
 exports.exportEtherpadAdditionalContent = () => ['comments'];
 ```
 
+## `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:
+
+```javascript
+exports.userJoin = async (hookName, {authorId, displayName, padId}) => {
+  console.log(`${authorId} (${displayName}) joined pad ${padId});
+};
+```
+
 ## `userLeave`
 
 Called from: `src/node/handler/PadMessageHandler.js`
@@ -838,20 +862,3 @@ exports.userLeave = async (hookName, {author, padId}) => {
   console.log(`${author} left pad ${padId}`);
 };
 ```
-
-## `clientReady`
-
-Called from: `src/node/handler/PadMessageHandler.js`
-
-Called when a `CLIENT_READY` message is received, which is the first message a
-newly connected client sends.
-
-The context is the raw message received from the user.
-
-Example:
-
-```javascript
-exports.clientReady = async (hookName, {padId}) => {
-  console.log(`Client has joined pad ${padId});
-};
-```

src/node/handler/PadMessageHandler.js

@@ -43,6 +43,8 @@ const webaccess = require('../hooks/express/webaccess');
 let rateLimiter;
 let socketio = null;
 
+hooks.deprecationNotices.clientReady = 'use the userJoin hook instead';
+
 exports.socketio = () => {
   // The rate limiter is created in this hook so that restarting the server resets the limiter. The
   // settings.commitRateLimiting object is passed directly to the rate limiter so that the limits
@@ -812,7 +814,7 @@ const handleClientReady = async (socket, message) => {
   sessionInfo.readonly =
       padIds.readonly || !webaccess.userCanModify(sessionInfo.auth.padID, socket.client.request);
 
-  await hooks.aCallAll('clientReady', message);
+  await hooks.aCallAll('clientReady', message); // Deprecated due to awkward context.
 
   // get all authordata of this new user
   assert(sessionInfo.author);
@@ -1088,6 +1090,15 @@ const handleClientReady = async (socket, message) => {
 
     socket.json.send(msg);
   }));
+
+  await hooks.aCallAll('userJoin', {
+    authorId: sessionInfo.author,
+    displayName: authorName,
+    padId: sessionInfo.padId,
+    readOnly: sessionInfo.readonly,
+    readOnlyPadId: sessionInfo.readOnlyPadId,
+    socket,
+  });
 };
 
 /**