====== Ktor ======

Ktor je významný doplnok programovania v Kotlin-e. Zabezpečuje komunikáciu cez API. Vytvára stranu **Servera** aj **Klienta**. Komunikácia môže byť na báze HTTP, alebo WebSocket. Ktor využíva **[[kotlin-coroutines|Coroutines]]**.

===== Server =====

Ktor Server vybuduje API rozhranie pre IP komunikáciu. Pre **dátové** projekty sa častejšie využije REST API komunikácia, kedy sa [[restapi_baseinfo|protokolom HTTP]] zasielajú požiadavky (Request) a naspäť sa vracajú odpovede (Response).

Projekt sólo servera s REST API je možné vygenerovať, upraviť a spustiť veľmi jednoducho a použiť napríklad pre testovací ''Mock server'', ktorý pobeží na desktope, alebo mobilných ARM zariadeniach (tablet, telefón, ...). Už pri vygenerovaní projektu, build-nutí a spustení je k dispozícii základný programový a funkčný server.

> pre JVM (desktopy) sa používa generátor: [[https://start.ktor.io/settings|New Ktor Project]] a ďalej postupovať podľa [[https://www.restapi.sk/doku.php?id=kotlin-ktor#vytvorenie_projektu|popisu nižšie]]
> pre Multiplatform využi IntelliJ Idea - nový MP projekt s Ktor

Server pri príjme požiadavky zabezpečuje Smerovanie (Routing) a podrobné Trasy (Route) k cieľom, Príklad čiastočne funkčného kódu:

<code Kotlin>
routing {
  route("/") {
    get("") { call.respondText("Please define path.") }
  }
  route("/article") {
    get { call.respond(repository.allArticles) }
    get ("/byId/{idArticle}") { call.respond(repository.articleById(call.parameters["idArticle"])) }
    post { call.receive<article>() /* code for add or update */ }
    delete("/{id}") { /* code for remove */ }
  }
}
</code>

Príklad príkazu ''curl'' pre **POST** a **DELETE**:
<code bash>
# POST:
curl -v --header "Content-Type: application/json" --request POST --data '{"name":"MyTest2","description":"Task for my test2","priority":"High"}' 0.0.0.0:8080/tasks

# DELETE:
curl -v --request DELETE 0.0.0.0:8080/tasks/MyTest

# switch -v showing detail info of response from server
</code>
==== Vytvorenie projektu ====

Generovť projekt je možné pomocou web rozhrania, alebo aplikácie **Ktor CLI**, alebo priamo v IDE.

=== Generovanie pomocou web rozhrania ===

> Vytvorenie projektu na [[https://ktor.io/docs/server-create-a-new-project.html|webe Ktor]].

Na stránke [[https://start.ktor.io/settings|New Ktor Project]] po vyplnení mena projektu sa v **Configure** zvolia parametre (možné ponechať predvolené). Pre pridanie **Plugins** v spondej tabuľke sa použije **Add** (možné bez ponechať výberu), ale každopádne je vhodné zmapovať pluginy pre ich budúce použitie. **Preview** poskyruje náhľad na štruktúru projektu. \\
Nakoniec sa projekt stiahne a uloží pomocou **Download**. Potom už postačuje ZIP rozbaliť na vhodné miesto. \\
- Generátor je vhodné použiť, ak nie je dostupné profi IDE s možnosťou generovania projektu **Ktor**. \\
- Zároveň je možné vygenerovaný projekt spravovať v ľahších IDE (VSC, ...)

== Oživenie projektu ==

Ak je projekt pripravený, tak sa ďalej bude pracovať v jeho zložke. (Príkazy sú vhodné pre Shell ktorý je aj vo Windows...)
<code>
cd ~/<pathToMyProject>
</code>
Nastaviť skript ako spustiteľný:
<code>
chmod +x ./gradlew
</code>
Zostavenie projektu:
<code>
./gradlew build
</code>
Spustenie projektu:
<code>
./gradlew run
</code>
Overenie funkčnosti v prehliadači na adrese: [[http://0.0.0.0:8080]]

== Otvorenie projektu v IDE IntelliJ IDEA ==

<code>
cd ~/<pathToMyProject>
open -na "IntelliJ IDEA CE.app" .  # open my project if IDE is in /Applications/
</code>
prípadne:
<code>
open -a "IntelliJ IDEA CE.app" .
</code>
alebo skrátene za predpokladu správnej konfigurácie [[https://www.jetbrains.com/help/idea/2025.2/working-with-the-ide-features-from-command-line.html?Working_with_the_IDE_Features_from_Command_Line&keymap=macOS#standalone|Path]]:
<code>
idea .
</code>

=== Nový projekt pomocou Ktor CLI ===

Predpokladá sa že už je nainštalovaný [[https://brew.sh/|Homebrew]] \\
Inštalácia Ktor CLI:
<code>
brew install ktor
</code>
Vytvorenie projektu:
<code>
mkdir ~/MyKtorProjects
cd ~/MyKtorProjects
brew upgrade ktor
ktor new
cd <ktorSample>
chmod +x ./gradlew
./gradlew build
./gradlew run
</code>
Pre výber doplnkov použi šípky, tabelátor a enter. Vytvorenie : Ctrl+G

=== aktuálna IP adresa PC ===
<code bash>
ipconfig getifaddr en0  # ipv4 only
# or
ifconfig | grep "inet " | grep -v 127.0.0.1;  # other IP of device
# other
curl ifconfig.me  # ipv6
# see more for curl command: https://curl.se/
</code>

==== Testovanie projektu ====

> KtorIo : [[https://ktor.io/docs/server-create-a-new-project.html#write-an-integration-test|Integračný test]]
> KtorIo : [[https://ktor.io/docs/server-requests-and-responses.html#add-unit-tests|Jednotkové testy]]

Pri testovaní je vhdoné vytvoriť ''@Test'' funkcie pre všetky trasy. Test beží v oddelenom priestore od servera. Pre test je nutné vytvoriť zložky ''test/kotlin'' v ''src'' (vedľa ''main'').

=== Obsluha chýb ===

> KtorIo : [[https://ktor.io/docs/server-create-a-new-project.html#register-error-handlers|Pridanie pluginu StatusPage]]

Ak doplnuk **StatusPage** nebol vybraný a pridaný pri tvorbe projektu, potom je vhodné ho pridať manuálne.

==== RESTful API ====

> KtorIo : [[https://ktor.io/docs/server-create-restful-apis.html|Ako vytvoriť RESTful API v Kotlin s Ktor]] - nový projekt s vybranými doplnkami: Routing, Content Negotiation, Kotlinx.serialization, Static Content

RESTful API komunikuje JSON formátom dát. Teda neprijíma telo odoslané pomocou ''submit'' v HTML a taktiež pre zobrazenie výsledku nevytvára statický HTML obsah stránky, ako v príkladoch vyššie.

  * **Content Negotiation** - skúma typ obsahu //request//, aby poskytol správny //response//. Klient HTTP indikuje typ obsahu v hlavičke kľúčom ''Accept'' (jeden či viac typov, napríklad: text/html, application/xhtml+xml, application/xml;q=0.9, image/avif, image/webp,image/apng, */*;q=0.8, application/signed-exchange;v=b3;q=0.7).

=== Testovanie projektu ===

> KtorIo : [[https://ktor.io/docs/server-create-restful-apis.html#create-unit-tests|trasy pomocou klienta Ktor]] a JUnit
> KtorIo : [[https://ktor.io/docs/server-create-restful-apis.html#unit-tests-via-jsonpath|testy pomocou JsonPath]]

==== Web stránka pomocou Kotlin/Ktor ====

> KtorIo : [[https://ktor.io/docs/server-create-website.html|interaktívna web stránka]] s Ktor a Thymeleaf