func ClientSupportedCompressors(ctxcontext.Context) ([]string,error)

func Invoke(ctxcontext.Context, methodstring, args, replyany, cc *ClientConn, opts ...CallOption)error

func Method(ctxcontext.Context) (string,bool)

func MethodFromServerStream(streamServerStream) (string,bool)

func NewContextWithServerTransportStream(ctxcontext.Context, streamServerTransportStream)context.Context

func SendHeader(ctxcontext.Context, mdmetadata.MD)error

func SetHeader(ctxcontext.Context, mdmetadata.MD)error

func SetSendCompressor(ctxcontext.Context, namestring)error

func SetTrailer(ctxcontext.Context, mdmetadata.MD)error

type BidiStreamingClient[Reqany, Resany] interface {// Send sends a request message to the server.  The client may call Send// multiple times to send multiple messages to the server.  On error, Send// aborts the stream.  If the error was generated by the client, the status// is returned directly.  Otherwise, io.EOF is returned, and the status of// the stream may be discovered using Recv().Send(*Req)error// Recv receives the next response message from the server. The client may// repeatedly call Recv to read messages from the response stream.  If// io.EOF is returned, the stream has terminated with an OK status.  Any// other error is compatible with the status package and indicates the// RPC's status code and message.Recv() (*Res,error)// ClientStream is embedded to provide Context, Header, Trailer, and// CloseSend functionality.  No other methods in the ClientStream should be// called directly.ClientStream}

type BidiStreamingServer[Reqany, Resany] interface {// Recv receives the next request message from the client.  The server may// repeatedly call Recv to read messages from the request stream.  If// io.EOF is returned, it indicates the client called CloseSend on its// BidiStreamingClient.  Any other error indicates the stream was// terminated unexpectedly, and the handler method should return, as the// stream is no longer usable.Recv() (*Req,error)// Send sends a response message to the client.  The server handler may// call Send multiple times to send multiple messages to the client.  An// error is returned if the stream was terminated unexpectedly, and the// handler method should return, as the stream is no longer usable.Send(*Res)error// ServerStream is embedded to provide Context, SetHeader, SendHeader, and// SetTrailer functionality.  No other methods in the ServerStream should// be called directly.ServerStream}

type CallOption interface {// contains filtered or unexported methods}

funcCallContentSubtype¶added inv1.10.0

func CallContentSubtype(contentSubtypestring)CallOption

CallContentSubtype returns a CallOption that will set the content-subtypefor a call. For example, if content-subtype is "json", the Content-Type overthe wire will be "application/grpc+json". The content-subtype is convertedto lowercase before being included in Content-Type. See Content-Type onhttps://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md#requests formore details.

If ForceCodec is not also used, the content-subtype will be used to look upthe Codec to use in the registry controlled by RegisterCodec. See thedocumentation on RegisterCodec for details on registration. The lookup ofcontent-subtype is case-insensitive. If no such Codec is found, the callwill result in an error with code codes.Internal.

If ForceCodec is also used, that Codec will be used for all request andresponse messages, with the content-subtype set to the given contentSubtypehere for requests.

funcForceCodec¶added inv1.19.0

func ForceCodec(codecencoding.Codec)CallOption

ForceCodec returns a CallOption that will set codec to be used for allrequest and response messages for a call. The result of calling Name() willbe used as the content-subtype after converting to lowercase, unlessCallContentSubtype is also used.

See Content-Type onhttps://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md#requests formore details. Also see the documentation on RegisterCodec andCallContentSubtype for more details on the interaction between Codec andcontent-subtype.

This function is provided for advanced users; prefer to use onlyCallContentSubtype to select a registered codec instead.

Experimental¶

Notice: This API is EXPERIMENTAL and may be changed or removed in alater release.

funcForceCodecV2¶added inv1.66.0

func ForceCodecV2(codecencoding.CodecV2)CallOption

ForceCodecV2 returns a CallOption that will set codec to be used for allrequest and response messages for a call. The result of calling Name() willbe used as the content-subtype after converting to lowercase, unlessCallContentSubtype is also used.

See Content-Type onhttps://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md#requests formore details. Also see the documentation on RegisterCodec andCallContentSubtype for more details on the interaction between Codec andcontent-subtype.

This function is provided for advanced users; prefer to use onlyCallContentSubtype to select a registered codec instead.

Experimental¶

Notice: This API is EXPERIMENTAL and may be changed or removed in alater release.

funcHeader¶

func Header(md *metadata.MD)CallOption

Header returns a CallOptions that retrieves the header metadatafor a unary RPC.

funcMaxCallRecvMsgSize¶added inv1.4.0

func MaxCallRecvMsgSize(bytesint)CallOption

MaxCallRecvMsgSize returns a CallOption which sets the maximum message sizein bytes the client can receive. If this is not set, gRPC uses the default4MB.

funcMaxCallSendMsgSize¶added inv1.4.0

func MaxCallSendMsgSize(bytesint)CallOption

MaxCallSendMsgSize returns a CallOption which sets the maximum message sizein bytes the client can send. If this is not set, gRPC uses the default`math.MaxInt32`.

funcMaxRetryRPCBufferSize¶added inv1.14.0

func MaxRetryRPCBufferSize(bytesint)CallOption

MaxRetryRPCBufferSize returns a CallOption that limits the amount of memoryused for buffering this RPC's requests for retry purposes.

Experimental¶

Notice: This API is EXPERIMENTAL and may be changed or removed in alater release.

funcOnFinish¶added inv1.54.0

func OnFinish(onFinish func(errerror))CallOption

OnFinish returns a CallOption that configures a callback to be called whenthe call completes. The error passed to the callback is the status of theRPC, and may be nil. The onFinish callback provided will only be called onceby gRPC. This is mainly used to be used by streaming interceptors, to benotified when the RPC completes along with information about the status ofthe RPC.

Experimental¶

Notice: This API is EXPERIMENTAL and may be changed or removed in alater release.

funcPeer¶added inv1.2.0

func Peer(p *peer.Peer)CallOption

Peer returns a CallOption that retrieves peer information for a unary RPC.The peer field will be populated *after* the RPC completes.

funcPerRPCCredentials¶added inv1.4.0

func PerRPCCredentials(credscredentials.PerRPCCredentials)CallOption

PerRPCCredentials returns a CallOption that sets credentials.PerRPCCredentialsfor a call.

funcStaticMethod¶added inv1.62.0

func StaticMethod()CallOption

StaticMethod returns a CallOption which specifies that a call is being madeto a method that is static, which means the method is known at compile timeand doesn't change at runtime. This can be used as a signal to stats pluginsthat this method is safe to include as a key to a measurement.

funcTrailer¶

func Trailer(md *metadata.MD)CallOption

Trailer returns a CallOptions that retrieves the trailer metadatafor a unary RPC.

funcUseCompressor¶added inv1.8.0

func UseCompressor(namestring)CallOption

UseCompressor returns a CallOption which sets the compressor used whensending the request. If WithCompressor is also set, UseCompressor hashigher priority.

Experimental¶

Notice: This API is EXPERIMENTAL and may be changed or removed in alater release.

funcWaitForReady¶added inv1.18.0

func WaitForReady(waitForReadybool)CallOption

WaitForReady configures the RPC's behavior when the client is inTRANSIENT_FAILURE, which occurs when all addresses fail to connect. IfwaitForReady is false, the RPC will fail immediately. Otherwise, the clientwill wait until a connection becomes available or the RPC's deadline isreached.

By default, RPCs do not "wait for ready".

type ClientConn struct {// contains filtered or unexported fields}

funcNewClient¶added inv1.63.0

func NewClient(targetstring, opts ...DialOption) (conn *ClientConn, errerror)

NewClient creates a new gRPC "channel" for the target URI provided. No I/Ois performed. Use of the ClientConn for RPCs will automatically cause it toconnect. The Connect method may be called to manually create a connection,but for most users this should be unnecessary.

The target name syntax is defined inhttps://github.com/grpc/grpc/blob/master/doc/naming.md. E.g. to use the dnsname resolver, a "dns:///" prefix may be applied to the target. The defaultname resolver will be used if no scheme is detected, or if the parsed schemeis not a registered name resolver. The default resolver is "dns" but can beoverridden using the resolver package's SetDefaultScheme.

Examples:

• "foo.googleapis.com:8080"
• "dns:///foo.googleapis.com:8080"
• "dns:///foo.googleapis.com"
• "dns:///10.0.0.213:8080"
• "dns:///%5B2001:db8:85a3:8d3:1319:8a2e:370:7348%5D:443"
• "dns://8.8.8.8/foo.googleapis.com:8080"
• "dns://8.8.8.8/foo.googleapis.com"
• "zookeeper://zk.example.com:9900/example_service"

The DialOptions returned by WithBlock, WithTimeout,WithReturnConnectionError, and FailOnNonTempDialError are ignored by thisfunction.

func (*ClientConn)CanonicalTarget¶added inv1.63.0

func (cc *ClientConn) CanonicalTarget()string

CanonicalTarget returns the canonical target string used when creating cc.

This always has the form "<scheme>://[authority]/<endpoint>". For example:

• "dns:///example.com:42"
• "dns://8.8.8.8/example.com:42"
• "unix:///path/to/socket"

func (*ClientConn)Close¶

func (cc *ClientConn) Close()error

Close tears down the ClientConn and all underlying connections.

func (*ClientConn)Connect¶added inv1.41.0

func (cc *ClientConn) Connect()

Connect causes all subchannels in the ClientConn to attempt to connect ifthe channel is idle. Does not wait for the connection attempts to beginbefore returning.

Experimental¶

Notice: This API is EXPERIMENTAL and may be changed or removed in a laterrelease.

func (*ClientConn)GetMethodConfig¶added inv1.4.0

func (cc *ClientConn) GetMethodConfig(methodstring)MethodConfig

GetMethodConfig gets the method config of the input method.If there's an exact match for input method (i.e. /service/method), we returnthe corresponding MethodConfig.If there isn't an exact match for the input method, we look for the service's defaultconfig under the service (i.e /service/) and then for the default for all services (empty string).

If there is a default MethodConfig for the service, we return it.Otherwise, we return an empty MethodConfig.

func (*ClientConn)GetState¶added inv1.5.2

func (cc *ClientConn) GetState()connectivity.State

GetState returns the connectivity.State of ClientConn.

func (*ClientConn)Invoke¶added inv1.8.0

func (cc *ClientConn) Invoke(ctxcontext.Context, methodstring, args, replyany, opts ...CallOption)error

Invoke sends the RPC request on the wire and returns after response isreceived. This is typically called by generated code.

All errors returned by Invoke are compatible with the status package.

func (*ClientConn)NewStream¶added inv1.8.0

func (cc *ClientConn) NewStream(ctxcontext.Context, desc *StreamDesc, methodstring, opts ...CallOption) (ClientStream,error)

NewStream creates a new Stream for the client side. This is typicallycalled by generated code. ctx is used for the lifetime of the stream.

To ensure resources are not leaked due to the stream returned, one of the followingactions must be performed:

1. Call Close on the ClientConn.
2. Cancel the context provided.
3. Call RecvMsg until a non-nil error is returned. A protobuf-generatedclient-streaming RPC, for instance, might use the helper functionCloseAndRecv (note that CloseSend does not Recv, therefore is notguaranteed to release all resources).
4. Receive a non-nil, non-io.EOF error from Header or SendMsg.

If none of the above happen, a goroutine and a context will be leaked, and grpcwill not call the optionally-configured stats handler with a stats.End message.

func (*ClientConn)ResetConnectBackoff¶added inv1.15.0

func (cc *ClientConn) ResetConnectBackoff()

ResetConnectBackoff wakes up all subchannels in transient failure and causesthem to attempt another connection immediately. It also resets the backofftimes used for subsequent attempts regardless of the current state.

In general, this function should not be used. Typical service or networkoutages result in a reasonable client reconnection strategy by default.However, if a previously unavailable network becomes available, this may beused to trigger an immediate reconnect.

Experimental¶

Notice: This API is EXPERIMENTAL and may be changed or removed in alater release.

func (*ClientConn)Target¶added inv1.14.0

func (cc *ClientConn) Target()string

Target returns the target string of the ClientConn.

func (*ClientConn)WaitForStateChange¶added inv1.5.2

func (cc *ClientConn) WaitForStateChange(ctxcontext.Context, sourceStateconnectivity.State)bool

WaitForStateChange waits until the connectivity.State of ClientConn changes from sourceState orctx expires. A true value is returned in former case and false in latter.

type ClientConnInterface interface {// Invoke performs a unary RPC and returns after the response is received// into reply.Invoke(ctxcontext.Context, methodstring, argsany, replyany, opts ...CallOption)error// NewStream begins a streaming RPC.NewStream(ctxcontext.Context, desc *StreamDesc, methodstring, opts ...CallOption) (ClientStream,error)}

type ClientStream interface {// Header returns the header metadata received from the server if there// is any. It blocks if the metadata is not ready to read.  If the metadata// is nil and the error is also nil, then the stream was terminated without// headers, and the status can be discovered by calling RecvMsg.Header() (metadata.MD,error)// Trailer returns the trailer metadata from the server, if there is any.// It must only be called after stream.CloseAndRecv has returned, or// stream.Recv has returned a non-nil error (including io.EOF).Trailer()metadata.MD// CloseSend closes the send direction of the stream. It closes the stream// when non-nil error is met. It is also not safe to call CloseSend// concurrently with SendMsg.CloseSend()error// Context returns the context for this stream.//// It should not be called until after Header or RecvMsg has returned. Once// called, subsequent client-side retries are disabled.Context()context.Context// SendMsg is generally called by generated code. On error, SendMsg aborts// the stream. If the error was generated by the client, the status is// returned directly; otherwise, io.EOF is returned and the status of// the stream may be discovered using RecvMsg. For unary or server-streaming// RPCs (StreamDesc.ClientStreams is false), a nil error is returned// unconditionally.//// SendMsg blocks until://   - There is sufficient flow control to schedule m with the transport, or//   - The stream is done, or//   - The stream breaks.//// SendMsg does not wait until the message is received by the server. An// untimely stream closure may result in lost messages. To ensure delivery,// users should ensure the RPC completed successfully using RecvMsg.//// It is safe to have a goroutine calling SendMsg and another goroutine// calling RecvMsg on the same stream at the same time, but it is not safe// to call SendMsg on the same stream in different goroutines. It is also// not safe to call CloseSend concurrently with SendMsg.//// It is not safe to modify the message after calling SendMsg. Tracing// libraries and stats handlers may use the message lazily.SendMsg(many)error// RecvMsg blocks until it receives a message into m or the stream is// done. It returns io.EOF when the stream completes successfully. On// any other error, the stream is aborted and the error contains the RPC// status.//// It is safe to have a goroutine calling SendMsg and another goroutine// calling RecvMsg on the same stream at the same time, but it is not// safe to call RecvMsg on the same stream in different goroutines.RecvMsg(many)error}

funcNewClientStream¶

func NewClientStream(ctxcontext.Context, desc *StreamDesc, cc *ClientConn, methodstring, opts ...CallOption) (ClientStream,error)

NewClientStream is a wrapper for ClientConn.NewStream.

type ClientStreamingClient[Reqany, Resany] interface {// Send sends a request message to the server.  The client may call Send// multiple times to send multiple messages to the server.  On error, Send// aborts the stream.  If the error was generated by the client, the status// is returned directly.  Otherwise, io.EOF is returned, and the status of// the stream may be discovered using CloseAndRecv().Send(*Req)error// CloseAndRecv closes the request stream and waits for the server's// response.  This method must be called once and only once after sending// all request messages.  Any error returned is implemented by the status// package.CloseAndRecv() (*Res,error)// ClientStream is embedded to provide Context, Header, and Trailer// functionality.  No other methods in the ClientStream should be called// directly.ClientStream}

type ClientStreamingServer[Reqany, Resany] interface {// Recv receives the next request message from the client.  The server may// repeatedly call Recv to read messages from the request stream.  If// io.EOF is returned, it indicates the client called CloseAndRecv on its// ClientStreamingClient.  Any other error indicates the stream was// terminated unexpectedly, and the handler method should return, as the// stream is no longer usable.Recv() (*Req,error)// SendAndClose sends a single response message to the client and closes// the stream.  This method must be called once and only once after all// request messages have been processed.  Recv should not be called after// calling SendAndClose.SendAndClose(*Res)error// ServerStream is embedded to provide Context, SetHeader, SendHeader, and// SetTrailer functionality.  No other methods in the ServerStream should// be called directly.ServerStream}

type CompressorCallOption struct {CompressorTypestring}

type ConnectParams struct {// Backoff specifies the configuration options for connection backoff.Backoffbackoff.Config// MinConnectTimeout is the minimum amount of time we are willing to give a// connection to complete.MinConnectTimeouttime.Duration}

type ContentSubtypeCallOption struct {ContentSubtypestring}

type CustomCodecCallOption struct {CodecCodec}

type DialOption interface {// contains filtered or unexported methods}

funcWithAuthority¶added inv1.2.0

func WithAuthority(astring)DialOption

WithAuthority returns a DialOption that specifies the value to be used as the:authority pseudo-header and as the server name in authentication handshake.

funcWithChainStreamInterceptor¶added inv1.21.0

func WithChainStreamInterceptor(interceptors ...StreamClientInterceptor)DialOption

WithChainStreamInterceptor returns a DialOption that specifies the chainedinterceptor for streaming RPCs. The first interceptor will be the outer most,while the last interceptor will be the inner most wrapper around the real call.All interceptors added by this method will be chained, and the interceptordefined by WithStreamInterceptor will always be prepended to the chain.

funcWithChainUnaryInterceptor¶added inv1.21.0

func WithChainUnaryInterceptor(interceptors ...UnaryClientInterceptor)DialOption

WithChainUnaryInterceptor returns a DialOption that specifies the chainedinterceptor for unary RPCs. The first interceptor will be the outer most,while the last interceptor will be the inner most wrapper around the real call.All interceptors added by this method will be chained, and the interceptordefined by WithUnaryInterceptor will always be prepended to the chain.

funcWithChannelzParentID¶added inv1.12.0

func WithChannelzParentID(cchannelz.Identifier)DialOption

WithChannelzParentID returns a DialOption that specifies the channelz ID ofcurrent ClientConn's parent. This function is used in nested channel creation(e.g. grpclb dial).

Experimental¶

Notice: This API is EXPERIMENTAL and may be changed or removed in alater release.

funcWithConnectParams¶added inv1.25.0

func WithConnectParams(pConnectParams)DialOption

WithConnectParams configures the ClientConn to use the provided ConnectParamsfor creating and maintaining connections to servers.

The backoff configuration specified as part of the ConnectParams overridesall defaults specified inhttps://github.com/grpc/grpc/blob/master/doc/connection-backoff.md. Considerusing the backoff.DefaultConfig as a base, in cases where you want tooverride only a subset of the backoff configuration.

funcWithContextDialer¶added inv1.19.0

func WithContextDialer(f func(context.Context,string) (net.Conn,error))DialOption

WithContextDialer returns a DialOption that sets a dialer to createconnections. If FailOnNonTempDialError() is set to true, and an error isreturned by f, gRPC checks the error's Temporary() method to decide if itshould try to reconnect to the network address.

Note that gRPC by default performs name resolution on the target passed toNewClient. To bypass name resolution and cause the target string to bepassed directly to the dialer here instead, use the "passthrough" resolverby specifying it in the target string, e.g. "passthrough:target".

Note: All supported releases of Go (as of December 2023) override the OSdefaults for TCP keepalive time and interval to 15s. To enable TCP keepalivewith OS defaults for keepalive time and interval, use a net.Dialer that setsthe KeepAlive field to a negative value, and sets the SO_KEEPALIVE socketoption to true from the Control field. For a concrete example of how to dothis, see internal.NetDialerWithTCPKeepalive().

For more information, please seeissue 23459 in the Go GitHub repo.

funcWithCredentialsBundle¶added inv1.16.0

func WithCredentialsBundle(bcredentials.Bundle)DialOption

WithCredentialsBundle returns a DialOption to set a credentials bundle forthe ClientConn.WithCreds. This should not be used together withWithTransportCredentials.

Experimental¶

Notice: This API is EXPERIMENTAL and may be changed or removed in alater release.

funcWithDefaultCallOptions¶added inv1.4.0

func WithDefaultCallOptions(cos ...CallOption)DialOption

WithDefaultCallOptions returns a DialOption which sets the defaultCallOptions for calls over the connection.

funcWithDefaultServiceConfig¶added inv1.20.0

func WithDefaultServiceConfig(sstring)DialOption

WithDefaultServiceConfig returns a DialOption that configures the defaultservice config, which will be used in cases where:

1. WithDisableServiceConfig is also used, or

2. The name resolver does not provide a service config or provides aninvalid service config.

The parameter s is the JSON representation of the default service config.For more information about service configs, see:https://github.com/grpc/grpc/blob/master/doc/service_config.mdFor a simple example of usage, see:examples/features/load_balancing/client/main.go

funcWithDisableHealthCheck¶added inv1.17.0

func WithDisableHealthCheck()DialOption

WithDisableHealthCheck disables the LB channel health checking for allSubConns of this ClientConn.

Experimental¶

Notice: This API is EXPERIMENTAL and may be changed or removed in alater release.

funcWithDisableRetry¶added inv1.14.0

func WithDisableRetry()DialOption

WithDisableRetry returns a DialOption that disables retries, even if theservice config enables them. This does not impact transparent retries, whichwill happen automatically if no data is written to the wire or if the RPC isunprocessed by the remote server.

funcWithDisableServiceConfig¶added inv1.12.0

func WithDisableServiceConfig()DialOption

WithDisableServiceConfig returns a DialOption that causes gRPC to ignore anyservice config provided by the resolver and provides a hint to the resolverto not fetch service configs.

Note that this dial option only disables service config from resolver. Ifdefault service config is provided, gRPC will use the default service config.

funcWithIdleTimeout¶added inv1.56.0

func WithIdleTimeout(dtime.Duration)DialOption

WithIdleTimeout returns a DialOption that configures an idle timeout for thechannel. If the channel is idle for the configured timeout, i.e there are noongoing RPCs and no new RPCs are initiated, the channel will enter idle modeand as a result the name resolver and load balancer will be shut down. Thechannel will exit idle mode when the Connect() method is called or when anRPC is initiated.

A default timeout of 30 minutes will be used if this dial option is not setat dial time and idleness can be disabled by passing a timeout of zero.

Experimental¶

Notice: This API is EXPERIMENTAL and may be changed or removed in alater release.

funcWithInitialConnWindowSize¶added inv1.4.0

func WithInitialConnWindowSize(sint32)DialOption

WithInitialConnWindowSize returns a DialOption which sets the value forinitial window size on a connection. The lower bound for window size is 64Kand any value smaller than that will be ignored.

funcWithInitialWindowSize¶added inv1.4.0

func WithInitialWindowSize(sint32)DialOption

WithInitialWindowSize returns a DialOption which sets the value for initialwindow size on a stream. The lower bound for window size is 64K and any valuesmaller than that will be ignored.

funcWithKeepaliveParams¶added inv1.2.0

func WithKeepaliveParams(kpkeepalive.ClientParameters)DialOption

WithKeepaliveParams returns a DialOption that specifies keepalive parametersfor the client transport.

Keepalive is disabled by default.

funcWithLocalDNSResolution¶added inv1.71.0

func WithLocalDNSResolution()DialOption

WithLocalDNSResolution forces local DNS name resolution even when a proxy isspecified in the environment. By default, the server name is provideddirectly to the proxy as part of the CONNECT handshake. This is ignored ifWithNoProxy is used.

Experimental¶

Notice: This API is EXPERIMENTAL and may be changed or removed in alater release.

funcWithMaxCallAttempts¶added inv1.65.0

func WithMaxCallAttempts(nint)DialOption

WithMaxCallAttempts returns a DialOption that configures the maximum numberof attempts per call (including retries and hedging) using the channel.Service owners may specify a higher value for these parameters, but highervalues will be treated as equal to the maximum value by the clientimplementation. This mitigates security concerns related to the serviceconfig being transferred to the client via DNS.

A value of 5 will be used if this dial option is not set or n < 2.

funcWithMaxHeaderListSize¶added inv1.14.0

func WithMaxHeaderListSize(suint32)DialOption

WithMaxHeaderListSize returns a DialOption that specifies the maximum(uncompressed) size of header list that the client is prepared to accept.

funcWithNoProxy¶added inv1.29.0

func WithNoProxy()DialOption

WithNoProxy returns a DialOption which disables the use of proxies for thisClientConn. This is ignored if WithDialer or WithContextDialer are used.

Experimental¶

Notice: This API is EXPERIMENTAL and may be changed or removed in alater release.

funcWithPerRPCCredentials¶

func WithPerRPCCredentials(credscredentials.PerRPCCredentials)DialOption

WithPerRPCCredentials returns a DialOption which sets credentials and placesauth state on each outbound RPC.

funcWithReadBufferSize¶added inv1.7.0

func WithReadBufferSize(sint)DialOption

WithReadBufferSize lets you set the size of read buffer, this determines howmuch data can be read at most for each read syscall.

The default value for this buffer is 32KB. Zero or negative values willdisable read buffer for a connection so data framer can access theunderlying conn directly.

funcWithResolvers¶added inv1.27.0

func WithResolvers(rs ...resolver.Builder)DialOption

WithResolvers allows a list of resolver implementations to be registeredlocally with the ClientConn without needing to be globally registered viaresolver.Register. They will be matched against the scheme used for thecurrent Dial only, and will take precedence over the global registry.

Experimental¶

Notice: This API is EXPERIMENTAL and may be changed or removed in alater release.

funcWithSharedWriteBuffer¶added inv1.58.0

func WithSharedWriteBuffer(valbool)DialOption

WithSharedWriteBuffer allows reusing per-connection transport write buffer.If this option is set to true every connection will release the buffer afterflushing the data on the wire.

Experimental¶

Notice: This API is EXPERIMENTAL and may be changed or removed in alater release.

funcWithStatsHandler¶added inv1.2.0

func WithStatsHandler(hstats.Handler)DialOption

WithStatsHandler returns a DialOption that specifies the stats handler forall the RPCs and underlying network connections in this ClientConn.

funcWithStreamInterceptor¶added inv1.0.2

func WithStreamInterceptor(fStreamClientInterceptor)DialOption

WithStreamInterceptor returns a DialOption that specifies the interceptor forstreaming RPCs.

funcWithTransportCredentials¶

func WithTransportCredentials(credscredentials.TransportCredentials)DialOption

WithTransportCredentials returns a DialOption which configures a connectionlevel security credentials (e.g., TLS/SSL). This should not be used togetherwith WithCredentialsBundle.

funcWithUnaryInterceptor¶added inv1.0.2

func WithUnaryInterceptor(fUnaryClientInterceptor)DialOption

WithUnaryInterceptor returns a DialOption that specifies the interceptor forunary RPCs.

funcWithUserAgent¶

func WithUserAgent(sstring)DialOption

WithUserAgent returns a DialOption that specifies a user agent string for allthe RPCs.

funcWithWriteBufferSize¶added inv1.7.0

func WithWriteBufferSize(sint)DialOption

WithWriteBufferSize determines how much data can be batched before doing awrite on the wire. The default value for this buffer is 32KB.

Zero or negative values will disable the write buffer such that each writewill be on underlying connection. Note: A Send call may not directlytranslate to a write.

type EmptyCallOption struct{}

type EmptyDialOption struct{}

type EmptyServerOption struct{}

type FailFastCallOption struct {FailFastbool}

type ForceCodecCallOption struct {Codecencoding.Codec}

type ForceCodecV2CallOption struct {CodecV2encoding.CodecV2}

type GenericClientStream[Reqany, Resany] struct {ClientStream}

func (*GenericClientStream[Req, Res])CloseAndRecv¶added inv1.64.0

func (x *GenericClientStream[Req, Res]) CloseAndRecv() (*Res,error)

CloseAndRecv closes the sending side of the stream, then receives the unaryresponse from the server. The type of message which it returns is determinedby the Res type parameter of the GenericClientStream receiver.

func (*GenericClientStream[Req, Res])Recv¶added inv1.64.0

func (x *GenericClientStream[Req, Res]) Recv() (*Res,error)

Recv reads one message from the stream of responses generated by the server.The type of the message returned is determined by the Res type parameterof the GenericClientStream receiver.

func (*GenericClientStream[Req, Res])Send¶added inv1.64.0

func (x *GenericClientStream[Req, Res]) Send(m *Req)error

Send pushes one message into the stream of requests to be consumed by theserver. The type of message which can be sent is determined by the Req typeparameter of the GenericClientStream receiver.

type GenericServerStream[Reqany, Resany] struct {ServerStream}

func (*GenericServerStream[Req, Res])Recv¶added inv1.64.0

func (x *GenericServerStream[Req, Res]) Recv() (*Req,error)

Recv reads one message from the stream of requests generated by the client.The type of the message returned is determined by the Req type parameterof the clientStreamServer receiver.

func (*GenericServerStream[Req, Res])Send¶added inv1.64.0

func (x *GenericServerStream[Req, Res]) Send(m *Res)error

Send pushes one message into the stream of responses to be consumed by theclient. The type of message which can be sent is determined by the Restype parameter of the serverStreamServer receiver.

func (*GenericServerStream[Req, Res])SendAndClose¶added inv1.64.0

func (x *GenericServerStream[Req, Res]) SendAndClose(m *Res)error

SendAndClose pushes the unary response to the client. The type of messagewhich can be sent is determined by the Res type parameter of theclientStreamServer receiver.

type HeaderCallOption struct {HeaderAddr *metadata.MD}

type MaxHeaderListSizeDialOption struct {MaxHeaderListSizeuint32}

type MaxHeaderListSizeServerOption struct {MaxHeaderListSizeuint32}

type MaxRecvMsgSizeCallOption struct {MaxRecvMsgSizeint}

type MaxRetryRPCBufferSizeCallOption struct {MaxRetryRPCBufferSizeint}

type MaxSendMsgSizeCallOption struct {MaxSendMsgSizeint}

type MethodDesc struct {MethodNamestringHandlerMethodHandler}

type MethodHandler func(srvany, ctxcontext.Context, dec func(any)error, interceptorUnaryServerInterceptor) (any,error)

type MethodInfo struct {// Name is the method name only, without the service name or package name.Namestring// IsClientStream indicates whether the RPC is a client streaming RPC.IsClientStreambool// IsServerStream indicates whether the RPC is a server streaming RPC.IsServerStreambool}

type OnFinishCallOption struct {OnFinish func(error)}

type PeerCallOption struct {PeerAddr *peer.Peer}

type PerRPCCredsCallOption struct {Credscredentials.PerRPCCredentials}

type PreparedMsg struct {// contains filtered or unexported fields}

func (*PreparedMsg)Encode¶added inv1.21.0

func (p *PreparedMsg) Encode(sStream, msgany)error

Encode marshalls and compresses the message using the codec and compressor for the stream.

type Server struct {// contains filtered or unexported fields}

funcNewServer¶

func NewServer(opt ...ServerOption) *Server

NewServer creates a gRPC server which has no service registered and has notstarted to accept requests yet.

func (*Server)GetServiceInfo¶

func (s *Server) GetServiceInfo() map[string]ServiceInfo

GetServiceInfo returns a map from service names to ServiceInfo.Service names include the package names, in the form of <package>.<service>.

func (*Server)GracefulStop¶added inv1.0.2

func (s *Server) GracefulStop()

GracefulStop stops the gRPC server gracefully. It stops the server fromaccepting new connections and RPCs and blocks until all the pending RPCs arefinished.

func (*Server)RegisterService¶

func (s *Server) RegisterService(sd *ServiceDesc, ssany)

RegisterService registers a service and its implementation to the gRPCserver. It is called from the IDL generated code. This must be called beforeinvoking Serve. If ss is non-nil (for legacy code), its type is checked toensure it implements sd.HandlerType.

func (*Server)Serve¶

func (s *Server) Serve(lisnet.Listener)error

Serve accepts incoming connections on the listener lis, creating a newServerTransport and service goroutine for each. The service goroutinesread gRPC requests and then call the registered handlers to reply to them.Serve returns when lis.Accept fails with fatal errors. lis will be closed whenthis method returns.Serve will return a non-nil error unless Stop or GracefulStop is called.

Note: All supported releases of Go (as of December 2023) override the OSdefaults for TCP keepalive time and interval to 15s. To enable TCP keepalivewith OS defaults for keepalive time and interval, callers need to do thefollowing two things:

• pass a net.Listener created by calling the Listen method on anet.ListenConfig with the `KeepAlive` field set to a negative value. Thiswill result in the Go standard library not overriding OS defaults for TCPkeepalive interval and time. But this will also result in the Go standardlibrary not enabling TCP keepalives by default.
• override the Accept method on the passed in net.Listener and set theSO_KEEPALIVE socket option to enable TCP keepalives, with OS defaults.

func (*Server)ServeHTTP¶

func (s *Server) ServeHTTP(whttp.ResponseWriter, r *http.Request)

ServeHTTP implements the Go standard library's http.Handlerinterface by responding to the gRPC request r, by looking upthe requested gRPC method in the gRPC server s.

The provided HTTP request must have arrived on an HTTP/2connection. When using the Go standard library's server,practically this means that the Request must also have arrivedover TLS.

To share one port (such as 443 for https) between gRPC and anexisting http.Handler, use a root http.Handler such as:

if r.ProtoMajor == 2 && strings.HasPrefix(r.Header.Get("Content-Type"), "application/grpc") {grpcServer.ServeHTTP(w, r)} else {yourMux.ServeHTTP(w, r)}

Note that ServeHTTP uses Go's HTTP/2 server implementation which is totallyseparate from grpc-go's HTTP/2 server. Performance and features may varybetween the two paths. ServeHTTP does not support some gRPC featuresavailable through grpc-go's HTTP/2 server.

Experimental¶

Notice: This API is EXPERIMENTAL and may be changed or removed in alater release.

func (*Server)Stop¶

func (s *Server) Stop()

Stop stops the gRPC server. It immediately closes all openconnections and listeners.It cancels all active RPCs on the server side and the correspondingpending RPCs on the client side will get notified by connectionerrors.

type ServerOption interface {// contains filtered or unexported methods}

funcChainStreamInterceptor¶added inv1.28.0

func ChainStreamInterceptor(interceptors ...StreamServerInterceptor)ServerOption

ChainStreamInterceptor returns a ServerOption that specifies the chained interceptorfor streaming RPCs. The first interceptor will be the outer most,while the last interceptor will be the inner most wrapper around the real call.All stream interceptors added by this method will be chained.

funcChainUnaryInterceptor¶added inv1.28.0

func ChainUnaryInterceptor(interceptors ...UnaryServerInterceptor)ServerOption

ChainUnaryInterceptor returns a ServerOption that specifies the chained interceptorfor unary RPCs. The first interceptor will be the outer most,while the last interceptor will be the inner most wrapper around the real call.All unary interceptors added by this method will be chained.

funcConnectionTimeout¶added inv1.7.3

func ConnectionTimeout(dtime.Duration)ServerOption

ConnectionTimeout returns a ServerOption that sets the timeout forconnection establishment (up to and including HTTP/2 handshaking) for allnew connections. If this is not set, the default is 120 seconds. A zero ornegative value will result in an immediate timeout.

Experimental¶

Notice: This API is EXPERIMENTAL and may be changed or removed in alater release.

funcCreds¶

func Creds(ccredentials.TransportCredentials)ServerOption

Creds returns a ServerOption that sets credentials for server connections.

funcForceServerCodec¶added inv1.38.0

func ForceServerCodec(codecencoding.Codec)ServerOption

ForceServerCodec returns a ServerOption that sets a codec for messagemarshaling and unmarshaling.

This will override any lookups by content-subtype for Codecs registeredwith RegisterCodec.

See Content-Type onhttps://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md#requests formore details. Also see the documentation on RegisterCodec andCallContentSubtype for more details on the interaction between encoding.Codecand content-subtype.

This function is provided for advanced users; prefer to register codecsusing encoding.RegisterCodec.The server will automatically use registered codecs based on the incomingrequests' headers. See alsohttps://github.com/grpc/grpc-go/blob/master/Documentation/encoding.md#using-a-codec.Will be supported throughout 1.x.

Experimental¶

Notice: This API is EXPERIMENTAL and may be changed or removed in alater release.

funcForceServerCodecV2¶added inv1.66.0

func ForceServerCodecV2(codecV2encoding.CodecV2)ServerOption

ForceServerCodecV2 is the equivalent of ForceServerCodec, but for the newCodecV2 interface.

Will be supported throughout 1.x.

Experimental¶

Notice: This API is EXPERIMENTAL and may be changed or removed in alater release.

funcHeaderTableSize¶added inv1.25.0

func HeaderTableSize(suint32)ServerOption

HeaderTableSize returns a ServerOption that sets the size of dynamicheader table for stream.

Experimental¶

Notice: This API is EXPERIMENTAL and may be changed or removed in alater release.

funcInTapHandle¶added inv1.0.5

func InTapHandle(htap.ServerInHandle)ServerOption

InTapHandle returns a ServerOption that sets the tap handle for all the servertransport to be created. Only one can be installed.

Experimental¶

Notice: This API is EXPERIMENTAL and may be changed or removed in alater release.

funcInitialConnWindowSize¶added inv1.4.0

func InitialConnWindowSize(sint32)ServerOption

InitialConnWindowSize returns a ServerOption that sets window size for a connection.The lower bound for window size is 64K and any value smaller than that will be ignored.

funcInitialWindowSize¶added inv1.4.0

func InitialWindowSize(sint32)ServerOption

InitialWindowSize returns a ServerOption that sets window size for stream.The lower bound for window size is 64K and any value smaller than that will be ignored.

funcKeepaliveEnforcementPolicy¶added inv1.3.0

func KeepaliveEnforcementPolicy(kepkeepalive.EnforcementPolicy)ServerOption

KeepaliveEnforcementPolicy returns a ServerOption that sets keepalive enforcement policy for the server.

funcKeepaliveParams¶added inv1.3.0

func KeepaliveParams(kpkeepalive.ServerParameters)ServerOption

KeepaliveParams returns a ServerOption that sets keepalive and max-age parameters for the server.

funcMaxConcurrentStreams¶

func MaxConcurrentStreams(nuint32)ServerOption

MaxConcurrentStreams returns a ServerOption that will apply a limit on the numberof concurrent streams to each ServerTransport.

funcMaxHeaderListSize¶added inv1.14.0

func MaxHeaderListSize(suint32)ServerOption

MaxHeaderListSize returns a ServerOption that sets the max (uncompressed) sizeof header list that the server is prepared to accept.

funcMaxRecvMsgSize¶added inv1.4.0

func MaxRecvMsgSize(mint)ServerOption

MaxRecvMsgSize returns a ServerOption to set the max message size in bytes the server can receive.If this is not set, gRPC uses the default 4MB.

funcMaxSendMsgSize¶added inv1.4.0

func MaxSendMsgSize(mint)ServerOption

MaxSendMsgSize returns a ServerOption to set the max message size in bytes the server can send.If this is not set, gRPC uses the default `math.MaxInt32`.

funcNumStreamWorkers¶added inv1.30.0

func NumStreamWorkers(numServerWorkersuint32)ServerOption

NumStreamWorkers returns a ServerOption that sets the number of workergoroutines that should be used to process incoming streams. Setting this tozero (default) will disable workers and spawn a new goroutine for eachstream.

Experimental¶

Notice: This API is EXPERIMENTAL and may be changed or removed in alater release.

funcReadBufferSize¶added inv1.7.0

func ReadBufferSize(sint)ServerOption

ReadBufferSize lets you set the size of read buffer, this determines how muchdata can be read at most for one read syscall. The default value for thisbuffer is 32KB. Zero or negative values will disable read buffer for aconnection so data framer can access the underlying conn directly.

funcSharedWriteBuffer¶added inv1.58.0

func SharedWriteBuffer(valbool)ServerOption

SharedWriteBuffer allows reusing per-connection transport write buffer.If this option is set to true every connection will release the buffer afterflushing the data on the wire.

Experimental¶

Notice: This API is EXPERIMENTAL and may be changed or removed in alater release.

funcStatsHandler¶added inv1.2.0

func StatsHandler(hstats.Handler)ServerOption

StatsHandler returns a ServerOption that sets the stats handler for the server.

funcStreamInterceptor¶

func StreamInterceptor(iStreamServerInterceptor)ServerOption

StreamInterceptor returns a ServerOption that sets the StreamServerInterceptor for theserver. Only one stream interceptor can be installed.

funcUnaryInterceptor¶

func UnaryInterceptor(iUnaryServerInterceptor)ServerOption

UnaryInterceptor returns a ServerOption that sets the UnaryServerInterceptor for theserver. Only one unary interceptor can be installed. The construction of multipleinterceptors (e.g., chaining) can be implemented at the caller.

funcUnknownServiceHandler¶added inv1.2.0

func UnknownServiceHandler(streamHandlerStreamHandler)ServerOption

UnknownServiceHandler returns a ServerOption that allows for adding a customunknown service handler. The provided method is a bidi-streaming RPC servicehandler that will be invoked instead of returning the "unimplemented" gRPCerror whenever a request is received for an unregistered service or method.The handling function and stream interceptor (if set) have full access tothe ServerStream, including its Context.

funcWaitForHandlers¶added inv1.61.0

func WaitForHandlers(wbool)ServerOption

WaitForHandlers cause Stop to wait until all outstanding method handlers haveexited before returning. If false, Stop will return as soon as allconnections have closed, but method handlers may still be running. Bydefault, Stop does not wait for method handlers to return.

Experimental¶

Notice: This API is EXPERIMENTAL and may be changed or removed in alater release.

funcWriteBufferSize¶added inv1.7.0

func WriteBufferSize(sint)ServerOption

WriteBufferSize determines how much data can be batched before doing a writeon the wire. The default value for this buffer is 32KB. Zero or negativevalues will disable the write buffer such that each write will be on underlyingconnection. Note: A Send call may not directly translate to a write.

type ServerStream interface {// SetHeader sets the header metadata. It may be called multiple times.// When call multiple times, all the provided metadata will be merged.// All the metadata will be sent out when one of the following happens://  - ServerStream.SendHeader() is called;//  - The first response is sent out;//  - An RPC status is sent out (error or success).SetHeader(metadata.MD)error// SendHeader sends the header metadata.// The provided md and headers set by SetHeader() will be sent.// It fails if called multiple times.SendHeader(metadata.MD)error// SetTrailer sets the trailer metadata which will be sent with the RPC status.// When called more than once, all the provided metadata will be merged.SetTrailer(metadata.MD)// Context returns the context for this stream.Context()context.Context// SendMsg sends a message. On error, SendMsg aborts the stream and the// error is returned directly.//// SendMsg blocks until://   - There is sufficient flow control to schedule m with the transport, or//   - The stream is done, or//   - The stream breaks.//// SendMsg does not wait until the message is received by the client. An// untimely stream closure may result in lost messages.//// It is safe to have a goroutine calling SendMsg and another goroutine// calling RecvMsg on the same stream at the same time, but it is not safe// to call SendMsg on the same stream in different goroutines.//// It is not safe to modify the message after calling SendMsg. Tracing// libraries and stats handlers may use the message lazily.SendMsg(many)error// RecvMsg blocks until it receives a message into m or the stream is// done. It returns io.EOF when the client has performed a CloseSend. On// any non-EOF error, the stream is aborted and the error contains the// RPC status.//// It is safe to have a goroutine calling SendMsg and another goroutine// calling RecvMsg on the same stream at the same time, but it is not// safe to call RecvMsg on the same stream in different goroutines.RecvMsg(many)error}

type ServerStreamingClient[Resany] interface {// Recv receives the next response message from the server. The client may// repeatedly call Recv to read messages from the response stream.  If// io.EOF is returned, the stream has terminated with an OK status.  Any// other error is compatible with the status package and indicates the// RPC's status code and message.Recv() (*Res,error)// ClientStream is embedded to provide Context, Header, and Trailer// functionality.  No other methods in the ClientStream should be called// directly.ClientStream}

type ServerStreamingServer[Resany] interface {// Send sends a response message to the client.  The server handler may// call Send multiple times to send multiple messages to the client.  An// error is returned if the stream was terminated unexpectedly, and the// handler method should return, as the stream is no longer usable.Send(*Res)error// ServerStream is embedded to provide Context, SetHeader, SendHeader, and// SetTrailer functionality.  No other methods in the ServerStream should// be called directly.ServerStream}

type ServerTransportStream interface {Method()stringSetHeader(mdmetadata.MD)errorSendHeader(mdmetadata.MD)errorSetTrailer(mdmetadata.MD)error}

funcServerTransportStreamFromContext¶added inv1.12.0

func ServerTransportStreamFromContext(ctxcontext.Context)ServerTransportStream

ServerTransportStreamFromContext returns the ServerTransportStream saved inctx. Returns nil if the given context has no stream associated with it(which implies it is not an RPC invocation context).

Experimental¶

Notice: This API is EXPERIMENTAL and may be changed or removed in alater release.

type ServiceDesc struct {ServiceNamestring// The pointer to the service interface. Used to check whether the user// provided implementation satisfies the interface requirements.HandlerTypeanyMethods     []MethodDescStreams     []StreamDescMetadataany}

type ServiceInfo struct {Methods []MethodInfo// Metadata is the metadata specified in ServiceDesc when registering service.Metadataany}

type ServiceRegistrar interface {// RegisterService registers a service and its implementation to the// concrete type implementing this interface.  It may not be called// once the server has started serving.// desc describes the service and its methods and handlers. impl is the// service implementation which is passed to the method handlers.RegisterService(desc *ServiceDesc, implany)}

type StaticMethodCallOption struct {EmptyCallOption}

type StreamClientInterceptor func(ctxcontext.Context, desc *StreamDesc, cc *ClientConn, methodstring, streamerStreamer, opts ...CallOption) (ClientStream,error)

type StreamDesc struct {// StreamName and Handler are only used when registering handlers on a// server.StreamNamestring// the name of the method excluding the serviceHandlerStreamHandler// the handler called for the method// ServerStreams and ClientStreams are used for registering handlers on a// server as well as defining RPC behavior when passed to NewClientStream// and ClientConn.NewStream.  At least one must be true.ServerStreamsbool// indicates the server can perform streaming sendsClientStreamsbool// indicates the client can perform streaming sends}

type StreamHandler func(srvany, streamServerStream)error

type StreamServerInfo struct {// FullMethod is the full RPC method string, i.e., /package.service/method.FullMethodstring// IsClientStream indicates whether the RPC is a client streaming RPC.IsClientStreambool// IsServerStream indicates whether the RPC is a server streaming RPC.IsServerStreambool}

type StreamServerInterceptor func(srvany, ssServerStream, info *StreamServerInfo, handlerStreamHandler)error

type Streamer func(ctxcontext.Context, desc *StreamDesc, cc *ClientConn, methodstring, opts ...CallOption) (ClientStream,error)

type TrailerCallOption struct {TrailerAddr *metadata.MD}

type UnaryClientInterceptor func(ctxcontext.Context, methodstring, req, replyany, cc *ClientConn, invokerUnaryInvoker, opts ...CallOption)error

type UnaryHandler func(ctxcontext.Context, reqany) (any,error)

type UnaryInvoker func(ctxcontext.Context, methodstring, req, replyany, cc *ClientConn, opts ...CallOption)error

type UnaryServerInfo struct {// Server is the service implementation the user provides. This is read-only.Serverany// FullMethod is the full RPC method string, i.e., /package.service/method.FullMethodstring}

type UnaryServerInterceptor func(ctxcontext.Context, reqany, info *UnaryServerInfo, handlerUnaryHandler) (respany, errerror)