lweb/README.md

# lweb

LiHaSo Webserver Modul

## Öffentliche Funktionen:

### Konfiguration des Server Moduls:

Mögliche Parameter:
```
lweb::#conf_port            ;Hörender Port, z.B. "80"
lweb::#conf_binding         ;Interface Binding z.B. nur Lokalhost mit "127.0.0.1"
lweb::#conf_defaultfile     ;Standard wenn keine Datei (Extension angegeben ist) z.B. "index.php"
lweb::#conf_basedir         ;Standard Verzeichnis z.B. "/srv/www/htdocs/"
lweb::#conf_error400        ;TODO:error400 bearbeitung
lweb::#conf_max_clients     ;Maximale Clientconnections (Memory beachten)
lweb::#conf_server_type     ;Derzeit ohne Funktion (Später z.B. HTTPS und HTTP oder HTTP/2 usw.)
lweb::#conf_cache_enable    ;Bei wert auf 1 Setzen um zu Aktivieren diese Funktion ist aber derzeit mit Vorsicht zu geniessen!!!!
```

#### Funktionen
`lweb::set_config(parameter.i=#conf_defaultfile, setting.s="index.html")`

Dass setting ist immer ein String.

Rückgabewert ist `#True` oder `#False.`


`lweb::get_config(parameter.i=#conf_defaultfile)`

Der Rückgabewert ist immer einen String.

### Starten des Servers
`lweb::start_server()`

Rückgabewert ist `#True` oder `#False.`

### Verschiedene arten des Handlers Registrieren & Proceduren:

`lweb::register_client_handler(Route.s, Callback.i, AppPrototype.i = #handler_proto_get, RouteType.i = #handler_sub)`

Rückgabewerte ist immer ein JSONString!

AppPrototype Möglichkeiten:
```
lweb::#handler_proto_universal      ;Für HTTP POST und GET Requests Nimmt Optional einen String entgegen.
lweb::#handler_proto_post           ;Nur für HTTP POST Requests Nimmt Zwingend einen String entgegen.
lweb::#handler_proto_get            ;Nur für HTTP GET Requests Nimmt keinen String entgegen.
```

RouteType Möglichkeiten:
```
lweb::#handler_only         ;Reagiert nur auf die Url (Bsp. /rest/v1/test aber nicht auf /rest/v1/test/sub)
lweb::#handler_sub          ;Reagiert auf eine ganze Url die begint. (Bsp. /rest/v1/test sowie auch auf /rest/v1/test/sub)
lweb::#handler_type         ;Reagiert auf datentypen (zb. *.php = "php")
```

Map für Antwort ist eine einfache Stringmap:
`NewMap Response.s()`

Wobei folgende werte entsprechend gesetzt werden müssen:
* `lweb::#cha_R_ResponseType = "ResponseType"`                ;Element ResponseType,Mimetype mit `lweb::mimetype("html")` z.B. Setzen.
* `lweb::#cha_R_ResponseContentType = "ResponseContentType"`  ;Element ResponseContentType, `lweb::#response_string` oder `lweb::#response_Memory`
* `lweb::#cha_R_MemoryAdress = "MemoryAdress"`                ;Element MemoryAdress, Konvertieren zu String `Str(Adresse)` wird mit `Val()` zurückkonvertiert. Und nach dem Bearbeiten wieder freigegeben!
* `lweb::#cha_R_MemorySize = "MemorySize"`                    ;Element MemorySize, Konvertieren zu String `Str(Grösse)` wird mit `Val()` zurückkonvertiert.
* `lweb::#cha_R_StringBase64 = "StringBase64"`                ;Element StringBase64, Base64 Encoded String
* `lweb::#cha_R_http_head_status = "HeaderStatus"`            ;`"200 OK"`, `"300 Error"`, `"500 Server Error"` usw. 

Zu beachten ist das entweder ein Base64 encodierter String oder ein MemoryBlock zurückgegeben werden muss!

Komplettes Beispiel:
```
Procedure.s Sample_Header(Map Header.s())
  Define *Text
  Define.s Encoded, ZumSenden, TBD
  NewMap Response.s()
  TBD="<div><div><h1>Header</h1></div><br/>"+#CRLF$
  ResetMap(Header())
  While NextMapElement(Header())
    TBD = TBD+"<div>"+MapKey(Header())+" : "+Header()+" </div><br/>"+#CRLF$
  Wend
  
  *Text = UTF8("<!DOCTYPE html><html><header><title>Alle Client Headers</title></header><body>"+TBD+"</body></html>")
  Encoded = Base64Encoder(*Text, MemorySize(*Text))
  Debug "Encoded: " + Encoded
  Response(lhs_web::#cha_R_ResponseContentType) = lhs_web::#response_string
  Response(lhs_web::#cha_R_StringBase64) = Encoded
  Response(lhs_web::#cha_R_ResponseType) = lhs_web::mimetype("html")
  Response(lhs_web::#cha_R_http_head_status) = "200 OK"
  ZumSenden = lhs_web::MapToJSONString(Response())
  Debug "ZumSenden: " + ZumSenden
  ProcedureReturn ZumSenden
EndProcedure

lhs_web::register_client_handler("/server/show_client_headers", @Sample_Header(),lhs_web::#handler_proto_get, lhs_web::#handler_sub)
```

