Generated-code reference

This page describes the code generated when compiling .proto files with protoc, using the protoc-gen-go-grpc grpc plugin. This latest version of generated code uses generics by default. If you’re working with older generated code that doesn’t use generics, you can find the relevant documentation here. While we encourage using this latest version with generics, you can temporarily revert to the old behavior by setting the useGenericStreams flag to false.

You can find out how to define a gRPC service in a .proto file in Service definition.

Thread-safety: note that client-side RPC invocations and server-side RPC handlers are thread-safe and are meant to be run on concurrent goroutines. But also note that for individual streams, incoming and outgoing data is bi-directional but serial; so e.g. individual streams do not support concurrent reads or concurrent writes (but reads are safely concurrent with writes).

Methods on generated server interfaces

On the server side, each service Bar in the .proto file results in the function:

func RegisterBarServer(s *grpc.Server, srv BarServer)

The application can define a concrete implementation of the BarServer interface and register it with a grpc.Server instance (before starting the server instance) by using this function.

Unary methods

These methods have the following signature on the generated service interface:

Foo(context.Context, *RequestMsg) (*ResponseMsg, error)

In this context, RequestMsg is the protobuf message sent from the client, and ResponseMsg is the protobuf message sent back from the server.

Server-streaming methods

These methods have the following signature on the generated service interface: Foo(*RequestMsg, grpc.ServerStreamingServer[*ResponseMsg]) error

In this context, RequestMsg is the single request from the client, and grpc.ServerStreamingServer represents the server side of server-to-client stream of response type ResponseMsg.

Refer to grpc.ServerStreamingServer documentation for detailed usage information.

Client-streaming methods

These methods have the following signature on the generated service interface:

Foo(grpc.ClientStreamingServer[*RequestMsg, *ResponseMsg]) error

Where RequestMsg is the message type of the stream, sent from client-to-server and ResponseMsg is the type of response from server to client.

In this context, grpc.ClientStreamingServer can be used both to read the client-to-server message stream and to send the single server response message.

Refer to grpc.ClientStreamingServer documentation for detailed usage information.

Bidi-streaming methods

These methods have the following signature on the generated service interface:

Foo(grpc.BidiStreamingServer[*RequestMsg, *ResponseMsg]) error

Where RequestMsg is the message type of the stream, sent from client-to-server and ResponseMsg is the type of stream from server-to-client.

In this context, grpc.BidiStreamingServer can be used to access both the client-to-server message stream and the server-to-client message stream.

Refer to grpc.BidiStreamingServer documentation for detailed usage information.

Methods on generated client interfaces

For client side usage, each service Bar in the .proto file also results in the function: func BarClient(cc *grpc.ClientConn) BarClient, which returns a concrete implementation of the BarClient interface (this concrete implementation also lives in the generated .pb.go file).

Unary Methods

These methods have the following signature on the generated client stub:

(ctx context.Context, in *RequestMsg, opts ...grpc.CallOption) (*ResponseMsg, error)

In this context, RequestMsg is the single request from client to server, and ResponseMsg contains the response sent back from the server.

Server-Streaming methods

These methods have the following signature on the generated client stub:

Foo(ctx context.Context, in *RequestMsg, opts ...grpc.CallOption) (grpc.ServerStreamingClient[*ResponseMsg], error)

In this context, grpc.ServerStreamingClient represents the client side of server-to-client stream of ResponseMsg messages.

Refer to grpc.ServerStreamingClient documentation for detailed usage information.

Client-Streaming methods

These methods have the following signature on the generated client stub:

Foo(ctx context.Context, opts ...grpc.CallOption) (grpc.ClientStreamingClient[*RequestMsg, *ResponseMsg], error)

In this context, grpc.ClientStreamingClient represents the client side of client-to-server stream of RequestMsg messages. It can be used both to send the client-to-server message stream and to receive the single server response message.

Refer to grpc.ClientStreamingClient documentation for detailed usage information.

Bidi-Streaming methods

These methods have the following signature on the generated client stub:

Foo(ctx context.Context, opts ...grpc.CallOption) (grpc.BidiStreamingClient[*RequestMsg, *ResponseMsg], error)

In this context, grpc.BidiStreamingClient represents both the client-to-server and server-to-client message streams.

Refer to grpc.BidiStreamingClient documentation for detailed usage information.

Packages and Namespaces

When the protoc compiler is invoked with --go_out=plugins=grpc:, the proto package to Go package translation works the same as when the protoc-gen-go plugin is used without the grpc plugin.

So, for example, if foo.proto declares itself to be in package foo, then the generated foo.pb.go file will also be in the Go package foo.