public/lib/module_resolver/fidl/module_resolver.fidl

// 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 modular;

// import "lib/daisy/fidl/daisy.fidl";
// import "lib/story/fidl/create_chain.fidl";
// import "lib/story/fidl/create_link.fidl";
// import "lib/module/fidl/link_path.fidl";
// import "lib/module/fidl/module_manifest.fidl";

[ServiceName="modular.ModuleResolver"]
interface ModuleResolver {
  // Finds Modules (contained in Fuchsia packages) that satisfy the constraints
  // specified in |query|. Results are returned in order according to scoring
  // configuration and signals given in |scoring_info|.
  //
  // If no results could be found, |modules| will be empty.
  // TODO(thatguy): Offer some kind of fallback instruction/option to clients
  // in the case of no results.
  //
  // For detailed information on the resolution process, see
  // docs/module_resolution.md.
  // TODO(thatguy): Make |scoring_info| required, when we do ranking.
  1: FindModules(ResolverQuery query, ResolverScoringInfo? scoring_info) ->
      (FindModulesResult result);
};

// Mirrors the information present in a Daisy. Where a Daisy 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 ResolverQuery {
  // Ignored if |url| is set.
  string? verb;

  // Set to the URL of the specific Module you wish to launch. If set, |verb|
  // is ignored.
  // TODO(thatguy): Replace with a package ID, whenever we've landed on what
  // exactly that looks like.
  string? url;

  vector<ResolverNounConstraintEntry>? noun_constraints;
};

struct ResolverNounConstraintEntry {
  // A null key is allowed for backwards compatibility reasons, and is only
  // allowed if |ResolverQuery.url| is given. MI4-739
  string? key;
  ResolverNounConstraint constraint;
};

union ResolverNounConstraint {
  // An Entity reference from which type constraints will be derived.
  // TODO(thatguy): Have callers populate |entity_type| directly, and remove
  // this.
  string entity_reference;

  // DEPRECATED: Use |entity_reference|.
  string json;

  // A list of Entity types.
  vector<string> entity_type;

  // Information about the state of a Link at the time this query is made.
  // TODO(thatguy): Collapse the contents of this into |entity_type| as well,
  // and add any other fields necessary for constraint matching.
  ResolverLinkInfo link_info;
};

struct ResolverLinkInfo {
  LinkPath path;

  // In the cases that a Link already has type constraints on it, those are
  // used directly instead of inferring them from an Entity value on the Link.
  LinkAllowedTypes? allowed_types;

  // If |allowed_types| is not available, an Entity reference in the Link's value
  // can be used to get type constraint information.
  string? content_snapshot;

  // TODO(thatguy): May want to include LinkPermissions for further matching
  // and constraint generation.
};

// TODO(thatguy): Placeholder to define the exact data (either directly contain
// or reference) used to support scoring of returned results.  It is in support
// of making |FindModules()| above a deterministic function.
// The method above, as written, would not be deterministic with respect to the
// Module Index, as that would be injected as a dependency at initialization
// time and may change asynchronously.
//
// This may become a service in the future.
struct ResolverScoringInfo {
  uint32 dummy; // FIDL2 does not allow empty structs
};

struct FindModulesResult {
  vector<ModuleResolverResult> modules;
};

struct ModuleResolverResult {
  // 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;

  CreateChainInfo create_chain_info;

  ResolutionDebugInfo? debug_info;
};

struct ResolutionDebugInfo {
  uint32 dummy; // FIDL2 does not allow empty structs
};