// Copyright 2017 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.modular;

[Discoverable]
protocol ModuleResolver {
    /// Finds Modules (contained in Fuchsia packages) that satisfy the constraints
    /// specified in `query`. Module resolution is done by matching the requested
    /// `query.action` and `query.parameter_constraints` (with both names and
    /// types) against actions and constraints specified in module manifests.
    ///
    /// If no results could be found, `response.results` will be empty.
    ///
    /// For detailed information on the resolution process, see
    /// docs/modular/module_resolution.md.
    ///
    // TODO(thatguy): Offer some kind of fallback instruction/option to clients
    // in the case of no results.
    FindModules(FindModulesQuery query) -> (FindModulesResponse response);
};

/// Mirrors the information present in a Intent. Where a Intent is meant to
/// interface between Modules and the Framework, this structure is specific to
/// the interface between the Framework and the ModuleResolver.
///
/// In that role, it has references to structures and concepts that are only
/// visible within the abstraction layer of the Framework.
struct FindModulesQuery {
    /// The handler is a module URL; if the handler is specified, the search for
    /// (action, parameter_constraints) is scoped within the specified handler.
    string? handler;
    string action;
    vector<FindModulesParameterConstraint> parameter_constraints;
};

struct FindModulesParameterConstraint {
    string param_name;
    vector<string> param_types;
};

enum FindModulesStatus {
    /// A search was successfully conducted.
    SUCCESS = 0;
    /// `FindModulesQuery.handler` was specified but the resolver doesn't know
    /// about it.
    UNKNOWN_HANDLER = 1;
};

struct FindModulesResponse {
    FindModulesStatus status;
    vector<FindModulesResult> results;
};

struct FindModulesResult {
    /// The ID of the Module. For now, this is the URL of the Module binary.
    string module_id;

    /// The Module's manifest file (see docs/manifests/module.md).
    ModuleManifest? manifest;
};