Subject: [Fwd: I-D ACTION:draft-dusseault-http-patch-08.txt]

From: James M Snell <[email-masked]>
Date: Mon, 23 Jul 2007 16:27:27 -0700

FYI... the updated PATCH draft has posted.  See below.

- James

-------- Original Message --------
[snip]
From:  <[email-masked]>
To:  <[email-masked]>
Subject: I-D ACTION:draft-dusseault-http-patch-08.txt
[snip]

A New Internet-Draft is available from the on-line Internet-Drafts
directories.

	Title		: PATCH Method for HTTP
	Author(s)	: J. Snell, L. Dusseault
	Filename	: draft-dusseault-http-patch-08.txt
	Pages		: 13
	Date		: 2007-7-23
	
Several applications extending HTTP require a feature to do partial
   resource modification.  Existing HTTP functionality only allows a
   complete replacement of a document.  This proposal adds a new HTTP
   method, PATCH, to modify an existing HTTP resource.

A URL for this Internet-Draft is:
http://www.ietf.org/internet-drafts/draft-dusseault-http-patch-08.txt

[snip]

---

From: Julian Reschke <[email-masked]>
Date: Wed, 25 Jul 2007 10:55:36 +0200

Find below some comments on patch-08:

Section 2.1., para. 6:
OLD:

     It is RECOMMENDED that Servers provide strong ETags for all resources
     for which PATCH is supported.

Again, there's a set patch operations where the previous state of the 
resource is irrelevant, such as for "append" operations.  I think they 
should be allowed, thus this requirement is a problem.  Just state that 
strong etags can help making sure that you apply the patch to the 
version you want it   apply to, and let's leave it at that.

Section 2.1., para. 8:
OLD:

     The server MUST NOT ignore any Content-* (e.g.  Content-Range)
     headers that it does not understand or implement and MUST return a
     501 (Not Implemented) response in such cases.

A MUST level requirement with a wild card Just Does Not Work.  I'm not 
even sure what this is about.  As far as I understand what we could say, 
if at all, is that entity headers sent with the request apply to the 
enclosed entity, not the resource being addressed.  Thus, for instance, 
a "Content-Language" request header in PATCH describes the natural 
language of the patch document (entity).  So what why would it be a 
problem to ignore it?  Or, rephrasing it, what do you expect the server 
to do with it?

Section 2.3., para. 2:
OLD:

     Accept-Patch = "Accept-Patch" ":" #( media-range )

Need to state nature of ABNF syntax; here: borrowed from RFC2616.

Section 2.3., para. 4:
OLD:

  2.3.1.  Example

NEW:

  2.3.1.  Example: OPTIONS request and response for specific resource

Best regards, Julian

---

From: James M Snell <[email-masked]>
Date: Wed, 25 Jul 2007 09:59:39 -0700

> version you want it   apply to, and let's leave it at that.

If this were a MUST, I'd agree.  There are some extremely good reasons
why an ETag should be provided, even if there are some good cases where
they might not be useful.

> problem to ignore it?  Or, rephrasing it, what do you expect the server

FWIW, this language was actually taken directly from RFC2616.  For
something like Content-Language, ignoring it really is not all that much
of a problem.  For Content-Range, however, ignoring the header could
cause some serious problems with the processing of the PATCH operation.

>  2.3.1.  Example: OPTIONS request and response for specific resource

I'll fix these in the next draft. Thank you very much for the comments.

- James

---

From: "Mark Baker" <[email-masked]>
Date: Wed, 25 Jul 2007 13:20:03 -0400

James, I hope you incorporate the change I requested here;

http://lists.w3.org/Archives/Public/ietf-http-wg/2007JulSep/0052.html

Thanks.

Mark.

-- 
Mark Baker.  Ottawa, Ontario, CANADA.         http://www.markbaker.ca
Coactus; Web-inspired integration strategies  http://www.coactus.com

---

From: Julian Reschke <[email-masked]>
Date: Wed, 25 Jul 2007 19:30:23 +0200

> they might not be useful.

If it's foreseeable that in some use cases they aren't useful, there 
shouldn't be SHOULD-level requirement to provide them.

> FWIW, this language was actually taken directly from RFC2616.  For

Interesting, we'll have to clarify this in rfc2616bis then.

> cause some serious problems with the processing of the PATCH operation.

Yes. Let's state clearly what the requirement is then. MUST NOT ignore 
Content-Range?

Best regards, Julian

---

From: James M Snell <[email-masked]>
Date: Fri, 27 Jul 2007 10:34:45 -0700

Hey Mark,

Yeah, I think you're right on the Content-Location thing.  FWIW, Atompub
takes the same approach.

Regarding this comment:

> It also seems a bit odd considering that the intent of PATCH is - like
> PUT - to set the state of the resource explicitly, so in general,
> after a successful response the client pretty much knows the state and
> so the representation is probably not communicating much.

For simple byte and char oriented delta's, that's true, but for
structural or even semantically oriented patches, this is not
necessarily true.  For instance, the patch format could be telling the
server to add an attribute to an XML element dependent on some boolean
condition.  The server could successfully apply the patch, but the
client would have no way of knowing the exact result.

