WEBDAV Working Group Y. Goland, Microsoft INTERNET-DRAFT E. J. Whitehead, Jr. U.C. Irvine October 25, 1996 Expires April, 1997 Author's draft: v0.1 Extensions for Distributed Authoring and Versioning on the World Wide Web Status of this Memo This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or made obsolete by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress". To learn the current status of any Internet-Draft, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or ftp.isi.edu (US West Coast). Distribution of this document is unlimited. Please send comments to the WWW Distributed Authoring and Versioning (WEBDAV) working group at , which may be joined by sending a message with subject "subscribe" to . Discussions of the WEBDAV working group are archived at . The HTTP working group at also discusses the HTTP protocol. Discussions of the HTTP working group are archived at . General discussions about HTTP and the applications which use HTTP should take place on the mailing list. Abstract TBD 1. Introduction 1.1 Purpose This specification defines extensions to the HTTP/1.1 [HTTP11] protocol, the URL [URL] specification, and defines subtypes of the Application content type [RFC1521]. Together, these provide a means for augmenting existing facilities for remote authoring with abilities for locking, versioning, relationships, attributes, and listing and maniupulation of the URL name space. Capbilities detailed in this specification meet the requirements for Distributed Authoring and Versioning, stated in [ref DA Reqt's][ref Vers. Reqt's]. 1.2 Terminology Unless otherwise noted below, the use of terminology in this document is consistent with the definitions of terms given in [HTTP11]. check in A Check In is a declaration that the client no longer intends to edit a representation(s). check out A Check Out is a declaration by a client that they intend to edit a representation(s). command comments Command Comments associate either a string or a URI with an HTTP message. destroy To destroy a URI is to request that the URI and the associated resource be permanently removed from storage. This differs from delete in that some versioning systems handle delete as a request to no longer make the specified URI updateable. history The history of a URI is a list of all the versions of the URI along with related information. merge A merge is the process whereby a resource represented by one URI is combined with a resource represented by a second URI. Merges can occur at the client or the server. no-modify lock A no-modify lock prevents a locked resource from being altered until all no-modify locks are released. notify request A notify request instructs the recipient to send update information regarding the progress of a request. read lock A read lock prevents anyone who does not posses a read lock on a resource from reading that resource. server diff A server diff is a mechanism whereby the server compares two or more representations, and sends the client a message containing a summary of the differences between the entities. write lock A write lock prevents anyone who does not possess a write lock on a resource from altering that resource. 1.3 Notational Conventions and Generic Grammar This specification uses the Augmented BNF and Basic Rules as defined in Section 2 of [HTTP11]. 2. Attributes It is often necessary to record meta data about a resource. The natural place to store such meta data is in HTTP headers however this presents a problem. HTTP headers, as defined in [HTTP11], are used either for content description or communication. While communication headers can be retrieved with the Option method, content description headers can not. In addition neither of these headers were designed for remote setting and on-demand retrieval. What is needed is a third type of header, a header which provides information about the resource's nature, not its content or transmission state. This type of header will be referred to as an attribute header. One could add attribute headers to an HTTP message and declare that they must be recorded and provided when a GET is executed, but it is expected that resources will find themselves with a large number of attributes, each of which may consist of a large amount of data. Understanding that the headers can not be sent with every message it becomes necessary to provide a means to discover what headers a resource has, to add new headers, delete current headers, find out the value of a header, and so on. In short, headers require the same maintenance as a resource. Rather then inventing a raft of new methods, the current methods will be bent to our purposes. A specification is provided below for describing a header in the context of the URI of the headerís associated resource. So, were a header named "FileName" to exist and be associated with the resource http://foo/bar, it would be uniquely referred to as http://foo/bar. Headers may also have a hierarchy so the URI http://foo/bar would refer to the header "FirstAuthor" which is a child of the header "Author." The "_" is used to denote hierarchy because it is legal to use within a token. Note that the name space for headers is actually flat and the use of "_" to denote hierarchy is optional. It is only meant to make it easier to group headers. The "<...>" enclosure was chosen because it will not cause a conflict with any currently existing URIs. 2.1 Attribute Syntax To support requests for attributes the definition of a URI must be altered as follows: URI = ( absoluteURI | relativeURI ) ["<" Attribute ">"] ["#" fragment] Attribute = field-name ; See section 4.2 of [HTTP11] Values for attribute headers are specified as the entity-body of a request. This allows for content negotiation for attribute headers. Thus attributes can now be used in any context where a normal URI would be used. When a resource is copied, moved, or otherwise manipulated, its attributes are equally effected. However servers make the final determination regarding the state of any attribute header and may choose to not copy, move, etc. any subset of headers when it performs the requested action on a resource. In order to prevent name space collisions both headers and header prefixes should be registered with a central authority. A header prefix is any legal token that may only be used when it is prefixed to another token. Thus Netscape could register the prefix NS and thus be the only organization allowed to create headers which begin with NS. 2.2 Standard Attributes The following attributes have their name and semantics defined by this specification. AttributeDirectory The attribute "AttributeDirectory" returns a list of all attribute headers on a resource. To retrieve a list of attribute headers associated with the URL http:\\foo\bar one would send a GET request with a request-URI of \bar, where Host would equal foo. The same logic applies to PUT, which would be used to set an attribute's value. Link This attribute header contains information about resources that are associated with this resource. A SiteMap representation SHOULD be available. [TBD: Review the SiteMap format and figure out tag formats to define source links.] LockInformation See Lock Discovery, Section 3.2. NotifyRequest See Notify Request, Section 6. Source The exact contents of the resource as stored, without any processing by the server (e.g. without processing of server-side includes). 3. Lock/Unlock Locks come in three types, write, read, and no-modify. Logically a write lock and a read lock can co-exist on a single resource. This means that one set of clients can alter the resource and another set are the only ones allowed to read it. This may seem silly but is actually used in Orange book compliant environments. A write lock and a no-modify lock can not be used together for obvious reasons. A read lock and a no-modify lock can be used together. Locks are assigned to a subset of the representations available for a resource. If the lock only applies to a single representation then the lock may be further restricted to only a particular range of the representation. A content-range header is used for this purpose. The range may go off the "end" of the representation. Locks that exceed the end of a representation control the ability to append to the representation. Locks may be taken out either in exclusive or shared mode. In shared mode anyone with proper access may take out a lock. In exclusive mode only the user(s) who originally took out the lock may alter the lock. However a new user can be added to an exclusive lock if the addition is performed by one of the lockís current owners. If an entire resource is write locked and a lock owner deletes the resource then the write lock remains. So long as the write lock remains the URI can not be reused. In order to provide for maximum flexibility and ease of administration, lock tokens will be used to track locks. When a lock is taken out a lock token will be returned. A single lock token can represent any number of locks. In future lock requests the same token may have new locks added or old locks removed from it. Lock tokens are not required to transferable between lock administration resources. Locks also have time outs associated with them. If no time out value is associated with a lock then the lock will never time out. Otherwise the lock will expire if a number of seconds equal to the time out value passes without the resource being accessed by a lock owner. The time out value may be altered, without effecting the rest of the lock, by submitting a lock request with no Lock Entries. Finally, locks may be taken out for multiple clients in a single request. The Lock_Owners field allows for tokens to be used to identify multiple clients who are considered owners of the lock. A server SHOULD only allow a lock token to be used in a request if the requestor is an owner of that lock token. [TBD - We need an error message indicating that the server will not accept certain lock combinations or accept overlapping locks. We also need an error stating that an unlock couldn't be executed because it did not exactly match with a lock.] Locks will be implemented using POST. The request-URI will be the lock administration resource. The entity-body will be of type application/lock. 3.1 Definition of Content Type application/lock LOCK_BODY = Token_Status Time_Out Lock_Owners Lock_Request Token_Status = (Token_Field | "No Token") Token_Field = "Lock Token" ":" LockToken Time_Out = "Time Out" ":" (*DIGIT | "Never") Lock_Request = ("Unlock" | Lock_Entries) Lock_Entries = "Lock Entries" ":" #(Lock_URI LockType (("Exclusive" | "Shared") | "Unlock") Headers) Lock_Owners = "[" *Lock_Owner "]" Lock_Owner = token; This is some identifier used to list who owns the lock. Lock_URI = "URI" URI LockToken = Any OCTET but LWS LockType = ("Write" | "Read" | "No-Modify" | "Write" "Read" | "Read" "No-Modify") Headers = #message-header ; As defined in 4.2 of [1] The Headers allows the lock to specify a subset of representations of a resource. Examples of type application/lock include: Time Out: Never Lock Entries: URI http://www.microsoft.com/staff/yarong.html Write Exclusive [Yaron Goland ] This specifies a request for an exclusive write lock on http://www.microsoft.com/staff/yarong.html, held by Yarong Goland. This lock will never automatically time out. 3.2 Processing a Lock Request [TBD- Do we want to allow for multiple independent new lock declarations? What about multiple, independent, lock token extensions?] A lock request without a LockToken is a new lock request. All the requests in a lock must be granted or a 503 Service Unavailable must be returned. If the lock is granted then the return body should be formated as: RETURN_LOCK_BODY = LockToken A lock request with a LockToken is a request to extend the lock represented by the lock token. The same rules as specified in the previous paragraph apply. A lock request with Unlock specified for Lock_Request means that all locks associated with this token should be removed. A lock_entries with Unlock specified means this particular lock should be removed from the token. The BNF allows for Unlocks to be specified without specifying a lock token. This is not an error. This syntax allows authorized users to override locks they do not have the token for. Lock requests MUST be processed as an atomic action or the request must be refused. When multiple resources are locked under a single token an operation will only be allowed on any of the resources if the remaining locks in the token can be guaranteed to exist for the life of the operation. 3.3 Lock Discovery When a lock is taken out the system SHOULD record who owns the lock. Ownership information can be taken from the From header, from identification provided by authentication, or from the LockOwners field. This information SHOULD be available through the attribute header "LockInformation" which has the mime type application/LockInformation. The format of the mime entity is: LOCKINFORMATION = #(Token_Field Time_Out Lock_Owners Lock_Entries) [Contact_Field] Contact_Field = "Contact" ":" token The Contact_Field is used to provide contact information in case there is a problem with a lock. An example of a LockInformation attribute is: LockInformation: Token: a5dzq Time Out: Never [Yaron Goland The exclusive write lock on http://www.microsoft.com/staff/yarong.html is held by Yaron Goland, has token value a5dqz, and will never time out. If there is a problem with a lock, the Lock Administrator should be contacted. 4. Name Space Manipulation 4.1 Copy A copy performs a byte-for-byte duplication of a resource, making it available at both the original and new location in the URI namespace. There is no guarantee that the result of a GET on the URL of the resource copy will be identical to a GET on the original resource. For example, copying a script to a new location will often remove it from its intended environment, and cause it to either not work, or produce erroneous output. A copy MUST be atomic. A copy is performed by sending a POST method to a resource which can perform the copy. The entity body for the POST method is of content type application/copy, defined in Section 4.1.1. Before any copied resources are made available through the destination URIs, all copied resources must either be available or return a 503 Service Unavailable response code when referenced. If the No Overwrite value is specified then that entry in the copy should not occur if the destination URI already exists. If a resource is not copied because a "No Overwrite" flag was used and the resource exists then the request still succeeded. 4.1.1 Definition of Content Type application/copy BODY = 1*(Source_URI Headers Destination_URI Headers Type) Source_URI = URI Destination_URI = URI Type = "Overwrite" | "No Overwrite" Headers = #message-header ; As defined in 4.2 of [HTTP11] Examples of content type application/copy include: http://www.ics.uci.edu/~ejw/hidden/draft.html Accept-Language: fr, en;q=0.7 http://www.ics.uci.edu/~ejw/final_report.html Overwrite This example specifies a copy of the French language version of http://www.ics.uci.edu/~ejw/hidden/draft.html if available, otherwise any English version, into http://www.ics.uci.edu/~ejw/final_report.html, overwriting the contents of final_report.html if they exist. http://www.ics.uci.edu/pub/ietf/http/index.html Range: bytes=0-500 http://www.ics.uci.edu/~ejw/working.html Range: bytes=0-500 Overwrite This example specifies a copy of the first 500 bytes of /pub/ietf/index.html into /~ejw/working.html, overwriting the first 500 bytes of working.html if they exist. 4.2 Move A move causes the source resource to be accessible at the destination URI. A move MUST be atomic. A move is performed by sending a POST method to a resource which can perform the move. The entity body of the POST method is of content type application/move, defined exactly the same as content type application/copy, (Section 4.1.1). In this case atomicity requires that before the resources are made available at the new location they must no longer be available at the old location. The rest of the atomicity requirements are the same as for copy. 4.3 Redirect Redirect is used to instruct a server to return one of the 3xx series codes. A Redirect request defines both the error code and the semantics of the entity-body. To perform a redirect a POST should be performed with the content-type equal to application/redirect. The body of the mime type is defined as TBD. [The mime type will contain the URI being redirected, the code to be used, and the semantics of the entity-body to be returned.] 5. Relationships Section removed due to lack of consensus between authors. 6. Notify Request Header (proposal, for comment) Whenever the NotifyRequest header is included in an HTTP request, the server should send update information on the progress of a request. Notify_Request = "NotifyRequest" ":" It is common, in asynchronous environments, to provide a mechanism to describe the status of a request as it is processed. As we provide for more and more powerful methods, which have longer and longer processing times, might we not want a similar feature for HTTP? 7. URI Groups Any URI, which has a representation of content type application/uri_group, is defined to be a URI group. Content type application/uri_group will use the SiteMap format. Members are listed, added, or removed from the group by performing actions on application/uri_group. The advantage of SiteMaps in this context is that they are designed to point to other SiteMaps. In this way a hierarchy can be built and when an operation is performed it will act recursively down the tree. 8. Versioning (TBD) Acknowledgements Roy Fielding, Richard Taylor. Others, TBD. References [HTTP11] R. T. Fielding, J. Gettys, J. C. Mogul, H. F. Nielsen, and T. Berners-Lee. "Hypertext Transfer Protocol -- HTTP/1.1" Internet-Draft draft-ietf-http-v11-spec-07.txt, expires February 12, 1997. [RFC1521] N. Borenstein, N. Freed. "MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies." RFC 1521, Bellcore, Innsoft, September, 1993. [URL] T. Berners-Lee, L. Masinter, M. McCahill. "Uniform Resource Locators (URL)." RFC 1738, CERN, Xerox PARC, University of Minnesota, December, 1994. [2] R. Khare, "HTTP/1.2 EXTENSION PROTOCOL (PEP)" Internet-Draft draft-ietf-http-pep-00.txt, expires August 19, 1996