v4

gRPC schema

View as markdown

Fetch the protobuf schema of the Synthient gRPC API.

The @synthient/synthient/grpcschema entry point fetches the protobuf schema of the Synthient gRPC API using gRPC server reflection. It needs the optional peer dependencies @grpc/grpc-js and @bufbuild/protobuf, and importing it without them fails:

npm install @grpc/grpc-js @bufbuild/protobuf

fetchSchema

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.

function fetchSchema(options?: FetchSchemaOptions): Promise<Schema>;

import { SchemaError, explain, fetchSchema } from "@synthient/synthient/grpcschema";

try {
  const schema = await fetchSchema();
  for (const file of schema.descriptorSet.file) {
    console.log(file.name, file.package);
  }
} catch (error) {
  const explanation = explain(error);
  if (error instanceof SchemaError && explanation !== "") {
    throw new Error(`${explanation} ${error.message}`, { cause: error });
  }
  throw error;
}
  • Errors: Errors from the gRPC call or the reflection responses reject with a SchemaError, invalid options with a TypeError or RangeError, and a canceled signal with its reason.

FetchSchemaOptions

With no options, fetchSchema fetches every service from DEFAULT_ENDPOINT over TLS, sending the key from SYNTHIENT_API_KEY if it is set.

  • Name
    apiKey?
    Type
    string | undefined
    Description

    Sent as x-api-key metadata when not empty. Defaults to the SYNTHIENT_API_KEY environment variable.

  • Name
    endpoint?
    Type
    string | undefined
    Description

    The server as host:port, a bare host (port 443 is assumed), or a grpc:// or https:// URL. Defaults to DEFAULT_ENDPOINT.

  • Name
    plaintext?
    Type
    boolean | undefined
    Description

    Disables TLS, for local development servers.

  • Name
    symbols?
    Type
    Iterable<string> | undefined
    Description

    Fully qualified service or message names to resolve. Empty resolves every listed service except the grpc.reflection services.

  • Name
    signal?
    Type
    AbortSignal | undefined
    Description

    Cancels the fetch, which rejects with the signal's reason.

  • Name
    timeout?
    Type
    number | undefined
    Description

    Milliseconds allowed for the whole fetch. Defaults to 30_000. It must be an integer from 1 to 2147483647.

Schema

The protobuf schema returned by fetchSchema.

  • Name
    endpoint
    Type
    string
    Description

    The normalized address that was queried.

  • Name
    symbols
    Type
    string[]
    Description

    The service or message names that were resolved.

  • Name
    descriptorSet
    Type
    FileDescriptorSet
    Description

    The resolved files in dependency order, each file after the files it imports. FileDescriptorSet comes from @bufbuild/protobuf/wkt.

SchemaError

Fetching the schema failed. explain describes common causes. It extends SynthientError, and its name is "SchemaError".

  • Name
    code
    Type
    number | undefined
    Description

    The gRPC status code, as in status from @grpc/grpc-js, or undefined when the failure was not a gRPC status.

constructor(message: string, code?: number, options?: ErrorOptions);

explain

Returns a human-readable explanation of a common fetchSchema error, or "" if it has none, including for any error that is not a SchemaError.

function explain(error: unknown): string;
gRPC statusExplanation
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.

normalizeEndpoint

Converts raw to host:port form and returns it with the host name used for TLS.

function normalizeEndpoint(raw: string): {
  endpoint: string;
  host: string;
};
  • Input: It accepts host:port, a bare host (port 443 is assumed), and grpc:// or https:// URLs. An empty raw uses DEFAULT_ENDPOINT.

The address of the Synthient gRPC API.

const DEFAULT_ENDPOINT = "grpc.synthient.com:443";
Previous
Next