# gRPC schema

Fetch the protobuf schema of the Synthient gRPC API.

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

```go
import "github.com/synthient/synthient-go/grpcschema"
```

The first time you import it, run `go mod tidy` to add its gRPC dependencies.

## Fetch

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

```go
func Fetch(ctx context.Context, apiKey string, opts ...Options) (*Schema, error)
```

```go
ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
defer cancel()

schema, err := grpcschema.Fetch(ctx, os.Getenv("SYNTHIENT_API_KEY"))
if err != nil {
	explanation := grpcschema.Explain(err)
	if explanation != "" {
		log.Fatalf("%s %v", explanation, err)
	}
	log.Fatal(err)
}
for _, file := range schema.DescriptorSet.GetFile() {
	fmt.Println(file.GetName(), file.GetPackage())
}
```

- **Auth:** `apiKey` is sent as `x-api-key` metadata when it is not empty.
- **Input:** `opts` is optional, and only the first is used.
- **Timeout:** Bound the call with a context deadline.

## Options

The zero value fetches every service from `DefaultEndpoint` over TLS.

- `Endpoint` `string` — The server address as `host:port`, a bare host (port 443 is assumed), or a `grpc://` or `https://` URL. Empty uses `DefaultEndpoint`, `"grpc.synthient.com:443"`.
- `Plaintext` `bool` — Disables TLS, for local development servers.
- `Symbols` `[]string` — Fully qualified service or message names to resolve. Empty resolves every service the server lists, except the reflection service itself.

## Schema

- `Endpoint` `string` — The normalized address that was queried.
- `Symbols` `[]string` — The service or message names that were resolved.
- `DescriptorSet` `*descriptorpb.FileDescriptorSet` — The resolved files in dependency order, each file after the files it imports.

## Explain

Returns a human-readable explanation of a common gRPC error returned by `Fetch`, or an empty string if it has none.

```go
func Explain(err error) string
```

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