It seems to me that the rate limiter should be an interface instead, so that a client that wants to use a different implementation could supply their own.

Specifically, we could use the golang.org/x/time/rate implementation.

The waiting should be done by the rate limiter implementation itself, i.e. Allow should be blocking, so that the wait does not need to be in increments of 50 milliseconds, but could wait e.g. for external events as well.

The rate limiter should take the context into account, so that when the context is canceled or a deadline is reached, the limiter will stop waiting.

The behavior in this pull request could be implemented outside of gocql by wrapping of Session.Query. That said a proper implementation should probably be rate limiting the query attempts (queryExecutor.attemptQuery) instead of the high-level Session.Query call. The Session.Query also does not handle batches and attemptQuery is used for batches too.

It seems that there could be an interceptor-like interface that would allow to wrap attemptQuery calls. This could be used to supply a rate limiter implementation as well as replace the Query/Batch observers in version 2 of the gocql package.

Something the following draft, but the interface would need some refinement probably:

type QueryAttemptInterceptor interface {
    // AttemptQuery executes the query on the given connection.
    // The attempt function does the actual work, the AttempQuery implementation is free to execute code
    // before/after the call to the attempt function or skip the call altogether.
    // If error is nil, the returned *Iter must be non-nil.
    AttemptQuery(ctx context.Context, query ExecutableQuery, conn *Conn, attempt func(ctx context, query ExecutableQuery, conn *Conn) *Iter) (*Iter, error))
}

@testisnullus @joao-r-reis what do you think, should we open a separate issue for the interceptor-like interface?

I agree that making this an interceptor-like interface would open up more use cases beyond rate limiting so it seems like a good idea to me 👍

I think it is a great suggestion, we can create an issue for it