Description

SPPAS does what it was written to do, and a plugin is how it does something else. A plugin is a program somebody wrote outside SPPAS, declared by a file which says what it is called, what it is for, what it can be set with, and which command line runs it. SPPAS installs it, shows it, sets it, runs it on files, and puts what it produced back among the files of the person. It never looks inside it.

That is what makes plugins worth having, and it is also what makes them delicate. A plugin extends SPPAS without SPPAS being touched: a laboratory writes the tool its own work needs, and hands it over as an archive. But what is handed over is a program, it runs on the machine of whoever installs it, and nothing of SPPAS reads what it does before it does it.

This application is what stands between a person and those programs. It shows what is installed and what each one claims to do, it installs and removes them, it lets their options be set, it runs one of them on the files she chose, and it says what happened to each of those files. It runs nothing of its own, and it decides nothing of what a plugin does.

Two services answer for what this application does not: the files it runs a plugin on are provided by the provision of files, and the options of a plugin are shown and set by the service which serves options. What is left is the plugins themselves — which ones are there, what they are, and what one run of one of them did.

Defining the needs

Data dictionary

Three data, and they all belong to one run. What a plugin is, and which ones are installed, is held by the domain of the plugins and read from there.

• D1. A run — one plugin, the files it was given, and the moment it was started.
• D2. A result — what happened to one file of a run: whether the plugin ran on it, what the plugin said about it, and whether it failed.
• D3. A produced file — a file which appeared because a run happened. There may be several for one file, and there may be none.

sppasPluginParam and sppasPluginsManager are not among them. What a plugin declares of itself, where it stands, how it is installed and how it is started are established, read where they are written, and this document adds nothing to them.

Conceptual model of communication

Four actors border this application: a person, and three neighbouring domains it calls. It writes into none of the three.

Actors

• A1. The person — sees what is installed, installs and removes, sets a plugin, starts a run, follows it, and reads what happened to each of her files.
• A2. The domain of the plugins — holds what is installed, says what each plugin declares of itself, installs one from an archive, removes one, and starts one on a file.
• A3. The provision of files — gives the files a run works on, and makes what was produced reachable among the files of the person.
• A4. The service of the options — shows the options a plugin declares and gives back what was set on them.

Flows

• F1. A2 → app — the plugins which are installed, and what each of them declares of itself [012].
• F2. app → A1 — one line per plugin: its name, what it says of itself, its version [011], [012].
• F3. app → A1 — that a plugin cannot be run on this machine [031].
• F4. A1 → app — an archive to install [021].
• F5. app → A2 — the archive, to be installed.
• F6. A2 → app — the plugin which was installed, or what stood in the way.
• F7. A1 → app — the plugin to remove [022].
• F8. app → A2 — the plugin to remove, and what came of it.
• F9. app → A4 — the options a plugin declares, to be set.
• F10. A4 → app — those options, with the values which were set [202].
• F11. A3 → app — the files the run is to work on [101].
• F12. app → A1 — how many files the run will work on [103].
• F13. A1 → app — start the run [301].
• F14. app → A2 — a plugin to start, on one file, with the values which were set [302].
• F15. A2 → app — what the plugin said about that file, and whether it failed.
• F16. app → A1 — which file is being treated, and how many remain [303].
• F17. app → A1 — one result per file: what was done, what was produced, what went wrong [401], [402], [403].
• F18. app → A3 — the files which were produced, to be made known [501].

Nothing goes from this application to a plugin but a file and the values which were set. What a plugin does with them is its own, and what it says comes back as it said it: this application relays and does not interpret.

F11 and F18 are the same neighbour at the two ends of a run. The files a plugin works on and the files it produced are both the person's, and both are known by the domain which knows her files. This application holds neither.

Conceptual model of data

Four classes. The plugin is one of them without being modelled: it belongs to the domain of the plugins, and it appears here with its identifier and no property.

The classes of entities

The relations

R2 and R3 are aggregations: a result exists only inside the run it belongs to, and a produced file only inside the result it came of. A run which has no result has not started, and a result with no produced file is a file the plugin read and did not write for.

R1 reads (1,1) on the side of the run: a run is one plugin and never two. Running two plugins on one set of files is two runs, each with its own results, and there is no moment at which they are one thing.

