Subject: Review: Redirect Reference Resources -- Part one

From: Juergen Reuter <[email-masked]>
Date: Mon, 07 Feb 2000 14:50:31 +0100

Following the working group's last call for comments, below is the
first part of a review of the Redirect Reference Resources Protocol.
It covers the abstract, tabe of contents and chapters 1 to 6 of the
protocol.

********

> Abstract
> ...
> The related specification, RFC xxxx, defines bindings, and the BIND 
> method for creating them.

The problem of circularity in cross-refencing other specifications has
already been discussed for the bindings protocol and, as far as I
understand, holds true for this protocol as well.

> Creating a new binding to a resource 
> indirectly creates one or more new URIs mapped to that resource, which 
> can then be used to access it.  Servers are required to insure the 
> integrity of any bindings that they allow to be created.

IMHO, issues that refer to the bindings protocol should not appear in
this protocol and not at all in the abstract, unless they are needed
for clarification of the definition of redirect reference resources in
contrast to bindings. To avoid circular cross-references, this can only
have informational character to the reader, but no specificational
character.  If, nevertheless, the contrast to bindings is to be revealed,
it should be made obviously using language like "while bindings are
useful for ..., redirect references are nice when ...", or "unlike
bindings, which ..., redirect references do ...".  Anyway, the above
section is too specific to appear in an abstract.

What I am missing are some introductional notes on redirect references
themselves; that they have already been specified long ago in HTTP/1.0
(or even before?) and are today frequently used throughout present
HTTP servers' configuration capabilities (this is probably what the
specification calls "ordinary HTTP 1.1 redirect"); but that until now,
there is no standardized way for a client to remotely create, modify
and delete redirect references on a server; that this protocol claims
redirect references to be viewed as WebDAV resources of a new resource
type; and that this protocol provides new DAV:properties and a new
method to create, modify and delete redirect reference resources in a
proper and standardized manner.

> Table of Contents
>
> 1	Notational Conventions........................................3
> 2	Introduction..................................................3

As Roy pointed out for the bindings protocol, the section "Notational
Conventions" should not appear before the introduction.  This should
also hold true for this specification.

> 16.4	Private Locations May Be Revealed............................23

Personally, I would not expect a complete sentence as header line.

> Slein et al.                                                    Page 2

For the bindings protocol Roy pointed out that a working draft in that
status should not be formatted, even if the internet official protocol
standards track tells something different.  This should also hold true
for this specification.

> 2 Introduction

The first three sections of this chapter are identical to those of the
bindings protocol; hence the general discussion made for the
corresponding sections of the bindings protocol should also hold true
for this specification.

> A redirect 
> reference resource is a resource in one collection whose purpose is to 
> forward requests to another resource (its target), usually in a 
> different collection.

I move "usually" be replaced by "possibly".

> The companion specification, RFC xxxx,

This may result in yet another circular cross-reference.

> defines the BIND method, a 
> different mechanism for allowing clients to create alternative access 
> paths to existing WebDAV-compliant resources. The BIND method lets 
> clients associate a new URI with an existing WebDAV resource.  This URI 
> can then be used to submit requests to the resource.  Since URIs of 
> WebDAV-compliant resources are hierarchical, and correspond to a 
> hierarchy of collections in resource space, the BIND method also has the 
> effect of adding the resource to a collection.  As new URIs are 
> associated with the resource, it appears in additional collections.

Could the above section be dropped?  To reveal the differences between
bindings and redirect reference resources, the next but one section
("By contrast, ...") should suffice.

> 3 Terminology

> Reference Resource
>      ...
>      bindings (defined in [B])

Once again a reference to bindings.

> Direct Reference Resource
>     Direct Reference Resources are out of scope for this 
>     specification, but are defined here for contrast with redirect 
>     reference resources.

