MXS-553: Update and document the protocol API

Removed unused and properly documented all entry points in the protocol
module API. As the removal of the `session` entry point is an backwards
incompatible change, the protocol API version was updated.

examples/testprotocol.c

@@ -105,9 +105,9 @@ MXS_MODULE* MXS_CREATE_MODULE()
         test_close,       /**< Close                         */
         test_listen,      /**< Create a listener             */
         test_auth,        /**< Authentication                */
-        test_session,     /**< Session                       */
         test_default_auth, /**< Default authenticator        */
-        test_connection_limit   /**< Connection limit        */
+        test_connection_limit, /**< Connection limit         */
+        NULL
     };
 
     static MXS_MODULE info =

include/maxscale/protocol.h

@@ -28,47 +28,147 @@ struct server;
 struct session;
 
 /**
- * @verbatim
+ * Protocol module API
- * The operations that can be performed on the descriptor
- *
- *      read            EPOLLIN handler for the socket
- *      write           MaxScale data write entry point
- *      write_ready     EPOLLOUT handler for the socket, indicates
- *                      that the socket is ready to send more data
- *      error           EPOLLERR handler for the socket
- *      hangup          EPOLLHUP handler for the socket
- *      accept          Accept handler for listener socket only
- *      connect         Create a connection to the specified server
- *                      for the session pased in
- *      close           MaxScale close entry point for the socket
- *      listen          Create a listener for the protocol
- *      auth            Authentication entry point
- *      session         Session handling entry point
- *      auth_default    Default authenticator name
- *      connlimit       Maximum connection limit
- *      established     Whether connection is fully established
- * @endverbatim
- *
- * This forms the "module object" for protocol modules within the gateway.
- *
- * @see load_module
  */
 typedef struct mxs_protocol
 {
-    int32_t (*read)(struct dcb *);
+    /**
-    int32_t (*write)(struct dcb *, GWBUF *);
+     * EPOLLIN handler, used to read available data from network socket
-    int32_t (*write_ready)(struct dcb *);
+     *
-    int32_t (*error)(struct dcb *);
+     * @param dcb DCB to read from
-    int32_t (*hangup)(struct dcb *);
+     *
-    int32_t (*accept)(struct dcb *);
+     * @return 1 on success, 0 on error
-    int32_t (*connect)(struct dcb *, struct server *, struct session *);
+     */
-    int32_t (*close)(struct dcb *);
+    int32_t (*read)(struct dcb* dcb);
-    int32_t (*listen)(struct dcb *, char *);
+
-    int32_t (*auth)(struct dcb *, struct server *, struct session *, GWBUF *);
+    /**
-    int32_t (*session)(struct dcb *, void *); // TODO: remove this, not used
+     * Write data to a network socket
-    char   *(*auth_default)();
+     *
-    int32_t (*connlimit)(struct dcb *, int limit);
+     * @param dcb    DCB to write to
-    bool    (*established)(struct dcb *);
+     * @param buffer Buffer to write
+     *
+     * @return 1 on success, 0 on error
+     */
+    int32_t (*write)(struct dcb* dcb, GWBUF* buffer);
+
+    /**
+     * EPOLLOUT handler, used to write buffered data
+     *
+     * @param dcb DCB to write to
+     *
+     * @return 1 on success, 0 on error
+     *
+     * @note Currently the return value is ignored
+     */
+    int32_t (*write_ready)(struct dcb* dcb);
+
+    /**
+     * EPOLLERR handler
+     *
+     * @param dcb DCB for which the error occurred
+     *
+     * @return 1 on success, 0 on error
+     *
+     * @note Currently the return value is ignored
+     */
+    int32_t (*error)(struct dcb* dcb);
+
+    /**
+     * EPOLLHUP and EPOLLRDHUP handler
+     *
+     * @param dcb DCB for which the hangup occurred
+     *
+     * @return 1 on success, 0 on error
+     *
+     * @note Currently the return value is ignored
+     */
+    int32_t (*hangup)(struct dcb* dcb);
+
+    /**
+     * Accept a connection, only for client side protocol modules
+     *
+     * @param dcb The listener DCB
+     *
+     * @return 1 on success, 0 on error
+     *
+     * @note Currently the return value is ignored
+     */
+    int32_t (*accept)(struct dcb* dcb);
+
+    /**
+     * Connect to a server, only for backend side protocol modules
+     *
+     * @param dcb     DCB to connect
+     * @param server  Server where the connection is made
+     * @param session The session where the DCB should be linked to
+     *
+     * @return The opened file descriptor or DCBFD_CLOSED on error
+     */
+    int32_t (*connect)(struct dcb* dcb, struct server* server, struct session* session);
+
+    /**
+     * Free protocol data allocated in the connect handler
+     *
+     * @param dcb DCB to close
+     *
+     * @return 1 on success, 0 on error
+     *
+     * @note Currently the return value is ignored
+     */
+    int32_t (*close)(struct dcb* dcb);
+
+    /**
+     * Listen on a network socket, only for client side protocol modules
+     *
+     * @param dcb     DCB to listen with
+     * @param address Address to listen on in `address|port` format
+     *
+     * @return 1 on success, 0 on error
+     */
+    int32_t (*listen)(struct dcb* dcb, char* address);
+
+    /**
+     * Perform user re-authentication
+     *
+     * @param dcb     DCB to re-authenticate
+     * @param server  Server where the DCB is connected
+     * @param session The session for the DCB
+     * @param buffer  The buffer containing the original re-authentication request
+     *
+     * @return 1 on success, 0 on error
+     *
+     * @note Currently the return value is ignored
+     */
+    int32_t (*auth)(struct dcb* dcb, struct server* server, struct session* session, GWBUF* buffer);
+
+    /**
+     * Returns the name of the default authenticator module for this protocol
+     *
+     * @return The name of the default authenticator
+     */
+    char* (*auth_default)();
+
+    /**
+     * Handle connection limits
+     *
+     * @param dcb   DCB to handle
+     * @param limit Maximum number of connections
+     *
+     * @return 1 on success, 0 on error
+     *
+     * @note Currently the return value is ignored
+     */
+    int32_t (*connlimit)(struct dcb* dcb, int limit);
+
+    /**
+     * Check if the connection has been fully established, used by connection pooling
+     *
+     * @param dcb DCB to check
+     *
+     * @return True if the connection is fully established and can be pooled
+     */
+    bool (*established)(struct dcb* );
+
 } MXS_PROTOCOL;
 
 /**
@@ -76,7 +176,7 @@ typedef struct mxs_protocol
  * the MXS_PROTOCOL structure is changed. See the rules defined in modinfo.h
  * that define how these numbers should change.
  */
