Cmdr/docs/Async.md

### Async Commands ###

An async command is a virtual command that the host can use to send data to the client at any time while connected to the host. As the name implies, the occurance of a client receiving data from an async command is not always the result of running a regular command in the current session. This can occur for example when information in your account is changed by another client connected to the host; your client would not know about this change until an async command is sent notify it of the change. These commands cannot be called directly by a client or even a module command object.

Async commands are not only used send data to the client but also used internally within the host to help session objects operating in different processes to communicate with each other. Some async commands in fact are considered internal only because the client should never see any data come from them at anytime.

These are considered "virtual" commands because there is no defined command objects attached to them. Instead, async commands are best identified by command id values 1-255. Here is a list of currently "defined" async commands:

```
#define ASYNC_RDY                1
#define ASYNC_SYS_MSG            2
#define ASYNC_EXE_CRASH          3
#define ASYNC_EXIT               4   // internal only
#define ASYNC_CAST               5   // internal only
#define ASYNC_MAXSES             6   // internal only
#define ASYNC_LOGOUT             7   // internal only
#define ASYNC_USER_DELETED       8   
#define ASYNC_GROUP_RENAMED      9   // internal only
#define ASYNC_DISP_RENAMED       10  // internal only
#define ASYNC_GRP_TRANS          11  // internal only
#define ASYNC_USER_GROUP_CHANGED 12  // internal only
#define ASYNC_CMD_RANKS_CHANGED  13  // internal only
#define ASYNC_RESTART            14  // internal only
#define ASYNC_ENABLE_MOD         15  // internal only
#define ASYNC_DISABLE_MOD        16  // internal only
#define ASYNC_GROUP_UPDATED      17  // internal only
#define ASYNC_END_SESSION        18  // internal only
#define ASYNC_USER_LOGIN         19  // internal only
#define ASYNC_RESTORE_AUTH       20  // internal only
#define ASYNC_TO_PEER            21
#define ASYNC_LIMITED_CAST       22
#define ASYNC_RW_MY_INFO         23  // internal only
#define ASYNC_P2P                24
#define ASYNC_CLOSE_P2P          25  // internal only
#define ASYNC_NEW_CH_MEMBER      26
#define ASYNC_DEL_CH             27
#define ASYNC_RENAME_CH          28
#define ASYNC_CH_ACT_FLAG        29
#define ASYNC_NEW_SUB_CH         30
#define ASYNC_RM_SUB_CH          31
#define ASYNC_RENAME_SUB_CH      32
#define ASYNC_INVITED_TO_CH      33
#define ASYNC_RM_CH_MEMBER       34
#define ASYNC_INVITE_ACCEPTED    35
#define ASYNC_MEM_LEVEL_CHANGED  36
#define ASYNC_SUB_CH_LEVEL_CHG   37
#define ASYNC_ADD_RDONLY         38
#define ASYNC_RM_RDONLY          39
#define ASYNC_ADD_CMD            40
#define ASYNC_RM_CMD             41
#define ASYNC_USER_RENAMED       42
#define ASYNC_PUBLIC_AUTH        43  // internal only
```

### Async Data ###

```ASYNC_RDY (1)```
This command signals to the client that your current session is now ready to start running commands. This is usually sent after successfully setting up the tcp connection or after successfully recovering from a session crash. It can carry ```TEXT``` data that can be displayed directly to the user if needed.

```ASYNC_SYS_MSG (2)```
This command carry ```TEXT``` or ```ERR``` data that are system messages that can be directly displayed to the user of needed. It is also used to carry ```HOST_CERT``` data during the tcp connection setup and ```MY_INFO``` when local user account information has changed.

```ASYNC_EXE_CRASH (3)```
This is used to send ```ERR``` messages to the client if your session crashes or fails to setup a command executor at the host side for any reason.

```ASYNC_EXIT (4)```
This is an internal async command that doesn't carry any data. This will cause the host to stop listing for clients, close all sessions and then close the main process.

```ASYNC_CAST (5)```
This is an internal only command that carries a 54byte open sub-channels list and an embedded mrci frame that can then be sent to clients that have any of the matching open sub-channels. It drops that sub-channel list before arriving at the client so it will apppear like a regular mrci frame of any data type.

```ASYNC_MAXSES (6)```
Internal only async command that is used by internal commands to send a ```BYTES``` frame to the main process to update the maximum amount the concurrent sessions for the host. The data itself is actually a 32bit unsigned int.

```ASYNC_LOGOUT (7)```
This internal only async command doesn't carry any data. This is just used to notify the main process that the user has logged out and should not attempt to restore authentication in case of a session crash. This doesn't actually do the logout.

```ASYNC_USER_DELETED (8)```
This async command carry ```TEXT``` data that is the user name of the user account that was deleted from the host database. All sessions that get this command must read and match this to the user name that is currently logged in. If the user name matches, the session must logout and forward this to the client since the user account no longer exists.

