Rustdoc crate je webové rozhraní na /rustdoc deklarované objevením z crate, přítomné v topologii, jeho odevzdané projekci i na domovské stránce, ať už jeho producent běžel, nebo ne, a běžící server odpovídá na /rustdoc/ ze stromu, který producent zapsal

Co to znamená

Reference rustdoc, kterou crate vykresluje, je jedním z povrchů, které tento repozitář poskytuje, s id rustdoc a připojením /rustdoc. Je v topologii od chvíle, kdy je crate: majordomus web list ji jmenuje, domovská stránka běžícího serveru ji nabízí a commitnutá projekce docs/generated/web.json ji nese, ať už v tomto checkoutu někdo stránky vytvořil, nebo ne. Běžící majordomus serve odpovídá na /rustdoc/ ze stromu, který zapsal producent, a když strom ještě není, odpoví 503 jmenujícím příkaz, který ho zapíše, místo nevysvětleného 404.

Princip

web::discover deklaruje povrch z crate, stejně jako deklaruje obsluhovanou dokumentaci z site/config.toml: deklarace závisí na existenci crate, ne na tom, že proběhl build. Průchod generovaným webovým kořenem přeskakuje adresář rustdoc ze stejného důvodu, z jakého přeskakuje docs — zjišťování už povrch zná — a čte jen revizi, kterou tam producent zaznamenal. Ta revize, built_from, je z commitnuté projekce vynechána, protože hodnota lišící se mezi checkouty by způsobila, že by každý klon hlásil projekci jako driftovanou.

Producent scripts/rust-check --doc zapisuje target/web/rustdoc/ s surface.json v web-surface/v1 a úvodní stránkou. Servírování jde přes web::files, hlídaný statický server, který už servíruje /docs/: každý segment cesty požadavku se zkontroluje dřív, než se dotkne souborového systému, a vyřešený soubor musí zůstat uvnitř kanonického kořene.

Jak to vidět

majordomus web explain rustdoc                          # mount, producer, availability, built_from
jq '.surfaces[] | select(.id == "rustdoc")' docs/generated/web.json
scripts/rust-check --doc && majordomus serve            # then /rustdoc/ on the URL it logs
bash test/run.sh 488_rustdoc_discoverable
cargo test --manifest-path apps/majordomus-cli/Cargo.toml web::discover
cargo test --manifest-path apps/majordomus-cli/Cargo.toml --test http_serve

Co nepokrývá

Zda je strom, který servíruje, úplný nebo aktuální, je rustdoc-complete a rustdoc-verified-live; toto tvrzení je o tom, že povrch existuje a je dosažitelný. Co nese publikovaný web, je rustdoc-composed-from-the-topology a rustdoc-published. Samotný mount — proč /rustdoc a ne cesta pod /docs nebo /api — je rozhodnutí zaznamenané v ADR 0086, ne něco, co by případ mohl prokázat jako správné.

Proč existuje

Po celou dobu existence crate jeho kontrola tuto referenci při každém běhu vykreslila a nic ji nedeklarovalo: router ji nemohl obsloužit, domovská stránka na ni nemohla odkázat a topologie, z níž se web staví, ji nepojmenovávala. Povrch, který existuje, jen když producent náhodou běžel v jednom checkoutu, je povrch, na který se nikdo nemůže spolehnout, takže deklarace se bere ze samotného crate. test/cases/488_rustdoc_discoverable.sh se ptá topologie dřív, než producent běžel, a obsluhovaného socketu poté.