// Copyright 2020 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.pkg;

using fuchsia.io;

/// A collection of TUF repositories contained in an attached storage device.
[Discoverable]
protocol LocalMirror {
    /// Obtains and returns a named TUF metadata file from an attached storage
    /// device.
    ///
    /// + request `repo_url` the URL of the TUF repository for which to return
    ///     metadata.
    /// + request `path` the path of the metadata file, relative to the
    ///     repository_metadata directory for the specific TUF repository.
    /// + request `metadata` a server end for a TUF metadata file to be opened
    ///     with `OPEN_RIGHT_READABLE | OPEN_FLAG_DESCRIBE`. If the metadata
    ///     directory exists but the requested file does not, the client end
    ///     will receive an OnOpen with `Status::NOT_FOUND`.
    /// * error a `GetMetadataError` value
    GetMetadata(
        RepositoryUrl repo_url,
        string:fuchsia.io.MAX_PATH path,
        request<fuchsia.io.File> metadata
        ) -> () error GetMetadataError;

    /// Obtains and returns a blob from an attached storage device.
    ///
    /// + request `blob_id` the id of the blob to return.
    /// + request `blob` a server end for a blob file to be opened
    ///     with `OPEN_RIGHT_READABLE | OPEN_FLAG_DESCRIBE`. If the blobs
    ///     directory exists but the requested file does not, the client end
    ///     will receive an OnOpen with `Status::NOT_FOUND`.
    /// * error a `GetBlobError` value
    GetBlob(
        BlobId blob_id,
        request<fuchsia.io.File> blob
        ) -> () error GetBlobError;
};

/// Error type for [`fuchsia.pkg/LocalMirror.GetMetadata`].
enum GetMetadataError {
    /// An error occurred when opening the requested metadata file. This may (though
    /// does not necessarily) indicate the metadata directory does not exist.
    ERROR_OPENING_METADATA = 1;
};

/// Error type for [`fuchsia.pkg/LocalMirror.GetBlob`].
enum GetBlobError {
    /// An error occurred when opening the requested blob. This may (though
    /// does not necessarily) indicate the blobs directory does not exist.
    ERROR_OPENING_BLOB = 1;
};