Merge pull request #4287 from esl/unify-hook-names

Unify hook names, removing the (seldom used) '_hook' suffix

doc/developers-guide/Hooks-and-handlers.md

@@ -26,7 +26,7 @@ I.e. if `mod_offline` was not available, the code would simply crash; if it was
 To avoid that coupling and also to enable other ([possibly yet to be written](#sidenote-code-yet-to-be-written)) code to carry out some action at this particular moment, `ejabberd_sm` calls instead:
 
 ```erlang
-mongoose_hooks:offline_message_hook(Acc, From, To, Packet);
+mongoose_hooks:offline_message(Acc, From, To, Packet);
 ```
 
 `mongoose_hooks` is a module which serves as an API for calling hooks in the server. All such modules are placed in `src/hooks`.
@@ -37,7 +37,7 @@ This means that there is some degree of coupling still - but this time between t
 The extra level of indirection introduced by this call gives the flexibility to determine at runtime what code actually gets run at this point.
 This depends on which handlers are registered to process the event.
 
-`offline_message_hook` is the name of the hook (in other words of the event that is being signalled);
+`offline_message` is the name of the hook (in other words of the event that is being signalled);
 `Acc` is the [Accumulator, described later](#using-accumulators);
 `From`, `To` and `Packet` are the arguments passed to the handler, just as they would in case of the function being called directly.
 
@@ -86,10 +86,10 @@ If a Mongoose accumulator is passed to a hook, handlers should store their retur
 * If the value is to be passed on to be reused within the current processing context, use `mongoose_acc:set(Namespace, Key, Value, Acc)`.
 * If the value should be passed on to the recipient's session, pubsub node etc. use `mongoose_acc:set_permanent(Namespace, Key, Value, Acc)`.
 
-A real life example, then, with regard to `mod_offline` is the `resend_offline_messages_hook` run in `mod_presence`:
+A real life example, then, with regard to `mod_offline` is the `resend_offline_messages` hook run in `mod_presence`:
 
 ```erlang
-Acc1 = mongoose_hooks:resend_offline_messages_hook(Acc, Jid),
+Acc1 = mongoose_hooks:resend_offline_messages(Acc, Jid),
 Rs = mongoose_acc:get(offline, messages, [], Acc1),
 ```
 
@@ -122,7 +122,7 @@ It is decided when creating a hook and can be checked in the `mongoose_hooks` mo
 
 ## Registering hook handlers
 
-In order to store a packet when `ejabberd_sm` runs `offline_message_hook`, the relevant module must register a handler for this hook.
+In order to store a packet when `ejabberd_sm` runs `offline_message`, the relevant module must register a handler for this hook.
 To attain the runtime configurability the module should register the handlers when it's loaded and unregister them when
 it's unloaded.
 That's usually done in, respectively, `start/2` and `stop/1` functions.
@@ -133,10 +133,10 @@ gen_hook:add_handlers(hooks(HostType)),
 ```
 and the `hooks/1` function returns a list of tuples describing hook handlers, like:
 ```erlang
-{offline_message_hook, HostType, fun ?MODULE:inspect_packet/3, #{}, 50}
+{offline_message, HostType, fun ?MODULE:inspect_packet/3, #{}, 50}
 ```
 
-It is clearly visible that the handler `inspect_packet` is added to the `offline_message_hook`.
+It is clearly visible that the handler `inspect_packet` is added to the `offline_message` hook.
 
 `HostType` is the one for which the handler will be executed.
 In the case of statically defined domains, it is the same as the host, as configured in the [`general.hosts` section](../configuration/general.md#generalhosts).

doc/developers-guide/Stanza-routing.md

@@ -57,7 +57,7 @@ If the check passes, the next step is to call the handler associated with the co
 
 `ejabberd_sm` determines the available resources of the recipient, takes into account their priorities and whether the message is addressed to a particular resource or a bare JID.
 It appropriately replicates (or not) the message and sends it to the recipient's C2S process(es) by calling `mongoose_c2s:route/2`.
-In case no resources are available for delivery (hence no C2S processes to pass the message to), `offline_message_hook` is run.
+In case no resources are available for delivery (hence no C2S processes to pass the message to), the `offline_message` hook is run.
 
 As Bob has one online session, the message is sent to the C2S process associated with that session.
 

doc/developers-guide/hooks_description.md

@@ -127,10 +127,10 @@ These hooks are handled by the following modules:
 * [`mod_privacy`](../modules/mod_privacy.md) - filters received stanzas according to privacy lists.
 * [`mod_stream_management`](../modules/mod_stream_management.md) - filters out stanzas with conflicting session ID's.
 
-## `offline_message_hook`
+## `offline_message`
 
 ```erlang
-mongoose_hooks:offline_message_hook(Acc, From, To, Packet)
+mongoose_hooks:offline_message(Acc, From, To, Packet)
 ```
 
 `ejabberd_sm` runs this hook for each message which cannot be delivered, because no resource (i.e. device or desktop client application) of its recipient is available online for delivery.
@@ -212,7 +212,7 @@ This is the perfect place to plug in custom security control.
 * amp_check_condition
 * amp_determine_strategy
 * amp_verify_support
-* anonymous_purge_hook
+* anonymous_purge
 * auth_failed
 * c2s_stream_features
 * can_access_identity
@@ -235,7 +235,7 @@ This is the perfect place to plug in custom security control.
 * filter_pep_recipient
 * filter_room_packet
 * filter_unacknowledged_messages
-* forbidden_session_hook
+* forbidden_session
 * foreign_event
 * forget_room
 * get_key
@@ -273,10 +273,10 @@ This is the perfect place to plug in custom security control.
 * mod_global_distrib_known_recipient
 * mod_global_distrib_unknown_recipient
 * node_cleanup
-* offline_groupchat_message_hook
-* offline_message_hook
+* offline_groupchat_message
+* offline_message
 * packet_to_component
-* presence_probe_hook
+* presence_probe
 * privacy_check_packet
 * privacy_get_user_list
 * privacy_iq_get
@@ -289,7 +289,7 @@ This is the perfect place to plug in custom security control.
 * remove_domain
 * remove_user
 * reroute_unacked_messages
-* resend_offline_messages_hook
+* resend_offline_messages
 * room_exists
 * room_new_affiliations
 * room_packet
@@ -309,16 +309,16 @@ This is the perfect place to plug in custom security control.
 * s2s_stream_features
 * session_cleanup
 * session_opening_allowed_for_user
-* set_presence_hook
+* set_presence
 * set_vcard
 * sm_filter_offline_message
-* sm_register_connection_hook
-* sm_remove_connection_hook
+* sm_register_connection
+* sm_remove_connection
 * unacknowledged_message
 * unregister_subhost
-* unset_presence_hook
+* unset_presence
 * update_inbox_for_muc
-* user_available_hook
+* user_available
 * user_open_session
 * user_ping_response
 * user_receive_iq

doc/developers-guide/mod_muc_light_developers_guide.md

@@ -84,7 +84,7 @@ There are 2 test suites and one helper module in `big_tests/tests`.
 
 ## Hooks handled by this extension
 
-* `offline_groupchat_message_hook` handled by `mod_muc_light:prevent_service_unavailable/3`
+* `offline_groupchat_message` handled by `mod_muc_light:prevent_service_unavailable/3`
 
 Prevents the default behaviour of sending `service-unavailable` error to the room when a groupchat message is sent to an offline occupant.
 

doc/migrations/6.2.1_x.x.x.md

@@ -0,0 +1,4 @@
+## Hooks
+
+Hook names have been unified by removing the `_hook` prefix from the few hooks which used it,
+e.g. `offline_message_hook` is now called `offline_message`. This change affects the hook metric names as well.

doc/operation-and-maintenance/MongooseIM-metrics.md

@@ -73,7 +73,7 @@ As a result it makes more sense to maintain a list of the most relevant or usefu
 
 | Name | Type | Description (when it gets incremented) |
 | ---- | ---- | -------------------------------------- |
-| `[HostType, anonymous_purge_hook]` | spiral | An anonymous user disconnects. |
+| `[HostType, anonymous_purge]` | spiral | An anonymous user disconnects. |
 | `[HostType, disco_info]` | spiral | An information about the server has been requested via Disco protocol. |
 | `[HostType, disco_local_features]` | spiral | A list of server features is gathered. |
 | `[HostType, disco_local_identity]` | spiral | A list of server identities is gathered. |
@@ -82,15 +82,15 @@ As a result it makes more sense to maintain a list of the most relevant or usefu
 | `[HostType, disco_sm_identity]` | spiral | A list of user's identities is gathered. |
 | `[HostType, disco_sm_items]` | spiral | A list of user's items is gathered. |
 | `[HostType, mam_lookup_messages]` | spiral | An archive lookup is performed. |
-| `[HostType, offline_message_hook]` | spiral | A message was sent to an offline user. (Except for "error", "headline" and "groupchat" message types.) |
-| `[HostType, offline_groupchat_message_hook]` | spiral | A groupchat message was sent to an offline user. |
+| `[HostType, offline_message]` | spiral | A message was sent to an offline user. (Except for "error", "headline" and "groupchat" message types.) |
+| `[HostType, offline_groupchat_message]` | spiral | A groupchat message was sent to an offline user. |
 | `[HostType, privacy_updated_list]` | spiral | User's privacy list is updated. |
-| `[HostType, resend_offline_messages_hook]` | spiral | A list of offline messages is gathered for delivery to a user's new connection. |
+| `[HostType, resend_offline_messages]` | spiral | A list of offline messages is gathered for delivery to a user's new connection. |
 | `[HostType, roster_get_subscription_lists]` |  spiral | Presence subscription lists (based on which presence updates are broadcasted) are gathered. |
 | `[HostType, roster_in_subscription]` | spiral | A presence with subscription update is processed. |
 | `[HostType, roster_out_subscription]` | spiral | A presence with subscription update is received from a client. |
 | `[HostType, sm_broadcast]` | spiral | A stanza is broadcasted to all of user's resources. |
-| `[HostType, unset_presence_hook]` | spiral | A user disconnects or sends an `unavailable` presence. |
+| `[HostType, unset_presence]` | spiral | A user disconnects or sends an `unavailable` presence. |
 
 ### Presences & rosters
 

mkdocs.yml

@@ -194,6 +194,7 @@ nav:
       - '6.0.0 to 6.1.0': 'migrations/6.0.0_6.1.0.md'
       - '6.1.0 to 6.2.0': 'migrations/6.1.0_6.2.0.md'
       - '6.2.0 to 6.2.1': 'migrations/6.2.0_6.2.1.md'
+      - '6.2.1 to x.x.x': 'migrations/6.2.1_x.x.x.md'
       - 'MAM MUC migration helper': 'migrations/jid-from-mam-muc-script.md'
   - 'Contributions to the Ecosystem': 'Contributions.md'
   - 'MongooseIM History': 'History.md'

src/auth/ejabberd_auth_anonymous.erl

@@ -77,8 +77,8 @@ stop(HostType) ->
 -spec hooks(mongooseim:host_type()) -> gen_hook:hook_list().
 hooks(HostType) ->
     [
-        {sm_register_connection_hook, HostType, fun ?MODULE:register_connection/3, #{}, 100},
-        {sm_remove_connection_hook, HostType, fun ?MODULE:unregister_connection/3, #{}, 100},
+        {sm_register_connection, HostType, fun ?MODULE:register_connection/3, #{}, 100},
+        {sm_remove_connection, HostType, fun ?MODULE:unregister_connection/3, #{}, 100},
         {session_cleanup, HostType, fun ?MODULE:session_cleanup/3, #{}, 50}
     ].
 
@@ -155,7 +155,7 @@ purge_hook(true, HostType, LUser, LServer) ->
                               host_type => HostType,
                               lserver => LServer,
                               element => undefined }),
-    mongoose_hooks:anonymous_purge_hook(LServer, Acc, LUser).
+    mongoose_hooks:anonymous_purge(LServer, Acc, LUser).
 
 -spec session_cleanup(Acc, Params, Extra) -> {ok, Acc} when
     Acc :: mongoose_acc:t(),

src/c2s/mongoose_c2s.erl

@@ -545,7 +545,7 @@ verify_user(session_established, HostType, #{c2s_data := StateData} = HookParams
             {ok, Acc1};
         {stop, Acc1} ->
             Jid = StateData#c2s_data.jid,
-            Acc2 = mongoose_hooks:forbidden_session_hook(HostType, Acc1, Jid),
+            Acc2 = mongoose_hooks:forbidden_session(HostType, Acc1, Jid),
             ?LOG_INFO(#{what => forbidden_session, text => <<"User not allowed to open session">>,
                         acc => Acc2, c2s_state => StateData}),
             {stop, Acc2}

src/ejabberd_sm.erl

@@ -190,7 +190,7 @@ make_new_sid() ->
 open_session(HostType, SID, JID, Priority, Info) ->
     set_session(SID, JID, Priority, Info),
     ReplacedPIDs = check_for_sessions_to_replace(HostType, JID),
-    mongoose_hooks:sm_register_connection_hook(HostType, SID, JID, Info),
+    mongoose_hooks:sm_register_connection(HostType, SID, JID, Info),
     ReplacedPIDs.
 
 -spec close_session(Acc, SID, JID, Reason, Info) -> Acc1 when
@@ -203,7 +203,7 @@ open_session(HostType, SID, JID, Priority, Info) ->
 close_session(Acc, SID, JID, Reason, Info) ->
     #jid{luser = LUser, lserver = LServer, lresource = LResource} = JID,
     ejabberd_sm_backend:delete_session(SID, LUser, LServer, LResource),
-    mongoose_hooks:sm_remove_connection_hook(Acc, SID, JID, Info, Reason).
+    mongoose_hooks:sm_remove_connection(Acc, SID, JID, Info, Reason).
 
 -spec store_info(jid:jid(), sid(), info_key(), any()) -> ok.
 store_info(JID, SID, Key, Value) ->
@@ -282,7 +282,7 @@ get_raw_sessions(#jid{luser = LUser, lserver = LServer}) ->
       Info :: info().
 set_presence(Acc, SID, JID, Priority, Presence, Info) ->
     set_session(SID, JID, Priority, Info),
-    mongoose_hooks:set_presence_hook(Acc, JID, Presence).
+    mongoose_hooks:set_presence(Acc, JID, Presence).
 
 
 -spec unset_presence(Acc, SID, JID, Status, Info) -> Acc1 when
@@ -294,7 +294,7 @@ set_presence(Acc, SID, JID, Priority, Presence, Info) ->
       Info :: info().
 unset_presence(Acc, SID, JID, Status, Info) ->
     set_session(SID, JID, undefined, Info),
-    mongoose_hooks:unset_presence_hook(Acc, JID, Status).
+    mongoose_hooks:unset_presence(Acc, JID, Status).
 
 
 -spec get_session_pid(JID) -> none | pid() when
@@ -487,8 +487,8 @@ create_metrics() ->
 hooks(HostType) ->
     [
      {roster_in_subscription, HostType, fun ?MODULE:check_in_subscription/3, #{}, 20},
-     {offline_message_hook, HostType, fun ?MODULE:bounce_offline_message/3, #{}, 100},
-     {offline_groupchat_message_hook, HostType, fun ?MODULE:bounce_offline_message/3, #{}, 100},
+     {offline_message, HostType, fun ?MODULE:bounce_offline_message/3, #{}, 100},
+     {offline_groupchat_message, HostType, fun ?MODULE:bounce_offline_message/3, #{}, 100},
      {remove_user, HostType, fun ?MODULE:disconnect_removed_user/3, #{}, 100}
     ].
 
@@ -772,7 +772,7 @@ route_message(From, To, Acc, Packet) ->
 route_message_by_type(<<"error">>, _From, _To, Acc, _Packet) ->
     Acc;
 route_message_by_type(<<"groupchat">>, From, To, Acc, Packet) ->
-    mongoose_hooks:offline_groupchat_message_hook(Acc, From, To, Packet);
+    mongoose_hooks:offline_groupchat_message(Acc, From, To, Packet);
 route_message_by_type(<<"headline">>, From, To, Acc, Packet) ->
     {stop, Acc1} = bounce_offline_message(Acc, #{from => From, to => To, packet => Packet}, #{}),
     Acc1;
@@ -782,7 +782,7 @@ route_message_by_type(_, From, To, Acc, Packet) ->
         true ->
             case is_privacy_allow(From, To, Acc, Packet) of
                 true ->
-                    mongoose_hooks:offline_message_hook(Acc, From, To, Packet);
+                    mongoose_hooks:offline_message(Acc, From, To, Packet);
                 false ->
                     mongoose_hooks:failed_to_store_message(Acc)
             end;

src/event_pusher/mod_event_pusher_hook_translator.erl

@@ -130,8 +130,8 @@ merge_acc(Acc, EventPusherAcc) ->
 hooks(HostType) ->
     [
         {filter_local_packet, HostType, fun ?MODULE:filter_local_packet/3, #{}, 80},
-        {unset_presence_hook, HostType, fun ?MODULE:user_not_present/3, #{}, 90},
-        {user_available_hook, HostType, fun ?MODULE:user_present/3, #{}, 90},
+        {unset_presence, HostType, fun ?MODULE:user_not_present/3, #{}, 90},
+        {user_available, HostType, fun ?MODULE:user_present/3, #{}, 90},
         {user_send_message, HostType, fun ?MODULE:user_send_message/3, #{}, 90},
         {unacknowledged_message, HostType, fun ?MODULE:unacknowledged_message/3, #{}, 90}
     ].

src/global_distrib/mod_global_distrib_mapping.erl

@@ -226,8 +226,8 @@ hooks(HostType) ->
     [{register_subhost, global, fun ?MODULE:register_subhost/3, #{}, 90},
      {unregister_subhost, global, fun ?MODULE:unregister_subhost/3, #{}, 90},
      {packet_to_component, global, fun ?MODULE:packet_to_component/3, #{}, 90},
-     {sm_register_connection_hook, HostType, fun ?MODULE:session_opened/3, #{}, 90},
-     {sm_remove_connection_hook, HostType, fun ?MODULE:session_closed/3, #{}, 90}].
+     {sm_register_connection, HostType, fun ?MODULE:session_opened/3, #{}, 90},
+     {sm_remove_connection, HostType, fun ?MODULE:session_closed/3, #{}, 90}].
 
 -spec normalize_jid(jid:ljid()) -> [binary()].
 normalize_jid({_, _, _} = FullJid) ->