client

package
v0.15.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 26, 2025 License: Apache-2.0 Imports: 60 Imported by: 2,863

Documentation

Overview

Package client contains core part of Kitex client. Users should not directly use any method here other than the options and call options. Users should call NewClient in the generated code, which wraps the NewClient call in this package.

Service inline is a service deployment form of ByteDance's internal applications. Different Kitex services are merged together during the compilation period through the tool chain, and this capability is not yet opensource.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CallOptionInfoFromCtx 

func CallOptionInfoFromCtx(ctx context.Context) (res string)

CallOptionInfoFromCtx retrieves the call Options debug information from the given context.

func CallOptionsFromCtx 

func CallOptionsFromCtx(ctx context.Context) (res []callopt.Option)

CallOptionsFromCtx retrieves call-Options from the given context.

func ClientErrorHandlerWithAddr added in v0.6.0 

func ClientErrorHandlerWithAddr(ctx context.Context, err error) error

ClientErrorHandlerWithAddr is ErrorHandler for client, which will add remote addr info into error

func DefaultClientErrorHandler added in v0.3.3 

func DefaultClientErrorHandler(ctx context.Context, err error) error

DefaultClientErrorHandler is Default ErrorHandler for client when no ErrorHandler is specified with Option `client.WithErrorHandler`, this ErrorHandler will be injected. for thrift、KitexProtobuf, >= v0.4.0 wrap protocol error to TransError, which will be more friendly.

func NewCtxWithCallOptions 

func NewCtxWithCallOptions(ctx context.Context, opts []callopt.Option) context.Context

NewCtxWithCallOptions returns a new context associated with the given call-Options.

func WithContextMiddlewares added in v0.4.3 

func WithContextMiddlewares(ctx context.Context, mws ...endpoint.Middleware) context.Context

WithContextMiddlewares add middlewares into current ctx Every client receive this ctx will execute the middlewares. Note that ContextMiddleware is prior to the ClientMiddleware.

func WithMetaHandler 

func WithMetaHandler(h remote.MetaHandler) client.Option

WithMetaHandler adds a MetaHandler.

Types

type Client 

type Client interface {
	Call(ctx context.Context, method string, request, response interface{}) error
}

Client is the core interface abstraction of kitex client. It is designed for generated codes and should not be used directly. Parameter method specifies the method of a RPC call. Request is a packing of request parameters in the actual method defined in IDL, consist of zero, one or multiple arguments. So is response to the actual result type. Response may be nil to address oneway calls.

func NewClient 

func NewClient(svcInfo *serviceinfo.ServiceInfo, opts ...Option) (Client, error)

NewClient creates a kitex.Client with the given ServiceInfo, it is from generated code.

func NewServiceInlineClient added in v0.6.0 

func NewServiceInlineClient(svcInfo *serviceinfo.ServiceInfo, s ServerInitialInfo, opts ...Option) (Client, error)

NewServiceInlineClient creates a kitex.Client with the given ServiceInfo, it is from generated code.

type ContextServiceInlineHandler added in v0.6.0 

type ContextServiceInlineHandler interface {
	WriteMeta(cliCtx context.Context, req interface{}) (newCliCtx context.Context, err error)
	ReadMeta(cliCtx context.Context, resp interface{}) (err error)
}

type Option 

type Option = client.Option

Option is the only way to config client.

func TailOption added in v0.13.0 

func TailOption(opt Option) Option

TailOption is used to covert an option to a tail option which is executed after all options are applied. NOTICE: no compatibility guarantee for this api, just ignore it unless you clearly know what you are doing.

func WithACLRules 

func WithACLRules(rules ...acl.RejectFunc) Option

WithACLRules adds ACL rules. Note that the ACL checking process happens before service discovery.

func WithBackupRequest 

func WithBackupRequest(p *retry.BackupPolicy) Option

WithBackupRequest sets the backup request policy for client.

NOTICE: WithBackupRequest is only effective for all unary methods. May provide WithUnaryOptions(WithUnaryBackupRequest(d)) option later which is more recommended.

func WithBoundHandler 

func WithBoundHandler(h remote.BoundHandler) Option

WithBoundHandler adds remote.BoundHandler for client.

func WithCircuitBreaker added in v0.0.5 

