tstest, tstime: mockable timers and tickers

This change introduces tstime.Clock which is the start of a mockable
interface for use with testing other upcoming code changes.

Fixes #8463

Change-Id: I59eabc797828809194575736615535d918242ec4
Signed-off-by: Adrian Dewhurst <adrian@tailscale.com>

tstime/tstime.go

@@ -59,3 +59,79 @@ func Sleep(ctx context.Context, d time.Duration) bool {
 		return true
 	}
 }
+
+// Clock offers a subset of the functionality from the std/time package.
+// Normally, applications will use the StdClock implementation that calls the
+// appropriate std/time exported funcs. The advantage of using Clock is that
+// tests can substitute a different implementation, allowing the test to control
+// time precisely, something required for certain types of tests to be possible
+// at all, speeds up execution by not needing to sleep, and can dramatically
+// reduce the risk of flakes due to tests executing too slowly or quickly.
+type Clock interface {
+	// Now returns the current time, as in time.Now.
+	Now() time.Time
+	// NewTimer returns a timer whose notion of the current time is controlled
+	// by this Clock. It follows the semantics of time.NewTimer as closely as
+	// possible but is adapted to return an interface, so the channel needs to
+	// be returned as well.
+	NewTimer(d time.Duration) (TimerController, <-chan time.Time)
+	// NewTicker returns a ticker whose notion of the current time is controlled
+	// by this Clock. It follows the semantics of time.NewTicker as closely as
+	// possible but is adapted to return an interface, so the channel needs to
+	// be returned as well.
+	NewTicker(d time.Duration) (TickerController, <-chan time.Time)
+	// AfterFunc returns a ticker whose notion of the current time is controlled
+	// by this Clock. When the ticker expires, it will call the provided func.
+	// It follows the semantics of time.AfterFunc.
+	AfterFunc(d time.Duration, f func()) TimerController
+}
+
+// TickerController offers the receivers of a time.Ticker to ensure
+// compatibility with standard timers, but allows for the option of substituting
+// a standard timer with something else for testing purposes.
+type TickerController interface {
+	// Reset follows the same semantics as with time.Ticker.Reset.
+	Reset(d time.Duration)
+	// Stop follows the same semantics as with time.Ticker.Stop.
+	Stop()
+}
+
+// TimerController offers the receivers of a time.Timer to ensure
+// compatibility with standard timers, but allows for the option of substituting
+// a standard timer with something else for testing purposes.
+type TimerController interface {
+	// Reset follows the same semantics as with time.Timer.Reset.
+	Reset(d time.Duration) bool
+	// Stop follows the same semantics as with time.Timer.Stop.
+	Stop() bool
+}
+
+// StdClock is a simple implementation of Clock using the relevant funcs in the
+// std/time package.
+type StdClock struct{}
+
+// Now calls time.Now.
+func (StdClock) Now() time.Time {
+	return time.Now()
+}
+
+// NewTimer calls time.NewTimer. As an interface does not allow for struct
+// members and other packages cannot add receivers to another package, the
+// channel is also returned because it would be otherwise inaccessible.
+func (StdClock) NewTimer(d time.Duration) (TimerController, <-chan time.Time) {
+	t := time.NewTimer(d)
+	return t, t.C
+}
+
+// NewTicker calls time.NewTicker. As an interface does not allow for struct
+// members and other packages cannot add receivers to another package, the
+// channel is also returned because it would be otherwise inaccessible.
+func (StdClock) NewTicker(d time.Duration) (TickerController, <-chan time.Time) {
+	t := time.NewTicker(d)
+	return t, t.C
+}
+
+// AfterFunc calls time.AfterFunc.
+func (StdClock) AfterFunc(d time.Duration, f func()) TimerController {
+	return time.AfterFunc(d, f)
+}