Subject: new proposed text for locking overview

From: Julian Reschke <[email-masked]>
Date: Tue, 06 Jul 2004 20:24:48 +0200

Hi,

I noticed that RFC2518 historically says little about what a lock 
actually *is*, instead just describes it's behaviour (which of course 
needs to be done is well). The result is that essential information if 
spread across the document; instead of being in a single place. A good 
example for this is if you look at the various places in RFC2518 that 
say something about what a timeout is, what it means to refresh it, when 
the server needs to respect it and so on...

Here's what I wrote for 
<http://greenbytes.de/tech/webdav/draft-reschke-webdav-locking-latest.html#rfc.section.2> 
(which continues to progress nicely)...:

-- 

2.5  Status of a lock

    Having a URI (the lock token URI) on it's own, a lock is a resource
    in the sense defined by [RFC2396].  In general, this resource does
    not have a HTTP URL, and thus can not be directly manipulated using
    HTTP methods.  Instead, this specification defines the new methods
    LOCK (creating and refreshing locks, see Section 4) and UNLOCK
    (removing locks, see Section 5) that act indirectly on locks.

    A lock has state that can be indirectly observed by using the
    DAV:lockdiscovery property defined in Section 3.2.  At a minimum, the
    state of a lock consists of the items defined in the sections below.
    After lock creation, all parts of the state with the exception of the
    timeout value are immutable.

2.5.1  Lock Access Type

    At present, this specification only defines one lock access type, the
    "write" lock defined in Section xx.

2.5.2  Lock Scope

    A lock has either exclusive or shared scope (see Section 2.1).

2.5.3  Lock Root

    A lock is created as effect of a LOCK (creation) method request.  The
    lock root is the URL to which this request was adressed.

2.5.4  Lock Depth

    A "depth 0" lock only affects the resource to which the LOCK request
    was adressed to (the lock root).  This resource is said to be
    "directly locked" by the lock.

    On the other hand, a "depth infinity" lock on a collection
    additionally affects all members of that collection.  These resources
    are said to be "indirectly locked" by the lock.  A "depth infinity"
    lock on a non-collection resource behaves exactly the same way as a
    "depth 0" lock.

2.5.5  Lock Owner

    Clients can submit information about the lock owner when creating a
    lock.  This information should be sufficient for either directly
    contacting a principal (such as a telephone number or email URI), or
    for discovering the principal (such as the URL of a homepage).

    Owner information is kept with the lock so that it can be returned in
    the DAV:lockdiscovery property upon request.  Note that this
    information is entirely client-controlled, thus a server MUST store
    the information faithfully just like if it appeared in a WebDAV dead
    property (see [RFC2518], section 4).

2.5.6  Lock Timeout

    In general, a lock expires after a certain amount of time.  This time
    can be specified in the LOCK creation request (however servers are
    not required to honor this request).

    If the timeout expires then the lock may be lost.  Specifically, if
    the server wishes to harvest the lock upon time-out, the server
    SHOULD act as if an UNLOCK method was executed by the server on the
    resource using the lock token of the timed-out lock, performed with
    its override authority.  Thus logs should be updated with the
    disposition of the lock, notifications should be sent, etc., just as
    they would be for an UNLOCK request.

    The timers used for timeout expiry can be reset by the client by
    submitting a LOCK refresh request.

    Servers are advised to pay close attention to the values submitted by
    clients, as they will be indicative of the type of activity the
    client intends to perform.  For example, an applet running in a
    browser may need to lock a resource, but because of the instability
    of the environment within which the applet is running, the applet may
    be turned off without warning.  As a result, the applet is likely to
    ask for a relatively small timeout value so that if the applet dies,
    the lock can be quickly harvested.  However, a document management
    system is likely to ask for an extremely long timeout because its
    user may be planning on going off-line.

    A client MUST NOT assume that just because the time-out has expired
    the lock has been lost.  Clients MUST assume that locks may
    arbitrarily disappear at any time, regardless of the value given in
    the Timeout header.  The Timeout header only indicates the behavior
    of the server if "extraordinary" circumstances do not occur.  For
    example, an administrator may remove a lock at any time or the system
    may crash in such a way that it loses the record of the lock's
    existence.