func WithCircuitBreaker(s *circuitbreak.CBSuite) Option

WithCircuitBreaker adds a circuitbreaker suite for the client.

func WithClientBasicInfo 

func WithClientBasicInfo(ebi *rpcinfo.EndpointBasicInfo) Option

WithClientBasicInfo provides initial information for client endpoint in RPCInfo.

func WithCloseCallbacks 

func WithCloseCallbacks(callback func() error) Option

WithCloseCallbacks adds callback to Close

func WithCodec 

func WithCodec(c remote.Codec) Option

WithCodec to set a codec that handle other protocols which not support by kitex

func WithConnMetric deprecated 

func WithConnMetric() Option

WithConnMetric to enable reporting connection pool stats.

Deprecated: Use WithConnReporterEnabled instead.

func WithConnPool 

func WithConnPool(pool remote.ConnPool) Option

WithConnPool sets the connection pool. Note that this option can only be specified once. If more than one pool is specified by this option, only the first one will be used.

func WithConnReporterEnabled 

func WithConnReporterEnabled() Option

WithConnReporterEnabled to enable reporting connection pool stats.

func WithConnectTimeout 

func WithConnectTimeout(d time.Duration) Option

WithConnectTimeout specifies the connection timeout.

func WithContextBackup added in v0.7.0 

func WithContextBackup(backupHandler func(prev, cur context.Context) (ctx context.Context, backup bool)) Option

WithContextBackup enables local-session to retrieve context backuped by server, in case of user don't correctly pass context into next RPC call.

  • backupHandler pass a handler to check and handler user-defined key-values according to current context, returning backup==false means no need further operations.

func WithDestService 

func WithDestService(svr string) Option

WithDestService specifies the name of target service.

func WithDiagnosisService 

func WithDiagnosisService(ds diagnosis.Service) Option

WithDiagnosisService sets the diagnosis service for gathering debug information.

func WithDialer 

func WithDialer(d remote.Dialer) Option

WithDialer sets the Dialer for creating connections.

func WithErrorHandler 

func WithErrorHandler(f func(context.Context, error) error) Option

WithErrorHandler sets the error handler.

func WithFailureRetry 

func WithFailureRetry(p *retry.FailurePolicy) Option

WithFailureRetry sets the failure retry policy for client.

NOTICE: WithFailureRetry is only effective for all unary methods. May provide WithUnaryOptions(WithUnaryFailureRetry(d)) option later which is more recommended.

func WithFallback added in v0.5.0 

func WithFallback(fb *fallback.Policy) Option

WithFallback is used to set the fallback policy for the client. Demos are provided below: 

demo1. fallback for error and resp
	`client.WithFallback(fallback.NewFallbackPolicy(yourFBFunc))`
demo2. fallback for error and enable reportAsFallback, which sets reportAsFallback to be true and will do report(metric) as Fallback result
	`client.WithFallback(fallback.ErrorFallback(yourErrFBFunc).EnableReportAsFallback())`
demo2. fallback for rpctime and circuit breaker
	`client.WithFallback(fallback.TimeoutAndCBFallback(yourErrFBFunc))`

NOTICE: WithFallback is only effective for all unary methods. May provide WithUnaryOptions(WithUnaryFallback(d)) option later which is more recommended.

func WithFirstMetaHandler 

func WithFirstMetaHandler(h remote.MetaHandler) Option

WithFirstMetaHandler adds a MetaHandler.

func WithFramedTransport deprecated 

func WithFramedTransport() Option

WithFramedTransport to use framed transport

Deprecated: Use WithTransportProtocol(transport.Framed) instead.

IMPORTANT: this option will be deleted in the future!!!

func WithGRPCConnPoolSize added in v0.2.0 

func WithGRPCConnPoolSize(s uint32) Option

WithGRPCConnPoolSize sets the value for the client connection pool size. In general, you should not adjust the size of the connection pool, otherwise it may cause performance degradation. You should adjust the size according to the actual situation.

func WithGRPCInitialConnWindowSize added in v0.2.0 

func WithGRPCInitialConnWindowSize(s uint32) Option

WithGRPCInitialConnWindowSize sets the value for initial window size on a connection of grpc. The lower bound for window size is 64K and any value smaller than that will be ignored. It corresponds to the WithInitialConnWindowSize DialOption of gRPC.

