idnits 2.17.1
draft-gajda-dav-push-00.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
No issues found here.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
== The document seems to lack the recommended RFC 2119 boilerplate, even if
it appears to use RFC 2119 keywords -- however, there's a paragraph with
a matching beginning. Boilerplate error?
(The document does seem to have the reference to RFC 2119 which the
ID-Checklist requires).
== Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD',
or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please
use uppercase 'NOT' together with RFC 2119 keywords (if that is what you
mean).
Found 'SHOULD not' in this paragraph:
; A list of topics without active subscribers. ; Applications
servers SHOULD not send further push messages for the ; enlisted topics
to this transport unless a new client subscribes on ; this transport.
no-subscribers-list "no-subscribers" [ 1* topic } ]
== Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD',
or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please
use uppercase 'NOT' together with RFC 2119 keywords (if that is what you
mean).
Found 'MUST not' in this paragraph:
A Push Gateway MUST not accept subscription requests with an
expiration time that would exceed the refresh interval.
-- The document date (May 2, 2017) is 2523 days in the past. Is this
intentional?
Checking references for intended status: Proposed Standard
----------------------------------------------------------------------------
(See RFCs 3967 and 4897 for information about using normative references
to lower-maturity documents in RFCs)
== Unused Reference: 'RFC3339' is defined on line 1001, but no explicit
reference was found in the text
** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112)
Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 1 comment (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Network Working Group M. Gajda
3 Internet-Draft dmfs
4 Intended status: Standards Track May 2, 2017
5 Expires: November 3, 2017
7 Push Discovery and Notification Dispatch Protocol
8 draft-gajda-dav-push-00
10 Abstract
12 This specification defines a framework and protocols for a push
13 notification system that allows clients, application servers and push
14 notification servers to interact with each other in a standardized
15 manner.
17 Status of This Memo
19 This Internet-Draft is submitted in full conformance with the
20 provisions of BCP 78 and BCP 79.
22 Internet-Drafts are working documents of the Internet Engineering
23 Task Force (IETF). Note that other groups may also distribute
24 working documents as Internet-Drafts. The list of current Internet-
25 Drafts is at http://datatracker.ietf.org/drafts/current/.
27 Internet-Drafts are draft documents valid for a maximum of six months
28 and may be updated, replaced, or obsoleted by other documents at any
29 time. It is inappropriate to use Internet-Drafts as reference
30 material or to cite them other than as "work in progress."
32 This Internet-Draft will expire on November 3, 2017.
34 Copyright Notice
36 Copyright (c) 2017 IETF Trust and the persons identified as the
37 document authors. All rights reserved.
39 This document is subject to BCP 78 and the IETF Trust's Legal
40 Provisions Relating to IETF Documents
41 (http://trustee.ietf.org/license-info) in effect on the date of
42 publication of this document. Please review these documents
43 carefully, as they describe your rights and restrictions with respect
44 to this document. Code Components extracted from this document must
45 include Simplified BSD License text as described in Section 4.e of
46 the Trust Legal Provisions and are provided without warranty as
47 described in the Simplified BSD License.
49 Table of Contents
51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
52 2. Conventions Used in This Document . . . . . . . . . . . . . . 3
53 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
54 4. Architecture . . . . . . . . . . . . . . . . . . . . . . . . 4
55 4.1. Application Server . . . . . . . . . . . . . . . . . . . 5
56 4.2. Push Gateway . . . . . . . . . . . . . . . . . . . . . . 5
57 4.3. Push Delivery Service . . . . . . . . . . . . . . . . . . 6
58 4.4. Client . . . . . . . . . . . . . . . . . . . . . . . . . 6
59 5. Protocol Workflows . . . . . . . . . . . . . . . . . . . . . 6
60 5.1. App Server <-> Push Gateway bootstrap workflow . . . . . 6
61 5.2. Client <-> App Server workflow . . . . . . . . . . . . . 7
62 5.2.1. Client discovery and subscription workflow - Generic 7
63 5.2.2. Unsubscribe . . . . . . . . . . . . . . . . . . . . . 7
64 5.2.3. Client discovery and subscription workflow - WebDAV . 8
65 5.3. App Server -> Push Gateway subscribe workflow . . . . . . 10
66 5.4. App Server -> Push Gateway push workflow . . . . . . . . 11
67 6. Syntax Elements/Properties . . . . . . . . . . . . . . . . . 13
68 6.1. Push gateway protocol . . . . . . . . . . . . . . . . . . 13
69 6.1.1. Bootstrapping . . . . . . . . . . . . . . . . . . . . 13
70 6.1.2. Subscription . . . . . . . . . . . . . . . . . . . . 13
71 6.1.3. Update notification . . . . . . . . . . . . . . . . . 15
72 6.2. XML Element definitions . . . . . . . . . . . . . . . . . 16
73 6.2.1. WebDAV Properties . . . . . . . . . . . . . . . . . . 16
74 6.2.2. Subscription request . . . . . . . . . . . . . . . . 19
75 7. HTTP Headers for DAV-Push . . . . . . . . . . . . . . . . . . 21
76 7.1. Push-Client-Id Header . . . . . . . . . . . . . . . . . . 21
77 8. Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . 21
78 8.1. Application Servers . . . . . . . . . . . . . . . . . . . 21
79 8.2. Clients . . . . . . . . . . . . . . . . . . . . . . . . . 22
80 8.3. Push Gateway . . . . . . . . . . . . . . . . . . . . . . 22
81 9. Security Considerations . . . . . . . . . . . . . . . . . . . 23
82 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23
83 10.1. Namespace Registration . . . . . . . . . . . . . . . . . 23
84 11. Normative References . . . . . . . . . . . . . . . . . . . . 23
85 Appendix A. Change History (To be removed by RFC Editor before
86 publication) . . . . . . . . . . . . . . . . . . . . 24
87 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 24
89 1. Introduction
91 In a client/server protocol, clients can typically create, update,
92 delete "resources" (data) on the server, as well as retrieve data on
93 the server.
95 In many cases, data can appear on the server as the result of some
96 other client or server-side process interacting with the server.
98 Thus clients need a way to detect when the data on the server has
99 changed.
101 Most protocols provide a data synchronization mechanism to support
102 that, but typically clients need to "poll" the server to find out
103 when changes have occurred. Network based polling is inefficient,
104 and instead push notifications are preferred as a way of alerting
105 clients to new data or changes to existing data on the server
107 2. Conventions Used in This Document
109 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
110 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
111 "OPTIONAL" in this document are to be interpreted as described in
112 [RFC2119]
114 When XML element types in the namespaces "DAV:" and
115 "urn:ietf:params:xml:ns:dav-push" are referenced in this document
116 outside of the context of an XML fragment, the string "DAV:" and
117 "DAV-PUSH:" will be prefixed to the element type names respectively.
119 3. Terminology
121 Application Server Provides resources a client application might
122 want to monitor for changes. Typical applications are email,
123 calendars and address books.
125 Push Gateway A service to provide a common, standardized interface
126 to Push Delivery Services. A Push Gateway provides or relays one
127 or multiple delivery channels, the so called Transports.
129 Push Delivery Service A Service which provides the actual push
130 transport mechanism to the client application.
132 Transport A Transport is a logical channel to a specific Push
133 Delivery Service, provided by a Push Gateway. It is identified by
134 the transport-uri.
136 Client Application An application that uses the services of the
137 Application Server and wants to get notified instantaneously about
138 certain changes on the server. A client application typically
139 runs on a mobile or desktop device.
141 Push Notification A message sent from the Application server to the
142 Client Application to notify the client of an update. The basic
143 information carried by the notification is "there was a change"
144 for a specific Topic.
146 Topic A Topic is a name for a notification feed or channel. Each
147 watchable resource has a Topic that clients can subscribe to.
148 Each subscriber to a particular topic will receive a notification
149 when a substantial change was made to any of the resources with
150 that Topic.
152 4. Architecture
154 This document introduces an entity called "Push Gateway" which acts
155 as a proxy between an application server and a push delivery service.
156 A Push Gateway provides at least one Transport. Each Transport is
157 identified by a URI and connects to exactly one Push Delivery
158 Service.
160 Push Gateways MAY support relaying, so a push gateway might forward
161 all or some notifications to another push gateway.
163 +----------------------------+
164 | Application Server |
165 +-----------------------+----+
166 ^ |
167 | |
168 | |
169 | |
170 | v
171 | +-------------------------+
172 | | Push Gateway |
173 | +---------+---------------+
174 | |
175 | |
176 | |
177 | v
178 | +-------------------------+
179 | | Push delivery Service |
180 | +---------+---------------+
181 | |
182 | |
183 | |
184 | |
185 | v
186 +-----+--------------------+
187 | Client Application |
188 +--------------------------+
190 4.1. Application Server
192 The server is responsible for generating push topics and sending
193 update notifications to the Push Gateway. A push topic is a unique
194 token that identifies the update notification feed of a resource or a
195 group of resources. The topic is forwarded to the Push Gateway
196 whenever a relevant change in one of these resources occurs.
198 This document doesn't specify how topics are generated. However, for
199 privacy reasons the topic MUST NOT contain user names, user data
200 (like folder/collection names) or URLs in plain text. If a server
201 doesn't maintain opaque, anonymous identifiers it SHOULD use a hash
202 algorithm, like SHA256, to generate an opaque identifier from
203 resource properties.
205 Push topics MAY be generated on a per-user base for shared resources.
207 A server MAY change push topics at any time to improve privacy. If
208 doing so the server MUST continue to send out push notifications for
209 the old topic until all subscriptions to that topic have expired.
211 The application server maintains a mapping of subscribed push topics
212 to a list of push gateways. It updates this mapping whenever
214 o A new subscription request is received,
216 o A response from the push gateway indicates that there are no
217 active subscribers for a particular topic.
219 The application server doesn't maintain references to push clients,
220 because this information is opaque to the application server.
222 4.2. Push Gateway
224 The Push Gateway maintains a mapping of push-topics to a list of
225 subscribed clients and expiration times. It updates the list
226 whenever
228 o it receives a new subscription,
230 o a subscription expires or
232 o the Push Delivery Service returns that a specific client is no
233 longer available.
235 If a push message for a specific topic is received the push gateway
236 will notify all clients with an active (not expired) subscription for
237 that topic.
239 A push gateway may relay messages for other gateways. A gateway that
240 supports relaying MUST maintain a map of topics to gateways just like
241 an application server.
243 4.3. Push Delivery Service
245 TBD: Minimum requirements for PDS to support this protocol. Describe
246 what state information the PDS needs to maintain.
248 4.4. Client
250 TBD: what information does the client need to maintain
252 5. Protocol Workflows
254 5.1. App Server <-> Push Gateway bootstrap workflow
256 This protocol allows an application server to initialize the
257 supported push transports by querying a set of configured push
258 gateways. This requires that the application server knows the root
259 URL of each configured gateway. In order to retrieve the list of
260 supported transports it posts a JSON object with an empty list of
261 push-transports to each gateway.
263 The following request shows the bootstrap request of an application
264 server that was configured with the Push Gateway URL
265 https://push.example.com/gateway
267 POST /gateway
268 Host: push.example.com
269 Content-Type: application/json
270 Content-Length: xxx
272 { "push-transports": []}
274 The push gateway responds with a JSON object that contains an array
275 of push transports.
277 HTTP/1.1 200 OK
278 Content-Type: application/json
279 Content-Length: xxx
281 { "push-transports": [
282 {
283 "transport": {
284 "transport-uri":
285 "https://push.example.com/transport",
286 "refresh-interval": 172800,
287 "transport-data" : { ... }
288 }
289 },{
290 "transport": {
291 "transport-uri":
292 "urn:uuid:01234567-0123-0123-0123-0123456789ab",
293 "refresh-interval": 172800,
294 "transport-data" : { ... }
295 }
296 }]
297 }
299 TBD: HTTP status for failure with a XML/JSON error response body
301 5.2. Client <-> App Server workflow
303 The communication between Client and Application Server is defined in
304 the respective application protocol. The application protocol needs
305 to be extended in order to support push.
307 This document describes the general idea behind the required
308 extensions and gives a concrete definition for a WebDAV extension.
310 5.2.1. Client discovery and subscription workflow - Generic
312 TBD:
314 5.2.2. Unsubscribe
316 This document doesn't specify an explicit unsubscribe method. A
317 client that doesn't wish to receive any further push notifications
318 for a specific topic, MAY send a subscription with an expiration date
319 in the past.
321 An application server which receives such a subscription MUST handle
322 it like any other subscription. In particular the Application Server
323 MUST
324 o verify the Push Topic and
326 o forward the susbcription to the Push Gateway.
328 A Push Gateway which receives a subscription with a passed expiration
329 date MUST
331 o remove the client from the list of subscribers to this topic and
333 o not send out any further push messages to this client.
335 5.2.3. Client discovery and subscription workflow - WebDAV
337 5.2.3.1. Push discovery
339 The following example shows a PROPFIND request on a user's calendar
340 home to discover push support.
342 PROPFIND http://calendar.example.com/calendars/
343 Content-Type: application/xml
344 Depth: 0
345 Content-Length: xxx
347
348
349 />
350
351
352
353
354
356 The server responds with the respective properties. In this
357 particular case the server added an empty P:transport element to
358 signal it will accept any transport provided by the client. >
359 Response
360 HTTP/1.1 207 Multistatus
361 Content-Type: application/xml; charset=UTF-8
362 Content-Length: xxx
364
365
366 /calendars/
367
368
369
370 https://calendar.example.com/subscribe
371
372
373
374
375 urn:uuid:01234567-0123-0123-0123-0123456789ab
377
378 ...
379
380 172800
381
382
383 https://push.example.com/transport
385
386 ...
387
388 172800
389
390
391 123
392 1
393
394 HTTP/1.1 200 OK
395
396
397
399 5.2.3.2. Push subscribe
401 Calendar server -> Client - CS server advertises its supported push
402 mechanisms Clients request POST to P:subscribe-URL - does the actual
403 subscription to the calendar server:
405 POST /subscribe HTTP/1.1
406 Host: calendar.example.com
407 Content-Type: application/xml; charset=UTF-8
409
410 123
411 abc
412
413 https://push.example.com/transport
415 XYZ
416
417 2017-10-07T12:00:00Z
418
420 If one or more topics are invalid the enitre request MUST fail
421 without any subscriptions being recorded. In this case the server
422 MUST return an error response containg a list of topics that failed.
423 If a topic is valid but the authenticated user doesn't have access to
424 any of the resources that the topic belongs to, the server SHOULD
425 treat this topic as being invalid and the request SHOULD fail.
427 TBD: response
429 5.3. App Server -> Push Gateway subscribe workflow
431 When a client sends a request to subscribe to specific topics, the
432 application server MUST foward the subscription to the chosen gateway
433 or to the gateway that announced itself as a proxy for the chosen
434 gateway.
436 If a gateway acts as a proxy for another gateway it MUST forward the
437 request to the proxied gateway.
439 The following example shows a request to subscribe to two topics.
441 POST / HTTP/1.1
442 Host: push.example.com
443 Content-Type: application/json
445 {
446 "push-subscribe": {
447 "topics": [ "123", "abc" ],
448 "transport": {
449 "transport-uri": "https://push.example.com/transport",
450 "client-data": "XYZ"
451 },
452 "expires": "2017-10-07T12:00:00Z"
453 }
454 }
456 Response: HTTP status for success, or HTTP status for failure with a
457 XML/JSON error response body To acknowledge the subscription the
458 gateway SHOULD send an initial PUSH notification to the client.
460 TBD: responses A successful response containt the URL to send update
461 messages to. The URL may be different than the transport URL. An
462 Application Server MUST use this URL when sending push notifications
463 to transports provided by clients.
465 HTTP/1.1 200 OK
466 Content-Type: application/json
468 { "push-url": "https://push.example.com/" }
470 5.4. App Server -> Push Gateway push workflow
472 Whenever a substantial change occurs in any of the resources, the
473 application server sends a Push Message to the gateway containing the
474 Topics of the resources that have changed. The following example
475 sends a push notification for the Topics "123" and "abc". The
476 message for Topic "123" also contains a "client-id" to omit any
477 notification to the sole client that modified the resource and caused
478 this push message. The second message has a low priority and no
479 "client-id". Such a message could be generated by multiple clients
480 acknowledging an alarm on a shared calendar.
482 POST / HTTP/1.1
483 Host: push.example.com
484 Content-Type: application/json
486 {
487 "push": {
488 "messages" : [{
489 "topic": "123",
490 "priority": 100,
491 "timestamp": "2017-10-01T14:00:52Z",
492 "client-id": "xyz"
493 }, {
494 "topic": "abc",
495 "priority": 0,
496 "timestamp": "2017-10-01T14:00:53Z"
497 }]
498 }
499 }
501 Response: HTTP status for success, or HTTP status for failure with a
502 XML/JSON error response body It's not an error if a topic is unknown
503 or there are no active subscribers for this topic. Instead the
504 response will contain a list of all topics without subscribers. The
505 application server SHOULD update its topic-to-gateway mapping
506 accordingly. The application server MUST assume that topics which
507 were in the request and not in the "no-subscribers" list have been
508 pushed to the client. If there is a subscriber for each topic in the
509 request, the no-subscribers list MUST be omitted.
511 HTTP/1.1 200 OK
512 Content-Type: application/json
514 { "push-response": {} }
516 If there are topics without active subscribers:
518 HTTP/1.1 200 OK
519 Content-Type: application/json
521 {
522 "push-response": {
523 "no-subscribers": [
524 { "topic": "123"}
525 ]
526 }
527 }
529 6. Syntax Elements/Properties
531 6.1. Push gateway protocol
533 6.1.1. Bootstrapping
535 ; root element
536 root {
537 push-transports
538 }
540 ; a list of push transports supported by a gateway
541 ; in the request sent by the application server this is empty
542 push-transports "push-transports" [
543 * transport
544 ]
546 transport "transport" {
548 ; The uri of the transport.
549 "transport-uri" : uri,
551 transport-data?
552 }
554 ; optional data the client needs to know in order to subscribe
555 ; to allow easy conversion to other formats,
556 ; this object MUST NOT contain structured data.
557 transport-data "transport-data" {
558 ^"": any
559 }
561 6.1.2. Subscription
562 ; root element
563 root {
564 push-subscribe
565 }
567 ; the object describing the subscription
568 push-subscribe "push-subscribe" {
569 topic-list,
570 selected-transport,
571 expires
572 }
574 ; The list of topics to subscribe to. Unless a previous
575 ; subscription is updated by a request, existing
576 ; subscriptions won't be affected by new subscriptions.
577 topic-list "topics" [
578 * topic
579 }
581 ; The chosen transport type
582 selected-transport "selected-transport" {
584 ; The transport-uri of the chosen transport
585 "transport-uri" : uri,
587 ; The client-data string as sent by the client
588 "client-data" : string
589 }
591 ; The time of when the subscription expires
592 ; must be a UTC timestamp following
593 ; https://tools.ietf.org/html/rfc3339
594 expires "expires" : RFC 3339 timestamp
595 ; root element
596 root {
597 error
598 }
600 ; the object describing the failure
601 error "error" {
602 invalid-topic-list
603 }
605 ; The list of topics that the user can't subscribe to
606 invalid-topic-list "invalid-topics" [
607 1* topic
608 }
610 6.1.3. Update notification
612 ; The root object
613 root {
614 "push" [ 1* message ]
615 }
617 ; A message object, describing the update
618 message {
619 topic,
620 ? priority,
621 timestamp,
622 ? client-id
623 }
625 ; The topic of the resource that has been updated
626 topic "topic" : string
628 ; The priority of the change, with 0 being the lowest and 100
629 ; being the highest priority
630 ; If omitted, implementations SHOULD default to 50.
631 priority "priority" : integer 0..100
633 ; The time of when the change occurred. The value MUST be a
634 ; timestamp in UTC following https://tools.ietf.org/html/rfc3339
635 ; If the server aggregated multiple updates before sending the push
636 ; message, this MUST be the timestamp of the most recent update.
637 timestamp "timestamp" : RFC 3339 timestamp
639 ; An optional id that identifies the client that triggered the update
640 ; notification. Push gateways can use this information to suppress
641 ; push messages to this particular client, in order to avoid
642 ; unnecessary sync operations.
643 ; If the server aggregated multiple updates from different clients
644 ; into one message, it MUST omit the client-id to ensure all clients
645 ; receive the push message.
646 client-id "client-id": string
648 ; root element of the push subscribe response
649 root {
650 ? no-subscribers-list
651 }
653 ; A list of topics without active subscribers.
654 ; Applications servers SHOULD not send further push messages for the
655 ; enlisted topics to this transport unless a new client subscribes on
656 ; this transport.
657 no-subscribers-list "no-subscribers" [
658 1* topic }
659 ]
661 6.2. XML Element definitions
663 6.2.1. WebDAV Properties
665 6.2.1.1. DAV-PUSH:push-subscribe-URL
667 Name: push-subscribe-URL
669 Namespace: urn:ietf:params:xml:ns:dav-push
671 Purpose: Specifies the address to send the subscription requests to.
673 Description: The push-subscribe-URL element contains exactly one
674 DAV:href element with a URL that points to the subscription
675 service endpoint.
677 Definition:
679
681 6.2.1.2. DAV-PUSH:supported-transport-set
683 Name: supported-transport-set
685 Namespace: urn:ietf:params:xml:ns:dav-push
687 Purpose: Specifies a list of transports supported by the application
688 server.
690 Description: This element contains the set of push transports
691 supported by the server. The transport-uri element of each
692 transport must be unique within the set of transports.
694 The set MAY contain one transport element without any child
695 elements to indicate that the client may provide its own
696 transport.
698 Definition:
700
702 6.2.1.3. DAV-PUSH:transport
704 Name: transport
706 Namespace: urn:ietf:params:xml:ns:dav-push
708 Purpose: Describes a specific transport.
710 Description: A transport element represents a specific push
711 transport path to clients on a specific service. In general it
712 contains a transport-uri element that uniquely identifies the
713 transport.
715 Definition:
717
720 6.2.1.4. DAV-PUSH:transport-uri
722 Name: transport-uri
724 Namespace: urn:ietf:params:xml:ns:dav-push
726 Purpose: Specifies the URI that identifes the transport.
728 Description: Clients compare the provided transport-uris to the
729 transport-uris they support.
731 Definition:
733
734 PCDATA value: The URI identifying the transport.
736 6.2.1.5. DAV-PUSH:transport-data
738 Name: transport-data
740 Namespace: urn:ietf:params:xml:ns:dav-push
742 Purpose: Contains a list of additional attributes that client needs
743 to know in order to subscribe on this transport.
745 Description:
747 Definition:
749
751 6.2.1.6. DAV-PUSH:refresh-interval
753 Name: refresh-interval
755 Namespace: urn:ietf:params:xml:ns:dav-push
757 Purpose: Specifies the maximum refresh interval.
759 Description: Specifies the duration in seconds after which the
760 client is expected to re-subscribe. If the client didn't res-
761 subscribe within this period of time the gateway MUST remove all
762 subscriptions and no further push notifications will be delivered
763 to the client until it subscribes again.
765 A Push Gateway MUST not accept subscription requests with an
766 expiration time that would exceed the refresh interval.
768 Definition:
770
771 PCDATA value: the maximum refresh interval in seconds
773 6.2.1.7. DAV-PUSH:topic
775 Name: topic
777 Namespace: urn:ietf:params:xml:ns:dav-push
779 Purpose: Specifies the push topic of a resource.
781 Description: The topic identifies the name of the update channel for
782 a resource. Clients send the topic in a subscription request to
783 inform application server and gateway that it wants to receive
784 update notifications for the resource.
786 This document doesn't specify a specific format for topics nor a
787 specifc algorithm to generate them.
789 Server developers MUST ensure that topics on different
790 installations won't collide.
792 Resources within the same domain MAY share topics.
794 Definition:
796
797 PCDATA value: the push topic
799 6.2.1.8. DAV-PUSH:version
801 Name: push-version
803 Namespace: urn:ietf:params:xml:ns:dav-push
805 Purpose: Specifies the highest version number of the push protocol
806 supported by this server.
808 Description:
810 Definition:
812
813 PCDATA value: the highest push protocol version number
814 supported by the application server
816 6.2.2. Subscription request
818 6.2.2.1. DAV-PUSH:subscribe
820 Name: subscribe
822 Namespace: urn:ietf:params:xml:ns:dav-push
824 Purpose: Represents a subscription request document.
826 Description: The subscribe request contains all information to
827 subscribe to specific topics selecting a specific transport to
828 deliver push notifications.
830 A subscription must have an expiration date after which the
831 subscriptions will become void.
833 Definition:
835
838 6.2.2.2. DAV-PUSH:selected-transport
840 Name: selected-transport
842 Namespace: urn:ietf:params:xml:ns:dav-push
844 Purpose: Specifies the transport the client has chosen.
846 Description: The selected-transport element contains the transport-
847 uri of the transport that the client has chosen for push delivery.
848 It also contains a client-data element to be forwarded to the push
849 gateway.
851 Definition:
853
856 6.2.2.3. DAV-PUSH:client-data
858 Name: client-data
860 Namespace: urn:ietf:params:xml:ns:dav-push
862 Purpose: Contains a string the client needs to provide to the push-
863 gateway for the chosen transport.
865 Description: This element provides a mechanism for the client to
866 communicate to the gateway. The format of the data string is not
867 defined in this document. The application server MUST forward the
868 client-data string as provided by the client.
869 Gateways SHOULD use this to authenticate clients.
871 Definition:
873
874 PCDATA value: client data as required by the push gateway
875 Name: invalid-topics (precondition)
877 Purpose: The request could not succeed, because it contained
878 invalid push topics. This element contains one topic element
879 for each rejected push topic. The client may repeat the
880 request without those topics.
882 Definition:
884
886 7. HTTP Headers for DAV-Push
888 7.1. Push-Client-Id Header
890 Push-Client-Id = "Push-Client-Id" ":" token
892 The client sends this header to identify itself to the application
893 server as the modifying instance. If the application server didn't
894 coalesce multiple updates from different clients into a single push
895 message, it SHOULD include the value in the update notification
896 message. The provided token ([RFC7230]) MUST be percent-encoded as
897 per[RFC3986]. Gateways can use this information to suppress push
898 messages to this particular client.
900 The actual value of token is part of the contract between client and
901 gateway. The token MUST NOT contain any sensitive data like user
902 name or device identifiers. It SHOULD be either a random or an
903 obfuscated token (using a cryptographic hash function).
905 8. Guidelines
907 8.1. Application Servers
909 Servers may want to implement some form of "keep-alive" within the
910 push protocol to ensures clients know they are still connected in
911 cases where actual data changes happen at long intervals (e.g., a
912 calendar user who only makes changes once a day)
914 Priorities: Range 0 - 100 - 0 is lowest and 100 is highest e.g.: low
915 priority - updates due to other attendees changing their partstat
916 high priority - updates to events ocurring in the next 24 hours
917 Priority is used by a client to indicate what level of push they want
918 at a specific time. It can also be used by the push gateway or push
919 delivery system to throttle push notifications to the client based on
920 load.
922 Servers MAY delay the delivery of push notifications for several
923 seconds in order to coalesce notifications. This is useful to give
924 the server a certain amount of control over the client's behavior
925 during times of high load.
927 Servers MUST NOT coalesce push notifications based on priority.
929 Application servers MAY allow clients to provide their own
930 transports. If the transport-uri is not among the transport-uris as
931 advertised by the application server, the transport-uri MUST be an
932 HTTPS URL. If a client sends such a transport-uri, the application
933 server SHOULD perform a transport discovery on the provided URL to
934 discover all transports supported on this gateway.
936 8.2. Clients
938 Clients MUST be prepared that they might receive an initial push
939 notification that acknowledges the subscription before the response
940 to the push-subscribe request has been received.
942 Clients SHOULD NOT rely solely on push notifications. The framework
943 described in this document does not make any guarantees about the
944 delivery of a push notification. Clients should be prepared to
945 trigger a synchronization themselves if no push message has been
946 received within some time period.
948 Clients can expect that sometimes they will get a push but then not
949 detect any actual changes when they sync (i.e., "no-op" push from
950 server as a "keep-alive" mechanism).
952 8.3. Push Gateway
954 A Push Gateway SHOULD require some kind of authentication to be
955 encoded in the client-data string. This document doesn't specify any
956 authentication methods. However, among others, encrypting the
957 client-data string with a shared secret and digitally signing the
958 data are two possible options to achieve this.
960 Client data MAY contain additional per-client preferences, like
961 minimum priority to deliver or maximum delay of notifications when
962 doing coalescing. This is part of the contract between client and
963 transport an not subject of this specification.
965 Gateways MAY coalesce push notifications based on priority.
967 9. Security Considerations
969 To prevent abuse of the service, Push Gateways SHOULD require either
970 servers or clients or both to authenticate. Servers SHOULD
971 authenticate every request of Protocol #2 via HTTP.
973 Push Gateways use the information to authenticate
974 subscription requests from a Server by relating them to Client
975 authorization requests. Clients will typically be authenticating to
976 Servers to access protected data on the server and thus SHOULD
977 authenticate when using Protocol #1.
979 10. IANA Considerations
981 This document uses a URN to describe a new XML namespace conforming
982 to the registry mechanism described in[RFC3688].
984 10.1. Namespace Registration
986 Registration request for the push namespace:
988 URI: urn:ietf:params:xml:ns:dav-push
990 Registrant Contact: The IESG
992 XML: None - not applicable for namespace registrations.
994 11. Normative References
996 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
997 Requirement Levels", BCP 14, RFC 2119,
998 DOI 10.17487/RFC2119, March 1997,
999 .
1001 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
1002 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
1003 .
1005 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
1006 DOI 10.17487/RFC3688, January 2004,
1007 .
1009 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
1010 Resource Identifier (URI): Generic Syntax", STD 66,
1011 RFC 3986, DOI 10.17487/RFC3986, January 2005,
1012 .
1014 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
1015 Protocol (HTTP/1.1): Message Syntax and Routing",
1016 RFC 7230, DOI 10.17487/RFC7230, June 2014,
1017 .
1019 Appendix A. Change History (To be removed by RFC Editor before
1020 publication)
1022 Changes in -01:
1024 1.
1026 Author's Address
1028 Marten Gajda
1029 dmfs GmbH
1030 Schandauer Strasse 34
1031 Dresden 01309
1032 Germany
1034 Email: marten@dmfs.org
1035 URI: http://dmfs.org