Does it really make sense to define terms that are out of scope?
Direct Reference Resources as defined here are only a single example
for something that is not a redirect reference resource, but one
probably could define an arbitrary number of other things that are as
well "in contrast"; it just depends on what particular attribute the
contrast refers to.  Anyway, this definition probably should require
that a direct reference resource be a reference resource.

> 4 Overview of Redirect Reference Resources

> ...
> It is also what insures that redirect reference resources 
> will be simple to implement and that cross-server references will be 
> possible.

It may *help* that redirect reference resources will be simple to
implement, but it can not ensure it, unless you implicitly make
assumptions about the implementation, which should not be made in this
specification.

> 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 12.1 below), whose 
> value contains the URI of the target resource.  It can then submit 
> requests to the target resource. 

Why not using the HTTP Location header field to resolve the reference?
This can be (and usually is) done even by clients that are unaware of
the above.  The true reason for introducing a DAV:reftarget property
seems to be the possibility to *modify* the URI of the target resource
rather than resolving the reference.

> 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 [WebDAV]), DAV:redirectref, 
> is defined in Section 13.1 below.

Just wondering: is there a standardized registration procedure for new
DAV:resourcetype property values, e.g. something like MIME
registration procedures as defined in RFC 2048?  If not, that might
substantially impair interoperability.

> Since a redirect reference resource is a resource, it can have its own 
> properties and body, and 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 11.2 below) is provided so that 
> referencing-aware clients can control whether an operation is applied to 
> the redirect reference resource or to its target resource.

When I read this, I first thought you were going to specify something
that behaves like a direct reference resource, which however was
declared to be out of scope for this specification.  Having a look at
section 6.2, it then (hopefully) became clear to me what you really
wanted to say in this section.  Hence I move to modify the wording,
e.g. as follows:

"While the basically intended behaviour of a redirect reference
resource is to redirect a client to a different location, a different
behaviour of the server is expected when creating, modifying or
deleting the redirect reference resource itself.  To let the server
distinguish between these two fashions of behaviour, the
Apply-To-Redirect-Ref request header (defined in Section 11.2 below)
is provided so that a referencing-aware client can tell the server
that it does not want to be redirected, but that the requested
operation is to be applied to the redirect reference resource itself."

> 5 Creating a Redirect Reference Resource
>
> The MKRESOURCE method is used to create new redirect reference 
> resources.

I propose that "the MKRESOURCE method" should better read "the new
MKRESOURCE method", as the method seems to be newly introduced in this
specification.

> It creates a new binding between the new redirect reference resource
> and the last path segment of the Request-URI.  The new binding is
> added to its parent collection, identified by the Request-URI minus
> its trailing slash (if present) and final segment.

So, this protocol does not just informally refer to the bindings
protocol, but really depends on it?  Does this imply a specific
implementation of redirect reference resources using bindings?  Or is
the meaning of the word "binding" not the same as defined in the
bindings protocol?

> 5.1 MKRESOURCE
>
> The MKRESOURCE method requests the creation of a resource and 
> initialization of its properties.  It allows resources other than 
> standard data containers and collections to be created and their 
> properties initialized in one atomic operation.

N.b.: the more general concept of MKRESOURCE has the potential
of replacing the more specific concept of MKCOL, if it allowed a
DAV:collection value for the DAV:resourcetype property.

> The body of the new resource is empty.

What is the body of a resource?  For standard data containers, the
intended meaning seems to be clear, but what is the meaning for other
resource types?  In this case, this probably should read "The entity
body of a response returned from a GET request on the new resource
MUST be empty.", or the term "body of a resource" should be defined
somewhere else.  (N.b.: WebDAV also uses the term "body of a resource"
in sections 8.10.2 and 17.5 without prior definition).  Anyway, for
clients that do not support automatic redirection, it is sensible to
provide some text/html response body to be returned from a GET request
that can be shown to the user.  Hence, I move to take away the
restriction that the body must be empty.

> The properties of the new resource are as specified by the 
> DAV:propertyupdate request body, using PROPPATCH semantics.