func WithGRPCInitialWindowSize added in v0.2.0 

func WithGRPCInitialWindowSize(s uint32) Option

WithGRPCInitialWindowSize sets the value for initial window size on a grpc stream. The lower bound for window size is 64K and any value smaller than that will be ignored. It corresponds to the WithInitialWindowSize DialOption of gRPC.

func WithGRPCKeepaliveParams added in v0.2.0 

func WithGRPCKeepaliveParams(kp grpc.ClientKeepalive) Option

WithGRPCKeepaliveParams returns a DialOption that specifies keepalive parameters for the client transport. It corresponds to the WithKeepaliveParams DialOption of gRPC.

func WithGRPCMaxHeaderListSize added in v0.2.0 

func WithGRPCMaxHeaderListSize(s uint32) Option

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

func WithGRPCReadBufferSize added in v0.3.0 

func WithGRPCReadBufferSize(s uint32) Option

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

The default value for this buffer is 32KB. Zero will disable read buffer for a connection so data framer can access the underlying conn directly. It corresponds to the WithReadBufferSize DialOption of gRPC.

func WithGRPCTLSConfig added in v0.5.0 

func WithGRPCTLSConfig(tlsConfig *tls.Config) Option

WithGRPCTLSConfig sets the TLS config for gRPC client.

func WithGRPCWriteBufferSize added in v0.3.0 

func WithGRPCWriteBufferSize(s uint32) Option

WithGRPCWriteBufferSize determines how much data can be batched before doing a write on the wire. The corresponding memory allocation for this buffer will be twice the size to keep syscalls low. The default value for this buffer is 32KB.

Zero will disable the write buffer such that each write will be on underlying connection. Note: A Send call may not directly translate to a write. It corresponds to the WithWriteBufferSize DialOption of gRPC.

func WithGeneric 

func WithGeneric(g generic.Generic) Option

WithGeneric set Generic type for generic call. Deprecated, it only takes effect on binary thrift generic v1, please use generic.BinaryThriftGenericV2 instead.

func WithHTTPConnection 

func WithHTTPConnection() Option

WithHTTPConnection specifies client use RPC over http.

func WithHTTPResolver 

func WithHTTPResolver(r http.Resolver) Option

WithHTTPResolver specifies resolver for url (which specified by WithURL).

func WithHostPorts 

func WithHostPorts(hostports ...string) Option

WithHostPorts specifies the target instance addresses when doing service discovery. It overwrites the results from the Resolver.

func WithInstanceMW 

func WithInstanceMW(mw endpoint.Middleware) Option

WithInstanceMW adds middleware for client to handle request after service discovery and loadbalance process.

func WithLoadBalancer 

func WithLoadBalancer(lb loadbalance.Loadbalancer, opts ...*lbcache.Options) Option

WithLoadBalancer sets the loadbalancer for client.

func WithLogger 

func WithLogger(logger klog.FormatLogger) Option

WithLogger sets the Logger for kitex client. Deprecated: client uses the global klog.DefaultLogger.

func WithLongConnection 

func WithLongConnection(cfg connpool.IdleConfig) Option

WithLongConnection enables long connection with kitex's built-in pooling implementation.

func WithMiddleware 

func WithMiddleware(mw endpoint.Middleware) Option

WithMiddleware adds middleware for client to handle request.

func WithMiddlewareBuilder 

func WithMiddlewareBuilder(mwb endpoint.MiddlewareBuilder) Option

WithMiddlewareBuilder adds middleware that depend on context for client to handle request

func WithMixedRetry added in v0.11.0 

func WithMixedRetry(p *retry.MixedPolicy) Option

WithMixedRetry sets the mixed retry policy for client.

NOTICE: WithMixedRetry is only effective for all unary methods. May provide WithUnaryOptions(WithUnaryMixedRetry(d)) option later which is more recommended.

func WithMuxConnection 

func WithMuxConnection(connNum int) Option

WithMuxConnection specifies the transport type to be mux.

func WithPayloadCodec 

func WithPayloadCodec(c remote.PayloadCodec) Option

WithPayloadCodec to set a payloadCodec that handle other payload which not support by kitex

func WithProxy 

func WithProxy(p proxy.ForwardProxy) Option

