proposal: additions to the plugin system

[thewilli]

I have some requirements the current plugin system does not fulfill. Would you accept the following changes / additions (as a PR :wink:)?

Settings

The plugin-name.meta file allows to set parameter descriptions. I want to introduce another optional possibility: Defining type.<PARAMETER_NAME> and setting it to string value of either string (default), bool or number will lead to a rendered text field, checkbox or number input field in the plugin administration, and save the values with the corresponding type in the configuration when changed.

Might break plugin administration of external themes.

Might get extended by additional types (e.g. enums rendering to radio button list).

New Hooks

• activated: the plugin is now activated (was deactivated before). not triggered for default plugin(s) upon setup, only for manual activation.
• deactivated: the plugin is now deactivated (was activated before), do e.g. some cleanup
• cronjob: cronjob handler, see API addition below

REST API addition

I want to introduce a new endpoint, GET /cronjob. All it does is to trigger the cronjob hook (see above) of all supported and activated plugins. I need this for plugins to e.g. check the status of a link (is the page still available? has it changed?) and cleanup of e.g. cancelled or timeouted uploads. Currently I see now way to trigger the plugins regularly to do these kinds of lookups or cleanups.

The interval of cronjob invocation would be up to the user, and cronjoob hook would get the date and time of the last run in order to do some timing. Finally Shaarli itself could use this handler to do some (optional) cleanup as well.

[ArthurHoaro]

Settings

This is a good idea. Implementing lists for either select or radio buttons would be nice too.

Hooks

activated and deactivated hooks are interesting, however they would only work with user actions through the UI, and not with a config file manual edit. I don't see any easy way around that though.

It means that plugins shouldn't rely too much on them to be usable, especially official ones. For example, to deploy my Shaarli's instance through Docker, I use a custom configuration file to enable a few plugins, changing the theme, etc.

A way around activated hook is to check if everything is in order using the init hook, and initialize the plugins settings (or anything) otherwise.

Cronjob

OK for me. Make sure that the hook can be manually triggered for logged in users, not only using the REST API.

Also note that API documentation is hosted in this repo: https://github.com/shaarli/api-documentation

EDIT: Actually, a POST endpoint with a free body in the request would be better IMHO.

[thewilli]

EDIT: Actually, a POST endpoint with a free body in the request would be better IMHO.

you are absolutely right, especially as GET requests should be idempotent. As much as I try to stick to this, many triggers (free online services, tools, ...) only support GET requests so I would prefer to maximize compatibility here.

[thewilli]

A way around activated hook is to check if everything is in order using the init hook, and initialize the plugins settings (or anything) otherwise.

that's right, but it would also add additional overhead to each request. Not sure what's the best solution here. Maybe this hook should just be dropped, as the deactivated hook is much more important imo.

[thewilli]

@ArthurHoaro I was working on my draft of this and came up with another addition addition: What do you think of an optional url entry in the plugin-name.meta file, which can point to e.g. a Github repo or another web page with instructions and an issue tracker?

If a plugin has an url set, I would add a link to the plugin name in the administration page, so it would look like

[ArthurHoaro]

Good idea!

[agentcobra]

Hi, is it possible to have an updater system ?

[nodiscc]

is it possible to have an updater system ?

Hi, you mean a self-updater? I am not favorable to this. The application should not write its own files. The upgrade process is straightforward if you use pre-packaged releases (just backup data, drop files, restore data) or Docker images (just change a variable and issue a command).

I admit the documentation could be made more concise and do not go into so much detail right away.

The application should not write its own files. The recommended file permissions explicitly enforce this. There is so much that can go wrong during a self-upgrade process. Changing the application code should be left to a separate administrative context.

[agentcobra]

Only for plugins

[ArthurHoaro]

Even though it can look convenient, we definitely won't be pulling some random third party files on Shaarli instances.