I had to read this sentence again and again to understand the
meaning.  I move to choose a different wording, e.g. as follows:

"The MKRESOURCE request MAY contain a DAV:propertyupdate request body
to initialize resource properties.  Herein, the semantics is the same
as when sending a MKRESOURCE request without request body, followed by
a PROPPATCH with the DAV:propertyupdate request body."

This leads to a new question: is MKRESOURCE atomic (from all WebDAV
client's perspective)?  Or can another client access the new
resource's properties before they fully have been initialized?

If an error is encountered while initializing the properties, that
means that some properties may have been initialized, while others
still are undefined; atomicity would at least in that case be broken.
However, if MKRESOURCE could atomically create and (read & write) lock
a resource, this would prevent other clients from accessing the newly
created resource until the creator decides to remove the lock.  Hence,
I would like to put up for discussion the following question: Should a
MKRESOURCE request may contain a DAV:lockinfo XML element and those
request headers defined for the LOCK method in order to request atomic
creation and locking of a new resource?

> If the response status code is not 201, then a new resource is not 
> created ...

"is not created" should probably read "was not created", making it
consistent with the status codes description a few lines below (or is
deferred creation allowed for an implementation of MKRESOURCE?).

> Response Marshalling:
>
> Responses from a MKRESOURCE request SHOULD NOT be cached, as MKRESOURCE 
> has non-idempotent semantics.

I move that if MKRESOURCE has non-idempotent semantics, then responses
MUST NOT be cached unless the client and the server agree on some
cache protocol outside of the scope for this specification.

> 6 Operations on Redirect Reference Resources
>
> Although non-referencing-aware clients cannot create reference 
> resources,

I move that "non-referencing-aware clients" be replaced with "clients
not aware of this protocol".

> A reference-aware WebDAV client can act on this response in one of two 
> ways.  It 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 header in 
> order to operate on the reference resource itself.

A client can act on this response not only in one of these two ways,
but in any way it chooses.  I suppose you just want to present two
examples of typical behaviour that a client may choose.

> If the Apply-To-Redirect-Ref header is present, the request MUST be
> applied to the reference resource itself,

Here is the same wording problem as in chapter 4, where the wording
sounds as if direct references were addressed.

> A reference-aware client may know before submitting its request that the 
> Request-URI identifies a redirect reference resource. In this case, if 
> the client wants to apply the method to the reference resource, it can 
> save the round trip caused by the 302 response by using an Apply-To-
> Redirect-Ref header in its initial request to the URI.

Strictly spoken, this is redundant information and hence should be
dropped.  But it may be worth to be mentioned in an example.

> When 
> Apply-To-Redirect-Ref is used with GET or HEAD, the Redirect-Ref entity 
> header MUST be returned, along with all HTTP headers that make sense for 
> reference resources (for example, Cache-Control, Age, ETag, Expires, and 
> Last-Modified).  

As all HTTP headers that make sense for reference resource MUST be
returned, I would expect a precise definition of which headers do make
sense rather than just listing some examples.  Or "MUST" should be
replaced with "SHOULD" for these HTTP headers; then just giving some
examples seems ok.

> A redirect reference resource MAY have a body, though none is defined 
> for it in this specification.  The PUT method can be used, with Apply-
> To-Redirect-Ref, to create or replace the body of a redirect reference 
> resource.

Once again, this sounds as if you are assuming that a resource having
a body means that the body is stored in a standard data container
associated with the redirect reference resource.  But, in fact, the
specification does not state that a GET will return the same body that
was PUT onto the server.  Hence I move the behaviour be concretized,
using terms such as "request body", "entity body" and "response body".
Perhaps it may appropriate to state: "A PUT with Apply-To-Redirect-Ref
MAY contain a request body.  The semantics of the request body is out
of scope for this specification; in particular, this specification
does not require the same body to be returned in the response of a
subsequent GET with Apply-To-Redirect-Ref header."

> Since MKCOL and MKRESOURCE fail when applied to existing resources, if 
> the client attempts to resubmit the request to the target resource, the 
> request MUST fail (unless the reference resource is a dangling 
> reference).  Similarly, if the client attempts to resubmit the request 
> to the reference resource with an Apply-To-Redirect-Ref header, the 
> request MUST fail.

Once again, I move this paragraph be moved into an example section.

> Since ORDERPATCH applies only to collections, an ORDERPATCH request with 
> an Apply-To-Redirect-Ref header on a redirect reference resource MUST 
> fail.

What is ORDERPATCH?  Where is it specified?

> 6.1 Example: GET on a Redirect Reference Resource
> ...
> The Redirect-Ref header informs a reference-aware client 
> ...

I move that "reference-aware client" be replaced with "client aware of
this protocol".

> 6.2 Example: PUT on a Redirect Reference Resource with Apply-To-
> Redirect-Ref
> ...

See the above discussion on the "resource body" issue.

... to be continued ...

     Juergen Reuter

---

From: "Slein, Judith A" <[email-masked]>
Date: Mon, 14 Feb 2000 13:51:54 -0500

Juergen,

Thanks very much for your detailed review of the first 6 sections of
Redirect References.  I am sure that most of your suggestions for improved
language and focus in the spec will be accepted.  I'll just comment here on
a few of the deeper issues that you raise.

-----Original Message-----
From: Juergen Reuter [mailto:[email-masked]]
Sent: Monday, February 07, 2000 8:51 AM
To: WebDAV WG
Cc: [email-masked]; [email-masked]
Subject: Review: Redirect Reference Resources -- Part one

<js>
You are right that we need to step back and consider why we introduced the
DAV:reftarget property to begin with:

There is no other way to find the redirect references to a given resource
except by doing a search on this property.  (Even with DAV:reftarget, you
can only discover the local redirects to a given resource.)

A referencing-aware client can operate more efficiently with this property.
For example, if it needs to perform some operation on the targets of all of
the redirect references in a collection, it can do a PROPFIND to retrieve
all the DAV:reftarget properties at once, and submit requests directly to
the target resources, instead of performing two round-trips for each
redirect reference.

At the moment the spec prevents the use you suggest, since it says that
DAV:reftarget is readonly.  The rationale for this was that changing the
value of DAV:reftarget (changing what resource it points to) is effectively
to create an entirely new redirect reference, so we would do better to
require clients to do a new MKRESOURCE with the desired DAV:reftarget.

But since the server is (probably) not going to maintain DAV:reftarget, the
client might just be wanting to update it to keep it pointing at the same
resource.  So maybe it should be a client-writable property.
</js>

<js>
There is no standardized registration procedure.  Should we make this an
issue on the RFC-2518 list?
</js>

<js>
You are right that something needs to be done about this language.  Joe
Orton also pointed out that there is confusion here and in our discussion of
PUT with redirect references about what is allowed and what the result is.

MKRESOURCE is defined not just for this spec, but also for DeltaV, and the
plan is for the two specs to contain identical definitions (Section 5.1 of
redirect references should be identical to what appears in the DeltaV spec).
The intent is that the MKRESOURCE method lets you create a resource and set
its properties, but it doesn't provide any way to do the equivalent of a
PUT.  So we need to find a way to express that without preventing the useful
behavior you describe, of responding to GET with a response body explaining
that the resource you are looking for is located somewhere else.
</js>

> DAV:propertyupdate request body, using PROPPATCH semantics.

.
.
.

<js>
I would rather not take on this issue in the context of redirect references.
Whatever the semantics of PROPPATCH are in RFC 2518, that's what you get
here.  If RFC 2518 provides a way to ask that a resource be read-locked
while its properties are being set, it can be used here.  Otherwise, not.

I would actually be just as happy myself to have MKRESOURCE do nothing more
than create a resource, and make setting its properties be a separate
operation.  But I know that others feel strongly that MKRESOURCE needs to do
both.
</js>