wave/src/proto/proto/org/waveprotocol/box/common/comms/waveclient-rpc.proto

// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you 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.
//
// The wave view client-server protocol
//
// Author: jochen@google.com (Jochen Bekmann)
// Author: anorth@google.com (Alex North)

syntax = "proto2";

import "org/waveprotocol/box/server/rpc/rpc.proto";
import "org/waveprotocol/wave/federation/federation.protodevel";

package waveserver;

option java_package = "org.waveprotocol.box.common.comms";
option java_outer_classname = "WaveClientRpc";
option java_generic_services = true;

/**
 * Provides streaming wave views.
 *
 * A client requests a possibly filtered view of wavelets in a wave.
 * The response stream contains first a snapshot for each wavelet
 * currently in view, and then deltas for those wavelets. The end of
 * the initial set of snapshots is indicated by a "marker" message.
 * New wavelets may come into view after the marker, resulting in 
 * another snapshot.
 * 
 * The client may indicate that it already has a snapshot for some wavelets
 * by providing one or more known versions and signatures. If one matches
 * the server history the server will not send a snapshot but will instead
 * begin the stream with an empty delta specifying the resynchronization
 * version.
 * 
 * TODO(anorth):
 * - make the first response message a channel id only, then no more
 *   channel ids
 */
service ProtocolWaveClientRpc {
  rpc Open (ProtocolOpenRequest) returns (ProtocolWaveletUpdate) {
    option (rpc.is_streaming_rpc) = true;
  };
  rpc Submit (ProtocolSubmitRequest) returns (ProtocolSubmitResponse);
  rpc Authenticate (ProtocolAuthenticate) returns (ProtocolAuthenticationResult);
}

// A workaround for clients which do not support sending cookies over a websocket
// connection. See: http://code.google.com/p/wave-protocol/issues/detail?id=119
message ProtocolAuthenticate {
  required string token = 1;
}

// RPCs require a return type, although in this case no return data is desired.
// We don't want to return anything here because clients which implement
// websockets correctly (and thus don't use ProtocolAuthenticate) cannot
// recieve the authentication related information.
// If the client's authentication is not valid, the connection will be closed.
message ProtocolAuthenticationResult {
}

/**
 * A request to open a wave view.
 */
message ProtocolOpenRequest {
  // User making the request.
  // TODO(anorth): Remove this, replacing it with the implicit logged-in user.
  required string participant_id = 1;
  // Wave id to open.
  required string wave_id = 2;
  // Wavelet id prefixes by which to filter the view, empty means no filter.
  repeated string wavelet_id_prefix = 3;
  // Known wavelet versions for resynchronization.
  repeated WaveletVersion known_wavelet = 4;
}

// A pair of (wavelet id, wavelet version)
message WaveletVersion {
  required string wavelet_id = 1;
  required federation.ProtocolHashedVersion hashed_version = 2;
}

// A document and associated metadata
message DocumentSnapshot {
  required string document_id = 1;
  // This is a document operation that takes the document from zero to its current state.
  required federation.ProtocolDocumentOperation document_operation = 2;

  // ** Metadata
  // The participant who submitted the first operation to the document
  required string author = 3;
  // All participants who have submitted operations to the document
  repeated string contributor = 4;
  // The wavelet version when the document was last modified
  required int64 last_modified_version = 5;
  required int64 last_modified_time = 6;
}

// A wavelet and associated metadata.
message WaveletSnapshot {
  required string wavelet_id = 1;
  // The list of participants of this wavelet.
  repeated string participant_id = 2;
  // Snapshots of all the documents in the wavelet.
  repeated DocumentSnapshot document = 3;

  // ** Metadata
  // The current version of the wavelet
  required federation.ProtocolHashedVersion version = 4;
  // The participant that created the wavelet
  required int64 last_modified_time = 5;
  required string creator = 6;
  required int64 creation_time = 7;
}

// A snapshot of a user's view of a wave.
// Contains snapshots of all the wavelets visible to a user
message WaveViewSnapshot {
  required string wave_id = 1;
  repeated WaveletSnapshot wavelet = 2;
}

/**
 * Update message for a wave view.
 * Contains either:
 * - a channel id (only)
 * - a marker (only)
 * - a wavelet name, snapshot, version, and commit version
 * - a wavelet name, deltas, version
 * Must contain either one or more applied deltas or a commit notice.
 *
 * TODO(anorth): rename to reflect that this is a view update, not wavelet
 */
message ProtocolWaveletUpdate {
  // Specifies the wavelet name in the URI netpath notation.
  // Set only if there are deltas
  // TODO(anorth) make optional for channel id, marker updates
  required string wavelet_name = 1;

  // Zero or more deltas for this wavelet, streamed in order.
  // If snapshot is set, there should be zero deltas.
  // TODO(soren): consider using this in the snapshot case for uncommitted deltas.
  repeated federation.ProtocolWaveletDelta applied_delta = 2;

  // Indicates that the host server has committed the wavelet to disk at the
  // given version. Mandatory for snapshots.
  optional federation.ProtocolHashedVersion commit_notice = 3;

  // Resulting version of the wavelet after all deltas have been applied
  // May only be missing if there are no appliedDeltas
  // If snapshot is set, this is the version number of the snapshot, and is
  // mandatory.
  optional federation.ProtocolHashedVersion resulting_version = 4;

  // An optional snapshot of the wavelet
  optional WaveletSnapshot snapshot = 5;

  // View open marker, signifies all current snapshots have been sent.
  optional bool marker = 6 [default=false];

  // Channel id, set only in the first update to a client.
  // The client includes it in submits.
  optional string channel_id = 7;
}

/**
 * The client requests that the given delta be applied to the wavelet.
 */
message ProtocolSubmitRequest {
  required string wavelet_name = 1;
  required federation.ProtocolWaveletDelta delta = 2;
  optional string channel_id = 3;
}

/**
 * The result of submitting the delta to the server. If an error occurs
 * errorMessage will be present, otherwise hashedVersionAfterApplication will be
 * present. operationsApplied will report the actual number of operations
 * successfully applied to the wavelet by the server.
 */
message ProtocolSubmitResponse {
  required int32 operations_applied = 1;
  optional string error_message = 2;
  optional federation.ProtocolHashedVersion hashed_version_after_application = 3;
}