JSON command output for pgagroal-cli
#385
Labels
feature
New feature
Comments
|
I'm all for this, so 👍 Our "sister" project - https://github.com/pgmoneta/pgmoneta - uses https://github.com/DaveGamble/cJSON for JSON handling |
Great!
So far I've used json-c https://github.com/json-c/json-c for the prototype. |
|
Yeah, since we verified that the package was available to on the supported platforms. Would it be a big change in your PoC ? |
|
I've my implementation almost complete with json-c. |
fluca1978
added a commit
to fluca1978/pgagroal
that referenced
this issue
Dec 6, 2023
…roal-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 '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 '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 that indicates if the command was in error or not; - `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 agroal#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 agroal#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. Close agroal#385 Close agroal#390
fluca1978
added a commit
to fluca1978/pgagroal
that referenced
this issue
Dec 7, 2023
…roal-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 '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 '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 that indicates if the command was in error or not; - `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 agroal#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 agroal#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. Linux CI workflow updated. Close agroal#385 Close agroal#390
fluca1978
added a commit
to fluca1978/pgagroal
that referenced
this issue
Dec 7, 2023
…roal-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 '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 '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 agroal#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 agroal#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. Linux CI workflow updated. Close agroal#385 Close agroal#390
fluca1978
added a commit
to fluca1978/pgagroal
that referenced
this issue
Dec 7, 2023
…roal-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 '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 '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 agroal#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 agroal#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. Close agroal#385 Close agroal#390
fluca1978
added a commit
to fluca1978/pgagroal
that referenced
this issue
Dec 7, 2023
…roal-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 '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 '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 agroal#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 agroal#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. Close agroal#385 Close agroal#390
fluca1978
added a commit
to fluca1978/pgagroal
that referenced
this issue
Feb 7, 2024
…roal-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 '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 '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 agroal#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 agroal#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. Close agroal#385 Close agroal#390
fluca1978
added a commit
to fluca1978/pgagroal
that referenced
this issue
Feb 7, 2024
…roal-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 '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 '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 agroal#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 agroal#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. Close agroal#385 Close agroal#390
fluca1978
added a commit
to fluca1978/pgagroal
that referenced
this issue
Feb 8, 2024
…roal-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 '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 '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 agroal#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 agroal#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. Close agroal#385 Close agroal#390
fluca1978
added a commit
to fluca1978/pgagroal
that referenced
this issue
Feb 8, 2024
…roal-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 '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 '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 agroal#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 agroal#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. Close agroal#385 Close agroal#390
fluca1978
added a commit
to fluca1978/pgagroal
that referenced
this issue
Feb 8, 2024
…roal-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 '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 '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 agroal#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 agroal#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. Close agroal#385 Close agroal#390
fluca1978
added a commit
to fluca1978/pgagroal
that referenced
this issue
Feb 8, 2024
…roal-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 '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 '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 agroal#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 agroal#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. Close agroal#385 Close agroal#390
fluca1978
added a commit
to fluca1978/pgagroal
that referenced
this issue
Feb 8, 2024
…roal-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 '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 '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 agroal#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 agroal#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. Close agroal#385 Close agroal#390
fluca1978
added a commit
to fluca1978/pgagroal
that referenced
this issue
Feb 8, 2024
…roal-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 '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 '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 agroal#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 agroal#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 agroal#385 Close agroal#390
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
I would like to propose the ability for
pgagroal-clito provide command output in a JSON format.Rationale: json would allow a more stable output to mangle via automatic applications, letting the freedom to change the text output of every command as we wish.
My idea is to change the
pgagroal_management_read_xxxmethods that provide output in order to accept a flag that indicates the format of the output itself (text, json, with text being the default). In the case the JSON output is reqiested, the command will print out a json object.The JSON returned by each command should be as much as possible consistent. Therefore it should include:
commandinformation (which command has been launched)outputthat will contain the specific command information (e.g., a list of connections)errora flag to indicate if the command was successful or notEvery output information that requires an array of entries (e.g., a list of connections) must be wrapped in a
listjson array, with acountinteger information aside. This way it should be easy to query the output result.The following is a primordial prototype I've created to demonstrate how I imagine the thing:
and with a much more verbose output
I believe there is no rush for such a thing, and this could be implemented in a slow way while working on
1.7.The text was updated successfully, but these errors were encountered: