# gRPC schema

Fetch the protobuf schema of the Synthient gRPC API.

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

```ruby
require "synthient/grpcschema"
```

- **Loading:** It is not loaded by `require "synthient"`.
- **Dependencies:** It needs the `grpc` and `google-protobuf` gems, which the `synthient` gem does not depend on. Without them, the `require` raises `LoadError`.

## fetch

Connects to a Synthient gRPC endpoint and uses server reflection to fetch the protobuf files that define `symbols`, or every service the server lists when `symbols` is empty, along with all of their imports.

```ruby
def self.fetch: (?api_key: String?, ?endpoint: String, ?plaintext: bool, ?symbols: Array[String],
                 ?timeout: Numeric) -> Schema
```

- `api_key` `String?` — Sent as `x-api-key` metadata unless blank. The default is the `SYNTHIENT_API_KEY` environment variable.
- `endpoint` `String` — The server address as `host:port`, a bare host (port 443 is assumed), or a `grpc://` or `https://` URL. The default is `DEFAULT_ENDPOINT`, which an empty string also selects. An invalid URL raises `ArgumentError`.
- `plaintext` `bool` — Disables TLS, for local development servers. The default is `false`.
- `symbols` `Array[String]` — Fully qualified service or message names to resolve. Surrounding whitespace is trimmed, and blank and duplicate names are dropped. The default, `[]`, resolves every service the server lists.
- `timeout` `Numeric` — Seconds the whole fetch may take. The default is `30`. A value that is not a positive number raises `ArgumentError`.

```ruby
require "synthient/grpcschema"

begin
  schema = Synthient::GRPCSchema.fetch # reads SYNTHIENT_API_KEY
rescue Synthient::GRPCSchema::SchemaError => e
  explanation = Synthient::GRPCSchema.explain(e)
  abort explanation ? "#{explanation} #{e.message}" : e.message
end
schema.descriptor_set.file.each do |file|
  puts "#{file.name} #{file.package}"
end
```

- **Coverage:** Listing skips the `grpc.reflection` services; name one in `symbols` to fetch it.
- **Errors:** When the server rejects a request, `fetch` raises `SchemaError` with the gRPC status code, and unusable reflection responses raise `SchemaError` without one.

## Schema

The result of `fetch`.

- `endpoint` `String` — The normalized `host:port` address that was queried.
- `symbols` `Array[String]` — The service or message names that were resolved.
- `descriptor_set` `untyped` — A `Google::Protobuf::FileDescriptorSet` holding the resolved files in dependency order, each file after the files it imports.

## SchemaError

A failed schema fetch. It is a `Synthient::Error`.

- `code` `Integer?` — The gRPC status code, or `nil` when the server's reflection responses were unusable.

```ruby
def initialize: (?String? message, ?code: Integer?) -> void
```

## explain

Returns a human-readable explanation of a common fetch failure, or `nil` if it has none.

```ruby
def self.explain: (untyped error) -> String?
```

| 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 accepts a `SchemaError`, a `GRPC::BadStatus`, or any other error with a `code`.

## Constants

- `Synthient::GRPCSchema::DEFAULT_ENDPOINT` `String` — `"grpc.synthient.com:443"`, the Synthient gRPC endpoint.
- `Synthient::GRPCSchema::MAX_MESSAGE_SIZE` `Integer` — `33554432` (32 MiB), the largest reflection response the client accepts.
- `Synthient::GRPCSchema::EXPLANATIONS` `Hash[Integer, String]` — The explanations `explain` returns, by gRPC status code.