// 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;

using fuchsia.mem;

// 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();
};

// TODO(ppi): switch to a format defined in a FIDL table, so that the protocol
// is fully described by the FIDL file.
/// Contains an ordered list of commits serialized using the SerializedCommits
/// schema defined in serialized_commits.fbs.
struct CommitPack {
    fuchsia.mem.Buffer buffer;
};

/// 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(CommitPack 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, CommitPack? 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.
    ///
    /// If the resulting |status| is |OK|, |buffer| will contain the object
    /// content. If the resulting |status| is not |OK|, |buffer| will be null.
    4: GetObject(vector<uint8> id)
           -> (Status status, fuchsia.mem.Buffer? buffer);

    /// 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(CommitPack 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);
};