The values set belong to the run and not to the plugin. They are what the options held when the run started: a plugin set differently an hour later does not change what a run did, and a result read a week afterwards is read beside the values it was obtained with.

Computed, and never held

• How many files a run will work on, and how many remain, which are read from the files it was given.
• That a plugin cannot be run on this machine, which is read from what that plugin declares.
• Whether a run is over, which is one result per file of it.

What is not modelled, and why

• What a plugin declares of itself, where it stands, and how it is started: the domain of the plugins', and read from there.
• The files a run works on, which are the provision of files'. This application holds their identity for the time of the run, and nothing else.
• The options of a plugin, which the service of the options shows and sets. What is held here is the values, and only as they stood when a run started.
• What a plugin does, and what it means: nothing of it is knowable here.

Conceptual model of treatments

Seven treatments. Six answer a person who asked; the seventh answers the one before it.

The events

Organisational model of treatments

One procedure per treatment, numbered as it is. There are two tables, and the reason is [025]: where SPPAS answers from a server, two procedures have nothing to do at all.

Where SPPAS runs on the machine of the person

Where SPPAS answers from a server

PF2 and PF3 have nothing to do, and the two empty rows are the whole difference. What is offered on a server is what whoever runs that server installed, and a person who reaches SPPAS from a browser is not that one. The five other procedures are the same word for word: a run is a run, and what it says of itself does not depend on the machine it happens on. RO1

Several persons are on a server at once, and each has her own run. What a person may start is one run, which is RO7; what the machine can carry at one time is another question and another answer, and it belongs to whoever runs that machine. The two are not the same limit and are not written as one. RO8

How a run which lasts is followed

A run is started once and lasts as long as the files require. On her machine, what follows it is the interface itself, which is there for the whole run. On a server, nothing is: the request which started the run cannot hold the answer for minutes, and nothing of what happens reaches a page which is not asking.

A run is therefore started by one request and followed by others which ask where it stands. It is what the dashboard of swapp already does to know whether the interface it watches is alive. The consequence is stated plainly: a run outlives the request which started it, and it is the one thing this application holds between two requests. RO2

What those later requests obtain is what F16 and F17 carry: the file being treated, how many remain, and the results of the files which are done. A run which is over answers that it is over, and answers it as long as the person is reading it.

Rules of organisation

• RO1 — Installing and removing a plugin happen where SPPAS runs on the machine of the person, and nowhere else [025].
• RO2 — A run outlives the request which started it. It is advanced by a thread of the process which runs SPPAS, and it is the one thing this application holds between two requests. It lasts as long as that process and no longer.
• RO3 — What a plugin said is relayed as it was said. This application does not shorten it, does not translate it, and reads nothing into it.
• RO4 — The files a run works on and the files it produced are the provision of files', at both ends. This application holds their identity for the time of the run.
• RO5 — The options of a plugin are set before a run and read once, when that run starts. A plugin set during a run is set for the next one.
• RO6 — The options are shown in a container this application places in its own page. Setting a plugin is not leaving the list of plugins.
• RO7 — One run at a time for one person. A second run started while one is happening is refused, and the refusal says which run is still going.
• RO8 — Where SPPAS runs on the machine of the person, one run at a time is one run on that machine. Where it answers from a server, several persons run at once, and what bounds the number of runs the machine takes at one time is the business of whoever runs it.

RO7 is not a limit of the machine: a plugin which writes and a plugin which reads the same files at the same moment would leave results nobody can read, and the person could not tell which run produced what.

The tables

Each class of entities becomes a table, and its identifier becomes its key. There are five and not four: one property of the run holds several things, and a property which holds several things is not a column.

VALUE is what the conceptual model wrote as one property of the run. A run is started with the values of every option the plugin declares, which is as many values as there are options: they become a table of their own, keyed by the run and by the option. Written as a column, they would be one string nobody can read back option by option.

R2 and R3 are aggregations: the aggregated table takes the key of the aggregating one. A result is named by the run it belongs to and the file it is about, and those two together identify it: one file of one run has one result. A produced file is named inside the result it came of.

R1 has its low cardinality on the side of the run, which is (1,1): the table takes the key of the plugin, and it is never empty. A run without a plugin is not a run.

PLUGIN is a key and nothing else. The table exists so that a run may name what it started; what a plugin is made of is written in the domain which holds it.

Computed, and never held

