Card Stories - Plugin system - Webservice

=Description=

A cardstories plugin (foobar for instance) is a python file located in –plugins-dir (/usr/share/cardstories/plugins by default, hence /usr/share/cardstories/plugins/foobar/foobar.py) and its configuration files can be located in –plugins-confdir (/etc/cardstories/plugins by default, hence /etc/cardstories/plugins/foobar) and it could store information in –plugins-libdir (/var/lib/cardstories/plugins by default, hence /var/lib/cardstories/plugin/foobar).

The list of plugins to be activated would is given to the –plugins argument as a white space separated list of plugin names.

=Infrastructure=

Each plugin must provide a single class named Plugin that is instantiated with a single parameter : an instance of CardstoriesService. It may register when it loads and listen to game events and/or transform the incoming HTTP requests or the outgoing JSON result.

The name method must return a string that is the name of the plugin that can be used in the –plugins-pre-process and –plugin-post-process options (see below).

Configuration paths are available in the services.settings map as follows:

=Listening to the service=

A plugin can register to listen to all events occuring on the cardstories service as follows:

The accept function should act depending on the event, as shown above. When it is done it must register again to be notified of the next event.

=HTTP request filtering=

The plugins listed in the –plugins-pre-process option will be called, in that order, with the incoming HTTP request. For instance if –plugin-pre-process NAME is given to cardstories, the preprocess method of the Plugin instance will be called.

The example preprocess function adds a new data member to the Request object. It must return the result argument untouched.

The plugins listed in the –plugins-post-process option will be called, in that order, with the resulting JSON request. For instance if –plugin-post-process NAME is given to cardstories, the postprocess method of the Plugin instance will be called.

The example postprocess function adds a entry to the map that will be converted into a JSON object before being sent back to the HTTP client. It must return a map with the entry error set in case an error must be notified to the client.

The plugin names listed in the –plugin-post-process and –plugin-pre-process options are those returned by the name functions of the corresponding Plugin instance. Although it is best to name the plugin file with the same name as the one returned by the name function to avoid confusion, it is not mandatory.

=Plugin intercept=

A plugin may delete the action argument from a request in order to transparently bypass the handling of the request. It is used by solo mode to implement the action=solo command and prevent the regular handler from doing anything. The handler did not return the result of the callback but the arguments of the incoming request. When asking for a solo game the user was sent back to the lobby instead of being presented with the first step of the game.

An additional argument containing the result of the previous callbacks is given to the handle function to enable it to transparently return it.