En webtjeneste med flere ruter

En rute i Norscode er en helt vanlig funksjon. Det som gjør den til en rute, er at den registrerer seg selv med web.route. Kjøretiden finner alle slike funksjoner når tjenesten starter, og bygger rutetabellen av dem.

bruk std.web som web
bruk src.kjerne.noformat som nf

funksjon html(kropp: tekst) -> ordbok_tekst {
    returner web.response_builder(200, {"content-type": "text/html; charset=utf-8"}, kropp)
}

funksjon forside(ctx: ordbok_tekst) -> ordbok_tekst {
    web.route("GET /")
    returner html("<h1>Velkommen</h1><p><a href=/hilsen?navn=Kari>Hils</a></p>")
}

funksjon hilsen(ctx: ordbok_tekst) -> ordbok_tekst {
    web.route("GET /hilsen")
    la navn = web.request_query_param(ctx, "navn")
    hvis navn == "" { navn = "verden" }
    returner html("<h1>Hei, " + nf.html_escape(navn) + "!</h1>")
}

funksjon helse(ctx: ordbok_tekst) -> ordbok_tekst {
    web.route("GET /helse")
    returner web.response_builder(200, {"content-type": "text/plain"}, "ok")
}

funksjon start() -> heltall {
    skriv("Tjenesten er klar")
    returner 0
}

Hva som skjer her

Legg merke til html-funksjonen øverst. Den er ikke en rute — den har ingen web.route — men en vanlig hjelpefunksjon som bygger et svar med riktig innholdstype. Når du har mer enn én rute som returnerer HTML, sparer det deg for å gjenta den samme hovedlinja i hvert svar. Det er et lite eksempel på noe som gjelder generelt: rutene bør være tynne, og selve arbeidet bør gjøres i vanlige funksjoner som er lette å teste hver for seg.

ctx er forespørselen. Fra den henter du det klienten sendte: spørrestrengen med web.request_query_param, hodene med web.request_header. Kjøretiden har ingen dynamiske stiruter — du kan ikke skrive noe i retning av en sti med innebygd parameter — men spørrestrengen dekker det meste av det samme behovet.

Helseruta ser triviell ut, men er den viktigste av de tre i drift. Den svarer uten å røre database eller nettverk, og forteller dermed bare én ting: prosessen lever og binder porten. Det er nøyaktig det en prosessovervåker trenger å vite, og grunnen til at den bør holdes så enkel.

Start tjenesten

NORSCODE_VM_CAPABILITIES="net.tcp" \
NORSCODE_VM_NET_SCOPE="127.0.0.1" \
  nc serve tjeneste.no --host 127.0.0.1 --port 8080

Kapabilitetene er ikke pynt

Uten net.tcp binder ikke tjenesten porten i det hele tatt. Det føles strengt første gang, men er hele poenget: du ser i selve kommandoen hva programmet har lov til. Her kan det snakke TCP, og bare med localhost. Det kan ikke lese eller skrive disk, og ikke lese miljøvariabler.

Skal tjenesten lese en konfigurasjonsfil, må du legge til disk.read og peke NORSCODE_VM_DISK_ROOT dit fila ligger. Da står det svart på hvitt i oppstartskommandoen hva tjenesten rører — og den som leser kommandoen vet like mye som den som har lest all koden.

Én ting du ikke må glemme

Verdien fra spørrestrengen går gjennom nf.html_escape før den havner i HTML. Uten det kunne en besøkende sende inn et skript-element som navn, og få det kjørt i nettleseren til alle som åpnet lenka. Regelen er enkel og uten unntak: alt som kommer utenfra skal escapes før det settes inn i HTML, SQL eller JSON.

Tilbake til oversikten