idnits 2.17.1 draft-cohen-gena-p-base-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 4 longer pages, the longest (page 6) being 63 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 12 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 171 instances of too long lines in the document, the longest one being 7 characters in excess of 72. ** There is 1 instance of lines with control characters in the document. == There is 2 instances of lines with non-RFC2606-compliant FQDNs in the document. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 217: '... header then the method MUST fail with...' RFC 2119 keyword, line 301: '... Support for batch mode is OPTIONAL....' Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 38 has weird spacing: '...ription that ...' == Line 42 has weird spacing: '...sources for e...' == Line 242 has weird spacing: '...es that an ht...' == Line 325 has weird spacing: '...mantics depen...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (July 9, 1998) is 9395 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) -- Missing reference section? 'Bradner' on line 580 looks like a reference -- Missing reference section? '1996' on line 580 looks like a reference Summary: 10 errors (**), 0 flaws (~~), 8 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET DRAFT J. Cohen, Microsoft 2 S. Aggarwal, Microsoft 3 Expires January 1, 1999 July 9, 1998 5 General Event Notification Architecture Base 7 Status of this memo 9 This document is an Internet-Draft. Internet-Drafts are working documents 10 of the Internet Engineering Task Force (IETF), its areas, and its working 11 groups. Note that other groups may also distribute working documents as 12 Internet-Drafts. 14 Internet-Drafts are draft documents valid for a maximum of six months and 15 may be updated, replaced, or made obsolete by other documents at any time. 16 It is inappropriate to use Internet-Drafts as reference material or to 17 cite them other than as "work in progress". 19 To learn the current status of any Internet-Draft, please check the "1id- 20 abstracts.txt" listing contained in the Internet-Drafts Shadow Directories 21 on ftp.is.co.za (Africa), nic.nordu.net (Europe), munnari.oz.au (Pacific 22 Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast). 24 Distribution of this document is unlimited. Please send comments to the 25 HTTP working group at . Discussions of the 26 working group are archived at . 28 Abstract 30 This specification defines an HTTP notification architecture that 31 transmits notifications between HTTP resources. An HTTP resource could be 32 any object which might need to send or receive a notification, for example 33 a distribution list, buddy list, print job, etc. 35 Introduction 37 The protocol definition provides two main components notification and 38 subscription that can be used independently or in combination. 40 Any resource can transmit a notification through HTTP to any other 41 resource through the NOTIFY method. Notifications can be triggered by 42 arbitrary events occurring on originating resources for example, a 43 change in the properties of a resource, a notification received by the 44 originating resource, or any other general event. 46 Additionally, a resource can establish a subscription relationship with 47 any other resource and thereby automatically receive a notification when a 48 specified event occurs on the latter resource. 50 The notification framework defined herein thus provides powerful 51 capabilities to track arbitrary properties on resources on a real-time 52 basis, such as remote filesystem properties, buddy list online presence 53 information, device availability, etc. The notification framework also 54 allows for more complex routing schemes, such as routing notifications 55 through a succession or hierarchy of resources or sending a notification 56 to more than one resource. 58 This specification defines the syntax and semantics for asynchronous and 59 polled notification delivery. Asynchronous notifications allow a 60 subscription server to send an event notification at any time, without 61 maintaining a persistent network connection. Polled notifications allow a 62 backward compatible, although less elegant, mechanism for notification 63 delivery across a deployed infrastructure of proxy servers and firewalls. 64 The set of delivery mechanisms is extensible. 66 1 Definitions 68 1.1 Resource 70 A resource is any entity with a URI address that wishes to participate in 71 this notifications protocol. 73 1.2 Event 75 Any change in a resource that potentially needs to trigger an event 76 notification. 78 1.3 Subscription 80 An established relationship in which a resource has indicated interest in 81 certain events. 83 1.4 Subscriber 85 A resource that negotiates a subscription with a subscription server. 87 1.5 Implied Subscriber 89 A resource that did not negotiate a subscription with a subscription 90 server but will still be notified of events on that server. 92 1.6 Subscribed Resource 94 A subscribed resource is a resource that is the subject of a subscription. 96 1.7 Event Notification 98 An event notification is a message sent by a subscribed resource to its 99 subscribers, implied and otherwise, notifying them of an event on that 100 resource. 102 2 New HTTP Methods 104 Notification and subscription messages are transmitted via new HTTP 105 methods. 107 2.1 Subscription Methods 109 2.1.1 SUBSCRIBE 111 The SUBSCRIBE method is used to subscribe to a subscription server. 113 2.1.2 UNSUBSCRIBE 114 The UNSUBSCRIBE method is used to terminate a subscription. 116 2.2 Delivery Methods 118 2.2.1 NOTIFY 120 NOTIFY is used for asynchronous notification delivery from one resource to 121 another. The Request-URI is the URI of the resource to be notified. 123 2.2.2 POLL 125 POLL is used to check a resource for pending events. When a POLL request 126 occurs, the Request-URI is the URI of the subscribed resource. 128 3 Subscriptions 130 3.1 SUBSCRIBE request 131 A subscriber subscribes to subscription servers via the SUBSCRIBE method. 133 The Request-URI specifies the URI of the resource being subscribed to. 135 The following headers are provided (detailed header definitions are given 136 in a later section): 138 3.1.1 Notification-Type 140 Notification-Type indicates the type of event being subscribed to 142 3.1.2 Call-Back 144 Call-Back indicates how event notifications are to be delivered from the 145 subscription server to the subscriber 147 3.1.3 Subscription-Lifetime 149 Subscription-Lifetime indicates when the subscription is to expire. 151 3.2 SUBSCRIBE responses 153 The response to a SUBSCRIBE method must include a Subscription-ID header 154 that uniquely identifies the subscription. 155 The response must also include the Delivery-Scheme and Subscription- 156 Lifetime headers, with possibly adjusted values. 158 4 Delivery Mechanisms 160 Subscribers use the call-back or delivery-control header to specify the 161 method requested for delivering notifications, as well as any parameters 162 associated with the method. 164 This document defines two delivery schemes Asynchronous and Polled. The 165 set of delivery schemes is extensible. 167 4.1 Asynchronous 169 Asynchronous notification delivery occurs through a NOTIFY HTTP message 170 from the subscription server to the subscriber. This behavior may cause 171 problems with some existing systems which expect HTTP requests to initiate 172 from inside of the firewall. 174 4.2 Polled 176 Polled delivery indicates that the subscription client will poll the 177 resource at a specified interval agreed upon by the server and the client. 179 A Poll-Interval parameter specifies intent to issue the next POLL after 180 the specified Poll-Interval; the server may buffer notifications until the 181 next POLL. Subsequent POLL requests may also have a Poll-Interval header 182 specifying the requested duration until the next POLL. 184 A wait-timeout parameter specifies a request for the server to keep the 185 SUBSCRIBE connection open until the timeout value expires or a 186 notification is received. [[Issue: does Connection-timeout conflict with 187 HTTP? ]] The wait-timeout header can also appear on a POLL request, with 188 identical semantics. 190 5 New HTTP Headers 192 5.1 Notification-Type General Header 194 The Notification-Type request header is used with a SUBSCRIBE request 195 message to indicate the requested notification type. 197 The Notification-Type response header is used with a SUBSCRIBE response to 198 indicate the accepted notification type. 200 Notification-type := notification-Type: ntype 202 Ntype := gena:update | ntype-extension 203 Ntype-extension := < URL > 205 This draft declares one base notification type, gena:update. 207 5.2 Call-Back General Header 209 The call-back request header is used with a SUBSCRIBE request to indicate 210 the subscriber's preferred call-back addresses. 212 The call-back response header is used with a SUBSCRIBE response to 213 indicate the order in which the subscription server intends to call the 214 listed addresses. If an address submitted with a call-back request header 215 is not listed in the call-back response header then the server has 216 rejected its use. If the server can not accept any of the addresses 217 specified in the call-back request header then the method MUST fail with 219 The format of the call-back header is an ordered list of space separated 220 URIs. 222 The call-back parameter is an ordered series of URIs in a space separated 223 string. Each URI represents an event notification receiver interested in 224 receiving notifications (via NOTIFY or other methods) when a triggering 225 event occurs on the subscribed resource. 227 The call-back with the highest preference is listed first while the call- 228 back with the least preference is listed last in the string. 230 Call-back := Call-Back: URI [ URI ] 232 An example call-back header: 234 Call-Back: http://switchblade.microsoft.com:8888/mailclient 235 mailto:joshco@microsoft.com 237 This example indicates a preferred call-back via HTTP to the switchblade 238 machine on port 8888 and a secondary call-back via an email to 239 joshco@microsoft.com 241 URIs can be any valid URI type. For example, an http URI like 242 http://foo:port/bar indicates that an http transaction via NOTIFY is to 243 be sent upon event notification. An httpu URI like 244 Httpu://address:port/ indicates that a UDP datagram containing an HTTP 245 request with NOTIFY is to be sent. A mail URI like mailto:user@domain 246 indicates that an email message containing the same HTTP message with 247 NOTIFY is to be sent as the body of an email message. 249 5.3 Subscription-Lifetime: 250 This is used on a SUBSCRIBE request as well as response. The requester 251 indicates the timeout it is requesting. The responder may respond with 252 the same or different timeout, but the responder's value is binding. 254 Subscription-Lifetime: 1*DIGIT 256 In seconds. 258 5.4 Delivery-control: 260 This can be used on a SUBSCRIBE response, or a POLL request or response. 261 (Subscribe requests have an analogous version within the Delivery-Scheme 262 header.) In a request, the value indicates the Delivery-control the 263 client would like; the server responds with the Delivery-control 264 acceptable to it, which may be different from the requested Delivery- 265 control. 267 The Delivery-control header is a generic control mechanism for poll 268 related parameters. 270 Delivery-control := Delivery-control: 1#poll-parameter 271 Poll-parameter := poll-interval | wait-time | poll-provoke | batch-mode 273 Wait-time := wait-time = seconds 274 Poll-Interval := poll-interval = seconds 275 Poll-provoke := poll-provoke 276 Batch-Mode := multipart/related 278 Wait-time: Specifies in seconds how long the client requests the server to 279 keep the connection open (the server may close the connection earlier, at 280 its discretion). 282 Poll-Interval: On request, specifies the requested polling interval 283 initiated by the subscriber. On response, it indicates the servers 284 adjusted recommended poll-interval. 286 Poll-Provoke: The poll-provoke keyword is typically used in a NOTIFY 287 message, possibly over UDP, to indicate to the subscriber that a 288 notification has occurred and to poll the server for the details. This is 289 included as a security measure for unencrypted and or datagram 290 notifications where eavesdropping is common. This allows the server to 291 enforce ACLs on the subsequent provoked poll. 293 Batch-Mode: The batch mode parameter specifies if and how multiple event 294 notifications may be batched together into a single notification message. 295 In a request, the batch-control parameter indicates the preferred method 296 of batching from the subscriber. In a response, the batch-control 297 parameter indicates the allowed method on the server. This draft specifies 298 a single batch mechanism for multipart/related multipart MIME. It is 299 specified later in this document. Future specifications may define 300 additional batch mechanisms such as XML. 301 Support for batch mode is OPTIONAL. 303 5.5 Mandatory header for version control: 305 The GENA architecture makes use of the Mandatory specification as part of 306 the HTTP extension framework. [ 13.3 ] 308 5.6 Mandatory feature use 309 This is included on every request and response, to indicate the 310 notifications protocol version for cross-compatibility. 312 Mandatory := Man: tokenURI 314 This draft specifies the version token URI: 315 http://extensions.iana.org/http/GENA/ 317 This token is expressed as a URI for use with a future http extension 318 framework such as Mandatory [13.3] 320 5.7 Subscription-ID 322 This is contained in initial SUBSCRIBE responses, on all subsequent 323 SUBSCRIBE requests (for renewing existing subscriptions), on all POLL and 324 UNSUBSCRIBE requests, and on NOTIFY requests generated as a result of a 325 prior subscription. [[Issue: exact subscription ID semantics depends on 326 whether we have a From header.]] 328 Subscription-ID:= subscription-id = string 330 5.8 Route-ID: 332 Route-ID: indicates a route identifier for the message. Each proxy or 333 gateway in the path should append a route-id header to the subscription 334 message. When adding a new route-ID header, the proxy should use an 335 integer greater than the current highest in the rid field. 337 Syntax: 338 Route-ID: rid ; route-options 339 rid := integer 340 route-options := delivery-uri = URI 342 5.9 Depth Header 344 Depth = "Depth" ":" ("0" | "1" | "infinity") 346 The Depth header is used with methods executed on resources which could 347 potentially have internal members to indicate whether the method is to be 348 applied only to the resource (Depth = 0), to the resource and its 349 immediate children, (Depth = 1), or the resource and all its progeny 350 (Depth = infinity). 352 5.10 Extended-Response Header 354 Extended-Response := Extended-Response: response-code ; #(ext- 355 param) 357 Ext-param := namespace | comment-field 359 Response-code := numeric-digits 360 Namespace := ns = URI 361 Comment-field := comment = string 363 Example: 364 Extended-Response: 10219 ; ns = http://microsoft.com/gena comment = 365 subscription failed 367 5.11 The URI scheme httpu: 368 The URI scheme httpu: is defined to include a host and a port to which a 369 UDP datagram can be sent. It is specified as a URI with scheme `httpu'. 371 When used with the notification system, the payload of the UDP datagram is 372 to be the same as the HTTP messages defined here as well. 374 6 Response Codes 376 In addition to various HTTP response code messages, GENA response code 377 messages are also defined. These messages are returned through the 378 Extended-response header. 380 GENA responses are comprised of a major response code number and an 381 optional minor response code number. GENA responses always use an 382 appropriate x00 code as the major response code, and a minor response code 383 indicated with the Extended-Response code header. 385 HTTP response codes used for general responses: 387 200 Success 388 401 Authorization Required 389 In other cases, rather than allocate arbitrary response codes from the 390 already limited HTTP response code namespace, extended responses are used. 392 When used to indicate a successful operation, the 200 Ok HTTP response 393 code indicates the major response code, and the minor response code may 394 be: 396 20241 Subscription Succeeded 397 20242 Notification Acknowledged 398 20243 Subscription Terminated 400 When used to indicate an operation failure, the 400 HTTP response code 401 indicates the major response code, and the minor response code may be: 403 20441 Subscription Failed 404 20442 No valid call-backs 405 20443 Unsupported Notification-Type 407 7 Proxy Routing 409 Often, a client may reach a resource via a proxy server. In this case, 410 with a standard proxy server, asynchronous call-back addresses may not be 411 visible to an external server. Because of this, the Route-ID: header is 412 introduced. 414 Subscription clients should poll their proxy chain to detect which version 415 of HTTP that proxy supports. In addition, they should poll for support of 416 the `route-id' extension. This polling should be done via OPTIONS. 418 This draft does not address fan-out or aggregation of subscriptions or 419 notification delivery. 421 7.1 Example OPTIONS request 422 The proxy is myproxy.my.com on port 8080 424 OPTIONS * HTTP/1.1 425 Host: myproxy.my.com:8080 426 Compliance: uri=http://ietf.org/http-ext/route-id 428 Compliance: uri=http://ietf.org/http/v11 430 A successful response: 431 HTTP/1.1 200 Ok 432 Compliance: uri=http://ietf.org/http-ext/route-id 433 Compliance: uri=http://ietf.org/http/v11 435 Lack of a successful response indicates non-compliance with HTTP/1.1 and 436 Route-ID extensions. 438 7.2 Routing with a compliant Proxy 440 Compliant proxy servers are expected to include a Route-ID header as 441 they forward subscription request messages. As they include the route-id 442 header, the rid parameter is to be an integer greater than the highest rid 443 parameter of any other route-id header already in a message. This 444 allows a deterministic route list for the message transit. 446 Servers who send responses to messages which include route-id headers are 447 expected to consume the highest rid parameter route-id header, strip it 448 from the message and use that address as the connection proxy for 449 notification delivery. 451 7.3 Routing with a non-compliant Proxy 453 Since no deterministic way exists to determine an appropriate call-back 454 path for notification delivery, subscribers should NOT select asynchronous 455 call-back as a delivery type. 457 8 Examples 459 SUBSCRIBE URI HTTP/1.1 460 Notification-Type: CoreNotificationType 461 Call-back: URI [ URI ] 462 Delivery-control: poll-interval = seconds 463 Subscription-Lifetime: seconds 464 Notification-Version: 1.0 466 200 Subscribed 467 Notification-Version: 1.0 468 Call-back: [ accepted callback URIs] 469 Delivery-control: poll-interval = acc 470 Subscription-Lifetime: seconds 471 Subscription-ID: FFFFF 473 NOTIFY cbURI HTTP/1.1 474 Subscription-ID: FFFF (optional) 475 Notification-Type: UPDATE 476 Notification-Version: 1.0 477 Content-Type: 479 HTTP/1.1 200 Notification Acknowledged 481 [NOTIFY without subscription-ID is meant for 482 Unsolicited notifications like the IM case.] 484 POLL URI HTTP/1.1 485 Subscription-ID: FFFF 486 Delivery-control: Wait-time=20 488 200 None pending 489 Server: NSERV/1.0 490 Date: Tue Jan 05, 2068 492 POLL URI HTTP/1.1 493 Subscription-ID: FFFF 494 Delivery-control: Wait-time=20 496 200 Notification 497 Subscription-ID: FFFF 498 Notification-Type: UPDATE 500 UNSUBSCRIBE uri HTTP/1.1 501 Subscription-Id: NNN 502 Call-back: uri 504 HTTP/1.1 200 Ok 505 Extended-Response: 20243 ; ns=http://extension.iana.org/http/GENA/1/1/1; 506 comment = Subscription Terminated 508 9 Security Considerations 510 Servers responding to subscription requests should be careful to implement 511 a rational security policy for subscriptions which protects the event 512 notification data about resources as well as the resources themselves. 513 Allowing a subscriber to receive notifications on a resource which that 514 subscriber would not normally have access to may unknowingly reveal 515 information about that resource or the contents itself. 517 10 IANA Considerations 519 This document introduces a new entry into an HTTP extension registry. 520 This extension is: 522 http://extension.iana.org/http/GENA/1/1/1 524 11 Copyright 526 The following copyright notice is copied from RFC 2026 [Bradner, 1996], 527 Section 10.4, and describes the applicable copyright for this document. 529 Copyright (C) The Internet Society February 10, 1998. All Rights Reserved. 531 This document and translations of it may be copied and furnished to 532 others, and derivative works that comment on or otherwise explain it or 533 assist in its implementation may be prepared, copied, published and 534 distributed, in whole or in part, without restriction of any kind, 535 provided that the above copyright notice and this paragraph are included 536 on all such copies and derivative works. However, this document itself 537 may not be modified in any way, such as by removing the copyright notice 538 or references to the Internet Society or other Internet organizations, 539 except as needed for the purpose of developing Internet standards in which 540 case the procedures for copyrights defined in the Internet Standards 541 process must be followed, or as required to translate it into languages 542 other than English. 544 The limited permissions granted above are perpetual and will not be 545 revoked by the Internet Society or its successors or assignees. 547 This document and the information contained herein is provided on an "AS 548 IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE 549 DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO 550 ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY 551 RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A 552 PARTICULAR PURPOSE. 554 12 Intellectual Property 556 The following notice is copied from RFC 2026 [Bradner, 1996], Section 557 10.4, and describes the position of the IETF concerning intellectual 558 property claims made against this document. 560 The IETF takes no position regarding the validity or scope of any 561 intellectual property or other rights that might be claimed to pertain to 562 the implementation or use other technology described in this document or 563 the extent to which any license under such rights might or might not be 564 available; neither does it represent that it has made any effort to 565 identify any such rights. Information on the IETF's procedures with 566 respect to rights in standards-track and standards-related documentation 567 can be found in BCP-11. Copies of claims of rights made available for 568 publication and any assurances of licenses to be made available, or the 569 result of an attempt made to obtain a general license or permission for 570 the use of such proprietary rights by implementers or users of this 571 specification can be obtained from the IETF Secretariat. 573 The IETF invites any interested party to bring to its attention any 574 copyrights, patents or patent applications, or other proprietary rights 575 which may cover technology that may be required to practice this standard. 576 Please address the information to the IETF Executive Director. 578 13 References 580 13.1 [Bradner, 1996] 581 S. Bradner, "The Internet Standards Process - Revision 3." RFC 2026, BCP 582 9. Harvard University. October, 1996. 584 13.2 [Fielding et al., 1997] 585 R. Fielding, J. Gettys, J. Mogul, H. Frystyk, T. Berners-Lee, "Hypertext 586 Transfer Protocol -- HTTP/1.1." RFC 2068. U.C. Irvine, DEC, MIT/LCS. 587 January, 1997. 589 13.3 [Frystyk et al., 1998] 590 H. Frystyk Nielsen, P. Leach, Microsoft Scott Lawrence, Agranat Systems 591 Mandatory Extensions in HTTP ,, March 592 13, 1998 594 14 Authors' Addresses 596 Josh Cohen 597 Microsoft Corporation 598 One Microsoft Way 599 Redmond, WA 98052-6399 601 Email: 603 Sonu Aggarwal 604 Microsoft Corporation 605 One Microsoft Way 606 Redmond, WA 98052-6399 608 Email: sonuag@microsoft.com