From 49276dfa4bd2028cf30b814aef1c8d5b4f4ced88 Mon Sep 17 00:00:00 2001 From: jesperpedersen Date: Tue, 17 Sep 2019 09:07:55 -0400 Subject: [PATCH] Initial source documentation --- src/include/configuration.h | 15 ++++- src/include/logging.h | 8 ++- src/include/management.h | 30 ++++++++-- src/include/memory.h | 13 ++-- src/include/message.h | 87 +++++++++++++++++++++------ src/include/network.h | 59 +++++++++++++----- src/include/pgagroal.h | 116 +++++++++++++++++++++--------------- src/include/pipeline.h | 11 +++- src/include/pool.h | 40 ++++++++++--- src/include/security.h | 7 ++- src/include/server.h | 15 ++++- src/include/shmem.h | 9 ++- src/include/utils.h | 41 +++++++++---- src/include/worker.h | 14 +++-- src/libpgagroal/network.c | 41 ------------- 15 files changed, 333 insertions(+), 173 deletions(-) diff --git a/src/include/configuration.h b/src/include/configuration.h index 7c9e386e..6c6256ef 100644 --- a/src/include/configuration.h +++ b/src/include/configuration.h @@ -36,19 +36,28 @@ extern "C" { #include /** - * + * Initialize the configuration structure + * @param shmem The shared memory segment + * @param size The size of the configuration + * @return 0 upon success, otherwise 1 */ int pgagroal_init_configuration(void* shmem, size_t size); /** - * + * Read the configuration from a file + * @param filename The file name + * @param shmem The shared memory segment + * @return 0 upon success, otherwise 1 */ int pgagroal_read_configuration(char* filename, void* shmem); /** - * + * Read the HBA configuration from a file + * @param filename The file name + * @param shmem The shared memory segment + * @return 0 upon success, otherwise 1 */ int pgagroal_read_hba_configuration(char* filename, void* shmem); diff --git a/src/include/logging.h b/src/include/logging.h index ae3c7271..06881762 100644 --- a/src/include/logging.h +++ b/src/include/logging.h @@ -50,13 +50,17 @@ extern "C" { #define PGAGROAL_LOGGING_LEVEL_FATAL 6 /** - * + * Start the logging system + * @param shmem The shared memory segment + * @return 0 upon success, otherwise 1 */ int pgagroal_start_logging(void* shmem); /** - * + * Stop the logging system + * @param shmem The shared memory segment + * @return 0 upon success, otherwise 1 */ int pgagroal_stop_logging(void* shmem); diff --git a/src/include/management.h b/src/include/management.h index 538229e4..cb3ed35a 100644 --- a/src/include/management.h +++ b/src/include/management.h @@ -42,37 +42,55 @@ extern "C" { #define MANAGEMENT_FLUSH 3 /** - * + * Read the management header + * @param socket The socket descriptor + * @param id The resulting management identifier + * @param slot The resulting slot + * @return 0 upon success, otherwise 1 */ int pgagroal_management_read_header(int socket, signed char* id, int32_t* slot); /** - * + * Read the management payload + * @param socket The socket descriptor + * @param id The management identifier + * @param payload The resulting payload + * @return 0 upon success, otherwise 1 */ int pgagroal_management_read_payload(int socket, signed char id, int* payload); /** - * + * Free the management payload + * @param payload The payload */ void pgagroal_management_free_payload(void* payload); /** - * + * Management operation: Transfer a connection + * @param shmem The shared memory segment + * @param slot The slot + * @return 0 upon success, otherwise 1 */ int pgagroal_management_transfer_connection(void* shmem, int32_t slot); /** - * + * Management operation: Kill a connection + * @param shmem The shared memory segment + * @param slot The slot + * @return 0 upon success, otherwise 1 */ int pgagroal_management_kill_connection(void* shmem, int32_t slot); /** - * + * Management operation: Flush the pool + * @param shmem The shared memory segment + * @param mode The flush mode + * @return 0 upon success, otherwise 1 */ int pgagroal_management_flush(void* shmem, int32_t mode); diff --git a/src/include/memory.h b/src/include/memory.h index 509a6e1e..21eab4d2 100644 --- a/src/include/memory.h +++ b/src/include/memory.h @@ -38,31 +38,34 @@ extern "C" { #include /** - * + * Initialize a memory segment for the process local message structure + * @param shmem The shared memory segment */ void pgagroal_memory_init(void* shmem); /** - * + * Get the message structure + * @return The structure */ struct message* pgagroal_memory_message(void); /** - * + * Get the pointer to the message data section + * @return The pointer */ void* pgagroal_memory_data(void); /** - * + * Free the memory segment */ void pgagroal_memory_free(void); /** - * + * Destroy the memory segment */ void pgagroal_memory_destroy(void); diff --git a/src/include/message.h b/src/include/message.h index 7c1653c5..9ade0b60 100644 --- a/src/include/message.h +++ b/src/include/message.h @@ -43,115 +43,164 @@ extern "C" { #define MESSAGE_STATUS_ERROR 2 /** - * + * Read a message + * @param socket The socket descriptor + * @param msg The resulting message + * @return One of MESSAGE_STATUS_ZERO, MESSAGE_STATUS_OK or MESSAGE_STATUS_ERROR */ int pgagroal_read_message(int socket, struct message** msg); /** - * + * Read a message in blocking mode + * @param socket The socket descriptor + * @param msg The resulting message + * @return One of MESSAGE_STATUS_ZERO, MESSAGE_STATUS_OK or MESSAGE_STATUS_ERROR */ int pgagroal_read_block_message(int socket, struct message** msg); /** - * + * Write a message + * @param socket The socket descriptor + * @param msg The message + * @return One of MESSAGE_STATUS_ZERO, MESSAGE_STATUS_OK or MESSAGE_STATUS_ERROR */ int pgagroal_write_message(int socket, struct message* msg); /** - * + * Write a message with NODELAY + * @param socket The socket descriptor + * @param msg The message + * @return One of MESSAGE_STATUS_ZERO, MESSAGE_STATUS_OK or MESSAGE_STATUS_ERROR */ int pgagroal_write_nodelay_message(int socket, struct message* msg); /** - * + * Create a message + * @param data A pointer to the data + * @param length The length of the message + * @param msg The resulting message + * @return 0 upon success, otherwise 1 */ int pgagroal_create_message(void* data, ssize_t length, struct message** msg); /** - * + * Copy a message + * @param msg The resulting message + * @return The copy */ struct message* pgagroal_copy_message(struct message* msg); /** - * + * Free a message + * @param msg The resulting message */ void pgagroal_free_message(struct message* msg); /** - * + * Free a copy message + * @param msg The resulting message */ void pgagroal_free_copy_message(struct message* msg); /** - * + * Get the request identifier + * @param msg The message + * @return The identifier */ int32_t pgagroal_get_request(struct message* msg); /** - * + * Extract the user name and database from a message + * @param msg The message + * @param username The resulting user name + * @param database The resulting database + * @return 0 upon success, otherwise 1 */ int pgagroal_extract_username_database(struct message* msg, char** username, char** database); /** - * + * Write an empty message + * @param socket The socket descriptor + * @return 0 upon success, otherwise 1 */ int pgagroal_write_empty(int socket); /** - * + * Write a notice message + * @param socket The socket descriptor + * @return 0 upon success, otherwise 1 */ int pgagroal_write_notice(int socket); /** - * + * Write a pool is full message + * @param socket The socket descriptor + * @return 0 upon success, otherwise 1 */ int pgagroal_write_pool_full(int socket); /** - * + * Write a bad password message + * @param socket The socket descriptor + * @param username The user name + * @return 0 upon success, otherwise 1 */ int pgagroal_write_bad_password(int socket, char* username); /** - * + * Write an unsupported security model message + * @param socket The socket descriptor + * @param username The user name + * @return 0 upon success, otherwise 1 */ int pgagroal_write_unsupported_security_model(int socket, char* username); /** - * + * Write a no HBA entry message + * @param socket The socket descriptor + * @param username The user name + * @param database The database + * @param address The client address + * @return 0 upon success, otherwise 1 */ int pgagroal_write_no_hba_entry(int socket, char* username, char* database, char* address); /** - * + * Write a deallocate all message + * @param socket The socket descriptor + * @return 0 upon success, otherwise 1 */ int pgagroal_write_deallocate_all(int socket); /** - * + * Write a terminate message + * @param socket The socket descriptor + * @return 0 upon success, otherwise 1 */ int pgagroal_write_terminate(int socket); /** - * + * Is the connection valid + * @param socket The socket descriptor + * @return true upon success, otherwise false */ bool pgagroal_connection_isvalid(int socket); diff --git a/src/include/network.h b/src/include/network.h index 160907b3..e082c96b 100644 --- a/src/include/network.h +++ b/src/include/network.h @@ -37,67 +37,94 @@ extern "C" { #include /** - * + * Bind sockets for a host + * @param hostname The host name + * @param port The port number + * @param shmem The shared memory segment + * @param fds The resulting descriptors + * @param length The resulting length of descriptors + * @return 0 upon success, otherwise 1 */ int pgagroal_bind(const char* hostname, int port, void* shmem, int** fds, int* length); /** - * + * Bind a Unix Domain Socket + * @param directory The directory + * @param shmem The shared memory segment + * @return 0 upon success, otherwise 1 */ int pgagroal_bind_unix_socket(const char* directory, void* shmem); /** - * + * Connect to a host + * @param shmem The shared memory segment + * @param hostname The host name + * @param port The port number + * @param fd The resulting descriptor + * @return 0 upon success, otherwise 1 */ int pgagroal_connect(void* shmem, const char* hostname, int port, int* fd); /** - * + * Connect to a Unix Domain Socket + * @param directory The directory + * @param fd The resulting descriptor + * @return 0 upon success, otherwise 1 */ int pgagroal_connect_unix_socket(const char* directory, int* fd); /** - * + * Disconnect from a descriptor + * @param fd The descriptor + * @return 0 upon success, otherwise 1 */ int pgagroal_disconnect(int fd); /** - * + * Get the sockaddr_in structure + * @param sa The sockaddr structure + * @return The sockaddr_in / sockaddr_in6 structure */ void* pgagroal_get_sockaddr(struct sockaddr *sa); /** - * + * Get the address of a sockaddr + * @param sa The sockaddr structure + * @param address The result address + * @param length The length */ void pgagroal_get_address(struct sockaddr *sa, char* address, size_t length); /** - * - */ -int -pgagroal_is_ready(int fd); - -/** - * + * Apply TCP/NODELAY to a descriptor + * @param fd The descriptor + * @param shmem The shared memory segment + * @return 0 upon success, otherwise 1 */ int pgagroal_tcp_nodelay(int fd, void* shmem); /** - * + * Set the configured socket buffer size to a descriptor + * @param fd The descriptor + * @param shmem The shared memory segment + * @return 0 upon success, otherwise 1 */ int pgagroal_socket_buffers(int fd, void* shmem); /** - * + * Apply O_NONBLOCK to a descriptor + * @param fd The descriptor + * @param shmem The shared memory segment + * @return 0 upon success, otherwise 1 */ int pgagroal_socket_nonblocking(int fd, void* shmem); diff --git a/src/include/pgagroal.h b/src/include/pgagroal.h index 4cfcb372..f2766126 100644 --- a/src/include/pgagroal.h +++ b/src/include/pgagroal.h @@ -95,84 +95,102 @@ extern "C" { #define likely(x) __builtin_expect (!!(x), 1) #define unlikely(x) __builtin_expect (!!(x), 0) +/** @struct + * Defines a server + */ struct server { - char name[MISC_LENGTH]; - char host[MISC_LENGTH]; - int port; - int primary; + char name[MISC_LENGTH]; /**< The name of the server */ + char host[MISC_LENGTH]; /**< The host name of the server */ + int port; /**< The port of the server */ + int primary; /**< The status of the server */ } __attribute__ ((aligned (64))); +/** @struct + * Defines a connection + */ struct connection { - atomic_int state; - bool new; - int server; - char username[IDENTIFIER_LENGTH]; - char database[IDENTIFIER_LENGTH]; - int has_security; - ssize_t security_lengths[NUMBER_OF_SECURITY_MESSAGES]; - char security_messages[NUMBER_OF_SECURITY_MESSAGES][SECURITY_BUFFER_SIZE]; - time_t timestamp; - int fd; + atomic_int state; /**< The state */ + bool new; /**< Is the connection new */ + int server; /**< The server identifier */ + char username[IDENTIFIER_LENGTH]; /**< The user name */ + char database[IDENTIFIER_LENGTH]; /**< The database */ + int has_security; /**< The security identifier */ + ssize_t security_lengths[NUMBER_OF_SECURITY_MESSAGES]; /**< The lengths of the security messages */ + char security_messages[NUMBER_OF_SECURITY_MESSAGES][SECURITY_BUFFER_SIZE]; /**< The security messages */ + time_t timestamp; /**< The last used timestamp */ + int fd; /**< The descriptor */ } __attribute__ ((aligned (64))); +/** @struct + * Defines a HBA entry + */ struct hba { - char type[16]; - char database[IDENTIFIER_LENGTH]; - char user[IDENTIFIER_LENGTH]; - char address[IDENTIFIER_LENGTH]; - char method[IDENTIFIER_LENGTH]; + char type[16]; /**< The type */ + char database[IDENTIFIER_LENGTH]; /**< The database */ + char user[IDENTIFIER_LENGTH]; /**< The user name */ + char address[IDENTIFIER_LENGTH]; /**< The address / mask */ + char method[IDENTIFIER_LENGTH]; /**< The access method */ } __attribute__ ((aligned (64))); +/** @struct + * Defines the configuration and state of pgagroal + */ struct configuration { - char host[MISC_LENGTH]; - int port; + char host[MISC_LENGTH]; /**< The host */ + int port; /**< The port */ - int log_type; - int log_level; - char log_path[MISC_LENGTH]; + int log_type; /**< The logging type */ + int log_level; /**< The logging level */ + char log_path[MISC_LENGTH]; /**< The logging path */ - atomic_int number_of_connections; - int max_connections; + atomic_int number_of_connections; /**< The current number of connections */ + int max_connections; /**< The maximum number of connections */ - int blocking_timeout; - int idle_timeout; - int validation; - int background_interval; + int blocking_timeout; /**< The blocking timeout in seconds */ + int idle_timeout; /**< The idle timeout in seconds */ + int validation; /**< Validation mode */ + int background_interval; /**< Background validation timer in seconds */ - char libev[MISC_LENGTH]; - int buffer_size; - bool keep_alive; - bool nodelay; - bool non_blocking; - int backlog; + char libev[MISC_LENGTH]; /**< Name of libev mode */ + int buffer_size; /**< Socket buffer size */ + bool keep_alive; /**< Use keep alive */ + bool nodelay; /**< Use NODELAY */ + bool non_blocking; /**< Use non blocking */ + int backlog; /**< The backlog for listen */ - char unix_socket_dir[MISC_LENGTH]; + char unix_socket_dir[MISC_LENGTH]; /**< The directory for the Unix Domain Socket */ - int number_of_servers; - int number_of_hbas; + int number_of_servers; /**< The number of active servers */ + int number_of_hbas; /**< The number of active HBA entries */ - struct server servers[NUMBER_OF_SERVERS]; - struct connection connections[MAX_NUMBER_OF_CONNECTIONS]; - struct hba hbas[NUMBER_OF_HBAS]; + struct server servers[NUMBER_OF_SERVERS]; /**< The servers */ + struct connection connections[MAX_NUMBER_OF_CONNECTIONS]; /**< The connections */ + struct hba hbas[NUMBER_OF_HBAS]; /**< The HBA entries */ } __attribute__ ((aligned (64))); +/** @struct + * Defines a message + */ struct message { - signed char kind; - ssize_t length; - size_t max_length; - void* data; + signed char kind; /**< The kind of the message */ + ssize_t length; /**< The length of the message */ + size_t max_length; /**< The maximum size of the message */ + void* data; /**< The message data */ } __attribute__ ((aligned (64))); +/** @struct + * Defines the signal structure + */ struct signal_info { - struct ev_signal signal; - void* shmem; - int slot; + struct ev_signal signal; /**< The libev base type */ + void* shmem; /**< The shared memory segment */ + int slot; /**< The slot */ }; #ifdef __cplusplus diff --git a/src/include/pipeline.h b/src/include/pipeline.h index cd8e403d..949d75a6 100644 --- a/src/include/pipeline.h +++ b/src/include/pipeline.h @@ -40,12 +40,19 @@ extern "C" { typedef void (*callback)(struct ev_loop *, struct ev_io *, int); +/** @struct + * Define the structure for a pipeline + */ struct pipeline { - callback client; - callback server; + callback client; /**< The callback for the client */ + callback server; /**< The callback for the server */ }; +/** + * Get the performance pipeline + * @return The structure + */ struct pipeline performance_pipeline(); #ifdef __cplusplus diff --git a/src/include/pool.h b/src/include/pool.h index 4a21fa9e..2bbc13ef 100644 --- a/src/include/pool.h +++ b/src/include/pool.h @@ -38,55 +38,77 @@ extern "C" { #include /** - * + * Get a connection + * @param shmem The shared memory segment + * @param username The user name + * @param database The database + * @param slot The resulting slot + * @return 0 upon success, otherwise 1 */ int pgagroal_get_connection(void* shmem, char* username, char* database, int* slot); /** - * + * Return a connection + * @param shmem The shared memory segment + * @param slot The slot + * @return 0 upon success, otherwise 1 */ int pgagroal_return_connection(void* shmem, int slot); /** - * + * Kill a connection + * @param shmem The shared memory segment + * @param slot The slot + * @return 0 upon success, otherwise 1 */ int pgagroal_kill_connection(void* shmem, int slot); /** - * + * Perform idle timeout + * @param shmem The shared memory segment */ void pgagroal_idle_timeout(void* shmem); /** - * + * Perform connection validation + * @param shmem The shared memory segment */ void pgagroal_validation(void* shmem); /** - * + * Flush the pool + * @param shmem The shared memory segment + * @param mode The flush mode + * @return 0 upon success, otherwise 1 */ int pgagroal_flush(void* shmem, int mode); /** - * + * Initialize the pool + * @param shmem The shared memory segment + * @return 0 upon success, otherwise 1 */ int pgagroal_pool_init(void* shmem); /** - * + * Shutdown the pool + * @param shmem The shared memory segment + * @return 0 upon success, otherwise 1 */ int pgagroal_pool_shutdown(void* shmem); /** - * + * Print the status of the pool + * @param shmem The shared memory segment + * @return 0 upon success, otherwise 1 */ int pgagroal_pool_status(void* shmem); diff --git a/src/include/security.h b/src/include/security.h index 0cbac426..24c14501 100644 --- a/src/include/security.h +++ b/src/include/security.h @@ -38,7 +38,12 @@ extern "C" { #include /** - * + * Authenticate a user + * @param client_fd The descriptor + * @param address The client address + * @param shmem The shared memory segment + * @param slot The resulting slot + * @return 0 upon success, otherwise 1 */ int pgagroal_authenticate(int client_fd, char* address, void* shmem, int* slot); diff --git a/src/include/server.h b/src/include/server.h index 6262655d..1741f5bc 100644 --- a/src/include/server.h +++ b/src/include/server.h @@ -38,19 +38,28 @@ extern "C" { #include /** - * + * Get the primary server + * @param shmem The shared memory segment + * @param server The resulting server identifier + * @return 0 upon success, otherwise 1 */ int pgagroal_get_primary(void* shmem, int* server); /** - * + * Update the server state + * @param shmem The shared memory segment + * @param slot The slot + * @param socket The descriptor + * @return 0 upon success, otherwise 1 */ int pgagroal_update_server_state(void* shmem, int slot, int socket); /** - * + * Print the state of the servers + * @param shmem The shared memory segment + * @return 0 upon success, otherwise 1 */ int pgagroal_server_status(void* shmem); diff --git a/src/include/shmem.h b/src/include/shmem.h index 33880ace..88da1617 100644 --- a/src/include/shmem.h +++ b/src/include/shmem.h @@ -36,13 +36,18 @@ extern "C" { #include /** - * + * Create a shared memory segment + * @param size The size of the segment + * @return The pointer to the segment */ void* pgagroal_create_shared_memory(size_t size); /** - * + * Destroy a shared memory segment + * @param shmem The shared memory segment + * @param size The size + * @return 0 upon success, otherwise 1 */ int pgagroal_destroy_shared_memory(void* shmem, size_t size); diff --git a/src/include/utils.h b/src/include/utils.h index 9edab9ef..bfab4674 100644 --- a/src/include/utils.h +++ b/src/include/utils.h @@ -38,61 +38,79 @@ extern "C" { #include /** - * + * Read a byte + * @param data Pointer to the data + * @return The byte */ signed char pgagroal_read_byte(void* data); /** - * + * Read an int16 + * @param data Pointer to the data + * @return The int16 */ int16_t pgagroal_read_int16(void* data); /** - * + * Read an int32 + * @param data Pointer to the data + * @return The int32 */ int32_t pgagroal_read_int32(void* data); /** - * + * Read a string + * @param data Pointer to the data + * @return The string */ char* pgagroal_read_string(void* data); /** - * + * Write a byte + * @param data Pointer to the data + * @param b The byte */ void pgagroal_write_byte(void* data, signed char b); /** - * + * Write an int32 + * @param data Pointer to the data + * @param i The int32 */ void pgagroal_write_int32(void* data, int32_t i); /** - * + * Write a string + * @param data Pointer to the data + * @param s The string */ void pgagroal_write_string(void* data, char* s); /** - * + * Print the available libev engines */ void pgagroal_libev_engines(); /** - * + * Get the constant for a libev engine + * @param engine The name of the engine + * @return The constant */ unsigned int pgagroal_libev(char* engine); /** - * + * Get the name for a libev engine + * @param val The constant + * @return The name */ char* pgagroal_libev_engine(unsigned int val); @@ -100,7 +118,8 @@ pgagroal_libev_engine(unsigned int val); #ifdef DEBUG /** - * + * Decode a message + * @param msg The message */ void pgagroal_decode_message(struct message* msg); diff --git a/src/include/worker.h b/src/include/worker.h index ea297c53..de71a8bd 100644 --- a/src/include/worker.h +++ b/src/include/worker.h @@ -42,18 +42,24 @@ extern "C" { #define WORKER_SERVER_FAILURE 3 #define WORKER_SERVER_FATAL 4 +/** @struct + * The worker structure for each IO event + */ struct worker_info { - struct ev_io io; - int client_fd; - int server_fd; + struct ev_io io; /**< The libev base type */ + int client_fd; /**< The client descriptor */ + int server_fd; /**< The server descriptor */ }; extern volatile int running; extern volatile int exit_code; /** - * + * Create a worker instance + * @param fd The client descriptor + * @param address The client address + * @param shmem The shared memory segment */ void pgagroal_worker(int fd, char* address, void* shmem); diff --git a/src/libpgagroal/network.c b/src/libpgagroal/network.c index 45b1d756..af91cbf8 100644 --- a/src/libpgagroal/network.c +++ b/src/libpgagroal/network.c @@ -340,47 +340,6 @@ pgagroal_get_address(struct sockaddr *sa, char* address, size_t length) } } -int -pgagroal_is_ready(int fd) -{ - fd_set readmask; - fd_set exceptmask; - int fds; - struct timeval timeout; - struct timeval *timeoutp; - - timeout.tv_sec = 0; - timeout.tv_usec = 1; - timeoutp = &timeout; - - for (;;) - { - FD_ZERO(&readmask); - FD_ZERO(&exceptmask); - FD_SET(fd, &readmask); - FD_SET(fd, &exceptmask); - - fds = select(fd + 1, &readmask, NULL, &exceptmask, timeoutp); - if (fds == -1) - { - return -1; - } - else if (fds == 0) - { - return 0; - } - - if (FD_ISSET(fd, &exceptmask)) - { - return -1; - } - - return 1; - } - - return -1; -} - int pgagroal_socket_nonblocking(int fd, void* shmem) {