// 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(resource struct {
        repo_url RepositoryUrl;
        path string:fuchsia.io.MAX_PATH;
        metadata server_end:fuchsia.io.File;
    }) -> (struct {}) 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(resource struct {
        blob_id BlobId;
        blob server_end:fuchsia.io.File;
    }) -> (struct {}) error GetBlobError;
};

/// Error type for [`fuchsia.pkg/LocalMirror.GetMetadata`].
type GetMetadataError = strict enum {
    /// 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`].
type GetBlobError = strict enum {
    /// 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;
};