# README
gRPC-Go
The Go implementation of gRPC: A high performance, open source, general RPC framework that puts mobile and HTTP/2 first. For more information see the gRPC Quick Start: Go guide.
Installation
To install this package, you need to install Go and setup your Go workspace on your computer. The simplest way to install the library is to run:
$ go get -u google.golang.org/grpc
Prerequisites
This requires Go 1.6 or later. Go 1.7 will be required soon.
Constraints
The grpc package should only depend on standard Go packages and a small number of exceptions. If your contribution introduces new dependencies which are NOT in the list, you need a discussion with gRPC-Go authors and consultants.
Documentation
See API documentation for package and API descriptions and find examples in the examples directory.
Performance
See the current benchmarks for some of the languages supported in this dashboard.
Status
General Availability Google Cloud Platform Launch Stages.
FAQ
Compiling error, undefined: grpc.SupportPackageIsVersion
Please update proto package, gRPC package and rebuild the proto files:
go get -u github.com/golang/protobuf/{proto,protoc-gen-go}go get -u google.golang.org/grpcprotoc --go_out=plugins=grpc:. *.proto
# Packages
Package balancer defines APIs for load balancing in gRPC.
Package benchmark implements the building blocks to setup end-to-end gRPC benchmarks.
No description provided by the author
Package codes defines the canonical error codes used by gRPC.
Package connectivity defines connectivity semantics.
Package credentials implements various credentials supported by gRPC library, which encapsulate all the state needed by a client to authenticate with a server and make various assertions, e.g., about the client's identity, role, or whether it is authorized to make a particular call.
Package encoding defines the interface for the compressor and codec, and functions to register and retrieve compressors and codecs.
No description provided by the author
Package grpclog defines logging for grpc.
Package health provides some utility functions to health-check a server.
No description provided by the author
Package keepalive defines configurable parameters for point-to-point healthcheck.
Package metadata define the structure of the metadata supported by gRPC library.
Package naming defines the naming API and related data structures for gRPC.
Package peer defines various peer information associated with RPCs and corresponding utils.
Package reflection implements server reflection service.
Package resolver defines APIs for name resolution in gRPC.
Package stats is for collecting and reporting various network and RPC stats.
Package status implements errors returned by gRPC.
No description provided by the author
Package tap defines the function handles which are executed on the transport layer of gRPC-Go and related information.
No description provided by the author
# Functions
CallContentSubtype returns a CallOption that will set the content-subtype for a call.
CallCustomCodec returns a CallOption that will set the given Codec to be used for all request and response messages for a call.
Code returns the error code for err if it was produced by the rpc system.
ConnectionTimeout returns a ServerOption that sets the timeout for connection establishment (up to and including HTTP/2 handshaking) for all new connections.
Creds returns a ServerOption that sets credentials for server connections.
CustomCodec returns a ServerOption that sets a codec for message marshaling and unmarshaling.
Dial creates a client connection to the given target.
DialContext creates a client connection to the given target.
ErrorDesc returns the error description of err if it was produced by the rpc system.
Errorf returns an error containing an error code and a description; Errorf returns nil if c is OK.
FailFast configures the action to take when an RPC is attempted on broken connections or unreachable servers.
FailOnNonTempDialError returns a DialOption that specifies if gRPC fails on non-temporary dial errors.
Header returns a CallOptions that retrieves the header metadata for a unary RPC.
InitialConnWindowSize returns a ServerOption that sets window size for a connection.
InitialWindowSize returns a ServerOption that sets window size for stream.
InTapHandle returns a ServerOption that sets the tap handle for all the server transport to be created.
Invoke sends the RPC request on the wire and returns after response is received.
KeepaliveEnforcementPolicy returns a ServerOption that sets keepalive enforcement policy for the server.
KeepaliveParams returns a ServerOption that sets keepalive and max-age parameters for the server.
MaxCallRecvMsgSize returns a CallOption which sets the maximum message size the client can receive.
MaxCallSendMsgSize returns a CallOption which sets the maximum message size the client can send.
MaxConcurrentStreams returns a ServerOption that will apply a limit on the number of concurrent streams to each ServerTransport.
MaxHeaderListSize returns a ServerOption that sets the max (uncompressed) size of header list that the server is prepared to accept.
MaxMsgSize returns a ServerOption to set the max message size in bytes the server can receive.
MaxRecvMsgSize returns a ServerOption to set the max message size in bytes the server can receive.
MaxRetryRPCBufferSize returns a CallOption that limits the amount of memory used for buffering this RPC's requests for retry purposes.
MaxSendMsgSize returns a ServerOption to set the max message size in bytes the server can send.
Method returns the method string for the server context.
MethodFromServerStream returns the method string for the input stream.
NewClientStream is a wrapper for ClientConn.NewStream.
NewContextWithServerTransportStream creates a new context from ctx and attaches stream to it.
NewGZIPCompressor creates a Compressor based on GZIP.
NewGZIPCompressorWithLevel is like NewGZIPCompressor but specifies the gzip compression level instead of assuming DefaultCompression.
NewGZIPDecompressor creates a Decompressor based on GZIP.
NewServer creates a gRPC server which has no service registered and has not started to accept requests yet.
Peer returns a CallOption that retrieves peer information for a unary RPC.
PerRPCCredentials returns a CallOption that sets credentials.PerRPCCredentials for a call.
ReadBufferSize lets you set the size of read buffer, this determines how much data can be read at most for one read syscall.
RegisterChannelz turns on channelz service.
RoundRobin returns a Balancer that selects addresses round-robin.
RPCCompressor returns a ServerOption that sets a compressor for outbound messages.
RPCDecompressor returns a ServerOption that sets a decompressor for inbound messages.
SendHeader sends header metadata.
ServerTransportStreamFromContext returns the ServerTransportStream saved in ctx.
SetHeader sets the header metadata.
SetTrailer sets the trailer metadata that will be sent when an RPC returns.
StatsHandler returns a ServerOption that sets the stats handler for the server.
StreamInterceptor returns a ServerOption that sets the StreamServerInterceptor for the server.
Trailer returns a CallOptions that retrieves the trailer metadata for a unary RPC.
UnaryInterceptor returns a ServerOption that sets the UnaryServerInterceptor for the server.
UnknownServiceHandler returns a ServerOption that allows for adding a custom unknown service handler.
UseCompressor returns a CallOption which sets the compressor used when sending the request.
WithAuthority returns a DialOption that specifies the value to be used as the :authority pseudo-header.
WithBackoffConfig configures the dialer to use the provided backoff parameters after connection failures.
WithBackoffMaxDelay configures the dialer to use the provided maximum delay when backing off after failed connection attempts.
WithBalancer returns a DialOption which sets a load balancer with the v1 API.
WithBalancerName sets the balancer that the ClientConn will be initialized with.
WithBlock returns a DialOption which makes caller of Dial blocks until the underlying connection is up.
WithChannelzParentID returns a DialOption that specifies the channelz ID of current ClientConn's parent.
WithCodec returns a DialOption which sets a codec for message marshaling and unmarshaling.
WithCompressor returns a DialOption which sets a Compressor to use for message compression.
WithDecompressor returns a DialOption which sets a Decompressor to use for incoming message decompression.
WithDefaultCallOptions returns a DialOption which sets the default CallOptions for calls over the connection.
WithDialer returns a DialOption that specifies a function to use for dialing network addresses.
WithDisableRetry returns a DialOption that disables retries, even if the service config enables them.
WithDisableServiceConfig returns a DialOption that causes grpc to ignore any service config provided by the resolver and provides a hint to the resolver to not fetch service configs.
WithInitialConnWindowSize returns a DialOption which sets the value for initial window size on a connection.
WithInitialWindowSize returns a DialOption which sets the value for initial window size on a stream.
WithInsecure returns a DialOption which disables transport security for this ClientConn.
WithKeepaliveParams returns a DialOption that specifies keepalive parameters for the client transport.
WithMaxHeaderListSize returns a DialOption that specifies the maximum (uncompressed) size of header list that the client is prepared to accept.
WithMaxMsgSize returns a DialOption which sets the maximum message size the client can receive.
WithPerRPCCredentials returns a DialOption which sets credentials and places auth state on each outbound RPC.
WithReadBufferSize lets you set the size of read buffer, this determines how much data can be read at most for each read syscall.
WithServiceConfig returns a DialOption which has a channel to read the service configuration.
WithStatsHandler returns a DialOption that specifies the stats handler for all the RPCs and underlying network connections in this ClientConn.
WithStreamInterceptor returns a DialOption that specifies the interceptor for streaming RPCs.
WithTimeout returns a DialOption that configures a timeout for dialing a ClientConn initially.
WithTransportCredentials returns a DialOption which configures a connection level security credentials (e.g., TLS/SSL).
WithUnaryInterceptor returns a DialOption that specifies the interceptor for unary RPCs.
WithUserAgent returns a DialOption that specifies a user agent string for all the RPCs.
WithWaitForHandshake blocks until the initial settings frame is received from the server before assigning RPCs to the connection.
WithWriteBufferSize determines how much data can be batched before doing a write on the wire.
WriteBufferSize determines how much data can be batched before doing a write on the wire.
# Constants
PickFirstBalancerName is the name of the pick_first balancer.
The SupportPackageIsVersion variables are referenced from generated protocol buffer files to ensure compatibility with the gRPC version used.
The SupportPackageIsVersion variables are referenced from generated protocol buffer files to ensure compatibility with the gRPC version used.
The SupportPackageIsVersion variables are referenced from generated protocol buffer files to ensure compatibility with the gRPC version used.
Version is the current grpc version.
# Variables
DefaultBackoffConfig uses values specified for backoff in https://github.com/grpc/grpc/blob/master/doc/connection-backoff.md.
EnableTracing controls whether to trace RPCs using the golang.org/x/net/trace package.
ErrClientConnClosing indicates that the operation is illegal because the ClientConn is closing.
ErrClientConnTimeout indicates that the ClientConn cannot establish the underlying connections within the specified timeout.
ErrServerStopped indicates that the operation is now illegal because of the server being stopped.
# Structs
Address represents a server the client connects to.
BackoffConfig defines the parameters for the default gRPC backoff strategy.
BalancerConfig specifies the configurations for Balancer.
BalancerGetOptions configures a Get call.
ClientConn represents a client connection to an RPC server.
CompressorCallOption is a CallOption that indicates the compressor to use.
ContentSubtypeCallOption is a CallOption that indicates the content-subtype used for marshaling messages.
CustomCodecCallOption is a CallOption that indicates the codec used for marshaling messages.
EmptyCallOption does not alter the Call configuration.
EmptyDialOption does not alter the dial configuration.
FailFastCallOption is a CallOption for indicating whether an RPC should fail fast or not.
HeaderCallOption is a CallOption for collecting response header metadata.
MaxRecvMsgSizeCallOption is a CallOption that indicates the maximum message size the client can receive.
MaxRetryRPCBufferSizeCallOption is a CallOption indicating the amount of memory to be used for caching this RPC for retry purposes.
MaxSendMsgSizeCallOption is a CallOption that indicates the maximum message size the client can send.
MethodConfig defines the configuration recommended by the service providers for a particular method.
MethodDesc represents an RPC service's method specification.
MethodInfo contains the information of an RPC including its method name and type.
PeerCallOption is a CallOption for collecting the identity of the remote peer.
PerRPCCredsCallOption is a CallOption that indicates the per-RPC credentials to use for the call.
Server is a gRPC server to serve RPC requests.
ServiceConfig is provided by the service provider and contains parameters for how clients that connect to the service should behave.
ServiceDesc represents an RPC service's specification.
ServiceInfo contains unary RPC method info, streaming RPC method info and metadata for a service.
StreamDesc represents a streaming RPC service's method specification.
StreamServerInfo consists of various information about a streaming RPC on server side.
TrailerCallOption is a CallOption for collecting response trailer metadata.
UnaryServerInfo consists of various information about a unary RPC on server side.
# Interfaces
Balancer chooses network addresses for RPCs.
CallOption configures a Call before it starts or extracts information from a Call after it completes.
ClientStream defines the client-side behavior of a streaming RPC.
Codec defines the interface gRPC uses to encode and decode messages.
Compressor defines the interface gRPC uses to compress a message.
Decompressor defines the interface gRPC uses to decompress a message.
DialOption configures how we set up the connection.
ServerStream defines the server-side behavior of a streaming RPC.
ServerTransportStream is a minimal interface that a transport stream must implement.
Stream defines the common interface a client or server stream has to satisfy.
# Type aliases
A ServerOption sets options such as credentials, codec and keepalive parameters, etc.
StreamClientInterceptor intercepts the creation of ClientStream.
Streamer is called by StreamClientInterceptor to create a ClientStream.
StreamHandler defines the handler called by gRPC server to complete the execution of a streaming RPC.
StreamServerInterceptor provides a hook to intercept the execution of a streaming RPC on the server.
UnaryClientInterceptor intercepts the execution of a unary RPC on the client.
UnaryHandler defines the handler invoked by UnaryServerInterceptor to complete the normal execution of a unary RPC.
UnaryInvoker is called by UnaryClientInterceptor to complete RPCs.
UnaryServerInterceptor provides a hook to intercept the execution of a unary RPC on the server.