[#385][#390] JSON command output implementation for pgagroal-cli

This commit introduces the capaiblity for `pgagroal-cli` to print out
the command results in a JSON format.

A new dependency on the library 'cJSON' has been introduced;
see <https://github.com/DaveGamble/cJSON>.

A new set of functions, named 'pgagroal_json_xxx' have been added in a
separated file json.c (include file json.h) to handle JSON structures
in a more consistent way.

Each function that manipulates a JSON object has been named with the
'pgagroal_json_' prefix.
Each management function that reads data out of the
protocol and creates or handles json data has been named with the
prefix 'pgagroal_management_json_'.
A few functions with a prefix name 'pgagroal_management_json_print'
are used to print out a JSON object as normal text.

Every command output, in the JSON format, is structured with a
'command' is the main object contained in the output, that in turns
has different attributes:
- 'output' is an object that contains the command specific
information (e.g., list of databases, messages, and so on);
- `error` a boolean-like value that indicates if the command
was in error or not (0 means success, 1 means error);
- `status` a string that contains either 'OK' or an error message in
the case the `error` flag is set;
- `exit-status` an integer value with the exit status of the command,
0 in case of success, a different value in case of failure.

The JSON object for a result includes also another object, named
'application', that can be used for introspection: such object
describes which executable has launched the command (so far, only
`pgagroal-cli`) and at which version.

In the 'output' object, every thing that has a list (e.g.,
connections, limits, databases, servers) will be wrapped into an
object with the attributes 'list' and 'count': the former contains the
details of every "thing", while the latter contains the count (i.e.,
the size of the array 'list' ).
Whenever possible, a 'state' string is placed to indicate the state of
the single entry.

The command `status` and `status details` have been unified on the
management side.
There is a single function that handles both the cases of reading the
answer for the `status` or the `status details` commands. This has
been done because `status details` includes the output of `status`.
The function `pgagroal_management_json_read_status_details` is in
charge of getting the answer of the management protocol (i.e., read
the socket) and invoke the printing function in the case the output is
of type text. The above `pgagroal_management_json_read_status_details`
returns always a JSON object, that can be converted back to the text
output via `pgagroal_management_json_print_status_details`. In this
way, the output between the JSON and the text formats are always
coherent for these commands.

The `ping` (i.e., `is-alive`) command does not print nothing by
default. In the JSON version it provides the numerical status of the
server and a string that represents a human-readable status.

The `conf get` command has been refactored to be symmetric with other
commands: the logic to print out the result is now within the
management function (pgagroal_management_read_config_get) as per other
commands. The JSON provides the `config-key` and the `config-value` as
strings. See #390

The `conf set` command has been refactored similarly to `conf get` in
order to have all the logic to print out the information into the
management read method (see #390).
The exit status provided by the command is now
the result of the matching within the JSON object of the expected
configuration value and the requested configuration value.

The `conf ls` command has been refactored to produce a JSON object
when reading data out of the management socket. Such JSON object is
then printed as normal text if required.

A new utility function, named 'pgagroal_server_status_as_string' has
been added to the utils.c stuff. The idea is to have a consistent way
to translate the numerical status representation into an human
readable string.

The text output format of commands has slightly changed due to the
refactoring of some internal methods.

Documentation updated.
CI workflow updated.
Library list updated.

Added a FindcJSON.cmake file to help in finding out the library.

Update copyright of the json files to current year and community.

Close #385
Close #390

.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

CMakeLists.txt

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

README.md

@@ -69,6 +69,7 @@ See [Architecture](./doc/ARCHITECTURE.md) for the architecture of `pgagroal`.
 * [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:
@@ -79,7 +80,8 @@ dnf install git gcc cmake make    \
             openssl openssl-devel \
 	    systemd systemd-devel \
 	    python3-docutils      \
-	    libatomic
+	    libatomic             \
+	    cjson cjson-devel
 ```
 
 Please note that, on Rocky Linux, in order to install the `python3-docutils`

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 )  

doc/CLI.md

@@ -22,6 +22,7 @@ Available options are the following ones:
 -U, --user USERNAME      Set the user name
 -P, --password PASSWORD  Set the password
 -L, --logfile FILE       Set the log file
+-F, --format  text|json  Set the output format
 -v, --verbose            Output text string of result
 -V, --version            Display version information
 -?, --help               Display help
@@ -30,6 +31,11 @@ Available options are the following ones:
 
 Options can be specified either in short or long form, in any position of the command line.
 
+By default the command output, if any, is reported as text. It is possible to specify JSON as the output format,
+and this is the suggested format if there is the need to automtically parse the command output, since the text format
+could be subject to changes in future releases. For more information about the JSON output format,
+please see the [JSON Output Format](#json-output-format) section.
+
 ## Commands
 
 ### flush
@@ -380,3 +386,203 @@ pgagroal-cli reset-server 2>/dev/null
 
 There is a minimal shell completion support for `pgagroal-cli`.
 Please refer to the [Install pgagroal](https://github.com/agroal/pgagroal/blob/master/doc/tutorial/01_install.md) tutorial for detailed information about how to enable and use shell completions.
+
+
+## JSON Output Format
+
+It is possible to obtain the output of a command in a JSON format by specyfing the `-F` (`--format`) option on the command line.
+Supported output formats are:
+- `text` (the default)
+- `json`
+
+As an example, the following are invocations of commands with different output formats:
+
+```
+pgagroal-cli status     # defaults to text output format
+
+pgagroal-cli status --format text  # same as above
+pgagroal-cli status -F text        # same as above
+
+pgagroal-cli status --format json  # outputs as JSON text
+pgagroal-cli status -F json        # same as above
+```
+
+Whenever a command produces output, the latter can be obtained in a JSON format.
+Every command output consists of an object that contains two other objects:
+- a `command` object, with all the details about the command and its output;
+- an `application` object, with all the details about the executable that launched the command (e.g., `pgagroal-cli`).
+
+In the following, details about every object are provided:
+
+### The `application` object
+
+The `application` object is made by the following attributes:
+- `name` a string representing the name of the executable that launched the command;
+- `version` a string representing the version of the executable;
+- `major`, `minor`, `patch` are integers representing every single part of the version of the application.
+
+As an example, when `pgagroal-cli` launches a command, the output includes an `application` object like the following:
+
+```
+ "application":  {
+                "name": "pgagroal-cli",
+                "major":        1,
+                "minor":        6,
+                "patch":        0,
+                "version":      "1.6.0"
+        }
+```
+
+
+### The `command` object
+
+The `command` object represents the launched command and contains also the answer from the `pgagroal`.
+The object is made by the following attributes:
+- `name` a string representing the command launched (e.g., `status`);
+- `status` a string that contains either "OK" or an error string if the command failed;
+- `error` an interger value used as a flag to indicate if the command was in error or not, where `0` means success and `1` means error;
+- `exit-status` an integer that contains zero if the command run succesfully, another value depending on the specific command in case of failure;
+- `output` an object that contains the details of the executed command.
+
+The `output` object is *the variable part* in the JSON command output, that means its effective content depends on the launched command.
+
+Whenever the command output includes an array of stuff, for example a connection list, such array is wrapped into a `list` JSON array with a sibling named `count` that contains the integer size of the array (number of elements).
+
+
+The following are a few examples of commands that provide output in JSON:
+
+
+```
+pgagroal-cli ping --format json
+{
+        "command":      {
+                "name": "ping",
+                "status":       "OK",
+                "error":        0,
+                "exit-status":  0,
+                "output":       {
+                        "status":       1,
+                        "message":      "running"
+                }
+        },
+        "application":  {
+                "name": "pgagroal-cli",
+                "major":        1,
+                "minor":        6,
+                "patch":        0,
+                "version":      "1.6.0"
+        }
+}
+
+
+
+pgagroal-cli status --format json
+{
+        "command":      {
+                "name": "status",
+                "status":       "OK",
+                "error":        0,
+                "exit-status":  0,
+                "output":       {
+                        "status":       {
+                                "message":      "Running",
+                                "status":       1
+                        },
+                        "connections":  {
+                                "active":       0,
+                                "total":        2,
+                                "max":  15
+                        },
+                        "databases":    {
+                                "disabled":     {
+                                        "count":        0,
+                                        "state":        "disabled",
+                                        "list": []
+                                }
+                        }
+                }
+        },
+        "application":  {
+                "name": "pgagroal-cli",
+                "major":        1,
+                "minor":        6,
+                "patch":        0,
+                "version":      "1.6.0"
+        }
+}
+```
+
+As an example, the following is the output of a faulty `conf set` command (note the `status`, `error` and `exist-status` values):
+
+```
+pgagroal-cli conf set max_connections 1000  --format json
+{
+        "command":      {
+                "name": "conf set",
+                "status":       "Current and expected values are different",
+                "error":        true,
+                "exit-status":  2,
+                "output":       {
+                        "key":  "max_connections",
+                        "value":        "15",
+                        "expected":     "1000"
+                }
+        },
+        "application":  {
+                "name": "pgagroal-cli",
+                "major":        1,
+                "minor":        6,
+                "patch":        0,
+                "version":      "1.6.0"
+        }
+}
+```
+
+
+The `conf ls` command returns an array named `files` where each entry is made by a couple `description` and `path`, where the former
+is the mnemonic name of the configuration file, and the latter is the value of the configuration file used:
+
+```
+$ pgagroal-cli conf ls --format json
+{
+        "command":      {
+                "name": "conf ls",
+                "status":       "OK",
+                "error":        0,
+                "exit-status":  0,
+                "output":       {
+                        "files":        {
+                                "list": [{
+                                                "description":  "Main Configuration file",
+                                                "path": "/etc/pgagroal/pgagroal.conf"
+                                        }, {
+                                                "description":  "HBA File",
+                                                "path": "/etc/pgagroal/pgagroal_hba.conf"
+                                        }, {
+                                                "description":  "Limit file",
+                                                "path": "/etc/pgagroal/pgagroal_databases.conf"
+                                        }, {
+                                                "description":  "Frontend users file",
+                                                "path": "/etc/pgagroal/pgagroal_frontend_users.conf"
+                                        }, {
+                                                "description":  "Admins file",
+                                                "path": "/etc/pgagroal/pgagroal_admins.conf"
+                                        }, {
+                                                "description":  "Superuser file",
+                                                "path": ""
+                                        }, {
+                                                "description":  "Users file",
+                                                "path": "/etc/pgagroal/pgagroal_users.conf"
+                                        }]
+                        }
+                }
+        },
+        "application":  {
+                "name": "pgagroal-cli",
+                "major":        1,
+                "minor":        6,
+                "patch":        0,
+                "version":      "1.6.0"
+        }
+}
+```

src/CMakeLists.txt

@@ -22,6 +22,7 @@ if (${CMAKE_SYSTEM_NAME} STREQUAL "Linux")
     ${LIBEV_INCLUDE_DIRS}
     ${OPENSSL_INCLUDE_DIR}
     ${SYSTEMD_INCLUDE_DIRS}
+    ${CJSON_INCLUDE_DIRS}
   )
 
   #
@@ -33,6 +34,7 @@ if (${CMAKE_SYSTEM_NAME} STREQUAL "Linux")
     ${OPENSSL_SSL_LIBRARY}
     ${SYSTEMD_LIBRARIES}
     ${LIBATOMIC_LIBRARY}
+    ${CJSON_LIBRARIES}
   )
 
   set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -Wl,--no-undefined")
@@ -69,6 +71,7 @@ elseif(${CMAKE_SYSTEM_NAME} STREQUAL "Darwin")
     ${CMAKE_CURRENT_SOURCE_DIR}/include
     ${LIBEV_INCLUDE_DIRS}
     ${OPENSSL_INCLUDE_DIRS}
+    ${CJSON_INCLUDE_DIRS}
   )
 
   #
@@ -77,6 +80,7 @@ elseif(${CMAKE_SYSTEM_NAME} STREQUAL "Darwin")
   link_libraries(
     ${LIBEV_LIBRARIES}
     ${OPENSSL_LIBRARIES}
+    ${CJSON_LIBRARIES}
   )
 else()
 
@@ -98,6 +102,7 @@ else()
     ${CMAKE_CURRENT_SOURCE_DIR}/include
     ${LIBEV_INCLUDE_DIRS}
     ${OPENSSL_INCLUDE_DIRS}
+    ${CJSON_INCLUDE_DIRS}
   )
 
   #
@@ -106,6 +111,7 @@ else()
   link_libraries(
     ${LIBEV_LIBRARIES}
     ${OPENSSL_LIBRARIES}
+    ${CJSON_LIBRARIES}
   )
 endif()
 
@@ -314,3 +320,4 @@ endif()
 target_link_libraries(pgagroal-admin-bin pgagroal)
 
 install(TARGETS pgagroal-admin-bin DESTINATION ${CMAKE_INSTALL_BINDIR})
+