Maskinoversettelse, ikke gjennomgått av en morsmålsbruker. Engelsk er referansen.

Kom i gangRediger på GitHubKilde: web/README.md

Nettstedet kshana.dev

web/ er treet GitHub Pages serverer som https://kshana.dev: sidene (index.html, missions.html, capabilities.html, evidence.html, developers.html, editions.html), dokumentasjonen under docs/ og Kshana Studio under studio/ (servert på https://kshana.dev/studio/), appen som kjører motoren i nettleseren som WebAssembly (WASM), uten beregning på tjenersiden og uten opplasting. Studio har to visninger av én motor: den enkle visningen (studio/index.html, svaret først i vanlige ord) og den avanserte visningen (studio/advanced/index.html, hele dashbordet), som deler motor, worker, moduler og data med den enkle visningen gjennom <base href="../">.

Siden 0.35.0 har Studio fire visninger til, hver sin egen side med <base href="../">, uten søkeindeksering og med en mappe med syntetiske eksempler som testen leser:

  • studio/trust/: den maritime tillitsvisningen, en tillitsscore for mottakeren til et fartøys posisjonsstrøm, med et demospor i trust/demo/.
  • studio/training/: mannskapets treningsdebrief, som spiller av syntetisk NMEA med en jamming-, drag-off-, tidsspoof- eller replay-hendelse (training/demo/).
  • studio/interference/: interferenskartet og ruteeksponeringen (interference/demo/).
  • studio/tools/: én side med verktøykort med eksempler (tools/examples/, tools/samples/), inkludert signerte bevispakker (#evidence), testbenk-eksporten (#bench), compliance-kobling (#compliance), Galileo OSNMA-verifisering (#osnma) og kanalene til AI-assistenten (#ai).

Hvor filene kommer fra#

Tre typer filer ligger her, og de endres på tre ulike måter.

  1. Portede filer. Sidene, docs/, css/, js/, assets/, nettstedsdataene i data/ (land.json, search.json, series.json) og alt under studio/ skrives av web/tools/port_site.py fra et nettstedsbygg og Studios kilde. PORT-MANIFEST.json lister hver eneste med SHA-256-kontrollsummen (Secure Hash Algorithm, 256 bit). Ikke rediger dem her: site.test.mjs feiler på en manuell endring. Endre kilden og kjør porten på nytt:

    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

    Porten er deterministisk: en ny kjøring skriver ingenting, og --check avslutter med 1 hvis web/ ikke er det porten ville skrevet. Den tar med seg nettstedsbyggets crawl-filer uendret (hver sides canonical-, sosialkort- og schema.org-tagger, robots.txt, sitemap.xml, llms.txt, llms-full.txt), kontrollerer dem, skriver legacy-redirects.js, 404.html og videresendingssiden på Studios gamle adresse (playground/index.html, til /studio/), og peker hver side til de lokale skriftene og skriptbibliotekene (nedenfor).

  2. Filer web/ eier. Dette er kilder i egen rett, og porten rører dem aldri:

    • capabilities.json er den strukturerte kilden til funksjonskortene og standardrutenettet. Rediger den, ikke HTML-en.
    • data/verification-matrix.json er generert (cargo run --bin gen_validation_artifacts) og festet av tests/verification_artifacts_doc_sync.rs; ikke rediger den for hånd. data/card-matrix-map.json, data/oracle-references.json og data/standards-matrix-map.json er manuelt vedlikeholdte koblinger som den samme testen kontrollerer mot den genererte matrisen. Studios kopier under studio/data/ er disse filene, byte for byte.
    • og-card.svg, og-card.png og og-card.rendered-from.json er det sosiale kortet (python3 tools/gen_og_card.py).
    • CNAME, .well-known/security.txt, favicon.svg.
    • fonts/ og vendor/: skriftfilene og skriptbiblioteket sidene bruker, hentet én gang av tools/fetch_third_party.py og sjekket inn (se «Ingen forespørsler til tredjeparter»).
    • build.sh, smoke.mjs, site.test.mjs, legacy-urls.test.mjs og tools/.

  3. Byggeresultater, git-ignorert og produsert av build.sh: pkg/ (wasm-pack-pakken, som npm-pakken også bygges fra), studio/pkg/ (den samme pakken der Studio importerer den) og scenarios/ (hvert referansescenario, på adressen det tidligere enkeltsidenettstedet serverte dem fra).

Bygg og server lokalt#

./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/

Uten WASM-verktøykjeden setter KSHANA_WASM_PKG=<a built pkg folder> ./web/build.sh opp en eksisterende pakke i stedet for å kompilere en. Pages-arbeidsflyten bruker aldri det.

Tester#

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

Hver modul i studio/lib/ er ren logikk med en tilhørende *.test.mjs; Studios DOM-drivere (Document Object Model, sidens elementtre) er studio/app.js (den enkle visningen) og studio/advanced.js (den avanserte visningen). Kontinuerlig integrasjon kjører hver av disse som et eget trinn og feiler hvis en testfil under web/ ikke har noe trinn.

Ingen forespørsler til tredjeparter#

kshana.dev serverer sine egne skrifter, stiler og skript. En side sender ingen forespørsel til en skriftvert eller en skriptvert, så besøkerens adresse blir ikke gitt videre til noen.

Nettstedet og Studio er skrevet mot Google Fonts og en skriptvert. Porten erstatter hver sides Google Fonts-lenke med det tilsvarende stilarket i fonts/ (de samme @font-face-reglene og de samme skriftfilene, alle delsett, slik at tekst gjengis som før) og hver skriptvertadresse med filen under vendor/. fonts/FONTS.json og vendor/VENDOR.json registrerer hvor hver fil kom fra og kontrollsummen; skriftene er under SIL Open Font License (fonts/OFL-*.txt) og three.js under MIT-lisensen (vendor/three@…/LICENSE).

tools/fetch_third_party.py --from <site folder> --from <Studio folder> er det eneste trinnet som bruker nettverket. Kjør det på nytt bare når en side ber om et skriftsett eller en bibliotekversjon som ikke er her: porten avviser og sier fra om det. site.test.mjs feiler hvis en portet side, et stilark eller et skript nevner en skriftvert eller laster noe fra en annen vert.

Siden 404#

GitHub Pages svarer på en manglende adresse med /404.html og status 404. Porten lager den siden av hjemmesidens eget skall (navigasjon, bunntekst, søk) rundt en kort melding med lenker til forsiden, dokumentasjonen og Studio. Hver adresse i den er skrevet fra nettstedsroten, fordi den serveres på hvilken som helst dybde.

Gamle adresser#

Fram til v0.28.0 var nettstedet én enkelt side, og alt lå bak et fragment på / (/#playground, /#ledger, delingslenker som /#s=…, innbygginger som /?embed=1&…; et gammelt fanenavn i en innbyggingslenke, for eksempel tab=fom, åpner Studio-fanen som erstattet det). tools/legacy-urls.json lister hver slik adresse som publisert materiale bruker og hvor den havner nå; hjemmesiden laster legacy-redirects.js, generert fra den listen, for å sende dem dit. Legg til et tilfelle i listen før en adresse tas ut av bruk.

Utrulling#

GitHub Actions-arbeidsflyten pages ruller ut en utgivelsesmerkelapp (release tag), ikke main: release.yml utløser den når en utgivelse er publisert, og en manuell utløsning ruller ut en navngitt merkelapp på nytt. Den kjører build.sh, setter opp web/ uten testene, byggeskriptet, tools/, manifestet og denne filen, og publiserer resultatet til GitHub Pages.