# gRPC schema

Fetch the protobuf schema of the Synthient gRPC API.

The `Synthient.Client.GrpcSchema` package fetches the protobuf schema of the Synthient [gRPC API](https://docs.synthient.com/grpc) using gRPC server reflection. It is a separate package with its own dependencies on `Grpc.Net.Client`, `Grpc.Reflection`, and `Google.Protobuf`. Its types are in the `Synthient` namespace.

```bash
dotnet add package Synthient.Client.GrpcSchema
```

## FetchAsync

Connects to a Synthient gRPC endpoint and uses server reflection to fetch the protobuf files that define `GrpcSchemaOptions.Symbols`, or every listed service when there are none, along with all of their imports.

```csharp
public static class GrpcSchema
public static Task<GrpcSchemaResult> FetchAsync(string? apiKey, GrpcSchemaOptions? options = null, CancellationToken cancellationToken = default)
```

- `GrpcSchema.DefaultEndpoint` `const string` — `"grpc.synthient.com:443"`, the address of the Synthient gRPC API.

```csharp
try
{
    var schema = await GrpcSchema.FetchAsync(Environment.GetEnvironmentVariable("SYNTHIENT_API_KEY"));
    foreach (var file in schema.DescriptorSet.File)
    {
        Console.WriteLine($"{file.Name} {file.Package}");
    }
}
catch (GrpcSchemaException e)
{
    var explanation = GrpcSchema.Explain(e);
    Console.Error.WriteLine(explanation is null ? e.Message : $"{explanation} {e.Message}");
}
```

- **Auth:** `apiKey` is trimmed and sent as `x-api-key` metadata when it is not empty or whitespace. Unlike `SynthientClient`, it does not read `SYNTHIENT_API_KEY` on its own.
- **Input:** `null` options fetch every service of `GrpcSchema.DefaultEndpoint`. An invalid endpoint or a `Timeout` that is not positive throws an `ArgumentException`.
- **Errors:** A failure throws a `GrpcSchemaException`.

## GrpcSchemaOptions

The default options fetch every service from `GrpcSchema.DefaultEndpoint` over TLS.

- `Endpoint` `string?` — The server address as `host:port`, a bare host (port 443 is assumed), or a `grpc://` or `https://` URL. `null` or whitespace uses `GrpcSchema.DefaultEndpoint`. The URL scheme does not choose TLS; `Plaintext` does.
- `Plaintext` `bool` — Disables TLS, for local development servers.
- `Symbols` `IList<string>` — Fully qualified service or message names to resolve. Empty resolves every service the server lists, except the `grpc.reflection` services. The property is read-only, so add names to the list. Names are trimmed, and blank and duplicate names are dropped.
- `Timeout` `TimeSpan` — The deadline for the whole fetch. The default is 30 seconds, and it must be positive.

## GrpcSchemaResult

```csharp
public sealed record GrpcSchemaResult(string Endpoint, IReadOnlyList<string> Symbols, FileDescriptorSet DescriptorSet);
```

- `Endpoint` `string` — The normalized address that was queried.
- `Symbols` `IReadOnlyList<string>` — The service or message names that were resolved.
- `DescriptorSet` `FileDescriptorSet` — The resolved files, each after the files it imports. `FileDescriptorSet` is in `Google.Protobuf.Reflection`.

## GrpcSchemaException

Fetching a gRPC schema failed.

```csharp
public sealed class GrpcSchemaException : SynthientException
public GrpcSchemaException(StatusCode statusCode, string message, Exception? innerException = null)
```

- `StatusCode` `StatusCode` — The gRPC status code, from `Grpc.Core`, or `StatusCode.Unknown` if the server broke the reflection protocol.

* **Timeout:** A fetch that runs past `GrpcSchemaOptions.Timeout` fails with `StatusCode.DeadlineExceeded`.
* **Cancellation:** Cancelling the call's token throws `OperationCanceledException` instead.

## Explain

Returns a human-readable explanation of a common gRPC failure from `FetchAsync`, or `null` if there is none.

```csharp
public static string? Explain(Exception exception)
```

- **Input:** It reads the status code of a `GrpcSchemaException` or a `Grpc.Core.RpcException`.

| 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.                           |