• How many files of a run remain, which is what it was given against the results it holds.
• That a run is over, which is one result for every file it was given.
• That a plugin cannot be started on this machine, which is read from what that plugin declares.

Where each table stands

Here the machines are named, and not before. One table stands in a neighbouring domain; the four others stand in the process which runs SPPAS, held by what advances the run.

A run stands in the process, and it is advanced by a thread of it. This is what the setting up of SPPAS already does with the installation of its features: the model starts a thread, hands it something which holds where it stands, and answers later requests by reading that. A run of a plugin is the same thing with another long task, and there is no reason for this application to invent a second way.

Nothing is written on a disk, nothing is given a lifetime, and nothing sweeps anything: a run belongs to the process which holds it and goes when that process goes. A server which is restarted has no runs, and the person is told that the one she was following is not there any more.

The thread is a daemon: it does not hold the application alive, and killing the application kills it. What a plugin had already produced for the files which were done stays where the plugin wrote it, and is the person's.

Operational model of treatments

The organisational level said by what and when; this says in what tasks, and what among them cannot be half done.

The result of one file is the unit, and the run is not

A result is written with the files which came of it, or neither is. Between two results, nothing is owed: a run holds the files which are done and says nothing of the others, which is exactly what a person reading it has to be told.

A run which stops is not repaired. A plugin which never returns, a thread which died, an application which was killed: the run holds the results it had, and no more come. What was produced for the files which were done is the person's and stays hers.

What tells a run which stopped from a run which is slow is the thread itself. A run whose thread is no longer alive and which holds fewer results than it was given files has stopped, and says so. Nothing else is needed, and nothing else is written: the same question is asked the same way where the features of SPPAS are installed.

Two runs at once

RO7 says one run at a time for one person, and the operational level says what holds it: a run is made before the first file is started, and a request which would start a second one finds the first still alive and is refused. It is what the installation of the features answers to the same question, in the same words.

Where the code goes

In sppas/ui/swapp/app_plugins/, cut as every application of swapp is cut: one module for the model, one for the view, one for what dispatches, one for what answers the URL, and one module per part of the page.

What each one promises, which is the reason for the cutting:

• The model is the only one which calls the domain of the plugins and the two services, so it is the only one to be read again the day one of them changes. It reads nothing of what a plugin says beyond relaying it, and it is the only one which knows that a run is a thread.
• The view decides nothing, and shows what a plugin said as that plugin said it.
• What dispatches holds nothing between two requests: what has to survive is what the page carries.
• The parts of the page know the page and nothing else. None of them reads a file, a thread or a declaration.

No module here knows what a plugin does. There is nowhere for that knowledge to be held, and the first chapter says why there could not be.

Implementation model: MVC

The model holds the plugins, the run which is going and what came of it, and exposes neither the domain of the plugins nor the two services to the rest of the application. The controller is called once per request, reads the task it carries, and holds nothing afterwards. The view renders and collects, and takes no decision. Three components, three class diagrams.

The classes of the model

/ marks what is derived and held by nobody. What the operations promise is the chapter on the contracts.

One class, and the class of the core under it. What is installed, what each plugin declares, putting one in and taking one out, and starting one on files: sppasPluginsManager holds all of it, and a plugin is an sppasPluginParam. A class of this application holding any of that under another name would be a second truth.

The run is started one file at a time. The domain of the plugins is given a plugin and a list of files, and gives back one text for the whole list. It is given one file at a time here, for the reason the operational model gives: the result of one file is the unit, and a run which stops has done what it did file by file. What appeared for a file is what the files of the person gained for it, which is how the interface which exists today finds it as well.

Nothing of the core carries the run. sppasPluginsManager descends from a thread but defines nothing of one and is never started as one: the thread which advances a run is this model's own, started as the setting up of SPPAS starts the installation of its features. Whether that thread is alive is what RO7 leans on — a second run started while one is going finds it alive and is refused — and it is also what tells a run which stopped from a run which is slow.

What is tied to what

In yUML

To be read at yuml.me, class diagram.

[PluginsModel|manager;thread;run|plugins();one();can_run_here();install();remove();files_for();options_of();values_set();start();is_running();the_run()]++1-0..1>[PluginRun|run;plugin;moment;values;files;/remaining;/over|add();remaining();is_over();serialize();parse()]
[PluginRun]++1-0..*>[FileResult|file;done;what was said;produced]

