Add Push-Dont-Notify header (#90)

* Add Push-Dont-Notify header

* Refine header definition

Author: rfc2822

build.sh

@@ -1,4 +1,6 @@
 #!/bin/sh
 mkdir -p build
-kramdown-rfc2629 webdav-push.mkd >build/webdav-push.xml && (cd build; xml2rfc --html webdav-push.xml && xml2rfc --text webdav-push.xml && xdg-open webdav-push.html)
+kramdown-rfc2629 webdav-push.mkd >build/webdav-push.xml && (cd build; xml2rfc --html webdav-push.xml && xml2rfc --text webdav-push.xml)
+
+echo To view in a browser, run:   xdg-open build/webdav-push.html
 

content.mkd

@@ -188,7 +188,7 @@ The `push-register` element contains:
 
 The `subscription` 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}}).
 
-To specify which updates the client wants to be notified about, it uses the `trigger` element, which itself can contain:
+To specify which updates the client wants to be notified about, it uses the `trigger` (((trigger))) element, which itself can contain:
 
 * 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").
 * 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").
@@ -317,6 +317,8 @@ A WebDAV-Push server MUST notify registered subscriptions of a subscribed resour
 - on a _content update_, if this was requested during subscription registration,
 - on a _property update_, if this was requested during subscription registration.
 
+In case of the Web Push transport, this happens over a `POST` request to the subscription (push resource).
+
 
 ## Push Message
 
@@ -337,6 +339,51 @@ Example:
 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`.
 
 
+## Suppressing Notifications
+
+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.
+
+Header name: "Push-Dont-Notify"(((Push-Dont-Notify)))  
+Value syntax in ABNF with #rule extension as defined in {{Section 5.6.1 of RFC9110}}:
+
+    Push-Dont-Notify        = 1#(quoted-registration-url) / "*"
+
+    quoted-registration-url = quoted-string
+                              ; absolute push registration URL
+
+A server SHOULD NOT send push notifications that are triggered by the requested operation to the subscriptions of the `Push-Dont-Notify` header.
+
+Because URIs are not per se canonical, the URI MUST be provided in the exact form as it was originally provided by the server in the `Location` header.
+
+Usage of the asterisk value (`*`) requests that the server doesn't send any notifications for the operation.
+
+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.
+
+Example 1:
+
+    PUT /file.txt HTTP/1.1
+    Host: www.example.com
+    Push-Dont-Notify: "https://example.com/webdav/subscriptions/io6Efei4ooph"
+    
+    […]
+    
+    HTTP/1.1 201 Created
+
+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.
+
+Example 2:
+
+    DELETE /file.txt HTTP/1.1
+    Host: www.example.com
+    Push-Dont-Notify: *
+    
+    […]
+    
+    HTTP/1.1 204 No Content
+
+Here the client requests that the server doesn't send any push notification in the context of the deletion.
+
+
 ## Rate Limiting
 
 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:
@@ -354,6 +401,8 @@ Servers SHOULD take measures to avoid such problems. These can include:
 
 Such measures MUST 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.
 
+Clients 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 clients should be aware that it may be possible that the last operation fails and then no push notification is sent at all, so this should be used only when really necessary.
+
 
 ## Removal of Invalid Subscriptions