```ASYNC_GROUP_RENAMED (9)```
Internal only async command that carry ```TEXT``` command line arguments to notify all sessions that the a host group name has changed. Example: ```-src "old_group_name" -dst "new_group_name"```. All sessions that have matching current group names to ```old_group_name``` must update that group name to ```new_group_name``` and also send a ```ASYNC_SYS_MSG``` to the client containing an updated ```MY_INFO```.

```ASYNC_DISP_RENAMED (10)```
Internal only async command that carry ```TEXT``` command line arguments to notify all sessions that a user has changed the display name. Example: ```-name "new_display_name" -user "user_name"```. All sessions that have matching current user names to ```user_name``` must update the display name to ```new_display_name``` and also send a ```ASYNC_SYS_MSG``` to the client containing an updated ```MY_INFO```.

```ASYNC_GRP_TRANS (11)```
Internal only async command that carry the same ```TEXT``` command line arguments as ```ASYNC_GROUP_RENAMED``` to notify all sessions that the all users currently in the group given in ```-src``` must be updated to the group given in ```-dst```. This triggers a ```ASYNC_SYS_MSG``` to send an updated ```MY_INFO``` and the session will load all the commands that the user now have access to and remove any commands that lost access due to the group change.

```ASYNC_USER_GROUP_CHANGED (12)```
This is an internal only async command that carry ```TEXT``` command line arguments to notify all sessions that a user's group was changed to another group. example: ```-user "user_name" -group "new_group"```. All sessions the have the matching user name need to update it's group to ```new_group```, send a ```ASYNC_SYS_MSG``` with an updated ```MY_INFO``` and load all the commands that the user now have access to and remove any commands that lost access due to the group change.

```ASYNC_CMD_RANKS_CHANGED (13)```
This internal only async commmand doesn't carry any data. Instead, it notifies all sessions that the assigned command ranks have changed. This will cause all sessions to re-check the currently loaded commands and determine if it needs to remove any commands that the user no longer have access to and add any commands that the user may have gained access to.

```ASYNC_RESTART (14)```
This internal only async commmand doesn't carry any data. This will cause the host to stop listing for clients, close all sessions, reload the host settings and start listening for clients again.

```ASYNC_ENABLE_MOD (15)```
This internal only async commmand carry ```TEXT``` of a module name. All sessions that receive this will then load the requested module.

```ASYNC_DISABLE_MOD (16)```
This internal only async commmand carry ```TEXT``` of a module name. All sessions that receive this will delete all commands associated with this module and then unload it.

```ASYNC_GROUP_UPDATED (17)```
This is an internal only command that carry ```TEXT``` command line arguments to notify all sessions that a group's host rank has changed. Example: ```-name "group_name" -rank 2```. All sessions that have matching group names to ```group_name``` will need to update the host rank to ```2```. When the session's host rank is adjusted this way, the session will need to re-check the currently loaded commands and determine if it needs to remove any commands that the user no longer have access to and add any commands that the user may have gained access to.

```ASYNC_END_SESSION (18)```
This internal only async commmand doesn't carry any data. It will signal the session to close at the host side.

```ASYNC_USER_LOGIN (19)```
This is an internal only command that carry ```PRIV_IPC``` data containing the 256bit Keccak hash user id of the user that has successfully logged in. This is used by the command executor to notify the main process of the current user associated with the current session. The main process will use this information to restore the user authorization in case of a session crash.

```ASYNC_RESTORE_AUTH (20)```
This is an internal only command that carry ```PRIV_IPC``` data containing the 256bit Keccak hash user id of a user that has successfully logged in with the current session. It is used by the main process to tell the command executor in the slave process to authorize the user without a password. This is only used when attempting to restore the session from a crash and a user was logged in at the time.

```ASYNC_TO_PEER (21)```
This is an async command that carry an embedded mrci frame directly to/from peer sessions without any restrictions. It is prepended with the 224bit sha3 hash of the target session id; however, it drops that session id before arriving at the client so it will apppear as a regular mrci frame of any data type. Users should not be given direct access to this for security reasons.

```ASYNC_LIMITED_CAST (22)```
This operate exactly like ```ASYNC_CAST``` except only sessions with active update sub-channels will respond to it.

```ASYNC_RW_MY_INFO (23)```
This internal only async command carry ```TEXT``` data of the user name to tell all sessions that have the matching user name to send an update ```MY_INFO``` to the client. This is useful for when a host admin force updates user information of other lesser privileged users to make their clients aware of the changes.

```ASYNC_P2P (24)```
This async command carry an embedded mrci frame directly to/from peer sessions following the p2p negotiation process as described in [Type_IDs](Type_IDs.md), at the P2P specific data types. It prepends the 224bit sha3 hash of the destination session id and source session id; however, it drops the destination id and source id for just the P2P specific data types before arriving at the client. For all other data types (if a p2p connection is estabished), the source id is prepend-moved to the payload of the mrci frame before arriving at the client.

