[mod] conf:extension dvn [mod] readme

conf/example.json

@@ -1,17 +0,0 @@
-{
-	"auth": {
-		"kind": "none",
-		"data": null
-	},
-	"source": {
-		"kind": "ics_feed",
-		"data": {
-			"url": "https://www.phpclasses.org/browse/download/1/file/63438/name/example.ics",
-			"combine": true
-		}
-	},
-	"settings": {
-		"timezone": "UTC"
-	}
-}
-

conf/zeitbild.json

@@ -1,17 +0,0 @@
-{
-	"auth": {
-		"kind": "basic",
-		"data": null
-	},
-	"source": {
-		"kind": "ics_feed",
-		"data": {
-			"url": "http://{{username}}:{{password}}@localhost:7845/export/ics",
-			"combine": true
-		}
-	},
-	"settings": {
-		"timezone": "UTC"
-	}
-}
-

misc/conf-example.dvn.json

@@ -0,0 +1,23 @@
+{
+	"realms": [
+		{
+			"name": "holidays",
+			"auth": {
+				"kind": "static",
+				"data": {
+					"password": "secret"
+				}
+			},
+			"source": {
+				"kind": "ics_feed",
+				"data": {
+					"url": "https://www.kayaposoft.com/enrico/ics/v2.0?country=nor&fromDate=01-01-2025&toDate=31-12-2026&region=&holidayType=public_holiday&lang=no"
+				}
+			}
+		}
+	],
+	"settings": {
+		"timezone": "UTC"
+	}
+}
+

readme.md

@@ -2,7 +2,7 @@
 
 ## Beschreibung
 
-- stellt Kalender-Daten in Form eines CalDAV-Servers bereit
+- bereitet rohe Kalender-Daten aus verschiedenen Quellen mittels CalDAV auf und stellt diese als Server bereit
 - basiert auf [sabre/dav](https://sabre.io/dav/)
 
 
@@ -30,7 +30,11 @@
 Zum lokalen Testen:
 
 - im build-Verzeichnis `php -S localhost:8000` ausführen
-- im Browser `http://localhost:8000/` aufrufen
+- CalDAV-Client einrichten mit Ziel-URL
+	- URL: `http://localhost:8000/calendars/-/rides`
+	- Nutzername: `<realm-name>`
+	- Passwort: ``
+
 
 Für den Produktiv-Betrieb:
 
@@ -38,3 +42,98 @@ Für den Produktiv-Betrieb:
 - Web-Server neustarten
 
 
+## Dokumentation
+
+Der grobe Aufbau einer Konfigurations-Datei lässt sich in der [Beispiel-Konfiguration](misc/conf-example.dvn.json) sehen.
+
+
+### Bezüge
+
+_Bezüge_/_Realms_ dienen die Daten-Quellen. Sie sind in der Konfiguration im Knoten `realms` zu erfassen. Jeder Bezug hat:
+- einen Namen (`name`),
+- eine Zugangs-Definition (`auth`)
+- eine Quell-Definition (`source`)
+
+Beispiel:
+
+```json
+"realms": [
+    {
+		"name": "foo",
+		"auth": …
+		"source": …
+	},
+	{
+		"name": "bar",
+		"auth": …
+		"source": …
+	}
+]
+…
+```
+
+### Authentifizierungen
+
+_Authentifizierungen_ steuern wie auf einen Bezug zugegriffen wird.
+
+
+#### Fest
+
+- es wird ein festes Passwort erwartet
+- Beispiel:
+
+```json
+"auth": {
+	"kind": "static",
+	"data": {
+		"password": "secret"
+	}
+}
+```
+
+
+#### Durchleiten
+
+- es wird kein bestimmtes Passwort erwartet
+- das eingegebene Passwort wird an den Aufruf der Quelle weitergeleitet
+- Beispiel:
+
+```json
+"auth": {
+	"kind": "pass_through"
+}
+```
+
+
+### Quellen
+
+_Quellen_ sind die Stellen, die aufgerufen werden um die rohen Kalender-Daten zu erhalten.
+
+
+#### ICS-Feed
+
+Kalender-Daten, welche im [iCalendar](https://de.wikipedia.org/wiki/ICalendar)-Format `ics` vorliegen, können wie folgt eingebunden werden:
+
+
+```json
+"source" :{
+	"kind": "ics_feed",
+	"data": {
+		"url": "https://events.example.org/concerts.ics",
+		"conflate": true
+	}
+}
+```
+
+`url` ist hierbei schlicht die URL zur `ics`-Datei. Diese kann man den Platzhaltern `{{username}}` und `{{password}}` versehen sein. Im Fall einer Authentifizierung mittels Durchleiten, werden diese Platzhalter durch die konkret vorliegenden Werte ersetzt.
+
+Der Schalter `conflate` steuert, ob die erhaltenen Termine in einen Kalender zusammengefasst werden sollen, statt sie gemäß ihrer `VEVENT`-Feld-Werte `CATEGORIES` aufzutrennen. Das hat Auswirkungen auf die URL, die man im CalDAV-Client einstellen muss. Kommen in einer `ics`-Datei bspw. die `CATEGORIES`-Werte `day` und `night` vor und der Bezug hat den Name `music`, dann würden bei `"conflate": false` die Ziel-URL-Pfade `/calendars/-/music-day` und `/calendars/-/music-night` anliegen; bei `"conflate": true` nur `/calendars/-/music`.
+
+
+### Angaben für Clients
+
+- Kalender-URL: `<url-base>/calendars/-/<realm-name>[-<calendar-name>]`
+- Nutzername: `<realm-name>[-<auth-username>]`
+- Passwort: `<auth-password>`
+
+

source/main.php

@@ -18,7 +18,7 @@ require_once(DIR_LOGIC . '/conf.php');
 function main(
 ) : void
 {
-	\davina\conf\load('conf.json');
+	\davina\conf\load('conf.dvn.json');
 	
 	\davina\set_parameters([]);
 	

tools/build

@@ -81,7 +81,7 @@ def main():
 		else:
 			_shutil.copy(
 				args.conf_path,
-				_os.path.join(args.output_directory, "conf.json")
+				_os.path.join(args.output_directory, "conf.dvn.json")
 			)
 	print(args.output_directory)