├── .gitignore
├── xml
    ├── validate.sh
    ├── push-message-vapid-key.xml
    ├── sample-push-message.xml
    ├── sample-push-register.xml
    ├── sample-propfind-multistatus.xml
    ├── validate-samples.rng
    └── webdav-push.rng
├── abstract.md
├── .github
    └── workflows
    │   ├── validate-samples.yml
    │   ├── build-rfc.yml
    │   └── dependent-issues.yml
├── webdav-push.mkd
├── README.md
└── content.mkd


/.gitignore:
--------------------------------------------------------------------------------
1 | .idea/
2 | .obsidian/
3 | .refcache/
4 | build/
5 | 


--------------------------------------------------------------------------------
/xml/validate.sh:
--------------------------------------------------------------------------------
1 | #!/bin/sh
2 | 
3 | xmlstarlet val -e -r validate-samples.rng *.xml
4 | 


--------------------------------------------------------------------------------
/xml/push-message-vapid-key.xml:
--------------------------------------------------------------------------------
1 | <?xml version="1.0" encoding="utf-8" ?>
2 | <push-message xmlns="https://bitfire.at/webdav-push" xmlns:D="DAV:">
3 |   <property-update>
4 |     <D:prop>
5 |       <transports />
6 |     </D:prop>
7 |   </property-update>
8 | </push-message>
9 | 


--------------------------------------------------------------------------------
/abstract.md:
--------------------------------------------------------------------------------
1 | This document specifies a mechanism to timely notify WebDAV clients when the content or properties of a resource or its members are changed on the WebDAV server.
2 | 
3 | As a transport for such push notifications, it only specifies Web Push (RFC 8030). It can however by design be used with other transports as well.
4 | 


--------------------------------------------------------------------------------
/xml/sample-push-message.xml:
--------------------------------------------------------------------------------
1 | <?xml version="1.0" encoding="utf-8" ?>
2 | <push-message xmlns="https://bitfire.at/webdav-push" xmlns:D="DAV:">
3 |   <topic>O7M1nQ7cKkKTKsoS_j6Z3w</topic>
4 |   <content-update>
5 |     <D:sync-token>http://example.com/sync/10</D:sync-token>
6 |   </content-update>
7 |   <property-update />
8 | </push-message>
9 | 


--------------------------------------------------------------------------------
/.github/workflows/validate-samples.yml:
--------------------------------------------------------------------------------
 1 | name: Validate XML samples
 2 | on: push
 3 | 
 4 | jobs:
 5 |   validate:
 6 |     name: Validate XML samples
 7 |     runs-on: ubuntu-latest
 8 |     steps:
 9 |       - uses: actions/checkout@v4
10 |       - run: sudo apt-get update && sudo apt-get install -q xmlstarlet
11 |       - run: (cd xml; ./validate.sh)
12 | 
13 | 


--------------------------------------------------------------------------------
/xml/sample-push-register.xml:
--------------------------------------------------------------------------------
 1 | <push-register xmlns="https://bitfire.at/webdav-push" xmlns:D="DAV:">
 2 |   <subscription>
 3 |     <web-push-subscription>
 4 |       <push-resource>https://up.example.net/yohd4yai5Phiz1wi</push-resource>
 5 |       <content-encoding>aes128gcm</content-encoding>
 6 |       <subscription-public-key type="p256dh">BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcxaOzi6-AYWXvTBHm4bjyPjs7Vd8pZGH6SRpkNtoIAiw4</subscription-public-key>
 7 |       <auth-secret>BTBZMqHH6r4Tts7J_aSIgg</auth-secret>
 8 |     </web-push-subscription>
 9 |   </subscription>
10 |   <trigger>
11 |     <content-update>
12 |       <D:depth>infinity</D:depth>
13 |     </content-update>
14 |     <property-update>
15 |       <D:depth>0</D:depth>
16 |       <D:prop>
17 |         <D:displayname/>
18 |         <D:owner/>
19 |       </D:prop>
20 |     </property-update>
21 |   </trigger>
22 |   <expires>Wed, 20 Dec 2023 10:03:31 GMT</expires>
23 | </push-register>
24 | 


--------------------------------------------------------------------------------
/xml/sample-propfind-multistatus.xml:
--------------------------------------------------------------------------------
 1 | <multistatus xmlns="DAV:" xmlns:P="https://bitfire.at/webdav-push">
 2 |   <response>
 3 |     <href>/webdav/collection/</href>
 4 |     <prop>
 5 |       <P:transports>
 6 |         <P:web-push>
 7 |           <P:vapid-public-key type="p256ecdsa">BA1Hxzyi1RUM1b5wjxsn7nGxAszw2u61m164i3MrAIxHF6YK5h4SDYic-dRuU_RCPCfA5aq9ojSwk5Y2EmClBPs</P:vapid-public-key>
 8 |         </P:web-push>
 9 |         <!-- Not covered by this document:
10 |         <X:some-other-transport>
11 |           <X:some-parameter>...</X:some-parameter>
12 |         </X:some-other-transport>
13 |         -->
14 |       </P:transports>
15 |       <P:topic>O7M1nQ7cKkKTKsoS_j6Z3w</P:topic>
16 |       <P:supported-triggers>
17 |         <P:content-update>
18 |           <depth>1</depth>
19 |         </P:content-update>
20 |         <P:property-update>
21 |           <depth>0</depth>
22 |         </P:property-update>
23 |       </P:supported-triggers>
24 |     </prop>
25 |   </response>
26 | </multistatus>
27 | 


--------------------------------------------------------------------------------
/xml/validate-samples.rng:
--------------------------------------------------------------------------------
 1 | <grammar xmlns="http://relaxng.org/ns/structure/1.0">
 2 | 
 3 |   <!-- root elements of examples in document -->
 4 |   <start>
 5 |     <choice>
 6 |       <ref name="multistatus"/>
 7 |       <ref name="subscription-registration"/>
 8 |       <ref name="push-message"/>
 9 |       <ref name="web-push-subscription"/>
10 |     </choice>
11 |   </start>
12 | 
13 |   <define name="multistatus" ns="DAV:">   <!-- defined in WebDAV, here only for valiation of samples -->
14 |     <element name="multistatus">
15 |       <element name="response">
16 |         <element name="href">
17 |           <text/>
18 |         </element>
19 |         <element name="prop">
20 |           <interleave>
21 |             <ref name="prop-transports"/>
22 |             <ref name="prop-topic"/>
23 |             <ref name="prop-supported-triggers"/>
24 |           </interleave>
25 |         </element>
26 |       </element>
27 |     </element>
28 |   </define>
29 | 
30 |   <include href="webdav-push.rng"/>
31 | 
32 | </grammar>
33 | 


--------------------------------------------------------------------------------
/webdav-push.mkd:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Push for WebDAV (WebDAV-Push)
 3 | abbrev: WebDAV-Push
 4 | docname: draft-bitfire-webdav-push-00
 5 | category: exp
 6 | 
 7 | submissionType: independent
 8 | ipr: none
 9 | workgroup: Independent submission
