Witryna kshana.dev

web/ to drzewo, które GitHub Pages serwuje jako https://kshana.dev: strony (index.html, missions.html, capabilities.html, evidence.html, developers.html, editions.html), dokumentacja w docs/ oraz Kshana Studio w studio/ (serwowane pod https://kshana.dev/studio/), aplikacja uruchamiająca silnik w przeglądarce jako WebAssembly (WASM), bez obliczeń po stronie serwera i bez niczego przesyłanego. Studio ma dwa widoki jednego silnika: widok Prosty (studio/index.html, odpowiedź najpierw, zwykłymi słowami) i widok Zaawansowany (studio/advanced/index.html, pełny panel), który dzieli z widokiem Prostym silnik, worker, moduły i dane przez <base href="../">.

Od 0.35.0 Studio ma cztery dodatkowe widoki, każdy jako osobna strona z <base href="../">, bez indeksowania przez wyszukiwarki i z folderem syntetycznych próbek, które czyta jego test:

studio/trust/: morski widok zaufania, wskaźnik zaufania do odbiornika dla strumienia pozycji statku, z torem demonstracyjnym w trust/demo/.
studio/training/: omówienie szkolenia załogi, odtwarzające syntetyczne NMEA ze zdarzeniem zagłuszania, odciągnięcia, spoofingu czasu lub powtórzenia (training/demo/).
studio/interference/: mapa zakłóceń i narażenie trasy (interference/demo/).
studio/tools/: jedna strona kart narzędzi z przykładami (tools/examples/, tools/samples/), w tym podpisane pakiety dowodowe (#evidence), eksport bench (#bench), mapowanie compliance (#compliance), weryfikacja Galileo OSNMA (#osnma) i kanały asystenta AI (#ai).

Skąd pochodzą pliki#

Znajdują się tu trzy rodzaje plików i zmienia się je na trzy różne sposoby.

Pliki przeniesione. Strony, docs/, css/, js/, assets/, dane witryny w data/ (land.json, search.json, series.json) i wszystko w studio/ są zapisywane przez web/tools/port_site.py z kompilacji witryny i ze źródła Studio. PORT-MANIFEST.json wymienia każdy z nich wraz z sumą kontrolną SHA-256 (Secure Hash Algorithm, 256-bitowy). Nie edytuj ich tutaj: site.test.mjs kończy się niepowodzeniem przy ręcznej edycji. Zmień źródło i uruchom przeniesienie ponownie:
```
python3 web/tools/port_site.py --site <built site folder> --studio <Studio folder>
python3 web/tools/port_site.py --site <built site folder> --studio <Studio folder> --check
```
Przeniesienie jest deterministyczne: drugie uruchomienie niczego nie zapisuje, a --check kończy się kodem 1, jeśli web/ nie jest tym, co zapisałoby przeniesienie. Przenosi bez zmian pliki dla robotów z kompilacji witryny (znaczniki canonical, karty społecznościowej i schema.org każdej strony, robots.txt, sitemap.xml, llms.txt, llms-full.txt), sprawdza je, zapisuje legacy-redirects.js, 404.html i stronę przekierowującą pod dawnym adresem Studio (playground/index.html, do /studio/) oraz kieruje każdą stronę do lokalnych czcionek i bibliotek skryptów (poniżej).
Pliki będące własnością web/. To samodzielne źródła, których przeniesienie nigdy nie dotyka:
- capabilities.json jest ustrukturyzowanym źródłem kart możliwości i siatki standardów. Edytuj je, a nie HTML.
- data/verification-matrix.json jest generowany (cargo run --bin gen_validation_artifacts) i przypięty przez tests/verification_artifacts_doc_sync.rs; nie edytuj go ręcznie. data/card-matrix-map.json, data/oracle-references.json i data/standards-matrix-map.json to ręcznie utrzymywane odwzorowania, które ten sam test sprawdza względem wygenerowanej macierzy. Kopie Studio w studio/data/ są tymi plikami, bajt w bajt.
- og-card.svg, og-card.png i og-card.rendered-from.json to karta społecznościowa (python3 tools/gen_og_card.py).
- CNAME, .well-known/security.txt, favicon.svg.
- fonts/ i vendor/: pliki czcionek i biblioteka skryptów używane przez strony, pobrane jednorazowo przez tools/fetch_third_party.py i zatwierdzone (zob. „Brak żądań do osób trzecich”).
- build.sh, smoke.mjs, site.test.mjs, legacy-urls.test.mjs i tools/.
Wyniki kompilacji, ignorowane przez git i tworzone przez build.sh: pkg/ (pakiet wasm-pack, z którego budowany jest także pakiet npm), studio/pkg/ (ten sam pakiet tam, gdzie Studio go importuje) oraz scenarios/ (każdy scenariusz referencyjny, pod adresem, z którego serwowała je wcześniejsza witryna jednostronicowa).

Kompilacja i lokalne serwowanie#

./web/build.sh                     # compiles the WASM module and stages it for the Studio
python3 -m http.server -d web 8000 # serve over HTTP (required for WASM)
# open http://localhost:8000/

Bez narzędzi WASM KSHANA_WASM_PKG=<a built pkg folder> ./web/build.sh przygotowuje istniejący pakiet zamiast kompilować nowy. Przepływ Pages nigdy tego nie używa.

Testy#

node web/smoke.mjs                 # the WASM bindings (needs web/pkg)
node web/site.test.mjs             # the ported tree: manifest, version, counts, links, inline JSON
node web/tools/inline-json.test.mjs  # the guard for corrupt inline page data (an unescaped version bump)
node web/legacy-urls.test.mjs      # every old kshana.dev address still resolves
for f in web/studio/lib/*.test.mjs; do node "$f"; done   # the Studio's modules

Każdy moduł w studio/lib/ to czysta logika z odpowiadającym *.test.mjs; sterowniki DOM (Document Object Model, drzewo elementów strony) Studio to studio/app.js (widok Prosty) i studio/advanced.js (widok Zaawansowany). Ciągła integracja uruchamia każdy z nich jako osobny krok i kończy się niepowodzeniem, jeśli plik testowy w web/ nie ma kroku.

Brak żądań do osób trzecich#

kshana.dev serwuje własne czcionki, style i skrypty. Strona nie wysyła żądań do hosta czcionek ani hosta skryptów, więc adres odwiedzającego nie jest nikomu przekazywany.

Witryna i Studio są pisane z myślą o Google Fonts i hoście skryptów. Przeniesienie zastępuje link Google Fonts każdej strony odpowiednim arkuszem stylów w fonts/ (te same reguły @font-face i te same pliki czcionek, każdy podzbiór, więc tekst wyświetla się jak dawniej), a każdy adres hosta skryptów plikiem w vendor/. fonts/FONTS.json i vendor/VENDOR.json rejestrują, skąd pochodzi każdy plik, i jego sumę kontrolną; czcionki są na licencji SIL Open Font License (fonts/OFL-*.txt), a three.js na licencji MIT (vendor/three@…/LICENSE).

tools/fetch_third_party.py --from <site folder> --from <Studio folder> to jedyny krok korzystający z sieci. Uruchom go ponownie tylko wtedy, gdy strona prosi o zestaw czcionek lub wersję biblioteki, których tu nie ma: przeniesienie odmawia i mówi o tym. site.test.mjs kończy się niepowodzeniem, jeśli jakakolwiek przeniesiona strona, arkusz stylów lub skrypt wskazuje host czcionek albo ładuje cokolwiek z innego hosta.

Strona 404#

GitHub Pages odpowiada na brakujący adres stroną /404.html i statusem 404. Przeniesienie tworzy tę stronę z własnej powłoki strony głównej (nawigacja, stopka, wyszukiwanie) wokół krótkiego komunikatu z linkami do Strony głównej, Dokumentacji i Studio. Każdy adres w niej jest zapisany od korzenia witryny, ponieważ strona jest serwowana na dowolnej głębokości.

Dawne adresy#

Do v0.28.0 witryna była jedną stroną, a wszystko mieściło się za fragmentem w / (/#playground, /#ledger, linki udostępniania jako /#s=…, osadzenia jako /?embed=1&…; dawna nazwa karty w linku osadzenia, na przykład tab=fom, otwiera kartę Studio, która ją zastąpiła). tools/legacy-urls.json wymienia każdy taki adres używany przez opublikowane materiały i miejsce, w które teraz prowadzi; strona główna ładuje legacy-redirects.js, wygenerowany z tej listy, aby tam kierować. Dodaj przypadek do listy przed wycofaniem jakiegokolwiek adresu.

Wdrożenie#

Przepływ GitHub Actions pages wdraża znacznik wydania, a nie main: release.yml uruchamia go po opublikowaniu wydania, a ręczne uruchomienie ponownie wdraża wskazany znacznik. Uruchamia build.sh, przygotowuje web/ bez testów, skryptu kompilacji, tools/, manifestu i tego pliku oraz publikuje wynik w GitHub Pages.