hcq/MaxScale
hcq/MaxScale
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

MXS-553: Update and document the protocol API

Browse Source 
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.
This commit is contained in:
Markus Mäkelä 2018-05-18 13:01:54 +03:00
parent 66255361dc
commit cdb43335a2
No known key found for this signature in database
GPG Key ID: 72D48FCE664F7B19
8 changed files with 142 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
examples/testprotocol.c
View File

@ -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 =

178
include/maxscale/protocol.h
View File

@ -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.

1
server/modules/protocol/CDC/cdc.cc
View File

@ -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,

1
server/modules/protocol/HTTPD/httpd.cc
View File

@ -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

1
server/modules/protocol/MySQL/mariadbbackend/mysql_backend.cc
View File

@ -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

1
server/modules/protocol/MySQL/mariadbclient/mysql_client.cc
View File

@ -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

1
server/modules/protocol/maxscaled/maxscaled.cc
View File

@ -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

1
server/modules/protocol/telnetd/telnetd.cc
View File

@ -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