10 | keyword: WebDAV
11 | keyword: push
12 | 
13 | stand_alone: yes
14 | pi: [toc, sortrefs, symrefs]
15 | 
16 | author:
17 |  -
18 |     ins: R. Hirner
19 |     name: Ricki Hirner
20 |     organization: bitfire web engineering GmbH
21 |     abbrev: bitfire.at
22 |     street: Florastraße 27
23 |     city: Bad Vöslau
24 |     code: 2540
25 |     country: Austria
26 |     email: hirner@bitfire.at
27 | 
28 | normative:
29 |   RELAXNG:
30 |     title: "RELAX NG Specification"
31 |     author:
32 |       org: The Organization for the Advancement of Structured Information Standards
33 |     date:
34 |       3 December 2001
35 |     target: https://relaxng.org/spec-20011203.html
36 |   RFC4918:
37 |   RFC6578:
38 |   RFC8030:
39 |   RFC8291:
40 |   RFC8292:
41 |   RFC9110:
42 |   RFC9111:
43 | 
44 | informative:
45 |   RFC3744:
46 |   RFC4791:
47 |   RFC6352:
48 |   RFC6638:
49 |   UnifiedPush:
50 |     title: UnifiedPush
51 |     target: https://unifiedpush.org
52 |     date: false
53 | 
54 | 
55 | --- abstract
56 | 
57 | {::include abstract.md}
58 | 
59 | 
60 | --- middle
61 | 
62 | {::include-nested content.mkd}
63 | 


--------------------------------------------------------------------------------
/.github/workflows/build-rfc.yml:
--------------------------------------------------------------------------------
 1 | name: Build and publish document
 2 | on: push
 3 | 
 4 | # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 5 | permissions:
 6 |   contents: read
 7 |   pages: write
 8 |   id-token: write
 9 | 
10 | jobs:
11 |   build:
12 |     name: Generate HTML/TXT
13 |     runs-on: ubuntu-latest
14 |     steps:
15 |       - uses: actions/checkout@v4
16 |       - uses: actions/cache@v4
17 |         with:
18 |           path: |
19 |             $HOME/.local/share/gem
20 |             .refcache
21 |           key: webdav-push.mkd
22 | 
23 |       - name: Install packages
24 |         run: >
25 |           sudo apt-get install --no-install-recommends -y golang-go &&
26 |           sudo gem install kramdown-rfc &&
27 |           sudo pip3 install svgcheck xml2rfc --break-system-packages &&
28 |           go install github.com/blampe/goat/cmd/goat@latest && echo ~/go/bin >> $GITHUB_PATH
29 | 
30 |       - name: Prepare output directory
31 |         run: mkdir build
32 | 
33 |       - name: Kramdown to XML
34 |         run: kramdown-rfc2629 webdav-push.mkd >build/draft-bitfire-webdav-push-00.xml
35 | 
36 |       - name: XML to HTML
37 |         run: (cd build; xml2rfc --html draft-bitfire-webdav-push-00.xml)
38 |       - name: XML to TXT
39 |         run: (cd build; xml2rfc --text draft-bitfire-webdav-push-00.xml)
40 | 
41 |       - uses: actions/upload-pages-artifact@v3
42 |         with:
43 |           path: build
44 | 
45 |   deploy:
46 |     if: github.ref == 'refs/heads/main'
47 |     environment:
48 |       name: github-pages
49 |       url: ${{ steps.deployment.outputs.page_url }}
50 |     runs-on: ubuntu-latest
51 |     needs: build
52 |     steps:
53 |       - name: Deploy to GitHub Pages
54 |         id: deployment
55 |         uses: actions/deploy-pages@v4
56 | 


--------------------------------------------------------------------------------
/.github/workflows/dependent-issues.yml:
--------------------------------------------------------------------------------
 1 | name: Dependent Issues
 2 | 
 3 | on:
 4 |   issues:
 5 |     types:
 6 |       - opened
 7 |       - edited
 8 |       - closed
 9 |       - reopened