-- 

Feedback appreciated,

Julian

-- 
<green/>bytes GmbH -- http://www.greenbytes.de -- tel:+492512807760

-- 
<green/>bytes GmbH -- http://www.greenbytes.de -- tel:+492512807760

---

From: Jason Crawford <[email-masked]>
Date: Tue, 6 Jul 2004 15:28:20 -0400

> (removing locks, see Section 5) that act indirectly on locks.

I don't like us calling a lock a resource. 

The other paragraphs you included seem reasonable.

---

From: Jason Crawford <[email-masked]>
Date: Tue, 6 Jul 2004 16:19:22 -0400

On Tuesday, 07/06/2004 at 09:37 ZE2, Julian Reschke wrote:
> Jason Crawford wrote:
> > ...
> > ...
> So can you explain *why* you don't like that terminology?

I'll try...

Because we tend to tend to think of words the way we've used them even if 
they technically have a more generic definition.   A lock seems to not 
behave like what we typically refer to as a resource.  There doesn't seem 
to be a lot of overlap in their most important features and methods.

You mentioned that a lock has a URI.   I think of the lock-token 
identifying the lock, but the fact that it uses URI-like syntax is only 
coincidental to me.

If a lock is a resource, I'd expect to be able to substitute the word 
"resource" for "lock" and have it sound reasonable.  I'm comfortable 
saying that a lock acts on a resource, but I'd not be comfortable saying a 
 resource acts on a resource.  Similarly... "depth-resource", "exclusive 
resource", or "write resource".   I'd prefer to simply think of resources 
as something that locks act upon.

For me it feels better not to define a lock at all beyond it's behavior 
rather than to say it's a resource.

J.

---

From: Julian Reschke <[email-masked]>
Date: Wed, 07 Jul 2004 01:31:48 +0200

Jason Crawford wrote:
> I'll try...
> 
> Because we tend to tend to think of words the way we've used them even 
> if they technically have a more generic definition.   A lock seems to 
> not behave like what we typically refer to as a resource.  There doesn't 
> seem to be a lot of overlap in their most important features and methods.

Well, I'd say they do.

- you can ask the server to create a new lock using LOCK, similar to how 
servers frequently create new resources upon POST,
- a lock has a URI,
- a lock has state,
- the state is observable indirectly through HTTP methods and last but 
not least,
- it's pefectly ok to implement locks as HTTP resources (for instance 
which would react to DELETE).

> identifying the lock, but the fact that it uses URI-like syntax is only 

That's fine.

> saying that a lock acts on a resource, but I'd not be comfortable saying 
> a  resource acts on a resource.  Similarly... "depth-resource", 
> "exclusive resource", or "write resource".   I'd prefer to simply think 
> of resources as something that locks act upon.

If you substitute "lock" by "lock resource" things sound much better. 
The concept is similar to the version history resource in DeltaV. It's 
not strictly needed for many things, but making it an HTTP resource 
gives you a lot of advantages (such as properties you can observe 
*directly* though PROPFIND instead of indirectly through a specific 
REPORT).

> rather than to say it's a resource.

The desire to define the *state* of a resource (what it must consist of) 
in a single place IMHO is independant of whether we actually *state* 
that it *is* a resource.  I just happen to think that things become much 
clearer by seeing it this way.

So far I've heard a resounding "of course" internally in our office, 
yours and Elias' feedback. Let's see what others think...

Julian

---

From: Lisa Dusseault <[email-masked]>
Date: Wed, 7 Jul 2004 12:05:46 -0700