```ASYNC_CLOSE_P2P (25)```
This internal only async command carry a 224bit sha3 hash session id of a session that is about to close. This notifies all sessions that have matching hashes in p2p accepted and p2p pending list to remove them now. It also triggers a ```ASYNC_P2P``` to send a ```P2P_CLOSE``` for the session id in question so the clients can also be made aware of this.

```ASYNC_NEW_CH_MEMBER (26)```
```TEXT``` command line arguments when a new channel is created and the user that created it is added as the channel owner. Example: ```-user "user_name" -ch_name "new_channel" -ch_id 334 -level 1```.

```ASYNC_DEL_CH (27)```
```TEXT``` command line arguments when a channel is deleted. Example: ```-ch_name "channel_name" -ch_id 426```. The host will automatically close all sub-channels related to this channel for all sessions that have them open.

```ASYNC_RENAME_CH (28)```
```TEXT``` command line arguments when a channel is renamed. Example: ```-ch_name "old_name" -new_name "new_name"```.

```ASYNC_CH_ACT_FLAG (29)```
```TEXT``` command line arguments when sub-channel's active update flag has been updated. Example: ```-ch_name "channel_name" -sub_name "sub_channel" -state 1```. (```-state``` 1 is true or ```-state``` 0 is false).

```ASYNC_NEW_SUB_CH (30)```
```TEXT``` command line arguments when a new sub-channel is created. Example: ```-ch_name "channel_name" -sub_name "new_sub_channel" -ch_id 987 -sub_id 5 -level 2```.

```ASYNC_RM_SUB_CH (31)```
```TEXT``` command line arguments when a sub-channel is deleted. Example: ```-ch_name "channel_name" -sub_name "sub_channel" -ch_id 987 -sub_id 5```. The host will automatically close this sub-channel for sessions that currently have it open.

```ASYNC_RENAME_SUB_CH (32)```
```TEXT``` command line arguments when a sub-channel is renamed. Example: ```-ch_name "channel_name" -sub_name "sub_channel" -new_name "new_sub_name"```.

```ASYNC_INVITED_TO_CH (33)```
```TEXT``` command line arguments when a new user is invited to join a channel. Example: ```-ch_name "channel_name" -user "user_name"```.

```ASYNC_RM_CH_MEMBER (34)```
```TEXT``` command line arguments when a user is kicked from a channel, uninvited or has left the channel. Example: ```-ch_name "channel_name" -user "user_name" -ch_id 746```.

```ASYNC_INVITE_ACCEPTED (35)```
```TEXT``` command line arguments when a user that was previously invite to join the channel has accepted the invite and should now be considered full member of the channel starting off at level ```REGULAR```. Example: ```-ch_name "channel_name" -user "user_name"```.

```ASYNC_MEM_LEVEL_CHANGED (36)```
```TEXT``` command line arguments when a channel member's privilege level is changed. Example: ```-ch_name "channel_name" -user "user_name" -ch_id 774 -level 2```. The host automatically closes all sub-channels related to the channel for the affected user. It will be will up to the client to re-open the sub-channel(s) if the user still have access to it/them.

```ASYNC_SUB_CH_LEVEL_CHG (37)```
```TEXT``` command line arguments when a sub-channel's lowest level of access is changed. Example: ```-ch_name "channel_name" -sub_name "sub_channel" -level 3 -ch_id 645 -sub_id 5```. The host will automatically close this sub-channel for sessions that currently have it open. It will be up to the client to reopen it if the current user still have access to it.

```ASYNC_ADD_RDONLY (38)```
```TEXT``` command line arguments when a read only flag is added to a sub-channel's access level. Example: ```-ch_name "channel_name" -sub_id 5 -level 4```. The host will automatically close this sub-channel for sessions that currently have it open. It will be up to the client to reopen it if the current user still have access to it.

```ASYNC_RM_RDONLY (39)```
```TEXT``` command line arguments when a read only flag is removed from a sub-channel's access level. Example: ```-ch_name "channel_name" -sub_id 5 -level 4```. The host will automatically close this sub-channel for sessions that currently have it open. It will be up to the client to reopen it if the current user still have access to it.

```ASYNC_ADD_CMD (40)```
This async command carry ```NEW_CMD``` when the session's command executor loads a new command object and wants to notify the client of it.

```ASYNC_RM_CMD (41)```
This async command carry ```CMD_ID``` when the session's command executor deletes a command object and wants to notify the client of it.

```ASYNC_USER_RENAMED (42)```
```TEXT``` command line arguments when a user changes it's user name. Example: ```-old "old_user_name" -new_name "new_user_name"```.

```ASYNC_PUBLIC_AUTH (43)```
This internal only async commmand doesn't carry any data. It just tells the command executor to load or reload commands without an authorized user so only public commands will be available until the client authorizes into a user account. This is used by the host when starting a session for the first time or if restoring the session after a crash and no user was logged in at the time.