10 |   pull_request_target:
11 |     types:
12 |       - opened
13 |       - edited
14 |       - closed
15 |       - reopened
16 |       # Makes sure we always add status check for PRs. Useful only if
17 |       # this action is required to pass before merging. Otherwise, it
18 |       # can be removed.
19 |       - synchronize
20 | 
21 |   # Schedule a daily check. Useful if you reference cross-repository
22 |   # issues or pull requests. Otherwise, it can be removed.
23 |   schedule:
24 |     - cron: '12 9 * * *'
25 | 
26 | permissions: write-all
27 | 
28 | jobs:
29 |   check:
30 |     runs-on: ubuntu-latest
31 |     steps:
32 |       - uses: z0al/dependent-issues@v1
33 |         env:
34 |           # (Required) The token to use to make API calls to GitHub.
35 |           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
36 |           # (Optional) The token to use to make API calls to GitHub for remote repos.
37 |           GITHUB_READ_TOKEN: ${{ secrets.DEPENDENT_ISSUES_READ_TOKEN }}
38 | 
39 |         with:
40 |           # (Optional) The label to use to mark dependent issues
41 |           # label: dependent
42 | 
43 |           # (Optional) Enable checking for dependencies in issues.
44 |           # Enable by setting the value to "on". Default "off"
45 |           check_issues: on
46 | 
47 |           # (Optional) A comma-separated list of keywords. Default
48 |           # "depends on, blocked by"
49 |           keywords: depends on, blocked by
50 | 
51 |           # (Optional) A custom comment body. It supports `{{ dependencies }}` token.
52 |           comment: >
53 |             This PR/issue depends on:
54 | 
55 |             {{ dependencies }}
56 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | [![Specification: HTML](https://img.shields.io/badge/preview-html-brightgreen)](https://bitfireat.github.io/webdav-push/draft-bitfire-webdav-push-00.html)
 2 | [![Specification: TXT](https://img.shields.io/badge/preview-txt-brightgreen)](https://bitfireat.github.io/webdav-push/draft-bitfire-webdav-push-00.txt)
 3 | [![Matrix](https://img.shields.io/matrix/webdav-push:matrix.org)](https://matrix.to/#/#webdav-push:matrix.org)
 4 | [![GitHub Discussions](https://img.shields.io/github/discussions/bitfireAT/webdav-push)](https://img.shields.io/github/discussions/bitfireAT/webdav-push)
 5 | 
 6 | 
 7 | # The WebDAV Push project
 8 | 
 9 | **View the current specification draft (in work):**
10 | 
11 | * [HTML](https://bitfireat.github.io/webdav-push/draft-bitfire-webdav-push-00.html)
12 | * [TXT](https://bitfireat.github.io/webdav-push/draft-bitfire-webdav-push-00.txt)
13 | 
14 | These documents are [automatically compiled](https://github.com/bitfireAT/webdav-push/blob/main/.github/workflows/build-rfc.yml) from the source (kramdown-rfc):
15 | 
16 | * [metadata](https://github.com/bitfireAT/webdav-push/blob/main/webdav-push.mkd)
17 | * [content](https://github.com/bitfireAT/webdav-push/blob/main/content.mkd)
18 | 
19 | ---
20 | 
21 | ## Motivation
22 | 
23 | WebDAV is an open HTTP- and XML- based protocol that is widely adopted and can be used for remote file access (read/write). It has a wide range of usages from browsing folders and uploading files over the Internet with a desktop or mobile file manager (like FTP, but better) to specific protocols that define their own properties and use (virtual) files for data exchange.
24 | 
25 | Two of these specific WebDAV-based protocols are CalDAV and CardDAV. They allow to access calendars (events, tasks, journal entries, free/busy information, …) and contacts in a standardized way. Because they're open standards, a lot of different servers and clients can be used to work together (no vendor lock-in).
26 | 
27 | However, these protocols don't come with support for "Push", so there's no way for servers to notify clients about new/updated data. So,
28 | 
29 | - a file manager won't update its view of a folder automatically when a file in this folder is added/changed/removed, and
30 | - a CalDAV/CardDAV client has to ask the server for changes in regular intervals (polling), which causes unnecessary server load, bad user experience and useless energy usage (especially bad for mobile devices).
31 | 
32 | WebDAV is however extensible and it's possible to add new properties and mechanisms to it. So we want to create WebDAV-Push, so that users can receive updated data whenever they're available.
33 | 
34 | **This is especially important for CalDAV/CardDAV, where we want to bring (near-)real-time synchronization** (which is nowadays industry standard for proprietary protocols) also to CalDAV/CardDAV clients.
35 | 
36 | 
37 | ## How
38 | 
39 | Our goal is to draft a document defining WebDAV Push.
40 | 
41 | It will be mainly based on Web Push (RFC 8030), but open for other push transports.
42 | 
43 | Currently, the main organizations / people behind WebDAV Push are:
44 | 
45 | - [@bitfireAT](https://github.com/bitfireAT) (developers of [DAVx⁵](https://github.com/bitfireAT/davx5-ose)) – very interested in developing Push for WebDAV, especially CalDAV/CardDAV
46 | - [@verdigado](https://github.com/verdigado) – interested in using CalDAV/CardDAV push
47 | 
48 | The plan is to
49 | 
50 | - [draft a specification](content.md),
51 | - make a [first server-side implementation](https://github.com/bitfireAT/nc_ext_dav_push) for [@Nextcloud](https://github.com/nextcloud) (who are interested in supporting that) – it's in development and can already be used for demonstration purposes,
52 | - make a first client-side implementation for DAVx⁵ – basic support for demonstration purposes is also already available in the lastest releases,
53 | - ensure that it's usable with [@UnifiedPush](https://github.com/UnifiedPush) (because there's already much awesome open technology available).
54 | 
55 | A lot of people have shown their interest in WebDAV-Push. Thank you for all ideas and encouragement!
56 | 
57 | 
58 | ## Contact
59 | 
60 | If you're interested:
61 | 
62 | - have a look at the [specification draft](https://bitfireat.github.io/webdav-push/draft-bitfire-webdav-push-00.html) and tell us your ideas
63 | - take part in our [Discussions](https://github.com/bitfireAT/webdav-push/discussions) – feel free to create new topics with your ideas, questions, what you would love to see, …
64 | - join our Matrix channel: [#webdav-push:matrix.org](https://matrix.to/#/#webdav-push:matrix.org)
65 | - watch [@davx5@fosstodon.org](https://fosstodon.org/@davx5app), where we sometimes post Push-related news too
66 | 
67 | We would love to see some activity!
68 | 
69 | 
70 | ## Repo organization
71 | 
72 | The repository contains:
73 | 
74 | - **a [specification draft](https://bitfireat.github.io/webdav-push/draft-bitfire-webdav-push-00.html) describing our current idea of WebDAV-Push** (see above)
75 | - discussion and exchange about the WebDAV Push topic (in [Discussions](https://github.com/bitfireAT/webdav-push/discussions))
76 | - specific tasks (in [Issues](https://github.com/bitfireAT/webdav-push/issues)) and related patches (in [Pull requests](https://github.com/bitfireAT/webdav-push/pulls))
77 | 
78 | 


--------------------------------------------------------------------------------
/xml/webdav-push.rng:
--------------------------------------------------------------------------------
  1 | <grammar xmlns="http://relaxng.org/ns/structure/1.0" ns="https://bitfire.at/webdav-push">
  2 | 
  3 |   <!-- new WebDAV collection properties -->
  4 | 
  5 |   <!-- available push transports -->
  6 |   <define name="prop-transports">
  7 |     <element name="transports">
  8 |       <choice>
  9 |         <ref name="web-push-transport"/>
 10 |         <!-- or other transport, not covered by this schema -->
 11 |       </choice>
 12 |     </element>
 13 |   </define>
 14 | 
 15 |   <!-- push topic -->
 16 |   <define name="prop-topic">
 17 |     <element name="topic">
 18 |       <text/>
 19 |     </element>
 20 |   </define>
 21 | 
 22 |   <define name="prop-supported-triggers-content-update">
 23 |     <element name="content-update">
 24 |       <ref name="prop-dav-depth"/>
 25 |     </element>
 26 |   </define>
 27 |   <define name="prop-supported-triggers-property-update">
 28 |     <element name="property-update">
 29 |       <ref name="prop-dav-depth"/>
 30 |     </element>
 31 |   </define>
 32 |   <!-- supported triggers -->
 33 |   <define name="prop-supported-triggers">
 34 |     <element name="supported-triggers">
 35 |       <choice>
 36 |         <ref name="prop-supported-triggers-content-update"/>
 37 |         <ref name="prop-supported-triggers-property-update"/>
 38 |         <interleave>
 39 |           <ref name="prop-supported-triggers-content-update"/>
 40 |           <ref name="prop-supported-triggers-property-update"/>
 41 |         </interleave>
 42 |       </choice>
 43 |     </element>
 44 |   </define>
 45 | 
 46 | 
 47 |   <!-- subscription registration -->
 48 | 
 49 |   <define name="subscription-registration-trigger-content-update">
 50 |     <element name="content-update">
 51 |       <!-- requested depth -->
 52 |       <ref name="prop-dav-depth"/>
 53 |     </element>
 54 |   </define>
 55 |   <define name="subscription-registration-trigger-property-update">
 56 |     <element name="property-update">
 57 |       <!-- requested depth -->
 58 |       <ref name="prop-dav-depth"/>
 59 | 
 60 |       <!-- properties client is interested in -->
 61 |       <optional>
 62 |         <element ns="DAV:" name="prop">   <!-- list of properties, as in PROPFIND request -->
 63 |           <zeroOrMore>
 64 |             <element>
 65 |               <anyName/>
 66 |               <empty/>
 67 |             </element>
 68 |           </zeroOrMore>
 69 |         </element>
 70 |       </optional>
 71 |     </element>
 72 |   </define>
 73 |   <define name="subscription-registration">
 74 |     <element name="push-register">
 75 |       <!-- subscription to register -->
 76 |       <element name="subscription">
 77 |         <choice>
 78 |           <ref name="web-push-subscription"/>
 79 |           <!-- or other subscription, not covered by this schema -->
 80 |         </choice>
 81 |       </element>
 82 | 
 83 |       <!-- events that trigger a push notification -->
 84 |       <element name="trigger">
 85 |         <choice>
 86 |           <ref name="subscription-registration-trigger-content-update"/>
 87 |           <ref name="subscription-registration-trigger-property-update"/>
 88 |           <interleave>
 89 |             <ref name="subscription-registration-trigger-content-update"/>
 90 |             <ref name="subscription-registration-trigger-property-update"/>
 91 |           </interleave>
 92 |         </choice>
 93 |       </element>
 94 | 
 95 |       <!-- expiration -->
 96 |       <optional>
 97 |         <element name="expires">
 98 |           <text/>   <!-- date-time in IMF-fixdate format -->
 99 |         </element>
100 |       </optional>
101 |     </element>
102 |   </define>
103 | 
104 | 
105 |   <!-- XML error conditions (precondition/postcondition) for use with {DAV:}error element -->
106 | 
107 |   <define name="precondition-invalid-subscription">
108 |     <element name="invalid-subscription">
109 |       <empty/>
110 |     </element>
111 |   </define>
112 | 
113 |   <define name="precondition-push-not-available">
114 |     <element name="push-not-available">
115 |       <empty/>
116 |     </element>
117 |   </define>
118 | 
119 |   <define name="precondition-no-trigger-supported">
120 |     <element name="no-trigger-supported">
121 |       <empty/>
122 |     </element>
123 |   </define>
124 | 
125 | 
126 |   <!-- push message -->
127 | 
128 |   <define name="push-message">
129 |     <element name="push-message">
130 |       <interleave>
131 |         <!-- collection topic (not present in VAPID key rotation message) -->
132 |         <zeroOrMore>
133 |           <ref name="prop-topic"/>
134 |         </zeroOrMore>
135 | 
136 |         <!-- content update -->
137 |         <zeroOrMore>
138 |           <element name="content-update">
139 |             <optional>
140 |               <ref name="prop-dav-sync-token"/>
141 |             </optional>
142 |           </element>
143 |         </zeroOrMore>
144 | 
145 |         <!-- property update -->
146 |         <zeroOrMore>
147 |           <element name="property-update">
148 |             <optional>
149 |               <ref name="prop-dav-prop"/>
150 |             </optional>
151 |           </element>
152 |         </zeroOrMore>
153 |       </interleave>
154 |     </element>
155 |   </define>
156 | 
157 | 
158 |   <!-- Web Push properties -->
159 | 
160 |   <define name="web-push-transport">
161 |     <element name="web-push">
162 |       <!-- VAPID key -->
163 |       <optional>
164 |         <element name="vapid-public-key">
165 |           <attribute name="type">
166 |             <choice>
167 |               <value>p256ecdsa</value>
168 |               <!-- or other type / not covered by this schema -->
169 |             </choice>
170 |           </attribute>
171 |           <text/>
172 |         </element>
173 |       </optional>
174 |     </element>
175 |   </define>
176 | 
177 |   <define name="web-push-subscription">
178 |     <element name="web-push-subscription">
179 |       <interleave>
180 |         <!-- push resource (absolute URI) -->
181 |         <element name="push-resource">
182 |           <text/>
183 |         </element>
184 | 
185 |         <!-- message encryption -->
186 |         <element name="content-encoding">
187 |           <choice>
188 |             <value>aes128gcm</value>    <!-- defined in RFC8188 -->
189 |             <!-- or other encoding / not covered by this schema -->
190 |           </choice>
191 |         </element>
192 | 
193 |         <element name="subscription-public-key">
194 |           <attribute name="type">
195 |             <choice>
196 |               <value>p256dh</value>
197 |               <!-- or other type / not covered by this schema -->
198 |             </choice>
199 |           </attribute>
200 |           <text/>
201 |         </element>
202 | 
203 |         <element name="auth-secret">
204 |           <text/>
205 |         </element>
206 |       </interleave>
207 |     </element>
208 |   </define>
209 | 
210 | 
211 |   <!-- external properties (only informational) -->
212 | 
213 |   <define name="prop-dav-prop">
214 |     <element ns="DAV:" name="prop">
215 |       <zeroOrMore>
216 |         <element>
217 |           <anyName/>
218 |           <empty/>
219 |         </element>
220 |       </zeroOrMore>
221 |     </element>
222 |   </define>
223 | 
224 |   <define name="prop-dav-depth">        <!-- defined in WebDAV (RFC 4918) -->
225 |     <element ns="DAV:" name="depth">
226 |       <choice>
227 |         <value>0</value>
228 |         <value>1</value>
229 |         <value>infinity</value>
230 |       </choice>
231 |     </element>
232 |   </define>
233 | 
234 |   <define name="prop-dav-sync-token">   <!-- defined in RFC 6578 -->
235 |     <element ns="DAV:" name="sync-token">
236 |       <text/>
237 |     </element>
238 |   </define>
239 | 
240 | </grammar>
241 | 


--------------------------------------------------------------------------------
/content.mkd:
--------------------------------------------------------------------------------
  1 | 
  2 | # Introduction
  3 | 
  4 | **(This document is in work and subject of ongoing modification.)**
  5 | 
  6 | WebDAV-Push is intended as a tool for WebDAV {{RFC4918}} clients to get notified about updates in resources (usually collections) in near time so that they can refresh their views, perform synchronization etc.
  7 | 
  8 | A client MUST NOT rely solely on WebDAV-Push, so it should also perform regular polling like when WebDAV-Push is not available. However if WebDAV-Push is available, the polling frequency can be significantly reduced.
  9 | 
 10 | Typical use cases:
 11 | 
 12 | - A mobile app synchronizes calendars/address books with device-local storage and wants to be notified on collection updates in order to re-synchronize.
 13 | - A desktop file manager shows contents of a WebDAV collection and wants to be notified on updates in order to refresh the view.
 14 | - A calendar Web app shows a CalDAV collection and wants to be notified on updates in order to refresh the view.
 15 | 
 16 | [^todo]: TO BE DONE
 17 | 
 18 | 
 19 | ## Notational Conventions
 20 | 
 21 | {::boilerplate bcp14-tagged}
 22 | 
 23 | 
 24 | ## Overview
 25 | 
 26 | ~~~goat
 27 | .--------------------.   .--------------.   .--------------------.
 28 | | WebDAV-Push Server |   | Push Service |   | WebDAV-Push Client |
 29 | '--------------------'   '--------------'   '--------------------'
 30 | 
 31 |                                   Create subscription
 32 |                                 .----------------------o
 33 |                                 '---------------------->
 34 | 
 35 |                       Register subscription
 36 |            <-------------------------------------------o
 37 | 
 38 |                    Content update notification
 39 |            o------------------->*---------------------->
 40 | ~~~
 41 | {: title="Basic WebDAV-Push Workflow"}
 42 | 
 43 | A WebDAV-Push server needs to
 44 | 
 45 | - advertise WebDAV-Push and relevant information (service detection),
 46 | - manage subscriptions to resources (usually collections), and
 47 | - send push messages when a subscribed resource changes.
 48 | 
 49 | In order to manage subscriptions, a WebDAV server needs to
 50 | 
 51 | - provide a way for clients to subscribe to a resource (with transport-specific information),
 52 | - provide a way for clients to unsubscribe from a resource, and
 53 | - handle expired or otherwise invalid subscriptions.
 54 | 
 55 | Notifications about updated resources have to be sent to all subscribed clients over the respective push transports.
 56 | 
 57 | A WebDAV-Push client typically
 58 | 
 59 | - detects whether the server supports WebDAV-Push and which push transports,
 60 | - connects to a push service (which is usually not operated by the same party as the WebDAV server),
 61 | - subscribes to one or more resources on the server (with the data received from the push service),
 62 | - receives push notifications that cause some client-side action (like to refresh the view or run synchronization),
 63 | - re-subscribes to resources before the registrations expire,
 64 | - unsubscribes from resources when notifications are not needed anymore.
 65 | 
 66 | WebDAV-Push is not restricted to a specific push transport. This allows even upcoming, yet unknown push transports to be used with WebDAV-Push. Push transport definitions can define extra properties and additional processing rules.
 67 | 
 68 | WebDAV-Push implementations SHOULD implement at least the Web Push transport (defined in {{transport-web-push}}). Ideally, other transports are connected over a Web Push gateway instead of defining a new WebDAV-Push transport.
 69 | 
 70 | 
 71 | ## Terminology
 72 | 
 73 | If parts of a term are in brackets, it means that those parts may or may not be written together with the other parts. However it means the same in any case.
 74 | 
 75 | Push notification
 76 | : push message or delivery of a push message
 77 | 
 78 | Push message
 79 | : Actual network message that is sent from the server over a push transport to the client. Notifies the client that a specific resource (identified by its push topic) has changed.
 80 |   
 81 |   In Web Push context, a WebDAV-Push server can send a push message (more exact, "request delivery of a push message") over the push service by `POST`ing the message to the client's subscription URL.
 82 | 
 83 | Push service
 84 | : Infrastructure that implements a specific push transport. The push service is the actual network service between WebDAV-Push server and WebDAV-Push client.
 85 |   
 86 |   For instance, if the push transport is Web Push is a Web app, the push service would be provided by the vendor of the browser that the client runs in.
 87 | 
 88 | (Push) subscription (URL)
 89 | : The information that the client needs to provide to the server so that the server can send push notifications. The server can `POST` a push message to that URL.
 90 |   
 91 |   If the transport is Web Push, the term "(push) subscription (URL)" as used in this document is equivalent to the Web Push term "push resource".
 92 | 
 93 | (Push) topic
 94 | : Character sequence that identifies a WebDAV resource for push purposes (unique per WebDAV server). A specific resource could be reachable at different URLs, but it can only have one push topic.
 95 | 
 96 | (Push) transport
 97 | : Protocol that defines an actual push mechanism. In this document, Web Push is the only defined push transport (see {{transport-web-push}}). However, WebDAV-Push may also be used with other push transports like proprietary or yet unknown protocols. In that case, it has to be specified how to use that protocol with WebDAV-Push. A push transport typically involves a push service.
 98 | 
 99 | Web Push
100 | : "Protocol for the delivery of real-time events to user agents", defined by {{RFC8030}}. Usually implemented in browsers (which means that major browser vendors provide their own push services), but there are also other implementations like {{UnifiedPush}}. Some parts (namely push message delivery from the push service to the client) specify implementation details that may be done by other means without changing the meaning of the RFC for WebDAV-Push servers and clients.
101 | 
102 |   There are also additional standards that can be considered to belong to Web Push, especially VAPID ({{RFC8292}}) and Message Encryption ({{RFC8291}}).
103 | 
104 | WebDAV-Push
105 | : WebDAV-based protocol to notify clients about updates in resource using a push transport (in contrast to polling). Specified in this document.
106 | 
107 | (WebDAV-Push) client
108 | : WebDAV client that supports WebDAV-Push, for instance a CalDAV/CardDAV app on a mobile device
109 | 
110 | (WebDAV-Push) server
111 | : WebDAV server (for instance a CalDAV/CardDAV server) that implements WebDAV-Push
112 | 
113 | 
114 | ## XML Element Namespace
115 | 
116 | When XML element names are used without namespace in this document, they are in the WebDAV-Push namespace: `https://bitfire.at/webdav-push`
117 | 
118 | All XML elements defined by this document reside in this namespace. The XML schema for the elements can be found in {{xml-schema}}.
119 | 
120 | To reference element names in another namespace, the `{ns}element` syntax is used. For instance, `{DAV:}prop` means the `prop` XML element in the `DAV:` namespace.
121 | 
122 | 
123 | 
124 | # Service Detection
125 | 
126 | A server that supports WebDAV-Push MUST include "webdav-push" in the `DAV` header of an `OPTIONS` response for any resource that supports WebDAV-Push. The "webdav-push" value MUST indicate that all MUST-level requirements of this document are met and all SHOULD-level requirements are met except for a good reason.
127 | 
128 | Example:
129 | 
130 | ~~~http-message
131 | OPTIONS /calendars/
132 | Host: caldav.example.com
133 |     
134 | HTTP/1.1 200 OK
135 | Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE
136 | Allow: PROPFIND, PROPPATCH, LOCK, UNLOCK, REPORT, ACL
137 | DAV: 1, 2, access-control, calendar-access, webdav-push
138 | Content-Length: 0
139 | ~~~
140 | 
141 | Here, the OPTIONS response contains "webdav-push" in the DAV header to indicate that the resource supports the properties and operations defined in this document.
142 | 
143 | 
144 | ## Push Properties {#push-properties}
145 | 
146 | To provide information about WebDAV-Push support, new properties are defined. A server MUST provide the `transports`(((transports XML element))), `topic` and `supported-triggers` properties for resources that support WebDAV-Push. A server MUST NOT provide the `topic` and `supported-triggers` properties for resources that don't support WebDAV-Push (for instance for non-collection resources, if they're not supported).
147 | 
148 | The `transports` element(((transports XML element))) lists available push transports. Within the scope of this document, the only supported transport is `web-push` (see {{transport-web-push}}). Although the property is defined on every Push-capable resource, its value is usually the same for every resource on the server.
149 | 
150 | The `topic`(((topic XML element))) is a (server-wide) unique identifier for the resource. A specific resource could be reachable with different URLs, but it can have only one push topic. A server could for instance use a random UUID or a canonical URL that won't change over the lifetime of the resource.
151 | 
152 | The `supported-triggers` element(((supported-triggers XML element))) MUST contain at least one of the following elements:
153 | 
154 | - `content-update` if the resource supports push notifications on content updates (see {{content-updates}}). It contains a `{DAV:}depth` property that indicates the maximum supported depth.
155 | - `property-update` if the resource supports push notifications on property updates (see {{property-updates}}). It contains a `{DAV:}depth` property that indicates the maximum supported depth.
156 | 
157 | A client can use WebDAV `PROPFIND` to retrieve these properties.
158 | 
159 | Example:
160 | 
161 | ~~~http-message
162 | PROPFIND https://example.com/webdav/collection/
163 | <?xml version="1.0" encoding="utf-8" ?>
164 | <propfind xmlns="DAV:" xmlns:P="https://bitfire.at/webdav-push">
165 |   <prop>
166 |     <P:transports/>
167 |     <P:topic/>
168 |     <P:supported-triggers/>
169 |   </prop>
170 | </propfind>
171 | 
172 | HTTP/1.1 207 Multi-Status
173 | <?xml version="1.0" encoding="utf-8" ?>
174 | {::include xml/sample-propfind-multistatus.xml}
175 | ~~~
176 | 
177 | In this case, the queried collection supports WebDAV-Push in general and thus has a push topic. It supports the Web Push transport and provides a VAPID public key. Push notifications are supported for content updates of internal members and on property updates of the collection itself.
178 | 
179 | The comment shows how support for some other (not yet defined) transport could be advertised together with additional specific information that is required to use it.
180 | 
181 | 
182 | 
183 | # Subscription Management
184 | 
185 | ## Subscription Registration
186 | 
187 | To subscribe to a resource, the client sends a `POST` request with `Content-Type: application/xml` to the resource it wants to subscribe. The root XML element of the XML body is `push-register` and can be used to distinguish between WebDAV-Push and other requests.
188 | 
189 | The `push-register` element(((push-register XML element))) contains:
190 | 
191 | * exactly one `subscription` element, which contains all information the server needs to send a push message,
192 | * exactly one `trigger` element to specify the type of updates the client wants to be notified about, and
193 | * an optional `expires` element that contains the requested expiration time in the `IMF-fixdate` format (as defined in {{Section 5.6.7 of RFC9110}}).
194 | 
195 | The `subscription` element(((subscription XML element))) specifies a subscription that shall be notified on updates and contains exactly one element with details about a specific subscription type. Within the scope of this document, only the `web-push-subscription` child element is defined (see {{transport-web-push}}).
196 | 
197 | To specify which updates the client wants to be notified about, it uses the `trigger` (((trigger XML element))) element, which itself can contain:
198 | 
199 | * A `content-update` element to indicate the client's interest in notifications when the contents of the subscribed resource or its members change ("content update").
200 | * A `property-update` element to indicate the client's interest in notifications when the WebDAV properties of the subscribed resource or its members change ("property update").
201 | 
202 | WebDAV-Push is intended more as a helpful tool to speed up things (like synchronization) than a strict query processor. So subscriptions are processed in a relaxed way: the server does its best to fulfill the request, but if a certain trigger is not available, it's downgraded or ignored instead of rejected with an error response. If a client needs to know which triggers are supported, it can use `PROPFIND` with `supported-triggers`. A client MUST expect the server to downgrade or ignore certain triggers when they're not (fully) supported, and MUST be prepared to receive an error when it registers a subscription with only unsupported triggers.
203 | 
204 | ### Content Updates {#content-updates}
205 | 
206 | A "content update" occurs when the subscribed resource or a member is changed or removed, as defined in {{Section 3.5 of RFC6578}}. Typically, this is the case when the resource itself is modified or removed, or when a member is added or removed or its contents are modified. If the server supports {{RFC6578}}, a content update of a collection usually implies that the `{DAV:}sync-token` changes.
207 | 
208 | The `content-update` element(((content-update XML element))) contains a `{DAV:}depth` element that specifies whether the client is interested
209 | 
210 | - only in content updates of the subscribed resource (depth: `0`),
211 | - only in content updates of the subscribed resource and its internal members (depth: `1`), or
212 | - in content updates of the subscribed resource and its members (depth: `infinity`).
213 | 
214 | A content update of a collection itself (not of a member) only occurs when the collection has an entity body that is returned by `GET` and that body changes. A server MAY ignore such changes and not send notifications in that case.
215 | 
216 | A server SHOULD support content update notifications with a depth of at least `1` for every Push-capable collection.
217 | 
218 | If the subscribed resource doesn't support the content update trigger with the requested depth, the server MUST fall back to the lowest supported value instead. If the content update trigger isn't supported for the subscribed resource at all, it MUST be ignored.
219 | 
220 | In case the depth is `infinity`, the limitations described in {{Section 3.3 of RFC6578}} apply: notifications about changes in members which are not supported by the `DAV:sync-collection` report may not be sent.
221 | 
222 | ### Property Updates {#property-updates}
223 | 
224 | A "property update" occurs when the WebDAV properties of the subscribed resource or its members are modified. Properties update notifications are controlled by two elements within the `property-update`(((property-update XML element))) element:
225 | 
226 | 1. The `{DAV:}depth` element specifies whether the client is interested
227 | 
228 |    - only in property updates of the subscribed resource (depth: `0`),
229 |    - only in property updates of the subscribed resource and its internal members (depth: `1`), or
230 |    - in property updates of the subscribed resource and its members (depth: `infinity`).
231 | 
232 |    If the subscribed resource doesn't support the property update trigger with the requested depth, the server MUST fall back to the lowest supported value instead. If the property update trigger isn't supported for the subscribed resource at all, it MUST be ignored.
233 | 
234 |    In case the depth is `infinity`, the limitations described in {{Section 3.3 of RFC6578}} apply: notifications about changes in members which are not supported by the `DAV:sync-collection` report may not be sent.
235 | 
236 | 2. The optional `{DAV:}prop` element (as used in a `PROPFIND` request) specifies a list of properties that the client is interested in.
237 | 
238 |    If the `{DAV:}prop` element is empty or not present, the server chooses a list of properties that it considers to be useful for the client. If the `{DAV:}prop` element is present and contains properties for which property update notifications are not supported, the server MUST ignore those unsupported properties. Also, a server MAY ignore the contents of a `{DAV:prop}` element at all and treat it like if it was empty or not present.
239 | 
240 |    Neither a server nor a client SHOULD use property update notifications for properties that automatically change on a content update, like `{DAV:}getetag`, `{DAV:}getlastmodified` and `{DAV:}sync-token`, because this would implicitly cause a property update for every content update. Notifications about content updates should instead be requested/sent explicitly as content update notifications.
241 | 
242 | The removal of a resource, including the subscribed resource, is not considered as a property update but as a content update.
243 | 
244 | 
245 | ### Response
246 | 
247 | Allowed response codes:
248 | 
249 | * 201 if the subscription was registered and the server wants to return additional information, like encryption details that are only valid for this subscription. The format of these details is specified by the respective transport definition.
250 | * 204 if the subscription was registered without additional information
251 | * 403 with precondition `invalid-subscription` when the request doesn't contain a valid `subscription`
252 | * 403 with precondition `push-not-available` if WebDAV-Push is not available for this resource or if the user is not allowed to register a push subscription for it
253 | * 403 with precondition `no-supported-trigger` when the request doesn't contain a trigger or when all requested triggers are ignored (because they're not supported)
254 | * other response code with usual HTTP/WebDAV semantics
255 | 
256 | When a subscription is registered the first time, the server creates a canonical URL that identifies that registration (registration URL)(((Registration URL))) which can be used to remove the subscription. The server MUST send an absolute registration URL in the `Location` header.
257 | 
258 | The server MUST return a HTTP `Expires` header (as defined in {{Section 5.3 of RFC9111}}) in the `IMF-fixdate` format with the actual expiration date on the server, which may be shorter than the expiration requested by the client.
259 | 
260 | Example 1 (successful registration):
261 | 
262 | ~~~http-message
263 | POST https://example.com/webdav/collection/
264 | Content-Type: application/xml; charset="utf-8"
265 | 
266 | <?xml version="1.0" encoding="utf-8" ?>
267 | {::include xml/sample-push-register.xml}
268 | 
269 | HTTP/1.1 204 No Content
270 | Location: https://example.com/webdav/subscriptions/io6Efei4ooph
271 | Expires: Wed, 02 Oct 2024 07:28:00 GMT
272 | ~~~
273 | 
274 | Example 2: A client registers a content update trigger with infinite depth and a property update trigger with a depth of `1`, but the collection supports only content update triggers with a depth of `1` and doesn't support the property update trigger at all, it registers the subscription and responds with 201. Notifications will then only be sent on content updates with a depth of `1` (trigger downgraded by server). On property updates, notifications will not be sent (trigger ignored by server).
275 | 
276 | Example 3: A client registers a property update trigger with a depth of `0` and the collection doesn't support property update triggers at all, the server ignores the trigger. So all triggers of the request are ignored and the server responds with 403 with `no-supported-trigger`.
277 | 
278 | 
279 | ## Subscription Updates
280 | 
281 | Every subscription has a transport-specific unique identifier (the push resource in case of Web Push).
282 | 
283 | A server MUST NOT register a subscription with the same identifier multiple times for the same resource. Instead, when a client wants to register a subscription with an identifier that is already registered for the requested resource, the server MUST update the registration with the given details and the expiration date.
284 | 
285 | The response is the same as for subscription registration.
286 | 
287 | 
288 | ## Subscription Removal
289 | 
290 | A client can explicitly unsubscribe from a resource by sending a `DELETE` request to the previously acquired registration URL.
291 | 
292 | Allowed response codes:
293 | 
294 | * 204 if the registered subscription was removed.
295 | * 404 if the registration URL is unknown (or expired).
296 | * other response code with usual HTTP/WebDAV semantics
297 | 
298 | Sample request:
299 | 
300 | ~~~http-message
301 | DELETE https://example.com/webdav/subscriptions/io6Efei4ooph
302 | 
303 | HTTP/1.1 204 Unregistered
304 | ~~~
305 | 
306 | 
307 | ## Expiration
308 | 
309 | When a client registers or updates a subscription, it can request a specific expiration date-time. A server SHOULD take the requested expiration time into consideration, but MAY impose its own (often stricter) expiration rules. A server SHOULD allow subscriptions to be valid at least three days. When the expiration is too far in the future, it becomes more probable that the subscription will become invalid or stale at some time.
310 | 
311 | A client has to refresh its registrations regularly and before the expiration to keep them working. It can expect that subscriptions usually stay valid until their expiration, although there may be special circumstances that cause all subscriptions to be reset, like when the server software is changed.
312 | 
313 | A server MUST NOT send a notification to an expired subscription.
314 | 
315 | 
316 | 
317 | # Push Notification
318 | 
319 | A WebDAV-Push server MUST notify registered subscriptions of a subscribed resource:
320 | 
321 | - on a _content update_, if this was requested during subscription registration, and
322 | - on a _property update_, if this was requested during subscription registration.
323 | 
324 | In case of the Web Push transport, this happens over a `POST` request to the subscription (push resource).
325 | 
326 | 
327 | ## Push Message
328 | 
329 | The push message body consists of a `push-message` element, which contains information about the affected resource:
330 | 
331 | - a `topic` element(((topic XML element))) with the push topic (except for VAPID key rotation messages, see {{vapid-key-rotation}}),
332 | - a `content-update` element(((content-update XML element))) in case of a content update, and/or
333 | - a `property-update` element(((property-update XML element))) in case of a property update.
334 | 
335 | The `content-update` element of a push message SHOULD contain a `{DAV:}sync-token` element so that a client can ignore the push message when it already knows the latest state.
336 | 
337 | The `property-update` element of a push message is usually empty (except for VAPID key rotation messages).
338 | 
339 | Example:
340 | 
341 | ~~~xml
342 | {::include xml/sample-push-message.xml}
343 | ~~~
344 | 
345 | Here, both the contents and the properties of the resource (or its members, depending on the registered trigger) with topic `O7M1nQ7cKkKTKsoS_j6Z3w` have changed. The new sync-token (after the change) is `http://example.com/sync/10`.
346 | 
347 | 
348 | ## Suppressing Notifications
349 | 
350 | A client may not want to receive push notifications for a change that it induces itself. It can indicate this with the `Push-Dont-Notify` header field, which is sent together with the request that causes the change.
351 | 
352 | Header name: "Push-Dont-Notify"(((Push-Dont-Notify)))  
353 | Value syntax in ABNF with #rule extension as defined in {{Section 5.6.1 of RFC9110}}:
354 | 
355 | ~~~abnf-rfc9110
356 | Push-Dont-Notify        = 1#(quoted-registration-url) / "*"
357 | 
358 | quoted-registration-url = quoted-string
359 |                           ; absolute push registration URL
360 | ~~~
361 | 
362 | In the context of the requested operation, a server MUST NOT send push notifications to the explicitly given subscription URLs of the `Push-Dont-Notify` header, and it SHOULD NOT send any push notifications when the asterisk value (`*`) is used.
363 | 
364 | Because URLs are not per se canonical, registration URLs MUST be provided in the exact form as it was originally provided by the server in the `Location` header.
365 | 
366 | Multiple values can be provided as a list and/or using multiple lines as described in {{Section 5.2 of RFC9110}}. If the asterisk is used, other values MUST NOT be sent.
367 | 
368 | A server MUST ignore invalid values.
369 | 
370 | Example 1:
371 | 
372 | ~~~http-message
373 | PUT /file.txt HTTP/1.1
374 | Host: www.example.com
375 | Push-Dont-Notify: "https://example.com/webdav/subscriptions/io6Efei4ooph"
376 | 
377 | […]
378 | 
379 | HTTP/1.1 201 Created
380 | ~~~
381 | 
382 | In this example, the client requests that the server doesn't send a push notification for the change in `file.txt` to the mentioned subscription.
383 | 
384 | Example 2:
385 | 
386 | ~~~http-message
387 | DELETE /file.txt HTTP/1.1
388 | Host: www.example.com
389 | Push-Dont-Notify: *
390 | 
391 | […]
392 | 
393 | HTTP/1.1 204 No Content
394 | ~~~
395 | 
396 | Here the client requests that the server doesn't send any push notification in the context of the deletion.
397 | 
398 | 
399 | ## Rate Limiting
400 | 
401 | It's possible that a lot of changes occur within a short period of time (like an upload of many contacts or a mass-change of events, especially for a collection with a lot of subscriptions). This can lead to problems when every change results in a push message:
402 | 
403 | - The push server has to send a lot of messages (number of changes times number of subscriptions), which means high load and traffic.
404 | - The push service receives a lot of messages within a short period of time (spiky traffic, which should be avoided) and may throttle or deny delivery.
405 | - Push clients receive a lot of unnecessary notifications, because they'd only need one after all changes are done. Especially for mobile clients that also means a lot of useless battery and network usage.
406 | 
407 | A server SHOULD take measures to avoid such problems. These can include:
408 | 
409 | * to send push messages asynchronously (so that for instance a `PUT` doesn't block until all notifications are sent),
410 | * to impose a rate limit for push messages,
411 | * to delay push messages (usually for a short time),
412 | * to merge/omit push messages.
413 | 
414 | Such measures SHOULD NOT change the overall meaning of the push notifications so that the client can still perform its desired action. For instance, of a series of push messages that contain only content updates and occur shortly after each other, all but the last message can be omitted (the messages are _merged_ into a single one). If one of the push messages signals a property update, it can't be just omitted because the client then wouldn't know that a property update happened. So in that case the server could either send two messages (one merged message for the content updates and one for the property update) or even better a single push message that signals both the content and the property update.
415 | 
416 | A client MAY use the `Push-Dont-Notify: *` header to reduce the number of push messages when desired (for instance, for all requests in a batch except the last one). However it should be aware that if the last operation fails, then no push notification is sent at all; so this should be used only when really necessary.
417 | 
418 | 
419 | ## Removal of Invalid Subscriptions
420 | 
421 | A WebDAV-Push server SHOULD remove invalid subscriptions (encountered when trying to sending a push notification) at some time.
422 | 
423 | An invalid subscription is a subscription that push notifications can't be delivered to. Usually the push service returns an HTTP error code like 404 when it receives a notification for an invalid subscription. There may also be other conditions that render a subscription invalid, like a non-resolvable hostname or an encryption error.
424 | 
425 | A server could use some logic like remembering the last successful delivery plus some tolerance interval to defer removal of an invalid subscription. Doing so will make WebDAV-Push more reliable in case of temporary problems and avoid temporal "holes" between subscription removal and re-registration.
426 | 
427 | 
428 | 
429 | # CalDAV/CardDAV
430 | 
431 | WebDAV-Push can be used with CalDAV {{RFC4791}} and CardDAV {{RFC6352}} to provide short-time update notifications when collections (calendars, address books) or entries (contacts, events, …) change.
432 | 
433 | Depending on the features of a CalDAV/CardDAV client, it could for instance subscribe to:
434 | 
435 | - content updates of a home-set to become notified about new collections,
436 | - content updates of a collection (usually with a depth of `1`) to become notified about modified entries,
437 | - property updates of a collection (usually with a depth of `0`) to become notified about changes of properties like display name, calendar color and access permissions,
438 | - property updates (for instance display name) of a principal to update real names of collection owners.
439 | 
440 | A CalDAV/CardDAV server that supports WebDAV-Push SHOULD support:
441 | 
442 | - content updates with a `{DAV:}depth` of at least 1 on
443 |   - `calendar-home-set` and `addressbook-home-set` collections,
444 |   - calendars and address books (collections which have a `{DAV:}resourcetype` of `{CALDAV:}calendar` or `{CARDDAV:}addressbook`),
445 |   - scheduling inbox and outbox collections (collections which have a `{DAV:}resourcetype` of `{CALDAV:}schedule-inbox` or `{CALDAV:}schedule-outbox` as defined in {{Section 2 of RFC6638}});
446 | - property updates with a `{DAV:}depth` of at least 0 on
447 |   - calendars and address books,
448 |   - principals (collections with have a `{DAV:}resourcetype` of `{DAV:}principal` as defined in {{Section 4 of RFC3744}}).
449 | 
450 | 
451 | # Web Push Transport {#transport-web-push}
452 | 
453 | WebDAV-Push can be used with Web Push {{RFC8030}} as a transport to deliver WebDAV-Push notifications directly to compliant user agents, like Web browsers which come with their own push service infrastructure.
454 | 
455 | When the Web Push transport is used for WebDAV-Push,
456 | 
457 | * {{RFC8030}} defines how to generate subscriptions and send push messages,
458 | * the WebDAV-Push server acts as Web Push application server,
459 | * the WebDAV client acts as Web Push user agent.
460 | 
461 | Corresponding terminology:
462 | 
463 | * (WebDAV-Push) push subscription ↔ (Web Push) push resource
464 | * (WebDAV-Push) push server ↔ (Web Push) application server
465 | * (WebDAV-Push) push client ↔ (Web Push) user agent
466 | 
467 | Message encryption ({{message-encryption}}) MUST be used. VAPID(((VAPID))) ({{vapid}}) SHOULD be used. (If other methods to provide a security context for Web Push become established, those can be used and necessary WebDAV properties shall be added to this document.)
468 | 
469 | A server that supports the Web Push transport MUST list the `web-push` element(((web-push XML element))) in the `transports` property.
470 | 
471 | ~~~goat
472 | .--------------------.   .--------------.   .--------------------.
473 | |                    |   |   Web Push   |   |                    |
474 | | WebDAV-Push Server |   |   Service    |   | WebDAV-Push Client |
475 | '--------------------'   '--------------'   '--------------------'
476 | 
477 |                        Get VAPID public key
478 |            .-------------------------------------------o
479 |            '------------------------------------------->
480 | 
481 |                           Create restricted subscription
482 |                                 .----------------------o
483 |                                 '---------------------->
484 | 
485 |                Register subscription (with encryption)
486 |            <-------------------------------------------o
487 | 
488 |                Content/property update notification
489 |            o---(encrypted)----->*------(encrypted)----->
490 | ~~~
491 | {: title="WebDAV-Push over Web Push with VAPID and Message Encryption"}
492 | 
493 | 
494 | ## Subscription Registration
495 | 
496 | To register a Web Push subscription, the `subscription` element of the `push-register` request contains exactly one `web-push-subscription`.
497 | 
498 | The `web-push-subscription` element(((web-push-subscription XML element))) represents the public information of a Web Push subscription that is shared with the WebDAV-Push server.
499 | 
500 | It contains exactly one `push-resource` element(((push-resource XML element))), which specifies the absolute URI that identifies the endpoint where Web Push notifications are sent to.
501 | 
502 | A Web Push subscription is uniquely identified by its push resource.
503 | 
504 | 
505 | ## VAPID(((VAPID))) {#vapid}
506 | 
507 | VAPID {{RFC8292}} binds push subscriptions to a specific WebDAV-Push server.
508 | 
509 | A WebDAV-Push server that supports VAPID stores a key pair. It exposes an additional transport property `vapid-public-key`(((vapid-public-key XML element))) within the `web-push` element, which contains the VAPID public key in uncompressed form and base64url encoded. The attribute `type="p256ecdsa"` MUST be added to allow different key types in the future. See {{push-properties}} for an example.
510 | 
511 | If the server provides a VAPID public key, the client MUST use that key to create a restricted subscription at the push service (except when the used push service doesn't support VAPID).
512 | 
513 | A client can expect the VAPID public key to be the same for all resources on the server.
514 | 
515 | When the server provides a VAPID public key, it MUST include a corresponding `Authorization` header when sending a push message to prove its identity to the push service.
516 | 
517 | ### Key Rotation {#vapid-key-rotation}
518 | 
519 | The VAPID public key can sometimes change, either intentionally (key rotation) or for instance when the server or user data is moved to another machine. When the VAPID key has changed, a client has to create new restricted subscriptions because the old ones are bound to the old key and thus don't work anymore.
520 | 
521 | When a server that changes its VAPID key is able to notify clients with the old VAPID key before switching, it SHOULD send a key rotation push message to every distinct active subscription.
522 | 
523 | A key rotation push message is a push message that only contains a `property-update` that includes a `{DAV:}prop` property with the `transports` property like this:
524 | 
525 | ~~~xml
526 | {::include xml/push-message-vapid-key.xml}
527 | ~~~
528 | 
529 | A client that receives a key rotation push message MUST assume that the last known VAPID key isn't valid anymore. So in order to restore Push functionality, it has to query the new VAPID key, create a new subscription and register it again.
530 | 
531 | However because it's possible that the VAPID key changes without possibility to notify the clients with the old key, clients are advised to verify the VAPID key regularly.
532 | 
533 | 
534 | ## Message Encryption(((Encryption))) {#message-encryption}
535 | 
536 | Message encryption hides details of push messages from the push services. Before creating the subscription, the client generates a key pair as defined in {{RFC8291}}.
537 | 
538 | When the client then registers this subscription at the server, it includes these subscription properties:
539 | 
540 | * `content-encoding`(((content-encoding XML element))) – how the encrypted content is encoded; currently only `aes128gcm` is supported
541 | * `subscription-public-key`(((subscription-public-key XML element))) – public key of the user agent's key pair in uncompressed form and base64url encoded; attribute `type="p256dh"` MUST be added to allow different key types in the future
542 | * `auth-secret`(((auth-secret XML element))) – authentication secret
543 | 
544 | These properties are bound to the subscription (which is identified by the push resource). A server doesn't need to store these properties for every registration, but only once for the subscription.
545 | 
546 | The server uses these data to encrypt the payload before sending it to the push service. The client then decrypts the payload again.
547 | 
548 | 
549 | ## Push Message
550 | 
551 | The push message is delivered via `POST` to the push resource, with `Content-Type: application/xml; charset="UTF-8"`.
552 | 
553 | The server MAY send the push message with a `Topic` header so that an undelivered push message can be replaced by an updated one. The server MUST ensure that the meaning doesn't change when a push message is potentially replaced. The `Topic` header is visible to the push service, so its value MUST NOT contain sensitive information.
554 | 
555 | The server MAY use the `Urgency` header to set the priority of the push message. For instance, a CalDAV server may send push notifications for new/changed events with alarms that are scheduled within the next 15 minutes with `Urgency: high` so that users receive the alarm as soon as possible. Updates that are not that time-critical, for instance in slowly changing collections like a holiday calendar could be sent with `Urgency: low`.
556 | 
557 | 
558 | 
559 | # Security Considerations
560 | 
561 | ## Security Context
562 | 
563 | WebDAV-Push operates within the usual security context of WebDAV. A server usually restricts WebDAV access to authorized users. It makes sense to apply the same restrictions to WebDAV-Push operations (like subscription registration). It's however up to the server to define which WebDAV-Push operations are allowed and under which conditions. If a request is denied because of wrong authentication or security restrictions, the correct HTTP/WebDAV status codes MUST be used (usually 401 or 403).
564 | 
565 | WebDAV-Push SHOULD only be advertised to clients which are actually allowed to use it.
566 | 
567 | A server SHOULD restrict all requests to the access and knowledge scope of the currently authenticated user. For instance, when a subscription is registered, the registration can be associcated with the current user. The server should then restrict further usage of the registration URL to that user. The server should deny to update/delete the registration of another user, or to use a registration URL created by another user in the `Push-Dont-Notify` header.
568 | 
569 | 
570 | ## Push Services
571 | 
572 | Even when push messages are end-to-end-encrypted, push services can relate clients over metadata and heuristics. For instance, clients which are at the same time notified by a specific WebDAV-Push server have probably subscribed the same resource. Push services could also create a map of which clients are registered to which WebDAV-Push servers.
573 | 
574 | The value of a potential `Topic` header of a push message is not covered by end-to-end encryption because it's require the push service to process it.
575 | 
576 | 
577 | ## Web Push
578 | 
579 | When using the Web Push transport, the general requirements from {{Section 8 of RFC8030}} apply, especially:
580 | 
581 | - HTTP over TLS MUST be used for all communications.
582 | - Mechanisms that provide end-to-end confidentiality, integrity and data origin authentication MUST be used.
583 | 
584 | 
585 | 
586 | --- back
587 | 
588 | # XML Schema
589 | 
590 | This XML schema formally defines the XML elements used by this document and is expressed in {{RELAXNG}}.
591 | 
592 | ~~~xml
593 | {::include xml/webdav-push.rng}
594 | ~~~
595 | 


--------------------------------------------------------------------------------