- James

---

From: Lisa Dusseault <[email-masked]>
Date: Tue, 31 Jul 2007 08:54:43 -0700

On Jul 25, 2007, at 1:55 AM, Julian Reschke wrote:

> A MUST level requirement with a wild card Just Does Not Work.  I'm  
> not even sure what this is about.  As far as I understand what we  
> could say, if at all, is that entity headers sent with the request  
> apply to the enclosed entity, not the resource being addressed.   
> Thus, for instance, a "Content-Language" request header in PATCH  
> describes the natural language of the patch document (entity).  So  
> what why would it be a problem to ignore it?  Or, rephrasing it,  
> what do you expect the server to do with it?

This is the same requirement found in RFC2616 for PUT, and for the  
same reasons.

It's easy to implement.    If the server receives a header beginning  
with "Content-" that is not in some list of "Content-" headers it has  
code to deal with in a request, like "Content-Range" or "Content- 
Signature", then it needs to return 501 Not Implemented.   It would  
be a problem to ignore these headers because the client means  
something about the request body which won't be handled if they're  
ignored.

It's a standard type of requirement to allow future extensions to be  
designed more flexibly.  A more generic approach can be found in  
RFC2774 where "mandatory" header prefixes indicate mandatory-to- 
implement-otherwise-fail.

Lisa

---

From: Julian Reschke <[email-masked]>
Date: Tue, 31 Jul 2007 18:09:56 +0200

Lisa Dusseault wrote:
>> even sure what this is about.  As far as I understand what we could 
>> say, if at all, is that entity headers sent with the request apply to 
>> the enclosed entity, not the resource being addressed.  Thus, for 
>> instance, a "Content-Language" request header in PATCH describes the 
>> natural language of the patch document (entity).  So what why would it 
>> be a problem to ignore it?  Or, rephrasing it, what do you expect the 
>> server to do with it?
>>
> 
> 
> This is the same requirement found in RFC2616 for PUT, and for the same 
> reasons.   

Well, we already discussed it. Turns out it's underspecified, not 
implemented in Apache or IIS, and Roy said it needs to be fixed 
(<http://lists.w3.org/Archives/Public/ietf-http-wg/2007JulSep/0095.html>).

> code to deal with in a request, like "Content-Range" or 
> "Content-Signature", then it needs to return 501 Not Implemented.   It 
> would be a problem to ignore these headers because the client means 
> something about the request body which won't be handled if they're ignored.

The requirement has been there for over 10 years, and clients still 
can't rely on it (at least if they use the two most widely deployed 
servers allowing PUT). This should tell us something, I guess.

> designed more flexibly.  A more generic approach can be found in RFC2774 
> where "mandatory" header prefixes indicate 
> mandatory-to-implement-otherwise-fail.  

Although I link many things in RFC2774, I'll have to point out it's not 
widely implemented either. We probably will have to live with Must-Ignore.

Now, for PATCH things *could* be defined otherwise. To do that, I'd like 
to have a clarification of what it means to "understand or implement" a 
Content-* header in the context of PATCH (*), and also a use case that 
needs this. Otherwise it'll be a useless deviation from other HTTP 
methods, and will get as much implementation as it got for PUT.

Best regards, Julian

(*) So, what does "Content-Range" mean for PATCH?

---

From: Lisa Dusseault <[email-masked]>
Date: Tue, 31 Jul 2007 09:34:06 -0700

>> http://lists.w3.org/Archives/Public/ietf-http-wg/2007JulSep/0052.html

If we allow the server to return arbitrary bodies in a 200 response  
to a PATCH, we'll have to be very clear on how clients should handle  
the returned information.  A caching or synching client might use the  
body as the new representation of the resource regardless of what  
headers appeared in the 200 response.  Are there any other headers  
besides "Content-Location" which might indicate whether the response  
body was a representation of the resource or something else?

If we don't have an immediate use for the 200 body other than  
returning a reasonable representation of the resource, let's narrow  
down the potential meanings and simply require one meaning for 200  
OK.  Otherwise, without an immediate implementation to test against,  
I am not too hopeful about clients handling properly a 200 OK which  
differs from the normal meaning.

---

From: Lisa Dusseault <[email-masked]>
Date: Tue, 31 Jul 2007 09:46:27 -0700

On Jul 31, 2007, at 9:09 AM, Julian Reschke wrote:

