From cdb43335a24bcc11fda789fc1ff6d397bdb7a5fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= Date: Fri, 18 May 2018 13:01:54 +0300 Subject: [PATCH] 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 | 6 +- include/maxscale/protocol.h | 178 ++++++++++++++---- server/modules/protocol/CDC/cdc.cc | 1 - server/modules/protocol/HTTPD/httpd.cc | 1 - .../MySQL/mariadbbackend/mysql_backend.cc | 1 - .../MySQL/mariadbclient/mysql_client.cc | 1 - .../modules/protocol/maxscaled/maxscaled.cc | 1 - server/modules/protocol/telnetd/telnetd.cc | 1 - 8 files changed, 142 insertions(+), 48 deletions(-) diff --git a/examples/testprotocol.c b/examples/testprotocol.c index 396825cc7..06aab3e57 100644 --- a/examples/testprotocol.c +++ b/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_default_auth, /**< Default authenticator */ + test_connection_limit, /**< Connection limit */ + NULL }; static MXS_MODULE info = diff --git a/include/maxscale/protocol.h b/include/maxscale/protocol.h index 07500312d..28263b159 100644 --- a/include/maxscale/protocol.h +++ b/include/maxscale/protocol.h @@ -28,47 +28,147 @@ struct server; struct session; /** - * @verbatim - * 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 + * Protocol module API */ typedef struct mxs_protocol { - int32_t (*read)(struct dcb *); - int32_t (*write)(struct dcb *, GWBUF *); - int32_t (*write_ready)(struct dcb *); - int32_t (*error)(struct dcb *); - int32_t (*hangup)(struct dcb *); - int32_t (*accept)(struct dcb *); - int32_t (*connect)(struct dcb *, struct server *, struct session *); - int32_t (*close)(struct 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 - char *(*auth_default)(); - int32_t (*connlimit)(struct dcb *, int limit); - bool (*established)(struct dcb *); + /** + * EPOLLIN handler, used to read available data from network socket + * + * @param dcb DCB to read from + * + * @return 1 on success, 0 on error + */ + int32_t (*read)(struct dcb* dcb); + + /** + * Write data to a network socket + * + * @param dcb DCB to write to + * @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. diff --git a/server/modules/protocol/CDC/cdc.cc b/server/modules/protocol/CDC/cdc.cc index 9ed84f50d..74e0dc3ad 100644 --- a/server/modules/protocol/CDC/cdc.cc +++ b/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, diff --git a/server/modules/protocol/HTTPD/httpd.cc b/server/modules/protocol/HTTPD/httpd.cc index b5e5635ba..cdac18355 100644 --- a/server/modules/protocol/HTTPD/httpd.cc +++ b/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 diff --git a/server/modules/protocol/MySQL/mariadbbackend/mysql_backend.cc b/server/modules/protocol/MySQL/mariadbbackend/mysql_backend.cc index 44c656874..64901cbfd 100644 --- a/server/modules/protocol/MySQL/mariadbbackend/mysql_backend.cc +++ b/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 diff --git a/server/modules/protocol/MySQL/mariadbclient/mysql_client.cc b/server/modules/protocol/MySQL/mariadbclient/mysql_client.cc index 8c20fd093..a8b59e7d9 100644 --- a/server/modules/protocol/MySQL/mariadbclient/mysql_client.cc +++ b/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 diff --git a/server/modules/protocol/maxscaled/maxscaled.cc b/server/modules/protocol/maxscaled/maxscaled.cc index 7044382e6..ad289a285 100644 --- a/server/modules/protocol/maxscaled/maxscaled.cc +++ b/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 diff --git a/server/modules/protocol/telnetd/telnetd.cc b/server/modules/protocol/telnetd/telnetd.cc index ee70b2646..28b8402c9 100644 --- a/server/modules/protocol/telnetd/telnetd.cc +++ b/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