Add per-checkpoint ref resolver (ShardFor + RefName/ParseRef) · Entire

Add per-checkpoint ref resolver (ShardFor + RefName/ParseRef)

be6c71f·

Soph·2w ago·4 files·+221 added/-0 removed

First slice of the per-checkpoint git-ref checkpoint store (#1471), on top of the merged understanding layer. Pure naming/resolution; nothing constructs a ref store yet.

Sessions

Changes

4

87 unmodified lines

// Kind classifies this checkpoint ID.
func (id CheckpointID) Kind() Kind {
    return KindOf(string(id))
}

// ShardFor returns the two-character shard for storing this ID under a
// per-checkpoint git ref (refs/entire/checkpoints/<shard>/<id>), chosen so
// checkpoints spread evenly across buckets:
//
//   - Legacy hex IDs shard on the FIRST two characters, preserving the existing
//     entire/checkpoints/v1 tree layout (see Path).
//   - ULIDs shard on the LAST two characters: a ULID's leading characters encode
//     its timestamp and barely vary between nearby checkpoints, while the trailing
//     characters are random, so the suffix spreads evenly while the ID itself
//     stays lexicographically sortable.
//
// For an ID shorter than two characters the whole ID is returned; an unrecognized
// ID falls back to the first-two (prefix) layout.
func (id CheckpointID) ShardFor() string {
    s := string(id)
    if len(s) < 2 {
        return s
    }
    if id.Kind() == KindULID {
        return s[len(s)-2:]
    }
    return s[:2]
}

// NewCheckpointID creates a CheckpointID from a string, validating its format.
// Returns an error unless the string is a valid checkpoint ID (12-char hex or ULID).
func NewCheckpointID(s string) (CheckpointID, error) {

144 unmodified lines

// CheckpointRefPrefix is the namespace under which the git-refs backend stores
// one ref per checkpoint: refs/entire/checkpoints/<shard>/<id>. Each ref points
// at a checkpoint commit whose tree root is that checkpoint's contents. This is
// distinct from the git-branch backend's single entire/checkpoints/v1 branch.
const CheckpointRefPrefix = "refs/entire/checkpoints/"

// RefName returns the per-checkpoint git ref for a checkpoint ID:
// refs/entire/checkpoints/<shard>/<id>, where <shard> is id.ShardFor() (the
// first two chars for legacy hex IDs, the last two for ULIDs). The full ID is
// always the leaf, so the ref round-trips through ParseRef.
func RefName(cid id.CheckpointID) plumbing.ReferenceName {
    return plumbing.ReferenceName(CheckpointRefPrefix + cid.ShardFor() + "/" + cid.String())
}

// ParseRef extracts the checkpoint ID from a per-checkpoint ref name,
// reporting whether name is a well-formed checkpoint ref. A ref is well-formed
// when it has the CheckpointRefPrefix, exactly a <shard>/<id> tail, and the
// shard matches the ID's own ShardFor — so refs the resolver did not write
// (mismatched shard, extra path segments) are rejected rather than silently
// resolved to the wrong bucket. It does not require the ID to be a recognized
// kind, so a future ID format still parses as long as it shards consistently.
func ParseRef(name plumbing.ReferenceName) (id.CheckpointID, bool) {
    s := name.String()
    tail, ok := strings.CutPrefix(s, CheckpointRefPrefix)
    if !ok {
        return id.EmptyCheckpointID, false
    }
    shard, rest, ok := strings.Cut(tail, "/")
    if !ok || shard == "" || rest == "" {
        return id.EmptyCheckpointID, false
    }
    // Reject extra path segments: the tail must be exactly <shard>/<id>.
    if strings.Contains(rest, "/") {
        return id.EmptyCheckpointID, false
    }
    cid := id.CheckpointID(rest)
    if cid.ShardFor() != shard {
        return id.EmptyCheckpointID, false
    }
    return cid, true
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

package checkpoint

import (
    "strings"

"github.com/go-git/go-git/v6/plumbing"

"github.com/entireio/cli/cmd/entire/cli/checkpoint/id"
)

func TestRefName(t *testing.T) {
    t.Parallel()

tests := []struct {
        name string
        cid  id.CheckpointID
        want plumbing.ReferenceName
    }{
        {
            name: "legacy hex shards on first two",
            cid:  "a1b2c3d4e5f6",
            want: "refs/entire/checkpoints/a1/a1b2c3d4e5f6",
        },
        {
            name: "ulid shards on last two",
            cid:  "01KVBJCWYA4YW6J5M9GP655HZN",
            want: "refs/entire/checkpoints/ZN/01KVBJCWYA4YW6J5M9GP655HZN",
        },
    }

for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            t.Parallel()
            assert.Equal(t, tt.want, RefName(tt.cid))
        })
    }
}

func TestParseRef(t *testing.T) {
    t.Parallel()

tests := []struct {
        name   string
        ref    plumbing.ReferenceName
        wantID id.CheckpointID
        wantOK bool
    }{
        {
            name:   "legacy round-trip",
            ref:    "refs/entire/checkpoints/a1/a1b2c3d4e5f6",
            wantID: "a1b2c3d4e5f6",
            wantOK: true,
        },
        {
            name:   "ulid round-trip",
            ref:    "refs/entire/checkpoints/ZN/01KVBJCWYA4YW6J5M9GP655HZN",
            wantID: "01KVBJCWYA4YW6J5M9GP655HZN",
            wantOK: true,
        },
        {
            name:   "wrong prefix",
            ref:    "refs/heads/entire/checkpoints/v1",
            wantOK: false,
        },
        {
            name:   "shard does not match id (legacy in last-two bucket)",
            ref:    "refs/entire/checkpoints/f6/a1b2c3d4e5f6",
            wantOK: false,
        },
    }

for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            t.Parallel()
            gotID, gotOK := ParseRef(tt.ref)
            assert.Equal(t, tt.wantOK, gotOK)
            if tt.wantOK {
                assert.Equal(t, tt.wantID, gotID)
                // Round-trip: building the ref from the parsed ID reproduces it.
                assert.Equal(t, tt.ref, RefName(gotID))
            } else {
                assert.Equal(t, id.EmptyCheckpointID, gotID)
            }
        })
    }
}