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

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.

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

Name
GrpcSchema.DefaultEndpoint
Type
const string
Description
"grpc.synthient.com:443", the address of the Synthient gRPC API.

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.

Name
Endpoint
Type
string?
Description
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.
Name
Plaintext
Type
bool
Description
Disables TLS, for local development servers.
Name
Symbols
Type
IList<string>
Description
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.
Name
Timeout
Type
TimeSpan
Description
The deadline for the whole fetch. The default is 30 seconds, and it must be positive.

GrpcSchemaResult

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

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

GrpcSchemaException

Fetching a gRPC schema failed.

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

Name
StatusCode
Type
StatusCode
Description
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.

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.