A SIP Event Package for Subscribing to Changes to an HTTP Resource

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 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 and . 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 , for subscribing to changes in the resource referenced by an HTTP server. Such subscriptions do not carry the content associated with the resource -- the HTTP protocol is still used to transfer the contents of HTTP resources. This document 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.

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 link relations -- such as the HTTP Link: header , the the HTML <link/> element , and the Atom <atom:link/> element -- to convey the URI or URIs that can be used to discover changes to the resource. This document defines behavior for SIP and SIPS URIs in such link relations. 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. Clients making use of the mechanism described in this document MUST support the HTTP Link: header. Those clients that support processing of HTML bodies SHOULD support the HTML <link/> element; those that support processing of Atom documents SHOULD support Atom <atom:link/> elements. These requirements are not intended to preclude the use of any other types of link relations. 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 relationships with relations that allow for monitoring of changes. Implementors are cautioned to process all link relations to locate a one that corresponds with their preferred change monitoring protocol.

If an HTTP server wishes to offer the ability to subscribe to a changes in a resource's value using this event package, it returns a link relation containing a SIP or SIPS URI with a relation type of "monitor" in a successful response to a GET or HEAD request on that resource. If the server supports both SIP and SIPS access, it may return link relations for both kinds of access. 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 .

If a client wishes to subscribe to the state of multiple HTTP resources, it is free to make use of the mechanisms defined in RFC 4662 and/or RFC 5367 . This requires no special support by the server that provides resource state information. These approaches, however, require the addition of a Resource List Server (RLS) as defined in RFC 4662, which will typically subscribe to the state of resources on behalf of the monitoring user. In many cases, this is not a particularly efficient means of monitoring several resources, particularly when such resources reside on the same HTTP server. As a more efficient alternative, if an HTTP server wishes to offer the ablity to subscribe to the state of several HTTP resources in a single SUBSCRIBE request, it returns a link relation containing a SIP or SIPS URI with a relation type of "monitor-group" in a successful response to a GET or HEAD request on any monitorable resource. In general, this monitor-group URI will be the same for all resources on the same HTTP server. The monitor-group URI corresponds to an RLS service associated with the HTTP server. This RLS service MUST support subscriptions to request-contained resource lists, as defined in RFC 5367 . This RLS service is not, however, required to accept URI lists that include monitoring URIs that are not associated with resources served by its related HTTP server. This allows RLS functionality to be implemented without requiring back-end subscriptions. If a server wishes to reject such requests, the "403 Forbidden" response code is appropriate. The HTTP server MUST also return a SIP and/or SIPS link relation with a relation type of "monitor" whenever it returns a SIP and/or SIPS link relation with a relation type of "monitor-group." The monitor-group URI corresponds only to an RLS, and never an HTTP resource or fixed set of HTTP resources. If a client wishes to subscribe to the state of multiple HTTP resources, and has received monitor-group URIs for each of them, it may use the monitor-group URIs to subscribe to multiple resources in the same subscription. To do so, it starts with the set of HTTP resources it wishes to monitor. It then groups these resources by their respective monitor-group URIs. Finally, for each such group, it initiates a subscription to the group's monitor-list URI; this subscription includes a URI list, as described in RFC 5367. The URI list contains all of the URIs in the group. For example: consider the case in which a client wishes to monitor the resources http://www.example.com/goat, http://www.example.com/sheep, http://www.example.org/llama, and http://www.example.org/alpaca. It would use HTTP to perform HEAD and/or GET operations on these resources. The responses to these operations will contain link relations for both monitor and monitor-type for each of the four resources. Assume the monitor link for http://www.example.com/goat is sip:a94aa000@example.com; for http://www.example.com/sheep, sip:23ec24c5@example.com; for http://www.example.org/llama, sip:yxbO-UHYxyizU2H3dnEerQ@example.org; and for http://www.example.org/alpaca, sip:-J0piC0ihB9hfNaJc7GCBg@example.org. Further, assume the monitor-group link for http://www.example.com/goat and http://www.example.com/sheep are both sip:httpmon@rls.example.com, while the monitor-group link for http://www.example.org/llama and http://www.example.org/alpaca are both sip:rls@example.org. Because they share a common monitor-group link, the client would group together http://www.example.com/goat and http://www.example.com/sheep in a single subscription. It sends this subscription to the monitor-group URI (sip:httpmon@rls.example.com), with a resource-list containing the relevant monitor URIs (sip:a94aa000@example.com and sip:23ec24c5@example.com). It then repeats this process for the remaining two HTTP resources, using their monitor-group and monitor URIs in the same way.

[This section will be removed before publication as an RFC] Several potential mechanisms for retrieving the SIP URI from the HTTP server were evaluated. Of them, link relations were determined to have the most favorable set of properties. Two key candidates that were considered but rejected in favor of link relations are discussed below. The HTTP PROPFIND method (, 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 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.

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

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"?]

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.

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. The subscriber is responsible for selecting an expiration time that is appropriate for its purposes, taking the foregoing considerations into account. Keep in mind that the goal behind selecting subscription durations is to balance server load against time to recover in the case of a failure. In the absence of an expires value in a subscription, the notifier can assume a default expiration period according to local policy. This local policy may choose to take various aspects of the monitored resource into account, such as its age and presumed period of validity. Absent any other information, it would not be unreasonable for a server to assume a default expiration value of 86400 (one day) when the client fails to provide one.

By default, the bodies of NOTIFY messages for the http-monitor event package will be of content-type "message/http," as defined in RFC 2616 .

The message/http NOTIFY bodies used in the HTTP monitor event package reflect the response that would be returned if the client performed an HTTP HEAD operation on the HTTP resource. An example of a message/http body as used in this event package is shown below.

HTTP/1.1 200 OK Date: Sat, 13 Nov 2010 17:18:52 GMT ETag: 38fe6-58b-1840e7d0 Content-MD5: 4e3b50421829c7c379a5c6154e560449 Last-Modified: Sat, 13 Nov 2010 03:29:00 GMT Accept-Ranges: bytes Content-Location: http://www.example.com/pet-profiles/alpacas/ Content-Length: 12511 Content-Type: text/html When used in the HTTP monitor event package defined in this document, the message/http SHOULD contain at least one of an ETag or Content-MD5 header, unless returning a null state as described in . Inclusion of a Last-Modified header is also RECOMMENDED. Additionally, the message/http body MUST contain a Content-Location field that identifies the resource being monitored. Note that this is not necessarily the same URL from which the link association was originally obtained; see RFC 2616 for details. When used in the HTTP monitor event package, the message/http 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 renaming of the HTTP resource, the message/http start line will contain the same 3xx-class HTTP response that would be returned if a user agent attempted to access the relocated HTTP resource with a HEAD request (e.g., "301 Moved Permanently"). The message/http 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 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 HEAD request (e.g., "404 Not Found" or "410 Gone").

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.

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 body that is zero bytes long.

Upon receipt of a NOTIFY message, subscriber should use any information in the message/http 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.

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 .

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.

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 .

| | |(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]

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

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

Relation Name: monitor-group Description: Refers to a resource that can be used to monitor changes in a specified group of HTTP resources. Reference: RFC XXXX [[Note to RFC Editor: replace with the RFC number for this specification]]

http-monitor package Adam Roach, adam.roach@tekelec.com RFC XXXX [[Note to RFC Editor: replace with the RFC number for this specification]]

Thanks to Lisa Dusseault and Mark Nottingham for significant input on the mechanisms to bind an HTTP URL to a SIP URI. Thanks also to Mark Nottingham and Theo Zourzouvillys for thorough feedback on early versions of this document.