### Einen Mimetype eines Fileextensions:
`lweb::mimetype(file.s)`

Gibt einen String zurück.

Konvertiert z.B. `lweb::mimetype("html")` zu `"text/html"`

### Eine Map in einen JSONString Konvertieren (z.B. in Interaktion mit einer Spiderbasic App)
`lweb::MapToJSONString(Map ConvertMap.s())`

Gibt einen String zurück.

Beispiel:
```
  Response(lhs_web::#cha_R_ResponseContentType) = lhs_web::#response_string
  Response(lhs_web::#cha_R_StringBase64) = Encoded
  Response(lhs_web::#cha_R_ResponseType) = lhs_web::mimetype("html")
  Response(lhs_web::#cha_R_http_head_status) = "200 OK"
  ZumSenden = lhs_web::MapToJSONString(Response())
```
  
Ergib anschliessend einen String der wieder Zurückkonvertiert werden kann von der Hauptbearbeitungsprozedur (Client Thread in lweb.pbi).

### Verifizierung ob es eine Gültige IP Adresse ist (IPv6 und IPv4)
`lweb::IsIPStringValid(Adress.s)`

Beispiel: 
```
setting = "192.168.256.12"
If lweb::IsIPStringValid(setting)
    conf_binding = setting
Else
    ; Fehler
    conf_binding = "127.0.0.1"
EndIf
```
ergibt einen Fehler und wird die Standard IP Setzen.

Rückgabewert ist `#True` oder `#False.`
Initial commit 2020-10-28 14:24:53 +01:00			`# lweb`

