thriftbp

type AddressGenerator func() (string, error)

type BaseplateClientPoolConfig ClientPoolConfig

type Client interface {
	clientpool.Client
	thrift.TClient
}

type ClientPool interface {
	// The returned TClient implements TClient by grabbing a Client from its pool
	// and releasing that Client after its Call method completes.
	//
	// A typical example of how to use the pool is like this:
	//
	//     // service.NewServiceClient comes from thrift compiled go code.
	//     // client you got here should be treated as disposable and never be
	//     // shared between goroutines.
	//     client := service.NewServiceClient(pool.TClient())
	//     resp, err := client.MyEndpoint(ctx, req)
	//
	// Or you can create a "client factory" for the service you want to call:
	//
	//    type ServiceClientFactory struct {
	//        pool thriftbp.ClientPool
	//    }
	//
	//    // service.Service and service.NewServiceClient are from thrift compiled
	//    // go code.
	//    func (f ServiceClientFactory) Client service.Service {
	//        return service.NewServiceClient(f.pool.TClient())
	//    }
	//
	//    client := factory.Client()
	//    resp, err := client.MyEndpoint(ctx, req)
	//
	// If the call fails to get a client from the pool, it will return PoolError.
	// You can check the error returned using:
	//
	//     var poolErr thriftbp.PoolError
	//     if errors.As(err, &poolErr) {
	//       // It's unable to get a client from the pool
	//     } else {
	//       // It's error from the actual thrift call
	//     }
	//
	// If the error is not of type PoolError that means it's returned by the call
	// from the actual client.
	//
	// If the call fails to release the client back to the pool,
	// it will log the error on error level but not return it to the caller.
	// It also increases thriftbp_client_pool_release_errors_total counter.
	TClient() thrift.TClient

	// Passthrough APIs from clientpool.Pool:
	io.Closer
	IsExhausted() bool
}

