[agroal#361] Add a max_connection_age setting

This defines how long a connection will live in seconds
- Add a `max_connection_age` member to `struct configuration`. It will be checked upon returned to the pool, or during idle timeout.
- Add new STATE, TRACKER, and Prometheus metric for `max_connection_age`
- Add documentation for `max_connection_age`
- Add a `start_time` member to `struct connection`. Its implementation is similar to `timestamp`

[agroal#378] Vault Implementaion

[agroal#253][agroal#209] Refactor commands in `pgagroal-cli` and `pgagroal-admin`

Now `pgagroal-cli` has a set of "logically" grouped commands and
subcommands. For example, all the commands related to shutting down
the pooler are under the `shutdown` command, that can operate with
subcommands like `gracefully`, `immediate` or `cancel`.

In order to provide this capability, new functions have been
introduced as utilities:
- `parse_command()` accepts the command line and seek for a command,
possibly its subcommand, and an optional "value" (often the database
or server name).
- `parse_command_simple()` is a wrapper around the above
`parse_command` that shorten the function call line because it does
not require to specify the key and the value (and their defaults).
- `parse_deprecated_command()` does pretty much the same thing but
against the old command. Thanks to this, old commands can still work
and the user will be warned about their deprecation, but the interface
of `pgagroal-cli` is not broken.

All the above functions require to know the offset at which start seeking for
a command, and that depends on the number of options already parsed
via `getopt_long()`. Since the `&option_index` is valued only for long
options, I decided to use the `optind` global value, see
getopt_long(3).
This value is initialized with the "next thing" to seek on the command
line, i.e., the next index on `argv`.

In the case the command accepts an optional database name, the
database value is automatically set to '*' (all databases) in case the
database name is not found on the command line.
Therefore:
   pgagroal-cli flush idle
is equivalent to
   pgagroal-cli flush idle '*'

On the other hand, commands that require a server name get the value
automatically set to "\0" (an invalid server name) in order to "block"
other pieces of code. Moroever, if the server has not been specified,
the command is automatically set to "unknown" so that the help screen
is shown.

The `pgagroal-cli` has a set of `pgagroal_log_debug()` calls whenever
a command is "parsed", so that it is possible to quickly follow the
command line parsing.

Also, since the `pgagroal-cli` exists if no command line arguments
have been specified, the safety check aboutt `argc > 0` around the
command line parsing has been removed.

In the case the user specified an unknown command, she is warned on
stdout before printing the `usage()` help screen.

Deprecated commands are notified to the user via a warning message,
printed on stderr, that provides some hints about the correct usage of
the new command. The warning about deprecated commands is shown only
if the currently running version of the software is greater than the
version the command has been deprecated onto. In particular these
commands have been deprecated since 1.6.

This commit also introduces the command refactoring for `pgagroal-admin` in
a way similar to the work done for `pgagroal-cli`.
New commands are available:
- user <what>
with <what> being <add>, <del>, <edit>, <ls>.

Updated:
- documentation
- shell completions
- help screens
- examples

Close agroal#290 agroal#253

[agroal#381] Changes to `pgagroal-cli` commands

This commit changes two commands in `pgagroal-cli`.

The `is-alive` command is deprecated by means of the `ping`
command. Documentation has been modified accordingly.

The `details` command is now deprecated by the `status details`
one. To achieve this, the `status details` is parsed _before_ the
`status` one (that has not changed at all). In order to better reflect
this change, the internal constant `ACTION_DETAILS` has been renamed
to `ACTION_STATUS_DETAIL`.

Documentation updated accordingly.
Shell completions updated accordingly.

Close agroal#381

[agroal#378] Vault Implementation

.github/workflows/ci.yml

@@ -19,6 +19,8 @@ jobs:
       run: sudo apt update -y
     - name: Install libev
       run: sudo apt install -y libev4 libev-dev
+    - name: Install cJSON
+      run: sudo apt install -y libcjson1 libcjson-dev
     - name: Install systemd
       run: sudo apt install -y libsystemd-dev
     - name: Install rst2man
@@ -63,6 +65,8 @@ jobs:
       run: brew install openssl
     - name: Install libev
       run: brew install libev
+    - name: Install cJSON
+      run: brew install cjson
     - name: Install rst2man
       run: brew install docutils
     - name: Install clang

AUTHORS

@@ -1,10 +1,11 @@
 pgagroal was created by the following authors:
 
-Jesper Pedersen <jesper.pedersen@redhat.com>
+Jesper Pedersen <jesper.pedersen@comcast.net>
 David Fetter <[email protected]>
 Will Leinweber <[email protected]>
 Junduo Dong <[email protected]>
 Luca Ferrari <[email protected]>
 Nikita Bugrovsky <[email protected]>
 Lawrence Wu <[email protected]>
 Yongting You <[email protected]>
+Ashutosh Sharma <[email protected]>

CMakeLists.txt

@@ -1,7 +1,7 @@
 cmake_minimum_required(VERSION 3.14.0)
 
 set(VERSION_MAJOR "1")
-set(VERSION_MINOR "6")
+set(VERSION_MINOR "7")
 set(VERSION_PATCH "0")
 set(VERSION_STRING ${VERSION_MAJOR}.${VERSION_MINOR}.${VERSION_PATCH})
 
@@ -78,6 +78,16 @@ else ()
   message(FATAL_ERROR "rst2man needed")
 endif()
 
+# search for cJSON library
+# <https://github.com/DaveGamble/cJSON>
+find_package(cJSON)
+if (cJSON_FOUND)
+  message(STATUS "cJSON found version ${CJSON_VERSION}")
+else ()
+  message(FATAL_ERROR "cJSON needed")
+endif()
+
+
 if (${CMAKE_SYSTEM_NAME} STREQUAL "Linux")
   find_package(Libatomic)
   if (LIBATOMIC_FOUND)

CODE_OF_CONDUCT.md

@@ -33,7 +33,7 @@ projects.
 This code of conduct applies both within project spaces and in public spaces
 when an individual is representing the project or its community.
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting a maintainer of the project, Jesper Pedersen <jesper.pedersen@redhat.com>.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting a maintainer of the project, Jesper Pedersen <jesper.pedersen@comcast.net>.
 
 ### pgagroal Events Code of Conduct
 

LICENSE

@@ -1,5 +1,5 @@
 
-Copyright (C) 2023 Red Hat
+Copyright (C) 2024 The pgagroal community
 
 Redistribution and use in source and binary forms, with or without modification,
 are permitted provided that the following conditions are met:

README.md

@@ -68,12 +68,31 @@ See [Architecture](./doc/ARCHITECTURE.md) for the architecture of `pgagroal`.
 * [OpenSSL](http://www.openssl.org/)
 * [systemd](https://www.freedesktop.org/wiki/Software/systemd/)
 * [rst2man](https://docutils.sourceforge.io/)
+* [libatomic](https://gcc.gnu.org/wiki/Atomic)
+* [cJSON](https://github.com/DaveGamble/cJSON)
+
+On Rocky Linux (and similar) operating systems, the dependencies
+can be installed via `dnf(8)` as follows:
+
+```sh
+dnf install git gcc cmake make    \
+            libev libev-devel     \
+            openssl openssl-devel \
+	    systemd systemd-devel \
+	    python3-docutils      \
+	    libatomic             \
+	    cjson cjson-devel
+```
+
+Please note that, on Rocky Linux, in order to install the `python3-docutils`
+package (that provides `rst2man` executable), you need to enable the `crb` repository:
 
 ```sh
-dnf install git gcc cmake make libev libev-devel openssl openssl-devel systemd systemd-devel python3-docutils
+dnf config-manager --set-enabled crb
 ```
 
-Alternative [clang 8+](https://clang.llvm.org/) can be used.
+
+Alternatively to GCC, [clang 8+](https://clang.llvm.org/) can be used.
 
 ### Release build
 

cmake/FindcJSON.cmake

@@ -0,0 +1,51 @@
+# FindcJSON.cmake
+# Tries to find cJSON libraries on the system
+# (e.g., on Rocky Linux: cjson and cjson-devel)
+#
+# Inspired by <https://sources.debian.org/src/monado/21.0.0~dfsg1-1/cmake/FindcJSON.cmake/>
+#
+# If cJSON is found, sets the following variables:
+# - CJSON_INCLUDE_DIRS
+# - CJSON_LIBRARIES
+# - CJSON_VERSION
+#
+# In the header file cJSON.h the library version is specified as:
+# #define CJSON_VERSION_MAJOR 1
+# #define CJSON_VERSION_MINOR 7
+# #define CJSON_VERSION_PATCH 14
+
+
+find_path(
+    CJSON_INCLUDE_DIR
+    NAMES cjson/cJSON.h
+    PATH_SUFFIXES include)
+find_library(
+    CJSON_LIBRARY
+    NAMES cjson
+    PATH_SUFFIXES lib)
+
+include(FindPackageHandleStandardArgs)
+find_package_handle_standard_args(cJSON REQUIRED_VARS CJSON_INCLUDE_DIR
+                                                      CJSON_LIBRARY)
+if(CJSON_FOUND)
+  # these variables are needed for the build
+  set( CJSON_INCLUDE_DIRS "${CJSON_INCLUDE_DIR}" )
+  set( CJSON_LIBRARIES    "${CJSON_LIBRARY}"     )
+
+  # try to get out the library version from the headers
+  file(STRINGS "${CJSON_INCLUDE_DIR}/cjson/cJSON.h"
+    CJSON_VERSION_MAJOR REGEX "^#define[ \t]+CJSON_VERSION_MAJOR[ \t]+[0-9]+")
+  file(STRINGS "${CJSON_INCLUDE_DIR}/cjson/cJSON.h"
+    CJSON_VERSION_MINOR REGEX "^#define[ \t]+CJSON_VERSION_MINOR[ \t]+[0-9]+")
+    file(STRINGS "${CJSON_INCLUDE_DIR}/cjson/cJSON.h"
+    CJSON_VERSION_PATCH REGEX "^#define[ \t]+CJSON_VERSION_PATCH[ \t]+[0-9]+")
+  string(REGEX REPLACE "[^0-9]+" "" CJSON_VERSION_MAJOR "${CJSON_VERSION_MAJOR}")
+  string(REGEX REPLACE "[^0-9]+" "" CJSON_VERSION_MINOR "${CJSON_VERSION_MINOR}")
+  string(REGEX REPLACE "[^0-9]+" "" CJSON_VERSION_PATCH "${CJSON_VERSION_PATCH}")
+  set(CJSON_VERSION "${CJSON_VERSION_MAJOR}.${CJSON_VERSION_MINOR}.${CJSON_VERSION_PATCH}")
+  unset(CJSON_VERSION_MINOR)
+  unset(CJSON_VERSION_MAJOR)
+  unset(CJSON_VERSION_PATCH)
+endif()
+
+mark_as_advanced( CJSON_INCLUDE_DIR CJSON_LIBRARY )  

contrib/shell_comp/pgagroal_comp.bash

@@ -2,27 +2,61 @@
 
 # COMP_WORDS contains
 # at index 0 the executable name (pgagroal-cli)
-# at index 1 the command name (e.g., flush-all)
+# at index 1 the command name (e.g., flush)
+# at index 2, if required, the subcommand name (e.g., all)
 pgagroal_cli_completions()
 {
 
     if [ "${#COMP_WORDS[@]}" == "2" ]; then
         # main completion: the user has specified nothing at all
         # or a single word, that is a command
-        COMPREPLY=($(compgen -W "flush-idle flush-gracefully flush-all is-alive enable disable stop gracefully status details switch-to reload reset reset-server config-get config-set" "${COMP_WORDS[1]}"))
+        COMPREPLY=($(compgen -W "flush ping enable disable shutdown status switch-to conf clear" "${COMP_WORDS[1]}"))
+    else
+        # the user has specified something else
+        # subcommand required?
+        case ${COMP_WORDS[1]} in
+            flush)
+                COMPREPLY+=($(compgen -W "gracefully idle all" "${COMP_WORDS[2]}"))
+                ;;
+            shutdown)
+                COMPREPLY+=($(compgen -W "gracefully immediate cancel" "${COMP_WORDS[2]}"))
+                ;;
+            clear)
+                COMPREPLY+=($(compgen -W "server prometheus" "${COMP_WORDS[2]}"))
+                ;;
+	    conf)
+		COMPREPLY+=($(compgen -W "reload get set ls" "${COMP_WORDS[2]}"))
+		;;
+	    status)
+		COMPREPLY+=($(compgen -W "details" "${COMP_WORDS[2]}"))
+        esac
     fi
+
+
 }
 
 
+
 pgagroal_admin_completions()
 {
     if [ "${#COMP_WORDS[@]}" == "2" ]; then
         # main completion: the user has specified nothing at all
         # or a single word, that is a command
-        COMPREPLY=($(compgen -W "master-key add-user update-user remove-user list-users" "${COMP_WORDS[1]}"))
+        COMPREPLY=($(compgen -W "master-key user" "${COMP_WORDS[1]}"))
+    else
+        # the user has specified something else
+        # subcommand required?
+        case ${COMP_WORDS[1]} in
+            user)
+                COMPREPLY+=($(compgen -W "add del edit ls" "${COMP_WORDS[2]}"))
+                ;;
+        esac
     fi
 }
 
+
+
+
 # install the completion functions
 complete -F pgagroal_cli_completions pgagroal-cli
 complete -F pgagroal_admin_completions pgagroal-admin

contrib/shell_comp/pgagroal_comp.zsh

@@ -6,14 +6,86 @@ function _pgagroal_cli()
 {
     local line
     _arguments -C \
-               "1: :(flush-idle flush-all flush-gracefully is-alive enable disable stop gracefully status details switch-to reload reset reset-server config-get config-set)" \
+               "1: :(flush ping enable disable shutdown status switch-to conf clear)" \
+               "*::arg:->args"
+
+    case $line[1] in
+        flush)
+            _pgagroal_cli_flush
+            ;;
+        shutdown)
+            _pgagroal_cli_shutdown
+            ;;
+        clear)
+            _pgagroal_cli_clear
+            ;;
+	conf)
+	    _pgagroal_cli_conf
+	    ;;
+	status)
+	    _pgagroal_cli_status
+	    ;;
+    esac
+}
+
+function _pgagroal_cli_flush()
+{
+    local line
+    _arguments -C \
+               "1: :(gracefully idle all)" \
+               "*::arg:->args"
+}
+
+function _pgagroal_cli_conf()
+{
+    local line
+    _arguments -C \
+               "1: :(reload get set ls)" \
+               "*::arg:->args"
+}
+
+function _pgagroal_cli_shutdown()
+{
+    local line
+    _arguments -C \
+               "1: :(gracefully immediate cancel)" \
                "*::arg:->args"
 }
 
+function _pgagroal_cli_clear()
+{
+    local line
+    _arguments -C \
+               "1: :(server prometheus)" \
+               "*::arg:->args"
+}
+
+
 function _pgagroal_admin()
 {
     local line
     _arguments -C \
-               "1: :(master-key add-user update-user remove-user list-users)" \
+               "1: :(master-key user)" \
+               "*::arg:->args"
+
+    case $line[1] in
+        user)
+            _pgagroal_admin_user
+            ;;
+    esac
+}
+
+function _pgagroal_admin_user()
+{
+    _arguments -C \
+               "1: :(add del edit ls)" \
+               "*::arg:->args"
+}
+
+function _pgagroal_cli_status()
+{
+    local line
+    _arguments -C \
+               "1: :(details)" \
                "*::arg:->args"
 }

contrib/valgrind/README.md

@@ -0,0 +1,16 @@
+# Valgrind
+
+The [Valgrind](https://valgrind.org/) tool suite provides a number of debugging and profiling tools that help you make your programs faster and more correct. The most popular and the default of these tools is called **Memcheck**. It can detect many memory-related errors that can lead to crashes and unpredictable behaviour.
+
+# Run memory management detection
+
+``` bash
+valgrind --leak-check=full --show-leak-kinds=all --log-file=%p.log --trace-children=yes --track-origins=yes --read-var-info=yes ./pgagroal -c pgagroal.conf -a pgagroal_hba.conf
+```
+
+# Generate valgrind report with suppressed rules
+
+``` bash
+valgrind --suppressions=../../contrib/valgrind/pgagroal.supp --leak-check=full --show-leak-kinds=all --log-file=%p.log --trace-children=yes --track-origins=yes --read-var-info=yes ./pgagroal -c pgagroal.conf -a pgagroal_hba.conf
+```
+