You are viewing a plain text version of this content. The canonical link for it is here.
Posted to pr@cassandra.apache.org by "abenn135 (via GitHub)" <gi...@apache.org> on 2026/09/14 16:26:53 UTC

Re: [PR] CASSGO-39 Add exec attempt interceptor (round 3) [cassandra-gocql-driver]

abenn135 commented on code in PR #1943:
URL: https://github.com/apache/cassandra-gocql-driver/pull/1943#discussion_r4006874970


##########
query_executor.go:
##########
@@ -69,16 +71,151 @@ type internalRequest interface {
 }
 
 type queryExecutor struct {
-	pool   *policyConnPool
-	policy HostSelectionPolicy
+	pool        *policyConnPool
+	policy      HostSelectionPolicy
+	interceptor ExecAttemptInterceptor
 }
 
-func (q *queryExecutor) attemptQuery(ctx context.Context, qry internalRequest, conn *Conn) *Iter {
+type OpType int
+
+const (
+	OpQuery OpType = iota
+	OpBatch
+)
+
+type ImmutableQuery interface {

Review Comment:
   OK, removed entirely and went back to Query/Batch, with an admonition that they should be treated immutable.



##########
query_executor.go:
##########
@@ -69,16 +71,151 @@ type internalRequest interface {
 }
 
 type queryExecutor struct {
-	pool   *policyConnPool
-	policy HostSelectionPolicy
+	pool        *policyConnPool
+	policy      HostSelectionPolicy
+	interceptor ExecAttemptInterceptor
 }
 
-func (q *queryExecutor) attemptQuery(ctx context.Context, qry internalRequest, conn *Conn) *Iter {
+type OpType int
+
+const (
+	OpQuery OpType = iota
+	OpBatch
+)
+
+type ImmutableQuery interface {
+	Statement() string
+	Values() []interface{}
+}
+
+type immutableQuery struct {
+	query *Query
+}
+
+func (q *immutableQuery) Statement() string {
+	return q.query.stmt
+}
+
+func (q *immutableQuery) Values() []interface{} {
+	return q.query.values
+}
+
+type ImmutableBatch interface {
+	Type() BatchType
+	Entries() []BatchEntry
+	Cons() Consistency
+}
+
+type immutableBatch struct {
+	batch *Batch
+}
+
+func (b *immutableBatch) Type() BatchType {
+	return b.batch.Type
+}
+
+func (b *immutableBatch) Entries() []BatchEntry {
+	return b.batch.Entries
+}
+
+func (b *immutableBatch) Cons() Consistency {
+	return b.batch.Cons
+}
+
+type QueryAttempt struct {
+	// The op type, whether query or batch.
+	Type OpType
+	// Only one of Query or Batch will be set, depending on the op type.
+	Query ImmutableQuery
+	Batch ImmutableBatch
+	// The host that will receive the query.
+	Host *HostInfo
+	// The local address of the connection used to execute the query.
+	LocalAddr net.Addr
+	// The remote address of the connection used to execute the query.
+	RemoteAddr net.Addr
+	// The number of this query attempt. 0 for the initial attempt, 1 for the first retry, etc. Note that there may be multiple serial Attempts to different hosts within a single execution, whether main execution or speculative.
+	Attempts int
+	// The index of the speculative execution attempt this attempt is associated with, starting with index 1. -1 indicates this is the "main" execution.
+	SpeculativeExecutionCount int
+}
+
+// QueryAttemptHandler is a function that attempts query execution. The interceptor must call this once if it does not return an error.
+type QueryAttemptHandler = func(context.Context) (*Iter, error)

Review Comment:
   Done.



##########
query_executor.go:
##########
@@ -69,16 +71,151 @@ type internalRequest interface {
 }
 
 type queryExecutor struct {
-	pool   *policyConnPool
-	policy HostSelectionPolicy
+	pool        *policyConnPool
+	policy      HostSelectionPolicy
+	interceptor ExecAttemptInterceptor
 }
 
-func (q *queryExecutor) attemptQuery(ctx context.Context, qry internalRequest, conn *Conn) *Iter {
+type OpType int
+
+const (
+	OpQuery OpType = iota
+	OpBatch
+)
+
+type ImmutableQuery interface {
+	Statement() string
+	Values() []interface{}
+}
+
+type immutableQuery struct {
+	query *Query
+}
+
+func (q *immutableQuery) Statement() string {
+	return q.query.stmt
+}
+
+func (q *immutableQuery) Values() []interface{} {
+	return q.query.values
+}
+
+type ImmutableBatch interface {
+	Type() BatchType
+	Entries() []BatchEntry
+	Cons() Consistency
+}
+
+type immutableBatch struct {
+	batch *Batch
+}
+
+func (b *immutableBatch) Type() BatchType {
+	return b.batch.Type
+}
+
+func (b *immutableBatch) Entries() []BatchEntry {
+	return b.batch.Entries
+}
+
+func (b *immutableBatch) Cons() Consistency {
+	return b.batch.Cons
+}
+
+type QueryAttempt struct {

Review Comment:
   Done.



##########
query_executor.go:
##########
@@ -69,16 +71,151 @@ type internalRequest interface {
 }
 
 type queryExecutor struct {
-	pool   *policyConnPool
-	policy HostSelectionPolicy
+	pool        *policyConnPool
+	policy      HostSelectionPolicy
+	interceptor ExecAttemptInterceptor
 }
 
-func (q *queryExecutor) attemptQuery(ctx context.Context, qry internalRequest, conn *Conn) *Iter {
+type OpType int
+
+const (
+	OpQuery OpType = iota
+	OpBatch
+)
+
+type ImmutableQuery interface {
+	Statement() string
+	Values() []interface{}
+}
+
+type immutableQuery struct {
+	query *Query
+}
+
+func (q *immutableQuery) Statement() string {
+	return q.query.stmt
+}
+
+func (q *immutableQuery) Values() []interface{} {
+	return q.query.values
+}
+
+type ImmutableBatch interface {
+	Type() BatchType
+	Entries() []BatchEntry
+	Cons() Consistency
+}
+
+type immutableBatch struct {
+	batch *Batch
+}
+
+func (b *immutableBatch) Type() BatchType {
+	return b.batch.Type
+}
+
+func (b *immutableBatch) Entries() []BatchEntry {
+	return b.batch.Entries
+}
+
+func (b *immutableBatch) Cons() Consistency {
+	return b.batch.Cons
+}
+
+type QueryAttempt struct {
+	// The op type, whether query or batch.
+	Type OpType
+	// Only one of Query or Batch will be set, depending on the op type.
+	Query ImmutableQuery
+	Batch ImmutableBatch
+	// The host that will receive the query.
+	Host *HostInfo
+	// The local address of the connection used to execute the query.
+	LocalAddr net.Addr
+	// The remote address of the connection used to execute the query.
+	RemoteAddr net.Addr
+	// The number of this query attempt. 0 for the initial attempt, 1 for the first retry, etc. Note that there may be multiple serial Attempts to different hosts within a single execution, whether main execution or speculative.
+	Attempts int
+	// The index of the speculative execution attempt this attempt is associated with, starting with index 1. -1 indicates this is the "main" execution.
+	SpeculativeExecutionCount int
+}
+
+// QueryAttemptHandler is a function that attempts query execution. The interceptor must call this once if it does not return an error.
+type QueryAttemptHandler = func(context.Context) (*Iter, error)
+
+// ExecAttemptInterceptor is the interface implemented by interceptors / middleware.
+//
+// Interceptors are well-suited to logic that is not specific to a single query or batch, such as flow control.
+type ExecAttemptInterceptor interface {
+	// Intercept is invoked once immediately before a query or batch execution attempt, including retry attempts and
+	// speculative execution attempts.
+	//
+	// The interceptor is responsible for calling the `handler` function and returning the handler result. If the
+	// interceptor wants to bypass the handler and skip query execution, it should return an error. Failure to
+	// return either the handler result or an error will panic.
+	//
+	// Note that there is no affordance to mutate the query or batch at this stage -- the handler already encapsulates the original query/batch and cannot be modified.
+	Intercept(ctx context.Context, attempt QueryAttempt, handler QueryAttemptHandler) (*Iter, error)

Review Comment:
   That seems sensible to me. For our purposes we only need pre-attempt; if an attempt fails or is retried we don't need to know post-attempt; and if it succeeds we can use the Observer pattern, though I recognize there might be an effort to merge the two.



##########
session.go:
##########
@@ -968,26 +969,49 @@ type hostMetrics struct {
 	TotalLatency int64
 }
 
+// Query attempts could be started and finished out of order when using speculative execution. Therefore,
+// we issue attempt indexes at query start time (so that Interceptors can use them) then record those attempts
+// at completion time (so that metrics can correctly express average latency).
 type queryMetrics struct {
-	totalAttempts int64
-	totalLatency  int64
+	l                 sync.RWMutex
+	attemptsStarted   int
+	attemptsCompleted int
+	totalLatency      int64
 }
 
-func (qm *queryMetrics) attempt(addLatency time.Duration) int {
-	atomic.AddInt64(&qm.totalLatency, addLatency.Nanoseconds())
-	return int(atomic.AddInt64(&qm.totalAttempts, 1) - 1)
+func (qm *queryMetrics) getNextAttempt() int {
+	qm.l.Lock()
+	defer qm.l.Unlock()
+	attempt := qm.attemptsStarted
+	qm.attemptsStarted++
+	return attempt
 }
 
+func (qm *queryMetrics) recordAttempt(attempt int, addLatency time.Duration, s *Session) {
+	qm.l.Lock()
+	defer qm.l.Unlock()
+	qm.totalLatency += addLatency.Nanoseconds()
+	qm.attemptsCompleted++
+	if attempt > qm.attemptsCompleted && s != nil {
+		s.logger.Debug("attempt number is greater than total attempts completed, this should not happen", NewLogFieldInt("attempt", attempt), NewLogFieldInt("attemptsCompleted", qm.attemptsCompleted))

Review Comment:
   Removed.



##########
query_executor.go:
##########
@@ -69,16 +71,151 @@ type internalRequest interface {
 }
 
 type queryExecutor struct {
-	pool   *policyConnPool
-	policy HostSelectionPolicy
+	pool        *policyConnPool
+	policy      HostSelectionPolicy
+	interceptor ExecAttemptInterceptor
 }
 
-func (q *queryExecutor) attemptQuery(ctx context.Context, qry internalRequest, conn *Conn) *Iter {
+type OpType int
+
+const (
+	OpQuery OpType = iota
+	OpBatch

Review Comment:
   Done.



##########
query_executor.go:
##########
@@ -69,16 +71,151 @@ type internalRequest interface {
 }
 
 type queryExecutor struct {
-	pool   *policyConnPool
-	policy HostSelectionPolicy
+	pool        *policyConnPool
+	policy      HostSelectionPolicy
+	interceptor ExecAttemptInterceptor
 }
 
-func (q *queryExecutor) attemptQuery(ctx context.Context, qry internalRequest, conn *Conn) *Iter {
+type OpType int
+
+const (
+	OpQuery OpType = iota
+	OpBatch
+)
+
+type ImmutableQuery interface {
+	Statement() string
+	Values() []interface{}
+}
+
+type immutableQuery struct {
+	query *Query
+}
+
+func (q *immutableQuery) Statement() string {
+	return q.query.stmt
+}
+
+func (q *immutableQuery) Values() []interface{} {
+	return q.query.values
+}
+
+type ImmutableBatch interface {
+	Type() BatchType
+	Entries() []BatchEntry
+	Cons() Consistency
+}
+
+type immutableBatch struct {
+	batch *Batch
+}
+
+func (b *immutableBatch) Type() BatchType {
+	return b.batch.Type
+}
+
+func (b *immutableBatch) Entries() []BatchEntry {
+	return b.batch.Entries
+}
+
+func (b *immutableBatch) Cons() Consistency {
+	return b.batch.Cons
+}
+
+type QueryAttempt struct {
+	// The op type, whether query or batch.
+	Type OpType
+	// Only one of Query or Batch will be set, depending on the op type.
+	Query ImmutableQuery
+	Batch ImmutableBatch
+	// The host that will receive the query.
+	Host *HostInfo
+	// The local address of the connection used to execute the query.
+	LocalAddr net.Addr
+	// The remote address of the connection used to execute the query.
+	RemoteAddr net.Addr
+	// The number of this query attempt. 0 for the initial attempt, 1 for the first retry, etc. Note that there may be multiple serial Attempts to different hosts within a single execution, whether main execution or speculative.
+	Attempts int
+	// The index of the speculative execution attempt this attempt is associated with, starting with index 1. -1 indicates this is the "main" execution.
+	SpeculativeExecutionCount int
+}
+
+// QueryAttemptHandler is a function that attempts query execution. The interceptor must call this once if it does not return an error.
+type QueryAttemptHandler = func(context.Context) (*Iter, error)
+
+// ExecAttemptInterceptor is the interface implemented by interceptors / middleware.
+//
+// Interceptors are well-suited to logic that is not specific to a single query or batch, such as flow control.
+type ExecAttemptInterceptor interface {
+	// Intercept is invoked once immediately before a query or batch execution attempt, including retry attempts and
+	// speculative execution attempts.
+	//
+	// The interceptor is responsible for calling the `handler` function and returning the handler result. If the
+	// interceptor wants to bypass the handler and skip query execution, it should return an error. Failure to
+	// return either the handler result or an error will panic.
+	//
+	// Note that there is no affordance to mutate the query or batch at this stage -- the handler already encapsulates the original query/batch and cannot be modified.
+	Intercept(ctx context.Context, attempt QueryAttempt, handler QueryAttemptHandler) (*Iter, error)
+}
+
+// Use an ExecAttemptInterceptorChain to apply multiple Interceptors at Intercept time.
+type ExecAttemptInterceptorChain struct {
+	Interceptors []ExecAttemptInterceptor
+}
+
+func (c ExecAttemptInterceptorChain) Intercept(
+	ctx context.Context,
+	attempt QueryAttempt,
+	handler QueryAttemptHandler,
+) (*Iter, error) {
+	return c.Interceptors[0].Intercept(ctx, attempt, c.getNextHandler(0, attempt, handler))

Review Comment:
   Now that Intercept isn't expected to invoke the handler, this shouldn't panic. A for loop over zero items simply skips.



##########
query_executor.go:
##########
@@ -69,16 +71,151 @@ type internalRequest interface {
 }
 
 type queryExecutor struct {
-	pool   *policyConnPool
-	policy HostSelectionPolicy
+	pool        *policyConnPool
+	policy      HostSelectionPolicy
+	interceptor ExecAttemptInterceptor
 }
 
-func (q *queryExecutor) attemptQuery(ctx context.Context, qry internalRequest, conn *Conn) *Iter {
+type OpType int
+
+const (
+	OpQuery OpType = iota
+	OpBatch
+)
+
+type ImmutableQuery interface {
+	Statement() string
+	Values() []interface{}
+}
+
+type immutableQuery struct {
+	query *Query
+}
+
+func (q *immutableQuery) Statement() string {
+	return q.query.stmt
+}
+
+func (q *immutableQuery) Values() []interface{} {
+	return q.query.values
+}
+
+type ImmutableBatch interface {
+	Type() BatchType
+	Entries() []BatchEntry
+	Cons() Consistency
+}
+
+type immutableBatch struct {
+	batch *Batch
+}
+
+func (b *immutableBatch) Type() BatchType {
+	return b.batch.Type
+}
+
+func (b *immutableBatch) Entries() []BatchEntry {
+	return b.batch.Entries
+}
+
+func (b *immutableBatch) Cons() Consistency {
+	return b.batch.Cons
+}
+
+type QueryAttempt struct {
+	// The op type, whether query or batch.
+	Type OpType
+	// Only one of Query or Batch will be set, depending on the op type.
+	Query ImmutableQuery
+	Batch ImmutableBatch
+	// The host that will receive the query.
+	Host *HostInfo
+	// The local address of the connection used to execute the query.
+	LocalAddr net.Addr
+	// The remote address of the connection used to execute the query.
+	RemoteAddr net.Addr
+	// The number of this query attempt. 0 for the initial attempt, 1 for the first retry, etc. Note that there may be multiple serial Attempts to different hosts within a single execution, whether main execution or speculative.
+	Attempts int
+	// The index of the speculative execution attempt this attempt is associated with, starting with index 1. -1 indicates this is the "main" execution.
+	SpeculativeExecutionCount int
+}
+
+// QueryAttemptHandler is a function that attempts query execution. The interceptor must call this once if it does not return an error.
+type QueryAttemptHandler = func(context.Context) (*Iter, error)
+
+// ExecAttemptInterceptor is the interface implemented by interceptors / middleware.
+//
+// Interceptors are well-suited to logic that is not specific to a single query or batch, such as flow control.
+type ExecAttemptInterceptor interface {
+	// Intercept is invoked once immediately before a query or batch execution attempt, including retry attempts and
+	// speculative execution attempts.
+	//
+	// The interceptor is responsible for calling the `handler` function and returning the handler result. If the
+	// interceptor wants to bypass the handler and skip query execution, it should return an error. Failure to
+	// return either the handler result or an error will panic.
+	//
+	// Note that there is no affordance to mutate the query or batch at this stage -- the handler already encapsulates the original query/batch and cannot be modified.

Review Comment:
   Removed.



##########
query_executor.go:
##########
@@ -69,16 +71,151 @@ type internalRequest interface {
 }
 
 type queryExecutor struct {
-	pool   *policyConnPool
-	policy HostSelectionPolicy
+	pool        *policyConnPool
+	policy      HostSelectionPolicy
+	interceptor ExecAttemptInterceptor
 }
 
-func (q *queryExecutor) attemptQuery(ctx context.Context, qry internalRequest, conn *Conn) *Iter {
+type OpType int
+
+const (
+	OpQuery OpType = iota
+	OpBatch
+)
+
+type ImmutableQuery interface {
+	Statement() string
+	Values() []interface{}
+}
+
+type immutableQuery struct {
+	query *Query
+}
+
+func (q *immutableQuery) Statement() string {
+	return q.query.stmt
+}
+
+func (q *immutableQuery) Values() []interface{} {
+	return q.query.values
+}
+
+type ImmutableBatch interface {
+	Type() BatchType
+	Entries() []BatchEntry
+	Cons() Consistency
+}
+
+type immutableBatch struct {
+	batch *Batch
+}
+
+func (b *immutableBatch) Type() BatchType {
+	return b.batch.Type
+}
+
+func (b *immutableBatch) Entries() []BatchEntry {
+	return b.batch.Entries
+}
+
+func (b *immutableBatch) Cons() Consistency {
+	return b.batch.Cons
+}
+
+type QueryAttempt struct {
+	// The op type, whether query or batch.
+	Type OpType
+	// Only one of Query or Batch will be set, depending on the op type.
+	Query ImmutableQuery
+	Batch ImmutableBatch
+	// The host that will receive the query.
+	Host *HostInfo
+	// The local address of the connection used to execute the query.
+	LocalAddr net.Addr
+	// The remote address of the connection used to execute the query.
+	RemoteAddr net.Addr
+	// The number of this query attempt. 0 for the initial attempt, 1 for the first retry, etc. Note that there may be multiple serial Attempts to different hosts within a single execution, whether main execution or speculative.
+	Attempts int
+	// The index of the speculative execution attempt this attempt is associated with, starting with index 1. -1 indicates this is the "main" execution.
+	SpeculativeExecutionCount int
+}
+
+// QueryAttemptHandler is a function that attempts query execution. The interceptor must call this once if it does not return an error.
+type QueryAttemptHandler = func(context.Context) (*Iter, error)
+
+// ExecAttemptInterceptor is the interface implemented by interceptors / middleware.
+//
+// Interceptors are well-suited to logic that is not specific to a single query or batch, such as flow control.
+type ExecAttemptInterceptor interface {

Review Comment:
   Went with `RequestInterceptor`, sounds clean, not too confusing I don't think. Could also just do `ExecInterceptor` if you prefer.



##########
query_executor.go:
##########
@@ -69,16 +71,151 @@ type internalRequest interface {
 }
 
 type queryExecutor struct {
-	pool   *policyConnPool
-	policy HostSelectionPolicy
+	pool        *policyConnPool
+	policy      HostSelectionPolicy
+	interceptor ExecAttemptInterceptor
 }
 
-func (q *queryExecutor) attemptQuery(ctx context.Context, qry internalRequest, conn *Conn) *Iter {
+type OpType int
+
+const (
+	OpQuery OpType = iota
+	OpBatch
+)
+
+type ImmutableQuery interface {
+	Statement() string
+	Values() []interface{}
+}
+
+type immutableQuery struct {
+	query *Query
+}
+
+func (q *immutableQuery) Statement() string {
+	return q.query.stmt
+}
+
+func (q *immutableQuery) Values() []interface{} {
+	return q.query.values
+}
+
+type ImmutableBatch interface {
+	Type() BatchType
+	Entries() []BatchEntry
+	Cons() Consistency
+}
+
+type immutableBatch struct {
+	batch *Batch
+}
+
+func (b *immutableBatch) Type() BatchType {
+	return b.batch.Type
+}
+
+func (b *immutableBatch) Entries() []BatchEntry {
+	return b.batch.Entries
+}
+
+func (b *immutableBatch) Cons() Consistency {
+	return b.batch.Cons
+}
+
+type QueryAttempt struct {
+	// The op type, whether query or batch.
+	Type OpType
+	// Only one of Query or Batch will be set, depending on the op type.
+	Query ImmutableQuery
+	Batch ImmutableBatch
+	// The host that will receive the query.
+	Host *HostInfo
+	// The local address of the connection used to execute the query.
+	LocalAddr net.Addr
+	// The remote address of the connection used to execute the query.
+	RemoteAddr net.Addr
+	// The number of this query attempt. 0 for the initial attempt, 1 for the first retry, etc. Note that there may be multiple serial Attempts to different hosts within a single execution, whether main execution or speculative.
+	Attempts int
+	// The index of the speculative execution attempt this attempt is associated with, starting with index 1. -1 indicates this is the "main" execution.
+	SpeculativeExecutionCount int
+}
+
+// QueryAttemptHandler is a function that attempts query execution. The interceptor must call this once if it does not return an error.
+type QueryAttemptHandler = func(context.Context) (*Iter, error)
+
+// ExecAttemptInterceptor is the interface implemented by interceptors / middleware.
+//
+// Interceptors are well-suited to logic that is not specific to a single query or batch, such as flow control.
+type ExecAttemptInterceptor interface {
+	// Intercept is invoked once immediately before a query or batch execution attempt, including retry attempts and
+	// speculative execution attempts.
+	//
+	// The interceptor is responsible for calling the `handler` function and returning the handler result. If the
+	// interceptor wants to bypass the handler and skip query execution, it should return an error. Failure to
+	// return either the handler result or an error will panic.
+	//
+	// Note that there is no affordance to mutate the query or batch at this stage -- the handler already encapsulates the original query/batch and cannot be modified.
+	Intercept(ctx context.Context, attempt QueryAttempt, handler QueryAttemptHandler) (*Iter, error)
+}
+
+// Use an ExecAttemptInterceptorChain to apply multiple Interceptors at Intercept time.
+type ExecAttemptInterceptorChain struct {
+	Interceptors []ExecAttemptInterceptor
+}
+
+func (c ExecAttemptInterceptorChain) Intercept(
+	ctx context.Context,
+	attempt QueryAttempt,
+	handler QueryAttemptHandler,
+) (*Iter, error) {
+	return c.Interceptors[0].Intercept(ctx, attempt, c.getNextHandler(0, attempt, handler))
+}
+
+func (c ExecAttemptInterceptorChain) getNextHandler(curr int, attempt QueryAttempt, final QueryAttemptHandler) QueryAttemptHandler {
+	if curr == len(c.Interceptors)-1 {
+		return final
+	}
+
+	return func(ctx context.Context) (*Iter, error) {
+		return c.Interceptors[curr+1].Intercept(ctx, attempt, c.getNextHandler(curr+1, attempt, final))
+	}
+}
+
+func (q *queryExecutor) attemptQuery(ctx context.Context, iRequest internalRequest, conn *Conn, speculativeExecutionCount int) *Iter {
 	start := time.Now()
-	iter := qry.execute(ctx, conn)
-	end := time.Now()
 
-	qry.attempt(q.pool.keyspace, end, start, iter, conn.host)
+	var iter *Iter
+	var err error
+	attempt := iRequest.getNextAttempt()
+	if q.interceptor != nil {
+		iq := QueryAttempt{
+			Host:                      conn.host,
+			LocalAddr:                 conn.r.LocalAddr(),
+			RemoteAddr:                conn.r.RemoteAddr(),
+			Attempts:                  attempt,
+			SpeculativeExecutionCount: speculativeExecutionCount,
+		}
+		if iQuery, ok := iRequest.(*internalQuery); ok {
+			iq.Type = OpQuery
+			iq.Query = &immutableQuery{query: iQuery.originalQuery}
+		}
+		if iBatch, ok := iRequest.(*internalBatch); ok {
+			iq.Type = OpBatch
+			iq.Batch = &immutableBatch{batch: iBatch.originalBatch}
+		}
+		iter, err = q.interceptor.Intercept(ctx, iq, func(cxCtx context.Context) (*Iter, error) {
+			it := iRequest.execute(cxCtx, conn)
+			return it, it.err
+		})
+		if err != nil {
+			iter = &Iter{err: err}

Review Comment:
   Done.



##########
session.go:
##########
@@ -968,26 +969,49 @@ type hostMetrics struct {
 	TotalLatency int64
 }
 
+// Query attempts could be started and finished out of order when using speculative execution. Therefore,
+// we issue attempt indexes at query start time (so that Interceptors can use them) then record those attempts
+// at completion time (so that metrics can correctly express average latency).
 type queryMetrics struct {
-	totalAttempts int64
-	totalLatency  int64
+	l                 sync.RWMutex

Review Comment:
   +1 to what @toptobes said :)



##########
query_executor.go:
##########
@@ -69,16 +71,151 @@ type internalRequest interface {
 }
 
 type queryExecutor struct {
-	pool   *policyConnPool
-	policy HostSelectionPolicy
+	pool        *policyConnPool
+	policy      HostSelectionPolicy
+	interceptor ExecAttemptInterceptor
 }
 
-func (q *queryExecutor) attemptQuery(ctx context.Context, qry internalRequest, conn *Conn) *Iter {
+type OpType int
+
+const (
+	OpQuery OpType = iota
+	OpBatch
+)
+
+type ImmutableQuery interface {
+	Statement() string
+	Values() []interface{}
+}
+
+type immutableQuery struct {
+	query *Query
+}
+
+func (q *immutableQuery) Statement() string {
+	return q.query.stmt
+}
+
+func (q *immutableQuery) Values() []interface{} {
+	return q.query.values
+}
+
+type ImmutableBatch interface {
+	Type() BatchType
+	Entries() []BatchEntry
+	Cons() Consistency
+}
+
+type immutableBatch struct {
+	batch *Batch
+}
+
+func (b *immutableBatch) Type() BatchType {
+	return b.batch.Type
+}
+
+func (b *immutableBatch) Entries() []BatchEntry {
+	return b.batch.Entries
+}
+
+func (b *immutableBatch) Cons() Consistency {
+	return b.batch.Cons
+}
+
+type QueryAttempt struct {
+	// The op type, whether query or batch.
+	Type OpType
+	// Only one of Query or Batch will be set, depending on the op type.
+	Query ImmutableQuery
+	Batch ImmutableBatch
+	// The host that will receive the query.
+	Host *HostInfo
+	// The local address of the connection used to execute the query.
+	LocalAddr net.Addr
+	// The remote address of the connection used to execute the query.
+	RemoteAddr net.Addr
+	// The number of this query attempt. 0 for the initial attempt, 1 for the first retry, etc. Note that there may be multiple serial Attempts to different hosts within a single execution, whether main execution or speculative.
+	Attempts int
+	// The index of the speculative execution attempt this attempt is associated with, starting with index 1. -1 indicates this is the "main" execution.
+	SpeculativeExecutionCount int
+}
+
+// QueryAttemptHandler is a function that attempts query execution. The interceptor must call this once if it does not return an error.
+type QueryAttemptHandler = func(context.Context) (*Iter, error)
+
+// ExecAttemptInterceptor is the interface implemented by interceptors / middleware.
+//
+// Interceptors are well-suited to logic that is not specific to a single query or batch, such as flow control.
+type ExecAttemptInterceptor interface {
+	// Intercept is invoked once immediately before a query or batch execution attempt, including retry attempts and
+	// speculative execution attempts.
+	//
+	// The interceptor is responsible for calling the `handler` function and returning the handler result. If the
+	// interceptor wants to bypass the handler and skip query execution, it should return an error. Failure to
+	// return either the handler result or an error will panic.
+	//
+	// Note that there is no affordance to mutate the query or batch at this stage -- the handler already encapsulates the original query/batch and cannot be modified.
+	Intercept(ctx context.Context, attempt QueryAttempt, handler QueryAttemptHandler) (*Iter, error)
+}
+
+// Use an ExecAttemptInterceptorChain to apply multiple Interceptors at Intercept time.
+type ExecAttemptInterceptorChain struct {

Review Comment:
   I've changed the pattern to a simple for loop given how Intercept works after changing it. Let me know if you still feel like `Mux` is the right name here; I think it's still more of a chain since the output of one interceptor is passed to the input of the next one, so there is an intended order there.



##########
session.go:
##########
@@ -968,26 +969,49 @@ type hostMetrics struct {
 	TotalLatency int64
 }
 
+// Query attempts could be started and finished out of order when using speculative execution. Therefore,
+// we issue attempt indexes at query start time (so that Interceptors can use them) then record those attempts
+// at completion time (so that metrics can correctly express average latency).
 type queryMetrics struct {
-	totalAttempts int64
-	totalLatency  int64
+	l                 sync.RWMutex
+	attemptsStarted   int
+	attemptsCompleted int
+	totalLatency      int64
 }
 
-func (qm *queryMetrics) attempt(addLatency time.Duration) int {
-	atomic.AddInt64(&qm.totalLatency, addLatency.Nanoseconds())
-	return int(atomic.AddInt64(&qm.totalAttempts, 1) - 1)
+func (qm *queryMetrics) getNextAttempt() int {
+	qm.l.Lock()
+	defer qm.l.Unlock()
+	attempt := qm.attemptsStarted
+	qm.attemptsStarted++
+	return attempt
 }
 
+func (qm *queryMetrics) recordAttempt(attempt int, addLatency time.Duration, s *Session) {
+	qm.l.Lock()
+	defer qm.l.Unlock()
+	qm.totalLatency += addLatency.Nanoseconds()
+	qm.attemptsCompleted++
+	if attempt > qm.attemptsCompleted && s != nil {
+		s.logger.Debug("attempt number is greater than total attempts completed, this should not happen", NewLogFieldInt("attempt", attempt), NewLogFieldInt("attemptsCompleted", qm.attemptsCompleted))
+	}
+}
+
+// Returns total number of attempts started.
 func (qm *queryMetrics) attempts() int {
-	return int(atomic.LoadInt64(&qm.totalAttempts))
+	qm.l.RLock()
+	defer qm.l.RUnlock()
+	return qm.attemptsStarted

Review Comment:
   OK, reverted.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: pr-unsubscribe@cassandra.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: pr-unsubscribe@cassandra.apache.org
For additional commands, e-mail: pr-help@cassandra.apache.org