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
Objekt získáme, když zavoláme z  funkci. Řetězcová hodnota, kterou předáte metodě, bude názvem klíče, pod který bude váš Shellbox zaregistrován do pole. Obvykle k tomu rozšíření používají svůj vlastní název, pokud nepotřebují spouštěné příkazy izolovat do samostatných Shellboxů.

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. Ovšem ty budou dostupné jen v tom případě, že je bude vzdálený server také podporovat.

No a nakonec se nastaví název trasy (ovšem pozor, ve skutečnosti tohle přiřazení nic nedělá, protože je teprve ve fázi TODO – tedy jednou někdo možná k tomu nějakou funkcionalitu dodělá).

Obvykle si tvůrci rozšíření pomáhají statickou funkcí, s názvem, která vrací objekt   již nakonfigurovaný:



Sestavení příkazu
Parametry se předávají zavoláním metody. Ta automaticky celý řetězec upraví tak, aby se mohl předat přes URL. Pokud se tomu chcete vyhnout a předat řetězec pro vykonání příkazu tak jak je, použijte. Pomocná funkce, která ošetří problematické znaky předávaného řetězce tak, aby nedošlo během předání k nežádoucí dezinterpretaci, se totiž volá dřív než. A proměnné prostředí můžete předat jako pole, prostřednictvím metody.

Pokud chcete, aby sloučit standardní chybový výstup (stderr) se standardním výstupem (stdout), zavolejte metodu.

Většina příkazů pracuje se soubory, proto má pro práci s nimi Shellbox několik pomocných funkcí:


 * - Vytvoří ještě před spuštěním příkazu soubor pro jehož název použije obsah proměnné, do kterého pak nalije obsah proměnné
 * - Udělá totéž co, ovšem s tím rozdílem obsah souboru přelije ze souboru, identifikovaného řetězcovou hodnotou proměnné   (cesta k souboru)
 * - Pokud má mít příkaz nějaký výstup, můžete ho po vykonání příkazu uložit do souboru, který je ovšem pouze v RAM
 * - Udělá totéž co, až na to že obsah přeleje rovnou do souboru identifikovaného cestou
 * - Funguje podobně jako, ovšem s tím rozdílem, že to udělá pro všechny soubory, jejichž název vyhoví následujícímu filtru
 * - I v tomto případě to funguje jako u, až na to, že cílem souborů vyhovujících nastaveným parametrům bude adresář

A standardní vstup (stdin) můžete předat přes metodu



Použití skriptu
Je zcela běžné, že se výstup předává ke zpracování dalším příkazům přes rouru. Například Score nejprve použije abc2ly, který převede ABC značky do syntaxe LilyPondu, a teprve z tohoto výstupu vygeneruje pomocí lilypond, který akceptuje pouze syntaxi LilyPondu finální obrázek. Tradičně by se řešilo přes dvě volání metody Shell::command. Jedno pro abc2ly a druhé pro lilypond, s tím, že by se pak použil výstup z abc2ly. Ovšem to by vedlo ke zbytečné režii při použitíShellboxu na jiném serveru, protože obsah by se zbytečně posílat tam a zpět přes HTTP. Obejít se to dá tím, že se použije shellový skript, kterým si už sám, podle potřeby, bude volat další příkazy a případně průběžně zpracovávat jejich výstup.

Pokud chcete vidět nějaké ukázkové příklady, jak se to dělá, hoďte oko na adresář scripts/ v kódu rozšíření Score.



Zpracování výsledků
Zavoláním metody  získáte objekt. U něj můžete využít následující metody:


 * - pokud použijete metodu includeStderr, bude vracet null
 * - pokud bude přes  do pamětu uložen nějaký výstup, můžete jeho obsah pomocí této metody uložit do souboru
 * - ověřuje, zda byl tento soubor přijat
 * - pokud bude přes  do pamětu uložen nějaký výstup, můžete jeho obsah pomocí této metody uložit do souboru
 * - ověřuje, zda byl tento soubor přijat

Příklady

 * představuje pravděpodobně nejkomplexnější využití Shellboxu, včetně aplikace skriptu a filtrů při ukládání vygenerovaných souborů. Viz záplata která nahradila původní kód.
 * to má velice prosté. Viz záplata která nahradila původní kód.