State token draft

Enclosed in this message, please find an advance copy of an Internet
Draft submitted under the name, "draft-goland-state-token-00.txt",
titled, "State Tokens and Preconditions for HTTP".

The ideas in this draft grew out of the need to have a header to
express method preconditions which involve lock tokens (e.g., an
If-Lock-Token header), since entity tags are not sufficient for
use as lock tokens, and hence the existing If-Match and If-None-Match
headers could not be used.  Since it was the lack of extensibility
of the If-Match and If-None-Match headers which made them
unusable for expressing lock preconditions, instead of developing a
single-use If-Lock-Token header, a more general state token and
precondition scheme was developed, and is presented below.

Since the Design Team only ever discussed functionality similar to
If-Lock-Token, this proposal does not represent the consensus of the
Design Team.  However, I feel it is worthy of consideration, even if
we subsequently discover it is too general.

As always, your comments on this draft are appreciated.  The sole
source for determination of consensus on this draft is the discussion
list.

- Jim


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

                   State Tokens and Preconditions for HTTP

Status of this Memo

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/.

Abstract

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.

1 Overview

1.1 Problem Description

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.

1.2 Solution Requirements

1.2.1 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."

1.2.2 Conditonals

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.

2 State Token Syntax

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.

3 State Token Conditional Headers

3.1 If-State-Match

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.

3.2 If-None-State-Match

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.

4 E-Tags

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.

5 References

[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.

6 Authors' Addresses

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

Received on Wednesday, 21 May 1997 21:45:42 UTC