baseservice

Documentation

Overview

Package baseservice contains structs and initialization functions for "service-like" objects that provide commonly needed facilities so that they don't have to be redefined on every struct. The word "service" is used quite loosely here in that it may be applied to many long-lived object that aren't strictly services (e.g. adapters).

Index

• Constants
• func Init[TService withBaseService](archetype *Archetype, service TService) TService
• type Archetype
• type BaseService
  • func (s *BaseService) CancellableSleep(ctx context.Context, sleepDuration time.Duration)
  • func (s *BaseService) CancellableSleepC(ctx context.Context, sleepDuration time.Duration) <-chan struct{}
  • func (s *BaseService) CancellableSleepRandomBetween(ctx context.Context, sleepDurationMin, sleepDurationMax time.Duration)
  • func (s *BaseService) CancellableSleepRandomBetweenC(ctx context.Context, sleepDurationMin, sleepDurationMax time.Duration) <-chan struct{}
  • func (s *BaseService) ExponentialBackoff(attempt, maxAttemptsBeforeReset int) time.Duration
  • func (s *BaseService) GetBaseService() *BaseService

Constants

const MaxAttemptsBeforeResetDefault = 10

MaxAttemptsBeforeResetDefault is the number of attempts during exponential backoff after which attempts is reset so that sleep durations aren't flung into a ridiculously distant future. This constant is typically injected into the CancellableSleepExponentialBackoff function. It could technically take another value instead, but shouldn't unless there's a good reason to do so.

Functions

func Init

func Init[TService withBaseService](archetype *Archetype, service TService) TService

Init initializes a base service from an archetype. It returns the same service that was passed into it for convenience.

Types

type Archetype

type Archetype struct {
	// Logger is a structured logger.
	Logger *slog.Logger

	// Rand is a random source safe for concurrent access and seeded with a
	// cryptographically random seed to ensure good distribution between nodes
	// and services. The random source itself is _not_ cryptographically secure,
	// and therefore should not be used anywhere security-related. This is a
	// deliberate choice because Go's non-crypto rand source is about twenty
	// times faster, and so far none of our uses of random require cryptographic
	// secure randomness.
	Rand *rand.Rand

	// TimeNowUTC returns the current time as UTC. Normally it's implemented as
	// a call to `time.Now().UTC()`, but may be overridden in tests for time
	// injection. Services should try to use this function instead of the
	// vanilla ones from the `time` package for testing purposes.
	TimeNowUTC func() time.Time
}

Archetype contains the set of base service properties that are immutable, or otherwise safe for services to copy from another service. The struct is also embedded in BaseService, so these properties are available on services directly.

type BaseService

type BaseService struct {
	Archetype

	// Name is a name of the service. It should generally be used to prefix all
	// log lines the service emits.
	Name string
}

BaseService is a struct that's meant to be embedded on "service-like" objects (e.g. client, producer, queue maintainer) and which provides a number of convenient properties that are widely needed so that they don't have to be defined on every individual service and can easily be copied from each other.

An initial Archetype should be defined near the program's entrypoint (currently in Client), and then each service should invoke Init along with the archetype to initialize its own base service. This is often done in the service's constructor, but if it doesn't have one, it's the job of the caller which instantiates it to invoke Init.

func (*BaseService) CancellableSleep

func (s *BaseService) CancellableSleep(ctx context.Context, sleepDuration time.Duration)

CancellableSleep sleeps for the given duration, but returns early if context has been cancelled.

func (*BaseService) CancellableSleepC

func (s *BaseService) CancellableSleepC(ctx context.Context, sleepDuration time.Duration) <-chan struct{}

CancellableSleep sleeps for the given duration, but returns early if context has been cancelled.

This variant returns a channel that should be waited on and which will be closed when either the sleep or context is done.

func (*BaseService) CancellableSleepRandomBetween

func (s *BaseService) CancellableSleepRandomBetween(ctx context.Context, sleepDurationMin, sleepDurationMax time.Duration)

CancellableSleepRandomBetween sleeps for a random duration between the given bounds (max bound is exclusive), but returns early if context has been cancelled.

func (*BaseService) CancellableSleepRandomBetweenC

func (s *BaseService) CancellableSleepRandomBetweenC(ctx context.Context, sleepDurationMin, sleepDurationMax time.Duration) <-chan struct{}

CancellableSleepRandomBetween sleeps for a random duration between the given bounds (max bound is exclusive), but returns early if context has been cancelled.

This variant returns a channel that should be waited on and which will be closed when either the sleep or context is done.

func (*BaseService) ExponentialBackoff

func (s *BaseService) ExponentialBackoff(attempt, maxAttemptsBeforeReset int) time.Duration

ExponentialBackoff returns a duration for a reasonable exponential backoff interval for a service based on the given attempt number, which can then be fed into CancellableSleep to perform the sleep. Uses a 2**N second algorithm, +/- 10% random jitter. Sleep is cancelled if the given context is cancelled.

Attempt should start at one for the first backoff/failure.

func (*BaseService) GetBaseService

func (s *BaseService) GetBaseService() *BaseService