A SIP Event Package for Subscribing to Changes to an HTTP Resource
draft-roach-sip-http-subscribe-00

Status of this Memo

By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress.”

The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.

The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.

This Internet-Draft will expire on May 24, 2009.

Abstract

The Session Initiation Protocol (SIP) is increasingly being used in systems that are tightly coupled with Hypertext Transport Protocol (HTTP) servers for a variety of reasons. In many of these cases, applications can benefit from being able to discover, in near-real-time, when a specific HTTP resource is created, changed, or deleted. This document proposes a mechanism, based on the SIP events framework, for doing so.

This document further proposes that the HTTP work necessary to make such a mechanism work be extensible to support protocols other than SIP for monitoring HTTP resources.

Table of Contents

1.  Introduction
2.  Associating a Monitoring URI with an HTTP URL
3.  HTTP Change Event Package
    3.1.  Event Package Name
    3.2.  Event Package Parameters
    3.3.  SUBSCRIBE Bodies
    3.4.  Subscription Duration
    3.5.  NOTIFY Bodies
        3.5.1.  Formal definition of message/httpfrag
        3.5.2.  Use of message/httpfrag in HTTP Monitor Event Package
    3.6.  Notifier processing of SUBSCRIBE requests
    3.7.  Notifier generation of NOTIFY requests
    3.8.  Subscriber processing of NOTIFY requests
    3.9.  Handling of forked requests
    3.10.  Rate of notifications
    3.11.  State Agents
4.  Example Message Flow
5.  IANA Considerations
    5.1.  New Link Relation
    5.2.  New SIP Event Package
    5.3.  New message/httpfrag MIME Type
6.  Acknowledgements
7.  References
    7.1.  Normative References
    7.2.  Informative References
§  Author's Address
§  Intellectual Property and Copyright Statements

1.  Introduction

The Session Initiation Protocol (SIP) [RFC3261] (Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., Peterson, J., Sparks, R., Handley, M., and E. Schooler, “SIP: Session Initiation Protocol,” June 2002.) is increasingly being used in systems that are tightly coupled with Hypertext Transport Protocol (HTTP) [RFC2616] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.) servers for a variety of reasons. In many of these cases, applications can benefit from learning of changes to specified HTTP resources in near-real-time. For example, user agent terminals may elect to store service-related data in an HTTP tree, such as is described in [I‑D.griffin‑bliss‑rest] (Griffin, K. and J. Rosenberg, “Representational State Transfer (REST) for Feature Configuration in Session Initiation Protocol (SIP),” October 2008.) and [I‑D.zourzouvillys‑bliss‑ach‑config‑requirements] (Zourzouvillys, T., “Automatic Call Handling (ACH) Configuration Requirements,” October 2008.). When such configuration information is stored and retrieved using HTTP, clients may need to be informed when information changes, so as to make appropriate changes to their local behavior and user interface.

This document defines a mechanism, based on the SIP Event Framework [RFC3265] (Roach, A., “Session Initiation Protocol (SIP)-Specific Event Notification,” June 2002.), for subscribing to changes in the resource referenced by an HTTP server. It further defines a mechanism by which the proper SIP and/or SIPS URI to be used for such subscriptions can be determined from the HTTP server.

2.  Associating a Monitoring URI with an HTTP URL

One of the key challenges in subscribing to the changes of a resource indicated by an HTTP URL is determining which SIP URI corresponds to a specific HTTP URL. This specification takes the approach of having the HTTP server responsible for the URL in question select an appropriate SIP URI for the corresponding resource, and to return that URI within an HTTP transaction.

In particular, HTTP servers use the HTTP Link: header [I‑D.nottingham‑http‑link‑header] (Nottingham, M., “HTTP Header Linking,” July 2008.) with a relation type of "monitor" to convey the URI that can be used to discover changes to the resource. This document defines behavior for SIP and SIPS URIs in this header. Handling for other URI schemes is out of scope for the current document, although we expect future specifications to define procedures for monitoring via other protocols.

Because a single resource may have the ability to be monitored via multiple protocols, it is perfectly legal for an HTTP response to contain multiple "Link:" headers with a relation type of "monitor". Implementors are cautioned to search the entire HTTP response header block to locate a "Link:" header that corresponds with their preferred change monitoring protocol.

If an HTTP server provides the ability to subscribe to a changes in a resource's value using this event package, it MUST return a Link: header containing a SIP or SIPS URI with a relation type of "monitor" in any successful response to a GET or HEAD request on that resource. It MAY return both.

A client wishing to subscribe to the change state of an HTTP resource obtains a SIP or SIPS URI by sending a GET or HEAD request to the HTTP URL it wishes to monitor. This SIP or SIPS URI is then used in a SUBSCRIBE request, according to the event package defined in section Section 3 (HTTP Change Event Package).

[This indented text to be removed before publication as an RFC]

Several potential mechanisms for retrieving the SIP URI from the HTTP server were evaluated. Of them, the HTTP Link: header was determined to have the most favorable set of properties. Two key candidates that were considered but rejected in favor of Link: are discussed below.