>>> A MUST level requirement with a wild card Just Does Not Work.   
>>> I'm not even sure what this is about.  As far as I understand  
>>> what we could say, if at all, is that entity headers sent with  
>>> the request apply to the enclosed entity, not the resource being  
>>> addressed.  Thus, for instance, a "Content-Language" request  
>>> header in PATCH describes the natural language of the patch  
>>> document (entity).  So what why would it be a problem to ignore  
>>> it?  Or, rephrasing it, what do you expect the server to do with it?
>>>
>> It's easy to implement.    If the server receives a header  
>> beginning with "Content-" that is not in some list of "Content-"  
>> headers it has code to deal with in a request, like "Content- 
>> Range" or "Content-Signature", then it needs to return 501 Not  
>> Implemented.   It would be a problem to ignore these headers  
>> because the client means something about the request body which  
>> won't be handled if they're ignored.
>
>> It's a standard type of requirement to allow future extensions to  
>> be designed more flexibly.  A more generic approach can be found  
>> in RFC2774 where "mandatory" header prefixes indicate mandatory-to- 
> Although I link many things in RFC2774, I'll have to point out it's  
> not widely implemented either. We probably will have to live with  
> Must-Ignore.
>
> Now, for PATCH things *could* be defined otherwise. To do that, I'd  
> like to have a clarification of what it means to "understand or  
> implement" a Content-* header in the context of PATCH (*), and also  
> a use case that needs this. Otherwise it'll be a useless deviation  
> from other HTTP methods, and will get as much implementation as it  
> got for PUT.
>
> Best regards, Julian
>

I can certainly deal with something along these lines.  I agree this  
kind of thing is poorly implemented and appreciate the testing.  If  
2616 changes we could also change PATCH if the timing is right.

When should we attempt to have a HTTP Interop event?  A test suite  
like LITMUS (in fact I think part of Litmus can be reused) would go a  
long way towards alerting implementors to simple requirements that  
are easily missed.  A test suite could attempt a PUT with "Content- 
BOGUS: MUST FAIL" (assuming we kept this requirement) and expect to  
see at least some kind of error if not a 501.

Lisa

---

From: "Mark Baker" <[email-masked]>
Date: Tue, 31 Jul 2007 12:59:17 -0400

Hi Lisa,

On 7/31/07, Lisa Dusseault <[email-masked]> wrote:
> headers appeared in the 200 response.

That would be a broken client, AFAICT.  Are you aware of any software
which behaves this way?

>  Are there any other headers

Not AFAIK.

> differs from the normal meaning.

The normal meaning from 2616 seems to be "the request was successful,
here's some data".  I don't see any reason to be more specific than
that.

Mark.

---

From: Julian Reschke <[email-masked]>
Date: Tue, 31 Jul 2007 19:03:48 +0200

Lisa Dusseault wrote:
> kind of thing is poorly implemented and appreciate the testing.  If 2616 
> changes we could also change PATCH if the timing is right.
> 
> When should we attempt to have a HTTP Interop event?  A test suite like 
> LITMUS (in fact I think part of Litmus can be reused) would go a long 
> way towards alerting implementors to simple requirements that are easily 
> missed.  A test suite could attempt a PUT with "Content-BOGUS: MUST 
> FAIL" (assuming we kept this requirement) and expect to see at least 
> some kind of error if not a 501.

So again, what is the semantics of "Content-Range" in the context of PATCH?

Best regards, Julian

---

From: Lisa Dusseault <[email-masked]>
Date: Tue, 31 Jul 2007 10:43:17 -0700

On Jul 31, 2007, at 9:59 AM, Mark Baker wrote:

> That would be a broken client, AFAICT.

Interesting!  What's your basis for believing that?    Would a client  
that cached the body of a 200 OK response in response to a GET behave  
correctly if it cached the body regardless of whether there was a  
Content-Location header?  According to my reading of 2616, the  
Content-Location header might or might not be there if the response  
contains a representation of the resource.

> Are you aware of any software
> which behaves this way?

No, because we don't have PATCH clients implemented yet.

> here's some data".  I don't see any reason to be more specific than

The 200 OK response for GET is certainly more specific than that --  
the data has a specific context, address and cache behavior  
intended.  That's what I'm driving at for PATCH.

Lisa

---

From: Lisa Dusseault <[email-masked]>
Date: Tue, 31 Jul 2007 10:45:03 -0700

We could certainly add "Content-Range header MUST not appear in a  
PATCH request".  That could even be overridden by a future spec that  
uses the Content-Range header (and other directives, to be sure) to  
extend PATCH to replace certain ranges of the resource being updated.

Did you have a recommendation for the Content-Range header?

Lisa

On Jul 31, 2007, at 10:03 AM, Julian Reschke wrote:

>> I can certainly deal with something along these lines.  I agree  
>> this kind of thing is poorly implemented and appreciate the  
>> testing.  If 2616 changes we could also change PATCH if the timing  
>> is right.
>> like LITMUS (in fact I think part of Litmus can be reused) would  
>> go a long way towards alerting implementors to simple requirements  
>> that are easily missed.  A test suite could attempt a PUT with  
>> "Content-BOGUS: MUST FAIL" (assuming we kept this requirement) and  
>> expect to see at least some kind of error if not a 501.
>

---

From: Julian Reschke <[email-masked]>
Date: Tue, 31 Jul 2007 20:25:06 +0200

Lisa Dusseault wrote:
> 
> We could certainly add "Content-Range header MUST not appear in a PATCH 
> request".  That could even be overridden by a future spec that uses the 
> Content-Range header (and other directives, to be sure) to extend PATCH 
> to replace certain ranges of the resource being updated.
> 

No, I just want to make sure that *if* a spec makes mandatory 
requirements on the server treatment of an entire class of headers, it 
also defines how to implement them.

So what about Content-MD5? Any requirements above what RFC2616 says?

Best regards, Julian