Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions internal/clock/clock.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
// Package clock is where Trader reads the time. Code that needs "now" calls
// Clock, or takes a func() time.Time and is handed Clock, instead of calling
// time.Now itself, so a test can pass a fixed time and, if Trader ever has a clock
// of its own (a simulated one for replay, say), this is the one place to change.
package clock

import "time"

// Clock returns the current time, in UTC with the monotonic reading stripped.
func Clock() time.Time {
return time.Now().UTC().Round(0)
}
19 changes: 19 additions & 0 deletions internal/clock/clock_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
package clock

import (
"testing"
"time"

"github.com/stretchr/testify/assert"
)

func TestClock(t *testing.T) {
before := time.Now()
got := Clock()
after := time.Now()

assert.False(t, got.Before(before.Truncate(0)), "not before the call began")
assert.False(t, got.After(after), "not after the call returned")
assert.Equal(t, time.UTC, got.Location(), "UTC")
assert.Equal(t, got, got.Round(0), "no monotonic reading: comparing it with a stored time compares wall time")
}
35 changes: 35 additions & 0 deletions internal/id/deterministic.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
package id

import (
"math/rand/v2"
"sync"
)

// Deterministic is an EntropySource that draws from a seeded PRNG, for tests and
// replay: the same seed gives the same entropy every time, so with a fixed clock a
// Generator makes the same sequence of IDs every time.
//
// Never use it in production: its entropy is reproducible by construction, which
// is exactly what a production ID must not be.
type Deterministic struct {
mu sync.Mutex
rng *rand.Rand
}

// NewDeterministic returns a Deterministic source seeded with seed1 and seed2, the
// two-value seed math/rand/v2's PCG source takes.
func NewDeterministic(seed1, seed2 uint64) *Deterministic {
return &Deterministic{rng: rand.New(rand.NewPCG(seed1, seed2))}
}

// Entropy implements EntropySource.
func (d *Deterministic) Entropy() ([10]byte, error) {
d.mu.Lock()
defer d.mu.Unlock()

var b [10]byte
for i := range b {
b[i] = byte(d.rng.IntN(256))
}
return b, nil
}
34 changes: 34 additions & 0 deletions internal/id/deterministic_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
package id

