Author: al
Date: Tue Jun 4 08:33:44 2013
New Revision: 1489334
URL: http://svn.apache.org/r1489334
Log:
Create whitepapers repo to hold spec/ and whitepapers/
Added:
incubator/wave/whitepapers/
incubator/wave/whitepapers/Makefile
incubator/wave/whitepapers/access-control/
incubator/wave/whitepapers/access-control/Makefile
incubator/wave/whitepapers/access-control/access-control.html (with props)
incubator/wave/whitepapers/access-control/access-control.rst
incubator/wave/whitepapers/access-control/img/
incubator/wave/whitepapers/access-control/img/account-canonical.png (with
props)
incubator/wave/whitepapers/access-control/img/address-address.png (with
props)
incubator/wave/whitepapers/access-control/img/member-group-group.png
(with props)
incubator/wave/whitepapers/access-control/img/member-group-read-group.png
(with props)
incubator/wave/whitepapers/access-control/img/member-group.png (with
props)
incubator/wave/whitepapers/access-control/img/member-read-group.png (with
props)
incubator/wave/whitepapers/access-control/img/spelly.png (with props)
incubator/wave/whitepapers/attachments/
incubator/wave/whitepapers/attachments/Makefile
incubator/wave/whitepapers/attachments/attachments.html (with props)
incubator/wave/whitepapers/attachments/attachments.rst
incubator/wave/whitepapers/attachments/img/
incubator/wave/whitepapers/attachments/img/attachment-server-architecture.png
(with props)
incubator/wave/whitepapers/client-server-protocol/
incubator/wave/whitepapers/client-server-protocol/Makefile
incubator/wave/whitepapers/client-server-protocol/client-server-protocol.html
(with props)
incubator/wave/whitepapers/client-server-protocol/client-server-protocol.rst
incubator/wave/whitepapers/conversation/
incubator/wave/whitepapers/conversation/Makefile
incubator/wave/whitepapers/conversation/convspec.html
incubator/wave/whitepapers/conversation/convspec.rst
incubator/wave/whitepapers/conversation/refs/
incubator/wave/whitepapers/conversation/refs/RFC2119.xml (with props)
incubator/wave/whitepapers/federation/
incubator/wave/whitepapers/federation/Makefile
incubator/wave/whitepapers/federation/refs/
incubator/wave/whitepapers/federation/refs/OT.xml (with props)
incubator/wave/whitepapers/federation/refs/RFC2119.xml (with props)
incubator/wave/whitepapers/federation/refs/RFC3920.xml (with props)
incubator/wave/whitepapers/federation/refs/VERFED.xml (with props)
incubator/wave/whitepapers/federation/refs/XEP0060.xml (with props)
incubator/wave/whitepapers/federation/waveschema.rnc
incubator/wave/whitepapers/federation/wavespec.html
incubator/wave/whitepapers/federation/wavespec.rst
incubator/wave/whitepapers/google-wave-architecture/
incubator/wave/whitepapers/google-wave-architecture/Makefile
incubator/wave/whitepapers/google-wave-architecture/google-wave-architecture.html
(with props)
incubator/wave/whitepapers/google-wave-architecture/google-wave-architecture.rst
incubator/wave/whitepapers/google-wave-architecture/img/
incubator/wave/whitepapers/google-wave-architecture/img/acmewave-federati.png
(with props)
incubator/wave/whitepapers/google-wave-architecture/img/gateway-and-proxy.png
(with props)
incubator/wave/whitepapers/google-wave-architecture/img/love.png (with
props)
incubator/wave/whitepapers/operational-transform/
incubator/wave/whitepapers/operational-transform/Makefile
incubator/wave/whitepapers/operational-transform/img/
incubator/wave/whitepapers/operational-transform/img/annotations.png
(with props)
incubator/wave/whitepapers/operational-transform/img/composition.png
(with props)
incubator/wave/whitepapers/operational-transform/img/david_ot3.png (with
props)
incubator/wave/whitepapers/operational-transform/img/doc-items.png (with
props)
incubator/wave/whitepapers/operational-transform/img/ot-paths.png (with
props)
incubator/wave/whitepapers/operational-transform/img/transformation.png
(with props)
incubator/wave/whitepapers/operational-transform/operational-transform.html
(with props)
incubator/wave/whitepapers/operational-transform/operational-transform.rst
incubator/wave/whitepapers/rst2rfc.py
incubator/wave/whitepapers/rules.mk
incubator/wave/whitepapers/waveid/
incubator/wave/whitepapers/waveid/Makefile
incubator/wave/whitepapers/waveid/refs/
incubator/wave/whitepapers/waveid/refs/RFC2119.xml (with props)
incubator/wave/whitepapers/waveid/refs/RFC2246.xml (with props)
incubator/wave/whitepapers/waveid/refs/RFC2249.xml (with props)
incubator/wave/whitepapers/waveid/refs/RFC3490.xml (with props)
incubator/wave/whitepapers/waveid/refs/RFC3986.xml (with props)
incubator/wave/whitepapers/waveid/refs/RFC3987.xml (with props)
incubator/wave/whitepapers/waveid/refs/RFC5234.xml (with props)
incubator/wave/whitepapers/waveid/waveidspec.html
incubator/wave/whitepapers/waveid/waveidspec.rst
Added: incubator/wave/whitepapers/Makefile
URL:
http://svn.apache.org/viewvc/incubator/wave/whitepapers/Makefile?rev=1489334&view=auto
==============================================================================
--- incubator/wave/whitepapers/Makefile (added)
+++ incubator/wave/whitepapers/Makefile Tue Jun 4 08:33:44 2013
@@ -0,0 +1,19 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+WHITEPAPERS = access-control attachments client-server-protocol
google-wave-architecture operational-transform
+
+default:
+ for subdir in $(WHITEPAPERS); do \
+ (cd $$subdir && $(MAKE)) \
+ done
+
Added: incubator/wave/whitepapers/access-control/Makefile
URL:
http://svn.apache.org/viewvc/incubator/wave/whitepapers/access-control/Makefile?rev=1489334&view=auto
==============================================================================
--- incubator/wave/whitepapers/access-control/Makefile (added)
+++ incubator/wave/whitepapers/access-control/Makefile Tue Jun 4 08:33:44 2013
@@ -0,0 +1,3 @@
+include ../rules.mk
+
+default: access-control.html
Added: incubator/wave/whitepapers/access-control/access-control.html
URL:
http://svn.apache.org/viewvc/incubator/wave/whitepapers/access-control/access-control.html?rev=1489334&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/wave/whitepapers/access-control/access-control.html
------------------------------------------------------------------------------
svn:mime-type = application/xml
Added: incubator/wave/whitepapers/access-control/access-control.rst
URL:
http://svn.apache.org/viewvc/incubator/wave/whitepapers/access-control/access-control.rst?rev=1489334&view=auto
==============================================================================
--- incubator/wave/whitepapers/access-control/access-control.rst (added)
+++ incubator/wave/whitepapers/access-control/access-control.rst Tue Jun 4
08:33:44 2013
@@ -0,0 +1,222 @@
+######################################
+Access Control in Google Wave
+######################################
+
+:Authors:
+ Jon Tirsen
+
+:Version: 1.0 - May 2009
+
+Google Wave's primary means of access control is the list of addresses that
+participate on a wavelet and what access accounts has to these addresses. This
+white paper outlines how the wave platform stores, exchanges and enforces
+access control.
+
+This whitepaper is part of a series. All of the whitepapers
+can be found on `Google Wave Federation Protocol site`_.
+
+.. _Google Wave Federation Protocol site:
http://www.waveprotocol.org/whitepapers
+
+Executive summary
+#################
+
+Wave access control is defined as:
+
+* which individual or robot has access to a specific account,
+* what access an account has to an address,
+* and finally what access an address has to a wavelet (see `Google Wave Data
+ Model and Client-Server Protocol`_ for more information on the wavelets).
+
+.. _Google Wave Data Model and Client-Server Protocol:
http://www.waveprotocol.org/whitepapers/internal-client-server-protocol
+
+Access from individuals to accounts and accounts to addresses is defined and
+enforced inside each wave provider and not specified in the standard. Address
+access is modeled as a graph where each edge in the graph grants access from
+one address to another address. These edges are stored in waves and are
+authorized by the wave provider that controls the domain of the addresses. The
+access edges can be exchanged between wave providers through the normal wave
+federation protocols.
+
+Typically an account has access to a canonical address which is the entry point
+for an account into this graph, although this is wave provider specific.
+Operations are authorized at the source of each wave provider. If authorization
+spans multiple wave providers the operation needs to be sent and verified along
+the path of each of the involved wave providers. Different levels of access to
+a wavelet is still to be defined.
+
+Accounts and addresses
+======================
+
+Account
+ An account belongs to an end user or a robot. Exactly how accounts work is
+ wave provider specific. For example, Google uses Google Accounts to store and
+ authenticate accounts, so a Google Wave account is shared with other Google
+ properties.
+
+Address
+ Most of the system does not deal directly with accounts but rather with
+ addresses. An address is a string formatted as an email address (RFC 2822).
+ Addresses, rather than accounts, participate in wavelets.
+
+Canonical address
+ Each account has a canonical address which is the address the user acts as
+ normally. Most per-user metadata is stored with the canonical address as a
+ key. The canonical address cannot generally be changed, but an account can
+ participate on a single wavelet as multiple addresses.
+
+Authentication
+==============
+
+Each wave provider chooses how they authenticate their users. In Google Wave we
+use a simple username and password scheme for individuals. Robots are contacted
+by the Google Wave provider through a well-defined URL and are therefore
+authenticated that way.
+
+Address access as a graph
+=========================
+
+Address access can be seen as a directed graph of address to address edges
+where each edge is restricted by access settings.
+
+.. image:: img/address-address.png
+
+The entry point into the graph for a user or a robot is their canonical
address.
+
+.. image:: img/account-canonical.png
+
+There are multiple types of access which indicate what address A can do as
address B.
+
+* Indexed to (INDEX) - wavelets addressed to address B will be written into the
+ index of the account associated with address A (transitively).
+* Add (ADD) - address A can add address B to wavelets.
+* Add myself as (ADD_ME) - address A can add address A to wavelets as address
B.
+* Read (READ) - address A can read wavelets addressed to address B.
+* Write (WRITE) - address A can do anything as address B. This could also be
+ called "act as".
+* Grant (GRANT) - address A can grant additional access
+ edges to address B.
+
+Storing and exchanging access edges
+===================================
+
+Wave representation of an access edge
+ Access edges are stored in data documents in wavelets as follows:
+
+::
+
+ <grant from="[email protected]" to="[email protected]"
until="2009-06-14T13:31Z">
+ <access>INDEX</access>
+ <access>READ</access>
+ </grant>
+
+Authorized access edge
+ An authorized access edge is an access edge stored in a wave that can be
+ attributed to an author that has a Grant access edge to the to address she is
+ granting additional access too. This attribution should be enforced and
+ verified by the wave provider. For example, the Google wave provider uses a
+ namespace for all access edges. The namespace policy for that namespace will
+ not allow edits that are not authorized.
+
+Access wave
+ Each account has an access wave identified by its canonical address. This
+ contains the entire access sub-graph that is reachable from the canonical
+ address. The wave provider of the account maintains this access wave by
+ copying all the relevant and authorized access edges it encounters while
+ indexing its own and its federated wave providers' waves. This means that
+ access edges can be stored and distributed anywhere in the system as long as
+ they are authorized as above. The storage and distribution mechanism of
+ Google Wave itself is used to store and distribute this information.
+
+Time to live
+ When a wave provider issues an access edge to federated servers they are
+ issued with a limited time period. They have to be refreshed within that time
+ period or they are no longer valid. The time period should be chosen to
+ minimize chattiness of the protocol and still allow for timely revocation.
+ This is typically used for READ authorization when opening of a wavelet is
+ not validated at the owning wave provider.
+
+Authorizing an operation
+========================
+
+An operation always contains the path of authorization from the canonical
+address to the address the account wants to perform an operation as excluding
+any initial WRITE edges. Using the information available in the access wave
+the client builds the path and inserts it into the operation that it sends to
+its wave provider. After it has optimistically applied the operation to the
+wave in the client it sends it to its wave provider who then signs and forwards
+the operation to the next wave provider in the path. Every wave provider on the
+path will validate and sign the operation before it is finally forwarded and
+applied at the wave provider that owns the wavelet. This final wave provider is
+responsible for verifying all the signatures.
+
+If an authorization fails, the client has typically already optimistically
+applied the operation to the wave so will either need to reverse those
+operations or indicate an error to the user. In a well-behaved system this
+should only occur if an access edge has been removed or changed and this change
+has yet to be forwarded to the clients wave provider. In this case the client
+would access edges that are no longer valid.
+
+Groups
+######
+
+Groups are implemented on top of this generic access framework. Each group has
+an address and members. Group membership is expressed as the following edge for
+each member of the group:
+
+.. image:: img/member-group.png
+
+As you can see an important detail of groups in wave is that being a member of
+a group does not allow you to directly write into a wave which that group is
+addressed to. Instead it lets you add yourself as a direct participant to that
+wave.
+
+A group can be a member of another group which looks like this:
+
+.. image:: img/member-group-group.png
+
+This means that wavelets addressed to both Group 1 and Group 2 will be written
+into the member's index and the member can read and "write" (add self as a
+participant) to all these wavelets.
+
+Read-only groups mean that the "add myself" access is lacking:
+
+.. image:: img/member-read-group.png
+
+An address can be a read-write member of a nested group even though it's a
+read-only member of an outer group:
+
+.. image:: img/member-group-read-group.png
+
+This means the member can become a participant of wavelets addressed to Group 1
+but not to wavelets addressed to Group 2.
+
+Delegation
+==========
+
+Delegation allows an account to perform operations with another address as the
+author. Google Wave currently uses this for two cases:
+
+* An account that is a write-member of a group can perform an AddParticipant
+ operation to add an address belonging to that account to a wavelet.
+* Google Wave's spelling ("Spelly"), linking ("Linky"), and other
infrastructure
+ services act on behalf of any address in a wavelet with those services
+ enabled.
+
+This last case is represented as the following edge:
+
+.. image:: img/spelly.png
+
+This provides Google Wave infrastructure services full access to act as a user,
+while being authenticated as a service account.
+
+Per-wavelet access control
+==========================
+
+Google Wave will eventually support some level of access control on a wavelets
+but requirements and implementation plans have yet to be determined. For
+example:
+
+* A "commenter" role whereby a user can only create new blips and edit their
own blips.
+* A "confidential" mode (on the whole wavelet) or role (on a participant) where
+ participants can't add new participants.
+
Added: incubator/wave/whitepapers/access-control/img/account-canonical.png
URL:
http://svn.apache.org/viewvc/incubator/wave/whitepapers/access-control/img/account-canonical.png?rev=1489334&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/wave/whitepapers/access-control/img/account-canonical.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: incubator/wave/whitepapers/access-control/img/address-address.png
URL:
http://svn.apache.org/viewvc/incubator/wave/whitepapers/access-control/img/address-address.png?rev=1489334&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/wave/whitepapers/access-control/img/address-address.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: incubator/wave/whitepapers/access-control/img/member-group-group.png
URL:
http://svn.apache.org/viewvc/incubator/wave/whitepapers/access-control/img/member-group-group.png?rev=1489334&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/wave/whitepapers/access-control/img/member-group-group.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: incubator/wave/whitepapers/access-control/img/member-group-read-group.png
URL:
http://svn.apache.org/viewvc/incubator/wave/whitepapers/access-control/img/member-group-read-group.png?rev=1489334&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
incubator/wave/whitepapers/access-control/img/member-group-read-group.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: incubator/wave/whitepapers/access-control/img/member-group.png
URL:
http://svn.apache.org/viewvc/incubator/wave/whitepapers/access-control/img/member-group.png?rev=1489334&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/wave/whitepapers/access-control/img/member-group.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: incubator/wave/whitepapers/access-control/img/member-read-group.png
URL:
http://svn.apache.org/viewvc/incubator/wave/whitepapers/access-control/img/member-read-group.png?rev=1489334&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/wave/whitepapers/access-control/img/member-read-group.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: incubator/wave/whitepapers/access-control/img/spelly.png
URL:
http://svn.apache.org/viewvc/incubator/wave/whitepapers/access-control/img/spelly.png?rev=1489334&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/wave/whitepapers/access-control/img/spelly.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: incubator/wave/whitepapers/attachments/Makefile
URL:
http://svn.apache.org/viewvc/incubator/wave/whitepapers/attachments/Makefile?rev=1489334&view=auto
==============================================================================
--- incubator/wave/whitepapers/attachments/Makefile (added)
+++ incubator/wave/whitepapers/attachments/Makefile Tue Jun 4 08:33:44 2013
@@ -0,0 +1,3 @@
+include ../rules.mk
+
+default: attachments.html
Added: incubator/wave/whitepapers/attachments/attachments.html
URL:
http://svn.apache.org/viewvc/incubator/wave/whitepapers/attachments/attachments.html?rev=1489334&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/wave/whitepapers/attachments/attachments.html
------------------------------------------------------------------------------
svn:mime-type = application/xml
Added: incubator/wave/whitepapers/attachments/attachments.rst
URL:
http://svn.apache.org/viewvc/incubator/wave/whitepapers/attachments/attachments.rst?rev=1489334&view=auto
==============================================================================
--- incubator/wave/whitepapers/attachments/attachments.rst (added)
+++ incubator/wave/whitepapers/attachments/attachments.rst Tue Jun 4 08:33:44
2013
@@ -0,0 +1,316 @@
+#######################
+Google Wave Attachments
+#######################
+
+:Authors:
+ Michael Lancaster
+
+:Version: 1.0 - May 2009
+
+Wave messages may contain embedded binary attachments, such as images, PDF
+documents and ZIP archives. Because these binary files are qualitatively and
+quantitatively different to other wave content (rich text), they are handled as
+a somewhat special case within Google Wave. This document gives an overview on
+how attachments are represented within Google Wave, and how the servers
+interoperate to handle attachment uploading and serving.
+
+This whitepaper is part of a series. All of the whitepapers
+can be found on `Google Wave Federation Protocol site`_.
+
+.. _Google Wave Federation Protocol site:
http://www.waveprotocol.org/whitepapers
+
+High level summary
+##################
+
+Attachments are represented within a wave by an XML document, allowing changes
+(in upload progress, for instance) to be propagated to all users on the wave.
+Each attachment has a corresponding thumbnail image. For image attachments,
+this thumbnail is actually a small version of the image itself. In order to
+reduce latency for image attachments, HTML5 or Gears enabled clients may
+generate and upload a thumbnail before the image itself. For most other
+attachment types, the thumbnail is a generic representation of the attachment
+type (base on MIME type). Attachments are uploaded by the wave client using
+HTTP POST, and download of both attachments and their thumbnails is done using
+HTTP GET.
+
+Architecture
+############
+
+Attachment management is handled by a dedicated attachment server. This server
+is responsible for handling create, upload and download requests, generating
+thumbnails, reprocessing images, malware scanning, as well as for
+communications with the attachment store.
+
+The attachment server acts as an HTTP server (for handling attachment
+operations from the client), an RPC server (for handling attachment operations
+from internal agents, such as the mail gateway), and an RPC client for
+propagating attachment metadata to the wave server (see Google Wave Federation
+Architecture for details on the overall Google Wave architecture).
+
+.. image:: img/attachment-server-architecture.png
+
+Schema
+######
+
+Each attachment has a globally unique ID string, composed of the wave service
+provider domain, and a string that is unique for that provider. An example
+attachment ID for the wave sandbox wave provider would be
+"wavesandbox.com/3eb1c8ba-172b-4b1a-ae5b-d3140ed85c42". Each attachment is
+represented by a row in a replicated Bigtable (a Google proprietary scalable
+distributed database). The attachment metadata is represented by a protocol
+buffer stored in a column on that row. This protocol buffer contains such
+fields as the attachment size, upload progress, filename of the attachment, as
+well as a list of all wavelets that reference this attachment. The binary data
+for the thumbnail and attachment are each stored in separate columns on the
+same row.
+
+Thus an attachment row in the Bigtable looks like:
+
+AttachmentMetadata
+ contains the metadata protocol buffer,
+ThumbnailData
+ used to store the thumbnail BLOB (binary large object),
+AttachmentData
+ used to store the attachment BLOB, for small attachments
+
+Large attachments are stored in a separate Bigtable for better storage
+efficiency.
+
+For performance, and simplicity of design, a subset of the attachment metadata
+is also copied to any wavelets which reference the attachment. Storing this
+metadata in the wavelet means that we don't have to do anything special at wave
+load time to ensure that the client has a copy of the attachment metadata.
+Whenever the attachment server makes a modification to the attachment metadata,
+it pushes out the change to all relevant wavelets (via RPC to the wave
+server(s)).
+
+This copy of the metadata is represented by an XML sub-document on a data
+document within the wavelet. The ID of the Data Document is based on the
+attachment ID such that there is exactly one attachment data document for each
+attachment on a given wavelet.
+
+The attachment metadata XML sub-document is defined by the following RNC (Relax
+NG) schema::
+
+ element attachment {
+ attribute attachmentId { text },
+ attribute uploadProgress { xsd:integer },
+ attribute attachmentSize { xsd:integer },
+ attribute malware{ 0, 1 },
+ attribute stalled { 0, 1 }? // default = 0
+ attribute filename { text },
+ attribute mimeType { text },
+ attribute downloadToken { text },
+ element thumbnail {
+ attribute width { xsd:integer },
+ attribute height { xsd:integer },
+ attribute clientGenerated { 0, 1 }? // default=0
+ }?
+ element image {
+ attribute width { xsd:integer },
+ attribute height { xsd:integer }
+ }?
+ }
+
+Changes to the attachment record are replicated to all waves which refer to
+that attachment.
+
+The blip in which the attachment was inserted also contains an XML node which
+references the attachment, located at the insertion point of the attachment.
+This XML element (known as the embed) is a placeholder for the thumbnail to be
+rendered and takes the form::
+
+ <w:image attachment="attachment id"><w:caption>the thumbnail
caption</w:caption></w:image>
+
+
+Attachment Creation
+###################
+
+Attachments may be "created" in several different ways:
+
+* Uploading a thumbnail for the attachment
+* Uploading the attachment blob itself (or the first N bytes)
+* Linking an existing attachment to a new wave
+
+Each of these actions is represented by an attachment creation request.
+Attachment creation requests are sent as an HTTP POST, and may be either sent
+as an HTTP multipart request (enctype=multipart/form-data), or as a plain POST
+(enctype=application/x-www-form-urlencoded). The multipart POST is accepted to
+allow file uploads from non-Gears / HTML5 enabled browsers.
+
+In either case, the following fields may be sent either as HTTP POST
+parameters, or in the HTTP header::
+
+ required string attachmentId;
+ required string waveletName;
+ required int uploadType; // 0 for attachment, 1 for thumbnail
+ optional bool complete; // true if data field represents the entire
attachment
+ optional int thumbnail_width;
+ optional int thumbnail_height;
+
+For the non-multipart case, the filename is also optionally provided in the
+parameters / header.::
+
+ optional string fileName;
+
+and the bytes of the attachment / thumbnail are sent as the body of the POST.
+
+In the multipart case, only the part with name set to "uploadAttachment" is
+read, any other uploaded files are ignored. The filename is read from the
+filename field in the content-disposition for the file.
+
+Create requests are idempotent, so for instance it's okay to send one creation
+request with a thumbnail, and another with the first chunk of the attachment
+data. If the attachment record already exists, but the waveletName field does
+not correspond to any of the wavelets currently linked to the attachment, the
+existing attachment will be linked to the provided wavelet. Other fields which
+are already present in the existing attachment will be ignored.
+
+Example creation flow:
+
+1. User initiates attachment creation by dragging an image into the browser
(using Gears)
+
+2. Client generates a globally unique ID for the attachment
+
+3. Client thumbnails the image (using Gears) and displays it locally by adding
an <image> tag to the blip (other clients seeing the <image> tag will display
an empty thumbnail frame). The client then sends an HTTP POST containing a
create request, and the thumbnail data, to the Attachment server (via WFE)
+
+4. Attachment server creates a record in permanent storage for the attachment
and stores the (re-encoded for security) user-provided thumbnail
+
+5. Attachment server returns success to the client
+
+6. Attachment server creates a data document on the wavelet and adds a copy of
the attachment metadata.
+
+7. Thumbnail is now ready to download
+
+8. Client sends an HTTP POST containing the attachment
+
+9. Attachment server updates the attachment record in permanent storage
+
+10. Attachment server returns success to the client
+
+11. Attachment server generates a thumbnail for the attachment
+
+12. Image attachments are reprocessed to prevent XSS attacks, and attachments
are scanned for malware
+
+13. Attachment server updates the attachment data document on the wavelet
+
+14. Attachment is now ready to download
+
+Steps 8-14 may happen in parallel with 3-7.
+
+Below is an example of a multipart (non-Gears) creation request::
+
+ POST /wfe/upload/result HTTP/1.1
+ Host: wave.google.com
+ Content-Type: multipart/form-data;
boundary=---------------------------10102754414578508781458777923
+ Content-Length: 195197
+ -----------------------------10102754414578508781458777923
+ Content-Disposition: form-data; name="uploadAttachment";
filename="Downtown.pdf"
+ Content-Type: application/pdf
+
+ <encoded attachment binary data here>
+
+ -----------------------------10102754414578508781458777923
+ Content-Disposition: form-data; name="waveletName"
+
+ wavesandbox.com/w+6bf32acc-bd29-45c2-a252-699af690f5a6/conv+root
+ -----------------------------10102754414578508781458777923
+ Content-Disposition: form-data; name="attachmentId"
+
+ wavesandbox.com/3eb1c8ba-172b-4b1a-ae5b-d3140ed85c42
+
+ -----------------------------10102754414578508781458777923
+ Content-Disposition: form-data; name="uploadType"
+
+ 0
+ -----------------------------10102754414578508781458777923--
+
+
+Uploading
+#########
+
+Clients may upload large attachments in multiple chunks using an upload
request::
+
+ required string attachmentId;
+ required int offset;
+ optional int fullSize;
+
+The binary data is sent as per the creation request. Either multipart or form
+POSTs are accepted.
+
+An upload request may not be sent until the upload request (or create request)
+for the previous chunk has been acknowledged. That is, we don't currently
+support pipelining. Chunks must not overlap. Behaviour is not specified if
+chunk boundaries overlap.
+
+The response to HTTP upload / create requests is a string containing a single
+JSON object of the form::
+
+ {
+ responseCode: <response>,
+ errorMessage: "<error message> "
+ }
+
+Possible values for the responseCode field are::
+
+ 0 (OK)
+ 1 (INVALID_TOKEN)
+ 2 (INVALID_REQUEST)
+ 1000 (INTERNAL_SERVER_ERROR)
+
+The errorMessage field will not be provided for the non-error case (OK).
+Otherwise, it will contain a human-readable (although not necessarily end-user
+friendly) error message.
+
+In conjunction with these custom error codes, HTTP response codes should also
+be respected, however, due to limitations with cross-domain POSTs, the JSON
+response codes are used in preference.
+
+Attachment / Thumbnail download
+###############################
+
+A download request takes the following form::
+
+ required string attachmentId;
+ required string downloadToken;
+
+Requests for thumbnails / attachments are sent on different URLs, but otherwise
+look identical.
+
+The response to these requests is an HTTP response containing the bytes of the
+attachment / thumbnail, with the HTTP Content-Disposition header set to
+"attachment". The mime type of the response is set to the mime type of the
+attachment or thumbnail.
+
+Authentication / Authorization
+##############################
+
+Google web-apps use a centralized cookie-based authentication system.
+Authentication for upload and creation requests uses this system. In order to
+write the corresponding attachment data document into an associated wavelet,
+the user must be a participant on that wavelet.
+
+Downloads are authenticated using a download token which is stored in the
+attachment data document on the wavelet. Thus to download an attachment or a
+thumbnail, the user must at some point in time have had access to both the
+attachment id and the download token.
+
+Duplicate elimination
+#####################
+
+Because we expect a large percentage of attachments to be duplicates, we have
+an offline de-duping procedure. We store a weak hash with each attachment, and
+an offline process indexes attachments by hash, detects collisions, and then
+does a byte-by-byte comparison to eliminate duplicates. This is only done on
+attachments that are completely uploaded, and effectively immutable, and only
+on 'large' blobs, which are stored in a separate store. We maintain a level of
+indirection for these large blobs, so that we don't have to update the pointers
+upon duplicate detection and to prevent the leakage of information about the
+existence of previously uploaded attachments.
+
+References
+##########
+
+* E. Nebel and L. Masinter, `Form-based File Upload in HTML
<http://www.ietf.org/rfc/rfc1867.txt>`_, IETF RFC 1867, November 1995
+* F. Chang et al., `Google Research Publication: Bigtable
<http://labs.google.com/papers/bigtable.html>`_, OSDI'06: Seventh Symposium on
Operating System Design and Implementation, November 2006.
+* S. Lassen and S. Thorogood, `Google Wave Federation Architecture
<http://www.waveprotocol.org/whitepapers/google-wave-architecture>`_, June 2009
Added:
incubator/wave/whitepapers/attachments/img/attachment-server-architecture.png
URL:
http://svn.apache.org/viewvc/incubator/wave/whitepapers/attachments/img/attachment-server-architecture.png?rev=1489334&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
incubator/wave/whitepapers/attachments/img/attachment-server-architecture.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: incubator/wave/whitepapers/client-server-protocol/Makefile
URL:
http://svn.apache.org/viewvc/incubator/wave/whitepapers/client-server-protocol/Makefile?rev=1489334&view=auto
==============================================================================
--- incubator/wave/whitepapers/client-server-protocol/Makefile (added)
+++ incubator/wave/whitepapers/client-server-protocol/Makefile Tue Jun 4
08:33:44 2013
@@ -0,0 +1,3 @@
+include ../rules.mk
+
+default: client-server-protocol.html
Added:
incubator/wave/whitepapers/client-server-protocol/client-server-protocol.html
URL:
http://svn.apache.org/viewvc/incubator/wave/whitepapers/client-server-protocol/client-server-protocol.html?rev=1489334&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
incubator/wave/whitepapers/client-server-protocol/client-server-protocol.html
------------------------------------------------------------------------------
svn:mime-type = application/xml
Added:
incubator/wave/whitepapers/client-server-protocol/client-server-protocol.rst
URL:
http://svn.apache.org/viewvc/incubator/wave/whitepapers/client-server-protocol/client-server-protocol.rst?rev=1489334&view=auto
==============================================================================
---
incubator/wave/whitepapers/client-server-protocol/client-server-protocol.rst
(added)
+++
incubator/wave/whitepapers/client-server-protocol/client-server-protocol.rst
Tue Jun 4 08:33:44 2013
@@ -0,0 +1,333 @@
+#############################################
+Google Wave Client-Server Protocol Whitepaper
+#############################################
+
+.. Use headers in this order #=~-_
+
+:Authors:
+ Joe Gregorio
+
+:Version: 2.0 - May 2010
+
+This whitepaper is part of a series. All of the whitepapers
+can be found on `Google Wave Federation Protocol site`_.
+
+.. _Google Wave Federation Protocol site:
http://www.waveprotocol.org/whitepapers
+
+
+Editorial Notes
+###############
+To provide feedback on this draft join the wave-protocol
+mailing list at
+`http://groups.google.com/group/wave-protocol
<http://groups.google.com/group/wave-protocol>`_
+
+This current draft only covers a small subset of the functionality
+that is required to build a full client. Future drafts
+will expand to cover more functionality.
+
+Introduction
+############
+This document describes the protocol by which a
+wave client communicates with a wave server in order to
+create, read, and modify waves. The protocol is defined in
+terms of JSON messages exchanged over WebSockets.
+
+Background
+##########
+There is already a protocol being defined to handle the federation
+of Waves, however it was designed as a server-to-server protocol and
+is not well suited for clients.
+What is needed is a lighter weight protocol that only captures
+the needs of a client-server communication channel. The WebSockets protocol
+was chosen because it provides the two-way communication
+channel needed to efficiently handle wave messages, while being light weight
+and targeted to browsers, which are considered a primary platform
+for client developers.
+
+Scope
+#####
+This specification only covers the rudiments of the communication between
+a client and a server. There are many things that are not covered by
+this specification at this time, such as authentication, authorization,
+how a client determines which server to talk to, or which port to use.
+This protocol is a very simple client/server protocol implementation,
+and does not reflect the Google Wave web client protocol
+used in production today.
+
+Data Model
+##########
+It is important to understand the `Wave Federation Protocol`_
+and `Conversation Model`_ as a prerequisite to this specification.
+
+.. _Conversation Model:
http://www.waveprotocol.org/draft-protocol-specs/wave-conversation-model
+.. _Wave Federation Protocol:
http://www.waveprotocol.org/draft-protocol-specs/draft-protocol-spec
+
+Terminology
+===========
+The following terminology is used by this specification:
+
+* wave - a collection of wavelets
+* wavelet - a collection of named documents and participants, and the domain
of operational transformation
+* document - a structured wave document
+* wave message - a single message sent either from the client to the server or
from the server to the client.
+
+Wave messages do not include the WebSocket opening handshake messages.
+
+Operation
+#########
+This section assumes an elementary understanding of the theory of `Operational
+Transforms`_.
+
+.. _Operational Transforms:
http://www.waveprotocol.org/whitepapers/operational-transform
+
+Protocol Version
+================
+In the current implementation the version of the protocol is carried in each
+message and if the server does not understand the version sent it closes
+the connection. Future revisions may have the client and server negotiate
+for an agreed upon protocol version.
+
+The version of the protocol used is 1.
+
+Transport
+=========
+The protocol begins when a Wave client connects with a Wave server.
+The connection is handled by the WebSockets protocol. After the connection
+is initiated Wave messages are sent between the client and
+server encapsulated in WebSocket frames. Each message occupies
+a single frame.
+
+Transport Error Conditions
+==========================
+
+WebSocket Errors
+~~~~~~~~~~~~~~~~
+TBD
+
+Timeouts
+~~~~~~~~
+TBD
+
+Error recovery
+~~~~~~~~~~~~~~
+TDB
+
+Message Flow
+============
+There are two kinds of Wave requests, ProtocolOpenRequest
+and ProtocolSubmitRequest. Communication begins when
+a client sends a ProtocolOpenRequest to the server with the
+id of a Wave it wishes to monitor and/or mutate. After opening
+a wave the client may send ProtocolSubmitRequests
+to the server to manipulate the wave. The server will
+send ProtocolWaveletUpdates to the client as the server
+representation of the wave changes.
+
+Any error messages related to the opening of a wave
+are sent back from the server in a ProtocolWaveletUpdate.
+
+A client may send more than one ProtocolOpenRequest, one for
+each wave that the client is interested in.
+
+The client MUST send a ProtocolOpenRequest for each
+wave that the client is interested in. A client MUST NOT
+send mutations for a wave id that it has not issued a
+ProtocolOpenRequest for. The client must
+wait for the server to acknowledge the ProtocolOpenRequest
+before sending ProtocolSubmitRequests for the given
+wave as it needs to include the document hash with
+each ProtocolSubmitRequest.
+
+ProtocolOpenRequest
+~~~~~~~~~~~~~~~~~~~
+The ProtocolOpenRequest contains a wave id and
+a wavelet_id_prefix. Those two determine the set of
+wavelets that the client will be notified of changes
+to.
+
+The wavelet_id_prefix may be shortened to match
+a larger subset of wavelets, with the empty string
+matching all wavelets in the given wave.
+
+The client can indicate if it supports snapshots when
+it sends a ProtocolOpenRequest.
+
+It also contains the protocol version number, which is
+defined as 1, per the previous section on Protocol Version.
+
+
+ProtocolWaveletUpdate
+~~~~~~~~~~~~~~~~~~~~~
+In response to a ProtocolOpenRequest the server may
+send any number of ProtocolWaveletUpdate messages.
+The ProtocolWaveletUpdate may contain a snapshot of
+the current wave state or it will contain one or more
+ProtocolWaveletDelta messages that represent deltas
+to be applied to wavelets that the client is monitoring.
+The inclusion of the snapshot is determined by the
+server, it will only be sent on the first ProtocolWaveletUpdate,
+and will only be sent if the client has indicated in its
+ProtocolOpenRequest that it supports receiving snapshots.
+
+ProtocolWaveletUpdate messages will only be sent for
+wavelets that the client is an explicit participant in.
+
+ProtocolSubmitRequest
+~~~~~~~~~~~~~~~~~~~~~
+This message contains a ProtocolWaveletDelta which the
+client requests the server to apply to a wave. Only one
+submit per wavelet may be outstanding at any one time.
+
+The client specifies which version to apply the delta at,
+and the client is expected to transform deltas pending
+for submission against deltas received in
+ProtocolWaveletUpdates from the server.
+
+ProtocolWaveletDelta's are applied atomically and either
+fully succeed, or the whole delta will fail.
+
+ProtocolSubmitResponse
+~~~~~~~~~~~~~~~~~~~~~~
+The ProtocolSubmitResponse acknowledges the ProtocolSubmitRequest
+and if the delta was successfully applied it also supplies the
+ProtocolHashedVersion of the wavelet after the delta, which
+the client will need to successfully submit future deltas
+to the wavelet.
+
+Closing a wave
+~~~~~~~~~~~~~~
+TBD
+
+Specific Flows
+##############
+
+Search
+======
+TBD
+
+Creating a new wave
+===================
+Creating a new wave is different from other flows
+since neither the client nor the server have the wave
+id. The client must generate a unique id for the wave
+and send a ProtocolOpenRequest for that wave id.
+
+Entropy and Wave ID Length
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+TBD
+
+Serializing Protocol Buffers as JSON
+####################################
+There is no standard serialization of Protocol Buffers
+into JSON. This section will define the serialization
+that is used to construct Wave Messages from the protocol
+buffers included in this specification.
+
+Protocol buffer messages may be nested, so this serialization
+algorithm must be applied recursively.
+
+The root level message is emitted as a JSON object. Each
+member of the message will be emitted as a key-value pair
+in the JSON object. Each member's key name in
+the JSON serialization is set to normalize(key), where
+normalize is a function that takes in the protocol
+buffer member key name and returns a JSON utf-8 string.
+
+normalize()
+===========
+TBD
+
+Member value serialization
+==========================
+The serialization of a value for the key is dependent
+on the type and modifiers of that member. If the member
+is flagged as 'repeated' then the serialized
+value will be a JSON array. The array will be filled
+with the serialized values of the repeated members.
+
+Modifiers
+=========
+The following modifiers can be applied to message
+values and they alter how the values are serialized.
+
+repeated
+~~~~~~~~
+For each repeated member value, serialize it as
+JSON according to the following rules and add the serialization
+to the JSON array.
+
+required
+~~~~~~~~
+Required parameters are always serialized into JSON.
+
+optional
+~~~~~~~~
+Optional parameters are only serialized if they appear in the
+protocol buffer.
+
+string
+======
+A string member of a protocol buffer message is serialized
+as a JSON string.
+
+int
+===
+An int32 or int64 member of a protocol buffer message
+is serialized as a JSON number.
+
+bool
+====
+A bool value is serialized as a JSON number with a value of
+1 for true and 0 for false.
+
+enum
+====
+An enum value is serialized as a JSON string for the enumeration's value.
+
+bytes
+=====
+A bytes value is hex encoded and serialized as a JSON string.
+
+message
+=======
+A protocol buffer message is serialized by recursively applying
+the rules in this section.
+
+Security
+########
+
+Securing the channel
+====================
+TBD
+
+Authenticating the client
+=========================
+TBD
+
+Authorization
+=============
+Authorization is covered in the `Access Control Whitepaper`_.
+
+.. _Access Control Whitepaper:
http://www.waveprotocol.org/whitepapers/access-control
+
+Client-Server Protocol Buffers
+##############################
+While the client server protocol is implemented as JSON over WebSockets,
+each Wave message is a JSON serialization of a protocol buffer. The
+protocol buffer definitions are defined as:
+
+ TBD
+
+Example Client-Server Flow
+##########################
+
+ TBD
+
+Appendix A - Open Source Implementation Notes
+#############################################
+The current open source implementation of the
+client-server protocol begins with the client
+opening the wave "indexwave!indexwave". That
+is currently an implementation detail and is not
+documented.
+
Added: incubator/wave/whitepapers/conversation/Makefile
URL:
http://svn.apache.org/viewvc/incubator/wave/whitepapers/conversation/Makefile?rev=1489334&view=auto
==============================================================================
--- incubator/wave/whitepapers/conversation/Makefile (added)
+++ incubator/wave/whitepapers/conversation/Makefile Tue Jun 4 08:33:44 2013
@@ -0,0 +1,17 @@
+# Copyright 2009 Google Inc. All Rights Reserved.
+# Author: [email protected] (Christian Ohler)
+
+default: convspec.html
+
+.PHONY: clean
+clean:
+ -rm convspec.html
+
+convspec.html: convspec.xml
+# If there's a syntax error, xml2rfc will, by default, bring up a
+# dialog window if DISPLAY is set. We just want the message on
+# stderr, so we run it without DISPLAY.
+ DISPLAY= xml2rfc $< $@
+
+convspec.xml: convspec.rst
+ python ../rst2rfc.py convspec.rst > convspec.xml
