# gRPC schema

Fetch the protobuf schema of the Synthient gRPC API.

With the `grpcschema` feature, the `synthient::grpcschema` module fetches the protobuf schema of the Synthient [gRPC API](https://docs.synthient.com/grpc) using gRPC server reflection.

```bash
cargo add synthient --features grpcschema
```

- **Connection:** Unless `plaintext` is set, the connection uses rustls with the platform's trusted certificates, whichever TLS feature the HTTP client uses.
- **Re-exports:** The module re-exports `prost`, `prost_types`, and `tonic`'s `Code`.

## fetch

Starts a fetch of the protobuf files that define the server's services, along with all of their imports.

```rust
pub fn fetch(api_key: impl Into<String>) -> Fetch
```

```rust
use synthient::grpcschema;

let schema = match grpcschema::fetch(std::env::var("SYNTHIENT_API_KEY")?).await {
    Ok(schema) => schema,
    Err(err) => match err.explain() {
        Some(explanation) => return Err(format!("{explanation} {err}").into()),
        None => return Err(err.into()),
    },
};

println!("endpoint: {}", schema.endpoint);
for symbol in &schema.symbols {
    println!("service: {symbol}");
}
for file in &schema.descriptor_set.file {
    println!("file: {} (package {})", file.name(), file.package());
}
```

- **Auth:** `api_key` is sent as `x-api-key` metadata unless it is blank.
- **Network:** Nothing is sent until the returned `Fetch` is awaited, so change its options first.
- **Traits:** `Fetch` implements `IntoFuture` with `Output = Result<Schema, SchemaError>`, and the future is `Send + 'static`.

## Fetch

The default fetches every service from `DEFAULT_ENDPOINT` over TLS within 30 seconds.

```rust
pub fn endpoint(self, endpoint: impl Into<String>) -> Self
pub fn plaintext(self, plaintext: bool) -> Self
pub fn symbols<I, S>(self, symbols: I) -> Self
where
    I: IntoIterator<Item = S>,
    S: Into<String>,
pub fn timeout(self, timeout: Duration) -> Self
```

- `endpoint` — Sets the server as `host:port`, a bare host (port 443 is assumed), or a `grpc://` or `https://` URL. A blank endpoint uses `DEFAULT_ENDPOINT`.
- `plaintext` — Disables TLS when `true`, for local development servers.
- `symbols` — Resolves these fully qualified service or message names instead of every service the server lists. The listing leaves out the `grpc.reflection` services, so name one here to fetch its schema. Blank and repeated names are ignored.
- `timeout` — Sets how long the whole fetch may take. The default is 30 seconds. A fetch that runs out of time returns a `SchemaError` with the code `Code::DeadlineExceeded`.

## Schema

The protobuf schema returned by `fetch`.

- `endpoint` `String` — The normalized address that was queried, as `host:port`.
- `symbols` `Vec<String>` — The service or message names that were resolved.
- `descriptor_set` `FileDescriptorSet` — The resolved files in dependency order, each file after the files it imports.

`FileDescriptorSet` is `prost_types::FileDescriptorSet`. Encode it with `prost::Message::encode_to_vec` for tools such as `grpcurl` and `buf`:

```rust
use synthient::grpcschema::{self, prost::Message};

let schema = grpcschema::fetch(std::env::var("SYNTHIENT_API_KEY")?).await?;
std::fs::write("synthient.binpb", schema.descriptor_set.encode_to_vec())?;
```

## SchemaError

A failed schema fetch. Its `Display` output describes the failure, and `source()` returns the underlying error when there is one.

- `code` `Option<Code>` — The gRPC status code, or `None` when the failure was not a gRPC status, such as an invalid endpoint or an unusable reflection reply.

## explain

Returns a human-readable explanation of a common failure, or `None`.

```rust
pub fn explain(&self) -> Option<&'static str>
```

| gRPC code          | Explanation                                                                                              |
| ------------------ | -------------------------------------------------------------------------------------------------------- |
| `Unauthenticated`  | Missing or invalid API key.                                                                              |
| `PermissionDenied` | This API key does not have permission to inspect gRPC schemas.                                           |
| `NotFound`         | No protobuf schema found for the requested symbol. Fetch without symbols to list the available services. |
| `Unimplemented`    | The gRPC endpoint does not expose server reflection.                                                     |
| `Unavailable`      | Could not reach the gRPC endpoint. Check the address, network access, and TLS settings.                  |
| `DeadlineExceeded` | Timed out reading protobuf schemas from gRPC reflection. Use a longer timeout.                           |

## Constants

- `DEFAULT_ENDPOINT` `&str` — `"grpc.synthient.com:443"`, the address of the Synthient gRPC API.