Co to znamená
/docs je vlastní dokumentace tohoto repozitáře — web v Zole, servírovaný běžícím executable ze stejného zdroje, který se publikuje na GitHub Pages. /swagger je Swagger UI. /openapi.json je dokument, který čte prohlížeč, odvozený z registru schopností. / je úvodní stránka. Každý z těchto názvů patří právě jednomu producentovi a změna, která jeden z nich dá něčemu jinému, se odmítne, ne sloučí.
Nesestavená dokumentace odpovídá 503 jmenujícím příkaz, který ji sestaví, ne prohlížečem, který na té cestě dřív odpovídal, ani obecným selháním. Povrch, který není sestaven, zůstává ve strojově čitelné odpovědi se svým stavem, protože skrytí trasy před těmi, kdo ji udržují, ji neskryje před nikým jiným; úvodní stránka ji vykreslí jako nedostupnou a nenabízí odkaz na jisté 404.
Princip
Připojení jsou data dříve, než jsou trasy. web::discover řeší /swagger z http::swagger::SWAGGER_PATH a /docs ze sestavení dokumentace v konfiguraci webu a docs/generated/web.json nese mapu reserved od role k cestě, kterou generovaná dokumentace vykresluje přímo — takže publikovaná rezervace a vynucená jsou táž hodnota, ne dvě tvrzení, která se shodou okolností shodují. web::validate odmítne duplicitní připojení v rámci jednoho světa a vnořený nárok, který vnější povrch nedeklaroval, a http::surfaces odmítá při sestavení routeru, ne až za běhu požadavku.
Obsluha /docs je web::files, což není obecný souborový server: cesta požadavku se rozdělí na segmenty, každý segment se zkontroluje dřív, než se sáhne na souborový systém, ., .. a prázdné segmenty se odmítnou, rozlišená cesta se kanonizuje a musí zůstat uvnitř kanonického kořene — což zavírá dveře, které by jinak otevřel symlink uvnitř adresáře — a obsluhuje se jen povolená přípona. Nikde v tom není spojování nedůvěryhodného textu.
Ty dva mounty jsou také důvod, proč zdroj webu neuvádí žádný odkaz absolutní vůči originu. scripts/site-basepath-check takový odmítne, takže tentýž zdroj Zola sestaví pro origin Pages i pro mount /docs, aniž by kdekoli existovala druhá kopie dokumentace.
Jak to vidět
majordomus web list | grep -E 'swagger|docs' # /swagger and /docs, each with its producer
jq '.reserved' docs/generated/web.json
scripts/site-basepath-check # the source is base-path independent
bash test/run.sh 89_web_surface # the names, over a real socketCo nepokrývá
Z /docs na /swagger není žádné přesměrování. Zachování starého významu by zachovalo kolizi, což je věc, která se odstraňuje; čtenář, který přijde na /docs a čeká prohlížeč, dostane dokumentaci, což je to, co to slovo říká.
Rezervace se týká jmen, ne obsahu. Co obsahuje build dokumentace, je věc webu.
Proč existuje
Swagger UI drželo /docs, protože to slovo bylo při připojení volné a nic nezaznamenalo, co znamená. Když přišla dokumentace, chtěla název, který už jí byl přidělen, a nic v repozitáři nemohlo kolizi odmítnout ani si jí všimnout — připojení bylo konstantou v routeru a jeho význam žil jen v hlavách lidí, kteří ten router četli. Případ test/cases/89_web_surface.sh potvrzuje vlastnictví jako data a pak přes socket, včetně toho, že sestavené připojení dokumentace nespolkne /swagger ani /openapi.json pod ním.