Dokumentation erstellt. Falsch benante Prozedur gändert: MapStringToJSONString -> MapToJSONString 2020-11-13 10:32:09 +01:00			`LiHaSo Webserver Modul`

			`## Öffentliche Funktionen:`

			`### Konfiguration des Server Moduls:`

			`Mögliche Parameter:`
			```
			`lweb::#conf_port ;Hörender Port, z.B. "80"`
			`lweb::#conf_binding ;Interface Binding z.B. nur Lokalhost mit "127.0.0.1"`
			`lweb::#conf_defaultfile ;Standard wenn keine Datei (Extension angegeben ist) z.B. "index.php"`
			`lweb::#conf_basedir ;Standard Verzeichnis z.B. "/srv/www/htdocs/"`
			`lweb::#conf_error400 ;TODO:error400 bearbeitung`
			`lweb::#conf_max_clients ;Maximale Clientconnections (Memory beachten)`
			`lweb::#conf_server_type ;Derzeit ohne Funktion (Später z.B. HTTPS und HTTP oder HTTP/2 usw.)`
			`lweb::#conf_cache_enable ;Bei wert auf 1 Setzen um zu Aktivieren diese Funktion ist aber derzeit mit Vorsicht zu geniessen!!!!`
			```

			`#### Funktionen`
			`lweb::set_config(parameter.i=#conf_defaultfile, setting.s="index.html")`

			`Dass setting ist immer ein String.`

			Rückgabewert ist `#True` oder `#False.`


			`lweb::get_config(parameter.i=#conf_defaultfile)`

			`Der Rückgabewert ist immer einen String.`

			`### Starten des Servers`
			`lweb::start_server()`

			Rückgabewert ist `#True` oder `#False.`

			`### Verschiedene arten des Handlers Registrieren & Proceduren:`

			`lweb::register_client_handler(Route.s, Callback.i, AppPrototype.i = #handler_proto_get, RouteType.i = #handler_sub)`

			`Rückgabewerte ist immer ein JSONString!`

			`AppPrototype Möglichkeiten:`
			```
			`lweb::#handler_proto_universal ;Für HTTP POST und GET Requests Nimmt Optional einen String entgegen.`
			`lweb::#handler_proto_post ;Nur für HTTP POST Requests Nimmt Zwingend einen String entgegen.`
			`lweb::#handler_proto_get ;Nur für HTTP GET Requests Nimmt keinen String entgegen.`
			```

			`RouteType Möglichkeiten:`
			```
			`lweb::#handler_only ;Reagiert nur auf die Url (Bsp. /rest/v1/test aber nicht auf /rest/v1/test/sub)`
			`lweb::#handler_sub ;Reagiert auf eine ganze Url die begint. (Bsp. /rest/v1/test sowie auch auf /rest/v1/test/sub)`
			`lweb::#handler_type ;Reagiert auf datentypen (zb. *.php = "php")`
			```

			`Map für Antwort ist eine einfache Stringmap:`
			`NewMap Response.s()`

			`Wobei folgende werte entsprechend gesetzt werden müssen:`
			* `lweb::#cha_R_ResponseType = "ResponseType"` ;Element ResponseType,Mimetype mit `lweb::mimetype("html")` z.B. Setzen.
			* `lweb::#cha_R_ResponseContentType = "ResponseContentType"` ;Element ResponseContentType, `lweb::#response_string` oder `lweb::#response_Memory`
			* `lweb::#cha_R_MemoryAdress = "MemoryAdress"` ;Element MemoryAdress, Konvertieren zu String `Str(Adresse)` wird mit `Val()` zurückkonvertiert. Und nach dem Bearbeiten wieder freigegeben!
			* `lweb::#cha_R_MemorySize = "MemorySize"` ;Element MemorySize, Konvertieren zu String `Str(Grösse)` wird mit `Val()` zurückkonvertiert.
			* `lweb::#cha_R_StringBase64 = "StringBase64"` ;Element StringBase64, Base64 Encoded String
			* `lweb::#cha_R_http_head_status = "HeaderStatus"` ;`"200 OK"`, `"300 Error"`, `"500 Server Error"` usw.

			`Zu beachten ist das entweder ein Base64 encodierter String oder ein MemoryBlock zurückgegeben werden muss!`

			`Komplettes Beispiel:`
			```
			`Procedure.s Sample_Header(Map Header.s())`
			`Define *Text`
			`Define.s Encoded, ZumSenden, TBD`
			`NewMap Response.s()`
			`TBD="<div><div><h1>Header</h1></div><br/>"+#CRLF$`
			`ResetMap(Header())`
			`While NextMapElement(Header())`
			`TBD = TBD+"<div>"+MapKey(Header())+" : "+Header()+" </div><br/>"+#CRLF$`
			`Wend`

			`*Text = UTF8("<!DOCTYPE html><html><header><title>Alle Client Headers</title></header><body>"+TBD+"</body></html>")`
			`Encoded = Base64Encoder(Text, MemorySize(Text))`
			`Debug "Encoded: " + Encoded`
			`Response(lhs_web::#cha_R_ResponseContentType) = lhs_web::#response_string`
			`Response(lhs_web::#cha_R_StringBase64) = Encoded`
			`Response(lhs_web::#cha_R_ResponseType) = lhs_web::mimetype("html")`
			`Response(lhs_web::#cha_R_http_head_status) = "200 OK"`
			`ZumSenden = lhs_web::MapToJSONString(Response())`
			`Debug "ZumSenden: " + ZumSenden`
			`ProcedureReturn ZumSenden`
			`EndProcedure`

			`lhs_web::register_client_handler("/server/show_client_headers", @Sample_Header(),lhs_web::#handler_proto_get, lhs_web::#handler_sub)`
			```

			`### Einen Mimetype eines Fileextensions:`
			`lweb::mimetype(file.s)`

			`Gibt einen String zurück.`

			Konvertiert z.B. `lweb::mimetype("html")` zu `"text/html"`

			`### Eine Map in einen JSONString Konvertieren (z.B. in Interaktion mit einer Spiderbasic App)`
			`lweb::MapToJSONString(Map ConvertMap.s())`

			`Gibt einen String zurück.`

			`Beispiel:`
			```
			`Response(lhs_web::#cha_R_ResponseContentType) = lhs_web::#response_string`
			`Response(lhs_web::#cha_R_StringBase64) = Encoded`
			`Response(lhs_web::#cha_R_ResponseType) = lhs_web::mimetype("html")`
			`Response(lhs_web::#cha_R_http_head_status) = "200 OK"`
			`ZumSenden = lhs_web::MapToJSONString(Response())`
			```

			`Ergib anschliessend einen String der wieder Zurückkonvertiert werden kann von der Hauptbearbeitungsprozedur (Client Thread in lweb.pbi).`

			`### Verifizierung ob es eine Gültige IP Adresse ist (IPv6 und IPv4)`
			`lweb::IsIPStringValid(Adress.s)`

			`Beispiel:`
			```
			`setting = "192.168.256.12"`
			`If lweb::IsIPStringValid(setting)`
			`conf_binding = setting`
			`Else`
			`; Fehler`
			`conf_binding = "127.0.0.1"`
			`EndIf`
			```
			`ergibt einen Fehler und wird die Standard IP Setzen.`

			Rückgabewert ist `#True` oder `#False.`