Vstupní bod shellu je adaptér a dělá jedno volání

Co se změnilo ve verzi 2

Verze 1 vypisovala, co smí vstupní bod dělat, a seznam měl tvar, který nikdo nepojmenoval: každá položka byla voláním nástroje a čtyři položky místo jedné z nich dělalo jen to, že nástroj měl čtyři malé příkazy a žádný celkový. ADR 0043 mu ten celkový dalo — majordomus env enter, který exportuje, vykreslí banner, obnoví most workflow a zajistí runtime — a seznam se tím zhroutí na skutečný obsah: jedno volání, bootstrap příkazu, a nic kromě přidání adresáře do cesty a deklarace souboru ke sledování.

Je to zúžení, ne uvolnění. Vše, co zakazovala verze 1, je stále zakázáno, slovo od slova. Verze 2 přidává, že druhé volání nástroje je nyní také nález — protože dvě volání jsou dvě čtení repozitáře na horké cestě každého cd a protože ve chvíli, kdy vstupní soubor vybírá, který z několika příkazů spustit, začal o věcech rozhodovat, což je přesně selhání, o kterém toto pravidlo celé je.

Co toto jedno volání nyní dělá, se změnilo ve stejnou dobu a ta polovina patří project.entry-converges@2: vstup do repozitáře zvedne jeho runtime. Toto pravidlo o tom nic neříká. Říká, že to nedělá vstupní soubor — dělá to spustitelný soubor.

Zdůvodnění

.envrc je nejlákavější místo v repozitáři, kam vložit shellovou pipeline, a nejhorší. Běží při každém vstupu do adresáře, na každém stroji, v jakémkoli shellu, který někdo zrovna používá; nic ji netestuje; nikdo ji nerecenzuje; a každý fakt, který počítá, je fakt, který už něco jiného v repozitáři umí spočítat správně.

Selhání není hypotetické, je to běžný konečný stav. git rev-parse, aby ukázal větev. grep nad Cargo.toml pro verzi, která se pak rozchází s crate. find | wc -l pro spočítání pravidel, který počítá soubory, které se nenaparsují, a hlásí číslo, jaké by nehlásil žádný jiný povrch. curl, aby zjistil, zda server běží, který visí třicet sekund, když neběží. Každé přidal někdo rozumný, jeden řádek po druhém, a výsledkem je shellový program na horké cestě každého cd, který nepokrývá žádná kontrola a který říká věci, jež by nástroj vyvrátil.

Tytéž fakty už mají jeden kanonický typovaný zdroj — environment::RepositoryEnvironment — který vykresluje příkazová řádka, HTTP route, zdroj MCP, Cockpit i dokumentace. Shellový vstupní bod je jen dalším jeho konzumentem a jediné, co smí navíc, je vyhodnocovat přiřazení, protože to je jediná věc, kterou proces nemůže udělat svému rodičovskému shellu.

Cena záleží stejně jako správnost. Vstup do repozitáře člověk dělá desítkykrát denně a nikdy se nerozhodl na to čekat; a build spuštěný tam je build spuštěný v nejhorší možný okamžik.

Požadované chování

Soubor, který shell vyhodnotí při vstupu do repozitáře — .envrc nebo cokoli, co čte ekvivalentní nástroj — smí:

• přidat adresář do cesty (PATH);
• deklarují soubor ke sledování, aby se nástroj zeptal znovu, když se změní to, co ohlásil;
• provede právě jedno volání nástroje, tedy bootstrap příkazu (env enter), a eval to, co vypsal na standardní výstup;
• načíst strojově lokální soubor člověka, který repozitář nikdy nevidí ani nečte — místo pro jeho tajemství a přepisy, poslední, aby tamní hodnota vyhrála;
• přiřadit proměnné literál nebo hodnotu, kterou vytiskl jeden příkaz.

Nesmí:

• volat nástroj podruhé, ať je druhé volání k čemukoli: dvě volání jsou dvě čtení repozitáře při každém cd a volba mezi příkazy je rozhodnutí, které patří dovnitř spustitelného souboru, kde je typované, měřené a testované;
• spustí příkaz správy verzí nebo jakýkoli program, který zkoumá repozitář — git, grep, sed, awk, find, jq, wc, cat nad sledovaným souborem, cargo metadata;
• nic nesestavuje ani nevolá správce balíčků nebo překladač;
• samo sahat na síť, v jakékoli podobě, včetně požadavku HTTP přes loopback. Co jediné volání, které provádí, udělá s loopback adresou, kterou server tohoto checkoutu už zveřejnil, je věc spustitelného souboru a hranici tomu určuje project.entry-converges;
• nést počet, verzi, URL, jméno providera, branch nebo příkaz workflow jako literál, když to nástroj umí zjistit;
• nesou port, pid, timeout, dobu nečinnosti ani jiný parametr běhu: to jsou vlastní výchozí hodnoty bootstrap příkazu, deklarované jednou v deklaraci příkazové řádky a měněné tam.

Adaptér, který volá, najde program, aniž by jej sestavoval: checkout, který program ještě nesestavil, vypíše jeden řádek pojmenovávající recept, který jej sestaví, a skončí kódem 0, protože vstup do adresáře nesmí selhat.

Vše, co vstupní bod ukazuje, určí nástroj svým rychlým rozlišením, které nikdy nesestavuje index, nikdy nekontaktuje nic jiného než loopbackovou adresu, kterou publikoval běžící server, a to, co nedokázalo rozlišit, hlásí jako neznámé, ne jako výchozí hodnotu.

Chování při selhání

test/cases/100_environment.sh čte vstupní bod a selže, přičemž jmenuje řádek, když nese zakázaný příkaz, volá nástroj víc než jednou nebo překročí svůj rozpočet složitosti. Je to behaviorální případ, takže jej shell sada spouští při každé změně, která sadu vybírá, a vybírají jej třídy kontrol layer i shell.

Žádné vynucování za běhu neexistuje a ani by nemělo: soubor vyhodnocuje shell, který tento nástroj neovládá, a kontrola, která by tam běžela, by byla jednou věcí navíc na každém cd.

Ověření

test/cases/100_environment.sh drží vstupní bod do výše uvedeného seznamu, dokazuje, že nástroj volá právě jednou a že to volání je zaváděcí příkaz, dokazuje, že adaptér končí s 0 a říká, co spustit, když spustitelný soubor chybí, dokazuje, že exportovaný skript jsou jen přiřazení, a dokazuje, že kontrola umí selhat: zakázaný řádek vložený do jedné kopie a druhé volání nástroje vložené do jiné musí být oba odmítnuty toutéž čtečkou.

apps/majordomus-cli/tests/environment.rs dokazuje polovinu, na kterou vstupní bod deleguje: že rychlé rozlišení nestaví žádný index, že shell vyhodnotí exportovaný skript zpět na zadané hodnoty bez ohledu na to, co cesta repozitáře obsahuje, a že banner mlčí, když nikdo nesleduje.