TOC 
Network Working GroupP. Buchheit
Internet-DraftFriendFeed
Intended status: ExperimentalD. Clinton, Ed.
Expires: July 5, 2009Google
 January 2009


Simple Update Protocol
draft-clinton-sup-current

Status of this Memo

This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and 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 July 5, 2009.

Copyright Notice

Copyright (c) 2009 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document.

Abstract

This specification defines the Simple Update Protocol, a mechanism by which content publishers can signal to consumers that certain resources have been updated.

Editorial Note

To provide feedback on this Internet-Draft, join the Simple Update Protocol room on FriendFeed. [Ed: We may need/want to create a mailing list for this going forward.]



Table of Contents

1.  Introduction
    1.1.  Notational Conventions
    1.2.  Design Considerations
2.  Overview
3.  Updates Document
    3.1.  The 'updates' field
    3.2.  The 'period' field
    3.3.  The 'since_time' field
    3.4.  The 'updated_time' field
    3.5.  The 'available_periods' field
4.  Resource Token
5.  Update Token
6.  Discovery
    6.1.  Updates Link Header
    6.2.  Updates Link Element
7.  Examples
8.  Security Considerations
9.  IANA Considerations
10.  References
    10.1.  Normative References
    10.2.  Informative References
Appendix A.  Acknowledgements
§  Authors' Addresses




 TOC 

1.  Introduction

SUP (Simple Update Protocol) consists of a notification format called an Updates Document (Updates Document) that content publishers can use to alert consumers that one or more resources have been recently changed. Clients can subsequently poll a single Updates Document rather than each underlying resource individually and thus decrease both the latency in discovering recent changes and the total amount of bandwidth and time consumed.



 TOC 

1.1.  Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.).



 TOC 

1.2.  Design Considerations

Updates Documents are designed to be easy for publishers to create, and increase in benefit as the number of underlying resources and the number of consumers grow. Similarly, consumers that poll for a large number of resources from a given publisher, such as blog aggregators, feed readers, or intermediary publishers, will benefit from polling a publisher's Updates Document before retrieving each underlying resource individually.



 TOC 

2.  Overview

Publishers of URI-addressable resources may associated a semi-unique opaque identifier, called a Resource Token (Resource Token), with each underlying resource. The publisher signals the existence of these Resource Tokens via a discovery mechanism during the retrieval of the resource, either within the resource itself (the Updates Link Element (Updates Link Element)) or as meta-data associated with the response (the Updates Link Header (Updates Link Header)). The publisher may then create a URI-addressable Updates Document (Updates Document) that informs consumers which resources, as identified by Resource Tokens, have been recently modified.



 TOC 

3.  Updates Document

An Updates Document consists of a URI-addressable resource of type 'application/json' containing a single top-level JSON Object (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.) [RFC4627], mapping a set of well-known keys to well-defined values, as defined below.

Consumers SHOULD ignore any unanticipated keys in the JSON dictionary and SHOULD continue to parse all anticipated keys as specified.

The overall structure of the Updates Document is as follows:

{
    "updates": [ ... ],
    "period": ...,
    "since_time": ...,
    "updated_time": ...,
    "available_periods": { ... },
}


 TOC 

3.1.  The 'updates' field

A JSON List (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.) [RFC4627] of two-element JSON Lists, each containing the tuple (Resource Token (Resource Token), Update Token (Update Token)).

This field is REQUIRED. It MAY contain an empty list if no resources have been updated in the given interval.

"updates": [
    ["14ea1a46", "16NV"],
    ["a2f57d4b", "16Nx"],
    ["584c7e6c", "16NV"]
]


 TOC 

3.2.  The 'period' field

A positive integer representing the the duration of time under consideration in this Updates Document, in seconds.

This field is REQUIRED.

"period": 60


 TOC 

3.3.  The 'since_time' field

An [RFC3339] (Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” July 2002.) formatted string representing the start time of the interval covered by this Updates Document.

This field is REQUIRED.

"since_time": "2009-01-06T00:48:38Z"


 TOC 

3.4.  The 'updated_time' field

An [RFC3339] (Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” July 2002.) formatted string representing the end time of the interval covered by this Updates Document.

This field is REQUIRED.

"updated_time": "2009-01-06T00:50:48Z"

The delta in seconds between the 'start_time' and the 'updated_time' fields MUST be equal to or greater than the duration indicated by the 'period' field.



 TOC 

