diff --git a/internal/clock/clock.go b/internal/clock/clock.go new file mode 100644 index 00000000..fedf800f --- /dev/null +++ b/internal/clock/clock.go @@ -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) +} diff --git a/internal/clock/clock_test.go b/internal/clock/clock_test.go new file mode 100644 index 00000000..d0746d41 --- /dev/null +++ b/internal/clock/clock_test.go @@ -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") +} diff --git a/internal/id/deterministic.go b/internal/id/deterministic.go new file mode 100644 index 00000000..7cf62248 --- /dev/null +++ b/internal/id/deterministic.go @@ -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 +} diff --git a/internal/id/deterministic_test.go b/internal/id/deterministic_test.go new file mode 100644 index 00000000..04f1cf9a --- /dev/null +++ b/internal/id/deterministic_test.go @@ -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)) +} diff --git a/internal/id/doc.go b/internal/id/doc.go new file mode 100644 index 00000000..3951c4f4 --- /dev/null +++ b/internal/id/doc.go @@ -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 diff --git a/internal/id/errors.go b/internal/id/errors.go new file mode 100644 index 00000000..013ee1dc --- /dev/null +++ b/internal/id/errors.go @@ -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") +) diff --git a/internal/id/generate.go b/internal/id/generate.go new file mode 100644 index 00000000..bcf0ed81 --- /dev/null +++ b/internal/id/generate.go @@ -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 +} diff --git a/internal/id/generate_test.go b/internal/id/generate_test.go new file mode 100644 index 00000000..31b6a89c --- /dev/null +++ b/internal/id/generate_test.go @@ -0,0 +1,147 @@ +package id + +import ( + "strings" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +var t0 = time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC) + +func fixed(at time.Time) func() time.Time { return func() time.Time { return at } } + +func TestRandom_Entropy(t *testing.T) { + var r Random + a, err := r.Entropy() + require.NoError(t, err) + b, err := r.Entropy() + require.NoError(t, err) + + assert.NotEqual(t, [10]byte{}, a, "crypto/rand giving all zero bytes is astronomically unlikely") + assert.NotEqual(t, a, b, "two draws should not collide") +} + +func TestGenerator_RunID(t *testing.T) { + g := NewGenerator(fixed(t0), NewDeterministic(1, 2)) + got, err := g.RunID() + require.NoError(t, err) + + assert.False(t, got.IsZero()) + assert.True(t, strings.HasPrefix(got.String(), "run_")) + again, err := ParseRunID(got.String()) + require.NoError(t, err) + assert.True(t, got.Equal(again), "what it makes, ParseRunID accepts") +} + +func TestGenerator_SameMillisecondIsMonotonic(t *testing.T) { + // A clock that never moves lands every call on one millisecond, which forces the + // monotonic-entropy path. + g := NewGenerator(fixed(t0), NewDeterministic(1, 2)) + + var prev RunID + for i := range 100 { + got, err := g.RunID() + require.NoError(t, err) + if i > 0 { + assert.Less(t, prev.String(), got.String(), "strictly increasing within one millisecond") + } + prev = got + } +} + +func TestGenerator_AdvancingMillisecondsStaysOrdered(t *testing.T) { + now := t0 + g := NewGenerator(func() time.Time { return now }, NewDeterministic(1, 2)) + + var prev RunID + for i := range 20 { + now = t0.Add(time.Duration(i) * time.Millisecond) + got, err := g.RunID() + require.NoError(t, err) + if i > 0 { + assert.Less(t, prev.String(), got.String()) + } + prev = got + } +} + +func TestGenerator_ReportsEntropyError(t *testing.T) { + _, err := NewGenerator(fixed(t0), failingSource{}).RunID() + require.ErrorIs(t, err, assert.AnError) +} + +func TestGenerator_ReportsEntropyExhaustion(t *testing.T) { + g := NewGenerator(fixed(t0), maxEntropySource{}) + + // The first call draws all 0xFF; the second, in the same millisecond, cannot + // increment past it and must say so rather than wrap to zero. + _, err := g.RunID() + require.NoError(t, err) + _, err = g.RunID() + require.ErrorIs(t, err, ErrEntropyExhausted) +} + +func TestGenerator_ClockMovingBackwardContinuesFromTheLastMillisecond(t *testing.T) { + // 5 ms, then back to 2 ms, then forward again to 9 ms. + times := []time.Time{t0.Add(5 * time.Millisecond), t0.Add(2 * time.Millisecond), t0.Add(9 * time.Millisecond)} + g := NewGenerator(func() time.Time { t := times[0]; times = times[1:]; return t }, NewDeterministic(1, 2)) + + var ids []RunID + for range 3 { + got, err := g.RunID() + require.NoError(t, err, "a run can always get an ID") + ids = append(ids, got) + } + + assert.Less(t, ids[0].String(), ids[1].String(), "still strictly increasing after the step back") + assert.Less(t, ids[1].String(), ids[2].String()) + second, err := ids[1].Time() + require.NoError(t, err) + assert.True(t, second.Equal(t0.Add(5*time.Millisecond)), "stamped with the last millisecond used, not the earlier one: %s", second) + third, err := ids[2].Time() + require.NoError(t, err) + assert.True(t, third.Equal(t0.Add(9*time.Millisecond)), "and follows the clock again once it passes it") +} + +func TestGenerator_ConcurrentUseGivesUniqueIDs(t *testing.T) { + g := NewGenerator(fixed(t0), NewDeterministic(1, 2)) + + const n = 200 + results := make(chan RunID, n) + errs := make(chan error, n) + for range n { + go func() { + got, err := g.RunID() + results <- got + errs <- err + }() + } + + seen := make(map[string]bool, n) + for range n { + require.NoError(t, <-errs) + got := (<-results).String() + assert.False(t, seen[got], "duplicate ID under concurrent use") + seen[got] = true + } +} + +// failingSource always errors, to show a Generator reports it instead of falling back. +type failingSource struct{} + +func (failingSource) Entropy() ([10]byte, error) { return [10]byte{}, assert.AnError } + +// maxEntropySource always returns the largest entropy, so the next call in the same +// millisecond must overflow when it increments it. +type maxEntropySource struct{} + +func (maxEntropySource) Entropy() ([10]byte, error) { + var b [10]byte + for i := range b { + b[i] = 0xFF + } + return b, nil +} diff --git a/internal/id/id_test.go b/internal/id/id_test.go new file mode 100644 index 00000000..5120a547 --- /dev/null +++ b/internal/id/id_test.go @@ -0,0 +1,37 @@ +package id + +import ( + "go/parser" + "go/token" + "path/filepath" + "strconv" + "strings" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// The package makes IDs from the standard library and its own ULID encoding only: +// no third-party ID library, and nothing from the rest of the module (it is a leaf +// the engine and services depend on, never the other way round). +func TestPackage_ImportsOnlyTheStandardLibraryAndItsULID(t *testing.T) { + files, err := filepath.Glob("*.go") + require.NoError(t, err) + require.NotEmpty(t, files) + + for _, name := range files { + if strings.HasSuffix(name, "_test.go") { + continue + } + f, err := parser.ParseFile(token.NewFileSet(), name, nil, parser.ImportsOnly) + require.NoError(t, err) + for _, imp := range f.Imports { + path, err := strconv.Unquote(imp.Path.Value) + require.NoError(t, err) + stdlib := !strings.Contains(strings.SplitN(path, "/", 2)[0], ".") + assert.True(t, stdlib || path == "github.com/rustyeddy/trader/internal/id/internal/ulid", + "%s imports %s", name, path) + } + } +} diff --git a/internal/id/internal/ulid/ulid.go b/internal/id/internal/ulid/ulid.go new file mode 100644 index 00000000..7e4f2e84 --- /dev/null +++ b/internal/id/internal/ulid/ulid.go @@ -0,0 +1,177 @@ +// Package ulid implements the exact 128-bit representation mechanics behind +// Trader-owned identifiers: packing a 48-bit millisecond timestamp and +// 80 bits of entropy into 16 bytes, and converting between that +// representation and its canonical 26-character Crockford Base32 text form +// (https://github.com/ulid/spec). +// +// This package knows nothing about Trader's identifier kinds, generation +// policy, or monotonic sequencing; it knows only how to pack, encode, and +// decode the 128 bits. The public id package owns everything semantic — +// which kind an identifier belongs to, how it is generated, and what the +// zero value means — the same division of responsibility num/internal/fixed +// has with num. +package ulid + +import ( + "encoding/binary" + "fmt" + "time" +) + +// EncodedLen is the length of a ULID's canonical text encoding: 128 bits at +// 5 bits per Crockford Base32 character, rounded up to 26. +const EncodedLen = 26 + +// maxTimestamp is the largest value New accepts: the largest 48-bit +// unsigned integer, corresponding to roughly the year 10889. +const maxTimestamp = (1 << 48) - 1 + +// New packs a 48-bit millisecond-since-Unix-epoch timestamp and 80 bits of +// entropy into a 128-bit value: the timestamp occupies the first 6 bytes, +// most significant byte first, and entropy fills the remaining 10. +func New(millis int64, entropy [10]byte) ([16]byte, error) { + if millis < 0 || millis > maxTimestamp { + return [16]byte{}, fmt.Errorf("ulid: timestamp %d milliseconds out of 48-bit range", millis) + } + + var v [16]byte + v[0] = byte(millis >> 40) + v[1] = byte(millis >> 32) + v[2] = byte(millis >> 24) + v[3] = byte(millis >> 16) + v[4] = byte(millis >> 8) + v[5] = byte(millis) + copy(v[6:], entropy[:]) + return v, nil +} + +// Timestamp returns the UTC instant encoded in v's first 6 bytes. +func Timestamp(v [16]byte) time.Time { + millis := int64(v[0])<<40 | int64(v[1])<<32 | int64(v[2])<<24 | + int64(v[3])<<16 | int64(v[4])<<8 | int64(v[5]) + return time.UnixMilli(millis).UTC() +} + +// Entropy returns v's last 10 bytes: the 80-bit component that is not the +// timestamp. +func Entropy(v [16]byte) [10]byte { + var e [10]byte + copy(e[:], v[6:]) + return e +} + +// IncrementEntropy returns e+1, treating e as an unsigned 80-bit big-endian +// integer, and reports whether the increment overflowed — e was already +// the maximum representable value, 2^80-1. This is what lets a generator +// produce strictly increasing values for multiple identifiers created +// within the same millisecond, per the ULID spec's monotonic generation +// guidance, without drawing fresh entropy that could sort earlier than a +// sibling created moments before it. +func IncrementEntropy(e [10]byte) (next [10]byte, overflowed bool) { + next = e + for i := len(next) - 1; i >= 0; i-- { + next[i]++ + if next[i] != 0 { + return next, false + } + } + return next, true +} + +const alphabet = "0123456789ABCDEFGHJKMNPQRSTVWXYZ" + +// reverse maps an alphabet byte to its 5-bit value, or 0xFF for a byte that +// is not in the alphabet. Crockford Base32 is decoded strictly here: no +// case-folding and no typo-tolerant substitution (Crockford's own spec +// permits treating "O" as "0" and "I"/"L" as "1", but this package rejects +// rather than repairs malformed input, matching num's exact-parsing +// policy elsewhere in this module). +var reverse [256]byte + +func init() { + for i := range reverse { + reverse[i] = 0xFF + } + for i := range len(alphabet) { + reverse[alphabet[i]] = byte(i) + } +} + +// Encode returns v's canonical 26-character Crockford Base32 encoding. +func Encode(v [16]byte) string { + hi := binary.BigEndian.Uint64(v[0:8]) + lo := binary.BigEndian.Uint64(v[8:16]) + + var out [EncodedLen]byte + out[0] = alphabet[(hi>>61)&0x1F] + out[1] = alphabet[(hi>>56)&0x1F] + out[2] = alphabet[(hi>>51)&0x1F] + out[3] = alphabet[(hi>>46)&0x1F] + out[4] = alphabet[(hi>>41)&0x1F] + out[5] = alphabet[(hi>>36)&0x1F] + out[6] = alphabet[(hi>>31)&0x1F] + out[7] = alphabet[(hi>>26)&0x1F] + out[8] = alphabet[(hi>>21)&0x1F] + out[9] = alphabet[(hi>>16)&0x1F] + out[10] = alphabet[(hi>>11)&0x1F] + out[11] = alphabet[(hi>>6)&0x1F] + out[12] = alphabet[(hi>>1)&0x1F] + out[13] = alphabet[((hi&0x1)<<4)|((lo>>60)&0x0F)] + out[14] = alphabet[(lo>>55)&0x1F] + out[15] = alphabet[(lo>>50)&0x1F] + out[16] = alphabet[(lo>>45)&0x1F] + out[17] = alphabet[(lo>>40)&0x1F] + out[18] = alphabet[(lo>>35)&0x1F] + out[19] = alphabet[(lo>>30)&0x1F] + out[20] = alphabet[(lo>>25)&0x1F] + out[21] = alphabet[(lo>>20)&0x1F] + out[22] = alphabet[(lo>>15)&0x1F] + out[23] = alphabet[(lo>>10)&0x1F] + out[24] = alphabet[(lo>>5)&0x1F] + out[25] = alphabet[lo&0x1F] + return string(out[:]) +} + +// Decode parses s, which must be exactly EncodedLen characters from the +// Crockford Base32 alphabet, back into its 128-bit value. Decode rejects +// the wrong length, any character outside the alphabet, and a first +// character whose value would require more than the 3 significant bits +// available at the top of a 128-bit value (128 is not a multiple of 5, so +// the 26-character encoding has 2 unused leading bits; a first character +// value of 8 or more would need one of those bits, meaning the input does +// not represent 128 bits at all). +func Decode(s string) ([16]byte, error) { + if len(s) != EncodedLen { + return [16]byte{}, fmt.Errorf("ulid: wrong length: got %d characters, want %d", len(s), EncodedLen) + } + + var v [EncodedLen]byte + for i := range EncodedLen { + b := reverse[s[i]] + if b == 0xFF { + return [16]byte{}, fmt.Errorf("ulid: invalid character %q at position %d", s[i], i) + } + v[i] = b + } + if v[0] > 7 { + return [16]byte{}, fmt.Errorf("ulid: first character out of range: would overflow 128 bits") + } + + hi := uint64(v[0])<<61 | + uint64(v[1])<<56 | uint64(v[2])<<51 | uint64(v[3])<<46 | + uint64(v[4])<<41 | uint64(v[5])<<36 | uint64(v[6])<<31 | + uint64(v[7])<<26 | uint64(v[8])<<21 | uint64(v[9])<<16 | + uint64(v[10])<<11 | uint64(v[11])<<6 | uint64(v[12])<<1 | + uint64(v[13])>>4 + + lo := uint64(v[13]&0x0F)<<60 | + uint64(v[14])<<55 | uint64(v[15])<<50 | uint64(v[16])<<45 | + uint64(v[17])<<40 | uint64(v[18])<<35 | uint64(v[19])<<30 | + uint64(v[20])<<25 | uint64(v[21])<<20 | uint64(v[22])<<15 | + uint64(v[23])<<10 | uint64(v[24])<<5 | uint64(v[25]) + + var out [16]byte + binary.BigEndian.PutUint64(out[0:8], hi) + binary.BigEndian.PutUint64(out[8:16], lo) + return out, nil +} diff --git a/internal/id/internal/ulid/ulid_test.go b/internal/id/internal/ulid/ulid_test.go new file mode 100644 index 00000000..22e505c6 --- /dev/null +++ b/internal/id/internal/ulid/ulid_test.go @@ -0,0 +1,227 @@ +package ulid + +import ( + "strings" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestEncodeKnownVectors(t *testing.T) { + tests := []struct { + name string + in [16]byte + want string + }{ + {name: "all zero", in: [16]byte{}, want: strings.Repeat("0", 26)}, + {name: "all 0xFF", in: fill(0xFF), want: "7ZZZZZZZZZZZZZZZZZZZZZZZZZ"}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got := Encode(tt.in) + assert.Len(t, got, EncodedLen) + assert.Equal(t, tt.want, got) + }) + } +} + +func TestEncodeDecodeRoundTrip(t *testing.T) { + tests := []struct { + name string + in [16]byte + }{ + {name: "all zero", in: [16]byte{}}, + {name: "all 0xFF", in: fill(0xFF)}, + {name: "sequential bytes", in: [16]byte{0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15}}, + {name: "alternating bits", in: fill(0xAA)}, + {name: "one bit set at top", in: [16]byte{0x80}}, + {name: "one bit set at bottom", in: [16]byte{0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1}}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + encoded := Encode(tt.in) + require.Len(t, encoded, EncodedLen) + + got, err := Decode(encoded) + require.NoError(t, err) + assert.Equal(t, tt.in, got) + }) + } +} + +func TestDecodeRejectsWrongLength(t *testing.T) { + _, err := Decode("TOOSHORT") + require.Error(t, err) + + _, err = Decode(Encode([16]byte{}) + "X") + require.Error(t, err) + + _, err = Decode("") + require.Error(t, err) +} + +func TestDecodeRejectsInvalidCharacters(t *testing.T) { + // Crockford Base32 excludes I, L, O, and U specifically to avoid + // confusion with 1 and 0; each must be rejected, not silently mapped. + for _, c := range []byte{'I', 'L', 'O', 'U', 'i', 'o', '!', ' ', '_'} { + t.Run(string(c), func(t *testing.T) { + s := []byte(Encode([16]byte{})) + s[0] = c + _, err := Decode(string(s)) + require.Error(t, err) + }) + } +} + +func TestDecodeRejectsLowercase(t *testing.T) { + // Strict, exact-parsing policy: no case folding, matching num's + // reject-rather-than-repair convention elsewhere in this module. + upper := Encode([16]byte{1, 2, 3}) + lower := toLower(upper) + require.NotEqual(t, upper, lower) + + _, err := Decode(lower) + require.Error(t, err) +} + +func TestDecodeRejectsOverflowingFirstCharacter(t *testing.T) { + // The first character can only carry 3 significant bits (128 is not a + // multiple of 5); a value of 8 or more there would require a 129th or + // 130th bit that a 128-bit value does not have. + s := []byte(Encode([16]byte{})) + s[0] = alphabet[8] + _, err := Decode(string(s)) + require.Error(t, err) + + s[0] = alphabet[31] + _, err = Decode(string(s)) + require.Error(t, err) +} + +func TestNewPacksTimestampAndEntropy(t *testing.T) { + entropy := [10]byte{1, 2, 3, 4, 5, 6, 7, 8, 9, 10} + v, err := New(1_000, entropy) + require.NoError(t, err) + + assert.Equal(t, entropy, Entropy(v)) + assert.True(t, Timestamp(v).Equal(time.UnixMilli(1_000).UTC())) +} + +func TestNewRejectsOutOfRangeTimestamp(t *testing.T) { + _, err := New(-1, [10]byte{}) + require.Error(t, err) + + _, err = New(maxTimestamp+1, [10]byte{}) + require.Error(t, err) + + _, err = New(maxTimestamp, [10]byte{}) + require.NoError(t, err) + + _, err = New(0, [10]byte{}) + require.NoError(t, err) +} + +func TestTimestampExtractionRoundTrip(t *testing.T) { + want := time.Date(2026, 8, 6, 12, 34, 56, 789_000_000, time.UTC) + v, err := New(want.UnixMilli(), [10]byte{}) + require.NoError(t, err) + + got := Timestamp(v) + assert.True(t, got.Equal(want)) + assert.Equal(t, time.UTC, got.Location()) +} + +func TestIncrementEntropy(t *testing.T) { + tests := []struct { + name string + in [10]byte + wantNext [10]byte + wantOverflowed bool + }{ + { + name: "simple increment", + in: [10]byte{0, 0, 0, 0, 0, 0, 0, 0, 0, 1}, + wantNext: [10]byte{0, 0, 0, 0, 0, 0, 0, 0, 0, 2}, + }, + { + name: "carry across one byte", + in: [10]byte{0, 0, 0, 0, 0, 0, 0, 0, 0, 0xFF}, + wantNext: [10]byte{0, 0, 0, 0, 0, 0, 0, 0, 1, 0}, + }, + { + name: "carry across multiple bytes", + in: [10]byte{0, 0, 0, 0, 0, 0, 0, 0xFF, 0xFF, 0xFF}, + wantNext: [10]byte{0, 0, 0, 0, 0, 0, 1, 0, 0, 0}, + }, + { + name: "overflow at maximum value", + in: fill10(0xFF), + wantNext: [10]byte{}, + wantOverflowed: true, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + next, overflowed := IncrementEntropy(tt.in) + assert.Equal(t, tt.wantOverflowed, overflowed) + if !overflowed { + assert.Equal(t, tt.wantNext, next) + } + }) + } +} + +// FuzzEncodeDecode checks the round trip that must always hold: every +// 128-bit value's canonical encoding must decode back to the identical +// value. +func FuzzEncodeDecode(f *testing.F) { + f.Add(int64(0)) + f.Add(int64(-1)) + f.Add(int64(1<<63 - 1)) + + f.Fuzz(func(t *testing.T, seed int64) { + var v [16]byte + // Spread the fuzzer's single int64 seed across all 16 bytes with a + // simple mix, so each run still exercises the full byte range + // rather than only the low 8 bytes. + for i := range v { + seed = seed*6364136223846793005 + 1442695040888963407 + v[i] = byte(seed >> 56) + } + + got, err := Decode(Encode(v)) + require.NoError(t, err) + assert.Equal(t, v, got) + }) +} + +func fill(b byte) [16]byte { + var v [16]byte + for i := range v { + v[i] = b + } + return v +} + +func fill10(b byte) [10]byte { + var v [10]byte + for i := range v { + v[i] = b + } + return v +} + +func toLower(s string) string { + b := []byte(s) + for i, c := range b { + if c >= 'A' && c <= 'Z' { + b[i] = c + ('a' - 'A') + } + } + return string(b) +} diff --git a/internal/id/runid.go b/internal/id/runid.go new file mode 100644 index 00000000..670c86af --- /dev/null +++ b/internal/id/runid.go @@ -0,0 +1,111 @@ +package id + +import ( + "encoding/json" + "fmt" + "strings" + "time" + + "github.com/rustyeddy/trader/internal/id/internal/ulid" +) + +// runPrefix starts the text form of every RunID, so a stray one in a log line or a +// directory listing is recognisable on sight. +const runPrefix = "run_" + +// RunID identifies one run. Its text form is "run_" and a ULID: 26 Crockford +// Base32 characters holding the millisecond the ID was made and 80 bits of +// entropy, so run directories sort by start time and two never collide. +// +// The zero value is unset, not the ID that happens to encode sixteen zero bytes: +// IsZero reports true, String says so, and marshaling it is an error. A RunID +// comes only from a Generator or from ParseRunID, so it is always well formed. +type RunID struct { + value [16]byte + set bool +} + +// String is the canonical text form, or "" for the zero value. +func (id RunID) String() string { + if !id.set { + return "" + } + return runPrefix + ulid.Encode(id.value) +} + +// IsZero reports whether id is the unset zero value. +func (id RunID) IsZero() bool { return !id.set } + +// Equal reports whether id and o are the same ID. Two zero values are equal. +func (id RunID) Equal(o RunID) bool { return id.set == o.set && id.value == o.value } + +// Time is the instant the ID was made, in UTC, to the millisecond. +func (id RunID) Time() (time.Time, error) { + if !id.set { + return time.Time{}, ErrZeroValue + } + return ulid.Timestamp(id.value), nil +} + +// ParseRunID checks that s is a RunID in its canonical form and returns it. It +// refuses anything else (a wrong prefix, a malformed body, the reserved all-zero +// value) and repairs nothing. +func ParseRunID(s string) (RunID, error) { + rest, ok := strings.CutPrefix(s, runPrefix) + if !ok { + return RunID{}, fmt.Errorf("%w: %q does not start with %q", ErrInvalidID, s, runPrefix) + } + v, err := ulid.Decode(rest) + if err != nil { + return RunID{}, fmt.Errorf("%w: %v", ErrInvalidID, err) + } + if v == ([16]byte{}) { + return RunID{}, fmt.Errorf("%w: the all-zero value is reserved for the unset zero value", ErrInvalidID) + } + return RunID{value: v, set: true}, nil +} + +// MustParseRunID is ParseRunID for constants and tests; it panics on error. +func MustParseRunID(s string) RunID { + id, err := ParseRunID(s) + if err != nil { + panic(err) + } + return id +} + +// MarshalText encodes id as its text form. The zero value is an error: it is not +// a real ID, and a caller that forgot to set one should hear about it. +func (id RunID) MarshalText() ([]byte, error) { + if !id.set { + return nil, ErrZeroValue + } + return []byte(id.String()), nil +} + +// UnmarshalText decodes the text form, refusing anything ParseRunID refuses. +func (id *RunID) UnmarshalText(text []byte) error { + v, err := ParseRunID(string(text)) + if err != nil { + return err + } + *id = v + return nil +} + +// MarshalJSON encodes id as a JSON string holding its text form. +func (id RunID) MarshalJSON() ([]byte, error) { + if !id.set { + return nil, ErrZeroValue + } + return json.Marshal(id.String()) +} + +// UnmarshalJSON decodes a JSON string holding the text form. +func (id *RunID) UnmarshalJSON(data []byte) error { + var s string + if err := json.Unmarshal(data, &s); err != nil { + return err + } + return id.UnmarshalText([]byte(s)) +} diff --git a/internal/id/runid_test.go b/internal/id/runid_test.go new file mode 100644 index 00000000..9c9feb66 --- /dev/null +++ b/internal/id/runid_test.go @@ -0,0 +1,124 @@ +package id + +import ( + "encoding/json" + "strings" + "testing" + "time" + + "github.com/rustyeddy/trader/internal/id/internal/ulid" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// validRunID builds a well formed RunID string, varying one byte so distinct calls +// give distinct IDs, without going through a Generator. +func validRunID(b byte) string { + var v [16]byte + v[15] = b + return "run_" + ulid.Encode(v) +} + +func TestParseRunID_RoundTrips(t *testing.T) { + for i := range 5 { + id, err := ParseRunID(validRunID(byte(i + 1))) + require.NoError(t, err) + again, err := ParseRunID(id.String()) + require.NoError(t, err) + assert.True(t, id.Equal(again)) + assert.Equal(t, validRunID(byte(i+1)), id.String()) + } +} + +func TestParseRunID_Rejects(t *testing.T) { + tests := []struct{ name, in string }{ + {"empty", ""}, + {"prefix only", "run_"}, + {"no separator", "run01H8Z3K3R2N4XG9YB6HFA1V7ZQ"}, + {"short body", "run_TOOSHORT"}, + {"invalid character", "run_I1H8Z3K3R2N4XG9YB6HFA1V7ZQ"}, + {"no prefix", "01H8Z3K3R2N4XG9YB6HFA1V7ZQ"}, + {"another kind's prefix", "ord_" + strings.TrimPrefix(validRunID(1), "run_")}, + {"the reserved all-zero value", "run_" + strings.Repeat("0", 26)}, + {"a directory name with a suffix", validRunID(1) + "-copy"}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + _, err := ParseRunID(tt.in) + require.ErrorIs(t, err, ErrInvalidID) + }) + } +} + +func TestMustParseRunID(t *testing.T) { + assert.Equal(t, validRunID(1), MustParseRunID(validRunID(1)).String()) + assert.Panics(t, func() { MustParseRunID("not-a-valid-id") }) +} + +func TestRunID_ZeroValue(t *testing.T) { + var r RunID + assert.True(t, r.IsZero()) + assert.Equal(t, "", r.String()) + assert.False(t, MustParseRunID(validRunID(1)).IsZero()) + + _, err := r.Time() + require.ErrorIs(t, err, ErrZeroValue) + _, err = r.MarshalText() + require.ErrorIs(t, err, ErrZeroValue) + _, err = json.Marshal(r) + require.Error(t, err) +} + +func TestRunID_Equal(t *testing.T) { + a := MustParseRunID(validRunID(1)) + assert.True(t, a.Equal(MustParseRunID(a.String()))) + assert.False(t, a.Equal(MustParseRunID(validRunID(2)))) + + var zero RunID + assert.True(t, zero.Equal(RunID{}), "two zero values are equal") + assert.False(t, a.Equal(zero)) +} + +func TestRunID_Time(t *testing.T) { + at := time.Date(2026, 11, 21, 18, 15, 0, 123_000_000, time.UTC) + id, err := NewGenerator(func() time.Time { return at }, NewDeterministic(1, 2)).RunID() + require.NoError(t, err) + + got, err := id.Time() + require.NoError(t, err) + assert.True(t, got.Equal(at), "the creation time to the millisecond: %s", got) + assert.Equal(t, time.UTC, got.Location()) +} + +func TestRunID_Text(t *testing.T) { + want := MustParseRunID(validRunID(7)) + text, err := want.MarshalText() + require.NoError(t, err) + assert.Equal(t, want.String(), string(text)) + + var got RunID + require.NoError(t, got.UnmarshalText(text)) + assert.True(t, want.Equal(got)) + + require.ErrorIs(t, got.UnmarshalText([]byte("not-a-valid-id")), ErrInvalidID) + require.ErrorIs(t, got.UnmarshalText([]byte("ord_"+strings.TrimPrefix(validRunID(1), "run_"))), ErrInvalidID) +} + +func TestRunID_JSON(t *testing.T) { + type record struct { + RunID RunID `json:"run_id"` + } + want := record{RunID: MustParseRunID(validRunID(9))} + + data, err := json.Marshal(want) + require.NoError(t, err) + assert.JSONEq(t, `{"run_id":"`+validRunID(9)+`"}`, string(data), "a string, never the raw bytes") + + var got record + require.NoError(t, json.Unmarshal(data, &got)) + assert.True(t, want.RunID.Equal(got.RunID)) + + var r RunID + require.ErrorIs(t, json.Unmarshal([]byte(`"not-a-valid-id"`), &r), ErrInvalidID) + require.Error(t, json.Unmarshal([]byte(`12345`), &r)) +}