From 34f28a338a7ffc5227024d52ea87069ef6672cdf Mon Sep 17 00:00:00 2001 From: Rusty Eddy Date: Sat, 21 Nov 2026 12:11:23 -0800 Subject: [PATCH 1/2] Port the RunID from _archive/internal/id; add internal/clock (#702) internal/id keeps the ULID encoding, the monotonic Generator, Random and the seeded Deterministic entropy source, and RunID with its text and JSON forms. The other six kinds, Metadata and the clock.Clock interface are not ported. The Generator takes a func() time.Time; internal/clock.Clock is the one place that reads the time. Co-Authored-By: Claude Sonnet 5.5 --- _archive/internal/id/deterministic.go | 41 --- _archive/internal/id/doc.go | 126 ---------- _archive/internal/id/encoding.go | 49 ---- _archive/internal/id/encoding_test.go | 100 -------- _archive/internal/id/generate.go | 114 --------- _archive/internal/id/generate_test.go | 238 ------------------ _archive/internal/id/id.go | 98 -------- _archive/internal/id/id_test.go | 143 ----------- internal/clock/clock.go | 12 + internal/clock/clock_test.go | 19 ++ internal/id/deterministic.go | 35 +++ internal/id/deterministic_test.go | 34 +++ internal/id/doc.go | 33 +++ {_archive/internal => internal}/id/errors.go | 4 +- internal/id/generate.go | 104 ++++++++ internal/id/generate_test.go | 135 ++++++++++ internal/id/id_test.go | 37 +++ .../id/internal/ulid/ulid.go | 0 .../id/internal/ulid/ulid_test.go | 0 internal/id/runid.go | 111 ++++++++ internal/id/runid_test.go | 124 +++++++++ 21 files changed, 646 insertions(+), 911 deletions(-) delete mode 100644 _archive/internal/id/deterministic.go delete mode 100644 _archive/internal/id/doc.go delete mode 100644 _archive/internal/id/encoding.go delete mode 100644 _archive/internal/id/encoding_test.go delete mode 100644 _archive/internal/id/generate.go delete mode 100644 _archive/internal/id/generate_test.go delete mode 100644 _archive/internal/id/id.go delete mode 100644 _archive/internal/id/id_test.go create mode 100644 internal/clock/clock.go create mode 100644 internal/clock/clock_test.go create mode 100644 internal/id/deterministic.go create mode 100644 internal/id/deterministic_test.go create mode 100644 internal/id/doc.go rename {_archive/internal => internal}/id/errors.go (75%) create mode 100644 internal/id/generate.go create mode 100644 internal/id/generate_test.go create mode 100644 internal/id/id_test.go rename {_archive/internal => internal}/id/internal/ulid/ulid.go (100%) rename {_archive/internal => internal}/id/internal/ulid/ulid_test.go (100%) create mode 100644 internal/id/runid.go create mode 100644 internal/id/runid_test.go diff --git a/_archive/internal/id/deterministic.go b/_archive/internal/id/deterministic.go deleted file mode 100644 index 1fee4654..00000000 --- a/_archive/internal/id/deterministic.go +++ /dev/null @@ -1,41 +0,0 @@ -package id - -import ( - "math/rand/v2" - "sync" -) - -// Deterministic is an EntropySource that draws entropy from a seeded PRNG, -// for tests and replay: given the same seed, it produces the same sequence of -// entropy values every time, so — combined with a clock.Simulated — a -// Generator using it produces the same sequence of identifiers every time, -// satisfying issue #24's "deterministic generation produces reproducible -// sequences" requirement. -// -// Deterministic must never be used in production: its entropy is -// reproducible by construction, which is exactly what production -// identifiers must not be. -type Deterministic struct { - mu sync.Mutex - rng *rand.Rand -} - -// NewDeterministic returns a Deterministic source seeded with seed1 and -// seed2 — the same two-value seed shape math/rand/v2's PCG source itself -// takes, exposed directly rather than derived from a single value, so the -// seed a caller passes is exactly the seed that determines the sequence. -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/_archive/internal/id/doc.go b/_archive/internal/id/doc.go deleted file mode 100644 index 1e7f562c..00000000 --- a/_archive/internal/id/doc.go +++ /dev/null @@ -1,126 +0,0 @@ -// Package id implements Trader-owned identifiers and correlation metadata, -// as decided by issue #24 (M1-06). -// -// # Seven identifier kinds -// -// RunID, OrderID, FillID, EventID, CorrelationID, AccountID, and IntentID -// are each a distinct Go type — a RunID can never be assigned where an -// OrderID is expected, caught at compile time, not at runtime. Internally -// they share one generic implementation (ID[K], in id.go) rather than -// seven hand-copied ones, but nothing about that is visible at a call -// site: id.RunID is used exactly like any other named type. -// -// This is deliberately fewer kinds than issue #24 originally proposed; see -// "Deferred identifiers" below for which ones were cut, and why. -// -// Each kind's canonical string form carries a short prefix identifying it — -// "run_01J8Z3K3R2N4XG9YB6HFA1V7ZQ", "ord_01J8Z3K5H7T1MDCE9WNRP2VXY0" — so a -// stray ID string in a log line or database column is identifiable on -// sight, without cross-referencing code. The 26 characters after the -// prefix are a ULID (https://github.com/ulid/spec): a 48-bit millisecond -// timestamp followed by 80 bits of entropy, Crockford Base32 encoded. ULID -// is an internal encoding choice — see id/internal/ulid — never a public -// dependency; nothing in this package's exported API exposes a raw ULID -// value, a third-party ULID type, or the underlying [16]byte -// representation. -// -// # Construction -// -// Parse and the concrete Parse functions (ParseRunID, ParseOrderID, -// ...) validate external or persisted text. Generate and the concrete -// Generate functions produce new identifiers from a Generator. There -// is no way to construct a non-zero ID holding an arbitrary value: every -// path validates the kind prefix and the ULID body, or comes from a -// Generator that owns real entropy and a real clock. -// -// # Trader-owned versus broker-native identifiers -// -// A broker's own identifier for an order, account, or fill is not an -// id.OrderID or id.AccountID: broker identifiers are opaque strings with -// no ULID structure. Parsing one as a Trader ID simply fails — that -// structural rejection is what keeps the two from being confused, rather -// than a parallel BrokerOrderID type defined here. Packages that talk to a -// specific broker define their own native-identifier types (BrokerOrderID, -// BrokerAccountID, ...) alongside whatever mapping they need between the -// two; that mapping is a broker-adapter concern, not this package's. -// -// # AccountID has a different lifecycle -// -// Every other kind is generated fresh for the event it identifies: a new -// RunID per run, a new OrderID per order. AccountID is not: it is -// generated once when the account entity is created and then persisted -// for that account's lifetime, never regenerated on a later run. -// -// # Deferred identifiers -// -// Issue #24 originally proposed SessionID, IntentID, ProposalID, and -// InstrumentID alongside the six kinds this package originally exported. -// They were cut from the initial scope on review, using this rule of -// thumb: would two otherwise-identical instances of this thing ever need -// to coexist and be distinguished by Trader? That is clearly true for -// runs, orders, fills, and accounts. It was not yet true for sessions, -// intents, and proposals — none of those had a concrete, persisted -// domain object in the codebase yet to justify a generated identity for. -// They were to be added, alongside their corresponding domain objects, -// when that changed. -// -// IntentID was the first of the three to have that domain object appear: -// issue #177 (M4-02) introduced order.Intent, so IntentID was reinstated -// alongside it. SessionID and ProposalID remain deferred for the same -// reason IntentID originally was — no concrete Session or order.Proposal -// identity exists to distinguish yet (order.Proposal itself exists, per -// ADR-017, but nothing has yet needed to tell two Proposals apart by a -// generated identity rather than by the values they carry). -// -// InstrumentID was cut for a different reason: an instrument has a -// natural, canonical identity (EUR/USD, an exchange/symbol/asset triple, -// ...), not an arbitrary generated one. A ULID-based InstrumentID would -// have given EUR/USD a fresh identity every run, which is exactly wrong. -// Instrument identity is expected to come from a canonical instrument -// registry once the architecture document's instrument package exists, -// not from this package. -// -// # Generation -// -// Generator produces monotonic ULIDs from an injected clock.Clock and an -// entropy EntropySource, per ADR-015: it never calls time.Now itself. -// Multiple identifiers generated within the same millisecond receive -// strictly increasing entropy rather than fresh random values, preserving -// lexicographic sort order at millisecond resolution; see generate.go. -// Random is the production EntropySource; Deterministic is a seeded, -// injectable EntropySource for tests and replay — given the same simulated -// clock and seed, it produces the same sequence of identifiers every time. -// (EntropySource, not Source: Source is a separate type below, for -// Metadata's originating-component label — the two are unrelated despite -// the similar name.) -// -// # Zero value -// -// The zero value of every ID kind is unset, not the identifier that -// happens to encode sixteen zero bytes: IsZero reports true for it, -// String names it visibly ("") instead of returning something -// that could pass for real output, and MarshalText/MarshalJSON reject it -// outright. Parse rejects any input that would decode to the all-zero -// value for the same reason — that bit pattern is permanently reserved for -// "unset." -// -// # Correlation metadata -// -// Metadata bundles the fields needed to trace one identifier through a -// multi-stage workflow: EventID identifies this event, CorrelationID is -// shared across every stage of the workflow, CausationID names the -// specific EventID that directly caused this one, Timestamp is the -// canonical UTC event time, and Source names the originating component. -// A typical intent-to-fill chain shares one CorrelationID throughout while -// each stage's CausationID points at the EventID immediately before it: -// -// Intent: correlation = workflow ID, causation = zero (nothing caused it) -// Proposal: correlation = same workflow ID, causation = intent's EventID -// Order: correlation = same workflow ID, causation = proposal's EventID -// Fill: correlation = same workflow ID, causation = order's EventID -// -// See metadata.go. -// -// This package is private to Trader's runtime (ADR-065); it is not part of -// the supported external strategy/research Go API. -package id diff --git a/_archive/internal/id/encoding.go b/_archive/internal/id/encoding.go deleted file mode 100644 index 84f11395..00000000 --- a/_archive/internal/id/encoding.go +++ /dev/null @@ -1,49 +0,0 @@ -package id - -import "encoding/json" - -// MarshalText implements encoding.TextMarshaler, encoding id as its -// canonical text form. -// -// MarshalText reports ErrZeroValue for the zero value rather than emitting -// an empty or placeholder string: the zero value is not a real identifier, -// and a caller that forgot to set one deserves an error here, not a -// silently empty field on the wire. -func (id ID[K]) MarshalText() ([]byte, error) { - if !id.set { - return nil, ErrZeroValue - } - return []byte(id.String()), nil -} - -// UnmarshalText implements encoding.TextUnmarshaler. -func (id *ID[K]) UnmarshalText(text []byte) error { - v, err := Parse[K](string(text)) - if err != nil { - return err - } - *id = v - return nil -} - -// MarshalJSON implements json.Marshaler, encoding id as a JSON string -// holding its canonical text form. -// -// MarshalJSON reports ErrZeroValue for the zero value, for the same reason -// as MarshalText. -func (id ID[K]) MarshalJSON() ([]byte, error) { - if !id.set { - return nil, ErrZeroValue - } - return json.Marshal(id.String()) -} - -// UnmarshalJSON implements json.Unmarshaler, decoding a JSON string holding -// an identifier's canonical text form. -func (id *ID[K]) 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/_archive/internal/id/encoding_test.go b/_archive/internal/id/encoding_test.go deleted file mode 100644 index 77444e30..00000000 --- a/_archive/internal/id/encoding_test.go +++ /dev/null @@ -1,100 +0,0 @@ -package id - -import ( - "encoding/json" - "testing" - - "github.com/stretchr/testify/assert" - "github.com/stretchr/testify/require" -) - -func TestTextRoundTrip(t *testing.T) { - want := MustParseRunID(genValidRunID(t, 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)) -} - -func TestMarshalTextRejectsZeroValue(t *testing.T) { - var zero RunID - _, err := zero.MarshalText() - require.ErrorIs(t, err, ErrZeroValue) -} - -func TestUnmarshalTextRejectsInvalidInput(t *testing.T) { - var r RunID - err := r.UnmarshalText([]byte("not-a-valid-id")) - require.ErrorIs(t, err, ErrInvalidID) -} - -func TestUnmarshalTextRejectsWrongKindPrefix(t *testing.T) { - orderStr := genValidID(t, "ord", 1) - var r RunID - err := r.UnmarshalText([]byte(orderStr)) - require.ErrorIs(t, err, ErrInvalidID) -} - -func TestJSONRoundTrip(t *testing.T) { - want := MustParseOrderID(genValidID(t, "ord", 9)) - - data, err := json.Marshal(want) - require.NoError(t, err) - assert.JSONEq(t, `"`+want.String()+`"`, string(data)) - - var got OrderID - require.NoError(t, json.Unmarshal(data, &got)) - assert.True(t, want.Equal(got)) -} - -func TestMarshalJSONRejectsZeroValue(t *testing.T) { - var zero OrderID - _, err := json.Marshal(zero) - require.Error(t, err) -} - -func TestUnmarshalJSONRejectsMalformedInput(t *testing.T) { - var r RunID - err := json.Unmarshal([]byte(`"not-a-valid-id"`), &r) - require.ErrorIs(t, err, ErrInvalidID) -} - -func TestUnmarshalJSONRejectsNonStringValue(t *testing.T) { - var r RunID - err := json.Unmarshal([]byte(`12345`), &r) - require.Error(t, err) -} - -// TestNoRawBytesInJSON pins ADR-style expectations shared with num/config: -// every field marshals as a string, never as a raw number or byte array -// that would expose the [16]byte representation. -func TestNoRawBytesInJSON(t *testing.T) { - want := MustParseRunID(genValidRunID(t, 3)) - - data, err := json.Marshal(want) - require.NoError(t, err) - - var raw any - require.NoError(t, json.Unmarshal(data, &raw)) - _, isString := raw.(string) - assert.True(t, isString, "marshaled ID must be a JSON string, got %T", raw) -} - -func TestJSONFieldRoundTripInStruct(t *testing.T) { - type wrapper struct { - ID OrderID `json:"id"` - } - - want := wrapper{ID: MustParseOrderID(genValidID(t, "ord", 4))} - - data, err := json.Marshal(want) - require.NoError(t, err) - - var got wrapper - require.NoError(t, json.Unmarshal(data, &got)) - assert.True(t, want.ID.Equal(got.ID)) -} diff --git a/_archive/internal/id/generate.go b/_archive/internal/id/generate.go deleted file mode 100644 index 90fb4c88..00000000 --- a/_archive/internal/id/generate.go +++ /dev/null @@ -1,114 +0,0 @@ -package id - -import ( - "crypto/rand" - "errors" - "fmt" - "sync" - - "github.com/rustyeddy/trader/internal/clock" - "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 -} - -// ErrClockMovedBackward reports that a Generator observed its clock produce -// an earlier timestamp than one it had already used to generate an -// identifier. A Simulated clock cannot do this — ADR-015 has Advance -// reject a negative duration — but a Real clock can, briefly, after a wall- -// clock adjustment; Generate reports this rather than silently reusing or -// ignoring the earlier timestamp. -var ErrClockMovedBackward = errors.New("id: clock moved backward") - -// ErrEntropyExhausted reports that a Generator produced 2^80 identifiers -// within a single millisecond and cannot produce another monotonically -// increasing one without either waiting for the next millisecond or -// drawing fresh, non-monotonic entropy — something Generate never does -// silently. -var ErrEntropyExhausted = errors.New("id: entropy exhausted within one millisecond") - -// Generator produces monotonic Trader-owned identifiers from an injected -// clock.Clock and entropy EntropySource, per ADR-015: it never calls -// time.Now itself. Multiple identifiers generated within the same millisecond -// receive strictly increasing entropy rather than fresh random values — -// the ULID spec's monotonic generation guidance — so their lexicographic -// sort order matches creation order at millisecond resolution. -// -// Generator owns its own synchronization; a *Generator is safe for -// concurrent use, and every generated identifier's uniqueness and -// ordering guarantees hold across goroutines sharing one Generator, not -// just within a single goroutine's calls to it. -type Generator struct { - clock clock.Clock - source EntropySource - - mu sync.Mutex - hasLast bool - lastMS int64 - lastRand [10]byte -} - -// NewGenerator returns a Generator that timestamps identifiers using c and -// draws entropy from source. -func NewGenerator(c clock.Clock, source EntropySource) *Generator { - return &Generator{clock: c, source: source} -} - -// Generate produces a new identifier of kind K. -// -// Generate returns ErrEntropyExhausted if it has already produced 2^80 -// identifiers within the current millisecond, and ErrClockMovedBackward if -// g's clock reports a time earlier than one it has already used. Neither -// falls back to weaker behavior silently. -func Generate[K Kind](g *Generator) (ID[K], error) { - g.mu.Lock() - defer g.mu.Unlock() - - ms := g.clock.Now().UnixMilli() - - var rnd [10]byte - switch { - case !g.hasLast || ms > g.lastMS: - r, err := g.source.Entropy() - if err != nil { - return ID[K]{}, err - } - rnd = r - case ms == g.lastMS: - next, overflowed := ulid.IncrementEntropy(g.lastRand) - if overflowed { - return ID[K]{}, ErrEntropyExhausted - } - rnd = next - default: - return ID[K]{}, ErrClockMovedBackward - } - - v, err := ulid.New(ms, rnd) - if err != nil { - return ID[K]{}, err - } - - g.lastMS = ms - g.lastRand = rnd - g.hasLast = true - - return ID[K]{value: v, set: true}, nil -} diff --git a/_archive/internal/id/generate_test.go b/_archive/internal/id/generate_test.go deleted file mode 100644 index 52e932da..00000000 --- a/_archive/internal/id/generate_test.go +++ /dev/null @@ -1,238 +0,0 @@ -package id - -import ( - "strings" - "testing" - "time" - - "github.com/rustyeddy/trader/internal/clock" - "github.com/stretchr/testify/assert" - "github.com/stretchr/testify/require" -) - -func TestRandomEntropyIsNonZeroAndVaries(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 producing all zero bytes is astronomically unlikely") - assert.NotEqual(t, a, b, "two draws should not collide") -} - -func TestGenerateProducesParsableID(t *testing.T) { - c := clock.NewSimulated(time.Now()) - g := NewGenerator(c, NewDeterministic(1, 2)) - - got, err := GenerateRunID(g) - require.NoError(t, err) - assert.False(t, got.IsZero()) - - again, err := ParseRunID(got.String()) - require.NoError(t, err) - assert.True(t, got.Equal(again)) -} - -func TestGenerateEmbedsClockTimestamp(t *testing.T) { - start := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC) - c := clock.NewSimulated(start) - g := NewGenerator(c, NewDeterministic(1, 2)) - - got, err := GenerateRunID(g) - require.NoError(t, err) - - embedded, err := got.Time() - require.NoError(t, err) - assert.True(t, embedded.Equal(start)) -} - -func TestGenerateDifferentKindsProduceDifferentPrefixedStrings(t *testing.T) { - c := clock.NewSimulated(time.Now()) - g := NewGenerator(c, NewDeterministic(1, 2)) - - run, err := GenerateRunID(g) - require.NoError(t, err) - order, err := GenerateOrderID(g) - require.NoError(t, err) - - assert.True(t, strings.HasPrefix(run.String(), "run_")) - assert.True(t, strings.HasPrefix(order.String(), "ord_")) -} - -func TestGenerateSameMillisecondIsMonotonicallyIncreasing(t *testing.T) { - // A Simulated clock that is never advanced makes every call within this - // test land on the same millisecond, forcing the monotonic-entropy - // path deterministically instead of hoping wall-clock timing happens to - // line up. - c := clock.NewSimulated(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)) - g := NewGenerator(c, NewDeterministic(1, 2)) - - var prev RunID - for i := range 100 { - got, err := GenerateRunID(g) - require.NoError(t, err) - - if i > 0 { - assert.Less(t, prev.String(), got.String(), - "identifiers generated within the same millisecond must sort strictly increasing") - } - prev = got - } -} - -func TestGenerateAcrossAdvancingMillisecondsStaysOrdered(t *testing.T) { - c := clock.NewSimulated(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)) - g := NewGenerator(c, NewDeterministic(1, 2)) - - var prev RunID - for i := range 20 { - if i > 0 { - require.NoError(t, c.Advance(time.Millisecond)) - } - got, err := GenerateRunID(g) - require.NoError(t, err) - - if i > 0 { - assert.Less(t, prev.String(), got.String()) - } - prev = got - } -} - -func TestGenerateReportsEntropySourceError(t *testing.T) { - c := clock.NewSimulated(time.Now()) - g := NewGenerator(c, failingSource{}) - - _, err := GenerateRunID(g) - require.Error(t, err) -} - -func TestGenerateReportsEntropyExhaustion(t *testing.T) { - c := clock.NewSimulated(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)) - g := NewGenerator(c, maxEntropySource{}) - - // First call draws fresh entropy (all 0xFF from this fixed source); - // the second, still within the same millisecond, must increment past - // the maximum representable value and report exhaustion rather than - // silently wrapping around to zero and losing monotonicity. - _, err := GenerateRunID(g) - require.NoError(t, err) - - _, err = GenerateRunID(g) - require.ErrorIs(t, err, ErrEntropyExhausted) -} - -func TestGenerateReportsClockMovedBackward(t *testing.T) { - g := &Generator{clock: &stepClock{times: []time.Time{ - time.Date(2026, 1, 1, 0, 0, 0, 1_000_000, time.UTC), // .001s - time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC), // .000s -- earlier - }}, source: Random{}} - - _, err := GenerateRunID(g) - require.NoError(t, err) - - _, err = GenerateRunID(g) - require.ErrorIs(t, err, ErrClockMovedBackward) -} - -func TestGeneratorConcurrentUseProducesUniqueIDs(t *testing.T) { - c := clock.NewSimulated(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)) - g := NewGenerator(c, NewDeterministic(1, 2)) - - const n = 200 - results := make(chan RunID, n) - errs := make(chan error, n) - - for range n { - go func() { - got, err := GenerateRunID(g) - results <- got - errs <- err - }() - } - - seen := make(map[string]bool, n) - for range n { - require.NoError(t, <-errs) - got := <-results - assert.False(t, seen[got.String()], "duplicate identifier generated under concurrent use") - seen[got.String()] = true - } -} - -// TestDeterministicReproducesSequence is the concrete proof behind issue -// #24's "deterministic generation produces reproducible sequences" -// acceptance criterion: the same seed and the same simulated clock produce -// the exact same sequence of identifiers, every time. -func TestDeterministicReproducesSequence(t *testing.T) { - run := func() []string { - c := clock.NewSimulated(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)) - g := NewGenerator(c, NewDeterministic(42, 7)) - - out := make([]string, 10) - for i := range out { - require.NoError(t, c.Advance(time.Millisecond)) - got, err := GenerateRunID(g) - require.NoError(t, err) - out[i] = got.String() - } - return out - } - - first := run() - second := run() - assert.Equal(t, first, second) -} - -func TestDeterministicDifferentSeedsDiffer(t *testing.T) { - newSeq := func(seed uint64) string { - c := clock.NewSimulated(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)) - g := NewGenerator(c, NewDeterministic(seed, seed)) - got, err := GenerateRunID(g) - require.NoError(t, err) - return got.String() - } - - assert.NotEqual(t, newSeq(1), newSeq(2)) -} - -// failingSource always reports an error, for testing that Generate -// propagates a Source failure rather than falling back silently. -type failingSource struct{} - -func (failingSource) Entropy() ([10]byte, error) { - return [10]byte{}, assert.AnError -} - -// maxEntropySource always returns the maximum representable entropy value, -// so the very next same-millisecond Generate call is guaranteed to -// overflow when incrementing it. -type maxEntropySource struct{} - -func (maxEntropySource) Entropy() ([10]byte, error) { - var b [10]byte - for i := range b { - b[i] = 0xFF - } - return b, nil -} - -// stepClock is a clock.Clock returning each of times in order, one per -// Now() call, for testing exact sequences a Simulated clock cannot produce -// on its own (like time moving backward). -type stepClock struct { - times []time.Time - next int -} - -func (c *stepClock) Now() time.Time { - t := c.times[c.next] - c.next++ - return t -} - -func (c *stepClock) NewTimer(d time.Duration) clock.Timer { - panic("not implemented") -} diff --git a/_archive/internal/id/id.go b/_archive/internal/id/id.go deleted file mode 100644 index 4a2cabad..00000000 --- a/_archive/internal/id/id.go +++ /dev/null @@ -1,98 +0,0 @@ -package id - -import ( - "fmt" - "strings" - "time" - - "github.com/rustyeddy/trader/internal/id/internal/ulid" -) - -// ID is a Trader-owned identifier of kind K. RunID, OrderID, and the other -// aliases in kind.go are each a distinct instantiation of this generic -// type, giving compile-time distinctness between kinds without hand-writing -// ten nearly identical types. Its representation — a 128-bit ULID value — -// is unexported; callers can never construct one holding an arbitrary or -// invalid value, only through Parse, MustParse, or a Generator. -// -// The zero value of ID is not a valid identifier: it is treated as unset, -// not as the identifier that happens to encode sixteen zero bytes. IsZero -// reports true for it, String names it visibly rather than returning -// something that could pass for real output, and marshaling it fails. -// Parse rejects any input that would decode to the all-zero value for the -// same reason: that bit pattern is reserved for "unset," never assigned to -// a real identifier. -type ID[K Kind] struct { - value [16]byte - set bool -} - -// String returns id's canonical text form: "_<26-character -// Crockford Base32>", for example "run_01J8Z3K3R2N4XG9YB6HFA1V7ZQ". The -// zero value renders as "" rather than an empty or otherwise -// plausible-looking string; see MarshalText for the form used at -// serialization boundaries, which rejects the zero value outright instead -// of rendering it as text at all. -func (id ID[K]) String() string { - if !id.set { - return "" - } - var k K - return k.Prefix() + "_" + ulid.Encode(id.value) -} - -// IsZero reports whether id is the unset zero value. -func (id ID[K]) IsZero() bool { - return !id.set -} - -// Equal reports whether id and o hold the identical value. Two zero values -// are equal to each other. -func (id ID[K]) Equal(o ID[K]) bool { - return id.set == o.set && id.value == o.value -} - -// Time returns the creation instant encoded in id, in UTC. It reports -// ErrZeroValue if id is the zero value. -func (id ID[K]) Time() (time.Time, error) { - if !id.set { - return time.Time{}, ErrZeroValue - } - return ulid.Timestamp(id.value), nil -} - -// Parse validates s as a canonical ID[K] string — the correct kind prefix -// followed by a well-formed, non-zero ULID body — and returns the -// identifier it encodes. Malformed input, a wrong prefix, and a body that -// decodes to the reserved all-zero value are all rejected with -// ErrInvalidID; nothing is repaired or guessed. -func Parse[K Kind](s string) (ID[K], error) { - var k K - prefix := k.Prefix() - - rest, ok := strings.CutPrefix(s, prefix+"_") - if !ok { - return ID[K]{}, fmt.Errorf("%w: %q does not have the %q prefix", ErrInvalidID, s, prefix) - } - - v, err := ulid.Decode(rest) - if err != nil { - return ID[K]{}, fmt.Errorf("%w: %v", ErrInvalidID, err) - } - if v == ([16]byte{}) { - return ID[K]{}, fmt.Errorf("%w: the all-zero value is reserved for the unset zero value", ErrInvalidID) - } - - return ID[K]{value: v, set: true}, nil -} - -// MustParse is like Parse but panics on error. It is intended for -// programmer-controlled constants, fixtures, and tests, not for parsing -// external or generated input. -func MustParse[K Kind](s string) ID[K] { - v, err := Parse[K](s) - if err != nil { - panic(err) - } - return v -} diff --git a/_archive/internal/id/id_test.go b/_archive/internal/id/id_test.go deleted file mode 100644 index 5380ba67..00000000 --- a/_archive/internal/id/id_test.go +++ /dev/null @@ -1,143 +0,0 @@ -package id - -import ( - "strings" - "testing" - - "github.com/rustyeddy/trader/internal/id/internal/ulid" - "github.com/stretchr/testify/assert" - "github.com/stretchr/testify/require" -) - -func TestKindPrefixes(t *testing.T) { - // These are a public contract embedded in every ID string ever issued; - // pin them so a change is a visible, deliberate diff. - tests := []struct { - kind Kind - prefix string - }{ - {runKind{}, "run"}, - {orderKind{}, "ord"}, - {fillKind{}, "fil"}, - {eventKind{}, "evt"}, - {correlationKind{}, "cor"}, - {accountKind{}, "acc"}, - {intentKind{}, "int"}, - } - for _, tt := range tests { - assert.Equal(t, tt.prefix, tt.kind.Prefix()) - } -} - -func TestDistinctKindsAreDistinctTypes(t *testing.T) { - // This is a compile-time property, not a runtime one: the test itself - // IS the assertion. If RunID and OrderID were assignable to each other, - // this file would fail to compile. - var run RunID - var order OrderID - _ = run - _ = order - - // The following would not compile if uncommented, which is the point: - // run = order -} - -func TestParseValidRoundTrips(t *testing.T) { - for i := range 5 { - valid := MustParseRunID(genValidRunID(t, byte(i+1))) - again, err := ParseRunID(valid.String()) - require.NoError(t, err) - assert.True(t, valid.Equal(again)) - } -} - -func TestParseRejectsWrongPrefix(t *testing.T) { - orderStr := genValidID(t, "ord", 1) - _, err := ParseRunID(orderStr) - require.ErrorIs(t, err, ErrInvalidID) -} - -func TestParseRejectsMalformedBody(t *testing.T) { - tests := []struct { - name string - in string - }{ - {name: "empty", in: ""}, - {name: "prefix only", in: "run_"}, - {name: "no separator", in: "run01H8Z3K3R2N4XG9YB6HFA1V7ZQ"}, - {name: "wrong length body", in: "run_TOOSHORT"}, - {name: "invalid character", in: "run_I1H8Z3K3R2N4XG9YB6HFA1V7ZQ"}, - {name: "no prefix at all", in: "01H8Z3K3R2N4XG9YB6HFA1V7ZQ"}, - } - for _, tt := range tests { - t.Run(tt.name, func(t *testing.T) { - _, err := ParseRunID(tt.in) - require.ErrorIs(t, err, ErrInvalidID) - }) - } -} - -func TestParseRejectsAllZeroBody(t *testing.T) { - // The all-zero value is reserved for the unset zero value; it must - // never be accepted as a real, parsed identifier. - zeroBody := strings.Repeat("0", 26) - _, err := ParseRunID("run_" + zeroBody) - require.ErrorIs(t, err, ErrInvalidID) -} - -func TestMustParsePanicsOnInvalidInput(t *testing.T) { - assert.Panics(t, func() { MustParseRunID("not-a-valid-id") }) -} - -func TestZeroValueIsZero(t *testing.T) { - var r RunID - assert.True(t, r.IsZero()) - assert.Equal(t, "", r.String()) -} - -func TestNonZeroValueIsNotZero(t *testing.T) { - r := MustParseRunID(genValidRunID(t, 1)) - assert.False(t, r.IsZero()) -} - -func TestEqual(t *testing.T) { - a := MustParseRunID(genValidRunID(t, 1)) - b := MustParseRunID(a.String()) - c := MustParseRunID(genValidRunID(t, 2)) - - assert.True(t, a.Equal(b)) - assert.False(t, a.Equal(c)) - - var zero1, zero2 RunID - assert.True(t, zero1.Equal(zero2), "two zero values are equal to each other") - assert.False(t, a.Equal(zero1)) -} - -func TestTimeErrorsOnZeroValue(t *testing.T) { - var r RunID - _, err := r.Time() - require.ErrorIs(t, err, ErrZeroValue) -} - -func TestTimeReturnsEncodedInstant(t *testing.T) { - r := MustParseRunID(genValidRunID(t, 1)) - got, err := r.Time() - require.NoError(t, err) - assert.False(t, got.IsZero()) -} - -// genValidRunID and genValidID build a syntactically valid ID string -// directly from the ulid encoding, varying one byte so distinct calls -// produce distinct identifiers, without depending on the Generator this -// test file's phase does not yet cover. -func genValidRunID(t *testing.T, b byte) string { - t.Helper() - return genValidID(t, "run", b) -} - -func genValidID(t *testing.T, prefix string, b byte) string { - t.Helper() - var v [16]byte - v[15] = b - return prefix + "_" + ulid.Encode(v) -} 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/_archive/internal/id/errors.go b/internal/id/errors.go similarity index 75% rename from _archive/internal/id/errors.go rename to internal/id/errors.go index 958c98ce..013ee1dc 100644 --- a/_archive/internal/id/errors.go +++ b/internal/id/errors.go @@ -4,8 +4,8 @@ import "errors" var ( // ErrInvalidID reports text that is not a well-formed identifier of the - // requested kind: wrong prefix, malformed ULID body, or a body that - // decodes to the reserved all-zero value. + // 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 diff --git a/internal/id/generate.go b/internal/id/generate.go new file mode 100644 index 00000000..4237e752 --- /dev/null +++ b/internal/id/generate.go @@ -0,0 +1,104 @@ +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 +} + +// ErrClockMovedBackward reports that a Generator saw its clock return an earlier +// time than one it had already used for an identifier. The wall clock can do this, +// briefly, after an adjustment; Generate says so rather than silently reusing or +// ignoring the earlier time. +var ErrClockMovedBackward = errors.New("id: clock moved backward") + +// 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. +// +// 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, and ErrClockMovedBackward if the clock went back. Neither falls +// back to weaker behavior silently. +func (g *Generator) RunID() (RunID, error) { + g.mu.Lock() + defer g.mu.Unlock() + + ms := g.now().UnixMilli() + + var rnd [10]byte + switch { + case !g.hasLast || ms > g.lastMS: + r, err := g.source.Entropy() + if err != nil { + return RunID{}, err + } + rnd = r + case ms == g.lastMS: + next, overflowed := ulid.IncrementEntropy(g.lastRand) + if overflowed { + return RunID{}, ErrEntropyExhausted + } + rnd = next + default: + return RunID{}, ErrClockMovedBackward + } + + 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..fe66ecb6 --- /dev/null +++ b/internal/id/generate_test.go @@ -0,0 +1,135 @@ +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_ReportsClockMovedBackward(t *testing.T) { + times := []time.Time{t0.Add(time.Millisecond), t0} + g := NewGenerator(func() time.Time { t := times[0]; times = times[1:]; return t }, Random{}) + + _, err := g.RunID() + require.NoError(t, err) + _, err = g.RunID() + require.ErrorIs(t, err, ErrClockMovedBackward) +} + +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/_archive/internal/id/internal/ulid/ulid.go b/internal/id/internal/ulid/ulid.go similarity index 100% rename from _archive/internal/id/internal/ulid/ulid.go rename to internal/id/internal/ulid/ulid.go diff --git a/_archive/internal/id/internal/ulid/ulid_test.go b/internal/id/internal/ulid/ulid_test.go similarity index 100% rename from _archive/internal/id/internal/ulid/ulid_test.go rename to internal/id/internal/ulid/ulid_test.go 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)) +} From d511c26bee72ee9fde75b6ace3672343110fd36f Mon Sep 17 00:00:00 2001 From: Rusty Eddy Date: Sat, 21 Nov 2026 12:19:12 -0800 Subject: [PATCH 2/2] Keep the archive untouched; a backward clock continues from the last millisecond (#702) The port copies instead of moving, so _archive/internal/id is as it was. The Generator no longer fails when the clock steps back: it carries on from the last millisecond it used, so a run can always get an ID and IDs still sort in order. ErrClockMovedBackward is gone. Co-Authored-By: Claude Sonnet 5.5 --- _archive/internal/id/deterministic.go | 41 +++ _archive/internal/id/doc.go | 126 ++++++++++ _archive/internal/id/encoding.go | 49 ++++ _archive/internal/id/encoding_test.go | 100 ++++++++ _archive/internal/id/errors.go | 14 ++ _archive/internal/id/generate.go | 114 +++++++++ _archive/internal/id/generate_test.go | 238 ++++++++++++++++++ _archive/internal/id/id.go | 98 ++++++++ _archive/internal/id/id_test.go | 143 +++++++++++ _archive/internal/id/internal/ulid/ulid.go | 177 +++++++++++++ .../internal/id/internal/ulid/ulid_test.go | 227 +++++++++++++++++ internal/id/generate.go | 21 +- internal/id/generate_test.go | 24 +- 13 files changed, 1355 insertions(+), 17 deletions(-) create mode 100644 _archive/internal/id/deterministic.go create mode 100644 _archive/internal/id/doc.go create mode 100644 _archive/internal/id/encoding.go create mode 100644 _archive/internal/id/encoding_test.go create mode 100644 _archive/internal/id/errors.go create mode 100644 _archive/internal/id/generate.go create mode 100644 _archive/internal/id/generate_test.go create mode 100644 _archive/internal/id/id.go create mode 100644 _archive/internal/id/id_test.go create mode 100644 _archive/internal/id/internal/ulid/ulid.go create mode 100644 _archive/internal/id/internal/ulid/ulid_test.go diff --git a/_archive/internal/id/deterministic.go b/_archive/internal/id/deterministic.go new file mode 100644 index 00000000..1fee4654 --- /dev/null +++ b/_archive/internal/id/deterministic.go @@ -0,0 +1,41 @@ +package id + +import ( + "math/rand/v2" + "sync" +) + +// Deterministic is an EntropySource that draws entropy from a seeded PRNG, +// for tests and replay: given the same seed, it produces the same sequence of +// entropy values every time, so — combined with a clock.Simulated — a +// Generator using it produces the same sequence of identifiers every time, +// satisfying issue #24's "deterministic generation produces reproducible +// sequences" requirement. +// +// Deterministic must never be used in production: its entropy is +// reproducible by construction, which is exactly what production +// identifiers must not be. +type Deterministic struct { + mu sync.Mutex + rng *rand.Rand +} + +// NewDeterministic returns a Deterministic source seeded with seed1 and +// seed2 — the same two-value seed shape math/rand/v2's PCG source itself +// takes, exposed directly rather than derived from a single value, so the +// seed a caller passes is exactly the seed that determines the sequence. +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/_archive/internal/id/doc.go b/_archive/internal/id/doc.go new file mode 100644 index 00000000..1e7f562c --- /dev/null +++ b/_archive/internal/id/doc.go @@ -0,0 +1,126 @@ +// Package id implements Trader-owned identifiers and correlation metadata, +// as decided by issue #24 (M1-06). +// +// # Seven identifier kinds +// +// RunID, OrderID, FillID, EventID, CorrelationID, AccountID, and IntentID +// are each a distinct Go type — a RunID can never be assigned where an +// OrderID is expected, caught at compile time, not at runtime. Internally +// they share one generic implementation (ID[K], in id.go) rather than +// seven hand-copied ones, but nothing about that is visible at a call +// site: id.RunID is used exactly like any other named type. +// +// This is deliberately fewer kinds than issue #24 originally proposed; see +// "Deferred identifiers" below for which ones were cut, and why. +// +// Each kind's canonical string form carries a short prefix identifying it — +// "run_01J8Z3K3R2N4XG9YB6HFA1V7ZQ", "ord_01J8Z3K5H7T1MDCE9WNRP2VXY0" — so a +// stray ID string in a log line or database column is identifiable on +// sight, without cross-referencing code. The 26 characters after the +// prefix are a ULID (https://github.com/ulid/spec): a 48-bit millisecond +// timestamp followed by 80 bits of entropy, Crockford Base32 encoded. ULID +// is an internal encoding choice — see id/internal/ulid — never a public +// dependency; nothing in this package's exported API exposes a raw ULID +// value, a third-party ULID type, or the underlying [16]byte +// representation. +// +// # Construction +// +// Parse and the concrete Parse functions (ParseRunID, ParseOrderID, +// ...) validate external or persisted text. Generate and the concrete +// Generate functions produce new identifiers from a Generator. There +// is no way to construct a non-zero ID holding an arbitrary value: every +// path validates the kind prefix and the ULID body, or comes from a +// Generator that owns real entropy and a real clock. +// +// # Trader-owned versus broker-native identifiers +// +// A broker's own identifier for an order, account, or fill is not an +// id.OrderID or id.AccountID: broker identifiers are opaque strings with +// no ULID structure. Parsing one as a Trader ID simply fails — that +// structural rejection is what keeps the two from being confused, rather +// than a parallel BrokerOrderID type defined here. Packages that talk to a +// specific broker define their own native-identifier types (BrokerOrderID, +// BrokerAccountID, ...) alongside whatever mapping they need between the +// two; that mapping is a broker-adapter concern, not this package's. +// +// # AccountID has a different lifecycle +// +// Every other kind is generated fresh for the event it identifies: a new +// RunID per run, a new OrderID per order. AccountID is not: it is +// generated once when the account entity is created and then persisted +// for that account's lifetime, never regenerated on a later run. +// +// # Deferred identifiers +// +// Issue #24 originally proposed SessionID, IntentID, ProposalID, and +// InstrumentID alongside the six kinds this package originally exported. +// They were cut from the initial scope on review, using this rule of +// thumb: would two otherwise-identical instances of this thing ever need +// to coexist and be distinguished by Trader? That is clearly true for +// runs, orders, fills, and accounts. It was not yet true for sessions, +// intents, and proposals — none of those had a concrete, persisted +// domain object in the codebase yet to justify a generated identity for. +// They were to be added, alongside their corresponding domain objects, +// when that changed. +// +// IntentID was the first of the three to have that domain object appear: +// issue #177 (M4-02) introduced order.Intent, so IntentID was reinstated +// alongside it. SessionID and ProposalID remain deferred for the same +// reason IntentID originally was — no concrete Session or order.Proposal +// identity exists to distinguish yet (order.Proposal itself exists, per +// ADR-017, but nothing has yet needed to tell two Proposals apart by a +// generated identity rather than by the values they carry). +// +// InstrumentID was cut for a different reason: an instrument has a +// natural, canonical identity (EUR/USD, an exchange/symbol/asset triple, +// ...), not an arbitrary generated one. A ULID-based InstrumentID would +// have given EUR/USD a fresh identity every run, which is exactly wrong. +// Instrument identity is expected to come from a canonical instrument +// registry once the architecture document's instrument package exists, +// not from this package. +// +// # Generation +// +// Generator produces monotonic ULIDs from an injected clock.Clock and an +// entropy EntropySource, per ADR-015: it never calls time.Now itself. +// Multiple identifiers generated within the same millisecond receive +// strictly increasing entropy rather than fresh random values, preserving +// lexicographic sort order at millisecond resolution; see generate.go. +// Random is the production EntropySource; Deterministic is a seeded, +// injectable EntropySource for tests and replay — given the same simulated +// clock and seed, it produces the same sequence of identifiers every time. +// (EntropySource, not Source: Source is a separate type below, for +// Metadata's originating-component label — the two are unrelated despite +// the similar name.) +// +// # Zero value +// +// The zero value of every ID kind is unset, not the identifier that +// happens to encode sixteen zero bytes: IsZero reports true for it, +// String names it visibly ("") instead of returning something +// that could pass for real output, and MarshalText/MarshalJSON reject it +// outright. Parse rejects any input that would decode to the all-zero +// value for the same reason — that bit pattern is permanently reserved for +// "unset." +// +// # Correlation metadata +// +// Metadata bundles the fields needed to trace one identifier through a +// multi-stage workflow: EventID identifies this event, CorrelationID is +// shared across every stage of the workflow, CausationID names the +// specific EventID that directly caused this one, Timestamp is the +// canonical UTC event time, and Source names the originating component. +// A typical intent-to-fill chain shares one CorrelationID throughout while +// each stage's CausationID points at the EventID immediately before it: +// +// Intent: correlation = workflow ID, causation = zero (nothing caused it) +// Proposal: correlation = same workflow ID, causation = intent's EventID +// Order: correlation = same workflow ID, causation = proposal's EventID +// Fill: correlation = same workflow ID, causation = order's EventID +// +// See metadata.go. +// +// This package is private to Trader's runtime (ADR-065); it is not part of +// the supported external strategy/research Go API. +package id diff --git a/_archive/internal/id/encoding.go b/_archive/internal/id/encoding.go new file mode 100644 index 00000000..84f11395 --- /dev/null +++ b/_archive/internal/id/encoding.go @@ -0,0 +1,49 @@ +package id + +import "encoding/json" + +// MarshalText implements encoding.TextMarshaler, encoding id as its +// canonical text form. +// +// MarshalText reports ErrZeroValue for the zero value rather than emitting +// an empty or placeholder string: the zero value is not a real identifier, +// and a caller that forgot to set one deserves an error here, not a +// silently empty field on the wire. +func (id ID[K]) MarshalText() ([]byte, error) { + if !id.set { + return nil, ErrZeroValue + } + return []byte(id.String()), nil +} + +// UnmarshalText implements encoding.TextUnmarshaler. +func (id *ID[K]) UnmarshalText(text []byte) error { + v, err := Parse[K](string(text)) + if err != nil { + return err + } + *id = v + return nil +} + +// MarshalJSON implements json.Marshaler, encoding id as a JSON string +// holding its canonical text form. +// +// MarshalJSON reports ErrZeroValue for the zero value, for the same reason +// as MarshalText. +func (id ID[K]) MarshalJSON() ([]byte, error) { + if !id.set { + return nil, ErrZeroValue + } + return json.Marshal(id.String()) +} + +// UnmarshalJSON implements json.Unmarshaler, decoding a JSON string holding +// an identifier's canonical text form. +func (id *ID[K]) 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/_archive/internal/id/encoding_test.go b/_archive/internal/id/encoding_test.go new file mode 100644 index 00000000..77444e30 --- /dev/null +++ b/_archive/internal/id/encoding_test.go @@ -0,0 +1,100 @@ +package id + +import ( + "encoding/json" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestTextRoundTrip(t *testing.T) { + want := MustParseRunID(genValidRunID(t, 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)) +} + +func TestMarshalTextRejectsZeroValue(t *testing.T) { + var zero RunID + _, err := zero.MarshalText() + require.ErrorIs(t, err, ErrZeroValue) +} + +func TestUnmarshalTextRejectsInvalidInput(t *testing.T) { + var r RunID + err := r.UnmarshalText([]byte("not-a-valid-id")) + require.ErrorIs(t, err, ErrInvalidID) +} + +func TestUnmarshalTextRejectsWrongKindPrefix(t *testing.T) { + orderStr := genValidID(t, "ord", 1) + var r RunID + err := r.UnmarshalText([]byte(orderStr)) + require.ErrorIs(t, err, ErrInvalidID) +} + +func TestJSONRoundTrip(t *testing.T) { + want := MustParseOrderID(genValidID(t, "ord", 9)) + + data, err := json.Marshal(want) + require.NoError(t, err) + assert.JSONEq(t, `"`+want.String()+`"`, string(data)) + + var got OrderID + require.NoError(t, json.Unmarshal(data, &got)) + assert.True(t, want.Equal(got)) +} + +func TestMarshalJSONRejectsZeroValue(t *testing.T) { + var zero OrderID + _, err := json.Marshal(zero) + require.Error(t, err) +} + +func TestUnmarshalJSONRejectsMalformedInput(t *testing.T) { + var r RunID + err := json.Unmarshal([]byte(`"not-a-valid-id"`), &r) + require.ErrorIs(t, err, ErrInvalidID) +} + +func TestUnmarshalJSONRejectsNonStringValue(t *testing.T) { + var r RunID + err := json.Unmarshal([]byte(`12345`), &r) + require.Error(t, err) +} + +// TestNoRawBytesInJSON pins ADR-style expectations shared with num/config: +// every field marshals as a string, never as a raw number or byte array +// that would expose the [16]byte representation. +func TestNoRawBytesInJSON(t *testing.T) { + want := MustParseRunID(genValidRunID(t, 3)) + + data, err := json.Marshal(want) + require.NoError(t, err) + + var raw any + require.NoError(t, json.Unmarshal(data, &raw)) + _, isString := raw.(string) + assert.True(t, isString, "marshaled ID must be a JSON string, got %T", raw) +} + +func TestJSONFieldRoundTripInStruct(t *testing.T) { + type wrapper struct { + ID OrderID `json:"id"` + } + + want := wrapper{ID: MustParseOrderID(genValidID(t, "ord", 4))} + + data, err := json.Marshal(want) + require.NoError(t, err) + + var got wrapper + require.NoError(t, json.Unmarshal(data, &got)) + assert.True(t, want.ID.Equal(got.ID)) +} diff --git a/_archive/internal/id/errors.go b/_archive/internal/id/errors.go new file mode 100644 index 00000000..958c98ce --- /dev/null +++ b/_archive/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 + // requested kind: 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/_archive/internal/id/generate.go b/_archive/internal/id/generate.go new file mode 100644 index 00000000..90fb4c88 --- /dev/null +++ b/_archive/internal/id/generate.go @@ -0,0 +1,114 @@ +package id + +import ( + "crypto/rand" + "errors" + "fmt" + "sync" + + "github.com/rustyeddy/trader/internal/clock" + "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 +} + +// ErrClockMovedBackward reports that a Generator observed its clock produce +// an earlier timestamp than one it had already used to generate an +// identifier. A Simulated clock cannot do this — ADR-015 has Advance +// reject a negative duration — but a Real clock can, briefly, after a wall- +// clock adjustment; Generate reports this rather than silently reusing or +// ignoring the earlier timestamp. +var ErrClockMovedBackward = errors.New("id: clock moved backward") + +// ErrEntropyExhausted reports that a Generator produced 2^80 identifiers +// within a single millisecond and cannot produce another monotonically +// increasing one without either waiting for the next millisecond or +// drawing fresh, non-monotonic entropy — something Generate never does +// silently. +var ErrEntropyExhausted = errors.New("id: entropy exhausted within one millisecond") + +// Generator produces monotonic Trader-owned identifiers from an injected +// clock.Clock and entropy EntropySource, per ADR-015: it never calls +// time.Now itself. Multiple identifiers generated within the same millisecond +// receive strictly increasing entropy rather than fresh random values — +// the ULID spec's monotonic generation guidance — so their lexicographic +// sort order matches creation order at millisecond resolution. +// +// Generator owns its own synchronization; a *Generator is safe for +// concurrent use, and every generated identifier's uniqueness and +// ordering guarantees hold across goroutines sharing one Generator, not +// just within a single goroutine's calls to it. +type Generator struct { + clock clock.Clock + source EntropySource + + mu sync.Mutex + hasLast bool + lastMS int64 + lastRand [10]byte +} + +// NewGenerator returns a Generator that timestamps identifiers using c and +// draws entropy from source. +func NewGenerator(c clock.Clock, source EntropySource) *Generator { + return &Generator{clock: c, source: source} +} + +// Generate produces a new identifier of kind K. +// +// Generate returns ErrEntropyExhausted if it has already produced 2^80 +// identifiers within the current millisecond, and ErrClockMovedBackward if +// g's clock reports a time earlier than one it has already used. Neither +// falls back to weaker behavior silently. +func Generate[K Kind](g *Generator) (ID[K], error) { + g.mu.Lock() + defer g.mu.Unlock() + + ms := g.clock.Now().UnixMilli() + + var rnd [10]byte + switch { + case !g.hasLast || ms > g.lastMS: + r, err := g.source.Entropy() + if err != nil { + return ID[K]{}, err + } + rnd = r + case ms == g.lastMS: + next, overflowed := ulid.IncrementEntropy(g.lastRand) + if overflowed { + return ID[K]{}, ErrEntropyExhausted + } + rnd = next + default: + return ID[K]{}, ErrClockMovedBackward + } + + v, err := ulid.New(ms, rnd) + if err != nil { + return ID[K]{}, err + } + + g.lastMS = ms + g.lastRand = rnd + g.hasLast = true + + return ID[K]{value: v, set: true}, nil +} diff --git a/_archive/internal/id/generate_test.go b/_archive/internal/id/generate_test.go new file mode 100644 index 00000000..52e932da --- /dev/null +++ b/_archive/internal/id/generate_test.go @@ -0,0 +1,238 @@ +package id + +import ( + "strings" + "testing" + "time" + + "github.com/rustyeddy/trader/internal/clock" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestRandomEntropyIsNonZeroAndVaries(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 producing all zero bytes is astronomically unlikely") + assert.NotEqual(t, a, b, "two draws should not collide") +} + +func TestGenerateProducesParsableID(t *testing.T) { + c := clock.NewSimulated(time.Now()) + g := NewGenerator(c, NewDeterministic(1, 2)) + + got, err := GenerateRunID(g) + require.NoError(t, err) + assert.False(t, got.IsZero()) + + again, err := ParseRunID(got.String()) + require.NoError(t, err) + assert.True(t, got.Equal(again)) +} + +func TestGenerateEmbedsClockTimestamp(t *testing.T) { + start := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC) + c := clock.NewSimulated(start) + g := NewGenerator(c, NewDeterministic(1, 2)) + + got, err := GenerateRunID(g) + require.NoError(t, err) + + embedded, err := got.Time() + require.NoError(t, err) + assert.True(t, embedded.Equal(start)) +} + +func TestGenerateDifferentKindsProduceDifferentPrefixedStrings(t *testing.T) { + c := clock.NewSimulated(time.Now()) + g := NewGenerator(c, NewDeterministic(1, 2)) + + run, err := GenerateRunID(g) + require.NoError(t, err) + order, err := GenerateOrderID(g) + require.NoError(t, err) + + assert.True(t, strings.HasPrefix(run.String(), "run_")) + assert.True(t, strings.HasPrefix(order.String(), "ord_")) +} + +func TestGenerateSameMillisecondIsMonotonicallyIncreasing(t *testing.T) { + // A Simulated clock that is never advanced makes every call within this + // test land on the same millisecond, forcing the monotonic-entropy + // path deterministically instead of hoping wall-clock timing happens to + // line up. + c := clock.NewSimulated(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)) + g := NewGenerator(c, NewDeterministic(1, 2)) + + var prev RunID + for i := range 100 { + got, err := GenerateRunID(g) + require.NoError(t, err) + + if i > 0 { + assert.Less(t, prev.String(), got.String(), + "identifiers generated within the same millisecond must sort strictly increasing") + } + prev = got + } +} + +func TestGenerateAcrossAdvancingMillisecondsStaysOrdered(t *testing.T) { + c := clock.NewSimulated(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)) + g := NewGenerator(c, NewDeterministic(1, 2)) + + var prev RunID + for i := range 20 { + if i > 0 { + require.NoError(t, c.Advance(time.Millisecond)) + } + got, err := GenerateRunID(g) + require.NoError(t, err) + + if i > 0 { + assert.Less(t, prev.String(), got.String()) + } + prev = got + } +} + +func TestGenerateReportsEntropySourceError(t *testing.T) { + c := clock.NewSimulated(time.Now()) + g := NewGenerator(c, failingSource{}) + + _, err := GenerateRunID(g) + require.Error(t, err) +} + +func TestGenerateReportsEntropyExhaustion(t *testing.T) { + c := clock.NewSimulated(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)) + g := NewGenerator(c, maxEntropySource{}) + + // First call draws fresh entropy (all 0xFF from this fixed source); + // the second, still within the same millisecond, must increment past + // the maximum representable value and report exhaustion rather than + // silently wrapping around to zero and losing monotonicity. + _, err := GenerateRunID(g) + require.NoError(t, err) + + _, err = GenerateRunID(g) + require.ErrorIs(t, err, ErrEntropyExhausted) +} + +func TestGenerateReportsClockMovedBackward(t *testing.T) { + g := &Generator{clock: &stepClock{times: []time.Time{ + time.Date(2026, 1, 1, 0, 0, 0, 1_000_000, time.UTC), // .001s + time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC), // .000s -- earlier + }}, source: Random{}} + + _, err := GenerateRunID(g) + require.NoError(t, err) + + _, err = GenerateRunID(g) + require.ErrorIs(t, err, ErrClockMovedBackward) +} + +func TestGeneratorConcurrentUseProducesUniqueIDs(t *testing.T) { + c := clock.NewSimulated(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)) + g := NewGenerator(c, NewDeterministic(1, 2)) + + const n = 200 + results := make(chan RunID, n) + errs := make(chan error, n) + + for range n { + go func() { + got, err := GenerateRunID(g) + results <- got + errs <- err + }() + } + + seen := make(map[string]bool, n) + for range n { + require.NoError(t, <-errs) + got := <-results + assert.False(t, seen[got.String()], "duplicate identifier generated under concurrent use") + seen[got.String()] = true + } +} + +// TestDeterministicReproducesSequence is the concrete proof behind issue +// #24's "deterministic generation produces reproducible sequences" +// acceptance criterion: the same seed and the same simulated clock produce +// the exact same sequence of identifiers, every time. +func TestDeterministicReproducesSequence(t *testing.T) { + run := func() []string { + c := clock.NewSimulated(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)) + g := NewGenerator(c, NewDeterministic(42, 7)) + + out := make([]string, 10) + for i := range out { + require.NoError(t, c.Advance(time.Millisecond)) + got, err := GenerateRunID(g) + require.NoError(t, err) + out[i] = got.String() + } + return out + } + + first := run() + second := run() + assert.Equal(t, first, second) +} + +func TestDeterministicDifferentSeedsDiffer(t *testing.T) { + newSeq := func(seed uint64) string { + c := clock.NewSimulated(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)) + g := NewGenerator(c, NewDeterministic(seed, seed)) + got, err := GenerateRunID(g) + require.NoError(t, err) + return got.String() + } + + assert.NotEqual(t, newSeq(1), newSeq(2)) +} + +// failingSource always reports an error, for testing that Generate +// propagates a Source failure rather than falling back silently. +type failingSource struct{} + +func (failingSource) Entropy() ([10]byte, error) { + return [10]byte{}, assert.AnError +} + +// maxEntropySource always returns the maximum representable entropy value, +// so the very next same-millisecond Generate call is guaranteed to +// overflow when incrementing it. +type maxEntropySource struct{} + +func (maxEntropySource) Entropy() ([10]byte, error) { + var b [10]byte + for i := range b { + b[i] = 0xFF + } + return b, nil +} + +// stepClock is a clock.Clock returning each of times in order, one per +// Now() call, for testing exact sequences a Simulated clock cannot produce +// on its own (like time moving backward). +type stepClock struct { + times []time.Time + next int +} + +func (c *stepClock) Now() time.Time { + t := c.times[c.next] + c.next++ + return t +} + +func (c *stepClock) NewTimer(d time.Duration) clock.Timer { + panic("not implemented") +} diff --git a/_archive/internal/id/id.go b/_archive/internal/id/id.go new file mode 100644 index 00000000..4a2cabad --- /dev/null +++ b/_archive/internal/id/id.go @@ -0,0 +1,98 @@ +package id + +import ( + "fmt" + "strings" + "time" + + "github.com/rustyeddy/trader/internal/id/internal/ulid" +) + +// ID is a Trader-owned identifier of kind K. RunID, OrderID, and the other +// aliases in kind.go are each a distinct instantiation of this generic +// type, giving compile-time distinctness between kinds without hand-writing +// ten nearly identical types. Its representation — a 128-bit ULID value — +// is unexported; callers can never construct one holding an arbitrary or +// invalid value, only through Parse, MustParse, or a Generator. +// +// The zero value of ID is not a valid identifier: it is treated as unset, +// not as the identifier that happens to encode sixteen zero bytes. IsZero +// reports true for it, String names it visibly rather than returning +// something that could pass for real output, and marshaling it fails. +// Parse rejects any input that would decode to the all-zero value for the +// same reason: that bit pattern is reserved for "unset," never assigned to +// a real identifier. +type ID[K Kind] struct { + value [16]byte + set bool +} + +// String returns id's canonical text form: "_<26-character +// Crockford Base32>", for example "run_01J8Z3K3R2N4XG9YB6HFA1V7ZQ". The +// zero value renders as "" rather than an empty or otherwise +// plausible-looking string; see MarshalText for the form used at +// serialization boundaries, which rejects the zero value outright instead +// of rendering it as text at all. +func (id ID[K]) String() string { + if !id.set { + return "" + } + var k K + return k.Prefix() + "_" + ulid.Encode(id.value) +} + +// IsZero reports whether id is the unset zero value. +func (id ID[K]) IsZero() bool { + return !id.set +} + +// Equal reports whether id and o hold the identical value. Two zero values +// are equal to each other. +func (id ID[K]) Equal(o ID[K]) bool { + return id.set == o.set && id.value == o.value +} + +// Time returns the creation instant encoded in id, in UTC. It reports +// ErrZeroValue if id is the zero value. +func (id ID[K]) Time() (time.Time, error) { + if !id.set { + return time.Time{}, ErrZeroValue + } + return ulid.Timestamp(id.value), nil +} + +// Parse validates s as a canonical ID[K] string — the correct kind prefix +// followed by a well-formed, non-zero ULID body — and returns the +// identifier it encodes. Malformed input, a wrong prefix, and a body that +// decodes to the reserved all-zero value are all rejected with +// ErrInvalidID; nothing is repaired or guessed. +func Parse[K Kind](s string) (ID[K], error) { + var k K + prefix := k.Prefix() + + rest, ok := strings.CutPrefix(s, prefix+"_") + if !ok { + return ID[K]{}, fmt.Errorf("%w: %q does not have the %q prefix", ErrInvalidID, s, prefix) + } + + v, err := ulid.Decode(rest) + if err != nil { + return ID[K]{}, fmt.Errorf("%w: %v", ErrInvalidID, err) + } + if v == ([16]byte{}) { + return ID[K]{}, fmt.Errorf("%w: the all-zero value is reserved for the unset zero value", ErrInvalidID) + } + + return ID[K]{value: v, set: true}, nil +} + +// MustParse is like Parse but panics on error. It is intended for +// programmer-controlled constants, fixtures, and tests, not for parsing +// external or generated input. +func MustParse[K Kind](s string) ID[K] { + v, err := Parse[K](s) + if err != nil { + panic(err) + } + return v +} diff --git a/_archive/internal/id/id_test.go b/_archive/internal/id/id_test.go new file mode 100644 index 00000000..5380ba67 --- /dev/null +++ b/_archive/internal/id/id_test.go @@ -0,0 +1,143 @@ +package id + +import ( + "strings" + "testing" + + "github.com/rustyeddy/trader/internal/id/internal/ulid" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestKindPrefixes(t *testing.T) { + // These are a public contract embedded in every ID string ever issued; + // pin them so a change is a visible, deliberate diff. + tests := []struct { + kind Kind + prefix string + }{ + {runKind{}, "run"}, + {orderKind{}, "ord"}, + {fillKind{}, "fil"}, + {eventKind{}, "evt"}, + {correlationKind{}, "cor"}, + {accountKind{}, "acc"}, + {intentKind{}, "int"}, + } + for _, tt := range tests { + assert.Equal(t, tt.prefix, tt.kind.Prefix()) + } +} + +func TestDistinctKindsAreDistinctTypes(t *testing.T) { + // This is a compile-time property, not a runtime one: the test itself + // IS the assertion. If RunID and OrderID were assignable to each other, + // this file would fail to compile. + var run RunID + var order OrderID + _ = run + _ = order + + // The following would not compile if uncommented, which is the point: + // run = order +} + +func TestParseValidRoundTrips(t *testing.T) { + for i := range 5 { + valid := MustParseRunID(genValidRunID(t, byte(i+1))) + again, err := ParseRunID(valid.String()) + require.NoError(t, err) + assert.True(t, valid.Equal(again)) + } +} + +func TestParseRejectsWrongPrefix(t *testing.T) { + orderStr := genValidID(t, "ord", 1) + _, err := ParseRunID(orderStr) + require.ErrorIs(t, err, ErrInvalidID) +} + +func TestParseRejectsMalformedBody(t *testing.T) { + tests := []struct { + name string + in string + }{ + {name: "empty", in: ""}, + {name: "prefix only", in: "run_"}, + {name: "no separator", in: "run01H8Z3K3R2N4XG9YB6HFA1V7ZQ"}, + {name: "wrong length body", in: "run_TOOSHORT"}, + {name: "invalid character", in: "run_I1H8Z3K3R2N4XG9YB6HFA1V7ZQ"}, + {name: "no prefix at all", in: "01H8Z3K3R2N4XG9YB6HFA1V7ZQ"}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + _, err := ParseRunID(tt.in) + require.ErrorIs(t, err, ErrInvalidID) + }) + } +} + +func TestParseRejectsAllZeroBody(t *testing.T) { + // The all-zero value is reserved for the unset zero value; it must + // never be accepted as a real, parsed identifier. + zeroBody := strings.Repeat("0", 26) + _, err := ParseRunID("run_" + zeroBody) + require.ErrorIs(t, err, ErrInvalidID) +} + +func TestMustParsePanicsOnInvalidInput(t *testing.T) { + assert.Panics(t, func() { MustParseRunID("not-a-valid-id") }) +} + +func TestZeroValueIsZero(t *testing.T) { + var r RunID + assert.True(t, r.IsZero()) + assert.Equal(t, "", r.String()) +} + +func TestNonZeroValueIsNotZero(t *testing.T) { + r := MustParseRunID(genValidRunID(t, 1)) + assert.False(t, r.IsZero()) +} + +func TestEqual(t *testing.T) { + a := MustParseRunID(genValidRunID(t, 1)) + b := MustParseRunID(a.String()) + c := MustParseRunID(genValidRunID(t, 2)) + + assert.True(t, a.Equal(b)) + assert.False(t, a.Equal(c)) + + var zero1, zero2 RunID + assert.True(t, zero1.Equal(zero2), "two zero values are equal to each other") + assert.False(t, a.Equal(zero1)) +} + +func TestTimeErrorsOnZeroValue(t *testing.T) { + var r RunID + _, err := r.Time() + require.ErrorIs(t, err, ErrZeroValue) +} + +func TestTimeReturnsEncodedInstant(t *testing.T) { + r := MustParseRunID(genValidRunID(t, 1)) + got, err := r.Time() + require.NoError(t, err) + assert.False(t, got.IsZero()) +} + +// genValidRunID and genValidID build a syntactically valid ID string +// directly from the ulid encoding, varying one byte so distinct calls +// produce distinct identifiers, without depending on the Generator this +// test file's phase does not yet cover. +func genValidRunID(t *testing.T, b byte) string { + t.Helper() + return genValidID(t, "run", b) +} + +func genValidID(t *testing.T, prefix string, b byte) string { + t.Helper() + var v [16]byte + v[15] = b + return prefix + "_" + ulid.Encode(v) +} diff --git a/_archive/internal/id/internal/ulid/ulid.go b/_archive/internal/id/internal/ulid/ulid.go new file mode 100644 index 00000000..7e4f2e84 --- /dev/null +++ b/_archive/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/_archive/internal/id/internal/ulid/ulid_test.go b/_archive/internal/id/internal/ulid/ulid_test.go new file mode 100644 index 00000000..22e505c6 --- /dev/null +++ b/_archive/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/generate.go b/internal/id/generate.go index 4237e752..bcf0ed81 100644 --- a/internal/id/generate.go +++ b/internal/id/generate.go @@ -29,12 +29,6 @@ func (Random) Entropy() ([10]byte, error) { return b, nil } -// ErrClockMovedBackward reports that a Generator saw its clock return an earlier -// time than one it had already used for an identifier. The wall clock can do this, -// briefly, after an adjustment; Generate says so rather than silently reusing or -// ignoring the earlier time. -var ErrClockMovedBackward = errors.New("id: clock moved backward") - // 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") @@ -44,6 +38,11 @@ var ErrEntropyExhausted = errors.New("id: entropy exhausted within one milliseco // 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 { @@ -65,13 +64,15 @@ func NewGenerator(now func() time.Time, source EntropySource) *Generator { // RunID makes a new RunID. // // It returns ErrEntropyExhausted if it has already made 2^80 IDs in the current -// millisecond, and ErrClockMovedBackward if the clock went back. Neither falls -// back to weaker behavior silently. +// 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 { @@ -81,14 +82,12 @@ func (g *Generator) RunID() (RunID, error) { return RunID{}, err } rnd = r - case ms == g.lastMS: + default: // the same millisecond, or the clock went back to it next, overflowed := ulid.IncrementEntropy(g.lastRand) if overflowed { return RunID{}, ErrEntropyExhausted } rnd = next - default: - return RunID{}, ErrClockMovedBackward } v, err := ulid.New(ms, rnd) diff --git a/internal/id/generate_test.go b/internal/id/generate_test.go index fe66ecb6..31b6a89c 100644 --- a/internal/id/generate_test.go +++ b/internal/id/generate_test.go @@ -84,14 +84,26 @@ func TestGenerator_ReportsEntropyExhaustion(t *testing.T) { require.ErrorIs(t, err, ErrEntropyExhausted) } -func TestGenerator_ReportsClockMovedBackward(t *testing.T) { - times := []time.Time{t0.Add(time.Millisecond), t0} - g := NewGenerator(func() time.Time { t := times[0]; times = times[1:]; return t }, Random{}) +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)) - _, err := g.RunID() + 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) - _, err = g.RunID() - require.ErrorIs(t, err, ErrClockMovedBackward) + 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) {