type ClientPoolConfig struct {
	// ServiceSlug is a short identifier for the thrift service you are creating
	// clients for.  The preferred convention is to take the service's name,
	// remove the 'Service' prefix, if present, and convert from camel case to
	// all lower case, hyphen separated.
	//
	// Examples:
	//
	//     AuthenticationService -> authentication
	//     ImageUploadService -> image-upload
	ServiceSlug string `yaml:"serviceSlug"`

	// Addr is the address of a thrift service.  Addr must be in the format
	// "${host}:${port}"
	Addr string `yaml:"addr"`

	// InitialConnections is the desired inital number of thrift connections
	// created by the client pool.
	//
	// If an error occurred when we try to establish the initial N connections for
	// the pool, we log the errors on warning level,
	// then return the pool with the <N connections we already established.
	//
	// If that's unacceptable, then RequiredInitialConnections can be used to set
	// the hard requirement of minimal initial connections to be established.
	// Note that enabling this can cause cascading failures during an outage,
	// so it shall only be used for extreme circumstances.
	InitialConnections         int `yaml:"initialConnections"`
	RequiredInitialConnections int `yaml:"requiredInitialConnections"`
	// Deprecated: InitialConnectionsFallback is always true and setting it to
	// false won't do anything.
	InitialConnectionsFallback bool `yaml:"initialConnectionsFallback"`
	// Deprecated: Individual connection errors during initialization is always
	// logged via zap logger on warning level.
	InitialConnectionsFallbackLogger log.Wrapper `yaml:"initialConnectionsFallbackLogger"`

	// MaxConnections is the maximum number of thrift connections the client
	// pool can maintain.
	MaxConnections int `yaml:"maxConnections"`

	// MaxConnectionAge is the maximum duration that a pooled connection will be
	// kept before closing in favor of a new one.
	//
	// If this is not set, the default duration is 5 minutes
	// (see DefaultMaxConnectionAge).
	//
	// To disable this and keep connections in the pool indefinetly, set this to
	// a negative value.
	//
	// MaxConnectionAgeJitter is the ratio of random jitter +/- on top of
	// MaxConnectionAge. Default to 10% (see DefaultMaxConnectionAgeJitter).
	// For example, when MaxConnectionAge is 5min and MaxConnectionAgeJitter is
	// 10%, the TTL of the clients would be in range of (4:30, 5:30).
	//
	// When this is enabled, there will be one additional goroutine per connection
	// in the pool to do background housekeeping (to replace the expired
	// connections). We emit thriftbp_ttlclient_connection_housekeeping_total
	// counter with thrift_success tag to provide observalibility into the
	// background housekeeping.
	//
	// Due to a Go runtime bug [1], if you use a very small MaxConnectionAge or a
	// jitter very close to 1, the background housekeeping could cause excessive
	// CPU overhead.
	//
	// [1]: https://github.com/golang/go/issues/27707
	MaxConnectionAge       time.Duration `yaml:"maxConnectionAge"`
	MaxConnectionAgeJitter *float64      `yaml:"maxConnectionAgeJitter"`

	// ConnectTimeout and SocketTimeout are timeouts used by the underlying
	// thrift.TSocket.
	//
	// In most cases, you would want ConnectTimeout to be short, because if you
	// have problem connecting to the upstream you want to fail fast.
	//
	// For SocketTimeout, the value you should set depends on whether you set a
	// deadline to the context object to the client call functions or not.
	// If ALL your client calls will have a context object with a deadline
	// attached, then it's recommended to set SocketTimeout to a short value,
	// as this is the max overhead the client call will take over the set
	// deadline, in case the server is not-responding.
	// But if you don't always have a deadline attached to your client calls,
	// then SocketTimeout needs to be at least your upstream service's p99 latency
	// SLA. If it's shorter than that you are gonna close connections and fail
	// requests prematurely.
	//
	// It's recommended to make sure all your client call context objects have a
	// deadline set, and set SocketTimeout to a short value. For example:
	//
	//     clientCtx, cancel := context.WithTimeout(ctx, myCallTimeout)
	//     defer cancel()
	//     resp, err := client.MyCall(clientCtx, args)
	//
	// For both values, <=0 would mean no timeout.
	// In most cases you would want to set timeouts for both.
	ConnectTimeout time.Duration `yaml:"connectTimeout"`
	SocketTimeout  time.Duration `yaml:"socketTimeout"`

	// Any tags that should be applied to metrics logged by the ClientPool.
	// This includes the optional pool stats.
	//
	// Deprecated: We no longer emit any statsd metrics so this has no effect.
	MetricsTags metricsbp.Tags `yaml:"metricsTags"`

	// DefaultRetryOptions is the list of retry.Options to apply as the defaults
	// for the Retry middleware.
	//
	// This is optional, if it is not set, we will use a single option,
	// retry.Attempts(1).  This sets up the retry middleware but does not
	// automatically retry any requests.  You can set retry behavior per-call by
	// using retrybp.WithOptions.
	DefaultRetryOptions []retry.Option

	// ReportPoolStats signals to the ClientPool that it should report
	// statistics on the underlying clientpool.Pool in a background
	// goroutine.  If this is set to false, the reporting goroutine will
	// not be started and it will not report pool stats.
	//
	// It reports:
	// - the number of active clients to a gauge named
	//   "${ServiceSlug}.pool-active-connections".
	// - the number of allocated clients to a gauge named
	//   "${ServiceSlug}.pool-allocated-clients".
	//
	// The reporting goroutine is cancelled when the global metrics client
	// context is Done.
	//
	// Deprecated: The statsd metrics are deprecated and the prometheus metrics
	// are always reported.
	ReportPoolStats bool `yaml:"reportPoolStats"`

	// PoolGaugeInterval indicates how often we should update the active
	// connections gauge when collecting pool stats.
	//
	// When PoolGaugeInterval <= 0 and ReportPoolStats is true,
	// DefaultPoolGaugeInterval will be used instead.
	//
	// Deprecated: Not used any more. Prometheus gauges are auto scraped.
	PoolGaugeInterval time.Duration `yaml:"poolGaugeInterval"`

	// Suppress some of the errors returned by the server before sending them to
	// the client span.
	//
	// See MonitorClientArgs.ErrorSpanSuppressor for more details.
	//
	// This is optional. If it's not set IDLExceptionSuppressor will be used.
	ErrorSpanSuppressor errorsbp.Suppressor

	// When BreakerConfig is non-nil,
	// a breakerbp.FailureRatioBreaker will be created for the pool,
	// and its middleware will be set for the pool.
	BreakerConfig *breakerbp.Config `yaml:"breakerConfig"`

	// The edge context implementation. Optional.
	//
	// If it's not set, the global one from ecinterface.Get will be used instead.
	EdgeContextImpl ecinterface.Interface

	// The name for the server to identify this client,
	// via the "User-Agent" (HeaderUserAgent) THeader.
	//
	// Optional. If this is empty, no "User-Agent" header will be sent.
	ClientName string `yaml:"clientName"`

	// The hostname to add as a "thrift-hostname" header.
	//
	// Optional. If empty, no "thrift-hostname" header will be sent.
	ThriftHostnameHeader string `yaml:"thriftHostnameHeader"`
}