-#define MXS_PROTOCOL_VERSION      {1, 1, 0}
+#define MXS_PROTOCOL_VERSION      {2, 0, 0}
 
 /**
  * Specifies capabilities specific for protocol.

server/modules/protocol/CDC/cdc.cc

@@ -86,7 +86,6 @@ MXS_MODULE* MXS_CREATE_MODULE()
         cdc_close, /* Close                         */
         cdc_listen, /* Create a listener             */
         NULL, /* Authentication                */
-        NULL, /* Session                       */
         cdc_default_auth, /* default authentication */
         NULL,
         NULL,

server/modules/protocol/HTTPD/httpd.cc

@@ -81,7 +81,6 @@ MXS_MODULE* MXS_CREATE_MODULE()
         httpd_close,        /**< Close                         */
         httpd_listen,       /**< Create a listener             */
         NULL,               /**< Authentication                */
-        NULL,               /**< Session                       */
         httpd_default_auth, /**< Default authenticator         */
         NULL,               /**< Connection limit reached      */
         NULL

server/modules/protocol/MySQL/mariadbbackend/mysql_backend.cc

@@ -82,7 +82,6 @@ MXS_MODULE* MXS_CREATE_MODULE()
         gw_backend_close,           /* Close                         */
         NULL,                       /* Listen                        */
         gw_change_user,             /* Authentication                */
-        NULL,                       /* Session                       */
         gw_backend_default_auth,    /* Default authenticator         */
         NULL,                       /* Connection limit reached      */
         gw_connection_established

server/modules/protocol/MySQL/mariadbclient/mysql_client.cc

@@ -105,7 +105,6 @@ extern "C"
             gw_client_close,                        /* Close                         */
             gw_MySQLListener,                       /* Listen                        */
             NULL,                                   /* Authentication                */
-            NULL,                                   /* Session                       */
             gw_default_auth,                        /* Default authenticator         */
             gw_connection_limit,                    /* Send error connection limit   */
             NULL

server/modules/protocol/maxscaled/maxscaled.cc

@@ -183,7 +183,6 @@ MXS_MODULE* MXS_CREATE_MODULE()
         maxscaled_close,                /**< Close                         */
         maxscaled_listen,               /**< Create a listener             */
         NULL,                           /**< Authentication                */
-        NULL,                           /**< Session                       */
         mxsd_default_auth,              /**< Default authenticator         */
         NULL,                           /**< Connection limit reached      */
         NULL

server/modules/protocol/telnetd/telnetd.cc

@@ -102,7 +102,6 @@ MXS_MODULE* MXS_CREATE_MODULE()
         telnetd_close,                  /**< Close                         */
         telnetd_listen,                 /**< Create a listener             */
         NULL,                           /**< Authentication                */
-        NULL,                           /**< Session                       */
         telnetd_default_auth,           /**< Default authenticator         */
         NULL,                           /**< Connection limit reached      */
         NULL