gRPC schema

Fetch the protobuf schema of the Synthient gRPC API.

Synthient::GRPCSchema fetches the protobuf schema of the Synthient gRPC API using gRPC server reflection.

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.

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

Name
api_key
Type
String?
Description
Sent as x-api-key metadata unless blank. The default is the SYNTHIENT_API_KEY environment variable.
Name
endpoint
Type
String
Description
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.
Name
plaintext
Type
bool
Description
Disables TLS, for local development servers. The default is false.
Name
symbols
Type
Array[String]
Description
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.
Name
timeout
Type
Numeric
Description
Seconds the whole fetch may take. The default is 30. A value that is not a positive number raises ArgumentError.

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.

Name
endpoint
Type
String
Description
The normalized host:port address that was queried.
Name
symbols
Type
Array[String]
Description
The service or message names that were resolved.
Name
descriptor_set
Type
untyped
Description
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.

Name
code
Type
Integer?
Description
The gRPC status code, or nil when the server's reflection responses were unusable.

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

explain

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

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

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