Configuration overhaul for upcoming 3rd-party plugin support - [merged] #105

Closed alexander-haller closed 1 month ago

In GitLab by @mhxion on Jun 24, 2024, 02:15

Merges overridable-config -> dev

This PR mainly adds necessary design improvements to configuration system to make room for proper 3rd-party plugin support. We introduce a lot of new architectural improvements and a few new features.

`--override-config`/`--OC`

What we have seen in the meeting so far. One visual change made just now was: --OC was moved to its own section called elapi global options. This is to mean --OC is not quite like the other global option --help, where --OC can only be passed after the main program name elapi, and --help can be passed after almost any command/sub-command. This will also allow us to add more global options like --OC in the future.

Ease of plugin creation

Creating a plugin would now require just two lines of code inside cli.py.

$ pwd
/Users/<username>/.local/share/elapi/plugins/test

$ ls
__init__.py  cli.py

$ cat cli.py
from elapi.plugins.commons import Typer

# Plugin metadata
app = Typer(name="test", help="Test plugin.")

Robust configuration

Configuration values in elapi.yml are now properly validated. This fixes #30.

$ cat elapi.yml
host: True # <-- Invalid value
api_token: xxx-xxxxxxxxxx

$ elapi get info
CRITICAL 'host' is detected in configuration file, but it's not a string.                                                      validators.py:58

   P.S.: Host contains the URL of the root API endpoint. Example:
   host: 'https://demo.elabftw.net/api/v2'

This configuration validation is automatically run for all plugins (internal and 3rd-party). Scripts that are not plugins, however, will need to add the following boilerplate code for the validation to run. Though, running validation is not strictly necessary.

from elapi.validators import Validate, MainConfigurationValidator, ValidationError, Exit

if MainConfigurationValidator.ALREADY_VALIDATED is False:  # Only run this validation if validation was never run before
    validate_config = Validate(MainConfigurationValidator())
    try:
        validate_config()  # Run validation
    except ValidationError:  # Catch any error
        raise Exit(1)  # Abort. We could log some message before this line
    else:
        MainConfigurationValidator.ALREADY_VALIDATED = True  # If validation is run successfully, we update the status.

New configuration fields

We introduce two new configuration fields that will affect all plugins and raw commands.

# elapi.yml
verify_ssl: true  # Can be true or false.
timeout: 10  # In seconds. Default is 5.

elAPI's design pattern (or architecture) for plugin support

elAPI is built on a distinct design pattern named "Simple layered design pattern" that has allowed plugin support relatively swiftly with minimal maintenance in the first place. This design pattern is a generalization of layered pattern that doesn't have most of the cons of layered pattern. Until now, the implementation of the architecture was flawed. With this PR, the implementation is much more stable. Documentation/literature about this design pattern is yet to be completed.

elAPI-design-pattern.pdf

Additional remarks

elAPi is only accepting JSON as its input format for most CLI inline options including the new --OC, and --data, --header, --query. Typing JSON can get cumbersome and can be error prone. It'd be nice to be able to pass a YAML/JSON file instead. This was Alexander's suggestion which is yet to be worked on.

In GitLab by @mhxion on Jun 24, 2024, 02:15

requested review from @alexander-haller

In GitLab by @mhxion on Jun 24, 2024, 02:25

PR fixes #47.

In GitLab by @project_994_bot_1c5bd6ac1fdbd740fbc4ed080ecff58d on Jun 24, 2024, 02:43

added 1 commit

e796d48d - Rename class to remain consistent

Compare with previous version

In GitLab by @project_994_bot_1c5bd6ac1fdbd740fbc4ed080ecff58d on Jun 24, 2024, 02:56

added 1 commit

4cc7d67d - Add constant for panel name

Compare with previous version

approved this merge request

In GitLab by @mhxion on Jun 24, 2024, 13:10

approved this merge request

In GitLab by @mhxion on Jun 24, 2024, 13:10

I actually meant to merge and not approve it myself lol. Thanks for approving!

uhd-urz / elAPI