sdk/fidl/fuchsia.sys2/realm.fidl - fuchsia - Git at Google

 // 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.sys2;

 using fuchsia.io;
 using fuchsia.component;
 using fuchsia.component.decl;
 using fuchsia.component.config;
 using fuchsia.component.runner;
 using fuchsia.url;

 /// The maximum length of an instance ID.
 /// An instance ID is a 256-bit identifier, which when encoded
 /// in hex notation is 64 characters long.
 const MAX_INSTANCE_ID_LENGTH uint32 = 64;

 /// The maximum length of the human-readable start reason.
 /// This accounts for StartReason::AccessCapability which can have a length of
 /// MAX_MONIKER_LENGTH + MAX_NAME_LENGTH + 26 (4222 characters).
 const MAX_START_REASON uint32 = 5000;

 /// Errors that can be returned by the GetInstance call.
 type GetInstanceError = flexible enum {
     /// Could not find an instance matching the given moniker.
     INSTANCE_NOT_FOUND = 1;

     /// The given moniker could not be parsed.
     BAD_MONIKER = 2;
 };

 /// Errors that can be returned by the GetManifest call.
 type GetDeclarationError = flexible enum {
     /// Could not find an instance matching the given moniker.
     INSTANCE_NOT_FOUND = 1;

     /// The given moniker could not be parsed.
     BAD_MONIKER = 2;

     /// The component manifest is only available when the instance is resolved.
     INSTANCE_NOT_RESOLVED = 3;

     /// The component manifest could not be encoded into its persistable format.
     ENCODE_FAILED = 4;

     /// The specified collection was not found in the specified component.
     @available(added=12)
     BAD_CHILD_LOCATION = 5;

     /// The specified URL could not be parsed.
     @available(added=12)
     BAD_URL = 6;
 };

 /// Errors that can be returned by the GetStructuredConfig call.
 type GetStructuredConfigError = flexible enum {
     /// Could not find an instance matching the given moniker.
     INSTANCE_NOT_FOUND = 1;

     /// The given moniker could not be parsed.
     BAD_MONIKER = 2;

     /// The component manifest is only available when the instance is resolved.
     INSTANCE_NOT_RESOLVED = 3;

     /// There is no structured configuration associated with this instance.
     NO_CONFIG = 4;
 };

 /// Errors that can be returned by the GetAllInstances call.
 type GetAllInstancesError = flexible enum {
     /// Could not find the scope root instance.
     INSTANCE_NOT_FOUND = 1;
 };

 /// Errors that can be returned by the OpenDirectory call.
 type OpenError = flexible enum {
     /// Could not find an instance matching the given moniker.
     INSTANCE_NOT_FOUND = 1;

     /// The given moniker could not be parsed.
     BAD_MONIKER = 2;

     /// The requested directory is available when the instance is resolved.
     INSTANCE_NOT_RESOLVED = 3;

     /// The requested directory is available when the instance is running.
     ///
     /// Deprecation: the platform will stop emitting this error from version 19.
     /// The component will always be started if not already.
     @available(deprecated=19)
     INSTANCE_NOT_RUNNING = 4;

     /// Component manager's open request on the directory returned a FIDL error.
     FIDL_ERROR = 5;

     /// The instance does not have a directory of this type.
     NO_SUCH_DIR = 6;

     /// The given directory type could not be parsed.
     BAD_DIR_TYPE = 7;

     /// The given path could not be parsed by component manager.
     BAD_PATH = 8;

     /// Serving the requested directory requires starting the instance, but the
     /// instance failed to start.
     @available(added=19)
     INSTANCE_FAILED_TO_START = 9;
 };

 /// Errors that can be returned by the ConstructNamespace call.
 type ConstructNamespaceError = flexible enum {
     /// Could not find an instance matching the given moniker.
     INSTANCE_NOT_FOUND = 1;

     /// The given moniker could not be parsed.
     BAD_MONIKER = 2;

     /// Namespace construction requires the instance to be resolved.
     INSTANCE_NOT_RESOLVED = 3;
 };

 /// Errors that can be returned by the ConnectToStorageAdmin call.
 type ConnectToStorageAdminError = flexible enum {
     /// Could not find an instance matching the given moniker.
     INSTANCE_NOT_FOUND = 1;

     /// The given moniker could not be parsed.
     BAD_MONIKER = 2;

     /// The instance does not define a storage capability with the given name.
     STORAGE_NOT_FOUND = 3;

     /// This operation requires the instance to be resolved.
     INSTANCE_NOT_RESOLVED = 4;

     /// The given storage capability could not be parsed.
     BAD_CAPABILITY = 5;
 };

 /// Describes a component instance under a realm.
 ///
 /// Note: This structure is expected to fit in a single Zircon channel message.
 ///       Do not add fields that have the potential to violate that constraint.
 ///       Prefer to create dedicated methods and iterators instead.
 @available(added=11)
 type Instance = table {
     /// The path to this instance relative to the scope root.
     1: moniker string:fuchsia.component.MAX_MONIKER_LENGTH;

     /// The URL of the component manifest for this instance.
     2: url fuchsia.url.Url;

     /// The stable identifier for this instance, if one exists.
     3: instance_id string:<MAX_INSTANCE_ID_LENGTH>;

     /// Information about the resolved state of a component instance.
     /// If the component is not resolved, this field is not set.
     4: resolved_info ResolvedInfo;

     /// The component's environment name as defined by its parent.
     5: environment string:fuchsia.component.MAX_MONIKER_LENGTH;
 };

 /// Information about the resolved state of a component instance.
 @available(added=11)
 type ResolvedInfo = table {
     /// The resolved URL of this instance.
     1: resolved_url fuchsia.url.Url;

     /// Information about the execution state of a component instance.
     /// If the component is not running, this field is not set.
     2: execution_info ExecutionInfo;
 };

 /// Information about the execution state of a component instance.
 @available(added=11)
 type ExecutionInfo = table {
     /// The human-readable explanation for why this instance was started.
     1: start_reason string:MAX_START_REASON;
 };

 /// The directories of an instance that can be opened by component manager.
 @available(added=11)
 type OpenDirType = flexible enum {
     /// Served by the component's program. Rights unknown.
     OUTGOING_DIR = 1;
     /// Served by the component's runner. Rights unknown.
     RUNTIME_DIR = 2;
     /// Served by the component's resolver. Rights unknown.
     PACKAGE_DIR = 3;
     /// Served by component manager. Directory has RW rights.
     EXPOSED_DIR = 4;
     /// Served by component manager. Directory has RW rights.
     NAMESPACE_DIR = 5;
 };

 /// Locations from which a child could be resolved under a given parent.
 type ChildLocation = flexible union {
     1: collection string:fuchsia.component.MAX_NAME_LENGTH;

     // TODO(https://fxbug.dev/42077932) support static children
 };

 /// Offers detailed introspection into component instances under a realm.
 @discoverable
 closed protocol RealmQuery {
     /// Gets an instance identified by its moniker.
     @available(added=11)
     strict GetInstance(struct {
         moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
     }) -> (struct {
         instance Instance;
     }) error GetInstanceError;

     /// Gets the manifest of an instance identified by its moniker.
     ///
     /// The manifest is encoded in its standalone persistable format per RFC-0120 and
     /// is sent across using an iterator. Some manifests are too large to send over a
     /// Zircon channel and we can't use a VMO because we need an approach that is
     /// compatible with overnet.
     @available(added=13)
     strict GetResolvedDeclaration(struct {
         moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
     }) -> (resource struct {
         iterator client_end:ManifestBytesIterator;
     }) error GetDeclarationError;

     // TODO(https://fxbug.dev/42077935) delete once no longer required for ffx compat window
     /// Prefer `GetResolvedDeclaration` if available for your target API level.
     @available(added=11)
     strict GetManifest(struct {
         moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
     }) -> (resource struct {
         iterator client_end:ManifestBytesIterator;
     }) error GetDeclarationError;

     /// Gets the manifest of a component URL as if it were a child of the specified parent
     /// without actually creating or starting that component.
     ///
     /// The manifest is encoded in its standalone persistable format per RFC-0120 and
     /// is sent across using an iterator. Some manifests are too large to send over a
     /// Zircon channel and we can't use a VMO because we need an approach that is
     /// compatible with overnet.
     @available(added=12)
     strict ResolveDeclaration(struct {
         parent string:fuchsia.component.MAX_MONIKER_LENGTH;
         child_location ChildLocation;
         url fuchsia.url.Url;
     }) -> (resource struct {
         iterator client_end:ManifestBytesIterator;
     }) error GetDeclarationError;

     /// Gets the structured config of an instance identified by its moniker.
     @available(added=13)
     strict GetStructuredConfig(struct {
         moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
     }) -> (struct {
         config fuchsia.component.decl.ResolvedConfig;
     }) error GetStructuredConfigError;

     // replaced by ABI-compatible version above
     @available(added=11, replaced=13)
     strict GetStructuredConfig(struct {
         moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
     }) -> (struct {
         config fuchsia.component.config.ResolvedConfig;
     }) error GetStructuredConfigError;

     /// Returns an iterator over all component instances in this realm and instances within resolved
     /// children, recursively. Unresolved child components will be included in this list, but
     /// children of unresolved children will not be.
     @available(added=11)
     strict GetAllInstances() -> (resource struct {
         iterator client_end:InstanceIterator;
     }) error GetAllInstancesError;

     /// Constructs the namespace of an instance as determined by its use declarations.
     /// This is usually identical to what would be given to the component's runner on
     /// component start time, unless extended by
     /// `fuchsia.component/StartChildArgs.namespace_entries`.
     @available(added=11)
     strict ConstructNamespace(struct {
         moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
     }) -> (resource struct {
         /// The directory handles + paths that constitute the component's namespace.
         namespace vector<fuchsia.component.runner.ComponentNamespaceEntry>:MAX;
     }) error ConstructNamespaceError;

     /// Makes an fuchsia.io.Directory/Open call on a directory in an instance.
     @available(added=11)
     strict Open(resource struct {
         moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
         dir_type OpenDirType;
         flags fuchsia.io.OpenFlags;
         mode fuchsia.io.ModeType;
         path string:fuchsia.io.MAX_PATH_LENGTH;
         object server_end:fuchsia.io.Node;
     }) -> () error OpenError;

     /// Connects to the StorageAdmin protocol of a storage declared by an instance.
     @available(added=11)
     strict ConnectToStorageAdmin(resource struct {
         moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
         storage_name fuchsia.component.decl.name;
         server_end server_end:StorageAdmin;
     }) -> () error ConnectToStorageAdminError;

     /// Gets the detailed information of a particular instance identified by its moniker.
     /// This response contains handles to resources of the instance. As a result, component manager
     /// pays a non-trivial cost when this method is invoked.
     @available(added=11, deprecated=11, removed=12, note="Use GetInstance instead")
     strict GetInstanceInfo(struct {
         moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
     }) -> (resource struct {
         /// Basic information about the component instance.
         info InstanceInfo;

         /// Detailed information about the resolved component instance.
         /// If this object does not exist, the instance is not resolved.
         resolved box<ResolvedState>;
     }) error RealmQueryError;

     /// Gets all directories relevant to a particular instance identified by its moniker.
     /// This response contains directory handles served by component manager. As a result,
     /// component manager pays a non-trivial cost when this method is invoked.
     @available(added=11, deprecated=11, removed=12, note="Use Open instead")
     strict GetInstanceDirectories(struct {
         moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
     }) -> (resource struct {
         /// The directories available because the component instance is in resolved state
         /// If this object does not exist, the instance is not resolved.
         resolved_dirs box<ResolvedDirectories>;
     }) error RealmQueryError;
 };

 /// An iterator over all instances in the realm
 @available(added=11)
 closed protocol InstanceIterator {
     strict Next() -> (struct {
         infos vector<Instance>:MAX;
     });
 };

 /// An iterator over the bytes of an instance's manifest
 @available(added=11)
 closed protocol ManifestBytesIterator {
     strict Next() -> (struct {
         infos vector<uint8>:MAX;
     });
 };

 // ------------------------------------------------------------
 // All types below are marked deprecated and will be removed in
 // a newer API version.
 // ------------------------------------------------------------

 /// Describes the current state of instance
 @available(added=11, deprecated=11, removed=12)
 type InstanceState = strict enum {
     /// The component is created, but has not been resolved by component manager.
     /// Most information about this component is unknown.
     UNRESOLVED = 0;

     /// The component has been resolved by component manager but is not currently running.
     RESOLVED = 1;

     /// The component has been resolved and started by component manager. It is currently running.
     STARTED = 2;
 };

 /// Basic information about a component instance.
 /// This object contains information that is readily available to component manager.
 @available(added=11, deprecated=11, removed=12, note="Use Instance instead")
 type InstanceInfo = struct {
     /// The path to this instance relative to the scope root.
     moniker string:fuchsia.component.MAX_MONIKER_LENGTH;

     /// The URL of the component manifest for this instance.
     url fuchsia.url.Url;

     /// The stable identifier for this instance.
     instance_id string:<MAX_INSTANCE_ID_LENGTH, optional>;

     /// The current state of this instance.
     state InstanceState;
 };

 /// The detailed resolved state of a component instance
 @available(added=11, deprecated=11, removed=12, note="Use ResolvedInfo instead")
 type ResolvedState = resource struct {
     /// All `use` declarations as defined in the component manifest.
     uses vector<fuchsia.component.decl.Use>:MAX;

     /// All `expose` declarations as defined in the component manifest.
     exposes vector<fuchsia.component.decl.Expose>:MAX;

     /// The resolved structured configuration of this component instance.
     config box<fuchsia.component.config.ResolvedConfig>;

     /// The package directory containing the component manifest, if one exists.
     /// This directory has the same permissions given by the package resolver
     /// (most likely RO permissions).
     pkg_dir client_end:<fuchsia.io.Directory, optional>;

     /// The information available because the component instance is running.
     /// If this object does not exist, the instance is not running.
     execution box<ExecutionState>;

     /// The directory containing all capabilities exposed by the component.
     /// This directory has RW permissions.
     exposed_dir client_end:<fuchsia.io.Directory>;

     /// The directory representing the component's namespace.
     /// This directory has RW permissions.
     ns_dir client_end:<fuchsia.io.Directory>;
 };

 /// The detailed execution state of a component instance
 @available(added=11, deprecated=11, removed=12, note="Use ExecutionInfo instead")
 type ExecutionState = resource struct {
     /// The outgoing directory of this instance, if one exists.
     out_dir client_end:<fuchsia.io.Directory, optional>;

     /// The debug directory served by the runner of this instance, if one exists.
     runtime_dir client_end:<fuchsia.io.Directory, optional>;

     /// The human-readable explanation for why this instance was started.
     start_reason string:MAX;
 };

 /// The directories available because the component instance is in resolved state
 @available(added=11, deprecated=11, removed=12)
 type ResolvedDirectories = resource struct {
     /// The package directory containing the component manifest, if one exists.
     /// This directory has the same permissions given by the package resolver
     /// (most likely RX permissions).
     pkg_dir client_end:<fuchsia.io.Directory, optional>;

     /// The directory containing all capabilities exposed by the component.
     /// This directory has RW permissions.
     exposed_dir client_end:<fuchsia.io.Directory>;

     /// The directory handles + paths that constitute the component's namespace.
     ns_entries vector<fuchsia.component.runner.ComponentNamespaceEntry>:MAX;

     /// The directories available because the component instance is running.
     /// If this object does not exist, the instance is not running.
     execution_dirs box<ExecutionDirectories>;
 };

 /// The directories available because the component instance is running
 @available(added=11, deprecated=11, removed=12)
 type ExecutionDirectories = resource struct {
     /// The outgoing directory of this instance, if one exists.
     out_dir client_end:<fuchsia.io.Directory, optional>;

     /// The debug directory served by the runner of this instance, if one exists.
     runtime_dir client_end:<fuchsia.io.Directory, optional>;
 };

 /// An iterator over basic information of all instances in the realm
 @available(added=11, deprecated=11, removed=12, note="Use InstanceIterator instead")
 closed protocol InstanceInfoIterator {
     strict Next() -> (struct {
         infos vector<InstanceInfo>:MAX;
     });
 };

 /// Errors that can be returned by the RealmQuery API.
 type RealmQueryError = flexible enum {
     /// Could not find an instance matching the given moniker.
     INSTANCE_NOT_FOUND = 1;

     /// The given moniker could not be parsed.
     BAD_MONIKER = 2;
 };

 /// Errors that can be returned by the RealmExplorer API.
 @available(added=11, deprecated=11, removed=12)
 type RealmExplorerError = flexible enum {
     /// Could not find the scope root instance.
     // TODO(https://fxbug.dev/42059901): Close the connection when this error occurs.
     INSTANCE_NOT_FOUND = 1;
 };

 /// Offers basic introspection into component instances under a realm.
 @discoverable
 closed protocol RealmExplorer {
     /// Returns an iterator over basic information of each instance scoped to this realm.
     /// When the server receives this call, it will take a snapshot of the current component
     /// topology and relays that over the iterator. Any changes to the topology *after* this method
     /// call is received by the server will not be shown by the iterator.
     @available(added=11, deprecated=11, removed=12, note="Use RealmQuery.GetAllInstances instead")
     strict GetAllInstanceInfos() -> (resource struct {
         iterator client_end:InstanceInfoIterator;
     }) error RealmExplorerError;
 };
	// 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.sys2;

	using fuchsia.io;
	using fuchsia.component;
	using fuchsia.component.decl;
	using fuchsia.component.config;
	using fuchsia.component.runner;
	using fuchsia.url;

	/// The maximum length of an instance ID.
	/// An instance ID is a 256-bit identifier, which when encoded
	/// in hex notation is 64 characters long.
	const MAX_INSTANCE_ID_LENGTH uint32 = 64;

	/// The maximum length of the human-readable start reason.
	/// This accounts for StartReason::AccessCapability which can have a length of
	/// MAX_MONIKER_LENGTH + MAX_NAME_LENGTH + 26 (4222 characters).
	const MAX_START_REASON uint32 = 5000;

	/// Errors that can be returned by the GetInstance call.
	type GetInstanceError = flexible enum {
	/// Could not find an instance matching the given moniker.
	INSTANCE_NOT_FOUND = 1;

	/// The given moniker could not be parsed.
	BAD_MONIKER = 2;
	};

	/// Errors that can be returned by the GetManifest call.
	type GetDeclarationError = flexible enum {
	/// Could not find an instance matching the given moniker.
	INSTANCE_NOT_FOUND = 1;

	/// The given moniker could not be parsed.
	BAD_MONIKER = 2;

	/// The component manifest is only available when the instance is resolved.
	INSTANCE_NOT_RESOLVED = 3;

	/// The component manifest could not be encoded into its persistable format.
	ENCODE_FAILED = 4;

	/// The specified collection was not found in the specified component.
	@available(added=12)
	BAD_CHILD_LOCATION = 5;

	/// The specified URL could not be parsed.
	@available(added=12)
	BAD_URL = 6;
	};

	/// Errors that can be returned by the GetStructuredConfig call.
	type GetStructuredConfigError = flexible enum {
	/// Could not find an instance matching the given moniker.
	INSTANCE_NOT_FOUND = 1;

	/// The given moniker could not be parsed.
	BAD_MONIKER = 2;

	/// The component manifest is only available when the instance is resolved.
	INSTANCE_NOT_RESOLVED = 3;

	/// There is no structured configuration associated with this instance.
	NO_CONFIG = 4;
	};

	/// Errors that can be returned by the GetAllInstances call.
	type GetAllInstancesError = flexible enum {
	/// Could not find the scope root instance.
	INSTANCE_NOT_FOUND = 1;
	};

	/// Errors that can be returned by the OpenDirectory call.
	type OpenError = flexible enum {
	/// Could not find an instance matching the given moniker.
	INSTANCE_NOT_FOUND = 1;

	/// The given moniker could not be parsed.
	BAD_MONIKER = 2;

	/// The requested directory is available when the instance is resolved.
	INSTANCE_NOT_RESOLVED = 3;

	/// The requested directory is available when the instance is running.
	///
	/// Deprecation: the platform will stop emitting this error from version 19.
	/// The component will always be started if not already.
	@available(deprecated=19)
	INSTANCE_NOT_RUNNING = 4;

	/// Component manager's open request on the directory returned a FIDL error.
	FIDL_ERROR = 5;

	/// The instance does not have a directory of this type.
	NO_SUCH_DIR = 6;

	/// The given directory type could not be parsed.
	BAD_DIR_TYPE = 7;

	/// The given path could not be parsed by component manager.
	BAD_PATH = 8;

	/// Serving the requested directory requires starting the instance, but the
	/// instance failed to start.
	@available(added=19)
	INSTANCE_FAILED_TO_START = 9;
	};

	/// Errors that can be returned by the ConstructNamespace call.
	type ConstructNamespaceError = flexible enum {
	/// Could not find an instance matching the given moniker.
	INSTANCE_NOT_FOUND = 1;

	/// The given moniker could not be parsed.
	BAD_MONIKER = 2;

	/// Namespace construction requires the instance to be resolved.
	INSTANCE_NOT_RESOLVED = 3;
	};

	/// Errors that can be returned by the ConnectToStorageAdmin call.
	type ConnectToStorageAdminError = flexible enum {
	/// Could not find an instance matching the given moniker.
	INSTANCE_NOT_FOUND = 1;

	/// The given moniker could not be parsed.
	BAD_MONIKER = 2;

	/// The instance does not define a storage capability with the given name.
	STORAGE_NOT_FOUND = 3;

	/// This operation requires the instance to be resolved.
	INSTANCE_NOT_RESOLVED = 4;

	/// The given storage capability could not be parsed.
	BAD_CAPABILITY = 5;
	};

	/// Describes a component instance under a realm.
	///
	/// Note: This structure is expected to fit in a single Zircon channel message.
	/// Do not add fields that have the potential to violate that constraint.
	/// Prefer to create dedicated methods and iterators instead.
	@available(added=11)
	type Instance = table {
	/// The path to this instance relative to the scope root.
	1: moniker string:fuchsia.component.MAX_MONIKER_LENGTH;

	/// The URL of the component manifest for this instance.
	2: url fuchsia.url.Url;

	/// The stable identifier for this instance, if one exists.
	3: instance_id string:<MAX_INSTANCE_ID_LENGTH>;

	/// Information about the resolved state of a component instance.
	/// If the component is not resolved, this field is not set.
	4: resolved_info ResolvedInfo;

	/// The component's environment name as defined by its parent.
	5: environment string:fuchsia.component.MAX_MONIKER_LENGTH;
	};

	/// Information about the resolved state of a component instance.
	@available(added=11)
	type ResolvedInfo = table {
	/// The resolved URL of this instance.
	1: resolved_url fuchsia.url.Url;

	/// Information about the execution state of a component instance.
	/// If the component is not running, this field is not set.
	2: execution_info ExecutionInfo;
	};

	/// Information about the execution state of a component instance.
	@available(added=11)
	type ExecutionInfo = table {
	/// The human-readable explanation for why this instance was started.
	1: start_reason string:MAX_START_REASON;
	};

	/// The directories of an instance that can be opened by component manager.
	@available(added=11)
	type OpenDirType = flexible enum {
	/// Served by the component's program. Rights unknown.
	OUTGOING_DIR = 1;
	/// Served by the component's runner. Rights unknown.
	RUNTIME_DIR = 2;
	/// Served by the component's resolver. Rights unknown.
	PACKAGE_DIR = 3;
	/// Served by component manager. Directory has RW rights.
	EXPOSED_DIR = 4;
	/// Served by component manager. Directory has RW rights.
	NAMESPACE_DIR = 5;
	};

	/// Locations from which a child could be resolved under a given parent.
	type ChildLocation = flexible union {
	1: collection string:fuchsia.component.MAX_NAME_LENGTH;

	// TODO(https://fxbug.dev/42077932) support static children
	};

	/// Offers detailed introspection into component instances under a realm.
	@discoverable
	closed protocol RealmQuery {
	/// Gets an instance identified by its moniker.
	@available(added=11)
	strict GetInstance(struct {
	moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
	}) -> (struct {
	instance Instance;
	}) error GetInstanceError;

	/// Gets the manifest of an instance identified by its moniker.
	///
	/// The manifest is encoded in its standalone persistable format per RFC-0120 and
	/// is sent across using an iterator. Some manifests are too large to send over a
	/// Zircon channel and we can't use a VMO because we need an approach that is
	/// compatible with overnet.
	@available(added=13)
	strict GetResolvedDeclaration(struct {
	moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
	}) -> (resource struct {
	iterator client_end:ManifestBytesIterator;
	}) error GetDeclarationError;

	// TODO(https://fxbug.dev/42077935) delete once no longer required for ffx compat window
	/// Prefer `GetResolvedDeclaration` if available for your target API level.
	@available(added=11)
	strict GetManifest(struct {
	moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
	}) -> (resource struct {
	iterator client_end:ManifestBytesIterator;
	}) error GetDeclarationError;

	/// Gets the manifest of a component URL as if it were a child of the specified parent
	/// without actually creating or starting that component.
	///
	/// The manifest is encoded in its standalone persistable format per RFC-0120 and
	/// is sent across using an iterator. Some manifests are too large to send over a
	/// Zircon channel and we can't use a VMO because we need an approach that is
	/// compatible with overnet.
	@available(added=12)
	strict ResolveDeclaration(struct {
	parent string:fuchsia.component.MAX_MONIKER_LENGTH;
	child_location ChildLocation;
	url fuchsia.url.Url;
	}) -> (resource struct {
	iterator client_end:ManifestBytesIterator;
	}) error GetDeclarationError;

	/// Gets the structured config of an instance identified by its moniker.
	@available(added=13)
	strict GetStructuredConfig(struct {
	moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
	}) -> (struct {
	config fuchsia.component.decl.ResolvedConfig;
	}) error GetStructuredConfigError;

	// replaced by ABI-compatible version above
	@available(added=11, replaced=13)
	strict GetStructuredConfig(struct {
	moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
	}) -> (struct {
	config fuchsia.component.config.ResolvedConfig;
	}) error GetStructuredConfigError;

	/// Returns an iterator over all component instances in this realm and instances within resolved
	/// children, recursively. Unresolved child components will be included in this list, but
	/// children of unresolved children will not be.
	@available(added=11)
	strict GetAllInstances() -> (resource struct {
	iterator client_end:InstanceIterator;
	}) error GetAllInstancesError;

	/// Constructs the namespace of an instance as determined by its use declarations.
	/// This is usually identical to what would be given to the component's runner on
	/// component start time, unless extended by
	/// `fuchsia.component/StartChildArgs.namespace_entries`.
	@available(added=11)
	strict ConstructNamespace(struct {
	moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
	}) -> (resource struct {
	/// The directory handles + paths that constitute the component's namespace.
	namespace vector<fuchsia.component.runner.ComponentNamespaceEntry>:MAX;
	}) error ConstructNamespaceError;

	/// Makes an fuchsia.io.Directory/Open call on a directory in an instance.
	@available(added=11)
	strict Open(resource struct {
	moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
	dir_type OpenDirType;
	flags fuchsia.io.OpenFlags;
	mode fuchsia.io.ModeType;
	path string:fuchsia.io.MAX_PATH_LENGTH;
	object server_end:fuchsia.io.Node;
	}) -> () error OpenError;

	/// Connects to the StorageAdmin protocol of a storage declared by an instance.
	@available(added=11)
	strict ConnectToStorageAdmin(resource struct {
	moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
	storage_name fuchsia.component.decl.name;
	server_end server_end:StorageAdmin;
	}) -> () error ConnectToStorageAdminError;

	/// Gets the detailed information of a particular instance identified by its moniker.
	/// This response contains handles to resources of the instance. As a result, component manager
	/// pays a non-trivial cost when this method is invoked.
	@available(added=11, deprecated=11, removed=12, note="Use GetInstance instead")
	strict GetInstanceInfo(struct {
	moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
	}) -> (resource struct {
	/// Basic information about the component instance.
	info InstanceInfo;

	/// Detailed information about the resolved component instance.
	/// If this object does not exist, the instance is not resolved.
	resolved box<ResolvedState>;
	}) error RealmQueryError;

	/// Gets all directories relevant to a particular instance identified by its moniker.
	/// This response contains directory handles served by component manager. As a result,
	/// component manager pays a non-trivial cost when this method is invoked.
	@available(added=11, deprecated=11, removed=12, note="Use Open instead")
	strict GetInstanceDirectories(struct {
	moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
	}) -> (resource struct {
	/// The directories available because the component instance is in resolved state
	/// If this object does not exist, the instance is not resolved.
	resolved_dirs box<ResolvedDirectories>;
	}) error RealmQueryError;
	};

	/// An iterator over all instances in the realm
	@available(added=11)
	closed protocol InstanceIterator {
	strict Next() -> (struct {
	infos vector<Instance>:MAX;
	});
	};

	/// An iterator over the bytes of an instance's manifest
	@available(added=11)
	closed protocol ManifestBytesIterator {
	strict Next() -> (struct {
	infos vector<uint8>:MAX;
	});
	};

	// ------------------------------------------------------------
	// All types below are marked deprecated and will be removed in
	// a newer API version.
	// ------------------------------------------------------------

	/// Describes the current state of instance
	@available(added=11, deprecated=11, removed=12)
	type InstanceState = strict enum {
	/// The component is created, but has not been resolved by component manager.
	/// Most information about this component is unknown.
	UNRESOLVED = 0;

	/// The component has been resolved by component manager but is not currently running.
	RESOLVED = 1;

	/// The component has been resolved and started by component manager. It is currently running.
	STARTED = 2;
	};

	/// Basic information about a component instance.
	/// This object contains information that is readily available to component manager.
	@available(added=11, deprecated=11, removed=12, note="Use Instance instead")
	type InstanceInfo = struct {
	/// The path to this instance relative to the scope root.
	moniker string:fuchsia.component.MAX_MONIKER_LENGTH;

	/// The URL of the component manifest for this instance.
	url fuchsia.url.Url;

	/// The stable identifier for this instance.
	instance_id string:<MAX_INSTANCE_ID_LENGTH, optional>;

	/// The current state of this instance.
	state InstanceState;
	};

	/// The detailed resolved state of a component instance
	@available(added=11, deprecated=11, removed=12, note="Use ResolvedInfo instead")
	type ResolvedState = resource struct {
	/// All `use` declarations as defined in the component manifest.
	uses vector<fuchsia.component.decl.Use>:MAX;

	/// All `expose` declarations as defined in the component manifest.
	exposes vector<fuchsia.component.decl.Expose>:MAX;

	/// The resolved structured configuration of this component instance.
	config box<fuchsia.component.config.ResolvedConfig>;

	/// The package directory containing the component manifest, if one exists.
	/// This directory has the same permissions given by the package resolver
	/// (most likely RO permissions).
	pkg_dir client_end:<fuchsia.io.Directory, optional>;

	/// The information available because the component instance is running.
	/// If this object does not exist, the instance is not running.
	execution box<ExecutionState>;

	/// The directory containing all capabilities exposed by the component.
	/// This directory has RW permissions.
	exposed_dir client_end:<fuchsia.io.Directory>;

	/// The directory representing the component's namespace.
	/// This directory has RW permissions.
	ns_dir client_end:<fuchsia.io.Directory>;
	};

	/// The detailed execution state of a component instance
	@available(added=11, deprecated=11, removed=12, note="Use ExecutionInfo instead")
	type ExecutionState = resource struct {
	/// The outgoing directory of this instance, if one exists.
	out_dir client_end:<fuchsia.io.Directory, optional>;

	/// The debug directory served by the runner of this instance, if one exists.
	runtime_dir client_end:<fuchsia.io.Directory, optional>;

	/// The human-readable explanation for why this instance was started.
	start_reason string:MAX;
	};

	/// The directories available because the component instance is in resolved state
	@available(added=11, deprecated=11, removed=12)
	type ResolvedDirectories = resource struct {
	/// The package directory containing the component manifest, if one exists.
	/// This directory has the same permissions given by the package resolver
	/// (most likely RX permissions).
	pkg_dir client_end:<fuchsia.io.Directory, optional>;

	/// The directory containing all capabilities exposed by the component.
	/// This directory has RW permissions.
	exposed_dir client_end:<fuchsia.io.Directory>;

	/// The directory handles + paths that constitute the component's namespace.
	ns_entries vector<fuchsia.component.runner.ComponentNamespaceEntry>:MAX;

	/// The directories available because the component instance is running.
	/// If this object does not exist, the instance is not running.
	execution_dirs box<ExecutionDirectories>;
	};

	/// The directories available because the component instance is running
	@available(added=11, deprecated=11, removed=12)
	type ExecutionDirectories = resource struct {
	/// The outgoing directory of this instance, if one exists.
	out_dir client_end:<fuchsia.io.Directory, optional>;

	/// The debug directory served by the runner of this instance, if one exists.
	runtime_dir client_end:<fuchsia.io.Directory, optional>;
	};

	/// An iterator over basic information of all instances in the realm
	@available(added=11, deprecated=11, removed=12, note="Use InstanceIterator instead")
	closed protocol InstanceInfoIterator {
	strict Next() -> (struct {
	infos vector<InstanceInfo>:MAX;
	});
	};

	/// Errors that can be returned by the RealmQuery API.
	type RealmQueryError = flexible enum {
	/// Could not find an instance matching the given moniker.
	INSTANCE_NOT_FOUND = 1;

	/// The given moniker could not be parsed.
	BAD_MONIKER = 2;
	};

	/// Errors that can be returned by the RealmExplorer API.
	@available(added=11, deprecated=11, removed=12)
	type RealmExplorerError = flexible enum {
	/// Could not find the scope root instance.
	// TODO(https://fxbug.dev/42059901): Close the connection when this error occurs.
	INSTANCE_NOT_FOUND = 1;
	};

	/// Offers basic introspection into component instances under a realm.
	@discoverable
	closed protocol RealmExplorer {
	/// Returns an iterator over basic information of each instance scoped to this realm.
	/// When the server receives this call, it will take a snapshot of the current component
	/// topology and relays that over the iterator. Any changes to the topology after this method
	/// call is received by the server will not be shown by the iterator.
	@available(added=11, deprecated=11, removed=12, note="Use RealmQuery.GetAllInstances instead")
	strict GetAllInstanceInfos() -> (resource struct {
	iterator client_end:InstanceInfoIterator;
	}) error RealmExplorerError;
	};