WEBDAV Working Group Y.Y. Goland
INTERNET-DRAFT Microsoft Corporation
<draft-goland-state-token-00.txt> E.J. Whitehead, Jr.
U.C. Irvine
May 21, 1997
Expires November 21, 1997
This document is an Internet draft. 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 information
as Internet drafts.
Internet Drafts are draft documents valid for a maximum of six months
and can 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 as other than as "work in progress".
To learn the current status of any Internet draft please check the "lid-abstracts.txt"
listing contained in the Internet drafts shadow directories on ftp.is.co.za
(Africa), nic.nordu.net (Europe), munnari.oz.au (Pacific Rim), ds.internic.net
(US East coast) or ftp.isi.edu (US West coast). Further information about
the IETF can be found at URL: http://www.ietf.org/
Distribution of this document is unlimited. Please send comments to the WWW Distributed Authoring and Versioning (WebDAV) mailing list, <w3c-dist-auth@w3.org>, which may be joined by sending a message with subject "subscribe" to <w3c-dist-auth-request@w3.org>. Discussions are archived at URL: http://www.w3.org/pub/WWW/Archives/Public/w3c-dist-auth/.
There are times when a principal will want to predicate successful execution of a method on the current state of a resource. While HTTP/1.1 provides a mechanism for conditional execution of methods using entity tags via the "If-Match" and "If-None-Match" headers, the mechanism is not sufficiently extensible to express conditional statements involving more generic state indicators, such as lock tokens.
This draft defines the term "state token" as an identifier for a state of a resource. This draft defines requirements for state tokens and provides a state token syntax, along with two new headers which are used to express method preconditions using state tokens.
There are times when a principal will want to predicate successful execution of a method on the current state of a resource. While HTTP/1.1 [HTTP11] provides a mechanism for conditional execution of methods using entity tags via the "If-Match" and "If-None-Match" headers, the mechanism is not sufficiently extensible to express conditional statements involving more generic state indicators, such as lock tokens.
The fundamental issue with entity tags is that they can only be generated by a resource. However there are times when a client will want to be able to share state tokens between resources, potentially on different servers, as well as be able to generate certain types of lock tokens without first having to communicate with a server.
For example, a principal may wish to require that resource B have a certain state in order for a method to successfully execute on resource A. If the client submits an e-tag from resource B to resource A then A has no way of knowing that the e-tag is meant to describe resource B.
Another example occurs when a principal wishes to
predicate the successful completion of a method on the absence
of any locks on a resource. It is not sufficient to submit an
"If-None-Match: *" as this refers to the existence of
an entity, not of a lock.
This draft defines the term "state token" as an identifier for a state of a resource. The sections below define requirements for state tokens and provide a state token syntax, along with two new headers which can accept the new state token syntax.
Self-Describing. A state token must be self describing such that upon inspecting a state token it is possible to determine what sort of state token it is, what resource(s) it applies to, and what state it represents.
This self-describing nature allows servers to accept tokens from other servers and potentially be able to coordinate state information cross resource and cross site through standardized protocols. For example, the execution of a request on resource A can be predicated on the state of resource B, where A and B are potentially on different servers.
Client Generable. The state token syntax must allow, when appropriate, for clients to generate a state token without having first communicated with a server.
One drawback of entity tags is that they are set by the server and there is no interoperable algorithm for calculating an entity tag. Consequently, a client cannot generate an entity tag from a particular state of a resource. However, a state token which encodes an MD5 state hash could be calculated by a client based on a client-held state of a resource, and then submitted to a server in a conditional method invocation.
Another potential use for client generable state tokens is for a client to generate lock tokens with wild card fields, and hence be able to express conditionals such as: "only execute this GET if there are no write locks on this resource."
Universal. A solution must be applicable to all requests.
Positive and Negative. Conditional expressions must allow for the expression of both positive and negative state requirements.
State tokens are URLs [URL] employing the following syntax:
State-Token = "StateToken:" Type ":" Resources ":" State-Info Type = "Type" "=" Caret-encoded-URL Resources = "Res" "=" Caret-encoded-URL Caret-encoded-URL = "^" Resource "^" Resource = <A URI where all "^" characters are escaped> State-Info = *(uchar | reserved) ; uchar, reserved defined section 3.2.1 of RFC 2068
This proposal has created a new URL scheme for state tokens because a state token names a network resource using its normal name, which is typically state-invariant, along with additional information that specifies a particular state of the resource. Encoding the state information into the native URL scheme of the network resource was not felt to be safe, since freedom from name space collisions could not be guaranteed. If this proposal is accepted, the StateToken URL scheme will need to be defined and registered with IANA.
State Token URLs begin with the URL scheme name "StateToken" rather than the name of the particular state token type they represent in order to make the URL self describing. Thus it is possible to examine the URL and know, at a minimum, that it is a state token.
Labeled name/value pairs are used within the token to allow new fields to be added. Processors of state tokens MUST be prepared to accept the fields in whatever order they are present and MUST ignore any fields they do not understand.
The "Type" field specifies the type of the state information encoded in the state token. A URL is used in order to avoid namespace collisions.
The "Res" field identifies the resource for which the state token specifies a particular state. Since commas and spaces are acceptable URL characters, a caret is used to delimit a URL. Since a caret is an acceptable URL character, any instances of it must be escaped using the % escape convention.
The State-Info production is expanded upon in descriptions of specific state token types, and is intended to contain the state description information for a particular state token.
If-State-Match = "If-State-Match" ":" ("AND" | "OR") 1#("<" State-Token ">")
The If-State-Match header is intended to have similar functionality to the If-Match header defined in section 14.25 of RFC 2068.
If the AND keyword is used and all of the state tokens identify the state of the resource, then the server MAY perform the requested method. If the OR keyword is used and any of the state tokens identifies the current state of the resource, then server MAY perform the requested method. If neither of the keyword requirements is met, the server MUST NOT perform the requested method, and MUST return a 412 (Precondition Failed) response.
If-None-State-Match = "If-None-State-Match" 1#("<" State-Token ">")
The If-None-State-Match header is intended to have similar functionality to the If-None-Match header defined in section 14.26 of RFC 2068.
If any of the state tokens identifies the current state of the resource, the server MUST NOT perform the requested method. Instead, if the request method was GET, HEAD, INDEX, or GETMETA, the server SHOULD respond with a 304 (Not Modified) response, including the cache-related entity-header fields (particularly ETag) of the current state of the resource. For all other request methods, the server MUST respond with a status of 412 (Precondition Failed).
If none of the state tokens identifies the current state of the resource, the server MAY perform the requested method.
Note that the "AND" and "OR" keywords specified with the If-State-Match header are intentionally not defined for If-None-State-Match, because this functionality is not required.
E-tags have already been deployed using the If-Match and If-None-Match headers. Introducing two mechanisms to express e-tags would only confuse matters, therefore e-tags should continue to be expressed using quoted strings and the If-Match and If-None-Match headers.
[URL] T. Berners-Lee, L. Masinter, M. McCahill. "Uniform Resource Locators (URL)", RFC 1738, CERN, Xerox PARC, University of Minnesota, December 1994.
[HTTP11] R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2068, U.C. Irvine, DEC, MIT/LCS, January 1997.
Yaron Y. Goland Microsoft Corporation One Microsoft Way Bldg. 27N/3445 Redmond, WA 98052-6399 Fax: (206) 936 7329 EMail: yarong@microsoft.com E. James Whitehead, Jr. Department of Information and Computer Science University of California Irvine, CA 92697-3425 Fax: (714) 824-4056 EMail: ejw@ics.uci.edu