Author: ts
Date: Fri Feb 22 21:17:10 2008
New Revision: 7442
Log:
- Added RFC summary for entity tags.
Modified:
trunk/Webdav/design/design-1.1.txt
Modified: trunk/Webdav/design/design-1.1.txt
==============================================================================
--- trunk/Webdav/design/design-1.1.txt [iso-8859-1] (original)
+++ trunk/Webdav/design/design-1.1.txt [iso-8859-1] Fri Feb 22 21:17:10 2008
@@ -40,6 +40,147 @@
This section describes the support of Etags in the Webdav component, including
the usage of the if-header with Etags and the generation and sending of the
Etag header.
+
+============
+RFC Overview
+============
+
+Etags (Entity Tags) are generally used in the HTTP/1.1 protocol to provide a
+mechanism of validating that a resource is in the same state. Whenever the
+state of a resource changes, its Etag needs to change. In following, the
+definition of the HTTP/1.1 validation mechanisms in general, the defintion of
+an Etag and the definition of the ETag-header are described. In addition the
+usage of Etags in the Webdav RFC is described.
+
+Entity Tags
+===========
+
+Section 3.11 of the HTTP/1.1 RFC describes entity tags. These strings identify
+(tag) the state of a recource, named "entities" in the RFC. The entity tag
+consists of a quoted string and an optional weakness modifier. The quoted
+string must be unique for each state. ::
+
+ entity-tag = [ weak ] opaque-tag
+ weak = "W/"
+ opaque-tag = quoted-string
+
+A non-weak entity tag must identify a certain state uniquely. With the added W/
+prefix, one and the same tag may identify different states of a resource that
+are semantically equivalent.
+
+Entity tags are used in HTTP/1.1 in combination with the following headers:
+
+- Request
+ - If-Match
+ - If-None-Match
+ - If-Range
+-Response
+ - ETag
+
+Since the Webdav component will generate the entity tag, we should ensure to
+only generate strong entity tags.
+
+Headers
+=======
+
+The following section describes the headers that are affected by entity tags
+and how the server should repect them.
+
+If-Match
+--------
+
+The If-Match header is generally used to make the method it is send with
+conditional. Only if the conditions defined by the header are met, the action
+associated with the method should be performed by the server.
+
+The header format is defined as follows (14.24): ::
+
+ If-Match = "If-Match" ":" ( "*" | 1#entity-tag )
+
+The If-Match header in general asumes that the affected resource exists, if it
+does not, the request must fail since no entity is there to compare the given
+criteria too (no entity exists). The header either specifies "*", to indicate
+that an entity must exist, whichever that is. Alternatively any number of
+entity tags can be given, devided by ",". If one of the given tags match the
+current state of the resource, the method is performed as if not If-Match
+header was given. Else the method must fail with 412 (Precondition failed).
+
+In case the request would have failed anyway (not result in a 2xx or 412
+status), the If-Match condition is not even checked, but the error response
+generated by the request is returned. The reaction of a server to a combination
+of multiple If-* headers is undefined.
+
+.. Note::
+ We should just throw all If-* headers away if a combination of the occurs,
+ so the backend does not need to deal with it.
+
+Examples: ::
+
+ If-Match: "xyzzy"
+ If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
+ If-Match: *
+
+If-None-Match
+-------------
+
+This header behaves similar to the If-Match header, except that the operation
+is only performed if none of the submitted entity tags matches. In case the
+operation is a GET or a HEAD operation and one of the tags matched, the server
+should return a 304 (Not Modified) code, in all other cases a 412 (Precondition
+Failed) must be returned.
+
+The header is defined like this: ::
+
+ If-None-Match = "If-None-Match" ":" ( "*" | 1#entity-tag )
+
+The '*' again means that any entity tag exists (as for If-Match). In case of
+the If-None-Match header, the operation will be executed only of no entity of
+the resource exists. In fact this means that the resource does not exist.
+
+Examples: ::
+
+ If-None-Match: "xyzzy"
+ If-None-Match: W/"xyzzy"
+ If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
+ If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz"
+ If-None-Match: *
+
+If-Range
+--------
+
+The If-Range header does only make sense to be repected, if the server supports
+partial GET requests and resuming of such. Since the Webdav component does not
+support this, yet, the header will be ignored.
+
+.. Note::
+ If we support partial GET sometimes, support for this header must be
+ considered, too.
+
+ETag
+----
+
+The ETag header is send by a server to give the client an entity-tag for the
+current resource that he can use later with any of the headers described above.
+The ETag header is therefore a response header, while the headers described
+above are request headers.
+
+The ETag header is build up like this: ::
+
+ ETag = "ETag" ":" entity-tag
+
+Examples::
+
+ ETag: "xyzzy"
+ ETag: W/"xyzzy"
+ ETag: ""
+
+.. Attention::
+ The following is an asumption that should be verified somehow. It seems that
+ the ETag header is only defined for a single resource, which indicates that
+ responses that affect multiple resources should not contain it. For Webdav
+ this includes several methods like COPY and MOVE, but also PROPFIND with a
+ Depth header other than 0.
+
Lock support
^^^^^^^^^^^^
--
svn-components mailing list
svn-components@lists.ez.no
http://lists.ez.no/mailman/listinfo/svn-components
