Request for Comments: 4437 U.C. Santa Cruz
Category: Experimental G. Clemm
IBM
J. Reschke, Ed.
greenbytes
March 2006
Web Distributed Authoring and Versioning (WebDAV)
Redirect Reference Resources
Status of This Memo
This memo defines an Experimental Protocol for the Internet
community. It does not specify an Internet standard of any kind.
Discussion and suggestions for improvement are requested.
Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2006).
Abstract
This specification defines an extension to Web Distributed Authoring
and Versioning (WebDAV) to allow clients to author HTTP redirect
reference resources whose default response is an HTTP/1.1 3xx
(Redirection) status code. A redirect reference makes it possible to
access the target resourced indirectly through any URI mapped to the
redirect reference resource. This specification does not address
remapping of trees of resources or regular expression based
redirections. There are no integrity guarantees associated with
redirect reference resources. Other mechanisms can also be used to
achieve the same functionality as this specification. This
specification allows operators to experiment with this mechanism and
develop experience on what is the best approach to the problem.
Table of Contents
1. Introduction ....................................................3
2. Notational Conventions ..........................................4
3. Terminology .....................................................4
4. Overview of Redirect Reference Resources ........................5
5. Operations on Redirect Reference Resources ......................6
6. MKREDIRECTREF Method ............................................7
6.1. Example: Creating a Redirect Reference Resource
with MKREDIRECTREF .........................................8
7. UPDATEREDIRECTREF Method ........................................9
7.1. Example: Updating a Redirect Reference Resource with
UPDATEREDIRECTREF .........................................10
8. Operations on Collections That Contain Redirect
Reference Resources ............................................11
8.1. Example: PROPFIND on a Collection with Redirect
Reference .................................................11
8.2. Example: PROPFIND with Apply-To-Redirect-Ref on a
Collection with Redirect Reference Resources ..............13
9. Operations on Targets of Redirect Reference Resources ..........15
10. Relative References in DAV:reftarget ..........................15
10.1. Example: Resolving a Relative Reference in a
Multi-Status Response.....................................16
11. Redirect References to Collections ............................17
12. Headers .......................................................18
12.1. Redirect-Ref Response Header .............................18
12.2. Apply-To-Redirect-Ref Request Header .....................19
13. Redirect Reference Resource Properties ........................19
13.1. DAV:redirect-lifetime (protected) ........................19
13.2. DAV:reftarget (protected) ................................19
14. XML Elements ..................................................19
14.1. redirectref XML Element ..................................19
15. Extensions to the DAV:response XML Element for Multi-Status
Responses .....................................................20
16. Capability Discovery ..........................................20
16.1. Example: Discovery of Support for Redirect
Reference Resources ......................................20
17. Security Considerations .......................................21
17.1. Privacy Concerns .........................................21
17.2. Redirect Loops ...........................................21
17.3. Redirect Reference Resources and Denial of Service .......21
17.4. Revealing Private Locations ..............................22
18. Internationalization Considerations ...........................22
19. IANA Considerations ...........................................22
19.1. HTTP headers .............................................22
19.1.1. Redirect-Ref ......................................22
19.1.2. Apply-To-Redirect-Ref .............................23
20. Contributors ..................................................23
21. Acknowledgements ..............................................23
22. Normative References ..........................................23
1. Introduction
This specification extends the Web Distributed Authoring Protocol
(WebDAV) to enable clients to create new access paths to existing
resources. This capability is useful for several reasons.
WebDAV makes it possible to organize HTTP resources into hierarchies,
placing them into groupings, known as collections, that are more
easily browsed and manipulated than a single flat collection.
However, hierarchies require categorization decisions that locate
resources at a single location in the hierarchy, a drawback when a
resource has multiple valid categories. For example, in a hierarchy
of vehicle descriptions containing collections for cars and boats, a
description of a combination car/boat vehicle could belong in either
collection. Ideally, the description should be accessible from both.
Allowing clients to create new URIs that access the existing resource
lets them put that resource into multiple collections.
Hierarchies also make resource sharing more difficult, since
resources that have utility across many collections are still forced
into a single collection. For example, the mathematics department at
one university might create a collection of information on fractals
that contains bindings to some local resources, but also provides
access to some resources at other universities. For many reasons, it
may be undesirable to make physical copies of the shared resources:
to conserve disk space, to respect copyright constraints, or to make
any changes in the shared resources visible automatically. Being
able to create new access paths to existing resources in other
collections or even on other unrelated systems is useful for this
sort of case.
The redirect reference resources defined here provide a mechanism for
creating alternative access paths to existing resources. A redirect
reference resource is a resource in one collection whose purpose is
to redirect requests to another resource (its target), possibly in a
different collection. In this way, it allows clients to submit
requests to the target resource from another collection. It
redirects most requests to the target resource using an HTTP status
code from the 3xx range (Redirection), thereby providing a form of
mediated access to the target resource.
A redirect reference is a resource with properties but with no body
of its own. Properties of a redirect reference resource can contain
information such as who created the reference, when, and why. Since
redirect reference resources are implemented using HTTP 3xx
responses, it generally takes two round trips to submit a request to
the intended resource. Redirect references work equally well for
local resources and for resources that reside on a different system
from the reference.
The remainder of this document is structured as follows: Section 3
defines terms that will be used throughout the specification.
Section 4 provides an overview of redirect reference resources.
Section 5 defines the semantics of existing methods when applied to
redirect reference resources. Section 6 discusses how to create a
redirect reference resource, and Section 7 discusses updating
redirect references. Section 8 discusses their semantics when
applied to collections that contain redirect reference resources.
Sections 9 through 11 discuss several other issues raised by the
existence of redirect reference resources. Sections 12 through 15
define the new headers, properties, and XML elements required to
support redirect reference resources. Section 16 discusses
capability discovery. Sections 17 through 19 present the security,
internationalization, and IANA concerns raised by this specification.
The remaining sections provide a variety of supporting information.
2. Notational Conventions
Since this document describes a set of extensions to the WebDAV
Distributed Authoring Protocol [RFC2518], itself an extension to the
HTTP/1.1 protocol, the augmented BNF used here to describe protocol
elements is exactly the same as described in Section 2.1 of
[RFC2616]. Since this augmented BNF uses the basic production rules
provided in Section 2.2 of [RFC2616], these rules apply to this
document as well.
In this document, the key words "MUST", "MUST NOT", "REQUIRED",
"SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
and "OPTIONAL" are to be interpreted as described in [RFC2119].
3. Terminology
The terminology used here follows and extends that in the WebDAV
Distributed Authoring Protocol specification [RFC2518]. Definitions
of the terms resource, Uniform Resource Identifier (URI), and Uniform
Resource Locator (URL) are provided in [RFC3986].
Redirect Reference Resource
A resource created to redirect all requests made to it, using an
HTTP status code from the 3xx range, to a defined target resource.
Non-Reference Resource
A resource that is not a reference to another resource.
Target Resource
The resource to which requests are redirected by a redirect
reference resource. A target resource can be anything that can be
identified by an absolute URI (see [RFC3986], "absolute-URI").
This document uses the terms "precondition", "postcondition", and
"protected property" as defined in [RFC3253]. Servers MUST report
pre-/postcondition failures as described in Section 1.6 of this
document.
4. Overview of Redirect Reference Resources
For all operations submitted to a redirect reference resource, the
default response is a 302 (Found), accompanied by the Redirect-Ref
header (defined in Section 12.1, below) and the Location header
([RFC2616], Section 14.30) set to the URI of the target resource.
With this information, the client can resubmit the request to the URI
of the target resource.
A redirect reference resource never automatically forwards requests
to its target resource. Redirect resources bring the same benefits
as links in HTML documents. They can be created and maintained
without the involvement or even knowledge of their target resource.
This reduces the cost of linking between resources.
If the client is aware that it is operating on a redirect reference
resource, it can resolve the reference by retrieving the reference
resource’s DAV:reftarget property (defined in Section 13.2, below),
whose value contains the URI of the target resource. It can then
submit requests to the target resource.
A redirect reference resource is a new type of resource. To
distinguish redirect reference resources from non-reference
resources, a new value of the DAV:resourcetype property (defined in
[RFC2518]), DAV:redirectref, is defined in Section 14.1, below.
Since a redirect reference resource is a resource, methods can be
applied to the reference resource as well as to its target resource.
The Apply-To-Redirect-Ref request header (defined in Section 12.2,
below) is provided so that referencing-aware clients can control
whether an operation is applied to the redirect reference resource or
standard HTTP/WebDAV behaviour (redirection with a 3xx status code)
should occur. The Apply-To-Redirect-Ref header can be used with most
requests to redirect reference resources. This header is
particularly useful with PROPFIND, to retrieve the reference
resource’s own properties.
Implementation Note: Operations on the target of a redirect reference
usually do not affect the redirect reference itself. However,
clients should not rely on this behaviour (for instance, some servers
may update redirect references as a result of namespace operations on
the reference’s target).
5. Operations on Redirect Reference Resources
Although non-referencing-aware clients cannot create reference
resources, they should be able to submit requests through the
reference resources created by reference-aware WebDAV clients. They
should be able to follow any references to their targets. To make
this possible, a server that receives any request made via a redirect
reference resource MUST return a 3xx range (Redirection) status code,
unless the request includes an Apply-To-Redirect-Ref header
specifying "T". The client and server MUST follow [RFC2616], Section
10.3, but with these additional rules:
o The Location response header MUST contain a URI (see [RFC3986],
Section 3) that identifies the target of the reference resource.
o The response MUST include the Redirect-Ref header. This header
allows reference-aware WebDAV clients to recognize the resource as
a reference resource and to understand the reason for the
redirection.
A reference-aware WebDAV client can, like a non-referencing client,
resubmit the request to the URI in the Location header in order to
operate on the target resource. Alternatively, it can resubmit the
request to the URI of the redirect reference resource with the
"Apply-To-Redirect-Ref: T" header in order to operate on the
reference resource itself. In this case, the request MUST be applied
to the reference resource itself, and a 3xx response MUST NOT be
returned.
As redirect references do not have bodies, GET and PUT requests with
"Apply-To-Redirect-Ref: T" MUST fail with status 403 (forbidden).
6. MKREDIRECTREF Method
The MKREDIRECTREF method requests the creation of a redirect
reference resource.
If a MKREDIRECTREF request fails, the server state preceding the
request MUST be restored.
Responses from a MKREDIRECTREF request MUST NOT be cached, as
MKREDIRECTREF has non-idempotent and non-safe semantics (see
[RFC2616], Section 9.1).
Marshalling
The request body MUST be a DAV:mkredirectref XML element.
<!ELEMENT mkredirectref (reftarget, redirect-lifetime?)>
<!ELEMENT reftarget (href)>
<!ELEMENT redirect-lifetime (permanent | temporary)>
<!ELEMENT permanent EMPTY>
<!ELEMENT temporary EMPTY>
The DAV:href element is defined in [RFC2518] (Section 12.3) and
MUST contain either a URI or a relative-ref (see [RFC3986],
Sections 3 and 4.2).
If no DAV:redirect-lifetime element is specified, the server MUST
behave as if a value of DAV:temporary was specified.
If the request succeeds, the server MUST return 201 (Created)
status.
If a response body for a successful request is included, it MUST
be a DAV:mkredirectref-response XML element. Note that this
document does not define any elements for the MKREDIRECTREF
response body, but the DAV:mkredirectref-response element is
defined to ensure interoperability between future extensions that
do define elements for the response body.
<!ELEMENT mkredirectref-response ANY>
Preconditions
(DAV:resource-must-be-null): A resource MUST NOT exist at the
Request-URI.
(DAV:parent-resource-must-be-non-null): The Request-URI minus the
last past segment MUST identify a collection.
(DAV:name-allowed): The last segment of the Request-URI is
available for use as a resource name.
(DAV:locked-update-allowed): If the collection identified by the
Request-URI minus the last path segment is write-locked, then the
appropriate token MUST be specified in an If request header.
(DAV:redirect-lifetime-supported): If the request body contains a
DAV:redirect-lifetime element, the server MUST support the
specified lifetime. Support for DAV:temporary is REQUIRED, while
support for DAV:permanent is OPTIONAL.
(DAV:legal-reftarget): The specified is a legal URI or relative-
ref.
Postconditions
(DAV:new-redirectref): a new redirect reference resource is
created whose DAV:reftarget property has the value specified in
the request body.
6.1. Example: Creating a Redirect Reference Resource with MKREDIRECTREF
>> Request:
MKREDIRECTREF /~whitehead/dav/spec08.ref HTTP/1.1
Host: www.example.com
Content-Type: text/xml; charset="utf-8"
Content-Length: xxx
<?xml version="1.0" encoding="utf-8" ?>
<D:mkredirectref xmlns:D="DAV:">
<D:reftarget>
<D:href>/i-d/draft-webdav-protocol-08.txt</D:href>
</D:reftarget>
</D:mkredirectref>
>> Response:
HTTP/1.1 201 Created
This request resulted in the creation of a new redirect reference
resource at http://www.example.com/~whitehead/dav/spec08.ref, which
points to the resource identified by the DAV:reftarget property. In
this example, the target resource is identified by the URI
http://www.example.com/i-d/draft-webdav-protocol-08.txt. The
redirect reference resource’s DAV:resourcetype property is set to
DAV:redirectref, and its DAV:redirect-lifetime property has the value
DAV:temporary.
7. UPDATEREDIRECTREF Method
The UPDATEREDIRECTREF method requests the update of a redirect
reference resource.
If a UPDATEREDIRECTREF request fails, the server state preceding the
request MUST be restored.
Responses from a UPDATEREDIRECTREF request MUST NOT be cached, as
UPDATEREDIRECTREF has non-safe semantics (see [RFC2616], Section
9.1).
Marshalling
The request body MUST be a DAV:updateredirectref XML element.
<!ELEMENT updateredirectref (reftarget?, redirect-lifetime?)>
See Section 6 for a definition of DAV:reftarget and DAV:redirect-
lifetime.
If no DAV:reftarget element is specified, the server MUST NOT
change the target of the redirect reference.
If no DAV:redirect-lifetime element is specified, the server MUST
NOT change the lifetime of the redirect reference.
If a response body for a successful request is included, it MUST
be a DAV:updateredirectref-response XML element. Note that this
document does not define any elements for the UPDATEREDIRECTREF
response body, but the DAV:updateredirectref-response element is
defined to ensure interoperability between future extensions that
do define elements for the response body.
<!ELEMENT updateredirectref-response ANY>
Preconditions
(DAV:locked-update-allowed): if the resource is write-locked, then
the appropriate token MUST be specified in an If request header.
(DAV:must-be-redirectref): the resource identified by the
Request-URI must be a redirect reference resource as defined by
this specification.
(DAV:redirect-lifetime-supported): see Section 6.
(DAV:redirect-lifetime-update-supported): servers MAY support
changing the DAV:redirect-lifetime property; if they don’t, this
condition code can be used to signal failure.
(DAV:legal-reftarget): see Section 6.
Postconditions
(DAV:redirectref-updated): the DAV:reftarget and DAV:redirect-
lifetime properties of the redirect reference have been updated
accordingly.
7.1. Example: Updating a Redirect Reference Resource with
UPDATEREDIRECTREF
>> Request:
UPDATEREDIRECTREF /~whitehead/dav/spec08.ref HTTP/1.1
Host: www.example.com
Apply-To-Redirect-Ref: T
Content-Type: text/xml; charset="utf-8"
Content-Length: xxx
<?xml version="1.0" encoding="utf-8" ?>
<D:updateredirectref xmlns:D="DAV:">
<D:reftarget>
<D:href>/i-d/draft-webdav-protocol-08b.txt</D:href>
</D:reftarget>
</D:updateredirectref>
>> Response:
HTTP/1.1 200 OK
This request has updated the redirect reference’s DAV:reftarget
property to "/i-d/draft-webdav-protocol-08b.txt" and has not changed
the DAV:redirect-lifetime value. Note that the "Apply-To-Redirect-
Ref" request header must be used; otherwise, the request would result
in a redirect (3xx) response status.
8. Operations on Collections That Contain Redirect Reference Resources
According to [RFC2518], Section 9.2, methods that have defined
interactions with the "Depth" request header should apply all other
request headers to each resource in scope. However, applying this
principle to the "Apply-To-Redirect-Ref" header uniformly would make
it impractical to implement this specification on top of existing
servers and also would result in unexpected server behaviour for
clients that do not take the existence of redirect references into
account. On the other hand, the definition of the "Depth" header
allows alternate behaviours to be explicitly defined.
For this reason, this specification defines the interaction between
"Depth" and "Apply-To-Redirect-Ref" request headers on a case-by-case
basis and also provides a default for methods not mentioned here that
do not specify the behaviour themselves.
+-------------+-----------------+------------------+-----------+
| method name | defined in | supported depths | behaviour |
+-------------+-----------------+------------------+-----------+
| COPY | [RFC2518], 8.9 | 0, infinity | "T" |
| DELETE | [RFC2518], 8.7 | infinity | "T" |
| LOCK | [RFC2518], 8.11 | 0, infinity | "T" |
| MOVE | [RFC2518], 8.10 | 0, infinity | "T" |
| PROPFIND | [RFC2518], 8.2 | 0, 1, infinity | inherit |
| REPORT | [RFC3253], 3.6 | 0, 1, infinity | inherit |
| default | | | "T" |
+-------------+-----------------+------------------+-----------+
When the behaviour is defined to be "inherit", the method should
follow RFC2518’s default behaviour for "Depth" operations, which
means applying the value given for "Apply-To-Redirect-Ref" to each
resource in scope. On the other hand, when it is defined to be "T",
the method should behave as if a "Apply-To-Redirect-Ref: T" header
was specified for each operation on child resources. The latter
ensures that "Depth: infinity" operations will not fail unexpectedly
just because there was a redirect reference resource in scope.
8.1. Example: PROPFIND on a Collection with Redirect Reference
Resources
Suppose a PROPFIND request with Depth: infinity is submitted to the
following collection, with the members shown here:
/MyCollection/
(non-reference resource) diary.html
(redirect reference resource) nunavut
>> Request:
PROPFIND /MyCollection/ HTTP/1.1
Host: example.com
Depth: infinity
Apply-To-Redirect-Ref: F
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" ?>
<D:propfind xmlns:D="DAV: ">
<D:prop xmlns:J="http://example.com/jsprops/">
<D:resourcetype/>
<J:keywords/>
</D:prop>
</D:propfind>
>> Response:
HTTP/1.1 207 Multi-Status
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" ?>
<D:multistatus xmlns:D="DAV:" xmlns:J="http://example.com/jsprops/">
<D:response>
<D:href>/MyCollection/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype><D:collection/></D:resourcetype>
<J:keywords>diary, interests, hobbies</J:keywords>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>/MyCollection/diary.html</D:href>