v4

gRPC schema

View as markdown

Fetch the protobuf schema of the Synthient gRPC API.

The grpcschema package fetches the protobuf schema of the Synthient gRPC API using gRPC server reflection.

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.

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

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.

  • Name
    Endpoint
    Type
    string
    Description

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

  • Name
    Plaintext
    Type
    bool
    Description

    Disables TLS, for local development servers.

  • Name
    Symbols
    Type
    []string
    Description

    Fully qualified service or message names to resolve. Empty resolves every service the server lists, except the reflection service itself.

Schema

  • 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
    *descriptorpb.FileDescriptorSet
    Description

    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.

func Explain(err error) string
gRPC codeExplanation
UnauthenticatedMissing or invalid API key.
PermissionDeniedThis API key does not have permission to inspect gRPC schemas.
NotFoundNo 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.
DeadlineExceededTimed out reading protobuf schemas from gRPC reflection. Use a longer context deadline.
Previous
Next