3.5.  The 'available_periods' field

A JSON Object mapping time periods (in seconds) to URLs where an additional Updates Documents of the corresponding duration may be found.

This field is OPTIONAL.

"available_periods": {
    "60": "http://example.com/sup.json?seconds=60",
    "300": "http://example.com/sup.json?seconds=300",
    "600": "http://example.com/sup.json?seconds=600"
}


 TOC 

4.  Resource Token

A Resource Token is a short opaque string used to identify a individual URI-addressable resource. Each unique underlying resource MUST always map to a single, stable Resource Token, but different resources MAY occasionally share the same Resource Token.

Consumers SHOULD NOT attempt to parse or interpret the contents of the Resource Token. Clients SHOULD maintain a mapping of Resource Tokens to resource URIs is established via the Discovery (Discovery) mechanisms defined below.

A valid Resource Token is a non-empty string of no more than 128 characters composed of ASCII letters, numbers, or hyphens (regex [a-zA-Z0-9\-]), and are produced via the following rules, as defined by the augmented BNF (Crocker, D. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” January 2008.) [RFC5234] syntax.

resource_token = 1*128(CHAR / DIGIT / "-")


 TOC 

5.  Update Token

The Update Token is a short opaque string used to disambiguate distinct updates to a URI-addressable resource. In practice, the last update timestamp of the resource or its ETag is a suitable identifier, but clients SHOULD NOT attempt to parse or interpret the contents of the string.

A valid Update Token is a non-empty string of no more than 128 characters composed of ASCII letters, numbers, or hyphens (regex [a-zA-Z0-9\-]), and are produced via the following rules, as defined by the augmented BNF (Crocker, D. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” January 2008.) [RFC5234] syntax.

update_token = 1*128(CHAR / DIGIT / "-")


 TOC 

6.  Discovery

This section discusses how a publisher signals the existence of an Updates Document and how the publisher establishes the relationship between the semi-unique Resource Token and an underlying URI-addressable resource.

Publishers SHOULD announce the availability of an Updates Document and associate the underlying resource with a corresponding Resource Token via the Updates Link Header (Updates Link Header). If the underlying resource is an XML-based document, the publisher may additionally include a Updates Link Element (Updates Link Element) within the document itself.

Use of the Updates Link Header is RECOMMENDED as it is applicable to all resources published over HTTP, but consumers SHOULD be prepared for the presence of the Updates Link Element in addition to, or instead of, the Updates Link Header, when the underlying resource is a XML-based document.



 TOC 

6.1.  Updates Link Header

Responses to HTTP (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.) [RFC2616] requests for resources SHOULD include a HTTP Response Header (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.) [RFC2616] of 'Link' to signal both the URI at which the Updates Document (Updates Document) may be polled and the semi-unique Resource Token (Resource Token) of the resource being retrieved.

The 'rel' value of the Link header is defined as follows: [Pending IANA consideration]

updates

The 'type' value of the Link header is defined as follows:

application/json

The 'href' value of the Link header is produced via the via the following rules, as defined by the augmented BNF (Crocker, D. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” January 2008.) [RFC5234] syntax, the URI production grammar defined in [RFC3986] (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.), and the above grammar defining the 'resource_token' (Resource Token) production.

updates_document_uri =
    scheme ":" hier-part [ "?" query ] [ "#" resource_token ]

The complete value of the 'Link' header conform with the conventions formalized in [I‑D.nottingham‑http‑link‑header] (Nottingham, M., “Link Relations and HTTP Header Linking,” November 2008.) according to the following production rules, as defined by the augmented BNF (Crocker, D. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” January 2008.) [RFC5234] syntax, the URI production grammar defined in [RFC3986] (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.) and the 'updates_document_uri' production as defined above.

link_rel_value = "updates"
link_type = "application/json"
link_title = "Updates Document"
link_header = "Link:" 1*SP updates_document_uri *SP ";" 1*LWSP
    "rel=" DQUOTE link_rel_value DQUOTE ";" 1*LWSP
    "type=" DQUOTE link_type DQUOTE ";" 1*LWSP
    "title=" DQUOTE link_title DQUOTE

For example, the following 'Link' header refers to a Updates Document at 'http://example.com/sup.json' and indicates that the Resource Token of the resource being returned is '4496672d'.

Link: <http://example.com/sup.json#4496672d>;
    rel="updates";
    type="application/json";
    title="Updates Document"


 TOC 

