Connecting components

<<../../_common/fidl/_connecting_intro.md>>

Publishing a protocol implementation

Components that implement a FIDL protocol declare and expose that protocol as a capability in their component manifest. This enables the component framework to perform capability routing from this component to others in the topology that request the capability.

{
    // ...
    capabilities: [
        { protocol: "fuchsia.example.Foo" },
    ],
    expose: [
        {
            protocol: "fuchsia.example.Foo",
            from: "self",
        },
    ],
}

Capability routing describes the access rights for the protocol, but it does not establish the necessary endpoints for a connection. Components must publish the implementation as an /svc/ handle in the outgoing directory using the fuchsia.io protocol. The generated FIDL bindings wrap this handle and enable the provider to connect a request handle to begin receiving FIDL messages.

{Rust}

let mut service_fs = ServiceFs::new_local();

// Serve the protocol
service_fs.dir("svc").add_fidl_service(PROTOCOL_NAME);
service_fs.take_and_serve_directory_handle().context("failed to serve outgoing namespace")?;

{C++}

// Serve the protocol
FooImplementation instance;
fidl::Binding<fuchsia::example::Foo> binding(&instance);
instance.event_sender_ = &binding.events();
fidl::InterfaceRequestHandler<fuchsia::example::Foo> handler =
    [&](fidl::InterfaceRequest<fuchsia::example::Foo> request) {
      binding.Bind(std::move(request));
    };
context->outgoing()->AddPublicService(std::move(handler));

Connecting to a protocol implementation

Client components declare the protocol as a required capability in their component manifest. This allows the component framework to determine whether the component has the rights to access protocol implementation. If a valid route exists, the component's namespace contains a corresponding /svc/ handle.

{
    // ...
    use: [
        { protocol: "fuchsia.example.Foo" },
    ],
}

Recall that capabilities are routed explicitly between components, so the topology must include a connected set of offers between components for routing to succeed.

The client component uses the fuchsia.io protocol to establish a connection to the protocol implementation and open a channel. The generated FIDL bindings wrap this channel and enable the client to begin sending messages to the provider.

{Rust}

// Connect to FIDL protocol
let protocol = connect_to_protocol::<FooMarker>().expect("error connecting to echo");

{C++}

// Connect to FIDL protocol
fuchsia::example::FooSyncPtr proxy;
auto context = sys::ComponentContext::Create();
context->svc()->Connect(proxy.NewRequest());

Exercise: Echo server and client

In this section, you'll use the generated FIDL bindings for fidl.examples.routing.echo to implement client and server components in Rust.

<<../_common/_start_femu_with_packages.md>>

Create the server component

Begin by creating a new component project to implement the echo server. This component will serve the Echo protocol and handle incoming requests.

{Rust}

fx create component --path vendor/fuchsia-codelab/echo-server --lang rust

{C++}

fx create component --path vendor/fuchsia-codelab/echo-server --lang cpp

Add the generated bindings to the BUILD.gn file as a dependency:

{Rust}

echo-server/BUILD.gn:

rustc_binary("bin") {
  output_name = "echo-server"

  deps = [
    {{ '<strong>' }}"//vendor/fuchsia-codelab/echo-fidl:echo-rustc",{{ '</strong>' }}
    ...
  ]

  sources = [ "src/main.rs" ]
}

{C++}

echo-server/BUILD.gn:

executable("bin") {
  output_name = "echo-server"

  deps = [
    {{ '<strong>' }}"//vendor/fuchsia-codelab/echo-fidl:echo",{{ '</strong>' }}
    ...
  ]

  sources = [ "main.cc" ]
}

Declare the Echo protocol as a capability provided by the server component, and expose it for use by the parent realm:

{Rust}

echo-server/meta/echo_server.cml:

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/routing/rust/echo_server/meta/echo_server.cml" region_tag="example_snippet" adjust_indentation="auto" %}

{C++}

echo-server/meta/echo_server.cml:

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/routing/cpp/echo_server/meta/echo_server.cml" region_tag="example_snippet" adjust_indentation="auto" %}

Implement the server

Open the main source file and replace the import statements with the following code:

{Rust}

echo-server/src/main.rs:
```
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/routing/rust/echo_server/src/main.rs" region_tag="imports" adjust_indentation="auto" %}
```
FIDL bindings for Rust generate a Rust library crate named after the FIDL library. For the fidl.examples.routing.echo library, the generated crate name is fidl_fidl_examples_routing_echo. For more details, see Rust bindings.

{C++}

echo-server/main.cc:

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/routing/cpp/echo_server/main.cc" region_tag="imports" adjust_indentation="auto" %}

Add the following code to main() to serve the Echo protocol:

{Rust}

echo-server/src/main.rs:
```
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/routing/rust/echo_server/src/main.rs" region_tag="main_body" adjust_indentation="auto" highlight="1,2,3,4,14,15,23,24,25,26,27" %}
```
This code performs the following steps to serve the Echo protocol:
1. Initialize ServiceFs and add an entry under /svc/fidl.examples.routing.echo.Echo in the outgoing directory.
2. Serve the directory and begin listening for incoming connections.
3. Attach the handle_echo_request() function as a request handler for any matching Echo requests.
{C++}

echo-server/main.cc:
```
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/routing/cpp/echo_server/main.cc" region_tag="main_body" adjust_indentation="auto" highlight="3,8,13,14,15,16,17" %}
```
This code performs the following steps to serve the Echo protocol:
1. Initialize ComponentContext and add an entry under /svc/fidl.examples.routing.echo.Echo in the outgoing directory.
2. Serve the directory and begin listening for incoming connections.
3. Attach the EchoImplementation instance as a request handler for any matching Echo requests.

Add the following code to implement the protocol request handler:

{Rust}

echo-server/src/main.rs:
```
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/routing/rust/echo_server/src/main.rs" region_tag="handler" adjust_indentation="auto" %}
```
Each request in the EchoRequestStream is typed by the method name (EchoString) and includes a responder interface to send back the return value.
{C++}

echo-server/main.cc:
```
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/routing/cpp/echo_server/main.cc" region_tag="handler" adjust_indentation="auto" %}
```
Each Echo protocol method has a corresponding override function (EchoString()) and includes a callback interface to send back the return value.

This implementation simply "echoes" the same string value from the request back in the response payload.

Create the client component

Create another new component project to implement the echo client. This component will connect to the protocol implementation and send requests.

{Rust}

fx create component --path vendor/fuchsia-codelab/echo-client --lang rust

{C++}

fx create component --path vendor/fuchsia-codelab/echo-client --lang cpp

Add the generated bindings to the BUILD.gn file as a dependency:

{Rust}

echo-client/BUILD.gn:

rustc_binary("bin") {
  output_name = "echo-client"

  deps = [
    {{ '<strong>' }}"//vendor/fuchsia-codelab/echo-fidl:echo-rustc",{{ '</strong>' }}
    ...
  ]

  sources = [ "src/main.rs" ]
}

{C++}

echo-client/BUILD.gn:

executable("bin") {
  output_name = "echo-client"

  deps = [
    {{ '<strong>' }}"//vendor/fuchsia-codelab/echo-fidl:echo",{{ '</strong>' }}
    ...
  ]

  sources = [ "main.cc" ]
}

Configure the client's component manifest to request the fidl.examples.routing.echo.Echo capability exposed by the server:

{Rust}