hivedav

commit 0e797f86b169a64cb13b2ccef50c777aef6a6c79
parent 5d161d37264a625407510bf3092fdc7d40c447d2
Author: Andreas Gruhler <andreas.gruhler@adfinis.com>
Date:   Sun, 16 Jun 2024 11:13:06 +0200

doc(caldav): improve flow example

Diffstat:
M
docs/CALDAV.md
 | 
85
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----------

1 file changed, 75 insertions(+), 10 deletions(-)
diff --git a/docs/CALDAV.md b/docs/CALDAV.md
@@ -7,18 +7,83 @@ CalDav request flow is as follows:
 3. Get calendar from home set
 4. Fetch all events from calendar and sync availability
 
-To debug the flow, use the xml snippets from the code and curl. Example:
-```
-curl -XPROPFIND -H "Content-Type: text/xml" \
- --data-binary "@query.xml" -u '$user:$pass' \
- https://caldav.gmx.net/begenda/dav/users/
-```
+To debug the flow, use the xml snippets from the code and curl.
 
-## Tested clients
+## Tested providers
+* GMX
+  - discovery with `HIVEDAV_CALDAV_HOST` does not work, use direct link to
+    calendar uri (`HIVEDAV_CALDAV_URI`)
+  - example:
+    `HIVEDAV_CALDAV_URI=https://caldav.gmx.net/begenda/dav/$PRINCIPAL/calendar`
+  - https://hilfe.gmx.net/kalender/mobil/apps.html
+* Yahoo
+  - works with `HIVEDAV_CALDAV_HOST` automatic discovery or direct calendar uri
+    using `HIVEDAV_CALDAV_URI`
+  - create app password for `HIVEDAV_CALDAV_PASSWORD` at
+    https://login.yahoo.com/myaccount/security/app-password
+  - example 1: `HIVEDAV_CALDAV_HOST=https://caldav.calendar.yahoo.com` and
+    `HIVEDAV_CALENDAR=1`
+  - example 2:
+    `HIVEDAV_CALDAV_URI=https://caldav.calendar.yahoo.com/dav/$PRINCIPAL/Calendar/$CALENDAR_ID`
+  - https://help.yahoo.com/kb/SLN4707.html
 * Kopano (with calendar discovery, use `HIVEDAV_CALDAV_HOST`)
   - example: `HIVEDAV_CALDAV_HOST=https://mail.server.com:8443`
   - https://documentation.kopano.io/user_manual_kopanocore/configure_caldav_clients.html
-* GMX (with calendar direct uri to calendar, use `HIVEDAV_CALDAV_URI`)
-  - example: `HIVEDAV_CALDAV_URI=https://caldav.gmx.net/begenda/dav/00000000-0000-0000-0000-000000000000/calendar`
-  - https://hilfe.gmx.net/kalender/mobil/apps.html
 
+If you are unsure on how to retrieve the `HIVEDAV_CALDAV_URI` for a specific
+provider, follow the example flow below to manually discover a particular
+calendar CalDav uri.
+
+## Generic flow example
+These curl commands depict the request flow from the Go code and should work
+with any provider.
+
+First, read the principal:
+```
+cat <<EOF | curl -s -d @- -XPROPFIND -H "Content-Type: text/xml" -H "Depth: 0" \
+  -u '$USER:$PASSWORD' $CALDAV_HOST | xmllint --format -
+<d:propfind xmlns:d="DAV:">
+ <d:prop>
+  <d:current-user-principal />
+ </d:prop>
+</d:propfind>
+EOF
+```
+The principal path (`$PRINCIPAL`) is returned in the XML response tag
+`<DAV:current-user-principal>`. For some providers, `$CALDAV_HOST` has a
+special prefix (such as `/begenda/dav/users` for GMX, read the 302 redirect
+location with curl).
+
+Get calendar home set for the principal:
+```
+cat <<EOF | curl -s -d @- -XPROPFIND -H "Content-Type: text/xml" -H "Depth: 0" \
+  -u '$USER:$PASSWORD' $CALDAV_HOST/$PRINCIPAL | xmllint --format -
+<d:propfind xmlns:d="DAV:" xmlns:c="urn:ietf:params:xml:ns:caldav">
+ <d:prop>
+  <c:calendar-home-set />
+ </d:prop>
+</d:propfind>
+EOF
+```
+
+The users calendar home set `$HOME_SET` is returned in the
+`<calendar-home-set>` XML tag.
+
+This home set contains all calendars of the user. Finally, to list the
+calendars (`HIVEDAV_CALDAV_URI`):
+```
+cat <<EOF | curl -s -d @- -XPROPFIND -H "Content-Type: text/xml" -H "Depth: 1" \
+  -u '$USER:$PASSWORD' $CALDAV_HOST/$HOME_SET | xmllint --format -
+<d:propfind xmlns:d="DAV:" xmlns:cs="http://calendarserver.org/ns/" xmlns:c="urn:ietf:params:xml:ns:caldav">
+ <d:prop>
+  <d:resourcetype />
+  <d:displayname />
+  <cs:getctag />
+  <c:supported-calendar-component-set />
+ </d:prop>
+</d:propfind>
+EOF
+```
+
+Choose a calendar CalDav URI (`HIVEDAV_CALDAV_URI`) to sync with a particular
+calendar.