v4

gRPC schema

View as markdown

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

implementation("com.synthient:synthient-java-grpcschema:1.0.0")

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.

public static Schema fetch(String apiKey)
public static Schema fetch(String apiKey, FetchOptions options)
  • Name
    GrpcSchema.DEFAULT_ENDPOINT
    Type
    String
    Description

    "grpc.synthient.com:443", the address of the Synthient gRPC API.

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.

public static Builder builder()
public FetchOptions build()
  • Name
    endpoint
    Type
    String
    Description

    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.

  • Name
    plaintext
    Type
    boolean
    Description

    Disables TLS, for local development servers.

  • Name
    symbols
    Type
    String...
    Description

    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.

  • Name
    timeout
    Type
    Duration
    Description

    Sets the deadline for the whole fetch, by default 30 seconds. A timeout that is not positive throws IllegalArgumentException.

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.

  • Name
    endpoint
    Type
    String
    Description

    The normalized host:port that was queried.

  • Name
    symbols
    Type
    List<String>
    Description

    The service or message names that were resolved.

  • Name
    descriptorSet
    Type
    FileDescriptorSet
    Description

    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.

public static String explain(Throwable error)
gRPC codeExplanation
UNAUTHENTICATEDMissing or invalid API key.
PERMISSION_DENIEDThis API key does not have permission to inspect gRPC schemas.
NOT_FOUNDNo protobuf schema found for the requested symbol. Fetch without symbols to list the available services.
UNIMPLEMENTEDThe gRPC endpoint does not expose server reflection.
UNAVAILABLECould not reach the gRPC endpoint. Check the address, network access, and TLS settings.
DEADLINE_EXCEEDEDTimed 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.

public SchemaException(String message, Status.@Nullable Code code, @Nullable Throwable cause)
  • Name
    code
    Type
    Status.Code
    Description

    The gRPC status code of the failure, or null when the failure did not come from gRPC.

Previous
Next