Of course a lock can be *modelled* as a resource. Of course, 
RFC2518(bis) can explicitly model a lock as a resource.  Of course 
implementations can model a lock as a resource.  Note however we could 
instead choose to model the lock token as a resource if we wanted.

To argue at least as devil's advocate, we can also simply say that a 
lock token is in the format of a URI and stop there.  The original 
RFC2518 text says that a lock token "is represented as" a URI, not that 
it is a URI, although it also says that the URI identifies a lock.

RFC2396 is clear that URIs identify resources, but since then, the 
format defined for URIs in RFC2396 has been used for many other 
identifiers.   It's natural for a well defined format to be used for 
things beyond what it was defined for.  Even HTTP URLs are used for 
things which are not HTTP resources -- for example, when an XML 
namespace begins with the "http" scheme.   When does a new URI indicate 
a new resource?  Does the addition of query parameters to a HTTP URL 
mean that it's now addressing a different resource?  Who cares?

Is an XML namespace a resource?  Each namespace has a URI.  How would 
it help or hinder XML Namespace definition if we were to insist that an 
XML namespace were a resource? Must we insist that every URI identifies 
a resource?  What implications would this have for other specifications 
and their models?  Does the "DAV:" URI point to a DAV resource?  Other 
examples:
  - CAP uses "CAP URLs" without defining calendars as "resources" 
(draft-ietf-calsch-cap-13.txt)
  - XMPP URIs and URLs (there are several kinds) don't worry about 
whether the things identified are strictly resources

Another way to look at this; is there some problem solved by modelling 
a lock as a resource?  I took a look at the proposed text and 
"resource" is only used to refer to a lock in the first paragraph, so I 
don't understand the argument that this makes the text clearer.  That 
argument ought to involve a claim that the original text is unclear in 
some way that matters to interoperability.

My concrete worry is that implementors will feel that there are 
implementation implications resulting from modelling a lock as a 
resource, and make implementation decisions that aren't necessary.  
That was the result of the wording that a MOVE is the "logical 
equivalent of" a COPY followed by a DELETE -- definitional or 
explanatory wording was seen as normative in that case by some 
implementors.  Philosophical, definitional or modeling changes do have 
an effect on implementors behavior.  What effect would you like that to 
be?

Lisa

On Jul 6, 2004, at 4:31 PM, Julian Reschke wrote:

>
> Jason Crawford wrote:
>> I'll try...
>> Because we tend to tend to think of words the way we've used them 
>> even if they technically have a more generic definition.   A lock 
>> seems to not behave like what we typically refer to as a resource.  
>> There doesn't seem to be a lot of overlap in their most important 
>> features and methods.
>
> Well, I'd say they do.
>
> - you can ask the server to create a new lock using LOCK, similar to 
> how servers frequently create new resources upon POST,
> - a lock has a URI,
> - a lock has state,
>> identifying the lock, but the fact that it uses URI-like syntax is 
>> only coincidental to me.
>
> That's fine.
>
>> saying that a lock acts on a resource, but I'd not be comfortable 
>> saying a  resource acts on a resource.  Similarly... 
>> "depth-resource", "exclusive resource", or "write resource".   I'd 
>> prefer to simply think of resources as something that locks act upon.
>
>> For me it feels better not to define a lock at all beyond it's 
>> behavior rather than to say it's a resource.
>
> The desire to define the *state* of a resource (what it must consist 
> of) in a single place IMHO is independant of whether we actually 
> *state* that it *is* a resource.  I just happen to think that things 
> become much clearer by seeing it this way.
>

---

From: Julian Reschke <[email-masked]>
Date: Wed, 07 Jul 2004 21:34:19 +0200

> instead choose to model the lock token as a resource if we wanted.

According to RFC2396, anything that has a URI is a resource. There's a 
one-to-one relationship between a lock token and the lock. However, the 
lock token *is* the URI, so saying it is a resource doesn't really make 
sense.

> it is a URI, although it also says that the URI identifies a lock.

Anything that is identified by a URI is a resource. This by *by definition*.

