// Copyright 2017 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.ledger.cloud;

// This file defines a cloud service that can be used by Ledger to power cloud
// sync.

// Response status for cloud provider operations.
enum Status : int32 {
  OK = 0;
  AUTH_ERROR = 1;
  ARGUMENT_ERROR = 2;
  INTERNAL_ERROR = 3;
  NETWORK_ERROR = 4;
  NOT_FOUND = 5;
  PARSE_ERROR = 6;
  SERVER_ERROR = 7;
  UNKNOWN_ERROR = -1;
};

// Cloud service that powers cloud sync for a single user. Top-level interface
// of this file.
//
// Closing the client connection to CloudProvider shuts down all controllers
// (DeviceSets, PageClouds) that were produced by it.
[Discoverable]
interface CloudProvider {
  // Retrieves the controller for the user device set.
  1: GetDeviceSet(request<DeviceSet> device_set) -> (Status @status);

  // Retrieves the controller for cloud sync of a particular page.
  2: GetPageCloud(vector<uint8> app_id, vector<uint8> page_id, request<PageCloud> page_cloud)
      -> (Status @status);
};

// Cloud registry of devices participating in cloud sync.
//
// Closing the client connection to DeviceSet disconnects all watchers set on
// it.
interface DeviceSet {
  // Verifies that the device fingerprint in the cloud is still in the list of
  // devices, ensuring that the cloud was not erased since the last sync.
  1: CheckFingerprint(vector<uint8> fingerprint) -> (Status @status);

  // Adds the device fingerprint to the list of devices in the cloud.
  2: SetFingerprint(vector<uint8> fingerprint) -> (Status @status);

  // Watches the given |fingerprint| in the cloud so that |watcher| is notified
  // when the fingerprint is erased.
  //
  // At most one watcher can be set at any given time. If more than one watcher
  // is set, only the one set most recently receives notifications.
  //
  // The returned status is:
  //
  //   - OK, if setting the watcher succeeded,
  //   - NOT_FOUND, if the fingerprint was not found in the cloud
  //   - NETWORK_ERROR, if the watcher couldn't be set due to a network error
  //
  // If the returned status is not OK, the corresponding error call is also made
  // on the watcher.
  3: SetWatcher(vector<uint8> fingerprint, DeviceSetWatcher watcher)
      -> (Status @status);

  // Erases the entire registry of devices. This makes all devices detect that
  // cloud has been erased.
  4: Erase() -> (Status @status);
};

// Watcher for push notifications from the cloud registry of devices
// participating in cloud sync.
interface DeviceSetWatcher {
  // Called when cloud provider detects that the cloud storage was erased. No
  // further calls are made on the watcher after this is called.
  1: OnCloudErased();

  // Called when the network connection is lost. No further calls are made on
  // the watcher after this is called.
  2: OnNetworkError();
};

// Commit stored in the cloud.
struct Commit {
  // The id of the commit.
  vector<uint8> id;

  // The content of the commit.
  vector<uint8> data;
};

// A continuation token for paginated requests.
struct Token {
  vector<uint8> opaque_id;
};

// Handler for cloud sync of a single page.
//
// Implementation of this class manages a *commit log*, which is an append-only
// list of commits produced by all devices that participate in syncing this
// page. Position of commits within the log are references using position
// tokens, allowing the caller to retrieve the commits added to the cloud since
// the previous read. (plus possibly more - see comments for GetCommits() and
// SetWatcher().)
//
// Closing the client connection to PageCloud disconnects all watchers set on
// it.
interface PageCloud {
  // Adds the given commits to the commit log in the cloud.
  //
  // The commits are added in one batch, on the receiving side they are
  // delivered in the same order in a single OnNewCommits() call.
  1: AddCommits(vector<Commit> commits) -> (Status @status);

  // Retrieves commits from the cloud.
  //
  // All commits newer than |min_position_token| are guaranteed to be returned.
  // In addition to that, the response may include additional commits older
  // than or at |min_position_token|. Passing null |min_position_token|
  // retrieves all commits.
  //
  // If the resulting |status| is |OK|, |commits| contains all matching commits
  // (might be empty) and |position_token| contains the position token of the
  // most recent of the |commits| (equivalent to |min_position_token| if
  // |commits| is empty).
  2: GetCommits(Token? min_position_token)
      -> (Status @status, vector<Commit> commits, Token? position_token);

  // Uploads the given object to the cloud under the given id.
  //
  // If the object already exists in the cloud this method returns OK.
  3: AddObject(vector<uint8> id, fuchsia.mem.Buffer buffer) -> (Status @status);

  // Retrieves the object of the given id from the cloud.
  //
  // The size of the object is passed to the callback along with the socket
  // handle, so that the client can verify that all data was streamed when
  // draining the socket.
  //
  // TODO(ppi): return a VMO instead of a socket, see LE-442.
  4: GetObject(vector<uint8> id)
      -> (Status @status, uint64 size, handle<socket>? stream);

  // Watches the cloud for push notifications.
  //
  // At most one watcher can be set at any given time. If more than one watcher
  // is set, only the one set most recently receives notifications.
  //
  // All commits newer than |min_position_token| added to the cloud before or
  // after making this call are guaranteed to be delivered to |watcher|. In
  // addition to that, additional commits older than or at |min_position_token|
  // may be delivered to. If |min_position_token| is null, notifications for
  // all commits are delivered.
  5: SetWatcher(Token? min_position_token, PageCloudWatcher watcher)
      -> (Status @status);
};

// Watcher for push notifications from cloud sync of a single page.
interface PageCloudWatcher {
  // Called when new commits are added to the commit log in the cloud.
  //
  // The method takes the list of new |commits| along with the |position_token|
  // of the most recent of them.
  //
  // No subsequent calls are made until the client calls the callback of the
  // previous one.
  1: OnNewCommits(vector<Commit> commits, Token? position_token) -> ();

  // Called when a new object is added to the cloud.
  //
  // The method takes the |id| and the content of the new object.
  //
  // No subsequent calls are made until the client calls the callback of the
  // previous one.
  2: OnNewObject(vector<uint8> id, fuchsia.mem.Buffer buffer) -> ();

  // Called when an error occurs.
  //
  // No further calls are made on the watcher after this is called. The client
  // can then re-establish the watcher by calling SetWatcher() again.
  //
  // The status is one of:
  //
  //   - AUTH_ERROR, if the auth token needs a refresh
  //   - NETWORK_ERROR, if the connection was dropped
  //   - PARSE_ERROR, if an invalid server notification was received
  3: OnError(Status @status);
};