sdk/fidl/fuchsia.component.test/realm_builder.fidl - fuchsia - Git at Google

 // Copyright 2021 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.test;

 using fuchsia.component;
 using fuchsia.component.decl;
 using fuchsia.component.runner;
 using fuchsia.component.types;
 using fuchsia.data;
 using fuchsia.mem;
 using fuchsia.io;
 using fuchsia.url;

 // The Realm Builder Server will include a local component's name in its
 // program dictionary under this string. Clients should use this value when
 // extracting a local component's name.
 const LOCAL_COMPONENT_NAME_KEY string = "LOCAL_COMPONENT_NAME";

 /// This protocol can be used to instruct the Realm Builder Server to begin
 /// creating a new realm.
 @discoverable
 protocol RealmBuilderFactory {
     /// Creates a new RealmBuilder. The client end of `realm_server_end` can be
     /// used to mutate the realm that is being constructed, by doing things such
     /// as adding new children to the realm or adding capability routes between
     /// them. The client end of `builder_server_end` is used to finalize the
     /// realm, after which point it can be launched in a collection.
     Create(resource struct {
         pkg_dir_handle client_end:fuchsia.io.Directory;
         realm_server_end server_end:Realm;
         builder_server_end server_end:Builder;
     }) -> ();

     /// Identical to `Create`, but instead of the realm being empty by default
     /// it contains the contents of the manifest located at `relative_url`
     /// within `pkg_dir_handle`.
     CreateFromRelativeUrl(resource struct {
         pkg_dir_handle client_end:fuchsia.io.Directory;
         relative_url fuchsia.url.Url;
         realm_server_end server_end:Realm;
         builder_server_end server_end:Builder;
     }) -> (struct {}) error RealmBuilderError2;
 };

 /// Errors that may be returned by the `Realm` and `Builder` protocols.
 ///
 /// Will be renamed to `RealmBuilderError` once the other definition under this
 /// name earlier in this file is removed.
 type RealmBuilderError2 = strict enum : uint32 {
     /// Child cannot be added to the realm, as there is already a child in the
     /// realm with that name.
     CHILD_ALREADY_EXISTS = 0;

     /// A legacy component URL was given to `AddChild`, or a modern component
     /// url was given to `AddLegacyChild`.
     INVALID_MANIFEST_EXTENSION = 1;

     /// A component declaration failed validation.
     INVALID_COMPONENT_DECL = 2;

     /// The referenced child does not exist.
     NO_SUCH_CHILD = 3;

     /// The component declaration for the referenced child cannot be viewed nor
     /// manipulated by RealmBuilder, because the child was added to the realm
     /// using an URL that was neither a relative nor a legacy URL.
     CHILD_DECL_NOT_VISIBLE = 4;

     /// The source does not exist.
     NO_SUCH_SOURCE = 5;

     /// A target does not exist.
     NO_SUCH_TARGET = 6;

     /// The `capabilities` field is empty.
     CAPABILITIES_EMPTY = 7;

     /// The `targets` field is empty.
     TARGETS_EMPTY = 8;

     /// The `from` value is equal to one of the elements in `to`.
     SOURCE_AND_TARGET_MATCH = 9;

     /// The test package does not contain the component declaration referenced
     /// by a relative URL.
     DECL_NOT_FOUND = 10;

     /// Encountered an I/O error when attempting to read a component declaration
     /// referenced by a relative URL from the test package.
     DECL_READ_ERROR = 11;

     /// The `Build` function has been called multiple times on this channel.
     BUILD_ALREADY_CALLED = 12;

     /// A capability is invalid. This may occur if a required field is empty or
     /// if an unsupported type is received.
     CAPABILITY_INVALID = 13;

     /// The handle the client provided for the child realm is not usable.
     INVALID_CHILD_REALM_HANDLE = 14;

     /// `ReplaceComponentDecl` was called on a legacy or local component with a
     /// program declaration that did not match the one from the old component
     /// declaration. This could render a legacy or local component
     /// non-functional, and is disallowed.
     IMMUTABLE_PROGRAM = 15;

     /// The URL provided to `RealmBuilderFactory.CreateFromRelativeURL` is not a
     /// relative URL.
     URL_IS_NOT_RELATIVE = 16;

     /// The handle the client provided for the test's pkg directory is not
     /// usable.
     INVALID_PKG_DIR_HANDLE = 17;
 };

 protocol Builder {
     /// Assembles the realm being constructed and returns the URL for the root
     /// component in the realm, which may then be used to create a new component
     /// in any collection where fuchsia-test-component is properly set up. Once
     /// this is called, any Realm channels for the realm will no longer be
     /// usable. The `runner` argument must be provided if the `AddLocalChild`
     /// function has been used in this realm, as this runner channel will be
     /// used to inform the client when to start and stop running any local
     /// component implementations.
     ///
     /// Errors:
     /// - `INVALID_COMPONENT_DECL`: A component declaration failed validaiton.
     /// - `BUILD_ALREADY_CALLED`: The `Build` function has been called multiple
     ///   times on this channel.
     Build(resource struct {
         runner client_end:fuchsia.component.runner.ComponentRunner;
     }) -> (struct {
         root_component_url string:fuchsia.component.types.MAX_URL_LENGTH;
     }) error RealmBuilderError2;
 };

 /// A capability that can be routed around a realm using `AddRoute`.
 ///
 /// Will be renamed to `Capability` once the other definition under this name
 /// earlier in this file is removed.
 type Capability2 = flexible union {
     1: protocol Protocol;
     2: directory Directory;
     3: storage Storage;
     4: service Service;
     5: event Event;
 };

 /// A protocol capability
 type Protocol = table {
     1: name fuchsia.component.name;
     2: as fuchsia.component.name; // optional
     3: type fuchsia.component.decl.DependencyType; // optional
     4: path string:fuchsia.component.MAX_PATH_LENGTH; // optional
 };

 /// A directory capability
 type Directory = table {
     1: name fuchsia.component.name;
     2: as fuchsia.component.name; // optional
     3: type fuchsia.component.decl.DependencyType; // optional
     4: subdir string:fuchsia.component.MAX_PATH_LENGTH; // optional

     // the following fields are required if `to` contains a local component
     5: rights fuchsia.io.Rights;
     6: path string:fuchsia.component.MAX_PATH_LENGTH;
 };

 /// A storage capability
 type Storage = table {
     1: name fuchsia.component.name;
     2: as fuchsia.component.name; // optional

     // required if `to` contains a local component
     3: path fuchsia.component.name;
 };

 /// A service capability
 type Service = table {
     1: name fuchsia.component.name;
     2: as fuchsia.component.name; // optional

     // required if `to` contains a local component
     3: path string:fuchsia.component.MAX_PATH_LENGTH;
 };

 /// An event capability
 type Event = table {
     1: name fuchsia.component.name;
     2: as fuchsia.component.name; // optional
     3: filter fuchsia.data.Dictionary;
 };

 /// Properties that may be set on a child when it is added to a realm
 type ChildOptions = table {
     1: startup fuchsia.component.decl.StartupMode;
     2: environment fuchsia.component.name;
     3: on_terminate fuchsia.component.decl.OnTerminate;
 };

 const MAX_DIRECTORY_ENTRIES uint32 = 1024;

 /// The contents of a directory that should be provided by the realm builder
 /// server.
 type DirectoryContents = resource struct {
     entries vector<DirectoryEntry>:MAX_DIRECTORY_ENTRIES;
 };

 type DirectoryEntry = resource struct {
     /// The path to the file. Valid examples include `foo.txt` and
     /// `foo/bar.json`.
     file_path fuchsia.component.name;

     /// The contents of the file.
     file_contents fuchsia.mem.Buffer;
 };

 protocol Realm {
     /// Adds a component to the realm.
     ///
     /// Errors:
     /// - `CHILD_ALREADY_EXISTS`: this realm already contains a child with the
     ///   given name.
     /// - `INVALID_MANIFEST_EXTENSION`: `url` ends with `.cmx`, and thus should
     ///   be used with `AddLegacyChild` instead of `AddChild`.
     /// - `DECL_NOT_FOUND`: The test package does not contain the component
     ///   declaration referenced by a relative URL.
     /// - `DECL_READ_ERROR`: Encountered an I/O error when attempting to read a
     ///   component declaration referenced by a relative URL from the test
     ///   package.
     /// - `BUILD_ALREADY_CALLED`: The `Builder.Build` function has been called
     ///   for this realm, and thus this `Realm` channel can no longer be used.
     AddChild(struct {
         /// The name of the child that is being added.
         name fuchsia.component.name;

         /// The component's URL.
         url fuchsia.url.Url;

         /// Additional properties for the child.
         options ChildOptions;
     }) -> (struct {}) error RealmBuilderError2;

     /// Adds a [legacy
     /// component](https://fuchsia.dev/fuchsia-src/concepts/components/v1) to
     /// the realm. When the component is launched, RealmBuilder will reach out
     /// to appmgr to assist with launching the component, and the component will
     /// be able to utilize all of the features of the legacy component
     /// framework. Note that _only_ protocol capabilities may be routed to this
     /// component. Capabilities of any other type (such as a directory) are
     /// unsupported for legacy components launched by RealmBuilder, and this
     /// legacy component should instead use the CMX features to access things
     /// such as storage.
     ///
     /// Errors:
     /// - `CHILD_ALREADY_EXISTS`: this realm already contains a child with the
     ///   given name.
     /// - `INVALID_MANIFEST_EXTENSION`: `url` does not end with `.cmx`, and thus
     ///   should be used with `AddChild` instead of `AddLegacyChild`.
     /// - `BUILD_ALREADY_CALLED`: The `Builder.Build` function has been called
     ///   for this realm, and thus this `Realm` channel can no longer be used.
     AddLegacyChild(struct {
         /// The name of the child that is being added.
         name fuchsia.component.name;

         /// The component's legacy URL (commonly ends with `.cmx`).
         legacy_url fuchsia.url.Url;

         /// Additional properties for the child.
         options ChildOptions;
     }) -> (struct {}) error RealmBuilderError2;

     /// Adds a component to this realm whose declaration is set to `decl`. When
     /// launched, the component will share the test package as its package
     /// directory, and may access any resources from it.
     ///
     /// Errors:
     /// - `CHILD_ALREADY_EXISTS`: this realm already contains a child with the
     ///   given name.
     /// - `INVALID_COMPONENT_DECL`: `decl` failed validation.
     /// - `BUILD_ALREADY_CALLED`: The `Builder.Build` function has been called
     ///   for this realm, and thus this `Realm` channel can no longer be used.
     AddChildFromDecl(struct {
         /// The name of the child that is being added.
         name fuchsia.component.name;

         /// The component's declaration.
         decl fuchsia.component.decl.Component;

         /// Additional properties for the child.
         options ChildOptions;
     }) -> (struct {}) error RealmBuilderError2;

     /// Adds a component to the realm whose implementation will be provided by
     /// the client. When this component should be started, the runner channel
     /// passed into `Build` will receive a start request for a component whose
     /// `ProgramDecl` contains the relative moniker from the root of the
     /// constructed realm for the child that is to be run under the `program`
     /// key `LOCAL_COMPONENT_NAME`.
     ///
     /// Errors:
     /// - `CHILD_ALREADY_EXISTS`: this realm already contains a child with the
     ///   given name.
     /// - `BUILD_ALREADY_CALLED`: The `Builder.Build` function has been called
     ///   for this realm, and thus this `Realm` channel can no longer be used.
     AddLocalChild(struct {
         /// The name of the child that is being added.
         name fuchsia.component.name;

         /// Additional properties for the child.
         options ChildOptions;
     }) -> (struct {}) error RealmBuilderError2;

     /// Adds a child realm which can be built with the client end of
     /// `child_realm`.
     ///
     /// Errors:
     /// - `CHILD_ALREADY_EXISTS`: this realm already contains a child with the
     ///   given name.
     /// - `BUILD_ALREADY_CALLED`: The `Builder.Build` function has been called
     ///   for this realm, and thus this `Realm` channel can no longer be used.
     AddChildRealm(resource struct {
         /// The name of the child realm that is being added.
         name fuchsia.component.name;

         /// Additional properties for the child.
         options ChildOptions;

         /// The server end of the `Realm` channel that will be used to build the
         /// sub-realm.
         child_realm server_end:Realm;
     }) -> (struct {}) error RealmBuilderError2;

     /// Returns the component decl for the given component. `name` must refer to
     /// a component that is one of the following:
     ///
     /// - A component with a local implementation
     /// - A legacy component
     /// - A component added with a relative URL
     /// - An automatically generated realm (ex: the root)
     ///
     /// Errors:
     /// - `NO_SUCH_CHILD`: This realm does not contain a child with the given
     ///   name.
     /// - `CHILD_DECL_NOT_VISIBLE`: The component decl cannot be fetched for
     ///   the referenced child, because the child was added to the realm using
     ///   an absolute (not-relative) and modern (not legacy) URL.
     /// - `BUILD_ALREADY_CALLED`: The `Builder.Build` function has been called
     ///   for this realm, and thus this `Realm` channel can no longer be used.
     GetComponentDecl(struct {
         /// The name of the component whose declaration is being retrieved.
         name fuchsia.component.name;
     }) -> (struct {
         component_decl fuchsia.component.decl.Component;
     }) error RealmBuilderError2;

     /// Replaces the component decl for the given component. `name` must
     /// refer to a component that is one of the following:
     ///
     /// - A component with a local implementation
     /// - A legacy component
     /// - A component added with a relative URL
     /// - An automatically generated realm (ex: the root)
     ///
     /// Errors:
     /// - `NO_SUCH_CHILD`: This realm does not contain a child with the given
     ///   name.
     /// - `CHILD_ALREADY_EXISTS`: The component whose decl is being replaced has
     ///   had a child added to it through realm builder with the same name as an
     ///   element in `component_decl.children`.
     /// - `CHILD_DECL_NOT_VISIBLE`: The component decl cannot be manipulated for
     ///   the referenced child, because the child was added to the realm using
     ///   an absolute (not relative) and modern (not legacy) URL.
     /// - `INVALID_COMPONENT_DECL`: `component_decl` failed validation.
     /// - `BUILD_ALREADY_CALLED`: The `Builder.Build` function has been called
     ///   for this realm, and thus this `Realm` channel can no longer be used.
     ReplaceComponentDecl(struct {
         /// The name of the component whose declaration is being replaced.
         name fuchsia.component.name;

         /// The new component declaration for `name`.
         component_decl fuchsia.component.decl.Component;
     }) -> (struct {}) error RealmBuilderError2;

     /// Returns the component decl for this realm.
     ///
     /// Errors:
     /// - `BUILD_ALREADY_CALLED`: The `Builder.Build` function has been called
     ///   for this realm, and thus this `Realm` channel can no longer be used.
     GetRealmDecl() -> (struct {
         component_decl fuchsia.component.decl.Component;
     }) error RealmBuilderError2;

     /// Replaces the component decl for this realm.
     ///
     /// Errors:
     /// - `INVALID_COMPONENT_DECL`: `component_decl` failed validation.
     /// - `BUILD_ALREADY_CALLED`: The `Builder.Build` function has been called
     ///   for this realm, and thus this `Realm` channel can no longer be used.
     ReplaceRealmDecl(struct {
         /// The new component declaration for this realm.
         component_decl fuchsia.component.decl.Component;
     }) -> (struct {}) error RealmBuilderError2;

     /// Mutates component manifests in the realm such that every component in
     /// `to` will have a valid capability route for each item in `capabilities`
     /// provided by `from`.
     ///
     /// Errors:
     /// - `NO_SUCH_SOURCE`: `from` references a non-existent child.
     /// - `NO_SUCH_TARGET`: `to` references a non-existent child.
     /// - `CAPABILITIES_EMPTY`: `capabilities` is empty.
     /// - `TARGETS_EMPTY`: `to` is empty.
     /// - `SOURCE_AND_TARGET_MATCH`: `from` is equal to one of the elements in
     ///   `to`.
     /// - `INVALID_COMPONENT_DECL`: The requested route caused one of the
     ///   involved manifests to fail validation.
     /// - `BUILD_ALREADY_CALLED`: The `Builder.Build` function has been called
     ///   for this realm, and thus this `Realm` channel can no longer be used.
     AddRoute(struct {
         /// The capabilities that are to be routed.
         capabilities vector<Capability2>:MAX;

         /// The location where the elements of `capabilities` are available.
         from fuchsia.component.decl.Ref;

         /// The locations that should be able to access `capabilities`.
         to vector<fuchsia.component.decl.Ref>:MAX;
     }) -> (struct {}) error RealmBuilderError2;

     /// Offers a directory capability to a component in this realm. The
     /// directory will be read-only (i.e. have `r*` rights), and will have the
     /// contents described in `directory_contents`.
     ///
     /// Errors:
     /// - `NO_SUCH_TARGET`: `offer-to` references a non-existent child.
     /// - `BUILD_ALREADY_CALLED`: The `Builder.Build` function has been called
     ///   for this realm, and thus this `Realm` channel can no longer be used.
     ReadOnlyDirectory(resource struct {
         /// The name of the directory capability.
         name fuchsia.component.name;

         /// The target that this directory will be offered to.
         to vector<fuchsia.component.decl.Ref>:MAX;

         /// The contents of the directory.
         directory_contents DirectoryContents;
     }) -> (struct {}) error RealmBuilderError2;
 };
	// Copyright 2021 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.test;

	using fuchsia.component;
	using fuchsia.component.decl;
	using fuchsia.component.runner;
	using fuchsia.component.types;
	using fuchsia.data;
	using fuchsia.mem;
	using fuchsia.io;
	using fuchsia.url;

	// The Realm Builder Server will include a local component's name in its
	// program dictionary under this string. Clients should use this value when
	// extracting a local component's name.
	const LOCAL_COMPONENT_NAME_KEY string = "LOCAL_COMPONENT_NAME";

	/// This protocol can be used to instruct the Realm Builder Server to begin
	/// creating a new realm.
	@discoverable
	protocol RealmBuilderFactory {
	/// Creates a new RealmBuilder. The client end of `realm_server_end` can be
	/// used to mutate the realm that is being constructed, by doing things such
	/// as adding new children to the realm or adding capability routes between
	/// them. The client end of `builder_server_end` is used to finalize the
	/// realm, after which point it can be launched in a collection.
	Create(resource struct {
	pkg_dir_handle client_end:fuchsia.io.Directory;
	realm_server_end server_end:Realm;
	builder_server_end server_end:Builder;
	}) -> ();

	/// Identical to `Create`, but instead of the realm being empty by default
	/// it contains the contents of the manifest located at `relative_url`
	/// within `pkg_dir_handle`.
	CreateFromRelativeUrl(resource struct {
	pkg_dir_handle client_end:fuchsia.io.Directory;
	relative_url fuchsia.url.Url;
	realm_server_end server_end:Realm;
	builder_server_end server_end:Builder;
	}) -> (struct {}) error RealmBuilderError2;
	};

	/// Errors that may be returned by the `Realm` and `Builder` protocols.
	///
	/// Will be renamed to `RealmBuilderError` once the other definition under this
	/// name earlier in this file is removed.
	type RealmBuilderError2 = strict enum : uint32 {
	/// Child cannot be added to the realm, as there is already a child in the
	/// realm with that name.
	CHILD_ALREADY_EXISTS = 0;

	/// A legacy component URL was given to `AddChild`, or a modern component
	/// url was given to `AddLegacyChild`.
	INVALID_MANIFEST_EXTENSION = 1;

	/// A component declaration failed validation.
	INVALID_COMPONENT_DECL = 2;

	/// The referenced child does not exist.
	NO_SUCH_CHILD = 3;

	/// The component declaration for the referenced child cannot be viewed nor
	/// manipulated by RealmBuilder, because the child was added to the realm
	/// using an URL that was neither a relative nor a legacy URL.
	CHILD_DECL_NOT_VISIBLE = 4;

	/// The source does not exist.
	NO_SUCH_SOURCE = 5;

	/// A target does not exist.
	NO_SUCH_TARGET = 6;

	/// The `capabilities` field is empty.
	CAPABILITIES_EMPTY = 7;

	/// The `targets` field is empty.
	TARGETS_EMPTY = 8;

	/// The `from` value is equal to one of the elements in `to`.
	SOURCE_AND_TARGET_MATCH = 9;

	/// The test package does not contain the component declaration referenced
	/// by a relative URL.
	DECL_NOT_FOUND = 10;

	/// Encountered an I/O error when attempting to read a component declaration
	/// referenced by a relative URL from the test package.
	DECL_READ_ERROR = 11;

	/// The `Build` function has been called multiple times on this channel.
	BUILD_ALREADY_CALLED = 12;

	/// A capability is invalid. This may occur if a required field is empty or
	/// if an unsupported type is received.
	CAPABILITY_INVALID = 13;

	/// The handle the client provided for the child realm is not usable.
	INVALID_CHILD_REALM_HANDLE = 14;

	/// `ReplaceComponentDecl` was called on a legacy or local component with a
	/// program declaration that did not match the one from the old component
	/// declaration. This could render a legacy or local component
	/// non-functional, and is disallowed.
	IMMUTABLE_PROGRAM = 15;

	/// The URL provided to `RealmBuilderFactory.CreateFromRelativeURL` is not a
	/// relative URL.
	URL_IS_NOT_RELATIVE = 16;

	/// The handle the client provided for the test's pkg directory is not
	/// usable.
	INVALID_PKG_DIR_HANDLE = 17;
	};

	protocol Builder {
	/// Assembles the realm being constructed and returns the URL for the root
	/// component in the realm, which may then be used to create a new component
	/// in any collection where fuchsia-test-component is properly set up. Once
	/// this is called, any Realm channels for the realm will no longer be
	/// usable. The `runner` argument must be provided if the `AddLocalChild`
	/// function has been used in this realm, as this runner channel will be
	/// used to inform the client when to start and stop running any local
	/// component implementations.
	///
	/// Errors:
	/// - `INVALID_COMPONENT_DECL`: A component declaration failed validaiton.
	/// - `BUILD_ALREADY_CALLED`: The `Build` function has been called multiple
	/// times on this channel.
	Build(resource struct {
	runner client_end:fuchsia.component.runner.ComponentRunner;
	}) -> (struct {
	root_component_url string:fuchsia.component.types.MAX_URL_LENGTH;
	}) error RealmBuilderError2;
	};

	/// A capability that can be routed around a realm using `AddRoute`.
	///
	/// Will be renamed to `Capability` once the other definition under this name
	/// earlier in this file is removed.
	type Capability2 = flexible union {
	1: protocol Protocol;
	2: directory Directory;
	3: storage Storage;
	4: service Service;
	5: event Event;
	};

	/// A protocol capability
	type Protocol = table {
	1: name fuchsia.component.name;
	2: as fuchsia.component.name; // optional
	3: type fuchsia.component.decl.DependencyType; // optional
	4: path string:fuchsia.component.MAX_PATH_LENGTH; // optional
	};

	/// A directory capability
	type Directory = table {
	1: name fuchsia.component.name;
	2: as fuchsia.component.name; // optional
	3: type fuchsia.component.decl.DependencyType; // optional
	4: subdir string:fuchsia.component.MAX_PATH_LENGTH; // optional

	// the following fields are required if `to` contains a local component
	5: rights fuchsia.io.Rights;
	6: path string:fuchsia.component.MAX_PATH_LENGTH;
	};

	/// A storage capability
	type Storage = table {
	1: name fuchsia.component.name;
	2: as fuchsia.component.name; // optional

	// required if `to` contains a local component
	3: path fuchsia.component.name;
	};

	/// A service capability
	type Service = table {
	1: name fuchsia.component.name;
	2: as fuchsia.component.name; // optional

	// required if `to` contains a local component
	3: path string:fuchsia.component.MAX_PATH_LENGTH;
	};

	/// An event capability
	type Event = table {
	1: name fuchsia.component.name;
	2: as fuchsia.component.name; // optional
	3: filter fuchsia.data.Dictionary;
	};

	/// Properties that may be set on a child when it is added to a realm
	type ChildOptions = table {
	1: startup fuchsia.component.decl.StartupMode;
	2: environment fuchsia.component.name;
	3: on_terminate fuchsia.component.decl.OnTerminate;
	};

	const MAX_DIRECTORY_ENTRIES uint32 = 1024;

	/// The contents of a directory that should be provided by the realm builder
	/// server.
	type DirectoryContents = resource struct {
	entries vector<DirectoryEntry>:MAX_DIRECTORY_ENTRIES;
	};

	type DirectoryEntry = resource struct {
	/// The path to the file. Valid examples include `foo.txt` and
	/// `foo/bar.json`.
	file_path fuchsia.component.name;

	/// The contents of the file.
	file_contents fuchsia.mem.Buffer;
	};

	protocol Realm {
	/// Adds a component to the realm.
	///
	/// Errors:
	/// - `CHILD_ALREADY_EXISTS`: this realm already contains a child with the
	/// given name.
	/// - `INVALID_MANIFEST_EXTENSION`: `url` ends with `.cmx`, and thus should
	/// be used with `AddLegacyChild` instead of `AddChild`.
	/// - `DECL_NOT_FOUND`: The test package does not contain the component
	/// declaration referenced by a relative URL.
	/// - `DECL_READ_ERROR`: Encountered an I/O error when attempting to read a
	/// component declaration referenced by a relative URL from the test
	/// package.
	/// - `BUILD_ALREADY_CALLED`: The `Builder.Build` function has been called
	/// for this realm, and thus this `Realm` channel can no longer be used.
	AddChild(struct {
	/// The name of the child that is being added.
	name fuchsia.component.name;

	/// The component's URL.
	url fuchsia.url.Url;

	/// Additional properties for the child.
	options ChildOptions;
	}) -> (struct {}) error RealmBuilderError2;

	/// Adds a [legacy
	/// component](https://fuchsia.dev/fuchsia-src/concepts/components/v1) to
	/// the realm. When the component is launched, RealmBuilder will reach out
	/// to appmgr to assist with launching the component, and the component will
	/// be able to utilize all of the features of the legacy component
	/// framework. Note that _only_ protocol capabilities may be routed to this
	/// component. Capabilities of any other type (such as a directory) are
	/// unsupported for legacy components launched by RealmBuilder, and this
	/// legacy component should instead use the CMX features to access things
	/// such as storage.
	///
	/// Errors:
	/// - `CHILD_ALREADY_EXISTS`: this realm already contains a child with the
	/// given name.
	/// - `INVALID_MANIFEST_EXTENSION`: `url` does not end with `.cmx`, and thus
	/// should be used with `AddChild` instead of `AddLegacyChild`.
	/// - `BUILD_ALREADY_CALLED`: The `Builder.Build` function has been called
	/// for this realm, and thus this `Realm` channel can no longer be used.
	AddLegacyChild(struct {
	/// The name of the child that is being added.
	name fuchsia.component.name;

	/// The component's legacy URL (commonly ends with `.cmx`).
	legacy_url fuchsia.url.Url;

	/// Additional properties for the child.
	options ChildOptions;
	}) -> (struct {}) error RealmBuilderError2;

	/// Adds a component to this realm whose declaration is set to `decl`. When
	/// launched, the component will share the test package as its package
	/// directory, and may access any resources from it.
	///
	/// Errors:
	/// - `CHILD_ALREADY_EXISTS`: this realm already contains a child with the
	/// given name.
	/// - `INVALID_COMPONENT_DECL`: `decl` failed validation.
	/// - `BUILD_ALREADY_CALLED`: The `Builder.Build` function has been called
	/// for this realm, and thus this `Realm` channel can no longer be used.
	AddChildFromDecl(struct {
	/// The name of the child that is being added.
	name fuchsia.component.name;

	/// The component's declaration.
	decl fuchsia.component.decl.Component;

	/// Additional properties for the child.
	options ChildOptions;
	}) -> (struct {}) error RealmBuilderError2;

	/// Adds a component to the realm whose implementation will be provided by
	/// the client. When this component should be started, the runner channel
	/// passed into `Build` will receive a start request for a component whose
	/// `ProgramDecl` contains the relative moniker from the root of the
	/// constructed realm for the child that is to be run under the `program`
	/// key `LOCAL_COMPONENT_NAME`.
	///
	/// Errors:
	/// - `CHILD_ALREADY_EXISTS`: this realm already contains a child with the
	/// given name.
	/// - `BUILD_ALREADY_CALLED`: The `Builder.Build` function has been called
	/// for this realm, and thus this `Realm` channel can no longer be used.
	AddLocalChild(struct {
	/// The name of the child that is being added.
	name fuchsia.component.name;

	/// Additional properties for the child.
	options ChildOptions;
	}) -> (struct {}) error RealmBuilderError2;

	/// Adds a child realm which can be built with the client end of
	/// `child_realm`.
	///
	/// Errors:
	/// - `CHILD_ALREADY_EXISTS`: this realm already contains a child with the
	/// given name.
	/// - `BUILD_ALREADY_CALLED`: The `Builder.Build` function has been called
	/// for this realm, and thus this `Realm` channel can no longer be used.
	AddChildRealm(resource struct {
	/// The name of the child realm that is being added.
	name fuchsia.component.name;

	/// Additional properties for the child.
	options ChildOptions;

	/// The server end of the `Realm` channel that will be used to build the
	/// sub-realm.
	child_realm server_end:Realm;
	}) -> (struct {}) error RealmBuilderError2;

	/// Returns the component decl for the given component. `name` must refer to
	/// a component that is one of the following:
	///
	/// - A component with a local implementation
	/// - A legacy component
	/// - A component added with a relative URL
	/// - An automatically generated realm (ex: the root)
	///
	/// Errors:
	/// - `NO_SUCH_CHILD`: This realm does not contain a child with the given
	/// name.
	/// - `CHILD_DECL_NOT_VISIBLE`: The component decl cannot be fetched for
	/// the referenced child, because the child was added to the realm using
	/// an absolute (not-relative) and modern (not legacy) URL.
	/// - `BUILD_ALREADY_CALLED`: The `Builder.Build` function has been called
	/// for this realm, and thus this `Realm` channel can no longer be used.
	GetComponentDecl(struct {
	/// The name of the component whose declaration is being retrieved.
	name fuchsia.component.name;
	}) -> (struct {
	component_decl fuchsia.component.decl.Component;
	}) error RealmBuilderError2;

	/// Replaces the component decl for the given component. `name` must
	/// refer to a component that is one of the following:
	///
	/// - A component with a local implementation
	/// - A legacy component
	/// - A component added with a relative URL
	/// - An automatically generated realm (ex: the root)
	///
	/// Errors:
	/// - `NO_SUCH_CHILD`: This realm does not contain a child with the given
	/// name.
	/// - `CHILD_ALREADY_EXISTS`: The component whose decl is being replaced has
	/// had a child added to it through realm builder with the same name as an
	/// element in `component_decl.children`.
	/// - `CHILD_DECL_NOT_VISIBLE`: The component decl cannot be manipulated for
	/// the referenced child, because the child was added to the realm using
	/// an absolute (not relative) and modern (not legacy) URL.
	/// - `INVALID_COMPONENT_DECL`: `component_decl` failed validation.
	/// - `BUILD_ALREADY_CALLED`: The `Builder.Build` function has been called
	/// for this realm, and thus this `Realm` channel can no longer be used.
	ReplaceComponentDecl(struct {
	/// The name of the component whose declaration is being replaced.
	name fuchsia.component.name;

	/// The new component declaration for `name`.
	component_decl fuchsia.component.decl.Component;
	}) -> (struct {}) error RealmBuilderError2;

	/// Returns the component decl for this realm.
	///
	/// Errors:
	/// - `BUILD_ALREADY_CALLED`: The `Builder.Build` function has been called
	/// for this realm, and thus this `Realm` channel can no longer be used.
	GetRealmDecl() -> (struct {
	component_decl fuchsia.component.decl.Component;
	}) error RealmBuilderError2;

	/// Replaces the component decl for this realm.
	///
	/// Errors:
	/// - `INVALID_COMPONENT_DECL`: `component_decl` failed validation.
	/// - `BUILD_ALREADY_CALLED`: The `Builder.Build` function has been called
	/// for this realm, and thus this `Realm` channel can no longer be used.
	ReplaceRealmDecl(struct {
	/// The new component declaration for this realm.
	component_decl fuchsia.component.decl.Component;
	}) -> (struct {}) error RealmBuilderError2;

	/// Mutates component manifests in the realm such that every component in
	/// `to` will have a valid capability route for each item in `capabilities`
	/// provided by `from`.
	///
	/// Errors:
	/// - `NO_SUCH_SOURCE`: `from` references a non-existent child.
	/// - `NO_SUCH_TARGET`: `to` references a non-existent child.
	/// - `CAPABILITIES_EMPTY`: `capabilities` is empty.
	/// - `TARGETS_EMPTY`: `to` is empty.
	/// - `SOURCE_AND_TARGET_MATCH`: `from` is equal to one of the elements in
	/// `to`.
	/// - `INVALID_COMPONENT_DECL`: The requested route caused one of the
	/// involved manifests to fail validation.
	/// - `BUILD_ALREADY_CALLED`: The `Builder.Build` function has been called
	/// for this realm, and thus this `Realm` channel can no longer be used.
	AddRoute(struct {
	/// The capabilities that are to be routed.
	capabilities vector<Capability2>:MAX;

	/// The location where the elements of `capabilities` are available.
	from fuchsia.component.decl.Ref;

	/// The locations that should be able to access `capabilities`.
	to vector<fuchsia.component.decl.Ref>:MAX;
	}) -> (struct {}) error RealmBuilderError2;

	/// Offers a directory capability to a component in this realm. The
	/// directory will be read-only (i.e. have `r*` rights), and will have the
	/// contents described in `directory_contents`.
	///
	/// Errors:
	/// - `NO_SUCH_TARGET`: `offer-to` references a non-existent child.
	/// - `BUILD_ALREADY_CALLED`: The `Builder.Build` function has been called
	/// for this realm, and thus this `Realm` channel can no longer be used.
	ReadOnlyDirectory(resource struct {
	/// The name of the directory capability.
	name fuchsia.component.name;

	/// The target that this directory will be offered to.
	to vector<fuchsia.component.decl.Ref>:MAX;

	/// The contents of the directory.
	directory_contents DirectoryContents;
	}) -> (struct {}) error RealmBuilderError2;
	};