src/ledger/fidl/fuchsia.ledger.internal/internal.fidl

// Copyright 2016 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.internal;

using fuchsia.ledger;
using fuchsia.ledger.cloud;

// Entry interface implemented by the Ledger application, intended to be used by
// the process setting up the user environment to obtain repositories for
// individual users.
[Discoverable]
protocol LedgerRepositoryFactory {
    compose fuchsia.ledger.Syncable;

    // Binds to the directory referenced by `repository`. If this is called
    // multiple times for the same directory, only the first instance of
    // `server_id` / `cloud_provider` will be used. Any subsequent ones will
    // simply be ignored.
    //
    // Parameters:
    // `repository_directory` channel pointing to the disk directory where the
    //     repository is stored. At any given time, at most one repository
    //     instance backed by the same disk directory can be running
    //     concurrently.
    //     If this channel closes, `LedgerRepository` will close immediately.
    //     TODO(qsr): Use typed channel when remoteio has been migrated to FIDL2.
    // `cloud_provider` is used by Ledger to synchronize data through the
    //     cloud. If `cloud_provider` is disconnected, Ledger shuts down the
    //     repository and disconnects all clients.
    // `user_id` is a unique, not device local, user identifier. It will be
    //     used to enable Peer to Peer over Overnet, and will be removed
    //     once Overnet handles user identity. If it is empty, Ledger will not
    //     synchronize using Peer to Peer communication.
    GetRepository(handle<channel> repository_directory,
                  fuchsia.ledger.cloud.CloudProvider? cloud_provider,
                  string user_id,
                  request<LedgerRepository> repository);
};

// Controller interface for the Ledger application lifecycle.
[Discoverable]
protocol LedgerController {
    // Terminate the ledger application.
    Terminate();
};

protocol LedgerRepository {
    compose fuchsia.ledger.Syncable;

    // Creates a new Ledger for the given `ledger_name` if it doesn't already
    // exist.
    GetLedger(vector<uint8> ledger_name, request<fuchsia.ledger.Ledger> ledger);

    // Binds a new LedgerRepository handle to this repository.
    Duplicate(request<LedgerRepository> ledger_repository);

    // Sets a watcher to track the synchronization state of a user's Ledger. The
    // current state is immediately sent to the watcher when this method is
    // called.
    SetSyncStateWatcher(fuchsia.ledger.SyncWatcher watcher);

    // Tries to clean up disk space on the device by removing unused data that are
    // already backed up in the cloud.
    DiskCleanUp();

    // Closes the LedgerRepository. This method will close the LedgerRepository
    // connection once all connections to sub-objects (Ledgers, Pages,
    // PageSnapshots, pending Merges) are closed.
    // It is invalid to call any other method on LedgerRepository after
    // `Close()` is called.
    // Once the LedgerRepository connection is closed, it is guaranteed that
    // no access to the underlying storage will be made.
    Close();
};