# gRPC schema

Fetch the protobuf schema of the Synthient gRPC API.

The `com.synthient:synthient-java-grpcschema` artifact fetches the protobuf schema of the Synthient [gRPC API](https://docs.synthient.com/grpc) using gRPC server reflection. Its classes are in the `com.synthient.grpcschema` package, and its automatic module name is `com.synthient.grpcschema`. It depends on grpc-java and protobuf-java, and brings the shaded Netty transport at runtime.

**Install**

```kotlin title="Gradle"
implementation("com.synthient:synthient-java-grpcschema:1.0.0")
```

```xml title="Maven"
<dependency>
  <groupId>com.synthient</groupId>
  <artifactId>synthient-java-grpcschema</artifactId>
  <version>1.0.0</version>
</dependency>
```

## fetch

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

```java
public static Schema fetch(String apiKey)
public static Schema fetch(String apiKey, FetchOptions options)
```

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

```java
try {
    Schema schema = GrpcSchema.fetch(System.getenv().getOrDefault("SYNTHIENT_API_KEY", ""));
    System.out.println("endpoint: " + schema.endpoint());
    for (String symbol : schema.symbols()) {
        System.out.println("service: " + symbol);
    }
    for (FileDescriptorProto file : schema.descriptorSet().getFileList()) {
        System.out.println("file: " + file.getName() + " (package " + file.getPackage() + ")");
    }
} catch (SchemaException e) {
    String explanation = GrpcSchema.explain(e);
    System.err.println(explanation.isEmpty() ? e.toString() : explanation + " " + e);
}
```

- **Auth:** The API key is sent as `x-api-key` metadata unless it is blank.
- **Input:** The one-argument form fetches every service from `GrpcSchema.DEFAULT_ENDPOINT` over TLS.
- **Errors:** A failure throws `SchemaException`, and an invalid endpoint throws `IllegalArgumentException`.

## FetchOptions

`FetchOptions.builder()` returns a builder that fetches every service from `GrpcSchema.DEFAULT_ENDPOINT` over TLS, and `build()` returns the options.

```java
public static Builder builder()
public FetchOptions build()
```

- `endpoint` `String` — Sets the server: `host:port`, a bare host with port 443 assumed, or a `grpc://` or `https://` URL. An empty endpoint, the default, means `GrpcSchema.DEFAULT_ENDPOINT`.
- `plaintext` `boolean` — Disables TLS, for local development servers.
- `symbols` `String...` — Adds fully qualified service or message names to resolve, such as `synthient.v1.SynthientService`. Blank and repeated names are ignored. Without any, every service the server lists is resolved except the reflection service itself, which can be named here instead.
- `timeout` `Duration` — Sets the deadline for the whole fetch, by default 30 seconds. A timeout that is not positive throws `IllegalArgumentException`.

```java
Schema schema = GrpcSchema.fetch(
        "",
        FetchOptions.builder()
                .endpoint("localhost:50051")
                .plaintext(true)
                .symbols("synthient.v1.SynthientService")
                .timeout(Duration.ofSeconds(10))
                .build());
System.out.println(schema.descriptorSet().getFileCount());
```

- **Accessors:** Each setting can be read back from an accessor of the same name, such as `FetchOptions.timeout()`.

## Schema

The protobuf schema returned by `fetch`.

- `endpoint` `String` — The normalized `host:port` that was queried.
- `symbols` `List<String>` — The service or message names that were resolved.
- `descriptorSet` `FileDescriptorSet` — The resolved files, each after the files it imports.

## explain

Returns an explanation of a common failure of `fetch`, or an empty string if it has none.

```java
public static String explain(Throwable error)
```

| gRPC code           | Explanation                                                                                              |
| ------------------- | -------------------------------------------------------------------------------------------------------- |
| `UNAUTHENTICATED`   | Missing or invalid API key.                                                                              |
| `PERMISSION_DENIED` | This API key does not have permission to inspect gRPC schemas.                                           |
| `NOT_FOUND`         | 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.                  |
| `DEADLINE_EXCEEDED` | Timed out reading protobuf schemas from gRPC reflection. Use a longer timeout.                           |

- **Input:** It reads the code of a `SchemaException`, or the gRPC status of any other exception.

## SchemaException

Fetching a schema failed. It extends `SynthientException`.

```java
public SchemaException(String message, Status.@Nullable Code code, @Nullable Throwable cause)
```

- `code` `Status.Code` — The gRPC status code of the failure, or `null` when the failure did not come from gRPC.