randomness

README

randomness

randomness provides a secure random integer generator, optionally retryable, and collision-free.

Install

$ go get github.com/saucelabs/randomness@vX.Y.Z

Usage

See example_test.go, and randomness_test.go file.

Documentation

Run $ make doc or check out online.

Development

Check out CONTRIBUTION.

Release

1. Update CHANGELOG accordingly.
2. Once changes from MR are merged.
3. Tag and release.

Roadmap

Check out CHANGELOG.

Documentation

Overview

Package Randomness provides a secure random integer generator, optionally retryable, and collision-free.

Examples:

See `example_test.go` or the Example section of the GoDoc documention.

Index

• Variables
• type Randomness
  • func New(min, max, maxRetry int, collisionFree bool) (*Randomness, error)
  • func (r *Randomness) Generate() (int64, error)
  • func (r *Randomness) MustGenerate() int64

Examples

• New (Generate)
• New (Generate_collisionFree)
• New (Generate_collisionFreeError)
• New (Generate_collisionFreeMaxRetry)
• New (MustGenerate)

Variables

var (
	ErrFailedToGenerateRangeSaturated  = customerror.NewFailedToError("to generate, range saturated", "", nil)
	ErrFailedToGenerateReachedMaxRetry = customerror.NewFailedToError("to generate, reached max retry", "", nil)
	ErrInvalidMinBiggerThanMax         = customerror.NewInvalidError("param. Min can't be bigger than max", "", nil)
	ErrInvalidMinOrMaxLessThanZero     = customerror.NewInvalidError("params. `min`/`max` need to be bigger than zero", "", nil)
)

Types

type Randomness

type Randomness struct {
	CollisionFree bool

	Max int
	Min int
	// contains filtered or unexported fields
}

func New

func New(min, max, maxRetry int, collisionFree bool) (*Randomness, error)

Example (Generate)

Demonstrates how to generate a random number (integer).

r, err := New(0, 5, 0, false)
if err != nil {
	log.Fatalln(err)
}

n, err := r.Generate()
if err != nil {
	log.Fatalln(err)
}

fmt.Println(n < 0 && n > 5)

Output:

false

Example (Generate_collisionFree)

Demonstrates how to generate a random number (integer) - with the collision-free option, and no collision.

errMsgs := []error{}

r, err := New(1, 10, 0, true)
if err != nil {
	log.Fatalln(err)
}

for i := 0; i < 3; i++ {
	_, err := r.Generate()
	if err != nil {
		errMsgs = append(errMsgs, err)
	}
}

saturated := false

for _, err := range errMsgs {
	if errors.Is(err, ErrFailedToGenerateRangeSaturated) {
		saturated = true
	}
}

fmt.Println(saturated)

Output:

false

Example (Generate_collisionFreeError)

Demonstrates how to generate a random number (integer) - with the collision-free option, but causing collision.

errMsgs := []error{}

r, err := New(1, 3, 0, true)
if err != nil {
	log.Fatalln(err)
}

for i := 0; i < 10; i++ {
	_, err := r.Generate()
	if err != nil {
		errMsgs = append(errMsgs, err)
	}
}

saturated := false

for _, err := range errMsgs {
	if errors.Is(err, ErrFailedToGenerateRangeSaturated) {
		saturated = true
	}
}

fmt.Println(saturated)

Output:

true

Example (Generate_collisionFreeMaxRetry)

Demonstrates how to generate a random number (integer) - with the collision-free option, no collision, and with maxRetry.

errMsgs := []error{}

r, err := New(1, 10, 100, true)
if err != nil {
	log.Fatalln(err)
}

for i := 0; i < 10; i++ {
	_, err := r.Generate()
	if err != nil {
		errMsgs = append(errMsgs, err)
	}
}

saturated := false
reachedMaxRetries := false

for _, err := range errMsgs {
	if errors.Is(err, ErrFailedToGenerateRangeSaturated) {
		saturated = true
	}

	if errors.Is(err, ErrFailedToGenerateReachedMaxRetry) {
		reachedMaxRetries = true
	}
}

fmt.Println(saturated)
fmt.Println(reachedMaxRetries)

Output:

false
false

Example (MustGenerate)

Demonstrates how to generate a random number (integer).

r, err := New(0, 5, 0, false)
if err != nil {
	log.Fatalln(err)
}

n := r.MustGenerate()

fmt.Println(n < 0 && n > 5)

Output:

false

func (*Randomness) Generate

func (r *Randomness) Generate() (int64, error)

func (*Randomness) MustGenerate

func (r *Randomness) MustGenerate() int64

MustGenerate is like `RandomPortGenerator`, but will panic in case of any error.