import (
"testing"
"time"

"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)

func TestDeterministic_ReproducesTheSequence(t *testing.T) {
run := func() []string {
now := t0
g := NewGenerator(func() time.Time { return now }, NewDeterministic(42, 7))
out := make([]string, 10)
for i := range out {
now = t0.Add(time.Duration(i) * time.Millisecond)
got, err := g.RunID()
require.NoError(t, err)
out[i] = got.String()
}
return out
}
assert.Equal(t, run(), run(), "the same seed and clock give the same IDs")
}

func TestDeterministic_DifferentSeedsDiffer(t *testing.T) {
first := func(seed uint64) string {
got, err := NewGenerator(fixed(t0), NewDeterministic(seed, seed)).RunID()
require.NoError(t, err)
return got.String()
}
assert.NotEqual(t, first(1), first(2))
}
33 changes: 33 additions & 0 deletions internal/id/doc.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
// Package id makes Trader's identifiers. For now there is one, RunID, which names a
// run and the directory its results are kept in.
//
// A RunID's text form is "run_" and a ULID (https://github.com/ulid/spec): a 48-bit
// millisecond timestamp and 80 bits of entropy in 26 Crockford Base32 characters.
// IDs sort by the time they were made and cannot realistically collide. The ULID
// encoding lives in internal/ulid and is never part of this package's API: no
// exported name exposes a raw ULID, a third-party type or the 16-byte form.
//
// # Construction
//
// A RunID comes only from a Generator or from ParseRunID, which validates text it
// did not make, so a RunID in hand is always well formed. The zero value is unset
// (IsZero, a visible String, and an error when marshaled), never the ID that would
// encode sixteen zero bytes; ParseRunID refuses that pattern too.
//
// # Generation
//
// A Generator never reads the time itself: it is given a func() time.Time (in
// production internal/clock.Clock, in a test a fixed time) and an EntropySource
// (Random, crypto/rand, in production; the seeded Deterministic in tests, so the
// same clock and seed give the same IDs). IDs made in one millisecond get strictly
// increasing entropy, so their text sorts in creation order.
//
// # Other identifiers
//
// Orders have ids from the broker (sim-1, t-1), and an account's id is given when
// it is made. Other kinds (order, fill, event, correlation) are not here until
// something needs a generated identity for them; _archive/internal/id has the
// earlier seven-kind design.
//
// This package is private to Trader's runtime (ADR-065).
package id
14 changes: 14 additions & 0 deletions internal/id/errors.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
package id

import "errors"

var (
// ErrInvalidID reports text that is not a well-formed identifier of the
// a RunID: wrong prefix, malformed ULID body, or a body that decodes to
// the reserved all-zero value.
ErrInvalidID = errors.New("id: invalid identifier")

// ErrZeroValue reports an operation attempted on the unset zero value
// of an ID, where a real identifier is required.
ErrZeroValue = errors.New("id: zero value is not a valid identifier")
)
103 changes: 103 additions & 0 deletions internal/id/generate.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
package id

import (
"crypto/rand"
"errors"
"fmt"
"sync"
"time"

"github.com/rustyeddy/trader/internal/id/internal/ulid"
)

// EntropySource supplies the 80-bit entropy component of a new identifier.
type EntropySource interface {
// Entropy returns 10 fresh random bytes.
Entropy() ([10]byte, error)
}

// Random is an EntropySource backed by crypto/rand: the production
// default. Its zero value is ready to use.
type Random struct{}

// Entropy implements EntropySource.
func (Random) Entropy() ([10]byte, error) {
var b [10]byte
if _, err := rand.Read(b[:]); err != nil {
return [10]byte{}, fmt.Errorf("id: reading entropy: %w", err)
}
return b, nil
}

// ErrEntropyExhausted reports that a Generator made 2^80 IDs within one
// millisecond and cannot make another that still sorts after them.
var ErrEntropyExhausted = errors.New("id: entropy exhausted within one millisecond")

// Generator makes RunIDs from a clock and an entropy source, and never reads the
// time itself. IDs made within the same millisecond get strictly increasing entropy
// rather than fresh random values (the ULID spec's monotonic generation), so their
// text sorts in the order they were made.
//
// If the clock steps backwards (an NTP correction, say) the Generator carries on
// from the last millisecond it used instead of failing: a run must always be able
// to get an ID, and uniqueness and order matter more than the ID's time being exact
// during an adjustment.
//
// A *Generator is safe for concurrent use: uniqueness and order hold across
// goroutines sharing one.
type Generator struct {
now func() time.Time
source EntropySource

mu sync.Mutex
hasLast bool
lastMS int64
lastRand [10]byte
}

// NewGenerator returns a Generator that stamps IDs with now (pass clock.Clock in
// production, a fixed function in a test) and draws entropy from source.
func NewGenerator(now func() time.Time, source EntropySource) *Generator {
return &Generator{now: now, source: source}
}

// RunID makes a new RunID.
//
// It returns ErrEntropyExhausted if it has already made 2^80 IDs in the current
// millisecond; it never falls back to weaker entropy silently.
func (g *Generator) RunID() (RunID, error) {
g.mu.Lock()
defer g.mu.Unlock()

ms := g.now().UnixMilli()
if g.hasLast && ms < g.lastMS {
ms = g.lastMS // the clock went back: continue from the last millisecond
}

var rnd [10]byte
switch {
case !g.hasLast || ms > g.lastMS:
r, err := g.source.Entropy()
if err != nil {
return RunID{}, err
}
rnd = r
default: // the same millisecond, or the clock went back to it
next, overflowed := ulid.IncrementEntropy(g.lastRand)
if overflowed {
return RunID{}, ErrEntropyExhausted
}
rnd = next
}

v, err := ulid.New(ms, rnd)
if err != nil {
return RunID{}, err
}

g.lastMS = ms
g.lastRand = rnd
g.hasLast = true

return RunID{value: v, set: true}, nil
}
Loading
Loading