The HTTP PROPFIND method ([RFC4918] (Dusseault, L., “HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV),” June 2007.), section 9.1) can be used to retrieve the value of a specific property associated with an HTTP URL. However, this cannot be done in conjunction with retrieval of the document itself, which is usually desirable. If a PROPFIND approach is employed, clients will typically perform both a GET and a PROPFIND on resources of interest. Additionally, the use of PROPFIND requires support of the PROPFIND method in HTTP User Agents -- which, although fairly well implemented, still lacks the penetration of GET implementations.

Similar to PROPFIND, XRDS [XRI_Resolution_2.0] (Wachob, G., Reed, D., Chasen, L., Tan, W., and S. Churchill, “Extensible Resource Identifier (XRI) Resolution V2.0,” .) can be used to retrieve properties associated with an HTTP URL. It has the advantage of using GET instead of PROPFIND; however, it suffers from both the two-round-trip issue discussed above, as well as an unfortunately large number of options in specifying how to retrieve the properties.

3.  HTTP Change Event Package

3.1.  Event Package Name

The name of this event package is "http-monitor".

3.2.  Event Package Parameters

This event package defines no parameters. [TODO: should we define a simple filter that allows subscribers to request the body be sent in notifications? Something like "body=true"?]

3.3.  SUBSCRIBE Bodies

This event package defines no bodies to be used in the SUBSCRIBE message. Future extensions may define filter criteria to be sent in the SUBSCRIBE bodies.

3.4.  Subscription Duration

Reasonable values for the duration of subscriptions to the http-monitor event package vary widely with the nature of the HTTP resource being monitored. Some HTTP resources change infrequently (if ever), while other can change comparatively rapidly. For rapidly changing documents, the ability to recover more rapidly from a subscription failure is relatively important, so implementations will be well served by selecting smaller durations for their subscriptions, on the order of 1800 to 3600 seconds (30 minutes to an hour).

Subscriptions to slower-changing resources lack this property, and the need to periodically refresh subscriptions render short subscriptions wasteful. For these type of subscriptions, expirations as long as 604800 (one week) or even longer may well make sense.

Given the broad range of reasonable expirations involved, selecting a single default expiration is somewhat tricky. However, in the absence of an expires value in a subscription, the notifier shall assume a default expiration value of 86400 (one day).

3.5.  NOTIFY Bodies

By default, the bodies of NOTIFY messages for the http-monitor event package will be of content-type "message/httpfrag". This content-type is defined below, as is its use in the http-monitor event package.

3.5.1.  Formal definition of message/httpfrag

A valid message/httpfrag part is one that could be obtained by starting with some valid HTTP message and deleting any of the following:

• the entire start line
• one or more entire header fields
• the body

The following Augmented Backus-Naur Form (ABNF) [RFC2234] (Crocker, D., Ed. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” November 1997.) rule describes a message/httpfrag part using the HTTP grammar elements defined in [RFC2616] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.). The expansion of any element is subject to the restrictions on valid HTTP message syntax defined in [RFC2616] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.).

     httpfrag = [ start-line ]
                *(message-header CRLF)
                [ CRLF [ message-body ] ]

If the message/httpfrag part contains a body, it MUST also contain the appropriate header fields describing that body (such as Content-Length) and the blank line separating the headers from the body.

3.5.2.  Use of message/httpfrag in HTTP Monitor Event Package

The message/httpfrag NOTIFY bodies used in the HTTP monitor event package represent a subset of the HTTP response that would be returned if the client used an HTTP GET to retrieve the HTTP resource. Except for the normative constraints described in the remainder of this section, the notifier MAY include any arbitrary subset of the HTTP response, including the entire set of headers.

An example of a message/httpfrag body as used in this event package is shown below.

  ETag: 38fe6-58b-1840e7d0
  Last-Modified: Sat, 13 Nov 2010 23:29:00 GMT
  Content-MD5: 4e3b50421829c7c379a5c6154e560449

When used in the HTTP monitor event package defined in this document, the message/httpfrag MUST contain at least one of an ETag or Content-MD5 header, unless returning a null state as described in Section 3.7 (Notifier generation of NOTIFY requests). It MAY contain both. Inclusion of a Last-Modified header is also RECOMMENDED.

When used in the HTTP monitor event package, the message/httpfrag MUST NOT contain a message-body component, unless the corresponding subscription has explicitly indicated the desire to receive such bodies in the form of a filter. Filters for this event package are out of scope for this specification.

If the change to the resource being communicated represents a modification of the resource's value, the message/httpfrag MAY contain a start line. If present, this start line will contain a the same 2xx-class HTTP response that would be returned if a user agent attempted to access the HTTP resource with a GET request (e.g., "200 OK").

If the change to the resource being communicated represents a renaming of the HTTP resource, the message/httpfrag MUST contain a start line; this start line will contain a the same 3xx-class HTTP response that would be returned if a user agent attempted to access the relocated HTTP resource with a GET request (e.g., "301 Moved Permanently"). The message/httpfrag also SHOULD contain a Location: header that communicates the new name of the resource.

