// Copyright 2022 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.component.resolution;

/// An interface for resolving a URL to a component.
///
/// This interface is implemented by components that provide support
/// for loading components with a particular URL scheme.   For example,
/// the Fuchsia package component resolver exposes a service with this
/// interface to resolve component URLs using the "fuchsia-pkg://" scheme.
///
/// To use a resolver to resolve URLs within your realm, register it
/// in your realm's manifest.
///
/// Note: The component manager is the only intended direct client of this
/// interface.
@discoverable
closed protocol Resolver {
    /// Resolves a component with the given absolute URL.
    ///
    /// `component_url` is the unescaped URL of the component to resolve.
    ///
    /// If successful, returns information about the component
    /// that was resolved.
    ///
    /// On failure, returns a `ResolverError` error.
    strict Resolve(struct {
        component_url string:MAX_COMPONENT_URL_LENGTH;
    }) -> (resource struct {
        component Component;
    }) error ResolverError;

    /// Resolves a component with the absolute or relative URL. If relative, the
    /// component will be resolved relative to the supplied `context`.
    ///
    /// `component_url` is the unescaped URL of the component to resolve, the
    /// format of which can be either:
    ///
    ///   * a fully-qualified absolute component URL; or
    ///   * a subpackaged-component reference, prefixed by a URI relative
    ///     path to its containing subpackage (for example,
    ///     `child_package#meta/some_component.cm`)
    ///
    /// `context` is the `resolution_context` of a previously-resolved
    /// `Component`, providing the context for resoving a relative URL.
    strict ResolveWithContext(struct {
        component_url string:MAX_COMPONENT_URL_LENGTH;
        context Context;
    }) -> (resource struct {
        component Component;
    }) error ResolverError;
};

/// The possible error conditions returned by ComponentResolver.
// TODO(fxbug.dev/72139): API review of ResolverError.
type ResolverError = strict enum {
    /// An unexpected error occurred.
    INTERNAL = 1;
    /// A general IO error occurred.
    IO = 2;
    /// The component URL was malformed.
    INVALID_ARGS = 3;
    /// The repository specified in the URL is unsupported.
    NOT_SUPPORTED = 4;
    /// The component manifest was not found.
    MANIFEST_NOT_FOUND = 5;
    /// The component's package was not found.
    PACKAGE_NOT_FOUND = 6;
    /// Insufficient space on device to store component's package.
    NO_SPACE = 7;
    /// The component is temporarily unavailable.
    RESOURCE_UNAVAILABLE = 8;
    /// The component manifest could not be parsed or it contained invalid configuration.
    INVALID_MANIFEST = 9;
    /// The component specifies configuration fields but the values were not found.
    CONFIG_VALUES_NOT_FOUND = 10;
    /// The ABI revision file could not be found.
    @available(added=12)
    ABI_REVISION_NOT_FOUND = 11;
    /// The ABI revision value could not be parsed.
    @available(added=12)
    INVALID_ABI_REVISION = 12;
};