// Copyright 2025 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.
@available(added=HEAD)
library fuchsia.pkg.resolution;

using fuchsia.url;

/// Error codes for [`PackageResolver`] operations.
type ResolveError = flexible enum : int32 {
    /// The resolver encountered an otherwise unspecified error while handling the request.
    INTERNAL = 1;

    /// The resolver does not have permission to fetch a package blob.
    ACCESS_DENIED = 2;

    /// Some unspecified error during I/O.
    IO = 3;

    /// The package blob does not exist.
    BLOB_NOT_FOUND = 4;

    /// The package does not exist.
    PACKAGE_NOT_FOUND = 5;

    /// The resolver does not know about the repo.
    REPO_NOT_FOUND = 6;

    /// There is no space available to store the package or metadata.
    NO_SPACE = 7;

    /// The resolver is currently unable to fetch a package blob.
    UNAVAILABLE_BLOB = 8;

    /// The resolver is currently unable to fetch a repository's metadata.
    UNAVAILABLE_REPO_METADATA = 9;

    /// The `package_url` provided to resolver is invalid.
    INVALID_URL = 10;

    /// The `context` provided to resolver is invalid.
    INVALID_CONTEXT = 11;
};

/// A ResolveResult encapsulates the result of [`PackageResolver`] operations.
type ResolveResult = resource table {};

/// An abstract representation of a package resolver.
///
/// This is exposed to off-target SDK tooling, including ffx. Changes are subject to the
/// compatibility requirements set forth by those tools.
@discoverable(server="platform")
open protocol PackageResolver {
    /// If this method succeeds, and package garbage collection is not triggered in the interim,
    /// then subsequent resolves of the same package will not need to download any files. This is
    /// useful for pre-fetching large packages.
    ///
    /// + request `package_url` the absolute package URL for a package.  The
    ///   following link describes the format:
    ///   https://fuchsia.dev/fuchsia-src/concepts/packages/package_url.
    ///   URLs with fragments (aka resource paths) are used to indicate files within packages
    ///   (such as component manifests), not just packages, and so will be rejected.
    /// * error indicates failure. See [`ResolveError`] for values and error
    ///   scenarios.
    flexible Resolve(resource table {
        1: package_url string:fuchsia.url.MAX_URL_LENGTH;
    }) -> (ResolveResult) error ResolveError;
};