If the change to the resource being communicated represents a deletion of the HTTP resource, the message/httpfrag MUST contain a start line; this start line will contain a the same 4xx-class HTTP response that would be returned if a user agent attempted to access the missing HTTP resource with a GET request (e.g., "404 Not Found" or "410 Gone").

3.6.  Notifier processing of SUBSCRIBE requests

Upon receipt of a SUBSCRIBE request, the notifier applies authorization according to local policy. Typically, this policy will be aligned with the HTTP server authorization policies regarding access to the resource whose change state is being requested.

3.7.  Notifier generation of NOTIFY requests

NOTIFY messages should be generated whenever the underlying resource indicated by the corresponding HTTP URL has been modified.

In the case that the NOTIFIER has insufficient information to return any useful information about the underlying HTTP resource, it may return a message/httpfrag that is zero bytes long (which is a proper empty subset of the syntax described in section Section 3.5.1 (Formal definition of message/httpfrag)).

3.8.  Subscriber processing of NOTIFY requests

Upon receipt of a NOTIFY message, subscriber should use any information in the message/httpfrag to update its view of the underlying HTTP resource. In most cases, this results in an invalidation of its view of the HTTP resource. It is up to the subscriber implementation to decide whether it is appropriate to fetch a new copy of the HTTP resource as a reaction to a NOTIFY message.

3.9.  Handling of forked requests

Multiple notifiers for a single HTTP resource is semantically nonsensical. In the aberrant circumstance that a SUBSCRIBE request is forked, the SUBSCRIBER SHOULD terminate all but one subscription, as described in section 4.4.9 of RFC 3265 [RFC3265] (Roach, A., “Session Initiation Protocol (SIP)-Specific Event Notification,” June 2002.).

3.10.  Rate of notifications

Because the data stored in HTTP for the purpose of SIP services may change rapidly due to user input, and because it may potentially be rendered to users and/or used to impact call routing, a high degree of responsiveness is appropriate. However, for the protection of the network, notifiers for the http-monitor event package SHOULD NOT send notifications more frequently than once every second.

3.11.  State Agents

Decomposition of the authority for the HTTP resource into an HTTP Server and a SIP Events Server is likely to be useful, due to the potentially different scaling properties associated with serving HTTP resources and managing subscriptions. In the case of such decomposition, implementors are encouraged to familiarize themselves with the PUBLISH mechanism described in RFC 3903 [RFC3903] (Niemi, A., “Session Initiation Protocol (SIP) Extension for Event State Publication,” October 2004.).

4.  Example Message Flow

     Subscriber          HTTP Server      SIP Events Server
          |                   |                   |
          |                   |                   |
          |(1) HTTP GET       |                   |
          |------------------>|                   |
          |(2) HTTP 200 OK    |                   |
          |<------------------|                   |
          |(3) SIP SUBSCRIBE  |                   |
          |-------------------------------------->|
          |(4) SIP 200 OK     |                   |
          |<--------------------------------------|
          |(5) SIP NOTIFY     |                   |
          |<--------------------------------------|
          |(6) SIP 200 OK     |                   |
          |-------------------------------------->|
          |                   |(7) SIP PUBLISH    |
          |                   |------------------>|
          |                   |(8) SIP 200 OK     |
          |                   |<------------------|
          |(9) SIP NOTIFY     |                   |
          |<--------------------------------------|
          |(10) SIP 200       |                   |
          |-------------------------------------->|
          |                   |                   |
          |                   |                   |

[TBD: include full example messages]

5.  IANA Considerations

[TBD: these sections need some prose to describe which registry we're putting the values in to]

5.1.  New Link Relation

• Relation Name: monitor
• Description: Refers to a resource that can be used to monitor changes.
• Reference: RFC XXXX [[Note to RFC Editor: replace with the RFC number for this specification]]

5.2.  New SIP Event Package

Package Name:

http-monitor

Type:

package

Contact:

Adam Roach, adam.roach@tekelec.com

Reference:

RFC XXXX [[Note to RFC Editor: replace with the RFC number for this specification]]

5.3.  New message/httpfrag MIME Type

This document proposes a new message/httpfrag Message Media Type, to be registered at http://www.iana.org/assignments/media-types/message/. This body type is described in section Section 3.5 (NOTIFY Bodies)

Media Type name:         message
Media subtype name:      httpfrag
Required parameters:     none
Optional parameters:     version, msgtype

version:

The HTTP-Version number of the enclosed message (e.g., "1.1"). If not present, the version can be determined from the first line of the body.

msgtype:

The message type -- "request" or "response".

Encoding considerations: only "7bit", "8bit", or "binary" are
                         permitted
Security considerations: none

6.  Acknowledgements

Thanks to Lisa Dusseault and Mark Nottingham for significant input on the mechanisms to bind an HTTP URL to a SIP URI. Thanks to Robert Sparks for the message/sipfrag specification, from which the message/httpfrag definition was lifted wholesale.

7.  References

7.1. Normative References

7.2. Informative References

Author's Address

Full Copyright Statement

Copyright © The IETF Trust (2008).

This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.

This document and the information contained herein are provided on an “AS IS” basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property

The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.

Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.

The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org.