[PluginsModel]-.->[sppasPluginsManager]

The classes of the view

The parts of the page are those of the interface which exists today, and they bear its names: the plugins one under another, one plugin with what it says of itself, and what a run gave.

Putting a plugin in and taking one out are not on a plugin: they are not what one does to a plugin but what one does to the list, and they stand in the menu of the page. Where SPPAS answers from a server, they are not there at all. RO1

What is tied to what

In yUML

[PluginsView|populate_tree_content()]++1-1>[PluginsList]
[PluginsView]++1-1>[PluginRunPanel]
[PluginsList]++1-0..*>[PluginDescription]

[PluginsView]-.->[PluginsRecord]

The classes of the controller

What is tied to what

In yUML

[PluginsResponseRecipe|bake();_process_events()]++1-1>[PluginsController|record|handle();populate_view()]
[PluginsResponseRecipe]++1-1>[PluginsView]
[PluginsController]++1-1>[PluginsRecord|task;plugin;run;to_be_shown|serialize();parse()]

[PluginsController]-.->[PluginsModel]
[PluginsController]-.->[PluginsView]

The states

Running and stopped hold the same data, and what tells them apart is not in the data: it is whether the thread which advances the run is alive. A run is in one of the three and never in two.

The sequence, from the page to the produced files

1. The page is asked for. What is installed is read, and one card is built per plugin; a plugin which cannot be started here says so.
2. The person opens what a plugin says of itself at length, and closes it. Nothing else happens.
3. She sets the plugin: its options are handed to the service which shows them, and what was set comes back.
4. She asks to run it. The files she chose are read from the provision of files, and she is told how many there are.
5. She starts the run. The run is written with its moment and its values, before the first file is started.
6. The plugin is started on the first file; what it said is written as the result of that file, with the files which appeared.
7. Her page asks where the run stands, and is answered: this file, so many remaining, and the results already written.
8. Steps 6 and 7 happen again, at their own pace, until every file has a result.
9. What was produced is given to the provision of files, and is found among her own files.

Steps 1 to 4 happen in any order and any number of times. Step 5 happens once per run, and refuses while a run of that person is still going. RO7

The error policy

What is raised is caught by whatever answers a request, and by nothing below it. What a plugin writes on its own error output is not an error of this application: it is what that plugin said, and it is shown as such.

How to read them

pre is what has to be true on the way in, and what the operation does not check; post is what the caller can count on without looking.

What holds everywhere

• Only PluginsModel speaks to the domain of the plugins and to the two services. No other class of this application knows that either exists.
• What a plugin said is relayed as it was said: never shortened, never translated, and never read for a meaning. RO3
• Nothing of a run is written on a disk. A run belongs to the process which holds it and goes with it.
• What is absent gives back an empty thing — no plugin, no result, no produced file — and never nothing at all.
• What is raised is caught by whatever answers a request, and no class below it writes a catch.

Class by class

The run is advanced by a thread which is a daemon: it holds nothing alive, and an application which is killed kills it. A run whose thread is gone and which holds fewer results than files has stopped, and says so rather than being repaired.

Where each requirement is held

[203] is the only requirement held nowhere in this application, and it is written down so that nobody looks for it here.

Without a plugin, and without a run

A run started here starts a program, so what can be tested without starting one is tested without starting one. These need a plugin which is installed and nothing else.

Installing, removing and starting a plugin are the business of the domain of the plugins, and are tested there. What is checked here is what this application does with what that domain answered: TE4 to TE6 assert on the plugins which are given and on what is named, and never on what was unzipped or deleted.

With a run which really happens

These need a plugin to start, and the plugin they start is written for the tests: one which writes a file, one which fails, one which says nothing, one which takes its time. What is tested is this application, never a plugin of the person.

TE17 is the one which needs a thread to die. It is written because a run which stopped and a run which is slow hold the same data, and because the only thing which tells them apart is outside the data.

What no test covers, and where they stand

• What a plugin does. It is a program written elsewhere; this application is answerable for what it started it on and for what it said of it.
• [203] — finding the values of a former run. It is held nowhere in this application.
• The two services, which have their own dossiers and their own tests. What is checked here is the tie: which files were asked for, and which files were given back.
• The WCAG rules, which are verified on the page and not on a fragment of it.

The tests stand where the project puts its own, in tests/swapp/. Nine of the nineteen need no run at all.