RFC2518 says:

"A lock token is a type of state token, represented as a URI, which 
identifies a particular lock."

So we have a URI and an object identified by a URI. It's unclear to me 
why saying that object is a resource would be saying something new...

> identifiers.   It's natural for a well defined format to be used for 

Example, please?

> mean that it's now addressing a different resource?  Who cares?

A URI always identifies a resource. Whether a "new" URI identifies a 
"new" resource depends on URI scheme, implementation and intent.

> Is an XML namespace a resource?  Each namespace has a URI.  How would it 
> help or hinder XML Namespace definition if we were to insist that an XML 
> namespace were a resource? Must we insist that every URI identifies a 
> resource?  What implications would this have for other specifications 

Yes, because that's what the relevant RFCs say.

> and their models?  Does the "DAV:" URI point to a DAV resource?  Other 

Strictly speaking, "DAV:" isn't a URI (as defined by RFC2396). However, 
for instance, "DAV:displayname" is a resource.

> whether the things identified are strictly resources

I don't follow. What do you mean by "not being strictly a resource"? 
What's the definition of that? Do you have another definition for 
URI/resource than the one appearing in RFC2396?

> Another way to look at this; is there some problem solved by modelling a 
> lock as a resource?  I took a look at the proposed text and "resource" 
> is only used to refer to a lock in the first paragraph, so I don't 
> understand the argument that this makes the text clearer.  That argument 
> ought to involve a claim that the original text is unclear in some way 
> that matters to interoperability.

I think it helps understanding that a lock is an object that indeed has 
identity, a defined lifetime and observable properties.

> resource, and make implementation decisions that aren't necessary.  That 

