WL#6885: Flag to indicate session state

Affects: Server-5.7   —   Status: In-Documentation

As part of detecting if it is possible to change connections in a
load-balanced environment, it is necessary to detect if there is any
session-specific state that can affect what connection to use.

For that reason, it is critical to be able to see in the response
packet if there is a session state to take into consideration when
deciding if a switch can be made.

The session state consists of:
- User-defined variables
- Session-specific values for server variables.
- Temporary tables that are created.
- Prepared statements.
- Current database.

This worklog will then add a tracker to the
response packet of the MySQL protocol and all necessary changes to the
server to ensure that it can be detected if a session state exists on
the server.
Functional & Non-Functional Requirements
========================================

F1. It shall be possible for a client to set the new system variable 
    'session_track_state_change'.

F2. 'session_track_state_change' must be a read/write system variable 
    of boolean type.

F3. 'session_track_state_change' must have both global as well as session 
    scope.

F4. 'session_track_state_change' must be settable at command line.

F5. 'session_track_state_change' must accept only ON/OFF values.

F6. 'session_track_state_change' must default to OFF.

F7. 'session_track_state_change' when set to invalid value apart from ON/OFF
    an error is reported.

F8. The value of 'session_track_state_change' must be accessible through
    'SHOW VARIABLES' command and INFORMATION_SCHEMA's SESSION_VARIABLES/
    GLOBAL_VARIABLES tables.

F9. Old-clients must be able to interact with the new-server that has this 
    feature.

F10. Old server must be able to interact with the new-clients that support
     this feature.

F11. New client when interacting with old server, if enables   
     'session_track_state_change' variable then an error is returned.

F12. There will be a new boolean state tracker sent in the OK packet.

F13. The tracker will have a single 1/0 byte payload.

F14. The tracker (with 1 in its payload) will be sent in the OK packet 
     immediately following the statement that made a session state change.

F15. The tracker will be available through the C API functions defined in 
     WL#4797.

F16. The tracker will be reset back to false/0 via the COM_RESET_CONNECTION 
     RPC (in which case a tracker with a FALSE must be sent).

F17. The tracker will consider a state change (and raise the tracker) in the 
     following cases:
     - user defined variable assignment
     - successful session specific value for server configuration variables
       assignment
     - temporary tables created, altered or deleted
     - prepared statements added or removed
     - change of the current database

F18. Setting the tracker itself should not send any information in the 
     OK packet.
     ex: set session_track_state_change=1; should not send the the 
     boolean tracker in the OK packet.
Problem Description:
====================

In order to ensure session migration from one server to another we need a 
means to know if there is any session context available so that the context 
can be migrated to the target server. This worklog will implement a means to
let the connectors/fabric know that there is a change in session state by 
sending a tracker(flag) to the client in the OK packet.

New implementation:
====================

As part of this worklog any change in server session state will be tracked
by the client. Changes that contributes to a server session state are 
session system variables, user-defined variables, temporary tables,
prepared statements and current database. As part of this worklog a new
system variable will be introduced which can be set to ON/OFF to allow
the client to track about the session state change. State change notification
will be sent in the OK packet as a boolean value and is sent to the client 
only in response to change in attributes that contribute to session state.
Tracking/sending the session state notification can be turned ON/OFF by the 
client.
 
** Server-side changes **
=========================

A new system variable will be introduced to track the session state change.

  Name                : session_track_state_change
  Scope               : Session
  Value               : Bool
  Default             : OFF
  Command line option : Yes
  R/W system variable : Yes
  R/W session variable: Yes 

  For example:

  mysql> set @session_track_state_change=ON;
  This will make the server to track all types of session state.
  The type of session state can be one of the following:
  1. Adding/Deleting a prepared statement.
  2. Changing any server system variable.
  3. Changing any user variable (irrespective of set/unset).
  4. Creating/Dropping temporary tables.
  5. Change in current database.

  Modifying the above attributes will trigger the server
  to send a boolean tracker in the OK packet if this variable is set 
  to ON.

  If any other value apart from ON/OFF is specified then an error
  will be reported. 

Note: Any changes to Global system variables are not tracked and no 
notification is sent in the OK packet.

This enum will further be extended to add a new tracker as shown below:

enum enum_session_state_type
{
   SESSION_TRACK_SYSTEM_VARIABLES,     /* Session system variables */
   SESSION_TRACK_SCHEMA,               /* Current schema */
   SESSION_TRACK_STATE_CHANGE          /* a boolean tracker to track 
                                          any change to session */
 };

The above enum is introduced in WL#4797 which will be extended in this WL.
Data format for the newly introduced tracker is as shown below:
   [<1 byte boolean flag>]

1 represents there is a change in session state.
0 represents there is no change in session state.

Backward/Cross Compatibility
============================

New Server / Old Client:
In this case even if server can send the new boolean tracker information
client will read only the needed session context from the packet and skip
the remaining.

Old Server / New Client:
In this case even though client is capable of reading new session context
it need not do so, as server is not aware of new session trackers context
and will never send that information. Also an error is returned.