WithProxy sets the forward Proxy for client.

func WithRPCTimeout 

func WithRPCTimeout(d time.Duration) Option

WithRPCTimeout specifies the RPC timeout.

Warning: WithRPCTimeout is only effective for unary methods. It's recommended to use WithUnaryOptions(WithUnaryRPCTimeout(d)) instead.

func WithResolver 

func WithResolver(r discovery.Resolver) Option

WithResolver provides the Resolver for kitex client.

func WithRetryContainer 

func WithRetryContainer(rc *retry.Container) Option

WithRetryContainer sets Container

func WithRetryMethodPolicies added in v0.4.0 

func WithRetryMethodPolicies(mp map[string]retry.Policy) Option

WithRetryMethodPolicies sets the retry policy for method. The priority is higher than WithFailureRetry and WithBackupRequest. Only the methods which are not included by this config will use the policy that is configured by WithFailureRetry or WithBackupRequest . FailureRetry and BackupRequest can be set for different method at same time. Notice: method name is case-sensitive, it should be same with the definition in IDL.

NOTICE: WithRetryMethodPolicies is only effective for all unary methods. May provide WithUnaryOptions(WithUnaryRetryMethodPolicies(d)) option later which is more recommended.

func WithShortConnection added in v0.0.2 

func WithShortConnection() Option

WithShortConnection forces kitex to close connection after each call is finished.

func WithSpecifiedResultRetry added in v0.4.0 

func WithSpecifiedResultRetry(rr *retry.ShouldResultRetry) Option

WithSpecifiedResultRetry is used with FailureRetry. When you enable FailureRetry and want to retry with the specified error or response, you can configure this Option. ShouldResultRetry is defined inside retry.FailurePolicy, so WithFailureRetry also can set ShouldResultRetry. But if your retry policy is enabled by remote config, WithSpecifiedResultRetry is useful.

NOTICE: WithSpecifiedResultRetry is only effective for all unary methods. May provide WithUnaryOptions(WithUnarySpecifiedResultRetry(d)) option later which is more recommended.

func WithStatsLevel 

func WithStatsLevel(level stats.Level) Option

WithStatsLevel sets the stats level for client.

func WithStreamOptions added in v0.13.0 

func WithStreamOptions(opts ...StreamOption) Option

WithStreamOptions add stream options for client. It is used to isolate options that are only effective for streaming methods.

func WithSuite 

func WithSuite(suite Suite) Option

WithSuite adds an option suite for client.

func WithTTHeaderStreamingOptions added in v0.13.0 

func WithTTHeaderStreamingOptions(opts ...TTHeaderStreamingOption) Option

WithTTHeaderStreamingOptions add ttheader streaming options for client.

func WithTag 

func WithTag(key, val string) Option

WithTag sets the customize tag for service discovery, eg: idc, cluster.

func WithTimeoutProvider added in v0.0.5 

func WithTimeoutProvider(p rpcinfo.TimeoutProvider) Option

WithTimeoutProvider adds a TimeoutProvider to the client. Note that the timeout settings provided by the TimeoutProvider will be applied before the other timeout options in this package and those in the callopt package. Thus it can not modify the timeouts set by WithRPCTimeout, WithUnaryRPCTimeout or WithConnectTimeout.

func WithTracer 

func WithTracer(c stats.Tracer) Option

WithTracer adds a tracer to client.

func WithTransHandlerFactory 

func WithTransHandlerFactory(f remote.ClientTransHandlerFactory) Option

WithTransHandlerFactory sets the TransHandlerFactory for client.

func WithTransportProtocol 

func WithTransportProtocol(tp transport.Protocol) Option

WithTransportProtocol sets the transport protocol for client.

func WithUnaryOptions added in v0.13.0 

func WithUnaryOptions(opts ...UnaryOption) Option

WithUnaryOptions add unary options for client. It is used to isolate options that are only effective for unary/pingpong methods.

func WithWarmingUp added in v0.3.0 

func WithWarmingUp(wuo *warmup.ClientOption) Option

WithWarmingUp forces the client to do some warm-ups at the end of the initialization.

func WithXDSSuite added in v0.4.0 

func WithXDSSuite(suite xds.ClientSuite) Option

WithXDSSuite is used to set the xds suite for the client.

