github.com/m3db/m3@v1.5.1-0.20231129193456-75a402aa583b/src/dbnode/client/types.go (about)

     1  // Copyright (c) 2016 Uber Technologies, Inc.
     2  //
     3  // Permission is hereby granted, free of charge, to any person obtaining a copy
     4  // of this software and associated documentation files (the "Software"), to deal
     5  // in the Software without restriction, including without limitation the rights
     6  // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
     7  // copies of the Software, and to permit persons to whom the Software is
     8  // furnished to do so, subject to the following conditions:
     9  //
    10  // The above copyright notice and this permission notice shall be included in
    11  // all copies or substantial portions of the Software.
    12  //
    13  // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    14  // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    15  // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    16  // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    17  // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    18  // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
    19  // THE SOFTWARE.
    20  
    21  package client
    22  
    23  import (
    24  	gocontext "context"
    25  	"time"
    26  
    27  	"github.com/m3db/m3/src/cluster/shard"
    28  	"github.com/m3db/m3/src/dbnode/encoding"
    29  	"github.com/m3db/m3/src/dbnode/generated/thrift/rpc"
    30  	"github.com/m3db/m3/src/dbnode/namespace"
    31  	"github.com/m3db/m3/src/dbnode/runtime"
    32  	"github.com/m3db/m3/src/dbnode/storage/block"
    33  	"github.com/m3db/m3/src/dbnode/storage/bootstrap/result"
    34  	"github.com/m3db/m3/src/dbnode/storage/index"
    35  	"github.com/m3db/m3/src/dbnode/topology"
    36  	"github.com/m3db/m3/src/x/clock"
    37  	"github.com/m3db/m3/src/x/context"
    38  	"github.com/m3db/m3/src/x/ident"
    39  	"github.com/m3db/m3/src/x/instrument"
    40  	"github.com/m3db/m3/src/x/pool"
    41  	xretry "github.com/m3db/m3/src/x/retry"
    42  	"github.com/m3db/m3/src/x/sampler"
    43  	"github.com/m3db/m3/src/x/serialize"
    44  	xsync "github.com/m3db/m3/src/x/sync"
    45  	xtime "github.com/m3db/m3/src/x/time"
    46  
    47  	"github.com/uber/tchannel-go"
    48  	"github.com/uber/tchannel-go/thrift"
    49  )
    50  
    51  // Client can create sessions to write and read to a cluster.
    52  type Client interface {
    53  	// Options returns the Client Options.
    54  	Options() Options
    55  
    56  	// NewSession creates a new session.
    57  	NewSession() (Session, error)
    58  
    59  	// NewSessionWithOptions creates a new session with the provided Options instead of the ones returned by Options.
    60  	NewSessionWithOptions(opts Options) (Session, error)
    61  
    62  	// DefaultSession creates a default session that gets reused.
    63  	DefaultSession() (Session, error)
    64  
    65  	// DefaultSessionActive returns whether the default session is active.
    66  	DefaultSessionActive() bool
    67  }
    68  
    69  // Session can write and read to a cluster.
    70  type Session interface {
    71  	// WriteClusterAvailability returns whether cluster is available for writes.
    72  	WriteClusterAvailability() (bool, error)
    73  
    74  	// ReadClusterAvailability returns whether cluster is available for reads.
    75  	ReadClusterAvailability() (bool, error)
    76  
    77  	// Write value to the database for an ID.
    78  	Write(
    79  		namespace,
    80  		id ident.ID,
    81  		t xtime.UnixNano,
    82  		value float64,
    83  		unit xtime.Unit,
    84  		annotation []byte,
    85  	) error
    86  
    87  	// WriteTagged value to the database for an ID and given tags.
    88  	WriteTagged(
    89  		namespace,
    90  		id ident.ID,
    91  		tags ident.TagIterator,
    92  		t xtime.UnixNano,
    93  		value float64,
    94  		unit xtime.Unit,
    95  		annotation []byte,
    96  	) error
    97  
    98  	// Fetch values from the database for an ID.
    99  	Fetch(
   100  		namespace,
   101  		id ident.ID,
   102  		startInclusive,
   103  		endExclusive xtime.UnixNano,
   104  	) (encoding.SeriesIterator, error)
   105  
   106  	// FetchIDs values from the database for a set of IDs.
   107  	FetchIDs(
   108  		namespace ident.ID,
   109  		ids ident.Iterator,
   110  		startInclusive,
   111  		endExclusive xtime.UnixNano,
   112  	) (encoding.SeriesIterators, error)
   113  
   114  	// FetchTagged resolves the provided query to known IDs, and fetches the data for them.
   115  	FetchTagged(
   116  		ctx gocontext.Context,
   117  		namespace ident.ID,
   118  		q index.Query,
   119  		opts index.QueryOptions,
   120  	) (encoding.SeriesIterators, FetchResponseMetadata, error)
   121  
   122  	// FetchTaggedIDs resolves the provided query to known IDs.
   123  	FetchTaggedIDs(
   124  		ctx gocontext.Context,
   125  		namespace ident.ID,
   126  		q index.Query,
   127  		opts index.QueryOptions,
   128  	) (TaggedIDsIterator, FetchResponseMetadata, error)
   129  
   130  	// Aggregate aggregates values from the database for the given set of constraints.
   131  	Aggregate(
   132  		ctx gocontext.Context,
   133  		namespace ident.ID,
   134  		q index.Query,
   135  		opts index.AggregationOptions,
   136  	) (AggregatedTagsIterator, FetchResponseMetadata, error)
   137  
   138  	// ShardID returns the given shard for an ID for callers
   139  	// to easily discern what shard is failing when operations
   140  	// for given IDs begin failing.
   141  	ShardID(id ident.ID) (uint32, error)
   142  
   143  	// IteratorPools exposes the internal iterator pools used by the session to clients.
   144  	IteratorPools() (encoding.IteratorPools, error)
   145  
   146  	// Close the session
   147  	Close() error
   148  }
   149  
   150  // FetchResponseMetadata is metadata about a fetch response.
   151  type FetchResponseMetadata struct {
   152  	// Exhaustive indicates whether the underlying data set presents a full
   153  	// collection of retrieved data.
   154  	Exhaustive bool
   155  	// Responses is the count of responses.
   156  	Responses int
   157  	// EstimateTotalBytes is an approximation of the total byte size of the response.
   158  	EstimateTotalBytes int
   159  	// WaitedIndex counts how many times index querying had to wait for permits.
   160  	WaitedIndex int
   161  	// WaitedSeriesRead counts how many times series being read had to wait for permits.
   162  	WaitedSeriesRead int
   163  }
   164  
   165  // AggregatedTagsIterator iterates over a collection of tag names with optionally
   166  // associated values.
   167  type AggregatedTagsIterator interface {
   168  	// Next returns whether there are more items in the collection.
   169  	Next() bool
   170  
   171  	// Remaining returns the number of elements remaining to be iterated over.
   172  	Remaining() int
   173  
   174  	// Current returns the current tagName, and associated tagValues iterator.
   175  	// These remain valid until Next() is called again.
   176  	Current() (tagName ident.ID, tagValues ident.Iterator)
   177  
   178  	// Err returns any error encountered.
   179  	Err() error
   180  
   181  	// Finalize releases any held resources.
   182  	Finalize()
   183  }
   184  
   185  // TaggedIDsIterator iterates over a collection of IDs with associated tags and namespace.
   186  type TaggedIDsIterator interface {
   187  	// Next returns whether there are more items in the collection.
   188  	Next() bool
   189  
   190  	// Remaining returns the number of elements remaining to be iterated over.
   191  	Remaining() int
   192  
   193  	// Current returns the ID, Tags and Namespace for a single timeseries.
   194  	// These remain valid until Next() is called again.
   195  	Current() (namespaceID ident.ID, seriesID ident.ID, tags ident.TagIterator)
   196  
   197  	// Err returns any error encountered.
   198  	Err() error
   199  
   200  	// Finalize releases any held resources.
   201  	Finalize()
   202  }
   203  
   204  // AdminClient can create administration sessions.
   205  type AdminClient interface {
   206  	Client
   207  
   208  	// NewAdminSession creates a new admin session.
   209  	NewAdminSession() (AdminSession, error)
   210  
   211  	// DefaultAdminSession creates a default admin session that gets reused.
   212  	DefaultAdminSession() (AdminSession, error)
   213  }
   214  
   215  // PeerBlockMetadataIter iterates over a collection of
   216  // blocks metadata from peers.
   217  type PeerBlockMetadataIter interface {
   218  	// Next returns whether there are more items in the collection.
   219  	Next() bool
   220  
   221  	// Current returns the host and block metadata, which remain
   222  	// valid until Next() is called again.
   223  	Current() (topology.Host, block.Metadata)
   224  
   225  	// Err returns any error encountered
   226  	Err() error
   227  }
   228  
   229  // PeerBlocksIter iterates over a collection of blocks from peers.
   230  type PeerBlocksIter interface {
   231  	// Next returns whether there are more items in the collection.
   232  	Next() bool
   233  
   234  	// Current returns the metadata, and block data for a single block replica.
   235  	// These remain valid until Next() is called again.
   236  	Current() (topology.Host, ident.ID, ident.Tags, block.DatabaseBlock)
   237  
   238  	// Err returns any error encountered.
   239  	Err() error
   240  }
   241  
   242  // AdminSession can perform administrative and node-to-node operations.
   243  type AdminSession interface {
   244  	Session
   245  
   246  	// Origin returns the host that initiated the session.
   247  	Origin() topology.Host
   248  
   249  	// Replicas returns the replication factor.
   250  	Replicas() int
   251  
   252  	// TopologyMap returns the current topology map. Note that the session
   253  	// has a separate topology watch than the database itself, so the two
   254  	// values can be out of sync and this method should not be relied upon
   255  	// if the current view of the topology as seen by the database is required.
   256  	TopologyMap() (topology.Map, error)
   257  
   258  	// Truncate will truncate the namespace for a given shard.
   259  	Truncate(namespace ident.ID) (int64, error)
   260  
   261  	// FetchBootstrapBlocksFromPeers will fetch the most fulfilled block
   262  	// for each series using the runtime configurable bootstrap level consistency.
   263  	FetchBootstrapBlocksFromPeers(
   264  		namespace namespace.Metadata,
   265  		shard uint32,
   266  		start, end xtime.UnixNano,
   267  		opts result.Options,
   268  	) (result.ShardResult, error)
   269  
   270  	// FetchBootstrapBlocksMetadataFromPeers will fetch the blocks metadata from
   271  	// available peers using the runtime configurable bootstrap level consistency.
   272  	FetchBootstrapBlocksMetadataFromPeers(
   273  		namespace ident.ID,
   274  		shard uint32,
   275  		start, end xtime.UnixNano,
   276  		result result.Options,
   277  	) (PeerBlockMetadataIter, error)
   278  
   279  	// FetchBlocksMetadataFromPeers will fetch the blocks metadata from
   280  	// available peers.
   281  	FetchBlocksMetadataFromPeers(
   282  		namespace ident.ID,
   283  		shard uint32,
   284  		start, end xtime.UnixNano,
   285  		consistencyLevel topology.ReadConsistencyLevel,
   286  		result result.Options,
   287  	) (PeerBlockMetadataIter, error)
   288  
   289  	// FetchBlocksFromPeers will fetch the required blocks from the
   290  	// peers specified.
   291  	FetchBlocksFromPeers(
   292  		namespace namespace.Metadata,
   293  		shard uint32,
   294  		consistencyLevel topology.ReadConsistencyLevel,
   295  		metadatas []block.ReplicaMetadata,
   296  		opts result.Options,
   297  	) (PeerBlocksIter, error)
   298  
   299  	// BorrowConnections will borrow connection for hosts belonging to a shard.
   300  	BorrowConnections(
   301  		shardID uint32,
   302  		fn WithBorrowConnectionFn,
   303  		opts BorrowConnectionOptions,
   304  	) (BorrowConnectionsResult, error)
   305  
   306  	// DedicatedConnection will open and health check a new connection to one of the
   307  	// hosts belonging to a shard. The connection should be used for long running requests.
   308  	// For normal requests consider using BorrowConnections.
   309  	DedicatedConnection(
   310  		shardID uint32,
   311  		opts DedicatedConnectionOptions,
   312  	) (rpc.TChanNode, Channel, error)
   313  }
   314  
   315  // BorrowConnectionOptions are options to use when borrowing a connection
   316  type BorrowConnectionOptions struct {
   317  	// ContinueOnBorrowError allows skipping hosts that cannot borrow
   318  	// a connection for.
   319  	ContinueOnBorrowError bool
   320  	// ExcludeOrigin will exclude attempting to borrow a connection for
   321  	// the origin host (i.e. the local host).
   322  	ExcludeOrigin bool
   323  }
   324  
   325  // BorrowConnectionsResult is a result used when borrowing connections.
   326  type BorrowConnectionsResult struct {
   327  	Borrowed int
   328  }
   329  
   330  // WithBorrowConnectionFn is used to do work with a borrowed connection.
   331  type WithBorrowConnectionFn func(
   332  	shard shard.Shard,
   333  	host topology.Host,
   334  	client rpc.TChanNode,
   335  	channel Channel,
   336  ) (WithBorrowConnectionResult, error)
   337  
   338  // WithBorrowConnectionResult is returned from a borrow connection function.
   339  type WithBorrowConnectionResult struct {
   340  	// Break will break the iteration.
   341  	Break bool
   342  }
   343  
   344  // DedicatedConnectionOptions are options used for getting a dedicated connection.
   345  type DedicatedConnectionOptions struct {
   346  	ShardStateFilter      shard.State
   347  	BootstrappedNodesOnly bool
   348  }
   349  
   350  // Options is a set of client options.
   351  type Options interface {
   352  	// Validate validates the options.
   353  	Validate() error
   354  
   355  	// SetEncodingM3TSZ sets M3TSZ encoding.
   356  	SetEncodingM3TSZ() Options
   357  
   358  	// SetEncodingProto sets proto encoding.
   359  	SetEncodingProto(encodingOpts encoding.Options) Options
   360  
   361  	// IsSetEncodingProto returns whether proto encoding is set.
   362  	IsSetEncodingProto() bool
   363  
   364  	// SetRuntimeOptionsManager sets the runtime options manager, it is optional
   365  	SetRuntimeOptionsManager(value runtime.OptionsManager) Options
   366  
   367  	// RuntimeOptionsManager returns the runtime options manager, it is optional.
   368  	RuntimeOptionsManager() runtime.OptionsManager
   369  
   370  	// SetClockOptions sets the clock options.
   371  	SetClockOptions(value clock.Options) Options
   372  
   373  	// ClockOptions returns the clock options.
   374  	ClockOptions() clock.Options
   375  
   376  	// SetInstrumentOptions sets the instrumentation options.
   377  	SetInstrumentOptions(value instrument.Options) Options
   378  
   379  	// InstrumentOptions returns the instrumentation options.
   380  	InstrumentOptions() instrument.Options
   381  
   382  	// SetLogErrorSampleRate sets the log error sample rate between [0,1.0].
   383  	SetLogErrorSampleRate(value sampler.Rate) Options
   384  
   385  	// LogErrorSampleRate returns the log error sample rate between [0,1.0].
   386  	LogErrorSampleRate() sampler.Rate
   387  
   388  	// SetLogHostWriteErrorSampleRate sets the log error per host sample rate between [0,1.0].
   389  	SetLogHostWriteErrorSampleRate(value sampler.Rate) Options
   390  
   391  	// LogHostWriteErrorSampleRate returns the log error per host sample rate between [0,1.0].
   392  	LogHostWriteErrorSampleRate() sampler.Rate
   393  
   394  	// SetLogHostFetchErrorSampleRate sets the log error per host sample rate between [0,1.0].
   395  	SetLogHostFetchErrorSampleRate(value sampler.Rate) Options
   396  
   397  	// LogHostFetchErrorSampleRate returns the log error per host sample rate between [0,1.0].
   398  	LogHostFetchErrorSampleRate() sampler.Rate
   399  
   400  	// SetTopologyInitializer sets the TopologyInitializer.
   401  	SetTopologyInitializer(value topology.Initializer) Options
   402  
   403  	// TopologyInitializer returns the TopologyInitializer.
   404  	TopologyInitializer() topology.Initializer
   405  
   406  	// SetReadConsistencyLevel sets the read consistency level.
   407  	SetReadConsistencyLevel(value topology.ReadConsistencyLevel) Options
   408  
   409  	// ReadConsistencyLevel returns the read consistency level.
   410  	ReadConsistencyLevel() topology.ReadConsistencyLevel
   411  
   412  	// SetWriteConsistencyLevel sets the write consistency level.
   413  	SetWriteConsistencyLevel(value topology.ConsistencyLevel) Options
   414  
   415  	// WriteConsistencyLevel returns the write consistency level.
   416  	WriteConsistencyLevel() topology.ConsistencyLevel
   417  
   418  	// SetChannelOptions sets the channelOptions.
   419  	SetChannelOptions(value *tchannel.ChannelOptions) Options
   420  
   421  	// ChannelOptions returns the channelOptions.
   422  	ChannelOptions() *tchannel.ChannelOptions
   423  
   424  	// SetMaxConnectionCount sets the maxConnectionCount.
   425  	SetMaxConnectionCount(value int) Options
   426  
   427  	// MaxConnectionCount returns the maxConnectionCount.
   428  	MaxConnectionCount() int
   429  
   430  	// SetMinConnectionCount sets the minConnectionCount.
   431  	SetMinConnectionCount(value int) Options
   432  
   433  	// MinConnectionCount returns the minConnectionCount.
   434  	MinConnectionCount() int
   435  
   436  	// SetHostConnectTimeout sets the hostConnectTimeout.
   437  	SetHostConnectTimeout(value time.Duration) Options
   438  
   439  	// HostConnectTimeout returns the hostConnectTimeout.
   440  	HostConnectTimeout() time.Duration
   441  
   442  	// SetClusterConnectTimeout sets the clusterConnectTimeout.
   443  	SetClusterConnectTimeout(value time.Duration) Options
   444  
   445  	// ClusterConnectTimeout returns the clusterConnectTimeout.
   446  	ClusterConnectTimeout() time.Duration
   447  
   448  	// SetClusterConnectConsistencyLevel sets the clusterConnectConsistencyLevel.
   449  	SetClusterConnectConsistencyLevel(value topology.ConnectConsistencyLevel) Options
   450  
   451  	// ClusterConnectConsistencyLevel returns the clusterConnectConsistencyLevel.
   452  	ClusterConnectConsistencyLevel() topology.ConnectConsistencyLevel
   453  
   454  	// SetWriteRequestTimeout sets the writeRequestTimeout.
   455  	SetWriteRequestTimeout(value time.Duration) Options
   456  
   457  	// WriteRequestTimeout returns the writeRequestTimeout.
   458  	WriteRequestTimeout() time.Duration
   459  
   460  	// SetFetchRequestTimeout sets the fetchRequestTimeout.
   461  	SetFetchRequestTimeout(value time.Duration) Options
   462  
   463  	// FetchRequestTimeout returns the fetchRequestTimeout.
   464  	FetchRequestTimeout() time.Duration
   465  
   466  	// SetTruncateRequestTimeout sets the truncateRequestTimeout.
   467  	SetTruncateRequestTimeout(value time.Duration) Options
   468  
   469  	// TruncateRequestTimeout returns the truncateRequestTimeout.
   470  	TruncateRequestTimeout() time.Duration
   471  
   472  	// SetBackgroundConnectInterval sets the backgroundConnectInterval.
   473  	SetBackgroundConnectInterval(value time.Duration) Options
   474  
   475  	// BackgroundConnectInterval returns the backgroundConnectInterval.
   476  	BackgroundConnectInterval() time.Duration
   477  
   478  	// SetBackgroundConnectStutter sets the backgroundConnectStutter.
   479  	SetBackgroundConnectStutter(value time.Duration) Options
   480  
   481  	// BackgroundConnectStutter returns the backgroundConnectStutter.
   482  	BackgroundConnectStutter() time.Duration
   483  
   484  	// SetBackgroundHealthCheckInterval sets the background health check interval
   485  	SetBackgroundHealthCheckInterval(value time.Duration) Options
   486  
   487  	// BackgroundHealthCheckInterval returns the background health check interval
   488  	BackgroundHealthCheckInterval() time.Duration
   489  
   490  	// SetBackgroundHealthCheckStutter sets the background health check stutter
   491  	SetBackgroundHealthCheckStutter(value time.Duration) Options
   492  
   493  	// BackgroundHealthCheckStutter returns the background health check stutter
   494  	BackgroundHealthCheckStutter() time.Duration
   495  
   496  	// SetBackgroundHealthCheckFailLimit sets the background health failure
   497  	// limit before connection is deemed unhealth
   498  	SetBackgroundHealthCheckFailLimit(value int) Options
   499  
   500  	// BackgroundHealthCheckFailLimit returns the background health failure
   501  	// limit before connection is deemed unhealth
   502  	BackgroundHealthCheckFailLimit() int
   503  
   504  	// SetBackgroundHealthCheckFailThrottleFactor sets the throttle factor to
   505  	// apply when calculating how long to wait between a failed health check and
   506  	// a retry attempt. It is applied by multiplying against the host connect
   507  	// timeout to produce a throttle sleep value.
   508  	SetBackgroundHealthCheckFailThrottleFactor(value float64) Options
   509  
   510  	// BackgroundHealthCheckFailThrottleFactor returns the throttle factor to
   511  	// apply when calculating how long to wait between a failed health check and
   512  	// a retry attempt. It is applied by multiplying against the host connect
   513  	// timeout to produce a throttle sleep value.
   514  	BackgroundHealthCheckFailThrottleFactor() float64
   515  
   516  	// SetWriteRetrier sets the write retrier when performing a write for
   517  	// a write operation. Only retryable errors are retried.
   518  	SetWriteRetrier(value xretry.Retrier) Options
   519  
   520  	// WriteRetrier returns the write retrier when perform a write for
   521  	// a write operation. Only retryable errors are retried.
   522  	WriteRetrier() xretry.Retrier
   523  
   524  	// SetFetchRetrier sets the fetch retrier when performing a write for
   525  	// a fetch operation. Only retryable errors are retried.
   526  	SetFetchRetrier(value xretry.Retrier) Options
   527  
   528  	// FetchRetrier returns the fetch retrier when performing a fetch for
   529  	// a fetch operation. Only retryable errors are retried.
   530  	FetchRetrier() xretry.Retrier
   531  
   532  	// SetWriteShardsInitializing sets whether to write to shards that are
   533  	// initializing or not.
   534  	SetWriteShardsInitializing(value bool) Options
   535  
   536  	// WriteShardsInitializing returns whether to write to shards that are
   537  	// initializing or not.
   538  	WriteShardsInitializing() bool
   539  
   540  	// SetShardsLeavingCountTowardsConsistency sets whether to count shards
   541  	// that are leaving or not towards consistency level calculations.
   542  	SetShardsLeavingCountTowardsConsistency(value bool) Options
   543  
   544  	// ShardsLeavingCountTowardsConsistency returns whether to count shards
   545  	// that are leaving or not towards consistency level calculations.
   546  	ShardsLeavingCountTowardsConsistency() bool
   547  
   548  	// SetShardsLeavingAndInitializingCountTowardsConsistency sets whether to count
   549  	// the writes to the shards that are leaving and initializing as pair towards consistency.
   550  	SetShardsLeavingAndInitializingCountTowardsConsistency(value bool) Options
   551  
   552  	// ShardsLeavingAndInitializingCountTowardsConsistency returns whether to count the writes to the shards
   553  	// that are leaving and initializing towards consistency level calculations.
   554  	ShardsLeavingAndInitializingCountTowardsConsistency() bool
   555  
   556  	// SetTagEncoderOptions sets the TagEncoderOptions.
   557  	SetTagEncoderOptions(value serialize.TagEncoderOptions) Options
   558  
   559  	// TagEncoderOptions returns the TagEncoderOptions.
   560  	TagEncoderOptions() serialize.TagEncoderOptions
   561  
   562  	// SetTagEncoderPoolSize sets the TagEncoderPoolSize.
   563  	SetTagEncoderPoolSize(value pool.Size) Options
   564  
   565  	// TagEncoderPoolSize returns the TagEncoderPoolSize.
   566  	TagEncoderPoolSize() pool.Size
   567  
   568  	// SetTagDecoderOptions sets the TagDecoderOptions.
   569  	SetTagDecoderOptions(value serialize.TagDecoderOptions) Options
   570  
   571  	// TagDecoderOptions returns the TagDecoderOptions.
   572  	TagDecoderOptions() serialize.TagDecoderOptions
   573  
   574  	// SetTagDecoderPoolSize sets the TagDecoderPoolSize.
   575  	SetTagDecoderPoolSize(value pool.Size) Options
   576  
   577  	// TagDecoderPoolSize returns the TagDecoderPoolSize.
   578  	TagDecoderPoolSize() pool.Size
   579  
   580  	// SetWriteBatchSize sets the writeBatchSize
   581  	// NB(r): for a write only application load this should match the host
   582  	// queue ops flush size so that each time a host queue is flushed it can
   583  	// fit the entire flushed write ops into a single batch.
   584  	SetWriteBatchSize(value int) Options
   585  
   586  	// WriteBatchSize returns the writeBatchSize.
   587  	WriteBatchSize() int
   588  
   589  	// SetFetchBatchSize sets the fetchBatchSize
   590  	// NB(r): for a fetch only application load this should match the host
   591  	// queue ops flush size so that each time a host queue is flushed it can
   592  	// fit the entire flushed fetch ops into a single batch.
   593  	SetFetchBatchSize(value int) Options
   594  
   595  	// FetchBatchSize returns the fetchBatchSize.
   596  	FetchBatchSize() int
   597  
   598  	// SetWriteOpPoolSize sets the writeOperationPoolSize.
   599  	SetWriteOpPoolSize(value pool.Size) Options
   600  
   601  	// WriteOpPoolSize returns the writeOperationPoolSize.
   602  	WriteOpPoolSize() pool.Size
   603  
   604  	// SetWriteTaggedOpPoolSize sets the writeTaggedOperationPoolSize.
   605  	SetWriteTaggedOpPoolSize(value pool.Size) Options
   606  
   607  	// WriteTaggedOpPoolSize returns the writeTaggedOperationPoolSize.
   608  	WriteTaggedOpPoolSize() pool.Size
   609  
   610  	// SetFetchBatchOpPoolSize sets the fetchBatchOpPoolSize.
   611  	SetFetchBatchOpPoolSize(value pool.Size) Options
   612  
   613  	// FetchBatchOpPoolSize returns the fetchBatchOpPoolSize.
   614  	FetchBatchOpPoolSize() pool.Size
   615  
   616  	// SetCheckedBytesWrapperPoolSize sets the checkedBytesWrapperPoolSize.
   617  	SetCheckedBytesWrapperPoolSize(value pool.Size) Options
   618  
   619  	// CheckedBytesWrapperPoolSize returns the checkedBytesWrapperPoolSize.
   620  	CheckedBytesWrapperPoolSize() pool.Size
   621  
   622  	// SetHostQueueOpsFlushSize sets the hostQueueOpsFlushSize.
   623  	SetHostQueueOpsFlushSize(value int) Options
   624  
   625  	// HostQueueOpsFlushSize returns the hostQueueOpsFlushSize.
   626  	HostQueueOpsFlushSize() int
   627  
   628  	// SetHostQueueOpsFlushInterval sets the hostQueueOpsFlushInterval.
   629  	SetHostQueueOpsFlushInterval(value time.Duration) Options
   630  
   631  	// HostQueueOpsFlushInterval returns the hostQueueOpsFlushInterval.
   632  	HostQueueOpsFlushInterval() time.Duration
   633  
   634  	// SetContextPool sets the contextPool.
   635  	SetContextPool(value context.Pool) Options
   636  
   637  	// ContextPool returns the contextPool.
   638  	ContextPool() context.Pool
   639  
   640  	// SetCheckedBytesPool sets the checked bytes pool.
   641  	SetCheckedBytesPool(value pool.CheckedBytesPool) Options
   642  
   643  	// CheckedBytesPool returns the checked bytes pool.
   644  	CheckedBytesPool() pool.CheckedBytesPool
   645  
   646  	// SetIdentifierPool sets the identifier pool.
   647  	SetIdentifierPool(value ident.Pool) Options
   648  
   649  	// IdentifierPool returns the identifier pool.
   650  	IdentifierPool() ident.Pool
   651  
   652  	// SetHostQueueOpsArrayPoolSize sets the hostQueueOpsArrayPoolSize.
   653  	SetHostQueueOpsArrayPoolSize(value pool.Size) Options
   654  
   655  	// HostQueueOpsArrayPoolSize returns the hostQueueOpsArrayPoolSize.
   656  	HostQueueOpsArrayPoolSize() pool.Size
   657  
   658  	// SetHostQueueNewPooledWorkerFn sets the host queue new pooled worker function.
   659  	SetHostQueueNewPooledWorkerFn(value xsync.NewPooledWorkerFn) Options
   660  
   661  	// HostQueueNewPooledWorkerFn sets the host queue new pooled worker function.
   662  	HostQueueNewPooledWorkerFn() xsync.NewPooledWorkerFn
   663  
   664  	// SetHostQueueEmitsHealthStatus sets the hostQueueEmitHealthStatus.
   665  	SetHostQueueEmitsHealthStatus(value bool) Options
   666  
   667  	// HostQueueEmitsHealthStatus returns the hostQueueEmitHealthStatus.
   668  	HostQueueEmitsHealthStatus() bool
   669  
   670  	// SetSeriesIteratorPoolSize sets the seriesIteratorPoolSize.
   671  	SetSeriesIteratorPoolSize(value pool.Size) Options
   672  
   673  	// SeriesIteratorPoolSize returns the seriesIteratorPoolSize.
   674  	SeriesIteratorPoolSize() pool.Size
   675  
   676  	// SetReaderIteratorAllocate sets the readerIteratorAllocate.
   677  	SetReaderIteratorAllocate(value encoding.ReaderIteratorAllocate) Options
   678  
   679  	// ReaderIteratorAllocate returns the readerIteratorAllocate.
   680  	ReaderIteratorAllocate() encoding.ReaderIteratorAllocate
   681  
   682  	// SetSchemaRegistry sets the schema registry.
   683  	SetSchemaRegistry(registry namespace.SchemaRegistry) AdminOptions
   684  
   685  	// SchemaRegistry returns the schema registry.
   686  	SchemaRegistry() namespace.SchemaRegistry
   687  
   688  	// SetAsyncTopologyInitializers sets the AsyncTopologyInitializers
   689  	SetAsyncTopologyInitializers(value []topology.Initializer) Options
   690  
   691  	// AsyncTopologyInitializers returns the AsyncTopologyInitializers
   692  	AsyncTopologyInitializers() []topology.Initializer
   693  
   694  	// SetAsyncWriteWorkerPool sets the worker pool for async writes.
   695  	SetAsyncWriteWorkerPool(value xsync.PooledWorkerPool) Options
   696  
   697  	// AsyncWriteWorkerPool returns the worker pool for async writes.
   698  	AsyncWriteWorkerPool() xsync.PooledWorkerPool
   699  
   700  	// SetAsyncWriteMaxConcurrency sets the async writes maximum concurrency.
   701  	SetAsyncWriteMaxConcurrency(value int) Options
   702  
   703  	// AsyncWriteMaxConcurrency returns the async writes maximum concurrency.
   704  	AsyncWriteMaxConcurrency() int
   705  
   706  	// SetUseV2BatchAPIs sets whether the V2 batch APIs should be used.
   707  	SetUseV2BatchAPIs(value bool) Options
   708  
   709  	// UseV2BatchAPIs returns whether the V2 batch APIs should be used.
   710  	UseV2BatchAPIs() bool
   711  
   712  	// SetIterationOptions sets experimental iteration options.
   713  	SetIterationOptions(index.IterationOptions) Options
   714  
   715  	// IterationOptions returns experimental iteration options.
   716  	IterationOptions() index.IterationOptions
   717  
   718  	// SetWriteTimestampOffset sets the write timestamp offset.
   719  	SetWriteTimestampOffset(value time.Duration) AdminOptions
   720  
   721  	// WriteTimestampOffset returns the write timestamp offset.
   722  	WriteTimestampOffset() time.Duration
   723  
   724  	// SetNewConnectionFn sets a new connection generator function.
   725  	SetNewConnectionFn(value NewConnectionFn) AdminOptions
   726  
   727  	// NewConnectionFn returns the new connection generator function.
   728  	NewConnectionFn() NewConnectionFn
   729  
   730  	// SetNamespaceInitializer sets the NamespaceInitializer used to generate a namespace.Registry object
   731  	// that can be used to watch namespaces.
   732  	SetNamespaceInitializer(value namespace.Initializer) Options
   733  
   734  	// NamespaceInitializer returns the NamespaceInitializer.
   735  	NamespaceInitializer() namespace.Initializer
   736  
   737  	// SetThriftContextFn sets the retrier for streaming blocks.
   738  	SetThriftContextFn(value ThriftContextFn) Options
   739  
   740  	// ThriftContextFn returns the retrier for streaming blocks.
   741  	ThriftContextFn() ThriftContextFn
   742  }
   743  
   744  // ThriftContextFn turns a context into a thrift context for a thrift call.
   745  type ThriftContextFn func(gocontext.Context) thrift.Context
   746  
   747  // AdminOptions is a set of administration client options.
   748  type AdminOptions interface {
   749  	Options
   750  
   751  	// SetOrigin sets the current host originating requests from.
   752  	SetOrigin(value topology.Host) AdminOptions
   753  
   754  	// Origin gets the current host originating requests from.
   755  	Origin() topology.Host
   756  
   757  	// SetBootstrapConsistencyLevel sets the bootstrap consistency level.
   758  	SetBootstrapConsistencyLevel(value topology.ReadConsistencyLevel) AdminOptions
   759  
   760  	// BootstrapConsistencyLevel returns the bootstrap consistency level.
   761  	BootstrapConsistencyLevel() topology.ReadConsistencyLevel
   762  
   763  	// SetFetchSeriesBlocksMaxBlockRetries sets the max retries for fetching series blocks.
   764  	SetFetchSeriesBlocksMaxBlockRetries(value int) AdminOptions
   765  
   766  	// FetchSeriesBlocksMaxBlockRetries gets the max retries for fetching series blocks.
   767  	FetchSeriesBlocksMaxBlockRetries() int
   768  
   769  	// SetFetchSeriesBlocksBatchSize sets the batch size for fetching series blocks in batch.
   770  	SetFetchSeriesBlocksBatchSize(value int) AdminOptions
   771  
   772  	// FetchSeriesBlocksBatchSize gets the batch size for fetching series blocks in batch.
   773  	FetchSeriesBlocksBatchSize() int
   774  
   775  	// SetFetchSeriesBlocksMetadataBatchTimeout sets the timeout for fetching series blocks metadata in batch.
   776  	SetFetchSeriesBlocksMetadataBatchTimeout(value time.Duration) AdminOptions
   777  
   778  	// FetchSeriesBlocksMetadataBatchTimeout gets the timeout for fetching series blocks metadata in batch.
   779  	FetchSeriesBlocksMetadataBatchTimeout() time.Duration
   780  
   781  	// SetFetchSeriesBlocksBatchTimeout sets the timeout for fetching series blocks in batch.
   782  	SetFetchSeriesBlocksBatchTimeout(value time.Duration) AdminOptions
   783  
   784  	// FetchSeriesBlocksBatchTimeout gets the timeout for fetching series blocks in batch.
   785  	FetchSeriesBlocksBatchTimeout() time.Duration
   786  
   787  	// SetFetchSeriesBlocksBatchConcurrency sets the concurrency for fetching series blocks in batch.
   788  	SetFetchSeriesBlocksBatchConcurrency(value int) AdminOptions
   789  
   790  	// FetchSeriesBlocksBatchConcurrency gets the concurrency for fetching series blocks in batch.
   791  	FetchSeriesBlocksBatchConcurrency() int
   792  
   793  	// SetStreamBlocksRetrier sets the retrier for streaming blocks.
   794  	SetStreamBlocksRetrier(value xretry.Retrier) AdminOptions
   795  
   796  	// StreamBlocksRetrier returns the retrier for streaming blocks.
   797  	StreamBlocksRetrier() xretry.Retrier
   798  }
   799  
   800  // The rest of these types are internal types that mocks are generated for
   801  // in file mode and hence need to stay in this file and refer to the other
   802  // types such as AdminSession.  When mocks are generated in file mode the
   803  // other types they reference need to be in the same file.
   804  
   805  type clientSession interface {
   806  	AdminSession
   807  
   808  	// Open the client session.
   809  	Open() error
   810  }
   811  
   812  type hostQueue interface {
   813  	// Open the host queue.
   814  	Open()
   815  
   816  	// Len returns the length of the queue.
   817  	Len() int
   818  
   819  	// Enqueue an operation.
   820  	Enqueue(op op) error
   821  
   822  	// Host gets the host.
   823  	Host() topology.Host
   824  
   825  	// ConnectionCount gets the current open connection count.
   826  	ConnectionCount() int
   827  
   828  	// ConnectionPool gets the connection pool.
   829  	ConnectionPool() connectionPool
   830  
   831  	// BorrowConnection will borrow a connection and execute a user function.
   832  	BorrowConnection(fn WithConnectionFn) error
   833  
   834  	// Close the host queue, will flush any operations still pending.
   835  	Close()
   836  }
   837  
   838  // WithConnectionFn is a callback for a connection to a host.
   839  type WithConnectionFn func(client rpc.TChanNode, ch Channel)
   840  
   841  // Channel is an interface for tchannel.Channel struct.
   842  type Channel interface {
   843  	GetSubChannel(serviceName string, opts ...tchannel.SubChannelOption) *tchannel.SubChannel
   844  	Close()
   845  }
   846  
   847  type connectionPool interface {
   848  	// Open starts the connection pool connecting and health checking.
   849  	Open()
   850  
   851  	// ConnectionCount gets the current open connection count.
   852  	ConnectionCount() int
   853  
   854  	// NextClient gets the next client for use by the connection pool.
   855  	NextClient() (rpc.TChanNode, Channel, error)
   856  
   857  	// Close the connection pool.
   858  	Close()
   859  }
   860  
   861  type peerSource interface {
   862  	// BorrowConnection will borrow a connection and execute a user function.
   863  	BorrowConnection(hostID string, fn WithConnectionFn) error
   864  }
   865  
   866  type peer interface {
   867  	// Host gets the host.
   868  	Host() topology.Host
   869  
   870  	// BorrowConnection will borrow a connection and execute a user function.
   871  	BorrowConnection(fn WithConnectionFn) error
   872  }
   873  
   874  type status int
   875  
   876  const (
   877  	statusNotOpen status = iota
   878  	statusOpen
   879  	statusClosed
   880  )
   881  
   882  type healthStatus int
   883  
   884  const (
   885  	healthStatusCheckFailed healthStatus = iota
   886  	healthStatusOK
   887  )
   888  
   889  type op interface {
   890  	// Size returns the effective size of inner operations.
   891  	Size() int
   892  
   893  	// CompletionFn gets the completion function for the operation.
   894  	CompletionFn() completionFn
   895  }
   896  
   897  type (
   898  	enqueueDelayedFn     func(peersMetadata []receivedBlockMetadata)
   899  	enqueueDelayedDoneFn func()
   900  )
   901  
   902  type enqueueChannel interface {
   903  	enqueue(peersMetadata []receivedBlockMetadata) error
   904  	enqueueDelayed(numToEnqueue int) (enqueueDelayedFn, enqueueDelayedDoneFn, error)
   905  	// read is always safe to call since you can safely range
   906  	// over a closed channel, and/or do a checked read in case
   907  	// it is closed (unlike when publishing to a channel).
   908  	read() <-chan []receivedBlockMetadata
   909  	trackPending(amount int)
   910  	trackProcessed(amount int)
   911  	unprocessedLen() int
   912  	closeOnAllProcessed()
   913  }