From 38a396ee4984f2d794010cf691554541b319ab1b Mon Sep 17 00:00:00 2001 From: Fenris Wolf Date: Mon, 22 Sep 2025 20:08:05 +0200 Subject: [PATCH] [mod] conf:extension dvn [mod] readme --- conf/example.json | 17 ------ conf/zeitbild.json | 17 ------ misc/conf-example.dvn.json | 23 +++++++++ readme.md | 103 ++++++++++++++++++++++++++++++++++++- source/main.php | 2 +- tools/build | 2 +- 6 files changed, 126 insertions(+), 38 deletions(-) delete mode 100644 conf/example.json delete mode 100644 conf/zeitbild.json create mode 100644 misc/conf-example.dvn.json diff --git a/conf/example.json b/conf/example.json deleted file mode 100644 index 7721c6c..0000000 --- a/conf/example.json +++ /dev/null @@ -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" - } -} - diff --git a/conf/zeitbild.json b/conf/zeitbild.json deleted file mode 100644 index bd843d6..0000000 --- a/conf/zeitbild.json +++ /dev/null @@ -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" - } -} - diff --git a/misc/conf-example.dvn.json b/misc/conf-example.dvn.json new file mode 100644 index 0000000..2ae362f --- /dev/null +++ b/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®ion=&holidayType=public_holiday&lang=no" + } + } + } + ], + "settings": { + "timezone": "UTC" + } +} + diff --git a/readme.md b/readme.md index 2fc1434..30db4d7 100644 --- a/readme.md +++ b/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: `` + - 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: `/calendars/-/[-]` +- Nutzername: `[-]` +- Passwort: `` + + diff --git a/source/main.php b/source/main.php index 9913ac9..016d261 100644 --- a/source/main.php +++ b/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([]); diff --git a/tools/build b/tools/build index 6ea28b5..594ab68 100755 --- a/tools/build +++ b/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)