add checkpoint policy model · Entire

add checkpoint policy model

7a9f373· pfleidi·3w ago·4 files·+273 added/-0 removed

Define checkpoint format parsing and policy validation for the repo-wide checkpoint policy ref.

Sessions

1d8503f2a450View transcript

[?
Implement Checkpoint Policy Management SystemCodex·GPT-5.5·17 steps](/content/gh/entireio/cli/session/019ef111-70d5-7203-b653-e4834b8b92c0#timeline-1d8503f2a450/index.html)

Changes

4

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
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

package checkpointpolicy

import (
    "fmt"
    "strconv"
    "strings"
)

type CheckpointFamily string

const (
    CheckpointFamilyBranch CheckpointFamily = "branch"
    CheckpointFamilyRefs   CheckpointFamily = "refs"
)

type CheckpointFormat struct {
    Family CheckpointFamily
    Major  int
}

func ParseFormat(raw string) (CheckpointFormat, error) {
    familyRaw, majorRaw, ok := strings.Cut(raw, "-v")
    if !ok || familyRaw == "" || majorRaw == "" {
        return CheckpointFormat{}, fmt.Errorf("invalid checkpoint format %q", raw)
    }

family := CheckpointFamily(familyRaw)
    if _, ok := familyRanks[family]; !ok {
        return CheckpointFormat{}, fmt.Errorf("unknown checkpoint family %q", familyRaw)
    }

major, err := strconv.Atoi(majorRaw)
    if err != nil || major <= 0 {
        return CheckpointFormat{}, fmt.Errorf("invalid checkpoint major %q", majorRaw)
    }

return CheckpointFormat{Family: family, Major: major}, nil
}

func (f CheckpointFormat) String() string {
    if f.Family == "" || f.Major == 0 {
        return ""
    }
    return fmt.Sprintf("%s-v%d", f.Family, f.Major)
}

func Compare(a, b CheckpointFormat) int {
    aRank := familyRanks[a.Family]
    bRank := familyRanks[b.Family]
    if aRank != bRank {
        return compareInt(aRank, bRank)
    }
    return compareInt(a.Major, b.Major)
}

func KnowsFormat(format CheckpointFormat) bool {
    _, ok := knownFormats[format]
    return ok
}

func CanRead(format CheckpointFormat) bool {
    return readFormats[format]
}

func CanWrite(format CheckpointFormat) bool {
    return writeFormats[format]
}

func compareInt(a, b int) int {
    switch {
    case a < b:
        return -1
    case a > b:
        return 1
    default:
        return 0
    }
}

var familyRanks = map[CheckpointFamily]int{
    CheckpointFamilyBranch: 0,
    CheckpointFamilyRefs:   1,
}

var (
    branchV1Format = CheckpointFormat{Family: CheckpointFamilyBranch, Major: 1}
    refsV1Format   = CheckpointFormat{Family: CheckpointFamilyRefs, Major: 1}

knownFormats = map[CheckpointFormat]struct{}{
        branchV1Format: {},
        refsV1Format:   {},
    }

readFormats = map[CheckpointFormat]bool{
        branchV1Format: true,
    }

writeFormats = map[CheckpointFormat]bool{
        branchV1Format: true,
    }
)

Acmd/entire/cli/checkpointpolicy/format.go+101

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
52
53
54
55
56
57
58

package checkpointpolicy_test

import (
    "testing"

"github.com/entireio/cli/cmd/entire/cli/checkpoint"
    "github.com/entireio/cli/cmd/entire/cli/checkpointpolicy"
    "github.com/stretchr/testify/require"
)

func TestParseFormat(t *testing.T) {
    t.Parallel()
    tests := []struct {
        name    string
        input   string
        want    checkpointpolicy.CheckpointFormat
        wantErr string
    }{
        {name: "branch v1", input: "branch-v1", want: checkpointpolicy.CheckpointFormat{Family: checkpointpolicy.CheckpointFamilyBranch, Major: 1}},
        {name: "refs v2", input: "refs-v2", want: checkpointpolicy.CheckpointFormat{Family: checkpointpolicy.CheckpointFamilyRefs, Major: 2}},
        {name: "unknown family", input: "unknown-v1", wantErr: "unknown checkpoint family"},
        {name: "missing v", input: "branch-1", wantErr: "invalid checkpoint format"},
        {name: "zero major", input: "branch-v0", wantErr: "invalid checkpoint major"},
        {name: "non numeric major", input: "branch-vx", wantErr: "invalid checkpoint major"},
    }
    for _, tt := range tests {
        tt := tt
        t.Run(tt.name, func(t *testing.T) {
            t.Parallel()
            got, err := checkpointpolicy.ParseFormat(tt.input)
            if tt.wantErr != "" {
                require.ErrorContains(t, err, tt.wantErr)
                return
            }
            require.NoError(t, err)
            require.Equal(t, tt.want, got)
            require.Equal(t, tt.input, got.String())
        })
    }
}

func TestSupportedFormats(t *testing.T) {
    t.Parallel()
    branchV1, err := checkpointpolicy.ParseFormat(checkpoint.CheckpointVersionBranchV1)
    require.NoError(t, err)
    refsV1, err := checkpointpolicy.ParseFormat("refs-v1")
    require.NoError(t, err)

require.True(t, checkpointpolicy.KnowsFormat(branchV1))
    require.True(t, checkpointpolicy.CanRead(branchV1))
    require.True(t, checkpointpolicy.CanWrite(branchV1))
    require.Equal(t, checkpoint.CheckpointVersionBranchV1, branchV1.String())

require.True(t, checkpointpolicy.KnowsFormat(refsV1))
    require.False(t, checkpointpolicy.CanRead(refsV1))
    require.False(t, checkpointpolicy.CanWrite(refsV1))
    require.Less(t, checkpointpolicy.Compare(branchV1, refsV1), 0)
}

Acmd/entire/cli/checkpointpolicy/format_test.go+58

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

package checkpointpolicy

import (
    "fmt"

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

type Policy struct {
    CheckpointVersion    string `json:"checkpoint_version"`
    CheckpointMinVersion string `json:"checkpoint_min_version"`
}

func DefaultPolicy() Policy {
    return Policy{
        CheckpointVersion:    checkpoint.CheckpointVersionBranchV1,
        CheckpointMinVersion: checkpoint.CheckpointVersionBranchV1,
    }
}

func Normalize(policy Policy) Policy {
    if policy.CheckpointVersion == "" {
        policy.CheckpointVersion = checkpoint.CheckpointVersionBranchV1
    }
    if policy.CheckpointMinVersion == "" {
        policy.CheckpointMinVersion = checkpoint.CheckpointVersionBranchV1
    }
    return policy
}

func ValidatePolicy(policy Policy) error {
    policy = Normalize(policy)

version, err := ParseFormat(policy.CheckpointVersion)
    if err != nil {
        return fmt.Errorf("checkpoint_version: %w", err)
    }
    if !CanWrite(version) {
        return fmt.Errorf("checkpoint_version %q is not write-supported by this Entire CLI", policy.CheckpointVersion)
    }

minVersion, err := ParseFormat(policy.CheckpointMinVersion)
    if err != nil {
        return fmt.Errorf("checkpoint_min_version: %w", err)
    }
    if !CanRead(minVersion) {
        return fmt.Errorf("checkpoint_min_version %q is not read-supported by this Entire CLI", policy.CheckpointMinVersion)
    }
    if Compare(minVersion, version) > 0 {
        return fmt.Errorf("checkpoint_min_version %q is newer than checkpoint_version %q", policy.CheckpointMinVersion, policy.CheckpointVersion)
    }

return nil
}

func RequiresUpgrade(policy Policy) bool {
    policy = Normalize(policy)
    minVersion, err := ParseFormat(policy.CheckpointMinVersion)
    if err != nil {
        return true
    }
    return !CanRead(minVersion)
}

func UnsupportedWrite(policy Policy) bool {
    policy = Normalize(policy)
    version, err := ParseFormat(policy.CheckpointVersion)
    if err != nil {
        return true
    }
    return !CanWrite(version)
}
}

Acmd/entire/cli/checkpointpolicy/policy.go+72

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

package checkpointpolicy_test

import (
    "testing"

"github.com/entireio/cli/cmd/entire/cli/checkpoint"
    "github.com/entireio/cli/cmd/entire/cli/checkpointpolicy"
    "github.com/stretchr/testify/require"
)

func TestDefaultPolicy(t *testing.T) {
    t.Parallel()
    got := checkpointpolicy.DefaultPolicy()
    require.Equal(t, checkpoint.CheckpointVersionBranchV1, got.CheckpointVersion)
    require.Equal(t, checkpoint.CheckpointVersionBranchV1, got.CheckpointMinVersion)
}

func TestValidatePolicy(t *testing.T) {
    t.Parallel()
    tests := []struct {
        name    string
        policy  checkpointpolicy.Policy
        wantErr string
    }{
        {name: "default", policy: checkpointpolicy.DefaultPolicy()},
        {name: "unknown current", policy: checkpointpolicy.Policy{CheckpointVersion: "future-v1", CheckpointMinVersion: "branch-v1"}, wantErr: "unknown checkpoint family"},
        {name: "unsupported current", policy: checkpointpolicy.Policy{CheckpointVersion: "refs-v1", CheckpointMinVersion: "branch-v1"}, wantErr: "not write-supported"},
        {name: "unsupported minimum", policy: checkpointpolicy.Policy{CheckpointVersion: "branch-v1", CheckpointMinVersion: "refs-v1"}, wantErr: "not read-supported"},
    }
    for _, tt := range tests {
        tt := tt
        t.Run(tt.name, func(t *testing.T) {
            t.Parallel()
            err := checkpointpolicy.ValidatePolicy(tt.policy)
            if tt.wantErr == "" {
                require.NoError(t, err)
                return
            }
            require.ErrorContains(t, err, tt.wantErr)
        })
    }
}