shared

Documentation

Overview

Package shared holds some types that are used between multiple global-ratelimiter packages, and need to be broken out to prevent import cycles.

Index

• func AssertNoSanityCheckFailures(t testingt, entries []observer.LoggedEntry)
• func SanityCheckFloat[T ~float64](lower, actual, upper T, what string) (msg string)
• func SanityLogFloat[T ~float64](lower, actual, upper T, what string, logger log.Logger) T
• type GlobalKey
• type KeyMapper
  • func PrefixKey(prefix string) KeyMapper
• type LocalKey

Functions

func AssertNoSanityCheckFailures

func AssertNoSanityCheckFailures(t testingt, entries []observer.LoggedEntry)

func SanityCheckFloat

func SanityCheckFloat[T ~float64](lower, actual, upper T, what string) (msg string)

SanityCheckFloat checks bounds and numerically-valid-ness, and returns an error string if any check fails.

This is the "lower level" of SanityLogFloat, when invalid means behavior needs to change, and invalid data is an unavoidable possibility.

If invalid data should *always* be avoided by earlier code, use SanityLogFloat instead to do a paranoid log of violations without affecting behavior.

func SanityLogFloat

func SanityLogFloat[T ~float64](lower, actual, upper T, what string, logger log.Logger) T

SanityLogFloat ensures values are within sane bounds (inclusive) and not NaN or Inf, and logs an error if these expectations are violated. This should only be used when a value is believed to *always* be valid, not when it needs to be clamped to a reasonable range.

This largely exists because math.Max and similar retain NaN/Inf instead of treating them as error states, and that (and other issues) caused problems. There are a lot of potential gotchas with floats, and without good fuzzing you're kinda unlikely to trigger them all, so this helps us be as paranoid as we like with small enough cost to ignore (while also documenting expectations).

The "actual" value is returned no matter what, to make this easier to use in a logic chain without temp vars.

Violations are intentionally NOT fatal, nor is a "reasonable" value returned, as they are not expected to occur and code paths involved are not built with that assumption. Consider it "undefined behavior", this log exists only to help troubleshoot the cause later if it happens.

---

In tests, always assert that this is not ever triggered, by using the following:

logger, obs := logtest.NewObserved(t)
t.Cleanup(func() { AssertNoSanityCheckFailures(t, obs) })
// your test

Types

type GlobalKey

type GlobalKey string // GlobalKey represents a "global" / globally unique ratelimit key (i.e. namespaced by collection)

type KeyMapper

type KeyMapper interface {
	LocalToGlobal(key LocalKey) GlobalKey
	// GlobalToLocal does the reverse of LocalToGlobal.
	//
	// An error will be returned if the global key does not seem to have
	// come from this mapper.
	GlobalToLocal(key GlobalKey) (LocalKey, error)
}

KeyMapper is used to ensure that all keys that get communicated to aggregators are uniquely identifiable, when multiple collections are used.

A unique prefix / pattern per collection should be sufficient.

func PrefixKey

func PrefixKey(prefix string) KeyMapper

PrefixKey builds a KeyMapper that simply adds (or removes) a fixed prefix to all keys. If the global key does not have this prefix, an error will be returned when mapping to local.

type LocalKey

type LocalKey string // LocalKey represents a "local" / unique to this collection ratelimit key