Under the definition of RFC2396, there's no way to implement a WebDAV 
lock but as a resource. You may want to re-read RFC2396 
(<http://greenbytes.de/tech/webdav/rfc2396.html#rfc.section.1.1.p.3>) or 
RFC2396bis 
(<http://cvs.apache.org/viewcvs.cgi/*checkout*/ietf-uri/rev-2002/rfc2396bis.html#rfc.section.1.1.p.3>) 
to understand why this is correct.

> was the result of the wording that a MOVE is the "logical equivalent of" 
> a COPY followed by a DELETE -- definitional or explanatory wording was 
> seen as normative in that case by some implementors.  Philosophical, 
> definitional or modeling changes do have an effect on implementors 
> behavior.  What effect would you like that to be?

The intent is to better explain what a lock indeed *is*.

Could you elaborate in which way people could possibly misunderstand the 
new text?

Julian

---

From: Jason Crawford <[email-masked]>
Date: Wed, 7 Jul 2004 18:06:39 -0400

> servers frequently create new resources upon POST,
I don't understand how this is related.  As far as creation, typically to 
create a resource you do PUT or MKCOL.  And the resource appears at the 
URL you provide as an argument.   This is not the case for locks. 

> - a lock has a URI,
Are you referring to the lock-token?  It doesn't work the same way that 
URI's for typical resources work.   For typical resources, the URI is a 
URL.  This is not true for locks/locktokens.

> - a lock has state,
As do properties but we rarely refer to them as resources because that 
would cause confusion.  Instead we give them a different name, 
"properties" to avoid that confusion.    Of course, specifications that do 
properties more clearly as resources should feel free to also refer to 
them as resources.

BTW... I'm not saying a lock is a property.  I'm just providing a similar 
example of where we chose not to highlight the fact that something is a 
resource.

> - the state is observable indirectly through HTTP methods 
Again, not the same way as typical resources.  Only as a side effect of 
asking (PROPFIND) for the state of some OTHER resource.  That's weird.

And that's the only method locks and typical resources have in common. 

> and last but not least,
You can say that for just about anything in this world, but we don't. When 
we find reason to standardize what you just mentioned, we then begin to 
have a reason to call locks resources, but right now they act differently 
than what we typically think of as resources.  So although they (and just 
about anything else in this universe) can be called resources, it is not 
really helpful to do so... and because of the context, it's actually 
confusing.

> If you substitute "lock" by "lock resource" things sound much better.
It's less awkward as you say, but still a little.  It works better to just 
say "lock"
since adding "resource" detracts.

> *directly* though PROPFIND instead of indirectly through a specific
Well...  we don't do that in this spec though so it's premature to 
add verbiage claiming that they are resources.  Adding the verbiage
without the supporting behavior just adds confusion. 
Because you might want to eventually make them directly addressable 
via typical HTTP methods, we shouldn't say they aren't resources either.
Instead we should be silent.

> > For me it feels better not to define a lock at all beyond it's 
behavior
> that it *is* a resource. 
I agree.

> I just happen to think that things become much
;-)

---

From: Julian Reschke <[email-masked]>
Date: Thu, 08 Jul 2004 08:28:41 +0200

Jason Crawford wrote:

> I don't understand how this is related.  As far as creation, typically 
> to create a resource you do PUT or MKCOL.  And the resource appears at 
> the URL you provide as an argument.   This is not the case for locks.

That's only "typical" for WebDAV. Outside WebDAV, new resources are 
created as an effect of POST every second (and in this case, it's the 
server that assigns the URL). I'd actually call that the typical case, 
for the simply reason that it happens so often.

> URL.  This is not true for locks/locktokens.

What is a "typical" resource? And why is this relevant unless I say that 
a lock indeed is a "typical" resource?

> "properties" to avoid that confusion.    Of course, specifications that 
> do properties more clearly as resources should feel free to also refer 
> to them as resources.

As a matter of fact particular instances of WebDAV properties on a 
resource *are* resources on their own. We just don't have a common 
notation for their URLs. For instance we could have defined that the 
DAV:displayname property for a given WebDAV URL http://a/b has the 
following URL:

   http://a/b;displayname

and then we could have allowed DELETE/PUT/GET on it. Many say that this 
is what WebDAV should have done, because it would have avoided the 
current situation where property values can not be addressed by the 
common WebDAV methods.

> BTW... I'm not saying a lock is a property.  I'm just providing a 
> similar example of where we chose not to highlight the fact that 
> something is a resource.
> 

OK. Does "urn:ietf:rfc:2518" identify a resource? Does 
"mailto:[email-masked]"? None of them can be addressed using HTTP 
directly. They are still resources, just not HTTP resources.

> And that's the only method locks and typical resources have in common.

Again, unless you define what you understand with "typical" and how this 
is relevant here....

> You can say that for just about anything in this world, but we don't.   
>  When we find reason to standardize what you just mentioned, we then 
> begin to have a reason to call locks resources, but right now they act 
> differently than what we typically think of as resources.  So although 
> they (and just about anything else in this universe) can be called 
> resources, it is not really helpful to do so... and because of the 
> context, it's actually confusing.

I'd like to understand *why* you find that confusing? Because you 
usually only use the term "resource" when talking about HTTP resources?

> It's less awkward as you say, but still a little.  It works better to 
> just say "lock"

Well, that's what the spec *does*. The term "resource" is only used in 
the introduction.

> without the supporting behavior just adds confusion.

They technically *are* resources. If you're arguing with that statement, 
you should explain how this is incorrect according to RFC2396 (which is 
the relevant spec here).

Whether we should *say* that they are resources is a different question. 
We don't need to say it, but my feeling was that it helps understanding 
how they work.

> ..

Regards, Julian

---

From: Jason Crawford <[email-masked]>
Date: Thu, 8 Jul 2004 11:59:59 -0400

> for the simply reason that it happens so often.

We have different experience then.  For me PUT is only second to FTP.  And 
my web tools don't support authoring via POST. 

Besides.... We're working on or extending the WebDAV spec.  It doesn't 
make sense to treat our own spec(s) as exceptional.  We should be self 
consistant.   When we speak of resources, it has meant HTTP resources. 
This is not just coincidental.  The whole of 2518 is dedicated 
to defining these "resources".   To briefly use the term to refer to 
something that doesn't behave like the spec outlines doesn't make sense.

> a lock indeed is a "typical" resource?

An HTTP resource.

> current situation where property values can not be addressed by the

Right.  Properties are resources, but we don't call them resources.  That 
was my point.

> directly. They are still resources, just not HTTP resources.

That's right.   In the context of a spec dedicate to HTTP resources it's 
not useful to call these or LOCKS  resources.  It actually is confusing 
because resources usually refers to HTTP resources.

> Again, unless you define what you understand with "typical" and how this

HTTP Resources.    One's that support simple namespace operations like 
GET/PUT/DELETE  or GET/MKCOL/DELETE... and our new operations in the 
binding spec.

> usually only use the term "resource" when talking about HTTP resources?

Because throughout the spec resources refer to 
HTTP resources.  Now it is being suggested to use the term briefly
for something that doesn't behave like an HTTP resource at all.  It
will draw the wrong picture because all the important operational
behaviors that the spec defines for resources don't apply.

> We don't need to say it, but my feeling was that it helps understanding
Right.  The disagreement is not whether they are resources are not.  The
rfc you mention clearly allows them and just about anything else in the
world to be a resource. 

The disagreement is over whether we should mention that they are
resources.

Down the road we might want to openly call them resources if we go 
ahead and have the lock-token be a URL that responds to 
GET/DELETE/PROPSTAT methods, but right now calling these things 
resources despite the fact that they don't have the behaviors that
our spec spends so much time defining for resources would be
confusing and not really helpful.

---

From: Julian Reschke <[email-masked]>
Date: Thu, 08 Jul 2004 19:04:31 +0200

Jason Crawford wrote:

> We have different experience then.  For me PUT is only second to FTP. 
>  And my web tools don't support authoring via POST.

I'm not talking about authoring. I'm talking about HTML forms that allow 
user input and that perform a POST request that in many cases results in 
a new HTTP resource.

> consistant.   When we speak of resources, it has meant HTTP resources.

I disagree here. When we usually mean "HTTP resource" when we say 
"resource" this is the case because it's clear from the context. There 
are other cases, such as in

<http://greenbytes.de/tech/webdav/rfc3744.html#rfc.section.4.1>

Also, as a matter of fact, I *was* careful to say:

"Having a URI (the lock token URI) on it's own, a lock is a resource in 
the sense defined by [RFC2396]. In general, this resource does not have 
a HTTP URL, and thus can not be directly manipulated using HTTP methods."

So I claim there's no risk whatsoever of people misunderstanding this as 
meaning "HTTP resource".

> something that doesn't behave like the spec outlines doesn't make sense.

No, no. RFC2518 doesn't define resources at all. RFC2518 speaks about 
*HTTP* resources (which are defined in RFC2616), and what it means for a 
HTTP resource to be "WebDAV compliant".

>  > a lock indeed is a "typical" resource?

OK, and so why is this relevant when I explicitly say that generally 
it's not a HTTP resource?

> because resources usually refers to HTTP resources.

I'd agree if there was any risk of a misunderstanding. Looking at the 
text as proposed, there isn't. It says (a) "in the sense of RFC2396" and 
"generally not an HTTP URL".

> behaviors that the spec defines for resources don't apply.

See above.

> rfc you mention clearly allows them and just about anything else in the

Thanks.

> confusing and not really helpful.

A server may implement locks as HTTP resources, we don't need to change 
anything in RFC2518 to allow that.

Anyway, it seems that we just have different opinions how easily a 
reader can be confused by the statement in question.

Julian

---

From: Jason Crawford <[email-masked]>
Date: Fri, 9 Jul 2004 00:21:58 -0400

I approve of Geoff's suggestions which Julian says he's already added.