6.2.  Updates Link Element

In addition to, or instead of, the Updates Link Header (Updates Link Header), XML-based resources MAY include an Atom Syndication Format (Nottingham, M. and R. Sayre, “The Atom Syndication Format,” December 2005.) [RFC4287] 'atom:link' element to signal both the URI at which the Updates Document (Updates Document) may be retrieved and the Resource Token (Resource Token) associated with the containing document.

The 'rel' value of the atom:link element is defined as follows: [Pending IANA consideration]

updates

The 'type' value of the atom:link element is defined as follows:

application/json

The 'href' value of the atom:link element is produced via the via the following rules, as defined by the augmented BNF (Crocker, D. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” January 2008.) [RFC5234] syntax, the URI production grammar defined in [RFC3986] (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.), and the above grammar defining the 'resource_token' (Resource Token) production.

updates_document_uri =
    scheme ":" hier-part [ "?" query ] [ "#" resource_token ]

For example, the following 'atom:link' element refers to a Updates Document at 'http://example.com/sup.json' and indicates that the Resource Token of the containing document is '4496672d'.

<link xmlns="http://www.w3.org/2005/Atom"
      rel="updates"
      type="application/json"
      title="Updates Document"
      href="http://example.com/sup.json#4496672d"/>


 TOC 

7.  Examples

The following is a sample Updates Document that indicates that five distinct URI-addressable resources were updated in the interval between 1:14:35 and 1:16:45.

{
  "available_periods": {
    "60": "http://example.com/sup.json?seconds=60",
    "300": "http://example.com/sup.json?seconds=300",
    "600": "http://example.com/sup.json?seconds=600"
  },
  "period": 60,
  "since_time": "2009-01-06T01:14:35Z",
  "updated_time": "2009-01-06T01:16:45Z",
  "updates": [
    [
      "4496672d",
      "16fg"
    ],
    [
      "e8d50639",
      "16fg"
    ],
    [
      "e7cd6949",
      "16eA"
    ],
    [
      "1d8274dd",
      "16eA"
    ],
    [
      "19ab3751",
      "16eA"
    ],
  ]
}


 TOC 

8.  Security Considerations

SUP does not require that a site MUST encrypt its resource tokens. The resource tokens may be rendered opaque through strong encryption, hashing, or they may be non-opaque. In a scenario where a SUP document is being used to indicate that private or password protected resources have been updated and the resource tokens are insufficiently opaque (e.g. the urls of the resources are used as resource tokens or the resource tokens are rendered opaque with an algorithm that can be reversed in order to identify the underlying resource) then an attacker can build up a detailed profile of when these documents were updated. This profile can then be correlated with other data sources in order to compromise the security of the private or password protected resources. This is one way adoption of SUP can potentially weaken a site's security.



 TOC 

9.  IANA Considerations

[Ed: Draft language to propose "updates" as a IANA recognized link relation value.]



 TOC 

10.  References



 TOC 

10.1. Normative References

[RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML).
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” RFC 2616, June 1999 (TXT, PS, PDF, HTML, XML).
[RFC3339] Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” RFC 3339, July 2002 (TXT, HTML, XML).
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” STD 66, RFC 3986, January 2005 (TXT, HTML, XML).
[RFC4287] Nottingham, M. and R. Sayre, “The Atom Syndication Format,” RFC 4287, December 2005 (TXT).
[RFC4627] Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” RFC 4627, July 2006 (TXT).
[RFC5234] Crocker, D. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” STD 68, RFC 5234, January 2008 (TXT).


 TOC 

10.2. Informative References

[I-D.nottingham-http-link-header] Nottingham, M., “Link Relations and HTTP Header Linking,” draft-nottingham-http-link-header-03 (work in progress), November 2008 (TXT).


 TOC 

Appendix A.  Acknowledgements

The author acknowledges the contributions of [Ed: P. Buchheit should edit this section].

The editor would like to thank Adewale Oshineye for publishing an earlier interpretation of the SUP specification that helped form the basis for this document.



 TOC 

Authors' Addresses

  Paul Buchheit
  FriendFeed
Email:  [Ed: Paul -- do you want your email published?]
URI:  http://paulbuchheit.blogspot.com/
  
  DeWitt Clinton (editor)
  Google
Email:  dewitt@unto.net
URI:  http://unto.net/