## Prerequisites

This tutorial assumes that you are familiar with writing and running a Fuchsia
component and with implementing a FIDL server, which are both covered in the
[FIDL server](https://fuchsia.dev/docs/development/languages/fidl/tutorials/rust/basics/server) tutorial. For the full set of FIDL tutorials, refer
to the [overview](https://fuchsia.dev/docs/development/languages/fidl/tutorials/overview).

## Overview

This tutorial implements a client for a FIDL protocol and runs it
against the server created in the [previous tutorial](https://fuchsia.dev/docs/development/languages/fidl/tutorials/rust/basics/server). The client in this
tutorial is asynchronous. There is an [alternate tutorial](https://fuchsia.dev/docs/development/languages/fidl/tutorials/rust/basics/sync-client) for
synchronous clients.

If you want to write the code yourself, delete the following directories:

```bash
rm -r examples/fidl/rust/client/*
```

## Create the component

Create a new component project at `examples/fidl/rust/client`:

1. Add a `main()` function to `examples/fidl/rust/client/src/main.rs`:

   ```rust
   fn main() {
     println!("Hello, world!");
   }
   ```
2. Declare a target for the client in `examples/fidl/rust/client/BUILD.bazel`:

   ```python
   load(
       "//build/bazel/rules/components:fx_component.bzl",
       "fx_component",
       "fx_component_manifest",
   )
   load(
       "//build/bazel/rules/packages:fx_packaged_binary.bzl",
       "fx_packaged_binary",
   )
   load("//build/bazel/rules/rust:rustc_binary.bzl", "rustc_binary")


   # Declare an executable for the client.
   rustc_binary(
       name = "bin",
       binary_name = "fidl_echo_rust_client",
       srcs = ["src/main.rs"],
       edition = "2024",
   )

   fx_component_manifest(
       name = "echo-client_manifest",
       component_name = "echo_client",
       includes = ["//sdk/lib/syslog:client.shard"],
       manifest = "meta/client.cml",
   )

   fx_component(
       name = "echo-client",
       compiled_manifest = ":echo-client_manifest",
       visibility = [
           "//examples/fidl/echo-realm:__pkg__",
           "//examples/fidl/rust:__pkg__",
       ],
       deps = [":bin_packaged_bin"],
   )
   ```
3. Add a component manifest in `examples/fidl/rust/client/meta/client.cml`:

   > [!NOTE]
   > **Note:** The binary name in the manifest must match the output name of the `executable` defined in the previous step.

   ```json5
   {
       include: [ "syslog/client.shard.cml" ],

       // Information about the program to run.
       program: {
           // Use the built-in ELF runner.
           runner: "elf",

           // The binary to run for this component.
           binary: "bin/fidl_echo_rust_client",
       },

       // Capabilities used by this component.
       use: [
           { protocol: "fuchsia.examples.Echo" },
       ],
   }

   ```
4. Once you have created your component, ensure that you can add it to the
   build configuration:

   ```bash
   fx set core.x64 --with //examples/fidl/rust/client:echo-client
   ```
5. Build the Fuchsia image:

   ```bash
   fx build
   ```

## Edit GN dependencies

1. Add the following dependencies to the `rustc_binary`:

   ```python
       deps = [
           "//examples/fidl/fuchsia.examples:fuchsia.examples_rust",
           "//src/lib/fuchsia",
           "//src/lib/fuchsia-component",
           "//third_party/rust_crates/vendor:anyhow",
           "//third_party/rust_crates/vendor:futures",
       ],
   ```
2. Then, import them in `main.rs`:

   ```rust
   use anyhow::{Context as _, Error};
   use fidl_fuchsia_examples::{EchoEvent, EchoMarker};
   use fuchsia_component::client::connect_to_protocol;
   use futures::prelude::*;
   ```

These dependencies are explained in the [server tutorial](https://fuchsia.dev/docs/development/languages/fidl/tutorials/rust/basics/server).

## Connect to the server

The steps in this section explain how to add code to the `main()` function
that connects the client to the server and makes requests to it.

### Connect to the server

```rust
#[fuchsia::main]
async fn main() -> Result<(), Error> {
// Connect to the Echo protocol, which is assumed to be in the component's environment
let echo = connect_to_protocol::\<EchoMarker\>().context("Failed to connect to echo service")?;

    // Make an EchoString request and wait for the response
    let res = echo.echo_string("hello").await?;
    println!("response: {:?}", res);

    // Make a SendString request
    echo.send_string("hi")?;
    // Wait for a single OnString event
    let EchoEvent::OnString { response } =
        echo.take_event_stream().next().await.context("error receiving events")??;
    println!("Received OnString event for string {:?}", response);

    Ok(())
}
```

Under the hood, this call triggers a sequence of events that starts on the client and traces
through the server code from the previous tutorial.

- Initialize a client object, as well as a channel. The client object is bound to one end of the channel.
- Makes a request to the component framework containing the name of the service to connect to, and the other end of the channel. The name of the service is obtained implicitly using the `SERVICE_NAME` of `EchoMarker` template argument, similarly to how the service path is determined on the server end.
- This client object is returned from `connect_to_protocol`.

In the background, the request to the component framework gets routed to the server:

- When this request is received in the server process, it wakes up the `async::Executor` executor and tells it that the `ServiceFs` task can now make progress and should be run.
- The `ServiceFs` wakes up, sees the request available on the startup handle of the process, and looks up the name of the requested service in the list of `(service_name, service_startup_func)` provided through calls to `add_service`, `add_fidl_service`, etc. If a matching `service_name` exists, it calls `service_startup_func` with the provided channel to connect to the new service.
- `IncomingService::Echo` is called with a `RequestStream` (typed-channel) of the `Echo` FIDL protocol that is registered with `add_fidl_service`. The incoming request channel is stored in `IncomingService::Echo` and is added to the stream of incoming requests. `for_each_concurrent` consumes the `ServiceFs` into a `Stream` of type `IncomingService`. A handler is run for each entry in the stream, which matches over the incoming requests and dispatches to the `run_echo_server`. The resulting futures from each call to `run_echo_server` are run concurrently when the `ServiceFs` stream is `await`ed.
- When a request is sent on the channel, the channel the `Echo` service is becomes readable, which wakes up the asynchronous code in the body of `run_echo_server`.

### Send requests to the server

The code makes two requests to the server:

- An `EchoString` request
- A `SendString` request

```rust
#[fuchsia::main]
async fn main() -> Result<(), Error> {
    // Connect to the Echo protocol, which is assumed to be in the component's environment
    let echo = connect_to_protocol::<EchoMarker>().context("Failed to connect to echo service")?;

// Make an EchoString request and wait for the response
let res = echo.echo_string("hello").await?;
println!("response: {:?}", res);

// Make a SendString request
echo.send_string("hi")?;
    // Wait for a single OnString event
    let EchoEvent::OnString { response } =
        echo.take_event_stream().next().await.context("error receiving events")??;
    println!("Received OnString event for string {:?}", response);

    Ok(())
}
```

The call to `EchoString` returns a future, which resolves to the response returned by the server.
The returned future will resolve to an error if there is either an error sending the request or
receiving the response (e.g. when decoding the message, or if an epitaph was received).

On the other hand, the call to `SendString` returns a `Result`, since it is a fire and forget
method. This method call will return an error if there was an issue sending the request.

The [bindings reference](https://fuchsia.dev/docs/reference/fidl/bindings/rust-bindings) describes how these proxy methods are generated, and the
[Fuchsia rustdoc](https://fuchsia.dev/go/rustdoc/) includes documentation for the generated FIDL crates.

### Handle incoming events

The code then waits for a single `OnString` event from the server:

```rust
#[fuchsia::main]
async fn main() -> Result<(), Error> {
    // Connect to the Echo protocol, which is assumed to be in the component's environment
    let echo = connect_to_protocol::<EchoMarker>().context("Failed to connect to echo service")?;

    // Make an EchoString request and wait for the response
    let res = echo.echo_string("hello").await?;
    println!("response: {:?}", res);

    // Make a SendString request
    echo.send_string("hi")?;
// Wait for a single OnString event
let EchoEvent::OnString { response } =
echo.take_event_stream().next().await.context("error receiving events")??;
println!("Received OnString event for string {:?}", response);

    Ok(())
}
```

This is done by [taking the event stream](https://fuchsia.dev/docs/reference/fidl/bindings/rust-bindings#protocol-events-client) from the client object, then waiting
for a single event from it.

## Run the client

In order for the client and server to communicate using the `Echo` protocol,
component framework must route the `fuchsia.examples.Echo` capability from the
server to the client. For this tutorial, a


[](https://fuchsia.dev/docs/glossary#realm)


component is
provided to declare the appropriate capabilities and routes.

> [!NOTE]
> **Note:** You can explore the full source for the realm component at [`//examples/fidl/echo-realm`](https://cs.opensource.google/fuchsia/fuchsia/+/main:/examples/fidl/echo-realm)

1. Configure your build to include the provided package that includes the
   echo realm, server, and client:

   ```bash
   fx set core.x64 --with //examples/fidl/rust:echo-rust-client
   ```
2. Build the Fuchsia image:

   ```bash
   fx build
   ```
3. Run the `echo_realm` component. This creates the client and server component
   instances and routes the capabilities:

   ```bash
   ffx component run /core/ffx-laboratory:echo_realm fuchsia-pkg://fuchsia.com/echo-rust-client#meta/echo_realm.cm
   ```
4. Start the `echo_client` instance:

   ```bash
   ffx component start /core/ffx-laboratory:echo_realm/echo_client
   ```

The server component starts when the client attempts to connect to the `Echo`
protocol. You should see output similar to the following in the device logs
(`ffx log`):

    [echo_server][][I] Listening for incoming connections...
    [echo_server][][I] Received EchoString request for string "hello"
    [echo_server][][I] Response sent successfully
    [echo_client][][I] response: "hello"
    [echo_server][][I] Received SendString request for string "hi"
    [echo_server][][I] Event sent successfully
    [echo_client][][I] Received OnString event for string "hi"

Terminate the realm component to stop execution and clean up the component
instances:

```bash
ffx component destroy /core/ffx-laboratory:echo_realm
```
[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/development/languages/fidl/tutorials/rust/basics/client.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/development/languages/fidl/tutorials/rust/basics/client.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/development/languages/fidl/tutorials/rust/basics/client.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/development/languages/fidl/tutorials/rust/basics/client.md "Edit the source code of this page")