type DefaultClientMiddlewareArgs struct {
	// ServiceSlug is a short identifier for the thrift service you are creating
	// clients for.  The preferred convention is to take the service's name,
	// remove the 'Service' prefix, if present, and convert from camel case to
	// all lower case, hyphen separated.
	//
	// Examples:
	//
	//     AuthenticationService -> authentication
	//     ImageUploadService -> image-upload
	ServiceSlug string

	// RetryOptions is the list of retry.Options to apply as the defaults for the
	// Retry middleware.
	//
	// This is optional, if it is not set, we will use a single option,
	// retry.Attempts(1).  This sets up the retry middleware but does not
	// automatically retry any requests.  You can set retry behavior per-call by
	// using retrybp.WithOptions.
	RetryOptions []retry.Option

	// Suppress some of the errors returned by the server before sending them to
	// the client span.
	//
	// See MonitorClientArgs.ErrorSpanSuppressor for more details.
	//
	// This is optional. If it's not set IDLExceptionSuppressor will be used.
	ErrorSpanSuppressor errorsbp.Suppressor

	// When BreakerConfig is non-nil,
	// a breakerbp.FailureRatioBreaker will be created for the pool,
	// and its middleware will be set for the pool.
	BreakerConfig *breakerbp.Config

	// The edge context implementation. Optional.
	//
	// If it's not set, the global one from ecinterface.Get will be used instead.
	EdgeContextImpl ecinterface.Interface

	// The name for the server to identify this client,
	// via the "User-Agent" (HeaderUserAgent) THeader.
	//
	// Optional. If this is empty, no "User-Agent" header will be sent.
	ClientName string
}

type DefaultProcessorMiddlewaresArgs struct {
	// Suppress some of the errors returned by the server before sending them to
	// the server span.
	//
	// Based on Baseplate spec, the errors defined in your thrift IDL are not
	// treated as errors, and should be suppressed here. So in most cases that's
	// what the service developer should implement as the Suppressor here.
	//
	// Note that this suppressor only affects the errors send to the span. It
	// won't affect the errors returned to the client.
	//
	// This is optional. If it's not set IDLExceptionSuppressor will be used.
	ErrorSpanSuppressor errorsbp.Suppressor

	// Report the payload size metrics with this sample rate.
	//
	// This is optional. If it's not set none of the requests will be sampled.
	ReportPayloadSizeMetricsSampleRate float64

	// The edge context implementation. Optional.
	//
	// If it's not set, the global one from ecinterface.Get will be used instead.
	EdgeContextImpl ecinterface.Interface
}

type MonitorClientArgs struct {
	// The slug string of the service.
	//
	// Note that if this is the MonitorClient before retry,
	// ServiceSlug should also come with MonitorClientWrappedSlugSuffix.
	ServiceSlug string

	// Suppress some of the errors returned by the server before sending them to
	// the client span.
	//
	// Based on Baseplate spec, the errors defined in the server's thrift IDL are
	// not treated as errors, and should be suppressed here. So in most cases
	// that's what should be implemented as the Suppressor here.
	//
	// Note that this suppressor only affects the errors send to the span. It
	// won't affect the errors returned to the caller of the client function.
	//
	// This is optional. If it's not set IDLExceptionSuppressor will be used.
	ErrorSpanSuppressor errorsbp.Suppressor
}

type PoolError struct {
	// Cause is the inner error wrapped by PoolError.
	Cause error
}

type ServerConfig struct {
	// Required, used by both NewServer and NewBaseplateServer.
	//
	// This is the thrift processor implementation to handle endpoints.
	Processor thrift.TProcessor

	// Optional, used by both NewServer and NewBaseplateServer.
	//
	// For NewServer, this defines all the middlewares to wrap the server with.
	// For NewBaseplateServer, this only defines the middlewares in addition to
	// (and after) BaseplateDefaultProcessorMiddlewares.
	Middlewares []thrift.ProcessorMiddleware

	// Optional, used only by NewServer.
	//
	// A log wrapper that is used by the TSimpleServer.
	Logger thrift.Logger

	// Optional, used only by NewBaseplateServer.
	//
	// Please refer to the documentation of
	// DefaultProcessorMiddlewaresArgs.ErrorSpanSuppressor for more details
	// regarding how it is used.
	ErrorSpanSuppressor errorsbp.Suppressor

	// Optional, used only by NewBaseplateServer.
	//
	// Report the payload size metrics with this sample rate.
	// If not set none of the requests will be sampled.
	ReportPayloadSizeMetricsSampleRate float64

	// Optional, used by NewBaseplateServer and NewServer.
	//
	// Report the number of clients connected to the server as a runtime gauge
	// with metric name of 'thrift.connections'
	//
	// Deprecated: This feature is removed.
	ReportConnectionCount bool

	// Optional, used only by NewServer.
	// In NewBaseplateServer the address set in bp.Config() will be used instead.
	//
	// The endpoint address of your thrift service.
	//
	// This is ignored if Socket is non-nil.
	Addr string

	// Deprecated: No-op for now, will be removed in a future release.
	Timeout time.Duration

	// Optional, This duration is used to set both the read and write idle timeouts
	// for the thrift.TServerSocket used by the baseplate server.
	//
	// This is an experimental configuration and is subject to change or deprecation
	// without notice. When using NewBaseplateServer, setting a socket timeout will
	// also override the default thrift server logger to one that emits metrics
	// instead of logs in the event of a socket disconnect. A zero value means I/O
	// read or write operations will not time out.
	SocketTimeout time.Duration

	// Optional, used only by NewServer.
	// In NewBaseplateServer the address and timeout set in bp.Config() will be
	// used instead.
	//
	// You can choose to set Socket instead of Addr.
	Socket *thrift.TServerSocket
}