type Options 

type Options = client.Options

Options is used to initialize a client.

type ServerInitialInfo added in v0.6.0 

type ServerInitialInfo interface {
	BuildServiceInlineInvokeChain() endpoint.Endpoint
}

type StreamOption added in v0.13.0 

type StreamOption = client.StreamOption

func WithStreamMiddleware added in v0.13.0 

func WithStreamMiddleware(mw cep.StreamMiddleware) StreamOption

WithStreamMiddleware add middleware for stream.

func WithStreamMiddlewareBuilder added in v0.13.0 

func WithStreamMiddlewareBuilder(mwb cep.StreamMiddlewareBuilder) StreamOption

WithStreamMiddlewareBuilder add middleware builder for stream.

func WithStreamRecvMiddleware added in v0.13.0 

func WithStreamRecvMiddleware(mw cep.StreamRecvMiddleware) StreamOption

WithStreamRecvMiddleware add recv middleware for stream.

func WithStreamRecvMiddlewareBuilder added in v0.13.0 

func WithStreamRecvMiddlewareBuilder(mwb cep.StreamRecvMiddlewareBuilder) StreamOption

WithStreamRecvMiddlewareBuilder add recv middleware builder for stream.

func WithStreamRecvTimeout added in v0.13.0 

func WithStreamRecvTimeout(d time.Duration) StreamOption

WithStreamRecvTimeout add recv timeout for stream.Recv function. NOTICE: ONLY effective for ttheader streaming protocol for now.

func WithStreamSendMiddleware added in v0.13.0 

func WithStreamSendMiddleware(mw cep.StreamSendMiddleware) StreamOption

WithStreamSendMiddleware add send middleware for stream.

func WithStreamSendMiddlewareBuilder added in v0.13.0 

func WithStreamSendMiddlewareBuilder(mwb cep.StreamSendMiddlewareBuilder) StreamOption

WithStreamSendMiddlewareBuilder add send middleware builder for stream.

type StreamOptions added in v0.13.0 

type StreamOptions = client.StreamOptions

type Streaming 

type Streaming interface {
	// Deprecated, keep this method for compatibility with gen code with version < v0.13.0,
	// regenerate code with kitex command with version >= v0.13.0 to use StreamX instead.
	Stream(ctx context.Context, method string, request, response interface{}) error
	StreamX(ctx context.Context, method string) (streaming.ClientStream, error)
}

Streaming client streaming interface for code generate

type Suite 

type Suite interface {
	Options() []Option
}

A Suite is a collection of Options. It is useful to assemble multiple associated Options as a single one to keep the order or presence in a desired manner.

type TTHeaderStreamingOption added in v0.13.0 

type TTHeaderStreamingOption = client.TTHeaderStreamingOption

func WithTTHeaderStreamingTransportOptions added in v0.13.0 

func WithTTHeaderStreamingTransportOptions(opt ...ttstream.ClientHandlerOption) TTHeaderStreamingOption

WithTTHeaderStreamingTransportOptions add ttheader streaming transport options for client.

type TTHeaderStreamingOptions added in v0.13.0 

type TTHeaderStreamingOptions = client.TTHeaderStreamingOptions

type UnaryOption added in v0.13.0 

type UnaryOption = client.UnaryOption

func WithUnaryMiddleware added in v0.13.0 

func WithUnaryMiddleware(mw endpoint.UnaryMiddleware) UnaryOption

WithUnaryMiddleware add unary middleware for unary method.

func WithUnaryMiddlewareBuilder added in v0.13.0 

func WithUnaryMiddlewareBuilder(mwb endpoint.UnaryMiddlewareBuilder) UnaryOption

WithUnaryMiddlewareBuilder add unary middleware builder for unary method.

func WithUnaryRPCTimeout added in v0.13.0 

func WithUnaryRPCTimeout(d time.Duration) UnaryOption

WithUnaryRPCTimeout add rpc timeout for unary method.

type UnaryOptions added in v0.13.0 

type UnaryOptions = client.UnaryOptions

Source Files

View all Source files

Directories

Path Synopsis
Package callopt contains options that control the behavior of client on request level.
 Package callopt contains options that control the behavior of client on request level.
streamcall
Package genericclient ...
 Package genericclient ...

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.