Manual:BoxedCommand/cs

BoxedCommand je součástí knihovny, která umožňuje transparentně spouštět příkazy příkazové řádky (shellu) a to nejem lokálně (jak se běžně dělá), ale i na serverech, pokud také používají. Tahle stránka se zaobírá tím, jak lze pomocí této knihovny nahradit framework pro Shell, používaný od MediaWiki 1.30+.

A lightly edited and annotated example from :

Přehled
BoxedCommand používá oddělený sandbox, který se může spustit i na jiném serveru. Jde o dočasně vytvořený adresář, který neobsahuje žádné soubory, proto je potřeba data, s nimiž se bude pracovat, do příslušného souboru vložit pomocí funkce BoxedCommand. BoxedCommand se stará o to, aby vše fungovalo bez ohledu na to, jakou metodu pro vytvoření sandboxu administrátoři serverů nakonfigurovali.



Jak získáme BoxedCommand
získáme, když zavoláme funkci  z. The argument to  should be the name of the Shellbox configured in. Typically each extension will use its own name here, unless there is an advantage to further isolate commands from each other by using separate Shellboxes.

There are various additional hardening measures that can be set at this point such as enabling firejail's default seccomp filter or disabling network access. They will only be used if the sandboxing system supports them.

Finally, set a route name (TODO: this doesn't really do anything).

It is common for extensions to have a static function named  that returns a configured   object:

Constructing the command
Parameters can be passed by calling. These will be automatically escaped, raw parameters can be passed by using. The utility function  allows for escaping user-input before passing it to. Environment variables can be passed as an array to.

If you want stderr to be merged with stdout, call.

Many commands deal with files, so Shellbox makes it convenient to do so with the following helper functions:


 * - Creates a file with the name  with the contents   before execution
 * - Same as, but reads the contents from
 * - If it exists, save the file with name  into memory after execution
 * - Same as, except it saves the contents to
 * - Similar to, except it saves everything that matches the glob of
 * - Similar to, except all files are saved into the directory

Standard input can be passed by using.

Using a shell wrapper
It is common to run external commands in pipeline. For example, Score will run abc2ly to convert ABC markup to LilyPond and then generate images using lilypond from the LilyPond markup. Traditionally this would have been two Shell::command invocations, one for abc2ly, then another for lilypond using the output from abc2ly. However, this can cause unnecessary overhead when using a remote Shellbox server, since file contents need to be sent back and forth as HTTP requests unnecessarily. One practice is to use a shell script to run multiple commands, possibly interpreting the output.

Take a look at Score's scripts/ directory for examples on how this works.

Interpreting the result
Calling  will give you a   object. The following methods are useful:


 * - null if includeStderr was used
 * - if an output file was registered with, get that file's contents
 * - whether that file was received
 * - if an output file was registered with, get that file's contents
 * - whether that file was received

Examples

 * probably has the most complex uses of Shellbox's functionality, including using shell wrappers and output globbing. See the conversion patch.
 * has very simple uses. See the conversion patch.