Continue writing report

tex/.gitignore

@@ -17,4 +17,4 @@
 *.ist
 *.out
 _minted-*
-*.pdf
+main.pdf

tex/biblio.bib

@@ -35,6 +35,15 @@
 	lastchecked = {24. Huhtikuuta, 2020}
 }
 
+@article{rust:println,
+	title = {Macro std::println},
+	journal = {},
+	author = {Rust Team},
+	year = 2020,
+	url = {https://doc.rust-lang.org/std/macro.println.html},
+	lastchecked = {3. Toukokuuta, 2020}
+}
+
 @article{wiki:garbagecollection,
 	title = {Automaattinen roskienkeräys},
 	journal = {},
@@ -53,6 +62,15 @@
 	lastchecked = {1. Toukokuuta 2020},
 }
 
+@misc{rust:macro-lisp,
+	title = {Lisp-like DSL for Rust language},
+	url = {https://github.com/JunSuzukiJapan/macro-lisp},
+	publisher = {},
+	author = {JunSuzukiJapan},
+	year = 2020,
+	lastchecked = {1. Toukokuuta 2020},
+}
+
 @misc{rust:cratesio,
 	title = {The Rust community's crate registry},
 	url = {https://crates.io},
@@ -80,6 +98,15 @@
 	lastchecked = {1. Toukokuuta 2020},
 }
 
+@misc{yew:router-problem,
+	title ={How to use the Router},
+	url = {https://yew.rs/docs/concepts/router#how-to-use-the-router},
+	publisher = {},
+	author = {Yew Team},
+	year = 2020,
+	lastchecked = {3. Toukokuuta 2020},
+}
+
 @misc{webassembly:stdweb,
 	title = {stdweb},
 	url = "https://docs.rs/stdweb/0.4.20/stdweb",
@@ -124,3 +151,13 @@
 	year = 2019,
 	lastchecked = {2. Toukokuuta 2020},
 }
+
+@article{wiki:metaprogramming,
+	title ={Understanding WebAssembly text format},
+	url = {https://en.wikipedia.org/wiki/Metaprogramming},
+	journal = {},
+	author = {Wikipedia contributors},
+	year = 2020,
+	lastchecked = {3. Toukokuuta 2020},
+}
+

tex/chapters/2-kielet.tex

@@ -11,9 +11,11 @@ Automaattiselle roskienkeruulle on aikaisemmin ollut vaihtoehtona vain manuaalin
 
 Rustin yhtenä pääominaisuutena on mainostettu sen uudenlaista näkökulmaa muistinhallintaan: omistajuutta \cite{rust:ownership}. Siinä jokaisella arvolla on omistaja, ja kun omistaja menee näkyvyysalueen ulkopuolelle, niin menevät myös sen omistamat arvotkin, eli ne vapautetaan muistista. Arvojen omistajuutta voi siirtää joko pysyvästi tai väliaikaisesti lainaamalla.
 
+\clearpage
+
 \begin{code}
 	\inputminted{Rust}{code/ownership.rs}
-	\captionof{listing}{Omistajuus}
+	\captionof{listing}{Omistajuus Rustissa}
 	\label{code:rust:ownership}
 \end{code}
 
@@ -87,7 +89,7 @@ Edellä mainittu tyyppi u8 on niin kutsuttu allekirjoittamaton kokonaisluku (eng
 	\caption{Rustin kokonaislukutyypit ja niiden vaihteluvälit}
 \end{table}
 
-Toisin kuin C- ja C++ -kielissä, Rustissa on oletuksena allekirjoittamattomien kokonaislukujen ylivuoto pois päältä. Tämä tarkoittaa sitä, että jos 8-bittisen allekirjoittamattoman kokonaisluvun (u8) arvo on esimerkiksi 256, siitä tulee 0. Rustin kääntäjä siis ei anna tällaisen tapahtua vaan kääntämisen yhteydessä tulee virheviesti:
+\clearpage
 
 \begin{code}
 	\inputminted{shell}{code/integer-overflow}
@@ -95,6 +97,8 @@ Toisin kuin C- ja C++ -kielissä, Rustissa on oletuksena allekirjoittamattomien
 	\label{code:rust:integer-overflow}
 \end{code}
 
+Toisin kuin C- ja C++ -kielissä, Rustissa on oletuksena allekirjoittamattomien kokonaislukujen ylivuoto pois päältä. Tämä tarkoittaa sitä, että jos 8-bittisen allekirjoittamattoman kokonaisluvun (u8) arvo on esimerkiksi 256, siitä tulee 0. Rustin kääntäjä siis ei anna tällaisen tapahtua vaan kääntämisen yhteydessä tulee virheviesti, jonka voi nähdä koodiesimerkissä \ref{code:rust:integer-overflow}.
+
 \subsection{Muuttumaton data}
 Rustissa kaikki arvot ovat oletuksena muuttumattomia (engl.\ immutable). Jos muuttumattoman datan sijasta tarvitsee muuttujia (engl. mutable), voi käyttää avainsanaa ''mut'', esimerkiksi \mintinline{Rust}{let mut name = "Marko"}. Myös lainaukset suoritetaan oletuksena muuttumattomasti ja muutettavan lainauksen voi tehdä samalla avainsanalla, esimerkiksi \mintinline{Rust}{say_hello(&mut name)}
 
@@ -106,9 +110,7 @@ Rustia kehitettäessä on aina ollut tavoitteena luotettavuus. Tämä tarkoittaa
 Myös Rustin kääntäjään on panostettu paljon, ja virheiden sattuessa se on todella hyvä työkalu ohjelmoijalle. Se alleviivaa ongelmakohdat ja selittää lyhyesti, mistä ongelma johtuu. Jossain tapauksissa kääntäjä jopa antaa pieniä koodin pätkiä mistä voi olla apua ongelman ratkaisemisessa.
 
 \subsection{Paketinhallinta}
-Rustin paketinhallinta on toteutettu Cargo-nimisellä ohjelmalla. Sitä voi käyttää koko ohjelmiston elinkaaren ajan aina projektin luomisesta sen julkaisemiseen. Cargon käsittelemiä paketteja kutsutaan laatikoiksi (eng. crate), jotka julkaistaan crates.io \cite{rust:cratesio} pakettirekisterissä. Laatikot voivat myös olla riippuvaisia toisista laatikoista.
+Rustin paketinhallinta on toteutettu Cargo-nimisellä ohjelmalla. Sitä voi käyttää koko ohjelmiston elinkaaren ajan aina projektin luomisesta sen julkaisemiseen. Cargon käsittelemiä paketteja kutsutaan laatikoiksi (eng. crate), jotka julkaistaan crates.io \cite{rust:cratesio} pakettirekisterissä. Laatikot voivat myös olla riippuvaisia toisista laatikoista. Laatikon tiedot ja riippuvuudet määritetään Cargo.toml tiedostossa.
-
-Laatikon tiedot ja riippuvuudet määritetään Cargo.toml tiedostossa.
 
 \begin{code}
 	\inputminted{TOML}{code/Cargo.toml}
@@ -118,27 +120,51 @@ Laatikon tiedot ja riippuvuudet määritetään Cargo.toml tiedostossa.
 
 Cargoon on saatavilla myös useita liitännäisiä, esimerkiksi cargo-watch, joka suorittaa halutun toiminnon aina kun projektin sisällä tapahtuu muutoksia ja tässäkin projektissa käytetty cargo-web, joka helpottaa WebAssembly-ohjelmien kehittämistä.
 
+\subsection{Makrot}
+Yksi todella mielenkiintoinen ominaisuus Rustissa on makrot. Se on toiminnallisuus mikä mahdollistaa metaohjelmoinnin \cite{wiki:metaprogramming}. Metaohjelmoinnissa koodia voi generoida kääntämisen aikana, mikä on erityisen hyödyllistä esimerkiksi silloin, kun ohjelmoija tarvitsee useita toiminnalisuudeltaan samankaltaisia funktioita.
+
+\begin{code}
+	\inputminted{Rust}{code/macro.rs}
+	\captionof{listing}{Runsassanainen laskin toteutettuna Rustin makrona}
+	\label{code:rust:macro}
+\end{code}
+
+Makron sisällä suluissa olevat lauseet ovat verrattavissa Rustin \mintinline{Rust}{match} -lauseeseen. Kun makron syöte vastaa jotakin näistä lauseista, hakasulkujen sisällä oleva koodi generoidaan. Makrossa käytetty \mintinline{Rust}{println!()} on myös itsessään makro, joka tulee Rustin ''std'' -kirjaston mukana.
+
+\clearpage
+
+\begin{code}
+	\inputminted{Rust}{code/println.rs}
+	\captionof{listing}{Rustin sisäänrakennettu println!() makro \cite{rust:println}}
+	\label{code:rust:println}
+\end{code}
+
+Metaohjelmointi avaa aivan uudenlaisia mahdollisuuksia sille, mitä ohjelmointikielellä voi tehdä. Makroilla voi toteuttaa vaikka kokonaisen ohjelmointikielen \cite{rust:macro-lisp}.
+
 \subsection{Dokumentaatio ja yhteisö}
 Rust on tunnettu todella laajasta dokumentaatiostaan ja vahvasta yhteisöstään. Molemmista on paljon apua varsinkin aloittejioille.
 
-Aloitin itsekin opiskelemaan Rustia vain hieman ennen tämän opinnäytetyön alkua ja vahvasta yhteisöstä oli monesti apua.
+Aloitin itsekin opiskelemaan Rustia vain hieman ennen tämän opinnäytetyön alkua ja yhteisöstä oli monesti apua projektin aikana vastaan tulleissa ongelmissa.
 
 \section{WebAssembly}
 WebAssembly \cite{webassembly:home} on kehitteillä oleva asiakaspuolen ohjelmointikieli. Sitä on suunniteltu JavaScriptin seuraajaksi ja sen suurimpana etuna JavaScriptiin verrattuna on huomattavasti matalamman tason esitysmuoto, minkä ansiosta se on suorituskykyisempi.
 
 Kehittäjän ei ole tarkoitus kirjoittaa WebAssemblya itse, vaan käyttää työkaluja, joilla olemassa olevia ohjelmointikieliä voi kääntää WebAssemblyksi. Rust on tästä hyvä esimerkki, sillä WebAssembly on yksi sen kääntäjän natiiveista ''targeteista'', samalla tavalla kuin vaikka x86-prosessorit.
 
-WebAssembly on siis ensisijaisesti binääriformaatti, mutta sen voi muuntaa myös tekstiformaatiksi, jonka nimi on WebAssembly text \cite{webassembly:text}. WebAssembly text käyttää S-lauseita, joten se muistuttaa syntaxiltaan hyvin paljon Lisp-ohjelmointikieltä.
+WebAssembly on siis ensisijaisesti binääriformaatti, mutta sen voi muuntaa myös tekstiformaatiksi, jonka nimi on WebAssembly text \cite{webassembly:text}. WebAssembly text käyttää S-lauseita, joten se muistuttaa syntaksiltaan hyvin paljon Lisp-ohjelmointikieltä.
 
-\begin{code}
-	\inputminted{Lisp}{code/plus.wat}
-	\captionof{listing}{Lukujen yhteenlasku WebAssembly text -formaatissa}
-	\label{code:webassembly:plus}
-\end{code}
 \clearpage
 
+\begin{code}
+	\inputminted{Lisp}{code/plus.wat}
+	\captionof{listing}{Lukujen yhteenlaskufunktio WebAssembly text -formaatissa}
+	\label{code:webassembly:plus}
+\end{code}
+
 \begin{code}
 	\inputminted{Rust}{code/plus.rs}
-	\captionof{listing}{Lukujen yhteenlasku Rustilla}
+	\captionof{listing}{Lukujen yhteenlaskufunktio Rustilla}
 	\label{code:rust:plus}
 \end{code}
+
+WebAssembly textiä käytetään esimerkiksi debuggereissa.

tex/chapters/3-projekti.tex

@@ -7,6 +7,8 @@ Palvelinpuolen kehykseksi valikoitui Actix web. Se on käytännössä vastine Ja
 
 Actix web on puolestaan rakennettu hyödyntämällä Actix -sovelluskehystä, mikä on rakennettu löyhästi actor-mallin pohjalta. Actor-malli\cite{wiki:actor} on Carl Hewittin vuonna 1973 luoma matemaattinen ja tietotekninen malli rinnakkaisajosta. Tämän ansiosta Actix web on hyvin suorituskykyinen ja helposti skaalautuva ratkaisu rajapintoja rakennettaessa.
 
+\clearpage
+
 Actix web on myös hyvin integroitu Rustin vahvaan tyypitykseen. Erityisen vaikuttavaa oli se, että esimerkiksi tietyn rajapinnan päätepisteen POST-pyyntöön pystyy määrittämään parametriksi tietyn rakenteen (eng. structure).
 
 \begin{code}
@@ -23,7 +25,7 @@ Tällöin varmistutaan automaattisesti siitä, että kun asiakkaan POST-pyyntö
 	\label{code:json:registeruser}
 \end{code}
 
-Kun koodiesimerkin 7 funktioon ''register'' saapuu koodiesimerkin 8 mukainen JSON objekti, Actix huomaa väärän tyypin ja vastaa statuskoodilla ''400 Bad Request'', koska objektin parametri \mintinline{JSON}{"admin"} ei ole tyyppiä \mintinline{Rust}{bool}.
+Kun koodiesimerkin \ref{code:rust:registeruser} funktioon ''register'' saapuu koodiesimerkin \ref{code:json:registeruser} mukainen JSON objekti, Actix huomaa väärän tyypin ja vastaa statuskoodilla ''400 Bad Request'', koska objektin parametri \mintinline{JSON}{"admin"} ei ole tyyppiä \mintinline{Rust}{bool}.
 
 \subsection{Todentaminen}
 
@@ -37,9 +39,9 @@ Todentamiseen päätin käyttää JSON Web Tokeneita. JSON Web Tokenit ovat stan
 	\label{code:json:jwt}
 \end{code}
 
-Tämä tokenin sisältö on kaikkien sen hallussapitäjien nähtävissä. Turvallisuus tulee siitä, että token on allekirjoitettu palvelinpuolella vain palvelimen tiedossa olevalla salasanalla niin, että jos tokenin sisältö muuttuu yhtään, palvelin näkee että se ei ole enää validi.
+Tämä tokenin sisältö on kaikkien sen hallussapitäjien nähtävissä. Tokenin turvallisuus tulee siitä, että token on allekirjoitettu palvelinpuolella vain palvelimen tiedossa olevalla salasanalla niin, että jos tokenin sisältö muuttuu yhtään, palvelin näkee että se ei ole enää validi.
 
-Eli esimerkiksi jos joku tämän sovelluksen käyttäjä, joka ei ole ylläpitäjä, koittaa tehdä itsestään ylläpitäjän muuttamalla tokenista parametrin \mintinline{JSON}{"admin"}: \mintinline{JSON}{false} arvoksi \mintinline{JSON}{true}, palvelimella suoritettava JWT validointifunktio, joka tietää oikean salasanan, näkee että tämä tunniste ei ole validi.
+Eli esimerkiksi jos joku tämän sovelluksen käyttäjä, joka ei ole ylläpitäjä, koittaa tehdä itsestään ylläpitäjän muuttamalla tokenista parametrin \mintinline{JSON}{"admin": false} arvoksi \mintinline{JSON}{true}, palvelimella suoritettava JWT validointifunktio, joka tietää oikean salasanan, näkee että tämä tunniste ei ole enää validi.
 
 Tokenin sisällön voi päättää kokonaan itse, vaikkakin joitakin standardeja kenttiä on määritetty, esimerkiksi iss (issuer), sub (subject) ja exp (expiration time). Päätin sisällyttää tiedon siitä, että onko käyttäjä ylläpitäjä, koska tätä tietoa voi sitten käyttää asiakaspuolella esimerkiksi käyttöliittymän muokkaamiseen käyttäjän roolin perusteella. Usein myös käyttäjän nimi sisällytetään tokeniin. Tokenin sisältöä suunnitellessa kannattaa pitää mielessä että sen sisältö on nähtävissä kaikille, joten se ei ole oikea paikka tallettaa salaista tietoa, kuten vaikka käyttäjän salasana.
 
@@ -75,11 +77,22 @@ Olen JavaScript-maailmassa tottunut siihen, että käyttöliittymäkehyksiin lö
   \label{fig:login}
 \end{figure}
 
+\subsection{Reititys}
+Reititykseen käytin Yew:n liitännäistä, yew\char`_routeria. Reititys asiakaspuolen ohjelmassa tarkoittaa sitä, että selaimen osoitepalkissa olevan polun mukaan käyttäjä reititetään oikeaan ohjelman osaan. Tämä liittyy käsitykseen yhden sivun ohjelmista (eng. single page application), joissa selain suorittaa yhden ohjelman, jonka jälkeen perinteisiä sivujen latauksia ei enää tapahtu. Ohjelma muokkaa osoitepalkissa näkyvää osoitetta, jonka pohjalta sitten reititys oikeaan komponenttiin tapahtuu.
+
+Asiakaspuolen reititys vaatii myös palvelinpuolelta sen, että kaikki mahdolliset asiakaspuolen reitit palauttavat ohjelman. Toinen edellytys on se, että palvelin ei palauta uudelleenohjausta (HTTP 302), koska silloin myös osoitepalkissa oleva osoite muuttuu eikä sitä voida välittää asiakaspuolen ohjelmalle.
+
+Yritin pitkään toteuttaa tällaista logiikkaa palvelinpuolelle siinä onnistumatta, mutta onnekseni yew\char`_routerin esimerkeistä löytyi esimerkkikoodia tämän saavuttamiseksi käyttämäni palvelinkehyksen kanssa. Päädyin laittamaan kaikki palvelimen omat reitit polun \mintinline{shell}{/api/} alle, ja asiakaspuolen ohjelman juureen (\mintinline{shell}{/}). Sitten määritin ns. ''catch-all'' reitin, joka palauttaa asiakaspuolen ohjelman ilman uudelleenohjausta. Tämä on Actixissa nimeltään \mintinline{shell}{default_service}.
+
+\clearpage
+
+Myös yew\char`_routerin kanssa oli omat haasteensa. Alkuun en saanut sitä toimimaan ollenkaan, vaan kaikki kutsut ohjattiin ensimmäisenä määritettyyn reittiin, mikä oli tässä tapauksessa ''/''. Ongelman syyksi paljastui yew\char`_routerin Switch-komponentin kokoava ''to'' makro. Ratkaisuna oli reitin ''/'' makron \mintinline{Rust}{#[to = "/"]} siirtäminen viimeiseksi listassa. Tarkempaa tietoa tästä ongelmasta voi lukea Yew:n dokumentaatiosta \cite{yew:router-problem}.
+
 \section{Ongelmat}
 Projektin loppuvaiheilla ilmeni muutamia ongelmia, mitä en ehtinyt enää ajan puutteen takia korjaamaan.
 
-Palvelinpuolella keksin kokoava kirjasto, Actixin liitännäinen ''actix-identity'', kirjoittaa oletuksena keksiin parametrin \mintinline{JSON}{"HttpOnly": true}, mikä tarkoittaa sitä, että selain ei anna sen sisällä suoritettaville ohjelmille pääsyä tähän keksiin. Tämä on todella hyvä turvallisuusominaisuus, mikä estää haitallisia ohjelmia varastamaan käyttäjän kirjautumistietoja.
+Palvelinpuolella keksin kokoava kirjasto, Actixin liitännäinen actix\char`_identity, kirjoittaa oletuksena keksiin parametrin \mintinline{JSON}{"HttpOnly": true}, mikä tarkoittaa sitä, että selain ei anna sen sisällä suoritettaville ohjelmille pääsyä tähän keksiin. Tämä on todella hyvä turvallisuusominaisuus, mikä estää haitallisia ohjelmia varastamasta käyttäjän kirjautumistietoja.
 
-Suunnittelmana oli käyttää keksin tietoja asiakaspuolella reititykseen. Esimerkiksi jos keksiä ei ole olemassa, käyttäjä tulee reitittää sisäänkirjautumiskomponenttiin, missä keksi voidaan noutaa palvelimelta. Koska keksissä on tämä HttpOnly-parametri, tähän ei ole mahdollisuutta. Tämän parametrin voisi tietysti laittaa pois päältä, mutta ''actix-identity'' ei tarjoa tähän mitään mahdollisuutta.
+Suunnittelmana oli käyttää keksin tietoja asiakaspuolella reititykseen. Esimerkiksi jos keksiä ei ole olemassa, käyttäjä tulee reitittää sisäänkirjautumiskomponenttiin, missä keksi voidaan noutaa palvelimelta. Koska keksissä on tämä HttpOnly-parametri, tähän ei ole mahdollisuutta. Tämän parametrin voisi tietysti laittaa pois päältä, mutta actix\char`_identity ei tarjoa tähän mitään mahdollisuutta.
 
 Yhtenä ratkaisuna tähän ongelmaan olisi käyttää JSON Web Tokenin tallettamiseen keksien sijasta selaimen LocalStoragea. Tämä vaatisi lisää työtä sekä asiakaspuolella että palvelinpuolella ja valitettavasti tähän ei jäänyt enää aikaa.

tex/chapters/4-tulokset.tex

@@ -1,3 +1,4 @@
+\clearpage
 \chapter{Tulokset}
 
 \begin{figure}[h]
@@ -7,4 +8,5 @@
   \label{fig:login}
 \end{figure}
 
-Tuloksena syntyi yksinkertainen web-applikaatio, missä sekä asiakaspuoli että palvelinpuoli on toteutettu Rustilla.
+Tuloksena syntyi yksinkertainen web-applikaatio, missä sekä palvelinpuoli, että asiakaspuoli oli toteutettu Rustilla. Kuvassa \ref{fig:login} on kuvattu kaikki kirjautumisprosessin vaiheet tässä projektissa.
+

tex/code/Cargo.toml

@@ -4,8 +4,6 @@ version = "0.1.0"
 authors = ["Marko Korhonen <marko.korhonen@reekynet.com>"]
 edition = "2018"
 
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
-
 [dependencies]
 actix-web = "2.0.0"
 actix-rt = "1.0.0"

tex/code/macro.rs

@@ -0,0 +1,25 @@
+macro_rules! laske {
+    (lisää $num1:literal ja $num2:literal) => {
+        println!("{} plus {} on {}", $num1, $num2, $num1 + $num2);
+    };
+    (vähennä $num1:literal ja $num2:literal) => {
+        println!("{} miinus {} on {}", $num1, $num2, $num1 - $num2);
+    };
+    (kerro $num1:literal ja $num2:literal) => {
+        println!("{} kertaa {} on {}", $num1, $num2, $num1 * $num2);
+    };
+    (jaa $num1:literal ja $num2:literal) => {
+        println!("{} jaettuna {} on {}", $num1, $num2, $num1 / $num2);
+    };
+}
+
+laske!(lisää 10 ja 269);
+laske!(vähennä 652 ja 3);
+laske!(kerro 256 ja 2);
+laske!(jaa 100 ja 50);
+
+// Tuloste:
+// 10 plus 269 on 279
+// 652 miinus 3 on 649
+// 256 kertaa 2 on 512
+// 100 jaettuna 50 on 2

tex/code/println.rs

@@ -0,0 +1,4 @@
+macro_rules! println {
+    () => { ... };
+    ($($arg:tt)*) => { ... };
+}

tex/view.sh

@@ -3,12 +3,12 @@ function finish {
 	killall entr
 }
 
+bibtex8 main
 xelatex -shell-escape -8bit main
 
 makeglossaries main
 find chapters | entr -cp xelatex -shell-escape -8bit main &
 ls biblio.bib | entr -cp bibtex8 main &
-ls chapters/0abbr.tex | entr -cp makeglossaries main &
 zathura >/dev/null 2>&1 main.pdf
 
 trap finish EXIT